feat(analyzer): confidence-aware node + canonical edge dedup with surfaced counts

Plan Phase 1.1, 1.2, 1.5 — make the graph deterministic and canonical.

Before: GraphBuilder used first-write-wins on node ID. A class touched by
both ClassHierarchyDetector and SpringRestDetector would keep whichever
landed first (often the lower-confidence LEXICAL detector) and silently
drop the higher-confidence framework annotations.

After:
- mergeNode picks the higher-Confidence emission as the survivor.
- Survivor gap-fills missing FQN / Module / FilePath / LineStart /
  LineEnd / Layer / Source from the donor.
- Properties union with non-clobber semantics: donor only fills keys
  the survivor doesn't already have (preserves the high-confidence
  framework/auth_type/etc).
- Annotations unioned and sorted for determinism.

Edges now dedupe by canonical (sourceID, targetID, kind) tuple instead
of detector-assigned edge ID strings — two detectors emitting "a calls b"
with different edge ID conventions now collapse to one edge, with the
higher-confidence one winning.

Snapshot surfaces DedupedNodes / DedupedEdges / DroppedEdges counts.
codeiq index prints "Deduped: N nodes, M edges  Dropped: K phantom edges"
when any of those are non-zero, so operators can see graph health.

Tests (TDD per CLAUDE.md):
- TestGraphBuilderDedup_HigherConfidenceWins
- TestGraphBuilderDedup_AnnotationsUnioned
- TestGraphBuilderDedup_PropertiesMergeNonClobber
- TestGraphBuilderEdgeDedup_ByKey
- TestGraphBuilderEdgeDedup_DifferentKindKept
- TestGraphBuilderEdgeDedup_PropertiesUnioned
- TestGraphBuilderStats_DedupAndDropCounts

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: aksOps

go/internal/analyzer/analyzer.go

@@ -43,10 +43,17 @@ func NewAnalyzer(opts Options) *Analyzer {
 }
 
 // Stats reports per-run counts.
+//
+// Plan §1.5 — DedupedNodes/DedupedEdges/DroppedEdges expose dedup activity
+// so operators can see "graph collapsed 312 duplicate nodes, dropped 14
+// phantom edges" — the visibility is what makes "meaningful" diagnosable.
 type Stats struct {
-	Files int
-	Nodes int
-	Edges int
+	Files        int
+	Nodes        int
+	Edges        int
+	DedupedNodes int
+	DedupedEdges int
+	DroppedEdges int
 }
 
 // Run executes FileDiscovery → parse → detectors → GraphBuilder → cache writes
@@ -86,9 +93,12 @@ func (a *Analyzer) Run(root string) (Stats, error) {
 
 	snap := gb.Snapshot()
 	return Stats{
-		Files: len(files),
-		Nodes: len(snap.Nodes),
-		Edges: len(snap.Edges),
+		Files:        len(files),
+		Nodes:        len(snap.Nodes),
+		Edges:        len(snap.Edges),
+		DedupedNodes: snap.DedupedNodes,
+		DedupedEdges: snap.DedupedEdges,
+		DroppedEdges: snap.DroppedEdges,
 	}, nil
 }
 

go/internal/analyzer/graph_builder.go

@@ -9,50 +9,82 @@ import (
 )
 
 // GraphBuilder buffers detector results across batches. Concurrent-safe.
-// Snapshot() produces a deterministic sorted view with dangling edges
-// dropped — the same determinism contract as the Java GraphBuilder.
+//
+// Phase 1 (plan §1.1, §1.2):
+//   - Nodes are deduped by ID via mergeNode (confidence-aware).
+//   - Edges are deduped by canonical (source, target, kind) key via mergeEdge.
+//
+// Snapshot() produces a deterministic sorted view with phantom edges (those
+// whose endpoint is still missing) dropped, and exposes the dedup/drop
+// counts so the CLI can surface "deduped N, dropped K" diagnostics.
 type GraphBuilder struct {
 	mu    sync.Mutex
 	nodes map[string]*model.CodeNode
-	edges map[string]*model.CodeEdge
+	edges map[edgeKey]*model.CodeEdge
+
+	// Counters incremented as Add() observes duplicates and used by
+	// Snapshot() to populate the surfaced stats.
+	dedupedNodes int
+	dedupedEdges int
 }
 
 // NewGraphBuilder returns an empty builder.
 func NewGraphBuilder() *GraphBuilder {
 	return &GraphBuilder{
 		nodes: make(map[string]*model.CodeNode),
-		edges: make(map[string]*model.CodeEdge),
+		edges: make(map[edgeKey]*model.CodeEdge),
 	}
 }
 
