@formspec/build 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/analyzer/class-analyzer.d.ts

@@ -1,47 +1,68 @@
 /**
- * Class analyzer for extracting fields, types, and decorators.
+ * Class analyzer for extracting fields, types, and JSDoc constraints.
  *
- * Analyzes a TypeScript class declaration to extract:
- * - Field names and TypeScript types
- * - Decorator metadata (Field, Minimum, Maximum, etc.)
- * - Field optionality
- * - TSDoc @deprecated tags
- * - Default values from property initializers
+ * Produces `IRClassAnalysis` containing `FieldNode[]` and `typeRegistry`
+ * directly from class, interface, or type alias declarations.
+ * All downstream generation routes through the canonical FormIR.
  */
 import * as ts from "typescript";
-import { type DecoratorInfo } from "./decorator-extractor.js";
+import type { FieldNode, TypeNode, TypeDefinition, JsonValue } from "@formspec/core";
 /**
- * Analyzed field information from a class.
+ * Layout metadata extracted from `@Group` and `@ShowWhen` decorators.
+ * One entry per field, in the same order as `fields`.
  */
-export interface FieldInfo {
-    /** Field name */
-    name: string;
-    /** TypeScript type node for the field */
-    typeNode: ts.TypeNode | undefined;
-    /** Resolved type from the type checker */
-    type: ts.Type;
-    /** Whether the field is optional (has ? modifier) */
-    optional: boolean;
-    /** Decorators applied to the field */
-    decorators: DecoratorInfo[];
-    /** Whether the field has a TSDoc @deprecated tag */
-    deprecated: boolean;
-    /** Default value extracted from the property initializer (literal values only) */
-    defaultValue: unknown;
+export interface FieldLayoutMetadata {
+    /** Group label from `@Group("label")`, or undefined if ungrouped. */
+    readonly groupLabel?: string;
+    /** ShowWhen condition from `@ShowWhen({ field, value })`, or undefined if always visible. */
+    readonly showWhen?: {
+        readonly field: string;
+        readonly value: JsonValue;
+    };
 }
 /**
- * Result of analyzing a class declaration.
+ * Result of analyzing a class/interface/type alias into canonical IR.
  */
-export interface ClassAnalysis {
-    /** Class name */
-    name: string;
-    /** Analyzed fields */
-    fields: FieldInfo[];
-    /** Instance methods */
-    instanceMethods: MethodInfo[];
+export interface IRClassAnalysis {
+    /** Type name */
+    readonly name: string;
+    /** Analyzed fields as canonical IR FieldNodes */
+    readonly fields: readonly FieldNode[];
+    /** Layout metadata per field (same order/length as `fields`). */
+    readonly fieldLayouts: readonly FieldLayoutMetadata[];
+    /** Named type definitions referenced by fields */
+    readonly typeRegistry: Record<string, TypeDefinition>;
+    /** Instance methods (retained for downstream method-schema generation) */
+    readonly instanceMethods: readonly MethodInfo[];
     /** Static methods */
-    staticMethods: MethodInfo[];
+    readonly staticMethods: readonly MethodInfo[];
 }
+/**
+ * Result of analyzing a type alias into IR — either success or error.
+ */
+export type AnalyzeTypeAliasToIRResult = {
+    readonly ok: true;
+    readonly analysis: IRClassAnalysis;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Analyzes a class declaration and produces canonical IR FieldNodes.
+ */
+export declare function analyzeClassToIR(classDecl: ts.ClassDeclaration, checker: ts.TypeChecker, file?: string): IRClassAnalysis;
+/**
+ * Analyzes an interface declaration and produces canonical IR FieldNodes.
+ */
+export declare function analyzeInterfaceToIR(interfaceDecl: ts.InterfaceDeclaration, checker: ts.TypeChecker, file?: string): IRClassAnalysis;
+/**
+ * Analyzes a type alias declaration and produces canonical IR FieldNodes.
+ */
+export declare function analyzeTypeAliasToIR(typeAlias: ts.TypeAliasDeclaration, checker: ts.TypeChecker, file?: string): AnalyzeTypeAliasToIRResult;
+/**
+ * Resolves a TypeScript type to a canonical IR TypeNode.
+ */
+export declare function resolveTypeNode(type: ts.Type, checker: ts.TypeChecker, file: string, typeRegistry: Record<string, TypeDefinition>, visiting: Set<ts.Type>): TypeNode;
 /**
  * Analyzed method information.
  */
@@ -70,70 +91,4 @@ export interface ParameterInfo {
     /** Whether the parameter is optional (has ? or default value) */
     optional: boolean;
 }
-/**
- * Analyzes a class declaration to extract fields and methods.
- *
- * @param classDecl - The class declaration to analyze
- * @param checker - TypeScript type checker
- * @returns Analysis result with fields and methods
- */
-export declare function analyzeClass(classDecl: ts.ClassDeclaration, checker: ts.TypeChecker): ClassAnalysis;
-/**
- * Analyzes a property declaration to extract field info.
- */
-export declare function analyzeField(prop: ts.PropertyDeclaration, checker: ts.TypeChecker): FieldInfo | null;
-/**
- * Analyzes an interface declaration to extract field information.
- *
- * Similar to {@link analyzeClass} but for interface declarations.
- * Extracts JSDoc constraint tags (`@Minimum`, `@MaxLength`, etc.) and
- * display metadata (`@Field_displayName`, `@Field_description`) from
- * property signatures, producing the same {@link ClassAnalysis}
- * structure for downstream schema generation.
- *
- * @param interfaceDecl - The interface declaration to analyze
- * @param checker - TypeScript type checker
- * @returns Analysis result with fields (no methods — interfaces have no implementations)
- */
-export declare function analyzeInterface(interfaceDecl: ts.InterfaceDeclaration, checker: ts.TypeChecker): ClassAnalysis;
-/**
- * Result of analyzing a type alias — either a successful analysis or
- * an error describing why the alias can't be analyzed.
- */
-export type AnalyzeTypeAliasResult = {
-    ok: true;
-    analysis: ClassAnalysis;
-} | {
-    ok: false;
-    error: string;
-};
-/**
- * Analyzes a type alias declaration to extract field information.
- *
- * Supports type aliases whose body is a type literal (object type):
- *
- * ```typescript
- * type Config = {
- *   // @Field_displayName Name @Minimum 1
- *   name: string;
- * };
- * ```
- *
- * Returns an error result (not an exception) for non-object-literal aliases,
- * allowing callers to accumulate diagnostics across multiple types.
- *
- * @param typeAlias - The type alias declaration to analyze
- * @param checker - TypeScript type checker
- * @returns Success with analysis, or error with a diagnostic message including line number
- */
-export declare function analyzeTypeAlias(typeAlias: ts.TypeAliasDeclaration, checker: ts.TypeChecker): AnalyzeTypeAliasResult;
-/**
- * Analyzes an interface property signature to extract field info.
- *
- * Extracts JSDoc constraint tags (`@Minimum`, `@MaxLength`, etc.) and
- * display metadata (`@DisplayName`, `@Description`) from the property's
- * TSDoc comments. Also used by the type converter for nested interface/type
- * alias constraint propagation.
- */
-export declare function analyzeInterfaceProperty(prop: ts.PropertySignature, checker: ts.TypeChecker): FieldInfo | null;
 //# sourceMappingURL=class-analyzer.d.ts.map

package/dist/analyzer/class-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"class-analyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/class-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGnG;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,EAAE,CAAC,QAAQ,GAAG,SAAS,CAAC;IAClC,0CAA0C;IAC1C,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;IACd,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,oDAAoD;IACpD,UAAU,EAAE,OAAO,CAAC;IACpB,kFAAkF;IAClF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,uBAAuB;IACvB,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B,qBAAqB;IACrB,aAAa,EAAE,UAAU,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,uBAAuB;IACvB,cAAc,EAAE,EAAE,CAAC,QAAQ,GAAG,SAAS,CAAC;IACxC,2BAA2B;IAC3B,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,QAAQ,EAAE,EAAE,CAAC,QAAQ,GAAG,SAAS,CAAC;IAClC,oBAAoB;IACpB,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;IACd,0DAA0D;IAC1D,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,EAAE,CAAC,gBAAgB,EAC9B,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,aAAa,CA+Bf;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,EAAE,CAAC,mBAAmB,EAC5B,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,SAAS,GAAG,IAAI,CA6ClB;AAsLD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,EAAE,CAAC,oBAAoB,EACtC,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,aAAa,CAmBf;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,GACrC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,EAAE,CAAC,oBAAoB,EAClC,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,sBAAsB,CAkCxB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,EAAE,CAAC,iBAAiB,EAC1B,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,SAAS,GAAG,IAAI,CAyClB"}
+{"version":3,"file":"class-analyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/class-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/jsdoc-constraints.d.ts

@@ -1,47 +1,95 @@
 /**
- * JSDoc constraint tag extractor.
+ * JSDoc constraint and annotation extractor.
  *
- * Extracts constraint tags from JSDoc comments on class fields and returns
- * synthetic {@link DecoratorInfo} objects that integrate seamlessly with
- * the existing decorator-based constraint pipeline.
+ * Extracts constraints and annotation tags from JSDoc comments on
+ * class/interface fields and returns canonical IR nodes directly:
+ * - {@link ConstraintNode} for set-influencing tags (@Minimum, @Pattern, etc.)
+ * - {@link AnnotationNode} for value-influencing tags (@Field_displayName, etc.)
  *
- * Supported tags correspond to keys in {@link CONSTRAINT_TAG_DEFINITIONS}
+ * The IR extraction path uses the official `@microsoft/tsdoc` parser for
+ * constraints (all TSDoc-compliant alphanumeric names) and the TypeScript
+ * compiler JSDoc API for annotation tags (which contain underscores, e.g.
+ * `@Field_displayName`).
+ *
+ * Supported constraints correspond to keys in {@link BUILTIN_CONSTRAINT_DEFINITIONS}
  * from `@formspec/core` (e.g., `@Minimum`, `@Maximum`, `@Pattern`).
  */
 import * as ts from "typescript";
-import type { DecoratorInfo } from "./decorator-extractor.js";
+import { type ConstraintNode, type AnnotationNode } from "@formspec/core";
+/**
+ * A constraint argument value.
+ */
+export type ConstraintArg = string | number | boolean | null | ConstraintArg[] | {
+    [key: string]: ConstraintArg;
+};
+/**
+ * Extracted constraint information from a JSDoc tag.
+ * @deprecated Use {@link ConstraintNode} from the IR path instead.
+ */
+export interface ConstraintInfo {
+    /** Constraint name (e.g., "Minimum", "Pattern", "Field") */
+    name: string;
+    /** Constraint arguments as literal values */
+    args: ConstraintArg[];
+    /** Raw AST node (undefined for synthetic JSDoc constraint entries) */
+    node: ts.Decorator | undefined;
+}
 /**
- * Extracts JSDoc constraint tags from a TypeScript AST node and returns
- * synthetic {@link DecoratorInfo} objects.
+ * Extracts constraints from JSDoc comments on a TypeScript AST node and returns
+ * canonical {@link ConstraintNode} objects.
  *
- * For each recognised tag (case-sensitive PascalCase match against
- * {@link CONSTRAINT_TAG_DEFINITIONS}), the comment text is parsed
- * according to the tag's declared value type:
- * - `"number"` tags: parsed via `Number()` — skipped when NaN
- * - `"string"` tags (`Pattern`): used as-is (trimmed)
+ * Uses the official `@microsoft/tsdoc` parser for structured tag extraction.
+ * Constraints are registered as custom block tags in the TSDoc configuration.
  *
  * @param node - The AST node to inspect for JSDoc tags
- * @returns Synthetic decorator info objects for each valid constraint tag
+ * @param file - Absolute path to the source file for provenance
+ * @returns Canonical constraint nodes for each valid constraint tag
  */
-export declare function extractJSDocConstraints(node: ts.Node): DecoratorInfo[];
+export declare function extractJSDocConstraintNodes(node: ts.Node, file?: string): ConstraintNode[];
 /**
- * Extracts `@Field_displayName` and `@Field_description` TSDoc tags from
- * a node and returns a synthetic `Field` {@link DecoratorInfo} if either
- * is present.
+ * Extracts `@Field_displayName`, `@Field_description`, and `@deprecated`
+ * TSDoc tags from a node and returns canonical {@link AnnotationNode} objects.
  *
- * This enables interface properties to carry display metadata via TSDoc
- * tags instead of the `@Field` decorator (which requires a class):
+ * Uses a hybrid approach:
+ * - `@deprecated` is extracted via the TSDoc parser (standard tag).
+ * - `@Field_displayName` and `@Field_description` are extracted via the
+ *   TypeScript compiler JSDoc API because they contain underscores which
+ *   are invalid in TSDoc tag names.
  *
- * ```typescript
- * interface Config {
- *   // @Field_displayName Program Name
- *   // @Field_description Internal identifier
- *   programName: string;
- * }
- * ```
+ * @param node - The AST node to inspect for annotation tags
+ * @param file - Absolute path to the source file for provenance
+ * @returns Canonical annotation nodes
+ */
+export declare function extractJSDocAnnotationNodes(node: ts.Node, file?: string): AnnotationNode[];
+/**
+ * Checks if a node has a TSDoc `@deprecated` tag.
+ *
+ * Uses the TSDoc parser for structured detection.
+ */
+export declare function hasDeprecatedTag(node: ts.Node): boolean;
+/**
+ * Extracts a default value from a property initializer and returns a
+ * {@link DefaultValueAnnotationNode} if present.
+ *
+ * Only extracts literal values (strings, numbers, booleans, null).
+ */
+export declare function extractDefaultValueAnnotation(initializer: ts.Expression | undefined, file?: string): AnnotationNode | null;
+/**
+ * Extracts JSDoc constraint tags and returns synthetic {@link ConstraintInfo}
+ * objects for backward compatibility with the decorator-based pipeline.
+ *
+ * Uses the TypeScript compiler JSDoc API (not TSDoc parser) to maintain
+ * identical behavior with the legacy pipeline.
+ *
+ * @deprecated Use {@link extractJSDocConstraintNodes} for IR output.
+ */
+export declare function extractJSDocConstraints(node: ts.Node): ConstraintInfo[];
+/**
+ * Extracts `@Field_displayName` and `@Field_description` TSDoc tags
+ * and returns a synthetic `Field` {@link ConstraintInfo} for backward
+ * compatibility with the decorator-based pipeline.
  *
- * @param node - The AST node to inspect for display metadata tags
- * @returns A synthetic `Field` decorator info, or null if no tags found
+ * @deprecated Use {@link extractJSDocAnnotationNodes} for IR output.
  */
-export declare function extractJSDocFieldMetadata(node: ts.Node): DecoratorInfo | null;
+export declare function extractJSDocFieldMetadata(node: ts.Node): ConstraintInfo | null;
 //# sourceMappingURL=jsdoc-constraints.d.ts.map

package/dist/analyzer/jsdoc-constraints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-constraints.d.ts","sourceRoot":"","sources":["../../src/analyzer/jsdoc-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,aAAa,EAAE,CAoDtE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,aAAa,GAAG,IAAI,CAiC7E"}
+{"version":3,"file":"jsdoc-constraints.d.ts","sourceRoot":"","sources":["../../src/analyzer/jsdoc-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAOxB;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,aAAa,EAAE,GACf;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,sEAAsE;IACtE,IAAI,EAAE,EAAE,CAAC,SAAS,GAAG,SAAS,CAAC;CAChC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,cAAc,EAAE,CAGtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,cAAc,EAAE,CAGtF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,EACtC,IAAI,SAAK,GACR,cAAc,GAAG,IAAI,CAwCvB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,cAAc,EAAE,CA8CvE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,cAAc,GAAG,IAAI,CAgC9E"}

package/dist/analyzer/tsdoc-parser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * TSDoc-based structured tag parser.
+ *
+ * Bridges the TypeScript compiler AST with the official `@microsoft/tsdoc`
+ * parser to extract constraint and annotation tags from JSDoc comments
+ * on class/interface/type-alias properties.
+ *
+ * The parser recognises two categories of tags:
+ *
+ * 1. **Constraint tags** (all alphanumeric, TSDoc-compliant):
+ *    `@Minimum`, `@Maximum`, `@ExclusiveMinimum`, `@ExclusiveMaximum`,
+ *    `@MinLength`, `@MaxLength`, `@Pattern`, `@EnumOptions`
+ *    — Parsed via TSDocParser as custom block tags.
+ *
+ * 2. **Annotation tags** (`@Field_displayName`, `@Field_description`):
+ *    These contain underscores which are not valid in TSDoc tag names.
+ *    They are extracted via the TypeScript compiler's `ts.getJSDocTags()`
+ *    until a future migration to underscore-free tag names.
+ *
+ * The `@deprecated` tag is a standard TSDoc block tag, parsed structurally.
+ *
+ * **Fallback strategy**: TSDoc treats `{` / `}` as inline tag delimiters and
+ * `@` as a tag prefix, so content containing these characters (e.g. JSON
+ * objects in `@EnumOptions`, regex patterns with `@` in `@Pattern`) gets
+ * mangled by the TSDoc parser. For these tags, the raw text is extracted
+ * via the TS compiler's `ts.getJSDocTags()` API which preserves content
+ * verbatim.
+ */
+import * as ts from "typescript";
+import { type ConstraintNode, type AnnotationNode } from "@formspec/core";
+/**
+ * Result of parsing a single JSDoc comment attached to a TS AST node.
+ */
+export interface TSDocParseResult {
+    /** Constraint IR nodes extracted from custom block tags. */
+    readonly constraints: readonly ConstraintNode[];
+    /** Annotation IR nodes extracted from modifier/block tags and TS JSDoc API. */
+    readonly annotations: readonly AnnotationNode[];
+}
+/**
+ * Parses the JSDoc comment attached to a TypeScript AST node using the
+ * official TSDoc parser and returns canonical IR constraint and annotation
+ * nodes.
+ *
+ * For constraint tags (`@Minimum`, `@Pattern`, `@EnumOptions`, etc.),
+ * the structured TSDoc parser is used. For annotation tags that contain
+ * underscores (`@Field_displayName`, `@Field_description`), the TypeScript
+ * compiler JSDoc API is used as a fallback.
+ *
+ * @param node - The TS AST node to inspect (PropertyDeclaration, PropertySignature, etc.)
+ * @param file - Absolute source file path for provenance
+ * @returns Parsed constraint and annotation nodes
+ */
+export declare function parseTSDocTags(node: ts.Node, file?: string): TSDocParseResult;
+/**
+ * Checks if a TS AST node has a `@deprecated` tag using the TSDoc parser.
+ *
+ * Falls back to the TS compiler API for nodes without doc comments.
+ */
+export declare function hasDeprecatedTagTSDoc(node: ts.Node): boolean;
+//# sourceMappingURL=tsdoc-parser.d.ts.map

package/dist/analyzer/tsdoc-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc-parser.d.ts","sourceRoot":"","sources":["../../src/analyzer/tsdoc-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAYjC,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,cAAc,EAIpB,MAAM,gBAAgB,CAAC;AA8ExB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,SAAK,GAAG,gBAAgB,CAuHzE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAsB5D"}