vibecodedshit 0.0.0-stage → 0.2.0

package/dist/report/roadmap.js

@@ -0,0 +1,58 @@
+import { roundHalfUp } from '../scoring/aggregate.js';
+import { healthWith, nextCandidate } from '../scoring/what-if.js';
+import { rawText } from './format.js';
+export const ROADMAP_LIMIT = 10;
+const STDOUT_LIMIT = 3;
+const NO_OVERRIDES = new Map();
+/** The descriptor of the lowest-scoring anchor or level above `score`. Null when there is none or the parameter has no descriptors. */
+export function targetDescriptor(def, score) {
+    return nextCandidate(def, score)?.descriptor ?? null;
+}
+/**
+ * The parameters ranked by Gain: the whole health points the displayed health would rise by if that one parameter
+ * alone reached 100. Parameters at 100 and the not applicable or not measured ones are not listed. Empty when the
+ * run has no health score. Items with no Gain are listed only to fill the list up to the limit.
+ */
+export function buildRoadmap(run, methodology) {
+    if (!run.health)
+        return [];
+    const base = healthWith(run, methodology, NO_OVERRIDES);
+    if (base.health === null)
+        return [];
+    const items = [];
+    const dimensionOf = new Map();
+    for (const dim of methodology.dimensions) {
+        for (const def of dim.parameters) {
+            const param = run.parameters.find((p) => p.id === def.id);
+            if (!param || (param.status !== 'measured' && param.status !== 'failed'))
+                continue;
+            const score = param.status === 'failed' ? 0 : (param.score ?? 0);
+            if (score >= 100)
+                continue;
+            const after = healthWith(run, methodology, new Map([[def.id, 100]])).health ?? base.health;
+            items.push({
+                id: def.id,
+                name: def.name,
+                dimensionId: dim.id,
+                dimensionName: dim.name,
+                raw: param.status === 'measured' ? rawText(param, def) : null,
+                score,
+                gain: roundHalfUp(after) - run.health.displayed,
+                gainPrecise: after - base.health,
+                target: targetDescriptor(def, score),
+            });
+            dimensionOf.set(def.id, base.dimension.get(dim.id) ?? 0);
+        }
+    }
+    items.sort((a, b) => b.gain - a.gain || b.gainPrecise - a.gainPrecise || (dimensionOf.get(a.id) ?? 0) - (dimensionOf.get(b.id) ?? 0) || a.id.localeCompare(b.id, 'en', { numeric: true }));
+    return items.slice(0, ROADMAP_LIMIT);
+}
+export function gainText(gain) {
+    return gain > 0 ? `+${gain}` : '+0 · no gain';
+}
+/** The top lines `health report` prints after the report path: `<rank>. <id> <name> (<dimension>) +<gain> — <target>`. */
+export function roadmapLines(run, methodology) {
+    return buildRoadmap(run, methodology)
+        .slice(0, STDOUT_LIMIT)
+        .map((item, i) => `${i + 1}. ${item.id} ${item.name} (${item.dimensionName}) ${gainText(item.gain)}${item.target ? ` — ${item.target}` : ''}`);
+}

package/dist/report/scares.js

