Repository Quality Report: Validation File Size Compliance (2026-03-12)

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Validation File Size Compliance

Analysis Date: 2026-03-12
Focus Area: Validation File Size Compliance
Strategy Type: Custom (repository-specific)
Custom Area: Yes — The project's AGENTS.md explicitly documents a hard limit of 300 lines per validator file, with a target of 100–200 lines. A scan reveals 10 validation files currently exceed this hard limit, representing a 24% non-compliance rate across 42 total validation files.

---

Executive Summary

The gh-aw codebase maintains detailed guidelines in AGENTS.md about validator file size: target 100–200 lines, hard limit 300 lines, split when 2+ unrelated validation domains exist. Despite this documentation, 10 of the 42 validation files breach the hard limit. The most egregious is strict_mode_validation.go at 546 lines — 82% over the limit. In aggregate, these 10 files contain ~3,900 lines of code that should be distributed across ~20+ smaller, more focused files.

Splitting these validators will improve: testability (each sub-validator can be tested in isolation), discoverability (clear single-responsibility naming), and contribution friction reduction (smaller files are easier to review and modify). The project already has strong tooling (make lint, make test-unit) and naming conventions ({domain}_{subdomain}_validation.go) to support this refactoring.

Full Analysis Report

Focus Area: Validation File Size Compliance

Current State Assessment

Metrics Collected:

File	Lines	Over Limit By	Distinct Domains	Status
pkg/workflow/strict_mode_validation.go	546	+246	4 (permissions, network, env-secrets, tools)	❌
pkg/workflow/expression_validation.go	501	+201	3 (safety, syntax, runtime-import)	❌
pkg/workflow/safe_output_validation_config.go	420	+120	2 (config-JSON, type-config)	❌
pkg/workflow/safe_outputs_validation.go	390	+90	3 (network-domains, target, domain-pattern)	❌
pkg/workflow/dispatch_workflow_validation.go	372	+72	2 (dispatch logic, file-utility helpers)	❌
pkg/workflow/repository_features_validation.go	367	+67	2 (validation, repo-API-cache helpers)	❌
pkg/workflow/engine_validation.go	350	+50	2 (inline/auth config, plugin support)	❌
pkg/workflow/concurrency_validation.go	328	+28	2 (group-expression, brace/quote balance)	❌
pkg/cli/run_workflow_validation.go	323	+23	2 (run params, environment checks)	❌
pkg/workflow/permissions_validation.go	320	+20	2 (permission rules, message formatting)	❌

Summary Stats:

• Total validation files: 42
• Files exceeding 300-line hard limit: 10 (24%)
• Files in the 200–300 "warning" zone: 3 (mcp_config_validation.go, mcp_validation.go, template_injection_validation.go)
• Total LOC in over-limit files: ~3,900
• Biggest offender: 546 lines (82% over limit)

Findings

Strengths

• Project has detailed, well-documented size guidelines in AGENTS.md
• Naming convention {domain}_{subdomain}_validation.go is well-established and used consistently
• Strong test infrastructure — many validators have corresponding _test.go files
• Comment coverage requirement (30%) is documented

Areas for Improvement

• 10 validator files breach the documented hard limit — High severity
• strict_mode_validation.go (546 lines) has at least 4 distinct validation domains packed into one file — High severity
• expression_validation.go (501 lines) mixes expression safety, syntax checking, and runtime import validation — High severity
• Several files have clear "split lines" where pure utility/helper functions could be separated from validation logic — Medium severity

Candidate Split Plans

strict_mode_validation.go → 3 files:

• strict_mode_validation.go — validateStrictMode() orchestrator (~80 lines)
• strict_network_validation.go — validateStrictNetwork, validateStrictMCPNetwork, validateStrictFirewall (~150 lines)
• strict_env_secrets_validation.go — validateEnvSecrets, getEngineBaseEnvVarKeys, validateEnvSecretsSection (~130 lines)
• strict_tools_permissions_validation.go — validateStrictTools, validateStrictPermissions, validateStrictDeprecatedFields (~120 lines)

expression_validation.go → 3 files:

