lean_ctx_server/tools/

ctx_graph.rs

// SPDX-License-Identifier: Apache-2.0
use std::collections::HashMap;
use std::path::Path;

use lean_ctx::core::graph_index;
use lean_ctx::core::graph_provider::{self, GraphProvider};
use lean_ctx::core::tokens::count_tokens;

#[allow(clippy::too_many_arguments)]
pub fn handle(
    action: &str,
    path: Option<&str>,
    root: &str,
    cache: &mut lean_ctx::core::cache::SessionCache,
    crp_mode: crate::tools::CrpMode,
    depth: Option<usize>,
    kind: Option<&str>,
    to: Option<&str>,
    format: Option<&str>,
    since: Option<&str>,
) -> String {
    match action {
        "build" => handle_build(root),
        "related" => handle_related(path, root),
        "symbol" => handle_symbol(path, root, cache, crp_mode),
        "impact" => handle_impact(path, root),
        "status" => handle_status(root),
        "enrich" => handle_enrich(root),
        "context" => handle_context_query(path, root),
        "diagram" => crate::tools::ctx_graph_diagram::handle(path, depth, kind, root),
        "neighbors" => crate::tools::ctx_graph_primitives::neighbors(path, root, depth, format),
        "path" => crate::tools::ctx_graph_primitives::shortest_path(path, to, root, format),
        "explain" => crate::tools::ctx_graph_primitives::explain(path, root, format),
        "diff" => crate::tools::ctx_graph_diff::diff(since, root, format),
        _ => "Unknown action. Use: build, related, symbol, impact, status, enrich, context, \
diagram, neighbors, path, explain, diff"
            .to_string(),
    }
}

fn handle_build(root: &str) -> String {
    let index = graph_index::scan(root);

    let mut by_lang: HashMap<&str, (usize, usize)> = HashMap::new();
    for entry in index.files.values() {
        let e = by_lang.entry(&entry.language).or_insert((0, 0));
        e.0 += 1;
        e.1 += entry.token_count;
    }

    let mut result = Vec::new();
    result.push(format!(
        "Project Graph: {} files, {} symbols, {} edges",
        index.file_count(),
        index.symbol_count(),
        index.edge_count()
    ));

    let mut langs: Vec<_> = by_lang.iter().collect();
    langs.sort_by_key(|(_, v)| std::cmp::Reverse(v.1));
    result.push("\nLanguages:".to_string());
    for (lang, (count, tokens)) in &langs {
        result.push(format!("  {lang}: {count} files, {tokens} tok"));
    }

    let mut import_counts: HashMap<&str, usize> = HashMap::new();
    for edge in &index.edges {
        if edge.kind == "import" {
            *import_counts.entry(&edge.to).or_insert(0) += 1;
        }
    }
    let mut hotspots: Vec<_> = import_counts.iter().collect();
    hotspots.sort_by_key(|x| std::cmp::Reverse(*x.1));

    if !hotspots.is_empty() {
        result.push(format!("\nMost imported ({}):", hotspots.len().min(10)));
        for (module, count) in hotspots.iter().take(10) {
            result.push(format!("  {module}: imported by {count} files"));
        }
    }

    if let Some(dir) = GraphProvider::index_dir(root) {
        result.push(format!(
            "\nIndex saved: {}",
            lean_ctx::core::protocol::shorten_path(&dir.to_string_lossy())
        ));
    }

    let output = result.join("\n");
    let tokens = count_tokens(&output);
    format!("{output}\n[ctx_graph build: {tokens} tok]")
}

fn handle_related(path: Option<&str>, root: &str) -> String {
    let Some(target) = path else {
        return "path is required for 'related' action".to_string();
    };

    let Some(open) = graph_provider::open_or_build(root) else {
        return "No graph index found. Run ctx_graph with action='build' first.".to_string();
    };

    let rel_target = graph_index::graph_relative_key(target, root);

    let related = open.provider.related(&rel_target, 2);
    if related.is_empty() {
        return format!(
            "No related files found for {}",
            lean_ctx::core::protocol::shorten_path(target)
        );
    }

    let mut result = format!(
        "Files related to {} ({}):\n",
        lean_ctx::core::protocol::shorten_path(target),
        related.len()
    );
    for r in &related {
        result.push_str(&format!(
            "  {}\n",
            lean_ctx::core::protocol::shorten_path(r)
        ));
    }

    let tokens = count_tokens(&result);
    format!("{result}[ctx_graph related: {tokens} tok]")
}

