[repository-quality] Repository Quality: Validator File Size Compliance (2026-04-21)

[github-actions[bot]]

Analysis Date: 2026-04-21
Focus Area: Validator File Size Compliance (Custom)
Strategy Type: Custom — repository-specific
Custom Area: Yes — The project's own AGENTS.md defines explicit Validation Complexity Guidelines (100–200 line target, 300-line hard limit) but several files violate these self-imposed rules, creating a measurable technical debt signal to act on.

Executive Summary

A targeted audit of the pkg/workflow/ package against the project's stated Validation Complexity Guidelines found that 6 validation files exceed the stated 300-line hard limit, with the worst offender (safe_outputs_validation_config.go) at 431 lines—44% over the limit. Beyond validators, key infrastructure files (domains.go at 1,015 lines, cache.go at 1,002 lines) contain multiple distinct responsibilities that warrant splitting, and cmd/gh-aw/main.go at 898 lines is a near-monolith that makes CLI command setup difficult to navigate and test.

The good news: the overall test-to-source ratio is excellent at 2.18×, and the average file size across the 348-file workflow package is 238 lines—close to the 200-line target. The violations are concentrated in a small, identifiable set of files, making refactoring tractable and high-value.

Full Analysis Report

Focus Area: Validator File Size Compliance

Current State Assessment

Metrics Collected:

Metric	Value	Status
Workflow package: total files	348	✅
Workflow package: average file size	238 lines	✅ (near 200-line target)
Files exceeding 300-line hard limit	92	❌
Files exceeding 500 lines	42	❌
Validation files exceeding 300-line limit	6	❌
TODO/FIXME count (non-test)	7	✅ (low)
Test-to-source LOC ratio	2.18×	✅ (excellent)
cmd/gh-aw/main.go size	898 lines	❌

Validation Files Exceeding Hard Limit:

File	Lines	Over Limit By
safe_outputs_validation_config.go	431	+44%
permissions_validation.go	351	+17%
repository_features_validation.go	333	+11%
engine_validation.go	316	+5%
network_firewall_validation.go	305	+2%
expression_safety_validation.go	302	+1%

Other Oversized Infrastructure Files (non-validators):

File	Lines	Domains
domains.go	1,015	Engine-specific domain lists × 7+ engines + helpers
cache.go	1,002	Cache config parsing + YAML step generation
compiler_jobs.go	958	Job orchestration (15+ functions)
mcp_setup_generator.go	925	MCP setup YAML generation
compiler_yaml.go	917	YAML compilation helpers
cmd/gh-aw/main.go	898	CLI entry point (4 functions, mostly init() + main())

Findings

Strengths

• Excellent test coverage ratio (2.18×)
• Very few TODO/FIXME markers (7 total) — low technical debt smell
• The AGENTS.md guidelines exist and are detailed; the problem is adherence, not awareness
• Most files (256 of 348 in workflow/) are within the 300-line limit
• Several validation files (call_workflow_validation.go 295 lines, runtime_validation.go 290 lines) are close to compliant

Areas for Improvement

• 6 validation files exceed the hard limit — directly violates the project's own AGENTS.md rules 🔴
• domains.go (1,015 lines) mixes per-engine domain data for 7+ engines plus domain merging logic — clear opportunity for per-engine split 🔴
• cache.go (1,002 lines) mixes cache configuration parsing (lines ~1–400) and YAML step generation (lines ~400+) — two distinct domains 🟡
• cmd/gh-aw/main.go (898 lines) — CLI entry point contains init() that registers all commands + a very long main() — hard to navigate and test 🟡
• compiler_jobs.go (958 lines, 15+ functions) — job orchestration contains distinct sub-concerns (memory management jobs, custom jobs, pre-steps injection) 🟡

Detailed Analysis

The safe_outputs_validation_config.go file at 431 lines is the clearest violation. It contains: (1) struct type definitions (FieldValidation, TypeValidationConfig, ValidationConfig), (2) a 350+ line data declaration block with hardcoded validation rules for each safe-output type, and (3) a GetValidationConfigJSON() accessor function. The struct/type definitions and the config data could be separated into safe_outputs_validation_types.go and safe_outputs_validation_data.go.

The domains.go file has a clear split pattern: each engine (Copilot, Codex, Claude, Gemini, Crush, OpenCode, etc.) has its own domain constants and helper functions. These could move to per-engine files (domains_copilot.go, domains_claude.go, etc.) while shared utilities (mergeDomainsWithNetworkToolsAndRuntimes, GetAllowedDomains) stay in domains.go.

