@mrclrchtr/supi-lsp 7.3.1 → 8.0.0

package/src/client/client-document-sync.ts

@@ -1,5 +1,8 @@
 import { readFileSync } from "node:fs";
-import type { VersionedTextDocumentIdentifier } from "../config/types.ts";
+import {
+  TextDocumentSyncKind,
+  type VersionedTextDocumentIdentifier,
+} from "vscode-languageserver-protocol";
 import type { DiagnosticSynchronization } from "./client-diagnostic-evidence.ts";
 import type { DiagnosticWaitRegistry } from "./client-diagnostic-waiters.ts";
 import { fingerprintDocumentContent, type OpenDocumentState } from "./client-document-state.ts";
@@ -7,6 +10,59 @@ import { getDiagnosticFileState } from "./client-file-state.ts";
 
 type NotificationSender = (method: string, params: unknown) => void;
 
+/** Normalized document lifecycle options negotiated with one LSP server. */
+export interface NormalizedDocumentSync {
+  readonly openClose: boolean;
+  readonly change: TextDocumentSyncKind;
+  readonly save: boolean;
+  readonly includeText: boolean;
+}
+
+const NO_DOCUMENT_SYNC: NormalizedDocumentSync = Object.freeze({
+  openClose: false,
+  change: TextDocumentSyncKind.None,
+  save: false,
+  includeText: false,
+});
+
+/**
+ * Normalize structured and legacy numeric server synchronization options.
+ * Legacy non-none values use the historical full lifecycle defaults.
+ */
+export function normalizeDocumentSync(value: unknown): NormalizedDocumentSync {
+  if (value === TextDocumentSyncKind.None) return NO_DOCUMENT_SYNC;
+  if (value === TextDocumentSyncKind.Full || value === TextDocumentSyncKind.Incremental) {
+    return Object.freeze({
+      openClose: true,
+      change: value,
+      save: true,
+      includeText: false,
+    });
+  }
+  if (!isRecord(value)) return NO_DOCUMENT_SYNC;
+
+  const change = isTextDocumentSyncKind(value.change) ? value.change : TextDocumentSyncKind.None;
+  const save = value.save === true || isRecord(value.save);
+  return Object.freeze({
+    openClose: value.openClose === true,
+    change,
+    save,
+    includeText: isRecord(value.save) && value.save.includeText === true,
+  });
+}
+
+function isTextDocumentSyncKind(value: unknown): value is TextDocumentSyncKind {
+  return (
+    value === TextDocumentSyncKind.None ||
+    value === TextDocumentSyncKind.Full ||
+    value === TextDocumentSyncKind.Incremental
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 interface SynchronizeDocumentOptions {
   uri: string;
   content: string;
@@ -14,7 +70,7 @@ interface SynchronizeDocumentOptions {
   version: number;
   synchronizationId: number;
   evidenceRevision: number;
-  incrementalSync: boolean;
+  documentSync: NormalizedDocumentSync;
   waiters: DiagnosticWaitRegistry;
   sendNotification: NotificationSender;
 }
@@ -31,9 +87,9 @@ function endPosition(content: string): { line: number; character: number } {
 function contentChanges(
   previousContent: string,
   content: string,
-  incrementalSync: boolean,
+  change: TextDocumentSyncKind,
 ): unknown[] {
-  if (incrementalSync) {
+  if (change === TextDocumentSyncKind.Incremental) {
     return [
       {
         range: {
@@ -64,10 +120,11 @@ export function synchronizeDocument(options: SynchronizeDocumentOptions): void {
   const changes = contentChanges(
     options.document.content,
     options.content,
-    options.incrementalSync,
+    options.documentSync.change,
   );
   options.document.content = options.content;
   options.document.contentFingerprint = fingerprintDocumentContent(options.content);
+  if (options.documentSync.change === TextDocumentSyncKind.None) return;
   options.sendNotification("textDocument/didChange", {
     textDocument: {
       uri: options.uri,
@@ -98,7 +155,7 @@ export function synchronizeTrackedDocument(options: {
   nextVersion(): number;
   nextSynchronizationId(): number;
   evidenceRevision: number;
-  incrementalSync: boolean;
+  documentSync: NormalizedDocumentSync;
   waiters: DiagnosticWaitRegistry;
   sendNotification: NotificationSender;
   markUnversionedSyncMoment?(): void;
@@ -117,7 +174,7 @@ export function synchronizeTrackedDocument(options: {
     version: options.nextVersion(),
     synchronizationId: options.nextSynchronizationId(),
     evidenceRevision: options.evidenceRevision,
-    incrementalSync: options.incrementalSync,
+    documentSync: options.documentSync,
     waiters: options.waiters,
     sendNotification: options.sendNotification,
   });
@@ -130,11 +187,13 @@ interface ResynchronizeDocumentsOptions {
   nextVersion(uri: string): number;
   nextSynchronizationId(): number;
   evidenceRevision: number;
+  documentSync: NormalizedDocumentSync;
   /** Invalidate route evidence before the first changed document is applied. */
   noteInputContentChange(): number;
-  /** Record the verified disk content in the shared semantic barrier. */
-  observeDiskContent(uri: string, content: string): void;
-  incrementalSync: boolean;
+  /** Record the verified disk content and report whether its baseline changed. */
+  observeDiskContent(uri: string, content: string): boolean;
+  /** Send one save for an externally observed disk change. */
+  noteExternalDiskChange(uri: string, content: string): void;
   sendNotification: NotificationSender;
   uriToFile(uri: string): string;
   /** Disk content already read by classification; avoids a second read. */
@@ -157,6 +216,17 @@ export interface ResynchronizeDocumentsResult {
   failedFiles: string[];
 }
 
+/** Send one save when a refresh observes a new disk fingerprint. */
+function noteObservedDiskChange(
+  options: ResynchronizeDocumentsOptions,
+  uri: string,
+  content: string,
+): void {
+  if (options.observeDiskContent(uri, content)) {
+    options.noteExternalDiskChange(uri, content);
+  }
+}
+
 /** Re-read and synchronize every existing open document. */
 export function resynchronizeOpenDocuments(
   options: ResynchronizeDocumentsOptions,
@@ -185,7 +255,7 @@ export function resynchronizeOpenDocuments(
           version: options.nextVersion(uri),
           synchronizationId: options.nextSynchronizationId(),
           evidenceRevision: synchronizationRevision,
-          incrementalSync: options.incrementalSync,
+          documentSync: options.documentSync,
           waiters: options.waiters,
           sendNotification: options.sendNotification,
         });
@@ -200,7 +270,7 @@ export function resynchronizeOpenDocuments(
           waiters: options.waiters,
         });
       }
-      options.observeDiskContent(uri, content);
+      noteObservedDiskChange(options, uri, content);
       options.clearFailedFile(uri);
       synchronizedUris.add(uri);
       if (contentChanged) resynchronizedUris.add(uri);

package/src/client/client-semantic-input-barrier.ts

@@ -36,6 +36,8 @@ export interface SemanticInputBarrierHost {
   isOperational(): boolean;
   getOpenDocuments(): readonly SemanticInputDocument[];
   applyDocumentUpdates(updates: readonly SemanticInputUpdate[]): void;
+  /** Report disk changes that were observed during synchronization. */
+  noteExternalDiskChange?(filePath: string, content: string): void;
   closeMissingDocument(filePath: string): void;
   markUnreadableDocument(filePath: string): void;
 }
@@ -60,6 +62,7 @@ interface OpenDocumentRead {
 
 interface SynchronizationPlan {
   readonly updates: SemanticInputUpdate[];
+  readonly externalDiskChanges: Array<{ readonly filePath: string; readonly content: string }>;
   readonly observedDiskFingerprints: Map<string, string | undefined>;
 }
 
@@ -202,9 +205,13 @@ export class SemanticInputBarrier {
     this.#observedDiskFingerprints.set(uri, fingerprintDocumentContent(content));
   }
 
-  /** Record content read from disk after a synchronization or refresh pass. */
-  observeDiskContent(uri: string, content: string): void {
-    this.#observedDiskFingerprints.set(uri, fingerprintDocumentContent(content));
+  /** Record content read from disk and report a changed known baseline. */
+  observeDiskContent(uri: string, content: string): boolean {
+    const fingerprint = fingerprintDocumentContent(content);
+    const previous = this.#observedDiskFingerprints.get(uri);
+    const changed = this.#observedDiskFingerprints.has(uri) && previous !== fingerprint;
+    this.#observedDiskFingerprints.set(uri, fingerprint);
+    return changed;
   }
 
   /** Forget a document's last observed disk content. */
@@ -322,19 +329,25 @@ export class SemanticInputBarrier {
     reads: readonly OpenDocumentRead[],
   ): SynchronizationPlan {
     const updates: SemanticInputUpdate[] = [];
+    const externalDiskChanges: Array<{ readonly filePath: string; readonly content: string }> = [];
     const observedDiskFingerprints = new Map<string, string | undefined>();
     for (const read of reads) {
       const planned = this.#planDocumentRead(pending, read);
       observedDiskFingerprints.set(read.document.uri, planned.observedDiskFingerprint);
       if (planned.update) updates.push(planned.update);
+      if (planned.externalDiskChange) externalDiskChanges.push(planned.externalDiskChange);
     }
-    return { updates, observedDiskFingerprints };
+    return { updates, externalDiskChanges, observedDiskFingerprints };
   }
 
   #planDocumentRead(
     pending: PendingSynchronization,
     read: OpenDocumentRead,
-  ): { observedDiskFingerprint: string | undefined; update?: SemanticInputUpdate } {
+  ): {
+    observedDiskFingerprint: string | undefined;
+    update?: SemanticInputUpdate;
+    externalDiskChange?: { readonly filePath: string; readonly content: string };
+  } {
     const override = pending.contentOverrides.get(read.document.uri);
     if (read.result.kind === "error") {
       return this.#planReadError(read.document, read.result.error, override);
@@ -343,6 +356,12 @@ export class SemanticInputBarrier {
     const diskFingerprint = fingerprintDocumentContent(read.result.content);
     const hasObservedDiskContent = this.#observedDiskFingerprints.has(read.document.uri);
     const previousDiskFingerprint = this.#observedDiskFingerprints.get(read.document.uri);
+    const externalDiskChange =
+      override === undefined &&
+      hasObservedDiskContent &&
+      previousDiskFingerprint !== diskFingerprint
+        ? { filePath: read.document.filePath, content: read.result.content }
+        : undefined;
     // An explicit override controls server content; the disk fingerprint remains the next observation.
     const content =
       override ??
@@ -352,6 +371,7 @@ export class SemanticInputBarrier {
     const contentFingerprint = fingerprintDocumentContent(content);
     return {
       observedDiskFingerprint: diskFingerprint,
+      ...(externalDiskChange ? { externalDiskChange } : {}),
       ...(read.document.contentFingerprint !== contentFingerprint
         ? { update: { document: read.document, content } }
         : {}),
@@ -385,6 +405,9 @@ export class SemanticInputBarrier {
       this.#advanceRevision("content");
     }
     this.#rememberObservedDiskFingerprints(plan.observedDiskFingerprints);
+    for (const change of plan.externalDiskChanges) {
+      this.#host.noteExternalDiskChange?.(change.filePath, change.content);
+    }
   }
 
   #advanceRevision(changeKind: SemanticInputChangeKind): void {