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

package/dist/build.d.ts

@@ -2,7 +2,7 @@
  * `@formspec/build` - Build tools for FormSpec
  *
  * This package provides generators to compile FormSpec forms into:
- * - JSON Schema (for validation)
+ * - JSON Schema 2020-12 (for validation)
  * - JSON Forms UI Schema (for rendering)
  *
  * @example
@@ -23,8 +23,37 @@
  * @packageDocumentation
  */
 
-import type { FormElement } from '@formspec/core';
-import type { FormSpec } from '@formspec/core';
+import { AnyField } from '@formspec/core';
+import { ArrayField } from '@formspec/core';
+import { BooleanField } from '@formspec/core';
+import { BuiltinConstraintBroadeningRegistration } from '@formspec/core';
+import { Conditional } from '@formspec/core';
+import { ConstraintTagRegistration } from '@formspec/core';
+import { CustomAnnotationRegistration } from '@formspec/core';
+import { CustomConstraintRegistration } from '@formspec/core';
+import { CustomTypeRegistration } from '@formspec/core';
+import { DynamicEnumField } from '@formspec/core';
+import { DynamicSchemaField } from '@formspec/core';
+import { EnumOption } from '@formspec/core';
+import { EnumOptionValue } from '@formspec/core';
+import { ExtensionDefinition } from '@formspec/core';
+import { FormElement } from '@formspec/core';
+import { FormSpec } from '@formspec/core';
+import { Group } from '@formspec/core';
+import type { MetadataPolicyInput } from '@formspec/core';
+import { NumberField } from '@formspec/core';
+import { ObjectField } from '@formspec/core';
+import type { ResolvedMetadata } from '@formspec/core';
+import { StaticEnumField } from '@formspec/core';
+import { TextField } from '@formspec/core';
+import * as ts from 'typescript';
+import { z } from 'zod';
+
+export { AnyField }
+
+export { ArrayField }
+
+export { BooleanField }
 
 /**
  * Builds both JSON Schema and UI Schema from a FormSpec.
@@ -52,30 +81,354 @@ import type { FormSpec } from '@formspec/core';
  *
  * @param form - The FormSpec to build schemas from
  * @returns Object containing both jsonSchema and uiSchema
+ *
+ * @public
+ */
+export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options?: BuildFormSchemasOptions): BuildResult;
+
+/**
+ * Options for building schemas from a FormSpec.
+ *
+ * Currently identical to `GenerateJsonSchemaOptions`. Defined separately so the
+ * Chain DSL surface can grow independently in the future if needed.
+ *
+ * @public
  */
-export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>): BuildResult;
+export declare interface BuildFormSchemasOptions extends GenerateJsonSchemaOptions, GenerateUiSchemaOptions {
+}
+
+/**
+ * Builds JSON Schema and UI Schema from a TSDoc-derived model with ChainDSL
+ * field overlays.
+ *
+ * Overlays are matched by field name. The static model wins for structure,
+ * ordering, and constraints; ChainDSL overlays may contribute dynamic runtime
+ * field metadata such as dynamic enum or dynamic schema keywords, and may fill
+ * in missing annotations.
+ *
+ * @public
+ */
+export declare function buildMixedAuthoringSchemas(options: BuildMixedAuthoringSchemasOptions): MixedAuthoringSchemas;
+
+/**
+ * Options for generating mixed-authoring schemas.
+ *
+ * The `typeName` can resolve to a class, interface, or object type alias, just
+ * like `generateSchemas()`.
+ *
+ * @public
+ */
+export declare interface BuildMixedAuthoringSchemasOptions extends StaticSchemaGenerationOptions {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the class, interface, or type alias to analyze. */
+    readonly typeName: string;
+    /** ChainDSL overlays to apply to the static model. Groups and conditionals are flattened by field name. */
+    readonly overlays: FormSpec<readonly FormElement[]>;
+}
 
 /**
  * Result of building form schemas.
+ *
+ * @public
  */
 export declare interface BuildResult {
-    /** JSON Schema for validation */
-    readonly jsonSchema: JSONSchema7;
+    /** JSON Schema 2020-12 for validation */
+    readonly jsonSchema: JsonSchema2020;
     /** JSON Forms UI Schema for rendering */
     readonly uiSchema: UISchema;
 }
 
