pr-checkmate 1.23.18 → 1.23.20

package/README.md

@@ -10,7 +10,6 @@
 ![jscpd](https://img.shields.io/badge/jscpd-5-blue)
 [![API Docs](https://img.shields.io/badge/API_docs-TypeDoc-9600FF?logo=readthedocs&logoColor=white)](https://pr-checkmate-docs.pages.dev)
 [![Security scan](https://img.shields.io/badge/security-SBOM_%2B_VirusTotal-2ea44f)](https://github.com/Mybono/pr_checkmate_public/releases/latest)
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Mybono/pr_checkmate_public/badge)](https://scorecard.dev/viewer/?uri=github.com/Mybono/pr_checkmate_public)
 
 > PR CheckMate is a universal PR quality checker: one `npm install`, 51 checks across
 > 11 languages, running in CI on every pull request. The bundled languages need no
@@ -20,8 +19,6 @@ Every release is published with a CycloneDX SBOM and an independent
 [VirusTotal scan report](https://github.com/Mybono/pr_checkmate_public/releases/latest)
 of the exact npm tarball, attached to that version's
 [GitHub release notes](https://github.com/Mybono/pr_checkmate_public/releases/latest).
-The public repo also runs an [OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/Mybono/pr_checkmate_public)
-analysis of its own supply-chain hygiene.
 
 ## Why PR CheckMate
 

package/cspell.json

@@ -309,6 +309,7 @@
     "dont",
     "Dorg",
     "dotenv",
+    "dotenvx",
     "dotnet",
     "DPARALLEL",
     "dpdm",
@@ -343,6 +344,7 @@
     "endtable",
     "engineio",
     "ENOENT",
+    "ENOLOCK",
     "eoilist",
     "Escaneá",
     "Escaneás",
@@ -1235,23 +1237,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/config/constants.js

@@ -251,6 +251,7 @@ exports.KNOWN_CONFIG_KEYS = new Set([
     'migrationSafety',
     // dependencies
     'dependency',
+    'circularDeps',
     'outdatedDeps',
     'licenseCheck',
     'vulnScan',

package/dist/core/checks/dependencies/circular-deps.js

@@ -1,33 +1,151 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.circularDepsCheck = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+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 targets_1 = require("../../targets");
 const types_1 = require("../../types");
+const findings_1 = require("../findings");
+/**
+ * Cap for the analysis. dpdm builds the whole module graph, which on a large repo
+ * is the slowest part of a run — an uncapped analysis looks like a hung commit.
+ */
+const DEFAULT_TIMEOUT_MS = 120000;
+/**
+ * Ceiling for the assembled argument list. Passing every tracked source file as a
+ * separate argument overflows the OS argument limit (`E2BIG`) on a large repo, and
+ * a spawn that never starts writes no report. Past the ceiling dpdm gets globs
+ * instead — it expands them itself, over the same source paths.
+ */
+const MAX_ARGV_CHARS = 100000;
+/** Extensions dpdm resolves for us; also the globs used in the fallback. */
+const SOURCE_GLOBS = ['*.ts', '*.tsx', '*.js', '*.jsx'];
+/**
+ * Resolve dpdm, preferring the consumer project's own copy (so a repo pinned to a
+ * different major keeps its own behaviour) and falling back to the copy bundled
+ * with pr-checkmate — the order `lint` and `typecheck` use for eslint/tsc.
+ *
+ * Returns null instead of throwing: an unresolvable analyzer is a skip, never a
+ * failed PR. This check used to shell out to `npx dpdm`, which silently fetched
+ * dpdm from the registry on first use — and when that fetch could not happen
+ * (offline or locked-down CI, private registry, exit 127) nothing was analyzed.
+ */
+function resolveDpdm(cwd) {
+    for (const options of [{ paths: [cwd] }, undefined]) {
+        try {
+            return (0, utils_1.resolvePackageBin)('dpdm', 'lib/bin/dpdm.js', options);
+        }
+        catch {
+            // Try the next location; both failing is a skip, handled by the caller.
+        }
+    }
+    return null;
+}
+/**
+ * Build the file arguments for dpdm, falling back to globs when the explicit list
+ * would overflow the OS argument limit. `sourcePaths` scopes the globs the same way
+ * `listTrackedFiles` scopes the explicit list.
+ */
+function toFileArgs(files, sourcePaths) {
+    const explicitLength = files.reduce((sum, file) => sum + file.length + 1, 0);
+    if (explicitLength <= MAX_ARGV_CHARS)
+        return files;
+    const roots = sourcePaths.length > 0 ? sourcePaths : ['.'];
+    const globs = roots.flatMap(root => SOURCE_GLOBS.map(ext => `${root.replace(/\/+$/, '')}/**/${ext}`));
+    utils_1.logger.info(`[Circular Deps]: ${files.length} files exceed the argument limit — analyzing via globs (${globs.join(', ')})`);
+    return globs;
+}
+/** Read dpdm's report file; null when it is absent or unparseable. */
+function readReport(reportPath) {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(reportPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
 exports.circularDepsCheck = {
     name: 'Circular Deps',
     phase: 'blocking',
     applies(ctx) {
+        if (ctx.config.circularDeps?.enabled === false)
+            return false;
         return ctx.languages.includes('typescript') || ctx.languages.includes('javascript');
     },
     async run(ctx) {
-        const files = await (0, targets_1.listTrackedFiles)(ctx, ['*.ts', '*.tsx', '*.js', '*.jsx'], (0, config_1.getSourcePaths)());
-        if (files.length === 0)
+        const allFiles = await (0, targets_1.listTrackedFiles)(ctx, SOURCE_GLOBS, (0, config_1.getSourcePaths)());
+        if (allFiles.length === 0)
             return (0, types_1.pass)();
-        const result = await (0, execa_1.execa)('npx', ['dpdm', '--no-warning', '--no-tree', '--circular', ...files], {
-            cwd: ctx.cwd,
-            reject: false,
-        });
-        const output = (result.stdout + result.stderr).trim();
-        // dpdm's success message also contains "circular" — match only its error shapes:
-        // the "Circular Dependencies:" header or a numbered entry "[1] src/a.ts -> src/b.ts".
-        const hasCircular = /circular dependencies:/i.test(output) || /^\s*\[\d+\]/m.test(output);
-        if (hasCircular) {
-            utils_1.logger.error(`[Circular Deps]: ❌ circular dependencies detected:\n${output}`);
-            return (0, types_1.fail)('circular dependencies found');
+        // Files the client exempted (generated code, vendored bundles) are dropped
+        // before analysis — and again from the cycles below, since the graph can reach
+        // an ignored file by following imports from one that is analyzed.
+        const ignore = ctx.config.circularDeps?.ignore ?? [];
+        const files = ignore.length > 0 ? allFiles.filter(f => !(0, utils_1.matchesAnyGlob)(f, ignore)) : allFiles;
+        if (files.length === 0)
+            return (0, types_1.skip)('all files ignored');
+        const dpdmBin = resolveDpdm(ctx.cwd);
+        if (!dpdmBin) {
+            utils_1.logger.warn('[Circular Deps]: ⚠️ dpdm could not be resolved — skipping');
+            return (0, types_1.skip)('dpdm unavailable');
+        }
+        const timeout = ctx.config.circularDeps?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const reportPath = node_path_1.default.join(ctx.cwd, '.dpdm.temp.json');
+        try {
+            // Read the cycles from dpdm's JSON report rather than its console output.
+            // The console shapes this check used to grep for ("Circular Dependencies:",
+            // "[1] a -> b") are not what dpdm 4 prints ("• Circular Dependencies",
+            // "1) a -> b"), so no cycle ever matched and the check passed every repo,
+            // including one built solely out of a cycle. `--exit-code circular:1` gives
+            // the same answer independently: dpdm otherwise exits 0 even when it finds
+            // cycles, so the exit code alone cannot tell a clean repo from a broken run.
+            const result = await (0, execa_1.execa)(process.execPath, [
+                dpdmBin,
+                '--no-warning',
+                '--no-tree',
+                '--no-circular',
+                '--exit-code',
+                'circular:1',
+                '-o',
+                reportPath,
+                ...toFileArgs(files, (0, config_1.getSourcePaths)()),
+            ], { cwd: ctx.cwd, reject: false, timeout });
+            if (result.timedOut) {
+                utils_1.logger.warn(`[Circular Deps]: ⚠️ dpdm timed out after ${timeout}ms — skipping`);
+                return (0, types_1.skip)('dpdm timed out');
+            }
+            const report = readReport(reportPath);
+            // No report means dpdm never got far enough to write one (a tsconfig it
+            // cannot read, a file it cannot parse, a killed process). Skip: reporting
+            // that as "no cycles" hides a check that did not run, and failing on it
+            // blocks a PR that may have no cycle at all.
+            if (!report) {
+                const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+                utils_1.logger.warn(`[Circular Deps]: ⚠️ dpdm wrote no report (exit ${result.exitCode ?? 'killed'})${output ? `:\n${output}` : ''}`);
+                return (0, types_1.skip)(`dpdm failed to run (exit ${result.exitCode ?? 'killed'})`);
+            }
+            const cycles = (report.circulars ?? []).filter(cycle => ignore.length === 0 || !cycle.some(file => (0, utils_1.matchesAnyGlob)(file, ignore)));
+            if (cycles.length === 0)
+                return (0, types_1.pass)();
+            // Advisory by default. This check reported nothing for its whole existence
+            // (see the note above), so switching it on turns every long-standing cycle
+            // in every client repo into a finding at once — barrel files alone account
+            // for most of them. Warning first lets a repo see its cycles before they
+            // gate anything; promote with `circularDeps.severity: "error"`.
+            const sev = (0, findings_1.severityEmitter)(ctx.config.circularDeps?.severity, 'warn');
+            sev.log(`[Circular Deps]: ${sev.icon} ${cycles.length} circular dependency(ies):`);
+            cycles.slice(0, 10).forEach((cycle, i) => sev.log(`  ${i + 1}) ${cycle.join(' -> ')}`));
+            if (cycles.length > 10)
+                sev.log(`  ... and ${cycles.length - 10} more`);
+            return sev.emit(`${cycles.length} circular dependency(ies) found`);
+        }
+        finally {
+            (0, utils_1.cleanupTempFile)(reportPath);
         }
-        return (0, types_1.pass)();
     },
 };

package/dist/core/checks/dependencies/dependency-check.d.ts

@@ -1,4 +1,17 @@
 import { Check } from '../../types';
+/** One entry of knip's JSON reporter — a file plus the issues found for it. */
+interface KnipIssue {
+    file: string;
+    dependencies?: {
+        name: string;
+    }[];
+    unlisted?: {
+        name: string;
+    }[];
+}
+interface KnipReport {
+    issues?: KnipIssue[];
+}
 /**
  * Compile one `dependency.ignore` entry into a pattern knip matches the way this
  * config documents it — a glob over the whole dependency name.
@@ -11,4 +24,20 @@ import { Check } from '../../types';
  * only `eslint-…`, and keeps a plain name matching exactly that name.
  */
 export declare function toKnipIgnorePattern(entry: string): string;
+/**
+ * Pull knip's report out of a stdout stream that may carry unrelated output.
+ *
+ * knip imports the project's own config files while analyzing (a `wdio.conf.ts`
+ * for its WebdriverIO plugin, say), so any top-level side effect in them —
+ * a dotenv banner, a `console.log` in a config module — is printed before the
+ * report. Slicing from the first `{` to the last `}` therefore captured that
+ * noise instead: a dotenvx tip ending in `{ path: '…/.env' }` made the whole
+ * check fail on a repo whose report was perfectly valid.
+ *
+ * The json reporter writes the report as a single line (`JSON.stringify` with no
+ * indentation), so the last line that parses AND carries `issues` is the report.
+ * Anything else on stdout is noise, whatever braces it happens to contain.
+ */
+export declare function parseKnipReport(stdout: string): KnipReport | null;
 export declare const dependencyCheck: Check;
+export {};

package/dist/core/checks/dependencies/dependency-check.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dependencyCheck = void 0;
 exports.toKnipIgnorePattern = toKnipIgnorePattern;
+exports.parseKnipReport = parseKnipReport;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("../../../config");
@@ -57,6 +58,37 @@ function hasPackageJsonConfig(cwd) {
         return false;
     }
 }
+/**
+ * Pull knip's report out of a stdout stream that may carry unrelated output.
+ *
+ * knip imports the project's own config files while analyzing (a `wdio.conf.ts`
+ * for its WebdriverIO plugin, say), so any top-level side effect in them —
+ * a dotenv banner, a `console.log` in a config module — is printed before the
+ * report. Slicing from the first `{` to the last `}` therefore captured that
+ * noise instead: a dotenvx tip ending in `{ path: '…/.env' }` made the whole
+ * check fail on a repo whose report was perfectly valid.
+ *
+ * The json reporter writes the report as a single line (`JSON.stringify` with no
+ * indentation), so the last line that parses AND carries `issues` is the report.
+ * Anything else on stdout is noise, whatever braces it happens to contain.
+ */
+function parseKnipReport(stdout) {
+    const lines = stdout.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line.startsWith('{'))
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (Array.isArray(parsed.issues))
+                return parsed;
+        }
+        catch {
+            // A noise line that merely looks like JSON — keep scanning upwards.
+        }
+    }
+    return null;
+}
 /** Collect the names reported for one issue type across every file in the report. */
 function collectNames(issues, key) {
     return [...new Set(issues.flatMap(issue => (issue[key] ?? []).map(entry => entry.name)))];
@@ -122,18 +154,12 @@ exports.dependencyCheck = {
                 cwd: ctx.cwd,
                 reject: false,
             });
-            const start = stdout.indexOf('{');
-            const end = stdout.lastIndexOf('}');
-            // No JSON at all → the tool couldn't produce a result; skip rather than fail the client's PR.
-            if (start === -1 || end === -1)
-                return (0, types_1.skip)('knip produced no output');
-            let result;
-            try {
-                result = JSON.parse(stdout.slice(start, end + 1));
-            }
-            catch {
-                return (0, types_1.fail)('knip produced invalid JSON');
-            }
+            const result = parseKnipReport(stdout);
+            // No report on stdout → the tool couldn't produce a result; skip rather than
+            // fail the client's PR. Never fail here: a check that blocks a PR because a
+            // tool misbehaved reports our problem as the client's.
+            if (!result)
+                return (0, types_1.skip)('knip produced no report');
             const issues = result.issues ?? [];
             const unused = collectNames(issues, 'dependencies');
             const missing = collectNames(issues, 'unlisted');

package/dist/core/checks/dependencies/npm-audit.js

@@ -41,7 +41,28 @@ exports.npmAuditCheck = {
         const ignore = new Set((ctx.config.security?.['npm-audit']?.ignore ?? []).map(name => name.toLowerCase()));
         const ownName = getOwnPackageName();
         const { stdout } = await (0, execa_1.execa)('npm', ['audit', '--json'], { cwd: ctx.cwd, reject: false });
-        const report = JSON.parse(stdout);
+        // `npm audit` reports registry/lockfile problems as JSON on stdout, but not
+        // always: an absent npm (execa resolves with `code: 'ENOENT'`), a killed
+        // process or a proxy that answers with HTML all leave stdout unparseable.
+        // Parsing it bare made those cases throw, and a throw in a blocking check is
+        // a failed PR — the client saw "NPM Audit threw: Unexpected end of JSON
+        // input" and a red gate for an environment problem they did not cause.
+        let report;
+        try {
+            report = JSON.parse(stdout);
+        }
+        catch {
+            utils_1.logger.warn('[NPM Audit]: ⚠️ npm audit produced no parseable report — skipping');
+            return (0, types_1.skip)('npm audit produced no parseable report');
+        }
+        // A repo with no lockfile, or a registry npm cannot reach, yields
+        // `{"error":{"code":"ENOLOCK",…}}` — no `vulnerabilities` key at all. Passing
+        // on that reads as "no vulnerabilities" when nothing was actually audited.
+        if (report.error) {
+            const detail = report.error.summary ?? report.error.code ?? 'unknown error';
+            utils_1.logger.warn(`[NPM Audit]: ⚠️ npm could not audit this project — ${detail}`);
+            return (0, types_1.skip)(`npm audit unavailable: ${report.error.code ?? 'error'}`);
+        }
         const relevant = Object.values(report.vulnerabilities ?? {}).filter(v => v.isDirect && v.name !== ownName && isSeverityAtLeast(v.severity, auditLevel));
         const [ignored, directVulns] = relevant.reduce(([skip, block], v) => {
             (ignore.has(v.name.toLowerCase()) ? skip : block).push(v);

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

@@ -74,6 +74,15 @@ exports.lintCheck = {
             stdio: 'inherit',
             reject: false,
         });
-        return result.exitCode === 0 ? (0, types_1.pass)() : (0, types_1.fail)('lint errors found');
+        if (result.exitCode === 0)
+            return (0, types_1.pass)();
+        // ESLint exits 1 for lint errors and 2 for a fatal error — a config it cannot
+        // load, an unresolvable plugin, a parser it cannot construct. Only the
+        // former is the client's code. Treating exit 2 as "lint errors found" turned
+        // a config incompatibility (often between our bundled config and the client's
+        // toolchain) into a red gate on their PR, and named the wrong cause.
+        if (result.exitCode === 1)
+            return (0, types_1.fail)('lint errors found');
+        return (0, types_1.warn)(`eslint failed to run (exit ${result.exitCode ?? 'killed'})${hasLocal ? '' : ' — using the pr-checkmate config'}`);
     },
 };

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

@@ -52,6 +52,13 @@ exports.typecheckCheck = {
         const errorCount = (output.match(/error TS\d+/g) ?? []).length;
         if (output)
             utils_1.logger.warn(output);
+        // A non-zero exit with no diagnostic in it is not a type error — tsc was
+        // killed (OOM on a large project), crashed, or never started. Reporting that
+        // as `0 type error(s)` blocked PRs with a message naming nothing to fix.
+        if (errorCount === 0) {
+            utils_1.logger.warn(`[TypeScript]: ⚠️ tsc exited ${result.exitCode ?? 'abnormally'} without reporting a type error — treating as a tooling failure, not a type error`);
+            return (0, types_1.warn)(`tsc failed to run (exit ${result.exitCode ?? 'killed'})`);
+        }
         return (0, types_1.fail)(`${errorCount} type error(s)`);
     },
 };

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

@@ -91,7 +91,16 @@ exports.markdownLintCheck = {
                 reject: false,
                 stdio: 'inherit',
             });
-            return result.exitCode === 0 ? (0, types_1.pass)() : (0, types_1.warn)('markdown lint issues found');
+            if (result.exitCode === 0)
+                return (0, types_1.pass)();
+            // markdownlint-cli2 exits 1 for lint findings and 2 when it could not run
+            // (an unreadable config, a bad glob). Reporting the latter as "markdown lint
+            // issues found" names the wrong cause — and under `severity: error` it
+            // becomes a gate on a tooling problem.
+            if (result.exitCode === 2) {
+                return (0, types_1.warn)('markdownlint failed to run (exit 2) — check the markdownlint config');
+            }
+            return (0, types_1.warn)('markdown lint issues found');
         }
         finally {
             if (tempConfigFile && node_fs_1.default.existsSync(tempConfigFile))

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/security/security.js

@@ -17,7 +17,18 @@ exports.securityCheck = {
         return ctx.config.security?.gitleaks?.enabled !== false;
     },
     async run(ctx) {
-        const gitleaksBin = (0, utils_1.resolvePackageBin)('gitleaks-secret-scanner-fixed', 'bin/cli.js');
+        // A binary that cannot be resolved throws, and a throw in a blocking check is
+        // a failed PR — the client would see "Security Scan threw: Cannot resolve
+        // binary" as a red gate on a repo with no secrets in it. Every other bundled
+        // tool (knip, license-checker) already skips here; this one did not.
+        let gitleaksBin;
+        try {
+            gitleaksBin = (0, utils_1.resolvePackageBin)('gitleaks-secret-scanner-fixed', 'bin/cli.js');
+        }
+        catch {
+            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',

package/dist/init.js

@@ -58,8 +58,14 @@ const DEFAULT_CONFIG = {
     prettier: {
         rules: {},
     },
-    // Cspell customization
+    // Spellcheck (cspell). `enabled: false` turns the check off — that part always
+    // applies. The lists feed the cspell config pr-checkmate generates, so they are
+    // ignored when the repo has a cspell.json of its own; all of them are appended to
+    // the bundled defaults. `ignorePaths` takes globs to skip (e.g. "CHANGELOG.md",
+    // "generated/**"), anchored to the repo root so a pattern never matches a
+    // directory above the checkout.
     cspell: {
+        enabled: true,
         words: [],
         ignorePaths: [],
         ignoreRegExpList: [],
@@ -109,6 +115,19 @@ const DEFAULT_CONFIG = {
         // which knip can't see as imports and would report as unused).
         ignore: [],
     },
+    // Circular-import check (dpdm, bundled — nothing needed on the runner). Uses
+    // the project's own dpdm when it has one. Advisory by default (severity
+    // "warn"): most repos have long-standing cycles through barrel files, so see
+    // yours first, then set severity "error" to gate merges on them. enabled false
+    // disables the check; `ignore` takes glob patterns kept out of the analysis
+    // (generated or vendored code, or barrels whose cycles you tolerate). When the
+    // analyzer cannot run, the check skips rather than passing or failing.
+    circularDeps: {
+        enabled: true,
+        severity: 'warn',
+        ignore: [],
+        timeoutMs: 120000,
+    },
     // Unused-exports check (ts-unused-exports)
     deadCode: {
         enabled: true,

package/dist/interfaces/index.d.ts

@@ -19,6 +19,8 @@ export interface CspellConfig {
     ignorePaths: string[];
     enableFiletypes: string[];
     ignoreRegExpList: string[];
+    dictionaries?: string[];
+    enabled?: boolean;
 }
 export interface PRCheckMateConfig {
     sourcePath: string | string[];
@@ -42,10 +44,19 @@ export interface PRCheckMateConfig {
         config?: Record<string, any>;
     };
     spellcheck?: {
+        enabled?: boolean;
         words?: string[];
         ignoreWords?: string[];
         ignorePaths?: string[];
     };
+    cspell?: {
+        enabled?: boolean;
+        words?: string[];
+        ignorePaths?: string[];
+        ignoreRegExpList?: string[];
+        dictionaries?: string[];
+        language?: string;
+    };
     security?: {
         gitleaks?: {
             enabled?: boolean;
@@ -204,6 +215,12 @@ export interface PRCheckMateConfig {
         severity?: 'error' | 'warn';
         ignore?: string[];
     };
+    circularDeps?: {
+        enabled?: boolean;
+        severity?: 'error' | 'warn';
+        ignore?: string[];
+        timeoutMs?: number;
+    };
     vulnScan?: {
         enabled?: boolean;
         timeoutMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pr-checkmate",
-    "version": "1.23.18",
+    "version": "1.23.20",
     "description": "Automated PR quality checks: linting, formatting, dependency analysis, and spellcheck",
     "keywords": [
         "github-actions",
@@ -83,6 +83,7 @@
         "@typescript-eslint/parser": "^8.62.1",
         "@wasm-fmt/clang-format": "^22.1.8",
         "cspell": "^10.0.1",
+        "dpdm": "^4.2.0",
         "eslint": "^10.6.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-import-x": "^4.17.1",

package/pr-checkmate.schema.json

@@ -149,6 +149,18 @@
     "caseCollision": { "$ref": "#/$defs/toggle" },
     "sensitiveFileGuard": { "$ref": "#/$defs/toggle" },
     "configValidation": { "$ref": "#/$defs/toggle" },
+    "cspell": {
+      "description": "Spellcheck control. 'enabled: false' turns the check off. The other fields configure the cspell config pr-checkmate generates, so they apply only when the repository has no cspell.json of its own: 'words', 'ignorePaths', 'ignoreRegExpList' and 'dictionaries' are appended to the bundled defaults, 'language' replaces it. Ignore globs are anchored to the repository root, so '**/dist/**' never matches a directory above the checkout.",
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "language": { "type": "string" },
+        "words": { "type": "array", "items": { "type": "string" } },
+        "dictionaries": { "type": "array", "items": { "type": "string" } },
+        "ignorePaths": { "type": "array", "items": { "type": "string" } },
+        "ignoreRegExpList": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "yamlLint": {
       "type": "object",
       "properties": {
@@ -157,6 +169,15 @@
         "ignore": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "circularDeps": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "severity": { "enum": ["error", "warn"] },
+        "ignore": { "type": "array", "items": { "type": "string" } },
+        "timeoutMs": { "type": "number" }
+      }
+    },
     "typecheck": { "$ref": "#/$defs/toggle" },
     "prBody": {
       "type": "object",

package/src/config/cspell.json

@@ -309,6 +309,7 @@
     "dont",
     "Dorg",
     "dotenv",
+    "dotenvx",
     "dotnet",
     "DPARALLEL",
     "dpdm",
@@ -343,6 +344,7 @@
     "endtable",
     "engineio",
     "ENOENT",
+    "ENOLOCK",
     "eoilist",
     "Escaneá",
     "Escaneás",
@@ -1235,23 +1237,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/src/config/pr-checkmate.schema.json

@@ -149,6 +149,18 @@
     "caseCollision": { "$ref": "#/$defs/toggle" },
     "sensitiveFileGuard": { "$ref": "#/$defs/toggle" },
     "configValidation": { "$ref": "#/$defs/toggle" },
+    "cspell": {
+      "description": "Spellcheck control. 'enabled: false' turns the check off. The other fields configure the cspell config pr-checkmate generates, so they apply only when the repository has no cspell.json of its own: 'words', 'ignorePaths', 'ignoreRegExpList' and 'dictionaries' are appended to the bundled defaults, 'language' replaces it. Ignore globs are anchored to the repository root, so '**/dist/**' never matches a directory above the checkout.",
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "language": { "type": "string" },
+        "words": { "type": "array", "items": { "type": "string" } },
+        "dictionaries": { "type": "array", "items": { "type": "string" } },
+        "ignorePaths": { "type": "array", "items": { "type": "string" } },
+        "ignoreRegExpList": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "yamlLint": {
       "type": "object",
       "properties": {
@@ -157,6 +169,15 @@
         "ignore": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "circularDeps": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "severity": { "enum": ["error", "warn"] },
+        "ignore": { "type": "array", "items": { "type": "string" } },
+        "timeoutMs": { "type": "number" }
+      }
+    },
     "typecheck": { "$ref": "#/$defs/toggle" },
     "prBody": {
       "type": "object",