pr-checkmate 2.1.2 → 3.0.0

package/dist/core/registry.js

@@ -18,21 +18,13 @@ const merge_conflict_1 = require("./checks/git/merge-conflict");
 const missing_tests_1 = require("./checks/git/missing-tests");
 const todo_fixme_1 = require("./checks/git/todo-fixme");
 const cpp_format_1 = require("./checks/languages/cpp-format");
-const csharp_format_1 = require("./checks/languages/csharp-format");
+const external_checks_1 = require("./checks/languages/external-checks");
 const go_format_1 = require("./checks/languages/go-format");
-const go_lint_1 = require("./checks/languages/go-lint");
-const kotlin_lint_1 = require("./checks/languages/kotlin-lint");
 const lint_1 = require("./checks/languages/lint");
-const php_format_1 = require("./checks/languages/php-format");
 const prettier_1 = require("./checks/languages/prettier");
 const python_format_1 = require("./checks/languages/python-format");
 const python_lint_1 = require("./checks/languages/python-lint");
 const python_typecheck_1 = require("./checks/languages/python-typecheck");
-const ruby_lint_1 = require("./checks/languages/ruby-lint");
-const rust_format_1 = require("./checks/languages/rust-format");
-const rust_lint_1 = require("./checks/languages/rust-lint");
-const shellcheck_1 = require("./checks/languages/shellcheck");
-const swift_lint_1 = require("./checks/languages/swift-lint");
 const typecheck_1 = require("./checks/languages/typecheck");
 const commitlint_1 = require("./checks/pr/commitlint");
 const pr_body_1 = require("./checks/pr/pr-body");
@@ -101,18 +93,18 @@ exports.REGISTRY = [
     python_lint_1.pythonLintCheck,
     python_typecheck_1.pythonTypecheckCheck,
     dead_code_1.deadCodeCheck,
-    swift_lint_1.swiftLintCheck,
-    kotlin_lint_1.kotlinLintCheck,
-    go_lint_1.goLintCheck,
-    rust_lint_1.rustLintCheck,
-    ruby_lint_1.rubyLintCheck,
-    shellcheck_1.shellcheckCheck,
+    external_checks_1.swiftLintCheck,
+    external_checks_1.kotlinLintCheck,
+    external_checks_1.goLintCheck,
+    external_checks_1.rustLintCheck,
+    external_checks_1.rubyLintCheck,
+    external_checks_1.shellcheckCheck,
     // format
     prettier_1.prettierCheck,
     cpp_format_1.cppFormatCheck,
     python_format_1.pythonFormatCheck,
     go_format_1.goFormatCheck,
-    rust_format_1.rustFormatCheck,
-    csharp_format_1.csharpFormatCheck,
-    php_format_1.phpFormatCheck,
+    external_checks_1.rustFormatCheck,
+    external_checks_1.csharpFormatCheck,
+    external_checks_1.phpFormatCheck,
 ];

package/dist/core/run-checks.js

@@ -4,9 +4,12 @@ exports.applySeverity = applySeverity;
 exports.shouldReportDiffSkip = shouldReportDiffSkip;
 exports.runChecks = runChecks;
 const utils_1 = require("../utils");
+const package_version_1 = require("../utils/package-version");
 const pool_1 = require("../utils/pool");
+const resolve_bin_1 = require("../utils/resolve-bin");
 const result_collector_1 = require("../utils/result-collector");
 const context_1 = require("./context");
+const prepare_1 = require("./install/prepare");
 const registry_1 = require("./registry");
 const reporters_1 = require("./reporters");
 const types_1 = require("./types");
@@ -107,13 +110,27 @@ function noDiffReason(ctx) {
         return `no diff range (${scope.reason}) — set fetch-depth: 0`;
     return 'full scan — this check reviews a diff';
 }
