@kgdiff/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iiwish and kgdiff contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# kgdiff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**git diff for knowledge graphs.** Compare two versions of a graph — RDF, OBO or JSON — in the
+terminal, in CI, or as a single-file interactive HTML report. kgdiff understands what changed:
+a merge is a merge, a rename is a rename, a moved class is a move.
+
+```sh
+npx @kgdiff/cli before.ttl after.ttl
+```
+
+## Install
+
+```sh
+npm install --global @kgdiff/cli      # or: pnpm add -g @kgdiff/cli
+kgdiff --version
+```
+
+Node.js ≥ 22. `npx @kgdiff/cli …` works without installing.
+
+## Usage
+
+```
+kgdiff <before> <after> [options]
+kgdiff apply <graph> <delta> [-o <file>] [--no-strict [--verbose]]
+kgdiff --help | --version
+```
+
+Inputs are JSON (kgdiff, d3 / NetworkX, Cytoscape.js, G6, graphology, vis-network), JSON-LD,
+Turtle, N-Triples, N-Quads, TriG, RDF/XML (`.rdf`, `.owl` from Protégé or ROBOT) and OBO,
+detected from the extension and the content. Gzip-compressed files (`.ttl.gz`) work too. `-`
+reads one side from stdin. JSON-LD contexts must be inline: remote ones are never fetched.
+
+```sh
+kgdiff v12.json v13.json                          # colored summary
+kgdiff old.obo new.obo -o report.html --open      # interactive report, opened in the browser
+kgdiff a.ttl b.ttl --stat                         # diffstat only
+kgdiff a.ttl b.ttl --name-status | grep '^G'      # merges, one per line (tab-separated)
+kgdiff a.json b.json --json diff.json             # full machine-readable diff
+kgdiff a.json b.json --delta patch.json           # invertible delta …
+kgdiff apply a.json patch.json -o b.json          # … and apply it
+curl -s https://example.org/latest.ttl | kgdiff pinned.ttl -
+```
+
+Outputs combine: `kgdiff a.ttl b.ttl -o report.html --markdown summary.md --json diff.json`
+writes three files and still prints the summary. At most one output can go to stdout.
+
+Files are written atomically (temporary file + rename). kgdiff never overwrites its inputs: an
+output that is an input under another name — a case variant, a symlink, a hard link — is refused,
+in `kgdiff apply` too. An empty input is an error unless `--allow-empty` (an empty graph, e.g.
+before a first release), so a failed upstream command cannot pass for "everything removed".
+
+### In CI
+
+```yaml
+# Fail the job when the ontology changed, and explain what changed in the job summary.
+- run: npx @kgdiff/cli main/ontology.ttl ontology.ttl --markdown >> "$GITHUB_STEP_SUMMARY"
+- run: npx @kgdiff/cli main/ontology.ttl ontology.ttl --exit-code --quiet
+```
+
+`--markdown` is GitHub-flavoured Markdown (a diffstat table, a family legend and the hunk list
+in collapsible `<details>` groups), safe to paste into PR comments: labels are escaped and can
+never mention people, link issues or inject HTML.
+
+## Output
+
+The default summary: a header with node and edge totals, counters per replay phase, a diffstat
+bar, and the hunks grouped by phase (Removed, Restructured, Modified, Added). Glyphs keep it
+readable without color: `+` added, `−` removed, `~` modified, `⇄` structure (moves,
+relations), `⊕` merge, `⑂` split.
+
+```
+kgdiff  mhd 2026-09-01 → 2026-10-01                                179 → 184 nodes · 351 → 353 edges
+
+  +3 added   ~12 modified   ⇄7 restructured                                   58 changes in 22 hunks
+  +++++~~~~~~~~~~~~⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄⇄
+
+  Restructured 7
+  ⑂ Split “obsolete diabetes insipidus” into “obsolete diabetes i…   identity · inferred · 80% conf…
+  ⊕ Merged “juvenile diabetes” and “insulin-dependent diabetes me…   identity · via replacement hin…
+  ⊕ Merged “heart attack” into “myocardial infarction”               identity · via replacement hin…
+  ⇄ Moved “Crohn disease” under “inflammatory bowel disease”         structure · from “intestinal d…
+  Modified 12
+  ~ Renamed “alcoholic liver disease” → “alcohol-related liver di…   content · ~1 attribute · +1 sy…
+  …
+```
+
+Counters count hunks (reviewable changes); "58 changes" counts changed nodes and edges, which
+the bar splits by phase. Colors follow kgdiff's meaning families (green added, red removed,
+amber content, blue structure, violet identity) in truecolor, 256 or 16 colors. Lines fit the
+terminal down to 40 columns; CJK and emoji are measured correctly, and control, bidi and
+invisible characters in labels are shown as `␛` / `⟨U+202E⟩` instead of being interpreted. `--limit <n>` caps the list (default 50, `0`
+lists all). Hunk titles and the summary are localized (`--locale zh-CN`, or from `LANG`).
+
+`--stat` adds a nodes / edges table and changes by node type:
+
+```
+         added  removed  modified  unchanged
+  nodes      5        0        23        156
+  edges     10        8        12        331
+
+  By type
+  Term  28 +++++~~~~~~~~~~~~~~~~~~~~~~~
+```
+
+`--name-status` prints one line per hunk: a letter (`A` added, `D` removed, `M` modified,
+`R` renamed, `V` moved, `G` merged, `S` split, `E` relations), the anchor node id and the
+title, tab-separated when piped:
+
+```
+S	MHD:0000067	Split “obsolete diabetes insipidus” into …
+G	MHD:0000062	Merged “juvenile diabetes” and “insulin-dependent diabetes mellitus” into …
+V	MHD:0000087	Moved “Crohn disease” under “inflammatory bowel disease”
+```
+
+### HTML report
+
+`-o report.html` writes one self-contained file: the viewer plus the precomputed diff and
+layout (gzip-compressed above 512 kB). It opens instantly, works offline and can be attached to
+a PR or an e-mail. `--theme`, `--mode`, `--locale` and `--title` set the initial view;
+`--reproducible` omits the timestamp so identical inputs give byte-identical reports.
+
+Large graphs are laid out around their changes, with unchanged neighbourhoods collapsed. For
+those reports kgdiff also inlines the viewer's small compute add-on, so collapsed groups can be
+expanded in the browser; reports with a full layout leave it out. `--no-compute` always leaves
+it out (smaller file, groups stay collapsed).
+
+### Applying deltas
+
+`kgdiff apply` applies a delta (from `--delta`, or the delta inside `--json` output) and writes
+the patched graph as kgdiff JSON. By default it checks that the graph is the delta's base and
+that every operation's precondition holds. Parse the graph as when the delta was made (same
+`--format` / `--lang`), or its hash will differ. `--no-strict` applies every operation that fits
+and reports how many were skipped; add `--verbose` to list them.
+
+## Options
+
+Run `kgdiff --help` for the full list. The most useful:
+
+| Option                         | Meaning                                                                       |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| `--match id\|auto\|similarity` | How nodes are paired (default `auto`: ids, then similarity)                   |
+| `--hierarchy <predicate>`      | Hierarchy predicate, repeatable (e.g. `--hierarchy is_a`)                     |
+| `--ignore-attr <key>`          | Ignore an attribute when comparing, repeatable                                |
+| `-f, --format <fmt>`           | Force the input format (`json jsonld turtle ntriples nquads trig rdfxml obo`) |
+| `--lang zh,en`                 | RDF label language preference                                                 |
+| `--exit-code`, `-q`            | Exit 1 on differences; print nothing on stdout                                |
+| `--color auto\|always\|never`  | Colors (auto: only on a terminal, honours `NO_COLOR`)                         |
+
+## Exit codes
+
+| Code | Meaning                                                                   |
+| ---- | ------------------------------------------------------------------------- |
+| `0`  | Success (and, with `--exit-code`, no differences)                         |
+| `1`  | The graphs differ (only with `--exit-code`)                               |
+| `2`  | Usage or input error: one line on stderr with a hint, never a stack trace |
+
+## Environment
+
+| Variable                         | Effect                                                                  |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| `NO_COLOR`                       | Disable colors (unless `--color always`)                                |
+| `FORCE_COLOR`                    | `0` disables; `1` / `2` / `3` force exactly 16 / 256 / truecolor colors |
+| `COLORTERM`, `TERM`, `COLORFGBG` | Color depth and light-background detection                              |
+| `LC_ALL`, `LC_MESSAGES`, `LANG`  | Default locale (`zh*` → `zh-CN`, otherwise `en`)                        |
+| `COLUMNS`                        | Line width when stdout is not a terminal (default 120)                  |
+| `KGDIFF_MAX_INPUT`               | Input size limit after decompression (default `1G`; e.g. `4G`, `512M`)  |
+| `DEBUG=kgdiff`                   | Print stack traces with errors                                          |
+
+## Programmatic use
+
+```ts
+import { main, nodeIO } from 'kgdiff';
+
+process.exitCode = await main(['a.ttl', 'b.ttl', '--stat'], nodeIO());
+```
+
+`main(argv, io)` never throws and takes every side effect from `io` (streams, files, clock,
+environment, terminal size), so it runs in-process in tests. The renderers (`renderSummary`,
+`renderStat`, `renderNameStatus`, `renderMarkdown`, `renderReportHtml`) and helpers
+(`stringWidth`, `truncate`, `resolveColorLevel`, `parseCommandLine`) are exported too.
+
+## Development
+
+From the repository root:
+
+```sh
+pnpm tsx packages/cli/src/bin.ts examples/datasets/ontology-release/before.obo \
+  examples/datasets/ontology-release/after.obo --hierarchy is_a
+pnpm vitest run packages/cli          # tests, including golden outputs in test/__snapshots__
+pnpm --filter kgdiff typecheck
+```
+
+HTML reports need the standalone viewer bundle: `pnpm --filter @kgdiff/viewer build`.
+Golden snapshots follow the diff engine; after an intended change run
+`pnpm vitest run packages/cli -u` and review the snapshot diff.
+
+## License
+
+MIT

