pr-checkmate 1.23.24 → 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.
@@ -153,8 +179,9 @@ installed version.
 
 ## GitHub Actions
 
-Every workflow follows the same shape: checkout, set up Node, install, run. The
-TypeScript setup is the baseline:
+`init` generates this workflow; it is reproduced here so nothing about it is a
+surprise. One job runs the whole registry — which checks run is decided in
+`pr-checkmate.json`, not by copying YAML.
 
 ```yaml
 name: PR CheckMate
@@ -163,21 +190,57 @@ on:
     branches: [main]
 
 permissions:
-  contents: write
+  contents: read
   pull-requests: write
 
 jobs:
-  quality:
+  pr-checkmate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
         with: { fetch-depth: 0 }
-      - uses: actions/setup-node@v4
-        with: { node-version: 24 }
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with: { node-version: 24, cache: 'npm' }
       - run: npm ci
-      - run: npx pr-checkmate all
+      - name: Run PR CheckMate
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx pr-checkmate all
 ```
 
+Three lines are load-bearing:
+
+- `fetch-depth: 0` — without the full history the PR base is not in the clone, no
+  diff range can be built, and every diff-based check skips itself. The run says so
+  (`Scan Scope: … set fetch-depth: 0`) rather than reporting a clean pass.
+- `GITHUB_TOKEN` — Actions does not put it in the environment on its own. Without it
+  the checks still run, but the summary comment never reaches the PR.
+- no `continue-on-error` — a gate that cannot fail the job is not a gate.
+
+### Adopting it on an existing codebase
+
+The instinct on an existing codebase is to soften the workflow. Do the opposite: keep
+the gate real and relax individual checks in `pr-checkmate.json`, so whatever you have
+already made clean stays enforced.
+
+```jsonc
+{
+  // everything advisory to begin with…
+  "severityDefaults": { "failOn": "warn" },
+  // …except the ones you are ready to enforce
+  "severity": {
+    "Security Scan": "error",
+    "Diff Security": "error",
+    "Duplicate Code": "off"
+  }
+}
+```
+
+Promote checks one at a time as the codebase catches up. `pr-checkmate init` also
+offers an advisory workflow if you would rather start there, and it writes a banner
+explaining how to leave that mode. Either way, `init` never overwrites a workflow file
+that already exists.
+
 For a runner-dependency language, add its toolchain setup step before the run: Go with
 `actions/setup-go`, Rust with `dtolnay/rust-toolchain`, C# with `actions/setup-dotnet`,
 Ruby with `ruby/setup-ruby` (plus `gem install rubocop`), PHP with
@@ -209,8 +272,21 @@ covering when it runs, the config keys it reads, and how to turn it off.
 
 ## Configuration
 
