Repository Quality Report: Large File Complexity & Code Size Management (2026-03-24)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Large File Complexity

Analysis Date: 2026-03-24
Focus Area: Large File Complexity & Code Size Management
Strategy Type: Custom (repository-specific)
Custom Area: Yes — gh-aw's AGENTS.md explicitly documents a 300-line hard limit for validators and 100–200 line target, yet 163 source files exceed this threshold. This analysis identifies the highest-priority refactoring opportunities.

---

Executive Summary

The gh-aw codebase documents clear size guidelines: validators should target 100–200 lines with a hard limit of 300 lines. However, a sweep across all non-test Go files reveals 163 files exceeding 300 lines and 72 files exceeding 500 lines — indicating the size discipline applied to validators has not been consistently applied to the broader codebase.

The most impactful offenders are non-validator files that have grown into multi-concern monoliths: gateway_logs.go (1,127 lines combining types, parsing, rendering, and analytics), constants.go (1,093 lines of mixed-domain constants), trial_command.go (1,007 lines mixing CLI wiring with business logic), and compiler_safe_outputs_config.go (976 lines). Additionally, several validator files themselves now exceed the 300-line hard limit.

Splitting these files improves discoverability, testability, and maintainability — and aligns the non-validator codebase with the same quality bar already documented for validators.

---

Full Analysis Report

Focus Area: Large File Complexity

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total non-test Go source files	615	✅
Average file size	461 lines	⚠️
Files > 300 lines	163 (26.5%)	❌
Files > 500 lines	72 (11.7%)	❌
Files > 800 lines	~25	❌
Validator files > 300 lines	9	❌
Real TODOs/FIXMEs in source	7	✅
Test LOC / Source LOC ratio	317K / 284K ≈ 1.12	✅

Top 10 Largest Non-Validator Files:

File	Lines	Primary Concerns
pkg/cli/gateway_logs.go	1,127	Types + parsing + metrics + rendering
pkg/constants/constants.go	1,093	All constants (mixed domains)
pkg/workflow/safe_outputs_tools_filtering.go	1,037	Filtering logic
pkg/cli/trial_command.go	1,007	CLI + business logic + helpers
pkg/workflow/checkout_manager.go	983	Checkout orchestration
pkg/workflow/compiler_safe_outputs_config.go	976	Safe outputs config compilation
pkg/cli/logs_report.go	945	Log report rendering
pkg/workflow/frontmatter_types.go	917	All frontmatter type definitions
pkg/cli/logs_orchestrator.go	907	Log orchestration
pkg/workflow/compiler_orchestrator_workflow.go	902	Orchestrator workflow compilation

Validator Files Exceeding Hard Limit (300 lines):

File	Lines	Over By
pkg/workflow/safe_outputs_validation_config.go	407	+107
pkg/workflow/safe_outputs_validation.go	407	+107
pkg/workflow/dispatch_workflow_validation.go	363	+63
pkg/workflow/tools_validation.go	359	+59
pkg/workflow/permissions_validation.go	351	+51
pkg/cli/run_workflow_validation.go	344	+44
pkg/workflow/repository_features_validation.go	342	+42
pkg/workflow/template_injection_validation.go	306	+6
pkg/workflow/mcp_config_validation.go	301	+1

Findings

Strengths

• Validator decomposition philosophy is well-established (53 validator files, well-named by domain)
• Test coverage is strong — test LOC exceeds source LOC
• Only 7 real TODOs/FIXMEs indicating clean work-in-progress tracking
• fmt.Println is appropriately used only for structured stdout output (18 occurrences, all justified)
• Console formatting (console.FormatErrorMessage, etc.) is consistently applied

Areas for Improvement

