Skip to content

report.md

Latest commit

 

History

History
107 lines (74 loc) · 4.63 KB

report.md

File metadata and controls

107 lines (74 loc) · 4.63 KB
Raw

gaze report

Orchestrate Gaze's four analysis operations (CRAP, quality, classification, docscan) and pipe the combined JSON payload to an external AI CLI for formatting into a human-readable markdown report.

The formatted report is written to stdout and optionally appended to $GITHUB_STEP_SUMMARY for GitHub Actions Step Summary integration.

Synopsis

gaze report [packages] [flags]

Arguments

Argument Required Description
packages No Go package patterns (e.g., ./..., ./internal/...). Defaults to ./... when omitted.

When no package arguments are provided, ./... is used automatically (the entire module).

Flags

Flag Type Default Description
--format string text Output format: text (AI-formatted markdown) or json (raw analysis payload)
--ai string "" AI adapter: claude, gemini, ollama, or opencode. Required in text mode.
--model string "" Model name for the AI adapter. Required for ollama; optional for other adapters.
--ai-timeout duration 10m Maximum time to wait for the AI adapter to respond. Uses Go duration format (e.g., 5m, 30s, 2m30s).
--coverprofile string "" Path to a pre-generated Go coverage profile. Skips the internal go test -coverprofile run.
--max-crapload int not set CI gate: fail if CRAPload exceeds N. Absent by default (no enforcement).
--max-gaze-crapload int not set CI gate: fail if GazeCRAPload exceeds N. Absent by default (no enforcement).
--min-contract-coverage int not set CI gate: fail if average contract coverage is below N%. Absent by default (no enforcement).

Threshold Semantics

The threshold flags (--max-crapload, --max-gaze-crapload, --min-contract-coverage) use pointer semantics internally: when a flag is not provided, no threshold is enforced. When explicitly set — even to 0 — the threshold is active. This means --max-crapload=0 will fail if any function is in the CRAPload (i.e., zero tolerance).

Configuration Interaction

The gaze report command does not directly read .gaze.yaml. The underlying analysis pipeline uses default classification thresholds. To customize thresholds, use gaze crap and gaze quality individually.

The --coverprofile flag is the key CI optimization — pass a coverage profile generated during your test step to avoid running tests twice.

AI Adapter Details

Adapter Binary System Prompt Delivery Payload Delivery
claude claude Temp file via -p flag stdin
gemini gemini GEMINI.md in temp dir stdin
ollama HTTP API system field in JSON body prompt field in JSON body
opencode opencode .opencode/agents/gaze-reporter.md in temp dir via --dir stdin

Before the analysis pipeline starts, Gaze validates that the adapter binary exists on PATH (or that the Ollama HTTP API is reachable). An invalid binary produces a hard exit before any analysis runs.

Environment Variables

Variable Description
GITHUB_STEP_SUMMARY When set, the formatted report is appended to this file path for GitHub Actions Step Summary display. Symlink protection (O_NOFOLLOW) is applied.

Examples

AI-formatted report with Claude

gaze report ./... --ai=claude

JSON-only output (no AI required)

gaze report ./... --format=json > report.json

In JSON mode, the --ai flag is not required. The raw analysis payload is written directly to stdout.

CI integration with thresholds

# Generate coverage during test step
go test -race -count=1 -coverprofile=coverage.out ./...

# Run report with pre-generated coverage and quality gates
gaze report ./... \
  --ai=opencode \
  --coverprofile=coverage.out \
  --max-crapload=35 \
  --max-gaze-crapload=5 \
  --min-contract-coverage=8

Using Ollama (local model)

gaze report ./... --ai=ollama --model=llama3.2

The --model flag is required for Ollama and specifies which model to use for formatting.

See Also