Repository Quality Improvement: Constants Package Domain Segregation

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Constants Package Domain Segregation

Analysis Date: 2026-03-30
Focus Area: Constants Package Domain Segregation
Strategy Type: Custom (first run, 60% custom probability)
Custom Area: Yes — pkg/constants/constants.go is a 1087-line monolith mixing 12+ distinct conceptual domains. Splitting it into domain-specific files dramatically improves discoverability and reduces cognitive overhead.

---

Executive Summary

pkg/constants/constants.go has grown to 1087 lines containing 14 semantic types, 112 const groups, and several large var declarations—all in a single file imported by 121 packages. The file mixes completely unrelated concerns: runtime language version defaults, engine option metadata, MCP server IDs, GitHub Actions job names, step IDs, firewall configuration, feature flags, security validation lists, and Docker mount constants.

This monolith makes it unnecessarily difficult to locate a specific constant (e.g., "which file defines the default Node.js version?"), increases review noise (every PR that touches any constant shows a diff against this single massive file), and will accumulate further without intervention.

Go's package model fully supports splitting a package across multiple files—all files in the same pkg/constants/ directory remain in the same package, so no import paths change. The refactor is purely organizational and carries zero runtime risk.

Separately, several CLI and workflow package files exceed 800–1300 lines, and the audit_cross_run_render.go file writes markdown output using fmt.Println/fmt.Printf to stdout rather than a buffered writer, which mixes concerns and makes testing harder.

Full Analysis Report

Focus Area: Constants Package Domain Segregation

Current State Assessment

Metrics Collected:

Metric	Value	Status
constants.go line count	1087	❌
Semantic types defined	14	⚠️
Const groups (const keywords)	112	❌
Packages that import constants	121	⚠️
Files in pkg/constants/	2 (constants.go + test)	❌
Go source files >300 lines	175 / 630 (28%)	⚠️
Go source files >800 lines	20	⚠️
fmt.Errorf with %w wrapping	944 / 1420 (66%)	⚠️
interface{} instead of any	0	✅

Findings

Strengths

• Zero uses of deprecated interface{} — the codebase already uses the modern any alias throughout
• Strong error message quality: 1139 console-formatted user messages, 66% of fmt.Errorf use proper %w wrapping
• High test coverage ratio: 328k test LOC vs 150k source LOC (≈2.19× — excellent)
• workflow_errors.go provides a rich, structured WorkflowValidationError type with Field/Value/Reason/Suggestion fields
• Schema error suggestions (schema_suggestions.go) include fuzzy matching and "Did you mean?" guidance

Areas for Improvement

• 🔴 constants.go monolith — 1087 lines with 12+ conceptual domains in one file
• 🟡 Large files — 20 files exceed 800 lines; top offenders: gateway_logs.go (1332), constants.go (1087), audit_report_render.go (1045), logs_report.go (1011), trial_command.go (1007)
• 🟡 Unwrapped error returns — 238+ bare return err and 102+ bare return nil, err without context wrapping
• 🟡 Markdown rendering via fmt.Print* — audit_cross_run_render.go writes structured markdown to stdout with fmt.Println/Printf rather than accepting an io.Writer, making it hard to test

Detailed Analysis

constants.go Domain Breakdown

The file contains these clearly separable domains:

Domain	Lines (approx)	Proposed file
Semantic types (LineLength, Version, FeatureFlag, URL, ModelName, JobName, StepID, CommandPrefix, WorkflowID, EngineName, DocURL, MCPServerID)	~195	constants_types.go
Engine names, EngineOption struct, EngineOptions, SystemSecrets, helper funcs	~210	constants_engines.go
Runtime language version defaults (Node, Python, Go, Ruby, etc.)	~80	constants_runtimes.go
Timeout & performance defaults	~25	constants_timeouts.go
MCP server IDs, versions, gateway defaults, DefaultReadOnlyGitHubTools	~190	constants_mcp.go
Firewall / AWF / container paths and versions	~100	constants_infrastructure.go
GitHub Actions job names, step IDs, artifact names, output names	~160	constants_workflow_jobs.go
Feature flags	~25	constants_features.go
Security/validation lists (SafeWorkflowEvents, AllowedExpressions, DangerousPropertyNames)	~100	constants_security.go
YAML field ordering, shared-workflow forbidden fields, misc	~70	constants_workflow_schema.go

