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:
co-authored by
Claude Opus 5.5
parent
6b589515f1
commit
70f4ff8717
@@ -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 |
|
||||
| --- | --- |
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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([]);
|
||||
});
|
||||
});
|
||||
@@ -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);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user