@kgdiff/cli 0.4.0 → 0.5.0

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;
   }
 }

package/src/markdown.ts

@@ -1,11 +1,22 @@
 /**
  * GitHub-flavoured Markdown summary for PR comments and `$GITHUB_STEP_SUMMARY`
- * (docs/cli.md §Markdown summary): title, diffstat table, family legend and the hunk list
- * grouped by phase in `<details>` blocks. No HTML beyond `<details>` / `<summary>`.
+ * (docs/cli.md §Markdown summary): title, diffstat table, family legend, the hunks that change
+ * a watched attribute (review first), the hunk list grouped by phase and the possible matches,
+ * in `<details>` blocks. No HTML beyond `<details>` / `<summary>`.
  */
-import { type DiffResult, formatHunk, type Locale } from '@kgdiff/core';
-import { formatInt, messages } from './locale.js';
-import { type ChangeFamily, groupByPhase, hunkFamily, hunkGlyph, overview } from './model.js';
+import { type DiffResult, formatHunk, type Hunk, type Locale } from '@kgdiff/core';
+import { formatInt, messages, watchLabels } from './locale.js';
+import {
+  type ChangeFamily,
+  DEFAULT_WATCH_ATTRS,
+  groupByPhase,
+  hunkFamily,
+  hunkGlyph,
+  overview,
+  percent,
+  possibleMatches,
+  watchedChanges,
+} from './model.js';
 import { totalsText } from './summary.js';
 import { revealInvisible } from './width.js';
 
@@ -13,6 +24,12 @@ import { revealInvisible } from './width.js';
 export const MARKDOWN_HUNK_LIMIT = 100;
 /** Groups start expanded when the whole list is at most this long. */
 const OPEN_THRESHOLD = 30;
+/** Hunks listed under "Review first" before "…and N more". */
+export const MARKDOWN_REVIEW_LIMIT = 20;
+/** Possible matches listed before "…and N more". */
+export const MARKDOWN_POSSIBLE_LIMIT = 20;
+/** The possible matches start expanded when there are at most this many. */
+const POSSIBLE_OPEN_THRESHOLD = 10;
 
 const FAMILY_SQUARE: Readonly<Record<ChangeFamily, string>> = {
   added: '🟩',
@@ -61,6 +78,11 @@ export interface MarkdownOptions {
   readonly title: string;
   /** e.g. `kgdiff 0.1.0`. */
   readonly generator: string;
+  /**
+   * Attribute keys whose changes are flagged ⚑ for review first (`--watch-attr`). Default
+   * `DEFAULT_WATCH_ATTRS` (definitions); `[]` flags nothing.
+   */
+  readonly watch?: readonly string[];
 }
 
 /** Render the Markdown summary. Deterministic: no timestamps. */
@@ -90,6 +112,10 @@ export function renderMarkdown(diff: DiffResult, options: MarkdownOptions): stri
       m.markdown.legend,
       '',
     );
+    const watch = options.watch ?? DEFAULT_WATCH_ATTRS;
+    const watched = watchedChanges(diff, watch);
+    const item = (hunk: Hunk): string => hunkItem(hunk, diff, options.locale, watched.get(hunk.id));
+    out.push(...reviewFirstSection(diff, watched, watch, options.locale, item));
     let budget = MARKDOWN_HUNK_LIMIT;
     const open = ov.hunks <= OPEN_THRESHOLD ? ' open' : '';
     for (const group of groupByPhase(diff.hunks)) {
@@ -101,19 +127,109 @@ export function renderMarkdown(diff: DiffResult, options: MarkdownOptions): stri
         `<summary>${m.phase[group.phase]} (${formatInt(group.hunks.length)})</summary>`,
         '',
       );
