Skip to content

feat(explain): make local report format configurable - #807

Merged
XuPeng-SH merged 6 commits into
mainfrom
feat/explain-html-artifacts
Sep 18, 2026
Merged

XuPeng-SH merged 6 commits into
mainfrom
feat/explain-html-artifacts

Conversation

@XuPeng-SH

Copy link
Copy Markdown
Collaborator

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, or text in [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 --all
  • cargo check -p astra-cli --lib --offline
  • cargo clippy -p astra-cli --lib --offline -- -D warnings
  • cargo clippy -p astra-config --lib --offline -- -D warnings
  • cargo 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...HEAD

Demo: /tmp/astra-explain-demo.html

@XuPeng-SH XuPeng-SH left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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",

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@XuPeng-SH
XuPeng-SH merged commit 513eb7a into main Sep 18, 2026
41 of 42 checks passed
@XuPeng-SH
XuPeng-SH deleted the feat/explain-html-artifacts branch September 18, 2026 03:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant