@aburi/diff 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @aburi/diff
+
+Aburi diff engine. Takes two IRs (base + head) and emits an `aburi.diff.v1`
+projection: matched Symbol pairs, per-Symbol status + delta, Component / Dependency
+diffs, and canonical JSON output. Pure — write-to-disk is delegated to the caller
+so mid-pipeline gate evaluation can happen before serialisation.
+
+## 5-stage matcher
+
+Symbols are paired across base / head via cascading stages:
+
+1. **id-match** — `<language>:<path>#<qname>` equal → same Symbol.
+2. **git-rename** — optional table (from `git diff --find-renames`) rescues moved
+   files whose ids diverged only in the path segment.
+3. **logic-fingerprint** — remaining Symbols with the same `fingerprint.logic`
+   hash pair up (rename-invariant, whitespace-invariant).
+4. **name+signature** — same simple name + compatible `Signature` (input/output
+   set + throws) — the fuzzy layer.
+5. **dropped-weak** — last-resort match for pairs where both sides are dropped
+   (e.g. two empty stubs with matching qnames).
+
+Unmatched base Symbols become `removed`, unmatched head Symbols become `added`.
+Matched pairs are classified into one of five statuses per
+[`design/details/diff-algorithm.md`](../../design/details/diff-algorithm.md):
+`unchanged` / `moved` / `changed` / `moved+changed` / `dropped-toggled`
+(with `to-dropped` / `to-kept` direction).
+
+Per-Symbol delta records what specifically changed: rules array delta, effects
+array delta, calls array delta, decorators delta, signature delta, and the three
+boolean summary bits `apiChanged` / `logicChanged` / `syntaxChanged`.
+
+## Install
+
+```bash
+pnpm add @aburi/diff
+```
+
+## Usage
+
+```ts
+import { buildDiff, writeCanonicalDiff } from "@aburi/diff"
+
+const diff = buildDiff({
+  baseIR,
+  headIR,
+  base: { ref: "main", irSchema: "https://aburi.dev/schema/aburi.ir.v1.json" },
+  head: { ref: "HEAD", irSchema: "https://aburi.dev/schema/aburi.ir.v1.json" },
+  gitRenames: null,          // optional: { oldPath: newPath } table
+})
+
+diff.summary
+// { added, removed, moved, movedChanged, changed, droppedToggled, ... }
+
+await writeFile("out/diff.json", writeCanonicalDiff(diff), "utf8")
+// Or, to mirror `aburi diff --compact`:
+await writeFile("out/diff.json", writeCanonicalDiff(diff, { format: "compact" }), "utf8")
+```
+
+## See also
+
+- [`schema/aburi.diff.v1.json`](../../schema/aburi.diff.v1.json)
+- [`design/details/diff-algorithm.md`](../../design/details/diff-algorithm.md)

package/dist/index.d.mts

