fix(openapi): sanitize null security scopes to empty arrays in OpenAPI importers

[devin-ai-integration]

Description

Fix "Expected list. Received null." error when importing OpenAPI specs with null security scopes. Some real-world specs use {oauth2: null} instead of {oauth2: []} in security requirement objects, which causes all generators to crash during IR serialization.

Root cause: PR #9546 (Sept 2025) added the security field to the IR but the importers pass operation.security straight through without sanitizing null scope values. The Zurg list(AuthScope) validator rejects null at generation time.

Real-world evidence:

• Real-world API specs (including those used in benchmarks) have security: [{oauth2: null}] on endpoints that don't require specific scopes — this crashes all generators on main
• Scalar (14K-star OpenAPI tooling project): Hit the exact same bug and fixed it identically (value ?? []) in March 2025

Changes Made

• Added sanitizeSecurityScopes() utility with concrete Record<string, string[]> return type (no unnecessary generics/casts):
  • Shared via @fern-api/v3-importer-commons for the 3.1 importer (OperationConverter.ts)
  • Local utils/sanitizeSecurityScopes.ts in openapi-ir-parser for v3 importers (convertHttpOperation.ts, generateIr.ts) — separate copy required due to circular dependency constraint (openapi-ir-parser → v3-importer-commons → api-workspace-commons → openapi-ir-parser). The copy includes a cross-reference comment pointing to the canonical version and its tests.
• The as Record<string, string[]>[] cast is documented as safe since OpenAPI scopes are always string[] | null
• Unit tests live in v3-importer-commons alongside the canonical utility
• Added fix-null-security-scopes.yml unreleased changelog entry

Testing

• Unit tests added — 7 focused tests for sanitizeSecurityScopes covering: undefined/null input, valid scopes passthrough, null→[] sanitization, mixed null/valid scopes, multiple requirements, empty arrays
• All tests pass
• Manual testing completed — verified real-world API specs have {oauth2: null} on endpoints

Link to Devin session: https://app.devin.ai/sessions/f3bb4b99c28047a982ec031297681298

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against latest nightly baseline on main (2026-04-21T12:52:17Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	39s	46s	50s	+11s (+28.2%)
go-sdk	square	43s	53s	117s	+74s (+172.1%)
java-sdk	square	100s	109s	181s	+81s (+81.0%)
php-sdk	square	36s	41s	40s	+4s (+11.1%)
python-sdk	square	53s	64s	118s	+65s (+122.6%)
ruby-sdk-v2	square	65s	69s	126s	+61s (+93.8%)
rust-sdk	square	40s	37s	173s	+133s (+332.5%)
swift-sdk	square	33s	39s	43s	+10s (+30.3%)
ts-sdk	square	46s	52s	66s	+20s (+43.5%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-04-21T12:52:17Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-04-21 17:48 UTC

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against latest nightly baseline on main (2026-04-21T12:52:17Z).

Fixture	main	PR	Delta
docs	316.2s	317.3s (35 versions)	+1.1s (+0.3%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-04-21T12:52:17Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-04-21 17:49 UTC