@kgdiff/cli 0.3.0 → 0.5.0

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,10 +1,10 @@
 /**
- * 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 { ReportPayload, ThemePreference, ViewerMode } from '@kgdiff/viewer';
+import { type DiffResult, diffToJSON, type Locale, packDiffJSON } from '@kgdiff/core';
+import type { ReportPayload, ThemePreference, ViewerMode, ViewerScope } from '@kgdiff/viewer';
 import { renderReportHtml } from './html.js';
 
 export interface ReportInfo {
@@ -17,6 +17,7 @@ export interface ReportInfo {
   readonly after: { readonly name: string; readonly format?: string };
   readonly view: {
     readonly mode?: ViewerMode;
+    readonly scope?: ViewerScope;
     readonly theme?: ThemePreference;
     readonly locale: Locale;
   };
@@ -29,11 +30,11 @@ export async function buildReportPayload(
 ): Promise<ReportPayload> {
   const { layoutDiff, layoutToJSON } = await import('@kgdiff/layout');
   const layout = layoutToJSON(layoutDiff(diff));
-  const { mode, theme, locale } = info.view;
+  const { mode, scope, theme, locale } = info.view;
   return {
     format: 'kgdiff.report',
     version: 1,
-    diff: diffToJSON(diff),
+    diff: packDiffJSON(diffToJSON(diff)),
     layout,
     meta: {
       title: info.title,
@@ -44,6 +45,7 @@ export async function buildReportPayload(
     },
     view: {
       ...(mode !== undefined ? { mode } : {}),
+      ...(scope !== undefined ? { scope } : {}),
       ...(theme !== undefined ? { theme } : {}),
       locale,
     },

package/src/summary.ts

@@ -1,15 +1,17 @@
 /**
- * Terminal outputs: the default summary (header, counters, diffstat bar, hunk list), `--stat`
- * and `--name-status` (docs/cli.md §Terminal summary).
+ * Terminal outputs: the default summary (header, counters, diffstat bar, hunk list, possible
+ * matches), `--stat` and `--name-status` (docs/cli.md §Terminal summary).
  *
  * Every line is laid out on plain text first (measured with `stringWidth`, truncated with an
  * ellipsis) and painted last, so alignment holds with and without color and with CJK labels.
  */
 import { type DiffResult, formatHunk, type Hunk, type Locale } from '@kgdiff/core';
-import { formatInt, type Messages, messages } from './locale.js';
+import { formatInt, type Messages, messages, watchLabels } from './locale.js';
 import {
   apportion,
+  type ChangeFamily,
   COUNTER_PHASES,
+  DEFAULT_WATCH_ATTRS,
   groupByPhase,
   hunkFamily,
   hunkGlyph,
@@ -18,6 +20,10 @@ import {
   overview,
   PHASE_FAMILY,
   PHASE_GLYPH,
+  type PossibleMatch,
+  percent,
+  possibleMatches,
+  watchedChanges,
 } from './model.js';
 import type { Painter } from './style.js';
 import { padEnd, padStart, sanitize, stringWidth, truncate, wrap } from './width.js';
@@ -29,6 +35,35 @@ export interface TextContext {
   readonly width: number;
   /** Maximum hunks listed in the summary; 0 lists all. */
   readonly limit: number;
+  /**
+   * Attribute keys whose changes are flagged ⚑ for review first (`--watch-attr`). Default
+   * `DEFAULT_WATCH_ATTRS` (definitions); `[]` flags nothing.
+   */
+  readonly watch?: readonly string[];
+}
+
+/** Flag glyph of hunks that change a watched attribute. */
+const FLAG = '⚑';
+
+/** The watched attributes each hunk changes, for `ctx.watch` or the default definitions. */
+function watchedOf(diff: DiffResult, ctx: TextContext): ReadonlyMap<string, readonly string[]> {
+  return watchedChanges(diff, ctx.watch ?? DEFAULT_WATCH_ATTRS);
+}
+
+/** `⚑ Review first: definition changed in 10 hunks`, under the diffstat bar; none if no flags. */
+function reviewFirstLines(
+  watched: ReadonlyMap<string, readonly string[]>,
+  ctx: TextContext,
+  width: number,
+): string[] {
+  if (watched.size === 0) return [];
+  const m = messages(ctx.locale);
+  const keys = new Set<string>();
+  for (const list of watched.values()) for (const key of list) keys.add(key);
+  const watchOrder = (ctx.watch ?? DEFAULT_WATCH_ATTRS).filter((k) => keys.has(k));
+  const text = m.watch.line(watchLabels(watchOrder, m), watched.size);
+  const room = width - INDENT.length - stringWidth(FLAG) - 1;
+  return [`${INDENT}${ctx.paint.tone('accent', FLAG)} ${truncate(sanitize(text), room)}`];
 }
 
 const INDENT = '  ';
@@ -135,7 +170,13 @@ export function diffstatBar(ov: Overview, width: number, paint: Painter): string
   }).join('');
 }
 
