import { spawnSync } from "node:child_process"; import { mkdir, rm, writeFile } from "node:fs/promises"; import { join, resolve } from "node:path"; import { assertLinearOrBetter, growthExponents, } from "../../src/platform/cardinality/growth-regression.ts"; /** * scale-architecture.md ยง38. TypeScript scale gate. * * Parses `tsc --extendedDiagnostics` and measures bounded local fixtures: * generated feature modules composed by one context, at increasing local * cardinality. S3/S4 are never compiled; they are verified as topology. */ export type TscDiagnostics = Readonly<{ files: number; lines?: number; types: number; symbols: number; instantiations: number; memoryKb?: number; totalTimeSeconds?: number; }>; const FIELD_NAMES: Readonly> = Object.freeze({ Files: "files", Lines: "lines", Types: "types", Symbols: "symbols", Instantiations: "instantiations", "Memory used": "memoryKb", "Total time": "totalTimeSeconds", }); export function parseTscExtendedDiagnostics(text: string): TscDiagnostics { const parsed: Partial> = {}; for (const line of text.split(/\r?\n/u)) { const match = /^\s*([A-Za-z][A-Za-z ]*?):\s+([\d.]+)\s*([KMs]?)\s*$/u.exec(line); if (!match) continue; const field = FIELD_NAMES[match[1] as string]; if (!field) continue; const value = Number(match[2]); if (!Number.isFinite(value)) continue; parsed[field] = match[3] === "M" ? value * 1024 : value; } for (const required of ["files", "types", "symbols", "instantiations"] as const) { if (parsed[required] === undefined) { throw new TypeError(`tsc diagnostics missing ${required}`); } } return Object.freeze(parsed) as TscDiagnostics; } export function runTscDiagnostics(project: string, cwd = process.cwd()): TscDiagnostics { const tsc = resolve(cwd, "node_modules/.bin/tsc"); const result = spawnSync(tsc, ["--project", project, "--noEmit", "--extendedDiagnostics"], { cwd, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, }); if (result.status !== 0) { throw new Error(`tsc failed for ${project}: ${(result.stdout + result.stderr).slice(-2_000)}`); } return parseTscExtendedDiagnostics(result.stdout); } /** * Generates one bounded local app: `features` feature modules, each with its * own typed contract, composed by one generated index. The shape mirrors the * repository's feature-module/generated-index pattern. */ export async function writeLocalTscFixture( root: string, features: number, ): Promise { await rm(root, { recursive: true, force: true }); await mkdir(join(root, "features"), { recursive: true }); const imports: string[] = []; const members: string[] = []; for (let index = 0; index < features; index += 1) { const id = `feature${index}`; await writeFile( join(root, "features", `${id}.ts`), `export type ${id}Input = Readonly<{ id: string; limit: number; tags?: readonly string[] }>;\n` + `export type ${id}Output = Readonly<{ items: readonly Readonly<{ id: string; name: string }>[] }>;\n` + `export const ${id} = Object.freeze({\n` + ` id: "${id}" as const,\n` + ` routes: Object.freeze({ ${id.toUpperCase()}_LIST: "/${id}" }),\n` + ` execute(input: ${id}Input): ${id}Output {\n` + ` return { items: [{ id: input.id, name: String(input.limit) }] };\n` + ` },\n` + `});\n`, ); imports.push(`import { ${id} } from "./features/${id}.ts";`); members.push(` ${id},`); } await writeFile( join(root, "index.ts"), `${imports.join("\n")}\nexport const LOCAL_FEATURES = Object.freeze([\n${members.join("\n")}\n] as const);\n` + `export type LocalFeatureId = (typeof LOCAL_FEATURES)[number]["id"];\n`, ); const tsconfig = join(root, "tsconfig.json"); await writeFile( tsconfig, JSON.stringify( { compilerOptions: { target: "ES2022", module: "ESNext", moduleResolution: "Bundler", allowImportingTsExtensions: true, strict: true, noEmit: true, skipLibCheck: true, types: [], lib: ["ES2022"], }, include: ["index.ts", "features/*.ts"], }, null, 2, ), ); return tsconfig; } export type TscScaleReport = Readonly<{ passed: boolean; app: TscDiagnostics; local: readonly Readonly<{ features: number; diagnostics: TscDiagnostics }>[]; checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[]; }>; export async function collectTscScale( localSizes: readonly number[], cwd = process.cwd(), ): Promise { const app = runTscDiagnostics("tsconfig.app.json", cwd); const local: { features: number; diagnostics: TscDiagnostics }[] = []; for (const features of localSizes) { const tsconfig = await writeLocalTscFixture( resolve(cwd, ".tmp/scale-tsc", `local-${features}`), features, ); local.push({ features, diagnostics: runTscDiagnostics(tsconfig, cwd) }); } const checks: { name: string; passed: boolean; detail: string }[] = []; for (const metric of ["types", "symbols", "instantiations"] as const) { const series = local.map(({ features, diagnostics }) => ({ n: features, // Library/baseline cost is constant; growth is judged on what the local // features add on top of the smallest fixture. cost: Math.max(1, diagnostics[metric]), })); try { assertLinearOrBetter(series, { maxExponent: 1.3 }); checks.push({ name: `tsc:${metric}`, passed: true, detail: `exponents ${growthExponents(series).map((value) => value.toFixed(2)).join(", ")}`, }); } catch (error) { checks.push({ name: `tsc:${metric}`, passed: false, detail: error instanceof Error ? error.message : String(error), }); } } return Object.freeze({ passed: checks.every((check) => check.passed), app, local: Object.freeze(local), checks: Object.freeze(checks), }); } async function main(): Promise { const artifactArg = process.argv.find((argument) => argument.startsWith("--artifact=")); const sizesArg = process.argv.find((argument) => argument.startsWith("--local-sizes=")); const sizes = (sizesArg?.slice("--local-sizes=".length) ?? "25,100,400") .split(",") .map(Number) .filter((value) => Number.isSafeInteger(value) && value > 0); const artifact = resolve( artifactArg?.slice("--artifact=".length) ?? "artifacts/scale/tsc-diagnostics.json", ); const report = await collectTscScale(sizes); await mkdir(resolve(artifact, ".."), { recursive: true }); await writeFile( artifact, `${JSON.stringify({ schemaVersion: 1, generatedAt: new Date().toISOString(), ...report }, null, 2)}\n`, ); process.stdout.write( `tsc app: files=${report.app.files} types=${report.app.types} instantiations=${report.app.instantiations}\n`, ); for (const check of report.checks) { process.stdout.write(`${check.passed ? "PASS" : "FAIL"} ${check.name} (${check.detail})\n`); } process.stdout.write(`tsc diagnostics artifact: ${artifact}\n`); if (!report.passed) process.exitCode = 1; } if (import.meta.url === `file://${process.argv[1]}`) { await main(); }