[repository-quality] 🎯 Repository Quality Improvement Report - Code Organization (2026-08-04)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Code Organization

Analysis Date: 2026-08-04
Focus Area: Code Organization
Strategy Type: Standard
Custom Area: No

Executive Summary

The gh-aw codebase (267K source LOC / 517K test LOC across 3,119 files under pkg/) has a documented file-size guideline in .github/skills/developer-code-organization/SKILL.md recommending 100–500 line files, yet 15 non-test Go files currently exceed 1,000 lines and 83 exceed 600 lines. The largest offenders — pkg/workflow/awf_helpers.go (1,148 lines, 29 functions), pkg/cli/update_actions.go (1,144 lines, 18 functions), and pkg/workflow/compiler_custom_jobs.go (1,106 lines, 36 functions) — mix multiple unrelated concerns (feature-flag capability checks, command/arg building, job-property extraction) in single files, making them harder to navigate and review.

These files are strong refactor candidates because their functions already cluster into clear, independently testable groups (e.g., awfSupports* capability-check functions form a natural awf_capabilities.go file; extractCustomJob* functions form a natural compiler_custom_jobs_extract.go file). Splitting by functionality — consistent with the "Group by Functionality, Not by Type" pattern already documented — would reduce single-file cognitive load without changing behavior, and is low-risk since it is a pure code-move refactor covered by existing unit tests.

We recommend tackling the three largest files first as independent, reviewable PRs, followed by tracking future large files with a lightweight lint/CI check.

Full Analysis Report

Focus Area: Code Organization

Current State Assessment

Metrics Collected:

Metric	Value	Status
Files >1000 LOC (non-test)	15	⚠️
Files >600 LOC (non-test)	83	⚠️
Test LOC vs Source LOC	517,126 vs 267,469 (1.93x)	✅
TODO/FIXME markers	41	✅
Directories under pkg/	35	✅
Largest file	pkg/workflow/awf_helpers.go (1,148 lines, 29 funcs)	⚠️

Findings

Strengths

• Test coverage ratio is healthy (test LOC nearly 2x source LOC).
• Codebase already follows a documented functionality-based file organization convention (developer-code-organization skill) with good examples (create_issue.go, add_comment.go).
• TODO/FIXME count (41) is low relative to codebase size, indicating good technical-debt hygiene.

Areas for Improvement

• ⚠️ Medium: 15 files exceed 1,000 lines, violating the documented 100–500 line guideline by 2-10x.
• ⚠️ Medium: awf_helpers.go mixes AWF command building (BuildAWFCommand, BuildAWFArgs, ~600 lines) with unrelated capability-check predicates (awfSupports*, 10 small functions) and chroot config JSON builders.
• ⚠️ Low: update_actions.go combines action-version resolution (getLatestActionRelease*), git-based tag lookup, skill-ref updating, and workflow-file rewriting — four distinct responsibilities in one file.
• ⚠️ Low: No automated file-size lint currently enforces the documented guideline, so large files can grow unchecked.

Detailed Analysis

pkg/workflow/awf_helpers.go (1,148 lines):

• Lines 229–809: BuildAWFCommand / BuildAWFArgs / GetAWFCommandPrefix — core AWF invocation building (~580 lines, cohesive, could stay or move to awf_command_builder.go).
• Lines 1028–1126: ten awfSupports*(firewallConfig *FirewallConfig) bool predicates plus awfVersionAtLeast — a clean, extractable "capability matrix" module (~100 lines) → candidate for new file pkg/workflow/awf_capabilities.go.
• Lines 1126–1148+: chroot config JSON/bash builders — candidate for awf_chroot_config.go.

pkg/cli/update_actions.go (1,144 lines):

• Lines 403–804: action release resolution via GitHub API and git (getLatestActionRelease*, getLatestActionReleaseViaGit, parseActionTagRefs, findCooledDownActionVersion, getActionSHAForTag) — candidate for update_actions_release_resolver.go.
• Lines 804–1144: workflow-file and skill-ref rewriting (updateActionsInWorkflowFiles, updateSkillRefsInContent*, updateActionRefsInContentWithDeps) — candidate for update_actions_file_rewriter.go.

pkg/workflow/compiler_custom_jobs.go (1,106 lines):

• 15 of 36 functions are extractCustomJob* property extractors (env, container, services, timeout, concurrency, outputs, etc.) — candidate for compiler_custom_jobs_extract.go, leaving job-building orchestration (buildCustomJob*) in the main file.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Split AWF capability-check predicates out of awf_helpers.go

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

Description: Extract the ten awfSupports* boolean predicate functions plus awfVersionAtLeast (lines ~1041–1125 of pkg/workflow/awf_helpers.go) into a new file pkg/workflow/awf_capabilities.go. This is a pure code move — no logic changes.

Acceptance Criteria:

• New file pkg/workflow/awf_capabilities.go contains the moved functions with matching package/imports
• pkg/workflow/awf_helpers.go no longer contains these functions
• make fmt and make test-unit (or targeted go test ./pkg/workflow/...) pass unchanged
• No behavior change; only file relocation

Code Region: pkg/workflow/awf_helpers.go lines 1041-1125 (awfSupports*, awfVersionAtLeast functions)