-Everything lives in `pr-checkmate.json`. Run `npx pr-checkmate init` to scaffold the
-full file for your detected languages.
+Everything lives in one file, `pr-checkmate.json`. Run `npx pr-checkmate init` to
+scaffold it for your detected languages.
+
+The generated file is short on purpose: it holds your decisions plus a few empty
+blocks for the settings people tune most. Everything else stays implicit — the
+config is merged over the built-in defaults at load time, so new defaults reach
+you on upgrade without editing anything, and `init` is a first-run step rather
+than something to repeat after every release.
+
+**[The full configuration, annotated, with every option at its default →](https://github.com/Mybono/pr_checkmate_public/blob/main/pr-checkmate.json)**
+Copy the block you need into your file. The `$schema` line in the generated
+config also gives your editor autocomplete and a description for every key.
+
+Three settings REPLACE their default rather than extending it, so copy the
+default before editing: `ignoreDirs`, `duplicate.ignore`, `deadCode.ignoreFiles`.
 
 - Severity map. The one universal control. Key any check by its display name (as it
   appears in the report) and set `"error"` to fail the run, `"warn"` for advisory, or
@@ -272,4 +348,4 @@ affect it.
 
 LicenseRef Proprietary © 2025-2026 Artur Polishchuk. Free to install and run via the
 published npm package (see [LICENSE](LICENSE) for the exact grant); the source is not
-open-source and is not licensed for copying, modification, or redistribution.
+open-source and is not licensed for copying, modification, or redistribution.

package/cspell.json

@@ -1,13 +1,6 @@
 {
   "version": "0.2",
-  "language": "en,ru,uk,he,fr,es",
-  "import": [
-    "@cspell/dict-ru_ru/cspell-ext.json",
-    "@cspell/dict-uk-ua/cspell-ext.json",
-    "@cspell/dict-he/cspell-ext.json",
-    "@cspell/dict-fr-fr/cspell-ext.json",
-    "@cspell/dict-es-es/cspell-ext.json"
-  ],
+  "language": "en,en-GB",
   "words": [
     "absdiff",
     "abspath",
@@ -467,6 +460,7 @@
     "eficiente",
     "eigen",
     "EIGEN",
+    "EINTEGRITY",
     "EKNFFL",
     "elbert",
     "elementwise",
@@ -1057,6 +1051,7 @@
     "oaep",
     "Obagi",
     "objdetect",
+    "Octo",
     "octocat",
     "ohlc",
     "ohlcv",
@@ -1757,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/cli.js

@@ -2,66 +2,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("./core");
+const commands_1 = require("./core/commands");
+const doctor_1 = require("./core/install/doctor");
 const init_1 = require("./init");
 const utils_1 = require("./utils");
-/** Maps short CLI command names to their registry check names. */
-const COMMAND_TO_CHECK = {
-    lint: 'ESLint',
-    deps: 'Dependencies',
-    dependencies: 'Dependencies',
-    'npm-audit': 'NPM Audit',
-    prettier: 'Prettier',
-    spellcheck: 'Spellcheck',
-    security: 'Security Scan',
-    circular: 'Circular Deps',
-    license: 'License Check',
-    'pr-size': 'PR Size',
-    'pr-title': 'PR Title',
-    outdated: 'Outdated Deps',
-    markdown: 'Markdown',
-    'yaml-lint': 'YAML Lint',
-    symlinks: 'Broken Symlinks',
-    shellcheck: 'ShellCheck',
-    typecheck: 'TypeScript',
-    'diff-smell': 'Diff Smells',
-    'diff-security': 'Diff Security',
-    'workflow-security': 'Workflow Security',
-    'custom-rules': 'Custom Rules',
-    'banned-imports': 'Banned Imports',
-    'license-header': 'License Header',
-    'config-validation': 'Config Validation',
-    'dockerfile-security': 'Dockerfile Security',
-    'case-collision': 'Case Collision',
-    'vuln-scan': 'Vuln Scan',
-    'leftover-debug': 'Leftover Debug',
-    'lockfile-drift': 'Lockfile Drift',
-    'large-files': 'Large Files',
-    'todo-fixme': 'TODO/FIXME',
-    'missing-tests': 'Missing Tests',
-    coverage: 'Coverage',
-    'migration-safety': 'Migration Safety',
-    'sensitive-files': 'Sensitive Files',
-    'pr-body': 'PR Body',
-    duplicate: 'Duplicate Code',
-    commitlint: 'Commitlint',
-    'cpp-format': 'C++ Format',
-    'python-lint': 'Ruff Lint',
-    'python-format': 'Ruff Format',
-    'python-typecheck': 'Python Types',
-    'go-lint': 'Go Vet',
-    'go-format': 'Go Format',
-    'rust-lint': 'Clippy',
-    'rust-format': 'Rustfmt',
-    'csharp-format': 'C# Format',
-    'ruby-lint': 'RuboCop',
-    'php-format': 'PHP CS Fixer',
-};
-/** Commands that run the whole pipeline (or no pipeline at all) and take no siblings. */
-const STANDALONE_COMMANDS = ['init', 'all', 'precommit'];
-/** 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
@@ -77,10 +21,10 @@ const cmd = args[0];
  * diff and print a green summary.
  */
 function rejectUnknownFlags() {
-    const unknown = flags.filter(flag => !FLAGS[flag]);
+    const unknown = flags.filter(flag => !commands_1.FLAGS[flag]);
     if (unknown.length === 0)
         return;
-    const known = Object.entries(FLAGS)
+    const known = Object.entries(commands_1.FLAGS)
         .map(([flag, help]) => `${flag} (${help})`)
         .join(', ');
     utils_1.logger.error(`[cli]: Unknown flag(s) "${unknown.join('", "')}". Available: ${known}`);
@@ -101,6 +45,17 @@ function rejectConflictingScope() {
         utils_1.logger.error(`[cli]: "init" takes no flags, got: ${flags.join(', ')}.`);
         process.exit(1);
     }
+    // `--all` belongs to `install` alone. Accepting it elsewhere would look like a
+    // scope flag and quietly do nothing, which is the failure mode
+    // `rejectUnknownFlags` exists to prevent.
+    if (flags.includes('--all') && cmd !== 'install') {
+        utils_1.logger.error('[cli]: "--all" applies only to "install". Did you mean "--full"?');
+        process.exit(1);
+    }
+    if (flags.includes('--full') && commands_1.TOOLING_COMMANDS.includes(cmd ?? '')) {
+        utils_1.logger.error(`[cli]: "${cmd}" manages tooling and reviews nothing, so "--full" has no meaning.`);
+        process.exit(1);
+    }
 }
 const full = flags.includes('--full');
 /**
@@ -113,7 +68,7 @@ const full = flags.includes('--full');
  * added to the list but not to the branch.
  */
 function rejectExtraArgs() {
-    if (!cmd || !STANDALONE_COMMANDS.includes(cmd) || args.length <= 1)
+    if (!cmd || !commands_1.STANDALONE_COMMANDS.includes(cmd) || args.length <= 1)
         return;
     utils_1.logger.error(`[cli]: "${cmd}" takes no other arguments, got: ${args.slice(1).join(', ')}. Run them as a separate command.`);
     process.exit(1);
@@ -127,6 +82,24 @@ void (async () => {
             await (0, init_1.init)();
             process.exit(0);
         }
+        // Tooling management. These run no checks — they prepare, inspect or clean
+        // up what the checks need, so they never touch the diff or the reporter.
+        if (cmd === 'install') {
+            const results = await (0, doctor_1.installProfiles)(process.cwd(), flags.includes('--all'));
+            const failed = results.filter(r => r.status === 'failed');
+            for (const result of failed) {
+                utils_1.logger.error(`[install]: ❌ ${result.profile}: ${result.reason}`);
+            }
+            process.exit(failed.length > 0 ? 1 : 0);
+        }
+        if (cmd === 'doctor') {
+            await (0, doctor_1.runDoctor)();
+            process.exit(0);
+        }
+        if (cmd === 'cache-prune') {
+            (0, doctor_1.pruneCache)();
+            process.exit(0);
+        }
         // Full run: auto-detect the CI platform (GitHub/GitLab/Bitbucket), post the
         // summary to its PR/MR, and allow formatters to write.
         if (!cmd || cmd === 'all') {
@@ -150,12 +123,12 @@ void (async () => {
         // Every remaining argument is a check name, so `pr-checkmate lint spellcheck`
         // runs both in one pass. Unknown names abort the whole run — a typo must never
         // shrink the requested check set silently.
-        const unknown = args.filter(arg => !COMMAND_TO_CHECK[arg]);
+        const unknown = args.filter(arg => !commands_1.COMMAND_TO_CHECK[arg]);
         if (unknown.length > 0) {
-            utils_1.logger.error(`[cli]: Unknown command(s) "${unknown.join('", "')}". Available: ${STANDALONE_COMMANDS.join(', ')}, ${Object.keys(COMMAND_TO_CHECK).join(', ')}`);
+            utils_1.logger.error(`[cli]: Unknown command(s) "${unknown.join('", "')}". Available: ${commands_1.STANDALONE_COMMANDS.join(', ')}, ${Object.keys(commands_1.COMMAND_TO_CHECK).join(', ')}`);
             process.exit(1);
         }
-        const checkNames = [...new Set(args.map(arg => COMMAND_TO_CHECK[arg]))];
+        const checkNames = [...new Set(args.map(arg => commands_1.COMMAND_TO_CHECK[arg]))];
         const report = await (0, core_1.runChecks)({ only: checkNames, reporter: 'stdout', write: true, full });
         process.exit(report.ok ? 0 : 1);
     }

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
@@ -70,12 +100,30 @@ export declare const DEFAULT_COMMANDS: {
 /**
  * Packages allow-listed for the license check by default.
  *
- * These are pr-checkmate's own bundled cspell dictionaries. Some ship under
- * copyleft licenses (GPL/LGPL), but they are pr-checkmate dependencies — not
- * the consumer's — so clients should never have to allow-list them manually.
+ * These are the optional cspell language dictionaries. Some ship under copyleft
+ * licenses (GPL/LGPL), and a client who installs one to spellcheck their own
+ * language should not have that turn into a licence finding: the dictionary is
+ * data for our check, not code they ship.
  */
 export declare const DEFAULT_ALLOW_PACKAGES: string[];
+/**
+ * Canonical entry point to the PR CheckMate docs. Single source of truth: it is
+ * written into every generated `pr-checkmate.json` (via {@link documentation})
+ * and printed in the "new version available" notice, so the two can never drift.
+ */
+export declare const DOCS_URL = "https://github.com/Mybono/pr_checkmate_public/tree/main/documentation";
+/**
+ * The fully annotated configuration, with every option at its default value.
+ *
+ * A URL rather than a file inside the package on purpose: half the audience runs
+ * pr-checkmate through `npx` on a pipeline and has no `node_modules` at all, so
+ * a path into the installed package is a dead end for them. The release workflow
+ * publishes `src/config/pr-checkmate.template.json` to the public mirror under
+ * this name, which keeps one copy for everyone.
+ */
+export declare const FULL_CONFIG_URL = "https://github.com/Mybono/pr_checkmate_public/blob/main/pr-checkmate.json";
 export declare const documentation: {
+    pr_checkmate: string;
     eslint: string;
     typescriptEslint: string;
     prettier: string;

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.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
@@ -180,8 +215,8 @@ exports.SOURCE_EXTENSIONS = {
     all: ['.ts', '.tsx', '.js', '.jsx', '.json', '.md', '.mdx'],
 };
 exports.DEFAULT_COMMANDS = {
-    'npx pr-checkmate init': 'Update pr-checkmate.json',
-    'npx pr-checkmate all': 'Run all checks (the PR diff in CI, every tracked file locally)',
+    'npx pr-checkmate init': 'Create pr-checkmate.json and the CI workflow (first-run setup)',
+    'npx pr-checkmate all': 'Run all checks over the changes — the PR diff in CI, your branch changes 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',
@@ -197,9 +232,10 @@ exports.DEFAULT_COMMANDS = {
 /**
  * Packages allow-listed for the license check by default.
  *
- * These are pr-checkmate's own bundled cspell dictionaries. Some ship under
- * copyleft licenses (GPL/LGPL), but they are pr-checkmate dependencies — not
- * the consumer's — so clients should never have to allow-list them manually.
+ * These are the optional cspell language dictionaries. Some ship under copyleft
+ * licenses (GPL/LGPL), and a client who installs one to spellcheck their own
+ * language should not have that turn into a licence finding: the dictionary is
+ * data for our check, not code they ship.
  */
 exports.DEFAULT_ALLOW_PACKAGES = [
     '@cspell/dict-es-es',
@@ -208,7 +244,24 @@ exports.DEFAULT_ALLOW_PACKAGES = [
     '@cspell/dict-ru_ru',
     '@cspell/dict-uk-ua',
 ];
+/**
+ * Canonical entry point to the PR CheckMate docs. Single source of truth: it is
+ * written into every generated `pr-checkmate.json` (via {@link documentation})
+ * and printed in the "new version available" notice, so the two can never drift.
+ */
+exports.DOCS_URL = 'https://github.com/Mybono/pr_checkmate_public/tree/main/documentation';
+/**
+ * The fully annotated configuration, with every option at its default value.
+ *
+ * A URL rather than a file inside the package on purpose: half the audience runs
+ * pr-checkmate through `npx` on a pipeline and has no `node_modules` at all, so
+ * a path into the installed package is a dead end for them. The release workflow
+ * publishes `src/config/pr-checkmate.template.json` to the public mirror under
+ * this name, which keeps one copy for everyone.
+ */
+exports.FULL_CONFIG_URL = 'https://github.com/Mybono/pr_checkmate_public/blob/main/pr-checkmate.json';
 exports.documentation = {
+    pr_checkmate: exports.DOCS_URL,
     eslint: 'https://eslint.org/docs/latest/rules/',
     typescriptEslint: 'https://typescript-eslint.io/rules/',
     prettier: 'https://prettier.io/docs/en/options.html',
@@ -227,8 +280,15 @@ exports.KNOWN_CONFIG_KEYS = new Set([
     // core
     'sourcePath',
     'ignoreDirs',
+    'excludePaths',
     'languages',
+    'detect',
+    'install',
     'severity',
+    'severityDefaults',
+    'run',
+    'reporter',
+    'log',
     'customRules',
     '$schema',
     'commands',
@@ -242,6 +302,8 @@ exports.KNOWN_CONFIG_KEYS = new Set([
     'cspell',
     'markdownlint',
     'yamlLint',
+    'shellcheck',
+    'symlinks',
     'typecheck',
     // security
     'security',

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