pr-checkmate 2.1.2 → 3.0.0

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

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.diffSecurityCheck = void 0;
 const config_1 = require("../../../config");
 const utils_1 = require("../../../utils");
-const targets_1 = require("../../targets");
 const types_1 = require("../../types");
 const findings_1 = require("../findings");
 const MD5_LABEL = 'MD5 (weak hash — use sha256 or stronger)';
@@ -298,6 +297,9 @@ exports.diffSecurityCheck = {
                 // to them, matching `duplicate.ignore` and `deadCode.ignoreFiles`. A client
                 // who wants their tests scanned says so by listing something else here.
                 ignorePaths: cfg.ignorePaths ?? config_1.DIFF_SECURITY_IGNORE_DEFAULTS,
+                // This check owns the cross-line heuristic, so it is the one that turns it
+                // on. `0` from the client switches it off.
+                dataflowWindow: cfg.dataflowWindow ?? findings_1.DEFAULT_DATAFLOW_WINDOW,
             };
             const extra = compileExtraPatterns(ctx);
             const disabled = cfg.disablePatterns ?? [];
@@ -306,33 +308,39 @@ exports.diffSecurityCheck = {
             };
             /**
              * Feed one language's sources through the patterns, from the diff when
-             * there is one and from the files themselves otherwise. Both paths reach
-             * `scanDiffPatterns` in the same shape, so the two modes cannot disagree
-             * about what counts as a finding.
+             * there is one and from the files themselves otherwise.
+             *
+             * Through {@link reviewLines}, like the four other checks that need both
+             * modes. This used to be its body copied inline, on the assumption that a
+             * closure was needed to carry `patterns` — it is not, that is what `onChunk`
+             * is for, and the copy meant `fullScanBehaviour` and the `null`/`[]`
+             * distinction lived in two places, one of them a blocking security check
+             * (ticket 079).
              */
-            const review = async (globs, patterns) => {
-                if (ctx.baseSha) {
-                    scanInto(await (0, findings_1.diffAddedLines)(ctx, globs), patterns);
-                    return;
-                }
-                if (ctx.config.run?.fullScanBehaviour === 'skip')
-                    return;
-                const files = await (0, targets_1.listTrackedFiles)(ctx, globs, ['.']);
-                await (0, findings_1.scanTrackedFiles)(ctx, files, asDiff => scanInto(asDiff, patterns));
-            };
+            const review = (globs, patterns) => (0, findings_1.reviewLines)(ctx, globs, stdout => scanInto(stdout, patterns));
             // JS/TS patterns always run; language-specific sets scan their own globs
             // only when that language is present, so a Python repo gets Python rules.
             // Client `extraPatterns` run against every scanned language, since a
             // project rule is not tied to the built-in language split.
