Repository Quality Improvement Report - File Size & Responsibility Decomposition Debt

[github-actions[bot]]

🎯 Repository Quality Improvement Report - File Size & Responsibility Decomposition Debt

Analysis Date: 2026-03-26
Focus Area: File Size & Responsibility Decomposition Debt
Strategy Type: Custom (first run)
Custom Area: Yes — This codebase has an explicit 300-line hard limit for validators in AGENTS.md, and a broader spirit of "prefer many smaller files grouped by functionality." This custom focus area examines how well the current codebase adheres to that principle, and identifies the highest-value decomposition targets.

Executive Summary

The gh-aw codebase contains 626 source files averaging 236 lines each — broadly healthy. However, 171 files (27%) exceed the 300-line threshold stated in AGENTS.md, 55 files (9%) exceed 600 lines, and 6 files (1%) exceed 1,000 lines. While the 300-line hard limit is explicitly stated for validators, the project's own documentation emphasizes "prefer many smaller files grouped by functionality" and "add new files for new features rather than extending existing ones." The largest files have accumulated multiple distinct responsibilities over time, making them harder to review, test, and modify safely.

The five most actionable decomposition targets are: pkg/cli/gateway_logs.go (1,332 lines, combining type definitions, RPC parsing, log parsing, metrics, and table rendering), pkg/cli/audit_report_render.go (1,045 lines, 25 render functions across unrelated audit domains), pkg/constants/constants.go (1,099 lines, mixing semantic type machinery with all project constants), pkg/workflow/safe_outputs_tools_filtering.go (1,037 lines, 6 large functions across filtering and generation responsibilities), and cmd/gh-aw/main.go (860 lines, containing inline cobra command definitions that belong in the pkg/cli pattern already established).

Full Analysis Report

Focus Area: File Size & Responsibility Decomposition Debt

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total source files (non-test)	626	✅
Average lines per file	236	✅
Files > 300 lines	171 (27%)	⚠️
Files > 600 lines	55 (9%)	⚠️
Files > 1000 lines	6 (1%)	❌
Largest file	gateway_logs.go at 1,332 lines	❌
Functions in audit_report_render.go	25 functions	❌

Top 10 largest source files:

File	Lines	Functions	Primary Issue
pkg/cli/gateway_logs.go	1,332	15	Types + parsing + metrics + rendering
pkg/constants/constants.go	1,099	14	Types + all project constants mixed
pkg/cli/audit_report_render.go	1,045	25	25 render functions, many domains
pkg/workflow/safe_outputs_tools_filtering.go	1,037	6	Filtering + generation combined
pkg/cli/logs_report.go	1,011	—	Logs analysis across multiple concerns
pkg/cli/trial_command.go	1,007	10	Command + orchestration + helpers
pkg/workflow/checkout_manager.go	987	23	Broad checkout responsibilities
pkg/workflow/compiler_safe_outputs_config.go	968	16	Config generation + validation
pkg/cli/logs_orchestrator.go	941	—	Orchestration + analysis combined
pkg/workflow/frontmatter_types.go	923	—	Type zoo without clear grouping

Findings

Strengths

• Average file size of 236 lines is healthy for the overall codebase
• The pkg/workflow/ validator pattern (100+ separate validation files) demonstrates excellent decomposition
• Naming conventions ({domain}_{subdomain}_validation.go) are well-applied in validators
• Test-to-source ratio is strong: 969 test files vs 626 source files

Areas for Improvement

• pkg/cli/gateway_logs.go mixes 5 distinct responsibilities in 1,332 lines [Critical]
• pkg/cli/audit_report_render.go contains 25 functions spanning unrelated audit domains [High]
• pkg/constants/constants.go is a 1,099-line god file mixing types and values [High]
• cmd/gh-aw/main.go embeds cobra subcommand logic instead of delegating to pkg/cli [Medium]
• pkg/workflow/safe_outputs_tools_filtering.go combines filtering and tool generation [Medium]

