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

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

@@ -1,15 +1,46 @@
+/**
+ * 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';
 
-/** @public */
-export declare type CommentSourceSpan = CommentSpan;
+/**
+ * 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;
+}
 
-/** @public */
-export declare interface CommentSpan {
+/**
+ * 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.
@@ -18,10 +49,19 @@ export declare interface CommentSpan {
  */
 export declare function createLanguageServiceProxy(languageService: ts.LanguageService, semanticService: FormSpecSemanticService): ts.LanguageService;
 
-/** @public */
+/**
+ * Current semantic-query protocol version shared by FormSpec analysis clients
+ * and servers.
+ *
+ * @public
+ */
 export declare const FORMSPEC_ANALYSIS_PROTOCOL_VERSION = 2;
 
-/** @public */
+/**
+ * Current schema version for serialized analysis artifacts.
+ *
+ * @public
+ */
 export declare const FORMSPEC_ANALYSIS_SCHEMA_VERSION = 1;
 
 /**
@@ -30,11 +70,17 @@ export declare const FORMSPEC_ANALYSIS_SCHEMA_VERSION = 1;
  * @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[];
 }
 
@@ -44,12 +90,19 @@ export declare interface FormSpecAnalysisCommentSnapshot {
  * @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>;
 }
 
@@ -74,8 +127,11 @@ export declare type FormSpecAnalysisDiagnosticDataValue = string | number | bool
  * @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;
 }
 
@@ -85,10 +141,15 @@ export declare interface FormSpecAnalysisDiagnosticLocation {
  * @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[];
 }
 
@@ -98,15 +159,24 @@ export declare interface FormSpecAnalysisFileSnapshot {
  *
  * @public
  */
-export declare interface FormSpecAnalysisManifest {
+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;
 }
 
@@ -116,15 +186,25 @@ export declare interface FormSpecAnalysisManifest {
  * @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;
 }
 
@@ -134,12 +214,18 @@ export declare interface FormSpecAnalysisTagSnapshot {
  *
  * @public
  */
-export declare interface FormSpecIpcEndpoint {
+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;
 }
 
-/** @public */
+/**
+ * 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";
 
 /**
@@ -157,6 +243,11 @@ export declare class FormSpecPluginService {
     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.
@@ -164,9 +255,31 @@ export declare class FormSpecPluginService {
      * @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;
@@ -188,24 +301,45 @@ export declare class FormSpecPluginService {
  */
 export declare type FormSpecPluginServiceOptions = FormSpecSemanticServiceOptions;
 
-/** @public */
+/**
+ * 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;
 }
 
-/** @public */
+/**
+ * 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[];
 }
 
-/** @public */
+/**
+ * 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;
 }
 
@@ -214,7 +348,7 @@ export declare interface FormSpecSemanticHoverResult {
  *
  * @public
  */
-export declare type FormSpecSemanticQuery = {
+declare type FormSpecSemanticQuery = {
     readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
     readonly kind: "health";
 } | {
@@ -242,7 +376,7 @@ export declare type FormSpecSemanticQuery = {
  *
  * @public
  */
-export declare type FormSpecSemanticResponse = {
+declare type FormSpecSemanticResponse = {
     readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
     readonly kind: "health";
     readonly manifest: FormSpecAnalysisManifest;
@@ -311,7 +445,11 @@ export declare class FormSpecSemanticService {
     private logPerformanceEvents;
 }
 
-/** @public */
+/**
+ * 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;
@@ -331,7 +469,11 @@ export declare interface FormSpecSemanticServiceOptions {
     readonly now?: () => Date;
 }
 
-/** @public */
+/**
+ * Performance and cache counters exposed by the semantic service.
+ *
+ * @public
+ */
 export declare interface FormSpecSemanticServiceStats {
     /** Total number of calls by semantic query kind. */
     readonly queryTotals: {
@@ -371,11 +513,17 @@ export declare interface FormSpecSemanticServiceStats {
  * @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;
 }
 
@@ -406,7 +554,9 @@ export declare type FormSpecSerializedCompletionContext = {
  * @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;
 }
 
@@ -416,8 +566,11 @@ export declare interface FormSpecSerializedHoverInfo {
  * @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;
 }
 
@@ -427,16 +580,27 @@ export declare interface FormSpecSerializedTagDefinition {
  * @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;
 }
 
@@ -446,11 +610,17 @@ export declare interface FormSpecSerializedTagSemanticContext {
  * @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[];
 }
 
-/** @public */
+/**
+ * Target syntaxes that a FormSpec tag can accept.
+ *
+ * @public
+ */
 export declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
 
 /**
@@ -462,8 +632,13 @@ export declare function init(modules: {
     readonly typescript: typeof tsServer;
 }): tsServer.server.PluginModule;
 
-/** @public */
+/**
+ * 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;
 }