@dxos/versioning 0.10.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dxos/versioning",
+  "version": "0.10.0",
+  "description": "Checkpoints, draft branches, and 3-way merge for automerge-backed ECHO objects.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "info@dxos.org",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@dxos/echo": "workspace:*",
+    "@dxos/echo-client": "workspace:*",
+    "@dxos/invariant": "workspace:*",
+    "@dxos/schema": "workspace:*",
+    "diff": "catalog:",
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@dxos/typings": "workspace:*",
+    "vitest": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Branch.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+export {
+  Branch,
+  type MakeBranchProps as MakeProps,
+  BranchStatus as Status,
+  makeBranch as make,
+} from './internal/types';
+export {
+  type CreateBranchProps as CreateProps,
+  type MergeResult,
+  createBranch as create,
+  discardBranch as discard,
+  findBranch as find,
+  branchLabel as label,
+  mergeBranch as merge,
+} from './internal/model';

package/src/History.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+export { History } from './internal/types';
+export { type VersionedObject, ensureHistory as ensure } from './internal/model';

package/src/Version.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+export { type MakeVersionProps as MakeProps, Version, makeVersion as make } from './internal/types';
+export {
+  type CreateCheckpointProps as CreateProps,
+  contentAt,
+  createCheckpoint as create,
+  versionLabel as label,
+  restore,
+} from './internal/model';

package/src/diff.test.ts