package/dist/apply-command.d.ts

@@ -0,0 +1,34 @@
+import { type Delta, type GraphJSON, type KGraph } from '@kgdiff/core';
+import { type ApplyCommandOptions } from './args.js';
+import { type RawInput } from './inputs.js';
+import type { CliIO } from './io.js';
+/**
+ * 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 declare function readDelta(input: RawInput): 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 declare function graphOutputJSON(graph: KGraph, source?: string): GraphJSON;
+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 declare function applyLeniently(graph: KGraph, delta: Delta): {
+    readonly result: KGraph;
+    readonly skipped: readonly SkippedOp[];
+};
+/** Run the apply command. Returns the exit code. */
+export declare function runApply(o: ApplyCommandOptions, io: CliIO): Promise<number>;
+//# sourceMappingURL=apply-command.d.ts.map

package/dist/apply-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-command.d.ts","sourceRoot":"","sources":["../src/apply-command.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,KAAK,EAEV,KAAK,SAAS,EAGd,KAAK,MAAM,EAEZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,mBAAmB,EAAS,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAc,KAAK,QAAQ,EAAuB,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAUrC;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,CAwBhD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAKzE;AAID,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,KAAK,GACX;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,CAOrE;AAMD,oDAAoD;AACpD,wBAAsB,QAAQ,CAAC,CAAC,EAAE,mBAAmB,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAkGjF"}

