[refactor] Semantic Function Clustering Analysis — response_writer duplication and package organization #10584

Executive Summary

Analyzed 149 non-test .go files (~987 functions) under internal/. Overall the codebase is well-organized by feature (config split across config_*/validation_* files, difc cleanly separated, guard implementations grouped). Most name collisions found (Close, String, Error, New, UnmarshalJSON, Overall/ToResult, LabelAgent/LabelResource/LabelResponse) are expected Go idioms — distinct types implementing the same interface (io.Closer, error, fmt.Stringer, json.Unmarshaler, the guard.Guard and difc.LabeledData interfaces) — and are not refactoring targets.

One concrete near-duplicate was identified and is worth consolidating.

Identified Issue: Near-duplicate response writer wrapper

• File 1: internal/httputil/response_writer.go — BaseResponseWriter (status-code capture: WriteHeader, Write, Unwrap)
• File 2: internal/server/response_writer.go — responseWriter — already embeds httputil.BaseResponseWriter and only adds body buffering (body bytes.Buffer, Body()).

This is a good case of prior de-duplication (server's writer embeds the shared base rather than reimplementing status capture), so no action needed here beyond noting it as the intended pattern — flagging so it isn't mistaken for accidental duplication in future audits. Its logging wrapper methods (WriteHeader/Write overrides that just log then delegate) are thin pass-throughs and fine as-is.

Other Observations (no action needed)

• Close() implementations across internal/logger/*.go, internal/mcp/connection.go, internal/guard/registry.go, internal/guard/wasm_lifecycle.go, internal/launcher/launcher.go — each is a distinct type's io.Closer; not duplicative.
• LabelAgent/LabelResource/LabelResponse in internal/guard/{noop,wasm_labels,write_sink}.go — required implementations of the guard.Guard interface (NoopGuard, WasmGuard, WriteSinkGuard); correctly one-per-file.
• Overall()/ToResult() across internal/difc/resource.go (3 types) and internal/difc/path_labels.go — implementations of the difc.LabeledData interface for different resource wrapper types; correctly co-located, appropriate for path_labels.go to have its own file given it's a distinct labeled-data variant.
• UnmarshalJSON pairs in internal/config/guard_policy.go and internal/config/config_stdin.go — standard custom-unmarshaler pattern for different config types.
• validate* functions are already centralized across internal/config/validation_*.go files by concern (env, gateway, schema, server, rules) — well organized, no scatter detected.
• internal/util/ already serves as the centralized utility package (collections, format, json, netutil, random, toolname, truncate) — no scattered helper duplication found elsewhere.

Conclusion

No significant refactoring opportunities (misplaced functions, duplicate logic, or scattered helpers) were found beyond the note above. The codebase's internal/ structure is deliberately organized per-feature and per-concern, and repeated method names are legitimate polymorphic interface implementations rather than copy-paste duplication.

Analysis Metadata

• Total Go files analyzed: 149 (excluding _test.go)
• Total functions cataloged: ~987
• Duplicate/near-duplicate implementations found: 1 (already properly de-duplicated via embedding)
• Outliers found: 0
• Detection method: static grep/AST-pattern analysis of function signatures and cross-file name collisions

Generated by Semantic Function Refactoring · auto · 42.8 AIC · ⊞ 14K · ◷