Repository Quality Improvement Report - Validator File Size Compliance

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Validator File Size Compliance

Analysis Date: 2026-03-17
Focus Area: Validator File Size Compliance
Strategy Type: Custom (first run — no history to guide selection)
Custom Area: Yes — The AGENTS.md explicitly documents a 300-line hard limit and 100-200 line target for validators in pkg/workflow/. Analysis found 10 of 50 validator files violating this guideline, with the worst case at 715 lines — 2.4× the hard limit.

---

Executive Summary

The repository enforces a well-documented validator file size policy (100–200 lines target, 300-line hard limit) that has drifted out of compliance in 10 of the 50 validator files. The average validator file sits at 186 lines — well within the target range — demonstrating that most validators are well-managed. However, the 10 oversize files concentrate significant complexity in ways that reduce readability, increase test surface complexity, and make future contributors less confident about where to add new validation logic.

The primary violation is expression_validation.go at 715 lines (2.4× the limit), which bundles five conceptually distinct concerns: main safety orchestration, dangerous-property checking, runtime import path handling, expression syntax analysis, and quote/brace balancing. Splitting this file would improve clarity with essentially no risk of regression.

Two other high-priority targets are strict_mode_validation.go (546 lines, mixing permissions/network/environment-secret validation concerns) and permissions_validation.go (477 lines, combining toolset-permissions data loading, validation logic, and message formatting).

Full Analysis Report

Focus Area: Validator File Size Compliance

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total validator files	50	✅
Avg lines per validator	186	✅ Within target (100–200)
Files over 300 lines (hard limit)	10	❌
Files over 500 lines	3	❌ Critical
Largest file (expression_validation.go)	715 lines	❌ 2.4× limit
Files within 100–200 line target	27	✅
Files under 100 lines	13	✅

All Oversized Validators (> 300 lines):

File	Lines	% Over Limit	Violation Severity
pkg/workflow/expression_validation.go	715	+138%	❌ Critical
pkg/workflow/strict_mode_validation.go	546	+82%	❌ Critical
pkg/workflow/permissions_validation.go	477	+59%	❌ High
pkg/workflow/safe_outputs_validation_config.go	407	+36%	⚠️ High
pkg/workflow/safe_outputs_validation.go	407	+36%	⚠️ High
pkg/workflow/repository_features_validation.go	367	+22%	⚠️ Medium
pkg/workflow/dispatch_workflow_validation.go	359	+20%	⚠️ Medium
pkg/workflow/runtime_validation.go	355	+18%	⚠️ Medium
pkg/cli/run_workflow_validation.go	344	+15%	⚠️ Medium
pkg/workflow/tools_validation.go	331	+10%	⚠️ Medium

Findings

Strengths

• 80% of validator files (40/50) are within or below the 300-line limit
• Average file size (186 lines) is squarely in the 100–200 line target zone
• Validators are well-named with consistent *_validation.go conventions
• Files well under limit show healthy single-responsibility (e.g., cache_validation.go 39 lines, secrets_validation.go 59 lines)
• The scratchpad documentation (validation-refactoring.md) provides clear guidance for splitting

Areas for Improvement

• expression_validation.go (715 lines): Contains 5 distinct concerns mixed together — expression safety orchestration, dangerous-property logic, runtime import extraction/validation, expression syntax checking, and balanced-brace/quote helpers
• strict_mode_validation.go (546 lines): Combines permissions checks, network policy checks, environment secrets validation, and the top-level orchestrator in a single file
• permissions_validation.go (477 lines): Mixes toolset data initialization (embedded JSON loading, init()), permissions mapping, validation logic, and message formatting across 10 functions
• safe_outputs_validation_config.go and safe_outputs_validation.go are each 407 lines — their two-file structure suggests a split was attempted but didn't fully resolve the size problem

Detailed Analysis

expression_validation.go (715 lines, 11 functions)

Natural split into 3 files:

1. expression_safety_validation.go — validateExpressionSafety(), validateExpressionForDangerousProps(), validateSingleExpression(), containsExpression(), containsLogicalOperators() (~300 lines)
2. expression_syntax_validation.go — validateBalancedBraces(), validateExpressionSyntax(), validateExpressionContent(), validateBalancedQuotes() (~200 lines)
3. runtime_import_validation.go — extractRuntimeImportPaths(), validateRuntimeImportFiles() (~215 lines)

strict_mode_validation.go (546 lines, 10 functions)

Natural split into 3 files:

1. strict_mode_permissions_validation.go — validateStrictPermissions(), validateStrictDeprecatedFields(), validateStrictFirewall() (~150 lines)
2. strict_mode_network_validation.go — validateStrictNetwork(), validateStrictMCPNetwork(), validateStrictTools() (~140 lines)
3. strict_mode_env_validation.go — validateEnvSecrets(), getEngineBaseEnvVarKeys(), validateEnvSecretsSection(), validateStrictMode() (orchestrator) (~260 lines)

permissions_validation.go (477 lines, 10 functions)

Natural split into 2 files:

1. permissions_toolset_data.go — init(), GitHubToolsetPermissions type, GitHubToolsetsData type, collectRequiredPermissions(), isPermissionSufficient() — data and lookup logic (~200 lines)
2. permissions_validation.go — ValidatePermissions(), checkMissingPermissions(), FormatValidationMessage(), formatMissingPermissionsMessage(), ValidateIncludedPermissions() — active validation logic (~280 lines) → still slightly over; could trim to 250 with formatting helpers moved

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: The following tasks are designed for GitHub Copilot coding agent execution. Each is independently actionable. Please split these into individual work items for processing.

Improvement Tasks

Task 1: Split expression_validation.go into three focused files

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

Description:
pkg/workflow/expression_validation.go is 715 lines — 2.4× the 300-line hard limit documented in AGENTS.md. It mixes expression safety orchestration, dangerous-property detection, runtime import path handling, and expression syntax/quote/brace validation. Split it into three files with clear responsibilities.

Acceptance Criteria:

• expression_safety_validation.go contains orchestration and allowlist safety checks (validateExpressionSafety, validateExpressionForDangerousProps, validateSingleExpression, containsExpression, containsLogicalOperators)
• expression_syntax_validation.go contains syntax-level helpers (validateBalancedBraces, validateExpressionSyntax, validateExpressionContent, validateBalancedQuotes)
• runtime_import_validation.go contains import path logic (extractRuntimeImportPaths, validateRuntimeImportFiles)
• Original expression_validation.go is removed or reduced to package-level type declarations only
• All three files are under 300 lines
• make test-unit passes after the split
• make fmt && make lint pass

Code Region: pkg/workflow/expression_validation.go

Split `pkg/workflow/expression_validation.go` (715 lines) into three focused validator files following the AGENTS.md 300-line hard limit.

**Step 1**: Create `pkg/workflow/expression_syntax_validation.go` containing only the syntax-level helper functions: `validateBalancedBraces`, `validateExpressionSyntax`, `validateExpressionContent`, `validateBalancedQuotes`. Move these functions verbatim — do not change logic.

**Step 2**: Create `pkg/workflow/runtime_import_validation.go` containing `extractRuntimeImportPaths` and `validateRuntimeImportFiles`. Move these functions verbatim.

**Step 3**: Rename `expression_validation.go` to `expression_safety_validation.go` (or keep the name) and remove the functions that were moved to the new files. Update any package-level `var` or `type` declarations used only by the moved functions to follow them.

**Step 4**: Verify all imports are correct in each new file (add/remove as needed).

**Step 5**: Run `make fmt && make lint && make test-unit` — all must pass.

Do NOT change any logic, only reorganize code into smaller files.

---

Task 2: Split strict_mode_validation.go into focused concern-specific files

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

Description:
pkg/workflow/strict_mode_validation.go is 546 lines — 1.8× the hard limit. It contains four distinct validation concerns: permissions enforcement, network policy, MCP network requirements, tools checking, deprecated fields, and environment secrets validation. These can be cleanly separated.

Acceptance Criteria:

