feat(cli): add Archera comparison filters

[cristim]

archera-comparison can now narrow the vendor comparison with --line-item-ids, --contract-terms and --payment-options, matching the existing MCP filters. Each accepts comma-separated values and repeated flags. Omitted filters retain the vendor defaults.

Empty values and over-limit collections fail before HTTP. UUID and enum validation reuse the shared client, while fixed validation messages avoid echoing rejected values. Vendor status and Retry-After handling remain intact. IDs belong to Archera; these filters do not establish platform recommendation association.

Verification:

• On the parent, seven positive filter scenarios fail with unknown-flag errors while the omission control passes.
• The final implementation passes 31 top-level focused race tests through the real root command and shared client with an intercepted transport; an independent reviewer reproduced the focused run.
• Full race suite: 471 top-level tests pass. Build, vet, complexity, tidy, pinned golangci-lint v2.10.1 and formatting checks pass.
• Two independent Sol High reviewers each completed two adversarial passes; both documentation findings are fixed. Exact committed-head approvals will be posted below.

Tests use synthetic intercepted responses. No live vendor calls, purchases, installation or deployment were performed.

Closes #2264

Summary by CodeRabbit

• New Features
  • Added filters for line-item IDs, contract terms, and payment options to Archera comparisons. Filters accept repeated or comma-separated values and enforce supported values and limits.
  • Comparison results can show a hypothetical plan rollup narrowed by these filters.
• Documentation
  • Updated the CLI guide with filter formats, accepted values, limits, and validation behavior.

[cristim]

@coderabbitai review

[cristim]

Session: go441_reviewer_a
APPROVED 28574f7 by go441_reviewer_a

Two adversarial passes completed; documentation findings are resolved. Verified committed tree 9026b1296c5c46cda90d336ae73abf077aeb9c2e maps exactly to reviewed snapshot ee9223c496bc1b8cf58c966808d18ab5a921e0b36fcd8af7a31975fbbea8bba3, with the expected parent and four-file scope. Worktree was clean.

Attacked comma/repeated/empty values, duplicate counting, shared UUID/enum validation, error-value secrecy, transport/HTTP error separation, flag resets, query serialization and omission defaults. The docs now state the actual 74-term maximum. No actionable findings remain.

Independent focused race replay with Go 1.26.9 passed 31 top-level tests, 206 including subtests, using the real root command and shared client with synthetic intercepted HTTP. The first sandboxed attempt could not bind a loopback fixture server; the permitted retry passed. No live vendor/cloud verification. CI and required protections remain separate merge gates.

[cristim]

Session: go441_reviewer_b
APPROVED 28574f7 by go441_reviewer_b

Two adversarial passes completed; both documentation findings are resolved. Committed bytes match reviewed snapshot ee9223c496bc1b8cf58c966808d18ab5a921e0b36fcd8af7a31975fbbea8bba3, with expected parent e47d6054ecc5c57a458dc9da13906f8aa41e8b60, tree 9026b1296c5c46cda90d336ae73abf077aeb9c2e and four-file scope. Worktree was clean.

Checked bounds, duplicate preservation, empty-value rejection before HTTP, shared validation, fixed safe validation messages, existing status/Retry-After behavior, flag resets and field-layout associations. Documentation now names the correct 74-term limit and omission defaults. No actionable findings remain.

I inspected author verification logs, including seven positive parent unknown-flag failures and the passing omission control, full race suite, build and pinned lint. Reviewer A separately reproduced the focused run: 31 top-level tests, 206 including subtests. I ran no tests. This is code-review approval; CI and required protections must pass before merge.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: LeanerCloud/cloud-commitments-cli/.coderabbit.yaml
• Review profile: CHILL
• Plan: Essentials
• Run ID: 30880296-094d-4ddf-be43-33220fa1df61

📥 Commits

Reviewing files that changed from the base of the PR and between e47d605 and 28574f7.

