feat(cache): delta-based incremental SQLite analysis cache for Go (shivasurya#649)

## Summary

Adds `AnalysisCache` backed by SQLite to speed up repeated Go call graph builds.

**Cold → warm speedup**: ~2m 39s → ~24s (**6.6×**) on 392 Go files / 39,743 call sites.

Enable with `--enable-db-cache` on `resolution-report` (scan/ci in PR-10).

## Design

**Which passes are cached:**
- Passes 2a/2b/3 (file-local): cached by content hash — always safe
- Pass 4 (cross-file): delta-based — files are replayed from cache unless dirty
- Pass 1: never cached — must run to detect what changed

**Pass 4 delta invalidation** (`NeedsPass4Rerun`): a file is dirty if:
1. No cache entry exists
2. Content hash changed
3. A resolved callee FQN was removed from the index
4. An unresolved call name matches a newly-added FQN

Warm files skip resolution entirely; cached edges replay directly into the call graph.

**Per-table schema versioning** — three constants (`fileCacheVersion`, `functionIndexVersion`, `pass4Version`) stored in the `meta` table. On version mismatch only the affected table is wiped; other tables stay warm. Project-root change wipes all.

## Test coverage

- `analysis_cache_test.go`: per-table version wipe, file-cache wipe, project-root change
- `go_builder_test.go`: cold→warm round-trip, nil cache regression, dirty-file re-resolution

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

Author: shivasurya

.github/workflows/go-thirdparty-r2-upload.yml

@@ -0,0 +1,100 @@
+name: Upload Go Third-Party Registries to R2
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      force_upload:
+        description: 'Force upload even if not a release'
+        required: false
+        default: 'false'
+
+permissions:
+  contents: read
+
+jobs:
+  upload-go-thirdparty-registries:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+          cache: false
+
+      - name: Verify Go installation
+        run: |
+          echo "Go compiler: $(go version)"
+          echo "GOPATH: $(go env GOPATH)"
+          echo "GOMODCACHE: $(go env GOMODCACHE)"
+
+      - name: Install AWS CLI
+        run: |
+          curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+          unzip -q awscliv2.zip
+          sudo ./aws/install --update
+          aws --version
+
+      - name: Generate and upload Go third-party registries
+        env:
+          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+        run: |
+          cd sast-engine/tools
+          chmod +x upload_go_thirdparty_to_r2.sh
+          ./upload_go_thirdparty_to_r2.sh
+
+      - name: Verify uploads in R2
+        env:
+          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+        run: |
+          export AWS_ACCESS_KEY_ID="${R2_ACCESS_KEY_ID}"
+          export AWS_SECRET_ACCESS_KEY="${R2_SECRET_ACCESS_KEY}"
+          R2_ENDPOINT="https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com"
+
+          echo "Verifying uploaded files in R2..."
+          aws s3 ls "s3://code-pathfinder-assets/registries/go-thirdparty/v1/manifest.json" \
+            --endpoint-url "$R2_ENDPOINT" \
+            || echo "Warning: manifest.json not found"
+
+          echo ""
+          echo "Listing uploaded files..."
+          aws s3 ls "s3://code-pathfinder-assets/registries/go-thirdparty/v1/" \
+            --endpoint-url "$R2_ENDPOINT" \
+            --summarize --human-readable
+
+      - name: Test public CDN accessibility
+        run: |
+          echo "Testing public CDN URL..."
+          URL="https://assets.codepathfinder.dev/registries/go-thirdparty/v1/manifest.json"
+          echo "Testing: $URL"
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$URL")
+          if [ "$STATUS" = "200" ]; then
+            echo "  Go third-party manifest is publicly accessible"
+            echo ""
+            echo "Manifest contents:"
+            curl -s "$URL" | python3 -c "import json,sys; m=json.load(sys.stdin); pkgs=m.get('packages',[]); print('  Schema version:  ', m.get('schema_version','unknown')); print('  Registry version:', m.get('registry_version','unknown')); print('  Generated at:    ', m.get('generated_at','unknown')); print('  Packages:        ', len(pkgs)); [print(f'    - {p[\"import_path\"]} ({p.get(\"type_count\",0)} types, {p.get(\"function_count\",0)} functions)') for p in pkgs[:5]]"
+          else
+            echo "  Go third-party manifest returned HTTP $STATUS"
+            exit 1
+          fi
+
+      - name: Summary
+        run: |
+          echo "========================================="
+          echo "Go Third-Party Registry Upload Complete"
+          echo "========================================="
+          echo ""
+          echo "Registry available at:"
+          echo "  https://assets.codepathfinder.dev/registries/go-thirdparty/v1/manifest.json"
+          echo ""
+          echo "The code-pathfinder engine will use this CDN registry for Go third-party"
+          echo "type inference. Popular packages (gin, gorm, sqlx, etc.) will resolve"
+          echo "via CDN first; project-specific deps fall back to local vendor/ parsing."

sast-engine/cmd/ci.go

@@ -281,10 +281,25 @@ Examples:
 				builder.InitGoStdlibLoader(goRegistry, projectPath, logger)
 				goTypeEngine := resolution.NewGoTypeInferenceEngine(goRegistry)
 
-				goCG, err := builder.BuildGoCallGraph(codeGraph, goRegistry, goTypeEngine, logger)
+				enableDBCache, _ := cmd.Flags().GetBool("enable-db-cache")
+				var analysisCache *builder.AnalysisCache
+				if enableDBCache {
+					var cacheErr error
+					analysisCache, cacheErr = builder.OpenAnalysisCache(projectPath)
+					if cacheErr != nil {
+						logger.Warning("Could not open analysis cache: %v — running full analysis", cacheErr)
+					} else {
+						defer analysisCache.Close()
+					}
+				}
+
+				goCG, err := builder.BuildGoCallGraph(codeGraph, goRegistry, goTypeEngine, logger, analysisCache)
 				if err != nil {
 					logger.Warning("Failed to build Go call graph: %v", err)
 				} else {
+					if analysisCache != nil {
+						logger.Progress("Cache: incremental analysis cache updated")
+					}
 					builder.MergeCallGraphs(cg, goCG)
 					logger.Statistic("Go call graph merged: %d functions, %d call sites",
 						len(goCG.Functions), countTotalCallSites(goCG))
@@ -507,5 +522,6 @@ func init() {
 	ciCmd.Flags().Int("github-pr", 0, "Pull request number for posting comments")
 	ciCmd.Flags().Bool("pr-comment", false, "Post summary comment on the pull request")
 	ciCmd.Flags().Bool("pr-inline", false, "Post inline review comments for critical/high findings")
+	ciCmd.Flags().Bool("enable-db-cache", false, "Enable SQLite-backed incremental analysis cache (experimental)")
 	ciCmd.MarkFlagRequired("project")
 }

sast-engine/cmd/ci_test.go

@@ -370,3 +370,81 @@ func TestCICmdPrepareRulesLocalOnly(t *testing.T) {
 	_, err = os.Stat(outputFile)
 	require.NoError(t, err)
 }
+
+// TestCICmdEnableDBCacheFlag verifies that the --enable-db-cache flag is
+// registered on the ci command with the correct default value.
+func TestCICmdEnableDBCacheFlag(t *testing.T) {
+	flag := ciCmd.Flags().Lookup("enable-db-cache")
+	require.NotNil(t, flag, "enable-db-cache flag should be registered on ci command")
+	assert.Equal(t, "false", flag.DefValue)
+}
+
+// TestCICmdEnableDBCacheWithGoProject verifies the --enable-db-cache code path
+// is exercised when running the ci command against a Go project.
+func TestCICmdEnableDBCacheWithGoProject(t *testing.T) {
+	projectDir, rulesFile := setupCIIntegrationTest(t)
+
+	// Add a go.mod so the ci command enters the Go analysis branch.
+	require.NoError(t, os.WriteFile(
+		filepath.Join(projectDir, "go.mod"),
+		[]byte("module example.com/test\n\ngo 1.21\n"),
+		0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(projectDir, "main.go"),
+		[]byte("package main\n\nfunc main() {}\n"),
+		0o644,
+	))
+
+	outputFile := filepath.Join(t.TempDir(), "results.sarif")
+
+	resetCIFlags()
+	ciCmd.Flags().Set("rules", rulesFile)
+	ciCmd.Flags().Set("project", projectDir)
+	ciCmd.Flags().Set("output-file", outputFile)
+	require.NoError(t, ciCmd.Flags().Set("enable-db-cache", "true"))
+	defer ciCmd.Flags().Set("enable-db-cache", "false")
+
+	// Should complete without error — the cache is created and closed.
+	err := ciCmd.RunE(ciCmd, []string{})
+	require.NoError(t, err)
+}
+
+// TestCICmdEnableDBCacheOpenError verifies that when OpenAnalysisCache fails
+// (e.g. the cache directory is blocked), the ci command logs a warning and
+// continues without error, covering ci.go lines 289-291.
+func TestCICmdEnableDBCacheOpenError(t *testing.T) {
+	projectDir, rulesFile := setupCIIntegrationTest(t)
+
+	// Add a go.mod so the ci command enters the Go analysis branch.
+	require.NoError(t, os.WriteFile(
+		filepath.Join(projectDir, "go.mod"),
+		[]byte("module example.com/test\n\ngo 1.21\n"),
+		0o644,
+	))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(projectDir, "main.go"),
+		[]byte("package main\n\nfunc main() {}\n"),
+		0o644,
+	))
+
+	// Block the pathfinder cache directory by placing a regular file where the
+	// cache directory would be created, forcing MkdirAll to fail.
+	fakeCache := t.TempDir()
+	blockFile := filepath.Join(fakeCache, "pathfinder")
+	require.NoError(t, os.WriteFile(blockFile, []byte("block"), 0o444))
+	t.Setenv("XDG_CACHE_HOME", fakeCache)
+
+	outputFile := filepath.Join(t.TempDir(), "results.sarif")
+
+	resetCIFlags()
+	ciCmd.Flags().Set("rules", rulesFile)
+	ciCmd.Flags().Set("project", projectDir)
+	ciCmd.Flags().Set("output-file", outputFile)
+	require.NoError(t, ciCmd.Flags().Set("enable-db-cache", "true"))
+	defer ciCmd.Flags().Set("enable-db-cache", "false")
+
+	// Should warn about cache failure but continue without error.
+	err := ciCmd.RunE(ciCmd, []string{})
+	require.NoError(t, err)
+}

sast-engine/cmd/resolution_report.go

@@ -35,6 +35,7 @@ Use --csv to export unresolved calls with file, line, target, and reason.`,
 		projectInput := cmd.Flag("project").Value.String()
 		csvOutput := cmd.Flag("csv").Value.String()
 		dumpJSON := cmd.Flag("dump-callsites-json").Value.String()
+		enableDBCache, _ := cmd.Flags().GetBool("enable-db-cache")
 
 		if projectInput == "" {
 			fmt.Println("Error: --project flag is required")
@@ -60,10 +61,30 @@ Use --csv to export unresolved calls with file, line, target, and reason.`,
 				builder.InitGoStdlibLoader(goRegistry, projectInput, logger)
 				builder.InitGoThirdPartyLoader(goRegistry, projectInput, false, logger)
 				goTypeEngine := resolution.NewGoTypeInferenceEngine(goRegistry)
-				goCG, goErr := builder.BuildGoCallGraph(codeGraph, goRegistry, goTypeEngine, logger)
+
+				// Open SQLite analysis cache only when --enable-db-cache is set.
+				// Disabled by default to preserve current behaviour.
+				var analysisCache *builder.AnalysisCache
+				if enableDBCache {
+					var cacheErr error
+					analysisCache, cacheErr = builder.OpenAnalysisCache(projectInput)
+					if cacheErr != nil {
+						fmt.Fprintf(os.Stderr, "  [cache] warn: could not open cache: %v — running full analysis\n", cacheErr)
+						analysisCache = nil
+					}
+					if analysisCache != nil {
+						defer analysisCache.Close()
+					}
+				}
+
+				goCG, goErr := builder.BuildGoCallGraph(codeGraph, goRegistry, goTypeEngine, logger, analysisCache)
 				if goErr == nil && goCG != nil {
 					builder.MergeCallGraphs(cg, goCG)
 				}
