@kgdiff/cli 0.0.0-stage → 0.2.0

package/src/help.ts

@@ -0,0 +1,286 @@
+/**
+ * `kgdiff --help` and `kgdiff apply --help`: grouped options, defaults, examples and exit
+ * codes, aligned and wrapped to the terminal width.
+ */
+import type { Painter } from './style.js';
+import { padEnd, stringWidth, wrap } from './width.js';
+
+interface Entry {
+  readonly flags: string;
+  readonly text: string;
+  readonly default?: string;
+}
+
+interface Section {
+  readonly title: string;
+  readonly note?: string;
+  readonly entries?: readonly Entry[];
+  /** Pre-formatted lines (usage, examples). */
+  readonly lines?: readonly (readonly [command: string, comment?: string])[];
+}
+
+const MAIN: readonly Section[] = [
+  {
+    title: 'Usage',
+    lines: [
+      ['kgdiff <before> <after> [options]'],
+      ['kgdiff apply <graph> <delta> [-o <file>] [--no-strict]'],
+    ],
+    note:
+      'Graphs: JSON (.json), JSON-LD (.jsonld), Turtle (.ttl), N-Triples (.nt), N-Quads (.nq), ' +
+      'TriG (.trig), RDF/XML (.rdf, .owl), OBO (.obo); gzip-compressed files work too. ' +
+      'Use - to read one side from stdin.',
+  },
+  {
+    title: 'Output',
+    note: 'Default: a summary on stdout. Outputs combine, e.g. -o report.html --markdown summary.md',
+    entries: [
+      {
+        flags: '--stat',
+        text: 'Diffstat only: counters, bar, node and edge counts, changes by type',
+      },
+      {
+        flags: '--name-status',
+        text: 'One line per hunk: A added, D removed, M modified, R renamed, V moved, G merged, S split, E relations',
+      },
+      { flags: '--json [file]', text: 'Full machine-readable diff (DiffJSON)' },
+      { flags: '--delta [file]', text: 'Invertible delta only, for kgdiff apply' },
+      {
+        flags: '--markdown [file]',
+        text: 'GitHub-flavoured Markdown for PR comments and job summaries',
+      },
+      {
+        flags: '-o, --html <file>',
+        text: 'Self-contained interactive HTML report (works offline)',
+      },
+      {
+        flags: '--open',
+        text: 'Open the HTML report in the browser (a temporary file without -o)',
+      },
+      { flags: '--pretty', text: 'Indent JSON output' },
+    ],
+  },
+  {
+    title: 'Diff',
+    entries: [
+      {
+        flags: '-f, --format <fmt>',
+        text: 'Input format: auto, json, jsonld, turtle, ntriples, nquads, trig, rdfxml, obo',
+        default: 'auto',
+      },
+      { flags: '--before-format <fmt>', text: 'Format of <before> only' },
+      { flags: '--after-format <fmt>', text: 'Format of <after> only' },
+      { flags: '--match <strategy>', text: 'Node matching: id, auto, similarity', default: 'auto' },
+      { flags: '--threshold <n>', text: 'Similarity acceptance threshold, 0–1', default: '0.82' },
+      {
+        flags: '--edge-identity <mode>',
+        text: 'Edge identity: structure, id',
+        default: 'structure',
+      },
+      {
+        flags: '--hierarchy <predicate>',
+        text: 'Hierarchy predicate (repeatable); replaces the defaults when given',
+      },
+      { flags: '--ignore-attr <key>', text: 'Ignore an attribute when comparing (repeatable)' },
+      { flags: '--no-merges', text: 'Do not detect merges' },
+      { flags: '--no-splits', text: 'Do not detect splits' },
+      {
+        flags: '--lang <tags>',
+        text: 'RDF label language preference, comma-separated, e.g. zh,en',
+      },
+    ],
+  },
+  {
+    title: 'Report',
+    entries: [
+      {
+        flags: '--title <text>',
+        text: 'Title of the summary and report',
+        default: '<before> → <after>',
+      },
+      { flags: '--theme <theme>', text: 'Initial theme: auto, light, dark', default: 'auto' },
+      {
+        flags: '--locale <locale>',
+        text: 'Language of hunk titles and the report: en, zh-CN',
+        default: 'from LANG, else en',
+      },
+      { flags: '--mode <mode>', text: 'Initial viewer mode: overlay, swipe, replay, changes' },
+      {
+        flags: '--reproducible',
+        text: 'Omit the timestamp: byte-identical reports for identical input',
+      },
+      {
+        flags: '--no-compute',
+        text: 'Leave out the viewer compute add-on (by default inlined for large graphs laid out around their changes, so collapsed groups can be expanded)',
+      },
+    ],
+  },
+  {
+    title: 'Behaviour',
+    entries: [
+      {
+        flags: '--exit-code',
+        text: 'Exit with 1 when the graphs differ, like git diff --exit-code',
+      },
+      {
+        flags: '--allow-empty',
+        text: 'Treat an empty input as an empty graph (otherwise an empty file or stdin is an error)',
+      },
+      { flags: '-q, --quiet', text: 'Print nothing on stdout (files are still written)' },
+      {
+        flags: '--color <when>',
+        text: 'auto, always, never (auto honours NO_COLOR and FORCE_COLOR)',
+        default: 'auto',
+      },
+      { flags: '--limit <n>', text: 'Hunks listed in the summary; 0 lists all', default: '50' },
+      { flags: '-h, --help', text: 'Show this help' },
+      { flags: '-v, --version', text: 'Show the version' },
+    ],
+  },
+  {
+    title: 'Examples',
+    lines: [
+      ['kgdiff v12.json v13.json', 'colored summary'],
+      ['kgdiff old.obo new.obo -o report.html --open', 'interactive report'],
+      ['kgdiff a.ttl b.ttl --markdown >> "$GITHUB_STEP_SUMMARY"', 'CI job summary'],
+      ['kgdiff a.json b.json --exit-code -q', 'fail when the graphs differ'],
+      ['kgdiff a.json b.json --delta patch.json', 'export a delta …'],
+      ['kgdiff apply a.json patch.json -o b.json', '… and apply it'],
+      ['curl -s https://example.org/latest.ttl | kgdiff pinned.ttl -', 'compare with stdin'],
+    ],
+  },
+  {
+    title: 'Environment',
+    note:
+      'NO_COLOR, FORCE_COLOR (0–3) and COLORTERM control colors · LANG / LC_ALL the locale · ' +
+      'COLUMNS the width when piped · KGDIFF_MAX_INPUT the input size limit (default 1G, e.g. 4G) · ' +
+      'DEBUG=kgdiff prints stack traces',
+  },
+  {
+    title: 'Exit status',
+    note: '0 success (and no differences with --exit-code) · 1 differences with --exit-code · 2 usage or input error',
+  },
+];
+
+const APPLY: readonly Section[] = [
+  {
+    title: 'Usage',
+    lines: [['kgdiff apply <graph> <delta> [-o <file>] [--no-strict]']],
+    note:
+      'Applies a kgdiff delta (from --delta, or the delta inside --json output) to a graph and ' +
+      'writes the result as kgdiff JSON. Use - to read the graph or the delta from stdin.',
+  },
+  {
+    title: 'Options',
+    entries: [
+      {
+        flags: '-o, --output <file>',
+        text: 'Write the patched graph to a file',
+        default: 'stdout',
+      },
+      {
+        flags: '--no-strict',
+        text: "Apply the operations that fit even if the graph is not the delta's base; reports how many were skipped",
+      },
+      { flags: '--verbose', text: 'With --no-strict, list the skipped operations' },
+      { flags: '--allow-empty', text: 'Treat an empty <graph> as an empty graph' },
+      { flags: '-f, --format <fmt>', text: 'Format of <graph>', default: 'auto' },
+      { flags: '--lang <tags>', text: 'RDF label language preference, e.g. zh,en' },
+      { flags: '--pretty', text: 'Indent the JSON output' },
+      { flags: '-q, --quiet', text: 'Print nothing on stdout' },
+      { flags: '--color <when>', text: 'auto, always, never', default: 'auto' },
+      { flags: '-h, --help', text: 'Show this help' },
+    ],
+  },
+  {
+    title: 'Examples',
+    lines: [
+      ['kgdiff v1.ttl v2.ttl --delta patch.json', 'make a delta'],
+      ['kgdiff apply v1.ttl patch.json -o v2.json', 'apply it'],
+    ],
+  },
+  {
+    title: 'Exit status',
+    note: '0 applied · 2 the delta does not fit the graph, or another error',
+  },
+];
+
+const INDENT = '  ';
+const MAX_FLAGS = 26;
+
+function paintFlags(flags: string, paint: Painter): string {
+  return flags
+    .split(/(<[^>]+>|\[[^\]]+\])/)
+    .map((part) =>
+      part.startsWith('<') || part.startsWith('[') ? paint.dim(part) : paint.tone('accent', part),
+    )
+    .join('');
+}
+
+/**
+ * Render help text. `width` is the terminal width (descriptions wrap to it; below 60 columns
+ * they go under their flags).
+ */
+export function renderHelp(
+  topic: 'main' | 'apply',
+  version: string,
+  paint: Painter,
+  width: number,
+): string {
+  const sections = topic === 'apply' ? APPLY : MAIN;
+  const w = Math.max(40, Math.min(width, 100));
+  const flagWidth = Math.min(
+    MAX_FLAGS,
+    Math.max(...sections.flatMap((s) => (s.entries ?? []).map((e) => stringWidth(e.flags)))) + 2,
+  );
+  const stacked = w < 60;
+  const out: string[] = [
+    `${paint.bold(paint.tone('accent', 'kgdiff'))} ${version}  ${paint.dim(
+      topic === 'apply' ? 'apply a delta to a graph' : 'git diff for knowledge graphs',
+    )}`,
+  ];
+  for (const section of sections) {
+    out.push('', paint.bold(section.title));
+    for (const [command, comment] of section.lines ?? []) {
+      const gap = Math.max(2, 58 - stringWidth(command));
+      if (comment && stringWidth(command) + gap + stringWidth(comment) + 4 <= w) {
+        out.push(`${INDENT}${command}${' '.repeat(gap)}${paint.dim(`# ${comment}`)}`);
+        continue;
+      }
+      if (comment) out.push(INDENT + paint.dim(`# ${comment}`));
+      // Long commands wrap with a hanging indent (narrow terminals).
+      wrap(command, w - INDENT.length - 4).forEach((line, i) => {
+        out.push(`${INDENT}${i > 0 ? '    ' : ''}${line}`);
+      });
+    }
+    if (section.note && section.lines) out.push('');
+    if (section.note) {
+      for (const line of wrap(section.note, w - INDENT.length)) out.push(INDENT + paint.dim(line));
+    }
+    for (const entry of section.entries ?? []) {
+      const room = stacked ? w - INDENT.length * 3 : w - INDENT.length - flagWidth;
+      const defaultText = entry.default ? `[default: ${entry.default}]` : '';
+      const wrapped = wrap(defaultText ? `${entry.text} ${defaultText}` : entry.text, room).map(
+        (line) =>
+          defaultText && line.endsWith(defaultText)
+            ? line.slice(0, -defaultText.length) + paint.dim(defaultText)
+            : line,
+      );
+      const flagsPlain = entry.flags;
+      if (stacked || stringWidth(flagsPlain) >= flagWidth) {
+        out.push(INDENT + paintFlags(flagsPlain, paint));
+        for (const line of wrapped)
+          out.push(INDENT.repeat(stacked ? 3 : 1) + ' '.repeat(stacked ? 0 : flagWidth) + line);
+        continue;
+      }
+      wrapped.forEach((line, i) => {
+        const lead =
+          i === 0
+            ? paintFlags(flagsPlain, paint) + ' '.repeat(flagWidth - stringWidth(flagsPlain))
+            : padEnd('', flagWidth);
+        out.push(INDENT + lead + line);
+      });
+    }
+  }
+  return `${out.join('\n')}\n`;
+}

package/src/html.ts

@@ -0,0 +1,145 @@
+/**
+ * The single-file HTML report (docs/cli.md §HTML report): the standalone viewer bundle and the
+ * `ReportPayload` inlined in one accessible document that works offline.
+ *
+ * Pure: compression is injected, so the same inputs always give the same bytes.
+ */
+import type { ReportPayload, ThemePreference } from '@kgdiff/viewer';
+import { sanitize } from './width.js';
+
+/** MIME type of the payload script (`PAYLOAD_SCRIPT_TYPE` in `@kgdiff/viewer`). */
+export const PAYLOAD_TYPE = 'application/kgdiff+json';
+
+/** Payloads larger than this (UTF-8 bytes of the JSON) are embedded gzip + base64. */
+export const GZIP_THRESHOLD = 512 * 1024;
+
+const VIEWER_ID = 'kgdiff';
+
+/** Theme backgrounds (docs/visual-language.md `canvas.background`, `text.primary`). */
+const DARK = { background: '#0B0E14', text: '#E7EBF3' };
+const LIGHT = { background: '#F7F8FA', text: '#0F172A' };
+
+/** Escape text for HTML element content and double-quoted attribute values. */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * JSON that is safe inside a `<script>` element: `<` is written as `<` (so neither
+ * `</script` nor `<!--` can appear), and U+2028 / U+2029 are escaped. Still valid JSON.
+ */
+export function scriptSafeJson(json: string): string {
+  return json
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/**
+ * Make inline JavaScript safe inside a classic `<script>` element: `</script` becomes
+ * `<\/script` and `<!--` becomes `\x3C!--`. Both rewrites keep string, template and regular
+ * expression literals equivalent (the only places such sequences occur in real bundles).
+ */
+export function scriptSafeJs(code: string): string {
+  return code.replace(/<\/(script)/gi, '<\\/$1').replace(/<!--/g, '\\x3C!--');
+}
+
+export interface ReportHtmlOptions {
+  readonly payload: ReportPayload;
+  /** Source of the standalone viewer bundle (an IIFE). */
+  readonly bundle: string;
+  /**
+   * Source of the optional compute add-on (diff / layout in the browser, an IIFE that sets
+   * `globalThis.KgdiffCompute`), inlined right after the viewer bundle when given.
+   */
+  readonly compute?: string;
+  /** gzip compressor used for large payloads. Must be deterministic. */
+  readonly gzip: (data: Uint8Array) => Uint8Array;
+  /** Short description for `<meta name="description">` and `<noscript>`. */
+  readonly description: string;
+  /** Payload size above which it is compressed. Default `GZIP_THRESHOLD`. */
+  readonly gzipThreshold?: number;
+}
+
+function themeStyle(theme: ThemePreference): string {
+  const rule = (c: { background: string; text: string }): string =>
+    `html,body{background:${c.background};color:${c.text}}`;
+  if (theme === 'dark') return `:root{color-scheme:dark}${rule(DARK)}`;
+  if (theme === 'light') return `:root{color-scheme:light}${rule(LIGHT)}`;
+  return `:root{color-scheme:dark light}${rule(DARK)}@media (prefers-color-scheme:light){${rule(LIGHT)}}`;
+}
+
+/** Payload as embedded text plus its `data-encoding` (none, or `gzip-base64`). */
+export function encodePayload(
+  payload: ReportPayload,
+  gzip: (data: Uint8Array) => Uint8Array,
+  threshold = GZIP_THRESHOLD,
+): { readonly text: string; readonly encoding?: 'gzip-base64' } {
+  const json = JSON.stringify(payload);
+  const bytes = new TextEncoder().encode(json);
+  if (bytes.byteLength <= threshold) return { text: scriptSafeJson(json) };
+  return { text: Buffer.from(gzip(bytes)).toString('base64'), encoding: 'gzip-base64' };
+}
+
+/**
+ * Render the report document: `<!doctype html>`, `lang`, charset, viewport, title, an inline
+ * style that paints the theme background before the viewer loads (no white flash), a
+ * full-viewport `<kgdiff-viewer>`, the payload script, the inlined viewer bundle and, when
+ * given, the compute add-on.
+ */
+export function renderReportHtml(options: ReportHtmlOptions): string {
+  const { payload } = options;
+  const view = payload.view ?? {};
+  const theme = view.theme ?? 'auto';
+  const locale = view.locale ?? 'en';
+  // Titles come from graph metadata: no control or bidi characters in the tab title.
+  const title = sanitize(
+    payload.meta.title ?? `${payload.meta.before.name} → ${payload.meta.after.name}`,
+  );
+  const description = sanitize(options.description);
+  const encoded = encodePayload(payload, options.gzip, options.gzipThreshold);
+  const attrs = [
+    `id="${VIEWER_ID}"`,
+    // The report page is the viewer: its keyboard shortcuts apply to the whole page.
+    'global-shortcuts',
+    `theme="${escapeHtml(theme)}"`,
+    `locale="${escapeHtml(locale)}"`,
+    ...(view.mode ? [`mode="${escapeHtml(view.mode)}"`] : []),
+  ].join(' ');
+  const encodingAttr = encoded.encoding ? ` data-encoding="${encoded.encoding}"` : '';
+  const style =
+    `${themeStyle(theme)}html,body{margin:0;height:100%;overflow:hidden}` +
+    'kgdiff-viewer{display:block;position:fixed;inset:0;width:100%;height:100%}' +
+    '.kgdiff-sr{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;' +
+    'clip:rect(0 0 0 0);white-space:nowrap;border:0}' +
+    'noscript p{font:15px/1.5 system-ui,sans-serif;margin:2rem;max-width:40rem}';
+  return [
+    '<!doctype html>',
+    `<html lang="${escapeHtml(locale)}">`,
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<meta name="generator" content="${escapeHtml(payload.meta.generator)}">`,
+    `<meta name="description" content="${escapeHtml(description)}">`,
+    `<title>${escapeHtml(title)} · kgdiff</title>`,
+    `<style>${style}</style>`,
+    '</head>',
+    '<body>',
+    '<main>',
+    `<h1 class="kgdiff-sr">${escapeHtml(title)}</h1>`,
+    `<kgdiff-viewer ${attrs}></kgdiff-viewer>`,
+    `<noscript><p>${escapeHtml(description)}. This interactive report needs JavaScript.</p></noscript>`,
+    '</main>',
+    `<script type="${PAYLOAD_TYPE}" data-for="${VIEWER_ID}"${encodingAttr}>${encoded.text}</script>`,
+    `<script>${scriptSafeJs(options.bundle)}</script>`,
+    ...(options.compute !== undefined ? [`<script>${scriptSafeJs(options.compute)}</script>`] : []),
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n');
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * kgdiff CLI: `kgdiff <before> <after>` and `kgdiff apply <graph> <delta>` (docs/cli.md).
+ *
+ * `main` runs the CLI in-process against an injected `CliIO` (see `nodeIO` for the real one);
+ * the building blocks below are pure and reusable: argument parsing, terminal rendering,
+ * Markdown, the HTML report and the width / color helpers they rest on.
+ */
+
+export { readDelta } from './apply-command.js';
+export {
+  type ApplyCommandOptions,
+  type Command,
+  type CommonOptions,
+  DEFAULT_LIMIT,
+  type DiffCommandOptions,
+  parseCommandLine,
+  STDIO,
+} from './args.js';
+export { defaultTitle, describeDiff, graphLabel, outputWidth } from './diff-command.js';
+export { CliError, type CliErrorCode, describeError, formatError } from './errors.js';
+export { renderHelp } from './help.js';
+export {
+  encodePayload,
+  escapeHtml,
+  GZIP_THRESHOLD,
+  PAYLOAD_TYPE,
+  type ReportHtmlOptions,
+  renderReportHtml,
+  scriptSafeJs,
+  scriptSafeJson,
+} from './html.js';
+export type { CliFileSystem, CliIO, OutputStream } from './io.js';
+export { formatInt, matchLocale, messages, resolveLocale } from './locale.js';
+export { main } from './main.js';
+export {
+  escapeMarkdown,
+  MARKDOWN_HUNK_LIMIT,
+  type MarkdownOptions,
+  renderMarkdown,
+} from './markdown.js';
+export {
+  type ChangeFamily,
+  hunkFamily,
+  hunkGlyph,
+  KIND_FAMILY,
+  type NameStatus,
+  nameStatus,
+  type Overview,
+  overview,
+} from './model.js';
+export { nodeIO, openCommand } from './node-io.js';
+export { buildReportHtml, buildReportPayload, createGzip, type ReportInfo } from './report.js';
+export {
+  type ColorLevel,
+  type ColorMode,
+  createPainter,
+  type Painter,
+  resolveColorLevel,
+  stripAnsi,
+  type Tone,
+} from './style.js';
+export {
+  diffstatBar,
+  renderNameStatus,
+  renderStat,
+  renderSummary,
+  type TextContext,
+  totalsText,
+} from './summary.js';
+export { cliVersion } from './version.js';
+export { graphemeWidth, padEnd, padStart, sanitize, stringWidth, truncate, wrap } from './width.js';