/**
 * ATR Quality Standard — Type Definitions
 *
 * Vendor-neutral types for rule quality scoring and maturity validation.
 * See docs/proposals/001-atr-quality-standard-rfc.md for the full RFC.
 *
 * @module agent-threat-rules/quality/types
 */

/** Rule maturity level — matches ATR schema and RFC-001 §1 */
export type Maturity = "draft" | "experimental" | "stable" | "deprecated";

/**
 * Provenance of a metadata field.
 * RFC-001 §4: two-dimensional compliance model.
 *
 * - `human-reviewed`: a human maintainer verified this mapping/content
 * - `community-contributed`: submitted via PR by an external contributor
 * - `auto-generated`: filled by a script or LLM without human review
 * - `llm-generated`: produced by the TC crystallization flywheel
 *
 * The quality gate treats these differently:
 *  - experimental gate accepts any provenance
 *  - stable gate requires `human-reviewed` or `community-contributed`
 */
export type Provenance =
  | "human-reviewed"
  | "community-contributed"
  | "auto-generated"
  | "llm-generated";

/**
 * Per-field provenance tracking.
 * Each metadata field can have its own provenance so partially-reviewed
 * rules are represented accurately.
 */
export interface MetadataProvenance {
  readonly mitre_atlas?: Provenance;
  readonly mitre_attack?: Provenance;
  readonly owasp_llm?: Provenance;
  readonly owasp_agentic?: Provenance;
  readonly test_cases?: Provenance;
  readonly evasion_tests?: Provenance;
  readonly false_positives?: Provenance;
}

/**
 * Minimal metadata required to score and validate a rule.
 * Any vendor's rule format can be adapted to this interface via a parser.
 */
export interface RuleMetadata {
  /** Unique rule identifier */
  readonly id: string;
  /** Human-readable title */
  readonly title: string;
  /** Current maturity level */
  readonly maturity: Maturity;
  /** Number of distinct detection conditions (layers) */
  readonly conditions: number;
  /** Count of true_positive test cases */
  readonly truePositives: number;
  /** Count of true_negative test cases */
  readonly trueNegatives: number;
  /** Count of documented evasion tests */
  readonly evasionTests: number;
  /** Has at least one OWASP reference (LLM Top 10 or Agentic Top 10) */
  readonly hasOwaspRef: boolean;
  /** Has at least one MITRE reference (ATLAS or ATT&CK) */
  readonly hasMitreRef: boolean;
  /** Has at least one documented false_positive pattern */
  readonly hasFalsePositiveDocs: boolean;
  /** Number of real-world samples validated against this rule */
  readonly wildSamples?: number;
  /** Measured false positive rate on wild samples (0.0 - 100.0) */
  readonly wildFpRate?: number;
  /** ISO date of last wild validation run */
  readonly wildValidatedAt?: string;
  /** True if the rule was generated by an LLM (not human-authored) */
  readonly llmGenerated?: boolean;
  /** True if a human reviewer has explicitly approved this rule */
  readonly humanReviewed?: boolean;
  /** Per-field provenance tracking (RFC-001 §4) */
  readonly provenance?: MetadataProvenance;
}

/** Confidence score components and total */
export interface ConfidenceScore {
  /** Overall score 0-100, rounded to integer */
  readonly total: number;
  /** Precision component (weight 0.40) */
  readonly precisionScore: number;
  /** Wild validation component (weight 0.30) */
  readonly wildValidationScore: number;
  /** Coverage breadth component (weight 0.20) */
  readonly coverageScore: number;
  /** Evasion documentation component (weight 0.10) */
  readonly evasionScore: number;
  /** True if score was capped due to LLM-generated origin without human review */
  readonly capped: boolean;
}

/** Result of running a rule through the quality gate */
export interface QualityGateResult {
  /** True if the rule meets all required criteria for its target maturity */
  readonly passed: boolean;
  /** Human-readable list of gate failures (empty if passed) */
  readonly issues: readonly string[];
  /** Warnings that do not block promotion but should be addressed */
  readonly warnings: readonly string[];
}

/** Decision output from canPromote() */
export interface PromotionDecision {
  /** True if the rule is eligible to promote to `to` */
  readonly eligible: boolean;
  /** The maturity level this decision is for */
  readonly to: Maturity;
  /** Reasons the rule is not eligible (empty if eligible) */
  readonly blockers: readonly string[];
}

/** A false positive report used in demotion decisions */
export interface FpReport {
  /** ISO timestamp of the report */
  readonly reportedAt: string;
  /** Whether this report has been investigated and resolved */
  readonly resolved: boolean;
}

/** Decision output from shouldDemote() */
export interface DemotionDecision {
  /** True if the rule should be automatically demoted */
  readonly shouldDemote: boolean;
  /** Reasons for demotion (empty if shouldDemote is false) */
  readonly reasons: readonly string[];
}

/**
 * Deployment guidance based on confidence score.
 * Maps confidence to a recommended production use.
 */
export type DeploymentRecommendation =
  | "block-in-production" // 90-100
  | "block-with-monitoring" // 80-89
  | "alert-only" // 60-79
  | "evaluation-only" // 40-59
  | "do-not-deploy"; // <40