fn handle_symbol(
    path: Option<&str>,
    root: &str,
    cache: &mut lean_ctx::core::cache::SessionCache,
    crp_mode: crate::tools::CrpMode,
) -> String {
    let Some(spec) = path else {
        return "path is required for 'symbol' action (format: <file>::<symbol>, or a bare <symbol> name)".to_string();
    };

    let Some(open) = graph_provider::open_or_build(root) else {
        return "No graph index found. Run ctx_graph with action='build' first.".to_string();
    };

    // Bare symbol name (no `::`): resolve against the symbol table so GDScript
    // (and every other language) symbols are reachable without a file qualifier
    // (#314).
    let Some((file_part, symbol_name)) = spec.split_once("::") else {
        return resolve_bare_symbol(&open.provider, spec, root, cache, crp_mode);
    };

    let rel_file = graph_index::graph_relative_key(file_part, root);

    let key = format!("{rel_file}::{symbol_name}");
    let Some(symbol) = open.provider.get_symbol(&key) else {
        let available = open
            .provider
            .find_symbols(symbol_name, Some(&rel_file), None);
        if available.is_empty() {
            return format!(
                "Symbol '{symbol_name}' not found in {rel_file}. Run ctx_graph action='build' to update the index."
            );
        }
        let names: Vec<String> = available
            .iter()
            .take(10)
            .map(|s| format!("{}::{}", s.file, s.name))
            .collect();
        return format!(
            "Symbol '{symbol_name}' not found in {rel_file}.\nAvailable symbols:\n  {}",
            names.join("\n  ")
        );
    };

    let abs_path = if Path::new(file_part).is_absolute() {
        file_part.to_string()
    } else {
        Path::new(root)
            .join(rel_file.trim_start_matches(['/', '\\']))
            .to_string_lossy()
            .to_string()
    };

    render_symbol_snippet(&symbol, &abs_path, &rel_file, root, cache, crp_mode)
}

/// Resolve a bare symbol name (no `<file>::` qualifier) against the symbol table.
/// One unambiguous hit renders the snippet; otherwise the candidates are listed
/// so the caller can disambiguate with `<file>::<symbol>` (#314).
fn resolve_bare_symbol(
    provider: &GraphProvider,
    name: &str,
    root: &str,
    cache: &mut lean_ctx::core::cache::SessionCache,
    crp_mode: crate::tools::CrpMode,
) -> String {
    let matches = provider.find_symbols(name, None, None);
    if matches.is_empty() {
        return format!(
            "Symbol '{name}' not found. Run ctx_graph action='build' to update the index."
        );
    }

    let name_lower = name.to_lowercase();
    let exact: Vec<&graph_provider::SymbolInfo> = matches
        .iter()
        .filter(|s| s.name.to_lowercase() == name_lower)
        .collect();

    if let [only] = exact.as_slice() {
        let abs_path = Path::new(root)
            .join(only.file.trim_start_matches(['/', '\\']))
            .to_string_lossy()
            .to_string();
        return render_symbol_snippet(only, &abs_path, &only.file, root, cache, crp_mode);
    }

    // Several identically-named symbols, or only substring hits → list them.
    let shortlist: Vec<&graph_provider::SymbolInfo> = if exact.is_empty() {
        matches.iter().collect()
    } else {
        exact
    };
    let mut lines = vec![format!(
        "Symbol '{name}' matches {} entries — pick one with `<file>::{name}`:",
        shortlist.len()
    )];
    for s in shortlist.iter().take(15) {
        lines.push(format!(
            "  {}::{} ({}, {}:{})",
            lean_ctx::core::protocol::shorten_path(&s.file),
            s.name,
            s.kind,
            s.start_line,
            s.end_line
        ));
    }
    lines.join("\n")
}

/// Render a symbol's source snippet with the standard token-savings footer.
/// Shared by the qualified (`<file>::<symbol>`) and bare-name resolution paths.
///
/// The graph index is a discovery hint, not an authorization: the snippet is
/// cut from the source as the common rooted admitted reader delivers it NOW
/// (G01), under `root`. A source that is withheld yields its content-free
/// reason, never the lines the index points at.
fn render_symbol_snippet(
    symbol: &graph_provider::SymbolInfo,
    abs_path: &str,
    rel_display: &str,
    root: &str,
    cache: &mut lean_ctx::core::cache::SessionCache,
    crp_mode: crate::tools::CrpMode,
) -> String {
    use crate::tools::admitted_sources::SourceRead;
    let mut remaining = lean_ctx::core::limits::max_read_bytes();
    let content = match crate::tools::admitted_sources::read(abs_path, root, TOOL, &mut remaining) {
        SourceRead::Admitted(read) => read.content,
        SourceRead::Withheld(reason) | SourceRead::Unavailable(reason) => {
            return format!("Cannot read {abs_path}: {reason}");
        }
    };

    let lines: Vec<&str> = content.lines().collect();
    let start = symbol.start_line.saturating_sub(1);
    let end = symbol.end_line.min(lines.len());

    if start >= lines.len() {
        // The read path admits only inside a request scope; bind it so this
        // fallback is admitted for every caller (MCP dispatch and the CLI).
        return crate::tools::admitted_sources::as_agent_acquisition(root, || {
            crate::tools::ctx_read::handle(cache, abs_path, "full", crp_mode)
        });
    }

    let mut result = format!(
        "{}::{} ({}:{}-{})\n",
        lean_ctx::core::protocol::shorten_path(rel_display),
        symbol.name,
        symbol.kind,
        symbol.start_line,
        symbol.end_line
    );

    for (i, line) in lines[start..end].iter().enumerate() {
        result.push_str(&format!("{:>4}|{}\n", start + i + 1, line));
    }

    let tokens = count_tokens(&result);
    let full_tokens = count_tokens(&content);
    let saved = full_tokens.saturating_sub(tokens);
    let pct = if full_tokens > 0 {
        (saved as f64 / full_tokens as f64 * 100.0).round() as usize
    } else {
        0
    };

    format!("{result}[ctx_graph symbol: {tokens} tok (full file: {full_tokens} tok, -{pct}%)]")
}

