pr-checkmate 2.1.2 → 3.0.1

package/dist/core/install/ensure.js

@@ -4,7 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.manifestDir = manifestDir;
-exports.ensureProfile = ensureProfile;
+exports.cachedProfiles = cachedProfiles;
+exports.ensureTooling = ensureTooling;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -12,117 +13,213 @@ const execa_1 = require("../../utils/execa");
 const logger_1 = require("../../utils/logger");
 const cache_1 = require("./cache");
 const lock_1 = require("./lock");
+const merge_1 = require("./merge");
 /** Where the shipped manifests live inside the installed package. */
 function manifestDir(profile) {
     return node_path_1.default.resolve(__dirname, '../../..', 'install-manifests', profile);
 }
 const stampPath = (dir) => node_path_1.default.join(dir, '.pr-checkmate-installed');
-/** The manifest pair copied into the cache; `npm ci` reads exactly these two. */
-const MANIFEST_FILES = ['package.json', 'package-lock.json'];
-const LOCKFILE = MANIFEST_FILES[1];
+const MANIFEST = 'package.json';
+const LOCKFILE = 'package-lock.json';
 /**
- * A fingerprint of the manifest a profile directory was installed from.
+ * Merge the shipped manifests for a set of profiles, or say which one is missing.
+ *
+ * Returns `null` rather than throwing on a missing manifest, because that is an
+ * ordinary condition: a stamp written by another version can name a profile this
+ * one no longer ships. A *disagreement* between two manifests is different and
+ * still throws — see {@link mergeManifests}.
+ */
+function manifestFor(profiles) {
+    const dirs = profiles.map(name => ({ name, dir: manifestDir(name) }));
+    if (dirs.some(d => !node_fs_1.default.existsSync(node_path_1.default.join(d.dir, LOCKFILE))))
+        return null;
+    return (0, merge_1.mergeManifests)(dirs);
+}
+/**
+ * A fingerprint of the manifest a tooling directory was installed from.
  *
  * Comparing the lockfile hash rather than merely checking that `node_modules`
  * exists is what makes an upgrade correct: the cache path already includes our
  * version, but a client can also pin a `cacheDir` shared between checkouts, and
  * a half-written directory from an interrupted install must not read as ready.
  */
-function manifestHash(dir) {
+function hashOf(manifest) {
+    return node_crypto_1.default.createHash('sha256').update(JSON.stringify(manifest.lockfile)).digest('hex');
+}
+function readStamp(dir) {
     try {
-        const lock = node_fs_1.default.readFileSync(node_path_1.default.join(dir, LOCKFILE));
-        return node_crypto_1.default.createHash('sha256').update(lock).digest('hex');
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(stampPath(dir), 'utf-8'));
+        return Array.isArray(parsed.profiles) && typeof parsed.hash === 'string' ? parsed : null;
     }
     catch {
+        // Unreadable, absent, or written by a version that stamped a bare hash.
+        // All three mean the same thing here: we cannot claim to know what is there.
         return null;
     }
 }