@@ -0,0 +1,195 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { diffSpans, diffStats, merge3 } from './diff';
+
+describe('diffSpans', () => {
+  test('computes insert/delete/equal spans', ({ expect }) => {
+    const spans = diffSpans('the quick fox', 'the slow fox');
+    expect(spans.map((span) => span.kind)).toEqual(['equal', 'delete', 'insert', 'equal']);
+    expect(spans.find((span) => span.kind === 'insert')?.text).toBe('slow');
+  });
+
+  test('offsets index into the after text', ({ expect }) => {
+    const spans = diffSpans('one three', 'one two three');
+    const insert = spans.find((span) => span.kind === 'insert');
+    if (!insert) {
+      throw new Error('expected an insert span');
+    }
+    expect('one two three'.slice(insert.from, insert.to)).toBe(insert.text);
+  });
+
+  test('handles empty inputs', ({ expect }) => {
+    expect(diffSpans('', '')).toEqual([]);
+    expect(diffSpans('', 'abc')).toEqual([{ kind: 'insert', from: 0, to: 3, text: 'abc' }]);
+    expect(diffSpans('abc', '')).toEqual([{ kind: 'delete', from: 0, to: 0, text: 'abc' }]);
+  });
+});
+
+describe('diffStats', () => {
+  test('counts insertions and deletions', ({ expect }) => {
+    const stats = diffStats(diffSpans('the quick fox', 'the slow fox jumped'));
+    expect(stats.insertions).toBeGreaterThan(0);
+    expect(stats.deletions).toBeGreaterThan(0);
+  });
+});
+
+describe('merge3', () => {
+  test('merges non-overlapping changes from both sides', ({ expect }) => {
+    const base = 'alpha\nbravo\ncharlie\n';
+    const ours = 'alpha edited\nbravo\ncharlie\n';
+    const theirs = 'alpha\nbravo\ncharlie edited\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe('alpha edited\nbravo\ncharlie edited\n');
+  });
+
+  test('applies identical hunks from both sides once', ({ expect }) => {
+    const base = 'alpha\nbravo\n';
+    const both = 'alpha edited\nbravo\n';
+    const result = merge3({ base, ours: both, theirs: both });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe(both);
+  });
+
+  test('marks conflicting hunks, preferring theirs first', ({ expect }) => {
+    const base = 'alpha\nbravo\n';
+    const ours = 'alpha ours\nbravo\n';
+    const theirs = 'alpha theirs\nbravo\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(1);
+    expect(result.text).toContain('<<<<<<<');
+    expect(result.text.indexOf('alpha theirs')).toBeLessThan(result.text.indexOf('alpha ours'));
+  });
+
+  test('returns theirs when ours is unchanged from base', ({ expect }) => {
+    const base = 'alpha\n';
+    const theirs = 'alpha\nbeta\n';
+    expect(merge3({ base, ours: base, theirs }).text).toBe(theirs);
+  });
+
+  test('returns ours when theirs is unchanged from base', ({ expect }) => {
+    const base = 'alpha\n';
+    const ours = 'alpha\nbeta\n';
+    expect(merge3({ base, ours, theirs: base }).text).toBe(ours);
+  });
+
+  test('merges appends at end of file from one side', ({ expect }) => {
+    const base = 'alpha\nbravo\n';
+    const ours = 'alpha\nbravo\n';
+    const theirs = 'alpha\nbravo\ncharlie\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe('alpha\nbravo\ncharlie\n');
+  });
+
+  test('merges from an empty base', ({ expect }) => {
+    const result = merge3({ base: '', ours: 'ours\n', theirs: 'theirs\n' });
+    expect(result.conflicts).toBe(1);
+    expect(result.text).toContain('ours');
+    expect(result.text).toContain('theirs');
+  });
+
+  test('handles deletion on one side and edit elsewhere on the other', ({ expect }) => {
+    const base = 'alpha\nbravo\ncharlie\n';
+    const ours = 'alpha\ncharlie\n';
+    const theirs = 'alpha\nbravo\ncharlie edited\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe('alpha\ncharlie edited\n');
+  });
+
+  test('marks staggered overlapping hunks as a conflict', ({ expect }) => {
+    // Ours replaces base lines [0,2); theirs edits [1,2) — overlapping but different starts.
+    const base = 'alpha\nbravo\ncharlie\n';
+    const ours = 'replaced\ncharlie\n';
+    const theirs = 'alpha\nbravo edited\ncharlie\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(1);
+    expect(result.text).toContain('<<<<<<< branch');
+    expect(result.text).toContain('bravo edited');
+    expect(result.text).toContain('replaced');
+    // Untouched trailing content survives outside the conflict block.
+    expect(result.text.trimEnd().endsWith('charlie')).toBe(true);
+  });
+
+  test('staggered conflict regions include each side of the union', ({ expect }) => {
+    // Theirs replaces [0,3); ours edits [2,3) only — theirs' side must still carry its full block.
+    const base = 'one\ntwo\nthree\nfour\n';
+    const ours = 'one\ntwo\nthree edited\nfour\n';
+    const theirs = 'rewritten\nfour\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(1);
+    expect(result.text).toContain('rewritten');
+    expect(result.text).toContain('three edited');
+    // Ours' side of the union keeps the base lines it left unchanged.
+    const oursSection = result.text.slice(result.text.indexOf('======='), result.text.indexOf('>>>>>>>'));
+    expect(oursSection).toContain('one');
+    expect(oursSection).toContain('two');
+  });
+
+  test('adjacent hunks do not conflict', ({ expect }) => {
+    const base = 'alpha\nbravo\n';
+    const ours = 'alpha edited\nbravo\n';
+    const theirs = 'alpha\nbravo edited\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe('alpha edited\nbravo edited\n');
+  });
+
+  test('one broad hunk overlapping multiple hunks forms a single conflict region', ({ expect }) => {
+    // Ours replaces base lines [0,5); theirs edits [1,2) and [3,4) separately.
+    const base = 'l0\nl1\nl2\nl3\nl4\ntail\n';
+    const ours = 'REPLACED\ntail\n';
+    const theirs = 'l0\nl1 edited\nl2\nl3 edited\nl4\ntail\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(1);
+    // Theirs side of the union carries BOTH edits plus the untouched base lines between them.
+    const theirsSection = result.text.slice(result.text.indexOf('<<<<<<<'), result.text.indexOf('======='));
+    expect(theirsSection).toContain('l1 edited');
+    expect(theirsSection).toContain('l3 edited');
+    expect(theirsSection).toContain('l2');
+    // No hunk is applied twice and trailing content stays outside the conflict.
+    expect(result.text.match(/l1 edited/g)).toHaveLength(1);
+    expect(result.text.match(/l3 edited/g)).toHaveLength(1);
+    expect(result.text.trimEnd().endsWith('tail')).toBe(true);
+  });
+
+  test('inserts a blank line from one side', ({ expect }) => {
+    const base = 'a\nb\n';
+    const ours = 'a\nb\nc\n';
+    const theirs = 'a\n\nb\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe('a\n\nb\nc\n');
+  });
+
+  test('deletes a blank line from one side', ({ expect }) => {
+    const base = 'a\n\nb\n';
+    const ours = 'a\n\nb\nc\n';
+    const theirs = 'a\nb\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe('a\nb\nc\n');
+  });
+
+  test('replaces a blank line from one side', ({ expect }) => {
+    const base = 'a\n\nb\n';
+    const ours = 'a\n\nb\nc\n';
+    const theirs = 'a\nmiddle\nb\n';
+    const result = merge3({ base, ours, theirs });
+    expect(result.conflicts).toBe(0);
+    expect(result.text).toBe('a\nmiddle\nb\nc\n');
+  });
+
+  test('preserves content without trailing newline', ({ expect }) => {
+    const base = 'alpha';
+    const ours = 'alpha';
+    const theirs = 'alpha bravo';
+    const result = merge3({ base, ours, theirs });
+    expect(result.text).toBe('alpha bravo');
+  });
+});

package/src/diff.ts

