[repository-quality] Compiler Error Hint Rendering Gap

[github-actions[bot]]

Analysis Date: 2026-06-08
Focus Area: Compiler Error Hint Rendering Gap
Strategy Type: Custom
Custom Area: Yes — gh-aw is a markdown-to-YAML compiler; diagnostic quality is user-facing and directly impacts developer experience. A well-implemented Hint rendering pipeline exists but is completely bypassed at all 66 production call sites.

Executive Summary

pkg/console defines a CompilerError.Hint field that renders as a cyan-styled hint: line in the terminal, modelled after Rust/Go compiler diagnostics. Tests confirm it works correctly. But analysis shows that zero production call sites ever set this field — every formatCompilerError* helper ignores Hint entirely.

Meanwhile, 71 of 72 NewValidationError calls supply a non-empty Suggestion string. These suggestions currently reach users as unformatted plain text appended to the error body (\nSuggestion: use ...) via WorkflowValidationError.Error(). The styled hint: rendering path is dead code in production.

The schema compiler (pkg/parser/schema_compiler.go) has the same problem: generateSchemaBasedSuggestions returns fix guidance that is concatenated into the message string with a . separator instead of flowing through the Hint channel.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Add hint parameter to formatCompilerErrorWithPosition and formatCompilerErrorWithContext

Priority: High
Estimated Effort: Small
Focus Area: Compiler Error Hint Rendering

Description: formatCompilerErrorWithPosition (9 call sites) and formatCompilerErrorWithContext (3 call sites) construct console.CompilerError but never populate the Hint field. Add a hint string parameter to both functions so callers can pass fix guidance through. Update all 12 call sites to pass an empty string "" as the new parameter (no behaviour change yet — subsequent tasks wire in real hints).

Acceptance Criteria:

• formatCompilerErrorWithPosition signature updated to include hint string parameter
• formatCompilerErrorWithContext signature updated to include hint string parameter
• console.CompilerError{..., Hint: hint} populated in both functions
• All 12 existing callers updated to pass "" as hint (preserving current behaviour)
• pkg/workflow/compiler_error_formatter_test.go has a test verifying a non-empty hint appears in the formatted output
• make fmt and make build pass

Code Region: pkg/workflow/compiler_error_formatter.go

---

Task 2: Bridge WorkflowValidationError.Suggestion to CompilerError.Hint in formatCompilerError

Priority: High
Estimated Effort: Medium
Focus Area: Compiler Error Hint Rendering

Description: formatCompilerError already uses errors.As(cause, &vErr) to promote source position from WorkflowValidationError. Extend this to also extract vErr.Suggestion and pass it as the new hint parameter (from Task 1) to formatCompilerErrorWithPosition. Do the same for *ConfigurationError and *OperationError. Then remove \nSuggestion: ... from the three Error() methods in workflow_errors.go to prevent double-rendering — the suggestion now surfaces exclusively as a styled hint: line.

Acceptance Criteria:

• formatCompilerError extracts Suggestion from *WorkflowValidationError, *ConfigurationError, *OperationError via errors.As and passes it as hint
• WorkflowValidationError.Error() no longer appends \nSuggestion: ... to its string
• ConfigurationError.Error() and OperationError.Error() likewise no longer append suggestion
• A test in pkg/workflow/compiler_error_formatter_test.go verifies that a WorkflowValidationError with Suggestion: "try foo" produces "hint: try foo" in the final compiler error, and that "Suggestion:" does NOT appear in the output
• make fmt && go test ./pkg/workflow/... pass

Code Region: pkg/workflow/compiler_error_formatter.go, pkg/workflow/workflow_errors.go

---

Task 3: Promote schema suggestion strings to CompilerError.Hint in schema_compiler.go

Priority: Medium
Estimated Effort: Small
Focus Area: Compiler Error Hint Rendering

Description: In pkg/parser/schema_compiler.go, buildFallbackSchemaValidationError and the main validation path call generateSchemaBasedSuggestions / appendKnownFieldValidValuesHint and concatenate the result to the message string with a . separator. The local formatCompilerErrorWithLocation function has no hint parameter. Add a hint string parameter to it, and update callers to pass suggestion text as hint rather than appending it to the message.

Acceptance Criteria:

• formatCompilerErrorWithLocation in pkg/parser/schema_compiler.go gains a hint string parameter and sets Hint: hint on console.CompilerError
• buildFallbackSchemaValidationError passes suggestions as hint, not appended to message
• Main schema validation path (pathInfo branch) passes suggestion string as hint
• Existing parser tests updated for the changed output format (suggestion on hint: line vs inline)
• make fmt && go test ./pkg/parser/... pass

Code Region: pkg/parser/schema_compiler.go

---

Task 4: Add end-to-end tests for the Suggestion-to-Hint rendering path

Priority: Medium
Estimated Effort: Small
Focus Area: Compiler Error Hint Rendering

Description: The pkg/console/golden_test.go tests hint rendering with a static CompilerError{Hint: "..."} literal, but no test exercises the production chain: NewValidationError → formatCompilerError → styled hint: output. Add table-driven tests to pkg/workflow/compiler_error_formatter_test.go covering the full path and guarding against double-rendering regression.

Acceptance Criteria:

• Test: validation error with non-empty Suggestion → formatted output contains "hint:" line
• Test: validation error with empty Suggestion → formatted output contains no "hint:" line
• Test: ConfigurationError with Suggestion → formatted output contains "hint:" line
• Regression test: formatted output must NOT contain the literal substring "Suggestion:"
• Build tag //go:build !integration present on test file
• go test ./pkg/workflow/... -run TestFormatCompilerError passes

Code Region: pkg/workflow/compiler_error_formatter_test.go

---

📊 Historical Context

---

🎯 Recommendations

Immediate Actions (This Week)

1. Task 1 (Add hint parameter to formatters) — Priority: High — pure refactor, zero user-visible change, unblocks Tasks 2–3
2. Task 2 (Bridge WorkflowValidationError.Suggestion to Hint) — Priority: High — 71 validation errors gain styled hint output

Short-term Actions (This Month)

1. Task 3 (Schema suggestion promotion) — Priority: Medium — schema errors gain same hint quality as validation errors
2. Task 4 (End-to-end tests for hint path) — Priority: Medium — locks in the fix and prevents regression

Long-term Actions (This Quarter)

1. Audit remaining formatCompilerError calls that pass nil cause with no position — consider frontmatter field-line lookup to promote position accuracy

---

📈 Success Metrics

• CompilerError.Hint set in production: 0 → ≥ 71 (one per NewValidationError call with Suggestion)
• "Suggestion:" occurrences in terminal output: present (unformatted) → 0
• WorkflowValidationError.Error() includes suggestion in string: Yes → No
• Schema suggestion in message suffix: ~4 sites → 0

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 2 weeks after Tasks 1–2 land

---

References: §27143661020

Generated by Repository Quality Improvement Agent
Next analysis: 2026-06-09 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · 546.8 AIC · ⌖ 14.3 AIC · ⊞ 22.1K · ◷

• expires on Jun 9, 2026, 6:27 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #38123.