@formspec/build 0.1.0-alpha.5 → 0.1.0-alpha.50

package/dist/extensions/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extension registry for `@formspec/build`.
+ *
+ * @packageDocumentation
+ */
+export { createExtensionRegistry } from "./registry.js";
+export type { ExtensionRegistry, ExtensionTypeLookupResult, MutableExtensionRegistry, } from "./registry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EACV,iBAAiB,EACjB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,eAAe,CAAC"}

package/dist/extensions/registry.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Extension registry for resolving custom types, constraints, and annotations
+ * during JSON Schema generation and IR validation.
+ *
+ * The registry is created from a list of {@link ExtensionDefinition} objects
+ * and provides O(1) lookup by fully-qualified ID (extensionId + "/" + name).
+ *
+ * @packageDocumentation
+ */
+import type * as ts from "typescript";
+import type { ExtensionDefinition, CustomTypeRegistration, CustomConstraintRegistration, CustomAnnotationRegistration, ConstraintTagRegistration, BuiltinConstraintBroadeningRegistration } from "@formspec/core";
+/**
+ * The result of a successful extension type lookup.
+ *
+ * Returned by {@link ExtensionRegistry.findTypeByName},
+ * {@link ExtensionRegistry.findTypeByBrand}, and
+ * {@link ExtensionRegistry.findTypeBySymbol}.
+ *
+ * @public
+ */
+export interface ExtensionTypeLookupResult {
+    /** The fully-qualified extension ID (e.g., "x-stripe/monetary"). */
+    readonly extensionId: string;
+    /** The custom type registration matched by this lookup. */
+    readonly registration: CustomTypeRegistration;
+}
+/**
+ * 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 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): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type registration by a brand identifier.
+     *
+     * This is used during class analysis to resolve extension-defined custom types
+     * via structural brand detection (`unique symbol` computed property keys).
+     * Brand identifiers are stored as plain strings, so they must be unique
+     * across all extensions loaded into the registry.
+     *
+     * @param brand - The identifier text of the `unique symbol` brand variable.
+     */
+    findTypeByBrand(brand: string): ExtensionTypeLookupResult | undefined;
+    /**
+     * Look up a custom type by its TypeScript symbol identity.
+     *
+     * Built from `defineCustomType<T>()` type parameter extraction in the config file.
+     * This is the most precise detection path — it uses `ts.Symbol` identity, which is
+     * immune to import aliases and name collisions.
+     *
+     * Returns `undefined` until {@link MutableExtensionRegistry.setSymbolMap} has been
+     * called (i.e., before the TypeScript program is available), or when the symbol is
+     * not registered via a type parameter.
+     *
+     * @param symbol - The canonical TypeScript symbol to look up.
+     */
+    findTypeBySymbol(symbol: ts.Symbol): ExtensionTypeLookupResult | 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;
+}
+/**
+ * Mutable extension registry used internally by the build pipeline.
+ *
+ * Extends {@link ExtensionRegistry} with `setSymbolMap`, which must be called
+ * after the TypeScript program is created. Consumer code should accept only
+ * the read-only {@link ExtensionRegistry} interface.
+ *
+ * @public
+ */
+export interface MutableExtensionRegistry extends ExtensionRegistry {
+    /**
+     * Sets the symbol map built from config AST analysis.
+     *
+     * Called after the TypeScript program is created and the config file is analyzed.
+     * Prior to this call, {@link ExtensionRegistry.findTypeBySymbol} always returns
+     * `undefined`.
+     *
+     * @param map - A map from canonical `ts.Symbol` to the matching registry entry.
+     */
+    setSymbolMap(map: Map<ts.Symbol, ExtensionTypeLookupResult>): void;
+}
+/**
+ * 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[]): MutableExtensionRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/extensions/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/extensions/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,uCAAuC,EACxC,MAAM,gBAAgB,CAAC;AAexB;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAEpD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAAC;IAC7D;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAAC;IACxE;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAAC;IAEtE;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAAC;IAE3E;;;;;OAKG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,4BAA4B,GAAG,SAAS,CAAC;IAC/E;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAC7B;QACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,YAAY,EAAE,yBAAyB,CAAC;KAClD,GACD,SAAS,CAAC;IACd;;OAEG;IACH,+BAA+B,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAEb;QACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,YAAY,EAAE,uCAAuC,CAAC;KAChE,GACD,SAAS,CAAC;IAEd;;;;;OAKG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,4BAA4B,GAAG,SAAS,CAAC;CAChF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAyB,SAAQ,iBAAiB;IACjE;;;;;;;;OAQG;IACH,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,IAAI,CAAC;CACpE;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,mBAAmB,EAAE,GACzC,wBAAwB,CAuK1B"}

package/dist/extensions/resolve-custom-type.d.ts

@@ -0,0 +1,37 @@
+import * as ts from "typescript";
+import type { ExtensionRegistry, ExtensionTypeLookupResult } from "./registry.js";
+/**
+ * Resolves a TypeScript type to an extension-registered custom type, trying
+ * all three registration mechanisms in order of precision:
+ *
+ * 1. **Name-based** (via `sourceNode` AST walk) — matches the user-written
+ *    alias identifier (e.g. `amount: Decimal` → `"Decimal"`). Requires a
+ *    source node to walk; used by the direct-field code path.
+ * 2. **Symbol-based** — matches `ts.Symbol` identity via
+ *    `ExtensionRegistry.findTypeBySymbol`, populated from
+ *    `defineCustomType<T>()` type parameter extraction. Works for any type
+ *    regardless of import aliases or name collisions.
+ * 3. **Brand-based** — matches the `brand` identifier encoded into
+ *    intersection types as computed-property keys (e.g.
+ *    `string & { [__decimalBrand]: true }`). Structural; independent of
+ *    declaration names.
+ *
+ * Name-based resolution also has a symbol-fallback path that uses
+ * `type.aliasSymbol?.getName()` when no `sourceNode` is provided, so
+ * path-resolved types can still match name-registered custom types.
+ *
+ * Nullable unions (`T | null`, `T | undefined`, `T | null | undefined`) are
+ * stripped before every detection attempt, so registrations apply through
+ * nullable wrappers transparently.
+ *
+ * Returns `null` when no registered custom type matches.
+ */
+export declare function resolveCustomTypeFromTsType(type: ts.Type, checker: ts.TypeChecker, registry: ExtensionRegistry | undefined, sourceNode?: ts.Node): ExtensionTypeLookupResult | null;
+/**
+ * Returns the fully-qualified type ID for a resolved custom-type lookup.
+ *
+ * Type IDs have the form `${extensionId}/${typeName}`, matching the format
+ * produced elsewhere in the build pipeline.
+ */
+export declare function customTypeIdFromLookup(result: ExtensionTypeLookupResult): string;
+//# sourceMappingURL=resolve-custom-type.d.ts.map

