@aburi/diff 0.2.0 → 0.4.0

package/src/signature.ts

@@ -1,53 +0,0 @@
-import type { Signature } from "@aburi/types"
-
-/**
- * §3.4.2 signatureSimilarity — averaged type-similarity across `inputs`, `outputs`, and
- * `throws`. Follows diff-algorithm.md §3.4.2:
- * - null + null    → 1.0 (both symbols are signature-less; nothing to compare)
- * - null + non-null (either side) → 0.0
- * - both non-null: mean of three subscores
- *
- * Subscores:
- * - inputs: ordered type-string equality rate (`i-th type equal` counts as 1, else 0)
- * - outputs: same shape, but outputs is an array of type strings
- * - throws: unordered set intersection over union
- *
- * Empty subarrays on both sides count as 1.0 (they are trivially equal); on one side only
- * they count as 0.0 (asymmetric information).
- */
-export function signatureSimilarity(
-  base: Signature | null | undefined,
-  head: Signature | null | undefined,
-): number {
-  const baseSig = base ?? null
-  const headSig = head ?? null
-  if (baseSig === null && headSig === null) return 1
-  if (baseSig === null || headSig === null) return 0
-  const inputsScore = compareOrderedTypes(
-    baseSig.inputs.map((i) => i.type),
-    headSig.inputs.map((i) => i.type),
-  )
-  const outputsScore = compareOrderedTypes(baseSig.outputs, headSig.outputs)
-  const throwsScore = compareUnorderedSet(baseSig.throws, headSig.throws)
-  return (inputsScore + outputsScore + throwsScore) / 3
-}
-
-function compareOrderedTypes(a: readonly string[], b: readonly string[]): number {
-  if (a.length === 0 && b.length === 0) return 1
-  if (a.length !== b.length) return 0
-  let matches = 0
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] === b[i]) matches++
-  }
-  return matches / a.length
-}
-
-function compareUnorderedSet(a: readonly string[], b: readonly string[]): number {
-  if (a.length === 0 && b.length === 0) return 1
-  const setA = new Set(a)
-  const setB = new Set(b)
-  let intersection = 0
-  for (const t of setA) if (setB.has(t)) intersection++
-  const union = setA.size + setB.size - intersection
-  return union === 0 ? 1 : intersection / union
-}

package/src/similarity.ts

