[repository-quality] Repository Quality Improvement Report – Validation File Size Governance

[github-actions[bot]]

Analysis Date: 2026-04-10
Focus Area: Validation File Size Governance
Strategy Type: Custom
Custom Area: Yes — gh-aw's AGENTS.md explicitly mandates a 300-line hard limit for validator files, yet 9 validation files currently violate this limit. This focus area targets compliance with the project's own documented standards, which directly impacts maintainability, testability, and cognitive overhead when adding new validations.

---

Executive Summary

gh-aw has a rich validation system comprising 52 dedicated *_validation.go files across pkg/workflow/ and pkg/cli/. The AGENTS.md document explicitly establishes a hard limit of 300 lines per validator file and a minimum 30% comment coverage target. This analysis finds 9 files exceeding the hard limit (up to 462 lines) and numerous files below the 10% comment coverage threshold — in some cases as low as 5%.

The most critical offender is mcp_config_validation.go (462 lines), which contains two clearly separable domains: tools-section validation and MCP schema/requirements validation. Splitting these files will restore compliance with AGENTS.md, reduce per-file complexity, and improve focused test coverage.

Full Analysis Report

Focus Area: Validation File Size Governance

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total validation files	52	✅
Files exceeding 300-line hard limit	9	❌
Largest file (mcp_config_validation.go)	462 lines	❌
Files with <10% comment coverage	11	❌
Files with <30% comment coverage	~30+	⚠️
TODO/FIXME markers in validation files	0	✅

Files exceeding the 300-line hard limit:

File	Lines	Excess
pkg/workflow/mcp_config_validation.go	462	+162
pkg/workflow/tools_validation.go	368	+68
pkg/workflow/dispatch_workflow_validation.go	363	+63
pkg/workflow/permissions_validation.go	351	+51
pkg/cli/run_workflow_validation.go	350	+50
pkg/workflow/repository_features_validation.go	333	+33
pkg/workflow/safe_outputs_validation.go	309	+9
pkg/workflow/template_injection_validation.go	306	+6
pkg/workflow/expression_safety_validation.go	302	+2

Files with critically low comment coverage (<10%):

File	Comment Coverage	Lines
call_workflow_validation.go	5%	295
dispatch_workflow_validation.go	5%	363
expression_safety_validation.go	5%	302
tools_validation.go	5%	368
dispatch_repository_validation.go	6%	107
expression_syntax_validation.go	6%	236
step_order_validation.go	6%	216
strict_mode_permissions_validation.go	6%	190
permissions_validation.go	7%	351
safe_outputs_validation.go	7%	309

Findings

Strengths

• Excellent documentation header in mcp_config_validation.go (architecture overview, when-to-add guidance)
• validation.go and validation_helpers.go serve as well-documented anchors for the system
• Zero TODO/FIXME markers — no known deferred work
• Consistent function naming: validate* for private, Validate* for public functions

Areas for Improvement

• 9 files violate the documented 300-line hard limit — HIGH severity
• Many files lack meaningful inline comments — MEDIUM severity
• mcp_config_validation.go contains two separable domains (tools-section validation + MCP schema requirements) — HIGH severity
• tools_validation.go has no file-level documentation header (unlike other validators) — MEDIUM severity

Detailed Analysis

The mcp_config_validation.go file's 462 lines include two logically distinct areas:

1. ValidateToolsSection() and builtInToolNames — validates the tools: frontmatter key
2. ValidateMCPConfigs() and its helpers — validates mcp-servers: entries with schema + type requirements

Per the split decision tree in AGENTS.md, files over 300 lines with 2+ distinct domains should split. This applies directly here.

tools_validation.go is an unusual case: it contains GitHub tool guard-policy validation (allowed repos, min-integrity, toolsets) but has no file-level header documenting its scope — inconsistent with all other validators.

dispatch_workflow_validation.go at 363 lines contains helper functions (findWorkflowFile, extractWorkflowDispatchInputs, mdHasWorkflowDispatch) that support the core validateDispatchWorkflow() function but could reasonably be extracted to a dispatch_workflow_helpers.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 Claude to process.

Improvement Tasks

---

Task 1: Split mcp_config_validation.go into Two Files

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

Description:
pkg/workflow/mcp_config_validation.go is 462 lines — the largest validation file in the codebase and the most significant violator of the documented 300-line hard limit. It contains two distinct validation domains:

• Tools-section validation: ValidateToolsSection(), builtInToolNames, builtInToolNamesForError
• MCP server validation: ValidateMCPConfigs(), getRawMCPConfig(), inferMCPType(), validateStringProperty(), validateMCPRequirements(), buildSchemaMCPConfig(), validateMCPMountsSyntax()

