[repository-quality] Repository Quality Improvement Report - Validator Complexity Compliance

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Validator Complexity Compliance

Analysis Date: 2026-04-15
Focus Area: Validator Complexity Compliance (Custom)
Strategy Type: Custom
Custom Area: Yes — This area specifically targets the repository's own documented hard limit of 300 lines per validator file (from AGENTS.md), which is currently violated by 7 files. Since gh-aw has an explicit validation architecture guideline and a detailed refactoring guide in scratchpad/validation-refactoring.md, this is a uniquely actionable area.

Executive Summary

The repository's AGENTS.md documents a hard limit of 300 lines per validator file with a target of 100–200 lines. Analysis found 7 validator files that exceed this limit, ranging from 19% to 58% over. The most oversized files are tools_validation.go (475 lines), mcp_config_validation.go (462 lines), and safe_outputs_validation_config.go (416 lines). A refactoring guide already exists in scratchpad/validation-refactoring.md, and split patterns can be seen in the existing safe_outputs_validation.go / safe_outputs_validation_config.go pair.

Splitting these files will improve maintainability, make individual validators easier to test in isolation, and bring the codebase into compliance with its own architectural guidelines. Each file has clear function-level seams that make splitting straightforward with no behaviour changes required.

Full Analysis Report

Focus Area: Validator Complexity Compliance

Current State Assessment

Metrics Collected:

Metric	Value	Status
Validator files over hard limit (300 lines)	7	❌
Validator files over target (200 lines)	13+	⚠️
Total validator LOC	11,513	—
Repository test/source ratio	349k/160k (2.2×)	✅
Existing refactoring guide	Yes (scratchpad/validation-refactoring.md)	✅

Files exceeding the 300-line hard limit:

File	Lines	% Over Limit	Function Count
pkg/workflow/tools_validation.go	475	+58%	9
pkg/workflow/mcp_config_validation.go	462	+54%	8
pkg/workflow/safe_outputs_validation_config.go	416	+39%	1 (large)
pkg/workflow/template_injection_validation.go	384	+28%	8
pkg/workflow/dispatch_workflow_validation.go	363	+21%	8
pkg/workflow/safe_outputs_validation.go	358	+19%	6
pkg/workflow/permissions_validation.go	351	+17%	5

Findings

Strengths

• Repository has a clear refactoring guide: scratchpad/validation-refactoring.md
• AGENTS.md explicitly documents target (100–200 lines) and hard limit (300 lines)
• Existing split pattern in safe_outputs_validation.go + safe_outputs_validation_config.go
• Tests are comprehensive (2.2× test/source ratio) so refactoring can be verified safely
• Most files have clear function-level seams (distinct validation domains within one file)

Areas for Improvement

• [HIGH] tools_validation.go (475 lines): 9 functions spanning bash tool validation, GitHub tool config, guard policies, integrity reactions, and repo scope validation — clearly 3+ distinct domains
• [HIGH] mcp_config_validation.go (462 lines): Core MCP config validation mixed with property validation, type inference, and mount syntax — at least 3 splitworthy groups
• [MEDIUM] template_injection_validation.go (384 lines): Detection logic, extraction utilities, and error formatting — 3 distinct responsibilities
• [MEDIUM] dispatch_workflow_validation.go (363 lines): Dispatch validation mixed with file-resolution utilities (findWorkflowFile, isPathWithinDir)
• [LOW] permissions_validation.go (351 lines): Slightly over limit; ValidateIncludedPermissions is functionally distinct from the others

Detailed Analysis

The AGENTS.md decision tree for splitting is clear: any file over 300 lines containing 2+ distinct domains should be split. All 7 flagged files meet this criterion.

The existing safe_outputs_validation.go / safe_outputs_validation_config.go split demonstrates the pattern — but note that safe_outputs_validation_config.go itself is now 416 lines with a single large function GetValidationConfigJSON, suggesting it may need further extraction of helper logic.

For tools_validation.go, the natural split is:

• tools_validation_github.go — GitHub tool config, guard policy, integrity reactions, repo scope, tool/toolset validation (8 functions)
• tools_validation.go — Bash tool config + orchestration (keep small)

For mcp_config_validation.go, the split follows:

• mcp_config_validation.go — top-level ValidateMCPConfigs, ValidateToolsSection
• mcp_property_validation.go — validateStringProperty, validateMCPRequirements, buildSchemaMCPConfig
• mcp_mount_validation.go — validateMCPMountsSyntax

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following 5 tasks are designed for GitHub Copilot coding agent execution. Please split these into individual work items for Claude to process. Each task is self-contained and independently actionable.

Improvement Tasks

---

Task 1: Split tools_validation.go into GitHub-specific and general validation

Priority: High
Estimated Effort: Small
Focus Area: Validator Complexity Compliance

Description:
pkg/workflow/tools_validation.go is 475 lines (58% over the 300-line hard limit). It contains 9 functions across at least 3 distinct domains: bash tool validation, GitHub tool config/policy validation, and repo scope/pattern validation. Extract the 8 GitHub-specific functions into a new file.

Acceptance Criteria:

