@aburi/diff 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { CallEdge, SerializeOptions } from "@aburi/core";
+import { CallEdge, IntegrityViolation, SerializeOptions } from "@aburi/core";
 import { Component, ComponentDiff, Dependency, DependencyDiff, DependencyEndpoint, DependencyUnknown, DiffResult, IR, IRRef, MatchRationale, NotComparedFile, RelativePath, Signature, SkipReason, SliceRecord, Summary, Symbol, SymbolChange, SymbolDelta, SymbolId } from "@aburi/types";
 
 //#region src/components.d.ts
@@ -8,12 +8,18 @@ import { Component, ComponentDiff, Dependency, DependencyDiff, DependencyEndpoin
  * 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.
+ * Component identity is `id`; when a Component is present in both base and head with the same
+ * id, *any* field that differs makes it `changed` — the whole object is compared, not the three
+ * axes the delta names. Those two questions were conflated once: a rename, an added language or
+ * an edited description left the diff reporting `componentsChanged: 0` and an empty `changed[]`,
+ * so the projection layer had no before/after pair to render. The delta booleans stay exactly
+ * what they were — a summary of the three axes a reviewer scans for architectural movement — and
+ * a `changed[]` entry with all three `false` is a well-formed answer meaning "something else
+ * about this component moved", not a bug.
+ *
+ * `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.
  */
 declare function diffComponents(base: readonly Component[], head: readonly Component[]): ComponentDiff;
 /**
@@ -295,16 +301,23 @@ declare function buildDiff(input: DiffInput): DiffResult & {
 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.
+ * `baseIR` or `headIR` is not a Document of the shape `aburi.ir.v1` requires. `buildDiff`
+ * establishes that before touching any Symbol, by running invariant #20
+ * (`checkDocumentShape`): every field the schema requires, at every depth, named by the
+ * record it sits in and the field inside it — so a missing `stats` or `workspace`, a
+ * `symbols[3]` with no `fingerprint`, and a `stats.effectPropagation` with no `sccCount`
+ * all raise this. Anything here would otherwise crash during classification or the delta
+ * with a `TypeError` naming neither the record nor the field.
+ *
+ * A non-empty `$schema` is raised under this code too. That one is `buildDiff`'s own
+ * requirement rather than the schema's — two Documents that both say `""` agree with each
+ * other, so `schema-mismatch` would never fire on the pair.
+ *
+ * Not the semantic invariants: those are statements about a Document whose answer the diff
+ * does not depend on, and refusing an unsorted `symbols[]` would withhold a diff the
+ * matcher can produce.
  */
 | "ir-shape-invalid"
 /**
@@ -327,10 +340,20 @@ interface DiffErrorDetail {
   code: DiffErrorCode;
   /** Offending value (schema id, fuzz value, etc.) when applicable. */
   value?: string;
+  /**
+   * Populated only for `ir-shape-invalid`, one entry per breach of invariant #20.
+   *
+   * The message quotes the first and counts the rest, which is enough to start on and not
+   * enough to finish: a caller fixing a hand-assembled Document needs the others without
+   * running the diff again per field. `CoreErrorDetail.violations` carries the same array
+   * for the same reason, and the two are the same `IntegrityViolation` type.
+   */
+  violations?: readonly IntegrityViolation[];
 }
 declare class DiffError extends Error {
   readonly code: DiffErrorCode;
   readonly value: string | undefined;
+  readonly violations: readonly IntegrityViolation[] | undefined;
   constructor(message: string, detail: DiffErrorDetail, options?: {
     cause?: unknown;
   });
@@ -525,5 +548,4 @@ declare function classifyStatus(base: Symbol, head: Symbol): SymbolStatus;
 type DropDirection = "to-dropped" | "to-kept";
 declare function dropDirection(head: Symbol): DropDirection;
 //#endregion
-export { DEFAULT_LINE_FUZZ, type DeltaOptions, type DependencySideView, DiffError, type DiffErrorCode, type DiffErrorDetail, type DiffInput, type DropDirection, type GitRenameMap, MAX_LINE_FUZZ, MIN_LINE_FUZZ, type SliceInput, type SliceRecordViolation, type SliceViolationKind, type SymbolPair, type SymbolStatus, assertSliceRecordInvariant, buildDiff, classifyStatus, computeSlices, computeSymbolDelta, dependencySideView, diffComponents, diffDependencies, dropDirection, jaccard, jaccardTokens, lastSegment, matchStageDroppedWeak, matchStageGitRename, matchStageId, matchStageLogicFingerprint, matchStageNameSignature, memberSimilarity, nameSimilarity, ownersAreCompatible, signatureSimilarity, sliceAnchor, sliceRecordViolation, tokenizeName, writeCanonicalDiff };
-//# sourceMappingURL=index.d.mts.map
+export { DEFAULT_LINE_FUZZ, type DeltaOptions, type DependencySideView, DiffError, type DiffErrorCode, type DiffErrorDetail, type DiffInput, type DropDirection, type GitRenameMap, MAX_LINE_FUZZ, MIN_LINE_FUZZ, type SliceInput, type SliceRecordViolation, type SliceViolationKind, type SymbolPair, type SymbolStatus, assertSliceRecordInvariant, buildDiff, classifyStatus, computeSlices, computeSymbolDelta, dependencySideView, diffComponents, diffDependencies, dropDirection, jaccard, jaccardTokens, lastSegment, matchStageDroppedWeak, matchStageGitRename, matchStageId, matchStageLogicFingerprint, matchStageNameSignature, memberSimilarity, nameSimilarity, ownersAreCompatible, signatureSimilarity, sliceAnchor, sliceRecordViolation, tokenizeName, writeCanonicalDiff };