@kgdiff/cli 0.0.0-stage → 0.1.0

package/src/model.ts

@@ -0,0 +1,181 @@
+/**
+ * Presentation model shared by every text output: hunk families, glyphs, name-status letters,
+ * phase grouping and the per-phase counts behind the counters and the diffstat bar.
+ */
+import type { DiffResult, Hunk, HunkKind, ReplayPhase } from '@kgdiff/core';
+
+/** The five meaning families of docs/visual-language.md (mirrors `@kgdiff/scene`). */
+export type ChangeFamily = 'added' | 'removed' | 'content' | 'structure' | 'identity';
+
+/**
+ * Family of each hunk kind. Identical to `hunkFamily` in `@kgdiff/scene` (a test enforces it);
+ * duplicated so text outputs do not load the scene and layout modules.
+ */
+export const KIND_FAMILY: Readonly<Record<HunkKind, ChangeFamily>> = {
+  add: 'added',
+  remove: 'removed',
+  merge: 'identity',
+  split: 'identity',
+  relations: 'structure',
+  modify: 'content',
+};
+
+/**
+ * Family a hunk is shown with: its kind's family, except that a `modify` hunk made only of
+ * hierarchy moves (phase `restructure`) is `structure`, as its node is drawn
+ * (docs/visual-language.md: move → structure).
+ */
+export function hunkFamily(hunk: Hunk): ChangeFamily {
+  if (hunk.kind === 'modify' && hunk.phase === 'restructure') return 'structure';
+  return KIND_FAMILY[hunk.kind];
+}
+
+/** One-character glyph of a hunk: `+ − ~ ⇄ ⊕ ⑂`. */
+export function hunkGlyph(hunk: Hunk): string {
+  switch (hunk.kind) {
+    case 'add':
+      return '+';
+    case 'remove':
+      return '−';
+    case 'merge':
+      return '⊕';
+    case 'split':
+      return '⑂';
+    case 'relations':
+      return '⇄';
+    case 'modify':
+      return hunk.phase === 'restructure' ? '⇄' : '~';
+    default:
+      return assertNever(hunk.kind);
+  }
+}
+
+export type NameStatus = 'A' | 'D' | 'M' | 'R' | 'V' | 'G' | 'S' | 'E';
+
+/**
+ * `--name-status` letter: `A` added, `D` removed, `M` modified, `R` renamed, `V` moved,
+ * `G` merged, `S` split, `E` relations. A modify hunk is `R` when its node was renamed, else `V`
+ * when it moved in the hierarchy, else `M`.
+ */
+export function nameStatus(hunk: Hunk, diff: DiffResult): NameStatus {
+  switch (hunk.kind) {
+    case 'add':
+      return 'A';
+    case 'remove':
+      return 'D';
+    case 'merge':
+      return 'G';
+    case 'split':
+      return 'S';
+    case 'relations':
+      return 'E';
+    case 'modify': {
+      const facets = diff.index.node(hunk.anchor)?.facets ?? [];
+      if (facets.some((f) => f.kind === 'rename')) return 'R';
+      if (facets.some((f) => f.kind === 'move')) return 'V';
+      return 'M';
+    }
+    default:
+      return assertNever(hunk.kind);
+  }
+}
+
+/**
+ * Order of the phase groups in hunk lists: the replay order ("clean up, restructure, refine,
+ * grow"), shared with the viewer's change list and the Markdown summary.
+ */
+export const LIST_PHASES: readonly ReplayPhase[] = ['remove', 'restructure', 'modify', 'add'];
+
+/** Order of the counters and the diffstat bar segments. */
+export const COUNTER_PHASES: readonly ReplayPhase[] = ['add', 'remove', 'modify', 'restructure'];
+
+/** Counter glyph and family of each phase. */
+export const PHASE_GLYPH: Readonly<Record<ReplayPhase, string>> = {
+  add: '+',
+  remove: '−',
+  modify: '~',
+  restructure: '⇄',
+};
+
+export const PHASE_FAMILY: Readonly<Record<ReplayPhase, ChangeFamily>> = {
+  add: 'added',
+  remove: 'removed',
+  modify: 'content',
+  restructure: 'structure',
+};
+
+export interface PhaseCount {
+  /** Hunks in the phase. */
+  readonly hunks: number;
+  /** Changed elements (nodes + edges) owned by those hunks. */
+  readonly changes: number;
+}
+
+export interface Overview {
+  readonly phases: Readonly<Record<ReplayPhase, PhaseCount>>;
+  /** Changed elements (every changed node and edge belongs to exactly one hunk). */
+  readonly changes: number;
+  readonly hunks: number;
+}
+
+/** Per-phase hunk and change counts. O(hunks). */
+export function overview(diff: DiffResult): Overview {
+  const phases: Record<ReplayPhase, { hunks: number; changes: number }> = {
+    add: { hunks: 0, changes: 0 },
+    remove: { hunks: 0, changes: 0 },
+    modify: { hunks: 0, changes: 0 },
+    restructure: { hunks: 0, changes: 0 },
+  };
+  let changes = 0;
+  for (const h of diff.hunks) {
+    const n = h.nodes.length + h.edges.length;
+    phases[h.phase].hunks++;
+    phases[h.phase].changes += n;
+    changes += n;
+  }
+  return { phases, changes, hunks: diff.hunks.length };
+}
+
+/** Hunks in list order: grouped by `LIST_PHASES`, each group in review order. */
+export function groupByPhase(hunks: readonly Hunk[]): { phase: ReplayPhase; hunks: Hunk[] }[] {
+  return LIST_PHASES.map((phase) => ({
+    phase,
+    hunks: hunks.filter((h) => h.phase === phase).sort((a, b) => a.order - b.order),
+  })).filter((g) => g.hunks.length > 0);
+}
+
+/**
+ * Split `total` cells among `weights` proportionally (largest remainder); every positive weight
+ * gets at least one cell when `total` allows. Deterministic; ties go to the earlier entry.
+ */
+export function apportion(weights: readonly number[], total: number): number[] {
+  const sum = weights.reduce((a, b) => a + b, 0);
+  if (sum <= 0 || total <= 0) return weights.map(() => 0);
+  const exact = weights.map((w) => (w / sum) * total);
+  const cells = exact.map((x, i) => ((weights[i] as number) > 0 ? Math.max(1, Math.floor(x)) : 0));
+  let used = cells.reduce((a, b) => a + b, 0);
+  const byRemainder = exact
+    .map((x, i) => ({ i, r: x - Math.floor(x) }))
+    .sort((a, b) => b.r - a.r || a.i - b.i);
+  for (let k = 0; used < total && k < byRemainder.length * 2; k++) {
+    const { i } = byRemainder[k % byRemainder.length] as { i: number };
+    if ((weights[i] as number) > 0) {
+      cells[i] = (cells[i] as number) + 1;
+      used++;
+    }
+  }
+  // Minimum cells may overshoot a tiny total: take back from the largest segments.
+  while (used > total) {
+    let largest = 0;
+    for (let i = 1; i < cells.length; i++) {
+      if ((cells[i] as number) > (cells[largest] as number)) largest = i;
+    }
+    cells[largest] = (cells[largest] as number) - 1;
+    used--;
+  }
+  return cells;
+}
+
+export function assertNever(value: never): never {
+  throw new Error(`Unexpected value: ${String(value)}`);
+}

