pr-checkmate 3.0.4 → 3.2.0

package/dist/esm/core/install/merge.d.ts

@@ -0,0 +1,47 @@
+/** The `package.json` half of a shipped profile manifest. */
+interface ProfilePkg {
+    dependencies?: Record<string, string>;
+    overrides?: Record<string, unknown>;
+}
+/** The `package-lock.json` half. Entries are opaque to us beyond their identity. */
+interface ProfileLock {
+    packages: Record<string, unknown>;
+}
+/** A manifest pair `npm ci` can be pointed at. */
+export interface MergedManifest {
+    pkg: object;
+    lockfile: object;
+}
+/**
+ * Merge several profile manifests into the one a single `npm ci` installs.
+ *
+ * This is what stops the tooling cache from paying for the same package twice.
+ * Installing each profile into its own directory leaves npm nothing to
+ * deduplicate: `commitlint` and `js` share 30 MB, and separate trees download
+ * both copies. One tree costs the union instead of the sum — measured at 213 MB
+ * against 234 for a JavaScript repository, where per-profile directories came to
+ * 267 (ticket 087).
+ *
+ * The merge is a union, not a resolution, and it never reaches the network. Every
+ * shipped manifest was cut out of our own `package-lock.json` at build time, so
+ * two profiles that both contain a package contain the *same* entry for it,
+ * byte for byte. That is the whole reason this is safe to do at run time on a
+ * client's machine.
+ *
+ * Which makes a disagreement impossible unless we broke the build — so it throws
+ * rather than picking a winner. Choosing silently would hand a client a tree
+ * neither profile was tested against, and the integrity hashes that make this
+ * design defensible would be describing something we never ran.
+ *
+ * @param profiles Directories holding the shipped manifests, in any order.
+ * @param read Injected by tests; defaults to reading the two files.
+ * @throws If two profiles disagree about a package, or a manifest cannot be read.
+ */
+export declare function mergeManifests(profiles: Array<{
+    name: string;
+    dir: string;
+}>, read?: (dir: string) => {
+    pkg: ProfilePkg;
+    lock: ProfileLock;
+}): MergedManifest;
+export {};

package/dist/esm/core/install/merge.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const MERGED_NAME = 'pr-checkmate-tooling';
+const MERGED_VERSION = '1.0.0';
+/** Read a profile's shipped manifest pair from the installed package. */
+function readShippedManifest(dir) {
+    return {
+        pkg: JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8')),
+        lock: JSON.parse(fs.readFileSync(path.join(dir, 'package-lock.json'), 'utf-8')),
+    };
+}
+/**
+ * Merge several profile manifests into the one a single `npm ci` installs.
+ *
+ * This is what stops the tooling cache from paying for the same package twice.
+ * Installing each profile into its own directory leaves npm nothing to
+ * deduplicate: `commitlint` and `js` share 30 MB, and separate trees download
+ * both copies. One tree costs the union instead of the sum — measured at 213 MB
+ * against 234 for a JavaScript repository, where per-profile directories came to
+ * 267 (ticket 087).
+ *
+ * The merge is a union, not a resolution, and it never reaches the network. Every
+ * shipped manifest was cut out of our own `package-lock.json` at build time, so
+ * two profiles that both contain a package contain the *same* entry for it,
+ * byte for byte. That is the whole reason this is safe to do at run time on a
+ * client's machine.
+ *
+ * Which makes a disagreement impossible unless we broke the build — so it throws
+ * rather than picking a winner. Choosing silently would hand a client a tree
+ * neither profile was tested against, and the integrity hashes that make this
+ * design defensible would be describing something we never ran.
+ *
+ * @param profiles Directories holding the shipped manifests, in any order.
+ * @param read Injected by tests; defaults to reading the two files.
+ * @throws If two profiles disagree about a package, or a manifest cannot be read.
+ */
+export function mergeManifests(profiles, read = readShippedManifest) {
+    const dependencies = {};
+    const overrides = {};
+    const packages = {};
+    // Which profile first claimed a given key, so a conflict names both sides.
+    const claimedBy = new Map();
+    const claim = (kind, key, value, by, into) => {
+        const id = `${kind}:${key}`;
+        const seen = claimedBy.get(id);
+        if (seen === undefined) {
+            claimedBy.set(id, by);
+            into[key] = value;
+            return;
+        }
+        if (JSON.stringify(into[key]) !== JSON.stringify(value)) {
+            throw new Error(`profiles "${seen}" and "${by}" disagree about ${kind} "${key}" — ` +
+                'the shipped manifests are out of sync with our lockfile');
+        }
+    };
+    for (const { name, dir } of profiles) {
+        const { pkg, lock } = read(dir);
+        for (const [dep, version] of Object.entries(pkg.dependencies ?? {})) {
+            claim('dependency', dep, version, name, dependencies);
+        }
+        for (const [target, rule] of Object.entries(pkg.overrides ?? {})) {
+            claim('override', target, rule, name, overrides);
+        }
+        for (const [entryPath, entry] of Object.entries(lock.packages ?? {})) {
+            // The root entry describes the profile itself — its name, its direct
+            // dependencies. It is replaced by the merged root below, not merged: two
+            // profiles always "disagree" about it, and rightly so.
+            if (entryPath === '')
+                continue;
+            claim('package', entryPath, entry, name, packages);
+        }
+    }
+    const scoped = Object.keys(overrides).length > 0 ? { overrides } : {};
+    const root = { name: MERGED_NAME, version: MERGED_VERSION, dependencies, ...scoped };
+    return {
+        pkg: { ...root, private: true },
+        lockfile: {
+            name: MERGED_NAME,
+            version: MERGED_VERSION,
+            lockfileVersion: 3,
+            requires: true,
+            packages: { '': root, ...packages },
+        },
+    };
+}

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

@@ -0,0 +1,76 @@
+import type { PRCheckMateConfig } from '../../interfaces/index.js';
+import type { LanguageUsage } from '../../utils/detect-language.js';
+import { type EnsureOptions } from './ensure.js';
+import { type Profile } from './profiles.js';
+/**
+ * Whether a profile needs fetching at all, or already ships inside the package.
+ *
+ * This is the hinge the whole adaptive-install rollout turns on. Nearly every
+ * profile's packages sit in our `dependencies`, so it answers `true`, nothing is
+ * fetched, and a run is byte-for-byte the run it was before any of this existed.
+ * `pytypes` is the exception that already proves the other half works: `pyright`
+ * is a devDependency, so it reaches no client and is fetched on demand. 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: nearly every profile ships inside the package, so the interesting half
+     * of this function — a profile that is genuinely absent — is otherwise reachable
+     * only through a network install in a unit test. The code that runs when a
+     * package leaves `dependencies` must be tested before that day, not on it.
+     */
+    profiles?: Profile[];
+    /** The fetch itself, forwarded to `ensureTooling`. 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/esm/core/install/prepare.js

@@ -0,0 +1,142 @@
+import { logger } from '../../utils/logger.js';
+import { clearToolPaths, packagePresent, registerToolPaths } from '../../utils/resolve-bin.js';
+import { ensureTooling } from './ensure.js';
+import { PROFILES, planProfiles } from './profiles.js';
+/**
+ * Whether a profile needs fetching at all, or already ships inside the package.
+ *
+ * This is the hinge the whole adaptive-install rollout turns on. Nearly every
+ * profile's packages sit in our `dependencies`, so it answers `true`, nothing is
+ * fetched, and a run is byte-for-byte the run it was before any of this existed.
+ * `pytypes` is the exception that already proves the other half works: `pyright`
+ * is a devDependency, so it reaches no client and is fetched on demand. 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 function profileSatisfiedLocally(profile) {
+    return profile.packages.every(pkg => 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).
+ */
+export 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.
+    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(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).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);
+    };
+    const toFetch = [];
+    for (const profile of wanted) {
+        // Bundled tooling is the answer to "where is it" for most profiles, 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"`. It means "never fetch",
+        // and `ensureTooling` enforces that — but only after checking the cache, so
+        // pre-warmed tooling 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;
+        }
+        toFetch.push(profile);
+    }
+    // One call, one directory, one lock — for the whole run rather than per profile.
+    // Profiles overlap heavily, and a tree each made the client download the shared
+    // half once per profile that named it (ticket 087).
+    //
+    // Reached only when something actually needs fetching, which is also what keeps
+    // the cache directory untouched otherwise: resolving it is not a read — it
+    // creates the directory and warns when the configured path is unwritable, and a
+    // container with a read-only home would print that on every single run.
+    if (toFetch.length > 0) {
+        const result = await ensureTooling(toFetch.map(profile => profile.name), {
+            cwd: opts.cwd,
+            version: opts.version,
+            install,
+            ...(opts.installer ? { installer: opts.installer } : {}),
+        });
+        if (result.status === 'failed' || result.status === 'skipped') {
+            for (const profile of toFetch)
+                miss(profile, result.reason);
+        }
+        else if (result.dir) {
+            dirs.push(result.dir);
+        }
+    }
+    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.warn(`[install]: ⚠️ tooling unavailable — these checks cannot run: ${names}`);
+        if (onMissing === 'error') {
+            logger.error('[install]: ❌ install.onMissingTool is "error" — the affected checks fail');
+        }
+        else {
+            logger.info('[install]:    Pre-warm the cache with: npx pr-checkmate install --all');
+        }
+    }
+    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.
+ */
+export function noTooling() {
+    return { unavailable: new Map(), dirs: [], fatal: false };
+}

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

