Fix docs and installed-wheel claim drift

[karlwaldman]

Problem

The claim guard covered only README.md, pyproject.toml, and oilpriceapi/init.py. Public docs and most packaged source could bypass it. Current docs still advertised 1,000 API requests/month, fixed plan prices, a five-minute cadence, and a 99.9% uptime SLA; the installed wheel also carried a fixed streaming plan/price in customer recovery text. This is the Python portion of OilpriceAPI/oilpriceapi-api#5644.

Red / green

Red before implementation:

• recursive-discovery and installed-wheel tests failed because neither contract existed
• after discovery was wired, the current tree exposed 23 blocked customer-visible claims
• the future package-data regression failed because .pyi, Markdown, JSON, and other readable wheel files bypassed the .py-only scan
• release-readiness failed because the wheel smoke did not inspect installed claims

Green at 2f77d57:

• release unit suite: 416 passed, 13 skipped, 62.26% coverage
• focused future wheel-surface regressions: 4 passed
• Ruff source and changed claim files: green
• mypy: 46 source files, zero issues
• authored/generated claim scan: 61 surfaces
• exact built 1.12.2 wheel: 53 UTF-8 surfaces derived from RECORD, including .py, metadata, license, py.typed, and text files; .pyc is explicitly excluded
• exact wheel clean install, pip check, claim scan, and production demo smoke: green
• git diff --check: clean

Change

• recursively scan docs, examples, and all package source
• derive installed artifact discovery from the exact wheel RECORD and scan every customer-readable UTF-8 file, not a fixed extension list
• retain the canonical 50 requests/day allowance and link it to product facts
• replace stale monthly quota, plan-price, cadence, uptime, and generic real-time claims with API-provided metadata and current pricing links
• bump the patch candidate to 1.12.2 so PyPI consumers receive corrected docs and recovery copy

No API, entitlement, credential, email, or customer mutation is included.

[coderabbitai]

📝 Walkthrough

Walkthrough

The release updates documentation and package docstrings, expands storefront claim validation to repository and installed-wheel surfaces, and wires installed-artifact checks into the wheel smoke test. The package version and changelog advance to 1.12.2.

Changes

Storefront and release validation

Layer / File(s)	Summary
Update public claims EXAMPLES.md, docs/*, oilpriceapi/async_client.py, oilpriceapi/resources/diesel.py, oilpriceapi/streaming/*	Documentation and docstrings now describe source timestamps, account entitlements, WebSocket price updates, and current product information.
Expand public-surface validation scripts/validate_storefront_claims.py, tests/test_storefront_claims.py	Validation now discovers documentation and nested package sources, scans labeled blocked claims, and checks installed package metadata and versions. Tests cover discovery and wheel-only claims.
Wire the 1.12.2 release checks oilpriceapi/version.py, pyproject.toml, CHANGELOG.md, scripts/clean-wheel-smoke.sh, tests/test_release_readiness.py	The package and changelog advance to 1.12.2. The wheel smoke test validates the installed package root, and the readiness test checks the new CLI option.

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

Sequence Diagram(s)

sequenceDiagram
  participant CleanWheelSmoke
  participant InstalledWheel
  participant ValidateStorefrontClaims
  participant PackageMetadata
  CleanWheelSmoke->>InstalledWheel: install wheel and locate package root
  CleanWheelSmoke->>ValidateStorefrontClaims: run --package-root
  ValidateStorefrontClaims->>InstalledWheel: scan installed package sources
  ValidateStorefrontClaims->>PackageMetadata: inspect metadata and version
  PackageMetadata-->>ValidateStorefrontClaims: return contract and version data
  ValidateStorefrontClaims-->>CleanWheelSmoke: report validation result

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.43% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes to documentation and installed-wheel claim validation.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/claim-surface-guard

---

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.}

[coderabbitai]

Actionable comments posted: 4

🤖 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 `@docs/PERFORMANCE_GUIDE.md`:
- Line 347: Update the cache examples around the application-selected bucket and
the Redis example to use the documented source-timestamp freshness policy
consistently: make the freshness interval explicit, include the API/source
timestamp with each cached value, and derive staleness from that timestamp
rather than hard-coded five-minute or commodity-only key behavior. If retaining
five-minute values, clearly label them as illustrative.

In `@docs/TELEMETRY.md`:
- Line 194: Update the telemetry diagram’s “max 10 or 5min” label to reference
the configured batch interval, or explicitly identify five minutes as the
default, keeping it consistent with the configured batch interval described in
step 3.

In `@oilpriceapi/resources/diesel.py`:
- Around line 19-20: Update the get_price and get_stations docstrings to remove
or qualify hard-coded tier, free-access, and monthly station-limit claims,
ensuring both package source and installed documentation describe current
entitlements and rely on response metadata where applicable.

In `@scripts/validate_storefront_claims.py`:
- Around line 131-142: Update the non-package-root success message in main so it
reports the count from discover_public_surfaces() as “public surfaces” rather
than “Python public surfaces”; leave the exact installed artifact message
unchanged.

🪄 Autofix

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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e751d152-4522-40aa-abb1-fac76f0ecacb

📥 Commits

Reviewing files that changed from the base of the PR and between 7f2338c and 71dab1e.

📒 Files selected for processing (15)

• CHANGELOG.md
• EXAMPLES.md
• docs/PERFORMANCE_GUIDE.md
• docs/TELEMETRY.md
• docs/index.md
• oilpriceapi/async_client.py
• oilpriceapi/resources/diesel.py
• oilpriceapi/streaming/__init__.py
• oilpriceapi/streaming/client.py
• oilpriceapi/version.py
• pyproject.toml
• scripts/clean-wheel-smoke.sh
• scripts/validate_storefront_claims.py
• tests/test_release_readiness.py
• tests/test_storefront_claims.py