@oculum/scanner 1.0.13 → 1.0.15

package/src/shared/types.ts

@@ -3,99 +3,154 @@
  * Defines the core data structures for the security scanning engine
  */
 
-export type VulnerabilitySeverity = 'critical' | 'high' | 'medium' | 'low' | 'info'
+export type VulnerabilitySeverity =
+  | "critical"
+  | "high"
+  | "medium"
+  | "low"
+  | "info";
 
 export type VulnerabilityCategory =
-  | 'hardcoded_secret'
-  | 'high_entropy_string'
-  | 'sensitive_variable'
-  | 'security_bypass'
-  | 'dangerous_function'
-  | 'sql_injection'
-  | 'xss'
-  | 'command_injection'
-  | 'insecure_config'
-  | 'missing_auth'
-  | 'suspicious_package'
-  | 'cors_misconfiguration'
-  | 'root_container'
-  | 'dangerous_file'
-  | 'ai_pattern'
-  | 'sensitive_url'
-  | 'weak_crypto'
-  | 'data_exposure'  // Logging/exposing sensitive data
+  | "hardcoded_secret"
+  | "high_entropy_string"
+  | "sensitive_variable"
+  | "security_bypass"
+  | "dangerous_function"
+  | "sql_injection"
+  | "xss"
+  | "command_injection"
+  | "insecure_config"
+  | "missing_auth"
+  | "suspicious_package"
+  | "cors_misconfiguration"
+  | "root_container"
+  | "dangerous_file"
+  | "ai_pattern"
+  | "sensitive_url"
+  | "weak_crypto"
+  | "data_exposure" // Logging/exposing sensitive data
   // AI-specific categories (Story B)
-  | 'ai_prompt_injection'     // B1: Prompt hygiene issues - user input in system prompts
-  | 'ai_unsafe_execution'     // B2: LLM output fed to dangerous sinks (eval, exec, SQL)
-  | 'ai_overpermissive_tool'  // B4: Agent tools with excessive permissions
+  | "ai_prompt_injection" // B1: Prompt hygiene issues - user input in system prompts
+  | "ai_unsafe_execution" // B2: LLM output fed to dangerous sinks (eval, exec, SQL)
+  | "ai_overpermissive_tool" // B4: Agent tools with excessive permissions
   // AI-era vulnerability categories (M5)
-  | 'ai_rag_exfiltration'     // M5: RAG data leakage - cross-tenant retrieval, raw context exposure
-  | 'ai_endpoint_unprotected' // M5: AI endpoints without auth/rate limiting
-  | 'ai_schema_mismatch'      // M5: Missing schema validation on AI-generated outputs
+  | "ai_rag_exfiltration" // M5: RAG data leakage - cross-tenant retrieval, raw context exposure
+  | "ai_endpoint_unprotected" // M5: AI endpoints without auth/rate limiting
+  | "ai_schema_mismatch" // M5: Missing schema validation on AI-generated outputs
   // AI Detection Roadmap Phase 1
-  | 'ai_package_hallucination'  // P0: AI-hallucinated/fake package names in dependencies
-  | 'ai_rag_corpus_poisoning'   // P1: User uploads directly embedded without sanitization
-  | 'ai_rag_pii_leakage'        // P1: PII fields exposed in RAG retrieval responses
-  | 'ai_mcp_tool_poisoning'     // P1: MCP tool with unvalidated external content
-  | 'ai_mcp_credential_issue'   // P1: MCP credentials in parameters/responses
-  | 'ai_mcp_confused_deputy'    // P1: MCP operations without user context
+  | "ai_package_hallucination" // P0: AI-hallucinated/fake package names in dependencies
+  | "ai_rag_corpus_poisoning" // P1: User uploads directly embedded without sanitization
+  | "ai_rag_pii_leakage" // P1: PII fields exposed in RAG retrieval responses
+  | "ai_mcp_tool_poisoning" // P1: MCP tool with unvalidated external content
+  | "ai_mcp_credential_issue" // P1: MCP credentials in parameters/responses
+  | "ai_mcp_confused_deputy" // P1: MCP operations without user context
   // Phase 1 Enhancement Backlog