Detailed Analysis

gateway_logs.go is particularly problematic: it defines 10+ types (GatewayLogEntry, DifcFilteredEvent, GuardPolicyEvent, GatewayServerMetrics, GatewayToolMetrics, GatewayMetrics, RPCMessageEntry, etc.), implements RPC message parsing (~200 lines), gateway log parsing (~250 lines), metrics computation (~150 lines), and table rendering (~400 lines) all in one file. Every one of these is a distinct concern testable in isolation.

audit_report_render.go has 25 render* functions covering completely separate audit domains: renderOverview, renderMetrics, renderJobsTable, renderToolUsageTable, renderMCPToolUsageTable, renderGuardPolicySummary, renderFirewallAnalysis, renderPerformanceMetrics, renderPolicyAnalysis, renderEngineConfig, renderPromptAnalysis, renderSessionAnalysis, renderMCPServerHealth, renderSafeOutputSummary, and more. Each cluster of 3-4 render functions could stand alone.

constants/constants.go contains the semantic type definitions (LineLength, Version, FeatureFlag, URL, ModelName, JobName, StepID, EngineName, DocURL) along with their String()/IsValid() methods (already noted in AGENTS.md as having intentional duplication), followed by all project constants covering engines, container images, runtime versions, directories, timeouts, and feature flags.

cmd/gh-aw/main.go defines 7+ cobra commands inline (newCmd, removeCmd, enableCmd, disableCmd, compileCmd, runCmd, versionCmd) at 860 lines, while the pkg/cli package has well-established patterns for command files.

---

🤖 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.

Improvement Tasks

Task 1: Split pkg/cli/gateway_logs.go into focused files

Priority: High
Estimated Effort: Medium
Focus Area: File Decomposition

Description:
gateway_logs.go is 1,332 lines combining five distinct concerns: struct type definitions, constants, RPC message parsing, gateway log entry processing, metrics computation, and table rendering. This file should be split into focused files following the repository's existing conventions.

Acceptance Criteria:

• Types and constants extracted to pkg/cli/gateway_log_types.go (~150 lines)
• RPC message parsing logic (parseRPCMessages, buildToolCallsFromRPCMessages) moved to pkg/cli/gateway_log_rpc.go (~250 lines)
• Log parsing (parseGatewayLogs, processGatewayLogEntry, aggregate helpers) moved to pkg/cli/gateway_log_parser.go (~300 lines)
• All render* and table rendering functions moved to pkg/cli/gateway_log_render.go (~400 lines)
• All existing tests pass after refactoring
• No change in public API

Code Region: pkg/cli/gateway_logs.go

Split `pkg/cli/gateway_logs.go` (1,332 lines) into four focused files following the repository's existing naming conventions.

The file currently mixes:
1. Struct type definitions + constants (GatewayLogEntry, DifcFilteredEvent, GuardPolicyEvent, GatewayServerMetrics, etc.)
2. RPC message parsing: `parseRPCMessages` (lines ~233-436), `buildToolCallsFromRPCMessages` (lines ~876-1017)
3. Gateway log parsing: `parseGatewayLogs`, `processGatewayLogEntry`, `getOrCreateServer`, `getOrCreateTool`, `calculateGatewayAggregates` 
4. Table rendering: `renderGatewayMetricsTable`, `getSortedServerNames`, `extractMCPToolUsageData`, `buildGuardPolicySummary`

Create these new files (all in package `cli`):
- `pkg/cli/gateway_log_types.go` — all struct types and constants
- `pkg/cli/gateway_log_rpc.go` — RPC parsing functions
- `pkg/cli/gateway_log_parser.go` — log entry parsing and metrics computation
- `pkg/cli/gateway_log_render.go` — table rendering and display functions

After splitting, delete the original `gateway_logs.go`.

Run `make agent-finish` to verify all tests pass and formatting is correct.

---

Task 2: Split pkg/cli/audit_report_render.go by audit domain