The cache.go file separates naturally into config parsing (cache_config.go) and YAML step generation (cache_steps.go).

---

🤖 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 the coding agent to process one at a time.

Improvement Tasks

Task 1: Split safe_outputs_validation_config.go into type definitions and data

Priority: High
Estimated Effort: Small
Focus Area: Validator File Size Compliance

Description:
pkg/workflow/safe_outputs_validation_config.go (431 lines) contains three distinct concerns: struct type definitions, a large inline data block (~350 lines), and an accessor function. Split into safe_outputs_validation_types.go (types only) and keep the data + accessor in a renamed/trimmed file. This directly addresses the 300-line hard limit from AGENTS.md.

Acceptance Criteria:

• Struct types (FieldValidation, TypeValidationConfig, ValidationConfig) moved to safe_outputs_validation_types.go
• Remaining data block + GetValidationConfigJSON stays in safe_outputs_validation_config.go and is ≤300 lines
• All existing tests pass: go test ./pkg/workflow/ -run TestSafeOutputs
• make fmt && make lint passes

Code Region: pkg/workflow/safe_outputs_validation_config.go

Refactor `pkg/workflow/safe_outputs_validation_config.go` to comply with the project's 300-line hard limit.

The file currently has 431 lines mixing struct type definitions and inline validation data. Split it:
1. Create `pkg/workflow/safe_outputs_validation_types.go` containing only the struct types: `FieldValidation`, `TypeValidationConfig`, `ValidationConfig`, and any related constants/enums defined at the top of the file.
2. The original `safe_outputs_validation_config.go` should retain only the validation data declarations and the `GetValidationConfigJSON` function, keeping it under 300 lines.

Ensure all tests still pass with `go test ./pkg/workflow/ -run "TestSafeOutput|TestGetValidationConfig"` and run `make fmt && make lint` before committing.

---

Task 2: Split domains.go into per-engine domain files

Priority: High
Estimated Effort: Medium
Focus Area: Validator File Size Compliance / Code Organization

Description:
pkg/workflow/domains.go (1,015 lines) contains domain constants and helper functions for 7+ AI engines mixed together. Extract per-engine sections into dedicated files. This reduces the file from 1,015 to ~300 lines and makes it easier to add or update engine-specific domains.

Acceptance Criteria:

• Each engine that has >2 domain constants/functions gets its own file (e.g., domains_copilot.go, domains_claude.go, domains_codex.go, domains_crush.go, domains_gemini.go, domains_opencode.go)
• Shared/generic helpers (GetAllowedDomains, mergeDomainsWithNetworkToolsAndRuntimes, ecosystem domain logic) remain in domains.go
• domains.go is ≤300 lines after the split
• All existing tests pass: go test ./pkg/workflow/
• make fmt && make lint passes

Code Region: pkg/workflow/domains.go

Refactor `pkg/workflow/domains.go` to reduce its size from 1,015 lines by extracting per-engine domain definitions into separate files.

The file contains domain constants and helper functions for multiple AI engines (Copilot, Codex, Claude, Gemini, Crush, OpenCode, etc.). Create one file per engine that has substantial content:
- `pkg/workflow/domains_copilot.go` — CopilotDefaultDomains + GetCopilotAllowedDomainsWithToolsAndRuntimes
- `pkg/workflow/domains_claude.go` — ClaudeDefaultDomains + Claude-specific helpers
- `pkg/workflow/domains_codex.go` — CodexDefaultDomains + Codex-specific helpers  
- `pkg/workflow/domains_crush.go` — CrushBaseDefaultDomains, CrushDefaultDomains, crushProviderDomains, extractCrushProviderFromModel, GetCrushDefaultDomains, GetCrushAllowedDomainsWithToolsAndRuntimes
- `pkg/workflow/domains_gemini.go` — GeminiDefaultDomains + Gemini-specific helpers
- `pkg/workflow/domains_opencode.go` — OpenCodeBaseDefaultDomains, OpenCodeDefaultDomains, openCodeProviderDomains, extractOpenCodeProviderFromModel, GetOpenCodeDefaultDomains, GetOpenCodeAllowedDomainsWithToolsAndRuntimes

