vibecodedshit 0.0.0-stage → 0.3.0

package/dist/exec/docker.js

@@ -0,0 +1,158 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { ToolError } from '../scope/types.js';
+function run(spawn, args, onChild) {
+    return new Promise((resolve) => {
+        const child = spawn('docker', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        onChild?.();
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => resolve({ exitCode: null, stderr, spawnError: err.message }));
+        child.on('close', (code) => resolve({ exitCode: code, stderr }));
+    });
+}
+export const hostUser = () => process.getuid && process.getgid ? { uid: process.getuid(), gid: process.getgid() } : null;
+/**
+ * Download caches of every package manager the network-on steps use, under the /cache mount. Yarn (Berry) gets its
+ * global folder only, so a repository's own cache folder (zero-installs) stays in use. pnpm keeps its store under PNPM_HOME.
+ */
+const CACHE_ENV = {
+    npm_config_cache: '/cache/npm',
+    PNPM_HOME: '/cache/pnpm',
+    YARN_GLOBAL_FOLDER: '/cache/yarn',
+    BUN_INSTALL_CACHE_DIR: '/cache/bun',
+    PIP_CACHE_DIR: '/cache/pip',
+    UV_CACHE_DIR: '/cache/uv',
+    POETRY_CACHE_DIR: '/cache/poetry',
+    PDM_CACHE_DIR: '/cache/pdm',
+    PIPENV_CACHE_DIR: '/cache/pipenv',
+};
+/**
+ * Host directory for the package caches: `HEALTH_PACKAGE_CACHE`, or `off` for none, else `$XDG_CACHE_HOME/health/packages`,
+ * else `~/.cache/health/packages`. The cache only saves downloads: lockfiles and integrity checks decide what is installed.
+ */
+export function packageCacheDir(env = process.env, home = homedir()) {
+    const setting = env.HEALTH_PACKAGE_CACHE?.trim();
+    if (setting === 'off')
+        return null;
+    if (setting)
+        return path.resolve(setting);
+    return path.join(env.XDG_CACHE_HOME || path.join(home, '.cache'), 'health', 'packages');
+}
+/**
+ * `docker run` argv for one step. Network is off unless the step needs it. The container runs as the host user, so
+ * what a step writes into /work and /out stays removable on the host; HOME points at a directory any uid can write.
+ * Network-on steps also mount the host package cache at /cache, so repeated scans do not download the same packages again.
+ */
+export function dockerArgs(spec, name, runner, user = hostUser(), cacheDir = null) {
+    const cache = spec.network && cacheDir !== null;
+    return [
+        'run',
+        '--rm',
+        '--pull',
+        'never',
+        '--name',
+        name,
+        '--cpus',
+        String(runner.cpus),
+        '--memory',
+        `${runner.memory_gb}g`,
+        ...(user ? ['--user', `${user.uid}:${user.gid}`, '-e', 'HOME=/tmp'] : []),
+        ...(spec.network ? [] : ['--network', 'none']),
+        ...(cache ? Object.entries(CACHE_ENV).flatMap(([key, value]) => ['-e', `${key}=${value}`]) : []),
+        ...Object.entries(spec.env).flatMap(([key, value]) => ['-e', `${key}=${value}`]),
+        '-v',
+        `${spec.workDir}:/work`,
+        '-v',
+        `${spec.outDir}:/out`,
+        ...(cache ? ['-v', `${cacheDir}:/cache`] : []),
+        '-w',
+        spec.cwd === '.' ? '/work' : `/work/${spec.cwd}`,
+        runner.image,
+        ...spec.argv,
+    ];
+}
+function toolError(finished, spec) {
+    if (finished.spawnError !== undefined)
+        return new ToolError(`docker could not start: ${finished.spawnError}`);
+    if (finished.exitCode !== null && [125, 126, 127].includes(finished.exitCode)) {
+        const detail = finished.stderr.trim().split('\n').slice(-2).join(' | ');
+        return new ToolError(`${spec.step} could not run in the image (exit ${finished.exitCode})${detail ? `: ${detail}` : ''}`);
+    }
+    return null;
+}
+/**
+ * The real runner: one `docker run` per step. The timeout is enforced here with `docker kill`. The cache directory is
+ * created before a network-on step, so Docker does not create it as root.
+ */
+export function createDockerRunner(runner, spawn = nodeSpawn, cacheDir = packageCacheDir()) {
+    return {
+        async runStep(spec) {
+            if (spec.network && cacheDir !== null)
+                await mkdir(cacheDir, { recursive: true });
+            const name = `health-${randomBytes(4).toString('hex')}-${spec.label.replace(/[^A-Za-z0-9_.-]/g, '-')}`;
+            const started = Date.now();
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                void run(spawn, ['kill', name]);
+            }, spec.timeoutSeconds * 1000);
+            const finished = await run(spawn, dockerArgs(spec, name, runner, hostUser(), cacheDir));
+            clearTimeout(timer);
+            const durationMs = Date.now() - started;
+            if (timedOut)
+                return { status: 'timeout', exitCode: null, durationMs, outputDir: spec.outDir };
+            const failure = toolError(finished, spec);
+            if (failure)
+                throw failure;
+            return {
+                status: finished.exitCode === 0 ? 'ok' : 'failed',
+                exitCode: finished.exitCode,
+                durationMs,
+                outputDir: spec.outDir,
+            };
+        },
+    };
+}
+/**
+ * The image label a full scan checks. Bump it with `LABEL dev.vibecodedshit.health.revision` in docker/Dockerfile
+ * whenever the tools a full run needs from the image change, so an image built before the change is rebuilt.
+ */
+export const IMAGE_REVISION_LABEL = 'dev.vibecodedshit.health.revision';
+export const IMAGE_REVISION = '2';
+/**
+ * `docker image inspect <tag>`: the image id (a locally built image has no RepoDigest). An image whose revision label
+ * is not IMAGE_REVISION lacks tools this version runs in it, so it is a ToolError like a missing image.
+ */
+export function imageDigest(tag, spawn = nodeSpawn) {
+    return new Promise((resolve, reject) => {
+        const format = `{{.Id}} {{index .Config.Labels "${IMAGE_REVISION_LABEL}"}}`;
+        const child = spawn('docker', ['image', 'inspect', tag, '--format', format], { stdio: ['ignore', '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(`docker could not start: ${err.message}`)));
+        child.on('close', (code) => {
+            const [digest = '', revision = ''] = stdout.trim().split(/\s+/);
+            if (code !== 0 || digest === '') {
+                const detail = stderr.trim().split('\n').slice(-1)[0];
+                reject(new ToolError(`image ${tag} is not available${detail ? `: ${detail}` : ''}. Build it with npm run image:build`));
+            }
+            else if (revision !== IMAGE_REVISION) {
+                reject(new ToolError(`image ${tag} is out of date (revision ${revision || 'none'}, this version needs ${IMAGE_REVISION}). Rebuild it with npm run image:build`));
+            }
+            else
+                resolve(digest);
+        });
+    });
+}

package/dist/exec/findings.js

@@ -0,0 +1,73 @@
+import { emptyTallies, unitId } from '../measure/units.js';
+import { NORMAL_EXIT, parseEslint, parseMypy, parsePyright, parseRuff, parseTsc } from './reports.js';
+import { withFailedUnits } from './roots.js';
+function parse(result) {
+    switch (result.tool) {
+        case 'tsc':
+            return parseTsc(result.report ?? '', result.dir);
+        case 'mypy':
+            return parseMypy(result.report ?? '', result.dir);
+        case 'pyright':
+            return parsePyright(result.report ?? '', result.dir);
+        case 'eslint':
+            return parseEslint(result.report ?? '', result.dir);
+        case 'ruff':
+            return parseRuff(result.report ?? '', result.dir);
+    }
+}
+/** Why a check counts as a repository failure, or null when it ran and its report can be read. */
+export function failure(result) {
+    if (result.outcome.status === 'timeout')
+        return `${result.tool} timed out in ${result.dir}`;
+    const code = result.outcome.exitCode;
+    if (code === null || !NORMAL_EXIT[result.tool].includes(code))
+        return `${result.tool} exited with ${String(code)} in ${result.dir}`;
+    if (result.report === null || parse(result) === null)
+        return `${result.tool} wrote no usable report in ${result.dir}`;
+    return null;
+}
+/**
+ * Findings per 1,000 source lines for 2.1 and 2.5. Numerator: findings located in in-scope logic and
+ * test files (anything elsewhere is dropped). Denominator: source lines of those files, per
+ * (package, group) unit. A timeout or a checker with no usable report is a repository failure: the
+ * parameter scores 0. So does an install that failed in every root; when only some roots failed, the units
+ * beneath those roots are failed units and the rest are measured.
+ */
+export function measureFindings(ctx, results) {
+    const exec = ctx.exec;
+    if (!exec)
+        return { status: 'not_measured', reason: 'execution layer did not run' };
+    if (!exec.checksRan)
+        return { status: 'failed', reason: 'install failed, so the step did not run' };
+    const checks = results(exec);
+    for (const check of checks) {
+        const reason = failure(check);
+        if (reason !== null)
+            return { status: 'failed', reason };
+    }
+    const inScope = ctx.scope.files.filter((f) => f.role === 'logic' || f.role === 'test');
+    const tallies = emptyTallies(inScope);
+    const byPath = new Map(inScope.map((f) => [f.path, f]));
+    for (const file of inScope) {
+        const tally = tallies.get(unitId(file));
+        if (tally)
+            tally.denominator += file.sourceLines;
+    }
+    for (const check of checks) {
+        for (const reported of parse(check)?.files ?? []) {
+            const file = byPath.get(reported);
+            const tally = file && tallies.get(unitId(file));
+            if (tally)
+                tally.numerator += 1;
+        }
+    }
+    const units = [...tallies.values()]
+        .sort((a, b) => a.package.localeCompare(b.package) || a.group.localeCompare(b.group))
+        .map((t) => ({
+        package: t.package,
+        group: t.group,
+        weight: t.weight,
+        raw: { kind: 'ratio', numerator: t.numerator, denominator: t.denominator, scale: 1000 },
+    }));
+    return { status: 'measured', units: withFailedUnits(exec, ctx.scope, units) };
+}

package/dist/exec/plan.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+const MANIFEST = {
+    typescript_javascript: (base) => base === 'package.json',
+    python: (base) => base === 'pyproject.toml' || base === 'Pipfile' || base === 'setup.py' || /^requirements.*\.txt$/.test(base),
+};
+export function isUnder(dir, parent) {
+    return parent === '.' || dir === parent || dir.startsWith(`${parent}/`);
+}
+/**
+ * Install roots per language group: the manifest directories that have no manifest directory of the
+ * same group above them, so a workspace installs once at its root and a nested example does not
+ * need an install of its own. Logic files outside every root go to a root at "." with nothing to install.
+ * A root with no logic file of its group beneath it is dropped.
+ */
+export function planExecution(scope, tracked) {
+    const roots = [];
+    const typecheck = [];
+    for (const group of ['typescript_javascript', 'python']) {
+        const files = scope.files.filter((f) => f.group === group && (f.role === 'logic' || f.role === 'test'));
+        if (!files.some((f) => f.role === 'logic'))
+            continue;
+        const manifestDirs = [...new Set(tracked.filter((file) => MANIFEST[group](path.posix.basename(file))).map((file) => path.posix.dirname(file)))];
+        const candidates = manifestDirs.filter((dir) => !manifestDirs.some((other) => other !== dir && isUnder(dir, other))).sort();
+        const rootOf = (file) => candidates.find((dir) => isUnder(path.posix.dirname(file.path), dir)) ?? '.';
+        const byRoot = new Map();
+        for (const file of files)
+            byRoot.set(rootOf(file), [...(byRoot.get(rootOf(file)) ?? []), file]);
+        for (const [dir, groupFiles] of [...byRoot].sort(([a], [b]) => a.localeCompare(b))) {
+            const logic = groupFiles.filter((f) => f.role === 'logic');
+            if (logic.length === 0)
+                continue;
+            roots.push({
+                dir,
+                group,
+                weight: logic.reduce((sum, f) => sum + f.logicLines, 0),
+                logicFiles: logic.map((f) => f.path),
+                sourceFiles: groupFiles.map((f) => f.path),
+            });
+        }
+        const byPackage = new Map();
+        for (const file of files)
+            byPackage.set(file.package, [...(byPackage.get(file.package) ?? []), file]);
+        for (const [dir, unitFiles] of [...byPackage].sort(([a], [b]) => a.localeCompare(b))) {
+            if (!unitFiles.some((f) => f.role === 'logic'))
+                continue;
+            typecheck.push({ dir, group, root: rootOf(unitFiles[0]), sourceFiles: unitFiles.map((f) => f.path) });
+        }
+    }
+    return { roots, typecheck };
+}

package/dist/exec/reports.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+/** Tool output paths are `/work/...` or relative to the step's directory; map both to repo-relative. */
+export function toRepoPath(reported, stepDir) {
+    const posix = reported.split(path.sep).join('/').replace(/^\.\//, '');
+    const rel = posix.startsWith('/work/') ? posix.slice('/work/'.length) : posix.startsWith('/') ? null : path.posix.join(stepDir, posix);
+    return rel === null ? posix : path.posix.normalize(rel);
+}
+/** tsc `--pretty false`: `path(line,col): error TSnnnn: ...`. An error with no location is a config error, not a finding. */
+export function parseTsc(text, stepDir) {
+    const files = [];
+    for (const line of text.replace(/\r\n?/g, '\n').split('\n')) {
+        const located = /^(.+?)\(\d+,\d+\): error TS\d+:/.exec(line);
+        if (located?.[1])
+            files.push(toRepoPath(located[1], stepDir));
+        else if (/^error TS\d+:/.test(line))
+            return null;
+    }
+    return { files };
+}
+/** mypy text output: `path:line: error: ...` or `path:line:col: error: ...`. */
+export function parseMypy(text, stepDir) {
+    const files = [];
+    for (const line of text.replace(/\r\n?/g, '\n').split('\n')) {
+        const match = /^(.+?):\d+:(?:\d+:)? error:/.exec(line);
+        if (match?.[1])
+            files.push(toRepoPath(match[1], stepDir));
+    }
+    return { files };
+}
+function json(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `pyright --outputjson`: `generalDiagnostics` entries of severity error. Duplicates (same place and rule) count once. */
+export function parsePyright(text, stepDir) {
+    const doc = json(text);
+    if (!doc || !Array.isArray(doc.generalDiagnostics))
+        return null;
+    const seen = new Set();
+    const files = [];
+    for (const entry of doc.generalDiagnostics) {
+        if (entry.severity !== 'error' || typeof entry.file !== 'string')
+            continue;
+        const key = `${entry.file}:${entry.range?.start?.line ?? 0}:${entry.range?.start?.character ?? 0}:${entry.rule ?? entry.message ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        files.push(toRepoPath(entry.file, stepDir));
+    }
+    return { files };
+}
+/** `eslint -f json`: every message is a finding, including a parse error (no rule id), which counts as one. */
+export function parseEslint(text, stepDir) {
+    const doc = json(text);
+    if (!Array.isArray(doc))
+        return null;
+    const files = [];
+    for (const entry of doc) {
+        if (typeof entry.filePath !== 'string')
+            return null;
+        for (let i = 0; i < (entry.messages?.length ?? 0); i += 1)
+            files.push(toRepoPath(entry.filePath, stepDir));
+    }
+    return { files };
+}
+/** `ruff check --output-format json`: one entry per finding, a syntax error included. */
+export function parseRuff(text, stepDir) {
+    const doc = json(text);
+    if (!Array.isArray(doc))
+        return null;
+    const files = [];
+    for (const entry of doc) {
+        if (typeof entry.filename !== 'string')
+            return null;
+        files.push(toRepoPath(entry.filename, stepDir));
+    }
+    return { files };
+}
+/** Exit codes that mean "ran and reported findings", per tool. Anything else is a config or tool failure of the repository. */
+export const NORMAL_EXIT = {
+    tsc: [0, 1, 2],
+    pyright: [0, 1],
+    mypy: [0, 1],
+    eslint: [0, 1],
+    ruff: [0, 1],
+};

package/dist/exec/roots.js

@@ -0,0 +1,49 @@
+import { logicUnits } from '../measure/units.js';
+import { isUnder } from './plan.js';
+export function installFailed(root) {
+    return root.install !== null && root.install.status !== 'ok';
+}
+/** False only when every install root failed to install. With no root at all the checks ran. */
+export function anyRootHealthy(roots) {
+    return roots.length === 0 || roots.some((root) => !installFailed(root));
+}
+/** The install root of `group` whose install failed and that holds `dir` (a directory or a file path), or undefined. Install roots of one group never nest, so it is unique. */
+export function failedRootOf(exec, dir, group) {
+    return exec.roots.find((root) => installFailed(root) && root.group === group && isUnder(dir, root.dir));
+}
+/**
+ * The failed install roots a unit depends on: those holding its package directory or any of its logic files.
+ * A package is a workspace member or a directory with its own pyproject.toml, so without workspaces one TS/JS unit
+ * can span several install roots; it then counts as failed as soon as one of them failed.
+ */
+function failedRootsOf(exec, unit) {
+    return exec.roots.filter((root) => installFailed(root) && root.group === unit.group && (isUnder(unit.dir, root.dir) || unit.files.some((f) => isUnder(f.path, root.dir))));
+}
+/** One failed unit per (package, group) that depends on a failed install root. */
+export function failedUnits(exec, scope) {
+    return logicUnits(scope)
+        .filter((unit) => failedRootsOf(exec, unit).length > 0)
+        .map((unit) => ({ package: unit.package, group: unit.group, weight: unit.weight, raw: { kind: 'failed' } }));
+}
+const unitKey = (unit) => `${unit.package}\0${unit.group}`;
+/** `units` with the units beneath a failed install root replaced by failed ones. Order is kept when no root failed. */
+export function withFailedUnits(exec, scope, units) {
+    const failed = failedUnits(exec, scope);
+    if (failed.length === 0)
+        return units;
+    const keys = new Set(failed.map(unitKey));
+    return [...units.filter((unit) => !keys.has(unitKey(unit))), ...failed].sort((a, b) => a.package.localeCompare(b.package) || a.group.localeCompare(b.group));
+}
+/** The failed install roots that the failed units of a measurement lie under, for the report. */
+export function failedRootDirs(exec, scope, units) {
+    const logic = new Map(logicUnits(scope).map((unit) => [unitKey(unit), unit]));
+    const dirs = units.flatMap((unit) => {
+        const found = logic.get(unitKey(unit));
+        return unit.raw.kind === 'failed' && found ? failedRootsOf(exec, found).map((root) => root.dir) : [];
+    });
+    return [...new Set(dirs)].sort();
+}
+/** The install outcome of every install root, as run.json records it. */
+export function executionRoots(exec) {
+    return exec.roots.map((root) => ({ dir: root.dir, group: root.group, install: root.install?.status ?? null, exitCode: root.install?.exitCode ?? null }));
+}

package/dist/exec/run.js

@@ -0,0 +1,182 @@
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { parseEnvExample } from '../measure/ops/env-example.js';
+import { dirsUpward } from '../measure/ops/entry-points.js';
+import { readTracked, trackedPaths } from '../scope/tracked.js';
+import { knipRoots } from '../tools/knip.js';
+import { createWorkCopy } from '../tools/workcopy.js';
+import { ToolError } from '../scope/types.js';
+import { isUnder, planExecution } from './plan.js';
+import { anyRootHealthy, installFailed } from './roots.js';
+import { build } from './steps/build.js';
+import { install } from './steps/install.js';
+import { knip } from './steps/knip.js';
+import { lint } from './steps/lint.js';
+import { coverageInstall } from './steps/coverage-install.js';
+import { test } from './steps/test.js';
+import { typecheck } from './steps/typecheck.js';
+import { detectInvocations } from './test-runners/detect.js';
+import { RUNNERS } from './test-runners/index.js';
+/**
+ * `timeouts_seconds` names the test step `tests` and has no entry for the coverage provider install,
+ * which is bounded like install, or for knip, which is bounded like lint.
+ */
+const TIMEOUT_KEY = {
+    install: 'install',
+    'coverage-install': 'install',
+    build: 'build',
+    typecheck: 'typecheck',
+    lint: 'lint',
+    knip: 'lint',
+    test: 'tests',
+};
+function envFor(repoPath, dir, methodology) {
+    for (const up of dirsUpward(dir)) {
+        for (const name of methodology.d6.envExampleFiles) {
+            const text = readTracked(repoPath, path.posix.join(up, name));
+            if (text !== null)
+                return parseEnvExample(text);
+        }
+    }
+    return {};
+}
+/**
+ * Reads the reports of one test run. A timeout or a missing or unreadable results report leaves `results`
+ * unset (a repository failure). A results report with at least one case but no usable coverage report is
+ * a ToolError: coverage is the tool's job, so the run is invalid.
+ */
+async function readTest(invocation, outcome) {
+    const spec = RUNNERS[invocation.runner];
+    const base = { dir: invocation.dir, group: invocation.group, runner: invocation.runner, args: invocation.args, outcome };
+    if (outcome.status === 'timeout')
+        return base;
+    const read = (name) => readFile(path.join(outcome.outputDir, name), 'utf8').catch(() => null);
+    const text = await read(spec.results);
+    const results = text === null ? null : spec.parseResults(text);
+    if (results === null)
+        return base;
+    if (results.passed + results.failed + results.errored + results.skipped === 0)
+        return { ...base, results };
+    const coverageText = await read(spec.coverage);
+    const coverage = coverageText === null ? null : spec.parseCoverage(coverageText, invocation.dir);
+    if (coverage === null)
+        throw new ToolError(`${invocation.runner} produced results but no usable coverage data in ${invocation.dir}`);
+    if (spec.ranges === undefined || spec.parseRanges === undefined)
+        return { ...base, results, coverage };
+    const rangesText = await read(spec.ranges);
+    const ranges = rangesText === null ? null : spec.parseRanges(rangesText, invocation.dir);
+    if (ranges === null)
+        throw new ToolError(`${invocation.runner} produced no usable coverage-final.json in ${invocation.dir}`);
+    return { ...base, results, coverage, ranges };
+}
+/**
+ * Install, then build per install root, then typecheck per workspace package, lint per install root and knip
+ * per knip root, for the roots whose install worked (a failed root is skipped, its units score 0). One `docker run` each, run one after another on a temp copy
+ * of the tracked files; reports go to a separate temp directory, deleted afterwards. The work copy
+ * outlives the call so static tools can read the installed dependencies (`results.workDir`); the
+ * caller removes it with `cleanup`. On a throw both are deleted here.
+ * Throws `ToolError` from the runner; a repository failure is only recorded in the results.
+ */
+export async function runExecution(opts) {
+    const { repoPath, methodology, scope, runner, image } = opts;
+    const timeouts = methodology.execution.timeouts_seconds;
+    const tracked = trackedPaths(repoPath);
+    const trackedSet = new Set(tracked);
+    const plan = planExecution(scope, tracked);
+    const work = await createWorkCopy(repoPath, tracked);
+    const out = await mkdtemp(path.join(tmpdir(), 'health-out-'));
+    let counter = 0;
+    try {
+        const run = async (step, ctx, dirForEnv) => {
+            const command = step.command(ctx);
+            if (command === null)
+                return null;
+            counter += 1;
+            const label = `${step.name}-${counter}`;
+            const outDir = path.join(out, label);
+            await mkdir(outDir, { recursive: true });
+            const outcome = await runner.runStep({
+                label,
+                step: step.name,
+                network: step.network,
+                argv: command.argv,
+                cwd: ctx.dir,
+                timeoutSeconds: timeouts[TIMEOUT_KEY[step.name]],
+                env: envFor(repoPath, dirForEnv, methodology),
+                workDir: work.dir,
+                outDir,
+            });
+            return { outcome, command };
+        };
+        const context = (dir, group, files) => ({
+            dir,
+            group,
+            tracked: trackedSet,
+            read: (rel) => readTracked(repoPath, rel),
+            files,
+        });
+        const roots = [];
+        for (const root of plan.roots) {
+            const ctx = context(root.dir, root.group, root.logicFiles);
+            const installed = await run(install, ctx, root.dir);
+            const installOk = installed === null || installed.outcome.status === 'ok';
+            const built = installOk ? await run(build, ctx, root.dir) : null;
+            roots.push({ dir: root.dir, group: root.group, weight: root.weight, install: installed?.outcome ?? null, build: built?.outcome ?? null });
+        }
+        const checksRan = anyRootHealthy(roots);
+        const healthy = (dir, group) => !roots.some((r) => installFailed(r) && r.group === group && isUnder(dir, r.dir));
+        const healthyRoots = plan.roots.filter((root) => healthy(root.dir, root.group));
+        const typecheckResults = [];
+        const lintResults = [];
+        const knipResults = [];
+        const testResults = [];
+        if (checksRan) {
+            const collect = async (step, ctx, into, envDir) => {
+                const result = await run(step, ctx, envDir);
+                if (result === null || !result.command.tool || !result.command.report)
+                    return;
+                const report = await readFile(path.join(result.outcome.outputDir, result.command.report), 'utf8').catch(() => null);
+                into.push({ tool: result.command.tool, dir: ctx.dir, group: ctx.group, outcome: result.outcome, report });
+            };
+            for (const pkg of plan.typecheck.filter((p) => healthy(p.root, p.group)))
+                await collect(typecheck, context(pkg.dir, pkg.group, pkg.sourceFiles), typecheckResults, pkg.root);
+            for (const root of healthyRoots)
+                await collect(lint, context(root.dir, root.group, root.sourceFiles), lintResults, root.dir);
+            for (const dir of knipRoots(repoPath).filter((dir) => healthy(dir, 'typescript_javascript'))) {
+                const result = await run(knip, context(dir, 'typescript_javascript', []), dir);
+                if (result === null || !result.command.report)
+                    continue;
+                const report = await readFile(path.join(result.outcome.outputDir, result.command.report), 'utf8').catch(() => null);
+                knipResults.push({ dir, outcome: result.outcome, report });
+            }
+            const invocations = detectInvocations({ roots: healthyRoots, scope, tracked: trackedSet, read: (rel) => readTracked(repoPath, rel) });
+            for (const invocation of invocations) {
+                const files = healthyRoots
+                    .filter((r) => r.group === invocation.group)
+                    .flatMap((r) => r.logicFiles)
+                    .filter((file) => invocation.dir === '.' || file.startsWith(`${invocation.dir}/`));
+                const ctx = { ...context(invocation.dir, invocation.group, files), invocation };
+                const provider = await run(coverageInstall, ctx, invocation.dir);
+                if (provider && provider.outcome.status !== 'ok') {
+                    throw new ToolError(`the coverage provider could not be installed for ${invocation.runner} in ${invocation.dir} (${provider.outcome.status})`);
+                }
+                const ran = await run(test, ctx, invocation.dir);
+                if (ran === null)
+                    continue;
+                testResults.push(await readTest(invocation, ran.outcome));
+            }
+        }
+        return {
+            results: { image, roots, checksRan, typecheck: typecheckResults, lint: lintResults, knip: knipResults, test: { invocations: testResults }, workDir: work.dir },
+            cleanup: () => work.cleanup(),
+        };
+    }
+    catch (err) {
+        await work.cleanup();
+        throw err;
+    }
+    finally {
+        await rm(out, { recursive: true, force: true });
+    }
+}

package/dist/exec/steps/build.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { inDir, jsManager } from './lockfiles.js';
+function hasBuildScript(text) {
+    if (text === null)
+        return false;
+    try {
+        const scripts = JSON.parse(text).scripts;
+        return typeof scripts?.build === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+/** First-party top-level packages: directories with an `__init__.py` that hold a logic file. */
+function topLevelPackages(ctx) {
+    const names = new Set();
+    for (const file of ctx.files) {
+        const rel = path.posix.relative(ctx.dir, file);
+        const top = rel.split('/')[0];
+        if (!top || top === rel || !/^[A-Za-z_]\w*$/.test(top))
+            continue;
+        if (ctx.tracked.has(path.posix.join(ctx.dir, top, '__init__.py')))
+            names.add(top);
+    }
+    return [...names].sort();
+}
+/** The build script, or for Python `manage.py check` (Django) or importing each top-level package. Network off. */
+export const build = {
+    name: 'build',
+    network: false,
+    command(ctx) {
+        if (ctx.group === 'typescript_javascript') {
+            if (!hasBuildScript(ctx.read(inDir(ctx, 'package.json'))))
+                return null;
+            return { argv: [jsManager(ctx).manager, 'run', 'build'] };
+        }
+        if (/django/i.test(ctx.read(inDir(ctx, 'manage.py')) ?? '')) {
+            return { argv: ['health-venv', 'python', 'manage.py', 'check'] };
+        }
+        const packages = topLevelPackages(ctx);
+        if (packages.length === 0)
+            return null;
+        return { argv: ['health-venv', 'python', '-c', `import ${packages.join(', ')}`] };
+    },
+};

package/dist/exec/steps/coverage-install.js

@@ -0,0 +1,12 @@
+/**
+ * `@vitest/coverage-v8` has to match the installed vitest, so it cannot be baked into the image. This
+ * installs it into the temporary copy only (never into package.json or a lockfile). The only network-on
+ * step after install. A failure is a tool error: the provider is the tool's dependency, not the repository's.
+ */
+export const coverageInstall = {
+    name: 'coverage-install',
+    network: true,
+    command(ctx) {
+        return ctx.invocation?.runner === 'vitest' ? { argv: ['health-coverage-install'] } : null;
+    },
+};