@aburi/diff 0.2.0 → 0.3.0

package/src/diff.ts

@@ -1,6 +1,21 @@
 import { reconstructCallEdgesFromIR, type SerializeOptions, serializeCanonical } from "@aburi/core"
-import type { DiffResult, IR, IRRef, Summary, SymbolChange } from "@aburi/types"
-import { diffComponents, diffDependencies } from "./components"
+import type {
+  DiffResult,
+  IR,
+  IRRef,
+  NotComparedFile,
+  RelativePath,
+  SkipReason,
+  Summary,
+  SymbolChange,
+} from "@aburi/types"
+import {
+  DEPENDENCY_IDENTITY_FIELDS,
+  dependencyIdentity,
+  dependencySideView,
+  diffComponents,
+  diffDependencies,
+} from "./components"
 import { computeSymbolDelta, type DeltaOptions } from "./delta"
 import { DiffError } from "./errors"
 import {
@@ -15,7 +30,20 @@ import {
 import { computeSlices } from "./slice"
 import { classifyStatus, dropDirection } from "./status"
 
-const DIFF_SCHEMA = "https://aburi.dev/schema/aburi.diff.v1.json"
+const DIFF_SCHEMA = "https://aburi.kage1020.com/schema/aburi.diff.v1.json"
+
+/**
+ * The two counters `buildDiff` always writes, narrowed off `Summary`'s optionals.
+ *
+ * They are optional on the wire so a diff written before they existed stays valid, and that
+ * optionality is about *documents*, not about this function — a caller holding a value it just
+ * built should not have to re-decide what "absent" would have meant. Same reason
+ * `diffDependencies` declares its `unknown` array present.
+ */
+interface UnknownCounters {
+  unknown: number
+  depsUnknown: number
+}
 
 export interface DiffInput {
   baseIR: IR
@@ -40,9 +68,11 @@ const DEFAULT_GENERATOR = { name: "aburi", version: "0.0.0" }
  * pipe the result through additional steps (Markdown projection, `--fail-on` gate) before
  * serialisation.
  */
-export function buildDiff(input: DiffInput): DiffResult {
-  assertIRShape(input.baseIR, "baseIR")
-  assertIRShape(input.headIR, "headIR")
+export function buildDiff(
+  input: DiffInput,
+): DiffResult & { notCompared: NotComparedFile[]; summary: Summary & UnknownCounters } {
+  assertDiffable(input.baseIR, "baseIR")
+  assertDiffable(input.headIR, "headIR")
   ensureSchemasAgree(input.baseIR, input.headIR)
   const stage1 = matchStageId(input.baseIR.symbols, input.headIR.symbols)
   const stage2 = matchStageGitRename(
@@ -62,7 +92,12 @@ export function buildDiff(input: DiffInput): DiffResult {
     ...stage4_5.matched,
   ]
 
-  const summary: Summary = {
+  // Typed with the two counters present. They are optional on the wire, but this function
+  // writes both on every diff, and the local type is what carries that from here to the
+  // return without a cast.
+  const summary: Summary & UnknownCounters = {
+    unknown: 0,
+    depsUnknown: 0,
     added: 0,
     removed: 0,
     moved: 0,
@@ -78,6 +113,9 @@ export function buildDiff(input: DiffInput): DiffResult {
     depsAdded: 0,
     depsRemoved: 0,
   }
+  // Counted locally and assigned once below, where the other totals are, so the increment
+  // sites do not have to reason about a counter that is optional on the wire.
+  let unknown = 0
 
   const symbols: SymbolChange[] = []
   for (const pair of pairs) {
@@ -130,19 +168,51 @@ export function buildDiff(input: DiffInput): DiffResult {
   const finalRemainingHead = stage4_5.remainingHead
   const finalRemainingBase = stage4_5.remainingBase
 
+  // Read after the five matching stages, never before them. A Symbol that crossed files
+  // between the two revisions is paired by stage 2, 3 or 4 and comes out `moved` or
+  // `moved+changed`, whichever end of the move sits in the lost file — the other document
+  // holds real evidence for it either way. Only the leftovers are absences, and only an
+  // absence in a file that was never analysed is unexplained.
+  //
+  // The two loops below read opposite ends: a base leftover is looked up by the file it
+  // came from, a head leftover by the file it arrived in. In both cases the question is the
+  // same — did the document that lacks this Symbol ever read the file it is in?
+  // One construction per side, shared with the Dependency diff below. The Symbol loops and
+  // `diffDependencies` therefore read the same two maps rather than two answers to the same
+  // question — which is what makes "a Symbol reported unknown and the edges it took with it
+  // cannot disagree about which file went missing" structural instead of aspirational.
+  const baseSide = dependencySideView(input.baseIR)
+  const headSide = dependencySideView(input.headIR)
+  const lostByHead = headSide.lostFiles
+  const lostByBase = baseSide.lostFiles
+
   for (const h of finalRemainingHead) {
-    if (h.dropped) summary.droppedAdded++
-    else {
-      summary.added++
-      symbols.push({ status: "added", symbol: h })
+    if (h.dropped) {
+      summary.droppedAdded++
+      continue
+    }
+    const reason = lostByBase.get(h.source.file)
+    if (reason !== undefined) {
+      unknown++
+      symbols.push({ status: "unknown", symbol: h, absentFrom: "base", reason })
+      continue
     }
+    summary.added++
+    symbols.push({ status: "added", symbol: h })
   }
   for (const b of finalRemainingBase) {
-    if (b.dropped) summary.droppedRemoved++
-    else {
-      summary.removed++
-      symbols.push({ status: "removed", symbol: b })
+    if (b.dropped) {
+      summary.droppedRemoved++
+      continue
     }
+    const reason = lostByHead.get(b.source.file)
+    if (reason !== undefined) {
+      unknown++
+      symbols.push({ status: "unknown", symbol: b, absentFrom: "head", reason })
+      continue
+    }
+    summary.removed++
+    symbols.push({ status: "removed", symbol: b })
   }
 
   const components = diffComponents(input.baseIR.components, input.headIR.components)
@@ -150,9 +220,16 @@ export function buildDiff(input: DiffInput): DiffResult {
   summary.componentsRemoved = components.removed.length
   summary.componentsChanged = components.changed.length
 
-  const dependencies = diffDependencies(input.baseIR.dependencies, input.headIR.dependencies)
+  const dependencies = diffDependencies(input.baseIR.dependencies, input.headIR.dependencies, {
+    base: baseSide,
+    head: headSide,
+  })
   summary.depsAdded = dependencies.added.length
   summary.depsRemoved = dependencies.removed.length
+  // No `?? 0`: `diffDependencies` declares `unknown` present when it is given side views, so
+  // absorbing an absence here would launder a mis-wiring into a confident `depsUnknown: 0`.
+  summary.depsUnknown = dependencies.unknown.length
+  summary.unknown = unknown
 
   symbols.sort(compareSymbolChange)
 
@@ -177,9 +254,41 @@ export function buildDiff(input: DiffInput): DiffResult {
     components,
     dependencies,
     slices,
+    notCompared: filesNeitherSideRead(lostByBase, lostByHead),
   }
 }
 
+/**
+ * Paths both documents record as never analysed, with each side's own reason.
+ *
+ * This is the loss `unknown` cannot describe. That status is derived from the matcher's
+ * leftovers — a Symbol one document holds and the other lacks — and a file skipped on both
+ * sides contributes Symbols to neither, so it leaves no leftover to classify and the whole
+ * document falls silent about it. Silence is the one thing it must not do here: a diff with
+ * nothing to say about a path is exactly what a diff that compared it and found it unchanged
+ * looks like.
+ *
+ * The intersection, not the union. A one-sided loss has leftovers on the other side and is
+ * reported as `unknown` there; listing it here as well would count one loss twice, in two
+ * vocabularies that mean different things.
+ *
+ * Always returns an array, empty included. Optionality in the schema covers documents written
+ * before the field existed, and no arithmetic elsewhere in a diff would let a reader tell that
+ * case from a run that missed nothing (docs/design/diff-algorithm.md §10.1).
+ */
+function filesNeitherSideRead(
+  lostByBase: ReadonlyMap<RelativePath, SkipReason>,
+  lostByHead: ReadonlyMap<RelativePath, SkipReason>,
+): NotComparedFile[] {
+  const both: NotComparedFile[] = []
+  for (const [path, baseReason] of lostByBase) {
+    const headReason = lostByHead.get(path)
+    if (headReason === undefined) continue
+    both.push({ path, baseReason, headReason })
+  }
+  return both.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}
+
 /** §9.1 — refuse to diff across schema versions. */
 function ensureSchemasAgree(base: IR, head: IR): void {
   if (base.$schema !== head.$schema) {
@@ -190,36 +299,160 @@ function ensureSchemasAgree(base: IR, head: IR): void {
   }
 }
 
+/** Which of the two inputs a message is about. */
+type IRSide = "baseIR" | "headIR"
+
 /**
- * Top-level shape check. Refuses to enter the 5-stage matcher when a caller hands in an
- * IR-shaped object that is missing one of the collections the matcher requires as an
- * array. Without this, a malformed `baseIR = { symbols: undefined, ... }` would crash
- * deep inside `matchStageId` with `TypeError: undefined is not iterable`, leaving the
- * root cause obscured. Not a full schema validation — just an entry-point smoke test.
+ * A collection `buildDiff` keys by identity. One descriptor drives both halves of the
+ * entry-point check — that the entries are objects carrying string identity fields, and that
+ * no identity repeats — so the two cannot come to describe different collections, and a
+ * fourth entry added here is guarded by both or by neither. Reporting order is the order of
+ * this array, base side before head side.
  */
-function assertIRShape(ir: IR, name: "baseIR" | "headIR"): void {
+interface IdentifiedCollection {
+  readonly field: "symbols" | "components" | "dependencies"
+  /** The fields identity is read from, in the order `keyOf` receives them. */
+  readonly identityFields: readonly string[]
+  /** Join them the way the diff itself keys on them, or the check guards nothing. */
+  readonly keyOf: (parts: readonly string[]) => string
+  /** How a message names the repeated value. */
+  readonly noun: string
+  /** The repeated value as the IR spells it; also what `DiffError.value` carries. */
+  readonly show: (parts: readonly string[]) => string
+  /** What the diff does with a repeat, and the invariant that forbids it. */
+  readonly consequence: string
+}
+
+/** Identity is a single field, so joining the one-member tuple is joining nothing. */
+const soleField = (parts: readonly string[]): string => parts.join("")
+
+const IDENTIFIED_COLLECTIONS: readonly IdentifiedCollection[] = [
+  {
+    field: "symbols",
+    identityFields: ["id"],
+    keyOf: soleField,
+    noun: "id",
+    show: soleField,
+    consequence:
+      "stage 1 pairs Symbols by id and every later stage tracks the base Symbols it has " +
+      "consumed by id, so a repeat leaves one entry out of the diff entirely or classifies " +
+      "its counterpart twice (ir-schema.md §14 #1)",
+  },
+  {
+    field: "components",
+    identityFields: ["id"],
+    keyOf: soleField,
+    noun: "id",
+    show: soleField,
+    consequence:
+      "Component identity is the id, so a repeat hides one entry and can report a change " +
+      "the two revisions do not contain (ir-schema.md §14 #2)",
+  },
+  {
+    field: "dependencies",
+    identityFields: DEPENDENCY_IDENTITY_FIELDS,
+    keyOf: dependencyIdentity,
+    noun: "(from, to, via) triple",
+    show: (parts) => `(${parts.join(", ")})`,
+    consequence:
+      "direction and effect are deliberately outside Dependency identity (§6.2), so a " +
+      "repeat surfaces as an added + removed pair no reader can tell from a real flip " +
+      "(ir-schema.md §14 #13)",
+  },
+]
+
+/**
+ * The two things `buildDiff` needs before stage 1 runs: a Document it can walk, and
+ * identities it can key on. diff-algorithm.md §3.7 states the second and why it is checked
+ * here as well as at extraction time.
+ *
+ * Neither half is a full schema validation. A Symbol that reaches stage 1 is an object with
+ * a string `id`, because the identity scan reads that much; nothing checks it carries a
+ * `fingerprint`, which is `checkIRIntegrity` #20's job and runs when the CLI reads an IR off
+ * disk. What this does buy is that a malformed collection is named — `symbols: undefined`
+ * used to surface as `TypeError: undefined is not iterable` and `symbols: [null]` as
+ * `TypeError: Cannot read properties of null (reading 'id')`, both from inside
+ * `matchStageId`, with neither the collection nor the index named.
+ */
+function assertDiffable(ir: IR, name: IRSide): void {
   if (ir === null || typeof ir !== "object") {
-    throw new DiffError(`${name} must be an IR object; got ${typeof ir}.`, {
-      code: "ir-shape-invalid",
-      value: name,
-    })
+    throw shapeError(name, `${name} must be an IR object; got ${describeValue(ir)}.`)
   }
   if (typeof ir.$schema !== "string" || ir.$schema.length === 0) {
-    throw new DiffError(`${name}.$schema must be a non-empty schema URL.`, {
-      code: "ir-shape-invalid",
-      value: `${name}.$schema`,
-    })
+    throw shapeError(`${name}.$schema`, `${name}.$schema must be a non-empty schema URL.`)
   }
-  for (const field of ["symbols", "components", "dependencies"] as const) {
-    if (!Array.isArray(ir[field])) {
-      throw new DiffError(`${name}.${field} must be an array.`, {
-        code: "ir-shape-invalid",
-        value: `${name}.${field}`,
-      })
+  for (const collection of IDENTIFIED_COLLECTIONS) {
+    assertUniqueIdentity(ir[collection.field], `${name}.${collection.field}`, collection)
+  }
+}
+
+function assertUniqueIdentity(
+  entries: unknown,
+  subject: string,
+  collection: IdentifiedCollection,
+): void {
+  if (!Array.isArray(entries)) {
+    throw shapeError(subject, `${subject} must be an array.`)
+  }
+  const firstSeen = new Map<string, number>()
+  for (const [index, entry] of entries.entries()) {
+    const entrySubject = `${subject}[${index}]`
+    const parts = identityFieldsOf(entry, entrySubject, collection)
+    const key = collection.keyOf(parts)
+    const first = firstSeen.get(key)
+    if (first === undefined) {
+      firstSeen.set(key, index)
+      continue
     }
+    const shown = collection.show(parts)
+    throw new DiffError(
+      `${entrySubject} repeats the ${collection.noun} "${shown}" first seen at index ` +
+        `${first}; ${collection.consequence}.`,
+      { code: "ir-identity-collision", value: shown },
+    )
   }
 }
 
+/**
+ * The identity fields of one entry, established as strings on the way out. Reading them is
+ * what forces the check: without it a Symbol carrying no `id` has nothing to collide with,
+ * passes, and derives a Slice anchored on `undefined` several stages later — which
+ * `assertSliceRecordInvariant` reports as `slice-invariant-violated`, the one code the CLI
+ * presents as a bug in Aburi rather than in the caller's IR.
+ */
+function identityFieldsOf(
+  entry: unknown,
+  subject: string,
+  collection: IdentifiedCollection,
+): string[] {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw shapeError(subject, `${subject} must be an object; got ${describeValue(entry)}.`)
+  }
+  const parts: string[] = []
+  for (const field of collection.identityFields) {
+    const value = (entry as Record<string, unknown>)[field]
+    if (typeof value !== "string") {
+      throw shapeError(
+        `${subject}.${field}`,
+        `${subject}.${field} must be a string; got ${describeValue(value)}.`,
+      )
+    }
+    parts.push(value)
+  }
+  return parts
+}
+
+function shapeError(subject: string, message: string): DiffError {
+  return new DiffError(message, { code: "ir-shape-invalid", value: subject })
+}
+
+function describeValue(value: unknown): string {
+  if (value === undefined) return "undefined"
+  if (value === null) return "null"
+  if (Array.isArray(value)) return "an array"
+  return `a ${typeof value}`
+}
+
 /**
  * Deterministic ordering of the `symbols[]` output:
  * 1. by status (alphabetical) — pins added/changed/moved sections
@@ -236,10 +469,21 @@ function compareSymbolChange(a: SymbolChange, b: SymbolChange): number {
 }
 
 function referenceId(change: SymbolChange): string {
-  if (change.status === "added" || change.status === "removed") return change.symbol.id
+  if (change.status === "added" || change.status === "removed" || change.status === "unknown") {
+    return change.symbol.id
+  }
   return change.after.id
 }
 
+/**
+ * The files a document's scan never analysed, by path, with why.
+ *
+ * `stats.skippedFiles` is Class B: absent means the writer predates the field, not that
+ * nothing was lost. An empty map is the honest answer either way — with no enumeration
+ * there is no absence this function can explain, and guessing from
+ * `totalFiles > parsedFiles` would attach a reason to whichever Symbols happened to be
+ * missing. The CLI says so on stderr instead; a diff cannot invent the list.
+ */
 /**
  * Byte-deterministic serialiser for a DiffResult. Delegates to `@aburi/core`
  * `serializeCanonical` so the sort order, NFC normalisation, and codepoint key sort are

package/src/errors.ts

@@ -15,6 +15,13 @@ export type DiffErrorCode =
    * cryptic `TypeError: undefined is not iterable` deep in a matching stage.
    */
   | "ir-shape-invalid"
+  /**
+   * `baseIR` or `headIR` repeats an identity the diff keys on: a `symbols[].id`, a
+   * `components[].id`, or a `dependencies[]` `(from, to, via)` triple. Distinct from
+   * `ir-shape-invalid` because the Document is well-formed — the collision changes the
+   * answer rather than preventing one, and ir-schema.md §14 #1 / #2 / #13 already forbid it.
+   */
+  | "ir-identity-collision"
   /**
    * A `SliceRecord` broke the derivation invariant of slice-view.md §7.1 / §8.2:
    * `members[]` empty, `members[]` not in strictly ascending order, or `id` not

package/src/index.ts

@@ -1,4 +1,6 @@
 export {
+  type DependencySideView,
+  dependencySideView,
   diffComponents,
   diffDependencies,
 } from "./components"
@@ -33,8 +35,9 @@ export {
   jaccard,
   jaccardTokens,
   lastSegment,
+  memberSimilarity,
   nameSimilarity,
-  ownerSimilarity,
+  ownersAreCompatible,
   tokenizeName,
 } from "./similarity"
 export {