@oculum/scanner 1.0.12 → 1.0.13

package/src/{layer3/anthropic → validate}/providers/anthropic.ts

@@ -4,18 +4,16 @@
  * Validation using Anthropic Claude 3.5 Haiku model.
  */
 
-import type { Vulnerability, ScanFile, ValidationStatus } from '../../../types'
-import type { ProjectContext } from '../../../utils/project-context-builder'
-import { buildProjectContext } from '../../../utils/project-context-builder'
+import type { Vulnerability, ScanFile, ValidationStatus } from '../../shared/types'
+import type { ContextEngineResult } from '../../model/taint-types'
+import type { ProjectContext } from '../../model/project-context'
+import { buildProjectContext } from '../../model/project-context'
 import type { ValidationStats, AIValidationResult } from '../types'
 import { getAnthropicClient, HAIKU_PRICING, FILES_PER_API_BATCH } from '../clients'
 import { makeAnthropicRequestWithRetry } from '../utils/retry'
 import { parseMultiFileValidationResponse, parseValidationResponse, applyValidationResults } from '../utils/response-parser'
 import { buildMultiFileValidationRequest } from '../request-builder'
-import { HIGH_CONTEXT_VALIDATION_PROMPT } from '../prompts/validation'
-
-// Cache for project context (built once per scan)
-let cachedProjectContext: ProjectContext | null = null
+import { assembleValidationPrompt } from '../prompts/validation'
 
 /**
  * Validate findings using Anthropic Claude 3.5 Haiku
@@ -23,18 +21,20 @@ let cachedProjectContext: ProjectContext | null = null
 export async function validateWithAnthropic(
   findings: Vulnerability[],
   files: ScanFile[],
-  projectContext: ProjectContext | undefined,
+  ceResult: ContextEngineResult | undefined,
   stats: ValidationStats,
   onProgress?: (progress: { filesProcessed: number; totalFiles: number; status: string }) => void
 ): Promise<AIValidationResult> {
   console.log('[AI Validation] Initializing Anthropic client...')
   const client = getAnthropicClient()
 
-  // Build or use cached project context
-  const context = projectContext || cachedProjectContext || buildProjectContext(files)
-  if (!projectContext && !cachedProjectContext) {
-    cachedProjectContext = context
-    console.log('[AI Validation] Built project context:', {
+  // Extract project context from CE result or build from scratch
+  const context: ProjectContext = ceResult?.projectContext ?? buildProjectContext(files)
+  const fileTaintAnalyses = ceResult?.fileTaintAnalyses
+  const routeMap = ceResult?.routeMap
+  const frameworkAnalyses = ceResult?.frameworkAnalyses
+  if (!ceResult) {
+    console.log('[AI Validation] No ContextEngineResult provided, built project context from scratch:', {
       hasAuthMiddleware: context.auth.hasGlobalMiddleware,
       authProvider: context.auth.authProvider,
       orm: context.dataAccess.orm,
@@ -114,21 +114,32 @@ export async function validateWithAnthropic(
     const batchStartTime = Date.now()
 
     try {
-      // Build multi-file validation request
+      // Build multi-file validation request with scoped context, taint data, and route map
       const validationRequest = buildMultiFileValidationRequest(
         fileDataList.map(({ file, findings }) => ({ file, findings })),
-        context
+        context,
+        { contextMode: 'scoped' },
+        fileTaintAnalyses,
+        routeMap,
+        ceResult?.crossFileTaintPaths,
+        frameworkAnalyses
       )
 
+      // Assemble category-aware prompt for this batch
+      const batchCategories = [...new Set(
+        fileBatch.flatMap(([, fileFindings]) => fileFindings.map(f => f.category))
+      )]
+      const systemPrompt = assembleValidationPrompt(batchCategories)
+
       // Use Anthropic prompt caching with multi-file request
       const response = await makeAnthropicRequestWithRetry(() =>
         client.messages.create({
           model: 'claude-3-5-haiku-20241022',
-          max_tokens: 1500, // Reduced from 4096 - optimized format needs less output
+          max_tokens: 16384, // Must accommodate 8 files × multiple findings with full validation fields
           system: [
             {
               type: 'text',
-              text: HIGH_CONTEXT_VALIDATION_PROMPT,
+              text: systemPrompt,
               cache_control: { type: 'ephemeral' }, // Cache for 5 minutes
             },
           ],
@@ -296,15 +307,5 @@ export async function validateWithAnthropic(
   console.log(`    - Output: ${stats.estimatedOutputTokens.toLocaleString()} tokens`)
   console.log(`  - Estimated cost: $${stats.estimatedCost.toFixed(4)}`)
 
-  // Clear cache after validation complete
-  cachedProjectContext = null
-
   return { vulnerabilities: validatedFindings, stats }
 }
-
-/**
- * Clear cached project context (called after validation complete)
- */
-export function clearAnthropicCache(): void {
-  cachedProjectContext = null
-}

package/src/validate/providers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * AI Providers Index
+ *
+ * Re-exports all AI provider implementations.
+ */
+
+export { validateWithOpenAI } from './openai'
+export { validateWithAnthropic } from './anthropic'

package/src/{layer3/anthropic → validate}/providers/openai.ts

@@ -4,19 +4,17 @@
  * Validation using OpenAI GPT-5-mini model.
  */
 
-import type { Vulnerability, ScanFile, ValidationStatus } from '../../../types'
-import type { ProjectContext } from '../../../utils/project-context-builder'
-import { buildProjectContext } from '../../../utils/project-context-builder'
+import type { Vulnerability, ScanFile, ValidationStatus } from '../../shared/types'
+import type { ContextEngineResult } from '../../model/taint-types'
+import type { ProjectContext } from '../../model/project-context'
+import { buildProjectContext } from '../../model/project-context'
 import type { ValidationStats, AIValidationResult, StatsAccumulator } from '../types'
 import { createStatsAccumulator } from '../types'
 import { getOpenAIClient, GPT5_MINI_PRICING, FILES_PER_API_BATCH, PARALLEL_API_BATCHES } from '../clients'
 import { makeOpenAIRequestWithRetry } from '../utils/retry'
 import { parseMultiFileValidationResponse, parseValidationResponse, applyValidationResults } from '../utils/response-parser'
 import { buildMultiFileValidationRequest } from '../request-builder'
