[refactor] Semantic Function Clustering Analysis - Code Organization Opportunities

[github-actions]

Analysis of repository: githubnext/gh-aw-mcpg

Executive Summary

Analyzed 50 non-test Go files across 13 packages containing approximately 358 exported functions. The analysis identified 4 high-priority refactoring opportunities focused on reducing duplication and improving code organization. The codebase is generally well-organized with clear package boundaries, but there are specific opportunities to consolidate duplicate logic, centralize initialization patterns, and improve function placement.

Key Findings:

• ✅ Well-organized packages: Most packages follow single-responsibility principle
• ⚠️ Duplicate version setters: SetGatewayVersion() duplicated in 2 packages
• ⚠️ Logger initialization pattern: Repeated Init*/Close* pattern across 3 logger types
• ⚠️ Deprecated wrapper function: extractSessionFromAuth() marked deprecated but still present
• ✅ Good use of helper functions: common.go in logger package demonstrates good consolidation

Function Inventory

By Package

Package	Files	Functions	Primary Purpose
auth	1	9	Authorization header parsing
cmd	2	21	CLI commands (Cobra)
config	4	87	Configuration parsing & validation
difc	5	87	Security labels & DIFC system
guard	4	22	Security guards
launcher	2	50	Backend process management
logger	10	134	Logging framework
mcp	2	76	MCP protocol types
middleware	1	20	JQ schema middleware
server	9	130	HTTP server
sys	1	21	System utilities
testutil	4	28	Test utilities
timeutil	1	2	Time formatting
tty	2	11	TTY handling

Total: 50 files, ~358 functions

Clustering Results

Well-Organized Clusters (✅ No action needed):

• Constructor pattern: Consistent New*() functions (28 instances)
• Context helpers: Get*FromContext() and Set*InContext() in guard package
• Clone methods: 4 similar implementations in difc package (appropriate for type-specific logic)
• Logger common helpers: common.go centralizes shared file operations (initLogFile, closeLogFile)

Patterns Identified:

• Initialization: Init* (3 logger instances)
• Cleanup: Close* (3 logger instances, plus individual Close methods)
• Logging: Log* (12+ variations across file, markdown, jsonl loggers)
• Validation: Validate* (3 instances, well-distributed)

Identified Issues

1. 🔴 Duplicate Version Setter Functions

Issue: Identical SetGatewayVersion() function duplicated in two packages

Occurrences:

1. internal/server/unified.go:34 - For health endpoint reporting
2. internal/config/validation_schema.go:28 - For error reporting

Code Comparison:

// internal/server/unified.go
var gatewayVersion = "dev"

func SetGatewayVersion(version string) {
    if version != "" {
        gatewayVersion = version
    }
}

// internal/config/validation_schema.go  
var gatewayVersion = "dev"

func SetGatewayVersion(version string) {
    if version != "" {
        gatewayVersion = version
    }
}

Impact: Requires calling two separate functions to set version consistently

Recommendation:

• Create a single SetVersion() function in a shared location (e.g., version.go at root or in internal/config)
• Both packages should import and use the centralized version variable
• Estimated effort: 1-2 hours
• Benefits: Single source of truth, reduced duplication, easier version management

---

2. 🟡 Logger Initialization Pattern Repetition

Issue: Similar initialization/cleanup patterns repeated across 3 logger types

Pattern Analysis:
All three logger types (FileLogger, JSONLLogger, MarkdownLogger) implement nearly identical patterns:

// Pattern repeated 3 times:
func Init[Type]Logger(logDir, fileName string) error {
    // 1. Create logger struct
    // 2. Call initLogFile() helper
    // 3. Handle fallback/error
    // 4. Initialize global logger
}

func Close[Type]Logger() error {
    // 1. Lock mutex
    // 2. Call closeLogFile() helper  
    // 3. Return result
}

Current State: ✅ Good use of common helpers

• initLogFile() and closeLogFile() in common.go already centralize file operations
• Duplication is primarily in the wrapper functions and global initialization

Analysis:

