refactor(guardrails): add hotspot budgets and runtime cycle checks

scripts/check-file-budgets.ts

@@ -7,14 +7,35 @@ type FileBudgetResult = {
   lines: number;
 };
 
+type HotspotBudget = {
+  file: string;
+  baseline: number;
+  limit: number;
+};
+
+type HotspotStatus = HotspotBudget & {
+  lines: number;
+  delta: number;
+  overLimit: boolean;
+};
+
 const DEFAULT_LINE_LIMIT = 500;
 const TARGET_DIRS = ['src', 'launcher'];
 const TARGET_EXTENSIONS = new Set(['.ts']);
 const IGNORE_NAMES = new Set(['.DS_Store']);
+const HOTSPOT_BUDGETS: readonly HotspotBudget[] = [
+  { file: 'src/main.ts', baseline: 2978, limit: 3150 },
+  { file: 'src/config/service.ts', baseline: 116, limit: 140 },
+  { file: 'src/core/services/tokenizer.ts', baseline: 232, limit: 260 },
+  { file: 'launcher/main.ts', baseline: 101, limit: 130 },
+  { file: 'src/config/resolve.ts', baseline: 33, limit: 55 },
+  { file: 'src/main/runtime/composers/contracts.ts', baseline: 13, limit: 30 },
+];
 