-  | 'ai_mcp_description_injection'  // Prompt injection in MCP tool descriptions
-  | 'ai_mcp_server_shadowing'       // Cross-server tool shadowing attacks
-  | 'ai_mcp_config_secrets'         // Secrets in MCP config files
-  | 'ai_mcp_config_permissions'     // Overpermissive MCP settings
-  | 'ai_rag_query_injection'        // Query manipulation in RAG systems
-  | 'ai_rag_embedding_poisoning'    // Adversarial embedding attacks
-  | 'ai_rag_chunk_injection'        // Chunk boundary exploitation
-  | 'ai_package_typosquat'          // Typosquatting attacks on packages
-  | 'ai_package_malicious'          // Known malicious/vulnerable package
+  | "ai_mcp_description_injection" // Prompt injection in MCP tool descriptions
+  | "ai_mcp_server_shadowing" // Cross-server tool shadowing attacks
+  | "ai_mcp_config_secrets" // Secrets in MCP config files
+  | "ai_mcp_config_permissions" // Overpermissive MCP settings
+  | "ai_rag_query_injection" // Query manipulation in RAG systems
+  | "ai_rag_embedding_poisoning" // Adversarial embedding attacks
+  | "ai_rag_chunk_injection" // Chunk boundary exploitation
+  | "ai_package_typosquat" // Typosquatting attacks on packages
+  | "ai_package_malicious" // Known malicious/vulnerable package
   // AI Detection Roadmap Phase 2
-  | 'ai_unsafe_model_load'          // Pickle/torch.load RCE risks
-  | 'ai_unverified_model'           // Model loaded without integrity verification
-  | 'ai_unsafe_finetuning'          // Training on unvalidated data
-  | 'ai_excessive_agency'           // Unbounded agent autonomy risks
+  | "ai_unsafe_model_load" // Pickle/torch.load RCE risks
+  | "ai_unverified_model" // Model loaded without integrity verification
+  | "ai_unsafe_finetuning" // Training on unvalidated data
+  | "ai_excessive_agency" // Unbounded agent autonomy risks
   // Agent skill file security
-  | 'ai_skill_injection'            // Agent skill file with prompt injection, data exfil, or hidden execution
+  | "ai_skill_injection" // Agent skill file with prompt injection, data exfil, or hidden execution
+  | "ai_rules_file_backdoor" // Rules File Backdoor: invisible Unicode, stealth instructions in AI config files
   // OWASP Workstream 1: Classic vulnerability detectors
-  | 'missing_security_headers'      // Missing HTTP security headers (CSP, HSTS, etc.)
-  | 'ssrf'                          // Server-Side Request Forgery
-  | 'log_injection'                 // Log injection / log forging
-  | 'xxe'                           // XML External Entity injection
+  | "missing_security_headers" // Missing HTTP security headers (CSP, HSTS, etc.)
+  | "ssrf" // Server-Side Request Forgery
+  | "log_injection" // Log injection / log forging
+  | "xxe"; // XML External Entity injection
 
