pr-checkmate 3.0.3 → 3.1.0

package/dist/esm/core/checks/findings.d.ts

@@ -0,0 +1,299 @@
+import { CheckContext, CheckOutcome } from '../types.js';
+/**
+ * Client-configurable severity for a check's findings, read from that check's
+ * config block (e.g. `mergeConflict.severity`). `error` fails the run, `warn`
+ * only advises. Every check declares a natural default; the client overrides it
+ * per repo in pr-checkmate.json — promoting an advisory check to a gate, or
+ * downgrading a blocking one, with no code change.
+ *
+ * Deliberately not exported, here and for {@link SeverityEmitter}: no module
+ * names either type, and `tsc` inlines both into `findings.d.ts` anyway, so an
+ * `export` would only be API surface the Dead Code check then reports as unused.
+ */
+type Severity = 'error' | 'warn';
+interface SeverityEmitter {
+    /** Log at the resolved level (`logger.error` for error, `logger.warn` for warn). */
+    log: (msg: string) => void;
+    /** Prefix icon matching the level. */
+    icon: string;
+    /** Build the outcome at the resolved level (`fail` for error, `warn` for warn). */
+    emit: (details: string) => CheckOutcome;
+}
+/**
+ * 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 declare function severityEmitter(configured: Severity | undefined, fallback: Severity): SeverityEmitter;
+/** Findings grouped by label → matching sample strings. */
+export type FindingBucket = Record<string, string[]>;
+/** One scan's findings, split by the level each pattern assigned them. */
+export interface SeverityBuckets {
+    errors: FindingBucket;
+    warnings: FindingBucket;
+}
+/**
+ * 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 declare function mergeSeverityBuckets(into: SeverityBuckets, from: SeverityBuckets): void;
+/** A fresh pair of empty buckets for a check to accumulate into. */
+export declare function emptyBuckets(): SeverityBuckets;
+/**
+ * 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 declare function diffAddedLines(ctx: CheckContext, globs: string[]): Promise<string>;
+/**
+ * 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 declare function scanTrackedFiles(ctx: CheckContext, files: string[], onFile: (asDiff: string) => void): Promise<void>;
+/**
+ * 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 declare function reviewLines(ctx: CheckContext, globs: string[], onChunk: (stdout: string) => void): Promise<boolean>;
+/**
+ * Which comment markers apply to a file, since they are not universal:
+ * - `c-like` — `//` only. `#` is NOT a comment in C-family syntax, where it
+ *   opens a JS private field (`this.#handler`) or a C preprocessor directive.
+ * - `hash` — `#` only. `//` in Python or YAML is division or part of a URL.
+ * - `both` — unknown extension: strip either, which over-strips rather than
+ *   under-reports. The conservative default, and the pre-060 behaviour.
+ */
+export type CommentSyntax = 'c-like' | 'hash' | 'both';
+/** Comment syntax for a repo-relative path; `both` when the extension is unknown. */
+export declare function commentSyntaxFor(file: string): CommentSyntax;
+/**
+ * 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 declare function stripInlineComment(line: string, syntax?: CommentSyntax): string;
+/**
+ * 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 declare function stripStringLiterals(line: string): string;
+/** One regex-matched finding: which added lines to flag, under what label and level. */
+export interface DiffPattern {
+    pattern: RegExp;
+    label: string;
+    severity: Severity;
+    /**
+     * Which view of the line the pattern reads.
+     * - `raw` (default) — the line as written, comments already stripped. Required
+     *   by rules that inspect string *contents*, e.g. an SQL keyword in quotes.
+     * - `code` — string literals blanked by {@link stripStringLiterals}, so a rule
+     *   matching a *call* is not thrown off by unrelated quoting on the same line.
+     */
+    view?: 'raw' | 'code';
+}
+/**
+ * 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 declare const DEFAULT_DATAFLOW_WINDOW = 10;
+/**
+ * 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 declare function scanDiffPatterns(stdout: string, patterns: readonly DiffPattern[], opts?: {
+    skipIgnored?: boolean;
+    comments?: 'language' | 'legacy' | 'off';
+    /** Globs whose files are skipped entirely (client `<check>.ignorePaths`). */
+    ignorePaths?: string[];
+    /**
+     * Added lines a taint survives for the cross-line SQL heuristic.
+     *
+     * Off unless the caller asks. Only Diff Security owns this behaviour — it is
+     * configured by `diffSecurity.dataflowWindow` and reports a security label —
+     * so every other caller of this function gets a plain pattern scan.
+     */
+    dataflowWindow?: number;
+}): SeverityBuckets;
+/**
+ * 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 declare function logSample(name: string, summary: string, lines: string[]): void;
+export declare function bucketTotal(bucket: FindingBucket): number;
+/**
+ * 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 declare function reportCountedFindings(findings: FindingBucket, ctx: CheckContext, opts: {
+    /** Log prefix, e.g. 'TODO/FIXME'. */
+    prefix: string;
+    /** The client's level for this check, e.g. `ctx.config.todoFixme?.severity`. */
+    severity?: Severity;
+    /** Level to use when the client configured none. Defaults to `warn`. */
+    fallback?: Severity;
+    /** Samples printed per label. Defaults to the client's `log.sampleLimit`, else 3. */
+    sampleLimit?: number;
+    /** Shorten a label for the summary only, e.g. drop an explanatory tail. */
+    summaryLabel?: (label: string) => string;
+    /** Appended to the summary, e.g. ` (no ticket reference)`. */
+    suffix?: string;
+}): CheckOutcome;
+interface SeverityReportOptions {
+    /** Log prefix, e.g. 'Diff Security'. */
+    prefix: string;
+    /** Summary phrasing given the error count. */
+    errorSummary: (n: number) => string;
+    /** Summary phrasing given the warning count. */
+    warningSummary: (n: number) => string;
+    /** Append ": N occurrence(s)" after each label (default true). */
+    showCount?: boolean;
+    /** Max samples printed per label; omit to print all. */
+    sampleLimit?: number;
+    /**
+     * Finding labels to suppress (client `<check>.ignore`). A label is dropped
+     * when it contains any ignore entry (case-insensitive), so a repo can mute a
+     * single built-in finding without disabling the whole check.
+     */
+    ignore?: string[];
+    /**
+     * What a non-empty error bucket means for the run (client `<check>.failOn`):
+     * - `error` — block it (`fail`). The default: a finding the check itself rates
+     *   `error` is meant to gate the merge, which is what a PR gate is for.
+     * - `warn` — report but never block, whatever the finding's own severity.
+     * - `never` — always `pass`; the findings are still logged.
+     *
+     * Falls back to `defaults.failOn`, then to `error`.
+     */
+    failOn?: FailOn;
+    /**
+     * Per-finding level overrides (client `<check>.severityOverrides`), keyed by a
+     * case-insensitive substring of the label. Lets a repo demote one noisy rule,
+     * promote one it cares about, or drop a single finding — without turning the
+     * whole check off. `off` removes the finding entirely, like `ignore`.
+     */
+    severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
+    /** Repo-wide fallbacks (client `severityDefaults`), used when the check sets nothing. */
+    defaults?: {
+        failOn?: FailOn;
+    };
+}
+/**
+ * What a non-empty error bucket does to the run.
+ *
+ * Not exported, for the same reason as {@link Severity}: only this module names
+ * it, and `tsc` inlines it into `findings.d.ts` regardless.
+ */
+type FailOn = 'error' | 'warn' | 'never';
+/** The knobs a check reads straight out of its own block in pr-checkmate.json. */
+interface ClientFindingConfig {
+    ignore?: string[];
+    failOn?: FailOn;
+    severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
+}
+/**
+ * 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 declare function clientFindingOptions(ctx: CheckContext, cfg?: ClientFindingConfig): Pick<SeverityReportOptions, 'sampleLimit' | 'ignore' | 'failOn' | 'severityOverrides' | 'defaults'>;
+/**
+ * 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 declare function reportSeverityBuckets(errorsIn: FindingBucket, warningsIn: FindingBucket, opts: SeverityReportOptions): CheckOutcome;
+export {};