tga 10.0.0

//! `tga classify` — stage 2 (classification cascade) entry point.

use tga::classify::ClassificationPipeline;
use tga::core::config::{ClassificationConfig, Config};
use tga::core::db::{CheckpointMode, Database};

use crate::commands::args::ClassifyArgs;
use crate::commands::date_range::resolve_date_range;

/// Run the classification stage over previously-collected commits.
///
/// Why: wire CLI flags (`--rules`, `--use-llm`, `--force`, `--repos`,
/// `--weeks`, `--since/--until`, `--no-external`) into the
/// [`ClassificationPipeline`] without exposing the pipeline internals in
/// `main.rs`.  The new uniform filter flags (`--repos`, `--weeks`,
/// `--since/--until`) enable surgical re-classification of slices without
/// touching the full DB.
/// What: mutates the `ClassificationConfig` section of the loaded YAML config
/// to honor each override, then builds and runs the pipeline.
/// Test: integration-tested via pipeline unit tests in `classify::pipeline::tests`.
pub async fn run(config: Config, db: &mut Database, args: ClassifyArgs) -> anyhow::Result<()> {
    let mut cfg = config;

    // Ensure a classification section exists so overrides have somewhere to land.
    if cfg.classification.is_none() && (args.rules.is_some() || args.use_llm) {
        cfg.classification = Some(ClassificationConfig::default());
    }
    if let Some(ref mut c) = cfg.classification {
        if let Some(rules) = args.rules {
            // Prepend the CLI-supplied rules file to rules_files (back-compat
            // with `--rules`: single file, treated as the primary rules source).
            c.rules_files.insert(0, rules);
        }
        if args.use_llm {
            c.use_llm = true;
        }
        // When --no-external is passed, suppress all external classification
        // sources for this run regardless of what the rules file configures.
        if args.no_external {
            c.no_external = true;
        }
    }

    // Resolve the date window from --weeks / --since / --until.
    // Priority: --weeks > --since/--until.
    let (resolved_since, resolved_until) = resolve_date_range(
        args.weeks,
        args.since.as_deref(),
        args.until.as_deref(),
        None,
    )?;

    // Effective since: resolved window (from --weeks or --since) drives the
    // pipeline's `with_since` filter.  When --weeks is given we only have a
    // lower bound; when --since is given directly we may also have --until.
    let effective_since = resolved_since;
    let effective_until = resolved_until;

    // --since/--until without --force is a no-op (default flow already skips
    // classified rows). Flag this rather than silently ignoring it so the
    // operator notices the missing `--force`.
    if (effective_since.is_some() || effective_until.is_some()) && !args.force {
        tracing::warn!(
            "--since/--until/--weeks was supplied without --force; ignoring date window. \
             Pass --force to re-classify commits already in the DB."
        );
    }

    // #111: `--shas` subset. The pipeline rejects an empty list and unknown
    // SHAs before writing anything.
    let shas = match &args.shas {
        Some(path) => Some(read_sha_list(path)?),
        None => None,
    };
    if shas.is_some() && !args.force {
        tracing::warn!(
            "--shas without --force classifies only listed commits that have no verdict yet"
        );
    }

    let pipeline = ClassificationPipeline::new(cfg)
        .with_shas(shas)
        .with_force(args.force)
        .with_since(effective_since.clone())
        .with_until(effective_until.clone())
        .with_repos(args.repos.clone());

    // Backfill mode: fill in only the missing complexity scores and return,
    // leaving existing category/confidence/method verdicts untouched.
    if args.backfill_complexity {
        let updated = pipeline.backfill_complexity(db).await?;
        println!("Backfilled complexity for {updated} commit(s)");
        // Checkpoint the WAL after backfill too (issue #298).
        if let Err(e) = db.wal_checkpoint(CheckpointMode::Truncate) {
            tracing::warn!(error = %e, "WAL TRUNCATE checkpoint failed after backfill");
        }
        return Ok(());
    }

    let stats = pipeline.run(db).await?;

    // Issue #298: call PRAGMA wal_checkpoint(TRUNCATE) on clean exit to flush
    // the WAL into the main DB file and zero the WAL. Without this the main
    // DB file can lag behind the WAL, causing post-run queries to see a prior
    // state of the classifications table.
    if let Err(e) = db.wal_checkpoint(CheckpointMode::Truncate) {
        tracing::warn!(error = %e, "WAL TRUNCATE checkpoint failed after classify — \
            the WAL may not be flushed; run `sqlite3 <db> 'PRAGMA wal_checkpoint(TRUNCATE)'` manually");
    }

    println!(
        "Classified {}/{} commits ({:.1}% coverage)",
        stats.classified, stats.total_commits, stats.coverage_pct
    );
    if !stats.by_method.is_empty() {
        println!("By method:");
        for (method, count) in &stats.by_method {
            println!("  {method}: {count}");
        }
    }
    if !stats.by_category.is_empty() {
        println!("By category:");
        for (category, count) in &stats.by_category {
            println!("  {category}: {count}");
        }
    }
    print_llm_usage(&stats.llm_usage);
    Ok(())
}

/// Print the run's LLM call count and token totals (#111).
///
/// Why: the owner prices a full run from these numbers before approving it.
/// What: prints nothing when no LLM call was made; otherwise the outcome
/// counts, token totals, and the average tokens per call. Per-call rows are
/// in the `llm_usage` table.
fn print_llm_usage(u: &tga::classify::LlmUsageTotals) {
    if u.calls == 0 {
        return;
    }
    println!(
        "LLM calls: {} (adopted {}, not adopted {}, abstained {}, out-of-set {}, failed {})",
        u.calls, u.adopted, u.not_adopted, u.abstained, u.out_of_set, u.failed
    );
    println!(
        "LLM tokens: input {}, output {} ({} of {} calls reported usage)",
        u.input_tokens, u.output_tokens, u.calls_with_usage, u.calls
    );
    if u.calls_with_usage > 0 {
        let n = u.calls_with_usage as f64;
        println!(
            "LLM tokens per call: input {:.1}, output {:.1}",
            u.input_tokens as f64 / n,
            u.output_tokens as f64 / n
        );
    }
}

/// Read a `--shas` file: one SHA per line, blank lines and `#` comments
/// skipped, surrounding whitespace trimmed (#111).
fn read_sha_list(path: &std::path::Path) -> anyhow::Result<Vec<String>> {
    let text = std::fs::read_to_string(path)
        .map_err(|e| anyhow::anyhow!("cannot read --shas file {}: {e}", path.display()))?;
    Ok(text
        .lines()
        .map(str::trim)
        .filter(|l| !l.is_empty() && !l.starts_with('#'))
        .map(str::to_string)
        .collect())
}