pr-checkmate 2.1.2 → 3.0.1

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

@@ -180,6 +180,11 @@ export interface PRCheckMateConfig {
         typecheck?: boolean;
         typeChecker?: 'mypy' | 'pyright';
     };
+    packageSize?: {
+        enabled?: boolean;
+        maxGrowthPercent?: number;
+        compareWith?: string;
+    };
     diffSmell?: {
         enabled?: boolean;
         ignorePaths?: string[];
@@ -299,6 +304,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[];

package/dist/utils/resolve-bin.js

@@ -3,51 +3,161 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerToolPaths = registerToolPaths;
+exports.clearToolPaths = clearToolPaths;
+exports.ownPackageRoot = ownPackageRoot;
+exports.packagePresent = packagePresent;
+exports.resolveTool = resolveTool;
 exports.resolvePackageBin = resolvePackageBin;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 /**
- * Resolves a binary path for a bundled package, bypassing exports map restrictions.
+ * Extra roots to search, registered once per run by the install layer.
  *
- * 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)
+ * Module state rather than a parameter threaded through fifteen call sites: a
+ * profile directory is a property of the *run*, not of any one check, and every
+ * check that resolves a binary would otherwise have to be handed a value it has
+ * no opinion about. `registerToolPaths` is called before the first check starts
+ * and never during one, so nothing observes it changing underneath.
+ */
+let profileRoots = [];
+/**
+ * Point tool resolution at the profile directories fetched for this run.
  *
- * @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.
+ * 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.
  */
-function resolvePackageBin(pkgName, binRelPath, options) {
-    const resolveOpts = options?.paths ? { paths: options.paths } : undefined;
-    // 1. Direct subpath
+function registerToolPaths(dirs) {
+    profileRoots = [...dirs];
+}
+/** Drop every registered profile root. For tests, and for a second run in-process. */
+function clearToolPaths() {
+    profileRoots = [];
+}
+/** The root of the installed pr-checkmate package — where our own tooling lives. */
+function ownPackageRoot() {
+    return node_path_1.default.resolve(__dirname, '../..');
+}
+/**
+ * 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.
+ */
+function packagePresent(pkgName, from = ownPackageRoot()) {
+    let dir = from;
+    while (dir !== node_path_1.default.dirname(dir)) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(dir, 'node_modules', pkgName, 'package.json')))
+            return true;
+        dir = node_path_1.default.dirname(dir);
+    }
+    return false;
+}
+/** One resolution attempt against a single set of search paths. */
+function tryResolve(pkgName, binRelPath, paths) {
+    const resolveOpts = paths ? { paths } : undefined;
+    // 1. Direct subpath — the fast path for packages that export their bin.
     try {
         return require.resolve(`${pkgName}/${binRelPath}`, resolveOpts);
     }
     catch { }
-    // 2. Via package.json
+    // 2. Via package.json — for packages that export `./package.json` but not the
+    //    bin subpath (eslint).
     try {
         const pkgJsonPath = require.resolve(`${pkgName}/package.json`, resolveOpts);
         return node_path_1.default.join(node_path_1.default.dirname(pkgJsonPath), binRelPath);
     }
     catch { }
-    // 3. Walk up from main entry to find package root by matching package name
-    const main = require.resolve(pkgName, resolveOpts);
-    let dir = node_path_1.default.dirname(main);
-    while (dir !== node_path_1.default.dirname(dir)) {
-        const pkgJsonPath = node_path_1.default.join(dir, 'package.json');
-        if (node_fs_1.default.existsSync(pkgJsonPath)) {
-            try {
-                const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgJsonPath, 'utf-8'));
-                if (pkg.name === pkgName) {
-                    return node_path_1.default.join(dir, binRelPath);
+    // 3. Walk up from the main entry, matching the package name — for packages
+    //    that export neither (cspell).
+    try {
+        let dir = node_path_1.default.dirname(require.resolve(pkgName, resolveOpts));
+        while (dir !== node_path_1.default.dirname(dir)) {
+            const pkgJsonPath = node_path_1.default.join(dir, 'package.json');
+            if (node_fs_1.default.existsSync(pkgJsonPath)) {
+                try {
+                    const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgJsonPath, 'utf-8'));
+                    if (pkg.name === pkgName)
+                        return node_path_1.default.join(dir, binRelPath);
                 }
+                catch { }
             }
-            catch { }
+            dir = node_path_1.default.dirname(dir);
         }
-        dir = node_path_1.default.dirname(dir);
     }
+    catch { }
+    return null;
+}
+/**
+ * The roots to try, in order, and what finding a tool in each one means.
+ *
+ * The order is the policy, and it is deliberate:
+ *
+ * 1. **The client's own copy**, when a caller asked for it. A repository pinned
+ *    to ESLint 8 with a legacy `.eslintrc` must keep working, and only its copy
+ *    can do that.
+ * 2. **A fetched profile**, for tooling that does not ship inside the package.
+ * 3. **Our bundle** — module-relative, exactly as resolution worked before
+ *    profiles existed.
+ *
+ * Branch 3 is passed `undefined` rather than our package root on purpose: that is
+ * literally the previous behaviour, so a run with nothing registered resolves
+ * every tool along the identical path it always did.
+ */
+function candidates(optPaths) {
+    const list = [];
+    if (optPaths && optPaths.length > 0)
+        list.push({ paths: optPaths, source: 'client' });
+    for (const root of profileRoots)
+        list.push({ paths: [root], source: 'profile' });
+    list.push({ source: 'bundled' });
+    return list;
+}
+/**
+ * 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.
+ */
+function resolveTool(pkgName, binRelPath, options) {
+    for (const candidate of candidates(options?.paths)) {
+        const bin = tryResolve(pkgName, binRelPath, candidate.paths);
+        if (bin)
+            return { bin, source: candidate.source, root: candidate.paths?.[0] };
+    }
+    return null;
+}
+/**
+ * Resolves a binary path for a bundled package, bypassing exports map restrictions.
+ *
+ * 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, preferred over everything
+ *   else. Use `[process.cwd()]` to prefer the consumer project's copy.
+ */
+function resolvePackageBin(pkgName, binRelPath, options) {
+    const resolved = resolveTool(pkgName, binRelPath, options);
+    if (resolved)
+        return resolved.bin;
     throw new Error(`Cannot resolve binary "${binRelPath}" for package "${pkgName}"`);
 }