🔧 Semantic Function Clustering Analysis

Analysis of repository: github/gh-aw-mcpg
Workflow run: §28755174481

Overview

This report analyzes all 149 non-test Go source files across 24 packages in internal/, cataloging 929 functions/methods. The analysis identifies semantic clusters, outliers, and near-duplicate patterns. The codebase is generally well-organized; findings below are refactoring opportunities rather than critical defects.

Analysis Metadata

• Total Go Files Analyzed: 149 (non-test, in internal/)
• Total Functions/Methods Cataloged: 929
• Packages Analyzed: 24
• Top packages by function count: server (130), config (128), difc (115), logger (107), guard (75)

Identified Issues

1. Parallel sessionSuffix / truncateSessionID Functions

Issue: Two packages independently implement a function to format a session ID for logging.

While the exact output differs, both serve the same purpose: producing a log-safe representation of a session ID. The launcher variant doesn't truncate at all, which may leak full session IDs into logs.

Recommendation: Consolidate into internal/util with a shared FormatSessionIDForLog(sessionID string) string function. This also fixes the missing truncation in the launcher path.

Estimated Impact: Consistent session ID logging across all packages, reduced duplication.

2. Parallel Rate-Limit Reset Parsers

Issue: Two different implementations parse GitHub rate-limit reset times with different input formats.

The files even have cross-references in comments acknowledging each other's existence — a code smell indicating they should share a home. Both handle the same concern (deriving a time.Time from GitHub rate-limit data).

Recommendation: Consolidate both into internal/githubhttp/ (e.g., a new internal/githubhttp/ratelimit.go), since rate-limit handling is GitHub-specific. The server package can import it.

Estimated Impact: Centralized rate-limit parsing, easier to update when the GitHub API changes.

3. truncateSanitized is a Trivial Alias in logger/rpc_format.go

Issue: internal/logger/rpc_format.go defines:

func truncateSanitized(sanitized string, maxLength int) string {
    return util.Truncate(sanitized, maxLength)
}

This is a one-liner alias for util.Truncate with no added behavior. The sibling truncateAndSanitize is meaningful (chains sanitization + truncation). This alias adds indirection without value.

Recommendation: Remove truncateSanitized and call util.Truncate(sanitized, maxLength) directly at the two call sites.

Estimated Impact: Minor — reduces unnecessary indirection.

4. IsSingularReadTool in difc/evaluator.go — Potential Misplacement

Issue: internal/difc/evaluator.go contains:

func IsSingularReadTool(toolName string) bool {
    return !strings.HasPrefix(toolName, "list_") && !strings.HasPrefix(toolName, "search_")
}

This is a tool-naming convention helper that classifies MCP tool names by name prefix. It doesn't use any DIFC types or labels — it's a pure string classification utility in a file with 18 complex DIFC evaluation functions.

Recommendation: Move to internal/mcp/helpers.go or a new internal/difc/tool_helpers.go to separate it from the core DIFC evaluation logic.

Estimated Impact: Better discoverability — developers looking for tool-naming utilities will find them in the MCP package.

5. CreateHTTPServerForRoutedMode Co-location

Issue: internal/server/routed.go contains CreateHTTPServerForRoutedMode, while internal/server/http_server.go contains CreateHTTPServerForMCP. Both are public HTTP server factory functions that call the same buildMCPHTTPServer helper (defined in http_server.go).

routed.go currently holds only 3 functions, with the server-creation concern mixed with routing logic.

Recommendation: Move CreateHTTPServerForRoutedMode to http_server.go to co-locate all HTTP server factory functions. Leave pure routing logic (route registration, filtered server cache setup) in routed.go.

Estimated Impact: Clearer file responsibility — http_server.go owns all HTTP server creation.

Function Cluster Summary

Well-Organized Clusters ✓

Intentional Patterns (No Action Needed)

• rejectAuthRequest / rejectHMACRequest: Thin wrappers around rejectRequest — correctly documented as the intended pattern in http_helpers.go.
• InitFileLogger, InitMarkdownLogger, etc.: 7 separate logger init functions — intentional design for independent loggers dispatched via initLoggerSet.
• envutil/expand_env_args.go vs config/expand.go: Different expansion concerns (Docker -e flags vs ${VAR} syntax in config JSON) — correct separation.

Refactoring Recommendations by Priority

Priority 1: High Impact

1. Consolidate session ID formatting (Issue Configure as a Go CLI tool #1)

   • Merge sessionSuffix/truncateSessionID into shared internal/util utility
   • Add truncation to launcher path for security
   • Estimated effort: 1-2 hours

2. Centralize rate-limit reset parsing (Issue Lpcox/initial implementation #2)

   • Move parseRateLimitResetFromText to internal/githubhttp/
   • Remove cross-package comment references
   • Estimated effort: 1-2 hours

Priority 2: Medium Impact

3. Remove truncateSanitized alias (Issue Lpcox/initial implementation #3)

   • Replace 2 call sites with util.Truncate directly
   • Estimated effort: 30 minutes

4. Move IsSingularReadTool to MCP package (Issue Lpcox/add difc #4)

   • Move to internal/mcp/helpers.go
   • Update callers in difc/ and server/
   • Estimated effort: 1 hour

5. Move CreateHTTPServerForRoutedMode to http_server.go (Issue Updated Dockerfile #5)

   • Co-locate all HTTP server factory functions
   • Estimated effort: 30 minutes

Implementation Checklist

• Consolidate sessionSuffix/truncateSessionID into shared utility with proper truncation
• Move rate-limit reset parsing to internal/githubhttp/
• Remove truncateSanitized alias; call util.Truncate directly
• Move IsSingularReadTool to internal/mcp/helpers.go
• Move CreateHTTPServerForRoutedMode to http_server.go
• Run make agent-finished after each refactor to verify no regressions

References:

• §28755174481

network:
  allowed:
    - defaults
    - "awmgmcpg"

Generated by Semantic Function Refactoring · 94.9 AIC · ⊞ 8.4K · ◷