@@ -1,134 +0,0 @@
-/**
- * String similarity utilities dedicated to the diff engine. Kept in one file so the
- * name/signature/owner formulas are auditable side by side against diff-algorithm.md §3.4.
- */
-
-/**
- * Tokenise a qualified name into normalised lowercase word segments. Splits on:
- * - camelCase / PascalCase boundaries (`fooBar` → `foo`, `Bar`)
- * - snake_case underscores (`foo_bar` → `foo`, `bar`)
- * - dotted namespaces (`ns.Class` → `ns`, `Class`)
- * - `::` static-method separator (`Class::method` → `Class`, `method`)
- * - runs of digits (`get2Users` → `get`, `2`, `Users`)
- *
- * The result is de-duplicated so `InvoiceService.createInvoice` collapses to
- * `["invoice", "service", "create"]` — Jaccard similarity relies on set semantics, so
- * repeated tokens must not double-count.
- */
-export function tokenizeName(input: string): string[] {
-  const seen = new Set<string>()
-  const out: string[] = []
-  for (const raw of input.split(/[.:_\-\s/]+/)) {
-    if (raw.length === 0) continue
-    for (const piece of splitCamel(raw)) {
-      const norm = piece.toLowerCase()
-      if (norm.length === 0 || seen.has(norm)) continue
-      seen.add(norm)
-      out.push(norm)
-    }
-  }
-  return out
-}
-
-function splitCamel(word: string): string[] {
-  const chunks: string[] = []
-  let current = ""
-  for (const ch of word) {
-    if (current === "") {
-      current = ch
-      continue
-    }
-    const prev = current.slice(-1)
-    const boundary = isCamelBoundary(prev, ch)
-    if (boundary) {
-      chunks.push(current)
-      current = ch
-    } else {
-      current += ch
-    }
-  }
-  if (current.length > 0) chunks.push(current)
-  return chunks
-}
-
-function isCamelBoundary(prev: string, curr: string): boolean {
-  const prevLower = prev >= "a" && prev <= "z"
-  const prevUpper = prev >= "A" && prev <= "Z"
-  const prevDigit = prev >= "0" && prev <= "9"
-  const currLower = curr >= "a" && curr <= "z"
-  const currUpper = curr >= "A" && curr <= "Z"
-  const currDigit = curr >= "0" && curr <= "9"
-  if (prevLower && currUpper) return true
-  if ((prevLower || prevUpper) && currDigit) return true
-  if (prevDigit && (currLower || currUpper)) return true
-  return false
-}
-
-/**
- * Jaccard similarity between two token multisets. Formula: |A ∩ B| / |A ∪ B|.
- * Empty on both sides returns 1.0 (both are "no tokens", which are equivalent for the
- * purpose of §3.4.1). Empty on one side only returns 0.0.
- */
-export function jaccard(a: readonly string[], b: readonly string[]): number {
-  if (a.length === 0 && b.length === 0) return 1
-  if (a.length === 0 || b.length === 0) return 0
-  const setA = new Set(a)
-  const setB = new Set(b)
-  let intersection = 0
-  for (const t of setA) if (setB.has(t)) intersection++
-  const union = setA.size + setB.size - intersection
-  return intersection / union
-}
-
-/** name-token Jaccard shortcut used by nameSimilarity and ownerSimilarity call sites. */
-export function jaccardTokens(a: string, b: string): number {
-  return jaccard(tokenizeName(a), tokenizeName(b))
-}
-
-/**
- * §3.4.1 — Jaccard over the tokens of the full qualified name. The last segment is not
- * given extra weight; the entire path contributes uniformly because the intersection is
- * what the score should reward.
- */
-export function nameSimilarity(baseName: string, headName: string): number {
-  return jaccardTokens(baseName, headName)
-}
-
-/**
- * §3.4.6 — owner similarity: same as nameSimilarity but restricted to everything **before**
- * the last segment. Compensates for the R-8 same-name-different-class collision, where
- * `UserRepo.getUser` should not be pair-swapped with `AdminRepo.getUser`.
- *
- * Owner extraction:
- * - `Class::method` → `Class`
- * - `A.B.C.method` → `A.B.C`
- * - `topLevel`     → `` (empty)
- *
- * When both owners are empty (top-level functions), returns 1.0 because both live in the
- * same "no-owner" bucket. When one is empty and the other is not, returns 0.0 because the
- * two Symbols live in structurally different scopes.
- */
-export function ownerSimilarity(baseName: string, headName: string): number {
-  const baseOwner = extractOwner(baseName)
-  const headOwner = extractOwner(headName)
-  if (baseOwner === "" && headOwner === "") return 1
-  if (baseOwner === "" || headOwner === "") return 0
-  return jaccardTokens(baseOwner, headOwner)
-}
-
-function extractOwner(qname: string): string {
-  const staticIdx = qname.indexOf("::")
-  if (staticIdx >= 0) return qname.slice(0, staticIdx)
-  const lastDot = qname.lastIndexOf(".")
-  if (lastDot >= 0) return qname.slice(0, lastDot)
-  return ""
-}
-
-/** §3.4.1 tail note — used by drop-4.5 weak matcher and threshold lookup. */
-export function lastSegment(qname: string): string {
-  const staticIdx = qname.indexOf("::")
-  if (staticIdx >= 0) return qname.slice(staticIdx + 2)
-  const lastDot = qname.lastIndexOf(".")
-  if (lastDot >= 0) return qname.slice(lastDot + 1)
-  return qname
-}

package/src/slice.ts

