pr-checkmate 3.0.4 → 3.1.0

package/dist/esm/core/checks/security/security.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getPackageConfigPath, hasLocalConfig } from '../../../config/index.js';
+import { execa } from '../../../utils/execa.js';
+import { logger, resolveGitRef, resolvePackageBin } from '../../../utils/index.js';
+import { pass, fail, warn, skip } from '../../types.js';
+/**
+ * A HOME the scanner can actually write to.
+ *
+ * The bundled wrapper caches the gitleaks binary in `os.homedir()/.gitleaks-cache`
+ * and offers no way to move it — the path is hardcoded. So in any environment
+ * where HOME is not writable it crashes before scanning a single commit. That is
+ * not exotic: it is what the container does under `--user "$(id -u):$(id -g)"`,
+ * the invocation our own entrypoint and docs recommend, where HOME is `/`.
+ *
+ * Redirecting to the temp directory costs nothing that was available anyway — if
+ * HOME cannot be written to, there was no `~/.gitconfig` of ours to lose either.
+ */
+/**
+ * How many secrets the scan actually found.
+ *
+ * The row used to read `❌ Security Scan: potential secrets detected` whether the
+ * number was one or thirty-nine, and that is not a cosmetic gap. It is the reason
+ * a real regression nearly shipped: an allowlist entry removed six genuine
+ * `Generic API Key` findings from a client repository, 39 → 33, and the A/B sweep
+ * that compares report rows across 28 repositories saw two identical lines
+ * (ticket 085). A check that finds things has to say how many, or nothing can
+ * tell whether it started finding fewer.
+ *
+ * Read from gitleaks' JSON report rather than counted out of its console output —
+ * the same lesson as ticket 078, where the clone count was parsed from an English
+ * sentence and would have reported zero on a repository full of duplication.
+ *
+ * @returns The count, or `null` when the report could not be read — in which case
+ *   the caller keeps its old wording rather than claiming a number it does not have.
+ */
+export function countFindings(reportPath) {
+    try {
+        const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+        return Array.isArray(report) ? report.length : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * How the outcome names what was found.
+ *
+ * Its own function so both halves are reachable without running the scanner. The
+ * corpus for this check deliberately does not: the wrapper downloads a gitleaks
+ * binary on first use, and a unit suite that reaches the network is the thing the
+ * `installer` seam in `ensure.ts` exists to avoid. What broke here was the wording
+ * — a row that read the same for one secret and for thirty-nine — and the wording
+ * is testable on its own.
+ *
+ * `null` keeps the old sentence rather than inventing a number: a report we could
+ * not read is not a reason to claim a count.
+ */
+export function secretsSummary(found) {
+    return found === null ? 'potential secrets detected' : `${found} potential secret(s)`;
+}
+function writableHome() {
+    const home = os.homedir();
+    try {
+        fs.accessSync(home, fs.constants.W_OK);
+        return home;
+    }
+    catch { }
+    const fallback = os.tmpdir();
+    try {
+        fs.accessSync(fallback, fs.constants.W_OK);
+        logger.info(`[Security Scan]: HOME (${home}) is not writable — caching the scanner in ${fallback}`);
+        return fallback;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the wrapper died instead of reporting, judged from its stderr.
+ *
+ * The wrapper is a Node script, and Node exits **1** on an unhandled exception —
+ * the same code gitleaks itself uses for "secrets found". Left undistinguished,
+ * a scanner that never ran is reported as `potential secrets detected`, pointing
+ * at a report file that was never written. A gate accusing a clean repository is
+ * the same class of failure as one that stays quiet about a real leak, and this
+ * is the only signal available to tell them apart.
+ */
+export function looksLikeCrash(stderr) {
+    // The errno names are written out rather than factored to a shared `E` prefix:
+    // `E(?:ACCES|PERM|…)` saves four characters and costs the reader the ability to
+    // grep for the thing they are debugging.
+    return /^\s*(?:[A-Za-z]*Error|Uncaught|node:internal)|\b(?:EACCES|EPERM|ENOENT|EROFS)\b/m.test(stderr);
+}
+/**
+ * Secret scanning via the bundled gitleaks package. Language-agnostic — runs on
+ * every repo (Node, Python, C++, mobile). Secrets found → fail (blocking).
+ * Tooling/infra errors → warn, so a scanner hiccup never blocks an unrelated PR.
+ */
+export const securityCheck = {
+    name: 'Security Scan',
+    phase: 'blocking',
+    applies(ctx) {
+        return ctx.config.security?.gitleaks?.enabled !== false;
+    },
+    async run(ctx) {
+        // A binary that cannot be resolved throws, and a throw in a blocking check is
+        // a failed PR — the client would see "Security Scan threw: Cannot resolve
+        // binary" as a red gate on a repo with no secrets in it. Every other bundled
+        // tool (knip, license-checker) already skips here; this one did not.
+        let gitleaksBin;
+        try {
+            gitleaksBin = resolvePackageBin('gitleaks-secret-scanner-fixed', 'dist/bin/cli.js');
+        }
+        catch {
+            logger.warn('[Security Scan]: ⚠️ bundled gitleaks scanner could not be resolved — skipping');
+            return skip('gitleaks unavailable');
+        }
+        const hasClientConfig = hasLocalConfig(['.gitleaks.toml', 'gitleaks.toml', '.gitleaks/config.toml'], ctx.cwd);
+        // Pin the gitleaks binary version so the scanner never reaches out to the
+        // GitHub API for the "latest" version — that network call adds latency and
+        // times out in locked-down/offline CI (the scanner already falls back to
+        // this exact version). Overridable via `security.gitleaks.version`.
+        const gitleaksVersion = ctx.config.security?.gitleaks?.version ?? '8.30.0';
+        // The scan scope has to follow the run's scope. `--diff-mode ci` REQUIRES
+        // HEAD_SHA and aborts without it, so on a full-scan run (no diff range — the
+        // local default) it exited 2 and the secret scan silently became a warning
+        // about the scanner instead of a review of the code. `history` is the only
+        // whole-repository mode the scanner offers; it walks the full commit history,
+        // which took ~1s over 700 commits here but is worth bounding on a large
+        // monorepo via `security.gitleaks.depth`.
+        const isDelta = Boolean(ctx.baseSha);
+        const depth = ctx.config.security?.gitleaks?.depth;
+        // History mode needs a repository to walk. Without one the scanner exits 2
+        // after printing `fatal: not a git repository` and "An unexpected error
+        // occurred" — alarming output about the tool, for a directory it was never
+        // able to review. Every other check skips when git is unusable; so does this.
+        if (!isDelta && !(await resolveGitRef(ctx.cwd, 'HEAD'))) {
+            return skip('git history unavailable');
+        }
+        const args = isDelta
+            ? ['--diff-mode', 'ci']
+            : ['--diff-mode', 'history', ...(depth ? ['--depth', String(depth)] : [])];
+        args.push('--gitleaks-version', gitleaksVersion);
+        if (!hasClientConfig) {
+            args.push('--config', getPackageConfigPath('gitleaks.toml'));
+        }
+        // A machine-readable copy of the findings, purely so the outcome can carry a
+        // number. Written to a temp directory, never into the repository under review:
+        // a check whose side effect is a new untracked file shows up in the client's
+        // next commit. The console output is untouched — `stdio: inherit` below still
+        // streams the scanner's own report, which is what a reader actually looks at.
+        const reportDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pr-checkmate-gitleaks-'));
+        const reportPath = path.join(reportDir, 'findings.json');
+        args.push('--report-format', 'json', '--report-path', reportPath);
+        logger.info(`[Security Scan]: scanning ${isDelta ? 'the diff range' : `full history${depth ? ` (last ${depth} commits)` : ''}`}`);
+        const home = writableHome();
+        if (!home)
+            return skip('no writable directory for the scanner cache');
+        const env = {
+            ...process.env,
+            HOME: home,
+            ...(ctx.headSha ? { HEAD_SHA: ctx.headSha } : {}),
+            ...(ctx.baseSha ? { BASE_SHA: ctx.baseSha } : {}),
+        };
+        // stdout stays inherited so the scanner's own report streams to the log as it
+        // always has; stderr is captured because it is the only thing that separates
+        // a crash from a finding — see `crashed`.
+        const result = await execa(process.execPath, [gitleaksBin, ...args], {
+            cwd: ctx.cwd,
+            env,
+            stdio: ['ignore', 'inherit', 'pipe'],
+            reject: false,
+        });
+        const stderr = String(result.stderr ?? '');
+        if (stderr.trim())
+            logger.warn(stderr.trimEnd());
+        const found = countFindings(reportPath);
+        fs.rmSync(reportDir, { recursive: true, force: true });
+        if (result.exitCode === 0)
+            return pass();
+        // gitleaks exits 1 specifically when it finds secrets — but so does Node when
+        // the wrapper around it throws. Only the second one leaves a stack trace.
+        if (result.exitCode === 1 && !looksLikeCrash(stderr)) {
+            // The findings themselves are already above, streamed from the scanner. This
+            // used to say "review gitleaks-report.html" — a file the check never wrote:
+            // `--html-report` is passed by our own `scan:secrets` npm script and by
+            // nothing else, so a blocking check told the client to open something that
+            // does not exist (ticket 085).
+            const summary = secretsSummary(found);
+            logger.warn(`⚠️ gitleaks found ${summary} — see the findings above`);
+            return fail(summary);
+        }
+        const detail = looksLikeCrash(stderr)
+            ? 'scanner failed to start — nothing was scanned'
+            : `scanner error (exit ${result.exitCode})`;
+        logger.warn(`[Security Scan]: ⚠️ ${detail}`);
+        return warn(detail);
+    },
+};

package/dist/esm/core/checks/security/sensitive-file-guard.d.ts

@@ -0,0 +1,2 @@
+import { Check } from '../../types.js';
+export declare const sensitiveFileGuardCheck: Check;

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

@@ -0,0 +1,160 @@
+import { execa } from '../../../utils/execa.js';
+import { logger, matchesAnyGlob } from '../../../utils/index.js';
+import { excludeClientPaths } from '../../targets.js';
+import { pass, skip } from '../../types.js';
+import { clientFindingOptions, reportSeverityBuckets } from '../findings.js';
+/**
+ * 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)',
+        // 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',
+    },
+    {
+        label: 'Private keys and certificates',
+        patterns: [/\.(pem|key|p12|pfx|crt|cer|der|jks|keystore)$/i],
+        severity: 'error',
+    },
+    {
+        label: 'CI/CD pipeline config',
+        patterns: [
+            /^\.github\/workflows\//,
+            /^\.gitlab-ci\.yml$/,
+            /^\.circleci\//,
+            /^\.travis\.yml$/,
+            /^Jenkinsfile$/,
+            /^\.buildkite\//,
+        ],
+        severity: 'warn',
+    },
+    {
+        label: 'Authentication / authorization middleware',
+        patterns: [
+            /\/(middleware|guards?|interceptors?)\/(auth|jwt|session|token|oauth|rbac)/i,
+            /\/(auth|jwt|session)\.(ts|js|mjs|cjs)$/i,
+        ],
+        severity: 'warn',
+    },
+    {
+        label: 'Infrastructure and deployment config',
+        patterns: [
+            /^(docker-compose|compose)\.(yml|yaml)$/,
+            /^Dockerfile(\..+)?$/,
+            /^terraform\//,
+            /\.tf$/,
+            /^\.?kubeconfig$/,
+            /^helm\//,
+        ],
+        severity: 'warn',
+    },
+    {
+        label: 'Package manager lockfiles (dependency supply chain)',
+        patterns: [/^package-lock\.json$/, /^yarn\.lock$/, /^pnpm-lock\.yaml$/],
+        severity: 'warn',
+    },
+];
+/** Bucket changed files by category severity, keyed by category label. */
+function categorizeFiles(changedFiles) {
+    var _a;
+    const errors = {};
+    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);
+            }
+        }
+    }
+    return { errors, warnings };
+}
+export const sensitiveFileGuardCheck = {
+    name: 'Sensitive Files',
+    phase: 'informational',
+    // No `requiresDiff`: a committed `.env` or private key is committed whether
+    // this PR touched it or not (ticket 067). In a full scan the question becomes
+    // "what sensitive files does this repository contain", which is the more
+    // useful one when auditing a repo rather than reviewing a change.
+    applies(ctx) {
+        return ctx.config.sensitiveFileGuard?.enabled !== false;
+    },
+    async run(ctx) {
+        try {
+            const args = ctx.baseSha
+                ? ['diff', '--name-only', '--diff-filter=ACMRD', ctx.baseSha, ctx.headSha ?? 'HEAD']
+                : ['ls-files'];
+            if (!ctx.baseSha && ctx.config.run?.fullScanBehaviour === 'skip')
+                return pass();
+            // `reject: false` so a directory that is not a repository is an ordinary
+            // outcome rather than a thrown error whose message carries git's raw
+            // `fatal: not a git repository` into the log. The check still skips — but
+            // a skip with a reason reads as a decision, while a bare `fatal:` reads as
+            // a crash, and someone has to spend time proving it was not one.
+            const result = await execa('git', args, { cwd: ctx.cwd, reject: false });
+            if (result.exitCode !== 0)
+                return skip('git unavailable');
+            const cfg = ctx.config.sensitiveFileGuard ?? {};
+            // Path exclusions are applied before categorising, so one false positive —
+            // a `.pem` test fixture, a committed `.env.example` — is excused by name.
+            // 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.
+            // `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 = excludeClientPaths(result.stdout.split('\n').filter(Boolean), ctx.cwd).filter(file => !matchesAnyGlob(file, cfg.ignorePaths ?? []));
+            if (changedFiles.length === 0)
+                return pass();
+            const { errors, warnings } = categorizeFiles(changedFiles);
+            return reportSeverityBuckets(errors, warnings, {
+                prefix: 'Sensitive Files',
+                // "changed" is only true of a diff; a full scan is answering a different
+                // question — what the repository contains — and saying otherwise would
+                // send someone looking for a change that never happened.
+                errorSummary: n => `${n} sensitive file(s) ${ctx.baseSha ? 'changed' : 'in the repo'}`,
+                warningSummary: n => `${n} notable file(s) ${ctx.baseSha ? 'changed' : 'in the repo'}`,
+                showCount: false,
+                ...clientFindingOptions(ctx, cfg),
+                // Every sensitive path is listed rather than sampled: knowing that eight
+                // files are in play but only which three is not an answer anyone can act on.
+                sampleLimit: undefined,
+            });
+        }
+        catch (err) {
+            logger.warn(`[Sensitive Files]: ⚠️ Could not check file changes\n${err}`);
+            return skip('diff unavailable');
+        }
+    },
+};

