pr-checkmate 2.1.2 → 3.0.0

package/dist/core/context.js

@@ -192,7 +192,14 @@ async function buildContext(opts = {}) {
     // rather than calling getIgnoredDirs() — that one resolves against process.cwd(),
     // which is not necessarily the `cwd` under review.
     applyLogConfig(config);
-    const languages = opts.languages ?? (await (0, detect_language_1.detectLanguages)(cwd, config.ignoreDirs, config.detect));
+    // Detected as usage (language + file count), not as a bare list: the same scan
+    // answers two different questions, and the install layer needs the counts. A
+    // `Cargo.toml` beside zero `.rs` files is enough to run Rust checks and not
+    // enough to download a toolchain — see `detectLanguageUsage`.
+    const usage = opts.languages
+        ? opts.languages.map(lang => ({ lang, files: 1, marker: true }))
+        : await (0, detect_language_1.detectLanguageUsage)(cwd, config.ignoreDirs, config.detect);
+    const languages = usage.map(u => u.lang);
     const { baseSha, headSha, scope } = await resolveDiffRange(cwd, opts);
     // `scope` is logged because it decides what the whole run looks at, and getting
     // it wrong is invisible in the results: a run that reviewed one commit and one
@@ -201,6 +208,7 @@ async function buildContext(opts = {}) {
     return {
         cwd,
         languages,
+        usage,
         config,
         write: opts.write ?? false,
         baseSha,

package/dist/core/install/cache.js

@@ -24,14 +24,13 @@ function expandHome(dir, home = node_os_1.default.homedir()) {
         return home;
     return dir.startsWith('~/') ? node_path_1.default.join(home, dir.slice(2)) : dir;
 }
-/** A directory we can actually write to, or null. */
-function usable(dir) {
+/** A directory we can actually write to. */
+function writable(dir) {
     try {
         node_fs_1.default.mkdirSync(dir, { recursive: true });
-        // Existence is not permission: a cache directory baked into a container
-        // image is often present and read-only, and finding that out at install
-        // time rather than at write time is the difference between a clear message
-        // and a stack trace halfway through fetching.
+        // Existence is not permission, and finding that out here rather than at write
+        // time is the difference between a clear message and a stack trace halfway
+        // through fetching.
         node_fs_1.default.accessSync(dir, node_fs_1.default.constants.W_OK);
         return true;
     }
@@ -39,6 +38,30 @@ function usable(dir) {
         return false;
     }
 }
+/**
+ * A directory that already exists and can at least be read.
+ *
+ * Only ever asked of a cache path the client named explicitly, and only after
+ * {@link writable} has said no. That combination has exactly one meaning: a cache
+ * baked into a container image, read-only on purpose, holding tooling somebody
+ * warmed at build time. Reading it needs no write permission, and refusing it
+ * because a *future* fetch could not write there discards the tooling that is
+ * sitting right there — which is how our own image lost `Python Types` under
+ * `--user` (ticket 083).
+ *
+ * A fetch into such a directory still fails, in `ensureProfile`, with the path it
+ * could not create. That is the clear message the write check was for; it is just
+ * no longer paid for by every read.
+ */
+function readable(dir) {
+    try {
+        node_fs_1.default.accessSync(dir, node_fs_1.default.constants.R_OK | node_fs_1.default.constants.X_OK);
+        return node_fs_1.default.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Resolve the cache directory, falling back rather than failing.
  *
@@ -62,12 +85,20 @@ function resolveCacheDir(version, configured, env = process.env) {
     candidates.push({ dir: node_path_1.default.join(node_os_1.default.tmpdir(), 'pr-checkmate-cache'), reason: 'temp directory' });
     for (const [index, candidate] of candidates.entries()) {
         const dir = node_path_1.default.join(candidate.dir, version);
-        if (!usable(dir))
-            continue;
-        if (index > 0) {
-            logger_1.logger.warn(`[install]: ⚠️ cache directory "${candidates[0].dir}" is not writable — using ${candidate.reason} (${dir}). Fetched tooling will not survive a container rebuild.`);
+        if (writable(dir)) {
+            if (index > 0) {
+                logger_1.logger.warn(`[install]: ⚠️ cache directory "${candidates[0].dir}" is not writable — using ${candidate.reason} (${dir}). Fetched tooling will not survive a container rebuild.`);
+            }
+            return { dir, preferred: index === 0, reason: candidate.reason };
+        }
+        // An explicitly named cache that cannot be written but CAN be read is still
+        // the answer — see {@link readable} — and it has to win here rather than in a
+        // second pass at the end. Otherwise the writable-but-empty temp directory two
+        // candidates down takes precedence over a read-only cache holding the very
+        // tooling this run needs, which is the shape our own image has.
+        if (index === 0 && explicit && readable(dir)) {
+            return { dir, preferred: true, reason: 'configured, read-only' };
         }
-        return { dir, preferred: index === 0, reason: candidate.reason };
     }
     return null;
 }

package/dist/core/install/doctor.js

@@ -17,6 +17,7 @@ const package_version_1 = require("../../utils/package-version");
 Object.defineProperty(exports, "packageVersion", { enumerable: true, get: function () { return package_version_1.packageVersion; } });
 const cache_1 = require("./cache");
 const ensure_1 = require("./ensure");
+const prepare_1 = require("./prepare");
 const profiles_1 = require("./profiles");
 /**
  * Everything the install layer knows about this repository, in one shot.
@@ -52,6 +53,14 @@ async function installProfiles(cwd = process.cwd(), all = false) {
     const denied = new Set(install.deny ?? []);
     const wanted = (all ? profiles_1.PROFILES.map(p => p.name) : decisions.filter(d => d.required).map(d => d.profile)).filter(name => {
         const profile = profiles_1.PROFILES.find(p => p.name === name);
+        // Nothing to fetch for a profile whose packages already ship with us, and
+        // fetching it anyway is not merely wasted: `--all` downloaded a second copy
+        // of every bundled profile — some 800 packages — beside the ones already in
+        // `node_modules`. On a container build that lands in the image (ticket 083).
+        if (profile && (0, prepare_1.profileSatisfiedLocally)(profile)) {
+            logger_1.logger.info(`[install]: profile "${name}" already ships with the package`);
+            return false;
+        }
         const blocked = profile?.packages.filter(pkg => denied.has(pkg)) ?? [];
         if (blocked.length === 0)
             return true;

package/dist/core/install/ensure.js

@@ -74,9 +74,6 @@ function stageManifest(from, to) {
  */
 async function ensureProfile(profile, opts) {
     const { install } = opts;
-    if (install.strategy === 'manual') {
-        return { profile, status: 'skipped', reason: 'install.strategy is "manual"' };
-    }
     const source = manifestDir(profile);
     const expected = manifestHash(source);
     if (!expected) {
@@ -94,6 +91,28 @@ async function ensureProfile(profile, opts) {
     if (isInstalled(dir, expected)) {
         return { profile, status: 'cached', reason: 'already installed', dir };
     }
+    // Both of these mean "do not fetch", and both are asked AFTER the cache check
+    // above — because neither means "do not use what has already been fetched".
+    //
+    // `offline` was always in the right place; `manual` was not, and returned before
+    // the cache was ever looked at. So `install --all`, the command the product's
+    // own log recommends for pre-warming, did nothing for anyone who then set
+    // `manual` — including our Docker image, which sets it precisely because
+    // everything is supposed to already be there. `Python Types` in that image
+    // could not run at all (ticket 083).
+    // The env var as well as the config key, exactly as `PR_CHECKMATE_OFFLINE` is
+    // read below: the Docker image sets the strategy through the environment, and a
+    // guarantee that only holds when it is written in a config file is not a
+    // guarantee.
+    const strategy = process.env.PR_CHECKMATE_INSTALL_STRATEGY ?? install.strategy;
+    if (strategy === 'manual') {
+        return {
+            profile,
+            status: 'skipped',
+            reason: 'install.strategy is "manual" and the profile is not in the cache',
+            dir,
+        };
+    }
     if (install.offline || process.env.PR_CHECKMATE_OFFLINE === 'true') {
         return {
             profile,

package/dist/core/install/lock.d.ts

@@ -25,9 +25,10 @@ export declare function processAlive(pid: number): boolean;
  * @returns A release function, or `null` when the lock could not be created at
  *   all (an unwritable directory — the caller reports that, it is not fatal here).
  */
-export interface LockDeps {
+interface LockDeps {
     sleep?: (ms: number) => Promise<void>;
     now?: () => number;
     alive?: (pid: number) => boolean;
 }
 export declare function withLock(dir: string, timeoutMs: number, deps?: LockDeps): Promise<(() => void) | null>;
+export {};

package/dist/core/install/prepare.d.ts

@@ -0,0 +1,75 @@
+import type { PRCheckMateConfig } from '../../interfaces';
+import type { LanguageUsage } from '../../utils/detect-language';
+import { type EnsureOptions } from './ensure';
+import { type Profile } from './profiles';
+/**
+ * Whether a profile needs fetching at all, or already ships inside the package.
+ *
+ * This is the hinge the whole adaptive-install rollout turns on. Today every
+ * profile's packages sit in our `dependencies`, so every profile answers `true`
+ * here, nothing is ever fetched, and a run is byte-for-byte the run it was
+ * before any of this existed. When a package is moved out of `dependencies` it
+ * stops being present, its profile starts answering `false`, and the fetch turns
+ * itself on — no flag, no second code path, nothing to remember to flip.
+ *
+ * Which is what makes releases 2 and 3 of ticket 064 an edit to `package.json`
+ * rather than another change to this logic.
+ */
+export declare function profileSatisfiedLocally(profile: Profile): boolean;
+/** What the run knows about tooling before the first check starts. */
+export interface ToolingPlan {
+    /** Check name → why its tooling is not available. Empty on a healthy run. */
+    unavailable: Map<string, string>;
+    /** Profile directories tool resolution should search. */
+    dirs: string[];
+    /**
+     * True when tooling is missing and `install.onMissingTool` is `"error"`. The
+     * affected checks fail instead of skipping: in a closed contour a check that
+     * quietly stops running is worse than a red build.
+     */
+    fatal: boolean;
+}
+interface PrepareOptions {
+    cwd: string;
+    config: PRCheckMateConfig;
+    /** Detected languages with file counts — reused so the tree is scanned once. */
+    usage: LanguageUsage[];
+    /** Names of the checks this run intends to execute. */
+    selected: string[];
+    /** pr-checkmate's own version; part of the cache path. */
+    version: string;
+    /**
+     * The profile catalogue. Defaults to the shipped one; injected by tests.
+     *
+     * A seam rather than a mock of the module, for the same reason `ensure.ts` has
+     * one: every profile currently ships inside the package, so the interesting
+     * half of this function — a profile that is genuinely absent — is unreachable
+     * without either a network install in a unit test or a way to describe a
+     * profile that is not here. The code that runs when a package finally leaves
+     * `dependencies` must be tested before that day, not on it.
+     */
+    profiles?: Profile[];
+    /** The fetch itself, forwarded to `ensureProfile`. Injected by tests. */
+    installer?: EnsureOptions['installer'];
+}
+/**
+ * Make sure the tooling this run needs is present, and say what is missing.
+ *
+ * Runs once, before the first check, and answers two questions the run cannot
+ * proceed honestly without: which directories tool resolution should search, and
+ * which checks have no tool to run. The second is the one ticket 057 is about —
+ * a check whose tooling never arrived must appear in the report saying so, not
+ * vanish from it.
+ *
+ * Only profiles backing checks that are actually selected are considered, so
+ * `severity: { "Spellcheck": "off" }` stops costing a download rather than only a
+ * row in the report (lever B of ticket 064).
+ */
+export declare function prepareTooling(opts: PrepareOptions): Promise<ToolingPlan>;
+/**
+ * The plan for a run where preparation did not happen — nothing missing, nothing
+ * registered. Built fresh each time rather than shared: a caller holding a plan
+ * must not be able to see another run's.
+ */
+export declare function noTooling(): ToolingPlan;
+export {};

package/dist/core/install/prepare.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.profileSatisfiedLocally = profileSatisfiedLocally;
+exports.prepareTooling = prepareTooling;
+exports.noTooling = noTooling;
+const logger_1 = require("../../utils/logger");
+const resolve_bin_1 = require("../../utils/resolve-bin");
+const cache_1 = require("./cache");
+const ensure_1 = require("./ensure");
+const profiles_1 = require("./profiles");
+/**
+ * Whether a profile needs fetching at all, or already ships inside the package.
+ *
+ * This is the hinge the whole adaptive-install rollout turns on. Today every
+ * profile's packages sit in our `dependencies`, so every profile answers `true`
+ * here, nothing is ever fetched, and a run is byte-for-byte the run it was
+ * before any of this existed. When a package is moved out of `dependencies` it
+ * stops being present, its profile starts answering `false`, and the fetch turns
+ * itself on — no flag, no second code path, nothing to remember to flip.
+ *
+ * Which is what makes releases 2 and 3 of ticket 064 an edit to `package.json`
+ * rather than another change to this logic.
+ */
+function profileSatisfiedLocally(profile) {
+    return profile.packages.every(pkg => (0, resolve_bin_1.packagePresent)(pkg));
+}
+/** Profiles blocked outright by `install.deny`, with a line saying so. */
+function denied(profile, deny) {
+    const blocked = profile.packages.filter(pkg => deny.has(pkg));
+    if (blocked.length === 0)
+        return null;
+    return `install.deny lists ${blocked.join(', ')}`;
+}
+/**
+ * Make sure the tooling this run needs is present, and say what is missing.
+ *
+ * Runs once, before the first check, and answers two questions the run cannot
+ * proceed honestly without: which directories tool resolution should search, and
+ * which checks have no tool to run. The second is the one ticket 057 is about —
+ * a check whose tooling never arrived must appear in the report saying so, not
+ * vanish from it.
+ *
+ * Only profiles backing checks that are actually selected are considered, so
+ * `severity: { "Spellcheck": "off" }` stops costing a download rather than only a
+ * row in the report (lever B of ticket 064).
+ */
+async function prepareTooling(opts) {
+    // Every run starts from no registered roots. The SDK can call `runChecks` more
+    // than once in one process, and a directory registered by a previous run — for
+    // a different repository, with a different profile set — must not still be on
+    // the search path for this one.
+    (0, resolve_bin_1.clearToolPaths)();
+    const install = opts.config.install ?? {};
+    const strategy = process.env.PR_CHECKMATE_INSTALL_STRATEGY ?? install.strategy ?? 'adaptive';
+    const onMissing = install.onMissingTool ?? 'auto';
+    const deny = new Set(install.deny ?? []);
+    // Which profiles this repository needs: languages by file count, universal
+    // profiles by whether their check survived config. `install.profiles` and
+    // `excludeProfiles` have already had their say inside `planProfiles`.
+    const required = new Set((0, profiles_1.planProfiles)(opts.usage, opts.config)
+        .filter(decision => decision.required)
+        .map(decision => decision.profile));
+    // A profile nobody in this run would use is not worth a thought, let alone a
+    // download. `eager` opts out of that reasoning by definition: it exists so a
+    // container build or an air-gapped mirror can hold everything up front.
+    const chosen = opts.selected.length > 0 ? new Set(opts.selected) : null;
+    const wanted = (opts.profiles ?? profiles_1.PROFILES).filter(profile => {
+        if (strategy === 'eager')
+            return true;
+        if (!required.has(profile.name))
+            return false;
+        return !chosen || profile.checks.some(check => chosen.has(check));
+    });
+    const unavailable = new Map();
+    const dirs = [];
+    const miss = (profile, reason) => {
+        for (const check of profile.checks)
+            unavailable.set(check, reason);
+    };
+    // Resolved lazily, and at most once.
+    //
+    // Lazily because resolving is not a read: it creates the directory and, when the
+    // configured one is unwritable, warns about where fetched tooling will live
+    // instead. On a run that fetches nothing — every run, while the tooling still
+    // ships in `dependencies` — that warning is about a thing that never happens,
+    // and a container with a read-only home would print it on every single run.
+    // At most once because the warning belongs to the run, not to each profile.
+    let location;
+    const cacheDir = () => {
+        if (location === undefined)
+            location = (0, cache_1.resolveCacheDir)(opts.version, install.cacheDir);
+        return location;
+    };
+    for (const profile of wanted) {
+        // Bundled tooling is the answer to "where is it" for every profile today,
+        // and asking first is what keeps this whole path free of network calls.
+        if (profileSatisfiedLocally(profile))
+            continue;
+        const block = denied(profile, deny);
+        if (block) {
+            miss(profile, block);
+            continue;
+        }
+        // No early exit for `install.strategy: "manual"` any more. It means "never
+        // fetch", and `ensureProfile` enforces that — but only after checking the
+        // cache, so a pre-warmed profile is still used. Returning here instead
+        // meant `manual` also refused tooling that was already downloaded.
+        if (onMissing === 'skip') {
+            miss(profile, 'install.onMissingTool is "skip"');
+            continue;
+        }
+        const cache = cacheDir();
+        if (!cache) {
+            miss(profile, 'no writable cache directory for fetched tooling');
+            continue;
+        }
+        const result = await (0, ensure_1.ensureProfile)(profile.name, {
+            cwd: opts.cwd,
+            version: opts.version,
+            install,
+            ...(opts.installer ? { installer: opts.installer } : {}),
+        });
+        if (result.status === 'failed' || result.status === 'skipped') {
+            miss(profile, result.reason);
+            continue;
+        }
+        dirs.push(result.dir ?? (0, cache_1.profileDir)(cache.dir, profile.name));
+    }
+    if (unavailable.size > 0) {
+        // Always logged, never behind --debug. A check that did not run is the
+        // failure mode this whole layer exists to make loud.
+        const names = [...new Set(unavailable.keys())].join(', ');
+        logger_1.logger.warn(`[install]: ⚠️ tooling unavailable — these checks cannot run: ${names}`);
+        if (onMissing === 'error') {
+            logger_1.logger.error('[install]: ❌ install.onMissingTool is "error" — the affected checks fail');
+        }
+        else {
+            logger_1.logger.info('[install]:    Pre-warm the cache with: npx pr-checkmate install --all');
+        }
+    }
+    (0, resolve_bin_1.registerToolPaths)(dirs);
+    return { unavailable, dirs, fatal: onMissing === 'error' && unavailable.size > 0 };
+}
+/**
+ * The plan for a run where preparation did not happen — nothing missing, nothing
+ * registered. Built fresh each time rather than shared: a caller holding a plan
+ * must not be able to see another run's.
+ */
+function noTooling() {
+    return { unavailable: new Map(), dirs: [], fatal: false };
+}

package/dist/core/install/profiles.d.ts

@@ -12,7 +12,7 @@ import type { Language, LanguageUsage } from '../../utils/detect-language';
  * honest report: when a profile is missing, exactly those checks skip, with the
  * reason, instead of quietly disappearing (the mistake of ticket 057).
  */
-interface Profile {
+export interface Profile {
     name: ProfileName;
     /** Top-level packages installed for this profile. */
     packages: string[];
@@ -23,8 +23,23 @@ interface Profile {
      * enabled checks rather than by what the repository is written in.
      */
     languages?: Language[];
+    /**
+     * An extra condition on the client's config, for a language profile whose
+     * checks can be switched off by a key of their own.
+     *
+     * `severity: { "X": "off" }` is already honoured for every profile, but it is
+     * not the only off switch: `python.typecheck: false` and `go.enabled: false`
+     * are the ones a client actually writes, and a language profile decided on
+     * file counts alone downloads the tooling regardless. For `pytypes` that is
+     * 19 MB fetched to run nothing.
+     *
+     * Deliberately a predicate over the config rather than a list of keys: the
+     * condition it mirrors lives in the check's own `applies`, and expressing it
+     * the same way is what makes the two readable side by side.
+     */
+    enabledBy?(config: PRCheckMateConfig): boolean;
 }
-export type ProfileName = 'core' | 'js' | 'python' | 'cpp' | 'spellcheck' | 'markdown' | 'commitlint' | 'duplicate';
+export type ProfileName = 'core' | 'js' | 'python' | 'pytypes' | 'cpp' | 'go' | 'spellcheck' | 'markdown' | 'commitlint' | 'duplicate';
 /**
  * The catalogue.
  *
@@ -61,4 +76,3 @@ export interface ProfileDecision {
  * @returns One decision per profile, in catalogue order.
  */
 export declare function planProfiles(usage: LanguageUsage[], config: PRCheckMateConfig): ProfileDecision[];
-export {};

package/dist/core/install/profiles.js

@@ -54,12 +54,33 @@ exports.PROFILES = [
         checks: ['Ruff Lint', 'Ruff Format'],
         languages: ['python'],
     },
+    {
+        // Separate from `python` because it is 19 MB against ruff's 12, and because
+        // the two answer different questions: plenty of repositories want the linter
+        // and have their own opinion about type checking. Bundling them would make
+        // `python.typecheck: false` cost the download anyway, which is the feature
+        // defeating itself.
+        name: 'pytypes',
+        packages: ['pyright'],
+        checks: ['Python Types'],
+        languages: ['python'],
+        enabledBy: config => config.python?.typecheck !== false && config.python?.enabled !== false,
+    },
     {
         name: 'cpp',
         packages: ['@wasm-fmt/clang-format'],
         checks: ['C++ Format'],
         languages: ['cpp'],
     },
+    {
+        // Go Format only. `go vet` needs the toolchain itself, which is not ours to
+        // ship, so it stays a runner dependency and is deliberately absent here.
+        name: 'go',
+        packages: ['@wasm-fmt/gofmt'],
+        checks: ['Go Format'],
+        languages: ['go'],
+        enabledBy: config => config.go?.enabled !== false,
+    },
     {
         // The four below are not languages. They are single checks with heavy
         // tooling behind them, which is exactly why they are separate: switching
@@ -145,6 +166,12 @@ function decide(profile, usage, config, minFiles) {
     if (profile.name === 'core')
         return { required: true, reason: 'always installed' };
     if (profile.languages) {
+        // Asked before the file counts, because it is the cheaper and the more
+        // definite answer: a client who wrote `python.typecheck: false` has settled
+        // the question, and counting `.py` files can only override them.
+        if (profile.enabledBy && !profile.enabledBy(config)) {
+            return { required: false, reason: `${profile.checks.join(', ')} switched off` };
+        }
         const found = profile.languages
             .map(lang => usage.find(u => u.lang === lang))
             .filter((u) => Boolean(u) && u.files >= minFiles);

package/dist/core/install/reuse.d.ts

@@ -0,0 +1,41 @@
+import type { CheckContext } from '../types';
+/** One reuse decision, with the sentence that explains it. */
+interface ReuseDecision {
+    /** Search roots to prefer, or `undefined` to use our own copy. */
+    paths?: string[];
+    reason: string;
+}
+interface ReuseOptions {
+    /**
+     * The tool will read the client's OWN configuration file.
+     *
+     * When it will, the version check is the wrong question and must not be asked:
+     * a repository with ESLint 8 and a legacy `.eslintrc` can only be linted by
+     * ESLint 8, because ESLint 10 does not read eslintrc — and falling back to ours
+     * on the strength of a major mismatch would break precisely the case the reuse
+     * was there to serve. TypeScript is the same shape permanently: the check only
+     * applies when the repository has a `tsconfig.json`, so their compiler is
+     * always the one their config was written for.
+     *
+     * The version check exists for the opposite case — the client's old tool being
+     * handed configuration WE generated.
+     */
+    clientOwnsConfig?: boolean;
+}
+/**
+ * Decide whether this run should prefer the client's copy of `pkgName`.
+ *
+ * `compatible` (the default) reuses when the client's major matches ours, or when
+ * the client's own configuration is what the tool will read. A mismatch is not an
+ * error — we have our own copy — so it downgrades to ours with a line saying why.
+ */
+export declare function reuseDecision(pkgName: string, ctx: CheckContext, opts?: ReuseOptions): ReuseDecision;
+/**
+ * The search roots a check should prefer for `pkgName`, logging the reason once.
+ *
+ * The reason is logged rather than returned to each caller because it answers the
+ * question every confusing lint result starts with — "whose ESLint ran" — and no
+ * check should have to remember to say so.
+ */
+export declare function clientToolPaths(pkgName: string, ctx: CheckContext, opts?: ReuseOptions): string[] | undefined;
+export {};

package/dist/core/install/reuse.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reuseDecision = reuseDecision;
+exports.clientToolPaths = clientToolPaths;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../../utils/logger");
+const resolve_bin_1 = require("../../utils/resolve-bin");
+/**
+ * The major version we declare for a tool, from our own manifest.
+ *
+ * Read from `dependencies` rather than from the installed tree: what matters is
+ * the version our configuration was written against, and a hoisted install can
+ * resolve to something else entirely.
+ */
+function ownMajor(pkgName) {
+    try {
+        const manifest = node_path_1.default.join((0, resolve_bin_1.ownPackageRoot)(), 'package.json');
+        const deps = JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf-8')).dependencies;
+        const range = deps?.[pkgName];
+        if (!range)
+            return null;
+        // `^10.6.0`, `>=3.0.0`, `~5.1` — the leading number is the major in every
+        // form we declare. Deliberately not a semver parser: this package ships zero
+        // runtime dependencies on purpose, and a major comparison is the only
+        // question being asked.
+        const major = /(\d+)/.exec(range)?.[1];
+        return major ? Number(major) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The major version of a package as the client actually has it installed. */
+function installedMajor(pkgName, from) {
+    let dir = from;
+    while (dir !== node_path_1.default.dirname(dir)) {
+        const manifest = node_path_1.default.join(dir, 'node_modules', pkgName, 'package.json');
+        try {
+            if (node_fs_1.default.existsSync(manifest)) {
+                const version = JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf-8'))
+                    .version;
+                const major = version ? /(\d+)/.exec(version)?.[1] : undefined;
+                return major ? Number(major) : null;
+            }
+        }
+        catch {
+            return null;
+        }
+        dir = node_path_1.default.dirname(dir);
+    }
+    return null;
+}
+/**
+ * Decide whether this run should prefer the client's copy of `pkgName`.
+ *
+ * `compatible` (the default) reuses when the client's major matches ours, or when
+ * the client's own configuration is what the tool will read. A mismatch is not an
+ * error — we have our own copy — so it downgrades to ours with a line saying why.
+ */
+function reuseDecision(pkgName, ctx, opts = {}) {
+    const policy = ctx.config.install?.reuseLocal ?? 'compatible';
+    if (policy === 'off') {
+        return { reason: 'install.reuseLocal is "off" — using our own copy for reproducibility' };
+    }
+    const clientMajor = installedMajor(pkgName, ctx.cwd);
+    if (clientMajor === null) {
+        return { reason: `${pkgName} is not installed in the repository — using our own copy` };
+    }
+    if (policy === 'always') {
+        return {
+            paths: [ctx.cwd],
+            reason: `install.reuseLocal is "always" — using ${pkgName}@${clientMajor} from the repository`,
+        };
+    }
+    if (opts.clientOwnsConfig) {
+        return {
+            paths: [ctx.cwd],
+            reason: `using ${pkgName}@${clientMajor} from the repository — it reads the repository's own config`,
+        };
+    }
+    const ourMajor = ownMajor(pkgName);
+    if (ourMajor === null || clientMajor === ourMajor) {
+        return {
+            paths: [ctx.cwd],
+            reason: `using ${pkgName}@${clientMajor} from the repository (matches ours)`,
+        };
+    }
+    return {
+        reason: `the repository has ${pkgName}@${clientMajor} and our config is written for @${ourMajor} — using our own copy`,
+    };
+}
+/**
+ * The search roots a check should prefer for `pkgName`, logging the reason once.
+ *
+ * The reason is logged rather than returned to each caller because it answers the
+ * question every confusing lint result starts with — "whose ESLint ran" — and no
+ * check should have to remember to say so.
+ */
+function clientToolPaths(pkgName, ctx, opts = {}) {
+    const decision = reuseDecision(pkgName, ctx, opts);
+    logger_1.logger.debug(`[reuseLocal]: ${decision.reason}`);
+    return decision.paths;
+}