@@ -1,321 +0,0 @@
-import { type CallEdge, computeWeaklyConnectedComponents, RESERVED_LANGUAGE_IDS } from "@aburi/core"
-import type { SliceId, SliceRecord, SymbolChange, SymbolId } from "@aburi/types"
-import { DiffError } from "./errors"
-
-/** The three inputs of the Slice View pass — docs/design/slice-view.md §3. */
-export interface SliceInput {
-  /** SymbolChange records produced by `buildDiff` (pre-sort is not required). */
-  changes: readonly SymbolChange[]
-  /**
-   * Resolved call edges from the base IR. Typically produced by
-   * `reconstructCallEdgesFromIR(baseIR)` inside `buildDiff` — Slice View
-   * consumes only resolved edges (§5.4), never `Symbol.calls[]` directly.
-   */
-  baseCallEdges: readonly CallEdge[]
-  /** Resolved call edges from the head IR (same source rule as base). */
-  headCallEdges: readonly CallEdge[]
-}
-
-/**
- * Slice View clustering pass — docs/design/slice-view.md §2, §4–§8.
- *
- * Groups the changed-Symbol set of a diff into weakly-connected components
- * over the union of base and head call edges. Emits a `SliceRecord[]` whose
- * cluster ids are `"slice:" + <smallest-member Symbol id>`, both `slices[]`
- * and each `members[]` sorted ascending.
- *
- * Pure function: `(changes, baseCallEdges, headCallEdges)` → `SliceRecord[]`.
- * Determinism, idempotence, input-order insensitivity, and locality are all
- * guaranteed — see `computeWeaklyConnectedComponents` in `@aburi/core`.
- *
- * Returns `[]` when no SymbolChange is Node-eligible per §4.1; callers should
- * still serialise the empty array — the Markdown projection omits the section
- * (§9.4 / §12.5) but the JSON always emits the key so consumers never
- * distinguish "field absent" from "no slices" (§11.2).
- *
- * Every returned record has passed `assertSliceRecordInvariant` (§7.4).
- */
-export function computeSlices(input: SliceInput): SliceRecord[] {
-  const nodeIds = collectNodeIds(input.changes)
-  if (nodeIds.length === 0) return []
-
-  const nodeIdSet = new Set<SymbolId>(nodeIds)
-  const edges = collectEdges(input.baseCallEdges, input.headCallEdges, nodeIdSet)
-
-  const components = computeWeaklyConnectedComponents<SymbolId>(nodeIds, edges, (id) => id)
-
-  return components.map(makeSliceRecord)
-}
-
-const SLICE_ID_PREFIX = "slice:"
-
-/**
- * §7.1 — the single place production code derives a Slice id. Everything else
- * in `src/` either receives an id or renders one. (Tests spell the prefix out
- * literally on purpose: an expectation written in terms of the function under
- * test would agree with it no matter what it produced.)
- *
- * The cast is the one place a `SliceId` comes into existence. `SliceId` and
- * `SymbolId` are separate brands precisely so this concatenation cannot be
- * open-coded anywhere else: a bare `"slice:" + x` evaluates to `string`, which
- * `SliceRecord.id` no longer accepts.
- */
-function sliceIdFor(anchor: SymbolId): SliceId {
-  return `${SLICE_ID_PREFIX}${anchor}` as SliceId
-}
-
-/**
- * Build one SliceRecord from an ascending-sorted component and check its own
- * post-condition before letting it out (§7.4 layer 1).
- *
- * The check is not defending against untrusted input — this function builds
- * the id itself, so the derivation clause is true by construction here and
- * only the two clauses about `members` can actually fire. Those are the point:
- * `members[0]` is the anchor only because `computeWeaklyConnectedComponents`
- * returns each component sorted ascending, a guarantee that lives one layer
- * down and is invisible from this file. If it ever stops holding, the diff
- * would otherwise keep emitting well-formed-looking SliceRecords naming the
- * wrong anchor. Here it fails instead.
- */
-function makeSliceRecord(members: readonly SymbolId[]): SliceRecord {
-  const anchor = members[0]
-  if (anchor === undefined) {
-    throw new DiffError(
-      "computeSlices: the clustering utility returned an empty component; every weakly-connected " +
-        "component contains at least the node that seeded it (slice-view.md §6).",
-      { code: "slice-invariant-violated" },
-    )
-  }
-  const record: SliceRecord = { id: sliceIdFor(anchor), members: [...members] }
-  assertSliceRecordInvariant(record)
-  return record
-}
-
-/**
- * §7.1 — the anchor of a Slice: its lexicographically smallest member.
- *
- * Answers from `members[0]`. `id` is derived from the anchor, so
- * reconstructing the anchor by stripping the `"slice:"` prefix is circular at
- * best and, for a record that broke the derivation, silently wrong: it would
- * name a Symbol that is not in the Slice. `id` is read here only to name the
- * offending record in the error message. Consumers that need the anchor call
- * this; consumers that need a label keep using `id` directly.
- */
-export function sliceAnchor(record: SliceRecord): SymbolId {
-  const anchor = record.members[0]
-  if (anchor === undefined) {
-    const violation = emptyMembersViolation(record.id)
-    throw new DiffError(violation.message, {
-      code: "slice-invariant-violated",
-      value: violation.subject,
-    })
-  }
-  return anchor
-}
-
-/** Which clause of the §7.1 / §8.2 invariant a `SliceRecord` broke. */
-export type SliceViolationKind =
-  /** Not a `SliceRecord` at all: not an object, or `id` / `members` of the wrong type. */
-  | "malformed-shape"
-  /** `members[]` has no entries, so the Slice has no anchor (§11.1). */
-  | "members-empty"
-  /** `members[]` is not in strictly ascending order, so `members[0]` need not be the smallest (§8.2, §11.1). */
-  | "members-unordered"
-  /** `id` is not `"slice:" + members[0]` (§7.1). */
-  | "id-not-derived"
-  /** The anchor is itself in a reserved id namespace, so `id` would read as a doubled prefix (§7.5). */
-  | "anchor-in-reserved-namespace"
-
-export interface SliceRecordViolation {
-  kind: SliceViolationKind
-  /** The offending record's `id` when it has a usable one, else a short stand-in. */
-  subject: string
-  /** Human-facing explanation, suitable for an error message or a validator error. */
-  message: string
-}
-
-/**
- * Report which clause of the §7.1 / §8.2 invariant a value breaks, or `null`
- * when it is a well-formed `SliceRecord`. Non-throwing counterpart of
- * `assertSliceRecordInvariant`: the pass wants an exception, a schema
- * validator wants a verdict it can turn into its own error.
- *
- * Takes `unknown` rather than `SliceRecord` deliberately. §7.4 layer 2 points
- * this at documents written by third-party or older producers — data that has
- * not been type-checked by definition — so anything that assumed a well-typed
- * argument would crash on exactly the input it exists to reject.
- */
-export function sliceRecordViolation(value: unknown): SliceRecordViolation | null {
-  if (typeof value !== "object" || value === null) {
-    return {
-      kind: "malformed-shape",
-      subject: "<not an object>",
-      message: `Expected a SliceRecord object; got ${value === null ? "null" : typeof value}.`,
-    }
-  }
-  const { id, members } = value as { id?: unknown; members?: unknown }
-  const subject = typeof id === "string" ? id : "<missing id>"
-  if (typeof id !== "string") {
-    return {
-      kind: "malformed-shape",
-      subject,
-      message: `SliceRecord ${subject}: id must be a string; got ${typeof id}.`,
-    }
-  }
-  if (!Array.isArray(members) || members.some((member) => typeof member !== "string")) {
-    return {
-      kind: "malformed-shape",
-      subject,
-      message: `SliceRecord ${subject}: members must be an array of strings.`,
-    }
-  }
-
-  const anchor = members[0]
-  if (anchor === undefined) return emptyMembersViolation(subject)
-  // A Symbol id in the `slice:` namespace derives to `slice:slice:…`, which is
-  // self-consistent — it passes the derivation clause below — but names an id no reader can
-  // tell from a Slice id. `makeSymbolId` refuses to build such a Symbol id and
-  // `checkIRIntegrity` #16 rejects one read from disk, but `buildDiff` is public API and
-  // runs no integrity check, so the doubled prefix is caught here too.
-  const reservedAnchor = reservedNamespaceOf(anchor)
-  if (reservedAnchor !== null) {
-    return {
-      kind: "anchor-in-reserved-namespace",
-      subject,
-      message:
-        `SliceRecord anchor "${anchor}" uses the reserved language token "${reservedAnchor}", ` +
-        `so its Slice id would repeat the prefix (ir-schema.md §3.5, slice-view.md §7.5).`,
-    }
-  }
-  for (let i = 1; i < members.length; i++) {
-    const previous = members[i - 1] as string
-    const current = members[i] as string
-    if (previous < current) continue
-    return {
-      kind: "members-unordered",
-      subject,
-      message:
-        `SliceRecord ${subject}: members[] is not in strictly ascending order at index ${i} ` +
-        `("${current}" follows "${previous}"), so members[0] is not necessarily the anchor ` +
-        `(slice-view.md §8.2 for the order, §11.1 for uniqueness).`,
-    }
-  }
-  // The one place outside `sliceIdFor` that asserts an id brand, and the reason this
-  // function takes `unknown`: the anchor has been checked to be a string and nothing more.
-  // Whether it is a well-formed Symbol id is not this check's question — a record whose
-  // members are gibberish still has to be told apart from one whose id disagrees with them.
-  const expected = sliceIdFor(anchor as SymbolId)
-  if (id !== expected) {
-    return {
-      kind: "id-not-derived",
-      subject,
-      message:
-        `SliceRecord id "${id}" is not derived from the anchor "${anchor}"; ` +
-        `expected "${expected}" (slice-view.md §7.1).`,
-    }
-  }
-  return null
-}
-
-/** The reserved token an id opens with, or `null`. Shares the list `@aburi/core` enforces. */
-function reservedNamespaceOf(id: string): string | null {
-  const colon = id.indexOf(":")
-  if (colon < 0) return null
-  const token = id.slice(0, colon)
-  return RESERVED_LANGUAGE_IDS.has(token) ? token : null
-}
-
-/** Single source of the empty-`members[]` wording, shared with `sliceAnchor`. */
-function emptyMembersViolation(subject: string): SliceRecordViolation {
-  return {
-    kind: "members-empty",
-    subject,
-    message:
-      `SliceRecord ${subject}: members[] is empty, so the Slice has no anchor ` +
-      `(slice-view.md §11.1 requires at least one member).`,
-  }
-}
-
-/**
- * Throwing form of `sliceRecordViolation`. Raised as a coded `DiffError` so
- * callers branch on `code` rather than parsing the message; which clause broke
- * is `SliceRecordViolation.kind`, for callers that need to tell them apart.
- */
-export function assertSliceRecordInvariant(record: SliceRecord): void {
-  const violation = sliceRecordViolation(record)
-  if (violation === null) return
-  throw new DiffError(violation.message, {
-    code: "slice-invariant-violated",
-    value: violation.subject,
-  })
-}
-
-/**
- * §4.1 Node selection: keep every SymbolChange whose status is
- * added / removed / changed / moved+changed / dropped-toggled. The identity
- * is the head-side Symbol id where present (added / changed / moved+changed /
- * dropped-toggled), the base-side id for removed. Pure moved and unchanged
- * (already stripped upstream) are excluded — §4.1 / §4.3.
- *
- * The returned array is deliberately not deduplicated: a well-formed
- * SymbolChange list from `buildDiff` never mentions the same Symbol id
- * twice, and Union-Find would coalesce any accidental duplicate anyway.
- */
-function collectNodeIds(changes: readonly SymbolChange[]): SymbolId[] {
-  const ids: SymbolId[] = []
-  for (const change of changes) {
-    const id = nodeIdOf(change)
-    if (id === null) continue
-    ids.push(id)
-  }
-  return ids
-}
-
-function nodeIdOf(change: SymbolChange): SymbolId | null {
-  switch (change.status) {
-    case "added":
-      return change.symbol.id
-    case "removed":
-      // §4.1 — removed uses base-side id because there is no head symbol.
-      return change.symbol.id
-    case "changed":
-    case "moved+changed":
-    case "dropped-toggled":
-      return change.after.id
-    case "moved":
-      // §4.3 — pure moved is not a Node and is not used for bridging either.
-      return null
-  }
-  // Exhaustive: if SymbolChange grows a new status the compile error above
-  // fires before this fallback is reachable.
-}
-
-/**
- * §5.1 Edge selection: union of base and head, restricted to edges whose
- * BOTH endpoints are Nodes, canonicalised to `(u, v)` with `u < v` (self-
- * loops implicitly dropped). Multi-edges collapse naturally inside the WCC
- * primitive — no explicit dedup needed.
- *
- * The union is the load-bearing rule of §5.3: a controller that called an
- * old service in base and a new service in head needs both edges to land
- * all three Symbols in a single Slice.
- */
-function collectEdges(
-  baseEdges: readonly CallEdge[],
-  headEdges: readonly CallEdge[],
-  nodeIds: ReadonlySet<SymbolId>,
-): [SymbolId, SymbolId][] {
-  const pairs: [SymbolId, SymbolId][] = []
-  for (const edge of baseEdges) appendEdgeIfBothNodes(edge, nodeIds, pairs)
-  for (const edge of headEdges) appendEdgeIfBothNodes(edge, nodeIds, pairs)
-  return pairs
-}
-
-function appendEdgeIfBothNodes(
-  edge: CallEdge,
-  nodeIds: ReadonlySet<SymbolId>,
-  out: [SymbolId, SymbolId][],
-): void {
-  if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) return
-  out.push([edge.from, edge.to])
-}