@@ -0,0 +1,277 @@
+import { SerializeOptions } from "@aburi/core";
+import { Component, ComponentDiff, Dependency, DependencyDiff, DiffResult, IR, IRRef, MatchRationale, Signature, Symbol, SymbolDelta } from "@aburi/types";
+
+//#region src/components.d.ts
+/**
+ * §6.1 — Component diff. 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
+ * pairs via the `changed[]` entries so consumers can render them without stringifying
+ * arrays.
+ */
+declare function diffComponents(base: readonly Component[], head: readonly Component[]): ComponentDiff;
+/**
+ * §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).
+ */
+declare function diffDependencies(base: readonly Dependency[], head: readonly Dependency[]): DependencyDiff;
+//#endregion
+//#region src/delta.d.ts
+declare const DEFAULT_LINE_FUZZ = 2;
+declare const MAX_LINE_FUZZ = 10;
+declare const MIN_LINE_FUZZ = 0;
+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.
+ */
+declare function computeSymbolDelta(base: Symbol, head: Symbol, options?: DeltaOptions): SymbolDelta;
+//#endregion
+//#region src/match.d.ts
+/**
+ * A concluded pairing of one base Symbol with one head Symbol, along with the
+ * `MatchRationale` that placed them in the same pair. Stage 4 uses this shape both to
+ * carry results out and to feed the delta / status classifier downstream.
+ */
+interface SymbolPair {
+  base: Symbol;
+  head: Symbol;
+  rationale: MatchRationale;
+}
+/** Optional map returned by git for stage 2 (`old path` → `new path`). */
+type GitRenameMap = ReadonlyMap<string, string>;
+/**
+ * §3.1 — segments Symbols with identical `id` into paired matches. Runs first because it
+ * is the highest-confidence signal (no heuristics, just hash lookup).
+ */
+declare function matchStageId(base: readonly Symbol[], head: readonly Symbol[]): {
+  matched: SymbolPair[];
+  remainingBase: Symbol[];
+  remainingHead: Symbol[];
+};
+/**
+ * §3.2 — git rename detection. When a rename map is available (typical of ref-driven
+ * scans), rewrite the base id with the head-side file path and look for a hit.
+ *
+ * The rewriter only touches the `file` portion of the id — the `<language>:` prefix and
+ * the trailing `#<qualified-name>` segment stay unchanged so a moved file with the same
+ * qualified name is picked up correctly. When a Symbol's file is not in the rename map,
+ * it is left for later stages.
+ */
+declare function matchStageGitRename(remainingBase: readonly Symbol[], remainingHead: readonly Symbol[], renameMap: GitRenameMap | null): {
+  matched: SymbolPair[];
+  remainingBase: Symbol[];
+  remainingHead: Symbol[];
+};
+/**
+ * §3.3 — group base Symbols by `fingerprint.logic` and match head Symbols whose logic
+ * fingerprint is in the map. Two disambiguation branches:
+ * - single candidate → paired with `logic-fingerprint`
+ * - multiple candidates → best `nameSimilarity` wins if ≥ 0.85; otherwise leave both
+ *   sides in remaining for stage 4 to re-evaluate
+ *
+ * Dropped symbols are excluded (§3.3 tail) — their logic fingerprint is the sentinel
+ * `"000000000000"` and would collide with every other dropped Symbol in the workspace.
+ * They flow to the stage-4.5 weak matcher instead.
+ */
+declare function matchStageLogicFingerprint(remainingBase: readonly Symbol[], remainingHead: readonly Symbol[]): {
+  matched: SymbolPair[];
+  remainingBase: Symbol[];
+  remainingHead: Symbol[];
+};
+/**
+ * §3.4 — name + signature similarity with `(kind, signatureNullness)` bucket pre-filter.
+ * `signatureNullness` distinguishes symbols with no signature (`interface`, `type`,
+ * `class`) from callable ones so that a class body is never paired against a function.
+ *
+ * The composite score:
+ *   0.5 * nameSimilarity + 0.3 * signatureSimilarity + 0.2 * ownerSimilarity
+ *
+ * §3.4.3 threshold table:
+ * - 1-token name → 1.0 (unreachable → never paired; false-positive shield)
+ * - 2-token name → 0.95 (strict, avoids `getUser` vs `getUsers`)
+ * - default      → 0.85
+ *
+ * §3.4.3 tail — if both sides are signature-less, we skip pairing entirely because
+ * signatureSimilarity always returns 1.0 for `null + null` and would flood the bucket with
+ * false pairings.
+ */
+declare function matchStageNameSignature(remainingBase: readonly Symbol[], remainingHead: readonly Symbol[]): {
+  matched: SymbolPair[];
+  remainingBase: Symbol[];
+  remainingHead: Symbol[];
+};
+/**
+ * §3.4.5 — dropped-only weak matcher. For dropped Symbols the fingerprint is zeroed and
+ * name/signature are the only remaining signals. Score is a coarse "did the last name
+ * segment or file basename survive?" — if either half matches we pair (threshold 0.5).
+ *
+ * This is deliberately lax; diff-algorithm.md §3.4.5 already accepts that dropped Symbols live
+ * outside the main IR review surface, so occasional false pairings only affect the
+ * "Drop-rule variation" fold-out section in the Markdown projection.
+ */
+declare function matchStageDroppedWeak(remainingBase: readonly Symbol[], remainingHead: readonly Symbol[]): {
+  matched: SymbolPair[];
+  remainingBase: Symbol[];
+  remainingHead: Symbol[];
+};
+//#endregion
+//#region src/diff.d.ts
+interface DiffInput {
+  baseIR: IR;
+  headIR: IR;
+  /** IR reference metadata (git ref / file path) for provenance. */
+  base: IRRef;
+  head: IRRef;
+  /** Generator record for the diff output. Defaults to `{name: "aburi", version: "0.0.0"}`. */
+  generator?: {
+    name: string;
+    version: string;
+  };
+  /** Optional stage-2 rename table. When null/undefined stage 2 is skipped. */
+  gitRenames?: GitRenameMap | null;
+  /** Passed through to computeSymbolDelta (§5.2.1 line fuzz). */
+  delta?: DeltaOptions;
+}
+/**
+ * Top-level entry: run the 5-stage matcher, classify each pair, produce array deltas,
+ * fold in Component / Dependency diffs, and assemble the `aburi.diff.v1` JSON projection.
+ * The function is pure; write-to-disk is delegated to `writeCanonicalDiff` so callers can
+ * pipe the result through additional steps (Markdown projection, `--fail-on` gate) before
+ * serialisation.
+ */
+declare function buildDiff(input: DiffInput): DiffResult;
+/**
+ * Byte-deterministic serialiser for a DiffResult. Delegates to `@aburi/core`
+ * `serializeCanonical` so the sort order, NFC normalisation, and codepoint key sort are
+ * shared with the IR side.
+ */
+declare function writeCanonicalDiff(diff: DiffResult, options?: SerializeOptions): string;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Coded error class for every @aburi/diff failure. Consumers branch on `code` without
+ * parsing message text. Codes are stable and additions are non-breaking; renames are not.
+ */
+type DiffErrorCode = /** `base.$schema` and `head.$schema` disagree; a diff across schema versions cannot be trusted (§9.1). */"schema-mismatch" /** `config.diff.lineFuzz` was outside the documented [0, 10] range (diff-algorithm.md §5.2.1). */ | "invalid-line-fuzz"
+/**
+ * `baseIR` or `headIR` failed the top-level shape check that `buildDiff` enforces
+ * before touching any Symbol. Missing / non-array `symbols`, `components`,
+ * `dependencies`, or an absent `$schema` — anything that would otherwise crash with a
+ * cryptic `TypeError: undefined is not iterable` deep in a matching stage.
+ */
+| "ir-shape-invalid";
+interface DiffErrorDetail {
+  code: DiffErrorCode;
+  /** Offending value (schema id, fuzz value, etc.) when applicable. */
+  value?: string;
+}
+declare class DiffError extends Error {
+  readonly code: DiffErrorCode;
+  readonly value: string | undefined;
+  constructor(message: string, detail: DiffErrorDetail, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/signature.d.ts
+/**
+ * §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).
+ */
+declare function signatureSimilarity(base: Signature | null | undefined, head: Signature | null | undefined): number;
+//#endregion
+//#region src/similarity.d.ts
+/**
+ * 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.
+ */
+declare function tokenizeName(input: string): string[];
+/**
+ * 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.
+ */
+declare function jaccard(a: readonly string[], b: readonly string[]): number;
+/** name-token Jaccard shortcut used by nameSimilarity and ownerSimilarity call sites. */
+declare function jaccardTokens(a: string, b: string): number;
+/**
+ * §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.
+ */
+declare function nameSimilarity(baseName: string, headName: string): number;
+/**
+ * §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.
+ */
+declare function ownerSimilarity(baseName: string, headName: string): number;
+/** §3.4.1 tail note — used by drop-4.5 weak matcher and threshold lookup. */
+declare function lastSegment(qname: string): string;
+//#endregion
+//#region src/status.d.ts
+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
+ * (同 file、同 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.
+ */
+declare function classifyStatus(base: Symbol, head: Symbol): SymbolStatus;
+/** Direction of a `dropped-toggled` transition (§7.1 SymbolDroppedToggled). */
+type DropDirection = "to-dropped" | "to-kept";
+declare function dropDirection(head: Symbol): DropDirection;
+//#endregion
+export { DEFAULT_LINE_FUZZ, type DeltaOptions, DiffError, type DiffErrorCode, type DiffErrorDetail, type DiffInput, type DropDirection, type GitRenameMap, MAX_LINE_FUZZ, MIN_LINE_FUZZ, type SymbolPair, type SymbolStatus, buildDiff, classifyStatus, computeSymbolDelta, diffComponents, diffDependencies, dropDirection, jaccard, jaccardTokens, lastSegment, matchStageDroppedWeak, matchStageGitRename, matchStageId, matchStageLogicFingerprint, matchStageNameSignature, nameSimilarity, ownerSimilarity, signatureSimilarity, tokenizeName, writeCanonicalDiff };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/components.ts","../src/delta.ts","../src/match.ts","../src/diff.ts","../src/errors.ts","../src/signature.ts","../src/similarity.ts","../src/status.ts"],"mappings":"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"}