agentstatedeveloper-python 1.4.9

//! Python language adapter for AgentStateDeveloper.
//!
//! Implements [`LanguageAdapter`](agentstatedeveloper_core::LanguageAdapter)
//! on top of `tree-sitter-python`. Parses module-level functions, methods,
//! and classes, and runs a small substring-based effect inference pass.

use std::collections::{HashMap, HashSet};

use agentstatedeveloper_core::adapter::{
    CallEdge, DynamicDispatchHint, LanguageAdapter, ParsedSymbol, UnresolvedCall, WorkspaceSymbols,
};
use agentstatedeveloper_core::cross_service::{
    DetectedEndpoint, Direction, ServiceEndpoint, Transport, http_contract, pubsub_contract,
};
use agentstatedeveloper_core::dataflow::DetectedDataFlow;
use agentstatedeveloper_core::error::{AsdError, Result};
use agentstatedeveloper_core::schema::{Effect, EffectCategory, SymbolKind};
use serde_json::json;
use tree_sitter::{Node, Parser};

/// Python language adapter.
#[derive(Debug, Default, Clone, Copy)]
pub struct PythonAdapter;

impl PythonAdapter {
    pub fn new() -> Self {
        Self
    }
}

impl LanguageAdapter for PythonAdapter {
    fn language(&self) -> &str {
        "python"
    }

    fn file_extensions(&self) -> &'static [&'static str] {
        &["py"]
    }

    fn parse_symbols(&self, file: &str, source: &str) -> Result<Vec<ParsedSymbol>> {
        let mut parser = Parser::new();
        parser
            .set_language(&tree_sitter_python::LANGUAGE.into())
            .map_err(|e| AsdError::Parse(format!("failed to set python language: {e}")))?;

        let src_bytes = source.as_bytes();
        let tree = parser
            .parse(src_bytes, None)
            .ok_or_else(|| AsdError::Parse(format!("failed to parse {file}")))?;

        let module_prefix = module_qname_prefix(file);
        let root = tree.root_node();
        let mut out = Vec::new();
        walk(root, src_bytes, &module_prefix, &[], &mut out);
        Ok(out)
    }

    fn infer_effects(&self, _source: &str, symbol: &ParsedSymbol) -> Vec<Effect> {
        infer_effects_from_body(&symbol.body)
    }

    fn infer_service_endpoints(
        &self,
        file: &str,
        source: &str,
        symbols: &[ParsedSymbol],
    ) -> Vec<DetectedEndpoint> {
        infer_service_endpoints_in_python(file, source, symbols)
    }

    fn resolve_endpoint_prefixes(
        &self,
        files: &[(String, String)],
        endpoints: &mut Vec<ServiceEndpoint>,
    ) {
        resolve_python_endpoint_prefixes(files, endpoints);
    }

    fn extract_dataflow(
        &self,
        file: &str,
        source: &str,
        symbols: &[ParsedSymbol],
        _workspace: &WorkspaceSymbols,
    ) -> Vec<DetectedDataFlow> {
        infer_dataflow_in_python(file, source, symbols)
    }

    fn extract_call_edges(
        &self,
        file: &str,
        source: &str,
        symbols: &[ParsedSymbol],
        workspace: &WorkspaceSymbols,
    ) -> Vec<CallEdge> {
        extract_call_edges_impl(file, source, symbols, workspace)
    }

    fn scan_dynamic_dispatch(&self, file: &str, source: &str) -> Vec<DynamicDispatchHint> {
        scan_dynamic_dispatch_in_python(file, source)
    }

    fn report_unresolved_calls(
        &self,
        file: &str,
        source: &str,
        symbols: &[ParsedSymbol],
        workspace: &WorkspaceSymbols,
    ) -> Vec<UnresolvedCall> {
        report_unresolved_calls_in_python(file, source, symbols, workspace)
    }
}

/// Plan L t-006: walk a Python file's call nodes and report any that
/// the static resolver couldn't bind to a workspace qname. Includes
/// stdlib + third-party + dynamic — callers should treat the count
/// as "static-resolution gap," not "bug list."
///
/// Filters out a small known-stdlib allowlist so the output isn't
/// drowned in `print` / `len` / `range` calls. Anything else gets
/// reported, including third-party calls (which are useful to see —
/// they tell you "these dependencies sit outside the indexed scope").
pub fn report_unresolved_calls_in_python(
    file: &str,
    source: &str,
    symbols: &[ParsedSymbol],
    workspace: &WorkspaceSymbols,
) -> Vec<UnresolvedCall> {
    use std::collections::HashSet;

    // The Python builtins that aren't worth surfacing as gaps —
    // every program calls them and they're never going to resolve to
    // a workspace symbol. Keep this list tight; when in doubt, leave
    // the call OUT of the allowlist so it surfaces.
    let stdlib_allowlist: HashSet<&str> = [
        "print",
        "len",
        "range",
        "type",
        "isinstance",
        "super",
        "hasattr",
        "getattr",
        "setattr",
        "delattr",
        "callable",
        "iter",
        "next",
        "list",
        "dict",
        "set",
        "tuple",
        "str",
        "int",
        "float",
        "bool",
        "bytes",
        "bytearray",
        "frozenset",
        "min",
        "max",
        "sum",
        "abs",
        "round",
        "sorted",
        "reversed",
        "enumerate",
        "zip",
        "map",
        "filter",
        "any",
        "all",
        "open",
        "repr",
        "hash",
        "id",
        "vars",
        "dir",
        "format",
        "input",
        "ord",
        "chr",
        "hex",
        "oct",
        "bin",
        "pow",
        "divmod",
        "compile",
        "eval",
        "exec",
    ]
    .into_iter()
    .collect();

    let mut parser = Parser::new();
    if parser
        .set_language(&tree_sitter_python::LANGUAGE.into())
        .is_err()
    {
        return Vec::new();
    }
    let module_prefix = module_qname_prefix(file);
    let src_bytes = source.as_bytes();

    // Rebuild the same resolution context the call-graph walker uses.
    let mut by_simple: HashMap<String, String> = HashMap::new();
    let mut known: HashSet<&str> = HashSet::new();
    for sym in symbols {
        known.insert(sym.qname.as_str());
        if let Some(simple) = sym.qname.rsplit_once('.').map(|(_, s)| s) {
            by_simple.insert(simple.to_string(), sym.qname.clone());
        }
    }
    let imports = parse_imports(source, &mut parser, &module_prefix);

    let tree = match parser.parse(src_bytes, None) {
        Some(t) => t,
        None => return Vec::new(),
    };

    let mut line_starts: Vec<usize> = vec![0];
    for (i, b) in src_bytes.iter().enumerate() {
        if *b == b'\n' {
            line_starts.push(i + 1);
        }
    }
    let line_of = |off: usize| -> u32 {
        match line_starts.binary_search(&off) {
            Ok(i) => i as u32 + 1,
            Err(i) => i.max(1) as u32,
        }
    };

    let mut out = Vec::new();
    walk_unresolved_calls(
        tree.root_node(),
        src_bytes,
        &module_prefix,
        &by_simple,
        &known,
        &imports,
        workspace,
        &stdlib_allowlist,
        file,
        &line_of,
        &mut out,
    );
    out
}

#[allow(clippy::too_many_arguments)]
fn walk_unresolved_calls(
    node: Node<'_>,
    src: &[u8],
    module_prefix: &str,
    by_simple: &HashMap<String, String>,
    known: &HashSet<&str>,
    imports: &HashMap<String, ImportBinding>,
    workspace: &WorkspaceSymbols,
    stdlib_allowlist: &std::collections::HashSet<&str>,
    file: &str,
    line_of: &dyn Fn(usize) -> u32,
    out: &mut Vec<UnresolvedCall>,
) {
    if node.kind() == "call" {
        if let Some(func) = node.child_by_field_name("function") {
            let callee_text = node_text(func, src).unwrap_or_default();
            let resolved = resolve_callee(
                func,
                src,
                module_prefix,
                by_simple,
                known,
                imports,
                workspace,
                None, // enclosing_class — best-effort; we don't replay class scope
            );
            if resolved.is_none() {
                // Filter out trivial stdlib calls. Match on the FIRST
                // segment for chained attribute access (`foo.bar` →
                // check `foo` against the allowlist; this catches
                // `str.format`-style chains incidentally).
                let head = callee_text.split('.').next().unwrap_or(&callee_text).trim();
                if !stdlib_allowlist.contains(head) {
                    out.push(UnresolvedCall {
                        file: file.to_string(),
                        line: line_of(func.start_byte()),
                        callee_text: callee_text.trim().to_string(),
                    });
                }
            }
        }
    }
    let mut cursor = node.walk();
    for child in node.children(&mut cursor) {
        walk_unresolved_calls(
            child,
            src,
            module_prefix,
            by_simple,
            known,
            imports,
            workspace,
            stdlib_allowlist,
            file,
            line_of,
            out,
        );
    }
}

/// Walk path components and return the tail after the first `src` segment.
/// Falls back to the full path for projects without that convention.
///
/// Examples:
/// - `src/mypackage/module.py`  → `mypackage/module.py`
/// - `lib/src/utils.py`         → `utils.py`
/// - `mypackage/module.py`      → `mypackage/module.py`  (no `src`, unchanged)
fn strip_src_prefix(path: &str) -> &str {
    let mut offset = 0usize;
    for part in path.split('/') {
        if part == "src" {
            let after = offset + part.len() + 1;
            if after < path.len() {
                return &path[after..];
            }
        }
        offset += part.len() + 1;
    }
    path
}

/// Derive the dotted module prefix for a file path.
///
/// Anchors at the `src/` boundary for src-layout projects (PEP 517/518)
/// so the prefix is stable regardless of which directory `asd index` was
/// invoked from. Falls back to the full relative path for flat layouts.
///
/// `src/mypackage/module.py`        -> `mypackage.module`
/// `packages/mypkg/src/__init__.py` -> `mypkg.__init__`  (package-name disambiguates)
/// `foo/bar.py`                     -> `foo.bar`          (no src segment, fallback)
/// `./foo/bar.py`                   -> `foo.bar`
/// `bar.py`                         -> `bar`
fn module_qname_prefix(file: &str) -> String {
    let mut s = file;
    if let Some(stripped) = s.strip_prefix("./") {
        s = stripped;
    }
    let s = s.strip_suffix(".py").unwrap_or(s);
    let after_src = strip_src_prefix(s);
    // __init__.py at the root of a package's src/ dir is not unique across packages.
    // Prepend the package directory name (the segment before `src/`).
    if after_src == "__init__" {
        if let Some(pkg_name) = package_name_from_path(s) {
            return format!("{}.__init__", pkg_name.replace('-', "_"));
        }
    }
    after_src.replace('\\', "/").replace('/', ".")
}

/// Extract the package name from a path like `packages/my-pkg/src/__init__.py`
/// by finding the segment immediately before a `src` component.
fn package_name_from_path(path: &str) -> Option<&str> {
    let parts: Vec<&str> = path.split('/').collect();
    for (i, &part) in parts.iter().enumerate() {
        if part == "src" && i > 0 {
            return Some(parts[i - 1]);
        }
    }
    None
}

