refactor: Extract builder logic to builder/ package (#7)

This PR extracts ~1050 LOC of call graph builder logic from builder.go
into a dedicated builder/ package for better modularity and organization.

## Changes

### New Files Created

1. **builder/cache.go** (100 LOC)
   - ImportMapCache for thread-safe import map caching
   - Comprehensive tests with concurrent access validation

2. **builder/builder.go** (800 LOC)
   - BuildCallGraph - main orchestration function
   - indexFunctions, getFunctionsInFile, findContainingFunction
   - resolveCallTarget - core resolution logic with type inference
   - validateStdlibFQN, validateFQN - validation functions
   - detectPythonVersion - Python version detection
   - All functions have public wrappers for external use

3. **builder/helpers.go** (50 LOC)
   - ReadFileBytes - file reading utility
   - FindFunctionAtLine - AST traversal for function lookup

4. **builder/taint.go** (80 LOC)
   - GenerateTaintSummaries - taint analysis (Pass 5)

5. **builder/integration.go** (50 LOC)
   - BuildCallGraphFromPath - convenience function for 3-pass build

6. **builder/doc.go** (60 LOC)
   - Package documentation with usage examples

### Files Modified

1. **graph/callgraph/builder.go** - Backward compatibility layer
   - Type aliases for ImportMapCache
   - Wrapper functions delegating to builder package
   - All wrappers marked as Deprecated with migration path

2. **graph/callgraph/integration.go** - Simplified
   - Now uses builder.BuildCallGraphFromPath
   - Maintains same public API

3. **graph/callgraph/python_version_detector.go** - Simplified
   - Delegates to builder.DetectPythonVersion

### Files Removed

1. **cache_test.go** - Moved to builder/cache_test.go
2. **python_version_detector_test.go** - Tests moved to builder package

## Testing

✅ All tests pass (18 packages)
✅ Build succeeds (gradle buildGo)
✅ Lint passes (0 issues)
✅ Zero breaking changes - backward compatibility maintained

## Architecture

The builder package now contains all call graph construction logic:
- Pass 1: Module registry (registry package)
- Pass 2: Import extraction (resolution package)
- Pass 3: Call graph building (builder package) ← This PR
- Pass 4: Type inference integration
- Pass 5: Taint analysis

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: shivasurya

sourcecode-parser/graph/callgraph/builder.go

@@ -0,0 +1,88 @@
+package builder
+
+import (
+	"sync"
+
+	"github.com/shivasurya/code-pathfinder/sourcecode-parser/graph/callgraph/core"
+	"github.com/shivasurya/code-pathfinder/sourcecode-parser/graph/callgraph/resolution"
+)
+
+// ImportMapCache provides thread-safe caching of ImportMap instances.
+// It prevents redundant import extraction by caching results keyed by file path.
+//
+// Thread-safety:
+//   - All methods are safe for concurrent use
+//   - Uses RWMutex for optimized read-heavy workloads
+//   - GetOrExtract handles double-checked locking pattern
+type ImportMapCache struct {
+	cache map[string]*core.ImportMap // Maps file path to ImportMap
+	mu    sync.RWMutex                // Protects cache map
+}
+
+// NewImportMapCache creates a new empty import map cache.
+func NewImportMapCache() *ImportMapCache {
+	return &ImportMapCache{
+		cache: make(map[string]*core.ImportMap),
+	}
+}
+
+// Get retrieves an ImportMap from the cache if it exists.
+//
+// Parameters:
+//   - filePath: absolute path to the Python file
+//
+// Returns:
+//   - ImportMap and true if found in cache, nil and false otherwise
+func (c *ImportMapCache) Get(filePath string) (*core.ImportMap, bool) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	importMap, ok := c.cache[filePath]
+	return importMap, ok
+}
+
+// Put stores an ImportMap in the cache.
+//
+// Parameters:
+//   - filePath: absolute path to the Python file
+//   - importMap: the extracted ImportMap to cache
+func (c *ImportMapCache) Put(filePath string, importMap *core.ImportMap) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.cache[filePath] = importMap
+}
+
+// GetOrExtract retrieves an ImportMap from cache or extracts it if not cached.
+// This is the main entry point for using the cache.
+//
+// Parameters:
+//   - filePath: absolute path to the Python file
+//   - sourceCode: file contents (only used if extraction needed)
+//   - registry: module registry for resolving imports
+//
+// Returns:
+//   - ImportMap from cache or newly extracted
+//   - error if extraction fails (cache misses only)
+//
+// Thread-safety:
+//   - Multiple goroutines can safely call GetOrExtract concurrently
+//   - First caller for a file will extract and cache
+//   - Subsequent callers will get cached result
+func (c *ImportMapCache) GetOrExtract(filePath string, sourceCode []byte, registry *core.ModuleRegistry) (*core.ImportMap, error) {
+	// Try to get from cache (fast path with read lock)
+	if importMap, ok := c.Get(filePath); ok {
+		return importMap, nil
+	}
+
+	// Cache miss - extract imports (expensive operation)
+	importMap, err := resolution.ExtractImports(filePath, sourceCode, registry)
+	if err != nil {
+		return nil, err
+	}
+
+	// Store in cache for future use
+	c.Put(filePath, importMap)
+
+	return importMap, nil
+}