• The current pattern is acceptable given that each logger type has specific needs:
  • FileLogger: Fallback to stdout
  • JSONLLogger: JSON encoder initialization
  • MarkdownLogger: HTML wrapper initialization
• The important shared logic (file operations) is already centralized in common.go

Recommendation:

• Priority: LOW - Current organization is reasonable
• If further consolidation is desired:
  • Consider a generic LoggerBase struct with common initialization
  • Use composition pattern for type-specific behavior
• Estimated effort: 4-6 hours
• Benefits: Marginal - current organization with common.go is already good

---

3. 🟡 Deprecated Wrapper Function Not Removed

Issue: Deprecated function still present in codebase

Location: internal/server/auth.go:51

// Deprecated: Use auth.ExtractSessionID directly instead.
func extractSessionFromAuth(authHeader string) string {
    return auth.ExtractSessionID(authHeader)
}

Analysis:

• Function marked deprecated with clear guidance
• Simple one-line wrapper that delegates to internal/auth package
• Likely kept for backward compatibility during transition period

Recommendation:

• Search codebase for any remaining calls to extractSessionFromAuth()
• If no callers exist, remove the function
• If callers exist, refactor to use auth.ExtractSessionID() directly
• Estimated effort: 30 minutes - 1 hour
• Benefits: Cleaner codebase, reduced indirection

Verification command:

grep -r "extractSessionFromAuth" internal/ --include="*.go"

---

4. 🟢 File Organization - Auth Functions

Issue: Auth middleware and logging helper in same file

Current Structure: internal/server/auth.go

