Repository Quality: File Size Discipline — 2026-04-01

[github-actions[bot]]

🎯 Repository Quality Improvement Report — File Size Discipline

Analysis Date: 2026-04-01
Focus Area: File Size Discipline (Custom)
Strategy Type: Custom
Custom Area: Yes — this repository has a documented hard limit of 300 lines per file (in AGENTS.md), yet several production files significantly exceed this boundary. This focus area examines those violations and provides concrete decomposition tasks.

---

Executive Summary

The codebase has an explicit "hard limit" of 300 lines per Go source file, with a stated guideline to refactor files exceeding this size. An analysis of 629 non-test source files reveals 6 files exceeding 1,000 lines and 74 files between 500–1,000 lines — representing systematic drift from the documented standard.

The worst offenders are concentrated in pkg/cli/ and pkg/workflow/, the two highest-activity packages. The pattern is consistent: files that mix multiple concerns (parsing, processing, rendering, or configuration) tend to grow organically past the limit. Each of the top offenders has clear, natural seams where it can be split into smaller, single-responsibility files without changing public APIs.

Test coverage is excellent (219% test-to-source LOC ratio), so there is good test infrastructure to validate refactoring. TODO/FIXME debt is low (7 items), suggesting this is a quality codebase with focused technical debt.

Full Analysis Report

Focus Area: File Size Discipline

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total non-test .go files	629	✅
Files > 1000 lines	6	❌
Files 500–1000 lines	74	⚠️
Files 300–500 lines	96	⚠️
Average file size	238 lines	✅
Test-to-source LOC ratio	219%	✅
TODO/FIXME count	7	✅

Files exceeding 1,000 lines (all violate hard limit):

File	Lines	Dominant Concern	Decomposition Opportunity
pkg/cli/gateway_logs.go	1,332	Types + parsing + processing + rendering	Split into 4 files
pkg/constants/constants.go	1,083	All constants (mixed domains)	Split by domain
pkg/cli/audit_report_render.go	1,045	Many render functions	Split by render area
pkg/cli/logs_report.go	1,011	Log report rendering	Split by section
pkg/cli/trial_command.go	1,007	Command + business logic	Split logic out
pkg/workflow/checkout_manager.go	1,005	State management + step generation	Split generation

Findings

Strengths

• Excellent average file size of 238 lines (well within guideline for the average case)
• Outstanding test coverage (219% LOC ratio) ensures safe refactoring
• Low TODO/FIXME debt (only 7 items) indicating focused technical attention
• Consistent use of logger and console formatting patterns
• Good function-level separation already exists in most large files

Areas for Improvement

• pkg/cli/gateway_logs.go (1,332 lines) mixes 4+ concerns: type definitions, RPC parsing, log processing, and metrics rendering — HIGH severity
• pkg/constants/constants.go (1,083 lines) bundles all constants regardless of domain — MEDIUM severity
• pkg/cli/audit_report_render.go (1,045 lines) has 25+ render functions that could be grouped into sub-files by domain — HIGH severity
• pkg/cli/trial_command.go (1,007 lines) mixes Cobra command setup with substantial business logic — HIGH severity
• pkg/workflow/checkout_manager.go (1,005 lines) conflates state management with step generation — MEDIUM severity

Detailed Analysis

gateway_logs.go is the most egregious violation at 1,332 lines. It contains: type definitions (GatewayLogEntry, GatewayMetrics, RPCMessageEntry, etc.), RPC message parsing (parseRPCMessages), gateway log processing (parseGatewayLogs, processGatewayLogEntry), and metrics rendering (renderGatewayMetricsTable). Natural split points are clearly visible from the function list.

constants.go at 1,083 lines contains all constants in a single file. The type system is well-designed (semantic types with String()/IsValid() methods), but grouping all constants together regardless of domain makes it hard to navigate. Splitting by domain (engine constants, job constants, URL constants, etc.) would improve discoverability.

audit_report_render.go has 25+ render functions. The file renders: overview, metrics, tool usage, MCP tools, guard policies, firewall analysis, recommendations, performance metrics, policy analysis, and engine config. Each cluster could be its own file.

