Commit Graph
11 Commits
Author SHA1 Message Date
DongHyeonka 84d6e526a3 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
2026-11-04 20:38:14 +09:00
DongHyeonka 3ea7c37ed0 fix(registry): 적재에 실패한 레지스트리 source는 그 오류를 함께 적는다
문제: check-registries는 레지스트리 source 모듈의 import 오류를 삼키고
"missing registry source <path>"만 남겼다. 파일은 있는데 그 안의 import가
깨진 경우에도 파일이 없는 것처럼 보였다. 6ea9e4a의 원인(옮긴 export를 예전
경로에서 가져온 fixture)도 이 메시지만으로는 찾을 수 없어 임시 출력을 넣어
찾았다.

방법: source 경로가 있는데 적재가 실패하면 오류 메시지 첫 줄을 실패 문장
뒤에 붙인다. 파일이 없을 때의 문장은 그대로다(release-artifacts·json-schema
테스트가 그 문장을 쓴다). 스택 전체를 붙이는 방법은 버렸다. 산출물 JSON의
failures가 커지고 경로가 실행 환경마다 달라진다.

위험: 다운스트림이 이 실패 문장을 정확히 비교하면 달라진다. 파일이 없는
경우의 문장은 바뀌지 않았다.

검증: tests/unit/registry-governance.test.ts에 "있지만 import가 깨진 source"
테스트를 더했다. 수정 전 실패(1 failed), 수정 뒤 10건 통과. check-registries
PASS, eslint, tsc(node) 통과.
2026-11-03 02:15:31 +09:00
DongHyeonka e8d7fb427f fix(registry): 기능 라우트를 추가해도 governance를 고치지 않게 한다 (0929/07-03)
문제
FE-REG-ROUTE governance가 paramsSchema·searchSchema·loadingSurface를 참조
기능 값까지 적은 닫힌 목록으로 둔다. 기능이 자기 search 스키마나 자기
로딩 화면 이름을 가진 라우트를 더하면 check:registries가 "has unknown
value"로 실패하고, 템플릿 소유 파일인 registry-governance.json을 고쳐야
한다. 목록은 contract 일부라 고치면 breaking 증거나 재승인도 필요하다.
두 다운스트림 모두 여기서 충돌했다. 스키마 id는 이미 references가
FE-REG-SCHEMA와 대조하므로 목록은 같은 사실의 세 번째 사본이고,
loadingSurface는 data-surface 속성 말고 읽는 코드가 없다. 문서는
"governance file do not change"라고 적지만 그 약속을 고정하는 테스트는
라우트 없는 기능만 넣었다.

고른 방법 (2026-11-03 결정, 리뷰 (B))
- paramsSchema·searchSchema를 FE-REG-ROUTE allowedValues에서 뺐다.
  references 검사는 그대로라 등록되지 않은 스키마 id는 계속 실패한다.
- loadingSurface는 목록 대신 이름 형식만 본다. governance에 선언형 키
  fieldPatterns(필드 → 고정된 정규식)를 더하고 check-registries가 문자열
  값을 대조한다. FE-REG-ROUTE는 kebab-case
  ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$를 쓴다. fieldPatterns는 선언한
  레지스트리에서만 contract 스냅샷에 들어가므로 다른 레지스트리의
  contract는 바뀌지 않고, 정규식을 바꾸면 contract 변경(breaking)으로
  잡힌다.
- second-api-feature-registries 테스트의 두 번째 기능에 자기 search 스키마
  (SecondItemListQuery)와 전용 loading surface(second-item-list)를 가진
  라우트를 넣었다. 저장소 사본에 기능 디렉터리와 context만 더하고
  check-registries가 PASS인지 본다. 지시의 two-feature-install-typecheck는
  app 타입 검사만 돌려 governance를 보지 않으므로, check-registries를 돌리는
  이 테스트를 확장했다.
- 라우트 fixture(check:routes:fixture)의 governance도 같은 모양으로 바꾸고,
  형식에 맞지 않는 이름("Unknown loading")이 거절되는 단위 테스트를 더했다.
- starter-experience.md가 이 테스트를 가리키고, 라우트의 스키마·로딩 화면이
  governance 수정 없이 들어가는 이유를 적는다.
- 두 contract 변경(allowedValues 축소, fieldPatterns 추가)은 breaking이다.
  이 커밋에서는 증거 2건으로 게이트를 통과시키고, 기준선 재승인은 이번
  작업 묶음 끝에서 한 번에 한다.

이유: 기능 하나를 추가할 때 템플릿 파일을 고치게 만드는 지점이다. 두
다운스트림 모두에서 충돌했다.

버린 대안
- 문서만 "allowlist를 고치고 증거를 쓴다"로 정정: 기능마다 비용이
  반복된다.
- 기능 계약이 자기 allowlist 값을 기여하는 확장 메커니즘: 등록 규약이
  하나 더 생긴다.

