[repository-quality] Repository Quality Improvement Report — Large File Decomposition Debt (2026-04-14)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Large File Decomposition Debt

Analysis Date: 2026-04-14
Focus Area: Large File Decomposition Debt (Custom)
Strategy Type: Custom — first run, no prior history
Rationale: The AGENTS.md documents an explicit hard limit of 300 lines per file with a target of 100–200 lines. Auditing compliance with this policy surfaces concrete, high-impact refactoring opportunities that directly improve maintainability and reviewability.

---

Executive Summary

Analysis of the 675 non-test Go source files reveals significant decomposition debt: 179 files (26.5%) exceed the documented 300-line hard limit, including 6 files at 1,000+ lines. The worst offenders are concentrated in pkg/cli/ (audit and logs subsystems) and pkg/workflow/ (compiler pipeline). These files mix multiple logical domains and would benefit from the naming convention {domain}_{subdomain}.go documented in AGENTS.md.

The good news is that the codebase already demonstrates disciplined splitting in many places (e.g., the compile pipeline is decomposed into compile_config.go, compile_validation.go, compile_orchestrator.go, etc.). The tasks below bring the remaining hot-spots in line with that same pattern, prioritising the six files that violate the hard limit first.

Full Analysis Report

Focus Area: Large File Decomposition Debt

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total non-test Go files	675	✅
Files > 300 lines (hard limit)	179 (26.5 %)	❌
Files > 500 lines	81 (12.0 %)	❌
Files ≥ 1 000 lines (critically oversized)	6	❌
TODO / FIXME count (non-test)	7	✅

Top Offenders (≥ 1 000 lines):

File	Lines	Primary Concern
pkg/cli/audit_report_render.go	1 139	10+ distinct render functions across unrelated domains
pkg/workflow/compiler_orchestrator_workflow.go	1 102	Orchestration + 8 helper extraction functions
pkg/cli/logs_orchestrator.go	1 075	Download orchestration + filtering + concurrency
pkg/cli/gateway_logs.go	1 066	RPC parsing + gateway log parsing + aggregation + tool calls
pkg/cli/logs_report.go	1 065	15+ independent builder functions across 7 report domains
pkg/workflow/compiler_safe_outputs_config.go	1 035	Handler config generation for many handler types

Findings

Strengths

• Many areas already follow good decomposition (compile pipeline, codemod files, MCP server files).
• The 496 files under 300 lines (73.5 %) confirm the policy is widely respected.
• Naming conventions ({domain}_{subdomain}.go) are consistently applied where splitting has already occurred.

Areas for Improvement

• CRITICAL: 6 files exceed 1 000 lines — direct violation of the hard limit. ❌
• HIGH: 75 files in the 500–999 line range need attention. ⚠️
• MEDIUM: 98 files in the 300–499 range should be evaluated for splitting. ⚠️
• pkg/cli/audit_report_render.go mixes 10+ render domains (overview, metrics, jobs, tools, MCP, firewall, guard policies, key findings, recommendations, redacted domains, created items). Each domain independently satisfies the "2+ distinct domains" splitting criterion.
• pkg/cli/gateway_logs.go mixes RPC message parsing, gateway log parsing, tool call extraction, and aggregation — 4 independent concerns.
• pkg/cli/logs_report.go has 15+ independent build* functions for completely separate report sections that do not share state.

---

🤖 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 Claude to process.

---

Task 1: Split audit_report_render.go by render domain

Priority: High
Estimated Effort: Medium
Focus Area: Large File Decomposition
Code Region: pkg/cli/audit_report_render.go (1 139 lines)

Description:
audit_report_render.go contains 10+ logically independent render functions. Split it into focused files following the audit_report_render_{domain}.go naming pattern. Each split file should contain the functions for exactly one render domain.

Suggested split:

• audit_report_render_overview.go — renderOverview, renderMetrics
• audit_report_render_jobs.go — renderJobsTable
• audit_report_render_tools.go — renderToolUsageTable, renderMCPToolUsageTable
• audit_report_render_firewall.go — renderFirewallAnalysis, renderRedactedDomainsAnalysis
• audit_report_render_guard.go — renderGuardPolicySummary
• audit_report_render_findings.go — renderKeyFindings, renderRecommendations, renderCreatedItemsTable
• Keep renderConsole, renderJSON, and renderAuditComparison in the original file (entry points)