📒 Files selected for processing: 4

• cmd/archera_comparison.go
• cmd/archera_comparison_filters_test.go
• cmd/archera_comparison_test.go
• docs/cli/archera-comparison.md

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

📝 Walkthrough

The archera-comparison command accepts line-item ID, contract-term, and payment-option filters. It parses and validates these values before making a comparison request. Filter errors omit rejected values, and command runs reset filter state.

Changes: Archera comparison filters

Layer / File(s)	Summary
Filter flags and comparison request cmd/archera_comparison.go, cmd/archera_comparison_filters_test.go, docs/cli/archera-comparison.md	The command accepts repeated and comma-separated filter values and includes them in the comparison request. Tests cover query construction, and the documentation describes accepted values, limits, and omitted-filter behavior.
Validation and command state cmd/archera_comparison.go, cmd/archera_comparison_filters_test.go, cmd/archera_comparison_test.go	Invalid or excessive values fail before an HTTP request. Filter validation errors omit rejected values. Tests cover error attribution, help output, and resetting flag state between runs.

Priority: ⬇️ Low

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant archeraComparisonRequest
  participant insurance.Client
  participant ComparisonEndpoint
  CLI->>archeraComparisonRequest: Pass filter flag values
  archeraComparisonRequest-->>CLI: Return ComparisonRequest or validation error
  CLI->>insurance.Client: Submit ComparisonRequest
  insurance.Client->>ComparisonEndpoint: Send comparison request

Loading

Merge Risk: ⚪ Minimal · up to 28574

No identified filter issue remains to resolve before merging; normal checks still apply.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Issue #2264 coding requirements are met. cmd/archera_comparison.go adds all three flags, supports repeated and comma-separated entries, applies the 200, shared contract-term, and three payment-optio…
Out of Scope Changes check		The changes stay within issue #2264. Production changes add filters to the existing Archera comparison command and preserve its client, status, retry, rendering, and disclosure paths. Tests verify the…
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: adding Archera comparison filters to the CLI.

Full details: Linked Issues check

Explanation

Issue #2264 coding requirements are met. cmd/archera_comparison.go adds all three flags, supports repeated and comma-separated entries, applies the 200, shared contract-term, and three payment-option limits, and builds insurance.ComparisonRequest. Omitted filters produce no query parameters. Empty entries fail before client creation. Shared client validation handles UUID and enum values, and archeraSafeError removes rejected values from validation errors. The added tests cover query serialization, exact bounds, rejection before HTTP, help, flag reset, and redaction. The change preserves the read-only comparison and documents Archera ID scope and existing disclosures.

Full details: Out of Scope Changes check

Explanation

The changes stay within issue #2264. Production changes add filters to the existing Archera comparison command and preserve its client, status, retry, rendering, and disclosure paths. Tests verify the requested command behavior. Documentation describes the new flags, limits, defaults, validation, and non-association semantics. No dependency, matcher, purchase, deployment, or unrelated abstraction change is present.

Full details: Docstring Coverage

Explanation

Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 3 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

Session: resume-cc-audit

CodeRabbit completed a real review of 28574f7d54be0e43b38a374b88bc31a5b8940a06, with source and covered commit both matching that head and kind: reviewed. It reports no actionable comments; inline-comment and submitted-review lists are empty. The green status represents an actual completed comment-summary review.

The optional docstring-coverage warning is dismissed: CLI help and the command reference document the public contract, and the small private helpers and test names already express their operations. Adding comments that restate those operations would conflict with the minimal-comment convention. No inline finding is left unanswered.

Both independent exact-head approvals, parent failure and independent focused replay are recorded above. All required CI checks are green on this head, and GitHub reports MERGEABLE/CLEAN. A normal authorized merge may proceed without bypassing protections.

Follow-up issues filed: none for these filters, confirmed against the follow-up checklist. Line-item listing and recommendation association remain distinct work under the existing Archera integration tracking.