@kgdiff/cli 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kgdiff/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "git diff for knowledge graphs. Compare two graph files from the terminal, CI, or as a shareable HTML report.",
   "keywords": [
     "kgdiff",
@@ -45,11 +45,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kgdiff/core": "0.4.0",
-    "@kgdiff/formats": "0.4.0",
-    "@kgdiff/layout": "0.4.0",
-    "@kgdiff/scene": "0.4.0",
-    "@kgdiff/viewer": "0.4.0"
+    "@kgdiff/core": "0.6.0",
+    "@kgdiff/formats": "0.6.0",
+    "@kgdiff/layout": "0.6.0",
+    "@kgdiff/scene": "0.6.0",
+    "@kgdiff/viewer": "0.6.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/args.ts

@@ -12,7 +12,9 @@
 import { parseArgs } from 'node:util';
 import type { DiffOptions, EdgeIdentity, Locale, MatchOptions } from '@kgdiff/core';
 import type { FormatId } from '@kgdiff/formats';
-import type { ThemePreference, ViewerMode, ViewerScope } from '@kgdiff/viewer';
+import type { ThemePreference, ViewerMode, ViewerPanels, ViewerScope } from '@kgdiff/viewer';
+// The viewer's own panels syntax (no DOM): `--panels` reads exactly what `panels` does.
+import { PANEL_REGIONS, PANEL_STATES, parsePanels } from '@kgdiff/viewer/panels';
 import { CliError } from './errors.js';
 import { matchLocale } from './locale.js';
 import type { ColorMode } from './style.js';
@@ -38,7 +40,6 @@ const THEMES: readonly ThemePreference[] = ['auto', 'light', 'dark'];
 const MODES: readonly (ViewerMode | 'changes')[] = ['overlay', 'swipe', 'replay', 'changes'];
 const SCOPES: readonly ViewerScope[] = ['all', 'changes'];
 const COLOR_MODES: readonly ColorMode[] = ['auto', 'always', 'never'];
-
 /** Default `--limit`. */
 export const DEFAULT_LIMIT = 50;
 
@@ -70,6 +71,8 @@ export interface DiffCommandOptions extends CommonOptions {
   readonly theme?: ThemePreference;
   readonly mode?: ViewerMode;
   readonly scope?: ViewerScope;
+  /** `--panels`: the report's initial panel states (`view.panels`). */
+  readonly panels?: ViewerPanels;
   readonly reproducible: boolean;
   /** `--allow-empty`: an empty input is an empty graph instead of an error. */
   readonly allowEmpty: boolean;
@@ -78,6 +81,11 @@ export interface DiffCommandOptions extends CommonOptions {
   readonly exitCode: boolean;
   /** Max hunks in the summary; 0 = all. */
   readonly limit: number;
+  /**
+   * `--watch-attr`: attributes whose changes are flagged ⚑ for review first, replacing the
+   * default definitions. Absent when not given.
+   */
+  readonly watchAttrs?: readonly string[];
 }
 
 export interface ApplyCommandOptions extends CommonOptions {
@@ -143,11 +151,13 @@ export const DIFF_OPTIONS: Readonly<Record<string, OptionSpec>> = {
   theme: { type: 'string' },
   mode: { type: 'string' },
   scope: { type: 'string' },
+  panels: { type: 'string', multiple: true },
   reproducible: { type: 'boolean' },
   'no-compute': { type: 'boolean' },
   'allow-empty': { type: 'boolean' },
   'exit-code': { type: 'boolean' },
   limit: { type: 'string' },
+  'watch-attr': { type: 'string', multiple: true },
 };
 
 /** Options of `kgdiff apply <graph> <delta>`. */
@@ -217,6 +227,42 @@ function usageError(message: string, hint = HELP_HINT): CliError {
   return new CliError('usage', message, hint);
 }
 
+/**
+ * `--panels "detail:collapsed minimap:hidden"` (pairs separated by spaces or commas, the option
+ * repeatable), read by the viewer's own parser; a region named twice takes the last state. The
+ * first pair it rejects becomes a usage error that says what is wrong with it.
+ */
+function panelsOption(values: readonly string[]): ViewerPanels | undefined {
+  const { panels, invalid } = parsePanels(values.join(' '));
+  const [token] = invalid;
+  if (token !== undefined) throw panelsError(token);
+  return Object.keys(panels).length > 0 ? panels : undefined;
+}
+
+/** Why `parsePanels` rejected `token`: not a pair, an unknown region, or an unknown state. */
+function panelsError(token: string): CliError {
+  const regions = `Regions: ${PANEL_REGIONS.join(', ')}; states: ${PANEL_STATES.join(', ')}.`;
+  const [region = '', state, ...rest] = token.split(':');
+  if (state === undefined || rest.length > 0) {
+    return usageError(
+      `Invalid value "${token}" for --panels.`,
+      `Expected region:state pairs, e.g. --panels "detail:collapsed minimap:hidden". ${regions}`,
+    );
+  }
+  if (!(PANEL_REGIONS as readonly string[]).includes(region)) {
+    const close = suggest(region, PANEL_REGIONS);
+    return usageError(
+      `Unknown panel region "${region}" in --panels.`,
+      `${close ? `Did you mean "${close}"? ` : ''}${regions}`,
+    );
+  }
+  const close = suggest(state, PANEL_STATES);
+  return usageError(
+    `Invalid state "${state}" for the ${region} panel in --panels.`,
+    `${close ? `Did you mean "${close}"? ` : ''}Expected one of: ${PANEL_STATES.join(', ')}.`,
+  );
+}
+
 function choice<T extends string>(name: string, value: string, choices: readonly T[]): T {
   if ((choices as readonly string[]).includes(value)) return value as T;
   const close = suggest(value, choices);
@@ -492,6 +538,7 @@ function parseDiff(argv: readonly string[]): Command {
       : mode === 'changes'
         ? 'changes'
         : undefined;
+  const panels = panelsOption(v.strings('panels'));
   const limit = v.string('limit');
   const languages = parseLanguages(v);
   const title = v.string('title');
@@ -499,6 +546,13 @@ function parseDiff(argv: readonly string[]): Command {
   const delta = v.target('delta');
   const markdown = v.target('markdown');
   const html = v.string('html');
+  const watchAttrs = v.strings('watch-attr');
+  if (watchAttrs.some((key) => key.trim() === '')) {
+    throw usageError(
+      '--watch-attr needs an attribute key.',
+      'e.g. --watch-attr rdfs:comment. Attribute keys are listed in the JSON output (--json).',
+    );
+  }
   const options: DiffCommandOptions = {
     ...common,
     before,
@@ -519,6 +573,7 @@ function parseDiff(argv: readonly string[]): Command {
     ...(theme !== undefined ? { theme: choice('theme', theme, THEMES) } : {}),
     ...(mode !== undefined ? { mode: mode === 'changes' ? 'overlay' : mode } : {}),
     ...(scope !== undefined ? { scope } : {}),
+    ...(panels !== undefined ? { panels } : {}),
     reproducible: v.flag('reproducible'),
     compute: !v.flag('no-compute'),
     allowEmpty: v.flag('allow-empty'),
@@ -527,6 +582,7 @@ function parseDiff(argv: readonly string[]): Command {
       limit === undefined
         ? DEFAULT_LIMIT
         : parseNumber('limit', limit, 0, Number.MAX_SAFE_INTEGER, true),
+    ...(watchAttrs.length > 0 ? { watchAttrs } : {}),
   };
   checkOutputs(options);
   return { kind: 'diff', options };

package/src/diff-command.ts

@@ -235,7 +235,12 @@ export async function runDiff(o: DiffCommandOptions, io: CliIO): Promise<number>
   }
   if (o.markdown !== undefined) {
     const { renderMarkdown } = await import('./markdown.js');
-    const md = renderMarkdown(result, { locale: ctx.locale, title, generator });
+    const md = renderMarkdown(result, {
+      locale: ctx.locale,
+      title,
+      generator,
+      ...(o.watchAttrs ? { watch: o.watchAttrs } : {}),
+    });
     if (o.markdown !== STDIO)
       files.push({ path: o.markdown, content: md, label: 'Markdown summary' });
     else stdoutText = md;
@@ -255,6 +260,7 @@ export async function runDiff(o: DiffCommandOptions, io: CliIO): Promise<number>
           ...(o.scope ? { scope: o.scope } : {}),
           ...(o.theme ? { theme: o.theme } : {}),
           locale: ctx.locale,
+          ...(o.panels ? { panels: o.panels } : {}),
         },
       },
       { main: bundle, compute: () => loadCompute(o, io, ctx) },
@@ -284,6 +290,7 @@ export async function runDiff(o: DiffCommandOptions, io: CliIO): Promise<number>
       locale: ctx.locale,
       width: outputWidth(io),
       limit: o.limit,
+      ...(o.watchAttrs ? { watch: o.watchAttrs } : {}),
     };
     if (o.json === STDIO) stdoutText = json(diffToJSON(result), o.pretty);
     else if (o.delta === STDIO) stdoutText = json(result.delta, o.pretty);

package/src/errors.ts

@@ -78,8 +78,27 @@ const KGDIFF_HINTS: Readonly<Record<string, string>> = {
   'dangling-edge': 'An edge refers to a node the graph does not define.',
 };
 
+/** The bug report form an unexpected error links to. */
+const BUG_REPORT_FORM = 'https://github.com/iiwish/kgdiff/issues/new';
+
+/**
+ * Link to the bug report form, prefilled through the form's field ids (`version`,
+ * `environment`). Only public metadata goes into it: error messages and input paths can contain
+ * private data, and the person reporting decides what to paste into the form.
+ */
+export function bugReportUrl(version: string, runtime?: string): string {
+  const url = new URL(BUG_REPORT_FORM);
+  url.searchParams.set('template', 'bug_report.yml');
+  url.searchParams.set('version', `kgdiff ${version}`);
+  if (runtime) url.searchParams.set('environment', runtime);
+  return url.href;
+}
+
 /** User-facing message and hint for any thrown value. */
-export function describeError(error: unknown): { message: string; hint?: string } {
+export function describeError(
+  error: unknown,
+  bugReportUrl?: string,
+): { message: string; hint?: string } {
   if (error instanceof CliError) {
     return error.hint ? { message: error.message, hint: error.hint } : { message: error.message };
   }
@@ -91,7 +110,9 @@ export function describeError(error: unknown): { message: string; hint?: string
   if (code) return { message: systemReason(error) };
   return {
     message: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
-    hint: 'This is a bug in kgdiff. Run again with DEBUG=kgdiff and report the output.',
+    hint: bugReportUrl
+      ? `This is a bug in kgdiff. Run again with DEBUG=kgdiff and report it: ${bugReportUrl}`
+      : 'This is a bug in kgdiff. Run again with DEBUG=kgdiff and report the output.',
   };
 }
 
@@ -103,10 +124,15 @@ export function debugEnabled(debug: string | undefined): boolean {
 }
 
 /** The text written to stderr for an error (ends with a newline). */
-export function formatError(error: unknown, paint: Painter, debug: boolean): string {
+export function formatError(
+  error: unknown,
+  paint: Painter,
+  debug: boolean,
+  bugReportUrl?: string,
+): string {
   // Messages quote user input (paths, parser snippets, JSON.parse excerpts): never let it
   // carry escape sequences or bidi controls to the terminal.
-  const { message, hint } = describeError(error);
+  const { message, hint } = describeError(error, bugReportUrl);
   const lines = [`${paint.bold(paint.tone('removed', 'error:'))} ${sanitize(message)}`];
   if (hint) lines.push(`${paint.tone('accent', 'hint:')} ${sanitize(hint)}`);
   if (debug) {

package/src/help.ts

@@ -110,6 +110,10 @@ const MAIN: readonly Section[] = [
         text: 'Show the whole graph or only the changes (in any mode): all, changes',
         default: 'changes for large graphs, else all',
       },
+      {
+        flags: '--panels <spec>',
+        text: 'Initial panel states, e.g. "detail:collapsed minimap:hidden" (repeatable)',
+      },
       {
         flags: '--reproducible',
         text: 'Omit the timestamp: byte-identical reports for identical input',
@@ -138,6 +142,11 @@ const MAIN: readonly Section[] = [
         default: 'auto',
       },
       { flags: '--limit <n>', text: 'Hunks listed in the summary; 0 lists all', default: '50' },
+      {
+        flags: '--watch-attr <key>',
+        text: 'Flag changes to this attribute ⚑ for review first (repeatable); replaces the defaults',
+        default: 'definitions',
+      },
       { flags: '-h, --help', text: 'Show this help' },
       { flags: '-v, --version', text: 'Show the version' },
     ],

package/src/html.ts

@@ -107,8 +107,8 @@ export function renderReportHtml(options: ReportHtmlOptions): string {
     `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)}"`,
+    // Theme, language and panels travel in the payload's `view`, not as attributes: what the
+    // reader chose in an earlier report (remembered by the viewer) wins over them.
     ...(view.mode ? [`mode="${escapeHtml(view.mode)}"`] : []),
     ...(view.scope ? [`scope="${escapeHtml(view.scope)}"`] : []),
   ].join(' ');

package/src/index.ts

@@ -40,6 +40,7 @@ export {
 } from './markdown.js';
 export {
   type ChangeFamily,
+  DEFAULT_WATCH_ATTRS,
   hunkFamily,
   hunkGlyph,
   KIND_FAMILY,
@@ -47,6 +48,7 @@ export {
   nameStatus,
   type Overview,
   overview,
+  watchedChanges,
 } from './model.js';
 export { nodeIO, openCommand } from './node-io.js';
 export { buildReportHtml, buildReportPayload, createGzip, type ReportInfo } from './report.js';

package/src/io.ts

@@ -52,6 +52,11 @@ export interface CliIO {
   readonly stdinIsTTY: boolean;
   /** Terminal width of stdout, when known. */
   readonly columns: number | undefined;
+  /**
+   * The platform and runtime, for bug reports: `darwin arm64, Node.js v24.11.0`. Optional:
+   * without it the bug report link of an unexpected error names only the CLI version.
+   */
+  readonly runtime?: string;
   /** Clock for `generatedAt` in HTML reports. */
   now(): Date;
   /** Create a fresh private directory (`mkdtemp`) for reports opened with `--open` and no `-o`. */

package/src/locale.ts

@@ -4,7 +4,7 @@
  * searched for.
  */
 import type { Locale, ReplayPhase } from '@kgdiff/core';
-import type { ChangeFamily } from './model.js';
+import { type ChangeFamily, isDefinitionKey, type PossibleMatchSide } from './model.js';
 import type { Env } from './style.js';
 
 export const LOCALES: readonly Locale[] = ['en', 'zh-CN'];
@@ -67,13 +67,71 @@ export interface Messages {
   readonly byType: string;
   readonly untyped: string;
   readonly moreTypes: (n: number) => string;
+  /** Watched attributes (`--watch-attr`): changes flagged ⚑ for review first. */
+  readonly watch: {
+    /** How the default definition keys (`def`, `IAO:0000115`, …) are named. */
+    readonly definition: string;
+    /** After ⚑ under the diffstat bar: `Review first: definition changed in 10 hunks`. */
+    readonly line: (labels: readonly string[], hunks: number) => string;
+    /** After ⚑ in a hunk's summary: `definition`. */
+    readonly marker: (labels: readonly string[]) => string;
+  };
+  /** Pairings kgdiff considered but did not apply, listed after the hunks. */
+  readonly possible: {
+    readonly heading: string;
+    /** `“Saudi Aramco” → “Aramco”`; each side's id is added when both have the same name. */
+    readonly title: (before: PossibleMatchSide, after: PossibleMatchSide) => string;
+    readonly belowThreshold: (threshold: string) => string;
+    readonly ambiguous: string;
+    readonly evidence: (label: string, neighbors: string) => string;
+    /** Terminal: what "not applied" means and how to pair one. */
+    readonly hint: string;
+    readonly more: (n: number) => string;
+  };
   readonly markdown: {
     readonly legend: string;
     readonly more: (n: number) => string;
+    /** Heading of the block of hunks that change a watched attribute (after ⚑). */
+    readonly reviewFirst: string;
+    readonly reviewFirstHint: (labels: readonly string[]) => string;
+    readonly reviewFirstMore: (n: number) => string;
+    /** Like `possible.hint`, as Markdown. */
+    readonly possibleHint: string;
+    readonly possibleMore: (n: number) => string;
     readonly generatedBy: (generator: string) => string;
   };
 }
 
+/**
+ * Display names of watched attribute keys, in order: the default definition keys are all
+ * “definition” (once), other keys are shown as they are.
+ */
+export function watchLabels(keys: readonly string[], m: Messages): string[] {
+  const labels: string[] = [];
+  for (const key of keys) {
+    const label = isDefinitionKey(key) ? m.watch.definition : key;
+    if (!labels.includes(label)) labels.push(label);
+  }
+  return labels;
+}
+
+/**
+ * Both sides of a possible match, quoted and joined by `arrow`. When they share a name (two
+ * “Apple”s), `withId` adds each side's id, as hunk titles do for equally named nodes.
+ */
+function possibleTitle(
+  before: PossibleMatchSide,
+  after: PossibleMatchSide,
+  quote: (name: string) => string,
+  withId: (quoted: string, id: string) => string,
+  arrow: string,
+): string {
+  const same = before.name === after.name;
+  const side = (s: PossibleMatchSide): string =>
+    same ? withId(quote(s.name), s.id) : quote(s.name);
+  return `${side(before)}${arrow}${side(after)}`;
+}
+
 /** A count before and after the change. */
 export type Count = readonly [before: number, after: number];
 
@@ -123,12 +181,47 @@ const en: Messages = {
   byType: 'By type',
   untyped: '(untyped)',
   moreTypes: (n) => `… and ${plural(n, 'more type', 'more types')}`,
+  watch: {
+    definition: 'definition',
+    line: (labels, hunks) =>
+      `Review first: ${labels.join(', ')} changed in ${plural(hunks, 'hunk', 'hunks')}`,
+    marker: (labels) => labels.join(', '),
+  },
+  possible: {
+    heading: 'Possible matches',
+    title: (before, after) =>
+      possibleTitle(
+        before,
+        after,
+        (name) => `“${name}”`,
+        (quoted, id) => `${quoted} (${id})`,
+        ' → ',
+      ),
+    belowThreshold: (threshold) => `below the ${threshold} threshold`,
+    ambiguous: 'too close to another candidate',
+    evidence: (label, neighbors) => `name ${label} · neighbours ${neighbors}`,
+    hint:
+      'Not paired, so listed as removed or added. To pair one, add a synonym or a ' +
+      'replacement link, or lower --threshold.',
+    more: (n) => `… and ${formatInt(n)} more · --json lists all`,
+  },
   markdown: {
     legend:
       '🟩 added · 🟥 removed · 🟨 content (renames, attributes, types, synonyms) · ' +
       '🟦 structure (moves, relations) · 🟪 identity (merges, splits)',
     more: (n) =>
       `…and ${plural(n, 'more hunk', 'more hunks')}. Open the HTML report for the full list.`,
+    reviewFirst: 'Review first',
+    reviewFirstHint: (labels) =>
+      `These hunks change a watched attribute (${labels.join(', ')}). Such an edit can change ` +
+      'what existing data means even when the diff looks small.',
+    reviewFirstMore: (n) => `…and ${formatInt(n)} more.`,
+    possibleHint:
+      'kgdiff did not pair these nodes, so they are listed above as removed or added. If a ' +
+      'pair is the same thing, add a synonym or a replacement link, or lower `--threshold`.',
+    possibleMore: (n) =>
+      `…and ${plural(n, 'more possible match', 'more possible matches')}. The HTML report ` +
+      "shows them in each node's details.",
     generatedBy: (generator) => `Generated by ${generator}`,
   },
 };
@@ -162,10 +255,39 @@ const zh: Messages = {
   byType: '按类型',
   untyped: '（无类型）',
   moreTypes: (n) => `… 另有 ${formatInt(n)} 个类型`,
+  watch: {
+    definition: '定义',
+    line: (labels, hunks) => `优先审查：${formatInt(hunks)} 组变更修改了${labels.join('、')}`,
+    marker: (labels) => labels.join('、'),
+  },
+  possible: {
+    heading: '可能的匹配',
+    title: (before, after) =>
+      possibleTitle(
+        before,
+        after,
+        (name) => `「${name}」`,
+        (quoted, id) => `${quoted}（${id}）`,
+        '→',
+      ),
+    belowThreshold: (threshold) => `低于阈值 ${threshold}`,
+    ambiguous: '与其他候选过于接近',
+    evidence: (label, neighbors) => `名称 ${label} · 邻居 ${neighbors}`,
+    hint: '这些节点未配对，因此按删除或新增列出。如是同一节点，可补充别名或替换链接，或调低 --threshold。',
+    more: (n) => `… 另有 ${formatInt(n)} 对 · --json 列出全部`,
+  },
   markdown: {
     legend:
       '🟩 新增 · 🟥 删除 · 🟨 内容（改名、属性、类型、别名） · 🟦 结构（移动、关系） · 🟪 身份（合并、拆分、换 ID）',
     more: (n) => `……另有 ${formatInt(n)} 组变更未列出，完整列表请查看 HTML 报告。`,
+    reviewFirst: '优先审查',
+    reviewFirstHint: (labels) =>
+      `这些变更修改了受关注的属性（${labels.join('、')}）。这类修改在差异里看起来很小，却可能改变已有数据的含义。`,
+    reviewFirstMore: (n) => `……另有 ${formatInt(n)} 组。`,
+    possibleHint:
+      'kgdiff 没有配对这些节点，因此它们在上方按删除或新增列出。如果某一对其实是同一节点，可补充别名或替换链接，或调低 `--threshold`。',
+    possibleMore: (n) =>
+      `……另有 ${formatInt(n)} 对可能的匹配未列出，HTML 报告的节点详情中可以看到全部。`,
     generatedBy: (generator) => `由 ${generator} 生成`,
   },
 };

package/src/main.ts

@@ -4,7 +4,7 @@
  * load the diff engine.
  */
 import { parseCommandLine, peekColorMode } from './args.js';
-import { debugEnabled, formatError } from './errors.js';
+import { bugReportUrl, debugEnabled, formatError } from './errors.js';
 import { renderHelp } from './help.js';
 import type { CliIO } from './io.js';
 import { createPainter, isLightBackground, resolveColorLevel } from './style.js';
@@ -50,7 +50,10 @@ export async function main(argv: readonly string[], io: CliIO): Promise<number>
       resolveColorLevel(peekColorMode(argv), io.env, io.stderrIsTTY),
       light,
     );
-    io.stderr.write(formatError(error, paint, debugEnabled(io.env.DEBUG)));
+    // The platform comes from `io` like every other side effect, so `main` stays runnable
+    // in-process and its output deterministic in tests.
+    const report = bugReportUrl(cliVersion(), io.runtime);
+    io.stderr.write(formatError(error, paint, debugEnabled(io.env.DEBUG), report));
     return 2;
   }
 }