@formspec/build 0.1.0-alpha.26 → 0.1.0-alpha.27

package/dist/build.d.ts

@@ -27,9 +27,7 @@ import { AnyField } from '@formspec/core';
 import { ArrayField } from '@formspec/core';
 import { BooleanField } from '@formspec/core';
 import { BuiltinConstraintBroadeningRegistration } from '@formspec/core';
-import { BuiltinConstraintName } from '@formspec/core';
 import { Conditional } from '@formspec/core';
-import { ConstraintSemanticRole } from '@formspec/core';
 import { ConstraintTagRegistration } from '@formspec/core';
 import { CustomAnnotationRegistration } from '@formspec/core';
 import { CustomConstraintRegistration } from '@formspec/core';
@@ -38,10 +36,7 @@ import { DynamicEnumField } from '@formspec/core';
 import { DynamicSchemaField } from '@formspec/core';
 import { EnumOption } from '@formspec/core';
 import { EnumOptionValue } from '@formspec/core';
-import { ExtensionApplicableType } from '@formspec/core';
 import { ExtensionDefinition } from '@formspec/core';
-import { ExtensionPayloadValue } from '@formspec/core';
-import { ExtensionTypeKind } from '@formspec/core';
 import { FormElement } from '@formspec/core';
 import { FormSpec } from '@formspec/core';
 import { Group } from '@formspec/core';
@@ -49,7 +44,8 @@ import { NumberField } from '@formspec/core';
 import { ObjectField } from '@formspec/core';
 import { StaticEnumField } from '@formspec/core';
 import { TextField } from '@formspec/core';
-import { VocabularyKeywordRegistration } from '@formspec/core';
+import * as ts from 'typescript';
+import { z } from 'zod';
 
 export { AnyField }
 
