[refactor] Semantic Function Clustering Analysis - Code Organization and Duplication Issues

[github-actions]

Executive Summary

Analyzed 505 Go source files across the repository, with primary focus on the 261 files in pkg/workflow. Using Serena's semantic code analysis tools, I identified several critical code organization issues, duplicate implementations, and scattered helper functions that should be refactored.

Key Findings:

• 3 critical function misplacements (functions in wrong files)
• 2 duplicate implementations of YAML conversion logic
• 23 safe outputs config files that could be consolidated
• Inconsistent naming conventions between _helpers and _utils files

---

Critical Issues

1. Functions in Wrong Files (Outliers)

These functions are clearly misplaced and should be moved to appropriate files:

Issue #1: Safe Outputs Environment Function in Notification File

Problem: buildSafeOutputJobsEnvVars() is located in notify_comment.go but has nothing to do with notification comments.

• Current Location: pkg/workflow/notify_comment.go:429-484
• Function Purpose: Builds environment variables for safe output jobs
• Should Be In: pkg/workflow/safe_outputs_env.go (which already contains buildSafeOutputJobEnvVars() and buildWorkflowMetadataEnvVars())

Code Reference:

// notify_comment.go - WRONG FILE
func buildSafeOutputJobsEnvVars(jobNames []string) (string, []string) {
    // Builds env vars for safe outputs - belongs in safe_outputs_env.go
}

Impact: High - Breaks the "one file per feature" principle, makes code harder to find and maintain.

Recommendation: Move to pkg/workflow/safe_outputs_env.go

Issue #2: Build Function in Validation File

Problem: buildAgenticEngineSecretsMap() is located in imported_steps_validation.go but it's a build/initialization function, not validation logic.

• Current Location: pkg/workflow/imported_steps_validation.go:18-47
• Function Purpose: Builds a map of agentic engine secrets
• Should Be In: pkg/workflow/agentic_engine.go or a new pkg/workflow/agentic_engine_secrets.go

Related Functions Also Misplaced:

• isAgenticEngineSecret()
• getAgenticEngineSecrets()
• isCustomAgenticEngine()

Impact: Medium-High - Validation files should only contain validation logic.

Recommendation: Move secret-related functions to pkg/workflow/agentic_engine.go or create pkg/workflow/agentic_engine_secrets.go

Issue #3: YAML Conversion in Validation File

Problem: convertStepToYAML() standalone function in imported_steps_validation.go

• Current Location: pkg/workflow/imported_steps_validation.go:246-277
• Function Purpose: Converts step maps to YAML format
• Should Be In: pkg/workflow/compiler_yaml_helpers.go (which already has a method (*Compiler).convertStepToYAML())

Impact: Medium - See duplicate implementation issue below.

---

2. Duplicate Implementations

Duplicate YAML Conversion Functions

Problem: TWO different implementations of step-to-YAML conversion exist:

Implementation #1: pkg/workflow/imported_steps_validation.go:246-277

func convertStepToYAML(step map[string]any) (string, error) {
    var builder strings.Builder
    // Custom string-building implementation
    // Simple recursive approach
}

Implementation #2: pkg/workflow/agentic_engine.go:488-518