Keep all shared utilities in `domains.go` (ecosystem domains loading, `GetAllowedDomains`, `mergeDomainsWithNetworkToolsAndRuntimes`, `GetDomainEcosystem`, etc.).

Run `go test ./pkg/workflow/` to verify all tests pass, then `make fmt && make lint`.

---

Task 3: Split cache.go into config parsing and step generation

Priority: Medium
Estimated Effort: Medium
Focus Area: Code Organization / Validator File Size Compliance

Description:
pkg/workflow/cache.go (1,002 lines) mixes two distinct responsibilities: (1) cache configuration data structures and parsing logic (~lines 1–400), and (2) YAML step generation for GitHub Actions (~lines 400–1002). Separating these makes both easier to test and maintain.

Acceptance Criteria:

• Cache config types and parsing (CacheMemoryEntry, CacheMemoryConfig, parseCacheMemoryEntry, extractCacheMemoryConfig) move to cache_config.go
• YAML step generation functions (generateCacheSteps, generateCacheMemorySteps, generateCacheMemoryGitSetupStep, etc.) stay in cache.go or move to cache_steps.go
• Both resulting files are ≤500 lines (ideally ≤300)
• All existing tests pass: go test ./pkg/workflow/ -run "TestCache"
• make fmt && make lint passes

Code Region: pkg/workflow/cache.go

Refactor `pkg/workflow/cache.go` (1,002 lines) by separating cache configuration parsing from YAML step generation.

The file has two logical sections:
1. **Config/Parsing** (~lines 1–400): `CacheMemoryEntry`, `CacheMemoryConfig`, `isValidFileExtension`, `generateDefaultCacheKey`, `computeIntegrityCacheKey`, `parseCacheMemoryEntry`, `extractCacheMemoryConfig`, `extractCacheMemoryConfigFromMap`
2. **Step Generation** (~lines 401–1002): `generateCacheSteps`, `generateCacheMemorySteps`, `generateCacheMemoryGitSetupStep`, `generateCacheMemoryGitCommitSteps`, `generateCacheMemoryValidation`, `generateCacheMemoryArtifactUpload`, `buildCacheMemoryPromptSection`, `buildUpdateCacheMemoryJob`

Create `pkg/workflow/cache_config.go` with section 1 and leave section 2 in `cache.go` (renamed for clarity if needed).

Verify: `go test ./pkg/workflow/ -run "TestCache"` passes. Then `make fmt && make lint`.

---

Task 4: Refactor permissions_validation.go to remove ValidateIncludedPermissions

Priority: Medium
Estimated Effort: Small
Focus Area: Validator File Size Compliance

Description:
pkg/workflow/permissions_validation.go (351 lines) contains two logically distinct validation functions noted in its own comments: ValidatePermissions (general MCP toolset validation) and ValidateIncludedPermissions (validation for imported workflows). The file's own comments say to use different functions for different contexts — this is a signal to split by responsibility.

Acceptance Criteria:

• ValidateIncludedPermissions and its helpers moved to permissions_imports_validation.go
• permissions_validation.go reduced to ≤250 lines
• All existing tests pass: go test ./pkg/workflow/ -run "TestValidatePermissions|TestValidateIncluded"
• make fmt && make lint passes

Code Region: pkg/workflow/permissions_validation.go

Refactor `pkg/workflow/permissions_validation.go` (351 lines) to comply with the project's 300-line hard limit.

The file contains two documented-as-separate validation concerns:
1. `ValidatePermissions` — general-purpose validator used during compilation (lines ~35–120)
2. `ValidateIncludedPermissions` (method on `*Compiler`) — validator for imported/included workflows (lines ~210–351)

Move `ValidateIncludedPermissions` and any helpers specific to it into a new file `pkg/workflow/permissions_imports_validation.go`. Keep `ValidatePermissions`, `checkMissingPermissions`, `FormatValidationMessage`, and `formatMissingPermissionsMessage` in `permissions_validation.go`.

Verify: `go test ./pkg/workflow/ -run "TestValidatePermissions|TestValidateIncluded"` passes. Then `make fmt && make lint`.

---

Task 5: Add a CI lint check for file size compliance

Priority: Low
Estimated Effort: Small
Focus Area: Compliance Enforcement

Description:
The 300-line hard limit for validators is documented in AGENTS.md but not enforced automatically. Adding a simple shell-based check to the CI pipeline would prevent future regressions. This is a "ratchet" mechanism — it sets the current worst-case as the threshold and prevents things from getting worse while refactoring continues.

