[repository-quality] Repository Quality Improvement Report - Go Source File Decomposition (2026-05-15)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Go Source File Decomposition

Analysis Date: 2026-05-15
Focus Area: Go Source File Decomposition
Strategy Type: Custom
Custom Area: Yes — this repository has a documented 300-line hard limit (AGENTS.md) with many files far exceeding it; decomposition opportunities are concrete and high-value.

Executive Summary

The pkg/workflow and pkg/parser packages contain 29 source files exceeding 800 lines, with 6 files over 1000 lines — far above the 300-line target documented in AGENTS.md. These oversized files accumulate multiple distinct responsibilities, making navigation, testing, and review significantly harder.

The most impactful candidates for decomposition are domains.go (1041 lines, 23 functions spanning ecosystems, engines, runtimes, and network), frontmatter_extraction_yaml.go (1153 lines, 13 functions mixing YAML extraction logic for triggers, permissions, and commands), and import_field_extractor.go (1172 lines, 18 functions covering import validation, schema checking, and input substitution).

Each identified decomposition follows clear conceptual seams already present in the code, meaning these are straightforward extract-and-rename operations rather than architectural rewrites. Addressing the top 5 would reduce average file size by roughly 30% in the affected packages and align the codebase with its own documented standards.

Full Analysis Report

Focus Area: Go Source File Decomposition

Current State Assessment

Metrics Collected:

Metric	Value	Status
Files ≥ 800 lines (extreme)	29	❌
Files 500–800 lines (severe)	70	⚠️
Files 300–500 lines (moderate)	122	⚠️
Files within 300-line guideline	~571	✅
Total non-test source files	792	—
Documented hard limit (AGENTS.md)	300 lines	—
Largest file	import_field_extractor.go (1172 lines)	❌

Findings

Strengths

• AGENTS.md clearly documents the 300-line hard limit, signalling awareness of the problem
• Many large files already have some internal grouping via comments (e.g., compiler_yaml_main_job.go)
• Test coverage is exceptional (402k test LOC vs 192k source LOC — ~2:1 ratio), so refactors can be validated confidently

Areas for Improvement

• 🔴 pkg/parser/import_field_extractor.go (1172 lines): 18 functions across import accumulation, schema validation, input substitution, and observability config merging — 4 distinct domains in one file
• 🔴 pkg/workflow/frontmatter_extraction_yaml.go (1153 lines): Functions for trigger YAML extraction, permissions extraction, if-condition parsing, and command/label config — clear split points at lines ~107 (triggers) and ~765 (permissions/conditions)
• 🔴 pkg/workflow/domains.go (1041 lines): 23 functions mixing ecosystem domain tables, engine-specific defaults, runtime-based domains, HTTP MCP domain extraction, network permission domains, and API target domains
• 🔴 pkg/workflow/cache.go (1006 lines): Cache key generation, cache config types, and cache YAML step generation are intermingled
• 🟠 pkg/workflow/imports.go (795 lines): Merge operations for 6 different config types (tools, MCP servers, network, safe-outputs, features, env) could each live in their own file

Detailed Analysis

pkg/workflow/domains.go — Highest-Value Split

This file has 23 functions across clearly separable concerns:

• Lines 1–232: Constants and init, ecosystem domain data (npm, pypi, brew categories) → domains_ecosystem.go
• Lines 233–399: Engine-specific default domains (OpenCode, Crush, Pi, generic) → domains_engine_defaults.go
• Lines 399–485: Runtime-derived domains (node, python, go, etc.) → domains_runtime.go
• Lines 487–668: Core domain matching and HTTP MCP extraction → domains_network.go
• Lines 686–1041: Engine-level APIs and blocked/API target domains → stays in domains.go (reduced to ~350 lines)

pkg/parser/import_field_extractor.go — Most Complex File

18 functions across:

• Import accumulation and frontmatter processing (core logic)
• Schema validation and input type checking (lines 867–1030)
• Input substitution (lines 1031–1172)
• Observability config merging (lines 719–837)

