feat: add findUnwiredModules — entrypoint reachability check (#200)

Add a new check that detects exported symbols never transitively
reachable from application entrypoints (main, server, CLI). This
catches the "built but never plugged in" pattern where modules exist
and are tested but aren't wired into the execution pipeline.

Algorithm: BFS forward from entrypoint files using SCIP call graph,
building a reachable set (10K node budget), then flags exported
functions/methods not in the set.

Exposed via all interfaces:
- CLI: ckb unwired [--scope, --format, --min-confidence]
- HTTP API: GET /unwired?scope=...&minConfidence=...&limit=...
- MCP: findUnwiredModules tool (review + refactor presets)
- PR Review: "unwired" check (21st quality check in ckb review)

New package: internal/unwired/ (detector + types)
New engine method: query.FindUnwiredModules()

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: SimplyLiz

CLAUDE.md

@@ -51,7 +51,12 @@ golangci-lint run
 # Start A2A protocol server (for agent-to-agent communication)
 ./ckb a2a --port 8081
 
-# Run PR review (20 quality checks)
+# Find exported symbols not reachable from entrypoints
+./ckb unwired
+./ckb unwired --scope internal/cost,internal/multisampling
+./ckb unwired --format json
+
+# Run PR review (21 quality checks)
 ./ckb review
 ./ckb review --base=develop --format=markdown
 ./ckb review --checks=breaking,secrets,health --ci
@@ -124,15 +129,15 @@ claude mcp add ckb -- npx @tastehub/ckb mcp
 
 **Intelligence (v6.5):** `explainOrigin`, `analyzeCoupling`, `exportForLLM`, `auditRisk`
 
-**Code Analysis (v7.6):** `findDeadCode` (static dead code detection), `getAffectedTests`, `compareAPI`
+**Code Analysis (v7.6):** `findDeadCode` (static dead code detection), `findUnwiredModules` (entrypoint reachability — detects "built but never plugged in" modules), `getAffectedTests`, `compareAPI`
 
 **Compound Operations (v8.0):** `explore`, `understand`, `prepareChange`, `batchGet`, `batchSearch`
 
 **Streaming (v8.0):** `findReferences` and `searchSymbols` support SSE streaming with `stream: true`
 
 **Index Management (v8.0):** `reindex` (trigger index refresh), enhanced `getStatus` with health tiers
 
-**PR Review (v8.2):** `reviewPR` — unified review with 20 quality checks (breaking, secrets, tests, complexity, health, coupling, hotspots, risk, critical-path, traceability, independence, generated, classify, split, dead-code, test-gaps, blast-radius, comment-drift, format-consistency, bug-patterns); optional `--llm` flag for Claude-powered narrative
+**PR Review (v8.2):** `reviewPR` — unified review with 21 quality checks (breaking, secrets, tests, complexity, health, coupling, hotspots, risk, critical-path, traceability, independence, generated, classify, split, dead-code, unwired, test-gaps, blast-radius, comment-drift, format-consistency, bug-patterns); optional `--llm` flag for Claude-powered narrative
 
 ## A2A Integration
 

cmd/ckb/unwired.go

@@ -0,0 +1,136 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/SimplyLiz/CodeMCP/internal/query"
+)
+
+var (
+	unwiredFormat        string
+	unwiredScope         []string
+	unwiredLimit         int
+	unwiredMinConfidence float64
+	unwiredExclude       []string
+	unwiredIncludeTypes  bool
+	unwiredMaxNodes      int
+)
+
+var unwiredCmd = &cobra.Command{
+	Use:   "unwired",
+	Short: "Find exported symbols not reachable from entrypoints",
+	Long: `Find exported functions and methods that are never transitively called
+from any application entrypoint (main, server, CLI commands).
+
+This detects the "built but never plugged in" pattern where modules exist
+and are tested but aren't wired into the execution pipeline.
+
+Complements dead-code (which checks reference counts) by checking
+reachability from the actual runtime entry points.
+
+Examples:
+  ckb unwired
+  ckb unwired --scope src/cost,src/multisampling
+  ckb unwired --min-confidence 0.9
+  ckb unwired --include-types
+  ckb unwired --format json`,
+	Run: runUnwired,
+}
+
+func init() {
+	unwiredCmd.Flags().StringVar(&unwiredFormat, "format", "human", "Output format (human, json)")
+	unwiredCmd.Flags().StringSliceVar(&unwiredScope, "scope", nil, "Limit to specific packages/paths")
+	unwiredCmd.Flags().IntVar(&unwiredLimit, "limit", 100, "Maximum results to return")
+	unwiredCmd.Flags().Float64Var(&unwiredMinConfidence, "min-confidence", 0.80, "Minimum confidence threshold (0-1)")
+	unwiredCmd.Flags().StringSliceVar(&unwiredExclude, "exclude", nil, "Patterns to exclude")
+	unwiredCmd.Flags().BoolVar(&unwiredIncludeTypes, "include-types", false, "Include type definitions (higher FP rate)")
+	unwiredCmd.Flags().IntVar(&unwiredMaxNodes, "max-nodes", 10000, "Max symbols in reachable set")
+	rootCmd.AddCommand(unwiredCmd)
+}
+
+func runUnwired(cmd *cobra.Command, args []string) {
+	start := time.Now()
+	logger := newLogger(unwiredFormat)
+
+	repoRoot := mustGetRepoRoot()
+	engine := mustGetEngine(repoRoot, logger)
+	ctx := newContext()
+
+	opts := query.FindUnwiredModulesOptions{
+		Scope:           unwiredScope,
+		ExcludePatterns: unwiredExclude,
+		MinConfidence:   unwiredMinConfidence,
+		IncludeTypes:    unwiredIncludeTypes,
+		MaxNodes:        unwiredMaxNodes,
+		Limit:           unwiredLimit,
+	}
+
+	response, err := engine.FindUnwiredModules(ctx, opts)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	if unwiredFormat == "json" {
+		data, err := json.MarshalIndent(response, "", "  ")
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error formatting output: %v\n", err)
+			os.Exit(1)
+		}
+		fmt.Println(string(data))
+	} else {
+		printUnwiredHuman(response)
+	}
+
+	logger.Debug("Unwired analysis completed",
+		"unwiredCount", response.Summary.UnwiredCount,
+		"reachableCount", response.ReachableCount,
+		"duration", time.Since(start).Milliseconds(),
+	)
+}
+
+func printUnwiredHuman(resp *query.FindUnwiredModulesResponse) {
+	fmt.Println("Unwired Module Analysis")
+	fmt.Println("============================================================")
+	fmt.Println()
+
+	if len(resp.Entrypoints) > 0 {
+		fmt.Printf("Entrypoints: %d\n", len(resp.Entrypoints))
+		for _, ep := range resp.Entrypoints {
+			fmt.Printf("  - %s\n", ep)
+		}
+		fmt.Println()
+	}
+
+	fmt.Printf("Reachable symbols: %d\n", resp.ReachableCount)
+	fmt.Printf("Total exported:    %d\n", resp.Summary.TotalExported)
+	fmt.Printf("Unwired:           %d\n", resp.Summary.UnwiredCount)
+	if resp.Partial {
+		fmt.Println("  (partial — reachable set budget exhausted)")
+	}
+	fmt.Println()
+
+	if len(resp.UnwiredModules) == 0 {
+		fmt.Println("No unwired modules found.")
+		return
+	}
+
+	for _, mod := range resp.UnwiredModules {
+		fmt.Printf("── %s (%d/%d exported symbols unwired)\n",
+			mod.Path, mod.Summary.UnwiredCount, mod.Summary.TotalExported)
+		for _, item := range mod.Items {
+			fmt.Printf("   %s %s  (%.0f%% confidence)\n",
+				item.Kind, item.SymbolName, item.Confidence*100)
+			fmt.Printf("     %s\n", item.Reason)
+			if item.ReferenceCount > 0 {
+				fmt.Printf("     refs: %d (test: %d)\n", item.ReferenceCount, item.TestReferences)
+			}
+		}
+		fmt.Println()
+	}
+}

