vibecodedshit 0.0.0-stage → 0.3.0

package/dist/python/typing.js

@@ -0,0 +1,27 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolError } from '../scope/types.js';
+const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'python', 'typing_helper.py');
+/** Typing facts of every file, with one helper process. */
+export function analyzePythonTyping(repoPath, files) {
+    if (files.length === 0)
+        return {};
+    const result = spawnSync('python3', [helperPath], {
+        cwd: repoPath,
+        input: JSON.stringify({ files }),
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (result.error)
+        throw new ToolError(`Could not run python3: ${result.error.message}`);
+    if (result.status !== 0) {
+        throw new ToolError(`typing_helper.py failed: ${result.stderr.trim() || `exit ${String(result.status)}`}`);
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ToolError('typing_helper.py printed invalid JSON');
+    }
+}

package/dist/report/escape.js

@@ -0,0 +1,5 @@
+const ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+/** Every dynamic string in the report goes through this: package names, paths and reasons are untrusted. */
+export function escapeHtml(value) {
+    return String(value).replace(/[&<>"']/g, (c) => ENTITIES[c] ?? c);
+}

package/dist/report/format.js

@@ -0,0 +1,75 @@
+import { roundHalfUp } from '../scoring/aggregate.js';
+function round1(value) {
+    return roundHalfUp(value, 1).toFixed(1);
+}
+function scaleLabel(scale) {
+    if (scale === 100)
+        return '%';
+    if (scale === 1000)
+        return ' per 1,000';
+    return ` per ${scale}`;
+}
+function formatRaw(raw, unit) {
+    switch (raw.kind) {
+        case 'ratio':
+            return raw.denominator === 0
+                ? `${raw.numerator} / 0`
+                : `${raw.numerator} / ${raw.denominator} (${round1((raw.numerator / raw.denominator) * raw.scale)}${scaleLabel(raw.scale)})`;
+        case 'level':
+            return raw.level;
+        case 'number':
+            return `${raw.value} ${unit}`;
+        case 'failed':
+            return 'install failed';
+        case 'components':
+            return Object.entries(raw.components)
+                .map(([key, part]) => `${key}: ${formatRaw(part, unit)}`)
+                .join('; ');
+    }
+}
+/** The raw value as the report prints it. Level parameters have no pooled raw, so their units' levels are listed. */
+export function rawText(param, def) {
+    if (param.raw)
+        return formatRaw(param.raw, def.raw.unit);
+    const levels = [...new Set((param.units ?? []).flatMap((u) => (u.raw.kind === 'level' ? [u.raw.level] : [])))];
+    if (levels.length > 0)
+        return levels.join(', ');
+    const components = (param.units ?? []).flatMap((u) => (u.raw.kind === 'components' ? [u.raw] : []));
+    if (components.length > 0)
+        return components.map((c) => formatRaw(c, def.raw.unit)).join(' | ');
+    return 'no data';
+}
+/**
+ * The descriptor of the anchor or level whose score is closest to the parameter's score, ties to the lower score.
+ * Null for parameters without descriptors (components).
+ */
+export function nearestDescriptor(def, score) {
+    const scoring = def.scoring;
+    let candidates;
+    if (scoring.method === 'piecewise_linear')
+        candidates = scoring.anchors;
+    else if (scoring.method === 'levels')
+        candidates = Array.isArray(scoring.levels) ? scoring.levels : Object.values(scoring.levels).flat();
+    else
+        return null;
+    let best;
+    for (const candidate of candidates) {
+        if (!candidate.descriptor)
+            continue;
+        if (!best) {
+            best = candidate;
+            continue;
+        }
+        const gap = Math.abs(candidate.score - score);
+        const bestGap = Math.abs(best.score - score);
+        if (gap < bestGap - 1e-9 || (Math.abs(gap - bestGap) <= 1e-9 && candidate.score < best.score))
+            best = candidate;
+    }
+    return best?.descriptor?.replace(/\s+/g, ' ').trim() ?? null;
+}
+export function statusText(status) {
+    return status.replace('_', ' ');
+}
+export function scoreText(score) {
+    return score === null || score === undefined ? '–' : String(roundHalfUp(score));
+}

package/dist/report/render.js

@@ -0,0 +1,213 @@
+import { SHALLOW_WARNING } from '../report-only/hotspots.js';
+import { escapeHtml as e } from './escape.js';
+import { nearestDescriptor, rawText, scoreText, statusText } from './format.js';
+import { buildRoute, routeLines } from '../route/select.js';
+import { buildRoadmap, gainText, ROADMAP_LIMIT } from './roadmap.js';
+import { NO_SCARES, buildScares, unchecked } from './scares.js';
+import { STYLE } from './style.js';
+const HELP_URL = 'https://vibecodedshit.com';
+const NOT_COLLECTED = '<p class="muted">not collected</p>';
+function table(head, rows) {
+    const th = head.map((h) => `<th${h.num ? ' class="num"' : ''}>${e(h.text)}</th>`).join('');
+    const body = rows
+        .map((row) => `<tr>${row.map((cell, i) => `<td${head[i]?.num ? ' class="num"' : ''}>${cell}</td>`).join('')}</tr>`)
+        .join('\n');
+    return `<table><thead><tr>${th}</tr></thead><tbody>\n${body}\n</tbody></table>`;
+}
+function bar(percent, marks = []) {
+    const width = Math.max(0, Math.min(100, percent));
+    const ticks = marks.map((m) => `<i style="left:${m}%"></i>`).join('');
+    return `<div class="bar"><span style="width:${width}%"></span>${ticks}</div>`;
+}
+function asRecords(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.filter((v) => typeof v === 'object' && v !== null);
+}
+const str = (v) => (typeof v === 'string' || typeof v === 'number' ? String(v) : '');
+function header(run, methodology) {
+    const parts = ['<h1>Codebase health report</h1>'];
+    parts.push(`<p class="muted">${e(run.repo.path)} · ${run.repo.headCommit ? `commit <code>${e(run.repo.headCommit.slice(0, 12))}</code> · ` : ''}as of ${e(run.asOf)} · methodology ${e(run.methodology.version)} · ${e(run.mode)} run</p>`);
+    if (run.mode === 'preview' || !run.comparable) {
+        parts.push(`<p><span class="label">${e(run.comparableReason ?? 'preview, not comparable')}</span></p>`);
+    }
+    if (run.health) {
+        const band = methodology.bands.find((b) => b.key === run.health?.band);
+        parts.push(`<div class="health"><span class="score">${e(run.health.displayed)}</span><span class="band">${e(band?.name ?? run.health.band)}</span></div>`, bar(run.health.displayed, methodology.bands.slice(1).map((b) => b.min)), `<p>${e(band?.meaning?.replace(/\s+/g, ' ').trim() ?? '')}</p>`);
+    }
+    else {
+        parts.push('<p class="muted">no health score</p>');
+    }
+    return parts.join('\n');
+}
+function scaresSection(run) {
+    const scares = buildScares(run);
+    const parts = ['<h2>Top scares</h2>'];
+    if (scares.length > 0)
+        parts.push(`<ol>${scares.map((s) => `<li>${e(s)}</li>`).join('')}</ol>`);
+    else
+        parts.push(`<p>${e(NO_SCARES)}</p>`);
+    const missing = unchecked(run);
+    if (missing.length > 0)
+        parts.push(`<p class="muted">Not checked in this run: ${e(missing.join(', '))}.</p>`);
+    return parts.join('\n');
+}
+function dimensionsSection(run, methodology) {
+    const rows = methodology.dimensions.map((def) => {
+        const score = run.dimensions.find((d) => d.id === def.id)?.score ?? null;
+        return [
+            e(`${def.id}`),
+            e(def.name),
+            score === null ? '<span class="muted">not scored</span>' : e(scoreText(score)),
+            score === null ? '' : bar(score),
+        ];
+    });
+    return `<h2>Dimensions</h2>\n${table([{ text: '#' }, { text: 'Dimension' }, { text: 'Score', num: true }, { text: '' }], rows)}`;
+}
+function roadmapSection(run, methodology) {
+    const parts = ['<h2>Roadmap</h2>'];
+    const items = buildRoadmap(run, methodology);
+    if (!run.health) {
+        parts.push('<p class="muted">no roadmap</p>');
+        return parts.join('\n');
+    }
+    parts.push(`<p class="muted">The parameters ranked by Gain: the whole health points the health would rise by if that one parameter alone reached 100. Gains are independent and do not add up, because the dimension means and the cap interact. Top ${ROADMAP_LIMIT}.</p>`);
+    if (run.mode === 'preview')
+        parts.push('<p class="muted">Execution-layer parameters were not measured, so they are not ranked.</p>');
+    if (items.length === 0)
+        parts.push('<p class="muted">no parameter is below 100</p>');
+    else {
+        const top = Math.max(1, ...items.map((i) => i.gain));
+        parts.push(table([{ text: '#', num: true }, { text: 'Parameter' }, { text: 'Dimension' }, { text: 'Raw value' }, { text: 'Score', num: true }, { text: 'Gain', num: true }, { text: '' }, { text: 'Next anchor' }], items.map((item, i) => [
+            String(i + 1),
+            `${e(item.id)} ${e(item.name)}`,
+            e(item.dimensionName),
+            item.raw === null ? '–' : e(item.raw),
+            e(scoreText(item.score)),
+            e(gainText(item.gain)),
+            bar((item.gain / top) * 100),
+            item.target ? e(item.target) : '–',
+        ])));
+    }
+    if (run.health.band === 'vibe_coded' || run.health.band === 'fragile') {
+        parts.push(`<p>If you want help working through this roadmap to Stable, Peter Kisel takes on this work: <a href="${HELP_URL}">${HELP_URL}</a></p>`);
+    }
+    return parts.join('\n');
+}
+function routeSection(run, methodology) {
+    const plan = buildRoute(run, methodology);
+    if (plan.kind === 'none')
+        return '';
+    const lines = routeLines(plan);
+    if (plan.kind === 'preview')
+        return `<h2>Route</h2>\n<p class="muted">${e(lines.join(' '))}</p>`;
+    const parts = [`<h2>Route to ${e(plan.target.name)}</h2>`, ...lines.map((line) => `<p>${e(line)}</p>`)];
+    if (plan.unmeasured.length > 0)
+        parts.push(`<p class="muted">Not measured in this run, so the Route leaves them out: ${e(plan.unmeasured.join(', '))}.</p>`);
+    if (plan.slices.length > 0) {
+        parts.push(table([{ text: '#', num: true }, { text: 'Step' }, { text: 'Score', num: true }, { text: 'Health after', num: true }, { text: 'Target' }], plan.slices.map((s) => [String(s.position), `${e(s.id)} ${e(s.name)}`, e(`${scoreText(s.fromScore)} → ${scoreText(s.toScore)}`), e(s.healthAfter), e(s.descriptor)])));
+    }
+    return parts.join('\n');
+}
+function parametersSection(run, methodology) {
+    const defs = new Map(methodology.dimensions.flatMap((d) => d.parameters).map((p) => [p.id, p]));
+    const rows = run.parameters.map((param) => {
+        const def = defs.get(param.id);
+        const status = `<span class="status-${e(param.status)}">${e(statusText(param.status))}</span>${param.reason ? ` <span class="muted">(${e(param.reason)})</span>` : ''}`;
+        const scored = param.status === 'measured' || param.status === 'failed';
+        const raw = def && param.status === 'measured' ? e(rawText(param, def)) : '–';
+        const descriptor = def && param.status === 'measured' && param.score !== undefined ? nearestDescriptor(def, param.score) : null;
+        return [e(param.id), e(def?.name ?? param.id), raw, scored ? e(scoreText(param.score)) : '–', status, descriptor ? e(descriptor) : '–'];
+    });
+    return `<h2>Parameters</h2>\n${table([{ text: 'ID' }, { text: 'Parameter' }, { text: 'Raw value' }, { text: 'Score', num: true }, { text: 'Status' }, { text: 'Nearest anchor' }], rows)}`;
+}
+function breakdownTable(title, byKey, methodology) {
+    const keys = Object.keys(byKey).sort();
+    if (keys.length === 0)
+        return `<h3>${e(title)}</h3>\n<p class="muted">no units</p>`;
+    const head = [{ text: title.replace(/^By /, '') }, ...methodology.dimensions.map((d) => ({ text: `${d.id} ${d.name}`, num: true }))];
+    const rows = keys.map((key) => [
+        `<code>${e(key)}</code>`,
+        ...methodology.dimensions.map((d) => e(scoreText(byKey[key]?.[String(d.id)]))),
+    ]);
+    return `<h3>${e(title)}</h3>\n${table(head, rows)}`;
+}
+function breakdownSection(run, methodology) {
+    return `<h2>Breakdown</h2>\n${breakdownTable('By package', run.breakdown.byPackage, methodology)}\n${breakdownTable('By language group', run.breakdown.byGroup, methodology)}`;
+}
+function excludedSection(run) {
+    return `<h2>Excluded lines</h2>\n<p>${e(run.ignoreSet.excludedLinesPercent)}% of lines excluded by .healthignore</p>`;
+}
+function secretsHtml(value) {
+    const record = typeof value === 'object' && value !== null ? value : null;
+    const findings = asRecords(record?.findings);
+    if (!findings)
+        return NOT_COLLECTED;
+    if (findings.length === 0)
+        return '<p class="muted">none found</p>';
+    return table([{ text: 'Rule' }, { text: 'File' }, { text: 'Commit' }], findings.map((f) => [e(str(f.ruleId)), `<code>${e(str(f.file))}</code>`, `<code>${e(str(f.commit).slice(0, 8))}</code>`]));
+}
+function vulnerabilitiesHtml(value) {
+    const record = typeof value === 'object' && value !== null ? value : null;
+    const advisories = asRecords(record?.advisories);
+    if (!advisories)
+        return NOT_COLLECTED;
+    if (advisories.length === 0)
+        return '<p class="muted">none found</p>';
+    return table([{ text: 'Package' }, { text: 'Advisory' }, { text: 'Severity' }], advisories.map((a) => [`<code>${e(str(a.name))}</code>`, e(str(a.id)), e(str(a.severity))]));
+}
+function reportOnlySection(run) {
+    const only = run.reportOnly ?? {};
+    return [
+        '<h2>Report-only items</h2>',
+        '<p class="muted">These never change a score.</p>',
+        '<h3>Secrets in git history</h3>',
+        secretsHtml(only.secretsInHistory),
+        '<h3>Development-dependency vulnerabilities</h3>',
+        vulnerabilitiesHtml(only.devDependencyVulnerabilities),
+    ].join('\n');
+}
+function hotspotsSection(run) {
+    const hotspots = asRecords(run.reportOnly?.hotspots);
+    const parts = ['<h2>Fix these first</h2>', '<p class="muted">Files ranked by commits in the last 12 months times cognitive complexity.</p>'];
+    if (run.warnings.includes(SHALLOW_WARNING))
+        parts.push(`<p class="note">${e(SHALLOW_WARNING)}</p>`);
+    if (!hotspots)
+        parts.push(NOT_COLLECTED);
+    else if (hotspots.length === 0)
+        parts.push('<p class="muted">no file has both churn and complexity</p>');
+    else {
+        parts.push(table([{ text: 'File' }, { text: 'Commits', num: true }, { text: 'Complexity', num: true }, { text: 'Score', num: true }], hotspots.map((h) => [`<code>${e(str(h.path))}</code>`, e(str(h.churn)), e(str(h.complexity)), e(str(h.score))])));
+    }
+    return parts.join('\n');
+}
+/** One self-contained HTML document. Inline CSS, no script, no external reference, no clock value. */
+export function renderReport(run, methodology) {
+    const sections = [
+        header(run, methodology),
+        scaresSection(run),
+        dimensionsSection(run, methodology),
+        roadmapSection(run, methodology),
+        routeSection(run, methodology),
+        parametersSection(run, methodology),
+        breakdownSection(run, methodology),
+        excludedSection(run),
+        reportOnlySection(run),
+        hotspotsSection(run),
+    ];
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Codebase health report</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+${sections.filter((section) => section !== '').join('\n')}
+</main>
+</body>
+</html>
+`;
+}

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))];
+}