pr-checkmate 1.23.24 → 2.1.0

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

@@ -65,8 +65,11 @@ function scan(stdout, findings) {
 exports.migrationSafetyCheck = {
     name: 'Migration Safety',
     phase: 'informational',
+    // No `requiresDiff`: a destructive migration is destructive whenever it was
+    // written (ticket 067). Over a whole repository this becomes an inventory of
+    // the irreversible migrations already in the history, which is worth having.
     applies(ctx) {
-        return ctx.config.migrationSafety?.enabled !== false && Boolean(ctx.baseSha);
+        return ctx.config.migrationSafety?.enabled !== false;
     },
     async run(ctx) {
         // Not sourcePath-scoped: migrations commonly live outside `src` (db/, alembic/).
@@ -79,28 +82,27 @@ exports.migrationSafetyCheck = {
         if (migrationFiles.length === 0)
             return (0, types_1.pass)();
         try {
-            const { stdout } = await (0, execa_1.execa)('git', [
-                'diff',
-                '--unified=0',
-                ctx.baseSha,
-                ctx.headSha ?? 'HEAD',
-                '--',
-                ...migrationFiles,
-            ], { cwd: ctx.cwd });
+            let stdout = '';
+            if (ctx.baseSha) {
+                stdout = (await (0, execa_1.execa)('git', ['diff', '--unified=0', ctx.baseSha, ctx.headSha ?? 'HEAD', '--', ...migrationFiles], { cwd: ctx.cwd })).stdout;
+            }
+            else if (ctx.config.run?.fullScanBehaviour !== 'skip') {
+                await (0, findings_1.scanTrackedFiles)(ctx, migrationFiles, asDiff => {
+                    stdout += `${asDiff}\n`;
+                });
+            }
             const findings = {};
             scan(stdout, findings);
             if ((0, findings_1.bucketTotal)(findings) === 0)
                 return (0, types_1.pass)();
-            const sev = (0, findings_1.severityEmitter)(ctx.config.migrationSafety?.severity, 'warn');
-            (0, findings_1.logFindings)(findings, {
+            return (0, findings_1.reportCountedFindings)(findings, ctx, {
                 prefix: 'Migration Safety',
-                sampleLimit: 2,
-                isError: sev.icon === '❌',
+                severity: ctx.config.migrationSafety?.severity,
+                sampleLimit: ctx.config.log?.sampleLimit ?? 2,
+                // The labels carry an explanatory tail ("… — rewrites every row"); the
+                // summary is a one-line tally, so only the name of the risk fits.
+                summaryLabel: label => label.split(' — ')[0],
             });
-            const summary = Object.entries(findings)
-                .map(([label, arr]) => `${arr.length}× ${label.split(' — ')[0]}`)
-                .join(', ');
-            return sev.emit(summary);
         }
         catch (err) {
             utils_1.logger.warn(`[Migration Safety]: ⚠️ Could not analyze diff\n${err}`);

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

@@ -72,21 +72,53 @@ function categorizeFiles(changedFiles) {
 exports.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 && Boolean(ctx.baseSha);
+        return ctx.config.sensitiveFileGuard?.enabled !== false;
     },
     async run(ctx) {
         try {
-            const { stdout } = await (0, execa_1.execa)('git', ['diff', '--name-only', '--diff-filter=ACMRD', ctx.baseSha, 'HEAD'], { cwd: ctx.cwd });
-            const changedFiles = stdout.split('\n').filter(Boolean);
+            const args = ctx.baseSha
+                ? ['diff', '--name-only', '--diff-filter=ACMRD', ctx.baseSha, 'HEAD']
+                : ['ls-files'];
+            if (!ctx.baseSha && ctx.config.run?.fullScanBehaviour === 'skip')
+                return (0, types_1.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 (0, execa_1.execa)('git', args, { cwd: ctx.cwd, reject: false });
+            if (result.exitCode !== 0)
+                return (0, types_1.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.
+            const changedFiles = result.stdout
+                .split('\n')
+                .filter(Boolean)
+                .filter(file => !(0, utils_1.matchesAnyGlob)(file, cfg.ignorePaths ?? []));
             if (changedFiles.length === 0)
                 return (0, types_1.pass)();
             const { errors, warnings } = categorizeFiles(changedFiles);
             return (0, findings_1.reportSeverityBuckets)(errors, warnings, {
                 prefix: 'Sensitive Files',
-                errorSummary: n => `${n} sensitive file(s) changed`,
-                warningSummary: n => `${n} notable file(s) changed`,
+                // "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,
+                ...(0, findings_1.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) {

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

@@ -1,2 +1,12 @@
 import { Check } from '../../types';
+import { DiffPattern } from '../findings';
+/**
+ * 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/core/checks/security/workflow-security.js

@@ -1,23 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.workflowSecurityCheck = void 0;
+exports.workflowSecurityCheck = exports.WORKFLOW_PATTERNS = void 0;
 const utils_1 = require("../../../utils");
+const targets_1 = require("../../targets");
 const types_1 = require("../../types");
 const findings_1 = require("../findings");
+/**
+ * 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.
  */
-const WORKFLOW_PATTERNS = [
+exports.WORKFLOW_PATTERNS = [
     {
         // Untrusted PR-controlled input interpolated into an expression — the classic
         // `run:` script-injection vector when it reaches a shell.
-        pattern: /^\+(?!\+).*\$\{\{\s*github\.event\.(?:issue|pull_request|comment|review|discussion|head_commit|commits)[^}]*\.(?:title|body|head_ref|ref|label|name|email|message|url)/,
+        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: /^\+(?!\+).*\$\{\{\s*github\.head_ref\s*\}\}/,
+        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',
     },
@@ -33,38 +56,37 @@ const WORKFLOW_PATTERNS = [
         severity: 'warn',
     },
 ];
-function scanDiff(stdout) {
-    const errors = {};
-    const warnings = {};
-    for (const line of stdout.split('\n')) {
-        for (const { pattern, label, severity } of WORKFLOW_PATTERNS) {
-            if (pattern.test(line)) {
-                const bucket = severity === 'error' ? errors : warnings;
-                (bucket[label] ?? (bucket[label] = [])).push(line.slice(1).trim().substring(0, 120));
-            }
-        }
-    }
-    return { errors, warnings };
-}
 exports.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 && Boolean(ctx.baseSha);
+        return ctx.config.workflowSecurity?.enabled !== false;
     },
     async run(ctx) {
         try {
-            const stdout = await (0, findings_1.diffAddedLines)(ctx, [
-                '.github/workflows/*.yml',
-                '.github/workflows/*.yaml',
-            ]);
-            const { errors, warnings } = scanDiff(stdout);
-            return (0, findings_1.reportSeverityBuckets)(errors, warnings, {
+            const globs = ['.github/workflows/*.yml', '.github/workflows/*.yaml'];
+            const cfg = ctx.config.workflowSecurity ?? {};
+            const found = (0, findings_1.emptyBuckets)();
+            const scanInto = (stdout) => {
+                // `diffAddedLines` already dropped `pr-checkmate-ignore` lines, and
+                // `scanTrackedFiles` does the same for the whole-file path.
+                (0, findings_1.mergeSeverityBuckets)(found, (0, findings_1.scanDiffPatterns)(stdout, exports.WORKFLOW_PATTERNS, { ignorePaths: cfg.ignorePaths }));
+            };
+            if (ctx.baseSha) {
+                scanInto(await (0, findings_1.diffAddedLines)(ctx, globs));
+            }
+            else if (ctx.config.run?.fullScanBehaviour !== 'skip') {
+                const files = await (0, targets_1.listTrackedFiles)(ctx, globs, ['.']);
+                await (0, findings_1.scanTrackedFiles)(ctx, files, scanInto);
+            }
+            return (0, findings_1.reportSeverityBuckets)(found.errors, found.warnings, {
                 prefix: 'Workflow Security',
                 errorSummary: n => `${n} issue(s)`,
                 warningSummary: n => `${n} warning(s)`,
-                sampleLimit: 3,
-                ignore: ctx.config.workflowSecurity?.ignore,
+                ...(0, findings_1.clientFindingOptions)(ctx, cfg),
             });
         }
         catch (err) {

package/dist/core/commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CLI vocabulary, kept out of `cli.ts` so it can be imported without side
+ * effects: that module is an executable entry point — it parses `process.argv`
+ * and calls `process.exit` at import time, so anything importing it to read
+ * these tables would run the CLI instead.
+ *
+ * Separating them is what lets `commands.test.ts` assert the invariant that
+ * matters here: every command must resolve to a check that actually exists.
+ * A command pointing at a name no longer in the registry does not error — the
+ * `only` filter simply matches nothing, every check is filtered out, and the run
+ * reports success having verified nothing at all.
+ */
+/** Maps short CLI command names to their registry check names. */
+export declare const COMMAND_TO_CHECK: Record<string, string>;
+/**
+ * Commands that run the whole pipeline (or no pipeline at all) and take no siblings.
+ *
+ * The three install commands are here rather than in {@link COMMAND_TO_CHECK}
+ * because they run no checks at all: they manage the tooling the checks need.
+ * `doctor` in particular is the answer to "why did my typecheck not run" once
+ * tooling is fetched on demand — a question that must have a command behind it
+ * and not a reading of our source.
+ */
+export declare const TOOLING_COMMANDS: readonly string[];
+export declare const STANDALONE_COMMANDS: readonly string[];
+/** Flags accepted anywhere on the command line, with what each one means. */
+export declare const FLAGS: Record<string, string>;

package/dist/core/commands.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * CLI vocabulary, kept out of `cli.ts` so it can be imported without side
+ * effects: that module is an executable entry point — it parses `process.argv`
+ * and calls `process.exit` at import time, so anything importing it to read
+ * these tables would run the CLI instead.
+ *
+ * Separating them is what lets `commands.test.ts` assert the invariant that
+ * matters here: every command must resolve to a check that actually exists.
+ * A command pointing at a name no longer in the registry does not error — the
+ * `only` filter simply matches nothing, every check is filtered out, and the run
+ * reports success having verified nothing at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLAGS = exports.STANDALONE_COMMANDS = exports.TOOLING_COMMANDS = exports.COMMAND_TO_CHECK = void 0;
+/** Maps short CLI command names to their registry check names. */
+exports.COMMAND_TO_CHECK = {
+    // Every check that can fail a run is reachable on its own, so "why does this
+    // block me" is answered by running that one check instead of the whole suite.
+    'merge-conflict': 'Merge Conflict',
+    lint: 'ESLint',
+    deps: 'Dependencies',
+    dependencies: 'Dependencies',
+    'npm-audit': 'NPM Audit',
+    prettier: 'Prettier',
+    spellcheck: 'Spellcheck',
+    security: 'Security Scan',
+    circular: 'Circular Deps',
+    license: 'License Check',
+    'pr-size': 'PR Size',
+    'pr-title': 'PR Title',
+    outdated: 'Outdated Deps',
+    markdown: 'Markdown',
+    'yaml-lint': 'YAML Lint',
+    symlinks: 'Broken Symlinks',
+    shellcheck: 'ShellCheck',
+    typecheck: 'TypeScript',
+    'diff-smell': 'Diff Smells',
+    'diff-security': 'Diff Security',
+    'workflow-security': 'Workflow Security',
+    'custom-rules': 'Custom Rules',
+    'banned-imports': 'Banned Imports',
+    'license-header': 'License Header',
+    'config-validation': 'Config Validation',
+    'dockerfile-security': 'Dockerfile Security',
+    'case-collision': 'Case Collision',
+    'vuln-scan': 'Vuln Scan',
+    'leftover-debug': 'Leftover Debug',
+    'lockfile-drift': 'Lockfile Drift',
+    'large-files': 'Large Files',
+    'todo-fixme': 'TODO/FIXME',
+    'missing-tests': 'Missing Tests',
+    coverage: 'Coverage',
+    'migration-safety': 'Migration Safety',
+    'sensitive-files': 'Sensitive Files',
+    'pr-body': 'PR Body',
+    duplicate: 'Duplicate Code',
+    commitlint: 'Commitlint',
+    'cpp-format': 'C++ Format',
+    'python-lint': 'Ruff Lint',
+    'python-format': 'Ruff Format',
+    'python-typecheck': 'Python Types',
+    'go-lint': 'Go Vet',
+    'go-format': 'Go Format',
+    'rust-lint': 'Clippy',
+    'rust-format': 'Rustfmt',
+    'csharp-format': 'C# Format',
+    'ruby-lint': 'RuboCop',
+    'php-format': 'PHP CS Fixer',
+};
+/**
+ * Commands that run the whole pipeline (or no pipeline at all) and take no siblings.
+ *
+ * The three install commands are here rather than in {@link COMMAND_TO_CHECK}
+ * because they run no checks at all: they manage the tooling the checks need.
+ * `doctor` in particular is the answer to "why did my typecheck not run" once
+ * tooling is fetched on demand — a question that must have a command behind it
+ * and not a reading of our source.
+ */
+exports.TOOLING_COMMANDS = ['install', 'doctor', 'cache-prune'];
+exports.STANDALONE_COMMANDS = [
+    'init',
+    'all',
+    'precommit',
+    ...exports.TOOLING_COMMANDS,
+];
+/** Flags accepted anywhere on the command line, with what each one means. */
+exports.FLAGS = {
+    '--full': 'review every tracked file instead of the diff (the default outside CI)',
+    '--all': 'with "install": fetch every profile, not only the ones this repository needs',
+};

package/dist/core/context.d.ts

@@ -22,6 +22,8 @@ type RangePlan = {
     headSha?: string;
 } | {
     kind: 'github-event';
+} | {
+    kind: 'branch';
 } | {
     kind: 'ref';
     ref: string;
@@ -37,9 +39,16 @@ type RangePlan = {
  *    branch) — a gate exists to judge the diff.
  * 4. A CI build with no PR context still diffs `HEAD^`: it is a push/branch build,
  *    and delta is why CI runs are fast.
- * 5. Anything else is a human at a terminal → full scan. `HEAD^` used to be the
- *    fallback here, which meant a local `pr-checkmate all` judged only the last
- *    commit and could report a clean project with a `debugger` committed earlier.
+ * 5. Anything else is a human at a terminal, working on a branch → review what the
+ *    branch changed, i.e. everything since it diverged from the default branch.
+ *    That is the same set of changes a pull request would show, which is what
+ *    someone running the tool before opening one is asking about.
+ *
+ *    `HEAD^` was tried here once and was wrong for a different reason: it judged
+ *    only the last commit, so a `debugger` committed earlier on the branch passed.
+ *    The merge base has neither problem — it covers every commit on the branch —
+ *    and on the default branch itself, where there is nothing to diverge from,
+ *    {@link resolveDiffRange} falls back to a full scan.
  *
  * @param opts Run options as passed to `runChecks`.
  * @param env Environment to read CI markers from. Defaults to the current process.

package/dist/core/context.js

@@ -20,9 +20,16 @@ const execa_1 = require("../utils/execa");
  *    branch) — a gate exists to judge the diff.
  * 4. A CI build with no PR context still diffs `HEAD^`: it is a push/branch build,
  *    and delta is why CI runs are fast.
- * 5. Anything else is a human at a terminal → full scan. `HEAD^` used to be the
- *    fallback here, which meant a local `pr-checkmate all` judged only the last
- *    commit and could report a clean project with a `debugger` committed earlier.
+ * 5. Anything else is a human at a terminal, working on a branch → review what the
+ *    branch changed, i.e. everything since it diverged from the default branch.
+ *    That is the same set of changes a pull request would show, which is what
+ *    someone running the tool before opening one is asking about.
+ *
+ *    `HEAD^` was tried here once and was wrong for a different reason: it judged
+ *    only the last commit, so a `debugger` committed earlier on the branch passed.
+ *    The merge base has neither problem — it covers every commit on the branch —
+ *    and on the default branch itself, where there is nothing to diverge from,
+ *    {@link resolveDiffRange} falls back to a full scan.
  *
  * @param opts Run options as passed to `runChecks`.
  * @param env Environment to read CI markers from. Defaults to the current process.
@@ -47,20 +54,30 @@ function planDiffRange(opts, env = process.env) {
     }
     if ((0, utils_1.isCiEnvironment)(env))
         return { kind: 'ref', ref: 'HEAD^', reason: 'CI build, no PR context' };
-    return { kind: 'full', reason: 'no CI detected' };
+    return { kind: 'branch' };
 }
+/** A full scan the caller or the environment asked for, not one we fell back to. */
+const intended = (reason) => ({ kind: 'full', reason, degraded: false });
+/**
+ * A full scan we ended up with because a diff range could not be built. The
+ * distinction matters: the delta-only checks drop out either way, but here that
+ * is a symptom (shallow clone, missing base) rather than the intent — and it is
+ * the case worth telling the client about, because it silently removes most of
+ * the security surface.
+ */
+const degraded = (reason) => ({ kind: 'full', reason, degraded: true });
 /**
  * Carry out a {@link RangePlan}. Every path that cannot produce a usable base
  * commit returns no SHAs, which the checks read as "scan everything" — degrading
  * to a full scan is always safer than diffing against a ref that isn't there and
  * silently reviewing nothing.
  *
- * @returns The resolved range, plus a label for the log line.
+ * @returns The resolved range, plus the scope that produced it.
  */
 async function resolveDiffRange(cwd, opts) {
     const plan = planDiffRange(opts, process.env);
     if (plan.kind === 'full')
-        return { scope: `full (${plan.reason})` };
+        return { scope: intended(plan.reason) };
     // Pre-commit mode: diff HEAD against the current index. `git write-tree`
     // materialises the staged index as a real tree object, so every check that
     // diffs baseSha..headSha sees exactly the staged changes — no per-check code.
@@ -68,14 +85,18 @@ async function resolveDiffRange(cwd, opts) {
         try {
             const head = (await (0, execa_1.execa)('git', ['rev-parse', 'HEAD'], { cwd })).stdout.trim();
             const tree = (await (0, execa_1.execa)('git', ['write-tree'], { cwd })).stdout.trim();
-            return { baseSha: head, headSha: tree, scope: 'staged' };
+            return { baseSha: head, headSha: tree, scope: { kind: 'staged', degraded: false } };
         }
         catch {
-            return { scope: 'full (no staged range)' };
+            return { scope: degraded('no staged range') };
         }
     }
     if (plan.kind === 'explicit') {
-        return { baseSha: plan.baseSha, headSha: plan.headSha, scope: 'delta (explicit)' };
+        return {
+            baseSha: plan.baseSha,
+            headSha: plan.headSha,
+            scope: { kind: 'delta', reason: 'explicit', degraded: false },
+        };
     }
     let headSha;
     try {
@@ -83,7 +104,7 @@ async function resolveDiffRange(cwd, opts) {
         headSha = stdout.trim();
     }
     catch {
-        return { scope: 'full (no HEAD)' };
+        return { scope: degraded('no HEAD') };
     }
     // GitHub Actions: the PR event payload carries the base branch SHA. Read it
     // directly so delta works without relying on any client-set variable
@@ -95,19 +116,69 @@ async function resolveDiffRange(cwd, opts) {
             // Only use it if the commit is actually present in this clone; otherwise
             // fall through so a shallow clone degrades to a full scan, not 0 files.
             const baseSha = eventBase ? await (0, utils_1.resolveGitRef)(cwd, eventBase) : undefined;
-            if (baseSha)
-                return { baseSha, headSha, scope: 'delta (PR event)' };
+            if (baseSha) {
+                return { baseSha, headSha, scope: { kind: 'delta', reason: 'PR event', degraded: false } };
+            }
         }
         catch {
             // Malformed/unreadable event — fall through to a full scan below.
         }
-        return { headSha, scope: 'full (PR base unavailable)' };
+        return { headSha, scope: degraded('PR base unavailable') };
     }
+    if (plan.kind === 'branch')
+        return resolveBranchRange(cwd, headSha);
     const baseSha = await (0, utils_1.resolveGitRef)(cwd, plan.ref);
+    if (!baseSha)
+        return { headSha, scope: degraded(`${plan.ref} unresolvable`) };
+    return {
+        baseSha,
+        headSha,
+        scope: { kind: 'delta', reason: `${plan.ref}, ${plan.reason}`, degraded: false },
+    };
+}
+/** Branches a repository's trunk is normally called, most likely first. */
+const DEFAULT_BRANCHES = ['main', 'master', 'develop'];
+/**
+ * Where this branch diverged from the trunk, or nothing when it has not.
+ *
+ * Prefers `origin/HEAD` — the remote's own answer to "what is the default
+ * branch" — and falls back to the usual names, local or remote. Returns
+ * `undefined` when no trunk is found or when HEAD is already on it, which the
+ * caller turns into a full scan: on the trunk there is no branch to review.
+ */
+async function findMergeBase(cwd, headSha) {
+    const candidates = ['origin/HEAD'];
+    for (const name of DEFAULT_BRANCHES)
+        candidates.push(`origin/${name}`, name);
+    for (const candidate of candidates) {
+        const ref = await (0, utils_1.resolveGitRef)(cwd, candidate);
+        // A candidate that resolves to HEAD is the branch we are on, not a base.
+        if (!ref || ref === headSha)
+            continue;
+        const { stdout } = await (0, execa_1.execa)('git', ['merge-base', headSha, ref], { cwd, reject: false });
+        const base = stdout.trim();
+        // An unrelated history has no merge base, and a base equal to HEAD means the
+        // branch is behind rather than ahead — neither describes local changes.
+        if (base && base !== headSha)
+            return base;
+    }
+    return undefined;
+}
+/**
+ * Local run on a branch: review what the branch changed.
+ *
+ * On the trunk itself there is nothing to diff against, so this degrades to a
+ * full scan — deliberately not marked `degraded`, because it is the expected
+ * answer there rather than a configuration problem worth warning about.
+ */
+async function resolveBranchRange(cwd, headSha) {
+    const baseSha = await findMergeBase(cwd, headSha);
+    if (!baseSha)
+        return { headSha, scope: intended('no branch base — on the default branch?') };
     return {
         baseSha,
         headSha,
-        scope: baseSha ? `delta (${plan.ref}, ${plan.reason})` : `full (${plan.ref} unresolvable)`,
+        scope: { kind: 'delta', reason: 'branch changes', degraded: false },
     };
 }
 /**
@@ -120,12 +191,13 @@ async function buildContext(opts = {}) {
     // Detection reads the client's `ignoreDirs` from the config already loaded here,
     // rather than calling getIgnoredDirs() — that one resolves against process.cwd(),
     // which is not necessarily the `cwd` under review.
-    const languages = opts.languages ?? (await (0, detect_language_1.detectLanguages)(cwd, config.ignoreDirs));
+    applyLogConfig(config);
+    const languages = opts.languages ?? (await (0, detect_language_1.detectLanguages)(cwd, config.ignoreDirs, config.detect));
     const { baseSha, headSha, scope } = await resolveDiffRange(cwd, opts);
     // `scope` is logged because it decides what the whole run looks at, and getting
     // it wrong is invisible in the results: a run that reviewed one commit and one
     // that reviewed the repository both just print passes.
-    utils_1.logger.info(`[buildContext]: cwd=${cwd} languages=[${languages.join(', ') || 'none'}] write=${opts.write ?? false} scope=${scope}`);
+    utils_1.logger.info(`[buildContext]: cwd=${cwd} languages=[${languages.join(', ') || 'none'}] write=${opts.write ?? false} scope=${describeScope(scope)}`);
     return {
         cwd,
         languages,
@@ -133,6 +205,36 @@ async function buildContext(opts = {}) {
         write: opts.write ?? false,
         baseSha,
         headSha,
+        scope,
         cache: new Map(),
     };
 }
+/**
+ * Human-readable one-liner for a scope, e.g. `full (PR base unavailable)`.
+ *
+ * Deliberately not exported: `buildContext` is the only caller, and the scope it
+ * describes already travels on the context for anyone who wants to phrase it
+ * differently. An `export` here would only be API surface Dead Code reports.
+ */
+function describeScope(scope) {
+    return scope.reason ? `${scope.kind} (${scope.reason})` : scope.kind;
+}
+/**
+ * Apply the client's `log` block, with environment variables taking precedence.
+ *
+ * Env wins because the config file is committed and the environment is not: a
+ * one-off `PR_CHECKMATE_LOG_LEVEL=debug` to diagnose a CI run should not require
+ * editing — and later reverting — a tracked file.
+ */
+function applyLogConfig(config) {
+    const log = config.log ?? {};
+    const level = process.env.PR_CHECKMATE_LOG_LEVEL ?? log.level;
+    const format = process.env.PR_CHECKMATE_LOG_FORMAT ?? log.format;
+    utils_1.logger.configure({
+        ...(level ? { level } : {}),
+        ...(format ? { format } : {}),
+        ...(log.color ? { color: log.color } : {}),
+        ...(log.timestamps !== undefined ? { timestamps: log.timestamps } : {}),
+        ...(log.stderrLevels ? { stderrLevels: log.stderrLevels } : {}),
+    });
+}

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

@@ -0,0 +1,39 @@
+/** Where fetched tooling lives, and why it ended up there. */
+export interface CacheLocation {
+    dir: string;
+    /** `false` when the configured location was unusable and this is a fallback. */
+    preferred: boolean;
+    reason?: string;
+}
+/**
+ * Expand a leading `~`.
+ *
+ * Config files are written by hand, `~/.cache/pr-checkmate` is what a person
+ * writes, and nothing in Node expands it — the directory would be created
+ * literally, as a folder named `~`, in whatever the working directory happened
+ * to be.
+ */
+export declare function expandHome(dir: string, home?: string): string;
+/**
+ * Resolve the cache directory, falling back rather than failing.
+ *
+ * Every candidate below is a real environment: containers without `HOME`, CI
+ * images with a read-only home, and runners where only the temp directory is
+ * writable. A tool that refuses to work in any of them is a tool that fails on
+ * CI for reasons the client cannot see.
+ *
+ * @param version The pr-checkmate version, kept in the path so two projects on
+ *   different versions never share fetched tooling.
+ * @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. */
+export declare function profileDir(cacheDir: string, profile: string): string;
+/**
+ * Profile directories left behind by other versions of pr-checkmate.
+ *
+ * Nothing removes these automatically: an upgrade must not delete tooling a
+ * concurrently running older version is in the middle of using. `cache prune`
+ * is the deliberate, separate act.
+ */
+export declare function stalePaths(version: string, configured?: string): string[];