Acceptance Criteria:

• A new step or script checks that no *_validation.go file exceeds 450 lines (current worst-case ceiling to avoid false positives on existing violations)
• The check prints the offending files if the threshold is exceeded
• The check is wired into an existing CI workflow (e.g., added to make lint or a new make check-file-sizes target)
• Documented in AGENTS.md or Makefile with a comment explaining the purpose
• make lint or make check-file-sizes exits non-zero when a *_validation.go file exceeds 450 lines

Code Region: Makefile, .github/workflows/ci.yml

Add a file-size compliance check to prevent validator files from growing beyond the project's hard limit.

In the Makefile, add a target called `check-file-sizes` that:
1. Finds all `pkg/workflow/*_validation.go` files (excluding `_test.go`)
2. Reports any file exceeding 450 lines (current ceiling — allows existing violations while preventing new regressions)
3. Exits with non-zero status if any file exceeds the threshold

Example Makefile target:
```makefile
check-file-sizes:
	`@echo` "Checking validator file sizes..."
	`@find` pkg/workflow -name "*_validation.go" ! -name "*_test.go" -exec wc -l {} \; | \
	  awk '$$1 > 450 {print "FAIL: " $$2 " has " $$1 " lines (limit: 450)"; found=1} END {exit found}'

Wire check-file-sizes into make lint by adding it as a dependency. Update AGENTS.md to mention the automated enforcement under "Validation Complexity Guidelines".

Verify the check works: temporarily create a >450 line validation file and confirm the target exits non-zero.

---

## 📊 Historical Context

<details>
<summary>Previous Focus Areas</summary>

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|
| 2026-04-21 | Validator File Size Compliance | Custom | Yes | 6 validation files exceed 300-line hard limit; 5 tasks generated |

</details>

---

## 🎯 Recommendations

### Immediate Actions (This Week)
1. **Refactor `safe_outputs_validation_config.go`** (Task 1) — smallest effort, clearest split — Priority: High
2. **Refactor `permissions_validation.go`** (Task 4) — already has documented separation in comments — Priority: High

### Short-term Actions (This Month)
1. **Split `domains.go`** (Task 2) — reduces one of the largest files from 1,015 to ~300 lines — Priority: High
2. **Split `cache.go`** (Task 3) — config vs. step generation — Priority: Medium

### Long-term Actions (This Quarter)
1. **Add CI file-size enforcement** (Task 5) — prevents regression — Priority: Low
2. Revisit `engine_validation.go`, `network_firewall_validation.go`, and `repository_features_validation.go` — they are close to the limit (305–333 lines) and likely to grow

---

## 📈 Success Metrics

Track these metrics to measure improvement in **Validator File Size Compliance**:

- **Validation files >300 lines**: 6 → 0
- **Largest validation file**: 431 lines → ≤300 lines
- **`domains.go` size**: 1,015 lines → ≤300 lines
- **`cache.go` size**: 1,002 lines → ≤500 lines (two files)
- **Average workflow package file size**: 238 lines → ≤200 lines

---

## Next Steps

1. Review and prioritize the 5 tasks above
2. Assign Tasks 1 and 4 to the Copilot coding agent first (high priority, small effort)
3. Track progress — re-run this agent in ~2 weeks to measure improvement
4. Re-evaluate this focus area after Tasks 1–4 are complete

---

**References:**
- [§24724381534](https://github.com/github/gh-aw/actions/runs/24724381534)




> Generated by [Repository Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/24724381534/agentic_workflow) · ● 717.1K · [◷](https://github.com/search?q=repo%3Agithub%2Fgh-aw+%22gh-aw-workflow-call-id%3A+github%2Fgh-aw%2Frepository-quality-improver%22&type=discussions)
> - [x] expires <!-- gh-aw-expires: 2026-04-22T13:24:29.067Z --> on Apr 22, 2026, 1:24 PM UTC

<!-- gh-aw-agentic-workflow: Repository Quality Improvement Agent, engine: copilot, model: auto, id: 24724381534, workflow_id: repository-quality-improver, run: https://github.com/github/gh-aw/actions/runs/24724381534 -->

<!-- gh-aw-workflow-id: repository-quality-improver -->
<!-- gh-aw-workflow-call-id: github/gh-aw/repository-quality-improver -->