/// Tool identity the sources are read for (path jail, role rules, audit).
const TOOL: &str = "ctx_graph";

/// The admitted text of `path` (relative to `root`, or absolute inside it),
/// for derivations that only steer matching and are never rendered. `None`
/// when the source is absent, unreadable or withheld.
fn admitted_text(path: &str, root: &str) -> Option<String> {
    let mut remaining = lean_ctx::core::limits::max_read_bytes();
    match crate::tools::admitted_sources::read(path, root, TOOL, &mut remaining) {
        crate::tools::admitted_sources::SourceRead::Admitted(read) => Some(read.content),
        crate::tools::admitted_sources::SourceRead::Withheld(_)
        | crate::tools::admitted_sources::SourceRead::Unavailable(_) => None,
    }
}

fn file_path_to_module_prefixes(
    rel_path: &str,
    project_root: &str,
    provider: &GraphProvider,
) -> Vec<String> {
    let rel_path_slash = graph_index::graph_match_key(rel_path);
    let without_ext = rel_path_slash
        .strip_suffix(".rs")
        .or_else(|| rel_path_slash.strip_suffix(".ts"))
        .or_else(|| rel_path_slash.strip_suffix(".tsx"))
        .or_else(|| rel_path_slash.strip_suffix(".js"))
        .or_else(|| rel_path_slash.strip_suffix(".py"))
        .or_else(|| rel_path_slash.strip_suffix(".kt"))
        .or_else(|| rel_path_slash.strip_suffix(".kts"))
        .or_else(|| rel_path_slash.strip_suffix(".gd"))
        .unwrap_or(&rel_path_slash);

    let module_path = without_ext
        .strip_prefix("src/")
        .unwrap_or(without_ext)
        .replace('/', "::");

    let module_path = if module_path.ends_with("::mod") {
        module_path
            .strip_suffix("::mod")
            .unwrap_or(&module_path)
            .to_string()
    } else {
        module_path
    };

    // Manifest and source are read through the admitted reader like any other
    // source: a withheld manifest contributes no crate name.
    let crate_name = admitted_text("Cargo.toml", project_root)
        .or_else(|| admitted_text("package.json", project_root))
        .and_then(|c| {
            c.lines()
                .find(|l| l.contains("\"name\"") || l.starts_with("name"))
                .and_then(|l| l.split('"').nth(1))
                .map(|n| n.replace('-', "_"))
        })
        .unwrap_or_default();

    let mut prefixes = vec![
        format!("crate::{module_path}"),
        format!("super::{module_path}"),
        module_path.clone(),
    ];
    if !crate_name.is_empty() {
        prefixes.insert(0, format!("{crate_name}::{module_path}"));
    }

    let ext = Path::new(rel_path)
        .extension()
        .and_then(|e| e.to_str())
        .unwrap_or("");
    if ext == "gd" {
        // GDScript import edges resolve to the target script's project-relative
        // path (e.g. "actors/Player.gd"), not a Rust-style module path, so the
        // path itself is the key that `graph impact` must match on (#314).
        prefixes.push(rel_path_slash.clone());
    }
    if matches!(ext, "kt" | "kts") {
        if let Some(content) = admitted_text(rel_path.trim_start_matches(['/', '\\']), project_root)
            && let Some(package_name) = content.lines().map(str::trim).find_map(|line| {
                line.strip_prefix("package ")
                    .map(|rest| rest.trim().trim_end_matches(';').to_string())
            })
        {
            prefixes.push(package_name.clone());
            if let Some(entry) = provider.get_file_entry(rel_path) {
                for export in &entry.exports {
                    prefixes.push(format!("{package_name}.{export}"));
                }
            }
            if let Some(file_stem) = Path::new(rel_path).file_stem().and_then(|s| s.to_str()) {
                prefixes.push(format!("{package_name}.{file_stem}"));
            }
        }
    }

    prefixes.sort();
    prefixes.dedup();
    prefixes
}