These should be split into:

• mcp_tools_section_validation.go — tools section validation (ValidateToolsSection + constants)
• mcp_config_validation.go — MCP server config validation (ValidateMCPConfigs + helpers)

Acceptance Criteria:

• mcp_config_validation.go is ≤ 300 lines after split
• New mcp_tools_section_validation.go is ≤ 300 lines
• Both files have a file-level documentation comment header following the pattern from existing validators (see permissions_validation.go for reference)
• All existing tests in pkg/workflow/mcp_config_validation_test.go still pass
• make agent-finish passes without errors

Code Region: pkg/workflow/mcp_config_validation.go

Split `pkg/workflow/mcp_config_validation.go` (462 lines) into two focused files:

1. `pkg/workflow/mcp_tools_section_validation.go` — move `builtInToolNames`, `builtInToolNamesForError`, `ValidateToolsSection()`, and any helper functions that only support tools-section validation
2. `pkg/workflow/mcp_config_validation.go` — keep `ValidateMCPConfigs()`, `getRawMCPConfig()`, `inferMCPType()`, `validateStringProperty()`, `validateMCPRequirements()`, `buildSchemaMCPConfig()`, `validateMCPMountsSyntax()`

Each file must:
- Start with a `// This file provides...` documentation comment following the existing pattern
- Be ≤ 300 lines (hard limit from AGENTS.md)
- Include a `// # When to Add Validation Here` section at the top

After splitting, run `make agent-finish` to validate. Do NOT change any function signatures or behavior — this is a pure structural refactor.

---

Task 2: Add File-Level Documentation Header to tools_validation.go

Priority: High
Estimated Effort: Small
Focus Area: Validation File Size Governance / Documentation Consistency

Description:
pkg/workflow/tools_validation.go (368 lines) is the only large validation file without a file-level documentation comment header. Every other validator of comparable size (mcp_config_validation.go, permissions_validation.go, engine_validation.go, etc.) starts with a structured header documenting:

• What the file validates
• The validation functions it exports
• The validation pattern used
• When to add validation here

This omission makes the file harder to navigate and inconsistent with project standards.

Acceptance Criteria:

• File starts with a // This file provides... documentation comment
• Header includes // # Validation Functions listing all exported and key private functions
• Header includes // # When to Add Validation Here guidance
• make lint passes without errors
• No functional changes — documentation only

Code Region: pkg/workflow/tools_validation.go (top of file, before package workflow)

Add a file-level documentation header to `pkg/workflow/tools_validation.go` following the pattern from `pkg/workflow/mcp_config_validation.go` or `pkg/workflow/engine_validation.go`.

The header should document:
1. What this file validates (GitHub tool configuration: bash, GitHub MCP, guard policy, toolset compatibility)
2. The exported validation functions: `validateBashToolConfig()`, `validateGitHubReadOnly()`, `validateGitHubToolConfig()`, `validateGitHubGuardPolicy()`, `ValidateGitHubToolsAgainstToolsets()`
3. Key validation patterns (guard policy structure, repo pattern syntax)
4. When to add validation to this file vs other files

Do NOT change any function signatures or logic. This is a documentation-only change.
After adding, run `make lint` to verify no issues.

---

Task 3: Extract Helper Functions from dispatch_workflow_validation.go

Priority: Medium
Estimated Effort: Medium
Focus Area: Validation File Size Governance

Description:
pkg/workflow/dispatch_workflow_validation.go is 363 lines. The file's core function is validateDispatchWorkflow() but it also contains 6 helper functions that handle file discovery and YAML parsing:

• extractWorkflowDispatchInputs() — parses .lock.yml / .yml files
• getCurrentWorkflowName() — extracts workflow name from path
• isPathWithinDir() — path-traversal safety check
• findWorkflowFile() — searches .github/workflows directory
• mdHasWorkflowDispatch() — reads .md frontmatter for triggers
• extractMDWorkflowDispatchInputs() — extracts inputs from .md files
• containsWorkflowDispatch() — checks 'on:' section variants

These file-discovery and extraction helpers belong in a dispatch_workflow_helpers.go file, leaving only the core validation logic in dispatch_workflow_validation.go.

Acceptance Criteria:

• dispatch_workflow_validation.go is ≤ 300 lines after refactor
• New dispatch_workflow_helpers.go contains the extracted helpers with proper documentation
• Both files have file-level documentation comment headers
• All existing tests pass (go test ./pkg/workflow/... -run TestDispatch)
• make agent-finish passes without errors