@@ -142,8 +138,6 @@ export declare interface BuildResult {
 
 export { BuiltinConstraintBroadeningRegistration }
 
-export { BuiltinConstraintName }
-
 /**
  * A Categorization element (tab-based layout).
  *
@@ -186,8 +180,6 @@ export declare interface Category {
 
 export { Conditional }
 
-export { ConstraintSemanticRole }
-
 export { ConstraintTagRegistration }
 
 /**
@@ -239,13 +231,15 @@ export { EnumOption }
 
 export { EnumOptionValue }
 
-/* Excluded from this release type: ExtendedJSONSchema7 */
-export { ExtensionApplicableType }
+/**
+ * JSON Schema with FormSpec extension properties for arbitrary `x-formspec-*` keys.
+ *
+ * @public
+ */
+export declare type ExtendedJSONSchema7 = JSONSchema7 & FormSpecSchemaExtensions;
 
 export { ExtensionDefinition }
 
-export { ExtensionPayloadValue }
-
 /**
  * A registry of extensions that provides lookup by fully-qualified ID.
  *
@@ -305,13 +299,16 @@ export declare interface ExtensionRegistry {
     findAnnotation(annotationId: string): CustomAnnotationRegistration | undefined;
 }
 
-export { ExtensionTypeKind }
-
 export { FormElement }
 
 export { FormSpec }
 
-/* Excluded from this release type: FormSpecSchemaExtensions */
+/**
+ * Extension properties for custom FormSpec constraint tags.
+ *
+ * @public
+ */
+export declare type FormSpecSchemaExtensions = Record<`x-formspec-${string}`, unknown>;
 
 /**
  * Options for generating schemas from a decorated class.
@@ -428,6 +425,34 @@ export declare function generateSchemas(options: GenerateSchemasOptions): Genera
  */
 export declare function generateSchemasFromClass(options: GenerateFromClassOptions): 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.
+ *
+ * @param options - Host program, file path, type name, and optional schema generation options
+ * @returns Generated JSON Schema and UI Schema
+ *
+ * @public
+ */
+export declare function generateSchemasFromProgram(options: GenerateSchemasFromProgramOptions): GenerateFromClassResult;
+
+/**
+ * Options for generating schemas from a named type inside an existing TypeScript program.
+ *
+ * @public
+ */
+export declare 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;
+}
+
 /**
  * Options for generating schemas from a named type (class, interface, or type alias).
  *
@@ -599,9 +624,109 @@ export declare interface JsonSchema2020 {
     [key: `x-${string}`]: unknown;
 }
 
-/* Excluded from this release type: JSONSchema7 */
+/**
+ * A JSON Schema definition (legacy subset used by Zod validator and types.ts).
+ *
+ * @public
+ */
+export declare interface JSONSchema7 {
+    /** Declared JSON Schema dialect URI for the document root. */
+    $schema?: string;
+    /** Stable identifier for the schema document or sub-schema. */
+    $id?: string;
+    /** Reference to another schema location. */
+    $ref?: string;
+    /** Human-readable title for the schema node. */
+    title?: string;
+    /** Human-readable description for the schema node. */
+    description?: string;
+    /** Whether the schema node is deprecated. */
+    deprecated?: boolean;
+    /** JSON Schema type keyword for the current node. */
+    type?: JSONSchemaType | JSONSchemaType[];
+    /** Inclusive minimum string length. */
+    minLength?: number;
+    /** Inclusive maximum string length. */
+    maxLength?: number;
+    /** Regular expression pattern applied to string values. */
+    pattern?: string;
+    /** Inclusive numeric lower bound. */
+    minimum?: number;
+    /** Inclusive numeric upper bound. */
+    maximum?: number;
+    /** Exclusive numeric lower bound. */
+    exclusiveMinimum?: number;
+    /** Exclusive numeric upper bound. */
+    exclusiveMaximum?: number;
+    /** Closed set of allowed scalar values. */
+    enum?: readonly (string | number | boolean | null)[];
+    /** Literal value the instance must equal. */
+    const?: string | number | boolean | null;
+    /** Object properties keyed by property name. */
+    properties?: Record<string, JSONSchema7>;
+    /** Property names that must be present on object values. */
+    required?: string[];
+    /** Whether, or how, additional object properties are allowed. */
+    additionalProperties?: boolean | JSONSchema7;
+    /** Item schema or tuple schemas applied to array elements. */
+    items?: JSONSchema7 | JSONSchema7[];
+    /** Inclusive minimum array length. */
+    minItems?: number;
+    /** Inclusive maximum array length. */
+    maxItems?: number;
+    /** Schemas that must all validate successfully. */
+    allOf?: JSONSchema7[];
+    /** Schemas of which at least one may validate successfully. */
+    anyOf?: JSONSchema7[];
+    /** Schemas of which exactly one should validate successfully. */
+    oneOf?: JSONSchema7[];
+    /** Schema that must not validate successfully. */
+    not?: JSONSchema7;
+    /** Conditional branch predicate schema. */
+    if?: JSONSchema7;
+    /** Schema applied when the `if` branch matches. */
+    then?: JSONSchema7;
+    /** Schema applied when the `if` branch does not match. */
+    else?: JSONSchema7;
+    /** Format hint for downstream validators and tooling. */
+    format?: string;
+    /** Default value suggested for the schema node. */
+    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;
+}
 
-/* Excluded from this release type: JSONSchemaType */
+/**
+ * Zod schema for the legacy JSON Schema 7 subset used by `@formspec/build`.
+ *
+ * @public
+ */
+export declare const jsonSchema7Schema: z.ZodType<JSONSchema7>;
+
+/**
+ * JSON Schema type definitions.
+ *
+ * These types are a subset of JSON Schema sufficient for form generation.
+ */
+/**
+ * JSON Schema primitive types.
+ *
+ * @public
+ */
+export declare type JSONSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
 
 /**
  * A Label element for displaying static text.
@@ -769,6 +894,13 @@ export declare interface UISchemaElementBase {
  */
 export declare type UISchemaElementType = "Control" | "VerticalLayout" | "HorizontalLayout" | "Group" | "Categorization" | "Category" | "Label";
 