@@ -0,0 +1,83 @@
+export const SCARE_LIMIT = 3;
+export const NO_SCARES = 'Nothing in the checks below is a scare. The scan looks at committed secrets and known advisories, not access rules, so this is not a clean bill of health.';
+const records = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'object' && v !== null) : null;
+const text = (value) => (typeof value === 'string' || typeof value === 'number' ? String(value) : '');
+const SEVERITY_RANK = { critical: 4, high: 3, moderate: 2, low: 1 };
+const measured = (param) => param?.status === 'measured';
+function levels(param) {
+    if (!measured(param))
+        return [];
+    const fromRaw = param.raw?.kind === 'level' ? [param.raw.level] : [];
+    return [...fromRaw, ...(param.units ?? []).flatMap((u) => (u.raw.kind === 'level' ? [u.raw.level] : []))];
+}
+function secretScares(run, param) {
+    if (!measured(param))
+        return [];
+    const only = run.reportOnly ?? {};
+    const tree = records(only.secretsInTree) ?? [];
+    const scares = [];
+    if (tree.some((f) => f.supabaseRole === 'service_role')) {
+        scares.push('Anyone with access to your git repo can read and change all the data in your Supabase.');
+    }
+    // A Supabase anon key is public by design, so it is not a leaked secret.
+    const others = tree.filter((f) => f.supabaseRole !== 'service_role' && f.supabaseRole !== 'anon');
+    const first = others[0];
+    if (first) {
+        const more = others.length > 1 ? ` (${others.length} secrets in all)` : '';
+        scares.push(`Anyone with access to your git repo can use a secret committed in ${text(first.file)} (${text(first.ruleId)})${more}.`);
+    }
+    return scares;
+}
+function dependencyScare(run, param) {
+    if (!measured(param) || (param.score ?? 100) > 50)
+        return [];
+    const advisories = records(run.reportOnly?.productionDependencyVulnerabilities?.advisories) ?? [];
+    const worst = [...advisories].sort((a, b) => (SEVERITY_RANK[text(b.severity)] ?? 0) - (SEVERITY_RANK[text(a.severity)] ?? 0))[0];
+    const detail = worst
+        ? ` (${advisories.length} known ${advisories.length === 1 ? 'advisory' : 'advisories'}, the worst in ${text(worst.name)} ${text(worst.version)})`
+        : '';
+    return [`Your live app runs on dependencies with publicly known security holes${detail}.`];
+}
+function historyScare(run, param) {
+    if (!measured(param))
+        return [];
+    const history = records(run.reportOnly?.secretsInHistory?.findings) ?? [];
+    const inTree = new Set((records(run.reportOnly?.secretsInTree) ?? []).map((f) => `${text(f.file)}\0${text(f.ruleId)}`));
+    const gone = history.filter((f) => !inTree.has(`${text(f.file)}\0${text(f.ruleId)}`));
+    if (gone.length === 0)
+        return [];
+    return [`Deleting a key from the code did not kill it: ${gone.length === 1 ? 'a secret is' : `${gone.length} secrets are`} still readable in your git history.`];
+}
+/**
+ * The scares in severity order: plain-English consequences, not metrics. Only measured or failed parameters trigger
+ * one, so a preview simply has fewer. Never padded. Report only, never scored.
+ */
+export function buildScares(run) {
+    if (!run.valid)
+        return [];
+    const param = (id) => run.parameters.find((p) => p.id === id);
+    const scoreOf = (id) => {
+        const p = param(id);
+        return p && (p.status === 'measured' || p.status === 'failed') ? (p.status === 'failed' ? 0 : (p.score ?? 0)) : null;
+    };
+    const scares = [...secretScares(run, param('5.4')), ...dependencyScare(run, param('5.1')), ...historyScare(run, param('5.4'))];
+    if (levels(param('6.1')).some((l) => l === 'install_fails' || l === 'build_fails')) {
+        scares.push("A clean copy of this code doesn't install or build.");
+    }
+    if (scoreOf('1.1') === 0 || scoreOf('1.2') === 0)
+        scares.push('Nothing checks your changes, so your users find the breakage first.');
+    if (levels(param('5.3')).includes('none'))
+        scares.push('Two installs of the same commit can ship different code.');
+    if (scoreOf('6.4') === 0)
+        scares.push('Nothing stops broken code from reaching main.');
+    return scares.slice(0, SCARE_LIMIT);
+}
+/** What the scan could not check, named so an empty list is not read as clean. */
+export function unchecked(run) {
+    const names = [['5.4', 'secrets'], ['5.1', 'dependency advisories']];
+    return names.filter(([id]) => !run.parameters.some((p) => p.id === id && (p.status === 'measured' || p.status === 'failed'))).map(([, name]) => name);
+}
+/** The lines `health report` prints after the Roadmap lines: `Scare: <text>`. */
+export function scareLines(run) {
+    return buildScares(run).map((s) => `Scare: ${s}`);
+}

