vibecodedshit 0.0.0-stage → 0.2.0

package/dist/methodology/schema.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+const anchor = z.object({ raw: z.number(), score: z.number(), descriptor: z.string().optional() });
+const levelEntry = z.object({ level: z.string(), score: z.number(), descriptor: z.string().optional() });
+const component = z.object({
+    key: z.string(),
+    method: z.enum(['levels', 'ratio']),
+    levels: z.array(levelEntry).optional(),
+    definition: z.string().optional(),
+    measure: z.string().optional(),
+});
+const scoring = z.discriminatedUnion('method', [
+    z.object({ method: z.literal('piecewise_linear'), anchors: z.array(anchor).min(2) }),
+    z.object({
+        method: z.literal('levels'),
+        levels: z.union([z.array(levelEntry), z.record(z.string(), z.array(levelEntry))]),
+    }),
+    z.object({ method: z.literal('mean_of_components'), components: z.array(component).min(1) }),
+]);
+const parameterSchema = z.object({
+    id: z.string(),
+    key: z.string(),
+    name: z.string(),
+    layer: z.enum(['static', 'execution']),
+    weight: z.number(),
+    pooling: z.enum(['ratio', 'unit_weighted']),
+    raw: z.object({ unit: z.string(), when_empty: z.number() }),
+    scoring,
+    /** Prose per language or topic, for example the 3.5 forbidden-import lists. */
+    measure: z.record(z.string(), z.string()).optional(),
+    not_applicable_when: z.string().nullable().optional(),
+});
+export const dimensionFileSchema = z.object({
+    dimension: z.object({ id: z.number(), key: z.string(), name: z.string() }),
+    /** Dimension 6 prose naming the recognised tools and the removed prefixes. */
+    script_resolution: z.string().optional(),
+    parameters: z.array(parameterSchema).min(1),
+    presets: z.object({ files: z.array(z.string()) }).optional(),
+});
+const stringList = z.array(z.string());
+const presetRule = z.object({
+    name: z.string(),
+    description: z.string(),
+    from: z.object({ in: stringList.optional(), not_in: stringList.optional() }),
+    to: z.object({ in: stringList.optional(), packages: stringList.optional() }),
+    severity: z.enum(['error', 'warn', 'info']),
+    type_only_imports: z.enum(['included', 'excluded']),
+});
+export const presetFileSchema = z.object({
+    preset: z.object({
+        key: z.enum(['nextjs', 'express', 'django', 'fastapi', 'generic']),
+        name: z.string(),
+        languages: stringList,
+    }),
+    conventions: z.string().optional(),
+    /** Glob lists, or prose for content layers (nextjs `server_only` and `client`). */
+    layers: z.record(z.string(), z.union([stringList, z.string()])),
+    modules: z.object({
+        roots: z.union([stringList, z.string()]),
+        public_entry: z.union([z.string(), stringList, z.record(z.string(), z.string())]),
+    }),
+    rules: z.array(presetRule),
+});
+export const methodologyFileSchema = z.object({
+    version: z.string(),
+    dimensions: z.array(z.object({ id: z.number(), key: z.string(), file: z.string() })).min(1),
+    aggregation: z.object({
+        dimension_to_health: z.object({ cap_margin: z.number() }),
+    }),
+    bands: z
+        .array(z.object({ key: z.string(), name: z.string(), min: z.number(), max: z.number(), meaning: z.string().optional() }))
+        .min(1),
+    execution: z.object({
+        runner: z.object({ image: z.string(), cpus: z.number(), memory_gb: z.number() }),
+        timeouts_seconds: z.object({
+            install: z.number(),
+            build: z.number(),
+            typecheck: z.number(),
+            lint: z.number(),
+            tests: z.number(),
+        }),
+    }),
+});
+const globList = z.array(z.string());
+export const scopeFileSchema = z.object({
+    source_files: z.object({
+        extensions: z.object({
+            typescript: globList,
+            javascript: globList,
+            python: globList,
+        }),
+    }),
+    exclusions: z.object({
+        vendored: globList,
+        build_output: globList,
+        generated: globList,
+        minified: globList,
+        migrations: globList,
+        declarations: globList,
+        test_data: globList,
+    }),
+    file_roles: z.object({
+        test: z.object({ typescript_javascript: globList, python: globList }),
+        config: globList,
+    }),
+});

package/dist/python/deadcode.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', 'dead_code_helper.py');
+/** Symbols, `__all__`, imports and class bases of every file, with one helper process. */
+export function analyzePythonDeadCode(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(`dead_code_helper.py failed: ${result.stderr.trim() || `exit ${String(result.status)}`}`);
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ToolError('dead_code_helper.py printed invalid JSON');
+    }
+}