-function parseArgs(argv: string[]): { strict: boolean; limit: number } {
+function parseArgs(argv: string[]): { strict: boolean; limit: number; enforceGlobal: boolean } {
   let strict = false;
   let limit = DEFAULT_LINE_LIMIT;
+  let enforceGlobal = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -22,6 +43,10 @@ function parseArgs(argv: string[]): { strict: boolean; limit: number } {
       strict = true;
       continue;
     }
+    if (arg === '--enforce-global') {
+      enforceGlobal = true;
+      continue;
+    }
     if (arg === '--limit') {
       const raw = argv[i + 1];
       const parsed = Number.parseInt(raw ?? '', 10);
@@ -34,7 +59,7 @@ function parseArgs(argv: string[]): { strict: boolean; limit: number } {
     }
   }
 
-  return { strict, limit };
+  return { strict, limit, enforceGlobal };
 }
 
 function resolveFilesWithRipgrep(): string[] {
@@ -71,28 +96,77 @@ function collectOverBudgetFiles(files: string[], limit: number): FileBudgetResul
   return results.sort((a, b) => b.lines - a.lines || a.file.localeCompare(b.file));
 }
 
-function printReport(overBudget: FileBudgetResult[], limit: number, strict: boolean): void {
+function collectHotspotStatuses(hotspots: readonly HotspotBudget[]): HotspotStatus[] {
+  return hotspots.map((hotspot) => {
+    const content = fs.readFileSync(hotspot.file, 'utf8');
+    const lines = countLines(content);
+    return {
+      ...hotspot,
+      lines,
+      delta: lines - hotspot.baseline,
+      overLimit: lines > hotspot.limit,
+    };
+  });
+}
+
+function printGlobalReport(
+  overBudget: FileBudgetResult[],
+  limit: number,
+  strict: boolean,
+  enforceGlobal: boolean,
+): void {
   const mode = strict ? 'strict' : 'warning';
   if (overBudget.length === 0) {
     console.log(`[OK] file budget check (${mode}) — no files over ${limit} LOC`);
     return;
   }
 
-  const heading = strict ? '[FAIL]' : '[WARN]';
-  console.log(`${heading} file budget check (${mode}) — ${overBudget.length} files over ${limit} LOC`);
+  const heading = strict && enforceGlobal ? '[FAIL]' : '[WARN]';
+  console.log(
+    `${heading} file budget check (${mode}) — ${overBudget.length} files over ${limit} LOC`,
+  );
   for (const item of overBudget) {
     console.log(`  - ${item.file}: ${item.lines} LOC`);
   }
   console.log('  Hint: split by runtime/domain boundaries; keep composition roots thin.');
 }
 
+function printHotspotReport(hotspots: readonly HotspotStatus[], strict: boolean): void {
+  const mode = strict ? 'strict' : 'warning';
+  const overLimit = hotspots.filter((hotspot) => hotspot.overLimit);
+
+  if (overLimit.length === 0) {
+    console.log(`[OK] hotspot budget check (${mode}) — no hotspots over limit`);
+  } else {
+    const heading = strict ? '[FAIL]' : '[WARN]';
+    console.log(
+      `${heading} hotspot budget check (${mode}) — ${overLimit.length} hotspots over limit`,
+    );
+  }
+
+  for (const hotspot of hotspots) {
+    const status = hotspot.overLimit ? 'OVER' : 'OK';
+    const delta = hotspot.delta >= 0 ? `+${hotspot.delta}` : `${hotspot.delta}`;
+    console.log(
+      `  - [${status}] ${hotspot.file}: baseline=${hotspot.baseline}, limit=${hotspot.limit}, current=${hotspot.lines}, delta=${delta}`,
+    );
+  }
+}
+
 function main(): void {
-  const { strict, limit } = parseArgs(process.argv.slice(2));
+  const { strict, limit, enforceGlobal } = parseArgs(process.argv.slice(2));
   const files = resolveFilesWithRipgrep();
   const overBudget = collectOverBudgetFiles(files, limit);
-  printReport(overBudget, limit, strict);
+  const hotspotStatuses = collectHotspotStatuses(HOTSPOT_BUDGETS);
 
-  if (strict && overBudget.length > 0) {
+  printGlobalReport(overBudget, limit, strict, enforceGlobal);
+  printHotspotReport(hotspotStatuses, strict);
+
+  const overGlobalLimit = overBudget.length > 0;
+  const hotspotOverLimit = hotspotStatuses.some((hotspot) => hotspot.overLimit);
+  const strictFailure = hotspotOverLimit || (strict && enforceGlobal && overGlobalLimit);
+
+  if (strict && strictFailure) {
     process.exitCode = 1;
   }
 }

scripts/check-runtime-cycles.test.ts

@@ -0,0 +1,51 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { runRuntimeCycleCheck } from './check-runtime-cycles';
+
+type CliResult = {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+};
+
+const CHECKER_PATH = path.join(process.cwd(), 'scripts', 'check-runtime-cycles.ts');
+const FIXTURE_ROOT = path.join('scripts', 'fixtures', 'runtime-cycles');
+
+function runCheckerCli(args: string[]): CliResult {
+  const result = spawnSync('bun', ['run', CHECKER_PATH, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+}
+
+test('acyclic fixture passes runtime cycle check', () => {
+  const result = runRuntimeCycleCheck(path.join(FIXTURE_ROOT, 'acyclic'), true);
+  assert.equal(result.hasCycle, false);
+  assert.equal(result.fileCount >= 3, true);
+});
+
+test('cyclic fixture fails via CLI and prints readable cycle path', () => {
+  const result = runCheckerCli(['--strict', '--root', path.join(FIXTURE_ROOT, 'cyclic')]);
+
+  assert.equal(result.status, 1);
+  assert.match(result.stdout, /^\[FAIL\] runtime cycle check \(strict\)/m);
+  assert.match(result.stdout, /module-a\.ts/);
+  assert.match(result.stdout, /module-b\.ts|nested\/index\.ts/);
+});
+
+test('missing root returns actionable error', () => {
+  const missingRoot = path.join(FIXTURE_ROOT, 'does-not-exist');
+  const result = runCheckerCli(['--strict', '--root', missingRoot]);
+
+  assert.equal(result.status, 1);
+  assert.match(result.stdout, /Runtime root not found:/);
+  assert.match(result.stdout, /--root <path>/);
+});

scripts/check-runtime-cycles.ts

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export type ParsedArgs = {
+  strict: boolean;
+  root: string;
+};
+
+export type RuntimeCycleCheckResult = {
+  root: string;
+  mode: 'warning' | 'strict';
+  fileCount: number;
+  hasCycle: boolean;
+  cyclePath: string[];
+};
+
+const DEFAULT_ROOT = path.join('src', 'main', 'runtime');
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  let strict = false;
+  let root = DEFAULT_ROOT;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--strict') {
+      strict = true;
+      continue;
+    }
+    if (arg === '--root') {
+      const raw = argv[i + 1];
+      if (!raw || raw.startsWith('--')) {
+        throw new Error('Missing value for --root. Usage: --root <path>');
+      }
+      root = raw;
+      i += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return { strict, root };
+}
+
+function walkTsFiles(root: string): string[] {
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkTsFiles(fullPath));
+      continue;
+    }
+    if (entry.isFile() && path.extname(entry.name) === '.ts') {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function extractRelativeSpecifiers(source: string): string[] {
+  const specifiers = new Set<string>();
+  const pattern = /(?:import|export)\s+(?:[^'";]+\s+from\s+)?['"]([^'"]+)['"]/g;
+  for (const match of source.matchAll(pattern)) {
+    const specifier = match[1];
+    if (specifier.startsWith('.')) {
+      specifiers.add(specifier);
+    }
+  }
+  return Array.from(specifiers);
+}
+
+function resolveRelativeTarget(importerFile: string, specifier: string): string | null {
+  const importerDir = path.dirname(importerFile);
+  const baseTarget = path.resolve(importerDir, specifier);
+  const extension = path.extname(baseTarget);
+
+  const candidates = extension
+    ? [baseTarget]
+    : [`${baseTarget}.ts`, path.join(baseTarget, 'index.ts')];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return path.normalize(candidate);
+    }
+  }
+
+  return null;
+}
+
+function toRelativePosix(root: string, filePath: string): string {
+  return path.relative(root, filePath).split(path.sep).join('/');
+}
+
+function detectCycle(graph: Map<string, string[]>): string[] {
+  const state = new Map<string, 0 | 1 | 2>();
+  const stack: string[] = [];
+
+  const visit = (node: string): string[] => {
+    state.set(node, 1);
+    stack.push(node);
+
+    const neighbors = graph.get(node) ?? [];
+    for (const next of neighbors) {
+      const nextState = state.get(next) ?? 0;
+      if (nextState === 0) {
+        const cycle = visit(next);
+        if (cycle.length > 0) {
+          return cycle;
+        }
+      } else if (nextState === 1) {
+        const startIndex = stack.indexOf(next);
+        if (startIndex >= 0) {
+          return [...stack.slice(startIndex), next];
+        }
+      }
+    }
+
+    stack.pop();
+    state.set(node, 2);
+    return [];
+  };
+
+  const nodes = Array.from(graph.keys()).sort();
+  for (const node of nodes) {
+    if ((state.get(node) ?? 0) !== 0) {
+      continue;
+    }
+    const cycle = visit(node);
+    if (cycle.length > 0) {
+      return cycle;
+    }
+  }
+
+  return [];
+}
+
+export function runRuntimeCycleCheck(rootArg: string, strict: boolean): RuntimeCycleCheckResult {
+  const root = path.resolve(process.cwd(), rootArg);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(
+      `Runtime root not found: ${rootArg}. Use --root <path> to point at a directory.`,
+    );
+  }
+
+  const files = walkTsFiles(root)
+    .map((file) => path.normalize(file))
+    .sort();
+  const fileSet = new Set(files);
+  const graph = new Map<string, string[]>();
+
+  for (const file of files) {
+    const source = fs.readFileSync(file, 'utf8');
+    const specifiers = extractRelativeSpecifiers(source);
+    const edges = new Set<string>();
+    for (const specifier of specifiers) {
+      const target = resolveRelativeTarget(file, specifier);
+      if (!target) {
+        continue;
+      }
+      if (fileSet.has(target)) {
+        edges.add(target);
+      }
+    }
+    graph.set(file, Array.from(edges).sort());
+  }
+
+  const cycle = detectCycle(graph);
+  return {
+    root: rootArg,
+    mode: strict ? 'strict' : 'warning',
+    fileCount: files.length,
+    hasCycle: cycle.length > 0,
+    cyclePath: cycle.map((file) => toRelativePosix(root, file)),
+  };
+}
+
+export function formatSummary(result: RuntimeCycleCheckResult): string[] {
+  const lines: string[] = [];
+  if (!result.hasCycle) {
+    lines.push(
+      `[OK] runtime cycle check (${result.mode}) - ${result.fileCount} files scanned, no cycles detected`,
+    );
+    return lines;
+  }
+
+  const heading = result.mode === 'strict' ? '[FAIL]' : '[WARN]';
+  lines.push(`${heading} runtime cycle check (${result.mode}) - cycle detected`);
+  lines.push(`  root: ${result.root}`);
+  lines.push(`  cycle: ${result.cyclePath.join(' -> ')}`);
+  lines.push('  Hint: break bidirectional imports by moving shared logic to leaf modules.');
+  return lines;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): void {
+  try {
+    const { strict, root } = parseArgs(argv);
+    const result = runRuntimeCycleCheck(root, strict);
+    for (const line of formatSummary(result)) {
+      console.log(line);
+    }
+
+    if (strict && result.hasCycle) {
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.log(`[FAIL] runtime cycle check (strict) - ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (import.meta.main) {
+  main();
+}

scripts/fixtures/runtime-cycles/acyclic/entry.ts

@@ -0,0 +1,2 @@
+import './utils';
+export { value } from './feature';

scripts/fixtures/runtime-cycles/acyclic/feature.ts

@@ -0,0 +1,3 @@
+import { utilValue } from './utils';
+
+export const value = utilValue + 1;

scripts/fixtures/runtime-cycles/acyclic/utils/index.ts

@@ -0,0 +1 @@
+export const utilValue = 1;

scripts/fixtures/runtime-cycles/cyclic/module-a.ts

@@ -0,0 +1,3 @@
+import { b } from './module-b';
+
+export const a = b + 1;

scripts/fixtures/runtime-cycles/cyclic/module-b.ts

@@ -0,0 +1 @@
+export { c as b } from './nested';

scripts/fixtures/runtime-cycles/cyclic/nested/index.ts

@@ -0,0 +1,3 @@
+import { a } from '../module-a.ts';
+
+export const c = a + 1;