-function statLines(ov: Overview, ctx: TextContext, width: number): string[] {
+/** Counters, the diffstat bar, and the review-first line when a watched attribute changed. */
+function statLines(
+  ov: Overview,
+  ctx: TextContext,
+  width: number,
+  watched: ReadonlyMap<string, readonly string[]>,
+): string[] {
   const m = messages(ctx.locale);
   const right = m.changes(ov.changes, ov.hunks);
   const rows = counterLines(counterItems(ov, m, ctx.paint), width - INDENT.length);
@@ -149,6 +190,7 @@ function statLines(ov: Overview, ctx: TextContext, width: number): string[] {
     ),
   );
   lines.push(INDENT + diffstatBar(ov, width, ctx.paint));
+  lines.push(...reviewFirstLines(watched, ctx, width));
   return lines;
 }
 
@@ -169,30 +211,67 @@ function identicalLines(diff: DiffResult, ctx: TextContext, width: number): stri
   ];
 }
 
+/** A line of the hunk list (or of the possible matches): glyph, title, family and summary. */
 interface Row {
-  readonly hunk: Hunk;
+  /** Colour of the glyph and the family label. */
+  readonly tone: ChangeFamily;
   readonly glyph: string;
   readonly title: string;
   readonly family: string;
+  /** Watched attributes the hunk changes (`definition`), shown as `⚑ definition`. */
+  readonly flag?: string;
   readonly subtitle: string;
 }
 
