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

package/dist/extensions/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extension registry for `@formspec/build`.
+ *
+ * @packageDocumentation
+ */
+export { createExtensionRegistry } from "./registry.js";
+export type { ExtensionRegistry } 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,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/extensions/registry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 { ExtensionDefinition, CustomTypeRegistration, CustomConstraintRegistration, CustomAnnotationRegistration, ConstraintTagRegistration, BuiltinConstraintBroadeningRegistration } from "@formspec/core";
+/**
+ * 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): {
+        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;
+}
+/**
+ * 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;
+//# 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,EACV,mBAAmB,EACnB,sBAAsB,EACtB,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EACzB,uCAAuC,EACxC,MAAM,gBAAgB,CAAC;AAexB;;;;;;;;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,CACZ,QAAQ,EAAE,MAAM,GACf;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,sBAAsB,CAAA;KAAE,GAAG,SAAS,CAAC;IAE/F;;;;;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;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,mBAAmB,EAAE,GACzC,iBAAiB,CAkJnB"}

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

@@ -0,0 +1,347 @@
+/**
+ * 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 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 {
+    /**
+     * 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;
+    /**
+     * JSON Schema representation to use for static enums.
+     * @defaultValue "enum"
+     */
+    readonly enumSerialization?: "enum" | "oneOf";
+    /** Metadata resolution policy for static schema generation. */
+    readonly metadata?: MetadataPolicyInput | undefined;
+    /** Discriminator-specific schema generation behavior. */
+    readonly discriminator?: DiscriminatorResolutionOptions | 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[];
+//# sourceMappingURL=class-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"class-schema.d.ts","sourceRoot":"","sources":["../../src/generators/class-schema.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,152 @@
+import * as ts from "typescript";
+import type { ResolvedMetadata } from "@formspec/core";
+import type { UISchema } from "../ui-schema/types.js";
+import type { StaticBuildContext } from "../static-build.js";
+import { type StaticSchemaGenerationOptions } from "./class-schema.js";
+import { type JsonSchema2020 } from "../json-schema/ir-generator.js";
+/**
+ * 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 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;
+}
+/**
+ * Supported declaration kinds for declaration-driven schema generation.
+ *
+ * @public
+ */
+export type SchemaSourceDeclaration = ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+/**
+ * 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 type MetadataSourceDeclaration = SchemaSourceDeclaration | ts.MethodDeclaration | ts.FunctionDeclaration | ts.PropertyDeclaration | ts.PropertySignature;
+/**
+ * Options for generating schemas from a resolved declaration.
+ *
+ * @public
+ */
+export 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;
+}
+/**
+ * Options for generating schemas from a resolved TypeScript type.
+ *
+ * @public
+ */
+export 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 method or function parameter type.
+ *
+ * @public
+ */
+export 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;
+}
+/**
+ * Options for generating schemas from a method or function return type.
+ *
+ * @public
+ */
+export 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;
+}
+/**
+ * Options for resolving metadata from a declaration against the active
+ * metadata policy.
+ *
+ * @public
+ */
+export 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;
+}
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * Generates schemas for a method or function parameter type.
+ *
+ * @public
+ */
+export declare function generateSchemasFromParameter(options: GenerateSchemasFromParameterOptions): DiscoveredTypeSchemas;
+/**
+ * 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;
+/**
+ * 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;
+//# sourceMappingURL=discovered-schema.d.ts.map

package/dist/generators/discovered-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovered-schema.d.ts","sourceRoot":"","sources":["../../src/generators/discovered-schema.ts"],"names":[],"mappings":"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"}