sourcecode-parser/graph/callgraph/builder/builder.go

@@ -0,0 +1,173 @@
+package builder
+
+import (
+	"sync"
+	"testing"
+
+	"github.com/shivasurya/code-pathfinder/sourcecode-parser/graph/callgraph/core"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewImportMapCache(t *testing.T) {
+	cache := NewImportMapCache()
+	assert.NotNil(t, cache)
+	assert.NotNil(t, cache.cache)
+	assert.Empty(t, cache.cache)
+}
+
+func TestImportMapCache_GetPut(t *testing.T) {
+	cache := NewImportMapCache()
+	filePath := "/test/file.py"
+
+	// Initially should not exist
+	importMap, ok := cache.Get(filePath)
+	assert.False(t, ok)
+	assert.Nil(t, importMap)
+
+	// Put an ImportMap
+	expectedImportMap := core.NewImportMap(filePath)
+	expectedImportMap.AddImport("os", "os")
+	cache.Put(filePath, expectedImportMap)
+
+	// Should now exist
+	importMap, ok = cache.Get(filePath)
+	assert.True(t, ok)
+	assert.Equal(t, expectedImportMap, importMap)
+}
+
+func TestImportMapCache_GetOrExtract_CacheHit(t *testing.T) {
+	cache := NewImportMapCache()
+	filePath := "/test/file.py"
+
+	// Pre-populate cache
+	expectedImportMap := core.NewImportMap(filePath)
+	expectedImportMap.AddImport("sys", "sys")
+	cache.Put(filePath, expectedImportMap)
+
+	// GetOrExtract should return cached value without calling ExtractImports
+	importMap, err := cache.GetOrExtract(filePath, nil, nil)
+	assert.NoError(t, err)
+	assert.Equal(t, expectedImportMap, importMap)
+}
+
+func TestImportMapCache_GetOrExtract_CacheMiss(t *testing.T) {
+	cache := NewImportMapCache()
+	filePath := "/test/file.py"
+
+	// Simple Python code with imports
+	sourceCode := []byte(`import os
+import sys
+from pathlib import Path
+`)
+
+	registry := core.NewModuleRegistry()
+
+	// GetOrExtract should extract and cache
+	importMap, err := cache.GetOrExtract(filePath, sourceCode, registry)
+	require.NoError(t, err)
+	assert.NotNil(t, importMap)
+
+	// Should now be in cache
+	cachedImportMap, ok := cache.Get(filePath)
+	assert.True(t, ok)
+	assert.Equal(t, importMap, cachedImportMap)
+}
+
+func TestImportMapCache_ConcurrentAccess(t *testing.T) {
+	cache := NewImportMapCache()
+	filePath := "/test/file.py"
+
+	sourceCode := []byte(`import os`)
+	registry := core.NewModuleRegistry()
+
+	const numGoroutines = 100
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines)
+
+	results := make([]*core.ImportMap, numGoroutines)
+
+	// Multiple goroutines try to get/extract concurrently
+	for i := 0; i < numGoroutines; i++ {
+		go func(index int) {
+			defer wg.Done()
+			importMap, err := cache.GetOrExtract(filePath, sourceCode, registry)
+			assert.NoError(t, err)
+			results[index] = importMap
+		}(i)
+	}
+
+	wg.Wait()
+
+	// All results should be non-nil
+	for i := 0; i < numGoroutines; i++ {
+		assert.NotNil(t, results[i])
+	}
+
+	// All should point to the same cached instance
+	firstResult := results[0]
+	for i := 1; i < numGoroutines; i++ {
+		assert.Equal(t, firstResult, results[i], "Result %d should match first result", i)
+	}
+}
+
+func TestImportMapCache_ConcurrentPut(t *testing.T) {
+	cache := NewImportMapCache()
+
+	const numGoroutines = 50
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines)
+
+	// Multiple goroutines put different files concurrently
+	for i := 0; i < numGoroutines; i++ {
+		go func(index int) {
+			defer wg.Done()
+			filePath := "/test/file" + string(rune('0'+index)) + ".py"
+			importMap := core.NewImportMap(filePath)
+			cache.Put(filePath, importMap)
+		}(i)
+	}
+
+	wg.Wait()
+
+	// All files should be in cache
+	for i := 0; i < numGoroutines; i++ {
+		filePath := "/test/file" + string(rune('0'+i)) + ".py"
+		importMap, ok := cache.Get(filePath)
+		assert.True(t, ok, "File %d should be in cache", i)
+		assert.NotNil(t, importMap)
+	}
+}
+
+func TestImportMapCache_MultiplePutsForSameFile(t *testing.T) {
+	cache := NewImportMapCache()
+	filePath := "/test/file.py"
+
+	// First put
+	importMap1 := core.NewImportMap(filePath)
+	importMap1.AddImport("os", "os")
+	cache.Put(filePath, importMap1)
+
+	// Second put should replace
+	importMap2 := core.NewImportMap(filePath)
+	importMap2.AddImport("sys", "sys")
+	cache.Put(filePath, importMap2)
+
+	// Should get the second one
+	retrieved, ok := cache.Get(filePath)
+	assert.True(t, ok)
+	assert.Equal(t, importMap2, retrieved)
+	assert.NotEqual(t, importMap1, retrieved)
+}
+
+func TestImportMapCache_EmptyFilePath(t *testing.T) {
+	cache := NewImportMapCache()
+
+	// Empty file path should work (edge case)
+	importMap := core.NewImportMap("")
+	cache.Put("", importMap)
+
+	retrieved, ok := cache.Get("")
+	assert.True(t, ok)
+	assert.Equal(t, importMap, retrieved)
+}