trial_command.go at 1,007 lines is a command file that significantly exceeds the typical command file size. It likely contains business logic that should live in separate helper files.

checkout_manager.go at 1,005 lines mixes CheckoutManager state management with GitHub Actions YAML step generation. The step generation functions (GenerateCheckoutAppTokenSteps, GenerateAdditionalCheckoutSteps, etc.) could be a separate checkout_step_generator.go.

---

🤖 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. Each task is self-contained with clear acceptance criteria and a specific code region.

---

Improvement Tasks

Task 1: Split gateway_logs.go into focused files

Priority: High
Estimated Effort: Medium
Focus Area: File Size Discipline

Description:
pkg/cli/gateway_logs.go is 1,332 lines and mixes four distinct concerns. Split it into focused files without changing any public APIs or function signatures.

Acceptance Criteria:

• pkg/cli/gateway_log_types.go — all type definitions (structs, consts) currently in gateway_logs.go
• pkg/cli/gateway_log_parser.go — parseRPCMessages, parseGatewayLogs, findRPCMessagesPath
• pkg/cli/gateway_log_processor.go — processGatewayLogEntry, getOrCreateServer, getOrCreateTool, calculateGatewayAggregates, buildGuardPolicySummary
• pkg/cli/gateway_log_renderer.go — renderGatewayMetricsTable, getSortedServerNames, and any other render functions
• Original gateway_logs.go either removed or reduced to a thin orchestrating file
• All existing tests pass (go test ./pkg/cli/ -run ".*Gateway.*")
• Each new file is under 350 lines

Code Region: pkg/cli/gateway_logs.go

Split `pkg/cli/gateway_logs.go` (currently 1,332 lines) into four focused files following the existing codebase pattern of one concern per file. 

1. Create `pkg/cli/gateway_log_types.go` — move all type definitions and constants (GatewayLogEntry, DifcFilteredEvent, GuardPolicyEvent, GatewayServerMetrics, GatewayToolMetrics, GatewayMetrics, RPCMessageEntry, rpc* types, etc.)
2. Create `pkg/cli/gateway_log_parser.go` — move parseRPCMessages, findRPCMessagesPath, parseGatewayLogs and related helpers
3. Create `pkg/cli/gateway_log_processor.go` — move processGatewayLogEntry, getOrCreateServer, getOrCreateTool, calculateGatewayAggregates, buildGuardPolicySummary
4. Create `pkg/cli/gateway_log_renderer.go` — move renderGatewayMetricsTable, getSortedServerNames, and any other render helpers
5. Remove or consolidate gateway_logs.go if it becomes empty/redundant

Rules:
- Do NOT change any function signatures, type names, or package-level variable names
- Keep the same package (`package cli`)
- Keep the logger variable (`var gatewayLogsLog`) in the most appropriate file
- Run `make fmt` after changes
- Run `go test ./pkg/cli/ -run ".*[Gg]ateway.*"` to validate

---

Task 2: Split audit_report_render.go into domain-focused render files

Priority: High
Estimated Effort: Medium
Focus Area: File Size Discipline

Description:
pkg/cli/audit_report_render.go (1,045 lines) contains 25+ render functions spanning many distinct report domains. Split into domain-focused files.

Acceptance Criteria:

• pkg/cli/audit_render_overview.go — renderConsole, renderOverview, renderMetrics, renderJobsTable, renderAuditComparison
• pkg/cli/audit_render_tools.go — renderToolUsageTable, renderMCPToolUsageTable
• pkg/cli/audit_render_security.go — renderGuardPolicySummary, renderFirewallAnalysis, renderRedactedDomainsAnalysis, renderPolicyAnalysis
• pkg/cli/audit_render_insights.go — renderKeyFindings, renderRecommendations, renderAgenticAssessments, renderBehaviorFingerprint, renderTaskDomain
• pkg/cli/audit_render_metrics.go — renderPerformanceMetrics, renderEngineConfig, renderPromptAnalysis, renderSessionAnalysis, renderCreatedItemsTable, formatUnixTimestamp
• renderJSON can stay in the original audit_report_render.go or move to overview
• All existing tests pass
• Each new file is under 300 lines

