@openpresentation/opf 0.11.4 → 0.12.0

package/dist/diff.d.ts

@@ -0,0 +1,145 @@
+import { JsonPatchOperation } from './patch.js';
+
+type MatchedBy = "id" | "equal" | "similar" | "position";
+interface MatchPair {
+    /** Index in A. */
+    a: number;
+    /** Index in B. */
+    b: number;
+    by: MatchedBy;
+    /** Similarity score for `similar` pairs. */
+    similarity?: number;
+}
+interface ArrayMatch {
+    /** Pairs sorted by `a`. */
+    pairs: MatchPair[];
+    /** A indexes with no counterpart, ascending. */
+    removed: number[];
+    /** B indexes with no counterpart, ascending. */
+    added: number[];
+    /** `a` indexes of pairs that are out of order relative to the longest order-preserving chain. */
+    moved: Set<number>;
+}
+interface MatchOptions {
+    /** Minimum similarity (0..1) to treat two unequal elements as the same. Default 0.5. */
+    threshold?: number;
+}
+/** Content similarity in [0, 1]: matching scalar leaves at the same path, with partial credit for similar text. */
+declare function similarity(a: unknown, b: unknown): number;
+/** Match the elements of two arrays. Pure and deterministic. */
+declare function matchArrays(a: readonly unknown[], b: readonly unknown[], options?: MatchOptions): ArrayMatch;
+
+type MergeConflictKind = "modify-modify" | "modify-delete" | "delete-modify" | "add-add" | "move-move";
+interface MergeConflict {
+    kind: MergeConflictKind;
+    /** JSON Pointer in the merged document where the resolved value lives (or would live if it was deleted). */
+    path: string;
+    /** The value in the base document, when it had one. */
+    base?: unknown;
+    /** Our value; absent when we deleted it. */
+    ours?: unknown;
+    /** Their value; absent when they deleted it. */
+    theirs?: unknown;
+    /** Which side deleted the value, for `modify-delete` and `delete-modify`. */
+    deletedBy?: "ours" | "theirs";
+    /** Which side the merged document took. */
+    resolution: "ours" | "theirs";
+    /** The slide the conflict is inside, when it is inside one. */
+    slide?: {
+        id?: string;
+        title?: string;
+        index: number;
+    };
+    message: string;
+}
+interface MergeOptions extends MatchOptions {
+    /** Which side the merged document takes where the sides collide. Default "ours". Conflicts are reported either way. */
+    prefer?: "ours" | "theirs";
+}
+interface MergeResult {
+    /** The merged document. Conflicting places hold the preferred side's value. */
+    merged: unknown;
+    conflicts: MergeConflict[];
+    /** True when there are no conflicts. */
+    clean: boolean;
+    /** How many places changed on only one side (applied automatically) or identically on both. */
+    applied: {
+        ours: number;
+        theirs: number;
+        both: number;
+    };
+}
+/**
+ * Three-way merge of OPF documents. Never discards a side silently: every
+ * collision is listed in `conflicts` with the base, our value and their value.
+ * The merged document is not validated; callers validate it before saving.
+ */
+declare function mergePresentations(base: unknown, ours: unknown, theirs: unknown, options?: MergeOptions): MergeResult;
+
+type DiffChangeType = "added" | "removed" | "changed" | "moved";
+/** What kind of thing changed. */
+type DiffCategory = "slide" | "block" | "field" | "design" | "metadata" | "assets" | "catalogs" | "variables" | "narrative" | "extensions";
+interface DiffSlideRef {
+    id?: string;
+    title?: string;
+    /** Index in the first document, when the slide exists there. */
+    aIndex?: number;
+    /** Index in the second document, when the slide exists there. */
+    bIndex?: number;
+}
+interface DiffChange {
+    type: DiffChangeType;
+    category: DiffCategory;
+    /** JSON Pointer in document A (absent for additions). */
+    aPath?: string;
+    /** JSON Pointer in document B (absent for removals). */
+    bPath?: string;
+    /** Value in A (removed and changed). */
+    before?: unknown;
+    /** Value in B (added and changed). */
+    after?: unknown;
+    /** The slide the change belongs to, for slide-scoped changes. */
+    slide?: DiffSlideRef;
+}
+interface SlideMatchInfo extends DiffSlideRef {
+    /** How the slide was identified across the documents; absent for added/removed slides. */
+    matchedBy?: MatchedBy;
+    similarity?: number;
+    status: "unchanged" | "modified" | "moved" | "moved-modified" | "added" | "removed";
+}
+interface DiffSummary {
+    total: number;
+    byCategory: Partial<Record<DiffCategory, number>>;
+    byType: Partial<Record<DiffChangeType, number>>;
+    slides: {
+        added: number;
+        removed: number;
+        moved: number;
+        modified: number;
+        unchanged: number;
+    };
+}
+interface PresentationDiff {
+    equal: boolean;
+    changes: DiffChange[];
+    /** RFC 6902 patch: `applyPatch(a, patch)` deep-equals `b`. */
+    patch: JsonPatchOperation[];
+    slides: SlideMatchInfo[];
+    summary: DiffSummary;
+}
+type DiffOptions = MatchOptions;
+/** The category a change at `tokens` belongs to. */
+declare function categoryOf(tokens: readonly string[]): DiffCategory;
+/**
+ * Diff two OPF documents. Slides are matched by `id`, then by identical
+ * content, then by content similarity (`threshold`, default 0.5); the same
+ * rule matches blocks, list items and every other array element. The result
+ * lists categorised changes and a JSON Patch from `a` to `b`.
+ */
+declare function diffPresentations(a: unknown, b: unknown, options?: DiffOptions): PresentationDiff;
+/** A short, single-line description of a value for reports. */
+declare function describeValue(value: unknown): string;
+/** Render a diff as a plain-text report (no colour, stable ordering). */
+declare function formatDiffReport(diff: PresentationDiff): string;
+
+export { type ArrayMatch, type DiffCategory, type DiffChange, type DiffChangeType, type DiffOptions, type DiffSlideRef, type DiffSummary, type MatchOptions, type MatchPair, type MatchedBy, type MergeConflict, type MergeConflictKind, type MergeOptions, type MergeResult, type PresentationDiff, type SlideMatchInfo, categoryOf, describeValue, diffPresentations, formatDiffReport, matchArrays, mergePresentations, similarity };