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

package/dist/index.js

@@ -1,25 +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,
-  computeFormSpecTextHash,
+  FORMSPEC_ANALYSIS_PROTOCOL_VERSION as FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
   isFormSpecSemanticQuery
 } from "@formspec/analysis/protocol";
-import {
-  buildFormSpecAnalysisFileSnapshot,
-  createFormSpecPerformanceRecorder,
-  findDeclarationForCommentOffset,
-  getCommentHoverInfoAtOffset,
-  getSemanticCommentCompletionContextAtOffset,
-  getFormSpecPerformanceNow,
-  getSubjectType,
-  optionalMeasure,
-  resolveDeclarationPlacement,
-  serializeCompletionContext,
-  serializeHoverInfo
-} from "@formspec/analysis/internal";
+import "@formspec/analysis/internal";
 
 // src/workspace.ts
 import os from "os";
@@ -79,112 +72,154 @@ 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;
-var FORM_SPEC_PLUGIN_PERFORMANCE_EVENT = {
-  handleQuery: "plugin.handleQuery"
-};
 
-// src/service.ts
-var FormSpecPluginService = class {
+// 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;
-    this.runtimePaths = getFormSpecWorkspaceRuntimePaths(options.workspaceRoot);
-    this.manifest = createFormSpecAnalysisManifest(
-      options.workspaceRoot,
-      options.typescriptVersion,
-      Date.now()
-    );
   }
-  manifest;
-  runtimePaths;
   snapshotCache = /* @__PURE__ */ new Map();
   refreshTimers = /* @__PURE__ */ new Map();
-  server = null;
-  getManifest() {
-    return this.manifest;
+  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 }
+          })
+        )
+      }))
+    );
   }
