diffsplain 0.5.0 → 0.6.0

package/scripts/dev.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { stripVTControlCharacters } from "node:util";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function childStatus(code, signal) {
+  if (code !== null) return code;
+  return signal || "unknown";
+}
+
+function childExitCode(code) {
+  return code === null ? 1 : code;
+}
+
+// fallow-ignore-next-line complexity -- this validates the full dev-only command surface.
+export function parseDevelopmentArgs(rawArgs, callerDirectory = process.cwd()) {
+  const [mode, ...args] = rawArgs;
+  if (!["live", "mock"].includes(mode)) {
+    throw new Error('Use "live" or "mock".');
+  }
+  const values = new Map();
+  for (let index = 0; index < args.length; index += 1) {
+    const name = args[index];
+    if (!["--repo", "--fixture", "--port", "--delay"].includes(name)) {
+      throw new Error(`Unknown option: ${name}`);
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`${name} needs a value`);
+    if (values.has(name)) throw new Error(`${name} was passed more than once`);
+    values.set(name, value);
+    index += 1;
+  }
+  if (mode === "live" && values.has("--fixture")) {
+    throw new Error("--fixture is only available in mock mode");
+  }
+  if (mode === "mock" && values.has("--repo")) {
+    throw new Error("--repo is only available in live mode");
+  }
+  const port = values.get("--port") || "2299";
+  if (!/^\d+$/.test(port) || Number(port) > 65_535) {
+    throw new Error("--port must be a number from 0 to 65535");
+  }
+  const delay = values.get("--delay") || "750";
+  if (!/^\d+$/.test(delay) || Number(delay) < 10 || Number(delay) > 60_000) {
+    throw new Error("--delay must be a number from 10 to 60000");
+  }
+  return {
+    mode,
+    port,
+    delay,
+    repo: resolve(callerDirectory, values.get("--repo") || callerDirectory),
+    fixture: resolve(
+      callerDirectory,
+      values.get("--fixture") || resolve(root, "public/demo-diff-data.json"),
+    ),
+  };
+}
+
+export function developmentCommands(options, output) {
+  const clientReady = join(dirname(output), "client-ready");
+  const watcher =
+    options.mode === "live"
+      ? {
+          command: process.execPath,
+          args: [
+            resolve(root, "scripts/build-diff-data.mjs"),
+            "--repo",
+            options.repo,
+            "--worktree",
+            "--watch",
+            "--watch-content",
+            "--output",
+            output,
+          ],
+        }
+      : {
+          command: process.execPath,
+          args: [
+            resolve(root, "scripts/mock-agent.mjs"),
+            "--fixture",
+            options.fixture,
+            "--delay",
+            options.delay,
+            "--start-file",
+            join(dirname(output), "page-ready"),
+            "--advance-file",
+            clientReady,
+            "--output",
+            output,
+          ],
+        };
+  return {
+    watcher,
+    vite: {
+      command: process.execPath,
+      args: [
+        resolve(root, "node_modules/vite/bin/vite.js"),
+        "--host",
+        "127.0.0.1",
+        "--port",
+        options.port,
+      ],
+      env: {
+        DIFFSPLAIN_LIVE_OUTPUT: output,
+        ...(options.mode === "mock"
+          ? { DIFFSPLAIN_LIVE_ACK: clientReady }
+          : {}),
+      },
+    },
+  };
+}
+
+export function isDevelopmentEntry(argument, moduleUrl) {
+  return Boolean(argument) && pathToFileURL(resolve(argument)).href === moduleUrl;
+}
+
+export function viteServerUrl(output) {
+  return stripVTControlCharacters(output).match(
+    /Local:\s+(http:\/\/[^\s]+)/,
+  )?.[1];
+}
+
+// fallow-ignore-next-line complexity -- this supervisor owns both child lifecycles.
+async function main() {
+  const options = parseDevelopmentArgs(process.argv.slice(2));
+  if (!existsSync(options.mode === "live" ? options.repo : options.fixture)) {
+    throw new Error(
+      options.mode === "live"
+        ? `Repo does not exist: ${options.repo}`
+        : `Fixture does not exist: ${options.fixture}`,
+    );
+  }
+  const runtimeDirectory = mkdtempSync(join(tmpdir(), "diffsplain-dev-"));
+  const output = join(runtimeDirectory, "diff-data.json");
+  const { watcher, vite } = developmentCommands(options, output);
+  let closing = false;
+  let pageReady = false;
+  const children = new Set();
+  const stop = async (code = 0) => {
+    if (closing) return;
+    closing = true;
+    for (const child of children) {
+      if (!child.killed) child.kill("SIGTERM");
+    }
+    await Promise.all(
+      [...children].map((child) =>
+        child.exitCode === null ? once(child, "exit") : Promise.resolve(),
+      ),
+    );
+    rmSync(runtimeDirectory, { recursive: true, force: true });
+    process.exitCode = code;
+  };
+  process.on("SIGINT", () => void stop());
+  process.on("SIGTERM", () => void stop());
+
+  const watchChild = spawn(watcher.command, watcher.args, {
+    cwd: root,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  children.add(watchChild);
+  const viteChild = spawn(vite.command, vite.args, {
+    cwd: root,
+    env: { ...process.env, ...vite.env },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  children.add(viteChild);
+  for (const [name, child] of [
+    ["watcher", watchChild],
+    ["Vite", viteChild],
+  ]) {
+    child.on("error", (error) => {
+      if (!closing) {
+        console.error(`Could not start ${name}: ${error.message}`);
+        void stop(1);
+      }
+    });
+    child.on("exit", (code, signal) => {
+      children.delete(child);
+      if (!closing) {
+        console.error(`${name} stopped (${childStatus(code, signal)}).`);
+        void stop(childExitCode(code));
+      }
+    });
+  }
+  function relayWatcherLine(line) {
+    if (line) console.log(`[${options.mode}] ${line}`);
+  }
+  for (const stream of [watchChild.stdout, watchChild.stderr]) {
+    createInterface({ input: stream }).on("line", relayWatcherLine);
+  }
+  function relayViteLine(line) {
+    const url = viteServerUrl(line);
+    if (url && !pageReady) {
+      pageReady = true;
+      writeFileSync(join(runtimeDirectory, "page-ready"), "ready\n");
+      console.log(`Diffsplain ${options.mode} ready: ${url}`);
+    }
+    if (line) console.log(`[vite] ${line}`);
+  }
+  for (const stream of [viteChild.stdout, viteChild.stderr]) {
+    createInterface({ input: stream }).on("line", relayViteLine);
+  }
+}
+
+if (isDevelopmentEntry(process.argv[1], import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/doctor.mjs

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import {
+  agentDisabledReason,
   codingAgentBinary,
   codingAgents,
   findCommand,
@@ -12,6 +13,7 @@ const agentLabels = {
   cursor: 'Cursor',
   opencode: 'OpenCode',
 };
+const minimumNodeVersion = [22, 13, 0];
 
 function firstLine(value) {
   return value
@@ -21,99 +23,316 @@ function firstLine(value) {
     .find(Boolean);
 }
 
-function commandVersion(command) {
-  const result = spawnSync(command, ['--version'], {
+function commandResult(command, args, env) {
+  return spawnSync(command, args, {
     encoding: 'utf8',
+    env,
     timeout: 5_000,
     windowsHide: true,
   });
+}
+
+function commandVersion(command, env) {
+  const result = commandResult(command, ['--version'], env);
   if (result.error || result.status !== 0) return undefined;
   return firstLine(`${result.stdout || ''}\n${result.stderr || ''}`);
 }
 
-async function inspectDependency(
-  label,
-  command,
-  {
-    env,
-    platform,
-  },
-) {
+function commandSucceeds(command, args, env) {
+  const result = commandResult(command, args, env);
+  return !result.error && result.status === 0;
+}
+
+function parseNodeVersion(version) {
+  const match = version.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return undefined;
+  return match.slice(1).map(Number);
+}
+
+function supportsNodeVersion(version) {
+  const current = parseNodeVersion(version);
+  if (!current) return false;
+  for (const [index, part] of current.entries()) {
+    if (part !== minimumNodeVersion[index]) {
+      return part > minimumNodeVersion[index];
+    }
+  }
+  return true;
+}
+
+async function inspectDependency(label, command, { env, platform }) {
   const path = await findCommand(command, { env, platform });
-  if (!path) return { label, command, installed: false };
+  if (!path) {
+    return { label, command, installed: false, compatible: 'not-checked' };
+  }
+  const version = commandVersion(path, env);
   return {
     label,
     command,
     installed: true,
     path,
-    version: commandVersion(path),
+    version,
+    compatible: version ? 'not-verified' : 'unknown',
   };
 }
 
 function dependencyLine(dependency) {
   const label = dependency.label.padEnd(9);
+  if (dependency.disabled) {
+    return `  ! ${label} disabled (${dependency.disabled})`;
+  }
   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})`;
+  return `  ${mark} ${label} ${dependency.version || 'version unavailable'} (${dependency.path})`;
 }
 
-function joinedAgentNames(agents) {
-  return agents.map((agent) => agent.label).join(', ');
+function stateLine(name, value) {
+  return `    ${name.padEnd(14)} ${value}`;
 }
 
-export async function doctorReport({
-  env = process.env,
-  platform = process.platform,
-  architecture = process.arch,
-  nodeVersion = process.version,
-  nodePath = process.execPath,
-} = {}) {
+function capabilityLines(name, capability) {
+  return [
+    `  ${name}`,
+    stateLine(
+      'installed',
+      typeof capability.installed === 'boolean'
+        ? yesNo(capability.installed)
+        : capability.installed,
+    ),
+    stateLine('compatible', capability.compatible),
+    stateLine('authenticated', capability.authenticated),
+    stateLine('smoke test', capability.smokeTest),
+  ];
+}
+
+function yesNo(value) {
+  return value ? 'yes' : 'no';
+}
+
+function localSmokeTest(dependency, deep, env) {
+  if (!deep) return 'not-run';
+  if (!dependency.installed) return 'not-run';
+  return commandSucceeds(dependency.path, ['--help'], env)
+    ? 'passed (local command only)'
+    : 'failed (local command only)';
+}
+
+function providerCapability(agent, deep, env) {
+  return {
+    installed: agent.installed,
+    compatible: agent.compatible,
+    authenticated: 'not-checked',
+    smokeTest: localSmokeTest(agent, deep, env),
+  };
+}
+
+async function inspectDependencies(env, platform) {
   const [git, gh, ...agents] = await Promise.all([
     inspectDependency('Git', 'git', { env, platform }),
     inspectDependency('gh', 'gh', { env, platform }),
-    ...codingAgents.map((agent) =>
-      inspectDependency(
+    ...codingAgents.map((agent) => {
+      const disabled = agentDisabledReason(agent);
+      if (disabled) {
+        return Promise.resolve({
+          label: agentLabels[agent],
+          command: codingAgentBinary(agent, { env }),
+          installed: false,
+          compatible: 'no',
+          disabled,
+        });
+      }
+      return inspectDependency(
         agentLabels[agent],
         codingAgentBinary(agent, { env }),
         { env, platform },
-      ),
-    ),
+      );
+    }),
   ]);
-  const installedAgents = agents.filter((agent) => agent.installed);
-  const agentCount = installedAgents.length
+  return { git, gh, agents };
+}
+
+function coreInstalled(git, nodePath) {
+  return git.installed && Boolean(nodePath);
+}
+
+function coreReady(git, nodeSupported) {
+  return git.installed && Boolean(git.version) && nodeSupported;
+}
+
+function coreReviewCapability(git, nodeSupported, nodePath, deep, env) {
+  const ready = coreReady(git, nodeSupported);
+  return {
+    installed: coreInstalled(git, nodePath),
+    compatible: yesNo(ready),
+    authenticated: 'not-required',
+    smokeTest: localSmokeTest(git, deep, env),
+    ready,
+  };
+}
+
+function agentNoteCapabilities(agents, deep, env) {
+  return Object.fromEntries(
+    codingAgents.map((agent, index) => [
+      agent,
+      providerCapability(agents[index], deep, env),
+    ]),
+  );
+}
+
+function authenticationState(gh, env) {
+  if (!gh.installed) return 'not-checked';
+  return commandSucceeds(gh.path, ['auth', 'status', '--active'], env)
+    ? 'passed'
+    : 'failed';
+}
+
+function pullRequestCapability(gh, deep, env) {
+  return {
+    installed: gh.installed,
+    compatible: gh.compatible,
+    authenticated: authenticationState(gh, env),
+    smokeTest: localSmokeTest(gh, deep, env),
+  };
+}
+
+function machineReport({
+  deep,
+  platform,
+  architecture,
+  nodeVersion,
+  nodePath,
+  nodeSupported,
+  git,
+  gh,
+  agents,
+  capabilities,
+}) {
+  return {
+    schemaVersion: 1,
+    deep,
+    platform: { name: platform, architecture },
+    dependencies: {
+      node: {
+        installed: true,
+        version: nodeVersion,
+        path: nodePath,
+        compatible: nodeSupported ? 'yes' : 'no',
+      },
+      git,
+      gh,
+      agents: Object.fromEntries(
+        codingAgents.map((agent, index) => [agent, agents[index]]),
+      ),
+    },
+    capabilities,
+    ready: capabilities.coreReview.ready,
+  };
+}
+
+function installedCountLabel(installedAgents) {
+  return installedAgents.length
     ? `${installedAgents.length} installed`
     : 'none installed';
+}
+
+function agentCapabilityLines(agent, capabilities) {
+  return capabilityLines(
+    `Agent notes: ${agentLabels[agent]}`,
+    capabilities.agentNotes[agent],
+  );
+}
+
+function appendDoctorNotes(lines, installedAgents, deep) {
+  if (!installedAgents.length) {
+    lines.push('  No agent is required for a plain local review; use --no-agent.');
+  }
+  if (!deep) {
+    lines.push(
+      '  Smoke tests were not run. Use doctor --deep for local command checks.',
+    );
+  }
+}
+
+function reportText({
+  deep,
+  platform,
+  architecture,
+  nodeVersion,
+  nodePath,
+  git,
+  gh,
+  agents,
+  capabilities,
+}) {
+  const installedAgents = agents.filter((agent) => agent.installed);
   const lines = [
     'Diffsplain doctor',
     '',
     'Dependencies',
-    `  ✓ ${'Node'.padEnd(9)} ${nodeVersion} (${nodePath})`,
+    dependencyLine({
+      label: 'Node',
+      command: 'node',
+      installed: true,
+      path: nodePath,
+      version: nodeVersion,
+    }),
     dependencyLine(git),
     dependencyLine(gh),
     '',
-    `Coding agents (${agentCount})`,
+    `Coding agents (${installedCountLabel(installedAgents)})`,
     ...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.',
+    'Capabilities',
+    ...capabilityLines('Plain local review', {
+      ...capabilities.coreReview,
+      installed: yesNo(capabilities.coreReview.installed),
+    }),
+    ...codingAgents.flatMap((agent) =>
+      agentCapabilityLines(agent, capabilities),
+    ),
+    ...capabilityLines('Pull request lookup', {
+      ...capabilities.pullRequestLookup,
+      installed: yesNo(capabilities.pullRequestLookup.installed),
+    }),
     `  Platform: ${platform} ${architecture}`,
   ];
-  if (!installedAgents.length) {
-    lines.push('  Use --no-agent to run without agent notes.');
-  }
+  appendDoctorNotes(lines, installedAgents, deep);
+  return lines.join('\n');
+}
+
+export async function doctorReport({
+  env = process.env,
+  platform = process.platform,
+  architecture = process.arch,
+  nodeVersion = process.version,
+  nodePath = process.execPath,
+  deep = false,
+} = {}) {
+  const { git, gh, agents } = await inspectDependencies(env, platform);
+  const nodeSupported = supportsNodeVersion(nodeVersion);
+  const capabilities = {
+    coreReview: coreReviewCapability(git, nodeSupported, nodePath, deep, env),
+    agentNotes: agentNoteCapabilities(agents, deep, env),
+    pullRequestLookup: pullRequestCapability(gh, deep, env),
+  };
+  const reportOptions = {
+    deep,
+    platform,
+    architecture,
+    nodeVersion,
+    nodePath,
+    nodeSupported,
+    git,
+    gh,
+    agents,
+    capabilities,
+  };
+  const json = machineReport(reportOptions);
   return {
-    text: lines.join('\n'),
-    ready: git.installed && installedAgents.length > 0,
+    text: reportText(reportOptions),
+    json,
+    ready: json.ready,
   };
 }