Each section is independently testable and has its own data types.

pkg/workflow/frontmatter_extraction_yaml.go — Trigger vs Non-Trigger

The file's 1153 lines break into:

• frontmatter_extraction_triggers.go: The massive commentOutProcessedFieldsInOnSection function (lines 107–711, ~600 lines alone) handles trigger YAML processing
• frontmatter_extraction_conditions.go: extractPermissions, extractIfCondition, deployment conditions
• frontmatter_extraction_commands.go: extractCommandConfig, extractLabelCommandConfig

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items. Each task is independently executable and requires no coordination with others.

Improvement Tasks

Task 1: Split pkg/workflow/domains.go into Focused Sub-files

Priority: High
Estimated Effort: Medium
Focus Area: Go Source File Decomposition

Description: domains.go is 1041 lines with 23 functions across 4 conceptually distinct domains. Split it into sub-files following the seams already present in the code, while keeping the package-level API identical (no exported symbol renames).

Acceptance Criteria:

• domains_ecosystem.go: ecosystem domain lookup tables and init() registration (lines ~1–399)
• domains_engine_defaults.go: getOpenCodeDefaultDomains, getCrushDefaultDomains, getPiDefaultDomains, GetDefaultDomainsForEngine (~lines 233–399 + 750–811)
• domains_runtime.go: getDomainsFromRuntimes and related helpers (~lines 399–487)
• domains.go retains: GetAllowedDomains, matchesDomain, GetDomainEcosystem, HTTP MCP extraction, blocked/API-target domain functions (~350 lines)
• make build && make test-unit pass with no changes to exported API
• Each resulting file is ≤ 400 lines

Code Region: pkg/workflow/domains.go

Split `pkg/workflow/domains.go` (1041 lines) into focused sub-files without changing any exported symbols.

The file has four clearly separated concerns already visible in the code structure:

1. **Ecosystem domain tables** (`domains_ecosystem.go`): the `init()` registration and `getEcosystemDomains()` function, plus any embedded data for npm/pypi/brew categories. These are pure static data with no dependencies on other functions in the file.

2. **Engine-specific domain defaults** (`domains_engine_defaults.go`): `extractProviderFromModel`, `getOpenCodeDefaultDomains`, `getCrushDefaultDomains`, `getPiDefaultDomains`, `GetDefaultDomainsForEngine`, `GetAllowedDomainsForEngineWithModel`, `mustGetAllowedDomainsForEngineWithModel`, `GetAllowedDomainsForEngine`. These are cohesive: given an engine+model, return domains.

3. **Runtime-derived domains** (`domains_runtime.go`): `getDomainsFromRuntimes` and any private helpers it calls. This is a single responsibility: map runtime configuration to network domains.

4. **`domains.go`** (reduced): `GetAllowedDomains`, `GetDomainEcosystem`, `matchesDomain`, `extractHTTPMCPDomains`, `extractPlaywrightDomains`, `mergeDomainsWithNetworkToolsAndRuntimes`, `GetThreatDetectionAllowedDomains`, `GetBlockedDomains`, `formatBlockedDomains`, `GetAPITargetDomains`, `mergeAPITargetDomains`, `computeAllowedDomainsForSanitization`, `computeExpandedAllowedDomainsForSanitization`, `expandAllowedDomains`.

Steps:
1. Read `pkg/workflow/domains.go` carefully to map each function to one of the four groups.
2. Create the new files in `pkg/workflow/` with the `package workflow` declaration.
3. Move the relevant functions and any file-scoped variables/constants they depend on.
4. Delete the moved code from `domains.go`.
5. Run `make build` — fix any compile errors caused by missing variable references.
6. Run `make test-unit` — all tests must pass.
7. Verify each resulting file is ≤ 400 lines.

Do NOT rename any exported functions or change any function signatures. This is purely a file organization change.

---

