pr-checkmate 1.23.23 → 2.0.0

package/README.md

@@ -13,7 +13,7 @@
 
 > PR CheckMate is a security-first PR gate: secret scanning, dependency
 > vulnerability checks, and a signed SBOM + independent VirusTotal scan on
-> every release — plus 51 code-quality checks across 11 languages bundled in
+> every release — plus 53 code-quality checks across 12 languages bundled in
 > for free, running in CI on every pull request. The bundled languages need no
 > per-language toolchain setup.
 
@@ -82,6 +82,7 @@ tool installed; the check skips gracefully when the tool is absent.
 | C# | `dotnet format` | .NET SDK on the runner |
 | Ruby | RuboCop | `rubocop` on the runner |
 | PHP | PHP-CS-Fixer | `php-cs-fixer` on the runner |
+| Shell | ShellCheck | `shellcheck` on the runner |
 
 Secret scanning (gitleaks) and the universal git-diff checks are bundled and run for
 every language.
@@ -152,8 +153,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
@@ -162,31 +164,68 @@ 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
 `shivammathur/setup-php` (tools: `php-cs-fixer`), Kotlin by fetching the `ktlint`
-binary. Swift's `swiftlint` is pre-installed on `macos-latest`. Anything missing is
+binary. Swift's `swiftlint` is pre-installed on `macos-latest`, and `shellcheck` is
+pre-installed on `ubuntu-latest` — neither needs a setup step. Anything missing is
 skipped, not failed.
 
 ## Checks
 
-51 checks, grouped by category and run in parallel within each phase:
+53 checks, grouped by category and run in parallel within each phase:
 
 - Universal git-diff (18) — language-agnostic and bundled: merge-conflict markers,
   secret scan, diff security (JS/TS/Python/Go/Kotlin), diff smells, GitHub Actions and
@@ -196,9 +235,10 @@ skipped, not failed.
 - Dependencies (7) — unused/missing, circular, outdated, license compliance, npm audit,
   a cross-language vuln scan (osv-scanner, opt-in), and a direct-dependency vuln scan
   (grype, on by default).
-- Quality (6) — duplicate code, dead code, multi-language spellcheck, markdown lint, YAML lint, config validation.
+- Quality (7) — duplicate code, dead code, multi-language spellcheck, markdown lint,
+  YAML lint, broken symlinks, config validation.
 - PR hygiene (4) — size, title, body, and commit-message convention.
-- Per-language (16) — lint, format, and type-check for the languages listed above.
+- Per-language (17) — lint, format, and type-check for the languages listed above.
 
 Each check has its own page in the
 [per-check reference](https://github.com/Mybono/pr_checkmate_public/blob/main/documentation/checks/INDEX.md),
@@ -206,8 +246,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

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",

package/dist/cli.js

@@ -2,64 +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',
-    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
@@ -75,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}`);
@@ -99,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');
 /**
@@ -111,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);
@@ -125,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') {
@@ -148,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

@@ -70,12 +70,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.DUPLICATE_IGNORE_DEFAULTS = 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
@@ -180,8 +180,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 +197,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 +209,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 +245,15 @@ exports.KNOWN_CONFIG_KEYS = new Set([
     // core
     'sourcePath',
     'ignoreDirs',
+    'excludePaths',
     'languages',
+    'detect',
+    'install',
     'severity',
+    'severityDefaults',
+    'run',
+    'reporter',
+    'log',
     'customRules',
     '$schema',
     'commands',
@@ -242,6 +267,8 @@ exports.KNOWN_CONFIG_KEYS = new Set([
     'cspell',
     'markdownlint',
     'yamlLint',
+    'shellcheck',
+    'symlinks',
     'typecheck',
     // security
     'security',