Code Region: pkg/cli/audit_report_render.go

Split `pkg/cli/audit_report_render.go` (1,045 lines) into domain-focused render files. The file already has good function-level organization — just redistribute functions into logical groups.

Target split:
- `audit_render_overview.go`: renderJSON, renderConsole, renderOverview, renderMetrics, renderJobsTable, renderAuditComparison
- `audit_render_tools.go`: renderToolUsageTable, renderMCPToolUsageTable  
- `audit_render_security.go`: renderGuardPolicySummary, renderFirewallAnalysis, renderRedactedDomainsAnalysis, renderPolicyAnalysis
- `audit_render_insights.go`: renderKeyFindings, renderRecommendations, renderAgenticAssessments, renderBehaviorFingerprint, renderTaskDomain
- `audit_render_metrics.go`: renderPerformanceMetrics, renderEngineConfig, renderPromptAnalysis, renderSessionAnalysis, renderCreatedItemsTable, formatUnixTimestamp

Rules:
- Keep the same package (`package cli`)
- Do NOT change any function signatures or type definitions
- Run `make fmt` after changes
- Run `go test ./pkg/cli/ -run ".*[Aa]udit.*"` to validate

---

Task 3: Split trial_command.go by separating business logic from command setup

Priority: High
Estimated Effort: Medium
Focus Area: File Size Discipline

Description:
pkg/cli/trial_command.go (1,007 lines) exceeds the hard limit significantly. Command files should be thin wrappers; business logic should move to separate helper files.

Acceptance Criteria:

• pkg/cli/trial_command.go reduced to Cobra command setup, flag definitions, and delegation — ideally under 200 lines
• Business logic extracted to pkg/cli/trial_runner.go or appropriate named files
• All existing tests pass
• New files are each under 350 lines

Code Region: pkg/cli/trial_command.go

Refactor `pkg/cli/trial_command.go` (1,007 lines) to separate the Cobra command setup from the business logic.

1. Identify the RunE / run function logic and extract it to `pkg/cli/trial_runner.go`
2. Keep `NewTrialCommand()` in `trial_command.go` as a thin wrapper
3. Move any structs/types specific to trial logic to `pkg/cli/trial_types.go` if they make the file large
4. The goal is for `trial_command.go` to be under 200 lines and `trial_runner.go` to be under 400 lines

Follow the existing pattern in the codebase: `NewXCommand()` (thin) + `RunX()` (extracted, testable).

Rules:
- Do NOT change function signatures or exported names
- Run `make fmt` after changes  
- Run `go test ./pkg/cli/ -run ".*[Tt]rial.*"` to validate

---

Task 4: Split checkout_manager.go into state management and step generation

Priority: Medium
Estimated Effort: Small
Focus Area: File Size Discipline

Description:
pkg/workflow/checkout_manager.go (1,005 lines) mixes CheckoutManager state management with GitHub Actions YAML step generation. The step generation functions are independently testable and should be in their own file.

Acceptance Criteria:

• pkg/workflow/checkout_manager.go reduced to: type definitions, NewCheckoutManager, getters/setters, add, and any resolver logic — under 400 lines
• pkg/workflow/checkout_step_generator.go contains all Generate* functions (GenerateCheckoutAppTokenSteps, GenerateCheckoutAppTokenInvalidationSteps, GenerateAdditionalCheckoutSteps, GenerateGitHubFolderCheckoutStep, GenerateDefaultCheckoutStep, generateCheckoutStepLines)
• All existing tests pass
• Both new files under 500 lines

Code Region: pkg/workflow/checkout_manager.go

Split `pkg/workflow/checkout_manager.go` (1,005 lines) by moving all step generation functions to a new file.

1. Create `pkg/workflow/checkout_step_generator.go` in the same package (`package workflow`)
2. Move these functions to the new file:
   - GenerateCheckoutAppTokenSteps
   - GenerateCheckoutAppTokenInvalidationSteps
   - GenerateAdditionalCheckoutSteps
   - GenerateGitHubFolderCheckoutStep
   - GenerateDefaultCheckoutStep
   - generateCheckoutStepLines
