howtofixcli 0.7.7 → 0.7.9

package/dist/quality/report.js

@@ -1,803 +0,0 @@
-/**
- * The quality report — spec §2's ninth module: thresholds and config, the
- * per-file analysis pipeline, baseline comparison, and the three renderers
- * (human, JSON, SARIF).
- *
- * Two contracts carry the spec's §4 fix over `code-multivitals`:
- *
- * 1. **Attribution is by path, never by position.** `analyzeFiles` walks the
- *    `Map<path, ParsedFile>` that `parseFiles` guarantees is total and writes
- *    exactly one `FileReport` per requested path. A file that failed to parse
- *    becomes an explicit `{ ok: false }` entry with a `parse error` finding —
- *    one broken file can never shift another file's report, because nothing
- *    is paired by array index anywhere.
- * 2. **Severities are ranks.** Every metric maps to `0` (ok), `1` (warn) or
- *    `2` (error) through the threshold table (§3); compound smells consume
- *    those ranks (see `smells.ts`), and `--strict` compares ranks against the
- *    baseline, so a config change that moves a threshold cannot manufacture a
- *    regression — both sides of a comparison are re-ranked with the same
- *    config.
- *
- * The score that `ci.failBelow` gates is the LOC-weighted mean function MI on
- * the 0–100 SEI scale (§3.6): a repository is as maintainable as its code
- * mass, not as its worst five-line function. An empty report scores 100.
- */
-import { spawnSync } from "node:child_process";
-import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { extname, join, relative, resolve } from "node:path";
-import { SyntaxKind } from "typescript/unstable/ast";
-import { childNode, childNodes, hasModifier, nodeSpan, nodeText, parseFiles, walk } from "./ast.js";
-import { cognitive } from "./cognitive.js";
-import { cyclomatic } from "./cyclomatic.js";
-import { functionLength } from "./length.js";
-import { halsteadVolume } from "./halstead.js";
-import { maintainabilityIndex } from "./maintainability.js";
-import { nesting } from "./nesting.js";
-import { SMELL_SUGGESTIONS, detectSmells } from "./smells.js";
-export const RANK_LABELS = ["ok", "warn", "error"];
-/** The per-function metric keys, in the order the human report prints them. */
-export const FUNCTION_METRIC_ORDER = ["cyclomatic", "cognitive", "nesting", "length", "halstead", "mi", "parameters", "booleanParameters"];
-/** The six metrics a baseline tracks (module limits are config-shaped, not code-shaped). */
-export const BASELINE_METRIC_ORDER = ["cyclomatic", "cognitive", "nesting", "length", "halstead", "mi"];
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-/**
- * Defaults straight from spec §3. Halstead's warn line (500) is the spec's §6
- * example; the error line (1000) is this repo's own — the spec gives no error
- * tier for Halstead, so it is documented here rather than implied.
- */
-export const DEFAULT_THRESHOLDS = {
-    cyclomatic: { warn: 15, error: 25 },
-    cognitive: { warn: 12, error: 20 },
-    nesting: { warn: 4, error: 5 },
-    length: { warn: 60, error: 120 },
-    halstead: { warn: 500, error: 1000 },
-    mi: { warn: 65, error: 20 },
-    fileLines: { warn: 400, error: 800 },
-    exports: { warn: 20, error: 30 },
-    parameters: { warn: 5, error: 8 },
-};
-export function defaultConfig() {
-    const thresholds = {
-        cyclomatic: { ...DEFAULT_THRESHOLDS.cyclomatic },
-        cognitive: { ...DEFAULT_THRESHOLDS.cognitive },
-        nesting: { ...DEFAULT_THRESHOLDS.nesting },
-        length: { ...DEFAULT_THRESHOLDS.length },
-        halstead: { ...DEFAULT_THRESHOLDS.halstead },
-        mi: { ...DEFAULT_THRESHOLDS.mi },
-        fileLines: { ...DEFAULT_THRESHOLDS.fileLines },
-        exports: { ...DEFAULT_THRESHOLDS.exports },
-        parameters: { ...DEFAULT_THRESHOLDS.parameters },
-    };
-    return { ignore: [], thresholds, ci: { failBelow: 65, mode: "advisory" } };
-}
-const THRESHOLD_KEYS = ["cyclomatic", "cognitive", "nesting", "length", "halstead", "mi", "fileLines", "exports", "parameters"];
-function isFiniteNumber(value) {
-    return typeof value === "number" && Number.isFinite(value);
-}
-/**
- * `.howtofix/quality.json` over the defaults. A missing or broken file is "no
- * decision", not an error: a typo'd JSON must not take the gate down, and a
- * threshold that is not a finite number keeps its default instead of ranking
- * every metric `NaN > NaN === false` (all ok).
- */
-export function loadQualityConfig(cwd) {
-    const config = defaultConfig();
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(join(cwd, ".howtofix", "quality.json"), "utf8"));
-    }
-    catch {
-        return config;
-    }
-    if (typeof parsed !== "object" || parsed === null)
-        return config;
-    const raw = parsed;
-    if (typeof raw.enabled === "boolean")
-        config.enabled = raw.enabled;
-    if (Array.isArray(raw.ignore)) {
-        config.ignore = raw.ignore.filter((pattern) => typeof pattern === "string");
-    }
-    if (typeof raw.thresholds === "object" && raw.thresholds !== null) {
-        const given = raw.thresholds;
-        for (const key of THRESHOLD_KEYS) {
-            const pair = given[key];
-            if (typeof pair !== "object" || pair === null)
-                continue;
-            const bounds = pair;
-            if (isFiniteNumber(bounds.warn))
-                config.thresholds[key].warn = bounds.warn;
-            if (isFiniteNumber(bounds.error))
-                config.thresholds[key].error = bounds.error;
-        }
-    }
-    if (typeof raw.ci === "object" && raw.ci !== null) {
-        const given = raw.ci;
-        if (isFiniteNumber(given.failBelow))
-            config.ci.failBelow = given.failBelow;
-        if (given.mode === "advisory" || given.mode === "blocking")
-            config.ci.mode = given.mode;
-    }
-    return config;
-}
-/**
- * The three-layer switch, strongest layer first:
- *
- * 1. `HOWTOFIX_QUALITY` — `0`/`false` off, any other value on. Wins both ways.
- * 2. `enabled` in `.howtofix/quality.json`.
- * 3. `runtime` — the state a future `/quality off` passes in; consulted only
- *    when neither layer above decided.
- * 4. Default: on.
- *
- * This switch governs the *invocations* (the CLI's advisory path, the tool,
- * a slash command). The `--strict` CI path ignores it on purpose: an AST
- * analysis with no side effects that anyone can switch off from inside an
- * agent session is not a gate (spec §2).
- */
-export function qualityEnabled(cwd, runtime) {
-    const env = process.env.HOWTOFIX_QUALITY;
-    if (env !== undefined) {
-        const value = env.trim().toLowerCase();
-        if (value === "0" || value === "false")
-            return { enabled: false, source: "env" };
-        return { enabled: true, source: "env" };
-    }
-    const configured = loadQualityConfig(cwd).enabled;
-    if (configured !== undefined)
-        return { enabled: configured, source: "config" };
-    if (runtime !== undefined)
-        return { enabled: runtime, source: "runtime" };
-    return { enabled: true, source: "default" };
-}
-// ---------------------------------------------------------------------------
-// Ranking
-// ---------------------------------------------------------------------------
-function rankAbove(value, pair) {
-    if (value > pair.error)
-        return 2;
-    if (value > pair.warn)
-        return 1;
-    return 0;
-}
-function rankBelow(value, pair) {
-    if (value < pair.error)
-        return 2;
-    if (value < pair.warn)
-        return 1;
-    return 0;
-}
-/** Re-rank a stored value with the *current* thresholds (baseline comparisons). */
-function rankOfBaselineMetric(metric, value, thresholds) {
-    switch (metric) {
-        case "cyclomatic":
-            return rankAbove(value, thresholds.cyclomatic);
-        case "cognitive":
-            return rankAbove(value, thresholds.cognitive);
-        case "nesting":
-            return rankAbove(value, thresholds.nesting);
-        case "length":
-            return rankAbove(value, thresholds.length);
-        case "halstead":
-            return rankAbove(value, thresholds.halstead);
-        case "mi":
-            return rankBelow(value, thresholds.mi);
-    }
-}
-// ---------------------------------------------------------------------------
-// Analysis
-// ---------------------------------------------------------------------------
-function boolParamNames(unit) {
-    const names = [];
-    for (const parameter of childNodes(unit.node, "parameters")) {
-        const type = childNode(parameter, "type");
-        if (type?.kind !== SyntaxKind.BooleanKeyword)
-            continue;
-        // A destructured parameter has no identifier; its shape is still worth naming.
-        names.push(nodeText(childNode(parameter, "name")) ?? "<pattern>");
-    }
-    return names;
-}
-function analyzeFunction(unit, sourceFile, path, config) {
-    const t = config.thresholds;
-    // The metric walkers take the function's BODY: their nested-function guard
-    // also fires on the root, so passing the function node itself would score 0.
-    // An ambient declaration has no body; there is nothing inside to measure.
-    const body = childNode(unit.node, "body") ?? unit.node;
-    const values = {
-        cyclomatic: cyclomatic(body),
-        cognitive: cognitive(body),
-        nesting: nesting(body),
-        length: functionLength(unit),
-        halstead: halsteadVolume(body),
-        mi: 0,
-    };
-    values.mi = maintainabilityIndex(values.halstead, values.cyclomatic, values.length);
-    const booleanNames = boolParamNames(unit);
-    const parameterCount = childNodes(unit.node, "parameters").length;
-    const metrics = {
-        cyclomatic: { value: values.cyclomatic, rank: rankAbove(values.cyclomatic, t.cyclomatic) },
-        cognitive: { value: values.cognitive, rank: rankAbove(values.cognitive, t.cognitive) },
-        nesting: { value: values.nesting, rank: rankAbove(values.nesting, t.nesting) },
-        length: { value: values.length, rank: rankAbove(values.length, t.length) },
-        halstead: { value: values.halstead, rank: rankAbove(values.halstead, t.halstead) },
-        mi: { value: values.mi, rank: rankBelow(values.mi, t.mi) },
-        parameters: { value: parameterCount, rank: rankAbove(parameterCount, t.parameters) },
-        booleanParameters: { value: booleanNames.length, rank: (booleanNames.length > 0 ? 1 : 0) },
-    };
-    const ranks = {
-        cyclomatic: metrics.cyclomatic.rank,
-        cognitive: metrics.cognitive.rank,
-        nesting: metrics.nesting.rank,
-        length: metrics.length.rank,
-        halstead: metrics.halstead.rank,
-        mi: metrics.mi.rank,
-    };
-    const span = nodeSpan(sourceFile, unit.node);
-    let worstRank = 0;
-    for (const key of FUNCTION_METRIC_ORDER)
-        if (metrics[key].rank > worstRank)
-            worstRank = metrics[key].rank;
-    return {
-        path,
-        name: unit.name,
-        startLine: span.startLine,
-        endLine: span.endLine,
-        startColumn: span.startColumn,
-        endColumn: span.endColumn,
-        metrics,
-        booleanParameterNames: booleanNames,
-        smells: detectSmells(values, ranks),
-        worstRank,
-    };
-}
-/**
- * Count a file's exports: every statement carrying `export`, plus the specifiers
- * of `export { a, b }` (a re-export of nothing exports nothing, `export *`
- * counts as the one statement it is).
- */
-function countExports(sourceFile) {
-    let total = 0;
-    walk(sourceFile, (node) => {
-        if (node.kind === SyntaxKind.ExportDeclaration) {
-            const clause = childNode(node, "exportClause");
-            const elements = clause ? childNodes(clause, "elements") : [];
-            total += elements.length > 0 ? elements.length : 1;
-            return;
-        }
-        if (node.kind === SyntaxKind.ExportAssignment) {
-            total += 1;
-            return;
-        }
-        if (hasModifier(node, SyntaxKind.ExportKeyword))
-            total += 1;
-    });
-    return total;
-}
-/** Physical lines: a trailing newline ends the last line, it does not open one. */
-function fileLineCount(text) {
-    if (text.length === 0)
-        return 0;
-    let lines = 1;
-    for (let index = 0; index < text.length; index += 1) {
-        if (text.charCodeAt(index) === 10)
-            lines += 1;
-    }
-    if (text.charCodeAt(text.length - 1) === 10)
-        lines -= 1;
-    return lines;
-}
-const ZERO = { value: 0, rank: 0 };
-function errorFileReport(path, error) {
-    return {
-        path,
-        ok: false,
-        error,
-        lines: 0,
-        metrics: { lines: ZERO, exports: ZERO, mi: { value: 100, rank: 0 } },
-        functions: [],
-    };
-}
-function pushMetricFindings(into, file, fn, span, metric, value, warnLine) {
-    if (value.rank === 0)
-        return;
-    into.push({
-        path: file.path,
-        metric,
-        detail: metric === "booleanParameters" ? (fn?.booleanParameterNames.join(", ") ?? String(value.value)) : `${value.value} (limit ${warnLine})`,
-        rank: value.rank,
-        line: span.line,
-        endLine: span.endLine,
-        startColumn: span.startColumn,
-        endColumn: span.endColumn,
-        ...(fn ? { function: fn.name } : {}),
-    });
-}
-/**
- * Analyze a batch of files into the Map-based report (spec §4).
- *
- * `paths` may contain anything; every key of the input appears exactly once in
- * `report.files`, parsed or not. Findings follow the same order as the input,
- * so the three renderers see one deterministic stream.
- */
-export async function analyzeFiles(paths, config = defaultConfig()) {
-    const parsed = await parseFiles(paths);
-    const files = new Map();
-    const findings = [];
-    const t = config.thresholds;
-    for (const path of paths) {
-        const outcome = parsed.get(path);
-        if (!outcome) {
-            // `parseFiles` guarantees totality; if it ever regresses, fail visibly on
-            // this file rather than shifting the ones after it.
-            const report = errorFileReport(path, "internal: file missing from the parse result");
-            files.set(path, report);
-            findings.push({ path, metric: "parse error", detail: report.error ?? "", rank: 2, line: 1, endLine: 1, startColumn: 1, endColumn: 1 });
-            continue;
-        }
-        if (!outcome.ok) {
-            const report = errorFileReport(path, outcome.error);
-            files.set(path, report);
-            findings.push({ path, metric: "parse error", detail: outcome.error, rank: 2, line: 1, endLine: 1, startColumn: 1, endColumn: 1 });
-            continue;
-        }
-        const { sourceFile } = outcome;
-        const functions = outcome.functions.map((unit) => analyzeFunction(unit, sourceFile, path, config));
-        const lines = fileLineCount(sourceFile.text);
-        const exportCount = countExports(sourceFile);
-        const weight = functions.reduce((total, fn) => total + fn.metrics.length.value, 0);
-        const weightedMi = weight === 0 ? 100 : Math.round((functions.reduce((total, fn) => total + fn.metrics.mi.value * fn.metrics.length.value, 0) / weight) * 10) / 10;
-        const report = {
-            path,
-            ok: true,
-            lines,
-            metrics: {
-                lines: { value: lines, rank: rankAbove(lines, t.fileLines) },
-                exports: { value: exportCount, rank: rankAbove(exportCount, t.exports) },
-                mi: { value: weightedMi, rank: rankBelow(weightedMi, t.mi) },
-            },
-            functions,
-        };
-        files.set(path, report);
-        const fileSpan = { line: 1, endLine: Math.max(lines, 1), startColumn: 1, endColumn: 1 };
-        pushMetricFindings(findings, report, undefined, fileSpan, "file lines", report.metrics.lines, t.fileLines.warn);
-        pushMetricFindings(findings, report, undefined, fileSpan, "exports", report.metrics.exports, t.exports.warn);
-        for (const fn of functions) {
-            const fnSpan = { line: fn.startLine, endLine: fn.endLine, startColumn: fn.startColumn, endColumn: fn.endColumn };
-            for (const key of FUNCTION_METRIC_ORDER) {
-                pushMetricFindings(findings, report, fn, fnSpan, key, fn.metrics[key], warnLineOf(key, t));
-            }
-            for (const smell of fn.smells) {
-                findings.push({
-                    path,
-                    metric: "smell",
-                    detail: `${smell.label}: ${smell.reason}`,
-                    rank: 1,
-                    line: fn.startLine,
-                    endLine: fn.endLine,
-                    startColumn: fn.startColumn,
-                    endColumn: fn.endColumn,
-                    function: fn.name,
-                });
-            }
-        }
-    }
-    return { files, findings };
-}
-// ---------------------------------------------------------------------------
-// Aggregation
-// ---------------------------------------------------------------------------
-/** The score `ci.failBelow` gates: LOC-weighted mean function MI, 100 when empty. */
-export function reportScore(report) {
-    let weight = 0;
-    let total = 0;
-    for (const file of report.files.values()) {
-        if (!file.ok)
-            continue;
-        for (const fn of file.functions) {
-            weight += fn.metrics.length.value;
-            total += fn.metrics.mi.value * fn.metrics.length.value;
-        }
-    }
-    if (weight === 0)
-        return 100;
-    return Math.round((total / weight) * 10) / 10;
-}
-export function summarize(report) {
-    let errorFiles = 0;
-    let functions = 0;
-    let warn = 0;
-    let error = 0;
-    for (const file of report.files.values()) {
-        if (!file.ok)
-            errorFiles += 1;
-        functions += file.functions.length;
-    }
-    for (const finding of report.findings) {
-        if (finding.rank >= 2)
-            error += 1;
-        else
-            warn += 1;
-    }
-    return {
-        files: report.files.size,
-        errorFiles,
-        functions,
-        findings: report.findings.length,
-        warn,
-        error,
-        score: reportScore(report),
-    };
-}
-// ---------------------------------------------------------------------------
-// Baseline
-// ---------------------------------------------------------------------------
-export function buildBaseline(report) {
-    const functions = new Map();
-    for (const file of report.files.values()) {
-        if (!file.ok)
-            continue;
-        const entries = new Map();
-        for (const fn of file.functions) {
-            entries.set(`${fn.name}@${fn.startLine}`, {
-                cyclomatic: fn.metrics.cyclomatic.value,
-                cognitive: fn.metrics.cognitive.value,
-                nesting: fn.metrics.nesting.value,
-                length: fn.metrics.length.value,
-                halstead: fn.metrics.halstead.value,
-                mi: fn.metrics.mi.value,
-            });
-        }
-        if (entries.size > 0)
-            functions.set(file.path, entries);
-    }
-    const serialized = Object.fromEntries([...functions].map(([path, entries]) => [path, Object.fromEntries(entries)]));
-    return { version: 1, functions: serialized };
-}
-export function loadBaseline(cwd) {
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(join(cwd, ".howtofix", "quality-baseline.json"), "utf8"));
-    }
-    catch {
-        return undefined;
-    }
-    if (typeof parsed !== "object" || parsed === null)
-        return undefined;
-    const raw = parsed;
-    if (raw.version !== 1 || typeof raw.functions !== "object" || raw.functions === null)
-        return undefined;
-    return { version: 1, functions: raw.functions };
-}
-export function saveBaseline(cwd, baseline) {
-    const dir = join(cwd, ".howtofix");
-    mkdirSync(dir, { recursive: true });
-    const file = join(dir, "quality-baseline.json");
-    writeFileSync(file, `${JSON.stringify(baseline, null, 2)}\n`);
-    return relative(cwd, file);
-}
-/**
- * What changed against the baseline: a function that is new while over its
- * threshold, or one whose metric rank rose. Stored values are re-ranked with
- * the current config, so editing a threshold moves both sides together and
- * cannot fake a regression.
- */
-export function compareBaseline(baseline, report, config) {
-    const stored = new Map();
-    if (baseline) {
-        for (const [path, entries] of Object.entries(baseline.functions)) {
-            stored.set(path, new Map(Object.entries(entries)));
-        }
-    }
-    const regressions = [];
-    for (const file of report.files.values()) {
-        if (!file.ok)
-            continue;
-        const previous = stored.get(file.path);
-        for (const fn of file.functions) {
-            const key = `${fn.name}@${fn.startLine}`;
-            const before = previous?.get(key);
-            if (!before) {
-                if (fn.worstRank === 0)
-                    continue;
-                const worst = BASELINE_METRIC_ORDER.reduce((best, metric) => (fn.metrics[metric].rank > fn.metrics[best].rank ? metric : best));
-                regressions.push({ path: file.path, name: fn.name, startLine: fn.startLine, kind: "new", metric: worst, to: fn.metrics[worst].value });
-                continue;
-            }
-            for (const metric of BASELINE_METRIC_ORDER) {
-                const from = before[metric];
-                if (!isFiniteNumber(from))
-                    continue;
-                const rankFrom = rankOfBaselineMetric(metric, from, config.thresholds);
-                const rankTo = fn.metrics[metric].rank;
-                if (rankTo > rankFrom) {
-                    regressions.push({
-                        path: file.path,
-                        name: fn.name,
-                        startLine: fn.startLine,
-                        kind: "worsened",
-                        metric,
-                        from,
-                        to: fn.metrics[metric].value,
-                    });
-                }
-            }
-        }
-    }
-    return regressions;
-}
-/**
- * The `--strict` gate (spec §5, §7): parse errors, regressions against the
- * baseline, and a score under `ci.failBelow`. Without a baseline every flagged
- * function counts as new — the first CI run records one (`--update-baseline`)
- * instead of the gate being impossible to satisfy.
- */
-export function strictVerdict(report, config, baseline) {
-    const reasons = [];
-    for (const file of report.files.values()) {
-        if (!file.ok)
-            reasons.push(`${file.path}: parse error — ${file.error}`);
-    }
-    for (const regression of compareBaseline(baseline, report, config)) {
-        if (regression.kind === "new") {
-            reasons.push(`${regression.path}:${regression.startLine} ${regression.name} is new over threshold (${regression.metric} ${regression.to})`);
-        }
-        else {
-            reasons.push(`${regression.path}:${regression.startLine} ${regression.name} ${regression.metric} worsened ${regression.from} → ${regression.to}`);
-        }
-    }
-    const score = reportScore(report);
-    if (score < config.ci.failBelow) {
-        reasons.push(`score ${score} is below ci.failBelow ${config.ci.failBelow}`);
-    }
-    return { failed: reasons.length > 0, reasons };
-}
-// ---------------------------------------------------------------------------
-// Renderers
-// ---------------------------------------------------------------------------
-const FILE_MARKS = ["ok", "⚠", "✗"];
-const METRIC_ROWS = [
-    ["cyclomatic", "cyclomatic"],
-    ["cognitive", "cognitive"],
-    ["nesting", "nesting"],
-    ["length", "length"],
-    ["halstead", "halstead"],
-    ["mi", "MI"],
-    ["parameters", "parameters"],
-    ["booleanParameters", "boolean params"],
-];
-function warnLineOf(metric, thresholds) {
-    if (metric === "mi")
-        return thresholds.mi.warn;
-    if (metric === "booleanParameters")
-        return thresholds.parameters.warn;
-    return thresholds[metric].warn;
-}
-function metricRow(indent, label, value, warnLine) {
-    return `${indent}${label.padEnd(15)} ${value.value}   (limit ${warnLine})  ${RANK_LABELS[value.rank]}`;
-}
-function functionBlock(fn, config) {
-    const lines = [`  ${fn.name.padEnd(30)} L${fn.startLine}-${fn.endLine}`];
-    for (const [key, label] of METRIC_ROWS) {
-        const value = fn.metrics[key];
-        if (value.rank === 0)
-            continue;
-        if (key === "booleanParameters") {
-            lines.push(`    ${label.padEnd(15)} ${fn.booleanParameterNames.join(", ")}  warn`);
-            continue;
-        }
-        lines.push(metricRow("    ", label, value, warnLineOf(key, config.thresholds)));
-    }
-    if (fn.smells.length > 0) {
-        lines.push(`    ${"smells".padEnd(15)} ${fn.smells.map((smell) => smell.id).join(", ")}`);
-        for (const smell of fn.smells) {
-            lines.push(`    → ${SMELL_SUGGESTIONS[smell.id] ?? smell.label}`);
-        }
-    }
-    return lines;
-}
-function flaggedCount(fn) {
-    let count = fn.smells.length;
-    for (const key of FUNCTION_METRIC_ORDER)
-        if (fn.metrics[key].rank > 0)
-            count += 1;
-    return count;
-}
-function pickTop(report, top) {
-    const all = [];
-    for (const file of report.files.values()) {
-        for (const fn of file.functions)
-            if (fn.worstRank > 0)
-                all.push(fn);
-    }
-    all.sort((a, b) => {
-        if (a.worstRank !== b.worstRank)
-            return b.worstRank - a.worstRank;
-        const flagged = flaggedCount(b) - flaggedCount(a);
-        if (flagged !== 0)
-            return flagged;
-        const cc = b.metrics.cyclomatic.value - a.metrics.cyclomatic.value;
-        if (cc !== 0)
-            return cc;
-        return `${a.path}:${a.name}`.localeCompare(`${b.path}:${b.name}`);
-    });
-    const selected = new Map();
-    for (const fn of all.slice(0, top)) {
-        const bucket = selected.get(fn.path) ?? new Set();
-        bucket.add(`${fn.name}@${fn.startLine}`);
-        selected.set(fn.path, bucket);
-    }
-    return selected;
-}
-/**
- * The §6 human report: one header per file, details only where something is
- * flagged, names and line numbers always together, metric names in lowercase
- * spaces, and a concrete next step under every compound smell. `top` narrows
- * the listing to the N worst functions; the summary counts stay whole-report
- * so `--json`/`--sarif` parity holds.
- */
-export function formatHuman(report, config, options = {}) {
-    const summary = summarize(report);
-    const top = options.top && options.top > 0 ? pickTop(report, options.top) : undefined;
-    const shown = [...report.files.values()].filter((file) => !top || (top.get(file.path)?.size ?? 0) > 0);
-    const width = Math.max(40, ...shown.map((file) => file.path.length));
-    const out = [];
-    for (const file of shown) {
-        if (!file.ok) {
-            out.push(`${file.path.padEnd(width)}  parse error`);
-            out.push(`  ${file.error}`);
-            continue;
-        }
-        out.push(`${file.path.padEnd(width)}  MI ${file.metrics.mi.value}  ${FILE_MARKS[file.metrics.mi.rank]}`);
-        if (file.metrics.lines.rank > 0)
-            out.push(metricRow("  ", "file lines", file.metrics.lines, config.thresholds.fileLines.warn));
-        if (file.metrics.exports.rank > 0)
-            out.push(metricRow("  ", "exports", file.metrics.exports, config.thresholds.exports.warn));
-        for (const fn of file.functions) {
-            if (top && !top.get(file.path)?.has(`${fn.name}@${fn.startLine}`))
-                continue;
-            if (fn.worstRank === 0 && fn.smells.length === 0)
-                continue;
-            out.push(...functionBlock(fn, config));
-        }
-    }
-    if (out.length > 0)
-        out.push("");
-    const parseNote = summary.errorFiles > 0 ? `, ${summary.errorFiles} parse error(s)` : "";
-    out.push(`${summary.findings} findings in ${summary.files} files${parseNote} · ${summary.functions} functions · score ${summary.score}`);
-    return out.join("\n");
-}
-export function formatJson(report) {
-    const summary = summarize(report);
-    const files = [...report.files.values()].map((file) => ({
-        path: file.path,
-        ok: file.ok,
-        ...(file.ok ? {} : { error: file.error }),
-        lines: file.lines,
-        metrics: file.metrics,
-        functions: file.functions,
-    }));
-    return JSON.stringify({ version: 1, score: summary.score, summary, files, findings: report.findings }, null, 2);
-}
-const SARIF_LEVELS = ["warning", "error"];
-/** SARIF 2.1.0 for code scanning: one result per finding, regions included. */
-export function formatSarif(report) {
-    const rules = new Map();
-    for (const finding of report.findings) {
-        if (!rules.has(finding.metric))
-            rules.set(finding.metric, finding.metric);
-    }
-    const run = {
-        tool: {
-            driver: {
-                name: "howtofix-quality",
-                // The canonical repository, not a contributor's personal fork: this URL
-                // is what GitHub code scanning shows next to every finding, so pointing
-                // it at a fork credits the wrong place and breaks for anyone without
-                // access to that account.
-                informationUri: "https://github.com/NetroIndonesia/HowToFix-CLI",
-                rules: [...rules].map(([id, name]) => ({ id, name, shortDescription: { text: name } })),
-            },
-        },
-        results: report.findings.map((finding) => ({
-            ruleId: finding.metric,
-            level: SARIF_LEVELS[finding.rank >= 2 ? 1 : 0],
-            message: { text: finding.function ? `${finding.function}: ${finding.detail}` : finding.detail },
-            locations: [
-                {
-                    physicalLocation: {
-                        artifactLocation: { uri: finding.path },
-                        region: {
-                            startLine: finding.line,
-                            startColumn: finding.startColumn,
-                            endLine: finding.endLine,
-                            endColumn: finding.endColumn,
-                        },
-                    },
-                },
-            ],
-        })),
-    };
-    return JSON.stringify({ version: "2.1.0", $schema: "https://json.schemastore.org/sarif-2.1.0.json", runs: [run] }, null, 2);
-}
-const TS_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts"]);
-/** Never walked. `.howtofix` and friends start with a dot and are skipped on sight. */
-const SKIP_DIRS = new Set(["node_modules", "dist", "coverage"]);
-function walkForSources(dir, cwd, into) {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name))
-                continue;
-            walkForSources(full, cwd, into);
-            continue;
-        }
-        if (entry.isFile() && TS_EXTENSIONS.has(extname(entry.name)))
-            into.push(relative(cwd, full));
-    }
-}
-function gitLines(cwd, args) {
-    const run = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf8" });
-    if (run.error || run.status !== 0) {
-        const detail = run.error ? run.error.message : run.stderr.trim() || `exit ${run.status}`;
-        throw new Error(`git ${args.join(" ")} failed: ${detail}`);
-    }
-    return run.stdout.split("\n").filter((line) => line.trim().length > 0);
-}
-function changedPaths(cwd, base) {
-    const diff = gitLines(cwd, ["diff", "--name-only", "--diff-filter=ACMR", base]);
-    const untracked = gitLines(cwd, ["ls-files", "--others", "--exclude-standard"]);
-    return [...diff, ...untracked];
-}
-/** `dist/**` matches below dist, `vendor` matches the directory and its files. */
-function ignoredBy(relPath, pattern) {
-    if (!pattern.includes("*")) {
-        const prefix = pattern.endsWith("/") ? pattern : `${pattern}/`;
-        return relPath === pattern || relPath.startsWith(prefix);
-    }
-    const escaped = pattern
-        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-        .replace(/\*\*/g, "\u0000")
-        .replace(/\*/g, "[^/]*")
-        .replace(/\u0000/g, ".*");
-    return new RegExp(`^${escaped}$`).test(relPath);
-}
-/**
- * The batch to analyze: whole project, one target, or the changed set. Paths
- * come back relative to `cwd` (sorted, deduplicated, ignore-filtered) — they
- * are also the Map keys, so output paths stay readable and stable.
- */
-export function collectTargetPaths(cwd, options, ignore = []) {
-    let candidates;
-    if (options.changes) {
-        candidates = changedPaths(cwd, options.base ?? "HEAD");
-    }
-    else if (options.target) {
-        const full = resolve(cwd, options.target);
-        const stats = statSync(full, { throwIfNoEntry: false });
-        if (!stats)
-            throw new Error(`no such path: ${options.target}`);
-        if (stats.isDirectory()) {
-            candidates = [];
-            walkForSources(full, cwd, candidates);
-        }
-        else {
-            if (!TS_EXTENSIONS.has(extname(full)))
-                throw new Error(`not a TypeScript source file: ${options.target}`);
-            candidates = [relative(cwd, full)];
-        }
-    }
-    else {
-        candidates = [];
-        walkForSources(cwd, cwd, candidates);
-    }
-    const kept = new Set();
-    for (const path of candidates) {
-        if (!TS_EXTENSIONS.has(extname(path)))
-            continue;
-        if (ignore.some((pattern) => ignoredBy(path, pattern)))
-            continue;
-        kept.add(path);
-    }
-    return [...kept].sort();
-}