superseded: OpenAPI adopt recovery / classifier / drift (split)

[carlostasada]

Superseded

This branch was split into a smaller review stack. Please review and merge in order:

1. fix: harden OpenAPI adopt recovery and pin-forced regenerate #53 — adopt recovery + pin-forced regenerate + enum additive
2. fix: refine OpenAPI semantic diff and adopt status JSON #54 — semantic diff refinements + openapi-adopt-status.json (stacks on fix: harden OpenAPI adopt recovery and pin-forced regenerate #53)
3. ci: open one OpenAPI adopt PR instead of breaking issues #55 — one-PR drift workflow instead of breaking issues (stacks on fix: refine OpenAPI semantic diff and adopt status JSON #54)

Backup tip: 2ddd5fe on ctasada/harden-openapi (also refs/backup/pre-split-* locally).

Closing this PR to avoid duplicate review; the stacked PRs carry the full change set.

[greptile-apps]

Greptile Summary

The PR reclassifies additive enum values as non-breaking and adds rollback-and-regeneration handling for failed OpenAPI adoption. It also broadens SpotBugs coverage, hardens JaCoCo XML parsing, and centralizes spec downloads.

• Adds recursive enum-widening classification for schemas and inline operation definitions.
• Backs up pins during adoption and attempts to restore and regenerate after generation failures.
• Expands build-quality coverage and adds focused tests and documentation.

Confidence Score: 4/5

The spec-override propagation must be fixed before merging because adoption can succeed while generated sources do not correspond to the newly committed pins.

The nested regeneration forwards spec-source properties even though successful generation clears the only rollback marker, allowing overridden inputs to produce committed sources that disagree with the adopted specifications.

Files Needing Attention: build-logic/src/main/groovy/alpaca.openapi-generation.gradle

Important Files Changed

Filename	Overview
build-logic/src/main/groovy/alpaca.openapi-generation.gradle	Adds adoption rollback orchestration, but the initial regeneration forwards spec overrides and can clear the backup after generating from the wrong source.
scripts/adopt_openapi.py	Adds transactional pin writes, manual restoration, and recovery regeneration with focused unit coverage.
scripts/openapi_tools.py	Folds additive enum values out of surface comparisons and collects inline operation enums for reporting.
build-logic/src/main/groovy/markets/alpaca/gradle/OpenApiSpecSupport.groovy	Centralizes HTTP spec loading with status checks, request headers, timeouts, and empty-download rejection.
build-logic/src/main/groovy/alpaca.testing.gradle	Disables external entity and DTD loading while retaining support for JaCoCo's DOCTYPE.
build-logic/src/main/groovy/alpaca.quality.gradle	Replaces the handwritten-class allowlist with an exclusion limited to generated OpenAPI classes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Apply adopted pins] --> B[Create pin backup]
  B --> C[Forward Gradle project properties]
  C --> D[Nested generateApis]
  D --> E{Spec override present?}
  E -- No --> F[Generate from adopted specs]
  E -- Yes --> G[Generate from overridden source]
  F --> H[Delete pin backup]
  G --> H
  H --> I[Nested tests]

Loading

_{Reviews (1): Last reviewed commit: "fix: harden OpenAPI adopt recovery and e..." | Re-trigger Greptile}

[carlostasada]

Superseded by the stacked split: #53 → #54 → #55. Closing to keep review focused.