Priority: High
Estimated Effort: Medium
Focus Area: File Decomposition

Description:
audit_report_render.go contains 25 render* functions across completely unrelated audit domains (tools, security, performance, engine config, etc.) totalling 1,045 lines. Group related render functions into domain-focused files.

Acceptance Criteria:

• renderJSON, renderConsole, renderAuditComparison, renderOverview stay in a core audit_report_render.go (~200 lines)
• Tool/MCP-related renders (renderToolUsageTable, renderMCPToolUsageTable, renderMCPServerHealth) extracted to audit_render_tools.go (~200 lines)
• Security-related renders (renderGuardPolicySummary, renderFirewallAnalysis, renderRedactedDomainsAnalysis, renderPolicyAnalysis) extracted to audit_render_security.go (~200 lines)
• Performance/metrics renders (renderMetrics, renderJobsTable, renderPerformanceMetrics, renderSafeOutputSummary) extracted to audit_render_metrics.go (~200 lines)
• Analysis renders (renderKeyFindings, renderRecommendations, renderEngineConfig, renderPromptAnalysis, renderSessionAnalysis, renderCreatedItemsTable) extracted to audit_render_analysis.go (~250 lines)
• All existing tests pass

Code Region: pkg/cli/audit_report_render.go

Split `pkg/cli/audit_report_render.go` (1,045 lines, 25 functions) by grouping render functions into 5 domain-focused files.

All files stay in `package cli`. The function groupings are:

**`pkg/cli/audit_report_render.go`** (keep — core entry points):
- `renderJSON`, `renderConsole`, `renderAuditComparison`, `renderOverview`, helper `formatUnixTimestamp`

**`pkg/cli/audit_render_tools.go`** (new):
- `renderToolUsageTable`, `renderMCPToolUsageTable`, `renderMCPServerHealth`

**`pkg/cli/audit_render_security.go`** (new):
- `renderGuardPolicySummary`, `renderFirewallAnalysis`, `renderRedactedDomainsAnalysis`, `renderPolicyAnalysis`

**`pkg/cli/audit_render_metrics.go`** (new):
- `renderMetrics`, `renderJobsTable`, `renderPerformanceMetrics`, `renderSafeOutputSummary`

**`pkg/cli/audit_render_analysis.go`** (new):
- `renderKeyFindings`, `renderRecommendations`, `renderEngineConfig`, `renderPromptAnalysis`, `renderSessionAnalysis`, `renderCreatedItemsTable`

Do NOT change any function signatures or behavior. Run `make agent-finish` to verify all tests pass.

---

Task 3: Decompose pkg/constants/constants.go by domain

Priority: High
Estimated Effort: Small
Focus Area: File Decomposition

Description:
pkg/constants/constants.go is 1,099 lines mixing semantic type machinery (9 named types + their methods) with all project constants (engine versions, container images, runtime versions, directory paths, timeout values, feature flags). The type definitions and method implementations (already noted as intentionally duplicated in AGENTS.md) should be separated from the constant values.

Acceptance Criteria:

• Semantic type definitions and their String()/IsValid() methods extracted to pkg/constants/constants_types.go
• Engine-specific constants (engine names, versions, model names) grouped in pkg/constants/constants_engines.go
• Container/image constants (DefaultGhAwMount, DefaultNodeAlpineLTSImage, registry URLs, etc.) grouped in pkg/constants/constants_containers.go
• Runtime/version defaults (DefaultNodeVersion, DefaultPythonVersion, DefaultGoVersion, etc.) grouped in pkg/constants/constants_runtimes.go
• Directory/path constants (GhAwRootDir, AWFAuditDir, etc.) and timeouts stay in a reduced constants.go
• All imports in other packages continue to work (no API changes)
• make agent-finish passes

Code Region: pkg/constants/constants.go

Decompose `pkg/constants/constants.go` (1,099 lines) into domain-focused files. All files stay in `package constants`.