Task 2: Split pkg/parser/import_field_extractor.go into Focused Sub-files

Priority: High
Estimated Effort: Medium
Focus Area: Go Source File Decomposition

Description: import_field_extractor.go is the largest file at 1172 lines with 18 functions. It mixes import accumulation, schema validation, input substitution, and observability merging. Each section is independently testable.

Acceptance Criteria:

• import_field_extractor.go retains: importAccumulator struct, newImportAccumulator, extractAllImportFields, prepareFrontmatter, extractEngineConfig, extractConfigFields, extractActivationFields, extractStepAndJobFields, extractFeatureAndObservabilityFields, toImportsResult, computeImportRelPath, validateGitHubAppJSON (~700 lines)
• import_schema_validation.go: validateWithImportSchema, validateObjectInput, validateImportInputType, applyImportSchemaDefaultsFromFrontmatter (~165 lines)
• import_input_substitution.go: substituteImportInputsInContent and any helpers (~90 lines)
• import_observability.go: extractOTLPEndpointsFromObsMap, mergeObservabilityConfigs (~120 lines)
• make build && make test-unit pass with no changes to exported API

Code Region: pkg/parser/import_field_extractor.go

Split `pkg/parser/import_field_extractor.go` (1172 lines) into focused sub-files in `pkg/parser/` without changing any exported symbols or function signatures.

The natural seams are:

1. **`import_schema_validation.go`** — functions `validateWithImportSchema` (line ~867), `validateObjectInput` (line ~919), `validateImportInputType` (line ~964), `applyImportSchemaDefaultsFromFrontmatter` (line ~1031). These are cohesive: validate that import inputs match declared schema types and apply defaults.

2. **`import_input_substitution.go`** — function `substituteImportInputsInContent` (line ~1087) and any private helpers it calls. This handles template substitution of `${{ inputs.x }}` placeholders in imported workflow content.

3. **`import_observability.go`** — functions `extractOTLPEndpointsFromObsMap` (line ~719) and `mergeObservabilityConfigs` (line ~775). These handle OTLP endpoint extraction and merging of observability configuration.

4. **`import_field_extractor.go`** (reduced): everything else — the core `importAccumulator` struct and its methods, `computeImportRelPath`, `validateGitHubAppJSON`.

Steps:
1. Read the file from line 719 to end to understand the function boundaries precisely.
2. Create the three new files in `pkg/parser/` with `package parser` declaration and any required imports.
3. Move functions to their respective files.
4. Remove the moved functions from `import_field_extractor.go`.
5. Run `make build` and fix any missing-symbol errors.
6. Run `make test-unit` — all tests must pass.
7. Add build tags (`//go:build !integration`) at the top of any new test files if created.

---

Task 3: Split pkg/workflow/frontmatter_extraction_yaml.go into Trigger vs Non-Trigger

Priority: Medium
Estimated Effort: Medium
Focus Area: Go Source File Decomposition

Description: frontmatter_extraction_yaml.go is 1153 lines. The commentOutProcessedFieldsInOnSection function alone is ~600 lines (handling all trigger YAML processing). Extract triggers and conditions into focused files.

Acceptance Criteria:

• frontmatter_extraction_triggers.go: commentOutProcessedFieldsInOnSection, addZizmorIgnoreForWorkflowRun, and trigger-specific helpers (~700 lines)
• frontmatter_extraction_conditions.go: extractPermissions, extractIfCondition, extractDeploymentStatusStateCondition, isValidWorkflowRunConclusion, extractWorkflowRunConclusionCondition, extractExpressionFromIfString (~230 lines)
• frontmatter_extraction_commands.go: extractCommandConfig, extractLabelCommandConfig, isGitHubAppNestedField (~230 lines)
• frontmatter_extraction_yaml.go retains: indentYAMLLines, extractTopLevelYAMLSection (~110 lines)
• make build && make test-unit pass

Code Region: pkg/workflow/frontmatter_extraction_yaml.go

