🔧 Semantic Function Clustering Analysis
Automated read-only analysis of github/gh-aw — non-test Go sources under pkg/.
Overview
I clustered every top-level function and method across the non-test Go sources by name and purpose, then used Serena semantic tools to verify the strongest duplicate/outlier candidates. The headline result is a clean bill of health: the codebase is unusually well-factored. Every apparent duplicate surfaced by naming analysis resolved to a legitimate, intentional pattern rather than accidental duplication.
This issue documents the methodology, the few minor opportunities, and the evidence that the common refactoring smells are absent — so future analyses do not re-flag the same intentional patterns.
Key metrics
| Metric |
Value |
Non-test .go files analyzed (excl. testdata/, linters) |
937 |
| Top-level functions catalogued |
~5,500 |
Standalone functions duplicated by name (non-_wasm, cross-package) |
2 — both intentional delegating wrappers |
| Scattered helpers (truncate/sanitize/escape/format/...) |
0 duplicated — each defined exactly once |
| Files over 1000 lines |
9 (max 1221) — none oversized for a ~1000-file repo |
Build-tag _wasm.go variant files |
26 (correctly paired) |
What the analysis did NOT find (the good news)
Every duplicate-name candidate resolved to an intentional pattern
The naming-frequency pass flagged ~30 function/method names appearing 2+ times. Each was verified with Serena and direct reads and falls into one of three legitimate categories:
-
Build-tag platform variants (_wasm.go) — e.g. isTTY, stderrWriter, NewSpinner, RenderTable, PrintBanner, findGitRoot, RunGH*. These are go:build wasm vs !wasm implementations of the same symbol. Not duplication — required for the WASM/native split. (26 such files, correctly paired.)
-
Intentional thin delegating wrappers across package boundaries: compileSchema in pkg/workflow/schema_utils.go and pkg/parser/schema_compiler.go both delegate to parser.CompileSchema; GetVersion in pkg/cli/version.go delegates to workflow.GetVersion.
-
Interface implementations across types — method names like Render, RenderMCPConfig, GetInstallationSteps, GetExecutionSteps, GetSupportedEnvVarKeys appear 8–9 times because ~9 agentic-engine types implement a shared interface. Idiomatic Go polymorphism.
Scattered helpers: patterns classically duplicated across files (truncate*, sanitize*, escape*, formatBytes, pluralize, indent*, contains*) were each found defined exactly once. Utilities are already centralized in dedicated packages (stringutil, sliceutil, setutil, jsonutil, typeutil, fileutil, semverutil, ...).
Minor opportunities (low priority, optional)
These are the only genuine candidates found. Both are borderline — listed for completeness, not urgency.
1. Parameterize the writeJSONStringMapSection / ...SectionRaw pair
- File:
pkg/workflow/mcp_renderer_section_helpers.go:53 and :71
- Observation:
writeJSONStringMapSection and writeJSONStringMapSectionRaw are identical except for the single line that calls writeJSONStringMapEntries vs writeJSONStringMapEntriesRaw (the open-brace / entries / close-brace + trailing-comma skeleton is repeated verbatim).
- Suggestion: extract the shared skeleton and pass the entries-writer (or a
raw bool) as a parameter. Removes ~8 duplicated lines.
- Caveat: the
Raw split is deliberate and thoroughly documented (shell-placeholder un-escaping for unquoted heredocs). Any refactor must preserve that behavior and its comments. Impact: cosmetic.
2. Optional cohesion tidy in awf_helpers.go
- File:
pkg/workflow/awf_helpers.go (1075 lines)
- Observation: the file is cohesive (all AWF command construction + ARC-DinD path rewriting), but it also holds a cluster of ~10 version-capability predicates:
awfVersionAtLeast, awfSupportsExcludeEnv, awfSupportsCliProxy, awfSupportsAllowHostPorts, awfSupportsDockerHostPathPrefix, awfSupportsTokenSteering, awfSupportsChrootConfig, awfSupportsContainerRuntime, ...
- Suggestion: if the file grows further, these
awfSupports* feature-gates could move to a dedicated awf_capabilities.go. Not needed today. Impact: organizational nicety only.
Detected clusters (all well-organized)
Representative clusters and their verdicts
create* safe-output constructors — one file per entity (create_issue, create_pr, create_discussion, ...). Textbook one-file-per-feature.write* YAML/JSON/TOML emitters (writeJSONStringMap*, writeTOMLInlineStringMapSection, writeYAMLEnv, ...) — colocated by concern.sanitize* (16 funcs) — each distinct purpose (path, branch, JSON, shell, log, ...), no overlap.escape* (6 funcs) — distinct target grammars (YAML single/double-quoted, GraphQL, shell).parse* / Parse* — grouped in pkg/parser by input type.- Engine interface methods — implemented per engine type (Copilot, Claude, Codex, ...).
Recommended next actions
Analysis metadata
- Method: naming-pattern frequency clustering + Serena (
activate_project, get_symbols_overview) semantic verification of candidates.
- Scope:
pkg/ non-test .go files; testdata/ fixtures and analyzer test-inputs excluded.
- Verdict: Well-factored codebase. No significant refactoring debt in function organization or duplication.
References:
Generated by 🔧 Semantic Function Refactoring · 283.2 AIC · ⌖ 14.9 AIC · ⊞ 9.1K · ◷
🔧 Semantic Function Clustering Analysis
Automated read-only analysis of
github/gh-aw— non-test Go sources underpkg/.Overview
I clustered every top-level function and method across the non-test Go sources by name and purpose, then used Serena semantic tools to verify the strongest duplicate/outlier candidates. The headline result is a clean bill of health: the codebase is unusually well-factored. Every apparent duplicate surfaced by naming analysis resolved to a legitimate, intentional pattern rather than accidental duplication.
This issue documents the methodology, the few minor opportunities, and the evidence that the common refactoring smells are absent — so future analyses do not re-flag the same intentional patterns.
Key metrics
.gofiles analyzed (excl.testdata/, linters)_wasm, cross-package)_wasm.govariant filesWhat the analysis did NOT find (the good news)
Every duplicate-name candidate resolved to an intentional pattern
The naming-frequency pass flagged ~30 function/method names appearing 2+ times. Each was verified with Serena and direct reads and falls into one of three legitimate categories:
Build-tag platform variants (
_wasm.go) — e.g.isTTY,stderrWriter,NewSpinner,RenderTable,PrintBanner,findGitRoot,RunGH*. These arego:build wasmvs!wasmimplementations of the same symbol. Not duplication — required for the WASM/native split. (26 such files, correctly paired.)Intentional thin delegating wrappers across package boundaries:
compileSchemainpkg/workflow/schema_utils.goandpkg/parser/schema_compiler.goboth delegate toparser.CompileSchema;GetVersioninpkg/cli/version.godelegates toworkflow.GetVersion.Interface implementations across types — method names like
Render,RenderMCPConfig,GetInstallationSteps,GetExecutionSteps,GetSupportedEnvVarKeysappear 8–9 times because ~9 agentic-engine types implement a shared interface. Idiomatic Go polymorphism.Scattered helpers: patterns classically duplicated across files (
truncate*,sanitize*,escape*,formatBytes,pluralize,indent*,contains*) were each found defined exactly once. Utilities are already centralized in dedicated packages (stringutil,sliceutil,setutil,jsonutil,typeutil,fileutil,semverutil, ...).Minor opportunities (low priority, optional)
These are the only genuine candidates found. Both are borderline — listed for completeness, not urgency.
1. Parameterize the
writeJSONStringMapSection/...SectionRawpairpkg/workflow/mcp_renderer_section_helpers.go:53and:71writeJSONStringMapSectionandwriteJSONStringMapSectionRaware identical except for the single line that callswriteJSONStringMapEntriesvswriteJSONStringMapEntriesRaw(the open-brace / entries / close-brace + trailing-comma skeleton is repeated verbatim).raw bool) as a parameter. Removes ~8 duplicated lines.Rawsplit is deliberate and thoroughly documented (shell-placeholder un-escaping for unquoted heredocs). Any refactor must preserve that behavior and its comments. Impact: cosmetic.2. Optional cohesion tidy in
awf_helpers.gopkg/workflow/awf_helpers.go(1075 lines)awfVersionAtLeast,awfSupportsExcludeEnv,awfSupportsCliProxy,awfSupportsAllowHostPorts,awfSupportsDockerHostPathPrefix,awfSupportsTokenSteering,awfSupportsChrootConfig,awfSupportsContainerRuntime, ...awfSupports*feature-gates could move to a dedicatedawf_capabilities.go. Not needed today. Impact: organizational nicety only.Detected clusters (all well-organized)
Representative clusters and their verdicts
create*safe-output constructors — one file per entity (create_issue,create_pr,create_discussion, ...). Textbook one-file-per-feature.write*YAML/JSON/TOML emitters (writeJSONStringMap*,writeTOMLInlineStringMapSection,writeYAMLEnv, ...) — colocated by concern.sanitize*(16 funcs) — each distinct purpose (path, branch, JSON, shell, log, ...), no overlap.escape*(6 funcs) — distinct target grammars (YAML single/double-quoted, GraphQL, shell).parse*/Parse*— grouped inpkg/parserby input type.Recommended next actions
writeJSONStringMapSection/...Raw— preserve the documented shell-escaping behavior._wasm.govariants, cross-package delegating wrappers, and shared-interface methods as intentional, not duplication.Analysis metadata
activate_project,get_symbols_overview) semantic verification of candidates.pkg/non-test.gofiles;testdata/fixtures and analyzer test-inputs excluded.References: