@formspec/analysis 0.1.0-alpha.20

package/dist/analysis.d.ts

@@ -0,0 +1,812 @@
+import { AnnotationNode } from '@formspec/core';
+import { BuiltinConstraintBroadeningRegistration } from '@formspec/core';
+import { ConstraintNode } from '@formspec/core';
+import { ConstraintTagRegistration } from '@formspec/core';
+import { CustomConstraintRegistration } from '@formspec/core';
+import { ExtensionDefinition } from '@formspec/core';
+import type { JsonValue } from '@formspec/core';
+import type { PathTarget } from '@formspec/core';
+import { Provenance } from '@formspec/core';
+import * as ts from 'typescript';
+import { TypeNode } from '@formspec/core';
+
+export declare interface AnalysisTypeDefinition {
+    readonly name: string;
+    readonly type: TypeNode;
+    readonly constraints?: readonly ConstraintNode[];
+    readonly annotations?: readonly AnnotationNode[];
+    readonly provenance: Provenance;
+}
+
+export declare type AnalysisTypeRegistry = Record<string, AnalysisTypeDefinition>;
+
+/**
+ * Resolves targeted constraints against a field type, producing effective
+ * target states plus semantic diagnostics such as contradictions, unknown
+ * paths, and type mismatches.
+ */
+export declare function analyzeConstraintTargets(fieldName: string, fieldType: TypeNode, constraints: readonly ConstraintNode[], typeRegistry: AnalysisTypeRegistry, options?: {
+    readonly extensionRegistry?: ConstraintRegistryLike;
+}): ConstraintTargetAnalysisResult;
+
+export declare function buildConstraintTargetStates(fieldName: string, fieldType: TypeNode, constraints: readonly ConstraintNode[], typeRegistry: AnalysisTypeRegistry): readonly ResolvedTargetState[];
+
+/**
+ * Builds a transport-safe snapshot of every FormSpec-bearing doc comment in a
+ * source file, including semantic hover/completion context and file-local
+ * diagnostics.
+ */
+export declare function buildFormSpecAnalysisFileSnapshot(sourceFile: ts.SourceFile, options: BuildFormSpecAnalysisFileSnapshotOptions): FormSpecAnalysisFileSnapshot;
+
+/**
+ * Options used when building a serializable, editor-oriented snapshot for a
+ * TypeScript source file.
+ */
+export declare interface BuildFormSpecAnalysisFileSnapshotOptions {
+    readonly checker: ts.TypeChecker;
+    readonly extensions?: readonly ExtensionTagSource[];
+}
+
+/**
+ * Builds the synthetic helper declarations used to validate FormSpec tag
+ * applications through the TypeScript checker.
+ *
+ * The returned string is a virtual `.d.ts`-style prelude that declares the
+ * `__formspec.*` helper namespace together with context, path, member, and
+ * variant helper types. It is intended to be embedded into an in-memory
+ * TypeScript program, never emitted to disk.
+ */
+export declare function buildSyntheticHelperPrelude(extensions?: readonly ExtensionTagSource[]): string;
+
+/**
+ * Runs the TypeScript checker against a lowered synthetic tag application.
+ *
+ * This is the compiler-backed validation entrypoint used by FormSpec analysis
+ * to verify placement, target binding, and argument compatibility without
+ * requiring comment tags themselves to be valid TypeScript syntax.
+ */
+export declare function checkSyntheticTagApplication(options: CheckSyntheticTagApplicationOptions): SyntheticTagCheckResult;
+
+/**
+ * Options for running the TypeScript checker against a synthetic tag call.
+ */
+export declare interface CheckSyntheticTagApplicationOptions extends LowerSyntheticTagApplicationOptions {
+    readonly supportingDeclarations?: readonly string[];
+}
+
+export declare function collectCompatiblePathTargets(type: ts.Type, checker: ts.TypeChecker, capability: SemanticCapability): readonly string[];
+
+export declare function collectReferencedTypeAnnotations(type: TypeNode, typeRegistry: AnalysisTypeRegistry): readonly AnnotationNode[];
+
+export declare function collectReferencedTypeConstraints(type: TypeNode, typeRegistry: AnalysisTypeRegistry): readonly ConstraintNode[];
+
+export declare type CommentCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+} | {
+    readonly kind: "target";
+    readonly tag: ParsedCommentTag;
+} | {
+    readonly kind: "argument";
+    readonly tag: ParsedCommentTag;
+} | {
+    readonly kind: "none";
+};
+
+export declare interface CommentCursorTarget {
+    readonly kind: "tag-name" | "colon" | "target" | "argument";
+    readonly tag: ParsedCommentTag;
+}
+
+export declare interface CommentHoverInfo {
+    readonly kind: "tag-name" | "target" | "argument";
+    readonly markdown: string;
+}
+
+export declare interface CommentSemanticContextOptions {
+    readonly extensions?: readonly ExtensionTagSource[];
+    readonly placement?: FormSpecPlacement | null;
+    readonly checker?: ts.TypeChecker;
+    readonly subjectType?: ts.Type;
+}
+
+export declare interface CommentSourceSpan {
+    readonly start: number;
+    readonly end: number;
+}
+
+export declare type CommentSpan = CommentSourceSpan;
+
+export declare interface CommentTagSemanticContext {
+    readonly tag: ParsedCommentTag;
+    readonly tagDefinition: TagDefinition | null;
+    readonly placement: FormSpecPlacement | null;
+    readonly signatures: readonly TagSignature[];
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly targetCompletions: readonly string[];
+    readonly compatiblePathTargets: readonly string[];
+    readonly valueLabels: readonly string[];
+    readonly tagHoverMarkdown: string | null;
+    readonly targetHoverMarkdown: string | null;
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Computes a stable, non-cryptographic hash for document staleness checks
+ * across the plugin/LSP boundary.
+ */
+export declare function computeFormSpecTextHash(text: string): string;
+
+export declare interface ConstraintRegistrationLike {
+    readonly constraintName: string;
+    readonly applicableTypes: readonly TypeNode["kind"][] | null;
+    readonly isApplicableToType?: (type: TypeNode) => boolean;
+    readonly comparePayloads?: (left: JsonValue, right: JsonValue) => number;
+    readonly semanticRole?: ConstraintSemanticRoleLike;
+}
+
+export declare interface ConstraintRegistryLike {
+    findConstraint(constraintId: string): ConstraintRegistrationLike | undefined;
+    findConstraintTag(tagName: string): {
+        readonly extensionId: string;
+        readonly registration: ConstraintTagRegistrationLike;
+    } | undefined;
+}
+
+export declare interface ConstraintSemanticDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    readonly severity: "error" | "warning";
+    readonly primaryLocation: Provenance;
+    readonly relatedLocations: readonly Provenance[];
+}
+
+export declare interface ConstraintSemanticRoleLike {
+    readonly family: string;
+    readonly bound: "lower" | "upper" | "exact";
+    readonly inclusive: boolean;
+}
+
+export declare interface ConstraintTagParseRegistryLike {
+    readonly extensions: readonly ExtensionDefinition[];
+    findConstraint(constraintId: string): CustomConstraintRegistration | undefined;
+    findConstraintTag(tagName: string): {
+        readonly extensionId: string;
+        readonly registration: ConstraintTagRegistration;
+    } | undefined;
+    findBuiltinConstraintBroadening(typeId: string, tagName: string): {
+        readonly extensionId: string;
+        readonly registration: BuiltinConstraintBroadeningRegistration;
+    } | undefined;
+}
+
+export declare interface ConstraintTagRegistrationLike {
+    readonly tagName: string;
+    readonly constraintName: string;
+    readonly isApplicableToType?: (type: TypeNode) => boolean;
+}
+
+export declare interface ConstraintTargetAnalysisResult {
+    readonly diagnostics: readonly ConstraintSemanticDiagnostic[];
+    readonly targetStates: readonly ResolvedTargetState[];
+}
+
+export declare function dereferenceAnalysisType(type: TypeNode, typeRegistry: AnalysisTypeRegistry): TypeNode;
+
+export declare interface EffectiveTargetState {
+    readonly fieldName: string;
+    readonly path: PathTarget | null;
+    readonly targetName: string;
+    readonly type: TypeNode;
+    readonly inheritedConstraints: readonly ConstraintNode[];
+    readonly inheritedAnnotations: readonly AnnotationNode[];
+    readonly localConstraints: readonly ConstraintNode[];
+    readonly effectiveConstraints: readonly ConstraintNode[];
+}
+
+export declare interface EnclosingDocComment {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+    readonly parsed: ParsedCommentBlock;
+}
+
+export declare interface ExtensionConstraintTagSource {
+    readonly tagName: string;
+}
+
+export declare interface ExtensionTagSource {
+    readonly extensionId: string;
+    readonly constraintTags?: readonly ExtensionConstraintTagSource[];
+}
+
+/**
+ * Extract a `:foo.bar` path target prefix from raw tag text.
+ */
+export declare function extractPathTarget(text: string): ParsedPathTarget | null;
+
+export declare function findCommentTagAtOffset(documentText: string, offset: number, options?: {
+    readonly extensions?: readonly ExtensionTagSource[];
+}): ParsedCommentTag | null;
+
+/**
+ * Finds the smallest declaration whose leading doc comment contains the given
+ * source offset.
+ */
+export declare function findDeclarationForCommentOffset(sourceFile: ts.SourceFile, offset: number): ts.Node | null;
+
+export declare function findEnclosingDocComment(documentText: string, offset: number, options?: {
+    readonly extensions?: readonly ExtensionTagSource[];
+}): EnclosingDocComment | null;
+
+export declare function formatConstraintTargetName(fieldName: string, path: PathTarget | null): string;
+
+export declare function formatPathTarget(path: PathTarget | readonly string[]): string;
+
+export declare const FORMSPEC_ANALYSIS_PROTOCOL_VERSION = 1;
+
+export declare const FORMSPEC_ANALYSIS_SCHEMA_VERSION = 1;
+
+/**
+ * Serializable view of one declaration-attached doc comment in a source file.
+ */
+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.
+ */
+export declare interface FormSpecAnalysisDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    readonly range: CommentSpan;
+    readonly severity: "error" | "warning" | "info";
+}
+
+/**
+ * Serializable analysis artifact for a single source file.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare interface FormSpecIpcEndpoint {
+    readonly kind: "unix-socket" | "windows-pipe";
+    readonly address: string;
+}
+
+export declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
+
+export declare type FormSpecSemanticCapability = SemanticCapability;
+
+/**
+ * Query variants supported by the semantic tsserver plugin.
+ */
+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.
+ */
+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;
+};
+
+/**
+ * Serialized representation of a parsed target specifier with exact spans.
+ */
+export declare interface FormSpecSerializedCommentTargetSpecifier {
+    readonly rawText: string;
+    readonly valid: boolean;
+    readonly kind: ParsedCommentTargetSpecifier["kind"];
+    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.
+ */
+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.
+ */
+export declare interface FormSpecSerializedHoverInfo {
+    readonly kind: CommentHoverInfo["kind"];
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ */
+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.
+ */
+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.
+ */
+export declare interface FormSpecSerializedTagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+export declare type FormSpecTagCategory = "constraint" | "annotation" | "structure" | "ecosystem";
+
+export declare type FormSpecTagDefinition = TagDefinition;
+
+export declare type FormSpecTagOverload = TagSignature;
+
+export declare type FormSpecTagParameter = TagSignatureParameter;
+
+export declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
+
+export declare type FormSpecValueKind = "number" | "integer" | "signedInteger" | "string" | "json" | "boolean" | "condition";
+
+export declare function getAllTagDefinitions(extensions?: readonly ExtensionTagSource[]): readonly TagDefinition[];
+
+export declare function getCommentCompletionContextAtOffset(documentText: string, offset: number, options?: {
+    readonly extensions?: readonly ExtensionTagSource[];
+}): CommentCompletionContext;
+
+export declare function getCommentCursorTargetAtOffset(documentText: string, offset: number, options?: {
+    readonly extensions?: readonly ExtensionTagSource[];
+}): CommentCursorTarget | null;
+
+/**
+ * Returns hover information for the comment token under the given document
+ * offset, including semantic target/argument help when binding data is
+ * available.
+ */
+export declare function getCommentHoverInfoAtOffset(documentText: string, offset: number, options?: CommentSemanticContextOptions): CommentHoverInfo | null;
+
+export declare function getCommentTagSemanticContext(tag: ParsedCommentTag, options?: CommentSemanticContextOptions): CommentTagSemanticContext;
+
+export declare function getConstraintTagDefinitions(extensions?: readonly ExtensionTagSource[]): readonly TagDefinition[];
+
+/**
+ * Path to the manifest that advertises the local FormSpec semantic service for
+ * a workspace.
+ */
+export declare function getFormSpecManifestPath(workspaceRoot: string): string;
+
+/**
+ * Stable workspace-scoped identifier derived from the absolute workspace root.
+ */
+export declare function getFormSpecWorkspaceId(workspaceRoot: string): string;
+
+/**
+ * Directory used for machine-generated FormSpec tooling state inside a
+ * workspace.
+ */
+export declare function getFormSpecWorkspaceRuntimeDirectory(workspaceRoot: string): string;
+
+/**
+ * Resolves the enclosing host type for declarations nested under a containing
+ * class, interface, or type literal.
+ */
+export declare function getHostType(node: ts.Node, checker: ts.TypeChecker): ts.Type | undefined;
+
+/**
+ * Returns the last leading TSDoc/JSDoc block attached to a declaration node.
+ */
+export declare function getLastLeadingDocCommentRange(node: ts.Node, sourceFile: ts.SourceFile): ts.CommentRange | null;
+
+/**
+ * Filters a tag definition's overloads down to the ones that apply to the
+ * requested placement and synthetic target form.
+ *
+ * This is the overload-selection primitive used by both the lowering phase
+ * and cursor-aware tooling that wants to show only the currently-applicable
+ * signatures for a tag.
+ */
+export declare function getMatchingTagSignatures(definition: TagDefinition, placement: FormSpecPlacement, targetKind: SyntheticTagTargetKind | null): readonly TagSignature[];
+
+/**
+ * Resolves the completion context at a document offset, upgrading syntax-only
+ * results with placement/type-aware semantics when TypeScript binding data is
+ * available.
+ */
+export declare function getSemanticCommentCompletionContextAtOffset(documentText: string, offset: number, options?: CommentSemanticContextOptions): SemanticCommentCompletionContext;
+
+/**
+ * Resolves the direct subject type for declarations that can carry FormSpec
+ * comment tags.
+ */
+export declare function getSubjectType(node: ts.Node, checker: ts.TypeChecker): ts.Type | undefined;
+
+export declare function getTagCompletionPrefixAtOffset(documentText: string, offset: number): string | null;
+
+export declare function getTagDefinition(rawName: string, extensions?: readonly ExtensionTagSource[]): TagDefinition | null;
+
+export declare function getTagHoverMarkdown(rawName: string, extensions?: readonly ExtensionTagSource[]): string | null;
+
+export declare function getTypeSemanticCapabilities(type: ts.Type, checker: ts.TypeChecker): readonly SemanticCapability[];
+
+export declare function hasTypeSemanticCapability(type: ts.Type, checker: ts.TypeChecker, capability: SemanticCapability): boolean;
+
+/**
+ * Validates an unknown manifest payload from disk before consumers trust it.
+ */
+export declare function isFormSpecAnalysisManifest(value: unknown): value is FormSpecAnalysisManifest;
+
+/**
+ * Validates an unknown inbound IPC request before dispatching it.
+ */
+export declare function isFormSpecSemanticQuery(value: unknown): value is FormSpecSemanticQuery;
+
+/**
+ * Validates an unknown IPC response before the language server consumes it.
+ */
+export declare function isFormSpecSemanticResponse(value: unknown): value is FormSpecSemanticResponse;
+
+/**
+ * Result of lowering a tag application into the synthetic call representation
+ * used for compiler-backed validation.
+ */
+export declare interface LoweredSyntheticTagApplication {
+    readonly definition: TagDefinition;
+    readonly matchingSignatures: readonly TagSignature[];
+    readonly callExpression: string;
+}
+
+/**
+ * Inputs required to lower a parsed FormSpec tag into a synthetic TypeScript
+ * helper call.
+ *
+ * `hostType` and `subjectType` are trusted snippets of TypeScript type syntax
+ * supplied by the caller. They are embedded into an in-memory synthetic source
+ * file and are never executed.
+ */
+export declare interface LowerSyntheticTagApplicationOptions {
+    readonly tagName: string;
+    readonly placement: FormSpecPlacement;
+    readonly hostType: string;
+    readonly subjectType: string;
+    readonly target?: SyntheticTagTargetSpecifier | null;
+    readonly argumentExpression?: string | null;
+    readonly extensions?: readonly ExtensionTagSource[];
+}
+
+/**
+ * Lowers a normalized tag application into a synthetic helper call.
+ *
+ * The caller is responsible for supplying trusted `hostType` and `subjectType`
+ * snippets that are valid TypeScript type syntax in the generated synthetic
+ * program. This function does not sanitize those snippets; it only assembles
+ * the helper call and selects the matching overload metadata.
+ */
+export declare function lowerTagApplicationToSyntheticCall(options: LowerSyntheticTagApplicationOptions): LoweredSyntheticTagApplication;
+
+export declare function normalizeFormSpecTagName(rawName: string): string;
+
+export declare function parseCommentBlock(commentText: string, options?: ParseCommentSyntaxOptions): ParsedCommentBlock;
+
+export declare interface ParseCommentSyntaxOptions {
+    readonly offset?: number;
+    readonly extensions?: readonly ExtensionTagSource[];
+}
+
+export declare function parseConstraintTagValue(tagName: string, text: string, provenance: Provenance, options?: ParseConstraintTagValueOptions): ConstraintNode | null;
+
+export declare interface ParseConstraintTagValueOptions {
+    readonly registry?: ConstraintTagParseRegistryLike;
+    readonly fieldType?: TypeNode;
+}
+
+export declare interface ParsedCommentBlock {
+    readonly commentText: string;
+    readonly offset: number;
+    readonly tags: readonly ParsedCommentTag[];
+}
+
+export declare interface ParsedCommentTag {
+    readonly rawTagName: string;
+    readonly normalizedTagName: string;
+    readonly recognized: boolean;
+    readonly fullSpan: CommentSourceSpan;
+    readonly tagNameSpan: CommentSourceSpan;
+    readonly payloadSpan: CommentSourceSpan | null;
+    readonly colonSpan: CommentSourceSpan | null;
+    readonly target: ParsedCommentTargetSpecifier | null;
+    readonly argumentSpan: CommentSourceSpan | null;
+    readonly argumentText: string;
+}
+
+export declare interface ParsedCommentTargetSpecifier {
+    readonly rawText: string;
+    readonly valid: boolean;
+    readonly kind: "path" | "member" | "variant" | "ambiguous";
+    readonly fullSpan: CommentSourceSpan;
+    readonly colonSpan: CommentSourceSpan;
+    readonly span: CommentSourceSpan;
+    readonly path: PathTarget | null;
+}
+
+export declare function parseDefaultValueTagValue(text: string, provenance: Provenance): AnnotationNode;
+
+export declare interface ParsedPathTarget {
+    readonly path: PathTarget;
+    readonly remainingText: string;
+}
+
+export declare function parseTagSyntax(rawTagName: string, payloadText: string, options?: Omit<ParseCommentSyntaxOptions, "offset">): ParsedCommentTag;
+
+export declare function resolveConstraintTargetState(fieldName: string, fieldType: TypeNode, path: PathTarget | null, localConstraints: readonly ConstraintNode[], typeRegistry: AnalysisTypeRegistry): ResolvedTargetState;
+
+export declare function resolveDeclarationPlacement(node: ts.Node): FormSpecPlacement | null;
+
+/**
+ * Result of resolving a dotted FormSpec path target through a TypeScript type.
+ */
+export declare type ResolvedPathTargetType = {
+    readonly kind: "resolved";
+    readonly type: ts.Type;
+} | {
+    readonly kind: "missing-property";
+    readonly segment: string;
+} | {
+    readonly kind: "unresolvable";
+    readonly type: ts.Type;
+};
+
+export declare type ResolvedTargetState = ({
+    readonly kind: "resolved";
+} & EffectiveTargetState) | {
+    readonly kind: "missing-property";
+    readonly fieldName: string;
+    readonly path: PathTarget;
+    readonly targetName: string;
+    readonly segment: string;
+    readonly localConstraints: readonly ConstraintNode[];
+} | {
+    readonly kind: "unresolvable";
+    readonly fieldName: string;
+    readonly path: PathTarget;
+    readonly targetName: string;
+    readonly type: TypeNode;
+    readonly localConstraints: readonly ConstraintNode[];
+};
+
+/**
+ * Resolves a dotted FormSpec path target against a TypeScript type.
+ *
+ * Arrays are traversed through their item type so path-targets behave the same
+ * way they do in the IR validator and cursor-context completion logic.
+ */
+export declare function resolvePathTargetType(type: ts.Type, checker: ts.TypeChecker, segments: readonly string[]): ResolvedPathTargetType;
+
+export declare type SemanticCapability = "numeric-comparable" | "string-like" | "array-like" | "enum-member-addressable" | "json-like" | "condition-like" | "object-like";
+
+export declare type SemanticCommentCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+    readonly availableTags: readonly TagDefinition[];
+} | {
+    readonly kind: "target";
+    readonly semantic: CommentTagSemanticContext;
+} | {
+    readonly kind: "argument";
+    readonly semantic: CommentTagSemanticContext;
+    readonly valueLabels: readonly string[];
+} | {
+    readonly kind: "none";
+};
+
+/**
+ * Serializes tag-level semantic context for cross-process consumption.
+ */
+export declare function serializeCommentTagSemanticContext(semantic: CommentTagSemanticContext): FormSpecSerializedTagSemanticContext;
+
+/**
+ * Converts a parsed target specifier into its transport-safe JSON form.
+ */
+export declare function serializeCommentTargetSpecifier(target: ParsedCommentTargetSpecifier | null): FormSpecSerializedCommentTargetSpecifier | null;
+
+/**
+ * Serializes a cursor-scoped completion context for IPC.
+ */
+export declare function serializeCompletionContext(context: SemanticCommentCompletionContext): FormSpecSerializedCompletionContext;
+
+/**
+ * Serializes hover information for cross-process transport.
+ */
+export declare function serializeHoverInfo(hover: CommentHoverInfo | null): FormSpecSerializedHoverInfo | null;
+
+/**
+ * Serializes a parsed tag plus its semantic context into a file snapshot entry.
+ */
+export declare function serializeParsedCommentTag(tag: ParsedCommentTag, semantic: CommentTagSemanticContext): FormSpecAnalysisTagSnapshot;
+
+export declare function sliceCommentSpan(commentText: string, span: CommentSpan, options?: {
+    readonly offset?: number;
+}): string;
+
+/**
+ * A simplified TypeScript diagnostic surfaced from the synthetic compiler pass.
+ */
+export declare interface SyntheticCompilerDiagnostic {
+    readonly code: number;
+    readonly message: string;
+}
+
+/**
+ * Result of checking a lowered synthetic tag application with the TypeScript
+ * compiler.
+ */
+export declare interface SyntheticTagCheckResult {
+    readonly sourceText: string;
+    readonly diagnostics: readonly SyntheticCompilerDiagnostic[];
+}
+
+/**
+ * Target kinds that can be represented in a synthetic compiler call.
+ *
+ * This intentionally excludes `"none"`, because a missing target is modeled by
+ * omitting the synthetic target argument entirely.
+ */
+export declare type SyntheticTagTargetKind = "path" | "member" | "variant";
+
+/**
+ * A normalized target argument that can be lowered into a synthetic helper
+ * call for compiler-backed validation.
+ */
+export declare interface SyntheticTagTargetSpecifier {
+    readonly kind: SyntheticTagTargetKind;
+    readonly text: string;
+}
+
+export declare interface TagDefinition {
+    readonly canonicalName: string;
+    readonly valueKind: FormSpecValueKind | null;
+    readonly requiresArgument: boolean;
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly allowDuplicates: boolean;
+    readonly category: FormSpecTagCategory;
+    readonly placements: readonly FormSpecPlacement[];
+    readonly capabilities: readonly SemanticCapability[];
+    readonly completionDetail: string;
+    readonly hoverMarkdown: string;
+    readonly signatures: readonly TagSignature[];
+}
+
+export declare interface TagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+    readonly parameters: readonly TagSignatureParameter[];
+}
+
+export declare interface TagSignatureParameter {
+    readonly kind: "value" | "target-path" | "target-member" | "target-variant";
+    readonly label: string;
+    readonly optional?: boolean;
+    readonly capability?: SemanticCapability;
+    readonly valueKind?: FormSpecValueKind;
+}
+
+export { }