internal/api/handlers_unwired.go

@@ -0,0 +1,50 @@
+package api
+
+import (
+	"net/http"
+	"strconv"
+
+	"github.com/SimplyLiz/CodeMCP/internal/query"
+)
+
+// handleUnwired handles GET /unwired — find exported symbols not reachable from entrypoints.
+func (s *Server) handleUnwired(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	ctx := r.Context()
+	q := r.URL.Query()
+
+	opts := query.FindUnwiredModulesOptions{
+		MinConfidence: 0.80,
+		Limit:         100,
+		MaxNodes:      10000,
+	}
+
+	if scope := q.Get("scope"); scope != "" {
+		opts.Scope = []string{scope}
+	}
+	if minConf := q.Get("minConfidence"); minConf != "" {
+		if v, err := strconv.ParseFloat(minConf, 64); err == nil {
+			opts.MinConfidence = v
+		}
+	}
+	if limit := q.Get("limit"); limit != "" {
+		if v, err := strconv.Atoi(limit); err == nil {
+			opts.Limit = v
+		}
+	}
+	if q.Get("includeTypes") == "true" {
+		opts.IncludeTypes = true
+	}
+
+	result, err := s.engine.FindUnwiredModules(ctx, opts)
+	if err != nil {
+		InternalError(w, "Failed to find unwired modules", err)
+		return
+	}
+
+	WriteJSON(w, result, http.StatusOK)
+}