func ConvertStepToYAML(stepMap map[string]any) (string, error) {
    orderedStep := OrderMapFields(stepMap, constants.PriorityStepFields)
    yamlBytes, err := yaml.MarshalWithOptions(...)
    // Uses proper YAML marshaling with field ordering
    // Post-processes for GitHub Actions format
}
```

**Comparison:**
- Implementation #1: Simple string building, no field ordering
- Implementation #2: Proper YAML marshaling with field ordering, comment handling, indentation
- Implementation #2 is more robust and feature-complete

**Current Usage:**
- `compiler_yaml_helpers.go` has `(*Compiler).convertStepToYAML()` that delegates to `ConvertStepToYAML()` from `agentic_engine.go`
- `imported_steps_validation.go` uses its own local implementation

**Impact:** High - Code duplication, inconsistent YAML output, maintenance burden

**Recommendation:**
1. Remove the implementation from `imported_steps_validation.go`
2. Use the exported `ConvertStepToYAML()` from `agentic_engine.go` everywhere
3. Consider moving `ConvertStepToYAML()` to `compiler_yaml_helpers.go` for better organization

</details>

---

### File Organization Issues

#### 3. Excessive Safe Outputs Configuration Files

**Current State:** 23 files related to safe outputs, with 5 specifically for configuration:

**Compiler Integration (9 files):**
- `compiler_safe_outputs.go`
- `compiler_safe_outputs_config.go`
- `compiler_safe_outputs_core.go`
- `compiler_safe_outputs_discussions.go`
- `compiler_safe_outputs_env.go`
- `compiler_safe_outputs_job.go`
- `compiler_safe_outputs_shared.go`
- `compiler_safe_outputs_specialized.go`
- `compiler_safe_outputs_steps.go`
- `compiler_safe_output_jobs.go`

**Standalone Safe Outputs (13 files):**
- `safe_outputs.go`
- `safe_outputs_app.go`
- `safe_outputs_config.go` ← Core extraction
- `safe_outputs_config_helpers.go` ← Helper functions
- `safe_outputs_config_generation.go` ← Generation logic
- `safe_outputs_config_generation_helpers.go` ← Generation helpers
- `safe_outputs_config_helpers_reflection.go` ← Reflection utilities
- `safe_outputs_config_messages.go` ← Message-specific config
- `safe_outputs_domains_validation.go`
- `safe_outputs_env.go`
- `safe_outputs_jobs.go`
- `safe_outputs_permissions.go`
- `safe_outputs_steps.go`
- `safe_outputs_target_validation.go`
- `safe_output_validation_config.go`

**Analysis:**
- **Config files (5):** Could potentially be consolidated into 2-3 files
- **Validation files (3):** Well-organized, keep separate
- **Helper files (3):** Mix of regular helpers, generation helpers, and reflection helpers

**Recommendation:**

Consider consolidating the 5 config files:
```
Current:
- safe_outputs_config.go (extraction)
- safe_outputs_config_helpers.go
- safe_outputs_config_generation.go
- safe_outputs_config_generation_helpers.go
- safe_outputs_config_helpers_reflection.go

Proposed:
- safe_outputs_config.go (core extraction + helpers)
- safe_outputs_config_generation.go (generation + generation helpers)
- safe_outputs_config_reflection.go (reflection utilities)
```

**Impact:** Medium - Would reduce file count and improve maintainability, but requires careful refactoring.

---

#### 4. Inconsistent Helper File Naming

**Current Mix:**
- Files ending with `_helpers.go`: 9 files
- Files ending with `_utils.go`: 1 file (`mcp_config_utils.go`)

**Files with `_helpers`:**
```
close_entity_helpers.go
compiler_test_helpers.go
compiler_yaml_helpers.go
config_helpers.go
engine_helpers.go
error_helpers.go
git_helpers.go
map_helpers.go
safe_outputs_config_generation_helpers.go
safe_outputs_config_helpers.go
safe_outputs_config_helpers_reflection.go
update_entity_helpers.go
validation_helpers.go
```

**Files with `_utils`:**
```
mcp_config_utils.go

Recommendation:

• Option A: Standardize on _helpers.go for all helper files (rename mcp_config_utils.go → mcp_config_helpers.go)
• Option B: Use _utils.go for standalone utilities and _helpers.go for type-specific helpers

Preferred: Option A - Consistency is more important than the subtle distinction.

Impact: Low - Mostly cosmetic, but improves codebase consistency.

---

File Organization Patterns (Well-Organized)

These areas show good organization and should serve as examples:

✅ CRUD Operations (21 files)

Excellent organization with clear file-per-operation pattern:

• create_*.go - Creation operations (8 files)
• update_*.go - Update operations (6 files)
• add_*.go - Add operations (3 files)
• assign_*.go - Assignment operations (3 files)
• unassign_from_user.go

✅ Validation Files (35 files)

Well-organized with specific validation purposes:

• Domain-specific validation (docker, npm, pip, etc.)
• Feature validation (firewall, permissions, secrets)
• Component validation (agents, engines, tools)

✅ Engine Files (10+ files)

Consistent pattern across engine types:

• agentic_engine.go - Base interfaces and utilities
• claude_engine.go, codex_engine.go, copilot_engine.go - Specific implementations
• *_logs.go - Log parsing for each engine
• *_mcp.go - MCP configuration for each engine

✅ Compiler Files (25 files)

Logical grouping with clear prefixes:

• compiler_*.go - Core compiler functionality
• compiler_orchestrator_*.go - Orchestration logic
• compiler_yaml_*.go - YAML generation
• compiler_safe_outputs_*.go - Safe outputs integration

---

Recommendations Summary

Priority 1: Critical Fixes (Estimated: 2-4 hours)

1. Move buildSafeOutputJobsEnvVars() from notify_comment.go to safe_outputs_env.go

   • File: pkg/workflow/notify_comment.go:429-484
   • Update any imports/references
   • Benefit: Correct file organization

2. Remove duplicate convertStepToYAML() from imported_steps_validation.go

   • File: pkg/workflow/imported_steps_validation.go:246-277
   • Replace usage with ConvertStepToYAML() from agentic_engine.go
   • Benefit: Eliminate duplication, consistent YAML output

3. Move secret functions from imported_steps_validation.go to agentic_engine.go

   • Functions: buildAgenticEngineSecretsMap(), isAgenticEngineSecret(), etc.
   • Consider creating pkg/workflow/agentic_engine_secrets.go if the file gets too large
   • Benefit: Validation file only contains validation logic

Priority 2: Medium Impact (Estimated: 3-5 hours)

4. Standardize helper file naming

   • Rename mcp_config_utils.go → mcp_config_helpers.go
   • Update imports
   • Benefit: Consistent naming across codebase

5. Consider consolidating safe_outputs_config_ files*

   • Merge 5 config files into 2-3 files
   • Careful refactoring to maintain functionality
   • Benefit: Reduced file count, clearer organization

Priority 3: Long-term Improvements

6. Document architectural patterns

   • Create ARCHITECTURE.md documenting:
     • File naming conventions (_helpers, _validation, etc.)
     • Function naming patterns (build*, parse*, validate*, generate*)
     • File organization principles (one file per feature)
   • Benefit: Prevents future organizational issues

7. Consider moving ConvertStepToYAML() to yaml helpers

   • Current: pkg/workflow/agentic_engine.go
   • Proposed: pkg/workflow/compiler_yaml_helpers.go
   • Rationale: Better semantic location for YAML conversion utilities
   • Benefit: Improved discoverability

---

Analysis Metadata

• Repository: github/gh-aw
• Total Go Files Analyzed: 505 files
• Primary Focus: pkg/workflow (261 files)
• Analysis Method: Serena semantic code analysis + manual review
• Key Findings:
  • 3 critical function misplacements
  • 2 duplicate implementations
  • 23 safe outputs files (potential consolidation opportunity)
  • Inconsistent helper file naming (9 _helpers vs 1 _utils)
• Well-Organized Areas: CRUD operations (21), validation (35), engines (10+), compiler (25)
• Analysis Date: 2026-02-14

---

Implementation Checklist

• Review findings and prioritize refactoring tasks
• Priority 1: Move buildSafeOutputJobsEnvVars() to correct file
• Priority 1: Remove duplicate convertStepToYAML() implementation
• Priority 1: Move secret functions to agentic_engine.go
• Verify all changes with tests
• Priority 2: Standardize helper file naming
• Priority 2: Evaluate safe outputs config consolidation
• Priority 3: Create architecture documentation
• Priority 3: Consider moving ConvertStepToYAML() to yaml helpers

References:

• §22021139472

Generated by Semantic Function Refactoring

• expires on Feb 16, 2026, 5:15 PM UTC

[github-actions]

Closing this issue as a new semantic function refactoring analysis is being performed. A fresh analysis will identify current code organization opportunities and potential duplicates.