fn edge_matches_file(edge_to: &str, module_prefixes: &[String]) -> bool {
    module_prefixes.iter().any(|prefix| {
        edge_to == *prefix
            || edge_to.starts_with(&format!("{prefix}::"))
            || edge_to.starts_with(&format!("{prefix},"))
    })
}

fn handle_impact(path: Option<&str>, root: &str) -> String {
    let Some(target) = path else {
        return "path is required for 'impact' action".to_string();
    };

    let Some(open) = graph_provider::open_or_build(root) else {
        return "No graph index found. Run ctx_graph with action='build' first.".to_string();
    };
    let gp = &open.provider;

    let rel_target = graph_index::graph_relative_key(target, root);
    let module_prefixes = file_path_to_module_prefixes(&rel_target, root, gp);

    // Direct importers come from two complementary lookups, merged + deduped:
    //   1. `dependents(rel_target)` — the import resolver records edges keyed by
    //      the target's project-relative *file path*, so this is the primary,
    //      backend-agnostic match (works for Rust/TS/JS/Python/…).
    //   2. `edge_matches_file` over module-path prefixes — additionally catches
    //      edges keyed by a module/symbol path rather than a file (Rust `mod`,
    //      Kotlin package, barrel re-exports), which the file-path match misses.
    let mut direct: Vec<String> = gp.dependents(&rel_target);
    for e in gp.edges_by_kind("import") {
        if edge_matches_file(&e.to, &module_prefixes) && !direct.contains(&e.from) {
            direct.push(e.from);
        }
    }
    direct.retain(|d| *d != rel_target);

    let mut all_dependents: Vec<String> = direct.clone();
    for d in &direct {
        for dep in gp.dependents(d) {
            if !all_dependents.contains(&dep) && dep != rel_target {
                all_dependents.push(dep);
            }
        }
    }

    if all_dependents.is_empty() {
        return format!(
            "No files depend on {}",
            lean_ctx::core::protocol::shorten_path(target)
        );
    }

    let mut result = format!(
        "Impact of {} ({} dependents):\n",
        lean_ctx::core::protocol::shorten_path(target),
        all_dependents.len()
    );

    if !direct.is_empty() {
        result.push_str(&format!("\nDirect ({}):\n", direct.len()));
        for d in &direct {
            result.push_str(&format!(
                "  {}\n",
                lean_ctx::core::protocol::shorten_path(d)
            ));
        }
    }

    let indirect: Vec<&String> = all_dependents
        .iter()
        .filter(|d| !direct.contains(d))
        .collect();
    if !indirect.is_empty() {
        result.push_str(&format!("\nIndirect ({}):\n", indirect.len()));
        for d in &indirect {
            result.push_str(&format!(
                "  {}\n",
                lean_ctx::core::protocol::shorten_path(d)
            ));
        }
    }

    let tokens = count_tokens(&result);
    format!("{result}[ctx_graph impact: {tokens} tok]")
}

fn handle_status(root: &str) -> String {
    let Some(open) = graph_provider::open_best_effort(root) else {
        return "No graph index. Run ctx_graph action='build' to create one.".to_string();
    };
    let gp = &open.provider;

    let file_paths = gp.file_paths();
    let mut by_lang: HashMap<String, usize> = HashMap::new();
    let mut total_tokens = 0usize;
    for path in &file_paths {
        if let Some(entry) = gp.get_file_entry(path) {
            *by_lang.entry(entry.language).or_insert(0) += 1;
            total_tokens += entry.token_count;
        }
    }

    let mut langs: Vec<_> = by_lang.iter().collect();
    langs.sort_by_key(|item| std::cmp::Reverse(*item.1));
    let lang_summary: String = langs
        .iter()
        .take(5)
        .map(|(l, c)| format!("{l}:{c}"))
        .collect::<Vec<_>>()
        .join(" ");

    let semantic = lean_ctx::core::property_graph::CodeGraph::open(root).map_or_else(
        |_| String::new(),
        |g| {
            let mode = lean_ctx::core::config::SemanticMode::for_project(root);
            format!(
                "\n{}",
                lean_ctx::core::semantic::status_line(&g, mode, root)
            )
        },
    );
    format!(
        "Graph: {} files, {} symbols, {} edges ({:?}) | {} tok total\nLast scan: {}\nLanguages: {lang_summary}{semantic}\nStored: {}",
        gp.file_count(),
        gp.symbol_count(),
        gp.edge_count().unwrap_or(0),
        open.source,
        total_tokens,
        gp.last_scan(),
        GraphProvider::index_dir(root)
            .map(|d| d.to_string_lossy().to_string())
            .unwrap_or_default()
    )
}