-// Add merges a detector result. Duplicate node IDs are dropped (first write
-// wins — matches Java behaviour). Duplicate edge IDs likewise.
+// Add merges a detector result. Duplicate node IDs and duplicate edge
+// (source, target, kind) tuples collapse with confidence-aware merging.
 func (b *GraphBuilder) Add(r *detector.Result) {
 	if r == nil {
 		return
 	}
 	b.mu.Lock()
 	defer b.mu.Unlock()
 	for _, n := range r.Nodes {
-		if _, exists := b.nodes[n.ID]; !exists {
-			b.nodes[n.ID] = n
+		if existing, ok := b.nodes[n.ID]; ok {
+			b.nodes[n.ID] = mergeNode(existing, n)
+			b.dedupedNodes++
+			continue
 		}
+		b.nodes[n.ID] = n
 	}
 	for _, e := range r.Edges {
-		if _, exists := b.edges[e.ID]; !exists {
-			b.edges[e.ID] = e
+		k := makeEdgeKey(e)
+		if existing, ok := b.edges[k]; ok {
+			b.edges[k] = mergeEdge(existing, e)
+			b.dedupedEdges++
+			continue
 		}
+		b.edges[k] = e
 	}
 }
 
-// Snapshot is the deterministic, sorted view of buffered state with dangling
-// edges (source or target node missing) dropped.
+// Snapshot is the deterministic, sorted view of buffered state with
+// phantom edges (source or target node missing) dropped. It also exposes
+// the count of duplicate emissions collapsed during Add() and the count
+// of dangling edges dropped during this Snapshot call.
 type Snapshot struct {
 	Nodes []*model.CodeNode
 	Edges []*model.CodeEdge
+
+	// DedupedNodes is the count of node emissions that collided with an
+	// existing node ID and were merged in. Zero on a graph where no
+	// detector double-emitted.
+	DedupedNodes int
+	// DedupedEdges is the same for edges by (source, target, kind).
+	DedupedEdges int
+	// DroppedEdges is the count of edges that had no matching source or
+	// target node in the final node set — phantom references usually
+	// caused by a linker pointing at a node that no detector emitted.
+	DroppedEdges int
 }
 
-// Snapshot returns the current state as a sorted, dangling-edge-free Snapshot.
+// Snapshot returns the current state as a sorted, dangling-edge-free
+// Snapshot with surfaced dedup/drop counts.
 func (b *GraphBuilder) Snapshot() Snapshot {
 	b.mu.Lock()
 	defer b.mu.Unlock()
@@ -63,16 +95,25 @@ func (b *GraphBuilder) Snapshot() Snapshot {
 	sort.Slice(nodes, func(i, j int) bool { return nodes[i].ID < nodes[j].ID })
 
 	edges := make([]*model.CodeEdge, 0, len(b.edges))
+	dropped := 0
 	for _, e := range b.edges {
 		if _, src := b.nodes[e.SourceID]; !src {
+			dropped++
 			continue
 		}
 		if _, tgt := b.nodes[e.TargetID]; !tgt {
+			dropped++
 			continue
 		}
 		edges = append(edges, e)
 	}
 	sort.Slice(edges, func(i, j int) bool { return edges[i].ID < edges[j].ID })
 
-	return Snapshot{Nodes: nodes, Edges: edges}
+	return Snapshot{
+		Nodes:        nodes,
+		Edges:        edges,
+		DedupedNodes: b.dedupedNodes,
+		DedupedEdges: b.dedupedEdges,
+		DroppedEdges: dropped,
+	}
 }

go/internal/analyzer/merger.go

@@ -0,0 +1,135 @@
+package analyzer
+
+import (
+	"sort"
+
+	"github.com/randomcodespace/codeiq/go/internal/model"
+)
+
+// mergeNode merges incoming into existing, picking the higher-confidence
+// node as the survivor, then filling gaps and unioning properties /
+// annotations. Returns the survivor (which is mutated in place).
+//
+// Plan §1.1 — semantics:
+//   - Higher Confidence wins; ties keep existing.
+//   - Non-empty FQN / Module / FilePath / LineStart / LineEnd / Layer
+//     fill in from whichever side has them.
+//   - Properties: incoming wins per-key only when existing's value is nil
+//     or missing (do not clobber framework/auth_type already stamped by a
+//     higher-confidence detector).
+//   - Annotations are unioned and sorted for determinism.
+func mergeNode(existing, incoming *model.CodeNode) *model.CodeNode {
+	if existing == nil {
+		return incoming
+	}
+	if incoming == nil {
+		return existing
+	}
+
+	survivor := existing
+	donor := incoming
+	if incoming.Confidence > existing.Confidence {
+		survivor = incoming
+		donor = existing
+	}
+
+	// Gap-fill scalar fields from the donor when the survivor has none.
+	if survivor.FQN == "" && donor.FQN != "" {
+		survivor.FQN = donor.FQN
+	}
+	if survivor.Module == "" && donor.Module != "" {
+		survivor.Module = donor.Module
+	}
+	if survivor.FilePath == "" && donor.FilePath != "" {
+		survivor.FilePath = donor.FilePath
+	}
+	if survivor.LineStart == 0 && donor.LineStart != 0 {
+		survivor.LineStart = donor.LineStart
+	}
+	if survivor.LineEnd == 0 && donor.LineEnd != 0 {
+		survivor.LineEnd = donor.LineEnd
+	}
+	if survivor.Layer == model.LayerUnknown && donor.Layer != model.LayerUnknown {
+		survivor.Layer = donor.Layer
+	}
+	if survivor.Source == "" && donor.Source != "" {
+		survivor.Source = donor.Source
+	}
+
+	// Property union: donor fills missing keys; never clobbers existing.
+	if survivor.Properties == nil {
+		survivor.Properties = map[string]any{}
+	}
+	for k, v := range donor.Properties {
+		if _, exists := survivor.Properties[k]; exists {
+			continue
+		}
+		survivor.Properties[k] = v
+	}
+
+	// Annotation union — dedup + sort for determinism.
+	survivor.Annotations = unionSorted(survivor.Annotations, donor.Annotations)
+
+	return survivor
+}
+
+// mergeEdge merges two edges with the same EdgeKey (src, tgt, kind).
+// Higher-confidence wins; ties keep existing. Properties unioned with
+// non-clobber semantics.
+func mergeEdge(existing, incoming *model.CodeEdge) *model.CodeEdge {
+	if existing == nil {
+		return incoming
+	}
+	if incoming == nil {
+		return existing
+	}
+
+	survivor := existing
+	donor := incoming
+	if incoming.Confidence > existing.Confidence {
+		survivor = incoming
+		donor = existing
+	}
+	if survivor.Source == "" && donor.Source != "" {
+		survivor.Source = donor.Source
+	}
+	if survivor.Properties == nil {
+		survivor.Properties = map[string]any{}
+	}
+	for k, v := range donor.Properties {
+		if _, exists := survivor.Properties[k]; exists {
+			continue
+		}
+		survivor.Properties[k] = v
+	}
+	return survivor
+}
+
+func unionSorted(a, b []string) []string {
+	seen := make(map[string]struct{}, len(a)+len(b))
+	for _, s := range a {
+		seen[s] = struct{}{}
+	}
+	for _, s := range b {
+		seen[s] = struct{}{}
+	}
+	out := make([]string, 0, len(seen))
+	for s := range seen {
+		out = append(out, s)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// edgeKey is the canonical key used to dedupe edges. Two edges with the
+// same (source, target, kind) are considered the same edge regardless of
+// detector-assigned ID strings.
+type edgeKey struct {
+	source string
+	target string
+	kind   model.EdgeKind
+}
+
+func makeEdgeKey(e *model.CodeEdge) edgeKey {
+	return edgeKey{source: e.SourceID, target: e.TargetID, kind: e.Kind}
+}