@formspec/build 0.1.0-alpha.40 → 0.1.0-alpha.42

package/dist/build-alpha.d.ts

@@ -467,6 +467,11 @@ export declare interface GenerateJsonSchemaOptions {
      * @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 chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
 }
@@ -1284,6 +1289,11 @@ export declare interface StaticSchemaGenerationOptions {
      * @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. */

package/dist/build-beta.d.ts

@@ -467,6 +467,11 @@ export declare interface GenerateJsonSchemaOptions {
      * @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 chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
 }
@@ -1284,6 +1289,11 @@ export declare interface StaticSchemaGenerationOptions {
      * @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. */

package/dist/build-internal.d.ts

@@ -467,6 +467,11 @@ export declare interface GenerateJsonSchemaOptions {
      * @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 chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
 }
@@ -1284,6 +1289,11 @@ export declare interface StaticSchemaGenerationOptions {
      * @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. */

package/dist/build.d.ts

@@ -467,6 +467,11 @@ export declare interface GenerateJsonSchemaOptions {
      * @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 chain DSL generation. */
     readonly metadata?: MetadataPolicyInput | undefined;
 }
@@ -1284,6 +1289,11 @@ export declare interface StaticSchemaGenerationOptions {
      * @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. */

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

@@ -1 +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,EAMR,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAYV,MAAM,EAaP,MAAM,0BAA0B,CAAC;AA2ClC;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,CAAC,SAAS,WAAW,EAAE,CAAC,EACtC,OAAO,CAAC,EAAE,2BAA2B,GACpC,MAAM,CAYR"}
+{"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,EAMR,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAYV,MAAM,EAaP,MAAM,0BAA0B,CAAC;AA4ClC;;;;;GAKG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CACzC;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,CAAC,SAAS,WAAW,EAAE,CAAC,EACtC,OAAO,CAAC,EAAE,2BAA2B,GACpC,MAAM,CAoBR"}

package/dist/cli.cjs

@@ -79,11 +79,35 @@ function normalizeDeclarationPolicy(input) {
     displayName: normalizeScalarPolicy(input?.displayName)
   };
 }
+function normalizeEnumMemberDisplayNamePolicy(input) {
+  if (input?.mode === "infer-if-missing") {
+    return {
+      mode: "infer-if-missing",
+      infer: input.infer
+    };
+  }
+  if (input?.mode === "require-explicit") {
+    return {
+      mode: "require-explicit",
+      infer: () => ""
+    };
+  }
+  return {
+    mode: "disabled",
+    infer: () => ""
+  };
+}
+function normalizeEnumMemberPolicy(input) {
+  return {
+    displayName: normalizeEnumMemberDisplayNamePolicy(input?.displayName)
+  };
+}
 function normalizeMetadataPolicy(input) {
   return {
     type: normalizeDeclarationPolicy(input?.type),
     field: normalizeDeclarationPolicy(input?.field),
-    method: normalizeDeclarationPolicy(input?.method)
+    method: normalizeDeclarationPolicy(input?.method),
+    enumMember: normalizeEnumMemberPolicy(input?.enumMember)
   };
 }
 function getDeclarationMetadataPolicy(policy, declarationKind) {
@@ -196,6 +220,40 @@ function pickResolvedMetadataValue(baseValue, overlayValue) {
   }
   return baseValue ?? overlayValue;
 }
+function resolveEnumMemberDisplayName(current, policy, context) {
+  if (current !== void 0) {
+    return current;
+  }
+  if (policy.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit displayName for enum member "${context.logicalName}" on the ${context.surface} surface.`
+    );
+  }
+  if (policy.mode !== "infer-if-missing") {
+    return void 0;
+  }
+  const inferredValue = policy.infer(context).trim();
+  return inferredValue !== "" ? inferredValue : void 0;
+}
+function resolveEnumTypeMetadata(type, options) {
+  const members = type.members.map((member) => {
+    const displayName = resolveEnumMemberDisplayName(
+      member.displayName,
+      options.policy.enumMember.displayName,
+      {
+        surface: options.surface,
+        logicalName: String(member.value),
+        memberValue: member.value,
+        ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+      }
+    );
+    if (displayName === member.displayName) {
+      return member;
+    }
+    return displayName === void 0 ? { value: member.value } : { value: member.value, displayName };
+  });
+  return members.some((member, index) => member !== type.members[index]) ? { ...type, members } : type;
+}
 function resolveTypeNodeMetadata(type, options) {
   switch (type.kind) {
     case "array":
@@ -218,9 +276,10 @@ function resolveTypeNodeMetadata(type, options) {
         ...type,
         members: type.members.map((member) => resolveTypeNodeMetadata(member, options))
       };
+    case "enum":
+      return resolveEnumTypeMetadata(type, options);
     case "reference":
     case "primitive":
-    case "enum":
     case "dynamic":
     case "custom":
       return type;
@@ -323,11 +382,10 @@ function getDisplayName(metadata) {
   return metadata?.displayName?.value;
 }
 function resolveFormIRMetadata(ir, options) {
-  const rootLogicalName = options.rootLogicalName ?? ir.name ?? "FormSpec";
-  const metadata = resolveResolvedMetadata(ir.metadata, options.policy.type, {
+  const metadata = options.resolveRootTypeMetadata === false ? ir.metadata : resolveResolvedMetadata(ir.metadata, options.policy.type, {
     surface: options.surface,
     declarationKind: "type",
-    logicalName: rootLogicalName,
+    logicalName: options.rootLogicalName ?? ir.name ?? "FormSpec",
     ...options.buildContext !== void 0 && { buildContext: options.buildContext }
   });
   return {
@@ -372,7 +430,7 @@ function canonicalizeChainDSL(form, options) {
   const metadataPolicy = normalizeMetadataPolicy(
     options?.metadata ?? (0, import_internals._getFormSpecMetadataPolicy)(form)
   );
-  return {
+  const ir = {
     kind: "form-ir",
     irVersion: import_internals.IR_VERSION,
     elements: canonicalizeElements(form.elements, metadataPolicy),
@@ -380,6 +438,13 @@ function canonicalizeChainDSL(form, options) {
     typeRegistry: {},
     provenance: CHAIN_DSL_PROVENANCE
   };
+  return resolveFormIRMetadata(ir, {
+    policy: metadataPolicy,
+    surface: "chain-dsl",
+    // Chain DSL has no root/type-metadata authoring surface, so only resolve
+    // field/type-registry metadata and enum-member labels here.
+    resolveRootTypeMetadata: false
+  });
 }
 function canonicalizeElements(elements, metadataPolicy) {
   return elements.map((element) => canonicalizeElement(element, metadataPolicy));
@@ -953,17 +1018,25 @@ var init_collision_guards = __esm({
 // src/json-schema/ir-generator.ts
 function makeContext(options) {
   const vendorPrefix = options?.vendorPrefix ?? "x-formspec";
+  const rawEnumSerialization = options?.enumSerialization;
   if (!vendorPrefix.startsWith("x-")) {
     throw new Error(
       `Invalid vendorPrefix "${vendorPrefix}". Extension JSON Schema keywords must start with "x-".`
     );
   }
+  if (rawEnumSerialization !== void 0 && rawEnumSerialization !== "enum" && rawEnumSerialization !== "oneOf") {
+    throw new Error(
+      `Invalid enumSerialization "${rawEnumSerialization}". Expected "enum" or "oneOf".`
+    );
+  }
+  const enumSerialization = rawEnumSerialization ?? "enum";
   return {
     defs: {},
     typeNameMap: {},
     typeRegistry: {},
     extensionRegistry: options?.extensionRegistry,
-    vendorPrefix
+    vendorPrefix,
+    enumSerialization
   };
 }
 function generateJsonSchemaFromIR(ir, options) {
@@ -1137,7 +1210,7 @@ function generateTypeNode(type, ctx) {
     case "primitive":
       return generatePrimitiveType(type);
     case "enum":
-      return generateEnumType(type);
+      return generateEnumType(type, ctx);
     case "array":
       return generateArrayType(type, ctx);
     case "object":
@@ -1163,20 +1236,37 @@ function generatePrimitiveType(type) {
     type: type.primitiveKind === "integer" || type.primitiveKind === "bigint" ? "integer" : type.primitiveKind
   };
 }
-function generateEnumType(type) {
-  const hasDisplayNames = type.members.some((m) => m.displayName !== void 0);
-  if (hasDisplayNames) {
+function generateEnumType(type, ctx) {
+  if (ctx.enumSerialization === "oneOf") {
     return {
-      oneOf: type.members.map((m) => {
-        const entry = { const: m.value };
-        if (m.displayName !== void 0) {
-          entry.title = m.displayName;
-        }
-        return entry;
-      })
+      oneOf: type.members.map((m) => ({
+        const: m.value,
+        title: m.displayName ?? String(m.value)
+      }))
     };
   }
-  return { enum: type.members.map((m) => m.value) };
+  const schema = { enum: type.members.map((m) => m.value) };
+  const displayNames = buildEnumDisplayNameExtension(type);
+  if (displayNames !== void 0) {
+    schema[`${ctx.vendorPrefix}-display-names`] = displayNames;
+  }
+  return schema;
+}
+function buildEnumDisplayNameExtension(type) {
+  if (!type.members.some((member) => member.displayName !== void 0)) {
+    return void 0;
+  }
+  const displayNames = /* @__PURE__ */ Object.create(null);
+  for (const member of type.members) {
+    const key = String(member.value);
+    if (Object.hasOwn(displayNames, key)) {
+      throw new Error(
+        `Enum display-name key "${key}" is ambiguous after stringification. Use oneOf serialization for mixed string/number enum values that collide.`
+      );
+    }
+    displayNames[key] = member.displayName ?? key;
+  }
+  return displayNames;
 }
 function generateArrayType(type, ctx) {
   return {
@@ -1532,12 +1622,25 @@ function applyCustomConstraint(schema, constraint, ctx) {
       `Cannot generate JSON Schema for custom constraint "${constraint.constraintId}" without a matching extension registration`
     );
   }
-  assignVendorPrefixedExtensionKeywords(
-    schema,
-    registration.toJsonSchema(constraint.payload, ctx.vendorPrefix),
-    ctx.vendorPrefix,
-    `custom constraint "${constraint.constraintId}"`
-  );
+  const extensionSchema = registration.toJsonSchema(constraint.payload, ctx.vendorPrefix);
+  if (registration.emitsVocabularyKeywords) {
+    const target = schema;
+    for (const [key, value] of Object.entries(extensionSchema)) {
+      if (JSON_SCHEMA_STRUCTURAL_KEYWORDS.has(key)) {
+        throw new Error(
+          `Custom constraint "${constraint.constraintId}" with emitsVocabularyKeywords must not overwrite standard JSON Schema keyword "${key}"`
+        );
+      }
+      target[key] = value;
+    }
+  } else {
+    assignVendorPrefixedExtensionKeywords(
+      schema,
+      extensionSchema,
+      ctx.vendorPrefix,
+      `custom constraint "${constraint.constraintId}"`
+    );
+  }
 }
 function applyCustomAnnotation(schema, annotation, ctx) {
   const registration = ctx.extensionRegistry?.findAnnotation(annotation.annotationId);
@@ -1566,21 +1669,88 @@ function assignVendorPrefixedExtensionKeywords(schema, extensionSchema, vendorPr
     schema[key] = value;
   }
 }
+var JSON_SCHEMA_STRUCTURAL_KEYWORDS;
 var init_ir_generator = __esm({
   "src/json-schema/ir-generator.ts"() {
     "use strict";
     init_metadata();
     init_collision_guards();
+    JSON_SCHEMA_STRUCTURAL_KEYWORDS = /* @__PURE__ */ new Set([
+      "$schema",
+      "$ref",
+      "$defs",
+      "$id",
+      "$anchor",
+      "$dynamicRef",
+      "$dynamicAnchor",
+      "$vocabulary",
+      "$comment",
+      "type",
+      "enum",
+      "const",
+      "properties",
+      "patternProperties",
+      "additionalProperties",
+      "required",
+      "items",
+      "prefixItems",
+      "additionalItems",
+      "contains",
+      "allOf",
+      "oneOf",
+      "anyOf",
+      "not",
+      "if",
+      "then",
+      "else",
+      "minimum",
+      "maximum",
+      "exclusiveMinimum",
+      "exclusiveMaximum",
+      "multipleOf",
+      "minLength",
+      "maxLength",
+      "pattern",
+      "minItems",
+      "maxItems",
+      "uniqueItems",
+      "minProperties",
+      "maxProperties",
+      "minContains",
+      "maxContains",
+      "format",
+      "title",
+      "description",
+      "default",
+      "deprecated",
+      "readOnly",
+      "writeOnly",
+      "examples",
+      "dependentRequired",
+      "dependentSchemas",
+      "propertyNames",
+      "unevaluatedItems",
+      "unevaluatedProperties",
+      "contentEncoding",
+      "contentMediaType",
+      "contentSchema"
+    ]);
   }
 });
 
 // src/json-schema/generator.ts
 function generateJsonSchema(form, options) {
+  const metadata = options?.metadata;
+  const vendorPrefix = options?.vendorPrefix;
+  const enumSerialization = options?.enumSerialization;
   const ir = canonicalizeChainDSL(
     form,
-    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+    metadata !== void 0 ? { metadata } : void 0
   );
-  const internalOptions = options?.vendorPrefix === void 0 ? void 0 : { vendorPrefix: options.vendorPrefix };
+  const internalOptions = vendorPrefix === void 0 && enumSerialization === void 0 ? void 0 : {
+    ...vendorPrefix !== void 0 && { vendorPrefix },
+    ...enumSerialization !== void 0 && { enumSerialization }
+  };
   return generateJsonSchemaFromIR(ir, internalOptions);
 }
 var init_generator = __esm({
@@ -5594,6 +5764,7 @@ function generateSchemasFromClass(options) {
     {
       extensionRegistry: options.extensionRegistry,
       metadata: options.metadata,
+      enumSerialization: options.enumSerialization,
       vendorPrefix: options.vendorPrefix
     }
   );
@@ -5723,6 +5894,7 @@ function generateSchemasFromDetailedProgramContext(ctx, filePath, typeName, opti
     {
       extensionRegistry: options.extensionRegistry,
       metadata: options.metadata,
+      enumSerialization: options.enumSerialization,
       vendorPrefix: options.vendorPrefix
     }
   );
@@ -5939,7 +6111,7 @@ function toStandaloneJsonSchema(root, typeRegistry, options) {
       column: 0
     }
   };
-  const schema = generateJsonSchemaFromIR(
+  const ir = resolveFormIRMetadata(
     {
       kind: "form-ir",
       name: root.name,
@@ -5950,8 +6122,17 @@ function toStandaloneJsonSchema(root, typeRegistry, options) {
       typeRegistry,
       provenance: syntheticField.provenance
     },
+    {
+      policy: normalizeMetadataPolicy(options?.metadata),
+      surface: "tsdoc",
+      rootLogicalName: root.name
+    }
+  );
+  const schema = generateJsonSchemaFromIR(
+    ir,
     {
       extensionRegistry: options?.extensionRegistry,
+      enumSerialization: options?.enumSerialization,
       vendorPrefix: options?.vendorPrefix
     }
   );
@@ -5978,6 +6159,7 @@ function generateSchemasFromAnalysis(analysis, filePath, options) {
       { file: filePath },
       {
         extensionRegistry: options?.extensionRegistry,
+        enumSerialization: options?.enumSerialization,
         metadata: options?.metadata,
         vendorPrefix: options?.vendorPrefix
       }
@@ -6425,8 +6607,19 @@ function buildFormSchemas(form, options) {
   };
 }
 function writeSchemas(form, options) {
-  const { outDir, name = "schema", indent = 2, vendorPrefix, metadata } = options;
-  const buildOptions = vendorPrefix === void 0 && metadata === void 0 ? void 0 : { vendorPrefix, metadata };
+  const {
+    outDir,
+    name = "schema",
+    indent = 2,
+    vendorPrefix,
+    enumSerialization,
+    metadata
+  } = options;
+  const buildOptions = vendorPrefix === void 0 && enumSerialization === void 0 && metadata === void 0 ? void 0 : {
+    ...vendorPrefix !== void 0 && { vendorPrefix },
+    ...enumSerialization !== void 0 && { enumSerialization },
+    ...metadata !== void 0 && { metadata }
+  };
   const { jsonSchema, uiSchema: uiSchema2 } = buildFormSchemas(form, buildOptions);
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });
@@ -6474,6 +6667,8 @@ Usage:
 Options:
   -o, --out-dir <dir>   Output directory (default: ./generated)
   -n, --name <name>     Base name for output files (default: derived from input)
+  --enum-serialization <enum|oneOf>
+                         Enum JSON Schema representation (default: enum)
   -h, --help            Show this help message
 
 Example:
@@ -6490,6 +6685,7 @@ function parseArgs(args) {
   const positional = [];
   let outDir = "./generated";
   let name = "";
+  let enumSerialization = "enum";
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === void 0) continue;
@@ -6517,6 +6713,20 @@ function parseArgs(args) {
       i++;
       continue;
     }
+    if (arg === "--enum-serialization") {
+      const nextArg = args[i + 1];
+      if (!nextArg) {
+        console.error("Error: --enum-serialization requires a value");
+        return null;
+      }
+      if (nextArg !== "enum" && nextArg !== "oneOf") {
+        console.error('Error: --enum-serialization must be "enum" or "oneOf"');
+        return null;
+      }
+      enumSerialization = nextArg;
+      i++;
+      continue;
+    }
     if (arg.startsWith("-")) {
       console.error(`Error: Unknown option: ${arg}`);
       return null;
@@ -6536,7 +6746,7 @@ function parseArgs(args) {
   if (!name) {
     name = path3.basename(inputFile, path3.extname(inputFile));
   }
-  return { inputFile, outDir, name };
+  return { inputFile, outDir, name, enumSerialization };
 }
 async function main() {
   const args = process.argv.slice(2);
@@ -6544,7 +6754,7 @@ async function main() {
   if (!options) {
     process.exit(1);
   }
-  const { inputFile, outDir, name } = options;
+  const { inputFile, outDir, name, enumSerialization } = options;
   const absoluteInput = path3.resolve(process.cwd(), inputFile);
   try {
     const fileUrl = (0, import_node_url.pathToFileURL)(absoluteInput).href;
@@ -6561,7 +6771,7 @@ async function main() {
     const { writeSchemas: writeSchemas2 } = await Promise.resolve().then(() => (init_index(), index_exports));
     const { jsonSchemaPath, uiSchemaPath } = writeSchemas2(
       form,
-      { outDir, name }
+      { outDir, name, enumSerialization }
     );
     console.log("Generated:");
     console.log(`  ${jsonSchemaPath}`);