[repository-quality] Repository Quality: Large Source File Decomposition

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Large Source File Decomposition

Analysis Date: 2026-10-13
Focus Area: Large Source File Decomposition
Strategy Type: Custom
Custom Area: Yes — the repo has many 800+ LOC non-test Go files, and the pre-computed metrics show this is the most visible maintainability risk.

Executive Summary

50 non-test Go files under pkg/ exceed 800 lines. The largest, pkg/cli/token_usage_subagent_session.go, is 1427 lines with 45 functions. Several others are over 1000 lines with 36–57 functions each. Test coverage is strong (647K test LOC vs 350K source LOC), so splitting is low-risk. Other metrics are healthy: 38 TODO/FIXME markers and a 462-line README.

Recommendation: split the largest files along their cohesive function groups, with no behavior changes. Guard against regrowth with a lint or CI check.

Full Analysis Report

Current State Assessment

Metrics Collected:

Metric	Value	Status
Non-test Go files >800 LOC	50	⚠️
Largest file	1427 LOC (token_usage_subagent_session.go)	❌
Test/source LOC ratio	~1.85	✅
TODO/FIXME	38	✅

Strengths

• Very high test ratio makes refactors safe.
• Files are mostly package-cohesive.

Areas for Improvement

• ❌ Functions per file: import_field_extractor.go 57, compiler_experiments.go 51, token_usage_subagent_session.go 45, logs_run_processor.go 43.
• ⚠️ add_workflow_resolution.go (1214 LOC, 38 funcs) and audit_report.go (1173 LOC, 36 funcs) mix several concerns.
• ⚠️ No guard against new files growing past the threshold.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Split token_usage_subagent_session.go

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

Description: Break the 1427-line file into cohesive files (parsing, aggregation, reporting).

Acceptance Criteria:

• No resulting file >700 LOC
• No behavior changes; make fmt and make test-unit pass

Code Region: pkg/cli/token_usage_subagent_session.go

Split pkg/cli/token_usage_subagent_session.go into focused files by responsibility, moving functions verbatim. Follow .github/skills/developer-code-organization/SKILL.md. Run make fmt and tests.

---

Task 2: Split import_field_extractor.go and compiler_experiments.go

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

Description: These have the highest function counts (57 and 51). Group by concern.

Acceptance Criteria:

• Each resulting file <700 LOC
• WASM build variants are preserved
• Tests pass

Code Region: pkg/parser/import_field_extractor.go, pkg/workflow/compiler_experiments.go

Decompose both files into cohesive files without behavior change, following the repo's file naming conventions.

---

Task 3: Split add_workflow_resolution.go and audit_report.go

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

Description: Separate resolution/fetching from validation, and report building from rendering.

Acceptance Criteria:

• Each resulting file <700 LOC
• Tests pass unchanged

Code Region: pkg/cli/add_workflow_resolution.go, pkg/cli/audit_report.go

Refactor by moving functions into new files in the same package; do not alter signatures.

---

Task 4: Add file-size regression guard

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

Description: Add a check (script or custom linter) that fails when a new non-test Go file exceeds 1000 LOC. Allowlist existing offenders.

Acceptance Criteria:

• Check runs in make lint or an equivalent target
• Existing large files are allowlisted with a shrink-only baseline

Code Region: Makefile, pkg/linters/

Implement the file-size guard following .github/skills/go-linters/SKILL.md.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-10-13	Large File Decomposition	Custom	Y	4 tasks

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split the top 3 largest files — Priority: High

Short-term Actions (This Month)

1. Add the size guard — Priority: Medium

Long-term Actions (This Quarter)

1. Reduce the >800 LOC count from 50 to under 25 — Priority: Low

---

📈 Success Metrics

• Files >800 LOC: 50 → 25
• Largest file: 1427 → <1000 LOC

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate in 1 month

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-10-14 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · 15.1 AIC · ⌖ 0.647 AIC · ⊞ 9.8K · ◷

• expires on Oct 14, 2026, 5:11 AM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #68700.