fix(generator): compile 49 of 54 specs (was 43); broaden CI gold list

Continued chasing real-world spec failures through scripts/spec-compile.sh.
49 of 54 OpenAPI 3.x specs in specs/ now compile cleanly via cargo check
(gitea is Swagger 2.0, skipped). Up from 43 in #18.

## Bugs fixed (in order of how many specs they unblocked)

1. **Wrong fallback arm for typed-error enums.** When an op had only
   `default` (no specific 2xx) error responses, op_error_type emitted the
   typed enum but the codegen's "no typed enum" arm tried `typed = Some(v)`
   where v: serde_json::Value, mismatching the typed slot. Aligned the
   conditions in client_generator.rs:1206 so the default arm becomes
   `typed = None` whenever any non-2xx response exists.

2. **Indirect cycles via union wrappers.** stripe's
   BankAccount → BankAccountCustomer (enum) → Customer →
   BankAccountCustomer cycle wasn't direct self-reference, so my prior
   self-ref Box fix didn't catch it. generate_union_enum and
   generate_discriminated_enum now also Box variant payloads whose target
   is in analysis.dependencies.recursive_schemas. Closed stripe (17 errs
   → 0), microsoft-graph (5 → 0), lithic (1535 → 0).

3. **Reserved std type names.** cloudflare has a schema literally named
   `Result`; emitting `pub enum Result` shadows std::result::Result,
   breaking every `-> Result<T, ApiOpError<...>>`. Also gcore had a
   `Default` schema shadowing std::default::Default. to_rust_type_name
   now appends `Type` to a small reserved-name set (Result, Option, Box,
   Vec, String, Default, Clone, Debug, Send, Sync, Sized, Iterator, From,
   Into, TryFrom, TryInto, AsRef, AsMut, Some, None, Ok, Err).

4. **Rust 2024 keyword `gen`.** vercel had fields/types named `gen`.
   Added to is_rust_keyword.

5. **Default derive on enum with no variant matching default.** telnyx
   has `default: "en"` on a language enum with values like `en-US`,
   `en-AU`, … — no exact match. We were emitting `#[derive(Default)]`
   without `#[default]` on any variant, triggering E0665. Now we drop
   the Default derive when no variant matches.

6. **Sort-enum negative-prefix collisions.** telnyx and gcore use
   `["created_at", "-created_at", "ASC", "-ASC", …]` for sort orders.
   Both PascalCased to the same Rust variant, causing E0428 on the
   inline param enum. generate_single_param_enum now dedupes variant
   names with `_2`/`_3`/… suffixes.

7. **Per-method parameter ident collisions.** vercel's
   `exclude_ids` + `exclude-ids`, modern-treasury's duplicate `name`,
   twilio's `StartTime`/`StartTime>` produced E0382 (use of moved value)
   and E0415 (binding declared twice) in generated bodies. Added
   `ParameterInfo.rust_ident` populated by the analyzer at operation
   scope; client_generator.rs consults it everywhere instead of
   sanitizing param.name independently per call site.

8. **Case-sensitive operationId collision detection.** telnyx had two
   ops with operationIds `getMdrUsageReports` and `GetMdrUsageReports`.
   These didn't collide string-wise but PascalCased to the same Rust
   ident, producing two `GetMdrUsageReportsApiError` enum definitions
   (E0428). T6's collision check now compares PascalCased forms.

9. **Non-string scalars in `enum`.** gitpod has
   `type: string, enum: [2000, 5000, 10000, ...]` — numeric values on a
   string-typed schema. string_enum_values used to filter to .as_str()
   only, producing an empty Vec → empty enum (E0665, E0004). Now
   coerces non-string scalars via Display.

