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

package/dist/internals.js

@@ -51,11 +51,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) {
@@ -152,6 +176,40 @@ function resolveResolvedMetadata(current, policy, context) {
     ...displayNamePlural !== void 0 && { displayNamePlural }
   };
 }
+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":
@@ -174,9 +232,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;
@@ -255,11 +314,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 {
@@ -295,7 +353,7 @@ function canonicalizeChainDSL(form, options) {
   const metadataPolicy = normalizeMetadataPolicy(
     options?.metadata ?? _getFormSpecMetadataPolicy(form)
   );
-  return {
+  const ir = {
     kind: "form-ir",
     irVersion: IR_VERSION,
     elements: canonicalizeElements(form.elements, metadataPolicy),
@@ -303,6 +361,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));
@@ -4171,17 +4236,25 @@ function assertNoSerializedNameCollisions(ir) {
 // 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) {
@@ -4355,7 +4428,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":
@@ -4381,20 +4454,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 {
@@ -4743,6 +4833,66 @@ function generateCustomType(type, ctx) {
   }
   return registration.toJsonSchema(type.payload, ctx.vendorPrefix);
 }
+var 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"
+]);
 function applyCustomConstraint(schema, constraint, ctx) {
   const registration = ctx.extensionRegistry?.findConstraint(constraint.constraintId);
   if (registration === void 0) {
@@ -4750,12 +4900,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);
@@ -5319,7 +5482,7 @@ function createExtensionRegistry(extensions) {
 
 // src/generators/method-schema.ts
 import { IR_VERSION as IR_VERSION3 } from "@formspec/core/internals";
-function typeToJsonSchema(type, checker) {
+function typeToJsonSchema(type, checker, options) {
   const typeRegistry = {};
   const visiting = /* @__PURE__ */ new Set();
   const diagnostics = [];
@@ -5359,7 +5522,10 @@ function typeToJsonSchema(type, checker) {
     typeRegistry,
     provenance: fieldProvenance
   };
-  const schema = generateJsonSchemaFromIR(ir);
+  const schema = generateJsonSchemaFromIR(
+    ir,
+    options?.enumSerialization === void 0 ? void 0 : { enumSerialization: options.enumSerialization }
+  );
   const fieldSchema = schema.properties?.["__result"];
   if (fieldSchema) {
     if (schema.$defs && Object.keys(schema.$defs).length > 0) {
@@ -5369,16 +5535,16 @@ function typeToJsonSchema(type, checker) {
   }
   return { type: "object" };
 }
-function generateMethodSchemas(method, checker, loadedFormSpecs) {
-  const returnType = typeToJsonSchema(method.returnType, checker);
-  const params = generateParamsSchemas(method.parameters, checker, loadedFormSpecs);
+function generateMethodSchemas(method, checker, loadedFormSpecs, options) {
+  const returnType = typeToJsonSchema(method.returnType, checker, options);
+  const params = generateParamsSchemas(method.parameters, checker, loadedFormSpecs, options);
   return {
     name: method.name,
     params,
     returnType
   };
 }
-function generateParamsSchemas(parameters, checker, loadedFormSpecs) {
+function generateParamsSchemas(parameters, checker, loadedFormSpecs, options) {
   if (parameters.length === 0) {
     return null;
   }
@@ -5399,7 +5565,7 @@ function generateParamsSchemas(parameters, checker, loadedFormSpecs) {
   }
   if (parameters.length === 1 && parameters[0]) {
     const param = parameters[0];
-    const jsonSchema = typeToJsonSchema(param.type, checker);
+    const jsonSchema = typeToJsonSchema(param.type, checker, options);
     return {
       jsonSchema,
       uiSchema: null,
@@ -5409,7 +5575,7 @@ function generateParamsSchemas(parameters, checker, loadedFormSpecs) {
   const properties = {};
   const required = [];
   for (const param of parameters) {
-    const paramSchema = typeToJsonSchema(param.type, checker);
+    const paramSchema = typeToJsonSchema(param.type, checker, options);
     properties[param.name] = paramSchema;
     if (!param.optional) {
       required.push(param.name);