@formspec/build 0.1.0-alpha.2 → 0.1.0-alpha.20

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,79 @@
+/**
+ * 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>`
+ */
+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.
+ */
+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;AAMxB;;;;;;GAMG;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;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,SAAS,mBAAmB,EAAE,GACzC,iBAAiB,CA8FnB"}

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

@@ -0,0 +1,99 @@
+/**
+ * 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 type { UISchema } from "../ui-schema/types.js";
+import { 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";
+/**
+ * Generated schemas for a class.
+ */
+export interface ClassSchemas {
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+/**
+ * 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): ClassSchemas;
+/**
+ * Options for generating schemas from a decorated class.
+ */
+export interface GenerateFromClassOptions extends GenerateJsonSchemaFromIROptions {
+    /** Path to the TypeScript source file */
+    filePath: string;
+    /** Class name to analyze */
+    className: string;
+}
+/**
+ * Result of generating schemas from a decorated class.
+ */
+export interface GenerateFromClassResult {
+    /** JSON Schema 2020-12 for validation */
+    jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering */
+    uiSchema: UISchema;
+}
+/**
+ * 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
+ */
+export declare function generateSchemasFromClass(options: GenerateFromClassOptions): GenerateFromClassResult;
+/**
+ * Options for generating schemas from a named type (class, interface, or type alias).
+ */
+export interface GenerateSchemasOptions extends GenerateJsonSchemaFromIROptions {
+    /** Path to the TypeScript source file */
+    filePath: string;
+    /** Name of the exported class, interface, or type alias to analyze */
+    typeName: string;
+}
+/**
+ * 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",
+ * });
+ * ```
+ *
+ * @param options - File path and type name
+ * @returns Generated JSON Schema and UI Schema
+ */
+export declare function generateSchemas(options: GenerateSchemasOptions): GenerateFromClassResult;
+//# 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":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAMtD,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,cAAc,EACpB,MAAM,gCAAgC,CAAC;AAIxC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,UAAU,EAAE,cAAc,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,+BAA+B,GACxC,YAAY,CAuBd;AAmBD;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,+BAA+B;IAC/E,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,UAAU,EAAE,cAAc,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAsBzB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,+BAA+B;IAC7E,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,uBAAuB,CAOxF"}

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

@@ -0,0 +1,65 @@
+/**
+ * Method schema generator.
+ *
+ * Generates schemas for method parameters and return types, routing through
+ * the canonical IR pipeline (TypeScript type → TypeNode → JSON Schema 2020-12).
+ */
+import type * as ts from "typescript";
+import type { MethodInfo } from "../analyzer/class-analyzer.js";
+import { type JsonSchema2020 } from "../json-schema/ir-generator.js";
+/**
+ * Runtime-loaded FormSpec schemas, compatible with the CLI's FormSpecSchemas type.
+ */
+export interface LoadedFormSpecSchemas {
+    /** The FormSpec export name */
+    name: string;
+    /** Generated JSON Schema */
+    jsonSchema: unknown;
+    /** Generated UI Schema (FormSpec/JSON Forms) */
+    uiSchema: unknown;
+}
+/**
+ * Generated schemas for a method.
+ */
+export interface MethodSchemas {
+    /** Method name */
+    name: string;
+    /** Parameter schemas (from FormSpec or static analysis) */
+    params: MethodParamsSchemas | null;
+    /** Return type schema */
+    returnType: JsonSchema2020;
+}
+/**
+ * Parameter schemas for a method.
+ */
+export interface MethodParamsSchemas {
+    /** JSON Schema for parameters */
+    jsonSchema: JsonSchema2020;
+    /** UI Schema / FormSpec for parameters (if available) */
+    uiSchema: object | null;
+    /** Name of the FormSpec export used (if any) */
+    formSpecExport: string | null;
+}
+/**
+ * Generates schemas for a method's parameters and return type.
+ *
+ * If a parameter references a FormSpec via `InferSchema<typeof X>`,
+ * the schemas are taken from the loaded FormSpec at runtime.
+ * Otherwise, schemas are generated from static type analysis via the IR.
+ *
+ * @param method - The method information from static analysis
+ * @param checker - TypeScript type checker
+ * @param loadedFormSpecs - Map of FormSpec export names to their schemas
+ * @returns Generated method schemas
+ */
+export declare function generateMethodSchemas(method: MethodInfo, checker: ts.TypeChecker, loadedFormSpecs: Map<string, LoadedFormSpecSchemas>): MethodSchemas;
+/**
+ * Collects all FormSpec export names referenced by methods.
+ *
+ * Use this to determine which exports to load at runtime.
+ *
+ * @param methods - Array of method infos
+ * @returns Set of FormSpec export names
+ */
+export declare function collectFormSpecReferences(methods: MethodInfo[]): Set<string>;
+//# sourceMappingURL=method-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"method-schema.d.ts","sourceRoot":"","sources":["../../src/generators/method-schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,+BAA+B,CAAC;AAG/E,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAG/F;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,UAAU,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnC,yBAAyB;IACzB,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,UAAU,EAAE,cAAc,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gDAAgD;IAChD,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AA6CD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,qBAAqB,CAAC,GAClD,aAAa,CAYf;AAmED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAY5E"}

package/dist/generators/mixed-authoring.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Mixed-authoring schema generator.
+ *
+ * Composes a statically analyzed TSDoc/class/interface/type-alias model with
+ * ChainDSL-authored field overlays. The static model remains authoritative for
+ * structure and constraints; overlays may add runtime field behavior such as
+ * dynamic enum or dynamic schema metadata.
+ */
+import type { FormElement, FormSpec } from "@formspec/core";
+import type { GenerateJsonSchemaFromIROptions, JsonSchema2020 } from "../json-schema/ir-generator.js";
+import type { UISchema } from "../ui-schema/types.js";
+/**
+ * Result of generating schemas from a mixed-authoring composition.
+ */
+export interface MixedAuthoringSchemas {
+    /** JSON Schema 2020-12 for validation. */
+    readonly jsonSchema: JsonSchema2020;
+    /** JSON Forms UI Schema for rendering. */
+    readonly uiSchema: UISchema;
+}
+/**
+ * Options for generating mixed-authoring schemas.
+ *
+ * The `typeName` can resolve to a class, interface, or object type alias, just
+ * like `generateSchemas()`.
+ */
+export interface BuildMixedAuthoringSchemasOptions extends GenerateJsonSchemaFromIROptions {
+    /** Path to the TypeScript source file. */
+    readonly filePath: string;
+    /** Name of the class, interface, or type alias to analyze. */
+    readonly typeName: string;
+    /** ChainDSL overlays to apply to the static model. Groups and conditionals are flattened by field name. */
+    readonly overlays: FormSpec<readonly FormElement[]>;
+}
+/**
+ * Builds JSON Schema and UI Schema from a TSDoc-derived model with ChainDSL
+ * field overlays.
+ *
+ * Overlays are matched by field name. The static model wins for structure,
+ * ordering, and constraints; ChainDSL overlays may contribute dynamic runtime
+ * field metadata such as dynamic enum or dynamic schema keywords, and may fill
+ * in missing annotations.
+ */
+export declare function buildMixedAuthoringSchemas(options: BuildMixedAuthoringSchemasOptions): MixedAuthoringSchemas;
+//# sourceMappingURL=mixed-authoring.d.ts.map

package/dist/generators/mixed-authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixed-authoring.d.ts","sourceRoot":"","sources":["../../src/generators/mixed-authoring.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAGV,WAAW,EAEX,QAAQ,EAET,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EACV,+BAA+B,EAC/B,cAAc,EACf,MAAM,gCAAgC,CAAC;AAGxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAKtD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iCAAkC,SAAQ,+BAA+B;IACxF,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2GAA2G;IAC3G,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;CACrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iCAAiC,GACzC,qBAAqB,CAUvB"}