pr-checkmate 2.1.2 → 3.0.1

package/dist/core/checks/security/sensitive-file-guard.js

@@ -3,12 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sensitiveFileGuardCheck = void 0;
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
+const targets_1 = require("../../targets");
 const types_1 = require("../../types");
 const findings_1 = require("../findings");
+/**
+ * The committed template, in the names every ecosystem uses for it.
+ *
+ * `.env.example` holds placeholders, is checked in on purpose, and is what the
+ * `.env` convention tells people to commit — a repository without one is the
+ * unusual case. Flagging it as a secret is not a stylistic quibble now that
+ * ticket 055 makes this category block: it turns the recommended practice into a
+ * red build, and a gate that fires on correct code is a gate people switch off.
+ *
+ * Confirmed in the field before it was fixed here: a client shipped
+ * `"sensitiveFileGuard": { "ignorePaths": [".env.example"] }` in their config to
+ * work around it. Needing a hand-written exclusion for the file the ecosystem
+ * mandates is the definition of a false positive.
+ *
+ * Matched only at the end of the path, so `.env.example.local` — a real file with
+ * real values, named to sort next to the template — is still flagged.
+ */
+const TEMPLATE_SUFFIX = /\.(?:example|sample|template|dist|defaults)$/i;
 const SENSITIVE_CATEGORIES = [
     {
         label: 'Environment files (.env)',
-        patterns: [/^\.env$/, /^\.env\..+/, /\/.env$/, /\/.env\..+/],
+        // The dots are escaped. They were not, and `\/.env$` therefore matched ANY
+        // single character before `env`, so a nested file whose name merely ended in
+        // those three letters was reported as an environment file. Harmless while
+        // this category only warned; a red build over a filename once it blocks.
+        patterns: [/^\.env$/, /^\.env\..+/, /\/\.env$/, /\/\.env\..+/],
+        except: [TEMPLATE_SUFFIX],
         severity: 'error',
     },
     {
@@ -61,6 +85,8 @@ function categorizeFiles(changedFiles) {
     const warnings = {};
     for (const filePath of changedFiles) {
         for (const category of SENSITIVE_CATEGORIES) {
+            if (category.except?.some(p => p.test(filePath)))
+                continue;
             if (category.patterns.some(p => p.test(filePath))) {
                 const bucket = category.severity === 'error' ? errors : warnings;
                 (bucket[_a = category.label] ?? (bucket[_a] = [])).push(filePath);
@@ -82,7 +108,7 @@ exports.sensitiveFileGuardCheck = {
     async run(ctx) {
         try {
             const args = ctx.baseSha
-                ? ['diff', '--name-only', '--diff-filter=ACMRD', ctx.baseSha, 'HEAD']
+                ? ['diff', '--name-only', '--diff-filter=ACMRD', ctx.baseSha, ctx.headSha ?? 'HEAD']
                 : ['ls-files'];
             if (!ctx.baseSha && ctx.config.run?.fullScanBehaviour === 'skip')
                 return (0, types_1.pass)();
@@ -100,10 +126,18 @@ exports.sensitiveFileGuardCheck = {
             // Without this the only exclusion a client has is `ignore`, which suppresses
             // the whole CATEGORY: muting "Private keys and certificates" to excuse one
             // fixture would also excuse the next real key someone commits.
-            const changedFiles = result.stdout
-                .split('\n')
-                .filter(Boolean)
-                .filter(file => !(0, utils_1.matchesAnyGlob)(file, cfg.ignorePaths ?? []));
+            // `excludePaths` before the check's own `ignorePaths`, and both before
+            // categorising.
+            //
+            // This check deliberately does NOT go through `targets.ts`: a committed
+            // `.env` inside `dist/` is still a committed secret, so `ignoreDirs` must
+            // not hide it, and a key outside `sourcePath` is still a key. But
+            // `excludePaths` is different in kind — it is the client saying "do not
+            // look here" in as many words, and the documentation calls it the one
+            // exclusion that reaches every check. It did not reach this one, which
+            // meant a `.pem` test fixture failed the build and the key the docs told
+            // people to reach for did nothing (ticket 080).
+            const changedFiles = (0, targets_1.excludeClientPaths)(result.stdout.split('\n').filter(Boolean), ctx.cwd).filter(file => !(0, utils_1.matchesAnyGlob)(file, cfg.ignorePaths ?? []));
             if (changedFiles.length === 0)
                 return (0, types_1.pass)();
             const { errors, warnings } = categorizeFiles(changedFiles);

package/dist/core/checks/security/workflow-security.js

@@ -79,7 +79,13 @@ exports.workflowSecurityCheck = {
                 scanInto(await (0, findings_1.diffAddedLines)(ctx, globs));
             }
             else if (ctx.config.run?.fullScanBehaviour !== 'skip') {
-                const files = await (0, targets_1.listTrackedFiles)(ctx, globs, ['.']);
+                // `.github` is globally ignored and is the only place these files live,
+                // so this caller has to un-ignore it or scan nothing.
+                const files = await (0, targets_1.listTrackedFiles)(ctx, globs, ['.'], {
+                    keepDirs: ['.github', '.gitlab', '.circleci'],
+                });
+                if (files === null)
+                    return (0, types_1.skip)('git unavailable');
                 await (0, findings_1.scanTrackedFiles)(ctx, files, scanInto);
             }
             return (0, findings_1.reportSeverityBuckets)(found.errors, found.warnings, {

package/dist/core/checks/tool-install.d.ts

@@ -0,0 +1,102 @@
+import { CheckOutcome } from '../types';
+/**
+ * Where to get the external runners we deliberately do not ship.
+ *
+ * Eleven checks shell out to a tool that is not ours to bundle — a Kotlin linter,
+ * a Swift linter, the Go toolchain. When it is absent the check skips, which is
+ * the honest outcome, but `⏭️ ktlint: ktlint not installed` tells the reader
+ * something they already knew and nothing they can act on. A skip is only useful
+ * if it says what would make the check run.
+ *
+ * One table rather than a string at each call site: fourteen hand-written
+ * messages drift, and half of them end up naming an install route that has since
+ * moved.
+ *
+ * **Repository homepages, not deep documentation links.** A `#installation`
+ * anchor is exactly the kind of URL that rots, and a dead link printed into a
+ * client's CI log is worse than no link — it reads as carelessness about the
+ * thing we are asking them to trust. A project's repository root survives
+ * documentation reorganisations and always carries current install instructions.
+ *
+ * The command is the platform-agnostic one where a project has one, and the
+ * common-case one otherwise; the URL covers every other platform.
+ */
+declare const INSTALL_HINTS: {
+    readonly ktlint: {
+        readonly command: "brew install ktlint";
+        readonly url: "https://github.com/pinterest/ktlint";
+    };
+    readonly swiftlint: {
+        readonly command: "brew install swiftlint";
+        readonly url: "https://github.com/realm/SwiftLint";
+    };
+    readonly rubocop: {
+        readonly command: "gem install rubocop";
+        readonly url: "https://github.com/rubocop/rubocop";
+    };
+    readonly shellcheck: {
+        readonly command: "brew install shellcheck";
+        readonly url: "https://github.com/koalaman/shellcheck";
+    };
+    readonly go: {
+        readonly command: null;
+        readonly url: "https://go.dev/doc/install";
+    };
+    readonly gofmt: {
+        readonly command: null;
+        readonly url: "https://go.dev/doc/install";
+    };
+    readonly clippy: {
+        readonly command: "rustup component add clippy";
+        readonly url: "https://github.com/rust-lang/rust-clippy";
+    };
+    readonly rustfmt: {
+        readonly command: "rustup component add rustfmt";
+        readonly url: "https://github.com/rust-lang/rustfmt";
+    };
+    readonly 'php-cs-fixer': {
+        readonly command: "composer global require friendsofphp/php-cs-fixer";
+        readonly url: "https://github.com/PHP-CS-Fixer/PHP-CS-Fixer";
+    };
+    readonly dotnet: {
+        readonly command: null;
+        readonly url: "https://dotnet.microsoft.com/download";
+    };
+    readonly mypy: {
+        readonly command: "pip install mypy";
+        readonly url: "https://github.com/python/mypy";
+    };
+    readonly pyright: {
+        readonly command: "npm i -g pyright";
+        readonly url: "https://github.com/microsoft/pyright";
+    };
+    readonly grype: {
+        readonly command: "brew install grype";
+        readonly url: "https://github.com/anchore/grype";
+    };
+    readonly 'osv-scanner': {
+        readonly command: "brew install osv-scanner";
+        readonly url: "https://github.com/google/osv-scanner";
+    };
+};
+/**
+ * A tool this package expects the environment to provide.
+ *
+ * Exported because the runner specs in `languages/external-checks.ts` name one
+ * per check, and that is the point of naming them: a spec that cannot compile
+ * with a typo in the key cannot ship a skip pointing at an install route that
+ * does not exist.
+ */
+export type ExternalTool = keyof typeof INSTALL_HINTS;
+/**
+ * Skip because `tool` is not on the path, saying how to install it.
+ *
+ * @param tool Which runner is missing.
+ * @param label How to name it in the message. Omit when the check's own display
+ *   name already is the tool's name — `⏭️ ktlint: ktlint not installed` repeats
+ *   itself, which is what made these messages worth revisiting. Pass a label
+ *   when the two differ (`Go Vet` needs `go`) or when either of two tools would
+ *   have done (`mypy/pyright`).
+ */
+export declare function notInstalled(tool: ExternalTool, label?: string): CheckOutcome;
+export {};

package/dist/core/checks/tool-install.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notInstalled = notInstalled;
+const types_1 = require("../types");
+/**
+ * Where to get the external runners we deliberately do not ship.
+ *
+ * Eleven checks shell out to a tool that is not ours to bundle — a Kotlin linter,
+ * a Swift linter, the Go toolchain. When it is absent the check skips, which is
+ * the honest outcome, but `⏭️ ktlint: ktlint not installed` tells the reader
+ * something they already knew and nothing they can act on. A skip is only useful
+ * if it says what would make the check run.
+ *
+ * One table rather than a string at each call site: fourteen hand-written
+ * messages drift, and half of them end up naming an install route that has since
+ * moved.
+ *
+ * **Repository homepages, not deep documentation links.** A `#installation`
+ * anchor is exactly the kind of URL that rots, and a dead link printed into a
+ * client's CI log is worse than no link — it reads as carelessness about the
+ * thing we are asking them to trust. A project's repository root survives
+ * documentation reorganisations and always carries current install instructions.
+ *
+ * The command is the platform-agnostic one where a project has one, and the
+ * common-case one otherwise; the URL covers every other platform.
+ */
+const INSTALL_HINTS = {
+    ktlint: { command: 'brew install ktlint', url: 'https://github.com/pinterest/ktlint' },
+    swiftlint: { command: 'brew install swiftlint', url: 'https://github.com/realm/SwiftLint' },
+    rubocop: { command: 'gem install rubocop', url: 'https://github.com/rubocop/rubocop' },
+    shellcheck: {
+        command: 'brew install shellcheck',
+        url: 'https://github.com/koalaman/shellcheck',
+    },
+    go: { command: null, url: 'https://go.dev/doc/install' },
+    gofmt: { command: null, url: 'https://go.dev/doc/install' },
+    clippy: {
+        command: 'rustup component add clippy',
+        url: 'https://github.com/rust-lang/rust-clippy',
+    },
+    rustfmt: { command: 'rustup component add rustfmt', url: 'https://github.com/rust-lang/rustfmt' },
+    'php-cs-fixer': {
+        command: 'composer global require friendsofphp/php-cs-fixer',
+        url: 'https://github.com/PHP-CS-Fixer/PHP-CS-Fixer',
+    },
+    dotnet: { command: null, url: 'https://dotnet.microsoft.com/download' },
+    mypy: { command: 'pip install mypy', url: 'https://github.com/python/mypy' },
+    pyright: { command: 'npm i -g pyright', url: 'https://github.com/microsoft/pyright' },
+    grype: { command: 'brew install grype', url: 'https://github.com/anchore/grype' },
+    'osv-scanner': {
+        command: 'brew install osv-scanner',
+        url: 'https://github.com/google/osv-scanner',
+    },
+};
+/**
+ * Skip because `tool` is not on the path, saying how to install it.
+ *
+ * @param tool Which runner is missing.
+ * @param label How to name it in the message. Omit when the check's own display
+ *   name already is the tool's name — `⏭️ ktlint: ktlint not installed` repeats
+ *   itself, which is what made these messages worth revisiting. Pass a label
+ *   when the two differ (`Go Vet` needs `go`) or when either of two tools would
+ *   have done (`mypy/pyright`).
+ */
+function notInstalled(tool, label) {
+    const { command, url } = INSTALL_HINTS[tool];
+    const subject = label ? `${label} not installed` : 'not installed';
+    return (0, types_1.skip)(command ? `${subject} — ${command} · ${url}` : `${subject} — ${url}`);
+}

package/dist/core/commands.js

@@ -33,6 +33,7 @@ exports.COMMAND_TO_CHECK = {
     markdown: 'Markdown',
     'yaml-lint': 'YAML Lint',
     symlinks: 'Broken Symlinks',
+    'package-size': 'Package Size',
     shellcheck: 'ShellCheck',
     typecheck: 'TypeScript',
     'diff-smell': 'Diff Smells',

package/dist/core/context.js

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

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

@@ -27,7 +27,26 @@ export declare function expandHome(dir: string, home?: string): string;
  * @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. */
+/**
+ * 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.

package/dist/core/install/cache.js

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

package/dist/core/install/doctor.js

@@ -9,7 +9,6 @@ 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");
@@ -17,6 +16,7 @@ const package_version_1 = require("../../utils/package-version");
 Object.defineProperty(exports, "packageVersion", { enumerable: true, get: function () { return package_version_1.packageVersion; } });
 const cache_1 = require("./cache");
 const ensure_1 = require("./ensure");
+const prepare_1 = require("./prepare");
 const profiles_1 = require("./profiles");
 /**
  * Everything the install layer knows about this repository, in one shot.
@@ -31,11 +31,31 @@ async function planInstall(cwd = process.cwd(), usage) {
     const location = (0, cache_1.resolveCacheDir)((0, package_version_1.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. */
+/**
+ * Which profiles are usable right now, and why — fetched, or shipped with us.
+ *
+ * The cache is only half the answer, and reporting only that half was a lie in
+ * the client's favour's opposite direction: most profiles ship inside the
+ * package, are never fetched, and were listed as "not installed yet" on a machine
+ * where they worked perfectly. `doctor` exists to answer "why did my typecheck
+ * not run", so telling someone seven profiles are missing when six of them are
+ * present sends them to debug nothing.
+ *
+ * The cached half is read from the tooling directory's own stamp rather than
+ * inferred from paths: there is one tree for everything fetched, so what went
+ * into it is recorded rather than visible in the layout (ticket 087).
+ */
 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));
+    const present = new Map();
+    for (const profile of profiles_1.PROFILES) {
+        if ((0, prepare_1.profileSatisfiedLocally)(profile))
+            present.set(profile.name, 'ships with the package');
+    }
+    if (cacheDir) {
+        for (const name of (0, ensure_1.cachedProfiles)(cacheDir))
+            present.set(name, 'fetched');
+    }
+    return present;
 }
 /**
  * Fetch every profile this repository needs.
@@ -52,20 +72,29 @@ async function installProfiles(cwd = process.cwd(), all = false) {
     const denied = new Set(install.deny ?? []);
     const wanted = (all ? profiles_1.PROFILES.map(p => p.name) : decisions.filter(d => d.required).map(d => d.profile)).filter(name => {
         const profile = profiles_1.PROFILES.find(p => p.name === name);
+        // Nothing to fetch for a profile whose packages already ship with us, and
+        // fetching it anyway is not merely wasted: `--all` downloaded a second copy
+        // of every bundled profile — some 800 packages — beside the ones already in
+        // `node_modules`. On a container build that lands in the image (ticket 083).
+        if (profile && (0, prepare_1.profileSatisfiedLocally)(profile)) {
+            logger_1.logger.info(`[install]: profile "${name}" already ships with the package`);
+            return false;
+        }
         const blocked = profile?.packages.filter(pkg => denied.has(pkg)) ?? [];
         if (blocked.length === 0)
             return true;
         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: (0, package_version_1.packageVersion)(), install }));
-    }
-    return results;
+    // One install for the whole set. Profiles that share hundreds of packages used
+    // to be fetched into a tree each, which fought over npm's cache and downloaded
+    // the shared half once per profile (ticket 087).
+    const result = await (0, ensure_1.ensureTooling)(wanted, {
+        cwd,
+        version: (0, package_version_1.packageVersion)(),
+        install,
+    });
+    return [result];
 }
 /**
  * Explain what this repository needs, what it has, and what is missing — and why.
@@ -99,8 +128,13 @@ async function runDoctor(cwd = process.cwd()) {
     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 source = present.get(decision.profile);
+        const state = decision.required ? (source ? '✅' : '⬇️ ') : '—';
+        // Where a present profile came from, because "it works" and "it works
+        // because it was downloaded onto this runner" are different situations for
+        // anyone debugging a cache or an air-gapped build.
+        const how = decision.required && source ? ` (${source})` : '';
+        lines.push(`    ${state} ${decision.profile.padEnd(12)} ${decision.reason}${how}`);
     }
     const missing = decisions.filter(d => d.required && !present.has(d.profile));
     if (missing.length > 0) {

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

@@ -1,7 +1,7 @@
 import type { InstallConfig } from '../../interfaces';
 import type { ProfileName } from './profiles';
 /**
- * What happened to one profile, in the words the report and `doctor` use.
+ * What happened to the tooling cache, 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
@@ -9,12 +9,13 @@ import type { ProfileName } from './profiles';
  * 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';
+type EnsureStatus = 'cached' | 'installed' | 'skipped' | 'failed';
 export interface EnsureResult {
-    profile: ProfileName;
     status: EnsureStatus;
     reason: string;
     dir?: string;
+    /** Profiles the directory holds once this call is done. */
+    profiles: ProfileName[];
     durationMs?: number;
 }
 /** Whether the fetch succeeded, and what to quote in the report when it did not. */
@@ -22,7 +23,7 @@ export interface InstallOutcome {
     ok: boolean;
     detail?: string;
 }
-/** Options `ensureProfile` needs that do not come from the config file. */
+/** Options `ensureTooling` 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;
@@ -42,19 +43,35 @@ export interface EnsureOptions {
 /** 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.
+ * Which profiles the tooling cache holds, as recorded by the install that filled it.
  *
- * 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
+ * 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.
+ */
+export declare function cachedProfiles(cacheDir: string): ProfileName[];
+/**
+ * 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 `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.
  */
-export declare function ensureProfile(profile: ProfileName, opts: EnsureOptions): Promise<EnsureResult>;
+export declare function ensureTooling(wanted: ProfileName[], opts: EnsureOptions): Promise<EnsureResult>;
+export {};