isomorphic-jj 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isomorphic-jj",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "A pure-JavaScript library that brings Jujutsu (jj) version control semantics to Node.js and browsers",
   "type": "module",
   "bin": {

package/src/api/repository.js

@@ -756,69 +756,116 @@ export async function createJJ(options) {
      * @param {string[]} [args.paths] - Paths to move between changes (for history operations)
      * @returns {Promise<Object>} Returns change object for history operations, file info for file operations
      */
-    async move(args) {
-      if (!args || typeof args !== 'object') {
-        throw new JJError('INVALID_ARGUMENT', 'Missing or invalid arguments', {
-          suggestion: 'Use file.move({ from, to }) for files or rebase({ changeId, newParent }) for history',
+    /**
+     * Move a file in the working copy
+     *
+     * @param {Object} args - Move file arguments
+     * @param {string} args.from - Source file path
+     * @param {string} args.to - Destination file path
+     * @returns {Promise<Object>} Operation result including from, to paths and file stats
+     */
+    async moveFile(args) {
+      if (!args.from || typeof args.from !== 'string') {
+        throw new JJError('INVALID_ARGUMENT', 'Missing or invalid from path', {
+          suggestion: 'Provide a valid source file path',
+          provided: { from: args.from, type: typeof args.from },
         });
       }
 
-      // Detect operation type based on arguments
-      const isHistoryOp = this._detectHistoryOperation(args);
+      if (!args.to || typeof args.to !== 'string') {
+        throw new JJError('INVALID_ARGUMENT', 'Missing or invalid to path', {
+          suggestion: 'Provide a valid destination file path',
+          provided: { to: args.to, type: typeof args.to },
+        });
+      }
 
-      if (isHistoryOp) {
-        return await this._moveChange(args);
-      } else {
-        return await this._moveFile(args);
+      // Prevent moving to the same location
+      if (args.from === args.to) {
+        throw new JJError('INVALID_OPERATION', 'Source and destination paths are the same', {
+          path: args.from,
+          suggestion: 'Specify a different destination path',
+        });
       }
-    },
 
-    /**
-     * Detect if move operation is for history (rebase) or files
-     *
-     * @private
-     * @param {Object} args - Move arguments
-     * @returns {boolean} True if history operation, false if file operation
-     */
-    _detectHistoryOperation(args) {
-      // Explicit history operation indicators
-      if (args.paths || args.changeId || args.newParent) {
-        return true;
+      // Prevent absolute paths
+      if (args.from.startsWith('/') || args.to.startsWith('/')) {
+        throw new JJError('INVALID_PATH', 'Absolute paths are not allowed', {
+          suggestion: 'Use paths relative to the repository root',
+          provided: { from: args.from, to: args.to },
+        });
       }
 
-      // If only from/to are present, check if they look like change IDs
-      if (args.from && args.to && !args.changeId && !args.newParent && !args.paths) {
-        // Change IDs are 32-character hex strings
-        const changeIdPattern = /^[0-9a-f]{32}$/;
-        const fromLooksLikeChangeId = changeIdPattern.test(args.from);
-        const toLooksLikeChangeId = changeIdPattern.test(args.to);
+      // Prevent parent directory traversal
+      if (args.from.includes('..') || args.to.includes('..')) {
+        throw new JJError('INVALID_PATH', 'Parent directory traversal (..) is not allowed', {
+          suggestion: 'Use paths within the repository',
+          provided: { from: args.from, to: args.to },
+        });
+      }
 
-        // If both look like change IDs, it's likely a history operation
-        // However, we err on the side of file operations to be safe
-        // Users should use explicit { changeId, newParent } for clarity
-        if (fromLooksLikeChangeId && toLooksLikeChangeId) {
-          // This is ambiguous - throw a helpful error
-          throw new JJError('AMBIGUOUS_OPERATION',
-            'Ambiguous move operation: arguments look like change IDs', {
-            suggestion: 'Use { changeId, newParent } for history operations or ensure file paths don\'t match change ID pattern',
-            args,
-          });
-        }
+      const fromPath = `${dir}/${args.from}`;
+      const toPath = `${dir}/${args.to}`;
 
-        return false; // Treat as file operation
+      // Check if source file exists
+      try {
+        await fs.promises.stat(fromPath);
+      } catch (error) {
+        throw new JJError('FILE_NOT_FOUND', `Source file not found: ${args.from}`, {
+          path: args.from,
+          suggestion: 'Check that the source file exists',
+        });
       }
 
-      return false;
+      // Ensure destination directory exists
+      const toDir = toPath.substring(0, toPath.lastIndexOf('/'));
+      try {
+        await fs.promises.mkdir(toDir, { recursive: true });
+      } catch (error) {
+        throw new JJError('FILE_SYSTEM_ERROR', `Failed to create destination directory: ${error.message}`, {
+          path: toDir,
+          error: error.message,
+        });
+      }
+
+      // Move the file
+      try {
+        await fs.promises.rename(fromPath, toPath);
+      } catch (error) {
+        throw new JJError('FILE_SYSTEM_ERROR', `Failed to move file: ${error.message}`, {
+          from: args.from,
+          to: args.to,
+          error: error.message,
+        });
+      }
+
+      // Update working copy tracking
+      await workingCopy.load();
+      await workingCopy.untrackFile(args.from);
+      const stats = await fs.promises.stat(toPath);
+      await workingCopy.trackFile(args.to, {
+        mtime: stats.mtime,
+        size: stats.size,
+        mode: stats.mode,
+      });
+
+      return {
+        from: args.from,
+        to: args.to,
+        size: stats.size,
+        mode: stats.mode,
+        mtime: stats.mtime,
+      };
     },
 
     /**
-     * Move/rebase a change to a new parent (history operation)
+     * Move (rebase) a change to a new parent
      *
-     * @private
-     * @param {Object} args - Move arguments
+     * @param {Object} args - Move change arguments
+     * @param {string} args.changeId - Change ID to move (also accepts 'from' or 'source')
+     * @param {string} args.newParent - New parent change ID (also accepts 'to' or 'destination')
      * @returns {Promise<Object>} Updated change object
      */
-    async _moveChange(args) {
+    async moveChange(args) {
       await graph.load();
 
       // Support multiple parameter names for flexibility
@@ -906,110 +953,62 @@ export async function createJJ(options) {
     },
 
     /**
-     * Move/rename a file in the working copy (file operation)
-     *
-     * @private
-     * @param {Object} args - Move arguments
-     * @returns {Promise<Object>} Operation result including from, to paths and file stats
+     * @deprecated Use moveFile() for files or moveChange() for history operations
+     * Move operation - delegates to moveFile or moveChange based on arguments
      */
-    async _moveFile(args) {
-      if (!args.from || typeof args.from !== 'string') {
-        throw new JJError('INVALID_ARGUMENT', 'Missing or invalid from path', {
-          suggestion: 'Provide a valid source file path',
-          provided: { from: args.from, type: typeof args.from },
-        });
-      }
-
-      if (!args.to || typeof args.to !== 'string') {
-        throw new JJError('INVALID_ARGUMENT', 'Missing or invalid to path', {
-          suggestion: 'Provide a valid destination file path',
-          provided: { to: args.to, type: typeof args.to },
+    async move(args) {
+      if (!args || typeof args !== 'object') {
+        throw new JJError('INVALID_ARGUMENT', 'Missing or invalid arguments', {
+          suggestion: 'Use moveFile({ from, to }) for files or moveChange({ changeId, newParent }) for history',
         });
       }
 
-      // Prevent moving to the same location
-      if (args.from === args.to) {
-        throw new JJError('INVALID_OPERATION', 'Source and destination paths are the same', {
-          path: args.from,
-          suggestion: 'Specify a different destination path',
-        });
-      }
+      // Detect operation type based on arguments
+      const isHistoryOp = this._detectHistoryOperation(args);
 
-      // Prevent absolute paths
-      if (args.from.startsWith('/') || args.to.startsWith('/')) {
-        throw new JJError('INVALID_PATH', 'Absolute paths are not allowed', {
-          suggestion: 'Use paths relative to the repository root',
-          provided: { from: args.from, to: args.to },
-        });
+      if (isHistoryOp) {
+        return await this.moveChange(args);
+      } else {
+        return await this.moveFile(args);
       }
+    },
 
-      // Prevent parent directory traversal
-      if (args.from.includes('..') || args.to.includes('..')) {
-        throw new JJError('INVALID_PATH', 'Parent directory traversal (..) is not allowed', {
-          suggestion: 'Use paths within the repository',
-          provided: { from: args.from, to: args.to },
-        });
+    /**
+     * Detect if move operation is for history (rebase) or files
+     *
+     * @private
+     * @param {Object} args - Move arguments
+     * @returns {boolean} True if history operation, false if file operation
+     */
+    _detectHistoryOperation(args) {
+      // Explicit history operation indicators
+      if (args.paths || args.changeId || args.newParent) {
+        return true;
       }
 
-      const fromPath = `${dir}/${args.from}`;
-      const toPath = `${dir}/${args.to}`;
-
-      // Check if source file exists
-      try {
-        await fs.promises.access(fromPath);
-      } catch (error) {
-        throw new JJError('FILE_NOT_FOUND', `Source file not found: ${args.from}`, {
-          path: args.from,
-          fullPath: fromPath,
-          suggestion: 'Check that the file exists',
-        });
-      }
+      // If only from/to are present, check if they look like change IDs
+      if (args.from && args.to && !args.changeId && !args.newParent && !args.paths) {
+        // Change IDs are 32-character hex strings
+        const changeIdPattern = /^[0-9a-f]{32}$/;
+        const fromLooksLikeChangeId = changeIdPattern.test(args.from);
+        const toLooksLikeChangeId = changeIdPattern.test(args.to);
 
-      // Ensure destination directory exists
-      const pathParts = args.to.split('/');
-      if (pathParts.length > 1) {
-        const dirPath = pathParts.slice(0, -1).join('/');
-        const fullDirPath = `${dir}/${dirPath}`;
-        try {
-          await fs.promises.mkdir(fullDirPath, { recursive: true });
-        } catch (error) {
-          throw new JJError('DIRECTORY_CREATE_FAILED',
-            `Failed to create destination directory: ${dirPath}`, {
-            directory: dirPath,
-            originalError: error.message,
+        // If both look like change IDs, it's likely a history operation
+        // However, we err on the side of file operations to be safe
+        // Users should use explicit { changeId, newParent } for clarity
+        if (fromLooksLikeChangeId && toLooksLikeChangeId) {
+          // This is ambiguous - throw a helpful error
+          throw new JJError('AMBIGUOUS_OPERATION',
+            'Ambiguous move operation: arguments look like change IDs', {
+            suggestion: 'Use { changeId, newParent } for history operations or ensure file paths don\'t match change ID pattern',
+            args,
           });
         }
-      }
 
-      // Move the file
-      try {
-        await fs.promises.rename(fromPath, toPath);
-      } catch (error) {
-        throw new JJError('FILE_MOVE_FAILED', `Failed to move file: ${error.message}`, {
-          from: args.from,
-          to: args.to,
-          originalError: error.message,
-        });
+        return false; // Treat as file operation
       }
 
-      // Update working copy tracking
-      await workingCopy.load();
-      await workingCopy.untrackFile(args.from);
-      const stats = await fs.promises.stat(toPath);
-      await workingCopy.trackFile(args.to, {
-        mtime: stats.mtime,
-        size: stats.size,
-        mode: stats.mode,
-      });
-
-      // Return useful information about the move operation
-      return {
-        from: args.from,
-        to: args.to,
-        size: stats.size,
-        mode: stats.mode,
-        mtime: stats.mtime,
-      };
+      return false;
     },
 
     /**
@@ -1085,6 +1084,11 @@ export async function createJJ(options) {
         change.timestamp = new Date().toISOString();
       }
 
+      // Update metadata
+      if (args.metadata !== undefined) {
+        change.metadata = args.metadata;
+      }
+
       // Only snapshot files if describing working copy
       if (isWorkingCopy) {
         // Snapshot current file contents for conflict detection
@@ -1689,10 +1693,11 @@ export async function createJJ(options) {
      * @param {Object} [args={}] - Arguments
      * @param {string} [args.message] - Description for current change
      * @param {Object} [args.author] - Author for current change
+     * @param {Object} [args.metadata] - Metadata to attach to the change
      * @returns {Promise<Object>} The newly created change
      */
     async commit(args = {}) {
-      await this.describe({ message: args.message, author: args.author });
+      await this.describe({ message: args.message, author: args.author, metadata: args.metadata });
       return await this.new({ message: args.nextMessage });
     },
 
@@ -2516,7 +2521,7 @@ export async function createJJ(options) {
      * });
      */
     async rebase(args) {
-      return await this._moveChange(args);
+      return await this.moveChange(args);
     },
 
     /**

package/src/types.d.ts

@@ -76,6 +76,7 @@ export interface Change {
   description: string;
   timestamp: Date;
   fileSnapshot?: Record<string, FileSnapshot>;
+  metadata?: Record<string, any>;
 }
 
 /**
@@ -330,6 +331,24 @@ export interface MoveFileArgs {
   to: string;
 }
 
+/**
+ * Move change (rebase) arguments
+ */
+export interface MoveChangeArgs {
+  /** Change ID to move (also accepts 'from' or 'source') */
+  changeId?: ChangeID;
+  /** Source change ID (alias for changeId) */
+  from?: ChangeID;
+  /** Source change ID (alias for changeId) */
+  source?: ChangeID;
+  /** New parent change ID (also accepts 'to' or 'destination') */
+  newParent?: ChangeID;
+  /** Destination change ID (alias for newParent) */
+  to?: ChangeID;
+  /** Destination change ID (alias for newParent) */
+  destination?: ChangeID;
+}
+
 /**
  * Remove file arguments
  */
@@ -460,6 +479,8 @@ export interface UnabandonArgs {
 export interface LogOptions {
   revset?: Revset;
   limit?: number;
+  /** If true, return count of commits instead of commit objects */
+  count?: boolean;
 }
 
 /**
@@ -856,6 +877,122 @@ export interface MergeResult {
   conflicts: Conflict[];
 }
 
+/**
+ * Absorb operation arguments
+ */
+export interface AbsorbArgs {
+  /** Change to absorb into (optional, defaults to working copy parent) */
+  changeId?: ChangeID;
+  /** Destination change to absorb into (alias for changeId) */
+  destination?: ChangeID;
+  /** Dry run mode - don't apply changes */
+  dryRun?: boolean;
+  /** Specific paths to absorb */
+  paths?: string[];
+}
+
+/**
+ * Absorb operation result
+ */
+export interface AbsorbResult {
+  /** Changes that were absorbed */
+  absorbed: Array<{
+    path: string;
+    hunks: number;
+    destination: ChangeID;
+  }>;
+  /** Changes affected by the absorb */
+  affectedChanges: ChangeID[];
+  /** Changes that would be absorbed (dry run mode) */
+  wouldAbsorb?: Array<{
+    path: string;
+    hunks: number;
+    destination: ChangeID;
+  }>;
+}
+
+/**
+ * Bisect start arguments
+ */
+export interface BisectStartArgs {
+  /** Good change ID */
+  good: ChangeID;
+  /** Bad change ID */
+  bad: ChangeID;
+}
+
+/**
+ * Bisect state
+ */
+export interface BisectState {
+  /** Whether bisect is active */
+  active: boolean;
+  /** Good change */
+  good?: ChangeID;
+  /** Bad change */
+  bad?: ChangeID;
+  /** Current change being tested */
+  current?: ChangeID;
+  /** Remaining changes to test */
+  remaining?: number;
+}
+
+/**
+ * Sparse checkout set arguments
+ */
+export interface SparseSetArgs {
+  /** Patterns to set (replaces existing patterns) */
+  patterns: string[];
+}
+
+/**
+ * Sparse checkout add arguments
+ */
+export interface SparseAddArgs {
+  /** Patterns to add to existing sparse checkout */
+  patterns: string[];
+}
+
+/**
+ * Sparse checkout remove arguments
+ */
+export interface SparseRemoveArgs {
+  /** Patterns to remove from sparse checkout */
+  patterns: string[];
+}
+
+/**
+ * Merge driver for custom file merging
+ */
+export interface MergeDriver {
+  /** Driver name */
+  name: string;
+  /** Detect if this driver should handle a file */
+  detect(path: string, content: string): boolean;
+  /** Merge three versions of a file */
+  merge(args: {
+    path: string;
+    base: string;
+    ours: string;
+    theirs: string;
+  }): {
+    merged: string;
+    conflicts?: Array<{ line: number; message: string }>;
+  };
+}
+
+/**
+ * Merge driver registry
+ */
+export interface MergeDriverRegistry {
+  /** Register a custom merge driver */
+  register(driver: MergeDriver): void;
+  /** Get driver for a file path */
+  getDriver(path: string, content: string): MergeDriver | null;
+  /** List all registered drivers */
+  list(): MergeDriver[];
+}
+
 // ============================================================================
 // Main JJ Repository Interface
 // ============================================================================
@@ -875,6 +1012,7 @@ export interface JJ {
   revset: any;
   gitBackend?: any;
   backgroundOps?: any;
+  mergeDrivers: MergeDriverRegistry;
 
   // Repository lifecycle
   init(opts?: InitOptions): Promise<void>;
@@ -883,7 +1021,12 @@ export interface JJ {
   write(args: WriteArgs): Promise<WriteResult>;
   read(args: ReadArgs): Promise<string | Uint8Array>;
   cat(args: ReadArgs): Promise<string | Uint8Array>;
-  move(args: MoveFileArgs): Promise<MoveResult>;
+  moveFile(args: MoveFileArgs): Promise<MoveResult>;
+  moveChange(args: MoveChangeArgs): Promise<Change>;
+  /**
+   * @deprecated Use moveFile() for files or moveChange() for history operations
+   */
+  move(args: MoveFileArgs | MoveChangeArgs): Promise<MoveResult | Change>;
   remove(args: RemoveArgs): Promise<RemoveResult>;
   listFiles(args?: ListFilesArgs): Promise<string[]>;
   readStream(args: ReadStreamArgs): Promise<any>;
@@ -904,9 +1047,11 @@ export interface JJ {
   rebase(args: RebaseArgs): Promise<Change>;
   abandon(args: AbandonArgs): Promise<void>;
   unabandon(args: UnabandonArgs): Promise<void>;
+  absorb(args?: AbsorbArgs): Promise<AbsorbResult>;
 
   // Queries
-  log(opts?: LogOptions): Promise<LogEntry[]>;
+  log(opts?: LogOptions & { count?: false }): Promise<LogEntry[]>;
+  log(opts: LogOptions & { count: true }): Promise<number>;
   show(args: ShowArgs): Promise<Change>;
   obslog(opts?: ObslogOptions): Promise<Operation[]>;
 
@@ -1104,6 +1249,25 @@ export interface JJ {
     }>;
     parent: ChangeID;
   }>;
+
+  // Bisect operations
+  bisect: {
+    start(args: BisectStartArgs): Promise<void>;
+    good(): Promise<void>;
+    bad(): Promise<void>;
+    status(): Promise<BisectState>;
+    reset(): Promise<void>;
+  };
+
+  // Sparse checkout
+  sparse: {
+    list(): Promise<string[]>;
+    set(args: SparseSetArgs): Promise<void>;
+    add(args: SparseAddArgs): Promise<void>;
+    remove(args: SparseRemoveArgs): Promise<void>;
+    reset(): Promise<void>;
+    clear(): Promise<void>;
+  };
 }
 
 // ============================================================================