@kgdiff/cli 0.0.0-stage → 0.2.0

package/dist/width.js

@@ -0,0 +1,232 @@
+/**
+ * Terminal display width of text (East Asian Width, combining marks, emoji) and the helpers
+ * built on it: sanitizing untrusted labels, truncating with an ellipsis and padding.
+ *
+ * Widths follow what modern terminals render: CJK / fullwidth / emoji-presentation characters
+ * take two columns, combining marks, joiners and variation selectors none, East Asian
+ * "ambiguous" characters (`→`, `·`, `…`, box drawing) one. Measurement is per grapheme cluster
+ * (`Intl.Segmenter`), so `é` (e + U+0301), a ZWJ emoji sequence, a flag and a keycap
+ * are each measured as one unit.
+ */
+/** East Asian Width W and F ranges (Unicode 16), as inclusive [start, end] pairs, sorted. */
+const WIDE_RANGES = [
+    0x1100, 0x115f, 0x231a, 0x231b, 0x2329, 0x232a, 0x23e9, 0x23ec, 0x23f0, 0x23f0, 0x23f3, 0x23f3,
+    0x25fd, 0x25fe, 0x2614, 0x2615, 0x2630, 0x2637, 0x2648, 0x2653, 0x267f, 0x267f, 0x268a, 0x268f,
+    0x2693, 0x2693, 0x26a1, 0x26a1, 0x26aa, 0x26ab, 0x26bd, 0x26be, 0x26c4, 0x26c5, 0x26ce, 0x26ce,
+    0x26d4, 0x26d4, 0x26ea, 0x26ea, 0x26f2, 0x26f3, 0x26f5, 0x26f5, 0x26fa, 0x26fa, 0x26fd, 0x26fd,
+    0x2705, 0x2705, 0x270a, 0x270b, 0x2728, 0x2728, 0x274c, 0x274c, 0x274e, 0x274e, 0x2753, 0x2755,
+    0x2757, 0x2757, 0x2795, 0x2797, 0x27b0, 0x27b0, 0x27bf, 0x27bf, 0x2b1b, 0x2b1c, 0x2b50, 0x2b50,
+    0x2b55, 0x2b55, 0x2e80, 0x2e99, 0x2e9b, 0x2ef3, 0x2f00, 0x2fd5, 0x2ff0, 0x303e, 0x3041, 0x3096,
+    0x3099, 0x30ff, 0x3105, 0x312f, 0x3131, 0x318e, 0x3190, 0x31e5, 0x31ef, 0x321e, 0x3220, 0x3247,
+    0x3250, 0xa48c, 0xa490, 0xa4c6, 0xa960, 0xa97c, 0xac00, 0xd7a3, 0xf900, 0xfaff, 0xfe10, 0xfe19,
+    0xfe30, 0xfe52, 0xfe54, 0xfe66, 0xfe68, 0xfe6b, 0xff01, 0xff60, 0xffe0, 0xffe6, 0x16fe0, 0x16fe4,
+    0x16ff0, 0x16ff1, 0x17000, 0x187f7, 0x18800, 0x18cd5, 0x18d00, 0x18d08, 0x1aff0, 0x1aff3, 0x1aff5,
+    0x1affb, 0x1affd, 0x1affe, 0x1b000, 0x1b122, 0x1b132, 0x1b132, 0x1b150, 0x1b152, 0x1b155, 0x1b155,
+    0x1b164, 0x1b167, 0x1b170, 0x1b2fb, 0x1d300, 0x1d356, 0x1d360, 0x1d376, 0x1f004, 0x1f004, 0x1f0cf,
+    0x1f0cf, 0x1f18e, 0x1f18e, 0x1f191, 0x1f19a, 0x1f200, 0x1f202, 0x1f210, 0x1f23b, 0x1f240, 0x1f248,
+    0x1f250, 0x1f251, 0x1f260, 0x1f265, 0x1f300, 0x1f320, 0x1f32d, 0x1f335, 0x1f337, 0x1f37c, 0x1f37e,
+    0x1f393, 0x1f3a0, 0x1f3ca, 0x1f3cf, 0x1f3d3, 0x1f3e0, 0x1f3f0, 0x1f3f4, 0x1f3f4, 0x1f3f8, 0x1f43e,
+    0x1f440, 0x1f440, 0x1f442, 0x1f4fc, 0x1f4ff, 0x1f53d, 0x1f54b, 0x1f54e, 0x1f550, 0x1f567, 0x1f57a,
+    0x1f57a, 0x1f595, 0x1f596, 0x1f5a4, 0x1f5a4, 0x1f5fb, 0x1f64f, 0x1f680, 0x1f6c5, 0x1f6cc, 0x1f6cc,
+    0x1f6d0, 0x1f6d2, 0x1f6d5, 0x1f6d7, 0x1f6dc, 0x1f6df, 0x1f6eb, 0x1f6ec, 0x1f6f4, 0x1f6fc, 0x1f7e0,
+    0x1f7eb, 0x1f7f0, 0x1f7f0, 0x1f90c, 0x1f93a, 0x1f93c, 0x1f945, 0x1f947, 0x1f9ff, 0x1fa70, 0x1fa7c,
+    0x1fa80, 0x1fa89, 0x1fa8f, 0x1fac6, 0x1face, 0x1fadc, 0x1fadf, 0x1fae9, 0x1faf0, 0x1faf8, 0x20000,
+    0x2fffd, 0x30000, 0x3fffd,
+];
+/** True when the code point is East Asian Wide or Fullwidth. O(log n). */
+export function isWideCodePoint(cp) {
+    if (cp < 0x1100)
+        return false;
+    let lo = 0;
+    let hi = WIDE_RANGES.length / 2 - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const start = WIDE_RANGES[mid * 2];
+        const end = WIDE_RANGES[mid * 2 + 1];
+        if (cp < start)
+            hi = mid - 1;
+        else if (cp > end)
+            lo = mid + 1;
+        else
+            return true;
+    }
+    return false;
+}
+const ZERO_WIDTH = /^[\p{Mn}\p{Me}\p{Cf}]$/u;
+const EMOJI_PRESENTATION = /\p{Emoji_Presentation}/u;
+const EMOJI = /\p{Emoji}/u;
+const REGIONAL_INDICATOR = /\p{Regional_Indicator}/u;
+/** Display width of one grapheme cluster: 0, 1 or 2 columns. */
+export function graphemeWidth(grapheme) {
+    const cp = grapheme.codePointAt(0);
+    if (cp === undefined)
+        return 0;
+    if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0))
+        return 0;
+    if (cp < 0x7f && grapheme.length === 1)
+        return 1; // ASCII fast path
+    if (grapheme.length > 1) {
+        // Emoji sequences: presentation selector, ZWJ sequences, flags, keycaps, skin tones.
+        if (grapheme.includes('\uFE0F') && EMOJI.test(grapheme))
+            return 2;
+        if (grapheme.includes('\u200D') && EMOJI_PRESENTATION.test(grapheme))
+            return 2;
+        if (REGIONAL_INDICATOR.test(grapheme))
+            return 2;
+    }
+    const first = String.fromCodePoint(cp);
+    if (ZERO_WIDTH.test(first))
+        return 0;
+    if (grapheme.includes('\uFE0E'))
+        return 1; // text presentation selector
+    if (isWideCodePoint(cp) || EMOJI_PRESENTATION.test(first))
+        return 2;
+    return 1;
+}
+let segmenter;
+/** Grapheme clusters of `text` (code points as a fallback when `Intl.Segmenter` is missing). */
+export function graphemes(text) {
+    if (segmenter === undefined) {
+        segmenter =
+            typeof Intl.Segmenter === 'function'
+                ? new Intl.Segmenter('en', { granularity: 'grapheme' })
+                : null;
+    }
+    if (segmenter)
+        return Array.from(segmenter.segment(text), (s) => s.segment);
+    // Fallback: attach zero-width code points to the previous one.
+    const out = [];
+    for (const ch of text) {
+        const cp = ch.codePointAt(0);
+        if (out.length > 0 && (ZERO_WIDTH.test(ch) || (cp >= 0x1f3fb && cp <= 0x1f3ff))) {
+            out[out.length - 1] += ch;
+        }
+        else
+            out.push(ch);
+    }
+    return out;
+}
+const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
+/** Display width of `text` in terminal columns. Text must not contain ANSI escape sequences. */
+export function stringWidth(text) {
+    if (PRINTABLE_ASCII.test(text))
+        return text.length;
+    let width = 0;
+    for (const g of graphemes(text))
+        width += graphemeWidth(g);
+    return width;
+}
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control characters is the point.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+/**
+ * Invisible characters that can disguise text ("Trojan Source"): bidirectional controls
+ * (U+061C, U+200E/F, U+202A–U+202E, U+2066–U+2069), zero-width and invisible format characters
+ * (U+180E, U+200B, U+2060–U+2064, U+FEFF, U+FFF9–U+FFFB) and tag characters outside emoji flag
+ * sequences. Joiners (U+200C, U+200D) and variation selectors stay: scripts and emoji need them.
+ */
+const INVISIBLE = /[\u061C\u180E\u200B\u200E\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF\uFFF9-\uFFFB]|(?<!\u{1F3F4}[\u{E0020}-\u{E007E}]*)[\u{E0000}-\u{E007F}]/gu;
+/** Replace invisible and bidirectional control characters with a visible `⟨U+202E⟩`. */
+export function revealInvisible(text) {
+    return text.replace(INVISIBLE, (ch) => {
+        const cp = ch.codePointAt(0);
+        return `⟨U+${cp.toString(16).toUpperCase().padStart(4, '0')}⟩`;
+    });
+}
+/**
+ * Make untrusted text (labels, ids, file names, parser messages) safe to print on one
+ * terminal line: tabs and line breaks become spaces, other C0 controls (notably ESC, which
+ * could inject escape sequences or hyperlinks) become control pictures (`␛`), C1 controls
+ * U+FFFD, and invisible or bidirectional controls a visible `⟨U+202E⟩`.
+ */
+export function sanitize(text) {
+    return revealInvisible(text.replace(CONTROL, (ch) => {
+        const cp = ch.charCodeAt(0);
+        if (cp === 0x09 || cp === 0x0a || cp === 0x0d || cp === 0x2028 || cp === 0x2029)
+            return ' ';
+        if (cp < 0x20)
+            return String.fromCharCode(0x2400 + cp);
+        if (cp === 0x7f)
+            return '\u2421';
+        return '\uFFFD';
+    }));
+}
+/** `sanitize` line by line, keeping line breaks (stack traces). */
+export function sanitizeLines(text) {
+    return text.split(/\r?\n/).map(sanitize).join('\n');
+}
+/**
+ * Truncate `text` to at most `max` columns, ending with `…` when something was cut. Never
+ * splits a grapheme; a wide character that does not fit is dropped whole (the result may then
+ * be one column narrower than `max`). Returns '' for `max` ≤ 0.
+ */
+export function truncate(text, max, ellipsis = '…') {
+    if (max <= 0)
+        return '';
+    if (stringWidth(text) <= max)
+        return text;
+    const room = max - stringWidth(ellipsis);
+    if (room < 0)
+        return '';
+    let width = 0;
+    let out = '';
+    for (const g of graphemes(text)) {
+        const w = graphemeWidth(g);
+        if (width + w > room)
+            break;
+        out += g;
+        width += w;
+    }
+    return out.trimEnd() + ellipsis;
+}
+/** Pad `text` with spaces on the right to `width` columns (no-op when already wider). */
+export function padEnd(text, width) {
+    const gap = width - stringWidth(text);
+    return gap > 0 ? text + ' '.repeat(gap) : text;
+}
+/** Pad `text` with spaces on the left to `width` columns (no-op when already wider). */
+export function padStart(text, width) {
+    const gap = width - stringWidth(text);
+    return gap > 0 ? ' '.repeat(gap) + text : text;
+}
+/**
+ * Greedy word wrap to `width` columns. Breaks at spaces; CJK text (no spaces) breaks between
+ * graphemes. Lines never exceed `width` unless a single grapheme is wider.
+ */
+export function wrap(text, width) {
+    if (width <= 0 || stringWidth(text) <= width)
+        return [text];
+    const lines = [];
+    let line = '';
+    let lineWidth = 0;
+    const flush = () => {
+        lines.push(line.trimEnd());
+        line = '';
+        lineWidth = 0;
+    };
+    for (const word of text.split(/(?<= )/)) {
+        const w = stringWidth(word);
+        if (lineWidth + stringWidth(word.trimEnd()) <= width) {
+            line += word;
+            lineWidth += w;
+            continue;
+        }
+        if (lineWidth > 0)
+            flush();
+        if (stringWidth(word.trimEnd()) <= width) {
+            line = word;
+            lineWidth = w;
+            continue;
+        }
+        for (const g of graphemes(word)) {
+            const gw = graphemeWidth(g);
+            if (lineWidth + gw > width && lineWidth > 0)
+                flush();
+            line += g;
+            lineWidth += gw;
+        }
+    }
+    if (line.trim())
+        lines.push(line.trimEnd());
+    return lines;
+}
+//# sourceMappingURL=width.js.map

package/dist/width.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"width.js","sourceRoot":"","sources":["../src/width.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,GAAsB;IACrC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAC9F,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;IAChG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACjG,OAAO,EAAE,OAAO,EAAE,OA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"}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@kgdiff/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "git diff for knowledge graphs. Compare two graph files from the terminal, CI, or as a shareable HTML report.",
+  "keywords": [
+    "kgdiff",
+    "cli",
+    "diff",
+    "knowledge-graph",
+    "ontology",
+    "rdf"
+  ],
+  "homepage": "https://github.com/iiwish/kgdiff/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/iiwish/kgdiff/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iiwish/kgdiff.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "author": "iiwish",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "kgdiff": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@kgdiff/core": "0.2.0",
+    "@kgdiff/formats": "0.2.0",
+    "@kgdiff/layout": "0.2.0",
+    "@kgdiff/scene": "0.2.0",
+    "@kgdiff/viewer": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
 }

package/src/apply-command.ts

@@ -0,0 +1,203 @@
+/**
+ * `kgdiff apply <graph> <delta>`: apply a delta (docs/delta-format.md) and write the patched
+ * graph as kgdiff JSON.
+ */
+import { basename } from 'node:path';
+import {
+  applyDelta,
+  type Delta,
+  type EdgeIdentity,
+  type GraphJSON,
+  graphToJSON,
+  hashGraph,
+  type KGraph,
+  normalize,
+} from '@kgdiff/core';
+import { type ApplyCommandOptions, STDIO } from './args.js';
+import { CliError, formatWarning, isKgdiffError } from './errors.js';
+import { parseInput, type RawInput, readInput, readPair } from './inputs.js';
+import type { CliIO } from './io.js';
+import { formatInt } from './locale.js';
+import { outputContext, writeOutputFile } from './output.js';
+import { checkNoOverwrite } from './overwrite.js';
+import { sanitize } from './width.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read a delta from JSON text. Accepts a `kgdiff.delta` document, or a `kgdiff.diff` document
+ * (`--json` output), whose delta is used. Version checks are left to `applyDelta`.
+ */
+export function readDelta(input: RawInput): Delta {
+  const where = input.display === 'stdin' ? 'stdin' : `"${input.display}"`;
+  let value: unknown;
+  try {
+    value = JSON.parse(input.text);
+  } catch (error) {
+    throw new CliError(
+      'input',
+      `${where} is not valid JSON: ${error instanceof Error ? error.message : String(error)}.`,
+      'Create a delta with `kgdiff <before> <after> --delta <file>`.',
+      { cause: error },
+    );
+  }
+  if (isRecord(value) && value.format === 'kgdiff.diff' && isRecord(value.delta)) {
+    return value.delta as unknown as Delta;
+  }
+  if (!isRecord(value) || value.format !== 'kgdiff.delta') {
+    throw new CliError(
+      'input',
+      `${where} is not a kgdiff delta (expected "format": "kgdiff.delta").`,
+      'Create one with `kgdiff <before> <after> --delta <file>`. Is the order <graph> <delta>?',
+    );
+  }
+  return value as unknown as Delta;
+}
+
+/**
+ * The patched graph as kgdiff JSON (`graphToJSON`, which `kgdiff` reads back losslessly).
+ *
+ * Meta: `name` / `version` come from the delta's target (`applyDelta`); `source` names the
+ * output file (`source` argument), or is dropped when writing to stdout, so the result never
+ * claims to be the input file.
+ */
+export function graphOutputJSON(graph: KGraph, source?: string): GraphJSON {
+  const { format, version, meta, nodes, edges } = graphToJSON(graph);
+  const { source: _inputSource, ...rest } = meta ?? {};
+  const outMeta = source !== undefined ? { ...rest, source } : rest;
+  return Object.keys(outMeta).length > 0
+    ? { format, version, meta: outMeta, nodes, edges }
+    : { format, version, nodes, edges };
+}
+
+const EDGE_IDENTITIES: readonly unknown[] = ['structure', 'id'];
+
+export interface SkippedOp {
+  /** Index in `delta.ops`. */
+  readonly index: number;
+  readonly op: string;
+  readonly reason: string;
+}
+
+/**
+ * `--no-strict`: apply every operation whose precondition holds, in one pass, and collect the
+ * skipped ones (core's `onSkip`, in op order).
+ */
+export function applyLeniently(
+  graph: KGraph,
+  delta: Delta,
+): { readonly result: KGraph; readonly skipped: readonly SkippedOp[] } {
+  const skipped: SkippedOp[] = [];
+  const result = applyDelta(graph, delta, {
+    strict: false,
+    onSkip: ({ index, op, reason }) => skipped.push({ index, op: String(op.op), reason }),
+  });
+  return { result, skipped };
+}
+
+const PARSE_OPTIONS_HINT =
+  'If it is the same graph, parse it as when the delta was made: --format and --lang must match ' +
+  'the options given to `kgdiff … --delta` (they change what the graph contains).';
+
+/** Run the apply command. Returns the exit code. */
+export async function runApply(o: ApplyCommandOptions, io: CliIO): Promise<number> {
+  const ctx = outputContext(io, o);
+  await checkNoOverwrite(
+    io,
+    [
+      { role: '<graph>', path: o.graph },
+      { role: '<delta>', path: o.delta },
+    ],
+    [{ role: '-o', path: o.output }],
+  );
+  const [graphInput, deltaInput] = await readPair(
+    readInput(io, o.graph, '<graph>', { allowEmpty: o.allowEmpty }),
+    readInput(io, o.delta, '<delta>', {
+      emptyHint: 'Create a delta with `kgdiff <before> <after> --delta <file>`.',
+    }),
+  );
+  const delta = readDelta(deltaInput);
+  const parsed = parseInput(graphInput, {
+    format: o.format,
+    formatFlag: '--format',
+    ...(o.languages ? { languages: o.languages } : {}),
+  });
+  const edgeIdentity = EDGE_IDENTITIES.includes(delta.edgeIdentity)
+    ? { edgeIdentity: delta.edgeIdentity as EdgeIdentity }
+    : {};
+  const graph = normalize(parsed.graph, edgeIdentity);
+
+  let result: KGraph;
+  let skipped: readonly SkippedOp[] = [];
+  if (o.strict) {
+    try {
+      result = applyDelta(graph, delta, { strict: true });
+    } catch (error) {
+      if (isKgdiffError(error) && error.code === 'delta-base-mismatch') {
+        const { expected, actual } = error.details ?? {};
+        const where = o.graph === STDIO ? '<graph> (stdin)' : `<graph> "${o.graph}"`;
+        throw new CliError(
+          'input',
+          `${where} is not the base of this delta (graph ${String(actual)}, delta base ${String(expected)}).`,
+          `${PARSE_OPTIONS_HINT} Otherwise --no-strict applies what fits and reports the rest.`,
+          { cause: error },
+        );
+      }
+      if (isKgdiffError(error) && error.code === 'delta-conflict') {
+        throw new CliError(
+          'input',
+          error.message,
+          `The graph differs from the delta's base. --no-strict applies the operations that fit and reports the others. ${PARSE_OPTIONS_HINT}`,
+          { cause: error },
+        );
+      }
+      throw error;
+    }
+  } else {
+    const lenient = applyLeniently(graph, delta);
+    result = lenient.result;
+    skipped = lenient.skipped;
+    if (skipped.length > 0) {
+      const total = delta.ops.length;
+      const count = formatInt(skipped.length);
+      ctx.notice(
+        formatWarning(
+          `Skipped ${count} of ${formatInt(total)} ${total === 1 ? 'operation' : 'operations'} that do not fit this graph${o.verbose ? ':' : ' (--verbose lists them).'}`,
+          ctx.errPaint,
+        ),
+      );
+      if (o.verbose) {
+        for (const s of skipped) {
+          ctx.notice(`  #${s.index} ${sanitize(s.op)}: ${sanitize(s.reason)}\n`);
+        }
+      }
+    }
+  }
+
+  const hash = hashGraph(result);
+  const target = isRecord(delta.target) ? delta.target.hash : undefined;
+  if (typeof target === 'string' && hash !== target && skipped.length === 0) {
+    ctx.notice(
+      formatWarning(
+        `The result (${hash}) differs from the delta's target (${target}).`,
+        ctx.errPaint,
+      ),
+    );
+  }
+  const source = o.output === STDIO ? undefined : basename(o.output);
+  const text = `${JSON.stringify(graphOutputJSON(result, source), null, o.pretty ? 2 : undefined)}\n`;
+  if (o.output === STDIO) {
+    ctx.stdout(text);
+  } else {
+    const ops = delta.ops.length - skipped.length;
+    await writeOutputFile(
+      ctx,
+      o.output,
+      text,
+      `patched graph (${formatInt(ops)} ${ops === 1 ? 'operation' : 'operations'} applied, ${hash})`,
+    );
+  }
+  return 0;
+}