-export type ValidationStatus = 'confirmed' | 'downgraded' | 'dismissed' | 'not_validated'
+export type ValidationStatus =
+  | "confirmed"
+  | "downgraded"
+  | "dismissed"
+  | "not_validated";
+
+// ============================================================================
+// Taint Path Types (Serializable Output)
+// ============================================================================
+
+/** One step in a taint propagation path (serializable output format). */
+export interface TaintPathStep {
+  line: number;
+  variable: string;
+  taintKinds: string[];
+  description: string;
+  stepType:
+    | "source"
+    | "propagation"
+    | "sanitizer"
+    | "sink"
+    | "call_entry"
+    | "call_return";
+  filePath?: string;
+  functionName?: string;
+}
+
+/** A serializable taint path from source to sink. */
+export interface TaintPathOutput {
+  sourceType: string;
+  sourceLine: number;
+  sinkType: string;
+  sinkLine: number;
+  taintKinds: string[];
+  /** Always false — sanitized paths are filtered by the taint engine before serialization. */
+  sanitized: boolean;
+  steps: TaintPathStep[];
+}
+
+/** Evidence classification for a finding. */
+export type EvidenceLevel =
+  | "proven"
+  | "partial"
+  | "contextual"
+  | "pattern_only";
 
 export interface Vulnerability {
-  id: string
-  filePath: string
-  lineNumber: number
-  lineContent: string
-  severity: VulnerabilitySeverity
-  category: VulnerabilityCategory
-  title: string
-  description: string
-  suggestedFix?: string
-  confidence: 'high' | 'medium' | 'low'
+  id: string;
+  filePath: string;
+  lineNumber: number;
+  lineContent: string;
+  severity: VulnerabilitySeverity;
+  category: VulnerabilityCategory;
+  title: string;
+  description: string;
+  suggestedFix?: string;
+  confidence: "high" | "medium" | "low";
   /** @deprecated Use `source` instead. Kept for backward compatibility. */
-  layer: 1 | 2 | 3
+  layer: 1 | 2 | 3;
   /** Which detector group produced this finding */
-  source?: 'secrets' | 'structural' | 'ai_code' | 'config' | 'validation'
-  requiresAIValidation?: boolean // If true, must pass through AI validation before surfacing
+  source?: "secrets" | "structural" | "ai_code" | "config" | "validation";
+  requiresAIValidation?: boolean; // If true, must pass through AI validation before surfacing
 
   // AI validation metadata
-  validatedByAI?: boolean // true if this finding was processed by AI validation
-  validationStatus?: ValidationStatus // outcome of AI validation
-  validationNotes?: string // e.g., "Route protected by Clerk middleware"
-  originalSeverity?: VulnerabilitySeverity // For downgraded findings, the original severity
+  validatedByAI?: boolean; // true if this finding was processed by AI validation
+  validationStatus?: ValidationStatus; // outcome of AI validation
+  validationNotes?: string; // e.g., "Route protected by Clerk middleware"
+  originalSeverity?: VulnerabilitySeverity; // For downgraded findings, the original severity
 
   // Actionable output fields (PRO-82)
-  impact?: string // Why this matters (business impact) - from metadata registry or AI
-  evidence?: string // What triggered this finding
-  fixSteps?: string[] // Step-by-step fix instructions
-  references?: string[] // OWASP/CWE documentation links
-  aiEnhanced?: boolean // True if AI provided custom impact/fix beyond registry defaults
+  impact?: string; // Why this matters (business impact) - from metadata registry or AI
+  evidence?: string; // What triggered this finding
+  fixSteps?: string[]; // Step-by-step fix instructions
+  references?: string[]; // OWASP/CWE documentation links
+  aiEnhanced?: boolean; // True if AI provided custom impact/fix beyond registry defaults
 
   /** Base confidence score (0.0-1.0) set by the detector. Used by scoring stage. */
-  baseConfidence?: number
+  baseConfidence?: number;
+
+  /** Serialized taint path from source to sink (when available). */
+  taintPath?: TaintPathOutput;
+  /** Evidence classification for this finding. */
+  evidenceLevel?: EvidenceLevel;
 }
 
 /**
@@ -104,13 +159,13 @@ export interface Vulnerability {
  */
 export interface CancellationToken {
   /** Whether cancellation has been requested */
-  cancelled: boolean
+  cancelled: boolean;
   /** Reason for cancellation (e.g., "User pressed Ctrl+C") */
-  reason?: string
+  reason?: string;
   /** Request cancellation */
-  cancel(reason?: string): void
+  cancel(reason?: string): void;
   /** Register cleanup callback to run when cancelled */
-  onCancel(callback: () => void): void
+  onCancel(callback: () => void): void;
 }
 
 /**
@@ -122,212 +177,240 @@ export interface CancellationToken {
  * const result = await runScan(files, repo, { cancellationToken: token })
  */
 export function createCancellationToken(): CancellationToken {
-  const cleanupCallbacks: Array<() => void> = []
+  const cleanupCallbacks: Array<() => void> = [];
 
   const token: CancellationToken = {
     cancelled: false,
     reason: undefined,
     cancel(reason?: string) {
       if (!token.cancelled) {
-        token.cancelled = true
-        token.reason = reason
+        token.cancelled = true;
+        token.reason = reason;
         // Run cleanup callbacks
-        cleanupCallbacks.forEach(cb => {
+        cleanupCallbacks.forEach((cb) => {
           try {
-            cb()
+            cb();
           } catch (e) {
             // Ignore cleanup errors
           }
-        })
+        });
       }
     },
     onCancel(callback) {
       if (token.cancelled) {
-        callback() // Already cancelled, run immediately
+        callback(); // Already cancelled, run immediately
       } else {
-        cleanupCallbacks.push(callback)
+        cleanupCallbacks.push(callback);
       }
-    }
-  }
+    },
+  };
 