Split `pkg/workflow/frontmatter_extraction_yaml.go` (1153 lines) into focused sub-files in `pkg/workflow/` without changing any exported symbols or function signatures.

The file has four natural sections:

1. **`frontmatter_extraction_triggers.go`**: the `commentOutProcessedFieldsInOnSection` method (lines ~107–711, the largest single function in the file) and `addZizmorIgnoreForWorkflowRun` (lines ~712–764). These handle raw YAML transformation of trigger definitions (`on:` section).

2. **`frontmatter_extraction_conditions.go`**: `extractPermissions` (line ~765), `extractIfCondition` (line ~799), `extractDeploymentStatusStateCondition` (line ~839), `isValidWorkflowRunConclusion` (line ~902), `extractWorkflowRunConclusionCondition` (line ~908), `extractExpressionFromIfString` (line ~968). These are cohesive: compute `if:` conditions and permissions for the workflow job.

3. **`frontmatter_extraction_commands.go`**: `extractCommandConfig` (line ~986), `extractLabelCommandConfig` (line ~1068), `isGitHubAppNestedField` (line ~1144). These extract slash-command and label-trigger configurations.

4. **`frontmatter_extraction_yaml.go`** (reduced): `indentYAMLLines` (line 18) and `extractTopLevelYAMLSection` (line 43). Core YAML formatting utilities used by the other files.

Steps:
1. Read the full file to understand any shared private helpers.
2. Create three new files in `pkg/workflow/` with `package workflow` and required imports.
3. Move the function groups as described.
4. Remove moved code from `frontmatter_extraction_yaml.go`.
5. Run `make build` and fix any missing-symbol errors.
6. Run `make test-unit` — all tests must pass.

---

Task 4: Split pkg/workflow/imports.go by Merge Domain

Priority: Medium
Estimated Effort: Small
Focus Area: Go Source File Decomposition

Description: imports.go (795 lines) has 10+ merge functions each handling a separate config domain (tools, MCP servers, network, safe-outputs, features, env). Each could be a focused file or logically grouped.

Acceptance Criteria:

• imports_tools.go: MergeTools, MergeMCPServers (~100 lines)
• imports_network.go: MergeNetworkPermissions (~65 lines)
• imports_safe_outputs.go: MergeSafeOutputs, hasSafeOutputType, mergeSafeOutputConfig, mergeMessagesConfig, getSafeOutputTypeKeys (~500 lines)
• imports_features.go: MergeFeatures, mergeEnv (~80 lines)
• imports.go removed or retained as empty package doc file
• make build && make test-unit pass

Code Region: pkg/workflow/imports.go

Split `pkg/workflow/imports.go` (795 lines) into domain-focused sub-files in `pkg/workflow/`.

The file currently has 10 exported merge functions, each responsible for merging a single workflow configuration domain when processing imports. The natural grouping is:

1. **`imports_tools.go`**: `MergeTools` and `MergeMCPServers` — both merge tool-related configuration maps.

2. **`imports_network.go`**: `MergeNetworkPermissions` — merges network allow/deny lists.

3. **`imports_safe_outputs.go`**: `getSafeOutputTypeKeys`, `MergeSafeOutputs`, `hasSafeOutputType`, `mergeSafeOutputConfig`, `mergeMessagesConfig` — safe-outputs is the most complex domain and justifies its own file (~500 lines).

4. **`imports_features.go`**: `MergeFeatures` and `mergeEnv` — merge feature flags and environment variables.

Steps:
1. Read `pkg/workflow/imports.go` to identify function boundaries and shared private helpers.
2. Create the four new files with `package workflow` declarations and required imports.
3. Move each function group to its file.
4. Delete `imports.go` or retain it as an empty file with only the `package workflow` declaration.
5. Run `make build` — resolve any missing symbol errors.
6. Run `make test-unit` — all tests must pass.

---

Task 5: Add File-Size Linter Check for New Validator Files

