[repository-quality] 🎯 Repository Quality Improvement Report - Monolithic File Risk in pkg/cli & pkg/workflow

[github-actions[bot]]

Analysis Date: 2026-08-19
Focus Area: Monolithic Go File Risk Reduction (Code Organization / Maintainability)
Strategy Type: Custom
Custom Area: Yes — this is the first tracked run (no history in cache memory), and the pre-computed metrics flagged an unusually large concentration of 1000+ line Go files (12 files ≥1000 LOC, 165 files >800 LOC) concentrated almost entirely in pkg/cli and pkg/workflow. This is a repo-specific structural risk rather than a generic quality checklist item, so a custom deep-dive was more valuable than a standard category this run.

Executive Summary

This is the inaugural quality-improvement run for gh-aw (no prior focus-area history was found in cache memory), so the pass established a baseline covering file size distribution, test-to-source ratio, and function density in the largest files. The repository is generally healthy — test LOC (543,766) nearly doubles source LOC (277,772), a strong 1.96:1 ratio — but a cluster of very large files stands out: pkg/cli/add_package_manifest.go (1330 lines, 69 functions) and pkg/parser/import_field_extractor.go (1045 lines, 51 functions) are dense with many small, loosely related functions, suggesting these files have accreted responsibilities over time and would benefit from splitting into focused sub-files by concern (following the project's own developer-code-organization skill guidance).

By contrast, pkg/workflow/safe_outputs_handler_registry.go (1074 lines) is mostly a single large declarative map literal (only 4 real functions) — its size is structural/data-driven rather than a complexity smell, so it was excluded from the refactor task list. The highest-value opportunities are add_package_manifest.go, pkg/cli/audit.go (1098 lines, 49 functions), pkg/cli/logs_metrics.go (1062 lines, 14 functions with likely large functions), and pkg/parser/import_field_extractor.go. Splitting these along existing logical boundaries (already partially reflected in their function names) will reduce single-file cognitive load, ease code review, and align with the repo's stated code-organization conventions without changing any behavior.

Full Analysis Report

Focus Area: Monolithic Go File Risk Reduction

Current State Assessment

Metrics Collected:

Metric	Value	Status
Files >800 LOC (non-vendor)	165	⚠️
Files >1000 LOC	12 (6 in pkg/workflow, 5 in pkg/cli, 1 in pkg/parser)	⚠️
Largest file	pkg/cli/add_package_manifest.go (1330 LOC, 69 funcs)	⚠️
Test LOC vs Source LOC	543,766 vs 277,772 (1.96:1)	✅
TODO/FIXME markers	38 (mostly linter test fixtures / legitimate context.TODO() refs, not backlog debt)	✅
README.md size	408 lines	✅
pkg/cli total files	914 Go files	✅ (well distributed otherwise)

Findings

Strengths

• Test coverage discipline is strong — nearly 2 lines of test code per line of source across the repo.
• Most "TODO" hits are false positives (context.TODO() usages and linter test fixtures), not real backlog debt — only a handful reference actual pending work (e.g. bootstrap_config.go, add_interactive_orchestrator.go).
• pkg/cli and pkg/workflow already use per-concern file naming conventions (e.g. add_workflow_resolution.go, workflow_errors.go), so splitting large files has clear natural seams to follow.

Areas for Improvement

• ⚠️ Medium: pkg/cli/add_package_manifest.go (1330 LOC / 69 funcs) mixes manifest parsing, validation, and resolution logic in one file.
• ⚠️ Medium: pkg/cli/audit.go (1098 LOC / 49 funcs) is the primary entry point for gh aw audit but bundles data collection, formatting, and orchestration together — companion files audit_report.go (1037) and audit_diff.go (998) suggest the split pattern already exists but audit.go itself hasn't been fully decomposed.
• ⚠️ Low-Medium: pkg/cli/logs_metrics.go (1062 LOC, only 14 funcs) implies large average function size (~76 LOC/func) — a sign of functions doing too much rather than too many small helpers.
• ⚠️ Low-Medium: pkg/parser/import_field_extractor.go (1045 LOC / 51 funcs) — extraction logic for many import field types is centralized in one file.
• ✅ Not flagged: pkg/workflow/safe_outputs_handler_registry.go (1074 LOC) is a declarative registry map, not complex logic — low refactor value.

Detailed Analysis

The pattern across pkg/cli/audit.go, pkg/cli/audit_report.go, and pkg/cli/audit_diff.go shows the team already splits large features into _report.go / _diff.go siblings — this convention should simply be extended to the remaining monoliths. For add_package_manifest.go, the 69 functions are prime candidates for grouping into add_package_manifest_parse.go, add_package_manifest_validate.go, and add_package_manifest_resolve.go (mirroring the existing add_package_manifest_mapping_test.go split for tests). For logs_metrics.go, the low function-to-line ratio suggests looking for functions exceeding ~150 lines that could be broken into smaller named helpers before splitting files. import_field_extractor.go's 51 functions likely map one-to-one with import field types/tags, making a per-category split (e.g. import_field_extractor_scalar.go, import_field_extractor_composite.go) low-risk and mechanical.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Split pkg/cli/add_package_manifest.go by responsibility

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

Description: pkg/cli/add_package_manifest.go is 1330 lines with 69 functions covering manifest parsing, validation, and resolution. Split it into cohesive sub-files (e.g. add_package_manifest_parse.go, add_package_manifest_validate.go, add_package_manifest_resolve.go) without changing any exported behavior or function signatures.

Acceptance Criteria:

• File split into 2–4 files grouped by responsibility, each under ~500 LOC
• No functional changes — make test-unit passes unchanged
• make fmt and go build ./... succeed
• Existing tests in add_package_manifest_test.go and add_package_manifest_mapping_test.go require no changes beyond file location if any test helpers moved

Code Region: pkg/cli/add_package_manifest.go

Split pkg/cli/add_package_manifest.go (1330 lines, 69 functions) into smaller, cohesive files grouped by responsibility (parsing, validation, resolution), following the existing convention in this package (e.g. add_workflow_resolution.go). Do not change any function signatures, exported API, or behavior — this is a pure file-organization refactor. Ensure `go build ./...`, `make fmt`, and `make test-unit` (targeted to pkg/cli) all pass after the split. Update package-level comments only if they reference the old single-file location.

---

Task 2: Decompose pkg/cli/audit.go following the existing audit_report/audit_diff pattern

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

Description: pkg/cli/audit.go (1098 lines, 49 functions) bundles orchestration, data collection, and formatting for gh aw audit. The package already splits related concerns into audit_report.go and audit_diff.go — extend that same pattern to audit.go itself by extracting data-collection and formatting helpers into new sibling files.

Acceptance Criteria:

• audit.go reduced to primarily command wiring/orchestration
• Data-collection and formatting logic extracted into new files (e.g. audit_collect.go, audit_format.go)
• go build ./..., make fmt, and targeted make test-unit for pkg/cli pass
• No behavior change; existing audit tests pass unmodified

Code Region: pkg/cli/audit.go

Refactor pkg/cli/audit.go (1098 lines, 49 functions) by extracting data-collection and formatting logic into new sibling files, following the existing pattern already used for audit_report.go and audit_diff.go in the same package. Keep audit.go focused on command orchestration/wiring. This is a pure code-organization change — do not alter behavior, exported signatures, or CLI output. Validate with `go build ./...`, `make fmt`, and `make test-unit` scoped to pkg/cli.

---

Task 3: Break down oversized functions in pkg/cli/logs_metrics.go

Priority: Low
Estimated Effort: Small
Focus Area: Code Quality

Description: pkg/cli/logs_metrics.go is 1062 lines with only 14 functions (~76 LOC/function average), suggesting some functions handle too many concerns. Identify functions over ~150 lines and refactor them into smaller, named helper functions to improve readability and testability, without splitting the file itself unless a natural seam emerges.

Acceptance Criteria:

• Functions exceeding ~150 LOC identified and broken into smaller named helpers
• Each extracted helper has a clear single responsibility and doc comment
• go build ./..., make fmt, targeted make test-unit for pkg/cli pass
• No behavior change to metrics output

Code Region: pkg/cli/logs_metrics.go

Review pkg/cli/logs_metrics.go (1062 lines, only 14 top-level functions) for any function exceeding ~150 lines. Refactor such functions by extracting smaller, well-named helper functions with single responsibilities and doc comments, per this repo's developer-code-organization skill guidance. Do not change metric calculation behavior or output format. Validate with `go build ./...`, `make fmt`, and `make test-unit` scoped to pkg/cli.

---

Task 4: Split pkg/parser/import_field_extractor.go by field category

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

Description: pkg/parser/import_field_extractor.go (1045 lines, 51 functions) centralizes extraction logic for many different import field types. Split it into per-category files (e.g. scalar fields, composite/list fields, nested object fields) to make it easier to locate and extend field-extraction logic.

Acceptance Criteria:

• File split into 2–3 files grouped by field-type category
• No functional changes; all existing parser tests pass unmodified
• go build ./..., make fmt, and targeted make test-unit for pkg/parser pass

Code Region: pkg/parser/import_field_extractor.go

Split pkg/parser/import_field_extractor.go (1045 lines, 51 functions) into 2-3 smaller files grouped by field-type category (e.g. scalar field extractors, composite/list field extractors, nested object extractors). This is a pure file-organization refactor — do not change function signatures, exported API, or extraction behavior. Validate with `go build ./...`, `make fmt`, and `make test-unit` scoped to pkg/parser.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-08-19	Monolithic File Risk Reduction	Custom	Y	Baseline established; 4 tasks generated targeting the 4 largest complexity-dense Go files in pkg/cli and pkg/parser

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split pkg/cli/add_package_manifest.go into responsibility-based files — Priority: Medium
2. Decompose pkg/cli/audit.go following the existing audit_report/audit_diff split pattern — Priority: Medium

Short-term Actions (This Month)

1. Break down oversized functions in pkg/cli/logs_metrics.go — Priority: Low
2. Split pkg/parser/import_field_extractor.go by field category — Priority: Low

Long-term Actions (This Quarter)

1. Establish a lint rule or CI check flagging new Go files exceeding ~800 LOC to prevent future accretion — Priority: Low

---

📈 Success Metrics

• Files >1000 LOC: 12 → 8 or fewer
• Largest file size: 1330 LOC (add_package_manifest.go) → under 600 LOC per file after split

---

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 this focus area in ~90 days (or sooner if reused per the 10% reuse rule)

---

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

Generated by ⚡ Repository Quality Improvement Agent · auto · 27.3 AIC · ⌖ 2.76 AIC · ⊞ 9.9K · ◷

• expires on Aug 20, 2026, 5:13 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-20T13:13:19.743Z.

Closed by Workflow