isomorphic-jj 1.4.3 → 1.7.0

package/src/core/background-ops.js

@@ -8,8 +8,8 @@ import { JJError } from '../utils/errors.js';
 
 export class BackgroundOps {
   /**
-   * @param {Object} jj - JJ instance
-   * @param {Object} fs - Filesystem implementation
+   * @param {any} jj - JJ instance
+   * @param {any} fs - Filesystem implementation
    * @param {string} dir - Repository directory
    */
   constructor(jj, fs, dir) {
@@ -63,7 +63,7 @@ export class BackgroundOps {
    *
    * @param {string} path - Path to watch
    * @param {Function} callback - Callback function(event, filename)
-   * @returns {string} Watcher ID
+   * @returns {Promise<string>} Watcher ID
    */
   async watch(path, callback) {
     if (!this.running) {
@@ -81,13 +81,15 @@ export class BackgroundOps {
     }
 
     // Browser: use FileSystem Access API observeDirectory if available
-    if (typeof FileSystemObserver !== 'undefined') {
+    if (typeof (/** @type {any} */ (globalThis).FileSystemObserver) !== 'undefined') {
       const watcherId = `watcher-${this.watchers.size}`;
-      const observer = new FileSystemObserver(async (records) => {
-        for (const record of records) {
-          callback(record.type, record.relativePathComponents.join('/'));
+      const observer = new /** @type {any} */ (globalThis).FileSystemObserver(
+        async (/** @type {any} */ records) => {
+          for (const record of records) {
+            callback(record.type, record.relativePathComponents.join('/'));
+          }
         }
-      });
+      );
 
       // Note: This API is experimental and may not be available
       this.watchers.set(watcherId, observer);
@@ -130,11 +132,12 @@ export class BackgroundOps {
    * @param {Function} operation - Async operation to run
    * @param {Object} opts - Options
    * @param {string} [opts.description] - Operation description
-   * @returns {Promise<Object>} Operation result
+   * @returns {Promise<{id: string, promise: Promise<any>}>} Operation handle
    */
   async queue(operation, opts = {}) {
     const operationId = `op-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
 
+    /** @type {Record<string, any>} */
     const op = {
       id: operationId,
       description: opts.description || 'background operation',
@@ -190,10 +193,10 @@ export class BackgroundOps {
     let ops = Array.from(this.operations.values());
 
     if (opts.status) {
-      ops = ops.filter(op => op.status === opts.status);
+      ops = ops.filter((op) => op.status === opts.status);
     }
 
-    return ops.map(op => ({
+    return ops.map((op) => ({
       id: op.id,
       description: op.description,
       status: op.status,
@@ -212,42 +215,56 @@ export class BackgroundOps {
   async enableAutoSnapshot(opts = {}) {
     const debounceMs = opts.debounceMs || 1000;
 
-    const watcherId = await this.watch(this.dir, (event, filename) => {
-      if (filename && filename.startsWith('.jj/')) {
-        return; // Ignore .jj directory changes
-      }
+    const watcherId = await this.watch(
+      this.dir,
+      (/** @type {any} */ event, /** @type {any} */ filename) => {
+        if (filename && filename.startsWith('.jj/')) {
+          return; // Ignore .jj directory changes
+        }
 
-      if (filename && filename.startsWith('.git/')) {
-        return; // Ignore .git directory changes
-      }
+        if (filename && filename.startsWith('.git/')) {
+          return; // Ignore .git directory changes
+        }
 
-      // Debounce: wait for changes to settle
-      const existingTimer = this.timers.get(watcherId);
-      if (existingTimer) {
-        clearTimeout(existingTimer);
-      }
+        // Debounce: wait for changes to settle
+        const existingTimer = this.timers.get(watcherId);
+        if (existingTimer) {
+          clearTimeout(existingTimer);
+        }
 
-      const timer = setTimeout(async () => {
-        try {
-          // Create automatic snapshot
-          await this.queue(async () => {
-            await this.jj.describe({ message: `Auto-snapshot: ${filename || 'multiple files'} changed` });
-          }, { description: 'auto-snapshot' });
-        } catch (error) {
-          console.error('Auto-snapshot failed:', error);
-        } finally {
-          // Clean up timer reference
-          this.timers.delete(watcherId);
+        const timer = setTimeout(async () => {
+          try {
+            // Create automatic snapshot. queue() resolves as soon as the
+            // operation is *enqueued*, not once it finishes — it returns a
+            // `{ id, promise }` handle. Awaiting only queue() (and not the
+            // returned `promise`) would let a later describe() rejection
+            // become an unhandled promise rejection instead of landing in
+            // this catch block, so the handle's promise must be awaited too.
+            const { promise } = await this.queue(
+              async () => {
+                await this.jj.describe({
+                  message: `Auto-snapshot: ${filename || 'multiple files'} changed`,
+                });
+              },
+              { description: 'auto-snapshot' }
+            );
+            await promise;
+          } catch (error) {
+            console.error('Auto-snapshot failed:', error);
+          } finally {
+            // Clean up timer reference
+            this.timers.delete(watcherId);
+          }
+        }, debounceMs);
+
+        // Use unref() to allow process to exit if this is the only pending timer
+        if (timer.unref) {
+          timer.unref();
         }
-      }, debounceMs);
 
-      // Use unref() to allow process to exit if this is the only pending timer
-      if (timer.unref) {
-        timer.unref();
+        this.timers.set(watcherId, timer);
       }
-
-      this.timers.set(watcherId, timer);
-    });
+    );
 
     return watcherId;
   }

package/src/core/bookmark-store.js

@@ -1,6 +1,6 @@
 /**
  * BookmarkStore - Manages local and remote bookmarks
- * 
+ *
  * Bookmarks are named pointers to changes, similar to Git branches.
  */
 
@@ -15,6 +15,7 @@ export class BookmarkStore {
     this.storage = storage;
     this.local = new Map();
     this.remote = new Map(); // remote → (bookmark → changeId)
+    /** @type {Record<string, any>} */
     this.tracking = {}; // bookmark → { remote, ref } tracking info (v0.35.0)
   }
 
@@ -79,11 +80,13 @@ export class BookmarkStore {
    * Save bookmarks to storage
    */
   async save() {
+    /** @type {Record<string, any>} */
     const local = {};
     for (const [name, target] of this.local.entries()) {
       local[name] = target;
     }
 
+    /** @type {Record<string, any>} */
     const remote = {};
     for (const [remoteName, bookmarks] of this.remote.entries()) {
       remote[remoteName] = {};
@@ -102,7 +105,7 @@ export class BookmarkStore {
 
   /**
    * Set a local bookmark
-   * 
+   *
    * @param {string} name - Bookmark name
    * @param {string} target - Change ID to point to
    */
@@ -123,7 +126,7 @@ export class BookmarkStore {
 
   /**
    * Move an existing local bookmark
-   * 
+   *
    * @param {string} name - Bookmark name
    * @param {string} target - New change ID to point to
    */
@@ -144,7 +147,7 @@ export class BookmarkStore {
 
   /**
    * Delete a local bookmark
-   * 
+   *
    * @param {string} name - Bookmark name
    */
   async delete(name) {
@@ -162,7 +165,7 @@ export class BookmarkStore {
 
   /**
    * Get bookmark target
-   * 
+   *
    * @param {string} name - Bookmark name
    * @returns {Promise<string|null>} Change ID or null if not found
    */
@@ -172,7 +175,7 @@ export class BookmarkStore {
 
   /**
    * Set a remote bookmark
-   * 
+   *
    * @param {string} remoteName - Remote name
    * @param {string} name - Bookmark name
    * @param {string} target - Change ID to point to
@@ -191,7 +194,7 @@ export class BookmarkStore {
 
   /**
    * Get remote bookmark target
-   * 
+   *
    * @param {string} remoteName - Remote name
    * @param {string} name - Bookmark name
    * @returns {Promise<string|null>} Change ID or null if not found
@@ -204,13 +207,14 @@ export class BookmarkStore {
   /**
    * List all bookmarks (local and remote)
    *
-   * @returns {Promise<Array>} Array of bookmark objects
+   * @returns {Promise<Array<any>>} Array of bookmark objects
    */
   async list() {
     const result = [];
 
     // Add local bookmarks with tracking info (v0.35.0)
     for (const [name, target] of this.local.entries()) {
+      /** @type {Record<string, any>} */
       const bookmark = {
         name,
         changeId: target,

package/src/core/change-graph.js

@@ -1,6 +1,6 @@
 /**
  * ChangeGraph - Manages the change graph with stable change IDs
- * 
+ *
  * Tracks changes, their relationships (parents/children), and evolution (amends/rewrites).
  */
 
@@ -62,6 +62,7 @@ export class ChangeGraph {
    * Save graph to storage
    */
   async save() {
+    /** @type {Record<string, any>} */
     const changes = {};
     for (const [changeId, change] of this.nodes.entries()) {
       changes[changeId] = change;
@@ -75,8 +76,8 @@ export class ChangeGraph {
 
   /**
    * Add a change to the graph
-   * 
-   * @param {Object} change - Change object
+   *
+   * @param {Record<string, any>} change - Change object
    */
   async addChange(change) {
     validateChangeId(change.changeId);
@@ -96,9 +97,9 @@ export class ChangeGraph {
 
   /**
    * Get a change by ID
-   * 
+   *
    * @param {string} changeId - Change ID
-   * @returns {Object|null} Change object or null if not found
+   * @returns {Promise<Record<string, any>|null>} Change object or null if not found
    */
   async getChange(changeId) {
     validateChangeId(changeId);
@@ -107,8 +108,8 @@ export class ChangeGraph {
 
   /**
    * Get all changes
-   * 
-   * @returns {Array} Array of all changes
+   *
+   * @returns {Array<any>} Array of all changes
    */
   getAll() {
     return Array.from(this.nodes.values());
@@ -116,7 +117,7 @@ export class ChangeGraph {
 
   /**
    * Find change by commit ID
-   * 
+   *
    * @param {string} commitId - Git commit SHA-1
    * @returns {string|null} Change ID or null if not found
    */
@@ -126,8 +127,8 @@ export class ChangeGraph {
 
   /**
    * Get parent change IDs
-   * 
-   * @param {string} changeId - Change ID
+   *
+   * @param {any} changeId - Change ID
    * @returns {Array<string>} Array of parent change IDs
    */
   getParents(changeId) {
@@ -137,27 +138,27 @@ export class ChangeGraph {
 
   /**
    * Get child change IDs
-   * 
+   *
    * @param {string} changeId - Change ID
    * @returns {Array<string>} Array of child change IDs
    */
   getChildren(changeId) {
     const children = [];
-    
+
     for (const change of this.nodes.values()) {
       if (change.parents.includes(changeId)) {
         children.push(change.changeId);
       }
     }
-    
+
     return children;
   }
 
   /**
    * Evolve a change (update commitId, track predecessor)
-   * 
+   *
    * Used when amending or rewriting a change.
-   * 
+   *
    * @param {string} changeId - Change ID
    * @param {string} newCommitId - New commit SHA-1
    */
@@ -188,8 +189,8 @@ export class ChangeGraph {
 
   /**
    * Update a change (modify in place)
-   * 
-   * @param {Object} change - Updated change object
+   *
+   * @param {Record<string, any>} change - Updated change object
    */
   async updateChange(change) {
     validateChangeId(change.changeId);
@@ -213,20 +214,19 @@ export class ChangeGraph {
    */
   getAncestors(changeId) {
     const ancestors = [];
-    const visited = new Set();
+    // `visited` also doubles as "already enqueued" — mark a node the moment
+    // it's scheduled (not when dequeued), so a change reachable via two paths
+    // in a diamond-shaped history (a<-b, a<-c, b&c<-d) is only added once.
+    const visited = new Set([changeId]);
     const queue = [changeId];
 
     while (queue.length > 0) {
       const current = queue.shift();
 
-      if (visited.has(current)) {
-        continue;
-      }
-      visited.add(current);
-
       const parents = this.getParents(current);
       for (const parent of parents) {
         if (!visited.has(parent)) {
+          visited.add(parent);
           ancestors.push(parent);
           queue.push(parent);
         }
@@ -239,12 +239,8 @@ export class ChangeGraph {
   /**
    * Create a change with default values (helper for tests)
    *
-   * @param {Object} params - Change parameters
-   * @param {string[]} [params.parents] - Parent change IDs
-   * @param {string} [params.description] - Change description
-   * @param {Object} [params.fileSnapshot] - File snapshot
-   * @param {Object} [params.conflicts] - Conflict markers
-   * @returns {Promise<Object>} Created change object
+   * @param {Record<string, any>} [params] - Change parameters
+   * @returns {Promise<Record<string, any>>} Created change object
    */
   async createChange(params = {}) {
     const crypto = await import('crypto');
@@ -253,6 +249,7 @@ export class ChangeGraph {
     const tree = params.tree || crypto.randomBytes(20).toString('hex');
     const timestamp = params.timestamp || new Date().toISOString();
 
+    /** @type {Record<string, any>} */
     const change = {
       changeId,
       parents: params.parents || [],

package/src/core/conflict-model.js

@@ -18,20 +18,26 @@ import { generateId } from '../utils/id-generation.js';
  * Conflict types supported by JJ
  */
 export const ConflictType = {
-  CONTENT: 'content',        // File content conflicts (3-way merge)
-  PATH: 'path',              // Path/rename conflicts
-  DELETE_MODIFY: 'delete-modify',  // File deleted in one side, modified in other
-  MODIFY_DELETE: 'modify-delete',  // File modified in one side, deleted in other
-  ADD_ADD: 'add-add',        // Same path added in both sides
+  CONTENT: 'content', // File content conflicts (3-way merge)
+  PATH: 'path', // Path/rename conflicts
+  DELETE_MODIFY: 'delete-modify', // File deleted in one side, modified in other
+  MODIFY_DELETE: 'modify-delete', // File modified in one side, deleted in other
+  ADD_ADD: 'add-add', // Same path added in both sides
 };
 
 /**
  * ConflictModel manages conflict detection, storage, and resolution
  */
 export class ConflictModel {
+  /**
+   * @param {any} storage
+   * @param {any} fs
+   * @param {any} [mergeDriverRegistry]
+   */
   constructor(storage, fs, mergeDriverRegistry = null) {
     this.storage = storage;
     this.fs = fs;
+    /** @type {any} */
     this.mergeDriverRegistry = mergeDriverRegistry; // v0.5: merge drivers
     this.conflicts = new Map(); // conflictId -> Conflict
     this.fileConflicts = new Map(); // path -> conflictId
@@ -81,23 +87,29 @@ export class ConflictModel {
    * @param {string} opts.baseChange - Common ancestor change
    * @param {string} opts.leftChange - Left side change
    * @param {string} opts.rightChange - Right side change
-   * @param {Map} opts.baseFiles - Files in base
-   * @param {Map} opts.leftFiles - Files in left
-   * @param {Map} opts.rightFiles - Files in right
+   * @param {Map<any, any>} opts.baseFiles - Files in base
+   * @param {Map<any, any>} opts.leftFiles - Files in left
+   * @param {Map<any, any>} opts.rightFiles - Files in right
    * @param {Object} opts.drivers - Custom merge drivers (v0.5)
    * @param {string} opts.workingCopyDir - Working copy directory for file writes (v0.5)
-   * @returns {Array<Conflict>} Detected conflicts
+   * @returns {Promise<any[]>} Detected conflicts
    */
   async detectConflicts(opts) {
-    const { baseFiles, leftFiles, rightFiles, drivers = {}, workingCopyDir, baseChange, leftChange, rightChange } = opts;
+    const {
+      baseFiles,
+      leftFiles,
+      rightFiles,
+      drivers = {},
+      workingCopyDir,
+      baseChange,
+      leftChange,
+      rightChange,
+    } = opts;
+    /** @type {any[]} */
     const conflicts = [];
 
     // Get all unique paths across all versions
-    const allPaths = new Set([
-      ...baseFiles.keys(),
-      ...leftFiles.keys(),
-      ...rightFiles.keys(),
-    ]);
+    const allPaths = new Set([...baseFiles.keys(), ...leftFiles.keys(), ...rightFiles.keys()]);
 
     for (const path of allPaths) {
       const baseContent = baseFiles.get(path);
@@ -108,7 +120,7 @@ export class ConflictModel {
       if (this.mergeDriverRegistry) {
         const mergeResult = await this._tryMergeDriver(
           path,
-          {base: baseContent, ours: leftContent, theirs: rightContent},
+          { base: baseContent, ours: leftContent, theirs: rightContent },
           drivers,
           { baseChange, leftChange, rightChange }
         );
@@ -125,7 +137,10 @@ export class ConflictModel {
                   type: driverConflict.type || 'driver-conflict',
                   path,
                   sides: { base: baseContent, left: leftContent, right: rightContent },
-                  message: driverConflict.message || mergeResult.message || `Merge driver detected conflicts`,
+                  message:
+                    driverConflict.message ||
+                    mergeResult.message ||
+                    `Merge driver detected conflicts`,
                   driverResult: mergeResult,
                   driverFailed: mergeResult.driverFailed,
                   driverError: mergeResult.driverError,
@@ -167,6 +182,11 @@ export class ConflictModel {
 
   /**
    * Detect conflict for a single path
+   *
+   * @param {any} path
+   * @param {any} base
+   * @param {any} left
+   * @param {any} right
    */
   _detectPathConflict(path, base, left, right) {
     const baseExists = base !== undefined;
@@ -243,9 +263,12 @@ export class ConflictModel {
 
   /**
    * Create a conflict object
+   *
+   * @param {{ type: any, path: any, sides: any, message: any, driverFailed?: any, driverError?: any, driverResult?: any }} args
    */
   _createConflict({ type, path, sides, message, driverFailed, driverError }) {
     const conflictId = generateId('conflict');
+    /** @type {Record<string, any>} */
     const conflict = {
       conflictId,
       type,
@@ -269,6 +292,8 @@ export class ConflictModel {
 
   /**
    * Store a conflict
+   *
+   * @param {any} conflict
    */
   async addConflict(conflict) {
     this.conflicts.set(conflict.conflictId, conflict);
@@ -279,6 +304,8 @@ export class ConflictModel {
 
   /**
    * Get conflict by ID
+   *
+   * @param {any} conflictId
    */
   getConflict(conflictId) {
     return this.conflicts.get(conflictId);
@@ -286,6 +313,8 @@ export class ConflictModel {
 
   /**
    * Get conflict for a file path
+   *
+   * @param {any} path
    */
   getConflictForPath(path) {
     const conflictId = this.fileConflicts.get(path);
@@ -295,16 +324,18 @@ export class ConflictModel {
 
   /**
    * List all conflicts
+   *
+   * @param {Record<string, any>} [opts]
    */
   listConflicts(opts = {}) {
     let conflicts = Array.from(this.conflicts.values());
 
     if (opts.resolved !== undefined) {
-      conflicts = conflicts.filter(c => c.resolved === opts.resolved);
+      conflicts = conflicts.filter((c) => c.resolved === opts.resolved);
     }
 
     if (opts.type) {
-      conflicts = conflicts.filter(c => c.type === opts.type);
+      conflicts = conflicts.filter((c) => c.type === opts.type);
     }
 
     return conflicts;
@@ -312,6 +343,9 @@ export class ConflictModel {
 
   /**
    * Mark a conflict as resolved
+   *
+   * @param {any} conflictId
+   * @param {any} resolution
    */
   async resolveConflict(conflictId, resolution) {
     const conflict = this.conflicts.get(conflictId);
@@ -331,7 +365,7 @@ export class ConflictModel {
         // { side: 'ours' | 'theirs' | 'base' }
         if (!['ours', 'theirs', 'base'].includes(resolution.side)) {
           throw new JJError('INVALID_RESOLUTION', `Invalid side: ${resolution.side}`, {
-            suggestion: 'Use "ours", "theirs", or "base"'
+            suggestion: 'Use "ours", "theirs", or "base"',
           });
         }
         resolvedContent = { type: 'side', side: resolution.side };
@@ -359,6 +393,8 @@ export class ConflictModel {
 
   /**
    * Remove a conflict (after resolution is committed)
+   *
+   * @param {any} conflictId
    */
   async removeConflict(conflictId) {
     const conflict = this.conflicts.get(conflictId);
@@ -378,11 +414,12 @@ export class ConflictModel {
 
   /**
    * Create conflict markers for a content conflict (like Git's <<<<<<<, =======, >>>>>>>)
+   *
+   * @param {any} conflict
    */
   generateConflictMarkers(conflict) {
     if (conflict.type !== ConflictType.CONTENT) {
-      throw new JJError('INVALID_CONFLICT_TYPE',
-        'Can only generate markers for content conflicts');
+      throw new JJError('INVALID_CONFLICT_TYPE', 'Can only generate markers for content conflicts');
     }
 
     const { base, left, right } = conflict.sides;
@@ -400,9 +437,12 @@ export class ConflictModel {
 
   /**
    * Parse conflict markers from file content
+   *
+   * @param {any} content
    */
   parseConflictMarkers(content) {
-    const markerRegex = /^<{7} Left\n([\s\S]*?)\n\|{7} Base\n([\s\S]*?)\n={7}\n([\s\S]*?)\n>{7} Right$/gm;
+    const markerRegex =
+      /^<{7} Left\n([\s\S]*?)\n\|{7} Base\n([\s\S]*?)\n={7}\n([\s\S]*?)\n>{7} Right$/gm;
     const matches = markerRegex.exec(content);
 
     if (!matches) {
@@ -429,10 +469,10 @@ export class ConflictModel {
    * Try to use a merge driver for a file (v0.5)
    *
    * @param {string} path - File path
-   * @param {Object} content - Content versions { base, ours, theirs }
+   * @param {{ base?: string, ours?: string, theirs?: string }} content - Content versions { base, ours, theirs }
    * @param {Object} customDrivers - Per-merge custom drivers
    * @param {Object} metadata - Merge metadata
-   * @returns {Promise<Object|null>} Merge result or null if no driver
+   * @returns {Promise<Record<string, any>|null>} Merge result or null if no driver
    */
   async _tryMergeDriver(path, content, customDrivers, metadata) {
     if (!this.mergeDriverRegistry) {
@@ -469,7 +509,7 @@ export class ConflictModel {
    *
    * @param {string} workingCopyDir - Working copy directory
    * @param {string} filePath - File path
-   * @param {Object} result - Merge result
+   * @param {Record<string, any>} result - Merge result
    */
   async _writeDriverResult(workingCopyDir, filePath, result) {
     const fullPath = path.join(workingCopyDir, filePath);