devscout-rs 0.10.0

// The shared shape every verb's answer funnels through: the zero-hit exit
// code and its stderr note, the freshness warning, the two ambiguous-outcome
// renderers, the not-found fallback, and the one telemetry call every
// resolved query makes.

use std::cell::RefCell;
use std::io::Write;
use std::path::{Path, PathBuf};
use std::time::Instant;

use crate::exit::{EXIT_FAILURE, EXIT_NO_RESULT};
use crate::freshness::{validate, FreshnessState};
use crate::graph;
use crate::query;
use crate::query::json::J;
use crate::suggest;
use crate::telemetry;

use super::root::require_repo;

// These four notes go to STDERR, never stdout, so a zero hit leaves stdout
// exactly as empty as it was -- a caller parsing stdout sees no difference, and
// the note is advice for a human reader.
pub(crate) const ZERO_HIT_FIND: &str = "devscout find: zero hits — the manifest was searched and nothing matched. Not an error; fall back to text search (rg/grep) rather than rephrasing.";
pub(crate) const ZERO_HIT_REFS: &str = "devscout refs: zero hits — the graph was searched and no symbol matched. Not an error; fall back to text search (rg/grep) rather than rephrasing.";
pub(crate) const ZERO_HIT_READ: &str = "devscout read: zero hits — the graph was searched and no symbol matched. Not an error; fall back to text search (rg/grep) rather than rephrasing.";
pub(crate) const ZERO_HIT_IMPACT: &str = "devscout impact: zero hits — the graph was searched and no affected file came back. Not an error; fall back to text search (rg/grep) rather than rephrasing.";
pub(crate) const ZERO_HIT_TESTS: &str = "devscout tests: zero hits — the graph was searched and no symbol matched. Not an error; fall back to text search (rg/grep) rather than rephrasing.";

// The one place a zero-hit line is emitted. The "did you mean" candidates extend
// that same note rather than adding a second one; `query` carries the name the
// caller asked for on the two verbs that offer them and is `None` on the two that
// do not. A `None` note is a verb declining the advice: its answer resolved and
// is merely empty, so pointing at a text search would send the caller after
// something the graph has already answered. Broken-pipe errors are swallowed for
// the same reason `print_out` swallows them.
pub(crate) fn emit_zero_hit_note(code: i32, note: Option<&str>, cwd: &Path, query: Option<&str>) {
    let Some(note) = note else { return };
    if code != EXIT_NO_RESULT {
        return;
    }
    let mut text = String::from(note);
    let rows = query.map(|q| nearest_names(cwd, q)).unwrap_or_default();
    if !rows.is_empty() {
        text.push_str("\ndid you mean:");
        for row in rows {
            text.push('\n');
            text.push_str(&row);
        }
    }
    let stderr = std::io::stderr();
    let mut lock = stderr.lock();
    let _ = lock
        .write_all(text.as_bytes())
        .and_then(|()| lock.write_all(b"\n"));
}

// This invocation's one freshness validation, opened by the verb BEFORE it
// reads `graph.json` or `manifest.json` and finished once, by `finish_query` or
// by the stderr path. `--json` and stderr therefore describe one reading of one
// moment, and a query pays for exactly one `git status`.
//
// The slot is per-thread and per-invocation: a `begin_validation` replaces
// whatever the previous call in this process left, so an in-process test that
// runs two queries in a row can never inherit the first one's verdict.
thread_local! {
    static SLOT: RefCell<Option<Slot>> = const { RefCell::new(None) };
}

struct Slot {
    root: PathBuf,
    begin: validate::Begin,
    finished: Option<validate::Validation>,
}

// Opens the invocation's validation. Every query verb calls this as soon as it
// has a root, before any index artifact is read, so the snapshot it takes is
// genuinely earlier than the answer.
pub(crate) fn begin_validation(root: &Path, invocation_dir: &Path) {
    let begin = validate::begin(root, invocation_dir);
    SLOT.with(|slot| {
        *slot.borrow_mut() = Some(Slot {
            root: root.to_path_buf(),
            begin,
            finished: None,
        });
    });
}

// The finished validation for `root`, running it on first use. `None` when the
// slot belongs to another root -- a verb whose root came from its own path
// argument rather than the invocation directory -- so the caller falls back to
// a fresh validation of its own.
fn validation_for(root: &Path) -> Option<validate::Validation> {
    SLOT.with(|slot| {
        let mut slot = slot.borrow_mut();
        let entry = slot.as_mut()?;
        if entry.root != root {
            return None;
        }
        if entry.finished.is_none() {
            entry.finished = Some(entry.begin.finish());
        }
        entry.finished.clone()
    })
}