10. **Unresolvable $refs.** pagerduty uses
    `#/components/parameters/foo/schema` (last segment `schema` isn't
    a type name). google-tasks uses Swagger 2.0 carry-over
    `#/definitions/Foo`. extract_schema_name now (a) recognises
    `#/definitions/{X}` as an alias for `#/components/schemas/{X}`,
    (b) tightens the last-segment fallback to require PascalCase and
    skip JSON Schema sub-path keywords, and (c) when a ref still
    can't be resolved, falls back to serde_json::Value with a stderr
    warning instead of failing whole-document analysis.

11. **Nullable-anyOf wrapper collisions with the inner $ref.**
    `Step.status: anyOf [$ref StepStatus, null]` synthesized a
    wrapper named `StepStatus` that overwrote the actual top-level
    schema. Detect `is_nullable_pattern` in property analysis and
    unwrap to the inner type. When a wrapper IS needed, suffix
    collisions with `Union2`/`Union3`.

12. **Type-name dedup at emission.** Defensive layer: if two
    analyzed schemas PascalCase to the same Rust ident, the first
    occurrence wins and later ones are silently dropped (catches
    cases where analysis missed the collision).

## CI

The spec-compile job now exercises 49 specs, up from 43:
  + gcore lithic microsoft-graph stripe telnyx vercel

## Quality follow-ups tracked in `bd` (`.beads/issues.jsonl`)

- Q1 Method-name canonicalization
- Q2 Format-typed scalars (date-time, uuid, byte, binary, ipv*, uri)
- Q3 Builder pattern for ops with many parameters (depends on Q1)
- Q4 Tagged discriminator enums
- Q5 Display for ApiOpError that surfaces the typed body

All 205 unit tests still pass; clippy + fmt clean.

Refs #14

Author: lightsofapollo

.beads/issues.jsonl

