@kgdiff/cli 0.0.0-stage → 0.2.0

package/src/inputs.ts

@@ -0,0 +1,269 @@
+/**
+ * Reading inputs: files or stdin, gzip-compressed or not, UTF-8 / UTF-16 text, parsed with
+ * `@kgdiff/formats`. Failures become `CliError`s that name the file and suggest a fix.
+ */
+import { basename, resolve } from 'node:path';
+import { type FormatId, type ParseOptions, type ParseResult, parseGraph } from '@kgdiff/formats';
+import { FORMATS, STDIO } from './args.js';
+import { CliError, isKgdiffError, systemErrorCode, systemReason } from './errors.js';
+import type { CliIO } from './io.js';
+import type { Env } from './style.js';
+import { sanitize } from './width.js';
+
+export const FORMAT_NAMES: Readonly<Record<FormatId, string>> = {
+  json: 'JSON',
+  jsonld: 'JSON-LD',
+  turtle: 'Turtle',
+  ntriples: 'N-Triples',
+  nquads: 'N-Quads',
+  trig: 'TriG',
+  rdfxml: 'RDF/XML',
+  obo: 'OBO',
+};
+
+export interface RawInput {
+  /** How the input is called in messages: the path as given, or `stdin`. */
+  readonly display: string;
+  /** File name without directories and without `.gz` (format detection, `meta.source`). */
+  readonly filename?: string;
+  readonly text: string;
+  /** True for empty or whitespace-only input (only returned with `allowEmpty`). */
+  readonly empty: boolean;
+}
+
+const READ_HINTS: Readonly<Record<string, string>> = {
+  ENOENT: 'Check the path. Use - to read from stdin.',
+  EISDIR: 'Pass a file, not a directory.',
+  EACCES: 'Check the file permissions.',
+};
+
+/** Resolve a user-supplied path against the IO's working directory. */
+export function resolvePath(io: CliIO, path: string): string {
+  return resolve(io.cwd, path);
+}
+
+/** Default input size limit (bytes, after decompression): 1 GiB. */
+export const DEFAULT_MAX_INPUT = 1024 ** 3;
+
+const SIZE_UNITS: Readonly<Record<string, number>> = { '': 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3 };
+
+/**
+ * Input size limit: `KGDIFF_MAX_INPUT` (bytes, or with a binary `K` / `M` / `G` suffix, e.g.
+ * `4G`), else `DEFAULT_MAX_INPUT`. Applies to files, stdin and decompressed gzip data.
+ *
+ * @throws CliError `usage` for an unreadable value.
+ */
+export function maxInputBytes(env: Env): number {
+  const raw = env.KGDIFF_MAX_INPUT?.trim();
+  if (!raw) return DEFAULT_MAX_INPUT;
+  const match = /^(\d+(?:\.\d+)?)\s*([kmg]?)i?b?$/i.exec(raw);
+  const value = match ? Number(match[1]) * (SIZE_UNITS[(match[2] ?? '').toLowerCase()] ?? 1) : NaN;
+  if (!Number.isFinite(value) || value < 1) {
+    throw new CliError(
+      'usage',
+      `Invalid KGDIFF_MAX_INPUT "${sanitize(raw)}".`,
+      'Use a byte count such as 2147483648, or 512M / 2G.',
+    );
+  }
+  return Math.floor(value);
+}
+
+function formatBytes(bytes: number): string {
+  for (const [unit, size] of [
+    ['GiB', 1024 ** 3],
+    ['MiB', 1024 ** 2],
+    ['KiB', 1024],
+  ] as const) {
+    if (bytes >= size) return `${Number((bytes / size).toFixed(1))} ${unit}`;
+  }
+  return `${bytes} B`;
+}
+
+function tooLarge(where: string, limit: number, cause?: unknown): CliError {
+  return new CliError(
+    'input',
+    `${where} is too large: the input limit is ${formatBytes(limit)}.`,
+    'If the input is genuine, raise the limit with KGDIFF_MAX_INPUT (e.g. KGDIFF_MAX_INPUT=4G).',
+    cause === undefined ? undefined : { cause },
+  );
+}
+
+function isTooLarge(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code;
+  return (
+    error instanceof RangeError ||
+    code === 'ERR_BUFFER_TOO_LARGE' ||
+    code === 'ERR_FS_FILE_TOO_LARGE' ||
+    code === 'ERR_STRING_TOO_LONG'
+  );
+}
+
+/**
+ * Decode input bytes: gunzip when gzip-compressed (output capped at `limit`, so a gzip bomb is
+ * an error, not an out-of-memory crash), UTF-16 by BOM, else strict UTF-8.
+ */
+export async function decodeText(bytes: Uint8Array, where: string, limit: number): Promise<string> {
+  let data = bytes;
+  if (data[0] === 0x1f && data[1] === 0x8b) {
+    const { gunzipSync } = await import('node:zlib');
+    try {
+      data = gunzipSync(data, { maxOutputLength: limit });
+    } catch (error) {
+      if (isTooLarge(error)) throw tooLarge(`${where} (decompressed)`, limit, error);
+      throw new CliError(
+        'input',
+        `Cannot decompress ${where}: ${systemReason(error)}.`,
+        undefined,
+        {
+          cause: error,
+        },
+      );
+    }
+  }
+  const encoding =
+    data[0] === 0xff && data[1] === 0xfe
+      ? 'utf-16le'
+      : data[0] === 0xfe && data[1] === 0xff
+        ? 'utf-16be'
+        : 'utf-8';
+  try {
+    return new TextDecoder(encoding, { fatal: true }).decode(data);
+  } catch (error) {
+    if (isTooLarge(error)) throw tooLarge(where, limit, error);
+    throw new CliError(
+      'input',
+      `${where} is not valid ${encoding.toUpperCase()} text.`,
+      `kgdiff reads text formats (${Object.values(FORMAT_NAMES).join(', ')}). Convert binary formats first.`,
+      { cause: error },
+    );
+  }
+}
+
+export interface ReadOptions {
+  /** Accept an empty (or whitespace-only) input as an empty graph (`--allow-empty`). */
+  readonly allowEmpty?: boolean;
+  /** Hint shown when the input is empty and that is not allowed. */
+  readonly emptyHint?: string;
+}
+
+/**
+ * Read a file (or stdin for `-`) as text. `role` names the argument in messages. Inputs above
+ * the size limit, and empty inputs unless `allowEmpty`, are errors.
+ */
+export async function readInput(
+  io: CliIO,
+  path: string,
+  role: string,
+  options: ReadOptions = {},
+): Promise<RawInput> {
+  const limit = maxInputBytes(io.env);
+  let raw: { display: string; where: string; filename?: string; bytes: Uint8Array };
+  if (path === STDIO) {
+    if (io.stdinIsTTY) {
+      io.stderr.write(`Reading ${role} from stdin… (end with Ctrl-D)\n`);
+    }
+    let bytes: Uint8Array;
+    try {
+      bytes = await io.readStdin(limit);
+    } catch (error) {
+      if (isTooLarge(error)) throw tooLarge(`${role} (stdin)`, limit, error);
+      throw error;
+    }
+    raw = { display: 'stdin', where: `${role} (stdin)`, bytes };
+  } else {
+    const display = sanitize(path);
+    const where = `${role} "${display}"`;
+    const absolute = resolvePath(io, path);
+    let bytes: Uint8Array;
+    try {
+      const size = (await io.fs.stat(absolute))?.size;
+      if (size !== undefined && size > limit) throw tooLarge(where, limit);
+      bytes = await io.fs.readFile(absolute);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (isTooLarge(error)) throw tooLarge(where, limit, error);
+      const code = systemErrorCode(error);
+      throw new CliError(
+        'input',
+        `Cannot read ${where}: ${systemReason(error)}.`,
+        (code && READ_HINTS[code]) || undefined,
+        { cause: error },
+      );
+    }
+    raw = { display, where, filename: basename(path).replace(/\.gz$/i, ''), bytes };
+  }
+  const text = await decodeText(raw.bytes, raw.where, limit);
+  const empty = text.trim() === '';
+  if (empty && !options.allowEmpty) {
+    throw new CliError(
+      'input',
+      `${raw.where} is empty.`,
+      options.emptyHint ??
+        (path === STDIO
+          ? 'Did the command before the pipe fail? Pass --allow-empty if an empty graph is intended.'
+          : 'Pass --allow-empty to compare with an empty graph (e.g. before a first release).'),
+    );
+  }
+  return {
+    display: raw.display,
+    ...(raw.filename !== undefined ? { filename: raw.filename } : {}),
+    text,
+    empty,
+  };
+}
+
+/**
+ * Read two inputs concurrently; when both fail, the first one's error is reported (so the
+ * message does not depend on which read finished first).
+ */
+export async function readPair(
+  first: Promise<RawInput>,
+  second: Promise<RawInput>,
+): Promise<[RawInput, RawInput]> {
+  const [a, b] = await Promise.allSettled([first, second]);
+  if (a.status === 'rejected') throw a.reason;
+  if (b.status === 'rejected') throw b.reason;
+  return [a.value, b.value];
+}
+
+export interface GraphParseOptions {
+  readonly format: FormatId | 'auto';
+  readonly languages?: readonly string[];
+  /** Flag that overrides the format of this input, for hints (`--before-format`). */
+  readonly formatFlag: string;
+}
+
+/** Parse a graph, turning parser errors into messages that name the input. */
+export function parseInput(input: RawInput, options: GraphParseOptions): ParseResult {
+  const parseOptions: ParseOptions = {
+    format: options.format,
+    ...(input.filename !== undefined ? { filename: input.filename } : {}),
+    ...(options.languages ? { rdf: { languages: options.languages } } : {}),
+  };
+  if (input.empty) {
+    // --allow-empty: an empty graph, without asking a parser to guess the format of nothing.
+    return parseGraph('{"nodes":[],"edges":[]}', { ...parseOptions, format: 'json' });
+  }
+  try {
+    return parseGraph(input.text, parseOptions);
+  } catch (error) {
+    if (!isKgdiffError(error)) throw error;
+    const where = input.display === 'stdin' ? 'stdin' : `"${input.display}"`;
+    const undetected = /could not detect the format/i.test(error.message);
+    const message = undetected
+      ? `Cannot tell the format of ${where}.`
+      : `${where}: ${error.message.replace(/\.$/, '')}.`;
+    const formats = FORMATS.filter((format) => format !== 'auto').join(', ');
+    // A kgdiff file names its own format and version: another --format cannot help.
+    const marked = error.code === 'unsupported-version';
+    const newer = marked && typeof error.details?.version === 'number' && error.details.version > 1;
+    const hint = undetected
+      ? `Pass ${options.formatFlag} <fmt> (${formats}) or use a known file extension.`
+      : newer
+        ? 'Upgrade kgdiff: npm install -g @kgdiff/cli@latest.'
+        : options.format === 'auto' && !marked
+          ? `If the format was detected wrongly, pass ${options.formatFlag} <fmt> (${formats}).`
+          : undefined;
+    throw new CliError('input', message, hint, { cause: error });
+  }
+}

package/src/io.ts

@@ -0,0 +1,68 @@
+/**
+ * Everything the CLI needs from the outside world, injected so that `main` runs in-process in
+ * tests (fake streams, in-memory files, fixed clock) and for real in `bin.ts` (`nodeIO`).
+ */
+import type { Env } from './style.js';
+
+/** The standalone viewer bundles an HTML report can inline. */
+export type ViewerBundle = 'main' | 'compute';
+
+/** A writable text stream (stdout / stderr). */
+export interface OutputStream {
+  write(chunk: string): void;
+}
+
+/** What overwrite checks need to know about an existing file. */
+export interface FileStat {
+  /** Device and inode: equal for the same file under any name (case variant, link). */
+  readonly dev: number;
+  readonly ino: number;
+  readonly size: number;
+}
+
+export interface CliFileSystem {
+  /** Read a whole file. Rejects with a Node-style error (`code`: ENOENT, EISDIR, EACCES…). */
+  readFile(path: string): Promise<Uint8Array>;
+  /**
+   * Create or replace a file atomically: write a temporary file in the same directory, then
+   * rename it over `path` (readers never see a half-written file; a symlink at `path` is
+   * replaced, not written through).
+   */
+  writeFile(path: string, data: string | Uint8Array): Promise<void>;
+  /** Stat following symlinks; `undefined` when nothing exists at `path`. */
+  stat(path: string): Promise<FileStat | undefined>;
+  /** Canonical absolute path (symlinks resolved). Rejects when `path` does not exist. */
+  realpath(path: string): Promise<string>;
+}
+
+export interface CliIO {
+  readonly stdout: OutputStream;
+  readonly stderr: OutputStream;
+  /** Read all of stdin; rejects with a `RangeError` beyond `maxBytes`. */
+  readStdin(maxBytes: number): Promise<Uint8Array>;
+  readonly fs: CliFileSystem;
+  readonly env: Env;
+  /** Directory relative paths are resolved against. */
+  readonly cwd: string;
+  /** Whether stdout is a terminal. */
+  readonly isTTY: boolean;
+  /** Whether stderr is a terminal (colors of errors and notices). */
+  readonly stderrIsTTY: boolean;
+  /** Whether stdin is a terminal (nothing piped in). */
+  readonly stdinIsTTY: boolean;
+  /** Terminal width of stdout, when known. */
+  readonly columns: number | undefined;
+  /** Clock for `generatedAt` in HTML reports. */
+  now(): Date;
+  /** Create a fresh private directory (`mkdtemp`) for reports opened with `--open` and no `-o`. */
+  makeTempDir(): Promise<string>;
+  /** Open a file with the platform's default application (the browser, for HTML). */
+  openFile(path: string): Promise<void>;
+  /**
+   * Source of a standalone viewer bundle: `main` (`@kgdiff/viewer/standalone`, the
+   * `<kgdiff-viewer>` element) or `compute` (`@kgdiff/viewer/standalone/compute`, the optional
+   * diff / layout add-on). Rejects with a `CliError` (`viewer-missing`) when it is not built or
+   * not installed.
+   */
+  loadViewerBundle(part: ViewerBundle): Promise<string>;
+}

