@formspec/build 0.1.0-alpha.4 → 0.1.0-alpha.41

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike North
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,138 +1,283 @@
 # @formspec/build
 
-Build tools to compile FormSpec forms into JSON Schema and JSON Forms UI Schema.
+Build-time schema generation for FormSpec.
 
-## Installation
+This package covers:
+
+- Chain DSL to JSON Schema / UI Schema compilation
+- Static analysis of TypeScript classes, interfaces, and type aliases with TSDoc tags
+- Mixed-authoring schema generation
+- Extension-aware schema generation with custom vendor keywords
+
+## Install
 
 ```bash
-npm install @formspec/build
-# or
 pnpm add @formspec/build
 ```
 
-> **Note:** Most users should install the `formspec` umbrella package instead, which re-exports everything from this package.
+Most app code can use `formspec`, but use `@formspec/build` directly when you need static analysis or lower-level generation APIs.
 
-## Requirements
+## Public Entry Points
 
-This package is ESM-only and requires:
+| Entry point                 | Purpose                               |
+| --------------------------- | ------------------------------------- |
+| `@formspec/build`           | Public build APIs                     |
+| `@formspec/build/browser`   | Browser-safe chain-DSL and IR surface |
+| `@formspec/build/internals` | Unstable low-level IR/analyzer APIs   |
 
-```json
-// package.json
-{
-  "type": "module"
-}
+## Chain DSL Generation
+
+```ts
+import { buildFormSchemas } from "@formspec/build";
+import { field, formspec } from "@formspec/dsl";
+
+const form = formspec(
+  field.text("name", { required: true }),
+  field.enum("status", ["draft", "published"] as const)
+);
+
+const { jsonSchema, uiSchema } = buildFormSchemas(form);
 ```
 
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext"
+## Static Analysis
+
+`generateSchemas()` is the main entry point for TSDoc-backed generation.
+
+```ts
+import { generateSchemas } from "@formspec/build";
+
+const { jsonSchema, uiSchema } = generateSchemas({
+  filePath: "./src/forms.ts",
+  typeName: "ProductConfig",
+});
+```
+
+`generateSchemasFromClass()` remains available when the input is definitely a class declaration.
+
+```ts
+import { generateSchemasFromClass } from "@formspec/build";
+
+const result = generateSchemasFromClass({
+  filePath: "./src/forms.ts",
+  className: "ProductConfig",
+});
+```
+
+### Static Build Context
+
+Use the static build context APIs when you need to inspect exports, declarations,
+or method signatures before deciding what schemas to generate.
+
+Public helpers in this workflow:
+
+- `createStaticBuildContext(filePath)` - Create a reusable compiler-backed context from a file.
+- `createStaticBuildContextFromProgram(program, filePath)` - Reuse a host-owned `ts.Program`.
+- `resolveModuleExport(context, exportName?)` - Resolve any exported symbol, including functions and other non-schema declarations.
+- `resolveModuleExportDeclaration(context, exportName?)` - Resolve only schema-source declarations (`class`, `interface`, `type` alias).
+- `resolveDeclarationMetadata(...)` - Resolve metadata for named types, methods, and properties using FormSpec's active metadata policy.
+- `generateSchemasFromDeclaration(...)` - Generate from a resolved schema-source declaration.
+- `generateSchemasFromParameter(...)` - Generate from a method or function parameter declaration.
+- `generateSchemasFromReturnType(...)` - Generate from a method or function return type, unwrapping awaited `Promise<T>`-style returns before generation.
+- `generateSchemasFromType(...)` - Generate directly from a resolved `ts.Type`.
+
+Use `resolveModuleExportDeclaration(...)` when your tooling wants to hand a resolved
+declaration straight to `generateSchemasFromDeclaration(...)`. Use `resolveModuleExport(...)`
+when you need lower-level TypeScript access first, for example to inspect a function
+export and then generate schemas from one of its signature types.
+
+```ts
+import * as ts from "typescript";
+import {
+  createStaticBuildContext,
+  generateSchemasFromDeclaration,
+  generateSchemasFromParameter,
+  generateSchemasFromReturnType,
+  resolveDeclarationMetadata,
+  resolveModuleExport,
+  resolveModuleExportDeclaration,
+} from "@formspec/build";
+
+const context = createStaticBuildContext("./src/service.ts");
+const serviceDeclaration = resolveModuleExportDeclaration(context, "PaymentService");
+
+if (serviceDeclaration && ts.isClassDeclaration(serviceDeclaration)) {
+  const submitMethod = serviceDeclaration.members.find(
+    (member): member is ts.MethodDeclaration =>
+      ts.isMethodDeclaration(member) &&
+      ts.isIdentifier(member.name) &&
+      member.name.text === "submit"
+  );
+
+  if (submitMethod?.parameters[0]) {
+    const methodMetadata = resolveDeclarationMetadata({
+      context,
+      declaration: submitMethod,
+    });
+    const inputSchemas = generateSchemasFromParameter({
+      context,
+      parameter: submitMethod.parameters[0],
+    });
   }
 }
