[refactor] Semantic Function Clustering Analysis: Outlier Functions and File Organization Improvements

[github-actions]

Overview

This issue summarizes the results of a semantic function clustering and refactoring analysis performed on all non-test Go source files in the pkg/ directory. The analysis covered 762 source files containing 3,727 function definitions across 23 packages.

Overall, the codebase is well-organized: naming conventions are consistent, the *_validation.go / *_parser.go / *_generation.go file naming pattern is applied broadly, and platform-specific (wasm/non-wasm) duplication is correctly handled with build constraints. However, a few concrete outliers were found.

---

Identified Issues

1. env.go — Misnamed File (YAML Utilities, Not Environment Config)

File: pkg/workflow/env.go (54 lines, 3 functions)

env.go contains only YAML-generation helper functions — nothing related to environment variables or configuration:

// pkg/workflow/env.go
func writeYAMLEnv(b *strings.Builder, indent, key, value string)
func formatYAMLEnv(indent, key, value string) string
func writeHeadersToYAML(yaml *strings.Builder, headers map[string]string, indent string)

The filename env.go strongly implies environment variable management, but every function in the file is a YAML string builder utility — used by compiler_yaml_main_job.go and similar files.

Recommendation: Rename env.go to yaml_env_helpers.go, or merge these three small helpers directly into compiler_yaml.go / compiler_yaml_helpers.go where the rest of the YAML generation lives.

Estimated effort: ~15 minutes (rename + update any internal references)

---

2. model_identifier.go — Public Validation Functions Mixed With Parsing Logic

File: pkg/workflow/model_identifier.go (417 lines)

This file is the parser/tokenizer for model identifier strings (e.g., provider/model?effort=high). It has a clear parser responsibility. However, it also exports three business-rule validation functions that belong with model alias validation:

// pkg/workflow/model_identifier.go — candidates to move to model_alias_validation.go
func ValidateEffortParam(value string) error          // Validates "effort" parameter values
func ValidateTemperatureParam(value string) error     // Validates "temperature" float range
func ValidateKnownParams(params map[string]string) error // Validates all known query params

These public functions enforce business rules (effort must be low/medium/high; temperature must be in [0.0, 2.0]). The private parse-time validators in the same file (validateProviderToken, validateModelToken, validateParamKey, etc.) are part of the parsing machinery and should stay — but the three public ones are semantic validators that logically belong alongside pkg/workflow/model_alias_validation.go, which already handles model alias constraints.

Recommendation: Move ValidateEffortParam, ValidateTemperatureParam, and ValidateKnownParams to model_alias_validation.go. The private parse-time validators stay in model_identifier.go.

Estimated effort: ~30 minutes (move functions + update call sites)

---

3. action_sha_checker.go — Validation Orchestrator in a Checker File

File: pkg/workflow/action_sha_checker.go (211 lines)

The file correctly owns ExtractActionsFromLockFile and CheckActionSHAUpdates (extraction and diff checking). However, ValidateActionSHAsInLockFile is a user-facing validation orchestrator — it calls the other two functions, formats warnings, and returns an error:

// pkg/workflow/action_sha_checker.go
func ValidateActionSHAsInLockFile(lockFilePath string, cache *ActionCache, verbose bool) error

There is already a pkg/workflow/lock_validation.go (with ValidateLockSchemaCompatibility). The naming pattern and purpose suggest ValidateActionSHAsInLockFile belongs there.

Recommendation: Move ValidateActionSHAsInLockFile to lock_validation.go. The underlying helpers (ExtractActionsFromLockFile, CheckActionSHAUpdates) stay in action_sha_checker.go.

Estimated effort: ~20 minutes (move function + update call sites)

---

4. engine_helpers.go — Single Validation Function Out of Place

File: pkg/workflow/engine_helpers.go (383 lines)

engine_helpers.go is the shared utilities hub for engine installation step generation. However, the last function is a validation predicate:

// pkg/workflow/engine_helpers.go (line 380) — candidate to move to engine_validation.go
func EngineHasValidateSecretStep(engine CodingAgentEngine, data *WorkflowData) bool {
    step := engine.GetSecretValidationStep(data)
    return len(step) > 0
}

There is an existing pkg/workflow/engine_validation.go with 8 Compiler-method validators. This 3-line function checks whether an engine produces a validation step — it is a validation predicate, not a generation helper.

Recommendation: Move EngineHasValidateSecretStep to engine_validation.go.

Estimated effort: ~10 minutes (move function + update call sites)

---

What is Well-Organized (Do Not Change)

Patterns to preserve

• Platform-specific pairs (github_cli.go / github_cli_wasm.go, git_helpers_wasm.go, docker_validation_wasm.go, etc.) — all 7 WASM stub files use correct Go build constraints. These are intentional, not duplicates.

• Update-entity helper fan-out (update_entity_helpers.go → update_issue_helpers.go / update_pull_request_helpers.go / update_discussion_helpers.go) — a good model for coordinated multi-file helpers with shared infrastructure.

• engine_helpers.go as a shared hub — GetBaseInstallationSteps, GenerateMultiSecretValidationStep, BuildDefaultSecretValidationStep, and FilterEnvForSecrets are legitimately shared across multiple engine implementations.

• Generic shared utilities — map_helpers.go (2 functions), parse_helpers.go (2 functions), validation_helpers.go (5 functions) are small, focused, and non-redundant.

• strings.go vs pkg/stringutil/ — different domains. workflow/strings.go handles workflow-specific sanitization (job names, artifact identifiers, heredoc delimiters). pkg/stringutil/ handles general string utilities (ANSI stripping, PAT classification, URL normalization). No consolidation needed.

• 59 *_validation.go files in pkg/workflow/ — the volume is large but the pattern is consistent and appropriate for this compilation system.

---

Refactoring Recommendations Summary

Priority	File	Action	Effort
High	pkg/workflow/env.go	Rename to yaml_env_helpers.go or merge into compiler_yaml.go	~15 min
Medium	pkg/workflow/model_identifier.go	Move 3 public Validate* functions to model_alias_validation.go	~30 min
Medium	pkg/workflow/action_sha_checker.go	Move ValidateActionSHAsInLockFile to lock_validation.go	~20 min
Low	pkg/workflow/engine_helpers.go	Move EngineHasValidateSecretStep to engine_validation.go	~10 min

Implementation Checklist

• Rename/merge env.go into appropriately named YAML helpers file
• Move ValidateEffortParam, ValidateTemperatureParam, ValidateKnownParams from model_identifier.go to model_alias_validation.go
• Move ValidateActionSHAsInLockFile from action_sha_checker.go to lock_validation.go
• Move EngineHasValidateSecretStep from engine_helpers.go to engine_validation.go
• Update all call sites after each move
• Verify no circular import issues introduced
• Run tests after each change

Analysis Metadata

• Total Go files analyzed: 762 (non-test, in pkg/)
• Total functions cataloged: 3,727
• WASM platform-specific pairs: 7 (intentional, not duplicates)
• Validation files in pkg/workflow/: 59
• Outlier functions found: 5 (across 4 files)
• True duplicates detected: 0
• Detection method: Naming pattern analysis + Serena LSP semantic analysis + manual code review
• Analysis date: 2026-05-07
• Workflow run: §25467930693

Generated by Semantic Function Refactoring · ● 312.8K · ◷

• expires on May 9, 2026, 12:08 AM UTC

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · ● 79.1K · ◷