package/dist/extensions/resolve-custom-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-custom-type.d.ts","sourceRoot":"","sources":["../../src/extensions/resolve-custom-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAIjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAoDlF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,UAAU,CAAC,EAAE,EAAE,CAAC,IAAI,GACnB,yBAAyB,GAAG,IAAI,CA8ClC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAEhF"}

package/dist/extensions/symbol-registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Symbol-based custom type registry.
+ *
+ * Walks the FormSpec config file AST to find `defineCustomType<T>()` calls,
+ * extracts the TypeScript type argument, resolves it to a canonical `ts.Symbol`,
+ * and builds a `Map` for O(1) symbol-identity lookup during field analysis.
+ *
+ * This detection path is the most precise available — it uses TypeScript's own
+ * type identity, making it immune to import aliases and name collisions.
+ *
+ * @packageDocumentation
+ */
+import * as ts from "typescript";
+import type { ExtensionRegistry, ExtensionTypeLookupResult } from "./registry.js";
+/**
+ * Walks the config file's AST to find `defineCustomType<T>()` calls,
+ * extracts type arguments, resolves them to ts.Symbol, and builds a
+ * Map for O(1) symbol-identity lookup during field analysis.
+ *
+ * Returns an empty map if the config file isn't in the program, has
+ * no `defineCustomType` calls, or none have type arguments.
+ *
+ * @param configPath - Absolute path to the FormSpec config file.
+ * @param program - The TypeScript program that includes the config file.
+ * @param checker - Type checker for the program.
+ * @param extensionRegistry - The runtime extension registry already built from
+ *   the config's export; used to look up the matching registration by typeName.
+ * @returns A map from canonical ts.Symbol to the matching registry entry.
+ *
+ * @public
+ */
+export declare function buildSymbolMapFromConfig(configPath: string, program: ts.Program, checker: ts.TypeChecker, extensionRegistry: ExtensionRegistry): Map<ts.Symbol, ExtensionTypeLookupResult>;
+//# sourceMappingURL=symbol-registry.d.ts.map

package/dist/extensions/symbol-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-registry.d.ts","sourceRoot":"","sources":["../../src/extensions/symbol-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAOlF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,iBAAiB,EAAE,iBAAiB,GACnC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,yBAAyB,CAAC,CA+D3C"}

package/dist/extensions/ts-type-utils.d.ts