/// Recursive descent over the Python tree. We enumerate:
/// - `function_definition` -> Function or Method depending on scope
/// - `class_definition` -> Class
///
/// Nested functions get their enclosing function/class names in their qname.
fn walk(
    node: Node<'_>,
    src: &[u8],
    module_prefix: &str,
    scope: &[(String, ScopeKind)],
    out: &mut Vec<ParsedSymbol>,
) {
    let kind = node.kind();
    match kind {
        "function_definition" => {
            let name = node_field_text(node, "name", src).unwrap_or_else(|| "<anon>".to_string());
            let qname = build_qname(module_prefix, scope, &name);
            let symbol_kind = if scope.last().map(|s| s.1) == Some(ScopeKind::Class) {
                SymbolKind::Method
            } else {
                SymbolKind::Function
            };
            let signature = extract_function_signature(node, src, &name);
            out.push(make_parsed_symbol(node, src, qname, symbol_kind, signature));

            // Recurse into the body with this function pushed on the scope.
            let mut new_scope = scope.to_vec();
            new_scope.push((name, ScopeKind::Function));
            if let Some(body) = node.child_by_field_name("body") {
                let mut cursor = body.walk();
                for child in body.children(&mut cursor) {
                    walk(child, src, module_prefix, &new_scope, out);
                }
            }
        }
        "class_definition" => {
            let name = node_field_text(node, "name", src).unwrap_or_else(|| "<anon>".to_string());
            let qname = build_qname(module_prefix, scope, &name);
            let signature = extract_class_signature(node, src, &name);
            out.push(make_parsed_symbol(
                node,
                src,
                qname,
                SymbolKind::Class,
                signature,
            ));

            let mut new_scope = scope.to_vec();
            new_scope.push((name, ScopeKind::Class));
            if let Some(body) = node.child_by_field_name("body") {
                let mut cursor = body.walk();
                for child in body.children(&mut cursor) {
                    walk(child, src, module_prefix, &new_scope, out);
                }
            }
        }
        _ => {
            // Descend into other containers (module root, decorated_definition, etc.).
            let mut cursor = node.walk();
            for child in node.children(&mut cursor) {
                walk(child, src, module_prefix, scope, out);
            }
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ScopeKind {
    Class,
    Function,
}

fn build_qname(module_prefix: &str, scope: &[(String, ScopeKind)], name: &str) -> String {
    let mut parts = Vec::with_capacity(scope.len() + 2);
    if !module_prefix.is_empty() {
        parts.push(module_prefix.to_string());
    }
    for (s, _) in scope {
        parts.push(s.clone());
    }
    parts.push(name.to_string());
    parts.join(".")
}

fn node_field_text(node: Node<'_>, field: &str, src: &[u8]) -> Option<String> {
    node.child_by_field_name(field)
        .and_then(|n| node_text(n, src))
}

fn node_text(node: Node<'_>, src: &[u8]) -> Option<String> {
    src.get(node.byte_range())
        .map(|b| String::from_utf8_lossy(b).into_owned())
}

fn make_parsed_symbol(
    node: Node<'_>,
    src: &[u8],
    qname: String,
    kind: SymbolKind,
    signature: Option<String>,
) -> ParsedSymbol {
    let start = node.start_position();
    let end = node.end_position();
    let body = node_text(node, src).unwrap_or_default();
    let doc = extract_python_doc(&body);
    ParsedSymbol {
        qname,
        kind,
        // tree-sitter positions are 0-based; ASD wants 1-based.
        start_line: (start.row as u32) + 1,
        start_col: (start.column as u32) + 1,
        end_line: (end.row as u32) + 1,
        end_col: (end.column as u32) + 1,
        body,
        signature,
        doc,
    }
}

fn extract_python_doc(body: &str) -> Option<String> {
    for quote in &[r#"""""#, "'''"] {
        if let Some(start) = body.find(quote) {
            let after = start + quote.len();
            if let Some(end_rel) = body[after..].find(quote) {
                let content = &body[after..after + end_rel];
                let cleaned = content
                    .lines()
                    .map(|l| l.trim())
                    .filter(|l| !l.is_empty())
                    .collect::<Vec<_>>()
                    .join(" ");
                if !cleaned.is_empty() {
                    return Some(truncate_doc(&cleaned));
                }
            }
        }
    }
    None
}

fn extract_function_signature(node: Node<'_>, src: &[u8], name: &str) -> Option<String> {
    let params = node.child_by_field_name("parameters")?;
    let params_text = node_text(params, src)?;
    Some(format!("def {name}{params_text}"))
}

fn extract_class_signature(node: Node<'_>, src: &[u8], name: &str) -> Option<String> {
    // `superclasses` is optional in the grammar.
    if let Some(sup) = node.child_by_field_name("superclasses") {
        if let Some(sup_text) = node_text(sup, src) {
            return Some(format!("class {name}{sup_text}"));
        }
    }
    Some(format!("class {name}"))
}

// -----------------------------------------------------------------------------
// Cross-service endpoint detection (t-002)
//
// Heuristic, line-based, matching the substring style of effect inference.
// Inbound: FastAPI/Flask route decorators. Outbound: requests/httpx client
// calls with a literal URL. Non-literal URLs (f-strings, variables) are skipped
// — without a literal we can't form a contract that would match a server route.
// Session/client-object calls and Django url routing are known coverage gaps.
// -----------------------------------------------------------------------------

const HTTP_VERBS: &[&str] = &["get", "post", "put", "patch", "delete", "head", "options"];

fn infer_service_endpoints_in_python(
    file: &str,
    source: &str,
    symbols: &[ParsedSymbol],
) -> Vec<DetectedEndpoint> {
    let mut out = Vec::new();
    // Plan Q t-004: resolve each router's prefix once per file so route contracts
    // are the full runtime path, not just the decorator arg. Covers same-file
    // `APIRouter(prefix=)` / `Blueprint(url_prefix=)` and same-file
    // `include_router`/`register_blueprint` mounts. (Cross-file/nested mount
    // trees are increment 2.)
    let router_prefixes = collect_router_prefixes(source);
    for (idx, raw) in source.lines().enumerate() {
        let line_no = (idx + 1) as u32;
        let line = raw.trim();

        // Inbound: route decorators (@app.get("/x"), @router.get("/x"), @bp.route(...)).
        let receiver_prefix = route_receiver(line).and_then(|r| router_prefixes.get(&r).cloned());
        for (method, path, conf) in parse_route_decorator(line) {
            if let Some(owner) = owner_for_decorator(symbols, line_no) {
                let full = match &receiver_prefix {
                    Some(pfx) => join_route(pfx, &path),
                    None => path.clone(),
                };
                out.push(DetectedEndpoint {
                    transport: Transport::Http,
                    direction: Direction::Inbound,
                    contract: http_contract(&method, &full),
                    owner_qname: owner.qname.clone(),
                    file: file.to_string(),
                    line: line_no,
                    confidence: conf,
                    note: None,
                });
            }
        }

        // Outbound: requests/httpx client calls with a literal URL.
        for (method, url, conf) in parse_client_calls(line) {
            if let Some(owner) = owner_for_body_line(symbols, line_no) {
                out.push(DetectedEndpoint {
                    transport: Transport::Http,
                    direction: Direction::Outbound,
                    contract: http_contract(&method, &url),
                    owner_qname: owner.qname.clone(),
                    file: file.to_string(),
                    line: line_no,
                    confidence: conf,
                    note: None,
                });
            }
        }

        // Pub-sub (Celery): a @shared_task/@app.task def is a listener; the task
        // function's name is the contract. `name.delay()/.apply_async()` is the
        // emit. The two match by task name.
        if is_celery_task_decorator(line) {
            if let Some(owner) = owner_for_decorator(symbols, line_no) {
                let task = simple_name(&owner.qname);
                out.push(DetectedEndpoint {
                    transport: Transport::PubSub,
                    direction: Direction::Inbound,
                    contract: pubsub_contract(task),
                    owner_qname: owner.qname.clone(),
                    file: file.to_string(),
                    line: line_no,
                    confidence: 0.85,
                    note: Some("celery task".into()),
                });
            }
        }
        for task in parse_celery_emits(line) {
            if let Some(owner) = owner_for_body_line(symbols, line_no) {
                out.push(DetectedEndpoint {
                    transport: Transport::PubSub,
                    direction: Direction::Outbound,
                    contract: pubsub_contract(&task),
                    owner_qname: owner.qname.clone(),
                    file: file.to_string(),
                    line: line_no,
                    confidence: 0.6,
                    note: Some("celery emit".into()),
                });
            }
        }
    }
    out
}

/// Last dotted segment of a qname (`a.b.process_order` → `process_order`).
fn simple_name(qname: &str) -> &str {
    qname.rsplit('.').next().unwrap_or(qname)
}

/// `@shared_task`, `@app.task`, `@celery.task(bind=True)`, `@<x>.task` — Celery
/// task definitions (which act as message consumers).
fn is_celery_task_decorator(line: &str) -> bool {
    let Some(body) = line.strip_prefix('@') else {
        return false;
    };
    let head = body.split('(').next().unwrap_or(body).trim();
    head == "shared_task" || head == "task" || head.ends_with(".task")
}

/// Task names invoked via `<name>.delay(` / `<name>.apply_async(`.
fn parse_celery_emits(line: &str) -> Vec<String> {
    let mut out = Vec::new();
    for suffix in [".delay(", ".apply_async("] {
        let mut from = 0;
        while let Some(rel) = line[from..].find(suffix) {
            let pos = from + rel;
            from = pos + suffix.len();
            let name: String = line[..pos]
                .chars()
                .rev()
                .take_while(|c| c.is_alphanumeric() || *c == '_')
                .collect::<Vec<_>>()
                .into_iter()
                .rev()
                .collect();
            if !name.is_empty() && !out.contains(&name) {
                out.push(name);
            }
        }
    }
    out
}

/// The symbol whose line range contains `line`, innermost (largest start_line)
/// when nested (class + method).
fn owner_for_body_line(symbols: &[ParsedSymbol], line: u32) -> Option<&ParsedSymbol> {
    symbols
        .iter()
        .filter(|s| s.start_line <= line && line <= s.end_line)
        .max_by_key(|s| s.start_line)
}

/// The symbol a decorator on `line` decorates: the symbol containing the line,
/// else the nearest `def` starting just below it (decorators stack within a few
/// lines of the definition).
fn owner_for_decorator(symbols: &[ParsedSymbol], line: u32) -> Option<&ParsedSymbol> {
    if let Some(s) = owner_for_body_line(symbols, line) {
        return Some(s);
    }
    symbols
        .iter()
        .filter(|s| s.start_line > line && s.start_line <= line + 6)
        .min_by_key(|s| s.start_line)
}

/// Parse a route decorator line into `(METHOD, path, confidence)` pairs.
/// `@x.get("/p")` → one entry; `@x.route("/p", methods=["GET","POST"])` → one
/// per method (default GET when `methods=` is absent).
fn parse_route_decorator(line: &str) -> Vec<(String, String, f64)> {
    let Some(rest) = line.strip_prefix('@') else {
        return Vec::new();
    };
    // Need an `obj.attr(` shape.
    let Some(paren) = rest.find('(') else {
        return Vec::new();
    };
    let callee = rest[..paren].trim();
    let args = &rest[paren + 1..];
    let Some(attr) = callee.rsplit('.').next() else {
        return Vec::new();
    };
    // The attribute must be on something (a.b), not a bare `@decorator(`.
    if !callee.contains('.') {
        return Vec::new();
    }
    let attr = attr.trim();

    if HTTP_VERBS.contains(&attr) {
        if let Some(path) = first_string_arg(args) {
            return vec![(attr.to_uppercase(), path, 0.95)];
        }
        return Vec::new();
    }
    if attr == "route" {
        let Some(path) = first_string_arg(args) else {
            return Vec::new();
        };
        let methods = methods_kwarg(args);
        let methods = if methods.is_empty() {
            vec!["GET".to_string()]
        } else {
            methods
        };
        return methods
            .into_iter()
            .map(|m| (m, path.clone(), 0.9))
            .collect();
    }
    Vec::new()
}

// ── router-prefix resolution (Plan Q t-004) ────────────────────────────────

/// The receiver variable of a route decorator: `@router.get("/x")` → `router`,
/// `@app.route(...)` → `app`. `None` for bare `@decorator(` shapes.
fn route_receiver(line: &str) -> Option<String> {
    let rest = line.trim().strip_prefix('@')?;
    let paren = rest.find('(')?;
    let callee = rest[..paren].trim();
    let dot = callee.rfind('.')?;
    let recv = callee[..dot].trim();
    if recv.is_empty() {
        None
    } else {
        Some(recv.to_string())
    }
}

/// Map every router/blueprint variable in a file to its resolved prefix, from
/// same-file `APIRouter(prefix=)` / `Blueprint(url_prefix=)` definitions and
/// same-file `include_router(child, prefix=)` / `register_blueprint(child,
/// url_prefix=)` mounts. The mount prefix precedes the router's own prefix
/// (FastAPI/Flask ordering).
fn collect_router_prefixes(source: &str) -> HashMap<String, String> {
    let mut self_p: HashMap<String, String> = HashMap::new();
    let mut mount_p: HashMap<String, String> = HashMap::new();
    for raw in source.lines() {
        let line = raw.trim();
        // `<var> = APIRouter(... prefix="P" ...)` / `Blueprint(... url_prefix="P" ...)`.
        if let Some(eq) = line.find('=') {
            let var = line[..eq].trim();
            if is_ident(var) {
                let rhs = &line[eq + 1..];
                if let Some(a) = ctor_args(rhs, "APIRouter") {
                    if let Some(p) = string_kwarg(a, "prefix") {
                        self_p.insert(var.to_string(), p);
                    }
                } else if let Some(a) = ctor_args(rhs, "Blueprint") {
                    if let Some(p) = string_kwarg(a, "url_prefix") {
                        self_p.insert(var.to_string(), p);
                    }
                }
            }
        }
        // `<recv>.include_router(<child>, prefix="Q")` / `register_blueprint(<child>, url_prefix="Q")`.
        if let Some(a) = ctor_args(line, "include_router") {
            if let (Some(child), Some(q)) = (first_ident_arg(a), string_kwarg(a, "prefix")) {
                mount_p.entry(child).or_insert(q);
            }
        }
        if let Some(a) = ctor_args(line, "register_blueprint") {
            if let (Some(child), Some(q)) = (first_ident_arg(a), string_kwarg(a, "url_prefix")) {
                mount_p.entry(child).or_insert(q);
            }
        }
    }
    let keys: HashSet<String> = self_p.keys().chain(mount_p.keys()).cloned().collect();
    let mut out = HashMap::new();
    for k in keys {
        let full = normalize_prefix(&format!(
            "{}{}",
            mount_p.get(&k).map(String::as_str).unwrap_or(""),
            self_p.get(&k).map(String::as_str).unwrap_or("")
        ));
        if !full.is_empty() {
            out.insert(k, full);
        }
    }
    out
}

/// Args slice after `Name(` in `s`, respecting an identifier boundary before
/// `Name` (so `APIRouter` is not matched inside `MyAPIRouter`).
fn ctor_args<'a>(s: &'a str, name: &str) -> Option<&'a str> {
    let mut from = 0;
    while let Some(rel) = s[from..].find(name) {
        let pos = from + rel;
        from = pos + name.len();
        let before_ok = pos == 0
            || !s[..pos]
                .chars()
                .next_back()
                .map(|c| c.is_alphanumeric() || c == '_')
                .unwrap_or(false);
        let after = s[pos + name.len()..].trim_start();
        if before_ok {
            if let Some(args) = after.strip_prefix('(') {
                return Some(args);
            }
        }
    }
    None
}

/// A `key="value"` string kwarg, respecting an identifier boundary before `key`
/// (so `prefix` is not matched inside `url_prefix`).
fn string_kwarg(args: &str, key: &str) -> Option<String> {
    let mut from = 0;
    while let Some(rel) = args[from..].find(key) {
        let pos = from + rel;
        from = pos + key.len();
        let before_ok = pos == 0
            || !args[..pos]
                .chars()
                .next_back()
                .map(|c| c.is_alphanumeric() || c == '_')
                .unwrap_or(false);
        if !before_ok {
            continue;
        }
        let after = args[pos + key.len()..].trim_start();
        if let Some(after) = after.strip_prefix('=') {
            if let Some(s) = read_string_literal(after.trim_start()) {
                return Some(s);
            }
        }
    }
    None
}

/// First positional argument if it's a (possibly dotted) identifier.
fn first_ident_arg(args: &str) -> Option<String> {
    let s = args.trim_start();
    let end = s
        .find(|c: char| !(c.is_alphanumeric() || c == '_' || c == '.'))
        .unwrap_or(s.len());
    let id = &s[..end];
    if id.is_empty() || id.starts_with('.') {
        None
    } else {
        Some(id.to_string())
    }
}

fn is_ident(s: &str) -> bool {
    !s.is_empty() && s.chars().all(|c| c.is_alphanumeric() || c == '_')
}

/// Normalize a prefix: leading slash, no trailing slash, collapse `//`.
fn normalize_prefix(p: &str) -> String {
    let p = p.trim();
    if p.is_empty() {
        return String::new();
    }
    let mut s = p.to_string();
    while s.contains("//") {
        s = s.replace("//", "/");
    }
    if !s.starts_with('/') {
        s.insert(0, '/');
    }
    while s.len() > 1 && s.ends_with('/') {
        s.pop();
    }
    s
}

/// Join a resolved router prefix with a decorator path into the full route path.
fn join_route(prefix: &str, path: &str) -> String {
    if prefix.is_empty() {
        return path.to_string();
    }
    let p = prefix.trim_end_matches('/');
    if path.is_empty() || path == "/" {
        return p.to_string();
    }
    if path.starts_with('/') {
        format!("{p}{path}")
    } else {
        format!("{p}/{path}")
    }
}

// ── project-level mount-tree resolution (Plan Q t-004b/c) ───────────────────

/// Rewrite each inbound HTTP endpoint's contract to the full runtime path by
/// resolving the cross-file, nested router-mount chain
/// (`app.include_router(api, prefix="/api")` → `api.include_router(calc,
/// prefix="/calc")` → `@calc.get("/x")` = `/api/calc/x`). Routers are keyed by
/// their **qname** (`module.var`), so an `include_router(alias)` mount connects
/// to the aliased router's routes even across files and generic `router` names
/// (t-004c: aliases resolved via `from … import … as …`).
fn resolve_python_endpoint_prefixes(
    files: &[(String, String)],
    endpoints: &mut Vec<ServiceEndpoint>,
) {
    // Per-file module qname + import alias map (local name -> imported qname).
    let module_by_path: HashMap<&str, String> = files
        .iter()
        .map(|(p, _)| (p.as_str(), module_qname_prefix(p)))
        .collect();
    let imports_by_path: HashMap<&str, HashMap<String, String>> = files
        .iter()
        .map(|(p, s)| {
            (
                p.as_str(),
                file_import_qnames(s, &module_by_path[p.as_str()]),
            )
        })
        .collect();

    // Global router tables keyed by qname (globally unique — no ambiguity).
    let mut self_by_q: HashMap<String, String> = HashMap::new();
    let mut parent_of: HashMap<String, Vec<(String, String)>> = HashMap::new(); // child -> mounts
    let mut app_qs: HashSet<String> = HashSet::new();
    let mut known: HashSet<String> = HashSet::new();

    for (path, source) in files {
        let module = &module_by_path[path.as_str()];
        let imports = &imports_by_path[path.as_str()];
        for raw in source.lines() {
            let line = raw.trim();
            // `<var> = APIRouter(...)` / `Blueprint(...)` / `FastAPI()` / `Flask()`.
            if let Some(eq) = line.find('=') {
                let var = line[..eq].trim();
                if is_ident(var) {
                    let rhs = &line[eq + 1..];
                    let q = qualify(module, var); // a definition binds locally
                    if let Some(a) = ctor_args(rhs, "APIRouter") {
                        if let Some(p) = string_kwarg(a, "prefix") {
                            self_by_q.insert(q.clone(), normalize_prefix(&p));
                        }
                        known.insert(q);
                    } else if let Some(a) = ctor_args(rhs, "Blueprint") {
                        if let Some(p) = string_kwarg(a, "url_prefix") {
                            self_by_q.insert(q.clone(), normalize_prefix(&p));
                        }
                        known.insert(q);
                    } else if ctor_args(rhs, "FastAPI").is_some()
                        || ctor_args(rhs, "Flask").is_some()
                    {
                        app_qs.insert(q.clone());
                        known.insert(q);
                    }
                }
            }
            // `<parent>.include_router(<child>, prefix="Q")` / register_blueprint.
            for (fname, pkey) in [
                ("include_router", "prefix"),
                ("register_blueprint", "url_prefix"),
            ] {
                if let Some(a) = ctor_args(line, fname) {
                    if let (Some(child), Some(parent)) =
                        (first_ident_arg(a), mount_receiver(line, fname))
                    {
                        let m = string_kwarg(a, pkey)
                            .map(|s| normalize_prefix(&s))
                            .unwrap_or_default();
                        let child_q = resolve_name(&child, module, imports);
                        let parent_q = resolve_name(&parent, module, imports);
                        known.insert(child_q.clone());
                        known.insert(parent_q.clone());
                        let mounts = parent_of.entry(child_q).or_default();
                        let edge = (parent_q, m);
                        if !mounts.contains(&edge) {
                            mounts.push(edge);
                        }
                    }
                }
            }
        }
    }

    let mut cache: HashMap<String, Option<Vec<String>>> = HashMap::new();
    let mut local: HashMap<String, HashMap<String, String>> = HashMap::new();
    let src_by_path: HashMap<&str, &str> = files
        .iter()
        .map(|(p, s)| (p.as_str(), s.as_str()))
        .collect();
    // Routes served under >1 mount prefix produce extra endpoints (t-004d),
    // appended after the in-place rewrite pass.
    let mut additions: Vec<ServiceEndpoint> = Vec::new();

    for ep in endpoints.iter_mut() {
        if ep.transport != Transport::Http || ep.direction != Direction::Inbound {
            continue;
        }
        let Some(src) = src_by_path.get(ep.file.as_str()).copied() else {
            continue;
        };
        let Some(module) = module_by_path.get(ep.file.as_str()) else {
            continue;
        };
        let imports = &imports_by_path[ep.file.as_str()];
        let Some(line) = src.lines().nth(ep.line.saturating_sub(1) as usize) else {
            continue;
        };
        let line = line.trim();
        let Some(recv) = route_receiver(line) else {
            continue;
        };
        let decos = parse_route_decorator(line);
        let Some((_, raw_path, _)) = decos.first() else {
            continue;
        };
        let method = ep
            .contract
            .strip_prefix("http:")
            .and_then(|s| s.split(' ').next())
            .unwrap_or("GET")
            .to_string();

        let recv_q = resolve_name(&recv, module, imports);
        // Global mount-tree resolution for known routers; else file-local (t-004a).
        // A router mounted at N prefixes yields N full paths (t-004d).
        let prefixes: Vec<String> = if known.contains(&recv_q) {
            resolve_full_q(&recv_q, &self_by_q, &parent_of, &app_qs, &mut cache)
        } else {
            vec![
                local
                    .entry(ep.file.clone())
                    .or_insert_with(|| collect_router_prefixes(src))
                    .get(&recv)
                    .cloned()
                    .unwrap_or_default(),
            ]
        };
        let mut paths: Vec<String> = prefixes.iter().map(|p| join_route(p, raw_path)).collect();
        paths.sort();
        paths.dedup();
        if paths.is_empty() {
            paths.push(raw_path.clone());
        }
        ep.contract = http_contract(&method, &paths[0]);
        for extra in paths.iter().skip(1) {
            let mut dup = ep.clone();
            dup.contract = http_contract(&method, extra);
            additions.push(dup);
        }
    }
    endpoints.extend(additions);
}

/// `module.name`, or just `name` when module is empty.
fn qualify(module: &str, name: &str) -> String {
    if module.is_empty() {
        name.to_string()
    } else {
        format!("{module}.{name}")
    }
}

/// Resolve a local name to a qname: an imported alias resolves to the imported
/// symbol's qname; otherwise it's `module.name` (a local binding).
fn resolve_name(name: &str, module: &str, imports: &HashMap<String, String>) -> String {
    imports
        .get(name)
        .cloned()
        .unwrap_or_else(|| qualify(module, name))
}

/// Per-file import map: local name -> imported symbol qname, for
/// `from <mod> import a, b as c` (relative or absolute). Best-effort single-line
/// — enough to connect router aliases. Reuses [`resolve_relative_import`].
fn file_import_qnames(source: &str, module: &str) -> HashMap<String, String> {
    let mut out = HashMap::new();
    for raw in source.lines() {
        let line = raw.trim();
        let Some(rest) = line.strip_prefix("from ") else {
            continue;
        };
        let Some(imp) = rest.find(" import ") else {
            continue;
        };
        let module_raw = rest[..imp].trim();
        let resolved = if module_raw.starts_with('.') {
            match resolve_relative_import(module, module_raw) {
                Some(m) => m,
                None => continue,
            }
        } else {
            module_raw.to_string()
        };
        let names = rest[imp + " import ".len()..]
            .trim()
            .trim_start_matches('(')
            .trim_end_matches(')')
            .trim_end_matches('\\')
            .trim();
        for part in names.split(',') {
            let part = part.trim();
            if part.is_empty() || part == "*" {
                continue;
            }
            let (orig, local) = match part.split_once(" as ") {
                Some((o, l)) => (o.trim(), l.trim()),
                None => (part, part),
            };
            if is_ident(orig) && is_ident(local) {
                out.insert(local.to_string(), qualify(&resolved, orig));
            }
        }
    }
    out
}

/// Full mount-resolved prefixes for a router qname. A router included at several
/// mounts (or via a parent that is) yields several full paths — one per mount
/// path through the tree (`full(parent) + mount + self`). Memoized, cycle-guarded
/// (a cycle contributes no path), and deduped.
fn resolve_full_q(
    q: &str,
    self_by_q: &HashMap<String, String>,
    parent_of: &HashMap<String, Vec<(String, String)>>,
    app_qs: &HashSet<String>,
    cache: &mut HashMap<String, Option<Vec<String>>>,
) -> Vec<String> {
    if let Some(c) = cache.get(q) {
        return c.clone().unwrap_or_default(); // in-progress (None) → empty = cycle break
    }
    cache.insert(q.to_string(), None); // mark visiting
    let self_p = self_by_q.get(q).cloned().unwrap_or_default();
    let mut out: Vec<String> = if app_qs.contains(q) {
        vec![self_p.clone()]
    } else if let Some(parents) = parent_of.get(q) {
        let mut acc = Vec::new();
        for (parent, mount) in parents {
            let mut pfulls = resolve_full_q(parent, self_by_q, parent_of, app_qs, cache);
            if pfulls.is_empty() {
                pfulls.push(String::new());
            }
            for pf in pfulls {
                acc.push(normalize_prefix(&format!("{pf}{mount}{self_p}")));
            }
        }
        if acc.is_empty() {
            vec![self_p.clone()]
        } else {
            acc
        }
    } else {
        vec![self_p.clone()]
    };
    out.sort();
    out.dedup();
    cache.insert(q.to_string(), Some(out.clone()));
    out
}

/// The receiver before `.<fname>(` — `api_router.include_router(...)` →
/// `api_router`, `app.register_blueprint(...)` → `app`.
fn mount_receiver(line: &str, fname: &str) -> Option<String> {
    let pos = line.find(fname)?;
    let before = line[..pos].trim_end().strip_suffix('.')?;
    let start = before
        .rfind(|c: char| !(c.is_alphanumeric() || c == '_'))
        .map(|i| i + 1)
        .unwrap_or(0);
    let recv = &before[start..];
    if recv.is_empty() {
        None
    } else {
        Some(recv.to_string())
    }
}

/// Parse requests/httpx client calls on a line into `(METHOD, url, confidence)`.
/// Handles `requests.get("u")`, `httpx.post('u')`, and
/// `requests.request("POST", "u")`. Only literal URLs are returned.
fn parse_client_calls(line: &str) -> Vec<(String, String, f64)> {
    let mut out = Vec::new();
    for module in ["requests.", "httpx."] {
        let mut search_from = 0usize;
        while let Some(rel) = line[search_from..].find(module) {
            let start = search_from + rel;
            // Must be a call boundary, not a substring of a longer identifier.
            let preceded_ok = start == 0
                || !line[..start]
                    .chars()
                    .next_back()
                    .map(|c| c.is_alphanumeric() || c == '_' || c == '.')
                    .unwrap_or(false);
            let after = &line[start + module.len()..];
            search_from = start + module.len();
            if !preceded_ok {
                continue;
            }
            let Some(paren) = after.find('(') else {
                continue;
            };
            let attr = after[..paren].trim();
            let args = &after[paren + 1..];
            if HTTP_VERBS.contains(&attr) {
                if let Some(url) = first_string_arg(args) {
                    out.push((attr.to_uppercase(), url, 0.9));
                }
            } else if attr == "request" {
                // requests.request("POST", "url", ...)
                let parts = first_two_string_args(args);
                if let (Some(method), Some(url)) = parts {
                    out.push((method.to_uppercase(), url, 0.9));
                }
            }
        }
    }
    out
}

/// Extract the first string literal from an argument list. Returns `None` for
/// f-strings / b-strings (dynamic) so we never form a bogus contract; r-strings
/// (raw) are accepted. Leading whitespace and a `url=` kwarg name are skipped.
fn first_string_arg(args: &str) -> Option<String> {
    let s = args.trim_start();
    // Skip a leading `name=` kwarg label (e.g. url=, path=).
    let s = match s.find('=') {
        Some(eq)
            if s[..eq].chars().all(|c| c.is_alphanumeric() || c == '_')
                && !s[..eq].is_empty()
                && s.as_bytes().get(eq + 1) != Some(&b'=') =>
        {
            s[eq + 1..].trim_start()
        }
        _ => s,
    };
    read_string_literal(s)
}

fn first_two_string_args(args: &str) -> (Option<String>, Option<String>) {
    let first = read_string_literal(args.trim_start());
    // Advance past the first literal + comma, then read the second.
    let Some(comma) = args.find(',') else {
        return (first, None);
    };
    let second = first_string_arg(&args[comma + 1..]);
    (first, second)
}

/// Read a leading string literal, rejecting f/b-string prefixes. Returns the
/// inner text (without quotes).
fn read_string_literal(s: &str) -> Option<String> {
    let bytes = s.as_bytes();
    let mut i = 0;
    // Allow a raw-string prefix `r`/`R`; reject f/b (dynamic / bytes).
    if let Some(&c) = bytes.first() {
        match c {
            b'r' | b'R' => i = 1,
            b'f' | b'F' | b'b' | b'B' => return None,
            _ => {}
        }
    }
    let quote = *bytes.get(i)?;
    if quote != b'"' && quote != b'\'' {
        return None;
    }
    let inner = &s[i + 1..];
    let end = inner.find(quote as char)?;
    Some(inner[..end].to_string())
}

/// Parse a `methods=["GET", "POST"]` (or `=('GET',)`) kwarg into upper-cased
/// method names.
fn methods_kwarg(args: &str) -> Vec<String> {
    let Some(pos) = args.find("methods") else {
        return Vec::new();
    };
    let after = &args[pos + "methods".len()..];
    let after = after.trim_start();
    let Some(after) = after.strip_prefix('=') else {
        return Vec::new();
    };
    // Take up to the closing bracket/paren of the list.
    let after = after.trim_start();
    let open = after.chars().next();
    let close = match open {
        Some('[') => ']',
        Some('(') => ')',
        _ => return Vec::new(),
    };
    let Some(end) = after.find(close) else {
        return Vec::new();
    };
    let list = &after[1..end];
    let mut out = Vec::new();
    let mut rest = list;
    while let Some(m) = read_string_literal(rest.trim_start()) {
        out.push(m.to_uppercase());
        match rest.find(',') {
            Some(c) => rest = &rest[c + 1..],
            None => break,
        }
    }
    out
}

// -----------------------------------------------------------------------------
// Data-flow detection (t-002 slice 4)
//
// Conservative arg→param detection: only same-file function calls whose
// arguments are ALL bare identifiers. High precision over recall — cross-file
// resolution, method calls, literals, and kwargs are deliberately skipped
// (tracked as follow-up). The pipeline maps each arg position to the callee's
// parameter name from its signature.
// -----------------------------------------------------------------------------

fn infer_dataflow_in_python(
    file: &str,
    source: &str,
    symbols: &[ParsedSymbol],
) -> Vec<DetectedDataFlow> {
    use std::collections::HashMap;

    // Same-file function simple-name → qname. A name defined more than once is
    // ambiguous (mapped to None) and never resolved.
    let mut name_to_qname: HashMap<&str, Option<String>> = HashMap::new();
    for s in symbols {
        if s.kind == SymbolKind::Function {
            let last = s.qname.rsplit('.').next().unwrap_or(s.qname.as_str());
            name_to_qname
                .entry(last)
                .and_modify(|e| *e = None)
                .or_insert_with(|| Some(s.qname.clone()));
        }
    }

    let mut out = Vec::new();
    for (idx, raw) in source.lines().enumerate() {
        let line_no = (idx + 1) as u32;
        for (callee_name, args) in simple_calls(raw) {
            let Some(Some(callee_qname)) = name_to_qname.get(callee_name.as_str()) else {
                continue;
            };
            let Some(owner) = owner_for_body_line(symbols, line_no) else {
                continue;
            };
            for (i, arg) in args.iter().enumerate() {
                out.push(DetectedDataFlow {
                    caller_qname: owner.qname.clone(),
                    callee_qname: callee_qname.clone(),
                    arg_index: i,
                    arg: arg.clone(),
                    file: file.to_string(),
                    line: line_no,
                    confidence: 0.7,
                });
            }
        }
    }
    out
}

/// Find `name(args)` call sites on a line where the callee is a bare function
/// (not a method) and every argument is a simple identifier. Returns
/// `(callee_name, [arg_idents])`.
fn simple_calls(line: &str) -> Vec<(String, Vec<String>)> {
    let t = line.trim_start();
    if t.starts_with("def ")
        || t.starts_with("async def ")
        || t.starts_with("class ")
        || t.starts_with('@')
        || t.starts_with('#')
    {
        return Vec::new();
    }
    let chars: Vec<char> = line.chars().collect();
    let mut out = Vec::new();
    let mut i = 0;
    while i < chars.len() {
        if chars[i] == '(' {
            // Capture the identifier ending right before '('.
            let mut start = i;
            while start > 0 && (chars[start - 1].is_alphanumeric() || chars[start - 1] == '_') {
                start -= 1;
            }
            let is_method = start > 0 && chars[start - 1] == '.';
            let name: String = chars[start..i].iter().collect();
            let valid = name
                .chars()
                .next()
                .is_some_and(|c| c.is_alphabetic() || c == '_');
            if !is_method && valid {
                if let Some(close) = matching_close(&chars, i) {
                    let inner: String = chars[i + 1..close].iter().collect();
                    if let Some(args) = simple_args(&inner) {
                        out.push((name, args));
                    }
                    i = close;
                }
            }
        }
        i += 1;
    }
    out
}

fn matching_close(chars: &[char], open: usize) -> Option<usize> {
    let mut depth = 0i32;
    let mut i = open;
    while i < chars.len() {
        match chars[i] {
            '(' => depth += 1,
            ')' => {
                depth -= 1;
                if depth == 0 {
                    return Some(i);
                }
            }
            _ => {}
        }
        i += 1;
    }
    None
}

/// `Some(args)` only when every comma-separated argument is a bare identifier
/// (no nested calls, literals, operators, or kwargs) and there is at least one.
fn simple_args(inner: &str) -> Option<Vec<String>> {
    let inner = inner.trim();
    if inner.is_empty() {
        return None;
    }
    let mut args = Vec::new();
    for part in inner.split(',') {
        let p = part.trim();
        let is_ident = p
            .chars()
            .next()
            .is_some_and(|c| c.is_alphabetic() || c == '_')
            && p.chars().all(|c| c.is_alphanumeric() || c == '_');
        if !is_ident || matches!(p, "True" | "False" | "None" | "self" | "cls") {
            return None;
        }
        args.push(p.to_string());
    }
    Some(args)
}

// -----------------------------------------------------------------------------
// Effect inference
// -----------------------------------------------------------------------------

fn infer_effects_from_body(body: &str) -> Vec<Effect> {
    let mut effects: Vec<Effect> = Vec::new();

    // Plan L t-002: detection runs on a copy with comments + string
    // literals masked to spaces, so an effect-like substring inside a
    // `# os.open(…)` comment or a `"os.open(…)"` literal no longer
    // produces a false-positive inference. We preserve byte length so
    // all the existing offset-based slicing (`&body[args_start..]`,
    // notes, path extraction) continues to read from the original
    // source — the mask only suppresses *matches*, not data.
    let masked = mask_comments_and_literals(body);
    let scan = masked.as_str();

    // open(...) -> IoFsRead (+ IoFsWrite when mode contains 'w' or 'a')
    for call_site in find_calls(scan, "open(") {
        let args = &body[call_site.args_start..call_site.args_end];
        effects.push(Effect {
            effect: EffectCategory::IoFsRead,
            qualifiers: extract_open_path(args)
                .map(|p| json!({ "paths": [p] }))
                .unwrap_or(serde_json::Value::Null),
            note: Some(trim_note(
                &body[call_site.call_start..call_site.args_end + 1],
            )),
            ..Default::default()
        });
        if mentions_write_mode(args) {
            effects.push(Effect {
                effect: EffectCategory::IoFsWrite,
                qualifiers: extract_open_path(args)
                    .map(|p| json!({ "paths": [p] }))
                    .unwrap_or(serde_json::Value::Null),
                note: Some(trim_note(
                    &body[call_site.call_start..call_site.args_end + 1],
                )),
                ..Default::default()
            });
        }
    }

    // print(...) / sys.stdout / sys.stderr / logging.* / log.* / logger.* -> Log
    let log_needles = [
        "print(",
        "sys.stdout",
        "sys.stderr",
        "logging.debug",
        "logging.info",
        "logging.warning",
        "logging.warn",
        "logging.error",
        "logging.critical",
        "logging.exception",
        "log.debug",
        "log.info",
        "log.warning",
        "log.warn",
        "log.error",
        "log.critical",
        "log.exception",
        "logger.debug",
        "logger.info",
        "logger.warning",
        "logger.warn",
        "logger.error",
        "logger.critical",
        "logger.exception",
    ];
    if log_needles.iter().any(|n| scan.contains(n)) {
        let note = first_matching_line(scan, body, &log_needles);
        effects.push(Effect {
            effect: EffectCategory::Log,
            qualifiers: serde_json::Value::Null,
            note,
            ..Default::default()
        });
    }

    // Database cursor/conn/db.execute(...) / .fetchone() / .commit()  -> IoDb*
    // Heuristic: inspect the SQL-like first arg of `.execute(` to decide
    // read vs write. Common names: db, conn, cursor, cur, session, c.
    let db_receivers = [
        "db.execute(",
        "conn.execute(",
        "cursor.execute(",
        "cur.execute(",
        "session.execute(",
        "c.execute(",
        "self.db.execute(",
        "self.conn.execute(",
    ];
    let mut seen_db_read = false;
    let mut seen_db_write = false;
    for recv in db_receivers {
        for call_site in find_calls(scan, recv) {
            let args = &body[call_site.args_start..call_site.args_end];
            let sql = args.trim_start_matches(|c: char| {
                c.is_whitespace() || c == '"' || c == '\'' || c == 'f' || c == 'r' || c == 'b'
            });
            let upper: String = sql.chars().take(16).collect::<String>().to_uppercase();
            let is_write = upper.starts_with("INSERT")
                || upper.starts_with("UPDATE")
                || upper.starts_with("DELETE")
                || upper.starts_with("REPLACE")
                || upper.starts_with("CREATE")
                || upper.starts_with("DROP")
                || upper.starts_with("ALTER")
                || upper.starts_with("TRUNCATE");
            let is_read = upper.starts_with("SELECT")
                || upper.starts_with("WITH")
                || upper.starts_with("SHOW");
            let note = Some(trim_note(
                &body[call_site.call_start..call_site.args_end + 1],
            ));
            if is_write && !seen_db_write {
                effects.push(Effect {
                    effect: EffectCategory::IoDbWrite,
                    qualifiers: serde_json::Value::Null,
                    note,
                    ..Default::default()
                });
                seen_db_write = true;
            } else if is_read && !seen_db_read {
                effects.push(Effect {
                    effect: EffectCategory::IoDbRead,
                    qualifiers: serde_json::Value::Null,
                    note,
                    ..Default::default()
                });
                seen_db_read = true;
            } else if !is_write && !is_read && !seen_db_read && !seen_db_write {
                // Unrecognized SQL — conservatively emit both.
                effects.push(Effect {
                    effect: EffectCategory::IoDbRead,
                    qualifiers: serde_json::Value::Null,
                    note: note.clone(),
                    ..Default::default()
                });
                effects.push(Effect {
                    effect: EffectCategory::IoDbWrite,
                    qualifiers: serde_json::Value::Null,
                    note,
                    ..Default::default()
                });
                seen_db_read = true;
                seen_db_write = true;
            }
        }
    }
    // .commit() implies a preceding write
    if !seen_db_write && (scan.contains(".commit()") || scan.contains("conn.commit")) {
        effects.push(Effect {
            effect: EffectCategory::IoDbWrite,
            qualifiers: serde_json::Value::Null,
            note: first_matching_line(scan, body, &[".commit()", "conn.commit"]),
            ..Default::default()
        });
    }

    // Network libraries -> IoNetOut
    let net_prefixes = ["requests.", "urllib.", "httpx.", "aiohttp."];
    let mut net_hosts: Vec<String> = Vec::new();
    let mut net_note: Option<String> = None;
    for prefix in net_prefixes {
        for call_site in find_prefixed_calls(scan, prefix) {
            let args = &body[call_site.args_start..call_site.args_end];
            if let Some(host) = extract_url_host(args) {
                if !net_hosts.contains(&host) {
                    net_hosts.push(host);
                }
            }
            if net_note.is_none() {
                net_note = Some(trim_note(
                    &body[call_site.call_start..call_site.args_end + 1],
                ));
            }
        }
    }
    if net_note.is_some() {
        let qualifiers = if net_hosts.is_empty() {
            serde_json::Value::Null
        } else {
            json!({ "hosts": net_hosts })
        };
        effects.push(Effect {
            effect: EffectCategory::IoNetOut,
            qualifiers,
            note: net_note,
            ..Default::default()
        });
    }

    // subprocess.* / os.system / os.exec* -> ProcSpawn
    let proc_patterns = ["subprocess.", "os.system(", "os.exec"];
    if let Some(note) = first_match_note(scan, body, &proc_patterns) {
        effects.push(Effect {
            effect: EffectCategory::ProcSpawn,
            qualifiers: serde_json::Value::Null,
            note: Some(note),
            ..Default::default()
        });
    }

    // os.environ / os.getenv -> EnvRead
    let env_patterns = ["os.environ", "os.getenv"];
    if let Some(note) = first_match_note(scan, body, &env_patterns) {
        let mut vars: Vec<String> = Vec::new();
        for call_site in find_calls(scan, "os.getenv(") {
            let args = &body[call_site.args_start..call_site.args_end];
            if let Some(v) = extract_first_string_literal(args) {
                if !vars.contains(&v) {
                    vars.push(v);
                }
            }
        }
        let qualifiers = if vars.is_empty() {
            serde_json::Value::Null
        } else {
            json!({ "vars": vars })
        };
        effects.push(Effect {
            effect: EffectCategory::EnvRead,
            qualifiers,
            note: Some(note),
            ..Default::default()
        });
    }

    // time.sleep -> TimeSleep
    if let Some(note) = first_match_note(scan, body, &["time.sleep"]) {
        effects.push(Effect {
            effect: EffectCategory::TimeSleep,
            qualifiers: serde_json::Value::Null,
            note: Some(note),
            ..Default::default()
        });
    }

    // time.time / time.monotonic / datetime.now -> TimeRead
    let time_read_patterns = [
        "time.time",
        "time.monotonic",
        "time.perf_counter",
        "datetime.now",
        "datetime.utcnow",
        "datetime.today",
    ];
    if let Some(note) = first_match_note(scan, body, &time_read_patterns) {
        effects.push(Effect {
            effect: EffectCategory::TimeRead,
            qualifiers: serde_json::Value::Null,
            note: Some(note),
            ..Default::default()
        });
    }

    // random.* / secrets.* -> Random
    let random_patterns = ["random.", "secrets.", "os.urandom("];
    if let Some(note) = first_match_note(scan, body, &random_patterns) {
        effects.push(Effect {
            effect: EffectCategory::Random,
            qualifiers: serde_json::Value::Null,
            note: Some(note),
            ..Default::default()
        });
    }

    // `raise ` statement -> Throw
    if has_raise_statement(scan) {
        let note = first_matching_line(scan, body, &["raise "]);
        effects.push(Effect {
            effect: EffectCategory::Throw,
            qualifiers: serde_json::Value::Null,
            note,
            ..Default::default()
        });
    }

    effects
}

/// Scan for a literal needle and return the lines we recognize as actual call
/// sites. We do not attempt to skip string literals — for M1 this is good
/// enough and matches the "plain substring" guidance.
#[derive(Debug, Clone, Copy)]
struct CallSite {
    call_start: usize,
    args_start: usize,
    args_end: usize,
}

/// Find all call sites where `needle` (which must end in `(`) appears in
/// `body`, returning the byte offsets of the opening identifier, the byte
/// after the `(`, and the matching `)`.
fn find_calls(body: &str, needle: &str) -> Vec<CallSite> {
    let mut out = Vec::new();
    if !needle.ends_with('(') {
        return out;
    }
    let bytes = body.as_bytes();
    let mut search_from = 0;
    while let Some(idx) = body[search_from..].find(needle) {
        let abs = search_from + idx;
        let args_start = abs + needle.len();
        if let Some(args_end) = find_matching_paren(bytes, args_start) {
            out.push(CallSite {
                call_start: abs,
                args_start,
                args_end,
            });
            search_from = args_end + 1;
        } else {
            search_from = args_start;
        }
    }
    out
}

#[allow(dead_code)]
fn contains_call(body: &str, needle: &str) -> bool {
    !find_calls(body, needle).is_empty()
}

/// Like [`find_calls`], but for a dotted module/receiver prefix that ends in
/// `.` (e.g. `"requests."`). Matches `prefix<identifier>(` — the dotted
/// prefix, a bare method identifier, then the call's parens — and returns a
/// [`CallSite`] whose `call_start` is the prefix start and whose
/// `args_start..args_end` span the parenthesised arguments.
///
/// `find_calls` requires its needle to end in `(`, so passing a varying-method
/// prefix like `"requests."` to it returns nothing (the guard rejects
/// non-`(` needles). That is exactly how the network-effect detection used to
/// silently no-op for `requests.get(...)` / `httpx.post(...)`; this helper
/// closes that gap.
fn find_prefixed_calls(body: &str, prefix: &str) -> Vec<CallSite> {
    let mut out = Vec::new();
    let bytes = body.as_bytes();
    let mut from = 0;
    while let Some(rel) = body[from..].find(prefix) {
        let abs = from + rel;
        let after = abs + prefix.len();
        from = after;
        // The method name must be a bare identifier immediately followed by '('.
        let rest = &body[after..];
        let name_len = rest
            .find(|c: char| !(c.is_alphanumeric() || c == '_'))
            .unwrap_or(rest.len());
        if name_len == 0 || rest.as_bytes().get(name_len) != Some(&b'(') {
            continue;
        }
        let args_start = after + name_len + 1;
        if let Some(args_end) = find_matching_paren(bytes, args_start) {
            out.push(CallSite {
                call_start: abs,
                args_start,
                args_end,
            });
            from = args_end + 1;
        }
    }
    out
}

/// Given the position just after `(`, find the matching `)`. Handles nested
/// parens and single/double quoted strings (non-raw). Returns the index of the
/// matching `)` byte.
fn find_matching_paren(bytes: &[u8], start: usize) -> Option<usize> {
    let mut depth: i32 = 1;
    let mut i = start;
    let mut in_string: Option<u8> = None;
    while i < bytes.len() {
        let c = bytes[i];
        if let Some(q) = in_string {
            if c == b'\\' {
                i += 2;
                continue;
            }
            if c == q {
                in_string = None;
            }
        } else {
            match c {
                b'"' | b'\'' => in_string = Some(c),
                b'(' => depth += 1,
                b')' => {
                    depth -= 1;
                    if depth == 0 {
                        return Some(i);
                    }
                }
                _ => {}
            }
        }
        i += 1;
    }
    None
}

fn mentions_write_mode(args: &str) -> bool {
    // Look for a mode string literal containing 'w' or 'a'. Very loose —
    // we just scan quoted sections.
    let bytes = args.as_bytes();
    let mut i = 0;
    while i < bytes.len() {
        let c = bytes[i];
        if c == b'"' || c == b'\'' {
            let q = c;
            let start = i + 1;
            let mut j = start;
            while j < bytes.len() && bytes[j] != q {
                if bytes[j] == b'\\' {
                    j += 2;
                    continue;
                }
                j += 1;
            }
            if j <= bytes.len() {
                let lit = &args[start..j.min(bytes.len())];
                if lit.len() <= 4 && (lit.contains('w') || lit.contains('a') || lit.contains('x')) {
                    return true;
                }
                i = j + 1;
                continue;
            }
        }
        i += 1;
    }
    false
}

/// Extract the first positional argument if it is a plain string literal.
fn extract_open_path(args: &str) -> Option<String> {
    extract_first_string_literal(args)
}

/// If the args start with a string literal, return its contents.
fn extract_first_string_literal(args: &str) -> Option<String> {
    let trimmed = args.trim_start();
    let bytes = trimmed.as_bytes();
    if bytes.is_empty() {
        return None;
    }
    let q = bytes[0];
    if q != b'"' && q != b'\'' {
        return None;
    }
    let mut j = 1;
    let mut out = String::new();
    while j < bytes.len() {
        let c = bytes[j];
        if c == b'\\' && j + 1 < bytes.len() {
            out.push(bytes[j + 1] as char);
            j += 2;
            continue;
        }
        if c == q {
            return Some(out);
        }
        out.push(c as char);
        j += 1;
    }
    None
}

/// Try to extract a host from args containing a URL literal.
fn extract_url_host(args: &str) -> Option<String> {
    // Find any `http://` or `https://` in the args text.
    let lower = args;
    for scheme in ["https://", "http://"] {
        if let Some(idx) = lower.find(scheme) {
            let tail = &lower[idx + scheme.len()..];
            let end = tail
                .find(|c: char| {
                    c == '/' || c == '"' || c == '\'' || c == ')' || c == '?' || c.is_whitespace()
                })
                .unwrap_or(tail.len());
            let host = &tail[..end];
            if !host.is_empty() {
                return Some(host.to_string());
            }
        }
    }
    None
}

/// Return a short, single-line note snippet.
/// Cap a doc string at 512 characters, trimming at a word boundary when possible.
fn truncate_doc(s: &str) -> String {
    const MAX: usize = 512;
    if s.len() <= MAX {
        return s.to_string();
    }
    // Try to break at a space before the limit.
    let truncated = &s[..MAX];
    match truncated.rfind(' ') {
        Some(pos) => format!("{}…", &truncated[..pos]),
        None => format!("{}…", truncated),
    }
}

fn trim_note(s: &str) -> String {
    let first_line = s.lines().next().unwrap_or("").trim();
    if first_line.len() > 120 {
        format!("{}...", &first_line[..120])
    } else {
        first_line.to_string()
    }
}

/// Plan L t-002: scan `scan` for a match (so comments / string literals
/// previously masked to spaces don't trigger), but return the matching
/// line from `body` so the note reflects the real source text. `scan`
/// and `body` MUST be the same byte length and split into the same
/// line count for the alignment to hold.
fn first_matching_line(scan: &str, body: &str, needles: &[&str]) -> Option<String> {
    for (i, scan_line) in scan.lines().enumerate() {
        for n in needles {
            if scan_line.contains(n) {
                return body.lines().nth(i).map(|l| l.trim().to_string());
            }
        }
    }
    None
}

/// Check each needle against the masked `scan`; return the first
/// matching line from the real `body` as a note.
fn first_match_note(scan: &str, body: &str, needles: &[&str]) -> Option<String> {
    for n in needles {
        if scan.contains(n) {
            return first_matching_line(scan, body, needles);
        }
    }
    None
}

/// Detect a `raise` statement (not `raises` in a docstring or attribute).
/// We check for `raise ` preceded by start-of-line or whitespace.
/// Operates on the masked `scan` so a `raise` inside a comment or
/// string literal doesn't trip the detector.
fn has_raise_statement(scan: &str) -> bool {
    for line in scan.lines() {
        let trimmed = line.trim_start();
        if trimmed.starts_with("raise ") || trimmed == "raise" {
            return true;
        }
    }
    false
}

/// Plan L t-005: scan Python source for call patterns the static
/// call-graph walker can't resolve. Returns one hint per detected
/// site so the indexer can surface a warning. The patterns we
/// flag are deliberately conservative — only the ones that are
/// unambiguously dynamic dispatch:
///
/// - `getattr(obj, "name")(args)` and `getattr(obj, name_var)(args)`
///   — runtime attribute lookup feeding a call.
/// - `__getattr__` / `__getattribute__` method definitions — the
///   class promises to resolve unknown attributes at runtime.
///
/// We deliberately do NOT flag plain `getattr(obj, "name")` (no
/// trailing call) — that's a read, not a dispatch, and gets
/// resolved by the property/attribute pass.
///
/// Detection runs against the masked source (Plan L t-002) so a
/// `# getattr(...)` in a comment doesn't generate a phantom warning.
pub fn scan_dynamic_dispatch_in_python(file: &str, source: &str) -> Vec<DynamicDispatchHint> {
    let masked = mask_comments_and_literals(source);
    let mut hints = Vec::new();
    let bytes = masked.as_bytes();
    let body = source.as_bytes();
    let mut line_starts: Vec<usize> = vec![0];
    for (i, b) in body.iter().enumerate() {
        if *b == b'\n' {
            line_starts.push(i + 1);
        }
    }
    let line_of = |off: usize| -> u32 {
        match line_starts.binary_search(&off) {
            Ok(i) => i as u32 + 1,
            Err(i) => i.max(1) as u32,
        }
    };
    let snippet_at = |off: usize| -> String {
        let line_idx = line_of(off).saturating_sub(1) as usize;
        let start = line_starts.get(line_idx).copied().unwrap_or(0);
        let end = line_starts
            .get(line_idx + 1)
            .copied()
            .unwrap_or(body.len())
            .saturating_sub(1);
        std::str::from_utf8(&body[start..end])
            .map(|s| s.trim().to_string())
            .unwrap_or_default()
    };

    // Pattern 1: getattr(obj, …)(…)  — the trailing `(` after the
    // outer `)` is the giveaway. We use find_calls + check the byte
    // right after args_end.
    for site in find_calls(&masked, "getattr(") {
        // Peek past the closing `)` for an opening `(` (allowing
        // whitespace / chained attribute reads in between is more
        // ambitious — for v1 we require an immediate call).
        let mut j = site.args_end + 1;
        while j < bytes.len() && (bytes[j] == b' ' || bytes[j] == b'\t') {
            j += 1;
        }
        if j < bytes.len() && bytes[j] == b'(' {
            hints.push(DynamicDispatchHint {
                file: file.to_string(),
                line: line_of(site.call_start),
                pattern: "getattr".into(),
                snippet: snippet_at(site.call_start),
            });
        }
    }

    // Pattern 2: `def __getattr__(self, …)` / `def __getattribute__(…)`
    // method definitions. Scan line by line; `mask_comments_and_literals`
    // preserves line splits so offsets align.
    for (i, line) in masked.lines().enumerate() {
        let trimmed = line.trim_start();
        if trimmed.starts_with("def __getattr__(") || trimmed.starts_with("def __getattribute__(") {
            let off = line_starts.get(i).copied().unwrap_or(0);
            hints.push(DynamicDispatchHint {
                file: file.to_string(),
                line: (i + 1) as u32,
                pattern: "__getattr__".into(),
                snippet: snippet_at(off),
            });
        }
    }

    hints
}

/// Plan L t-002: walk Python source and replace bytes inside `#`
/// line comments and string literals (single/double/triple, with
/// optional `r` / `b` / `f` prefixes) with ASCII space. Newlines and
/// every other byte stay where they are, so the output has the same
/// byte length AND the same line split as the input. Callers can
/// detect call patterns against the masked output and use byte
/// offsets to extract real text from the original body.
///
/// Limitations:
/// - F-string interpolations inside `f"{expr}"` are masked along
///   with the rest of the literal. An effect inside an f-string
///   interpolation will be missed. Acceptable trade — the bug being
///   fixed is comments and plain strings producing false positives;
///   under-detecting f-string interpolations is conservative.
/// - Raw strings (`r"..."`) are masked normally; backslashes don't
///   escape the closing quote.
fn mask_comments_and_literals(body: &str) -> String {
    let bytes = body.as_bytes();
    let mut out: Vec<u8> = bytes.to_vec();
    let n = bytes.len();
    let mut i = 0;
    while i < n {
        let c = bytes[i];
        // Line comment: `#` to end-of-line, but not inside an f-string
        // (we're not in a string here because we'd have entered the
        // literal branch below).
        if c == b'#' {
            let mut j = i;
            while j < n && bytes[j] != b'\n' {
                out[j] = b' ';
                j += 1;
            }
            i = j;
            continue;
        }
        // String literal start. Optional prefix: r/R/b/B/f/F (and
        // combinations like rb, fr, Rb…). The prefix bytes themselves
        // are NOT masked — they're identifiers as far as effect
        // detection is concerned, and erasing them could turn
        // `rb"…"` into `  "…"` which still parses as a literal but
        // changes column counts in error paths. Leave the prefix,
        // mask the literal body.
        let quote_start = find_quote_after_optional_prefix(bytes, i);
        if let Some(qi) = quote_start {
            let q = bytes[qi];
            // Triple quote?
            let triple = qi + 2 < n && bytes[qi + 1] == q && bytes[qi + 2] == q;
            let (literal_start, end_pos) = if triple {
                let inner_start = qi + 3;
                let end = find_triple_close(bytes, inner_start, q);
                (inner_start, end)
            } else {
                let inner_start = qi + 1;
                let end = find_single_close(bytes, inner_start, q);
                (inner_start, end)
            };
            // Mask the literal body (between the open and close
            // quotes). Quotes themselves stay so paren-matching and
            // any human-eyeballing of the masked source still reads.
            for k in literal_start..end_pos.min(n) {
                if out[k] != b'\n' {
                    out[k] = b' ';
                }
            }
            // Advance past the closing quote(s).
            i = end_pos + if triple { 3 } else { 1 };
            continue;
        }
        i += 1;
    }
    // Safety: byte length must be preserved for offset-based slicing
    // upstream. `out` was built from `bytes.to_vec()` and only mutated
    // in place, so length is identical to `body.len()`. The mutations
    // only ever swap a byte for ASCII space (0x20) or leave it alone,
    // both of which keep the buffer valid UTF-8.
    debug_assert_eq!(out.len(), bytes.len());
    String::from_utf8(out).unwrap_or_else(|_| body.to_string())
}

/// Skip optional Python string prefix bytes (`r`, `R`, `b`, `B`, `f`,
/// `F`, in 1- or 2-char combinations like `rb`/`Rb`/`fr`) starting at
/// `i`, returning the index of the opening quote if found. Only
/// activates when `bytes[i]` is one of the prefix bytes AND a quote
/// follows within two bytes — otherwise the caller's `i` is on a
/// normal identifier byte and we return None.
fn find_quote_after_optional_prefix(bytes: &[u8], i: usize) -> Option<usize> {
    let n = bytes.len();
    if i >= n {
        return None;
    }
    let c = bytes[i];
    if c == b'"' || c == b'\'' {
        return Some(i);
    }
    let is_prefix = |b: u8| matches!(b, b'r' | b'R' | b'b' | b'B' | b'f' | b'F');
    if !is_prefix(c) {
        return None;
    }
    // The byte before `i` must NOT be an identifier byte — otherwise
    // we're in the middle of a word like `_renderRequest`, not at a
    // string prefix. Treat any ASCII alphanumeric or underscore as
    // identifier-continuing.
    if i > 0 {
        let prev = bytes[i - 1];
        if prev.is_ascii_alphanumeric() || prev == b'_' {
            return None;
        }
    }
    // 1-char prefix: `r"…"`
    if i + 1 < n && (bytes[i + 1] == b'"' || bytes[i + 1] == b'\'') {
        return Some(i + 1);
    }
    // 2-char prefix: `rb"…"` / `fr"…"` / etc.
    if i + 2 < n && is_prefix(bytes[i + 1]) && (bytes[i + 2] == b'"' || bytes[i + 2] == b'\'') {
        return Some(i + 2);
    }
    None
}

/// Find the closing single-quote `q` starting from `start`. Honors
/// backslash escapes. Returns the index of the closing quote, or
/// `bytes.len()` if no close found (treat as "string runs to EOF").
/// A bare newline closes a non-triple string in Python — we honor
/// that so an unterminated literal doesn't mask the rest of the file.
fn find_single_close(bytes: &[u8], start: usize, q: u8) -> usize {
    let n = bytes.len();
    let mut j = start;
    while j < n {
        let b = bytes[j];
        if b == b'\\' {
            j += 2;
            continue;
        }
        if b == b'\n' {
            return j; // unterminated; stop at newline
        }
        if b == q {
            return j;
        }
        j += 1;
    }
    n
}

/// Find the closing `qqq` triple-quote sequence starting from `start`.
/// Returns the index of the FIRST quote in the closing triple, or
/// `bytes.len()` if the literal runs to EOF.
fn find_triple_close(bytes: &[u8], start: usize, q: u8) -> usize {
    let n = bytes.len();
    let mut j = start;
    while j + 2 < n {
        if bytes[j] == b'\\' {
            j += 2;
            continue;
        }
        if bytes[j] == q && bytes[j + 1] == q && bytes[j + 2] == q {
            return j;
        }
        j += 1;
    }
    n
}

// -----------------------------------------------------------------------------
// Call-edge extraction (intra- and cross-module)
// -----------------------------------------------------------------------------

/// Build the (caller_qname -> callee_qname) edge set for one file. Resolution
/// is best-effort and covers:
///
/// - `identifier()` -> intra-module `simple_name -> qname`, then imports
///   (`from foo import bar` / `import foo as f`).
/// - `Class.method()` -> resolve `<module>.Class.method`.
/// - `self.method()` inside `<module>.Class.<fn>` -> resolve to `<module>.Class.method`.
/// - `foo.bar()` where `foo` is an imported module -> resolve via the import
///   map to `<foo_prefix>.bar`, and emit only if that qname exists in the
///   workspace. This is how we capture cross-module calls like
///   `logger.write_log` from `_driver.py`.
///
/// Anything we can't resolve (subscripts, lambdas, star imports, relative
/// imports, dynamic dispatch) is silently skipped.
fn extract_call_edges_impl(
    file: &str,
    source: &str,
    symbols: &[ParsedSymbol],
    workspace: &WorkspaceSymbols,
) -> Vec<CallEdge> {
    let module_prefix = module_qname_prefix(file);

    // All known qnames in this file.
    let known: HashSet<&str> = symbols.iter().map(|s| s.qname.as_str()).collect();

    // simple_name -> qname for single-identifier resolution. If two symbols
    // share a simple name (e.g. method/function collision), we keep the first
    // module-level one we see; this is best-effort by design.
    let mut by_simple: HashMap<String, String> = HashMap::new();
    for s in symbols {
        let simple = s.qname.rsplit('.').next().unwrap_or(&s.qname).to_string();
        // Prefer module-level functions/classes over nested entries: only fill
        // if the qname has exactly module_prefix + "." + simple.
        let module_level = if module_prefix.is_empty() {
            s.qname == simple
        } else {
            s.qname == format!("{}.{}", module_prefix, simple)
        };
        if module_level {
            by_simple.insert(simple, s.qname.clone());
        } else {
            by_simple.entry(simple).or_insert_with(|| s.qname.clone());
        }
    }

    let mut parser = Parser::new();
    if parser
        .set_language(&tree_sitter_python::LANGUAGE.into())
        .is_err()
    {
        return Vec::new();
    }

    // Parse the full source once to extract top-level imports. We need the
    // file-level tree (not individual symbol bodies) so we can pick up
    // `import foo` / `from foo import bar` at module scope. module_prefix
    // is passed so relative imports (`from . import x`, `from .foo import y`)
    // can be resolved to absolute qnames — Plan D t-004.
    let imports = parse_imports(source, &mut parser, &module_prefix);

    let mut edges: HashSet<CallEdge> = HashSet::new();

    for sym in symbols {
        // Only function and method bodies can contain calls in a meaningful
        // sense; skip class/module symbols (their bodies' calls are usually
        // attributed to a wrapping function anyway).
        if !matches!(sym.kind, SymbolKind::Function | SymbolKind::Method) {
            continue;
        }

        let src_bytes = sym.body.as_bytes();
        let tree = match parser.parse(src_bytes, None) {
            Some(t) => t,
            None => continue,
        };

        // The parsed body is a `function_definition` at (or near) the root —
        // walk the whole tree and pick up every `call` node.
        let enclosing_class = enclosing_class_qname(&sym.qname, &module_prefix, &known);
        collect_calls(
            tree.root_node(),
            src_bytes,
            sym,
            &module_prefix,
            &by_simple,
            &known,
            &imports,
            workspace,
            enclosing_class.as_deref(),
            &mut edges,
        );
    }

    let mut out: Vec<CallEdge> = edges.into_iter().collect();
    out.sort_by(|a, b| {
        a.caller_qname
            .cmp(&b.caller_qname)
            .then_with(|| a.callee_qname.cmp(&b.callee_qname))
    });
    out
}

/// Imports discovered at module scope, keyed by the local binding.
///
/// Each entry records:
/// - `qname_prefix`: the qname (or qname prefix) the local name resolves to.
/// - `is_module`: whether the local name refers to a *module* (resolve
///   `local.attr` -> `qname_prefix.attr`) vs. a single imported symbol
///   (resolve `local.attr` -> `qname_prefix.attr` as well, but `local()`
///   resolves to `qname_prefix` directly).
#[derive(Debug, Clone)]
struct ImportBinding {
    qname_prefix: String,
    /// `true` for `import foo` / `import foo as f`; `false` for
    /// `from foo import bar`. Currently both forms resolve attribute access
    /// via the same path (`qname_prefix` + `.` + `attr`), but we keep the
    /// distinction so future resolvers (e.g., re-exports) can tell apart
    /// module handles from direct symbol bindings.
    #[allow(dead_code)]
    is_module: bool,
}

/// Walk the file's top-level statements and collect import bindings.
///
/// Supports:
/// - `import foo` -> `foo -> ("foo", module)`
/// - `import foo.bar` -> `foo -> ("foo", module)` (only the first segment binds)
/// - `import foo as f` -> `f -> ("foo", module)`
/// - `from foo import bar` -> `bar -> ("foo.bar", symbol)`
/// - `from foo import bar as b` -> `b -> ("foo.bar", symbol)`
/// - `from foo import (a, b, c)` -> each as above
/// - Plan D t-004: relative imports (`from . import x`, `from .foo import y`,
///   `from ..pkg import z`) — resolved against `module_prefix`.
///
/// - Plan L t-004: imports nested inside function bodies, class
///   bodies, and conditional blocks (`if TYPE_CHECKING:`, `try: …
///   except ImportError: …`) are also collected and merged into the
///   same flat map.
///
/// Skips:
/// - `from foo import *` — can't statically resolve members.
///
/// Nested-import scoping policy: we deliberately use a single flat
/// map rather than per-function scoping. Real Python code rarely
/// shadows module-scope imports inside a function under the same
/// local name; when it does (typically `try/except ImportError`
/// fallbacks), either branch resolving to the same prefix is the
/// behavior callers want. The trade-off: a function that genuinely
/// imports a different module under a colliding name would resolve
/// to whichever was inserted last. Acceptable for the call-edge
/// signal we're building.
fn parse_imports(
    source: &str,
    parser: &mut Parser,
    module_prefix: &str,
) -> HashMap<String, ImportBinding> {
    let mut out: HashMap<String, ImportBinding> = HashMap::new();
    let src_bytes = source.as_bytes();
    let tree = match parser.parse(src_bytes, None) {
        Some(t) => t,
        None => return out,
    };
    walk_imports(tree.root_node(), src_bytes, module_prefix, &mut out);
    out
}

/// Plan L t-004: recursively walk the tree picking up every
/// `import_statement` / `import_from_statement` node — module-scope
/// AND nested. Skipping non-import nodes is implicit; we just
/// recurse into every child and dispatch on `kind()`.
///
/// We don't prune at function/class boundaries on purpose: a
/// `if TYPE_CHECKING:` block sits at module scope, a body import
/// sits inside a function, a `try: import cPickle / except: import
/// pickle` sits inside a `try_statement`. Recursing everywhere
/// catches all three with one walk.
fn walk_imports(
    node: Node<'_>,
    src: &[u8],
    module_prefix: &str,
    out: &mut HashMap<String, ImportBinding>,
) {
    match node.kind() {
        "import_statement" => {
            collect_import_statement(node, src, out);
            return;
        }
        "import_from_statement" => {
            collect_import_from_statement(node, src, module_prefix, out);
            return;
        }
        _ => {}
    }
    let mut cursor = node.walk();
    for child in node.children(&mut cursor) {
        walk_imports(child, src, module_prefix, out);
    }
}

/// Plan D t-004: resolve a relative-import dot prefix against the importing
/// file's `module_prefix`. Returns the absolute module qname (e.g.
/// "crucible.agents.base") that the dots + optional suffix point to, or
/// None when the relative import escapes the workspace.
fn resolve_relative_import(module_prefix: &str, raw: &str) -> Option<String> {
    let dot_count = raw.chars().take_while(|c| *c == '.').count();
    if dot_count == 0 {
        return None;
    }
    let suffix = raw[dot_count..].trim().trim_matches('.');
    let parts: Vec<&str> = if module_prefix.is_empty() {
        Vec::new()
    } else {
        module_prefix.split('.').collect()
    };
    if dot_count > parts.len() {
        return None;
    }
    let keep = parts.len() - dot_count;
    let mut base = parts[..keep].join(".");
    if !suffix.is_empty() {
        if !base.is_empty() {
            base.push('.');
        }
        base.push_str(suffix);
    }
    if base.is_empty() { None } else { Some(base) }
}

/// Handle `import a, b as c, d.e`.
fn collect_import_statement(node: Node<'_>, src: &[u8], out: &mut HashMap<String, ImportBinding>) {
    // Tree-sitter-python emits each imported name as a `name` field (which
    // may appear multiple times), each being either `dotted_name` or
    // `aliased_import`.
    let mut cursor = node.walk();
    for child in node.children_by_field_name("name", &mut cursor) {
        match child.kind() {
            "dotted_name" => {
                // `import foo.bar.baz` -> local binding is the first segment,
                // but resolves to just that first segment (not the tail —
                // Python only binds the top package name).
                let full = node_text(child, src).unwrap_or_default();
                let full = full.trim().to_string();
                if full.is_empty() {
                    continue;
                }
                let first = full.split('.').next().unwrap_or(&full).to_string();
                out.insert(
                    first.clone(),
                    ImportBinding {
                        qname_prefix: first,
                        is_module: true,
                    },
                );
                // Also register the fully-dotted form so `foo.bar.baz(...)`
                // written explicitly can resolve to a module qname prefix.
                if full.contains('.') {
                    out.insert(
                        full.clone(),
                        ImportBinding {
                            qname_prefix: full,
                            is_module: true,
                        },
                    );
                }
            }
            "aliased_import" => {
                // `import foo as f` / `import foo.bar as fb`
                let name = child
                    .child_by_field_name("name")
                    .and_then(|n| node_text(n, src))
                    .unwrap_or_default();
                let alias = child
                    .child_by_field_name("alias")
                    .and_then(|n| node_text(n, src))
                    .unwrap_or_default();
                let name = name.trim().to_string();
                let alias = alias.trim().to_string();
                if name.is_empty() || alias.is_empty() {
                    continue;
                }
                out.insert(
                    alias,
                    ImportBinding {
                        qname_prefix: name,
                        is_module: true,
                    },
                );
            }
            _ => {}
        }
    }
}

/// Handle `from foo import a, b as c` and `from foo import (a, b)`.
fn collect_import_from_statement(
    node: Node<'_>,
    src: &[u8],
    module_prefix: &str,
    out: &mut HashMap<String, ImportBinding>,
) {
    // `module_name` field holds a `dotted_name` or `relative_import`.
    let module_node = node.child_by_field_name("module_name");
    let module_kind = module_node.map(|n| n.kind()).unwrap_or("");
    let module = if module_kind == "relative_import" {
        // Plan D t-004: resolve `.`/`..`/etc. against the importing file's
        // module_prefix. `from . import x` from crucible/agents/foo.py
        // resolves to module "crucible.agents".
        let raw = module_node
            .and_then(|n| node_text(n, src))
            .unwrap_or_default();
        match resolve_relative_import(module_prefix, raw.trim()) {
            Some(m) => m,
            None => return,
        }
    } else {
        let m = module_node
            .and_then(|n| node_text(n, src))
            .unwrap_or_default()
            .trim()
            .to_string();
        if m.is_empty() {
            return;
        }
        m
    };

    // Detect `from foo import *` — tree-sitter-python represents the `*` as
    // a `wildcard_import` child (not a `name` field). Skip in that case.
    let mut cursor_all = node.walk();
    for child in node.children(&mut cursor_all) {
        if child.kind() == "wildcard_import" {
            return;
        }
    }

    let mut cursor = node.walk();
    for child in node.children_by_field_name("name", &mut cursor) {
        match child.kind() {
            "dotted_name" => {
                let name = node_text(child, src).unwrap_or_default();
                let name = name.trim().to_string();
                if name.is_empty() {
                    continue;
                }
                let qname = format!("{module}.{name}");
                out.insert(
                    name,
                    ImportBinding {
                        qname_prefix: qname,
                        is_module: false,
                    },
                );
            }
            "aliased_import" => {
                let name = child
                    .child_by_field_name("name")
                    .and_then(|n| node_text(n, src))
                    .unwrap_or_default();
                let alias = child
                    .child_by_field_name("alias")
                    .and_then(|n| node_text(n, src))
                    .unwrap_or_default();
                let name = name.trim().to_string();
                let alias = alias.trim().to_string();
                if name.is_empty() || alias.is_empty() {
                    continue;
                }
                let qname = format!("{module}.{name}");
                out.insert(
                    alias,
                    ImportBinding {
                        qname_prefix: qname,
                        is_module: false,
                    },
                );
            }
            _ => {}
        }
    }
}

/// For a method qname like `mod.Class.m`, return `Some("mod.Class")` provided
/// `mod.Class` is a known symbol in this file. Otherwise `None`.
fn enclosing_class_qname(
    qname: &str,
    module_prefix: &str,
    known: &HashSet<&str>,
) -> Option<String> {
    let parts: Vec<&str> = qname.split('.').collect();
    if parts.len() < 2 {
        return None;
    }
    // Drop the function/method name; look for the deepest ancestor that is a
    // known symbol AND lives below `module_prefix`.
    for end in (1..parts.len()).rev() {
        let candidate = parts[..end].join(".");
        if !module_prefix.is_empty() && !candidate.starts_with(module_prefix) {
            continue;
        }
        if known.contains(candidate.as_str()) {
            return Some(candidate);
        }
    }
    None
}

#[allow(clippy::too_many_arguments)]
fn collect_calls(
    node: Node<'_>,
    src: &[u8],
    sym: &ParsedSymbol,
    module_prefix: &str,
    by_simple: &HashMap<String, String>,
    known: &HashSet<&str>,
    imports: &HashMap<String, ImportBinding>,
    workspace: &WorkspaceSymbols,
    enclosing_class: Option<&str>,
    out: &mut HashSet<CallEdge>,
) {
    if node.kind() == "call" {
        if let Some(func) = node.child_by_field_name("function") {
            if let Some(callee) = resolve_callee(
                func,
                src,
                module_prefix,
                by_simple,
                known,
                imports,
                workspace,
                enclosing_class,
            ) {
                out.insert(CallEdge {
                    caller_qname: sym.qname.clone(),
                    callee_qname: callee,
                });
            }
        }
    }
    let mut cursor = node.walk();
    for child in node.children(&mut cursor) {
        collect_calls(
            child,
            src,
            sym,
            module_prefix,
            by_simple,
            known,
            imports,
            workspace,
            enclosing_class,
            out,
        );
    }
}

/// Resolve the function-position node of a `call` to a fully-qualified name,
/// when possible. Precedence (LEGB-ish, for our purposes):
///
/// 1. Intra-module `simple_name -> qname` (local definitions shadow imports).
/// 2. Import map (`from foo import bar` / `import foo as f`).
/// 3. For attribute calls, try intra-module class resolution, then imports.
///
/// Cross-module resolutions are only emitted when the resolved qname is
/// present in `workspace.qnames`. This drops stdlib / third-party calls
/// whose symbols we didn't index.
#[allow(clippy::too_many_arguments)]
fn resolve_callee(
    func: Node<'_>,
    src: &[u8],
    module_prefix: &str,
    by_simple: &HashMap<String, String>,
    known: &HashSet<&str>,
    imports: &HashMap<String, ImportBinding>,
    workspace: &WorkspaceSymbols,
    enclosing_class: Option<&str>,
) -> Option<String> {
    match func.kind() {
        "identifier" => {
            let name = node_text(func, src)?;
            // 1) intra-module first (shadows imports)
            if let Some(q) = by_simple.get(&name) {
                return Some(q.clone());
            }
            // 2) import map (e.g., `from logger import write_log`)
            if let Some(binding) = imports.get(&name) {
                if workspace.contains(&binding.qname_prefix) {
                    return Some(binding.qname_prefix.clone());
                }
            }
            None
        }
        "attribute" => {
            // `<object>.<attribute>` — resolve `self.X`, `Class.X`, and
            // `<imported_module>.X`.
            let object = func.child_by_field_name("object")?;
            let attr = func.child_by_field_name("attribute")?;
            let attr_name = node_text(attr, src)?;

            match object.kind() {
                "identifier" => {
                    let obj_name = node_text(object, src)?;
                    if obj_name == "self" {
                        let class = enclosing_class?;
                        let candidate = format!("{class}.{attr_name}");
                        if known.contains(candidate.as_str()) {
                            return Some(candidate);
                        }
                        return None;
                    }

                    // Intra-module class attribute: `Foo.bar` -> `mod.Foo.bar`
                    let class_qname = if module_prefix.is_empty() {
                        obj_name.clone()
                    } else {
                        format!("{module_prefix}.{obj_name}")
                    };
                    if known.contains(class_qname.as_str()) {
                        let candidate = format!("{class_qname}.{attr_name}");
                        if known.contains(candidate.as_str()) {
                            return Some(candidate);
                        }
                    }

                    // Imported module or symbol: `logger.write_log` ->
                    // `<prefix>.write_log`, validated against workspace.
                    if let Some(binding) = imports.get(&obj_name) {
                        let candidate = format!("{}.{}", binding.qname_prefix, attr_name);
                        if workspace.contains(&candidate) {
                            return Some(candidate);
                        }
                    }
                    None
                }
                "attribute" => {
                    // Chained attribute like `foo.bar.baz(...)`. Try to
                    // flatten into a dotted path and match against imports.
                    let chain = flatten_attribute(object, src)?;
                    if let Some(binding) = imports.get(&chain) {
                        let candidate = format!("{}.{}", binding.qname_prefix, attr_name);
                        if workspace.contains(&candidate) {
                            return Some(candidate);
                        }
                    }
                    None
                }
                _ => None,
            }
        }
        _ => None,
    }
}

/// Flatten a nested `attribute` node back into its dotted text form.
/// Returns `None` if any inner node isn't an identifier/attribute chain.
fn flatten_attribute(node: Node<'_>, src: &[u8]) -> Option<String> {
    match node.kind() {
        "identifier" => node_text(node, src),
        "attribute" => {
            let object = node.child_by_field_name("object")?;
            let attr = node.child_by_field_name("attribute")?;
            let head = flatten_attribute(object, src)?;
            let tail = node_text(attr, src)?;
            Some(format!("{head}.{tail}"))
        }
        _ => None,
    }
}

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

    #[test]
    fn router_prefix_resolution_fastapi_and_flask() {
        // FastAPI: APIRouter(prefix=) on the router the decorator hangs on.
        let src = r#"
router = APIRouter(prefix="/api/notifications", tags=["x"])

@router.get("/unread")
def unread(): ...
"#;
        let p = collect_router_prefixes(src);
        assert_eq!(
            p.get("router").map(String::as_str),
            Some("/api/notifications")
        );
        assert_eq!(
            route_receiver("@router.get(\"/unread\")").as_deref(),
            Some("router")
        );
        assert_eq!(
            join_route("/api/notifications", "/unread"),
            "/api/notifications/unread"
        );

        // Flask blueprint url_prefix.
        let flask = r#"bp = Blueprint("acct", __name__, url_prefix="/accounts")"#;
        assert_eq!(
            collect_router_prefixes(flask).get("bp").map(String::as_str),
            Some("/accounts")
        );

        // Same-file mount: include_router prefix precedes the router's own prefix.
        let mounted = r#"
sub = APIRouter(prefix="/items")
app.include_router(sub, prefix="/api")
"#;
        assert_eq!(
            collect_router_prefixes(mounted)
                .get("sub")
                .map(String::as_str),
            Some("/api/items")
        );
    }

    #[test]
    fn router_prefix_edge_cases() {
        // `prefix` must not be matched inside `url_prefix`, and a plain FastAPI()
        // app with no prefix yields nothing.
        assert_eq!(string_kwarg(r#"url_prefix="/z""#, "prefix"), None);
        assert_eq!(
            string_kwarg(r#"url_prefix="/z""#, "url_prefix").as_deref(),
            Some("/z")
        );
        assert!(collect_router_prefixes("app = FastAPI()").is_empty());
        // join handles missing/extra slashes and root paths.
        assert_eq!(join_route("/api", "items"), "/api/items");
        assert_eq!(join_route("/api/", "/items"), "/api/items");
        assert_eq!(join_route("/api", "/"), "/api");
        assert_eq!(join_route("", "/items"), "/items");
        // ctor boundary: APIRouter not matched inside a longer identifier.
        assert!(ctor_args("x = MyAPIRouter(prefix=\"/a\")", "APIRouter").is_none());
    }

    fn ep(contract: &str, file: &str, line: u32) -> ServiceEndpoint {
        ServiceEndpoint {
            transport: Transport::Http,
            direction: Direction::Inbound,
            contract: contract.to_string(),
            repo_id: "r".into(),
            symbol_id: "s".into(),
            qname: "q".into(),
            file: file.into(),
            line,
            confidence: 0.95,
            note: None,
        }
    }

    #[test]
    fn cross_file_aliased_mount_tree_resolves_nested_prefix() {
        // The real-world shape: nested include_router across files, where the
        // mounted router is an ALIASED import and the decorator uses a generic
        // `router`. Qname identity (module.var) bridges the alias.
        //   main:  app=FastAPI(); app.include_router(api_router, "/api")
        //   api:   api_router=APIRouter(); include_router(calculators_router, "/calculators")
        //          (calculators_router is `from calc import router as calculators_router`)
        //   calc:  router=APIRouter(); @router.get("/budget")  → /api/calculators/budget
        let files = vec![
            (
                "main.py".to_string(),
                "from api import api_router\napp = FastAPI()\napp.include_router(api_router, prefix=\"/api\")\n".to_string(),
            ),
            (
                "api.py".to_string(),
                "from calc import router as calculators_router\napi_router = APIRouter()\napi_router.include_router(calculators_router, prefix=\"/calculators\")\n".to_string(),
            ),
            (
                "calc.py".to_string(),
                "router = APIRouter()\n\n@router.get(\"/budget\")\ndef budget(): ...\n".to_string(),
            ),
        ];
        let mut eps = vec![ep(&http_contract("GET", "/budget"), "calc.py", 3)];
        resolve_python_endpoint_prefixes(&files, &mut eps);
        assert_eq!(eps[0].contract, "http:GET /api/calculators/budget");
    }

    #[test]
    fn same_router_name_distinct_modules_resolve_independently() {
        // `router` in two files → distinct qnames (a.router, b.router), each
        // resolving to its own prefix (no cross-contamination).
        let files = vec![
            (
                "a.py".to_string(),
                "router = APIRouter(prefix=\"/api/notif\")\n\n@router.get(\"/x\")\ndef x(): ...\n"
                    .to_string(),
            ),
            (
                "b.py".to_string(),
                "router = APIRouter(prefix=\"/api/inst\")\n\n@router.get(\"/y\")\ndef y(): ...\n"
                    .to_string(),
            ),
        ];
        let mut eps = vec![
            ep(&http_contract("GET", "/x"), "a.py", 3),
            ep(&http_contract("GET", "/y"), "b.py", 3),
        ];
        resolve_python_endpoint_prefixes(&files, &mut eps);
        assert_eq!(eps[0].contract, "http:GET /api/notif/x");
        assert_eq!(eps[1].contract, "http:GET /api/inst/y");
    }

    #[test]
    fn multi_mount_emits_route_under_each_prefix() {
        // api_router mounted at BOTH /api/v1 and /api → route served at both.
        let files = vec![
            (
                "main.py".to_string(),
                "from api import api_router\napp = FastAPI()\napp.include_router(api_router, prefix=\"/api/v1\")\napp.include_router(api_router, prefix=\"/api\")\n".to_string(),
            ),
            (
                "api.py".to_string(),
                "api_router = APIRouter()\n\n@api_router.get(\"/health\")\ndef health(): ...\n".to_string(),
            ),
        ];
        let mut eps = vec![ep(&http_contract("GET", "/health"), "api.py", 3)];
        resolve_python_endpoint_prefixes(&files, &mut eps);
        let contracts: std::collections::HashSet<String> =
            eps.iter().map(|e| e.contract.clone()).collect();
        assert_eq!(eps.len(), 2, "{contracts:?}");
        assert!(
            contracts.contains("http:GET /api/v1/health"),
            "{contracts:?}"
        );
        assert!(contracts.contains("http:GET /api/health"), "{contracts:?}");
    }

    #[test]
    fn module_prefix_strips_py_and_leading_dot_slash() {
        // src/ anchor — stable for PEP 517 src-layout projects
        assert_eq!(
            module_qname_prefix("src/mypackage/module.py"),
            "mypackage.module"
        );
        assert_eq!(module_qname_prefix("src/utils.py"), "utils");
        // __init__.py at root of package src/ gets package-name prefix
        assert_eq!(
            module_qname_prefix("packages/mypkg/src/__init__.py"),
            "mypkg.__init__"
        );
        assert_eq!(
            module_qname_prefix("packages/my-pkg/src/__init__.py"),
            "my_pkg.__init__"
        );
        // no src segment — full relative path (fallback)
        assert_eq!(module_qname_prefix("foo/bar.py"), "foo.bar");
        assert_eq!(module_qname_prefix("./foo/bar.py"), "foo.bar");
        assert_eq!(module_qname_prefix("bar.py"), "bar");
    }

    #[test]
    fn strip_src_prefix_variants() {
        assert_eq!(strip_src_prefix("src/pkg/mod.py"), "pkg/mod.py");
        assert_eq!(strip_src_prefix("lib/src/utils.py"), "utils.py");
        assert_eq!(strip_src_prefix("pkg/mod.py"), "pkg/mod.py");
    }

    #[test]
    fn parses_module_function_and_class() {
        let src = "def top():\n    return 1\n\nclass C:\n    def m(self):\n        return 2\n";
        let a = PythonAdapter::new();
        let syms = a.parse_symbols("x.py", src).unwrap();
        let qnames: Vec<_> = syms.iter().map(|s| s.qname.clone()).collect();
        assert!(qnames.contains(&"x.top".to_string()));
        assert!(qnames.contains(&"x.C".to_string()));
        assert!(qnames.contains(&"x.C.m".to_string()));
        let top = syms.iter().find(|s| s.qname == "x.top").unwrap();
        assert_eq!(top.kind, SymbolKind::Function);
        let m = syms.iter().find(|s| s.qname == "x.C.m").unwrap();
        assert_eq!(m.kind, SymbolKind::Method);
    }

    #[test]
    fn infers_fs_read_and_write_from_open() {
        let body = "def f():\n    with open('/tmp/a.txt', 'w') as f:\n        f.write('hi')\n";
        let effects = infer_effects_from_body(body);
        let cats: Vec<_> = effects.iter().map(|e| e.effect.clone()).collect();
        assert!(cats.contains(&EffectCategory::IoFsRead));
        assert!(cats.contains(&EffectCategory::IoFsWrite));
    }

    #[test]
    fn empty_when_no_patterns() {
        let body = "def f(x):\n    return x + 1\n";
        assert!(infer_effects_from_body(body).is_empty());
    }

    // ----- Plan L t-002: comment + string-literal false-positive guards -----

    #[test]
    fn comment_mentioning_open_does_not_infer_fs_effects() {
        // `open(` appears only in a comment; we must NOT infer fs.read.
        let body = "def f(x):\n    # consider open('/tmp/x') for cache\n    return x\n";
        let effects = infer_effects_from_body(body);
        let cats: Vec<_> = effects.iter().map(|e| e.effect.clone()).collect();
        assert!(
            !cats.contains(&EffectCategory::IoFsRead),
            "open() in a comment must not infer IoFsRead; got {cats:?}"
        );
    }

    #[test]
    fn string_literal_mentioning_open_does_not_infer_fs_effects() {
        // `open(` only inside a string literal — no real call.
        let body = "def f():\n    msg = 'use open(path) to load'\n    return msg\n";
        let effects = infer_effects_from_body(body);
        assert!(
            effects.is_empty(),
            "open() inside a string literal must not infer any effect; got {effects:?}"
        );
    }

    #[test]
    fn triple_string_docstring_mentioning_requests_does_not_infer_net() {
        // A docstring describing what `requests.get` would do — must
        // not infer IoNetOut.
        let body = r#"def f():
    """Pretend we call requests.get('https://example.com') here.

    But we don't actually.
    """
    return 42
"#;
        let effects = infer_effects_from_body(body);
        let cats: Vec<_> = effects.iter().map(|e| e.effect.clone()).collect();
        assert!(
            !cats.contains(&EffectCategory::IoNetOut),
            "requests.* in a docstring must not infer IoNetOut; got {cats:?}"
        );
    }

    #[test]
    fn real_requests_call_infers_net_out() {
        // The positive counterpart to the docstring test above. A live
        // `requests.get(url)` MUST infer IoNetOut. Regression guard for the
        // dead-code bug where `find_calls(scan, "requests.")` returned nothing
        // because the prefix didn't end in `(` — found by the cross-language
        // conformance matrix (effects column was blank for Python).
        for body in [
            "def f():\n    return requests.get('https://api.svc/x')\n",
            "def f():\n    return httpx.post('https://api.svc/x', json={})\n",
            "def f():\n    return requests.request('POST', 'https://api.svc/x')\n",
        ] {
            let cats: Vec<_> = infer_effects_from_body(body)
                .iter()
                .map(|e| e.effect.clone())
                .collect();
            assert!(
                cats.contains(&EffectCategory::IoNetOut),
                "expected IoNetOut for `{body}`; got {cats:?}"
            );
        }
    }

    #[test]
    fn real_open_still_fires_when_comment_also_mentions_it() {
        // The masking must not suppress a real call site that sits
        // next to a comment containing the same pattern.
        let body = "def f():\n    # open('/tmp/a') would also work\n    open('/tmp/b')\n";
        let effects = infer_effects_from_body(body);
        let cats: Vec<_> = effects.iter().map(|e| e.effect.clone()).collect();
        assert!(
            cats.contains(&EffectCategory::IoFsRead),
            "real open() must still infer IoFsRead even when a comment also mentions it; got {cats:?}"
        );
    }

    #[test]
    fn raise_inside_string_literal_does_not_infer_throw() {
        let body = "def f():\n    msg = 'do not raise here'\n    return msg\n";
        let effects = infer_effects_from_body(body);
        let cats: Vec<_> = effects.iter().map(|e| e.effect.clone()).collect();
        assert!(
            !cats.contains(&EffectCategory::Throw),
            "raise inside a string literal must not infer Throw; got {cats:?}"
        );
    }

    #[test]
    fn mask_preserves_byte_length_and_line_count() {
        // The downstream offset-based slicing relies on masked + body
        // being the same byte length AND splitting into the same lines.
        let body = "x = 'open(\"a\")'  # open(\"b\")\ny = 1\n";
        let masked = mask_comments_and_literals(body);
        assert_eq!(masked.len(), body.len(), "mask must preserve byte length");
        assert_eq!(
            masked.lines().count(),
            body.lines().count(),
            "mask must preserve line count"
        );
        // Spot check: `open(` inside the literal AND the comment must
        // be erased from the masked view.
        assert!(
            !masked.contains("open("),
            "masked source must not contain `open(` from literal or comment"
        );
    }

    #[test]
    fn mask_leaves_identifier_chars_alone() {
        // `request_open` is an identifier, not a string prefix —
        // masking must not eat the `r` thinking it's `r"…"`.
        let body = "request_open = 1\n";
        let masked = mask_comments_and_literals(body);
        assert_eq!(
            masked, body,
            "no comments/literals here; masked must equal original"
        );
    }

    #[test]
    fn mask_handles_raw_and_byte_string_prefixes() {
        let body = "x = r\"open('/tmp/a')\"\ny = b'open(\"b\")'\nz = rb\"open(\"c\")\"\n";
        let effects = infer_effects_from_body(body);
        assert!(
            effects.is_empty(),
            "raw/byte/raw-byte literals must mask their contents; got {effects:?}"
        );
    }

    /// Build a WorkspaceSymbols with just a set of qnames (kinds defaulted
    /// to Function). Tests don't currently exercise the kinds map.
    fn workspace_with(qnames: &[&str]) -> WorkspaceSymbols {
        let mut ws = WorkspaceSymbols::default();
        for q in qnames {
            ws.qnames.insert((*q).to_string());
            ws.kinds.insert((*q).to_string(), SymbolKind::Function);
        }
        ws
    }

    #[test]
    fn extracts_intra_module_call_edges() {
        let src = r#"
def helper(x):
    return x

def caller():
    return helper(1)

class C:
    def __init__(self):
        self.x = helper(2)

    def m(self):
        return self.__init__()
"#;
        let a = PythonAdapter::new();
        let syms = a.parse_symbols("m.py", src).unwrap();
        let ws = workspace_with(&["m.helper", "m.caller", "m.C", "m.C.__init__", "m.C.m"]);
        let edges = a.extract_call_edges("m.py", src, &syms, &ws);
        let pairs: Vec<(String, String)> = edges
            .iter()
            .map(|e| (e.caller_qname.clone(), e.callee_qname.clone()))
            .collect();
        assert!(
            pairs.contains(&("m.caller".to_string(), "m.helper".to_string())),
            "missing caller -> helper edge; got {pairs:?}",
        );
        assert!(
            pairs.contains(&("m.C.__init__".to_string(), "m.helper".to_string())),
            "missing C.__init__ -> helper edge; got {pairs:?}",
        );
        assert!(
            pairs.contains(&("m.C.m".to_string(), "m.C.__init__".to_string())),
            "missing C.m -> C.__init__ edge; got {pairs:?}",
        );
    }

    #[test]
    fn extracts_cross_module_edges_via_from_import() {
        // `from logger import write_log` — `write_log(...)` should resolve
        // to `logger.write_log`.
        let src = r#"
from logger import write_log

def foo():
    write_log("/tmp/x", "hi")
"#;
        let a = PythonAdapter::new();
        let syms = a.parse_symbols("caller.py", src).unwrap();
        let ws = workspace_with(&["logger.write_log", "caller.foo"]);
        let edges = a.extract_call_edges("caller.py", src, &syms, &ws);
        let pairs: Vec<(String, String)> = edges
            .iter()
            .map(|e| (e.caller_qname.clone(), e.callee_qname.clone()))
            .collect();
        assert!(
            pairs.contains(&("caller.foo".to_string(), "logger.write_log".to_string())),
            "missing foo -> logger.write_log edge; got {pairs:?}",
        );
    }

    #[test]
    fn extracts_cross_module_edges_via_module_import() {
        // `import logger` — `logger.write_log(...)` should resolve.
        let src = r#"
import logger

def foo():
    logger.write_log("/tmp/x", "hi")
"#;
        let a = PythonAdapter::new();
        let syms = a.parse_symbols("caller.py", src).unwrap();
        let ws = workspace_with(&["logger.write_log", "caller.foo"]);
        let edges = a.extract_call_edges("caller.py", src, &syms, &ws);
        let pairs: Vec<(String, String)> = edges
            .iter()
            .map(|e| (e.caller_qname.clone(), e.callee_qname.clone()))
            .collect();
        assert!(
            pairs.contains(&("caller.foo".to_string(), "logger.write_log".to_string())),
            "missing foo -> logger.write_log edge; got {pairs:?}",
        );
    }

    #[test]
    fn drops_unknown_imports() {
        // Workspace doesn't know about `stdlib_mod.thing` — no edge emitted.
        let src = r#"
import stdlib_mod

def foo():
    stdlib_mod.thing()
"#;
        let a = PythonAdapter::new();
        let syms = a.parse_symbols("caller.py", src).unwrap();
        let ws = workspace_with(&["caller.foo"]);
        let edges = a.extract_call_edges("caller.py", src, &syms, &ws);
        let pairs: Vec<(String, String)> = edges
            .iter()
            .map(|e| (e.caller_qname.clone(), e.callee_qname.clone()))
            .collect();
        assert!(
            pairs.is_empty(),
            "expected no edges for unknown imports; got {pairs:?}",
        );
    }

    #[test]
    fn import_alias_and_from_import_with_alias() {
        let src = r#"
import logger as lg
from greetings import hello as h

def foo():
    lg.write_log("/tmp/x", "hi")
    h("world")
"#;
        let a = PythonAdapter::new();
        let syms = a.parse_symbols("caller.py", src).unwrap();
        let ws = workspace_with(&["logger.write_log", "greetings.hello", "caller.foo"]);
        let edges = a.extract_call_edges("caller.py", src, &syms, &ws);
        let pairs: Vec<(String, String)> = edges
            .iter()
            .map(|e| (e.caller_qname.clone(), e.callee_qname.clone()))
            .collect();
        assert!(
            pairs.contains(&("caller.foo".to_string(), "logger.write_log".to_string())),
            "missing lg.write_log edge; got {pairs:?}",
        );
        assert!(
            pairs.contains(&("caller.foo".to_string(), "greetings.hello".to_string())),
            "missing h() edge; got {pairs:?}",
        );
    }

    #[test]
    fn local_definition_shadows_import() {
        // `helper` defined locally should win over `from x import helper`.
        let src = r#"
from other import helper

def helper(x):
    return x

def foo():
    helper(1)
"#;
        let a = PythonAdapter::new();
        let syms = a.parse_symbols("m.py", src).unwrap();
        let ws = workspace_with(&["other.helper", "m.helper", "m.foo"]);
        let edges = a.extract_call_edges("m.py", src, &syms, &ws);
        let pairs: Vec<(String, String)> = edges
            .iter()
            .map(|e| (e.caller_qname.clone(), e.callee_qname.clone()))
            .collect();
        assert!(
            pairs.contains(&("m.foo".to_string(), "m.helper".to_string())),
            "expected local helper to shadow import; got {pairs:?}",
        );
        assert!(
            !pairs.contains(&("m.foo".to_string(), "other.helper".to_string())),
            "expected imported helper to be shadowed; got {pairs:?}",
        );
    }

    #[test]
    fn default_extract_call_edges_returns_empty_for_unrelated_adapter() {
        // Sanity: ensure the trait method exists and the default returns empty.
        // This pins the behavior so callers can rely on it.
        struct Dummy;
        impl LanguageAdapter for Dummy {
            fn language(&self) -> &str {
                "dummy"
            }
            fn parse_symbols(&self, _f: &str, _s: &str) -> Result<Vec<ParsedSymbol>> {
                Ok(Vec::new())
            }
            fn infer_effects(&self, _s: &str, _p: &ParsedSymbol) -> Vec<Effect> {
                Vec::new()
            }
        }
        let d = Dummy;
        let ws = WorkspaceSymbols::default();
        assert!(d.extract_call_edges("x", "", &[], &ws).is_empty());
    }

    // -- Plan D t-004: relative-import resolver -----------------------------

    #[test]
    fn relative_dot_resolves_to_current_package() {
        // crucible/agents/litellm_agent.py → file qname = crucible.agents.litellm_agent
        // `from . import base` → "crucible.agents.base"
        let r = super::resolve_relative_import("crucible.agents.litellm_agent", ".").unwrap();
        assert_eq!(r, "crucible.agents");
    }

    #[test]
    fn relative_dot_with_suffix_appends_module() {
        let r = super::resolve_relative_import("crucible.agents.litellm_agent", ".base").unwrap();
        assert_eq!(r, "crucible.agents.base");
    }

    #[test]
    fn relative_double_dot_goes_up_one_more() {
        // `from ..util import x` from crucible/agents/litellm_agent.py
        // current package = crucible.agents; parent = crucible; "..util" → crucible.util
        let r = super::resolve_relative_import("crucible.agents.litellm_agent", "..util").unwrap();
        assert_eq!(r, "crucible.util");
    }

    #[test]
    fn relative_from_init_resolves_against_package() {
        // crucible/agents/__init__.py has module_prefix = crucible.agents.__init__
        // `from . import base` → drop 1 segment → crucible.agents; +"base" → crucible.agents.base
        let r = super::resolve_relative_import("crucible.agents.__init__", ".base").unwrap();
        assert_eq!(r, "crucible.agents.base");
    }

    #[test]
    fn relative_escaping_workspace_returns_none() {
        // Two dots when we only have one segment to drop.
        assert!(super::resolve_relative_import("crucible", "..foo").is_none());
    }

    // ---- Plan L t-006: unresolved-call reporter -----------------------

    #[test]
    fn unresolved_calls_reports_third_party_call() {
        // A call to a name that isn't in the workspace and isn't on
        // the stdlib allowlist should surface.
        use agentstatedeveloper_core::WorkspaceSymbols;
        let src = "import requests\n\ndef fetch(url):\n    return requests.get(url)\n";
        let parsed = vec![ParsedSymbol {
            qname: "app.client.fetch".into(),
            kind: SymbolKind::Function,
            start_line: 3,
            start_col: 0,
            end_line: 4,
            end_col: 30,
            signature: Some("def fetch(url)".into()),
            body: src.into(),
            doc: None,
        }];
        let mut ws = WorkspaceSymbols::default();
        ws.qnames.insert("app.client.fetch".into());
        ws.kinds
            .insert("app.client.fetch".into(), SymbolKind::Function);
        ws.build_suffix_index();

        let hits = report_unresolved_calls_in_python("app/client.py", src, &parsed, &ws);
        assert!(
            hits.iter().any(|h| h.callee_text.contains("requests")),
            "expected unresolved hint for requests.get; got {hits:?}"
        );
    }

    #[test]
    fn unresolved_calls_skips_stdlib_allowlist() {
        // print() / len() / range() must NOT show up as unresolved —
        // they're on the allowlist.
        use agentstatedeveloper_core::WorkspaceSymbols;
        let src = "def show(items):\n    print(len(items))\n    for i in range(3): pass\n";
        let parsed = vec![ParsedSymbol {
            qname: "app.show.show".into(),
            kind: SymbolKind::Function,
            start_line: 1,
            start_col: 0,
            end_line: 3,
            end_col: 30,
            signature: Some("def show(items)".into()),
            body: src.into(),
            doc: None,
        }];
        let mut ws = WorkspaceSymbols::default();
        ws.qnames.insert("app.show.show".into());
        ws.kinds
            .insert("app.show.show".into(), SymbolKind::Function);
        ws.build_suffix_index();

        let hits = report_unresolved_calls_in_python("app/show.py", src, &parsed, &ws);
        assert!(
            hits.is_empty(),
            "stdlib allowlist calls must not be reported; got {hits:?}"
        );
    }

    #[test]
    fn unresolved_calls_skips_resolved_internal_calls() {
        // A call to an internal symbol that resolves must NOT appear
        // in the unresolved list.
        use agentstatedeveloper_core::WorkspaceSymbols;
        let src = "def helper(): return 1\n\ndef use(): return helper()\n";
        let parsed = vec![
            ParsedSymbol {
                qname: "app.lib.helper".into(),
                kind: SymbolKind::Function,
                start_line: 1,
                start_col: 0,
                end_line: 1,
                end_col: 22,
                signature: Some("def helper()".into()),
                body: src.into(),
                doc: None,
            },
            ParsedSymbol {
                qname: "app.lib.use".into(),
                kind: SymbolKind::Function,
                start_line: 3,
                start_col: 0,
                end_line: 3,
                end_col: 25,
                signature: Some("def use()".into()),
                body: src.into(),
                doc: None,
            },
        ];
        let mut ws = WorkspaceSymbols::default();
        ws.qnames.insert("app.lib.helper".into());
        ws.kinds
            .insert("app.lib.helper".into(), SymbolKind::Function);
        ws.qnames.insert("app.lib.use".into());
        ws.kinds.insert("app.lib.use".into(), SymbolKind::Function);
        ws.build_suffix_index();

        let hits = report_unresolved_calls_in_python("app/lib.py", src, &parsed, &ws);
        assert!(
            !hits.iter().any(|h| h.callee_text == "helper"),
            "internal resolved call must not appear in unresolved list; got {hits:?}"
        );
    }

    // ---- Plan L t-005: dynamic-dispatch scanner -----------------------

    #[test]
    fn detects_getattr_call_pattern() {
        let src = "def dispatch(obj, name):\n    return getattr(obj, name)(42)\n";
        let hints = scan_dynamic_dispatch_in_python("app/dispatch.py", src);
        assert_eq!(hints.len(), 1, "expected 1 getattr hint; got {hints:?}");
        assert_eq!(hints[0].pattern, "getattr");
        assert_eq!(hints[0].line, 2);
        assert!(hints[0].snippet.contains("getattr(obj, name)(42)"));
    }

    #[test]
    fn getattr_without_trailing_call_is_not_flagged() {
        // A bare attribute read — not a dispatch — should NOT warn.
        let src = "def read(obj, name):\n    return getattr(obj, name, None)\n";
        let hints = scan_dynamic_dispatch_in_python("app/read.py", src);
        assert!(
            hints.is_empty(),
            "bare getattr (no trailing call) must not be flagged; got {hints:?}"
        );
    }

    #[test]
    fn detects_getattr_with_string_arg_then_call() {
        let src = "def go(obj):\n    return getattr(obj, 'method')(1, 2)\n";
        let hints = scan_dynamic_dispatch_in_python("app/go.py", src);
        assert_eq!(hints.len(), 1);
        assert_eq!(hints[0].pattern, "getattr");
    }

    #[test]
    fn detects_dunder_getattr_method_definition() {
        let src =
            "class Proxy:\n    def __getattr__(self, name):\n        return self._lookup(name)\n";
        let hints = scan_dynamic_dispatch_in_python("app/proxy.py", src);
        assert_eq!(hints.len(), 1);
        assert_eq!(hints[0].pattern, "__getattr__");
        assert_eq!(hints[0].line, 2);
    }

    #[test]
    fn detects_dunder_getattribute_method_definition() {
        let src = "class Strict:\n    def __getattribute__(self, name):\n        return super().__getattribute__(name)\n";
        let hints = scan_dynamic_dispatch_in_python("app/strict.py", src);
        assert_eq!(hints.len(), 1);
        assert_eq!(hints[0].pattern, "__getattr__");
    }

    #[test]
    fn getattr_inside_comment_or_string_is_masked() {
        // The scanner runs on masked source — a getattr in a comment
        // or string literal must NOT produce a warning.
        let src = "def f(obj):\n    # consider getattr(obj, 'x')(1) here\n    msg = 'use getattr(obj, x)(args) at runtime'\n    return msg\n";
        let hints = scan_dynamic_dispatch_in_python("app/f.py", src);
        assert!(
            hints.is_empty(),
            "getattr inside comment/string must not be flagged; got {hints:?}"
        );
    }

    // ---- Plan L t-004: nested-import resolution -----------------------

    #[test]
    fn extract_call_edges_resolves_function_body_import() {
        // `def f(): import requests; requests.get(...)` — the import
        // lives inside the function body, not at module scope. The
        // walker must descend into the body and pick it up.
        use crate::PythonAdapter;
        use agentstatedeveloper_core::{
            LanguageAdapter, ParsedSymbol, SymbolKind, WorkspaceSymbols,
        };

        let adapter = PythonAdapter::new();
        let src = "def f():\n    from pkg.util import helper\n    return helper()\n";

        let syms = vec![ParsedSymbol {
            qname: "app.main.f".into(),
            kind: SymbolKind::Function,
            start_line: 1,
            start_col: 0,
            end_line: 3,
            end_col: 22,
            signature: Some("def f()".into()),
            body: src.into(),
            doc: None,
        }];

        let mut ws = WorkspaceSymbols::default();
        ws.qnames.insert("pkg.util.helper".into());
        ws.kinds
            .insert("pkg.util.helper".into(), SymbolKind::Function);
        ws.qnames.insert("app.main.f".into());
        ws.kinds.insert("app.main.f".into(), SymbolKind::Function);
        ws.build_suffix_index();

        let edges = adapter.extract_call_edges("app/main.py", src, &syms, &ws);
        assert!(
            edges.iter().any(|e| e.callee_qname == "pkg.util.helper"),
            "function-body import must produce cross-module edge; got {edges:?}"
        );
    }

    #[test]
    fn extract_call_edges_resolves_if_typechecking_import() {
        // Imports inside `if TYPE_CHECKING:` blocks should also be
        // collected — the walker doesn't prune on conditional nodes.
        use crate::PythonAdapter;
        use agentstatedeveloper_core::{
            LanguageAdapter, ParsedSymbol, SymbolKind, WorkspaceSymbols,
        };

        let adapter = PythonAdapter::new();
        let src = "from typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n    from pkg.api import Client\n\ndef use():\n    return Client()\n";

        let syms = vec![ParsedSymbol {
            qname: "app.main.use".into(),
            kind: SymbolKind::Function,
            start_line: 6,
            start_col: 0,
            end_line: 7,
            end_col: 20,
            signature: Some("def use()".into()),
            body: src.into(),
            doc: None,
        }];

        let mut ws = WorkspaceSymbols::default();
        ws.qnames.insert("pkg.api.Client".into());
        ws.kinds.insert("pkg.api.Client".into(), SymbolKind::Class);
        ws.qnames.insert("app.main.use".into());
        ws.kinds.insert("app.main.use".into(), SymbolKind::Function);
        ws.build_suffix_index();

        let edges = adapter.extract_call_edges("app/main.py", src, &syms, &ws);
        assert!(
            edges.iter().any(|e| e.callee_qname == "pkg.api.Client"),
            "if TYPE_CHECKING import must resolve; got {edges:?}"
        );
    }

    #[test]
    fn extract_call_edges_resolves_try_except_import() {
        // `try: import cPickle as pickle / except: import pickle` —
        // the try-block import lives inside a `try_statement`. Walker
        // must descend.
        use crate::PythonAdapter;
        use agentstatedeveloper_core::{
            LanguageAdapter, ParsedSymbol, SymbolKind, WorkspaceSymbols,
        };

        let adapter = PythonAdapter::new();
        let src = "try:\n    from pkg.fast import loader\nexcept ImportError:\n    from pkg.slow import loader\n\ndef boot():\n    return loader()\n";

        let syms = vec![ParsedSymbol {
            qname: "app.main.boot".into(),
            kind: SymbolKind::Function,
            start_line: 6,
            start_col: 0,
            end_line: 7,
            end_col: 20,
            signature: Some("def boot()".into()),
            body: src.into(),
            doc: None,
        }];

        let mut ws = WorkspaceSymbols::default();
        ws.qnames.insert("pkg.fast.loader".into());
        ws.kinds
            .insert("pkg.fast.loader".into(), SymbolKind::Function);
        ws.qnames.insert("pkg.slow.loader".into());
        ws.kinds
            .insert("pkg.slow.loader".into(), SymbolKind::Function);
        ws.qnames.insert("app.main.boot".into());
        ws.kinds
            .insert("app.main.boot".into(), SymbolKind::Function);
        ws.build_suffix_index();

        let edges = adapter.extract_call_edges("app/main.py", src, &syms, &ws);
        // Either branch's resolution is acceptable — both are real
        // bindings in the same module. We just need at least one.
        let resolved = edges
            .iter()
            .any(|e| e.callee_qname == "pkg.fast.loader" || e.callee_qname == "pkg.slow.loader");
        assert!(
            resolved,
            "try/except import must resolve to one of the branches; got {edges:?}"
        );
    }

    #[test]
    fn module_scope_imports_still_resolve_after_nested_walker() {
        // Regression guard: the recursive walker must not break the
        // already-working module-scope case.
        use crate::PythonAdapter;
        use agentstatedeveloper_core::{
            LanguageAdapter, ParsedSymbol, SymbolKind, WorkspaceSymbols,
        };

        let adapter = PythonAdapter::new();
        let src = "from pkg.util import helper\n\ndef f():\n    return helper()\n";

        let syms = vec![ParsedSymbol {
            qname: "app.main.f".into(),
            kind: SymbolKind::Function,
            start_line: 3,
            start_col: 0,
            end_line: 4,
            end_col: 22,
            signature: Some("def f()".into()),
            body: src.into(),
            doc: None,
        }];

        let mut ws = WorkspaceSymbols::default();
        ws.qnames.insert("pkg.util.helper".into());
        ws.kinds
            .insert("pkg.util.helper".into(), SymbolKind::Function);
        ws.qnames.insert("app.main.f".into());
        ws.kinds.insert("app.main.f".into(), SymbolKind::Function);
        ws.build_suffix_index();

        let edges = adapter.extract_call_edges("app/main.py", src, &syms, &ws);
        assert!(
            edges.iter().any(|e| e.callee_qname == "pkg.util.helper"),
            "module-scope import must still resolve; got {edges:?}"
        );
    }

    #[test]
    fn extract_call_edges_resolves_double_dot_relative_import() {
        // Plan L t-003 acceptance gate: the double-dot case
        // (`from ..pkg import x`) was tested in isolation
        // (`relative_double_dot_goes_up_one_more`) but never end-to-end.
        // This locks in the full pipeline behavior so future refactors
        // can't silently regress on the two-dot case.
        use crate::PythonAdapter;
        use agentstatedeveloper_core::{
            LanguageAdapter, ParsedSymbol, SymbolKind, WorkspaceSymbols,
        };

        let adapter = PythonAdapter::new();
        // crucible.agents.litellm_agent imports from crucible.util
        // (two dots up: agents → crucible, then .util).
        let caller_src = "from ..util import helper\n\ndef act():\n    return helper()\n";

        let caller_syms = vec![ParsedSymbol {
            qname: "crucible.agents.litellm_agent.act".into(),
            kind: SymbolKind::Function,
            start_line: 3,
            start_col: 0,
            end_line: 4,
            end_col: 22,
            signature: Some("def act()".into()),
            body: caller_src.into(),
            doc: None,
        }];

        let mut workspace = WorkspaceSymbols::default();
        workspace.qnames.insert("crucible.util.helper".into());
        workspace
            .kinds
            .insert("crucible.util.helper".into(), SymbolKind::Function);
        workspace
            .qnames
            .insert("crucible.agents.litellm_agent.act".into());
        workspace.kinds.insert(
            "crucible.agents.litellm_agent.act".into(),
            SymbolKind::Function,
        );
        workspace.build_suffix_index();

        let edges = adapter.extract_call_edges(
            "crucible/agents/litellm_agent.py",
            caller_src,
            &caller_syms,
            &workspace,
        );

        assert!(
            edges
                .iter()
                .any(|e| e.callee_qname == "crucible.util.helper"),
            "expected double-dot relative import to produce cross-module edge to crucible.util.helper; got {edges:?}"
        );
    }

    #[test]
    fn extract_call_edges_resolves_relative_import_to_cross_module() {
        // End-to-end: a relative import + a call should produce a cross-module
        // CallEdge. This is the Crucible reproducer collapsed to a unit test.
        use crate::PythonAdapter;
        use agentstatedeveloper_core::{
            LanguageAdapter, ParsedSymbol, SymbolKind, WorkspaceSymbols,
        };

        let adapter = PythonAdapter::new();
        let caller_src =
            "from .base import make_decision\n\ndef act():\n    return make_decision()\n";

        let caller_syms = vec![ParsedSymbol {
            qname: "crucible.agents.litellm_agent.act".into(),
            kind: SymbolKind::Function,
            start_line: 3,
            start_col: 0,
            end_line: 4,
            end_col: 27,
            signature: Some("def act()".into()),
            body: caller_src.into(),
            doc: None,
        }];

        let mut workspace = WorkspaceSymbols::default();
        workspace
            .qnames
            .insert("crucible.agents.base.make_decision".into());
        workspace.kinds.insert(
            "crucible.agents.base.make_decision".into(),
            SymbolKind::Function,
        );
        workspace
            .qnames
            .insert("crucible.agents.litellm_agent.act".into());
        workspace.kinds.insert(
            "crucible.agents.litellm_agent.act".into(),
            SymbolKind::Function,
        );
        workspace.build_suffix_index();

        let edges = adapter.extract_call_edges(
            "crucible/agents/litellm_agent.py",
            caller_src,
            &caller_syms,
            &workspace,
        );

        assert!(
            edges
                .iter()
                .any(|e| e.callee_qname == "crucible.agents.base.make_decision"),
            "expected cross-module edge to crucible.agents.base.make_decision; got {edges:?}"
        );
    }
}

#[cfg(test)]
mod service_endpoint_tests {
    use super::*;
    use agentstatedeveloper_core::adapter::LanguageAdapter;

    fn detect(src: &str) -> Vec<DetectedEndpoint> {
        let a = PythonAdapter;
        let symbols = a.parse_symbols("app.py", src).unwrap();
        a.infer_service_endpoints("app.py", src, &symbols)
    }

    fn inbound(eps: &[DetectedEndpoint]) -> Vec<&DetectedEndpoint> {
        eps.iter()
            .filter(|e| e.direction == Direction::Inbound)
            .collect()
    }
    fn outbound(eps: &[DetectedEndpoint]) -> Vec<&DetectedEndpoint> {
        eps.iter()
            .filter(|e| e.direction == Direction::Outbound)
            .collect()
    }

    #[test]
    fn fastapi_decorator_route_is_inbound() {
        let src = "@app.get(\"/charge\")\ndef charge():\n    return 1\n";
        let eps = detect(src);
        let inb = inbound(&eps);
        assert_eq!(inb.len(), 1, "{eps:?}");
        assert_eq!(inb[0].contract, "http:GET /charge");
        assert!(
            inb[0].owner_qname.ends_with("charge"),
            "owner: {}",
            inb[0].owner_qname
        );
        assert!(inb[0].confidence > 0.9);
    }

    #[test]
    fn flask_route_with_methods_emits_one_per_method() {
        let src = "@app.route(\"/items\", methods=[\"GET\", \"POST\"])\ndef items():\n    pass\n";
        let eps = detect(src);
        let mut got: Vec<String> = inbound(&eps).iter().map(|e| e.contract.clone()).collect();
        got.sort();
        assert_eq!(
            got,
            vec![
                "http:GET /items".to_string(),
                "http:POST /items".to_string()
            ]
        );
    }

    #[test]
    fn flask_route_defaults_to_get() {
        let src = "@app.route(\"/ping\")\ndef ping():\n    pass\n";
        let eps = detect(src);
        let inb = inbound(&eps);
        assert_eq!(inb.len(), 1);
        assert_eq!(inb[0].contract, "http:GET /ping");
    }

    #[test]
    fn requests_client_call_is_outbound() {
        let src = "def pay():\n    requests.post(\"https://payments.svc/charge\", json=x)\n";
        let eps = detect(src);
        let out = outbound(&eps);
        assert_eq!(out.len(), 1, "{eps:?}");
        assert_eq!(out[0].contract, "http:POST /charge");
        assert!(
            out[0].owner_qname.ends_with("pay"),
            "owner: {}",
            out[0].owner_qname
        );
    }

    #[test]
    fn requests_request_method_first_arg() {
        let src = "def f():\n    httpx.request(\"DELETE\", \"https://api/things/{id}\")\n";
        let eps = detect(src);
        let out = outbound(&eps);
        assert_eq!(out.len(), 1);
        assert_eq!(out[0].contract, "http:DELETE /things/{}");
    }

    #[test]
    fn non_literal_urls_are_skipped() {
        // A variable and an f-string can't form a usable contract.
        let src = "def f():\n    requests.get(url)\n    requests.get(f\"/u/{i}\")\n";
        let eps = detect(src);
        assert!(outbound(&eps).is_empty(), "{eps:?}");
    }

    #[test]
    fn import_line_is_not_a_client_call() {
        let src = "import requests\n\ndef f():\n    return 1\n";
        assert!(detect(src).is_empty());
    }

    #[test]
    fn client_and_server_contracts_match_for_matching_endpoint() {
        // The whole point: an outbound client contract equals the inbound server
        // contract for the same logical endpoint, so match_edges would link them.
        let server = detect("@app.get(\"/users/{id}\")\ndef get_user(id):\n    pass\n");
        let client = detect("def fetch():\n    requests.get(\"https://users.svc/users/:id\")\n");
        assert_eq!(inbound(&server)[0].contract, outbound(&client)[0].contract);
        assert_eq!(inbound(&server)[0].contract, "http:GET /users/{}");
    }
}

#[cfg(test)]
mod dataflow_tests {
    use super::*;
    use agentstatedeveloper_core::adapter::{LanguageAdapter, WorkspaceSymbols};

    fn detect(src: &str) -> Vec<DetectedDataFlow> {
        let a = PythonAdapter;
        let symbols = a.parse_symbols("m.py", src).unwrap();
        a.extract_dataflow("m.py", src, &symbols, &WorkspaceSymbols::default())
    }

    #[test]
    fn same_file_call_maps_positional_args() {
        let src = "def helper(a, b):\n    return a\n\ndef caller():\n    helper(x, y)\n";
        let df = detect(src);
        assert_eq!(df.len(), 2, "{df:?}");
        assert!(df.iter().all(|d| d.callee_qname.ends_with("helper")));
        assert!(df.iter().all(|d| d.caller_qname.ends_with("caller")));
        let args: Vec<(usize, String)> = df.iter().map(|d| (d.arg_index, d.arg.clone())).collect();
        assert!(args.contains(&(0, "x".to_string())));
        assert!(args.contains(&(1, "y".to_string())));
    }

    #[test]
    fn method_calls_are_skipped() {
        let src = "def caller():\n    obj.helper(x)\n";
        assert!(detect(src).is_empty(), "{:?}", detect(src));
    }

    #[test]
    fn unknown_or_cross_file_callee_skipped() {
        // helper isn't defined in this file → not resolved (cross-file is a follow-up).
        let src = "def caller():\n    helper(x)\n";
        assert!(detect(src).is_empty());
    }

    #[test]
    fn non_identifier_args_are_skipped() {
        let src = "def helper(a):\n    pass\n\ndef caller():\n    helper(\"lit\")\n    helper(g(x))\n    helper(a + b)\n";
        assert!(detect(src).is_empty(), "{:?}", detect(src));
    }

    #[test]
    fn ambiguous_callee_name_skipped() {
        let src = "def helper(a):\n    pass\n\ndef helper(b):\n    pass\n\ndef caller():\n    helper(x)\n";
        assert!(detect(src).is_empty(), "{:?}", detect(src));
    }
}

#[cfg(test)]
mod pubsub_tests {
    use super::*;
    use agentstatedeveloper_core::adapter::LanguageAdapter;

    fn detect(src: &str) -> Vec<DetectedEndpoint> {
        let a = PythonAdapter;
        let symbols = a.parse_symbols("tasks.py", src).unwrap();
        a.infer_service_endpoints("tasks.py", src, &symbols)
    }
    fn ps(eps: &[DetectedEndpoint], dir: Direction) -> Vec<&DetectedEndpoint> {
        eps.iter()
            .filter(|e| e.transport == Transport::PubSub && e.direction == dir)
            .collect()
    }

    #[test]
    fn shared_task_is_a_listener() {
        let eps = detect("@shared_task\ndef process_order(o):\n    return o\n");
        let inb = ps(&eps, Direction::Inbound);
        assert_eq!(inb.len(), 1, "{eps:?}");
        assert_eq!(inb[0].contract, "topic:process_order");
    }

    #[test]
    fn delay_call_is_an_emit() {
        let eps = detect("def caller():\n    process_order.delay(payload)\n");
        let outb = ps(&eps, Direction::Outbound);
        assert_eq!(outb.len(), 1);
        assert_eq!(outb[0].contract, "topic:process_order");
    }

    #[test]
    fn listener_and_emit_share_one_contract() {
        let src = "@app.task(bind=True)\ndef send_email(addr):\n    pass\n\ndef trigger():\n    send_email.apply_async((a,))\n";
        let eps = detect(src);
        assert_eq!(
            ps(&eps, Direction::Inbound)[0].contract,
            ps(&eps, Direction::Outbound)[0].contract
        );
        assert_eq!(ps(&eps, Direction::Inbound)[0].contract, "topic:send_email");
    }

    #[test]
    fn non_celery_decorator_is_not_a_listener() {
        // @property / @app.get(...) must not register as a pub-sub listener.
        assert!(
            ps(
                &detect("@property\ndef value(self):\n    return 1\n"),
                Direction::Inbound
            )
            .is_empty()
        );
        let http = detect("@app.get(\"/x\")\ndef h():\n    pass\n");
        assert!(ps(&http, Direction::Inbound).is_empty());
    }
}