• strict_mode_permissions_validation.go contains validateStrictPermissions, validateStrictDeprecatedFields, validateStrictFirewall
• strict_mode_network_validation.go contains validateStrictNetwork, validateStrictMCPNetwork, validateStrictTools
• strict_mode_env_validation.go contains validateEnvSecrets, getEngineBaseEnvVarKeys, validateEnvSecretsSection
• strict_mode_validation.go is reduced to the orchestrator validateStrictMode only (and any shared types/vars)
• All resulting files are under 300 lines
• make test-unit passes
• make fmt && make lint pass

Code Region: pkg/workflow/strict_mode_validation.go

Split `pkg/workflow/strict_mode_validation.go` (546 lines) into multiple focused files following the AGENTS.md validator size guidelines.

**Step 1**: Create `pkg/workflow/strict_mode_network_validation.go` containing `validateStrictNetwork`, `validateStrictMCPNetwork`, and `validateStrictTools`. These are all network/tool-access concerns.

**Step 2**: Create `pkg/workflow/strict_mode_env_validation.go` containing `validateEnvSecrets`, `getEngineBaseEnvVarKeys`, and `validateEnvSecretsSection`. These are all environment-secrets concerns.

**Step 3**: Create `pkg/workflow/strict_mode_permissions_validation.go` containing `validateStrictPermissions`, `validateStrictDeprecatedFields`, and `validateStrictFirewall`. These are permissions and firewall concerns.

**Step 4**: Reduce `strict_mode_validation.go` to contain only the orchestrating function `validateStrictMode` plus any shared package-level variables/types not suited to the other files.

**Step 5**: Fix imports in each new file as needed.

**Step 6**: Run `make fmt && make lint && make test-unit` — all must pass.

Do NOT change any function logic. This is a pure code organization refactor.

---

Task 3: Split permissions_validation.go — separate data loading from validation logic

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

Description:
pkg/workflow/permissions_validation.go is 477 lines — 59% over the limit. It mixes two distinct responsibilities: loading and indexing the embedded github_toolsets_permissions.json data, and the active validation/formatting logic. Separating these concerns also makes the data-loading layer independently testable.

Acceptance Criteria:

• permissions_toolset_data.go contains init(), GitHubToolsetPermissions type, GitHubToolsetsData type, toolsetPermissionsMap var, GitHubToolConfig methods, collectRequiredPermissions, isPermissionSufficient — the data layer
• permissions_validation.go retains ValidatePermissions, checkMissingPermissions, FormatValidationMessage, formatMissingPermissionsMessage, ValidateIncludedPermissions — the active validation layer
• Both files are under 300 lines
• make test-unit passes
• make fmt && make lint pass

Code Region: pkg/workflow/permissions_validation.go

Split `pkg/workflow/permissions_validation.go` (477 lines) by separating its data-loading layer from its validation logic layer.

**Step 1**: Create `pkg/workflow/permissions_toolset_data.go`. Move these elements into it:
- The `//go:embed data/github_toolsets_permissions.json` directive and `githubToolsetsPermissionsJSON` var
- `GitHubToolsetPermissions` struct
- `GitHubToolsetsData` struct
- `toolsetPermissionsMap` var
- `ValidatableTool` interface (if defined here)
- `GitHubToolConfig` struct and its methods (`GetToolsets`, `IsReadOnly`)
- The `init()` function that loads the JSON
- `collectRequiredPermissions` function
- `isPermissionSufficient` function

**Step 2**: Keep in `permissions_validation.go`:
- `PermissionsValidationResult` struct (if defined here)
- `ValidatePermissions` function
- `checkMissingPermissions` function
- `FormatValidationMessage` function
- `formatMissingPermissionsMessage` function
- `ValidateIncludedPermissions` function

**Step 3**: Fix imports in both files.

**Step 4**: Run `make fmt && make lint && make test-unit` — all must pass.

Do NOT change any function logic. This is a pure reorganization.

---

Task 4: Add compliance check for validator file sizes to CI

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

Description:
The 300-line hard limit for validators is documented in AGENTS.md but has no automated enforcement. A lightweight shell check in the CI workflow (or Makefile) would prevent future regressions after the current violations are fixed. This could be a simple find | awk check added to make lint or as a dedicated make check-validator-sizes target.

Acceptance Criteria:

• A new Makefile target check-validator-sizes finds all *valid*.go files in pkg/ and fails if any exceed 300 lines
• The target prints the filename and line count for each violation
• The target is added to the make lint or make agent-finish chain
• A comment in the Makefile references the AGENTS.md guideline
• The CI passes (current violations from Tasks 1-3 should be fixed first, OR the check is added after those PRs merge)

Code Region: Makefile

Add a Makefile target to enforce the 300-line validator file size limit documented in AGENTS.md.

Add the following target to the Makefile:

```makefile
## check-validator-sizes: Verify validator files do not exceed 300 lines (AGENTS.md hard limit)
check-validator-sizes:
	`@echo` "Checking validator file sizes..."
	`@violations`=$$(find ./pkg -type f -name "*valid*.go" ! -name "*_test.go" -exec wc -l {} \; | awk '$$1 > 300 {print $$1, $$2}' | sort -rn); \
	if [ -n "$$violations" ]; then \
		echo "❌ Validator files exceeding 300-line limit (AGENTS.md §Validation Complexity Guidelines):"; \
		echo "$$violations"; \
		exit 1; \
	else \
		echo "✅ All validator files within 300-line limit"; \
	fi

Then add check-validator-sizes to the lint target's dependencies (or to agent-finish) so it runs automatically.

Test by running make check-validator-sizes. It should currently fail (showing the 10 violations). After Tasks 1-3 are completed, it should pass.

---

## 📊 Historical Context

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

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|
| 2026-03-17 | Validator File Size Compliance | Custom | Y | First run. Found 10/50 validators over 300-line limit. Worst offender: 715 lines. 4 tasks generated. |

</details>

---

## 🎯 Recommendations

### Immediate Actions (This Week)
1. **Split `expression_validation.go`** (Task 1) — Priority: High. Largest violation at 715 lines. 11 well-scoped functions make the split straightforward.
2. **Split `strict_mode_validation.go`** (Task 2) — Priority: High. Four distinct security concern areas in one file.

### Short-term Actions (This Month)
1. **Split `permissions_validation.go`** (Task 3) — Priority: Medium. Clean data/logic separation opportunity.
2. **Add CI size check** (Task 4) — Priority: Medium. Prevents future regressions automatically.

### Long-term Actions (This Quarter)
1. Address the five medium-priority violations (`safe_outputs_validation_config.go`, `safe_outputs_validation.go`, `repository_features_validation.go`, `dispatch_workflow_validation.go`, `runtime_validation.go`) — each 330–410 lines, requiring more contextual analysis before splitting.

---

## 📈 Success Metrics

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

- **Files over 300-line limit**: 10 → **0** (after all tasks)
- **Largest validator file**: 715 lines → **≤ 300 lines**
- **Avg validator file size**: 186 lines → maintain ≤ 200 lines
- **CI enforcement**: None → Automated `check-validator-sizes` check in `make lint`

---

## Next Steps

1. Review and prioritize Tasks 1–4 above
2. Assign Tasks 1–3 to Copilot coding agent via planner agent (each is independently actionable)
3. Complete Task 4 (CI enforcement) after Tasks 1–3 merge to lock in the gains
4. Re-evaluate validator compliance in ~30 days; target: 0 violations

---

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


> AI generated by [Repository Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/23196685331) · [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-18T13:38:09.905Z --> on Mar 18, 2026, 1:38 PM UTC

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

[github-actions[bot]]

👋 The smoke test agent was here! Passing through on a quality verification mission — checking that all systems are go. 🚀✨

📰 BREAKING: Report filed by Smoke Copilot · ◷

[github-actions[bot]]

🎉 The smoke test agent returns with a second message — fully caffeinated and reporting for duty!

All systems verified operational. The haiku has been dispatched, discussions commented, builds compiled, pages fetched, and files written.

The Copilot was here... and it was glorious. 🤖✨🚀

📰 BREAKING: Report filed by Smoke Copilot · ◷

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #21596.