-import { HIGH_CONTEXT_VALIDATION_PROMPT } from '../prompts/validation'
-
-// Cache for project context (built once per scan)
-let cachedProjectContext: ProjectContext | null = null
+import { assembleValidationPrompt } from '../prompts/validation'
 
 /**
  * Validate findings using OpenAI GPT-5-mini
@@ -25,16 +23,18 @@ let cachedProjectContext: ProjectContext | null = null
 export async function validateWithOpenAI(
   findings: Vulnerability[],
   files: ScanFile[],
-  projectContext: ProjectContext | undefined,
+  ceResult: ContextEngineResult | undefined,
   stats: ValidationStats
 ): Promise<AIValidationResult> {
   const client = getOpenAIClient()
 
-  // Build or use cached project context
-  const context = projectContext || cachedProjectContext || buildProjectContext(files)
-  if (!projectContext && !cachedProjectContext) {
-    cachedProjectContext = context
-    console.log('[OpenAI Validation] Built project context:', {
+  // Extract project context from CE result or build from scratch
+  const context: ProjectContext = ceResult?.projectContext ?? buildProjectContext(files)
+  const fileTaintAnalyses = ceResult?.fileTaintAnalyses
+  const routeMap = ceResult?.routeMap
+  const frameworkAnalyses = ceResult?.frameworkAnalyses
+  if (!ceResult) {
+    console.log('[OpenAI Validation] No ContextEngineResult provided, built project context from scratch:', {
       hasAuthMiddleware: context.auth.hasGlobalMiddleware,
       authProvider: context.auth.authProvider,
       orm: context.dataAccess.orm,
@@ -109,21 +109,32 @@ export async function validateWithOpenAI(
     }
 
     try {
-      // Build multi-file validation request
+      // Build multi-file validation request with scoped context, taint data, and route map
       const validationRequest = buildMultiFileValidationRequest(
         fileDataList.map(({ file, findings: fileFindings }) => ({ file, findings: fileFindings })),
-        context
+        context,
+        { contextMode: 'scoped' },
+        fileTaintAnalyses,
+        routeMap,
+        ceResult?.crossFileTaintPaths,
+        frameworkAnalyses
       )
 
+      // Assemble category-aware prompt for this batch
+      const batchCategories = [...new Set(
+        fileDataList.flatMap(({ findings: fileFindings }) => fileFindings.map(f => f.category))
+      )]
+      const systemPrompt = assembleValidationPrompt(batchCategories)
+
       // Call OpenAI GPT-5-mini with retry logic
       const response = await makeOpenAIRequestWithRetry(async () =>
         client.chat.completions.create({
           model: 'gpt-5-mini-2025-08-07',
           messages: [
-            { role: 'system', content: HIGH_CONTEXT_VALIDATION_PROMPT },
+            { role: 'system', content: systemPrompt },
             { role: 'user', content: validationRequest },
           ],
-          max_completion_tokens: 4096, // Sufficient for larger batches with many findings
+          max_completion_tokens: 16384, // Must accommodate 8 files × multiple findings with full validation fields
           response_format: {
             type: 'json_schema',
             json_schema: {
@@ -146,8 +157,8 @@ export async function validateWithOpenAI(
                               index: { type: 'number' },
                               keep: { type: 'boolean' },
                               notes: {
-                                type: ['string', 'null'],
-                                default: null
+                                type: 'string',
+                                description: 'Required: brief reason for the decision (5-15 words for rejections, 10-30 words for accepts)',
                               },
                               adjustedSeverity: {
                                 type: ['string', 'null'],
@@ -376,9 +387,3 @@ export async function validateWithOpenAI(
   return { vulnerabilities: validatedFindings, stats }
 }
 
-/**
- * Clear cached project context (called after validation complete)
- */
-export function clearOpenAICache(): void {
-  cachedProjectContext = null
-}

package/src/validate/request-builder.ts