Acceptance Criteria:

• Original audit_report_render.go is ≤ 300 lines after the split
• Each new file is ≤ 300 lines
• All exported and unexported symbols remain accessible (same package)
• make build && make test-unit pass without errors
• make fmt && make lint pass without errors

Split `pkg/cli/audit_report_render.go` (currently 1139 lines) into focused sub-files.
Each sub-file should cover exactly one render domain, following the existing pattern used
in the compile pipeline. Keep the entry-point functions (`renderConsole`, `renderJSON`,
`renderAuditComparison`) in the original file and move each domain-specific render function
to a new file named `audit_report_render_{domain}.go`.

After splitting:
1. Run `make fmt` to format all new files.
2. Run `make lint` to ensure no linting issues.
3. Run `make build` to verify compilation.
4. Run `make test-unit` to ensure no regressions.

---

Task 2: Split gateway_logs.go by concern

Priority: High
Estimated Effort: Medium
Focus Area: Large File Decomposition
Code Region: pkg/cli/gateway_logs.go (1 066 lines)

Description:
gateway_logs.go mixes four independent concerns: type definitions, RPC message parsing, gateway log parsing, MCP tool-call extraction, and aggregation. Split into files aligned with each concern.

Suggested split:

• gateway_logs_types.go — all type/struct definitions (lines ~1–103)
• gateway_logs_rpc.go — parseRPCMessages, findRPCMessagesPath, buildToolCallsFromRPCMessages
• gateway_logs_parsing.go — parseGatewayLogs, processGatewayLogEntry, getOrCreateServer, getOrCreateTool
• gateway_logs_aggregation.go — calculateGatewayAggregates, buildGuardPolicySummary
• gateway_logs_mcp.go — extractMCPToolUsageData

Acceptance Criteria:

• Original gateway_logs.go is ≤ 300 lines (or removed if entirely replaced)
• Each new file is ≤ 300 lines
• make build && make test-unit pass without errors
• make fmt && make lint pass without errors

Split `pkg/cli/gateway_logs.go` (1066 lines) into concern-aligned files:
- `gateway_logs_types.go` for all struct/type definitions
- `gateway_logs_rpc.go` for RPC message parsing functions
- `gateway_logs_parsing.go` for gateway log parsing
- `gateway_logs_aggregation.go` for aggregation and guard policy summary
- `gateway_logs_mcp.go` for MCP tool usage extraction

After splitting, run `make fmt && make lint && make build && make test-unit`.

---

Task 3: Split logs_report.go by report section

Priority: Medium
Estimated Effort: Medium
Focus Area: Large File Decomposition
Code Region: pkg/cli/logs_report.go (1 065 lines)

Description:
logs_report.go contains 15+ independent builder functions, each constructing a completely separate section of the logs report. These functions share no state and can be cleanly separated.

Suggested split:

• logs_report_tools.go — buildToolUsageSummary, isValidToolName
• logs_report_mcp.go — buildMCPFailuresSummary, buildMCPToolUsageSummary
• logs_report_firewall.go — buildFirewallLogSummary, buildRedactedDomainsSummary, buildAccessLogSummary, aggregateDomainStats, convertDomainsToSortedSlices
• logs_report_errors.go — buildCombinedErrorsSummary, buildMissingToolsSummary, buildMissingDataSummary
• Keep top-level buildLogsData, renderLogsConsole, renderLogsJSON, writeSummaryFile, and helper types in logs_report.go

Acceptance Criteria:

• Original logs_report.go is ≤ 300 lines
• Each new file is ≤ 300 lines
• make build && make test-unit pass without errors
• make fmt && make lint pass without errors

Split `pkg/cli/logs_report.go` (1065 lines) into section-focused files. Move each group
of independent builder functions to its own file:
- `logs_report_tools.go` — tool usage builders
- `logs_report_mcp.go` — MCP failure and tool usage builders
- `logs_report_firewall.go` — firewall, access log, and redacted domain builders
- `logs_report_errors.go` — error and missing-tool builders

