Model OpenAPI enum constraints

[sdairs]

Closes #296

Summary

• add typed BYOC availability-zone suffixes, query endpoint roles, upgrade-window values, and Postgres slow-query sorting
• extend the shared analyzer to compare integer enum constraints against explicitly serialized Rust enums
• remove eight remediated acknowledgements while documenting why three deprecated API-key role fields remain scalar
• validate query endpoint --role values from the library enum and update auto-provisioning, output, and docs
• bump the drift report schema to version 3 for the new integer-enum semantics

Verification

• cargo test --workspace
• cargo clippy --workspace --all-targets -- -D warnings
• cargo fmt --all --check
• cargo check --workspace --all-features
• python3 -m unittest discover -s scripts/tests -p "test_*.py"
• python3 scripts/check-openapi-drift.py --dry-run (0 actionable drift; 5 acknowledged unsupported constraints)

[sdairs]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit b52fba0. Configure here.}

[Copilot]

Pull request overview

Updates clickhousectl and the shared OpenAPI drift analyzer to model previously scalar OpenAPI enum constraints as typed Rust enums (including integer-backed enums), and wires those types through the API library, CLI validation, tests, and documentation while bumping the drift report schema to v3.

Changes:

• Add typed enums for BYOC availability-zone suffixes, query-endpoint roles, upgrade-window numeric fields, and Postgres slow-query sorting; propagate through client signatures and CLI request building/validation.
• Extend the OpenAPI analyzer to distinguish integer enum constraints, inventory integer-discriminant Rust enums (with explicit i64 Serde conversion), and compare these constraints bidirectionally.
• Bump analyzer report schema version (v2 → v3) and update the drift-check script, tests, and README examples accordingly.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/tests/test_check_openapi_drift.py	Updates drift-report schema version expectations and validation tests for v3.
scripts/check-openapi-drift.py	Requires analyzer report schema_version 3.
README.md	Updates query-endpoint docs/examples to reflect typed/validated roles.
crates/clickhousectl/tests/cli_request_shape_test.rs	Adds CLI wiremock coverage to assert typed query-endpoint roles serialize correctly.
crates/clickhousectl/src/cloud/services.rs	Validates query-endpoint --role values against library enum values and builds typed role requests.
crates/clickhousectl/src/cloud/service_query.rs	Switches auto-provisioning to use typed query-endpoint role enum.
crates/clickhouse-openapi-analyzer/src/rust_inventory.rs	Inventories integer discriminants + Serde i64 conversion metadata for Rust enums.
crates/clickhouse-openapi-analyzer/src/report.rs	Bumps drift report schema constant to v3.
crates/clickhouse-openapi-analyzer/src/openapi.rs	Distinguishes integer-only enums vs other numeric enums in spec inventory.
crates/clickhouse-openapi-analyzer/src/config.rs	Removes remediated enum acknowledgements; documents remaining deprecated API-key role scalar decision.
crates/clickhouse-openapi-analyzer/src/compare.rs	Compares integer enum constraints against checkable Rust integer enums; adds fixtures/tests.
crates/clickhouse-cloud-api/tests/models_test.rs	Adds/updates model serialization + unknown-value tolerance tests for new typed enums.
crates/clickhouse-cloud-api/tests/model_facade_test.rs	Ensures new model types are re-exported consistently via root and models::*.
crates/clickhouse-cloud-api/tests/integration_test.rs	Updates integration tests to use typed query-endpoint roles and upgrade-window types.
crates/clickhouse-cloud-api/tests/client_test.rs	Updates client tests for typed query-endpoint roles, typed slow-query sort params, and upgrade-window values.
crates/clickhouse-cloud-api/src/models/services.rs	Introduces QueryEndpointRole, UpgradeWindowStartHourUtc, UpgradeWindowDuration; updates request/response types.
crates/clickhouse-cloud-api/src/models/postgres.rs	Introduces typed slow-query sorting enums used by the client method.
crates/clickhouse-cloud-api/src/models/byoc.rs	Introduces ByocAvailabilityZoneSuffix and updates BYOC request type accordingly.
crates/clickhouse-cloud-api/src/models.rs	Re-exports newly introduced enums through the public facade.
crates/clickhouse-cloud-api/src/client/postgres.rs	Changes slow-query list method signature to accept typed sorting enums.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.