[repository-quality] Repository Quality Improvement — Validation Architecture Compliance (2026-04-27)

[github-actions[bot]]

Analysis Date: 2026-04-27
Focus Area: Validation Architecture Compliance
Strategy Type: Custom (repository-specific)
Custom Area: Yes — gh-aw's AGENTS.md defines explicit size constraints for validator files (target 100–200 lines, hard limit 300 lines). This run audits compliance across all *_validation*.go files.

Executive Summary

The codebase has clear, documented architectural rules for validator files: a 100–200 line target and a 300-line hard limit, with a decision tree for when to split. However, 8 of ~20 validator files currently exceed the hard limit, ranging from 302 to 440 lines. This creates maintenance burden, reduces test isolation, and silently erodes the architecture guidelines that contributors are expected to follow.

The most critical violation is safe_outputs_validation_config.go (440 lines), which is almost entirely a large data declaration with one function — a clear candidate to split into a pure config/data file. Other violations like permissions_validation.go and repository_features_validation.go mix multiple distinct concerns within a single file.

Full Analysis Report

Focus Area: Validation Architecture Compliance

Current State Assessment

AGENTS.md Section "Validation Complexity Guidelines" states:

• Target size: 100–200 lines per validator
• Hard limit: 300 lines (refactor if exceeded)
• When to split: file exceeds 300 lines OR contains 2+ unrelated validation domains

Metrics Collected:

Metric	Value	Status
Total validator files	~20	✅
Files exceeding hard limit (300 lines)	8	❌
Compliance rate	60%	⚠️
Most over-limit file	safe_outputs_validation_config.go (440 lines)	❌
Test-to-source ratio (overall)	218%	✅

Violating Files (sorted by severity):

File	Lines	% Over Limit	Functions	Issue
pkg/workflow/safe_outputs_validation_config.go	440	+47%	1 (+large data var)	Data/config blob in validation file
pkg/workflow/permissions_validation.go	351	+17%	5	Mixes validation + message formatting
pkg/cli/run_workflow_validation.go	350	+17%	5	Mixes file resolution + input validation + remote validation
pkg/workflow/repository_features_validation.go	333	+11%	8	Mixes GitHub API calls + validation logic
pkg/cli/mcp_validation.go	322	+7%	—	Likely multiple sub-domains
pkg/workflow/engine_validation.go	316	+5%	6	Mixes engine registration + validation
pkg/workflow/network_firewall_validation.go	305	+2%	6	Just over the limit
pkg/workflow/expression_safety_validation.go	302	+1%	—	Borderline

Findings

Strengths

• Documentation of the architecture rules exists and is clear (AGENTS.md)
• Most validators (12/20) comply with the 300-line hard limit
• Overall test ratio is excellent (218%), so validators are generally well-tested
• The naming convention ({domain}_{subdomain}_validation.go) is consistently applied

Areas for Improvement

• [High] safe_outputs_validation_config.go: 370+ lines are a large var ValidationConfig data map — this is config/data, not validation logic, and should live in its own file
• [High] permissions_validation.go: Contains both permission validation and message formatting (FormatValidationMessage, formatMissingPermissionsMessage) — 2 distinct concerns
• [Medium] repository_features_validation.go: Contains GitHub API client calls (getRepositoryFeatures, checkRepositoryHasDiscussions, etc.) mixed with the validation orchestrator — the repository API layer should be separated
• [Medium] engine_validation.go: Contains engine registration (registerInlineEngineDefinition) alongside validation — registration is a side-effect, not validation

Detailed Analysis

The split decision tree from AGENTS.md is clear: "File > 300 lines?" → Should split. All 8 files above should have been refactored by this guideline. The root cause is likely organic growth — validators gain complexity as new engine types, tools, and features are added.

The most impactful quick win is safe_outputs_validation_config.go: the huge ValidationConfig var (lines 46–416) is pure data and has nothing in common with validation logic. Extracting it to safe_outputs_types_config.go or similar would immediately bring the file into compliance and improve navigability.

