diffsplain 0.1.0

package/scripts/present.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { helpText, parseCliArgs } from './cli-args.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const callerDirectory = process.cwd();
+let cli;
+try {
+  cli = parseCliArgs(process.argv.slice(2), { callerDirectory });
+} catch (error) {
+  console.error(error.message);
+  console.error('Run diffsplain --help for usage.');
+  process.exit(2);
+}
+
+if (cli.help) {
+  console.log(helpText);
+  process.exit(0);
+}
+
+const { agentEnabled, port } = cli;
+const feedArgs = [...cli.feedArgs];
+const agentArgs = [...cli.agentArgs];
+const outputIndex = feedArgs.indexOf('--output');
+
+if (outputIndex === -1) {
+  feedArgs.push('--output', resolve(root, '.cache/diff-data.json'));
+  agentArgs.push('--output', resolve(root, '.cache/diff-data.json'));
+}
+if (!feedArgs.includes('--watch')) feedArgs.push('--watch');
+const outputPath = resolve(
+  callerDirectory,
+  feedArgs[feedArgs.indexOf('--output') + 1],
+);
+
+const builtPage = resolve(root, 'dist/index.html');
+if (!existsSync(builtPage)) {
+  const result = spawnSync(
+    process.platform === 'win32' ? 'npm.cmd' : 'npm',
+    ['run', 'build'],
+    { cwd: root, stdio: 'inherit' },
+  );
+  if (result.error) {
+    console.error(`Could not build the local page: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.status !== 0) process.exit(result.status || 1);
+}
+
+const feed = spawn(
+  process.execPath,
+  [resolve(root, 'scripts/build-diff-data.mjs'), ...feedArgs],
+  {
+    cwd: callerDirectory,
+    stdio: agentEnabled
+      ? ['inherit', 'pipe', 'inherit']
+      : ['inherit', 'inherit', 'inherit'],
+  },
+);
+const site = spawn(
+  process.execPath,
+  [
+    resolve(root, 'scripts/serve-built.mjs'),
+    '--output',
+    outputPath,
+    '--port',
+    String(port),
+  ],
+  { cwd: root, stdio: 'inherit' },
+);
+let closing = false;
+let agent;
+let agentTimer;
+let agentFingerprint;
+let queuedFingerprint;
+
+function snapshotState() {
+  try {
+    const snapshot = JSON.parse(readFileSync(outputPath, 'utf8'));
+    if (snapshot.notes?.reviewFingerprint) {
+      const fingerprint = snapshot.notes.reviewFingerprint;
+      return {
+        fingerprint,
+        hasCurrentAgentNotes:
+          snapshot.notes.complete &&
+          snapshot.notes.fresh &&
+          snapshot.notes.generatedFor === fingerprint,
+      };
+    }
+    const reviewData = {
+      repo: {
+        name: snapshot.repo.name,
+        base: snapshot.repo.base,
+        head: snapshot.repo.head,
+        branch: snapshot.repo.branch,
+        baseBranch: snapshot.repo.baseBranch,
+        remote: snapshot.repo.remote,
+        targetKind: snapshot.repo.target?.kind,
+      },
+      change: {
+        title: snapshot.change.title,
+        number: snapshot.change.number,
+      },
+      files: snapshot.files.map((file) => ({
+        path: file.path,
+        oldPath: file.oldPath,
+        status: file.status,
+        additions: file.additions,
+        deletions: file.deletions,
+        isBinary: file.isBinary,
+        patch: file.patch,
+      })),
+    };
+    return {
+      fingerprint: createHash('sha256')
+        .update(JSON.stringify(reviewData))
+        .digest('hex'),
+      hasCurrentAgentNotes: false,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function snapshotFingerprint() {
+  return snapshotState()?.fingerprint;
+}
+
+function runAgent(fingerprint) {
+  if (closing || !agentEnabled) return;
+  if (agent) {
+    queuedFingerprint = fingerprint;
+    return;
+  }
+  agentFingerprint = fingerprint;
+  const child = spawn(
+    process.execPath,
+    [resolve(root, 'scripts/generate-summaries.mjs'), ...agentArgs],
+    { cwd: callerDirectory, stdio: 'inherit' },
+  );
+  agent = child;
+  let settled = false;
+  const finish = (code, signal, error) => {
+    if (settled) return;
+    settled = true;
+    const finishedFingerprint = agentFingerprint;
+    if (agent === child) agent = undefined;
+    agentFingerprint = finishedFingerprint;
+    if (!closing && (error || code || signal)) {
+      if (error) console.error(error.message);
+      console.error(
+        'The coding agent could not write notes. The diff page will stay open.',
+      );
+    }
+    const latest = queuedFingerprint || snapshotFingerprint();
+    queuedFingerprint = undefined;
+    if (latest && latest !== finishedFingerprint) scheduleAgent(latest);
+  };
+  child.on('error', (error) => finish(1, undefined, error));
+  child.on('exit', (code, signal) => finish(code, signal));
+}
+
+function scheduleAgent(fingerprint) {
+  const state = snapshotState();
+  const selectedFingerprint = fingerprint || state?.fingerprint;
+  if (
+    !agentFingerprint &&
+    state?.hasCurrentAgentNotes &&
+    selectedFingerprint === state.fingerprint
+  ) {
+    agentFingerprint = selectedFingerprint;
+    return;
+  }
+  if (!selectedFingerprint || selectedFingerprint === agentFingerprint) return;
+  if (agent) {
+    queuedFingerprint = selectedFingerprint;
+    return;
+  }
+  clearTimeout(agentTimer);
+  agentTimer = setTimeout(() => runAgent(selectedFingerprint), 2_500);
+}
+
+if (agentEnabled && feed.stdout) {
+  const feedLines = createInterface({ input: feed.stdout });
+  feedLines.on('line', (line) => {
+    if (line.startsWith('Wrote ') || line === 'No diff-data changes') {
+      scheduleAgent();
+    }
+    if (line !== 'No diff-data changes') console.log(line);
+  });
+}
+
+function stop(code = 0) {
+  if (closing) return;
+  closing = true;
+  clearTimeout(agentTimer);
+  if (!feed.killed) feed.kill('SIGTERM');
+  if (!site.killed) site.kill('SIGTERM');
+  if (agent && !agent.killed) agent.kill('SIGTERM');
+  process.exitCode = code;
+}
+
+feed.on('exit', (code, signal) => {
+  if (!closing && (code || signal)) stop(code || 1);
+});
+feed.on('error', (error) => {
+  if (!closing) {
+    console.error(`Could not start the diff watcher: ${error.message}`);
+    stop(1);
+  }
+});
+site.on('exit', (code, signal) => {
+  if (!closing) stop(code || (signal ? 1 : 0));
+});
+site.on('error', (error) => {
+  if (!closing) {
+    console.error(`Could not start the local page: ${error.message}`);
+    stop(1);
+  }
+});
+process.on('SIGINT', () => stop(0));
+process.on('SIGTERM', () => stop(0));

package/scripts/serve-built.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { dirname, extname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const clientRoot = resolve(root, 'dist');
+const rawArgs = process.argv.slice(2);
+
+function option(name, fallback) {
+  const index = rawArgs.indexOf(name);
+  if (index === -1) return fallback;
+  const value = rawArgs[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`${name} needs a value`);
+  }
+  return value;
+}
+
+const output = resolve(option('--output', resolve(root, '.cache/diff-data.json')));
+const portValue = option('--port', '3000');
+if (!/^\d+$/.test(portValue) || Number(portValue) > 65_535) {
+  throw new Error('--port must be a number from 0 to 65535');
+}
+
+const contentTypes = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+function notFound() {
+  return new Response('Not found', { status: 404 });
+}
+
+async function fileResponse(file, { live = false } = {}) {
+  try {
+    const info = await stat(file);
+    if (!info.isFile()) return notFound();
+    return new Response(await readFile(file), {
+      headers: {
+        'content-type':
+          contentTypes[extname(file).toLowerCase()] ||
+          'application/octet-stream',
+        'cache-control': live
+          ? 'no-store'
+          : 'public, max-age=31536000, immutable',
+      },
+    });
+  } catch {
+    return notFound();
+  }
+}
+
+async function fetchAsset(request) {
+  const url = new URL(request.url);
+  if (url.pathname === '/diff-data.json') {
+    return fileResponse(output, { live: true });
+  }
+
+  let pathname;
+  try {
+    pathname = decodeURIComponent(url.pathname);
+  } catch {
+    return notFound();
+  }
+  const file = resolve(
+    clientRoot,
+    pathname === '/' ? 'index.html' : `.${pathname}`,
+  );
+  if (file !== clientRoot && !file.startsWith(`${clientRoot}${sep}`)) {
+    return notFound();
+  }
+  return fileResponse(file);
+}
+
+function nodeRequest(request) {
+  const host = request.headers.host || '127.0.0.1';
+  const init = {
+    method: request.method,
+    headers: request.headers,
+  };
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    init.body = Readable.toWeb(request);
+    init.duplex = 'half';
+  }
+  return new Request(`http://${host}${request.url}`, init);
+}
+
+async function send(nodeResponse, response) {
+  nodeResponse.writeHead(response.status, Object.fromEntries(response.headers));
+  if (!response.body) {
+    nodeResponse.end();
+    return;
+  }
+  Readable.fromWeb(response.body).pipe(nodeResponse);
+}
+
+const server = createServer(async (request, response) => {
+  try {
+    const webRequest = nodeRequest(request);
+    await send(response, await fetchAsset(webRequest));
+  } catch (error) {
+    console.error(error);
+    response.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+    response.end('Diffsplain could not load this page.');
+  }
+});
+
+server.listen(Number(portValue), '127.0.0.1', () => {
+  const address = server.address();
+  const selectedPort =
+    address && typeof address === 'object' ? address.port : Number(portValue);
+  console.log(`Diffsplain: http://127.0.0.1:${selectedPort}`);
+});
+
+let closing = false;
+function close() {
+  if (closing) return;
+  closing = true;
+  server.close(() => {
+    process.exitCode = 0;
+  });
+}
+
+process.on('SIGINT', close);
+process.on('SIGTERM', close);

package/scripts/summary-path.mjs

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+
+export function summaryPath({
+  projectRoot,
+  callerDirectory,
+  repo,
+  explicit,
+  pr,
+  branch,
+  checkout = false,
+  base,
+  head,
+  remote = 'origin',
+}) {
+  if (explicit) return resolve(callerDirectory, explicit);
+  if (!pr && !branch && !checkout && !(base && head)) {
+    return resolve(repo, '.diffsplain/summaries.json');
+  }
+
+  const pullRequest =
+    pr?.match(/\/pull\/(\d+)(?:\/|$)/)?.[1] || pr || undefined;
+  const target = pr
+    ? { kind: 'pr', pullRequest, remote }
+    : branch
+      ? { kind: 'branch', branch, base: base || 'default', remote }
+      : checkout
+        ? { kind: 'checkout', base: base || 'default', remote }
+        : { kind: 'range', base, head };
+  const key = createHash('sha256')
+    .update(JSON.stringify({ repo, target }))
+    .digest('hex')
+    .slice(0, 24);
+  return resolve(projectRoot, '.cache/summaries', `${target.kind}-${key}.json`);
+}

package/scripts/write-todo-demo.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  todoDemoChange,
+  todoDemoFiles,
+} from "../site/todo-demo.js";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const generatedAt = "2026-07-29T06:30:00.000Z";
+const fingerprint = createHash("sha256")
+  .update(JSON.stringify({ change: todoDemoChange, files: todoDemoFiles }))
+  .digest("hex");
+
+const snapshot = {
+  version: fingerprint.slice(0, 12),
+  generatedAt,
+  repo: {
+    name: "todo-list-demo",
+    root: "/demo/todo-list",
+    base: "main",
+    head: "feature/todo-filters",
+    branch: "feature/todo-filters",
+    baseBranch: "main",
+    target: {
+      kind: "pull-request",
+    },
+  },
+  change: todoDemoChange,
+  notes: {
+    reviewFingerprint: fingerprint,
+    generatedFor: fingerprint,
+    fresh: true,
+    complete: true,
+  },
+  files: todoDemoFiles,
+};
+
+const summaries = {
+  change: todoDemoChange,
+  files: Object.fromEntries(
+    todoDemoFiles.map((file) => [file.path, file.summary]),
+  ),
+};
+
+await Promise.all([
+  writeFile(
+    resolve(root, "public/demo-diff-data.json"),
+    `${JSON.stringify(snapshot, null, 2)}\n`,
+  ),
+  writeFile(
+    resolve(root, "data/todo-demo-summaries.json"),
+    `${JSON.stringify(summaries, null, 2)}\n`,
+  ),
+]);
+
+console.log(`Wrote todo demo with ${todoDemoFiles.length} files`);