package/dist/apply-command.js

@@ -0,0 +1,135 @@
+/**
+ * `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, graphToJSON, hashGraph, normalize, } from '@kgdiff/core';
+import { STDIO } from './args.js';
+import { CliError, formatWarning, isKgdiffError } from './errors.js';
+import { parseInput, readInput, readPair } from './inputs.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) {
+    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) {
+    const where = input.display === 'stdin' ? 'stdin' : `"${input.display}"`;
+    let value;
+    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;
+    }
+    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;
+}
+/**
+ * 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, source) {
+    const { meta, ...json } = graphToJSON(graph);
+    const { source: _inputSource, ...rest } = meta ?? {};
+    const outMeta = source !== undefined ? { ...rest, source } : rest;
+    return Object.keys(outMeta).length > 0 ? { meta: outMeta, ...json } : json;
+}
+const EDGE_IDENTITIES = ['structure', 'id'];
+/**
+ * `--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, delta) {
+    const skipped = [];
+    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, io) {
+    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 }
+        : {};
+    const graph = normalize(parsed.graph, edgeIdentity);
+    let result;
+    let skipped = [];
+    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;
+}
+//# sourceMappingURL=apply-command.js.map

package/dist/apply-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-command.js","sourceRoot":"","sources":["../src/apply-command.ts"],"names":[],"mappings":"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"}

package/dist/args.d.ts

@@ -0,0 +1,96 @@
+import type { DiffOptions, Locale } from '@kgdiff/core';
+import type { FormatId } from '@kgdiff/formats';
+import type { ThemePreference, ViewerMode } from '@kgdiff/viewer';
+import type { ColorMode } from './style.js';
+/** Path value meaning "write to stdout" / "read from stdin". */
+export declare const STDIO = "-";
+export declare const FORMATS: readonly (FormatId | 'auto')[];
+/** Default `--limit`. */
+export declare const DEFAULT_LIMIT = 50;
+export interface CommonOptions {
+    readonly color: ColorMode;
+    readonly quiet: boolean;
+    readonly locale?: Locale;
+}
+export interface DiffCommandOptions extends CommonOptions {
+    /** Paths, or `-` for stdin. */
+    readonly before: string;
+    readonly after: string;
+    readonly beforeFormat: FormatId | 'auto';
+    readonly afterFormat: FormatId | 'auto';
+    /** `--lang`: RDF label language preference. */
+    readonly languages?: readonly string[];
+    readonly diff: DiffOptions;
+    readonly stat: boolean;
+    readonly nameStatus: boolean;
+    /** Output path, or `-` for stdout. */
+    readonly json?: string;
+    readonly delta?: string;
+    readonly markdown?: string;
+    readonly html?: string;
+    readonly open: boolean;
+    readonly pretty: boolean;
+    readonly title?: string;
+    readonly theme?: ThemePreference;
+    readonly mode?: ViewerMode;
+    readonly reproducible: boolean;
+    /** `--allow-empty`: an empty input is an empty graph instead of an error. */
+    readonly allowEmpty: boolean;
+    /** Inline the viewer's compute add-on when the report needs it (`--no-compute` disables). */
+    readonly compute: boolean;
+    readonly exitCode: boolean;
+    /** Max hunks in the summary; 0 = all. */
+    readonly limit: number;
+}
+export interface ApplyCommandOptions extends CommonOptions {
+    readonly graph: string;
+    readonly delta: string;
+    /** Output path, or `-` for stdout. */
+    readonly output: string;
+    readonly strict: boolean;
+    readonly format: FormatId | 'auto';
+    readonly languages?: readonly string[];
+    readonly pretty: boolean;
+    /** `--allow-empty`: an empty <graph> is an empty graph instead of an error. */
+    readonly allowEmpty: boolean;
+    /** `--verbose`: list the operations `--no-strict` skipped. */
+    readonly verbose: boolean;
+}
+export type Command = {
+    readonly kind: 'help';
+    readonly topic: 'main' | 'apply';
+    readonly color: ColorMode;
+} | {
+    readonly kind: 'version';
+} | {
+    readonly kind: 'diff';
+    readonly options: DiffCommandOptions;
+} | {
+    readonly kind: 'apply';
+    readonly options: ApplyCommandOptions;
+};
+interface OptionSpec {
+    readonly type: 'boolean' | 'string';
+    readonly short?: string;
+    readonly multiple?: boolean;
+    /** `--json [file]`: a string option whose value may be omitted. */
+    readonly optionalValue?: boolean;
+}
+/** Options of `kgdiff <before> <after>`. */
+export declare const DIFF_OPTIONS: Readonly<Record<string, OptionSpec>>;
+/** Options of `kgdiff apply <graph> <delta>`. */
+export declare const APPLY_OPTIONS: Readonly<Record<string, OptionSpec>>;
+/** Edit distance (insertions, deletions, substitutions, adjacent transpositions). */
+export declare function editDistance(a: string, b: string): number;
+/** Closest candidate within a small edit distance (or sharing a prefix), if any. */
+export declare function suggest(input: string, candidates: readonly string[]): string | undefined;
+/**
+ * Parse `argv` (without `node` and the script) into a command.
+ *
+ * @throws CliError `usage` with a message and a hint for any invalid command line.
+ */
+export declare function parseCommandLine(argv: readonly string[]): Command;
+/** Best-effort `--color` value for printing an error about the command line itself. */
+export declare function peekColorMode(argv: readonly string[]): ColorMode;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}