-/** Whether this profile directory already holds exactly this manifest, installed. */
-function isInstalled(dir, expected) {
-    if (!expected)
+/**
+ * Whether the directory already holds everything asked for.
+ *
+ * A **superset** check, not an equality one, and that is the point of the shared
+ * directory. `install --all` warms the cache with every profile; a run that needs
+ * two of them must read that as ready, or the pre-warming built into our Docker
+ * image buys nothing — the failure ticket 083 was about. It is also what makes a
+ * language added six months later cost one install rather than one per run.
+ *
+ * The stamp's own hash is re-derived from the manifests we ship *now*, so a
+ * directory installed by a build with different manifests is correctly rejected
+ * even when its profile list still looks right.
+ */
+function holdsAll(dir, stamp, needed) {
+    if (!stamp || !node_fs_1.default.existsSync(node_path_1.default.join(dir, 'node_modules')))
         return false;
-    try {
-        return (node_fs_1.default.readFileSync(stampPath(dir), 'utf-8').trim() === expected &&
-            node_fs_1.default.existsSync(node_path_1.default.join(dir, 'node_modules')));
-    }
-    catch {
+    if (!needed.every(p => stamp.profiles.includes(p)))
         return false;
-    }
+    const installed = manifestFor(stamp.profiles);
+    return installed !== null && hashOf(installed) === stamp.hash;
 }
-/** Copy the shipped manifest into the cache so `npm ci` has something to read. */
-function stageManifest(from, to) {
-    node_fs_1.default.mkdirSync(to, { recursive: true });
-    for (const file of MANIFEST_FILES) {
-        node_fs_1.default.copyFileSync(node_path_1.default.join(from, file), node_path_1.default.join(to, file));
-    }
+/** Write the merged manifest into the cache so `npm ci` has something to read. */
+function writeManifest(dir, manifest) {
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    node_fs_1.default.writeFileSync(node_path_1.default.join(dir, MANIFEST), JSON.stringify(manifest.pkg, null, 2));
+    node_fs_1.default.writeFileSync(node_path_1.default.join(dir, LOCKFILE), JSON.stringify(manifest.lockfile, null, 2));
+}
+/** Sorted, de-duplicated, so a set is one set however it was assembled. */
+const normalise = (profiles) => [...new Set(profiles)].sort();
+/**
+ * Which profiles the tooling cache holds, as recorded by the install that filled it.
+ *
+ * The one way to ask, so the stamp's format has a single owner. There is one tree
+ * for all fetched tooling now, so what is in it is written down rather than
+ * readable from the directory layout.
+ */
+function cachedProfiles(cacheDir) {
+    const dir = (0, cache_1.toolingDir)(cacheDir);
+    if (!node_fs_1.default.existsSync(node_path_1.default.join(dir, 'node_modules')))
+        return [];
+    return readStamp(dir)?.profiles ?? [];
 }
 /**
- * Make one profile's tooling available, fetching it only if it is not already there.
+ * Make a set of profiles' tooling available, fetching only what 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
+ * Idempotent by design: this is the single entry point for both the `install`
+ * command and the lazy path taken when it was never run (`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.
+ * Everything needed goes into **one** tree. Profiles overlap heavily — `js` and
+ * `commitlint` share 30 MB — and a directory each left npm nothing to
+ * deduplicate: 267 MB against the 211 one merged tree costs for the same set
+ * (ticket 087). The set only ever grows: a run needing a profile the directory
+ * lacks reinstalls the union, so nothing already fetched is lost.
+ *
+ * The install itself is a plain `npm ci` against a manifest merged from the ones
+ * 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.
  */
-async function ensureProfile(profile, opts) {
+async function ensureTooling(wanted, 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) {
-        return { profile, status: 'failed', reason: `no shipped manifest for profile "${profile}"` };
+    const needed = normalise(wanted);
+    if (needed.length === 0) {
+        return { status: 'cached', reason: 'nothing to fetch', profiles: [] };
     }
     const location = (0, cache_1.resolveCacheDir)(opts.version, install.cacheDir);
     if (!location) {
         return {
-            profile,
             status: 'failed',
             reason: 'no writable cache directory (tried the configured path, ~/.cache and the temp dir)',
+            profiles: [],
         };
     }
-    const dir = (0, cache_1.profileDir)(location.dir, profile);
-    if (isInstalled(dir, expected)) {
-        return { profile, status: 'cached', reason: 'already installed', dir };
+    const dir = (0, cache_1.toolingDir)(location.dir);
+    const stamp = readStamp(dir);
+    if (holdsAll(dir, stamp, needed)) {
+        return { status: 'cached', reason: 'already installed', dir, profiles: stamp?.profiles ?? [] };
+    }
+    // Never shrink: whatever the directory already holds stays, or a repository
+    // that alternates between two languages would reinstall on every run.
+    const target = normalise([...(stamp?.profiles ?? []), ...needed]);
+    let installing = target;
+    let manifest = manifestFor(target);
+    if (!manifest) {
+        // The stamp names a profile this version no longer ships. Keeping it would
+        // make the directory permanently un-installable; dropping it costs a refetch
+        // of tooling that is obsolete anyway.
+        installing = needed;
+        manifest = manifestFor(needed);
+    }
+    if (!manifest) {
+        return {
+            status: 'failed',
+            reason: `no shipped manifest for ${needed.join(', ')}`,
+            profiles: [],
+        };
+    }
+    // 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 {
+            status: 'skipped',
+            reason: 'install.strategy is "manual" and the tooling is not in the cache',
+            dir,
+            profiles: stamp?.profiles ?? [],
+        };
     }
     if (install.offline || process.env.PR_CHECKMATE_OFFLINE === 'true') {
         return {
-            profile,
             status: 'skipped',
-            reason: 'install.offline is set and the profile is not in the cache',
+            reason: 'install.offline is set and the tooling is not in the cache',
             dir,
+            profiles: stamp?.profiles ?? [],
         };
     }
-    // The lock file lives in the profile directory, so the directory has to exist
+    // The lock file lives in the tooling directory, so the directory has to exist
     // before there is anything to lock. Creating it inside `withLock` would put
     // the creation itself outside the lock, which is the race it exists to close.
     try {
         node_fs_1.default.mkdirSync(dir, { recursive: true });
     }
     catch (err) {
-        return { profile, status: 'failed', reason: `cannot create ${dir}: ${err.message}` };
+        return {
+            status: 'failed',
+            reason: `cannot create ${dir}: ${err.message}`,
+            profiles: [],
+        };
     }
     const release = await (0, lock_1.withLock)(dir, install.waitTimeoutMs ?? 120000);
     if (!release) {
-        return { profile, status: 'failed', reason: `cannot write to ${dir}`, dir };
+        return { status: 'failed', reason: `cannot write to ${dir}`, dir, profiles: [] };
     }
     try {
         // Re-checked inside the lock: while we waited, the process we were waiting
         // for probably did the work. Without this, waiting is pointless — every
         // queued job would reinstall in turn.
-        if (isInstalled(dir, expected)) {
-            return { profile, status: 'cached', reason: 'installed by another process', dir };
+        if (holdsAll(dir, readStamp(dir), needed)) {
+            return {
+                status: 'cached',
+                reason: 'installed by another process',
+                dir,
+                profiles: readStamp(dir)?.profiles ?? [],
+            };
         }
-        return await runInstall(profile, source, dir, expected, opts);
+        return await runInstall(installing, manifest, dir, opts);
     }
     finally {
         release();
@@ -143,27 +240,34 @@ async function npmCi(dir, opts) {
     return { ok: false, detail: detail || `exit ${result.exitCode}` };
 }
 /** The fetch itself, once we hold the lock and know it is needed. */
-async function runInstall(profile, source, dir, expected, opts) {
+async function runInstall(profiles, manifest, dir, opts) {
     const started = Date.now();
-    stageManifest(source, dir);
-    const count = Object.keys(JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, LOCKFILE), 'utf-8')).packages).length;
+    writeManifest(dir, manifest);
+    const named = profiles.join(', ');
+    const count = Object.keys(manifest.lockfile.packages).length - 1;
     // Always logged, never behind --debug: this is a security tool downloading
     // code at run time, and that must be visible in every CI log by default.
-    logger_1.logger.info(`[install]: 📦 fetching profile "${profile}" (${count} packages) → ${dir}`);
+    logger_1.logger.info(`[install]: 📦 fetching tooling for ${named} (${count} packages) → ${dir}`);
     try {
         const install = opts.installer ?? ((target) => npmCi(target, opts));
         const result = await install(dir);
         if (!result.ok) {
-            return { profile, status: 'failed', reason: `npm ci failed: ${result.detail}`, dir };
+            return { status: 'failed', reason: `npm ci failed: ${result.detail}`, dir, profiles: [] };
         }
-        node_fs_1.default.writeFileSync(stampPath(dir), expected);
+        const stamp = { hash: hashOf(manifest), profiles };
+        node_fs_1.default.writeFileSync(stampPath(dir), JSON.stringify(stamp));
         const durationMs = Date.now() - started;
-        logger_1.logger.info(`[install]: ✅ profile "${profile}" ready in ${(durationMs / 1000).toFixed(1)}s`);
-        return { profile, status: 'installed', reason: `${count} packages`, dir, durationMs };
+        logger_1.logger.info(`[install]: ✅ tooling ready in ${(durationMs / 1000).toFixed(1)}s (${named})`);
+        return { status: 'installed', reason: `${count} packages`, dir, profiles, durationMs };
     }
     catch (err) {
         // A timeout arrives here as a thrown error. It is a skip, not a crash: the
         // rest of the run is still worth doing, and the affected checks say why.
-        return { profile, status: 'failed', reason: `npm ci failed: ${err.message}`, dir };
+        return {
+            status: 'failed',
+            reason: `npm ci failed: ${err.message}`,
+            dir,
+            profiles: [],
+        };
     }
 }

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/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/core/install/merge.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeManifests = mergeManifests;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("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(node_fs_1.default.readFileSync(node_path_1.default.join(dir, 'package.json'), 'utf-8')),
+        lock: JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.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.
+ */
+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/core/install/prepare.d.ts

@@ -0,0 +1,76 @@
+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. 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 {};