**`pkg/constants/constants_types.go`** (new — semantic types):
Move all named type definitions and their String()/IsValid() methods:
- `LineLength`, `Version`, `FeatureFlag`, `URL`, `ModelName`, `JobName`, `StepID`, `CommandPrefix`, `WorkflowID`, `EngineName`, `DocURL`
- All associated `String()` and `IsValid()` method implementations

**`pkg/constants/constants_engines.go`** (new — AI engine constants):
- `CopilotEngine`, `ClaudeEngine`, `CodexEngine`, `GeminiEngine`, `CustomEngine` (EngineName consts)
- Default engine versions: `DefaultCopilotVersion`, `DefaultClaudeCodeVersion`, `DefaultCodexVersion`, `DefaultGeminiVersion`
- Model names: `DefaultCopilotDetectionModel`
- Engine doc URLs

**`pkg/constants/constants_runtimes.go`** (new — runtime/language versions):
- `DefaultNodeVersion`, `DefaultPythonVersion`, `DefaultGoVersion`, `DefaultRubyVersion`, `DefaultJavaVersion`, `DefaultDotNetVersion`, `DefaultDenoVersion`, `DefaultBunVersion`, etc.

**`pkg/constants/constants_containers.go`** (new — container images):  
- `DefaultNodeAlpineLTSImage`, `DefaultPythonAlpineLTSImage`, `DefaultAlpineImage`, `DevModeGhAwImage`
- `DefaultGhAwMount`, `DefaultGhBinaryMount`, `DefaultTmpGhAwMount`, `DefaultWorkspaceMount`

**`pkg/constants/constants.go`** (keep — shrunk):
- Remaining constants: directories, timeouts, feature flags, misc

Run `make agent-finish` to verify build and tests pass.

---

Task 4: Move cobra subcommand definitions out of cmd/gh-aw/main.go

Priority: Medium
Estimated Effort: Medium
Focus Area: File Decomposition / CLI Architecture

Description:
cmd/gh-aw/main.go is 860 lines containing 7 cobra var command definitions (newCmd, removeCmd, enableCmd, disableCmd, compileCmd, runCmd, versionCmd) inline. The repository already has a rich pkg/cli/ package with proper command files (add_command.go, compile_command.go, etc.). The main.go entrypoint should be thin, delegating to constructors in pkg/cli/.

Acceptance Criteria:

• main.go reduced to ≤150 lines, containing only: root command definition, flag registration (init()), and main()
• Each command (new, remove, enable, disable, run, version) moved to dedicated files in cmd/gh-aw/ or exposed as constructors from pkg/cli/
• compileCmd (the largest at ~120 lines) moved to pkg/cli/compile_command.go or integrated with the existing compile command path
• All ./gh-aw --help and subcommand behaviors unchanged
• make agent-finish passes

Code Region: cmd/gh-aw/main.go

Refactor `cmd/gh-aw/main.go` (860 lines) to be a thin entrypoint that delegates to `pkg/cli/` constructors, following the pattern already established in the repository.

Currently, `main.go` contains 7 var-declared cobra commands inline (`newCmd` at line 107, `removeCmd` at 165, `enableCmd` at 190, `disableCmd` at 209, `compileCmd` at 230, `runCmd` at 347, `versionCmd` at 432).

Move each command to a constructor function in `pkg/cli/`:
- `pkg/cli/new_command.go` — `NewWorkflowCommand() *cobra.Command`
- `pkg/cli/remove_command.go` — `NewRemoveCommand() *cobra.Command`  
- `pkg/cli/enable_command.go` — `NewEnableCommand() *cobra.Command`
- `pkg/cli/disable_command.go` — `NewDisableCommand() *cobra.Command`
- Update `pkg/cli/compile_command.go` — integrate `compileCmd` logic
- Update `pkg/cli/run_command.go` — integrate `runCmd` logic (or create if needed)
- `pkg/cli/version_command.go` — `NewVersionCommand() *cobra.Command`

`cmd/gh-aw/main.go` should then just call these constructors in `init()` or equivalent. Keep `main()` as-is.