+
+const inputDeclaration = resolveModuleExportDeclaration(context, "SubmitInput");
+if (inputDeclaration) {
+  const inputSchemas = generateSchemasFromDeclaration({
+    context,
+    declaration: inputDeclaration,
+  });
+}
+
+const paymentSymbol = resolveModuleExport(context, "submitPayment");
+const paymentDeclaration = paymentSymbol?.declarations?.find(ts.isFunctionDeclaration);
+if (paymentDeclaration) {
+  const outputSchemas = generateSchemasFromReturnType({
+    context,
+    declaration: paymentDeclaration,
+  });
+}
 ```
 
-## Usage
+If you already own a `ts.Program`, use `createStaticBuildContextFromProgram(program, filePath)`
+instead of letting FormSpec create one. If your tool has already resolved a raw
+`ts.Type` or signature declaration, use `generateSchemasFromType(...)` or
+`generateSchemasFromReturnType(...)` directly.
 
-### Generate Schemas in Memory
+This is the supported public path for build-time analysis workflows that used to
+require `@formspec/build/internals`.
 
-```typescript
-import { buildFormSchemas } from "@formspec/build";
-import { formspec, field, group } from "@formspec/dsl";
+### Supported TSDoc Examples
 
-const ContactForm = formspec(
-  field.text("name", { label: "Name", required: true }),
-  field.text("email", { label: "Email", required: true }),
-  field.enum("subject", ["General", "Support", "Sales"]),
-);
+```ts
+export interface ProductConfig {
+  /** @displayName Product Name @minLength 1 */
+  name: string;
 
-const { jsonSchema, uiSchema } = buildFormSchemas(ContactForm);
+  /** @format email */
+  supportEmail?: string;
 
-// Use with JSON Forms renderer
-// <JsonForms schema={jsonSchema} uischema={uiSchema} data={formData} />
+  /** @placeholder Search products */
+  query?: string;
+
+  /** @minimum 0 @maximum 9999.99 */
+  price: number;
+
+  /** @uniqueItems */
+  tags: string[];
+}
 ```
 
-### Write Schemas to Disk
+## Extension-Aware Generation
 
-```typescript
-import { writeSchemas } from "@formspec/build";
+Static-analysis and mixed-authoring generation APIs accept `extensionRegistry` and `vendorPrefix`. Chain DSL generation accepts `vendorPrefix`, but not `extensionRegistry`.
 
-const result = writeSchemas(ContactForm, {
-  outDir: "./generated",
-  name: "contact-form",
-  indent: 2,
-});
+```ts
+import { createExtensionRegistry, generateSchemas } from "@formspec/build";
+
+const registry = createExtensionRegistry([myExtension]);
 
-console.log(`JSON Schema: ${result.jsonSchemaPath}`);
-console.log(`UI Schema: ${result.uiSchemaPath}`);
-// JSON Schema: ./generated/contact-form-schema.json
-// UI Schema: ./generated/contact-form-uischema.json
+const result = generateSchemas({
+  filePath: "./src/forms.ts",
+  typeName: "Invoice",
+  extensionRegistry: registry,
+  vendorPrefix: "x-acme",
+});
 ```
 
-### Use Individual Generators
+Generation validates canonical IR before emitting schemas. Invalid inputs now fail generation with structured diagnostic codes surfaced in the thrown error.
 
-```typescript
-import { generateJsonSchema, generateUiSchema } from "@formspec/build";
+### Handling Generation Failures
 
-const jsonSchema = generateJsonSchema(ContactForm);
-const uiSchema = generateUiSchema(ContactForm);
-```
+Static generation now uses explicit error reporting on the main entry points:
+
+- `generateSchemas({ ..., errorReporting: "throw" })` and `generateSchemasFromProgram({ ..., errorReporting: "throw" })` keep the simple throw-on-error contract.
+- `generateSchemas({ ..., errorReporting: "diagnostics" })` and `generateSchemasFromProgram({ ..., errorReporting: "diagnostics" })` return structured diagnostics instead of throwing for analysis and validation failures.
+- `generateSchemasBatch()` and `generateSchemasBatchFromProgram()` continue to return per-target diagnostics across multiple targets.
+
+Use the `"throw"` mode when you want "schema or failure" ergonomics. Use the `"diagnostics"` mode when you want to surface as much feedback as possible in one pass, especially in editor, CI, or migration tooling. The older `generateSchemasDetailed()` and `generateSchemasFromProgramDetailed()` wrappers remain available only as deprecated compatibility shims.
+
+```ts
+import { generateSchemas, generateSchemasBatch } from "@formspec/build";
+
+try {
+  const { jsonSchema, uiSchema } = generateSchemas({
+    filePath: "./src/forms.ts",
+    typeName: "Invoice",
+    errorReporting: "throw",
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+
+  if (message.includes("UNSUPPORTED_CUSTOM_TYPE_OVERRIDE")) {
+    // An extension tried to override a TS global built-in such as Date or Array
+  } else if (message.includes("SYNTHETIC_SETUP_FAILURE")) {
+    // Extension setup failed before tag type-checking could run
+  } else if (message.includes("TYPE_MISMATCH")) {
+    // A tag was applied to an incompatible field or target type
+  }
 
-## Generated Output
-
-### JSON Schema (Draft-07)
-
-```json
-{
-  "$schema": "https://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "name": { "type": "string", "title": "Name" },
-    "email": { "type": "string", "title": "Email" },
-    "subject": {
-      "type": "string",
-      "enum": ["General", "Support", "Sales"]
-    }
-  },
-  "required": ["name", "email"]
+  throw error;
+}
+
+const detailed = generateSchemas({
+  filePath: "./src/forms.ts",
+  typeName: "Invoice",
+  errorReporting: "diagnostics",
+});
+
+if (!detailed.ok) {
+  for (const diagnostic of detailed.diagnostics) {
+    console.error(`${diagnostic.code}: ${diagnostic.message}`);
+  }
 }
-```
 
-### JSON Forms UI Schema
+const batch = generateSchemasBatch({
+  targets: [
+    { filePath: "./src/forms.ts", typeName: "Invoice" },
+    { filePath: "./src/forms.ts", typeName: "PaymentTerms" },
+  ],
+});
 
-```json
-{
-  "type": "VerticalLayout",
-  "elements": [
-    { "type": "Control", "scope": "#/properties/name", "label": "Name" },
-    { "type": "Control", "scope": "#/properties/email", "label": "Email" },
-    { "type": "Control", "scope": "#/properties/subject" }
-  ]
+for (const result of batch) {
+  if (!result.ok) {
+    console.error(
+      `${result.typeName} failed: ${result.diagnostics.map((diagnostic) => diagnostic.code).join(", ")}`
+    );
+  }
 }
 ```
 
-## API Reference
+The most relevant codes for extension-backed static analysis failures are:
+
+- `UNSUPPORTED_CUSTOM_TYPE_OVERRIDE` for extension custom types that conflict with unsupported TypeScript global built-ins.
+- `SYNTHETIC_SETUP_FAILURE` for invalid or conflicting extension custom type registrations and other synthetic compiler setup failures.
+- `TYPE_MISMATCH` for normal tag-on-type incompatibilities in author source.
+- `TYPE_NOT_FOUND` when a requested exported target cannot be resolved.
+- `UNSUPPORTED_ROOT_TYPE` and `DUPLICATE_ROOT_PROPERTIES` when a requested type alias cannot be treated as a schema root.
+- `PROGRAM_CONTEXT_FAILURE` when the package cannot create or reuse a TypeScript program for the requested file.
+
+As a rule of thumb, `UNSUPPORTED_CUSTOM_TYPE_OVERRIDE` and `SYNTHETIC_SETUP_FAILURE` indicate extension configuration problems, while `TYPE_MISMATCH` usually indicates an authoring error in the analyzed source.
+
+## Internal Entry Point
 
-### Functions
+Low-level canonical IR generators, analyzer primitives, and validation helpers are intentionally no longer exported from the package root. If you need those unstable internals inside the monorepo, import them from `@formspec/build/internals`.
 
-| Function | Description |
-|----------|-------------|
-| `buildFormSchemas(form)` | Generate both JSON Schema and UI Schema |
-| `generateJsonSchema(form)` | Generate only JSON Schema |
-| `generateUiSchema(form)` | Generate only UI Schema |
-| `writeSchemas(form, options)` | Build and write schemas to disk |
+## Main Exports
 
-### Types
+- `buildFormSchemas(form, options?)`
+- `generateJsonSchema(form, options?)`
+- `generateUiSchema(form)`
+- `writeSchemas(form, options)`
+- `generateSchemas(options)`
+- `generateSchemasFromClass(options)`
+- `generateSchemasFromProgram(options)`
+- `generateSchemasBatch(options)`
+- `generateSchemasBatchFromProgram(options)`
+- `buildMixedAuthoringSchemas(options)`
+- `createExtensionRegistry(extensions)`
 
-| Type | Description |
-|------|-------------|
-| `BuildResult` | Return type of `buildFormSchemas` |
-| `WriteSchemasOptions` | Options for `writeSchemas` |
-| `WriteSchemasResult` | Return type of `writeSchemas` |
-| `JSONSchema7` | JSON Schema Draft-07 type |
-| `UISchema` | JSON Forms UI Schema type |
+`writeSchemas()` is the chain-DSL convenience wrapper for writing emitted files. Extension registries apply to the static-analysis and mixed-authoring generation flows above, not to `writeSchemas()`.
 
 ## License
 
-UNLICENSED
+This package is part of the FormSpec monorepo and is released under the MIT License. See [LICENSE](./LICENSE) for details.

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

@@ -0,0 +1,135 @@
+/**
+ * Class analyzer for extracting fields, types, and JSDoc constraints.
+ *
+ * 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 ConstraintSemanticDiagnostic } from "@formspec/analysis/internal";
+import type { FieldNode, TypeNode, AnnotationNode, TypeDefinition, JsonValue, ResolvedMetadata } from "@formspec/core/internals";
+import type { ExtensionRegistry } from "../extensions/index.js";
+import type { MetadataPolicyInput } from "@formspec/core";
+import { normalizeMetadataPolicy } from "../metadata/index.js";
+export declare function isResolvableObjectLikeAliasTypeNode(typeNode: ts.TypeNode): boolean;
+/**
+ * Layout metadata extracted from `@Group` and `@ShowWhen` TSDoc tags.
+ * One entry per field, in the same order as `fields`.
+ */
+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/interface/type alias into canonical IR.
+ */
+export interface IRClassAnalysis {
+    /** Type name */
+    readonly name: string;
+    /** Root-level metadata for the analyzed declaration. */
+    readonly metadata?: ResolvedMetadata;
+    /** 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>;
+    /** Root-level metadata for the analyzed declaration. */
+    readonly annotations?: readonly AnnotationNode[];
+    /** Extraction-time diagnostics surfaced before IR validation. */
+    readonly diagnostics?: readonly ConstraintSemanticDiagnostic[];
+    /** Instance methods (retained for downstream method-schema generation) */
+    readonly instanceMethods: readonly MethodInfo[];
+    /** Static methods */
+    readonly staticMethods: readonly MethodInfo[];
+}
+export type AnalyzeTypeAliasToIRFailureKind = "duplicate-properties" | "not-object-like";
+/**
+ * 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 kind: AnalyzeTypeAliasToIRFailureKind;
+    readonly error: string;
+};
+export interface DeclarationRootInfo {
+    readonly metadata?: ResolvedMetadata;
+    readonly annotations: readonly AnnotationNode[];
+    readonly diagnostics: readonly ConstraintSemanticDiagnostic[];
+}
+/**
+ * Discriminator-specific schema generation options.
+ *
+ * @public
+ */
+export interface DiscriminatorResolutionOptions {
+    /**
+     * Optional prefix applied only to metadata-derived discriminator values.
+     *
+     * Literal discriminator identities taken directly from a bound type remain
+     * unchanged.
+     */
+    readonly apiNamePrefix?: string | undefined;
+}
+interface AnalyzerMetadataPolicy {
+    readonly raw: MetadataPolicyInput | undefined;
+    readonly normalized: ReturnType<typeof normalizeMetadataPolicy>;
+    readonly discriminator: DiscriminatorResolutionOptions | undefined;
+}
+export declare function createAnalyzerMetadataPolicy(input?: MetadataPolicyInput, discriminator?: DiscriminatorResolutionOptions): AnalyzerMetadataPolicy;
+export declare function analyzeDeclarationRootInfo(declaration: ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration, checker: ts.TypeChecker, file?: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput): DeclarationRootInfo;
+/**
+ * Analyzes a class declaration and produces canonical IR FieldNodes.
+ */
+export declare function analyzeClassToIR(classDecl: ts.ClassDeclaration, checker: ts.TypeChecker, file?: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): IRClassAnalysis;
+/**
+ * Analyzes an interface declaration and produces canonical IR FieldNodes.
+ */
+export declare function analyzeInterfaceToIR(interfaceDecl: ts.InterfaceDeclaration, checker: ts.TypeChecker, file?: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): IRClassAnalysis;
+/**
+ * Analyzes a type alias declaration and produces canonical IR FieldNodes.
+ */
+export declare function analyzeTypeAliasToIR(typeAlias: ts.TypeAliasDeclaration, checker: ts.TypeChecker, file?: string, extensionRegistry?: ExtensionRegistry, metadataPolicy?: MetadataPolicyInput, discriminatorOptions?: DiscriminatorResolutionOptions): AnalyzeTypeAliasToIRResult;
+export declare function getAnalyzableObjectLikePropertyName(name: ts.PropertyName): string | null;
+/**
+ * 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>, sourceNode?: ts.Node, metadataPolicy?: AnalyzerMetadataPolicy, extensionRegistry?: ExtensionRegistry, diagnostics?: ConstraintSemanticDiagnostic[]): TypeNode;
+/**
+ * Analyzed method information.
+ */
+export interface MethodInfo {
+    /** Method name */
+    name: string;
+    /** Method parameters */
+    parameters: ParameterInfo[];
+    /** Return type node */
+    returnTypeNode: ts.TypeNode | undefined;
+    /** Resolved return type */
+    returnType: ts.Type;
+}
+/**
+ * Analyzed parameter information.
+ */
+export interface ParameterInfo {
+    /** Parameter name */
+    name: string;
+    /** TypeScript type node */
+    typeNode: ts.TypeNode | undefined;
+    /** Resolved type */
+    type: ts.Type;
+    /** If this is InferSchema<typeof X>, the export name X */
+    formSpecExportName: string | null;
+    /** Whether the parameter is optional (has ? or default value) */
+    optional: boolean;
+}
+export {};
+//# sourceMappingURL=class-analyzer.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,53 @@
+/**
+ * JSDoc constraint and annotation extractor.
+ *
+ * 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 (@displayName, etc.)
+ *
+ * The IR extraction path uses the official `@microsoft/tsdoc` parser for
+ * all canonical tags.
+ *
+ * Supported constraints correspond to the built-in FormSpec constraint tags
+ * (e.g., `@minimum`, `@maximum`, `@pattern`).
+ */
+import * as ts from "typescript";
+import type { ConstraintNode, AnnotationNode } from "@formspec/core/internals";
+import { type ParseTSDocOptions, type TSDocParseResult } from "./tsdoc-parser.js";
+export declare function extractJSDocParseResult(node: ts.Node, file?: string, options?: ParseTSDocOptions): TSDocParseResult;
+/**
+ * Extracts constraints from JSDoc comments on a TypeScript AST node and returns
+ * canonical {@link ConstraintNode} objects.
+ *
+ * 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
+ * @param file - Absolute path to the source file for provenance
+ * @returns Canonical constraint nodes for each valid constraint tag
+ */
+export declare function extractJSDocConstraintNodes(node: ts.Node, file?: string, options?: ParseTSDocOptions): ConstraintNode[];
+/**
+ * Extracts canonical annotation tags from a node and returns
+ * {@link AnnotationNode} objects.
+ *
+ * @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, options?: ParseTSDocOptions): 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;
+//# sourceMappingURL=jsdoc-constraints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsdoc-constraints.d.ts","sourceRoot":"","sources":["../../src/analyzer/jsdoc-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAa,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAM3B,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,SAAK,EACT,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAElB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,SAAK,EACT,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,EAAE,CAGlB;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,IAAI,SAAK,EACT,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,EAAE,CAGlB;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"}