trellis 1.0.8 → 2.0.5

package/src/semantic/types.ts

@@ -0,0 +1,175 @@
+/**
+ * Semantic Patching — Type Definitions
+ *
+ * DESIGN.md §4.1–4.4 — Pillar 2: Semantic Patching.
+ * Types for parser adapters, AST entities, parse results,
+ * semantic patches, and structured merge conflicts.
+ */
+
+// ---------------------------------------------------------------------------
+// AST Entities
+// ---------------------------------------------------------------------------
+
+export interface ASTEntity {
+  /** Stable ID derived from structural signature (name + kind + scope path). */
+  id: string;
+  /** Entity type. */
+  kind: ASTEntityKind;
+  /** Human-readable name. */
+  name: string;
+  /** Scope path for disambiguation (e.g. 'MyClass.myMethod'). */
+  scopePath: string;
+  /** Byte range in source for roundtrip (start, end). */
+  span: [number, number];
+  /** Raw source text of this declaration. */
+  rawText: string;
+  /** Structural signature for identity matching (excludes whitespace/comments). */
+  signature: string;
+  /** Child entities (nested functions, inner classes, etc.). */
+  children: ASTEntity[];
+}
+
+export type ASTEntityKind =
+  | 'FunctionDef'
+  | 'ClassDef'
+  | 'InterfaceDef'
+  | 'TypeAlias'
+  | 'EnumDef'
+  | 'VariableDecl'
+  | 'MethodDef'
+  | 'PropertyDef'
+  | 'Constructor'
+  | 'Unknown';
+
+// ---------------------------------------------------------------------------
+// Import / Export Relations
+// ---------------------------------------------------------------------------
+
+export interface ImportRelation {
+  source: string;
+  specifiers: string[];
+  isDefault: boolean;
+  isNamespace: boolean;
+  rawText: string;
+  span: [number, number];
+}
+
+export interface ExportRelation {
+  name: string;
+  isDefault: boolean;
+  source?: string;
+  rawText: string;
+  span: [number, number];
+}
+
+// ---------------------------------------------------------------------------
+// Parse Result
+// ---------------------------------------------------------------------------
+
+export interface ParseResult {
+  /** The file entity this parse belongs to. */
+  fileEntityId: string;
+  /** File path. */
+  filePath: string;
+  /** Language identifier. */
+  language: string;
+  /** Top-level declarations found in the file. */
+  declarations: ASTEntity[];
+  /** Import relationships. */
+  imports: ImportRelation[];
+  /** Export relationships. */
+  exports: ExportRelation[];
+}
+
+// ---------------------------------------------------------------------------
+// Parser Adapter Interface
+// ---------------------------------------------------------------------------
+
+export interface ParserAdapter {
+  /** Languages this adapter supports. */
+  languages: string[];
+  /** Parse a source file into AST-level entities. */
+  parse(content: string, filePath: string): ParseResult;
+  /** Compute semantic patches between two parse results. */
+  diff(oldResult: ParseResult, newResult: ParseResult): SemanticPatch[];
+}
+
+// ---------------------------------------------------------------------------
+// Semantic Patch Types
+// ---------------------------------------------------------------------------
+
+export type SemanticPatch =
+  | { kind: 'symbolAdd'; entity: ASTEntity }
+  | { kind: 'symbolRemove'; entityId: string; entityName: string }
+  | {
+      kind: 'symbolModify';
+      entityId: string;
+      entityName: string;
+      oldSignature: string;
+      newSignature: string;
+      oldRawText: string;
+      newRawText: string;
+    }
+  | {
+      kind: 'symbolRename';
+      entityId: string;
+      oldName: string;
+      newName: string;
+    }
+  | {
+      kind: 'symbolMove';
+      entityId: string;
+      entityName: string;
+      oldFile: string;
+      newFile: string;
+    }
+  | {
+      kind: 'importAdd';
+      fileId: string;
+      source: string;
+      specifiers: string[];
+      rawText: string;
+    }
+  | {
+      kind: 'importRemove';
+      fileId: string;
+      source: string;
+    }
+  | {
+      kind: 'importModify';
+      fileId: string;
+      source: string;
+      oldSpecifiers: string[];
+      newSpecifiers: string[];
+    }
+  | {
+      kind: 'exportAdd';
+      fileId: string;
+      name: string;
+      rawText: string;
+    }
+  | {
+      kind: 'exportRemove';
+      fileId: string;
+      name: string;
+    };
+
+// ---------------------------------------------------------------------------
+// Semantic Merge Conflict
+// ---------------------------------------------------------------------------
+
+export interface SemanticMergeConflict {
+  entityId: string;
+  entityName: string;
+  entityKind: string;
+  filePath: string;
+  ours: SemanticPatch;
+  theirs: SemanticPatch;
+  suggestion?: 'accept-ours' | 'accept-theirs' | 'combine';
+}
+
+export interface SemanticMergeResult {
+  clean: boolean;
+  patches: SemanticPatch[];
+  conflicts: SemanticMergeConflict[];
+}

package/src/sync/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Sync Module — Public Surface
+ *
+ * @module sync
+ *
+ * Re-exports the CRDT {@link reconcile|reconciler}, {@link SyncEngine} for
+ * the have→want→ops→ack protocol, and {@link MemoryTransport} for testing.
+ * Branch policies control whether sync uses linear (fast-forward) or
+ * CRDT (concurrent append) mode.
+ *
+ * @see DESIGN.md §3.5 for the branch concurrency model.
+ */
+
+export type {
+  PeerId,
+  SyncMessage,
+  SyncHaveMessage,
+  SyncWantMessage,
+  SyncOpsMessage,
+  SyncAckMessage,
+  SyncState,
+  BranchPolicy,
+  SyncTransport,
+} from './types.js';
+
+export { reconcile, findForkPoint } from './reconciler.js';
+
+export type { ReconcileResult, ReconcileConflict } from './reconciler.js';
+
+export { SyncEngine } from './sync-engine.js';
+
+export { MemoryTransport } from './memory-transport.js';

package/src/sync/memory-transport.ts

@@ -0,0 +1,66 @@
+/**
+ * In-Memory Sync Transport
+ *
+ * A simple in-memory transport for testing and local multi-engine sync.
+ * Messages are delivered synchronously between connected peers.
+ */
+
+import type { SyncTransport, SyncMessage, PeerId } from './types.js';
+
+// ---------------------------------------------------------------------------
+// In-memory transport
+// ---------------------------------------------------------------------------
+
+export class MemoryTransport implements SyncTransport {
+  private peerId: string;
+  private peerName: string;
+  private handlers: ((message: SyncMessage) => void)[] = [];
+  private connectedPeers: Map<string, MemoryTransport> = new Map();
+
+  constructor(peerId: string, peerName: string = peerId) {
+    this.peerId = peerId;
+    this.peerName = peerName;
+  }
+
+  /**
+   * Connect two transports so they can exchange messages.
+   */
+  static connect(a: MemoryTransport, b: MemoryTransport): void {
+    a.connectedPeers.set(b.peerId, b);
+    b.connectedPeers.set(a.peerId, a);
+  }
+
+  /**
+   * Disconnect two transports.
+   */
+  static disconnect(a: MemoryTransport, b: MemoryTransport): void {
+    a.connectedPeers.delete(b.peerId);
+    b.connectedPeers.delete(a.peerId);
+  }
+
+  async send(peerId: string, message: SyncMessage): Promise<void> {
+    const peer = this.connectedPeers.get(peerId);
+    if (!peer) {
+      throw new Error(`Peer not connected: ${peerId}`);
+    }
+    // Deliver to peer's handlers
+    for (const handler of peer.handlers) {
+      handler(message);
+    }
+  }
+
+  onMessage(handler: (message: SyncMessage) => void): void {
+    this.handlers.push(handler);
+  }
+
+  peers(): PeerId[] {
+    return [...this.connectedPeers.entries()].map(([id, transport]) => ({
+      id,
+      name: transport.peerName,
+    }));
+  }
+
+  getPeerId(): string {
+    return this.peerId;
+  }
+}

package/src/sync/reconciler.ts

@@ -0,0 +1,237 @@
+/**
+ * CRDT Reconciler
+ *
+ * DESIGN.md §10.5 — Merges divergent op streams using causal ordering.
+ * Each device maintains its own causal chain. The reconciler merges
+ * divergent chains by:
+ *   1. Finding the common ancestor (fork point)
+ *   2. Collecting ops unique to each side
+ *   3. Topologically sorting the combined set by causal dependencies
+ *   4. Detecting conflicts using patch commutativity (§4.4)
+ */
+
+import type { VcsOp } from '../vcs/types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ReconcileResult {
+  /** The merged op stream in causal order. */
+  merged: VcsOp[];
+  /** Ops that were only on side A. */
+  uniqueToA: VcsOp[];
+  /** Ops that were only on side B. */
+  uniqueToB: VcsOp[];
+  /** Common ancestor op hash (fork point). */
+  forkPoint: string | null;
+  /** Whether the merge was clean (no causal conflicts). */
+  clean: boolean;
+  /** Conflicting op pairs (both modify same file without commutativity). */
+  conflicts: ReconcileConflict[];
+}
+
+export interface ReconcileConflict {
+  opA: VcsOp;
+  opB: VcsOp;
+  filePath: string;
+  reason: string;
+}
+
+// ---------------------------------------------------------------------------
+// Core reconciliation
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the common ancestor (fork point) of two op streams.
+ * Returns the hash of the last op that appears in both streams.
+ */
+export function findForkPoint(opsA: VcsOp[], opsB: VcsOp[]): string | null {
+  const hashesB = new Set(opsB.map((o) => o.hash));
+  let forkPoint: string | null = null;
+
+  for (const op of opsA) {
+    if (hashesB.has(op.hash)) {
+      forkPoint = op.hash;
+    }
+  }
+
+  return forkPoint;
+}
+
+/**
+ * Reconcile two divergent op streams into a single merged stream.
+ *
+ * Algorithm:
+ *   1. Find the fork point (last common op)
+ *   2. Split each stream into shared prefix + unique suffix
+ *   3. Check for conflicts in the unique portions
+ *   4. Interleave unique ops in causal (timestamp) order
+ */
+export function reconcile(opsA: VcsOp[], opsB: VcsOp[]): ReconcileResult {
+  const forkPoint = findForkPoint(opsA, opsB);
+
+  // Split into shared prefix and unique suffixes
+  const hashesA = new Set(opsA.map((o) => o.hash));
+  const hashesB = new Set(opsB.map((o) => o.hash));
+
+  const shared: VcsOp[] = [];
+  const uniqueToA: VcsOp[] = [];
+  const uniqueToB: VcsOp[] = [];
+
+  for (const op of opsA) {
+    if (hashesB.has(op.hash)) {
+      shared.push(op);
+    } else {
+      uniqueToA.push(op);
+    }
+  }
+
+  for (const op of opsB) {
+    if (!hashesA.has(op.hash)) {
+      uniqueToB.push(op);
+    }
+  }
+
+  // If one side has no unique ops, it's a fast-forward
+  if (uniqueToA.length === 0) {
+    return {
+      merged: [...shared, ...uniqueToB],
+      uniqueToA: [],
+      uniqueToB,
+      forkPoint,
+      clean: true,
+      conflicts: [],
+    };
+  }
+
+  if (uniqueToB.length === 0) {
+    return {
+      merged: [...shared, ...uniqueToA],
+      uniqueToA,
+      uniqueToB: [],
+      forkPoint,
+      clean: true,
+      conflicts: [],
+    };
+  }
+
+  // Both sides diverged — detect conflicts
+  const conflicts = detectConflicts(uniqueToA, uniqueToB);
+
+  // Merge unique ops by timestamp (causal ordering)
+  const interleaved = interleaveByTimestamp(uniqueToA, uniqueToB);
+
+  return {
+    merged: [...shared, ...interleaved],
+    uniqueToA,
+    uniqueToB,
+    forkPoint,
+    clean: conflicts.length === 0,
+    conflicts,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Conflict detection
+// ---------------------------------------------------------------------------
+
+/** VcsOp kinds that represent file-level mutations. */
+const FILE_MUTATION_KINDS = new Set([
+  'vcs:fileAdd',
+  'vcs:fileModify',
+  'vcs:fileDelete',
+  'vcs:fileRename',
+]);
+
+/**
+ * Detect conflicts between two sets of unique ops.
+ * Two ops conflict when they both mutate the same file.
+ */
+function detectConflicts(
+  uniqueA: VcsOp[],
+  uniqueB: VcsOp[],
+): ReconcileConflict[] {
+  const conflicts: ReconcileConflict[] = [];
+
+  // Index A's file mutations
+  const aMutations = new Map<string, VcsOp[]>();
+  for (const op of uniqueA) {
+    if (!FILE_MUTATION_KINDS.has(op.kind) || !op.vcs?.filePath) continue;
+    const path = op.vcs.filePath;
+    if (!aMutations.has(path)) aMutations.set(path, []);
+    aMutations.get(path)!.push(op);
+  }
+
+  // Check B's file mutations against A's
+  for (const op of uniqueB) {
+    if (!FILE_MUTATION_KINDS.has(op.kind) || !op.vcs?.filePath) continue;
+    const path = op.vcs.filePath;
+    const aOps = aMutations.get(path);
+    if (!aOps) continue;
+
+    for (const aOp of aOps) {
+      // Same file modified by both sides
+      if (aOp.kind === 'vcs:fileModify' && op.kind === 'vcs:fileModify') {
+        conflicts.push({
+          opA: aOp,
+          opB: op,
+          filePath: path,
+          reason: `Both sides modified ${path}`,
+        });
+      } else if (
+        (aOp.kind === 'vcs:fileDelete' && op.kind === 'vcs:fileModify') ||
+        (aOp.kind === 'vcs:fileModify' && op.kind === 'vcs:fileDelete')
+      ) {
+        conflicts.push({
+          opA: aOp,
+          opB: op,
+          filePath: path,
+          reason: `Delete/modify conflict on ${path}`,
+        });
+      } else if (aOp.kind === 'vcs:fileAdd' && op.kind === 'vcs:fileAdd') {
+        // Both added same file — conflict if different content
+        if (aOp.vcs?.contentHash !== op.vcs?.contentHash) {
+          conflicts.push({
+            opA: aOp,
+            opB: op,
+            filePath: path,
+            reason: `Both sides added ${path} with different content`,
+          });
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+// ---------------------------------------------------------------------------
+// Interleaving
+// ---------------------------------------------------------------------------
+
+/**
+ * Interleave two op arrays by timestamp, preserving causal ordering
+ * within each array.
+ */
+function interleaveByTimestamp(a: VcsOp[], b: VcsOp[]): VcsOp[] {
+  const result: VcsOp[] = [];
+  let ai = 0;
+  let bi = 0;
+
+  while (ai < a.length && bi < b.length) {
+    const tA = new Date(a[ai].timestamp).getTime();
+    const tB = new Date(b[bi].timestamp).getTime();
+
+    if (tA <= tB) {
+      result.push(a[ai++]);
+    } else {
+      result.push(b[bi++]);
+    }
+  }
+
+  while (ai < a.length) result.push(a[ai++]);
+  while (bi < b.length) result.push(b[bi++]);
+
+  return result;
+}