[repository-quality] 🎯 Repository Quality Improvement Report - Monolithic File Decomposition & Single-Responsibility Violations

[github-actions[bot]]

Analysis Date: 2026-08-11
Focus Area: Monolithic File Decomposition (Code Organization / Code Quality hybrid)
Strategy Type: Custom
Custom Area: Yes — the standard "Code Organization" category was too generic; the repo's own metrics show a specific, actionable pattern (25 files >900 LOC, several with 40-55 top-level functions) that a generic category wouldn't surface with concrete file targets.

Executive Summary

gh-aw's Go codebase (272K source LOC vs. 529K test LOC — a healthy ~1.9x test ratio) has accumulated a cluster of oversized, multi-responsibility files. 25 non-test .go files exceed 900 lines, and 87 exceed 600 lines. Several of these — pkg/workflow/compiler_types.go (55 top-level functions), pkg/parser/import_field_extractor.go (51), pkg/cli/audit.go (49), and pkg/cli/add_package_manifest.go (47) — mix unrelated concerns (option builders, compiler state mutators, command wiring, business logic) in a single file, making them slow to navigate, risky to review, and prone to merge conflicts given their high edit frequency (update_actions.go and compiler_custom_jobs.go are both actively churned, per git log).

None of these files are missing test coverage (all three sampled have dedicated _test.go files), so the risk is not correctness but maintainability: reviewers must scroll through hundreds of unrelated lines to find a single symbol, and the high function count per file makes grep-based navigation the primary discovery tool instead of package structure. The pkg/workflow and pkg/cli packages carry most of this weight (3,185 files total in pkg/), suggesting these two packages have grown faster than their internal organization has kept pace.

We recommend a set of surgical splits (not full rewrites) that group functions by concern — e.g., separating compiler_types.go's builder/option functions from its Compiler struct mutators, and splitting audit.go's CLI command wiring from its audit execution/report logic. Each task below targets one file with a clear split boundary and preserves existing tests by relocating them alongside their functions.

Full Analysis Report

Focus Area: Monolithic File Decomposition & Single-Responsibility Violations

Current State Assessment

The codebase organizes logic primarily by package (pkg/workflow, pkg/cli, pkg/parser), but within packages many files have grown into de facto "kitchen sink" modules. This was measured directly rather than inferred:

Metrics Collected:

Metric	Value	Status
Files >900 LOC (non-test)	25	⚠️
Files >600 LOC (non-test)	87	⚠️
Total source LOC (pkg/)	269,815	i️
Test LOC vs Source LOC	528,980 / 272,175 (1.9x)	✅
Files with >20 top-level funcs	55+ (top offender: compiler_types.go)	⚠️
switch statement count (pkg/cli + pkg/workflow)	720	⚠️ (dispatch-heavy)
TODO/FIXME markers	41	✅
README size	415 lines	✅

Findings

Strengths

• Test coverage ratio (1.9x test-to-source LOC) is strong; all sampled oversized files already have dedicated _test.go companions, so splitting is low-risk from a coverage standpoint.
• Package-level separation (workflow, cli, parser) is sound; the problem is intra-package file granularity, not overall architecture.
• Low TODO/FIXME count (41) indicates the team keeps technical debt markers in check rather than letting them accumulate silently.

Areas for Improvement

• [High] pkg/workflow/compiler_types.go has 55 top-level functions mixing CompilerOption builders (WithVerbose, WithEngineOverride, ...) with *Compiler method mutators (SetSkipValidation, SetContext, ...) — two distinct concerns (functional-options construction vs. runtime state mutation) in one 900+ line file.
• [High] pkg/cli/audit.go (49 functions, 1095 LOC) mixes Cobra command registration (NewAuditCommand, registerAuditCommandFlags) with core audit execution logic (AuditWorkflowRun, runAuditMulti) and low-level error classification helpers (isPermissionError, isPermissionErrorStr).
• [Medium] pkg/parser/import_field_extractor.go (1045 LOC, 51 functions) is the largest file in pkg/parser, disproportionate to the package's typical file size, suggesting extraction-related logic should be split by field type or extraction phase.
• [Medium] pkg/cli/add_package_manifest.go (997 LOC, 47 functions) and pkg/cli/update_actions.go (1144 LOC, actively churned per git log) are both large cli files under continuous edit, increasing merge-conflict risk for concurrent contributors.
• [Low] High switch statement density (720 across two packages) suggests some dispatch logic could be table-driven or moved to smaller per-case files, though this is secondary to the file-size issue.

Detailed Analysis

The four target files below were chosen because each has (a) a clear, mechanical split boundary along existing naming/semantic lines, (b) existing test coverage that can be relocated without new test-writing effort, and (c) high enough LOC/function-count to meaningfully reduce review and navigation burden once split.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Split pkg/workflow/compiler_types.go into options and mutators files

Priority: High
Estimated Effort: Medium
Focus Area: Monolithic File Decomposition

Description: pkg/workflow/compiler_types.go (1000+ lines, 55 top-level functions) mixes two distinct concerns: (1) CompilerOption functional-option constructors (e.g. WithVerbose, WithEngineOverride, WithSkipValidation, WithNoEmit, WithFailFast, WithWorkflowIdentifier, WithVersion) and (2) *Compiler struct method setters/getters (e.g. SetSkipValidation, SetContext, SetModelPricingResolver, SetRequireDocker, SetQuiet, SetBatchMode, GetExperimentalFeatureUsage). Split into pkg/workflow/compiler_options.go (all With* functional options and the CompilerOption type) and keep compiler_types.go for the Compiler struct definition, NewCompiler, and its methods. Move corresponding test cases from compiler_types_test.go into a new compiler_options_test.go following the same split.

Acceptance Criteria:

• pkg/workflow/compiler_options.go created containing all With* option constructor functions and the CompilerOption type alias
• pkg/workflow/compiler_types.go retains only Compiler struct, NewCompiler, and Set*/Get* methods
• Corresponding tests relocated/split to match; go build ./... and go test ./pkg/workflow/... pass with no behavior change
• No public API signatures changed (pure file-move refactor)

Code Region: pkg/workflow/compiler_types.go (lines 1–220, functional options section)

Refactor pkg/workflow/compiler_types.go in the gh-aw repository. This file currently mixes two concerns: CompilerOption functional-option constructors (functions named With*, such as WithVerbose, WithEngineOverride, WithSkipValidation, WithNoEmit, WithFailFast, WithWorkflowIdentifier, WithVersion) and *Compiler struct methods (NewCompiler, SetSkipValidation, SetContext, SetModelPricingResolver, SetRequireDocker, SetQuiet, SetBatchMode, GetExperimentalFeatureUsage, etc.).

Task: Create a new file pkg/workflow/compiler_options.go containing the CompilerOption type and all With* functional-option constructor functions, moved verbatim from compiler_types.go. Leave pkg/workflow/compiler_types.go containing only the Compiler struct definition, NewCompiler, and the Set*/Get* methods. Do not change any function signatures or behavior — this is a pure code-organization move within the same package (pkg/workflow), so no import changes are needed elsewhere in the codebase.

Also split the corresponding test file: move test functions that test the With* option constructors from compiler_types_test.go (if present) into a new compiler_options_test.go, keeping the remaining Compiler-struct-method tests in compiler_types_test.go.

After the move, run `go build ./...` and `go test ./pkg/workflow/...` to confirm no build or test breakage. Run `make fmt` after the change. Do not modify any other files.

---

Task 2: Split pkg/cli/audit.go into command wiring, execution, and error-classification files

Priority: High
Estimated Effort: Medium
Focus Area: Monolithic File Decomposition

Description: pkg/cli/audit.go (1095 lines, 49 functions) combines three distinct responsibilities: Cobra CLI command registration (NewAuditCommand, registerAuditCommandFlags, runAuditCommand, getAuditCommandOptions, resolveAuditCommandArgs), core audit execution (runAuditSingle, runAuditMulti, AuditWorkflowRun, newAuditRunConfig, resolveAuditHostname, resolveAuditOutputDir, ensureAuditNotCancelled, applyAuditRepoFlag), and low-level error classification helpers (isPermissionErrorStr, isPermissionError). Split into pkg/cli/audit_command.go (Cobra wiring) and pkg/cli/audit_errors.go (error classification helpers), keeping audit.go for the core AuditWorkflowRun execution logic.

Acceptance Criteria:

• pkg/cli/audit_command.go created with NewAuditCommand, registerAuditCommandFlags, runAuditCommand, getAuditCommandOptions, resolveAuditCommandArgs
• pkg/cli/audit_errors.go created with isPermissionErrorStr, isPermissionError
• pkg/cli/audit.go retains runAuditSingle, runAuditMulti, AuditWorkflowRun, newAuditRunConfig, resolveAuditHostname, resolveAuditOutputDir, ensureAuditNotCancelled, applyAuditRepoFlag
• go build ./... and go test ./pkg/cli/... pass with no behavior change; no public API changes

Code Region: pkg/cli/audit.go (lines 94–300)

Refactor pkg/cli/audit.go in the gh-aw repository (package pkg/cli). This file (around 1095 lines, 49 functions) mixes three responsibilities: Cobra CLI command wiring, core audit execution logic, and low-level error classification helpers.

Task:
1. Create pkg/cli/audit_command.go containing the Cobra command wiring functions moved verbatim from audit.go: NewAuditCommand, registerAuditCommandFlags, runAuditCommand, getAuditCommandOptions, resolveAuditCommandArgs.
2. Create pkg/cli/audit_errors.go containing the error classification helpers moved verbatim from audit.go: isPermissionErrorStr, isPermissionError.
3. Leave pkg/cli/audit.go containing only the core audit execution logic: runAuditSingle, runAuditMulti, AuditWorkflowRun, newAuditRunConfig, resolveAuditHostname, resolveAuditOutputDir, ensureAuditNotCancelled, applyAuditRepoFlag.

