pr-checkmate 2.0.0 → 2.1.0

package/README.md

@@ -10,6 +10,7 @@
 ![cspell](https://img.shields.io/badge/cspell-10-4285F4)
 ![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)
+[![Container](https://img.shields.io/badge/ghcr.io-pr--checkmate-2496ED?logo=docker&logoColor=white)](https://github.com/users/Mybono/packages/container/package/pr-checkmate)
 
 > PR CheckMate is a security-first PR gate: secret scanning, dependency
 > vulnerability checks, and a signed SBOM + independent VirusTotal scan on
@@ -121,13 +122,38 @@ 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
+Only three checks genuinely need a diff and drop out of a full scan — PR Size, Missing
+Tests and Lockfile Drift. Everything else, the whole security family included, scans the
+working tree when there is no diff to read. 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
 
+**Use the container.** With no `node_modules` to reuse, a cold `npx` downloads 547 MB and
+takes about five minutes — on every job. The image carries the whole toolchain already:
+
+```bash
+docker run --rm -v "$PWD:/repo" --user "$(id -u):$(id -g)" \
+  ghcr.io/mybono/pr-checkmate:latest all
+```
+
+161 MB pulled once and cached by the runner, and the checks that need a binary on the
+machine — ShellCheck among them — are inside, so they stop silently skipping. Pin the
+version tag (`:2.0.0`) for a reproducible pipeline; `--user` keeps files that formatters
+rewrite owned by you rather than by root.
+
+Verify what you pulled — the image carries build provenance signed by the workflow
+that produced it:
+
+```bash
+gh attestation verify oci://ghcr.io/mybono/pr-checkmate:2 --owner Mybono
+```
+
+[All tags →](https://github.com/users/Mybono/packages/container/package/pr-checkmate)
+
+The `npx` route still works, and the rest of this section is about making it comfortable.
+
 Plenty of repos never add pr-checkmate to `package.json` and call it on the fly in CI
 instead (`npx pr-checkmate`). That works, but there is no `node_modules` to generate a
 config from, so the run silently falls back to the defaults with no file to tune.

package/cspell.json

@@ -1752,7 +1752,14 @@
     "/**/yarn.lock",
     "/**/pnpm-lock.yaml",
     "/**/*.min.js",
-    "/**/*.min.css"
+    "/**/*.min.css",
+    "/CHANGELOG.md",
+    "/**/__tests__/**",
+    "/**/__mocks__/**",
+    "/**/*.test.*",
+    "/**/*.spec.*",
+    "/**/test/**",
+    "/**/tests/**"
   ],
   "enableFiletypes": ["typescript", "javascript", "markdown", "json"],
   "ignoreRegExpList": ["/https?:\\/\\/[^\\s]+/g", "/\\b[0-9a-f]{7,40}\\b/gi"]

package/dist/config/constants.d.ts

@@ -17,6 +17,18 @@ export declare const IGNORED_DIRS: string[];
  * nested report globs that are not plain directory names.
  */
 export declare const IGNORE_PATTERNS: string[];
+/**
+ * Where test code lives, as globs.
+ *
+ * Deliberately NOT part of {@link IGNORED_DIRS}: that list hides a directory from
+ * every check, and test code still wants linting, type-checking and formatting.
+ * What test code does not want is the handful of checks whose findings are noise
+ * on it — duplication (setup boilerplate repeats by design), unused exports (the
+ * runner consumes them), spelling (fixture identifiers) and the diff security
+ * scan (a test's whole job may be to call the dangerous thing). Each of those
+ * defaults to this list, and each lets a client replace it.
+ */
+export declare const TEST_PATH_GLOBS: string[];
 /**
  * Test files/folders excluded from duplicate-code detection by default.
  * Test suites legitimately repeat setup/arrange/assert boilerplate, so counting
@@ -24,6 +36,24 @@ export declare const IGNORE_PATTERNS: string[];
  * override this list via `duplicate.ignore` in pr-checkmate.json.
  */
 export declare const DUPLICATE_IGNORE_DEFAULTS: string[];
+/**
+ * Paths the diff security scan skips by default.
+ *
+ * A security test corpus is built out of the exact constructs the scan hunts for
+ * — `eval()`, `document.write()`, `__proto__` — so scanning it turns every added
+ * test case into a finding, and under `severity: error` into a blocked merge.
+ * Clients can override via `diffSecurity.ignorePaths` (which REPLACES this list).
+ */
+export declare const DIFF_SECURITY_IGNORE_DEFAULTS: string[];
+/**
+ * Files written by a release tool rather than by a person.
+ *
+ * `CHANGELOG.md` is assembled from commit subjects, so every typo anyone has ever
+ * committed reappears in it — 39 of 42 spellcheck findings in one real repository
+ * came from that one file, none of them actionable: the text cannot be corrected
+ * without rewriting git history, and the next release regenerates it anyway.
+ */
+export declare const GENERATED_DOC_FILES: string[];
 /**
  * Files excluded from the dead-code (unused-exports) report by default. These are
  * REGEX sources (matched against each reported file path), not globs — dead-code's

package/dist/config/constants.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_CONFIG_KEYS = exports.CONFIG_FILE = exports.documentation = exports.FULL_CONFIG_URL = exports.DOCS_URL = exports.DEFAULT_ALLOW_PACKAGES = exports.DEFAULT_COMMANDS = exports.SOURCE_EXTENSIONS = exports.DUPLICATE_CODE_FORMATS = exports.CONFIG_FILE_PATTERNS = exports.DEAD_CODE_IGNORE_DEFAULTS = exports.DUPLICATE_IGNORE_DEFAULTS = exports.IGNORE_PATTERNS = exports.IGNORED_DIRS = void 0;
+exports.KNOWN_CONFIG_KEYS = exports.CONFIG_FILE = exports.documentation = exports.FULL_CONFIG_URL = exports.DOCS_URL = exports.DEFAULT_ALLOW_PACKAGES = exports.DEFAULT_COMMANDS = exports.SOURCE_EXTENSIONS = exports.DUPLICATE_CODE_FORMATS = exports.CONFIG_FILE_PATTERNS = exports.DEAD_CODE_IGNORE_DEFAULTS = exports.GENERATED_DOC_FILES = exports.DIFF_SECURITY_IGNORE_DEFAULTS = exports.DUPLICATE_IGNORE_DEFAULTS = exports.TEST_PATH_GLOBS = exports.IGNORE_PATTERNS = exports.IGNORED_DIRS = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 /**
  * Build output, dependency, tooling, and report directories that are never
@@ -86,6 +86,11 @@ exports.IGNORED_DIRS = [
     'allure-results',
     'playwright-report',
     '.wdio',
+    // Generated knowledge-graph output. Committed by repos that keep the graph in
+    // version control, and machine-written from end to end: a multi-megabyte
+    // `graph.json` trips the large-file check, and `GRAPH_REPORT.md` carries every
+    // identifier in the codebase past the spellchecker. Neither is anyone's source.
+    'graphify-out',
 ];
 /**
  * Glob form of the ignore list, for tools that take glob ignores directly
@@ -110,12 +115,17 @@ exports.IGNORE_PATTERNS = [
     '**/audit-report/**',
 ];
 /**
- * Test files/folders excluded from duplicate-code detection by default.
- * Test suites legitimately repeat setup/arrange/assert boilerplate, so counting
- * them as clones is noise that drowns out real production duplication. Clients can
- * override this list via `duplicate.ignore` in pr-checkmate.json.
+ * Where test code lives, as globs.
+ *
+ * Deliberately NOT part of {@link IGNORED_DIRS}: that list hides a directory from
+ * every check, and test code still wants linting, type-checking and formatting.
+ * What test code does not want is the handful of checks whose findings are noise
+ * on it — duplication (setup boilerplate repeats by design), unused exports (the
+ * runner consumes them), spelling (fixture identifiers) and the diff security
+ * scan (a test's whole job may be to call the dangerous thing). Each of those
+ * defaults to this list, and each lets a client replace it.
  */
-exports.DUPLICATE_IGNORE_DEFAULTS = [
+exports.TEST_PATH_GLOBS = [
     '**/__tests__/**',
     '**/__mocks__/**',
     '**/*.test.*',
@@ -123,6 +133,31 @@ exports.DUPLICATE_IGNORE_DEFAULTS = [
     '**/test/**',
     '**/tests/**',
 ];
+/**
+ * Test files/folders excluded from duplicate-code detection by default.
+ * Test suites legitimately repeat setup/arrange/assert boilerplate, so counting
+ * them as clones is noise that drowns out real production duplication. Clients can
+ * override this list via `duplicate.ignore` in pr-checkmate.json.
+ */
+exports.DUPLICATE_IGNORE_DEFAULTS = [...exports.TEST_PATH_GLOBS];
+/**
+ * Paths the diff security scan skips by default.
+ *
+ * A security test corpus is built out of the exact constructs the scan hunts for
+ * — `eval()`, `document.write()`, `__proto__` — so scanning it turns every added
+ * test case into a finding, and under `severity: error` into a blocked merge.
+ * Clients can override via `diffSecurity.ignorePaths` (which REPLACES this list).
+ */
+exports.DIFF_SECURITY_IGNORE_DEFAULTS = [...exports.TEST_PATH_GLOBS];
+/**
+ * Files written by a release tool rather than by a person.
+ *
+ * `CHANGELOG.md` is assembled from commit subjects, so every typo anyone has ever
+ * committed reappears in it — 39 of 42 spellcheck findings in one real repository
+ * came from that one file, none of them actionable: the text cannot be corrected
+ * without rewriting git history, and the next release regenerates it anyway.
+ */
+exports.GENERATED_DOC_FILES = ['CHANGELOG.md'];
 /**
  * Files excluded from the dead-code (unused-exports) report by default. These are
  * REGEX sources (matched against each reported file path), not globs — dead-code's

package/dist/config/pr-checkmate-workflow-docker.yml

@@ -0,0 +1,79 @@
+name: PR CheckMate
+
+# The container variant, scaffolded because this repository does not carry
+# pr-checkmate as a dependency.
+#
+# The alternative would be `npx pr-checkmate`, and with no node_modules to reuse
+# that resolves to whatever is newest on the registry and downloads it again on
+# every job: 547 MB and about five minutes, measured. Worse, a major release
+# would land on you without a line changing here — and a major release of a gate
+# can start failing builds that passed yesterday.
+#
+# The image is pulled once and cached by the runner, and the tag below pins the
+# major so nothing moves under you.
+
+on:
+  pull_request:
+    branches: [main, master, develop]
+    types: [opened, synchronize, reopened]
+
+# Least privilege. `pull-requests: write` is what lets the run upsert its summary
+# comment on the PR; drop it and the checks still run, they just report to the log.
+permissions:
+  contents: read
+  pull-requests: write
+
+# Push three times in a minute and the first two runs become answers to questions
+# nobody is asking any more — they still hold a runner, and they still race to
+# upsert the summary comment, so a stale verdict can land on top of a fresh one.
+# Keyed per PR, so runs on different pull requests never cancel each other.
+concurrency:
+  group: pr-checkmate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pr-checkmate:
+    name: PR CheckMate
+    runs-on: ubuntu-latest
+    # A hung step otherwise runs to GitHub's six-hour default before anyone hears
+    # about it. Every check has its own internal timeout; this is the backstop.
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          # Required, not optional. Without the full history the PR base commit is
+          # not in the clone, no diff range can be built, and every diff-based
+          # check skips itself. The run then says `Scan Scope: … set
+          # fetch-depth: 0`, which is this line.
+          fetch-depth: 0
+
+      # One job runs the whole registry. Which checks run is decided in
+      # pr-checkmate.json (`severity`), not by splitting this into jobs.
+      #
+      # `--user` is not a detail: without it every file a formatter rewrites comes
+      # back owned by root, and the next step in your pipeline fails on
+      # permissions long after this one reported success.
+      #
+      # The environment variables are passed through by name rather than by value:
+      # the run reads them to find the PR, and interpolating them into the command
+      # line would put their contents into a shell.
+      - name: Run PR CheckMate
+        env:
+          # Not injected automatically: without this the run cannot authenticate,
+          # and the summary comment silently never reaches the PR.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          docker run --rm \
+            -v "$PWD:/repo" \
+            --user "$(id -u):$(id -g)" \
+            -e GITHUB_TOKEN \
+            -e GITHUB_REPOSITORY \
+            -e GITHUB_EVENT_NAME \
+            -e GITHUB_EVENT_PATH \
+            -e GITHUB_REF \
+            -e GITHUB_SHA \
+            -e CI \
+            -v "$GITHUB_EVENT_PATH:$GITHUB_EVENT_PATH:ro" \
+            ghcr.io/mybono/pr-checkmate:__IMAGE_TAG__ all

package/dist/config/pr-checkmate-workflow.yml

@@ -11,10 +11,23 @@ permissions:
   contents: read
   pull-requests: write
 
+# Push three times in a minute and the first two runs become answers to questions
+# nobody is asking any more — they still hold a runner, and they still race to
+# upsert the summary comment, so a stale verdict can land on top of a fresh one.
+# Keyed per PR, so runs on different pull requests never cancel each other.
+concurrency:
+  group: pr-checkmate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   pr-checkmate:
     name: PR CheckMate
     runs-on: ubuntu-latest
+    # A hung step otherwise runs to GitHub's six-hour default before anyone hears
+    # about it. Every check here has its own internal timeout; this is the backstop
+    # for the ones that cannot fail themselves — a wedged network fetch, a tool
+    # waiting on stdin. Raise it for a large monorepo.
+    timeout-minutes: 20
     steps:
       - name: Checkout code
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
@@ -48,9 +61,29 @@ jobs:
           restore-keys: |
             pr-checkmate-${{ runner.os }}-
 
+      # Grype keeps its own vulnerability database, and it is the single largest
+      # download in the whole run: 134 MB compressed, 1.9 GB unpacked, refreshed
+      # daily upstream. Without this step every job pays for it again. The key is
+      # dated rather than content-hashed, because the thing that changes is the
+      # upstream database, not anything in this repository — a stale entry is
+      # restored by the prefix and grype updates it in place.
+      - name: Cache Grype vulnerability database
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.cache/grype
+          key: grype-db-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: |
+            grype-db-${{ runner.os }}-
+
       # One job runs the whole registry. Splitting it per check would repeat the
       # checkout and install for every one of them, and the selection of what runs
       # belongs in pr-checkmate.json (`severity`), not in copied YAML.
+      #
+      # This template is the one `init` scaffolds when pr-checkmate IS a
+      # dependency: `npm ci` above installs it, so npx runs that copy at the
+      # version your lockfile pins. A repository that does not install it gets
+      # the container variant instead, because bare `npx` would resolve to the
+      # newest release and download it on every job.
       - name: Run PR CheckMate
         env:
           # Not injected automatically: without this the run cannot authenticate,

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

@@ -72,15 +72,20 @@ exports.markdownLintCheck = {
             'coverage/**',
             'graphify-out/**',
             '.claude/**',
+            // Release-tool output, not prose anyone edits — see GENERATED_DOC_FILES.
+            ...config_1.GENERATED_DOC_FILES,
             ...(userConfig.ignores ?? []),
         ];
         // markdownlint-cli2 has no --ignore-path flag; exclusions are expressed as
         // negated globs (`#pattern`). A bare directory name also needs `#name/**`
-        // to exclude its contents.
+        // to exclude its contents — but a filename does not, and `#CHANGELOG.md/**`
+        // is a glob that can never match. `path.extname` is what tells them apart,
+        // and it reads a leading dot as part of the name, so `.claude` is still
+        // treated as the directory it is.
         const ignoreGlobs = defaultIgnorePatterns.flatMap(pattern => {
             const clean = pattern.replace(/\/+$/, '');
             const globs = [`#${clean}`];
-            if (!clean.includes('*'))
+            if (!clean.includes('*') && !node_path_1.default.extname(clean))
                 globs.push(`#${clean}/**`);
             return globs;
         });

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.diffSecurityCheck = void 0;
+const config_1 = require("../../../config");
 const utils_1 = require("../../../utils");
 const targets_1 = require("../../targets");
 const types_1 = require("../../types");
@@ -293,7 +294,10 @@ exports.diffSecurityCheck = {
             const found = (0, findings_1.emptyBuckets)();
             const scanOpts = {
                 comments: cfg.commentHandling ?? 'language',
-                ignorePaths: cfg.ignorePaths,
+                // Setting `ignorePaths` REPLACES the test-path defaults rather than adding
+                // to them, matching `duplicate.ignore` and `deadCode.ignoreFiles`. A client
+                // who wants their tests scanned says so by listing something else here.
+                ignorePaths: cfg.ignorePaths ?? config_1.DIFF_SECURITY_IGNORE_DEFAULTS,
             };
             const extra = compileExtraPatterns(ctx);
             const disabled = cfg.disablePatterns ?? [];

package/dist/core/run-checks.d.ts

@@ -1,4 +1,28 @@
-import { CheckReport, RunOptions } from './types';
+import type { RunScope } from './types';
+import { CheckContext, CheckReport, CheckStatus, RunOptions } from './types';
+/**
+ * Apply the universal `config.severity` override for a check. Only remaps
+ * between warn↔fail (pass/skip are never changed); `off` is handled earlier by
+ * excluding the check from the run entirely. This is what lets a repo turn any
+ * advisory check into a gate, or downgrade a blocking one, by name.
+ */
+export declare function applySeverity(name: string, status: CheckStatus, ctx: CheckContext): CheckStatus;
+/**
+ * Whether a diff-only check's skip is worth a row in the report.
+ *
+ * The two cases look identical from inside the check and are opposites to the
+ * person reading the result:
+ *
+ * - The range is missing because the run FELL BACK to a full scan — a shallow
+ *   clone, an unreachable PR base. Coverage was lost without anyone choosing
+ *   that, and saying nothing is how it stays lost (ticket 057).
+ * - The full scan was ASKED FOR. `--full` means "look at everything now", so
+ *   three rows explaining that three checks review a diff repeat what the reader
+ *   just said and push the real findings further down.
+ *
+ * `always` and `never` remain absolute; only `auto` distinguishes them.
+ */
+export declare function shouldReportDiffSkip(scope: RunScope | undefined, reportSkipped?: 'auto' | 'always' | 'never'): boolean;
 /**
  * Run all applicable checks and return a structured report.
  *

package/dist/core/run-checks.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.applySeverity = applySeverity;
+exports.shouldReportDiffSkip = shouldReportDiffSkip;
 exports.runChecks = runChecks;
 const utils_1 = require("../utils");
 const pool_1 = require("../utils/pool");
@@ -71,6 +73,29 @@ function applySeverity(name, status, ctx) {
         return 'warn';
     return status;
 }
+/**
+ * Whether a diff-only check's skip is worth a row in the report.
+ *
+ * The two cases look identical from inside the check and are opposites to the
+ * person reading the result:
+ *
+ * - The range is missing because the run FELL BACK to a full scan — a shallow
+ *   clone, an unreachable PR base. Coverage was lost without anyone choosing
+ *   that, and saying nothing is how it stays lost (ticket 057).
+ * - The full scan was ASKED FOR. `--full` means "look at everything now", so
+ *   three rows explaining that three checks review a diff repeat what the reader
+ *   just said and push the real findings further down.
+ *
+ * `always` and `never` remain absolute; only `auto` distinguishes them.
+ */
+function shouldReportDiffSkip(scope, reportSkipped = 'auto') {
+    if (reportSkipped === 'never')
+        return false;
+    if (reportSkipped === 'always')
+        return true;
+    const askedForFullScan = scope?.kind === 'full' && !scope.degraded;
+    return !askedForFullScan;
+}
 /**
  * Why a `requiresDiff` check could not run, phrased for the person reading the
  * report. A full scan the client asked for is expected; one we fell back to is
@@ -90,11 +115,19 @@ function noDiffReason(ctx) {
  */
 async function runOne(check, ctx, collector, heavy) {
     try {
-        // A diff-only check without a range is a hole in coverage, not an
-        // irrelevance: report it as a skip so the gap is visible in the summary.
+        // A diff-only check without a range is usually a hole in coverage rather
+        // than an irrelevance, so it is reported as a skip and the gap stays visible
+        // (ticket 057).
+        //
+        // Except when the whole-repository scan was ASKED FOR. `--full` means "look
+        // at everything now", and answering with three rows explaining that three
+        // checks review a diff tells the reader something they just said themselves.
+        // A degraded scope still reports: there the missing range is a symptom —
+        // a shallow clone, an unreachable base — and staying quiet about it is how
+        // coverage disappears unnoticed.
         if (check.requiresDiff && !ctx.baseSha) {
-            const show = ctx.config.run?.reportSkipped ?? 'auto';
-            if (show !== 'never' && (await check.applies(ctx))) {
+            if (shouldReportDiffSkip(ctx.scope, ctx.config.run?.reportSkipped) &&
+                (await check.applies(ctx))) {
                 collector.register(check.name, 'skip', noDiffReason(ctx));
             }
             return;

package/dist/init.js

@@ -91,7 +91,21 @@ const ADVISORY_FLAG = '        continue-on-error: true';
  * were just asked about.
  */
 function setupWorkflow(root, mode) {
-    const workflowSource = path_1.default.join(__dirname, 'config', 'pr-checkmate-workflow.yml');
+    // Which template a repository gets is decided by whether it actually installs
+    // us. Both are correct for their own case and wrong for the other:
+    //
+    //  - a dependency means `npx pr-checkmate` runs the copy the lockfile pins,
+    //    which is fast and reproducible;
+    //  - no dependency means `npx` resolves to the newest release and downloads it
+    //    on every job — 547 MB, about five minutes, and a major version can land
+    //    without anyone changing a line.
+    //
+    // Asking the client to notice that difference in a comment is asking them to
+    // read a file they scaffolded precisely so they would not have to.
+    const source = installsPackage(root)
+        ? 'pr-checkmate-workflow.yml'
+        : 'pr-checkmate-workflow-docker.yml';
+    const workflowSource = path_1.default.join(__dirname, 'config', source);
     const workflowDir = path_1.default.join(root, '.github', 'workflows');
     const workflowDest = path_1.default.join(workflowDir, 'pr-checkmate.yml');
     if (!fs_1.default.existsSync(workflowSource)) {
@@ -105,13 +119,46 @@ function setupWorkflow(root, mode) {
     if (!fs_1.default.existsSync(workflowDir)) {
         fs_1.default.mkdirSync(workflowDir, { recursive: true });
     }
-    const template = fs_1.default.readFileSync(workflowSource, 'utf-8');
+    const template = fs_1.default.readFileSync(workflowSource, 'utf-8').replace(/__IMAGE_TAG__/g, imageTag());
     const workflow = mode === 'advisory'
         ? template.replace(RUN_STEP_ANCHOR, `${ADVISORY_NOTICE}\n${RUN_STEP_ANCHOR}\n${ADVISORY_FLAG}`)
         : template;
     fs_1.default.writeFileSync(workflowDest, workflow);
     utils_1.logger.info(`[init]: ✅ Created .github/workflows/pr-checkmate.yml (${mode === 'strict' ? 'blocking' : 'advisory'})`);
 }
+/**
+ * Whether this repository installs pr-checkmate rather than reaching for it on
+ * the pipeline. A missing or unreadable package.json answers "no", which is the
+ * safe way round: the container variant works either way, while the npm variant
+ * assumes an install that may not happen.
+ */
+function installsPackage(root) {
+    try {
+        const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(root, 'package.json'), 'utf-8'));
+        return Boolean(pkg.dependencies?.['pr-checkmate'] ?? pkg.devDependencies?.['pr-checkmate']);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The image tag written into the generated workflow: our own major.
+ *
+ * Pinned to a major rather than to `latest`, so patches and features arrive on
+ * their own while a change that can start failing builds does not. Pinned to a
+ * major rather than an exact version, so a client is not left on a release with
+ * a known problem because nobody remembered to bump a YAML file.
+ */
+function imageTag() {
+    try {
+        const manifest = path_1.default.resolve(__dirname, '..', 'package.json');
+        const version = JSON.parse(fs_1.default.readFileSync(manifest, 'utf-8')).version;
+        return version.split('.')[0] || 'latest';
+    }
+    catch {
+        return 'latest';
+    }
+}
 /** Where the advisory banner is spliced in — the step that runs the checks. */
 const RUN_STEP_ANCHOR = '      - name: Run PR CheckMate';
 /** Create a tsconfig.json scaffold if the consumer repo lacks one. */
@@ -217,30 +264,62 @@ function buildInitialConfig(sourcePath, languages) {
         commands: config_1.DEFAULT_COMMANDS,
         '// reporting': REPORTING_HINT,
         sourcePath,
-        // What can stop a merge, and how to stand any of it down. "warn" keeps the
-        // finding in the report without failing the run; "off" removes the check.
-        severity: Object.fromEntries(exports.BLOCKING_BY_DEFAULT.map(name => [name, 'error'])),
-        // The knobs people reach for first, seeded EMPTY.
+        // Which checks can stop a merge — named, but NOT written as values.
+        //
+        // Writing `"Workflow Security": "error"` reads like a statement of the
+        // default and is not one: the map promotes as well as demotes, so an entry
+        // of "error" turns that check's ADVISORY findings into failures too. On a
+        // real client repository that flipped 54 warnings into a red build. The
+        // names belong in a comment; the map stays empty until the client means
+        // something by it.
+        '// severity': [
+            `These checks fail a run by default: ${exports.BLOCKING_BY_DEFAULT.join(', ')}.`,
+            'To stand one down, add it below with "warn" (stays in the report, stops',
+            'blocking) or "off" (does not run at all).',
+            'Adding a check with "error" is not a restatement of the default — it also',
+            "PROMOTES that check's advisory findings to failures, which is stricter.",
+        ].join(' '),
+        severity: {},
+        // The knobs people reach for first.
         //
-        // Empty is the whole point: an empty container changes nothing, so it cannot
-        // freeze today's default in someone else's repository, but it puts the edit
-        // one line away instead of behind a lookup. Which blocks appear here is
-        // decided by what actually makes noise in real repositories — spelling,
-        // lint rules, generated files, knip's guesses about unused dependencies.
+        // Two shapes appear here, and the difference is not cosmetic. A list whose
+        // values are APPENDED to the defaults is seeded empty: empty changes nothing,
+        // so it cannot freeze today's default in someone else's repository. A list
+        // that REPLACES its default is written out in full instead — seeded empty it
+        // would silently switch the default off, and left out entirely it would be
+        // invisible, which is how a repository ends up spellchecking its own
+        // CHANGELOG and reporting every test fixture as duplication.
         //
-        // Three blocks are deliberately NOT here, because for them an empty value is
-        // not neutral — it REPLACES a non-empty default and makes things worse:
-        //   ignoreDirs           → seeded empty, nothing is ignored at all
-        //   duplicate.ignore     → test boilerplate starts reporting as duplication
-        //   deadCode.ignoreFiles → test helpers start reporting as unused exports
-        // Anyone who needs those sets them deliberately, with the defaults in view.
+        // Written-out lists are a deliberate trade: they stop tracking the package,
+        // so a later release that adds a directory to the defaults will not reach a
+        // config that already spells the list out. That is the price of being able
+        // to see and edit the value, and it is the one people asked for.
         excludePaths: [],
+        // REPLACES the default. Copied out so the list is editable in place —
+        // note that ESLint does not read it; ESLint honours `eslint.ignorePatterns`.
+        ignoreDirs: [...config_1.IGNORED_DIRS],
+        // Spelling: `words` and `ignorePaths` are both APPENDED to the bundled lists,
+        // so both stay empty. What the bundled list already skips is spelled out in
+        // the sibling comment rather than duplicated here.
+        '// cspell': `Already skipped by default: ${config_1.GENERATED_DOC_FILES.join(', ')}, test and mock paths, lockfiles, minified bundles, and every directory in "ignoreDirs". Anything listed below is ADDED to that.`,
         cspell: { words: [], ignorePaths: [] },
-        eslint: { rules: {}, ignorePatterns: [] },
+        // `max-len` is written out at its default rather than left implicit: it is
+        // the rule people hit first and tune first, and a line limit is a house
+        // style, not a defect — arguing with it through documentation wastes
+        // everyone's time when the number could just be sitting here, editable.
+        eslint: { rules: { 'max-len': ['warn', { code: 300 }] }, ignorePatterns: [] },
         markdownlint: { ignores: [] },
         dependency: { ignore: [] },
         circularDeps: { ignore: [] },
         yamlLint: { ignore: [] },
+        // The three lists that REPLACE their defaults, written out. Each one exists
+        // because test code trips a check that production code does not: suites
+        // repeat their setup, the runner is the only consumer of what they export,
+        // and a security test's whole job may be to call the dangerous function.
+        // Delete an entry to have that check start reporting on tests again.
+        duplicate: { ignore: [...config_1.DUPLICATE_IGNORE_DEFAULTS] },
+        deadCode: { ignoreFiles: [...config_1.DEAD_CODE_IGNORE_DEFAULTS] },
+        diffSecurity: { ignorePaths: [...config_1.DIFF_SECURITY_IGNORE_DEFAULTS] },
         documentation: config_1.documentation,
         languages,
     };

package/dist/scripts/copy-configs.js

@@ -17,6 +17,10 @@ const configFiles = [
     { source: 'src/config/cspell.json', dest: 'cspell.json' },
     { source: 'tsconfig.json', dest: 'tsconfig.json' },
     { source: 'src/config/pr-checkmate-workflow.yml', dest: 'dist/config/pr-checkmate-workflow.yml' },
+    {
+        source: 'src/config/pr-checkmate-workflow-docker.yml',
+        dest: 'dist/config/pr-checkmate-workflow-docker.yml',
+    },
     { source: 'src/config/pr-checkmate.schema.json', dest: 'pr-checkmate.schema.json' },
 ];
 /**

package/eslint-default-rules.json

@@ -12,7 +12,7 @@
   "@typescript-eslint/no-floating-promises": ["error"],
   "space-before-function-paren": "off",
   "operator-linebreak": "off",
-  "max-len": ["warn", { "code": 100 }],
+  "max-len": ["warn", { "code": 300 }],
   "semi": ["warn", "always"],
   "quotes": ["warn", "single", { "avoidEscape": true }],
   "object-curly-spacing": ["warn", "always"],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pr-checkmate",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "Security-first PR gate for CI: secret scanning, grype dependency scanning, SBOM — plus linting and formatting across 11 languages",
     "keywords": [
         "github-actions",
@@ -34,6 +34,7 @@
         ".prettierrc",
         "cspell.json",
         "src/config/pr-checkmate-workflow.yml",
+        "src/config/pr-checkmate-workflow-docker.yml",
         "pr-checkmate.schema.json",
         ".markdownlint.json",
         "gitleaks.toml",

package/src/config/cspell.json

@@ -1752,7 +1752,14 @@
     "/**/yarn.lock",
     "/**/pnpm-lock.yaml",
     "/**/*.min.js",
-    "/**/*.min.css"
+    "/**/*.min.css",
+    "/CHANGELOG.md",
+    "/**/__tests__/**",
+    "/**/__mocks__/**",
+    "/**/*.test.*",
+    "/**/*.spec.*",
+    "/**/test/**",
+    "/**/tests/**"
   ],
   "enableFiletypes": ["typescript", "javascript", "markdown", "json"],
   "ignoreRegExpList": ["/https?:\\/\\/[^\\s]+/g", "/\\b[0-9a-f]{7,40}\\b/gi"]

package/src/config/eslint-default-rules.json

@@ -12,7 +12,7 @@
   "@typescript-eslint/no-floating-promises": ["error"],
   "space-before-function-paren": "off",
   "operator-linebreak": "off",
-  "max-len": ["warn", { "code": 100 }],
+  "max-len": ["warn", { "code": 300 }],
   "semi": ["warn", "always"],
   "quotes": ["warn", "single", { "avoidEscape": true }],
   "object-curly-spacing": ["warn", "always"],

package/src/config/pr-checkmate-workflow-docker.yml

@@ -0,0 +1,79 @@
+name: PR CheckMate
+
+# The container variant, scaffolded because this repository does not carry
+# pr-checkmate as a dependency.
+#
+# The alternative would be `npx pr-checkmate`, and with no node_modules to reuse
+# that resolves to whatever is newest on the registry and downloads it again on
+# every job: 547 MB and about five minutes, measured. Worse, a major release
+# would land on you without a line changing here — and a major release of a gate
+# can start failing builds that passed yesterday.
+#
+# The image is pulled once and cached by the runner, and the tag below pins the
+# major so nothing moves under you.
+
+on:
+  pull_request:
+    branches: [main, master, develop]
+    types: [opened, synchronize, reopened]
+
+# Least privilege. `pull-requests: write` is what lets the run upsert its summary
+# comment on the PR; drop it and the checks still run, they just report to the log.
+permissions:
+  contents: read
+  pull-requests: write
+
+# Push three times in a minute and the first two runs become answers to questions
+# nobody is asking any more — they still hold a runner, and they still race to
+# upsert the summary comment, so a stale verdict can land on top of a fresh one.
+# Keyed per PR, so runs on different pull requests never cancel each other.
+concurrency:
+  group: pr-checkmate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pr-checkmate:
+    name: PR CheckMate
+    runs-on: ubuntu-latest
+    # A hung step otherwise runs to GitHub's six-hour default before anyone hears
+    # about it. Every check has its own internal timeout; this is the backstop.
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          # Required, not optional. Without the full history the PR base commit is
+          # not in the clone, no diff range can be built, and every diff-based
+          # check skips itself. The run then says `Scan Scope: … set
+          # fetch-depth: 0`, which is this line.
+          fetch-depth: 0
+
+      # One job runs the whole registry. Which checks run is decided in
+      # pr-checkmate.json (`severity`), not by splitting this into jobs.
+      #
+      # `--user` is not a detail: without it every file a formatter rewrites comes
+      # back owned by root, and the next step in your pipeline fails on
+      # permissions long after this one reported success.
+      #
+      # The environment variables are passed through by name rather than by value:
+      # the run reads them to find the PR, and interpolating them into the command
+      # line would put their contents into a shell.
+      - name: Run PR CheckMate
+        env:
+          # Not injected automatically: without this the run cannot authenticate,
+          # and the summary comment silently never reaches the PR.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          docker run --rm \
+            -v "$PWD:/repo" \
+            --user "$(id -u):$(id -g)" \
+            -e GITHUB_TOKEN \
+            -e GITHUB_REPOSITORY \
+            -e GITHUB_EVENT_NAME \
+            -e GITHUB_EVENT_PATH \
+            -e GITHUB_REF \
+            -e GITHUB_SHA \
+            -e CI \
+            -v "$GITHUB_EVENT_PATH:$GITHUB_EVENT_PATH:ro" \
+            ghcr.io/mybono/pr-checkmate:__IMAGE_TAG__ all

package/src/config/pr-checkmate-workflow.yml

@@ -11,10 +11,23 @@ permissions:
   contents: read
   pull-requests: write
 
+# Push three times in a minute and the first two runs become answers to questions
+# nobody is asking any more — they still hold a runner, and they still race to
+# upsert the summary comment, so a stale verdict can land on top of a fresh one.
+# Keyed per PR, so runs on different pull requests never cancel each other.
+concurrency:
+  group: pr-checkmate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   pr-checkmate:
     name: PR CheckMate
     runs-on: ubuntu-latest
+    # A hung step otherwise runs to GitHub's six-hour default before anyone hears
+    # about it. Every check here has its own internal timeout; this is the backstop
+    # for the ones that cannot fail themselves — a wedged network fetch, a tool
+    # waiting on stdin. Raise it for a large monorepo.
+    timeout-minutes: 20
     steps:
       - name: Checkout code
         uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
@@ -48,9 +61,29 @@ jobs:
           restore-keys: |
             pr-checkmate-${{ runner.os }}-
 
+      # Grype keeps its own vulnerability database, and it is the single largest
+      # download in the whole run: 134 MB compressed, 1.9 GB unpacked, refreshed
+      # daily upstream. Without this step every job pays for it again. The key is
+      # dated rather than content-hashed, because the thing that changes is the
+      # upstream database, not anything in this repository — a stale entry is
+      # restored by the prefix and grype updates it in place.
+      - name: Cache Grype vulnerability database
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.cache/grype
+          key: grype-db-${{ runner.os }}-${{ github.run_id }}
+          restore-keys: |
+            grype-db-${{ runner.os }}-
+
       # One job runs the whole registry. Splitting it per check would repeat the
       # checkout and install for every one of them, and the selection of what runs
       # belongs in pr-checkmate.json (`severity`), not in copied YAML.
+      #
+      # This template is the one `init` scaffolds when pr-checkmate IS a
+      # dependency: `npm ci` above installs it, so npx runs that copy at the
+      # version your lockfile pins. A repository that does not install it gets
+      # the container variant instead, because bare `npx` would resolve to the
+      # newest release and download it on every job.
       - name: Run PR CheckMate
         env:
           # Not injected automatically: without this the run cannot authenticate,