feat(explain): make local report format configurable - #807
Conversation
XuPeng-SH
left a comment
There was a problem hiding this comment.
Review conclusion: changes requested. GitHub prevents the authenticated PR author from submitting REQUEST_CHANGES on their own PR, so this is posted as a COMMENT review; it is not an approval.
Reviewed head 620c17f, including config precedence and CLI/TUI propagation, canonical/derived artifact publication, HTML escaping and bounds, clock-domain timing, and runtime outcome producers. One correctness issue remains: terminal outcomes are misrepresented as incomplete in the default HTML report. Please preserve those recorded outcomes in collapsed stage rows and cover all terminal outcome variants.
Validation: git diff --check passed. Cargo is unavailable in this review environment, so I could not independently run Rust tests. Static Checks and Test Suite are still in progress for this head.
| | ExplainAnalyzeOutcomeV1::Deferred, | ||
| ) => "waiting", | ||
| Some(ExplainAnalyzeOutcomeV1::Cancelled) => "cancelled", | ||
| _ => "incomplete", |
There was a problem hiding this comment.
[P2] Preserve recorded terminal outcomes in the stage summary
Even when terminal_observed is true, Reused, Suppressed, Delegated, Fallback, Unavailable, and Interrupted fall through to incomplete. render_node uses this value as the visible outcome in every collapsed stage row, not just as a CSS class. These are reachable runtime results: finish_explain_analyze_tool_call emits Reused/Suppressed, and on_turn_terminal emits Delegated. A fully recorded reused tool or delegated turn therefore appears unfinished in the new default report (and can contradict the report's recorded capture badge and expanded outcome). Keep presentation color classification separate from the displayed canonical outcome, reserving incomplete for genuinely missing terminal facts. Add coverage for these terminal variants.
What changed
Explain Analyze now publishes a bounded standalone HTML report by default, while keeping the canonical JSON artifact as the source of truth. Users can choose
html,markdown, ortextin[explain].report_format,/config, or/explain --format …; format-only commands keep the current explain mode.The HTML report is an inspection workspace designed for long and incomplete runs: outcome and capture completeness are separate, stage rows use native disclosure, token coverage and estimates are explicit, clock domains are normalized, missing ends and delivery gaps are actionable, labels are escaped, and output is bounded. Reports publish atomically and failed derived writes clean up their temporary file without hiding the canonical artifact.
Validation
cargo fmt --allcargo check -p astra-cli --lib --offlinecargo clippy -p astra-cli --lib --offline -- -D warningscargo clippy -p astra-config --lib --offline -- -D warningscargo test -p astra-cli --lib --offline explain(81 passed)cargo test -p astra-config --lib --offline explain_report_format(4 passed)git diff --check origin/main...HEADDemo:
/tmp/astra-explain-demo.html