package/dist/report/style.js

@@ -0,0 +1,27 @@
+/** Inline CSS. No external font, image or request. */
+export const STYLE = `
+:root { color-scheme: light dark; --bg: #fafaf8; --fg: #1c1c1a; --muted: #6b6b66; --line: #dcdcd4; --accent: #2b5fd9; --warn: #a15c00; --card: #ffffff; }
+@media (prefers-color-scheme: dark) { :root { --bg: #151514; --fg: #ecece6; --muted: #9a9a92; --line: #33332f; --accent: #7aa2ff; --warn: #e0a040; --card: #1e1e1c; } }
+* { box-sizing: border-box; }
+body { margin: 0; padding: 32px 16px 64px; background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, sans-serif; }
+main { max-width: 960px; margin: 0 auto; }
+h1 { font-size: 22px; margin: 0 0 4px; }
+h2 { font-size: 17px; margin: 40px 0 8px; padding-top: 16px; border-top: 1px solid var(--line); }
+.muted { color: var(--muted); }
+.health { display: flex; gap: 24px; align-items: baseline; margin: 16px 0 8px; }
+.health .score { font-size: 56px; font-weight: 700; line-height: 1; }
+.health .band { font-size: 22px; font-weight: 600; }
+.label { display: inline-block; padding: 2px 10px; border: 1px solid var(--warn); color: var(--warn); border-radius: 4px; font-weight: 600; }
+table { width: 100%; border-collapse: collapse; background: var(--card); font-size: 14px; }
+th, td { text-align: left; padding: 6px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+th { font-weight: 600; color: var(--muted); }
+td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+.bar { position: relative; min-width: 80px; height: 10px; background: var(--line); border-radius: 5px; overflow: hidden; margin: 6px 0; }
+.bar span { display: block; height: 100%; background: var(--accent); }
+.bar i { position: absolute; top: 0; bottom: 0; width: 2px; background: var(--bg); }
+a { color: var(--accent); }
+code { font: 13px ui-monospace, monospace; word-break: break-all; }
+.status-not_measured, .status-not_applicable { color: var(--muted); }
+.status-failed { color: var(--warn); font-weight: 600; }
+.note { color: var(--warn); margin: 4px 0 8px; }
+`;