-      for (const hunk of listed) {
-        const { title, subtitle } = formatHunk(hunk, diff, options.locale);
-        const family = hunkFamily(hunk);
-        const glyph = hunkGlyph(hunk) === '~' ? '\\~' : hunkGlyph(hunk);
-        const note = subtitle ? ` — *${escapeMarkdown(subtitle)}*` : '';
-        out.push(`- ${FAMILY_SQUARE[family]} ${glyph} ${escapeMarkdown(title)}${note}`);
-      }
+      for (const hunk of listed) out.push(item(hunk));
       out.push('', '</details>', '');
     }
     if (ov.hunks > MARKDOWN_HUNK_LIMIT) {
       out.push(`*${escapeMarkdown(m.markdown.more(ov.hunks - MARKDOWN_HUNK_LIMIT))}*`, '');
     }
+    out.push(...possibleSection(diff, options.locale));
   }
   out.push(`*${escapeMarkdown(m.markdown.generatedBy(options.generator))}*`);
   return `${out.join('\n')}\n`;
 }
+
+/**
+ * A hunk as a list item: family square, glyph, title, then its summary in italics, after
+ * `⚑ definition` when it changes a watched attribute.
+ */
+function hunkItem(
+  hunk: Hunk,
+  diff: DiffResult,
+  locale: Locale,
+  watchedKeys: readonly string[] | undefined,
+): string {
+  const m = messages(locale);
+  const { title, subtitle } = formatHunk(hunk, diff, locale);
+  const glyph = hunkGlyph(hunk) === '~' ? '\\~' : hunkGlyph(hunk);
+  const flag = watchedKeys ? `⚑ ${m.watch.marker(watchLabels(watchedKeys, m))}` : '';
+  const note = [flag, subtitle].filter(Boolean).join(' · ');
+  return `- ${FAMILY_SQUARE[hunkFamily(hunk)]} ${glyph} ${escapeMarkdown(title)}${note ? ` — *${escapeMarkdown(note)}*` : ''}`;
+}
+
+/**
+ * The hunks that change a watched attribute, before the phase groups (which may start
+ * collapsed), in list order: a reworded definition can change what existing data means while
+ * the diff looks small. The same items in the groups carry the ⚑ marker. Empty when none.
+ */
+function reviewFirstSection(
+  diff: DiffResult,
+  watched: ReadonlyMap<string, readonly string[]>,
+  watch: readonly string[],
+  locale: Locale,
+  item: (hunk: Hunk) => string,
+): string[] {
+  if (watched.size === 0) return [];
+  const m = messages(locale);
+  const keys = new Set<string>();
+  for (const list of watched.values()) for (const key of list) keys.add(key);
+  const labels = watchLabels(
+    watch.filter((k) => keys.has(k)),
+    m,
+  );
+  const flagged = groupByPhase(diff.hunks).flatMap((g) => g.hunks.filter((h) => watched.has(h.id)));
+  const out = [
+    '<details open>',
+    `<summary>⚑ ${m.markdown.reviewFirst} (${formatInt(flagged.length)})</summary>`,
+    '',
+    `*${escapeMarkdown(m.markdown.reviewFirstHint(labels))}*`,
+    '',
+  ];
+  for (const hunk of flagged.slice(0, MARKDOWN_REVIEW_LIMIT)) out.push(item(hunk));
+  if (flagged.length > MARKDOWN_REVIEW_LIMIT) {
+    out.push(
+      '',
+      `*${escapeMarkdown(m.markdown.reviewFirstMore(flagged.length - MARKDOWN_REVIEW_LIMIT))}*`,
+    );
+  }
+  out.push('', '</details>', '');
+  return out;
+}
+
+/**
+ * The possible matches (`possibleMatches`): pairings kgdiff did not apply between a node listed
+ * as removed and one listed as added. In a pull request comment they are what tells a reviewer
+ * that "removed X" and "added Y" may be one entity. Empty when there are none.
+ */
+function possibleSection(diff: DiffResult, locale: Locale): string[] {
+  const possible = possibleMatches(diff);
+  if (possible.length === 0) return [];
+  const m = messages(locale);
+  const threshold = percent(diff.options.match.threshold);
+  const open = possible.length <= POSSIBLE_OPEN_THRESHOLD ? ' open' : '';
+  const out = [
+    `<details${open}>`,
+    `<summary>${m.possible.heading} (${formatInt(possible.length)})</summary>`,
+    '',
+    `*${m.markdown.possibleHint}*`,
+    '',
+  ];
+  for (const p of possible.slice(0, MARKDOWN_POSSIBLE_LIMIT)) {
+    const reason =
+      p.reason === 'ambiguous' ? m.possible.ambiguous : m.possible.belowThreshold(threshold);
+    const note = [
+      percent(p.score),
+      reason,
+      m.possible.evidence(percent(p.label), percent(p.neighbors)),
+    ].join(' · ');
+    out.push(`- ≈ ${escapeMarkdown(m.possible.title(p.before, p.after))} — *${note}*`);
+  }
+  if (possible.length > MARKDOWN_POSSIBLE_LIMIT) {
+    out.push(
+      '',
+      `*${escapeMarkdown(m.markdown.possibleMore(possible.length - MARKDOWN_POSSIBLE_LIMIT))}*`,
+    );
+  }
+  out.push('', '</details>', '');
+  return out;
+}

package/src/model.ts

@@ -1,8 +1,9 @@
 /**
  * Presentation model shared by every text output: hunk families, glyphs, name-status letters,
- * phase grouping and the per-phase counts behind the counters and the diffstat bar.
+ * phase grouping, the per-phase counts behind the counters and the diffstat bar, the watched
+ * attributes flagged for review first, and the possible matches listed after the hunks.
  */
-import type { DiffResult, Hunk, HunkKind, ReplayPhase } from '@kgdiff/core';
+import type { DiffResult, Hunk, HunkKind, MatchSuggestion, ReplayPhase } from '@kgdiff/core';
 
 /** The five meaning families of docs/visual-language.md (mirrors `@kgdiff/scene`). */
 export type ChangeFamily = 'added' | 'removed' | 'content' | 'structure' | 'identity';
@@ -176,6 +177,118 @@ export function apportion(weights: readonly number[], total: number): number[] {
   return cells;
 }
 
+/**
+ * Attributes watched by default: definitions, under the keys the formats give them (OBO `def`,
+ * kgdiff JSON `definition`, `IAO:0000115` for OBO ontologies in RDF, `skos:definition`). A
+ * reworded definition can change what existing data means while the diff looks small.
+ */
+export const DEFAULT_WATCH_ATTRS: readonly string[] = [
+  'def',
+  'definition',
+  'IAO:0000115',
+  'skos:definition',
+];
+
+const DEFINITION_KEYS: ReadonlySet<string> = new Set(DEFAULT_WATCH_ATTRS);
+
+/** Whether `key` is one of the default definition keys, shown as “definition”. */
+export function isDefinitionKey(key: string): boolean {
+  return DEFINITION_KEYS.has(key);
+}
+
+/**
+ * The watched attributes each hunk changes, by hunk id, in `watch` order; hunks that change
+ * none are absent. Only attribute changes of matched nodes count: an added or removed node's
+ * definition is part of that addition or removal, not a change to a definition. Ignored
+ * attributes (`ignoreAttrs`) never show up here, since the diff does not report them. O(changes).
+ */
+export function watchedChanges(
+  diff: DiffResult,
+  watch: readonly string[],
+): ReadonlyMap<string, readonly string[]> {
+  const watched = new Set(watch);
+  const byHunk = new Map<string, readonly string[]>();
+  if (watched.size === 0) return byHunk;
+  for (const hunk of diff.hunks) {
+    const keys = new Set<string>();
+    for (const id of hunk.nodes) {
+      for (const facet of diff.index.node(id)?.facets ?? []) {
+        if (facet.kind !== 'attrs') continue;
+        for (const change of facet.changes) if (watched.has(change.key)) keys.add(change.key);
+      }
+    }
+    if (keys.size > 0)
+      byHunk.set(
+        hunk.id,
+        [...watched].filter((k) => keys.has(k)),
+      );
+  }
+  return byHunk;
+}
+
+/** One side of a possible match: the node's id in its version and the name shown for it. */
+export interface PossibleMatchSide {
+  readonly id: string;
+  readonly name: string;
+}
+
+/** A pairing kgdiff considered but did not apply (a `MatchSuggestion`), ready to list. */
+export interface PossibleMatch {
+  readonly before: PossibleMatchSide;
+  readonly after: PossibleMatchSide;
+  readonly score: number;
+  readonly reason: MatchSuggestion['reason'];
+  /** Label and neighbourhood evidence, 0..1. */
+  readonly label: number;
+  readonly neighbors: number;
+}
+
+/** Longest name shown for either side (as hunk titles shorten names, @kgdiff/core i18n). */
+const MAX_POSSIBLE_NAME = 40;
+
+function shortName(label: string): string {
+  const chars = Array.from(label);
+  return chars.length > MAX_POSSIBLE_NAME
+    ? `${chars.slice(0, MAX_POSSIBLE_NAME - 1).join('')}…`
+    : label;
+}
+
+const byCodePoint = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+/**
+ * The suggestions a reviewer of the text outputs needs to see: pairings kgdiff did not apply
+ * where the before node is reported removed or the after node added, so that "removed X, added
+ * Y" can be read as "maybe X became Y". The viewer's detail panel lists the same ones. Names
+ * are the label each node had in its own version. Highest score first, then by ids.
+ */
+export function possibleMatches(diff: DiffResult): PossibleMatch[] {
+  const list: PossibleMatch[] = [];
+  for (const s of diff.suggestions) {
+    const before = diff.index.nodeByBefore(s.before);
+    const after = diff.index.nodeByAfter(s.after);
+    if (before?.status !== 'removed' && after?.status !== 'added') continue;
+    list.push({
+      before: { id: s.before, name: shortName(before?.before?.label ?? before?.label ?? s.before) },
+      after: { id: s.after, name: shortName(after?.after?.label ?? after?.label ?? s.after) },
+      score: s.score,
+      reason: s.reason,
+      label: s.evidence.label,
+      neighbors: s.evidence.neighbors,
+    });
+  }
+  return list.sort(
+    (x, y) =>
+      y.score - x.score ||
+      byCodePoint(x.before.id, y.before.id) ||
+      byCodePoint(x.after.id, y.after.id),
+  );
+}
+
+/** A score or evidence value as a whole percentage: `0.796` → `80%`. */
+export function percent(value: number): string {
+  return `${Math.round(value * 100)}%`;
+}
+
 export function assertNever(value: never): never {
   throw new Error(`Unexpected value: ${String(value)}`);
 }

