Skip to content

fix: resolve $ref pointers in operation parameters#27

Merged
lucianfialho merged 1 commit into
mainfrom
fix/resolve-parameter-refs
May 22, 2026
Merged

fix: resolve $ref pointers in operation parameters#27
lucianfialho merged 1 commit into
mainfrom
fix/resolve-parameter-refs

Conversation

@lucianfialho
Copy link
Copy Markdown
Owner

Problem

Specs that declare parameters once in `components.parameters` and reference them via `$ref` from operations (Stripe, Slack, GitHub, Sympla, etc.) crash spec2cli with:

```
Error: Cannot add option '--undefined ' to command 'X' due to conflicting flag '--undefined'
```

The extractor was resolving `$ref` for schemas only — parameter `$ref` entries were treated as raw objects, leaving `name` and `in` undefined.

Fix

  • New `refs.ts` module exporting `resolveSchema` and `resolveParameter` (deduplicates the pointer-walking logic both already needed)
  • `extractParams` now calls `resolveParameter` before reading `name`/`in`, and skips entries that still lack these after resolution (defensive)
  • Split `extractor.ts` into focused modules (`refs`, `params`, `naming`) so each file stays under the 150-line gate

Test plan

  • All 123 existing tests pass
  • Sympla spec (which uses `$ref: '#/components/parameters/TokenUser'`) now loads — verified end-to-end with `--dry-run`
  • Petstore and other specs without parameter refs still work

🤖 Generated with Claude Code

OpenAPI 3.x specs commonly declare parameters once in
components.parameters and reference them via \$ref from operations
(Stripe, Slack, GitHub, Sympla, etc all do this). The extractor was
only resolving \$ref for schemas, treating ref-only parameter entries
as raw objects with undefined name/in fields. This produced
'Cannot add option --undefined <undefined>' crashes.

Added resolveParameter() in a new refs.ts module and a guard against
parameters missing name/in after resolution. As part of the change,
split extractor.ts into focused modules (refs, params, naming) to
keep each file under 150 lines.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@lucianfialho lucianfialho merged commit 78962a2 into main May 22, 2026
1 check passed
@lucianfialho lucianfialho deleted the fix/resolve-parameter-refs branch May 22, 2026 11:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant