refactor(fmt): switch LSP server to full document sync

Author: fi3ework

packages/rstack/THIRD_PARTY_NOTICES.md

@@ -499,34 +499,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-## vscode-languageserver-textdocument
-
-The language server started by `rs fmt --lsp` includes bundled code from
-[vscode-languageserver-textdocument](https://github.com/microsoft/vscode-languageserver-node).
-
-License: MIT
-
-Copyright (c) Microsoft Corporation
-
-All rights reserved.
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED _AS IS_, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

packages/rstack/src/fmt/lsp/minimalEdit.ts

@@ -90,5 +90,50 @@ const computeMinimalEdit = (source: string, formatted: string): MinimalEdit | un
   };
 };
 
-export { computeMinimalEdit };
-export type { MinimalEdit };
+/** An LSP position; `character` counts UTF-16 code units, like JS offsets. */
+interface Position {
+  line: number;
+  character: number;
+}
+
+/** A minimal edit expressed as the LSP range/newText the editor applies. */
+interface MinimalTextEdit {
+  range: { start: Position; end: Position };
+  newText: string;
+}
+
+/**
+ * Reduces a reformat to the single LSP text edit that actually changed.
+ *
+ * The offset → position mapping only counts line feeds because LSP characters
+ * and JS offsets share the UTF-16 unit, and because `computeMinimalEdit` never
+ * places a boundary inside a surrogate pair or a `\r\n`.
+ */
+const computeMinimalTextEdit = (source: string, formatted: string): MinimalTextEdit | undefined => {
+  const edit = computeMinimalEdit(source, formatted);
+  if (!edit) {
+    return undefined;
+  }
+
+  let line = 0;
+  let lineStart = 0;
+  // Resumes from the previous call's line, so start and end share one scan.
+  const advanceTo = (offset: number): Position => {
+    let lineFeed = source.indexOf('\n', lineStart);
+    while (lineFeed !== -1 && lineFeed < offset) {
+      line++;
+      lineStart = lineFeed + 1;
+      lineFeed = source.indexOf('\n', lineStart);
+    }
+
+    return { line, character: offset - lineStart };
+  };
+
+  const start = advanceTo(edit.start);
+  const end = advanceTo(edit.end);
+
+  return { range: { start, end }, newText: edit.newText };
+};
+
+export { computeMinimalEdit, computeMinimalTextEdit };
+export type { MinimalEdit, MinimalTextEdit };

packages/rstack/src/fmt/lsp/server.ts

@@ -1,11 +1,10 @@
 import { fileURLToPath } from 'node:url';
 import { inspect } from 'node:util';