• Critical: pkg/constants/constants.go (1,093 lines) — one file for all constants across all domains violates cohesion
• Critical: pkg/cli/gateway_logs.go (1,127 lines) — contains 13+ functions spanning type definitions, JSON parsing, RPC analysis, and table rendering
• High: cmd/gh-aw/main.go (862 lines) — command registration and CLI wiring in a single file
• Medium: Several validators have silently crept past the documented 300-line hard limit
• Medium: pkg/workflow/frontmatter_types.go (917 lines) — all frontmatter types in one file

Detailed Analysis

Why constants.go should be split:
The file contains 141 type definitions and constants spanning engine versions, MCP URLs, runtime defaults, job names, step IDs, firewall configuration, playground settings, and language support maps. A grep of section boundaries shows clear domain groupings that map cleanly to separate files.

Why gateway_logs.go should be split:
Functions include parseRPCMessages (170–341), parseGatewayLogs (357–433), processGatewayLogEntry (434–541), renderGatewayMetricsTable (580–707), and buildToolCallsFromRPCMessages (719–860). These span distinct concerns: type definitions, I/O parsing, metric computation, and rendering.

Why validator overruns matter:
AGENTS.md documents these limits as guardrails against complexity. When validators silently exceed their limits, it signals that the review checklist is not enforcing the constraint. Fixing the validators restores the documented quality bar.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following 5 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 pkg/constants/constants.go into Domain-Specific Files

Priority: High
Estimated Effort: Medium
Focus Area: Code Organization

Description:
pkg/constants/constants.go is 1,093 lines and contains constants spanning multiple unrelated domains: semantic type definitions, engine versions, MCP configuration, runtime defaults, job/step names, firewall settings, and playground parameters. Split it into cohesive domain files in pkg/constants/.

Acceptance Criteria:

• constants.go reduced to ≤ 300 lines (or ideally ≤ 200)
• New files named by domain: e.g., constants_engines.go, constants_mcp.go, constants_runtimes.go, constants_types.go, constants_jobs.go
• All existing constants remain in the same constants package — no import path changes
• All references across the codebase continue to compile without changes
• make build && make test-unit passes

Code Region: pkg/constants/constants.go

Split `pkg/constants/constants.go` (currently 1,093 lines) into multiple domain-specific files within the same `pkg/constants/` package.

Group constants logically:
- `constants_types.go` — semantic type aliases (LineLength, Version, FeatureFlag, URL, ModelName, JobName, StepID, CommandPrefix, WorkflowID, EngineName, DocURL) and their String()/IsValid() methods
- `constants_engines.go` — engine names, versions, and engine-specific defaults (Copilot, Claude, Codex, Gemini)
- `constants_mcp.go` — MCP server URLs, versions, containers (MCPGateway, GitHub MCP, Serena, etc.)
- `constants_runtimes.go` — language runtime versions (Node, Python, Go, Bun, Deno, UV, etc.)
- `constants_jobs.go` — JobName, StepID constants for GitHub Actions jobs and steps
- `constants_misc.go` — any remaining constants that don't fit a clean category

All files must be in `package constants`. No import paths change. Run `make build && make test-unit` to verify nothing breaks.

---

Task 2: Split pkg/cli/gateway_logs.go into Focused Sub-Files

Priority: High
Estimated Effort: Medium
Focus Area: Code Organization

Description:
pkg/cli/gateway_logs.go is 1,127 lines and contains at least 4 distinct concerns: type definitions, file I/O parsing, metric aggregation, and table rendering. Split into cohesive files in pkg/cli/.

Acceptance Criteria:

• gateway_logs.go is either removed or reduced to ≤ 300 lines
• New files follow the naming pattern: gateway_logs_types.go, gateway_logs_parsing.go, gateway_logs_metrics.go, gateway_logs_rendering.go
• All new files remain in package cli
• All existing callers compile without changes
• make build && make test-unit passes

Code Region: pkg/cli/gateway_logs.go

Split `pkg/cli/gateway_logs.go` (1,127 lines) into focused sub-files within `package cli`.