For permissions_validation.go, message formatting is a presentation concern that doesn't belong in validation logic — it should live in a permissions_validation_messages.go or be moved to the console package.

---

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

Improvement Tasks

---

Task 1: Extract ValidationConfig data from safe_outputs_validation_config.go

Priority: High
Estimated Effort: Small
Focus Area: Validation Architecture Compliance

Description:
pkg/workflow/safe_outputs_validation_config.go is 440 lines but has only 1 function. Lines 46–416 are a large var ValidationConfig = map[string]TypeValidationConfig{...} data declaration. The type definitions (FieldValidation, TypeValidationConfig) and the data variable should be moved to a new file, leaving only the GetValidationConfigJSON function (and its logger) in the original file.

Acceptance Criteria:

• Create pkg/workflow/safe_outputs_validation_types.go containing the FieldValidation and TypeValidationConfig type definitions and the ValidationConfig variable
• safe_outputs_validation_config.go retains only the logger, constants, and GetValidationConfigJSON function
• safe_outputs_validation_config.go is under 100 lines after the split
• make build and make test-unit pass without errors
• Run make fmt before committing

Code Region: pkg/workflow/safe_outputs_validation_config.go

In `pkg/workflow/safe_outputs_validation_config.go`, the file is 440 lines but contains only 1 function (`GetValidationConfigJSON`). The rest is type definitions and a large data variable `ValidationConfig`. Per the AGENTS.md validation architecture guidelines (300-line hard limit), this file must be split.

Please:
1. Create a new file `pkg/workflow/safe_outputs_validation_types.go` with the `FieldValidation` struct, `TypeValidationConfig` struct, and the `ValidationConfig` variable (the large `map[string]TypeValidationConfig` starting around line 46).
2. Keep only the `safeOutputValidationLog` logger, constants, and `GetValidationConfigJSON` function in `safe_outputs_validation_config.go`.
3. Run `make build && make test-unit && make fmt` to verify correctness.
4. The split should not change any exported APIs.

---

Task 2: Split permissions_validation.go — separate message formatting

Priority: High
Estimated Effort: Small
Focus Area: Validation Architecture Compliance

Description:
pkg/workflow/permissions_validation.go (351 lines) contains both validation logic and message formatting functions (FormatValidationMessage, formatMissingPermissionsMessage). Per AGENTS.md, files with 2+ unrelated validation domains should be split. Message formatting is a presentation concern separate from validation logic.

Acceptance Criteria:

• Create pkg/workflow/permissions_validation_messages.go containing FormatValidationMessage and formatMissingPermissionsMessage
• permissions_validation.go retains ValidatePermissions, checkMissingPermissions, and ValidateIncludedPermissions
• Both files are under 300 lines
• make build and make test-unit pass
• Run make fmt before committing

Code Region: pkg/workflow/permissions_validation.go

`pkg/workflow/permissions_validation.go` (351 lines) mixes two concerns per the AGENTS.md split criteria:
1. Validation logic: `ValidatePermissions`, `checkMissingPermissions`, `ValidateIncludedPermissions`
2. Message formatting: `FormatValidationMessage`, `formatMissingPermissionsMessage`

Please split into two files:
- `pkg/workflow/permissions_validation.go` — keep only validation functions
- `pkg/workflow/permissions_validation_messages.go` — move message formatting functions

Run `make build && make test-unit && make fmt` to verify. No exported API signatures should change.

---

Task 3: Split repository_features_validation.go — separate API layer from validation

Priority: Medium
Estimated Effort: Medium
Focus Area: Validation Architecture Compliance

Description:
pkg/workflow/repository_features_validation.go (333 lines, 8 functions) mixes two distinct concerns: (1) GitHub API calls to check repository features (getRepositoryFeatures, checkRepositoryHasDiscussions, checkRepositoryHasIssues, and their uncached variants, plus getCurrentRepository), and (2) the validation orchestrator (validateRepositoryFeatures). The API layer should be separated into its own file.

Acceptance Criteria:

