docs(audits): dated API coverage snapshot + green main (closes #428)

[axisrow]

Summary

Closes the two open issues of milestone 0.3.15 (#428, #448).

• audit: снимок покрытия Yandex Direct API после волны #415–#425 (v5 ✅, v4 23/33) #428 — adds docs/audits/API_COVERAGE.md, a dated parity snapshot (main @ e9c7ea5) as a reference point for future audits. All figures are script-generated (build_api_coverage_report.py, build_wsdl_optional_field_audit.py) cross-referenced with direct_cli/v4_contracts.py:
  • v5 WSDL: 29 services / 112 operations, strict parity, 0 model gaps.
  • Reports: 8 types / 84 fields / 6 headers, fully covered.
  • Optional-field audit: 3215 supported / 26 not_applicable / 0 missing_followup.
  • v4: 23 / 32 contracts CLI-wired; the 4 formerly-undocumented methods are now docs-verified (docs(v4): document GetKeywordsSuggestion contract from official docs (closes #435) #444–447); GetCreditLimits/CheckPayment now have CLI commands (docs(v4): verify GetCreditLimits wire-shape against official docs (closes #430) #439/docs(v4): stamp CheckPayment with docs-absence verification (closes #431) #440).
• chore(v4finance): remove dead V4_FINANCE_CURRENCIES constant after #441/#442/#443 merge #448 — no code needed: V4_FINANCE_CURRENCIES was already removed on main by fix(v4): align create-invoice wire-body with docs; drop Currency (closes #434) #443. Verified grep -rn V4_FINANCE_CURRENCIES is empty and the suite is green.
• Drive-by: fixes a red test on main introduced by the docs(v4): document GetKeywordsSuggestion contract from official docs (closes #435) #444–447 docs wave — test_call_v4_refuses_undocumented_write_method now uses the _or_skip variant (no contract has param_shape=undocumented + safety=write anymore; the runtime guard is intact, the path is just unreachable).

Test plan

• pytest tests/test_api_coverage.py tests/test_wsdl_parity_gate.py tests/test_v4_live_contracts.py — green
• python3 scripts/build_wsdl_optional_field_audit.py --check — current
• python3 scripts/check_reports_drift.py — 0 drift
• full unit suite (pytest --ignore=tests/test_integration.py) — 1899 passed, 37 skipped

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a dated API coverage snapshot document for milestone 0.3.15 and fixes a failing test on main by switching to a skip-tolerant helper since no v4 contract currently has the undocumented + write combination.

Changes:

• New docs/audits/API_COVERAGE.md with frozen parity snapshot at commit e9c7ea5.
• Updates test_call_v4_refuses_undocumented_write_method to use _first_method_with_shape_and_safety_or_skip so the test skips instead of failing when no matching contract exists.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/audits/API_COVERAGE.md	New dated API coverage snapshot doc for #428.
tests/test_v4_runtime_shape.py	Switch undocumented-write test to _or_skip helper to handle empty registry case.

[axisrow]

@claude review. Focus on critical issues: bugs, security vulnerabilities, logical errors, data loss risks, performance problems. Do NOT nitpick style, naming conventions, minor formatting, or subjective preferences — only flag issues that could break functionality or cause real harm in production.

[claude]

Claude finished @axisrow's task in 1m 3s —— View job

---

Review: PR #449 — API coverage snapshot + green-main test fix

Verdict: No critical issues. Safe to merge.

Scope is small: one new docs file and a 1-line test-helper swap. I focused on the test change since the doc is non-executable.

Test change — correct ✅

tests/test_v4_runtime_shape.py:118 switches test_call_v4_refuses_undocumented_write_method from _first_method_with_shape_and_safety (hard AssertionError on no match) to the _or_skip variant. I verified the reasoning end-to-end:

• The registry has exactly one PARAM_UNDOCUMENTED contract: PayCampaignsByCard at direct_cli/v4_contracts.py:129, with safety=SAFETY_DANGEROUS. There is no undocumented+write pair, so the old assert genuinely fails — the skip is the right fix, not a masked bug.
• The runtime guard is confirmed intact: direct_cli/v4/__init__.py:15 defines _UNSAFE_SAFETY_LEVELS = {SAFETY_WRITE, SAFETY_DANGEROUS} and line 43 refuses any method in that set. WRITE and DANGEROUS hit the identical refusing to send path, so the behaviour the test asserts is still enforced — it's just unreachable from the current registry.
• test_call_v4_refuses_undocumented_dangerous_method (line 130) still uses the non-skip helper and stays green because PayCampaignsByCard matches undocumented+dangerous. So the refuse-to-send path remains covered by a real, executing test — the skip doesn't create a coverage hole.

The behaviour-test-that-skips-when-its-precondition-is-unreachable is an acceptable pattern here; the parallel dangerous test keeps the guard under live coverage.

Docs file — fine

docs/audits/API_COVERAGE.md is an explicitly frozen, commit-pinned snapshot with the regeneration commands inlined. Figures can drift from main over time, but that's the stated intent of a dated audit, not a defect.

Notes (non-blocking)

• The doc claims "5 undocumented" v4 methods — that's the documentation source (SOURCE_UNDOCUMENTED), a distinct axis from param_shape=undocumented (of which there's 1). The wording is correct in context; flagging only so a future reader doesn't conflate the two when re-counting.

No bugs, security, data-loss, or performance concerns found.

---

• Read PR diff
• Analyze test change (_or_skip semantics)
• Verify doc claims against repo state
• Post review
  · chore/issue-428-api-coverage-snapshot