@aburi/diff 0.3.0 → 0.4.0

package/src/components.ts

@@ -1,258 +0,0 @@
-import type {
-  Component,
-  ComponentDiff,
-  ComponentId,
-  Dependency,
-  DependencyDiff,
-  DependencyEndpoint,
-  DependencyUnknown,
-  DiffSkippedFile,
-  IR,
-  RelativePath,
-  SkipReason,
-} from "@aburi/types"
-
-/**
- * `docs/design/diff-algorithm.md` §6.1 — Component diff. Assumes `components[].id` is unique on each side (ir-schema.md §14
- * #2) and does not check it: `buildDiff` establishes that before calling, and a caller
- * reaching this export directly owns the obligation, because the lookup map here is
- * last-write-wins and a repeat is lost rather than reported.
- *
- * Component identity is `id`; when a Component is present in both
- * base and head with the same id, the three delta booleans describe which axes actually
- * moved (roots reshuffle, public API globs, or framework hint list). `modified` deltas
- * are intentionally absent from this diff (diff-algorithm.md §5.2.3): fields are reported as before/after
- * pairs via the `changed[]` entries so consumers can render them without stringifying
- * arrays.
- */
-export function diffComponents(
-  base: readonly Component[],
-  head: readonly Component[],
-): ComponentDiff {
-  const baseById = new Map<ComponentId, Component>()
-  for (const c of base) baseById.set(c.id, c)
-  const headById = new Map<ComponentId, Component>()
-  for (const c of head) headById.set(c.id, c)
-
-  const added: Component[] = []
-  const removed: Component[] = []
-  const changed: ComponentDiff["changed"] = []
-
-  for (const [id, headComp] of headById) {
-    const baseComp = baseById.get(id)
-    if (baseComp === undefined) {
-      added.push(headComp)
-      continue
-    }
-    const rootsChanged = !stringArraysEqual(baseComp.roots, headComp.roots)
-    const publicApiChanged = !stringArraysEqual(baseComp.publicApi ?? [], headComp.publicApi ?? [])
-    const frameworksChanged = !stringArraysEqual(
-      baseComp.frameworks ?? [],
-      headComp.frameworks ?? [],
-    )
-    if (rootsChanged || publicApiChanged || frameworksChanged) {
-      changed.push({
-        before: baseComp,
-        after: headComp,
-        delta: { rootsChanged, publicApiChanged, frameworksChanged },
-      })
-    }
-  }
-  for (const [id, baseComp] of baseById) {
-    if (!headById.has(id)) removed.push(baseComp)
-  }
-  sortById(added)
-  sortById(removed)
-  changed.sort((a, b) => (a.after.id < b.after.id ? -1 : a.after.id > b.after.id ? 1 : 0))
-  return { added, removed, changed }
-}
-
-/**
- * What one document knows about itself, for deciding whether the *other* document's silence
- * about an edge is evidence.
- *
- * `symbolFiles` is keyed on the endpoint id exactly as `dependencies[]` spells it, and its
- * values come from `symbols[].source.file` — the same space `stats.skippedFiles[].path` is in,
- * and the same space `buildDiff` classifies Symbols by. Reading the file out of the id's path
- * segment instead would introduce a second answer to "which file is this endpoint in", and
- * nothing in the schema forces the two to agree; a Symbol reported `unknown` while its edges
- * stayed `removed` is precisely the inconsistency this exists to remove.
- *
- * A Component endpoint is absent from the map, which is how it stays out of the reclassification
- * without a special case: a Component is an aggregate over roots and has no file to lose.
- */
-export interface DependencySideView {
-  /**
-   * `source.file` of every Symbol this document holds, by the id an endpoint would name it
-   * with. Keyed by `DependencyEndpoint` rather than `SymbolId` because that is the question
-   * being asked: the lookup happens with an endpoint whose kind is not yet known, and "absent"
-   * is the answer for a Component id. Demanding the kind up front would move that decision to
-   * the caller, where it would need a second Symbol-id silhouette test to make.
-   */
-  symbolFiles: ReadonlyMap<DependencyEndpoint, RelativePath>
-  /**
-   * Files this document never analysed, by path, with the reason it gave. `RelativePath` on
-   * both sides of the file space is what states the bridge these two maps exist to make — one
-   * map's values are the other's keys — though the alias is unbranded, so it is intent rather
-   * than enforcement.
-   */
-  lostFiles: ReadonlyMap<RelativePath, SkipReason>
-}
-
-/**
- * Build a side view from a document. The only construction site there is.
- *
- * `buildDiff` reads `lostFiles` for its own Symbol classification too, from this same object,
- * so "a Symbol reported unknown and the edges it took with it cannot disagree about which file
- * went missing" is a property of the wiring rather than a claim in a comment.
- *
- * Exported because `DependencySideView` is public and `diffDependencies` requires one: without
- * a factory a caller would have to reproduce the `symbols[].source.file` keying and the
- * `stats.skippedFiles` read, and the likeliest outcome of that is a caller who gets it wrong.
- */
-export function dependencySideView(ir: IR): DependencySideView {
-  const symbolFiles = new Map<DependencyEndpoint, RelativePath>()
-  for (const symbol of ir.symbols) symbolFiles.set(symbol.id, symbol.source.file)
-  const lostFiles = new Map<RelativePath, SkipReason>()
-  for (const file of ir.stats.skippedFiles ?? []) lostFiles.set(file.path, file.reason)
-  return { symbolFiles, lostFiles }
-}
-
-/**
- * `docs/design/diff-algorithm.md` §6.2 — Dependency diff. Identity is the composite
- * `(from, to, via)` triple; direction and effect changes are surfaced as an added + removed
- * pair so `modified` is not part of the schema (§6.2 tail). Uniqueness of that triple is the caller's obligation on the same
- * terms as `diffComponents` above — a repeat here is indistinguishable in the output from
- * the flip it encodes.
- *
- * `sides` is what separates a deletion from a loss (`docs/design/diff-algorithm.md` §6.2.1).
- * It is required rather than optional: omitting it would classify every edge into a lost file
- * as a deletion again — silently, and while still writing `unknown: []`, which this schema
- * defines as "nothing was unknown" rather than "nobody looked". A caller with no skip list to
- * offer says so by passing a side view whose `lostFiles` is empty, which is the honest spelling
- * of an IR written before `stats.skippedFiles` existed.
- *
- * The return type declares `unknown` present, where the schema leaves it optional for documents
- * that predate the field. A reader may find it missing; this function always writes it.
- */
-export function diffDependencies(
-  base: readonly Dependency[],
-  head: readonly Dependency[],
-  sides: { base: DependencySideView; head: DependencySideView },
-): DependencyDiff & { unknown: DependencyUnknown[] } {
-  const baseKeys = new Map<string, Dependency>()
-  for (const d of base) baseKeys.set(dependencyKey(d), d)
-  const headKeys = new Map<string, Dependency>()
-  for (const d of head) headKeys.set(dependencyKey(d), d)
-  const added: Dependency[] = []
-  const removed: Dependency[] = []
-  const unknown: DependencyUnknown[] = []
-  for (const [key, dep] of headKeys) {
-    const b = baseKeys.get(key)
-    if (b === undefined) {
-      // Held by head and not by base, so its endpoints resolve against head — the document
-      // that has the Symbols — and the question is whether base could have seen them.
-      const lostFiles = endpointsLostBy(dep, sides.head, sides.base)
-      if (lostFiles.length > 0) unknown.push({ dependency: dep, absentFrom: "base", lostFiles })
-      else added.push(dep)
-      continue
-    }
-    // A direction or effect flip. No loss check: both documents hold the edge, so neither is
-    // silent about it, and `unknown` exists only to explain a silence. That holds without
-    // appealing to any invariant — nothing forbids a path from being both a `source.file` and a
-    // skipped one, so "they both have it, therefore neither lost the file" would not be sound.
-    if (b.direction !== dep.direction || (b.effect ?? null) !== (dep.effect ?? null)) {
-      removed.push(b)
-      added.push(dep)
-    }
-  }
-  for (const [key, dep] of baseKeys) {
-    if (headKeys.has(key)) continue
-    const lostFiles = endpointsLostBy(dep, sides.base, sides.head)
-    if (lostFiles.length > 0) unknown.push({ dependency: dep, absentFrom: "head", lostFiles })
-    else removed.push(dep)
-  }
-  added.sort(compareDependencies)
-  removed.sort(compareDependencies)
-  unknown.sort((a, b) => compareDependencies(a.dependency, b.dependency))
-  return { added, removed, unknown }
-}
-
-/**
- * The endpoint files `absent` never analysed, read through `holder` because that is the
- * document the edge — and therefore the Symbol behind each endpoint — actually comes from.
- *
- * Both endpoints are checked: an edge dies when *either* end's file goes, including one whose
- * other end survived, and that half is the easiest to miss because the surviving Symbol is
- * right there in both documents.
- *
- * Deduped and sorted by path, so an intra-file edge collapses to the one file it lost.
- */
-function endpointsLostBy(
-  dep: Dependency,
-  holder: DependencySideView,
-  absent: DependencySideView,
-): DiffSkippedFile[] {
-  // Keyed by path, so an intra-file edge collapses to the one file it lost. Keying by reason
-  // instead would look identical on every fixture whose two endpoints were skipped for
-  // different reasons, and silently drop one of two files skipped for the same reason.
-  const byPath = new Map<RelativePath, SkipReason>()
-  for (const endpoint of [dep.from, dep.to]) {
-    const file = holder.symbolFiles.get(endpoint)
-    // Normally a Component endpoint: an aggregate over roots, with no file to lose, which is
-    // why component-level edges need no special case to stay out of this.
-    //
-    // The other way to land here is a symbol-shaped endpoint with no Symbol behind it, which
-    // `ir-schema.md` §14 #4 forbids. `buildDiff` does not run the integrity checker, and the
-    // CLI cannot reach it because `readIR` rejects such a document first — so this is a library
-    // caller who assembled an IR by hand, and the edge quietly reverts to the misclassification
-    // this function exists to remove. Treated the same as a Component endpoint deliberately:
-    // there is no diagnostics channel here, and refusing would take down the legitimate case
-    // that shares the branch.
-    if (file === undefined) continue
-    const reason = absent.lostFiles.get(file)
-    if (reason === undefined) continue
-    byPath.set(file, reason)
-  }
-  return [...byPath.entries()]
-    .map(([path, reason]) => ({ path, reason }))
-    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
-}
-
-/**
- * `docs/design/diff-algorithm.md` §6.2 — the fields Dependency identity is made of, in key order, and the join that turns
- * them into one. Both halves are exported so the entry-point uniqueness check keys on
- * exactly what this file keys on — a check with its own notion of identity would let through
- * the duplicates that actually collide here, and a check that shared only the join would
- * still be free to disagree about which fields identity is made of.
- *
- * Core's invariant #13 joins the same triple with a different separator. The two agree for
- * every endpoint that satisfies the id grammars of ir-schema.md §3.1 and §4, which is every
- * Document the integrity checker accepts; they could in principle disagree for one that does
- * not, and `buildDiff` runs no grammar check on the IRs it is handed.
- */
-export const DEPENDENCY_IDENTITY_FIELDS = ["from", "to", "via"] as const
-
-export function dependencyIdentity(parts: readonly string[]): string {
-  return parts.join("::")
-}
-
-function dependencyKey(d: Dependency): string {
-  return dependencyIdentity(DEPENDENCY_IDENTITY_FIELDS.map((field) => d[field]))
-}
-
-function compareDependencies(a: Dependency, b: Dependency): number {
-  const keyA = dependencyKey(a)
-  const keyB = dependencyKey(b)
-  return keyA < keyB ? -1 : keyA > keyB ? 1 : 0
-}
-
-function stringArraysEqual(a: readonly string[], b: readonly string[]): boolean {
-  if (a.length !== b.length) return false
-  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
-  return true
-}
-
-function sortById<T extends { id: string }>(items: T[]): void {
-  items.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
-}