• expression_safety_validation.go — validateExpressionSafety, validateExpressionForDangerousProps (~200 lines)
• expression_syntax_validation.go — validateSingleExpression, containsExpression (~150 lines)
• runtime_import_validation.go — extractRuntimeImportPaths, validateRuntimeImportFiles (~80 lines) — file may already exist

repository_features_validation.go → 2 files:

• repository_features_validation.go — validateRepositoryFeatures, ClearRepositoryFeaturesCache (~120 lines)
• repository_api_client.go — getRepositoryFeatures, checkRepositoryHasDiscussions, checkRepositoryHasIssues, helpers (~200 lines)

dispatch_workflow_validation.go → 2 files:

• dispatch_workflow_validation.go — validateDispatchWorkflow logic (~150 lines)
• dispatch_workflow_utils.go — extractWorkflowDispatchInputs, findWorkflowFile, mdHasWorkflowDispatch, helpers (~180 lines)

---

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

---

Improvement Tasks

Task 1: Split strict_mode_validation.go into domain-focused files

Priority: High
Estimated Effort: Medium
Focus Area: Validation File Size Compliance

Description:
strict_mode_validation.go (546 lines) contains 4 distinct validation domains: strict mode orchestration, network validation, env-secrets validation, and tools/permissions validation. Per AGENTS.md, files exceeding 300 lines must be refactored. This file is 82% over the hard limit.

Acceptance Criteria:

• strict_mode_validation.go reduced to ≤200 lines (orchestrator only: validateStrictMode)
• strict_network_validation.go created with validateStrictNetwork, validateStrictMCPNetwork, validateStrictFirewall
• strict_env_secrets_validation.go created with validateEnvSecrets, getEngineBaseEnvVarKeys, validateEnvSecretsSection
• strict_tools_permissions_validation.go created with validateStrictTools, validateStrictPermissions, validateStrictDeprecatedFields
• All existing tests continue to pass (make test-unit)
• make agent-finish passes with no errors

Code Region: pkg/workflow/strict_mode_validation.go

Refactor `pkg/workflow/strict_mode_validation.go` (546 lines) to comply with the project's hard limit of 300 lines per validator file (documented in AGENTS.md).

The file contains 4 distinct validation domains that should each live in their own file following the `{domain}_{subdomain}_validation.go` naming convention:

1. Create `pkg/workflow/strict_network_validation.go` — move `validateStrictNetwork`, `validateStrictMCPNetwork`, and `validateStrictFirewall` (approx lines 84–201, 437–500)
2. Create `pkg/workflow/strict_env_secrets_validation.go` — move `validateEnvSecrets`, `getEngineBaseEnvVarKeys`, `validateEnvSecretsSection` (approx lines 244–381)
3. Create `pkg/workflow/strict_tools_permissions_validation.go` — move `validateStrictTools`, `validateStrictPermissions`, `validateStrictDeprecatedFields` (approx lines 56–243)
4. Keep only `validateStrictMode` (the orchestrating function, approx lines 382–435) in `strict_mode_validation.go` along with any shared types/constants

After refactoring:
- Run `make fmt` to format all new files
- Run `make test-unit` to verify all tests pass
- Run `make agent-finish` for final validation
- Each new file should be ≤250 lines
- Each file should have build tag `//go:build !integration` at the very top

---

Task 2: Split expression_validation.go into focused concerns

Priority: High
Estimated Effort: Medium
Focus Area: Validation File Size Compliance

Description:
expression_validation.go (501 lines) mixes three distinct concerns: expression safety checking, expression syntax validation, and runtime import path validation. The runtime import concern may already have a test file (runtime_import_validation_test.go), suggesting it was intended to be a separate file.

Acceptance Criteria:

• Expression safety logic (≤200 lines) kept in expression_validation.go or moved to expression_safety_validation.go
• validateSingleExpression and helpers separated into expression_syntax_validation.go (≤200 lines)
• Runtime import functions moved to runtime_import_validation.go (≤100 lines) — verify if file already exists before creating
• All existing tests pass (make test-unit)
• make agent-finish passes

Code Region: pkg/workflow/expression_validation.go