• Create pkg/workflow/repository_features_client.go containing the GitHub API helper functions (getCurrentRepository, getCurrentRepositoryUncached, getRepositoryFeatures, checkRepositoryHasDiscussions, checkRepositoryHasDiscussionsUncached, checkRepositoryHasIssues, checkRepositoryHasIssuesUncached)
• repository_features_validation.go retains only validateRepositoryFeatures and the RepositoryFeatures type
• Both files are under 300 lines
• make build and make test-unit pass
• Run make fmt before committing

Code Region: pkg/workflow/repository_features_validation.go

`pkg/workflow/repository_features_validation.go` (333 lines, 8 functions) violates the AGENTS.md 300-line hard limit and contains 2 distinct domains:
1. GitHub API client helpers: `getCurrentRepository`, `getCurrentRepositoryUncached`, `getRepositoryFeatures`, `checkRepositoryHasDiscussions`, `checkRepositoryHasDiscussionsUncached`, `checkRepositoryHasIssues`, `checkRepositoryHasIssuesUncached`
2. Validation orchestration: `validateRepositoryFeatures` (which calls the helpers above)

Please split:
- Move all API/client helper functions into a new `pkg/workflow/repository_features_client.go`
- Keep only `validateRepositoryFeatures` (and `RepositoryFeatures` type if defined here) in `repository_features_validation.go`
- Run `make build && make test-unit && make fmt` to verify. No exported API signatures should change.

---

Task 4: Split engine_validation.go — separate engine registration from validation

Priority: Medium
Estimated Effort: Small
Focus Area: Validation Architecture Compliance

Description:
pkg/workflow/engine_validation.go (316 lines, 6 functions) includes registerInlineEngineDefinition, which is a side-effect registration operation, not a validation function. This mixes registration and validation concerns. Extracting registration to its own file will bring engine_validation.go under the 300-line limit and clarify responsibilities.

Acceptance Criteria:

• Move registerInlineEngineDefinition (and any closely related registration helpers) to pkg/workflow/engine_registration.go
• engine_validation.go is under 300 lines
• make build and make test-unit pass
• Run make fmt before committing

Code Region: pkg/workflow/engine_validation.go

`pkg/workflow/engine_validation.go` (316 lines) exceeds the AGENTS.md 300-line hard limit and contains a registration function `registerInlineEngineDefinition` mixed with validation functions. Registration is a side-effect concern distinct from validation.

Please:
1. Move `registerInlineEngineDefinition` to a new file `pkg/workflow/engine_registration.go`
2. Move any other non-validation helpers that logically belong with registration
3. Confirm `engine_validation.go` is under 300 lines after the split
4. Run `make build && make test-unit && make fmt` to verify correctness

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-04-27	Validation Architecture Compliance	Custom	Yes	First run — 8 validator files exceed 300-line hard limit

---

🎯 Recommendations

Immediate Actions (This Week)

1. Extract ValidationConfig data from safe_outputs_validation_config.go — Priority: High (easiest win, purely mechanical)
2. Split permissions_validation.go — Priority: High (clear domain boundary exists)

Short-term Actions (This Month)

1. Split repository_features_validation.go — Priority: Medium (higher impact but needs careful API boundary review)
2. Split engine_validation.go — Priority: Medium (small change, removes side-effect from validator)

Long-term Actions (This Quarter)

1. Add a CI check that fails if any *_validation*.go file exceeds 300 lines — prevents regression
2. Review remaining borderline files (network_firewall_validation.go at 305, expression_safety_validation.go at 302) for potential minor refactors

---

📈 Success Metrics

Track these metrics to measure improvement in Validation Architecture Compliance:

• Validator files over hard limit: 8 → 0
• Compliance rate: 60% → 100%
• Average validator file size: ~230 lines → <200 lines
• Largest validator file: 440 lines → <300 lines

---

Next Steps

1. Review and prioritize the 4 tasks above
2. Assign tasks to Copilot coding agent via planner agent (Tasks 1 and 2 first — highest priority, smallest effort)
3. Re-evaluate validator compliance after tasks complete
4. Consider adding a Makefile lint rule to prevent regression

---

References:

• §24997222213

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

• expires on Apr 28, 2026, 1:21 PM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #28945.