[refactor] Semantic Function Clustering Analysis — Outliers, Near-Duplicates, and Scattered Helpers

[github-actions]

🔧 Semantic Function Clustering Analysis

Analysis of repository: github/gh-aw-mcpg — §29703870629

Executive Summary

Analysis of 158 Go source files (excluding test files) across the internal/ directory cataloged 956 functions. The codebase is overall well-organized with clear package boundaries, but four categories of refactoring opportunities were identified: outlier functions that don't belong in their current files, near-duplicate extraction patterns, redundant filesystem-write scaffolding, and scattered typed-argument-decoding helpers.

No severe disorganization was found — findings are moderate-impact improvements targeting code centralization and cleaner separation of concerns.

Identified Issues

1. Outlier Functions (Functions in Wrong Files)

GenerateRandomAgentID in internal/auth/header.go

• Function: GenerateRandomAgentID() (string, error)
• Issue: All other functions in this file parse or validate auth headers. Random ID generation is an entropy/credential utility concern.
• Recommendation: Move to internal/util/random.go (already has random utilities) or a dedicated internal/auth/id.go.

parseServerIDFromToolName in internal/middleware/jqschema.go

• Function: parseServerIDFromToolName(toolName string) string
• Issue: The file handles jq filtering, schema processing, and payload persistence. Tool-name parsing is a generic naming helper unrelated to these concerns.
• Recommendation: Extract to a shared tool-name utility near internal/server/ tool registry concerns.

randomSerial in internal/proxy/tls.go

• Function: randomSerial() *big.Int
• Issue: Crypto-random primitive embedded in proxy-specific TLS file.
• Recommendation: Consolidate with similar crypto-random helpers if they exist, or document that it's intentionally local to certificate assembly.

---

2. Near-Duplicate Functions

Session ID extraction duplication

• Occurrence 1: internal/auth/header.go:ExtractSessionIDFromHeaders(xAgentID, authHeader string) string
• Occurrence 2: internal/server/session.go:extractSessionIDFromRequest(r *http.Request) string
• Similarity: Both implement the same extraction logic from X-Agent-ID/Authorization; the server wrapper adds only HTTP request field access.
• Recommendation: Keep one canonical extractor in internal/auth/ and make the server-layer wrapper clearly minimal (a single-line delegating call).

Integer env-var parsing duplication

• Occurrence 1: internal/envutil/envutil.go:GetEnvInt(...) (generic)
• Occurrence 2: internal/config/gateway_env.go:parseAndValidateIntEnv(envKey string, validate func(int) *ValidationError) (policy-aware)
• Similarity: Both parse integer environment variables and handle validation/default behavior.
• Recommendation: Formalize layering: envutil provides generic ParseEnvInt/ValidateEnvInt helpers; gateway_env provides thin policy wrappers only.

Typed argument-map extraction duplication

• Occurrence 1: internal/proxy/router.go:extractOwnerRepoNumber(...)
• Occurrence 2: internal/githubhttp/collaborator.go:ParseCollaboratorPermissionArgs(...)
• Similarity: Both extract owner/repo/username fields from map[string]interface{} tool arguments with the same util.GetStringFromMap pattern and similar error shaping.
• Recommendation: Create a small typed arg-decoding helper in internal/util/ or internal/githubhttp/ for common owner/repo/number/username patterns.

JSON-backed state logger scaffolding duplication

• Occurrence 1: internal/logger/tools_logger.go:writeToFile
• Occurrence 2: internal/logger/observed_url_domains_logger.go:writeToFile
• Similarity: Both persist in-memory state to JSON files using identical init/fallback/write lifecycle patterns.
• Recommendation: Extract a shared statefulJSONLogger base helper within internal/logger/ to remove repeated scaffolding.

---

3. Scattered Filesystem-Write Helpers

Theme: Directory creation, permission handling, and file-write semantics are duplicated across logging, payload storage, sessions, and TLS generation.

Location	Function	Pattern
internal/logger/fileutil.go	atomicWriteFile, writeJSONToFile	Atomic write + chmod
internal/middleware/jqschema.go	savePayload	MkdirAll + WriteFile
internal/server/session.go	ensureSessionDirectory	MkdirAll + permission check
internal/proxy/tls.go	writePEM	MkdirAll + WriteFile

Recommendation: Evaluate whether a shared internal/fileutil (or extending internal/logger/fileutil.go) for mkdir/write/chmod/atomic-write patterns would reduce duplication and simplify error handling.

---

Refactoring Recommendations

Priority 1: High Impact

1. Consolidate session ID extraction — Ensure ExtractSessionIDFromHeaders is the single canonical implementation, with extractSessionIDFromRequest being a clear, minimal wrapper. Estimated effort: ~30 min.

2. Move GenerateRandomAgentID — Relocate to internal/util/random.go for consistency with other random utilities. Estimated effort: ~30 min.

3. Extract shared JSON-state logger scaffolding — Deduplicate writeToFile pattern in internal/logger/. Estimated effort: ~1–2 hours.

Priority 2: Medium Impact

4. Centralize typed tool-argument decoding — Create reusable owner/repo/username extractor helpers. Estimated effort: ~2–3 hours.

5. Shared filesystem-write utilities — Audit and consolidate file-write patterns across logger, middleware, server, proxy. Estimated effort: ~2–4 hours.

6. Extract parseServerIDFromToolName — Move to a tool-name utility module. Estimated effort: ~30 min.

Priority 3: Long-term Improvements

7. Formalize env-var validation layering — Expand envutil with reusable validated-reader combinators; keep config package purely policy-focused. Estimated effort: ~3–4 hours.

---

Implementation Checklist

• Review and triage findings above
• Consolidate ExtractSessionIDFromHeaders / extractSessionIDFromRequest duplication
• Move GenerateRandomAgentID to internal/util/random.go
• Deduplicate writeToFile in internal/logger/
• Centralize typed tool-argument decoding helpers
• Audit filesystem-write helpers across packages
• Extract parseServerIDFromToolName to tool-name utilities
• Expand envutil validated-reader layer

Analysis Metadata

Field	Value
Total Go Files Analyzed	158
Total Functions Cataloged	956
Function Clusters Identified	12
Outlier Functions Found	4
Near-Duplicate Pairs Detected	4
Scattered Helper Themes	4
Detection Method	Naming pattern analysis + semantic clustering
Analysis Date	2026-07-19

References:

• §29703870629

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• awmgmcpg
• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Semantic Function Refactoring · 78.1 AIC · ⊞ 8.5K · ◷