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

package/README.md

@@ -1,3 +1,11 @@
 # @formspec/ts-plugin
 
 TypeScript language service plugin for FormSpec semantic comment analysis.
+
+## Profiling
+
+Set `FORMSPEC_PLUGIN_PROFILE=1` to enable semantic query hotspot logging.
+
+Set `FORMSPEC_PLUGIN_PROFILE_THRESHOLD_MS=<number>` to raise or lower the
+minimum total query duration required before a profiling summary is logged.
+Empty or non-finite values are ignored.

package/dist/__tests__/handle-query.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handle-query.test.d.ts.map

package/dist/__tests__/handle-query.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-query.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/handle-query.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/helpers.d.ts

@@ -0,0 +1,11 @@
+import * as ts from "typescript";
+import type { FormSpecPluginService } from "../service.js";
+export declare const FORM_SPEC_PLUGIN_TEST_SOCKET_TIMEOUT_MS = 1000;
+export interface TestProgramContext {
+    readonly workspaceRoot: string;
+    readonly filePath: string;
+    readonly program: ts.Program;
+}
+export declare function createProgramContext(sourceText: string): Promise<TestProgramContext>;
+export declare function expectErrorResponse(response: ReturnType<FormSpecPluginService["handleQuery"]>, fragment: string): void;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/__tests__/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/__tests__/helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D,eAAO,MAAM,uCAAuC,OAAQ,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC;CAC9B;AAED,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAgB1F;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,UAAU,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC,EAC1D,QAAQ,EAAE,MAAM,GACf,IAAI,CAMN"}

package/dist/constants.d.ts