Suggested split:
- `gateway_logs_types.go` — All struct type definitions (GatewayLogEntry, DifcFilteredEvent, GatewayServerMetrics, GatewayToolMetrics, GatewayMetrics, RPCMessageEntry, rpcRequestPayload, rpcToolCallParams, rpcResponsePayload, rpcError, rpcPendingRequest)
- `gateway_logs_parsing.go` — parseRPCMessages, parseGatewayLogs, processGatewayLogEntry, findRPCMessagesPath
- `gateway_logs_metrics.go` — getOrCreateServer, getOrCreateTool, calculateGatewayAggregates, buildToolCallsFromRPCMessages, extractMCPToolUsageData, displayAggregatedGatewayMetrics
- `gateway_logs_rendering.go` — renderGatewayMetricsTable, getSortedServerNames

Keep all files in `package cli`. No interface changes. Run `make build && make test-unit` to verify.

---

Task 3: Split Oversized Validator Files Back Below 300-Line Hard Limit

Priority: Medium
Estimated Effort: Medium
Focus Area: Validation Complexity

Description:
The following validator files exceed the documented 300-line hard limit in AGENTS.md: safe_outputs_validation.go (407), safe_outputs_validation_config.go (407), dispatch_workflow_validation.go (363), tools_validation.go (359), and permissions_validation.go (351). Apply the same split strategy documented in scratchpad/validation-refactoring.md.

Acceptance Criteria:

• All 5 validator files reduced to ≤ 300 lines each
• Sub-validator files named following {domain}_{subdomain}_validation.go convention
• Test files updated if validator functions move to new files
• Validation logic and error messages remain identical
• make build && make test-unit && make lint passes

Code Region: pkg/workflow/safe_outputs_validation.go, pkg/workflow/safe_outputs_validation_config.go, pkg/workflow/dispatch_workflow_validation.go, pkg/workflow/tools_validation.go, pkg/workflow/permissions_validation.go

Refactor these 5 validator files that exceed the 300-line hard limit documented in AGENTS.md:

1. `pkg/workflow/safe_outputs_validation.go` (407 lines) — split validation domains into `safe_outputs_format_validation.go` and `safe_outputs_security_validation.go` or similar
2. `pkg/workflow/safe_outputs_validation_config.go` (407 lines) — split config-specific validations
3. `pkg/workflow/dispatch_workflow_validation.go` (363 lines) — split into dispatch trigger and workflow target validations
4. `pkg/workflow/tools_validation.go` (359 lines) — split tool type vs tool config validations
5. `pkg/workflow/permissions_validation.go` (351 lines) — split read vs write permission validations

Follow the naming convention `{domain}_{subdomain}_validation.go` per AGENTS.md. Keep all files in `package workflow`. Validation logic and error messages must remain identical. Run `make build && make test-unit && make lint` to verify.

---

Task 4: Slim Down cmd/gh-aw/main.go by Extracting Command Registration

Priority: Medium
Estimated Effort: Small
Focus Area: Code Organization

Description:
cmd/gh-aw/main.go is 862 lines and contains all command registrations, flag definitions, and CLI wiring inline. The file should focus on bootstrapping and delegate command registration to helper functions or sub-files. Target: ≤ 400 lines for main.go.

Acceptance Criteria:

• cmd/gh-aw/main.go reduced to ≤ 400 lines
• Extracted registrations remain in package main
• Command groupings extracted to appropriately named files (e.g., cmd/gh-aw/commands_workflow.go, cmd/gh-aw/commands_mcp.go)
• ./gh-aw --help and all subcommands still function correctly
• make build && make test-unit passes

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

Slim down `cmd/gh-aw/main.go` (862 lines) by extracting command registration groups into separate files within `package main` in `cmd/gh-aw/`.

