[repository-quality] Repository Quality Improvement Report - Exported Symbol Documentation Debt (2026-04-13)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Exported Symbol Documentation Debt

Analysis Date: 2026-04-13
Focus Area: Exported Symbol Documentation Debt
Strategy Type: Custom (first run — no prior history)
Custom Area: Yes — chosen because gh-aw has 675 Go source files and a large public API surface area (parser, workflow, console, constants, cli) that is actively used by contributors and AI agents. Undocumented exported symbols reduce IDE experience quality, slow contributor onboarding, and make AI-assisted development less effective.

Executive Summary

Analysis of the repository's Go source files reveals 219 exported functions and 90 exported types lacking Go doc comments, concentrated in a handful of high-traffic packages. The most impactful gaps are in pkg/constants (12 semantic type aliases with no docs), pkg/console/console_wasm.go (20 Format* functions mirroring the non-wasm API), pkg/workflow/js.go (12 public stub getters), and pkg/parser (15+ frequently-called URL/cron/hash functions).

The repository has excellent test coverage (test LOC is 2.17× source LOC) and very few TODO/FIXME items (7 total), showing strong engineering discipline. Documentation of exported symbols is the next natural quality step — it directly improves IDE hover documentation, godoc output, and AI-assisted code navigation.

The five tasks below are scoped for a Copilot coding agent and range from 30-minute quick wins (constants type aliases) to medium efforts (parser URL helpers).

Full Analysis Report

Focus Area: Exported Symbol Documentation Debt

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total Go source files (non-test)	675	i️
Exported functions missing doc comment	~219	⚠️
Exported types missing doc comment	~90	⚠️
Test LOC / Source LOC ratio	217%	✅
TODO/FIXME/HACK comments	7	✅
Files > 600 lines	58	⚠️
Packages with no tests	2 (tty, types)	✅ (trivial packages)

Hot spots by file:

