diff --git a/CHANGELOG.md b/CHANGELOG.md index b61bf5fc..75b63762 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -115,7 +115,7 @@ 6. **쓰는 곳이 있을 때만.** - V2 HTTP 클라이언트와 V2 API 행에서 지운 이름(아래 `048f490`·`12f3bb7` 행). 두 다운스트림은 앱 코드에서 V2 클라이언트를 부르지 않는다. 부르는 곳은 템플릿의 `tests/unit/runtime-adapters.test.ts`뿐이고 그 파일은 템플릿 것으로 바뀐다. - realtime: `BoundedPollOperationContract`를 지웠다. SSE·poll이 서버에 닿지 못한 실패는 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`이다. - - 예제 화면 3개(`EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`)가 `platform-examples-feature`로 옮겼다. 예제를 지운 제품(tech-log)은 이 기능 폴더와 `src/contexts/platform-examples-context/`를 지운다. 예제 화면을 여는 제품 테스트는 그 기능을 설치해 두거나 제품 화면으로 옮긴다. memento의 `production-csp.spec.ts`·`old-tab-chunk-recovery.spec.ts`가 `/examples/states`·`/examples/ui`에서 시작한다. `/examples/platform`(플랫폼 구성 화면)은 플랫폼 라우트로 남는다. + - 예제 화면 3개(`EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`)가 `platform-examples-feature`로 옮겼다. 예제를 지운 제품(tech-log)은 이 기능 폴더, `tests/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`를 지우고 `corepack pnpm generate:feature-index`를 돈다. 지우기 전에 `corepack pnpm test:sample-removal -- --feature=platform-examples-feature`가 사본에서 같은 삭제로 게이트를 돈다. 템플릿 문서가 지운 폴더를 계속 적어도 `verify:documentation`과 FE-GATE-005가 통과하는 것은 위 절의 수정부터다(1105/14-01). 그래서 두 절을 함께 받는다. 예제 화면을 여는 제품 테스트는 그 기능을 설치해 두거나 제품 화면으로 옮긴다. memento의 `production-csp.spec.ts`·`old-tab-chunk-recovery.spec.ts`가 `/examples/states`·`/examples/ui`에서 시작한다. `/examples/platform`(플랫폼 구성 화면)은 플랫폼 라우트로 남는다. - 포트를 직접 구현한 코드: `OpfsJournalPort.countPartitionTransactions`·`removePartition`, worker gateway의 `removePartition`, `PublicCacheInspection.activePointer`가 필수 칸이다. - offline-indexeddb recipe 타입: `src`와 이름이 같은 34개가 `src` 타입을 다시 내보낸다. (1103/04-01, 1103/04-04, 1103/09-04, 1103/05-01, 0929/05-01, 1103/02-05, 0929/05-03) @@ -147,7 +147,7 @@ | [계약] | 기능 어댑터 기여는 실행 중에도 `needs`에 적은 capability만 받는다. cast로 다른 capability를 읽던 기능은 `undefined`를 받는다 (1103/09-08) | `src/features/feature-adapter-contribution.ts` | `e7d6358` | | [계약] | 기능 계약이 route id `APP_HOME`을 선언하면 플랫폼 홈을 대신한다. 둘이 선언하면 두 기능 id를 적고 실패한다. `src/contexts//context-layout.tsx`가 `CONTEXT_LAYOUT`을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 `
` 하나를 그려야 하고, `tests/component/layout-landmarks.test.tsx`가 설치된 레이아웃을 모두 실행해 본다 (1101/09-03) | `src/contracts/routes.ts`, `src/contexts/bounded-context-module.ts`, `scripts/generate-product-feature-index.ts`, `tests/component/layout-landmarks.test.tsx` | `ca16187`, `27f4523` | | [계약] | 앱 조립이 닿지 않는 기능 라우트를 앱 모듈을 평가할 때 throw로 거절한다. 소유 context 루트 밖의 라우트, 계약에 없는 route handle, 플랫폼 라우트가 먼저 받는 경로, 다른 기능과 같은 경로(파라미터 이름만 다른 것과 대소문자·끝 슬래시만 다른 것 포함)다. 시작할 런타임이 없는 선택 capability(realtime·webWorkers·offlineCommands)도 거절한다 (1101/09-06, 1101/09-07, 1103/08-04, 1101 README 14.4) | `src/apps/deployable-app-module.ts`, `src/contexts/bounded-context-module.ts`, `src/bootstrap/` | `7139c7c`, `d6e4e51`, `7d85589`, `8469554`, `851fded`, `48a4074` | -| [계약] **BREAKING** | 예제 화면 `EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`가 끌 수 있는 기능 `platform-examples-feature`(context `platform-examples-context`, 루트 `examples/*`)로 옮겼다. 페이지 파일은 그 기능의 `presentation/`에 있다. `PLATFORM_ROUTE_REGISTRY`·`PLATFORM_ROUTE_RUNTIME_CONTRACT`·`PLATFORM_ROUTE_RUNTIME`에서 키가 빠졌다. 홈 문구 `home.starter.platform`·`ui`·`states`는 `home.starter.open({title})`로 바뀌었다. 예제를 지운 제품은 이 기능 폴더와 context를 지운다. `/examples/platform`은 플랫폼 라우트로 남는다 (1103/09-04) | `src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`, `src/contracts/routes.ts` | `b96d61d` | +| [계약] **BREAKING** | 예제 화면 `EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`가 끌 수 있는 기능 `platform-examples-feature`(context `platform-examples-context`, 루트 `examples/*`)로 옮겼다. 페이지 파일은 그 기능의 `presentation/`에 있다. `PLATFORM_ROUTE_REGISTRY`·`PLATFORM_ROUTE_RUNTIME_CONTRACT`·`PLATFORM_ROUTE_RUNTIME`에서 키가 빠졌다. 홈 문구 `home.starter.platform`·`ui`·`states`는 `home.starter.open({title})`로 바뀌었다. 예제를 지운 제품은 이 기능 폴더, 그 테스트 폴더, context를 지운다(위 "먼저 할 일" 6단계). `/examples/platform`은 플랫폼 라우트로 남는다 (1103/09-04) | `src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`, `src/contracts/routes.ts` | `b96d61d` | | [계약] | 계약 기여의 출처는 `EXTERNAL_PACKAGE`이고, `TEMPLATE_FIXTURE`는 참조 기능만 하나 쓸 수 있다. 다른 출처 종류는 `unknown contribution source kind`로 거절한다 (1101/07-04) | `src/contracts/external-contract-runtime.ts` | `c063389` | | [계약] **BREAKING** | `useApplicationMutation`은 raw `{ execute, definitionId }`를 받지 않는다. `useServerStateScope()`의 scope로 만든 `BoundMutation`을 넘기고 `execute(input, { signal, intent })`로 부른다. `commandMutationIdentity()`가 `operationId`·`requiresIdempotencyKey`를 descriptor에서 준다. `QueryDefinition.owner`·`operationId`와 `BoundMutation.owner`는 아무도 읽지 않아 `@deprecated` 선택 칸으로 바꿨고 다음 릴리스에서 지운다. raw query는 남았다. 세션이 바뀌면 이전 결과가 보이지 않는다(JSDoc에 위험 표기) (1101/08-03, 1103/16-05, 1101/03-03, 1103/16-06) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/adapters/query/` | `1fa5f3e`, `f59a806`, `68f94f5` | diff --git a/PRODUCT.md b/PRODUCT.md index de4e8dc6..5d612657 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -30,7 +30,7 @@ web - 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지입니다. - 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → component 세 단계로 파생됩니다(`tokens/primitive.css`, `semantic.css`, `component.css`). - 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다. -- 참조 기능(`src/features/reference-feature/`)은 `test:sample-removal`로 지울 수 있습니다. 예제 라우트 4개(`/examples/platform`, `ui`, `states`, `auth`)와 홈은 기본 구성이고 제거 드릴이 없습니다. 그래서 예제 화면에만 넣은 디자인은 파생 서비스에 그대로 남습니다. +- 참조 기능(`src/features/reference-feature/`)은 `test:sample-removal`로 지울 수 있습니다. 예제 화면 3개(`/examples/ui`, `states`, `auth`)도 기능 `platform-examples-feature`라서 같은 드릴(`test:sample-removal -- --feature=platform-examples-feature`)로 지울 수 있습니다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성이고 제거 드릴이 없습니다. 그래서 예제 화면 3개에만 넣은 디자인은 예제를 지운 파생 서비스에서 함께 사라지고, 홈과 플랫폼 구성 화면에 넣은 디자인은 남습니다. - 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다. ## Brand Commitments diff --git a/docs/README.md b/docs/README.md index f2f541aa..7d9393f8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -51,6 +51,9 @@ checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은 없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은 `scripts/verify-documentation-readiness.ts`다. +복사한 프로젝트가 지울 수 있는 템플릿 기능(참조 기능, 예제 화면. 목록은 +`scripts/lib/removable-template-features.ts`)의 경로와 script는 그 기능이 설치돼 있을 때 +(`src/features//feature-module.ts`가 있을 때) 검사하고, 지운 뒤에는 없어도 된다. 게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다. diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index fa66ffdf..ea669dbd 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -104,11 +104,18 @@ layouts"). Its starter links are the first three screens of the navigation. The example screens `/examples/ui`, `/examples/states` and `/examples/auth` are one feature, `src/features/platform-examples-feature/`, in its own context `src/contexts/platform-examples-context/` (1103/09-04). A product turns them -off like any feature: leave the id out of `VITE_PRODUCT_FEATURES`, or remove -it with `corepack pnpm test:sample-removal -- --feature=platform-examples-feature` -as the drill. Their routes then leave the registry, the navigation, the -bundle and the manual accessibility list (FE-GATE-028). Their component tests -are in `tests/features/platform-examples-feature/` and go with them. +off like any feature: leave the id out of `VITE_PRODUCT_FEATURES`, or delete +the feature. To delete it, remove those two folders and +`tests/features/platform-examples-feature/` (its component tests), then run +`corepack pnpm generate:feature-index`; +`corepack pnpm test:sample-removal -- --feature=platform-examples-feature` +does the same in a copy of the repository and runs the gates there. Their +routes then leave the registry, the navigation, the bundle and the manual +accessibility list (FE-GATE-028). This document keeps naming the three +folders after they are gone: `verify:documentation` checks the paths of a +removable template feature (`scripts/lib/removable-template-features.ts`) +while the feature is installed and accepts them once its `feature-module.ts` +is gone (1105/14-01). The platform overview (`/examples/platform`, `src/presentation/examples/platform-overview-page.tsx`) stays a platform diff --git a/scripts/lib/removable-template-features.ts b/scripts/lib/removable-template-features.ts index 415f56e7..39e5aed2 100644 --- a/scripts/lib/removable-template-features.ts +++ b/scripts/lib/removable-template-features.ts @@ -7,7 +7,8 @@ * files outside them, which `scripts/test-sample-removal.ts` deletes with it. * * This is the one list. The removal drill reads the reference sample's paths - * and scripts from it, and the documentation check reads the whole of it. + * and scripts from it, and the documentation check reads the whole of it: a + * feature counts as deleted once its `feature-module.ts` is gone. */ export type RemovableTemplateFeature = Readonly<{ /** Its FEATURE_MODULE_ID, also its folder under src/features and tests/features. */ diff --git a/scripts/lib/removal-fixture.ts b/scripts/lib/removal-fixture.ts index 9222d777..e892a57c 100644 --- a/scripts/lib/removal-fixture.ts +++ b/scripts/lib/removal-fixture.ts @@ -74,6 +74,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([ "tests/unit/backend-contract-pin.test.ts", // 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md. "tests/unit/feature-tracked-files.test.ts", + // 1105/14-01 + "tests/unit/template-feature-removal-documents.test.ts", ] as const); /** The tests a fixture copied from `copyTargets` cannot run. */ diff --git a/scripts/verify-documentation-readiness.ts b/scripts/verify-documentation-readiness.ts index 7fda24b5..32f4b322 100644 --- a/scripts/verify-documentation-readiness.ts +++ b/scripts/verify-documentation-readiness.ts @@ -8,6 +8,10 @@ import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts"; import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts"; import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts"; import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts"; +import { + REMOVABLE_TEMPLATE_FEATURES, + removableTemplateFeaturePaths, +} from "./lib/removable-template-features.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; /** @@ -183,6 +187,25 @@ const gateIds = new Set([ ).gates.map((gate) => gate.id), ...RETIRED_GATE_IDS, ]); +// 1105/14-01. A copy may delete the template features listed in +// scripts/lib/removable-template-features.ts, and the CHANGELOG tells +// tech-log to delete the example screens. The documents are the template's: +// a product that edited them to drop the feature's paths would conflict on +// every sync. While a feature is installed (its feature-module.ts exists), +// its paths and scripts are checked like any other; once it is not, they are +// not drift. tech-log keeps the reference sample's folder with its contracts +// but without its module, screens and tests (CHANGELOG "먼저 할 일" 1). A +// misspelt feature folder is not on the list and still fails. +const removedTemplateFeatures = REMOVABLE_TEMPLATE_FEATURES.filter( + (feature) => !exists(`src/features/${feature.featureId}/feature-module.ts`), +); +const removedTemplateFeaturePaths = removedTemplateFeatures.flatMap((feature) => + removableTemplateFeaturePaths(feature), +); +const removedTemplateFeatureScripts = new Set(removedTemplateFeatures.flatMap((feature) => feature.scripts)); +function missingScript(name: string): boolean { + return !scripts.has(name) && !removedTemplateFeatureScripts.has(name); +} // Generated output is what git ignores, so a document may name it before a // run has written it. const ignorePatterns = (await readFile(join(rootDirectory, ".gitignore"), "utf8").catch(() => "")) @@ -361,17 +384,18 @@ for (const document of contractDocuments) { !exists(trimmed) && !NOT_CREATED.has(trimmed) && !generated(trimmed) && - !deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) + !deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) && + !removedTemplateFeaturePaths.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`)) ) { missingPaths.add(trimmed); } } const missingScripts = new Set(); for (const [, name = ""] of text.matchAll(/(?:corepack pnpm|`pnpm) (?:run )?([a-z](?:[\w:-]*\w)?)/gu)) { - if (!PNPM_COMMANDS.has(name) && !scripts.has(name)) missingScripts.add(name); + if (!PNPM_COMMANDS.has(name) && missingScript(name)) missingScripts.add(name); } for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) { - if (scriptPrefixes.has(name.split(":")[0]) && !scripts.has(name)) missingScripts.add(name); + if (scriptPrefixes.has(name.split(":")[0]) && missingScript(name)) missingScripts.add(name); } documentReferences.push({ path: document, @@ -486,6 +510,12 @@ if (!passed) { ); process.exit(1); } +if (removedTemplateFeatures.length > 0) { + process.stdout.write( + `Documentation readiness: paths and scripts of removed template features not required: ` + + `${removedTemplateFeatures.map((feature) => feature.featureId).join(", ")}\n`, + ); +} const unverified = documentReferences.flatMap((entry) => entry.unverifiedLinks); if (unverified.length > 0) { const reasons = [...pairedTrees].flatMap(([repository, tree]) => diff --git a/tests/unit/hosting-probe.test.ts b/tests/unit/hosting-probe.test.ts index 0bae3ed7..de9f2d3c 100644 --- a/tests/unit/hosting-probe.test.ts +++ b/tests/unit/hosting-probe.test.ts @@ -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] }), diff --git a/tests/unit/template-feature-removal-documents.test.ts b/tests/unit/template-feature-removal-documents.test.ts new file mode 100644 index 00000000..68d564e9 --- /dev/null +++ b/tests/unit/template-feature-removal-documents.test.ts @@ -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); +});