Skip to content

아키텍처 정본과 실제 소스로 문서 drift를 검증한다 - #780

Merged
developer-1px merged 3 commits into
feat/777-documentation-architecturefrom
feat/779-architecture-drift
Sep 13, 2026
Merged

아키텍처 정본과 실제 소스로 문서 drift를 검증한다#780
developer-1px merged 3 commits into
feat/777-documentation-architecturefrom
feat/779-architecture-drift

Conversation

@developer-1px

Copy link
Copy Markdown
Owner

사이트와 Architecture가 같은 라우트 등록을 읽어도 실제 저장소와 맞는다는 보장은 없었습니다. 책임·위치·공개 source를 저장소의 아키텍처 등록으로 옮기고, 사이트 등록 및 제품 소비 근거를 실제 파일·exports·import 경로와 대조합니다.

  • architecture/modules.json이 35개 패키지의 책임·위치·진입점·API 문서 위치를 소유합니다. 사이트 메뉴·Architecture·Source의 API 링크·API 생성기가 이를 소비하며, 사이트의 중복 책임 정의를 거절합니다.
  • 생성 API 본문 35개를 packages/*/docs/api-reference.md로 이동했습니다. 기존 공개 URL과 Usage 탐색을 유지하고 소유 문서와 생성기를 연결합니다. 변경 파일 다수는 문서 이동입니다.
  • check:architecture가 workspace 분모·package 이름·types export에 대응하는 실제 source·API 소유 위치를 검증합니다. 3개 Application의 대표 연결 17개는 해당 route에서 출발하는 정적 import 경로로 대조합니다. --evidence로 경로를 출력합니다.
  • 소스 표시용 ?raw·?url은 소비 근거에서 제외합니다. 다른 제품 route를 근거로 등록하거나 비공개 subpath를 참조하면 실패합니다.
  • 배포 검사에서 드러난 Source의 app 역참조와 카탈로그 중간 라우트를 제거했습니다. Applications를 명시된 Host 위치로 인정하면서 shared의 역참조 금지를 유지·확장합니다.

검증:

  • 관련 사이트 단위 테스트 161개 통과(문서·등록 155, app shell 5, Markdown Source 1).
  • drift 회귀 5개, API 등록 3개, route 등록 4개 통과. npm run docs:evaluate에서 API 35개·공개 export 1,249개와 문서 링크를 확인했습니다.
  • 정본 모듈 가드, 사이트 타입 검사, 사이트 production 빌드·산출물 검사, pre-push 패키지 빌드 통과. 기존 chunk 크기 경고는 유지됩니다.
  • Chrome 탐색 시나리오 6개 통과(설정 제외, 대상 재검증 포함): Architecture → API → Usage → Source, 카탈로그, 후보 상태, 프로토콜/협업 API 링크, 모바일 가로 넘침.

정적 import 그래프에는 type import와 barrel re-export가 포함됩니다. 실제 runtime 호출, 전체 제품 의존성, 책임 분류의 의미적 정당성을 증명하지 않습니다. Editing·Rich Text 혼합 책임과 미완료 Hands/Profile·Artifact는 별도 소유권·동작 감사 대상으로 남기고 architecture/README.md에 조사 결과와 한계를 기록했습니다.

#778 위의 후속 PR입니다. base는 feat/777-documentation-architecture입니다.

Closes #779

사이트맵을 모듈·제품과 설계 현황으로 재편한다
@developer-1px
developer-1px merged commit 738fd43 into feat/777-documentation-architecture Sep 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant