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

package/README.md

@@ -1,3 +1,67 @@
 # @formspec/ts-plugin
 
 TypeScript language service plugin for FormSpec semantic comment analysis.
+
+This package serves two roles:
+
+- a turnkey `tsserver` plugin via `init()`
+- a composable in-process semantic API for downstream TypeScript hosts
+
+The shipped plugin is the reference implementation. Downstream tools that
+already own their own TypeScript plugin/runtime can use
+`FormSpecSemanticService` and `createLanguageServiceProxy(...)` directly while
+reusing the same host `Program`.
+
+## Public Composition APIs
+
+```ts
+import { FormSpecSemanticService, createLanguageServiceProxy } from "@formspec/ts-plugin";
+```
+
+`FormSpecSemanticService` provides:
+
+- `getFileSnapshot(filePath)`
+- `getCompletionContext(filePath, offset)`
+- `getHover(filePath, offset)`
+- `getDiagnostics(filePath)`
+- `scheduleSnapshotRefresh(filePath)`
+- `getStats()`
+
+`FormSpecPluginService` wraps the same semantic service with the manifest + IPC
+transport used by the packaged language server.
+
+## Reference Host Example
+
+The shipped FormSpec `tsserver` plugin is only one reference implementation.
+Downstream tools that already own a TypeScript `Program` can build their own
+feedback layer directly on top of `FormSpecSemanticService`.
+
+See:
+
+- [reference-host-example.ts](https://github.com/mike-north/formspec/blob/main/packages/ts-plugin/src/reference-host-example.ts)
+- [downstream-authoring-host.test.ts](https://github.com/mike-north/formspec/blob/main/packages/ts-plugin/src/__tests__/downstream-authoring-host.test.ts)
+
+These source-repository references intentionally show a downstream host that
+renders diagnostics from `code` + `data` instead of reusing FormSpec's default
+message text.
+
+## White-Label Diagnostics
+
+Diagnostics returned by the semantic service and plugin transport include:
+
+- stable machine-readable `code`
+- structured `category`
+- raw diagnostic `data`
+- optional `relatedLocations`
+- default human-readable `message`
+
+Downstream tools can ignore `message` and render from `code` + `data` if they
+want full control over presentation.
+
+## 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__/downstream-authoring-host.test.d.ts

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

package/dist/__tests__/downstream-authoring-host.test.d.ts.map

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

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/__tests__/semantic-service.test.d.ts

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

package/dist/__tests__/semantic-service.test.d.ts.map

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

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"}