@formspec/analysis 0.1.0-alpha.20 → 0.1.0-alpha.21

package/dist/analysis.d.ts

@@ -1,123 +1,18 @@
-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 {
+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 {
+declare interface CommentSourceSpan {
     readonly start: number;
     readonly end: number;
 }
 
-export declare type CommentSpan = CommentSourceSpan;
+declare type CommentSpan = CommentSourceSpan;
 
-export declare interface CommentTagSemanticContext {
+declare interface CommentTagSemanticContext {
     readonly tag: ParsedCommentTag;
     readonly tagDefinition: TagDefinition | null;
     readonly placement: FormSpecPlacement | null;
@@ -134,121 +29,21 @@ export declare interface CommentTagSemanticContext {
 /**
  * Computes a stable, non-cryptographic hash for document staleness checks
  * across the plugin/LSP boundary.
+ *
+ * @public
  */
 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;
-
+/** @public */
 export declare const FORMSPEC_ANALYSIS_PROTOCOL_VERSION = 1;
 
+/** @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;
@@ -261,6 +56,8 @@ export declare interface FormSpecAnalysisCommentSnapshot {
 
 /**
  * File-local diagnostic derived from comment parsing or semantic analysis.
+ *
+ * @public
  */
 export declare interface FormSpecAnalysisDiagnostic {
     readonly code: string;
@@ -271,6 +68,8 @@ export declare interface FormSpecAnalysisDiagnostic {
 
 /**
  * Serializable analysis artifact for a single source file.
+ *
+ * @public
  */
 export declare interface FormSpecAnalysisFileSnapshot {
     readonly filePath: string;
@@ -283,6 +82,8 @@ export declare interface FormSpecAnalysisFileSnapshot {
 /**
  * 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;
@@ -298,6 +99,8 @@ export declare interface FormSpecAnalysisManifest {
 
 /**
  * Serializable view of a single parsed FormSpec tag within a doc comment.
+ *
+ * @public
  */
 export declare interface FormSpecAnalysisTagSnapshot {
     readonly rawTagName: string;
@@ -315,18 +118,20 @@ export declare interface FormSpecAnalysisTagSnapshot {
 /**
  * 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;
 }
 
-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;
+declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
 
 /**
  * Query variants supported by the semantic tsserver plugin.
+ *
+ * @public
  */
 export declare type FormSpecSemanticQuery = {
     readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
@@ -353,6 +158,8 @@ export declare type FormSpecSemanticQuery = {
 
 /**
  * Response variants returned by the semantic tsserver plugin.
+ *
+ * @public
  */
 export declare type FormSpecSemanticResponse = {
     readonly protocolVersion: typeof FORMSPEC_ANALYSIS_PROTOCOL_VERSION;
@@ -385,6 +192,8 @@ export declare type FormSpecSemanticResponse = {
 
 /**
  * Serialized representation of a parsed target specifier with exact spans.
+ *
+ * @public
  */
 export declare interface FormSpecSerializedCommentTargetSpecifier {
     readonly rawText: string;
@@ -398,6 +207,8 @@ export declare interface FormSpecSerializedCommentTargetSpecifier {
 /**
  * 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";
@@ -416,6 +227,8 @@ export declare type FormSpecSerializedCompletionContext = {
 
 /**
  * Hover payload for a single comment token under the cursor.
+ *
+ * @public
  */
 export declare interface FormSpecSerializedHoverInfo {
     readonly kind: CommentHoverInfo["kind"];
@@ -424,6 +237,8 @@ export declare interface FormSpecSerializedHoverInfo {
 
 /**
  * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
  */
 export declare interface FormSpecSerializedTagDefinition {
     readonly canonicalName: string;
@@ -433,6 +248,8 @@ export declare interface FormSpecSerializedTagDefinition {
 
 /**
  * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
  */
 export declare interface FormSpecSerializedTagSemanticContext {
     readonly tagName: string;
@@ -450,182 +267,65 @@ export declare interface FormSpecSerializedTagSemanticContext {
 
 /**
  * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
  */
 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;
+declare type FormSpecTagCategory = "constraint" | "annotation" | "structure" | "ecosystem";
 
-export declare type FormSpecTagParameter = TagSignatureParameter;
+declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
 
-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[];
+declare type FormSpecValueKind = "number" | "integer" | "signedInteger" | "string" | "json" | "boolean" | "condition";
 
 /**
  * Path to the manifest that advertises the local FormSpec semantic service for
  * a workspace.
+ *
+ * @public
  */
 export declare function getFormSpecManifestPath(workspaceRoot: string): string;
 
 /**
  * Stable workspace-scoped identifier derived from the absolute workspace root.
+ *
+ * @public
  */
 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.
+ * @public
  */
-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;
+export declare function getFormSpecWorkspaceRuntimeDirectory(workspaceRoot: string): string;
 
 /**
  * Validates an unknown manifest payload from disk before consumers trust it.
+ *
+ * @public
  */
 export declare function isFormSpecAnalysisManifest(value: unknown): value is FormSpecAnalysisManifest;
 
 /**
  * Validates an unknown inbound IPC request before dispatching it.
+ *
+ * @public
  */
 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.
+ * @public
  */
-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 function isFormSpecSemanticResponse(value: unknown): value is FormSpecSemanticResponse;
 
-export declare interface ParsedCommentTag {
+declare interface ParsedCommentTag {
     readonly rawTagName: string;
     readonly normalizedTagName: string;
     readonly recognized: boolean;
@@ -638,7 +338,7 @@ export declare interface ParsedCommentTag {
     readonly argumentText: string;
 }
 
-export declare interface ParsedCommentTargetSpecifier {
+declare interface ParsedCommentTargetSpecifier {
     readonly rawText: string;
     readonly valid: boolean;
     readonly kind: "path" | "member" | "variant" | "ambiguous";
@@ -648,62 +348,9 @@ export declare interface ParsedCommentTargetSpecifier {
     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;
+declare type SemanticCapability = "numeric-comparable" | "string-like" | "array-like" | "enum-member-addressable" | "json-like" | "condition-like" | "object-like";
 
-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 = {
+declare type SemanticCommentCompletionContext = {
     readonly kind: "tag-name";
     readonly prefix: string;
     readonly availableTags: readonly TagDefinition[];
@@ -720,68 +367,40 @@ export declare type SemanticCommentCompletionContext = {
 
 /**
  * Serializes tag-level semantic context for cross-process consumption.
+ *
+ * @public
  */
 export declare function serializeCommentTagSemanticContext(semantic: CommentTagSemanticContext): FormSpecSerializedTagSemanticContext;
 
 /**
  * Converts a parsed target specifier into its transport-safe JSON form.
+ *
+ * @public
  */
 export declare function serializeCommentTargetSpecifier(target: ParsedCommentTargetSpecifier | null): FormSpecSerializedCommentTargetSpecifier | null;
 
 /**
  * Serializes a cursor-scoped completion context for IPC.
+ *
+ * @public
  */
 export declare function serializeCompletionContext(context: SemanticCommentCompletionContext): FormSpecSerializedCompletionContext;
 
 /**
  * Serializes hover information for cross-process transport.
+ *
+ * @public
  */
 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.
+ * @public
  */
-export declare interface SyntheticTagTargetSpecifier {
-    readonly kind: SyntheticTagTargetKind;
-    readonly text: string;
-}
+export declare function serializeParsedCommentTag(tag: ParsedCommentTag, semantic: CommentTagSemanticContext): FormSpecAnalysisTagSnapshot;
 
-export declare interface TagDefinition {
+declare interface TagDefinition {
     readonly canonicalName: string;
     readonly valueKind: FormSpecValueKind | null;
     readonly requiresArgument: boolean;
@@ -795,13 +414,13 @@ export declare interface TagDefinition {
     readonly signatures: readonly TagSignature[];
 }
 
-export declare interface TagSignature {
+declare interface TagSignature {
     readonly label: string;
     readonly placements: readonly FormSpecPlacement[];
     readonly parameters: readonly TagSignatureParameter[];
 }
 
-export declare interface TagSignatureParameter {
+declare interface TagSignatureParameter {
     readonly kind: "value" | "target-path" | "target-member" | "target-variant";
     readonly label: string;
     readonly optional?: boolean;