b45d6a03db7ab71abd5f9d6369d6140ee08296e1
16
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
b45d6a03db |
fix(removal): 제품 기능 제거 드릴이 템플릿 테스트의 예시 ID를 잔여로 세지 않는다
문제: 매뉴얼 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 |
||
|
|
bfd9d50d2b |
fix(registries): 계약 조립 실패의 원인을 check:registries에 한 번만 찍는다
문제: 계약 조립이 실패하면 check:registries 출력에 같은 원인이 두 번 나온다. 1103/09-07 수정이 ContractContributionError의 message 끝에 reason을 붙였고, 1103/14-06 수정이 loadErrorText에서 message 뒤에 "(reason: ...)"를 또 붙였다. 두 수정이 다른 브랜치에서 들어왔다. 기존 테스트는 reason이 message에 없는 가짜 오류로만 시험해 중복을 보지 못했다. 고른 방법: loadErrorText가 message에 reason이 이미 들어 있으면 붙이지 않는다. reason을 message에 싣지 않는 오류(기존 테스트의 가짜 오류)는 지금처럼 "(reason: ...)"가 붙는다. 버린 대안: ContractContributionError message에서 reason을 다시 빼는 것. message만 찍는 다른 출구(부팅 오류, 테스트 출력)가 원인을 잃는다(1103/09-07이 고친 문제). 위험·한계: message 첫 줄만 보므로 여러 줄 reason은 다시 붙는다. 지금 reason은 한 줄이다. docs/manual/reference/errors.md의 출력 형식 줄을 실제 출력에 맞췄다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/registry-governance.test.ts 새 테스트는 실제 ContractContributionError를 던지는 source로 check:registries를 돌려 원인이 한 번만 나오는지 본다. Refs: 1105/09-03 |
||
|
|
799ab7f667 |
fix(dev): dev manifest를 기능 생성·제거 때 다시 쓰는 커밋 파일로 둔다
문제 c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된 기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는 capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로 떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음 0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤 끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다. 감시 이벤트(파일 쓰기)를 없애도 같았다. 고른 방법 - 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을 그대로 낸다. - 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로 둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를 돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기 절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다. - tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의 contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다. - 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다. Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev server 로그의 page reload). - 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와 같은 조건을 dev만 따로 두게 된다. 위험·한계 - 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다. test:unit이 그 상태를 이름과 명령으로 알린다. 검증 - test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건, check:types, lint, verify:documentation 통과. - 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋 뒤 깨끗한 clone에서 돈다. Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09 |
||
|
|
2ec9d56008 |
feat(scaffold): create:feature --with-create가 짝 백엔드 생성기와 같은 slice를 만든다
문제
- 프론트 create:feature는 GET /api/<base>-items 목록 하나를 만든다. 짝 백엔드
new-feature.sh는 POST /<plural>(201, NOT_IDEMPOTENT)과 GET /<plural>/{id}를
만든다. 경로 규칙도, operation 쌍도 맞지 않는다(03-07).
- 짝 백엔드 모양(Envelope)의 상세 GET·작성 POST·폼·결과 불명 화면 예제는
참조 기능뿐이고, 참조 기능은 problem details 모양이라 옮기면 짝 백엔드에서
쓰이지 않는 분기와 값(400·422 분류, retryBudget 0, Envelope 줄 없음)을
함께 옮긴다(09-06, 16 5.3절).
- 생성된 목록의 "총 N개"는 배열 길이다. 백엔드 meta.page.total을 쓰지
않는다(03-02 수정이 남긴 일).
고른 방법
- 경로: 백엔드 new-feature.sh와 같은 복수형 규칙(backendPathSegment)으로
API_PATH 상수 하나를 둔다. 백엔드 api-base-path는 API_BASE_URL에 붙인다.
- 목록: mapper가 { items, total }을 내고 total은 page?.total ?? 길이다. 빈
목록은 EmptySurface로 같은 빈 상태를 그린다.
- --with-create: 상세 GET, 작성 POST, 상세·작성 라우트와 페이지, 폼 스키마
(이름 100자 = 백엔드 NAME_MAX_LENGTH), 뮤테이션 정책(commandMutationIdentity),
작성 폼 테스트를 만든다. 작성은 백엔드 기본에 맞춰 NEVER(retryBudget 0, 키
없음)다. --keyed는 백엔드 create를 IdempotencyExecutor 뒤에 둔 경우의
KEYED 값(IDEMPOTENCY_REPLAY, retryBudget 1)을 쓴다.
- 작성 descriptor: acceptedStatuses [201], refusedBeforeWrite
["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED(백엔드
보안 필터·@RequiresPermission 프록시·rate-limit interceptor가 use case 전에
거절한다). mapProblem이 <BASE>_INVALID를 이름 칸 오류로 바꾼다.
- 생성 테스트: gateway 테스트가 세 operation의 백엔드 본문(201 Envelope,
404 <BASE>_NOT_FOUND, 400 <BASE>_INVALID → NOT_APPLIED, 응답 유실 →
MAYBE_APPLIED, NEVER는 키 없음·KEYED는 503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키
1회 재전송)을 손으로 적는다. 하네스 재시도 상한은 앱 기본값 2다(16-07 (3)).
작성 폼 테스트는 라우터를 거쳐 201 저장 뒤 상세 열기, 400 거절을 이름 칸에
보이고 저장 버튼이 켜진 채 다시 저장, 응답 유실 뒤 결과 불명(NEVER는 다시
보내기 없음, KEYED는 같은 Idempotency-Key로 다시 보내기)을 본다.
- 페이지 테스트의 앱 조립은 <base>-test-app.tsx 하나로 모은다.
- slice 템플릿은 scripts/create-feature-write-slice.ts에 둔다. 리뷰 5.3절
재검토 조건(템플릿 2,000줄)을 넘지 않게 하고, create-feature.ts의 수정을
필요한 자리로 좁힌다.
- X1: 생성한 context 선언을 임시 폴더에 써서 생성기 선언 읽기로 읽고, 그
모듈을 import해 앱 모듈 조립(라우트 루트 검사)이 기능 라우트를 받는지 보는
단위 테스트를 더한다.
버린 대안
- 작성을 기본 KEYED로: 백엔드 생성 create는 키를 읽지 않아, 같은 키 재전송이
새 항목을 만든다. 안전해 보이는 거짓 보장이다.
- 참조 기능을 Envelope로 옮기기(09-06 (2)): 참조 테스트와 MSW fixture를 다수
바꾸고 problem details 예제가 사라진다.
- 목록 값을 배열로 두고 total을 배열 속성으로 싣기: TanStack 구조 공유가 배열
속성을 버린다.
위험·한계
- 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에 GET 페이지 목록을
더하기 전에는 생성 목록이 405를 받는다. descriptor 주석과 매뉴얼에 적었다.
- 생성 기능의 초기 JS: 기본 +647 B, --with-create +964 B(이 브랜치 기준선
203,702 B에서 잰 값, 기능당 1 KiB 안). 기준선의 남은 여유는 1,098 B라
--with-create 기능 하나를 넣으면 134 B가 남는다.
- 두 생성기를 실제로 띄워 붙여 보지는 않았다. 백엔드 템플릿의 응답 본문과
경로를 읽어 생성 테스트에 옮겼다.
검증
- RED: tests/unit/create-feature.test.ts 새 17건 실패 → GREEN 43건 통과.
- 기본·--with-create·--with-create --keyed·--context reference-context
--with-create 네 기능을 만든 상태에서: check:types(app·test·node), lint,
check:registries(additive), check:i18n, check:architecture,
check:design-system, check:diagnostics, verify:documentation 통과. 생성 기능
테스트 77건 통과. 빠른 계층 313파일 3,818건 중 참조 라우팅 테스트 1건만
실패(X1, 다음 커밋).
- 변이: refusedBeforeWrite 삭제 → gateway·폼 테스트 2건 실패. 상세 GET의
responseEnvelope 삭제 → 조립 거절로 테스트와 check:registries 실패. KEYED
retryBudget 0 → 503 재전송 테스트 실패. 정책의 descriptor 상수 오타 → tsc 실패.
- flock 아래 build, check:bundle: 기준 203,702, 기본 기능 204,349, --with-create
기능 204,666 / 204,800 B PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-06
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-07
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
|
||
|
|
3b40f73638 |
fix(contracts)!: 스키마 메타의 boundary를 쓰임과 대조하고 실패 본문 행을 둔다
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(
|
||
|
|
f59a806429 |
feat(server-state): 뮤테이션 정책이 operation ID와 키 여부를 descriptor에서 받는다
문제 BoundMutation의 operationId와 requiresIdempotencyKey는 기능이 손으로 다시 적는 자유 값이다. operationId에 오타가 있어도 check:types와 check:registries가 통과하고, 실행기는 intent의 operation ID가 descriptor와 다르다며 보내기 전에 거부한다(MISSING_IDEMPOTENCY_KEY 위반). 화면은 "요청을 처리할 수 없습니다"로 멈추고 원인을 말하지 않는다(리뷰 E-2). 1101/03-03이 같은 재기술을 적었다. 고른 방법 src/contracts/server-state.ts에 commandMutationIdentity(descriptor)를 둔다. descriptor의 operationId와 retrySemantics === "KEYED"를 돌려주고, 정책은 이것을 펼쳐 쓴다. 상수 이름 오타는 tsc가 잡는다. GET·HEAD descriptor를 넘기면 바인딩 때 throw한다. 참조 기능의 생성 정책이 이것을 쓴다. 버린 대안 - BoundMutation.operationId를 brand 타입으로: 자유 문자열도 막지만 테스트 약 27곳과 다운스트림 정책을 깨는 공개 타입 변경이다. - 실행기 위반 이름을 INTENT_OPERATION_MISMATCH로 나누기: http 어댑터의 닫힌 위반 어휘와 화면 매핑을 바꾼다. 값을 descriptor에서 받으면 그 경로에 닿지 않으므로 미뤘다. - 타입에서 method를 쓰기 method로 좁히기: InstalledHttpContract로 주석한 descriptor(method: HttpMethod)가 모두 타입 오류가 나서 실행 때 검사만 둔다. 위험·한계 - 정책에 operationId 문자열을 직접 적는 길은 남는다. 매뉴얼 7단계 "못 잡음"에 적었다. - 참조 기능 presentation이 계약 기여 파일을 import한다. 두 파일 모두 지연 청크라 초기 JS는 바뀌지 않는다(check:bundle은 다음 커밋들과 함께 잰다). 검증 - RED: tests/unit/command-mutation-identity.test.ts 4건이 함수 없음으로 실패. GREEN 뒤 통과. - tests/features/reference-feature, tests/component/application-query.test.tsx 125건 통과. - check:types, check:architecture, lint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-05 |
||
|
|
3f7e10c91a |
fix(contracts): 한 계약 기여 안에서 응답 모양이 다른 operation을 거절한다
문제 responseEnvelope는 operation마다 적는 선택 칸이다. 생성 뼈대에 operation을 손으로 더하면서 이 줄을 빠뜨려도 check:types, check:registries, 라우터를 거치는 페이지 테스트가 모두 통과한다. MSW 시나리오 핸들러가 descriptor의 선언대로 답하기 때문이다. 짝 백엔드에 붙이면 그 화면만 SCHEMA_MISMATCH로 깨진다(리뷰 E-1). 고른 방법 계약 조립이 기여 하나 안의 operation이 같은 응답 모양을 읽는지 본다. 값이 없는 것과 "NONE"은 같은 모양이다. 기여 하나는 백엔드 하나의 패키지라서 그 안의 operation은 한 모양이다. 두 백엔드를 쓰는 기능은 기여를 나눈다. 거절 reason은 두 operation과 고칠 방법을 말한다. 앱을 조립하는 모든 테스트와 check:registries가 실패한다. 버린 대안 - responseEnvelope를 필수 칸으로: tsc가 잡는 가장 강한 통제지만 descriptor 약 25곳(참조, tests, 다운스트림 손 descriptor, 계약 패키지)을 깨는 공개 타입 변경이다. 같은 실수(일부만 빠뜨림)를 이 규칙이 잡으므로 작은 쪽을 골랐다. - 기여 단위 기본값: "기본값이 어디서 오나"라는 규칙이 하나 는다. 위험·한계 - 기여 안의 operation 모두에서 줄을 빼면 잡지 못한다. 생성된 gateway 테스트 (백엔드 본문을 손으로 적음)만 잡는다. 매뉴얼에 적었다. - 한 기여에 두 모양을 섞던 다운스트림 기여는 조립이 거부한다. 레포 안에서는 테스트 fixture 하나(api-operation-rows)가 그랬고 고쳤다. 검증 - RED: 새 테스트 3건 중 섞인 기여 거절 1건 실패. GREEN 뒤 통과. - tests/unit·integration·contract·component·features·runtime-schema·platform· architecture 297파일 3,718건: 섞인 fixture 1건만 실패 → 고친 뒤 통과. - check:types, lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01 |
||
|
|
d5e3bf2e2c |
chore(review): 1103 계약·레지스트리 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 07-01~07-04 13-04 14-06 |
||
|
|
c99b7a7f63 |
docs(contracts): 두 오류 어휘와 commandRecovery를 누가 읽는지 타입 옆에 적는다
문제 - AppFailure(닫힌 kind, retryable, action)와 AppError(열린 owner.reason kind, retryability)의 관계가 타입 옆에 없다. AppFailure.retryable과 action "retry"는 뜻이 다른데(CONFLICT는 retryable false, action retry) 설명이 없어 모순으로 읽고 "고치는" 변경이 나올 수 있다(1101/07-05). - CommandRecoveryDescriptor는 KEYED 쓰기에 필수지만 HTTP 실행기는 읽지 않는다. 결과 불명 쓰기를 기능 gateway가 수습한다는 것은 설계서 4.4절에만 있다(1101/07-07). - 07-01(c)에서 더한 읽기 retrySemantics 거절 문구가 errors.md reason 표에 없다. 고른 방법 주석만 더한다. AppFailure 위에 어느 경계에서 어느 어휘를 쓰는지와, 둘 다 재시도 동작을 바꾸지 않는다는 것. retryable 칸에 "src에서 읽는 곳이 없고, 화면 버튼은 action"이라는 것. CommandRecoveryDescriptor 위에 실행기가 읽지 않고 기능 gateway가 재전송·조회를 정한다는 것. errors.md reason 표에 한 행. 버린 대안 - retryable을 autoRetryable 같은 이름으로 바꾸기: 다운스트림 import를 깨는 비용에 비해 얻는 것이 작다. 위험·한계 - 동작은 바뀌지 않는다. "src에서 읽는 곳이 없다"는 grep으로 확인한 지금 상태다. 검증 - grep: src/presentation·bootstrap·features·application에서 AppFailure.retryable을 읽는 곳 0. commandRecovery를 읽는 곳은 플랫폼 개요 화면뿐. - eslint, verify:documentation 통과. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 1101/07-05, 1101/07-07 |
||
|
|
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
|
||
|
|
f98d0c3663 |
fix(contracts): 계약 조립 오류 메시지에 원인을 싣는다 (1103/09-07)
문제
ContractContributionError의 message는 "Installed contract contribution is not
composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는
message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에
operation id도 프로필 id도 없었다("missing registry source …: Installed
contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience
정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …"
메시지를 약속했다.
고른 방법
message에 reason을 붙인다: "Installed contract contribution is not composable:
<reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을
보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를
그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다.
문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로
고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다.
위험·한계
- check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object
registry, breaking change missing evidence … removed)은 그대로다(14-06 범위).
- message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다.
검증
- RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN
으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패.
- 같은 파일, external-contract-runtime, http-execution-v3-auth-profile,
reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과.
- eslint, tsc(test), verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07
|
||
|
|
9edc8307b0 |
fix(features)!: 기능이 아닌 폴더 표시를 NOT_A_FEATURE로 바꾸고 선언과 함께 두면 실패한다 (1103/09-09)
문제 src/features/<dir>/NOT_INSTALLED 표시는 "기능이 아닌 샘플 폴더"라는 뜻인데, 같은 단어가 런타임 상태 "선언됐지만 빌드·FEATURE_OVERRIDES가 뺀 기능"으로도 쓰였다(product-features.ts). 생성기는 feature-module.ts를 못 읽을 때만 표시를 찾았으므로, 샘플을 졸업시키며 표시를 지우지 않으면 표시가 "설치 안 됨"이라고 말하는 채로 조용히 설치됐다. 고른 방법 - 표시 이름을 NOT_A_FEATURE로 바꾼다(local-draft-feature 파일 이름 변경). 런타임 상태 NOT_INSTALLED는 그대로 둔다. - 생성기가 표시와 feature-module.ts가 함께 있으면 둘 중 무엇을 지울지 적고 실패한다. - 옛 이름 표시는 받지 않는다. 받으면 같은 다의가 남는다. 옛 표시만 있는 폴더는 "has no feature-module.ts; … mark the directory with NOT_A_FEATURE"로 실패해 새 이름을 알려 준다. README 상태 표, starter-experience, 매뉴얼 errors·patterns 표를 맞췄다. 위험·한계 다운스트림이 자기 폴더에 NOT_INSTALLED 표시를 두었다면 생성 단계가 실패한다. 파일 이름만 바꾸면 된다. 검증 - RED: 생성기 테스트 3건(새 이름 허용, 옛 이름 거절, 동시 존재 거절)이 수정 전 실패. - generate-product-feature-index.test.ts 17건 통과. generate:feature-index 통과. verify:documentation PASS_SCOPED. eslint, tsc(node·test) 통과. BREAKING CHANGE: src/features/<dir>/NOT_INSTALLED 표시 파일은 더 이상 인식되지 않는다. 같은 자리에 NOT_A_FEATURE라는 이름으로 옮긴다. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-09 |
||
|
|
365d8c3c02 |
fix(contracts): 쿠키 인증 쓰기는 CSRF 헤더를 요구하는 프로필만 조립한다
문제 브라우저는 쿠키를 어느 사이트의 요청에든 붙이므로, 쿠키로 인증하는 쓰기 요청은 페이지만 넣을 수 있는 헤더(CSRF 토큰)가 있어야 서버가 진짜 요청을 가른다. V2 클라이언트는 resolveRestSecurityProfiles로 "쿠키 프로필 + GET·HEAD 밖 method면 HEADER CSRF 프로필"을 강제했다. 048f490·12f3bb7이 V2를 지운 뒤 V3에는 이 검사가 없다. V3 프로필 설치 규칙은 SAME_ORIGIN_COOKIE에 쿠키 전송과 bearer 금지만 요구한다. 그래서 제품이 CSRF 헤더 없는 쿠키 프로필을 POST에 붙여도 조립이 통과한다. 고른 방법 assertHttpContract가 operation의 auth profile을 설치된 레지스트리에서 찾아, 쓰기(GET·HEAD 밖)인데 SAME_ORIGIN_COOKIE이고 requiredCredentialHeaders에 x-csrf-token·x-xsrf-token이 없으면 operation·method·프로필 이름을 담아 거절한다. 읽기 쿠키 프로필은 CSRF 없이 그대로 된다(tech-log·memento 예시와 같다). 버린 대안 - 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구: 읽기 전용 쿠키 프로필 (MEMENTO_BFF_READ 등)까지 막는다. method는 operation에만 있다. - 요청 때(attachCredentials) 검사: 조립 때 잡을 수 있는 설정 실수를 사용자 요청 시점까지 미룬다. 위험·한계 - 이미 CSRF 없는 쿠키 쓰기 프로필을 쓰는 제품은 조립이 실패한다. 의도한 실패다(CHANGELOG [보안]). - 헤더 값이 올바른 CSRF 토큰인지는 서버만 안다. 프론트는 헤더가 반드시 실리는지만 보장한다(requiredCredentialHeaders가 없으면 fetch 0회). 검증 - RED: tests/unit/rest-profile-contract.test.ts "refuses a write whose cookie profile requires no CSRF header" 실패(조립이 통과). - GREEN: 같은 파일 7건 통과. CSRF를 요구하는 쓰기와 CSRF 없는 쿠키 읽기는 조립된다. - check:types, lint, check:architecture, check:registries, test:unit 2,568, test:integration 117, test:component 245 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 |
||
|
|
12f3bb7862 |
refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제 기능 하나가 같은 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에 넘긴다. |
||
|
|
5c2f8b875c |
docs(manual): 매뉴얼만으로 기능을 추가한 실험의 막힘 5건을 메운다 (1101/16-01)
문제: docs/manual(
|
||
|
|
8b2048763b |
docs(manual): 새 기능 추가 매뉴얼을 docs/manual에 쓴다 (U9, 1101/16-01)
문제 - 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와 폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패 메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다. 리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다. - create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일 (a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다. 고른 방법 - docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과 안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일, reference/ 4개(create-feature, global-ids, patterns, errors). - 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다 정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을 적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트 밖 라우트는 이제 앱 모듈이 적재 때 거부한다). - 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로 바꿨다. - 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY, 게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿 docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은 design-docs의 conventions/feature-design-principles.md를 번호로만 가리킨다. - 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지 않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는 것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만 더한다. - 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조 페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다. - 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고 지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기 (입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기 (메시지로 문서를 검색할 수 없다). 위험·한계 - docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는 verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래 .md만 검사하므로 reference/도 따로 링크해야 한다. - 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절 번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다. - 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만 둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능 테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다. - "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시 돌리지 않았다. 검증 - docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고 node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서 모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다. - 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두 말하며 FAIL_UNVERIFIED. - 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고, 42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩 코드에서 확인했다. - node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과. |