@erclx/canon 5.77.0 → 5.79.0

package/src/pr/bijection.ts

@@ -1,4 +1,5 @@
 import type { RenamePair } from '@/git/files'
+import { findMislinked, type Mislinked } from '@/pr/links'
 import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
 
 /**
@@ -62,6 +63,12 @@ export interface BijectionReport {
    * comparison has no way to tell a stale claim from one it could not check.
    */
   readonly evidenceUnread: boolean
+  /**
+   * Links in the section whose anchor hashes a path other than the one their
+   * label names, which open the wrong file's diff. Empty for a body that links
+   * nothing, since an unlinked path is the ordinary form.
+   */
+  readonly mislinked: readonly Mislinked[]
 }
 
 export type Bijection =
@@ -231,6 +238,7 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
     unnamed: reached.filter((path) => !owesNoBullet(path)),
     incidental: reached.filter(owesNoBullet),
     evidenceUnread,
+    mislinked: findMislinked(input.body, input.changed),
   }
 }
 

package/src/pr/evidence.ts

@@ -31,6 +31,9 @@ const LOCAL_SKIP_PREFIX = '**No local preview:**'
 /** How the line naming why no reel was filmed opens. */
 const REEL_SKIP_PREFIX = '**No reel:**'
 
+/** How the line naming the painted paths changed with no capture opens. */
+const UNCAPTURED_PREFIX = '**Uncaptured:**'
+
 /** The width a reel is filmed at, which it asks for in the comment. */
 const REEL_WIDTH = 960
 
@@ -43,6 +46,9 @@ const FOLDED_SUMMARY = 'Within tolerance'
 /** The heading every body opens with. */
 const EVIDENCE_HEADING = '## Evidence'
 
+/** How the line counting renamed images whose pixels did not change opens. */
+const MOVED_PREFIX = '**Moved unchanged:**'
+
 /** How the visible commit line opens. */
 const BASE_PREFIX = '**Base:**'
 
@@ -59,8 +65,11 @@ const BOX_LINE = /^(\s*[-*+] \[)([ xX])(\] )(.*)$/
 /** The trailing segment a tick carries, naming the commit the box passed at. Matched only at the end of a line, so a box whose own text says `passed at` is left alone. */
 const STAMP = / · passed at `([0-9a-f]{7,40})`$/
 
-/** What ends the text of a box that a person has to judge by eye. */
-const TASTE_SUFFIX = '(taste)'
+/** The marker a box a person has to judge by eye carries among its trailing markers. */
+const TASTE_MARKER = '(taste)'
+
+/** The run of parenthesized markers that ends a box, such as `(taste) (local only)`, in any order. */
+const TRAILING_MARKERS = /(?:\s*\([^()]*\))+$/
 
 /** A `#issuecomment-<id>` suffix, which is the REST comment id `gh pr view` never returns directly. */
 const ISSUE_COMMENT_ID = /#issuecomment-(\d+)$/
