pr-checkmate 3.2.3 → 4.0.0

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.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/cjs/init.js

@@ -5,12 +5,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BLOCKING_BY_DEFAULT = void 0;
 exports.setupWorkflow = setupWorkflow;
-exports.templateExtras = templateExtras;
 exports.buildInitialConfig = buildInitialConfig;
 exports.init = init;
 const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
 const inquirer_1 = __importDefault(require("inquirer"));
+const path_1 = __importDefault(require("path"));
 const index_js_1 = require("./config/index.js");
 const findings_js_1 = require("./core/checks/findings.js");
 const index_js_2 = require("./utils/index.js");
@@ -420,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 {
@@ -450,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 {};

package/dist/cjs/mcp/config-tools.js

@@ -0,0 +1,320 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainConfig = explainConfig;
+exports.validateConfig = validateConfig;
+exports.writeConfig = writeConfig;
+exports.suggestConfig = suggestConfig;
+exports.formatSuggestion = formatSuggestion;
+/**
+ * Setting pr-checkmate up for one specific repository, by the agent that is
+ * already sitting in it.
+ *
+ * The slow part of adopting a gate is not turning it on; it is deciding what to do
+ * about the findings an existing codebase already has. The documented answer is a
+ * strict workflow with a permissive config, then promoting checks one at a time as
+ * they go clean. That is a procedure an agent can carry out — if it can see the
+ * baseline — so these tools hand it exactly that: what the repository looks like,
+ * what it fails today, and a config that makes the gate real from day one without
+ * turning the first run into three thousand red lines.
+ *
+ * Nothing here writes except `write_config`, and that one validates first, merges
+ * over what is already there, and never replaces a value the user chose.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const constants_js_1 = require("../config/constants.js");
+const loader_js_1 = require("../config/loader.js");
+const config_validation_js_1 = require("../core/checks/quality/config-validation.js");
+const registry_js_1 = require("../core/registry.js");
+const detect_language_js_1 = require("../utils/detect-language.js");
+const own_deps_js_1 = require("../utils/own-deps.js");
+const review_js_1 = require("./review.js");
+const CONFIG_FILE = 'pr-checkmate.json';
+const LEVELS = new Set(['error', 'warn', 'off']);
+const FAIL_ON = new Set(['error', 'warn', 'never']);
+/** Directories that hold code nobody on the team wrote by hand. Not in the default ignore list. */
+const GENERATED_DIRS = ['generated', '__generated__', 'vendor', 'third_party', 'third-party'];
+/**
+ * Checks whose failure is never "existing debt". A conflict marker is a file that
+ * does not run; a leaked secret is already exposed. Proposing `warn` for these
+ * would make the gate quietly agree to ship them, so they are reported as things
+ * to fix, and left blocking.
+ */
+const NEVER_DOWNGRADE = new Set(['Merge Conflict', 'Security Scan']);
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The schema shipped with the package, or `undefined` when this install does not carry it. */
+function loadSchema() {
+    const root = (0, own_deps_js_1.findOwnPackageRoot)();
+    if (!root)
+        return undefined;
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(root, 'pr-checkmate.schema.json'), 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveRef(node, schema) {
+    const ref = node.$ref?.replace('#/$defs/', '');
+    return ref && schema.$defs?.[ref] ? { ...schema.$defs[ref], ...node, $ref: undefined } : node;
+}
+/** First sentence, so a listing of sixty keys stays a listing. */
+const firstSentence = (text = '') => {
+    const cut = text.search(/(?<=[.!?])\s/);
+    return (cut === -1 ? text : text.slice(0, cut)).slice(0, 200);
+};
+/** What a key means, from the schema that ships with the package. */
+function explainConfig(key) {
+    const schema = loadSchema();
+    if (!schema?.properties) {
+        return { text: 'The configuration schema is not available in this install.', isError: true };
+    }
+    if (!key) {
+        const rows = Object.entries(schema.properties)
+            .filter(([name]) => name !== '$schema')
+            .map(([name, node]) => {
+            const resolved = resolveRef(node, schema);
+            return `- ${name}${resolved.description ? ` — ${firstSentence(resolved.description)}` : ''}`;
+        });
+        return {
+            text: `Keys of ${CONFIG_FILE} (pass one as "key" for details; nested keys use dots, e.g. "prSize.maxLines"):\n${rows.join('\n')}`,
+        };
+    }
+    let node = schema;
+    for (const part of key.split('.')) {
+        node = node?.properties?.[part] ? resolveRef(node.properties[part], schema) : undefined;
+        if (!node)
+            break;
+    }
+    if (!node) {
+        const near = (0, config_validation_js_1.suggestName)(key.split('.')[0], Object.keys(schema.properties));
+        return {
+            text: `No such key "${key}".${near ? ` Did you mean "${near}"?` : ''}`,
+            isError: true,
+        };
+    }
+    const lines = [`${key}${node.type ? ` (${node.type})` : ''}`];
+    if (node.description)
+        lines.push(node.description);
+    if (node.default !== undefined)
+        lines.push(`default: ${JSON.stringify(node.default)}`);
+    if (node.enum)
+        lines.push(`one of: ${node.enum.map(v => JSON.stringify(v)).join(', ')}`);
+    for (const [name, child] of Object.entries(node.properties ?? {})) {
+        const resolved = resolveRef(child, schema);
+        lines.push(`- ${key}.${name}${resolved.description ? ` — ${firstSentence(resolved.description)}` : ''}`);
+    }
+    return { text: lines.join('\n') };
+}
+/** Problems in a proposed `severity` map: names that are not checks, levels that are not levels. */
+function validateSeverity(severity) {
+    if (severity === undefined)
+        return [];
+    if (!isRecord(severity)) {
+        return ['"severity" must be an object of check name → "error" | "warn" | "off"'];
+    }
+    const problems = [];
+    const names = registry_js_1.REGISTRY.map(c => c.name);
+    for (const [check, level] of Object.entries(severity)) {
+        if (!names.includes(check)) {
+            const near = (0, config_validation_js_1.suggestName)(check, names);
+            problems.push(`severity: no check named "${check}"${near ? ` — did you mean "${near}"?` : ''}`);
+        }
+        if (typeof level !== 'string' || !LEVELS.has(level)) {
+            problems.push(`severity.${check}: "${String(level)}" is not one of error, warn, off`);
+        }
+    }
+    return problems;
+}
+/** Problems in a proposed config, phrased so the agent can correct them. Empty means it is acceptable. */
+function validateConfig(config, cwd) {
+    const problems = [];
+    const schema = loadSchema();
+    const known = Object.keys(schema?.properties ?? {});
+    if (known.length > 0) {
+        for (const key of Object.keys(config)) {
+            if (known.includes(key) || key.startsWith('//'))
+                continue;
+            const near = (0, config_validation_js_1.suggestName)(key, known);
+            problems.push(`unknown key "${key}"${near ? ` — did you mean "${near}"?` : ''}`);
+        }
+    }
+    problems.push(...validateSeverity(config.severity));
+    for (const [key, block] of Object.entries(config)) {
+        if (isRecord(block) && typeof block.failOn === 'string' && !FAIL_ON.has(block.failOn)) {
+            problems.push(`${key}.failOn: "${block.failOn}" is not one of error, warn, never`);
+        }
+    }
+    const sources = config.sourcePath === undefined ? [] : [config.sourcePath].flat();
+    for (const source of sources) {
+        if (typeof source !== 'string' || !node_fs_1.default.existsSync(node_path_1.default.resolve(cwd, source))) {
+            problems.push(`sourcePath: "${String(source)}" does not exist in this repository`);
+        }
+    }
+    return problems;
+}
+/** `{a:{b:1,c:2}}` under `a` → `a.b`, `a.c`: what was added, not just where it hangs. */
+function leafPaths(value, here) {
+    return isRecord(value) && Object.keys(value).length > 0
+        ? Object.entries(value).flatMap(([k, v]) => leafPaths(v, `${here}.${k}`))
+        : [here];
+}
+/**
+ * Merge `incoming` into `existing`. A value that is already set and differs is
+ * kept — the file is the user's — and listed, so the agent can ask rather than
+ * overwrite. Objects merge key by key; arrays and scalars are leaves.
+ */
+function mergeKeepingExisting(existing, incoming, trail, overwrite, report) {
+    const out = { ...existing };
+    for (const [key, value] of Object.entries(incoming)) {
+        const here = [...trail, key].join('.');
+        if (!(key in existing)) {
+            out[key] = value;
+            report.added.push(...leafPaths(value, here));
+        }
+        else if (isRecord(existing[key]) && isRecord(value)) {
+            out[key] = mergeKeepingExisting(existing[key], value, [...trail, key], overwrite, report);
+        }
+        else if (JSON.stringify(existing[key]) === JSON.stringify(value)) {
+            continue;
+        }
+        else if (overwrite) {
+            out[key] = value;
+            report.added.push(`${here} (replaced)`);
+        }
+        else {
+            report.kept.push(here);
+        }
+    }
+    return out;
+}
+/** Validate and write `config` into the repository's `pr-checkmate.json`. */
+function writeConfig(cwd, config, overwrite) {
+    if (!isRecord(config))
+        return { text: '"config" must be a JSON object.', isError: true };
+    const problems = validateConfig(config, cwd);
+    if (problems.length > 0) {
+        return {
+            text: `Not written — fix these first:\n${problems.map(p => `- ${p}`).join('\n')}`,
+            isError: true,
+        };
+    }
+    const file = node_path_1.default.join(cwd, CONFIG_FILE);
+    let existing = {};
+    if (node_fs_1.default.existsSync(file)) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(file, 'utf-8'));
+            if (isRecord(parsed))
+                existing = parsed;
+            else
+                throw new Error('not an object');
+        }
+        catch {
+            // A file we cannot read is a file we must not replace: the user may be mid-edit.
+            return {
+                text: `${CONFIG_FILE} exists but is not valid JSON; fix it by hand first.`,
+                isError: true,
+            };
+        }
+    }
+    const report = { added: [], kept: [] };
+    const merged = mergeKeepingExisting(existing, config, [], overwrite, report);
+    if (report.added.length === 0) {
+        return {
+            text: `Nothing to write: ${CONFIG_FILE} already holds these values.${report.kept.length > 0 ? ` Left as the user set them: ${report.kept.join(', ')} (pass overwrite: true only if they asked for the change).` : ''}`,
+            structured: { written: false, added: [], kept: report.kept },
+        };
+    }
+    // Point editors at the schema when this repository has the package installed:
+    // that line is what makes every other key discoverable by autocomplete.
+    const schemaPath = './node_modules/pr-checkmate/pr-checkmate.schema.json';
+    const withSchema = !('$schema' in merged) && node_fs_1.default.existsSync(node_path_1.default.join(cwd, schemaPath))
+        ? { $schema: schemaPath, ...merged }
+        : merged;
+    node_fs_1.default.writeFileSync(file, `${JSON.stringify(withSchema, null, 2)}\n`);
+    return {
+        text: [
+            `${existing && Object.keys(existing).length > 0 ? 'Updated' : 'Created'} ${CONFIG_FILE}:`,
+            ...report.added.map(k => `  + ${k}`),
+            ...(report.kept.length > 0
+                ? [
+                    `Left as the user set them: ${report.kept.join(', ')} (overwrite: true replaces them — only if asked).`,
+                ]
+                : []),
+        ].join('\n'),
+        structured: { written: true, added: report.added, kept: report.kept },
+    };
+}
+/**
+ * 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.
+ */
+async function suggestConfig(cwd) {
+    const current = (0, loader_js_1.loadProjectConfig)(cwd);
+    const usage = await (0, detect_language_js_1.detectLanguageUsage)(cwd, current.ignoreDirs ?? constants_js_1.IGNORED_DIRS, current.detect);
+    const languages = usage.map(u => `${u.lang} (${u.files} file${u.files === 1 ? '' : 's'})`);
+    const hasConfig = node_fs_1.default.existsSync(node_path_1.default.join(cwd, CONFIG_FILE));
+    const proposed = {};
+    const notes = [];
+    const generated = GENERATED_DIRS.filter(d => node_fs_1.default.existsSync(node_path_1.default.join(cwd, d)) && !(current.ignoreDirs ?? constants_js_1.IGNORED_DIRS).includes(d));
+    if (generated.length > 0) {
+        proposed.excludePaths = generated.map(d => `${d}/**`);
+        notes.push(`Excluded ${generated.join(', ')}: code nobody maintains by hand only produces findings no one can act on.`);
+    }
+    const baseline = await (0, review_js_1.review)({ cwd, scope: 'full' });
+    const severity = {};
+    const skipped = [];
+    for (const r of baseline.report.results) {
+        if (r.status === 'fail' && NEVER_DOWNGRADE.has(r.name)) {
+            notes.push(`${r.name} fails today (${r.details ?? 'findings'}) and is NOT proposed as a warning: fix it${r.name === 'Security Scan' ? ' and rotate whatever was exposed' : ''} instead of silencing it.`);
+        }
+        else if (r.status === 'fail') {
+            severity[r.name] = 'warn';
+            notes.push(`${r.name} fails today (${r.details ?? 'findings'}) → warn, so existing debt does not block every PR. Promote it back to "error" once it is clean.`);
+        }
+        else if (r.status === 'skip' && /tooling unavailable/.test(r.details ?? '')) {
+            skipped.push(r.name);
+        }
+    }
+    if (Object.keys(severity).length > 0)
+        proposed.severity = severity;
+    if (skipped.length > 0) {
+        notes.push(`Could not run ${skipped.join(', ')}: tooling not available here (run "pr-checkmate install" and ask again for a complete baseline).`);
+    }
+    const clean = baseline.report.results.filter(r => r.status === 'pass').length;
+    notes.push(`Baseline: ${clean} check(s) pass, ${baseline.report.summary.failed} fail, ${baseline.report.summary.warned} warn (fast checks only; "verify" adds the slow ones).`);
+    if (hasConfig)
+        notes.push(`${CONFIG_FILE} already exists: write_config keeps every value already set and only adds the rest.`);
+    if (Object.keys(proposed).length === 0) {
+        notes.push('The defaults already fit this repository: no config file is needed. Everything is on and blocking where it should be.');
+    }
+    return { proposed, notes, languages };
+}
+/** `suggest_config` as the text an agent reads. */
+function formatSuggestion(s) {
+    const body = Object.keys(s.proposed).length > 0
+        ? `\nProposed ${CONFIG_FILE}:\n${JSON.stringify(s.proposed, null, 2)}\n`
+        : '\n';
+    return {
+        text: [
+            `Languages: ${s.languages.join(', ') || 'none detected'}`,
+            ...s.notes.map(n => `- ${n}`),
+            body,
+            Object.keys(s.proposed).length > 0
+                ? 'Show this to the user and, if they agree, call write_config with it. Do not write it unasked.'
+                : '',
+        ]
+            .filter(Boolean)
+            .join('\n'),
+        structured: { languages: s.languages, proposed: s.proposed, notes: s.notes },
+    };
+}

package/dist/cjs/mcp/dependency.d.ts

@@ -0,0 +1,33 @@
+export type Ecosystem = 'npm' | 'pypi';
+/**
+ * `avoid`   — do not add it (does not exist, no such version, known serious advisory)
+ * `review`  — a person should look first (new, rarely used, deprecated, install script…)
+ * `ok`      — nothing found
+ * `unknown` — a lookup failed, so nothing can be said
+ */
+export type Verdict = 'avoid' | 'review' | 'ok' | 'unknown';
+export interface DependencyReport {
+    name: string;
+    ecosystem: Ecosystem;
+    version?: string;
+    verdict: Verdict;
+    reasons: string[];
+    facts: Record<string, string | number | boolean>;
+}
+/** The slice of a fetch the checks need; injectable so tests never touch the network. */
+export type FetchJson = (url: string, init?: RequestInit) => Promise<{
+    ok: boolean;
+    status: number;
+    body?: unknown;
+    error?: string;
+}>;
+/** The famous package `name` is suspiciously close to, if any. A name that *is* the famous one is not a match. */
+export declare function lookalikeOf(name: string, ecosystem: Ecosystem): string | undefined;
+/** Is `name` safe to add? Never throws: every failure becomes part of the verdict. */
+export declare function checkDependency(name: string, opts?: {
+    version?: string;
+    ecosystem?: Ecosystem;
+    fetchJson?: FetchJson;
+}): Promise<DependencyReport>;
+/** The report as the text an agent reads. */
+export declare function formatDependency(r: DependencyReport): string;