@formspec/ts-plugin 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/index.js

@@ -1,20 +1,18 @@
+// src/index.ts
+import {
+  FORMSPEC_ANALYSIS_PROTOCOL_VERSION as FORMSPEC_ANALYSIS_PROTOCOL_VERSION4,
+  FORMSPEC_ANALYSIS_SCHEMA_VERSION as FORMSPEC_ANALYSIS_SCHEMA_VERSION2
+} from "@formspec/analysis/protocol";
+
 // src/service.ts
 import fs from "fs/promises";
 import net from "net";
 import "typescript";
 import {
-  FORMSPEC_ANALYSIS_PROTOCOL_VERSION as FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-  buildFormSpecAnalysisFileSnapshot,
-  computeFormSpecTextHash,
-  findDeclarationForCommentOffset,
-  getSubjectType,
-  getCommentHoverInfoAtOffset,
-  getSemanticCommentCompletionContextAtOffset,
-  isFormSpecSemanticQuery,
-  resolveDeclarationPlacement,
-  serializeCompletionContext,
-  serializeHoverInfo
-} from "@formspec/analysis";
+  FORMSPEC_ANALYSIS_PROTOCOL_VERSION as FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
+  isFormSpecSemanticQuery
+} from "@formspec/analysis/protocol";
+import "@formspec/analysis/internal";
 
 // src/workspace.ts
 import os from "os";