@@ -0,0 +1,225 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { diffLines, diffWordsWithSpace } from 'diff';
+
+/**
+ * Shared diff unit consumed by all diff renderings (inline, side-by-side, gutter).
+ * Offsets index into the AFTER text; deletions are zero-width and carry the offset where
+ * the removed text used to be, so widgets can render the removed content in place.
+ */
+export type DiffSpan = {
+  kind: 'equal' | 'insert' | 'delete';
+  from: number;
+  to: number;
+  text: string;
+};
+
+/** Computes word-level {@link DiffSpan}s between two texts, offset into the after text. */
+export const diffSpans = (before: string, after: string): DiffSpan[] => {
+  const spans: DiffSpan[] = [];
+  let offset = 0;
+  for (const change of diffWordsWithSpace(before, after)) {
+    const kind = change.added ? 'insert' : change.removed ? 'delete' : 'equal';
+    const length = kind === 'delete' ? 0 : change.value.length;
+    spans.push({ kind, from: offset, to: offset + length, text: change.value });
+    offset += length;
+  }
+  return spans;
+};
+
+export type DiffStats = { insertions: number; deletions: number };
+
+/** Character counts, used for the `+N −M` branch summaries. */
+export const diffStats = (spans: DiffSpan[]): DiffStats =>
+  spans.reduce(
+    (stats, span) => {
+      if (span.kind === 'insert') {
+        stats.insertions += span.text.length;
+      } else if (span.kind === 'delete') {
+        stats.deletions += span.text.length;
+      }
+      return stats;
+    },
+    { insertions: 0, deletions: 0 },
+  );
+
+export type Merge3Props = { base: string; ours: string; theirs: string };
+export type Merge3Result = { text: string; conflicts: number };
+
+/**
+ * Line-based 3-way merge. Non-overlapping hunks apply automatically; overlapping hunks
+ * produce git-style conflict markers with the branch (theirs) side first, since the merge
+ * flow is review-then-accept and the branch content is what was just reviewed.
+ */
+export const merge3 = ({ base, ours, theirs }: Merge3Props): Merge3Result => {
+  if (ours === base) {
+    return { text: theirs, conflicts: 0 };
+  }
+  if (theirs === base || ours === theirs) {
+    return { text: ours, conflicts: 0 };
+  }
+
+  const baseLines = splitLines(base);
+  const oursHunks = lineHunks(baseLines, splitLines(ours));
+  const theirsHunks = lineHunks(baseLines, splitLines(theirs));
+
+  const out: string[] = [];
+  let conflicts = 0;
+  let baseIndex = 0;
+  let oursCursor = 0;
+  let theirsCursor = 0;
+
+  while (baseIndex < baseLines.length || oursCursor < oursHunks.length || theirsCursor < theirsHunks.length) {
+    const oursHunk = oursHunks[oursCursor];
+    const theirsHunk = theirsHunks[theirsCursor];
+    const nextOurs = oursHunk?.baseStart ?? Infinity;
+    const nextTheirs = theirsHunk?.baseStart ?? Infinity;
+    const next = Math.min(nextOurs, nextTheirs);
+
+    // Copy unchanged base lines up to the next hunk.
+    while (baseIndex < Math.min(next, baseLines.length)) {
+      out.push(baseLines[baseIndex]);
+      baseIndex += 1;
+    }
+    if (next === Infinity) {
+      break;
+    }
+
+    const oursActive = oursHunk !== undefined && oursHunk.baseStart === next;
+    const theirsActive = theirsHunk !== undefined && theirsHunk.baseStart === next;
+    const identical =
+      oursActive &&
+      theirsActive &&
+      sameLines(oursHunk.lines, theirsHunk.lines) &&
+      oursHunk.baseLength === theirsHunk.baseLength;
+    // Hunks conflict when their consumed base intervals overlap — same start, or a staggered
+    // hunk beginning inside the interval the active hunk consumes (e.g. [0,2) vs [1,2)).
+    const overlap =
+      !identical &&
+      oursHunk !== undefined &&
+      theirsHunk !== undefined &&
+      (nextOurs === nextTheirs ||
+        (oursActive && nextTheirs < hunkEnd(oursHunk)) ||
+        (theirsActive && nextOurs < hunkEnd(theirsHunk)));
+
+    if (overlap) {
+      // The conflict region is the connected union of every intersecting hunk on both sides —
+      // a broad hunk can overlap several smaller ones, all of which must be consumed together.
+      const oursRegion = [oursHunk];
+      const theirsRegion = [theirsHunk];
+      oursCursor += 1;
+      theirsCursor += 1;
+      let unionEnd = Math.max(hunkEnd(oursHunk), hunkEnd(theirsHunk));
+      let expanded = true;
+      while (expanded) {
+        expanded = false;
+        while (oursCursor < oursHunks.length && oursHunks[oursCursor].baseStart < unionEnd) {
+          const hunk = oursHunks[oursCursor];
+          oursRegion.push(hunk);
+          unionEnd = Math.max(unionEnd, hunkEnd(hunk));
+          oursCursor += 1;
+          expanded = true;
+        }
+        while (theirsCursor < theirsHunks.length && theirsHunks[theirsCursor].baseStart < unionEnd) {
+          const hunk = theirsHunks[theirsCursor];
+          theirsRegion.push(hunk);
+          unionEnd = Math.max(unionEnd, hunkEnd(hunk));
+          theirsCursor += 1;
+          expanded = true;
+        }
+      }
+
+      out.push(
+        '<<<<<<< branch',
+        ...sideContent(baseLines, theirsRegion, next, unionEnd),
+        '=======',
+        ...sideContent(baseLines, oursRegion, next, unionEnd),
+        '>>>>>>> current',
+      );
+      conflicts += 1;
+      baseIndex = unionEnd;
+    } else if (identical) {
+      out.push(...oursHunk.lines);
+      baseIndex = next + oursHunk.baseLength;
+      oursCursor += 1;
+      theirsCursor += 1;
+    } else if (oursActive) {
+      out.push(...oursHunk.lines);
+      baseIndex = next + oursHunk.baseLength;
+      oursCursor += 1;
+    } else if (theirsHunk !== undefined) {
+      out.push(...theirsHunk.lines);
+      baseIndex = next + theirsHunk.baseLength;
+      theirsCursor += 1;
+    }
+  }
+
+  return { text: joinLines(out, [base, ours, theirs]), conflicts };
+};
+
+type Hunk = { baseStart: number; baseLength: number; lines: string[] };
+
+const hunkEnd = (hunk: Hunk) => hunk.baseStart + hunk.baseLength;
+
+/** One side's content for a conflict region: its hunks plus the union's base lines they leave unchanged. */
+const sideContent = (baseLines: string[], hunks: Hunk[], unionStart: number, unionEnd: number): string[] => {
+  const out: string[] = [];
+  let position = unionStart;
+  for (const hunk of hunks) {
+    out.push(...baseLines.slice(position, hunk.baseStart), ...hunk.lines);
+    position = Math.max(position, hunkEnd(hunk));
+  }
+  out.push(...baseLines.slice(position, unionEnd));
+  return out;
+};
+
+/** Convert jsdiff line changes into base-anchored replacement hunks. */
+const lineHunks = (baseLines: string[], sideLines: string[]): Hunk[] => {
+  const hunks: Hunk[] = [];
+  let baseIndex = 0;
+  let pending: Hunk | undefined;
+  for (const change of diffLines(joinForDiff(baseLines), joinForDiff(sideLines))) {
+    const lines = chunkLines(change.value);
+    if (change.added) {
+      pending = pending ?? { baseStart: baseIndex, baseLength: 0, lines: [] };
+      pending.lines.push(...lines);
+    } else if (change.removed) {
+      pending = pending ?? { baseStart: baseIndex, baseLength: 0, lines: [] };
+      pending.baseLength += lines.length;
+      baseIndex += lines.length;
+    } else {
+      if (pending) {
+        hunks.push(pending);
+        pending = undefined;
+      }
+      baseIndex += lines.length;
+    }
+  }
+  if (pending) {
+    hunks.push(pending);
+  }
+  return hunks;
+};
+
+const sameLines = (a: string[], b: string[]) => a.length === b.length && a.every((line, index) => line === b[index]);
+
+const splitLines = (text: string): string[] => (text === '' ? [] : stripTrailingNewline(text).split('\n'));
+
+// Unlike whole-document splitting, a diff chunk is never empty — a chunk of '\n' is one blank
+// line (jsdiff attaches the terminator to its line), so no empty-string special case applies.
+const chunkLines = (value: string): string[] => stripTrailingNewline(value).split('\n');
+
+const stripTrailingNewline = (text: string) => (text.endsWith('\n') ? text.slice(0, -1) : text);
+
+// diffLines needs a trailing newline so the last line compares as a whole line.
+const joinForDiff = (lines: string[]) => (lines.length === 0 ? '' : `${lines.join('\n')}\n`);
+
+const joinLines = (lines: string[], inputs: string[]) => {
+  const text = lines.join('\n');
+  // Preserve a trailing newline when every non-empty input has one.
+  const nonEmpty = inputs.filter((input) => input.length > 0);
+  const trailing = nonEmpty.length > 0 && nonEmpty.every((input) => input.endsWith('\n'));
+  return trailing && text.length > 0 ? `${text}\n` : text;
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as Branch from './Branch';
+export * as History from './History';
+export * as Version from './Version';
+export * from './diff';

package/src/internal/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './model';
+export * from './types';