This is a pure code-organization move within the same package — do not change any function signatures, exported names, or behavior. Existing tests in audit_test.go should continue to pass unchanged since the package is the same.

After the move, run `go build ./...` and `go test ./pkg/cli/...` to confirm no breakage, then run `make fmt`. Do not modify any other files.

---

Task 3: Extract error-classification and helper logic from pkg/parser/import_field_extractor.go

Priority: Medium
Estimated Effort: Medium
Focus Area: Monolithic File Decomposition

Description: pkg/parser/import_field_extractor.go (1045 lines, 51 functions) is disproportionately large compared to typical files in pkg/parser. Identify the logically distinct extraction phases/field-type groups within this file (e.g., string-field extraction vs. list/map-field extraction vs. validation helpers) and split into 2 focused files, e.g. pkg/parser/import_field_extractor.go (core dispatch/entry points) and pkg/parser/import_field_validators.go (validation-only helper functions).

Acceptance Criteria:

• File split into at least 2 files along a clear semantic boundary (documented in the PR description)
• All existing exported/unexported function names and signatures unchanged
• go build ./... and go test ./pkg/parser/... pass with no behavior change

Code Region: pkg/parser/import_field_extractor.go

Refactor pkg/parser/import_field_extractor.go in the gh-aw repository (package pkg/parser). This file is 1045 lines with 51 top-level functions, making it the largest file in pkg/parser and disproportionate to sibling files in the package.

Task: Read through the file and identify a clear semantic split — typically extraction/parsing entry-point functions vs. lower-level validation or helper functions that support them. Move the validation/helper functions (functions that check, sanitize, or validate already-extracted field values, as opposed to functions that perform the extraction/parsing itself) into a new file pkg/parser/import_field_validators.go. Leave the core extraction/dispatch functions in import_field_extractor.go.

This must be a pure move — do not rename, change signatures, or alter behavior of any function. Keep all functions in the same package (pkg/parser) so no external imports change.

After the split, run `go build ./...` and `go test ./pkg/parser/...` to confirm the change is behavior-preserving, then run `make fmt`. In the PR description, briefly document the semantic boundary you used for the split. Do not modify any other files.

---

Task 4: Split Cobra command registration out of pkg/cli/add_package_manifest.go

Priority: Medium
Estimated Effort: Small

Description: pkg/cli/add_package_manifest.go (997 lines, 47 functions) is one of several large, actively-edited files in pkg/cli (alongside update_actions.go at 1144 lines). Reduce merge-conflict risk and improve navigability by separating the Cobra command/flag registration boilerplate from the core package-manifest business logic (manifest parsing, generation, and validation functions), following the same pattern used for the audit.go split in Task 2.

Acceptance Criteria:

• Cobra command construction/flag-registration functions moved to a new pkg/cli/add_package_manifest_command.go
• Core manifest logic remains in pkg/cli/add_package_manifest.go
• go build ./... and go test ./pkg/cli/... pass with no behavior change

Code Region: pkg/cli/add_package_manifest.go

Refactor pkg/cli/add_package_manifest.go in the gh-aw repository (package pkg/cli). This file is 997 lines with 47 functions, mixing Cobra CLI command/flag registration wiring with core package-manifest business logic (parsing, generating, and validating package manifests).

Task: Identify the Cobra command construction and flag-registration functions (functions that build *cobra.Command instances or register flags on them) and move them verbatim into a new file pkg/cli/add_package_manifest_command.go. Leave the core manifest parsing/generation/validation logic in pkg/cli/add_package_manifest.go.

This is a pure code-organization move — preserve all function signatures, exported names, and behavior exactly. Both files remain in package pkg/cli so no import changes are needed elsewhere.

After the split, run `go build ./...` and `go test ./pkg/cli/...` to confirm no breakage, then run `make fmt`. Do not modify any other files.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-08-11	Monolithic File Decomposition & Single-Responsibility Violations	Custom	Y	First run — no prior history available; established baseline metrics (25 files >900 LOC, 87 files >600 LOC)

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split pkg/workflow/compiler_types.go and pkg/cli/audit.go (Tasks 1–2) — Priority: High

Short-term Actions (This Month)

1. Split pkg/parser/import_field_extractor.go and pkg/cli/add_package_manifest.go (Tasks 3–4) — Priority: Medium
2. Audit remaining files >900 LOC for similar split opportunities — Priority: Medium

Long-term Actions (This Quarter)

1. Establish a soft file-size lint threshold (e.g., 700 LOC) as a CI advisory check to prevent future monolith growth — Priority: Low

---

📈 Success Metrics

• Files >900 LOC (non-test): 25 → target 20 or fewer after Tasks 1–4
• Max top-level functions per file: 55 (compiler_types.go) → target ≤30 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 1 quarter (after splits land) or pivot to a new area next run

---

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

Generated by ⚡ Repository Quality Improvement Agent · auto · 25.4 AIC · ⌖ 3.63 AIC · ⊞ 9.4K · ◷

• expires on Aug 12, 2026, 5:19 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 #52298.