Code Region: pkg/workflow/dispatch_workflow_validation.go

Refactor `pkg/workflow/dispatch_workflow_validation.go` (363 lines) by extracting file-discovery and parsing helpers to a new `pkg/workflow/dispatch_workflow_helpers.go` file.

Move these functions to `dispatch_workflow_helpers.go`:
- `extractWorkflowDispatchInputs()`
- `getCurrentWorkflowName()`
- `isPathWithinDir()`
- `findWorkflowFileResult` struct and `findWorkflowFile()`
- `mdHasWorkflowDispatch()`
- `extractMDWorkflowDispatchInputs()`
- `containsWorkflowDispatch()`

Keep in `dispatch_workflow_validation.go`:
- `validateDispatchWorkflow()` (the core validation function)
- Any validation-specific helper called only from `validateDispatchWorkflow()`

Both files must have `// This file provides...` documentation headers following the pattern from other validators.

After refactoring, run:
```bash
go test ./pkg/workflow/... -run "TestDispatch\|TestCall"
make agent-finish

Do NOT change any function signatures, behavior, or visibility.

---

#### Task 4: Improve Comment Coverage in `expression_safety_validation.go`

**Priority**: Medium
**Estimated Effort**: Small
**Focus Area**: Validation File Size Governance / Documentation

**Description:**
`pkg/workflow/expression_safety_validation.go` (302 lines, 5% comment coverage) validates GitHub Actions expression safety — one of the most security-critical validations in the codebase. Yet it has almost no inline comments explaining the complex regex patterns, dangerous property detection logic, or validation options struct.

The AGENTS.md target is 30% comment coverage. Adding comments here will help future contributors understand the security-sensitive logic.

**Acceptance Criteria:**
- [ ] File has a `// This file provides...` documentation header
- [ ] The `ExpressionValidationOptions` struct fields are documented
- [ ] The `validateExpressionForDangerousProps()` function has comments explaining what "dangerous props" are
- [ ] Key regex patterns have inline comments explaining what they match
- [ ] `validateSingleExpression()` has a comment explaining the validation flow
- [ ] Comment coverage reaches ≥ 15% (a practical improvement step toward 30%)
- [ ] `make lint` passes without errors

**Code Region:** `pkg/workflow/expression_safety_validation.go`

```markdown
Add documentation comments to `pkg/workflow/expression_safety_validation.go` to improve its comment coverage from 5% to ≥15%.

Specifically:
1. Add a file-level `// This file provides...` header (see `mcp_config_validation.go` for the pattern) explaining:
   - What expression safety validates (GitHub Actions expression injection risks)
   - The exported `validateExpressionSafety()` entry point
   - The dangerous property patterns being checked
   - The `ExpressionValidationOptions` struct purpose

2. Document the `ExpressionValidationOptions` struct fields

3. Add a comment before `validateExpressionForDangerousProps()` explaining what "dangerous properties" means in the context of GitHub Actions (e.g., properties like `.title`, `.body` that can contain attacker-controlled content)

4. Add brief inline comments on complex regex patterns

5. Document the `validateSingleExpression()` function's validation flow

Do NOT change any logic — documentation only.
After adding, verify with `make lint`.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-10	Validation File Size Governance	Custom	Yes	First run – 9 files over limit identified

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split mcp_config_validation.go — highest line count (462), two clear domains — Priority: High
2. Add documentation header to tools_validation.go — quick win, consistency fix — Priority: High

Short-term Actions (This Month)

1. Extract helpers from dispatch_workflow_validation.go — brings it under 300 lines — Priority: Medium
2. Improve comment coverage in expression_safety_validation.go — security-critical file — Priority: Medium
3. Address remaining 5 files over 300 lines (permissions, run_workflow, repository_features, safe_outputs, template_injection)

Long-term Actions (This Quarter)

1. Add a CI check (make lint or a dedicated script) that enforces the 300-line hard limit on *_validation.go files to prevent future regressions
2. Bring all validation files to ≥ 15% comment coverage as an incremental step toward the 30% target

---

📈 Success Metrics

Track these metrics to measure improvement in Validation File Size Governance:

• Files exceeding 300-line limit: 9 → 0
• Average comment coverage in validation files: ~8% → ≥15%
• Largest validation file: 462 lines → ≤300 lines

---

References:

• §24244678727

Generated by Repository Quality Improvement Agent · ● 616.5K · ◷

• expires on Apr 11, 2026, 1:19 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-04-11T13:19:10.607Z.

Closed by Workflow