feat(fixer): repair path parameters missing required: true

[erraggy]

Fixes #381.

#378 added the OAS 2.0 required: true check for path parameters and made the defect visible in both validators. It did not make it fixable — there was no corresponding FixType, and oastools fix left every one of those errors behind.

The fix

FixTypePathParameterNotRequired ("path-parameter-not-required") sets required: true on any in: path parameter that omits it. The spec permits no other value, so there is no judgment call, nothing to configure, and no information to lose.

It runs at the three sites the validator reports the defect, with paths that match the validator's exactly:

Site	Reported path
OAS 2.0 root-level parameters	parameters.{name}

Both constraints carried over from #378 hold: parameters that are a $ref are skipped so the definition they name is repaired once instead of at every use site, and the path-item pass runs once per path item rather than inside the per-operation loop.

Keeping the validator and fixer aligned

Rather than duplicate the traversal, the defect test moved to paramutil.NeedsRequiredTrue and both packages now call it. That collapsed four copies of the condition into one and fixed a latent inconsistency along the way: validator/oas3.go compared against a bare "path" literal while oas2.go used parser.ParamInPath.

TestFixPathParamsRequired_ResolvesValidatorErrors is the guard: it validates a defective spec, asserts the error is reported, fixes, re-validates, and asserts no required: true error survives — for both OAS versions, including through $ref use sites. If the two sides ever drift, this fails.

Enabled by default

The issue's complaint was that oastools fix could not repair this, so leaving the fix opt-in would have needed a new flag to actually resolve it. It joins FixTypeMissingPathParameter in the always-on set via a new exported fixer.DefaultEnabledFixes(), which the CLI and MCP server now call instead of each hardcoding their own copy of the list.

Corpus impact is nil: DigitalOcean, Asana, Plaid, and GitHub each produce 0 fixes with unchanged validation error counts; none of them exhibit this defect.

Notes

• Honors DryRun (records the fix, leaves the document alone), which FixTypeMissingPathParameter currently does not.
• webhooks path items are untouched, matching the validator, which does not check them for this rule either.
• Docs updated: package docs, fixer/deep_dive.md, CLI --help and cli-reference.md, MCP tool description and mcp-server.md, whitepaper.

Verified with make check (green: lint + 8861 tests) and gopls diagnostics (clean), plus an end-to-end CLI round trip in both versions: validate reports the errors, fix repairs them, validate then passes.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a default-enabled fixer for existing OpenAPI path parameters missing required: true, shared requiredness detection across validators, OAS 2.0/3.x repair logic, CLI/MCP wiring, integration aliases, and documentation.

Changes

Path parameter requiredness

Layer / File(s)	Summary
Shared requiredness predicate and validation internal/paramutil/*, validator/*	Centralizes detection of non-reference path parameters missing required: true and applies it across OAS 2.0 and OAS 3.x validation.
Fix type defaults and pipeline wiring fixer/fixer.go, fixer/pipeline.go, fixer/fixer_test.go, fixer/*_test.go	Adds FixTypePathParameterNotRequired, exposes fresh default fixes, and wires version-specific repair passes after missing path-parameter fixes.
OAS path parameter repair and tests fixer/pathparam_required.go, fixer/pathparam_required_test.go	Repairs reusable, path-item, and operation parameters across OAS versions, with dry-run, reference, ordering, nil-safety, and validator-parity coverage.
Command, MCP, integration, and documentation updates cmd/oastools/commands/fix.go, internal/mcpserver/*, integration/harness/*, docs/*, fixer/*.md, fixer/doc.go	Uses the expanded default fix set in CLI and MCP flows, adds configuration aliases, and documents the new fix behavior and scope.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OpenAPI document
  participant Validator
  participant Fixer
  Validator->>OpenAPI document: Report path parameters missing required true
  Fixer->>OpenAPI document: Set required true on repairable parameters
  Fixer-->>Validator: Revalidate the updated document

Loading

Possibly related PRs

• erraggy/oastools#382: Modifies the same path-parameter validation logic and $ref handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR satisfies #381 by adding the fix type, covering all required OAS locations, skipping $ref, and reusing validator logic.
Out of Scope Changes check	✅ Passed	The extra docs, tests, CLI/MCP updates, and validator/paramutil changes all support the requested fixer and stay in scope.
Docstring Coverage	✅ Passed	Docstring coverage is 92.00% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: fixing path parameters missing required:true.
Description check	✅ Passed	The description directly explains the path-parameter fixer, its scope, default behavior, and related validation changes.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/381-path-param-required-fixtype

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 97.53086% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.05%. Comparing base (4655686) to head (b3fac56).

Files with missing lines	Patch %	Lines
fixer/pathparam_required.go	96.77%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #390      +/-   ##
==========================================
+ Coverage   85.02%   85.05%   +0.03%     
==========================================
  Files         194      196       +2     
  Lines       27666    27739      +73     
==========================================
+ Hits        23522    23593      +71     
- Misses       2812     2813       +1     
- Partials     1332     1333       +1     

Files with missing lines	Coverage Δ
fixer/fixer.go	91.42% <100.00%> (+0.09%)	⬆️
fixer/pipeline.go	97.53% <100.00%> (+0.27%)	⬆️
internal/mcpserver/server.go	91.85% <100.00%> (ø)
internal/mcpserver/tools_fix.go	79.71% <100.00%> (-0.29%)	⬇️
internal/paramutil/pathparam.go	100.00% <100.00%> (ø)
validator/oas2.go	89.76% <100.00%> (ø)
validator/oas3.go	86.33% <100.00%> (ø)
validator/path_validation.go	96.72% <100.00%> (ø)
fixer/pathparam_required.go	96.77% <96.77%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.