• New file pkg/workflow/tools_validation_github.go created containing: validateGitHubReadOnly, validateGitHubToolConfig, validateGitHubGuardPolicy, validateIntegrityReactions, validateReposScope, validateRepoPattern, isValidOwnerOrRepo, ValidateGitHubToolsAgainstToolsets
• pkg/workflow/tools_validation.go retains only validateBashToolConfig plus any orchestration/dispatcher functions, and is under 300 lines
• All existing tests pass (make test-unit)
• make fmt and make lint pass with no new issues

Code Region: pkg/workflow/tools_validation.go

Refactor `pkg/workflow/tools_validation.go` to comply with the repository's 300-line validator hard limit (documented in AGENTS.md).

The file is currently 475 lines. Create a new file `pkg/workflow/tools_validation_github.go` and move the following functions into it:
- `validateGitHubReadOnly`
- `validateGitHubToolConfig`
- `validateGitHubGuardPolicy`
- `validateIntegrityReactions`
- `validateReposScope`
- `validateRepoPattern`
- `isValidOwnerOrRepo`
- `ValidateGitHubToolsAgainstToolsets`

Keep `validateBashToolConfig` and any remaining orchestration in `tools_validation.go`.

Both files must remain in the `workflow` package. No behaviour changes — pure file split.

After splitting, verify:
1. `make fmt` passes
2. `make lint` passes  
3. `go test -run ".*" ./pkg/workflow/` passes

---

Task 2: Split mcp_config_validation.go into focused sub-validators

Priority: High
Estimated Effort: Small
Focus Area: Validator Complexity Compliance

Description:
pkg/workflow/mcp_config_validation.go is 462 lines (54% over limit). It mixes top-level config validation entry points, property validation helpers, type inference, and mount syntax validation. Split into 3 focused files following the naming convention {domain}_{subdomain}_validation.go.

Acceptance Criteria:

• pkg/workflow/mcp_config_validation.go retains: ValidateMCPConfigs, ValidateToolsSection, getRawMCPConfig, inferMCPType — under 250 lines
• New file pkg/workflow/mcp_property_validation.go created with: validateStringProperty, validateMCPRequirements, buildSchemaMCPConfig
• New file pkg/workflow/mcp_mount_validation.go created with: validateMCPMountsSyntax
• All files under 300 lines
• All existing tests pass (make test-unit)
• make fmt and make lint pass

Code Region: pkg/workflow/mcp_config_validation.go

Refactor `pkg/workflow/mcp_config_validation.go` (462 lines) to comply with the repository's 300-line validator hard limit from AGENTS.md.

Split it into 3 files (all in the `workflow` package, no behaviour changes):

1. **`pkg/workflow/mcp_config_validation.go`** (keep): `ValidateMCPConfigs`, `ValidateToolsSection`, `getRawMCPConfig`, `inferMCPType`

2. **`pkg/workflow/mcp_property_validation.go`** (new): `validateStringProperty`, `validateMCPRequirements`, `buildSchemaMCPConfig`

3. **`pkg/workflow/mcp_mount_validation.go`** (new): `validateMCPMountsSyntax`

Each resulting file must be under 300 lines. No logic changes — pure file reorganization.

After splitting:
1. `make fmt` passes
2. `make lint` passes
3. `go test -run ".*" ./pkg/workflow/` passes

---

Task 3: Split template_injection_validation.go by responsibility

Priority: Medium
Estimated Effort: Small
Focus Area: Validator Complexity Compliance

Description:
pkg/workflow/template_injection_validation.go is 384 lines. It contains 8 functions with 3 distinct responsibilities: detection, extraction utilities, and error formatting. Extract utilities and formatting into a separate file.

Acceptance Criteria:

• pkg/workflow/template_injection_validation.go retains core validation: hasUnsafeExpressionInRunContent, validateNoTemplateInjection, validateNoTemplateInjectionFromParsed — under 250 lines
• New file pkg/workflow/template_injection_utils.go created with: extractRunBlocks, removeHeredocContent, extractRunSnippet, detectExpressionContext, formatTemplateInjectionError
• All existing tests pass (make test-unit)
• make fmt and make lint pass

Code Region: pkg/workflow/template_injection_validation.go

Refactor `pkg/workflow/template_injection_validation.go` (384 lines) to comply with the repository's 300-line hard limit from AGENTS.md.

Create a new file `pkg/workflow/template_injection_utils.go` (same `workflow` package) with these utility/helper functions:
- `extractRunBlocks`
- `removeHeredocContent`
- `extractRunSnippet`
- `detectExpressionContext`
- `formatTemplateInjectionError`

Keep the core validation entry points in `template_injection_validation.go`:
- `hasUnsafeExpressionInRunContent`
- `validateNoTemplateInjection`
- `validateNoTemplateInjectionFromParsed`

No behaviour changes. After splitting:
1. `make fmt` passes
2. `make lint` passes
3. `go test -run ".*TemplateInjection.*\|.*templateInjection.*" ./pkg/workflow/` passes

---

Task 4: Extract file-resolution utilities from dispatch_workflow_validation.go

