pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/core/checks/findings.js

@@ -0,0 +1,701 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execa } from '../../utils/execa.js';
+import { logger, matchesAnyGlob } from '../../utils/index.js';
+import { listTrackedFiles } from '../targets.js';
+import { fail, pass, warn } from '../types.js';
+/**
+ * Resolve a check's effective severity (`configured` from config, else its
+ * `fallback`) into a matched logger, icon, and outcome constructor — so a check
+ * logs and returns consistently at whatever level the client chose.
+ */
+export function severityEmitter(configured, fallback) {
+    const isError = (configured ?? fallback) === 'error';
+    return {
+        log: (isError ? logger.error : logger.warn).bind(logger),
+        icon: isError ? '❌' : '⚠️',
+        emit: (details) => (isError ? fail(details) : warn(details)),
+    };
+}
+/** Append `from`'s samples to `into`, merging labels both sides produced. */
+function mergeBucket(into, from) {
+    for (const [label, items] of Object.entries(from))
+        (into[label] ?? (into[label] = [])).push(...items);
+}
+/**
+ * Fold one scan's findings into a check's running totals.
+ *
+ * Checks accumulate across several scans — one per language, or one per file on
+ * the full-scan path — so every accumulating check needs this, and each had the
+ * same pair of nested loops written out inline.
+ */
+export function mergeSeverityBuckets(into, from) {
+    mergeBucket(into.errors, from.errors);
+    mergeBucket(into.warnings, from.warnings);
+}
+/** A fresh pair of empty buckets for a check to accumulate into. */
+export function emptyBuckets() {
+    return { errors: {}, warnings: {} };
+}
+/**
+ * Inline opt-out honoured by every content check, on both the diff path and the
+ * whole-file path — a line muted in a PR must stay muted in a full scan.
+ */
+const IGNORE_DIRECTIVE = 'pr-checkmate-ignore';
+/**
+ * Run `git diff` over the given file globs, returning the raw unified diff
+ * (zero context, added/copied/modified/renamed files) for added-line scanning.
+ */
+export async function diffAddedLines(ctx, globs) {
+    const args = [
+        'diff',
+        '--unified=0',
+        '--diff-filter=ACMR',
+        ctx.baseSha,
+        ctx.headSha ?? 'HEAD',
+        '--',
+        ...globs,
+    ];
+    const cacheKey = `d:${args.join('')}`;
+    let stdout = ctx.cache?.get(cacheKey);
+    if (stdout === undefined) {
+        stdout = (await execa('git', args, { cwd: ctx.cwd })).stdout;
+        ctx.cache?.set(cacheKey, stdout);
+    }
+    // Universal inline suppression: strip added lines opted out with the
+    // `pr-checkmate-ignore` directive, so every content check that scans this
+    // diff honours it without repeating the check itself.
+    return stdout
+        .split('\n')
+        .filter(line => !(line.startsWith('+') && line.includes(IGNORE_DIRECTIVE)))
+        .join('\n');
+}
+/**
+ * Present tracked files as if every line had just been added, so a check written
+ * for a diff can review the whole repository unchanged.
+ *
+ * The patterns are anchored on the diff's `+` marker (`/^\+(?!\+)…/`), which is
+ * why `--full` used to skip most of the security surface: no diff, no lines
+ * starting with `+`, no findings. Rather than rewrite forty patterns — and lose
+ * the guarantee that both modes agree — the file contents are wrapped in the
+ * shape the pipeline already understands. Comment stripping, string blanking,
+ * `view: 'code'`, grouping and every client knob then work identically.
+ *
+ * Files are read one at a time and handed to `onFile` rather than concatenated:
+ * a monorepo would otherwise be assembled into a single multi-megabyte string
+ * before the first pattern ran.
+ */
+export async function scanTrackedFiles(ctx, files, onFile) {
+    for (const file of files) {
+        let content;
+        try {
+            content = fs.readFileSync(path.join(ctx.cwd, file), 'utf-8');
+        }
+        catch {
+            // Unreadable or vanished between listing and reading — nothing to review.
+            continue;
+        }
+        // Binary files have no lines worth matching and would produce nonsense
+        // samples in the report.
+        if (content.includes('\0'))
+            continue;
+        // The `pr-checkmate-ignore` opt-out has to be honoured here too. It is applied
+        // in `diffAddedLines` for the delta path, and a line muted in a PR that then
+        // reappears in the full scan would make the directive look unreliable.
+        const lines = content
+            .split('\n')
+            .filter(line => !line.includes(IGNORE_DIRECTIVE))
+            .map(line => `+${line}`);
+        // The `+++` header tells `scanDiffPatterns` which comment syntax applies;
+        // the `@@` hunk header is what makes line numbers come out 1-based for the
+        // checks that report them (Merge Conflict). Without it they start at zero.
+        onFile([`+++ b/${file}`, `@@ -0,0 +1,${lines.length} @@`, ...lines].join('\n'));
+    }
+}
+/**
+ * Hand a check the lines it should review, from the diff when there is one and
+ * from the tracked files otherwise.
+ *
+ * The single entry point every content check uses, so the choice between the two
+ * modes is made once rather than re-implemented per check — and so a check cannot
+ * accidentally support only one of them, which is how `--full` ended up with no
+ * security coverage at all (ticket 067).
+ *
+ * `onChunk` is called once per diff in delta mode and once per file in full mode,
+ * which keeps a whole monorepo from being concatenated before matching starts.
+ *
+ * Returns whether the review actually happened. `false` means git could not
+ * produce a file list, and the caller has to say so rather than report a pass:
+ * a check that reviewed nothing looks exactly like a check that found nothing,
+ * and that is the whole of ticket 072. `fullScanBehaviour: "skip"` is the one
+ * case where `true` is returned having reviewed nothing on purpose — the client
+ * asked for that, so it is not a hole in coverage.
+ */
+export async function reviewLines(ctx, globs, onChunk) {
+    if (ctx.baseSha) {
+        onChunk(await diffAddedLines(ctx, globs));
+        return true;
+    }
+    if (ctx.config.run?.fullScanBehaviour === 'skip')
+        return true;
+    const files = await listTrackedFiles(ctx, globs, ['.']);
+    if (files === null)
+        return false;
+    await scanTrackedFiles(ctx, files, onChunk);
+    return true;
+}
+const C_LIKE_EXTENSIONS = new Set([
+    'ts',
+    'tsx',
+    'js',
+    'jsx',
+    'mjs',
+    'cjs',
+    'go',
+    'java',
+    'kt',
+    'kts',
+    'cs',
+    'c',
+    'cc',
+    'cpp',
+    'cxx',
+    'h',
+    'hpp',
+    'php',
+    'rs',
+    'swift',
+    'scala',
+    'm',
+    'mm',
+]);
+const HASH_EXTENSIONS = new Set([
+    'py',
+    'pyi',
+    'sh',
+    'bash',
+    'zsh',
+    'ksh',
+    'yml',
+    'yaml',
+    'rb',
+    'toml',
+    'tf',
+    'pl',
+    'r',
+]);
+/** Comment syntax for a repo-relative path; `both` when the extension is unknown. */
+export function commentSyntaxFor(file) {
+    const ext = file.slice(file.lastIndexOf('.') + 1).toLowerCase();
+    if (C_LIKE_EXTENSIONS.has(ext))
+        return 'c-like';
+    if (HASH_EXTENSIONS.has(ext))
+        return 'hash';
+    return 'both';
+}
+/**
+ * True when the `//` at `i` opens a comment rather than a regex literal.
+ *
+ * A regex literal can contain `//` (`line.replace(/\/\//g, '')`), and treating
+ * it as a comment truncates the line — dropping whatever a security pattern
+ * would have matched further along. Regex literals only appear where a value is
+ * expected, so the preceding non-space character is enough to tell them apart
+ * without tokenizing.
+ */
+function isCommentSlash(line, i) {
+    const before = line.slice(0, i).trimEnd();
+    if (before.length === 0)
+        return true;
+    // These all precede a value, so a `/` after one opens a regex literal.
+    // `;` and `}` are deliberately absent: they close a statement, where a
+    // trailing `// comment` is overwhelmingly the more likely reading.
+    if (/[(,=:[!&|?]$/.test(before))
+        return false;
+    return !/\breturn$/.test(before);
+}
+/** Returned by a {@link walkStringState} visitor to end the walk early. */
+const STOP = Symbol('stop');
+/**
+ * Walk `line` once, reporting for each character whether it sits inside a string
+ * literal.
+ *
+ * The bookkeeping — which quote opened the literal, and that a backslash escapes
+ * the closing one — is the part {@link stripInlineComment} and
+ * {@link stripStringLiterals} genuinely have in common; only what each does with
+ * the answer differs. Kept in one place so a correction to the escape handling
+ * cannot land in one of them and be forgotten in the other.
+ *
+ * A visitor may return an index to resume the walk from, which is how a caller
+ * skips wholesale past a regex literal, or {@link STOP} to end the walk.
+ */
+function walkStringState(line, visit) {
+    let quote = '';
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        const closes = quote !== '' && c === quote && line[i - 1] !== '\\';
+        const opens = quote === '' && (c === '"' || c === "'" || c === '`');
+        const signal = visit({ c, i, inString: quote !== '', isDelimiter: closes || opens });
+        if (signal === STOP)
+            return;
+        if (typeof signal === 'number') {
+            i = signal;
+            continue;
+        }
+        if (closes)
+            quote = '';
+        else if (opens)
+            quote = c;
+    }
+}
+/**
+ * Strip a trailing line comment from a line, tracking quote state so a marker
+ * inside a string literal (a `#` in `"#fff"`, a `//` in a quoted URL) survives.
+ *
+ * Heuristic, not a tokenizer. `syntax` selects the applicable markers — passing
+ * the wrong one is how a valid `this.#handler = eval(payload)` used to be read
+ * as a comment and dropped entirely (ticket 059).
+ *
+ * Block comments are handled by the caller, which alone can track `/* *\/` state
+ * across lines; see {@link scanDiffPatterns}.
+ */
+export function stripInlineComment(line, syntax = 'both') {
+    const hash = syntax !== 'c-like';
+    const slash = syntax !== 'hash';
+    let cut = -1;
+    walkStringState(line, ({ c, i, inString, isDelimiter }) => {
+        if (inString || isDelimiter)
+            return;
+        if (hash && c === '#') {
+            cut = i;
+            return STOP;
+        }
+        if (slash && c === '/') {
+            // A `/` where a value is expected opens a regex literal. Skipping past it
+            // wholesale is what handles the escaped slashes inside one — `/\/\//` ends
+            // in two literal `/` characters that would otherwise read as a comment.
+            if (!isCommentSlash(line, i))
+                return endOfRegexLiteral(line, i);
+            if (line[i + 1] === '/') {
+                cut = i;
+                return STOP;
+            }
+        }
+    });
+    return cut === -1 ? line : line.slice(0, cut);
+}
+/**
+ * Index of the closing `/` of the regex literal opening at `start`, or the end
+ * of the line when it never closes. Escapes and character classes both hide a
+ * `/` that does not terminate the literal.
+ */
+function endOfRegexLiteral(line, start) {
+    let inClass = false;
+    for (let i = start + 1; i < line.length; i++) {
+        const c = line[i];
+        if (c === '\\') {
+            i++;
+            continue;
+        }
+        if (c === '[')
+            inClass = true;
+        else if (c === ']')
+            inClass = false;
+        else if (c === '/' && !inClass)
+            return i;
+    }
+    return line.length;
+}
+/**
+ * Blank out the contents of string literals, keeping the quotes and the original
+ * length so the rest of the line still reads as code.
+ *
+ * This is what lets a pattern ask "is a real call being made here" without a
+ * lookahead that guesses at quoting. The `eval` rule used to carry
+ * `(?![^'"`]*['"`])` — intended to skip `eval` written inside a string, but in
+ * practice it disabled the rule on any line containing a quote anywhere, so
+ * `eval(userInput + "x")` and ``eval(`${payload}`)`` both went unreported
+ * (ticket 058).
+ *
+ * Only for patterns that match *code*. Rules that look for string *contents* —
+ * an SQL keyword inside quotes, a hardcoded URL — must keep reading the raw
+ * line, which is what {@link DiffPattern.view} selects.
+ */
+export function stripStringLiterals(line) {
+    let out = '';
+    // Both quotes are kept and only what they enclose is blanked, so the line
+    // still reads as code — `f("x")` stays a call with an argument.
+    walkStringState(line, ({ c, inString, isDelimiter }) => {
+        out += inString && !isDelimiter ? ' ' : c;
+    });
+    return out;
+}
+/** Characters kept per logged sample, so one minified added line can't flood the log. */
+const SAMPLE_MAX_LENGTH = 120;
+/**
+ * Cross-line taint tracking: the cheapest useful step beyond a per-line regex.
+ *
+ * A per-line pattern cannot see the shape that actually ships:
+ *
+ * ```ts
+ * const q = `SELECT * FROM u WHERE id=${id}`;
+ * db.query(q);
+ * ```
+ *
+ * Both halves are innocent alone — a template literal is not a query, and
+ * `query(q)` is not an interpolation — so the built-in rule, which requires the
+ * backtick *inside* the call, misses it entirely. That is the most ordinary way
+ * anyone writes an injection.
+ *
+ * This is deliberately not dataflow analysis. It remembers one thing (a variable
+ * assigned from an interpolated template literal), for a bounded number of added
+ * lines, inside one hunk, and reports when that name is handed to a query sink.
+ * No scopes, no reassignment, no function boundaries. Ticket 058 calls the
+ * ceiling out on purpose: an honest boundary beats an inflated promise, and the
+ * finding is rated `warn` because a heuristic must not block a build.
+ */
+const TAINT_DECLARATION = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*`[^`]*\$\{/;
+/** Sinks that turn a tainted string into a query. */
+const TAINT_SINKS = 'query|execute|exec|raw';
+/**
+ * How many added lines a taint survives, for the one check that asks for it.
+ *
+ * Exported because the default belongs to Diff Security, not to this function:
+ * `scanDiffPatterns` is shared by Diff Smells, Workflow Security and Dockerfile
+ * Security too, and defaulting the heuristic ON here leaked a finding labelled
+ * "SQL injection risk" into a code-smell report — under the wrong check, three
+ * times per run, off a config key (`diffSecurity.dataflowWindow`) that has no
+ * meaning for any of them. Caught by our own Diff Smells row.
+ */
+export const DEFAULT_DATAFLOW_WINDOW = 10;
+const CROSS_LINE_SQL_LABEL = 'Interpolated value reaches a query (SQL injection risk, cross-line)';
+/** `@@ ... @@` — a new hunk, and the boundary taint never crosses. */
+const DIFF_HUNK_HEADER = /^@@ /;
+/**
+ * Whether this line hands `name` to a query sink.
+ *
+ * Built per lookup rather than cached: the set of tracked names is at most a
+ * handful per hunk, and a regex assembled from a captured identifier must not
+ * outlive the hunk that captured it.
+ */
+function reachesSink(code, name) {
+    return new RegExp(`\\b(?:${TAINT_SINKS})\\s*\\(\\s*${name}\\s*[,)]`).test(code);
+}
+/**
+ * The per-hunk taint state, kept out of {@link scanDiffPatterns} so the scan loop
+ * stays one thing: match patterns, collect findings. A tracker built with a
+ * window of `0` answers `false` to everything and records nothing, which is how
+ * the heuristic switches off without a branch at the call site.
+ */
+function taintTracker(window) {
+    let tainted = new Map();
+    let ordinal = 0;
+    return {
+        reset: () => {
+            tainted = new Map();
+            ordinal = 0;
+        },
+        inspect: (rawText, asCode) => {
+            if (window <= 0)
+                return false;
+            ordinal += 1;
+            // Sinks are looked for before new taints are recorded, so a line that both
+            // declares and consumes cannot report against itself — that shape is
+            // already covered by the built-in same-line rule.
+            let hit = false;
+            for (const [name, declaredAt] of tainted) {
+                if (ordinal - declaredAt > window) {
+                    tainted.delete(name);
+                    continue;
+                }
+                if (reachesSink(asCode, name))
+                    hit = true;
+            }
+            // Matched on the raw text: `stripStringLiterals` blanks the `${...}` that
+            // is the entire reason the value is suspect.
+            const declared = TAINT_DECLARATION.exec(rawText);
+            if (declared)
+                tainted.set(declared[1], ordinal);
+            return hit;
+        },
+    };
+}
+/** `+++ b/path/to/file.ts` — the header that says which file follows. */
+const DIFF_FILE_HEADER = /^\+\+\+ b\/(.+)$/;
+/**
+ * Bucket added diff lines by the {@link DiffPattern}s they match, split by
+ * severity. Patterns are expected to anchor on the leading `+` themselves
+ * (`/^\+(?!\+)…/`), which is what keeps `+++` file headers and context lines out.
+ *
+ * Comment handling follows the file each hunk belongs to, read from the `+++`
+ * headers as the diff is walked — a single run reviews files of several
+ * languages, so a repo-wide setting would be wrong for most of them.
+ *
+ * `skipIgnored` re-applies the `pr-checkmate-ignore` opt-out for callers that run
+ * `git diff` themselves; a diff obtained from {@link diffAddedLines} is already
+ * filtered and should leave it off.
+ *
+ * `comments: 'off'` scans lines verbatim, which is how a client audits code that
+ * was commented out rather than deleted.
+ */
+export function scanDiffPatterns(stdout, patterns, opts = {}) {
+    const errors = {};
+    const warnings = {};
+    const mode = opts.comments ?? 'language';
+    const ignorePaths = opts.ignorePaths ?? [];
+    let syntax = 'both';
+    // Block comments span lines, so the state belongs to the walk, not to one line.
+    let inBlockComment = false;
+    // Whole files can be excluded by glob; the flag persists until the next header.
+    let skippingFile = false;
+    // Cleared at every file and hunk boundary: two unrelated hunks are not two
+    // halves of one flow.
+    const taint = taintTracker(Math.max(0, opts.dataflowWindow ?? 0));
+    for (const line of stdout.split('\n')) {
+        const header = DIFF_FILE_HEADER.exec(line);
+        if (header) {
+            syntax = mode === 'language' ? commentSyntaxFor(header[1]) : 'both';
+            inBlockComment = false;
+            skippingFile = ignorePaths.length > 0 && matchesAnyGlob(header[1], ignorePaths);
+            taint.reset();
+            continue;
+        }
+        // Checked before the `+` filter below, which a hunk header does not satisfy.
+        if (DIFF_HUNK_HEADER.test(line)) {
+            taint.reset();
+            continue;
+        }
+        if (skippingFile)
+            continue;
+        // Only added lines carry block-comment state: a `-` line is code being
+        // removed, and letting it open a `/*` would blank the additions after it.
+        if (!line.startsWith('+'))
+            continue;
+        if (opts.skipIgnored && line.includes(IGNORE_DIRECTIVE))
+            continue;
+        const prepared = uncomment(line, { mode, syntax, inBlockComment });
+        inBlockComment = prepared.inBlockComment;
+        const asCode = stripStringLiterals(prepared.text);
+        for (const { pattern, label, severity, view } of patterns) {
+            if (pattern.test(view === 'code' ? asCode : prepared.text)) {
+                const bucket = severity === 'error' ? errors : warnings;
+                (bucket[label] ?? (bucket[label] = [])).push(line.slice(1).trim().substring(0, SAMPLE_MAX_LENGTH));
+            }
+        }
+        if (taint.inspect(prepared.text, asCode)) {
+            (warnings[CROSS_LINE_SQL_LABEL] ?? (warnings[CROSS_LINE_SQL_LABEL] = [])).push(line.slice(1).trim().substring(0, SAMPLE_MAX_LENGTH));
+        }
+    }
+    return { errors, warnings };
+}
+/**
+ * Reduce one added line to what should be matched against: block comments
+ * blanked (carrying the open state on), then the trailing line comment removed.
+ * `mode: 'off'` returns the line untouched.
+ */
+function uncomment(line, state) {
+    const { mode, syntax } = state;
+    if (mode === 'off')
+        return { text: line, inBlockComment: false };
+    // `hash` languages have no `/* */`, and running the stripper over them would
+    // eat a legitimate `/*` appearing in, say, a shell glob.
+    if (syntax === 'hash') {
+        return { text: stripInlineComment(line, syntax), inBlockComment: false };
+    }
+    const { text, open } = stripBlockComments(line, state.inBlockComment);
+    return { text: stripInlineComment(text, syntax), inBlockComment: open };
+}
+/**
+ * Blank out `/* … *\/` regions, carrying the open state across lines. Without
+ * this a call commented out with a block comment reads as live code, and — worse
+ * — a line ending mid-comment leaves the rest of the hunk being scanned as if it
+ * were code.
+ */
+function stripBlockComments(line, open) {
+    let out = '';
+    let i = 0;
+    let inside = open;
+    while (i < line.length) {
+        if (inside) {
+            const end = line.indexOf('*/', i);
+            if (end === -1)
+                return { text: out, open: true };
+            out += ' '.repeat(end + 2 - i);
+            i = end + 2;
+            inside = false;
+            continue;
+        }
+        const start = line.indexOf('/*', i);
+        if (start === -1) {
+            out += line.slice(i);
+            break;
+        }
+        out += line.slice(i, start);
+        i = start;
+        inside = true;
+    }
+    return { text: out, open: inside };
+}
+/** Total number of findings across all labels in a bucket. */
+/** How many findings reach the log before the rest are counted instead. */
+const MAX_LOGGED = 10;
+/**
+ * Log a capped sample of raw output lines under a one-line summary.
+ *
+ * The cap is the point: a linter with 400 offences must not push the rest of the
+ * report out of a CI log's scrollback, and the count that follows the sample is
+ * what keeps the truncation from reading as the whole story.
+ *
+ * Deliberately not the private `logFindings` below, which this nearly collided
+ * with. That one takes findings already grouped into labelled buckets and pairs
+ * the log with a severity; this one takes lines a tool printed and does nothing
+ * but show them, which is what a check wrapping somebody else's output needs and
+ * the only thing it can honestly claim about them.
+ *
+ * Here rather than beside its first caller because three categories want it now —
+ * the language runner, the Python type check, and Duplicate Code — and a
+ * `quality/` check importing from `languages/` to get a logger was the wrong
+ * shape (ticket 079).
+ */
+export function logSample(name, summary, lines) {
+    logger.warn(`[${name}]: ⚠️ ${summary}`);
+    lines.slice(0, MAX_LOGGED).forEach(line => logger.warn(`  ${line}`));
+    if (lines.length > MAX_LOGGED)
+        logger.warn(`  ... and ${lines.length - MAX_LOGGED} more`);
+}
+export function bucketTotal(bucket) {
+    return Object.values(bucket).reduce((sum, arr) => sum + arr.length, 0);
+}
+/**
+ * Report a bucket at the check's configured level, summarized as
+ * `9× console.*(), 1× debugger statement`.
+ *
+ * The phrasing every keyword-counting check uses: the label already says what
+ * was found, so only the count varies. Written out per check, the four-step tail
+ * — resolve the level, log at it, join the counts, emit at the same level — was
+ * copied verbatim, and `isError: sev.icon === '❌'` is exactly the kind of link
+ * between two of those steps that silently rots when only one side is edited.
+ */
+export function reportCountedFindings(findings, ctx, opts) {
+    const sev = severityEmitter(opts.severity, opts.fallback ?? 'warn');
+    logFindings(findings, {
+        prefix: opts.prefix,
+        sampleLimit: opts.sampleLimit ?? ctx.config.log?.sampleLimit ?? 3,
+        isError: sev.icon === '❌',
+    });
+    const label = opts.summaryLabel ?? ((l) => l);
+    const summary = Object.entries(findings)
+        .map(([name, arr]) => `${arr.length}× ${label(name)}`)
+        .join(', ');
+    return sev.emit(summary + (opts.suffix ?? ''));
+}
+/**
+ * Log one bucket of findings using the shared check format.
+ *
+ * Internal: checks reach it through {@link reportCountedFindings} or
+ * {@link reportSeverityBuckets}, which pair the logging with the outcome so the
+ * two cannot report different levels.
+ */
+function logFindings(bucket, opts) {
+    const emit = opts.isError ? logger.error.bind(logger) : logger.warn.bind(logger);
+    const icon = opts.isError ? '❌' : '⚠️';
+    const showCount = opts.showCount ?? true;
+    const { sampleLimit } = opts;
+    for (const [label, items] of Object.entries(bucket)) {
+        emit(`[${opts.prefix}]: ${icon} ${label}${showCount ? `: ${items.length} occurrence(s)` : ':'}`);
+        const shown = sampleLimit === undefined ? items : items.slice(0, sampleLimit);
+        shown.forEach(item => emit(`    ${item}`));
+        if (sampleLimit !== undefined && items.length > sampleLimit) {
+            emit(`    ... and ${items.length - sampleLimit} more`);
+        }
+    }
+}
+/**
+ * The half of {@link SeverityReportOptions} every check fills in identically:
+ * the client's own `<check>.ignore` / `failOn` / `severityOverrides`, the shared
+ * sample limit, and the repo-wide `severityDefaults` fallback.
+ *
+ * Only the phrasing (`prefix` and the two summaries) is ever check-specific, so
+ * spelling the rest out per check meant five lines of copy-paste that had to be
+ * kept in step by hand — and a check that forgot one line silently ignored a
+ * knob the client had set.
+ */
+export function clientFindingOptions(ctx, cfg = {}) {
+    return {
+        sampleLimit: ctx.config.log?.sampleLimit ?? 3,
+        ignore: cfg.ignore,
+        failOn: cfg.failOn,
+        severityOverrides: cfg.severityOverrides,
+        defaults: ctx.config.severityDefaults,
+    };
+}
+/** Remove bucket entries whose label matches any ignore substring. */
+function dropIgnored(bucket, ignore) {
+    if (ignore.length === 0)
+        return bucket;
+    const lowered = ignore.map(i => i.toLowerCase());
+    const kept = {};
+    for (const [label, items] of Object.entries(bucket)) {
+        if (!lowered.some(i => label.toLowerCase().includes(i)))
+            kept[label] = items;
+    }
+    return kept;
+}
+/**
+ * Re-file findings according to the client's per-label overrides, returning
+ * fresh buckets. A label matching several overrides takes the longest (most
+ * specific) match, so a broad rule and a narrow exception can coexist.
+ */
+function applyOverrides(errors, warnings, overrides) {
+    const entries = Object.entries(overrides).map(([k, v]) => [k.toLowerCase(), v]);
+    if (entries.length === 0)
+        return { errors, warnings };
+    const out = { errors: {}, warnings: {} };
+    const place = (label, items, fallback) => {
+        const lowered = label.toLowerCase();
+        const matches = entries.filter(([key]) => lowered.includes(key));
+        const best = matches.sort((a, b) => b[0].length - a[0].length)[0];
+        const level = best ? best[1] : fallback;
+        if (level === 'off')
+            return;
+        const bucket = level === 'error' ? out.errors : out.warnings;
+        (bucket[label] ?? (bucket[label] = [])).push(...items);
+    };
+    for (const [label, items] of Object.entries(errors))
+        place(label, items, 'error');
+    for (const [label, items] of Object.entries(warnings))
+        place(label, items, 'warn');
+    return out;
+}
+/**
+ * Report error/warning finding buckets: log both, then produce the outcome.
+ *
+ * Order is the contract, and each step exists because the one before it is too
+ * blunt on its own:
+ *   1. `ignore` — drop the finding outright.
+ *   2. `severityOverrides` — re-file what survived.
+ *   3. `failOn` — decide what a remaining error means for the run.
+ * The universal `severity[<check name>]` map is applied later still, by the
+ * orchestrator, so a client can always override a check wholesale by name.
+ */
+export function reportSeverityBuckets(errorsIn, warningsIn, opts) {
+    const ignore = opts.ignore ?? [];
+    const filed = applyOverrides(dropIgnored(errorsIn, ignore), dropIgnored(warningsIn, ignore), opts.severityOverrides ?? {});
+    const { errors, warnings } = filed;
+    const totalErrors = bucketTotal(errors);
+    const totalWarnings = bucketTotal(warnings);
+    if (totalErrors === 0 && totalWarnings === 0)
+        return pass();
+    const logOpts = { prefix: opts.prefix, showCount: opts.showCount, sampleLimit: opts.sampleLimit };
+    logFindings(errors, { ...logOpts, isError: true });
+    logFindings(warnings, { ...logOpts, isError: false });
+    const failOn = opts.failOn ?? opts.defaults?.failOn ?? 'error';
+    if (failOn === 'never')
+        return pass();
+    const parts = [];
+    if (totalErrors > 0)
+        parts.push(opts.errorSummary(totalErrors));
+    if (totalWarnings > 0)
+        parts.push(opts.warningSummary(totalWarnings));
+    const summary = parts.join(', ');
+    return failOn === 'error' && totalErrors > 0 ? fail(summary) : warn(summary);
+}