Documentation
¶
Overview ¶
Package output renders analysis results to various output formats (terminal, JSON, HTML, badges).
HTML report generation uses Go's embedded template system (//go:embed) to bundle templates at compile time, producing self-contained binaries with no runtime dependencies. The generated HTML is fully standalone: all CSS, JavaScript, and chart rendering code is inlined, allowing reports to be viewed offline without external CDN dependencies.
CRITICAL MAINTENANCE NOTE: Templates are embedded at compile time. After modifying templates/report.html or templates/styles.css, you MUST rebuild the binary with `go build -o ars .` for changes to take effect. Hot-reloading does NOT work.
Security: All user-generated content (file paths, evidence, scores) is sanitized via template.JSEscape() before embedding in <script> tags to prevent XSS attacks.
Package output renders analysis results to various output formats (terminal, JSON, HTML, badges).
Terminal rendering uses hierarchical display with automatic color encoding (green/yellow/red) based on score thresholds. Colors convey metric health at a glance without requiring users to interpret numeric scores. NO_COLOR environment variable support ensures compatibility with screen readers, CI/CD pipelines, and accessibility tools per https://no-color.org standards.
The package handles evidence formatting, section expansion/collapse for verbose output, and tier classification display with visual indicators (emojis, color, progress bars).
Index ¶
- func GenerateBadge(scored *types.ScoredResult) badgeInfo
- func NewHTMLGenerator() (*htmlGenerator, error)
- func RenderBadge(w io.Writer, scored *types.ScoredResult)
- func RenderC7Debug(w io.Writer, analysisResults []*types.AnalysisResult)
- func RenderJSON(w io.Writer, report *JSONReport) error
- func RenderRecommendations(w io.Writer, recs []recommend.Recommendation)
- func RenderScores(w io.Writer, scored *types.ScoredResult, verbose bool)
- func RenderSummary(w io.Writer, result *types.ScanResult, analysisResults []*types.AnalysisResult, ...)
- type JSONReport
- type TraceData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GenerateBadge ¶
func GenerateBadge(scored *types.ScoredResult) badgeInfo
GenerateBadge creates a shields.io badge URL and markdown from a scored result. Returns empty badgeInfo if scored is nil.
func NewHTMLGenerator ¶
func NewHTMLGenerator() (*htmlGenerator, error)
NewHTMLGenerator creates a generator with embedded templates.
func RenderBadge ¶
func RenderBadge(w io.Writer, scored *types.ScoredResult)
RenderBadge prints the shields.io badge markdown to w.
func RenderC7Debug ¶
func RenderC7Debug(w io.Writer, analysisResults []*types.AnalysisResult)
RenderC7Debug renders detailed C7 debug data (prompts, responses, scores, traces) to the provided writer. This is called only when --debug-c7 is active. The writer is typically os.Stderr so debug output never mixes with normal stdout output.
Debug rendering helps developers: 1. Understand why C7 scores are low (inspect actual agent responses) 2. Validate C7 scoring heuristics (see score trace breakdowns) 3. Debug Claude CLI integration issues (capture raw prompts/responses) 4. Replay saved responses without hitting the Claude API (--debug-dir)
Output goes to stderr by convention to keep stdout clean for JSON pipelines and avoid contaminating production output with debug data.
func RenderJSON ¶
func RenderJSON(w io.Writer, report *JSONReport) error
RenderJSON writes the JSON report to w with pretty-printed indentation.
func RenderRecommendations ¶
func RenderRecommendations(w io.Writer, recs []recommend.Recommendation)
RenderRecommendations prints ranked improvement recommendations to w.
Each recommendation shows rank, summary, impact, effort, and action. Recommendations are pre-sorted by ROI (impact/effort ratio) in the recommend package, so displaying them in order guides users toward the most efficient improvements. High-impact, low-effort changes appear first (quick wins).
Impact visualization uses color thresholds: ≥0.5 points = green (significant), ≥0.2 points = yellow (moderate), <0.2 = red (marginal). This helps users gauge whether a recommendation is worth pursuing given their tier goals.
func RenderScores ¶
func RenderScores(w io.Writer, scored *types.ScoredResult, verbose bool)
RenderScores prints a formatted scoring section showing per-category scores, composite score, and tier rating. When verbose is true, per-metric sub-score breakdowns are shown beneath each category.
Score rendering uses color-coded thresholds aligned with tier boundaries: - Green (≥8.0): Agent-Ready tier, agents can work autonomously - Yellow (≥6.0): Agent-Assisted tier, agents need human guidance - Red (<6.0): Agent-Limited or Agent-Hostile, agents struggle significantly
This color mapping helps users quickly identify categories dragging down the composite score and prioritize improvements for tier advancement.
func RenderSummary ¶
func RenderSummary(w io.Writer, result *types.ScanResult, analysisResults []*types.AnalysisResult, verbose bool)
RenderSummary prints a formatted scan summary to w.
Color is automatically disabled when w is not a TTY (e.g., piped output). This prevents ANSI escape codes from corrupting piped data while preserving the visual hierarchy when output goes to a terminal. The layout uses a fixed hierarchy: header → file counts → per-language breakdown → exclusion counts → verbose file listing → category-specific metrics (C1-C7).
Each category renderer (renderC1-C7) follows the same pattern: bold headers, color-coded metrics using score thresholds, and optional verbose sections for detailed breakdowns (top offenders, per-item details, traces).
Types ¶
type JSONReport ¶
type JSONReport struct {
Version string `json:"version"`
CompositeScore float64 `json:"composite_score"`
Tier string `json:"tier"`
Categories []jsonCategory `json:"categories"`
Recommendations []jsonRecommendation `json:"recommendations"`
BadgeURL string `json:"badge_url,omitempty"`
BadgeMarkdown string `json:"badge_markdown,omitempty"`
}
JSONReport is the top-level JSON output structure.
func BuildJSONReport ¶
func BuildJSONReport(scored *types.ScoredResult, recs []recommend.Recommendation, verbose bool, includeBadge bool) *JSONReport
BuildJSONReport converts a ScoredResult and recommendations into a JSONReport. The verbose parameter is deprecated; sub_scores are always included. When includeBadge is true, badge URL and markdown are included.
type TraceData ¶
type TraceData struct {
ScoringConfig *scoring.ScoringConfig
AnalysisResults []*types.AnalysisResult
Languages []string // Detected project languages for build/test commands
}
TraceData holds analysis data needed for rendering call trace modals. Passed to GenerateReport; can be nil when trace rendering is not needed.
Source Files