/**
 * Confidence Scoring Types
 *
 * Per-finding continuous confidence scoring (0.0–1.0) that replaces
 * the tier-based routing system. Each finding gets a numeric score
 * computed from baseConfidence + sum(adjustments), and routing
 * decisions use score thresholds instead of tier membership.
 *
 * The adjustment system is extensible for the future Context Engine
 * (taint, route, framework data).
 */

import type { Vulnerability, ScanDepth } from '../shared/types'

// ============================================================================
// Confidence Adjustment
// ============================================================================

/**
 * A single adjustment applied to a finding's confidence score.
 * Records what changed the score, by how much, and why.
 */
export interface ConfidenceAdjustment {
  /** Which adjustment rule produced this */
  factor: string
  /** Numeric change to score (positive = more confident, negative = less) */
  delta: number
  /** Human-readable explanation */
  reason: string
  /** Origin of this adjustment */
  source: 'file_context' | 'auto_dismiss' | 'taint' | 'route' | 'framework' | 'detector'
}

// ============================================================================
// Confidence Computation Result
// ============================================================================

/**
 * Full computation result for a single finding's confidence score.
 */
export interface ConfidenceComputation {
  /** Final clamped score (0.0–1.0) */
  score: number
  /** Base confidence from the detector */
  base: number
  /** All adjustments applied */
  adjustments: ConfidenceAdjustment[]
  /** Routing decision based on score thresholds */
  routing: 'surface' | 'validate' | 'suppress'
}

// ============================================================================
// Scored Finding
// ============================================================================

/**
 * A vulnerability enriched with confidence scoring data.
 * Extends the base Vulnerability with computed confidence information.
 */
export interface ScoredFinding extends Vulnerability {
  /** Confidence computation result */
  confidence_score: ConfidenceComputation
}

// ============================================================================
// Depth Configuration
// ============================================================================

/**
 * Score thresholds for each scan depth level.
 * Determines how findings are routed based on their confidence score.
 */
export interface DepthConfig {
  /** Minimum score to surface directly without AI validation */
  surfaceThreshold: number
  /** Minimum score to send to AI validation (below this = suppress) */
  validateThreshold: number
  /** Whether AI validation is available at this depth */
  aiEnabled: boolean
}

// ============================================================================
// Confidence Log
// ============================================================================

/**
 * Structured log entry for confidence scoring decisions.
 * Used for debugging, tuning, and audit trails.
 */
export interface ConfidenceLog {
  /** Finding identifier (filePath:lineNumber:category) */
  findingId: string
  /** Vulnerability category */
  category: string
  /** Detector group that produced the finding */
  detectorGroup: string
  /** Base confidence from detector */
  base: number
  /** All adjustments applied */
  adjustments: ConfidenceAdjustment[]
  /** Final computed score */
  final: number
  /** Routing decision */
  routing: 'surface' | 'validate' | 'suppress'
  /** File path */
  filePath: string
  /** Severity */
  severity: string
}

// ============================================================================
// Adjustment Rule System
// ============================================================================

/**
 * Context available to adjustment rules for evaluating findings.
 *
 * Starts minimal (file classification + basic project info).
 * When Context Engine lands, add optional taint?, route?, framework?
 * fields — existing rules ignore them; new rules check for presence.
 */
export interface AdjustmentContext {
  /** File-level classification */
  file: {
    isTestFile: boolean
    isExampleFile: boolean
    isDocFile: boolean
    isScannerCode: boolean
    isToolingDir: boolean
    isServerOnly: boolean
    isClientBundled: boolean
  }
  /** Project-level context */
  project: {
    hasAuthMiddleware: boolean
    hasTypeScript: boolean
    orm: string | null
    validationLib: string | null
  }
  /** The raw line content of the finding */
  lineContent: string
  /** The file path of the finding */
  filePath: string

  // Context Engine fields (optional — existing rules ignore undefined)
  taint?: {
    confirmed: boolean
    sources: string[]
    sinkType: string | null
    sanitised: boolean
    confidence: 'high' | 'medium' | 'low' | null
  }
  route?: {
    hasAuth: boolean
    isPublic: boolean
    middleware: string[]
    methods: string[]
    hasRateLimiting: boolean
  }
  framework?: {
    /** A safe-by-design pattern matches this finding's line */
    safePatternMatch: { id: string; reason: string } | null
    /** An unsafe-despite-framework pattern matches this finding's line */
    unsafePatternMatch: { id: string; reason: string } | null
    /** Which frameworks are active in the project */
    activeFrameworks: string[]
    /** ORM in use */
    orm: string | null
  }
}

/**
 * A single adjustment rule that can modify a finding's confidence score.
 * Rules are evaluated in order; all matching rules contribute their delta.
 */
export interface AdjustmentRule {
  /** Unique name for this rule */
  name: string
  /** Origin category */
  source: ConfidenceAdjustment['source']
  /** Whether this rule applies to the given finding + context */
  applies: (finding: Vulnerability, context: AdjustmentContext) => boolean
  /** Score delta when rule applies (negative = less confident) */
  delta: number
  /** Human-readable reason */
  reason: string
}