-function rowsOf(diff: DiffResult, hunks: readonly Hunk[], ctx: TextContext): Row[] {
+function rowsOf(
+  diff: DiffResult,
+  hunks: readonly Hunk[],
+  ctx: TextContext,
+  watched: ReadonlyMap<string, readonly string[]>,
+): Row[] {
   const m = messages(ctx.locale);
   return hunks.map((hunk) => {
     const { title, subtitle } = formatHunk(hunk, diff, ctx.locale);
+    const keys = watched.get(hunk.id);
     return {
-      hunk,
+      tone: hunkFamily(hunk),
       glyph: hunkGlyph(hunk),
       title: sanitize(title),
       family: m.family[hunkFamily(hunk)],
+      ...(keys ? { flag: sanitize(m.watch.marker(watchLabels(keys, m))) } : {}),
       subtitle: sanitize(subtitle),
     };
   });
 }
 
-const rightText = (row: Row): string =>
-  row.subtitle ? `${row.family} · ${row.subtitle}` : row.family;
+/** What follows the family label: ` · ⚑ definition · <subtitle>`, as plain text. */
+const restText = (row: Row): string =>
+  (row.flag ? ` · ${FLAG} ${row.flag}` : '') + (row.subtitle ? ` · ${row.subtitle}` : '');
+
+/** Glyph of a possible match: “maybe the same”. */
+const POSSIBLE_GLYPH = '≈';
+/** Possible matches listed before "… and N more" (all with `--limit 0`). */
+export const POSSIBLE_LIMIT = 10;
+
+/** Possible match rows: both names, then the score, why it was not applied and the evidence. */
+function possibleRows(diff: DiffResult, list: readonly PossibleMatch[], ctx: TextContext): Row[] {
+  const m = messages(ctx.locale);
+  const threshold = percent(diff.options.match.threshold);
+  return list.map((p) => ({
+    tone: 'identity',
+    glyph: POSSIBLE_GLYPH,
+    title: sanitize(m.possible.title(p.before, p.after)),
+    family: percent(p.score),
+    subtitle: sanitize(
+      [
+        p.reason === 'ambiguous' ? m.possible.ambiguous : m.possible.belowThreshold(threshold),
+        m.possible.evidence(percent(p.label), percent(p.neighbors)),
+      ].join(' · '),
+    ),
+  }));
+}
+
+const rightText = (row: Row): string => row.family + restText(row);
 
 /** Natural width of the hunk list (before any truncation). */
 function listWidth(rows: readonly Row[]): number {
@@ -229,16 +308,24 @@ function listColumns(rows: readonly Row[], width: number): { title: number; righ
 
 function renderRow(row: Row, cols: { title: number; right: number }, ctx: TextContext): string {
   const { paint } = ctx;
-  const tone = hunkFamily(row.hunk);
+  const tone = row.tone;
   const glyph = paint.tone(tone, row.glyph);
   if (cols.right === 0) return `${INDENT}${glyph} ${truncate(row.title, cols.title)}`;
   const title = padEnd(truncate(row.title, cols.title), cols.title);
   const familyWidth = stringWidth(row.family);
   const restRoom = cols.right - familyWidth;
-  const rest = row.subtitle && restRoom >= 6 ? truncate(` · ${row.subtitle}`, restRoom) : '';
+  const full = restText(row);
+  const rest = full && restRoom >= 6 ? truncate(full, restRoom) : '';
+  // The flag comes first, so it survives truncation, and keeps the accent colour; the summary
+  // after it is dimmed.
+  const flag = row.flag ? ` · ${FLAG} ${row.flag}` : '';
+  const flagShown = flag ? rest.slice(0, Math.min(rest.length, flag.length)) : '';
+  const painted = flagShown
+    ? paint.dim(flagShown.slice(0, 3)) + paint.tone('accent', flagShown.slice(3))
+    : '';
   return (
     `${INDENT}${glyph} ${title}${' '.repeat(COLUMN_GAP)}` +
-    `${paint.tone(tone, row.family)}${paint.dim(rest)}`
+    `${paint.tone(tone, row.family)}${painted}${paint.dim(rest.slice(flagShown.length))}`
   );
 }
 
@@ -268,6 +355,13 @@ function headerNatural(diff: DiffResult, title: string, ctx: TextContext, ov: Ov
  * The default terminal output: header (title, node and edge totals), per-phase counters, a
  * proportional diffstat bar, then the hunks grouped by phase with glyph, title and a family /
  * summary column. At most `ctx.limit` hunks are listed (0 = all), then "… and N more".
+ * Hunks that change a watched attribute (`ctx.watch`, definitions by default) are marked
+ * `⚑ definition` before their summary, and a line under the bar counts them.
+ *
+ * Last come the possible matches: pairings kgdiff considered but did not apply, between a node
+ * listed as removed and one listed as added (`possibleMatches`), with their score, why they were
+ * not applied, the evidence, and how to pair one. At most `POSSIBLE_LIMIT` (all with
+ * `--limit 0`).
  */
 export function renderSummary(diff: DiffResult, title: string, ctx: TextContext): string {
   const ov = overview(diff);
@@ -275,33 +369,61 @@ export function renderSummary(diff: DiffResult, title: string, ctx: TextContext)
     const width = layoutWidth(headerNatural(diff, title, ctx, ov), ctx.width);
     return `${[...headerLines(diff, title, ctx, width), '', ...identicalLines(diff, ctx, width)].join('\n')}\n`;
   }
+  const watched = watchedOf(diff, ctx);
   const m = messages(ctx.locale);
+  const { paint } = ctx;
   const groups = groupByPhase(diff.hunks);
   let shown = 0;
   const budget = ctx.limit > 0 ? ctx.limit : Number.POSITIVE_INFINITY;
   const listed = groups.map((g) => {
     const take = g.hunks.slice(0, Math.max(0, budget - shown));
     shown += take.length;
-    return { phase: g.phase, total: g.hunks.length, rows: rowsOf(diff, take, ctx) };
+    return { phase: g.phase, total: g.hunks.length, rows: rowsOf(diff, take, ctx, watched) };
   });
+  const possible = possibleMatches(diff);
+  const possibleShown = possible.slice(
+    0,
+    ctx.limit > 0 ? Math.min(ctx.limit, POSSIBLE_LIMIT) : possible.length,
+  );
+  const possibleList = possibleRows(diff, possibleShown, ctx);
   const allRows = listed.flatMap((g) => g.rows);
   const width = layoutWidth(
-    Math.max(headerNatural(diff, title, ctx, ov), listWidth(allRows)),
+    Math.max(headerNatural(diff, title, ctx, ov), listWidth(allRows), listWidth(possibleList)),
     ctx.width,
   );
   const cols = listColumns(allRows, width);
-  const lines = [...headerLines(diff, title, ctx, width), '', ...statLines(ov, ctx, width), ''];
+  // Columns of their own: hunk titles are often long, and the reason and evidence matter more
+  // here than lining up with the hunks above (the section has its own heading).
+  const possibleCols = listColumns(possibleList, width);
+  const lines = [
+    ...headerLines(diff, title, ctx, width),
+    '',
+    ...statLines(ov, ctx, width, watched),
+    '',
+  ];
   for (const group of listed) {
     if (group.rows.length === 0) continue;
-    lines.push(
-      `${INDENT}${ctx.paint.bold(m.phase[group.phase])} ${ctx.paint.dim(formatInt(group.total))}`,
-    );
+    lines.push(`${INDENT}${paint.bold(m.phase[group.phase])} ${paint.dim(formatInt(group.total))}`);
     for (const row of group.rows) lines.push(renderRow(row, cols, ctx));
   }
   const hidden = ov.hunks - shown;
   if (hidden > 0) {
     const more = `${m.more(hidden)} · ${m.moreHint}`;
-    lines.push(INDENT + ctx.paint.dim(truncate(more, width - INDENT.length)));
+    lines.push(INDENT + paint.dim(truncate(more, width - INDENT.length)));
+  }
+  if (possible.length > 0) {
+    lines.push(
+      '',
+      `${INDENT}${paint.bold(m.possible.heading)} ${paint.dim(formatInt(possible.length))}`,
+    );
+    for (const row of possibleList) lines.push(renderRow(row, possibleCols, ctx));
+    const notListed = possible.length - possibleShown.length;
+    if (notListed > 0) {
+      lines.push(INDENT + paint.dim(truncate(m.possible.more(notListed), width - INDENT.length)));
+    }
+    for (const line of wrap(m.possible.hint, width - INDENT.length)) {
+      lines.push(INDENT + paint.dim(line));
+    }
   }
   return `${lines.join('\n')}\n`;
 }
@@ -310,15 +432,16 @@ const MAX_TYPE_ROWS = 12;
 const MAX_TYPE_NAME = 28;
 
 /**
- * `--stat`: header, counters and bar, a nodes / edges × added / removed / modified / unchanged
- * table, and a git-style per-type breakdown (`+` added, `−` removed, `~` modified nodes).
+ * `--stat`: header, counters and bar (with the review-first line, as in the summary), a
+ * nodes / edges × added / removed / modified / unchanged table, and a git-style per-type
+ * breakdown (`+` added, `−` removed, `~` modified nodes).
  */
 export function renderStat(diff: DiffResult, title: string, ctx: TextContext): string {
   const ov = overview(diff);
   const width = layoutWidth(headerNatural(diff, title, ctx, ov), ctx.width);
   const lines = [...headerLines(diff, title, ctx, width), ''];
   if (ov.hunks === 0) return `${[...lines, ...identicalLines(diff, ctx, width)].join('\n')}\n`;
-  lines.push(...statLines(ov, ctx, width), '');
+  lines.push(...statLines(ov, ctx, width, watchedOf(diff, ctx)), '');
   lines.push(...countsTable(diff, ctx, width), '');
   lines.push(...typeLines(diff, ctx, width));
   return `${lines.join('\n')}\n`;