package/dist/esm/core/checks/security/workflow-security.d.ts

@@ -0,0 +1,12 @@
+import { Check } from '../../types.js';
+import { DiffPattern } from '../findings.js';
+/**
+ * GitHub Actions workflow risks, matched on added diff lines of workflow files.
+ * These are the high-frequency supply-chain / injection footguns.
+ *
+ * Exported for the corpus in `workflow-security.test.ts`: these rules turn on a
+ * context distinction subtle enough that only worked examples can hold it in
+ * place.
+ */
+export declare const WORKFLOW_PATTERNS: DiffPattern[];
+export declare const workflowSecurityCheck: Check;

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

@@ -0,0 +1,100 @@
+import { logger } from '../../../utils/index.js';
+import { listTrackedFiles } from '../../targets.js';
+import { skip } from '../../types.js';
+import { clientFindingOptions, diffAddedLines, emptyBuckets, mergeSeverityBuckets, reportSeverityBuckets, scanDiffPatterns, scanTrackedFiles, } from '../findings.js';
+/**
+ * A YAML key binding — `HEAD_REF: ${{ … }}`, `ref: ${{ … }}` — rather than an
+ * interpolation inside a script body.
+ *
+ * This is the distinction the rules below turn on. Binding an untrusted value to
+ * an `env:` entry or an action input is *the recommended fix*: the value reaches
+ * the shell as data, expanded after parsing. Flagging it made the check punish
+ * the exact remediation it recommends, which is worse than not checking at all —
+ * a warning on correct code teaches people to ignore the warnings.
+ *
+ * The risky shape is the same expression inside a `run:` block, where GitHub
+ * substitutes it into the script *before* the shell parses it.
+ */
+const YAML_KEY_BINDING = String.raw `(?!\s*[\w.-]+:\s*\$\{\{)`;
+/**
+ * GitHub Actions workflow risks, matched on added diff lines of workflow files.
+ * These are the high-frequency supply-chain / injection footguns.
+ *
+ * Exported for the corpus in `workflow-security.test.ts`: these rules turn on a
+ * context distinction subtle enough that only worked examples can hold it in
+ * place.
+ */
+export const WORKFLOW_PATTERNS = [
+    {
+        // Untrusted PR-controlled input interpolated into an expression — the classic
+        // `run:` script-injection vector when it reaches a shell.
+        pattern: new RegExp([
+            String.raw `^\+(?!\+)${YAML_KEY_BINDING}.*\$\{\{\s*github\.event\.`,
+            String.raw `(?:issue|pull_request|comment|review|discussion|head_commit|commits)[^}]*`,
+            String.raw `\.(?:title|body|head_ref|ref|label|name|email|message|url)`,
+        ].join('')),
+        label: 'untrusted github.event input in expression (script injection risk)',
+        severity: 'error',
+    },
+    {
+        pattern: new RegExp(String.raw `^\+(?!\+)${YAML_KEY_BINDING}.*\$\{\{\s*github\.head_ref\s*\}\}`),
+        label: 'github.head_ref interpolation (injection risk — use an env var)',
+        severity: 'warn',
+    },
+    {
+        // Third-party action not pinned to a full 40-char commit SHA.
+        pattern: /^\+(?!\+).*\buses:\s*['"]?[\w.-]+\/[\w.-]+@(?![0-9a-fA-F]{40}\b)[\w./-]+/,
+        label: 'action not pinned to a full commit SHA (supply-chain risk)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+).*\bpull_request_target\b/,
+        label: 'pull_request_target trigger (runs with repo secrets on untrusted PRs)',
+        severity: 'warn',
+    },
+];
+export const workflowSecurityCheck = {
+    name: 'Workflow Security',
+    phase: 'informational',
+    // No `requiresDiff`: an injectable workflow is injectable whether the line
+    // arrived in this PR or long before it (ticket 067). Ours had lived there for
+    // months when ticket 060 found it — by hand, because no mode looked.
+    applies(ctx) {
+        return ctx.config.workflowSecurity?.enabled !== false;
+    },
+    async run(ctx) {
+        try {
+            const globs = ['.github/workflows/*.yml', '.github/workflows/*.yaml'];
+            const cfg = ctx.config.workflowSecurity ?? {};
+            const found = emptyBuckets();
+            const scanInto = (stdout) => {
+                // `diffAddedLines` already dropped `pr-checkmate-ignore` lines, and
+                // `scanTrackedFiles` does the same for the whole-file path.
+                mergeSeverityBuckets(found, scanDiffPatterns(stdout, WORKFLOW_PATTERNS, { ignorePaths: cfg.ignorePaths }));
+            };
+            if (ctx.baseSha) {
+                scanInto(await diffAddedLines(ctx, globs));
+            }
+            else if (ctx.config.run?.fullScanBehaviour !== 'skip') {
+                // `.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 listTrackedFiles(ctx, globs, ['.'], {
+                    keepDirs: ['.github', '.gitlab', '.circleci'],
+                });
+                if (files === null)
+                    return skip('git unavailable');
+                await scanTrackedFiles(ctx, files, scanInto);
+            }
+            return reportSeverityBuckets(found.errors, found.warnings, {
+                prefix: 'Workflow Security',
+                errorSummary: n => `${n} issue(s)`,
+                warningSummary: n => `${n} warning(s)`,
+                ...clientFindingOptions(ctx, cfg),
+            });
+        }
+        catch (err) {
+            logger.warn(`[Workflow Security]: ⚠️ Could not analyze diff\n${err}`);
+            return skip('diff unavailable');
+        }
+    },
+};

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

@@ -0,0 +1,102 @@
+import { CheckOutcome } from '../types.js';
+/**
+ * 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/esm/core/checks/tool-install.js

@@ -0,0 +1,66 @@
+import { skip } from '../types.js';
+/**
+ * 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`).
+ */
+export function notInstalled(tool, label) {
+    const { command, url } = INSTALL_HINTS[tool];
+    const subject = label ? `${label} not installed` : 'not installed';
+    return skip(command ? `${subject} — ${command} · ${url}` : `${subject} — ${url}`);
+}