문제 create:feature는 "모든 merge 게이트를 통과하는 가장 작은 기능"을 만든다고 적고, test:feature-scaffold(FE-GATE-020)가 그 주장을 지키는 유일한 드릴이다. 그런데 드릴은 손으로 적은 15개 명령만 돌았고 merge 단계는 명령 참조가 88개다. 그 범위 밖(시각 회귀, a11y, 번들, 계약·스키마·시나리오 테스트 등)에서 생성 기능을 깨는 템플릿 변경이 생겨도 FE-GATE-020은 통과했다(12-01·12-03이 실제로 그렇게 생겼다). 또 제품 기능 제거 드릴 (test:sample-removal -- --feature=<id>)은 어떤 게이트도 돌지 않아, 빈 사유 결함(16-02)이 드러나지 않았다. 고른 방법 - 새 scripts/lib/feature-scaffold-drill.ts가 fixture의 config/ci/gates.json merge 단계를 단계 순서대로, 명령마다 한 번 뽑는다. 음성 fixture 명령은 run-ci-gate.ts처럼 등록된 종료 코드와 진단 ID로 판정한다. - 돌지 않는 명령은 SCAFFOLD_DRILL_EXCLUDED_SCRIPTS에 이유와 함께 둔다: 브라우저 명령 7개(FE-GATE-020 job에 브라우저가 없다. merge_gate matrix browser: false), test:system(bubblewrap·systemd·cgroup 필요, 기능과 무관한 provider 샌드박스 검사), verify:lockfile(연결한 node_modules에 install한다), 제거 드릴 5개(저장소를 다시 복사한다. 이 드릴 자신 포함). merge 단계에 없는 스크립트를 제외 목록에 두면 실패한다. - 생성 기능을 merge 명령 뒤에 test:sample-removal -- --feature=scaffold-feature로 다시 지운다(16-02 둘째 절반). - 생성 명령의 주석·Next 출력과 매뉴얼 두 곳의 주장을 실제 범위로 고쳤다. - 버린 대안: 손 목록에 빠진 명령 더하기. 다음 merge 명령이 다시 빠진다. 복사본 에서 브라우저 게이트까지 전부(리뷰 5.1 (d)). 드릴 job에 브라우저가 없고 수십 분이 든다. 생성 경로만 도는 chromium a11y·시각 1회(5.1 (c)). 12-01·12-03을 고치는 다른 작업이 진행 중이라 지금 넣으면 그 수정 전까지 드릴이 실패한다. 그 둘이 들어오면 제외 목록에서 빼는 것을 다시 본다. 위험·한계 - 드릴 시간이 크게 는다(빌드·release candidate·coverage·제거 드릴 한 번). FE-GATE-020 job(45분)의 임계 경로를 넘으면 리뷰 5.1 재검토 조건대로 줄인다. tests/unit이 한 merge에서 도는 횟수(1101/10-06)도 는다. - 이 커밋 메시지에는 드릴 전체 실행 결과를 적지 않았다(공유 잠금 대기). 검증 - RED: 새 tests/unit/feature-scaffold-drill.test.ts의 "is what test:feature-scaffold runs"가 수정 전 실패. - 수정 뒤 feature-scaffold-drill 5건(merge 명령 전부가 실행 또는 제외, 음성 fixture 기대 유지, merge 단계에 명령을 더하면 드릴이 돈다, 낡은 제외 거부, 드릴이 이 목록을 씀), create-feature, removal-fixture 합계 43건 통과. verify:documentation PASS_SCOPED, check:types 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-02 Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-02
141 lines
7.4 KiB
Markdown
141 lines
7.4 KiB
Markdown
# create:feature 참조
|
|
|
|
모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만드는 명령이다. 정본은 `scripts/create-feature.ts`다.
|
|
`test:feature-scaffold`가 생성한 기능으로 `config/ci/gates.json`의 merge 단계 명령을 돌려 확인한다. 브라우저 게이트(FE-GATE-008·009의 브라우저 명령)와 `test:system`은 빼고 돈다. 뺀 명령과 이유는 `scripts/lib/feature-scaffold-drill.ts`에 있다.
|
|
템플릿 문자열이 그 파일 안에 있고, 참조 기능을 import하지 않는다. 그래서 참조 기능을 지운 프로젝트에서도 동작한다.
|
|
|
|
## 사용법
|
|
|
|
```bash
|
|
corepack pnpm create:feature <id> [--context <context id>] [--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>]
|
|
```
|
|
|
|
| 인자 | 규칙 |
|
|
|---|---|
|
|
| `<id>` | 케밥 표기, 40자 이하. 기존 기능·context ID와 겹치면 거부 |
|
|
| `--context` | 기존 context ID. 없으면 `<base>-context`를 새로 만든다 |
|
|
| `--package` | `@scope/name@<정확한 버전>`. `--digest`, `--revision`과 함께만 |
|
|
| `--digest` | `sha256:` + 소문자 hex 64자리 |
|
|
| `--revision` | 소스 리비전. 소문자 hex 7~64자리 |
|
|
|
|
- `<base>`: ID에서 끝의 `-feature`를 뗀 것이다. `invoice-feature`면 `invoice`. 모든 전역 ID의 접두어가 된다.
|
|
- 패키지 인자가 없으면 자리표시자 신원을 쓰고 표준 오류로 경고한다.
|
|
- 패키지 인자가 있으면 계약 조립기와 같은 신원 검사(`composeContractContributions`)로 형식을 확인한다.
|
|
|
|
## 하는 일
|
|
|
|
```text
|
|
인자 파싱 (틀리면 사용법 출력, 종료 코드 2)
|
|
→ 생성기로 선언을 읽고, 설치된 라우트·topic·문구 키를 읽는다
|
|
→ 계획: ID 검사, 충돌 검사, topic 생성, navigationOrder 계산
|
|
→ 쓰기: 쓸 경로와 기능 폴더가 하나라도 있으면 아무것도 쓰지 않고 거부
|
|
→ 생성기 실행: 거부하면 만든 파일을 모두 지운다
|
|
→ 출력: 만든 파일, 다음 할 일 (종료 코드 0)
|
|
```
|
|
|
|
실패하면 `create:feature: <메시지>`를 표준 오류에 쓰고 종료 코드 1로 끝난다. 메시지는 [errors.md](errors.md#생성-명령-createfeature)에 있다.
|
|
|
|
## 만드는 파일
|
|
|
|
기능 폴더 `src/features/<id>/`:
|
|
|
|
- `feature-module.ts`: 선언 헤더(`FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`)와 `FEATURE_MODULE`
|
|
- `feature-runtime.ts`: 실행 쪽. `feature-module.ts`가 동적으로만 import한다
|
|
- `context-routes.ts`: context가 적재하는 라우트
|
|
- `contracts/<base>-feature-contract.ts`: 라우트, 무효화, 계약 패키지 신원
|
|
- `contracts/<base>-schemas.ts`: zod 스키마와 `zodValidator` 검증기
|
|
- `contracts/<base>-mapper.ts`: 와이어 값 → 화면 값
|
|
- `contracts/<base>-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행)
|
|
- `contracts/<base>-contract-contribution.ts`: HTTP descriptor와 계약 기여. FE-REG-API 행은 여기서 뽑는다
|
|
- `contracts/<base>-message-catalog.ts`: ko-KR·en-US 문구
|
|
- `application/<base>-feature-api.ts`: input, gateway port, `ApplicationFeatureInputs` 보강
|
|
- `adapters/<base>-http-gateway.ts`: HTTP gateway
|
|
- `adapters/create-<base>-feature-input.ts`: 조립 기여(`needs: ["http", "telemetry"]`)
|
|
- `presentation/<base>-feature-runtime.ts`: 지연 로드 페이지 표
|
|
- `presentation/<base>-routes.ts`: route ID → URL 함수(`buildRouteUrl`)
|
|
- `presentation/use-<base>-items.ts`: 쿼리 바인딩
|
|
- `presentation/<base>-list-page.tsx`: `CollectionPage` 목록 페이지
|
|
|
|
`domain/`은 만들지 않는다. 업무 규칙이 생기면 사람이 만든다.
|
|
|
|
기능 테스트 폴더 `tests/features/<id>/`:
|
|
|
|
- `<base>-feature-input.test.ts`: input과 mapper 단위 테스트
|
|
- `<base>-list-page.test.tsx`: 라우터를 거치는 페이지 테스트(목록, 빈 목록, 실패 후 다시 시도)
|
|
|
|
기능 폴더 밖:
|
|
|
|
- `src/contexts/<base>-context/context-module.ts`: 새 context일 때만
|
|
- `artifacts/tests/a11y-manual/<ROUTE_ID>.md`: pending 기록
|
|
|
|
## 뼈대 모양
|
|
|
|
- 라우트 1개: 파라미터·검색값 없는 목록, `session-required`, `feature-boundary`.
|
|
- GET 1개: `SAFE`, `EXTERNAL_BEARER`, 응답은 항목 배열.
|
|
- 쿼리 1개: `LIST_STANDARD` profile.
|
|
- 무효화 topic 1개, namespace 1개, edge 1개.
|
|
- 빈 배열 응답은 공유 빈 상태 화면으로 그린다. `tests/e2e/accessibility.spec.ts`가 모든 API에 `[]`를 답하기 때문이다.
|
|
|
|
한도·마감 같은 숫자는 `scripts/create-feature.ts`의 템플릿이 정본이다.
|
|
|
|
생성된 문구는 자리 채움이다. ko-KR 설명 문구가 "제품 문구로 바꾸세요"라고 적혀 있다. 제품 문구로 바꾼다.
|
|
|
|
## 하지 않는 일
|
|
|
|
- 레지스트리 기준선, governance, 중앙 카탈로그를 고치지 않는다. 고칠 필요가 없다.
|
|
- `README.md`나 문서를 고치지 않는다.
|
|
- `tests/mocks/` 공유 파일을 고치지 않는다.
|
|
- `package.json`, `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`를 고치지 않는다.
|
|
- a11y 기록에 서명하지 않는다.
|
|
- 실제 계약 패키지를 설치하지 않는다.
|
|
|
|
## 출력
|
|
|
|
표준 출력:
|
|
|
|
```text
|
|
create:feature: <id> in <context> (new context), route <ROUTE_ID> at <path>
|
|
created <파일> ...
|
|
|
|
Next:
|
|
1. Before a release, have a person review and sign artifacts/tests/a11y-manual/<ROUTE_ID>.md (FE-GATE-028). ...
|
|
2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage ...
|
|
The feature's own tests: node scripts/run-vitest.ts run tests/features/<id> ...
|
|
The registry baseline does not change: ...
|
|
```
|
|
|
|
패키지 인자가 없을 때 표준 오류:
|
|
|
|
```text
|
|
create:feature warning: no --package was given, so src/features/<id>/contracts/<base>-feature-contract.ts pins the placeholder contract identity. ...
|
|
```
|
|
|
|
이 경고가 나오면 [03 문서의 "자리표시자 계약 신원 교체"](../03-outside-feature-folder.md#자리표시자-계약-신원-교체)를 릴리스 전에 한다.
|
|
|
|
## 되돌리기
|
|
|
|
생성한 기능을 지우려면 만든 것을 지우고 생성기를 다시 돌린다.
|
|
|
|
```bash
|
|
rm -r src/features/<id> tests/features/<id> artifacts/tests/a11y-manual/<ROUTE_ID>.md
|
|
rm -r src/contexts/<base>-context # 새 context를 만들었을 때만
|
|
corepack pnpm generate:feature-index
|
|
```
|
|
|
|
## 이 명령을 지키는 검사
|
|
|
|
- `tests/unit/create-feature.test.ts` (`test:unit`, FE-GATE-005)
|
|
- 렌더 결과만 본다. 저장소를 건드리지 않는다.
|
|
- 접두어, 참조 기능 이름이 없음, topic 형식과 충돌, `navigationOrder`, 거부 조건, 덮어쓰기 거부와 되돌리기.
|
|
- `test:feature-scaffold` (FE-GATE-020)
|
|
- 저장소 복사본에 기능 하나를 만들고 커밋한 뒤 게이트를 돈다.
|
|
- 타입, lint, 아키텍처, 레지스트리, i18n, 디자인 시스템, 진단, 문서, unit, component, integration, 기능 테스트, 커버리지, CI 계약, 빌드.
|
|
- `test:sample-removal` (FE-GATE-020)
|
|
- 참조 기능을 지운 복사본에서 이 명령으로 기능을 만들고 같은 게이트를 다시 돈다. 명령이 참조 기능에 기대지 않는다는 증거다.
|
|
|
|
## 알려진 한계
|
|
|
|
- `--context reference-context`로 참조 context에 넣으면 참조 기능 테스트 tests/features/reference-feature/installed-context-routing.test.ts가 깨진다. 그 테스트는 참조 context의 라우트 수를 정확히 비교한다.
|
|
- 드릴은 `check:bundle`(FE-GATE-012), 브라우저 테스트(`test:a11y`, `test:e2e`)를 돌리지 않는다.
|
|
- 새 context는 앱이 하나일 때만 만든다. 앱이 여럿이면 `--context`로 기존 context를 고른다.
|