@kgdiff/cli 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kgdiff/cli",
-  "version": "0.3.0",
+  "version": "0.5.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.3.0",
-    "@kgdiff/formats": "0.3.0",
-    "@kgdiff/layout": "0.3.0",
-    "@kgdiff/scene": "0.3.0",
-    "@kgdiff/viewer": "0.3.0"
+    "@kgdiff/core": "0.5.0",
+    "@kgdiff/formats": "0.5.0",
+    "@kgdiff/layout": "0.5.0",
+    "@kgdiff/scene": "0.5.0",
+    "@kgdiff/viewer": "0.5.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/args.ts

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import type { DiffOptions, EdgeIdentity, Locale, MatchOptions } from '@kgdiff/core';
 import type { FormatId } from '@kgdiff/formats';
-import type { ThemePreference, ViewerMode } from '@kgdiff/viewer';
+import type { ThemePreference, ViewerMode, ViewerScope } from '@kgdiff/viewer';
 import { CliError } from './errors.js';
 import { matchLocale } from './locale.js';
 import type { ColorMode } from './style.js';
@@ -34,7 +34,9 @@ export const FORMATS: readonly (FormatId | 'auto')[] = [
 const MATCH_STRATEGIES = ['id', 'auto', 'similarity'] as const;
 const EDGE_IDENTITIES: readonly EdgeIdentity[] = ['structure', 'id'];
 const THEMES: readonly ThemePreference[] = ['auto', 'light', 'dark'];
-const MODES: readonly ViewerMode[] = ['overlay', 'swipe', 'replay', 'changes'];
+/** `changes` is the viewer's legacy mode: overlay + `--scope changes`. */
+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`. */
@@ -67,6 +69,7 @@ export interface DiffCommandOptions extends CommonOptions {
   readonly title?: string;
   readonly theme?: ThemePreference;
   readonly mode?: ViewerMode;
+  readonly scope?: ViewerScope;
   readonly reproducible: boolean;
   /** `--allow-empty`: an empty input is an empty graph instead of an error. */
   readonly allowEmpty: boolean;
@@ -75,6 +78,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 {
@@ -139,11 +147,13 @@ export const DIFF_OPTIONS: Readonly<Record<string, OptionSpec>> = {
   title: { type: 'string' },
   theme: { type: 'string' },
   mode: { type: 'string' },
+  scope: { type: 'string' },
   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>`. */
@@ -479,7 +489,15 @@ function parseDiff(argv: readonly string[]): Command {
   };
 
   const theme = v.string('theme');
-  const mode = v.string('mode');
+  const modeArg = v.string('mode');
+  const mode = modeArg === undefined ? undefined : choice('mode', modeArg, MODES);
+  const scopeArg = v.string('scope');
+  const scope =
+    scopeArg !== undefined
+      ? choice('scope', scopeArg, SCOPES)
+      : mode === 'changes'
+        ? 'changes'
+        : undefined;
   const limit = v.string('limit');
   const languages = parseLanguages(v);
   const title = v.string('title');
@@ -487,6 +505,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,
@@ -505,7 +530,8 @@ function parseDiff(argv: readonly string[]): Command {
     pretty: v.flag('pretty'),
     ...(title !== undefined ? { title } : {}),
     ...(theme !== undefined ? { theme: choice('theme', theme, THEMES) } : {}),
-    ...(mode !== undefined ? { mode: choice('mode', mode, MODES) } : {}),
+    ...(mode !== undefined ? { mode: mode === 'changes' ? 'overlay' : mode } : {}),
+    ...(scope !== undefined ? { scope } : {}),
     reproducible: v.flag('reproducible'),
     compute: !v.flag('no-compute'),
     allowEmpty: v.flag('allow-empty'),
@@ -514,6 +540,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;
@@ -252,6 +257,7 @@ export async function runDiff(o: DiffCommandOptions, io: CliIO): Promise<number>
         after: { name: graphLabel(after.graph.meta, afterInput), format: after.format },
         view: {
           ...(o.mode ? { mode: o.mode } : {}),
+          ...(o.scope ? { scope: o.scope } : {}),
           ...(o.theme ? { theme: o.theme } : {}),
           locale: ctx.locale,
         },
@@ -283,6 +289,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

@@ -104,7 +104,12 @@ const MAIN: readonly Section[] = [
         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: '--mode <mode>', text: 'Initial viewer mode: overlay, swipe, replay' },
+      {
+        flags: '--scope <scope>',
+        text: 'Show the whole graph or only the changes (in any mode): all, changes',
+        default: 'changes for large graphs, else all',
+      },
       {
         flags: '--reproducible',
         text: 'Omit the timestamp: byte-identical reports for identical input',
@@ -133,6 +138,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

@@ -110,6 +110,7 @@ export function renderReportHtml(options: ReportHtmlOptions): string {
     `theme="${escapeHtml(theme)}"`,
     `locale="${escapeHtml(locale)}"`,
     ...(view.mode ? [`mode="${escapeHtml(view.mode)}"`] : []),
+    ...(view.scope ? [`scope="${escapeHtml(view.scope)}"`] : []),
   ].join(' ');
   const encodingAttr = encoded.encoding ? ` data-encoding="${encoded.encoding}"` : '';
   const style =

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

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