pr-checkmate 1.23.23 → 2.0.0

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

@@ -5,9 +5,13 @@ import { CheckContext, CheckOutcome } from '../types';
  * 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.
  */
-export type Severity = 'error' | 'warn';
-export interface SeverityEmitter {
+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. */
@@ -23,33 +27,156 @@ export interface SeverityEmitter {
 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>;
 /**
- * Strip a trailing line comment (`//` or `#`) from a line, tracking quote state
- * so a marker inside a string literal (or a `#` in `"#fff"`, a `//` in a quoted
- * URL) is preserved. Heuristic, not a tokenizer: block comments and regex
- * literals aren't handled. Used by code-targeting checks so `# print(x)` or
- * `// eval(x)` in a comment isn't flagged as real code.
+ * 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.
+ */
+export declare function reviewLines(ctx: CheckContext, globs: string[], onChunk: (stdout: string) => void): Promise<void>;
+/**
+ * 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';
+}
+/**
+ * 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 stripInlineComment(line: string): string;
+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[];
+}): SeverityBuckets;
 /** Total number of findings across all labels in a bucket. */
 export declare function bucketTotal(bucket: FindingBucket): number;
-interface LogOptions {
-    /** Log prefix, e.g. 'Diff Security'. */
+/**
+ * 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;
-    /** Use logger.error + ❌ instead of logger.warn + ⚠️. */
-    isError?: boolean;
-    /** Append ": N occurrence(s)" after the label (default true). */
-    showCount?: boolean;
-    /** Max samples printed per label; omit to print all. */
+    /** 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;
-}
-/** Log one bucket of findings using the shared check format. */
-export declare function logFindings(bucket: FindingBucket, opts: LogOptions): void;
+    /** 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;
@@ -67,10 +194,62 @@ interface SeverityReportOptions {
      * 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.
- * Returns pass() when both buckets are empty, otherwise warn() with a summary.
+ *
+ * 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 {};