sherd 0.6.0

two-axis federation of SPEC.md and source over a dir DAG, for small-context local models
Documentation
//! `plan`, `triage`, `ask` and `tdd` -- the verbs that choose or take the next step.

use super::*;

#[cfg(feature = "ollama")]
pub(super) fn ask(root: &Path, dir: &Path, question: &str) -> ExitCode {
    let Ok(p) = lens::pack(root, dir, lens::Depth::Rule) else {
        eprintln!("sherd: {}: no pack", dir.display());
        return ExitCode::from(2);
    };
    use std::io::Write;
    let prompt = format!("{}\n\n---\n{question}\n", p.text);
    let eta = crate::ollama::predict(p.cost.tokens);
    eprintln!(
        "# pack {} · {} nodes · eta {:.0}s cold / {:.0}s if cached",
        p.cost,
        p.chain.len(),
        eta.total_s(),
        eta.cached_s()
    );
    eprint!("# ");
    let _ = std::io::stderr().flush();
    let mut n = 0usize;
    match crate::ollama::generate_with(&prompt, eta, &mut |c| {
        if crate::ollama::verbose() {
            eprint!("{c}")
        } else {
            n += 1;
            if n.is_multiple_of(25) {
                eprint!(".")
            }
        }
        let _ = std::io::stderr().flush();
    }) {
        Ok(r) => {
            eprintln!();
            println!("{}", r.text);
            let actual = r.ms as f64 / 1000.0;
            eprintln!(
                "[{} sent · {} gen · {actual:.1}s (eta {:.0}s, {:+.0}%){}]",
                r.prompt_tokens,
                r.eval_tokens,
                if crate::ollama::last_cached() {
                    eta.cached_s()
                } else {
                    eta.total_s()
                },
                (actual
                    - if crate::ollama::last_cached() {
                        eta.cached_s()
                    } else {
                        eta.total_s()
                    })
                    / if crate::ollama::last_cached() {
                        eta.cached_s()
                    } else {
                        eta.total_s()
                    }
                    * 100.0,
                if crate::ollama::last_cached() {
                    " prefix CACHED"
                } else {
                    ""
                }
            );
            ExitCode::SUCCESS
        }
        Err(e) => {
            eprintln!("sherd: {e}");
            ExitCode::from(2)
        }
    }
}

#[cfg(feature = "ollama")]
pub(super) fn tdd_cmd(
    root: &Path,
    dir: &Path,
    invariant: &str,
    task: &str,
) -> ExitCode {
    match crate::tdd::drive(root, dir, invariant, task, 3) {
        Ok(_) => ExitCode::SUCCESS,
        Err(e) => {
            eprintln!("sherd: {e}");
            ExitCode::from(1)
        }
    }
}

pub(super) fn plan_cmd(
    root: &Path,
    milestone: Option<&str>,
    json: bool,
) -> ExitCode {
    plan_with(root, milestone, json, &state::State::load())
}

