feat(cli): add structural-health columns to recipe list

[njhensley]

Summary

Extend aicr recipe list with the ADR-009 §4 structural-health view: a rolled-up status column and a compact per-phase coverage summary, delegating all computation to pkg/health so pkg/cli stays logic-free.

Motivation / Context

Part of the recipe health tracking epic (ADR-009 V1). #1208 delivered the recipe list enumeration command (criteria/leaf/source columns + --format/filter flags); this adds the health-derived columns on top, without changing #1208's output shape.

Fixes: #1228
Related: #1224 (epic), #1226/#1227 (health grading dependencies)

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update

Component(s) Affected

• CLI (cmd/aicr, pkg/cli)
• Docs/examples (docs/, examples/)
• Other: pkg/client/v1 facade (Client.ComputeHealth)

Implementation Notes

• New facade method Client.ComputeHealth(ctx, filter) wraps health.Compute, binding the client's own DataProvider + version so --data overlays are scored against the same catalog the listing enumerates (not the process-global embedded catalog). It follows the sibling facade guard pattern and deliberately omits the per-op timeout since health.Compute applies its own HealthComputeTimeout.
• table: adds STATUS (rolled-up verdict) and COVERAGE (compact per-phase named-check summary, R:n D:n P:n C:n); non-leaf overlays render -.
• json/yaml: each entry gains an additive health block (per-dimension status map + full declared_coverage), omitted for non-leaf overlays. The embedded CatalogEntry carries yaml:",inline" so feat(recipe): add aicr recipe list subcommand for catalog enumeration #1208's fields stay top-level — yaml.v3 does not auto-inline anonymous struct fields the way encoding/json does.
• Degrades gracefully: rendering reads the dimension set generically, so an absent constraints_wellformed dimension (pkg/health: constraints_wellformed signal (parse-only, hermetic) #1227 not yet merged) doesn't break the status column.

Testing

gofmt -l ...                          # clean
golangci-lint run (pinned v2.12.2)    # 0 issues
go test -race ./pkg/cli/... ./pkg/client/v1/...   # pass

Coverage: pkg/cli 64.0% → 67.7%, pkg/client/v1 75.1% → 75.3% (new ComputeHealth 81.2%). New tests cover the table/json/yaml formats, the non-leaf - placeholder, filtered-CLI pass-through, the empty-result branch, and a YAML-inline regression guard.

This change was reviewed by a multi-persona review pass (Go architecture, CLI/API-contract, test-quality), which caught and fixed a YAML serialization regression before push.

Risk Assessment

• Low — Additive output only; feat(recipe): add aicr recipe list subcommand for catalog enumeration #1208's existing fields/columns are unchanged and guarded by tests. Easy to revert.

Rollout notes: Backwards compatible. The health block is additive (omitted for non-leaf); existing json/yaml/table consumers see no field removals or renames.

Checklist

• Tests pass locally (make test with -race)
• Linter passes (make lint)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality
• I updated docs if user-facing behavior changed
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 4a925a91-1406-4c7c-a349-a90fa4f2e270

📥 Commits

Reviewing files that changed from the base of the PR and between 6c14530 and 53a79b3.

📒 Files selected for processing (5)

• docs/user/cli-reference.md
• pkg/cli/recipe_list.go
• pkg/cli/recipe_list_test.go
• pkg/client/v1/health.go
• pkg/client/v1/health_test.go

---

📝 Walkthrough

Walkthrough

This PR extends the aicr recipe list command to display ADR-009 structural-health status and declared-coverage summaries for leaf overlays. A new Client.ComputeHealth facade is introduced to compute and filter health reports, which the CLI then pairs with catalog entries and renders as STATUS/COVERAGE columns in table output or health objects in JSON/YAML. Non-leaf overlays render placeholder columns. Tests validate all output formats, filtering behavior, and edge cases. Documentation is updated with the new output field descriptions and examples.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Epic: Recipe health tracking (ADR-009 V1) — enumeration, structural soundness, public matrix #1224: This PR directly implements the recipe-list health augmentation checkpoint described in the epic, wiring Client.ComputeHealth into pkg/cli/recipe_list.go to render ADR-009 health STATUS/COVERAGE columns.

Possibly related PRs

• NVIDIA/aicr#1291: This PR's new aicr recipe list health rendering depends on the pkg/health.Compute core implementation, including leaf-overlay grading and the same status/coverage semantics.
• NVIDIA/aicr#1293: This PR renders health dimensions and declared coverage introduced by the retrieved PR's changes to the health model, including chart_pinned grading dimension and declared_coverage descriptor.

Suggested labels

area/recipes, size/L, theme/recipes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(cli): add structural-health columns to recipe list' is concise, specific, and directly summarizes the main change: adding health-derived columns to the recipe list output.
Description check	✅ Passed	The description is comprehensive and clearly related to the changeset, explaining the motivation, implementation details, testing approach, and risk assessment for adding structural-health columns to recipe list.
Linked Issues check	✅ Passed	The PR fully meets the objectives from #1228: it adds structural-health columns to recipe list, implements table/JSON/YAML formats with health data, introduces Client.ComputeHealth facade, updates documentation, and includes comprehensive tests covering all required scenarios.
Out of Scope Changes check	✅ Passed	All changes are scoped to the #1228 objective: health columns in recipe list output, the ComputeHealth facade, documentation updates, and corresponding tests. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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