From 9edc8307b08bbdd350dfcabd9cbadc428a1d432e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:19:17 +0900 Subject: [PATCH] =?UTF-8?q?fix(features)!:=20=EA=B8=B0=EB=8A=A5=EC=9D=B4?= =?UTF-8?q?=20=EC=95=84=EB=8B=8C=20=ED=8F=B4=EB=8D=94=20=ED=91=9C=EC=8B=9C?= =?UTF-8?q?=EB=A5=BC=20NOT=5FA=5FFEATURE=EB=A1=9C=20=EB=B0=94=EA=BE=B8?= =?UTF-8?q?=EA=B3=A0=20=EC=84=A0=EC=96=B8=EA=B3=BC=20=ED=95=A8=EA=BB=98=20?= =?UTF-8?q?=EB=91=90=EB=A9=B4=20=EC=8B=A4=ED=8C=A8=ED=95=9C=EB=8B=A4=20(11?= =?UTF-8?q?03/09-09)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 src/features//NOT_INSTALLED 표시는 "기능이 아닌 샘플 폴더"라는 뜻인데, 같은 단어가 런타임 상태 "선언됐지만 빌드·FEATURE_OVERRIDES가 뺀 기능"으로도 쓰였다(product-features.ts). 생성기는 feature-module.ts를 못 읽을 때만 표시를 찾았으므로, 샘플을 졸업시키며 표시를 지우지 않으면 표시가 "설치 안 됨"이라고 말하는 채로 조용히 설치됐다. 고른 방법 - 표시 이름을 NOT_A_FEATURE로 바꾼다(local-draft-feature 파일 이름 변경). 런타임 상태 NOT_INSTALLED는 그대로 둔다. - 생성기가 표시와 feature-module.ts가 함께 있으면 둘 중 무엇을 지울지 적고 실패한다. - 옛 이름 표시는 받지 않는다. 받으면 같은 다의가 남는다. 옛 표시만 있는 폴더는 "has no feature-module.ts; … mark the directory with NOT_A_FEATURE"로 실패해 새 이름을 알려 준다. README 상태 표, starter-experience, 매뉴얼 errors·patterns 표를 맞췄다. 위험·한계 다운스트림이 자기 폴더에 NOT_INSTALLED 표시를 두었다면 생성 단계가 실패한다. 파일 이름만 바꾸면 된다. 검증 - RED: 생성기 테스트 3건(새 이름 허용, 옛 이름 거절, 동시 존재 거절)이 수정 전 실패. - generate-product-feature-index.test.ts 17건 통과. generate:feature-index 통과. verify:documentation PASS_SCOPED. eslint, tsc(node·test) 통과. BREAKING CHANGE: src/features//NOT_INSTALLED 표시 파일은 더 이상 인식되지 않는다. 같은 자리에 NOT_A_FEATURE라는 이름으로 옮긴다. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-09 --- README.md | 2 +- docs/architecture/starter-experience.md | 4 +-- docs/manual/reference/errors.md | 3 +- docs/manual/reference/patterns.md | 2 +- scripts/generate-product-feature-index.ts | 34 ++++++++++++++----- .../{NOT_INSTALLED => NOT_A_FEATURE} | 0 .../generate-product-feature-index.test.ts | 31 +++++++++++++++-- 7 files changed, 60 insertions(+), 16 deletions(-) rename src/features/local-draft-feature/{NOT_INSTALLED => NOT_A_FEATURE} (100%) diff --git a/README.md b/README.md index 43178c84..03dcf59a 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ and | `COMPOSED` | capability ledger, design documents | wired into the default production path | Default | | `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project | | `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional | -| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a `src/features//NOT_INSTALLED` marker file | not part of the build | Optional (recipe) or Experimental (feature) | +| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a declared feature the build or `FEATURE_OVERRIDES` left out. A sample directory that is no feature at all carries a `src/features//NOT_A_FEATURE` marker file instead | not part of the build | Optional (recipe) or Experimental (feature) | | `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional | | `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental | | `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported | diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 0a4512dc..204290f2 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -115,8 +115,8 @@ selected app. Every build and check script runs it first; run it yourself with `corepack pnpm generate:feature-index`. It fails, naming the file, when: - a directory under `src/features/` has no `feature-module.ts` and no - `NOT_INSTALLED` marker file (`src/features/local-draft-feature/NOT_INSTALLED` - is the one intentional example); + `NOT_A_FEATURE` marker file (`src/features/local-draft-feature/NOT_A_FEATURE` + is the one intentional example), or has both; - a feature names an undeclared context, or a context an undeclared app; - a context or app exceeds its declared budget; - `VITE_PRODUCT_FEATURES` names a feature the app does not declare. The diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 4cf83d62..7b0a813a 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -55,7 +55,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `Context belongs to undeclared app ` | `CONTEXT_APP_ID` 오타 | `src/contexts//context-module.ts` | | ` must export a literal ` | 헤더를 상수 참조나 식으로 썼다. 생성기는 글자로 읽는다 | 그 파일. `export const = "<값>";` 꼴 | | ` must export a positive integer ` | 예산 값이 정수 리터럴이 아니다 | 그 파일 | -| `src/features/ has no feature-module.ts; add one or mark the directory with NOT_INSTALLED` | 기능 폴더에 선언 파일이 없다 | `feature-module.ts`를 만들거나 `NOT_INSTALLED` 파일을 둔다 | +| `src/features/ has no feature-module.ts; add one or mark the directory with NOT_A_FEATURE` | 기능 폴더에 선언 파일이 없다 | `feature-module.ts`를 만들거나, 기능이 아닌 샘플 폴더면 `NOT_A_FEATURE` 파일을 둔다 | +| `src/features/ has both feature-module.ts and NOT_A_FEATURE; …` | 기능이 아니라고 표시한 폴더에 선언 파일이 있다 | 기능으로 설치하려면 `NOT_A_FEATURE`를 지운다. 설치하지 않으려면 `feature-module.ts`를 지운다 | | `Duplicate generated feature ids: ` | 두 폴더가 같은 `FEATURE_MODULE_ID` | 한쪽 `feature-module.ts` | | `Duplicate context id: ` | 두 폴더가 같은 `CONTEXT_MODULE_ID` | 한쪽 `context-module.ts` | | `Context feature cardinality exceeds budget ` | context의 기능 수가 예산을 넘었다 | `CONTEXT_MAX_FEATURES`, 또는 새 context | diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index c8e49e09..c6c6554e 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -99,7 +99,7 @@ const search = (q: string) => | 수정·삭제 명령 | 같은 V3 계약 (`PUT`, `PATCH`, `DELETE`) | 없음 (참조 기능은 생성 명령만 있다) | — | | 낙관적 갱신 | `useApplicationMutation`의 `optimistic` 옵션 (`application-query.ts`) | 없음 | 런타임 테스트만 | | 페이지 넘김 | `src/adapters/query-cache/index.ts`의 `createCursorPaginationRuntime` | 없음 (참조 기능은 커서 필터만, 다음 커서 없음) | 런타임 테스트만 | -| 로컬 저장(IndexedDB) | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` + `product-composition.ts` | `src/features/local-draft-feature/` (`NOT_INSTALLED`, 설치되지 않음) | 계약 테스트 | +| 로컬 저장(IndexedDB) | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` + `product-composition.ts` | `src/features/local-draft-feature/` (`NOT_A_FEATURE`, 기능이 아닌 샘플) | 계약 테스트 | ## 화면 diff --git a/scripts/generate-product-feature-index.ts b/scripts/generate-product-feature-index.ts index fc19dc2e..5740e956 100644 --- a/scripts/generate-product-feature-index.ts +++ b/scripts/generate-product-feature-index.ts @@ -271,11 +271,17 @@ function requiredInteger(source: string, name: string, file: string): number { } /** - * 09-07 (D-10). A feature directory must declare itself or say it is not - * installed. A missing or misspelt `feature-module.ts` used to drop the + * 09-07 (D-10). A feature directory must declare itself or say it is not a + * feature. A missing or misspelt `feature-module.ts` used to drop the * feature from the product without a word. + * + * 1103/09-09. The marker was named `NOT_INSTALLED`, the runtime state of a + * declared feature the build or the runtime document left out + * (`src/contracts/product-features.ts`). It marks something else, a directory + * that is no feature at all (an architecture sample), so it has its own name, + * and a directory may not carry both the marker and a declaration. */ -export const NOT_INSTALLED_MARKER = "NOT_INSTALLED"; +export const NOT_A_FEATURE_MARKER = "NOT_A_FEATURE"; async function readDeclarations( directory: string, @@ -292,17 +298,27 @@ async function readDeclarations( for (const item of items) { if (!item.isDirectory()) continue; const file = resolve(directory, item.name, fileName); + const marker = + requiredUnless !== undefined && + (await readFile(resolve(directory, item.name, requiredUnless)).then( + () => true, + () => false, + )); + let source: string; try { - found.push({ directory: item.name, file, source: await readFile(file, "utf8") }); + source = await readFile(file, "utf8"); } catch { - if (requiredUnless === undefined) continue; - const marker = await readFile(resolve(directory, item.name, requiredUnless)) - .then(() => true, () => false); - if (marker) continue; + if (requiredUnless === undefined || marker) continue; throw new Error( `src/features/${item.name} has no ${fileName}; add one or mark the directory with ${requiredUnless}`, ); } + if (marker) { + throw new Error( + `src/features/${item.name} has both ${fileName} and ${requiredUnless}; delete ${requiredUnless} to install it, or ${fileName} to keep it out`, + ); + } + found.push({ directory: item.name, file, source }); } return found; } @@ -351,7 +367,7 @@ export async function createFileSystemDeclarationSource( for (const declaration of await readDeclarations( resolve(root, "src/features"), "feature-module.ts", - NOT_INSTALLED_MARKER, + NOT_A_FEATURE_MARKER, )) { const feature: FeatureDeclaration = { id: requiredLiteral(declaration.source, "FEATURE_MODULE_ID", declaration.file), diff --git a/src/features/local-draft-feature/NOT_INSTALLED b/src/features/local-draft-feature/NOT_A_FEATURE similarity index 100% rename from src/features/local-draft-feature/NOT_INSTALLED rename to src/features/local-draft-feature/NOT_A_FEATURE diff --git a/tests/scripts/generate-product-feature-index.test.ts b/tests/scripts/generate-product-feature-index.test.ts index 4d1f05bf..53b305d6 100644 --- a/tests/scripts/generate-product-feature-index.test.ts +++ b/tests/scripts/generate-product-feature-index.test.ts @@ -145,7 +145,7 @@ describe("app-scoped selection from ownership declarations", () => { await expect(generateAppIndexes(overContexts, "a")).rejects.toThrow(/App a context cardinality 2 exceeds budget 1/); }); - it("refuses a feature directory without a declaration or NOT_INSTALLED marker (09-07)", async () => { + it("refuses a feature directory without a declaration or NOT_A_FEATURE marker (09-07)", async () => { const files = { "src/apps/a/app-module.ts": app("a"), "src/contexts/c/context-module.ts": context("c", "a"), @@ -158,12 +158,39 @@ describe("app-scoped selection from ownership declarations", () => { ); const marked = await repo({ ...files, - "src/features/typo/NOT_INSTALLED": "Composed only by tests.\n", + "src/features/typo/NOT_A_FEATURE": "Composed only by tests.\n", }); const selected = await generateAppIndexes(marked, "a"); expect(selected.entries.map((entry) => entry.id)).toEqual(["f"]); }); + it("no longer accepts the old NOT_INSTALLED marker name (1103/09-09)", async () => { + // The word is the runtime state "declared but not selected"; a marker + // under that name is read as a missing declaration, naming the new one. + const root = await repo({ + "src/apps/a/app-module.ts": app("a"), + "src/contexts/c/context-module.ts": context("c", "a"), + "src/features/sample/NOT_INSTALLED": "Composed only by tests.\n", + }); + await expect(generateAppIndexes(root, "a")).rejects.toThrow( + /src\/features\/sample has no feature-module\.ts; add one or mark the directory with NOT_A_FEATURE/u, + ); + }); + + it("refuses a marked directory that also declares a feature (1103/09-09)", async () => { + // Graduating a sample means deleting the marker; keeping both used to + // install the feature silently while the marker said it was none. + const root = await repo({ + "src/apps/a/app-module.ts": app("a"), + "src/contexts/c/context-module.ts": context("c", "a"), + "src/features/f/feature-module.ts": feature("f", "c"), + "src/features/f/NOT_A_FEATURE": "Composed only by tests.\n", + }); + await expect(generateAppIndexes(root, "a")).rejects.toThrow( + /src\/features\/f has both feature-module\.ts and NOT_A_FEATURE; delete NOT_A_FEATURE to install it, or feature-module\.ts to keep it out/u, + ); + }); + it("skips contexts without features and never imports another app's features", async () => { const root = await repo({ "src/apps/a/app-module.ts": app("a"),