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

package/dist/ts-plugin-alpha.d.ts

@@ -0,0 +1,470 @@
+import * as ts from 'typescript';
+import type * as tsServer from 'typescript/lib/tsserverlibrary.js';
+
+/** @public */
+export declare type CommentSourceSpan = CommentSpan;
+
+/** @public */
+export declare interface CommentSpan {
+    readonly start: number;
+    readonly end: number;
+}
+
+/**
+ * Reference proxy wrapper that keeps FormSpec semantic snapshots fresh while
+ * delegating actual TypeScript editor features to the original service.
+ *
+ * @public
+ */
+export declare function createLanguageServiceProxy(languageService: ts.LanguageService, semanticService: FormSpecSemanticService): ts.LanguageService;
+
+/** @public */
+export declare const FORMSPEC_ANALYSIS_PROTOCOL_VERSION = 2;
+
+/** @public */
+export declare const FORMSPEC_ANALYSIS_SCHEMA_VERSION = 1;
+
+/**
+ * Serializable view of one declaration-attached doc comment in a source file.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisCommentSnapshot {
+    readonly commentSpan: CommentSpan;
+    readonly declarationSpan: CommentSpan;
+    readonly placement: FormSpecPlacement | null;
+    readonly subjectType: string | null;
+    readonly hostType: string | null;
+    readonly tags: readonly FormSpecAnalysisTagSnapshot[];
+}
+
+/**
+ * File-local diagnostic derived from comment parsing or semantic analysis.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnostic {
+    readonly code: string;
+    readonly category: FormSpecAnalysisDiagnosticCategory;
+    readonly message: string;
+    readonly range: CommentSpan;
+    readonly severity: "error" | "warning" | "info";
+    readonly relatedLocations: readonly FormSpecAnalysisDiagnosticLocation[];
+    readonly data: Record<string, FormSpecAnalysisDiagnosticDataValue>;
+}
+
+/**
+ * Machine-readable diagnostic category used by FormSpec tooling surfaces.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticCategory = "tag-recognition" | "value-parsing" | "type-compatibility" | "target-resolution" | "constraint-validation" | "infrastructure";
+
+/**
+ * Primitive structured values carried in diagnostic facts for white-label
+ * downstream rendering.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticDataValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+
+/**
+ * Additional source location associated with a diagnostic.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnosticLocation {
+    readonly filePath: string;
+    readonly range: CommentSpan;
+    readonly message?: string;
+}
+
+/**
+ * Serializable analysis artifact for a single source file.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisFileSnapshot {
+    readonly filePath: string;
+    readonly sourceHash: string;
+    readonly generatedAt: string;
+    readonly comments: readonly FormSpecAnalysisCommentSnapshot[];
+    readonly diagnostics: readonly FormSpecAnalysisDiagnostic[];
+}
+
+/**
+ * Discovery record written by the tsserver plugin so other FormSpec tooling
+ * can locate and validate the matching semantic service for a workspace.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisManifest {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly analysisSchemaVersion: typeof FORMSPEC_ANALYSIS_SCHEMA_VERSION;
+    readonly workspaceRoot: string;
+    readonly workspaceId: string;
+    readonly endpoint: FormSpecIpcEndpoint;
+    readonly typescriptVersion: string;
+    readonly extensionFingerprint: string;
+    readonly generation: number;
+    readonly updatedAt: string;
+}
+
+/**
+ * Serializable view of a single parsed FormSpec tag within a doc comment.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisTagSnapshot {
+    readonly rawTagName: string;
+    readonly normalizedTagName: string;
+    readonly recognized: boolean;
+    readonly fullSpan: CommentSpan;
+    readonly tagNameSpan: CommentSpan;
+    readonly payloadSpan: CommentSpan | null;
+    readonly target: FormSpecSerializedCommentTargetSpecifier | null;
+    readonly argumentSpan: CommentSpan | null;
+    readonly argumentText: string;
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+}
+
+/**
+ * Cross-process endpoint used by the language server to reach the semantic
+ * tsserver plugin on the current workspace host.
+ *
+ * @public
+ */
+export declare interface FormSpecIpcEndpoint {
+    readonly kind: "unix-socket" | "windows-pipe";
+    readonly address: string;
+}
+
+/** @public */
+export declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
+
+/**
+ * Reference manifest/socket wrapper around `FormSpecSemanticService`.
+ *
+ * Downstream TypeScript hosts that already control their own plugin/runtime
+ * lifecycle can use `FormSpecSemanticService` directly and skip this wrapper.
+ *
+ * @public
+ */
+export declare class FormSpecPluginService {
+    private readonly options;
+    private readonly manifest;
+    private readonly runtimePaths;
+    private readonly semanticService;
+    private server;
+    constructor(options: FormSpecPluginServiceOptions);
+    getManifest(): FormSpecAnalysisManifest;
+    /**
+     * Returns the underlying semantic service used by this reference wrapper.
+     *
+     * @public
+     */
+    getSemanticService(): FormSpecSemanticService;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    scheduleSnapshotRefresh(filePath: string): void;
+    handleQuery(query: FormSpecSemanticQuery): FormSpecSemanticResponse;
+    private executeQuery;
+    private respondToSocket;
+    private writeManifest;
+    private cleanupRuntimeArtifacts;
+    private logQueryDuration;
+}
+
+/**
+ * Public configuration for the reference plugin wrapper that exposes
+ * `FormSpecSemanticService` over the local manifest + IPC transport.
+ *
+ * Supports the same semantic-service options, including
+ * `enablePerformanceLogging`, `performanceLogThresholdMs`, and
+ * `snapshotDebounceMs`. The packaged tsserver plugin wires these from
+ * `FORMSPEC_PLUGIN_PROFILE=1` and `FORMSPEC_PLUGIN_PROFILE_THRESHOLD_MS`.
+ *
+ * @public
+ */
+export declare type FormSpecPluginServiceOptions = FormSpecSemanticServiceOptions;
+
+/** @public */
+export declare interface FormSpecSemanticCompletionResult {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly sourceHash: string;
+    readonly context: FormSpecSerializedCompletionContext;
+}
+
+/** @public */
+export declare interface FormSpecSemanticDiagnosticsResult {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly sourceHash: string;
+    readonly diagnostics: readonly FormSpecAnalysisDiagnostic[];
+}
+
+/** @public */
+export declare interface FormSpecSemanticHoverResult {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly sourceHash: string;
+    readonly hover: FormSpecSerializedHoverInfo | null;
+}
+
+/**
+ * Query variants supported by the semantic tsserver plugin.
+ *
+ * @public
+ */
+export declare type FormSpecSemanticQuery = {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "health";
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "completion";
+    readonly filePath: string;
+    readonly offset: number;
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "hover";
+    readonly filePath: string;
+    readonly offset: number;
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "diagnostics";
+    readonly filePath: string;
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "file-snapshot";
+    readonly filePath: string;
+};
+
+/**
+ * Response variants returned by the semantic tsserver plugin.
+ *
+ * @public
+ */
+export declare type FormSpecSemanticResponse = {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "health";
+    readonly manifest: FormSpecAnalysisManifest;
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "completion";
+    readonly sourceHash: string;
+    readonly context: FormSpecSerializedCompletionContext;
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "hover";
+    readonly sourceHash: string;
+    readonly hover: FormSpecSerializedHoverInfo | null;
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "diagnostics";
+    readonly sourceHash: string;
+    readonly diagnostics: readonly FormSpecAnalysisDiagnostic[];
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "file-snapshot";
+    readonly snapshot: FormSpecAnalysisFileSnapshot | null;
+} | {
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    readonly kind: "error";
+    readonly error: string;
+};
+
+/**
+ * Reusable in-process semantic service for FormSpec authoring features.
+ *
+ * Downstream TypeScript hosts can construct this directly against their own
+ * `Program` and own the final presentation of completions, hover, and
+ * diagnostics. The shipped tsserver plugin is a reference wrapper over this
+ * public service.
+ *
+ * @public
+ */
+export declare class FormSpecSemanticService {
+    private readonly options;
+    private readonly snapshotCache;
+    private readonly refreshTimers;
+    private readonly stats;
+    constructor(options: FormSpecSemanticServiceOptions);
+    /** Resolves semantic completion context for a comment cursor position. */
+    getCompletionContext(filePath: string, offset: number): FormSpecSemanticCompletionResult | null;
+    /** Resolves semantic hover payload for a comment cursor position. */
+    getHover(filePath: string, offset: number): FormSpecSemanticHoverResult | null;
+    /** Returns canonical FormSpec diagnostics for a file in the current host program. */
+    getDiagnostics(filePath: string): FormSpecSemanticDiagnosticsResult;
+    /** Returns the full serialized semantic snapshot for a file. */
+    getFileSnapshot(filePath: string): FormSpecAnalysisFileSnapshot;
+    /** Schedules a debounced background refresh for the file snapshot cache. */
+    scheduleSnapshotRefresh(filePath: string): void;
+    /** Clears pending timers and cached semantic snapshots. */
+    dispose(): void;
+    /** Returns a copy of the current performance and cache counters. */
+    getStats(): FormSpecSemanticServiceStats;
+    private runMeasured;
+    private withCommentQueryContext;
+    private getFileSnapshotWithCacheState;
+    private getNow;
+    private getSourceEnvironment;
+    private recordQueryPath;
+    private updateStatsFromPerformanceEvents;
+    private logPerformanceEvents;
+}
+
+/** @public */
+export declare interface FormSpecSemanticServiceOptions {
+    /** Workspace root used for runtime paths and contextual logging. */
+    readonly workspaceRoot: string;
+    /** TypeScript version string reported by the host runtime. */
+    readonly typescriptVersion: string;
+    /** Supplies the current host program. Returns `undefined` until ready. */
+    readonly getProgram: () => ts.Program | undefined;
+    /** Optional logger used for profiling and refresh-failure messages. */
+    readonly logger?: LoggerLike;
+    /** Enables structured hotspot logging for semantic queries. */
+    readonly enablePerformanceLogging?: boolean;
+    /** Minimum query duration, in milliseconds, required before logging. */
+    readonly performanceLogThresholdMs?: number;
+    /** Debounce window, in milliseconds, for background snapshot refresh. */
+    readonly snapshotDebounceMs?: number;
+    /** Injectable clock used by tests and runtime snapshot timestamps. */
+    readonly now?: () => Date;
+}
+
+/** @public */
+export declare interface FormSpecSemanticServiceStats {
+    /** Total number of calls by semantic query kind. */
+    readonly queryTotals: {
+        readonly completion: number;
+        readonly hover: number;
+        readonly diagnostics: number;
+        readonly fileSnapshot: number;
+    };
+    /** Cold vs warm query path counts for snapshot-backed operations. */
+    readonly queryPathTotals: {
+        readonly diagnostics: {
+            readonly cold: number;
+            readonly warm: number;
+        };
+        readonly fileSnapshot: {
+            readonly cold: number;
+            readonly warm: number;
+        };
+    };
+    /** Number of file snapshot cache hits. */
+    readonly fileSnapshotCacheHits: number;
+    /** Number of file snapshot cache misses. */
+    readonly fileSnapshotCacheMisses: number;
+    /** Number of synthetic batch cache hits. */
+    readonly syntheticBatchCacheHits: number;
+    /** Number of synthetic batch cache misses. */
+    readonly syntheticBatchCacheMisses: number;
+    /** Number of synthetic compiler program creations. */
+    readonly syntheticCompileCount: number;
+    /** Total synthetic application count compiled across misses. */
+    readonly syntheticCompileApplications: number;
+}
+
+/**
+ * Serialized representation of a parsed target specifier with exact spans.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedCommentTargetSpecifier {
+    readonly rawText: string;
+    readonly valid: boolean;
+    readonly kind: "path" | "member" | "variant" | "ambiguous";
+    readonly fullSpan: CommentSpan;
+    readonly colonSpan: CommentSpan;
+    readonly span: CommentSpan;
+}
+
+/**
+ * Cursor-scoped completion context serialized for transport between the
+ * semantic tsserver plugin and the lightweight LSP.
+ *
+ * @public
+ */
+export declare type FormSpecSerializedCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+    readonly availableTags: readonly FormSpecSerializedTagDefinition[];
+} | {
+    readonly kind: "target";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+} | {
+    readonly kind: "argument";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+    readonly valueLabels: readonly string[];
+} | {
+    readonly kind: "none";
+};
+
+/**
+ * Hover payload for a single comment token under the cursor.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedHoverInfo {
+    readonly kind: "tag-name" | "target" | "argument";
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedTagDefinition {
+    readonly canonicalName: string;
+    readonly completionDetail: string;
+    readonly hoverMarkdown: string;
+}
+
+/**
+ * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedTagSemanticContext {
+    readonly tagName: string;
+    readonly tagDefinition: FormSpecSerializedTagDefinition | null;
+    readonly placement: FormSpecPlacement | null;
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly targetCompletions: readonly string[];
+    readonly compatiblePathTargets: readonly string[];
+    readonly valueLabels: readonly string[];
+    readonly signatures: readonly FormSpecSerializedTagSignature[];
+    readonly tagHoverMarkdown: string | null;
+    readonly targetHoverMarkdown: string | null;
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedTagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+/** @public */
+export declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
+
+/**
+ * Initializes the FormSpec TypeScript language service plugin.
+ *
+ * @public
+ */
+export declare function init(modules: {
+    readonly typescript: typeof tsServer;
+}): tsServer.server.PluginModule;
+
+/** @public */
+export declare interface LoggerLike {
+    info(message: string): void;
+}
+
+export { }