/// The name of the edge end `node_id`, when that reference may be served now
/// (G04): a file or module node while its file is served, a symbol or test
/// node while its file still serves the name. `None`: the end is skipped as
/// if it were not in the graph. A node without a file on record (commit,
/// knowledge, issue, CI run) follows the originless rule (`serves_node_parts`).
fn served_node_name(
    graph: &lean_ctx::core::property_graph::CodeGraph,
    node_id: i64,
) -> Option<String> {
    let conn = graph.connection();
    let Ok((name, kind, file_path)) = conn.query_row(
        "SELECT n.name, n.kind, p.path FROM nodes n JOIN paths p ON p.id = n.file_id \
         WHERE n.id = ?1",
        rusqlite::params![node_id],
        |row| {
            Ok((
                row.get::<_, String>(0)?,
                row.get::<_, String>(1)?,
                row.get::<_, String>(2)?,
            ))
        },
    ) else {
        return Some(format!("node#{node_id}"));
    };
    let served = graph.serves_node_parts(&kind, &file_path, &name, None);
    served.then_some(name)
}

fn handle_enrich(root: &str) -> String {
    let graph = match lean_ctx::core::property_graph::CodeGraph::open(root) {
        Ok(g) => g,
        Err(e) => return format!("Failed to open graph: {e}"),
    };

    match lean_ctx::core::graph_enricher::enrich_graph(&graph, Path::new(root), 500) {
        Ok(stats) => {
            let node_count = graph.node_count().unwrap_or(0);
            let edge_count = graph.edge_count().unwrap_or(0);
            format!(
                "Graph enriched.\n{}\nTotal: {node_count} nodes, {edge_count} edges",
                stats.format_summary()
            )
        }
        Err(e) => format!("Enrichment failed: {e}"),
    }
}