@@ -0,0 +1,8 @@
+export declare const FORM_SPEC_PLUGIN_MAX_SOCKET_PAYLOAD_BYTES: number;
+export declare const FORM_SPEC_PLUGIN_SOCKET_IDLE_TIMEOUT_MS = 30000;
+export declare const FORM_SPEC_PLUGIN_DEFAULT_PERFORMANCE_LOG_THRESHOLD_MS = 50;
+export declare const FORM_SPEC_PLUGIN_DEFAULT_SNAPSHOT_DEBOUNCE_MS = 250;
+export declare const FORM_SPEC_PLUGIN_PERFORMANCE_EVENT: {
+    readonly handleQuery: "plugin.handleQuery";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yCAAyC,QAAa,CAAC;AACpE,eAAO,MAAM,uCAAuC,QAAS,CAAC;AAC9D,eAAO,MAAM,qDAAqD,KAAK,CAAC;AACxE,eAAO,MAAM,6CAA6C,MAAM,CAAC;AAEjE,eAAO,MAAM,kCAAkC;;CAErC,CAAC"}

package/dist/index.cjs

@@ -38,15 +38,16 @@ module.exports = __toCommonJS(index_exports);
 var import_promises = __toESM(require("fs/promises"), 1);
 var import_node_net = __toESM(require("net"), 1);
 var ts = require("typescript");
-var import_analysis2 = require("@formspec/analysis");
+var import_protocol2 = require("@formspec/analysis/protocol");
+var import_internal = require("@formspec/analysis/internal");
 
 // src/workspace.ts
 var import_node_os = __toESM(require("os"), 1);
 var import_node_path = __toESM(require("path"), 1);
-var import_analysis = require("@formspec/analysis");
+var import_protocol = require("@formspec/analysis/protocol");
 function getFormSpecWorkspaceRuntimePaths(workspaceRoot, platform = process.platform, userScope = getFormSpecUserScope()) {
-  const workspaceId = (0, import_analysis.getFormSpecWorkspaceId)(workspaceRoot);
-  const runtimeDirectory = (0, import_analysis.getFormSpecWorkspaceRuntimeDirectory)(workspaceRoot);
+  const workspaceId = (0, import_protocol.getFormSpecWorkspaceId)(workspaceRoot);
+  const runtimeDirectory = (0, import_protocol.getFormSpecWorkspaceRuntimeDirectory)(workspaceRoot);
   const sanitizedUserScope = sanitizeScopeSegment(userScope);
   const endpoint = platform === "win32" ? {
     kind: "windows-pipe",
@@ -59,15 +60,15 @@ function getFormSpecWorkspaceRuntimePaths(workspaceRoot, platform = process.plat
     workspaceRoot,
     workspaceId,
     runtimeDirectory,
-    manifestPath: (0, import_analysis.getFormSpecManifestPath)(workspaceRoot),
+    manifestPath: (0, import_protocol.getFormSpecManifestPath)(workspaceRoot),
     endpoint
   };
 }
 function createFormSpecAnalysisManifest(workspaceRoot, typescriptVersion, generation, extensionFingerprint = "builtin") {
   const paths = getFormSpecWorkspaceRuntimePaths(workspaceRoot);
   return {
-    protocolVersion: import_analysis.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-    analysisSchemaVersion: import_analysis.FORMSPEC_ANALYSIS_SCHEMA_VERSION,
+    protocolVersion: import_protocol.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+    analysisSchemaVersion: import_protocol.FORMSPEC_ANALYSIS_SCHEMA_VERSION,
     workspaceRoot,
     workspaceId: paths.workspaceId,
     endpoint: paths.endpoint,
@@ -92,6 +93,15 @@ function sanitizeScopeSegment(value) {
   return sanitized.length > 0 ? sanitized : "formspec";
 }
 
+// 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 {
   constructor(options) {
@@ -122,8 +132,25 @@ var FormSpecPluginService = class {
     this.server = import_node_net.default.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: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+              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;
@@ -179,100 +206,36 @@ var FormSpecPluginService = class {
     }
     const timer = setTimeout(() => {
       try {
-        this.getFileSnapshot(filePath);
+        this.getFileSnapshot(filePath, void 0);
       } 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.options.snapshotDebounceMs ?? FORM_SPEC_PLUGIN_DEFAULT_SNAPSHOT_DEBOUNCE_MS);
     this.refreshTimers.set(filePath, timer);
   }
   handleQuery(query) {
-    switch (query.kind) {
-      case "health":
-        return {
-          protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-          kind: "health",
-          manifest: this.manifest
-        };
-      case "completion": {
-        const environment = this.getSourceEnvironment(query.filePath);
-        if (environment === null) {
-          return {
-            protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-            kind: "error",
-            error: `Unable to resolve TypeScript source file for ${query.filePath}`
-          };
-        }
-        const declaration = (0, import_analysis2.findDeclarationForCommentOffset)(environment.sourceFile, query.offset);
-        const placement = declaration === null ? null : (0, import_analysis2.resolveDeclarationPlacement)(declaration);
-        const subjectType = declaration === null ? void 0 : (0, import_analysis2.getSubjectType)(declaration, environment.checker);
-        const context = (0, import_analysis2.getSemanticCommentCompletionContextAtOffset)(
-          environment.sourceFile.text,
-          query.offset,
-          {
-            checker: environment.checker,
-            ...placement === null ? {} : { placement },
-            ...subjectType === void 0 ? {} : { subjectType }
-          }
-        );
-        return {
-          protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-          kind: "completion",
-          sourceHash: (0, import_analysis2.computeFormSpecTextHash)(environment.sourceFile.text),
-          context: (0, import_analysis2.serializeCompletionContext)(context)
-        };
-      }
-      case "hover": {
-        const environment = this.getSourceEnvironment(query.filePath);
-        if (environment === null) {
-          return {
-            protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-            kind: "error",
-            error: `Unable to resolve TypeScript source file for ${query.filePath}`
-          };
-        }
-        const declaration = (0, import_analysis2.findDeclarationForCommentOffset)(environment.sourceFile, query.offset);
-        const placement = declaration === null ? null : (0, import_analysis2.resolveDeclarationPlacement)(declaration);
-        const subjectType = declaration === null ? void 0 : (0, import_analysis2.getSubjectType)(declaration, environment.checker);
-        const hover = (0, import_analysis2.getCommentHoverInfoAtOffset)(environment.sourceFile.text, query.offset, {
-          checker: environment.checker,
-          ...placement === null ? {} : { placement },
-          ...subjectType === void 0 ? {} : { subjectType }
-        });
-        return {
-          protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-          kind: "hover",
-          sourceHash: (0, import_analysis2.computeFormSpecTextHash)(environment.sourceFile.text),
-          hover: (0, import_analysis2.serializeHoverInfo)(hover)
-        };
-      }
-      case "diagnostics": {
-        const snapshot = this.getFileSnapshot(query.filePath);
-        return {
-          protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-          kind: "diagnostics",
-          sourceHash: snapshot.sourceHash,
-          diagnostics: snapshot.diagnostics
-        };
-      }
-      case "file-snapshot":
-        return {
-          protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
-          kind: "file-snapshot",
-          snapshot: this.getFileSnapshot(query.filePath)
-        };
-      default: {
-        throw new Error(`Unhandled semantic query: ${JSON.stringify(query)}`);
-      }
+    const performance = this.options.enablePerformanceLogging === true ? (0, import_internal.createFormSpecPerformanceRecorder)() : void 0;
+    const response = (0, import_internal.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 (!(0, import_analysis2.isFormSpecSemanticQuery)(query)) {
+      if (!(0, import_protocol2.isFormSpecSemanticQuery)(query)) {
         throw new Error("Invalid FormSpec semantic query payload");
       }
       const response = this.handleQuery(query);
@@ -281,7 +244,7 @@ var FormSpecPluginService = class {
     } catch (error) {
       socket.end(
         `${JSON.stringify({
-          protocolVersion: import_analysis2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+          protocolVersion: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
           kind: "error",
           error: error instanceof Error ? error.message : String(error)
         })}
@@ -301,24 +264,58 @@ var FormSpecPluginService = class {
       await import_promises.default.rm(this.runtimePaths.endpoint.address, { force: true });
     }
   }
-  getSourceEnvironment(filePath) {
-    const program = this.options.getProgram();
-    if (program === void 0) {
-      return null;
-    }
-    const sourceFile = program.getSourceFile(filePath);
-    if (sourceFile === void 0) {
-      return null;
-    }
-    return {
-      sourceFile,
-      checker: program.getTypeChecker()
-    };
+  withCommentQueryContext(filePath, offset, handler, performance) {
+    return (0, import_internal.optionalMeasure)(
+      performance,
+      "plugin.resolveCommentQueryContext",
+      {
+        filePath,
+        offset
+      },
+      () => {
+        const environment = this.getSourceEnvironment(filePath, performance);
+        if (environment === null) {
+          return {
+            protocolVersion: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+            kind: "error",
+            error: `Unable to resolve TypeScript source file for ${filePath}`
+          };
+        }
+        const declaration = (0, import_internal.optionalMeasure)(
+          performance,
+          "plugin.findDeclarationForCommentOffset",
+          {
+            filePath,
+            offset
+          },
+          () => (0, import_internal.findDeclarationForCommentOffset)(environment.sourceFile, offset)
+        );
+        const placement = declaration === null ? null : (0, import_internal.optionalMeasure)(
+          performance,
+          "plugin.resolveDeclarationPlacement",
+          void 0,
+          () => (0, import_internal.resolveDeclarationPlacement)(declaration)
+        );
+        const subjectType = declaration === null ? void 0 : (0, import_internal.optionalMeasure)(
+          performance,
+          "plugin.getSubjectType",
+          void 0,
+          () => (0, import_internal.getSubjectType)(declaration, environment.checker)
+        );
+        return handler({
+          ...environment,
+          declaration,
+          placement,
+          subjectType
+        });
+      }
+    );
   }
-  getFileSnapshot(filePath) {
-    const environment = this.getSourceEnvironment(filePath);
+  getFileSnapshot(filePath, performance) {
+    const startedAt = (0, import_internal.getFormSpecPerformanceNow)();
+    const environment = this.getSourceEnvironment(filePath, performance);
     if (environment === null) {
-      return {
+      const missingSourceSnapshot = {
         filePath,
         sourceHash: "",
         generatedAt: this.getNow().toISOString(),
@@ -332,25 +329,192 @@ var FormSpecPluginService = class {
           }
         ]
       };
+      performance?.record({
+        name: "plugin.getFileSnapshot",
+        durationMs: (0, import_internal.getFormSpecPerformanceNow)() - startedAt,
+        detail: {
+          filePath,
+          cache: "missing-source"
+        }
+      });
+      return missingSourceSnapshot;
     }
-    const sourceHash = (0, import_analysis2.computeFormSpecTextHash)(environment.sourceFile.text);
     const cached = this.snapshotCache.get(filePath);
-    if (cached?.sourceHash === sourceHash) {
+    if (cached?.sourceHash === environment.sourceHash) {
+      performance?.record({
+        name: "plugin.getFileSnapshot",
+        durationMs: (0, import_internal.getFormSpecPerformanceNow)() - startedAt,
+        detail: {
+          filePath,
+          cache: "hit"
+        }
+      });
       return cached.snapshot;
     }
-    const snapshot = (0, import_analysis2.buildFormSpecAnalysisFileSnapshot)(environment.sourceFile, {
-      checker: environment.checker
+    const snapshot = (0, import_internal.buildFormSpecAnalysisFileSnapshot)(environment.sourceFile, {
+      checker: environment.checker,
+      now: () => this.getNow(),
+      ...performance === void 0 ? {} : { performance }
     });
     this.snapshotCache.set(filePath, {
-      sourceHash,
+      sourceHash: environment.sourceHash,
       snapshot
     });
+    performance?.record({
+      name: "plugin.getFileSnapshot",
+      durationMs: (0, import_internal.getFormSpecPerformanceNow)() - startedAt,
+      detail: {
+        filePath,
+        cache: "miss"
+      }
+    });
     return snapshot;
   }
   getNow() {
     return this.options.now?.() ?? /* @__PURE__ */ new Date();
   }
+  executeQuery(query, performance) {
+    switch (query.kind) {
+      case "health":
+        return {
+          protocolVersion: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+          kind: "health",
+          manifest: this.manifest
+        };
+      case "completion":
+        return this.withCommentQueryContext(
+          query.filePath,
+          query.offset,
+          (context) => ({
+            protocolVersion: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+            kind: "completion",
+            sourceHash: context.sourceHash,
+            context: (0, import_internal.serializeCompletionContext)(
+              (0, import_internal.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: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+            kind: "hover",
+            sourceHash: context.sourceHash,
+            hover: (0, import_internal.serializeHoverInfo)(
+              (0, import_internal.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: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+          kind: "diagnostics",
+          sourceHash: snapshot.sourceHash,
+          diagnostics: snapshot.diagnostics
+        };
+      }
+      case "file-snapshot":
+        return {
+          protocolVersion: import_protocol2.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+          kind: "file-snapshot",
+          snapshot: this.getFileSnapshot(query.filePath, performance)
+        };
+      default: {
+        throw new Error(`Unhandled semantic query: ${JSON.stringify(query)}`);
+      }
+    }
+  }
+  getSourceEnvironment(filePath, performance) {
+    return (0, import_internal.optionalMeasure)(
+      performance,
+      "plugin.getSourceEnvironment",
+      {
+        filePath
+      },
+      () => {
+        const program = (0, import_internal.optionalMeasure)(
+          performance,
+          "plugin.sourceEnvironment.getProgram",
+          void 0,
+          () => this.options.getProgram()
+        );
+        if (program === void 0) {
+          return null;
+        }
+        const sourceFile = (0, import_internal.optionalMeasure)(
+          performance,
+          "plugin.sourceEnvironment.getSourceFile",
+          void 0,
+          () => program.getSourceFile(filePath)
+        );
+        if (sourceFile === void 0) {
+          return null;
+        }
+        const checker = (0, import_internal.optionalMeasure)(
+          performance,
+          "plugin.sourceEnvironment.getTypeChecker",
+          void 0,
+          () => program.getTypeChecker()
+        );
+        const sourceHash = (0, import_internal.optionalMeasure)(
+          performance,
+          "plugin.sourceEnvironment.computeTextHash",
+          void 0,
+          () => (0, import_protocol2.computeFormSpecTextHash)(sourceFile.text)
+        );
+        return {
+          sourceFile,
+          checker,
+          sourceHash
+        };
+      }
+    );
+  }
+  logPerformanceEvents(events) {
+    const logger = this.options.logger;
+    if (logger === void 0 || events.length === 0) {
+      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;
+      }
+    }
+    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 !== FORM_SPEC_PLUGIN_PERFORMANCE_EVENT.handleQuery).sort((left, right) => right.durationMs - left.durationMs).slice(0, 8);
+    const lines = [
+      `[FormSpec][perf] ${rootEvent.name} ${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}`}`;
+}
 function createLanguageServiceProxy(languageService, semanticService) {
   const wrapWithSnapshotRefresh = (fn) => {
     return (fileName, ...args) => {
@@ -385,9 +549,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);
@@ -396,11 +574,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,