-            await review(JS_GLOBS, [...SECURITY_PATTERNS, ...extra]);
+            const sets = [[JS_GLOBS, [...SECURITY_PATTERNS, ...extra]]];
             if (ctx.languages.includes('python')) {
-                await review(['*.py'], [...PYTHON_SECURITY_PATTERNS, ...extra]);
+                sets.push([['*.py'], [...PYTHON_SECURITY_PATTERNS, ...extra]]);
             }
             if (ctx.languages.includes('go')) {
-                await review(['*.go'], [...GO_SECURITY_PATTERNS, ...extra]);
+                sets.push([['*.go'], [...GO_SECURITY_PATTERNS, ...extra]]);
             }
             if (ctx.languages.includes('kotlin')) {
-                await review(['*.kt', '*.kts', '*.java'], [...KOTLIN_SECURITY_PATTERNS, ...extra]);
+                sets.push([
+                    ['*.kt', '*.kts', '*.java'],
+                    [...KOTLIN_SECURITY_PATTERNS, ...extra],
+                ]);
+            }
+            for (const [globs, patterns] of sets) {
+                // One failed set fails the check. A partial answer is worse than none
+                // here: three of five language sets scanned, reported as a pass, reads
+                // as a clean repository (ticket 072).
+                if (!(await review(globs, patterns)))
+                    return (0, types_1.skip)('git unavailable');
             }
             return (0, findings_1.reportSeverityBuckets)(found.errors, found.warnings, {
                 prefix: 'Diff Security',

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

@@ -30,7 +30,13 @@ const DOCKER_PATTERNS = [
         severity: 'warn',
     },
     {
-        pattern: /^\+(?!\+)\s*(?:ENV|ARG)\s+\w*(?:PASSWORD|SECRET|TOKEN|API_?KEY|ACCESS_KEY)\w*\s*[=\s]/i,
+        // The `_FILE`/`_PATH` exclusion is not a loophole, it is the thing this rule
+        // is trying to steer people towards: `ENV DB_PASSWORD_FILE=/run/secrets/db`
+        // names a location, holds no secret, and is how Docker and Kubernetes tell
+        // you to do it. Flagging the correct practice alongside the wrong one is how
+        // a rule gets switched off — and it teaches obscuring the variable name,
+        // which makes the next real secret harder to spot, not easier.
+        pattern: /^\+(?!\+)\s*(?:ENV|ARG)\s+\w*(?:PASSWORD|SECRET|TOKEN|API_?KEY|ACCESS_KEY)\w*(?<!_FILE)(?<!_PATH)(?<!_FILEPATH)\s*[=\s]/i,
         label: 'secret baked into ENV/ARG (use build secrets / runtime injection)',
         severity: 'warn',
     },

package/dist/core/checks/security/migration-safety.js

@@ -48,17 +48,45 @@ function isAddNotNullNoDefault(line) {
         /\bNOT\s+NULL\b/i.test(line) &&
         !/\bDEFAULT\b/i.test(line));
 }
+/**
+ * Drop the comment from an added migration line, keeping the leading `+` so the
+ * patterns stay anchored on it.
+ *
+ * This check does its own matching rather than going through `scanDiffPatterns`,
+ * and it inherited none of the comment handling — so a commented-out statement
+ * was reported as destructive. `-- DROP TABLE users;` does nothing, and calling
+ * it "irreversible data loss" is noise on the most alarming label the product
+ * prints. Found by ticket 062's corpus.
+ *
+ * Only the two markers that are unambiguous in the files this check looks at:
+ * `--` in SQL and `#` in Python/Ruby migrations. `--` is required to be preceded
+ * by whitespace or the line start, which keeps it away from an identifier like
+ * `a--b` and from most string contents; `stripInlineComment` handles `#` with the
+ * string awareness it already has.
+ */
+function withoutComment(line) {
+    // The diff marker is split off first: `+-- DROP TABLE` puts `--` immediately
+    // after the `+`, where a boundary rule looking for whitespace or line-start
+    // does not see it — which is exactly the shape a commented-out statement takes.
+    const marker = line.startsWith('+') ? '+' : '';
+    const body = (0, findings_1.stripInlineComment)(line.slice(marker.length), 'hash').replace(/(^|\s)--.*$/, '$1');
+    return marker + body;
+}
 /** Bucket dangerous added lines by risk label, honouring the opt-out directive. */
 function scan(stdout, findings) {
     for (const line of stdout.split('\n')) {
         if (line.includes('pr-checkmate-ignore'))
             continue;
+        // The sample keeps the ORIGINAL line: the reader needs to see what was
+        // written, comment and all, even though the match ran on the code.
+        const code = withoutComment(line);
+        const sample = () => line.slice(1).trim().substring(0, 120);
         for (const { pattern, label } of DDL_PATTERNS) {
-            if (pattern.test(line))
-                (findings[label] ?? (findings[label] = [])).push(line.slice(1).trim().substring(0, 120));
+            if (pattern.test(code))
+                (findings[label] ?? (findings[label] = [])).push(sample());
         }
-        if (isAddNotNullNoDefault(line)) {
-            (findings[NOT_NULL_NO_DEFAULT] ?? (findings[NOT_NULL_NO_DEFAULT] = [])).push(line.slice(1).trim().substring(0, 120));
+        if (isAddNotNullNoDefault(code)) {
+            (findings[NOT_NULL_NO_DEFAULT] ?? (findings[NOT_NULL_NO_DEFAULT] = [])).push(sample());
         }
     }
 }

package/dist/core/checks/security/security.d.ts

@@ -1,4 +1,60 @@
 import { Check } from '../../types';
+/**
+ * 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 declare function countFindings(reportPath: string): number | 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 declare function secretsSummary(found: number | null): string;
+/**
+ * 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 declare function looksLikeCrash(stderr: string): boolean;
 /**
  * Secret scanning via the bundled gitleaks package. Language-agnostic — runs on
  * every repo (Node, Python, C++, mobile). Secrets found → fail (blocking).

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

@@ -1,10 +1,107 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.securityCheck = void 0;
+exports.countFindings = countFindings;
+exports.secretsSummary = secretsSummary;
+exports.looksLikeCrash = looksLikeCrash;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("../../../config");
 const utils_1 = require("../../../utils");
 const execa_1 = require("../../../utils/execa");
 const types_1 = require("../../types");
+/**
+ * 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.
+ */
+function countFindings(reportPath) {
+    try {
+        const report = JSON.parse(node_fs_1.default.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.
+ */
+function secretsSummary(found) {
+    return found === null ? 'potential secrets detected' : `${found} potential secret(s)`;
+}
+function writableHome() {
+    const home = node_os_1.default.homedir();
+    try {
+        node_fs_1.default.accessSync(home, node_fs_1.default.constants.W_OK);
+        return home;
+    }
+    catch { }
+    const fallback = node_os_1.default.tmpdir();
+    try {
+        node_fs_1.default.accessSync(fallback, node_fs_1.default.constants.W_OK);
+        utils_1.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.
+ */
+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).
@@ -29,11 +126,7 @@ exports.securityCheck = {
             utils_1.logger.warn('[Security Scan]: ⚠️ bundled gitleaks scanner could not be resolved — skipping');
             return (0, types_1.skip)('gitleaks unavailable');
         }
-        const hasClientConfig = (0, config_1.hasLocalConfig)([
-            '.gitleaks.toml',
-            'gitleaks.toml',
-            '.gitleaks/config.toml',
-        ]);
+        const hasClientConfig = (0, config_1.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
@@ -62,25 +155,56 @@ exports.securityCheck = {
         if (!hasClientConfig) {
             args.push('--config', (0, config_1.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 = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'pr-checkmate-gitleaks-'));
+        const reportPath = node_path_1.default.join(reportDir, 'findings.json');
+        args.push('--report-format', 'json', '--report-path', reportPath);
         utils_1.logger.info(`[Security Scan]: scanning ${isDelta ? 'the diff range' : `full history${depth ? ` (last ${depth} commits)` : ''}`}`);
+        const home = writableHome();
+        if (!home)
+            return (0, types_1.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 (0, execa_1.execa)(process.execPath, [gitleaksBin, ...args], {
             cwd: ctx.cwd,
             env,
-            stdio: 'inherit',
+            stdio: ['ignore', 'inherit', 'pipe'],
             reject: false,
         });
+        const stderr = String(result.stderr ?? '');
+        if (stderr.trim())
+            utils_1.logger.warn(stderr.trimEnd());
+        const found = countFindings(reportPath);
+        node_fs_1.default.rmSync(reportDir, { recursive: true, force: true });
         if (result.exitCode === 0)
             return (0, types_1.pass)();
-        // gitleaks exits 1 specifically when it finds secrets — that is a real violation.
-        if (result.exitCode === 1) {
-            utils_1.logger.warn('⚠️ gitleaks found potential secrets — review gitleaks-report.html');
-            return (0, types_1.fail)('potential secrets detected');
+        // 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);
+            utils_1.logger.warn(`⚠️ gitleaks found ${summary} — see the findings above`);
+            return (0, types_1.fail)(summary);
         }
-        return (0, types_1.warn)(`scanner error (exit ${result.exitCode})`);
+        const detail = looksLikeCrash(stderr)
+            ? 'scanner failed to start — nothing was scanned'
+            : `scanner error (exit ${result.exitCode})`;
+        utils_1.logger.warn(`[Security Scan]: ⚠️ ${detail}`);
+        return (0, types_1.warn)(detail);
     },
 };

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}`);
+}