fn handle_context_query(query: Option<&str>, root: &str) -> String {
    let Some(query) = query else {
        return "Usage: ctx_graph action=context path=\"<query or file path>\"".to_string();
    };

    let graph = match lean_ctx::core::property_graph::CodeGraph::open(root) {
        Ok(g) => g,
        Err(e) => return format!("Failed to open graph: {e}"),
    };

    let gp = graph_provider::open_or_build(root);
    let mut result = Vec::new();

    // A node whose file is no longer served is treated as not in the graph.
    if let Ok(Some(node)) = graph.get_node_by_path(query)
        && graph.serves_file(&node.file_path)
    {
        result.push(format!("## Context for `{query}`\n"));

        if let Some(node_id) = node.id {
            let edges_out = graph.edges_from(node_id).unwrap_or_default();
            let edges_in = graph.edges_to(node_id).unwrap_or_default();

            let mut tests: Vec<String> = Vec::new();
            let mut commits: Vec<String> = Vec::new();
            let mut knowledge: Vec<String> = Vec::new();
            let mut imports: Vec<String> = Vec::new();
            let mut dependents: Vec<String> = Vec::new();

            for edge in &edges_out {
                let Some(target) = served_node_name(&graph, edge.target_id) else {
                    continue;
                };
                match edge.kind {
                    lean_ctx::core::property_graph::EdgeKind::TestedBy => tests.push(target),
                    lean_ctx::core::property_graph::EdgeKind::ChangedIn => commits.push(target),
                    lean_ctx::core::property_graph::EdgeKind::MentionedIn => {
                        knowledge.push(target);
                    }
                    lean_ctx::core::property_graph::EdgeKind::Imports => imports.push(target),
                    _ => {}
                }
            }

            for edge in &edges_in {
                if edge.kind == lean_ctx::core::property_graph::EdgeKind::Imports
                    && let Some(source) = served_node_name(&graph, edge.source_id)
                {
                    dependents.push(source);
                }
            }

            if !tests.is_empty() {
                result.push(format!("**Tests ({}):** {}", tests.len(), tests.join(", ")));
            }
            if !commits.is_empty() {
                result.push(format!(
                    "**Recent commits ({}):** {}",
                    commits.len(),
                    commits
                        .iter()
                        .take(5)
                        .cloned()
                        .collect::<Vec<_>>()
                        .join(", ")
                ));
            }
            if !knowledge.is_empty() {
                result.push(format!(
                    "**Knowledge ({}):** {}",
                    knowledge.len(),
                    knowledge.join(", ")
                ));
            }
            if !imports.is_empty() {
                result.push(format!(
                    "**Imports ({}):** {}",
                    imports.len(),
                    imports
                        .iter()
                        .take(10)
                        .cloned()
                        .collect::<Vec<_>>()
                        .join(", ")
                ));
            }
            if !dependents.is_empty() {
                result.push(format!(
                    "**Depended on by ({}):** {}",
                    dependents.len(),
                    dependents
                        .iter()
                        .take(10)
                        .cloned()
                        .collect::<Vec<_>>()
                        .join(", ")
                ));
            }

            if let Ok(impact) = graph.impact_analysis(query, 3) {
                // Only files that are served now count toward the radius.
                let affected = impact
                    .affected_files
                    .iter()
                    .filter(|file| graph.serves_file(file))
                    .count();
                if affected > 0 {
                    result.push(format!("**Impact radius:** {affected} files within 3 hops"));
                }
            }
        }
    } else {
        result.push(format!("## Search: `{query}`\n"));

        // Symbol names (e.g. GDScript `_ready`, or any function/type) live in the
        // GraphIndex, not the PropertyGraph node table, so resolve them here — a
        // bare concept query should return hits instead of "nothing found" (#314).
        let mut symbols = gp
            .as_ref()
            .map(|o| o.provider.find_symbols(query, None, None))
            .unwrap_or_default();
        let q_lower = query.to_lowercase();
        symbols.sort_by(|a, b| {
            (a.name.to_lowercase() != q_lower)
                .cmp(&(b.name.to_lowercase() != q_lower))
                .then_with(|| a.file.cmp(&b.file))
                .then_with(|| a.start_line.cmp(&b.start_line))
        });
        if !symbols.is_empty() {
            result.push(format!("**Symbols ({}):**", symbols.len()));
            for s in symbols.iter().take(15) {
                result.push(format!(
                    "  - {}::{} ({}, {}:{})",
                    lean_ctx::core::protocol::shorten_path(&s.file),
                    s.name,
                    s.kind,
                    s.start_line,
                    s.end_line
                ));
            }
        }

        let related = gp
            .as_ref()
            .map(|o| o.provider.related(query, 2))
            .unwrap_or_default();
        if !related.is_empty() {
            result.push(format!("**Related files ({}):**", related.len()));
            for f in related.iter().take(15) {
                result.push(format!("  - {f}"));
            }
        }

        if symbols.is_empty() && related.is_empty() {
            result.push("No matching nodes found in graph.".to_string());
        }
    }

    result.join("\n")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_edge_matches_file_crate_prefix() {
        let prefixes = vec![
            "lean_ctx::core::cache".to_string(),
            "crate::core::cache".to_string(),
            "super::core::cache".to_string(),
            "core::cache".to_string(),
        ];
        assert!(edge_matches_file(
            "lean_ctx::core::cache::SessionCache",
            &prefixes
        ));
        assert!(edge_matches_file(
            "crate::core::cache::SessionCache",
            &prefixes
        ));
        assert!(edge_matches_file("crate::core::cache", &prefixes));
        assert!(!edge_matches_file(
            "lean_ctx::core::config::Config",
            &prefixes
        ));
        assert!(!edge_matches_file("crate::core::cached_reader", &prefixes));
    }

    #[test]
    fn test_file_path_to_module_prefixes_rust() {
        let gp = GraphProvider::GraphIndex(lean_ctx::core::graph_index::ProjectIndex::new(
            "/nonexistent",
        ));
        let prefixes = file_path_to_module_prefixes("src/core/cache.rs", "/nonexistent", &gp);
        assert!(prefixes.contains(&"crate::core::cache".to_string()));
        assert!(prefixes.contains(&"core::cache".to_string()));
    }

    #[test]
    fn test_file_path_to_module_prefixes_mod_rs() {
        let gp = GraphProvider::GraphIndex(lean_ctx::core::graph_index::ProjectIndex::new(
            "/nonexistent",
        ));
        let prefixes = file_path_to_module_prefixes("src/core/mod.rs", "/nonexistent", &gp);
        assert!(prefixes.contains(&"crate::core".to_string()));
        assert!(!prefixes.iter().any(|p| p.contains("mod")));
    }

    #[test]
    fn test_file_path_to_module_prefixes_gd_uses_path() {
        // GDScript import edges store the resolved project-relative path, so the
        // path itself must be among the prefixes `graph impact` matches on (#314).
        let gp = GraphProvider::GraphIndex(lean_ctx::core::graph_index::ProjectIndex::new(
            "/nonexistent",
        ));
        let prefixes = file_path_to_module_prefixes("actors/Player.gd", "/nonexistent", &gp);
        assert!(
            prefixes.contains(&"actors/Player.gd".to_string()),
            "got: {prefixes:?}"
        );
    }

    #[test]
    fn test_edge_matches_file_gd_path() {
        let prefixes = vec!["actors/Base.gd".to_string()];
        assert!(edge_matches_file("actors/Base.gd", &prefixes));
        assert!(!edge_matches_file("actors/Enemy.gd", &prefixes));
    }
}

