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

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
@@ -60,8 +60,8 @@ export declare function buildFormSchemas<E extends readonly FormElement[]>(form:
  * Result of building form schemas.
  */
 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;
 }
@@ -98,24 +98,12 @@ export declare const categorySchema: z.ZodType<Category>;
  * Generated schemas for a class.
  */
 export declare interface ClassSchemas {
-    /** JSON Schema for validation */
-    jsonSchema: ExtendedJSONSchema7;
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
     /** 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.
  */
@@ -216,66 +204,12 @@ export declare const controlSchema: z.ZodObject<{
     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.
  */
@@ -290,14 +224,17 @@ export declare interface GenerateFromClassOptions {
  * Result of generating schemas from a decorated class.
  */
 export declare interface GenerateFromClassResult {
-    /** JSON Schema for validation */
-    jsonSchema: ExtendedJSONSchema7;
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
     /** JSON Forms UI Schema for rendering */
     uiSchema: UISchema;
 }
 
 /**
- * Generates a JSON Schema from a FormSpec.
+ * 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
@@ -308,7 +245,7 @@ export declare interface GenerateFromClassResult {
  *
  * 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" },
@@ -319,25 +256,20 @@ export declare interface GenerateFromClassResult {
  * ```
  *
  * @param form - The FormSpec to convert
- * @returns A JSON Schema object
+ * @returns A JSON Schema 2020-12 object
  */
-export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>): JSONSchema7;
+export declare function generateJsonSchema<E extends readonly FormElement[]>(form: FormSpec<E>): JsonSchema2020;
 
 /**
- * Generates JSON Schema and FormSpec/UI Schema from a named TypeScript
+ * 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 analysis pipeline:
- *
- * - **Classes**: extracts decorators and JSDoc constraints
- * - **Interfaces**: extracts TSDoc tags (`@Field_displayName`, `@Minimum`, etc.)
- * - **Type aliases**: object literal bodies analyzed like interfaces
+ * appropriate IR analysis pipeline.
  *
  * @example
  * ```typescript
- * // Works with both classes and interfaces — caller doesn't need to know
  * const result = generateSchemas({
  *   filePath: "./src/config.ts",
  *   typeName: "DiscountConfig",
@@ -345,15 +277,15 @@ export declare function generateJsonSchema<E extends readonly FormElement[]>(for
  * ```
  *
  * @param options - File path and type name
- * @returns Generated JSON Schema and FormSpec/UI Schema
+ * @returns Generated JSON Schema and UI Schema
  */
 export declare function generateSchemas(options: GenerateSchemasOptions): GenerateFromClassResult;
 
 /**
- * Generates JSON Schema and FormSpec/UI Schema from a decorated TypeScript class.
+ * 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,
+ * creating a TypeScript program, finding the class, analyzing it to IR,
  * and generating schemas — all in one call.
  *
  * @example
@@ -366,7 +298,7 @@ export declare function generateSchemas(options: GenerateSchemasOptions): Genera
  * ```
  *
  * @param options - File path, class name, and optional compiler options
- * @returns Generated JSON Schema and FormSpec/UI Schema
+ * @returns Generated JSON Schema and UI Schema
  */
 export declare function generateSchemasFromClass(options: GenerateFromClassOptions): GenerateFromClassResult;
 
@@ -383,6 +315,9 @@ export declare interface GenerateSchemasOptions {
 /**
  * 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(
@@ -423,32 +358,16 @@ export declare interface GenerateSchemasOptions {
  */
 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`.
+ * Accepts any schema object — `JSONSchema7`, `JsonSchema2020`, `ExtendedJSONSchema7`, etc.
  *
  * @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;
+export declare function getSchemaExtension(schema: object, key: `x-formspec-${string}`): unknown;
 
 /**
  * A group element with a label.
@@ -478,7 +397,44 @@ export declare interface HorizontalLayout {
 export declare const horizontalLayoutSchema: z.ZodType<HorizontalLayout>;
 
 /**
- * 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.
+ */
+export declare interface JsonSchema2020 {
+    $schema?: string;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema2020>;
+    type?: string;
+    properties?: Record<string, JsonSchema2020>;
+    required?: string[];
+    items?: JsonSchema2020;
+    additionalProperties?: boolean;
+    enum?: readonly (string | number)[];
+    const?: string | number | boolean | null;
+    oneOf?: readonly JsonSchema2020[];
+    anyOf?: readonly JsonSchema2020[];
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    pattern?: string;
+    uniqueItems?: boolean;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    deprecated?: boolean;
+    [key: `x-${string}`]: unknown;
+}
+
+/**
+ * A JSON Schema definition (legacy subset used by Zod validator and types.ts).
  */
 export declare interface JSONSchema7 {
     $schema?: string;
@@ -532,7 +488,7 @@ export declare interface JSONSchema7 {
 export declare const jsonSchema7Schema: z.ZodType<JSONSchema7>;
 
 /**
- * JSON Schema Draft-07 type definitions.
+ * JSON Schema type definitions.
  *
  * These types are a subset of JSON Schema sufficient for form generation.
  */
@@ -707,11 +663,6 @@ export declare const ruleSchema: z.ZodObject<{
     };
 }>;
 
-/**
- * Runs the code generation.
- */
-export declare function runCodegen(options: CodegenOptions): void;
-
 /**
  * Condition for a rule.
  */
@@ -742,43 +693,7 @@ export declare const schemaBasedConditionSchema: z.ZodObject<{
  * @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;
-}
+export declare function setSchemaExtension(schema: object, key: `x-formspec-${string}`, value: unknown): void;
 
 /**
  * Root UI Schema (always a layout — not a Control, Category, or Label).

package/dist/canonicalize/chain-dsl-canonicalizer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonicalizer that translates chain DSL `FormSpec` objects into the
+ * canonical FormIR intermediate representation.
+ *
+ * This module maps the runtime objects produced by `@formspec/dsl` builder
+ * functions (`field.*`, `group`, `when`, `formspec`) into the IR that all
+ * downstream phases (validation, JSON Schema generation, UI Schema generation)
+ * consume.
+ */
+import type { FormElement, FormSpec, FormIR } from "@formspec/core";
+/**
+ * Translates a chain DSL `FormSpec` into the canonical `FormIR`.
+ *
+ * @param form - A form specification created via `formspec(...)` from `@formspec/dsl`
+ * @returns The canonical intermediate representation
+ */
+export declare function canonicalizeChainDSL(form: FormSpec<readonly FormElement[]>): FormIR;
+//# sourceMappingURL=chain-dsl-canonicalizer.d.ts.map

package/dist/canonicalize/chain-dsl-canonicalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-dsl-canonicalizer.d.ts","sourceRoot":"","sources":["../../src/canonicalize/chain-dsl-canonicalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EASV,WAAW,EACX,QAAQ,EAiBR,MAAM,EAYP,MAAM,gBAAgB,CAAC;AAqCxB;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,WAAW,EAAE,CAAC,GAAG,MAAM,CAQnF"}

package/dist/canonicalize/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonicalization layer — converts authoring surface output to canonical IR.
+ *
+ * @packageDocumentation
+ */
+export { canonicalizeChainDSL } from "./chain-dsl-canonicalizer.js";
+export { canonicalizeTSDoc, type TSDocSource } from "./tsdoc-canonicalizer.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canonicalize/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/canonicalize/tsdoc-canonicalizer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TSDoc canonicalizer — assembles an {@link IRClassAnalysis} into a canonical
+ * {@link FormIR}, applying layout metadata from `@Group` and `@ShowWhen`
+ * decorators.
+ *
+ * The analysis functions in `class-analyzer.ts` produce `FieldNode[]`,
+ * `fieldLayouts`, and `typeRegistry` directly. This canonicalizer uses
+ * the layout metadata to wrap fields in `GroupLayoutNode` and
+ * `ConditionalLayoutNode` elements.
+ */
+import type { FormIR } from "@formspec/core";
+import type { IRClassAnalysis } from "../analyzer/class-analyzer.js";
+/**
+ * Source-level metadata for provenance tracking.
+ */
+export interface TSDocSource {
+    /** Absolute path to the source file. */
+    readonly file: string;
+}
+/**
+ * Wraps an {@link IRClassAnalysis} (from `analyzeClassToIR`,
+ * `analyzeInterfaceToIR`, or `analyzeTypeAliasToIR`) into a canonical
+ * {@link FormIR}.
+ *
+ * Fields with `@Group` decorators are grouped into `GroupLayoutNode` elements.
+ * Fields with `@ShowWhen` decorators are wrapped in `ConditionalLayoutNode` elements.
+ * When both are present, the conditional wraps the field inside the group.
+ *
+ * @param analysis - IR analysis result (fields are already FieldNode[])
+ * @param source - Optional source file metadata for provenance
+ * @returns The canonical FormIR
+ */
+export declare function canonicalizeTSDoc(analysis: IRClassAnalysis, source?: TSDocSource): FormIR;
+//# sourceMappingURL=tsdoc-canonicalizer.d.ts.map

package/dist/canonicalize/tsdoc-canonicalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc-canonicalizer.d.ts","sourceRoot":"","sources":["../../src/canonicalize/tsdoc-canonicalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,MAAM,EAMP,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,+BAA+B,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAmBzF"}