3. Keep CheckoutManager type definition, NewCheckoutManager, all getters/setters, and resolver logic in `checkout_manager.go`

Rules:
- Same package (`package workflow`)
- Do NOT change any function signatures
- Run `make fmt` after changes
- Run `go test ./pkg/workflow/ -run ".*[Cc]heckout.*"` to validate

---

Task 5: Split constants.go into domain-grouped files

Priority: Medium
Estimated Effort: Small
Focus Area: File Size Discipline

Description:
pkg/constants/constants.go (1,083 lines) has all constants, types, and values in one file. Splitting by domain improves discoverability and adheres to the size guideline.

Acceptance Criteria:

• pkg/constants/engine_constants.go — EngineName type + engine constants (CopilotEngine, ClaudeEngine, etc.)
• pkg/constants/job_constants.go — JobName, StepID types + all job/step name constants
• pkg/constants/url_constants.go — URL, DocURL types + URL constants
• pkg/constants/version_constants.go — Version, ModelName types + version/model constants
• pkg/constants/constants.go — remaining general constants (CommandPrefix, LineLength, FeatureFlag, WorkflowID)
• All files compile successfully
• All existing tests pass (go test ./pkg/constants/...)
• Each file under 300 lines

Code Region: pkg/constants/constants.go

Split `pkg/constants/constants.go` (1,083 lines) into domain-grouped constant files.

The file contains several semantic types with their associated constants. Group them by domain:

1. `engine_constants.go` — EngineName type, String()/IsValid() methods, and all engine name constants (CopilotEngine, ClaudeEngine, CodexEngine, CustomEngine, etc.)
2. `job_constants.go` — JobName and StepID types with their methods and all job name / step ID constants  
3. `url_constants.go` — URL and DocURL types with their methods and all URL constants
4. `version_constants.go` — Version and ModelName types with their methods and all version/model name constants
5. `feature_constants.go` — FeatureFlag type with its methods and all feature flag constants
6. Keep `constants.go` for CommandPrefix, LineLength, WorkflowID, and any truly general constants

Rules:
- Same package (`package constants`)
- Do NOT change type names, constant names, or method signatures
- Run `make fmt` after changes
- Run `go test ./pkg/constants/...` to validate

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-01	file-size-discipline	Custom	Yes	5 decomposition tasks generated for 6 files > 1000 lines

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split gateway_logs.go (1,332 lines) — most impactful, clear seams — Priority: High
2. Split audit_report_render.go (1,045 lines) — 25+ functions, easy grouping — Priority: High

Short-term Actions (This Month)

1. Refactor trial_command.go (1,007 lines) — improves testability of business logic — Priority: High
2. Add CI lint rule to fail builds when any new file exceeds 500 lines — Priority: Medium
3. Split checkout_manager.go (1,005 lines) — natural seam already identified — Priority: Medium

Long-term Actions (This Quarter)

1. Split constants.go into domain files — lower urgency, no behavior change — Priority: Medium
2. Audit the 74 files in the 500–1,000 line range for similar decomposition opportunities
3. Add a make check-file-sizes target that reports files over the 300-line guideline

---

📈 Success Metrics

Track these metrics to measure improvement in File Size Discipline:

• Files > 1,000 lines: 6 → 0 (target after tasks complete)
• Files > 500 lines: 80 → < 20 (target after 3 months)
• Average file size: 238 lines → < 200 lines (target after 6 months)
• Largest file: 1,332 lines → < 400 lines (target after tasks complete)

---

Next Steps

1. Review and prioritize the 5 tasks above
2. Assign to Copilot coding agent via planner agent (start with Tasks 1 and 2)
3. Track file size metrics monthly
4. Re-evaluate this focus area in 30 days

---

References:

• §23851205816

AI generated by Repository Quality Improvement Agent · history

• expires on Apr 2, 2026, 1:46 PM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

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

A newer discussion is available at Discussion #24117.