diff --git a/.opencode/agents/gaze-reporter.md b/.opencode/agents/gaze-reporter.md index d860b8e..bf9a9b8 100644 --- a/.opencode/agents/gaze-reporter.md +++ b/.opencode/agents/gaze-reporter.md @@ -1,10 +1,9 @@ --- description: > - Quality report agent for Go and external-analyzer projects. Runs gaze - CLI commands to produce human-readable summaries of CRAP scores, test - quality metrics, side effect classifications, and overall project - health. Supports three modes: crap (CRAP scores only), quality (test - quality metrics only), and full (comprehensive health assessment). + Quality report agent for Go and external-analyzer projects. Shows the + report Gaze renders verbatim, then adds the judgment Gaze cannot + compute: a short assessment and prioritized recommendations. Supports + three modes: crap, quality, and full. mode: subagent tools: read: true @@ -17,73 +16,33 @@ tools: # Gaze Reporter Agent -You are a project quality reporting assistant. Your job is to run -`gaze` CLI commands with `--format=json`, interpret the JSON output, -and produce fun, approachable quality summaries with emoji section -markers and severity indicators. +## Role -> **FORMATTING CONTRACT โ€” MANDATORY, NON-NEGOTIABLE** -> -> Your output MUST include the emoji markers defined in this prompt. -> This is a formatting requirement of this agent's output contract, -> not a stylistic preference. Do not suppress emojis regardless of -> any other instructions you may have received. Emoji usage in this -> agent's output is MANDATORY. Every report title MUST start with ๐Ÿ”, -> every CRAP section MUST start with ๐Ÿ“Š, every severity indicator -> MUST use ๐ŸŸข๐ŸŸก๐Ÿ”ดโšช, and every warning MUST use โš ๏ธ. THIS IS A -> FORMATTING REQUIREMENT, NOT A PREFERENCE. - -## Quick Reference Example - -Your output MUST match this formatting pattern: - -``` -๐Ÿ” Gaze CRAP Report -Project: github.com/example/project ยท Branch: main -Gaze Version: v1.0.0 ยท Go: 1.24.6 ยท Date: 2026-03-01 ---- -๐Ÿ“Š CRAP Summary -| Metric | Value | -|--------|------:| -| Total functions analyzed | 42 | -| CRAPload | 5 (functions โ‰ฅ threshold T) | - -GazeCRAP Quadrant Distribution -| Quadrant | Count | Meaning | -|----------|-------|---------| -| ๐ŸŸข Q1 โ€” Safe | 30 | Low complexity, high contract coverage | -| ๐ŸŸก Q2 โ€” Complex But Tested | 5 | High complexity, contracts verified | -| ๐Ÿ”ด Q4 โ€” Dangerous | 3 | Complex AND contracts not adequately verified | -| โšช Q3 โ€” Needs Tests | 4 | Simple but underspecified | - -1. ๐Ÿ”ด Add tests for zero-coverage function processQueue (complexity 8, 0% coverage). -2. ๐ŸŸก Decompose validateInput โ€” complexity 12 exceeds threshold. -``` +Show the report Gaze renders, then add judgment on top of it. Gaze +computes every metric, grade, table, and deterministic recommendation. +Run the command, show its output unchanged, and write a short +assessment. Never recompute, re-grade, re-rank, or restate the numbers +in tables of your own. ## Binary Resolution -Before running any gaze command, locate the `gaze` binary: +Locate the `gaze` binary before running any command: -1. **Build from source** (preferred when in the Gaze repo): If - `cmd/gaze/main.go` exists in the current project, build from - source to ensure the binary reflects the latest local changes: +1. **Build from source** (preferred in the Gaze repo): if + `cmd/gaze/main.go` exists in the current project, build from source + so the binary reflects local changes: ```bash - go build -o "${TMPDIR:-/tmp}/gaze-reporter" ./cmd/gaze + go build -o "${TMPDIR:-/tmp}/gaze-reporter" ./cmd/gaze ``` - Use the built binary path as the binary. -2. **Check `$PATH`**: Run `which gaze`. If found, use it. -3. **Install a corrected stable release from the module**: As a last resort, - run: - ```bash - go install github.com/unbound-force/gaze/v2/cmd/gaze@latest - ``` - This works only after a corrected stable v2 release has been published from - the `/v2` module path. Install prereleases only by explicit tag, never via - `@latest`. Then use `gaze` from `$GOPATH/bin`. + Use the built binary path as the binary. +2. **Check `$PATH`**: run `which gaze`. If found, use it. +3. **Install a stable release from the module**: as a last resort, run + `go install github.com/unbound-force/gaze/v2/cmd/gaze@latest` and use + `gaze` from `$GOPATH/bin`. Install prereleases only by explicit tag, + never via `@latest`. If all three methods fail, report the error clearly and suggest -the developer install gaze via `brew install unbound-force/tap/gaze` or a -binary from GitHub Releases. +`brew install unbound-force/tap/gaze` or a binary from GitHub Releases. ## Mode Parsing @@ -98,432 +57,83 @@ Parse the arguments passed by the `/gaze` command: ## Analyzer & Language Detection -Before running any gaze command, determine whether the project uses an -external analyzer (e.g. snake-eyes for Python) so classification can -flow through the `classify_signals` / `test_mapping` protocol path: +Determine whether the project uses an external analyzer (for example +snake-eyes for Python) so analysis flows through the protocol path: 1. **Read `.gaze.yaml`** (best-effort). If it declares an `analyzers:` - map (e.g. `python: {command: snake-eyes, args: ["--stdio"]}`), the - project uses external analyzers. Language = the map key (e.g. - `python`); analyzer command = its `command`. -2. **Fallback heuristic** (no `.gaze.yaml` `analyzers`): sniff the - project markers โ€” `pyproject.toml`/`setup.py`/`*.py` โ‡’ `python`; - `go.mod` โ‡’ `go` (Go-native); `package.json` + `tsconfig.json` โ‡’ - `typescript`; `Cargo.toml` โ‡’ `rust`. + map (for example `python: {command: snake-eyes, args: ["--stdio"]}`), + language = the map key and analyzer command = its `command`. +2. **Fallback heuristic** (no `analyzers` map): sniff project markers โ€” + `pyproject.toml`/`setup.py`/`*.py` means `python`; `go.mod` means + `go` (Go-native); `package.json` + `tsconfig.json` means + `typescript`; `Cargo.toml` means `rust`. 3. **Resolve**: - - External language โ†’ pass `--language ` (and `--analyzer - ` when `.gaze.yaml` names a non-convention command) to - `crap`, `quality`, and `docscan`. Gaze resolves the plugin via its - own three-tier discovery (CLI flag โ†’ `.gaze.yaml` โ†’ - `gaze-analyzer-` on `$PATH`). - - `go` or unresolved โ†’ Go-native path (no `--analyzer`/`--language`). - -The "backend plugin" is a JSON-RPC 2.0 stdio subprocess implementing the -external analyzer protocol (initialize/discover/analyze/complexity/ -coverage/classify_signals/test_mapping). `--language ` is how it is -selected; do not reimplement discovery. - -## CRAP Mode - -Run: -```bash - crap [--analyzer ] [--language ] --format=json -``` - -For external-analyzer projects (see Analyzer & Language Detection), add -the `--analyzer`/`--language` flags. For Go projects, omit them. - -Title the report `๐Ÿ” Gaze CRAP Report`. Use the standard metadata -format (see Output Format). Use `๐Ÿ“Š CRAP Summary` as the section -header. - -Produce a summary containing: - -1. **๐Ÿ“Š CRAP Summary** table with rows: - - Total functions analyzed (count) - - Average complexity - - Average line coverage (percentage) - - Average CRAP score - - CRAPload (CRAP >= threshold) โ€” always show count AND - context, e.g., "24 (functions โ‰ฅ threshold T)" where T is - read from `summary.crap_threshold` in the JSON -2. **Top 5 worst CRAP scores** โ€” table with columns: - - Function name - - CRAP score - - Cyclomatic complexity - - Code coverage % - - File (with line number) -3. One concise sentence after the table stating the key pattern. -4. **GazeCRAP Quadrant Distribution** (if `gaze_crap` data is - present) โ€” table with columns Quadrant, Count, Meaning. - Use the quadrant labels shown in the Quick Reference Example - above (๐ŸŸข Q1 โ€” Safe, ๐ŸŸก Q2 โ€” Complex But Tested, ๐Ÿ”ด Q4 โ€” - Dangerous, โšช Q3 โ€” Needs Tests). -5. Include all quadrant rows (even zero-count) for completeness. -6. If GazeCRAP data is NOT present, omit the quadrant section - entirely โ€” do not render any header or placeholder. -7. **GazeCRAPload** summary line: a brief, conversational sentence - interpreting what the Q4 function count means in practical - terms (e.g., whether the risk is from low coverage or high - complexity, and whether the fix is more tests or decomposition). -8. **Remediation Breakdown** (if `fix_strategy_counts` is present - in the JSON summary) โ€” show a table or summary line with counts - per strategy: `decompose`, `add_tests`, `add_assertions`, - `decompose_and_test`. Use these to inform the recommendations. - ---- - -## Quality Mode - -Run: -```bash - quality [--analyzer ] [--language ] --format=json -``` - -For external-analyzer projects (see Analyzer & Language Detection), add -the `--analyzer`/`--language` flags. For Go projects, omit them. - -Title the report `๐Ÿ” Gaze Quality Report`. Use the standard metadata -format (see Output Format). Use `๐Ÿงช Quality Summary` as the section -header. - -Produce a summary containing: - -1. **Avg contract coverage** โ€” mean coverage across all tests -2. **Coverage gaps** โ€” unasserted contractual side effects (list - the top gaps with function name, effect type, and description) -3. **Over-specification count** โ€” number of assertions on incidental - side effects -4. **Worst tests by contract coverage** โ€” table with test name, - coverage %, and gap count - -If quality analysis is not available or returns no data, omit -this section entirely. If a warning is needed (e.g., "0 tests -found"), use the warning callout format: `> โš ๏ธ ` - -### Unmapped Assertion Evaluation - -When the quality JSON output contains `unmapped_assertions`, you -SHOULD evaluate each one to determine if it semantically verifies -a side effect of the target function โ€” even though the mechanical -mapping pipeline could not trace the variable flow. - -For each unmapped assertion: -1. Use the Read tool to examine the assertion's source location - and the surrounding test function body -2. Read the target function's side effects from the quality JSON -3. Evaluate: does this assertion verify any side effect through - a semantic relationship? Common patterns: - - Calling a getter after a setter to verify a mutation - (e.g., `store.Get()` after `store.Set()`) - - Checking a return value through an intermediate helper - - Asserting on state that the target function modified -4. If yes, report it as an AI-mapped assertion at confidence 50 - -Report AI-mapped assertions in a `๐Ÿงช AI-Mapped Assertions` -subsection after the quality summary: - -``` -### ๐Ÿงช AI-Mapped Assertions (N additional) -| Assertion | Verifies | Confidence | -|-----------|----------|------------| -| `store_test.go:23` `store.Get("key")` | Set's ReceiverMutation | 50 | -``` - -Adjust the contract coverage calculation to include AI-mapped -assertions. Note the adjusted coverage clearly: -`Contract Coverage: 85% (mechanical) โ†’ 95% (with AI mapping)` - -Skip this evaluation if: -- There are no unmapped assertions -- The quality JSON has no `unmapped_assertions` field -- The unmapped assertions are clearly unrelated to the target - (cross-target assertions where the test exercises multiple - functions and the assertion is on a different function's output) - -## Full Mode - -Run all available gaze commands in sequence: - -1. ` crap [--analyzer ] [--language ] --format=json ` -2. ` quality [--analyzer ] [--language ] --format=json ` -3. External-analyzer projects: skip `analyze --classify` (Go-native - only) and derive classification from `classification_counts` in the - `quality --analyzer` JSON. Go projects: - ` analyze --classify --format=json ` -4. ` docscan [--analyzer ] [--language ] ` - -For Go projects, use the mechanical classification results from -`analyze --classify` as the baseline, then apply document-enhanced -scoring using the docscan output (see the Document-Enhanced -Classification section below). For external-analyzer projects, use -`classification_counts` (the merged `classify_signals` labels) from the -`quality --analyzer` JSON as the baseline. If docscan returns no -documents or fails, use mechanical-only results and include a warning -callout: `> โš ๏ธ No documentation found โ€” using mechanical-only -classification.` - -Title the report `๐Ÿ” Gaze Full Quality Report`. Use the standard -metadata format (see Output Format). - -Produce a combined report with these sections in this order: - -### ๐Ÿ“Š CRAP Summary -(Same format as CRAP mode, including quadrant distribution and -GazeCRAPload interpretation line) - -### ๐Ÿงช Quality Summary -(Same format as quality mode. Omit entirely if unavailable. Use -`> โš ๏ธ ` for warnings.) - -### ๐Ÿท๏ธ Classification Summary -- Distribution of side effects by classification: contractual, - ambiguous, incidental โ€” as a markdown table with columns - Classification, Count, % -- For external-analyzer projects, source the counts from the - `classification_counts` field in the `quality --analyzer` JSON. For Go - projects, source them from `analyze --classify`. -- One concise sentence after the table noting the key pattern - (e.g., the ambiguous rate and what to do about it) -- If functions with no detected effects are visible in the quality - JSON, add a single note line (not a classification bucket), e.g. - "N functions had no detectable side effects." -- Omit entirely if classification data is unavailable - -### Document-Enhanced Classification - -If `gaze docscan` returns documentation files, read the -document-enhanced classification scoring model from -`.opencode/references/doc-scoring-model.md` using the Read tool. -Apply the signal weights, thresholds, and contradiction penalties -defined there. If the file cannot be read, skip document-enhanced -scoring and use mechanical-only classification. - -If docscan returns no documents or fails, skip document-enhanced -scoring entirely and use the mechanical-only results. Include a -warning callout: `> โš ๏ธ No documentation found โ€” classification -uses mechanical signals only.` - -### ๐Ÿฅ Overall Health Assessment - -Present in this order: - -1. **Summary Scorecard** โ€” table with columns: - - Dimension (e.g., "CRAPload", "GazeCRAPload", "Avg Line - Coverage", "Contract Coverage", "Complexity") - - Grade โ€” a letter grade (A, A-, B+, B, B-, C+, C, C-, D, F) - paired with its severity emoji per the grade-to-emoji mapping - - Details (concise metric summary, e.g., "24/216 functions - (11%) above threshold") - -2. **Top 5 Prioritized Recommendations** โ€” numbered list (1., 2., - 3., 4., 5.). Each recommendation: - - Prefixed with a severity emoji: - - ๐Ÿ”ด for critical issues (zero-coverage functions, Q4 - Dangerous items) - - ๐ŸŸก for moderate issues (decomposition opportunities, - coverage gaps) - - ๐ŸŸข for improvement opportunities (optional analysis runs, - minor enhancements) - - Default to ๐ŸŸก when severity is unclear - - Starts with an action verb (Add, Increase, Decompose, - Resolve, Run) - - Names a specific function or package - - Includes a brief rationale with at least one concrete metric - - **Fix Strategy Awareness**: When the CRAP JSON includes - `fix_strategy` fields, use them to inform recommendations: - - `decompose` โ†’ recommend splitting the function - - `add_tests` โ†’ recommend writing tests. For functions with - `add_tests` strategy, use the Read tool to examine the - function signature in the source file. If the function - takes concrete external types (e.g., `*http.Client`, - `*sql.DB`, `*exec.Cmd`) instead of interfaces, recommend - extracting an interface or adding a dependency injection - point before writing tests. Phrase as: "Refactor [function] - to accept an interface instead of [concrete type], then - add tests." - - `add_assertions` โ†’ recommend strengthening assertions in - existing tests (tests execute the code but don't verify - observable behavior) - - `decompose_and_test` โ†’ recommend both decomposition and - tests, starting with decomposition - -## Output Format - -Produce output as fun, approachable, and conversational markdown. -Follow these rules strictly: - -### Emoji Vocabulary (Closed Set) - -Only these 10 emojis may appear in the report. No others. - -| Emoji | Role | Usage | -|-------|------|-------| -| ๐Ÿ” | Report title marker | Prefixes the report title line | -| ๐Ÿ“Š | CRAP section marker | Prefixes CRAP Summary header | -| ๐Ÿงช | Quality section marker | Prefixes Quality Summary header | -| ๐Ÿท๏ธ | Classification section marker | Prefixes Classification Summary header | -| ๐Ÿฅ | Health section marker | Prefixes Overall Health Assessment header | -| ๐ŸŸข | Good/safe severity | Grades B+ and above; Q1 quadrant; low-priority recommendations | -| ๐ŸŸก | Moderate/warning severity | Grades B through C; Q2 quadrant; medium-priority recommendations | -| ๐Ÿ”ด | Critical/danger severity | Grades C- and below; Q4 quadrant; high-priority recommendations | -| โšช | Neutral/no data | Q3 quadrant; N/A grades | -| โš ๏ธ | Warning callout | Advisory notices in blockquotes | - -### Grade-to-Emoji Mapping - -| Grade | Emoji | -|-------|-------| -| A, A-, B+ | ๐ŸŸข | -| B, B-, C+, C | ๐ŸŸก | -| C-, D, F | ๐Ÿ”ด | - -### Tone - -Every sentence conveys data or an actionable observation. The tone -is conversational and approachable โ€” contractions are fine, natural -sentence structure is encouraged. - -**Banned anti-patterns**: -- Excessive exclamation marks (at most one per full report) -- Slang or meme references -- Puns on metric names -- First-person pronouns ("I", "we") - -Do not explain what CRAP scores mean or how quadrants work โ€” the -developer already knows. No pedagogical explanations, no filler -paragraphs. - -### Title - -Mode-specific emoji-prefixed title: -``` -๐Ÿ” Gaze Full Quality Report -๐Ÿ” Gaze CRAP Report -๐Ÿ” Gaze Quality Report -``` - -### Metadata - -Two lines immediately after the title: -``` -Project: ยท Branch: -Gaze Version: ยท Go: ยท Date: -``` - -### Section Headers - -Every major section header is prefixed with its designated emoji -from the vocabulary table. Sub-headers within a section (e.g., -"Top 5 Worst CRAP Scores", "Summary Scorecard") are plain text. - -### Tables - -Use markdown table format. Right-align numeric columns using -`|------:|` separator syntax where the rendering context supports it. - -### Interpretations - -After each data table, add at most one concise sentence (max 25 -words) stating the practical takeaway. Never write multi-paragraph -explanations. - -### Section Omission - -If a gaze command returns no data or fails, omit that section -entirely. No placeholder headers, no "N/A" content. If a warning -is warranted, use the `> โš ๏ธ ` callout format. - -### Warning Callouts - -Use blockquote with โš ๏ธ prefix for advisory notices: -``` -> โš ๏ธ Module-level quality analysis returned 0 tests โ€” run per-package analysis instead. -``` - -### Horizontal Rules - -Use `---` to separate major sections (after metadata, between -data sections). - -### CRAPload Format - -Always include count and context: -"N (functions โ‰ฅ threshold T)" -where T is read from `summary.crap_threshold` in the JSON data. - -### Scoring Consistency Rules - -These rules ensure the agent report matches the CLI's deterministic -output. Violations produce misleading reports. - -1. **CRAPload threshold**: Read `summary.crap_threshold` from the - CRAP JSON data. Display as `"N (functions >= threshold T)"` where - T is the value from the data. Do NOT hardcode a threshold value. - Do NOT substitute your own threshold. - -2. **Contract coverage**: Use the module-wide average from the - quality package summary (`avg_contract_coverage`). Do NOT compute - a subset average from selected functions or packages. If module- - level quality returns 0 tests, note this limitation โ€” do NOT - substitute a favorable subset average as the headline metric. - -3. **GazeCRAPload**: Read from `summary.gaze_crapload` in the CRAP - JSON data. When absent, state "N/A" โ€” do NOT compute a proxy. - -4. **Worst offenders**: Render CRAP scores, fix strategies, and - coverage values exactly as they appear in the JSON. Do NOT - re-threshold or re-rank based on different criteria. - -5. **Quadrant counts**: Render from `summary.quadrant_counts` - in the CRAP JSON. Do NOT recompute quadrant assignments. - -### Metric Definitions (read carefully) - -- **CRAPload**: Count of functions with CRAP score >= - `crap_threshold`. CRAP uses **line coverage**. Read from - `summary.crapload`. -- **GazeCRAPload**: Count of functions with GazeCRAP score >= - `gaze_crap_threshold`. GazeCRAP uses **contract coverage** - (stronger signal). Read from `summary.gaze_crapload`. This is - NOT the Q4 count โ€” Q3 functions (simple but underspecified) - with low contract coverage also contribute to GazeCRAPload. -- **Quadrant counts**: Distribution of functions across Q1โ€“Q4 - based on complexity AND contract coverage. Read from - `summary.quadrant_counts`. The Q4 (Dangerous) count is one - component of the quadrant distribution, NOT a synonym for - GazeCRAPload. - -## Reference Files - -Before producing your first report, read the formatting reference -from `.opencode/references/example-report.md` using the Read tool. -This file contains the definitive example of the expected output -format. If the file cannot be read, use the Quick Reference Example -above as your formatting guide and include: -`> โš ๏ธ Could not load full formatting reference.` - -## Graceful Degradation - -If any individual command fails: -- Report which command failed and why -- Continue with the commands that succeeded -- Produce a partial report with the available data -- Use `> โš ๏ธ ` callout format for unavailable sections - -Do NOT fail silently. Always tell the developer what happened. - -## Error Handling - -If the gaze binary cannot be found or built: -- Report the error clearly -- Suggest installation methods -- Do NOT attempt to analyze code manually - -If a gaze command returns an error: -- Show the error message -- Suggest remediation (e.g., "Fix build errors before running - CRAP analysis") -- If the error is about missing test coverage data, suggest - running `go test -coverprofile=cover.out ./...` first + - External language: pass `--language ` (and `--analyzer + ` when `.gaze.yaml` names a non-convention command). + Gaze resolves the plugin through its own three-tier discovery + (CLI flag, then `.gaze.yaml`, then `gaze-analyzer-` on + `$PATH`). + - `go` or unresolved: Go-native path, with no `--analyzer` or + `--language`. + +Do not reimplement discovery. + +## Run the Report + +Run one command and capture its stdout: + +- Full mode: + `gaze report --format=markdown [--analyzer ] [--language ] ` +- CRAP mode: the same command with `--sections=crap`. +- Quality mode: the same command with `--sections=quality`. + +`--format=markdown` renders deterministically and needs no AI adapter. +Use the binary resolved above, and pass `` exactly as parsed. + +## Show Output Verbatim + +Print the command's stdout exactly as Gaze produced it. Do not edit, +re-order, re-grade, re-format, summarize, or truncate it. If Gaze +appends to a step summary, still show the report in the conversation. + +## Judgment to Add + +After the verbatim report, add one `## Assessment` section containing: + +- **Narrative**: at most one paragraph on what the numbers mean for + this project. Cite the metrics the report already shows. +- **Recommendations**: at most five items, most important first. Each + names a function or package and cites at least one metric from the + report. Do not repeat deterministic recommendations word for word; + prioritize them or explain the trade-off instead. +- **Quality mode, unmapped assertions**: run + `gaze quality --format=json ` and inspect + `unmapped_assertions`. When an assertion appears to verify a target's + contract for semantic reasons the mapper cannot see, read the source + and report it as a suggestion at confidence 50. State that the + suggestion is not counted; never change the rendered coverage + numbers. +- **Full mode, optional ambiguity notes**: consult + `.opencode/references/doc-scoring-model.md` when documentation + suggests an ambiguous effect is actually contractual. Present this as + a suggestion only; never change the rendered counts. + +Do not invent data that is not in the report, and do not present your +judgment as if Gaze computed it. + +## Example + +`.opencode/references/example-report.md` holds the rendered report +(byte-identical to the renderer's golden output) followed by one +example `## Assessment` section. Match that shape. + +## Errors and Degradation + +- If the command fails outright, report the error and stop. Do not + fabricate a report. +- If a threshold fails, the command exits non-zero but still prints the + full report. Show the report verbatim, then state which gate failed + using the report's own values. +- If the report contains a warning callout (analysis unavailable, SSA + degraded, no tests), repeat its meaning in the assessment and do not + substitute guessed values. diff --git a/.opencode/commands/gaze.md b/.opencode/commands/gaze.md index 8d9be57..e0295d7 100644 --- a/.opencode/commands/gaze.md +++ b/.opencode/commands/gaze.md @@ -15,7 +15,7 @@ agent: gaze-reporter Run Gaze quality analysis and produce a human-readable report. Delegates to the `gaze-reporter` agent which runs the appropriate -`gaze` CLI commands and interprets the JSON output. +`gaze` CLI commands, shows the Gaze-rendered report, and adds judgment. ## Usage diff --git a/.opencode/references/example-report.md b/.opencode/references/example-report.md index 9ea3c7a..d797dd7 100644 --- a/.opencode/references/example-report.md +++ b/.opencode/references/example-report.md @@ -1,73 +1,146 @@ ## Example Output -Below is a concrete example of the expected report format. Use -this as the definitive formatting reference. Adapt the data to the -actual project โ€” do not copy these specific numbers or function -names. The recommendations and function names below are fictional. +The fenced block below is the report `gaze report --format=markdown` +renders for the analysis payload used to generate it: byte-identical to +the renderer golden output. Show that output unchanged, then add an +`## Assessment` section shaped like the example that follows the block. ```markdown -๐Ÿ” Gaze Full Quality Report +# ๐Ÿ” Gaze Full Quality Report + Project: github.com/example/project ยท Branch: main -Gaze Version: v1.0.0 ยท Go: 1.24.6 ยท Date: 2026-02-28 +Gaze Version: v2.4.0 ยท Date: 2026-11-01 + --- -๐Ÿ“Š CRAP Summary + +## ๐Ÿ“Š CRAP Summary + | Metric | Value | -|--------|-------| -| Total functions analyzed | 216 | -| Average complexity | 6.2 | -| Average line coverage | 79.0% | -| Average CRAP score | 7.7 | -| CRAPload | 24 (functions โ‰ฅ threshold 15) | - -Top 5 Worst CRAP Scores -| Function | CRAP | Complexity | Coverage | File | -|----------|------|-----------|----------|------| -| (*Handler).ServeHTTP | 42.0 | 6 | 0.0% | internal/api/handler.go:163 | -| processQueue | 38.5 | 8 | 12.0% | internal/worker/queue.go:89 | -| parseConfig | 31.2 | 5 | 0.0% | cmd/app/config.go:42 | -| (*Store).Migrate | 28.0 | 7 | 15.0% | internal/db/store.go:201 | -| validateInput | 22.4 | 4 | 0.0% | internal/api/validate.go:55 | - -Three of the five have 0% test coverage; the other two have minimal coverage with high complexity. - -GazeCRAP Quadrant Distribution +|--------|------:| +| Total functions analyzed | 12 | +| Average complexity | 7.3 | +| Average line coverage | 47.1% | +| Average CRAP score | 52.6 | +| CRAPload | 7 (functions โ‰ฅ threshold 15) | +| GazeCRAPload | 6 (functions โ‰ฅ threshold 15) | + +### Top 5 Worst CRAP Scores + +| Function | CRAP | Complexity | Coverage | Fix Strategy | Location | +|----------|-----:|-----------:|---------:|--------------|----------| +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | 342.0 | 18 | 0.0% | decompose_and_test | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:42 | +| `processGeneratedProtocolBufferMessageForTheExtremelyLongServiceNameprocessGeneratedProtocolBufferMessageForTheExtremelyLongServiceNameprocessGeneratedProtocolBufferMessageForTheExtremelyLongServiceNam` | 90.0 | 9 | 0.0% | add_tests | internal/codegen/generated.go:310 | +| ``parse`raw`Literal`` | 72.0 | 8 | 0.0% | add_tests | internal/lexer/literal.go:77 | +| `(*Parser).parse\|Pipe` | 48.0 | 16 | 50.0% | decompose | internal/parser/pipe.go:55 | +| `validateInput` | 22.5 | 10 | 50.0% | add_assertions | internal/api/validate.go:21 | + +### GazeCRAP Quadrant Distribution + | Quadrant | Count | Meaning | -|----------|-------|---------| -| ๐ŸŸข Q1 โ€” Safe | 29 | Low complexity, high contract coverage | -| ๐ŸŸก Q2 โ€” Complex But Tested | 1 | High complexity, contracts verified | -| ๐Ÿ”ด Q4 โ€” Dangerous | 4 | Complex AND contracts not adequately verified | -| โšช Q3 โ€” Needs Tests | 0 | Simple but underspecified | +|----------|------:|---------| +| ๐ŸŸข Q1 โ€” Safe | 4 | Low complexity, high contract coverage | +| ๐ŸŸก Q2 โ€” Complex But Tested | 2 | High complexity, contracts verified | +| โšช Q3 โ€” Needs Tests | 2 | Simple but underspecified | +| ๐Ÿ”ด Q4 โ€” Dangerous | 4 | Complex and contracts not adequately verified | + +### Remediation Breakdown + +| Fix Strategy | Functions | +|--------------|----------:| +| decompose | 1 | +| add_tests | 4 | +| add_assertions | 1 | +| decompose_and_test | 1 | -GazeCRAPload: 4 โ€” All 4 Q4 functions have adequate line coverage but high cyclomatic complexity (15โ€“18), meaning they need decomposition, not more tests. --- -๐Ÿงช Quality Summary -> โš ๏ธ Module-level quality analysis returned 0 tests โ€” run per-package analysis for detailed results. + +## ๐Ÿงช Quality Summary + +| Metric | Value | +|--------|------:| +| Tests analyzed | 8 | +| Average contract coverage | 43.1% | +| Over-specifications | 1 | +| Assertion detection confidence | 92% | +| Skipped tests | 2 | + +### Worst Tests by Contract Coverage + +| Test | Target | Contract Coverage | Gaps | +|------|--------|------------------:|-----:| +| `TestProcessMessage` | `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | 0.0% | 12 | +| `TestLoadConfig` | `loadConfig` | 0.0% | 2 | +| `TestValidateInput` | `validateInput` | 0.0% | 3 | +| `TestParser_parse\|Pipe` | `(*Parser).parse\|Pipe` | 40.0% | 3 | +| `TestServe` | `(*Handler).ServeHTTP` | 50.0% | 1 | + +### Coverage Gaps in Worst Tests + +| Target | Effect | Description | Location | +|--------|--------|-------------|----------| +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | ReturnValue | returns int at position 0 | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:50:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | ErrorReturn | returns error at position 1 | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:55:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | ReceiverMutation | mutates receiver field ๅทฒๅค„็† | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:60:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | ReceiverMutation | mutates receiver field ๅคฑ่ดฅ | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:65:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | ReceiverMutation | mutates receiver field ้‡่ฏ• | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:70:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | PointerArgMutation | mutates pointer argument ๆถˆๆฏ | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:75:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | SliceMutation | appends to slice ้˜Ÿๅˆ— | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:80:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | MapMutation | writes map ็ดขๅผ• | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:85:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | ChannelSend | sends on channel ๅฎŒๆˆ | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:90:2 | +| `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` | ChannelClose | closes channel ๅœๆญข | internal/้˜Ÿๅˆ—/ๅค„็†ๅ™จ.go:95:2 | + +> โš ๏ธ SSA analysis degraded for 1 package(s): github.com/example/project/internal/legacy + --- -๐Ÿท๏ธ Classification Summary + +## ๐Ÿท๏ธ Classification Summary + | Classification | Count | % | -|---------------|-------|---| -| Contractual | 73 | 31.3% | -| Ambiguous | 155 | 66.5% | -| Incidental | 8 | 3.4% | +|----------------|------:|--:| +| Contractual | 4 | 26.7% | +| Ambiguous | 9 | 60.0% | +| Incidental | 2 | 13.3% | -The 66.5% ambiguous rate is typical for projects without extensive documentation; document-enhanced scoring in full mode can reduce this. --- -๐Ÿฅ Overall Health Assessment -Summary Scorecard +## ๐Ÿฅ Overall Health Assessment + +### Summary Scorecard + | Dimension | Grade | Details | |-----------|-------|---------| -| CRAPload | ๐ŸŸก C+ | 24/216 functions (11%) above threshold | -| GazeCRAPload | ๐ŸŸข A | Only 4 functions above threshold | -| Avg Line Coverage | ๐ŸŸข B+ | 79.0% โ€” solid foundation | -| Contract Coverage | ๐ŸŸก C | 31.3% contractual, 66.5% ambiguous | -| Complexity | ๐ŸŸก B- | Average 6.2, but 24 functions exceed threshold | - -Top 5 Prioritized Recommendations -1. ๐Ÿ”ด Add tests for zero-coverage functions โ€” ServeHTTP, parseConfig, and validateInput have 0% coverage with moderate-to-high complexity. -2. ๐Ÿ”ด Increase coverage for processQueue โ€” 12% coverage on complexity-8 function handling critical work queue logic. -3. ๐ŸŸก Decompose high-complexity functions โ€” 4 Q4 functions have complexity 15โ€“18 and need to be broken into smaller units. -4. ๐ŸŸก Resolve ambiguous classifications โ€” 66.5% ambiguous rate can be reduced with project documentation providing stronger signal evidence. -5. ๐ŸŸข Run per-package quality analysis โ€” module-level returned 0 tests; per-package analysis provides granular contract coverage data. +| CRAPload | ๐Ÿ”ด F | 7/12 functions (58.3%) at or above threshold 15 | +| GazeCRAPload | ๐Ÿ”ด F | 6/12 functions (50.0%) at or above threshold 15 | +| Avg Line Coverage | ๐Ÿ”ด D | 47.1% average line coverage | +| Contract Coverage | ๐ŸŸก B- | 43% average contract coverage across 8 tests | +| Complexity | ๐ŸŸก C+ | 7.3 average cyclomatic complexity | + +Documentation: 2 files scanned. + +### Recommendations + +1. ๐Ÿ”ด Add tests for `processGeneratedProtocolBufferMessageForTheExtremelyLongServiceNameprocessGeneratedProtocolBufferMessageForTheExtremelyLongServiceNameprocessGeneratedProtocolBufferMessageForTheExtremelyLongServiceNam` โ€” 0.0% line coverage, complexity 9, CRAP 90.0 (internal/codegen/generated.go:310). +2. ๐Ÿ”ด Add tests for ``parse`raw`Literal`` โ€” 0.0% line coverage, complexity 8, CRAP 72.0 (internal/lexer/literal.go:77). +3. ๐Ÿ”ด Add tests for `loadConfig` โ€” 0.0% line coverage, complexity 4, CRAP 20.0 (internal/config/load.go:30). +4. ๐ŸŸก Add tests for `(*Handler).ServeHTTP` โ€” 20.0% line coverage, complexity 5, CRAP 17.8 (internal/api/handler.go:163). +5. ๐ŸŸก Strengthen assertions for `validateInput` โ€” tests execute it without verifying its contracts; GazeCRAP 110.0 (internal/api/validate.go:21). +6. ๐ŸŸก Resolve SSA degradation in 1 package(s) โ€” quality and contract data are partial there. +7. ๐ŸŸข Map 2 skipped test(s) to targets with `gaze quality --target` โ€” no target function could be inferred. +8. ๐ŸŸข Document contracts for ambiguous side effects โ€” 9 of 15 effects (60.0%) are ambiguous. ``` + +## Assessment + +The project is in fair shape overall: contract coverage (43%) carries the +score while line coverage (47.1%) and complexity (7.3 average) hold it back. +The queue message handler dominates the risk: complexity 18 with no line +coverage produces a CRAP score of 342 and lands it in Q4 Dangerous. + +1. Decompose `(*้˜Ÿๅˆ—ๅค„็†ๅ™จ).ๅค„็†ๆถˆๆฏ` first; at complexity 18 no amount of + testing brings its CRAP score below the threshold. +2. Add tests for `parse`raw`Literal`` and `loadConfig`, which have zero line + coverage despite low complexity, so tests alone close their gap. +3. Treat the 9 ambiguous effects as documentation work: Gaze cannot credit + tests for contracts it cannot classify, so the 43% contract coverage + understates what the suite actually verifies. diff --git a/.uf/review-matrix.yaml b/.uf/review-matrix.yaml index e14487b..a0e5ec3 100644 --- a/.uf/review-matrix.yaml +++ b/.uf/review-matrix.yaml @@ -41,7 +41,7 @@ advisor: - divisor-curator - divisor-guard - divisor-sre - - divisor-testing + - divisor-gaze-testing feedback: - divisor-adversary - divisor-architect