-  return token
+  return token;
 }
 
 export interface ScanFile {
-  path: string
-  content: string
-  language: string
-  size: number
+  path: string;
+  content: string;
+  language: string;
+  size: number;
 }
 
 // Severity counts for issue-mix display
 export interface SeverityCounts {
-  critical: number
-  high: number
-  medium: number
-  low: number
-  info: number
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  info: number;
 }
 
 // Category counts keyed by VulnerabilityCategory
-export type CategoryCounts = Partial<Record<VulnerabilityCategory, number>>
+export type CategoryCounts = Partial<Record<VulnerabilityCategory, number>>;
 
 /** Summary of a suppressed vulnerability (for --show-suppressed output) */
 export interface SuppressedVulnerabilitySummary {
   /** Finding hash */
-  hash: string
+  hash: string;
   /** File path */
-  filePath: string
+  filePath: string;
   /** Line number */
-  lineNumber: number
+  lineNumber: number;
   /** Vulnerability category */
-  category: VulnerabilityCategory
+  category: VulnerabilityCategory;
   /** Severity */
-  severity: VulnerabilitySeverity
+  severity: VulnerabilitySeverity;
   /** Title */
-  title: string
+  title: string;
   /** How it was suppressed */
-  suppressionType: 'inline' | 'config-finding' | 'config-rule'
+  suppressionType: "inline" | "config-finding" | "config-rule";
   /** Reason for suppression */
-  suppressionReason: string
+  suppressionReason: string;
   /** Expiration date (if any) */
-  expires?: string
+  expires?: string;
 }
 
 export interface ScanResult {
-  repoName: string
-  repoUrl: string
-  branch: string
-  filesScanned: number
-  filesSkipped: number
-  vulnerabilities: Vulnerability[]
+  repoName: string;
+  repoUrl: string;
+  branch: string;
+  filesScanned: number;
+  filesSkipped: number;
+  vulnerabilities: Vulnerability[];
 
   // Issue-mix fields - use these for displaying security posture
-  severityCounts: SeverityCounts
-  categoryCounts: CategoryCounts
-  hasBlockingIssues: boolean // true if any critical or high severity issues
+  severityCounts: SeverityCounts;
+  categoryCounts: CategoryCounts;
+  hasBlockingIssues: boolean; // true if any critical or high severity issues
 
-  scanDuration: number // milliseconds
-  timestamp: string
+  scanDuration: number; // milliseconds
+  timestamp: string;
 
   // AI Validation stats (Phase 1 optimization metrics)
   validationStats?: {
-    totalFindings: number
-    validatedFindings: number
-    confirmedFindings: number
-    dismissedFindings: number
-    downgradedFindings: number
-    autoDismissedFindings: number
-    estimatedInputTokens: number
-    estimatedOutputTokens: number
-    estimatedCost: number
-    apiCalls: number
-    cacheCreationTokens: number
-    cacheReadTokens: number
-    cacheHitRate: number
-  }
+    totalFindings: number;
+    validatedFindings: number;
+    confirmedFindings: number;
+    dismissedFindings: number;
+    downgradedFindings: number;
+    autoDismissedFindings: number;
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    estimatedCost: number;
+    apiCalls: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    cacheHitRate: number;
+    rejectionBreakdown?: Record<
+      string,
+      Array<{
+        title: string;
+        filePath: string;
+        lineNumber: number;
+        severity: string;
+        confidenceScore?: number;
+        reason: string;
+      }>
+    >;
+  };
 
   // Cancellation metadata
-  cancelled?: boolean // true if scan was cancelled by user
-  cancelReason?: string // Reason for cancellation (e.g., "User pressed Ctrl+C")
+  cancelled?: boolean; // true if scan was cancelled by user
+  cancelReason?: string; // Reason for cancellation (e.g., "User pressed Ctrl+C")
 
   // Suppression metadata
   suppressionStats?: {
     /** Total findings before suppression */
-    total: number
+    total: number;
     /** Findings suppressed by inline comments */
-    inlineSuppressed: number
+    inlineSuppressed: number;
     /** Findings suppressed by config (finding hash) */
-    configFindingSuppressed: number
+    configFindingSuppressed: number;
     /** Findings suppressed by config (rule) */
-    configRuleSuppressed: number
+    configRuleSuppressed: number;
     /** Findings that would have been suppressed but suppression expired */
-    expired: number
-  }
+    expired: number;
+  };
   /** Suppressed vulnerabilities (when --show-suppressed is used) */
-  suppressedVulnerabilities?: SuppressedVulnerabilitySummary[]
+  suppressedVulnerabilities?: SuppressedVulnerabilitySummary[];
 
   // Baseline diff metadata (only present when --new flag is used)
   baselineDiff?: {
     /** When the baseline was created */
-    baselineCreatedAt: string
+    baselineCreatedAt: string;
     /** Git commit of the baseline (if available) */
-    baselineCommit?: string
+    baselineCommit?: string;
     /** Number of new findings (not in baseline) */
-    newCount: number
+    newCount: number;
     /** Number of fixed findings (in baseline, not in current) */
-    fixedCount: number
+    fixedCount: number;
     /** Number of existing findings (in both) */
-    existingCount: number
+    existingCount: number;
     /** Details of fixed findings for display */
     fixedFindings: Array<{
-      hash: string
-      filePath: string
-      lineNumber: number
-      category: string
-      severity: string
-      title: string
-    }>
-  }
+      hash: string;
+      filePath: string;
+      lineNumber: number;
+      category: string;
+      severity: string;
+      title: string;
+    }>;
+  };
+
+  /** Confidence-suppressed findings eligible for review (score >= 0.5 but below surface threshold) */
+  forReviewFindings?: Array<Vulnerability & { confidenceScore: number }>;
 
   /** Filter audit trail (when includeFilterAudit option is enabled) */
-  filterAuditTrail?: import('../postprocess/filtering/pipeline').AnnotatedFinding[]
+  filterAuditTrail?: import("../postprocess/filtering/pipeline").AnnotatedFinding[];
+
+  /** Project context from context engine (for two-phase scan protocol) */
+  projectContext?: import("../model/project-context").ProjectContext;
+
+  /** Language breakdown of scanned files (e.g., { "TypeScript": 45, "Python": 12 }) */
+  languageStats?: Record<string, number>;
 }
 
 export interface ScanProgress {
-  status: 'fetching' | 'layer1' | 'layer2' | 'layer3' | 'validating' | 'complete' | 'failed'
-  message: string
-  filesProcessed: number
-  totalFiles: number
-  vulnerabilitiesFound: number
+  status:
+    | "fetching"
+    | "layer1"
+    | "layer2"
+    | "layer3"
+    | "validating"
+    | "complete"
+    | "failed";
+  message: string;
+  filesProcessed: number;
+  totalFiles: number;
+  vulnerabilitiesFound: number;
 }
 
-export type ProgressCallback = (progress: ScanProgress) => void
+export type ProgressCallback = (progress: ScanProgress) => void;
 
 // Pattern definitions for Layer 1
 export interface SecretPattern {
-  name: string
-  pattern: RegExp
-  severity: VulnerabilitySeverity
-  description: string
+  name: string;
+  pattern: RegExp;
+  severity: VulnerabilitySeverity;
+  description: string;
 }
 
 // Config audit rules for Layer 1
 export interface ConfigRule {
-  name: string
-  filePatterns: string[]
-  check: (content: string, filePath: string) => ConfigViolation[]
+  name: string;
+  filePatterns: string[];
+  check: (content: string, filePath: string) => ConfigViolation[];
 }
 
 export interface ConfigViolation {
-  line: number
-  lineContent: string
-  message: string
-  severity: VulnerabilitySeverity
+  line: number;
+  lineContent: string;
+  message: string;
+  severity: VulnerabilitySeverity;
+  category?: VulnerabilityCategory;
 }
 
 // Layer 2 heuristics
 export interface SensitiveVariablePattern {
-  pattern: RegExp
-  severity: VulnerabilitySeverity
-  description: string
+  pattern: RegExp;
+  severity: VulnerabilitySeverity;
+  description: string;
 }
 
 // Layer 3 AI analysis
 export interface AIAnalysisRequest {
-  filePath: string
-  content: string
-  context: string
+  filePath: string;
+  content: string;
+  context: string;
 }
 
 export interface AIFinding {
-  lineNumber: number
-  lineContent: string
-  severity: VulnerabilitySeverity
-  category: VulnerabilityCategory
-  title: string
-  description: string
-  suggestedFix: string
+  lineNumber: number;
+  lineContent: string;
+  severity: VulnerabilitySeverity;
+  category: VulnerabilityCategory;
+  title: string;
+  description: string;
+  suggestedFix: string;
 }
 
 // ============================================================================