@@ -0,0 +1,78 @@
+import type { PRCheckMateConfig } from '../../interfaces/index.js';
+import type { Language, LanguageUsage } from '../../utils/detect-language.js';
+/**
+ * A named bundle of tooling, and the checks that stop working without it.
+ *
+ * The package ships ~233 MB of tooling, and no repository needs all of it: a
+ * Python service pays for the whole JavaScript toolchain, a repository with
+ * Spellcheck switched off still pays for cspell. Profiles are how that stops —
+ * they name which slice of the tooling a given repository actually needs.
+ *
+ * `checks` is not documentation. It is what turns a failed install into an
+ * honest report: when a profile is missing, exactly those checks skip, with the
+ * reason, instead of quietly disappearing (the mistake of ticket 057).
+ */
+export interface Profile {
+    name: ProfileName;
+    /** Top-level packages installed for this profile. */
+    packages: string[];
+    /** Registry names of the checks that need it. */
+    checks: string[];
+    /**
+     * Languages that make this profile necessary. Absent for profiles driven by
+     * 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' | 'pytypes' | 'cpp' | 'go' | 'spellcheck' | 'markdown' | 'commitlint' | 'duplicate';
+/**
+ * The catalogue.
+ *
+ * Sizes in the comments are measured exclusive footprints — what leaves with the
+ * profile and is shared with nothing else (see ticket 069).
+ */
+export declare const PROFILES: Profile[];
+/** The profile a check belongs to, or `undefined` when it needs no extra tooling. */
+export declare function profileForCheck(check: string): Profile | undefined;
+/** Why a profile is (or is not) part of this run — the answer `doctor` prints. */
+export interface ProfileDecision {
+    profile: ProfileName;
+    required: boolean;
+    reason: string;
+}
+/**
+ * Decide which profiles this repository needs, and why.
+ *
+ * The two inputs are deliberately different in kind:
+ *
+ * - **Languages are counted in files, never in markers.** A Python service that
+ *   installed us through npm has a `package.json`, which is a JavaScript marker
+ *   — and downloading 152 MB of JavaScript tooling because of the file that
+ *   installed us would be the whole feature backfiring. `LanguageUsage.files`
+ *   exists for exactly this (ticket 068).
+ * - **Universal profiles are driven by enabled checks**, so `severity: {
+ *   "Spellcheck": "off" }` starts saving bandwidth instead of only a report row.
+ *
+ * @param usage Detected languages with their tracked file counts.
+ * @param config The client's config; `install.profiles` and `install.excludeProfiles`
+ *   have the last word, in that order — an explicit exclusion beats an explicit
+ *   request, because it is the one that can be a hard requirement (air-gapped,
+ *   licence policy, a runner that must not download a wasm binary).
+ * @returns One decision per profile, in catalogue order.
+ */
+export declare function planProfiles(usage: LanguageUsage[], config: PRCheckMateConfig): ProfileDecision[];

package/dist/esm/core/install/profiles.js

@@ -0,0 +1,192 @@
+/**
+ * The catalogue.
+ *
+ * Sizes in the comments are measured exclusive footprints — what leaves with the
+ * profile and is shared with nothing else (see ticket 069).
+ */
+export const PROFILES = [
+    {
+        // Always installed. Everything here backs a check that runs on any
+        // repository whatever it is written in, so there is nothing to decide.
+        name: 'core',
+        packages: ['execa', 'yaml', 'inquirer', 'gitleaks-secret-scanner-fixed'],
+        checks: ['Security Scan'],
+    },
+    {
+        // 152 MB, the largest by far, and the one a Python repository pays for
+        // today with nothing to show for it.
+        name: 'js',
+        packages: [
+            'typescript',
+            'eslint',
+            'eslint-config-prettier',
+            'eslint-plugin-import-x',
+            'eslint-plugin-jsdoc',
+            'eslint-plugin-prettier',
+            'eslint-plugin-sonarjs',
+            '@typescript-eslint/eslint-plugin',
+            '@typescript-eslint/parser',
+            'prettier',
+            'dpdm',
+            'knip',
+            'ts-unused-exports',
+            'license-checker-rseidelsohn',
+        ],
+        checks: [
+            'ESLint',
+            'Prettier',
+            'TypeScript',
+            'Circular Deps',
+            'Dependencies',
+            'Dead Code',
+            'License Check',
+        ],
+        languages: ['typescript', 'javascript'],
+    },
+    {
+        name: 'python',
+        packages: ['@astral-sh/ruff-wasm-nodejs'],
+        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
+        // one off should stop costing megabytes, not just a line in the report.
+        name: 'spellcheck',
+        packages: ['cspell'],
+        checks: ['Spellcheck'],
+    },
+    {
+        name: 'markdown',
+        packages: ['markdownlint'],
+        checks: ['Markdown'],
+    },
+    {
+        name: 'commitlint',
+        packages: ['@commitlint/cli', '@commitlint/config-conventional'],
+        checks: ['Commitlint'],
+    },
+    {
+        name: 'duplicate',
+        packages: ['jscpd'],
+        checks: ['Duplicate Code'],
+    },
+];
+/** The profile a check belongs to, or `undefined` when it needs no extra tooling. */
+export function profileForCheck(check) {
+    return PROFILES.find(p => p.checks.includes(check));
+}
+/**
+ * A check counts as enabled unless it is switched off.
+ *
+ * Deliberately asymmetric with how the runner selects checks: this must not
+ * import the registry (that would drag every check into the install path), and
+ * being wrong in the "enabled" direction only costs a download, while being
+ * wrong the other way silently removes a check. So anything not explicitly off
+ * is treated as on.
+ */
+function isCheckEnabled(check, config) {
+    return config.severity?.[check] !== 'off';
+}
+/**
+ * Decide which profiles this repository needs, and why.
+ *
+ * The two inputs are deliberately different in kind:
+ *
+ * - **Languages are counted in files, never in markers.** A Python service that
+ *   installed us through npm has a `package.json`, which is a JavaScript marker
+ *   — and downloading 152 MB of JavaScript tooling because of the file that
+ *   installed us would be the whole feature backfiring. `LanguageUsage.files`
+ *   exists for exactly this (ticket 068).
+ * - **Universal profiles are driven by enabled checks**, so `severity: {
+ *   "Spellcheck": "off" }` starts saving bandwidth instead of only a report row.
+ *
+ * @param usage Detected languages with their tracked file counts.
+ * @param config The client's config; `install.profiles` and `install.excludeProfiles`
+ *   have the last word, in that order — an explicit exclusion beats an explicit
+ *   request, because it is the one that can be a hard requirement (air-gapped,
+ *   licence policy, a runner that must not download a wasm binary).
+ * @returns One decision per profile, in catalogue order.
+ */
+export function planProfiles(usage, config) {
+    const install = config.install ?? {};
+    const minFiles = Math.max(1, install.minFilesPerLanguage ?? 1);
+    const requested = new Set(install.profiles ?? []);
+    const excluded = new Set(install.excludeProfiles ?? []);
+    return PROFILES.map(profile => {
+        const decision = decide(profile, usage, config, minFiles);
+        if (excluded.has(profile.name)) {
+            return {
+                profile: profile.name,
+                required: false,
+                reason: 'excluded by install.excludeProfiles',
+            };
+        }
+        if (!decision.required && requested.has(profile.name)) {
+            return { profile: profile.name, required: true, reason: 'requested by install.profiles' };
+        }
+        return { profile: profile.name, required: decision.required, reason: decision.reason };
+    });
+}
+/** The automatic half of {@link planProfiles}, before the client's overrides. */
+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);
+        if (found.length > 0) {
+            const detail = found.map(u => `${u.files} ${u.lang} file(s)`).join(', ');
+            return { required: true, reason: detail };
+        }
+        // Named separately from "no files": a marker with no source files is the
+        // OctoBot case — a `Cargo.toml` beside zero `.rs`. The language is real
+        // enough to run checks for; it is not real enough to download a toolchain.
+        const markerOnly = profile.languages.some(lang => usage.some(u => u.lang === lang));
+        return {
+            required: false,
+            reason: markerOnly
+                ? 'declared by a marker file but no source files tracked'
+                : 'no source files tracked',
+        };
+    }
+    const enabled = profile.checks.filter(check => isCheckEnabled(check, config));
+    return enabled.length > 0
+        ? { required: true, reason: `${enabled.join(', ')} enabled` }
+        : { required: false, reason: `${profile.checks.join(', ')} switched off` };
+}

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

@@ -0,0 +1,41 @@
+import type { CheckContext } from '../types.js';
+/** 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 {};