+export { BuiltinConstraintBroadeningRegistration }
+
+/**
+ * A Categorization element (tab-based layout).
+ *
+ * @public
+ */
+export declare interface Categorization {
+    /** Discriminator identifying a categorization layout. */
+    readonly type: "Categorization";
+    /** Categories rendered as tabs or steps. */
+    readonly elements: Category[];
+    /** Optional label for the overall categorization container. */
+    readonly label?: string | undefined;
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific categorization options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+/**
+ * A Category element, used inside a Categorization layout.
+ *
+ * @public
+ */
+export declare interface Category {
+    /** Discriminator identifying a category inside a categorization layout. */
+    readonly type: "Category";
+    /** Category label shown in tabs or step navigation. */
+    readonly label: string;
+    /** Child elements rendered inside the category. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific category options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+export { Conditional }
+
+export { ConstraintTagRegistration }
+
 /**
  * A Control element that binds to a JSON Schema property.
+ *
+ * @public
+ */
+export declare interface ControlElement {
+    /** Discriminator identifying a JSON Forms control element. */
+    readonly type: "Control";
+    /** JSON Pointer scope that this control binds to. */
+    readonly scope: string;
+    /** Optional label override, or `false` to suppress the label. */
+    readonly label?: string | false | undefined;
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific control options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+/**
+ * Creates an extension registry from a list of extension definitions.
+ *
+ * The registry indexes all types, constraints, and annotations by their
+ * fully-qualified IDs (`<extensionId>/<name>`) for O(1) lookup during
+ * generation and validation.
+ *
+ * @param extensions - The extension definitions to register.
+ * @returns An {@link ExtensionRegistry} instance.
+ * @throws If duplicate type/constraint/annotation IDs are detected across extensions.
+ *
+ * @public
+ */
+export declare function createExtensionRegistry(extensions: readonly ExtensionDefinition[]): ExtensionRegistry;
+
+/**
+ * Creates a supported static build context for a source file.
+ *
+ * @param filePath - Entry TypeScript source file used for export resolution
+ * @returns Reusable build context containing the program, checker, and source file
+ *
+ * @public
+ */
+export declare function createStaticBuildContext(filePath: string): StaticBuildContext;
+
+/**
+ * Creates a supported static build context from an existing host-owned program.
+ *
+ * @param program - Existing TypeScript program supplied by the caller
+ * @param filePath - Entry TypeScript source file used for export resolution
+ * @returns Reusable build context containing the program, checker, and source file
+ *
+ * @public
  */
-export declare interface ControlElement extends UISchemaElementBase {
-    type: "Control";
-    scope: string;
-    label?: string;
+export declare function createStaticBuildContextFromProgram(program: ts.Program, filePath: string): StaticBuildContext;
+
+export { CustomAnnotationRegistration }
+
+export { CustomConstraintRegistration }
+
+export { CustomTypeRegistration }
+
+/**
+ * Non-throwing schema generation result with structured diagnostics.
+ *
+ * @public
+ */
+export declare interface DetailedClassSchemasResult {
+    /** Whether schema generation completed without error-severity diagnostics. */
+    readonly ok: boolean;
+    /** Collected analysis and validation diagnostics for this target. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** JSON Schema 2020-12 for validation, when generation succeeds. */
+    readonly jsonSchema?: JsonSchema2020 | undefined;
+    /** JSON Forms UI Schema for rendering, when generation succeeds. */
+    readonly uiSchema?: UISchema | undefined;
 }
 
 /**
- * Generates a JSON Schema from a FormSpec.
+ * Result for a single target in a batch generation request.
+ *
+ * @public
+ */
+export declare interface DetailedSchemaGenerationTargetResult extends DetailedClassSchemasResult {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias that was analyzed. */
+    readonly typeName: string;
+}
+
+/**
+ * Generated schemas for a discovered declaration or signature type.
+ *
+ * `uiSchema` is `null` when the discovered type does not have an object-shaped
+ * root that can be represented as a JSON Forms layout.
+ *
+ * @public
+ */
+export declare interface DiscoveredTypeSchemas {
+    /** JSON Schema 2020-12 for the resolved type. */
+    readonly jsonSchema: JsonSchema2020;
+    /** UI Schema for object-shaped roots, or `null` when not applicable. */
+    readonly uiSchema: UISchema | null;
+    /**
+     * Resolved type-level metadata used during generation, when available.
+     *
+     * This preserves explicit and inferred naming metadata such as singular and
+     * plural API/display names for consumers that need the resolved values in
+     * addition to the emitted schema artifacts.
+     */
+    readonly resolvedMetadata?: ResolvedMetadata | undefined;
+}
+
+/**
+ * Discriminator-specific schema generation options.
+ *
+ * @public
+ */
+export declare 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;
+}
+
+export { DynamicEnumField }
+
+export { DynamicSchemaField }
+
+export { EnumOption }
+
+export { EnumOptionValue }
+
+/**
+ * JSON Schema with FormSpec extension properties for arbitrary `x-formspec-*` keys.
+ *
+ * @public
+ */
+export declare type ExtendedJSONSchema7 = JSONSchema7 & FormSpecSchemaExtensions;
+
+export { ExtensionDefinition }
+
+/**
+ * A registry of extensions that provides lookup by fully-qualified ID.
+ *
+ * Type IDs follow the format: `<extensionId>/<typeName>`
+ * Constraint IDs follow the format: `<extensionId>/<constraintName>`
+ * Annotation IDs follow the format: `<extensionId>/<annotationName>`
+ *
+ * @public
+ */
+export declare interface ExtensionRegistry {
+    /** The extensions registered in this registry (in registration order). */
+    readonly extensions: readonly ExtensionDefinition[];
+    /**
+     * Look up a custom type registration by its fully-qualified type ID.
+     *
+     * @param typeId - The fully-qualified type ID (e.g., "x-stripe/monetary/Decimal").
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findType(typeId: string): CustomTypeRegistration | undefined;
+    /**
+     * Look up a custom type registration by a TypeScript-facing type name.
+     *
+     * This is used during TSDoc/class analysis to resolve extension-defined
+     * custom types from source-level declarations.
+     */
+    findTypeByName(typeName: string): {
+        readonly extensionId: string;
+        readonly registration: CustomTypeRegistration;
+    } | undefined;
+    /**
+     * Look up a custom constraint registration by its fully-qualified constraint ID.
+     *
+     * @param constraintId - The fully-qualified constraint ID.
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findConstraint(constraintId: string): CustomConstraintRegistration | undefined;
+    /**
+     * Look up a TSDoc custom constraint-tag registration by tag name.
+     */
+    findConstraintTag(tagName: string): {
+        readonly extensionId: string;
+        readonly registration: ConstraintTagRegistration;
+    } | undefined;
+    /**
+     * Look up built-in tag broadening for a given custom type ID.
+     */
+    findBuiltinConstraintBroadening(typeId: string, tagName: string): {
+        readonly extensionId: string;
+        readonly registration: BuiltinConstraintBroadeningRegistration;
+    } | undefined;
+    /**
+     * Look up a custom annotation registration by its fully-qualified annotation ID.
+     *
+     * @param annotationId - The fully-qualified annotation ID.
+     * @returns The registration if found, otherwise `undefined`.
+     */
+    findAnnotation(annotationId: string): CustomAnnotationRegistration | undefined;
+}
+
+export { FormElement }
+
+export { FormSpec }
+
+/**
+ * Extension properties for custom FormSpec constraint tags.
+ *
+ * @public
+ */
+export declare type FormSpecSchemaExtensions = Record<`x-formspec-${string}`, unknown>;
+
+/**
+ * Options for generating schemas from a decorated class.
+ *
+ * @public
+ */
+export declare interface GenerateFromClassOptions extends StaticSchemaGenerationOptions {
+    /** Path to the TypeScript source file */
+    filePath: string;
+    /** Class name to analyze */
+    className: string;
+}
+
+/**
+ * Result of generating schemas from a decorated class.
+ *
+ * @public
+ */
+export declare interface GenerateFromClassResult {
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+
+/**
+ * Generates a JSON Schema 2020-12 from a FormSpec.
+ *
+ * All generation routes through the canonical IR. The chain DSL is first
+ * canonicalized to a FormIR, then the IR-based generator produces the schema.
  *
  * @example
  * ```typescript
@@ -86,7 +439,7 @@ export declare interface ControlElement extends UISchemaElementBase {
  *
  * const schema = generateJsonSchema(form);
  * // {
- * //   $schema: "https://json-schema.org/draft-07/schema#",
+ * //   $schema: "https://json-schema.org/draft/2020-12/schema",
  * //   type: "object",
  * //   properties: {
  * //     name: { type: "string", title: "Name" },
@@ -97,13 +450,357 @@ export declare interface ControlElement extends UISchemaElementBase {
  * ```
  *
  * @param form - The FormSpec to convert
- * @returns A JSON Schema object
+ * @returns A JSON Schema 2020-12 object
+ *
+ * @public
+ */
+export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>, options?: GenerateJsonSchemaOptions): JsonSchema2020;
+
+/**
+ * Options for generating JSON Schema from a Chain DSL form.
+ *
+ * @public
+ */
+export declare interface GenerateJsonSchemaOptions {
+    /**
+     * Vendor prefix for emitted extension keywords.
+     * @defaultValue "x-formspec"
+     */
+    readonly vendorPrefix?: string | undefined;
+    /** Metadata resolution policy for chain DSL generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named TypeScript
+ * type — a decorated class, an interface with TSDoc tags, or a type alias.
+ *
+ * This is the recommended entry point. It automatically detects whether
+ * the name resolves to a class, interface, or type alias and uses the
+ * appropriate IR analysis pipeline.
+ *
+ * @example
+ * ```typescript
+ * const result = generateSchemas({
+ *   filePath: "./src/config.ts",
+ *   typeName: "DiscountConfig",
+ *   errorReporting: "throw",
+ * });
+ * ```
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type and throws when
+ * generation reports error-severity diagnostics.
+ *
+ * @param options - File path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
+ *
+ * @param options - File path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
+ * @param options - File path and type name
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemas(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates schemas for many targets and returns per-target diagnostics instead
+ * of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatch(options: GenerateSchemasBatchOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Generates schemas for many targets from an existing TypeScript program and
+ * returns per-target diagnostics instead of failing on the first problem.
+ *
+ * @public
+ */
+export declare function generateSchemasBatchFromProgram(options: GenerateSchemasBatchFromProgramOptions): readonly DetailedSchemaGenerationTargetResult[];
+
+/**
+ * Batch options for non-throwing schema generation using an existing program.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Batch options for non-throwing schema generation.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasBatchOptions extends StaticSchemaGenerationOptions {
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named type and returns structured
+ * diagnostics instead of throwing on validation or analysis failures.
+ * @deprecated Use `generateSchemas({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasDetailed(options: StaticSchemaGenerationOptions & {
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a decorated TypeScript class.
+ *
+ * This is a high-level entry point that handles the entire pipeline:
+ * creating a TypeScript program, finding the class, analyzing it to IR,
+ * and generating schemas — all in one call.
+ *
+ * @example
+ * ```typescript
+ * const result = generateSchemasFromClass({
+ *   filePath: "./src/forms.ts",
+ *   className: "UserForm",
+ * });
+ * console.log(result.jsonSchema);
+ * ```
+ *
+ * @param options - File path, class name, and optional compiler options
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromClass(options: GenerateFromClassOptions): GenerateFromClassResult;
+
+/**
+ * Generates schemas from a resolved declaration using the supported public
+ * static-build workflow.
+ *
+ * Named declarations reuse the same analyzer semantics as FormSpec's existing
+ * top-level generation APIs. Non-object type aliases fall back to the generic
+ * resolved-type entry point.
+ *
+ * @public
+ */
+export declare function generateSchemasFromDeclaration(options: GenerateSchemasFromDeclarationOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a resolved declaration.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromDeclarationOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration to turn into schemas. */
+    readonly declaration: SchemaSourceDeclaration;
+}
+
+/**
+ * Generates schemas for a method or function parameter type.
+ *
+ * @public
+ */
+export declare function generateSchemasFromParameter(options: GenerateSchemasFromParameterOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a method or function parameter type.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromParameterOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Parameter declaration whose type should be converted into schemas. */
+    readonly parameter: ts.ParameterDeclaration;
+}
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program supplied by the caller.
+ *
+ * This low-level entry point lets downstream tooling reuse a host-owned
+ * `Program` for both FormSpec extraction and other TypeScript analysis.
+ */
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and throws when generation reports error-severity diagnostics.
+ *
+ * @param options - Host program, file path, type name, and explicit throw-on-error reporting
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "throw";
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ *
+ * @param options - Host program, file path, type name, and explicit diagnostics reporting
+ * @returns Structured generation result with diagnostics
+ *
+ * @public
  */
-export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>): JSONSchema7;
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions & {
+    readonly errorReporting: "diagnostics";
+}): DetailedClassSchemasResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program.
+ *
+ * @deprecated Pass `errorReporting` explicitly. Omitting it defaults to `"throw"` only for backward compatibility.
+ * @param options - Host program, file path, and type name
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and UI Schema from a named type within an existing
+ * TypeScript program and returns structured diagnostics instead of throwing on
+ * validation or analysis failures.
+ * @deprecated Use `generateSchemasFromProgram({ ...options, errorReporting: "diagnostics" })` instead.
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgramDetailed(options: StaticSchemaGenerationOptions & {
+    readonly program: ts.Program;
+    readonly filePath: string;
+    readonly typeName: string;
+}): DetailedClassSchemasResult;
+
+/**
+ * Options for generating schemas from a named type inside an existing TypeScript program.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Path to the TypeScript source file */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze */
+    readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
+}
+
+/**
+ * Generates schemas for a method or function return type.
+ *
+ * Awaited `Promise<T>`-style return types are unwrapped before generation.
+ *
+ * @public
+ */
+export declare function generateSchemasFromReturnType(options: GenerateSchemasFromReturnTypeOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a method or function return type.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromReturnTypeOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Signature declaration whose return type should be converted into schemas. */
+    readonly declaration: ts.SignatureDeclaration;
+}
+
+/**
+ * Generates schemas from a resolved TypeScript type.
+ *
+ * This is the advanced public entry point for build tooling that already uses
+ * the TypeScript compiler API to discover types before handing them to
+ * FormSpec.
+ *
+ * @public
+ */
+export declare function generateSchemasFromType(options: GenerateSchemasFromTypeOptions): DiscoveredTypeSchemas;
+
+/**
+ * Options for generating schemas from a resolved TypeScript type.
+ *
+ * @public
+ */
+export declare interface GenerateSchemasFromTypeOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** TypeScript type to turn into schemas. */
+    readonly type: ts.Type;
+    /**
+     * Optional source node associated with the type.
+     *
+     * When provided, FormSpec uses it as the source location for provenance and
+     * inline-type analysis.
+     */
+    readonly sourceNode?: ts.Node | undefined;
+    /** Optional logical name used for anonymous roots. */
+    readonly name?: string | undefined;
+}
+
+/**
+ * Options for generating schemas from a named type (class, interface, or type alias).
+ *
+ * @public
+ */
+export declare interface GenerateSchemasOptions extends StaticSchemaGenerationOptions {
+    /** Path to the TypeScript source file */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze */
+    readonly typeName: string;
+    /**
+     * Controls whether error-severity diagnostics throw or are returned in the result.
+     */
+    readonly errorReporting: "throw" | "diagnostics";
+}
 
 /**
  * Generates a JSON Forms UI Schema from a FormSpec.
  *
+ * All generation routes through the canonical IR. The chain DSL is first
+ * canonicalized to a FormIR, then the IR-based generator produces the schema.
+ *
  * @example
  * ```typescript
  * const form = formspec(
@@ -141,59 +838,199 @@ export declare function generateJsonSchema<E extends readonly FormElement[]>(for
  *
  * @param form - The FormSpec to convert
  * @returns A JSON Forms UI Schema
+ *
+ * @public
+ */
+export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>, options?: GenerateUiSchemaOptions): UISchema;
+
+/**
+ * Options for generating a UI Schema from a Chain DSL form.
+ *
+ * @public
  */
