pr-checkmate 3.2.3 → 4.0.0

package/dist/esm/core/install/prepare.js

@@ -1,7 +1,7 @@
 import { logger } from '../../utils/logger.js';
 import { clearToolPaths, packagePresent, registerToolPaths } from '../../utils/resolve-bin.js';
 import { ensureTooling } from './ensure.js';
-import { PROFILES, planProfiles } from './profiles.js';
+import { planProfiles, PROFILES } from './profiles.js';
 /**
  * Whether a profile needs fetching at all, or already ships inside the package.
  *

package/dist/esm/core/install/profiles.d.ts

@@ -3,7 +3,7 @@ import type { Language, LanguageUsage } from '../../utils/detect-language.js';
 /**
  * A named bundle of tooling, and the checks that stop working without it.
  *
- * The package ships ~233 MB of tooling, and no repository needs all of it: a
+ * The tooling totals ~233 MB, and no repository needs all of it: a
  * Python service pays for the whole JavaScript toolchain, a repository with
  * Spellcheck switched off still pays for cspell. Profiles are how that stops —
  * they name which slice of the tooling a given repository actually needs.

package/dist/esm/core/install/profiles.js

@@ -20,9 +20,9 @@ export const PROFILES = [
             'typescript',
             'eslint',
             'eslint-config-prettier',
-            'eslint-plugin-import-x',
             'eslint-plugin-jsdoc',
             'eslint-plugin-prettier',
+            'eslint-plugin-simple-import-sort',
             'eslint-plugin-sonarjs',
             '@typescript-eslint/eslint-plugin',
             '@typescript-eslint/parser',

package/dist/esm/core/install/reuse.js

@@ -5,15 +5,18 @@ import { ownPackageRoot } from '../../utils/resolve-bin.js';
 /**
  * The major version we declare for a tool, from our own manifest.
  *
- * Read from `dependencies` rather than from the installed tree: what matters is
+ * Read from the manifest rather than from the installed tree: what matters is
  * the version our configuration was written against, and a hoisted install can
  * resolve to something else entirely.
  */
 function ownMajor(pkgName) {
     try {
         const manifest = path.join(ownPackageRoot(), 'package.json');
-        const deps = JSON.parse(fs.readFileSync(manifest, 'utf-8')).dependencies;
-        const range = deps?.[pkgName];
+        const parsed = JSON.parse(fs.readFileSync(manifest, 'utf-8'));
+        // Profile tooling is declared in `devDependencies` — it is fetched on demand
+        // rather than installed with us — but it is still the version our config was
+        // written against, and the manifest keeps both.
+        const range = parsed.dependencies?.[pkgName] ?? parsed.devDependencies?.[pkgName];
         if (!range)
             return null;
         // `^10.6.0`, `>=3.0.0`, `~5.1` — the leading number is the major in every

package/dist/esm/core/registry.js

@@ -38,6 +38,7 @@ import { packageSizeCheck } from './checks/quality/package-size.js';
 import { spellcheckCheck } from './checks/quality/spellcheck.js';
 import { symlinksCheck } from './checks/quality/symlinks.js';
 import { yamlLintCheck } from './checks/quality/yaml-lint.js';
+import { agentInstructionsCheck } from './checks/security/agent-instructions.js';
 import { diffSecurityCheck } from './checks/security/diff-security.js';
 import { dockerfileSecurityCheck } from './checks/security/dockerfile-security.js';
 import { migrationSafetyCheck } from './checks/security/migration-safety.js';
@@ -63,6 +64,7 @@ export const REGISTRY = [
     diffSecurityCheck,
     workflowSecurityCheck,
     dockerfileSecurityCheck,
+    agentInstructionsCheck,
     caseCollisionCheck,
     vulnScanCheck,
     grypeScanCheck,

package/dist/esm/core/reporters.js

@@ -1,4 +1,7 @@
 import fs from 'node:fs';
+import { isMcpRegistered } from '../agent/registration.js';
+import { AGENT_SETUP_COMMAND } from '../config/constants.js';
+import { readMcpSettings } from '../mcp/settings.js';
 import { paginate, request } from '../utils/http.js';
 import { logger } from '../utils/index.js';
 import { packageVersion } from '../utils/package-version.js';
@@ -100,6 +103,12 @@ function printStdout(report, cfg) {
     if (cfg.include?.docsLink !== false) {
         // The docs cover every check and config key.
         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 &&
+            readMcpSettings(process.cwd()).enabled &&
+            !isMcpRegistered(process.cwd())) {
+            logger.print(` AI AGENT: ${AGENT_SETUP_COMMAND} — your agent then writes code that passes.`);
+        }
     }
 }
 /** Network settings shared by every platform call. */

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

@@ -1,10 +1,11 @@
 import { isCiEnvironment, logger } from '../utils/index.js';
 import { packageVersion } from '../utils/package-version.js';
-import { Semaphore, resolveConcurrency, runPool, withTimeout } from '../utils/pool.js';
+import { resolveConcurrency, runPool, Semaphore, withTimeout } from '../utils/pool.js';
 import { clearToolPaths } from '../utils/resolve-bin.js';
 import { ResultCollector } from '../utils/result-collector.js';
 import { buildContext } from './context.js';
-import { prepareTooling, noTooling } from './install/prepare.js';
+import { collectFindings } from './finding-store.js';
+import { noTooling, prepareTooling } from './install/prepare.js';
 import { REGISTRY } from './registry.js';
 import { report } from './reporters.js';
 import { PHASES, } from './types.js';
@@ -169,15 +170,24 @@ async function runOne(check, ctx, collector, heavy, tooling) {
         }
         const started = Date.now();
         const timeoutMs = ctx.config.run?.checkTimeoutMs ?? 300000;
-        const execute = () => withTimeout(check.run(ctx), timeoutMs, () => {
-            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 collectFindings(() => withTimeout(check.run(ctx), timeoutMs, () => {
+                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) {
             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/esm/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/esm/core/sarif.js

@@ -0,0 +1,57 @@
+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`. */
+export 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/esm/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/esm/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/esm/index.js

@@ -6,6 +6,8 @@
 // Primary programmatic API: run checks and receive a structured report.
 // Never throws for violations, never calls process.exit — the caller decides.
 export { runChecks, buildContext, REGISTRY } from './core/index.js';
+// SARIF 2.1.0 export of a report, for code-scanning dashboards and editors.
+export { toSarif } from './core/sarif.js';
 // Authoring helpers for consumers writing their own checks (plugins).
 export { pass, warn, fail, skip, defineCheck } from './core/index.js';
 // Config helpers for consumers embedding pr-checkmate.

package/dist/esm/init.d.ts

@@ -30,14 +30,6 @@ export declare function setupWorkflow(root: string, mode: GateMode): void;
  * heart about what should block.
  */
 export declare const BLOCKING_BY_DEFAULT: readonly ["Security Scan", "Sensitive Files", "Diff Security", "Workflow Security", "Merge Conflict", "NPM Audit", "License Check", "Dependencies", "TypeScript", "ESLint", "YAML Lint"];
-/**
- * Every option the template documents that the file does not already carry, at
- * its default. Without this, options such as `vulnScan` (off by default) or
- * `licenseCheck` exist only in the docs, and nobody edits what they cannot see.
- * Comment keys travel with the option they describe, section headers with the
- * first option after them.
- */
-export declare function templateExtras(existing: Record<string, unknown>): Record<string, unknown>;
 export declare function buildInitialConfig(sourcePath: string, languages: string[]): Record<string, unknown>;
 /**
  * Initialize (or refresh) pr-checkmate configuration in the current project.

package/dist/esm/init.js

@@ -2,11 +2,11 @@ import { fileURLToPath as __fileURLToPath } from 'node:url';
 import { dirname as __dirnameFn } from 'node:path';
 const __dirname = __dirnameFn(__fileURLToPath(import.meta.url));
 import fs from 'fs';
-import path from 'path';
 import inquirer from 'inquirer';
-import { DEAD_CODE_IGNORE_DEFAULTS, DEFAULT_COMMANDS, DIFF_SECURITY_IGNORE_DEFAULTS, documentation, DOCS_URL, DUPLICATE_IGNORE_DEFAULTS, FULL_CONFIG_URL, GENERATED_DOC_FILES, IGNORED_DIRS, } from './config/index.js';
+import path from 'path';
+import { AGENT_SETUP_COMMAND, DEAD_CODE_IGNORE_DEFAULTS, DEFAULT_COMMANDS, DIFF_SECURITY_IGNORE_DEFAULTS, DOCS_URL, documentation, DUPLICATE_IGNORE_DEFAULTS, FULL_CONFIG_URL, GENERATED_DOC_FILES, IGNORED_DIRS, } from './config/index.js';
 import { DEFAULT_DATAFLOW_WINDOW } from './core/checks/findings.js';
-import { logger, detectLanguages, findOwnPackageRoot } from './utils/index.js';
+import { detectLanguages, findOwnPackageRoot, logger } from './utils/index.js';
 const CONFIG_FILE = path.resolve(process.cwd(), 'pr-checkmate.json');
 /**
  * Points editors at the bundled JSON schema. With the generated config reduced
@@ -286,7 +286,7 @@ const GRYPE_SCAN_SEED = {
  * Comment keys travel with the option they describe, section headers with the
  * first option after them.
  */
-export function templateExtras(existing) {
+function templateExtras(existing) {
     const templatePath = path.join(__dirname, 'config', 'pr-checkmate.template.json');
     if (!fs.existsSync(templatePath)) {
         return {};
@@ -413,6 +413,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 (AGENT_SETUP_COMMAND in commands)
+        return commands;
+    return { ...commands, [AGENT_SETUP_COMMAND]: DEFAULT_COMMANDS[AGENT_SETUP_COMMAND] };
+}
 async function updateConfig(root) {
     logger.info('[init]: pr-checkmate.json already exists — updating it.');
     try {
@@ -443,6 +453,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.writeFileSync(CONFIG_FILE, `${JSON.stringify(updated, null, 2)}\n`);

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