isomorphic-jj 1.12.1 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 1.14.0 — 2026-10-09 — describe()/metaedit() honor changeId; operations.restore() restores the view
+
+Fixes [#55](https://github.com/johnhenry/isomorphic-jj/issues/55) and
+[#56](https://github.com/johnhenry/isomorphic-jj/issues/56). Both change
+observable behavior, hence a minor bump.
+
+### Fixed
+
+- **`describe()` and `metaedit()` ignored `changeId`.** Both only read the
+  older `revision` option (`metaedit` also `change`), so
+  `describe({ changeId, message })` silently rewrote the working-copy change
+  instead of the named one -- the documented option (API.md) did nothing and
+  `DescribeArgs` in `types.d.ts` didn't list it. Both now accept `changeId`
+  (alongside `revision`), rewrite exactly that change, leave the working
+  copy's description alone, and keep change IDs stable. `DescribeArgs` gains
+  `changeId` and `revision`. Regression tests:
+  `tests/integration/describe-change-id.test.js`.
+- **`operations.restore()` left changes created after the target operation
+  visible.** The restore operation recorded the right view (heads, working
+  copy), but the revset layer only hid orphaned changes that were empty and
+  undescribed, so a described change stayed in `log()`, `heads(all())` and
+  `visible_heads()`. As in jj, restoring now restores the *view*: every
+  change created after the target operation and unreachable from the
+  restored working copy, bookmarks and tags is hidden (not deleted -- it
+  stays in the graph and resolvable by change ID). The hidden set is stored
+  in the operation's `view.hiddenChanges`, so it persists across later
+  operations, `undo()`/`redo()` of the restore bring the changes back, and
+  they reappear if the working copy/bookmarks make them reachable again
+  (e.g. `edit({ changeId })`). **Behavior change:** `log()` after a restore
+  no longer lists such changes. Regression tests:
+  `tests/integration/op-restore-view.test.js`.
+
+## 1.13.0 — 2026-10-05 — Write-path fixes: converge on a fresh instance, new files lost on edit(), rebase content
+
+Fixed in [PR #52](https://github.com/johnhenry/isomorphic-jj/pull/52).
+
+Three bugs found while wiring a consumer (JJHub's isomorphic jj engine)
+to write through this library, constructing one fresh `createJJ()`
+instance per call so no read is ever served from a stale cache. Two of
+them change observable behavior, hence a minor bump.
+
+### Fixed
+
+- **`converge()` threw `WORKING_COPY_NOT_LOADED` on a fresh instance.**
+  Both outcomes record the working copy in their operation, but
+  `converge()` loaded only the graph and user config — so it only worked
+  after some earlier call on the same instance had loaded the working
+  copy. It now loads it itself. Regression tests: "on a fresh instance"
+  in `tests/integration/converge.test.js`.
+- **A new file `write()` created was deleted by the next `edit()` away.**
+  `write()` tracks a file without recording it in the working-copy
+  change (the next command commits it, as in jj), but `edit()` first
+  deleted every tracked file missing from the change being left, as
+  cross-branch "pollution" from an earlier checkout. Since issue #30 every
+  switch fully syncs the working directory to its target, so nothing
+  leaks that way any more; what the cleanup actually removed was every new
+  file — top-level or nested — written into that change. Edits to files
+  already recorded survived, which made it look path-dependent. `edit()`
+  now commits every tracked file into the change it leaves, like
+  `new()`/`describe()`. **Behavior change:** a tracked file on disk is
+  now always the checked-out change's content when `edit()` leaves it;
+  code that removed a file from a change by editing the graph alone (not
+  `remove()`) must now remove it from disk too —
+  `tests/integration/issue-43-restore-reliability.test.js`'s
+  descendant-deletion test did exactly that and now uses `remove()`.
+  Regression tests: "write() then edit() away" in
+  `tests/integration/file-operations.test.js`.
+- **`moveChange()`/`rebase()` kept the change's own tree verbatim.** The
+  three-way conflict check from issue #31 ran, but the rebased content
+  was never derived from it: the change kept every file only its OLD
+  parent had and never picked up what only the NEW parent changed. Its
+  content is now jj's rebase, path by path — the new parent's value
+  wherever the change didn't touch a path relative to its old parent,
+  the change's own value wherever it did (a path both sides changed
+  differently is the conflict #31 already reports, with markers). When
+  the moved change is checked out, its files on disk are synced to the
+  result. **Behavior change:** a rebased change's `fileSnapshot` now
+  differs from before for any path its old and new parents disagree on.
+  Regression tests: "content of the rebased change" in
+  `tests/integration/rebase-conflict-detection.test.js`.
+
+### Not changed
+
+- `moveChange()` still re-derives only the moved change's own content,
+  not that of its descendants (they follow it structurally, by parent
+  change id, but keep their trees) — see the README's status section.
+- Conflict detection still compares whole files, not lines: two sides
+  changing different lines of one file is a conflict.
+
+### Testing
+
+1882 tests passing, 0 skipped; lint, format:check, typecheck, and all 12
+`examples/*.mjs` green; coverage 97.39% statements / 90.13% branches
+(gate 90%). Each new regression test fails against 1.12.1's source.
+
 ## 1.12.1 — 2026-09-27 — Conflict type shape + README status refresh
 
 A cross-library documentation/typing audit flagged four things to verify

package/README.md

@@ -1020,8 +1020,8 @@ repo/
 
 ## Project Status
 
-**Current Version**: 1.12.0 (`@johnhenry/isomorphic-jj`; same library/API lineage as the old `isomorphic-jj`, which reached v1.8.0 before the rename — see the provenance note at the top of this file, and the CHANGELOG's `1.9.0` entry for how the scoped/unscoped version lineages were merged back together)
-**Test Coverage**: 1874 tests passing, ~97% statements / 90% branches
+**Current Version**: 1.14.0 (`@johnhenry/isomorphic-jj`; same library/API lineage as the old `isomorphic-jj`, which reached v1.8.0 before the rename — see the provenance note at the top of this file, and the CHANGELOG's `1.9.0` entry for how the scoped/unscoped version lineages were merged back together)
+**Test Coverage**: 1882 tests passing, ~97% statements / 90% branches
 **JJ CLI parity**: tracks Jujutsu through v0.45.1
 **Status**: Actively developed; broad JJ CLI semantic parity, used in the examples/apps in this repo and in [JJHub](#family). Not yet 1.0 in the API-stability sense (the version number is past 1.0 only because merging the scoped/unscoped lineages forced it above the unscoped side's prior ceiling, not because the API is frozen) — API surface can still shift; pin a version and read the CHANGELOG before upgrading.
 
@@ -1038,6 +1038,8 @@ repo/
 - ✅ 0.3.0: Parity refresh tracking jj through **v0.45.1** — a working `/browser` entry (async `createBrowserFS()`, bundle-safe protobuf schema loading, no stray Node-only imports), `undo()`/`operations.restore()` reverting graph rewrites with real progressive undo/redo, `squash()`/`abandon()`/`edit()`/`new()` fully syncing content instead of only metadata, `rebase()` performing a real three-way merge and recording conflicts, and the new `converge()` command (jj v0.45.0) to auto-resolve divergent commits. See [CHANGELOG.md](./CHANGELOG.md).
 - ✅ 0.4.0: `converge()` generalized from pairwise to N-way — any number of divergent copies of one change id resolve in a single call, matching how jj's own underlying engine already treats divergence internally (issue #32). See [CHANGELOG.md](./CHANGELOG.md).
 - ✅ 1.9.0: Scoped (`@johnhenry/isomorphic-jj`) and unscoped (`isomorphic-jj`) version lineages merged into one shared version going forward, with both names dual-published on every release.
+- ✅ 1.14.0: `describe()`/`metaedit()` honor `changeId`; `operations.restore()` restores the view (changes created after the target op are hidden from `log()`). See [CHANGELOG.md](./CHANGELOG.md).
+- ✅ 1.13.0: Write-path fixes — `converge()` works on a fresh instance, `edit()` no longer deletes new files `write()` created in the change it leaves, and `moveChange()`/`rebase()` derives the rebased change's content (new parent + the change's own edits) instead of keeping its tree verbatim. Not done: a rebase re-derives only the moved change's content, not its descendants', and conflicts are detected per whole file, not per line. See [CHANGELOG.md](./CHANGELOG.md).
 - ✅ 1.9.1 – 1.12.0: Operation-log reliability pass — `undo()`/`operations.restore()` correctness across write/snapshot/squash/rebase/abandon/edit, `log()` visibility fixes, and recording gaps in descendant rebases and conflict-resolution ops (issues #37–#39, #41, #43, #45, #48). See [CHANGELOG.md](./CHANGELOG.md) for the full per-fix breakdown.
 
 See [ROADMAP.md](./ROADMAP.md) for detailed plans, and [CHANGELOG.md](./CHANGELOG.md) for the release history.

package/dist/index.cjs

@@ -1517,6 +1517,24 @@ class OperationLog {
       operation.parents = operation.parents || [];
     }
 
+    // `view.hiddenChanges` (written by operations.restore()) is part of the
+    // view, so it persists across later operations. undo()/redo()/restore()
+    // set it explicitly (their view is a snapshot of another operation);
+    // every other operation carries the current head's value forward.
+    if (
+      this.headOperationId &&
+      operation.view &&
+      !('hiddenChanges' in operation.view) &&
+      operation.eventType !== 'undo' &&
+      operation.eventType !== 'redo'
+    ) {
+      const headOp = this.operations.find((op) => op.id === this.headOperationId);
+      const inherited = headOp.view && headOp.view.hiddenChanges;
+      if (inherited && inherited.length > 0) {
+        operation.view = { ...operation.view, hiddenChanges: inherited };
+      }
+    }
+
     // Generate operation ID
     const id = await generateOperationId(operation);
     const fullOperation = {
@@ -2763,16 +2781,18 @@ class RevsetEngine {
       case 'visible_heads': {
         await this.graph.load();
         const allChanges = this.graph.getAll();
-        const changeIdSet = new Set(allChanges.map((c) => c.changeId));
+        const restoreHidden = await this._computeRestoreHidden();
+        const visibleChanges = allChanges.filter((c) => !restoreHidden.has(c.changeId));
+        const changeIdSet = new Set(visibleChanges.map((c) => c.changeId));
         const hasChildren = new Set();
-        for (const change of allChanges) {
+        for (const change of visibleChanges) {
           if (change.parents) {
             for (const parent of change.parents) {
               if (changeIdSet.has(parent)) hasChildren.add(parent);
             }
           }
         }
-        return allChanges.filter((c) => !hasChildren.has(c.changeId)).map((c) => c.changeId);
+        return visibleChanges.filter((c) => !hasChildren.has(c.changeId)).map((c) => c.changeId);
       }
 
       // `git_refs()` and `git_head()` are deprecated compatibility shims.
@@ -3258,6 +3278,49 @@ class RevsetEngine {
    * @returns {Promise<Set<string>>} change IDs to exclude
    */
   async _computeHiddenOrphans(allChanges) {
+    const restoreHidden = await this._computeRestoreHidden();
+    const hidden = await this._computeUnreferencedOrphans(allChanges);
+    for (const id of restoreHidden) hidden.add(id);
+    return hidden;
+  }
+
+  /**
+   * Changes hidden by `operations.restore()` (issue #56): the head
+   * operation's `view.hiddenChanges`, minus any that the current working
+   * copy / bookmarks / tags make reachable again. Deliberately does NOT use
+   * the operation log's recorded heads for reachability -- later operations
+   * record structural heads, which would include the hidden leaf itself.
+   *
+   * @returns {Promise<Set<string>>}
+   */
+  async _computeRestoreHidden() {
+    const hidden = new Set();
+    if (!this.oplog) return hidden;
+    const headOp = await this.oplog.getHeadOperation();
+    const listed = (headOp && headOp.view && headOp.view.hiddenChanges) || [];
+    if (listed.length === 0) return hidden;
+
+    const roots = new Set([this.workingCopy.getCurrentChangeId()]);
+    await this.bookmarkStore.load();
+    for (const bookmark of await this.bookmarkStore.list()) roots.add(bookmark.changeId);
+    for (const tag of await this.tagStore.list()) roots.add(tag.changeId);
+    const reachable = new Set();
+    for (const rootId of roots) {
+      for (const id of await this.getAncestors(rootId)) reachable.add(id);
+    }
+    for (const id of listed) {
+      if (!reachable.has(id)) hidden.add(id);
+    }
+    return hidden;
+  }
+
+  /**
+   * The #37(b)/#43(2)/#48 rule: unreachable, undescribed orphans.
+   *
+   * @param {any[]} allChanges
+   * @returns {Promise<Set<string>>}
+   */
+  async _computeUnreferencedOrphans(allChanges) {
     const trackedHeads = new Set();
     try {
       const wcId = this.workingCopy && this.workingCopy.getCurrentChangeId();
@@ -8203,6 +8266,61 @@ async function createJJ(options) {
     return heads;
   };
 
+  /**
+   * Changes that `operations.restore(targetOp)` must hide (issue #56): every
+   * change created after `targetOp` (i.e. not among the heads / working copy /
+   * touched changes recorded up to targetOp, nor their ancestors) that is not
+   * reachable from the restored working copy, bookmarks or tags. Hidden, not
+   * deleted -- they reappear if a later operation makes them reachable again.
+   * Previously hidden changes that targetOp's own view already hid stay hidden.
+   *
+   * @param {any[]} ops - Full operation list (chronological)
+   * @param {any} targetOp
+   * @returns {Promise<string[]>}
+   */
+  const computeRestoreHiddenChanges = async (ops, targetOp) => {
+    await graph.load();
+    const ancestorsOf = (/** @type {Iterable<string>} */ seeds) => {
+      const seen = new Set();
+      const stack = [...seeds];
+      while (stack.length > 0) {
+        const id = /** @type {string} */ (stack.pop());
+        if (seen.has(id)) continue;
+        seen.add(id);
+        for (const parent of graph.getParents(id)) stack.push(parent);
+      }
+      return seen;
+    };
+
+    const targetIndex = ops.findIndex((o) => o.id === targetOp.id);
+    const knownSeeds = new Set();
+    for (const op of ops.slice(0, targetIndex + 1)) {
+      const view = op.view || {};
+      for (const id of view.heads || []) knownSeeds.add(id);
+      if (view.workingCopy) knownSeeds.add(view.workingCopy);
+      for (const id of Object.keys(op.changeSnapshot || {})) knownSeeds.add(id);
+    }
+    const known = ancestorsOf(knownSeeds);
+
+    const roots = new Set([workingCopy.getCurrentChangeId()]);
+    await bookmarks.load();
+    for (const bookmark of await bookmarks.list()) roots.add(bookmark.changeId);
+    for (const tag of await tags.list()) roots.add(tag.changeId);
+    const reachable = ancestorsOf(roots);
+
+    const hidden = new Set(
+      ((targetOp.view && targetOp.view.hiddenChanges) || []).filter(
+        (/** @type {string} */ id) => !reachable.has(id)
+      )
+    );
+    for (const change of graph.getAll()) {
+      if (!known.has(change.changeId) && !reachable.has(change.changeId)) {
+        hidden.add(change.changeId);
+      }
+    }
+    return [...hidden];
+  };
+
   /**
    * Re-parent every child of `changeId` onto `newParents` instead — used
    * when a change is being elided from the graph (abandon(), issue #30;
@@ -9330,6 +9448,27 @@ async function createJJ(options) {
         await conflicts.addConflict(conflict);
       }
 
+      // The rebased change's content, path by path: (new base) + (what the
+      // change itself did relative to its old base), as jj's rebase. It
+      // used to keep its own full tree verbatim — keeping every file only
+      // the OLD base had and never picking up what only the NEW base
+      // changed. A path both sides changed differently keeps the change's
+      // own value here; if that's a real conflict, detectConflicts() above
+      // reported it and the marker text below replaces it.
+      const contentChanged = Boolean(oldParentChange);
+      if (oldParentChange) {
+        /** @type {Record<string, string>} */
+        const rebased = {};
+        const allPaths = new Set([...baseFiles.keys(), ...leftFiles.keys(), ...rightFiles.keys()]);
+        for (const filePath of allPaths) {
+          const baseValue = baseFiles.get(filePath);
+          const ownValue = leftFiles.get(filePath);
+          const value = ownValue === baseValue ? rightFiles.get(filePath) : ownValue;
+          if (value !== undefined) rebased[filePath] = value;
+        }
+        change.fileSnapshot = rebased;
+      }
+
       // Materialize real conflict-marker text into the moved change's file
       // content — issue #43(3): rebase()/moveChange() used to record the
       // conflict correctly as DATA (via conflicts.addConflict() above) but
@@ -9371,6 +9510,13 @@ async function createJJ(options) {
         }
       }
 
+      // A checked-out change's files on disk are its content: bring them in
+      // line with the rebased snapshot (markers included), tracked, so the
+      // next command's auto-snapshot finds nothing to re-record.
+      if (contentChanged && changeId === workingCopy.getCurrentChangeId()) {
+        await syncWorkingCopyFiles(change.fileSnapshot || {});
+      }
+
       // Update parent
       change.parents = [newParent];
       await graph.updateChange(change);
@@ -9509,6 +9655,11 @@ async function createJJ(options) {
      * @param {Record<string, any>} [args]
      */
     async describe(args = {}) {
+      // Documented option is `changeId`; `revision` is the older spelling.
+      if (args.changeId && !args.revision) {
+        args = { ...args, revision: args.changeId };
+      }
+
       await graph.load();
       await workingCopy.load();
       await userConfig.load();
@@ -9658,10 +9809,13 @@ async function createJJ(options) {
      * @returns {Promise<Object>} Updated change object
      */
     async metaedit(args = {}) {
-      // Normalize: accept 'change' as alias for 'revision'
+      // Normalize: accept 'change' / 'changeId' as aliases for 'revision'
       if (args.change && !args.revision) {
         args = { ...args, revision: args.change };
       }
+      if (args.changeId && !args.revision) {
+        args = { ...args, revision: args.changeId };
+      }
 
       // Normalize: accept 'message' as alias for 'description'
       if (args.message && !args.description) {
@@ -10354,29 +10508,18 @@ async function createJJ(options) {
       // see issue #29.
       const fileSnapshotBeforeSwitch = await snapshotFilesystem();
 
-      // CRITICAL FIX: Clean working directory BEFORE snapshotting to prevent cross-branch pollution
-      // Remove files that don't belong to the current changeId before we snapshot it
+      // Commit the change being left: every tracked file on disk is its
+      // content, as in new()/describe(). This used to first DELETE every
+      // tracked file missing from the change's recorded fileSnapshot, as
+      // "pollution" from an earlier checkout — but a switch now fully syncs
+      // the working directory to its target (issue #30, below), so nothing
+      // leaks that way any more, and what that cleanup actually deleted was
+      // every new file write() had created in this change: write() tracks a
+      // file without recording it in the change, so it is only committed
+      // here, by the next command.
       if (previousChangeId !== args.changeId) {
         const previousChange = await graph.getChange(previousChangeId);
         if (previousChange) {
-          const previousSnapshot = previousChange.fileSnapshot || {};
-          const workingDirFiles = await workingCopy.listFiles();
-
-          // Delete files that exist in working dir but NOT in previous changeId's snapshot
-          // This removes pollution from other branches that were previously checked out
-          for (const filePath of workingDirFiles) {
-            if (!previousSnapshot[filePath]) {
-              try {
-                const fullPath = join(dir, filePath);
-                await fs.promises.unlink(fullPath);
-                await workingCopy.untrackFile(filePath);
-              } catch (error) {
-                // Ignore errors - file might already be deleted or inaccessible
-              }
-            }
-          }
-
-          // Now snapshot the CLEAN working directory (no pollution!)
           const currentSnapshot = await snapshotFilesystem();
           if (currentSnapshot && Object.keys(currentSnapshot).length > 0) {
             changeSnapshot[previousChangeId] = structuredClone(previousChange);
@@ -10600,7 +10743,11 @@ async function createJJ(options) {
         redoFileSnapshot,
         redoConflictsSnapshot,
         parents: [],
-        view: { ...landingView, fileSnapshot: diskSnapshotBeforeThisOp },
+        view: {
+          ...landingView,
+          fileSnapshot: diskSnapshotBeforeThisOp,
+          hiddenChanges: landingView.hiddenChanges || [],
+        },
       });
 
       const restoredFileCount =
@@ -10723,7 +10870,11 @@ async function createJJ(options) {
         redoOf: undoOp.id,
         changeSnapshot: undoChangeSnapshot,
         parents: [],
-        view: { ...redoneView, fileSnapshot: diskSnapshotBeforeThisOp },
+        view: {
+          ...redoneView,
+          fileSnapshot: diskSnapshotBeforeThisOp,
+          hiddenChanges: redoneView.hiddenChanges || [],
+        },
       });
 
       const restoredFileCount =
@@ -11055,6 +11206,13 @@ async function createJJ(options) {
 
         await applyGraphReversal(reversal);
 
+        // Restoring the view hides (not deletes) every change that was
+        // created after targetOp and is not reachable from the restored
+        // working copy / bookmarks / tags -- see issue #56. The list is
+        // recorded in the view so it survives later operations, and so
+        // undo()/redo() of the restore bring the changes back.
+        const hiddenChanges = await computeRestoreHiddenChanges(ops, targetOp);
+
         // Record this restoration as a new operation
         await oplog.recordOperation({
           timestamp: new Date().toISOString(),
@@ -11062,7 +11220,7 @@ async function createJJ(options) {
           description: `restore to operation ${args.operation}`,
           parents: [],
           changeSnapshot,
-          view: { ...targetOp.view, fileSnapshot: diskSnapshotBeforeThisOp },
+          view: { ...targetOp.view, fileSnapshot: diskSnapshotBeforeThisOp, hiddenChanges },
         });
 
         return {
@@ -11681,6 +11839,9 @@ async function createJJ(options) {
       }
 
       await graph.load();
+      // Both outcomes below record the working copy in their operation —
+      // a fresh instance hasn't loaded it yet.
+      await workingCopy.load();
       await userConfig.load();
       const siblings = graph.getDivergentSiblings(changeId);