@oculum/scanner 1.0.11 → 1.0.13

package/src/index.ts

@@ -1,1047 +1,47 @@
 /**
- * Scanner Orchestrator
- * Coordinates all three scanning layers and produces final results
- */
-
-import type {
-  ScanFile,
-  ScanResult,
-  Vulnerability,
-  SeverityCounts,
-  CategoryCounts,
-  VulnerabilityCategory,
-  ScanMode,
-  ScanModeConfig,
-  ScanDepth,
-  CancellationToken,
-  SuppressedVulnerabilitySummary,
-} from './types'
-import { SCANNABLE_EXTENSIONS, SPECIAL_FILES, MAX_FILE_SIZE, SCAN_MODE_DEFAULTS } from './types'
-import { runLayer1Scan } from './layer1'
-import { runLayer2Scan } from './layer2'
-import { runLayer3Scan } from './layer3'
-import { validateFindingsWithAI, applyAutoDismissRules, type ValidationStats } from './layer3/anthropic'
-import { aggregateLocalhostFindings } from './layer1/urls'
-import { detectGlobalAuthMiddleware, type MiddlewareAuthConfig, getRoutePathFromFile, isRouteProtectedByMiddleware } from './utils/middleware-detector'
-import { detectAuthHelpers } from './utils/auth-helper-detector'
-import { buildFileAuthImports } from './utils/imported-auth-detector'
-// Tier system imports for filtering by scan depth
-import {
-  type DetectorTier,
-  type TierStats,
-  getTierForCategory,
-  isTierVisibleAtDepth,
-  shouldValidateWithAI,
-  computeTierStats,
-  formatTierStats,
-} from './tiers'
-// Suppression system
-import { SuppressionManager } from './suppression'
-// Rule metadata for actionable output (PRO-82)
-import { getRuleMetadata } from './rules'
-// Framework-aware fix suggestions (PRO-83)
-import { getFrameworkFix } from './rules/framework-fixes'
-// Project context for framework detection
-import { buildProjectContext, type ProjectContext } from './utils/project-context-builder'
-
-// Maximum candidates per file to send to AI validation (cost control)
-const MAX_VALIDATION_CANDIDATES_PER_FILE = 10
-
-/**
- * Classify vulnerabilities into tier groups for filtering
- */
-interface TierClassification {
-  /** Tier A (core): High-precision, always visible */
-  core: Vulnerability[]
-  /** Tier B (ai_assisted): Context-heavy, needs AI validation */
-  ai_assisted: Vulnerability[]
-  /** Tier C (experimental): Hidden from users, internal use only */
-  experimental: Vulnerability[]
-}
-
-/**
- * Classify vulnerabilities by their detector tier
- */
-function classifyByTier(vulnerabilities: Vulnerability[]): TierClassification {
-  const result: TierClassification = {
-    core: [],
-    ai_assisted: [],
-    experimental: [],
-  }
-
-  for (const vuln of vulnerabilities) {
-    const tier = getTierForCategory(vuln.category, vuln.layer)
-    result[tier].push(vuln)
-  }
-
-  return result
-}
-
-/**
- * Filter vulnerabilities based on scan depth and tier
- *
- * - cheap: Only Tier A (core) findings are surfaced
- * - validated: Tier A visible, Tier B goes through AI validation
- * - deep: Same as validated, plus Layer 3 semantic analysis
- *
- * Tier C (experimental) is NEVER surfaced to users, regardless of depth.
- */
-function filterByTierAndDepth(
-  vulnerabilities: Vulnerability[],
-  depth: ScanDepth
-): {
-  /** Findings to surface directly (no AI validation needed) */
-  toSurface: Vulnerability[]
-  /** Findings to send through AI validation */
-  toValidate: Vulnerability[]
-  /** Findings hidden from users (Tier C) */
-  hidden: Vulnerability[]
-  /** Tier stats for logging */
-  tierStats: TierStats
-} {
-  const classified = classifyByTier(vulnerabilities)
-  const tierStats = computeTierStats(
-    vulnerabilities.map(v => ({ category: v.category, layer: v.layer }))
-  )
-
-  switch (depth) {
-    case 'cheap':
-      // Only Tier A is visible, no AI validation
-      return {
-        toSurface: classified.core,
-        toValidate: [],
-        hidden: [...classified.ai_assisted, ...classified.experimental],
-        tierStats,
-      }
-
-    case 'validated':
-    case 'deep':
-      // Tier A always surfaces, Tier B goes to AI validation
-      // For findings that already require AI validation, only include Tier A/B
-      const coreRequiringValidation = classified.core.filter(v =>
-        v.requiresAIValidation ||
-        v.category === 'high_entropy_string' ||
-        v.category === 'hardcoded_secret' ||
-        (v.category === 'sensitive_url' && v.severity !== 'info')
-      )
-      const coreNotRequiringValidation = classified.core.filter(v =>
-        !coreRequiringValidation.includes(v)
-      )
-
-      return {
-        toSurface: coreNotRequiringValidation,
-        toValidate: [...coreRequiringValidation, ...classified.ai_assisted],
-        hidden: classified.experimental,
-        tierStats,
-      }
-  }
-}
-
-export interface ScanOptions {
-  /** Enable AI-powered validation and analysis */
-  enableAI?: boolean
-  /** Maximum files to scan */
-  maxFiles?: number
-  /** Branch being scanned */
-  branch?: string
-  /** Scan mode configuration (full vs incremental) */
-  scanMode?: ScanMode | ScanModeConfig
-  /** Scan depth (cheap/validated/deep) - controls AI usage */
-  scanDepth?: ScanDepth
-  /** Suppress console.log output (for interactive CLI mode) */
-  quiet?: boolean
-  /** Cancellation token for aborting scans gracefully */
-  cancellationToken?: CancellationToken
-  /** Project path for loading suppression config (defaults to cwd) */
-  projectPath?: string
-  /** Include suppressed findings in output (for --show-suppressed) */
-  showSuppressed?: boolean
-}
-
-export interface ScanProgress {
-  status: 'fetching' | 'layer1' | 'layer2' | 'layer3' | 'validating' | 'complete' | 'failed'
-  message: string
-  filesProcessed: number
-  totalFiles: number
-  vulnerabilitiesFound: number
-}
-
-export type ProgressCallback = (progress: ScanProgress) => void
-
-/**
- * Resolve scan mode configuration from options
- *
- * Handles both scan mode (full/incremental) and depth (cheap/validated/deep).
- * Depth controls AI usage:
- * - cheap: skip AI validation + skip Layer 3
- * - validated: run AI validation, skip Layer 3
- * - deep: run AI validation + Layer 3
- */
-function resolveScanModeConfig(options: ScanOptions): ScanModeConfig {
-  const scanModeOption = options.scanMode
-
-  // Determine base mode
-  const mode: ScanMode = !scanModeOption ? 'full'
-    : typeof scanModeOption === 'string' ? scanModeOption
-    : scanModeOption.mode
-
-  const defaults = SCAN_MODE_DEFAULTS[mode]
-
-  // Build config from defaults + explicit overrides
-  let config: ScanModeConfig = {
-    ...defaults,
-    mode,
-    ...(typeof scanModeOption === 'object' ? scanModeOption : {}),
-  }
-
-  // Apply depth mode (default: 'cheap')
-  const depth = options.scanDepth ?? 'cheap'
-  config.scanDepth = depth
-
-  // Map depth to skipAIValidation/skipLayer3 unless explicitly overridden
-  const hasExplicitSkipAI = typeof scanModeOption === 'object' && scanModeOption.skipAIValidation !== undefined
-  const hasExplicitSkipL3 = typeof scanModeOption === 'object' && scanModeOption.skipLayer3 !== undefined
-
-  if (!hasExplicitSkipAI) {
-    config.skipAIValidation = depth === 'cheap'
-  }
-  if (!hasExplicitSkipL3) {
-    config.skipLayer3 = depth !== 'deep'
-  }
-
-  return config
-}
-
-/**
- * Run a complete security scan on the provided files
- * 
- * Supports two scan modes:
- * - full: Complete scan with AI validation on all files (initial onboarding, deep audits)
- * - incremental: Focused scan on changed files only (CI/CD, fast feedback)
- */
-export async function runScan(
-  files: ScanFile[],
-  repoInfo: { name: string; url: string; branch: string },
-  options: ScanOptions = {},
-  onProgress?: ProgressCallback
-): Promise<ScanResult> {
-  const startTime = Date.now()
-  const allVulnerabilities: Vulnerability[] = []
-
-  // Resolve scan mode configuration
-  const scanModeConfig = resolveScanModeConfig(options)
-  const isIncremental = scanModeConfig.mode === 'incremental'
-  const depth = scanModeConfig.scanDepth || 'cheap'
-  const quiet = options.quiet ?? false
-  const cancellationToken = options.cancellationToken
-
-  // Conditional logging helper - suppresses output in quiet mode (interactive CLI)
-  const log = (message: string) => {
-    if (!quiet) {
-      console.log(message)
-    }
-  }
-
-  // Helper to check cancellation and throw if cancelled
-  const checkCancelled = () => {
-    if (cancellationToken?.cancelled) {
-      throw new Error(`Scan cancelled: ${cancellationToken.reason || 'user requested'}`)
-    }
-  }
-
-  log(`[Scanner] repo=${repoInfo.name} mode=${scanModeConfig.mode} depth=${depth} files=${files.length}`)
-  if (isIncremental && scanModeConfig.changedFiles) {
-    log(`[Scanner] repo=${repoInfo.name} incremental_files=${scanModeConfig.changedFiles.length}`)
-  }
-
-  // Report progress helper
-  const reportProgress = (
-    status: ScanProgress['status'],
-    message: string,
-    vulnerabilitiesFound: number = allVulnerabilities.length
-  ) => {
-    if (onProgress) {
-      onProgress({
-        status,
-        message,
-        filesProcessed: files.length,
-        totalFiles: files.length,
-        vulnerabilitiesFound,
-      })
-    }
-  }
-  
-  // For incremental scans, filter to only changed files for AI-heavy operations
-  // but still run static analysis on all files for context
-  const filesForAI = isIncremental && scanModeConfig.changedFiles
-    ? files.filter(f => scanModeConfig.changedFiles!.some(cf => f.path.endsWith(cf) || f.path.includes(cf)))
-    : files
-
-  // Declare variables that need to be accessible in catch block
-  let middlewareConfig: MiddlewareAuthConfig | undefined
-  let capturedValidationStats: ValidationStats | undefined
-
-  try {
-    checkCancelled()
-
-    // Detect global auth middleware before scanning (always on all files for context)
-    middlewareConfig = detectGlobalAuthMiddleware(files)
-    if (middlewareConfig.hasAuthMiddleware) {
-      log(`[Scanner] repo=${repoInfo.name} auth_middleware=${middlewareConfig.authType || 'unknown'} file=${middlewareConfig.middlewareFile}`)
-    }
-
-    // Build imported auth registry for cross-file middleware detection
-    const fileAuthImports = buildFileAuthImports(files)
-    const filesWithImportedAuth = Array.from(fileAuthImports.values()).filter(f => f.usesImportedAuth).length
-    if (filesWithImportedAuth > 0) {
-      log(`[Scanner] repo=${repoInfo.name} files_with_imported_auth=${filesWithImportedAuth}`)
-    }
-
-    checkCancelled()
-
-    // Phase timing tracking
-    const phaseTiming: { layer1?: number; layer2?: number; aiValidation?: number; layer3?: number } = {}
-
-    // Layer 1: Surface Scan
-    const layer1Start = Date.now()
-    reportProgress('layer1', 'Running surface scan (patterns, entropy, config)...')
-    let layer1Result = await runLayer1Scan(files, onProgress, cancellationToken)
-
-    // Aggregate repeated localhost findings
-    const layer1RawCount = layer1Result.vulnerabilities.length
-    layer1Result = {
-      ...layer1Result,
-      vulnerabilities: aggregateLocalhostFindings(layer1Result.vulnerabilities)
-    }
-    phaseTiming.layer1 = Date.now() - layer1Start
-    log(`[Layer1] repo=${repoInfo.name} findings_raw=${layer1RawCount} findings_deduped=${layer1Result.vulnerabilities.length} duration=${phaseTiming.layer1}ms`)
-
-    checkCancelled()
-
-    // Layer 2: Structural Scan
-    const layer2Start = Date.now()
-    reportProgress('layer2', 'Running structural scan (variables, logic gates)...', layer1Result.vulnerabilities.length)
-    const layer2Result = await runLayer2Scan(files, { middlewareConfig, fileAuthImports }, onProgress, cancellationToken)
-
-    // Format heuristic breakdown for logging
-    const heuristicBreakdown = Object.entries(layer2Result.stats.raw)
-      .filter(([, count]) => count > 0)
-      .map(([name, count]) => `${name}:${count}`)
-      .join(',')
-    phaseTiming.layer2 = Date.now() - layer2Start
-    log(`[Layer2] repo=${repoInfo.name} findings_raw=${Object.values(layer2Result.stats.raw).reduce((a, b) => a + b, 0)} findings_deduped=${layer2Result.vulnerabilities.length} duration=${phaseTiming.layer2}ms heuristic_breakdown={${heuristicBreakdown}}`)
-
-    // Combine Layer 1 and Layer 2 findings
-    const layer12Findings = [...layer1Result.vulnerabilities, ...layer2Result.vulnerabilities]
-
-    // Aggregate noisy findings BEFORE tier filtering to reduce noise
-    const beforeAggregationCount = layer12Findings.length
-    const aggregatedFindings = aggregateNoisyFindings(layer12Findings)
-    const aggregatedCount = beforeAggregationCount - aggregatedFindings.length
-
-    // Build project context for framework-aware fixes (PRO-83)
-    // This detects frameworks (Next.js, Express), ORMs (Prisma, Drizzle), and frontend libs (React, Vue)
-    const projectContext = buildProjectContext(files)
-
-    // Enrich findings with metadata from rule registry (PRO-82)
-    // PRO-83: Uses projectContext for framework-specific fix suggestions
-    // This provides default impact, evidence, fixSteps, references for all findings
-    // AI validation can override these later with context-aware content
-    const enrichedFindings = enrichWithMetadata(aggregatedFindings, projectContext)
-
-    // Apply tier-based filtering based on scan depth
-    // This is the key integration point for the detector tier system
-    const tierFiltered = filterByTierAndDepth(enrichedFindings, depth)
-
-    // Log tier breakdown
-    log(`[Scanner] repo=${repoInfo.name} tier_breakdown=${formatTierStats(tierFiltered.tierStats)}`)
-    log(`[Scanner] repo=${repoInfo.name} depth=${depth} tier_routing: surface=${tierFiltered.toSurface.length} validate=${tierFiltered.toValidate.length} hidden=${tierFiltered.hidden.length}`)
-
-    // For cheap scans: Tier A surfaces directly, Tier B/C are hidden
-    // For validated/deep: Tier A surfaces, Tier B goes through AI validation, Tier C hidden
-
-    // Some Tier A findings still need AI validation (entropy, secrets, AI-specific)
-    const additionalValidation = tierFiltered.toSurface.filter(v =>
-      v.requiresAIValidation ||
-      v.category === 'ai_prompt_injection' ||     // Story B1: Prompt hygiene
-      v.category === 'ai_unsafe_execution' ||     // Story B2: LLM output execution
-      v.category === 'ai_overpermissive_tool'     // Story B4: Agent tool permissions
-    )
-
-    // Surface findings that don't need validation (excluding those that do)
-    const noValidationNeededRaw = tierFiltered.toSurface.filter(v => !additionalValidation.includes(v))
-
-    // Apply auto-dismiss rules to direct-surface findings (mode='surface')
-    // Uses 'surface' mode to exclude cost-saving rules like 'info_severity_core_only'
-    // This ensures test/scanner/example files are dismissed, but info-severity findings still surface
-    const { toValidate: noValidationNeeded, dismissed: surfaceDismissed } = applyAutoDismissRules(noValidationNeededRaw, 'surface')
-
-    // Combine tier-filtered validation candidates with additional ones
-    const requiresValidation = [...tierFiltered.toValidate, ...additionalValidation]
-
-    // Apply smart auto-dismiss rules BEFORE AI validation (saves API costs)
-    const { toValidate: afterAutoDismiss, dismissed: autoDismissed } = applyAutoDismissRules(requiresValidation)
-
-    // Combine all dismissed findings for logging
-    const allDismissed = [...surfaceDismissed, ...autoDismissed]
-
-    // Track auto-dismiss by severity and category for logging
-    const autoDismissBySeverity: Record<string, number> = { info: 0, low: 0, medium: 0, high: 0, critical: 0 }
-    const autoDismissByCategory: Record<string, number> = {}
-    for (const d of allDismissed) {
-      autoDismissBySeverity[d.finding.severity] = (autoDismissBySeverity[d.finding.severity] || 0) + 1
-      autoDismissByCategory[d.finding.category] = (autoDismissByCategory[d.finding.category] || 0) + 1
-    }
-    if (allDismissed.length > 0) {
-      const categoryBreakdown = Object.entries(autoDismissByCategory)
-        .sort(([, a], [, b]) => b - a)
-        .map(([cat, count]) => `${cat}:${count}`)
-        .join(',')
-      log(`[AutoDismiss] repo=${repoInfo.name} total=${allDismissed.length} (surface=${surfaceDismissed.length} validation=${autoDismissed.length}) by_severity={info:${autoDismissBySeverity.info},low:${autoDismissBySeverity.low},medium:${autoDismissBySeverity.medium},high:${autoDismissBySeverity.high}} by_category={${categoryBreakdown}}`)
-    }
-
-    // Apply per-file cap to validation candidates (cost control)
-    // Use scan mode config for max files
-    const maxValidationFiles = scanModeConfig.maxAIValidationFiles || MAX_VALIDATION_CANDIDATES_PER_FILE
-    const cappedValidation = capValidationCandidatesPerFile(afterAutoDismiss, maxValidationFiles)
-
-    checkCancelled()
-
-    // AI Validation of selected findings (if AI is enabled and not skipped by scan mode)
-    let validatedFindings = cappedValidation
-    let capturedValidationStats: ValidationStats | undefined = undefined
-    const shouldValidate = options.enableAI !== false && !scanModeConfig.skipAIValidation && cappedValidation.length > 0
-
-    if (shouldValidate) {
-      checkCancelled()
-      const aiValidationStart = Date.now()
-      reportProgress('validating', 'AI validating findings (entropy, secrets, AI patterns)...', cappedValidation.length)
-
-      // For incremental scans, only validate findings in changed files
-      const findingsToValidate = isIncremental && scanModeConfig.changedFiles
-        ? cappedValidation.filter(v => scanModeConfig.changedFiles!.some(cf => v.filePath.endsWith(cf) || v.filePath.includes(cf)))
-        : cappedValidation
-
-      if (findingsToValidate.length > 0) {
-        const validationResult = await validateFindingsWithAI(
-          findingsToValidate,
-          filesForAI,
-          undefined, // projectContext (uses default)
-          onProgress ? (progress) => {
-            // Convert AI validation progress to ScanProgress format
-            onProgress({
-              status: 'validating',
-              message: progress.status,
-              filesProcessed: progress.filesProcessed,
-              totalFiles: progress.totalFiles,
-              vulnerabilitiesFound: allVulnerabilities.length,
-            })
-          } : undefined
-        )
-        validatedFindings = validationResult.vulnerabilities
-        const { stats: validationStats } = validationResult
-        capturedValidationStats = validationStats // Capture for return
-        phaseTiming.aiValidation = Date.now() - aiValidationStart
-
-        log(`[AI Validation] repo=${repoInfo.name} depth=${depth} duration=${phaseTiming.aiValidation}ms candidates=${findingsToValidate.length} capped_from=${requiresValidation.length} auto_dismissed=${autoDismissed.length} kept=${validationStats.confirmedFindings} rejected=${validationStats.dismissedFindings} downgraded=${validationStats.downgradedFindings}`)
-        log(`[AI Validation] cost_estimate: input_tokens=${validationStats.estimatedInputTokens} output_tokens=${validationStats.estimatedOutputTokens} cost=$${validationStats.estimatedCost.toFixed(4)} api_calls=${validationStats.apiCalls}`)
-
-        // Add back findings that weren't validated (not in changed files)
-        // Mark them as skipped rather than failed validation
-        const notValidated = cappedValidation.filter(v => !findingsToValidate.includes(v)).map(v => ({
-          ...v,
-          validatedByAI: false,
-          validationStatus: 'not_validated' as const,
-          validationNotes: 'Skipped validation (not in changed files for incremental scan)',
-        }))
-        validatedFindings.push(...notValidated)
-      }
-    } else if (scanModeConfig.skipAIValidation) {
-      log(`[AI Validation] repo=${repoInfo.name} depth=${depth} skipped=true reason=scan_mode_config findings_requiring_validation=${cappedValidation.length}`)
-      // In cheap mode, don't surface findings that require AI validation
-      // These are low-confidence without validation and would be noise
-      // Only surface high-confidence findings that don't need validation
-      validatedFindings = []
-    }
-
-    // Combine validated and non-validated findings
-    allVulnerabilities.push(...validatedFindings, ...noValidationNeeded)
-
-    // Layer 3: AI Semantic Analysis (new findings)
-    // Skip for incremental scans by default (configurable)
-    const shouldRunLayer3 = options.enableAI !== false && !scanModeConfig.skipLayer3
-
-    if (shouldRunLayer3) {
-      checkCancelled()
-      const layer3Start = Date.now()
-      reportProgress('layer3', 'Running AI semantic analysis...', allVulnerabilities.length)
-
-      // For incremental scans, only analyze changed files
-      const filesToAnalyze = isIncremental ? filesForAI : files
-      const maxLayer3Files = scanModeConfig.maxLayer3Files || 10
-
-      // Detect auth helpers for Layer 3 context
-      const authHelperContext = detectAuthHelpers(files)
-
-      const layer3Result = await runLayer3Scan(filesToAnalyze, {
-        enableAI: options.enableAI,
-        maxFiles: maxLayer3Files,
-        projectContext: {
-          middlewareConfig: middlewareConfig.hasAuthMiddleware ? {
-            hasAuthMiddleware: true,
-            authType: middlewareConfig.authType,
-            protectedPaths: middlewareConfig.protectedPaths,
-          } : undefined,
-          authHelpers: authHelperContext.hasThrowingHelpers ? {
-            hasThrowingHelpers: true,
-            summary: authHelperContext.summary,
-          } : undefined,
-        },
-        cancellationToken,
-      })
-      phaseTiming.layer3 = Date.now() - layer3Start
-      allVulnerabilities.push(...layer3Result.vulnerabilities)
-      log(`[Layer3] repo=${repoInfo.name} depth=${depth} duration=${phaseTiming.layer3}ms files_analyzed=${layer3Result.aiAnalyzed} findings=${layer3Result.vulnerabilities.length}`)
-    } else if (scanModeConfig.skipLayer3) {
-      log(`[Layer3] repo=${repoInfo.name} depth=${depth} skipped=true reason=scan_mode_config`)
-    }
-
-    // Log phase timing summary
-    const phaseTimingStr = Object.entries(phaseTiming)
-      .filter(([, ms]) => ms !== undefined)
-      .map(([phase, ms]) => `${phase}=${ms}ms`)
-      .join(' ')
-    if (phaseTimingStr) {
-      log(`[Scanner] repo=${repoInfo.name} phase_timing: ${phaseTimingStr}`)
-    }
-
-    // Deduplicate vulnerabilities
-    const uniqueVulnerabilities = deduplicateVulnerabilities(allVulnerabilities)
-
-    // Resolve contradictions (e.g., middleware-protected INFO vs missing-auth CRITICAL on same route)
-    const resolvedVulnerabilities = resolveContradictions(uniqueVulnerabilities, middlewareConfig)
-
-    // Apply suppressions (inline comments + config file)
-    const projectPath = options.projectPath || process.cwd()
-    const suppressionManager = new SuppressionManager({ projectPath })
-    const suppressionResult = suppressionManager.applySuppressions(resolvedVulnerabilities, files)
-
-    // Log suppression stats if any were suppressed
-    if (suppressionResult.suppressed.length > 0 || suppressionResult.expiredSuppressions > 0) {
-      log(`[Suppression] repo=${repoInfo.name} suppressed=${suppressionResult.suppressed.length} (inline=${suppressionResult.stats.inlineSuppressed} config_finding=${suppressionResult.stats.configFindingSuppressed} config_rule=${suppressionResult.stats.configRuleSuppressed}) expired=${suppressionResult.expiredSuppressions}`)
-    }
-
-    // Use the filtered findings (after suppression)
-    const afterSuppression = suppressionResult.findings
-
-    // Sort by severity
-    const sortedVulnerabilities = sortBySeverity(afterSuppression)
-
-    // Compute issue-mix counts (based on unsuppressed findings)
-    const severityCounts = computeSeverityCounts(sortedVulnerabilities)
-    const categoryCounts = computeCategoryCounts(sortedVulnerabilities)
-    const hasBlockingIssues = severityCounts.critical > 0 || severityCounts.high > 0
-
-    // Build suppressed vulnerabilities summary (for --show-suppressed)
-    const suppressedVulnerabilities: SuppressedVulnerabilitySummary[] | undefined = options.showSuppressed
-      ? suppressionResult.suppressed.map(s => ({
-          hash: s.suppression.hash,
-          filePath: s.vulnerability.filePath,
-          lineNumber: s.vulnerability.lineNumber,
-          category: s.vulnerability.category,
-          severity: s.vulnerability.severity,
-          title: s.vulnerability.title,
-          suppressionType: s.suppression.type,
-          suppressionReason: s.suppression.reason,
-          expires: s.suppression.expires,
-        }))
-      : undefined
-
-    reportProgress('complete', 'Scan complete!', sortedVulnerabilities.length)
-
-    return {
-      repoName: repoInfo.name,
-      repoUrl: repoInfo.url,
-      branch: repoInfo.branch,
-      filesScanned: files.length,
-      filesSkipped: 0, // TODO: track skipped files
-      vulnerabilities: sortedVulnerabilities,
-      severityCounts,
-      categoryCounts,
-      hasBlockingIssues,
-      scanDuration: Date.now() - startTime,
-      timestamp: new Date().toISOString(),
-      validationStats: capturedValidationStats,
-      suppressionStats: suppressionResult.suppressed.length > 0 || suppressionResult.expiredSuppressions > 0
-        ? suppressionResult.stats
-        : undefined,
-      suppressedVulnerabilities,
-    }
-  } catch (error) {
-    if (cancellationToken?.cancelled) {
-      // Return partial results on cancellation
-      reportProgress('failed', 'Scan cancelled')
-
-      // Compute partial results
-      const uniqueVulnerabilities = deduplicateVulnerabilities(allVulnerabilities)
-      const resolvedVulnerabilities = resolveContradictions(uniqueVulnerabilities, middlewareConfig)
-      const sortedVulnerabilities = sortBySeverity(resolvedVulnerabilities)
-      const severityCounts = computeSeverityCounts(sortedVulnerabilities)
-      const categoryCounts = computeCategoryCounts(sortedVulnerabilities)
-
-      return {
-        repoName: repoInfo.name,
-        repoUrl: repoInfo.url,
-        branch: repoInfo.branch,
-        filesScanned: files.length,
-        filesSkipped: 0,
-        vulnerabilities: sortedVulnerabilities,
-        severityCounts,
-        categoryCounts,
-        hasBlockingIssues: false, // Don't block on partial results
-        scanDuration: Date.now() - startTime,
-        timestamp: new Date().toISOString(),
-        validationStats: capturedValidationStats,
-        cancelled: true,
-        cancelReason: cancellationToken.reason,
-      }
-    }
-
-    reportProgress('failed', `Scan failed: ${error}`)
-    throw error
-  }
-}
-
-/**
- * Enrich findings with metadata from the rule registry (PRO-82)
- * Sets default impact, evidence, fixSteps, and references from registry
- *
- * PRO-83: When projectContext is provided, uses framework-aware fix suggestions
- * that are tailored to the user's detected tech stack (e.g., Prisma-specific
- * SQL injection fixes instead of generic advice).
+ * Scanner Public API
  *
- * These can be overridden later by AI-generated content
- */
-function enrichWithMetadata(
-  findings: Vulnerability[],
-  projectContext?: ProjectContext
-): Vulnerability[] {
-  return findings.map(f => {
-    const metadata = getRuleMetadata(f.category)
-    if (!metadata) return f
-
-    // PRO-83: Check for framework-specific fix suggestions
-    let fixSteps = metadata.fixSteps
-    if (projectContext) {
-      const frameworkFix = getFrameworkFix(
-        f.category,
-        projectContext.frameworks,
-        projectContext.dataAccess
-      )
-      if (frameworkFix) {
-        fixSteps = frameworkFix.fixSteps
-        // Optionally append code example to description if available
-        // This makes the fix more actionable
-      }
-    }
-
-    return {
-      ...f,
-      // Set defaults from registry (AI can override later)
-      impact: f.impact || metadata.whyItMatters,
-      evidence: f.evidence || metadata.evidence,
-      fixSteps: f.fixSteps || fixSteps,
-      references: f.references || metadata.references,
-    }
-  })
-}
-
-/**
- * Aggregate noisy findings in the same file to reduce clutter
- * Groups repeated findings with same filePath + category + title
- * Especially useful for AI pattern spam
- */
-function aggregateNoisyFindings(vulnerabilities: Vulnerability[]): Vulnerability[] {
-  // Group findings by file + category + title
-  const groups = new Map<string, Vulnerability[]>()
-  
-  for (const vuln of vulnerabilities) {
-    // Create grouping key: same file, category, and base title (without line-specific info)
-    const baseTitle = vuln.title.replace(/\s*\(\d+ instances?\)/, '').trim()
-    const key = `${vuln.filePath}|${vuln.category}|${baseTitle}`
-    
-    const existing = groups.get(key) || []
-    existing.push(vuln)
-    groups.set(key, existing)
-  }
-  
-  const result: Vulnerability[] = []
-  
-  for (const [key, group] of groups) {
-    // If only 1-2 findings, keep them as-is
-    if (group.length <= 2) {
-      result.push(...group)
-      continue
-    }
-    
-    // For 3+ similar findings in same file, aggregate into one
-    const first = group[0]
-    const lineNumbers = group.map(v => v.lineNumber).sort((a, b) => a - b)
-    const uniqueLines = [...new Set(lineNumbers)]
-    
-    // Format line numbers nicely (show first few, then "...")
-    const lineDisplay = uniqueLines.length > 5
-      ? `${uniqueLines.slice(0, 5).join(', ')}... (${uniqueLines.length} total)`
-      : uniqueLines.join(', ')
-    
-    // Keep highest severity from the group
-    const highestSeverity = group.reduce((max, v) => 
-      severityRank(v.severity) > severityRank(max.severity) ? v : max
-    , group[0]).severity
-    
-    // Create aggregated finding
-    const aggregated: Vulnerability = {
-      id: `${first.id}-aggregated`,
-      filePath: first.filePath,
-      lineNumber: uniqueLines[0], // First occurrence
-      lineContent: `${group.length} instances across this file`,
-      severity: highestSeverity,
-      category: first.category,
-      title: `${first.title.replace(/\s*\(\d+ instances?\)/, '')} (${group.length} instances)`,
-      description: `${first.description}\n\nFound ${group.length} occurrences at lines: ${lineDisplay}`,
-      suggestedFix: first.suggestedFix,
-      confidence: first.confidence,
-      layer: first.layer,
-      requiresAIValidation: first.requiresAIValidation,
-    }
-    
-    result.push(aggregated)
-  }
-  
-  return result
-}
-
-/**
- * Cap validation candidates per file to control AI costs
- * Prioritizes by:
- * 1. Tier (ai_assisted findings need AI most, so they get priority)
- * 2. Severity (critical > high > medium > low > info)
- * 3. Category importance (secrets/URLs/auth before cosmetic patterns)
- */
-function capValidationCandidatesPerFile(
-  vulnerabilities: Vulnerability[],
-  maxPerFile: number = MAX_VALIDATION_CANDIDATES_PER_FILE
-): Vulnerability[] {
-  // Group by file
-  const byFile = new Map<string, Vulnerability[]>()
-  for (const vuln of vulnerabilities) {
-    const existing = byFile.get(vuln.filePath) || []
-    existing.push(vuln)
-    byFile.set(vuln.filePath, existing)
-  }
-
-  const result: Vulnerability[] = []
-
-  for (const [filePath, fileVulns] of byFile) {
-    // Sort by priority: tier first (ai_assisted needs AI most), then severity, then category
-    const sorted = [...fileVulns].sort((a, b) => {
-      // Tier comparison: ai_assisted (needs AI) > core (high precision) > experimental (hidden anyway)
-      const tierPriority = (v: Vulnerability): number => {
-        const tier = getTierForCategory(v.category, v.layer)
-        if (tier === 'ai_assisted') return 10  // Highest priority - these NEED AI validation
-        if (tier === 'core') return 5           // High precision, but AI can still help
-        return 1                                 // Experimental - shouldn't even be here
-      }
-      const tierDiff = tierPriority(b) - tierPriority(a)
-      if (tierDiff !== 0) return tierDiff
-
-      // Severity comparison (higher severity = higher priority)
-      const severityDiff = severityRank(b.severity) - severityRank(a.severity)
-      if (severityDiff !== 0) return severityDiff
-
-      // Category importance (secrets/URLs/auth before AI patterns)
-      const categoryPriority = (v: Vulnerability): number => {
-        if (v.category === 'hardcoded_secret') return 10
-        if (v.category === 'high_entropy_string') return 9
-        if (v.category === 'sensitive_url') return 8
-        if (v.category === 'missing_auth') return 7
-        if (v.category === 'ai_pattern') return 3
-        return 5
-      }
-      return categoryPriority(b) - categoryPriority(a)
-    })
-
-    // Take top N per file
-    const capped = sorted.slice(0, maxPerFile)
-    result.push(...capped)
-
-    // Note: Capping log removed to support quiet mode - this is debug info only
-  }
-
-  return result
-}
-
-/**
- * Remove duplicate vulnerabilities (same file, line, category)
- * Also handles cross-layer URL duplicates (sensitive_url + ai_pattern)
- */
-function deduplicateVulnerabilities(vulnerabilities: Vulnerability[]): Vulnerability[] {
-  const seen = new Map<string, Vulnerability>()
-  const urlDedupMap = new Map<string, Vulnerability>()
-
-  for (const vuln of vulnerabilities) {
-    // Special handling for URL duplicates across layers
-    // (e.g., Layer 1 detects as sensitive_url, Layer 2 detects as ai_pattern)
-    if ((vuln.category === 'sensitive_url' || vuln.category === 'ai_pattern') &&
-        /url|localhost|127\.0\.0\.1|http/i.test(vuln.lineContent)) {
-
-      // Create compound key that ignores category differences for URLs
-      const urlKey = `${vuln.filePath}:${vuln.lineNumber}:url_finding`
-      const existing = urlDedupMap.get(urlKey)
-
-      if (!existing) {
-        urlDedupMap.set(urlKey, vuln)
-      } else {
-        // Keep Layer 1 (more specific) over Layer 2 AI pattern
-        // Or keep higher severity
-        if (vuln.layer < existing.layer ||
-            severityRank(vuln.severity) > severityRank(existing.severity)) {
-          urlDedupMap.set(urlKey, vuln)
-        }
-      }
-      continue
-    }
-
-    // Standard deduplication for non-URL findings
-    const key = `${vuln.filePath}:${vuln.lineNumber}:${vuln.category}`
-    const existing = seen.get(key)
-
-    // Keep the higher severity or higher confidence finding
-    if (!existing) {
-      seen.set(key, vuln)
-    } else if (severityRank(vuln.severity) > severityRank(existing.severity)) {
-      seen.set(key, vuln)
-    } else if (
-      severityRank(vuln.severity) === severityRank(existing.severity) &&
-      confidenceRank(vuln.confidence) > confidenceRank(existing.confidence)
-    ) {
-      seen.set(key, vuln)
-    }
-  }
-
-  // Combine URL and non-URL findings
-  return [...Array.from(seen.values()), ...Array.from(urlDedupMap.values())]
-}
-
-/**
- * Resolve contradictions in findings
- * 
- * Key contradiction types:
- * 1. Same route has both "protected by middleware" (info) AND "missing auth" (high/critical)
- *    → Keep only the info-level "protected by middleware" finding
- * 2. Same file has BYOK "transient use" (info) AND "key stored insecurely" (high)
- *    → Keep only the most accurate one based on context
- * 3. Same line has conflicting severities from different layers
- *    → Prefer the lower severity if one explicitly notes protection
- */
-function resolveContradictions(
-  vulnerabilities: Vulnerability[],
-  middlewareConfig?: MiddlewareAuthConfig
-): Vulnerability[] {
-  // Group findings by file path for contradiction analysis
-  const byFile = new Map<string, Vulnerability[]>()
-  for (const vuln of vulnerabilities) {
-    const existing = byFile.get(vuln.filePath) || []
-    existing.push(vuln)
-    byFile.set(vuln.filePath, existing)
-  }
-
-  const result: Vulnerability[] = []
-
-  for (const [filePath, fileVulns] of byFile) {
-    // Check for auth contradictions in this file
-    const authFindings = fileVulns.filter(v => v.category === 'missing_auth')
-    const otherFindings = fileVulns.filter(v => v.category !== 'missing_auth')
-    
-    // Identify protected routes (middleware or auth helper)
-    const protectedInfos = authFindings.filter(v => 
-      v.severity === 'info' && 
-      (v.validationNotes === 'MIDDLEWARE_PROTECTED' || 
-       v.validationNotes === 'AUTH_HELPER_PROTECTED' ||
-       v.title.includes('protected by middleware') ||
-       v.title.includes('uses auth helper'))
-    )
-    
-    // NEW: Check if this file's route is protected by middleware (even without explicit info finding)
-    // This catches Layer 3 findings that don't have the Layer 2 protection info
-    const routePath = getRoutePathFromFile(filePath)
-    const isAPIRouteProtected = routePath && middlewareConfig?.hasAuthMiddleware
-      ? isRouteProtectedByMiddleware(routePath, middlewareConfig).isProtected
-      : false
-    
-    // Also check if file is a client component calling protected API routes
-    // Client components (components/, app/ without route.ts) calling /api/** are safe
-    const isClientCallingProtectedAPI = 
-      middlewareConfig?.hasAuthMiddleware &&
-      (filePath.includes('/components/') || 
-       (filePath.includes('/app/') && !filePath.includes('route.ts')))
-    
-    // If we have protected route info findings OR the route is protected by middleware
-    if (protectedInfos.length > 0 || isAPIRouteProtected || isClientCallingProtectedAPI) {
-      // Keep the protected info findings
-      result.push(...protectedInfos)
-      
-      // For other auth findings on same file, either drop or downgrade to info
-      const otherAuthFindings = authFindings.filter(v => !protectedInfos.includes(v))
-      
-      for (const vuln of otherAuthFindings) {
-        // If it's high/critical missing auth on a protected route, drop it entirely
-        // (the middleware/helper protection supersedes)
-        if (vuln.severity === 'critical' || vuln.severity === 'high') {
-          const reason = isAPIRouteProtected 
-            ? 'API route protected by middleware' 
-            : isClientCallingProtectedAPI 
-              ? 'client component calling protected API'
-              : 'route is protected'
-          // Note: Contradiction log removed to support quiet mode - this is debug info only
-          continue // Skip this finding
-        }
-        
-        // Keep lower severity auth findings as-is
-        result.push(vuln)
-      }
-    } else {
-      // No protection detected - keep all auth findings as-is
-      result.push(...authFindings)
-    }
-    
-    // Handle BYOK contradictions
-    const byokFindings = otherFindings.filter(v => 
-      v.category === 'ai_pattern' && v.title.toLowerCase().includes('byok')
-    )
-    const nonByokFindings = otherFindings.filter(v => 
-      !(v.category === 'ai_pattern' && v.title.toLowerCase().includes('byok'))
-    )
-    
-    if (byokFindings.length > 0) {
-      // Check if we have both transient (low) and storage (high) BYOK findings
-      const transientByok = byokFindings.filter(v => 
-        v.severity === 'low' || v.severity === 'info'
-      )
-      const storageByok = byokFindings.filter(v => 
-        v.severity === 'high' || v.severity === 'medium'
-      )
-      
-      if (transientByok.length > 0 && storageByok.length > 0) {
-        // If we detected transient usage, prefer the lower severity
-        // The higher severity ones may be false positives
-        result.push(...transientByok)
-        // Mark high-severity BYOK for review
-        for (const vuln of storageByok) {
-          result.push({
-            ...vuln,
-            severity: 'low',
-            validationNotes: `${vuln.validationNotes || ''} (downgraded: transient BYOK usage detected in same file)`.trim(),
-          })
-        }
-      } else {
-        // Keep all BYOK findings as-is
-        result.push(...byokFindings)
-      }
-    }
-    
-    // Add non-BYOK other findings
-    result.push(...nonByokFindings)
-  }
-
-  return result
-}
-
-/**
- * Sort vulnerabilities by severity (critical first)
+ * Re-exports from stage modules. All prior exports preserved.
  */