@@ -25,7 +23,7 @@ import {
   getFormSpecManifestPath,
   getFormSpecWorkspaceId,
   getFormSpecWorkspaceRuntimeDirectory
-} from "@formspec/analysis";
+} from "@formspec/analysis/protocol";
 function getFormSpecWorkspaceRuntimePaths(workspaceRoot, platform = process.platform, userScope = getFormSpecUserScope()) {
   const workspaceId = getFormSpecWorkspaceId(workspaceRoot);
   const runtimeDirectory = getFormSpecWorkspaceRuntimeDirectory(workspaceRoot);
@@ -74,10 +72,426 @@ function sanitizeScopeSegment(value) {
   return sanitized.length > 0 ? sanitized : "formspec";
 }
 
+// src/semantic-service.ts
+import "typescript";
+import {
+  FORMSPEC_ANALYSIS_PROTOCOL_VERSION as FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+  computeFormSpecTextHash
+} from "@formspec/analysis/protocol";
+import {
+  buildFormSpecAnalysisFileSnapshot,
+  createFormSpecPerformanceRecorder,
+  findDeclarationForCommentOffset,
+  getCommentHoverInfoAtOffset,
+  getSemanticCommentCompletionContextAtOffset,
+  getFormSpecPerformanceNow,
+  getSubjectType,
+  optionalMeasure,
+  resolveDeclarationPlacement,
+  serializeCompletionContext,
+  serializeHoverInfo
+} from "@formspec/analysis/internal";
+
+// src/constants.ts
+var FORM_SPEC_PLUGIN_MAX_SOCKET_PAYLOAD_BYTES = 256 * 1024;
+var FORM_SPEC_PLUGIN_SOCKET_IDLE_TIMEOUT_MS = 3e4;
+var FORM_SPEC_PLUGIN_DEFAULT_PERFORMANCE_LOG_THRESHOLD_MS = 50;
+var FORM_SPEC_PLUGIN_DEFAULT_SNAPSHOT_DEBOUNCE_MS = 250;
+
+// src/perf-utils.ts
+function formatPerformanceEvent(event) {
+  const detailEntries = Object.entries(event.detail ?? {}).map(([key, value]) => `${key}=${String(value)}`).join(" ");
+  return `${event.durationMs.toFixed(1)}ms ${event.name}${detailEntries === "" ? "" : ` ${detailEntries}`}`;
+}
+
+// src/semantic-service.ts
+var STATS_ONLY_EVENT_NAMES = /* @__PURE__ */ new Set([
+  "analysis.syntheticCheckBatch.cacheHit",
+  "analysis.narrowSyntheticCheckBatch.cacheHit",
+  "analysis.syntheticCheckBatch.cacheMiss",
+  "analysis.narrowSyntheticCheckBatch.cacheMiss",
+  "analysis.syntheticCheckBatch.createProgram",
+  "analysis.narrowSyntheticCheckBatch.createProgram"
+]);
+var StatsOnlyPerformanceRecorder = class {
+  mutableEvents = [];
+  get events() {
+    return this.mutableEvents;
+  }
+  measure(name, detail, callback) {
+    const result = callback();
+    if (STATS_ONLY_EVENT_NAMES.has(name)) {
+      this.mutableEvents.push({
+        name,
+        durationMs: 0,
+        ...detail === void 0 ? {} : { detail }
+      });
+    }
+    return result;
+  }
+  record(event) {
+    if (STATS_ONLY_EVENT_NAMES.has(event.name)) {
+      this.mutableEvents.push(event);
+    }
+  }
+};
+var FormSpecSemanticService = class {
+  constructor(options) {
+    this.options = options;
+  }
+  snapshotCache = /* @__PURE__ */ new Map();
+  refreshTimers = /* @__PURE__ */ new Map();
+  stats = {
+    queryTotals: {
+      completion: 0,
+      hover: 0,
+      diagnostics: 0,
+      fileSnapshot: 0
+    },
+    queryPathTotals: {
+      diagnostics: { cold: 0, warm: 0 },
+      fileSnapshot: { cold: 0, warm: 0 }
+    },
+    fileSnapshotCacheHits: 0,
+    fileSnapshotCacheMisses: 0,
+    syntheticBatchCacheHits: 0,
+    syntheticBatchCacheMisses: 0,
+    syntheticCompileCount: 0,
+    syntheticCompileApplications: 0
+  };
+  /** Resolves semantic completion context for a comment cursor position. */
+  getCompletionContext(filePath, offset) {
+    this.stats.queryTotals.completion += 1;
+    return this.runMeasured(
+      "semantic.getCompletionContext",
+      { filePath, offset },
+      (performance2) => this.withCommentQueryContext(filePath, offset, performance2, (context) => ({
+        protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+        sourceHash: context.sourceHash,
+        context: serializeCompletionContext(
+          getSemanticCommentCompletionContextAtOffset(context.sourceFile.text, offset, {
+            checker: context.checker,
+            ...context.placement === null ? {} : { placement: context.placement },
+            ...context.subjectType === void 0 ? {} : { subjectType: context.subjectType }
+          })
+        )
+      }))
+    );
+  }
+  /** Resolves semantic hover payload for a comment cursor position. */
+  getHover(filePath, offset) {
+    this.stats.queryTotals.hover += 1;
+    return this.runMeasured(
+      "semantic.getHover",
+      { filePath, offset },
+      (performance2) => this.withCommentQueryContext(filePath, offset, performance2, (context) => ({
+        protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+        sourceHash: context.sourceHash,
+        hover: serializeHoverInfo(
+          getCommentHoverInfoAtOffset(context.sourceFile.text, offset, {
+            checker: context.checker,
+            ...context.placement === null ? {} : { placement: context.placement },
+            ...context.subjectType === void 0 ? {} : { subjectType: context.subjectType }
+          })
+        )
+      }))
+    );
+  }
+  /** Returns canonical FormSpec diagnostics for a file in the current host program. */
+  getDiagnostics(filePath) {
+    this.stats.queryTotals.diagnostics += 1;
+    return this.runMeasured("semantic.getDiagnostics", { filePath }, (performance2) => {
+      const { snapshot, cacheState } = this.getFileSnapshotWithCacheState(filePath, performance2);
+      this.recordQueryPath("diagnostics", cacheState);
+      return {
+        protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+        sourceHash: snapshot.sourceHash,
+        diagnostics: snapshot.diagnostics
+      };
+    });
+  }
+  /** Returns the full serialized semantic snapshot for a file. */
+  getFileSnapshot(filePath) {
+    this.stats.queryTotals.fileSnapshot += 1;
+    return this.runMeasured("semantic.getFileSnapshot", { filePath }, (performance2) => {
+      const { snapshot, cacheState } = this.getFileSnapshotWithCacheState(filePath, performance2);
+      this.recordQueryPath("fileSnapshot", cacheState);
+      return snapshot;
+    });
+  }
+  /** Schedules a debounced background refresh for the file snapshot cache. */
+  scheduleSnapshotRefresh(filePath) {
+    const existing = this.refreshTimers.get(filePath);
+    if (existing !== void 0) {
+      clearTimeout(existing);
+    }
+    const timer = setTimeout(() => {
+      try {
+        this.getFileSnapshot(filePath);
+      } catch (error) {
+        this.options.logger?.info(
+          `[FormSpec] Failed to refresh semantic snapshot for ${filePath}: ${String(error)}`
+        );
+      }
+      this.refreshTimers.delete(filePath);
+    }, this.options.snapshotDebounceMs ?? FORM_SPEC_PLUGIN_DEFAULT_SNAPSHOT_DEBOUNCE_MS);
+    timer.unref();
+    this.refreshTimers.set(filePath, timer);
+  }
+  /** Clears pending timers and cached semantic snapshots. */
+  dispose() {
+    for (const timer of this.refreshTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.refreshTimers.clear();
+    this.snapshotCache.clear();
+  }
+  /** Returns a copy of the current performance and cache counters. */
+  getStats() {
+    return {
+      queryTotals: { ...this.stats.queryTotals },
+      queryPathTotals: {
+        diagnostics: { ...this.stats.queryPathTotals.diagnostics },
+        fileSnapshot: { ...this.stats.queryPathTotals.fileSnapshot }
+      },
+      fileSnapshotCacheHits: this.stats.fileSnapshotCacheHits,
+      fileSnapshotCacheMisses: this.stats.fileSnapshotCacheMisses,
+      syntheticBatchCacheHits: this.stats.syntheticBatchCacheHits,
+      syntheticBatchCacheMisses: this.stats.syntheticBatchCacheMisses,
+      syntheticCompileCount: this.stats.syntheticCompileCount,
+      syntheticCompileApplications: this.stats.syntheticCompileApplications
+    };
+  }
+  runMeasured(name, detail, fn) {
+    const performance2 = this.options.enablePerformanceLogging === true ? createFormSpecPerformanceRecorder() : new StatsOnlyPerformanceRecorder();
+    const result = optionalMeasure(performance2, name, detail, () => fn(performance2));
+    this.updateStatsFromPerformanceEvents(performance2.events);
+    if (this.options.enablePerformanceLogging === true) {
+      this.logPerformanceEvents(name, performance2.events);
+    }
+    return result;
+  }
+  withCommentQueryContext(filePath, offset, performance2, handler) {
+    return optionalMeasure(
+      performance2,
+      "semantic.resolveCommentQueryContext",
+      {
+        filePath,
+        offset
+      },
+      () => {
+        const environment = this.getSourceEnvironment(filePath, performance2);
+        if (environment === null) {
+          return null;
+        }
+        const declaration = optionalMeasure(
+          performance2,
+          "semantic.findDeclarationForCommentOffset",
+          {
+            filePath,
+            offset
+          },
+          () => findDeclarationForCommentOffset(environment.sourceFile, offset)
+        );
+        const placement = declaration === null ? null : optionalMeasure(
+          performance2,
+          "semantic.resolveDeclarationPlacement",
+          void 0,
+          () => resolveDeclarationPlacement(declaration)
+        );
+        const subjectType = declaration === null ? void 0 : optionalMeasure(
+          performance2,
+          "semantic.getSubjectType",
+          void 0,
+          () => getSubjectType(declaration, environment.checker)
+        );
+        return handler({
+          ...environment,
+          declaration,
+          placement,
+          subjectType
+        });
+      }
+    );
+  }
+  getFileSnapshotWithCacheState(filePath, performance2) {
+    const startedAt = getFormSpecPerformanceNow();
+    const environment = this.getSourceEnvironment(filePath, performance2);
+    if (environment === null) {
+      this.stats.fileSnapshotCacheMisses += 1;
+      const snapshot2 = {
+        filePath,
+        sourceHash: "",
+        generatedAt: this.getNow().toISOString(),
+        comments: [],
+        diagnostics: [
+          {
+            code: "MISSING_SOURCE_FILE",
+            category: "infrastructure",
+            message: `Unable to resolve TypeScript source file for ${filePath}`,
+            range: { start: 0, end: 0 },
+            severity: "warning",
+            relatedLocations: [],
+            data: {
+              filePath
+            }
+          }
+        ]
+      };
+      performance2.record({
+        name: "semantic.getFileSnapshot.result",
+        durationMs: getFormSpecPerformanceNow() - startedAt,
+        detail: {
+          filePath,
+          cache: "missing-source"
+        }
+      });
+      return {
+        snapshot: snapshot2,
+        cacheState: "missing-source"
+      };
+    }
+    const cached = this.snapshotCache.get(filePath);
+    if (cached?.sourceHash === environment.sourceHash) {
+      this.stats.fileSnapshotCacheHits += 1;
+      performance2.record({
+        name: "semantic.getFileSnapshot.result",
+        durationMs: getFormSpecPerformanceNow() - startedAt,
+        detail: {
+          filePath,
+          cache: "hit"
+        }
+      });
+      return {
+        snapshot: cached.snapshot,
+        cacheState: "hit"
+      };
+    }
+    this.stats.fileSnapshotCacheMisses += 1;
+    const snapshot = buildFormSpecAnalysisFileSnapshot(environment.sourceFile, {
+      checker: environment.checker,
+      now: () => this.getNow(),
+      performance: performance2
+    });
+    this.snapshotCache.set(filePath, {
+      sourceHash: environment.sourceHash,
+      snapshot
+    });
+    performance2.record({
+      name: "semantic.getFileSnapshot.result",
+      durationMs: getFormSpecPerformanceNow() - startedAt,
+      detail: {
+        filePath,
+        cache: "miss"
+      }
+    });
+    return {
+      snapshot,
+      cacheState: "miss"
+    };
+  }
+  getNow() {
+    return this.options.now?.() ?? /* @__PURE__ */ new Date();
+  }
+  getSourceEnvironment(filePath, performance2) {
+    return optionalMeasure(
+      performance2,
+      "semantic.getSourceEnvironment",
+      {
+        filePath
+      },
+      () => {
+        const program = optionalMeasure(
+          performance2,
+          "semantic.sourceEnvironment.getProgram",
+          void 0,
+          () => this.options.getProgram()
+        );
+        if (program === void 0) {
+          return null;
+        }
+        const sourceFile = optionalMeasure(
+          performance2,
+          "semantic.sourceEnvironment.getSourceFile",
+          void 0,
+          () => program.getSourceFile(filePath)
+        );
+        if (sourceFile === void 0) {
+          return null;
+        }
+        const checker = optionalMeasure(
+          performance2,
+          "semantic.sourceEnvironment.getTypeChecker",
+          void 0,
+          () => program.getTypeChecker()
+        );
+        const sourceHash = optionalMeasure(
+          performance2,
+          "semantic.sourceEnvironment.computeTextHash",
+          void 0,
+          () => computeFormSpecTextHash(sourceFile.text)
+        );
+        return {
+          sourceFile,
+          checker,
+          sourceHash
+        };
+      }
+    );
+  }
+  recordQueryPath(kind, cacheState) {
+    if (cacheState === "hit") {
+      this.stats.queryPathTotals[kind].warm += 1;
+      return;
+    }
+    this.stats.queryPathTotals[kind].cold += 1;
+  }
+  updateStatsFromPerformanceEvents(events) {
+    for (const event of events) {
+      if (event.name === "analysis.syntheticCheckBatch.cacheHit" || event.name === "analysis.narrowSyntheticCheckBatch.cacheHit") {
+        this.stats.syntheticBatchCacheHits += 1;
+        continue;
+      }
+      if (event.name === "analysis.syntheticCheckBatch.cacheMiss" || event.name === "analysis.narrowSyntheticCheckBatch.cacheMiss") {
+        this.stats.syntheticBatchCacheMisses += 1;
+        const applicationCount = event.detail?.["applicationCount"];
+        if (typeof applicationCount === "number") {
+          this.stats.syntheticCompileApplications += applicationCount;
+        }
+        continue;
+      }
+      if (event.name === "analysis.syntheticCheckBatch.createProgram" || event.name === "analysis.narrowSyntheticCheckBatch.createProgram") {
+        this.stats.syntheticCompileCount += 1;
+      }
+    }
+  }
+  logPerformanceEvents(rootEventName, events) {
+    const logger = this.options.logger;
+    if (logger === void 0 || events.length === 0) {
+      return;
+    }
+    const rootEvent = [...events].reverse().find((event) => event.name === rootEventName);
+    if (rootEvent === void 0) {
+      return;
+    }
+    const thresholdMs = this.options.performanceLogThresholdMs ?? FORM_SPEC_PLUGIN_DEFAULT_PERFORMANCE_LOG_THRESHOLD_MS;
+    if (rootEvent.durationMs < thresholdMs) {
+      return;
+    }
+    const sortedHotspots = [...events].filter((event) => event.name !== rootEventName).sort((left, right) => right.durationMs - left.durationMs).slice(0, 8);
+    const lines = [
+      `[FormSpec][perf] ${formatPerformanceEvent(rootEvent)}`,
+      ...sortedHotspots.map((event) => `  ${formatPerformanceEvent(event)}`)
+    ];
+    logger.info(lines.join("\n"));
+  }
+};
+
 // src/service.ts
 var FormSpecPluginService = class {
   constructor(options) {
     this.options = options;
+    this.semanticService = new FormSpecSemanticService(options);
     this.runtimePaths = getFormSpecWorkspaceRuntimePaths(options.workspaceRoot);
     this.manifest = createFormSpecAnalysisManifest(
       options.workspaceRoot,
@@ -87,12 +501,19 @@ var FormSpecPluginService = class {
   }
   manifest;
   runtimePaths;
-  snapshotCache = /* @__PURE__ */ new Map();
-  refreshTimers = /* @__PURE__ */ new Map();
+  semanticService;
   server = null;
   getManifest() {
     return this.manifest;
   }
+  /**
+   * Returns the underlying semantic service used by this reference wrapper.
+   *
+   * @public
+   */
+  getSemanticService() {
+    return this.semanticService;
+  }
   async start() {
     if (this.server !== null) {
       return;
@@ -104,8 +525,25 @@ var FormSpecPluginService = class {
     this.server = net.createServer((socket) => {
       let buffer = "";
       socket.setEncoding("utf8");
+      socket.setTimeout(FORM_SPEC_PLUGIN_SOCKET_IDLE_TIMEOUT_MS, () => {
+        this.options.logger?.info(
+          `[FormSpec] Closing idle semantic query socket for ${this.runtimePaths.workspaceRoot}`
+        );
+        socket.destroy();
+      });
       socket.on("data", (chunk) => {
         buffer += String(chunk);
+        if (buffer.length > FORM_SPEC_PLUGIN_MAX_SOCKET_PAYLOAD_BYTES) {
+          socket.end(
+            `${JSON.stringify({
+              protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
+              kind: "error",
+              error: `FormSpec semantic query exceeded ${String(FORM_SPEC_PLUGIN_MAX_SOCKET_PAYLOAD_BYTES)} bytes`
+            })}
+`
+          );
+          return;
+        }
         const newlineIndex = buffer.indexOf("\n");
         if (newlineIndex < 0) {
           return;
@@ -134,11 +572,7 @@ var FormSpecPluginService = class {
     await this.writeManifest();
   }
   async stop() {
-    for (const timer of this.refreshTimers.values()) {
-      clearTimeout(timer);
-    }
-    this.refreshTimers.clear();
-    this.snapshotCache.clear();
+    this.semanticService.dispose();
     const server = this.server;
     this.server = null;
     if (server?.listening === true) {
@@ -155,96 +589,65 @@ var FormSpecPluginService = class {
     await this.cleanupRuntimeArtifacts();
   }
   scheduleSnapshotRefresh(filePath) {
-    const existing = this.refreshTimers.get(filePath);
-    if (existing !== void 0) {
-      clearTimeout(existing);
-    }
-    const timer = setTimeout(() => {
-      try {
-        this.getFileSnapshot(filePath);
-      } catch (error) {
-        this.options.logger?.info(
-          `[FormSpec] Failed to refresh semantic snapshot for ${filePath}: ${String(error)}`
-        );
-      }
-      this.refreshTimers.delete(filePath);
-    }, this.options.snapshotDebounceMs ?? 250);
-    this.refreshTimers.set(filePath, timer);
+    this.semanticService.scheduleSnapshotRefresh(filePath);
   }
   handleQuery(query) {
+    if (this.options.enablePerformanceLogging === true) {
+      const startedAt = performance.now();
+      const response = this.executeQuery(query);
+      this.logQueryDuration(query, performance.now() - startedAt);
+      return response;
+    }
+    return this.executeQuery(query);
+  }
+  executeQuery(query) {
     switch (query.kind) {
       case "health":
         return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
           kind: "health",
           manifest: this.manifest
         };
       case "completion": {
-        const environment = this.getSourceEnvironment(query.filePath);
-        if (environment === null) {
+        const result = this.semanticService.getCompletionContext(query.filePath, query.offset);
+        if (result === null) {
           return {
-            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
             kind: "error",
             error: `Unable to resolve TypeScript source file for ${query.filePath}`
           };
         }
-        const declaration = findDeclarationForCommentOffset(environment.sourceFile, query.offset);
-        const placement = declaration === null ? null : resolveDeclarationPlacement(declaration);
-        const subjectType = declaration === null ? void 0 : getSubjectType(declaration, environment.checker);
-        const context = getSemanticCommentCompletionContextAtOffset(
-          environment.sourceFile.text,
-          query.offset,
-          {
-            checker: environment.checker,
-            ...placement === null ? {} : { placement },
-            ...subjectType === void 0 ? {} : { subjectType }
-          }
-        );
         return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-          kind: "completion",
-          sourceHash: computeFormSpecTextHash(environment.sourceFile.text),
-          context: serializeCompletionContext(context)
+          ...result,
+          kind: "completion"
         };
       }
       case "hover": {
-        const environment = this.getSourceEnvironment(query.filePath);
-        if (environment === null) {
+        const result = this.semanticService.getHover(query.filePath, query.offset);
+        if (result === null) {
           return {
-            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
             kind: "error",
             error: `Unable to resolve TypeScript source file for ${query.filePath}`
           };
         }
-        const declaration = findDeclarationForCommentOffset(environment.sourceFile, query.offset);
-        const placement = declaration === null ? null : resolveDeclarationPlacement(declaration);
-        const subjectType = declaration === null ? void 0 : getSubjectType(declaration, environment.checker);
-        const hover = getCommentHoverInfoAtOffset(environment.sourceFile.text, query.offset, {
-          checker: environment.checker,
-          ...placement === null ? {} : { placement },
-          ...subjectType === void 0 ? {} : { subjectType }
-        });
         return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-          kind: "hover",
-          sourceHash: computeFormSpecTextHash(environment.sourceFile.text),
-          hover: serializeHoverInfo(hover)
+          ...result,
+          kind: "hover"
         };
       }
       case "diagnostics": {
-        const snapshot = this.getFileSnapshot(query.filePath);
+        const result = this.semanticService.getDiagnostics(query.filePath);
         return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-          kind: "diagnostics",
-          sourceHash: snapshot.sourceHash,
-          diagnostics: snapshot.diagnostics
+          ...result,
+          kind: "diagnostics"
         };
       }
       case "file-snapshot":
         return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
           kind: "file-snapshot",
-          snapshot: this.getFileSnapshot(query.filePath)
+          snapshot: this.semanticService.getFileSnapshot(query.filePath)
         };
       default: {
         throw new Error(`Unhandled semantic query: ${JSON.stringify(query)}`);
@@ -263,7 +666,7 @@ var FormSpecPluginService = class {
     } catch (error) {
       socket.end(
         `${JSON.stringify({
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
+          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
           kind: "error",
           error: error instanceof Error ? error.message : String(error)
         })}
@@ -283,54 +686,24 @@ var FormSpecPluginService = class {
       await fs.rm(this.runtimePaths.endpoint.address, { force: true });
     }
   }
-  getSourceEnvironment(filePath) {
-    const program = this.options.getProgram();
-    if (program === void 0) {
-      return null;
+  logQueryDuration(query, durationMs) {
+    const logger = this.options.logger;
+    if (logger === void 0) {
+      return;
     }
-    const sourceFile = program.getSourceFile(filePath);
-    if (sourceFile === void 0) {
-      return null;
+    const thresholdMs = this.options.performanceLogThresholdMs ?? FORM_SPEC_PLUGIN_DEFAULT_PERFORMANCE_LOG_THRESHOLD_MS;
+    if (durationMs < thresholdMs) {
+      return;
     }
-    return {
-      sourceFile,
-      checker: program.getTypeChecker()
+    const event = {
+      name: "plugin.handleQuery",
+      durationMs,
+      detail: {
+        kind: query.kind,
+        ...query.kind === "health" ? {} : { filePath: query.filePath }
+      }
     };
-  }
-  getFileSnapshot(filePath) {
-    const environment = this.getSourceEnvironment(filePath);
-    if (environment === null) {
-      return {
-        filePath,
-        sourceHash: "",
-        generatedAt: this.getNow().toISOString(),
-        comments: [],
-        diagnostics: [
-          {
-            code: "MISSING_SOURCE_FILE",
-            message: `Unable to resolve TypeScript source file for ${filePath}`,
-            range: { start: 0, end: 0 },
-            severity: "warning"
-          }
-        ]
-      };
-    }
-    const sourceHash = computeFormSpecTextHash(environment.sourceFile.text);
-    const cached = this.snapshotCache.get(filePath);
-    if (cached?.sourceHash === sourceHash) {
-      return cached.snapshot;
-    }
-    const snapshot = buildFormSpecAnalysisFileSnapshot(environment.sourceFile, {
-      checker: environment.checker
-    });
-    this.snapshotCache.set(filePath, {
-      sourceHash,
-      snapshot
-    });
-    return snapshot;
-  }
-  getNow() {
-    return this.options.now?.() ?? /* @__PURE__ */ new Date();
+    logger.info(`[FormSpec][perf] ${formatPerformanceEvent(event)}`);
   }
 };
 function createLanguageServiceProxy(languageService, semanticService) {
@@ -367,9 +740,23 @@ function createLanguageServiceProxy(languageService, semanticService) {
 
 // src/index.ts
 var services = /* @__PURE__ */ new Map();
+var PERF_LOG_ENV_VAR = "FORMSPEC_PLUGIN_PROFILE";
+var PERF_LOG_THRESHOLD_ENV_VAR = "FORMSPEC_PLUGIN_PROFILE_THRESHOLD_MS";
 function formatPluginError(error) {
   return error instanceof Error ? error.stack ?? error.message : String(error);
 }
+function readBooleanEnvFlag(name) {
+  const rawValue = process.env[name];
+  return rawValue === "1" || rawValue === "true";
+}
+function readNumberEnvFlag(name) {
+  const rawValue = process.env[name];
+  if (rawValue === void 0 || rawValue.trim() === "") {
+    return void 0;
+  }
+  const parsed = Number(rawValue);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
 function getOrCreateService(info, typescriptVersion) {
   const workspaceRoot = info.project.getCurrentDirectory();
   const existing = services.get(workspaceRoot);
@@ -378,11 +765,14 @@ function getOrCreateService(info, typescriptVersion) {
     attachProjectCloseHandler(info, workspaceRoot, existing);
     return existing.service;
   }
+  const performanceLogThresholdMs = readNumberEnvFlag(PERF_LOG_THRESHOLD_ENV_VAR);
   const service = new FormSpecPluginService({
     workspaceRoot,
     typescriptVersion,
     getProgram: () => info.languageService.getProgram(),
-    logger: info.project.projectService.logger
+    logger: info.project.projectService.logger,
+    enablePerformanceLogging: readBooleanEnvFlag(PERF_LOG_ENV_VAR),
+    ...performanceLogThresholdMs === void 0 ? {} : { performanceLogThresholdMs }
   });
   const serviceEntry = {
     service,
@@ -424,11 +814,16 @@ function init(modules) {
   return {
     create(info) {
       const service = getOrCreateService(info, typescriptVersion);
-      return createLanguageServiceProxy(info.languageService, service);
+      return createLanguageServiceProxy(info.languageService, service.getSemanticService());
     }
   };
 }
 export {
+  FORMSPEC_ANALYSIS_PROTOCOL_VERSION4 as FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+  FORMSPEC_ANALYSIS_SCHEMA_VERSION2 as FORMSPEC_ANALYSIS_SCHEMA_VERSION,
+  FormSpecPluginService,
+  FormSpecSemanticService,
+  createLanguageServiceProxy,
   init
 };
 //# sourceMappingURL=index.js.map