/// End-to-end GDScript graph coverage on a real Godot fixture (#314): four `.gd`
/// scripts with `_ready` definitions and `res://` import edges, exercised through
/// the public graph actions (context / impact / bare symbol).
#[cfg(test)]
mod gdscript_p0_tests {
    use super::*;

    fn write(root: &std::path::Path, rel: &str, content: &str) {
        let p = root.join(rel);
        std::fs::create_dir_all(p.parent().unwrap()).unwrap();
        std::fs::write(p, content).unwrap();
    }

    /// Minimal Godot project: `Player`/`Enemy` extend `Base`, `main` preloads
    /// `Player`; every script defines `_ready`. Returns (tempdir guard, root).
    fn godot_fixture() -> (tempfile::TempDir, String) {
        let tmp = tempfile::tempdir().expect("tempdir");
        let data = tmp.path().join("data");
        std::fs::create_dir_all(&data).unwrap();
        lean_ctx::test_env::set_var("LEAN_CTX_DATA_DIR", data.to_string_lossy().to_string());

        let proj = tmp.path().join("game");
        std::fs::create_dir_all(&proj).unwrap();
        write(
            &proj,
            "project.godot",
            "[application]\nconfig/name=\"Fixture\"\n",
        );
        write(
            &proj,
            "actors/Base.gd",
            "extends Node\n\nfunc _ready():\n\tpass\n",
        );
        write(
            &proj,
            "actors/Player.gd",
            "extends \"res://actors/Base.gd\"\n\nfunc _ready():\n\tprint(\"player\")\n",
        );
        write(
            &proj,
            "actors/Enemy.gd",
            "extends \"res://actors/Base.gd\"\n\nfunc _ready():\n\tprint(\"enemy\")\n",
        );
        write(
            &proj,
            "main.gd",
            "const Player = preload(\"res://actors/Player.gd\")\n\nfunc _ready():\n\tprint(\"main\")\n",
        );

        (tmp, proj.to_string_lossy().to_string())
    }

    #[test]
    fn context_resolves_gdscript_symbol() {
        let _lock = lean_ctx::core::data_dir::test_env_lock();
        let (_tmp, root) = godot_fixture();
        let _ = handle_build(&root);
        let out = handle_context_query(Some("_ready"), &root);
        assert!(
            out.contains("_ready"),
            "context should surface _ready symbols: {out}"
        );
        assert!(!out.contains("No matching nodes found"), "got: {out}");
        lean_ctx::test_env::remove_var("LEAN_CTX_DATA_DIR");
    }

    #[test]
    fn impact_lists_gdscript_dependents() {
        let _lock = lean_ctx::core::data_dir::test_env_lock();
        let (_tmp, root) = godot_fixture();
        let _ = handle_build(&root);
        let out = handle_impact(Some("actors/Base.gd"), &root);
        assert!(
            out.contains("Player.gd"),
            "Base.gd dependents should include Player: {out}"
        );
        assert!(
            out.contains("Enemy.gd"),
            "Base.gd dependents should include Enemy: {out}"
        );
        lean_ctx::test_env::remove_var("LEAN_CTX_DATA_DIR");
    }

    #[test]
    fn bare_symbol_resolves_gdscript() {
        let _lock = lean_ctx::core::data_dir::test_env_lock();
        let (_tmp, root) = godot_fixture();
        let _ = handle_build(&root);
        let mut cache = lean_ctx::core::cache::SessionCache::new();
        let out = handle_symbol(
            Some("_ready"),
            &root,
            &mut cache,
            crate::tools::CrpMode::Off,
        );
        // Four `_ready` defs → a disambiguation list (or a snippet), never the
        // pre-#314 "Invalid symbol spec" / "not found" errors.
        assert!(out.contains("_ready"), "bare symbol should resolve: {out}");
        assert!(!out.contains("Invalid symbol spec"), "got: {out}");
        assert!(!out.to_lowercase().contains("not found"), "got: {out}");
        lean_ctx::test_env::remove_var("LEAN_CTX_DATA_DIR");
    }
}

/// G01: what `ctx_graph` renders from a source is cut from the admitted text.
#[cfg(test)]
mod admission_tests {
    use super::*;
    use lean_ctx::core::policy::runtime::TestPolicyOverride;