-function sortBySeverity(vulnerabilities: Vulnerability[]): Vulnerability[] {
-  return [...vulnerabilities].sort((a, b) => {
-    const severityDiff = severityRank(b.severity) - severityRank(a.severity)
-    if (severityDiff !== 0) return severityDiff
-    
-    // Secondary sort by confidence
-    return confidenceRank(b.confidence) - confidenceRank(a.confidence)
-  })
-}
 
-function severityRank(severity: string): number {
-  const ranks: Record<string, number> = {
-    critical: 5,
-    high: 4,
-    medium: 3,
-    low: 2,
-    info: 1,
-  }
-  return ranks[severity] || 0
-}
+// ============================================================================
+// Core Scanner API
+// ============================================================================
 
-function confidenceRank(confidence: string): number {
-  const ranks: Record<string, number> = {
-    high: 3,
-    medium: 2,
-    low: 1,
-  }
-  return ranks[confidence] || 0
-}
+// Pipeline orchestrator — main entry point
+export { runScan, type ScanOptions } from './pipeline'
 
-/**
- * Compute severity counts from vulnerabilities
- */
-function computeSeverityCounts(vulnerabilities: Vulnerability[]): SeverityCounts {
-  const counts: SeverityCounts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 }
-
-  for (const vuln of vulnerabilities) {
-    if (vuln.severity in counts) {
-      counts[vuln.severity]++
-    }
-  }
+// Summary utilities (public API for backfilling legacy scans etc.)
+export { computeIssueMixFromVulnerabilities } from './report/summary'
 
