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"),