docs(manual): 기능마다 바뀌는 추적 파일 둘과 충돌 처리 명령을 적는다

문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다.
create:feature가 public/release-manifest.json(dev server manifest)의
setDigest·packages를 다시 쓰고, 참조 기능이 있는 동안은 초기 JS 기록
(config/scale/feature-shape-ceilings.json initialJavascript)을 명령으로 다시
써야 한다. 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘"(context 선언,
a11y 기록)이라고만 적고, 정본 표(starter-experience.md "Adding a feature")에도
두 파일이 없다. 기능 브랜치 둘은 같은 setDigest 줄을 다른 값으로 바꿔
충돌하는데, 어떻게 푸는지는 test:unit 실패 문구에만 있다.

고른 방법(리뷰 대안 (a)): 문서와 생성 출력에 두 파일, 쓰는 주체, 다시 쓰는
명령, 충돌 처리("아무 쪽이나 고르고 명령을 다시 돌린다")를 적는다.
- scripts/create-feature.ts에 FEATURE_TRACKED_FILE_REWRITES(경로·명령)를
  두고 생성 출력이 충돌 처리 줄에 쓴다.
- 03 A절에 표와 충돌 단락, "기능을 지울 때"에 초기 JS 기록 재작성, 정본 표에
  두 행, 01 1단계 흐름에 manifest 재작성 줄을 더했다.
- 새 단위 테스트가 그 상수의 파일·명령이 03 A절과 정본 표에 있는지 본다.
초기 JS 기록과 그 측정 스크립트 경로는 참조 기능과 함께 지워지므로 문서에서
백틱 없이 적었다(performance-evidence.md와 같은 규칙, 제거 드릴의
verify:documentation).
버린 대안(이번에 하지 않음, 결정 대기):
- (b) dev manifest를 생성 파일로 두고(.gitignore) dev·Playwright 시작 전에
  만들기: 커밋 줄이 사라지지만 dev 스크립트와 Playwright webServer 명령을
  바꿔야 한다. Playwright 설정은 다른 작업(12-04)이 고치는 중이다.
- (d) 초기 JS 기록이 템플릿 자신의 값만 담게 측정에서 설치된 제품 기능을
  빼기: 측정 스크립트가 어떤 기능이 템플릿 것인지 알아야 한다.

위험·한계: 충돌 자체는 남는다. 두 기능 브랜치를 합칠 때 사람이 명령을 다시
돌려야 한다. 완료 기준의 둘째 길("03 A절·정본 표가 두 파일과 충돌 처리
명령을 적는다")만 채운다. 실제 두 브랜치 git merge로 재현하지 않았다.
테스트는 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴에서는 돌지
않는다(`scripts/lib/removal-fixture.ts`의 문서 테스트 목록).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-tracked-files.test.ts
corepack pnpm verify:documentation
corepack pnpm test:realtime-removal

Refs: 1105/16-01
This commit is contained in:
DongHyeonka
2026-11-06 02:12:06 +09:00
parent f600e6b132
commit 6d084cf6a2
6 changed files with 103 additions and 2 deletions
+2
View File
@@ -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>/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 |
+3
View File
@@ -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 <context id>`: 0단계에서 기존 context를 골랐을 때만 준다.
+15 -2
View File
@@ -19,7 +19,7 @@
## A. 생성 명령이 만든다
`corepack pnpm create:feature`가 쓰는 폴더 밖 파일은 둘이다. 있는 파일은 덮어쓰지 않는다.
`corepack pnpm create:feature`가 새로 만드는 폴더 밖 파일은 둘이다. 있는 파일은 덮어쓰지 않는다. 이미 있는 추적 파일 중 다시 쓰는 것은 아래 "기능마다 바뀌는 템플릿 추적 파일"에 있다.
- `src/contexts/<context>/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="<id> removed" corepack pnpm update:registry-baseline
+23
View File
@@ -1691,6 +1691,27 @@ async function readInstalledFacts(root: string): Promise<InstalledFacts> {
});
}
/**
* 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 <id> [--context <context id>] [--with-create [--keyed]] " +
"[--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>]";
@@ -1752,6 +1773,8 @@ function report(plan: FeaturePlan): string {
" A failing gate's log is artifacts/quality/gates/FE-GATE-<NNN>.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`;
+2
View File
@@ -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. */
+58
View File
@@ -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);
}
});
});