package/src/node-io.ts

@@ -0,0 +1,146 @@
+/**
+ * The real `CliIO`: process streams, the file system, the platform opener and the viewer
+ * bundles resolved from `@kgdiff/viewer/standalone` and `@kgdiff/viewer/standalone/compute`.
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { CliError, systemErrorCode } from './errors.js';
+import type { CliFileSystem, CliIO, ViewerBundle } from './io.js';
+
+async function readStdin(maxBytes: number): Promise<Uint8Array> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : (chunk as Buffer);
+    size += buffer.byteLength;
+    if (size > maxBytes) {
+      process.stdin.destroy();
+      throw new RangeError(`stdin is larger than ${maxBytes} bytes`);
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Atomic replace: write `.<name>.<random>.tmp` next to `path` (exclusive create), copy the
+ * permissions of an existing file, then rename over `path`. The temporary file is removed on
+ * failure.
+ */
+async function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void> {
+  const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    await writeFile(temp, data, { flag: 'wx', mode: 0o666 });
+    const existing = await stat(path).catch(() => undefined);
+    if (existing) await chmod(temp, existing.mode & 0o7777);
+    await rename(temp, path);
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+/** The real file system (exported for tests that exercise links and case variants). */
+export function nodeFileSystem(): CliFileSystem {
+  return {
+    readFile: (path) => readFile(path),
+    writeFile: writeFileAtomic,
+    stat: async (path) => {
+      try {
+        const s = await stat(path);
+        return { dev: s.dev, ino: s.ino, size: s.size };
+      } catch (error) {
+        if (systemErrorCode(error) === 'ENOENT' || systemErrorCode(error) === 'ENOTDIR') {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+    realpath: (path) => realpath(path),
+  };
+}
+
+/** Command that opens a file with the default application on this platform. */
+export function openCommand(
+  platform: NodeJS.Platform,
+  path: string,
+): { command: string; args: string[]; verbatim: boolean } {
+  if (platform === 'darwin') return { command: 'open', args: [path], verbatim: false };
+  if (platform === 'win32') {
+    // `start` takes its first quoted argument as a window title, hence the empty "". With /s,
+    // cmd strips the outer quotes and runs the rest verbatim.
+    return { command: 'cmd', args: ['/d', '/s', '/c', `"start "" "${path}""`], verbatim: true };
+  }
+  return { command: 'xdg-open', args: [path], verbatim: false };
+}
+
+function openFile(path: string): Promise<void> {
+  const { command, args, verbatim } = openCommand(process.platform, path);
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: 'ignore',
+      detached: true,
+      windowsHide: true,
+      windowsVerbatimArguments: verbatim,
+    });
+    child.once('error', reject);
+    child.once('spawn', () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
+
+const VIEWER_SPECIFIERS: Readonly<Record<ViewerBundle, string>> = {
+  main: '@kgdiff/viewer/standalone',
+  compute: '@kgdiff/viewer/standalone/compute',
+};
+
+async function loadViewerBundle(part: ViewerBundle): Promise<string> {
+  const specifier = VIEWER_SPECIFIERS[part];
+  const what = part === 'main' ? 'standalone viewer bundle' : 'viewer compute add-on';
+  const hint =
+    'Build it with `pnpm --filter @kgdiff/viewer build` (development) or reinstall kgdiff.';
+  let path: string;
+  try {
+    path = createRequire(import.meta.url).resolve(specifier);
+  } catch (error) {
+    throw new CliError(
+      'viewer-missing',
+      `The HTML report needs the ${what} (${specifier}), which was not found.`,
+      hint,
+      { cause: error },
+    );
+  }
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    throw new CliError('viewer-missing', `Cannot read the ${what} at ${path}.`, hint, {
+      cause: error,
+    });
+  }
+}
+
+/** `CliIO` bound to the current process. */
+export function nodeIO(): CliIO {
+  return {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    readStdin,
+    fs: nodeFileSystem(),
+    env: process.env,
+    cwd: process.cwd(),
+    isTTY: process.stdout.isTTY === true,
+    stderrIsTTY: process.stderr.isTTY === true,
+    stdinIsTTY: process.stdin.isTTY === true,
+    columns: process.stdout.isTTY ? process.stdout.columns : undefined,
+    now: () => new Date(),
+    makeTempDir: () => mkdtemp(join(tmpdir(), 'kgdiff-')),
+    openFile,
+    loadViewerBundle,
+  };
+}

package/src/output.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared output plumbing of the commands: painters for stdout / stderr, the resolved locale,
+ * `--quiet`, and writing output files with a short notice on stderr.
+ */
+import type { Locale } from '@kgdiff/core';
+import type { CommonOptions } from './args.js';
+import { CliError, systemErrorCode, systemReason } from './errors.js';
+import { resolvePath } from './inputs.js';
+import type { CliIO } from './io.js';
+import { resolveLocale } from './locale.js';
+import { createPainter, isLightBackground, type Painter, resolveColorLevel } from './style.js';
+import { sanitize } from './width.js';
+
+export interface OutputContext {
+  readonly io: CliIO;
+  readonly locale: Locale;
+  /** Painter for stdout. */
+  readonly paint: Painter;
+  /** Painter for stderr. */
+  readonly errPaint: Painter;
+  readonly quiet: boolean;
+  /** Write to stdout unless `--quiet`. */
+  stdout(text: string): void;
+  /** Write a notice or warning to stderr unless `--quiet`. */
+  notice(text: string): void;
+}
+
+export function outputContext(io: CliIO, options: CommonOptions): OutputContext {
+  const light = isLightBackground(io.env);
+  return {
+    io,
+    locale: resolveLocale(options.locale, io.env),
+    paint: createPainter(resolveColorLevel(options.color, io.env, io.isTTY), light),
+    errPaint: createPainter(resolveColorLevel(options.color, io.env, io.stderrIsTTY), light),
+    quiet: options.quiet,
+    stdout: (text) => {
+      if (!options.quiet && text) io.stdout.write(text);
+    },
+    notice: (text) => {
+      if (!options.quiet) io.stderr.write(text);
+    },
+  };
+}
+
+/** `1.2 MB`, `512 kB`, `90 B` (decimal units, like most file managers). */
+export function formatSize(bytes: number): string {
+  if (bytes < 1000) return `${bytes} B`;
+  if (bytes < 1_000_000) return `${(bytes / 1000).toFixed(bytes < 10_000 ? 1 : 0)} kB`;
+  return `${(bytes / 1_000_000).toFixed(1)} MB`;
+}
+
+const WRITE_HINTS: Readonly<Record<string, string>> = {
+  ENOENT: 'Create the directory first.',
+  EISDIR: 'Pass a file name, not a directory.',
+  EACCES: 'Check the permissions of the directory.',
+};
+
+/** Write an output file and report it on stderr (`✓ Wrote report.html (1.2 MB)`). */
+export async function writeOutputFile(
+  ctx: OutputContext,
+  path: string,
+  content: string,
+  label: string,
+): Promise<void> {
+  const data = new TextEncoder().encode(content);
+  try {
+    await ctx.io.fs.writeFile(resolvePath(ctx.io, path), data);
+  } catch (error) {
+    const code = systemErrorCode(error);
+    throw new CliError(
+      'output',
+      `Cannot write ${label} to "${sanitize(path)}": ${systemReason(error)}.`,
+      (code && WRITE_HINTS[code]) || undefined,
+      { cause: error },
+    );
+  }
+  const p = ctx.errPaint;
+  ctx.notice(
+    `${p.tone('added', '✓')} Wrote ${label} ${p.bold(sanitize(path))} ${p.dim(`(${formatSize(data.byteLength)})`)}\n`,
+  );
+}

package/src/overwrite.ts

@@ -0,0 +1,75 @@
+/**
+ * Outputs never overwrite inputs, and two outputs never share a file — under any spelling:
+ * case variants on case-insensitive file systems, symlinks and hard links all resolve to the
+ * same (device, inode) pair; files that do not exist yet compare by canonical directory and
+ * case-folded name.
+ */
+import { basename, dirname, join } from 'node:path';
+import { STDIO } from './args.js';
+import { CliError } from './errors.js';
+import { resolvePath } from './inputs.js';
+import type { CliIO } from './io.js';
+import { sanitize } from './width.js';
+
+export interface PathRole {
+  /** How the path was given, for messages (`<before>`, `--json`, `-o`). */
+  readonly role: string;
+  /** Path as given; `-` (stdin / stdout) and `undefined` are ignored. */
+  readonly path: string | undefined;
+}
+
+/** Identity of the file at `path`: `inode:dev:ino` when it exists, else a canonical path. */
+export async function fileIdentity(io: CliIO, path: string): Promise<string> {
+  const absolute = resolvePath(io, path);
+  const stat = await io.fs.stat(absolute);
+  if (stat) return `inode:${stat.dev}:${stat.ino}`;
+  let directory = dirname(absolute);
+  try {
+    directory = await io.fs.realpath(directory);
+  } catch {
+    // A missing directory makes the write fail later with its own message.
+  }
+  // Case-folded: on case-insensitive file systems `A.json` and `a.json` are one file. On
+  // case-sensitive ones this can only refuse two outputs that differ in case alone.
+  return `path:${join(directory, basename(absolute)).toLowerCase()}`;
+}
+
+/**
+ * @throws CliError `usage` when an output is one of the inputs or two outputs are one file.
+ */
+export async function checkNoOverwrite(
+  io: CliIO,
+  inputs: readonly PathRole[],
+  outputs: readonly PathRole[],
+): Promise<void> {
+  const used = (p: PathRole): p is PathRole & { path: string } =>
+    p.path !== undefined && p.path !== STDIO;
+  const inputIds = new Map<string, PathRole>();
+  for (const input of inputs.filter(used)) {
+    // Missing inputs are reported when they are read.
+    if (await io.fs.stat(resolvePath(io, input.path))) {
+      inputIds.set(await fileIdentity(io, input.path), input);
+    }
+  }
+  const outputIds = new Map<string, PathRole>();
+  for (const output of outputs.filter(used)) {
+    const id = await fileIdentity(io, output.path);
+    const input = inputIds.get(id);
+    if (input) {
+      throw new CliError(
+        'usage',
+        `${output.role} "${sanitize(output.path)}" is the input ${input.role} "${sanitize(input.path as string)}"; kgdiff never overwrites its inputs.`,
+        'Write to another file, then move it into place if you want to replace the input.',
+      );
+    }
+    const other = outputIds.get(id);
+    if (other) {
+      throw new CliError(
+        'usage',
+        `${other.role} and ${output.role} both write to "${sanitize(output.path)}".`,
+        'Give each output its own file.',
+      );
+    }
+    outputIds.set(id, output);
+  }
+}

package/src/report.ts

@@ -0,0 +1,101 @@
+/**
+ * Build the `ReportPayload` embedded in HTML reports: diff (`diffToJSON`) + layout
+ * (`layoutToJSON`) + meta + initial view preferences. `@kgdiff/layout` and `node:zlib` are
+ * loaded on demand, so text outputs never pay for them.
+ */
+import { type DiffResult, diffToJSON, type Locale } from '@kgdiff/core';
+import type { ReportPayload, ThemePreference, ViewerMode } from '@kgdiff/viewer';
+import { renderReportHtml } from './html.js';
+
+export interface ReportInfo {
+  readonly title: string;
+  /** e.g. `kgdiff 0.1.0`. */
+  readonly generator: string;
+  /** ISO timestamp; omitted for reproducible reports. */
+  readonly generatedAt?: string;
+  readonly before: { readonly name: string; readonly format?: string };
+  readonly after: { readonly name: string; readonly format?: string };
+  readonly view: {
+    readonly mode?: ViewerMode;
+    readonly theme?: ThemePreference;
+    readonly locale: Locale;
+  };
+}
+
+/** Lay out the diff and assemble the payload. Deterministic apart from `generatedAt`. */
+export async function buildReportPayload(
+  diff: DiffResult,
+  info: ReportInfo,
+): Promise<ReportPayload> {
+  const { layoutDiff, layoutToJSON } = await import('@kgdiff/layout');
+  const layout = layoutToJSON(layoutDiff(diff));
+  const { mode, theme, locale } = info.view;
+  return {
+    format: 'kgdiff.report',
+    version: 1,
+    diff: diffToJSON(diff),
+    layout,
+    meta: {
+      title: info.title,
+      generator: info.generator,
+      ...(info.generatedAt !== undefined ? { generatedAt: info.generatedAt } : {}),
+      before: info.before,
+      after: info.after,
+    },
+    view: {
+      ...(mode !== undefined ? { mode } : {}),
+      ...(theme !== undefined ? { theme } : {}),
+      locale,
+    },
+  };
+}
+
+/**
+ * Deterministic gzip (level 9). The header's OS byte is normalized to 255 ("unknown") so the
+ * bytes do not depend on the platform the report was generated on.
+ */
+export async function createGzip(): Promise<(data: Uint8Array) => Uint8Array> {
+  const { gzipSync, constants } = await import('node:zlib');
+  return (data) => {
+    const out = gzipSync(data, { level: constants.Z_BEST_COMPRESSION });
+    out[9] = 0xff;
+    return out;
+  };
+}
+
+/**
+ * Whether a report should inline the compute add-on: only when the layout covers just the
+ * changes (large graphs), where the viewer may need to lay out collapsed groups the user
+ * expands. Full layouts need no browser-side computation, so small reports stay small.
+ */
+export function needsCompute(payload: ReportPayload): boolean {
+  return payload.layout.scope === 'changes';
+}
+
+export interface ReportBundles {
+  /** The standalone viewer bundle. */
+  readonly main: string;
+  /**
+   * Loads the compute add-on; called only when `needsCompute`. Returning `undefined` (e.g.
+   * `--no-compute`) leaves it out.
+   */
+  readonly compute: () => Promise<string | undefined>;
+}
+
+/** Full HTML document for a diff. */
+export async function buildReportHtml(
+  diff: DiffResult,
+  info: ReportInfo,
+  bundles: ReportBundles,
+  description: string,
+): Promise<string> {
+  const payload = await buildReportPayload(diff, info);
+  const compute = needsCompute(payload) ? await bundles.compute() : undefined;
+  return renderReportHtml({
+    payload,
+    bundle: bundles.main,
+    ...(compute !== undefined ? { compute } : {}),
+    description,
+    gzip: await createGzip(),
+  });
+}