    fn policy(body: &str) -> lean_ctx::core::policy::ResolvedPolicy {
        lean_ctx::core::policy::load(&format!(
            "name = \"ctx-graph-test\"\nversion = \"1.0.0\"\ndescription = \"test\"\n{body}"
        ))
        .unwrap()
    }

    fn symbol(
        file: &str,
        name: &str,
        start_line: usize,
        end_line: usize,
    ) -> graph_provider::SymbolInfo {
        graph_provider::SymbolInfo {
            name: name.to_owned(),
            file: file.to_owned(),
            kind: "fn".to_owned(),
            start_line,
            end_line,
            is_exported: true,
        }
    }

    /// The old snippet renderer read the file raw (`fs::read_to_string`): a
    /// value a project rule masks was printed, and a source the policy blocks
    /// was printed in full. The index entry alone must authorize neither.
    #[test]
    fn a_symbol_snippet_is_cut_from_the_admitted_source_or_withheld() {
        let _data = lean_ctx::core::data_dir::isolated_data_dir();
        let project = tempfile::tempdir().unwrap();
        let root = project.path().to_string_lossy().into_owned();
        let billing = project.path().join("billing.rs");
        std::fs::write(
            &billing,
            "pub fn charge() {\n    let customer = \"CUS-1234\";\n}\n",
        )
        .unwrap();
        let billing = billing.to_string_lossy().into_owned();
        let charge = symbol("billing.rs", "charge", 1, 3);
        let mut cache = lean_ctx::core::cache::SessionCache::new();
        let off = crate::tools::CrpMode::Off;
        {
            // Control: a source no rule touches is rendered as before.
            let _community = TestPolicyOverride::set(None);
            let out =
                render_symbol_snippet(&charge, &billing, "billing.rs", &root, &mut cache, off);
            assert!(
                out.contains("   2|    let customer = \"CUS-1234\";\n"),
                "{out}"
            );
            assert!(out.contains("[ctx_graph symbol: "), "{out}");
        }
        {
            let _policy =
                TestPolicyOverride::set(Some(policy("[redaction]\ncustomer = \"CUS-[0-9]{4}\"\n")));
            let out =
                render_symbol_snippet(&charge, &billing, "billing.rs", &root, &mut cache, off);
            assert!(!out.contains("CUS-1234"), "{out}");
            assert!(out.contains("[REDACTED:customer]"), "{out}");
        }
        {
            let plan = project.path().join("plan.rs");
            std::fs::write(
                &plan,
                "CONFIDENTIAL\npub fn hidden() {\n    body_marker();\n}\n",
            )
            .unwrap();
            let _policy = TestPolicyOverride::set(Some(policy(
                "[filters]\nclassification = \"block\"\nblocked_labels = [\"CONFIDENTIAL\"]\n",
            )));
            let out = render_symbol_snippet(
                &symbol("plan.rs", "hidden", 2, 4),
                &plan.to_string_lossy(),
                "plan.rs",
                &root,
                &mut cache,
                off,
            );
            assert!(out.starts_with("Cannot read "), "{out}");
            assert!(out.contains("withheld"), "{out}");
            assert!(!out.contains("body_marker"), "{out}");
            assert!(
                cache.get_full_content(&plan.to_string_lossy()).is_none(),
                "a withheld source must not be in the session cache"
            );
        }
        assert!(
            cache.get_full_content(&billing).is_none(),
            "a snippet does not seed the session cache"
        );
    }

    /// A manifest the policy blocks contributes no crate name to matching.
    #[test]
    fn a_withheld_manifest_contributes_no_crate_prefix() {
        let _data = lean_ctx::core::data_dir::isolated_data_dir();
        let project = tempfile::tempdir().unwrap();
        let root = project.path().to_string_lossy().into_owned();
        std::fs::write(
            project.path().join("Cargo.toml"),
            "# CONFIDENTIAL\n[package]\nname = \"orbital-core\"\n",
        )
        .unwrap();
        let gp = GraphProvider::GraphIndex(lean_ctx::core::graph_index::ProjectIndex::new(&root));
        {
            let _community = TestPolicyOverride::set(None);
            let prefixes = file_path_to_module_prefixes("src/core/cache.rs", &root, &gp);
            assert!(
                prefixes.contains(&"orbital_core::core::cache".to_string()),
                "{prefixes:?}"
            );
        }
        let _policy = TestPolicyOverride::set(Some(policy(
            "[filters]\nclassification = \"block\"\nblocked_labels = [\"CONFIDENTIAL\"]\n",
        )));
        let prefixes = file_path_to_module_prefixes("src/core/cache.rs", &root, &gp);
        assert!(
            !prefixes
                .iter()
                .any(|prefix| prefix.contains("orbital_core")),
            "{prefixes:?}"
        );
        assert!(prefixes.contains(&"crate::core::cache".to_string()));
    }
}