fix(scale): keep the ceiling rationale next to the baseline, not in a review document (11-04, 00-02, 14-05)

The growth test read docs/reviews/, which the removal fixtures do not copy and
README lets a project delete, so three removal checks failed with ENOENT. The
rationale now lives in config/scale/feature-shape-ceilings.json and a guard
test keeps code from reading the deletable history documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-27 14:03:03 +09:00
co-authored by Claude Opus 5.5
parent 6b589515f1
commit 70f4ff8717
7 changed files with 143 additions and 8 deletions
+2 -1
View File
@@ -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 |
| --- | --- |
+41
View File
@@ -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"
}
]
}
@@ -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 |
| --- | --- | --- | --- |
@@ -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;
+1
View File
@@ -56,6 +56,7 @@ const SAMPLE_EXTRAS: Readonly<Record<string, FeatureExtras>> = 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",
@@ -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<string[]> {
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([]);
});
});
+31 -6
View File
@@ -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<Record<string, string>>[];
}>;
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);
}
});
});