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
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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와 적용 여부
|
||||
|
||||
@@ -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>/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>/context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
|
||||
| `src/contexts/<context>/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/<ROUTE_ID>.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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
- 뼈대는 손으로 만들지 않는다. `corepack pnpm create:feature <id>`로 만든다.
|
||||
- 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다.
|
||||
|
||||
참조 기능(src/features/reference-feature/)을 복사해 이름을 바꾸는 방법은 쓰지 않는다.
|
||||
참조 기능(`src/features/reference-feature/`)을 복사해 이름을 바꾸는 방법은 쓰지 않는다.
|
||||
그 방법은 접두어 없는 전역 ID, 참조 전용 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다.
|
||||
생성 명령은 이 문제를 미리 피한 파일을 쓴다.
|
||||
|
||||
@@ -151,7 +151,7 @@ corepack pnpm create:feature invoice-feature
|
||||
- 있으면 `domain/<model>.ts`에 둔다.
|
||||
- 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다.
|
||||
- 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 `name`을 `displayName`으로 바꾼다).
|
||||
- 예제(참조 기능): src/features/reference-feature/domain/
|
||||
- 예제(참조 기능): `src/features/reference-feature/domain/`
|
||||
- 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다.
|
||||
- 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다.
|
||||
- 서버가 정한 제한이면 `contracts/<base>-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: <codecId>`로 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: <codecId>`로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제(참조 기능): `src/features/reference-feature/presentation/reference-routes.ts`.
|
||||
- 상세 경로는 목록 경로 뒤에 `/items/:<id 이름>`을 붙인다. 예: `/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 <id> --with-create`의 `presentation/<base>-create-page.tsx`(짝 백엔드 Envelope), 참조 기능의 src/features/reference-feature/presentation/reference-resource-form-page.tsx(problem details)
|
||||
- 결과 불명 화면 예제: `create:feature <id> --with-create`의 `presentation/<base>-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/<id>`
|
||||
- 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=<id>`)은 지운 뒤 기록을 다시 쓰고 검사한다.
|
||||
- 참조 기능이 설치돼 있으면 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 기능과 함께 바뀐다. `test:unit`이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=<id>`)은 지운 뒤 기록을 다시 쓰고 검사한다.
|
||||
- 로컬에서 FE-GATE-013을 돌리려면 `VITE_COMMIT_SHA=$(git rev-parse HEAD)`를 준다. 없으면 release candidate가 `source.revision`을 거절한다. 실패한 게이트의 로그는 `artifacts/quality/gates/FE-GATE-<NNN>.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/`의 고정 경로를 읽는다.
|
||||
|
||||
@@ -209,7 +209,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
|
||||
|
||||
**정본**: 어떤 status·code가 "적용 안 됨"인지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2다.
|
||||
|
||||
**어디에 적나**: `contracts/<base>-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 예제(참조 기능): src/features/reference-feature/contracts/reference-feature-contract-contribution.ts의 `CREATE_EFFECT`.
|
||||
**어디에 적나**: `contracts/<base>-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 예제(참조 기능): `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts`의 `CREATE_EFFECT`.
|
||||
|
||||
**틀리면**
|
||||
|
||||
|
||||
@@ -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="<id> removed" corepack pnpm update:registry-baseline
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
기능을 만들 때 쓰는 패턴과, 그 패턴의 정의와 예제가 어디 있는지 적는다.
|
||||
|
||||
- **정의**: 플랫폼(기능 밖)에서 패턴을 제공하는 파일.
|
||||
- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature <id> --with-create`가 더 만드는 코드다(짝 백엔드 Envelope 모양). `참조 기능`은 src/features/reference-feature/다(Envelope가 아닌 problem details 모양). 참조 기능은 지울 수 있으므로 그 경로는 백틱 없이 적는다. 백틱 경로는 문서 검사(`verify:documentation`)가 존재를 확인한다.
|
||||
- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature <id> --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-<base>-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/<profile>.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 tests/component/product-feature-switch.test.tsx |
|
||||
| 기능 끄기 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 `tests/component/product-feature-switch.test.tsx` |
|
||||
|
||||
## 라우트
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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다.
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user