Each resulting file would be 25–210 lines — well within the 200-line guideline.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following tasks are designed for GitHub Copilot coding agent execution. Please split these into individual work items for the agent to process one at a time.

---

Improvement Tasks

Task 1: Split constants.go into domain-specific files — Part A (Types + Engines + Runtimes)

Priority: High
Estimated Effort: Medium
Focus Area: Constants Package Domain Segregation

Description:
The pkg/constants/constants.go file is 1087 lines and mixes 12+ unrelated domains. This task covers the first split: extract the semantic type definitions, engine constants, and runtime version defaults into dedicated files. All files remain in the package constants package, so no import paths change anywhere in the codebase.

Acceptance Criteria:

• Create pkg/constants/constants_types.go containing all 14 type definitions (LineLength, Version, FeatureFlag, URL, ModelName, JobName, StepID, CommandPrefix, WorkflowID, EngineName, DocURL, MCPServerID, EngineOption struct, SystemSecretSpec struct) with their String()/IsValid() methods
• Create pkg/constants/constants_engines.go containing engine-related constants: CopilotEngine, ClaudeEngine, CodexEngine, GeminiEngine, AgenticEngines, EngineOptions, SystemSecrets, GetEngineOption(), GetAllEngineSecretNames()
• Create pkg/constants/constants_runtimes.go containing all Default*Version runtime constants (Node, Python, Go, Ruby, DotNet, Java, Elixir, Haskell, Deno, Bun) and image constants (DefaultNodeAlpineLTSImage, etc.)
• Remove the extracted declarations from constants.go
• Run make build && make test-unit to confirm no breakage
• constants.go should be noticeably shorter (target <700 lines after this task)

Code Region: pkg/constants/constants.go (lines 1–510 approximately)

In the file `pkg/constants/constants.go`, extract the following groups into new files within the same `pkg/constants/` package directory:

1. Create `pkg/constants/constants_types.go`:
   - All `type` declarations (LineLength, Version, FeatureFlag, URL, ModelName, JobName, StepID, CommandPrefix, WorkflowID, EngineName, DocURL, MCPServerID) with their `String()` and `IsValid()` methods
   - The `EngineOption` struct and `SystemSecretSpec` struct definitions

2. Create `pkg/constants/constants_engines.go`:
   - `CopilotEngine`, `ClaudeEngine`, `CodexEngine`, `GeminiEngine` constants
   - `AgenticEngines` var
   - `EngineOptions` var
   - `SystemSecrets` var
   - `GetEngineOption()` function
   - `GetAllEngineSecretNames()` function

3. Create `pkg/constants/constants_runtimes.go`:
   - All `Default*Version` constants for language runtimes (DefaultNodeVersion, DefaultPythonVersion, DefaultGoVersion, DefaultRubyVersion, DefaultDotNetVersion, DefaultJavaVersion, DefaultElixirVersion, DefaultHaskellVersion, DefaultDenoVersion, DefaultBunVersion)
   - Container image constants: DefaultNodeAlpineLTSImage, DefaultPythonAlpineLTSImage, DefaultAlpineImage, DevModeGhAwImage

Remove the extracted declarations from `constants.go`. Do NOT change any import paths in other packages — all files remain in `package constants`.

Verify with: `make build && make test-unit`

---

Task 2: Split constants.go — Part B (MCP + Infrastructure + Workflow Jobs + Features + Security)

Priority: High
Estimated Effort: Medium
Focus Area: Constants Package Domain Segregation

Description:
Continuation of the constants split. Extract the remaining 5 domains from constants.go into dedicated files. After this task, constants.go should contain only the few items that don't fit cleanly into a domain (CLIExtensionPrefix, GetWorkflowDir, MaxSymlinkDepth, SharedWorkflowForbiddenFields, etc.) and be under 150 lines.

Acceptance Criteria:

• Create pkg/constants/constants_mcp.go with MCP server IDs (SafeOutputsMCPServerID, MCPScriptsMCPServerID, AgenticWorkflowsMCPServerID), MCP version constants, DefaultMCPRegistryURL, DefaultMCPGatewayVersion/Container/PayloadDir/PayloadSizeThreshold, DefaultMCPSDKVersion, DefaultGitHubMCPServerVersion, DefaultReadOnlyGitHubTools, DefaultGitHubToolsLocal/Remote, DefaultGitHubTools, DefaultBashTools, CopilotStemCommands
• Create pkg/constants/constants_infrastructure.go with AWF/firewall constants (AWFDefaultCommand, AWFProxyLogsDir, AWFAuditDir, FirewallAuditArtifactName, AWFDefaultLogLevel, AWFExcludeEnvMinVersion, DefaultFirewallVersion, DefaultFirewallRegistry, DefaultAPMActionVersion, DefaultAPMVersion, DefaultGitHubLockdown), container mount constants (GhAwRootDir, GhAwRootDirShell, DefaultGhAwMount, DefaultGhBinaryMount, DefaultTmpGhAwMount, DefaultWorkspaceMount, DefaultActivationJobRunnerImage)
• Create pkg/constants/constants_workflow_jobs.go with all job name constants (AgentJobName, ActivationJobName etc.), step ID constants (CheckMembershipStepID etc.), artifact name constants, output name constants, and rate limit defaults
• Create pkg/constants/constants_features.go with all FeatureFlag const values (MCPScriptsFeatureFlag, MCPGatewayFeatureFlag, DisableXPIAPromptFeatureFlag, CopilotRequestsFeatureFlag, DIFCProxyFeatureFlag)
• Create pkg/constants/constants_security.go with SafeWorkflowEvents, AllowedExpressions, DangerousPropertyNames, DefaultAllowedDomains
• constants.go should be under 150 lines after both Task 1 and Task 2
• Run make build && make test-unit to confirm no breakage

Code Region: pkg/constants/constants.go (lines 510–1087 approximately)

In `pkg/constants/constants.go`, extract the remaining domains into new files in the same `pkg/constants/` package:

1. Create `pkg/constants/constants_mcp.go`:
   - MCPServerID type (if not already in constants_types.go)
   - MCP server ID constants: SafeOutputsMCPServerID, MCPScriptsMCPServerID, AgenticWorkflowsMCPServerID, MCPScriptsMCPVersion
   - DefaultMCPRegistryURL, PublicGitHubHost, GitHubCopilotMCPDomain
   - DefaultMCPGatewayVersion, DefaultMCPGatewayContainer, DefaultMCPGatewayPayloadDir, DefaultMCPGatewayPayloadSizeThreshold
   - DefaultMCPSDKVersion, DefaultGitHubMCPServerVersion, DefaultGitHubScriptVersion
   - DefaultReadOnlyGitHubTools, DefaultGitHubToolsLocal, DefaultGitHubToolsRemote, DefaultGitHubTools
   - DefaultBashTools, CopilotStemCommands
   - DefaultPlaywrightMCPVersion, DefaultPlaywrightBrowserVersion, DefaultQmdVersion, DefaultQmdIndexingRunnerImage

2. Create `pkg/constants/constants_infrastructure.go`:
   - All AWF_ and DefaultFirewall* constants
   - Container registry and image defaults: DefaultAPMActionVersion, DefaultAPMVersion
   - Path/mount constants: GhAwRootDir, GhAwRootDirShell, DefaultGhAwMount, DefaultGhBinaryMount, DefaultTmpGhAwMount, DefaultWorkspaceMount
   - DefaultActivationJobRunnerImage, DefaultGitHubLockdown

3. Create `pkg/constants/constants_workflow_jobs.go`:
   - All JobName constants (AgentJobName through UnlockJobName)
   - All artifact name constants (SafeOutputArtifactName, AgentOutputArtifactName, etc.)
   - All StepID constants (CheckMembershipStepID through PreActivationAppTokenStepID)
   - All output name constants (IsTeamMemberOutput through SkipIfCheckFailingOkOutput, ActivatedOutput, ArtifactPrefixOutputName)
   - DefaultRateLimitMax, DefaultRateLimitWindow

