Merge branch dev into published

Author: PEZ

CHANGELOG.md

@@ -4,6 +4,11 @@ Changes to Calva.
 
 ## [Unreleased]
 
+## [2.0.588] - 2026-05-15
+
+- [Make API clojure editing independent of a `TextEditor` instance](https://github.com/BetterThanTomorrow/calva/issues/3220)
+- Bump deps.clj to v1.12.5.1638
+
 ## [2.0.587] - 2026-05-10
 
 - Fix: [The structural editor fails in some API usage scenarios](https://github.com/BetterThanTomorrow/calva/issues/3218)

deps-clj-version

@@ -1 +1 @@
-v1.12.4.1618
+v1.12.5.1638

deps.clj.jar

@@ -351,10 +351,16 @@ The `ranges` module contains functions for retreiving [vscode.Range](https://cod
 All functions in this module have the following TypeScript signature:
 
 ```typescript
-(editor = vscode.window.activeTextEditor, position = editor?.selection?.active) => [vscode.Range, string];
+(editorOrDocument?: vscode.TextEditor | vscode.TextDocument, position?: vscode.Position) => [vscode.Range, string];
 ```
 
-I.e. they expect a [vscode.TextEditor](https://code.visualstudio.com/api/references/vscode-api#TextEditor) – defaulting to the currently active editor – and a [vscode.Position](https://code.visualstudio.com/api/references/vscode-api#Position) – defaulting to the current active position in the editor (or the first active position if multiple selections/positions exist, and will return a tuple with the range, and the text for the piece of interest requested.
+They can be called in three ways:
+
+* **No arguments**: uses the active text editor’s document and cursor position.
+* **A `TextEditor`**: uses its document and primary cursor position (or the given `position` if provided).
+* **A `TextDocument` + `Position`**: uses them directly — no visible editor required. This is useful for programmatic/API usage where you have a document reference but no open editor tab.
+
+All variants return a tuple with the range and the text for the piece of interest requested.
 
 !!! Note "Custom REPL Commands"
     The `ranges` function have corresponding [REPL Snippets/Commands](custom-commands.md) substitution variables. It is the same implementation functions used in both cases.
@@ -402,6 +408,17 @@ _Corresponding [REPL Snippet](custom-commands.md) variable: `$top-level-defined-
       ...)
     ```
 
+=== "Joyride (with TextDocument + Position)"
+
+    ```clojure
+    ;; Query a form without the file being open in an editor
+    (p/let [uri (vscode/Uri.file "/path/to/file.clj")
+            doc (vscode/workspace.openTextDocument uri)
+            pos (vscode/Position. 5 0)
+            [range text] (calva/ranges.currentTopLevelForm doc pos)]
+      (println "Form at line 5:" text))
+    ```
+
 === "ClojureScript"
 
     ```clojure
@@ -421,12 +438,14 @@ The `editor` module has facilites (well, a facility, so far) for editing Clojure
 
 ### `editor.replace()`
 
-With `editor.replace()` you can replace a range in a Clojure editor with new text. The arguments are:
+With `editor.replace()` you can replace a range in a Clojure document with new text. The arguments are:
 
-* `editor`, a `vscode.TextEditor`
+* `editorOrDocument`, a `vscode.TextEditor` or a `vscode.TextDocument`
 * `range`, a `vscode.Range`
 * `newText`, a string
 
+When a `TextEditor` is provided, the edit uses `TextEditor.edit()` with undo grouping and formatting. When a `TextDocument` is provided, the edit uses `WorkspaceEdit` — no visible editor is required, making it suitable for programmatic edits from other extensions.
+
 === "Joyride"
 
     ```clojure
@@ -437,6 +456,19 @@ With `editor.replace()` you can replace a range in a Clojure editor with new tex
                    (println "Error replacing text:" e))))
     ```
 
+=== "Joyride (editor-free)"
+
+    ```clojure
+    ;; Edit a document without opening it in an editor
+    (-> (p/let [uri (vscode/Uri.file "/path/to/file.clj")
+                doc (vscode/workspace.openTextDocument uri)
+                range (vscode/Range. (vscode/Position. 2 0) (vscode/Position. 2 9))
+                _ (calva/editor.replace doc range "(def a 42)")]
+          (println "Text replaced without opening an editor!"))
+        (p/catch (fn [e]
+                   (println "Error replacing text:" e))))
+    ```
+
 === "JavaScript"
 
     ```javascript

docs/site/api.md

@@ -3,7 +3,7 @@
   "displayName": "Calva: Clojure & ClojureScript Interactive Programming",
   "description": "Integrated REPL, formatter, Paredit, and more. Powered by cider-nrepl and clojure-lsp.",
   "icon": "assets/calva.png",
-  "version": "2.0.587",
+  "version": "2.0.588",
   "publisher": "betterthantomorrow",
   "author": {
     "name": "Better Than Tomorrow",

package-lock.json

@@ -1,15 +1,24 @@
 import * as vscode from 'vscode';
 import * as getText from '../util/get-text';
+import { resolveDocAndPos } from '../util/resolve-doc-and-pos';
 
+/**
+ * Wraps a `(document, position) => [Range, string]` function so it can be called with:
+ * - No arguments: uses the active text editor's document and cursor position.
+ * - A `TextEditor`: uses its document and primary cursor position.
+ * - A `TextDocument` + `Position`: uses them directly, no visible editor required.
+ *
+ * Returns `[undefined, undefined]` when no document/position can be resolved.
+ */
 const wrapSelectionAndTextFunction = (
   f: (document: vscode.TextDocument, position: vscode.Position) => [vscode.Range, string]
 ) => {
-  return (editor = vscode.window.activeTextEditor, position = editor?.selections?.[0]?.active) => {
-    if (editor && position && editor.document && editor.document.languageId === 'clojure') {
-      return f(editor.document, position);
-    } else {
+  return (editorOrDoc?: vscode.TextEditor | vscode.TextDocument, position?: vscode.Position) => {
+    const resolved = resolveDocAndPos(editorOrDoc, position, vscode.window.activeTextEditor);
+    if (!resolved) {
       return [undefined, undefined];
     }
+    return f(resolved.doc as vscode.TextDocument, resolved.pos as vscode.Position);
   };
 };
 

package.json

@@ -241,13 +241,48 @@ export class DocumentModel implements EditableModel {
     );
   }
 
+  private applyViaWorkspaceEdit(modelEdits: ModelEdit<ModelEditFunction>[]): Thenable<boolean> {
+    const doc = this.document.document;
+    const wsEdit = new vscode.WorkspaceEdit();
+    for (const modelEdit of modelEdits) {
+      switch (modelEdit.editFn) {
+        case 'insertString': {
+          const [offset, text] = modelEdit.args as documentModel.ModelEditArgs<'insertString'>;
+          wsEdit.insert(doc.uri, doc.positionAt(offset), text);
+          break;
+        }
+        case 'changeRange': {
+          const [start, end, text] = modelEdit.args as documentModel.ModelEditArgs<'changeRange'>;
+          const range = new vscode.Range(doc.positionAt(start), doc.positionAt(end));
+          wsEdit.replace(doc.uri, range, text);
+          break;
+        }
+        case 'deleteRange': {
+          const [offset, count] = modelEdit.args as documentModel.ModelEditArgs<'deleteRange'>;
+          const range = new vscode.Range(doc.positionAt(offset), doc.positionAt(offset + count));
+          wsEdit.delete(doc.uri, range);
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    this.staleDocumentVersion = this.documentVersion;
+    return vscode.workspace.applyEdit(wsEdit);
+  }
+
   edit(modelEdits: ModelEdit<ModelEditFunction>[], options: ModelEditOptions): Thenable<boolean> {
     // undoStopBefore===false joins this edit with the prior one in a single undoable unit.
     const undoStopBefore = !(options.undoStopBefore === false);
     // Nothing to do?
     if (!modelEdits || modelEdits.length == 0) {
       return Promise.resolve(true);
     }
+    // Editor-free path: when no formatting, no selections, and no explicit editor,
+    // use WorkspaceEdit which only needs a document URI (no visible editor required).
+    if (options.skipFormat && !options.selections && !options.editor) {
+      return this.applyViaWorkspaceEdit(modelEdits);
+    }
     // Reformatting will retouch the spots affected by edits.
     // The edits are stated in terms of the document-as-it-is, before any of the edits.
     // Reformat's offsets must be in post-edit terms (i.e., "a later as-is", before reformatting).

src/api/ranges.ts

@@ -7,6 +7,7 @@ import * as printer from './printer';
 import * as paredit from './cursor-doc/paredit';
 import * as format from './calva-fmt/src/format';
 import * as commentPrefix from './comment-prefix';
+import { isTextEditor } from './util/editor-utils';
 
 type CandidatesMap = Map<number, number[]>;
 
@@ -612,13 +613,26 @@ export async function toggleLineCommentCommand(behaviorArg?: ToggleCommentBehavi
   );
 }
 
+/**
+ * Replaces text in a Clojure document within the given range.
+ *
+ * @param editorOrDocument When a `TextEditor` is provided, uses `TextEditor.edit()`
+ *   with undo grouping, formatting, and selection restoration (the interactive editing path).
+ *   When a `TextDocument` is provided, uses `WorkspaceEdit` via `vscode.workspace.applyEdit()`,
+ *   which requires no visible editor and causes no UI side effects — suitable for
+ *   programmatic/API edits. Formatting is automatically skipped since it requires a visible editor.
+ * @param range The document range to replace.
+ * @param newText The replacement text.
+ * @param options Edit options forwarded to `DocumentModel.edit()`.
+ */
 export function replace(
-  editor: vscode.TextEditor,
+  editorOrDocument: vscode.TextEditor | vscode.TextDocument,
   range: vscode.Range,
   newText: string,
   options = {}
 ) {
-  const document = editor.document;
+  const hasEditor = isTextEditor(editorOrDocument);
+  const document = hasEditor ? editorOrDocument.document : editorOrDocument;
   const mirrorDoc: model.EditableDocument = docMirror.getDocument(document);
   return mirrorDoc.model.edit(
     [
@@ -633,7 +647,9 @@ export function replace(
         undoStopBefore: true,
       },
       ...options,
-      editor,
+      // Without a TextEditor, formatting and selection restoration can't work,
+      // so force skipFormat to route through WorkspaceEdit.
+      ...(hasEditor ? { editor: editorOrDocument } : { skipFormat: true }),
     }
   );
 }

src/doc-mirror/index.ts

@@ -4,6 +4,7 @@ import * as testUtil from './util';
 import * as vscode from 'vscode';
 import * as edit from '../../../edit';
 import * as docMirror from '../../../doc-mirror';
+import * as ranges from '../../../api/ranges';
 
 const suiteName = 'Edit Replace Suite';
 
@@ -104,4 +105,142 @@ suite(suiteName, function () {
       'Active editor content should be unchanged'
     );
   });
+
+  suite('Editor-less API', function () {
+    async function openDocWithMirror(): Promise<vscode.TextDocument> {
+      const doc = await vscode.workspace.openTextDocument(vscode.Uri.file(targetFilePath));
+      await testUtil.waitForCondition(
+        () => {
+          try {
+            docMirror.getDocument(doc);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        4000,
+        50,
+        'Timed out waiting for mirror document (no editor)'
+      );
+      return doc;
+    }
+
+    test('edit.replace applies edit via TextDocument', async function () {
+      const targetDoc = await openDocWithMirror();
+
+      const range = new vscode.Range(
+        new vscode.Position(2, 0),
+        new vscode.Position(2, '(def a 1)'.length)
+      );
+      const result = await edit.replace(targetDoc, range, '(def a 42)', {
+        skipFormat: true,
+      });
+
+      assert.strictEqual(result, true, 'edit.replace should return true');
+      const content = targetDoc.getText();
+      assert.ok(content.includes('(def a 42)'), `Should contain replacement. Got: ${content}`);
+      assert.ok(!content.includes('(def a 1)'), `Should not contain original. Got: ${content}`);
+    });
+
+    test('ranges.currentForm resolves with TextDocument + Position', async function () {
+      const targetDoc = await openDocWithMirror();
+
+      // Position on the opening paren — currentForm returns the whole list
+      const pos = new vscode.Position(2, 0);
+      const [formRange, formText] = ranges.currentForm(targetDoc, pos);
+      assert.ok(formRange, 'should return a range');
+      assert.strictEqual(formText, '(def a 1)', `should return the form. Got: ${formText}`);
+    });
+
+    test('ranges.currentTopLevelForm resolves with TextDocument + Position', async function () {
+      const targetDoc = await openDocWithMirror();
+
+      // Position inside a symbol — currentTopLevelForm still returns the enclosing def
+      const pos = new vscode.Position(2, 5);
+      const [formRange, formText] = ranges.currentTopLevelForm(targetDoc, pos);
+      assert.ok(formRange, 'should return a range');
+      assert.strictEqual(
+        formText,
+        '(def a 1)',
+        `should return the top-level form. Got: ${formText}`
+      );
+    });
+
+    test('ranges.currentEnclosingForm resolves with TextDocument + Position', async function () {
+      const targetDoc = await openDocWithMirror();
+
+      // Position on symbol 'a' — enclosing form is (def a 1)
+      const pos = new vscode.Position(2, 5);
+      const [formRange, formText] = ranges.currentEnclosingForm(targetDoc, pos);
+      assert.ok(formRange, 'should return a range');
+      assert.strictEqual(
+        formText,
+        '(def a 1)',
+        `should return the enclosing form. Got: ${formText}`
+      );
+    });
+
+    test('edit then ranges: doc mirror reflects the edit', async function () {
+      const targetDoc = await openDocWithMirror();
+
+      // Replace (def a 1) with (def a 42)
+      const range = new vscode.Range(
+        new vscode.Position(2, 0),
+        new vscode.Position(2, '(def a 1)'.length)
+      );
+      await edit.replace(targetDoc, range, '(def a 42)', { skipFormat: true });
+
+      // Range query on the edited content should see the new form
+      const pos = new vscode.Position(2, 0);
+      const [, formText] = ranges.currentForm(targetDoc, pos);
+      assert.strictEqual(
+        formText,
+        '(def a 42)',
+        `After edit, form should be updated. Got: ${formText}`
+      );
+    });
+
+    test('edit.replace edits the target document, not the active editor', async function () {
+      const targetDoc = await openDocWithMirror();
+
+      // Open a different file as the active editor
+      const otherDoc = await vscode.workspace.openTextDocument(vscode.Uri.file(otherFilePath));
+      await vscode.window.showTextDocument(otherDoc, {
+        viewColumn: vscode.ViewColumn.One,
+        preview: false,
+      });
+      await testUtil.waitForCondition(
+        () => vscode.window.activeTextEditor?.document.uri.fsPath === otherFilePath,
+        4000,
+        50,
+        'Timed out waiting for other file to become active'
+      );
+
+      const otherContentBefore = vscode.window.activeTextEditor.document.getText();
+
+      // Edit the target via TextDocument (no skipFormat — the exact scenario that was buggy)
+      const range = new vscode.Range(
+        new vscode.Position(2, 0),
+        new vscode.Position(2, '(def a 1)'.length)
+      );
+      const result = await edit.replace(targetDoc, range, '(def a 42)');
+
+      assert.strictEqual(result, true, 'edit.replace should return true');
+
+      // Target document should have the edit
+      const targetContent = targetDoc.getText();
+      assert.ok(
+        targetContent.includes('(def a 42)'),
+        `Target should contain replacement. Got: ${targetContent}`
+      );
+
+      // Active editor's document should be untouched
+      const otherContentAfter = vscode.window.activeTextEditor.document.getText();
+      assert.strictEqual(
+        otherContentAfter,
+        otherContentBefore,
+        'Active editor content should be unchanged when editing via TextDocument'
+      );
+    });
+  });
 });