pr-checkmate 3.0.4 → 3.1.0

package/dist/esm/core/commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CLI vocabulary, kept out of `cli.ts` so it can be imported without side
+ * effects: that module is an executable entry point — it parses `process.argv`
+ * and calls `process.exit` at import time, so anything importing it to read
+ * these tables would run the CLI instead.
+ *
+ * Separating them is what lets `commands.test.ts` assert the invariant that
+ * matters here: every command must resolve to a check that actually exists.
+ * A command pointing at a name no longer in the registry does not error — the
+ * `only` filter simply matches nothing, every check is filtered out, and the run
+ * reports success having verified nothing at all.
+ */
+/** Maps short CLI command names to their registry check names. */
+export declare const COMMAND_TO_CHECK: Record<string, string>;
+/**
+ * Commands that run the whole pipeline (or no pipeline at all) and take no siblings.
+ *
+ * The three install commands are here rather than in {@link COMMAND_TO_CHECK}
+ * because they run no checks at all: they manage the tooling the checks need.
+ * `doctor` in particular is the answer to "why did my typecheck not run" once
+ * tooling is fetched on demand — a question that must have a command behind it
+ * and not a reading of our source.
+ */
+export declare const TOOLING_COMMANDS: readonly string[];
+export declare const STANDALONE_COMMANDS: readonly string[];
+/** Flags accepted anywhere on the command line, with what each one means. */
+export declare const FLAGS: Record<string, string>;

package/dist/esm/core/commands.js

@@ -0,0 +1,89 @@
+/**
+ * CLI vocabulary, kept out of `cli.ts` so it can be imported without side
+ * effects: that module is an executable entry point — it parses `process.argv`
+ * and calls `process.exit` at import time, so anything importing it to read
+ * these tables would run the CLI instead.
+ *
+ * Separating them is what lets `commands.test.ts` assert the invariant that
+ * matters here: every command must resolve to a check that actually exists.
+ * A command pointing at a name no longer in the registry does not error — the
+ * `only` filter simply matches nothing, every check is filtered out, and the run
+ * reports success having verified nothing at all.
+ */
+/** Maps short CLI command names to their registry check names. */
+export const COMMAND_TO_CHECK = {
+    // Every check that can fail a run is reachable on its own, so "why does this
+    // block me" is answered by running that one check instead of the whole suite.
+    'merge-conflict': 'Merge Conflict',
+    lint: 'ESLint',
+    deps: 'Dependencies',
+    dependencies: 'Dependencies',
+    'npm-audit': 'NPM Audit',
+    prettier: 'Prettier',
+    spellcheck: 'Spellcheck',
+    security: 'Security Scan',
+    circular: 'Circular Deps',
+    license: 'License Check',
+    'pr-size': 'PR Size',
+    'pr-title': 'PR Title',
+    outdated: 'Outdated Deps',
+    markdown: 'Markdown',
+    'yaml-lint': 'YAML Lint',
+    symlinks: 'Broken Symlinks',
+    'package-size': 'Package Size',
+    shellcheck: 'ShellCheck',
+    typecheck: 'TypeScript',
+    'diff-smell': 'Diff Smells',
+    'diff-security': 'Diff Security',
+    'workflow-security': 'Workflow Security',
+    'custom-rules': 'Custom Rules',
+    'banned-imports': 'Banned Imports',
+    'license-header': 'License Header',
+    'config-validation': 'Config Validation',
+    'dockerfile-security': 'Dockerfile Security',
+    'case-collision': 'Case Collision',
+    'vuln-scan': 'Vuln Scan',
+    'leftover-debug': 'Leftover Debug',
+    'lockfile-drift': 'Lockfile Drift',
+    'large-files': 'Large Files',
+    'todo-fixme': 'TODO/FIXME',
+    'missing-tests': 'Missing Tests',
+    coverage: 'Coverage',
+    'migration-safety': 'Migration Safety',
+    'sensitive-files': 'Sensitive Files',
+    'pr-body': 'PR Body',
+    duplicate: 'Duplicate Code',
+    commitlint: 'Commitlint',
+    'cpp-format': 'C++ Format',
+    'python-lint': 'Ruff Lint',
+    'python-format': 'Ruff Format',
+    'python-typecheck': 'Python Types',
+    'go-lint': 'Go Vet',
+    'go-format': 'Go Format',
+    'rust-lint': 'Clippy',
+    'rust-format': 'Rustfmt',
+    'csharp-format': 'C# Format',
+    'ruby-lint': 'RuboCop',
+    'php-format': 'PHP CS Fixer',
+};
+/**
+ * Commands that run the whole pipeline (or no pipeline at all) and take no siblings.
+ *
+ * The three install commands are here rather than in {@link COMMAND_TO_CHECK}
+ * because they run no checks at all: they manage the tooling the checks need.
+ * `doctor` in particular is the answer to "why did my typecheck not run" once
+ * tooling is fetched on demand — a question that must have a command behind it
+ * and not a reading of our source.
+ */
+export const TOOLING_COMMANDS = ['install', 'doctor', 'cache-prune'];
+export const STANDALONE_COMMANDS = [
+    'init',
+    'all',
+    'precommit',
+    ...TOOLING_COMMANDS,
+];
+/** Flags accepted anywhere on the command line, with what each one means. */
+export const FLAGS = {
+    '--full': 'review every tracked file instead of the diff (the default outside CI)',
+    '--all': 'with "install": fetch every profile, not only the ones this repository needs',
+};

package/dist/esm/core/context.d.ts

@@ -0,0 +1,62 @@
+import type { CheckContext, RunOptions } from './types.js';
+/**
+ * What a run should look at, before any git call is made. Separated from
+ * {@link resolveDiffRange} so the precedence rules are a pure function of the
+ * options and the environment — the part worth pinning with tests.
+ *
+ * - `full` — every tracked file. Checks fall back to `git ls-files` when the range
+ *   is undefined, so this is expressed by resolving to no SHAs at all.
+ * - `staged` — index vs HEAD (pre-commit).
+ * - `explicit` — SHAs the caller supplied.
+ * - `github-event` — base SHA from the pull_request event payload.
+ * - `ref` — diff against a named ref (a PR's destination branch, or `HEAD^`).
+ */
+type RangePlan = {
+    kind: 'full';
+    reason: string;
+} | {
+    kind: 'staged';
+} | {
+    kind: 'explicit';
+    baseSha?: string;
+    headSha?: string;
+} | {
+    kind: 'github-event';
+} | {
+    kind: 'branch';
+} | {
+    kind: 'ref';
+    ref: string;
+    reason: string;
+};
+/**
+ * Decide what to look at. Order matters and is the contract:
+ *
+ * 1. `full` wins over everything — an explicit "check all of it" must not be
+ *    quietly narrowed by a CI variable that happens to be set.
+ * 2. `staged`, then caller-supplied SHAs.
+ * 3. The CI platform's PR context (GitHub event payload, Bitbucket destination
+ *    branch) — a gate exists to judge the diff.
+ * 4. A CI build with no PR context still diffs `HEAD^`: it is a push/branch build,
+ *    and delta is why CI runs are fast.
+ * 5. Anything else is a human at a terminal, working on a branch → review what the
+ *    branch changed, i.e. everything since it diverged from the default branch.
+ *    That is the same set of changes a pull request would show, which is what
+ *    someone running the tool before opening one is asking about.
+ *
+ *    `HEAD^` was tried here once and was wrong for a different reason: it judged
+ *    only the last commit, so a `debugger` committed earlier on the branch passed.
+ *    The merge base has neither problem — it covers every commit on the branch —
+ *    and on the default branch itself, where there is nothing to diverge from,
+ *    {@link resolveDiffRange} falls back to a full scan.
+ *
+ * @param opts Run options as passed to `runChecks`.
+ * @param env Environment to read CI markers from. Defaults to the current process.
+ */
+export declare function planDiffRange(opts: RunOptions, env?: NodeJS.ProcessEnv): RangePlan;
+/**
+ * Assemble the shared CheckContext once per run. Language detection is skipped
+ * when the caller supplies `languages` (e.g. PRValidator passes its ProjectType).
+ */
+export declare function buildContext(opts?: RunOptions): Promise<CheckContext>;
+export {};

package/dist/esm/core/context.js

@@ -0,0 +1,241 @@
+import fs from 'node:fs';
+import { loadProjectConfig } from '../config/loader.js';
+import { detectLanguageUsage } from '../utils/detect-language.js';
+import { execa } from '../utils/execa.js';
+import { isCiEnvironment, logger, resolveGitRef } from '../utils/index.js';
+/**
+ * Decide what to look at. Order matters and is the contract:
+ *
+ * 1. `full` wins over everything — an explicit "check all of it" must not be
+ *    quietly narrowed by a CI variable that happens to be set.
+ * 2. `staged`, then caller-supplied SHAs.
+ * 3. The CI platform's PR context (GitHub event payload, Bitbucket destination
+ *    branch) — a gate exists to judge the diff.
+ * 4. A CI build with no PR context still diffs `HEAD^`: it is a push/branch build,
+ *    and delta is why CI runs are fast.
+ * 5. Anything else is a human at a terminal, working on a branch → review what the
+ *    branch changed, i.e. everything since it diverged from the default branch.
+ *    That is the same set of changes a pull request would show, which is what
+ *    someone running the tool before opening one is asking about.
+ *
+ *    `HEAD^` was tried here once and was wrong for a different reason: it judged
+ *    only the last commit, so a `debugger` committed earlier on the branch passed.
+ *    The merge base has neither problem — it covers every commit on the branch —
+ *    and on the default branch itself, where there is nothing to diverge from,
+ *    {@link resolveDiffRange} falls back to a full scan.
+ *
+ * @param opts Run options as passed to `runChecks`.
+ * @param env Environment to read CI markers from. Defaults to the current process.
+ */
+export function planDiffRange(opts, env = process.env) {
+    if (opts.full)
+        return { kind: 'full', reason: 'requested' };
+    if (opts.staged)
+        return { kind: 'staged' };
+    if (opts.baseSha || opts.headSha) {
+        return { kind: 'explicit', baseSha: opts.baseSha, headSha: opts.headSha };
+    }
+    if (env.GITHUB_EVENT_NAME === 'pull_request' && env.GITHUB_EVENT_PATH) {
+        return { kind: 'github-event' };
+    }
+    if (env.BITBUCKET_PR_DESTINATION_BRANCH) {
+        return {
+            kind: 'ref',
+            ref: `origin/${env.BITBUCKET_PR_DESTINATION_BRANCH}`,
+            reason: 'PR build',
+        };
+    }
+    if (isCiEnvironment(env))
+        return { kind: 'ref', ref: 'HEAD^', reason: 'CI build, no PR context' };
+    return { kind: 'branch' };
+}
+/** A full scan the caller or the environment asked for, not one we fell back to. */
+const intended = (reason) => ({ kind: 'full', reason, degraded: false });
+/**
+ * A full scan we ended up with because a diff range could not be built. The
+ * distinction matters: the delta-only checks drop out either way, but here that
+ * is a symptom (shallow clone, missing base) rather than the intent — and it is
+ * the case worth telling the client about, because it silently removes most of
+ * the security surface.
+ */
+const degraded = (reason) => ({ kind: 'full', reason, degraded: true });
+/**
+ * Carry out a {@link RangePlan}. Every path that cannot produce a usable base
+ * commit returns no SHAs, which the checks read as "scan everything" — degrading
+ * to a full scan is always safer than diffing against a ref that isn't there and
+ * silently reviewing nothing.
+ *
+ * @returns The resolved range, plus the scope that produced it.
+ */
+async function resolveDiffRange(cwd, opts) {
+    const plan = planDiffRange(opts, process.env);
+    if (plan.kind === 'full')
+        return { scope: intended(plan.reason) };
+    // Pre-commit mode: diff HEAD against the current index. `git write-tree`
+    // materialises the staged index as a real tree object, so every check that
+    // diffs baseSha..headSha sees exactly the staged changes — no per-check code.
+    if (plan.kind === 'staged') {
+        try {
+            const head = (await execa('git', ['rev-parse', 'HEAD'], { cwd })).stdout.trim();
+            const tree = (await execa('git', ['write-tree'], { cwd })).stdout.trim();
+            return { baseSha: head, headSha: tree, scope: { kind: 'staged', degraded: false } };
+        }
+        catch {
+            return { scope: degraded('no staged range') };
+        }
+    }
+    if (plan.kind === 'explicit') {
+        return {
+            baseSha: plan.baseSha,
+            headSha: plan.headSha,
+            scope: { kind: 'delta', reason: 'explicit', degraded: false },
+        };
+    }
+    let headSha;
+    try {
+        const { stdout } = await execa('git', ['rev-parse', 'HEAD'], { cwd });
+        headSha = stdout.trim();
+    }
+    catch {
+        return { scope: degraded('no HEAD') };
+    }
+    // GitHub Actions: the PR event payload carries the base branch SHA. Read it
+    // directly so delta works without relying on any client-set variable
+    // (GITHUB_EVENT_* are injected by the runner).
+    if (plan.kind === 'github-event') {
+        try {
+            const event = JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf-8'));
+            const eventBase = event?.pull_request?.base?.sha;
+            // Only use it if the commit is actually present in this clone; otherwise
+            // fall through so a shallow clone degrades to a full scan, not 0 files.
+            const baseSha = eventBase ? await resolveGitRef(cwd, eventBase) : undefined;
+            if (baseSha) {
+                return { baseSha, headSha, scope: { kind: 'delta', reason: 'PR event', degraded: false } };
+            }
+        }
+        catch {
+            // Malformed/unreadable event — fall through to a full scan below.
+        }
+        return { headSha, scope: degraded('PR base unavailable') };
+    }
+    if (plan.kind === 'branch')
+        return resolveBranchRange(cwd, headSha);
+    const baseSha = await resolveGitRef(cwd, plan.ref);
+    if (!baseSha)
+        return { headSha, scope: degraded(`${plan.ref} unresolvable`) };
+    return {
+        baseSha,
+        headSha,
+        scope: { kind: 'delta', reason: `${plan.ref}, ${plan.reason}`, degraded: false },
+    };
+}
+/** Branches a repository's trunk is normally called, most likely first. */
+const DEFAULT_BRANCHES = ['main', 'master', 'develop'];
+/**
+ * Where this branch diverged from the trunk, or nothing when it has not.
+ *
+ * Prefers `origin/HEAD` — the remote's own answer to "what is the default
+ * branch" — and falls back to the usual names, local or remote. Returns
+ * `undefined` when no trunk is found or when HEAD is already on it, which the
+ * caller turns into a full scan: on the trunk there is no branch to review.
+ */
+async function findMergeBase(cwd, headSha) {
+    const candidates = ['origin/HEAD'];
+    for (const name of DEFAULT_BRANCHES)
+        candidates.push(`origin/${name}`, name);
+    for (const candidate of candidates) {
+        const ref = await resolveGitRef(cwd, candidate);
+        // A candidate that resolves to HEAD is the branch we are on, not a base.
+        if (!ref || ref === headSha)
+            continue;
+        const { stdout } = await execa('git', ['merge-base', headSha, ref], { cwd, reject: false });
+        const base = stdout.trim();
+        // An unrelated history has no merge base, and a base equal to HEAD means the
+        // branch is behind rather than ahead — neither describes local changes.
+        if (base && base !== headSha)
+            return base;
+    }
+    return undefined;
+}
+/**
+ * Local run on a branch: review what the branch changed.
+ *
+ * On the trunk itself there is nothing to diff against, so this degrades to a
+ * full scan — deliberately not marked `degraded`, because it is the expected
+ * answer there rather than a configuration problem worth warning about.
+ */
+async function resolveBranchRange(cwd, headSha) {
+    const baseSha = await findMergeBase(cwd, headSha);
+    if (!baseSha)
+        return { headSha, scope: intended('no branch base — on the default branch?') };
+    return {
+        baseSha,
+        headSha,
+        scope: { kind: 'delta', reason: 'branch changes', degraded: false },
+    };
+}
+/**
+ * Assemble the shared CheckContext once per run. Language detection is skipped
+ * when the caller supplies `languages` (e.g. PRValidator passes its ProjectType).
+ */
+export async function buildContext(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const config = opts.config ?? loadProjectConfig();
+    // Detection reads the client's `ignoreDirs` from the config already loaded here,
+    // rather than calling getIgnoredDirs() — that one resolves against process.cwd(),
+    // which is not necessarily the `cwd` under review.
+    applyLogConfig(config);
+    // 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 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
+    // that reviewed the repository both just print passes.
+    logger.info(`[buildContext]: cwd=${cwd} languages=[${languages.join(', ') || 'none'}] write=${opts.write ?? false} scope=${describeScope(scope)}`);
+    return {
+        cwd,
+        languages,
+        usage,
+        config,
+        write: opts.write ?? false,
+        baseSha,
+        headSha,
+        scope,
+        cache: new Map(),
+    };
+}
+/**
+ * Human-readable one-liner for a scope, e.g. `full (PR base unavailable)`.
+ *
+ * Deliberately not exported: `buildContext` is the only caller, and the scope it
+ * describes already travels on the context for anyone who wants to phrase it
+ * differently. An `export` here would only be API surface Dead Code reports.
+ */
+function describeScope(scope) {
+    return scope.reason ? `${scope.kind} (${scope.reason})` : scope.kind;
+}
+/**
+ * Apply the client's `log` block, with environment variables taking precedence.
+ *
+ * Env wins because the config file is committed and the environment is not: a
+ * one-off `PR_CHECKMATE_LOG_LEVEL=debug` to diagnose a CI run should not require
+ * editing — and later reverting — a tracked file.
+ */
+function applyLogConfig(config) {
+    const log = config.log ?? {};
+    const level = process.env.PR_CHECKMATE_LOG_LEVEL ?? log.level;
+    const format = process.env.PR_CHECKMATE_LOG_FORMAT ?? log.format;
+    logger.configure({
+        ...(level ? { level } : {}),
+        ...(format ? { format } : {}),
+        ...(log.color ? { color: log.color } : {}),
+        ...(log.timestamps !== undefined ? { timestamps: log.timestamps } : {}),
+        ...(log.stderrLevels ? { stderrLevels: log.stderrLevels } : {}),
+    });
+}

package/dist/esm/core/index.d.ts

@@ -0,0 +1,4 @@
+export { runChecks } from './run-checks.js';
+export { buildContext } from './context.js';
+export { REGISTRY } from './registry.js';
+export * from './types.js';

package/dist/esm/core/index.js

@@ -0,0 +1,4 @@
+export { runChecks } from './run-checks.js';
+export { buildContext } from './context.js';
+export { REGISTRY } from './registry.js';
+export * from './types.js';

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

@@ -0,0 +1,58 @@
+/** Where fetched tooling lives, and why it ended up there. */
+export interface CacheLocation {
+    dir: string;
+    /** `false` when the configured location was unusable and this is a fallback. */
+    preferred: boolean;
+    reason?: string;
+}
+/**
+ * Expand a leading `~`.
+ *
+ * Config files are written by hand, `~/.cache/pr-checkmate` is what a person
+ * writes, and nothing in Node expands it — the directory would be created
+ * literally, as a folder named `~`, in whatever the working directory happened
+ * to be.
+ */
+export declare function expandHome(dir: string, home?: string): string;
+/**
+ * Resolve the cache directory, falling back rather than failing.
+ *
+ * Every candidate below is a real environment: containers without `HOME`, CI
+ * images with a read-only home, and runners where only the temp directory is
+ * writable. A tool that refuses to work in any of them is a tool that fails on
+ * CI for reasons the client cannot see.
+ *
+ * @param version The pr-checkmate version, kept in the path so two projects on
+ *   different versions never share fetched tooling.
+ * @param configured `install.cacheDir`, if the client set one.
+ */
+export declare function resolveCacheDir(version: string, configured?: string, env?: NodeJS.ProcessEnv): CacheLocation | null;
+/**
+ * Where fetched tooling is installed — one tree for the whole run, not one per profile.
+ *
+ * A directory per profile left npm nothing to deduplicate, and the profiles
+ * overlap heavily: `commitlint` and `js` share 30 MB, so two trees fetched both
+ * copies. Measured on a JavaScript repository, per-profile directories came to
+ * 267 MB where a single merged tree costs 213 (ticket 087).
+ *
+ * The name is deliberately not derived from which profiles are inside. What is
+ * installed is recorded in the directory's own stamp and checked as a superset,
+ * so a cache warmed by `install --all` serves every narrower run — a path keyed
+ * by the profile set would miss on the first one.
+ */
+export declare function toolingDir(cacheDir: string): string;
+/**
+ * Where a single profile's tooling used to be installed.
+ *
+ * Kept only so `cache prune` can still recognise and remove the directories left
+ * by versions that used the per-profile layout.
+ */
+export declare function profileDir(cacheDir: string, profile: string): string;
+/**
+ * Profile directories left behind by other versions of pr-checkmate.
+ *
+ * Nothing removes these automatically: an upgrade must not delete tooling a
+ * concurrently running older version is in the middle of using. `cache prune`
+ * is the deliberate, separate act.
+ */
+export declare function stalePaths(version: string, configured?: string): string[];

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

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { logger } from '../../utils/logger.js';
+/**
+ * Expand a leading `~`.
+ *
+ * Config files are written by hand, `~/.cache/pr-checkmate` is what a person
+ * writes, and nothing in Node expands it — the directory would be created
+ * literally, as a folder named `~`, in whatever the working directory happened
+ * to be.
+ */
+export function expandHome(dir, home = os.homedir()) {
+    if (dir === '~')
+        return home;
+    return dir.startsWith('~/') ? path.join(home, dir.slice(2)) : dir;
+}
+/** A directory we can actually write to. */
+function writable(dir) {
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        // 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.
+        fs.accessSync(dir, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        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 {
+        fs.accessSync(dir, fs.constants.R_OK | fs.constants.X_OK);
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the cache directory, falling back rather than failing.
+ *
+ * Every candidate below is a real environment: containers without `HOME`, CI
+ * images with a read-only home, and runners where only the temp directory is
+ * writable. A tool that refuses to work in any of them is a tool that fails on
+ * CI for reasons the client cannot see.
+ *
+ * @param version The pr-checkmate version, kept in the path so two projects on
+ *   different versions never share fetched tooling.
+ * @param configured `install.cacheDir`, if the client set one.
+ */
+export function resolveCacheDir(version, configured, env = process.env) {
+    const explicit = env.PR_CHECKMATE_CACHE_DIR ?? configured;
+    const candidates = [];
+    if (explicit)
+        candidates.push({ dir: expandHome(explicit), reason: 'configured' });
+    // `homedir()` on a container without HOME returns something like `/` — hence
+    // the write check rather than a bare existence test.
+    candidates.push({ dir: path.join(os.homedir(), '.cache', 'pr-checkmate'), reason: 'home cache' });
+    candidates.push({ dir: path.join(os.tmpdir(), 'pr-checkmate-cache'), reason: 'temp directory' });
+    for (const [index, candidate] of candidates.entries()) {
+        const dir = path.join(candidate.dir, version);
+        if (writable(dir)) {
+            if (index > 0) {
+                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 null;
+}
+/**
+ * Where fetched tooling is installed — one tree for the whole run, not one per profile.
+ *
+ * A directory per profile left npm nothing to deduplicate, and the profiles
+ * overlap heavily: `commitlint` and `js` share 30 MB, so two trees fetched both
+ * copies. Measured on a JavaScript repository, per-profile directories came to
+ * 267 MB where a single merged tree costs 213 (ticket 087).
+ *
+ * The name is deliberately not derived from which profiles are inside. What is
+ * installed is recorded in the directory's own stamp and checked as a superset,
+ * so a cache warmed by `install --all` serves every narrower run — a path keyed
+ * by the profile set would miss on the first one.
+ */
+export function toolingDir(cacheDir) {
+    return path.join(cacheDir, 'tooling');
+}
+/**
+ * Where a single profile's tooling used to be installed.
+ *
+ * Kept only so `cache prune` can still recognise and remove the directories left
+ * by versions that used the per-profile layout.
+ */
+export function profileDir(cacheDir, profile) {
+    return path.join(cacheDir, profile);
+}
+/**
+ * Profile directories left behind by other versions of pr-checkmate.
+ *
+ * Nothing removes these automatically: an upgrade must not delete tooling a
+ * concurrently running older version is in the middle of using. `cache prune`
+ * is the deliberate, separate act.
+ */
+export function stalePaths(version, configured) {
+    const location = resolveCacheDir(version, configured);
+    if (!location)
+        return [];
+    const root = path.dirname(location.dir);
+    try {
+        return fs
+            .readdirSync(root, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && entry.name !== version)
+            .map(entry => path.join(root, entry.name));
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,35 @@
+import { type LanguageUsage } from '../../utils/detect-language.js';
+import { packageVersion } from '../../utils/package-version.js';
+import { type EnsureResult } from './ensure.js';
+import { type ProfileDecision } from './profiles.js';
+export { packageVersion };
+/**
+ * Everything the install layer knows about this repository, in one shot.
+ *
+ * `usage` is a parameter rather than always detected here so a caller that
+ * already has it — `doctor` prints it — does not scan the repository twice and
+ * log two contradictory-looking detection lines for one command.
+ */
+export declare function planInstall(cwd?: string, usage?: LanguageUsage[]): Promise<{
+    decisions: ProfileDecision[];
+    cacheDir: string | null;
+}>;
+/**
+ * Fetch every profile this repository needs.
+ *
+ * Shared by the `install` command and by the run itself, so a client who never
+ * runs `install` gets the same result lazily. `all` is what a container build or
+ * an air-gapped mirror wants: everything, regardless of what this repository
+ * happens to contain.
+ */
+export declare function installProfiles(cwd?: string, all?: boolean): Promise<EnsureResult[]>;
+/**
+ * Explain what this repository needs, what it has, and what is missing — and why.
+ *
+ * The command exists because adaptive installation makes "why did my typecheck
+ * not run" a routine question, and the answer must be a command rather than a
+ * reading of our source.
+ */
+export declare function runDoctor(cwd?: string): Promise<void>;
+/** Remove cached tooling belonging to other versions of pr-checkmate. */
+export declare function pruneCache(): void;