4. Create `pkg/constants/constants_features.go`:
   - The feature flag const block: MCPScriptsFeatureFlag, MCPGatewayFeatureFlag, DisableXPIAPromptFeatureFlag, CopilotRequestsFeatureFlag, DIFCProxyFeatureFlag

5. Create `pkg/constants/constants_security.go`:
   - DefaultAllowedDomains, SafeWorkflowEvents, AllowedExpressions, DangerousPropertyNames

Remove all extracted declarations from `constants.go`. Keep in `constants.go` only: CLIExtensionPrefix, MaxExpressionLineLength, ExpressionBreakThreshold, GetWorkflowDir(), MaxSymlinkDepth, SharedWorkflowForbiddenFields, IgnoredFrontmatterFields, PriorityStepFields, PriorityJobFields, PriorityWorkflowFields, DefaultAllowedMemoryExtensions.

Verify with: `make build && make test-unit`

---

Task 3: Add Context to Unwrapped Error Returns in High-Traffic Packages

Priority: Medium
Estimated Effort: Medium
Focus Area: Error Handling Quality

Description:
The codebase has ~340 bare return err / return nil, err patterns that pass errors up without adding context. While not all of these are wrong (e.g., immediately after a top-level user-facing function), those in deeply-nested internal functions lose callsite context. This task focuses on the pkg/workflow/ package which has the most bare returns in functions that benefit from wrapping context.

Acceptance Criteria:

• Review all bare return err in pkg/workflow/ (excluding *_test.go)
• Wrap errors with fmt.Errorf("context: %w", err) in internal helper functions where the error's origin would be unclear from the message alone
• Do NOT wrap errors in functions that are called directly by user-facing CLI commands (those are fine as-is, as they're already at the top of the stack)
• Prioritize functions in checkout_manager.go, cache.go, and compiler_orchestrator_workflow.go — the three largest workflow files
• All new wrapping strings should follow snake_case verb phrasing: "failed to X: %w" format
• Run make build && make test-unit to confirm no breakage

Code Region: pkg/workflow/checkout_manager.go, pkg/workflow/cache.go, pkg/workflow/compiler_orchestrator_workflow.go

In `pkg/workflow/checkout_manager.go`, `pkg/workflow/cache.go`, and `pkg/workflow/compiler_orchestrator_workflow.go`:

Find all locations where an error is returned without context wrapping (patterns: `return err`, `return nil, err`, `return "", err`, `return false, err`, etc.) in internal helper functions (non-exported, or exported functions that are not the top-level command handler).

For each such location, determine if adding context would help identify the failure source. If yes, wrap with:
    return fmt.Errorf("failed to <operation>: %w", err)

Use concise, lowercase verb phrases: "failed to read lock file", "failed to parse YAML", "failed to clone repository", etc.

Do not wrap errors in top-level exported functions that are the direct entry points called by cobra command handlers — those should propagate cleanly for the command's own error formatting.

After changes, run: `make build && make test-unit`

---

Task 4: Refactor audit_cross_run_render.go to Accept io.Writer for Testability

Priority: Medium
Estimated Effort: Small
Focus Area: Testability & Output Routing

Description:
pkg/cli/audit_cross_run_render.go (360 lines) renders a markdown report by calling fmt.Println and fmt.Printf directly, hardcoded to stdout. This makes it impossible to unit test the rendering output without capturing stdout, and it prevents callers from redirecting the output. The functions should accept an io.Writer parameter.

Acceptance Criteria:

• Refactor renderCrossRunReportMarkdown(report *CrossRunAuditReport) to accept an io.Writer as first parameter: renderCrossRunReportMarkdown(w io.Writer, report *CrossRunAuditReport)
• Replace all fmt.Println(...) and fmt.Printf(...) calls inside this function (and any helpers it calls within the same file) with fmt.Fprintln(w, ...) and fmt.Fprintf(w, ...)
• Update all callers of renderCrossRunReportMarkdown to pass os.Stdout
• Add a simple unit test in audit_cross_run_render_test.go (create if not exists) that calls renderCrossRunReportMarkdown with a bytes.Buffer and asserts the output contains expected strings
• Run make build && make test-unit to confirm no breakage

Code Region: pkg/cli/audit_cross_run_render.go, callers in pkg/cli/audit_cross_run.go

In `pkg/cli/audit_cross_run_render.go`:

1. Change the signature of `renderCrossRunReportMarkdown` from:
   ```go
   func renderCrossRunReportMarkdown(report *CrossRunAuditReport)

to:

func renderCrossRunReportMarkdown(w io.Writer, report *CrossRunAuditReport)

2. Replace all fmt.Println(x) with fmt.Fprintln(w, x) and all fmt.Printf(format, args...) with fmt.Fprintf(w, format, args...) throughout the function body and any unexported helper functions called exclusively by it within the same file.

3. Add "io" to the import block.

4. Find all callers of renderCrossRunReportMarkdown in pkg/cli/ and update them to pass os.Stdout as the first argument.

5. Create pkg/cli/audit_cross_run_render_test.go with at least one test:

   func TestRenderCrossRunReportMarkdown_ContainsHeader(t *testing.T) {
       var buf bytes.Buffer
       report := &CrossRunAuditReport{RunsAnalyzed: 3, ...}
       renderCrossRunReportMarkdown(&buf, report)
       assert.Contains(t, buf.String(), "Audit Report")
   }

Verify: make build && make test-unit

---

## 📊 Historical Context

<details>
<summary><b>Previous Focus Areas</b></summary>

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|
| 2026-03-30 | Constants Package Domain Segregation | Custom | Yes | First run — identified 1087-line constants monolith; 4 tasks generated |

</details>

---

## 🎯 Recommendations

### Immediate Actions (This Week)
1. **Execute Task 1** — Split constants types/engines/runtimes into dedicated files — Priority: High
2. **Execute Task 2** — Split remaining constants domains into dedicated files — Priority: High

### Short-term Actions (This Month)
1. **Execute Task 3** — Add error context to unwrapped returns in top 3 workflow files — Priority: Medium
2. **Execute Task 4** — Refactor audit_cross_run_render.go for testability — Priority: Medium
3. **Consider splitting** `gateway_logs.go` (1332 lines) into parsing, processing, and rendering sub-files

### Long-term Actions (This Quarter)
1. Establish a policy to enforce the 300-line file limit via CI (e.g., a script that fails if any non-test file exceeds 500 lines without a documented exception)
2. Systematically audit all `pkg/cli/` files over 500 lines for similar render/logic separation opportunities

---

## 📈 Success Metrics

Track these metrics to measure improvement in **Constants Package Domain Segregation**:

- **`constants.go` line count**: 1087 → Target ≤ 150 (residual file)
- **Files in `pkg/constants/`**: 2 → Target 12 (one per domain + test)
- **Avg file size in `pkg/constants/`**: 545 → Target ≤ 120 lines
- **Go source files >800 lines**: 20 → Target ≤ 15 (after splitting gateway_logs.go and audit_report_render.go)
- **Unwrapped error returns in `pkg/workflow/`**: (current count) → Reduce by 30%

---

## Next Steps

1. Review and prioritize the 4 tasks above
2. Assign Tasks 1 & 2 to Copilot coding agent first (they are independent and can be executed sequentially)
3. Tasks 3 & 4 can be done in parallel after Tasks 1 & 2 complete
4. Re-evaluate constants organization in 30 days to assess discoverability improvements

---

**References:**
- [§23747364709](https://github.com/github/gh-aw/actions/runs/23747364709)

*Generated by Repository Quality Improvement Agent*
*Next analysis: 2026-03-31 — Focus area will be selected based on diversity algorithm (recent: constants-package-domain-segregation)*


> AI generated by [Repository Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/23747364709) · [history](https://github.com/search?q=repo%3Agithub%2Fgh-aw+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw%2Frepository-quality-improver%22&type=discussions)
> - [x] expires <!-- gh-aw-expires: 2026-03-31T13:40:29.106Z --> on Mar 31, 2026, 1:40 PM UTC

<!-- gh-aw-workflow-id: repository-quality-improver -->
<!-- gh-aw-workflow-call-id: github/gh-aw/repository-quality-improver -->

[github-actions[bot]]

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

A newer discussion is available at Discussion #23730.