Run `make agent-finish` to verify build and tests pass.

---

Task 5: Split pkg/workflow/safe_outputs_tools_filtering.go into filtering and generation

Priority: Medium
Estimated Effort: Small
Focus Area: File Decomposition

Description:
safe_outputs_tools_filtering.go (1,037 lines, 6 functions) combines tool filtering (deciding which tools are enabled, computeEnabledToolNames) with tool generation (constructing JSON tool definitions, generateFilteredToolsJSON, generateDynamicTools, generateToolsMetaJSON) and repo parameter injection (addRepoParameterIfNeeded, computeRepoParamForTool). These are separate concerns.

Acceptance Criteria:

• Tool enablement/filtering logic (computeEnabledToolNames) stays in a reduced safe_outputs_tools_filtering.go
• Repo parameter logic (addRepoParameterIfNeeded, computeRepoParamForTool, ~90 lines) extracted to safe_outputs_tools_repo.go
• Tool generation (generateFilteredToolsJSON, generateDynamicTools, generateToolsMetaJSON, types) extracted to safe_outputs_tools_generator.go
• All existing tests pass
• make agent-finish passes

Code Region: pkg/workflow/safe_outputs_tools_filtering.go

Split `pkg/workflow/safe_outputs_tools_filtering.go` (1,037 lines) into three focused files. All in `package workflow`.

**`pkg/workflow/safe_outputs_tools_filtering.go`** (keep — shrunk):
- `computeEnabledToolNames` (lines ~607-736) — the core filtering logic

**`pkg/workflow/safe_outputs_tools_repo.go`** (new):
- `addRepoParameterIfNeeded` (lines ~437-606) — repo parameter injection
- `computeRepoParamForTool` (lines ~737-763) — repo parameter calculation

**`pkg/workflow/safe_outputs_tools_generator.go`** (new):
- `generateFilteredToolsJSON` (lines ~38-436) — main tool JSON generation
- `generateDynamicTools` (lines ~764-953) — dynamic tool construction
- `ToolsMeta` type (lines ~954-974) — type definition
- `generateToolsMetaJSON` (lines ~975-end) — meta JSON generation

Run `make agent-finish` to verify all tests pass.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-03-26	File Size & Responsibility Decomposition Debt	Custom	Yes	First run — 5 tasks generated targeting 5 files over 1,000 lines

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split gateway_logs.go (1,332 lines) — 4-way split, highest complexity reduction — Priority: High
2. Split audit_report_render.go (1,045 lines, 25 functions) — 5-way split by render domain — Priority: High
3. Decompose constants.go (1,099 lines) — 5-way split by constant domain — Priority: High

Short-term Actions (This Month)

1. Refactor main.go — move command definitions to pkg/cli — Priority: Medium
2. Split safe_outputs_tools_filtering.go — separate filtering from generation — Priority: Medium

Long-term Actions (This Quarter)

1. Add a CI lint step (or make lint rule) that warns when any new *_test.go-excluded .go file exceeds 400 lines — prevents regression
2. Review pkg/cli/trial_command.go (1,007 lines), pkg/workflow/checkout_manager.go (987 lines), and pkg/workflow/compiler_safe_outputs_config.go (968 lines) for further decomposition

---

📈 Success Metrics

Track these metrics to measure improvement in File Size & Responsibility Decomposition Debt:

• Files > 1,000 lines: 6 → 0 (target after these 5 tasks)
• Files > 600 lines: 55 → < 40
• Files > 300 lines: 171 → < 150
• Average functions per file in pkg/cli/: ~10 → ≤ 6
• main.go line count: 860 → ≤ 150

---

Next Steps

1. Review and prioritize the 5 tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on decomposition items
4. Re-evaluate this focus area in 2 weeks to verify progress

---

References:

• Workflow run: §23597000998

AI generated by Repository Quality Improvement Agent · history

• expires on Mar 27, 2026, 1:40 PM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #23243.