package/src/node-io.ts

@@ -138,6 +138,7 @@ export function nodeIO(): CliIO {
     stderrIsTTY: process.stderr.isTTY === true,
     stdinIsTTY: process.stdin.isTTY === true,
     columns: process.stdout.isTTY ? process.stdout.columns : undefined,
+    runtime: `${process.platform} ${process.arch}, Node.js ${process.version}`,
     now: () => new Date(),
     makeTempDir: () => mkdtemp(join(tmpdir(), 'kgdiff-')),
     openFile,

package/src/report.ts

@@ -1,9 +1,9 @@
 /**
- * Build the `ReportPayload` embedded in HTML reports: diff (`diffToJSON`) + layout
+ * Build the `ReportPayload` embedded in HTML reports: packed diff (`packDiffJSON`) + layout
  * (`layoutToJSON`) + meta + initial view preferences. `@kgdiff/layout` and `node:zlib` are
  * loaded on demand, so text outputs never pay for them.
  */
-import { type DiffResult, diffToJSON, type Locale } from '@kgdiff/core';
+import { type DiffResult, diffToJSON, type Locale, packDiffJSON } from '@kgdiff/core';
 import type { ReportPayload, ThemePreference, ViewerMode, ViewerScope } from '@kgdiff/viewer';
 import { renderReportHtml } from './html.js';
 
@@ -34,7 +34,7 @@ export async function buildReportPayload(
   return {
     format: 'kgdiff.report',
     version: 1,
-    diff: diffToJSON(diff),
+    diff: packDiffJSON(diffToJSON(diff)),
     layout,
     meta: {
       title: info.title,