Refactor `pkg/workflow/expression_validation.go` (501 lines) by separating its three distinct concerns into focused files.

Steps:
1. Check if `pkg/workflow/runtime_import_validation.go` already exists. If not, create it and move `extractRuntimeImportPaths` and `validateRuntimeImportFiles` (approx lines 377–500) into it.
2. Move `validateSingleExpression`, `containsExpression`, and the `ExpressionValidationOptions` type into `pkg/workflow/expression_syntax_validation.go` (approx lines 241–376)
3. Keep `validateExpressionSafety` and `validateExpressionForDangerousProps` in the original file, renaming it to `expression_safety_validation.go` if appropriate, or keeping as `expression_validation.go`

Each new file must:
- Have build tag `//go:build !integration` at the very top (first line, followed by blank line)
- Follow `{domain}_{subdomain}_validation.go` naming convention
- Be ≤250 lines

After refactoring:
- Run `make fmt`
- Run `make test-unit` to verify `runtime_import_validation_test.go` and related tests still pass
- Run `make agent-finish`

---

Task 3: Split repository_features_validation.go into validation and API client

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

Description:
repository_features_validation.go (367 lines) mixes high-level workflow validation with low-level GitHub API access functions (getRepositoryFeatures, checkRepositoryHasDiscussions, etc.). The API client helpers are a distinct concern and should live in a separate file.

Acceptance Criteria:

• repository_features_validation.go reduced to ≤200 lines (validation logic + cache clear)
• repository_features_api.go created with getRepositoryFeatures, checkRepositoryHasDiscussions, checkRepositoryHasIssues, and related uncached helpers
• All existing tests pass (make test-unit)
• make agent-finish passes

Code Region: pkg/workflow/repository_features_validation.go

Refactor `pkg/workflow/repository_features_validation.go` (367 lines) by extracting the GitHub API client helpers into a separate file.

The file has two distinct concerns:
1. **Validation logic**: `ClearRepositoryFeaturesCache`, `validateRepositoryFeatures` — keep in `repository_features_validation.go`
2. **API client helpers**: `getCurrentRepository`, `getCurrentRepositoryUncached`, `getRepositoryFeatures`, `checkRepositoryHasDiscussions`, `checkRepositoryHasDiscussionsUncached`, `checkRepositoryHasIssues`, `checkRepositoryHasIssuesUncached` — move to `repository_features_api.go`

Steps:
1. Create `pkg/workflow/repository_features_api.go` with the API helper functions
2. Move the cache variables (if any) that are only used by the API client to the new file
3. Keep the new `repository_features_validation.go` ≤200 lines
4. Add `//go:build !integration` build tag to any new test files
5. Run `make fmt && make test-unit && make agent-finish`

---

Task 4: Split dispatch_workflow_validation.go into validation and utility helpers

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

Description:
dispatch_workflow_validation.go (372 lines) contains the main validateDispatchWorkflow function alongside many utility/helper functions for finding workflow files and extracting dispatch inputs. The utilities are a distinct, reusable concern.

Acceptance Criteria:

• dispatch_workflow_validation.go reduced to ≤200 lines (validation logic only)
• dispatch_workflow_utils.go created with extractWorkflowDispatchInputs, findWorkflowFile, getCurrentWorkflowName, isPathWithinDir, mdHasWorkflowDispatch, extractMDWorkflowDispatchInputs, containsWorkflowDispatch
• All tests pass (make test-unit)
• make agent-finish passes

Code Region: pkg/workflow/dispatch_workflow_validation.go

Refactor `pkg/workflow/dispatch_workflow_validation.go` (372 lines) by extracting utility/helper functions into `pkg/workflow/dispatch_workflow_utils.go`.

Functions to move to the new utils file (approx lines 164–372):
- `extractWorkflowDispatchInputs`
- `getCurrentWorkflowName`
- `isPathWithinDir`
- `findWorkflowFile` and its `findWorkflowFileResult` type
- `mdHasWorkflowDispatch`
- `extractMDWorkflowDispatchInputs`
- `containsWorkflowDispatch`