@@ -345,66 +428,85 @@ export interface DetectorContext {
   // Auth context (project-wide)
   auth: {
     /** Middleware configuration (if detected) */
-    middleware: MiddlewareAuthContextSummary | null
+    middleware: MiddlewareAuthContextSummary | null;
     /** Auth helpers detected in the project */
-    authHelpers: AuthHelperContextSummary
+    authHelpers: AuthHelperContextSummary;
     /** Public endpoint patterns (health, webhook, etc.) */
-    publicEndpoints: string[]
-  }
+    publicEndpoints: string[];
+  };
 
   // Framework context (project-wide)
   framework: {
     /** Primary backend framework detected */
-    primary: 'nextjs' | 'express' | 'fastify' | 'koa' | 'hono' | 'nestjs' | 'django' | 'flask' | 'rails' | 'unknown' | null
+    primary:
+      | "nextjs"
+      | "express"
+      | "fastify"
+      | "koa"
+      | "hono"
+      | "nestjs"
+      | "django"
+      | "flask"
+      | "fastapi"
+      | "rails"
+      | "unknown"
+      | null;
     /** Frontend framework detected */
-    frontend: 'react' | 'vue' | 'svelte' | 'angular' | 'unknown' | null
+    frontend: "react" | "vue" | "svelte" | "angular" | "unknown" | null;
     /** Whether the project uses TypeScript */
-    hasTypeScript: boolean
-  }
+    hasTypeScript: boolean;
+  };
 
   // Data access context (project-wide)
   dataAccess: {
     /** ORM/query builder detected */
-    orm: 'prisma' | 'drizzle' | 'typeorm' | 'sequelize' | 'knex' | null
+    orm: "prisma" | "drizzle" | "typeorm" | "sequelize" | "knex" | null;
     /** Whether RLS (Row-Level Security) is detected */
-    hasRLS: boolean
+    hasRLS: boolean;
     /** Validation library detected */
-    validationLib: 'zod' | 'yup' | 'joi' | 'valibot' | null
-  }
+    validationLib: "zod" | "yup" | "joi" | "valibot" | null;
+  };
 
   // Per-file context (computed for each file)
   file: {
     /** Whether this file is server-only (not bundled to client) */
-    isServerOnly: boolean
+    isServerOnly: boolean;
     /** Whether this file is client-bundled (exposed to browser) */
-    isClientBundled: boolean
+    isClientBundled: boolean;
     /** Whether this file is a test/mock/fixture file */
-    isTestFile: boolean
+    isTestFile: boolean;
     /** Whether this file is a config file */
-    isConfigFile: boolean
+    isConfigFile: boolean;
     /** Whether this file is in a tooling directory */
-    isToolingDir: boolean
-  }
+    isToolingDir: boolean;
+  };
 }
 
 /** Simplified middleware auth config for DetectorContext */
 export interface MiddlewareAuthContextSummary {
   /** Whether auth middleware was detected */
-  hasAuthMiddleware: boolean
+  hasAuthMiddleware: boolean;
   /** The type of auth detected */
-  authType: 'clerk' | 'nextauth' | 'auth0' | 'supabase' | 'custom' | 'unknown' | null
+  authType:
+    | "clerk"
+    | "nextauth"
+    | "auth0"
+    | "supabase"
+    | "custom"
+    | "unknown"
+    | null;
   /** Protected path patterns */
-  protectedPaths: string[]
+  protectedPaths: string[];
   /** Public/excluded path patterns */
-  publicPaths: string[]
+  publicPaths: string[];
 }
 
 /** Simplified auth helper context for DetectorContext */
 export interface AuthHelperContextSummary {
   /** Whether the project has throwing auth helpers */
-  hasThrowingHelpers: boolean
+  hasThrowingHelpers: boolean;
   /** Names of throwing auth helpers */
-  throwingHelperNames: string[]
+  throwingHelperNames: string[];
 }
 
 /**
@@ -438,36 +540,53 @@ export function createEmptyDetectorContext(): DetectorContext {
       isConfigFile: false,
       isToolingDir: false,
     },
-  }
+  };
 }
 
 // Supported file extensions for scanning
 export const SCANNABLE_EXTENSIONS = [
-  '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
-  '.py', '.rb', '.php', '.go', '.java', '.cs',
-  '.env', '.yaml', '.yml', '.json', '.toml',
-  '.dockerfile', '.sh', '.bash',
-  '.md',  // Agent skill files (SKILL.md, copilot-instructions.md, etc.)
-]
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".rb",
+  ".php",
+  ".go",
+  ".java",
+  ".cs",
+  ".env",
+  ".yaml",
+  ".yml",
+  ".json",
+  ".toml",
+  ".dockerfile",
+  ".sh",
+  ".bash",
+  ".md", // Agent skill files (SKILL.md, copilot-instructions.md, etc.)
+];
 
 // Files to always scan regardless of extension
 export const SPECIAL_FILES = [
-  'Dockerfile',
-  'docker-compose.yml',
-  'docker-compose.yaml',
-  '.env',
-  '.env.local',
-  '.env.production',
-  '.env.development',
-  'package.json',
-  'requirements.txt',
-  'Gemfile',
-  'go.mod',
-  '.cursorrules',
-]
+  "Dockerfile",
+  "docker-compose.yml",
+  "docker-compose.yaml",
+  ".env",
+  ".env.local",
+  ".env.production",
+  ".env.development",
+  "package.json",
+  "requirements.txt",
+  "Gemfile",
+  "go.mod",
+  ".cursorrules",
+  ".windsurfrules",
+];
 
 // Max file size to scan (50KB as per PRD)
-export const MAX_FILE_SIZE = 50 * 1024
+export const MAX_FILE_SIZE = 50 * 1024;
 
 // ============================================================================
 // Scan Mode Configuration
@@ -475,11 +594,11 @@ export const MAX_FILE_SIZE = 50 * 1024
 
 /**
  * Scan mode determines the depth and cost of the scan
- * 
+ *
  * - 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 type ScanMode = 'full' | 'incremental'
+export type ScanMode = "full" | "incremental";
 
 /**
  * Scan depth controls AI usage independent of full vs incremental mode
@@ -506,41 +625,41 @@ export type ScanMode = 'full' | 'incremental'
  * | CLI --deep     | deep          | Thorough analysis when requested     |
  * | Onboarding     | deep          | Full picture on first scan           |
  */
