isomorphic-jj 1.1.3 → 1.2.0

package/README.md

@@ -202,6 +202,54 @@ await jj.amend();
 await jj.undo();
 ```
 
+### Understanding Working Copy vs Parent
+
+A common source of confusion: **the working copy and its parent are different changes**.
+
+```javascript
+// After init, you have a working copy change (with changeId)
+const status1 = await jj.status();
+console.log(status1.workingCopy.changeId);  // e.g., "abc123..."
+console.log(status1.workingCopy.description);  // "(no description set)"
+
+// When you describe(), you're updating the PARENT change
+await jj.describe({ message: 'Add feature' });
+
+// The working copy changeId is STILL the same!
+const status2 = await jj.status();
+console.log(status2.workingCopy.changeId);  // SAME: "abc123..."
+console.log(status2.workingCopy.description);  // UPDATED: "Add feature"
+
+// When you new(), you create a NEW working copy
+await jj.new({ message: 'Next change' });
+
+const status3 = await jj.status();
+console.log(status3.workingCopy.changeId);  // DIFFERENT: "def456..."
+console.log(status3.workingCopy.description);  // "Next change"
+```
+
+**Key points:**
+- **Working copy IS a change** with its own `changeId` (always `@` in revsets)
+- **`describe()`** updates the parent's description, not the working copy's changeId
+- **`status()`** returns the working copy changeId (which may or may not have a description)
+- **`new()`** creates a new working copy change and makes the previous one the parent
+- **Reading metadata immediately after write** shows working copy state, not parent state
+
+**Common pattern:**
+```javascript
+// 1. Edit files
+await jj.write({ path: 'file.js', data: 'content' });
+
+// 2. Describe the change (updates parent)
+await jj.describe({ message: 'Add file' });
+
+// 3. Create new working copy for next change
+await jj.new({ message: 'Next feature' });
+
+// Or use commit() to combine describe() + new()
+await jj.commit({ message: 'Add file', nextMessage: 'Next feature' });
+```
+
 ---
 
 ## Features

package/dist/index.cjs

@@ -1312,6 +1312,7 @@ class BookmarkStore {
     this.storage = storage;
     this.local = new Map();
     this.remote = new Map(); // remote → (bookmark → changeId)
+    this.tracking = {}; // bookmark → { remote, ref } tracking info (v0.35.0)
   }
 
   /**
@@ -1354,6 +1355,7 @@ class BookmarkStore {
 
     this.local.clear();
     this.remote.clear();
+    this.tracking = data.tracked || {}; // Load tracking info (v0.35.0)
 
     // Load local bookmarks
     for (const [name, target] of Object.entries(data.local)) {
@@ -1391,7 +1393,7 @@ class BookmarkStore {
       version: 1,
       local,
       remote,
-      tracked: {},
+      tracked: this.tracking || {}, // Save tracking info (v0.35.0)
     });
   }
 
@@ -1504,13 +1506,23 @@ class BookmarkStore {
   async list() {
     const result = [];
 
-    // Add local bookmarks
+    // Add local bookmarks with tracking info (v0.35.0)
     for (const [name, target] of this.local.entries()) {
-      result.push({
+      const bookmark = {
         name,
         changeId: target,
         remote: null,
-      });
+      };
+
+      // Include tracking info if available
+      if (this.tracking && this.tracking[name]) {
+        bookmark.tracking = {
+          remote: this.tracking[name].remote,
+          ref: this.tracking[name].remoteName || name,
+        };
+      }
+
+      result.push(bookmark);
     }
 
     // Add remote bookmarks
@@ -1832,6 +1844,24 @@ class RevsetEngine {
       }
     }
 
+    // v0.36.0: visible() - non-abandoned changes
+    if (trimmed === 'visible()') {
+      await this.graph.load();
+      const all = this.graph.getAll();
+      return all
+        .filter(c => !c.abandoned)
+        .map(c => c.changeId);
+    }
+
+    // v0.36.0: hidden() - abandoned changes
+    if (trimmed === 'hidden()') {
+      await this.graph.load();
+      const all = this.graph.getAll();
+      return all
+        .filter(c => c.abandoned === true)
+        .map(c => c.changeId);
+    }
+
     // ancestors(changeId) - all ancestors including the change itself
     const ancestorsMatch = trimmed.match(/^ancestors\(([0-9a-f]{32})\)$/);
     if (ancestorsMatch) {
@@ -4279,9 +4309,15 @@ class UserConfig {
   }
 
   /**
-   * Load config from storage
+   * Load config from storage and/or programmatic object
+   * v0.35.0: Also loads workspace-specific config from workspace-config.json
+   * v0.36.0: Accepts optional config object for programmatic configuration
+   *
+   * @param {Object} [opts] - Optional config options
+   * @param {Object} [opts.workspace] - Workspace-specific config to merge (highest priority)
+   * @param {Object} [opts.override] - Config object to merge over loaded config
    */
-  async load() {
+  async load(opts = {}) {
     try {
       const data = await this.storage.read('config.json');
       if (data) {
@@ -4291,6 +4327,45 @@ class UserConfig {
       // No config file yet, use defaults
       await this.init();
     }
+
+    // Merge programmatic override config if provided
+    if (opts.override) {
+      this.config = this._deepMerge(this.config, opts.override);
+    }
+
+    // Load workspace-specific config from file (v0.35.0)
+    try {
+      const workspaceData = await this.storage.read('workspace-config.json');
+      if (workspaceData) {
+        // Merge workspace config over global config (workspace takes precedence)
+        this.config = this._deepMerge(this.config, workspaceData);
+      }
+    } catch (error) {
+      // No workspace config, that's fine
+    }
+
+    // Merge programmatic workspace config if provided (highest priority)
+    if (opts.workspace) {
+      this.config = this._deepMerge(this.config, opts.workspace);
+    }
+  }
+
+  /**
+   * Deep merge two config objects (workspace overrides global)
+   * @private
+   */
+  _deepMerge(target, source) {
+    const result = { ...target };
+
+    for (const key in source) {
+      if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+        result[key] = this._deepMerge(target[key] || {}, source[key]);
+      } else {
+        result[key] = source[key];
+      }
+    }
+
+    return result;
   }
 
   /**
@@ -7017,7 +7092,8 @@ async function createJJ(options) {
      * @param {Object} args - Arguments
      * @param {string} [args.revset='all()'] - Revset expression to filter changes
      * @param {number} [args.limit] - Maximum number of changes to return
-     * @returns {Promise<Array>} Array of changes
+     * @param {boolean} [args.count=false] - If true, return count instead of changes (v0.36.0)
+     * @returns {Promise<Array|number>} Array of changes or count if args.count is true
      */
     async log(args = {}) {
       await graph.load();
@@ -7026,6 +7102,11 @@ async function createJJ(options) {
       const revsetExpr = args.revset || 'all()';
       const changeIds = await revset.evaluate(revsetExpr);
 
+      // If count mode, return count early (v0.36.0 feature)
+      if (args.count) {
+        return changeIds.length;
+      }
+
       let changes = [];
       for (const changeId of changeIds) {
         const change = await graph.getChange(changeId);
@@ -8046,9 +8127,18 @@ async function createJJ(options) {
      * @returns {Promise<Object>} The new backout change including changeId, description, and backedOut field
      */
     async backout(args) {
+      // Normalize: accept common parameter aliases
+      if (args && args.change && !args.revision) {
+        args = { ...args, revision: args.change };
+      } else if (args && args.changeId && !args.revision) {
+        args = { ...args, revision: args.changeId };
+      } else if (args && args.target && !args.revision) {
+        args = { ...args, revision: args.target };
+      }
+
       if (!args || !args.revision) {
         throw new JJError('INVALID_ARGUMENT', 'Missing revision argument', {
-          suggestion: 'Provide the change ID to back out: { revision: "abc123..." }',
+          suggestion: 'Provide the change ID to back out: { revision: "abc123..." } (or use change/changeId/target)',
         });
       }
 
@@ -9083,6 +9173,15 @@ async function createJJ(options) {
      * @param {string[]} [args.paths] - Specific paths to include in first split (full implementation planned for future)
      */
     async split(args) {
+      // Normalize: accept common parameter aliases
+      if (args && args.change && !args.changeId) {
+        args = { ...args, changeId: args.change };
+      } else if (args && args.revision && !args.changeId) {
+        args = { ...args, changeId: args.revision };
+      } else if (args && args.target && !args.changeId) {
+        args = { ...args, changeId: args.target };
+      }
+
       // Check for interactive mode (not supported)
       if (args.interactive) {
         throw new JJError(
@@ -11324,21 +11423,13 @@ async function createJJ(options) {
           });
         }
 
-        await userConfig.load();
-
-        // Handle nested keys (e.g., 'user.name')
-        const parts = key.split('.');
-        let value = userConfig.config;
-
-        for (const part of parts) {
-          if (value && typeof value === 'object') {
-            value = value[part];
-          } else {
-            return null;
-          }
+        // Ensure config is loaded at least once
+        if (!userConfig.config) {
+          await userConfig.load();
         }
 
-        return value;
+        // Use userConfig.get() to preserve programmatic config
+        return userConfig.get(key);
       },
 
       /**
@@ -11387,6 +11478,87 @@ async function createJJ(options) {
         await userConfig.load();
         return userConfig.config;
       },
+
+      /**
+       * Reload configuration (including workspace-specific config)
+       * v0.35.0: Loads workspace-config.json if present
+       * v0.36.0: Accepts optional config object for programmatic configuration
+       *
+       * @param {Object} [opts] - Optional config options
+       * @param {Object} [opts.workspace] - Workspace-specific config to merge (highest priority)
+       * @param {Object} [opts.override] - Config object to merge over loaded config
+       * @returns {Promise<void>}
+       *
+       * @example
+       * // Load from files only
+       * await repo.config.load();
+       *
+       * @example
+       * // Programmatic workspace config (no file I/O needed)
+       * await repo.config.load({
+       *   workspace: { user: { email: 'test@example.com' } }
+       * });
+       *
+       * @example
+       * // Override global config programmatically
+       * await repo.config.load({
+       *   override: { test: { value: 'override' } }
+       * });
+       */
+      async load(opts) {
+        await userConfig.load(opts);
+      },
+    },
+
+    /**
+     * Template helper functions (v0.36.0)
+     *
+     * Utilities for displaying and formatting JJ data
+     */
+    template: {
+      /**
+       * Get files modified in a change
+       *
+       * @param {string} changeId - Change ID
+       * @returns {Promise<string[]>} Array of file paths
+       */
+      async files(changeId) {
+        await graph.load();
+        const change = await graph.getChange(changeId);
+        if (!change || !change.fileSnapshot) {
+          return [];
+        }
+        return Object.keys(change.fileSnapshot);
+      },
+
+      /**
+       * Join array elements with a separator
+       *
+       * @param {string[]} array - Array of strings
+       * @param {string} separator - Separator string
+       * @returns {string} Joined string
+       */
+      join(array, separator) {
+        if (!Array.isArray(array)) {
+          return '';
+        }
+        return array.join(separator);
+      },
+
+      /**
+       * Format path for display
+       *
+       * @param {string} path - File path
+       * @returns {string} Formatted path
+       */
+      format_path(path) {
+        if (!path) {
+          return '';
+        }
+        // Simple formatting: just return the path as-is for now
+        // In real JJ, this might apply colors, truncation, etc.
+        return path;
+      },
     },
 
     /**