From b45d6a03db7ab71abd5f9d6369d6140ee08296e1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:21:38 +0900 Subject: [PATCH] =?UTF-8?q?fix(removal):=20=EC=A0=9C=ED=92=88=20=EA=B8=B0?= =?UTF-8?q?=EB=8A=A5=20=EC=A0=9C=EA=B1=B0=20=EB=93=9C=EB=A6=B4=EC=9D=B4=20?= =?UTF-8?q?=ED=85=9C=ED=94=8C=EB=A6=BF=20=ED=85=8C=EC=8A=A4=ED=8A=B8?= =?UTF-8?q?=EC=9D=98=20=EC=98=88=EC=8B=9C=20ID=EB=A5=BC=20=EC=9E=94?= =?UTF-8?q?=EC=97=AC=EB=A1=9C=20=EC=84=B8=EC=A7=80=20=EC=95=8A=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 매뉴얼 1단계 예시 ID는 invoice-feature이고 11단계가 `test:sample-removal -- --feature=invoice-feature`로 그 기능을 지운다. 드릴은 제품 기능의 잔여를 src·tests 모든 파일에서 기능 ID의 대소문자 무시 부분 문자열로 찾았다. 템플릿 소유 tests/unit/create-feature.test.ts가 같은 예시 ID를 데이터로 51번 쓰므로, 다른 검사가 모두 통과해도 `fixture-id-residue: residue: tests/unit/create-feature.test.ts`로 rc=1이었다 (리뷰 16-R1). errors.md의 안내는 그 템플릿 파일을 고치라는 것이었다. notice-feature, orders-feature, shop-feature 같은 이름도 같은 충돌이 난다. 고른 방법: 제품 기능의 잔여 판정을 scripts/lib/feature-residue.ts의 productFeatureResidue로 옮기고 범위를 나눈다. - src: 지금처럼 경로나 내용에 기능 ID·폴더 이름이 있으면 잔여. 플랫폼 소스는 제품 기능을 이름으로 부르지 않으므로, 남은 이름은 타입 검사가 못 보는 참조(카탈로그 키, 런타임 오버라이드, 링크)다. - tests: 파일 이름에 기능 ID가 있거나, 기능의 src/features// 또는 tests/features//에서 import(동적 import, vi.mock 포함)하는 파일만 잔여. 테스트 본문에 ID를 글자로 적은 것은 세지 않는다. 지운 기능에 기대는 테스트는 같은 드릴의 test:all이 잡는다. 참조 샘플(reference-feature)은 템플릿이 모든 파일을 가지므로 기존 넓은 패턴을 그대로 쓴다. 빌드 산출물(dist) 잔여 검사도 그대로다. 단위 테스트: 저장소 자체(create-feature.test.ts 포함)를 invoice-feature로 훑으면 잔여 0, src/contracts에 ID를 남긴 파일·이름에 ID가 있는 e2e spec·기능 폴더 import는 잔여, 테스트 본문의 예시 데이터는 잔여 아님. 매뉴얼 01 11단계와 errors.md의 판정 문장·안내(템플릿 파일이 나오면 고치지 말고 템플릿에 알린다)를 고쳤다. 버린 대안: - 제거 전에 한 번 훑어 이미 걸리던 파일을 제외: src/contracts에 남긴 잔여도 제거 전부터 ID를 담고 있으므로 같이 빠진다(완료 기준 둘째를 못 지킨다). - 템플릿 테스트의 예시 ID를 예약 접두어로 바꾸기: 부분 문자열 검색이면 접두어를 붙여도 걸리고, create-feature.test.ts의 파생 이름 기대값 수십 곳을 함께 바꿔야 한다. - 생성 명령이 템플릿 테스트에 나오는 ID를 거절: 목록이 따로 낡는다. 위험·한계: tests 안에서 기능 ID를 글자로만 담은 진짜 잔여(예: 기능을 import하지 않고 경로 문자열만 적은 테스트)는 이제 잔여로 나오지 않는다. 그런 테스트가 지운 기능에 기대면 test:all이 실패하고, 기대지 않으면 해가 없다. src 쪽 부분 문자열 검색은 그대로라 items 같은 짧은 ID는 플랫폼 소스의 글자에 여전히 걸릴 수 있다(이번 범위 밖). 실제 드릴 실행(198초)은 단위 테스트로 대신하지 못한다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts 16-R1과 같은 순서: create:feature invoice-feature --with-create --keyed 뒤 corepack pnpm test:sample-removal -- --feature=invoice-feature (rc=0 기대), 그리고 src/contracts/invoice-leftover.ts에 "invoice-feature"를 남긴 변이에서 rc=1(fixture-id-residue) 기대 Refs: 1105/16-04 --- docs/manual/01-add-a-feature.md | 8 ++-- docs/manual/reference/errors.md | 2 +- scripts/lib/feature-residue.ts | 62 +++++++++++++++++++++++++ scripts/test-sample-removal.ts | 19 +++++--- tests/unit/feature-residue.test.ts | 73 ++++++++++++++++++++++++++++++ 5 files changed, 154 insertions(+), 10 deletions(-) create mode 100644 scripts/lib/feature-residue.ts create mode 100644 tests/unit/feature-residue.test.ts diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 031ae443..fc962ae0 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -639,7 +639,8 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature 기능 폴더를 가리키는 커버리지 정책 행, owner가 기능 ID인 증거 정책 행을 지움 → 레지스트리 기준선을 다시 찍음 (빼는 변경은 breaking이라서) → 타입·아키텍처·레지스트리·테스트·커버리지·CI 계약·빌드 게이트 - → src와 tests에 기능 ID나 폴더 이름이 남았는지 찾음 + → 지운 기능을 가리키는 파일이 남았는지 찾음 + (src: 기능 ID·폴더 이름을 담은 파일, tests: 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일) ``` ① **정할 것**: 없음. 확인 단계다. @@ -651,9 +652,10 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature ③ **잡는 검사 / 못 잡는 것** -- 남은 파일이 기능 ID나 폴더 이름을 담고 있으면 실패한다. +- 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일이다. - 메시지: ` removal failed:` 다음 줄 `fixture-id-residue: residue: ` -- **못 잡음**: 기능 ID를 담지 않은 폴더 밖 파일. 예: route ID만 적은 e2e spec, `artifacts/tests/a11y-manual/.md`. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. + - 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다. +- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID만 적은 e2e spec, `artifacts/tests/a11y-manual/.md`. `tests` 안에서 기능 ID를 글자로만 적은 테스트도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index c0461617..d1b3ed55 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -194,6 +194,6 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | 메시지 | 원인 | 고칠 곳 | |---|---|---| -| ` removal failed:` 다음 `fixture-id-residue: residue: ` (`test:sample-removal`) | 기능을 지운 뒤에도 `src`·`tests`에 기능 ID를 담은 파일이 남았다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능 ID를 담지 않게 한다 | +| ` removal failed:` 다음 `fixture-id-residue: residue: ` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features//`, `tests/features//`)에서 import하는 파일이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 | | `No installed feature declares FEATURE_MODULE_ID ""` | `--feature=`에 없는 기능 ID | 명령 인자 | | `feature scaffold failed:` 다음 `: ` (`test:feature-scaffold`) | 생성한 기능이 게이트 하나를 통과하지 못했다 | `scripts/create-feature.ts`의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 | diff --git a/scripts/lib/feature-residue.ts b/scripts/lib/feature-residue.ts new file mode 100644 index 00000000..2bcfc934 --- /dev/null +++ b/scripts/lib/feature-residue.ts @@ -0,0 +1,62 @@ +import { readdir, readFile } from "node:fs/promises"; +import path from "node:path"; + +/** + * 1105/16-04. What a product feature leaves behind after + * `test:sample-removal -- --feature=` deleted its folders, in the copy the + * drill made. + * + * - `src/`: any file whose path or text still names the feature ID or its + * folder. Platform source never names a product feature, so a name left + * there is a reference the type checker cannot see (a catalog key, a + * runtime override, a link). + * - `tests/`: a file named after the feature, or one that imports from the + * feature's `src/features//` or `tests/features//`. The test + * text is not searched for the bare name: the template's own tests use + * example IDs as data (`tests/unit/create-feature.test.ts` writes + * `invoice-feature`, the manual's example, 51 times), and the drill flagged + * them as residue of a product feature that took that name. A test that + * still depends on the removed feature fails `test:all`, which the drill + * runs. + * + * The reference sample keeps its own, wider pattern in + * scripts/test-sample-removal.ts: the template owns all of its files. + */ +function escapeRegExp(value: string): string { + return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"); +} + +async function filesUnder(directory: string): Promise { + const entries = await readdir(directory, { withFileTypes: true }).catch(() => []); + const nested = await Promise.all( + entries.map((entry) => { + const target = path.join(directory, entry.name); + return entry.isDirectory() ? filesUnder(target) : Promise.resolve([target]); + }), + ); + return nested.flat(); +} + +export async function productFeatureResidue( + root: string, + featureId: string, + directory: string, +): Promise { + const names = [...new Set([featureId, directory])].map(escapeRegExp).join("|"); + const named = new RegExp(names, "iu"); + const imported = new RegExp( + String.raw`(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\bmock\s*\(\s*)["'][^"'\n]*/features/(?:${names})/`, + "u", + ); + const residue: string[] = []; + const relative = (file: string) => path.relative(root, file).split(path.sep).join("/"); + for (const file of await filesUnder(path.join(root, "src"))) { + const name = relative(file); + if (named.test(`${name}\n${await readFile(file, "utf8")}`)) residue.push(name); + } + for (const file of await filesUnder(path.join(root, "tests"))) { + const name = relative(file); + if (named.test(name) || imported.test(await readFile(file, "utf8"))) residue.push(name); + } + return residue.sort(); +} diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index 2fe4c041..d8e9e69a 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -11,6 +11,7 @@ import path from "node:path"; import { ROUTE_FEATURE_OWNER } from "../src/features/installed-feature-contracts.ts"; import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts"; +import { productFeatureResidue } from "./lib/feature-residue.ts"; import { isProductionModulePath } from "./lib/risk-coverage.ts"; import { createRemovalFixtureRoot, @@ -415,14 +416,20 @@ try { await regenerateRemovalFixtureWorkflow(fixtureRoot); const residue: string[] = []; - for (const root of ["src", "tests"]) { - for (const file of await filesBelow(path.join(fixtureRoot, root))) { - const relative = path.relative(fixtureRoot, file); - const content = await readFile(file, "utf8"); - if (extras.residue.test(`${relative}\n${content}`)) { - residue.push(relative); + if (isSample) { + for (const root of ["src", "tests"]) { + for (const file of await filesBelow(path.join(fixtureRoot, root))) { + const relative = path.relative(fixtureRoot, file); + const content = await readFile(file, "utf8"); + if (extras.residue.test(`${relative}\n${content}`)) { + residue.push(relative); + } } } + } else { + // 1105/16-04. Template tests use example feature IDs as data; only what + // still points at the removed feature counts (scripts/lib/feature-residue.ts). + residue.push(...(await productFeatureResidue(fixtureRoot, featureId, located.directory))); } const missingCommonTests: string[] = []; diff --git a/tests/unit/feature-residue.test.ts b/tests/unit/feature-residue.test.ts new file mode 100644 index 00000000..7ebbeff4 --- /dev/null +++ b/tests/unit/feature-residue.test.ts @@ -0,0 +1,73 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { afterAll, describe, expect, it } from "vitest"; + +import { productFeatureResidue } from "../../scripts/lib/feature-residue.ts"; + +/** + * 1105/16-04. The manual's example ID is `invoice-feature` (01 1단계), and + * its step 11 removes that feature with + * `test:sample-removal -- --feature=invoice-feature`. The drill searched every + * file under `src` and `tests` for the ID as a substring, so the template's + * own tests/unit/create-feature.test.ts, which writes that example ID 51 + * times as data, failed the removal (`fixture-id-residue`), and the advice + * was to edit that template file. + */ +const ID = "invoice-feature"; +const roots: string[] = []; + +afterAll(async () => { + await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); +}); + +async function fixture(files: Readonly>): Promise { + const root = await mkdtemp(path.join(tmpdir(), "feature-residue-")); + roots.push(root); + for (const [file, content] of Object.entries(files)) { + await mkdir(path.dirname(path.join(root, file)), { recursive: true }); + await writeFile(path.join(root, file), content); + } + return root; +} + +// Built at run time so this file does not itself read as an import of the +// feature when the repository is searched below. +const importOf = (target: string) => ["import { x } from", JSON.stringify(target)].join(" "); + +describe("product feature residue (1105/16-04)", () => { + it("does not count the template's own tests that name the manual's example ID", async () => { + expect(await productFeatureResidue(process.cwd(), ID, ID)).toEqual([]); + }); + + it("counts what still points at the removed feature", async () => { + const root = await fixture({ + "src/contracts/leftover.ts": `export const OWNER = "${ID}";\n`, + "src/platform/clean.ts": "export const NOTHING = 1;\n", + [`tests/e2e/${ID}.spec.ts`]: "test('opens', () => {});\n", + "tests/unit/imports-feature.test.ts": `${importOf(`../../src/features/${ID}/feature-module.ts`)};\n`, + "tests/unit/imports-feature-tests.test.ts": `${importOf(`../features/${ID}/helpers.ts`)};\n`, + "tests/unit/example-data.test.ts": `const request = { id: "${ID}" };\nconst path = "src/features/${ID}/feature-module.ts";\n`, + }); + + expect(await productFeatureResidue(root, ID, ID)).toEqual([ + "src/contracts/leftover.ts", + `tests/e2e/${ID}.spec.ts`, + "tests/unit/imports-feature-tests.test.ts", + "tests/unit/imports-feature.test.ts", + ]); + }); + + it("matches the folder name as well as the ID", async () => { + const root = await fixture({ + "src/contracts/leftover.ts": 'export const DIRECTORY = "invoices";\n', + "tests/unit/x.test.ts": `${importOf("../../src/features/invoices/index.ts")};\n`, + }); + + expect(await productFeatureResidue(root, ID, "invoices")).toEqual([ + "src/contracts/leftover.ts", + "tests/unit/x.test.ts", + ]); + }); +});