package/src/status.ts

@@ -1,36 +0,0 @@
-import type { Symbol as IRSymbol } from "@aburi/types"
-
-export type SymbolStatus = "unchanged" | "moved" | "changed" | "moved+changed" | "dropped-toggled"
-
-/**
- * §4 — determine which of the five statuses a matched pair falls into. `dropped-toggled`
- * has absolute priority: whenever `dropped` differs between base and head, every other
- * signal is ignored because the underlying fingerprint change is a consequence of the
- * drop-rule flip, not a genuine code edit (§4.1 rationale).
- *
- * "pathChanged" catches both physical file relocation AND in-file rename: any Symbol id
- * mismatch between base and head means the identifier moved, and DF9 ("method rename
- * (same file, same logic) → moved") relies on this. Stage-1 pairs cannot trigger the id branch
- * (they match by exact id), so this only affects stage-2+ pairings where the pair was
- * discovered via fingerprint or name/signature similarity.
- */
-export function classifyStatus(base: IRSymbol, head: IRSymbol): SymbolStatus {
-  const droppedToggled = base.dropped !== head.dropped
-  if (droppedToggled) return "dropped-toggled"
-  const pathChanged = base.source.file !== head.source.file || base.id !== head.id
-  const fingerprintChanged =
-    base.fingerprint.api !== head.fingerprint.api ||
-    base.fingerprint.logic !== head.fingerprint.logic ||
-    base.fingerprint.syntax !== head.fingerprint.syntax
-  if (pathChanged && fingerprintChanged) return "moved+changed"
-  if (pathChanged) return "moved"
-  if (fingerprintChanged) return "changed"
-  return "unchanged"
-}
-
-/** Direction of a `dropped-toggled` transition (§7.1 SymbolDroppedToggled). */
-export type DropDirection = "to-dropped" | "to-kept"
-
-export function dropDirection(head: IRSymbol): DropDirection {
-  return head.dropped ? "to-dropped" : "to-kept"
-}