문제 기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행 (defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고, contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게 http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가 없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을 위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석 (resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만 남기고, 레지스트리 기준선 재승인을 승인했다. 고른 방법 - src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다. 조립된 contribution의 descriptor마다 operationId, featureId, method, path, authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope, request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는 같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다. requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다. - FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다. installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고 FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다. - realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과 retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics· replayPolicy 대신). - rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립 때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다. - 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로 바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를 지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다. - create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를 만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다. - 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다 (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음). - 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다. 버린 대안 - V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은 실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다. - 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary· unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를 쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다. 위험·한계 - BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes 의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다. 옮기는 법은 CHANGELOG에 적는다. - V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF 모드)가 사라졌다. V3 descriptor에는 그 칸이 없다. - BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2 필드를 갖지만 자체 계약이라 바꾸지 않았다. 검증 - check:types, lint, check:architecture, check:registries(11 registries PASS, compatibility=none), check:ci, check:diagnostics, check:adapter-inventory, verify:documentation 통과. - test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함), test:integration 114, test:component 245, test:contract 23, test:runtime-schema 56, tests/features 99 통과. - tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두 번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다. - check:bundle 통과. 초기 JS 201,598 → 200,911 B. - test:feature-scaffold 16개, test:sample-removal 23개 검사 통과. BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다. defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations, validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS, createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles, validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile, loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은 operation을 contract contribution에만 적고, schemas 행을 feature-runtime에 넘긴다.
16 KiB
16 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 꼴 |
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_INSTALLED |
기능 폴더에 선언 파일이 없다 | feature-module.ts를 만들거나 NOT_INSTALLED 파일을 둔다 |
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 |
Product REST auth profile <id> reuses a template profile id. |
제품 프로필 ID가 템플릿 것과 같다 | src/contracts/product-contracts.ts |
계약·스키마·mapper
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
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도 같은 꼴) |
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 하나다. 원인은 오류 객체(ContractContributionError)의 reason 속성에 있다. 메시지만 보이면 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>: command operations require a command effect descriptor |
쓰기에 commandEffect가 없다 |
V3 commandEffect |
<id>/<operationId>: read operations carry no command descriptors |
GET에 commandEffect·commandRecovery를 적었다 |
둘 다 null |
<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 |
조립 기여
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
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를 지운다 |
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·tests에 기능 ID를 담은 파일이 남았다 |
그 파일을 기능 폴더 안으로 옮기거나, 기능 ID를 담지 않게 한다 |
No installed feature declares FEATURE_MODULE_ID "<id>" |
--feature=에 없는 기능 ID |
명령 인자 |
feature scaffold failed: 다음 <check>: <failure> (test:feature-scaffold) |
생성한 기능이 게이트 하나를 통과하지 못했다 | scripts/create-feature.ts의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 |