// Query-time index freshness, `find`/`refs`/`read`/`impact`/`tests` only: `map`
// just rebuilt the index and has nothing to say about it being stale relative to
// itself. Root resolution mirrors `require_repo`'s plain climb, never
// `require_repo_for_path`'s argument-named-file fallback. Called BEFORE
// `emit_zero_hit_note` so the two lines land on stderr in a fixed order when
// both fire for the same query. Never touches stdout, never changes the exit
// code.
pub(crate) fn emit_freshness_warning(cwd: &Path) {
    let Some(root) = crate::repo::find_scout_root(cwd).or_else(|| crate::repo::find_repo_root(cwd))
    else {
        return;
    };
    // The verb's own validation when it opened one at this root; otherwise this
    // invocation never reached a verb, and the check runs here, once.
    let validation = validation_for(&root).unwrap_or_else(|| validate::begin(&root, cwd).finish());
    let Some(warning) = validation.warning else {
        return;
    };
    let stderr = std::io::stderr();
    let mut lock = stderr.lock();
    let _ = lock
        .write_all(warning.as_bytes())
        .and_then(|()| lock.write_all(b"\n"));
}

// The nearest names a zero-hit `find`/`refs` offers, never substituted for the
// query and never run. The graph is read here rather than carried out of the
// command that just ran: this path is reached only once that command has decided
// it has nothing to print.
fn nearest_names(cwd: &Path, query: &str) -> Vec<String> {
    let Ok(root) = require_repo(cwd) else {
        return Vec::new();
    };
    let Some(g) = graph::read_graph(&root) else {
        return Vec::new();
    };
    suggest::suggestion_lines(&g.names, query)
}

// The one JSON envelope both ambiguous answers share, so an ambiguous type and
// an ambiguous member never drift into two shapes a consumer must tell apart:
// only the candidate objects differ, each in its renderer's own vocabulary.
fn ambiguous_json(q: &str, candidates: Vec<J>) -> String {
    J::Obj(vec![
        ("schema_version", J::UInt(query::SCHEMA_VERSION)),
        (
            "outcome",
            J::Str(query::Outcome::Ambiguous.as_str().to_string()),
        ),
        ("query", J::Str(q.to_string())),
        ("candidates", J::Arr(candidates)),
    ])
    .to_json_string()
}

// The refusal's own candidate objects, one per row, in the SAME order the
// rows print -- both are built from `query::pick`'s own refusal order, so the
// list a caller reads and the numbers `--pick` answers with cannot disagree.
pub(crate) fn type_candidate_object(index: &query::GraphIndex, id: &str) -> J {
    let d = query::candidate_def(index, id);
    J::Obj(vec![
        ("id", J::Str(id.to_string())),
        ("file", J::Str(d.file.clone())),
        ("line", J::UInt(d.line as u64)),
        ("kind", J::Str(d.kind.clone())),
    ])
}

// One member candidate as the refusal's own JSON object.
pub(crate) fn member_candidate_object(c: &query::MemberCandidate) -> J {
    J::Obj(vec![
        ("owner", J::Str(c.owner.clone())),
        ("name", J::Str(c.name.clone())),
        ("file", J::Str(c.file.clone())),
        ("line", J::UInt(c.line as u64)),
    ])
}

// Shared by the four graph-reading verbs -- the "never guess" house rule: name
// every candidate's `{id, def site, kind}` and exit 1. `--compact` is inert here
// (a candidate list has no wide form to narrow); `--json` carries the same facts
// under `member_ambiguous_out`'s own keys.
pub(crate) fn ambiguous_candidates_out(
    index: &query::GraphIndex,
    q: &str,
    ids: &[String],
    json: bool,
) -> (i32, String) {
    let ordered = query::type_candidates_in_refusal_order(index, ids);
    if json {
        let candidates = ordered
            .iter()
            .map(|id| type_candidate_object(index, id))
            .collect();
        return (EXIT_FAILURE, ambiguous_json(q, candidates));
    }
    let mut out = vec![format!(
        "ambiguous symbol \"{q}\" — {} candidates:",
        ordered.len()
    )];
    out.extend(
        ordered
            .iter()
            .map(|id| query::type_candidate_row(id, query::candidate_def(index, id))),
    );
    (EXIT_FAILURE, out.join("\n"))
}

// Renders a member-ambiguous outcome (`RefsResult::MemberAmbiguous` and its
// mirrors on `read`/`impact`/`tests`): one row per candidate, its declaring
// type, file and line -- NEVER the bare `{id, def site, kind}` list
// `ambiguous_candidates_out` renders for an ambiguous TYPE name. Both outcomes
// answer under the same JSON keys, so a caller branching on `outcome` reads
// either without knowing which kind of name it asked about.
pub(crate) fn member_ambiguous_out(
    q: &str,
    candidates: &[query::MemberCandidate],
    json: bool,
) -> (i32, String) {
    if json {
        let rows = candidates.iter().map(member_candidate_object).collect();
        return (EXIT_FAILURE, ambiguous_json(q, rows));
    }
    let mut out = vec![format!(
        "ambiguous member \"{q}\" — {} candidates:",
        candidates.len()
    )];
    out.extend(candidates.iter().map(query::member_candidate_row));
    (EXIT_FAILURE, out.join("\n"))
}

// Renders a fully-unresolved query (`NotFound` on every one of `refs`/`read`/
// `impact`/`tests`): `plain` unchanged under text/`--compact` -- the exact
// bytes these verbs always printed here -- and, only under `--json`, a small
// object naming the outcome. No JSON shape existed for this case before, so
// this is additive the same way `member_ambiguous_out`'s JSON arm is.
pub(crate) fn fallback_advised_out(q: &str, json: bool, plain: String) -> (i32, String) {
    if json {
        let out = J::Obj(vec![
            ("schema_version", J::UInt(query::SCHEMA_VERSION)),
            (
                "outcome",
                J::Str(query::Outcome::FallbackAdvised.as_str().to_string()),
            ),
            ("query", J::Str(q.to_string())),
        ])
        .to_json_string();
        (EXIT_NO_RESULT, out)
    } else {
        (EXIT_NO_RESULT, plain)
    }
}

// `freshness`'s own JSON shape: `state` first (`"fresh"`/`"stale"`/
// `"unknown"`), then the fields that state alone carries. `Stale`'s
// `indexedHead`/`currentHead` mirror `freshness_warning`'s own truncated
// stderr wording in spirit but are written full-length here -- a
// programmatic consumer should not have to guess where a short hash was cut.
// `pub(crate)`: the fact export states the same freshness the queries answer
// with, through this one renderer, so the two can never drift apart.
pub(crate) fn freshness_json(state: &FreshnessState) -> J {
    match state {
        FreshnessState::Fresh => J::Obj(vec![("state", J::Str("fresh".to_string()))]),
        FreshnessState::Stale {
            indexed_head,
            current_head,
            changed_files,
        } => J::Obj(vec![
            ("state", J::Str("stale".to_string())),
            ("indexedHead", J::Str(indexed_head.clone())),
            ("currentHead", J::Str(current_head.clone())),
            ("changedFiles", J::UInt(*changed_files as u64)),
        ]),
        FreshnessState::Unknown { reason } => J::Obj(vec![
            ("state", J::Str("unknown".to_string())),
            ("reason", J::Str(reason.as_str().to_string())),
        ]),
    }
}

// Appends the `next:` trailer to a rendered answer, or returns it untouched
// when nothing survived the suggestion list's own resolve check. The trailer
// is stdout's last line, so a renderer never has to know it exists -- and
// `--json`, which carries the same suggestions as a key instead, never calls
// this.
pub(crate) fn with_next_trailer(out: String, next: &[Vec<String>]) -> String {
    match crate::render::next_line(next) {
        Some(line) => format!("{out}\n{line}"),
        None => out,
    }
}

// Splices a top-level `freshness` key onto an already-rendered `--json`
// answer, as its new last key (after `outcome`) -- string surgery on the
// finished object rather than a second pass through the `J` tree, because
// every caller here already rendered a complete, correct object of its own
// and re-building it from scratch risks a byte drift the existing builders
// do not have today. Safe because every `--json` answer this crate renders
// is exactly one top-level object (`J::Obj(...).to_json_string()`), which
// always ends in exactly one `}` and never in trailing whitespace.
fn append_freshness(out: &str, state: &FreshnessState) -> String {
    debug_assert!(
        out.ends_with('}'),
        "a --json answer must be exactly one top-level object: {out}"
    );
    let mut spliced = out.strip_suffix('}').unwrap_or(out).to_string();
    spliced.push_str(",\"freshness\":");
    spliced.push_str(&freshness_json(state).to_json_string());
    spliced.push('}');
    spliced
}

// The one telemetry call every query verb makes, taking the rendered answer
// whole: the outcome and count recorded are the ones that answer carries, so a
// record can never describe a different answer than the caller was handed.
// `json` gates the `freshness` splice: only a `--json` answer is a single
// top-level object this can safely append to, and `find` (which never
// produces one) always passes `false`. Freshness is spliced BEFORE the
// telemetry call so `result_bytes` counts what is actually printed.
pub(crate) fn finish_query(
    root: &Path,
    verb: &'static str,
    seed: &str,
    start: Instant,
    json: bool,
    answer: (i32, String, query::Outcome, usize),
) -> (i32, String) {
    let (code, mut out, outcome, candidate_count) = answer;
    if json {
        let state = validation_for(root)
            .map(|v| v.state)
            .unwrap_or_else(|| validate::begin(root, root).finish().state);
        out = append_freshness(&out, &state);
    }
    telemetry::record(
        root,
        &telemetry::QueryEvent {
            verb,
            seed,
            outcome,
            candidate_count,
        },
        start.elapsed(),
        out.len(),
    );
    (code, out)
}