-export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>): UISchema;
+export declare interface GenerateUiSchemaOptions {
+    /** Metadata resolution policy for chain DSL UI generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
+}
+
+export { Group }
 
 /**
  * A group element with a label.
+ *
+ * @public
  */
-export declare interface GroupLayout extends UISchemaElementBase {
-    type: "Group";
-    label: string;
-    elements: UISchemaElement[];
+export declare interface GroupLayout {
+    /** Discriminator identifying a labeled group container. */
+    readonly type: "Group";
+    /** Group label shown by compatible renderers. */
+    readonly label: string;
+    /** Child elements rendered inside the group. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific group options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
 }
 
 /**
  * A horizontal layout element.
+ *
+ * @public
  */
-export declare interface HorizontalLayout extends UISchemaElementBase {
-    type: "HorizontalLayout";
-    elements: UISchemaElement[];
+export declare interface HorizontalLayout {
+    /** Discriminator identifying a horizontal layout container. */
+    readonly type: "HorizontalLayout";
+    /** Child elements rendered side by side. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific layout options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
 }
 
 /**
- * A JSON Schema definition (draft-07 subset).
+ * A JSON Schema 2020-12 document, sub-schema, or keyword collection.
+ *
+ * This interface covers the subset of JSON Schema 2020-12 that this generator
+ * emits, plus an index signature for custom `x-formspec-*` extension keywords.
+ *
+ * @public
+ */
+export declare interface JsonSchema2020 {
+    /** Declared JSON Schema dialect URI for the document root. */
+    $schema?: string;
+    /** Reference to another schema location. */
+    $ref?: string;
+    /** Named reusable schema definitions keyed by definition name. */
+    $defs?: Record<string, JsonSchema2020>;
+    /** JSON Schema type keyword for the current node. */
+    type?: string;
+    /** Object properties keyed by property name. */
+    properties?: Record<string, JsonSchema2020>;
+    /** Property names that must be present on object values. */
+    required?: string[];
+    /** Item schema applied to array elements. */
+    items?: JsonSchema2020;
+    /** Whether, or how, additional object properties are allowed. */
+    additionalProperties?: boolean | JsonSchema2020;
+    /** Closed set of allowed scalar values. */
+    enum?: readonly (string | number)[];
+    /** Literal value the instance must equal. */
+    const?: unknown;
+    /** Schemas that must all validate successfully. */
+    allOf?: readonly JsonSchema2020[];
+    /** Schemas of which exactly one should validate successfully. */
+    oneOf?: readonly JsonSchema2020[];
+    /** Schemas of which at least one may validate successfully. */
+    anyOf?: readonly JsonSchema2020[];
+    /** Inclusive numeric lower bound. */
+    minimum?: number;
+    /** Inclusive numeric upper bound. */
+    maximum?: number;
+    /** Exclusive numeric lower bound. */
+    exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound. */
+    exclusiveMaximum?: number;
+    /** Required numeric step interval. */
+    multipleOf?: number;
+    /** Inclusive minimum string length. */
+    minLength?: number;
+    /** Inclusive maximum string length. */
+    maxLength?: number;
+    /** Inclusive minimum array length. */
+    minItems?: number;
+    /** Inclusive maximum array length. */
+    maxItems?: number;
+    /** Regular expression pattern applied to string values. */
+    pattern?: string;
+    /** Whether array elements must be unique. */
+    uniqueItems?: boolean;
+    /** Format hint for downstream validators and tooling. */
+    format?: string;
+    /** Human-readable title for the schema node. */
+    title?: string;
+    /** Human-readable description for the schema node. */
+    description?: string;
+    /** Default value suggested for the schema node. */
+    default?: unknown;
+    /** Whether the schema node is deprecated. */
+    deprecated?: boolean;
+    /** Additional vendor-prefixed extension keywords. */
+    [key: `x-${string}`]: unknown;
+}
+
+/**
+ * A JSON Schema definition (legacy subset used by Zod validator and types.ts).
+ *
+ * @public
  */
 export declare interface JSONSchema7 {
+    /** Declared JSON Schema dialect URI for the document root. */
     $schema?: string;
+    /** Stable identifier for the schema document or sub-schema. */
     $id?: string;
+    /** Reference to another schema location. */
     $ref?: string;
+    /** Human-readable title for the schema node. */
     title?: string;
+    /** Human-readable description for the schema node. */
     description?: string;
+    /** Whether the schema node is deprecated. */
+    deprecated?: boolean;
+    /** JSON Schema type keyword for the current node. */
     type?: JSONSchemaType | JSONSchemaType[];
+    /** Inclusive minimum string length. */
     minLength?: number;
+    /** Inclusive maximum string length. */
     maxLength?: number;
+    /** Regular expression pattern applied to string values. */
     pattern?: string;
+    /** Inclusive numeric lower bound. */
     minimum?: number;
+    /** Inclusive numeric upper bound. */
     maximum?: number;
+    /** Exclusive numeric lower bound. */
     exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound. */
     exclusiveMaximum?: number;
+    /** Closed set of allowed scalar values. */
     enum?: readonly (string | number | boolean | null)[];
+    /** Literal value the instance must equal. */
     const?: string | number | boolean | null;
+    /** Object properties keyed by property name. */
     properties?: Record<string, JSONSchema7>;
+    /** Property names that must be present on object values. */
     required?: string[];
+    /** Whether, or how, additional object properties are allowed. */
     additionalProperties?: boolean | JSONSchema7;
+    /** Item schema or tuple schemas applied to array elements. */
     items?: JSONSchema7 | JSONSchema7[];
+    /** Inclusive minimum array length. */
     minItems?: number;
+    /** Inclusive maximum array length. */
     maxItems?: number;
+    /** Schemas that must all validate successfully. */
     allOf?: JSONSchema7[];
+    /** Schemas of which at least one may validate successfully. */
     anyOf?: JSONSchema7[];
+    /** Schemas of which exactly one should validate successfully. */
     oneOf?: JSONSchema7[];
+    /** Schema that must not validate successfully. */
     not?: JSONSchema7;
+    /** Conditional branch predicate schema. */
     if?: JSONSchema7;
+    /** Schema applied when the `if` branch matches. */
     then?: JSONSchema7;
+    /** Schema applied when the `if` branch does not match. */
     else?: JSONSchema7;
+    /** Format hint for downstream validators and tooling. */
     format?: string;
+    /** Default value suggested for the schema node. */
     default?: unknown;
     /**
      * Data source key for dynamic enum fields.
@@ -213,85 +1050,383 @@ export declare interface JSONSchema7 {
 }
 
 /**
- * JSON Schema Draft-07 type definitions.
+ * Zod schema for the legacy JSON Schema 7 subset used by `@formspec/build`.
+ *
+ * @public
+ */
+export declare const jsonSchema7Schema: z.ZodType<JSONSchema7>;
+
+/**
+ * JSON Schema type definitions.
  *
  * These types are a subset of JSON Schema sufficient for form generation.
  */
 /**
  * JSON Schema primitive types.
+ *
+ * @public
  */
 export declare type JSONSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
 
+/**
+ * A Label element for displaying static text.
+ *
+ * @public
+ */
+export declare interface LabelElement {
+    /** Discriminator identifying a static text label element. */
+    readonly type: "Label";
+    /** Static text content rendered by the label element. */
+    readonly text: string;
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific label options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
+}
+
+/**
+ * Supported declaration kinds for standalone metadata resolution.
+ *
+ * This helper is intentionally limited to named type declarations,
+ * methods/functions, and object-like properties. It does not currently expose
+ * parameter or variable metadata resolution on the public build surface.
+ *
+ * @public
+ */
+export declare type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
+
+/**
+ * Result of generating schemas from a mixed-authoring composition.
+ *
+ * @public
+ */
+export declare interface MixedAuthoringSchemas {
+    /** JSON Schema 2020-12 for validation. */
+    readonly jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering. */
+    readonly uiSchema: UISchema;
+}
+
+export { NumberField }
+
+export { ObjectField }
+
+/**
+ * Resolves metadata from a declaration using FormSpec's configured metadata
+ * policy for the matching declaration kind.
+ *
+ * @public
+ */
+export declare function resolveDeclarationMetadata(options: ResolveDeclarationMetadataOptions): ResolvedMetadata | undefined;
+
+/**
+ * Options for resolving metadata from a declaration against the active
+ * metadata policy.
+ *
+ * @public
+ */
+export declare interface ResolveDeclarationMetadataOptions extends StaticSchemaGenerationOptions {
+    /** Supported build context used for checker access and related analysis. */
+    readonly context: StaticBuildContext;
+    /** Declaration whose metadata should be resolved. */
+    readonly declaration: MetadataSourceDeclaration;
+}
+
+/**
+ * Resolves an export from the context source file, following aliases and re-exports.
+ *
+ * @param context - Static build context created for the entry source file
+ * @param exportName - Export name to resolve. Defaults to `"default"`.
+ * @returns Resolved symbol for the export, or `null` when it cannot be found
+ *
+ * @public
+ */
+export declare function resolveModuleExport(context: StaticBuildContext, exportName?: string): ts.Symbol | null;
+
+/**
+ * Resolves the declaration behind an export from the context source file,
+ * following aliases and re-exports. This helper is intentionally limited to
+ * declaration kinds accepted by declaration-driven schema generation.
+ *
+ * @param context - Static build context created for the entry source file
+ * @param exportName - Export name to resolve. Defaults to `"default"`.
+ * @returns Resolved class, interface, or type-alias declaration for the export,
+ * or `null` when the export does not resolve to one of those schema-source kinds
+ *
+ * @public
+ */
+export declare function resolveModuleExportDeclaration(context: StaticBuildContext, exportName?: string): ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration | null;
+
 /**
  * Rule for conditional element visibility/enablement.
+ *
+ * @public
  */
 export declare interface Rule {
-    effect: RuleEffect;
-    condition: SchemaBasedCondition;
+    /** UI effect to apply when the rule condition matches. */
+    readonly effect: RuleEffect;
+    /** Predicate that controls when the UI effect applies. */
+    readonly condition: SchemaBasedCondition;
 }
 
 /**
- * JSON Schema subset for rule conditions.
+ * JSON Schema subset used in rule conditions.
+ *
+ * @public
  */
-declare interface RuleConditionSchema {
+export declare interface RuleConditionSchema {
+    /** Literal value the condition schema must equal. */
     const?: unknown;
+    /** Allowed values for the condition schema. */
     enum?: readonly unknown[];
+    /** JSON Schema type required by the condition schema. */
     type?: string;
+    /** Negated branch of the condition schema. */
+    not?: RuleConditionSchema;
+    /** Inclusive numeric lower bound in the condition schema. */
     minimum?: number;
+    /** Inclusive numeric upper bound in the condition schema. */
     maximum?: number;
+    /** Exclusive numeric lower bound in the condition schema. */
+    exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound in the condition schema. */
+    exclusiveMaximum?: number;
+    /** Inclusive minimum string length in the condition schema. */
+    minLength?: number;
+    /** Nested property conditions keyed by property name. */
     properties?: Record<string, RuleConditionSchema>;
+    /** Property names that must be present for the condition to match. */
+    required?: string[];
+    /** Schemas that must all match for the condition to succeed. */
     allOf?: RuleConditionSchema[];
 }
 
+/**
+ * JSON Forms UI Schema type definitions.
+ *
+ * These are the consumer-facing TypeScript shapes. Runtime validation remains
+ * defined separately in `./schema.ts`.
+ *
+ * See: https://jsonforms.io/docs/uischema/
+ */
 /**
  * Rule effect types for conditional visibility.
+ *
+ * @public
  */
 export declare type RuleEffect = "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
 
 /**
  * Condition for a rule.
+ *
+ * @public
  */
 export declare interface SchemaBasedCondition {
-    scope: string;
-    schema: RuleConditionSchema;
+    /** JSON Pointer scope the rule evaluates against. */
+    readonly scope: string;
+    /** JSON Schema fragment evaluated at the scoped location. */
+    readonly schema: RuleConditionSchema;
 }
 
 /**
- * Root UI Schema (always a layout).
+ * A batch target for non-throwing schema generation.
+ *
+ * @public
  */
-export declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout;
+export declare interface SchemaGenerationTarget {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze. */
+    readonly typeName: string;
+}
+
+/**
+ * Supported declaration kinds for declaration-driven schema generation.
+ *
+ * @public
+ */
+export declare type SchemaSourceDeclaration = ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+
+/**
+ * Supported compiler context for static build-time analysis workflows.
+ *
+ * This context gives consumers access to the TypeScript program, checker, and
+ * source file used to discover declarations before invoking FormSpec schema
+ * generation helpers.
+ *
+ * @public
+ */
+export declare interface StaticBuildContext {
+    /** Host-owned or FormSpec-created TypeScript program. */
+    readonly program: ts.Program;
+    /** TypeScript checker for symbol and type analysis. */
+    readonly checker: ts.TypeChecker;
+    /** Source file used as the entry module for export resolution. */
+    readonly sourceFile: ts.SourceFile;
+}
+
+export { StaticEnumField }
+
+/**
+ * Shared options for schema generation flows that support custom extensions.
+ *
+ * @public
+ */
+export declare interface StaticSchemaGenerationOptions {
+    /**
+     * Registry used to resolve custom types, constraints, and annotations.
+     */
+    readonly extensionRegistry?: ExtensionRegistry | undefined;
+    /**
+     * Vendor prefix for emitted extension keywords.
+     * @defaultValue "x-formspec"
+     */
+    readonly vendorPrefix?: string | undefined;
+    /** Metadata resolution policy for static schema generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
+    /** Discriminator-specific schema generation behavior. */
+    readonly discriminator?: DiscriminatorResolutionOptions | undefined;
+}
+
+export { TextField }
+
+/**
+ * Root UI Schema (always a layout — not a Control, Category, or Label).
+ *
+ * @public
+ */
+export declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout | Categorization;
 
 /**
  * Union of all UI Schema element types.
+ *
+ * @public
  */
-export declare type UISchemaElement = ControlElement | VerticalLayout | HorizontalLayout | GroupLayout;
+export declare type UISchemaElement = ControlElement | VerticalLayout | HorizontalLayout | GroupLayout | Categorization | Category | LabelElement;
 
 /**
  * Base interface for all UI Schema elements.
+ *
+ * This is a manually maintained interface representing the common shape
+ * shared by all element types. It is kept as an interface (rather than
+ * derived from Zod) because it is the base of a discriminated union, not
+ * a union member itself.
+ *
+ * @public
  */
-declare interface UISchemaElementBase {
+export declare interface UISchemaElementBase {
+    /** Discriminator for the concrete JSON Forms element type. */
     type: UISchemaElementType;
+    /** Optional rule controlling visibility or enablement. */
     rule?: Rule;
+    /** Renderer-specific options shared by UI schema elements. */
     options?: Record<string, unknown>;
 }
 
 /**
- * JSON Forms UI Schema type definitions.
+ * UI Schema element types.
  *
- * These types define the UI layout structure for JSON Forms.
- * See: https://jsonforms.io/docs/uischema/
+ * @public
  */
+export declare type UISchemaElementType = "Control" | "VerticalLayout" | "HorizontalLayout" | "Group" | "Categorization" | "Category" | "Label";
+
 /**
- * UI Schema element types.
+ * Zod schema for the root UI Schema (layout types only).
+ *
+ * @public
+ */
+export declare const uiSchemaSchema: z.ZodType<UISchema>;
+
+/**
+ * Options for validating canonical FormIR.
+ *
+ * @public
+ */
+export declare interface ValidateIROptions {
+    /** Vendor prefix used when resolving extension-backed keywords. */
+    readonly vendorPrefix?: string;
+    /** Extension registry used to resolve custom constraints and types. */
+    readonly extensionRegistry?: ExtensionRegistry;
+}
+
+/**
+ * A machine-readable validation diagnostic returned by static schema analysis.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnostic {
+    /** Stable machine-readable diagnostic code. */
+    readonly code: string;
+    /** Human-readable explanation of the validation problem. */
+    readonly message: string;
+    /** Severity of the reported validation problem. */
+    readonly severity: ValidationDiagnosticSeverity;
+    /** Primary source location associated with the diagnostic. */
+    readonly primaryLocation: ValidationDiagnosticLocation;
+    /** Related source locations that add context to the diagnostic. */
+    readonly relatedLocations: readonly ValidationDiagnosticLocation[];
+}
+
+/**
+ * Public source-location shape attached to validation diagnostics.
+ *
+ * This mirrors the provenance information surfaced by the shared analysis
+ * layer without exposing `@formspec/core/internals` through the public API.
+ *
+ * @public
+ */
+export declare interface ValidationDiagnosticLocation {
+    /** Authoring surface that produced the diagnostic location. */
+    readonly surface: "tsdoc" | "chain-dsl" | "extension" | "inferred";
+    /** Absolute path to the source file. */
+    readonly file: string;
+    /** 1-based line number in the source file. */
+    readonly line: number;
+    /** 0-based column number in the source file. */
+    readonly column: number;
+    /** Optional span length in characters. */
+    readonly length?: number;
+    /** Optional tag or construct associated with the location. */
+    readonly tagName?: string;
+}
+
+/**
+ * Supported severity levels returned by static build validation.
+ *
+ * @public
  */
-export declare type UISchemaElementType = "Control" | "VerticalLayout" | "HorizontalLayout" | "Group" | "Categorization" | "Category";
+export declare type ValidationDiagnosticSeverity = "error" | "warning";
+
+/**
+ * Result of validating canonical FormIR before schema emission.
+ *
+ * @public
+ */
+export declare interface ValidationResult {
+    /** Diagnostics produced during validation. */
+    readonly diagnostics: readonly ValidationDiagnostic[];
+    /** Whether any error-severity diagnostics were produced. */
+    readonly valid: boolean;
+}
 
 /**
  * A vertical layout element.
+ *
+ * @public
  */
-export declare interface VerticalLayout extends UISchemaElementBase {
-    type: "VerticalLayout";
-    elements: UISchemaElement[];
+export declare interface VerticalLayout {
+    /** Discriminator identifying a vertical layout container. */
+    readonly type: "VerticalLayout";
+    /** Child elements rendered in vertical order. */
+    readonly elements: UISchemaElement[];
+    /** Optional rule controlling visibility or enablement. */
+    readonly rule?: Rule | undefined;
+    /** Renderer-specific layout options. */
+    readonly options?: Record<string, unknown> | undefined;
+    /** Additional renderer-specific extension properties. */
+    readonly [k: string]: unknown;
 }
 
 /**
@@ -322,13 +1457,17 @@ export declare interface VerticalLayout extends UISchemaElementBase {
  * @param form - The FormSpec to build schemas from
  * @param options - Output options (directory, file name, indentation)
  * @returns Object containing paths to the generated files
+ *
+ * @public
  */
 export declare function writeSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options: WriteSchemasOptions): WriteSchemasResult;
 
 /**
  * Options for writing schemas to disk.
+ *
+ * @public
  */
-export declare interface WriteSchemasOptions {
+export declare interface WriteSchemasOptions extends GenerateJsonSchemaOptions {
     /** Output directory for the schema files */
     readonly outDir: string;
     /** Base name for the output files (without extension). Defaults to "schema" */
@@ -339,6 +1478,8 @@ export declare interface WriteSchemasOptions {
 
 /**
  * Result of writing schemas to disk.
+ *
+ * @public
  */
 export declare interface WriteSchemasResult {
     /** Path to the generated JSON Schema file */