위험·한계
- loadingSurface 오타는 이제 형식만 맞으면 통과한다. 이 값은 로딩
  요소의 data-surface 속성일 뿐이라 동작이 바뀌지 않는다. loadingSurface가
  로딩 컴포넌트 선택 같은 실행 의미를 갖게 되면 닫힌 목록을 다시 둔다.
- errorSurface·access는 라우터가 의미로 읽으므로 닫힌 목록을 유지한다.
  기능이 새 errorSurface를 쓰려면 지금처럼 governance를 고친다.
- 다운스트림은 다음 동기화에서 자기가 이 목록에 더한 값을 지운다.
  CHANGELOG [계약] 행이 필요하다.

검증
- RED(수정 전): 확장한 second-api-feature-registries 테스트가
  "FE-REG-ROUTE.SECOND_ITEM_LIST.searchSchema has unknown value
  SecondItemListQuery", "...loadingSurface has unknown value
  second-item-list"로 실패. 새 형식 테스트는 수정 전 checker로
  "expected [] to deeply equal [ Array(1) ]"로 실패.
- GREEN: 두 테스트 통과. 증거 없이 check-registries는 "breaking change
  missing evidence" 2건(allowedValues contract-field-changed,
  fieldPatterns contract-field-added)으로 실패, 증거를 넣은 뒤
  "11 registries PASS".
- 회귀: registry-compatibility·registry-governance·second-api-feature-
  registries·release-artifacts·two-feature-install-typecheck 57/57.
  compatibility fixtures 11 PASS. check:routes:fixture는 기대대로
  "duplicates routeId=DUPLICATE"로 실패. verify-documentation-readiness
  PASS_SCOPED. tsc node·test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
2026-11-03 00:55:33 +09:00
DongHyeonka 82c9e594ff fix(registry): 선언된 null 전환과 허용값 추가를 breaking으로 막지 않는다 (0929/07-02)
문제
레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS
타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로
판정한다. null과 문자열은 타입이 달라서, governance가 string|null로
선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API
timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도
breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도
어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에
"마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID
defaultValue null -> "local-build"에 "the value itself did not change"라고
적은 breaking 증거를 남겼다.

고른 방법 (리뷰 최소 개선 B)
- 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입
  (contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라
  field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나
  선언 밖 값이면 지금처럼 field-type-changed(breaking)다.
- contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두
  포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나,
  새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지
  contract 변경도 그대로 breaking이다.
- 선언 타입 판정은 check-registries.ts에 있던 runtimeType·
  matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다.
- semantic-diff.json fixture에 nullable-field-cleared(behavior-change),
  registry-contract-extension(additive)을 더하고 artifact id 목록에도
  넣었다.

버린 대안
- 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는
  길을 더 넓힌다(0929/07-04).
- nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른
  레지스트리 영향을 다시 봐야 하는 넓은 변경이다.
- 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰
  기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로
  breaking에 남겼다.

위험·한계
- fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능
  꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다.
  paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다.
- 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서
  behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행
  (field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는
  0929/07-01 범위라 이번에는 지우지 않았다.
- 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이
  바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번
  라운드는 CHANGELOG 미출시 절이 없어 적지 않았다).
- fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아
  계속 breaking으로 남는다.

검증
- RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패
  (null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의
  kind, allowlist 확장 breaking). check-registry-compatibility-fixtures:
  nullable-field-cleared actual breaking, registry-contract-extension
  actual breaking.
- GREEN: registry-compatibility·registry-governance·release-artifacts·
  second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS.
  check-registries "11 registries PASS"(남은 breaking은
  REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음).
  ci-artifact-contract "semantic validator" 사례 통과.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian
  exit=126 환경 문제로 이 변경과 무관하게 실패).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonkaandClaude Opus 5.5 ad0e83c867 fix(features): make feature add and removal work from the feature directory (09-07, 14-03)
A feature directory without feature-module.ts vanished silently, registry
consumers listed only the sample's directories, and the removal gate only knew
the sample. The generator now fails unless a NOT_INSTALLED marker says so
(D-10), consumer directories are globs over every feature, and the removal
script takes --feature=<id>. starter-experience.md documents the current
ownership declarations and the files a new feature touches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:10:19 +09:00
DongHyeonka 381d5549e2 fix: preserve artifact writer failures 2026-08-02 04:46:33 +09:00
DongHyeonka c9f5887cac refactor: validate generated evidence artifacts 2026-08-02 04:33:01 +09:00
DongHyeonka 53d181fbe4 fix: baseline invalidation registry contracts 2026-08-02 00:28:17 +09:00
DongHyeonka 0eb23875cb fix: harden invalidation registry governance 2026-08-01 23:59:11 +09:00
DongHyeonka c6da03369c refactor: 리펙토링 2026-08-01 19:39:59 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00