d4aa365bd9e1da4eba72b9d9fd7b451ce576b92e
18
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
af10cae9a6 |
docs(architecture): 현재 계약 문서와 매뉴얼의 영어 부분을 한국어로 옮긴다
문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md, starter-experience.md, capability-consumer-experience.md, contract-ownership.md, static-delivery.md, review-evidence.md는 본문이 영어이고, backend-api-and-server-state-contract.md와 optional-adapter-recipes.md에는 영어 문단이 남아 있다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드 주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은 그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서 고친다. - tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를 자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`) - 「Ownership declarations」「Adding a feature」를 인용한 주석 (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과 docs/manual의 절 이름 인용 - optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게 바꾼다(number 검사) 위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라 새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다. review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다. 검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로 비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외 목록에서 지웠다. |
||
|
|
01cac930e0 |
docs(manual): 샘플 대신 생성 기능 경로와 시험하는 코드 조각을 예제로 둔다
매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을 가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는 참조 기능에만 있다. 생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안 코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절, 소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook, 403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다. tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어 tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를 돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다. 위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오 forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이 끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에 이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서 실패한다. 검증(desktop): test:unit 213 files 3096 passed(이 커밋까지), verify:documentation PASS_SCOPED, lint 통과. |
||
|
|
b72cd7d4a7 |
test(fixtures): local-draft 샘플을 IndexedDB 소비자 fixture로 옮긴다
src/features/local-draft-feature는 기능이 아니라 IndexedDB recipe의 소비자다. 시험 5개와 recipe가 쓰고, 그래서 생성기에 NOT_A_FEATURE 예외가 있었다(S4 3.1절 S-3). 코드를 tests/fixtures/indexeddb-consumer/로 옮기고 import만 고쳤다. NOT_A_FEATURE 표식은 이 폴더만 썼고 다운스트림 둘에도 없어 생성기에서 지웠다. 선언 없는 폴더는 밖으로 옮기라는 메시지로 실패한다. 매뉴얼 오류표, README, starter-experience, capability-consumer-experience, patterns를 고쳤다. 위험: fixture는 기능 폴더 밖이라 기능 계층 규칙(dependency-cruiser)이 걸리지 않는다. recipe가 tests/ 아래 파일을 type import한다. 검증(desktop): test:contract, test:recipes, test:browser-capabilities, test:unit 통과. |
||
|
|
1dda18da30 |
fix(docs): 참조 기능 경로를 다시 백틱으로 적어 문서 검사가 본다
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.
고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
README, starter-experience, static-delivery, compatibility,
backend-api-and-server-state-contract, manual-checklist,
adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
and scripts only where verify:documentation checks them"을 더했다. 검사기가
읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
검사기와 같은 규칙을 두 곳에 두게 된다.
위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal
Refs: 1105/14-03
|
||
|
|
48c1ab7ab6 |
fix(server-state)!: 손으로 적은 뮤테이션 operation ID를 타입 검사에서 막는다
문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만 BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를 문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고, 저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로 거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다. 고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로 바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을 직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열 그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice 생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다. 템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts (commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로 바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다. 버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행 때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림 분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게 적재되는 계약 전체를 타입으로 모을 곳이 없다. 위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에 operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가 실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든 객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌 뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가 없다. 검증: desktop batch에서 확인. corepack pnpm check:types:test tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모 커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다. node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx BREAKING CHANGE: BoundMutation.operationId는 string이 아니라 MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와 `requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)` 로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환 타입도 operationId가 MutationOperationId다. Refs: 1103/16-05 |
||
|
|
41f8801d64 |
chore(review): 1103 기능 생성기·기능 패턴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-07 09-06 16-01 16-04~16-07 # Conflicts: # docs/manual/01-add-a-feature.md # docs/manual/reference/create-feature.md # docs/manual/reference/patterns.md # scripts/create-feature.ts # scripts/test-feature-scaffold.ts |
||
|
|
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
|
||
|
|
fbd8f7d148 |
chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02 # Conflicts: # docs/manual/01-add-a-feature.md # docs/manual/02-decision-tables.md # docs/manual/reference/patterns.md |
||
|
|
68f94f5e93 |
refactor(server-state): 아무도 읽지 않는 쿼리·뮤테이션 정의 칸을 선택 칸으로 둔다
문제 QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다. bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능 작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로 적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②). 고른 방법 세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는 채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다. 매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title· navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다. 버린 대안 - 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과 다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다. - 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의 operation ID를 싣는다. 같은 값을 두 번 싣는다. 위험·한계 - 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면 FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와 test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은 파일이라 이번에는 문서로만 적었다. 검증 - RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner· operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과. - tests/features/reference-feature, tests/unit/create-feature.test.ts, scope-fence 129건 통과. check:types(app·node·test), lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06 |
||
|
|
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 |
||
|
|
e20b5bfe3a |
chore(review): 1103 업로드·전송 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 01-01 01-02 01-03 |
||
|
|
f800549315 |
feat(http): 짝 백엔드 Fileserver의 multipart 한 번 업로드 client를 더한다
문제: 두 템플릿을 짝으로 쓰면 파일 업로드 경로가 없다. 프론트 업로드 레시피는 PRESIGNED_MULTIPART_V1 서버를 가정하는데 짝 백엔드는 그 코드를 지웠고, 짝 백엔드 Fileserver(POST /v1/files)를 부를 프론트 client는 없다. src 전체에 multipart 요청을 만드는 코드가 없다. 고친 방법(리뷰 D1 (나-1)): src/adapters/http/fileserver-upload.ts에 createFileserverUploadClient를 둔다. 백엔드 bbe944bd 계약 그대로다. - 입력은 FileContentPort.openSource가 주는 FileByteSource다. 바이트를 한 번 읽어 multipart 본문(파트 이름 file, RFC 7578, 파일 이름은 HTML 폼 인코더처럼 escape)을 직접 만든다. File·Blob은 이 adapter에 들어오지 않는다(eslint browser-data 경계). 선언 크기가 maxFileBytes보다 크면 읽기 전에 거절하고, 읽는 중에 넘어도 멈춘다. 선언 크기가 있으면 본문 버퍼 하나에 바로 쓴다. - 전송 규칙은 레시피와 V3 실행기와 같다. credentials는 인증 프로필이 정하고, 자격 증명 헤더는 admitCredentialHeaders로 프로필에 맞춰 받는다. redirect "error", no-referrer, no-store, 응답 본문 상한, 바이트에 비례한 deadline 하나, 호출자 abort(커널 createAbortableOperation). - 성공: 201 READY / 202 그 밖의 state를 Envelope에서 읽는다. 201과 202의 state가 맞지 않거나 size가 보낸 바이트와 다르면 SCHEMA_MISMATCH, APPLIED_CONFIRMED. - 실패: backend-envelope.ts의 readFailureEnvelope와 envelopeFailureReading을 그대로 쓴다. 효과 판정은 Fileserver 계약을 따른다. details.ambiguous, AMBIGUOUS_COMPLETION, IDEMPOTENT_IN_FLIGHT, IDEMPOTENCY_COMPLETION_UNKNOWN은 MAYBE_APPLIED. 그 밖의 4xx는 NOT_APPLIED(백엔드 UploadFile use case가 모호하지 않은 실패에서 업로드를 취소한다). 5xx는 이름 붙인 Fileserver code만 NOT_APPLIED이고 나머지는 MAYBE_APPLIED. 보낸 뒤 네트워크 실패· 시간 초과·abort도 MAYBE_APPLIED. Envelope의 retryable:false와 상한(기본 30초)을 넘는 Retry-After는 retryable을 false로 만든다(01-02와 같은 규칙). - Idempotency-Key 헤더를 보낸다. client는 스스로 다시 보내지 않는다. 위치를 http adapter로 고른 이유: Envelope 해석(backend-envelope.ts), 자격 증명 admission(http-contract-bridge.ts), bounded reader를 adapter 안 import로 다시 쓴다. 새 adapter 사이 import 예외가 필요 없다. 바꾼 http 파일은 index.ts의 export 한 묶음뿐이다. 버린 대안: - backend-envelope.ts를 커널(src/adapters/platform/)로 옮기고 client를 browser-transfer에 둔다. 다른 작업이 지금 고치는 파일을 옮겨야 하고, 커널은 제품 중립 primitive 자리인데 백엔드 짝 정책이 들어간다. file-transfer 레시피 예산 여유도 1.7KB뿐이고, 이 client는 presigned 레시피와 무관한데 그 제거 드릴에 함께 지워진다. - browser-transfer에 Envelope 파서를 하나 더 둔다. 갈라진 사본이다. - V3 실행기에 multipart 본문을 더한다. 1,900줄짜리 실행기를 다른 작업과 동시에 크게 고쳐야 한다. - FormData와 Blob을 쓴다. http adapter는 File·Blob을 쓸 수 없고(eslint), 기능은 Blob을 갖지 않는다. 조립: 제품이 product-composition.ts에서 client 재료 (FileserverUploadClientDependencies)를 capability로 넘기고, 기능 adapter가 createFileserverUploadClient를 부른다. 그래서 템플릿 boot 번들에는 들지 않는다. 매뉴얼 02 결정표 7절, patterns.md, 두 architecture 문서, 레시피 fallback이 이 경로를 가리킨다. adapter INVENTORY와 상세 리뷰 표에 행을 더했다(번호는 끝에 141로 붙였다). 위험·한계: - 재개가 없다. 파일 전체를 메모리에 한 번 읽는다(maxFileBytes까지). tus client는 없다. - 짝 백엔드 bbe944bd의 POST /v1/files는 멱등 키를 읽지 않는다 (NOT_IDEMPOTENT). MAYBE_APPLIED 뒤 같은 키로 다시 보내도 파일이 두 개 생길 수 있다. 매뉴얼에 적었다. - 효과 판정 표(NOT_APPLIED_5XX_CODES, MAYBE_APPLIED_CODES)는 백엔드 bbe944bd 기준이다. 어긋남을 알리는 검사는 없다(12-06과 같은 종류). - 실제 짝 백엔드를 띄운 업로드는 하지 않았다. 테스트는 계약대로 답하는 MSW다. 실제 브라우저(Playwright)에서도 돌리지 않았다. - 템플릿 기본 product-composition.ts가 자격 증명 owner를 노출하지 않으므로, 템플릿 세션(EXTERNAL_BEARER)으로 올리려면 제품이 자기 credential provider를 써야 한다. 검증: - tests/integration/fileserver-upload.test.ts 48건 통과(201/202 본문, Envelope 실패 16종, 409 IDEMPOTENT_IN_FLIGHT + Retry-After 2, 상한 밖 Retry-After, 보낸 뒤 네트워크 실패 뒤 같은 키 재전송, 시간 초과, abort, 자격 증명 거절, 크기·입력 거절). multipart 본문은 undici FormData 파서로 다시 읽어 확인했다. - 변이 7건(4xx 판정, ambiguous 무시, 상한 무시, credentials 고정, 키 누락, 201/202 state 검사 제거, Envelope retryable 무시) 모두 실패를 만들었다. - check:types, lint(바꾼 파일), check:architecture, check:adapter-inventory, verify:documentation, check:registries, check:ci 통과 - check:bundle PASS: initial JS 201,921 / 204,800 gzip bytes. 빌드 산출물 어디에도 client 코드가 없다(dist grep). check:optional-recipes:source PASS (file-transfer 56,082 / 57,800) Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01 |
||
|
|
c4d587052e |
fix(removal): 참조 기능을 지워도 문서 게이트가 통과하고 드릴이 그것을 본다
문제 README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서 10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고, verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서 참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거 드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint· check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다. 고른 방법 - 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로 적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로 적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다. - 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지 복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint, verify:documentation, check:i18n, check:design-system을 돈다 (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다. - 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2 (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울 수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다. 위험·한계 - 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지 않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다. - 드릴 시간이 lint·문서 검사 두 번만큼 는다. - 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기). 검증 - 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤 PASS_SCOPED. - 저장소에서 verify:documentation PASS_SCOPED, documentation-readiness 14건 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04 |
||
|
|
245f428123 |
fix(features): 제품 capability 타입과 기본값 설정 키가 타입 검사 3종을 통과한다 (1103/09-02)
문제 제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다. (a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를 보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만 product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능 파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를 리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이 경로를 지나지 않았다. 고른 방법 - 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고 FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를 extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든 프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은 capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유 파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을 고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다. - tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가 쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿 테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로 바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를 강요해 버렸다. - tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와 기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다. - 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature, frontend-application-foundation, 계약 주석. 위험·한계 - 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이 아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을 적었다. - product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로 옮겨야 node 검사가 통과한다. 검증 - RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿 테스트 8건, E-PROD와 같은 위치)에서 실패. - 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과. - check:types(tsc app·node·test), check:architecture, eslint, verify:documentation PASS_SCOPED. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02 |
||
|
|
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 |
||
|
|
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건 통과. |