package/dist/report-only/hotspots.js

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process';
+const HOTSPOT_LIMIT = 20;
+export const SHALLOW_WARNING = 'history is shallow; churn is a lower bound';
+/** `[asOf minus 12 months, end of asOf day]`, UTC, as ISO strings git accepts. */
+export function churnWindow(asOf) {
+    const start = new Date(`${asOf}T00:00:00Z`);
+    start.setUTCFullYear(start.getUTCFullYear() - 1);
+    return { since: `${start.toISOString().slice(0, 10)}T00:00:00+00:00`, until: `${asOf}T23:59:59+00:00` };
+}
+function git(repoPath, args) {
+    const result = spawnSync('git', ['-C', repoPath, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    return { status: result.error ? null : result.status, stdout: result.stdout };
+}
+/** Commits per path in the window, merges and renames ignored. */
+function churnByPath(repoPath, asOf) {
+    const { since, until } = churnWindow(asOf);
+    const log = git(repoPath, ['log', `--since=${since}`, `--until=${until}`, '--no-merges', '--no-renames', '--name-only', '-z', '--format=']);
+    if (log.status !== 0)
+        return null;
+    const churn = new Map();
+    for (const name of log.stdout.split('\0')) {
+        if (name === '')
+            continue;
+        churn.set(name, (churn.get(name) ?? 0) + 1);
+    }
+    return churn;
+}
+/**
+ * Files ranked by churn times complexity. Files with no churn or no complexity are left out.
+ * Only the files in `complexity` (logic files in scope that exist at HEAD) can appear.
+ */
+export function computeHotspots(repoPath, asOf, complexity) {
+    const warnings = [];
+    const churn = churnByPath(repoPath, asOf);
+    if (churn === null)
+        return { hotspots: [], warnings: ['hotspots: git history could not be read'] };
+    if (git(repoPath, ['rev-parse', '--is-shallow-repository']).stdout.trim() === 'true')
+        warnings.push(SHALLOW_WARNING);
+    const hotspots = [];
+    for (const entry of complexity) {
+        const commits = churn.get(entry.file) ?? 0;
+        if (commits === 0 || entry.complexitySum === 0)
+            continue;
+        hotspots.push({ path: entry.file, churn: commits, complexity: entry.complexitySum, score: commits * entry.complexitySum });
+    }
+    hotspots.sort((a, b) => b.score - a.score || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return { hotspots: hotspots.slice(0, HOTSPOT_LIMIT), warnings };
+}

package/dist/route/check.js

@@ -0,0 +1,37 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { ROUTE_FILE, SLICE_FILE, TASK_PLACEHOLDER } from './files.js';
+/** The problems with `dir` compared to the files regenerated from run.json. Empty when the facts match and every Task is written. */
+export function checkRouteFiles(dir, expected) {
+    if (!existsSync(dir))
+        return [`${dir} does not exist`];
+    const problems = [];
+    const known = new Set(expected.map((f) => f.name));
+    for (const name of readdirSync(dir)) {
+        if ((name === ROUTE_FILE || SLICE_FILE.test(name)) && !known.has(name))
+            problems.push(`${name}: not part of this Route`);
+    }
+    for (const file of expected) {
+        const full = path.join(dir, file.name);
+        if (!existsSync(full)) {
+            problems.push(`${file.name}: missing`);
+            continue;
+        }
+        const actual = readFileSync(full, 'utf8');
+        if (!actual.startsWith(file.fixed)) {
+            problems.push(`${file.name}: facts differ from run.json`);
+            continue;
+        }
+        if (file.name === ROUTE_FILE) {
+            if (actual !== file.content)
+                problems.push(`${file.name}: facts differ from run.json`);
+            continue;
+        }
+        const task = actual.slice(file.fixed.length);
+        if (task.includes(TASK_PLACEHOLDER))
+            problems.push(`${file.name}: Task placeholder not replaced`);
+        else if (task.trim() === '')
+            problems.push(`${file.name}: Task is empty`);
+    }
+    return problems;
+}

package/dist/route/files.js

@@ -0,0 +1,74 @@
+import { nearestDescriptor, rawText } from '../report/format.js';
+import { outOfReachLine } from './select.js';
+export const FACTS_START = '<!-- health:facts:start -->';
+export const FACTS_END = '<!-- health:facts:end -->';
+export const TASK_PLACEHOLDER = '<!-- health:task -->';
+export const ROUTE_FILE = 'ROUTE.md';
+export const SLICE_FILE = /^\d{2}-.+\.md$/;
+const WHERE_LIMIT = 10;
+const kebab = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+export function sliceFileName(slice) {
+    return `${String(slice.position).padStart(2, '0')}-${slice.id.replace('.', '-')}-${kebab(slice.name)}.md`;
+}
+function whereLines(run, slice, param) {
+    const units = [...(param?.units ?? [])]
+        .sort((a, b) => a.score - b.score || a.package.localeCompare(b.package) || a.group.localeCompare(b.group))
+        .slice(0, WHERE_LIMIT)
+        .map((u) => `- package \`${u.package}\` (${u.group}), score ${Math.round(u.score)}`);
+    const hotspots = slice.id === '4.1' && Array.isArray(run.reportOnly?.hotspots)
+        ? run.reportOnly.hotspots
+            .flatMap((h) => (typeof h === 'object' && h !== null && typeof h.path === 'string' ? [h.path] : []))
+            .slice(0, WHERE_LIMIT)
+            .map((file) => `- file \`${file}\` (hotspot)`)
+        : [];
+    const lines = [...units, ...hotspots];
+    return lines.length > 0 ? lines : ['- the whole repository'];
+}
+function sliceFacts(run, def, slice) {
+    const param = run.parameters.find((p) => p.id === slice.id);
+    const current = param?.status === 'measured' ? rawText(param, def) : 'no usable result';
+    const nearest = nearestDescriptor(def, slice.fromScore);
+    return [
+        FACTS_START,
+        `**Goal:** Raise ${slice.id} ${slice.name} from ${Math.round(slice.fromScore)} to ${Math.round(slice.toScore)}: "${slice.descriptor}"`,
+        '',
+        `**Why:** Today it is ${current} (score ${Math.round(slice.fromScore)})${nearest ? `, which the methodology describes as "${nearest}"` : ''}.`,
+        '',
+        '**Where:**',
+        ...whereLines(run, slice, param),
+        '',
+        `**Health effect:** health ${slice.healthBefore} -> ${slice.healthAfter} once this Slice and the ones before it are done.`,
+        '',
+        `**Done when:** re-running /codebase-health shows ${slice.id} ${slice.name} at ${Math.round(slice.toScore)} or higher ("${slice.descriptor}").`,
+        '',
+        '**Rules:** Raise the score by changing the code, not the measurement. Do not edit .healthignore, .gitleaksignore, lint, type or test configuration to hide findings, and do not delete, skip or weaken tests.',
+        FACTS_END,
+    ].join('\n');
+}
+function sliceFile(run, methodology, slice) {
+    const def = methodology.dimensions.flatMap((d) => d.parameters).find((p) => p.id === slice.id);
+    if (!def)
+        throw new Error(`No parameter ${slice.id} in the methodology`);
+    const fixed = `# ${String(slice.position).padStart(2, '0')}. ${slice.id} ${slice.name}\n\n${sliceFacts(run, def, slice)}\n\n## Task\n`;
+    return { name: sliceFileName(slice), fixed, content: `${fixed}\n${TASK_PLACEHOLDER}\n` };
+}
+function routeIndex(plan) {
+    const lines = [`# Route to ${plan.target.name}`, '', `${plan.slices.length} Slices take health from ${plan.from} to ${plan.to}. Hand them to your agent one at a time, in this order, as a goal each.`];
+    if (!plan.reached)
+        lines.push('', outOfReachLine(plan));
+    if (plan.unmeasured.length > 0)
+        lines.push('', `Not measured in this run, so this Route leaves them out: ${plan.unmeasured.join(', ')}.`);
+    if (plan.slices.length > 0) {
+        lines.push('', '| # | Slice | Health after |', '| --- | --- | --- |');
+        for (const slice of plan.slices)
+            lines.push(`| ${slice.position} | [${slice.id} ${slice.name}](${sliceFileName(slice)}) | ${slice.healthAfter} |`);
+    }
+    const text = `${lines.join('\n')}\n`;
+    return { name: ROUTE_FILE, fixed: text, content: text };
+}
+/** ROUTE.md and one file per Slice, the same on every call for the same run.json. Empty unless the plan is a Route. */
+export function buildRouteFiles(run, methodology, plan) {
+    if (plan.kind !== 'route')
+        return [];
+    return [routeIndex(plan), ...plan.slices.map((slice) => sliceFile(run, methodology, slice))];
+}

package/dist/route/order.js

@@ -0,0 +1,22 @@
+/**
+ * The fixed order Slices are written in (ADR 0001): secrets and known vulnerabilities, then the repo installs, builds
+ * and verifies, then the safety net, then types and lint, then CI and docs. Structural refactors and major upgrades
+ * (3.x, 4.x, 5.2) come last. It is advice about working order, so it lives here and not in the methodology YAML.
+ */
+const PRECEDENCE = [
+    '5.4', '5.1',
+    '6.1', '5.3', '5.5', '6.2', '6.5',
+    '1.1', '1.4', '1.2', '1.3', '1.5',
+    '2.1', '2.2', '2.5', '2.3', '2.4',
+    '6.4', '6.6', '6.3',
+];
+const LAST_GROUPS = ['3', '4'];
+/** Lower ranks are written first. Parameters not in the list go last: 3.x, then 4.x, then everything else (5.2). */
+export function precedenceRank(id) {
+    const listed = PRECEDENCE.indexOf(id);
+    if (listed >= 0)
+        return listed;
+    const [dimension = '', index = '0'] = id.split('.');
+    const group = LAST_GROUPS.indexOf(dimension);
+    return PRECEDENCE.length + (group >= 0 ? group : LAST_GROUPS.length) * 100 + Number(index);
+}

package/dist/route/select.js

@@ -0,0 +1,114 @@
+import { roundHalfUp } from '../scoring/aggregate.js';
+import { healthWith, nextCandidate } from '../scoring/what-if.js';
+import { precedenceRank } from './order.js';
+export const PREVIEW_LINE = 'Install Docker for a full run to get your Route';
+/** Vibe-coded and Fragile aim at Stable, Stable at Agent-ready, Agent-ready at nothing. The bounds come from the YAML. */
+export function targetBand(current, methodology) {
+    const bands = [...methodology.bands].sort((a, b) => a.min - b.min);
+    const stable = bands.findIndex((b) => b.key === 'stable');
+    const at = bands.findIndex((b) => b.key === current);
+    if (stable < 0 || at < 0 || at > stable)
+        return null;
+    return at < stable ? (bands[stable] ?? null) : (bands[stable + 1] ?? null);
+}
+function currentScore(run, id, overrides) {
+    const override = overrides.get(id);
+    if (override !== undefined)
+        return override;
+    const param = run.parameters.find((p) => p.id === id);
+    if (param?.status === 'failed')
+        return 0;
+    if (param?.status === 'measured')
+        return param.score ?? 0;
+    return null;
+}
+/** The greedy Steps: each is the one that raises the displayed health most, until the Target band is reached or no Step adds health. */
+function selectSteps(run, methodology, target) {
+    const overrides = new Map();
+    const steps = [];
+    for (;;) {
+        const base = healthWith(run, methodology, overrides);
+        if (base.health === null)
+            return { steps, reached: false };
+        const displayed = roundHalfUp(base.health);
+        if (displayed >= target.min)
+            return { steps, reached: true };
+        let best = null;
+        for (const dim of methodology.dimensions) {
+            for (const def of dim.parameters) {
+                const score = currentScore(run, def.id, overrides);
+                if (score === null)
+                    continue;
+                const candidate = nextCandidate(def, score);
+                if (!candidate)
+                    continue;
+                const after = healthWith(run, methodology, new Map([...overrides, [def.id, candidate.score]])).health;
+                if (after === null || after - base.health <= 1e-9)
+                    continue;
+                const entry = {
+                    step: { id: def.id, name: def.name, dimensionId: dim.id, fromScore: score, toScore: candidate.score, descriptor: candidate.descriptor },
+                    rise: roundHalfUp(after) - displayed,
+                    precise: after - base.health,
+                    dimensionScore: base.dimension.get(dim.id) ?? 0,
+                };
+                if (!best ||
+                    entry.rise > best.rise ||
+                    (entry.rise === best.rise &&
+                        (entry.precise > best.precise + 1e-9 ||
+                            (Math.abs(entry.precise - best.precise) <= 1e-9 &&
+                                (entry.dimensionScore < best.dimensionScore || (entry.dimensionScore === best.dimensionScore && entry.step.id.localeCompare(best.step.id, 'en', { numeric: true }) < 0)))))) {
+                    best = entry;
+                }
+            }
+        }
+        if (!best)
+            return { steps, reached: false };
+        overrides.set(best.step.id, best.step.toScore);
+        steps.push(best.step);
+    }
+}
+/** The Route for a run: Steps chosen by Gain, then written as Slices in the fixed precedence with the health after each. */
+export function buildRoute(run, methodology) {
+    if (!run.health)
+        return { kind: 'none' };
+    const target = targetBand(run.health.band, methodology);
+    if (!target)
+        return { kind: 'none' };
+    if (run.mode === 'preview')
+        return { kind: 'preview' };
+    const { steps, reached } = selectSteps(run, methodology, target);
+    const ordered = [...steps].sort((a, b) => precedenceRank(a.id) - precedenceRank(b.id) || a.toScore - b.toScore);
+    const overrides = new Map();
+    let before = run.health.displayed;
+    const slices = ordered.map((step, i) => {
+        overrides.set(step.id, step.toScore);
+        const after = roundHalfUp(healthWith(run, methodology, overrides).health ?? before);
+        const slice = { ...step, position: i + 1, healthBefore: before, healthAfter: after };
+        before = after;
+        return slice;
+    });
+    return {
+        kind: 'route',
+        target,
+        from: run.health.displayed,
+        to: before,
+        reached,
+        unmeasured: run.parameters.filter((p) => p.status === 'not_measured').map((p) => p.id),
+        slices,
+    };
+}
+/** The stdout lines: the summary, plus the out-of-reach line when the Target band is not reached. A preview gets its one line, Agent-ready nothing. */
+export function routeLines(plan) {
+    if (plan.kind === 'preview')
+        return [PREVIEW_LINE];
+    if (plan.kind === 'none')
+        return [];
+    const lines = [`Route to ${plan.target.name}: ${plan.slices.length} Slices, ${plan.from} -> ${plan.to}`];
+    if (!plan.reached)
+        lines.push(outOfReachLine(plan));
+    return lines;
+}
+export function outOfReachLine(plan) {
+    const reason = plan.unmeasured.length > 0 ? `until ${plan.unmeasured.join(', ')} are measured` : 'with the parameters measured, because no further Step adds health';
+    return `${plan.target.name} is out of reach ${reason}; this Route gets you to ${plan.to}`;
+}

package/dist/route/write.js

@@ -0,0 +1,13 @@
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { ROUTE_FILE, SLICE_FILE } from './files.js';
+/** Deletes the earlier ROUTE.md and Slice files in `dir` (nothing else), then writes the new ones. */
+export function writeRouteFiles(dir, files) {
+    mkdirSync(dir, { recursive: true });
+    for (const name of readdirSync(dir)) {
+        if (name === ROUTE_FILE || SLICE_FILE.test(name))
+            rmSync(path.join(dir, name), { force: true });
+    }
+    for (const file of files)
+        writeFileSync(path.join(dir, file.name), file.content, 'utf8');
+}

package/dist/run/read.js

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+export class RunReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RunReadError';
+    }
+}
+const nullableScore = z.number().nullable();
+/** The fields `report` and `diff` read. Unknown fields pass through untouched. */
+const runFileSchema = z.looseObject({
+    schemaVersion: z.literal(1),
+    valid: z.boolean(),
+    invalidReason: z.string().optional(),
+    warnings: z.array(z.string()),
+    methodology: z.looseObject({ version: z.string() }),
+    mode: z.enum(['preview', 'full']),
+    comparable: z.boolean(),
+    comparableReason: z.string().optional(),
+    asOf: z.string(),
+    layers: z.array(z.enum(['static', 'execution'])),
+    repo: z.looseObject({ path: z.string(), headCommit: z.string().nullable(), treeHash: z.string().nullable() }),
+    tools: z.record(z.string(), z.unknown()),
+    execution: z
+        .looseObject({
+        feedbackLoop: z.looseObject({ typecheckSeconds: z.number(), lintSeconds: z.number(), testSeconds: z.number(), totalSeconds: z.number() }),
+        roots: z
+            .array(z.looseObject({
+            dir: z.string(),
+            group: z.string(),
+            install: z.enum(['ok', 'failed', 'timeout']).nullable(),
+            exitCode: z.number().nullable(),
+        }))
+            .optional(),
+    })
+        .optional(),
+    reportOnly: z.record(z.string(), z.unknown()).optional(),
+    ignoreSet: z.looseObject({
+        healthignoreSha256: z.string().nullable(),
+        gitleaksignoreSha256: z.string().nullable(),
+        excludedLinesPercent: z.number(),
+    }),
+    scope: z.looseObject({ logicFiles: z.number(), logicLines: z.number(), sourceLines: z.number(), packages: z.array(z.string()) }),
+    parameters: z.array(z.looseObject({
+        id: z.string(),
+        status: z.enum(['measured', 'not_applicable', 'not_measured', 'failed']),
+        reason: z.string().optional(),
+        weight: z.number(),
+        raw: z.looseObject({ kind: z.enum(['ratio', 'level', 'number', 'components', 'failed']) }).nullable().optional(),
+        score: z.number().optional(),
+        units: z.array(z.looseObject({ package: z.string(), group: z.string(), weight: z.number(), raw: z.looseObject({}), score: z.number() })).optional(),
+    })),
+    dimensions: z.array(z.looseObject({ id: z.number(), key: z.string(), score: nullableScore })),
+    breakdown: z.looseObject({
+        byPackage: z.record(z.string(), z.record(z.string(), nullableScore)),
+        byGroup: z.record(z.string(), z.record(z.string(), nullableScore)),
+    }),
+    health: z.looseObject({ score: z.number(), displayed: z.number(), band: z.string() }).nullable(),
+});
+/** Parse a run.json document. Throws RunReadError naming the file for anything but a valid version 1 run. */
+export function parseRun(text, file) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (err) {
+        throw new RunReadError(`${file}: not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (typeof doc === 'object' && doc !== null && 'schemaVersion' in doc && doc.schemaVersion !== 1) {
+        throw new RunReadError(`${file}: unsupported schemaVersion ${JSON.stringify(doc.schemaVersion)} (this CLI reads 1)`);
+    }
+    const result = runFileSchema.safeParse(doc);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const where = issue && issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        throw new RunReadError(`${file}: not a run.json: ${where}: ${issue?.message ?? 'invalid'}`);
+    }
+    return result.data;
+}
+export function readRun(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        throw new RunReadError(`${file}: cannot read (${err instanceof Error ? err.message : String(err)})`);
+    }
+    return parseRun(text, file);
+}

package/dist/run/recompute.js

@@ -0,0 +1,19 @@
+import { poolParameter } from '../scoring/pool.js';
+import { dimensionScores, healthFrom } from './score-run.js';
+/** Re-derive every score from the stored raw values. */
+export function recompute(run, methodology) {
+    const defs = new Map(methodology.dimensions.flatMap((d) => d.parameters).map((p) => [p.id, p]));
+    const parameters = run.parameters.map((param) => {
+        const def = defs.get(param.id);
+        if (!def)
+            throw new Error(`run.json names unknown parameter ${param.id}`);
+        if (param.status === 'failed')
+            return { ...param, score: 0 };
+        if (param.status !== 'measured')
+            return param;
+        const pooled = poolParameter(def, param.units ?? []);
+        return { ...param, raw: pooled.raw, score: pooled.score, units: pooled.units };
+    });
+    const dimensions = dimensionScores(methodology, parameters);
+    return { parameters, dimensions, health: healthFrom(methodology, dimensions) };
+}