Keep the orchestration functions and type definitions in `logs_report.go`.
After splitting, run `make fmt && make lint && make build && make test-unit`.

---

Task 4: Split compiler_safe_outputs_config.go by handler group

Priority: Medium
Estimated Effort: Medium
Focus Area: Large File Decomposition
Code Region: pkg/workflow/compiler_safe_outputs_config.go (1 035 lines)

Description:
compiler_safe_outputs_config.go generates the GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG env variable consumed by the JavaScript safe-outputs runner. It mixes builder infrastructure, individual handler config functions, and the top-level orchestrator. Split by handler group.

Suggested split:

• compiler_safe_outputs_builder.go — handlerConfigBuilder struct and all its methods
• compiler_safe_outputs_handlers.go — individual handler config generators (issues, PRs, comments, discussions, etc.)
• Keep the top-level orchestrator and GenerateSafeOutputsHandlerConfig in the original file

Acceptance Criteria:

• Original compiler_safe_outputs_config.go is ≤ 300 lines
• Each new file is ≤ 300 lines
• make build && make test-unit pass without errors
• make fmt && make lint pass without errors

Split `pkg/workflow/compiler_safe_outputs_config.go` (1035 lines):
1. Move the `handlerConfigBuilder` struct and all its builder methods to
   `compiler_safe_outputs_builder.go`.
2. Move individual handler config generator functions to
   `compiler_safe_outputs_handlers.go`.
3. Keep the top-level orchestration and `GenerateSafeOutputsHandlerConfig` in the
   original file.

After splitting, run `make fmt && make lint && make build && make test-unit`.

---

Task 5: Evaluate and decompose pkg/workflow/frontmatter_types.go

Priority: Low
Estimated Effort: Small
Focus Area: Large File Decomposition
Code Region: pkg/workflow/frontmatter_types.go (957 lines)

Description:
frontmatter_types.go contains both type definitions and parsing logic in a single file. Per AGENTS.md conventions, parsing functions should live in a separate file when the combination exceeds the threshold.

Suggested split:

• Keep all type and struct declarations in frontmatter_types.go (target ≤ 300 lines)
• Move ParseFrontmatterConfig, parseRuntimesConfig, parsePermissionsConfig, and other parse functions to frontmatter_parsing.go

Acceptance Criteria:

• frontmatter_types.go contains only type/struct declarations and is ≤ 300 lines
• New frontmatter_parsing.go is ≤ 300 lines
• make build && make test-unit pass without errors
• make fmt && make lint pass without errors

Split `pkg/workflow/frontmatter_types.go` (957 lines) by separating type definitions
from parsing functions:
1. Keep all struct/type declarations in `frontmatter_types.go`.
2. Move `ParseFrontmatterConfig`, `parseRuntimesConfig`, `parsePermissionsConfig`,
   and any other parsing helpers to a new `frontmatter_parsing.go` file.

After splitting, run `make fmt && make lint && make build && make test-unit`.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-14	Large File Decomposition Debt	Custom	Yes	5 tasks generated targeting 6 files ≥ 1 000 lines

This is the first recorded run.

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split audit_report_render.go — largest single violation at 1 139 lines, cleanest domain boundaries — Priority: High
2. Split gateway_logs.go — 4 orthogonal concerns, straightforward extraction — Priority: High

Short-term Actions (This Month)

3. Split logs_report.go — 15+ independent builder functions — Priority: Medium
4. Split compiler_safe_outputs_config.go — clear builder / handler separation — Priority: Medium

Long-term Actions (This Quarter)

5. Decompose frontmatter_types.go — types vs. parsing separation — Priority: Low
6. Systematic pass over 500–999 line files — 75 files need evaluation — Priority: Low

---

📈 Success Metrics

Track these metrics to measure improvement in Large File Decomposition Debt:

• Files > 300 lines: 179 → target ≤ 50 (after addressing 500+ line files)
• Files ≥ 1 000 lines: 6 → target 0
• Average file size: currently ~175 lines → target ≤ 150 lines
• Max file size: 1 139 lines → target ≤ 300 lines

---

Next Steps

1. Review and prioritize the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate remaining 500+ line files after high-priority tasks are complete

---

References:

• §24400995446

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

• expires on Apr 15, 2026, 1:22 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 #26431.