@aburi/diff 0.1.0 → 0.3.0

package/src/components.ts

@@ -1,10 +1,27 @@
-import type { Component, ComponentDiff, Dependency, DependencyDiff } from "@aburi/types"
+import type {
+  Component,
+  ComponentDiff,
+  ComponentId,
+  Dependency,
+  DependencyDiff,
+  DependencyEndpoint,
+  DependencyUnknown,
+  DiffSkippedFile,
+  IR,
+  RelativePath,
+  SkipReason,
+} from "@aburi/types"
 
 /**
- * §6.1 — Component diff. Component identity is `id`; when a Component is present in both
+ * `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 (§5.2.3): fields are reported as before/after
+ * 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.
  */
@@ -12,9 +29,9 @@ export function diffComponents(
   base: readonly Component[],
   head: readonly Component[],
 ): ComponentDiff {
-  const baseById = new Map<string, Component>()
+  const baseById = new Map<ComponentId, Component>()
   for (const c of base) baseById.set(c.id, c)
-  const headById = new Map<string, Component>()
+  const headById = new Map<ComponentId, Component>()
   for (const c of head) headById.set(c.id, c)
 
   const added: Component[] = []
@@ -51,41 +68,177 @@ export function diffComponents(
 }
 
 /**
- * §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).
+ * 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[],
-): DependencyDiff {
+  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) {
-      added.push(dep)
+      // 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)) removed.push(dep)
+    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)
-  return { added, removed }
+  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 `${d.from}::${d.to}::${d.via}`
+  return dependencyIdentity(DEPENDENCY_IDENTITY_FIELDS.map((field) => d[field]))
 }
 
 function compareDependencies(a: Dependency, b: Dependency): number {

package/src/delta.ts

@@ -81,10 +81,23 @@ interface Identified<T> {
 }
 
 /**
- * Two-index diff: build key-indexed maps for both sides, then classify each key into
- * `added` / `removed` / `modified`. Line-fuzzed identities are matched within tolerance
- * so cosmetic line shifts do not produce added/removed noise. `modified` only fires when
- * the identity key stays the same but the content differs.
+ * §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>[],
@@ -92,37 +105,109 @@ function differentiate<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 removed: T[] = []
   const modified: T[] = []
-  const consumedBase = new Set<number>()
-  for (const h of head) {
-    let matchIdx = -1
-    for (let j = 0; j < base.length; j++) {
-      if (consumedBase.has(j)) continue
-      const b = base[j]
-      if (b === undefined) continue
-      if (b.key !== h.key) continue
-      if (Math.abs(b.line - h.line) > lineFuzz) continue
-      matchIdx = j
-      break
+  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
     }
-    if (matchIdx === -1) {
-      added.push(h.item)
+  }
+
+  // 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
     }
-    consumedBase.add(matchIdx)
-    const bmatch = base[matchIdx]
-    if (bmatch === undefined) continue
-    if (!isEqual(bmatch.item, h.item)) modified.push(h.item)
-  }
-  for (let j = 0; j < base.length; j++) {
-    if (consumedBase.has(j)) continue
-    const b = base[j]
-    if (b === undefined) continue
-    removed.push(b.item)
+    const skipBase = best[i + 1]?.[j] ?? NO_PAIRINGS
+    if (skipBase.pairs === here.pairs && skipBase.distance === here.distance) i++
+    else j++
   }
-  return { added, removed, modified }
+  return chosen
 }
 
 function diffRules(base: readonly Rule[], head: readonly Rule[], lineFuzz: number): ArrayDelta {
@@ -148,7 +233,14 @@ function diffEffects(base: readonly Effect[], head: readonly Effect[]): ArrayDel
   const mapper = (e: Effect): Identified<Effect> => ({
     item: e,
     key: `${e.id}::${e.target}`,
-    line: e.line,
+    // 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)
 }
@@ -241,6 +333,13 @@ function diffSignature(base: Signature | null, head: Signature | null): Signatur
       ),
     }
   }
+  /**
+   * 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,