diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 8c7967ad..fa66ffdf 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -215,6 +215,8 @@ Files outside the feature directory. Everything else a feature needs is in | File | When | What fails without it | | --- | --- | --- | | `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) | | `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/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index fc962ae0..347975f5 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -103,9 +103,12 @@ corepack pnpm create:feature invoice-feature → 파일 쓰기 (있는 파일은 덮어쓰지 않음) → 생성기 실행 → 생성기가 거부하면 만든 파일을 모두 지움 + → dev server manifest(public/release-manifest.json, 추적 파일) 다시 쓰기 → 만든 파일과 다음 할 일 출력 ``` +- 기능과 함께 커밋할 추적 파일은 둘이다. dev server manifest와, 참조 기능이 있는 동안의 초기 JS 기록이다. 기능 브랜치 둘이 같은 줄에서 충돌하면 명령을 다시 돌린다. 표와 명령은 [03 문서 A](03-outside-feature-folder.md#a-생성-명령이-만든다)에 있다. + ① **정할 것** - `--context `: 0단계에서 기존 context를 골랐을 때만 준다. diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index d4b56fcf..69f4d4f1 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -19,7 +19,7 @@ ## A. 생성 명령이 만든다 -`corepack pnpm create:feature`가 쓰는 폴더 밖 파일은 둘이다. 있는 파일은 덮어쓰지 않는다. +`corepack pnpm create:feature`가 새로 만드는 폴더 밖 파일은 둘이다. 있는 파일은 덮어쓰지 않는다. 이미 있는 추적 파일 중 다시 쓰는 것은 아래 "기능마다 바뀌는 템플릿 추적 파일"에 있다. - `src/contexts//context-module.ts` - 새 context일 때만 만든다. `--context`를 주면 만들지 않는다. @@ -31,6 +31,19 @@ `src/.generated/`도 기능 폴더 밖이다. 생성기가 매번 다시 만든다. 손으로 고치지 않는다. +### 기능마다 바뀌는 템플릿 추적 파일 (1105/16-01) + +새 파일 말고도, 기능 하나를 더하면 이미 있는 추적 파일 두 개가 바뀐다. 둘 다 명령이 쓰고, 기능과 같은 커밋에 넣는다. + +| 파일 | 누가 쓰나 | 다시 쓰는 명령 | 안 넣으면 | +|---|---|---|---| +| `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`이 빌드와 대조해 실패한다 | + +- **브랜치 둘이 충돌한다.** `setDigest`는 설치된 패키지 전체의 해시 한 줄이고, `initialJavascript`는 빌드 전체의 합계다. 기능을 하나씩 더한 두 브랜치는 같은 줄을 다른 값으로 바꾼다. 둘째 브랜치를 합칠 때 텍스트 충돌이 난다. +- **충돌하면 손으로 값을 합치지 않는다.** 아무 쪽이나 고른 뒤 위 명령을 다시 돌려 그 결과를 커밋한다. 두 기능이 다 들어간 상태의 값이 나온다. 손으로 합친 값이 틀리면 `test:unit`이 같은 명령을 말하며 실패한다. +- 레지스트리 기준선(`config/contracts/registry-baseline.json`)은 기능을 더하기만 하면 바뀌지 않는다(아래 C). + --- ## B. 사람이 꼭 해야 한다 @@ -182,7 +195,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`로 다시 쓰고, 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 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/scripts/create-feature.ts b/scripts/create-feature.ts index 15ed740b..3e2e5463 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -1691,6 +1691,27 @@ async function readInstalledFacts(root: string): Promise { }); } +/** + * 1105/16-01. Tracked template files that change with every added feature, + * and the command that writes each. A feature branch commits them with the + * feature; two feature branches change the same lines, and the merge takes + * the command again instead of a hand-merged value. docs/manual/03 (A) and + * the "Adding a feature" table in docs/architecture/starter-experience.md + * list them (tests/unit/feature-tracked-files.test.ts). + */ +export const FEATURE_TRACKED_FILE_REWRITES = Object.freeze([ + Object.freeze({ + path: "public/release-manifest.json", + command: "node scripts/write-dev-release-manifest.ts", + when: "create:feature runs it: the dev server's manifest names the installed contract packages", + }), + Object.freeze({ + path: "config/scale/feature-shape-ceilings.json", + command: "node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write", + when: "by hand while the sample is installed (the file goes with it): test:unit compares it with a build", + }), +]); + const USAGE = "Usage: pnpm create:feature [--context ] [--with-create [--keyed]] " + "[--package @scope/name@x.y.z --digest sha256:<64 hex> --revision ]"; @@ -1752,6 +1773,8 @@ function report(plan: FeaturePlan): string { " A failing gate's log is artifacts/quality/gates/FE-GATE-.txt. Locally FE-GATE-013 needs VITE_COMMIT_SHA=$(git rev-parse HEAD); to run them as CI does, set CI=true and the CI build identity (README).", " 3. The initial JavaScript changes. While config/scale/feature-shape-ceilings.json exists (the sample is installed), rewrite it with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write and commit it with the feature; test:unit compares it with a build. corepack pnpm check:bundle checks the budget.", " public/release-manifest.json (the dev server's manifest) now names the feature's contract package; commit it with the feature.", + " Two feature branches change the same lines of these files. On a merge conflict, take either side and run the command again:", + ...FEATURE_TRACKED_FILE_REWRITES.map((file) => ` ${file.path}: ${file.command}`), " The registry baseline does not change: new routes, operations, schemas and invalidation topics are additive.", ]; return `${lines.join("\n")}\n`; diff --git a/scripts/lib/removal-fixture.ts b/scripts/lib/removal-fixture.ts index efbbf9b3..8c6dd9e9 100644 --- a/scripts/lib/removal-fixture.ts +++ b/scripts/lib/removal-fixture.ts @@ -70,6 +70,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TARGETS = Object.freeze([ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([ "tests/unit/changelog-review-ids.test.ts", "tests/unit/documentation-readiness.test.ts", + // 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md. + "tests/unit/feature-tracked-files.test.ts", ] as const); /** The tests a fixture copied from `copyTargets` cannot run. */ diff --git a/tests/unit/feature-tracked-files.test.ts b/tests/unit/feature-tracked-files.test.ts new file mode 100644 index 00000000..c9e3ba33 --- /dev/null +++ b/tests/unit/feature-tracked-files.test.ts @@ -0,0 +1,58 @@ +import { readFile } from "node:fs/promises"; + +import { describe, expect, it } from "vitest"; + +import { FEATURE_TRACKED_FILE_REWRITES } from "../../scripts/create-feature.ts"; + +/** + * 1105/16-01. Adding a feature changes two tracked template files: the dev + * server's manifest (`create:feature` rewrites it) and, while the sample is + * installed, the initial JavaScript record (rewritten by command). The 03 + * manual's section A said the command writes two files outside the feature + * folder and named neither, the canonical table in starter-experience.md + * had neither, and nothing said what to do when two feature branches change + * the same `setDigest` line. The documents name each file with the command + * that rewrites it, which is also how a merge conflict on it is resolved. + */ +function between(text: string, start: string, end: string): string { + const from = text.indexOf(start); + const to = text.indexOf(end, from + start.length); + if (from < 0 || to < 0) throw new Error(`no section from "${start}" to "${end}"`); + return text.slice(from, to); +} + +describe("tracked files a feature changes (1105/16-01)", () => { + it("lists the generator's tracked rewrites", () => { + expect(FEATURE_TRACKED_FILE_REWRITES.map((file) => file.path)).toEqual([ + "public/release-manifest.json", + "config/scale/feature-shape-ceilings.json", + ]); + }); + + it("names each file and its rewrite command in the 03 manual's section A", async () => { + const section = between( + await readFile("docs/manual/03-outside-feature-folder.md", "utf8"), + "## A. 생성 명령이 만든다", + "## B. ", + ); + for (const file of FEATURE_TRACKED_FILE_REWRITES) { + expect(section, file.path).toContain(file.path); + expect(section, file.path).toContain(file.command); + } + expect(section).toMatch(/충돌/u); + }); + + it("names each file and its rewrite command in the canonical table", async () => { + const table = between( + await readFile("docs/architecture/starter-experience.md", "utf8"), + "Files outside the feature directory.", + "The central catalogs", + ); + for (const file of FEATURE_TRACKED_FILE_REWRITES) { + const row = table.split("\n").find((line) => line.startsWith("|") && line.includes(file.path)); + expect(row, file.path).toBeDefined(); + expect(row, file.path).toContain(file.command); + expect(row, file.path).toMatch(/merge conflict/u); + } + }); +});