pr-checkmate 2.0.0 → 2.1.2

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/core/types.d.ts

@@ -164,6 +164,24 @@ export declare const pass: (details?: string) => CheckOutcome;
 export declare const warn: (details: string) => CheckOutcome;
 export declare const fail: (details: string) => CheckOutcome;
 export declare const skip: (details: string) => CheckOutcome;
+/**
+ * Whether this repository is an npm project — the gate for every check that reads
+ * the npm dependency tree (NPM Audit, Dependencies, License Check, Outdated Deps).
+ *
+ * A `package.json` on its own is not the answer, and this is the one predicate
+ * where that matters most: installing pr-checkmate as a devDependency *creates*
+ * that file. Gate on it alone and a Python service gets four rows auditing the
+ * dependency tree of the tool auditing it — `npm audit` over our own transitive
+ * packages, licences of our own `node_modules`, "outdated" versions of tooling
+ * the team never chose. All four are unactionable by construction: nothing in the
+ * repository's own code can change any of them.
+ *
+ * So both halves must hold — a manifest to read, and JavaScript or TypeScript
+ * actually written here. A polyglot repository (a Django backend with a JS
+ * frontend) satisfies both and keeps every check; a Python repository whose only
+ * `package.json` is the one that installed us satisfies neither.
+ */
+export declare function isNpmProject(ctx: CheckContext): boolean;
 /**
  * Identity helper for authoring a `Check` with full type inference and checking.
  * Purely ergonomic — `defineCheck({ ... })` is equivalent to `{ ... } satisfies Check`.

package/dist/core/types.js

@@ -1,6 +1,12 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineCheck = exports.skip = exports.fail = exports.warn = exports.pass = exports.PHASES = void 0;
+exports.isNpmProject = isNpmProject;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 exports.PHASES = ['blocking', 'informational', 'format'];
 /** Outcome constructors — keep check bodies terse. */
 const pass = (details) => ({
@@ -14,6 +20,28 @@ const fail = (details) => ({ status: 'fail', details });
 exports.fail = fail;
 const skip = (details) => ({ status: 'skip', details });
 exports.skip = skip;
+/**
+ * Whether this repository is an npm project — the gate for every check that reads
+ * the npm dependency tree (NPM Audit, Dependencies, License Check, Outdated Deps).
+ *
+ * A `package.json` on its own is not the answer, and this is the one predicate
+ * where that matters most: installing pr-checkmate as a devDependency *creates*
+ * that file. Gate on it alone and a Python service gets four rows auditing the
+ * dependency tree of the tool auditing it — `npm audit` over our own transitive
+ * packages, licences of our own `node_modules`, "outdated" versions of tooling
+ * the team never chose. All four are unactionable by construction: nothing in the
+ * repository's own code can change any of them.
+ *
+ * So both halves must hold — a manifest to read, and JavaScript or TypeScript
+ * actually written here. A polyglot repository (a Django backend with a JS
+ * frontend) satisfies both and keeps every check; a Python repository whose only
+ * `package.json` is the one that installed us satisfies neither.
+ */
+function isNpmProject(ctx) {
+    if (!ctx.languages.includes('javascript') && !ctx.languages.includes('typescript'))
+        return false;
+    return node_fs_1.default.existsSync(node_path_1.default.join(ctx.cwd, 'package.json'));
+}
 /**
  * Identity helper for authoring a `Check` with full type inference and checking.
  * Purely ergonomic — `defineCheck({ ... })` is equivalent to `{ ... } satisfies Check`.

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/dist/utils/detect-language.js

@@ -18,7 +18,17 @@ const logger_1 = require("./logger");
  */
 const MARKER_FILES = {
     typescript: ['tsconfig.json'],
-    javascript: ['package.json'],
+    // Deliberately empty. `package.json` used to sit here, and it is the one marker
+    // this package creates itself: installing pr-checkmate through npm puts a
+    // `package.json` in a repository that may not hold a single line of JavaScript.
+    // A Python service then detected as JavaScript and got the whole JS half of the
+    // report — ESLint, Prettier, NPM Audit, License Check — every row of it about
+    // the file that installed us. `install/profiles.ts` already refused to buy
+    // 152 MB of toolchain off this marker (ticket 064); the checks now refuse to
+    // run off it for the same reason. Real JavaScript is detected by its `.js`,
+    // `.jsx`, `.mjs` and `.cjs` files, and a repository that has none loses
+    // nothing: every JS check it lost would have reported "no files" anyway.
+    javascript: [],
     python: ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'],
     cpp: ['CMakeLists.txt', 'compile_commands.json', 'conanfile.txt', 'conanfile.py'],
     swift: ['Package.swift', 'Package.resolved'],

package/dist/utils/index.d.ts

@@ -6,6 +6,7 @@ export * from './direct-deps';
 export * from './detect-language';
 export * from './glob';
 export * from './update-notifier';
+export * from './package-version';
 export * from './ci';
 export * from './git';
 /**

package/dist/utils/index.js

@@ -28,6 +28,7 @@ __exportStar(require("./direct-deps"), exports);
 __exportStar(require("./detect-language"), exports);
 __exportStar(require("./glob"), exports);
 __exportStar(require("./update-notifier"), exports);
+__exportStar(require("./package-version"), exports);
 __exportStar(require("./ci"), exports);
 __exportStar(require("./git"), exports);
 /**

package/dist/utils/package-version.d.ts

@@ -0,0 +1,4 @@
+/** The version of pr-checkmate that is executing right now. */
+export declare function packageVersion(): string;
+/** The package name that is executing right now — the one to query npm for. */
+export declare function packageName(): string;

package/dist/utils/package-version.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageVersion = packageVersion;
+exports.packageName = packageName;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Our own name and version, read from the manifest that ships inside the package.
+ *
+ * Read from disk rather than baked in at build time so it is the *running* copy
+ * that answers. That distinction is the whole point: a stale global install
+ * (`npm i -g pr-checkmate`) shadows the project's own copy on `PATH`, and a repo
+ * pinned to the latest version can still be checked by a year-old binary without
+ * anything in the log saying so. One client spent a while reading an upgrade
+ * notice for a version they had already installed, because nothing printed which
+ * version was speaking.
+ *
+ * Falls back to placeholders rather than throwing: no caller here is important
+ * enough to fail a run over a manifest it could not read.
+ */
+function readManifest() {
+    try {
+        const manifest = node_path_1.default.resolve(__dirname, '../..', 'package.json');
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf-8'));
+        return { name: parsed.name ?? 'pr-checkmate', version: parsed.version ?? '0.0.0' };
+    }
+    catch {
+        return { name: 'pr-checkmate', version: '0.0.0' };
+    }
+}
+/** The version of pr-checkmate that is executing right now. */
+function packageVersion() {
+    return readManifest().version;
+}
+/** The package name that is executing right now — the one to query npm for. */
+function packageName() {
+    return readManifest().name;
+}

package/dist/utils/update-notifier.js

@@ -1,16 +1,12 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMajorUpgrade = isMajorUpgrade;
 exports.getUpdateNotice = getUpdateNotice;
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
 // Imported from the module rather than the `../config` barrel on purpose:
 // `config/index.ts` imports `../utils`, so going through the barrel would make
 // utils ⇄ config circular. `constants.ts` itself pulls in nothing from utils.
 const constants_1 = require("../config/constants");
+const package_version_1 = require("./package-version");
 // Same widths as the run summary in `reporters.ts`, so the two boxes line up
 // when both are printed at the end of a run.
 const NOTICE_BORDER = '═'.repeat(63);
@@ -72,8 +68,10 @@ async function getUpdateNotice(timeoutMs = 2500) {
     if (process.env.PR_CHECKMATE_NO_UPDATE_CHECK)
         return null;
     try {
-        const pkgPath = node_path_1.default.resolve(__dirname, '../..', 'package.json');
-        const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf-8'));
+        // The *running* copy's identity, not the project's declared dependency. A
+        // stale global install shadows the local one on `PATH`, and it is the stale
+        // copy that must own the notice it prints.
+        const pkg = { name: (0, package_version_1.packageName)(), version: (0, package_version_1.packageVersion)() };
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         let latest;

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