sourcecode-parser/graph/callgraph/builder/cache.go

@@ -0,0 +1,53 @@
+// Package builder provides call graph construction orchestration.
+//
+// This package ties together all components to build a complete call graph:
+//   - Module registry (registry package)
+//   - Type inference (resolution package)
+//   - Import resolution (resolution package)
+//   - Call site extraction (extraction package)
+//   - Advanced resolution (resolution package)
+//   - Pattern detection (patterns package)
+//   - Taint analysis (analysis/taint package)
+//
+// # Basic Usage
+//
+//	// Build from existing code graph
+//	callGraph, err := builder.BuildCallGraph(codeGraph, moduleRegistry, projectRoot)
+//
+// # Call Resolution Strategy
+//
+// The builder uses a multi-strategy approach to resolve function calls:
+//  1. Direct import resolution
+//  2. Method chaining with type inference
+//  3. Self-attribute resolution (self.attr.method)
+//  4. Type inference for variable.method() calls
+//  5. ORM pattern detection (Django, SQLAlchemy)
+//  6. Framework detection (known external frameworks)
+//  7. Standard library resolution via remote CDN
+//
+// Each strategy is tried in order until one succeeds.
+//
+// # Multi-Pass Architecture
+//
+// The builder performs multiple passes over the codebase:
+//
+//  Pass 1: Index all function definitions
+//  Pass 2: Extract return types from all functions
+//  Pass 3: Extract variable assignments and type bindings
+//  Pass 4: Extract class attributes
+//  Pass 5: Resolve call sites and build call graph edges
+//  Pass 6: Generate taint summaries for security analysis
+//
+// This multi-pass approach ensures that all necessary type information
+// is collected before attempting to resolve call sites.
+//
+// # Caching
+//
+// The builder uses ImportMapCache to avoid re-parsing imports from
+// the same file multiple times, significantly improving performance.
+//
+// # Thread Safety
+//
+// All exported functions in this package are thread-safe. The ImportMapCache
+// uses a read-write mutex to allow concurrent reads while ensuring safe writes.
+package builder

sourcecode-parser/graph/callgraph/builder/cache_test.go

@@ -0,0 +1,58 @@
+package builder
+
+import (
+	"os"
+	"path/filepath"
+
+	sitter "github.com/smacker/go-tree-sitter"
+)
+
+// ReadFileBytes reads a file and returns its contents as a byte slice.
+// Helper function for reading source code.
+//
+// Parameters:
+//   - filePath: path to the file (can be relative or absolute)
+//
+// Returns:
+//   - File contents as byte slice
+//   - error if file cannot be read
+func ReadFileBytes(filePath string) ([]byte, error) {
+	absPath, err := filepath.Abs(filePath)
+	if err != nil {
+		return nil, err
+	}
+	return os.ReadFile(absPath)
+}
+
+// FindFunctionAtLine searches for a function definition at the specified line number.
+// Returns the tree-sitter node for the function, or nil if not found.
+//
+// This function recursively traverses the AST tree to find a function or method
+// definition node at the given line number.
+//
+// Parameters:
+//   - root: the root tree-sitter node to search from
+//   - lineNumber: the line number to search for (1-indexed)
+//
+// Returns:
+//   - tree-sitter node for the function definition, or nil if not found
+func FindFunctionAtLine(root *sitter.Node, lineNumber uint32) *sitter.Node {
+	if root == nil {
+		return nil
+	}
+
+	// Check if this node is a function definition at the target line
+	if (root.Type() == "function_definition" || root.Type() == "method_declaration") &&
+		root.StartPoint().Row+1 == lineNumber {
+		return root
+	}
+
+	// Recursively search children
+	for i := 0; i < int(root.ChildCount()); i++ {
+		if result := FindFunctionAtLine(root.Child(i), lineNumber); result != nil {
+			return result
+		}
+	}
+
+	return nil
+}