-export type ScanDepth = 'local' | 'verified' | 'deep'
+export type ScanDepth = "local" | "verified" | "deep";
 
 export interface ScanModeConfig {
   /** The scan mode */
-  mode: ScanMode
-  
+  mode: ScanMode;
+
   /** For incremental scans: paths of changed files */
-  changedFiles?: string[]
-  
+  changedFiles?: string[];
+
   /** For incremental scans: base commit/branch to diff against */
-  baseBranch?: string
-  
+  baseBranch?: string;
+
   /** Whether to skip AI validation entirely (for very fast scans) */
-  skipAIValidation?: boolean
-  
+  skipAIValidation?: boolean;
+
   /** Whether to skip Layer 3 deep analysis (reduces cost) */
-  skipLayer3?: boolean
-  
+  skipLayer3?: boolean;
+
   /** Maximum files to send to AI validation (cost control) */
-  maxAIValidationFiles?: number
-  
+  maxAIValidationFiles?: number;
+
   /** Maximum files for Layer 3 analysis (cost control) */
-  maxLayer3Files?: number
+  maxLayer3Files?: number;
 
-  /** Scan depth mode (cheap/validated/deep) - controls AI usage */
-  scanDepth?: ScanDepth
+  /** Scan depth mode (local/verified/deep) - controls AI usage */
+  scanDepth?: ScanDepth;
 
   /** Whether to exclude test files from scanning (default: true) */
-  excludeTestFiles?: boolean
+  excludeTestFiles?: boolean;
 
   /** Whether to exclude seed files from scanning (default: true) */
-  excludeSeedFiles?: boolean
+  excludeSeedFiles?: boolean;
 
   /** Custom file path patterns to exclude (glob format) */
-  customExclusions?: string[]
+  customExclusions?: string[];
 }
 
 /**
@@ -548,17 +667,17 @@ export interface ScanModeConfig {
  */
 export const SCAN_MODE_DEFAULTS: Record<ScanMode, Partial<ScanModeConfig>> = {
   full: {
-    mode: 'full',
+    mode: "full",
     skipAIValidation: false,
     skipLayer3: false,
     maxAIValidationFiles: 50,
     maxLayer3Files: 15,
   },
   incremental: {
-    mode: 'incremental',
+    mode: "incremental",
     skipAIValidation: false,
     skipLayer3: true, // Skip expensive Layer 3 for incremental
     maxAIValidationFiles: 20,
     maxLayer3Files: 5,
   },
-}
+};