The main.go file currently contains all command var declarations and AddCommand() calls inline. Extract logical groups:
- `cmd/gh-aw/commands_workflow.go` — workflow management commands (compile, run, enable, disable, remove, new, hash, fix)
- `cmd/gh-aw/commands_mcp.go` — MCP-related commands (mcp subcommand tree)
- `cmd/gh-aw/commands_logs.go` — logs/audit/status commands
- `cmd/gh-aw/commands_other.go` — remaining utility commands

Keep the rootCmd, engine validation, main() function, and build variable declarations in `main.go`. Each extracted file registers its commands in an `init()` function or a `register*Commands(rootCmd)` function called from `main()`.

Run `make build` and test that `./gh-aw --help` and all subcommands still work.

---

Task 5: Add File-Size Enforcement to CI

Priority: Low
Estimated Effort: Small
Focus Area: CI/CD Quality Gates

Description:
The 300-line hard limit for validators is documented but not enforced automatically. Add a lightweight CI check (bash script or Makefile target) that fails if any file in pkg/workflow/*validation*.go or pkg/cli/*validation*.go exceeds 300 lines. This prevents future regressions.

Acceptance Criteria:

• New make check-file-sizes target in Makefile
• Check covers all *validation*.go files
• Reports the offending files and their line counts
• Exits non-zero if any file exceeds 300 lines
• CI workflow (.github/workflows/ci.yml) runs this check
• make check-file-sizes currently fails (existing violations) — document in PR that existing violations are tracked issues

Code Region: Makefile, .github/workflows/ci.yml

Add a `make check-file-sizes` target to the Makefile that enforces the 300-line hard limit on validator files documented in AGENTS.md.

The check should:
1. Find all files matching `*validation*.go` in `pkg/workflow/` and `pkg/cli/` (excluding `_test.go` files)
2. Check each file's line count
3. Print a warning for each file exceeding 300 lines: `WARNING: pkg/workflow/safe_outputs_validation.go (407 lines) exceeds 300-line hard limit`
4. Exit with code 1 if any file exceeds 300 lines

Add this target to the Makefile under the existing `lint` or `check` targets. Add it to `.github/workflows/ci.yml` as a step in the `lint` job (or a dedicated `code-quality` job).

Note: Because existing violations exist, the initial PR can add the check but use `|| true` until the validator splits (Task 3) are complete. Document the known violations in the PR description.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-03-24	Large File Complexity	Custom	Yes	5 tasks generated; 163 files identified over limit

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split constants.go (Task 1) — pure mechanical refactor, zero behavior change, high discoverability gain — Priority: High
2. Split gateway_logs.go (Task 2) — 1,127 lines is untenable; clear domain separation already exists in the functions — Priority: High

Short-term Actions (This Month)

3. Fix oversized validators (Task 3) — restores adherence to documented hard limit — Priority: Medium
4. Slim cmd/gh-aw/main.go (Task 4) — improves first-impressions for new contributors — Priority: Medium

Long-term Actions (This Quarter)

5. Add file-size CI enforcement (Task 5) — prevents regression across the whole repo — Priority: Low

---

📈 Success Metrics

Track these metrics to measure improvement in Large File Complexity:

• Files > 300 lines: 163 → target < 80 (after Tasks 1–4)
• Files > 500 lines: 72 → target < 30
• Validator files > 300 lines: 9 → target 0 (after Task 3)
• constants.go size: 1,093 lines → target ≤ 200 lines
• gateway_logs.go size: 1,127 lines → target 0 (fully split)
• main.go size: 862 lines → target ≤ 400 lines

---

Next Steps

1. Review and prioritize the 5 tasks above
2. Assign tasks to Copilot coding agent via planner agent (start with Tasks 1 & 2)
3. Track validator compliance using make check-file-sizes once Task 5 lands
4. Re-evaluate file size distribution in ~1 month

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-03-25 — Focus area will be selected based on diversity algorithm

References:

• §23492025371

AI generated by Repository Quality Improvement Agent · history

• expires on Mar 25, 2026, 1:37 PM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #22907.