+
+				if enableDBCache && analysisCache != nil {
+					fmt.Println("Cache: incremental analysis cache updated")
+				}
 			}
 		}
 
@@ -910,4 +931,5 @@ func init() {
 	resolutionReportCmd.MarkFlagRequired("project")
 	resolutionReportCmd.Flags().String("csv", "", "Export unresolved calls to CSV file (e.g., --csv unresolved.csv)")
 	resolutionReportCmd.Flags().String("dump-callsites-json", "", "Export all Go call sites as JSONL for accuracy validation (e.g., --dump-callsites-json callsites.jsonl)")
+	resolutionReportCmd.Flags().Bool("enable-db-cache", false, "Enable SQLite-backed incremental analysis cache (experimental). Caches Pass 2b scopes and Pass 3 call sites per file keyed by content hash; only changed files are re-analysed on subsequent runs.")
 }

sast-engine/cmd/resolution_report_test.go

@@ -866,3 +866,49 @@ func main() {
 		resolutionReportCmd.Run(resolutionReportCmd, []string{})
 	})
 }
+
+// TestDumpCallSitesJSON verifies that dumpCallSitesJSON writes Go call site
+// records to a JSONL file and skips non-Go callers.
+func TestDumpCallSitesJSON(t *testing.T) {
+	goFunc := &graph.Node{ID: "fn", Language: "go", Name: "Fn"}
+	pyFunc := &graph.Node{ID: "pyfn", Language: "python", Name: "PyFn"}
+
+	cg := &core.CallGraph{
+		Functions: map[string]*graph.Node{
+			"example.com/pkg.Fn": goFunc,
+			"pymod.PyFn":         pyFunc,
+		},
+		CallSites: map[string][]core.CallSite{
+			"example.com/pkg.Fn": {
+				{Target: "fmt.Println", TargetFQN: "fmt.Println", Resolved: true, IsStdlib: true,
+					Location: core.Location{File: "main.go", Line: 5}},
+			},
+			"pymod.PyFn": {
+				{Target: "os.exit", Resolved: false, Location: core.Location{File: "script.py", Line: 2}},
+			},
+		},
+	}
+
+	out := filepath.Join(t.TempDir(), "callsites.jsonl")
+	err := dumpCallSitesJSON(cg, out)
+	assert.NoError(t, err)
+
+	data, err := os.ReadFile(out)
+	assert.NoError(t, err)
+	content := string(data)
+	// Only the Go call site should be written
+	assert.Contains(t, content, "fmt.Println")
+	assert.NotContains(t, content, "os.exit")
+}
+
+// TestDumpCallSitesJSON_WriteError verifies that an unwritable output path
+// returns an error from dumpCallSitesJSON.
+func TestDumpCallSitesJSON_WriteError(t *testing.T) {
+	cg := &core.CallGraph{
+		Functions: map[string]*graph.Node{},
+		CallSites: map[string][]core.CallSite{},
+	}
+	err := dumpCallSitesJSON(cg, "/nonexistent/dir/out.jsonl")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to create JSON file")
+}