Priority: Medium
Estimated Effort: Small
Focus Area: Validator Complexity Compliance

Description:
pkg/workflow/dispatch_workflow_validation.go is 363 lines and mixes two clearly distinct concerns: (1) dispatch workflow validation logic and (2) workflow file-resolution utilities (findWorkflowFile, isPathWithinDir, etc.). The file utilities can be extracted independently.

Acceptance Criteria:

• New file pkg/workflow/dispatch_workflow_file_resolver.go created with: getCurrentWorkflowName, isPathWithinDir, findWorkflowFile, mdHasWorkflowDispatch, extractMDWorkflowDispatchInputs
• pkg/workflow/dispatch_workflow_validation.go retains: validateDispatchWorkflow, extractWorkflowDispatchInputs, containsWorkflowDispatch — under 200 lines
• All existing tests pass (make test-unit)
• make fmt and make lint pass

Code Region: pkg/workflow/dispatch_workflow_validation.go

Refactor `pkg/workflow/dispatch_workflow_validation.go` (363 lines) to comply with the repository's 300-line validator hard limit from AGENTS.md.

Create a new file `pkg/workflow/dispatch_workflow_file_resolver.go` (same `workflow` package) containing these file-resolution utility functions:
- `getCurrentWorkflowName`
- `isPathWithinDir`
- `findWorkflowFile` (and any associated types like `findWorkflowFileResult`)
- `mdHasWorkflowDispatch`
- `extractMDWorkflowDispatchInputs`

Keep in `dispatch_workflow_validation.go`:
- `validateDispatchWorkflow`
- `extractWorkflowDispatchInputs`
- `containsWorkflowDispatch`

No behaviour changes. After splitting:
1. `make fmt` passes
2. `make lint` passes
3. `go test -run ".*[Dd]ispatch.*" ./pkg/workflow/` passes

---

Task 5: Bring safe_outputs_validation.go under the hard limit

Priority: Low
Estimated Effort: Small
Focus Area: Validator Complexity Compliance

Description:
pkg/workflow/safe_outputs_validation.go is 358 lines. The file already has a companion safe_outputs_validation_config.go (416 lines, itself over the limit). The validateSafeOutputsMax function (lines 222–315) is 93 lines and handles a distinct sub-domain (max value validation) that could be extracted.

Acceptance Criteria:

• pkg/workflow/safe_outputs_validation.go is under 300 lines after the refactor
• Extracted functions placed in appropriately named file(s) within pkg/workflow/
• All existing tests pass (make test-unit)
• make fmt and make lint pass

Code Region: pkg/workflow/safe_outputs_validation.go

Refactor `pkg/workflow/safe_outputs_validation.go` (358 lines) to comply with the 300-line hard limit documented in AGENTS.md.

Review the file and identify the most self-contained function group to extract. The `validateSafeOutputsMax` function (handling max-value validation, ~93 lines) and `validateSafeOutputsAllowWorkflows` (~42 lines) are good candidates for extraction into `pkg/workflow/safe_outputs_max_validation.go`.

Move to a new file `pkg/workflow/safe_outputs_max_validation.go` (same `workflow` package):
- `validateSafeOutputsMax`
- `isInvalidMaxValue`

Optionally also move:
- `validateSafeOutputsAllowWorkflows`

Keep in `safe_outputs_validation.go`:
- `validateSafeOutputsAllowedDomains`
- `validateSafeOutputsTarget`
- `validateTargetValue`
- `isGitHubExpression`

No behaviour changes. After splitting:
1. `make fmt` passes
2. `make lint` passes
3. `go test -run ".*SafeOutput.*\|.*safeOutput.*" ./pkg/workflow/` passes

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-15	Validator Complexity Compliance	Custom	Yes	Identified 7 validators exceeding the 300-line hard limit; generated 5 refactoring tasks

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split tools_validation.go (Task 1) — Priority: High, most oversized at 475 lines
2. Split mcp_config_validation.go (Task 2) — Priority: High, 462 lines with 3 clear domains

Short-term Actions (This Month)

1. Split template_injection_validation.go (Task 3) — Priority: Medium
2. Extract file-resolver from dispatch_workflow_validation.go (Task 4) — Priority: Medium

Long-term Actions (This Quarter)

1. Trim safe_outputs_validation.go (Task 5) — Priority: Low, smallest overage
2. Consider adding a CI lint rule (e.g., a shell check in the Makefile) that fails if any *_validation.go file exceeds 300 lines — prevents regression

---

📈 Success Metrics

Track these metrics to measure improvement:

• Validators over 300 lines: 7 → 0
• Largest single validator file: 475 lines → < 300 lines
• Average validator file size: ~200+ lines → 100–200 lines (target)
• Files fully compliant with AGENTS.md limit: ~60% → 100%

---

Next Steps

1. Review and prioritize the 5 tasks above
2. Assign tasks to Copilot coding agent via planner agent (Tasks 1 & 2 first)
3. Track progress — each split is verifiable with wc -l and make test-unit
4. Re-evaluate validator sizes after refactoring to confirm compliance

References:

• §24456571855

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

• expires on Apr 16, 2026, 1:20 PM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment