pr-checkmate 3.3.0 → 4.0.0

package/dist/cjs/core/checks/security/workflow-security.js

@@ -55,6 +55,39 @@ exports.WORKFLOW_PATTERNS = [
         label: 'pull_request_target trigger (runs with repo secrets on untrusted PRs)',
         severity: 'warn',
     },
+    {
+        // The second half of the "pwn request": `pull_request_target` alone is harmless,
+        // checking out the PR's own code under it hands the attacker a privileged
+        // runner. One line cannot see the trigger, so this stays a warning.
+        pattern: /^\+(?!\+)\s*(?:ref|repository):\s*['"]?\$\{\{\s*github\.event\.pull_request\.head\.(?:sha|ref|repo\.full_name)\s*\}\}/,
+        label: 'checkout of the PR head (code execution with secrets under pull_request_target)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*permissions:\s*write-all\b/,
+        label: 'permissions: write-all (grant the token only the scopes the job needs)',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+)\s*secrets:\s*inherit\b/,
+        label: 'secrets: inherit (hands every repository secret to the called workflow)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*ACTIONS_ALLOW_UNSECURE_COMMANDS:\s*['"]?true\b/i,
+        label: 'ACTIONS_ALLOW_UNSECURE_COMMANDS (re-enables the deprecated set-env / add-path injection vector)',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:curl|wget)\b[^|]*\|\s*(?:sudo\s+)?(?:sh|bash)\b/i,
+        label: 'piping a download straight to a shell (curl/wget … | sh)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*runs-on:\s*\[?\s*['"]?self-hosted\b/,
+        label: 'self-hosted runner (a PR from a fork can run code on your own infrastructure)',
+        severity: 'warn',
+    },
 ];
 exports.workflowSecurityCheck = {
     name: 'Workflow Security',

package/dist/cjs/core/commands.d.ts

@@ -22,6 +22,12 @@ export declare const COMMAND_TO_CHECK: Record<string, string>;
  * and not a reading of our source.
  */
 export declare const TOOLING_COMMANDS: readonly string[];
+/**
+ * Commands that serve AI agents rather than review a diff. They share the CLI's
+ * entry point and nothing else: no scope flags apply, and `mcp` in particular owns
+ * stdout for the protocol, so none of them may be confused with a check name.
+ */
+export declare const AGENT_COMMANDS: readonly string[];
 export declare const STANDALONE_COMMANDS: readonly string[];
 /** Flags accepted anywhere on the command line, with what each one means. */
 export declare const FLAGS: Record<string, string>;

package/dist/cjs/core/commands.js

@@ -12,7 +12,7 @@
  * reports success having verified nothing at all.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FLAGS = exports.STANDALONE_COMMANDS = exports.TOOLING_COMMANDS = exports.COMMAND_TO_CHECK = void 0;
+exports.FLAGS = exports.STANDALONE_COMMANDS = exports.AGENT_COMMANDS = exports.TOOLING_COMMANDS = exports.COMMAND_TO_CHECK = void 0;
 /** Maps short CLI command names to their registry check names. */
 exports.COMMAND_TO_CHECK = {
     // Every check that can fail a run is reachable on its own, so "why does this
@@ -44,6 +44,7 @@ exports.COMMAND_TO_CHECK = {
     'license-header': 'License Header',
     'config-validation': 'Config Validation',
     'dockerfile-security': 'Dockerfile Security',
+    'agent-instructions': 'Agent Instructions',
     'case-collision': 'Case Collision',
     'vuln-scan': 'Vuln Scan',
     'leftover-debug': 'Leftover Debug',
@@ -79,14 +80,23 @@ exports.COMMAND_TO_CHECK = {
  * and not a reading of our source.
  */
 exports.TOOLING_COMMANDS = ['install', 'doctor', 'cache-prune'];
+/**
+ * Commands that serve AI agents rather than review a diff. They share the CLI's
+ * entry point and nothing else: no scope flags apply, and `mcp` in particular owns
+ * stdout for the protocol, so none of them may be confused with a check name.
+ */
+exports.AGENT_COMMANDS = ['mcp', 'hook', 'agent-setup'];
 exports.STANDALONE_COMMANDS = [
     'init',
     'all',
     'precommit',
     ...exports.TOOLING_COMMANDS,
+    ...exports.AGENT_COMMANDS,
 ];
 /** Flags accepted anywhere on the command line, with what each one means. */
 exports.FLAGS = {
     '--full': 'review every tracked file instead of the diff (the default outside CI)',
     '--all': 'with "install": fetch every profile, not only the ones this repository needs',
+    '--sarif': 'write findings as SARIF 2.1.0 to pr-checkmate.sarif (check-running commands only)',
+    '--no-hook': 'with "agent-setup": skip the git-commit gate for Claude Code',
 };

package/dist/cjs/core/finding-store.d.ts

@@ -0,0 +1,16 @@
+import type { Finding } from '../utils/result-collector.js';
+/** Run `work` collecting every finding filed inside it. */
+export declare function collectFindings<T>(work: () => Promise<T>): Promise<{
+    result: T;
+    findings: Finding[];
+}>;
+/** A scanner saw `sample` under `label` at `file:line`. Claimed later by {@link fileFindings}. */
+export declare function noteLocation(label: string, sample: string, file: string, line: number): void;
+/**
+ * Turn the findings that survived filtering into located ones. Each sample claims
+ * the oldest location noted for it, so the same line appearing twice resolves to
+ * two places rather than one place twice.
+ */
+export declare function fileFindings(bucket: Record<string, string[]>, severity: Finding['severity']): void;
+/** File a finding directly, for scanners that already know exactly where it is. */
+export declare function addFinding(finding: Finding): void;

package/dist/cjs/core/finding-store.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectFindings = collectFindings;
+exports.noteLocation = noteLocation;
+exports.fileFindings = fileFindings;
+exports.addFinding = addFinding;
+/**
+ * Where a finding was, carried from the scanner that saw it to the report that
+ * names it.
+ *
+ * Scanners reduce what they find to strings in a bucket — `"debugger statement" →
+ * ["debugger;"]` — because the report only ever needed a count and a sample. An
+ * agent needs more: which file, which line. Rewriting forty checks to carry that
+ * would have been forty chances to disagree with each other, so the location is
+ * noted once, where the diff is walked, and attached once, where the buckets are
+ * filed.
+ *
+ * It is attached at filing time, not scan time, on purpose. `ignore` and
+ * `severityOverrides` run in between, and a finding the client has silenced must
+ * not reach an agent that would then dutifully "fix" it.
+ *
+ * The store is an `AsyncLocalStorage` scope per check. Checks of one phase run in
+ * parallel, so a module-level list would mix their findings; a scope cannot. Code
+ * running outside `collectFindings` (the library API, unit tests) finds no store
+ * and every call here does nothing.
+ */
+const node_async_hooks_1 = require("node:async_hooks");
+/** More than this and the list is noise to a reader and a cost to an agent. */
+const MAX_FINDINGS_PER_CHECK = 200;
+const scope = new node_async_hooks_1.AsyncLocalStorage();
+const keyOf = (label, sample) => `${label}\u0000${sample}`;
+/** Run `work` collecting every finding filed inside it. */
+async function collectFindings(work) {
+    const store = { found: [], pending: new Map() };
+    const result = await scope.run(store, work);
+    return { result, findings: store.found };
+}
+/** A scanner saw `sample` under `label` at `file:line`. Claimed later by {@link fileFindings}. */
+function noteLocation(label, sample, file, line) {
+    const store = scope.getStore();
+    if (!store)
+        return;
+    const key = keyOf(label, sample);
+    const queue = store.pending.get(key) ?? [];
+    queue.push({ file, line });
+    store.pending.set(key, queue);
+}
+/**
+ * Turn the findings that survived filtering into located ones. Each sample claims
+ * the oldest location noted for it, so the same line appearing twice resolves to
+ * two places rather than one place twice.
+ */
+function fileFindings(bucket, severity) {
+    const store = scope.getStore();
+    if (!store)
+        return;
+    for (const [label, samples] of Object.entries(bucket)) {
+        for (const sample of samples) {
+            if (store.found.length >= MAX_FINDINGS_PER_CHECK)
+                return;
+            const where = store.pending.get(keyOf(label, sample))?.shift();
+            if (!where)
+                continue;
+            store.found.push({ ...where, rule: label, snippet: sample, severity });
+        }
+    }
+}
+/** File a finding directly, for scanners that already know exactly where it is. */
+function addFinding(finding) {
+    const store = scope.getStore();
+    if (store && store.found.length < MAX_FINDINGS_PER_CHECK)
+        store.found.push(finding);
+}

package/dist/cjs/core/registry.js

@@ -41,6 +41,7 @@ const package_size_js_1 = require("./checks/quality/package-size.js");
 const spellcheck_js_1 = require("./checks/quality/spellcheck.js");
 const symlinks_js_1 = require("./checks/quality/symlinks.js");
 const yaml_lint_js_1 = require("./checks/quality/yaml-lint.js");
+const agent_instructions_js_1 = require("./checks/security/agent-instructions.js");
 const diff_security_js_1 = require("./checks/security/diff-security.js");
 const dockerfile_security_js_1 = require("./checks/security/dockerfile-security.js");
 const migration_safety_js_1 = require("./checks/security/migration-safety.js");
@@ -66,6 +67,7 @@ exports.REGISTRY = [
     diff_security_js_1.diffSecurityCheck,
     workflow_security_js_1.workflowSecurityCheck,
     dockerfile_security_js_1.dockerfileSecurityCheck,
+    agent_instructions_js_1.agentInstructionsCheck,
     case_collision_js_1.caseCollisionCheck,
     vuln_scan_js_1.vulnScanCheck,
     grype_scan_js_1.grypeScanCheck,

package/dist/cjs/core/reporters.js

@@ -6,6 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMarkdownReport = buildMarkdownReport;
 exports.report = report;
 const node_fs_1 = __importDefault(require("node:fs"));
+const registration_js_1 = require("../agent/registration.js");
+const constants_js_1 = require("../config/constants.js");
+const settings_js_1 = require("../mcp/settings.js");
 const http_js_1 = require("../utils/http.js");
 const index_js_1 = require("../utils/index.js");
 const package_version_js_1 = require("../utils/package-version.js");
@@ -107,6 +110,12 @@ function printStdout(report, cfg) {
     if (cfg.include?.docsLink !== false) {
         // The docs cover every check and config key.
         index_js_1.logger.print(' DOCUMENTATION: https://pr-checkmate-docs.pages.dev/');
+        // Said once per project, and never in CI, where nobody is there to act on it.
+        if (!process.env.CI &&
+            (0, settings_js_1.readMcpSettings)(process.cwd()).enabled &&
+            !(0, registration_js_1.isMcpRegistered)(process.cwd())) {
+            index_js_1.logger.print(` AI AGENT: ${constants_js_1.AGENT_SETUP_COMMAND} — your agent then writes code that passes.`);
+        }
     }
 }
 /** Network settings shared by every platform call. */

package/dist/cjs/core/run-checks.js

@@ -9,6 +9,7 @@ const pool_js_1 = require("../utils/pool.js");
 const resolve_bin_js_1 = require("../utils/resolve-bin.js");
 const result_collector_js_1 = require("../utils/result-collector.js");
 const context_js_1 = require("./context.js");
+const finding_store_js_1 = require("./finding-store.js");
 const prepare_js_1 = require("./install/prepare.js");
 const registry_js_1 = require("./registry.js");
 const reporters_js_1 = require("./reporters.js");
@@ -174,15 +175,24 @@ async function runOne(check, ctx, collector, heavy, tooling) {
         }
         const started = Date.now();
         const timeoutMs = ctx.config.run?.checkTimeoutMs ?? 300000;
-        const execute = () => (0, pool_js_1.withTimeout)(check.run(ctx), timeoutMs, () => {
-            index_js_1.logger.warn(`[runChecks]: ⏱️ ${check.name} exceeded ${timeoutMs}ms`);
-            return { status: 'warn', details: `timed out after ${timeoutMs}ms` };
-        });
+        // Locations noted while this check runs, collected per check: the phase runs
+        // its checks in parallel, so a shared list would mix their findings.
+        let located = [];
+        const execute = async () => {
+            const { result, findings } = await (0, finding_store_js_1.collectFindings)(() => (0, pool_js_1.withTimeout)(check.run(ctx), timeoutMs, () => {
+                index_js_1.logger.warn(`[runChecks]: ⏱️ ${check.name} exceeded ${timeoutMs}ms`);
+                return { status: 'warn', details: `timed out after ${timeoutMs}ms` };
+            }));
+            located = findings;
+            return result;
+        };
         const outcome = check.weight === 'heavy' ? await heavy.run(execute) : await execute();
         if (ctx.config.run?.timings) {
             index_js_1.logger.info(`[runChecks]: ${check.name} took ${Date.now() - started}ms`);
         }
-        collector.register(check.name, applySeverity(check.name, outcome.status, ctx), outcome.details);
+        collector.register(check.name, applySeverity(check.name, outcome.status, ctx), outcome.details, 
+        // A clean result has nothing to locate, even when `failOn: never` filed some.
+        outcome.status === 'pass' ? undefined : (outcome.findings ?? located));
     }
     catch (err) {
         // An unexpected throw in a blocking check fails the run; in informational/format

package/dist/cjs/core/sarif.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A report as SARIF 2.1.0 — the format GitHub code scanning, VS Code and most
+ * security dashboards read, so a finding shows up inline on the line it names
+ * instead of only in a summary table.
+ *
+ * Only what a consumer can use is written. A failed or warned check that located
+ * its problems yields one result per location; one that could not yields a single
+ * result with no location, because a finding with nowhere to point is still a
+ * finding. Passes and skips are not results.
+ */
+import type { CheckReport } from './types.js';
+/** Convert a report to a SARIF log object, ready for `JSON.stringify`. */
+export declare function toSarif(report: CheckReport, toolVersion: string): Record<string, unknown>;

package/dist/cjs/core/sarif.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSarif = toSarif;
+const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
+const ruleIdFor = (check, rule) => (rule ? `${check}/${rule}` : check);
+function locatedResult(check, f) {
+    return {
+        ruleId: ruleIdFor(check.name, f.rule),
+        level: f.severity === 'error' ? 'error' : 'warning',
+        message: { text: f.snippet ? `${f.rule}: ${f.snippet}` : f.rule },
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: { uri: f.file },
+                    ...(f.line !== undefined && { region: { startLine: f.line } }),
+                },
+            },
+        ],
+    };
+}
+function summaryResult(check) {
+    return {
+        ruleId: ruleIdFor(check.name),
+        level: check.status === 'fail' ? 'error' : 'warning',
+        message: { text: check.details ?? `${check.name} reported a problem` },
+    };
+}
+/** Convert a report to a SARIF log object, ready for `JSON.stringify`. */
+function toSarif(report, toolVersion) {
+    const results = [];
+    const rules = new Map();
+    for (const check of report.results) {
+        if (check.status !== 'fail' && check.status !== 'warn')
+            continue;
+        const found = check.findings && check.findings.length > 0
+            ? check.findings.map(f => locatedResult(check, f))
+            : [summaryResult(check)];
+        for (const r of found) {
+            results.push(r);
+            rules.set(r.ruleId, { id: r.ruleId, name: r.ruleId });
+        }
+    }
+    return {
+        $schema: SARIF_SCHEMA,
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'pr-checkmate',
+                        version: toolVersion,
+                        informationUri: 'https://www.npmjs.com/package/pr-checkmate',
+                        rules: [...rules.values()],
+                    },
+                },
+                results,
+            },
+        ],
+    };
+}

package/dist/cjs/core/types.d.ts

@@ -1,7 +1,7 @@
 import type { PRCheckMateConfig, ReporterConfig } from '../interfaces/index.js';
 import type { Language, LanguageUsage } from '../utils/detect-language.js';
-import type { CheckResult, CheckStatus } from '../utils/result-collector.js';
-export type { CheckResult, CheckStatus, Language, LanguageUsage };
+import type { CheckResult, CheckStatus, Finding } from '../utils/result-collector.js';
+export type { CheckResult, CheckStatus, Finding, Language, LanguageUsage };
 /**
  * Execution phases, run strictly in order. Within a phase checks run in parallel.
  * `format` runs last because formatters (prettier) may write files.
@@ -67,6 +67,11 @@ export interface CheckContext {
 export interface CheckOutcome {
     status: CheckStatus;
     details?: string;
+    /**
+     * Where the problems are. Left to the orchestrator for pattern-based checks,
+     * which note locations as they scan; a check that knows better may set it.
+     */
+    findings?: Finding[];
 }
 /**
  * A single quality gate. `applies` decides relevance (language/marker gating);

package/dist/cjs/index.d.ts

@@ -4,8 +4,9 @@
  * @module pr-checkmate
  */
 export { runChecks, buildContext, REGISTRY } from './core/index.js';
+export { toSarif } from './core/sarif.js';
 export { pass, warn, fail, skip, defineCheck } from './core/index.js';
-export type { Check, CheckContext, CheckOutcome, CheckReport, CheckResult, CheckStatus, Language, Phase, ReporterFn, ReporterKind, RunOptions, } from './core/index.js';
+export type { Check, CheckContext, CheckOutcome, CheckReport, CheckResult, CheckStatus, Finding, Language, Phase, ReporterFn, ReporterKind, RunOptions, } from './core/index.js';
 export { getSourcePath, getSourcePaths, getIgnoredDirs, getPackageConfigPath, hasLocalConfig, } from './config/index.js';
 export type { PRCheckMateConfig } from './interfaces/index.js';
 export { Logger } from './utils/logger.js';

package/dist/cjs/index.js

@@ -5,13 +5,16 @@
  * @module pr-checkmate
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = exports.hasLocalConfig = exports.getPackageConfigPath = exports.getIgnoredDirs = exports.getSourcePaths = exports.getSourcePath = exports.defineCheck = exports.skip = exports.fail = exports.warn = exports.pass = exports.REGISTRY = exports.buildContext = exports.runChecks = void 0;
+exports.Logger = exports.hasLocalConfig = exports.getPackageConfigPath = exports.getIgnoredDirs = exports.getSourcePaths = exports.getSourcePath = exports.defineCheck = exports.skip = exports.fail = exports.warn = exports.pass = exports.toSarif = exports.REGISTRY = exports.buildContext = exports.runChecks = void 0;
 // Primary programmatic API: run checks and receive a structured report.
 // Never throws for violations, never calls process.exit — the caller decides.
 var index_js_1 = require("./core/index.js");
 Object.defineProperty(exports, "runChecks", { enumerable: true, get: function () { return index_js_1.runChecks; } });
 Object.defineProperty(exports, "buildContext", { enumerable: true, get: function () { return index_js_1.buildContext; } });
 Object.defineProperty(exports, "REGISTRY", { enumerable: true, get: function () { return index_js_1.REGISTRY; } });
