pr-checkmate 3.0.0 → 3.0.2

package/dist/cli.js

@@ -88,7 +88,7 @@ void (async () => {
             const results = await (0, doctor_1.installProfiles)(process.cwd(), flags.includes('--all'));
             const failed = results.filter(r => r.status === 'failed');
             for (const result of failed) {
-                utils_1.logger.error(`[install]: ❌ ${result.profile}: ${result.reason}`);
+                utils_1.logger.error(`[install]: ❌ ${result.profiles.join(', ') || 'tooling'}: ${result.reason}`);
             }
             process.exit(failed.length > 0 ? 1 : 0);
         }

package/dist/config/constants.js

@@ -346,6 +346,7 @@ exports.KNOWN_CONFIG_KEYS = new Set([
     'licenseHeader',
     'duplicate',
     'deadCode',
+    'packageSize',
     'prBody',
     'prSize',
     'commitlint',

package/dist/core/checks/languages/ruff-shared.d.ts

@@ -2,9 +2,9 @@ type RuffModule = typeof import('@astral-sh/ruff-wasm-nodejs');
 type RuffWorkspace = InstanceType<RuffModule['Workspace']>;
 export declare const PY_GLOBS: string[];
 /**
- * Instantiate a Ruff WASM workspace with default settings. Shared by the Ruff
- * lint and format checks so their setup stays identical, and kept as a function
- * (not a module-level singleton) so the WASM module loads only when a check runs.
+ * Instantiate a Ruff WASM workspace. Shared by the Ruff lint and format checks so
+ * their setup stays identical, and kept as a function (not a module-level
+ * singleton) so the WASM module loads only when a check runs.
  */
 export declare function createRuffWorkspace(): RuffWorkspace;
 export {};

package/dist/core/checks/languages/ruff-shared.js

@@ -4,11 +4,34 @@ exports.PY_GLOBS = void 0;
 exports.createRuffWorkspace = createRuffWorkspace;
 exports.PY_GLOBS = ['*.py'];
 /**
- * Instantiate a Ruff WASM workspace with default settings. Shared by the Ruff
- * lint and format checks so their setup stays identical, and kept as a function
- * (not a module-level singleton) so the WASM module loads only when a check runs.
+ * The rules we lint Python with — pinned here rather than left to Ruff's defaults.
+ *
+ * `E4`/`E7`/`E9` (import placement, statement style, syntax) plus `F` (pyflakes:
+ * undefined names, unused imports, unreachable code) — the set Ruff itself
+ * shipped as its default through 0.15.
+ *
+ * Written down because leaving it implicit made our verdict change under us.
+ * Ruff 0.16 added the isort rules (`I`) to its defaults, and a routine dependency
+ * bump turned that into a 5- to 48-fold increase in findings across seventeen
+ * Python repositories — every one of them `I001`, "import block is un-sorted".
+ * Two repositories went from a clean report to a warning on code nobody had
+ * touched. Import order is a matter of taste, and a check that fires on every
+ * file in a repository is how people learn to ignore the whole report.
+ *
+ * Adding a rule to this list is a decision with a measurement behind it, which
+ * is the point: it is ours to make, not our dependency's to make for us.
+ */
+const SELECTED_RULES = ['E4', 'E7', 'E9', 'F'];
+/**
+ * Instantiate a Ruff WASM workspace. Shared by the Ruff lint and format checks so
+ * their setup stays identical, and kept as a function (not a module-level
+ * singleton) so the WASM module loads only when a check runs.
  */
 function createRuffWorkspace() {
     const { Workspace, PositionEncoding } = require('@astral-sh/ruff-wasm-nodejs');
-    return new Workspace(Workspace.defaultSettings(), PositionEncoding.Utf16);
+    const settings = {
+        ...Workspace.defaultSettings(),
+        lint: { select: SELECTED_RULES },
+    };
+    return new Workspace(settings, PositionEncoding.Utf16);
 }

package/dist/core/checks/quality/coverage.js

@@ -48,7 +48,12 @@ exports.coverageCheck = {
             : DEFAULT_REPORTS;
         const found = candidates.find(rel => {
             try {
-                return node_fs_1.default.statSync(node_path_1.default.join(ctx.cwd, rel)).size > 0;
+                // `isFile()` as well as the size: `statSync` reports a non-zero size for
+                // a directory too, so a path that happens to be one would read as a
+                // report. Non-empty matters because a zero-byte report is what a test
+                // run that died halfway leaves behind — the case this check exists for.
+                const stat = node_fs_1.default.statSync(node_path_1.default.join(ctx.cwd, rel));
+                return stat.isFile() && stat.size > 0;
             }
             catch {
                 return false;

package/dist/core/checks/quality/dead-code.js

@@ -44,7 +44,7 @@ exports.deadCodeCheck = {
             const ignore = compileIgnorePatterns(ctx.config.deadCode?.ignoreFiles ?? constants_1.DEAD_CODE_IGNORE_DEFAULTS);
             // ts-unused-exports prints one `path: sym1, sym2` line per file, preceded
             // by a `N modules with unused exports` summary line we skip.
-            const entries = output
+            const parsed = output
                 .split('\n')
                 .map(line => line.trim().match(/^(.+\.[cm]?tsx?): (.+)$/))
                 .filter((match) => match !== null)
@@ -54,8 +54,17 @@ exports.deadCodeCheck = {
                     .split(',')
                     .map(sym => sym.trim())
                     .filter(Boolean),
-            }))
-                .filter(entry => !ignore.some(re => re.test(entry.file)));
+            }));
+            // The tool said something and none of it was a report. That is not a clean
+            // repository — it is an answer this check cannot read, and calling it a
+            // pass is how Circular Deps stayed green on every repository for its whole
+            // existence while grepping for console wording that had changed. Same
+            // resolution as Grype Scan: say so rather than invent a verdict.
+            if (parsed.length === 0) {
+                utils_1.logger.warn(`[Dead Code]: ⚠️ ts-unused-exports produced no parseable output:\n${output}`);
+                return (0, types_1.warn)('ts-unused-exports produced no parseable output');
+            }
+            const entries = parsed.filter(entry => !ignore.some(re => re.test(entry.file)));
             if (entries.length === 0) {
                 utils_1.logger.info('[Dead Code]: ✅ No unused exports found');
                 return (0, types_1.pass)();

package/dist/core/checks/quality/package-size.d.ts

@@ -0,0 +1,36 @@
+import { Check } from '../../types';
+/** Why we could not read a published version. */
+export type QueryFailure = 'absent' | 'unauthenticated' | 'unreadable';
+/**
+ * Tell "never published" apart from "we were not let in".
+ *
+ * Lumped into one sentence they read the same and they are not: one is a fact
+ * about the package, the other is about this run's credentials. A skip whose
+ * reason is a guess between two causes is the defect of ticket 057, one layer up.
+ *
+ * A 401 is also evidence in itself, and it points one way: a name nobody ever
+ * published answers 404 on the public registry, while 401 comes from a host that
+ * has the package and will not show it to a stranger. So the message leads with
+ * the token, which is what that situation actually needs.
+ *
+ * It deliberately does NOT suggest `"private": true` as the way out. That field
+ * means "never publish this", and a package behind a private registry is
+ * published — advising it would break the publish step of the very repository
+ * asking. `packageSize.enabled: false` silences the row and touches nothing
+ * else, so that is the opt-out worth naming.
+ */
+export declare function classifyQueryFailure(stderr: string): QueryFailure;
+/**
+ * Reports how much the published package grew since the last release.
+ *
+ * The question this answers is "is it growing without anyone noticing", not "has
+ * it crossed a line" — so the comparison is against the previously published
+ * version rather than a threshold somebody had to invent. A number a client never
+ * configured is a number they will not trust, and a check that fires on every
+ * release teaches people to skim the whole report.
+ *
+ * Advisory by design. Growth is usually earned — a language profile was added, a
+ * WASM binary landed — and a red build for it would be wrong. `severity:
+ * { "Package Size": "error" }` makes it a gate for a repository that wants one.
+ */
+export declare const packageSizeCheck: Check;

package/dist/core/checks/quality/package-size.js

@@ -0,0 +1,203 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageSizeCheck = void 0;
+exports.classifyQueryFailure = classifyQueryFailure;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const utils_1 = require("../../../utils");
+const execa_1 = require("../../../utils/execa");
+const types_1 = require("../../types");
+const findings_1 = require("../findings");
+/** Growth that is worth a row in the report, unless the client says otherwise. */
+const DEFAULT_MAX_GROWTH = 20;
+/** How many of the files behind the growth are named. */
+const NAMED_FILES = 5;
+/**
+ * Ask npm what a tarball would contain, without producing one.
+ *
+ * `--dry-run` writes nothing to the working tree — which matters, because a check
+ * whose side effect is a `.tgz` beside the source shows up in the client's next
+ * commit. Given a package spec instead of nothing, npm answers for the PUBLISHED
+ * version, with the same shape and the same per-file detail; that is what makes a
+ * real comparison possible rather than a bare number.
+ *
+ * `--ignore-scripts` is not negotiable. `npm pack` runs `prepare` and `prepack`,
+ * and in a client's repository those are arbitrary commands — frequently a full
+ * build. A quality check that executes them has stopped being a check and started
+ * being a build step with side effects nobody asked for. We are a supply-chain
+ * tool; the same rule already governs the install path and the Docker build.
+ *
+ * @param cwd Repository to run in.
+ * @param spec `undefined` for the working tree, or `name@tag` for a release.
+ * @param registry Where to look for a published version; the manifest's own
+ *   `publishConfig.registry` when it names one.
+ */
+async function packManifest(cwd, spec, registry) {
+    const args = [
+        'pack',
+        ...(spec ? [spec] : []),
+        '--dry-run',
+        '--json',
+        '--ignore-scripts',
+        ...(registry ? ['--registry', registry] : []),
+    ];
+    const result = await (0, execa_1.execa)('npm', args, { cwd, reject: false });
+    if (result.exitCode !== 0)
+        return { failure: classifyQueryFailure(result.stderr ?? '') };
+    try {
+        const parsed = JSON.parse(result.stdout);
+        if (Array.isArray(parsed) && parsed.length > 0) {
+            return { manifest: parsed[0] };
+        }
+    }
+    catch {
+        // Fall through: npm answered with something that is not a manifest.
+    }
+    return { failure: 'unreadable' };
+}
+/**
+ * Tell "never published" apart from "we were not let in".
+ *
+ * Lumped into one sentence they read the same and they are not: one is a fact
+ * about the package, the other is about this run's credentials. A skip whose
+ * reason is a guess between two causes is the defect of ticket 057, one layer up.
+ *
+ * A 401 is also evidence in itself, and it points one way: a name nobody ever
+ * published answers 404 on the public registry, while 401 comes from a host that
+ * has the package and will not show it to a stranger. So the message leads with
+ * the token, which is what that situation actually needs.
+ *
+ * It deliberately does NOT suggest `"private": true` as the way out. That field
+ * means "never publish this", and a package behind a private registry is
+ * published — advising it would break the publish step of the very repository
+ * asking. `packageSize.enabled: false` silences the row and touches nothing
+ * else, so that is the opt-out worth naming.
+ */
+function classifyQueryFailure(stderr) {
+    if (/\bE?40[13]\b|Unauthorized|Forbidden|authentication token/i.test(stderr)) {
+        return 'unauthenticated';
+    }
+    if (/\bE?404\b|Not found/i.test(stderr))
+        return 'absent';
+    return 'unreadable';
+}
+/** `1.15 MB`, at the precision a human compares two of these at. */
+function mb(bytes) {
+    return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+/**
+ * Which files account for the growth, biggest first.
+ *
+ * A percentage alone is a finding nobody can act on — the same defect as a
+ * duplicate-code report with no file names (ticket 078). The published manifest
+ * carries per-file sizes, so the answer is a plain diff of the two lists: files
+ * that appeared, and files that grew.
+ */
+function growthByFile(before, after) {
+    const old = new Map(before.map(f => [f.path, f.size]));
+    return after
+        .map(f => ({ path: f.path, delta: f.size - (old.get(f.path) ?? 0), isNew: !old.has(f.path) }))
+        .filter(f => f.delta > 0)
+        .sort((a, b) => b.delta - a.delta)
+        .slice(0, NAMED_FILES)
+        .map(f => `${f.path} +${mb(f.delta)}${f.isNew ? ' (new)' : ''}`);
+}
+/** What this repository publishes, and where — or `null` if it publishes nothing. */
+function published(cwd) {
+    try {
+        const pkg = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(cwd, 'package.json'), 'utf-8'));
+        if (pkg.private || !pkg.name)
+            return null;
+        // `publishConfig.registry` is the manifest's own statement of where this
+        // package lives, and npm uses it for `publish` but not for a fetch. Asking
+        // the default registry instead reports "no published version" for every
+        // package on GitHub Packages or a company mirror — which is not a fact about
+        // the package, it is us having asked the wrong host. Measured on a real
+        // client: the default registry answered 404 for a package published at
+        // version 1.2.15.
+        const registry = pkg.publishConfig?.registry;
+        return registry ? { name: pkg.name, registry } : { name: pkg.name };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reports how much the published package grew since the last release.
+ *
+ * The question this answers is "is it growing without anyone noticing", not "has
+ * it crossed a line" — so the comparison is against the previously published
+ * version rather than a threshold somebody had to invent. A number a client never
+ * configured is a number they will not trust, and a check that fires on every
+ * release teaches people to skim the whole report.
+ *
+ * Advisory by design. Growth is usually earned — a language profile was added, a
+ * WASM binary landed — and a red build for it would be wrong. `severity:
+ * { "Package Size": "error" }` makes it a gate for a repository that wants one.
+ */
+exports.packageSizeCheck = {
+    name: 'Package Size',
+    phase: 'informational',
+    weight: 'heavy',
+    applies(ctx) {
+        if (ctx.config.packageSize?.enabled === false)
+            return false;
+        // A private package is never published, so there is nothing to compare with
+        // and no consumer to pay for the growth.
+        return published(ctx.cwd) !== null;
+    },
+    async run(ctx) {
+        const target = published(ctx.cwd);
+        if (!target)
+            return (0, types_1.skip)('no publishable package.json');
+        const tag = ctx.config.packageSize?.compareWith ?? 'latest';
+        const maxGrowth = ctx.config.packageSize?.maxGrowthPercent ?? DEFAULT_MAX_GROWTH;
+        const spec = `${target.name}@${tag}`;
+        const local = await packManifest(ctx.cwd);
+        if (!('manifest' in local))
+            return (0, types_1.skip)('npm could not describe this package');
+        const current = local.manifest;
+        // Never a pass: a green row over a comparison that did not happen is the
+        // mistake of ticket 072. And never one reason standing in for three — the
+        // three are different situations for the reader, and only one of them is a
+        // fact about the package rather than about the run.
+        const remote = await packManifest(ctx.cwd, spec, target.registry);
+        if (!('manifest' in remote)) {
+            // The fact, and nothing past it. The remedy for a private registry is three
+            // lines in a workflow — `setup-node` with `registry-url`, a scope, and
+            // `NODE_AUTH_TOKEN`, because npm reads the token through a reference in
+            // `.npmrc` — and instructions that do not fit cannot be followed. They
+            // belong on the check's page, which the report already links to.
+            //
+            // The package name is left out on purpose: the reader owns it. The host is
+            // not, because it is the one part they cannot infer — and the difference
+            // between "we asked the wrong registry" and "we were refused" is exactly
+            // what this row got wrong before.
+            // Named only when we know it. Without `publishConfig.registry` npm used
+            // whatever the client's own config points at, and we do not know what that
+            // was — "at the registry" would be filler dressed up as information.
+            const host = target.registry ? new URL(target.registry).host : null;
+            const at = host ? ` at ${host}` : '';
+            const reason = {
+                absent: `nothing published under this name${at} yet`,
+                unauthenticated: `no credentials for ${host ?? 'the registry'}`,
+                unreadable: `could not read the published version${at}`,
+            }[remote.failure];
+            return (0, types_1.skip)(reason);
+        }
+        const previous = remote.manifest;
+        const delta = current.unpackedSize - previous.unpackedSize;
+        const growth = previous.unpackedSize > 0 ? (delta / previous.unpackedSize) * 100 : 0;
+        const summary = `${mb(previous.unpackedSize)} → ${mb(current.unpackedSize)} ` +
+            `(${growth >= 0 ? '+' : ''}${growth.toFixed(1)}%) vs ${previous.version}`;
+        if (growth <= maxGrowth) {
+            utils_1.logger.info(`[Package Size]: ✅ ${summary}`);
+            return (0, types_1.pass)(summary);
+        }
+        (0, findings_1.logSample)('Package Size', `${summary}:`, growthByFile(previous.files, current.files));
+        return (0, types_1.warn)(summary);
+    },
+};

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/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"));
@@ -102,7 +103,28 @@ function resolveCacheDir(version, configured, env = process.env) {
     }
     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");
@@ -32,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.
@@ -67,14 +86,15 @@ async function installProfiles(cwd = process.cwd(), all = false) {
         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.
@@ -108,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 {};