pr-checkmate 1.23.19 → 1.23.21

package/.eslintrc.js

@@ -70,13 +70,15 @@ module.exports = {
     'space-before-function-paren': 'off',
     'operator-linebreak': 'off',
     'max-len': ['warn', { code: 100 }],
-    semi: ['error', 'always'],
-    quotes: ['error', 'single', { avoidEscape: true }],
-    'object-curly-spacing': ['error', 'always'],
-    'space-infix-ops': 'error',
-    'keyword-spacing': ['error', { before: true, after: true }],
+    // Formatting is advisory — see the note above `rules` in eslint-flat-config.mjs.
+    // Keep these in sync with src/config/eslint-default-rules.json.
+    semi: ['warn', 'always'],
+    quotes: ['warn', 'single', { avoidEscape: true }],
+    'object-curly-spacing': ['warn', 'always'],
+    'space-infix-ops': 'warn',
+    'keyword-spacing': ['warn', { before: true, after: true }],
     'padding-line-between-statements': [
-      'error',
+      'warn',
       { blankLine: 'always', prev: 'block', next: '*' },
       { blankLine: 'always', prev: '*', next: 'return' },
     ],
@@ -108,7 +110,7 @@ module.exports = {
     'jsdoc/check-tag-names': 'warn',
     'jsdoc/check-types': 'warn',
     'prettier/prettier': [
-      'error',
+      'warn',
       {
         semi: true,
         singleQuote: true,

package/README.md

@@ -29,8 +29,8 @@ every PR.
 - One package, any stack. Language is auto-detected from the repo.
 - Bundled tooling. ESLint, Prettier, Ruff, clang-format, and gitleaks run inside the
   package (WASM/JS), so clients install nothing for those languages.
-- Delta mode. In a PR only the changed files are checked; a full-project scan is the
-  fallback outside PR context.
+- Delta mode. A PR run checks only the changed files; outside CI the default is every tracked
+  file. `--full` forces that anywhere, and a run that cannot resolve its base falls back to it.
 - Parallel phases. Checks run concurrently within each phase: blocking, then
   informational, then format.
 - Reports in the PR. Results post as a single comment that updates in place, and
@@ -79,6 +79,24 @@ Run all checks:
 npx pr-checkmate all
 ```
 
+Scope depends on where the command runs. In CI it reviews the pull request diff, taking the
+base SHA from the GitHub `pull_request` event or Bitbucket's destination branch; a CI build
+with no PR attached falls back to `HEAD^`. Locally, with no CI environment detected, it
+reviews every tracked file. It used to fall back to `HEAD^` there too, so a local run saw
+only the last commit and would report a clean project with a `debugger` committed the day
+before. `--full` forces the whole-repo review anywhere, including inside a CI build, and it
+composes with any command:
+
+```bash
+npx pr-checkmate all --full
+npx pr-checkmate lint --full
+```
+
+The 16 checks that only make sense on a diff (PR Size, Diff Security, Merge Conflict, Custom
+Rules, Banned Imports, the git-diff family) drop out of the report on a full scan. The
+[per-check reference](https://github.com/Mybono/pr_checkmate_public/blob/main/documentation/checks/INDEX.md)
+spells out the rules under "Review scope".
+
 ### Running in CI without installing
 
 Plenty of repos never add pr-checkmate to `package.json` and call it on the fly in CI

package/cspell.json

@@ -903,6 +903,7 @@
     "riskfolio",
     "robolectric",
     "rowwise",
+    "rseidelsohn",
     "Rshum",
     "rtol",
     "rtype",
@@ -1010,6 +1011,7 @@
     "taxinfo",
     "Tayebeh",
     "tcwf",
+    "teamcity",
     "telaviv",
     "temurin",
     "Tenés",
@@ -1237,23 +1239,23 @@
     "רטינול"
   ],
   "ignorePaths": [
-    "**/node_modules/**",
-    "**/dist/**",
-    "**/.git/**",
-    "**/build/**",
-    "**/coverage/**",
-    "**/.next/**",
-    "**/.nuxt/**",
-    "**/out/**",
-    "**/__pycache__/**",
-    "**/.pytest_cache/**",
-    "**/.venv/**",
-    "**/venv/**",
-    "**/package-lock.json",
-    "**/yarn.lock",
-    "**/pnpm-lock.yaml",
-    "**/*.min.js",
-    "**/*.min.css"
+    "/**/node_modules/**",
+    "/**/dist/**",
+    "/**/.git/**",
+    "/**/build/**",
+    "/**/coverage/**",
+    "/**/.next/**",
+    "/**/.nuxt/**",
+    "/**/out/**",
+    "/**/__pycache__/**",
+    "/**/.pytest_cache/**",
+    "/**/.venv/**",
+    "/**/venv/**",
+    "/**/package-lock.json",
+    "/**/yarn.lock",
+    "/**/pnpm-lock.yaml",
+    "/**/*.min.js",
+    "/**/*.min.css"
   ],
   "enableFiletypes": ["typescript", "javascript", "markdown", "json"],
   "ignoreRegExpList": ["/https?:\\/\\/[^\\s]+/g", "/\\b[0-9a-f]{7,40}\\b/gi"]

package/dist/cli.js

@@ -56,8 +56,51 @@ const COMMAND_TO_CHECK = {
 };
 /** Commands that run the whole pipeline (or no pipeline at all) and take no siblings. */
 const STANDALONE_COMMANDS = ['init', 'all', 'precommit'];
-const args = process.argv.slice(2);
+/** Flags accepted anywhere on the command line, with what each one means. */
+const FLAGS = {
+    '--full': 'review every tracked file instead of the diff (the default outside CI)',
+};
+const argv = process.argv.slice(2);
+/**
+ * Flags are separated from positional arguments so they compose with every command
+ * — scope is orthogonal to which checks run, hence `pr-checkmate lint --full` as
+ * well as `pr-checkmate all --full`.
+ */
+const flags = argv.filter(arg => arg.startsWith('-'));
+const args = argv.filter(arg => !arg.startsWith('-'));
 const cmd = args[0];
+/**
+ * An unrecognised flag aborts the run. Ignoring it would report success for a scope
+ * the user did not ask for: a misspelling of `--full` must not quietly review the
+ * diff and print a green summary.
+ */
+function rejectUnknownFlags() {
+    const unknown = flags.filter(flag => !FLAGS[flag]);
+    if (unknown.length === 0)
+        return;
+    const known = Object.entries(FLAGS)
+        .map(([flag, help]) => `${flag} (${help})`)
+        .join(', ');
+    utils_1.logger.error(`[cli]: Unknown flag(s) "${unknown.join('", "')}". Available: ${known}`);
+    process.exit(1);
+}
+/**
+ * `--full` and `precommit` ask for different things — every tracked file versus the
+ * staged changes only. `planDiffRange` resolves the conflict in favour of `--full`,
+ * which would silently turn a pre-commit hook into a whole-repo scan, so the
+ * contradiction is refused here instead.
+ */
+function rejectConflictingScope() {
+    if (cmd === 'precommit' && flags.includes('--full')) {
+        utils_1.logger.error('[cli]: "precommit --full" is contradictory — precommit reviews the staged changes. Run "pr-checkmate all --full" for a whole-repo review.');
+        process.exit(1);
+    }
+    if (cmd === 'init' && flags.length > 0) {
+        utils_1.logger.error(`[cli]: "init" takes no flags, got: ${flags.join(', ')}.`);
+        process.exit(1);
+    }
+}
+const full = flags.includes('--full');
 /**
  * Reject extra arguments after a standalone command. Silently ignoring them would
  * report success for work that never ran — `pr-checkmate init lint` must not look
@@ -75,6 +118,8 @@ function rejectExtraArgs() {
 }
 void (async () => {
     try {
+        rejectUnknownFlags();
+        rejectConflictingScope();
         rejectExtraArgs();
         if (cmd === 'init') {
             await (0, init_1.init)();
@@ -86,7 +131,7 @@ void (async () => {
             // Fetch the update notice concurrently (best-effort, never blocks/affects
             // the exit code), but print it LAST — after the summary — so it's noticeable.
             const noticePromise = (0, utils_1.getUpdateNotice)();
-            const report = await (0, core_1.runChecks)({ reporter: 'auto', write: true });
+            const report = await (0, core_1.runChecks)({ reporter: 'auto', write: true, full });
             const notice = await noticePromise.catch(() => null);
             if (notice) {
                 utils_1.logger.info('');
@@ -109,7 +154,7 @@ void (async () => {
             process.exit(1);
         }
         const checkNames = [...new Set(args.map(arg => COMMAND_TO_CHECK[arg]))];
-        const report = await (0, core_1.runChecks)({ only: checkNames, reporter: 'stdout', write: true });
+        const report = await (0, core_1.runChecks)({ only: checkNames, reporter: 'stdout', write: true, full });
         process.exit(report.ok ? 0 : 1);
     }
     catch (err) {

package/dist/config/constants.d.ts

@@ -55,6 +55,7 @@ export declare const SOURCE_EXTENSIONS: {
 export declare const DEFAULT_COMMANDS: {
     'npx pr-checkmate init': string;
     'npx pr-checkmate all': string;
+    'npx pr-checkmate all --full': string;
     'npx pr-checkmate lint': string;
     'npx pr-checkmate prettier': string;
     'npx pr-checkmate deps': string;

package/dist/config/constants.js

@@ -181,7 +181,8 @@ exports.SOURCE_EXTENSIONS = {
 };
 exports.DEFAULT_COMMANDS = {
     'npx pr-checkmate init': 'Update pr-checkmate.json',
-    'npx pr-checkmate all': 'Run all checks',
+    'npx pr-checkmate all': 'Run all checks (the PR diff in CI, every tracked file locally)',
+    'npx pr-checkmate all --full': 'Run all checks over every tracked file, CI included',
     'npx pr-checkmate lint': 'Lint code using ESLint',
     'npx pr-checkmate prettier': 'Format code using Prettier',
     'npx pr-checkmate deps': 'Check project dependencies',

package/dist/core/checks/languages/lint.js

@@ -57,6 +57,13 @@ exports.lintCheck = {
         // parser, breaking TypeScript linting. Only pass it on the legacy path.
         if (version < 9)
             args.push('--ext', '.ts,.tsx,.js,.jsx');
+        // Files are named explicitly, so any of them that the config ignores produces a
+        // "File ignored because of a matching ignore pattern" warning. That is a fact
+        // about the config, not about the client's code, and a whole-repo run surfaces
+        // one per ignored-but-tracked file (`.eslintrc.js`, generated sources). The flag
+        // suppresses the warning only — nothing changes about which files are linted.
+        if (version >= 9)
+            args.push('--no-warn-ignored');
         // Only auto-fix when the caller allows file mutations.
         if (ctx.write)
             args.push('--fix');

package/dist/core/checks/pr/commitlint.js

@@ -63,9 +63,20 @@ exports.commitlintCheck = {
         const commitlintBin = (0, utils_1.resolvePackageBin)('@commitlint/cli', 'cli.js');
         const hasLocal = (0, config_1.hasLocalConfig)(LOCAL_CONFIG_FILES);
         let tempConfigFile = null;
-        const from = ctx.baseSha ?? 'HEAD~1';
-        const to = ctx.headSha ?? 'HEAD';
-        const args = ['--from', from, '--to', to, '--verbose'];
+        // With no diff range (a full-repo review, or `--full`) the check still has a
+        // meaningful subject: the newest commit message. `HEAD~1` cannot be assumed to
+        // exist, though — it is absent on a repository's first commit and in a shallow
+        // clone (`actions/checkout` fetches depth 1 by default). Passing it blind made
+        // commitlint die with an unhandled "ambiguous argument 'HEAD~1..HEAD'" stack
+        // trace in the client's log, and the check then reported "commit message
+        // violations found" — a verdict about code quality for what was a crash.
+        // `--last` lints exactly the newest commit and needs no ancestor.
+        const range = ctx.baseSha
+            ? ['--from', ctx.baseSha, '--to', ctx.headSha ?? 'HEAD']
+            : (await (0, utils_1.resolveGitRef)(ctx.cwd, 'HEAD~1'))
+                ? ['--from', 'HEAD~1', '--to', ctx.headSha ?? 'HEAD']
+                : ['--last'];
+        const args = [...range, '--verbose'];
         try {
             if (hasLocal) {
                 utils_1.logger.info('[Commitlint]: Using local config');

package/dist/core/checks/quality/spellcheck.d.ts

@@ -1,2 +1,27 @@
+import { CspellConfig } from '../../../interfaces';
 import { Check } from '../../types';
+/**
+ * Anchors an ignore glob to the repository root.
+ *
+ * cspell matches `ignorePaths` against each file's ABSOLUTE path, so an unanchored
+ * `**\/build/**` also matches every ancestor directory of the workspace. On Bitbucket
+ * Pipelines the clone lives in `/opt/atlassian/pipelines/agent/build`, so that one
+ * pattern excluded the entire repository and the check silently spellchecked nothing.
+ * A leading `/` anchors the pattern to the config's directory (the repo root) while
+ * `/**\/dir/**` still matches at any depth INSIDE the repo — verified against cspell 10.
+ *
+ * Patterns that are already anchored (`/…`) or plainly relative (`dir/**`,
+ * `CHANGELOG.md`) are left untouched: they cannot match an ancestor.
+ */
+export declare function anchorIgnoreGlob(pattern: string): string;
+/**
+ * Folds the client's `cspell` block from pr-checkmate.json into the bundled
+ * defaults. `enabled` is deliberately not carried over — it gates the check
+ * itself (see `applies`) and is not a cspell setting.
+ *
+ * Lists are appended so a client extends the curated vocabulary instead of
+ * replacing it; `language` is the one exception and replaces the default, because
+ * a client writing `"en"` means exactly that and appending would be meaningless.
+ */
+export declare function mergeCspellConfig(defaultConfig: CspellConfig, userConfig: Partial<CspellConfig>): CspellConfig;
 export declare const spellcheckCheck: Check;

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

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.spellcheckCheck = void 0;
+exports.anchorIgnoreGlob = anchorIgnoreGlob;
+exports.mergeCspellConfig = mergeCspellConfig;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("../../../config");
@@ -23,6 +25,47 @@ function loadUserCspellConfig(cwd) {
         return {};
     }
 }
+/**
+ * Anchors an ignore glob to the repository root.
+ *
+ * cspell matches `ignorePaths` against each file's ABSOLUTE path, so an unanchored
+ * `**\/build/**` also matches every ancestor directory of the workspace. On Bitbucket
+ * Pipelines the clone lives in `/opt/atlassian/pipelines/agent/build`, so that one
+ * pattern excluded the entire repository and the check silently spellchecked nothing.
+ * A leading `/` anchors the pattern to the config's directory (the repo root) while
+ * `/**\/dir/**` still matches at any depth INSIDE the repo — verified against cspell 10.
+ *
+ * Patterns that are already anchored (`/…`) or plainly relative (`dir/**`,
+ * `CHANGELOG.md`) are left untouched: they cannot match an ancestor.
+ */
+function anchorIgnoreGlob(pattern) {
+    return pattern.startsWith('**/') ? `/${pattern}` : pattern;
+}
+/**
+ * Folds the client's `cspell` block from pr-checkmate.json into the bundled
+ * defaults. `enabled` is deliberately not carried over — it gates the check
+ * itself (see `applies`) and is not a cspell setting.
+ *
+ * Lists are appended so a client extends the curated vocabulary instead of
+ * replacing it; `language` is the one exception and replaces the default, because
+ * a client writing `"en"` means exactly that and appending would be meaningless.
+ */
+function mergeCspellConfig(defaultConfig, userConfig) {
+    const dictionaries = [...(defaultConfig.dictionaries ?? []), ...(userConfig.dictionaries ?? [])];
+    return {
+        ...defaultConfig,
+        language: userConfig.language || defaultConfig.language,
+        words: [...defaultConfig.words, ...(userConfig.words || [])],
+        // Client globs are anchored too — a repo's own pattern is meant to be relative
+        // to that repo, never to whatever directories sit above the checkout.
+        ignorePaths: [...defaultConfig.ignorePaths, ...(userConfig.ignorePaths || [])].map(anchorIgnoreGlob),
+        ignoreRegExpList: [...defaultConfig.ignoreRegExpList, ...(userConfig.ignoreRegExpList || [])],
+        // The bundled dictionaries arrive through `import`, so there is nothing to
+        // override here. cspell ignores names it cannot resolve, so a client typo
+        // costs coverage but never fails the run.
+        ...(dictionaries.length > 0 ? { dictionaries } : {}),
+    };
+}
 function createTempCspellConfig(cwd) {
     const packageConfigPath = (0, config_1.getPackageConfigPath)('cspell.json');
     const packageConfigDir = node_path_1.default.dirname(packageConfigPath);
@@ -40,11 +83,8 @@ function createTempCspellConfig(cwd) {
         }
     });
     const mergedConfig = {
-        ...defaultConfig,
+        ...mergeCspellConfig(defaultConfig, userConfig),
         import: resolvedImports,
-        words: [...defaultConfig.words, ...(userConfig.words || [])],
-        ignorePaths: [...defaultConfig.ignorePaths, ...(userConfig.ignorePaths || [])],
-        ignoreRegExpList: [...defaultConfig.ignoreRegExpList, ...(userConfig.ignoreRegExpList || [])],
     };
     const tempConfigPath = node_path_1.default.join(cwd, '.cspell.temp.json');
     node_fs_1.default.writeFileSync(tempConfigPath, JSON.stringify(mergedConfig, null, 2));
@@ -53,26 +93,46 @@ function createTempCspellConfig(cwd) {
 exports.spellcheckCheck = {
     name: 'Spellcheck',
     phase: 'informational',
-    applies() {
-        return true;
+    /**
+     * Clients turn the check off with `cspell.enabled: false` (or the `spellcheck`
+     * alias the config interface uses). The universal `severity: { Spellcheck: "off" }`
+     * switch keeps working too — this is the per-check flag every other check exposes.
+     */
+    applies(ctx) {
+        return ctx.config.cspell?.enabled !== false && ctx.config.spellcheck?.enabled !== false;
     },
     async run(ctx) {
-        const files = await (0, targets_1.resolveScopedTargetFiles)(ctx, ['*.ts', '*.tsx', '*.js', '*.jsx', '*.md', '*.mdx', '*.json'], (0, config_1.getSourcePaths)());
-        if (files === null)
+        const targets = await (0, targets_1.resolveScopedTargetFiles)(ctx, ['*.ts', '*.tsx', '*.js', '*.jsx', '*.md', '*.mdx', '*.json'], (0, config_1.getSourcePaths)());
+        if (targets === null)
             return (0, types_1.skip)('git unavailable');
+        // Committed build output and test reports are dropped here, in JS, against
+        // repo-RELATIVE paths — a client cannot fix a typo in a generated file, so
+        // reporting one is noise that buries the real findings. Neither cspell
+        // mechanism can do this safely: `--exclude` ignores glob anchoring outright
+        // (`--exclude=/**/build/**` still matches an ancestor `build` dir, which on
+        // Bitbucket Pipelines is the checkout itself), and `ignorePaths` only reaches
+        // repos that have no cspell config of their own. Filtering the list keeps one
+        // rule for every repo. `ignoreDirs` already covers plain directory names via
+        // `resolveTargetFiles`; this adds the composite globs it cannot express
+        // (`**/cypress/videos/**`, `**/jest-html-reporters-*/**`).
+        const files = targets.filter(f => !(0, utils_1.matchesAnyGlob)(f, config_1.IGNORE_PATTERNS));
         if (files.length === 0)
             return (0, types_1.pass)('no files to spellcheck');
-        const patterns = [...files, ...config_1.IGNORE_PATTERNS.map(p => `--exclude=${p}`)];
         const hasLocal = (0, config_1.hasLocalConfig)(['cspell.json', '.cspell.json', 'cspell.config.json']);
         let tempConfigPath = null;
         const cspellBin = (0, utils_1.resolvePackageBin)('cspell', 'bin.mjs');
+        // `--no-must-find-files`: cspell exits 1 when it checked nothing, which the
+        // exit-code mapping below would report as "spelling issues found" — a warning
+        // about problems that do not exist. Every file being excluded is a pass, not a
+        // finding.
+        const baseArgs = [...files, '--no-progress', '--no-must-find-files'];
         let args;
         if (hasLocal) {
-            args = [...patterns, '--no-progress'];
+            args = baseArgs;
         }
         else {
             tempConfigPath = createTempCspellConfig(ctx.cwd);
-            args = [...patterns, '--config', tempConfigPath, '--no-progress'];
+            args = [...baseArgs, '--config', tempConfigPath];
         }
         try {
             const result = await (0, execa_1.execa)(process.execPath, [cspellBin, ...args], {

package/dist/core/checks/quality/yaml-lint.d.ts

@@ -1,4 +1,11 @@
 import { Check } from '../../types';
+/**
+ * True when a parser problem describes something actually wrong with the file —
+ * a syntax error, a duplicate key, a tab used for indentation.
+ */
+export declare function isFileDefect(problem: {
+    code?: string;
+}): boolean;
 /**
  * Bundled YAML linter (the `yaml` package — no runner dependency, always
  * available like Markdown/Spellcheck). Parses every changed `.yml`/`.yaml` file

package/dist/core/checks/quality/yaml-lint.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.yamlLintCheck = void 0;
+exports.isFileDefect = isFileDefect;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const yaml_1 = require("yaml");
@@ -15,6 +16,28 @@ const findings_1 = require("../findings");
 function shortMessage(message) {
     return message.split('\n')[0].trim();
 }
+/**
+ * Parser problems that are not defects in the file.
+ *
+ * `TAG_RESOLVE_FAILED` means the parser met an application-specific tag it has no
+ * schema for. YAML is explicitly extensible there, so the document is valid and the
+ * parser simply is not the application that defines the tag: `!Ref`, `!Sub`,
+ * `!GetAtt`, `!Equals` in CloudFormation and SAM templates, `!include` in Home
+ * Assistant, `!vault` in Ansible. Reporting those calls a whole ecosystem's valid
+ * files broken — one CloudFormation template produced **557 blocking findings** for
+ * a client, none of which was a real problem.
+ *
+ * Matched on the parser's `code`, not on message text, so a wording change upstream
+ * cannot silently re-enable it.
+ */
+const NON_DEFECT_CODES = new Set(['TAG_RESOLVE_FAILED']);
+/**
+ * True when a parser problem describes something actually wrong with the file —
+ * a syntax error, a duplicate key, a tab used for indentation.
+ */
+function isFileDefect(problem) {
+    return problem.code === undefined || !NON_DEFECT_CODES.has(problem.code);
+}
 /**
  * Bundled YAML linter (the `yaml` package — no runner dependency, always
  * available like Markdown/Spellcheck). Parses every changed `.yml`/`.yaml` file
@@ -60,7 +83,7 @@ exports.yamlLintCheck = {
             // so a single malformed file cannot abort the whole check.
             const docs = (0, yaml_1.parseAllDocuments)(source, { prettyErrors: true });
             for (const doc of docs) {
-                for (const problem of [...doc.errors, ...doc.warnings]) {
+                for (const problem of [...doc.errors, ...doc.warnings].filter(isFileDefect)) {
                     const pos = problem.linePos?.[0];
                     issues.push({
                         file,

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

@@ -39,10 +39,30 @@ exports.securityCheck = {
         // 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';
-        const args = ['--diff-mode', 'ci', '--gitleaks-version', gitleaksVersion];
+        // 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 (0, utils_1.resolveGitRef)(ctx.cwd, 'HEAD'))) {
+            return (0, types_1.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', (0, config_1.getPackageConfigPath)('gitleaks.toml'));
         }
+        utils_1.logger.info(`[Security Scan]: scanning ${isDelta ? 'the diff range' : `full history${depth ? ` (last ${depth} commits)` : ''}`}`);
         const env = {
             ...process.env,
             ...(ctx.headSha ? { HEAD_SHA: ctx.headSha } : {}),

package/dist/core/context.d.ts

@@ -1,6 +1,53 @@
 import type { CheckContext, RunOptions } from './types';
+/**
+ * What a run should look at, before any git call is made. Separated from
+ * {@link resolveDiffRange} so the precedence rules are a pure function of the
+ * options and the environment — the part worth pinning with tests.
+ *
+ * - `full` — every tracked file. Checks fall back to `git ls-files` when the range
+ *   is undefined, so this is expressed by resolving to no SHAs at all.
+ * - `staged` — index vs HEAD (pre-commit).
+ * - `explicit` — SHAs the caller supplied.
+ * - `github-event` — base SHA from the pull_request event payload.
+ * - `ref` — diff against a named ref (a PR's destination branch, or `HEAD^`).
+ */
+type RangePlan = {
+    kind: 'full';
+    reason: string;
+} | {
+    kind: 'staged';
+} | {
+    kind: 'explicit';
+    baseSha?: string;
+    headSha?: string;
+} | {
+    kind: 'github-event';
+} | {
+    kind: 'ref';
+    ref: string;
+    reason: string;
+};
+/**
+ * Decide what to look at. Order matters and is the contract:
+ *
+ * 1. `full` wins over everything — an explicit "check all of it" must not be
+ *    quietly narrowed by a CI variable that happens to be set.
+ * 2. `staged`, then caller-supplied SHAs.
+ * 3. The CI platform's PR context (GitHub event payload, Bitbucket destination
+ *    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.
+ *
+ * @param opts Run options as passed to `runChecks`.
+ * @param env Environment to read CI markers from. Defaults to the current process.
+ */
+export declare function planDiffRange(opts: RunOptions, env?: NodeJS.ProcessEnv): RangePlan;
 /**
  * Assemble the shared CheckContext once per run. Language detection is skipped
  * when the caller supplies `languages` (e.g. PRValidator passes its ProjectType).
  */
 export declare function buildContext(opts?: RunOptions): Promise<CheckContext>;
+export {};