+// SARIF 2.1.0 export of a report, for code-scanning dashboards and editors.
+var sarif_js_1 = require("./core/sarif.js");
+Object.defineProperty(exports, "toSarif", { enumerable: true, get: function () { return sarif_js_1.toSarif; } });
 // Authoring helpers for consumers writing their own checks (plugins).
 var index_js_2 = require("./core/index.js");
 Object.defineProperty(exports, "pass", { enumerable: true, get: function () { return index_js_2.pass; } });

package/dist/cjs/init.js

@@ -419,6 +419,16 @@ async function createConfig(root) {
  * update notice insisted `init` must not be skipped after an upgrade. Defaults
  * now apply when the config is loaded, so there is nothing to top up.
  */
+/** Adds the agent-setup command to a client's `commands` block when it is missing; nothing else in it is touched. */
+function withAgentCommand(commands) {
+    if (commands === undefined)
+        return undefined;
+    if (typeof commands !== 'object' || commands === null || Array.isArray(commands))
+        return commands;
+    if (index_js_1.AGENT_SETUP_COMMAND in commands)
+        return commands;
+    return { ...commands, [index_js_1.AGENT_SETUP_COMMAND]: index_js_1.DEFAULT_COMMANDS[index_js_1.AGENT_SETUP_COMMAND] };
+}
 async function updateConfig(root) {
     index_js_2.logger.info('[init]: pr-checkmate.json already exists — updating it.');
     try {
@@ -449,6 +459,7 @@ async function updateConfig(root) {
             // when missing; a client's own block is never touched.
             grypeScan: json.grypeScan ?? structuredClone(GRYPE_SCAN_SEED),
             ...templateExtras({ ...json, grypeScan: true }),
+            commands: withAgentCommand(json.commands),
             languages,
         };
         fs_1.default.writeFileSync(CONFIG_FILE, `${JSON.stringify(updated, null, 2)}\n`);

package/dist/cjs/interfaces/index.d.ts

@@ -317,6 +317,18 @@ export interface PRCheckMateConfig {
         severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
         ignorePaths?: string[];
     };
+    mcp?: {
+        enabled?: boolean;
+        disabledTools?: string[];
+        readOnly?: boolean;
+    };
+    agentInstructions?: {
+        enabled?: boolean;
+        ignore?: string[];
+        failOn?: 'error' | 'warn' | 'never';
+        severityOverrides?: Record<string, 'error' | 'warn' | 'off'>;
+        ignorePaths?: string[];
+    };
     dockerfileSecurity?: {
         enabled?: boolean;
         ignore?: string[];

package/dist/cjs/mcp/config-tools.d.ts

@@ -0,0 +1,30 @@
+import type { ToolResult } from './protocol.js';
+type Json = Record<string, unknown>;
+/** What a key means, from the schema that ships with the package. */
+export declare function explainConfig(key?: string): ToolResult;
+/** Problems in a proposed config, phrased so the agent can correct them. Empty means it is acceptable. */
+export declare function validateConfig(config: Json, cwd: string): string[];
+/** Validate and write `config` into the repository's `pr-checkmate.json`. */
+export declare function writeConfig(cwd: string, config: unknown, overwrite: boolean): ToolResult;
+interface Suggestion {
+    proposed: Json;
+    notes: string[];
+}
+/**
+ * Look at the repository and propose a config.
+ *
+ * The baseline is a whole-repository run of the fast checks. A check that already
+ * fails is proposed as `warn`: the gate is on from the first commit, the existing
+ * debt is visible, and nothing new can slip in unnoticed — then each check is
+ * promoted back to blocking as it reaches zero. Proposing `error` everywhere would
+ * make the first CI run red for reasons nobody on the pull request caused, and the
+ * usual response to that is to switch the whole tool off.
+ */
+export declare function suggestConfig(cwd: string): Promise<Suggestion & {
+    languages: string[];
+}>;
+/** `suggest_config` as the text an agent reads. */
+export declare function formatSuggestion(s: Suggestion & {
+    languages: string[];
+}): ToolResult;
+export {};