@@ -0,0 +1,40 @@
+import * as ts from "typescript";
+/**
+ * Collects all brand identifier texts from an intersection type's computed
+ * property names.
+ *
+ * Walks `type.getProperties()` looking for computed property names backed
+ * by plain identifiers — the standard `unique symbol` brand pattern. Returns
+ * all matching identifiers so that types with multiple brands (e.g.,
+ * `number & { [__integerBrand]: true } & { [__otherBrand]: true }`) are
+ * fully inspected regardless of property order.
+ */
+export declare function collectBrandIdentifiers(type: ts.Type): readonly string[];
+/**
+ * Resolves a TypeScript type to its canonical `ts.Symbol`, following alias chains.
+ *
+ * `aliasSymbol` tracks type aliases (e.g. `type Foo = Bar`); `getSymbol()` tracks
+ * the structural symbol. We prefer `aliasSymbol` when present so that aliased
+ * types resolve to the declaration site rather than the structural shape.
+ *
+ * Returns `undefined` for bare primitives and anonymous types, which have no
+ * symbol.
+ */
+export declare function resolveCanonicalSymbol(type: ts.Type, checker: ts.TypeChecker): ts.Symbol | undefined;
+/**
+ * Extracts the `ts.TypeNode` backing a property / parameter / type-alias
+ * declaration. Returns the node itself when `sourceNode` is already a type
+ * node, or `undefined` otherwise.
+ */
+export declare function extractTypeNodeFromSource(sourceNode: ts.Node): ts.TypeNode | undefined;
+/**
+ * Resolves a `ts.TypeReferenceNode` to its declaring `ts.TypeAliasDeclaration`,
+ * if the reference names a type alias — following import aliases so that
+ * `import { Foo } from "./types"; field: Foo` resolves through to the
+ * original `type Foo = ...` declaration.
+ *
+ * Returns `undefined` for references to non-alias declarations (interfaces,
+ * classes, modules, etc.).
+ */
+export declare function getTypeAliasDeclarationFromTypeReference(typeNode: ts.TypeReferenceNode, checker: ts.TypeChecker): ts.TypeAliasDeclaration | undefined;
+//# sourceMappingURL=ts-type-utils.d.ts.map

package/dist/extensions/ts-type-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ts-type-utils.d.ts","sourceRoot":"","sources":["../../src/extensions/ts-type-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,SAAS,MAAM,EAAE,CAcxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,EAAE,CAAC,MAAM,GAAG,SAAS,CAIvB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,QAAQ,GAAG,SAAS,CAatF;AAUD;;;;;;;;GAQG;AACH,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,EAAE,CAAC,iBAAiB,EAC9B,OAAO,EAAE,EAAE,CAAC,WAAW,GACtB,EAAE,CAAC,oBAAoB,GAAG,SAAS,CAGrC"}

package/dist/generators/class-schema.d.ts

