From 1dda18da30aa45b1f991d62460142a6bba5ab7a1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 23:08:46 +0900 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=EC=B0=B8=EC=A1=B0=20=EA=B8=B0?= =?UTF-8?q?=EB=8A=A5=20=EA=B2=BD=EB=A1=9C=EB=A5=BC=20=EB=8B=A4=EC=8B=9C=20?= =?UTF-8?q?=EB=B0=B1=ED=8B=B1=EC=9C=BC=EB=A1=9C=20=EC=A0=81=EC=96=B4=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EA=B2=80=EC=82=AC=EA=B0=80=20=EB=B3=B8?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 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 --- README.md | 10 ++-- docs/accessibility/manual-checklist.md | 2 +- .../backend-api-and-server-state-contract.md | 4 +- docs/architecture/starter-experience.md | 10 ++-- docs/architecture/static-delivery.md | 2 +- docs/contracts/compatibility.md | 2 +- docs/manual/01-add-a-feature.md | 20 +++---- docs/manual/02-decision-tables.md | 2 +- docs/manual/03-outside-feature-folder.md | 4 +- docs/manual/reference/patterns.md | 6 +-- docs/operations/adapter-remediation-ledger.md | 4 +- docs/operations/performance-evidence.md | 12 +++-- ...template-feature-removal-documents.test.ts | 54 +++++++++++++++++-- 13 files changed, 91 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index e84a8d0b..81d6bd69 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ See `docs/architecture/frontend-application-foundation.md`, `docs/architecture/overview.md`, `docs/architecture/layers.md`, and `docs/architecture/starter-experience.md`. The removable vertical slice is -the reference sample, src/features/reference-feature; its domain, application input, HTTP +under `src/features/reference-feature`; its domain, application input, HTTP binding, contracts, route runtime, and presentation own their contributions. The central installed catalogs only aggregate selected contributions. The generic starter routes continue to typecheck, test, and build after that @@ -232,8 +232,12 @@ reads them, except the one file noted below The reference feature is not in this list: deleting its directory alone leaves tests, policy entries and CI scripts behind that fail the gates. `scripts/test-sample-removal.ts` removes it from a copy of -the repository and lists everything that has to go with it (its header comment -and `SAMPLE_EXTRAS`); do the same in your project and run the gates. +the repository and lists everything that has to go with it (its header comment, +and the files outside the feature's folders in +`scripts/lib/removable-template-features.ts`); do the same in your project and +run the gates. The documents keep naming the sample's paths: the documentation +check accepts them once `src/features/reference-feature/feature-module.ts` is +gone. ## Verification diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 21804569..2e4158db 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -77,5 +77,5 @@ What the automated run scans: annotation. - The reference sample's list in its success, empty and error states, its detail, its form with submit errors and its status page, each after that - state is on screen (tests/e2e/reference-form.spec.ts, removed with the + state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the sample). diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md index f0526f2a..200015ea 100644 --- a/docs/architecture/backend-api-and-server-state-contract.md +++ b/docs/architecture/backend-api-and-server-state-contract.md @@ -283,8 +283,8 @@ backend idempotency를 대체하지 않는다. `src/presentation/adapters/query/application-query.ts` - Envelope operation의 거절 판정: `src/adapters/http/backend-envelope.ts` `REFUSED_BEFORE_WRITE`(6.1절 표) - - 참조 기능(Envelope 없음) 판정: src/features/reference-feature/contracts/reference-feature-contract-contribution.ts - (effect), src/features/reference-feature/adapters/reference-http-gateway.ts + - 참조 기능(Envelope 없음) 판정: `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts` + (effect), `src/features/reference-feature/adapters/reference-http-gateway.ts` (code) ### 6.1 거절 code와 적용 여부 diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index ea669dbd..01843825 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -168,8 +168,7 @@ selected app. Every build and check script runs it first; run it yourself with invalidation, topic versions and the external `contractPackages` the release manifest is checked against at boot), its message catalogs, and `loadRuntime`, which imports `feature-runtime.ts` dynamically. - The reference sample's feature-module.ts (src/features/reference-feature, - while it is installed) is the complete example. + `src/features/reference-feature/feature-module.ts` is the complete example. 2. Create `src/features//feature-runtime.ts` with `defineFeatureRuntime`: the `schemas` (FE-REG-SCHEMA rows for the feature's route and API schemas), the adapter contributions @@ -179,8 +178,7 @@ selected app. Every build and check script runs it first; run it yourself with it (`application.features.load`) when one of the feature's routes is entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip - (tests/unit/feature-shape-growth.test.ts, which goes with the reference - sample, bounds one feature at 1 KiB). + (`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB). An HTTP API is written once, as its contract contribution descriptor: it executes, and `check:registries` governs the FE-REG-API row projected from it (`projectApiOperationRows` in `src/contracts/api-operations.ts`). @@ -191,7 +189,7 @@ selected app. Every build and check script runs it first; run it yourself with `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each route handle carries the route's params/search `codecs`; the owning context loads this file only when its route root is visited - (the reference sample's context-routes.ts shows one). Each handle's + (`src/features/reference-feature/context-routes.ts`). Each handle's `routeId` must be a route of a feature contract in the same context; the context refuses the routes when they load, naming the route, context and features (`src/contexts/bounded-context-module.ts`). @@ -223,7 +221,7 @@ Files outside the feature directory. Everything else a feature needs is in | --- | --- | --- | | `src/.generated/*` | never by hand: every build and check script regenerates it | — | | `public/release-manifest.json` (tracked, the dev server's manifest) | every added or removed feature: `create:feature` rewrites it (`node scripts/write-dev-release-manifest.ts`). Commit it with the feature. Two feature branches change its `setDigest` line; on a merge conflict take either side and run the command again (1105/16-01) | `test:unit` (`tests/unit/dev-release-manifest.test.ts`) names the command; the dev server does not boot (`CONTRACT_SET_PACKAGE_MISSING`) | -| config/scale/feature-shape-ceilings.json `initialJavascript` (tracked, only while the sample is installed) | every added or removed feature, and every template change that moves the initial JavaScript: node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write. Commit it with the change; on a merge conflict run the command again | `test:unit` (the feature-shape growth test compares it with a build) | +| `config/scale/feature-shape-ceilings.json` `initialJavascript` (tracked, only while the sample is installed) | every added or removed feature, and every template change that moves the initial JavaScript: `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. Commit it with the change; on a merge conflict run the command again | `test:unit` (the feature-shape growth test compares it with a build) | | `src/contexts//context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature belongs to undeclared context ` | | `src/contexts//context-layout.tsx` | the context needs its own frame instead of `AppShell` (see "Product home and layouts" below) | nothing: without it the context renders in `AppShell` | | `artifacts/tests/a11y-manual/.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release | diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index f6765dd2..66caf133 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.md @@ -43,7 +43,7 @@ immutable release has a coherent HTML/assets/config/API/manifest tuple. Serve the app over HTTP/2 or later. The entry preloads every initial JavaScript file in parallel (`initialJsFiles` in `config/performance/budgets.json` bounds how many; the current count is -`initialJavascript.files` in config/scale/feature-shape-ceilings.json, which goes with the sample feature). Over HTTP/1.1 they queue for six connections per +`initialJavascript.files` in `config/scale/feature-shape-ceilings.json`, which goes with the sample feature). Over HTTP/1.1 they queue for six connections per host, and the first screen on Fast 3G came about one second later than with the initial chunks grouped (2026-11-03). Over HTTP/2 the difference was under 100 ms, so the template keeps the chunks split. A product that can only serve diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index ce4d99c5..9185fd3b 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -25,7 +25,7 @@ reader that accepts it must ship before any writer sends it. | `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` | | Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` | | HTTP success/failure envelope (V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/backend-envelope.ts` | -| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in the reference sample's contracts/reference-schemas.ts | +| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in `src/features/reference-feature/contracts/reference-schemas.ts` | | Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` | | Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` | | Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 5f5f3859..17121c2a 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -5,7 +5,7 @@ - 뼈대는 손으로 만들지 않는다. `corepack pnpm create:feature `로 만든다. - 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다. -참조 기능(src/features/reference-feature/)을 복사해 이름을 바꾸는 방법은 쓰지 않는다. +참조 기능(`src/features/reference-feature/`)을 복사해 이름을 바꾸는 방법은 쓰지 않는다. 그 방법은 접두어 없는 전역 ID, 참조 전용 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다. 생성 명령은 이 문제를 미리 피한 파일을 쓴다. @@ -151,7 +151,7 @@ corepack pnpm create:feature invoice-feature - 있으면 `domain/.ts`에 둔다. - 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다. - 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 `name`을 `displayName`으로 바꾼다). -- 예제(참조 기능): src/features/reference-feature/domain/ +- 예제(참조 기능): `src/features/reference-feature/domain/` - 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다. - 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다. - 서버가 정한 제한이면 `contracts/-schemas.ts`에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다. @@ -241,7 +241,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 2. problem 스키마를 problem details 모양으로 바꾼다. 3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다. -참조 기능(src/features/reference-feature/)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. +참조 기능(`src/features/reference-feature/`)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다. **입력과 스키마 메타데이터** @@ -378,7 +378,7 @@ projectRequest: (input) => Object.freeze({ - 참조 기능은 생성 operation에 목록 route(`REFERENCE_RESOURCE_LIST`)를 적었다. 실제로 보내는 화면은 폼 route다. 동작은 같고 기록의 이름표만 다르다. 새 기능은 위 기준을 따른다. - `needs`에는 실제로 쓰는 것만 적는다. - 템플릿이 만들지 않는 capability(예: `indexedDb`)는 `src/bootstrap/product-composition.ts`에서 만든다. 제품이 새로 만드는 capability의 타입은 `src/features/product-capabilities.ts`에 적는다. [03 문서](03-outside-feature-folder.md)를 본다. -- 문제 응답 매핑 예제(참조 기능): src/features/reference-feature/adapters/reference-http-gateway.ts +- 문제 응답 매핑 예제(참조 기능): `src/features/reference-feature/adapters/reference-http-gateway.ts` ③ **잡는 검사 / 못 잡는 것** @@ -422,8 +422,8 @@ projectRequest: (input) => Object.freeze({ ② **기준** - 경로는 계약에만 적는다. 페이지와 링크는 route ID와 `buildRouteUrl`로 URL을 만든다. 경로 문자열을 페이지에 다시 적지 않는다. -- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제(참조 기능): src/features/reference-feature/context-routes.ts. - - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다. `--with-create` 판의 상세 라우트는 codec을 넘긴다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제(참조 기능): src/features/reference-feature/presentation/reference-routes.ts. +- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제(참조 기능): `src/features/reference-feature/context-routes.ts`. + - 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다. `--with-create` 판의 상세 라우트는 codec을 넘긴다. 안 넘기면 `Unregistered route codec: `로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제(참조 기능): `src/features/reference-feature/presentation/reference-routes.ts`. - 상세 경로는 목록 경로 뒤에 `/items/:`을 붙인다. 예: `/notice/items/:noticeId`. `/notice/:noticeId`로 두지 않는다. - 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 `/notice/new`가 있으면 id가 `new`인 공지는 `/notice/:noticeId`로 열 수 없다. - `items/`를 끼우면 정적 경로와 겹치지 않는다. 참조 기능도 이렇게 한다(`/examples/reference-resources/items/:resourceId`). @@ -487,7 +487,7 @@ projectRequest: (input) => Object.freeze({ }); ``` - - 예제(참조 기능): src/features/reference-feature/presentation/use-reference-feature.ts의 생성 뮤테이션 정책. + - 예제(참조 기능): `src/features/reference-feature/presentation/use-reference-feature.ts`의 생성 뮤테이션 정책. ③ **잡는 검사 / 못 잡는 것** @@ -519,7 +519,7 @@ projectRequest: (input) => Object.freeze({ - 화면 문구는 모두 catalog에서 가져온다(`message(key)`). - 링크는 6단계의 URL 함수로 만든다. -- 결과 불명 화면 예제: `create:feature --with-create`의 `presentation/-create-page.tsx`(짝 백엔드 Envelope), 참조 기능의 src/features/reference-feature/presentation/reference-resource-form-page.tsx(problem details) +- 결과 불명 화면 예제: `create:feature --with-create`의 `presentation/-create-page.tsx`(짝 백엔드 Envelope), 참조 기능의 `src/features/reference-feature/presentation/reference-resource-form-page.tsx`(problem details) ③ **잡는 검사 / 못 잡는 것** @@ -616,7 +616,7 @@ projectRequest: (input) => Object.freeze({ expect(await posts[0]!.json()).toEqual({ title: "새 공지", body: "본문입니다." }); ``` - - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제(참조 기능): tests/features/reference-feature/reference-production-vertical.test.tsx의 504 재전송 테스트. + - 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제(참조 기능): `tests/features/reference-feature/reference-production-vertical.test.tsx`의 504 재전송 테스트. - 빠르게 돌리기: `node scripts/run-vitest.ts run tests/features/` - CI에서는 `test:coverage`(FE-GATE-005)가 `tests/features`를 돈다. `test:unit`은 `tests/unit`만 돈다. @@ -676,7 +676,7 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature - 지연 페이지가 셸과 같은 구성요소(`Button`, `SearchField` 등)를 쓰면 그 구성요소가 공유 청크로 떨어져 초기 파일 수도 하나 늘 수 있다. 파일 수 상한(`initialJsFiles`)은 여유가 있다. - 예산은 `config/performance/budgets.json`에 있다. 넘었을 때 고르는 법은 `docs/operations/performance-evidence.md`에 있다. 넘으면 예산을 올리기 전에 팀이 정한다. - 생성 명령의 드릴(`test:feature-scaffold`)도 merge 단계 명령으로 이 검사를 돈다. -- 참조 기능이 설치돼 있으면 초기 JS 기록(config/scale/feature-shape-ceilings.json)도 기능과 함께 바뀐다. test:unit이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=`)은 지운 뒤 기록을 다시 쓰고 검사한다. +- 참조 기능이 설치돼 있으면 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 기능과 함께 바뀐다. `test:unit`이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=`)은 지운 뒤 기록을 다시 쓰고 검사한다. - 로컬에서 FE-GATE-013을 돌리려면 `VITE_COMMIT_SHA=$(git rev-parse HEAD)`를 준다. 없으면 release candidate가 `source.revision`을 거절한다. 실패한 게이트의 로그는 `artifacts/quality/gates/FE-GATE-.txt`에 있다. - workflow와 같은 조건으로 돌리려면 README 로컬 merge 게이트 반복문 아래의 env 블록대로 `CI=true`와 CI 빌드 식별값(`VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest)을 주고 깨끗한 clone에서 돌린다. 이 값 없이 통과해도 CI에서 떨어질 수 있다(1103/11-07, 11-08). - 게이트는 한 checkout에서 하나씩 돌린다. 게이트와 증거 검사는 `dist`와 `artifacts/`의 고정 경로를 읽는다. diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index cc61cf6b..a63a822e 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -209,7 +209,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 **정본**: 어떤 status·code가 "적용 안 됨"인지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2다. -**어디에 적나**: `contracts/-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 예제(참조 기능): src/features/reference-feature/contracts/reference-feature-contract-contribution.ts의 `CREATE_EFFECT`. +**어디에 적나**: `contracts/-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 예제(참조 기능): `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts`의 `CREATE_EFFECT`. **틀리면** diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index ed195250..69058b8c 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -38,7 +38,7 @@ | 파일 | 누가 쓰나 | 다시 쓰는 명령 | 안 넣으면 | |---|---|---|---| | `public/release-manifest.json` (dev server의 manifest) | `create:feature`가 생성 뒤 바로 쓴다. 설치된 계약 패키지 목록(`packages`)과 그 다이제스트(`setDigest`) | `node scripts/write-dev-release-manifest.ts` | `test:unit`(`tests/unit/dev-release-manifest.test.ts`)이 다시 쓰는 명령을 말하며 실패한다. dev server가 `CONTRACT_SET_PACKAGE_MISSING`으로 부팅하지 못한다 | -| config/scale/feature-shape-ceilings.json의 `initialJavascript` (초기 JS 기록) | 사람이 명령으로 쓴다. 참조 기능이 설치돼 있는 동안만 있다(참조 기능과 함께 지워진다) | node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write | `test:unit`이 빌드와 대조해 실패한다 | +| `config/scale/feature-shape-ceilings.json`의 `initialJavascript` (초기 JS 기록) | 사람이 명령으로 쓴다. 참조 기능이 설치돼 있는 동안만 있다(참조 기능과 함께 지워진다) | `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write` | `test:unit`이 빌드와 대조해 실패한다 | - **브랜치 둘이 충돌한다.** `setDigest`는 설치된 패키지 전체의 해시 한 줄이고, `initialJavascript`는 빌드 전체의 합계다. 기능을 하나씩 더한 두 브랜치는 같은 줄을 다른 값으로 바꾼다. 둘째 브랜치를 합칠 때 텍스트 충돌이 난다. - **충돌하면 손으로 값을 합치지 않는다.** 아무 쪽이나 고른 뒤 위 명령을 다시 돌려 그 결과를 커밋한다. 두 기능이 다 들어간 상태의 값이 나온다. 손으로 합친 값이 틀리면 `test:unit`이 같은 명령을 말하며 실패한다. @@ -212,7 +212,7 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE) - `config/testing/risk-coverage.json`에서 그 기능을 가리키는 행 - 그 기능만 쓰던 제품 capability, 제품 인증 프로필, 계약 패키지 의존성 -그다음 dev manifest(`public/release-manifest.json`)의 계약 패키지를 `node scripts/write-dev-release-manifest.ts`로 다시 쓰고, 참조 기능이 설치돼 있으면 초기 JS 기록(config/scale/feature-shape-ceilings.json)도 node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write로 다시 쓴다(위 A의 표). 그리고 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다. +그다음 dev manifest(`public/release-manifest.json`)의 계약 패키지를 `node scripts/write-dev-release-manifest.ts`로 다시 쓰고, 참조 기능이 설치돼 있으면 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다(위 A의 표). 그리고 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다. ```bash REGISTRY_BASELINE_OWNER=<담당> REGISTRY_BASELINE_REASON=" removed" corepack pnpm update:registry-baseline diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index d529b831..cbcabd14 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -3,7 +3,7 @@ 기능을 만들 때 쓰는 패턴과, 그 패턴의 정의와 예제가 어디 있는지 적는다. - **정의**: 플랫폼(기능 밖)에서 패턴을 제공하는 파일. -- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature --with-create`가 더 만드는 코드다(짝 백엔드 Envelope 모양). `참조 기능`은 src/features/reference-feature/다(Envelope가 아닌 problem details 모양). 참조 기능은 지울 수 있으므로 그 경로는 백틱 없이 적는다. 백틱 경로는 문서 검사(`verify:documentation`)가 존재를 확인한다. +- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature --with-create`가 더 만드는 코드다(짝 백엔드 Envelope 모양). `참조 기능`은 `src/features/reference-feature/`다(Envelope가 아닌 problem details 모양). 참조 기능 경로도 다른 경로처럼 백틱으로 적는다. 문서 검사(`verify:documentation`)는 참조 기능이 있는 동안 그 경로가 있는지 확인하고, 참조 기능을 지운 사본에서는 없어도 된다고 본다(`scripts/lib/removable-template-features.ts`). - 예제가 없는 패턴은 **없음**이라고 적었다. 그 패턴은 정의를 읽고 직접 쓴다. 참조 기능은 예제일 뿐이다. 복사해 이름을 바꾸지 않는다. 모양을 보고 생성 뼈대에 옮긴다. @@ -13,12 +13,12 @@ | 패턴 | 정의 | 예제 | 검사 | |---|---|---|---| | 기능 모듈 등록 | `src/features/feature-module.ts` (`defineFeatureModule`, `defineFeatureRuntime`), 생성기 | 생성 뼈대 `feature-module.ts`, `feature-runtime.ts` | 생성기, 기능 ID와 계약 `featureId` 일치 | -| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 참조 기능의 src/contexts/reference-context/context-module.ts | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) | +| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 참조 기능의 `src/contexts/reference-context/context-module.ts` | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) | | context 전용 레이아웃 | `docs/architecture/starter-experience.md` "Product home and layouts" | `tests/helpers/fixture-layout-product.tsx` (테스트 fixture) | `tests/component/context-layouts.test.tsx` | | 앱 홈 대신하기 | `src/contracts/routes.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` | 없음 (기능 예제) | 조립 (두 기능이 `APP_HOME`을 선언하면 실패) | | 조립 기여(`needs`) | `src/features/feature-adapter-contribution.ts` | 생성 뼈대 `adapters/create--feature-input.ts` | 조립 (없는 capability, 다른 기능의 input) | | 제품 capability | `src/features/product-capabilities.ts`(타입), `src/bootstrap/product-composition.ts`(값), `src/bootstrap/product-composition-contract.ts` | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | `check:types` | -| 기능 끄기 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 tests/component/product-feature-switch.test.tsx | +| 기능 끄기 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 `tests/component/product-feature-switch.test.tsx` | ## 라우트 diff --git a/docs/operations/adapter-remediation-ledger.md b/docs/operations/adapter-remediation-ledger.md index 78819d06..5e48aab7 100644 --- a/docs/operations/adapter-remediation-ledger.md +++ b/docs/operations/adapter-remediation-ledger.md @@ -194,7 +194,7 @@ Captured after every correctness task landed. | `git diff --check` | 0 | clean | | `corepack pnpm test:component` | 0 | 126 passed | | `corepack pnpm test:integration` | 0 | 52 passed | -| test:reference-feature (the reference sample's script) | 0 | 26 passed | +| `corepack pnpm test:reference-feature` | 0 | 26 passed | | `corepack pnpm test:recipes` | 0 | 17 passed | | `corepack pnpm test:unit` | 1 | 1585 passed / 19 failed tests; the 19 are the unchanged pre-existing `ci-artifact-contract` sandbox failures | | `corepack pnpm check:registries` | 0 | 11 registries PASS | @@ -340,7 +340,7 @@ Run on the landed tree. Only what actually passed is claimed as passing. | `tests/unit` + `tests/integration`, no exclusions | — | 1643 passed / 1747; the 104 failures are the four environmental files below | | `corepack pnpm test:component` | 0 | 126 passed | | `corepack pnpm test:recipes` | 0 | 17 passed | -| test:reference-feature (the reference sample's script) | 0 | 26 passed | +| `corepack pnpm test:reference-feature` | 0 | 26 passed | ### Environmental failures, not claimed as green diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 9e01948c..5c231aee 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -20,8 +20,9 @@ Performance evidence is deliberately split by measurement context: 보고 예산을 정한다. 기준선 숫자는 이 문서에 적지 않는다. 손으로 적은 숫자는 두 번 낡았다. 기록은 -config/scale/feature-shape-ceilings.json의 `initialJavascript` 한 곳이다. 이 파일과 아래 -측정 테스트는 참조 기능을 복사해 재므로 샘플과 함께 지워진다. 그래서 경로를 백틱 없이 적는다. +`config/scale/feature-shape-ceilings.json`의 `initialJavascript` 한 곳이다. 이 파일과 아래 +측정 테스트는 참조 기능을 복사해 재므로 샘플과 함께 지워진다. 문서 검사는 샘플을 지운 사본에서 +이 경로들을 요구하지 않는다(`scripts/lib/removable-template-features.ts`). | 칸 | 뜻 | |---|---| @@ -29,14 +30,15 @@ config/scale/feature-shape-ceilings.json의 `initialJavascript` 한 곳이다. | `perFeatureGzipBytes` | 있는 context에 참조 기능 모양 기능을 하나 더할 때 느는 초기 JS. 상한 1 KiB | | `perContextGzipBytes` | 새 context를 하나 더할 때 느는 초기 JS. 상한 512 B | -- tests/unit/feature-shape-growth.test.ts(unit, merge 단계)가 매번 빌드해 이 +- `tests/unit/feature-shape-growth.test.ts`(unit, merge 단계)가 매번 빌드해 이 값을 재고, 상한을 넘거나 기록과 다르면(합계 256 B 초과, 파일 수 불일치, 기능· context 비용 10% 초과) 실패한다. 실패 메시지에 잰 값이 나온다. - 합계의 허용 오차는 바이트로 둔다(1105/15-02). build id만 달라도 합계가 수십 B 움직이므로 0으로 둘 수 없다. 예전 1%(약 2 KB)는 남은 여유와 기능 하나보다 커서, 여유를 다 쓴 변경이 기록을 고치지 않고 지나갈 수 있었다. -- 기록을 고칠 때는 `node scripts/scale/measure-feature-shape-growth.ts - --initial-baseline --write`를 돌리고 같은 변경에 넣는다. +- 기록을 고칠 때는 + `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`를 + 돌리고 같은 변경에 넣는다. - 여유는 예산에서 `gzipBytes`를 뺀 값이다. 그것을 `perFeatureGzipBytes`로 나누면 더 넣을 수 있는 기능 수다. 새 context마다 `perContextGzipBytes`가 더 든다. - 기능 실행부(`feature-runtime.ts`)는 라우트에 들어갈 때 받는 lazy chunk다. diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts index 68d564e9..a8de7cc2 100644 --- a/tests/unit/template-feature-removal-documents.test.ts +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -62,8 +62,9 @@ async function verifyWithout(removed: readonly string[]) { /** * Runs this repository's verify:documentation on a copy of the documents * with `mutate` applied to `document`; the code facts are this repository's. + * `documents` are the ones it checked (docs/README.md §1 and what it links). */ -async function verifyDocuments(document: string, mutate: (text: string) => string) { +async function verifyDocuments(document: string, mutate: (text: string) => string = (text) => text) { const parent = await mkdtemp(path.join(tmpdir(), "template-feature-documents-")); const root = path.join(parent, "frontend"); try { @@ -72,7 +73,11 @@ async function verifyDocuments(document: string, mutate: (text: string) => strin for (const entry of inputs) await cp(entry, path.join(root, entry), { recursive: true }); const target = path.join(root, document); await writeFile(target, mutate(await readFile(target, "utf8"))); - return spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" }); + const result = spawnSync(process.execPath, [path.resolve(CHECKER)], { cwd: root, encoding: "utf8" }); + const report = JSON.parse( + await readFile(path.join(root, "artifacts/quality/documentation-review.json"), "utf8"), + ) as { documentReferences: { path: string }[] }; + return { ...result, documents: report.documentReferences.map((entry) => entry.path) }; } finally { await rm(parent, { recursive: true, force: true }); } @@ -89,8 +94,8 @@ describe("verify:documentation after a template feature is deleted (1105/14-01)" ); // Only a deleted feature's paths are let through. While a feature is - // installed a missing path under it fails, and a folder that is not a - // removable template feature (a misspelt one) fails whether or not it exists. + // installed a missing path under it fails, and so does a feature folder + // that is not on the list (a misspelt one). it("still fails on a missing path under an installed template feature or an unknown folder", async () => { const document = "docs/architecture/starter-experience.md"; const missing = [ @@ -108,3 +113,44 @@ describe("verify:documentation after a template feature is deleted (1105/14-01)" for (const file of missing) expect(result.stderr).toContain(file); }, 60_000); }); + +/** Fenced blocks whose command lines verify:documentation reads. */ +const SHELL_FENCE = /^(?:bash|sh|shell|console|zsh)?$/u; + +/** + * 1105/14-03. The fix for 1103/14-04 wrote the reference sample's paths + * without backticks so that a copy without the sample passed, which also took + * 26 lines out of the check while the sample is installed: renaming one of + * its files left the manual pointing at nothing. Deleted features' paths are + * accepted now (above), so a current contract document names a removable + * template feature's path or script only where verify:documentation reads + * it: in an inline code span, a link target or a shell code block. + */ +describe("removable template features in the current contract documents (1105/14-03)", () => { + it("names their paths and scripts only where verify:documentation checks them", async () => { + const { documents } = await verifyDocuments("docs/README.md"); + const owned = REMOVABLE_TEMPLATE_FEATURES.flatMap((feature) => [ + ...removableTemplateFeaturePaths(feature), + ...feature.scripts, + ]); + const unchecked: string[] = []; + for (const document of documents) { + const lines = (await readFile(document, "utf8")).split("\n"); + let fence: string | null = null; + for (const [index, line] of lines.entries()) { + const marker = /^\s*```(\w*)/u.exec(line); + if (marker) { + fence = fence === null ? (marker[1] ?? "") : null; + continue; + } + if (fence !== null && SHELL_FENCE.test(fence)) continue; + const prose = line.replace(/`[^`\n]+`/gu, "").replace(/\]\([^)\s]+\)/gu, "]"); + for (const entry of owned) { + if (prose.includes(entry)) unchecked.push(`${document}:${index + 1}: ${entry}`); + } + } + } + expect(documents).toContain("docs/manual/01-add-a-feature.md"); + expect(unchecked).toEqual([]); + }, 60_000); +});