문제: 매뉴얼 1단계 예시 ID는 invoice-feature이고 11단계가 `test:sample-removal -- --feature=invoice-feature`로 그 기능을 지운다. 드릴은 제품 기능의 잔여를 src·tests 모든 파일에서 기능 ID의 대소문자 무시 부분 문자열로 찾았다. 템플릿 소유 tests/unit/create-feature.test.ts가 같은 예시 ID를 데이터로 51번 쓰므로, 다른 검사가 모두 통과해도 `fixture-id-residue: residue: tests/unit/create-feature.test.ts`로 rc=1이었다 (리뷰 16-R1). errors.md의 안내는 그 템플릿 파일을 고치라는 것이었다. notice-feature, orders-feature, shop-feature 같은 이름도 같은 충돌이 난다. 고른 방법: 제품 기능의 잔여 판정을 scripts/lib/feature-residue.ts의 productFeatureResidue로 옮기고 범위를 나눈다. - src: 지금처럼 경로나 내용에 기능 ID·폴더 이름이 있으면 잔여. 플랫폼 소스는 제품 기능을 이름으로 부르지 않으므로, 남은 이름은 타입 검사가 못 보는 참조(카탈로그 키, 런타임 오버라이드, 링크)다. - tests: 파일 이름에 기능 ID가 있거나, 기능의 src/features/<dir>/ 또는 tests/features/<dir>/에서 import(동적 import, vi.mock 포함)하는 파일만 잔여. 테스트 본문에 ID를 글자로 적은 것은 세지 않는다. 지운 기능에 기대는 테스트는 같은 드릴의 test:all이 잡는다. 참조 샘플(reference-feature)은 템플릿이 모든 파일을 가지므로 기존 넓은 패턴을 그대로 쓴다. 빌드 산출물(dist) 잔여 검사도 그대로다. 단위 테스트: 저장소 자체(create-feature.test.ts 포함)를 invoice-feature로 훑으면 잔여 0, src/contracts에 ID를 남긴 파일·이름에 ID가 있는 e2e spec·기능 폴더 import는 잔여, 테스트 본문의 예시 데이터는 잔여 아님. 매뉴얼 01 11단계와 errors.md의 판정 문장·안내(템플릿 파일이 나오면 고치지 말고 템플릿에 알린다)를 고쳤다. 버린 대안: - 제거 전에 한 번 훑어 이미 걸리던 파일을 제외: src/contracts에 남긴 잔여도 제거 전부터 ID를 담고 있으므로 같이 빠진다(완료 기준 둘째를 못 지킨다). - 템플릿 테스트의 예시 ID를 예약 접두어로 바꾸기: 부분 문자열 검색이면 접두어를 붙여도 걸리고, create-feature.test.ts의 파생 이름 기대값 수십 곳을 함께 바꿔야 한다. - 생성 명령이 템플릿 테스트에 나오는 ID를 거절: 목록이 따로 낡는다. 위험·한계: tests 안에서 기능 ID를 글자로만 담은 진짜 잔여(예: 기능을 import하지 않고 경로 문자열만 적은 테스트)는 이제 잔여로 나오지 않는다. 그런 테스트가 지운 기능에 기대면 test:all이 실패하고, 기대지 않으면 해가 없다. src 쪽 부분 문자열 검색은 그대로라 items 같은 짧은 ID는 플랫폼 소스의 글자에 여전히 걸릴 수 있다(이번 범위 밖). 실제 드릴 실행(198초)은 단위 테스트로 대신하지 못한다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts 16-R1과 같은 순서: create:feature invoice-feature --with-create --keyed 뒤 corepack pnpm test:sample-removal -- --feature=invoice-feature (rc=0 기대), 그리고 src/contracts/invoice-leftover.ts에 "invoice-feature"를 남긴 변이에서 rc=1(fixture-id-residue) 기대 Refs: 1105/16-04
19 KiB
19 KiB
실패 메시지와 고칠 파일
기능을 만들 때 흔히 보는 실패 메시지다. 메시지는 코드의 문자열을 그대로 옮겼다. <...>는 실제 값이 들어가는 자리다.
찾는 법: 메시지 앞부분으로 이 문서를 검색한다. 없으면 git grep '<메시지 앞부분>' -- src scripts로 코드를 찾는다. 코드가 정본이다.
메시지가 어느 단계에서 나오는지:
create:feature → 명령이 파일을 쓰기 전에 거부
generate:feature-index → 모든 빌드·검사 명령이 먼저 돌린다
조립·모듈 로드 → 테스트, 빌드, 앱 부팅 어디서든
check:registries → FE-GATE-010
lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
문서·접근성 → FE-GATE-017, FE-GATE-009, FE-GATE-028
릴리스 승인·공급망 → FE-GATE-027, FE-GATE-012
제거 드릴 → FE-GATE-020
<base>는 기능 ID에서 끝의 -feature를 뗀 것이다.
생성 명령 (create:feature)
모두 create:feature: 뒤에 나온다. 종료 코드는 1이다(인자 오류는 2).
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
feature id "<id>" must be kebab-case (lower-case words joined by single hyphens), at most 40 characters |
ID 형식 | 명령 인자 |
context id "<context>" must be kebab-case (lower-case words joined by single hyphens), at most 64 characters |
--context 형식 |
명령 인자 |
feature id <id> is already a feature or context |
같은 ID가 있다 | 다른 ID |
feature id <id> would prefix its ids with "<base>", which <other> already uses |
접두어가 기존 기능과 같다 | 다른 ID |
context <context> already exists; pass --context <context> to add the feature to it |
새로 만들 context가 이미 있다 | --context <context>를 준다 |
context id <context> is a feature id |
context ID가 기능 ID와 같다 | 다른 --context |
src/contexts has a <context> directory without a context declaration |
선언 없는 context 폴더 | src/contexts/<context>/context-module.ts를 만들거나 폴더를 지운다 |
another context already owns the route root <root>/* |
같은 라우트 루트를 다른 context가 가진다 | 다른 ID, 또는 그 context에 --context로 넣는다 |
a new context needs exactly one deployable app (declared: <apps>); pass --context <an existing context> |
앱이 여럿이라 새 context의 소속을 정할 수 없다 | --context |
route <ROUTE_ID> (<path>, <chunkId>) collides with installed route <ROUTE_ID> (<path>, <chunkId>) |
route ID·경로·chunk가 겹친다 | 다른 ID |
message keys already exist: <keys> |
문구 키가 겹친다 | 다른 ID |
generated topic <topic> is already installed; run the command again |
무작위 topic이 우연히 겹쳤다 | 명령을 다시 돌린다 |
contract package <packageId>@<version> is not a pinned identity: <reason> |
패키지 신원 형식. <reason> 예: <id>: package version must be exact SemVer, <id>: package digest, <id>: package sourceRevision, <id>: packageId |
--package, --digest, --revision |
--package, --digest and --revision go together. ... |
셋 중 일부만 줬다 | 셋을 함께 준다 |
--package must be @scope/name@<exact version>. ... |
버전 없는 패키지 이름 | @scope/name@1.2.3 꼴 |
--keyed needs --with-create. ... |
--keyed만 줬다 |
--with-create --keyed |
refusing to overwrite: <paths> |
쓸 파일이나 기능 폴더가 이미 있다 | 그 경로를 확인하고 지우거나 다른 ID |
the feature index generator rejected the feature, nothing was kept: |
생성기가 거부했다. 만든 파일은 모두 지웠다 | 뒤따르는 생성기 메시지(아래 절) |
생성기 (generate:feature-index)
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
Feature <id> belongs to undeclared context <context> |
context 선언이 없거나 FEATURE_CONTEXT_ID 오타 |
src/contexts/<context>/context-module.ts, 또는 src/features/<id>/feature-module.ts |
Context <context> belongs to undeclared app <app> |
CONTEXT_APP_ID 오타 |
src/contexts/<context>/context-module.ts |
<file> must export a literal <NAME> |
헤더를 상수 참조나 식으로 썼다. 생성기는 글자로 읽는다 | 그 파일. export const <NAME> = "<값>"; 꼴 |
<file> must export a positive integer <NAME> |
예산 값이 정수 리터럴이 아니다 | 그 파일 |
src/features/<dir> has no feature-module.ts; add one or mark the directory with NOT_A_FEATURE |
기능 폴더에 선언 파일이 없다 | feature-module.ts를 만들거나, 기능이 아닌 샘플 폴더면 NOT_A_FEATURE 파일을 둔다 |
src/features/<dir> has both feature-module.ts and NOT_A_FEATURE; … |
기능이 아니라고 표시한 폴더에 선언 파일이 있다 | 기능으로 설치하려면 NOT_A_FEATURE를 지운다. 설치하지 않으려면 feature-module.ts를 지운다 |
Duplicate generated feature ids: <id> |
두 폴더가 같은 FEATURE_MODULE_ID |
한쪽 feature-module.ts |
Duplicate context id: <id> |
두 폴더가 같은 CONTEXT_MODULE_ID |
한쪽 context-module.ts |
Context <context> feature cardinality <n> exceeds budget <max> |
context의 기능 수가 예산을 넘었다 | CONTEXT_MAX_FEATURES, 또는 새 context |
App <app> context cardinality <n> exceeds budget <max> |
앱의 context 수가 예산을 넘었다 | src/apps/<app>/app-module.ts의 APP_MAX_CONTEXTS |
조립·모듈 로드
테스트, 빌드, 앱 부팅 어디서든 나온다. 한 기능의 실수가 거의 모든 게이트를 같이 실패시킨다. 첫 메시지를 본다.
인증 프로필
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
<featureId>/<operationId>: unknown authProfileId <id> (계약 조립 오류의 reason) |
없는 인증 프로필 | contracts/<base>-contract-contribution.ts의 frontend.authProfileId. 제품 프로필이면 src/contracts/product-contracts.ts |
<featureId>/<operationId>: <METHOD> with cookie profile <id> must require x-csrf-token or x-xsrf-token (계약 조립 오류의 reason) |
쿠키 인증 프로필로 쓰기 요청을 보내는데 프로필이 CSRF 헤더를 요구하지 않는다 | src/contracts/product-contracts.ts의 그 프로필 requiredCredentialHeaders. 짝 백엔드는 x-xsrf-token |
Product REST auth profile <id> reuses a template profile id. |
제품 프로필 ID가 템플릿 것과 같다 | src/contracts/product-contracts.ts |
계약·스키마·mapper
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
부팅 화면 CONTRACT_SET_PACKAGE_MISSING / CONTRACT_SET_PACKAGE_UNEXPECTED(corepack pnpm dev, dev server를 쓰는 브라우저 테스트) |
dev manifest public/release-manifest.json의 계약 패키지가 설치된 기능과 다르다. 기능을 손으로 더하거나 지웠다 |
node scripts/write-dev-release-manifest.ts로 다시 쓰고 커밋한다. tests/unit/dev-release-manifest.test.ts가 같은 어긋남을 잡는다 |
Invalid or duplicate schema definition: <schemaId> |
스키마 ID 중복 또는 메타 형식 | contracts/<base>-schema-metadata.ts. 접두어를 붙인다 |
duplicate operation: <operationId> (계약 조립 오류의 reason) |
operation ID 중복 | contracts/<base>-contract-contribution.ts. 접두어를 붙인다 |
FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id> |
descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (responseSchema, problemSchema도 같은 꼴. 실패 본문 행은 boundary: "api-problem") |
contracts/<base>-schema-metadata.ts |
<schemaId>: row <boundary>, used as <boundary> (tests/unit/schema-metadata-policy.test.ts) |
스키마 메타 행의 boundary가 그 스키마가 쓰인 자리와 다르다. no FE-REG-SCHEMA row는 쓰이는데 행이 없다 |
contracts/<base>-schema-metadata.ts |
Unregistered route codec: <codecId> |
URL 함수가 기능 codec을 buildRouteUrl에 넘기지 않았다 |
presentation/<base>-routes.ts |
contract package <packageId> is declared, but no loaded contribution pins it |
계약 contractPackages에 적은 패키지를 계약 기여가 쓰지 않는다 |
contracts/<base>-contract-contribution.ts의 source |
<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages |
계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 <BASE>_CONTRACT_PACKAGE 하나를 쓰게 한다 |
contract package <packageId> is declared with conflicting identities |
두 기능이 같은 패키지를 다른 버전·digest로 선언했다 | 두 기능의 <BASE>_CONTRACT_PACKAGE를 맞춘다 |
계약 조립 실패의 메시지는 Installed contract contribution is not composable: <reason>이다. reason은 오류 객체(ContractContributionError)의 reason 속성에도 있다.
reason |
원인 | 고칠 곳 |
|---|---|---|
<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE |
참조 기능 전용 출처를 다른 기능이 썼다 | contracts/<base>-contract-contribution.ts의 source를 EXTERNAL_PACKAGE로 |
duplicate operation: <operationId> |
두 기여가 같은 operation ID | 접두어를 붙인다 |
duplicate contributionId: <id> |
두 기여가 같은 contributionId |
contracts/<base>-contract-contribution.ts |
<id>/<operationId>: unknown authProfileId <profile> |
V3 frontend.authProfileId가 없는 프로필 |
V3 frontend.authProfileId |
<id>/<operationId>: retry budget contradicts NEVER retry semantics |
NEVER인데 retryBudget가 0이 아니다 |
V3 frontend.retryBudget |
<id>/<operationId>: KEYED commands require a recovery descriptor |
KEYED인데 commandRecovery가 없다 |
V3 commandRecovery |
<id>/<operationId>: <GET·HEAD> is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값> |
읽기에 KEYED나 NEVER를 적었다 |
V3 retrySemantics. 재시도를 막으려면 frontend.retryBudget: 0 |
<id>/<operationId>: command operations require a command effect descriptor |
쓰기에 commandEffect가 없다 |
V3 commandEffect |
<id>/<operationId>: read operations carry no command descriptors |
GET에 commandEffect·commandRecovery를 적었다 |
둘 다 null |
<id>/<operationId>: responseEnvelope NONE, but <other> in the same contribution reads ENVELOPE_V1; ... |
한 계약 기여 안에서 operation 하나만 응답 모양이 다르다. 손으로 더한 operation에 responseEnvelope 줄을 빠뜨린 경우다 |
그 operation에 responseEnvelope: "ENVELOPE_V1" as const를 적는다. 정말 다른 백엔드면 기여를 나눈다 |
<id>: package version must be exact SemVer |
버전 범위(^1.2.0)나 형식 오류 |
<BASE>_CONTRACT_PACKAGE.version |
라우트·context
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
Duplicate route registry key: <ROUTE_ID> |
route ID 중복 | 계약 routes. 접두어를 붙인다 |
Duplicate route runtime contract key: <ROUTE_ID> |
routeRuntimeContracts 중복 |
계약 routeRuntimeContracts |
Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): the router would answer NOT_FOUND. |
라우트가 context 루트 밖 | 계약 routes.*.path, 또는 CONTEXT_ROUTE_PATH |
Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): context <other> (<root>) takes that URL. |
다른 context의 루트 아래 | 같은 곳 |
Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (<ids>). |
context-routes.ts의 handle이 계약에 없는 route ID |
src/features/<id>/context-routes.ts |
문구·서버 상태
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
Duplicate <locale> message key: <key> |
문구 키 중복 | contracts/<base>-message-catalog.ts. 접두어를 붙인다 |
Duplicate invalidation topic: <topic> |
topic 중복. 복사한 topic | 계약 invalidation. topic을 새로 만든다 |
Duplicate invalidation namespace: <key> |
namespace 중복 | defineQueryNamespaceIdentity 이름 |
Query invalidation topic is invalid. |
topic 형식이 qinv. + 26자가 아니다 |
defineQueryInvalidationTopic 값 |
Orphan invalidation topic: <topic> |
edge가 없는 topic | 계약 invalidation.edges |
Unregistered server-state profile: <profileId> |
없는 profile | 쿼리 바인딩의 profileId |
commandMutationIdentity: <operationId> is a GET; a mutation binds a write operation |
뮤테이션 정책에 읽기 descriptor를 넘겼다 | 정책의 commandMutationIdentity(...) 인자를 쓰기 descriptor로 |
조립 기여
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
feature <id> needs <capability>, which the host did not provide |
템플릿이 만들지 않는 capability | src/bootstrap/product-composition.ts의 capabilities, 또는 needs |
feature adapter contribution <id> installed an input for <other> |
기여의 featureId와 만든 input의 featureId가 다르다 |
adapters/create-<base>-feature-input.ts |
duplicate feature adapter contribution: <id> |
두 기여가 같은 기능 ID | 복사한 기여 파일 |
Feature <id> installed an input for <other> |
지연 로드한 기능이 다른 기능의 input을 냈다 | adapters/create-<base>-feature-input.ts |
레지스트리 (check:registries)
모두 Registry governance failed: 다음 줄에 나온다.
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
FE-REG-ROUTE.<ROUTE_ID> duplicates path=<path> from <ROUTE_ID> |
경로 중복 (chunkId=도 같은 꼴) |
계약 routes |
FE-REG-ROUTE.<ROUTE_ID>.loadingSurface value <value> does not match <pattern> |
로딩 화면 이름이 케밥 표기가 아니다 | 계약 routes.*.loadingSurface |
FE-REG-ROUTE.<ROUTE_ID>.<field> has unknown value <value> |
access·errorSurface가 정해진 값이 아니다 |
계약 routes |
FE-REG-ROUTE.<ROUTE_ID>.paramsSchema references unknown FE-REG-SCHEMA.schemaId=<id> |
라우트 스키마 ID를 기능이 등록하지 않았다 (searchSchema도 같은 꼴) |
계약 스키마 메타 |
FE-REG-API.<operationId> has no executable consumer for operationId=<operationId> |
계약의 operation을 기능 adapters/·application/에서 쓰지 않는다 |
쓰지 않으면 descriptor를 지운다 |
missing registry source <path>: <message> |
레지스트리 source를 읽다가 오류가 났다. 계약 조립 실패면 <message>가 Installed contract contribution is not composable: <reason>이고 <reason>이 위 reason 표의 값이다. 다른 오류가 reason 속성을 message와 따로 가지면 끝에 (reason: <reason>)이 붙는다. 읽지 못한 레지스트리는 removed 증거를 요구하지 않는다 |
<reason>이 가리키는 곳 |
breaking change missing evidence: <changeId> |
행을 빼거나 바꿨는데 승인이 없다 | update:registry-baseline 또는 config/contracts/registry-change-evidence.json |
stale breaking evidence <changeId>: no breaking change in the current diff has this changeId. ... |
지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 |
registry baseline approval digest mismatch: approved=<digest> actual=<digest> |
기준선 파일을 손으로 고쳤다 | update:registry-baseline으로 다시 찍는다 |
경계·lint·문구
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
check:architecture 출력의 규칙 이름 (feature-presentation-does-not-know-outbound-adapters 등) |
금지된 import | 규칙 뜻은 docs/architecture/layers.md의 "Rules" 표가 정본 |
Screen words come from the message catalog: use message(key) (0929/08-02). |
화면에 문자를 직접 썼다 | 문구 catalog에 키를 더하고 message(key) |
en-US catalog keys do not match ko-KR (I18n contract failed: 다음) |
두 locale의 키가 다르다 | contracts/<base>-message-catalog.ts |
en-US:<key> interpolation parameters do not match |
{name} 자리가 locale마다 다르다 |
같은 파일 |
문서·접근성
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
artifacts/tests/a11y-manual/ has no record for route IDs: <ids> (verify:documentation) |
라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 Route ID를 바꾼다 |
Manual accessibility record format is invalid: 다음 artifacts/tests/a11y-manual/<ROUTE_ID>.md: missing record (FE-GATE-009) |
같은 원인 | 같은 곳 |
Manual accessibility evidence is incomplete: 다음 <ROUTE_ID>: <failures> (FE-GATE-028) |
서명하지 않은 기록 | 03 문서 |
release IDs do not match (FE-GATE-028) |
라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 |
<doc> names paths that do not exist: <paths> (verify:documentation) |
문서가 없는 경로를 적었다 | 그 문서 |
릴리스 승인·공급망
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
release admission refused for <target>: 다음 contractPackages.<packageId>: pins the placeholder identity create:feature writes; pin the published package's version, digest and revision (FE-GATE-027) |
자리표시자 계약 신원으로 공개 대상 승인 | 03 문서 "자리표시자 계약 신원 교체" |
high-risk dependency missing review: add:<name>@<version> (generate:supply-chain) |
production 의존성을 더했는데 검토 기록이 없다 | config/security/dependency-change-evidence.json |
제거 드릴
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
<id> removal failed: 다음 fixture-id-residue: residue: <files> (test:sample-removal) |
기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. src는 기능 ID나 폴더 이름을 담은 파일, tests는 이름이 기능 ID를 담거나 기능 폴더(src/features/<id>/, tests/features/<id>/)에서 import하는 파일이다 |
그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 |
No installed feature declares FEATURE_MODULE_ID "<id>" |
--feature=에 없는 기능 ID |
명령 인자 |
feature scaffold failed: 다음 <check>: <failure> (test:feature-scaffold) |
생성한 기능이 게이트 하나를 통과하지 못했다 | scripts/create-feature.ts의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 |