fix(dev): dev manifest를 기능 생성·제거 때 다시 쓰는 커밋 파일로 둔다

문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.

고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
  그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
  둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
  돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
  절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
  contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
  Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
  server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
  같은 조건을 dev만 따로 두게 된다.

위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
  test:unit이 그 상태를 이름과 명령으로 알린다.

검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
  check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
  뒤 깨끗한 clone에서 돈다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
This commit is contained in:
DongHyeonka
2026-11-05 03:30:56 +09:00
parent 0eba0821bd
commit 799ab7f667
11 changed files with 69 additions and 98 deletions
+1 -1
View File
@@ -182,7 +182,7 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
- `config/testing/risk-coverage.json`에서 그 기능을 가리키는 행
- 그 기능만 쓰던 제품 capability, 제품 인증 프로필, 계약 패키지 의존성
그다음 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다.
그다음 dev manifest(`public/release-manifest.json`)의 계약 패키지를 `node scripts/write-dev-release-manifest.ts`로 다시 쓰고, 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다.
```bash
REGISTRY_BASELINE_OWNER=<담당> REGISTRY_BASELINE_REASON="<id> removed" corepack pnpm update:registry-baseline
+3
View File
@@ -140,8 +140,11 @@ create:feature warning: no --package was given, so src/features/<id>/contracts/<
rm -r src/features/<id> tests/features/<id> artifacts/tests/a11y-manual/<ROUTE_ID>.md
rm -r src/contexts/<base>-context # 새 context를 만들었을 때만
corepack pnpm generate:feature-index
node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의 계약 패키지를 뺀다
```
생성 명령은 `public/release-manifest.json`(dev server가 내주는 manifest)의 `contractSet`에 기능의 계약 패키지를 더한다. 기능과 함께 커밋한다. 낡으면 `tests/unit/dev-release-manifest.test.ts`가 다시 쓰는 명령을 말하며 실패하고, `corepack pnpm dev`는 `CONTRACT_SET_PACKAGE_MISSING`·`CONTRACT_SET_PACKAGE_UNEXPECTED`로 부팅하지 못한다.
## 이 명령을 지키는 검사
- `tests/unit/create-feature.test.ts` (`test:unit`, FE-GATE-005)
+1
View File
@@ -81,6 +81,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
| 부팅 화면 `CONTRACT_SET_PACKAGE_MISSING` / `CONTRACT_SET_PACKAGE_UNEXPECTED`(`corepack pnpm dev`, dev server를 쓰는 브라우저 테스트) | dev manifest `public/release-manifest.json`의 계약 패키지가 설치된 기능과 다르다. 기능을 손으로 더하거나 지웠다 | `node scripts/write-dev-release-manifest.ts`로 다시 쓰고 커밋한다. `tests/unit/dev-release-manifest.test.ts`가 같은 어긋남을 잡는다 |
| `Invalid or duplicate schema definition: <schemaId>` | 스키마 ID 중복 또는 메타 형식 | `contracts/<base>-schema-metadata.ts`. 접두어를 붙인다 |
| `duplicate operation: <operationId>` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/<base>-contract-contribution.ts`. 접두어를 붙인다 |
| `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`, `problemSchema`도 같은 꼴. 실패 본문 행은 `boundary: "api-problem"`) | `contracts/<base>-schema-metadata.ts` |
+11
View File
@@ -1751,6 +1751,7 @@ function report(plan: FeaturePlan): string {
` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`,
" 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).",
" 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.",
" The registry baseline does not change: new routes, operations, schemas and invalidation topics are additive.",
];
return `${lines.join("\n")}\n`;
@@ -1783,6 +1784,16 @@ async function main(): Promise<void> {
await rollBack(created);
fail(`the feature index generator rejected the feature, nothing was kept:\n${generated.stderr}`);
}
// 1103 X2 #3. The dev server's release manifest names the installed
// contract packages; the new feature declares one.
const manifest = spawnSync(
process.execPath,
[path.join(scriptDirectory, "write-dev-release-manifest.ts")],
{ cwd: root, encoding: "utf8" },
);
if (manifest.status !== 0) {
fail(`public/release-manifest.json could not be rewritten:\n${manifest.stderr}`);
}
process.stdout.write(report(plan));
if (plan.placeholder) {
process.stderr.write(
-40
View File
@@ -1,40 +0,0 @@
import { execFileSync } from "node:child_process";
import path from "node:path";
import type { Plugin } from "vite";
/**
* Serve only. The dev server answers the runtime's release-manifest request
* with scripts/write-dev-release-manifest.ts's output instead of the committed
* placeholder, so a feature that `create:feature` just added boots in
* `corepack pnpm dev` and in the dev-server browser tests. The manifest is
* built once in a child process at server start, because it imports the
* installed feature declarations, which this config must not load, and kept
* in memory: no file is written for the server's watcher to see. A build never
* uses it: the built manifest comes from scripts/generate-build-manifest.ts.
*/
export function devReleaseManifestPlugin(repositoryRoot = process.cwd()): Plugin {
return {
name: "frontend-dev-release-manifest",
// Vitest also starts Vite in serve mode; tests never fetch the manifest
// from a server, so they skip the child process.
apply: (_config, env) => env.command === "serve" && !process.env["VITEST"],
configureServer(server) {
const manifest = execFileSync(
process.execPath,
[path.join(repositoryRoot, "scripts/write-dev-release-manifest.ts")],
{ cwd: repositoryRoot, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] },
);
server.middlewares.use((request, response, next) => {
const pathname = new URL(request.url ?? "/", "http://dev.invalid").pathname;
if (request.method !== "GET" || !pathname.endsWith("/release-manifest.json")) {
next();
return;
}
response.setHeader("content-type", "application/json");
response.setHeader("cache-control", "no-store");
response.end(manifest);
});
},
};
}
@@ -46,8 +46,6 @@ const BUILD_INPUTS = [
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/vite-module-inventory.ts",
// vite.config.ts imports it (the dev-only release-manifest plugin).
"scripts/lib/dev-release-manifest.ts",
] as const;
// Platform-owned names that only happen to contain "reference".
const PLATFORM_TOKENS = [
+9
View File
@@ -387,6 +387,15 @@ try {
})) {
throw new Error("Registry baseline failed to update after sample removal");
}
// 1103 X2 #3. The dev server's manifest names the installed contract
// packages; the removed feature's is gone.
const devManifest = spawnSync(process.execPath, ["scripts/write-dev-release-manifest.ts"], {
cwd: fixtureRoot,
stdio: "inherit",
});
if (devManifest.status !== 0) {
throw new Error("public/release-manifest.json failed to update after the removal");
}
// 1103 X2 #2. config/scale/feature-shape-ceilings.json records the initial
// JavaScript of the features installed now, and test:unit compares a build
// with it. A product re-records it when it adds a feature; removing that
+13 -12
View File
@@ -1,24 +1,25 @@
import { readFile } from "node:fs/promises";
import { readFile, writeFile } from "node:fs/promises";
import { buildContractSet } from "./generate-contract-set.ts";
export const DEV_RELEASE_MANIFEST = "public/release-manifest.json";
/**
* The release manifest the dev server serves: the committed placeholder
* (public/release-manifest.json) with the contract set of the features
* installed now. Boot checks that set against the installed declarations, so
* a placeholder with a fixed set refused every app with one more feature
* (CONTRACT_SET_PACKAGE_MISSING) until someone edited it by hand.
* The release manifest the dev server serves (public/release-manifest.json)
* with the contract set of the features installed now. Boot checks that set
* against the installed declarations, so a placeholder with a fixed set
* refused every app with one more feature (CONTRACT_SET_PACKAGE_MISSING) in
* `corepack pnpm dev` and in the dev-server browser tests. `create:feature`
* and the feature removal drill rewrite it; a project commits it with the
* feature, as it does the registry baseline. A build never serves it: the
* built manifest comes from scripts/generate-build-manifest.ts.
*/
export async function devReleaseManifest(
source = "public/release-manifest.json",
): Promise<string> {
export async function devReleaseManifest(source = DEV_RELEASE_MANIFEST): Promise<string> {
const manifest = JSON.parse(await readFile(source, "utf8")) as Record<string, unknown>;
manifest["contractSet"] = buildContractSet();
return `${JSON.stringify(manifest, null, 2)}\n`;
}
// Printed, not written: a file the dev server's watcher picks up after the
// server started could reload a page while it is booting.
if (process.argv[1]?.endsWith("write-dev-release-manifest.ts")) {
process.stdout.write(await devReleaseManifest());
await writeFile(DEV_RELEASE_MANIFEST, await devReleaseManifest(), "utf8");
}
+22 -39
View File
@@ -1,56 +1,39 @@
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { readFile } from "node:fs/promises";
import { afterEach, describe, expect, it } from "vitest";
import { describe, expect, it } from "vitest";
import { buildContractSet } from "../../scripts/generate-contract-set.ts";
import { devReleaseManifest } from "../../scripts/write-dev-release-manifest.ts";
import {
DEV_RELEASE_MANIFEST,
devReleaseManifest,
} from "../../scripts/write-dev-release-manifest.ts";
/**
* 1103 X2. `create:feature` declares a contract package; the dev server used
* to serve the committed placeholder with a fixed empty set, so the app it
* had just generated refused to boot in `corepack pnpm dev`.
* 1103 X2 #3. `create:feature` declares a contract package; the committed
* dev manifest used to keep a fixed set, so the app it had just generated
* refused to boot in `corepack pnpm dev` (CONTRACT_SET_PACKAGE_MISSING).
*/
describe("dev release manifest", () => {
let directory: string | undefined;
afterEach(async () => {
if (directory) await rm(directory, { recursive: true, force: true });
directory = undefined;
it("names the contract set of the installed features", async () => {
const committed = JSON.parse(await readFile(DEV_RELEASE_MANIFEST, "utf8")) as Record<
string,
unknown
>;
expect(
committed["contractSet"],
`${DEV_RELEASE_MANIFEST} is stale; rewrite it with node scripts/write-dev-release-manifest.ts and commit it with the feature`,
).toEqual(JSON.parse(JSON.stringify(buildContractSet())));
});
it("serves the placeholder with the contract set of the installed features", async () => {
directory = await mkdtemp(path.join(tmpdir(), "dev-release-manifest-"));
const source = path.join(directory, "release-manifest.json");
await writeFile(
source,
JSON.stringify({
schemaVersion: 2,
buildId: "local-build",
contractSet: {
setAlgorithm: "CA_CONTRACT_SET_V1",
setDigest: "sha256:stale",
packages: [{ packageId: "@org-contracts/removed" }],
},
}),
);
const written = JSON.parse(await devReleaseManifest(source)) as Record<string, unknown>;
expect(written["buildId"]).toBe("local-build");
expect(written["contractSet"]).toEqual(JSON.parse(JSON.stringify(buildContractSet())));
});
it("keeps every other field of the committed placeholder", async () => {
// Whatever features are installed (a product's, or a drill's generated
// one): only the contract set may differ from the placeholder.
it("changes only the contract set", async () => {
const { contractSet, ...written } = JSON.parse(await devReleaseManifest()) as Record<
string,
unknown
>;
const { contractSet: _placeholderSet, ...placeholder } = JSON.parse(
await readFile("public/release-manifest.json", "utf8"),
const { contractSet: _committedSet, ...committed } = JSON.parse(
await readFile(DEV_RELEASE_MANIFEST, "utf8"),
) as Record<string, unknown>;
expect(written).toEqual(placeholder);
expect(written).toEqual(committed);
expect(contractSet).toEqual(JSON.parse(JSON.stringify(buildContractSet())));
});
});
@@ -28,8 +28,6 @@ const BUILD_INPUTS = [
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/vite-module-inventory.ts",
// vite.config.ts imports it (the dev-only release-manifest plugin).
"scripts/lib/dev-release-manifest.ts",
] as const;
// Feature ids stay: the generated index still declares them so the platform
// overview reports NOT_INSTALLED. Their modules and route ids go.
+9 -2
View File
@@ -6,7 +6,6 @@ import { defineConfig, loadEnv } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { devReleaseManifestPlugin } from "./scripts/lib/dev-release-manifest.ts";
import { viteModuleInventoryPlugin } from "./scripts/lib/vite-module-inventory.ts";
import { ENV_REGISTRY } from "./src/contracts/env.ts";
@@ -176,9 +175,17 @@ export default defineConfig(({ command, mode }) => {
assertRuntimeConfigUnderBase(process.env, base);
return {
base,
plugins: [react(), tailwindcss(), viteModuleInventoryPlugin(), devReleaseManifestPlugin()],
plugins: [react(), tailwindcss(), viteModuleInventoryPlugin()],
// Development keeps the router's warnings.
resolve: command === "build" ? { alias: reactRouterProductionAliases(process.cwd()) } : {},
server: {
watch: {
// Test and build output, never app source. Playwright writes trace
// resources (.html) under artifacts/ while a dev-server test runs;
// watched, each one made Vite reload every open page.
ignored: ["**/artifacts/**", "**/dist/**", "**/.tmp/**"],
},
},
build: {
manifest: true,
sourcemap: false,