@@ -76,14 +85,18 @@ const IMAGE_EXTENSION = /\.(png|jpe?g|gif|webp|avif|svg)$/i
 export interface EvidenceItem {
   readonly path: string
   readonly stem: string
-  /** True when `path` did not exist at the comparison's base commit. */
+  /** True when `path` did not exist at the comparison's base commit and was not renamed from a path that did. */
   readonly added: boolean
+  /** Where a renamed image sat at the base, which its before image reads from. Absent for any image that was not renamed. */
+  readonly basePath?: string
   /** Pixel width of the head image, read from its PNG header. Absent when unread. */
   readonly width?: number
   /** Pixel width of the base image, absent for an added case or an unread header. */
   readonly baseWidth?: number
   /** Whether the head differs from its base by no more than sub-visual noise. Absent when the pair was not compared. */
   readonly withinTolerance?: boolean
+  /** Whether the head and base files hold the same bytes. Read only for a renamed image, where it alone lets the listing drop the pair, since a small edit also passes the tolerance. */
+  readonly identical?: boolean
 }
 
 export interface EvidenceState {
@@ -125,11 +138,13 @@ function splitEvidencePath(path: string): {
 /**
  * Groups every evidence path in `changed` by its state, keying each entry
  * inside a state by filename stem so a before/after pair sharing a name
- * across two states can be read as one case.
+ * across two states can be read as one case. A path in `renamedFrom` was moved
+ * from the path it maps to, so it is not added and its base reads from there.
  */
 export async function groupEvidence(
   changed: readonly string[],
   existsAtBase: ExistsAtBase,
+  renamedFrom: ReadonlyMap<string, string> = new Map(),
 ): Promise<EvidenceReading> {
   const paths = changed.filter(isEvidencePath)
   if (paths.length === 0) return { kind: 'refused', reason: 'no-evidence' }
@@ -137,14 +152,20 @@ export async function groupEvidence(
   const resolved = await Promise.all(
     paths.map(async (path) => {
       const { state, stem } = splitEvidencePath(path)
-      const added = !(await existsAtBase(path))
-      return { path, state, stem, added }
+      const basePath = renamedFrom.get(path)
+      const added = basePath === undefined && !(await existsAtBase(path))
+      return { path, state, stem, added, basePath }
     }),
   )
 
   const byState = new Map<string, EvidenceItem[]>()
-  for (const { path, state, stem, added } of resolved) {
-    const item: EvidenceItem = { path, stem, added }
+  for (const { path, state, stem, added, basePath } of resolved) {
+    const item: EvidenceItem = {
+      path,
+      stem,
+      added,
+      ...(basePath !== undefined && { basePath }),
+    }
     const items = byState.get(state)
     if (items === undefined) byState.set(state, [item])
     else items.push(item)
@@ -277,7 +298,7 @@ function baseFold(item: EvidenceItem, repo: string, base: string): string[] {
     '<summary>Base</summary>',
     '',
     evidenceImage(
-      rawUrl(repo, base, item.path),
+      rawUrl(repo, base, item.basePath ?? item.path),
       `${escapeCell(item.stem)} base`,
       item.baseWidth,
     ),
@@ -476,6 +497,22 @@ function skipLines(prefix: string, reason: string | undefined): string[] {
   return text === '' ? [] : [`${prefix} ${escapeCell(text)}`, '']
 }
 
+/**
+ * The uncaptured line, or nothing once the list is empty or a reel filmed at
+ * this head shows the change. A reel at an earlier head leaves it, since a
+ * later push may have added the path.
+ */
+function uncapturedLines(
+  uncaptured: readonly string[],
+  head: string,
+  reel: EvidenceReel | undefined,
+): string[] {
+  if (uncaptured.length === 0) return []
+  if (reel !== undefined && head.startsWith(reel.head)) return []
+  const paths = uncaptured.map((path) => `\`${path}\``).join(', ')
+  return [`${UNCAPTURED_PREFIX} ${paths}`, '']
+}
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
@@ -511,6 +548,10 @@ export function evidenceMarker(head: string): string {
  * A skip names why the local address or the reel is missing, on its own line
  * where that address or reel would sit. Each is dropped whenever its address
  * or reel renders, carried or passed, so a skip never outlives its cause.
+ *
+ * The uncaptured line names each painted path changed with no capture, under
+ * the reel, and is computed fresh on every render rather than carried, so it
+ * drops on the first render after a capture or a reel at the head lands.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -522,6 +563,7 @@ export function renderEvidenceBody(
   local?: string,
   reel?: EvidenceReel,
   skips: EvidenceSkips = {},
+  uncaptured: readonly string[] = [],
 ): string {
   const segments = [
     ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
@@ -535,6 +577,7 @@ export function renderEvidenceBody(
     ...(reel === undefined
       ? skipLines(REEL_SKIP_PREFIX, skips.reel)
       : [reelLine(reel), '']),
+    ...uncapturedLines(uncaptured, head, reel),
   ]
   const closing =
     checklist === undefined
@@ -548,8 +591,16 @@ export function renderEvidenceBody(
     states
       .map((entry) => ({ ...entry, items: entry.items.filter(keep) }))
       .filter((entry) => entry.items.length > 0)
-  const open = split((item) => item.withinTolerance !== true)
-  const folded = split((item) => item.withinTolerance === true)
+  const isMoved = (item: EvidenceItem): boolean =>
+    item.basePath !== undefined && item.identical === true
+  const open = split((item) => !isMoved(item) && item.withinTolerance !== true)
+  const folded = split(
+    (item) => !isMoved(item) && item.withinTolerance === true,
+  )
+  const movedCount = states.reduce(
+    (total, entry) => total + entry.items.filter(isMoved).length,
+    0,
+  )
 
   const headCount = open.reduce((total, entry) => total + entry.items.length, 0)
   const opener =
@@ -564,6 +615,12 @@ export function renderEvidenceBody(
     ...opening,
     `${BASE_PREFIX} ${commitLink(repo, base)} · **Head:** ${commitLink(repo, head)}`,
     '',
+    ...(movedCount === 0
+      ? []
+      : [
+          `${MOVED_PREFIX} ${movedCount} ${movedCount === 1 ? 'image' : 'images'}`,
+          '',
+        ]),
     ...sections,
     '',
     ...closing,
@@ -859,7 +916,7 @@ export interface ChecklistBox {
   readonly isTicked: boolean
   /** The short sha a tick names, absent on an empty box or a tick nothing stamped. */
   readonly stamp?: string
-  /** Whether the box ends in `(taste)`, which no driver ticks. */
+  /** Whether the box's trailing marker run holds `(taste)`, which no driver ticks. */
   readonly isTaste: boolean
 }
 
@@ -906,12 +963,23 @@ export function readChecklistBoxes(checklist: string): ChecklistBox[] {
       text: parsed.text,
       isTicked: parsed.isTicked,
       ...(parsed.stamp !== undefined && { stamp: parsed.stamp }),
-      isTaste: parsed.text.endsWith(TASTE_SUFFIX),
+      isTaste: hasTasteMarker(parsed.text),
     })
   })
   return boxes
 }
 
+function hasTasteMarker(text: string): boolean {
+  const run = TRAILING_MARKERS.exec(text)?.[0] ?? ''
+  const markers: readonly string[] = run.match(/\([^()]*\)/g) ?? []
+  return markers.includes(TASTE_MARKER)
+}
+
+/** The boxes a driver can run, being every box but a taste one. */
+export function countDrivable(boxes: readonly ChecklistBox[]): number {
+  return boxes.filter((box) => !box.isTaste).length
+}
+
 /** The head the marked comment's trailing marker names. */
 export function findEvidenceHead(
   comments: readonly EvidenceComment[],

package/src/pr/frames.ts

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises'
+import { REEL_MAX_BYTES } from '@/take/reel'
 
 /** The branch holding review frames. It never merges into a branch anyone checks out. */
 export const FRAMES_BRANCH = 'canon/frames'
@@ -13,12 +14,6 @@ const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
 const RIFF = [0x52, 0x49, 0x46, 0x46]
 const WEBP = [0x57, 0x45, 0x42, 0x50]
 
-/**
- * The largest reel an add takes, GitHub's cap on an image in a comment, so a
- * reel that would not render is refused before it reaches the branch.
- */
-export const REEL_MAX_BYTES = 10_000_000
-
 const SHORT_HEAD_LENGTH = 7
 
 const HEAD_PATTERN = /^[0-9a-f]{7,40}$/

package/src/pr/health.ts

@@ -1,18 +1,26 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+/** The key listing folders whose listeners skip the health paths. */
+export const PAGE_ONLY_KEY = 'page-only'
+
 /** Where a project declares what `canon pr local` checks beyond the page. */
 export const LOCAL_CONFIG_REL = join('canon', 'config', 'local.toml')
 
 /**
- * The health paths a project declared. `none` is an absent file or an empty
- * `health = []`. `invalid` is a declaration that exists and cannot be used,
- * which refuses rather than falling back to the page-only probe, since that
- * fallback is the failure the declaration exists to catch.
+ * The health paths a project declared, with the folders whose listeners skip
+ * them. `none` is an absent file or an empty `health = []`. `invalid` is a
+ * declaration that exists and cannot be used, which refuses rather than
+ * falling back to the page-only probe, since that fallback is the failure the
+ * declaration exists to catch.
  */
 export type HealthDeclaration =
-  | { readonly kind: 'paths'; readonly paths: readonly string[] }
-  | { readonly kind: 'none' }
+  | {
+      readonly kind: 'paths'
+      readonly paths: readonly string[]
+      readonly pageOnly: readonly string[]
+    }
+  | { readonly kind: 'none'; readonly pageOnly: readonly string[] }
   | { readonly kind: 'invalid'; readonly reason: string }
 
 /**
@@ -28,9 +36,24 @@ function isLocalPath(entry: unknown): entry is string {
   )
 }
 
+/**
+ * A repository-relative folder as whole segments, or undefined when the entry
+ * is not one. Absolute paths, drive letters, backslashes, and `..` refuse,
+ * since each would name a place outside the repository. A leading `./` and
+ * trailing slashes are dropped so the match compares segments alone.
+ */
+function toFolder(entry: unknown): string | undefined {
+  if (typeof entry !== 'string') return undefined
+  if (entry.startsWith('/') || entry.includes('\\')) return undefined
+  if (/^[A-Za-z]:/.test(entry)) return undefined
+  const segments = entry.split('/').filter((s) => s !== '' && s !== '.')
+  if (segments.length === 0 || segments.includes('..')) return undefined
+  return segments.join('/')
+}
+
 export function readHealthPaths(root: string): HealthDeclaration {
   const path = join(root, LOCAL_CONFIG_REL)
-  if (!existsSync(path)) return { kind: 'none' }
+  if (!existsSync(path)) return { kind: 'none', pageOnly: [] }
 
   let parsed: Record<string, unknown>
   try {
@@ -42,15 +65,40 @@ export function readHealthPaths(root: string): HealthDeclaration {
     return { kind: 'invalid', reason: `${LOCAL_CONFIG_REL} is not valid TOML` }
   }
 
-  const declared = parsed.health
-  if (!Array.isArray(declared) || !declared.every(isLocalPath)) {
-    return {
-      kind: 'invalid',
-      reason: `${LOCAL_CONFIG_REL} needs health as a list of paths, each starting with a single /`,
+  const hasHealth = 'health' in parsed
+  const hasPageOnly = PAGE_ONLY_KEY in parsed
+  if (!hasHealth && !hasPageOnly) return invalidHealth()
+
+  let paths: readonly string[] = []
+  if (hasHealth) {
+    const declared = parsed.health
+    if (!Array.isArray(declared) || !declared.every(isLocalPath)) {
+      return invalidHealth()
     }
+    paths = declared
   }
 
-  return declared.length === 0
-    ? { kind: 'none' }
-    : { kind: 'paths', paths: declared }
+  let pageOnly: readonly string[] = []
+  if (hasPageOnly) {
+    const declared = parsed[PAGE_ONLY_KEY]
+    const folders = Array.isArray(declared) ? declared.map(toFolder) : []
+    if (!Array.isArray(declared) || folders.includes(undefined)) {
+      return {
+        kind: 'invalid',
+        reason: `${LOCAL_CONFIG_REL} needs ${PAGE_ONLY_KEY} as a list of folders relative to the repository, with no leading / and no ..`,
+      }
+    }
+    pageOnly = folders as string[]
+  }
+
+  return paths.length === 0
+    ? { kind: 'none', pageOnly }
+    : { kind: 'paths', paths, pageOnly }
+}
+
+function invalidHealth(): HealthDeclaration {
+  return {
+    kind: 'invalid',
+    reason: `${LOCAL_CONFIG_REL} needs health as a list of paths, each starting with a single /`,
+  }
 }

package/src/pr/lift.ts

@@ -4,9 +4,11 @@ import {
   type ReviewRow,
   resolveReviewScope,
   resolveUiScope,
+  standingPasses,
   type UiCounts,
 } from '@/pr/review-scope'
 import { readCarry } from '@/pr/carry'
+import { readWaivers } from '@/pr/waiver'
 import { DEFAULT_PAINTED, isPainted, type PaintedPatterns } from '@/pr/painted'
 
 /** How long `--wait` holds for a pending CI run, in seconds, when none is named. */
@@ -28,6 +30,7 @@ export type LiftRefusal =
   | 'ui-behind'
   | 'ui-undriven'
   | 'evidence-owed'
+  | 'painted-uncaptured'
   | 'standing-stale'
   | 'standing-conflict'
   | 'standing-unknown'
@@ -52,6 +55,10 @@ export interface GateResult {
   readonly paintedPaths?: readonly string[]
   /** Every path a box can observe that kept a UI close from carrying forward. */
   readonly drivenPaths?: readonly string[]
+  /** The painted paths changed with no capture, reel at the head, or waiver, sorted. */
+  readonly uncaptured?: readonly string[]
+  /** The uncaptured paths a review waived, sorted. */
+  readonly waived?: readonly string[]
 }
 
 /** How an earlier commit sits against the head, and what changed since. */
@@ -78,8 +85,35 @@ export interface PullState {
 export interface EvidenceGate {
   readonly isSettled: boolean
   readonly owed: readonly string[]
-  /** Whether the marked comment carries a visual checklist, which binds the UI gate. */
-  readonly hasChecklist: boolean
+  /** Whether the marked comment's checklist holds a box a driver can run, which binds the UI gate. */
+  readonly hasDrivableBox: boolean
+  /**
+   * The painted paths changed while no evidence image did, absent where the
+   * base keeps no captures, which reads as unchecked and passes.
+   */
+  readonly uncaptured?: readonly string[]
+  /** The head the marked comment's reel was filmed at, when it embeds one. */
+  readonly reelHead?: string
+}
+
+/**
+ * Whether an evidence record binds the UI family. A checklist binds unless
+ * the record counts zero drivable boxes, so a missing or unreadable count
+ * fails closed rather than reading as unbound.
+ */
+export function readsDrivableBox(record: {
+  readonly checklist?: unknown
+  readonly drivable?: unknown
+}): boolean {
+  if (typeof record.checklist !== 'string' || record.checklist === '') {
+    return false
+  }
+  const { drivable } = record
+  return !(
+    typeof drivable === 'number' &&
+    Number.isInteger(drivable) &&
+    drivable === 0
+  )
 }
 
 export interface ChecksGate {
@@ -219,13 +253,14 @@ export async function uiGate(
   painted: PaintedPatterns,
   reviews: readonly ReviewRow[],
   head: string,
-  hasChecklist: boolean,
+  hasDrivableBox: boolean,
 ): Promise<GateResult> {
-  if (!hasChecklist) return pass('ui')
-
   const scope = resolveUiScope({ reviews })
-  if (scope.state === 'none') return fail('ui', 'ui-missing')
+  // An open verdict holds the gate even once no drivable box remains, so
+  // dropping the checklist or marking a failed box taste never clears it.
   if (scope.state === 'open') return fail('ui', 'ui-open')
+  if (!hasDrivableBox) return pass('ui')
+  if (scope.state === 'none') return fail('ui', 'ui-missing')
   if (scope.source !== 'marker') return fail('ui', 'ui-unmarked')
   if (scope.commit === undefined) return fail('ui', 'ui-behind')
   // Ahead of the head test so a close carried across commits is refused too.
@@ -254,6 +289,39 @@ export async function uiGate(
   }
 }
 
+/**
+ * The evidence gate. An owed step refuses first. Then every painted path the
+ * pull request changed with no capture refuses, unless a reel filmed at the
+ * head shows it or a standing pass waived it by the path as the list spells it.
+ * A reel at an earlier head clears nothing, since a later push may add the
+ * path, and for the same reason a waiver counts only while the newest pass of
+ * its family restates it.
+ */
+export function evidenceGate(
+  evidence: EvidenceGate,
+  reviews: readonly ReviewRow[],
+  head: string,
+): GateResult {
+  if (!evidence.isSettled) return fail('evidence', 'evidence-owed')
+
+  const isFilmed =
+    evidence.reelHead !== undefined && coversHead(evidence.reelHead, head)
+  const listed = isFilmed ? [] : (evidence.uncaptured ?? [])
+  const named = new Set(
+    readWaivers(standingPasses(reviews)).map((waiver) => waiver.path),
+  )
+  const waived = listed.filter((path) => named.has(path)).toSorted()
+  const uncaptured = listed.filter((path) => !named.has(path)).toSorted()
+
+  const lists = {
+    ...(uncaptured.length > 0 && { uncaptured }),
+    ...(waived.length > 0 && { waived }),
+  }
+  return uncaptured.length > 0
+    ? { ...fail('evidence', 'painted-uncaptured'), ...lists }
+    : { ...pass('evidence'), ...lists }
+}
+
 function standingGate(standing: Standing): GateResult {
   if (standing === 'fresh') return pass('standing')
   return fail('standing', `standing-${standing}`)
@@ -409,8 +477,8 @@ export async function lift(
 
   const gates: GateResult[] = [
     reviewGate(reviews, tip),
-    await uiGate(api, painted, reviews, tip, evidence.hasChecklist),
-    evidence.isSettled ? pass('evidence') : fail('evidence', 'evidence-owed'),
+    await uiGate(api, painted, reviews, tip, evidence.hasDrivableBox),
+    evidenceGate(evidence, reviews, tip),
     standingGate(standing),
   ]
   if (!pull.isDraft) return settleReady(api, opts, pull, tip, gates)
@@ -481,7 +549,7 @@ export async function lift(
 
   const reread = [
     reviewGate(nowReviews, nowTip),
-    await uiGate(api, painted, nowReviews, nowTip, evidence.hasChecklist),
+    await uiGate(api, painted, nowReviews, nowTip, evidence.hasDrivableBox),
   ].find((gate) => !gate.isOk)
   if (reread?.reason !== undefined) {
     return refused(reread.reason, cleared, nowTip, ci.waited)

package/src/pr/links.ts

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto'
+import { findBacktickSpans } from '@/markdown/backticks'
+import { KEY_CHANGES, LINE_SUFFIX, readSectionAt } from '@/pr/paths'
+
+/** A Key changes link whose anchor hashes a path other than its label's. */
+export interface Mislinked {
+  readonly path: string
+  readonly anchor: string
+}
+
+/**
+ * The fragment GitHub gives a file's diff in a pull request's Files tab, being
+ * `diff-` and the SHA-256 of the raw path. Read off a merged pull request's
+ * rendered page, so a path holding a space or a bracket hashes as written.
+ */
+export function diffAnchor(path: string): string {
+  return `diff-${createHash('sha256').update(path).digest('hex')}`
+}
+
+interface Located {
+  readonly text: string
+  readonly offset: number
+  readonly whole: string
+}
+
+/** The section's text and where it starts, in the body with line endings normalized. */
+function locateSection(body: string, title: string): Located | undefined {
+  const whole = body.replace(/\r\n/g, '\n')
+  const found = readSectionAt(whole, title)
+  return found === undefined ? undefined : { ...found, whole }
+}
+
+/** Blanks every code span, keeping offsets, so a bracket inside a path never reads as link syntax. */
+function maskSpans(text: string): string {
+  let out = text
+  for (const span of findBacktickSpans(text)) {
+    out =
+      out.slice(0, span.start) +
+      ' '.repeat(span.end - span.start) +
+      out.slice(span.end)
+  }
+  return out
+}
+
+/**
+ * An inline link: a destination bare or in angle brackets, then an optional
+ * quoted title. A form this misses reads as no link, and a span inside it then
+ * gets a second link nested in the first.
+ */
+const LINK =
+  /\[[^\]]*\]\(\s*(<[^>]*>|[^)\s]*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/dg
+const DIFF_DESTINATION = /#diff-[0-9a-f]{64}$/
+
+interface Edit {
+  readonly start: number
+  readonly end: number
+  readonly text: string
+}
+
+/**
+ * Writes each code span in `## Key changes` that names a changed file as a link
+ * to that file's diff, keeping the span as the label.
+ *
+ * Only an exact changed path is linked. A partial spelling or a folder names no
+ * single row in the Files tab, and a link to a guessed row is worse than none.
+ *
+ * A span that is the whole label of an existing diff link has its destination
+ * rewritten, which is how a wrong anchor clears. A span anywhere else inside a
+ * link's brackets is left alone, since a link nested in a link breaks the
+ * bullet, and the rewrite stays idempotent.
+ *
+ * `filesUrl` is the pull request's `/files` address, absolute because the body
+ * becomes the squash commit message, where a relative link resolves nowhere.
+ */
+export function linkKeyChanges(
+  body: string,
+  changed: readonly string[],
+  filesUrl: string,
+): string {
+  const located = locateSection(body, KEY_CHANGES)
+  if (located === undefined) return body
+
+  const { text } = located
+  const known = new Set(changed)
+  const links = [...maskSpans(text).matchAll(LINK)].map((match) => ({
+    start: match.index ?? 0,
+    end: (match.index ?? 0) + match[0].length,
+    destination: match[1] ?? '',
+    destinationStart: match.indices?.[1]?.[0] ?? 0,
+  }))
+
+  const edits: Edit[] = []
+  for (const span of findBacktickSpans(text)) {
+    const path = span.content.replace(LINE_SUFFIX, '')
+    if (!known.has(path)) continue
+    const target = `${filesUrl}#${diffAnchor(path)}`
+
+    const link = links.find((l) => l.start < span.start && span.end <= l.end)
+    if (link === undefined) {
+      edits.push({
+        start: span.start,
+        end: span.end,
+        text: `[${text.slice(span.start, span.end)}](${target})`,
+      })
+      continue
+    }
+
+    const wholeLabel =
+      span.start === link.start + 1 && text.startsWith('](', span.end)
+    if (!wholeLabel || !DIFF_DESTINATION.test(link.destination)) continue
+    edits.push({
+      start: link.destinationStart,
+      end: link.destinationStart + link.destination.length,
+      text: target,
+    })
+  }
+
+  let out = ''
+  let cursor = 0
+  for (const edit of edits) {
+    out += text.slice(cursor, edit.start) + edit.text
+    cursor = edit.end
+  }
+  out += text.slice(cursor)
+
+  return (
+    located.whole.slice(0, located.offset) +
+    out +
+    located.whole.slice(located.offset + text.length)
+  )
+}
+
+const DIFF_LINK = /\[(`+)([^`]+)\1\]\([^)\s]*#(diff-[0-9a-f]{64})\)/g
+
+/**
+ * Every Key changes link whose label is a changed path and whose anchor hashes
+ * another path.
+ *
+ * A label that is no changed path, such as a bare file name or a function, is
+ * left unjudged: it can open the right file under a spelling this cannot map
+ * back to a row, and an accusation needs the row.
+ */
+export function findMislinked(
+  body: string,
+  changed: readonly string[],
+): Mislinked[] {
+  const located = locateSection(body, KEY_CHANGES)
+  if (located === undefined) return []
+
+  const known = new Set(changed)
+  const out: Mislinked[] = []
+  for (const match of located.text.matchAll(DIFF_LINK)) {
+    const path = (match[2] ?? '').trim().replace(LINE_SUFFIX, '')
+    const anchor = match[3] ?? ''
+    if (known.has(path) && diffAnchor(path) !== anchor) {
+      out.push({ path, anchor })
+    }
+  }
+  return out
+}