@@ -0,0 +1,448 @@
+/**
+ * Request Builders for AI Validation
+ *
+ * Functions for building validation requests with full or scoped file context.
+ */
+
+import type { Vulnerability, ScanFile } from '../shared/types'
+import type { ProjectContext } from '../model/project-context'
+import { getFileValidationContext } from '../model/project-context'
+import type { FileTaintAnalysis } from '../model/taint-types'
+import type { CrossFileTaintPath } from '../model/cross-file-taint'
+import type { FileFrameworkAnalysis } from '../model/framework-models/types'
+import type { RouteMap } from '../model/route-discovery'
+import { findClosestRoute } from '../model/route-discovery/utils'
+import { getLanguageFromPath } from './utils/path-helpers'
+import { extractRelevantContext } from './utils/context-extractor'
+import type { ExtractionConfig } from './utils/context-extractor'
+
+// ============================================================================
+// Options
+// ============================================================================
+
+export interface RequestBuilderOptions {
+  /** Context mode: 'full' sends entire file, 'scoped' extracts relevant regions (default: 'scoped') */
+  contextMode?: 'full' | 'scoped'
+  /** Override extraction config for scoped mode */
+  extractionConfig?: Partial<ExtractionConfig>
+}
+
+// ============================================================================
+// Single-File Request Builder
+// ============================================================================
+
+/**
+ * Build a high-context validation request with full or scoped file content
+ */
+export function buildHighContextValidationRequest(
+  file: ScanFile,
+  findings: Vulnerability[],
+  projectContext: ProjectContext,
+  options?: RequestBuilderOptions,
+  fileTaintAnalyses?: Map<string, FileTaintAnalysis>,
+  routeMap?: RouteMap,
+  crossFileTaintPaths?: CrossFileTaintPath[],
+  frameworkAnalyses?: Map<string, FileFrameworkAnalysis>
+): string {
+  const mode = options?.contextMode ?? 'scoped'
+
+  // Get file content (full or scoped)
+  const { numberedContent, contextNote } = getFileContent(file, findings, mode, options?.extractionConfig)
+
+  // Build file-level taint summary
+  const taintSummary = fileTaintAnalyses ? buildFileTaintSummary(file.path, fileTaintAnalyses) : ''
+
+  // Build file-level route summary
+  const routeSummary = routeMap ? buildFileRouteSummary(file.path, routeMap) : ''
+
+  // Build candidate findings list with taint, route, and framework annotations
+  const candidatesText = findings.map((f, idx) => {
+    const taintAnnotation = fileTaintAnalyses
+      ? buildFindingTaintAnnotation(f, file.path, fileTaintAnalyses)
+      : ''
+    const crossFileAnnotation = crossFileTaintPaths
+      ? buildCrossFileTaintAnnotation(f, file.path, crossFileTaintPaths)
+      : ''
+    const routeAnnotation = routeMap
+      ? buildFindingRouteAnnotation(f, file.path, routeMap)
+      : ''
+    const frameworkAnnotation = frameworkAnalyses
+      ? buildFindingFrameworkAnnotation(f, file.path, frameworkAnalyses)
+      : ''
+    return `### Candidate ${idx}
+- **Rule**: ${f.title}
+- **Category**: ${f.category}
+- **Original Severity**: ${f.severity}
+- **Line**: ${f.lineNumber}
+- **Detection Layer**: ${f.layer}
+- **Description**: ${f.description}
+- **Flagged Code**: \`${f.lineContent.trim()}\`${taintAnnotation}${crossFileAnnotation}${routeAnnotation}${frameworkAnnotation}`
+  }).join('\n\n')
+
+  // Get file-specific context
+  const fileContext = getFileValidationContext(file, projectContext)
+
+  return `## Project Context
+${projectContext.summary}
+
+${fileContext}
+${taintSummary}${routeSummary}
+## Full File Content${contextNote}
+\`\`\`${file.language || getLanguageFromPath(file.path)}
+${numberedContent}
+\`\`\`
+
+## Candidate Findings to Validate (${findings.length} total)
+
+${candidatesText}
+
+---
+
+Please validate each candidate finding. Return a JSON array with your decision for each.
+Remember: Be AGGRESSIVE in rejecting false positives. Use the full file context and project architecture to make informed decisions.`
+}
+
+// ============================================================================
+// Multi-File Request Builder (Phase 2 Optimization)
+// ============================================================================
+
+/**
+ * Build a multi-file validation request (Phase 2 optimization)
+ * Batches multiple files into a single API call to reduce overhead
+ */
+export function buildMultiFileValidationRequest(
+  fileDataList: Array<{ file: ScanFile; findings: Vulnerability[] }>,
+  projectContext: ProjectContext,
+  options?: RequestBuilderOptions,
+  fileTaintAnalyses?: Map<string, FileTaintAnalysis>,
+  routeMap?: RouteMap,
+  crossFileTaintPaths?: CrossFileTaintPath[],
+  frameworkAnalyses?: Map<string, FileFrameworkAnalysis>
+): string {
+  const mode = options?.contextMode ?? 'scoped'
+
+  const filesContent = fileDataList.map(({ file, findings }, fileIndex) => {
+    // Get file content (full or scoped)
+    const { numberedContent, contextNote } = getFileContent(file, findings, mode, options?.extractionConfig)
+
+    // Build file-level taint summary
+    const taintSummary = fileTaintAnalyses ? buildFileTaintSummary(file.path, fileTaintAnalyses) : ''
+
+    // Build file-level route summary
+    const routeSummary = routeMap ? buildFileRouteSummary(file.path, routeMap) : ''
+
+    // Build candidate findings list with file-specific indices, taint, route, and framework annotations
+    const candidatesText = findings.map((f, idx) => {
+      const taintAnnotation = fileTaintAnalyses
+        ? buildFindingTaintAnnotation(f, file.path, fileTaintAnalyses)
+        : ''
+      const crossFileAnnotation = crossFileTaintPaths
+        ? buildCrossFileTaintAnnotation(f, file.path, crossFileTaintPaths)
+        : ''
+      const routeAnnotation = routeMap
+        ? buildFindingRouteAnnotation(f, file.path, routeMap)
+        : ''
+      const frameworkAnnotation = frameworkAnalyses
+        ? buildFindingFrameworkAnnotation(f, file.path, frameworkAnalyses)
+        : ''
+      return `### Candidate ${idx}
+- **Rule**: ${f.title}
+- **Category**: ${f.category}
+- **Original Severity**: ${f.severity}
+- **Line**: ${f.lineNumber}
+- **Detection Layer**: ${f.layer}
+- **Description**: ${f.description}
+- **Flagged Code**: \`${f.lineContent.trim()}\`${taintAnnotation}${crossFileAnnotation}${routeAnnotation}${frameworkAnnotation}`
+    }).join('\n\n')
+
+    // Get file-specific context
+    const fileContext = getFileValidationContext(file, projectContext)
+
+    return `
+================================================================================
+FILE ${fileIndex + 1}: ${file.path}
+================================================================================
+
+${fileContext}
+${taintSummary}${routeSummary}
+### Full File Content${contextNote}
+\`\`\`${file.language || getLanguageFromPath(file.path)}
+${numberedContent}
+\`\`\`
+
+### Candidate Findings to Validate (${findings.length} total)
+
+${candidatesText}`
+  }).join('\n\n')
+
+  return `## Project Context
+${projectContext.summary}
+
+${filesContent}
+
+---
+
+## Response Format
+
+For EACH file, provide a JSON object with the file path and validation results.
+Return a JSON array where each element has:
+- "file": the file path (e.g., "${fileDataList[0]?.file.path || 'path/to/file.ts'}")
+- "validations": array of validation results for that file's candidates
+
+Example response format:
+\`\`\`json
+[
+  {
+    "file": "src/auth.ts",
+    "validations": [
+      { "index": 0, "keep": true, "adjustedSeverity": "medium", "notes": "Protected by middleware" },
+      { "index": 1, "keep": false }
+    ]
+  },
+  {
+    "file": "src/api.ts",
+    "validations": [
+      { "index": 0, "keep": true, "notes": "User input flows to SQL query" }
+    ]
+  }
+]
+\`\`\`
+
+Remember: Be AGGRESSIVE in rejecting false positives. Use the full file context and project architecture to make informed decisions.`
+}
+
+// ============================================================================
+// Annotation Helpers
+// ============================================================================
+
+/**
+ * Build a file-level taint summary for the AI prompt.
+ * Returns empty string if no taint analysis exists for the file.
+ */
+export function buildFileTaintSummary(
+  filePath: string,
+  fileTaintAnalyses: Map<string, FileTaintAnalysis>
+): string {
+  const analysis = fileTaintAnalyses.get(filePath)
+  if (!analysis || analysis.sources.length === 0) return ''
+
+  const sourceTypes = [...new Set(analysis.sources.map(s => s.sourceType))].join(', ')
+  const totalPaths = analysis.taintPaths.length
+  const unsanitised = analysis.taintPaths.filter(p => !p.sanitised).length
+  const sanitiserNames = [...new Set(analysis.sanitisers.map(s => s.name))]
+
+  const lines = [
+    `### Data Flow Analysis`,
+    `- User input sources: ${sourceTypes}`,
+    `- Taint paths: ${totalPaths} (${unsanitised} unsanitised)`,
+  ]
+  if (sanitiserNames.length > 0) {
+    lines.push(`- Sanitisers detected: ${sanitiserNames.join(', ')}`)
+  }
+
+  return lines.join('\n') + '\n'
+}
+
+/**
+ * Build a per-finding taint annotation for the AI prompt.
+ * Returns a string to append after the "Flagged Code" line.
+ */
+export function buildFindingTaintAnnotation(
+  finding: Vulnerability,
+  filePath: string,
+  fileTaintAnalyses: Map<string, FileTaintAnalysis>
+): string {
+  const analysis = fileTaintAnalyses.get(filePath)
+  if (!analysis) return ''
+
+  // Check if any taint path has a sink at the finding's line number
+  const matchingPaths = analysis.taintPaths.filter(
+    tp => tp.sink.line === finding.lineNumber
+  )
+
+  if (matchingPaths.length > 0) {
+    // Pick the best path (unsanitised first, then highest confidence)
+    const bestPath = matchingPaths.find(p => !p.sanitised) ?? matchingPaths[0]
+    const chainStr = bestPath.chain
+      .map(v => `${v.name}(L${v.taintedAt})`)
+      .join(' → ')
+    const fullChain = chainStr
+      ? `${bestPath.source.variable}(L${bestPath.source.line}) → ${chainStr} → sink(L${bestPath.sink.line})`
+      : `${bestPath.source.variable}(L${bestPath.source.line}) → sink(L${bestPath.sink.line})`
+
+    const lines = [
+      `\n- **Taint Analysis**: User input reaches this sink`,
+      `  - Source: \`${bestPath.source.expression}\` (${bestPath.source.sourceType}, L${bestPath.source.line})`,
+      `  - Chain: ${fullChain}`,
+      `  - Sink type: ${bestPath.sink.sinkType}`,
+      `  - Sanitised: ${bestPath.sanitised ? 'Yes' : 'No'}`,
+      `  - Confidence: ${bestPath.confidence}`,
+    ]
+    return lines.join('\n')
+  }
+
+  // File has taint analysis with sources but no path reaches this finding's line
+  if (analysis.sources.length > 0) {
+    return '\n- **Taint Analysis**: No user-input data flow reaches this line'
+  }
+
+  return ''
+}
+
+// ============================================================================
+// Route Annotation Helpers
+// ============================================================================
+
+/**
+ * Build a per-finding route annotation for the AI prompt.
+ * Returns a string to append after taint annotations.
+ */
+export function buildFindingRouteAnnotation(
+  finding: Vulnerability,
+  filePath: string,
+  routeMap: RouteMap
+): string {
+  const fileRoutes = routeMap.fileToRoutes.get(filePath)
+  if (!fileRoutes || fileRoutes.length === 0) return ''
+
+  // Find the closest route to the finding's line
+  const route = findClosestRoute(fileRoutes, finding.lineNumber)
+  if (!route) return ''
+
+  const framework = route.framework.replace(/_/g, ' ')
+  const methods = route.methods.join(', ')
+  const authStr = route.authMiddleware.length > 0
+    ? route.authMiddleware.join(', ')
+    : 'NONE'
+  const rateLimitStr = route.rateLimiting ? 'Yes' : 'NONE'
+
+  const lines = [
+    `\n- **Route Context:**`,
+    `  - Handler: ${framework} ${methods} \`${route.path}\``,
+    `  - Auth middleware: ${authStr}`,
+    `  - Rate limiting: ${rateLimitStr}`,
+  ]
+
+  if (route.isPublic) {
+    lines.push(`  - Public endpoint: Yes`)
+  }
+
+  return lines.join('\n')
+}
+
+/**
+ * Build a file-level route summary for the AI prompt.
+ * Returns empty string if no routes exist for the file.
+ */
+export function buildFileRouteSummary(
+  filePath: string,
+  routeMap: RouteMap
+): string {
+  const fileRoutes = routeMap.fileToRoutes.get(filePath)
+  if (!fileRoutes || fileRoutes.length === 0) return ''
+
+  const routeDescriptions = fileRoutes.map(r => {
+    const methods = r.methods.join('|')
+    const auth = r.authMiddleware.length > 0 ? ` [auth: ${r.authMiddleware.join(', ')}]` : ' [no auth]'
+    const rateLimit = r.rateLimiting ? ' [rate-limited]' : ''
+    const pub = r.isPublic ? ' [public]' : ''
+    return `  - ${methods} \`${r.path}\` (L${r.handlerLine})${auth}${rateLimit}${pub}`
+  })
+
+  return `### Route Map\n${routeDescriptions.join('\n')}\n`
+}
+
+// ============================================================================
+// Cross-File Taint Annotation Helpers
+// ============================================================================
+
+/**
+ * Build a per-finding cross-file taint annotation for the AI prompt.
+ * Appended after intra-file taint annotations when cross-file paths exist.
+ */
+export function buildCrossFileTaintAnnotation(
+  finding: Vulnerability,
+  filePath: string,
+  crossFileTaintPaths: CrossFileTaintPath[]
+): string {
+  // Check if any cross-file taint path has a sink at the finding's line
+  const matchingPaths = crossFileTaintPaths.filter(
+    cfp => (cfp.sinkFile === filePath && cfp.sink.line === finding.lineNumber) ||
+           (cfp.sourceFile === filePath && cfp.importLink.callLine === finding.lineNumber)
+  )
+
+  if (matchingPaths.length === 0) return ''
+
+  const bestPath = matchingPaths.find(p => !p.sanitised) ?? matchingPaths[0]
+
+  const lines = [
+    `\n- **Cross-File Taint**: User input crosses file boundary`,
+    `  - Source: \`${bestPath.source.expression}\` in \`${bestPath.sourceFile}\` (L${bestPath.source.line})`,
+    `  - Via: \`${bestPath.importLink.symbolName}()\` imported from \`${bestPath.importLink.toFile}\``,
+    `  - Sink: ${bestPath.sink.sinkType} in \`${bestPath.sinkFile}\` (L${bestPath.sink.line})`,
+    `  - Sanitised: ${bestPath.sanitised ? 'Yes' : 'No'}`,
+  ]
+
+  return lines.join('\n')
+}
+
+// ============================================================================
+// Framework Annotation Helpers
+// ============================================================================
+
+/**
+ * Build a per-finding framework annotation for the AI prompt.
+ * Returns a string to append after route annotations.
+ */
+export function buildFindingFrameworkAnnotation(
+  finding: Vulnerability,
+  filePath: string,
+  frameworkAnalyses: Map<string, FileFrameworkAnalysis>
+): string {
+  const analysis = frameworkAnalyses.get(filePath)
+  if (!analysis) return ''
+
+  const safePatterns = analysis.safeLines.get(finding.lineNumber)
+  const unsafePatterns = analysis.unsafeLines.get(finding.lineNumber)
+
+  if (!safePatterns?.length && !unsafePatterns?.length) return ''
+
+  const lines: string[] = []
+  if (safePatterns) {
+    for (const pattern of safePatterns) {
+      lines.push(`\n- **Framework Context**: ${pattern.reason}`)
+    }
+  }
+  if (unsafePatterns) {
+    for (const pattern of unsafePatterns) {
+      lines.push(`\n- **Framework Context**: ${pattern.reason}`)
+    }
+  }
+
+  return lines.join('')
+}
+
+function getFileContent(
+  file: ScanFile,
+  findings: Vulnerability[],
+  mode: 'full' | 'scoped',
+  extractionConfig?: Partial<ExtractionConfig>
+): { numberedContent: string; contextNote: string } {
+  if (mode === 'full') {
+    const numberedContent = file.content
+      .split('\n')
+      .map((line, i) => `${String(i + 1).padStart(4, ' ')} | ${line}`)
+      .join('\n')
+    return { numberedContent, contextNote: '' }
+  }
+
+  // Scoped mode: extract relevant regions
+  const findingLineNumbers = findings.map(f => f.lineNumber)
+  const extracted = extractRelevantContext(file.content, findingLineNumbers, extractionConfig)
+
+  const contextNote = extracted.isFullFile
+    ? ''
+    : ` (Showing ${extracted.linesSent} of ${extracted.totalLines} lines — relevant regions around findings)`
+
+  return { numberedContent: extracted.content, contextNote }
+}

package/src/{layer3/anthropic → validate}/types.ts

@@ -2,7 +2,7 @@
  * Type definitions for AI validation module
  */
 
-import type { Vulnerability, VulnerabilitySeverity, VulnerabilityCategory, ValidationStatus } from '../../types'
+import type { Vulnerability, VulnerabilitySeverity, VulnerabilityCategory, ValidationStatus } from '../shared/types'
 
 // ============================================================================
 // Cost Monitoring Types