-  return counts
-}
-
-/**
- * Compute category counts from vulnerabilities
- */
-function computeCategoryCounts(vulnerabilities: Vulnerability[]): CategoryCounts {
-  const counts: CategoryCounts = {}
-  
-  for (const vuln of vulnerabilities) {
-    const category = vuln.category as VulnerabilityCategory
-    counts[category] = (counts[category] || 0) + 1
-  }
-  
-  return counts
-}
+// ============================================================================
+// Re-export types and utilities
+// ============================================================================
 
-/**
- * Helper to compute counts from vulnerabilities (for backfilling legacy scans)
- */
-export function computeIssueMixFromVulnerabilities(vulnerabilities: Vulnerability[]): {
-  severityCounts: SeverityCounts
-  categoryCounts: CategoryCounts
-  hasBlockingIssues: boolean
-} {
-  const severityCounts = computeSeverityCounts(vulnerabilities)
-  const categoryCounts = computeCategoryCounts(vulnerabilities)
-  const hasBlockingIssues = severityCounts.critical > 0 || severityCounts.high > 0
-  
-  return { severityCounts, categoryCounts, hasBlockingIssues }
-}
+export * from './shared/types'
+export { runLayer1Scan } from './detect/secrets'
+export { runLayer2Scan } from './detect/structural'
+export { buildProjectContext, type ProjectContext } from './model/project-context'
+export { validateFindingsWithAI, type ValidationStats, type AIValidationResult } from './validate'
+export { createCancellationToken } from './shared/types'
 
