pr-checkmate 1.23.23 → 2.0.0

package/dist/core/context.js

@@ -20,9 +20,16 @@ const execa_1 = require("../utils/execa");
  *    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 → full scan. `HEAD^` used to be the
- *    fallback here, which meant a local `pr-checkmate all` judged only the last
- *    commit and could report a clean project with a `debugger` committed earlier.
+ * 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.
@@ -47,20 +54,30 @@ function planDiffRange(opts, env = process.env) {
     }
     if ((0, utils_1.isCiEnvironment)(env))
         return { kind: 'ref', ref: 'HEAD^', reason: 'CI build, no PR context' };
-    return { kind: 'full', reason: 'no CI detected' };
+    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 a label for the log line.
+ * @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: `full (${plan.reason})` };
+        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.
@@ -68,14 +85,18 @@ async function resolveDiffRange(cwd, opts) {
         try {
             const head = (await (0, execa_1.execa)('git', ['rev-parse', 'HEAD'], { cwd })).stdout.trim();
             const tree = (await (0, execa_1.execa)('git', ['write-tree'], { cwd })).stdout.trim();
-            return { baseSha: head, headSha: tree, scope: 'staged' };
+            return { baseSha: head, headSha: tree, scope: { kind: 'staged', degraded: false } };
         }
         catch {
-            return { scope: 'full (no staged range)' };
+            return { scope: degraded('no staged range') };
         }
     }
     if (plan.kind === 'explicit') {
-        return { baseSha: plan.baseSha, headSha: plan.headSha, scope: 'delta (explicit)' };
+        return {
+            baseSha: plan.baseSha,
+            headSha: plan.headSha,
+            scope: { kind: 'delta', reason: 'explicit', degraded: false },
+        };
     }
     let headSha;
     try {
@@ -83,7 +104,7 @@ async function resolveDiffRange(cwd, opts) {
         headSha = stdout.trim();
     }
     catch {
-        return { scope: 'full (no HEAD)' };
+        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
@@ -95,19 +116,69 @@ async function resolveDiffRange(cwd, opts) {
             // 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 (0, utils_1.resolveGitRef)(cwd, eventBase) : undefined;
-            if (baseSha)
-                return { baseSha, headSha, scope: 'delta (PR event)' };
+            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: 'full (PR base unavailable)' };
+        return { headSha, scope: degraded('PR base unavailable') };
     }
+    if (plan.kind === 'branch')
+        return resolveBranchRange(cwd, headSha);
     const baseSha = await (0, utils_1.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 (0, utils_1.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 (0, execa_1.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: baseSha ? `delta (${plan.ref}, ${plan.reason})` : `full (${plan.ref} unresolvable)`,
+        scope: { kind: 'delta', reason: 'branch changes', degraded: false },
     };
 }
 /**
@@ -120,12 +191,13 @@ async function buildContext(opts = {}) {
     // 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.
-    const languages = opts.languages ?? (await (0, detect_language_1.detectLanguages)(cwd, config.ignoreDirs));
+    applyLogConfig(config);
+    const languages = opts.languages ?? (await (0, detect_language_1.detectLanguages)(cwd, config.ignoreDirs, config.detect));
     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.
-    utils_1.logger.info(`[buildContext]: cwd=${cwd} languages=[${languages.join(', ') || 'none'}] write=${opts.write ?? false} scope=${scope}`);
+    utils_1.logger.info(`[buildContext]: cwd=${cwd} languages=[${languages.join(', ') || 'none'}] write=${opts.write ?? false} scope=${describeScope(scope)}`);
     return {
         cwd,
         languages,
@@ -133,6 +205,36 @@ async function buildContext(opts = {}) {
         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;
+    utils_1.logger.configure({
+        ...(level ? { level } : {}),
+        ...(format ? { format } : {}),
+        ...(log.color ? { color: log.color } : {}),
+        ...(log.timestamps !== undefined ? { timestamps: log.timestamps } : {}),
+        ...(log.stderrLevels ? { stderrLevels: log.stderrLevels } : {}),
+    });
+}

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

@@ -0,0 +1,39 @@
+/** 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 a single profile's tooling is installed. */
+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/core/install/cache.js

@@ -0,0 +1,99 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandHome = expandHome;
+exports.resolveCacheDir = resolveCacheDir;
+exports.profileDir = profileDir;
+exports.stalePaths = stalePaths;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("../../utils/logger");
+/**
+ * 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.
+ */
+function expandHome(dir, home = node_os_1.default.homedir()) {
+    if (dir === '~')
+        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) {
+    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.
+        node_fs_1.default.accessSync(dir, node_fs_1.default.constants.W_OK);
+        return true;
+    }
+    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.
+ */
+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: node_path_1.default.join(node_os_1.default.homedir(), '.cache', 'pr-checkmate'), reason: 'home cache' });
+    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.`);
+        }
+        return { dir, preferred: index === 0, reason: candidate.reason };
+    }
+    return null;
+}
+/** Where a single profile's tooling is installed. */
+function profileDir(cacheDir, profile) {
+    return node_path_1.default.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.
+ */
+function stalePaths(version, configured) {
+    const location = resolveCacheDir(version, configured);
+    if (!location)
+        return [];
+    const root = node_path_1.default.dirname(location.dir);
+    try {
+        return node_fs_1.default
+            .readdirSync(root, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && entry.name !== version)
+            .map(entry => node_path_1.default.join(root, entry.name));
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,35 @@
+import { type LanguageUsage } from '../../utils/detect-language';
+import { type EnsureResult } from './ensure';
+import { type ProfileDecision } from './profiles';
+/** Our own version, read from the package manifest that ships with us. */
+export declare function packageVersion(): string;
+/**
+ * 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;

package/dist/core/install/doctor.js

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageVersion = packageVersion;
+exports.planInstall = planInstall;
+exports.installProfiles = installProfiles;
+exports.runDoctor = runDoctor;
+exports.pruneCache = pruneCache;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const loader_1 = require("../../config/loader");
+const detect_language_1 = require("../../utils/detect-language");
+const logger_1 = require("../../utils/logger");
+const cache_1 = require("./cache");
+const ensure_1 = require("./ensure");
+const profiles_1 = require("./profiles");
+/** Our own version, read from the package manifest that ships with us. */
+function packageVersion() {
+    try {
+        const manifest = node_path_1.default.resolve(__dirname, '../../..', 'package.json');
+        return JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf-8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * 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.
+ */
+async function planInstall(cwd = process.cwd(), usage) {
+    const config = (0, loader_1.loadProjectConfig)();
+    const detected = usage ?? (await (0, detect_language_1.detectLanguageUsage)(cwd, config.ignoreDirs, config.detect));
+    const location = (0, cache_1.resolveCacheDir)(packageVersion(), config.install?.cacheDir);
+    return { decisions: (0, profiles_1.planProfiles)(detected, config), cacheDir: location?.dir ?? null };
+}
+/** Whether a profile's tooling is present in the cache right now. */
+function installedProfiles(cacheDir) {
+    if (!cacheDir)
+        return new Set();
+    return new Set(profiles_1.PROFILES.filter(p => node_fs_1.default.existsSync(node_path_1.default.join((0, cache_1.profileDir)(cacheDir, p.name), 'node_modules'))).map(p => p.name));
+}
+/**
+ * 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.
+ */
+async function installProfiles(cwd = process.cwd(), all = false) {
+    const config = (0, loader_1.loadProjectConfig)();
+    const install = config.install ?? {};
+    const { decisions } = await planInstall(cwd);
+    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);
+        const blocked = profile?.packages.filter(pkg => denied.has(pkg)) ?? [];
+        if (blocked.length === 0)
+            return true;
+        logger_1.logger.info(`[install]: profile "${name}" skipped — install.deny lists ${blocked.join(', ')}`);
+        return false;
+    });
+    const results = [];
+    // Sequential on purpose. Parallel installs of profiles that share hundreds of
+    // packages fight over npm's cache and gain nothing; the wall-clock cost lands
+    // once, on a cold cache, and clarity of the log matters more there.
+    for (const profile of wanted) {
+        results.push(await (0, ensure_1.ensureProfile)(profile, { cwd, version: packageVersion(), install }));
+    }
+    return results;
+}
+/**
+ * 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.
+ */
+async function runDoctor(cwd = process.cwd()) {
+    const config = (0, loader_1.loadProjectConfig)();
+    const usage = await (0, detect_language_1.detectLanguageUsage)(cwd, config.ignoreDirs, config.detect);
+    const { decisions, cacheDir } = await planInstall(cwd, usage);
+    const present = installedProfiles(cacheDir);
+    const lines = [];
+    lines.push('PR CheckMate — install doctor');
+    lines.push('');
+    lines.push(`  version    ${packageVersion()}`);
+    lines.push(`  repository ${cwd}`);
+    lines.push(`  cache      ${cacheDir ?? 'unavailable (no writable directory)'}`);
+    lines.push(`  strategy   ${config.install?.strategy ?? 'adaptive'}`);
+    lines.push('');
+    lines.push('  Languages');
+    if (usage.length === 0)
+        lines.push('    none detected');
+    for (const u of usage) {
+        // The distinction that decides downloads: a marker declares a language, a
+        // file proves it. Only the second is worth a toolchain.
+        const evidence = u.files > 0 ? `${u.files} file(s)` : 'marker file only';
+        lines.push(`    ${u.lang.padEnd(12)} ${evidence}`);
+    }
+    lines.push('');
+    lines.push('  Profiles');
+    for (const decision of decisions) {
+        const state = decision.required ? (present.has(decision.profile) ? '✅' : '⬇️ ') : '—';
+        lines.push(`    ${state} ${decision.profile.padEnd(12)} ${decision.reason}`);
+    }
+    const missing = decisions.filter(d => d.required && !present.has(d.profile));
+    if (missing.length > 0) {
+        lines.push('');
+        lines.push(`  ${missing.length} profile(s) not installed yet. They are fetched on the next`);
+        lines.push('  run, or now with: npx pr-checkmate install');
+    }
+    const stale = (0, cache_1.stalePaths)(packageVersion(), config.install?.cacheDir);
+    if (stale.length > 0) {
+        lines.push('');
+        lines.push(`  ${stale.length} directory(ies) from other versions: npx pr-checkmate cache-prune`);
+    }
+    logger_1.logger.print(lines.join('\n'));
+}
+/** Remove cached tooling belonging to other versions of pr-checkmate. */
+function pruneCache() {
+    const config = (0, loader_1.loadProjectConfig)();
+    const stale = (0, cache_1.stalePaths)(packageVersion(), config.install?.cacheDir);
+    if (stale.length === 0) {
+        logger_1.logger.print('Nothing to prune — no tooling from other versions is cached.');
+        return;
+    }
+    for (const dir of stale) {
+        try {
+            node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+            logger_1.logger.print(`removed ${dir}`);
+        }
+        catch (err) {
+            // Another version may be running right now; refusing to delete its
+            // tooling is the correct outcome, not an error worth failing on.
+            logger_1.logger.warn(`[cache-prune]: could not remove ${dir}: ${err.message}`);
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+import type { InstallConfig } from '../../interfaces';
+import type { ProfileName } from './profiles';
+/**
+ * What happened to one profile, in the words the report and `doctor` use.
+ *
+ * `skipped` and `failed` are deliberately distinct. Skipped means we chose not
+ * to fetch — offline, `strategy: "manual"`, an explicit exclusion — and the
+ * client already knows why. Failed means we tried and could not, which is the
+ * case that has to reach the report: ticket 057 is the standing reminder that a
+ * check quietly vanishing is worse than a check failing loudly.
+ */
+export type EnsureStatus = 'cached' | 'installed' | 'skipped' | 'failed';
+export interface EnsureResult {
+    profile: ProfileName;
+    status: EnsureStatus;
+    reason: string;
+    dir?: string;
+    durationMs?: number;
+}
+/** Whether the fetch succeeded, and what to quote in the report when it did not. */
+export interface InstallOutcome {
+    ok: boolean;
+    detail?: string;
+}
+/** Options `ensureProfile` needs that do not come from the config file. */
+export interface EnsureOptions {
+    /** Repository under review — the cwd npm runs in, so the client's `.npmrc` applies. */
+    cwd: string;
+    /** pr-checkmate's own version; part of the cache path. */
+    version: string;
+    install: InstallConfig;
+    /**
+     * The fetch itself. Defaults to `npm ci`; injected by tests.
+     *
+     * A seam rather than a mock of the module: everything around the fetch — the
+     * lock, the cache stamp, the offline and strategy branches, the reasons that
+     * end up in the report — is logic worth pinning, and without this the only way
+     * to reach it is to actually download tooling from the network in a unit test.
+     */
+    installer?: (dir: string) => Promise<InstallOutcome>;
+}
+/** Where the shipped manifests live inside the installed package. */
+export declare function manifestDir(profile: string): string;
+/**
+ * Make one profile's tooling available, fetching it only if it is not already there.
+ *
+ * Idempotent by design: this is the single entry point for both the postinstall
+ * warm-up and the lazy path taken when postinstall never ran (`npm ci
+ * --ignore-scripts`, a `node_modules` restored from a CI cache). Two code paths
+ * for the same job is how the two drift apart and how one of them silently stops
+ * working.
+ *
+ * The install itself is a plain `npm ci` against a manifest we generated from our
+ * own lockfile, run from the client's repository so their `.npmrc`, registry and
+ * proxy settings apply unchanged. `--ignore-scripts` is not negotiable: we are a
+ * supply-chain tool, and running arbitrary install hooks from a security check
+ * would be indefensible. Integrity is npm's own, over the whole transitive tree —
+ * a tampered tarball aborts with `EINTEGRITY` rather than being installed.
+ */
+export declare function ensureProfile(profile: ProfileName, opts: EnsureOptions): Promise<EnsureResult>;