/// `plan` over a store it READS -- believability and the kept/tried record --
/// and never writes (`src/plan:V7`, `B12`).
///
/// It used to clear every `plan` key, record one per step and save, on both
/// output forms. Nothing read those keys -- `apply` re-derives the plan -- so
/// a read-only verb rewrote a store every worktree shares. Taking the store
/// as a value is also what lets a test hand it a file of its own.
pub(super) fn plan_with(
    root: &Path,
    milestone: Option<&str>,
    json: bool,
    st: &state::State,
) -> ExitCode {
    // V27: every node is read BEFORE anything is planned, and one that
    // cannot be read is a refusal -- skipping it dropped its rows (B17).
    let unread = plan::unreadable(root);
    for (path, e) in &unread {
        eprintln!(
            "plan: {}: cannot read -- {e}. a node discovered and not read is a failure, \
             not a node with no open rows (src/plan:V27)",
            path.display()
        );
    }
    if !unread.is_empty() {
        return ExitCode::from(2);
    }
    let (p, outside) = plan::plan_in(root, milestone);
    let est: Vec<u64> = p
        .steps
        .iter()
        .map(|t| {
            lens::pack(root, &root.join(&t.node), lens::Depth::Rule)
                .map_or(0, |k| k.cost.tokens)
        })
        .collect();
    // V26: a shell step's scripts, `None` for a Rust step.
    let touches: Vec<Option<Vec<String>>> =
        p.steps.iter().map(|t| plan::footprint(root, t)).collect();
    if json {
        println!(
            "{}",
            plan::to_json_with(st, &p, (milestone, outside), &est, &touches)
        );
        return ExitCode::SUCCESS;
    }

    let scope = milestone.map_or(String::new(), |m| format!(" in {m}"));
    println!(
        "HORIZON {} of {} open rows{scope} · {} unmanaged\n",
        p.steps.len(),
        p.total_open,
        p.unmanaged.len()
    );
    // V24: rows the filter set aside are named, never silently dropped.
    if outside > 0 {
        println!(
            "  {outside} open rows sit in nodes that declare no milestones -- not in any\n  milestone, so not in this plan.\n"
        );
    }
    for (((i, t), est), foot) in
        p.steps.iter().enumerate().zip(&est).zip(&touches)
    {
        let c = plan::Confidence::of(i);
        let (tried, kept) = plan::record(&t.node);
        let score = if tried == 0 {
            "untried".to_string()
        } else {
            format!("{kept}/{tried} kept")
        };
        println!(
            "{}. {} {:<11} {} {}",
            i + 1,
            c.label(),
            t.node.display(),
            t.id,
            t.text
        );
        println!(
            "      believability {:.2} ({score})",
            plan::believability(&t.node)
        );
        let why = plan::invalidators_of(c, t, foot.as_deref()).join(" · ");
        match foot {
            None => {
                println!("      ~{est} tok context · invalidated by: {why}\n")
            }
            Some(scripts) => println!(
                "      ~{est} tok context · touches {}\n      invalidated by: {why}\n",
                if scripts.is_empty() {
                    "unknown -- the row cites no script".to_string()
                } else {
                    scripts.join(", ")
                }
            ),
        }
    }
    if p.steps.is_empty() {
        println!("  nothing actionable.\n");
    }
    // V3: say what is NOT managed. Silence would read as coverage.
    println!("UNMANAGED ({}):", p.unmanaged.len());
    let mut by: std::collections::BTreeMap<&str, usize> =
        std::collections::BTreeMap::new();
    for (_, k) in &p.unmanaged {
        *by.entry(k.why()).or_default() += 1;
    }
    for (why, n) in by {
        println!("  {n:3}  {why}");
    }
    println!(
        "\nRun `sherd plan` again after each apply -- applying a task edits\nthe spec that plans the next one, so this list goes stale."
    );
    ExitCode::SUCCESS
}

pub(super) fn triage_cmd(root: &Path) -> ExitCode {
    let rows = plan::triage(root);
    let mut moves: std::collections::BTreeMap<&str, Vec<(String, String)>> =
        std::collections::BTreeMap::new();
    let (mut decompose, mut keep) = (Vec::new(), Vec::new());
    for (t, k, p) in &rows {
        let id = format!("{} {}", t.node.display(), t.id);
        match p {
            split::Proposal::Move(n) => {
                moves.entry(n).or_default().push((id, t.text.clone()))
            }
            split::Proposal::Decompose(ns) => {
                decompose.push((id, t.text.clone(), ns.join(" + ")))
            }
            split::Proposal::Keep => keep.push((id, t.text.clone(), k.why())),
        }
    }
    println!(
        "TRIAGE of {} unmanaged rows -- ADVISORY, prose classification is\n\
              wrong-by-default (plan V4). Confirm each before moving.\n",
        rows.len()
    );
    let total: usize = moves.values().map(Vec::len).sum();
    println!("MOVE to a node ({total}):");
    for (node, rs) in &moves {
        println!("  -> src/{node}");
        for (id, text) in rs {
            println!(
                "       {id:14} {}",
                text.chars().take(66).collect::<String>()
            );
        }
    }
    println!("\nDECOMPOSE, spans several nodes ({}):", decompose.len());
    for (id, text, ns) in &decompose {
        println!(
            "  {id:14} [{ns}]  {}",
            text.chars().take(50).collect::<String>()
        );
    }
    println!("\nKEEP at root ({}):", keep.len());
    for (id, text, why) in &keep {
        println!(
            "  {id:14} {:<48} ({why})",
            text.chars().take(48).collect::<String>()
        );
    }
    ExitCode::SUCCESS
}

#[cfg(test)]
#[path = "tests/steps.rs"]
mod tests;