In pkg/workflow/awf_helpers.go, move the following functions (and only these) into a new file pkg/workflow/awf_capabilities.go, keeping the same package (workflow) and copying only the imports each moved function actually needs: awfVersionAtLeast, awfSupportsExcludeEnv, awfSupportsCliProxy, awfSupportsAllowHostPorts, awfSupportsDockerHostPathPrefix, awfSupportsTokenSteering, awfSupportsChrootConfig, awfSupportsContainerRuntime, awfSupportsLegacySecurity, awfSupportsDefaultAiCreditsPricing, awfSupportsAPIProxyProviders, awfSupportsBoundedQueries. Do not change any function signatures or logic. After moving, run `make fmt` and `go build ./...` and `go test ./pkg/workflow/...` to confirm nothing breaks. Remove now-unused imports from awf_helpers.go if any.

---

Task 2: Split action-release resolution logic out of update_actions.go

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

Description: Extract the GitHub API/git-based action-version resolution functions (lines ~403–804 of pkg/cli/update_actions.go) into a new file pkg/cli/update_actions_release_resolver.go, separating "how do we find the latest version" from "how do we rewrite files" concerns.

Acceptance Criteria:

• New file pkg/cli/update_actions_release_resolver.go contains getLatestActionRelease, getLatestActionReleaseWithDeps, getLatestActionReleaseViaGit, parseActionTagRefs, findCooledDownActionVersion, getActionSHAForTag
• pkg/cli/update_actions.go reduced by ~400 lines with no behavior change
• make fmt and go test ./pkg/cli/... (or targeted subset) pass

Code Region: pkg/cli/update_actions.go lines 403-804

In pkg/cli/update_actions.go, move these functions (and only these) into a new file pkg/cli/update_actions_release_resolver.go in the same package (cli): getLatestActionRelease, getLatestActionReleaseWithDeps, getLatestActionReleaseViaGit, parseActionTagRefs, findCooledDownActionVersion, getActionSHAForTag. Preserve exact signatures and logic; only relocate code and adjust imports (remove unused imports from update_actions.go, add needed imports to the new file). Run `make fmt`, `go build ./...`, and `go test ./pkg/cli/... -run TestUpdateActions` (or the closest matching test names) to verify no regressions.

---

Task 3: Extract custom job property extractors into a dedicated file

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

Description: Move the 15 extractCustomJob* functions from pkg/workflow/compiler_custom_jobs.go (env, container, services, timeout, concurrency, outputs, continue-on-error, environment, runs-on extraction) into a new file pkg/workflow/compiler_custom_jobs_extract.go, leaving job orchestration (buildCustomJob, buildCustomJobs) in the original file.

Acceptance Criteria:

• New file pkg/workflow/compiler_custom_jobs_extract.go contains all extractCustomJob* functions
• compiler_custom_jobs.go reduced to job-building/orchestration logic (~500 lines)
• go test ./pkg/workflow/... -run TestCustomJob (or closest matching) passes unchanged

Code Region: pkg/workflow/compiler_custom_jobs.go (functions matching extractCustomJob*)

In pkg/workflow/compiler_custom_jobs.go, move all functions whose names start with extractCustomJob (extractCustomJobNeeds, extractCustomJobProperties, extractCustomJobCoreProperties, extractCustomJobRunsOn, extractCustomJobTimeoutMinutes, extractCustomJobConcurrency, extractCustomJobEnv, extractCustomJobContainer, extractCustomJobServices, extractCustomJobContinueOnError, extractCustomJobEnvironment, extractCustomJobOutputs) into a new file pkg/workflow/compiler_custom_jobs_extract.go in the same package (workflow). Keep signatures and logic identical; only relocate code and fix imports. Run `make fmt`, `go build ./...`, and `go test ./pkg/workflow/...` (targeted to custom job tests if possible) to confirm behavior is unchanged.

---

Task 4: Add a CI check to flag new Go files exceeding 800 lines

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

Description: The repository documents a 100–500 line file-size guideline but has no automated enforcement. Add a lightweight script (e.g., scripts/check-file-size.sh or a Makefile target) that warns (non-blocking, informational) when non-test .go files under pkg/ exceed 800 lines, to prevent further growth of already-large files while not blocking existing ones.

Acceptance Criteria:

• New script/Makefile target lists files >800 LOC (non-test, under pkg/) and prints them as a warning, without failing the build
• Documented usage in the script header comment
• Optionally wired into an existing make lint or make check target as advisory output only (non-blocking)

Code Region: New file, e.g. scripts/check-file-size.sh

Create a small shell script scripts/check-file-size.sh that finds all non-test *.go files under pkg/ exceeding 800 lines using `find pkg -name "*.go" ! -name "*_test.go" -exec wc -l {} \; | awk '$1>800 {print}'`, prints them sorted descending by line count as an advisory warning (not a failure), and exits 0 regardless of findings. Add a comment at the top explaining this is informational only, tied to the file-size guideline in .github/skills/developer-code-organization/SKILL.md. Optionally add a Makefile target `check-file-size` that runs this script, without wiring it into any target that fails CI.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-08-04	Code Organization	Standard	N	First run — established baseline of 15 files >1000 LOC

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split awf_helpers.go capability predicates into awf_capabilities.go — Priority: Medium

Short-term Actions (This Month)

1. Split update_actions.go release-resolution logic — Priority: Medium
2. Extract compiler_custom_jobs.go property extractors — Priority: Low

Long-term Actions (This Quarter)

1. Add advisory CI file-size check and revisit remaining files >1000 LOC — Priority: Low

---

📈 Success Metrics

• Files >1000 LOC (non-test): 15 → 12 or fewer
• Largest file size: 1,148 lines → under 700 lines

---

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 month

---

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

Generated by ⚡ Repository Quality Improvement Agent · auto · 31.9 AIC · ⌖ 2.59 AIC · ⊞ 9.6K · ◷

• expires on Aug 5, 2026, 5:28 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 #50563.