feat(scan): per-CVE reachability assessment tracking + scan summary line

- Track ReachabilityAssessed / ReachabilityQueryHashes per EnrichedVuln so the
  CLI knows which CVEs tree-sitter actually evaluated (vs. no-data)
- Only forward UNREACHABLE rows to the snapshot when reachability was actually
  assessed; stop manufacturing UNREACHABLE/SEMANTIC rows with no evidence
- Attach query hashes and routine/file/module evidence JSON to forwarded rows
- Extract pure, unit-tested buildReachabilityPayloads from postReachabilityToSnapshot
- Print a "Reachability: N assessed, R reachable, ..." line in the pretty scan
  summary when reachability ran

Author: 0x73746F66

cmd/cli_sca.go

@@ -13,6 +13,7 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/hex"
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -307,22 +308,9 @@ func introducedViaChain(p scan.ScopedPackage, key string, manifestGroups []scan.
 //
 // Memory-yaml VEX hints are attached so user-authored decisions win over the
 // auto-computed verdict.
-func postReachabilityToSnapshot(client *vdb.Client, env vdb.CliEnv, snapshot *vdb.CliIngestionSnapshot, persisted []vdb.CliFindingResult, enriched []scan.EnrichedVuln, gitCtx *gitctx.GitContext) {
-	if snapshot == nil || len(enriched) == 0 {
-		return
-	}
-
-	// Map (cveId|packageName|packageVer) → findingUuid for fast lookup.
-	findingByKey := make(map[string]vdb.CliFindingResult, len(persisted))
-	for _, f := range persisted {
-		k := f.FindingID + "|" + f.PackageName + "|" + f.PackageVersion
-		findingByKey[k] = f
-	}
-
-	// Memory-yaml lookup — best-effort. The CLI already merges this into
-	// enriched but we need the raw status fields to forward upstream.
-	memRecords := loadMemoryRecords(gitCtx)
-
+// buildReachabilityPayloads turns enriched vulns into CliReachabilityPayload
+// rows. It is pure (no side effects, no network) so it is unit-testable.
+func buildReachabilityPayloads(enriched []scan.EnrichedVuln, findingByKey map[string]vdb.CliFindingResult, memRecords map[string]memory.FindingRecord) []vdb.CliReachabilityPayload {
 	payloads := make([]vdb.CliReachabilityPayload, 0, len(enriched)*2)
 	for _, ev := range enriched {
 		fkey := ev.CveID + "|" + ev.PackageName + "|" + ev.PackageVer
@@ -349,21 +337,19 @@ func postReachabilityToSnapshot(client *vdb.Client, env vdb.CliEnv, snapshot *vd
 
 		switch ev.Reachability {
 		case "direct", "transitive":
-			// Tree-sitter verdict — emit one row per affected routine if any.
 			row := base
 			row.Source = "TREE_SITTER"
 			row.Verdict = strings.ToUpper(ev.Reachability)
-			if len(ev.AffectedSymbols.Routines) > 0 {
+			if ev.AffectedSymbols != nil && len(ev.AffectedSymbols.Routines) > 0 {
 				row.MatchedRoutine = ev.AffectedSymbols.Routines[0]
 			}
+			if len(ev.ReachabilityQueryHashes) > 0 {
+				row.QueryHash = ev.ReachabilityQueryHashes[0]
+			}
 			payloads = append(payloads, row)
 		case "semantic":
-			// Symbol-fallback hits — one row per match.
 			if len(ev.SemanticMatches) == 0 {
-				row := base
-				row.Source = "SYMBOL_FALLBACK"
-				row.Verdict = "SEMANTIC"
-				payloads = append(payloads, row)
+				break
 			}
 			for _, m := range ev.SemanticMatches {
 				row := base
@@ -374,15 +360,47 @@ func postReachabilityToSnapshot(client *vdb.Client, env vdb.CliEnv, snapshot *vd
 				row.MatchStartLine = m.Line
 				payloads = append(payloads, row)
 			}
-		default:
-			// No reachability verdict — treat as UNREACHABLE so the server
-			// records a not_affected/code_not_reachable VEX statement.
+		case "unreachable":
+			if !ev.ReachabilityAssessed {
+				break
+			}
 			row := base
 			row.Source = "TREE_SITTER"
 			row.Verdict = "UNREACHABLE"
+			if len(ev.ReachabilityQueryHashes) > 0 {
+				row.QueryHash = ev.ReachabilityQueryHashes[0]
+			}
+			if ev.AffectedSymbols != nil && (len(ev.AffectedSymbols.Routines) > 0 || len(ev.AffectedSymbols.Files) > 0 || len(ev.AffectedSymbols.Modules) > 0) {
+				evidence := map[string]any{
+					"routines": ev.AffectedSymbols.Routines,
+					"files":    ev.AffectedSymbols.Files,
+					"modules":  ev.AffectedSymbols.Modules,
+				}
+				if b, err := json.Marshal(evidence); err == nil {
+					row.EvidenceJSON = string(b)
+				}
+			}
 			payloads = append(payloads, row)
+		default:
+			// Empty / unassessed — emit no row.
 		}
 	}
+	return payloads
+}
+
+func postReachabilityToSnapshot(client *vdb.Client, env vdb.CliEnv, snapshot *vdb.CliIngestionSnapshot, persisted []vdb.CliFindingResult, enriched []scan.EnrichedVuln, gitCtx *gitctx.GitContext) {
+	if snapshot == nil || len(enriched) == 0 {
+		return
+	}
+
+	findingByKey := make(map[string]vdb.CliFindingResult, len(persisted))
+	for _, f := range persisted {
+		k := f.FindingID + "|" + f.PackageName + "|" + f.PackageVersion
+		findingByKey[k] = f
+	}
+
+	memRecords := loadMemoryRecords(gitCtx)
+	payloads := buildReachabilityPayloads(enriched, findingByKey, memRecords)
 
 	if len(payloads) == 0 {
 		return
@@ -608,6 +626,19 @@ func runReachabilityForFindings(hits []vdb.CliReachabilityHit, enriched []scan.E
 
 	for i := range enriched {
 		cve := enriched[i].CveID
+		if evaluatedCVEs[cve] {
+			enriched[i].ReachabilityAssessed = true
+		}
+		// Collect query hashes for this CVE
+		var hashes []string
+		for _, e := range byHash {
+			if e.cves[cve] {
+				hashes = append(hashes, e.query.QueryHash)
+			}
+		}
+		if len(hashes) > 0 {
+			enriched[i].ReachabilityQueryHashes = hashes
+		}
 		switch {
 		case reachableCVEs[cve]:
 			enriched[i].Reachability = "transitive"

cmd/cli_sca_reachability_test.go

@@ -0,0 +1,139 @@
+package cmd
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/vulnetix/cli/v3/internal/memory"
+	"github.com/vulnetix/cli/v3/internal/scan"
+	"github.com/vulnetix/cli/v3/pkg/vdb"
+)
+
+func TestBuildReachabilityPayloads_EmptyReachabilityEmitsNoRow(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{VulnFinding: scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"}, Reachability: ""},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, nil)
+	assert.Empty(t, payloads, "empty reachability should emit no row")
+}
+
+func TestBuildReachabilityPayloads_UnreachableAssessedEmitsRowWithQueryHash(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{
+			VulnFinding:  scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"},
+			Reachability: "unreachable", ReachabilityAssessed: true,
+			ReachabilityQueryHashes: []string{"abc123"},
+		},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, nil)
+	assert.Len(t, payloads, 1)
+	assert.Equal(t, "UNREACHABLE", payloads[0].Verdict)
+	assert.Equal(t, "TREE_SITTER", payloads[0].Source)
+	assert.Equal(t, "abc123", payloads[0].QueryHash)
+}
+
+func TestBuildReachabilityPayloads_UnreachableNotAssessedEmitsNoRow(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{
+			VulnFinding:  scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"},
+			Reachability: "unreachable", ReachabilityAssessed: false,
+		},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, nil)
+	assert.Empty(t, payloads, "unreachable without assessed flag should emit no row")
+}
+
+func TestBuildReachabilityPayloads_MemoryVexWithEmptyReachabilityEmitsNoRow(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{
+			VulnFinding:  scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"},
+			Reachability: "",
+		},
+	}
+	memRecords := map[string]memory.FindingRecord{
+		"CVE-2024-0001": {Status: "not_affected", Justification: "vulnerable_code_not_present", Package: "lodash"},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, memRecords)
+	assert.Empty(t, payloads, "memory VEX + empty reachability should not manufacture UNREACHABLE row")
+}
+
+func TestBuildReachabilityPayloads_SemanticWithMatchesEmitsRows(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{
+			VulnFinding:  scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"},
+			Reachability: "semantic",
+			SemanticMatches: []scan.SemanticMatch{
+				{File: "src/app.js", Line: 42, Symbol: "merge", Kind: "routine"},
+			},
+		},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, nil)
+	assert.Len(t, payloads, 1)
+	assert.Equal(t, "SEMANTIC", payloads[0].Verdict)
+	assert.Equal(t, "SEMANTIC_GREP", payloads[0].Source)
+	assert.Equal(t, "src/app.js", payloads[0].MatchedFile)
+	assert.Equal(t, "merge", payloads[0].MatchedRoutine)
+	assert.Equal(t, 42, payloads[0].MatchStartLine)
+}
+
+func TestBuildReachabilityPayloads_SemanticEmptyMatchesEmitsNoRow(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{
+			VulnFinding:     scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"},
+			Reachability:    "semantic",
+			SemanticMatches: []scan.SemanticMatch{},
+		},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, nil)
+	assert.Empty(t, payloads, "semantic with no matches should emit no row")
+}
+
+func TestBuildReachabilityPayloads_DirectEmitsRow(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{
+			VulnFinding:             scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"},
+			Reachability:            "direct",
+			ReachabilityAssessed:    true,
+			ReachabilityQueryHashes: []string{"hash1"},
+			AffectedSymbols: &scan.AffectedSymbols{
+				Routines: []string{"merge"},
+			},
+		},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, nil)
+	assert.Len(t, payloads, 1)
+	assert.Equal(t, "DIRECT", payloads[0].Verdict)
+	assert.Equal(t, "TREE_SITTER", payloads[0].Source)
+	assert.Equal(t, "hash1", payloads[0].QueryHash)
+	assert.Equal(t, "merge", payloads[0].MatchedRoutine)
+}
+
+func TestBuildReachabilityPayloads_FindingUuidLookup(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{VulnFinding: scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"}, Reachability: "transitive", ReachabilityAssessed: true},
+	}
+	findingByKey := map[string]vdb.CliFindingResult{
+		"CVE-2024-0001|lodash|4.17.20": {FindingUuid: "find-uuid-1", Purl: "pkg:npm/lodash@4.17.20"},
+	}
+	payloads := buildReachabilityPayloads(enriched, findingByKey, nil)
+	assert.Len(t, payloads, 1)
+	assert.Equal(t, "find-uuid-1", payloads[0].FindingUuid)
+	assert.Equal(t, "pkg:npm/lodash@4.17.20", payloads[0].Purl)
+}
+
+func TestBuildReachabilityPayloads_MemoryVexForwardedOnRow(t *testing.T) {
+	enriched := []scan.EnrichedVuln{
+		{
+			VulnFinding:  scan.VulnFinding{CveID: "CVE-2024-0001", PackageName: "lodash", PackageVer: "4.17.20"},
+			Reachability: "transitive", ReachabilityAssessed: true,
+		},
+	}
+	memRecords := map[string]memory.FindingRecord{
+		"CVE-2024-0001": {Status: "not_affected", Justification: "vulnerable_code_not_present", ActionResponse: "upgrade", Package: "lodash"},
+	}
+	payloads := buildReachabilityPayloads(enriched, nil, memRecords)
+	assert.Len(t, payloads, 1)
+	assert.Equal(t, "not_affected", payloads[0].MemoryVexStatus)
+	assert.Equal(t, "vulnerable_code_not_present", payloads[0].MemoryVexJustification)
+	assert.Equal(t, "upgrade", payloads[0].MemoryVexAction)
+}

cmd/scan.go

@@ -2347,6 +2347,13 @@ func printPrettyScanSummary(
 	totalPkgs := len(countUniqueMap(allPackages))
 	summary := fmt.Sprintf("  %d packages | %s", totalPkgs, pluralise("vulnerability", totalVulns))
 	fmt.Fprintln(os.Stdout, display.Bold(t, summary))
+
+	// Reachability summary (only when reachability ran).
+	if anyReachabilityAssessed(enrichedVulns) {
+		assessed, reachable, notReachable, notAssessable := countReachability(enrichedVulns)
+		fmt.Fprintf(os.Stdout, "  Reachability: %d assessed, %d reachable, %d not reachable, %d not assessable/no data\n",
+			assessed, reachable, notReachable, notAssessable)
+	}
 	fmt.Fprintln(os.Stdout)
 
 	// Artefact paths.
@@ -2361,6 +2368,38 @@ func printPrettyScanSummary(
 	fmt.Fprintln(os.Stdout)
 }
 
+// anyReachabilityAssessed returns true if any vuln has ReachabilityAssessed set.
+func anyReachabilityAssessed(vulns []scan.EnrichedVuln) bool {
+	for _, v := range vulns {
+		if v.ReachabilityAssessed {
+			return true
+		}
+	}
+	return false
+}
+
+// countReachability returns (assessed, reachable, notReachable, notAssessable)
+// across all vulns. A vuln is "assessed" when ReachabilityAssessed is true and
+// the verdict is reachable or unreachable. Unassessed counts as notAssessable.
+func countReachability(vulns []scan.EnrichedVuln) (assessed, reachable, notReachable, notAssessable int) {
+	for _, v := range vulns {
+		if !v.ReachabilityAssessed {
+			notAssessable++
+			continue
+		}
+		assessed++
+		switch v.Reachability {
+		case "direct", "transitive", "semantic":
+			reachable++
+		case "unreachable":
+			notReachable++
+		default:
+			notAssessable++
+		}
+	}
+	return
+}
+
 // printCollapsedActions deduplicates actions and collapses groups that share a
 // common prefix (e.g., "Apply Red Hat patch RHSA-2024:XXXX" × 33 → one line
 // listing all advisory IDs).

internal/scan/enrich.go

@@ -72,6 +72,14 @@ type EnrichedVuln struct {
 	//   empty         — no analysis was performed (no data to compare).
 	Reachability string
 
+	// ReachabilityAssessed is true when tree-sitter queries actually ran
+	// for this CVE (i.e. the CVE was in the evaluated set).
+	ReachabilityAssessed bool
+
+	// ReachabilityQueryHashes are the query hashes that ran for this CVE.
+	// Populated when ReachabilityAssessed is true.
+	ReachabilityQueryHashes []string
+
 	// AffectedSymbols is the symbol-level fallback returned by the API for
 	// every tier. Populated whether or not tree-sitter queries existed.
 	AffectedSymbols *AffectedSymbols