pr-checkmate 3.3.0 → 4.0.0

package/dist/esm/mcp/review.d.ts

@@ -0,0 +1,63 @@
+import type { CheckReport } from '../core/types.js';
+/**
+ * What a review looks at.
+ *
+ * - `worktree` — every uncommitted change, staged or not, new files included.
+ *   The default: it is the code the agent just wrote.
+ * - `staged`   — the index only; what `git commit` would record.
+ * - `branch`   — commits since the branch left the default branch.
+ * - `full`     — every tracked file.
+ */
+export type ReviewScope = 'worktree' | 'staged' | 'branch' | 'full';
+export declare const REVIEW_SCOPES: readonly ReviewScope[];
+/**
+ * The checks cheap enough to run after every edit: nothing heavy, nothing that
+ * talks to a registry. Derived from the registry rather than listed, so a check
+ * added next month is in the loop from day one unless it declares itself heavy.
+ */
+export declare function fastCheckNames(): string[];
+/** The repository containing `dir`, or `undefined` when it is not inside one. */
+export declare function resolveRepoRoot(dir: string): Promise<string | undefined>;
+/**
+ * Turn the working tree into a git tree object without touching the real index.
+ *
+ * `git add -A` against a scratch copy of the index, then `write-tree`: the result
+ * is the same kind of object `precommit` diffs against, so every delta-aware check
+ * works unchanged. The agent's staging area stays exactly as they left it, and
+ * `.gitignore` is honoured because git itself does the walking.
+ *
+ * The one side effect is loose blob objects for the changed files in the object
+ * store; `git gc` reclaims them and they are invisible to every other command.
+ *
+ * @returns base and head to diff, or `undefined` when there is no HEAD yet.
+ */
+export declare function snapshotWorktree(cwd: string): Promise<{
+    baseSha: string;
+    headSha: string;
+} | undefined>;
+export interface ReviewOptions {
+    /** Directory inside the repository to review. */
+    cwd: string;
+    scope?: ReviewScope;
+    /** Exact check names to run; when set it overrides {@link ReviewOptions.deep}. */
+    only?: string[];
+    /** Include heavy and network checks (typecheck, grype, spellcheck, audit…). */
+    deep?: boolean;
+    /**
+     * Let formatters and `--fix` rewrite files. Off everywhere except `apply_fixes`;
+     * a review that edits the code it is reviewing has stopped being a review.
+     */
+    write?: boolean;
+}
+export interface ReviewOutcome {
+    report: CheckReport;
+    scope: ReviewScope;
+    /** Files the diff touches; absent for `full`, which has no diff. */
+    changedFiles?: number;
+    /** Set when the requested scope could not be built and a fallback ran instead. */
+    note?: string;
+}
+/** Run one review, read-only and silent: never writes files, never posts a comment. */
+export declare function review(opts: ReviewOptions): Promise<ReviewOutcome>;
+/** Files in the working-tree diff, with a content hash, so a later call can tell what a fixer rewrote. */
+export declare function fingerprintChanges(cwd: string): Promise<Map<string, string>>;

package/dist/esm/mcp/review.js