sast-engine/cmd/scan.go

@@ -262,10 +262,25 @@ Examples:
 
 				goTypeEngine := resolution.NewGoTypeInferenceEngine(goRegistry)
 
-				goCG, err := builder.BuildGoCallGraph(codeGraph, goRegistry, goTypeEngine, logger)
+				enableDBCache, _ := cmd.Flags().GetBool("enable-db-cache")
+				var analysisCache *builder.AnalysisCache
+				if enableDBCache {
+					var cacheErr error
+					analysisCache, cacheErr = builder.OpenAnalysisCache(projectPath)
+					if cacheErr != nil {
+						logger.Warning("Could not open analysis cache: %v — running full analysis", cacheErr)
+					} else {
+						defer analysisCache.Close()
+					}
+				}
+
+				goCG, err := builder.BuildGoCallGraph(codeGraph, goRegistry, goTypeEngine, logger, analysisCache)
 				if err != nil {
 					logger.Warning("Failed to build Go call graph: %v", err)
 				} else {
+					if analysisCache != nil {
+						logger.Progress("Cache: incremental analysis cache updated")
+					}
 					builder.MergeCallGraphs(cg, goCG)
 					logger.Statistic("Go call graph merged: %d functions, %d call sites",
 						len(goCG.Functions), countTotalCallSites(goCG))
@@ -1052,5 +1067,6 @@ func init() {
 	scanCmd.Flags().Bool("diff-aware", false, "Enable diff-aware scanning (only report findings in changed files)")
 	scanCmd.Flags().String("base", "", "Base git ref for diff-aware scanning (required with --diff-aware)")
 	scanCmd.Flags().String("head", "HEAD", "Head git ref for diff-aware scanning")
+	scanCmd.Flags().Bool("enable-db-cache", false, "Enable SQLite-backed incremental analysis cache (experimental)")
 	scanCmd.MarkFlagRequired("project")
 }