package/dist/python/env.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { runPythonHelper } from './helper.js';
+const cache = new Map();
+/** Environment variable names read by each given Python file: one helper spawn per scan, memoized per repository. */
+export function pythonEnvReads(repoPath, files) {
+    const key = path.resolve(repoPath);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const reads = files.length === 0 ? {} : runPythonHelper('env_helper.py', repoPath, { files });
+    cache.set(key, reads);
+    return reads;
+}

package/dist/python/helper.js

@@ -0,0 +1,24 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolError } from '../scope/types.js';
+const pythonDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'python');
+/** Run one stdlib-only helper from `python/` with JSON in and JSON out. A missing interpreter or a crashed helper is a ToolError. */
+export function runPythonHelper(helper, repoPath, input) {
+    const result = spawnSync('python3', [path.join(pythonDir, helper)], {
+        cwd: repoPath,
+        input: JSON.stringify(input),
+        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(`${helper} failed: ${result.stderr.trim() || `exit ${String(result.status)}`}`);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ToolError(`${helper} printed invalid JSON`);
+    }
+}

package/dist/python/imports.js

@@ -0,0 +1,40 @@
+import { spawn } 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', 'imports_helper.py');
+function runHelper(repoPath, files) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('python3', [helperPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => reject(new ToolError(`Could not run python3: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new ToolError(`imports_helper.py failed: ${stderr.trim() || `exit ${String(code)}`}`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout).files);
+            }
+            catch {
+                reject(new ToolError('imports_helper.py printed invalid JSON'));
+            }
+        });
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(JSON.stringify({ root: path.resolve(repoPath), files }));
+    });
+}
+/** Import statements and builtin `open` calls of every in-scope Python file, one helper process per scan. */
+export function readPythonImports(ctx) {
+    return ctx.tools.memo(`d3-py-imports:${ctx.repoPath}`, () => {
+        const files = ctx.scope.files.filter((f) => f.group === 'python').map((f) => f.path);
+        return files.length === 0 ? Promise.resolve({}) : runHelper(ctx.repoPath, files);
+    });
+}

package/dist/python/nox.js

@@ -0,0 +1,16 @@
+import path from 'node:path';
+import { trackedPaths } from '../scope/tracked.js';
+import { runPythonHelper } from './helper.js';
+const cache = new Map();
+/** The sessions of the tracked `noxfile.py` in `file`'s directory (one helper spawn per scan, memoized per repository). Undefined when it does not parse. */
+export function noxSessions(repoPath, file) {
+    const key = path.resolve(repoPath);
+    let all = cache.get(key);
+    if (!all) {
+        const files = trackedPaths(repoPath).filter((f) => path.posix.basename(f) === 'noxfile.py');
+        all = files.length === 0 ? {} : runPythonHelper('nox_helper.py', repoPath, { files });
+        cache.set(key, all);
+    }
+    const found = all[file];
+    return found?.ok ? found.sessions : undefined;
+}

package/dist/python/scope.js

@@ -0,0 +1,35 @@
+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', 'scope_helper.py');
+export function pythonVersion() {
+    const result = spawnSync('python3', ['--version'], { encoding: 'utf8' });
+    if (result.error || result.status !== 0) {
+        throw new ToolError('python3 is not available on PATH, but the repository has Python files');
+    }
+    return `${result.stdout}${result.stderr}`.trim().replace(/^Python\s+/, '');
+}
+/** Classify all Python files with one helper process. */
+export function analyzePythonFiles(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(`scope_helper.py failed: ${result.stderr.trim() || `exit ${result.status}`}`);
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ToolError('scope_helper.py printed invalid JSON');
+    }
+}

package/dist/python/tests.js

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import { trackedPaths } from '../scope/tracked.js';
+import { runPythonHelper } from './helper.js';
+const cache = new Map();
+const NOT_FIRST_PARTY = /(?:^|\/)(?:node_modules|\.venv|venv|site-packages|__pycache__)\//;
+/**
+ * Import and test-case facts of every tracked Python file, packages that only re-export included (they are not scoped files but
+ * 1.4 follows imports through them). One helper spawn per scan, memoized per repository.
+ */
+export function pythonTestFacts(repoPath) {
+    const key = path.resolve(repoPath);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const files = trackedPaths(repoPath).filter((f) => f.endsWith('.py') && !NOT_FIRST_PARTY.test(f));
+    const facts = files.length === 0 ? {} : runPythonHelper('tests_helper.py', repoPath, { files });
+    cache.set(key, facts);
+    return facts;
+}

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>
+`;
+}