package/src/delta.ts

@@ -1,400 +0,0 @@
-import type {
-  ArrayDelta,
-  Call,
-  Decorator,
-  Effect,
-  Symbol as IRSymbol,
-  Rule,
-  Signature,
-  SignatureDelta,
-  SymbolDelta,
-} from "@aburi/types"
-import { DiffError } from "./errors"
-
-export const DEFAULT_LINE_FUZZ = 2
-export const MAX_LINE_FUZZ = 10
-export const MIN_LINE_FUZZ = 0
-
-export interface DeltaOptions {
-  /**
-   * §5.2.1 line fuzz for rule/call identity. Must be an integer in
-   * `[MIN_LINE_FUZZ, MAX_LINE_FUZZ]` (`0..10`); anything outside — or a non-finite value —
-   * throws `DiffError({ code: "invalid-line-fuzz" })`. Setting `0` disables fuzz; omitting
-   * the field falls back to `DEFAULT_LINE_FUZZ` (2).
-   */
-  lineFuzz?: number
-}
-
-/**
- * §5 — Compute the full per-Symbol delta between two paired Symbols. The three axis
- * booleans (`apiChanged` / `logicChanged` / `syntaxChanged`) come from fingerprint
- * comparison; the array deltas (`rules` / `effects` / `calls` / `decorators`) come from
- * identity-preserving diff with configurable line fuzz.
- */
-export function computeSymbolDelta(
-  base: IRSymbol,
-  head: IRSymbol,
-  options: DeltaOptions = {},
-): SymbolDelta {
-  const fuzz = validateLineFuzz(options.lineFuzz ?? DEFAULT_LINE_FUZZ)
-  const delta: SymbolDelta = {
-    apiChanged: base.fingerprint.api !== head.fingerprint.api,
-    logicChanged: base.fingerprint.logic !== head.fingerprint.logic,
-    syntaxChanged: base.fingerprint.syntax !== head.fingerprint.syntax,
-    componentChanged: (base.component ?? null) !== (head.component ?? null),
-    visibilityChanged: base.visibility !== head.visibility,
-  }
-  delta.rules = diffRules(base.rules, head.rules, fuzz)
-  delta.effects = diffEffects(base.effects, head.effects)
-  delta.calls = diffCalls(base.calls, head.calls, fuzz)
-  delta.decorators = diffDecorators(base.decorators, head.decorators, fuzz)
-  const sigDelta = diffSignature(base.signature ?? null, head.signature ?? null)
-  delta.signature = sigDelta
-  return delta
-}
-
-/**
- * §5.2.1 range check. Loud on violation rather than silently clamping so a config typo
- * (`lineFuzz: 999`) or an upstream numeric bug (`NaN`, `Infinity`) surfaces at the diff
- * boundary instead of quietly rounding into a range that produces the wrong deltas.
- */
-function validateLineFuzz(value: number): number {
-  if (!Number.isFinite(value) || !Number.isInteger(value)) {
-    throw new DiffError(
-      `config.diff.lineFuzz must be an integer in [${MIN_LINE_FUZZ}, ${MAX_LINE_FUZZ}]; got ${String(value)}.`,
-      { code: "invalid-line-fuzz", value: String(value) },
-    )
-  }
-  if (value < MIN_LINE_FUZZ || value > MAX_LINE_FUZZ) {
-    throw new DiffError(
-      `config.diff.lineFuzz must be within [${MIN_LINE_FUZZ}, ${MAX_LINE_FUZZ}]; got ${value}.`,
-      { code: "invalid-line-fuzz", value: String(value) },
-    )
-  }
-  return value
-}
-
-interface Identified<T> {
-  item: T
-  key: string
-  line: number
-}
-
-/**
- * §5.2 — pair the two sides by identity key within ±`lineFuzz`, then classify each element
- * into `added` / `removed` / `modified`. `modified` fires only when a pairing holds and the
- * content differs, so a cosmetic line shift produces nothing.
- *
- * Several elements of one Symbol routinely share a key — two `guard` rules, two calls to one
- * target, two `@Get` — so which base element a head element takes is a real choice. Two
- * passes make it: first the elements whose key **and content** agree, then whatever is left.
- * An untouched element is therefore claimed by its own counterpart before an edited or
- * deleted neighbour can take it, and the remainder pairs by proximity — where a genuine edit
- * lands. Taking the first key hit instead reported a deleted `guard@1` by removing its
- * untouched `guard@3` neighbour *and* listing that same neighbour as modified.
- *
- * Each pass is an order-preserving assignment rather than a per-element search, because a
- * greedy pass takes a pairing that leaves a better set unreachable. Two identical guards
- * shifted down two lines are the smallest case: the first head element is nearest to the
- * *second* base element, and claiming it strands the other head outside the window, so a
- * block that moved intact comes back as an `added` and a `removed`.
- */
-function differentiate<T>(
-  base: readonly Identified<T>[],
-  head: readonly Identified<T>[],
-  isEqual: (a: T, b: T) => boolean,
-  lineFuzz: number,
-): ArrayDelta {
-  const freeBase = new Set(base.map((_, index) => index))
-  const freeHead = new Set(head.map((_, index) => index))
-  const partnerOf = new Map<number, Identified<T>>()
-  for (const contentMustAgree of [true, false]) {
-    const admits = (b: Identified<T>, h: Identified<T>): boolean =>
-      b.key === h.key &&
-      Math.abs(b.line - h.line) <= lineFuzz &&
-      (!contentMustAgree || isEqual(b.item, h.item))
-    for (const [baseIndex, headIndex] of assignInOrder(base, head, freeBase, freeHead, admits)) {
-      freeBase.delete(baseIndex)
-      freeHead.delete(headIndex)
-      const counterpart = base[baseIndex]
-      if (counterpart !== undefined) partnerOf.set(headIndex, counterpart)
-    }
-  }
-
-  const added: T[] = []
-  const modified: T[] = []
-  for (const [index, h] of head.entries()) {
-    const counterpart = partnerOf.get(index)
-    if (counterpart === undefined) added.push(h.item)
-    else if (!isEqual(counterpart.item, h.item)) modified.push(h.item)
-  }
-  const removed = base.filter((_, index) => freeBase.has(index)).map((b) => b.item)
-  return { added, removed, modified }
-}
-
-/** How good an assignment is: more pairings first, then less total line movement. */
-interface Quality {
-  pairs: number
-  distance: number
-}
-
-const NO_PAIRINGS: Quality = { pairs: 0, distance: 0 }
-
-/** `a` is preferred over `b`: more pairings wins, and among equals the tighter one does. */
-function better(a: Quality, b: Quality): boolean {
-  return a.pairs !== b.pairs ? a.pairs > b.pairs : a.distance < b.distance
-}
-
-/**
- * The best set of non-crossing pairings between the still-free elements of `base` and `head`,
- * as `[baseIndex, headIndex]` in ascending order — most pairings first, then least total line
- * movement.
- *
- * Non-crossing is the whole content of the rule, and ir-schema §14 #11 is what licenses it:
- * these arrays are ordered by line, so `i < j` means element `i` sits above element `j` in the
- * file. Two pairings that cross would have an element move above one it was below, which is
- * not a line shift — it is a different element. Restricting to non-crossing sets also makes
- * the optimum reachable by a suffix recurrence rather than by a general assignment algorithm.
- *
- * Maximising the count before minimising distance is what stops a near pairing from being
- * taken at the cost of a far one that would otherwise have no partner at all.
- */
-function assignInOrder<T>(
-  base: readonly Identified<T>[],
-  head: readonly Identified<T>[],
-  freeBase: ReadonlySet<number>,
-  freeHead: ReadonlySet<number>,
-  admits: (b: Identified<T>, h: Identified<T>) => boolean,
-): Array<[number, number]> {
-  // best[i][j] is the quality of the best assignment over base[i..] and head[j..].
-  const best: Quality[][] = Array.from({ length: base.length + 1 }, () =>
-    Array.from({ length: head.length + 1 }, () => NO_PAIRINGS),
-  )
-  const pairingAt = (i: number, j: number): Quality | null => {
-    const b = base[i]
-    const h = head[j]
-    if (b === undefined || h === undefined) return null
-    if (!freeBase.has(i) || !freeHead.has(j) || !admits(b, h)) return null
-    const rest = best[i + 1]?.[j + 1] ?? NO_PAIRINGS
-    return { pairs: rest.pairs + 1, distance: rest.distance + Math.abs(b.line - h.line) }
-  }
-  for (let i = base.length - 1; i >= 0; i--) {
-    for (let j = head.length - 1; j >= 0; j--) {
-      const skipBase = best[i + 1]?.[j] ?? NO_PAIRINGS
-      const skipHead = best[i]?.[j + 1] ?? NO_PAIRINGS
-      let winner = better(skipBase, skipHead) ? skipBase : skipHead
-      const paired = pairingAt(i, j)
-      if (paired !== null && better(paired, winner)) winner = paired
-      const row = best[i]
-      if (row !== undefined) row[j] = winner
-    }
-  }
-
-  // Walk the table back down, taking a pairing wherever it is what the optimum was built from.
-  const chosen: Array<[number, number]> = []
-  let i = 0
-  let j = 0
-  while (i < base.length && j < head.length) {
-    const here = best[i]?.[j] ?? NO_PAIRINGS
-    const paired = pairingAt(i, j)
-    if (paired !== null && paired.pairs === here.pairs && paired.distance === here.distance) {
-      chosen.push([i, j])
-      i++
-      j++
-      continue
-    }
-    const skipBase = best[i + 1]?.[j] ?? NO_PAIRINGS
-    if (skipBase.pairs === here.pairs && skipBase.distance === here.distance) i++
-    else j++
-  }
-  return chosen
-}
-
-function diffRules(base: readonly Rule[], head: readonly Rule[], lineFuzz: number): ArrayDelta {
-  const mapper = (r: Rule): Identified<Rule> => ({
-    item: r,
-    key: r.type,
-    line: r.line,
-  })
-  return differentiate(base.map(mapper), head.map(mapper), rulesEqual, lineFuzz)
-}
-
-function rulesEqual(a: Rule, b: Rule): boolean {
-  return (
-    a.type === b.type &&
-    (a.condition ?? null) === (b.condition ?? null) &&
-    (a.what ?? null) === (b.what ?? null) &&
-    (a.expr ?? null) === (b.expr ?? null) &&
-    (a.loopKind ?? null) === (b.loopKind ?? null)
-  )
-}
-
-function diffEffects(base: readonly Effect[], head: readonly Effect[]): ArrayDelta {
-  const mapper = (e: Effect): Identified<Effect> => ({
-    item: e,
-    key: `${e.id}::${e.target}`,
-    // Propagated entries (effect-propagation.md §5.1) omit `line`. An infinite fuzz admits
-    // every same-key candidate, so no placeholder can put an effect outside the window — but
-    // §5.2.0 ranks the admitted candidates by distance, so `0` does read as "at the top of
-    // the Symbol" and a propagated effect prefers the earliest local one carrying its key.
-    // Effects are already keyed by `(id, target)`, which is the whole of their identity in
-    // ir-schema §7, so a tie only arises between two entries that agree on it; the choice
-    // between those is what §5.2.0's exact-content pass settles.
-    line: e.line ?? 0,
-  })
-  return differentiate(base.map(mapper), head.map(mapper), effectsEqual, Number.POSITIVE_INFINITY)
-}
-
-function effectsEqual(a: Effect, b: Effect): boolean {
-  return (
-    a.id === b.id && a.target === b.target && a.plugin === b.plugin && a.confidence === b.confidence
-  )
-}
-
-function diffCalls(base: readonly Call[], head: readonly Call[], lineFuzz: number): ArrayDelta {
-  const mapper = (c: Call): Identified<Call> => ({
-    item: c,
-    key: c.target,
-    line: c.line,
-  })
-  return differentiate(base.map(mapper), head.map(mapper), callsEqual, lineFuzz)
-}
-
-function callsEqual(a: Call, b: Call): boolean {
-  return a.target === b.target && (a.resolved ?? null) === (b.resolved ?? null)
-}
-
-/**
- * §5.2.2 — decorator diff. Identity is `name`; when the same-named decorator is present
- * on both sides within the line-fuzz window, the argument list determines whether the
- * entry is a modified pair or an implicit no-op.
- */
-function diffDecorators(
-  base: readonly Decorator[],
-  head: readonly Decorator[],
-  lineFuzz: number,
-): ArrayDelta {
-  const mapper = (d: Decorator): Identified<Decorator> => ({
-    item: d,
-    key: d.name,
-    line: d.line,
-  })
-  return differentiate(base.map(mapper), head.map(mapper), decoratorsEqual, lineFuzz)
-}
-
-function decoratorsEqual(a: Decorator, b: Decorator): boolean {
-  if (a.name !== b.name) return false
-  if (a.arguments.length !== b.arguments.length) return false
-  for (let i = 0; i < a.arguments.length; i++) {
-    if (a.arguments[i] !== b.arguments[i]) return false
-  }
-  return true
-}
-
-/**
- * §5.3 — signature delta. Three cases:
- * - both sides `null` → `null` (nothing to compare)
- * - exactly one side `null` → the present side is emitted verbatim as
- *   `added` (when only head has a signature) or `removed` (when only base has one);
- *   the three axis booleans compare the missing side against `false` defaults
- * - both sides non-null → per-list sub-deltas:
- *   - `inputs`: strict positional compare via `differentiate(..., lineFuzz: 0)` — index
- *     used as the line key so ordered parameter lists match position-for-position
- *   - `outputs`: positional compare (added/removed emitted when the arrays diverge at
- *     an index), no `modified` category
- *   - `throws`: unordered set diff — duplicates collapse per Set semantics
- *   - `async` / `generator` / `typeParameters` change flags follow the raw fields
- */
-function diffSignature(base: Signature | null, head: Signature | null): SignatureDelta | null {
-  if (base === null && head === null) return null
-  if (base === null || head === null) {
-    const empty: ArrayDelta = { added: [], removed: [], modified: [] }
-    const present = base ?? head
-    if (present === null) return null
-    const isBaseNull = base === null
-    const inputs: ArrayDelta = isBaseNull
-      ? { added: [...present.inputs], removed: [], modified: [] }
-      : { added: [], removed: [...present.inputs], modified: [] }
-    const outputs: ArrayDelta = isBaseNull
-      ? { added: [...present.outputs], removed: [], modified: [] }
-      : { added: [], removed: [...present.outputs], modified: [] }
-    const throws: ArrayDelta = isBaseNull
-      ? { added: [...present.throws], removed: [], modified: [] }
-      : { added: [], removed: [...present.throws], modified: [] }
-    return {
-      inputs,
-      outputs,
-      throws,
-      asyncChanged: (base?.async ?? false) !== (head?.async ?? false),
-      generatorChanged: (base?.generator ?? false) !== (head?.generator ?? false),
-      typeParametersChanged: !arraysEqual(
-        base?.typeParameters ?? empty.added.map(String),
-        head?.typeParameters ?? empty.added.map(String),
-      ),
-    }
-  }
-  /**
-   * Parameters are positional, so the index is part of the identity and the fuzz below is 0.
-   * That makes each key unique within its list, so §5.2.0 never has a choice to make here and
-   * both of its passes reduce to the same positional comparison. Dropping the index from the
-   * key would make two same-named parameters ambiguous and hand the choice back to §5.2.0,
-   * which is not what a positional list wants.
-   */
-  const inputMapper = (
-    input: { name: string; type: string },
-    index: number,
-  ): Identified<{ name: string; type: string }> => ({
-    item: input,
-    key: `${index}:${input.name}`,
-    line: index,
-  })
-  const inputs = differentiate(
-    base.inputs.map(inputMapper),
-    head.inputs.map(inputMapper),
-    (a, b) => a.name === b.name && a.type === b.type,
-    0,
-  )
-  const outputs = diffStringList(base.outputs, head.outputs)
-  const throws = diffStringSet(base.throws, head.throws)
-  return {
-    inputs,
-    outputs,
-    throws,
-    asyncChanged: base.async !== head.async,
-    generatorChanged: base.generator !== head.generator,
-    typeParametersChanged: !arraysEqual(base.typeParameters, head.typeParameters),
-  }
-}
-
-function diffStringList(base: readonly string[], head: readonly string[]): ArrayDelta {
-  const added: string[] = []
-  const removed: string[] = []
-  const max = Math.max(base.length, head.length)
-  for (let i = 0; i < max; i++) {
-    const b = i < base.length ? base[i] : undefined
-    const h = i < head.length ? head[i] : undefined
-    if (b === undefined && h !== undefined) added.push(h)
-    else if (h === undefined && b !== undefined) removed.push(b)
-    else if (b !== h) {
-      if (b !== undefined) removed.push(b)
-      if (h !== undefined) added.push(h)
-    }
-  }
-  return { added, removed, modified: [] }
-}
-
-function diffStringSet(base: readonly string[], head: readonly string[]): ArrayDelta {
-  const setB = new Set(base)
-  const setH = new Set(head)
-  const added: string[] = []
-  const removed: string[] = []
-  for (const h of setH) if (!setB.has(h)) added.push(h)
-  for (const b of setB) if (!setH.has(b)) removed.push(b)
-  return { added, removed, modified: [] }
-}
-
-function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
-  if (a.length !== b.length) return false
-  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
-  return true
-}