chore: prepare v1.57.0 release

[erraggy]

Summary

• Pre-release preparation for v1.57.0
• Includes CI benchmark results

Checklist

• All tests pass
• Benchmarks recorded
• Documentation reviewed

---

🤖 Generated by prepare-release.sh

[coderabbitai]

📝 Walkthrough

Walkthrough

The change documents OpenAPI discriminator dialects, typed schema decoding, conversion and validation rules, and map reference tracking. It adds parser examples, updates plugin versions to 1.57.0, and records package benchmark results.

Changes

OpenAPI parsing and conversion documentation

Layer / File(s)	Summary
Parser semantics and examples parser/deep_dive.md, parser/doc.go, parser/example_test.go, CLAUDE.md	Documents discriminator string-form handling and schema field promotion, with examples covering discriminator marshaling and schema field types.
Dialect guidance and conversion rules .claude/docs/oas-concepts.md, CONTRIBUTORS.md, converter/deep_dive.md, validator/deep_dive.md	Updates version-specific discriminator guidance, conversion behavior, loss-of-fidelity notes, and validation documentation.
Map reference tracking guidance docs/developer-guide.md, walker/deep_dive.md, walker/example_test.go, walker/options.go	Clarifies when polymorphic schema fields retain map values and how map-based reference tracking applies.

Version 1.57.0 release artifacts

Layer / File(s)	Summary
Release version and benchmark records .claude-plugin/marketplace.json, plugin/.claude-plugin/plugin.json, benchmarks/benchmark-v1.57.0.txt	Sets both plugin manifests to version 1.57.0 and adds benchmark results for the Go packages.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• erraggy/oastools#386: Updates the same Claude manifests and adds a versioned benchmark artifact.
• erraggy/oastools#325: Performs a related plugin manifest version update.
• erraggy/oastools#361: Overlaps on Claude plugin manifest version fields.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: preparing the v1.57.0 release.
Description check	✅ Passed	The description matches the release-prep changes and mentions benchmarks and tests included in the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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 chore/v1.57.0-release-prep

---

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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.10%. Comparing base (b2be348) to head (00bb5fb).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #403   +/-   ##
=======================================
  Coverage   85.10%   85.10%           
=======================================
  Files         197      197           
  Lines       27904    27904           
=======================================
  Hits        23747    23747           
  Misses       2820     2820           
  Partials     1337     1337           

Files with missing lines	Coverage Δ
walker/options.go	85.71% <ø> (ø)

🚀 New features to boost your workflow:

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@benchmarks/benchmark-v1.57.0.txt`:
- Around line 1-364: Remove the generated benchmark artifact from the pull
request; do not modify or retain benchmarks/benchmark-v1.57.0.txt. Leave the
repository’s benchmarks directory unchanged unless the repository rule is
explicitly updated to permit this file.

In `@parser/example_test.go`:
- Around line 392-395: Update the documentation comment for ExampleSchema_items
to state that Items can decode as *Schema, []*Schema for the OAS 2.0 tuple form,
or bool; leave the documented types for AdditionalProperties, AdditionalItems,
UnevaluatedItems, and UnevaluatedProperties unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 78bab386-7a58-494e-84d9-6c04e1b41265

📥 Commits

Reviewing files that changed from the base of the PR and between b2be348 and 00bb5fb.

📒 Files selected for processing (15)

• .claude-plugin/marketplace.json
• .claude/docs/oas-concepts.md
• CLAUDE.md
• CONTRIBUTORS.md
• benchmarks/benchmark-v1.57.0.txt
• converter/deep_dive.md
• docs/developer-guide.md
• parser/deep_dive.md
• parser/doc.go
• parser/example_test.go
• plugin/.claude-plugin/plugin.json
• validator/deep_dive.md
• walker/deep_dive.md
• walker/example_test.go
• walker/options.go

[coderabbitai]

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Do not modify files under benchmarks/.

This entire file is a change under a prohibited directory. Remove benchmarks/benchmark-v1.57.0.txt from this PR, or update the repository rule before merging.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@benchmarks/benchmark-v1.57.0.txt` around lines 1 - 364, Remove the generated
benchmark artifact from the pull request; do not modify or retain
benchmarks/benchmark-v1.57.0.txt. Leave the repository’s benchmarks directory
unchanged unless the repository rule is explicitly updated to permit this file.

Source: Coding guidelines

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Document the OAS 2.0 tuple form for Items.

Items can also decode as []*parser.Schema for the OAS 2.0 tuple form, so the stated *Schema-or-bool set is incomplete.

Proposed fix

-// AdditionalProperties, AdditionalItems, UnevaluatedItems and UnevaluatedProperties
-// hold either a *Schema or a bool per JSON Schema, so consumers type-assert.
+// AdditionalProperties, AdditionalItems, UnevaluatedItems and UnevaluatedProperties
+// are polymorphic. Items may also be []*parser.Schema for the OAS 2.0 tuple form,
+// so consumers must type-assert according to the field and OAS version.

As per coding guidelines, “Items … [decode as] *Schema, []*Schema (OAS 2.0 tuple form), or bool.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	// ExampleSchema_items demonstrates reading Schema's any-typed fields. Items,
	// AdditionalProperties, AdditionalItems, UnevaluatedItems and UnevaluatedProperties
	// hold either a *Schema or a bool per JSON Schema, so consumers type-assert. The
	// decoded types are the same whether the source was YAML or JSON.
	// ExampleSchema_items demonstrates reading Schema's any-typed fields. Items,
	// AdditionalProperties, AdditionalItems, UnevaluatedItems and UnevaluatedProperties
	// are polymorphic. Items may also be []*parser.Schema for the OAS 2.0 tuple form,
	// so consumers must type-assert according to the field and OAS version. The
	// decoded types are the same whether the source was YAML or JSON.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@parser/example_test.go` around lines 392 - 395, Update the documentation
comment for ExampleSchema_items to state that Items can decode as *Schema,
[]*Schema for the OAS 2.0 tuple form, or bool; leave the documented types for
AdditionalProperties, AdditionalItems, UnevaluatedItems, and
UnevaluatedProperties unchanged.

Source: Coding guidelines