@@ -0,0 +1,5 @@
+{"id":"openapi-generator-8tu","title":"[Q4] Tagged discriminator enums (drop untagged when discriminator+mapping is present)","description":"When a schema has discriminator: { propertyName: 'type', mapping: { ... } }, we know exactly which type to deserialize at runtime by reading one field. Yet today we still emit #[serde(untagged)] on the union enum, which makes serde try every variant in order on every deserialization (slow) and emits the variant payload's JSON inline instead of a tagged shape on serialization (loses the discriminator on round-trip). Anthropic's content blocks (text/image/tool_use/tool_result) and OpenAI's response items are exactly this pattern. Tagged is much better. Approach: in generate_discriminated_enum, when the spec provides discriminator with mapping, emit #[serde(tag = '\u003cdiscriminator.property_name\u003e')] and rename each variant to the mapping value. For unions WITHOUT a discriminator, untagged remains.\n\n## Context\nFiles: src/generator.rs. Evidence: src/generator.rs:1107 generate_discriminated_enum and 1251 generate_union_enum both emit #[serde(untagged)] regardless of discriminator presence. See umbrella gpu-cli/openapi-to-rust#14.","acceptance_criteria":"- [ ] Discriminator + mapping → #[serde(tag = ...)] enum, not untagged.\n- [ ] Round-trip test: deserialize a JSON sample, serialize back, byte-equal modulo whitespace.\n- [ ] Variants ordered to match mapping insertion order (deterministic codegen).\n- [ ] Pet/Cat/Dog allOf-parent pattern (umbrella H12) supported.\n- [ ] All 49 currently-compiling specs still compile.","status":"open","priority":2,"issue_type":"task","owner":"james@littlebearlabs.io","created_at":"2026-05-08T23:13:12Z","created_by":"James Lal","updated_at":"2026-05-08T23:13:12Z","labels":["phase4","quality","schema"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"openapi-generator-st8","title":"[Q3] Builder pattern for operations with many parameters","description":"OpenAI's responses_create has 25+ parameters. Even with Option\u003cT\u003e for optionals, the call site is hostile: client.responses_create(model, None, None, ..., Some('system prompt'), None, ...). Goal: emit a \u003cOp\u003eBuilder\u003c'_\u003e per op with .field(value) setters and a final .send().await. Required path/header params remain positional on the entry method; optional + body fields become builder setters. For struct-typed bodies, also generate per-field setters on the builder (delegating into the body struct).\n\n## Context\nFiles: src/client_generator.rs. Evidence: src/client_generator.rs:836 generate_request_param emits flat positional method args. See umbrella gpu-cli/openapi-to-rust#14.","acceptance_criteria":"- [ ] [generator.builders] enabled = true; threshold = 3 in TOML config.\n- [ ] Each operation with \u003ethreshold optional params gets a builder struct.\n- [ ] Required params stay positional on the entry method.\n- [ ] .send(self) -\u003e Result\u003c\u003cResponseT\u003e, ApiOpError\u003c...\u003e\u003e runs the existing emitted body.\n- [ ] Snapshot tests for an op with many optional params show the new shape compiles and the existing call compiles.\n- [ ] All 49 currently-compiling specs still compile.","status":"open","priority":2,"issue_type":"task","owner":"james@littlebearlabs.io","created_at":"2026-05-08T23:11:55Z","created_by":"James Lal","updated_at":"2026-05-08T23:11:55Z","labels":["codegen","phase4","quality"],"dependency_count":0,"dependent_count":1,"comment_count":0}
+{"id":"openapi-generator-quq","title":"[Q2] Format-typed scalars (date-time, uuid, byte, binary, ipv4, ipv6, uri)","description":"Real-world specs use 'format' tags everywhere. Today everything collapses to String/Vec\u003cu8\u003e. Add typed scalars: date-time → chrono::DateTime\u003cUtc\u003e; date → chrono::NaiveDate; time → chrono::NaiveTime; duration → chrono::Duration; uuid → uuid::Uuid; byte → Vec\u003cu8\u003e + base64 serde; binary → bytes::Bytes; ipv4/ipv6 → std::net::Ipv*Addr; uri/url → url::Url. Configurable via [generator.types] TOML section with per-format choices (chrono vs time vs string, bytes vs vec_u8, etc.). Default: 'string' (current behavior, opt-in).\n\n## Context\nFiles: Cargo.toml, src/analysis.rs, src/generator.rs, scripts/spec-compile.sh. Evidence: src/analysis.rs:3091 get_number_rust_type only handles int32/int64/float/double; string format never produces typed scalars. See umbrella gpu-cli/openapi-to-rust#14.","acceptance_criteria":"- [ ] All formats above accept a TOML override.\n- [ ] Default ('string') matches today's behavior — no spec regresses.\n- [ ] When chrono is selected, generated structs use chrono::serde::rfc3339 for format: date-time.\n- [ ] When uuid is selected, generated structs use uuid::Uuid (with serde feature).\n- [ ] byte round-trips via base64 (matches OAS spec).\n- [ ] One end-to-end fixture per format under tests/conformance/fixtures/schema/format-*.yaml proving the types deserialize a real example.\n- [ ] Generated crate's Cargo.toml gets the right feature-gated deps.","status":"open","priority":2,"issue_type":"task","owner":"james@littlebearlabs.io","created_at":"2026-05-08T23:11:40Z","created_by":"James Lal","updated_at":"2026-05-08T23:11:40Z","labels":["phase4","quality","schema"],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"id":"openapi-generator-99a","title":"[Q1] Method-name canonicalization","description":"Heuristic post-processor on snake-cased operationId: tokenize path template, drop trailing tokens that match path tokens (in reverse path order), drop trailing HTTP-method verb. Re-check uniqueness; restore tokens for collisions. Goal: Anthropic's betaGetFileMetadataV1FilesFileIdGet + path /v1/files/{fileId} + GET → get_file_metadata.\n\n## Context\nToday get_method_name emits op.operation_id.to_snake_case() verbatim. Anthropic's spec produces names like beta_get_file_metadata_v1_files_file_id_get — the path and HTTP method are literally appended into the operationId. See umbrella issue gpu-cli/openapi-to-rust#14.","acceptance_criteria":"- [ ] Heuristic implemented in src/client_generator.rs:get_method_name (line ~859).\n- [ ] Unique across operation set; collisions fall back to original.\n- [ ] CLI/config flag [generator.method_names] strip_path = true (default true).\n- [ ] Snapshot tests confirm anthropic produces get_file_metadata not beta_get_file_metadata_v1_files_file_id_get.\n- [ ] All 49 currently-compiling specs still compile.","status":"open","priority":2,"issue_type":"task","owner":"james@littlebearlabs.io","created_at":"2026-05-08T23:10:47Z","created_by":"James Lal","updated_at":"2026-05-08T23:10:47Z","labels":["codegen","phase4","quality"],"dependencies":[{"issue_id":"openapi-generator-99a","depends_on_id":"openapi-generator-st8","type":"blocks","created_at":"2026-05-08T17:11:55Z","created_by":"James Lal","metadata":"{}"}],"dependency_count":1,"dependent_count":0,"comment_count":0}
+{"id":"openapi-generator-81u","title":"[Q5] Display for ApiOpError that surfaces the typed body","description":"Today format!('{e}', e: ApiOpError\u003cE\u003e) on an Api variant prints 'API error 404: {full body}'. For a Stripe error that includes a huge param_documentation blob, the message becomes a wall of JSON. Users complain they can't tell at a glance what the typed variant captured. Approach: in ApiError::Display, truncate body to ~500 chars with a '… (truncated)' marker; if typed.is_some(), prepend '(typed: \u003cvariant_name\u003e)' (E: fmt::Debug bound already exists); if parse_error.is_some() and typed.is_none(), append '(parse error: …)'. Full body still accessible via .body field.\n\n## Context\nFiles: src/http_error.rs. Evidence: src/http_error.rs:234 ApiError Display prints body verbatim — for huge JSON bodies this is unreadable; typed.is_some() info is hidden. See umbrella gpu-cli/openapi-to-rust#14.","acceptance_criteria":"- [ ] ApiError Display truncates body at 500 chars (configurable via const).\n- [ ] Typed variant name appears when typed.is_some().\n- [ ] Parse error reason appears when typed parsing failed.\n- [ ] Full body still accessible via .body — no info loss.\n- [ ] Unit test in src/http_error.rs covers all three branches.","status":"open","priority":3,"issue_type":"task","owner":"james@littlebearlabs.io","created_at":"2026-05-08T23:13:13Z","created_by":"James Lal","updated_at":"2026-05-08T23:13:13Z","labels":["codegen","phase4","quality"],"dependency_count":0,"dependent_count":0,"comment_count":0}

.github/workflows/ci.yml

@@ -65,9 +65,9 @@ jobs:
       - run: |
           scripts/spec-compile.sh \
             anthropic arcade asana box browserbase cartesia cerebras circleci \
-            coda coingecko datadog-v2 digitalocean github gitpod \
+            coda coingecko datadog-v2 digitalocean gcore github gitpod \
             google-calendar google-drive google-gmail google-tasks google-youtube \
-            grafana groq imagekit increase launchdarkly letta luma meta-llama \
-            modern-treasury openai pagerduty perplexity resend retell runway \
-            sentry snyk spotify supabase terminal-shop together twilio val-town \
-            writer
+            grafana groq imagekit increase launchdarkly letta lithic luma \
+            meta-llama microsoft-graph modern-treasury openai pagerduty \
+            perplexity resend retell runway sentry snyk spotify stripe \
+            supabase telnyx terminal-shop together twilio val-town vercel writer

src/analysis.rs

@@ -3686,11 +3686,26 @@ impl SchemaAnalyzer {
             // be unique, but real-world specs (arcade, cal-com, telnyx,
             // val-town, …) frequently aren't. Auto-disambiguate by suffixing
             // with the method, then a counter, and warn.
-            let operation_id = if analysis.operations.contains_key(&raw_operation_id) {
+            //
+            // The collision key is the PascalCased form so that case-only
+            // differences (telnyx has `getMdrUsageReports` AND
+            // `GetMdrUsageReports`) collide too — otherwise codegen would
+            // produce two `GetMdrUsageReportsApiError` enums in the same
+            // module.
+            use heck::ToPascalCase;
+            let canon = |s: &str| s.replace('.', "_").to_pascal_case();
+            let key_collides = |id: &str| -> bool {
+                let target = canon(id);
+                analysis
+                    .operations
+                    .keys()
+                    .any(|existing| canon(existing) == target)
+            };
+            let operation_id = if key_collides(&raw_operation_id) {
                 let method_lower = method.to_lowercase();
                 let mut candidate = format!("{}_{}", raw_operation_id, method_lower);
                 let mut suffix = 2;
-                while analysis.operations.contains_key(&candidate) {
+                while key_collides(&candidate) {
                     candidate = format!("{}_{}_{}", raw_operation_id, method_lower, suffix);
                     suffix += 1;
                 }

src/generator.rs

@@ -638,7 +638,7 @@ impl CodeGenerator {
                             nullable: false,
                         })
                         .collect();
-                    self.generate_union_enum(schema, &schema_refs)
+                    self.generate_union_enum(schema, &schema_refs, analysis)
                 } else {
                     self.generate_discriminated_enum(
                         schema,
@@ -648,7 +648,7 @@ impl CodeGenerator {
                     )
                 }
             }
-            SchemaType::Union { variants } => self.generate_union_enum(schema, variants),
+            SchemaType::Union { variants } => self.generate_union_enum(schema, variants, analysis),
             SchemaType::Reference { target } => {
                 // For references, check if we need to generate a type alias
                 // This handles cases like nullable patterns
@@ -868,12 +868,21 @@ impl CodeGenerator {
     ) -> Result<TokenStream> {
         let enum_name = format_ident!("{}", self.to_rust_type_name(&schema.name));
 
-        // Determine which variant should be the default
+        // Determine which variant should be the default. The spec's `default`
+        // may not exactly match any enum value (telnyx has
+        // `default: "en"` on a language enum that lists `en-US`, `en-AU`,
+        // … — no exact match). When that happens, drop the `Default` derive
+        // entirely instead of emitting it on an enum where no variant has
+        // `#[default]` (E0665).
         let default_value = schema
             .default
             .as_ref()
             .and_then(|v| v.as_str())
             .map(|s| s.to_string());
+        let has_default_match = match &default_value {
+            Some(d) => values.iter().any(|v| v == d),
+            None => !values.is_empty(),
+        };
 
         // Variant-name uniqueness: enum values that PascalCase to the same
         // identifier (e.g. `ASC`/`asc` both → `Asc`) collide and produce
@@ -933,16 +942,23 @@ impl CodeGenerator {
             TokenStream::new()
         };
 
-        // Generate derives with optional Specta support
-        let derives = if self.config.enable_specta {
-            quote! {
+        // Generate derives with optional Specta support. Drop `Default` if
+        // no variant ends up tagged `#[default]` (would trigger E0665).
+        let derives = match (self.config.enable_specta, has_default_match) {
+            (true, true) => quote! {
                 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, Default)]
                 #[cfg_attr(feature = "specta", derive(specta::Type))]
-            }
-        } else {
-            quote! {
+            },
+            (true, false) => quote! {
+                #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+                #[cfg_attr(feature = "specta", derive(specta::Type))]
+            },
+            (false, true) => quote! {
                 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, Default)]
-            }
+            },
+            (false, false) => quote! {
+                #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+            },
         };
 
         Ok(quote! {
@@ -1119,19 +1135,31 @@ impl CodeGenerator {
                     nullable: false,
                 })
                 .collect();
-            return self.generate_union_enum(schema, &schema_refs);
+            return self.generate_union_enum(schema, &schema_refs, analysis);
         }
 
+        let enclosing = self.to_rust_type_name(&schema.name);
         let enum_variants = variants.iter().map(|variant| {
             let variant_name = format_ident!("{}", variant.rust_name);
             let variant_value = &variant.discriminator_value;
 
-            // Always use tuple variant that references the existing type
-            // This ensures the standalone event types are actually used
             let variant_type = format_ident!("{}", self.to_rust_type_name(&variant.type_name));
+            // Box variant payloads that point at the enclosing enum or any
+            // schema in the analysis's recursive set, otherwise the enum has
+            // infinite size (E0072).
+            let payload = if self.to_rust_type_name(&variant.type_name) == enclosing
+                || analysis
+                    .dependencies
+                    .recursive_schemas
+                    .contains(&variant.type_name)
+            {
+                quote! { Box<#variant_type> }
+            } else {
+                quote! { #variant_type }
+            };
             quote! {
                 #[serde(rename = #variant_value)]
-                #variant_name(#variant_type),
+                #variant_name(#payload),
             }
         });
 
@@ -1224,6 +1252,7 @@ impl CodeGenerator {
         &self,
         schema: &crate::analysis::AnalyzedSchema,
         variants: &[crate::analysis::SchemaRef],
+        analysis: &crate::analysis::SchemaAnalysis,
     ) -> Result<TokenStream> {
         let enum_name = format_ident!("{}", self.to_rust_type_name(&schema.name));
 
@@ -1332,7 +1361,15 @@ impl CodeGenerator {
             // break the cycle. Observed in microsoft-graph.yaml.
             let target_rust_name = self.to_rust_type_name(&variant.target);
             let enclosing_name = self.to_rust_type_name(&schema.name);
-            let variant_type_tokens = if target_rust_name == enclosing_name {
+            let is_self_ref = target_rust_name == enclosing_name;
+            // Indirect cycles (stripe BankAccount → BankAccountCustomer →
+            // Customer → BankAccountCustomer): variants pointing into the
+            // analysis's recursive_schemas set must also be heap-allocated.
+            let is_recursive_target = analysis
+                .dependencies
+                .recursive_schemas
+                .contains(&variant.target);
+            let variant_type_tokens = if is_self_ref || is_recursive_target {
                 quote! { Box<#variant_type_tokens> }
             } else {
                 variant_type_tokens
@@ -1803,6 +1840,40 @@ impl CodeGenerator {
             result = format!("Type{result}");
         }
 
+        // Avoid masking ubiquitous std types and traits. cloudflare has a
+        // schema literally named `Result`, gcore has `Default`; emitting
+        // `pub enum Result { ... }` shadows std::result::Result and breaks
+        // every method's `-> Result<T, ApiOpError<...>>`. Same for impls
+        // like `impl Default for HttpClient { ... }` when `Default` resolves
+        // to the local type alias.
+        if matches!(
+            result.as_str(),
+            "Result"
+                | "Option"
+                | "Box"
+                | "Vec"
+                | "String"
+                | "Some"
+                | "None"
+                | "Ok"
+                | "Err"
+                | "Default"
+                | "Clone"
+                | "Debug"
+                | "Send"
+                | "Sync"
+                | "Sized"
+                | "Iterator"
+                | "From"
+                | "Into"
+                | "TryFrom"
+                | "TryInto"
+                | "AsRef"
+                | "AsMut"
+        ) {
+            result.push_str("Type");
+        }
+
         result
     }
 
@@ -1931,6 +2002,8 @@ impl CodeGenerator {
                 | "unsized"
                 | "virtual"
                 | "yield"
+                // Rust 2024 edition reservations.
+                | "gen"
         )
     }