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

package/dist/build.d.ts

@@ -0,0 +1,890 @@
+/**
+ * `@formspec/build` - Build tools for FormSpec
+ *
+ * This package provides generators to compile FormSpec forms into:
+ * - JSON Schema (for validation)
+ * - JSON Forms UI Schema (for rendering)
+ *
+ * @example
+ * ```typescript
+ * import { buildFormSchemas } from "@formspec/build";
+ * import { formspec, field, group } from "@formspec/dsl";
+ *
+ * const form = formspec(
+ *   group("Customer",
+ *     field.text("name", { label: "Name", required: true }),
+ *     field.text("email", { label: "Email" }),
+ *   ),
+ * );
+ *
+ * const { jsonSchema, uiSchema } = buildFormSchemas(form);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { FormElement } from '@formspec/core';
+import type { FormSpec } from '@formspec/core';
+import { z } from 'zod';
+
+/**
+ * Builds both JSON Schema and UI Schema from a FormSpec.
+ *
+ * This is a convenience function that combines `generateJsonSchema`
+ * and `generateUiSchema`.
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   field.text("name", { required: true }),
+ *   field.number("age", { min: 0 }),
+ * );
+ *
+ * const { jsonSchema, uiSchema } = buildFormSchemas(form);
+ *
+ * // Use with JSON Forms renderer
+ * <JsonForms
+ *   schema={jsonSchema}
+ *   uischema={uiSchema}
+ *   data={formData}
+ *   renderers={materialRenderers}
+ * />
+ * ```
+ *
+ * @param form - The FormSpec to build schemas from
+ * @returns Object containing both jsonSchema and uiSchema
+ */
+export declare function buildFormSchemas<E extends readonly FormElement[]>(form: FormSpec<E>): BuildResult;
+
+/**
+ * Result of building form schemas.
+ */
+export declare interface BuildResult {
+    /** JSON Schema for validation */
+    readonly jsonSchema: JSONSchema7;
+    /** JSON Forms UI Schema for rendering */
+    readonly uiSchema: UISchema;
+}
+
+/**
+ * A Categorization element (tab-based layout).
+ */
+export declare interface Categorization {
+    type: "Categorization";
+    elements: Category[];
+    label?: string | undefined;
+    rule?: Rule | undefined;
+    options?: Record<string, unknown> | undefined;
+    [k: string]: unknown;
+}
+
+export declare const categorizationSchema: z.ZodType<Categorization>;
+
+/**
+ * A Category element, used inside a Categorization layout.
+ */
+export declare interface Category {
+    type: "Category";
+    label: string;
+    elements: UISchemaElement[];
+    rule?: Rule | undefined;
+    options?: Record<string, unknown> | undefined;
+    [k: string]: unknown;
+}
+
+export declare const categorySchema: z.ZodType<Category>;
+
+/**
+ * Generated schemas for a class.
+ */
+export declare interface ClassSchemas {
+    /** JSON Schema for validation */
+    jsonSchema: ExtendedJSONSchema7;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+
+/**
+ * Options for code generation.
+ */
+export declare interface CodegenOptions {
+    /** Source files to analyze (glob patterns supported) */
+    files: string[];
+    /** Output file path */
+    output: string;
+    /** Base directory for relative imports */
+    baseDir?: string;
+}
+
+/**
+ * A Control element that binds to a JSON Schema property.
+ */
+export declare type ControlElement = z.infer<typeof controlSchema>;
+
+/**
+ * Zod schema for a Control element.
+ */
+export declare const controlSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Control">;
+    scope: z.ZodString;
+    label: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+    rule: z.ZodOptional<z.ZodObject<{
+        effect: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+        condition: z.ZodObject<{
+            scope: z.ZodString;
+            schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+        }, "strict", z.ZodTypeAny, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    type: z.ZodLiteral<"Control">;
+    scope: z.ZodString;
+    label: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+    rule: z.ZodOptional<z.ZodObject<{
+        effect: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+        condition: z.ZodObject<{
+            scope: z.ZodString;
+            schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+        }, "strict", z.ZodTypeAny, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    type: z.ZodLiteral<"Control">;
+    scope: z.ZodString;
+    label: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodLiteral<false>]>>;
+    rule: z.ZodOptional<z.ZodObject<{
+        effect: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+        condition: z.ZodObject<{
+            scope: z.ZodString;
+            schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+        }, "strict", z.ZodTypeAny, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">>;
+
+/**
+ * Information about a decorated class found during codegen analysis.
+ *
+ * Used to track which classes need type metadata patches and where
+ * they are located in the source tree.
+ */
+export declare interface DecoratedClassInfo {
+    /** Class name as it appears in the source file */
+    name: string;
+    /** Import path to the source file (relative to output, without extension) */
+    sourcePath: string;
+    /** Type metadata for all decorated properties in the class */
+    typeMetadata: Record<string, TypeMetadata>;
+    /** Whether the class is exported from its source file */
+    isExported: boolean;
+}
+
+/** JSON Schema with FormSpec extension properties for arbitrary x-formspec-* keys. */
+export declare type ExtendedJSONSchema7 = JSONSchema7 & FormSpecSchemaExtensions;
+
+/**
+ * Finds all decorated classes in the given source files.
+ */
+export declare function findDecoratedClasses(files: string[], baseDir: string): DecoratedClassInfo[];
+
+/**
+ * FormSpec field definition (simplified for output).
+ */
+export declare interface FormSpecField {
+    _field: string;
+    id: string;
+    label?: string;
+    placeholder?: string;
+    description?: string;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    pattern?: string;
+    options?: (string | {
+        id: string;
+        label: string;
+    })[];
+    showWhen?: object;
+    group?: string;
+    fields?: FormSpecField[];
+}
+
+/** Extension properties for custom FormSpec decorators. */
+export declare type FormSpecSchemaExtensions = Record<`x-formspec-${string}`, unknown>;
+
+/**
+ * Generates the codegen output file content.
+ */
+export declare function generateCodegenOutput(classes: DecoratedClassInfo[], outputPath: string, baseDir: string): string;
+
+/**
+ * Options for generating schemas from a decorated class.
+ */
+export declare interface GenerateFromClassOptions {
+    /** Path to the TypeScript source file */
+    filePath: string;
+    /** Class name to analyze */
+    className: string;
+}
+
+/**
+ * Result of generating schemas from a decorated class.
+ */
+export declare interface GenerateFromClassResult {
+    /** JSON Schema for validation */
+    jsonSchema: ExtendedJSONSchema7;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+
+/**
+ * Generates a JSON Schema from a FormSpec.
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   field.text("name", { label: "Name", required: true }),
+ *   field.number("age", { min: 0 }),
+ * );
+ *
+ * const schema = generateJsonSchema(form);
+ * // {
+ * //   $schema: "https://json-schema.org/draft-07/schema#",
+ * //   type: "object",
+ * //   properties: {
+ * //     name: { type: "string", title: "Name" },
+ * //     age: { type: "number", minimum: 0 }
+ * //   },
+ * //   required: ["name"]
+ * // }
+ * ```
+ *
+ * @param form - The FormSpec to convert
+ * @returns A JSON Schema object
+ */
+export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>): JSONSchema7;
+
+/**
+ * Generates JSON Schema and FormSpec/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 analysis pipeline:
+ *
+ * - **Classes**: extracts decorators and JSDoc constraints
+ * - **Interfaces**: extracts TSDoc tags (`@Field_displayName`, `@Minimum`, etc.)
+ * - **Type aliases**: object literal bodies analyzed like interfaces
+ *
+ * @example
+ * ```typescript
+ * // Works with both classes and interfaces — caller doesn't need to know
+ * const result = generateSchemas({
+ *   filePath: "./src/config.ts",
+ *   typeName: "DiscountConfig",
+ * });
+ * ```
+ *
+ * @param options - File path and type name
+ * @returns Generated JSON Schema and FormSpec/UI Schema
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions): GenerateFromClassResult;
+
+/**
+ * Generates JSON Schema and FormSpec/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,
+ * 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 FormSpec/UI Schema
+ */
+export declare function generateSchemasFromClass(options: GenerateFromClassOptions): GenerateFromClassResult;
+
+/**
+ * Options for generating schemas from a named type (class, interface, or type alias).
+ */
+export declare interface GenerateSchemasOptions {
+    /** Path to the TypeScript source file */
+    filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze */
+    typeName: string;
+}
+
+/**
+ * Generates a JSON Forms UI Schema from a FormSpec.
+ *
+ * @example
+ * ```typescript
+ * const form = formspec(
+ *   group("Customer",
+ *     field.text("name", { label: "Name" }),
+ *   ),
+ *   when("status", "draft",
+ *     field.text("notes", { label: "Notes" }),
+ *   ),
+ * );
+ *
+ * const uiSchema = generateUiSchema(form);
+ * // {
+ * //   type: "VerticalLayout",
+ * //   elements: [
+ * //     {
+ * //       type: "Group",
+ * //       label: "Customer",
+ * //       elements: [
+ * //         { type: "Control", scope: "#/properties/name", label: "Name" }
+ * //       ]
+ * //     },
+ * //     {
+ * //       type: "Control",
+ * //       scope: "#/properties/notes",
+ * //       label: "Notes",
+ * //       rule: {
+ * //         effect: "SHOW",
+ * //         condition: { scope: "#/properties/status", schema: { const: "draft" } }
+ * //       }
+ * //     }
+ * //   ]
+ * // }
+ * ```
+ *
+ * @param form - The FormSpec to convert
+ * @returns A JSON Forms UI Schema
+ */
+export declare function generateUiSchema<E extends readonly FormElement[]>(form: FormSpec<E>): UISchema;
+
+/**
+ * Converts FormSpecField[] (from decorator/interface/type analysis) to a JSON Forms UISchema.
+ *
+ * Mapping:
+ * - Each field → `{ type: "Control", scope: "#/properties/{id}", label? }`
+ * - `showWhen: { field, value }` → rule with SHOW effect
+ * - `group` property → Groups fields by group name, preserving insertion order
+ * - `fields` (nested object) → single Control pointing to the object property
+ * - Root wrapper → `{ type: "VerticalLayout", elements }`
+ *
+ * @param fields - The FormSpecField array to convert
+ * @returns A JSON Forms UISchema
+ */
+export declare function generateUiSchemaFromFields(fields: FormSpecField[]): UISchema;
+
+/**
+ * Reads a FormSpec extension property from a JSON Schema node.
+ *
+ * Use this to safely read `x-formspec-*` properties from any schema,
+ * including nested schemas typed as `JSONSchema7`.
+ *
+ * @param schema - Any JSON Schema node
+ * @param key - Extension key (must start with `x-formspec-`)
+ * @returns The extension value, or `undefined` if not present
+ */
+export declare function getSchemaExtension(schema: JSONSchema7, key: `x-formspec-${string}`): unknown;
+
+/**
+ * A group element with a label.
+ */
+export declare interface GroupLayout {
+    type: "Group";
+    label: string;
+    elements: UISchemaElement[];
+    rule?: Rule | undefined;
+    options?: Record<string, unknown> | undefined;
+    [k: string]: unknown;
+}
+
+export declare const groupLayoutSchema: z.ZodType<GroupLayout>;
+
+/**
+ * A horizontal layout element.
+ */
+export declare interface HorizontalLayout {
+    type: "HorizontalLayout";
+    elements: UISchemaElement[];
+    rule?: Rule | undefined;
+    options?: Record<string, unknown> | undefined;
+    [k: string]: unknown;
+}
+
+export declare const horizontalLayoutSchema: z.ZodType<HorizontalLayout>;
+
+/**
+ * A JSON Schema definition (draft-07 subset).
+ */
+export declare interface JSONSchema7 {
+    $schema?: string;
+    $id?: string;
+    $ref?: string;
+    title?: string;
+    description?: string;
+    deprecated?: boolean;
+    type?: JSONSchemaType | JSONSchemaType[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    enum?: readonly (string | number | boolean | null)[];
+    const?: string | number | boolean | null;
+    properties?: Record<string, JSONSchema7>;
+    required?: string[];
+    additionalProperties?: boolean | JSONSchema7;
+    items?: JSONSchema7 | JSONSchema7[];
+    minItems?: number;
+    maxItems?: number;
+    allOf?: JSONSchema7[];
+    anyOf?: JSONSchema7[];
+    oneOf?: JSONSchema7[];
+    not?: JSONSchema7;
+    if?: JSONSchema7;
+    then?: JSONSchema7;
+    else?: JSONSchema7;
+    format?: string;
+    default?: unknown;
+    /**
+     * Data source key for dynamic enum fields.
+     * Indicates that options should be fetched from a registered resolver.
+     */
+    "x-formspec-source"?: string;
+    /**
+     * Field names whose values are needed to fetch dynamic enum options.
+     * Used for dependent/cascading dropdowns.
+     */
+    "x-formspec-params"?: readonly string[];
+    /**
+     * Schema source identifier for dynamic schema fields.
+     * Indicates that the schema should be loaded dynamically at runtime.
+     */
+    "x-formspec-schemaSource"?: string;
+}
+
+export declare const jsonSchema7Schema: z.ZodType<JSONSchema7>;
+
+/**
+ * JSON Schema Draft-07 type definitions.
+ *
+ * These types are a subset of JSON Schema sufficient for form generation.
+ */
+/**
+ * JSON Schema primitive types.
+ */
+export declare type JSONSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+
+/**
+ * Zod schema for JSON Schema primitive type strings.
+ */
+export declare const jsonSchemaTypeSchema: z.ZodEnum<["string", "number", "integer", "boolean", "object", "array", "null"]>;
+
+/**
+ * A Label element for displaying static text.
+ */
+export declare type LabelElement = z.infer<typeof labelElementSchema>;
+
+/**
+ * Zod schema for a Label element.
+ */
+export declare const labelElementSchema: z.ZodObject<{
+    type: z.ZodLiteral<"Label">;
+    text: z.ZodString;
+    rule: z.ZodOptional<z.ZodObject<{
+        effect: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+        condition: z.ZodObject<{
+            scope: z.ZodString;
+            schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+        }, "strict", z.ZodTypeAny, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    type: z.ZodLiteral<"Label">;
+    text: z.ZodString;
+    rule: z.ZodOptional<z.ZodObject<{
+        effect: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+        condition: z.ZodObject<{
+            scope: z.ZodString;
+            schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+        }, "strict", z.ZodTypeAny, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    type: z.ZodLiteral<"Label">;
+    text: z.ZodString;
+    rule: z.ZodOptional<z.ZodObject<{
+        effect: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+        condition: z.ZodObject<{
+            scope: z.ZodString;
+            schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+        }, "strict", z.ZodTypeAny, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }, {
+            schema: RuleConditionSchema;
+            scope: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }, {
+        effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+        condition: {
+            schema: RuleConditionSchema;
+            scope: string;
+        };
+    }>>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.ZodTypeAny, "passthrough">>;
+
+/**
+ * Rule for conditional element visibility/enablement.
+ */
+export declare type Rule = z.infer<typeof ruleSchema>;
+
+/**
+ * JSON Schema subset used in rule conditions.
+ */
+export declare interface RuleConditionSchema {
+    const?: unknown;
+    enum?: readonly unknown[];
+    type?: string;
+    not?: RuleConditionSchema;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    minLength?: number;
+    properties?: Record<string, RuleConditionSchema>;
+    required?: string[];
+    allOf?: RuleConditionSchema[];
+}
+
+export declare const ruleConditionSchema: z.ZodType<RuleConditionSchema>;
+
+/**
+ * Rule effect types for conditional visibility.
+ */
+export declare type RuleEffect = z.infer<typeof ruleEffectSchema>;
+
+/**
+ * Zod schema for rule effect values.
+ */
+export declare const ruleEffectSchema: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+
+/**
+ * Zod schema for a UI Schema rule.
+ */
+export declare const ruleSchema: z.ZodObject<{
+    effect: z.ZodEnum<["SHOW", "HIDE", "ENABLE", "DISABLE"]>;
+    condition: z.ZodObject<{
+        scope: z.ZodString;
+        schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+    }, "strict", z.ZodTypeAny, {
+        schema: RuleConditionSchema;
+        scope: string;
+    }, {
+        schema: RuleConditionSchema;
+        scope: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+    condition: {
+        schema: RuleConditionSchema;
+        scope: string;
+    };
+}, {
+    effect: "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
+    condition: {
+        schema: RuleConditionSchema;
+        scope: string;
+    };
+}>;
+
+/**
+ * Runs the code generation.
+ */
+export declare function runCodegen(options: CodegenOptions): void;
+
+/**
+ * Condition for a rule.
+ */
+export declare type SchemaBasedCondition = z.infer<typeof schemaBasedConditionSchema>;
+
+/**
+ * Zod schema for a schema-based rule condition.
+ */
+export declare const schemaBasedConditionSchema: z.ZodObject<{
+    scope: z.ZodString;
+    schema: z.ZodType<RuleConditionSchema, z.ZodTypeDef, RuleConditionSchema>;
+}, "strict", z.ZodTypeAny, {
+    schema: RuleConditionSchema;
+    scope: string;
+}, {
+    schema: RuleConditionSchema;
+    scope: string;
+}>;
+
+/**
+ * Sets a FormSpec extension property on a JSON Schema node.
+ *
+ * Use this to safely add `x-formspec-*` properties to any schema,
+ * including nested schemas typed as `JSONSchema7` (which don't carry
+ * the extension index signature).
+ *
+ * @param schema - Any JSON Schema node
+ * @param key - Extension key (must start with `x-formspec-`)
+ * @param value - Extension value
+ */
+export declare function setSchemaExtension(schema: JSONSchema7, key: `x-formspec-${string}`, value: unknown): void;
+
+/**
+ * Code generation for FormSpec type metadata.
+ *
+ * Generates a TypeScript file that patches decorated classes with
+ * their extracted type metadata, enabling runtime schema generation
+ * as an alternative to a TypeScript transformer.
+ *
+ * Usage:
+ *   formspec codegen ./src/forms.ts -o ./src/__formspec_types__.ts
+ *
+ * Then in your code:
+ *   import './__formspec_types__';  // Patches all decorated classes
+ *   import { UserFormSchema, getUserFormFormSpec } from './__formspec_types__';
+ *   const spec = getUserFormFormSpec();
+ */
+/**
+ * Type metadata format used by `@formspec/decorators`.
+ *
+ * Represents the runtime type information for a field that TypeScript
+ * normally erases at compile time.
+ */
+export declare interface TypeMetadata {
+    /** Base type: "string", "number", "boolean", "enum", "array", "object", "unknown" */
+    type: string;
+    /** For enum types, the possible literal values */
+    values?: unknown[];
+    /** For array types, metadata about the array element type */
+    itemType?: TypeMetadata;
+    /** For object types, metadata about each property */
+    properties?: Record<string, TypeMetadata>;
+    /** Whether the field accepts null */
+    nullable?: boolean;
+    /** Whether the field is optional (T | undefined or ?: modifier) */
+    optional?: boolean;
+}
+
+/**
+ * Root UI Schema (always a layout — not a Control, Category, or Label).
+ */
+export declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout | Categorization;
+
+/**
+ * Union of all UI Schema element types.
+ */
+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.
+ */
+export declare interface UISchemaElementBase {
+    type: UISchemaElementType;
+    rule?: Rule;
+    options?: Record<string, unknown>;
+}
+
+export declare const uiSchemaElementSchema: z.ZodType<UISchemaElement>;
+
+/**
+ * UI Schema element types.
+ */
+export declare type UISchemaElementType = z.infer<typeof uiSchemaElementTypeSchema>;
+
+/**
+ * Zod schema for UI Schema element type strings.
+ */
+export declare const uiSchemaElementTypeSchema: z.ZodEnum<["Control", "VerticalLayout", "HorizontalLayout", "Group", "Categorization", "Category", "Label"]>;
+
+/**
+ * Zod schema for the root UI Schema (layout types only).
+ */
+export declare const uiSchemaSchema: z.ZodType<UISchema>;
+
+/**
+ * A vertical layout element.
+ */
+export declare interface VerticalLayout {
+    type: "VerticalLayout";
+    elements: UISchemaElement[];
+    rule?: Rule | undefined;
+    options?: Record<string, unknown> | undefined;
+    [k: string]: unknown;
+}
+
+export declare const verticalLayoutSchema: z.ZodType<VerticalLayout>;
+
+/**
+ * Builds and writes both JSON Schema and UI Schema files to disk.
+ *
+ * This is a convenience function for build-time schema generation.
+ * It creates the output directory if it doesn't exist.
+ *
+ * @example
+ * ```typescript
+ * import { formspec, field } from "formspec";
+ * import { writeSchemas } from "@formspec/build";
+ *
+ * const ProductForm = formspec(
+ *   field.text("name", { required: true }),
+ *   field.enum("status", ["draft", "active"]),
+ * );
+ *
+ * // Write schemas to ./generated/product-schema.json and ./generated/product-uischema.json
+ * const { jsonSchemaPath, uiSchemaPath } = writeSchemas(ProductForm, {
+ *   outDir: "./generated",
+ *   name: "product",
+ * });
+ *
+ * console.log(`Generated: ${jsonSchemaPath}, ${uiSchemaPath}`);
+ * ```
+ *
+ * @param form - The FormSpec to build schemas from
+ * @param options - Output options (directory, file name, indentation)
+ * @returns Object containing paths to the generated files
+ */
+export declare function writeSchemas<E extends readonly FormElement[]>(form: FormSpec<E>, options: WriteSchemasOptions): WriteSchemasResult;
+
+/**
+ * Options for writing schemas to disk.
+ */
+export declare interface WriteSchemasOptions {
+    /** Output directory for the schema files */
+    readonly outDir: string;
+    /** Base name for the output files (without extension). Defaults to "schema" */
+    readonly name?: string;
+    /** Number of spaces for JSON indentation. Defaults to 2 */
+    readonly indent?: number;
+}
+
+/**
+ * Result of writing schemas to disk.
+ */
+export declare interface WriteSchemasResult {
+    /** Path to the generated JSON Schema file */
+    readonly jsonSchemaPath: string;
+    /** Path to the generated UI Schema file */
+    readonly uiSchemaPath: string;
+}
+
+export { }