Priority: Low
Estimated Effort: Small
Focus Area: Go Source File Decomposition

Description: The 300-line guideline is documented but unenforced. Add a lightweight CI check (shell script or Go test) that fails if any *_validation.go file exceeds 300 lines, preventing future drift specifically for the validator category.

Acceptance Criteria:

• A check exists in Makefile or .github/workflows/ci.yml that finds *_validation.go files exceeding 300 lines
• The check prints the offending filename and line count
• The check exits non-zero when violations exist
• The check is integrated into make lint or a dedicated make check-file-sizes target
• Existing *_validation.go files all pass (or violations are documented as known exceptions)
• make agent-finish passes end-to-end

Code Region: Makefile, .github/workflows/ci.yml

Add a lightweight file-size enforcement check to prevent validator files from growing beyond the documented 300-line hard limit.

The check should:
1. Find all files matching `*_validation.go` in `pkg/` (recursively).
2. For each file, count non-blank, non-comment lines (or use raw `wc -l` for simplicity).
3. Print any file exceeding 300 lines with its name and count.
4. Exit non-zero if any violations exist.

Implementation options (choose the simplest):

**Option A — Shell one-liner in Makefile:**
```makefile
check-validator-sizes:
`@violations`=$$(find pkg -name "*_validation.go" | xargs wc -l 2>/dev/null | awk '$$1 > 300 && $$2 != "total" {print $$2 ": " $$1 " lines"}'); \
if [ -n "$$violations" ]; then echo "Validator files exceeding 300-line limit:"; echo "$$violations"; exit 1; fi
`@echo` "All validator files are within the 300-line limit."

Option B — Go test in pkg/workflow/ or pkg/parser/:
A table-driven test that opens each *_validation.go file and asserts lineCount <= 300.

Add the chosen check to:

• Makefile as check-validator-sizes target
• The lint target's dependency list (or a new check target)
• .github/workflows/ci.yml if it has a dedicated lint job

Run make agent-finish to confirm all CI gates pass.

---

## 📊 Historical Context

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

| Date | Focus Area | Type | Custom | Key Outcomes |
|------|------------|------|--------|--------------|
| 2026-05-15 | Go Source File Decomposition | Custom | Y | First run — identified 29 files > 800 lines; 5 actionable tasks created |

</details>

---

## 🎯 Recommendations

### Immediate Actions (This Week)
1. **Split `domains.go`** — highest function count (23) with clearest seams — Priority: High
2. **Split `import_field_extractor.go`** — largest file, 4 independent concerns — Priority: High

### Short-term Actions (This Month)
1. **Split `frontmatter_extraction_yaml.go`** — the 600-line trigger function alone is a maintenance liability — Priority: Medium
2. **Split `imports.go`** — straightforward grouping by merge domain — Priority: Medium

### Long-term Actions (This Quarter)
1. **Add file-size linter** — prevent future drift in validator files — Priority: Low
2. **Apply decomposition to remaining 800+ line files** — `cache.go`, `threat_detection.go`, `audit.go`, `forecast.go` — Priority: Medium

---

## 📈 Success Metrics

- **Files > 800 lines**: 29 → 0 (after completing Tasks 1–4)
- **Average file size (pkg/workflow)**: ~340 lines → ≤ 250 lines
- **Largest file**: 1172 lines → ≤ 400 lines

---

## Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on file size reduction
4. Re-evaluate this focus area in 3 months

---

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




> Generated by [⚡ Repository Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/25919970142) · ● 9.3M · [◷](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-05-16T13:26:45.671Z --> on May 16, 2026, 1:26 PM UTC

<!-- gh-aw-agentic-workflow: Repository Quality Improvement Agent, engine: copilot, version: 1.0.43, model: claude-sonnet-4.6, id: 25919970142, workflow_id: repository-quality-improver, run: https://github.com/github/gh-aw/actions/runs/25919970142 -->

<!-- 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-05-16T13:26:45.671Z.

Closed by Workflow