@kgdiff/cli 0.0.0-stage → 0.2.0

package/dist/help.js

@@ -0,0 +1,247 @@
+import { padEnd, stringWidth, wrap } from './width.js';
+const MAIN = [
+    {
+        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 = [
+    {
+        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, paint) {
+    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, version, paint, width) {
+    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 = [
+        `${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`;
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

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

package/dist/html.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 } from '@kgdiff/viewer';
+/** MIME type of the payload script (`PAYLOAD_SCRIPT_TYPE` in `@kgdiff/viewer`). */
+export declare const PAYLOAD_TYPE = "application/kgdiff+json";
+/** Payloads larger than this (UTF-8 bytes of the JSON) are embedded gzip + base64. */
+export declare const GZIP_THRESHOLD: number;
+/** Escape text for HTML element content and double-quoted attribute values. */
+export declare function escapeHtml(text: string): string;
+/**
+ * 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 declare function scriptSafeJson(json: string): string;
+/**
+ * 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 declare function scriptSafeJs(code: string): string;
+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;
+}
+/** Payload as embedded text plus its `data-encoding` (none, or `gzip-base64`). */
+export declare function encodePayload(payload: ReportPayload, gzip: (data: Uint8Array) => Uint8Array, threshold?: number): {
+    readonly text: string;
+    readonly 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 declare function renderReportHtml(options: ReportHtmlOptions): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,gBAAgB,CAAC;AAGrE,mFAAmF;AACnF,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,sFAAsF;AACtF,eAAO,MAAM,cAAc,QAAa,CAAC;AAQzC,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,CAAC;IAChD,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAUD,kFAAkF;AAClF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,EACtC,SAAS,SAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;CAAE,CAK9D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAkDnE"}

package/dist/html.js

@@ -0,0 +1,107 @@
+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) {
+    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) {
+    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) {
+    return code.replace(/<\/(script)/gi, '<\\/$1').replace(/<!--/g, '\\x3C!--');
+}
+function themeStyle(theme) {
+    const rule = (c) => `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, gzip, threshold = GZIP_THRESHOLD) {
+    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) {
+    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');
+}
+//# sourceMappingURL=html.js.map

package/dist/html.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,aAAa,EACb,KAAK,kBAAkB,EACvB,gBAAgB,EAChB,KAAK,GACN,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,YAAY,EACZ,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,KAAK,eAAe,EACpB,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,YAAY,EACjB,UAAU,EACV,SAAS,EACT,WAAW,EACX,KAAK,UAAU,EACf,UAAU,EACV,KAAK,QAAQ,EACb,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,aAAa,EACb,KAAK,OAAO,EACZ,iBAAiB,EACjB,SAAS,EACT,KAAK,IAAI,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * 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 { DEFAULT_LIMIT, parseCommandLine, STDIO, } from './args.js';
+export { defaultTitle, describeDiff, graphLabel, outputWidth } from './diff-command.js';
+export { CliError, describeError, formatError } from './errors.js';
+export { renderHelp } from './help.js';
+export { encodePayload, escapeHtml, GZIP_THRESHOLD, PAYLOAD_TYPE, renderReportHtml, scriptSafeJs, scriptSafeJson, } from './html.js';
+export { formatInt, matchLocale, messages, resolveLocale } from './locale.js';
+export { main } from './main.js';
+export { escapeMarkdown, MARKDOWN_HUNK_LIMIT, renderMarkdown, } from './markdown.js';
+export { hunkFamily, hunkGlyph, KIND_FAMILY, nameStatus, overview, } from './model.js';
+export { nodeIO, openCommand } from './node-io.js';
+export { buildReportHtml, buildReportPayload, createGzip } from './report.js';
+export { createPainter, resolveColorLevel, stripAnsi, } from './style.js';
+export { diffstatBar, renderNameStatus, renderStat, renderSummary, totalsText, } from './summary.js';
+export { cliVersion } from './version.js';
+export { graphemeWidth, padEnd, padStart, sanitize, stringWidth, truncate, wrap } from './width.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAIL,aAAa,EAEb,gBAAgB,EAChB,KAAK,GACN,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAqB,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,YAAY,EAEZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,cAAc,EACd,mBAAmB,EAEnB,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,UAAU,EACV,SAAS,EACT,WAAW,EAEX,UAAU,EAEV,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AAC/F,OAAO,EAGL,aAAa,EAEb,iBAAiB,EACjB,SAAS,GAEV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,aAAa,EAEb,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC"}

package/dist/inputs.d.ts

@@ -0,0 +1,54 @@
+import { type FormatId, type ParseResult } from '@kgdiff/formats';
+import type { CliIO } from './io.js';
+import type { Env } from './style.js';
+export declare const FORMAT_NAMES: Readonly<Record<FormatId, string>>;
+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;
+}
+/** Resolve a user-supplied path against the IO's working directory. */
+export declare function resolvePath(io: CliIO, path: string): string;
+/** Default input size limit (bytes, after decompression): 1 GiB. */
+export declare const DEFAULT_MAX_INPUT: number;
+/**
+ * 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 declare function maxInputBytes(env: Env): number;
+/**
+ * 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 declare function decodeText(bytes: Uint8Array, where: string, limit: number): Promise<string>;
+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 declare function readInput(io: CliIO, path: string, role: string, options?: ReadOptions): Promise<RawInput>;
+/**
+ * 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 declare function readPair(first: Promise<RawInput>, second: Promise<RawInput>): Promise<[RawInput, RawInput]>;
+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 declare function parseInput(input: RawInput, options: GraphParseOptions): ParseResult;
+//# sourceMappingURL=inputs.d.ts.map

package/dist/inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../src/inputs.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,QAAQ,EAAqB,KAAK,WAAW,EAAc,MAAM,iBAAiB,CAAC;AAGjG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAGtC,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAS3D,CAAC;AAEF,MAAM,WAAW,QAAQ;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAQD,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAI3C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAa9C;AAgCD;;;GAGG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCjG;AAED,MAAM,WAAW,WAAW;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,KAAK,EACT,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAuDnB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,EACxB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,GACxB,OAAO,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAK/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,GAAG,WAAW,CAgCnF"}