File	Undocumented Exported Items
pkg/console/console_wasm.go	20 functions
pkg/workflow/js.go	12 functions
pkg/workflow/engine_helpers.go	9 functions
pkg/workflow/secret_extraction.go	7 functions
pkg/stringutil/sanitize.go	5 functions
pkg/semverutil/semverutil.go	5 functions
pkg/constants/*.go	12 types
pkg/parser/github_urls.go	3 functions
pkg/parser/schedule_cron_detection.go	3 functions

Findings

Strengths

• Excellent package-level doc.go coverage across most packages
• Engine helper files have rich file-level header comments describing purpose and organization
• secret_extraction.go uses well-formed example doc comments for complex functions
• semverutil has clear, complete doc comments on every exported function
• Very low technical debt signal (7 TODO items in 675 files)

Areas for Improvement

• pkg/constants — All 12 semantic type aliases (Version, ModelName, URL, DocURL, JobName, StepID, MCPServerID, EngineName, LineLength, CommandPrefix, WorkflowID, FeatureFlag) lack doc comments. These types are referenced throughout the codebase and deserve at minimum a one-sentence description of purpose and usage
• pkg/console/console_wasm.go — 20 Format* functions are wasm mirror implementations of the console package. While the non-wasm versions are documented, the wasm counterparts have no docs, creating an inconsistency visible in wasm build contexts
• pkg/workflow/js.go — 12 Get* stub getter functions returned after removing embedded scripts have no explanation of why they return empty/placeholder strings, nor guidance for callers
• pkg/parser — Several URL-parsing and cron-detection helpers (ParseGitHubURL, ParseRunURLExtended, IsDailyCron, etc.) are missing doc comments despite being part of the public parser API

Detailed Analysis

The AGENTS.md documentation calls out that "Only comment code that needs a bit of clarification. Do not comment otherwise." However, Go's godoc tool and IDE tooling rely specifically on exported symbol doc comments to surface hover documentation and generate package reference pages. Functions like LevenshteinDistance, QuoteCronExpressions, and GetGitHubHostForRepo are genuinely non-obvious in intent or expected input format, making documentation particularly valuable here.

The pkg/constants semantic type aliases are a special case: they exist to provide type safety and carry semantic meaning (e.g., WorkflowID vs. string), but without doc comments a new contributor cannot easily understand when to use each type vs. the underlying primitive.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following 5 tasks are designed for GitHub Copilot coding agent execution. Split these into individual work items for processing. Each task is self-contained with a specific file scope.

Improvement Tasks

---

Task 1: Document Semantic Type Aliases in pkg/constants

Priority: High
Estimated Effort: Small
Focus Area: Exported Symbol Documentation Debt

Description:
All 12 semantic type aliases in pkg/constants lack Go doc comments. These types (Version, ModelName, URL, DocURL, JobName, StepID, MCPServerID, EngineName, LineLength, CommandPrefix, WorkflowID, FeatureFlag) are used extensively across the codebase as the canonical domain types and deserve clear documentation explaining their purpose and usage guidance.

Acceptance Criteria:

• All 12 exported type declarations in pkg/constants/*.go have a Go doc comment starting with the type name
• Each comment explains what values the type represents and when to use it over the underlying primitive
• make lint passes with no new issues
• make fmt has been run

Code Region: pkg/constants/version_constants.go, pkg/constants/url_constants.go, pkg/constants/job_constants.go, pkg/constants/engine_constants.go, pkg/constants/constants.go, pkg/constants/feature_constants.go

Add Go doc comments to all 12 exported semantic type alias declarations in `pkg/constants/`. The files involved are:
- `pkg/constants/version_constants.go` — `Version`, `ModelName`
- `pkg/constants/url_constants.go` — `URL`, `DocURL`
- `pkg/constants/job_constants.go` — `JobName`, `StepID`, `MCPServerID`
- `pkg/constants/engine_constants.go` — `EngineName`
- `pkg/constants/constants.go` — `LineLength`, `CommandPrefix`, `WorkflowID`
- `pkg/constants/feature_constants.go` — `FeatureFlag`

For each type, add a doc comment immediately above the `type` declaration that:
1. Starts with the type name (Go convention)
2. Describes what the type represents
3. Explains when to use this type instead of the underlying primitive (string/int)

Example of the expected style:
```go
// Version represents a semantic version string (e.g., "v1.2.3" or "latest").
// Use this type for tool/engine version fields to distinguish version strings from
// arbitrary strings at compile time.
type Version string
```

After adding comments, run `make fmt` and `make lint` to verify no issues were introduced. Do NOT add tests — this is a documentation-only change.

---

Task 2: Document Exported Functions in pkg/workflow/js.go

Priority: High
Estimated Effort: Small
Focus Area: Exported Symbol Documentation Debt

Description:
pkg/workflow/js.go exposes 12 public Get* functions that return empty strings or placeholder values because embedded scripts were removed (scripts are now provided by actions/setup at runtime). These functions have no doc comments explaining why they exist, why they return empty/stub values, and what callers should do instead.

Acceptance Criteria:

• All exported Get* functions in pkg/workflow/js.go have Go doc comments
• Comments explain that embedded scripts were removed and scripts are loaded at runtime via actions/setup
• The special case of GetLogParserScript (returns "EXTERNAL_SCRIPT" placeholder) is clearly documented
• make lint passes

Code Region: pkg/workflow/js.go

Add Go doc comments to all exported `Get*` functions in `pkg/workflow/js.go`. These functions currently return empty strings or placeholder values because embedded JavaScript scripts were removed — scripts are now provided by the `actions/setup` action at runtime from `actions/setup/js/`.

For each function, add a doc comment that:
1. Starts with the function name (Go convention)
2. Explains that the function returns an empty string (or placeholder) because embedded scripts were removed
3. Notes that the actual script is loaded at runtime by `actions/setup` from `actions/setup/js/`
4. For `GetLogParserScript`, document that it returns the `"EXTERNAL_SCRIPT"` sentinel value to signal that an external runtime script should be used

Example style:
```go
// GetJavaScriptSources returns an empty map because embedded JavaScript scripts
// have been removed. Scripts are provided at runtime by the actions/setup action,
// which copies them from actions/setup/js/ to /tmp/gh-aw/actions/.
func GetJavaScriptSources() map[string]string {
    return map[string]string{}
}
```

Run `make fmt` and `make lint` after making the changes.

---

Task 3: Document Exported Functions in pkg/stringutil/sanitize.go and pkg/workflow/engine_helpers.go

Priority: Medium
Estimated Effort: Small
Focus Area: Exported Symbol Documentation Debt

Description:
pkg/stringutil/sanitize.go has 5 exported functions with no doc comments, and pkg/workflow/engine_helpers.go has 9 exported functions missing docs (despite having an excellent file-level package doc). Adding function-level comments fills the gap that the file header doesn't cover.

Acceptance Criteria:

• All exported functions in pkg/stringutil/sanitize.go have Go doc comments
• All exported functions in pkg/workflow/engine_helpers.go that currently lack doc comments have been documented
• Comments describe parameters, return values for non-obvious functions
• make lint passes

Code Region: pkg/stringutil/sanitize.go, pkg/workflow/engine_helpers.go

Add Go doc comments to the exported functions in two files:

**1. pkg/stringutil/sanitize.go**
Add doc comments to all 5 exported functions. Each comment should describe what the function does, any notable sanitization rules or edge cases, and the expected input/output.

**2. pkg/workflow/engine_helpers.go**
This file already has an excellent file-level header comment. Add individual function doc comments to the ~9 exported functions that currently lack them (e.g., `GenerateAgentInstallSteps`, `GenerateNpmInstallStep`, `GenerateEngineDependenciesInstallStep`, `GetClaudeSystemPrompt`). Each comment should describe the purpose of the function and any key parameters.

After making changes, run `make fmt` and `make lint` to verify correctness.

---

Task 4: Document Exported URL and Cron Helper Functions in pkg/parser

Priority: Medium
Estimated Effort: Small
Focus Area: Exported Symbol Documentation Debt

Description:
pkg/parser exposes several exported utility functions used both internally and potentially by external consumers, particularly URL parsing and cron schedule detection functions. These lack doc comments despite being non-trivial in behavior.

Acceptance Criteria:

• ParseGitHubURL, ParseRunURLExtended, ParseRepoFileURL in pkg/parser/github_urls.go have doc comments with example URLs in comments
• IsDailyCron, IsHourlyCron, IsWeeklyCron in pkg/parser/schedule_cron_detection.go have doc comments describing what cron patterns they match
• LevenshteinDistance in pkg/parser/schema_suggestions.go has a doc comment
• QuoteCronExpressions in pkg/parser/workflow_update.go has a doc comment
• make lint passes

Code Region: pkg/parser/github_urls.go, pkg/parser/schedule_cron_detection.go, pkg/parser/schema_suggestions.go, pkg/parser/workflow_update.go

Add Go doc comments to exported functions in `pkg/parser` that currently lack them:

**pkg/parser/github_urls.go**:
- `ParseGitHubURL` — document accepted URL formats (repo URL, PR URL, run URL, etc.) and what `GitHubURLComponents` fields are populated for each
- `ParseRunURLExtended` — document the extended/looser parsing vs. strict `ParseGitHubURL`
- `ParseRepoFileURL` — document the expected URL format (e.g., `https://github.com/owner/repo/blob/ref/path`)

**pkg/parser/schedule_cron_detection.go**:
- `IsDailyCron` — describe which cron patterns qualify as "daily" (runs once per day)
- `IsHourlyCron` — describe which cron patterns qualify as "hourly"
- `IsWeeklyCron` — describe which cron patterns qualify as "weekly"

**pkg/parser/schema_suggestions.go**:
- `LevenshteinDistance` — standard algorithm description with note that it's used for schema key suggestions

**pkg/parser/workflow_update.go**:
- `QuoteCronExpressions` — explain why cron expressions need quoting in YAML (YAML parser ambiguity) and what transformations are applied

After making changes, run `make fmt` and `make lint`.

---

Task 5: Document Format* Functions in pkg/console/console_wasm.go

Priority: Low
Estimated Effort: Small
Focus Area: Exported Symbol Documentation Debt

Description:
pkg/console/console_wasm.go has 20 exported Format* functions that are wasm-target implementations mirroring the non-wasm console package API. These functions have no doc comments, creating an inconsistency with the non-wasm versions. Since this is a wasm build target, a brief note that these are simplified wasm-compatible implementations would be helpful.

Acceptance Criteria:

• All exported Format* functions in pkg/console/console_wasm.go have doc comments
• Comments note that this is the wasm implementation (simplified, without terminal color codes)
• make lint passes

Code Region: pkg/console/console_wasm.go

Add Go doc comments to the 20 exported `Format*` (and other exported) functions in `pkg/console/console_wasm.go`. These are wasm-target implementations of the console formatting API that strip terminal color/style codes for wasm build contexts.

For each function:
1. Add a one-line doc comment starting with the function name
2. Note that this is the wasm implementation (returns plain text without ANSI codes)
3. Reference the non-wasm counterpart in `pkg/console/console.go` if helpful

Example:
```go
// FormatSuccessMessage returns a plain-text success message for wasm build targets.
// Unlike the non-wasm version, no ANSI color codes or terminal formatting are applied.
func FormatSuccessMessage(message string) string { return "✓ " + message }
```

After changes, run `make fmt` and `make lint`.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-13	Exported Symbol Documentation Debt	First run	Yes	5 tasks generated covering constants, workflow/js, parser, stringutil, console_wasm

---

🎯 Recommendations

Immediate Actions (This Week)

1. Document pkg/constants semantic type aliases — 12 type aliases, ~30 min effort, high IDE/godoc impact — Priority: High
2. Document pkg/workflow/js.go stub getters — Prevents future confusion about why these functions return empty — Priority: High

Short-term Actions (This Month)

1. Document pkg/parser URL/cron helpers — These are part of the public parser API used by external consumers — Priority: Medium
2. Document pkg/workflow/engine_helpers.go exported functions — Completes the excellent file-level docs with function-level detail — Priority: Medium

Long-term Actions (This Quarter)

1. Add godoc linting — Consider adding a revive or golint rule for missing exported function doc comments to prevent regression — Priority: Low
2. Document pkg/console/console_wasm.go — Wasm consistency improvement — Priority: Low

---

📈 Success Metrics

Track these metrics to measure improvement in Exported Symbol Documentation Debt:

• Undocumented exported functions: ~219 → target 0 (pkg/constants, pkg/parser, pkg/stringutil, pkg/workflow/js.go completed first)
• Undocumented exported types: ~90 → target 0 (pkg/constants 12 types as first milestone)
• godoc coverage score: Run go doc ./... and verify no // undocumented entries for public API packages

---

Next Steps

1. Review and prioritize the 5 tasks above
2. Assign tasks to Copilot coding agent via planner agent (Tasks 1 and 2 first — highest ROI)
3. Track progress on documentation improvement
4. Re-evaluate this focus area in ~2 weeks to measure reduction in undocumented symbols

---

References:

• §24345347720

Generated by Repository Quality Improvement Agent · ● 1M · ◷

• expires on Apr 14, 2026, 1:22 PM UTC