Keep in `dispatch_workflow_validation.go`:
- `validateDispatchWorkflow` and its direct validation helpers

New `dispatch_workflow_utils.go` must:
- Have build tag `//go:build !integration` at the very top
- Be ≤250 lines

Run `make fmt && make test-unit && make agent-finish` after refactoring.

---

Task 5: Add linting check to catch future validator size violations

Priority: Low
Estimated Effort: Small
Focus Area: Validation File Size Compliance

Description:
To prevent regression, add a CI check (or Makefile target) that alerts when validation files exceed 300 lines. This enforces the documented hard limit automatically rather than relying on manual review.

Acceptance Criteria:

• A make check-validator-sizes target added to the Makefile that exits non-zero if any *_validation*.go file exceeds 300 lines
• The check lists the offending files with their line counts
• Existing over-limit files are either excluded with a comment (as known technical debt) or already fixed by Tasks 1–4
• make agent-finish continues to pass

Code Region: Makefile

Add a Makefile target `check-validator-sizes` that enforces the project's documented hard limit of 300 lines per `*_validation*.go` file (see AGENTS.md "Validation Complexity Guidelines").

The target should:
1. Find all `*_validation*.go` files excluding `*_test.go` and `*_wasm.go` files
2. Check if any exceed 300 lines
3. Print a clear error message with file name and line count for each violation
4. Exit with a non-zero code if any violations are found

Example implementation:
```makefile
.PHONY: check-validator-sizes
check-validator-sizes:
	`@echo` "Checking validation file sizes (hard limit: 300 lines)..."
	`@violations`=$$(find . -name "*_validation*.go" ! -name "*_test.go" ! -name "*_wasm.go" ! -path "./.git/*" | xargs wc -l | awk '$$1 > 300 && $$2 != "total" {print $$2": "$$1" lines"}'); \
	if [ -n "$$violations" ]; then \
		echo "ERROR: The following validation files exceed the 300-line hard limit:"; \
		echo "$$violations"; \
		exit 1; \
	fi
	`@echo` "All validation files are within the 300-line hard limit. ✅"

Note: Before enabling this as a blocking check, Tasks 1–4 above should be completed to bring the existing violations into compliance.

---

### 📊 Historical Context

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

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|
| 2026-03-12 | Validation File Size Compliance | Custom | ✅ | 10 over-limit files identified, 5 tasks generated |

</details>

---

### 🎯 Recommendations

#### Immediate Actions (This Week)
1. **Fix `strict_mode_validation.go`** (Task 1) — Priority: High — 82% over hard limit, 4 distinct domains
2. **Fix `expression_validation.go`** (Task 2) — Priority: High — 67% over hard limit, 3 distinct domains

#### Short-term Actions (This Month)
1. **Fix `repository_features_validation.go`** (Task 3) — Priority: Medium — Clear API/validation boundary
2. **Fix `dispatch_workflow_validation.go`** (Task 4) — Priority: Medium — Clear validation/utility boundary

#### Long-term Actions (This Quarter)
1. **Add `make check-validator-sizes`** (Task 5) — Priority: Low — Prevent regression
2. Address the 3 files in the 200–300 "warning zone" (`mcp_config_validation.go`, `mcp_validation.go`, `template_injection_validation.go`) proactively

---

### 📈 Success Metrics

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

- **Files over 300 lines**: 10 → **0**
- **Files over 200 lines (warning zone)**: 13 → **≤5**
- **Average validator file size**: ~192 lines → **≤180 lines**
- **Largest single validator**: 546 lines → **≤250 lines**

---

### Next Steps

1. Assign Tasks 1 & 2 to the Copilot coding agent via the planner agent (these are the highest-impact fixes)
2. Tasks 3 & 4 can be done in parallel once Tasks 1 & 2 are complete
3. Task 5 (CI enforcement) should be done last, after violations are fixed
4. Re-evaluate this focus area after Tasks 1–4 are complete to verify compliance

---

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


> AI generated by [Repository Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/23004537817) · [history](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-03-13T13:39:34.948Z --> on Mar 13, 2026, 1:39 PM UTC

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-13T13:39:34.948Z.

Closed by Workflow