pr-checkmate 2.1.0 → 3.0.0

package/dist/config/constants.d.ts

@@ -52,6 +52,12 @@ export declare const DIFF_SECURITY_IGNORE_DEFAULTS: string[];
  * committed reappears in it — 39 of 42 spellcheck findings in one real repository
  * came from that one file, none of them actionable: the text cannot be corrected
  * without rewriting git history, and the next release regenerates it anyway.
+ *
+ * Matched at ANY depth, not just at the repository root. The root-only form was
+ * the original, and it left every nested changelog unhandled: a component-config
+ * repository with one per component produced 157 of 157 spelling findings and 240
+ * of 246 markdown findings from files nobody writes by hand. A generated file is
+ * generated wherever it sits.
  */
 export declare const GENERATED_DOC_FILES: string[];
 /**
@@ -70,6 +76,13 @@ export declare const CONFIG_FILE_PATTERNS: string[];
  * config/CI YAML and JSON out of the report — they are data, not code, and their
  * repetition is not meaningful duplication. This mirrors the code-only file set the
  * check already uses when scanning a git diff, so full-tree and diff scans agree.
+ *
+ * One entry per language pr-checkmate detects, all of them verified against the
+ * jscpd binary rather than assumed: the list used to stop at C++ while the check
+ * only ever handed jscpd `.ts`/`.js` files, so the Go, Rust, C#, Ruby and PHP
+ * halves were unreachable and the Python one was decoration. Copy-paste is a
+ * language-independent smell, and the tokenizer behind this check has always been
+ * able to see it — the file list was the only thing in the way.
  */
 export declare const DUPLICATE_CODE_FORMATS: string[];
 /**
@@ -129,7 +142,6 @@ export declare const documentation: {
     prettier: string;
     cspell: string;
 };
-export declare const CONFIG_FILE: string;
 /**
  * Every top-level key PR CheckMate recognises in pr-checkmate.json — the union
  * of the `PRCheckMateConfig` interface fields and the keys the `init` generator

package/dist/config/constants.js

@@ -1,10 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_CONFIG_KEYS = exports.CONFIG_FILE = exports.documentation = exports.FULL_CONFIG_URL = exports.DOCS_URL = exports.DEFAULT_ALLOW_PACKAGES = exports.DEFAULT_COMMANDS = exports.SOURCE_EXTENSIONS = exports.DUPLICATE_CODE_FORMATS = exports.CONFIG_FILE_PATTERNS = exports.DEAD_CODE_IGNORE_DEFAULTS = exports.GENERATED_DOC_FILES = exports.DIFF_SECURITY_IGNORE_DEFAULTS = exports.DUPLICATE_IGNORE_DEFAULTS = exports.TEST_PATH_GLOBS = exports.IGNORE_PATTERNS = exports.IGNORED_DIRS = void 0;
-const node_path_1 = __importDefault(require("node:path"));
+exports.KNOWN_CONFIG_KEYS = exports.documentation = exports.FULL_CONFIG_URL = exports.DOCS_URL = exports.DEFAULT_ALLOW_PACKAGES = exports.DEFAULT_COMMANDS = exports.SOURCE_EXTENSIONS = exports.DUPLICATE_CODE_FORMATS = exports.CONFIG_FILE_PATTERNS = exports.DEAD_CODE_IGNORE_DEFAULTS = exports.GENERATED_DOC_FILES = exports.DIFF_SECURITY_IGNORE_DEFAULTS = exports.DUPLICATE_IGNORE_DEFAULTS = exports.TEST_PATH_GLOBS = exports.IGNORE_PATTERNS = exports.IGNORED_DIRS = void 0;
 /**
  * Build output, dependency, tooling, and report directories that are never
  * product code. Every check excludes them by directory-name segment match (see
@@ -156,8 +152,14 @@ exports.DIFF_SECURITY_IGNORE_DEFAULTS = [...exports.TEST_PATH_GLOBS];
  * committed reappears in it — 39 of 42 spellcheck findings in one real repository
  * came from that one file, none of them actionable: the text cannot be corrected
  * without rewriting git history, and the next release regenerates it anyway.
+ *
+ * Matched at ANY depth, not just at the repository root. The root-only form was
+ * the original, and it left every nested changelog unhandled: a component-config
+ * repository with one per component produced 157 of 157 spelling findings and 240
+ * of 246 markdown findings from files nobody writes by hand. A generated file is
+ * generated wherever it sits.
  */
-exports.GENERATED_DOC_FILES = ['CHANGELOG.md'];
+exports.GENERATED_DOC_FILES = ['**/CHANGELOG.md'];
 /**
  * Files excluded from the dead-code (unused-exports) report by default. These are
  * REGEX sources (matched against each reported file path), not globs — dead-code's
@@ -192,6 +194,13 @@ exports.CONFIG_FILE_PATTERNS = [
  * config/CI YAML and JSON out of the report — they are data, not code, and their
  * repetition is not meaningful duplication. This mirrors the code-only file set the
  * check already uses when scanning a git diff, so full-tree and diff scans agree.
+ *
+ * One entry per language pr-checkmate detects, all of them verified against the
+ * jscpd binary rather than assumed: the list used to stop at C++ while the check
+ * only ever handed jscpd `.ts`/`.js` files, so the Go, Rust, C#, Ruby and PHP
+ * halves were unreachable and the Python one was decoration. Copy-paste is a
+ * language-independent smell, and the tokenizer behind this check has always been
+ * able to see it — the file list was the only thing in the way.
  */
 exports.DUPLICATE_CODE_FORMATS = [
     'javascript',
@@ -203,6 +212,11 @@ exports.DUPLICATE_CODE_FORMATS = [
     'swift',
     'c',
     'cpp',
+    'csharp',
+    'go',
+    'php',
+    'ruby',
+    'rust',
 ];
 /**
  * File extensions to check
@@ -267,7 +281,6 @@ exports.documentation = {
     prettier: 'https://prettier.io/docs/en/options.html',
     cspell: 'https://cspell.org/configuration/',
 };
-exports.CONFIG_FILE = node_path_1.default.resolve(process.cwd(), 'pr-checkmate.json');
 /**
  * Every top-level key PR CheckMate recognises in pr-checkmate.json — the union
  * of the `PRCheckMateConfig` interface fields and the keys the `init` generator

package/dist/config/index.d.ts

@@ -1,23 +1,35 @@
 export * from './constants';
 export { loadProjectConfig } from '../config/loader';
 /**
- * Get the configured source path(s) dynamically as a normalized list.
- * Accepts a single string or an array in pr-checkmate.json; empty/invalid
- * values fall back to `['.']` (the whole repo). Clients narrow scanning to a
- * subdirectory by setting `sourcePath` in their pr-checkmate.json. Always reads
- * fresh config.
+ * The configured source path(s), normalised to a list.
+ *
+ * Accepts a string or an array; empty and invalid values fall back to `['.']`,
+ * the whole repository. Clients narrow scanning to a subdirectory by setting
+ * `sourcePath`.
+ *
+ * `cwd` is a parameter rather than `process.cwd()` baked in, and that is the
+ * whole of ticket 074. This used to read a `CONFIG_FILE` constant resolved at
+ * *module load*, so the answer was fixed to whatever directory the process
+ * started in — `chdir` could not change it and neither could a caller. For the
+ * CLI that is harmless, since its working directory never moves; for
+ * `runChecks({ cwd })` it meant the SDK consumer's own `sourcePath` was applied
+ * to somebody else's repository, silently scoping every scoped check to a
+ * directory that may not exist there.
+ *
+ * It also read the file itself, duplicating `loadProjectConfig` with its own
+ * defaults. One reader is now the only reader.
  */
-export declare function getSourcePaths(): string[];
+export declare function getSourcePaths(cwd?: string): string[];
 /**
- * Get a single source path (first configured entry) for callers that only
- * support one directory. Prefer `getSourcePaths()` for scan targets.
+ * The first configured source path, for callers that only support one directory.
+ * Prefer {@link getSourcePaths} for scan targets.
  */
-export declare function getSourcePath(): string;
+export declare function getSourcePath(cwd?: string): string;
 /**
  * Get the effective list of directory names excluded from every check
  * (client `ignoreDirs` in pr-checkmate.json, or the curated default).
  */
-export declare function getIgnoredDirs(): string[];
+export declare function getIgnoredDirs(cwd?: string): string[];
 /**
  * Get path to package config files
  */
@@ -25,4 +37,4 @@ export declare function getPackageConfigPath(fileName: string): string;
 /**
  * Check if project has local config
  */
-export declare function hasLocalConfig(configNames: string[]): boolean;
+export declare function hasLocalConfig(configNames: string[], cwd?: string): boolean;

package/dist/config/index.js

@@ -26,51 +26,46 @@ exports.hasLocalConfig = hasLocalConfig;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const loader_1 = require("../config/loader");
-const utils_1 = require("../utils");
-const constants_1 = require("./constants");
 __exportStar(require("./constants"), exports);
 var loader_2 = require("../config/loader");
 Object.defineProperty(exports, "loadProjectConfig", { enumerable: true, get: function () { return loader_2.loadProjectConfig; } });
 /**
- * Load configuration dynamically (always reads fresh config)
+ * The configured source path(s), normalised to a list.
+ *
+ * Accepts a string or an array; empty and invalid values fall back to `['.']`,
+ * the whole repository. Clients narrow scanning to a subdirectory by setting
+ * `sourcePath`.
+ *
+ * `cwd` is a parameter rather than `process.cwd()` baked in, and that is the
+ * whole of ticket 074. This used to read a `CONFIG_FILE` constant resolved at
+ * *module load*, so the answer was fixed to whatever directory the process
+ * started in — `chdir` could not change it and neither could a caller. For the
+ * CLI that is harmless, since its working directory never moves; for
+ * `runChecks({ cwd })` it meant the SDK consumer's own `sourcePath` was applied
+ * to somebody else's repository, silently scoping every scoped check to a
+ * directory that may not exist there.
+ *
+ * It also read the file itself, duplicating `loadProjectConfig` with its own
+ * defaults. One reader is now the only reader.
  */
-function loadConfig() {
-    try {
-        if (node_fs_1.default.existsSync(constants_1.CONFIG_FILE)) {
-            const configContent = node_fs_1.default.readFileSync(constants_1.CONFIG_FILE, 'utf-8');
-            return JSON.parse(configContent);
-        }
-    }
-    catch (err) {
-        utils_1.logger.warn(`⚠️ Failed to read config from ${constants_1.CONFIG_FILE}, using defaults${err}`);
-    }
-    return { sourcePath: '.' };
-}
-/**
- * Get the configured source path(s) dynamically as a normalized list.
- * Accepts a single string or an array in pr-checkmate.json; empty/invalid
- * values fall back to `['.']` (the whole repo). Clients narrow scanning to a
- * subdirectory by setting `sourcePath` in their pr-checkmate.json. Always reads
- * fresh config.
- */
-function getSourcePaths() {
-    const { sourcePath } = loadConfig();
+function getSourcePaths(cwd = process.cwd()) {
+    const { sourcePath } = (0, loader_1.loadProjectConfig)(cwd);
     const paths = (Array.isArray(sourcePath) ? sourcePath : [sourcePath]).filter((p) => typeof p === 'string' && p.trim().length > 0);
     return paths.length > 0 ? paths : ['.'];
 }
 /**
- * Get a single source path (first configured entry) for callers that only
- * support one directory. Prefer `getSourcePaths()` for scan targets.
+ * The first configured source path, for callers that only support one directory.
+ * Prefer {@link getSourcePaths} for scan targets.
  */
-function getSourcePath() {
-    return getSourcePaths()[0];
+function getSourcePath(cwd) {
+    return getSourcePaths(cwd)[0];
 }
 /**
  * Get the effective list of directory names excluded from every check
  * (client `ignoreDirs` in pr-checkmate.json, or the curated default).
  */
-function getIgnoredDirs() {
-    return (0, loader_1.loadProjectConfig)().ignoreDirs ?? [];
+function getIgnoredDirs(cwd) {
+    return (0, loader_1.loadProjectConfig)(cwd).ignoreDirs ?? [];
 }
 /**
  * Get path to package config files
@@ -82,7 +77,6 @@ function getPackageConfigPath(fileName) {
 /**
  * Check if project has local config
  */
-function hasLocalConfig(configNames) {
-    const projectRoot = process.cwd();
-    return configNames.some(name => node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, name)));
+function hasLocalConfig(configNames, cwd = process.cwd()) {
+    return configNames.some(name => node_fs_1.default.existsSync(node_path_1.default.join(cwd, name)));
 }

package/dist/core/checks/dependencies/banned-imports.js

@@ -39,7 +39,7 @@ exports.bannedImportsCheck = {
         try {
             const errors = {};
             const warnings = {};
-            await (0, findings_1.reviewLines)(ctx, ['*'], stdout => {
+            const reviewed = await (0, findings_1.reviewLines)(ctx, ['*'], stdout => {
                 var _a;
                 for (const raw of stdout.split('\n')) {
                     if (!raw.startsWith('+') || raw.startsWith('+++'))
@@ -53,6 +53,9 @@ exports.bannedImportsCheck = {
                     }
                 }
             });
+            // An unreadable file list is not "no banned imports" (ticket 072).
+            if (!reviewed)
+                return (0, types_1.skip)('git unavailable');
             // A ban configured as "error" blocks the run, regardless of phase — that
             // is the default `failOn`, and the client can still relax it per repo.
             return (0, findings_1.reportSeverityBuckets)(errors, warnings, {

package/dist/core/checks/dependencies/circular-deps.js

@@ -9,6 +9,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("../../../config");
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
+const reuse_1 = require("../../install/reuse");
 const targets_1 = require("../../targets");
 const types_1 = require("../../types");
 const findings_1 = require("../findings");
@@ -36,8 +37,10 @@ const SOURCE_GLOBS = ['*.ts', '*.tsx', '*.js', '*.jsx'];
  * dpdm from the registry on first use — and when that fetch could not happen
  * (offline or locked-down CI, private registry, exit 127) nothing was analyzed.
  */
-function resolveDpdm(cwd) {
-    for (const options of [{ paths: [cwd] }, undefined]) {
+function resolveDpdm(ctx) {
+    // No configuration of its own — dpdm reads the module graph — so the version
+    // check is the right question here and `clientOwnsConfig` stays off.
+    for (const options of [{ paths: (0, reuse_1.clientToolPaths)('dpdm', ctx) }, undefined]) {
         try {
             return (0, utils_1.resolvePackageBin)('dpdm', 'lib/bin/dpdm.js', options);
         }
@@ -80,7 +83,13 @@ exports.circularDepsCheck = {
         return ctx.languages.includes('typescript') || ctx.languages.includes('javascript');
     },
     async run(ctx) {
-        const allFiles = await (0, targets_1.listTrackedFiles)(ctx, SOURCE_GLOBS, (0, config_1.getSourcePaths)());
+        const allFiles = await (0, targets_1.listTrackedFiles)(ctx, SOURCE_GLOBS, (0, config_1.getSourcePaths)(ctx.cwd));
+        // A cycle detector needs the WHOLE graph, so an unreadable file list is the
+        // one case where passing would be worst: half a graph produces confident
+        // nonsense, and no graph reported as `pass` says the repository is acyclic
+        // when nobody looked (ticket 072).
+        if (allFiles === null)
+            return (0, types_1.skip)('git unavailable');
         if (allFiles.length === 0)
             return (0, types_1.pass)();
         // Files the client exempted (generated code, vendored bundles) are dropped
@@ -90,7 +99,7 @@ exports.circularDepsCheck = {
         const files = ignore.length > 0 ? allFiles.filter(f => !(0, utils_1.matchesAnyGlob)(f, ignore)) : allFiles;
         if (files.length === 0)
             return (0, types_1.skip)('all files ignored');
-        const dpdmBin = resolveDpdm(ctx.cwd);
+        const dpdmBin = resolveDpdm(ctx);
         if (!dpdmBin) {
             utils_1.logger.warn('[Circular Deps]: ⚠️ dpdm could not be resolved — skipping');
             return (0, types_1.skip)('dpdm unavailable');
@@ -114,7 +123,7 @@ exports.circularDepsCheck = {
                 'circular:1',
                 '-o',
                 reportPath,
-                ...toFileArgs(files, (0, config_1.getSourcePaths)()),
+                ...toFileArgs(files, (0, config_1.getSourcePaths)(ctx.cwd)),
             ], { cwd: ctx.cwd, reject: false, timeout });
             if (result.timedOut) {
                 utils_1.logger.warn(`[Circular Deps]: ⚠️ dpdm timed out after ${timeout}ms — skipping`);

package/dist/core/checks/dependencies/dependency-check.js

@@ -106,7 +106,7 @@ exports.dependencyCheck = {
     applies(ctx) {
         if (ctx.config.dependency?.enabled === false)
             return false;
-        return node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, 'package.json'));
+        return (0, types_1.isNpmProject)(ctx);
     },
     async run(ctx) {
         // Resolve the bundled knip binary and run it via the current node — never
@@ -122,7 +122,7 @@ exports.dependencyCheck = {
         // from a config file only, so they go into a temp one — but a client's own knip
         // config wins outright, exactly as it does for cspell.
         const ignore = ctx.config.dependency?.ignore ?? [];
-        const clientOwnsConfig = (0, config_1.hasLocalConfig)(KNIP_CONFIG_FILES) || hasPackageJsonConfig(ctx.cwd);
+        const clientOwnsConfig = (0, config_1.hasLocalConfig)(KNIP_CONFIG_FILES, ctx.cwd) || hasPackageJsonConfig(ctx.cwd);
         let tempConfigPath = null;
         if (ignore.length > 0 && clientOwnsConfig) {
             // Say so out loud: a silently ignored `ignore` list looks like a broken check.

package/dist/core/checks/dependencies/grype-scan.js

@@ -4,6 +4,7 @@ exports.grypeScanCheck = void 0;
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
 const types_1 = require("../../types");
+const tool_install_1 = require("../tool-install");
 const SEVERITY_ORDER = ['negligible', 'low', 'medium', 'high', 'critical'];
 /** grype artifact `type` → the ecosystem we can resolve direct deps for. */
 const TYPE_TO_ECOSYSTEM = {
@@ -69,7 +70,7 @@ exports.grypeScanCheck = {
         // execa v9 with reject:false resolves (not throws) with `code: 'ENOENT'`
         // when the binary is absent — detect the missing scanner on the result.
         if (result.code === 'ENOENT')
-            return (0, types_1.skip)('grype not installed');
+            return (0, tool_install_1.notInstalled)('grype');
         if (result.timedOut) {
             utils_1.logger.warn(`[Grype Scan]: ⚠️ grype timed out after ${timeout}ms — skipping`);
             return (0, types_1.skip)('grype timed out');

package/dist/core/checks/dependencies/license-check.js

@@ -1,11 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.licenseCheck = void 0;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
 const types_1 = require("../../types");
@@ -19,7 +14,7 @@ exports.licenseCheck = {
     name: 'License Check',
     phase: 'blocking',
     applies(ctx) {
-        return node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, 'package.json'));
+        return (0, types_1.isNpmProject)(ctx);
     },
     async run(ctx) {
         const allowPackages = new Set(ctx.config.licenseCheck?.allowPackages ?? []);

package/dist/core/checks/dependencies/npm-audit.js

@@ -34,7 +34,7 @@ exports.npmAuditCheck = {
     applies(ctx) {
         if (ctx.config.security?.['npm-audit']?.enabled === false)
             return false;
-        return node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, 'package.json'));
+        return (0, types_1.isNpmProject)(ctx);
     },
     async run(ctx) {
         // `high`, not `moderate`. A moderate CVE in a direct dependency often has no

package/dist/core/checks/dependencies/outdated-deps.js

@@ -1,11 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.outdatedDepsCheck = void 0;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
 const types_1 = require("../../types");
@@ -16,7 +11,7 @@ exports.outdatedDepsCheck = {
     applies(ctx) {
         if (ctx.config.outdatedDeps?.enabled === false)
             return false;
-        return node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, 'package.json'));
+        return (0, types_1.isNpmProject)(ctx);
     },
     async run(ctx) {
         // `npm outdated` queries the registry for every dependency and can take a

package/dist/core/checks/dependencies/vuln-scan.js

@@ -4,6 +4,7 @@ exports.vulnScanCheck = void 0;
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
 const types_1 = require("../../types");
+const tool_install_1 = require("../tool-install");
 /**
  * Cross-language dependency vulnerability scan via osv-scanner, which reads
  * lockfiles across ecosystems (npm, PyPI, Go, crates, Maven, …) against the OSV
@@ -33,7 +34,7 @@ exports.vulnScanCheck = {
         // execa v9 with reject:false resolves (not throws) with `code: 'ENOENT'`
         // when the binary is absent — detect the missing scanner on the result.
         if (result.code === 'ENOENT')
-            return (0, types_1.skip)('osv-scanner not installed');
+            return (0, tool_install_1.notInstalled)('osv-scanner');
         if (result.timedOut) {
             utils_1.logger.warn(`[Vuln Scan]: ⚠️ osv-scanner timed out after ${timeout}ms — skipping`);
             return (0, types_1.skip)('osv-scanner timed out');

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

@@ -74,8 +74,15 @@ export declare function scanTrackedFiles(ctx: CheckContext, files: string[], onF
  *
  * `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<void>;
+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
@@ -129,6 +136,17 @@ export interface DiffPattern {
      */
     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
@@ -150,8 +168,34 @@ export declare function scanDiffPatterns(stdout: string, patterns: readonly Diff
     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;
-/** Total number of findings across all labels in a bucket. */
+/**
+ * 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