-import { TextDocument } from 'vscode-languageserver-textdocument';
 import {
   createConnection,
   MessageType,
   ShowMessageNotification,
-  TextDocuments,
+  TextDocumentSyncKind,
   type Connection,
   type InitializeParams,
   type TextEdit,
@@ -20,7 +19,7 @@ import { formatFmtSource } from '../format.ts';
 import { createIgnoreMatcher, type IgnorePredicate } from '../ignore.ts';
 import type { FmtPluginResolver } from '../plugins.ts';
 import type { ResolvedFmtConfig } from '../types.ts';
-import { computeMinimalEdit } from './minimalEdit.ts';
+import { computeMinimalTextEdit } from './minimalEdit.ts';
 
 interface RunFmtLspOptions {
   /** Base for relative CLI paths, and the workspace root when the client reports none. */
@@ -146,41 +145,27 @@ const formatDocumentSource = async (
 /**
  * Turns a reformat of an open buffer into the edit the editor applies.
  *
- * `TextDocuments` mutates the same document instance on every change, so the
- * buffer can move on while the formatter runs. The text is snapshotted up
- * front and the version is re-checked afterwards, which keeps the returned
- * positions describing the text the edit was computed from.
+ * The client can replace the buffer while the formatter runs, so the text is
+ * re-read afterwards: the edit stays valid exactly as long as the text it was
+ * computed from is still the text the client holds.
  */
 const createDocumentEdits = async (
-  document: TextDocument,
+  getText: () => string | undefined,
   format: (source: string) => Promise<string | undefined>,
 ): Promise<TextEdit[]> => {
-  const { version } = document;
-  const source = document.getText();
-  const formatted = await format(source);
-  // Edits for a buffer the client has already changed would be applied to text
-  // they were never computed for; the editor formats again after the change.
-  if (document.version !== version) {
+  const source = getText();
+  if (source === undefined) {
     return [];
   }
 
-  const edit = formatted === undefined ? undefined : computeMinimalEdit(source, formatted);
-  if (!edit) {
+  const formatted = await format(source);
+  if (getText() !== source) {
     return [];
   }
 
-  // Nothing awaits between the version check and this mapping, so the document
-  // still holds `source` and its incrementally maintained line table maps the
-  // offsets without rebuilding one from scratch.
-  return [
-    {
-      range: {
-        start: document.positionAt(edit.start),
-        end: document.positionAt(edit.end),
-      },
-      newText: edit.newText,
-    },
-  ];
+  const edit = formatted === undefined ? undefined : computeMinimalTextEdit(source, formatted);
+
+  return edit ? [edit] : [];
 };
 
 const startFmtLsp = (options: RunFmtLspOptions, onExit: () => void): void => {
@@ -193,8 +178,27 @@ const startFmtLsp = (options: RunFmtLspOptions, onExit: () => void): void => {
   // raw bytes into the JSON-RPC stream and break the client's framing parser.
   // This runs before any user code can load.
   redirectConsoleToConnection(connection);
-  // Document sync also maps offsets to UTF-16 positions for the returned edits.
-  const documents = new TextDocuments(TextDocument);
+  // Full document sync: every change carries the whole buffer, so tracking a
+  // document is replacing one string, and a dropped or reordered change heals
+  // on the next one.
+  const documents = new Map<string, string>();
+
+  connection.onDidOpenTextDocument(({ textDocument }) => {
+    documents.set(textDocument.uri, textDocument.text);
+  });
+  connection.onDidChangeTextDocument(({ textDocument, contentChanges }) => {
+    const change = contentChanges[0];
+    if (change) {
+      documents.set(textDocument.uri, change.text);
+    } else {
+      // An empty change list is a protocol violation; dropping the entry keeps
+      // stale text from standing in for the buffer until the next change.
+      documents.delete(textDocument.uri);
+    }
+  });
+  connection.onDidCloseTextDocument(({ textDocument }) => {
+    documents.delete(textDocument.uri);
+  });
 
   let root = options.cwd;
   let sessionPromise: Promise<FmtLspSession> | undefined;
@@ -229,17 +233,18 @@ const startFmtLsp = (options: RunFmtLspOptions, onExit: () => void): void => {
 
     return {
       // The project config is the single source of truth, so client formatting
-      // options are ignored. The connection fills in incremental
-      // `textDocumentSync` for the `TextDocuments` listener; nothing else is
-      // advertised.
-      capabilities: { documentFormattingProvider: true },
+      // options are ignored and nothing beyond formatting is advertised. Full
+      // sync spares the client from computing deltas the server never uses.
+      capabilities: {
+        documentFormattingProvider: true,
+        textDocumentSync: TextDocumentSyncKind.Full,
+      },
     };
   });
 
   connection.onDocumentFormatting(async ({ textDocument }): Promise<TextEdit[]> => {
-    const document = documents.get(textDocument.uri);
     const filePath = toFilePath(textDocument.uri);
-    if (!document || !filePath) {
+    if (!filePath) {
       return [];
     }
 
@@ -248,16 +253,16 @@ const startFmtLsp = (options: RunFmtLspOptions, onExit: () => void): void => {
     try {
       const session = await getSession();
 
-      return await createDocumentEdits(document, (source) =>
-        formatDocumentSource(session, filePath, source),
+      return await createDocumentEdits(
+        () => documents.get(textDocument.uri),
+        (source) => formatDocumentSource(session, filePath, source),
       );
     } catch (error) {
       connection.console.error(`Failed to format "${filePath}": ${String(error)}`);
       return [];
     }
   });
 
-  documents.listen(connection);
   connection.listen();
 };
 

packages/rstack/tests/cli/fmt/lsp.test.ts

@@ -48,9 +48,9 @@ test(
       const { capabilities } = await client.initialize();
 
       expect(capabilities.documentFormattingProvider).toBe(true);
-      // Incremental sync, filled in by the connection for the `TextDocuments`
-      // listener; without it compliant clients would never send the document.
-      expect(capabilities.textDocumentSync).toBe(2);
+      // Full document sync; without a sync capability compliant clients would
+      // never send the document.
+      expect(capabilities.textDocumentSync).toBe(1);
       expect(capabilities.documentRangeFormattingProvider).toBeUndefined();
       expect(capabilities.documentOnTypeFormattingProvider).toBeUndefined();
     });
@@ -94,20 +94,15 @@ test(
 );
 
 test(
-  'formats incremental changes sent by the client',
+  'formats changes sent by the client',
   async () => {
     await withLspServer(async (client) => {
       await client.initialize();
       const uri = openDocument(client, 'src/index.ts', 'const x = 1;\n');
-      // Replaces ` = 1` with `=2`, leaving `const x=2;` in the buffer.
+      // Full document sync: the change carries the whole new buffer.
       client.notify('textDocument/didChange', {
         textDocument: { uri, version: 2 },
-        contentChanges: [
-          {
-            range: { start: { line: 0, character: 7 }, end: { line: 0, character: 11 } },
-            text: '=2',
-          },
-        ],
+        contentChanges: [{ text: 'const x=2;\n' }],
       });
 
       const edits = await client.formatDocument(uri);

packages/rstack/tests/fmt/lsp/server.test.ts

@@ -1,14 +1,11 @@
 import { expect, test } from 'rstack/test';
-import { TextDocument } from 'vscode-languageserver-textdocument';
 import { createDocumentEdits } from '../../../src/fmt/lsp/server.ts';
 
-const createDocument = (text: string): TextDocument =>
-  TextDocument.create('file:///src/index.ts', 'typescript', 1, text);
-
 test('maps the edit onto the formatted document', async () => {
-  const document = createDocument('const a = 1;\nconst b=2;\n');
-
-  const edits = await createDocumentEdits(document, async () => 'const a = 1;\nconst b = 2;\n');
+  const edits = await createDocumentEdits(
+    () => 'const a = 1;\nconst b=2;\n',
+    async () => 'const a = 1;\nconst b = 2;\n',
+  );
 
   expect(edits).toEqual([
     {
@@ -19,24 +16,36 @@ test('maps the edit onto the formatted document', async () => {
 });
 
 test('returns no edits for an already formatted document', async () => {
-  const document = createDocument('const a = 1;\n');
+  const getText = () => 'const a = 1;\n';
 
-  expect(await createDocumentEdits(document, async () => 'const a = 1;\n')).toEqual([]);
-  expect(await createDocumentEdits(document, async () => undefined)).toEqual([]);
+  expect(await createDocumentEdits(getText, async () => 'const a = 1;\n')).toEqual([]);
+  expect(await createDocumentEdits(getText, async () => undefined)).toEqual([]);
 });
 
-// `TextDocuments` mutates the document in place, so a change arriving while the
-// formatter runs would otherwise be mapped through the new line table.
+test('returns no edits for a document that is not open', async () => {
+  expect(
+    await createDocumentEdits(
+      () => undefined,
+      async () => '',
+    ),
+  ).toEqual([]);
+});
+
+// The client can replace the buffer while the formatter runs; an edit computed
+// from the old text must not reach the new one.
 test('returns no edits when the document changes while it is formatted', async () => {
-  const document = createDocument('const a = 1;\nconst b=2;\n');
+  let text = 'const a = 1;\nconst b=2;\n';
 
-  const edits = await createDocumentEdits(document, async (source) => {
-    TextDocument.update(document, [{ text: 'const b=2;\n' }], 2);
+  const edits = await createDocumentEdits(
+    () => text,
+    async (source) => {
+      text = 'const b=2;\n';
 
-    return source.replace('const b=2;', 'const b = 2;');
-  });
+      return source.replace('const b=2;', 'const b = 2;');
+    },
+  );
 
-  // Without the version check this returns an edit for line 1, which the
+  // Without the staleness check this returns an edit for line 1, which the
   // shortened buffer no longer holds.
   expect(edits).toEqual([]);
 });