[refactor] Semantic function clustering: outliers and scattered helpers

[github-actions]

Overview

Semantic analysis of 726 non-test Go source files across pkg/workflow (352 files), pkg/cli (263 files), pkg/parser, and smaller utility packages. The codebase is well-structured overall — this report focuses on the three actionable issues found.

---

Issue 1 — Outlier function: computeIntegrityCacheKey in cache.go

File: pkg/workflow/cache.go (line 80)
Recommendation priority: High

computeIntegrityCacheKey belongs semantically in cache_integrity.go. Every call it makes is to a function defined in that file:

// cache.go — calls three functions, all from cache_integrity.go
func computeIntegrityCacheKey(cache CacheMemoryEntry, githubConfig *GitHubToolConfig) string {
    integrityLevel := cacheIntegrityLevel(githubConfig)         // cache_integrity.go
    policyHash     := computePolicyHash(githubConfig)           // cache_integrity.go
    ...
    return generateIntegrityAwareCacheKey(...)                   // cache_integrity.go
}

cache_integrity.go already owns: computePolicyHash, buildCanonicalPolicy, cacheIntegrityLevel, generateIntegrityAwareCacheKey. This function is the missing piece of that chain.

Recommendation: Move computeIntegrityCacheKey from cache.go to cache_integrity.go.

---

Issue 2 — Npm/Node step-generation split across engine_helpers.go and nodejs.go

Files: pkg/workflow/engine_helpers.go, pkg/workflow/nodejs.go
Recommendation priority: Medium

nodejs.go is the canonical home for Node.js/npm step generation:

Function	Current file
GenerateNodeJsSetupStep	nodejs.go ✓
GenerateNpmInstallSteps	nodejs.go ✓
GenerateNpmInstallStepsWithScope	nodejs.go ✓
BuildStandardNpmEngineInstallSteps	engine_helpers.go ← outlier
BuildNpmEngineInstallStepsWithAWF	engine_helpers.go ← outlier
GetNpmBinPathSetup	engine_helpers.go ← outlier

engine_helpers.go mixes engine orchestration, secret validation, YAML formatting, environment filtering, and npm step generation. The three npm-specific functions there are outliers; they belong in nodejs.go alongside the rest of the npm step generation code.

Recommendation: Move BuildStandardNpmEngineInstallSteps, BuildNpmEngineInstallStepsWithAWF, and GetNpmBinPathSetup from engine_helpers.go to nodejs.go.

---

Issue 3 — Complementary percentage helpers in separate audit files

Files: pkg/cli/audit_cross_run_render.go, pkg/cli/audit_diff.go
Recommendation priority: Low

Two small math/format helpers serve the same conceptual pair (compute → format percentage) but are isolated in different files:

// audit_cross_run_render.go
func safePercent(part, total int) float64 {
    if total == 0 { return 0 }
    return float64(part) / float64(total) * 100
}

// audit_diff.go
func formatPercent(pct float64) string {
    return fmt.Sprintf("%.0f%%", pct)
}

Neither file currently uses the other's function, resulting in repeated inline percent formatting across the audit rendering code. Extracting both into a shared audit_math_helpers.go (or similar) would allow the common pattern formatPercent(safePercent(a, b)) to be used consistently.

Recommendation: Extract safePercent and formatPercent into a shared pkg/cli/audit_math_helpers.go.

---

What was verified as well-organized (no action needed)

• strict_mode_*_validation.go — clean domain-based validation split ✓
• update_*_helpers.go / close_entity_helpers.go — clean entity hierarchy with shared base types ✓
• safe_outputs_* family — well-decomposed by concern ✓
• codemod_*.go — one codemod per file ✓
• audit_report_render_*.go — clean rendering domain split ✓
• compile_*.go (cli) — well-decomposed orchestration ✓
• getEffective*Token family in github_token.go ✓
• _wasm.go platform splits — all carry correct //go:build js || wasm constraints, not duplicates ✓
• aggregateLogFiles[T LogAnalysis] generic abstraction — already in log_aggregation.go ✓

---

Analysis Metadata

Metric	Value
Total Go files analyzed	726
Packages examined	workflow, cli, parser, stringutil, agentdrain
Outlier functions identified	4 (computeIntegrityCacheKey + 3 npm funcs in engine_helpers.go)
Near-duplicate pairs	1 (safePercent / formatPercent)
Detection method	Serena LSP semantic analysis + naming-pattern clustering
Workflow run	§24887527394

Implementation Checklist

• Move computeIntegrityCacheKey → cache_integrity.go
• Move BuildStandardNpmEngineInstallSteps, BuildNpmEngineInstallStepsWithAWF, GetNpmBinPathSetup → nodejs.go
• Consider extracting safePercent + formatPercent → audit_math_helpers.go

Generated by Semantic Function Refactoring · ● 221.9K · ◷

• expires on Apr 26, 2026, 11:46 AM UTC