test(layout): 저장소 배치 규칙 R3~R9를 검사로 두고 매뉴얼에 적는다

소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.

고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
  목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
  포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
  gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
  목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
  샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
  `kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
  보지 않는다. 산출물 `documentation-review.json`에
  `layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
  nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
  추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
  `check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
  기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
  「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.

위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.

검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.

Refs: design-docs repo-structure/04-frontend-layout.md 11절, README.md 3.4절
This commit is contained in:
2026-11-08 17:41:27 +09:00
parent 79dc945a67
commit e902e657d1
5 changed files with 305 additions and 4 deletions
+46
View File
@@ -184,6 +184,28 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
- 템플릿이 아직 연결하지 않은 것: 활성화 화면(`onUpdateWaiting`·`requestActivation()`). 확인할 것 목록은 `docs/architecture/optional-adapter-recipes.md`의 "Service Worker를 켤 때 확인할 것"에 있다.
- realtime·Web Worker·오프라인 명령을 고르면 조립이 `Selected optional capabilities have no runtime to start them`로 거절한다. 템플릿 조립에 아직 그 런타임이 없다.
### Web Worker를 들일 때 tsconfig 더하기
템플릿에는 Web Worker 코드가 없다. 그래서 Worker용 tsconfig도 없다. 빈 tsconfig는 0파일을 검사하고 통과한다(아래 E절 R8). 2026-11-08에 지웠다. Worker 코드를 처음 넣는 변경에서 아래를 함께 한다.
1. Worker 코드를 `src/adapters/web-worker/`에 둔다. 그 폴더의 `index.ts`가 배럴이다.
2. 루트에 `tsconfig.web-worker.json`을 만든다. lib가 `WebWorker`이고 DOM이 없어서, Worker 코드가 `document`·`window`를 쓰면 실패한다. `tsconfig.service-worker.json`과 같은 이유다.
```json
{
"extends": "./tsconfig.base.json",
"compilerOptions": { "lib": ["ES2022", "WebWorker"], "types": [], "skipLibCheck": false },
"include": ["src/adapters/web-worker"],
"exclude": ["src/adapters/web-worker/index.ts"]
}
```
3. Worker 진입 파일을 `tsconfig.app.json`의 `exclude`에 더한다. 배럴처럼 페이지가 import하는 파일은 app 프로그램에 남긴다.
4. `tsconfig.json`의 `references`에 `{ "path": "./tsconfig.web-worker.json" }`을 더한다. 편집기가 Worker 파일에 이 설정을 쓴다.
5. `package.json`에 `"check:types:web-worker": "tsc --project tsconfig.web-worker.json"`을 더하고 `check:types` 사슬에 잇는다. 사슬 끝의 `node scripts/check-typecheck-inputs.ts`가 이 tsconfig의 입력이 0개면 실패시킨다.
6. `config/repository-layout.json`에 `tsconfig.web-worker.json` 항목을 더한다(E절 R1). `sets`는 `tsconfig.service-worker.json`과 같게 `fixture-copy`·`secret-scan`이다. `config/security/secret-scan-policy.json`의 `trackedRoots`에도 같은 이름을 더한다(R2).
7. `scripts/verify-documentation-readiness.ts`의 `NOT_CREATED`에서 `src/adapters/web-worker`를 뺀다.
---
## D. 고치지 않는다
@@ -199,6 +221,30 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
---
## E. 저장소 배치 규칙 (R1~R10)
기능 밖의 루트 폴더·설정·검사를 더하거나 옮길 때 지킨다. 2026-11-07 소유자 지적(샘플이 남아 있음, 역할이 겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)이 다시 나오지 않게 하는 규칙이다. 설계와 근거는 design-docs `repo-structure/04-frontend-layout.md` 11절이다.
| ID | 규칙 | 검사 |
| --- | --- | --- |
| R1 | 루트 항목은 모두 `config/repository-layout.json`에 있다. 항목마다 종류(source·tool-convention·gate-input·document·history·output), 역할, 읽는 곳을 적는다 | `tests/unit/repository-layout.test.ts`(FE-GATE-005). 등록부에 없는 루트 항목이 추적되면 실패 |
| R2 | 루트 경로 목록은 등록부의 이름 붙은 집합(`sets`, 하위 경로는 `setPaths`)에서만 고른다. 목록을 코드에 새로 적지 않는다. JSON 정책 파일(`config/security/secret-scan-policy.json`)은 그 집합의 사본을 갖고 시험이 같은지 본다 | 같은 시험. 목록을 쓰던 곳이 `scripts/lib/repository-layout.ts`를 import하는지, 루트 이름 두 개 이상의 문자열 배열이 없는지 |
| R3 | 추적 파일은 읽는 곳이 있다. `artifacts/`는 출력 전용이라 `.gitkeep`만 추적한다. 사람이 쓴 기록은 `docs/` 아래에 둔다(수동 a11y 기록은 `docs/accessibility/route-reviews/`) | `tests/unit/tracked-artifacts.test.ts`(FE-GATE-005). `config/` 아래 고아 JSON은 리뷰가 본다 |
| R4 | 템플릿이나 제품이 넣은 샘플 기능은 `scripts/lib/removable-template-features.ts` 목록에 있고, 복사본에서 지우고 빌드·시험하는 drill로 증명한다. 문서 검사만으로는 안 된다 | `tests/unit/example-feature-rules.test.ts`(FE-GATE-005). FE-GATE-020이 `test:sample-removal`을 목록 전체로 도는지 |
| R5 | 게이트의 검사 대상(visual 골든, e2e 라우트, 게이트 증거 목록, 규모 측정)은 플랫폼 화면·시험 fixture·생성기 출력이다. 지울 샘플 기능이 아니다 | 같은 시험. 샘플의 기능 ID·라우트가 visual·e2e의 `goto`, `config/ci/gates.json` 산출물 경로, `config/scale/`에 나오면 실패 |
| R6 | 매뉴얼의 예제 위치는 `create:feature` 출력이나 매뉴얼 안 코드 조각을 가리킨다. 지울 샘플 기능의 경로를 가리키지 않는다 | `verify:documentation`(FE-GATE-017). `docs/manual/`에 목록 샘플의 경로가 나오면 실패 |
| R7 | 이 repo에 둘 수 있는 실행 환경 파일은 개발 의존 서비스용 compose와 개발 Dockerfile뿐이다. nginx·Kubernetes·Helm·Terraform 설정은 인프라 repo에 두고 링크한다. 호스트에 요구하는 것은 계약(`config/hosting/`)과 검사(FE-GATE-019)로 둔다 | 파일: `tests/unit/repository-layout.test.ts`(FE-GATE-005). 문서: `verify:documentation`(FE-GATE-017)이 현재 문서의 ```` ```nginx ````·```` ```hcl ```` 블록과 `kind: Deployment` 같은 매니페스트 줄을 막는다. 이력 폴더(`docs/history/`, `docs/reviews/`, `docs/superpowers/`)는 기록이라 보지 않는다 |
| R8 | 검사 대상이 0개인 게이트 명령은 실패하거나 SKIP을 출력한다. 통과로 보이면 안 된다 | FE-GATE-003: `scripts/check-typecheck-inputs.ts`(package script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상), `scripts/check-type-fixtures.ts`(fixture 0개면 실패) |
| R9 | tsconfig는 lib·types·모듈 해석 중 하나가 다를 때만 새로 만든다. 옵션이 같고 파일만 다르면 실행기 하나로 돈다(예: 음성 타입 fixture는 `check:types:fixtures` 하나) | `tests/unit/repository-layout.test.ts`(FE-GATE-005). 옵션이 같은 tsconfig 쌍이 있으면 실패 |
| R10 | 이력 문서(끝난 라운드의 계획·작업 목록·보고)는 루트나 숨김 폴더에 두지 않고 이력 폴더 한 곳에 둔다. 정본으로 쓰이는 부분은 이력에 두지 않는다 | 루트 `*.md`는 R1 등록부에 종류와 함께 있어야 한다. "정본으로 쓰이는가"는 리뷰가 본다 |
루트 항목을 더하거나 옮길 때의 순서:
1. `config/repository-layout.json`에 항목을 더하거나 고친다. 종류·역할·읽는 곳을 적는다(R1).
2. 그 항목이 들어갈 집합을 `sets`(항목 전체)나 `setPaths`(항목 안 경로)에 적는다. 집합의 뜻은 파일 머리의 `sets` 설명에 있다(R2).
3. `secret-scan` 집합을 바꿨으면 `config/security/secret-scan-policy.json`의 `trackedRoots`도 같게 고친다.
4. 새 tsconfig라면 R9를 먼저 본다. 다른 tsconfig와 옵션이 같으면 만들지 않는다.
## 기능을 지울 때
`corepack pnpm test:sample-removal -- --feature=<id>`는 복사본에서 지워 보고 게이트를 돈다. 실제 저장소에서 지울 때는 아래를 함께 지운다.