-  async start() {
-    if (this.server !== null) {
-      return;
-    }
-    await fs.mkdir(this.runtimePaths.runtimeDirectory, { recursive: true });
-    if (this.runtimePaths.endpoint.kind === "unix-socket") {
-      await fs.rm(this.runtimePaths.endpoint.address, { force: true });
-    }
-    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_VERSION2,
-              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;
-        }
-        const payload = buffer.slice(0, newlineIndex);
-        const remaining = buffer.slice(newlineIndex + 1);
-        if (remaining.trim().length > 0) {
-          this.options.logger?.info(
-            `[FormSpec] Ignoring extra semantic query payload data for ${this.runtimePaths.workspaceRoot}`
-          );
-        }
-        buffer = remaining;
-        this.respondToSocket(socket, payload);
-      });
-    });
-    await new Promise((resolve, reject) => {
-      const handleError = (error) => {
-        reject(error);
+  /** 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
       };
-      this.server?.once("error", handleError);
-      this.server?.listen(this.runtimePaths.endpoint.address, () => {
-        this.server?.off("error", handleError);
-        resolve();
-      });
     });
-    await this.writeManifest();
   }
-  async stop() {
-    for (const timer of this.refreshTimers.values()) {
-      clearTimeout(timer);
-    }
-    this.refreshTimers.clear();
-    this.snapshotCache.clear();
-    const server = this.server;
-    this.server = null;
-    if (server?.listening === true) {
-      await new Promise((resolve, reject) => {
-        server.close((error) => {
-          if (error === void 0) {
-            resolve();
-            return;
-          }
-          reject(error);
-        });
-      });
-    }
-    await this.cleanupRuntimeArtifacts();
+  /** 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) {
@@ -192,7 +227,7 @@ var FormSpecPluginService = class {
     }
     const timer = setTimeout(() => {
       try {
-        this.getFileSnapshot(filePath, void 0);
+        this.getFileSnapshot(filePath);
       } catch (error) {
         this.options.logger?.info(
           `[FormSpec] Failed to refresh semantic snapshot for ${filePath}: ${String(error)}`
@@ -200,76 +235,58 @@ var FormSpecPluginService = class {
       }
       this.refreshTimers.delete(filePath);
     }, this.options.snapshotDebounceMs ?? FORM_SPEC_PLUGIN_DEFAULT_SNAPSHOT_DEBOUNCE_MS);
+    timer.unref();
     this.refreshTimers.set(filePath, timer);
   }
-  handleQuery(query) {
-    const performance = this.options.enablePerformanceLogging === true ? createFormSpecPerformanceRecorder() : void 0;
-    const response = optionalMeasure(
-      performance,
-      FORM_SPEC_PLUGIN_PERFORMANCE_EVENT.handleQuery,
-      {
-        kind: query.kind,
-        ...query.kind === "health" ? {} : { filePath: query.filePath }
-      },
-      () => this.executeQuery(query, performance)
-    );
-    if (performance !== void 0) {
-      this.logPerformanceEvents(performance.events);
-    }
-    return response;
-  }
-  respondToSocket(socket, payload) {
-    try {
-      const query = JSON.parse(payload);
-      if (!isFormSpecSemanticQuery(query)) {
-        throw new Error("Invalid FormSpec semantic query payload");
-      }
-      const response = this.handleQuery(query);
-      socket.end(`${JSON.stringify(response)}
-`);
-    } catch (error) {
-      socket.end(
-        `${JSON.stringify({
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-          kind: "error",
-          error: error instanceof Error ? error.message : String(error)
-        })}
-`
-      );
+  /** Clears pending timers and cached semantic snapshots. */
+  dispose() {
+    for (const timer of this.refreshTimers.values()) {
+      clearTimeout(timer);
     }
+    this.refreshTimers.clear();
+    this.snapshotCache.clear();
   }
-  async writeManifest() {
-    const tempManifestPath = `${this.runtimePaths.manifestPath}.tmp`;
-    await fs.writeFile(tempManifestPath, `${JSON.stringify(this.manifest, null, 2)}
-`, "utf8");
-    await fs.rename(tempManifestPath, this.runtimePaths.manifestPath);
+  /** 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
+    };
   }
-  async cleanupRuntimeArtifacts() {
-    await fs.rm(this.runtimePaths.manifestPath, { force: true });
-    if (this.runtimePaths.endpoint.kind === "unix-socket") {
-      await fs.rm(this.runtimePaths.endpoint.address, { force: true });
+  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, handler, performance) {
+  withCommentQueryContext(filePath, offset, performance2, handler) {
     return optionalMeasure(
-      performance,
-      "plugin.resolveCommentQueryContext",
+      performance2,
+      "semantic.resolveCommentQueryContext",
       {
         filePath,
         offset
       },
       () => {
-        const environment = this.getSourceEnvironment(filePath, performance);
+        const environment = this.getSourceEnvironment(filePath, performance2);
         if (environment === null) {
-          return {
-            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-            kind: "error",
-            error: `Unable to resolve TypeScript source file for ${filePath}`
-          };
+          return null;
         }
         const declaration = optionalMeasure(
-          performance,
-          "plugin.findDeclarationForCommentOffset",
+          performance2,
+          "semantic.findDeclarationForCommentOffset",
           {
             filePath,
             offset
@@ -277,14 +294,14 @@ var FormSpecPluginService = class {
           () => findDeclarationForCommentOffset(environment.sourceFile, offset)
         );
         const placement = declaration === null ? null : optionalMeasure(
-          performance,
-          "plugin.resolveDeclarationPlacement",
+          performance2,
+          "semantic.resolveDeclarationPlacement",
           void 0,
           () => resolveDeclarationPlacement(declaration)
         );
         const subjectType = declaration === null ? void 0 : optionalMeasure(
-          performance,
-          "plugin.getSubjectType",
+          performance2,
+          "semantic.getSubjectType",
           void 0,
           () => getSubjectType(declaration, environment.checker)
         );
@@ -297,11 +314,12 @@ var FormSpecPluginService = class {
       }
     );
   }
-  getFileSnapshot(filePath, performance) {
+  getFileSnapshotWithCacheState(filePath, performance2) {
     const startedAt = getFormSpecPerformanceNow();
-    const environment = this.getSourceEnvironment(filePath, performance);
+    const environment = this.getSourceEnvironment(filePath, performance2);
     if (environment === null) {
-      const missingSourceSnapshot = {
+      this.stats.fileSnapshotCacheMisses += 1;
+      const snapshot2 = {
         filePath,
         sourceHash: "",
         generatedAt: this.getNow().toISOString(),
@@ -309,131 +327,83 @@ var FormSpecPluginService = class {
         diagnostics: [
           {
             code: "MISSING_SOURCE_FILE",
+            category: "infrastructure",
             message: `Unable to resolve TypeScript source file for ${filePath}`,
             range: { start: 0, end: 0 },
-            severity: "warning"
+            severity: "warning",
+            relatedLocations: [],
+            data: {
+              filePath
+            }
           }
         ]
       };
-      performance?.record({
-        name: "plugin.getFileSnapshot",
+      performance2.record({
+        name: "semantic.getFileSnapshot.result",
         durationMs: getFormSpecPerformanceNow() - startedAt,
         detail: {
           filePath,
           cache: "missing-source"
         }
       });
-      return missingSourceSnapshot;
+      return {
+        snapshot: snapshot2,
+        cacheState: "missing-source"
+      };
     }
     const cached = this.snapshotCache.get(filePath);
     if (cached?.sourceHash === environment.sourceHash) {
-      performance?.record({
-        name: "plugin.getFileSnapshot",
+      this.stats.fileSnapshotCacheHits += 1;
+      performance2.record({
+        name: "semantic.getFileSnapshot.result",
         durationMs: getFormSpecPerformanceNow() - startedAt,
         detail: {
           filePath,
           cache: "hit"
         }
       });
-      return cached.snapshot;
+      return {
+        snapshot: cached.snapshot,
+        cacheState: "hit"
+      };
     }
+    this.stats.fileSnapshotCacheMisses += 1;
     const snapshot = buildFormSpecAnalysisFileSnapshot(environment.sourceFile, {
       checker: environment.checker,
       now: () => this.getNow(),
-      ...performance === void 0 ? {} : { performance }
+      performance: performance2
     });
     this.snapshotCache.set(filePath, {
       sourceHash: environment.sourceHash,
       snapshot
     });
-    performance?.record({
-      name: "plugin.getFileSnapshot",
+    performance2.record({
+      name: "semantic.getFileSnapshot.result",
       durationMs: getFormSpecPerformanceNow() - startedAt,
       detail: {
         filePath,
         cache: "miss"
       }
     });
-    return snapshot;
+    return {
+      snapshot,
+      cacheState: "miss"
+    };
   }
   getNow() {
     return this.options.now?.() ?? /* @__PURE__ */ new Date();
   }
-  executeQuery(query, performance) {
-    switch (query.kind) {
-      case "health":
-        return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-          kind: "health",
-          manifest: this.manifest
-        };
-      case "completion":
-        return this.withCommentQueryContext(
-          query.filePath,
-          query.offset,
-          (context) => ({
-            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-            kind: "completion",
-            sourceHash: context.sourceHash,
-            context: serializeCompletionContext(
-              getSemanticCommentCompletionContextAtOffset(context.sourceFile.text, query.offset, {
-                checker: context.checker,
-                ...context.placement === null ? {} : { placement: context.placement },
-                ...context.subjectType === void 0 ? {} : { subjectType: context.subjectType }
-              })
-            )
-          }),
-          performance
-        );
-      case "hover":
-        return this.withCommentQueryContext(
-          query.filePath,
-          query.offset,
-          (context) => ({
-            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-            kind: "hover",
-            sourceHash: context.sourceHash,
-            hover: serializeHoverInfo(
-              getCommentHoverInfoAtOffset(context.sourceFile.text, query.offset, {
-                checker: context.checker,
-                ...context.placement === null ? {} : { placement: context.placement },
-                ...context.subjectType === void 0 ? {} : { subjectType: context.subjectType }
-              })
-            )
-          }),
-          performance
-        );
-      case "diagnostics": {
-        const snapshot = this.getFileSnapshot(query.filePath, performance);
-        return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-          kind: "diagnostics",
-          sourceHash: snapshot.sourceHash,
-          diagnostics: snapshot.diagnostics
-        };
-      }
-      case "file-snapshot":
-        return {
-          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION2,
-          kind: "file-snapshot",
-          snapshot: this.getFileSnapshot(query.filePath, performance)
-        };
-      default: {
-        throw new Error(`Unhandled semantic query: ${JSON.stringify(query)}`);
-      }
-    }
-  }
-  getSourceEnvironment(filePath, performance) {
+  getSourceEnvironment(filePath, performance2) {
     return optionalMeasure(
-      performance,
-      "plugin.getSourceEnvironment",
+      performance2,
+      "semantic.getSourceEnvironment",
       {
         filePath
       },
       () => {
         const program = optionalMeasure(
-          performance,
-          "plugin.sourceEnvironment.getProgram",
+          performance2,
+          "semantic.sourceEnvironment.getProgram",
           void 0,
           () => this.options.getProgram()
         );
@@ -441,8 +411,8 @@ var FormSpecPluginService = class {
           return null;
         }
         const sourceFile = optionalMeasure(
-          performance,
-          "plugin.sourceEnvironment.getSourceFile",
+          performance2,
+          "semantic.sourceEnvironment.getSourceFile",
           void 0,
           () => program.getSourceFile(filePath)
         );
@@ -450,14 +420,14 @@ var FormSpecPluginService = class {
           return null;
         }
         const checker = optionalMeasure(
-          performance,
-          "plugin.sourceEnvironment.getTypeChecker",
+          performance2,
+          "semantic.sourceEnvironment.getTypeChecker",
           void 0,
           () => program.getTypeChecker()
         );
         const sourceHash = optionalMeasure(
-          performance,
-          "plugin.sourceEnvironment.computeTextHash",
+          performance2,
+          "semantic.sourceEnvironment.computeTextHash",
           void 0,
           () => computeFormSpecTextHash(sourceFile.text)
         );
@@ -469,19 +439,38 @@ var FormSpecPluginService = class {
       }
     );
   }
-  logPerformanceEvents(events) {
-    const logger = this.options.logger;
-    if (logger === void 0 || events.length === 0) {
+  recordQueryPath(kind, cacheState) {
+    if (cacheState === "hit") {
+      this.stats.queryPathTotals[kind].warm += 1;
       return;
     }
-    let rootEvent;
-    for (let index = events.length - 1; index >= 0; index -= 1) {
-      const candidate = events[index];
-      if (candidate?.name === FORM_SPEC_PLUGIN_PERFORMANCE_EVENT.handleQuery) {
-        rootEvent = candidate;
-        break;
+    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;
     }
@@ -489,18 +478,234 @@ var FormSpecPluginService = class {
     if (rootEvent.durationMs < thresholdMs) {
       return;
     }
-    const sortedHotspots = [...events].filter((event) => event.name !== FORM_SPEC_PLUGIN_PERFORMANCE_EVENT.handleQuery).sort((left, right) => right.durationMs - left.durationMs).slice(0, 8);
+    const sortedHotspots = [...events].filter((event) => event.name !== rootEventName).sort((left, right) => right.durationMs - left.durationMs).slice(0, 8);
     const lines = [
-      `[FormSpec][perf] ${rootEvent.name} ${formatPerformanceEvent(rootEvent)}`,
+      `[FormSpec][perf] ${formatPerformanceEvent(rootEvent)}`,
       ...sortedHotspots.map((event) => `  ${formatPerformanceEvent(event)}`)
     ];
     logger.info(lines.join("\n"));
   }
 };
-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/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,
+      options.typescriptVersion,
+      Date.now()
+    );
+  }
+  manifest;
+  runtimePaths;
+  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;
+    }
+    await fs.mkdir(this.runtimePaths.runtimeDirectory, { recursive: true });
+    if (this.runtimePaths.endpoint.kind === "unix-socket") {
+      await fs.rm(this.runtimePaths.endpoint.address, { force: true });
+    }
+    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;
+        }
+        const payload = buffer.slice(0, newlineIndex);
+        const remaining = buffer.slice(newlineIndex + 1);
+        if (remaining.trim().length > 0) {
+          this.options.logger?.info(
+            `[FormSpec] Ignoring extra semantic query payload data for ${this.runtimePaths.workspaceRoot}`
+          );
+        }
+        buffer = remaining;
+        this.respondToSocket(socket, payload);
+      });
+    });
+    await new Promise((resolve, reject) => {
+      const handleError = (error) => {
+        reject(error);
+      };
+      this.server?.once("error", handleError);
+      this.server?.listen(this.runtimePaths.endpoint.address, () => {
+        this.server?.off("error", handleError);
+        resolve();
+      });
+    });
+    await this.writeManifest();
+  }
+  async stop() {
+    this.semanticService.dispose();
+    const server = this.server;
+    this.server = null;
+    if (server?.listening === true) {
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error === void 0) {
+            resolve();
+            return;
+          }
+          reject(error);
+        });
+      });
+    }
+    await this.cleanupRuntimeArtifacts();
+  }
+  scheduleSnapshotRefresh(filePath) {
+    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_VERSION3,
+          kind: "health",
+          manifest: this.manifest
+        };
+      case "completion": {
+        const result = this.semanticService.getCompletionContext(query.filePath, query.offset);
+        if (result === null) {
+          return {
+            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
+            kind: "error",
+            error: `Unable to resolve TypeScript source file for ${query.filePath}`
+          };
+        }
+        return {
+          ...result,
+          kind: "completion"
+        };
+      }
+      case "hover": {
+        const result = this.semanticService.getHover(query.filePath, query.offset);
+        if (result === null) {
+          return {
+            protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
+            kind: "error",
+            error: `Unable to resolve TypeScript source file for ${query.filePath}`
+          };
+        }
+        return {
+          ...result,
+          kind: "hover"
+        };
+      }
+      case "diagnostics": {
+        const result = this.semanticService.getDiagnostics(query.filePath);
+        return {
+          ...result,
+          kind: "diagnostics"
+        };
+      }
+      case "file-snapshot":
+        return {
+          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
+          kind: "file-snapshot",
+          snapshot: this.semanticService.getFileSnapshot(query.filePath)
+        };
+      default: {
+        throw new Error(`Unhandled semantic query: ${JSON.stringify(query)}`);
+      }
+    }
+  }
+  respondToSocket(socket, payload) {
+    try {
+      const query = JSON.parse(payload);
+      if (!isFormSpecSemanticQuery(query)) {
+        throw new Error("Invalid FormSpec semantic query payload");
+      }
+      const response = this.handleQuery(query);
+      socket.end(`${JSON.stringify(response)}
+`);
+    } catch (error) {
+      socket.end(
+        `${JSON.stringify({
+          protocolVersion: FORMSPEC_ANALYSIS_PROTOCOL_VERSION3,
+          kind: "error",
+          error: error instanceof Error ? error.message : String(error)
+        })}
+`
+      );
+    }
+  }
+  async writeManifest() {
+    const tempManifestPath = `${this.runtimePaths.manifestPath}.tmp`;
+    await fs.writeFile(tempManifestPath, `${JSON.stringify(this.manifest, null, 2)}
+`, "utf8");
+    await fs.rename(tempManifestPath, this.runtimePaths.manifestPath);
+  }
+  async cleanupRuntimeArtifacts() {
+    await fs.rm(this.runtimePaths.manifestPath, { force: true });
+    if (this.runtimePaths.endpoint.kind === "unix-socket") {
+      await fs.rm(this.runtimePaths.endpoint.address, { force: true });
+    }
+  }
+  logQueryDuration(query, durationMs) {
+    const logger = this.options.logger;
+    if (logger === void 0) {
+      return;
+    }
+    const thresholdMs = this.options.performanceLogThresholdMs ?? FORM_SPEC_PLUGIN_DEFAULT_PERFORMANCE_LOG_THRESHOLD_MS;
+    if (durationMs < thresholdMs) {
+      return;
+    }
+    const event = {
+      name: "plugin.handleQuery",
+      durationMs,
+      detail: {
+        kind: query.kind,
+        ...query.kind === "health" ? {} : { filePath: query.filePath }
+      }
+    };
+    logger.info(`[FormSpec][perf] ${formatPerformanceEvent(event)}`);
+  }
+};
 function createLanguageServiceProxy(languageService, semanticService) {
   const wrapWithSnapshotRefresh = (fn) => {
     return (fileName, ...args) => {
@@ -609,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