• authMiddleware() - HTTP middleware for authentication
• extractSessionFromAuth() - Deprecated wrapper (see issue Lpcox/initial implementation #3)
• logRuntimeError() - Error logging utility

Analysis:

• logRuntimeError() is a general utility function in an auth-specific file
• Function is only called within the server package (checked 2 occurrences in auth.go)
• Current placement is marginally acceptable but could be improved

Recommendation:

• Priority: LOW - Current organization is functional
• If refactoring: Move logRuntimeError() to:
  • Option A: internal/server/helpers.go (for server-specific utilities)
  • Option B: Keep in auth.go but rename file to server/middleware.go to reflect broader scope
• Estimated effort: 1 hour
• Benefits: Clearer file purpose, better organization

Detailed Function Clusters

Cluster 1: Configuration Functions ✅

Pattern: Configuration loading, parsing, and validation
Files: internal/config/ (4 files)

Functions:

• config.go: Loading (2 functions)
• validation.go: Variable expansion (1 function)
• validation_env.go: Environment validation (7 functions)
• validation_schema.go: Schema validation (~10 functions)
• rules/rules.go: Validation error constructors (8+ functions)

Analysis: ✅ Well-organized by functionality - Each file has clear purpose

---

Cluster 2: Server Functions

Pattern: HTTP server and routing
Files: internal/server/ (9 files)

Organization:

• server.go - Core server (11 functions)
• routed.go - Routed mode (4 functions)
• unified.go - Unified mode (16+ functions)
• auth.go - Auth middleware (3 functions)
• handlers.go - Generic handlers (2 functions)
• health.go - Health endpoint (2 functions)
• response_writer.go - Response wrapper (5 functions)
• transport.go - HTTP transport (6 functions)
• sdk_logging.go - SDK logging middleware (2 functions)

Analysis: ✅ Good separation by mode and concern

---

Cluster 3: Logger Functions

Pattern: Logging infrastructure
Files: internal/logger/ (10 files)

Organization:

• logger.go - Debug logger (3 functions)
• file_logger.go - File logging (6 functions)
• jsonl_logger.go - JSONL RPC logging (5 functions)
• markdown_logger.go - Markdown logging (6 functions)
• rpc_logger.go - RPC logging (3 functions)
• rpc_formatter.go - RPC formatting (private functions)
• rpc_helpers.go - RPC helpers (1 function)
• common.go - Shared helpers (2 functions) ✅
• slog_adapter.go - Slog integration (7 functions)
• global_helpers.go - Global logger access
• sanitize/sanitize.go - Data sanitization (5 functions)

Analysis: ✅ Well-organized with good use of common helpers

---

Cluster 4: DIFC Functions

Pattern: Security labels and information flow control
Files: internal/difc/ (5 files)

Organization:

• agent.go - Agent labels (17 functions)
• capabilities.go - Capabilities (8 functions)
• evaluator.go - Flow evaluation (6 functions)
• labels.go - Label types (19 functions)
• resource.go - Resources (11 functions)

Analysis: ✅ Well-organized by concept within security domain

---

Cluster 5: Launcher Functions

Pattern: Backend process management
Files: internal/launcher/ (2 files)

Organization:

• launcher.go - Main launcher (5 functions)
• connection_pool.go - Connection pooling (11 functions)

Analysis: ✅ Clear separation between launch and pool management

Refactoring Recommendations

Priority 1: High Impact (Recommended)

1.1 Consolidate Duplicate SetGatewayVersion()

• Effort: 1-2 hours
• Impact: HIGH
• Task: Create single version management function
• Benefits: Single source of truth, easier maintenance

1.2 Remove Deprecated extractSessionFromAuth()

• Effort: 30 minutes - 1 hour
• Impact: MEDIUM
• Task: Verify no callers exist, remove function
• Benefits: Reduced code, clearer call paths

Priority 2: Medium Impact (Consider)

2.1 Review Logger Initialization Pattern

• Effort: 4-6 hours
• Impact: LOW-MEDIUM
• Task: Consider generic base logger with composition
• Benefits: Marginal - current common.go approach is already good
• Note: Current organization is acceptable; only refactor if adding more logger types

Priority 3: Low Impact (Optional)

3.1 Relocate logRuntimeError() Function

• Effort: 1 hour
• Impact: LOW
• Task: Move to dedicated helpers file or rename auth.go
• Benefits: Slightly clearer organization

Implementation Checklist

Phase 1: Quick Wins (2-3 hours)

• Task 1: Consolidate SetGatewayVersion() functions

  • Create centralized version management (new version.go or in config/)
  • Update internal/server/unified.go to use centralized version
  • Update internal/config/validation_schema.go to use centralized version
  • Update main.go to call single version setter
  • Run tests to verify

• Task 2: Remove deprecated extractSessionFromAuth()

  • Verify no callers: grep -r "extractSessionFromAuth" internal/
  • Remove function from internal/server/auth.go
  • Run tests to verify

Phase 2: Optional Improvements (4-6 hours)

• Task 3: Review logger initialization patterns (if needed)
• Task 4: Relocate logRuntimeError() (if desired)

Phase 3: Verification

• Run full test suite: make test-all
• Run linter: make lint
• Verify no functionality broken
• Update documentation if needed

Analysis Metadata

• Total Go Files Analyzed: 50 (excluding tests)
• Total Functions Cataloged: ~358
• Function Clusters Identified: 5 major clusters
• High-Priority Issues Found: 2
• Medium-Priority Issues Found: 2
• Code Organization: Generally excellent with clear package boundaries
• Detection Method: Pattern analysis + grep-based code inspection
• Analysis Date: 2026-01-22
• Repository: githubnext/gh-aw-mcpg

Key Strengths

✅ Well-organized package structure following Go conventions
✅ Consistent naming patterns (New*, Get*, Validate*, etc.)
✅ Good use of helper functions (e.g., logger/common.go)
✅ Clear separation of concerns (routed vs unified server modes)
✅ Proper use of internal packages for encapsulation

Summary

The MCP Gateway codebase demonstrates strong organization with clear package boundaries and consistent patterns. The identified refactoring opportunities are focused on eliminating specific instances of duplication rather than systemic organizational issues. The highest priority items (duplicate SetGatewayVersion() and deprecated wrapper function) are straightforward fixes with clear benefits.

Recommended action: Focus on Priority 1 tasks (3-4 hours total) for immediate code quality improvements. Priority 2 and 3 items can be deferred as they offer marginal benefits given the current good organization.

AI generated by Semantic Function Refactoring