package/src/locale.ts

@@ -0,0 +1,177 @@
+/**
+ * Locale selection and the CLI's own strings (summary, stat, Markdown). Hunk titles come from
+ * `@kgdiff/core`'s `formatHunk`; errors and notices on stderr stay in English so they can be
+ * searched for.
+ */
+import type { Locale, ReplayPhase } from '@kgdiff/core';
+import type { ChangeFamily } from './model.js';
+import type { Env } from './style.js';
+
+export const LOCALES: readonly Locale[] = ['en', 'zh-CN'];
+
+/**
+ * Map a locale tag or POSIX locale (`zh_CN.UTF-8`, `zh-Hant`, `en_US`, `C`) to a supported
+ * locale: any Chinese tag → `zh-CN`, any English or POSIX tag → `en`, anything else `undefined`.
+ */
+export function matchLocale(tag: string): Locale | undefined {
+  const t = tag
+    .trim()
+    .toLowerCase()
+    .replace(/[.@].*$/, '')
+    .replace(/_/g, '-');
+  if (t === 'zh' || t.startsWith('zh-') || t === 'cn') return 'zh-CN';
+  if (t === 'en' || t.startsWith('en-') || t === 'c' || t === 'posix') return 'en';
+  return undefined;
+}
+
+/**
+ * The locale to use: `--locale` when given, else the first non-empty of `LC_ALL`, `LC_MESSAGES`,
+ * `LANG` (POSIX precedence), mapped with `matchLocale`; `en` when nothing matches.
+ */
+export function resolveLocale(flag: Locale | undefined, env: Env): Locale {
+  if (flag) return flag;
+  for (const name of ['LC_ALL', 'LC_MESSAGES', 'LANG'] as const) {
+    const value = env[name];
+    if (value) return matchLocale(value) ?? 'en';
+  }
+  return 'en';
+}
+
+/** Thousands separators without `Intl`, so output never depends on the runtime's ICU data. */
+export function formatInt(n: number): string {
+  return String(Math.trunc(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+export interface Messages {
+  /** Group headings, by replay phase. */
+  readonly phase: Readonly<Record<ReplayPhase, string>>;
+  /** Counter labels (`+3 added`), by replay phase. */
+  readonly counter: Readonly<Record<ReplayPhase, string>>;
+  readonly family: Readonly<Record<ChangeFamily, string>>;
+  /** `179 → 184 nodes · 351 → 353 edges`; one number when a count did not change. */
+  readonly totals: (nodes: Count, edges: Count) => string;
+  readonly changes: (changes: number, hunks: number) => string;
+  readonly more: (n: number) => string;
+  readonly moreHint: string;
+  readonly identical: string;
+  readonly identicalDetail: (nodes: number, edges: number) => string;
+  readonly table: {
+    readonly nodes: string;
+    readonly edges: string;
+    readonly added: string;
+    readonly removed: string;
+    readonly modified: string;
+    readonly unchanged: string;
+    readonly total: string;
+  };
+  readonly byType: string;
+  readonly untyped: string;
+  readonly moreTypes: (n: number) => string;
+  readonly markdown: {
+    readonly legend: string;
+    readonly more: (n: number) => string;
+    readonly generatedBy: (generator: string) => string;
+  };
+}
+
+/** A count before and after the change. */
+export type Count = readonly [before: number, after: number];
+
+const plural = (n: number, one: string, many: string): string =>
+  `${formatInt(n)} ${n === 1 ? one : many}`;
+
+/** `179 → 184`, or `74` when unchanged. */
+export function formatCount([before, after]: Count): string {
+  return before === after ? formatInt(after) : `${formatInt(before)} → ${formatInt(after)}`;
+}
+
+const en: Messages = {
+  phase: {
+    restructure: 'Restructured',
+    modify: 'Modified',
+    add: 'Added',
+    remove: 'Removed',
+  },
+  counter: { add: 'added', remove: 'removed', modify: 'modified', restructure: 'restructured' },
+  family: {
+    added: 'added',
+    removed: 'removed',
+    content: 'content',
+    structure: 'structure',
+    identity: 'identity',
+  },
+  // The noun agrees with the number next to it (the after count): `1 node`, `2 → 1 node`.
+  totals: (nodes, edges) =>
+    `${formatCount(nodes)} ${nodes[1] === 1 ? 'node' : 'nodes'} · ` +
+    `${formatCount(edges)} ${edges[1] === 1 ? 'edge' : 'edges'}`,
+  changes: (changes, hunks) =>
+    `${plural(changes, 'change', 'changes')} in ${plural(hunks, 'hunk', 'hunks')}`,
+  more: (n) => `… and ${formatInt(n)} more`,
+  moreHint: '--limit 0 lists all',
+  identical: 'No differences',
+  identicalDetail: (nodes, edges) =>
+    `Both versions have ${plural(nodes, 'node', 'nodes')} and ${plural(edges, 'edge', 'edges')}.`,
+  table: {
+    nodes: 'nodes',
+    edges: 'edges',
+    added: 'added',
+    removed: 'removed',
+    modified: 'modified',
+    unchanged: 'unchanged',
+    total: 'before → after',
+  },
+  byType: 'By type',
+  untyped: '(untyped)',
+  moreTypes: (n) => `… and ${plural(n, 'more type', 'more types')}`,
+  markdown: {
+    legend:
+      '🟩 added · 🟥 removed · 🟨 content (renames, attributes, types, synonyms) · ' +
+      '🟦 structure (moves, relations) · 🟪 identity (merges, splits)',
+    more: (n) =>
+      `…and ${plural(n, 'more hunk', 'more hunks')}. Open the HTML report for the full list.`,
+    generatedBy: (generator) => `Generated by ${generator}`,
+  },
+};
+
+const zh: Messages = {
+  phase: { restructure: '结构调整', modify: '修改', add: '新增', remove: '删除' },
+  counter: { add: '新增', remove: '删除', modify: '修改', restructure: '结构调整' },
+  family: {
+    added: '新增',
+    removed: '删除',
+    content: '内容',
+    structure: '结构',
+    identity: '身份',
+  },
+  totals: (nodes, edges) => `节点 ${formatCount(nodes)} · 关系 ${formatCount(edges)}`,
+  changes: (changes, hunks) => `${formatInt(hunks)} 组共 ${formatInt(changes)} 处变化`,
+  more: (n) => `… 另有 ${formatInt(n)} 组`,
+  moreHint: '--limit 0 显示全部',
+  identical: '没有差异',
+  identicalDetail: (nodes, edges) =>
+    `两个版本均有 ${formatInt(nodes)} 个节点、${formatInt(edges)} 条关系。`,
+  table: {
+    nodes: '节点',
+    edges: '关系',
+    added: '新增',
+    removed: '删除',
+    modified: '修改',
+    unchanged: '未变',
+    total: '变更前 → 变更后',
+  },
+  byType: '按类型',
+  untyped: '（无类型）',
+  moreTypes: (n) => `… 另有 ${formatInt(n)} 个类型`,
+  markdown: {
+    legend:
+      '🟩 新增 · 🟥 删除 · 🟨 内容（改名、属性、类型、别名） · 🟦 结构（移动、关系） · 🟪 身份（合并、拆分、换 ID）',
+    more: (n) => `……另有 ${formatInt(n)} 组变更未列出，完整列表请查看 HTML 报告。`,
+    generatedBy: (generator) => `由 ${generator} 生成`,
+  },
+};
+
+const MESSAGES: Readonly<Record<Locale, Messages>> = { en, 'zh-CN': zh };
+
+export function messages(locale: Locale): Messages {
+  return MESSAGES[locale];
+}

package/src/main.ts

@@ -0,0 +1,56 @@
+/**
+ * Entry point logic: parse the command line, dispatch, map every failure to a friendly message
+ * on stderr and an exit code. Commands are loaded on demand so `--help` and `--version` never
+ * load the diff engine.
+ */
+import { parseCommandLine, peekColorMode } from './args.js';
+import { debugEnabled, formatError } from './errors.js';
+import { renderHelp } from './help.js';
+import type { CliIO } from './io.js';
+import { createPainter, isLightBackground, resolveColorLevel } from './style.js';
+import { cliVersion } from './version.js';
+
+/**
+ * Run the CLI with `argv` (without `node` and the script path).
+ *
+ * Exit codes: 0 success (and no differences with `--exit-code`), 1 differences with
+ * `--exit-code`, 2 usage or input error (message on stderr; stack trace only with
+ * `DEBUG=kgdiff`). Never throws.
+ */
+export async function main(argv: readonly string[], io: CliIO): Promise<number> {
+  const light = isLightBackground(io.env);
+  try {
+    const command = parseCommandLine(argv);
+    switch (command.kind) {
+      case 'help': {
+        const paint = createPainter(resolveColorLevel(command.color, io.env, io.isTTY), light);
+        io.stdout.write(
+          renderHelp(command.topic, cliVersion(), paint, io.isTTY && io.columns ? io.columns : 80),
+        );
+        return 0;
+      }
+      case 'version':
+        io.stdout.write(`kgdiff ${cliVersion()}\n`);
+        return 0;
+      case 'diff': {
+        const { runDiff } = await import('./diff-command.js');
+        return await runDiff(command.options, io);
+      }
+      case 'apply': {
+        const { runApply } = await import('./apply-command.js');
+        return await runApply(command.options, io);
+      }
+      default: {
+        const exhaustive: never = command;
+        throw new Error(`Unknown command ${JSON.stringify(exhaustive)}`);
+      }
+    }
+  } catch (error) {
+    const paint = createPainter(
+      resolveColorLevel(peekColorMode(argv), io.env, io.stderrIsTTY),
+      light,
+    );
+    io.stderr.write(formatError(error, paint, debugEnabled(io.env.DEBUG)));
+    return 2;
+  }
+}

package/src/markdown.ts

@@ -0,0 +1,119 @@
+/**
+ * GitHub-flavoured Markdown summary for PR comments and `$GITHUB_STEP_SUMMARY`
+ * (docs/cli.md §Markdown summary): title, diffstat table, family legend and the hunk list
+ * grouped by phase in `<details>` blocks. No HTML beyond `<details>` / `<summary>`.
+ */
+import { type DiffResult, formatHunk, type Locale } from '@kgdiff/core';
+import { formatInt, messages } from './locale.js';
+import { type ChangeFamily, groupByPhase, hunkFamily, hunkGlyph, overview } from './model.js';
+import { totalsText } from './summary.js';
+import { revealInvisible } from './width.js';
+
+/** Hunks listed before "…and N more". */
+export const MARKDOWN_HUNK_LIMIT = 100;
+/** Groups start expanded when the whole list is at most this long. */
+const OPEN_THRESHOLD = 30;
+
+const FAMILY_SQUARE: Readonly<Record<ChangeFamily, string>> = {
+  added: '🟩',
+  removed: '🟥',
+  content: '🟨',
+  structure: '🟦',
+  identity: '🟪',
+};
+
+/** Zero-width space: invisible, but enough to stop GitHub's autolinkers and filters. */
+const ZWSP = '\u200B';
+
+/**
+ * Escape untrusted text for inline GFM.
+ *
+ * 1. Invisible and bidirectional controls become a visible `⟨U+202E⟩`; C0 controls and line
+ *    breaks become spaces; C1 controls are dropped.
+ * 2. GitHub's post-Markdown filters are defused first (they act on the rendered text, so
+ *    escaping alone does not stop them): a zero-width space breaks `:shortcode:` emoji,
+ *    `@mentions`, `#123` / `org/repo#123` / `GH-123` references, bare `scheme://` URLs and
+ *    `www.` autolinks.
+ * 3. Markdown punctuation (backslash, backtick, `*`, `_`, brackets, `|`, `~`, `#`, `$` for math)
+ *    is backslash-escaped; `<`, `>` and `&` become entities, so no raw HTML gets through.
+ */
+export function escapeMarkdown(text: string): string {
+  return (
+    revealInvisible(text)
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are replaced on purpose.
+      .replace(/[\u0000-\u001f\u2028\u2029]+/g, ' ')
+      .replace(/[\u007f-\u009f]/g, '')
+      .replace(/:([a-z0-9_+-]+):/gi, `:${ZWSP}$1:`)
+      .replace(/\b(GH)-(?=\d)/gi, `$1${ZWSP}-`)
+      .replace(/([@#])(?=[\p{L}\p{N}_])/gu, `$1${ZWSP}`)
+      .replace(/:\/\//g, `://${ZWSP}`)
+      .replace(/\b(www)\./gi, `$1${ZWSP}.`)
+      .replace(/[\\`*_[\]|~#$]/g, '\\$&')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .trim()
+  );
+}
+
+export interface MarkdownOptions {
+  readonly locale: Locale;
+  readonly title: string;
+  /** e.g. `kgdiff 0.1.0`. */
+  readonly generator: string;
+}
+
+/** Render the Markdown summary. Deterministic: no timestamps. */
+export function renderMarkdown(diff: DiffResult, options: MarkdownOptions): string {
+  const m = messages(options.locale);
+  const ov = overview(diff);
+  const out: string[] = [`## kgdiff · ${escapeMarkdown(options.title)}`, ''];
+  const totals = escapeMarkdown(totalsText(diff, m));
+
+  if (ov.hunks === 0) {
+    const detail = m.identicalDetail(diff.stats.after.nodes, diff.stats.after.edges);
+    out.push(`✅ **${m.identical}.** ${escapeMarkdown(detail)}`, '');
+  } else {
+    out.push(`**${escapeMarkdown(m.changes(ov.changes, ov.hunks))}** · ${totals}`, '');
+    // Table cells are sentence-cased (a no-op for Chinese).
+    const t = Object.fromEntries(
+      Object.entries(m.table).map(([k, v]) => [k, v.charAt(0).toUpperCase() + v.slice(1)]),
+    ) as typeof m.table;
+    const { nodes, edges, before, after } = diff.stats;
+    const pair = (b: number, a: number): string => `${formatInt(b)} → ${formatInt(a)}`;
+    out.push(
+      `| | ${t.added} | ${t.removed} | ${t.modified} | ${t.unchanged} | ${t.total} |`,
+      '| :-- | --: | --: | --: | --: | --: |',
+      `| **${t.nodes}** | ${formatInt(nodes.added)} | ${formatInt(nodes.removed)} | ${formatInt(nodes.modified)} | ${formatInt(nodes.unchanged)} | ${pair(before.nodes, after.nodes)} |`,
+      `| **${t.edges}** | ${formatInt(edges.added)} | ${formatInt(edges.removed)} | ${formatInt(edges.modified)} | ${formatInt(edges.unchanged)} | ${pair(before.edges, after.edges)} |`,
+      '',
+      m.markdown.legend,
+      '',
+    );
+    let budget = MARKDOWN_HUNK_LIMIT;
+    const open = ov.hunks <= OPEN_THRESHOLD ? ' open' : '';
+    for (const group of groupByPhase(diff.hunks)) {
+      if (budget <= 0) break;
+      const listed = group.hunks.slice(0, budget);
+      budget -= listed.length;
+      out.push(
+        `<details${open}>`,
+        `<summary>${m.phase[group.phase]} (${formatInt(group.hunks.length)})</summary>`,
+        '',
+      );
+      for (const hunk of listed) {
+        const { title, subtitle } = formatHunk(hunk, diff, options.locale);
+        const family = hunkFamily(hunk);
+        const glyph = hunkGlyph(hunk) === '~' ? '\\~' : hunkGlyph(hunk);
+        const note = subtitle ? ` — *${escapeMarkdown(subtitle)}*` : '';
+        out.push(`- ${FAMILY_SQUARE[family]} ${glyph} ${escapeMarkdown(title)}${note}`);
+      }
+      out.push('', '</details>', '');
+    }
+    if (ov.hunks > MARKDOWN_HUNK_LIMIT) {
+      out.push(`*${escapeMarkdown(m.markdown.more(ov.hunks - MARKDOWN_HUNK_LIMIT))}*`, '');
+    }
+  }
+  out.push(`*${escapeMarkdown(m.markdown.generatedBy(options.generator))}*`);
+  return `${out.join('\n')}\n`;
+}