🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
fix(api): title OpenAPI union variants for Scalar (#16701)
Tobias Wochinger99aa9785afbc
diff --git a/package.json b/package.jsonindex 700c9cabba..63f8022870 100644--- a/package.json+++ b/package.json@@ -38,7 +38,7 @@"format": "prettier --write \"**/*.{js,jsx,ts,tsx,css}\" --experimental-cli","format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,css}\" --experimental-cli","playwright:install": "pnpm --filter web exec playwright install chromium",- "openapi:export": "npx fern-api export --api server web/public/generated/api/openapi.yml && pnpm --filter web exec tsx scripts/openapi/sync-deprecations.ts && npx fern-api export --api client web/public/generated/api-client/openapi.yml && npx fern-api export --api organizations web/public/generated/organizations-api/openapi.yml",+ "openapi:export": "npx fern-api export --api server web/public/generated/api/openapi.yml && pnpm --filter web exec tsx scripts/openapi/postprocess-openapi.ts && npx fern-api export --api client web/public/generated/api-client/openapi.yml && npx fern-api export --api organizations web/public/generated/organizations-api/openapi.yml","storybook": "pnpm --filter web run storybook","test": "turbo run test","release": "bash ./scripts/release-preflight.sh && dotenv -e ../.env -- release-it",diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex a2008c9afa..46477fb5de 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -10983,6 +10983,7 @@ components:- $ref: '#/components/schemas/NumericScoreV1'required:- dataType+ title: NumericScoreV1- type: objectallOf:- type: object@@ -10994,6 +10995,7 @@ components:- $ref: '#/components/schemas/CategoricalScoreV1'required:- dataType+ title: CategoricalScoreV1- type: objectallOf:- type: object@@ -11005,6 +11007,7 @@ components:- $ref: '#/components/schemas/BooleanScoreV1'required:- dataType+ title: BooleanScoreV1- type: objectallOf:- type: object@@ -11016,6 +11019,7 @@ components:- $ref: '#/components/schemas/TextScoreV1'required:- dataType+ title: TextScoreV1BaseScore:title: BaseScoretype: object@@ -11185,6 +11189,7 @@ components:- $ref: '#/components/schemas/NumericScore'required:- dataType+ title: NumericScore- type: objectallOf:- type: object@@ -11196,6 +11201,7 @@ components:- $ref: '#/components/schemas/CategoricalScore'required:- dataType+ title: CategoricalScore- type: objectallOf:- type: object@@ -11207,6 +11213,7 @@ components:- $ref: '#/components/schemas/BooleanScore'required:- dataType+ title: BooleanScore- type: objectallOf:- type: object@@ -11218,6 +11225,7 @@ components:- $ref: '#/components/schemas/CorrectionScore'required:- dataType+ title: CorrectionScore- type: objectallOf:- type: object@@ -11229,6 +11237,7 @@ components:- $ref: '#/components/schemas/TextScore'required:- dataType+ title: TextScoreproperties:_deprecation:$ref: '#/components/schemas/Deprecation'@@ -11238,7 +11247,9 @@ components:oneOf:- type: numberformat: double+ title: DoubleNumber- type: string+ title: Stringdescription: >-The value of the score. Must be passed as string for categorical andtext scores, and numeric for boolean and numeric scores@@ -12015,17 +12026,22 @@ components:oneOf:- type: stringnullable: true+ title: String- type: integernullable: true+ title: Integer- type: numberformat: floatnullable: true+ title: FloatNumber- type: booleannullable: true+ title: Boolean- type: arrayitems:type: stringnullable: true+ title: ArrayCommentObjectType:title: CommentObjectTypetype: string@@ -12328,6 +12344,7 @@ components:- $ref: '#/components/schemas/PublicEvaluatorNumericScore'required:- dataType+ title: PublicEvaluatorNumericScore- type: objectallOf:- type: object@@ -12339,6 +12356,7 @@ components:- $ref: '#/components/schemas/PublicEvaluatorBooleanScore'required:- dataType+ title: PublicEvaluatorBooleanScore- type: objectallOf:- type: object@@ -12350,6 +12368,7 @@ components:- $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'required:- dataType+ title: PublicEvaluatorCategoricalScoredescription: >-Flat structured output definition used when creating or updating anevaluator.@@ -12451,6 +12470,7 @@ components:- $ref: '#/components/schemas/PublicEvaluatorNumericScore'required:- dataType+ title: PublicEvaluatorNumericScore- type: objectallOf:- type: object@@ -12462,6 +12482,7 @@ components:- $ref: '#/components/schemas/PublicEvaluatorBooleanScore'required:- dataType+ title: PublicEvaluatorBooleanScore- type: objectallOf:- type: object@@ -12473,6 +12494,7 @@ components:- $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'required:- dataType+ title: PublicEvaluatorCategoricalScoredescription: >-Flat evaluator output definition returned by the public API.@@ -12876,6 +12898,7 @@ components:- $ref: '#/components/schemas/DateTimeEvaluationRuleFilter'required:- type+ title: DateTimeEvaluationRuleFilter- type: objectallOf:- type: object@@ -12887,6 +12910,7 @@ components:- $ref: '#/components/schemas/StringEvaluationRuleFilter'required:- type+ title: StringEvaluationRuleFilter- type: objectallOf:- type: object@@ -12898,6 +12922,7 @@ components:- $ref: '#/components/schemas/NumberEvaluationRuleFilter'required:- type+ title: NumberEvaluationRuleFilter- type: objectallOf:- type: object@@ -12909,6 +12934,7 @@ components:- $ref: '#/components/schemas/StringOptionsEvaluationRuleFilter'required:- type+ title: StringOptionsEvaluationRuleFilter- type: objectallOf:- type: object@@ -12920,6 +12946,7 @@ components:- $ref: '#/components/schemas/CategoryOptionsEvaluationRuleFilter'required:- type+ title: CategoryOptionsEvaluationRuleFilter- type: objectallOf:- type: object@@ -12931,6 +12958,7 @@ components:- $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter'required:- type+ title: ArrayOptionsEvaluationRuleFilter- type: objectallOf:- type: object@@ -12942,6 +12970,7 @@ components:- $ref: '#/components/schemas/StringObjectEvaluationRuleFilter'required:- type+ title: StringObjectEvaluationRuleFilter- type: objectallOf:- type: object@@ -12953,6 +12982,7 @@ components:- $ref: '#/components/schemas/NumberObjectEvaluationRuleFilter'required:- type+ title: NumberObjectEvaluationRuleFilter- type: objectallOf:- type: object@@ -12964,6 +12994,7 @@ components:- $ref: '#/components/schemas/BooleanEvaluationRuleFilter'required:- type+ title: BooleanEvaluationRuleFilter- type: objectallOf:- type: object@@ -12975,6 +13006,7 @@ components:- $ref: '#/components/schemas/NullEvaluationRuleFilter'required:- type+ title: NullEvaluationRuleFilterdescription: >-One filter condition used to decide whether a live-ingested observationshould be evaluated.@@ -13467,6 +13499,7 @@ components:title: EvaluatorChatPromptInputoneOf:- type: string+ title: String- $ref: '#/components/schemas/EvaluatorChatPrompt'description: >-A user prompt string, or a list containing exactly one user chat message.@@ -13582,6 +13615,7 @@ components:- $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'required:- type+ title: LlmAsJudgeEvaluatorVersion- type: objectallOf:- type: object@@ -13593,6 +13627,7 @@ components:- $ref: '#/components/schemas/CodeEvaluatorVersion'required:- type+ title: CodeEvaluatorVersionEvaluationRuleAssignment:title: EvaluationRuleAssignmenttype: object@@ -13778,6 +13813,7 @@ components:- $ref: '#/components/schemas/LlmAsJudgeEvaluator'required:- type+ title: LlmAsJudgeEvaluator- type: objectallOf:- type: object@@ -13789,6 +13825,7 @@ components:- $ref: '#/components/schemas/CodeEvaluator'required:- type+ title: CodeEvaluatordescription: >-One evaluator that can be used for scoring.@@ -13897,6 +13934,7 @@ components:- $ref: '#/components/schemas/CreateLlmAsJudgeEvaluatorRequest'required:- type+ title: CreateLlmAsJudgeEvaluatorRequest- type: objectallOf:- type: object@@ -13908,6 +13946,7 @@ components:- $ref: '#/components/schemas/CreateCodeEvaluatorRequest'required:- type+ title: CreateCodeEvaluatorRequestdescription: >-Initial evaluator definition with metadata and definition fields at thesame level. The returned evaluator starts at version `1`.@@ -14301,6 +14340,7 @@ components:- $ref: '#/components/schemas/TraceEvent'required:- type+ title: TraceEvent- type: objectallOf:- type: object@@ -14312,6 +14352,7 @@ components:- $ref: '#/components/schemas/ScoreEvent'required:- type+ title: ScoreEvent- type: objectallOf:- type: object@@ -14323,6 +14364,7 @@ components:- $ref: '#/components/schemas/CreateSpanEvent'required:- type+ title: CreateSpanEvent- type: objectallOf:- type: object@@ -14334,6 +14376,7 @@ components:- $ref: '#/components/schemas/UpdateSpanEvent'required:- type+ title: UpdateSpanEvent- type: objectallOf:- type: object@@ -14345,6 +14388,7 @@ components:- $ref: '#/components/schemas/CreateGenerationEvent'required:- type+ title: CreateGenerationEvent- type: objectallOf:- type: object@@ -14356,6 +14400,7 @@ components:- $ref: '#/components/schemas/UpdateGenerationEvent'required:- type+ title: UpdateGenerationEvent- type: objectallOf:- type: object@@ -14367,6 +14412,7 @@ components:- $ref: '#/components/schemas/CreateEventEvent'required:- type+ title: CreateEventEvent- type: objectallOf:- type: object@@ -14378,6 +14424,7 @@ components:- $ref: '#/components/schemas/SDKLogEvent'required:- type+ title: SDKLogEvent- type: objectallOf:- type: object@@ -14389,6 +14436,7 @@ components:- $ref: '#/components/schemas/CreateObservationEvent'required:- type+ title: CreateObservationEvent- type: objectallOf:- type: object@@ -14400,6 +14448,7 @@ components:- $ref: '#/components/schemas/UpdateObservationEvent'required:- type+ title: UpdateObservationEventObservationType:title: ObservationTypetype: string@@ -14976,6 +15025,7 @@ components:- type: objectadditionalProperties:type: integer+ title: Object- $ref: '#/components/schemas/OpenAICompletionUsageSchema'- $ref: '#/components/schemas/OpenAIResponseUsageSchema'legacyMetricsResponse:@@ -16072,6 +16122,7 @@ components:- $ref: '#/components/schemas/ChatPrompt'required:- type+ title: ChatPrompt- type: objectallOf:- type: object@@ -16083,6 +16134,7 @@ components:- $ref: '#/components/schemas/TextPrompt'required:- type+ title: TextPromptPromptType:title: PromptTypetype: string@@ -16649,6 +16701,7 @@ components:- $ref: '#/components/schemas/ScoreSubjectTraceV3'required:- kind+ title: ScoreSubjectTraceV3- type: objectallOf:- type: object@@ -16660,6 +16713,7 @@ components:- $ref: '#/components/schemas/ScoreSubjectObservationV3'required:- kind+ title: ScoreSubjectObservationV3- type: objectallOf:- type: object@@ -16671,6 +16725,7 @@ components:- $ref: '#/components/schemas/ScoreSubjectSessionV3'required:- kind+ title: ScoreSubjectSessionV3- type: objectallOf:- type: object@@ -16682,6 +16737,7 @@ components:- $ref: '#/components/schemas/ScoreSubjectExperimentV3'required:- kind+ title: ScoreSubjectExperimentV3description: >-A reference to the entity this score is attached to. Discriminated by"kind" — one of trace, observation, session, or experiment.@@ -16826,6 +16882,7 @@ components:- $ref: '#/components/schemas/NumericScoreV3'required:- dataType+ title: NumericScoreV3- type: objectallOf:- type: object@@ -16837,6 +16894,7 @@ components:- $ref: '#/components/schemas/BooleanScoreV3'required:- dataType+ title: BooleanScoreV3- type: objectallOf:- type: object@@ -16848,6 +16906,7 @@ components:- $ref: '#/components/schemas/CategoricalScoreV3'required:- dataType+ title: CategoricalScoreV3- type: objectallOf:- type: object@@ -16859,6 +16918,7 @@ components:- $ref: '#/components/schemas/TextScoreV3'required:- dataType+ title: TextScoreV3- type: objectallOf:- type: object@@ -16870,6 +16930,7 @@ components:- $ref: '#/components/schemas/CorrectionScoreV3'required:- dataType+ title: CorrectionScoreV3GetScoresV3Meta:title: GetScoresV3Metatype: object@@ -17071,6 +17132,7 @@ components:- $ref: '#/components/schemas/GetScoresResponseDataNumeric'required:- dataType+ title: GetScoresResponseDataNumeric- type: objectallOf:- type: object@@ -17082,6 +17144,7 @@ components:- $ref: '#/components/schemas/GetScoresResponseDataCategorical'required:- dataType+ title: GetScoresResponseDataCategorical- type: objectallOf:- type: object@@ -17093,6 +17156,7 @@ components:- $ref: '#/components/schemas/GetScoresResponseDataBoolean'required:- dataType+ title: GetScoresResponseDataBoolean- type: objectallOf:- type: object@@ -17104,6 +17168,7 @@ components:- $ref: '#/components/schemas/GetScoresResponseDataCorrection'required:- dataType+ title: GetScoresResponseDataCorrection- type: objectallOf:- type: object@@ -17115,6 +17180,7 @@ components:- $ref: '#/components/schemas/GetScoresResponseDataText'required:- dataType+ title: GetScoresResponseDataTextGetScoresResponse:title: GetScoresResponsetype: object@@ -17368,6 +17434,7 @@ components:#/components/schemas/unstablePublicNumericEvaluatorOutputDefinitionrequired:- dataType+ title: UnstablePublicNumericEvaluatorOutputDefinition- type: objectallOf:- type: object@@ -17380,6 +17447,7 @@ components:#/components/schemas/unstablePublicBooleanEvaluatorOutputDefinitionrequired:- dataType+ title: UnstablePublicBooleanEvaluatorOutputDefinition- type: objectallOf:- type: object@@ -17392,6 +17460,7 @@ components:#/components/schemas/unstablePublicCategoricalEvaluatorOutputDefinitionrequired:- dataType+ title: UnstablePublicCategoricalEvaluatorOutputDefinitiondescription: >-Structured output definition to send when creating an evaluator.@@ -17508,6 +17577,7 @@ components:#/components/schemas/unstablePublicNumericEvaluatorOutputDefinitionrequired:- dataType+ title: UnstablePublicNumericEvaluatorOutputDefinition- type: objectallOf:- type: object@@ -17520,6 +17590,7 @@ components:#/components/schemas/unstablePublicBooleanEvaluatorOutputDefinitionrequired:- dataType+ title: UnstablePublicBooleanEvaluatorOutputDefinition- type: objectallOf:- type: object@@ -17532,6 +17603,7 @@ components:#/components/schemas/unstablePublicCategoricalEvaluatorOutputDefinitionrequired:- dataType+ title: UnstablePublicCategoricalEvaluatorOutputDefinitiondescription: >-Evaluator output definition returned by the public API.@@ -17897,6 +17969,7 @@ components:- $ref: '#/components/schemas/unstableDateTimeEvaluationRuleFilter'required:- type+ title: UnstableDateTimeEvaluationRuleFilter- type: objectallOf:- type: object@@ -17908,6 +17981,7 @@ components:- $ref: '#/components/schemas/unstableStringEvaluationRuleFilter'required:- type+ title: UnstableStringEvaluationRuleFilter- type: objectallOf:- type: object@@ -17919,6 +17993,7 @@ components:- $ref: '#/components/schemas/unstableNumberEvaluationRuleFilter'required:- type+ title: UnstableNumberEvaluationRuleFilter- type: objectallOf:- type: object@@ -17930,6 +18005,7 @@ components:- $ref: '#/components/schemas/unstableStringOptionsEvaluationRuleFilter'required:- type+ title: UnstableStringOptionsEvaluationRuleFilter- type: objectallOf:- type: object@@ -17941,6 +18017,7 @@ components:- $ref: '#/components/schemas/unstableCategoryOptionsEvaluationRuleFilter'required:- type+ title: UnstableCategoryOptionsEvaluationRuleFilter- type: objectallOf:- type: object@@ -17952,6 +18029,7 @@ components:- $ref: '#/components/schemas/unstableArrayOptionsEvaluationRuleFilter'required:- type+ title: UnstableArrayOptionsEvaluationRuleFilter- type: objectallOf:- type: object@@ -17963,6 +18041,7 @@ components:- $ref: '#/components/schemas/unstableStringObjectEvaluationRuleFilter'required:- type+ title: UnstableStringObjectEvaluationRuleFilter- type: objectallOf:- type: object@@ -17974,6 +18053,7 @@ components:- $ref: '#/components/schemas/unstableNumberObjectEvaluationRuleFilter'required:- type+ title: UnstableNumberObjectEvaluationRuleFilter- type: objectallOf:- type: object@@ -17985,6 +18065,7 @@ components:- $ref: '#/components/schemas/unstableBooleanEvaluationRuleFilter'required:- type+ title: UnstableBooleanEvaluationRuleFilter- type: objectallOf:- type: object@@ -17996,6 +18077,7 @@ components:- $ref: '#/components/schemas/unstableNullEvaluationRuleFilter'required:- type+ title: UnstableNullEvaluationRuleFilterdescription: >-One filter condition used to decide whether a live-ingested targetshould be evaluated.@@ -18409,6 +18491,7 @@ components:- $ref: '#/components/schemas/unstableWidgetPlacement'required:- type+ title: UnstableWidgetPlacement- type: objectallOf:- type: object@@ -18420,6 +18503,7 @@ components:- $ref: '#/components/schemas/unstablePresetPlacement'required:- type+ title: UnstablePresetPlacementdescription: |-A tile on the dashboard's 12-column grid. `x`/`y` are the tile'stop-left cell (0-based; `y` grows downward), `width`/`height` its size@@ -18486,6 +18570,7 @@ components:- $ref: '#/components/schemas/unstableCreateWidgetPlacement'required:- type+ title: UnstableCreateWidgetPlacement- type: objectallOf:- type: object@@ -18497,6 +18582,7 @@ components:- $ref: '#/components/schemas/unstableCreatePresetPlacement'required:- type+ title: UnstableCreatePresetPlacementunstableCreateWidgetPlacement:title: unstableCreateWidgetPlacementtype: object@@ -19598,6 +19684,7 @@ components:- $ref: '#/components/schemas/unstableLlmAsJudgeEvaluator'required:- type+ title: UnstableLlmAsJudgeEvaluator- type: objectallOf:- type: object@@ -19609,6 +19696,7 @@ components:- $ref: '#/components/schemas/unstableCodeEvaluator'required:- type+ title: UnstableCodeEvaluatordescription: >-One evaluator that can be used for scoring.@@ -19776,6 +19864,7 @@ components:- $ref: '#/components/schemas/unstableCreateLlmAsJudgeEvaluatorRequest'required:- type+ title: UnstableCreateLlmAsJudgeEvaluatorRequest- type: objectallOf:- type: object@@ -19787,6 +19876,7 @@ components:- $ref: '#/components/schemas/unstableCreateCodeEvaluatorRequest'required:- type+ title: UnstableCreateCodeEvaluatorRequestdescription: >-Request body for creating an evaluator.diff --git a/web/scripts/openapi/sync-deprecations.ts b/web/scripts/openapi/postprocess-openapi.tssimilarity index 69%rename from web/scripts/openapi/sync-deprecations.tsrename to web/scripts/openapi/postprocess-openapi.tsindex ecf8b932be..f98a420b91 100644--- a/web/scripts/openapi/sync-deprecations.ts+++ b/web/scripts/openapi/postprocess-openapi.ts@@ -3,6 +3,7 @@ import path from "node:path";import { getFernDeprecatedOperations } from "./fern-deprecations";import { stampDeprecations } from "./stamp-deprecations";+import { stampUnionVariantTitles } from "./stamp-union-variant-titles";const webDirectory = process.cwd();const definitionDirectory = path.resolve(@@ -16,10 +17,13 @@ const openApiPath = path.resolve(const deprecatedOperations = getFernDeprecatedOperations(definitionDirectory);const openApiSource = fs.readFileSync(openApiPath, "utf8");-const syncedSource = stampDeprecations(openApiSource, deprecatedOperations);+const deprecatedSource = stampDeprecations(openApiSource, deprecatedOperations);+const { source: syncedSource, stamped } =+ stampUnionVariantTitles(deprecatedSource);if (syncedSource !== openApiSource) fs.writeFileSync(openApiPath, syncedSource);console.log(`Synced ${deprecatedOperations.length} deprecated OpenAPI operations from Fern definitions.`,);+console.log(`Titled ${stamped} anonymous OpenAPI union variants for Scalar.`);diff --git a/web/scripts/openapi/stamp-union-variant-titles.ts b/web/scripts/openapi/stamp-union-variant-titles.tsnew file mode 100644index 0000000000..1758ccc9b2--- /dev/null+++ b/web/scripts/openapi/stamp-union-variant-titles.ts@@ -0,0 +1,176 @@+import assert from "node:assert/strict";+import {+ isMap,+ isScalar,+ isSeq,+ parse,+ parseDocument,+ type Node,+ type Pair,+} from "yaml";++/** Fold width used by `fern export`. */+const LINE_WIDTH = 80;+const RESOLVE_OPTIONS = { maxAliasCount: -1 };+const UNION_KEYS = ["oneOf", "anyOf"] as const;++function scalarString(node: unknown): string | undefined {+ if (!isScalar(node)) return undefined;+ const value = node.value;+ return typeof value === "string" ? value : undefined;+}++function pairKey(pair: Pair): string | undefined {+ return scalarString(pair.key);+}++function refName(node: Node | null | undefined): string | undefined {+ if (!isMap(node)) return undefined;+ const ref = scalarString(node.get("$ref", true));+ return ref?.split("/").at(-1) ?? ref;+}++/** References that compose the variant itself, excluding refs in properties. */+function composingRefNames(variant: Node): string[] {+ if (!isMap(variant)) return [];++ const direct = refName(variant);+ if (direct) return [direct];++ const allOf = variant.get("allOf", true);+ if (!isSeq(allOf)) return [];++ return allOf.items+ .map((item) => refName(item as Node))+ .filter((name): name is string => Boolean(name));+}++function pascalCase(value: string): string {+ return value+ .split(/[^A-Za-z0-9]+/)+ .filter(Boolean)+ .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)+ .join("");+}++function inferVariantName(+ variant: Node,+ schemas: Node | null | undefined,+): string | undefined {+ if (!isMap(variant)) return undefined;++ const title = scalarString(variant.get("title", true));+ if (title) return pascalCase(title);++ const uniqueRefs = [...new Set(composingRefNames(variant))];+ if (uniqueRefs.length > 1) return undefined;++ const refName = uniqueRefs[0];+ if (refName) {+ const referencedSchema = isMap(schemas)+ ? schemas.get(refName, true)+ : undefined;+ if (isMap(referencedSchema)) {+ const referencedTitle = scalarString(referencedSchema.get("title", true));+ if (referencedTitle) return pascalCase(referencedTitle);+ }+ return refName;+ }++ const type = scalarString(variant.get("type", true));+ if (!type) return undefined;++ const format = scalarString(variant.get("format", true));+ return pascalCase(format ? `${format}-${type}` : type);+}++function stampNode(+ node: Node | null | undefined,+ path: string,+ schemas: Node | null | undefined,+): number {+ let stamped = 0;++ if (isMap(node)) {+ for (const unionKey of UNION_KEYS) {+ const union = node.get(unionKey, true);+ if (!isSeq(union)) continue;++ const names = union.items.map((variant, index) => {+ const name = inferVariantName(variant as Node, schemas);+ if (!name) {+ throw new Error(+ `Cannot infer OpenAPI variant title for ${path}.${unionKey}[${index}]`,+ );+ }+ return name;+ });++ const duplicate = names.find(+ (name, index) => names.indexOf(name) !== index,+ );+ if (duplicate) {+ throw new Error(+ `Duplicate OpenAPI variant title ${duplicate} in ${path}.${unionKey}`,+ );+ }++ union.items.forEach((variant, index) => {+ if (!isMap(variant)) {+ throw new Error(+ `Cannot stamp non-object union variant ${path}.${unionKey}[${index}]`,+ );+ }+ const hasNaturalName =+ scalarString(variant.get("title", true)) || refName(variant);+ if (!hasNaturalName) {+ variant.set("title", names[index]);+ stamped += 1;+ }+ });+ }++ for (const pair of node.items) {+ const key = pairKey(pair) ?? "?";+ stamped += stampNode(pair.value as Node, `${path}.${key}`, schemas);+ }+ } else if (isSeq(node)) {+ node.items.forEach((item, index) => {+ stamped += stampNode(item as Node, `${path}[${index}]`, schemas);+ });+ }++ return stamped;+}++/**+ * Gives every OpenAPI `oneOf` / `anyOf` branch a stable display title.+ *+ * Fern emits anonymous wrapper objects for discriminated unions. Scalar then+ * falls back to the parent schema title, making every option look identical in+ * the API reference. Name anonymous wrappers from their composing schema and+ * anonymous primitives from their format/type. Direct refs and existing titles+ * already have a stable name and stay untouched.+ */+export function stampUnionVariantTitles(source: string): {+ source: string;+ stamped: number;+} {+ const document = parseDocument(source);+ if (document.errors.length > 0) {+ throw new Error(document.errors.map((error) => error.message).join("\n"));+ }++ const schemas = document.getIn(["components", "schemas"], true) as+ | Node+ | null+ | undefined;+ const stamped = stampNode(document.contents, "$", schemas);+ const expected = document.toJS(RESOLVE_OPTIONS) as unknown;+ const text = document.toString({ lineWidth: LINE_WIDTH });+ const after = parse(text, RESOLVE_OPTIONS) as unknown;++ assert.deepStrictEqual(after, expected);++ return { source: text, stamped };+}diff --git a/web/src/__tests__/server/unit/openapi-union-variant-titles.servertest.ts b/web/src/__tests__/server/unit/openapi-union-variant-titles.servertest.tsnew file mode 100644index 0000000000..0a51c0f8c7--- /dev/null+++ b/web/src/__tests__/server/unit/openapi-union-variant-titles.servertest.ts@@ -0,0 +1,163 @@+import fs from "node:fs";+import path from "node:path";+import { parse } from "yaml";++import { stampUnionVariantTitles } from "../../../../scripts/openapi/stamp-union-variant-titles";++type Schema = {+ oneOf?: Array<Record<string, unknown>>;+ anyOf?: Array<Record<string, unknown>>;+};+type OpenApiDocument = {+ components: { schemas: Record<string, Schema> };+};++const SPEC = `openapi: 3.0.1+components:+ schemas:+ LlmRequest:+ title: LLMJudgeRequest+ type: object+ CodeRequest:+ type: object+ CreateRequest:+ oneOf:+ - type: object+ allOf:+ - type: object+ properties:+ type:+ type: string+ enum: [llm_as_judge]+ - $ref: '#/components/schemas/LlmRequest'+ - type: object+ allOf:+ - type: object+ properties:+ type:+ type: string+ enum: [code]+ - $ref: '#/components/schemas/CodeRequest'+ DirectRequest:+ oneOf:+ - $ref: '#/components/schemas/LlmRequest'+ - $ref: '#/components/schemas/CodeRequest'+ Value:+ oneOf:+ - type: number+ format: double+ - type: string+`;++function parseSpec(source: string): OpenApiDocument {+ return parse(source, { maxAliasCount: -1 }) as OpenApiDocument;+}++function titles(source: string, schema: string): unknown[] {+ return (+ parseSpec(source).components.schemas[schema].oneOf?.map(+ (variant) => variant.title,+ ) ?? []+ );+}++function expectAllUnionVariantsNamed(value: unknown, path = "$"): void {+ if (Array.isArray(value)) {+ value.forEach((item, index) =>+ expectAllUnionVariantsNamed(item, `${path}[${index}]`),+ );+ return;+ }+ if (!value || typeof value !== "object") return;++ const record = value as Record<string, unknown>;+ for (const unionKey of ["oneOf", "anyOf"] as const) {+ const union = record[unionKey];+ if (!Array.isArray(union)) continue;++ union.forEach((variant, index) => {+ const branch = variant as Record<string, unknown>;+ const name = branch.title ?? branch.$ref;+ expect(name, `${path}.${unionKey}[${index}]`).toEqual(expect.any(String));+ });+ }++ for (const [key, child] of Object.entries(record)) {+ expectAllUnionVariantsNamed(child, `${path}.${key}`);+ }+}++describe("OpenAPI union variant titles", () => {+ it("gives every union variant in the generated public spec a resolvable name", () => {+ const openApiPath = path.resolve(+ process.cwd(),+ "public/generated/api/openapi.yml",+ );+ const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));++ expectAllUnionVariantsNamed(openApi);+ });++ it("names Fern wrappers from referenced schema titles and names", () => {+ const result = stampUnionVariantTitles(SPEC);++ expect(titles(result.source, "CreateRequest")).toEqual([+ "LLMJudgeRequest",+ "CodeRequest",+ ]);+ expect(titles(result.source, "DirectRequest")).toEqual([+ undefined,+ undefined,+ ]);+ expect(result.stamped).toBe(4);+ });++ it("names primitive variants by format and type", () => {+ const result = stampUnionVariantTitles(SPEC);++ expect(titles(result.source, "Value")).toEqual(["DoubleNumber", "String"]);+ });++ it("is idempotent", () => {+ const first = stampUnionVariantTitles(SPEC);+ const second = stampUnionVariantTitles(first.source);++ expect(second.source).toBe(first.source);+ expect(second.stamped).toBe(0);+ });++ it("does not use nested property refs as the variant name", () => {+ const nestedPropertyRef = `openapi: 3.0.1+components:+ schemas:+ Payload:+ type: object+ Value:+ oneOf:+ - type: object+ properties:+ payload:+ $ref: '#/components/schemas/Payload'+ - type: string+`;++ const result = stampUnionVariantTitles(nestedPropertyRef);++ expect(titles(result.source, "Value")).toEqual(["Object", "String"]);+ });++ it("fails when inferred names are ambiguous", () => {+ const ambiguous = `openapi: 3.0.1+components:+ schemas:+ Value:+ oneOf:+ - type: string+ - type: string+`;++ expect(() => stampUnionVariantTitles(ambiguous)).toThrow(+ /Duplicate OpenAPI variant title String/,+ );+ });+});