-// Re-export types and utilities
-export * from './types'
-export { runLayer1Scan } from './layer1'
-export { runLayer2Scan } from './layer2'
-export { runLayer3Scan } from './layer3'
-export { buildProjectContext, type ProjectContext } from './utils/project-context-builder'
-export { validateFindingsWithAI, type ValidationStats, type AIValidationResult } from './layer3/anthropic'
-export { createCancellationToken } from './types'
+// Confidence scoring exports (Phase 2B)
+export {
+  scoreFindings,
+  buildAdjustmentContext,
+  buildConfidenceLog,
+  DEPTH_CONFIGS,
+  type ScoredFinding,
+  type ConfidenceComputation,
+  type ConfidenceAdjustment,
+  type ConfidenceLog,
+  type AdjustmentRule,
+  type AdjustmentContext,
+  type DepthConfig,
+} from './score'
+
+// Context Engine types
+export type { ContextEngineResult } from './model/taint-types'
 
 // Suppression system exports
 export {
@@ -1060,7 +60,7 @@ export {
   type RuleSuppression,
   type SuppressionResult,
   type SuppressedVulnerability,
-} from './suppression'
+} from './postprocess/suppression'
 
 // Baseline system exports
 export {
@@ -1078,7 +78,7 @@ export {
   type LoadBaselineResult,
   type SaveBaselineResult,
   type ClearBaselineResult,
-} from './baseline'
+} from './shared/baseline'
 
 // Rule metadata exports (PRO-82)
 export {
@@ -1087,4 +87,30 @@ export {
   getAllCategories,
   hasMetadata,
   type RuleMetadata,
-} from './rules'
+} from './shared/rules'
+
+// AI Context exports
+export {
+  AIContextManager,
+  AI_CONTEXT_FILE,
+  AI_CONTEXT_PATH,
+  type AIContextManagerOptions,
+  type SaveContextResult,
+  type LoadContextResult,
+  type ClearContextResult,
+} from './shared/ai-context'
+
+// Category filter exports (Phase 2: Category-Based Filtering)
+export {
+  CATEGORY_GROUPS,
+  ALL_CATEGORIES,
+  normalizeCategory,
+  expandCategoryPattern,
+  matchesAnyCategory,
+  shouldFailOnCategories,
+  getMatchingCategories,
+  parseCategoryList,
+  validateCategories,
+  getAvailableCategoryGroups,
+  getCategoryGroupCounts,
+} from './shared/category-filter'