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

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

@@ -0,0 +1,645 @@
+/**
+ * TypeScript language service plugin entrypoint for FormSpec.
+ *
+ * This package exposes the reference tsserver plugin and the reusable semantic
+ * service used by downstream TypeScript hosts.
+ *
+ * @packageDocumentation
+ */
+
+import * as ts from 'typescript';
+import type * as tsServer from 'typescript/lib/tsserverlibrary.js';
+
+/**
+ * Hover payload for a token inside a parsed FormSpec doc comment.
+ *
+ * @public
+ */
+export declare interface CommentHoverInfo {
+    /** Comment token kind currently being described. */
+    readonly kind: "tag-name" | "target" | "argument";
+    /** Markdown rendered for the hovered token. */
+    readonly markdown: string;
+}
+
+/**
+ * Half-open character span within a source comment string.
+ *
+ * @public
+ */
+export declare interface CommentSourceSpan {
+    /** Zero-based start offset, inclusive. */
+    readonly start: number;
+    /** Zero-based end offset, exclusive. */
+    readonly end: number;
+}
+
+/**
+ * Source span used by serialized comment-analysis payloads.
+ *
+ * @public
+ */
+export declare type CommentSpan = CommentSourceSpan;
+
+/**
+ * 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;
+
+/**
+ * Current semantic-query protocol version shared by FormSpec analysis clients
+ * and servers.
+ *
+ * @public
+ */
+export declare const FORMSPEC_ANALYSIS_PROTOCOL_VERSION = 2;
+
+/**
+ * Current schema version for serialized analysis artifacts.
+ *
+ * @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 {
+    /** Span covering the full doc comment block. */
+    readonly commentSpan: CommentSpan;
+    /** Span covering the declaration that owns the comment. */
+    readonly declarationSpan: CommentSpan;
+    /** Normalized placement where the comment was found, if known. */
+    readonly placement: FormSpecPlacement | null;
+    /** String form of the subject type targeted by the comment, if known. */
+    readonly subjectType: string | null;
+    /** String form of the host declaration type, if known. */
+    readonly hostType: string | null;
+    /** Parsed tag snapshots found inside the comment. */
+    readonly tags: readonly FormSpecAnalysisTagSnapshot[];
+}
+
+/**
+ * File-local diagnostic derived from comment parsing or semantic analysis.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnostic {
+    /** Stable diagnostic code for downstream rendering or filtering. */
+    readonly code: string;
+    /** High-level diagnostic category. */
+    readonly category: FormSpecAnalysisDiagnosticCategory;
+    /** Human-readable diagnostic message. */
+    readonly message: string;
+    /** Source range where the diagnostic applies. */
+    readonly range: CommentSpan;
+    /** Severity to surface in editor or CLI UIs. */
+    readonly severity: "error" | "warning" | "info";
+    /** Additional source locations related to the diagnostic. */
+    readonly relatedLocations: readonly FormSpecAnalysisDiagnosticLocation[];
+    /** Structured diagnostic facts for white-label downstream formatting. */
+    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 {
+    /** Absolute file path for the related diagnostic location. */
+    readonly filePath: string;
+    /** Source range for the related diagnostic location. */
+    readonly range: CommentSpan;
+    /** Optional explanatory text for the related location. */
+    readonly message?: string;
+}
+
+/**
+ * Serializable analysis artifact for a single source file.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisFileSnapshot {
+    /** Absolute path of the analyzed source file. */
+    readonly filePath: string;
+    /** Stable hash of the file text used to detect drift. */
+    readonly sourceHash: string;
+    /** ISO timestamp recording when the snapshot was generated. */
+    readonly generatedAt: string;
+    /** Parsed comment snapshots extracted from the file. */
+    readonly comments: readonly FormSpecAnalysisCommentSnapshot[];
+    /** Diagnostics produced for the file at snapshot time. */
+    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
+ */
+declare interface FormSpecAnalysisManifest {
+    /** Protocol version expected by both the client and semantic service. */
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    /** Schema version for serialized analysis artifacts. */
+    readonly analysisSchemaVersion: typeof FORMSPEC_ANALYSIS_SCHEMA_VERSION;
+    /** Absolute workspace root the manifest was generated for. */
+    readonly workspaceRoot: string;
+    /** Stable identifier derived from the workspace root. */
+    readonly workspaceId: string;
+    /** IPC endpoint clients should connect to for semantic queries. */
+    readonly endpoint: FormSpecIpcEndpoint;
+    /** TypeScript version reported by the host environment. */
+    readonly typescriptVersion: string;
+    /** Fingerprint representing the active extension-tag registry. */
+    readonly extensionFingerprint: string;
+    /** Monotonic generation number for manifest refreshes. */
+    readonly generation: number;
+    /** ISO timestamp for when the manifest was last written. */
+    readonly updatedAt: string;
+}
+
+/**
+ * Serializable view of a single parsed FormSpec tag within a doc comment.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisTagSnapshot {
+    /** Raw tag name as written in the source comment. */
+    readonly rawTagName: string;
+    /** Canonicalized tag name used for registry lookup. */
+    readonly normalizedTagName: string;
+    /** Whether the tag matched a known FormSpec tag definition. */
+    readonly recognized: boolean;
+    /** Span covering the full tag payload on the source line. */
+    readonly fullSpan: CommentSpan;
+    /** Span covering only the tag-name token. */
+    readonly tagNameSpan: CommentSpan;
+    /** Span covering the payload after the tag name, if present. */
+    readonly payloadSpan: CommentSpan | null;
+    /** Parsed target specifier, if the tag includes one. */
+    readonly target: FormSpecSerializedCommentTargetSpecifier | null;
+    /** Span covering the argument token or payload segment, if present. */
+    readonly argumentSpan: CommentSpan | null;
+    /** Raw argument text after any target specifier. */
+    readonly argumentText: string;
+    /** Semantic context derived for the parsed tag. */
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+}
+
+/**
+ * Cross-process endpoint used by the language server to reach the semantic
+ * tsserver plugin on the current workspace host.
+ *
+ * @public
+ */
+declare interface FormSpecIpcEndpoint {
+    /** Transport kind used to connect to the workspace semantic service. */
+    readonly kind: "unix-socket" | "windows-pipe";
+    /** Absolute socket path or pipe name for the semantic service endpoint. */
+    readonly address: string;
+}
+
+/**
+ * Declaration contexts where a FormSpec tag may appear.
+ *
+ * @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);
+    /**
+     * Returns the manifest written by the plugin service for workspace discovery.
+     *
+     * @internal
+     */
+    getManifest(): FormSpecAnalysisManifest;
+    /**
+     * Returns the underlying semantic service used by this reference wrapper.
+     *
+     * @public
+     */
+    getSemanticService(): FormSpecSemanticService;
+    /**
+     * Starts the IPC transport and writes the current workspace manifest.
+     *
+     * Calling this more than once is a no-op.
+     *
+     * @public
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the IPC transport, clears semantic state, and removes runtime artifacts.
+     *
+     * @public
+     */
+    stop(): Promise<void>;
+    /**
+     * Schedules a background refresh for the cached semantic snapshot of a file.
+     *
+     * @public
+     */
+    scheduleSnapshotRefresh(filePath: string): void;
+    /**
+     * Handles a semantic query issued against the plugin transport.
+     *
+     * @internal
+     */
+    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;
+
+/**
+ * Serialized completion result returned by the semantic service.
+ *
+ * @public
+ */
+export declare interface FormSpecSemanticCompletionResult {
+    /** Protocol version used by the serialized response. */
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    /** Hash of the source file used to compute the response. */
+    readonly sourceHash: string;
+    /** Serialized completion payload for the active cursor context. */
+    readonly context: FormSpecSerializedCompletionContext;
+}
+
+/**
+ * Serialized diagnostics result returned by the semantic service.
+ *
+ * @public
+ */
+export declare interface FormSpecSemanticDiagnosticsResult {
+    /** Protocol version used by the serialized response. */
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    /** Hash of the source file used to compute the response. */
+    readonly sourceHash: string;
+    /** Canonical FormSpec diagnostics for the requested file. */
+    readonly diagnostics: readonly FormSpecAnalysisDiagnostic[];
+}
+
+/**
+ * Serialized hover result returned by the semantic service.
+ *
+ * @public
+ */
+export declare interface FormSpecSemanticHoverResult {
+    /** Protocol version used by the serialized response. */
+    readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
+    /** Hash of the source file used to compute the response. */
+    readonly sourceHash: string;
+    /** Serialized hover payload, or `null` when nothing is available at the cursor. */
+    readonly hover: FormSpecSerializedHoverInfo | null;
+}
+
+/**
+ * Query variants supported by the semantic tsserver plugin.
+ *
+ * @public
+ */
+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
+ */
+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;
+}
+
+/**
+ * Configuration for the reusable in-process semantic service.
+ *
+ * @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;
+}
+
+/**
+ * Performance and cache counters exposed by the semantic service.
+ *
+ * @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 {
+    /** Raw target text without the leading colon. */
+    readonly rawText: string;
+    /** Whether the serialized target parsed successfully. */
+    readonly valid: boolean;
+    /** Target syntax kind inferred for the serialized specifier. */
+    readonly kind: "path" | "member" | "variant" | "ambiguous";
+    /** Span covering the entire target, including the leading colon. */
+    readonly fullSpan: CommentSpan;
+    /** Span covering only the colon token. */
+    readonly colonSpan: CommentSpan;
+    /** Span covering only the target text. */
+    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 {
+    /** Comment token kind being described. */
+    readonly kind: "tag-name" | "target" | "argument";
+    /** Markdown payload that should be rendered for the hover. */
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedTagDefinition {
+    /** Canonical tag name, including the `@` prefix. */
+    readonly canonicalName: string;
+    /** Short completion label shown in completion menus. */
+    readonly completionDetail: string;
+    /** Markdown hover content describing the tag. */
+    readonly hoverMarkdown: string;
+}
+
+/**
+ * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedTagSemanticContext {
+    /** Canonical tag name, including the `@` prefix. */
+    readonly tagName: string;
+    /** Tag metadata when the tag is recognized by the registry. */
+    readonly tagDefinition: FormSpecSerializedTagDefinition | null;
+    /** Declaration placement the tag was evaluated in, if known. */
+    readonly placement: FormSpecPlacement | null;
+    /** Target syntaxes supported by the matching signatures. */
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    /** Suggested targets for completion UIs. */
+    readonly targetCompletions: readonly string[];
+    /** Compatible path targets computed from the subject type, if available. */
+    readonly compatiblePathTargets: readonly string[];
+    /** Suggested value labels derived from the matching signatures. */
+    readonly valueLabels: readonly string[];
+    /** Signature summaries for the recognized tag in the current placement. */
+    readonly signatures: readonly FormSpecSerializedTagSignature[];
+    /** Markdown hover for the tag name token. */
+    readonly tagHoverMarkdown: string | null;
+    /** Markdown hover for the target token, when available. */
+    readonly targetHoverMarkdown: string | null;
+    /** Markdown hover for the argument token, when available. */
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
+ */
+export declare interface FormSpecSerializedTagSignature {
+    /** Human-readable rendering of one supported tag signature. */
+    readonly label: string;
+    /** Declaration placements where this signature is valid. */
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+/**
+ * Target syntaxes that a FormSpec tag can accept.
+ *
+ * @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;
+
+/**
+ * Minimal logging surface used by the semantic service and plugin wrapper.
+ *
+ * @public
+ */
+export declare interface LoggerLike {
+    /** Writes a human-readable diagnostic or profiling message. */
+    info(message: string): void;
+}
+
+export { }