pr-checkmate 3.3.0 → 4.0.0

package/dist/esm/cli.js

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { evaluateHook } from './agent/hook.js';
+import { reportSetup, setupAgent } from './agent/setup.js';
 import { loadProjectConfig } from './config/loader.js';
-import { COMMAND_TO_CHECK, FLAGS, STANDALONE_COMMANDS, TOOLING_COMMANDS } from './core/commands.js';
+import { AGENT_COMMANDS, COMMAND_TO_CHECK, FLAGS, STANDALONE_COMMANDS, TOOLING_COMMANDS, } from './core/commands.js';
 import { runChecks } from './core/index.js';
 import { installProfiles, pruneCache, runDoctor } from './core/install/doctor.js';
 import { ensureGrypeDb } from './core/install/grype-db.js';
+import { toSarif } from './core/sarif.js';
 import { init } from './init.js';
+import { serve } from './mcp/serve.js';
+import { createServerDefinition } from './mcp/tools.js';
+import { isolateInheritedStdio } from './utils/execa.js';
 import { getUpdateNotice, logger } from './utils/index.js';
+import { packageVersion } from './utils/package-version.js';
 const argv = process.argv.slice(2);
 /**
  * Flags are separated from positional arguments so they compose with every command
@@ -52,6 +61,28 @@ function rejectConflictingScope() {
         logger.error('[cli]: "--all" applies only to "install". Did you mean "--full"?');
         process.exit(1);
     }
+    // `mcp` speaks a protocol on stdout and `hook` is invoked by a harness with a
+    // fixed payload: neither has anything to configure from the command line, and a
+    // flag that quietly did nothing would look like it had.
+    if ((cmd === 'mcp' || cmd === 'hook') && flags.length > 0) {
+        logger.error(`[cli]: "${cmd}" takes no flags, got: ${flags.join(', ')}.`);
+        process.exit(1);
+    }
+    // Only a command that runs checks has findings to export; `all`, `precommit` and a
+    // named check do, every other standalone command does not.
+    const runsChecks = !cmd || cmd === 'all' || cmd === 'precommit' || !STANDALONE_COMMANDS.includes(cmd);
+    if (flags.includes('--sarif') && !runsChecks) {
+        logger.error('[cli]: "--sarif" applies only to commands that run checks.');
+        process.exit(1);
+    }
+    if (flags.includes('--no-hook') && cmd !== 'agent-setup') {
+        logger.error('[cli]: "--no-hook" applies only to "agent-setup".');
+        process.exit(1);
+    }
+    if (flags.includes('--full') && AGENT_COMMANDS.includes(cmd ?? '')) {
+        logger.error(`[cli]: "${cmd}" reviews nothing on its own, so "--full" has no meaning.`);
+        process.exit(1);
+    }
     if (flags.includes('--full') && TOOLING_COMMANDS.includes(cmd ?? '')) {
         logger.error(`[cli]: "${cmd}" manages tooling and reviews nothing, so "--full" has no meaning.`);
         process.exit(1);
@@ -73,6 +104,55 @@ function rejectExtraArgs() {
     logger.error(`[cli]: "${cmd}" takes no other arguments, got: ${args.slice(1).join(', ')}. Run them as a separate command.`);
     process.exit(1);
 }
+/**
+ * Write the report as SARIF when `--sarif` was passed. Written before the exit code
+ * is decided, so a failing run still leaves the file a dashboard needs to show why.
+ */
+function writeSarifIfRequested(report) {
+    if (!flags.includes('--sarif'))
+        return;
+    const file = path.resolve(process.cwd(), 'pr-checkmate.sarif');
+    fs.writeFileSync(file, `${JSON.stringify(toSarif(report, packageVersion()), null, 2)}\n`);
+    logger.info(`[sarif]: wrote ${file}`);
+}
+/** Everything the harness wrote to stdin, as text; empty when stdin is closed or a terminal. */
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/**
+ * The commands that serve AI agents. Returns whether `cmd` was one of them (and has
+ * therefore already exited); kept out of the main dispatcher so that one stays
+ * readable as the list of commands grows.
+ *
+ * `mcp` must stay ahead of anything that could print: from here until stdin closes,
+ * stdout carries protocol messages and nothing else.
+ */
+async function runAgentCommand() {
+    if (cmd === 'mcp') {
+        await serve(createServerDefinition());
+        process.exit(0);
+    }
+    if (cmd === 'hook') {
+        // Discarded rather than shown: the harness reads stdout and stderr of a hook
+        // as instructions to the model, so only the verdict may reach either.
+        isolateInheritedStdio('discard');
+        logger.setSink({ out: () => undefined, err: () => undefined });
+        const verdict = await evaluateHook(await readStdin(), process.cwd());
+        if (verdict.stderr)
+            process.stderr.write(`${verdict.stderr}\n`);
+        process.exit(verdict.exitCode);
+    }
+    if (cmd === 'agent-setup') {
+        reportSetup(setupAgent(process.cwd(), { hook: !flags.includes('--no-hook') }));
+        process.exit(0);
+    }
+    return false;
+}
 void (async () => {
     try {
         rejectUnknownFlags();
@@ -82,6 +162,8 @@ void (async () => {
             await init();
             process.exit(0);
         }
+        if (await runAgentCommand())
+            return;
         // 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') {
@@ -123,12 +205,14 @@ void (async () => {
                 logger.info('');
                 notice.forEach(line => logger.info(line));
             }
+            writeSarifIfRequested(report);
             process.exit(report.ok ? 0 : 1);
         }
         // Local pre-commit: check the staged changes (index vs HEAD), print to
         // stdout, never modify files. Exits non-zero on failure to block the commit.
         if (cmd === 'precommit') {
             const report = await runChecks({ staged: true, reporter: 'stdout', write: false });
+            writeSarifIfRequested(report);
             process.exit(report.ok ? 0 : 1);
         }
         // Every remaining argument is a check name, so `pr-checkmate lint spellcheck`
@@ -141,6 +225,7 @@ void (async () => {
         }
         const checkNames = [...new Set(args.map(arg => COMMAND_TO_CHECK[arg]))];
         const report = await runChecks({ only: checkNames, reporter: 'stdout', write: true, full });
+        writeSarifIfRequested(report);
         process.exit(report.ok ? 0 : 1);
     }
     catch (err) {

package/dist/esm/config/constants.d.ts

@@ -95,6 +95,7 @@ export declare const SOURCE_EXTENSIONS: {
     json: string[];
     all: string[];
 };
+export declare const AGENT_SETUP_COMMAND = "npx pr-checkmate agent-setup";
 export declare const DEFAULT_COMMANDS: {
     'npx pr-checkmate init': string;
     'npx pr-checkmate all': string;
@@ -109,6 +110,7 @@ export declare const DEFAULT_COMMANDS: {
     'npx pr-checkmate diff-smell': string;
     'npx pr-checkmate pr-body': string;
     'npx pr-checkmate duplicate': string;
+    "npx pr-checkmate agent-setup": string;
 };
 /**
  * Packages allow-listed for the license check by default.

package/dist/esm/config/constants.js

@@ -225,6 +225,7 @@ export const SOURCE_EXTENSIONS = {
     json: ['.json'],
     all: ['.ts', '.tsx', '.js', '.jsx', '.json', '.md', '.mdx'],
 };
+export const AGENT_SETUP_COMMAND = 'npx pr-checkmate agent-setup';
 export const DEFAULT_COMMANDS = {
     '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',
@@ -239,6 +240,7 @@ export const DEFAULT_COMMANDS = {
     'npx pr-checkmate diff-smell': 'Scan git diff for code smells',
     'npx pr-checkmate pr-body': 'Validate PR description',
     'npx pr-checkmate duplicate': 'Detect duplicate code blocks (jscpd)',
+    [AGENT_SETUP_COMMAND]: 'Connect your AI agent: MCP server, rules for it and edit hooks (writes .mcp.json)',
 };
 /**
  * Packages allow-listed for the license check by default.
@@ -320,6 +322,8 @@ export const KNOWN_CONFIG_KEYS = new Set([
     'diffSecurity',
     'workflowSecurity',
     'dockerfileSecurity',
+    'agentInstructions',
+    'mcp',
     'sensitiveFileGuard',
     'migrationSafety',
     // dependencies

package/dist/esm/config/pr-checkmate.template.json

@@ -97,6 +97,16 @@
     "enabled": true,
     "ignore": []
   },
+  "agentInstructions": {
+    "enabled": true,
+    "ignore": []
+  },
+  "//mcp": "What the MCP server offers an AI agent here. 'enabled': false turns it off; 'disabledTools' hides tools by name; 'readOnly' hides the ones that write files. Applies from the agent's next request.",
+  "mcp": {
+    "enabled": true,
+    "disabledTools": [],
+    "readOnly": false
+  },
   "//sensitiveFileGuard": "Flags .env files, private keys, CI config and lockfiles. 'ignorePaths' excuses ONE file by glob (a .pem test fixture); 'ignore' silences a whole CATEGORY and would excuse the next real key too — reach for ignorePaths first.",
   "sensitiveFileGuard": {
     "enabled": true,

package/dist/esm/core/checks/findings.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execa } from '../../utils/execa.js';
 import { logger, matchesAnyGlob } from '../../utils/index.js';
+import { fileFindings, noteLocation } from '../finding-store.js';
 import { listTrackedFiles } from '../targets.js';
 import { fail, pass, warn } from '../types.js';
 /**
@@ -370,6 +371,8 @@ export const DEFAULT_DATAFLOW_WINDOW = 10;
 const CROSS_LINE_SQL_LABEL = 'Interpolated value reaches a query (SQL injection risk, cross-line)';
 /** `@@ ... @@` — a new hunk, and the boundary taint never crosses. */
 const DIFF_HUNK_HEADER = /^@@ /;
+/** The first line of the new side of a hunk: `@@ -3,2 +10,4 @@` → 10. */
+const HUNK_NEW_START = /^@@ -\d+(?:,\d+)? \+(\d+)/;
 /**
  * Whether this line hands `name` to a query sink.
  *
@@ -443,6 +446,9 @@ export function scanDiffPatterns(stdout, patterns, opts = {}) {
     const mode = opts.comments ?? 'language';
     const ignorePaths = opts.ignorePaths ?? [];
     let syntax = 'both';
+    // Where the walk is, for findings that need to say so.
+    let file = '';
+    let newLine = 0;
     // Block comments span lines, so the state belongs to the walk, not to one line.
     let inBlockComment = false;
     // Whole files can be excluded by glob; the flag persists until the next header.
@@ -453,6 +459,7 @@ export function scanDiffPatterns(stdout, patterns, opts = {}) {
     for (const line of stdout.split('\n')) {
         const header = DIFF_FILE_HEADER.exec(line);
         if (header) {
+            file = header[1];
             syntax = mode === 'language' ? commentSyntaxFor(header[1]) : 'both';
             inBlockComment = false;
             skippingFile = ignorePaths.length > 0 && matchesAnyGlob(header[1], ignorePaths);
@@ -461,9 +468,15 @@ export function scanDiffPatterns(stdout, patterns, opts = {}) {
         }
         // Checked before the `+` filter below, which a hunk header does not satisfy.
         if (DIFF_HUNK_HEADER.test(line)) {
+            newLine = Number(HUNK_NEW_START.exec(line)?.[1] ?? 0);
             taint.reset();
             continue;
         }
+        // Counted before any skip: an ignored or excluded line still occupies a line
+        // number in the file, and the ones after it must not shift.
+        const lineNo = newLine;
+        if (line.startsWith('+'))
+            newLine++;
         if (skippingFile)
             continue;
         // Only added lines carry block-comment state: a `-` line is code being
@@ -475,18 +488,28 @@ export function scanDiffPatterns(stdout, patterns, opts = {}) {
         const prepared = uncomment(line, { mode, syntax, inBlockComment });
         inBlockComment = prepared.inBlockComment;
         const asCode = stripStringLiterals(prepared.text);
-        for (const { pattern, label, severity, view } of patterns) {
-            if (pattern.test(view === 'code' ? asCode : prepared.text)) {
-                const bucket = severity === 'error' ? errors : warnings;
-                (bucket[label] ?? (bucket[label] = [])).push(line.slice(1).trim().substring(0, SAMPLE_MAX_LENGTH));
-            }
-        }
+        const where = { file, line: lineNo };
+        recordMatches(patterns, { text: prepared.text, asCode }, line, where, { errors, warnings });
         if (taint.inspect(prepared.text, asCode)) {
-            (warnings[CROSS_LINE_SQL_LABEL] ?? (warnings[CROSS_LINE_SQL_LABEL] = [])).push(line.slice(1).trim().substring(0, SAMPLE_MAX_LENGTH));
+            record(warnings, CROSS_LINE_SQL_LABEL, line, where);
         }
     }
     return { errors, warnings };
 }
+/** File one added line under `label` and remember where it was, for findings that say so. */
+function record(bucket, label, line, where) {
+    const sample = line.slice(1).trim().substring(0, SAMPLE_MAX_LENGTH);
+    (bucket[label] ?? (bucket[label] = [])).push(sample);
+    noteLocation(label, sample, where.file, where.line);
+}
+/** File every pattern that matches one prepared line under its own label and severity. */
+function recordMatches(patterns, view, line, where, into) {
+    for (const { pattern, label, severity, view: wants } of patterns) {
+        if (pattern.test(wants === 'code' ? view.asCode : view.text)) {
+            record(severity === 'error' ? into.errors : into.warnings, label, line, where);
+        }
+    }
+}
 /**
  * Reduce one added line to what should be matched against: block comments
  * blanked (carrying the open state on), then the trailing line comment removed.
@@ -577,6 +600,7 @@ export function bucketTotal(bucket) {
  */
 export function reportCountedFindings(findings, ctx, opts) {
     const sev = severityEmitter(opts.severity, opts.fallback ?? 'warn');
+    fileFindings(findings, sev.icon === '❌' ? 'error' : 'warn');
     logFindings(findings, {
         prefix: opts.prefix,
         sampleLimit: opts.sampleLimit ?? ctx.config.log?.sampleLimit ?? 3,
@@ -681,6 +705,8 @@ export function reportSeverityBuckets(errorsIn, warningsIn, opts) {
     const ignore = opts.ignore ?? [];
     const filed = applyOverrides(dropIgnored(errorsIn, ignore), dropIgnored(warningsIn, ignore), opts.severityOverrides ?? {});
     const { errors, warnings } = filed;
+    fileFindings(errors, 'error');
+    fileFindings(warnings, 'warn');
     const totalErrors = bucketTotal(errors);
     const totalWarnings = bucketTotal(warnings);
     if (totalErrors === 0 && totalWarnings === 0)

package/dist/esm/core/checks/git/large-files.d.ts

@@ -1,2 +1,3 @@
 import { Check } from '../../types.js';
+export declare const DEFAULT_MAX_KB = 500;
 export declare const largeFilesCheck: Check;

package/dist/esm/core/checks/git/large-files.js

@@ -5,7 +5,7 @@ import { logger, matchesAnyGlob } from '../../../utils/index.js';
 import { resolveTargetFiles } from '../../targets.js';
 import { pass, skip } from '../../types.js';
 import { severityEmitter } from '../findings.js';
-const DEFAULT_MAX_KB = 500;
+export const DEFAULT_MAX_KB = 500;
 /**
  * Lockfiles are legitimately large and always generated, never accidental — so
  * they're exempt from the size/binary guard by default (a 600 KB

package/dist/esm/core/checks/pr/pr-size-check.d.ts

@@ -1,2 +1,4 @@
 import { Check } from '../../types.js';
+export declare const DEFAULT_MAX_FILES = 50;
+export declare const DEFAULT_MAX_LINES = 1000;
 export declare const prSizeCheck: Check;

package/dist/esm/core/checks/pr/pr-size-check.js

@@ -1,8 +1,8 @@
 import { execa } from '../../../utils/execa.js';
 import { logger } from '../../../utils/index.js';
 import { pass, skip, warn } from '../../types.js';
-const DEFAULT_MAX_FILES = 50;
-const DEFAULT_MAX_LINES = 1000;
+export const DEFAULT_MAX_FILES = 50;
+export const DEFAULT_MAX_LINES = 1000;
 export const prSizeCheck = {
     name: 'PR Size',
     phase: 'informational',

package/dist/esm/core/checks/security/agent-instructions.d.ts

@@ -0,0 +1,4 @@
+import { Check } from '../../types.js';
+import { DiffPattern } from '../findings.js';
+export declare const AGENT_PATTERNS: DiffPattern[];
+export declare const agentInstructionsCheck: Check;

package/dist/esm/core/checks/security/agent-instructions.js

@@ -0,0 +1,146 @@
+// cspell:ignore windsurfrules
+import { logger } from '../../../utils/index.js';
+import { listTrackedFiles } from '../../targets.js';
+import { skip } from '../../types.js';
+import { clientFindingOptions, diffAddedLines, emptyBuckets, mergeSeverityBuckets, reportSeverityBuckets, scanDiffPatterns, scanTrackedFiles, } from '../findings.js';
+/**
+ * Files that tell an AI agent what to do, or what it may do.
+ *
+ * They are code in every sense that matters: an agent reads them and acts, with
+ * the developer's shell and the developer's credentials. A pull request that edits
+ * one changes what every contributor's agent will do on its next run, and the diff
+ * is prose — which review tends to skim. That makes this the cheapest place in a
+ * repository to plant an instruction, and the least reviewed.
+ */
+const INSTRUCTION_GLOBS = [
+    'AGENTS.md',
+    '**/AGENTS.md',
+    'CLAUDE.md',
+    '**/CLAUDE.md',
+    'GEMINI.md',
+    '.cursorrules',
+    '.windsurfrules',
+    '.cursor/rules/**',
+    '.github/copilot-instructions.md',
+    '.claude/commands/**',
+    '.claude/agents/**',
+    '.claude/skills/**',
+    '.claude/settings.json',
+    '.mcp.json',
+];
+/** Dot-directories the file walk drops by default and this check lives in. */
+const KEEP_DIRS = ['.claude', '.cursor', '.github'];
+/**
+ * Characters a person cannot see and a model reads anyway: zero-width characters,
+ * bidirectional overrides and the Unicode "tag" block. Each has been used to hide
+ * an instruction inside text that looks harmless on screen. A byte-order mark is
+ * left out on purpose — editors put one at the top of ordinary files.
+ */
+const INVISIBLE = '[\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2064\\u2066-\\u2069]|[\\u{E0000}-\\u{E007F}]';
+export const AGENT_PATTERNS = [
+    {
+        pattern: new RegExp(`^\\+(?!\\+).*(?:${INVISIBLE})`, 'u'),
+        label: 'invisible Unicode characters (can hide instructions from a human reviewer)',
+        severity: 'error',
+    },
+    {
+        pattern: 
+        // "Do not add X without telling the user" asks the agent to check in, so a
+        // `without` that follows a negation in the same sentence is not a match.
+        /^\+(?!\+)(?![^\n]*\b(?:do not|don't|never)\b[^.\n]*\bwithout\b).*\b(?:do not|don't|never|without)\b[^.\n]{0,30}\b(?:tell|telling|inform|informing|mention|show|reveal|notify)\b[^.\n]{0,20}\b(?:the )?(?:user|developer|human)\b/i,
+        label: 'tells the agent to hide something from the user',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:send|post|upload|curl|wget|fetch|exfiltrate|email)\b[^\n]{0,80}(?:\.env\b|credentials?|secrets?|api[_ -]?keys?|\btokens?\b|\bssh\b|id_rsa)[^\n]{0,80}https?:\/\//i,
+        label: 'sends credentials or secrets to a URL',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:ignore|disregard|forget|override)\b[^.\n]{0,40}\b(?:previous|prior|above|earlier|all|any)\b[^.\n]{0,30}\b(?:instructions?|rules|prompts?|guidelines)\b/i,
+        label: 'prompt-injection phrasing ("ignore previous instructions")',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:curl|wget)\b[^|\n]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b/i,
+        label: 'pipes a download straight into a shell (an agent will run what it is told to run)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+).*(?:--no-verify|--dangerously-skip-permissions|--no-gpg-sign)\b/,
+        label: 'instructs the agent to skip a safety check',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*"defaultMode"\s*:\s*"bypassPermissions"/,
+        label: 'bypassPermissions as the project default (every contributor’s agent runs without asking)',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+)\s*"enableAllProjectMcpServers"\s*:\s*true/,
+        label: 'auto-approves every MCP server this repository declares',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*"(?:Bash|Write|Edit)(?:\((?:\*|:\*)\))?"\s*,?\s*$/,
+        label: 'permission granted for every shell command or file write',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+).*"url"\s*:\s*"http:\/\/(?!localhost|127\.0\.0\.1|\[::1\])/,
+        label: 'MCP server reached over plain HTTP',
+        severity: 'warn',
+    },
+    {
+        // `"args": ["-y", "pkg"]` with no @version: whatever is published next runs on
+        // the machine of everyone who opens the repository.
+        pattern: /^\+(?!\+).*"args"\s*:\s*\[\s*"-y"\s*,\s*"(?:@[^/"@]+\/)?[^"@]+"/,
+        label: 'MCP server fetched with npx and no pinned version (the next publish runs on every contributor’s machine)',
+        severity: 'warn',
+    },
+];
+export const agentInstructionsCheck = {
+    name: 'Agent Instructions',
+    phase: 'informational',
+    // No `requiresDiff`: a hidden instruction is as live in a file that arrived last
+    // year as in one added today, so a whole-repository run reads them too.
+    applies(ctx) {
+        return ctx.config.agentInstructions?.enabled !== false;
+    },
+    async run(ctx) {
+        try {
+            const cfg = ctx.config.agentInstructions ?? {};
+            const found = emptyBuckets();
+            const scanInto = (stdout) => {
+                // `comments: 'off'`: these are Markdown and JSON, where a leading `#` is a
+                // heading and `//` is part of a URL — stripping them as comments would
+                // blank exactly the lines worth reading.
+                mergeSeverityBuckets(found, scanDiffPatterns(stdout, AGENT_PATTERNS, {
+                    comments: 'off',
+                    ignorePaths: cfg.ignorePaths,
+                }));
+            };
+            if (ctx.baseSha) {
+                scanInto(await diffAddedLines(ctx, INSTRUCTION_GLOBS));
+            }
+            else if (ctx.config.run?.fullScanBehaviour !== 'skip') {
+                const files = await listTrackedFiles(ctx, INSTRUCTION_GLOBS, ['.'], {
+                    keepDirs: KEEP_DIRS,
+                });
+                if (files === null)
+                    return skip('git unavailable');
+                await scanTrackedFiles(ctx, files, scanInto);
+            }
+            return reportSeverityBuckets(found.errors, found.warnings, {
+                prefix: 'Agent Instructions',
+                errorSummary: n => `${n} issue(s)`,
+                warningSummary: n => `${n} warning(s)`,
+                ...clientFindingOptions(ctx, cfg),
+            });
+        }
+        catch (err) {
+            logger.warn(`[Agent Instructions]: ⚠️ Could not analyze agent files\n${err}`);
+            return skip('agent files unavailable');
+        }
+    },
+};

package/dist/esm/core/checks/security/diff-security.d.ts

@@ -1,2 +1,9 @@
 import { Check } from '../../types.js';
+import { DiffPattern } from '../findings.js';
+/**
+ * npm supply-chain entry points, matched in `package.json`. Both are how a
+ * compromised package reaches a developer machine or CI runner, so they are
+ * worth a human look whenever one is added — neither is wrong by itself.
+ */
+export declare const PACKAGE_JSON_PATTERNS: DiffPattern[];
 export declare const diffSecurityCheck: Check;

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

@@ -232,6 +232,25 @@ const KOTLIN_SECURITY_PATTERNS = [
     },
 ];
 const JS_GLOBS = ['*.ts', '*.tsx', '*.js', '*.jsx', '*.mjs', '*.cjs'];
+const PACKAGE_JSON_GLOBS = ['package.json', '*/package.json'];
+/**
+ * npm supply-chain entry points, matched in `package.json`. Both are how a
+ * compromised package reaches a developer machine or CI runner, so they are
+ * worth a human look whenever one is added — neither is wrong by itself.
+ */
+export const PACKAGE_JSON_PATTERNS = [
+    {
+        pattern: /^\+(?!\+)\s*"(?:preinstall|install|postinstall)"\s*:/,
+        label: 'npm install lifecycle script (runs on every consumer install)',
+        severity: 'warn',
+    },
+    {
+        // `repository.url` is the one key that legitimately holds a `git+https:` value.
+        pattern: /^\+(?!\+)\s*"(?!url")[^"]+"\s*:\s*"(?:git\+[a-z]+:|git:\/\/|git@|github:|https?:\/\/[^"]+\.(?:tgz|tar\.gz)")/,
+        label: 'dependency from a git or tarball URL (bypasses registry integrity and audit)',
+        severity: 'warn',
+    },
+];
 /**
  * Compile the client's `extraPatterns` into the same shape as the built-ins, so
  * a project rule gets identical treatment: comment stripping, the code/raw view,
@@ -320,6 +339,7 @@ export const diffSecurityCheck = {
             // Client `extraPatterns` run against every scanned language, since a
             // project rule is not tied to the built-in language split.
             const sets = [[JS_GLOBS, [...SECURITY_PATTERNS, ...extra]]];
+            sets.push([PACKAGE_JSON_GLOBS, PACKAGE_JSON_PATTERNS]);
             if (ctx.languages.includes('python')) {
                 sets.push([['*.py'], [...PYTHON_SECURITY_PATTERNS, ...extra]]);
             }

package/dist/esm/core/checks/security/security.d.ts

@@ -30,19 +30,6 @@ import { Check } from '../../types.js';
  *   the caller keeps its old wording rather than claiming a number it does not have.
  */
 export declare function countFindings(reportPath: string): number | null;
-/**
- * How the outcome names what was found.
- *
- * Its own function so both halves are reachable without running the scanner. The
- * corpus for this check deliberately does not: the wrapper downloads a gitleaks
- * binary on first use, and a unit suite that reaches the network is the thing the
- * `installer` seam in `ensure.ts` exists to avoid. What broke here was the wording
- * — a row that read the same for one secret and for thirty-nine — and the wording
- * is testable on its own.
- *
- * `null` keeps the old sentence rather than inventing a number: a report we could
- * not read is not a reason to claim a count.
- */
 export declare function secretsSummary(found: number | null): string;
 /**
  * Whether the wrapper died instead of reporting, judged from its stderr.

package/dist/esm/core/checks/security/security.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { getPackageConfigPath, hasLocalConfig } from '../../../config/index.js';
 import { execa } from '../../../utils/execa.js';
 import { logger, resolveGitRef, resolvePackageBin } from '../../../utils/index.js';
+import { addFinding } from '../../finding-store.js';
 import { fail, pass, skip, warn } from '../../types.js';
 /**
  * A HOME the scanner can actually write to.
@@ -57,6 +58,31 @@ export function countFindings(reportPath) {
  * `null` keeps the old sentence rather than inventing a number: a report we could
  * not read is not a reason to claim a count.
  */
+/**
+ * Tell the report where each leak is. The secret itself is never copied: the
+ * finding carries a file, a line and the rule that matched, which is all anyone
+ * needs to go and remove it — and all that is safe to hand to an agent's context.
+ */
+function recordLeaks(reportPath, cwd) {
+    try {
+        const report = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+        if (!Array.isArray(report))
+            return;
+        for (const leak of report) {
+            if (typeof leak?.File !== 'string')
+                continue;
+            addFinding({
+                file: path.isAbsolute(leak.File) ? path.relative(cwd, leak.File) : leak.File,
+                line: typeof leak.StartLine === 'number' ? leak.StartLine : undefined,
+                rule: typeof leak.RuleID === 'string' ? leak.RuleID : 'secret',
+                severity: 'error',
+            });
+        }
+    }
+    catch {
+        // An unreadable report already shows up as an uncounted summary; no locations to add.
+    }
+}
 export function secretsSummary(found) {
     return found === null ? 'potential secrets detected' : `${found} potential secret(s)`;
 }
@@ -177,6 +203,7 @@ export const securityCheck = {
         if (stderr.trim())
             logger.warn(stderr.trimEnd());
         const found = countFindings(reportPath);
+        recordLeaks(reportPath, ctx.cwd);
         fs.rmSync(reportDir, { recursive: true, force: true });
         if (result.exitCode === 0)
             return pass();

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

@@ -52,6 +52,39 @@ export const 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',
+    },
 ];
 export const workflowSecurityCheck = {
     name: 'Workflow Security',

package/dist/esm/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>;