+/**
+ * Whether a skip came from the missing diff range, as opposed to any other reason
+ * a check can decline to run.
+ *
+ * `reportDegradedScope` counts these to say how much coverage a fallback to a full
+ * scan cost. It used to count every skip in the report, which already included
+ * unrelated ones ("mypy not installed"), and tooling skips would have added more —
+ * turning a number that means "checks you lost to a shallow clone" into "skips,
+ * roughly". Matched on the phrasing {@link noDiffReason} produces, which is the
+ * only thing that distinguishes them once a skip is just a status and a string.
+ */
+function isDiffSkip(details) {
+    return Boolean(details && /^no diff range|^full scan — this check reviews a diff/.test(details));
+}
 /**
  * Run one check: gate on `applies`, execute, translate throws into `fail`.
  *
  * `heavy` admits only a couple of expensive checks at a time, and the per-check
  * timeout means one that never returns costs a warning rather than the run.
  */
-async function runOne(check, ctx, collector, heavy) {
+async function runOne(check, ctx, collector, heavy, tooling) {
     try {
         // A diff-only check without a range is usually a hole in coverage rather
         // than an irrelevance, so it is reported as a skip and the gap stays visible
@@ -141,6 +158,20 @@ async function runOne(check, ctx, collector, heavy) {
             // from run() (e.g. "no relevant files changed") are still reported.
             return;
         }
+        // Tooling is checked AFTER `applies`, so the row only appears for a check
+        // that would otherwise have run. A Ruff row in a TypeScript repository would
+        // be noise; a Ruff row in a Python repository whose toolchain never arrived
+        // is the whole point — ticket 057, applied to tooling instead of diffs.
+        const missing = tooling.unavailable.get(check.name);
+        if (missing) {
+            // Severity still has the last word, as it does for every other outcome: a
+            // client who made this check advisory does not get a hard failure out of
+            // `onMissingTool: "error"`, and one who promoted it does.
+            const status = applySeverity(check.name, tooling.fatal ? 'fail' : 'skip', ctx);
+            utils_1.logger.warn(`[runChecks]: ${status === 'fail' ? '❌' : '⏭️'} ${check.name}: ${missing}`);
+            collector.register(check.name, status, `tooling unavailable — ${missing}`);
+            return;
+        }
         const started = Date.now();
         const timeoutMs = ctx.config.run?.checkTimeoutMs ?? 300000;
         const execute = () => (0, pool_1.withTimeout)(check.run(ctx), timeoutMs, () => {
@@ -180,12 +211,16 @@ async function runChecks(opts = {}) {
     // the list from here rather than importing the registry, which would make
     // registry → check → registry a cycle.
     ctx.checkNames = resolveChecks(opts).map(c => c.name);
+    // Before any check starts: make sure the tools they need are reachable, and
+    // learn which ones are not. Doing this per-check would fetch the same profile
+    // from several checks at once and leave each of them guessing on failure.
+    const tooling = await prepareToolingFor(ctx, selected);
     const limit = (0, pool_1.resolveConcurrency)(ctx.config.run?.concurrency);
     const heavyLimit = Math.max(1, ctx.config.run?.heavyConcurrency ?? 1);
     const heavy = new pool_1.Semaphore(heavyLimit);
     for (const phase of types_1.PHASES) {
         const inPhase = selected.filter(c => c.phase === phase);
-        await (0, pool_1.runPool)(inPhase.map(c => () => runOne(c, ctx, collector, heavy)), limit);
+        await (0, pool_1.runPool)(inPhase.map(c => () => runOne(c, ctx, collector, heavy, tooling)), limit);
     }
     reportDegradedScope(ctx, collector);
     const build = () => {
@@ -204,6 +239,40 @@ async function runChecks(opts = {}) {
     }
     return result;
 }
+/**
+ * Prepare the tooling the selected checks need, or explain what is missing.
+ *
+ * Separate from `prepareTooling` itself so the failure of the *preparation* is
+ * never the failure of the *run*: fetching tooling is best-effort by nature —
+ * offline runners, read-only caches, a registry having a bad day — and a throw
+ * here would take down a run that could still have done most of its job. The
+ * checks that needed the tooling report it themselves, one row each.
+ *
+ * `install.strategy: "manual"` and a caller that supplied its own checks both
+ * arrive here; neither is special-cased, because a profile whose packages ship
+ * with us needs no preparation either way and the loop exits having done nothing.
+ */
+async function prepareToolingFor(ctx, selected) {
+    try {
+        return await (0, prepare_1.prepareTooling)({
+            cwd: ctx.cwd,
+            config: ctx.config,
+            // A hand-built context (the SDK, a test) carries no counts. Treating its
+            // languages as real rather than marker-only is the honest reading: a caller
+            // that names a language is asserting it, not guessing.
+            usage: ctx.usage ?? ctx.languages.map(lang => ({ lang, files: 1, marker: true })),
+            selected: selected.map(c => c.name),
+            version: (0, package_version_1.packageVersion)(),
+        });
+    }
+    catch (err) {
+        utils_1.logger.warn(`[install]: ⚠️ could not prepare tooling: ${errMessage(err)}`);
+        // Preparation may have registered roots before it threw. Leaving them behind
+        // would point resolution at a half-installed directory for the whole run.
+        (0, resolve_bin_1.clearToolPaths)();
+        return (0, prepare_1.noTooling)();
+    }
+}
 /**
  * Surface a scope that silently narrowed the run.
  *
@@ -220,7 +289,9 @@ function reportDegradedScope(ctx, collector) {
     const mode = ctx.config.run?.onDegradedScope ?? 'warn';
     if (mode === 'off' || !ctx.scope?.degraded || !(0, utils_1.isCiEnvironment)())
         return;
-    const dropped = collector.getResults().filter(r => r.status === 'skip').length;
+    const dropped = collector
+        .getResults()
+        .filter(r => r.status === 'skip' && isDiffSkip(r.details)).length;
     const detail = `${ctx.scope.reason}; ${dropped} diff-only check(s) did not run — set fetch-depth: 0`;
     utils_1.logger.error(`[runChecks]: ${mode === 'error' ? '❌' : '⚠️'} Degraded scope: ${detail}`);
     collector.register('Scan Scope', mode === 'error' ? 'fail' : 'warn', detail);

package/dist/core/targets.d.ts

@@ -1,4 +1,31 @@
-import type { CheckContext } from './types';
+import { type CheckContext, type CheckOutcome } from './types';
+/**
+ * Drop files that live under any excluded directory (client `ignoreDirs` or the
+ * curated default), matched on any path segment so nesting depth doesn't matter.
+ * Applied to every check's file list so build/tooling/report dirs are never
+ * scanned, even when committed.
+ *
+ * `keepDirs` un-ignores specific segments for a single check — e.g. YAML lint
+ * keeps the CI dirs (`.github`, `.gitlab`, `.circleci`), which are ignored
+ * globally but hold the workflow files a YAML linter most needs to see.
+ */
+/**
+ * Drop files the client excluded by path.
+ *
+ * Separate from `ignoreDirs`, which matches a directory *name* on any segment:
+ * that cannot express "this one file" and cannot express "this one path" —
+ * `ignoreDirs: ["generated"]` silences every `generated/` in the repository, not
+ * the one that is actually generated. Globs answer both, and because this sits
+ * in the one function every file-scanning check calls, a client writes the rule
+ * once instead of hunting for the right key on each check.
+ *
+ * Exported because three checks build their file list themselves and cannot go
+ * through the resolvers above — and `excludePaths` is documented as "the only
+ * exclusion that reaches every check", which was not true of them (ticket 080).
+ * Each has a real reason to skip `sourcePath` and `ignoreDirs`; none has one to
+ * ignore a client saying "do not look here".
+ */
+export declare function excludeClientPaths(files: string[], cwd: string): string[];
 /**
  * Lists the files a language check should operate on, matched by pathspec `globs`
  * (e.g. `['*.py']`). Uses the PR diff range when available (delta mode), else
@@ -20,10 +47,94 @@ export declare function resolveTargetFiles(ctx: CheckContext, globs: string[], o
  * fallback while gaining delta support on every platform via `ctx.baseSha`.
  */
 export declare function resolveScopedTargetFiles(ctx: CheckContext, globs: string[], sourcePaths: string[]): Promise<string[] | null>;
+/**
+ * The files to work on, or the outcome to return instead of working.
+ *
+ * One value rather than two, because the two-value shape is what kept going
+ * wrong. Every file-scanning check ends up writing the same triple —
+ *
+ * ```typescript
+ * const targets = await resolveTargetFiles(ctx, globs);
+ * if (targets === null) return skip('git unavailable');
+ * if (targets.length === 0) return pass('no Kotlin files changed');
+ * ```
+ *
+ * — and it was written out seventeen times, with nineteen exact copies of the
+ * middle line and seven copies of the comment explaining why the two cases are
+ * not the same (ticket 079). The point of collapsing it is not the four lines. It
+ * is that `null` means "git could not tell us" and `[]` means "git did and there
+ * is nothing", they are opposite answers, and a check that conflates them reports
+ * a clean pass over a tree it never opened — which is ticket 072, and before that
+ * ticket 067, and both were found in security checks, where it cost the most.
+ *
+ * Written this way round — an array or an outcome, not a nullable array — so the
+ * caller's one line is `if (!Array.isArray(targets)) return targets;` and there
+ * is no second case left to forget.
+ *
+ * Not exported: it is the return type of {@link resolveTargets} and every caller
+ * gets it by inference, so exporting it would only widen the public surface and
+ * show up as an unused export in our own Dead Code check.
+ */
+type TargetsOrOutcome = string[] | CheckOutcome;
+/** How a check wants an empty file list phrased, and at which status. */
+type EmptyResult = {
+    pass: string;
+} | {
+    skip: string;
+};
+/** Options for {@link resolveTargets} beyond the globs themselves. */
+interface ResolveOptions {
+    /**
+     * What no matching files means to this check, and in what words.
+     *
+     * Not defaulted, and that is deliberate: the two halves of the corpus disagree.
+     * A language check has genuinely nothing to do when its language is not in the
+     * diff, so `{ pass: 'no Kotlin files changed' }`. A whole-tree check that finds
+     * no files at all has not reviewed the repository, so `{ skip: 'no tracked
+     * files' }`. Picking one for the caller would make half of them wrong.
+     */
+    onEmpty: EmptyResult;
+    /** Walk every tracked file instead of the PR diff range. */
+    wholeTree?: boolean;
+    /** Restrict the result to the configured `sourcePath`(s). */
+    scoped?: boolean;
+    /** Un-ignore specific directory segments, as in {@link resolveTargetFiles}. */
+    keepDirs?: string[];
+}
+/**
+ * Resolve a check's file list, or the outcome it should report instead.
+ *
+ * The one entry point for checks that operate on whole files. It wraps
+ * {@link resolveTargetFiles} and {@link listTrackedFiles} rather than replacing
+ * them — a check that needs the raw list (because it distinguishes the two cases
+ * itself, or scans in several passes) still calls those directly.
+ */
+export declare function resolveTargets(ctx: CheckContext, globs: string[], opts: ResolveOptions): Promise<TargetsOrOutcome>;
 /**
  * List ALL tracked files matching `globs` (never delta), scoped to
- * `sourcePath`(s). For whole-repo analyses like circular-dependency detection
- * that need the full graph, not just the PR diff. Using `git ls-files` means
- * untracked `node_modules` is excluded by construction.
+ * `sourcePath`(s).
+ *
+ * For whole-repo analyses like circular-dependency detection that need the full
+ * graph, not just the PR diff. Using `git ls-files` means untracked
+ * `node_modules` is excluded by construction.
+ *
+ * `keepDirs` un-ignores segments for one caller, exactly as in
+ * {@link resolveTargetFiles}. It was missing here, and that made Workflow
+ * Security blind on the whole-tree path: `.github` is in the default ignore list,
+ * so `git ls-files .github/workflows/*.yml` returned the workflow and this
+ * function then dropped it. A blocking security check reported a clean pass over
+ * files it had never been handed — the surviving half of ticket 067, found by
+ * level 1 of the release regression plan.
+ *
+ * `null` when git could not answer, `[]` when it answered "nothing". The two are
+ * opposites to a caller and used to be the same value: `reject: false` keeps a
+ * failed git out of the catch below, so a directory git cannot read returned an
+ * empty list, and every caller read that as "nothing to review" and passed. On a
+ * directory holding real code that produced three green rows — Diff Security,
+ * Workflow Security, Diff Smells — over files none of them had opened
+ * (ticket 072).
  */
-export declare function listTrackedFiles(ctx: CheckContext, globs: string[], sourcePaths: string[]): Promise<string[]>;
+export declare function listTrackedFiles(ctx: CheckContext, globs: string[], sourcePaths: string[], opts?: {
+    keepDirs?: string[];
+}): Promise<string[] | null>;
+export {};

package/dist/core/targets.js

@@ -3,8 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.excludeClientPaths = excludeClientPaths;
 exports.resolveTargetFiles = resolveTargetFiles;
 exports.resolveScopedTargetFiles = resolveScopedTargetFiles;
+exports.resolveTargets = resolveTargets;
 exports.listTrackedFiles = listTrackedFiles;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -12,6 +14,7 @@ const config_1 = require("../config");
 const loader_1 = require("../config/loader");
 const utils_1 = require("../utils");
 const execa_1 = require("../utils/execa");
+const types_1 = require("./types");
 /**
  * Drop files that live under any excluded directory (client `ignoreDirs` or the
  * curated default), matched on any path segment so nesting depth doesn't matter.
@@ -31,11 +34,17 @@ const execa_1 = require("../utils/execa");
  * the one that is actually generated. Globs answer both, and because this sits
  * in the one function every file-scanning check calls, a client writes the rule
  * once instead of hunting for the right key on each check.
+ *
+ * Exported because three checks build their file list themselves and cannot go
+ * through the resolvers above — and `excludePaths` is documented as "the only
+ * exclusion that reaches every check", which was not true of them (ticket 080).
+ * Each has a real reason to skip `sourcePath` and `ignoreDirs`; none has one to
+ * ignore a client saying "do not look here".
  */
-function excludeConfiguredPaths(files) {
+function excludeClientPaths(files, cwd) {
     let patterns = [];
     try {
-        patterns = (0, loader_1.loadProjectConfig)().excludePaths ?? [];
+        patterns = (0, loader_1.loadProjectConfig)(cwd).excludePaths ?? [];
     }
     catch {
         // A config that cannot be read is the loader's problem to report, not a
@@ -43,8 +52,8 @@ function excludeConfiguredPaths(files) {
     }
     return patterns.length > 0 ? files.filter(f => !(0, utils_1.matchesAnyGlob)(f, patterns)) : files;
 }
-function excludeIgnoredDirs(files, keepDirs = []) {
-    const ignored = new Set((0, config_1.getIgnoredDirs)());
+function excludeIgnoredDirs(files, cwd, keepDirs = []) {
+    const ignored = new Set((0, config_1.getIgnoredDirs)(cwd));
     for (const dir of keepDirs)
         ignored.delete(dir);
     if (ignored.size === 0)
@@ -78,15 +87,45 @@ async function resolveTargetFiles(ctx, globs, opts = {}) {
             : ['ls-files', ...globs];
         const cacheKey = `t:${args.join('
')}`;
         let stdout = ctx.cache?.get(cacheKey);
+        const fromCache = stdout !== undefined;
         if (stdout === undefined) {
-            stdout = (await (0, execa_1.execa)('git', args, { cwd: ctx.cwd, reject: false })).stdout;
+            // `reject: false` keeps a failed git out of the catch below, so the exit
+            // code is the only thing separating "git could not answer" from "nothing
+            // matched". They are opposites to the caller: every caller turns `null`
+            // into a skip with a reason and `[]` into a clean pass. Without this
+            // branch a directory git cannot read produced the second — seven checks
+            // reporting ✅ over code none of them had looked at, while the docstring
+            // above had promised `null` all along. Found by ticket 062's corpus.
+            //
+            // A pathspec that matches nothing still exits 0, so the ordinary empty
+            // result cannot be swallowed here.
+            const result = await (0, execa_1.execa)('git', args, { cwd: ctx.cwd, reject: false });
+            if (result.exitCode !== 0) {
+                utils_1.logger.warn(`[targets]: ⚠️ git could not list files (exit ${result.exitCode})`);
+                return null;
+            }
+            stdout = result.stdout;
             ctx.cache?.set(cacheKey, stdout);
         }
-        const files = excludeConfiguredPaths(excludeIgnoredDirs(stdout
+        const files = excludeClientPaths(excludeIgnoredDirs(stdout
             .split('\n')
             .map(f => f.trim())
-            .filter(Boolean), opts.keepDirs)).filter(f => node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, f)));
-        utils_1.logger.info(`[targets]: ${ctx.baseSha ? '📂 Delta' : 'Full scan'}: ${files.length} file(s) for ${globs.join(', ')}`);
+            .filter(Boolean), ctx.cwd, opts.keepDirs), ctx.cwd).filter(f => node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, f)));
+        // One line per actual git call, not per consumer. Several checks ask for the
+        // same globs in a run and were each answered from the cache, but the line was
+        // printed after the cache branch — so four checks sharing one lookup printed
+        // four identical `Delta: 1 file(s) for *` lines and the log implied four walks
+        // of the tree.
+        //
+        // Demoted rather than dropped on a cache hit: the count is computed AFTER
+        // filtering, and two callers with the same globs but different `keepDirs` get
+        // different lists from the same cached output. Losing the second line would
+        // hide a real difference, so it moves to `debug` instead of disappearing.
+        const line = `[targets]: ${ctx.baseSha ? '📂 Delta' : 'Full scan'}: ${files.length} file(s) for ${globs.join(', ')}`;
+        if (fromCache)
+            utils_1.logger.debug(`${line} (cached)`);
+        else
+            utils_1.logger.info(line);
         return files;
     }
     catch (err) {
@@ -116,23 +155,69 @@ async function resolveScopedTargetFiles(ctx, globs, sourcePaths) {
         return null;
     return scopeToSourcePaths(files, sourcePaths);
 }
+/**
+ * Resolve a check's file list, or the outcome it should report instead.
+ *
+ * The one entry point for checks that operate on whole files. It wraps
+ * {@link resolveTargetFiles} and {@link listTrackedFiles} rather than replacing
+ * them — a check that needs the raw list (because it distinguishes the two cases
+ * itself, or scans in several passes) still calls those directly.
+ */
+async function resolveTargets(ctx, globs, opts) {
+    const listOpts = opts.keepDirs ? { keepDirs: opts.keepDirs } : {};
+    // Read once, and only when something will use it. A whole-tree walk is always
+    // scoped — that is what `listTrackedFiles` promises its callers — while a delta
+    // walk is scoped only on request.
+    const sourcePaths = opts.wholeTree || opts.scoped ? (0, config_1.getSourcePaths)(ctx.cwd) : [];
+    const files = opts.wholeTree
+        ? await listTrackedFiles(ctx, globs, sourcePaths, listOpts)
+        : await resolveTargetFiles(ctx, globs, listOpts);
+    if (files === null)
+        return (0, types_1.skip)('git unavailable');
+    const scoped = opts.wholeTree ? files : scopeToSourcePaths(files, sourcePaths);
+    if (scoped.length > 0)
+        return scoped;
+    return 'pass' in opts.onEmpty ? (0, types_1.pass)(opts.onEmpty.pass) : (0, types_1.skip)(opts.onEmpty.skip);
+}
 /**
  * List ALL tracked files matching `globs` (never delta), scoped to
- * `sourcePath`(s). For whole-repo analyses like circular-dependency detection
- * that need the full graph, not just the PR diff. Using `git ls-files` means
- * untracked `node_modules` is excluded by construction.
+ * `sourcePath`(s).
+ *
+ * For whole-repo analyses like circular-dependency detection that need the full
+ * graph, not just the PR diff. Using `git ls-files` means untracked
+ * `node_modules` is excluded by construction.
+ *
+ * `keepDirs` un-ignores segments for one caller, exactly as in
+ * {@link resolveTargetFiles}. It was missing here, and that made Workflow
+ * Security blind on the whole-tree path: `.github` is in the default ignore list,
+ * so `git ls-files .github/workflows/*.yml` returned the workflow and this
+ * function then dropped it. A blocking security check reported a clean pass over
+ * files it had never been handed — the surviving half of ticket 067, found by
+ * level 1 of the release regression plan.
+ *
+ * `null` when git could not answer, `[]` when it answered "nothing". The two are
+ * opposites to a caller and used to be the same value: `reject: false` keeps a
+ * failed git out of the catch below, so a directory git cannot read returned an
+ * empty list, and every caller read that as "nothing to review" and passed. On a
+ * directory holding real code that produced three green rows — Diff Security,
+ * Workflow Security, Diff Smells — over files none of them had opened
+ * (ticket 072).
  */
-async function listTrackedFiles(ctx, globs, sourcePaths) {
+async function listTrackedFiles(ctx, globs, sourcePaths, opts = {}) {
     try {
-        const { stdout } = await (0, execa_1.execa)('git', ['ls-files', ...globs], { cwd: ctx.cwd, reject: false });
-        const files = excludeConfiguredPaths(excludeIgnoredDirs(stdout
+        const result = await (0, execa_1.execa)('git', ['ls-files', ...globs], { cwd: ctx.cwd, reject: false });
+        if (result.exitCode !== 0) {
+            utils_1.logger.warn(`[targets]: ⚠️ git could not list tracked files (exit ${result.exitCode})`);
+            return null;
+        }
+        const files = excludeClientPaths(excludeIgnoredDirs(result.stdout
             .split('\n')
             .map(f => f.trim())
-            .filter(Boolean)));
+            .filter(Boolean), ctx.cwd, opts.keepDirs), ctx.cwd);
         return scopeToSourcePaths(files, sourcePaths);
     }
     catch (err) {
         utils_1.logger.warn(`[targets]: ⚠️ Could not list tracked files\n${err}`);
-        return [];
+        return null;
     }
 }

package/dist/core/types.d.ts

@@ -1,7 +1,7 @@
 import type { PRCheckMateConfig, ReporterConfig } from '../interfaces';
-import type { Language } from '../utils/detect-language';
+import type { Language, LanguageUsage } from '../utils/detect-language';
 import type { CheckResult, CheckStatus } from '../utils/result-collector';
-export type { CheckResult, CheckStatus, Language };
+export type { CheckResult, CheckStatus, Language, LanguageUsage };
 /**
  * Execution phases, run strictly in order. Within a phase checks run in parallel.
  * `format` runs last because formatters (prettier) may write files.
@@ -32,6 +32,12 @@ export interface CheckContext {
     cwd: string;
     /** Languages detected (or supplied) for this repo — drives `applies` gating. */
     languages: Language[];
+    /**
+     * The same detection with its evidence — file counts per language. Read by the
+     * install layer, which must not confuse "this language is here" with "this
+     * language is worth a toolchain download". Absent on hand-built contexts.
+     */
+    usage?: LanguageUsage[];
     /** Merged pr-checkmate.json + defaults. */
     config: PRCheckMateConfig;
     /** When false, checks that would modify files (prettier, --fix) run read-only or skip the write. */

package/dist/init.js

@@ -11,6 +11,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const config_1 = require("./config");
+const findings_1 = require("./core/checks/findings");
 const utils_1 = require("./utils");
 const CONFIG_FILE = path_1.default.resolve(process.cwd(), 'pr-checkmate.json');
 /**
@@ -319,7 +320,26 @@ function buildInitialConfig(sourcePath, languages) {
         // Delete an entry to have that check start reporting on tests again.
         duplicate: { ignore: [...config_1.DUPLICATE_IGNORE_DEFAULTS] },
         deadCode: { ignoreFiles: [...config_1.DEAD_CODE_IGNORE_DEFAULTS] },
-        diffSecurity: { ignorePaths: [...config_1.DIFF_SECURITY_IGNORE_DEFAULTS] },
+        // `dataflowWindow` is written out at its default for the same reason as
+        // `max-len`: it is a number people will want to change, and a number nobody
+        // can see is a number nobody can change. It is also the one finding in this
+        // check produced by a heuristic rather than a pattern, so the caveat belongs
+        // next to the value — including the part that surprises people, which is what
+        // promoting the whole check to `error` does to it.
+        '// diffSecurity': [
+            '"ignorePaths" REPLACES the test-path defaults below — they are there because a security',
+            "test's job is to contain the exact constructs this check hunts for.",
+            '"dataflowWindow" is how many added lines a value stays tainted for, so an interpolated',
+            'string assigned on one line and passed to a query on the next are still connected.',
+            'It is a heuristic — no scopes, no reassignment tracking — so it only ever warns.',
+            'Set it to 0 to switch it off. Note that "severity": { "Diff Security": "error" } promotes',
+            'this warning to a failure along with the rest, so a repository that makes this check a',
+            'gate and does not want the heuristic blocking should set dataflowWindow to 0.',
+        ].join(' '),
+        diffSecurity: {
+            dataflowWindow: findings_1.DEFAULT_DATAFLOW_WINDOW,
+            ignorePaths: [...config_1.DIFF_SECURITY_IGNORE_DEFAULTS],
+        },
         documentation: config_1.documentation,
         languages,
     };

package/dist/interfaces/index.d.ts

@@ -299,6 +299,7 @@ export interface PRCheckMateConfig {
             flags?: string;
         }>;
         commentHandling?: 'language' | 'legacy' | 'off';
+        dataflowWindow?: number;
     };
     mergeConflict?: {
         enabled?: boolean;

package/dist/utils/resolve-bin.d.ts

@@ -1,16 +1,66 @@
+/** Where a tool was found, in the order the candidates are tried. */
+export type ToolSource = 'client' | 'profile' | 'bundled';
+/** A resolved tool binary, and which copy of it answered. */
+export interface ResolvedTool {
+    bin: string;
+    source: ToolSource;
+    /** The search root that produced it; `undefined` for module-relative resolution. */
+    root?: string;
+}
+/**
+ * Point tool resolution at the profile directories fetched for this run.
+ *
+ * Called by the install layer once the cache is known. Passing an empty list —
+ * or never calling it at all — leaves resolution exactly as it was before
+ * profiles existed, which is what keeps a run that needs no fetching identical
+ * to a run from before there was anything to fetch.
+ */
+export declare function registerToolPaths(dirs: string[]): void;
+/** Drop every registered profile root. For tests, and for a second run in-process. */
+export declare function clearToolPaths(): void;
+/** The root of the installed pr-checkmate package — where our own tooling lives. */
+export declare function ownPackageRoot(): string;
+/**
+ * Whether a package is physically present in our own dependency tree.
+ *
+ * Checked by walking `node_modules` upwards rather than by `require.resolve`,
+ * because a package that restricts its `exports` map resolves for neither its
+ * main entry nor its `package.json` while being perfectly well installed —
+ * `cspell` is one. The question here is only "is it there", and the directory
+ * answers that without an opinion about what it chooses to export.
+ *
+ * Walking up matters as much as the check itself: installed as a dependency, our
+ * own packages are hoisted to the client's `node_modules`, one level above ours.
+ */
+export declare function packagePresent(pkgName: string, from?: string): boolean;
+/**
+ * Resolve a tool's binary and say which copy answered.
+ *
+ * Use this over {@link resolvePackageBin} when the answer is worth logging — the
+ * source is the difference between "the client's ESLint 8 ran" and "ours did",
+ * and that is the first thing anyone asks when a lint result looks wrong.
+ *
+ * @param pkgName Package whose binary to resolve (e.g. `eslint`).
+ * @param binRelPath Bin path relative to the package root (e.g. `bin/eslint.js`).
+ * @param options Resolution options.
+ * @param options.paths Roots to prefer ahead of everything else. Use
+ *   `[process.cwd()]` to prefer the consumer project's copy.
+ */
+export declare function resolveTool(pkgName: string, binRelPath: string, options?: {
+    paths?: string[];
+}): ResolvedTool | null;
 /**
  * Resolves a binary path for a bundled package, bypassing exports map restrictions.
  *
- * Strategy (tries each in order):
- * 1. Direct subpath — fast path for packages that explicitly export their bin
- * 2. Via package.json — for packages that export ./package.json but not the bin subpath (e.g. eslint)
- * 3. Walk up from main entry — for packages that export neither (e.g. cspell)
+ * Throws when no copy can be found anywhere, which is the honest outcome: a check
+ * that cannot find its tool has nothing to report, and the install layer turns
+ * that into a skip with a reason rather than letting it surface as a stack trace.
  *
  * @param pkgName - The package whose binary to resolve (e.g. `eslint`).
  * @param binRelPath - The bin path relative to the package root (e.g. `bin/eslint.js`).
  * @param options - Resolution options.
- * @param options.paths - Directories to resolve from (passed to `require.resolve`).
- *   Use `[process.cwd()]` to prefer the consumer project's copy of the package.
+ * @param options.paths - Directories to resolve from, preferred over everything
+ *   else. Use `[process.cwd()]` to prefer the consumer project's copy.
  */
 export declare function resolvePackageBin(pkgName: string, binRelPath: string, options?: {
     paths?: string[];