fix(docs): 지운 템플릿 기능의 경로를 문서 검사가 요구하지 않는다
문제 CHANGELOG "먼저 할 일" 6단계는 예제를 지운 제품(tech-log)에게 예제 기능 폴더와 그 context를 지우라고 한다. 그런데 starter-experience.md가 그 세 폴더를 백틱 경로로 적어서, 지운 사본에서 verify:documentation과 FE-GATE-005의 documentation-readiness "passes the documents as they are"가 "starter-experience.md names paths that do not exist"로 실패한다(리뷰 14-R1). 그 문서가 안내한 드릴(test:sample-removal --feature=platform-examples-feature)도 같은 문서 검사와, 예제 기능 ID를 적은 tests/unit/hosting-probe.test.ts 때문에 잔여 검사에서 실패한다. PRODUCT.md는 예제 화면에 제거 드릴이 없다고 적는다. 지운 제품이 템플릿 문서를 고치면 동기화마다 그 줄이 충돌한다. 고른 방법 - 문서 검사는 scripts/lib/removable-template-features.ts의 기능마다, 그 기능이 설치돼 있으면(src/features/<id>/feature-module.ts가 있으면) 그 경로·script를 지금처럼 검사하고, 아니면 그 기능이 가진 경로(기능·테스트 폴더, context, 전용 파일)와 script를 없어도 되는 것으로 본다. 폴더가 아니라 feature-module.ts를 보는 것은 tech-log가 참조 기능 폴더를 계약 파일만 남긴 채 NOT_A_FEATURE로 두기 때문이다(CHANGELOG 옮기는 법 1). 목록에 없는 폴더(오타)는 그대로 실패한다. 지운 기능이 있으면 stdout에 그 ID를 적는다. - tests/unit/hosting-probe.test.ts의 FEATURE_OVERRIDES 키를 테스트 전용 기능 ID(fixture-feature)로 바꾼다. probe는 키 이름을 보지 않는다. - 새 테스트 tests/unit/template-feature-removal-documents.test.ts: 저장소 사본에서 기능마다 그 경로를 지우고 색인을 다시 만든 뒤 사본의 verify:documentation이 통과한다. 사본의 코드로 경로를 찾으므로 실제로 지운 상태다. 기능 ID는 목록에서 읽어 테스트에 적지 않는다(제거 드릴의 잔여 검사). 설치된 기능 아래의 없는 경로와 목록에 없는 폴더는 여전히 실패하는 것도 본다. 문서를 읽으므로 REMOVAL_FIXTURE_DOCUMENT_TESTS에 더했다. - PRODUCT.md, starter-experience.md(지우는 법과 문서 검사 규칙), docs/README.md 1절 검사 설명, CHANGELOG 6단계(테스트 폴더, generate:feature-index, 드릴, 두 절을 함께 받을 것)를 고쳤다. - 버린 대안: (a) 세 경로를 백틱 없이 적기(1103/14-04 방식). 검사가 또 좁아진다(1105/14-03). (b) 모든 src/features/<dir> 아래 경로를 폴더가 없으면 통과시키기. 기능 폴더 이름 오타가 조용히 지나간다. (c) FE-GATE-020에 예제 기능 드릴을 더하기. job이 약 5분 는다. 문서 쪽은 새 unit 테스트가 merge 단계에서 본다. 위험·한계 - 새 테스트는 저장소 사본을 두 번 만든다(기능마다 cp·색인·검사). test:unit 시간이 몇 초 는다. 드릴이 test:all에서 이 파일을 다시 돈다. - 예제 기능 드릴 전체(test:all, build 등)는 이 커밋에서 돌리지 않았다. 알려진 남은 실패는 e2e·visual spec이 예제 화면을 여는 것이고 드릴 밖이다. - RED에서 새 테스트는 앞 커밋의 목록 모듈을 import하므로 그대로 돈다. 검증 - desktop batch에서 확인: node scripts/run-vitest.ts run tests/unit/template-feature-removal-documents.test.ts tests/unit/hosting-probe.test.ts tests/unit/removal-fixture.test.ts tests/unit/documentation-readiness.test.ts, corepack pnpm verify:documentation, corepack pnpm test:sample-removal -- --feature=platform-examples-feature Refs: 1105/14-01
This commit is contained in:
@@ -241,12 +241,15 @@ describe("SPA fallback and worker script surfaces (1101/13-04)", () => {
|
||||
});
|
||||
|
||||
// FE-RB-001 changes the two emergency switches without a rebuild; the
|
||||
// probe after it must still pass.
|
||||
// probe after it must still pass. 1105/14-01: the feature ID is the
|
||||
// test-only one (tests/helpers/fixture-feature.tsx). It named the example
|
||||
// screens' feature, so a copy that deleted them as the CHANGELOG says kept
|
||||
// this file as residue and failed that feature's removal drill.
|
||||
it("passes a host whose config.json differs only in the emergency switches", async () => {
|
||||
const switched = JSON.stringify({
|
||||
...JSON.parse(CONFIG),
|
||||
CAPABILITY_OVERRIDES: { realtime: "DISABLED" },
|
||||
FEATURE_OVERRIDES: { "platform-examples-feature": false },
|
||||
FEATURE_OVERRIDES: { "fixture-feature": false },
|
||||
});
|
||||
expect(
|
||||
await failed({ ...RELEASE, "/__probe/deep-link": [200, INDEX], "/config.json": [200, switched] }),
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { existsSync } from "node:fs";
|
||||
import { cp, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts";
|
||||
import {
|
||||
REMOVABLE_TEMPLATE_FEATURES,
|
||||
removableTemplateFeaturePaths,
|
||||
} from "../../scripts/lib/removable-template-features.ts";
|
||||
import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts";
|
||||
|
||||
/**
|
||||
* 1105/14-01. The CHANGELOG tells a product (tech-log) to delete the example
|
||||
* screens' feature, and the template's own documents name that feature's
|
||||
* folders. A copy that deleted them failed verify:documentation and the
|
||||
* FE-GATE-005 copy of it ("passes the documents as they are"), and only the
|
||||
* reference sample's removal was ever tried. The features come from
|
||||
* scripts/lib/removable-template-features.ts, so no feature ID is written
|
||||
* here: the removal drills refuse a test that still names the removed one.
|
||||
*/
|
||||
const CHECKER = "scripts/verify-documentation-readiness.ts";
|
||||
/** What verify:documentation reads besides the code. */
|
||||
const DOCUMENTS = Object.freeze(["README.md", "CHANGELOG.md", "docs", "artifacts/tests/a11y-manual"]);
|
||||
|
||||
/**
|
||||
* Runs verify:documentation in a copy of the repository without `removed`,
|
||||
* as a product that deleted it has it. The code facts are the copy's:
|
||||
* tests/unit/documentation-readiness.test.ts copies only the documents and
|
||||
* looks paths up in this repository, where nothing is deleted. The feature
|
||||
* index is generated again, as the product does after the deletion.
|
||||
*/
|
||||
async function verifyWithout(removed: readonly string[]) {
|
||||
const parent = await mkdtemp(path.join(tmpdir(), "template-feature-removal-"));
|
||||
const root = path.join(parent, "frontend");
|
||||
try {
|
||||
for (const entry of [...REMOVAL_FIXTURE_COPY_TARGETS, ...DOCUMENTS]) {
|
||||
// A drill runs this test in a copy that has already lost some of them.
|
||||
if (!existsSync(entry)) continue;
|
||||
await cp(entry, path.join(root, entry), {
|
||||
recursive: true,
|
||||
filter: (source) => !source.includes(`${path.sep}.generated`),
|
||||
});
|
||||
}
|
||||
await linkFixtureNodeModules(root);
|
||||
for (const entry of removed) await rm(path.join(root, entry), { recursive: true, force: true });
|
||||
const generated = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
expect(generated.status, generated.stderr).toBe(0);
|
||||
return spawnSync(process.execPath, [path.join(root, CHECKER)], { cwd: root, encoding: "utf8" });
|
||||
} finally {
|
||||
await rm(parent, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Runs this repository's verify:documentation on a copy of the documents
|
||||
* with `mutate` applied to `document`; the code facts are this repository's.
|
||||
*/
|
||||
async function verifyDocuments(document: string, mutate: (text: string) => string) {
|
||||
const parent = await mkdtemp(path.join(tmpdir(), "template-feature-documents-"));
|
||||
const root = path.join(parent, "frontend");
|
||||
try {
|
||||
// The pin says which commit of the paired backend the documents describe.
|
||||
const inputs = ["README.md", "docs", "artifacts/tests/a11y-manual", "config/contracts/backend-contract-pin.json"];
|
||||
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" });
|
||||
} finally {
|
||||
await rm(parent, { recursive: true, force: true });
|
||||
}
|
||||
}
|
||||
|
||||
describe("verify:documentation after a template feature is deleted (1105/14-01)", () => {
|
||||
it.each(REMOVABLE_TEMPLATE_FEATURES.map((feature) => [feature.featureId, feature] as const))(
|
||||
"passes in a copy without %s",
|
||||
async (_featureId, feature) => {
|
||||
const result = await verifyWithout(removableTemplateFeaturePaths(feature));
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
},
|
||||
120_000,
|
||||
);
|
||||
|
||||
// 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.
|
||||
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 = [
|
||||
...REMOVABLE_TEMPLATE_FEATURES.filter((feature) =>
|
||||
existsSync(`src/features/${feature.featureId}/feature-module.ts`),
|
||||
).map((feature) => `src/features/${feature.featureId}/no-such-module.ts`),
|
||||
"src/features/no-such-template-feature/feature-module.ts",
|
||||
];
|
||||
const result = await verifyDocuments(
|
||||
document,
|
||||
(text) => `${text}\n${missing.map((file) => `- \`${file}\``).join("\n")}\n`,
|
||||
);
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(`${document} names paths that do not exist:`);
|
||||
for (const file of missing) expect(result.stderr).toContain(file);
|
||||
}, 60_000);
|
||||
});
|
||||
Reference in New Issue
Block a user