fix(registries): 계약 조립 실패의 reason을 적고 읽지 못한 레지스트리를 지운 것으로 세지 않는다

문제
기능 계약 조립이 실패하면(예: 없는 authProfileId) check:registries 출력은
"missing registry source src/features/loaded-feature-runtimes.ts: Installed
contract contribution is not composable" 두 줄, "FE-REG-API is not an
object registry", "FE-REG-ROUTE references unknown registry FE-REG-SCHEMA",
"breaking change missing evidence: FE-REG-API:*:*:removed" 등이다. 원인은
ContractContributionError.reason에 있는데 검사기는 message 첫 줄만 적는다.
끝의 removed 줄은 "breaking 증거를 더하라"로 읽혀 틀린 다음 행동을
제안한다(실험 E-9).

고른 방법
- source를 읽다 난 오류에 문자열 reason이 있으면 "(reason: ...)"로 함께
  적는다.
- 읽지 못한 레지스트리는 따로 모은다. 그 레지스트리에 대해서는 행 검사
  ("is not an object registry"), 그것을 가리키는 참조 검사, 기준선 비교
  (removed 증거 요구)를 하지 않는다. 같은 실패를 다른 이름으로 다시 적지
  않기 위해서다. 게이트는 load 실패 한 줄로 그대로 실패한다.
- errors.md 레지스트리 표에 이 메시지 행을 더했다.

버린 대안
- 메시지 접두어를 "failed to load"로 바꾸기: 의미는 더 맞지만 기존 테스트와
  CI 진단 기대값이 "missing registry source"를 쓴다. 이번에는 바꾸지 않았다.

위험·한계
- source 파일을 실수로 지운 경우에도 removed 증거 요구를 건너뛴다. 그래도
  "missing registry source" 실패로 게이트는 막힌다. 레지스트리를 의도해서
  지우면 governance에서도 빠지므로 removed 증거 요구는 그대로다.
- FE-REG-API와 FE-REG-SCHEMA가 같은 source라 load 실패 줄은 두 번 나온다.

검증
- RED: registry-governance에 임시 디렉터리 fixture(두 레지스트리, 하나가
  다른 하나를 참조, 기준선 있음)를 더했다. source가 reason 있는 오류를
  던지면 출력이 load 실패 한 줄이어야 한다. 고치기 전에는 reason이 없고
  cascade 3줄이 더 나와 실패했다.
- GREEN: registry-governance 11건 통과. E-9 재실행(참조 기능 목록
  operation의 authProfileId를 NOTICE_NOPE로): 출력이 "... (reason:
  reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId
  NOTICE_NOPE)" 두 줄뿐이고 removed 줄이 없다.
- check:registries:fixture·check:routes:fixture·baseline-fixture가 기대
  진단으로 실패한다. eslint, check:types:node, check:types:test 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-06
This commit is contained in:
DongHyeonka
2026-11-04 20:38:14 +09:00
parent 5bee9abed9
commit 84d6e526a3
3 changed files with 158 additions and 3 deletions
+1
View File
@@ -144,6 +144,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| `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> (reason: <reason>)` | 레지스트리 source를 읽다가 오류가 났다. 계약 조립 실패면 `<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`으로 다시 찍는다 |