[refactor] Function naming patterns and refactoring opportunities in pkg/workflow

[github-actions]

Analysis Summary

Analyzed 260+ files in pkg/workflow directory using Serena's semantic tools to identify function naming patterns and potential refactoring opportunities.

Common Function Naming Patterns

Primary Patterns by Prefix

1. build* (High frequency, ~50+ occurrences)

   • Building workflow jobs: buildMainJob, buildActivationJob, buildSafeOutputJob
   • Building steps: buildCustomActionStep, buildGitHubScriptStep, buildCheckoutRepository
   • Building configurations: buildMCPGatewayConfig, buildConcurrencyGroupKeys
   • Building environment variables: buildSafeOutputJobEnvVars, buildWorkflowMetadataEnvVars
   • Building specialized components: buildCopilotAssignmentStep, buildAgentOutputDownloadSteps

2. parse* (High frequency, ~40+ occurrences)

   • Parsing workflow configs: parseIssuesConfig, parsePullRequestsConfig, parseCommentsConfig
   • Parsing tool configs: parseUpdateIssuesConfig, parseAssignToAgentConfig
   • Parsing cache configs: parseCacheMemoryEntry, parseMessagesConfig
   • Parsing package dependencies: parseNpmPackage, parsePipPackage, parseGoPackage

3. generate* (High frequency, ~40+ occurrences)

   • Generating workflow YAML: generateWorkflowHeader, generateWorkflowBody, generateYAML
   • Generating steps: generatePostSteps, generateCacheSteps, generateCacheMemorySteps
   • Generating configs: generateSafeOutputsConfig, generateDependabotConfig
   • Generating metadata: generateDefaultCacheKey, generatePlaceholderSubstitutionStep

4. validate* (Medium frequency, ~30+ occurrences)

   • Validating agent files: validateAgentFile, validateHTTPTransportSupport
   • Validating runtime: validateNoRuntimeMixing, validateRuntimeModeRecursive
   • Validating scripts: validateNoExecSync, validateNoGitHubScriptGlobals
   • Validating filters: ValidateEventFilters, validateFilterExclusivity

5. extract* (Medium frequency, ~25+ occurrences)

   • Extracting from frontmatter: extractFeatures, extractDescription, extractTrackerID
   • Extracting configurations: extractSafeOutputsConfig, extractCacheMemoryConfig
   • Extracting YAML sections: extractYAMLSections, extractAdditionalConfigurations
   • Extracting metadata: extractBaseRepo, extractGoPackages

6. render* (Medium frequency, ~20+ occurrences)

   • Rendering MCP configs: renderSafeOutputsMCPConfig, renderAgenticWorkflowsMCPConfig
   • Rendering specific servers: RenderGitHubMCP, RenderPlaywrightMCP, RenderSerenaMCP
   • Rendering formats: renderSafeOutputsTOML, renderAgenticWorkflowsTOML

Secondary Patterns

7. has* / is* (Boolean checks)

   • HasSafeOutputsEnabled, HasMCPServers, hasCopilotAssignee
   • isActivationJobNeeded, isAgenticEngineSecret, isSandboxDisabled

8. get* (Getters)

   • GetEnabledSafeOutputToolNames, getMCPConfig, getAgenticEngineSecrets
   • GetGlobalEngineRegistry, getSharedActionResolver

9. compute* (Calculations)

   • computePermissionsForSafeOutputs, computeNormalizedPaths

10. convert* (Transformations)

    • convertStepToYAML, convertPermissionsToAppTokenFields

Files Organized by Purpose

Compiler Core (prefix: compiler_*)

• Orchestration: compiler_orchestrator.go, compiler_orchestrator_workflow.go, compiler_orchestrator_engine.go
• Job Building: compiler_jobs.go, compiler_activation_jobs.go, compiler_safe_output_jobs.go
• YAML Generation: compiler_yaml.go, compiler_yaml_helpers.go, compiler_yaml_main_job.go
• Safe Outputs: compiler_safe_outputs_core.go, compiler_safe_outputs_steps.go, compiler_safe_outputs_config.go
• Validation: compiler_filters_validation.go
• Types: compiler_types.go

MCP Configuration (prefix: mcp_*)

• Core Config: mcp_config_builtin.go, mcp_config_custom.go, mcp_config_types.go, mcp_config_utils.go
• Server Configs: mcp_github_config.go, mcp_playwright_config.go, mcp_serena_config.go
• Rendering: mcp_renderer.go, mcp_config_playwright_renderer.go, mcp_config_serena_renderer.go
• Gateway: mcp_gateway_config.go, mcp_gateway_constants.go
• Detection: mcp_detection.go
• Environment: mcp_environment.go
• Setup: mcp_setup_generator.go

Safe Outputs (prefix: safe_outputs_*)

• Configuration: safe_outputs_config.go, safe_outputs_config_helpers.go, safe_outputs_config_generation.go
• Job/Step Building: safe_outputs_jobs.go, safe_outputs_steps.go
• Environment: safe_outputs_env.go
• Permissions: safe_outputs_permissions.go
• GitHub App: safe_outputs_app.go
• Messages: safe_outputs_config_messages.go
• Validation: safe_outputs_domains_validation.go, safe_outputs_target_validation.go

Create Operations (prefix: create_*)

• Issues: create_issue.go
• Pull Requests: create_pull_request.go
• Discussions: create_discussion.go
• Code Scanning: create_code_scanning_alert.go
• Projects: create_project.go, create_project_status_update.go
• Comments: create_pr_review_comment.go
• Sessions: create_agent_session.go

Update Operations (prefix: update_*)

• Issues: update_issue.go
• Pull Requests: update_pull_request.go
• Discussions: update_discussion.go
• Releases: update_release.go
• Projects: update_project.go
• Helpers: update_entity_helpers.go

Bundler (prefix: bundler_*)

• Core: bundler.go
• Validation: bundler_runtime_validation.go, bundler_script_validation.go, bundler_safety_validation.go
• Utilities: bundler_file_mode.go

Agentic Engines

• Core: agentic_engine.go
• Specific Engines: claude_engine.go, codex_logs.go, claude_logs.go
• MCP Integration: claude_mcp.go, codex_mcp.go

Add Operations (prefix: add_*)

• add_comment.go, add_labels.go, add_reviewer.go

Assign Operations (prefix: assign_*)

• assign_to_agent.go, assign_to_user.go, assign_milestone.go

Utilities

• Actions: action_resolver.go, action_cache.go, action_pins.go, action_mode.go
• Artifacts: artifacts.go, artifact_manager.go
• Cache: cache.go
• Shell: shell.go
• Concurrency: concurrency.go
• Arguments: args.go
• Dependencies: dependabot.go

Potential Refactoring Opportunities

1. Functions in Wrong Files (Outliers)

notify_comment.go

Issue: Contains buildSafeOutputJobsEnvVars() function that seems related to safe outputs environment variables, not notification comments.
Suggestion: Move to safe_outputs_env.go which already contains similar functions like buildSafeOutputJobEnvVars(), buildWorkflowMetadataEnvVars().

imported_steps_validation.go

Issue: Contains buildAgenticEngineSecretsMap() which is a build/initialization function, not validation.
Suggestion: Move to agentic_engine.go or create a new agentic_engine_secrets.go file. Keep only validation logic in this file.

imported_steps_validation.go

Issue: Contains convertStepToYAML() which is a conversion/formatting utility, not validation.
Suggestion: Move to compiler_yaml_helpers.go which already contains similar YAML utilities.

frontmatter_extraction_metadata.go

Issue: Contains many extract* functions but also buildSourceURL() which is a build function.
Suggestion: Rename file to frontmatter_metadata.go (shorter, clearer) or move buildSourceURL() to a URL utilities file.

2. Potential File Consolidation

Safe Outputs Config Files (5 files)

Current: safe_outputs_config.go, safe_outputs_config_helpers.go, safe_outputs_config_generation.go, safe_outputs_config_generation_helpers.go, safe_outputs_config_messages.go
Suggestion: Consider consolidating into 2-3 files:

• safe_outputs_config.go (core extraction)
• safe_outputs_config_generation.go (generation logic + helpers)
• safe_outputs_config_messages.go (keep separate as domain-specific)

MCP Config Renderers

Current: Multiple renderer files spread across mcp_config_*.go and mcp_renderer.go
Suggestion: Consider organizing by:

• mcp_renderer.go (core rendering logic)
• mcp_renderers_servers.go (server-specific renderers: GitHub, Playwright, Serena)
• mcp_renderers_builtin.go (builtin renderers: safe outputs, agentic workflows)

3. Inconsistent Naming Patterns

Compiler Methods Consistency

Some files use (*Compiler).buildXXX extensively while others mix build, parse, and extract methods.
Suggestion: Establish clear conventions:

• parse* for reading/parsing user input → struct
• extract* for pulling data from existing structures
• build* for constructing workflow components (jobs, steps, configs)
• generate* for creating output (YAML, strings, files)
• validate* for checking constraints/rules

Helper File Naming

Current: Mix of *_helpers.go, *_utils.go, *_generation_helpers.go
Suggestion: Standardize on either:

• *_helpers.go for all helper files, OR
• *_utils.go for standalone utilities, *_helpers.go for type-specific helpers

4. Large Multi-Purpose Files

compiler_types.go (850+ lines)

Contains: Type definitions, constructor functions, compiler methods, option functions
Suggestion: Split into:

• compiler_types.go (type definitions only)
• compiler_options.go (option functions: WithVerbose, WithEngineOverride, etc.)
• compiler_new.go or keep constructors in compiler_types.go

agentic_engine.go (1000+ lines estimated)

Contains: Interfaces, structs, registry, conversion utilities, validation step generation
Suggestion: Split into:

• agentic_engine_interfaces.go (interfaces)
• agentic_engine_registry.go (registry implementation)
• agentic_engine.go (base engine implementation)
• agentic_engine_utils.go (utilities)

5. Missing Abstraction Opportunities

Step Building Pattern

Many files have build*Step() functions with similar patterns (creating steps with conditions, environment variables, etc.)
Suggestion: Create a step_builder.go with common step building utilities to reduce duplication.

Config Parsing Pattern

Many parse*Config() methods follow similar patterns (extracting maps, validating fields, building structs)
Suggestion: Create generic config parsing utilities in a shared location to reduce boilerplate.

Recommendations

High Priority

1. Move misplaced functions to appropriate files (especially buildSafeOutputJobsEnvVars, convertStepToYAML)
2. Establish and document naming conventions for functions
3. Split overly large files (compiler_types.go, agentic_engine.go)

Medium Priority

4. Consolidate helper files with consistent naming
5. Create shared utilities for common patterns (step building, config parsing)
6. Consider consolidating safe_outputs_config_* files

Low Priority

7. Reorganize MCP renderer files for better clarity
8. Document architectural patterns and file organization principles

Notes

• Analysis performed using Serena's semantic tools on a representative sample of files
• Focused on function naming patterns rather than implementation details
• All suggested refactorings should preserve existing functionality
• Consider creating a coding standards document for pkg/workflow

Generated by Semantic Function Refactoring

• expires on Feb 16, 2026, 7:42 AM UTC

[github-actions]

Closing this issue as a new semantic function refactoring analysis is being performed. The new analysis will provide updated findings based on the current codebase state.