diffsplain 0.2.1 → 0.4.0

package/scripts/build-diff-data.mjs

@@ -79,6 +79,7 @@ const cacheRoot = cacheOption
   : resolve(projectRoot, '.cache/git');
 const remoteMode = Boolean(prOption || branchOption);
 const watching = has('--watch');
+const ignoreSummaryWatch = has('--ignore-summary-watch');
 
 if (prOption && branchOption) fail('--pr and --branch cannot be used together');
 if (prOption && (baseOption || headOption)) fail('--pr cannot be used with --base or --head');
@@ -706,7 +707,25 @@ function resolveTarget() {
   return resolveLocalTarget();
 }
 
-function filePatch(file, target) {
+function trackedPatches(files, target) {
+  const raw = target.runGit([
+    'diff',
+    '--no-ext-diff',
+    '--no-textconv',
+    '--binary',
+    '--find-renames',
+    ...target.range,
+  ]);
+  const patches = raw
+    .split(/(?=^diff --git )/m)
+    .filter((patch) => patch.startsWith('diff --git '));
+  if (patches.length !== files.length) return undefined;
+  return new Map(
+    files.map((file, index) => [file.path, patches[index]]),
+  );
+}
+
+function filePatch(file, target, patches) {
   if (file.untracked) {
     return runRepoWithDiffExit([
       'diff',
@@ -719,6 +738,8 @@ function filePatch(file, target) {
       file.path,
     ]);
   }
+  const combined = patches?.get(file.path);
+  if (combined !== undefined) return combined;
   const pathspec = file.oldPath ? [file.oldPath, file.path] : [file.path];
   return target.runGit([
     'diff',
@@ -766,7 +787,7 @@ function build() {
   const target = resolveTarget();
   const remoteRepository = githubRepository(target.remote?.url);
   const summaryDoc = readJson(summariesPath, {}) || {};
-  const nameStatus = parseNameStatus(
+  const allTrackedFiles = parseNameStatus(
     target.runGit([
       'diff',
       '--no-ext-diff',
@@ -776,7 +797,10 @@ function build() {
       '--find-renames',
       ...target.range,
     ]),
-  ).filter((file) => !excludedPaths.has(file.path));
+  );
+  const nameStatus = allTrackedFiles.filter(
+    (file) => !excludedPaths.has(file.path),
+  );
   const numstat = parseNumstat(
     target.runGit([
       'diff',
@@ -788,6 +812,7 @@ function build() {
       ...target.range,
     ]),
   );
+  const patches = trackedPatches(allTrackedFiles, target);
 
   if (target.kind === 'worktree' || target.kind === 'checkout') {
     const trackedPaths = new Set(nameStatus.map((file) => file.path));
@@ -815,7 +840,7 @@ function build() {
           deletions: 0,
           isBinary: false,
         };
-    const patch = filePatch(file, target);
+    const patch = filePatch(file, target, patches);
     const binary =
       stat.isBinary ||
       patch.includes('Binary files ') ||
@@ -954,9 +979,11 @@ function build() {
 
 function fingerprint() {
   let summariesTime = '';
-  try {
-    summariesTime = String(statSync(summariesPath).mtimeMs);
-  } catch {}
+  if (!ignoreSummaryWatch) {
+    try {
+      summariesTime = String(statSync(summariesPath).mtimeMs);
+    } catch {}
+  }
   if (remoteMode) return summariesTime;
   if (baseOption && headOption) {
     return [

package/scripts/cli-args.mjs

@@ -16,6 +16,7 @@ const valueOptions = new Set([
   '--model',
   '--reasoning',
   '--batch-size',
+  '--jobs',
   '--port',
 ]);
 const flagOptions = new Set([
@@ -38,6 +39,9 @@ export const helpText = `Usage: diffsplain [REPO] [options]
 Show the current checkout against its default branch:
   diffsplain
 
+Commands:
+  doctor              Check Git, GitHub CLI, and coding agents
+
 Targets:
   --branch NAME       Show a remote branch against its default branch
   --pr NUMBER|URL     Show a GitHub pull request
@@ -48,11 +52,12 @@ Targets:
 Options:
   --repo PATH|URL|OWNER/NAME
                       Repo to review (default: current repo)
-  --agent NAME        Use codex, claude, copilot, or opencode
+  --agent NAME        Use codex, claude, copilot, cursor, or opencode
   --no-agent          Do not write agent notes
   --model NAME        Model for agent notes
   --reasoning LEVEL   Agent reasoning effort when supported
-  --batch-size COUNT  Files per agent pass (default: 4)
+  --batch-size COUNT  Maximum files per agent pass (default: 12)
+  --jobs COUNT        Agent passes to run at once (default: 3)
   --force             Regenerate all agent notes
   --remote NAME|URL   Git remote (default: origin)
   --port NUMBER       Local page port (default: 2299)
@@ -60,10 +65,11 @@ Options:
   -v, --version       Show the installed version
 
 Agent fallback:
-  codex, claude, copilot, opencode
+  codex, claude, copilot, cursor, opencode
 
 Examples:
   diffsplain
+  diffsplain doctor
   diffsplain --repo owner/project --pr 42
   diffsplain owner/project --branch feature/search
   diffsplain --agent claude`;
@@ -116,6 +122,11 @@ export function parseCliArgs(
     pathExists = existsSync,
   } = {},
 ) {
+  if (rawArgs[0] === 'doctor') {
+    if (rawArgs.length > 1) fail('doctor does not take arguments or options');
+    return { doctor: true };
+  }
+
   const options = new Map();
   const positionals = [];
   let agent;
@@ -259,6 +270,7 @@ export function parseCliArgs(
     '--model',
     '--reasoning',
     '--batch-size',
+    '--jobs',
   ]) {
     const value = options.get(name);
     if (value) {
@@ -287,6 +299,13 @@ export function parseCliArgs(
   ) {
     fail('--batch-size must be a number from 1 to 50');
   }
+  const jobs = options.get('--jobs');
+  if (
+    jobs &&
+    (!/^[1-9]\d*$/.test(jobs) || Number(jobs) > 8)
+  ) {
+    fail('--jobs must be a number from 1 to 8');
+  }
 
   const portValue = options.get('--port') || '2299';
   if (!/^\d+$/.test(portValue) || Number(portValue) > 65_535) {

package/scripts/coding-agents.mjs

@@ -1,8 +1,20 @@
 import { constants } from 'node:fs';
 import { access } from 'node:fs/promises';
-import { delimiter, dirname, isAbsolute, join } from 'node:path';
+import {
+  basename,
+  delimiter,
+  dirname,
+  isAbsolute,
+  join,
+} from 'node:path';
 
-export const codingAgents = ['codex', 'claude', 'copilot', 'opencode'];
+export const codingAgents = [
+  'codex',
+  'claude',
+  'copilot',
+  'cursor',
+  'opencode',
+];
 
 async function executable(path) {
   try {
@@ -16,7 +28,7 @@ async function executable(path) {
   }
 }
 
-export async function commandAvailable(
+export async function findCommand(
   command,
   {
     env = process.env,
@@ -28,7 +40,7 @@ export async function commandAvailable(
     command.includes('/') ||
     command.includes('\\')
   ) {
-    return executable(command);
+    return (await executable(command)) ? command : undefined;
   }
 
   const extensions =
@@ -39,11 +51,15 @@ export async function commandAvailable(
   for (const directory of directories) {
     for (const extension of extensions) {
       if (await executable(join(directory, `${command}${extension}`))) {
-        return true;
+        return join(directory, `${command}${extension}`);
       }
     }
   }
-  return false;
+  return undefined;
+}
+
+export async function commandAvailable(command, options) {
+  return Boolean(await findCommand(command, options));
 }
 
 export async function selectCodingAgent(
@@ -78,6 +94,7 @@ export function codingAgentBinary(
   } = {},
 ) {
   if (agent === 'codex') return codexBin || env.CODEX_BIN || agent;
+  if (agent === 'cursor') return env.CURSOR_BIN || 'cursor-agent';
   return env[`${agent.toUpperCase()}_BIN`] || agent;
 }
 
@@ -117,6 +134,14 @@ export function parseAgentResponse(agent, stdout) {
     if (parts.length) return parseJsonText(parts.join(''), 'OpenCode');
   }
 
+  if (agent === 'cursor') {
+    const envelope = parseJsonText(stdout, 'Cursor');
+    if (typeof envelope?.result === 'string') {
+      return parseJsonText(envelope.result, 'Cursor');
+    }
+    return envelope;
+  }
+
   const label = agent === 'copilot' ? 'Copilot' : 'Codex';
   return parseJsonText(stdout, label);
 }
@@ -193,6 +218,20 @@ export function agentCommand({
     return { command: binary, args, input: 'none' };
   }
 
+  if (agent === 'cursor') {
+    const args = ['--print', '--output-format', 'json'];
+    if (model) args.push('--model', model);
+    args.push(
+      `${prompt}\n\nRead the snapshot from @${basename(inputPath)}. Return only JSON that matches this schema:\n${JSON.stringify(schema)}`,
+    );
+    return {
+      command: binary,
+      args,
+      input: 'none',
+      cwd: dirname(inputPath),
+    };
+  }
+
   const args = [
     'run',
     '--pure',

package/scripts/doctor.mjs

@@ -0,0 +1,119 @@
+import { spawnSync } from 'node:child_process';
+import {
+  codingAgentBinary,
+  codingAgents,
+  findCommand,
+} from './coding-agents.mjs';
+
+const agentLabels = {
+  codex: 'Codex',
+  claude: 'Claude',
+  copilot: 'Copilot',
+  cursor: 'Cursor',
+  opencode: 'OpenCode',
+};
+
+function firstLine(value) {
+  return value
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '')
+    .split('\n')
+    .map((line) => line.trim())
+    .find(Boolean);
+}
+
+function commandVersion(command) {
+  const result = spawnSync(command, ['--version'], {
+    encoding: 'utf8',
+    timeout: 5_000,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) return undefined;
+  return firstLine(`${result.stdout || ''}\n${result.stderr || ''}`);
+}
+
+async function inspectDependency(
+  label,
+  command,
+  {
+    env,
+    platform,
+  },
+) {
+  const path = await findCommand(command, { env, platform });
+  if (!path) return { label, command, installed: false };
+  return {
+    label,
+    command,
+    installed: true,
+    path,
+    version: commandVersion(path),
+  };
+}
+
+function dependencyLine(dependency) {
+  const label = dependency.label.padEnd(9);
+  if (!dependency.installed) {
+    return `  ✗ ${label} not found (${dependency.command})`;
+  }
+  const mark = dependency.version ? '✓' : '!';
+  const version = dependency.version || 'version unavailable';
+  return `  ${mark} ${label} ${version} (${dependency.path})`;
+}
+
+function joinedAgentNames(agents) {
+  return agents.map((agent) => agent.label).join(', ');
+}
+
+export async function doctorReport({
+  env = process.env,
+  platform = process.platform,
+  architecture = process.arch,
+  nodeVersion = process.version,
+  nodePath = process.execPath,
+} = {}) {
+  const [git, gh, ...agents] = await Promise.all([
+    inspectDependency('Git', 'git', { env, platform }),
+    inspectDependency('gh', 'gh', { env, platform }),
+    ...codingAgents.map((agent) =>
+      inspectDependency(
+        agentLabels[agent],
+        codingAgentBinary(agent, { env }),
+        { env, platform },
+      ),
+    ),
+  ]);
+  const installedAgents = agents.filter((agent) => agent.installed);
+  const agentCount = installedAgents.length
+    ? `${installedAgents.length} installed`
+    : 'none installed';
+  const lines = [
+    'Diffsplain doctor',
+    '',
+    'Dependencies',
+    `  ✓ ${'Node'.padEnd(9)} ${nodeVersion} (${nodePath})`,
+    dependencyLine(git),
+    dependencyLine(gh),
+    '',
+    `Coding agents (${agentCount})`,
+    ...agents.map(dependencyLine),
+    '',
+    'Status',
+    git.installed
+      ? '  ✓ Git reviews are ready.'
+      : '  ✗ Git is not installed.',
+    installedAgents.length
+      ? `  ✓ Agent notes are ready with ${joinedAgentNames(installedAgents)}.`
+      : '  ✗ No supported coding agent is installed.',
+    gh.installed
+      ? '  ✓ Pull request lookup is ready with gh.'
+      : '  ✗ gh is not installed; pull request lookup is unavailable.',
+    `  Platform: ${platform} ${architecture}`,
+  ];
+  if (!installedAgents.length) {
+    lines.push('  Use --no-agent to run without agent notes.');
+  }
+  return {
+    text: lines.join('\n'),
+    ready: git.installed && installedAgents.length > 0,
+  };
+}