fix: refine OpenAPI semantic diff and adopt status JSON

[carlostasada]

Summary

• Expand the semantic diff for OAS 3.1 nullable / binary equivalents (including anyOf/oneOf + type: null, also with $ref siblings) and additive oneOf / anyOf members; added allOf members stay breaking.
• Compare operation security after document-level inheritance: adding OR alternatives while keeping every previously accepted non-empty scheme set is additive (e.g. Market Data BasicAuth alongside API keys); removing/replacing schemes, AND-tightening, and optional/empty → required stay breaking.
• Write build/openapi-adopt-status.json for machine-readable breaking / changed gating.
• Adopt when pins differ structurally from upstream (not only when the semantic surface changes), so equivalent spellings still catch up; key-order-only churn does not.
• Includes the one-PR drift workflow on bot/openapi-adopt (draft when breaking or adopt fails) with concurrency serialization.

Test plan

• PYTHONPATH=. python -m unittest scripts.tests.test_openapi_tools scripts.tests.test_adopt_openapi
• ./gradlew adoptOpenApiDryRun — Market Data inherit→BasicAuth OR widening is extended; crypto security: [] → required remains breaking
• Confirm build/openapi-adopt-status.json is written on dry-run

[greptile-apps]

Greptile Summary

The PR refines OpenAPI semantic comparison and adds machine-readable adoption status output.

• Classifies operation-level security changes as breaking.
• Normalizes equivalent nullable and binary schema representations.
• Treats additive oneOf and anyOf members as non-breaking while preserving breaking treatment for allOf.
• Adopts structurally changed pins even when the generated surface is equivalent.
• Writes build/openapi-adopt-status.json for automated gating.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
scripts/openapi_tools.py	Refines semantic normalization and composition matching, and now preserves operation authentication changes as breaking differences.
scripts/adopt_openapi.py	Adds structural pin-drift detection and writes machine-readable adoption status before applying exit gating.
scripts/tests/test_openapi_tools.py	Adds coverage for security changes, schema equivalences, and additive composition members.
scripts/tests/test_adopt_openapi.py	Covers status JSON output, structural pin catch-up, and refusal of security-only breaking adoption.
GENERATION.md	Documents structural pin adoption and the refined semantic change categories.
CHANGELOG.md	Records the semantic-diff and structural pin-adoption behavior changes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Load pinned and candidate specs] --> B[Normalize equivalent OpenAPI forms]
  B --> C[Compute semantic diff]
  A --> D[Compare structural fingerprints]
  C --> E{Breaking semantic change?}
  D --> F{Any structural drift?}
  E --> G[Write adoption report and status JSON]
  F --> G
  G --> H{Dry run or no change?}
  H -->|Yes| I[Exit without updating pins]
  H -->|No| J{Breaking change allowed?}
  J -->|No| K[Refuse adoption]
  J -->|Yes| L[Update pins and regenerate clients]

Loading

_{Reviews (2): Last reviewed commit: "fix: treat operation security requiremen..." | Re-trigger Greptile}

[carlostasada]

@greptileai