@@ -0,0 +1,139 @@
+/**
+ * Running the gate on behalf of an AI agent — the part the MCP server and the
+ * commit hook share.
+ *
+ * Both exist for the same reason: an agent has not committed yet. The CLI's own
+ * scopes answer other questions — `precommit` looks at the index, which an agent
+ * that never ran `git add` leaves empty, and the default branch scope looks at
+ * commits, which is exactly what has not happened. So this module adds the scope
+ * an agent actually needs: *everything I have changed so far*.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/loader.js';
+import { REGISTRY } from '../core/registry.js';
+import { runChecks } from '../core/run-checks.js';
+import { execa } from '../utils/execa.js';
+export const REVIEW_SCOPES = ['worktree', 'staged', 'branch', 'full'];
+/**
+ * Checks that need the network. A tool call that waits on a registry is a tool
+ * call the agent stops trusting, so they sit behind `deep` with the heavy ones.
+ */
+const NETWORK_CHECKS = new Set(['NPM Audit', 'Outdated Deps']);
+/**
+ * The checks cheap enough to run after every edit: nothing heavy, nothing that
+ * talks to a registry. Derived from the registry rather than listed, so a check
+ * added next month is in the loop from day one unless it declares itself heavy.
+ */
+export function fastCheckNames() {
+    return REGISTRY.filter(c => c.weight !== 'heavy' && !NETWORK_CHECKS.has(c.name)).map(c => c.name);
+}
+/** The repository containing `dir`, or `undefined` when it is not inside one. */
+export async function resolveRepoRoot(dir) {
+    try {
+        const { stdout } = await execa('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Turn the working tree into a git tree object without touching the real index.
+ *
+ * `git add -A` against a scratch copy of the index, then `write-tree`: the result
+ * is the same kind of object `precommit` diffs against, so every delta-aware check
+ * works unchanged. The agent's staging area stays exactly as they left it, and
+ * `.gitignore` is honoured because git itself does the walking.
+ *
+ * The one side effect is loose blob objects for the changed files in the object
+ * store; `git gc` reclaims them and they are invisible to every other command.
+ *
+ * @returns base and head to diff, or `undefined` when there is no HEAD yet.
+ */
+export async function snapshotWorktree(cwd) {
+    let baseSha;
+    try {
+        baseSha = (await execa('git', ['rev-parse', 'HEAD'], { cwd })).stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'pr-checkmate-index-'));
+    try {
+        const indexPath = (await execa('git', ['rev-parse', '--git-path', 'index'], { cwd })).stdout;
+        const realIndex = path.resolve(cwd, indexPath.trim());
+        const scratchIndex = path.join(scratch, 'index');
+        if (fs.existsSync(realIndex))
+            fs.copyFileSync(realIndex, scratchIndex);
+        const env = { GIT_INDEX_FILE: scratchIndex };
+        await execa('git', ['add', '-A'], { cwd, env });
+        const headSha = (await execa('git', ['write-tree'], { cwd, env })).stdout.trim();
+        return { baseSha, headSha };
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** Run one review, read-only and silent: never writes files, never posts a comment. */
+export async function review(opts) {
+    const scope = opts.scope ?? 'worktree';
+    const only = opts.only && opts.only.length > 0 ? opts.only : opts.deep ? undefined : fastCheckNames();
+    const base = {
+        cwd: opts.cwd,
+        config: loadProjectConfig(opts.cwd),
+        only,
+        reporter: 'none',
+        write: opts.write === true,
+    };
+    if (scope === 'full')
+        return { report: await runChecks({ ...base, full: true }), scope };
+    if (scope === 'staged')
+        return { report: await runChecks({ ...base, staged: true }), scope };
+    if (scope === 'branch')
+        return { report: await runChecks(base), scope };
+    const range = await snapshotWorktree(opts.cwd);
+    if (!range) {
+        // A repository with no commit has no base to diff against. Falling back to a
+        // full scan keeps the file-based checks useful, and the note says so.
+        return {
+            report: await runChecks({ ...base, full: true }),
+            scope: 'full',
+            note: 'no commits yet, so there is no diff to review; scanned every tracked file instead',
+        };
+    }
+    const changedFiles = (await execa('git', ['diff', '--name-only', range.baseSha, range.headSha], { cwd: opts.cwd })).stdout
+        .split('\n')
+        .filter(Boolean).length;
+    // Nothing edited yet: say so instead of printing a green report that reads as a
+    // verdict on code nobody wrote.
+    if (changedFiles === 0) {
+        return {
+            report: { results: [], summary: { passed: 0, warned: 0, failed: 0, skipped: 0 }, ok: true },
+            scope,
+            changedFiles,
+        };
+    }
+    return {
+        report: await runChecks({ ...base, baseSha: range.baseSha, headSha: range.headSha }),
+        scope,
+        changedFiles,
+    };
+}
+/** Files in the working-tree diff, with a content hash, so a later call can tell what a fixer rewrote. */
+export async function fingerprintChanges(cwd) {
+    const range = await snapshotWorktree(cwd);
+    const files = new Map();
+    if (!range)
+        return files;
+    const { stdout } = await execa('git', ['diff', '--name-only', range.baseSha, range.headSha], {
+        cwd,
+    });
+    for (const name of stdout.split('\n').filter(Boolean)) {
+        const abs = path.join(cwd, name);
+        files.set(name, fs.existsSync(abs) ? createHash('sha1').update(fs.readFileSync(abs)).digest('hex') : '');
+    }
+    return files;
+}

package/dist/esm/mcp/serve.d.ts

@@ -0,0 +1,8 @@
+import { type ServerDefinition } from './protocol.js';
+/**
+ * Run the server until the client closes stdin.
+ *
+ * Resolves once every request already received has been answered, so a client
+ * that sends a call and immediately closes the pipe still gets its response.
+ */
+export declare function serve(server: ServerDefinition, input?: NodeJS.ReadableStream): Promise<void>;

package/dist/esm/mcp/serve.js

@@ -0,0 +1,43 @@
+/**
+ * The stdio transport: one JSON message per line in, one per line out.
+ *
+ * stdout belongs to the protocol. A single stray byte on it — a log line, a
+ * progress message from a tool a check spawned — corrupts the stream and the
+ * client drops the server with an error that never mentions the cause. So the
+ * first thing `serve` does is take the real `stdout.write` for itself and point
+ * everything else at stderr, which MCP clients capture as the server's log.
+ */
+import readline from 'node:readline';
+import { isolateInheritedStdio } from '../utils/execa.js';
+import { logger } from '../utils/index.js';
+import { handleLine } from './protocol.js';
+/**
+ * Run the server until the client closes stdin.
+ *
+ * Resolves once every request already received has been answered, so a client
+ * that sends a call and immediately closes the pipe still gets its response.
+ */
+export async function serve(server, input = process.stdin) {
+    const protocolWrite = process.stdout.write.bind(process.stdout);
+    const toStderr = ((chunk) => process.stderr.write(chunk));
+    process.stdout.write = toStderr;
+    isolateInheritedStdio();
+    logger.setSink({
+        out: chunk => void process.stderr.write(chunk),
+        err: chunk => void process.stderr.write(chunk),
+    });
+    const pending = new Set();
+    const lines = readline.createInterface({ input, crlfDelay: Infinity });
+    lines.on('line', line => {
+        if (!line.trim())
+            return;
+        const job = handleLine(server, line).then(response => {
+            if (response)
+                protocolWrite(`${JSON.stringify(response)}\n`);
+        });
+        pending.add(job);
+        void job.finally(() => pending.delete(job));
+    });
+    await new Promise(resolve => lines.once('close', resolve));
+    await Promise.allSettled([...pending]);
+}

package/dist/esm/mcp/settings.d.ts

@@ -0,0 +1,13 @@
+import type { ToolDefinition } from './protocol.js';
+export interface McpSettings {
+    /** `false` leaves the server connected but with no tools, resources or prompts. */
+    enabled: boolean;
+    /** Tool names to hide from the agent. Unknown names are ignored. */
+    disabledTools: string[];
+    /** Hide every tool that writes files (`apply_fixes`, `write_config`). */
+    readOnly: boolean;
+}
+/** The `mcp` block of the project's `pr-checkmate.json`, with defaults for whatever it leaves out. */
+export declare function readMcpSettings(cwd: string): McpSettings;
+/** The tools the agent may see under `settings`. */
+export declare function allowedTools(tools: ToolDefinition[], settings: McpSettings): ToolDefinition[];

package/dist/esm/mcp/settings.js

@@ -0,0 +1,43 @@
+/**
+ * What a project allows the MCP server to do, read from the `mcp` block of its
+ * `pr-checkmate.json`.
+ *
+ * Read again on every request instead of once at startup: the server outlives any
+ * single edit, and a user who turns a tool off expects the next call to obey,
+ * not the next restart. A missing or unreadable file means the defaults, so a
+ * typo in the JSON never silently switches the server off.
+ *
+ * Kept free of other pr-checkmate modules (type imports only) because the run
+ * summary asks the same question, and a heavier import would loop back into it.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULTS = { enabled: true, disabledTools: [], readOnly: false };
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The `mcp` block of the project's `pr-checkmate.json`, with defaults for whatever it leaves out. */
+export function readMcpSettings(cwd) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, 'pr-checkmate.json'), 'utf-8'));
+        const block = isRecord(parsed) ? parsed.mcp : undefined;
+        if (!isRecord(block))
+            return DEFAULTS;
+        return {
+            enabled: block.enabled !== false,
+            disabledTools: Array.isArray(block.disabledTools)
+                ? block.disabledTools.filter((n) => typeof n === 'string')
+                : [],
+            readOnly: block.readOnly === true,
+        };
+    }
+    catch {
+        return DEFAULTS;
+    }
+}
+/** The tools the agent may see under `settings`. */
+export function allowedTools(tools, settings) {
+    if (!settings.enabled)
+        return [];
+    return tools.filter(t => !settings.disabledTools.includes(t.name) && !(settings.readOnly && t.writes));
+}

package/dist/esm/mcp/tools.d.ts

@@ -0,0 +1,23 @@
+import type { CheckReport } from '../core/types.js';
+import type { ServerDefinition, ToolResult } from './protocol.js';
+import { type ReviewScope } from './review.js';
+/**
+ * Render a report for a model: findings first, nothing for what passed.
+ *
+ * A passing check is the expected case and carries no information the agent can
+ * act on, so only the count survives. Skips stay because one of them can mean "the
+ * tooling never arrived" — a hole in coverage the agent should be able to see.
+ */
+export declare function formatReport(report: CheckReport, meta: {
+    scope: ReviewScope;
+    changedFiles?: number;
+    note?: string;
+    advice?: string;
+}): ToolResult;
+/**
+ * The server definition `serve` hands to the protocol layer.
+ *
+ * What it offers is decided per access, from the project's `mcp` settings, so a
+ * change to `pr-checkmate.json` takes effect on the agent's next request.
+ */
+export declare function createServerDefinition(cwd?: string): ServerDefinition;