+/**
+ * Zod schema for the root UI Schema (layout types only).
+ *
+ * @public
+ */
+export declare const uiSchemaSchema: z.ZodType<UISchema>;
+
 /**
  * A vertical layout element.
  *
@@ -787,8 +919,6 @@ export declare interface VerticalLayout {
     readonly [k: string]: unknown;
 }
 
-export { VocabularyKeywordRegistration }
-
 /**
  * Builds and writes both JSON Schema and UI Schema files to disk.
  *

package/dist/cli.cjs

@@ -1235,6 +1235,74 @@ var init_extensions = __esm({
   }
 });
 
+// src/json-schema/schema.ts
+var import_zod3, jsonSchemaTypeSchema, jsonSchema7Schema;
+var init_schema2 = __esm({
+  "src/json-schema/schema.ts"() {
+    "use strict";
+    import_zod3 = require("zod");
+    jsonSchemaTypeSchema = import_zod3.z.enum([
+      "string",
+      "number",
+      "integer",
+      "boolean",
+      "object",
+      "array",
+      "null"
+    ]);
+    jsonSchema7Schema = import_zod3.z.lazy(
+      () => import_zod3.z.object({
+        $schema: import_zod3.z.string().optional(),
+        $id: import_zod3.z.string().optional(),
+        $ref: import_zod3.z.string().optional(),
+        // Metadata
+        title: import_zod3.z.string().optional(),
+        description: import_zod3.z.string().optional(),
+        deprecated: import_zod3.z.boolean().optional(),
+        // Type
+        type: import_zod3.z.union([jsonSchemaTypeSchema, import_zod3.z.array(jsonSchemaTypeSchema)]).optional(),
+        // String validation
+        minLength: import_zod3.z.number().optional(),
+        maxLength: import_zod3.z.number().optional(),
+        pattern: import_zod3.z.string().optional(),
+        // Number validation
+        minimum: import_zod3.z.number().optional(),
+        maximum: import_zod3.z.number().optional(),
+        exclusiveMinimum: import_zod3.z.number().optional(),
+        exclusiveMaximum: import_zod3.z.number().optional(),
+        // Enum
+        enum: import_zod3.z.array(import_zod3.z.union([import_zod3.z.string(), import_zod3.z.number(), import_zod3.z.boolean(), import_zod3.z.null()])).readonly().optional(),
+        const: import_zod3.z.union([import_zod3.z.string(), import_zod3.z.number(), import_zod3.z.boolean(), import_zod3.z.null()]).optional(),
+        // Object
+        properties: import_zod3.z.record(import_zod3.z.string(), jsonSchema7Schema).optional(),
+        required: import_zod3.z.array(import_zod3.z.string()).optional(),
+        additionalProperties: import_zod3.z.union([import_zod3.z.boolean(), jsonSchema7Schema]).optional(),
+        // Array
+        items: import_zod3.z.union([jsonSchema7Schema, import_zod3.z.array(jsonSchema7Schema)]).optional(),
+        minItems: import_zod3.z.number().optional(),
+        maxItems: import_zod3.z.number().optional(),
+        // Composition
+        allOf: import_zod3.z.array(jsonSchema7Schema).optional(),
+        anyOf: import_zod3.z.array(jsonSchema7Schema).optional(),
+        oneOf: import_zod3.z.array(jsonSchema7Schema).optional(),
+        not: jsonSchema7Schema.optional(),
+        // Conditional
+        if: jsonSchema7Schema.optional(),
+        then: jsonSchema7Schema.optional(),
+        else: jsonSchema7Schema.optional(),
+        // Format
+        format: import_zod3.z.string().optional(),
+        // Default
+        default: import_zod3.z.unknown().optional(),
+        // FormSpec extensions
+        "x-formspec-source": import_zod3.z.string().optional(),
+        "x-formspec-params": import_zod3.z.array(import_zod3.z.string()).readonly().optional(),
+        "x-formspec-schemaSource": import_zod3.z.string().optional()
+      }).passthrough()
+    );
+  }
+});
+
 // src/analyzer/tsdoc-parser.ts
 function createFormSpecTSDocConfig(extensionTagNames = []) {
   const config = new import_tsdoc.TSDocConfiguration();
@@ -3204,6 +3272,18 @@ var init_class_analyzer = __esm({
 });
 
 // src/analyzer/program.ts
+function createProgramContextFromProgram(program, filePath) {
+  const absolutePath = path.resolve(filePath);
+  const sourceFile = program.getSourceFile(absolutePath) ?? program.getSourceFile(filePath);
+  if (!sourceFile) {
+    throw new Error(`Could not find source file in provided program: ${absolutePath}`);
+  }
+  return {
+    program,
+    checker: program.getTypeChecker(),
+    sourceFile
+  };
+}
 function createProgramContext(filePath) {
   const absolutePath = path.resolve(filePath);
   const fileDir = path.dirname(absolutePath);
@@ -3274,24 +3354,33 @@ function findTypeAliasByName(sourceFile, aliasName) {
 }
 function analyzeNamedTypeToIR(filePath, typeName, extensionRegistry) {
   const ctx = createProgramContext(filePath);
+  return analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry);
+}
+function analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry) {
+  const analysisFilePath = path.resolve(filePath);
   const classDecl = findClassByName(ctx.sourceFile, typeName);
   if (classDecl !== null) {
-    return analyzeClassToIR(classDecl, ctx.checker, filePath, extensionRegistry);
+    return analyzeClassToIR(classDecl, ctx.checker, analysisFilePath, extensionRegistry);
   }
   const interfaceDecl = findInterfaceByName(ctx.sourceFile, typeName);
   if (interfaceDecl !== null) {
-    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, filePath, extensionRegistry);
+    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, analysisFilePath, extensionRegistry);
   }
   const typeAlias = findTypeAliasByName(ctx.sourceFile, typeName);
   if (typeAlias !== null) {
-    const result = analyzeTypeAliasToIR(typeAlias, ctx.checker, filePath, extensionRegistry);
+    const result = analyzeTypeAliasToIR(
+      typeAlias,
+      ctx.checker,
+      analysisFilePath,
+      extensionRegistry
+    );
     if (result.ok) {
       return result.analysis;
     }
     throw new Error(result.error);
   }
   throw new Error(
-    `Type "${typeName}" not found as a class, interface, or type alias in ${filePath}`
+    `Type "${typeName}" not found as a class, interface, or type alias in ${analysisFilePath}`
   );
 }
 var ts4, path;
@@ -3448,16 +3537,34 @@ function generateSchemasFromClass(options) {
   );
 }
 function generateSchemas(options) {
-  const analysis = analyzeNamedTypeToIR(
+  const ctx = createProgramContext(options.filePath);
+  return generateSchemasFromProgram({
+    ...options,
+    program: ctx.program
+  });
+}
+function generateSchemasFromProgram(options) {
+  const ctx = createProgramContextFromProgram(options.program, options.filePath);
+  const analysis = analyzeNamedTypeToIRFromProgramContext(
+    ctx,
     options.filePath,
     options.typeName,
     options.extensionRegistry
   );
-  return generateClassSchemas(analysis, { file: options.filePath }, options);
+  return generateClassSchemas(
+    analysis,
+    { file: options.filePath },
+    {
+      extensionRegistry: options.extensionRegistry,
+      vendorPrefix: options.vendorPrefix
+    }
+  );
 }
+var ts5;
 var init_class_schema = __esm({
   "src/generators/class-schema.ts"() {
     "use strict";
+    ts5 = require("typescript");
     init_program();
     init_class_analyzer();
     init_canonicalize();
@@ -3661,7 +3768,10 @@ __export(index_exports, {
   generateJsonSchema: () => generateJsonSchema,
   generateSchemas: () => generateSchemas,
   generateSchemasFromClass: () => generateSchemasFromClass,
+  generateSchemasFromProgram: () => generateSchemasFromProgram,
   generateUiSchema: () => generateUiSchema,
+  jsonSchema7Schema: () => jsonSchema7Schema,
+  uiSchemaSchema: () => uiSchema,
   writeSchemas: () => writeSchemas
 });
 function buildFormSchemas(form, options) {
@@ -3693,6 +3803,8 @@ var init_index = __esm({
     fs = __toESM(require("fs"), 1);
     path2 = __toESM(require("path"), 1);
     init_extensions();
+    init_schema2();
+    init_schema();
     init_generator();
     init_generator2();
     init_class_schema();