diff --git a/README.md b/README.md index f798dbe4..b21660d1 100644 --- a/README.md +++ b/README.md @@ -192,7 +192,8 @@ target designs and work history. ### Files you can delete after copying These record how the template was built. Nothing in the build or the gates -reads them, except the one file noted below. +reads them, except the one file noted below +(`tests/unit/deletable-history-documents.test.ts` checks this). | Path | Contents | | --- | --- | diff --git a/config/scale/feature-shape-ceilings.json b/config/scale/feature-shape-ceilings.json new file mode 100644 index 00000000..1731d967 --- /dev/null +++ b/config/scale/feature-shape-ceilings.json @@ -0,0 +1,41 @@ +{ + "schemaVersion": 1, + "baseline": "config/scale/feature-shape-growth.json", + "ceilings": { + "contextMaxFeatures": 200, + "appMaxContexts": 20 + }, + "summary": "The ceilings bound the count; they are not a verified capacity. The practical limit of one app is the initial JavaScript budget, then typecheck memory. 400 features were not measured (D-18 makes it optional).", + "axes": [ + { + "axis": "Typecheck of one app", + "verified": "Linear, about 115k instantiations and 37 MB of tsc memory per feature, up to 100 features", + "condition": "Reference-shaped features, tsconfig.app.json, the host recorded in the baseline", + "notVerified": "200 features (one full context) and beyond; 4,000 (20 x 200) would need on the order of 150 GB by the same slope" + }, + { + "axis": "Production build", + "verified": "Completes at 100 features in seconds", + "condition": "Same", + "notVerified": "Beyond 100" + }, + { + "axis": "Initial JavaScript", + "verified": "Grows by about 2.9 KB gzip and one file per feature: every installed feature's contracts and module load at boot", + "condition": "Same", + "notVerified": "The initial budget (204,800 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling" + }, + { + "axis": "Lazy JavaScript", + "verified": "About 6.8 KB gzip and six files per feature, every file far below the 120 KiB lazy-chunk budget", + "condition": "Same", + "notVerified": "Download cost of many lazy files" + }, + { + "axis": "Routes", + "verified": "4 per feature, composed without conflict", + "condition": "Same", + "notVerified": "Router matching cost at runtime" + } + ] +} diff --git a/docs/reviews/2026-09-23-extreme-scale-acceptance.md b/docs/reviews/2026-09-23-extreme-scale-acceptance.md index 264c9935..86ef8194 100644 --- a/docs/reviews/2026-09-23-extreme-scale-acceptance.md +++ b/docs/reviews/2026-09-23-extreme-scale-acceptance.md @@ -36,7 +36,7 @@ Measured 2026-09-27, two runs per size, Intel i5-10400F (12 logical CPUs), Node | 25 | 110 | 3,579,093 | 1.4 GB | 8.1 s / 8.7 s | 1.7 s / 2.1 s | 39 / 274,493 B | 165 / 171,638 B | | 100 | 410 | 12,157,304 | 4.2 GB | 31.3 s / 43.2 s | 6.0 s / 3.7 s | 114 / 490,658 B | 615 / 704,938 B | -What this means for the declared ceilings (`CONTEXT_MAX_FEATURES = 200`, `src/contexts/reference-context/context-module.ts:10`; `APP_MAX_CONTEXTS = 20`, `src/apps/template-app/app-module.ts:7`): +What this means for the declared ceilings (`CONTEXT_MAX_FEATURES = 200`, `src/contexts/reference-context/context-module.ts:10`; `APP_MAX_CONTEXTS = 20`, `src/apps/template-app/app-module.ts:7`). The table below is a copy of `config/scale/feature-shape-ceilings.json`, which `tests/unit/feature-shape-growth.test.ts` checks against the baseline path and both constants; this document may be deleted after copying the template, the JSON file may not: | Growth axis | Verified | Condition | Not verified | | --- | --- | --- | --- | diff --git a/scripts/scale/measure-feature-shape-growth.ts b/scripts/scale/measure-feature-shape-growth.ts index dba1ec0e..380c3688 100644 --- a/scripts/scale/measure-feature-shape-growth.ts +++ b/scripts/scale/measure-feature-shape-growth.ts @@ -29,6 +29,8 @@ import { parseTscExtendedDiagnostics, type TscDiagnostics } from "./collect-tsc- * `--write` stores the result as config/scale/feature-shape-growth.json. */ export const FEATURE_SHAPE_BASELINE_PATH = "config/scale/feature-shape-growth.json"; +/** What the declared ceilings rest on, derived by hand from the baseline. */ +export const FEATURE_SHAPE_CEILINGS_PATH = "config/scale/feature-shape-ceilings.json"; const SOURCE_FEATURE = "src/features/reference-feature"; const FEATURES_PER_CONTEXT = 200; diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index 912a1c4e..0df1e082 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -56,6 +56,7 @@ const SAMPLE_EXTRAS: Readonly> = Object.freeze({ "tests/unit/feature-shape-growth.test.ts", "scripts/scale/measure-feature-shape-growth.ts", "config/scale/feature-shape-growth.json", + "config/scale/feature-shape-ceilings.json", "tests/mocks", "tests/fixtures/typecheck/invalid-feature-input.ts", "tests/fixtures/typecheck/invalid-reference-operation.ts", diff --git a/tests/unit/deletable-history-documents.test.ts b/tests/unit/deletable-history-documents.test.ts new file mode 100644 index 00000000..01bbaec7 --- /dev/null +++ b/tests/unit/deletable-history-documents.test.ts @@ -0,0 +1,65 @@ +import { readdir, readFile } from "node:fs/promises"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +/** + * README.md, "Files you can delete after copying", tells a new project that + * the build and the gates read none of the history documents except + * `docs/reviews/adapters/INVENTORY.md`. The removal fixtures rely on the same + * promise: they do not copy `docs/`. A test that opens a review document broke + * all three removal checks (fix of 11-04), so the promise is checked here. + */ +const CODE_ROOTS = ["src", "tests", "scripts", "config", "recipes", "schemas", ".gitea"]; +const ROOT_FILES = [ + "package.json", + "vite.config.ts", + "vitest.config.ts", + "eslint.config.ts", + "playwright.config.ts", +]; + +// Built from pieces so that this file does not match itself. +const REVIEWS = ["docs", "reviews", ""].join("/"); +const KEPT = `${REVIEWS}adapters/INVENTORY.md`; +const DELETABLE = [ + new RegExp(`${REVIEWS}(?!adapters/INVENTORY\\.md)`, "u"), + new RegExp(["docs", "superpowers"].join("/"), "u"), + new RegExp(`\\b${"SPEC"}\\.md\\b`, "u"), + new RegExp(`\\b${"CLAUDE"}\\.md\\b`, "u"), + new RegExp(`(^|["'\`(\\s])${"tasks"}/`, "u"), +]; + +async function codeFiles(directory: string): Promise { + const entries = await readdir(directory, { withFileTypes: true }).catch( + () => [], + ); + const files = await Promise.all( + entries.map(async (entry) => { + const target = path.join(directory, entry.name); + if (entry.isDirectory()) + return entry.name === "node_modules" ? [] : codeFiles(target); + return /\.(?:[cm]?[jt]sx?|json|ya?ml)$/u.test(entry.name) ? [target] : []; + }), + ); + return files.flat(); +} + +describe("deletable history documents", () => { + it("are read by no code, test, script or configuration", async () => { + const files = [ + ...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat(), + ...ROOT_FILES, + ]; + const readers: string[] = []; + for (const file of files) { + const lines = (await readFile(file, "utf8").catch(() => "")).split("\n"); + lines.forEach((line, index) => { + if (DELETABLE.some((pattern) => pattern.test(line))) + readers.push(`${file}:${index + 1}`); + }); + } + + expect(readers, `only ${KEPT} may be read`).toEqual([]); + }); +}); diff --git a/tests/unit/feature-shape-growth.test.ts b/tests/unit/feature-shape-growth.test.ts index fffc0b52..99cfc0c9 100644 --- a/tests/unit/feature-shape-growth.test.ts +++ b/tests/unit/feature-shape-growth.test.ts @@ -4,8 +4,11 @@ import { describe, expect, it } from "vitest"; import { FEATURE_SHAPE_BASELINE_PATH, + FEATURE_SHAPE_CEILINGS_PATH, renameReferenceFeature, } from "../../scripts/scale/measure-feature-shape-growth.ts"; +import { APP_MAX_CONTEXTS } from "../../src/apps/template-app/app-module.ts"; +import { CONTEXT_MAX_FEATURES } from "../../src/contexts/reference-context/context-module.ts"; /** * 11-04 (D-18). The scale evidence used to come from stub features that only @@ -92,12 +95,34 @@ describe("feature-shape growth measurement (11-04)", () => { } }); - it("states in the acceptance matrix what the ceilings rest on", async () => { - const acceptance = await readFile( - "docs/reviews/2026-09-23-extreme-scale-acceptance.md", - "utf8", + it("states in the committed rationale what the ceilings rest on", async () => { + // The rationale lives next to the baseline, not in a review document: the + // history documents may be deleted after copying (README.md). + const rationale = JSON.parse( + await readFile(FEATURE_SHAPE_CEILINGS_PATH, "utf8"), + ) as Readonly<{ + baseline: string; + ceilings: Readonly<{ contextMaxFeatures: number; appMaxContexts: number }>; + axes: readonly Readonly>[]; + }>; + + expect(rationale.baseline).toBe(FEATURE_SHAPE_BASELINE_PATH); + expect(rationale.ceilings).toEqual({ + contextMaxFeatures: CONTEXT_MAX_FEATURES, + appMaxContexts: APP_MAX_CONTEXTS, + }); + expect(rationale.axes.map((row) => row.axis)).toEqual( + expect.arrayContaining([ + "Typecheck of one app", + "Production build", + "Initial JavaScript", + "Lazy JavaScript", + "Routes", + ]), ); - expect(acceptance).toContain(FEATURE_SHAPE_BASELINE_PATH); - expect(acceptance).toMatch(/\| Growth axis \| Verified \| Condition \| Not verified \|/u); + for (const row of rationale.axes) { + for (const column of ["axis", "verified", "condition", "notVerified"]) + expect(row[column], `${row.axis}.${column}`).toMatch(/\S/u); + } }); });