fix(scripts): updates for multi-value enums and other schema additions

Author: nokome

scripts/lib/generate-conformance.ts

@@ -50,7 +50,9 @@ function extractNodeTypes(oxa: Record<string, unknown>): string[] {
   function walk(node: unknown): void {
     if (node && typeof node === "object" && !Array.isArray(node)) {
       const obj = node as Record<string, unknown>;
-      if (typeof obj.type === "string") {
+      // Only OXA node discriminators are capitalized; nested payload fields such
+      // as CSL's `type: "article-journal"` are not conformance node types.
+      if (typeof obj.type === "string" && /^[A-Z]/.test(obj.type)) {
         types.add(obj.type);
       }
       for (const value of Object.values(obj)) {
@@ -64,7 +66,18 @@ function extractNodeTypes(oxa: Record<string, unknown>): string[] {
   }
 
   walk(oxa);
-  return Array.from(types).sort();
+
+  const rootType = typeof oxa.type === "string" ? oxa.type : undefined;
+  const sortedTypes = Array.from(types).sort();
+
+  if (rootType && types.has(rootType)) {
+    // The first node type is treated as the primary type for docs examples.
+    // Keep nested node types deterministic, but do not let them sort ahead of
+    // the root node (for example, Cite inside CiteGroup).
+    return [rootType, ...sortedTypes.filter((type) => type !== rootType)];
+  }
+
+  return sortedTypes;
 }
 
 /**

scripts/lib/generate-docs.ts

@@ -8,12 +8,15 @@
 import { mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "fs";
 import { join } from "path";
 
-import { manifest, cases, type TestCase } from "@oxa/conformance";
-
 import { loadMergedSchema } from "./schema.js";
 
 const OUTPUT_DIR = join(import.meta.dirname, "../../docs/schema");
 const INDEX_FILE = join(OUTPUT_DIR, "index.md");
+const CONFORMANCE_DIR = join(
+  import.meta.dirname,
+  "../../packages/oxa-conformance",
+);
+const MANIFEST_FILE = join(CONFORMANCE_DIR, "manifest.json");
 
 interface SchemaProperty {
   type?: string;
@@ -36,6 +39,21 @@ interface SchemaDefinition {
   required?: string[];
 }
 
+interface TestCase {
+  formats: Record<string, unknown>;
+}
+
+interface ManifestCase {
+  id: string;
+  path: string;
+  nodeTypes: string[];
+}
+
+interface Manifest {
+  formats: string[];
+  cases: ManifestCase[];
+}
+
 export async function generateDocs(): Promise<void> {
   // Preserve index.md if it exists
   let indexContent: string | null = null;
@@ -56,12 +74,13 @@ export async function generateDocs(): Promise<void> {
 
   const schema = loadMergedSchema();
   const definitions = schema.definitions as Record<string, SchemaDefinition>;
-  const testCases = loadTestCases();
+  const { manifest, cases } = loadConformanceData();
+  const testCases = loadTestCases(manifest, cases);
 
   // Generate documentation for object types (non-union types)
   for (const [name, def] of Object.entries(definitions)) {
     if (!def.anyOf && def.type === "object") {
-      const content = generateDocContent(name, def, testCases);
+      const content = generateDocContent(name, def, testCases, manifest);
       const filePath = join(OUTPUT_DIR, `${name.toLowerCase()}.md`);
       writeFileSync(filePath, content);
       console.log(`Generated ${filePath}`);
@@ -83,6 +102,7 @@ function generateDocContent(
   name: string,
   def: SchemaDefinition,
   testCases: Map<string, TestCase>,
+  manifest: Manifest,
 ): string {
   const lines: string[] = [];
 
@@ -111,6 +131,10 @@ function generateDocContent(
     } else if (prop.enum && prop.enum.length === 1) {
       // Single-element enum (same as const)
       lines.push(`__${propName}__: _string_, ("${prop.enum[0]}")`);
+    } else if (prop.enum && prop.enum.length > 1) {
+      lines.push(
+        `__${propName}__: _string_, (${prop.enum.map((value) => `"${value}"`).join(" | ")})`,
+      );
     } else if (prop.type === "array" && prop.items) {
       const arrayType = getArrayItemType(prop.items);
       lines.push(`__${propName}__: __array__ ("${arrayType}")`);
@@ -137,7 +161,7 @@ function generateDocContent(
   // Add test case example if available
   const testCase = testCases.get(name.toLowerCase());
   if (testCase) {
-    lines.push(generateTestCaseSection(testCase));
+    lines.push(generateTestCaseSection(testCase, manifest));
   }
 
   return lines.join("\n");
@@ -213,7 +237,27 @@ function getArrayItemType(items: { $ref?: string; type?: string }): string {
   return "unknown";
 }
 
-function loadTestCases(): Map<string, TestCase> {
+function loadConformanceData(): {
+  manifest: Manifest;
+  cases: Record<string, TestCase>;
+} {
+  const manifest = JSON.parse(readFileSync(MANIFEST_FILE, "utf-8")) as Manifest;
+  const cases = Object.fromEntries(
+    manifest.cases.map((caseInfo) => [
+      caseInfo.id,
+      JSON.parse(
+        readFileSync(join(CONFORMANCE_DIR, caseInfo.path), "utf-8"),
+      ) as TestCase,
+    ]),
+  );
+
+  return { manifest, cases };
+}
+
+function loadTestCases(
+  manifest: Manifest,
+  cases: Record<string, TestCase>,
+): Map<string, TestCase> {
   const testCases = new Map<string, TestCase>();
 
   // Filter for *-basic test cases
@@ -257,7 +301,10 @@ const FORMAT_LANGUAGES: Record<string, string> = {
   jats: "xml",
 };
 
-function generateTestCaseSection(testCase: TestCase): string {
+function generateTestCaseSection(
+  testCase: TestCase,
+  manifest: Manifest,
+): string {
   const lines: string[] = [];
 
   lines.push("### Example");

scripts/lib/generate-lexicon.ts

@@ -346,6 +346,11 @@ function generateDocumentLexicon(
 function convertPropertyToLexicon(
   prop: SchemaProperty,
 ): Record<string, unknown> | null {
+  // Handle string enums
+  if (prop.enum && prop.enum.length > 1) {
+    return { type: "string", knownValues: prop.enum };
+  }
+
   // Handle arrays
   if (prop.type === "array" && prop.items) {
     if (prop.items.type === "string") {
@@ -415,7 +420,7 @@ function extractNonStructuralProperties(
 ): { properties: Record<string, unknown>; required: string[] } | null {
   if (!def.properties) return null;
 
-  const skip = new Set(["type", "children"]);
+  const skip = new Set(["type", "children", "prefix", "suffix"]);
   if (isFacetFeature) {
     // Facet features don't carry id/classes/data — these are node-level
     // concerns that don't translate to byte-range annotations

scripts/lib/generate-py.ts

@@ -236,6 +236,11 @@ function getPythonType(
     return `Literal["${prop.enum[0]}"]`;
   }
 
+  // Handle multi-value enums as Literal unions
+  if (prop.enum && prop.enum.length > 1) {
+    return `Literal[${prop.enum.map((value) => `"${value}"`).join(", ")}]`;
+  }
+
   // Handle $ref
   if (prop.$ref) {
     const typeName = prop.$ref.replace("#/definitions/", "");

scripts/lib/generate-rs.ts

@@ -75,6 +75,18 @@ export async function generateRs(): Promise<void> {
     "",
   ];
 
+  // Generate property enum types first so structs can use them.
+  for (const [name, def] of Object.entries(definitions)) {
+    if (!def.anyOf && def.type === "object") {
+      for (const [propName, prop] of Object.entries(def.properties || {})) {
+        if (prop.enum && prop.enum.length > 1) {
+          lines.push(...generatePropertyEnum(name, propName, prop));
+          lines.push("");
+        }
+      }
+    }
+  }
+
   // Generate struct types first (non-union types)
   for (const [name, def] of Object.entries(definitions)) {
     if (!def.anyOf && def.type === "object") {
@@ -123,7 +135,7 @@ function generateStruct(name: string, def: SchemaDefinition): string[] {
       lines.push(`    /// ${prop.description}`);
     }
 
-    const rustType = getRustType(prop);
+    const rustType = getRustType(name, propName, prop);
     const isRequired = required.has(propName);
 
     // Handle the "type" field which is a reserved keyword in Rust
@@ -152,6 +164,30 @@ function generateStruct(name: string, def: SchemaDefinition): string[] {
   return lines;
 }
 
+function generatePropertyEnum(
+  ownerName: string,
+  propName: string,
+  prop: SchemaProperty,
+): string[] {
+  const lines: string[] = [];
+  const enumName = getPropertyEnumName(ownerName, propName);
+
+  if (prop.description) {
+    lines.push(`/// ${prop.description}`);
+  }
+
+  lines.push("#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]");
+  lines.push(`pub enum ${enumName} {`);
+
+  for (const value of prop.enum || []) {
+    lines.push(`    #[serde(rename = "${value}")]`);
+    lines.push(`    ${toPascalCase(value)},`);
+  }
+
+  lines.push("}");
+  return lines;
+}
+
 function generateEnum(name: string, def: SchemaDefinition): string[] {
   const lines: string[] = [];
 
@@ -180,7 +216,11 @@ function generateEnum(name: string, def: SchemaDefinition): string[] {
   return lines;
 }
 
-function getRustType(prop: SchemaProperty): string {
+function getRustType(
+  ownerName: string,
+  propName: string,
+  prop: SchemaProperty,
+): string {
   // Handle const values (type discriminator) - use MustBe!
   if (prop.const) {
     return `MustBe!("${prop.const}")`;
@@ -191,6 +231,11 @@ function getRustType(prop: SchemaProperty): string {
     return `MustBe!("${prop.enum[0]}")`;
   }
 
+  // Handle multi-value enums as named Rust enums
+  if (prop.enum && prop.enum.length > 1) {
+    return getPropertyEnumName(ownerName, propName);
+  }
+
   // Handle $ref
   if (prop.$ref) {
     const typeName = prop.$ref.replace("#/definitions/", "");
@@ -229,6 +274,28 @@ function getRustType(prop: SchemaProperty): string {
   }
 }
 
+function getPropertyEnumName(ownerName: string, propName: string): string {
+  return `${ownerName}${toPascalCase(propName)}`;
+}
+
+function toPascalCase(s: string): string {
+  const result = s
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+
+  if (result.length === 0) {
+    return "Value";
+  }
+
+  if (/^[0-9]/.test(result)) {
+    return `Value${result}`;
+  }
+
+  return result;
+}
+
 function toSnakeCase(s: string): string {
   return s
     .replace(/([A-Z])/g, "_$1")

scripts/lib/generate-ts.ts

@@ -156,6 +156,11 @@ function getTypeScriptType(prop: SchemaProperty): string {
     return `"${prop.enum[0]}"`;
   }
 
+  // Handle multi-value enums as literal unions
+  if (prop.enum && prop.enum.length > 1) {
+    return prop.enum.map((value) => `"${value}"`).join(" | ");
+  }
+
   // Handle $ref
   if (prop.$ref) {
     return prop.$ref.replace("#/definitions/", "");