internal/api/routes.go

@@ -55,6 +55,9 @@ func (s *Server) registerRoutes() {
 	// v8.2 Unified PR Review
 	s.router.HandleFunc("/review/pr", s.handleReviewPR) // GET/POST
 
+	// Unwired module detection
+	s.router.HandleFunc("/unwired", s.handleUnwired) // GET /unwired?scope=...&minConfidence=...&limit=...
+
 	// v6.2 Federation endpoints
 	s.router.HandleFunc("/federations", s.handleListFederations)   // GET
 	s.router.HandleFunc("/federations/", s.handleFederationRoutes) // /federations/:name/*

internal/mcp/presets.go

@@ -88,17 +88,18 @@ var Presets = map[string][]string{
 		"getOwnership",
 		"getOwnershipDrift",
 		"recentlyRelevant",
-		"scanSecrets",       // Secret detection for PR reviews
-		"reviewPR",          // Unified PR review with quality gates
-		"getAffectedTests",  // Tests covering changed code
-		"analyzeTestGaps",   // Untested functions in changed files
-		"compareAPI",        // Breaking API changes
-		"findDeadCode",      // Dead code in changes
-		"auditRisk",         // Multi-factor risk scoring
-		"analyzeChange",     // Change analysis
-		"getFileComplexity", // File complexity for review
-		"listEntrypoints",   // Key entry points in changed code
-		"auditCompliance",   // Regulatory compliance audit
+		"scanSecrets",        // Secret detection for PR reviews
+		"reviewPR",           // Unified PR review with quality gates
+		"getAffectedTests",   // Tests covering changed code
+		"analyzeTestGaps",    // Untested functions in changed files
+		"compareAPI",         // Breaking API changes
+		"findDeadCode",       // Dead code in changes
+		"findUnwiredModules", // Exported symbols not reachable from entrypoints
+		"auditRisk",          // Multi-factor risk scoring
+		"analyzeChange",      // Change analysis
+		"getFileComplexity",  // File complexity for review
+		"listEntrypoints",    // Key entry points in changed code
+		"auditCompliance",    // Regulatory compliance audit
 	},
 
 	// Refactor: core + refactoring analysis tools
@@ -114,9 +115,10 @@ var Presets = map[string][]string{
 		"justifySymbol",
 		"analyzeCoupling",
 		"findDeadCodeCandidates",
-		"findDeadCode",     // v7.6: Static dead code detection (no telemetry needed)
-		"getAffectedTests", // v7.6: Find tests affected by changes
-		"compareAPI",       // v7.6: Breaking change detection
+		"findDeadCode",       // v7.6: Static dead code detection (no telemetry needed)
+		"findUnwiredModules", // Exported symbols not reachable from entrypoints
+		"getAffectedTests",   // v7.6: Find tests affected by changes
+		"compareAPI",         // v7.6: Breaking change detection
 		"auditRisk",
 		"explainOrigin",
 		"scanSecrets",         // v8.0: Secret detection for security audits

internal/mcp/presets_test.go

@@ -42,9 +42,9 @@ func TestPresetFiltering(t *testing.T) {
 		t.Fatalf("failed to set full preset: %v", err)
 	}
 	fullTools := server.GetFilteredTools()
-	// v8.3: Full now includes auditCompliance, listSymbols, getSymbolGraph (96)
-	if len(fullTools) != 96 {
-		t.Errorf("expected 96 full tools (v8.3), got %d", len(fullTools))
+	// v8.4: Full now includes findUnwiredModules (97)
+	if len(fullTools) != 97 {
+		t.Errorf("expected 97 full tools, got %d", len(fullTools))
 	}
 
 	// Full preset should still have core tools first

internal/mcp/token_budget_test.go

@@ -34,8 +34,8 @@ func TestToolsListTokenBudget(t *testing.T) {
 		maxTools int
 	}{
 		{PresetCore, maxCorePresetBytes, 20, 24},     // v8.3: 24 tools (+explainPath, responsibilities, exportForLLM)
-		{PresetReview, maxReviewPresetBytes, 30, 40}, // v8.3: 40 tools (+auditCompliance)
-		{PresetFull, maxFullPresetBytes, 80, 96},     // v8.3: 96 tools (+listSymbols, getSymbolGraph)
+		{PresetReview, maxReviewPresetBytes, 30, 41}, // v8.4: 41 tools (+findUnwiredModules)
+		{PresetFull, maxFullPresetBytes, 80, 97},     // v8.4: 97 tools (+findUnwiredModules)
 	}
 
 	for _, tt := range tests {

internal/mcp/tool_impls_unwired.go

@@ -0,0 +1,70 @@
+package mcp
+
+import (
+	"context"
+
+	"github.com/SimplyLiz/CodeMCP/internal/envelope"
+	"github.com/SimplyLiz/CodeMCP/internal/query"
+)
+
+// toolFindUnwiredModules finds exported symbols not reachable from entrypoints.
+func (s *MCPServer) toolFindUnwiredModules(params map[string]interface{}) (*envelope.Response, error) {
+	opts := query.FindUnwiredModulesOptions{}
+
+	// Scope
+	if scopeRaw, ok := params["scope"].([]interface{}); ok {
+		for _, v := range scopeRaw {
+			if str, ok := v.(string); ok {
+				opts.Scope = append(opts.Scope, str)
+			}
+		}
+	}
+
+	// Exclude patterns
+	if patternsRaw, ok := params["excludePatterns"].([]interface{}); ok {
+		for _, p := range patternsRaw {
+			if str, ok := p.(string); ok {
+				opts.ExcludePatterns = append(opts.ExcludePatterns, str)
+			}
+		}
+	}
+
+	// Min confidence
+	opts.MinConfidence = 0.80
+	if v, ok := params["minConfidence"].(float64); ok {
+		opts.MinConfidence = v
+	}
+
+	// Include types
+	if v, ok := params["includeTypes"].(bool); ok {
+		opts.IncludeTypes = v
+	}
+
+	// Max nodes (reachable set budget)
+	opts.MaxNodes = 10000
+	if v, ok := params["maxNodes"].(float64); ok {
+		opts.MaxNodes = int(v)
+	}
+
+	// Limit
+	opts.Limit = 100
+	if v, ok := params["limit"].(float64); ok {
+		opts.Limit = int(v)
+	}
+
+	ctx := context.Background()
+	result, err := s.engine().FindUnwiredModules(ctx, opts)
+	if err != nil {
+		return nil, err
+	}
+
+	resp := NewToolResponse().Data(result)
+	if result != nil && result.ReachableCount == 0 {
+		resp.Warning("No entrypoints detected. Ensure your project has main/server/CLI entry files.")
+	}
+	if result != nil && result.Partial {
+		resp.Warning("Reachable set budget exhausted — results may be incomplete. Increase maxNodes for a full scan.")
+	}
+
+	return resp.Build(), nil
+}