@@ -0,0 +1,392 @@
+/**
+ * Class schema generator.
+ *
+ * Generates JSON Schema 2020-12 and JSON Forms UI Schema from statically
+ * analyzed class/interface/type alias declarations, routing through the
+ * canonical FormIR pipeline.
+ */
+import * as ts from "typescript";
+import type { UISchema } from "../ui-schema/types.js";
+import type { MetadataPolicyInput } from "@formspec/core";
+import type { FormSpecConfig } from "@formspec/config";
+import { type DiscriminatorResolutionOptions, type IRClassAnalysis } from "../analyzer/class-analyzer.js";
+import { type TSDocSource } from "../canonicalize/index.js";
+import { type GenerateJsonSchemaFromIROptions, type JsonSchema2020 } from "../json-schema/ir-generator.js";
+import { type ExtensionRegistry } from "../extensions/index.js";
+import { type ValidationDiagnostic } from "../validate/index.js";
+export type { DiscriminatorResolutionOptions } from "../analyzer/class-analyzer.js";
+/**
+ * Generated schemas for a class.
+ *
+ * @beta
+ */
+export interface ClassSchemas {
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+/**
+ * Non-throwing schema generation result with structured diagnostics.
+ *
+ * @public
+ */
+export 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;
+}
+/**
+ * A batch target for non-throwing schema generation.
+ *
+ * @public
+ */
+export 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;
+}
+/**
+ * Batch options for non-throwing schema generation.
+ *
+ * @public
+ */
+export interface GenerateSchemasBatchOptions extends StaticSchemaGenerationOptions {
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+/**
+ * Batch options for non-throwing schema generation using an existing program.
+ *
+ * @public
+ */
+export interface GenerateSchemasBatchFromProgramOptions extends StaticSchemaGenerationOptions {
+    /** Existing TypeScript program supplied by the caller. */
+    readonly program: ts.Program;
+    /** Targets to analyze and generate. */
+    readonly targets: readonly SchemaGenerationTarget[];
+}
+/**
+ * Result for a single target in a batch generation request.
+ *
+ * @public
+ */
+export 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;
+}
+/**
+ * Generates JSON Schema 2020-12 and UI Schema from an IR class analysis.
+ *
+ * Routes through the canonical IR pipeline:
+ *   IRClassAnalysis → canonicalizeTSDoc → FormIR → JSON Schema / UI Schema
+ *
+ * @param analysis - The IR analysis result (from analyzeClassToIR, analyzeInterfaceToIR, or analyzeTypeAliasToIR)
+ * @param source - Optional source file metadata for provenance
+ * @returns Generated JSON Schema and UI Schema
+ */
+export declare function generateClassSchemas(analysis: IRClassAnalysis, source?: TSDocSource, options?: GenerateJsonSchemaFromIROptions & {
+    metadata?: MetadataPolicyInput | undefined;
+}): ClassSchemas;
+/**
+ * Generates JSON Schema 2020-12 and UI Schema from an IR class analysis
+ * without throwing on validation diagnostics.
+ *
+ * @public
+ */
+export declare function generateClassSchemasDetailed(analysis: IRClassAnalysis, source?: TSDocSource, options?: GenerateJsonSchemaFromIROptions & {
+    metadata?: MetadataPolicyInput | undefined;
+}): DetailedClassSchemasResult;
+/**
+ * Shared options for schema generation flows that support custom extensions.
+ *
+ * @public
+ */
+export interface StaticSchemaGenerationOptions {
+    /**
+     * FormSpec project configuration. When provided, resolves `extensionRegistry`,
+     * `vendorPrefix`, `enumSerialization`, and `metadata` from the config object.
+     * Direct options take precedence over config values.
+     */
+    readonly config?: FormSpecConfig | undefined;
+    /**
+     * Registry used to resolve custom types, constraints, and annotations.
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
+     */
+    readonly extensionRegistry?: ExtensionRegistry | undefined;
+    /**
+     * Vendor prefix for emitted extension keywords.
+     * @defaultValue "x-formspec"
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
+     */
+    readonly vendorPrefix?: string | undefined;
+    /**
+     * JSON Schema representation to use for static enums.
+     * @defaultValue "enum"
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
+     */
+    readonly enumSerialization?: "enum" | "oneOf";
+    /**
+     * Metadata resolution policy for static schema generation.
+     * @deprecated Provide a `FormSpecConfig` via the `config` option instead.
+     */
+    readonly metadata?: MetadataPolicyInput | undefined;
+    /** Discriminator-specific schema generation behavior. */
+    readonly discriminator?: DiscriminatorResolutionOptions | undefined;
+    /**
+     * Absolute path to the FormSpec config file (e.g., `formspec.config.ts`).
+     *
+     * When provided alongside a `config` that includes extensions, the build
+     * pipeline includes the config file in the TypeScript program and extracts
+     * `defineCustomType<T>()` type parameters. This enables symbol-based custom
+     * type detection — the most precise resolution path, immune to import aliases
+     * and name collisions.
+     *
+     * Obtain this from `loadFormSpecConfig()`:
+     * ```typescript
+     * const { config, configPath } = await loadFormSpecConfig();
+     * await generateSchemas({ filePath, typeName, config, configPath, errorReporting: "throw" });
+     * ```
+     */
+    readonly configPath?: string | undefined;
+}
+/**
+ * Options for generating schemas from a decorated class.
+ *
+ * @public
+ */
+export 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 interface GenerateFromClassResult {
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+/**
+ * Options for generating schemas from a named type inside an existing TypeScript program.
+ *
+ * @public
+ */
+export 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 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;
+/**
+ * Options for generating schemas from a named type (class, interface, or type alias).
+ *
+ * @public
+ */
+export 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 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 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 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 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 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;
+/**
+ * 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[];
+/**
+ * Resolves the effective extension registry, vendor prefix, enum serialization,
+ * and metadata from a `StaticSchemaGenerationOptions` object.
+ *
+ * Prefers explicit deprecated fields when present, falling back to the
+ * `config` object. This is the migration bridge — once all callers use
+ * `config`, the deprecated field reads can be removed.
+ *
+ * @internal
+ */
+export declare function resolveStaticOptions(options: StaticSchemaGenerationOptions): {
+    extensionRegistry: ExtensionRegistry | undefined;
+    vendorPrefix: string | undefined;
+    enumSerialization: "enum" | "oneOf" | undefined;
+    metadata: MetadataPolicyInput | undefined;
+};
+//# sourceMappingURL=class-schema.d.ts.map