repotoire 0.8.2

//! AST-driven extraction of [`super::predict::Evidence`] for Python
//! XML-parser call sites.
//!
//! # Why a separate module
//!
//! The scorer in [`super::predict`] takes plain data
//! ([`super::predict::Evidence`]) so it can be unit-tested without an
//! AST. This module's job is to populate that struct from a
//! `tree_sitter::Node` for a Python `call` expression that names an
//! XML parser API.
//!
//! Splitting the two halves matches Phase 2a/2b/2c/2d's
//! `evidence.rs` split.
//!
//! # What this module knows about
//!
//! - Walking up from the call node to the enclosing
//!   `function_definition` (for name) and `class_definition`
//!   (informational).
//! - Walking the module root to detect top-level `import defusedxml`
//!   / `from defusedxml import ...` / `from lxml import etree` /
//!   `import xml.etree...` and populate the file-scoped
//!   `import_defusedxml` / `import_lxml_etree` flags + classify the
//!   `XmlApi` of the call.
//! - Detecting the `resolve_entities=False`, `no_network=True`, and
//!   `forbid_dtd=True` kwargs on the call (or on a nearby
//!   `XMLParser(...)` constructor — the predictor's
//!   "co-located within the same statement" semantics).
//! - Walking a 10-line lookback window for user-input substrings
//!   (carry-over of the existing `has_user_input_flow` heuristic at
//!   the old `xxe.rs:181`).
//! - Reading the source line for `# repotoire: xxe-safe[<reason>]`
//!   or `# repotoire: xxe-vulnerable[<source>]` annotations.
//!
//! # What this module deliberately does NOT do
//!
//! - Does not look for evidence in non-Python languages (D5 scope).
//! - Does not cross function boundaries (a `parser = make_parser();
//!   etree.parse(blob, parser)` shape is documented as a v0
//!   limitation in decisions doc D5 #2).
//! - Does not consult the graph for the enclosing scope. AST walking
//!   is sufficient and avoids a detector → graph dependency.
//!
//! # Status (commit-by-commit context)
//!
//! Wired in via `mod.rs::scan_python_file_dual_branch`. Every public
//! symbol below is reachable from the integration path; the
//! `#![allow(dead_code)]` from the scaffolding commit is removed
//! in this commit (no symbols remain dead).

use super::predict::{
    extract_xxe_safe_reason, extract_xxe_vulnerable_source, matches_user_input, Evidence, XmlApi,
};
use crate::detectors::security::ast_helpers::{
    collect_named_args, enclosing_python_function, node_text, python_kwarg_truthy,
};
use std::collections::HashSet;
use tree_sitter::Node;

/// A Python XML parser call site discovered by walking the module
/// AST. Returned by [`collect_python_xml_sites`] so the integration
/// in `mod.rs` can iterate over every potentially-relevant call
/// without re-walking.
///
/// `call_node` is the `call` AST node; `api` is the classified
/// [`XmlApi`] (already resolved through the file's import alias map).
/// Only sites whose `api` matches a recognized XML parse API are
/// returned (the collector also filters by callee name so non-XML
/// `parse(...)` calls on unrelated objects don't get flagged).
pub(super) struct PythonXmlSite<'a> {
    pub call_node: Node<'a>,
    pub api: XmlApi,
}

/// Walk a Python module AST and collect every call whose callee is a
/// recognized XML parse API.
///
/// Recognition is two-layered:
///   1. The leftmost identifier (or the resolved canonical module via
///      [`collect_xml_aliases`]) maps to an XML library — defusedxml,
///      lxml.etree, xml.etree.ElementTree, xml.sax, xml.dom.
///   2. The method/function name on the callee is one of the parse
///      verbs (`parse`, `parseString`, `fromstring`, `XMLParser`,
///      `XMLReader`, `XMLTreeBuilder`, `parseFile`).
///
/// Both filters are necessary: layer 1 alone would flag
/// `etree.SubElement` (not a parse sink); layer 2 alone would flag
/// any `parse(...)` call on any object. Together they pin the call
/// to "an XML library, doing parse-like work".
pub(super) fn collect_python_xml_sites<'a>(
    module_root: Node<'a>,
    source: &'a [u8],
) -> Vec<PythonXmlSite<'a>> {
    let imports = collect_xml_imports(module_root, source);
    if imports.is_empty() {
        // No XML import in the file → no XXE risk possible. Fast path.
        return Vec::new();
    }

    let mut sites = Vec::new();
    let cursor = module_root.walk();
    let mut stack: Vec<Node<'_>> = vec![module_root];
    while let Some(node) = stack.pop() {
        for child in node.children(&mut cursor.clone()) {
            stack.push(child);
        }
        if node.kind() != "call" {
            continue;
        }
        let Some(func) = node.child_by_field_name("function") else {
            continue;
        };
        let func_text = node_text(func, source).unwrap_or("");
        if !is_xml_parse_callee(func_text) {
            continue;
        }
        let api = classify_xml_api(node, source, &imports);
        if !api.is_python() {
            // `XmlApi::Unknown` etc. don't fire dual-branch shape.
            continue;
        }
        sites.push(PythonXmlSite {
            call_node: node,
            api,
        });
    }
    sites
}

/// True iff a callee text (e.g. `etree.parse`, `XMLParser`,
/// `defusedxml.ElementTree.parseString`) names a parse-like XML API.
///
/// Pinned in tests so future additions (e.g. `iterparse`) are
/// deliberate. Keep in sync with the regex in the legacy line
/// scanner (`xxe::XXE_PATTERN` and the `has_parse_call` substring
/// list in `detect()`).
fn is_xml_parse_callee(func_text: &str) -> bool {
    let tail = func_text.rsplit('.').next().unwrap_or(func_text);
    matches!(
        tail,
        "parse"
            | "parseString"
            | "parseFile"
            | "fromstring"
            | "XMLParser"
            | "XMLReader"
            | "XMLTreeBuilder"
            | "DocumentBuilder"
            | "SAXParser"
            | "iterparse"
    )
}

/// Extract typed evidence from a Python XML-parser call node.
///
/// `call_node` must be a `call` AST node whose function names an XML
/// parser API (e.g. `etree.parse`, `ET.parse`, `XMLParser`,
/// `defusedxml.ElementTree.parse`).
///
/// `module_root` is the file's module-level root node (used for
/// file-scoped import detection).
///
/// `source` is the file's raw bytes. `lines` is the pre-split
/// source-line slice the scanner already builds; used for the
/// user-input lookback and annotation parsing.
///
/// Never panics; missing fields produce `None`/`false`/defaults.
pub(super) fn extract_python_evidence<'a>(
    call_node: Node<'a>,
    module_root: Node<'a>,
    source: &'a [u8],
    lines: &[&str],
) -> Evidence {
    let mut ev = Evidence::default();

    // ── File-scoped imports. ──
    let imports = collect_xml_imports(module_root, source);
    ev.import_defusedxml = imports
        .iter()
        .any(|m| m == "defusedxml" || m.starts_with("defusedxml."));
    ev.import_lxml_etree = imports
        .iter()
        .any(|m| m == "lxml" || m == "lxml.etree" || m.starts_with("lxml."));

    // ── Enclosing function (for name) and class. ──
    if let Some(fn_node) = enclosing_python_function(call_node) {
        if let Some(name_node) = fn_node.child_by_field_name("name") {
            if let Some(name) = node_text(name_node, source) {
                ev.enclosing_function = Some(name.to_string());
            }
        }
    }
    ev.enclosing_class = enclosing_python_class_name(call_node, source);

    // ── XmlApi classification. ──
    //
    // Inspect the call's function chain text. `defusedxml.*` is
    // safe-by-default; `lxml.etree.*` is the configurable family;
    // `xml.etree.*` / `xml.sax.*` / `xml.dom.*` are stdlib unsafe.
    //
    // For a call shape like `ET.parse(...)`, we already have
    // `import xml.etree.ElementTree as ET` recorded in `imports`; the
    // classification needs to consult `imports` to resolve the alias.
    ev.api = Some(classify_xml_api(call_node, source, &imports));

    // ── Protection kwargs (call-site only, per D5 #2 v0 limitation). ──
    let mut all_args: Vec<Node<'_>> = Vec::new();
    if let Some(args_node) = call_node.child_by_field_name("arguments") {
        all_args = collect_named_args(args_node);
    }
    ev.kw_resolve_entities_false = python_kwarg_falsy(&all_args, "resolve_entities", source);
    ev.kw_no_network_true = python_kwarg_truthy(&all_args, "no_network", source, false);
    ev.kw_forbid_dtd_true = python_kwarg_truthy(&all_args, "forbid_dtd", source, false);

    // Additionally check for an `XMLParser(...)` constructor call as
    // any argument to the parse call — the canonical lxml pattern:
    //   parser = etree.XMLParser(resolve_entities=False)
    //   etree.parse(blob, parser)
    //
    // v0 limitation: only fires when XMLParser is called inline as an
    // argument. The two-statement form is documented in D5 #2.
    let mut cursor = call_node.walk();
    for arg in call_node.children(&mut cursor) {
        if arg.kind() == "argument_list" {
            scan_inline_xmlparser_kwargs(arg, source, &mut ev);
        }
    }

    // ── User input flow (10-line lookback). ──
    let line_idx = call_node.start_position().row;
    let start = line_idx.saturating_sub(10);
    let mut found_user_input = false;
    for prev in &lines[start..line_idx] {
        if matches_user_input(prev) {
            found_user_input = true;
            break;
        }
    }
    ev.has_user_input_flow = found_user_input;

    // ── Source-line annotations. ──
    if let Some(line) = lines.get(line_idx) {
        ev.xxe_safe_annotation = extract_xxe_safe_reason(line);
        ev.xxe_vulnerable_annotation = extract_xxe_vulnerable_source(line);
    }

    ev
}

// ─────────────────────────────────────────────────────────────────────────────
// Import collection
// ─────────────────────────────────────────────────────────────────────────────

/// Walk the module root and collect a set of imported module names
/// relevant to XML parsing: `defusedxml`, `lxml`, `lxml.etree`,
/// `xml.etree`, `xml.etree.ElementTree`, `xml.sax`, `xml.dom`,
/// `xml.dom.minidom`, `xml.dom.pulldom`.
///
/// Also handles aliasing: `import xml.etree.ElementTree as ET`
/// records both the original module name and the alias in a separate
/// `aliases` map (for `classify_xml_api`).
///
/// This is a focused walker (we only care about XML-related modules)
/// rather than calling out to the shared `python_imports` helper —
/// the shared helper builds maps for every import in the file, which
/// is overkill for this detector's narrow needs.
fn collect_xml_imports<'a>(root: Node<'a>, source: &'a [u8]) -> HashSet<String> {
    let mut set = HashSet::new();
    let mut cursor = root.walk();
    for top in root.children(&mut cursor) {
        match top.kind() {
            "import_statement" => {
                // `import M [as N], M2 [as N2]`.
                let mut nc = top.walk();
                for child in top.children(&mut nc) {
                    if !child.is_named() {
                        continue;
                    }
                    let module_name = match child.kind() {
                        "dotted_name" => node_text(child, source).map(str::to_string),
                        "aliased_import" => child
                            .child_by_field_name("name")
                            .and_then(|n| node_text(n, source))
                            .map(str::to_string),
                        _ => None,
                    };
                    if let Some(name) = module_name {
                        if is_xml_module(&name) {
                            set.insert(name);
                        }
                    }
                }
            }
            "import_from_statement" => {
                // `from M import X`.
                if let Some(m) = top.child_by_field_name("module_name") {
                    if let Some(name) = node_text(m, source) {
                        if is_xml_module(name) {
                            set.insert(name.to_string());
                        }
                    }
                }
            }
            _ => {}
        }
    }
    set
}

/// True iff `name` is one of the XML-related modules we care about.
fn is_xml_module(name: &str) -> bool {
    const XML_MODULES: &[&str] = &[
        "defusedxml",
        "lxml",
        "lxml.etree",
        "xml",
        "xml.etree",
        "xml.etree.ElementTree",
        "xml.etree.cElementTree",
        "xml.sax",
        "xml.dom",
        "xml.dom.minidom",
        "xml.dom.pulldom",
    ];
    // Match exact OR any "M.*" submodule (e.g. `defusedxml.ElementTree`).
    XML_MODULES
        .iter()
        .any(|m| name == *m || name.starts_with(&format!("{m}.")))
}

/// Map aliases for the XML modules — `import xml.etree.ElementTree as ET`
/// produces `{ "ET" -> "xml.etree.ElementTree" }`. Used by
/// `classify_xml_api` to resolve a `ET.parse(...)` call to its
/// canonical module.
fn collect_xml_aliases<'a>(
    root: Node<'a>,
    source: &'a [u8],
) -> std::collections::HashMap<String, String> {
    let mut map = std::collections::HashMap::new();
    let mut cursor = root.walk();
    for top in root.children(&mut cursor) {
        match top.kind() {
            "import_statement" => {
                let mut nc = top.walk();
                for child in top.children(&mut nc) {
                    if !child.is_named() {
                        continue;
                    }
                    match child.kind() {
                        "aliased_import" => {
                            let module = child
                                .child_by_field_name("name")
                                .and_then(|n| node_text(n, source));
                            let alias = child
                                .child_by_field_name("alias")
                                .and_then(|n| node_text(n, source));
                            if let (Some(m), Some(a)) = (module, alias) {
                                if is_xml_module(m) {
                                    map.insert(a.to_string(), m.to_string());
                                }
                            }
                        }
                        "dotted_name" => {
                            // `import xml.etree.ElementTree` (no alias):
                            // the local name is the whole dotted path.
                            // No alias entry needed.
                        }
                        _ => {}
                    }
                }
            }
            "import_from_statement" => {
                // `from M import X [as Y]` — X (or Y) is a *symbol*,
                // not a module. Record the module so we know what API
                // family X belongs to.
                let module = top
                    .child_by_field_name("module_name")
                    .and_then(|n| node_text(n, source));
                let Some(module) = module else { continue };
                if !is_xml_module(module) {
                    continue;
                }
                let module_name_id = top.child_by_field_name("module_name").map(|n| n.id());
                let mut nc = top.walk();
                for child in top.children(&mut nc) {
                    if !child.is_named() || Some(child.id()) == module_name_id {
                        continue;
                    }
                    match child.kind() {
                        "dotted_name" => {
                            if let Some(name) = node_text(child, source) {
                                map.insert(name.to_string(), module.to_string());
                            }
                        }
                        "aliased_import" => {
                            let alias = child
                                .child_by_field_name("alias")
                                .and_then(|n| node_text(n, source));
                            if let Some(a) = alias {
                                map.insert(a.to_string(), module.to_string());
                            }
                        }
                        _ => {}
                    }
                }
            }
            _ => {}
        }
    }
    map
}

// ─────────────────────────────────────────────────────────────────────────────
// XmlApi classification
// ─────────────────────────────────────────────────────────────────────────────

/// Classify the call's parser API by inspecting:
///
/// 1. The function chain text (e.g. `defusedxml.ElementTree.parse`).
/// 2. The module aliases resolved from imports.
/// 3. The `from X import Y` map (`Y` as a bare-identifier callee).
fn classify_xml_api<'a>(
    call_node: Node<'a>,
    source: &'a [u8],
    imports: &HashSet<String>,
) -> XmlApi {
    let module_root = walk_to_module(call_node);
    let aliases = collect_xml_aliases(module_root, source);

    // Get the function being called as text.
    let Some(func) = call_node.child_by_field_name("function") else {
        return XmlApi::Unknown;
    };
    let func_text = node_text(func, source).unwrap_or("");

    // Parse the leftmost identifier of the chain.
    let leftmost = leftmost_identifier(func_text);

    // Resolve the leftmost identifier through the alias map.
    let resolved_module = aliases
        .get(leftmost)
        .cloned()
        .unwrap_or_else(|| leftmost.to_string());

    // Classify based on the resolved module name.
    if resolved_module.starts_with("defusedxml") {
        return XmlApi::Defusedxml;
    }
    if resolved_module == "lxml" || resolved_module.starts_with("lxml.") {
        return XmlApi::LxmlEtree;
    }
    if resolved_module.starts_with("xml.etree") {
        return XmlApi::StdlibElementTree;
    }
    if resolved_module.starts_with("xml.sax") || resolved_module.starts_with("xml.dom") {
        return XmlApi::StdlibOther;
    }

    // Fallback: scan the raw function text and the import set for
    // a recognizable family. Handles `etree.parse(...)` when
    // `from lxml import etree` (so `etree` is the leftmost ident).
    if imports.iter().any(|m| m.starts_with("defusedxml")) && leftmost.starts_with("defused") {
        return XmlApi::Defusedxml;
    }
    if imports.contains("lxml.etree") || imports.contains("lxml") {
        return XmlApi::LxmlEtree;
    }
    if imports.iter().any(|m| m.starts_with("xml.etree")) {
        return XmlApi::StdlibElementTree;
    }
    if imports
        .iter()
        .any(|m| m.starts_with("xml.sax") || m.starts_with("xml.dom"))
    {
        return XmlApi::StdlibOther;
    }

    XmlApi::Unknown
}

/// Return the leftmost identifier of a dotted/attribute chain.
///
/// `"xml.etree.ElementTree.parse"` → `"xml"`.
/// `"ET.parse"` → `"ET"`.
/// `"parse"` → `"parse"`.
fn leftmost_identifier(text: &str) -> &str {
    text.split('.').next().unwrap_or(text)
}

fn walk_to_module(node: Node<'_>) -> Node<'_> {
    let mut cur = node;
    while let Some(parent) = cur.parent() {
        cur = parent;
    }
    cur
}

// ─────────────────────────────────────────────────────────────────────────────
// Kwarg helpers
// ─────────────────────────────────────────────────────────────────────────────

/// Mirror of `python_kwarg_truthy` for `KW=False` detection.
///
/// Returns `true` iff the named kwarg appears AND its value is the
/// literal `False`. Conservative: a non-literal value (variable,
/// expression) returns `false` because we can't statically prove it's
/// False at runtime.
fn python_kwarg_falsy(args: &[Node<'_>], name: &str, source: &[u8]) -> bool {
    for arg in args {
        if arg.kind() != "keyword_argument" {
            continue;
        }
        let Some(arg_name) = arg.child_by_field_name("name") else {
            continue;
        };
        let Some(arg_name_text) = node_text(arg_name, source) else {
            continue;
        };
        if arg_name_text != name {
            continue;
        }
        let Some(value) = arg.child_by_field_name("value") else {
            continue;
        };
        if let Some(value_text) = node_text(value, source) {
            return value_text.trim() == "False";
        }
    }
    false
}

/// Scan the call's argument list for an inline `XMLParser(...)`
/// constructor and OR-in any protection kwargs from it.
///
/// Handles the canonical lxml safe-construction pattern when the
/// parser is constructed inline (NOT in a separate statement — that
/// case is the D5 #2 v0 limitation).
fn scan_inline_xmlparser_kwargs<'a>(arg_list: Node<'a>, source: &'a [u8], ev: &mut Evidence) {
    let mut cursor = arg_list.walk();
    for child in arg_list.children(&mut cursor) {
        if child.kind() != "call" {
            continue;
        }
        let Some(func) = child.child_by_field_name("function") else {
            continue;
        };
        let func_text = node_text(func, source).unwrap_or("");
        if !func_text.ends_with("XMLParser") {
            continue;
        }
        let Some(inner_args) = child.child_by_field_name("arguments") else {
            continue;
        };
        let inner = collect_named_args(inner_args);
        if !ev.kw_resolve_entities_false && python_kwarg_falsy(&inner, "resolve_entities", source) {
            ev.kw_resolve_entities_false = true;
        }
        if !ev.kw_no_network_true && python_kwarg_truthy(&inner, "no_network", source, false) {
            ev.kw_no_network_true = true;
        }
        if !ev.kw_forbid_dtd_true && python_kwarg_truthy(&inner, "forbid_dtd", source, false) {
            ev.kw_forbid_dtd_true = true;
        }
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Enclosing class (8-line carry-over from 2a/2b/2d, per the
// "rule-of-three deferred" comment in command_injection/evidence.rs:343)
// ─────────────────────────────────────────────────────────────────────────────

fn enclosing_python_class_name<'a>(node: Node<'a>, source: &'a [u8]) -> Option<String> {
    let mut cur = node.parent()?;
    loop {
        if cur.kind() == "class_definition" {
            let name = cur.child_by_field_name("name")?;
            return node_text(name, source).map(str::to_string);
        }
        if cur.kind() == "module" {
            return None;
        }
        cur = cur.parent()?;
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use crate::detectors::ast_fingerprint::parse_root_ext;
    use crate::parsers::lightweight::Language;

    /// Parse `source` as Python and find the first `call` node whose
    /// function chain ends with the given attribute or identifier
    /// name.
    fn first_call_with_attr<'tree>(
        tree: &'tree tree_sitter::Tree,
        source: &[u8],
        attr_name: &str,
    ) -> tree_sitter::Node<'tree> {
        fn walk<'a>(
            node: tree_sitter::Node<'a>,
            source: &[u8],
            attr_name: &str,
        ) -> Option<tree_sitter::Node<'a>> {
            if node.kind() == "call" {
                if let Some(func) = node.child_by_field_name("function") {
                    let text = node_text(func, source).unwrap_or("");
                    let last = text.rsplit('.').next().unwrap_or("");
                    if last == attr_name {
                        return Some(node);
                    }
                }
            }
            let mut cursor = node.walk();
            for child in node.children(&mut cursor) {
                if let Some(found) = walk(child, source, attr_name) {
                    return Some(found);
                }
            }
            None
        }
        walk(tree.root_node(), source, attr_name)
            .unwrap_or_else(|| panic!("no call to {} found in source", attr_name))
    }

    fn extract(src: &str, attr: &str) -> Evidence {
        let tree = parse_root_ext(src, Language::Python, "py").expect("parse python");
        let root = tree.root_node();
        let call = first_call_with_attr(&tree, src.as_bytes(), attr);
        let lines: Vec<&str> = src.lines().collect();
        extract_python_evidence(call, root, src.as_bytes(), &lines)
    }

    // ─── Import detection ───

    #[test]
    fn detects_defusedxml_import() {
        let src = "import defusedxml.ElementTree as ET\nET.parse('x.xml')\n";
        let ev = extract(src, "parse");
        assert!(ev.import_defusedxml);
        assert!(!ev.import_lxml_etree);
        assert_eq!(ev.api, Some(XmlApi::Defusedxml));
    }

    #[test]
    fn detects_lxml_etree_import() {
        let src = "from lxml import etree\netree.parse('x.xml')\n";
        let ev = extract(src, "parse");
        assert!(ev.import_lxml_etree);
        assert!(!ev.import_defusedxml);
        assert_eq!(ev.api, Some(XmlApi::LxmlEtree));
    }

    #[test]
    fn detects_stdlib_etree_import() {
        let src = "import xml.etree.ElementTree as ET\nET.parse('x.xml')\n";
        let ev = extract(src, "parse");
        assert!(!ev.import_defusedxml);
        assert!(!ev.import_lxml_etree);
        assert_eq!(ev.api, Some(XmlApi::StdlibElementTree));
    }

    #[test]
    fn detects_xml_sax_import() {
        let src = "import xml.sax\nxml.sax.parse('x.xml', handler)\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.api, Some(XmlApi::StdlibOther));
    }

    #[test]
    fn detects_xml_dom_minidom_import() {
        let src = "from xml.dom import minidom\nminidom.parse('x.xml')\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.api, Some(XmlApi::StdlibOther));
    }

    // ─── Kwarg detection ───

    #[test]
    fn detects_resolve_entities_false_on_parser_constructor() {
        // Inline XMLParser(...) as argument — the canonical safe pattern.
        let src = "\
            from lxml import etree\n\
            etree.parse(blob, etree.XMLParser(resolve_entities=False))\n";
        let ev = extract(src, "parse");
        assert!(ev.kw_resolve_entities_false);
    }

    #[test]
    fn detects_no_network_true() {
        let src = "\
            from lxml import etree\n\
            etree.parse(blob, etree.XMLParser(no_network=True))\n";
        let ev = extract(src, "parse");
        assert!(ev.kw_no_network_true);
    }

    #[test]
    fn detects_forbid_dtd_true() {
        let src = "\
            import defusedxml.ElementTree as ET\n\
            ET.parse(blob, forbid_dtd=True)\n";
        let ev = extract(src, "parse");
        assert!(ev.kw_forbid_dtd_true);
    }

    #[test]
    fn resolve_entities_true_does_not_fire_falsy_signal() {
        let src = "\
            from lxml import etree\n\
            etree.parse(blob, etree.XMLParser(resolve_entities=True))\n";
        let ev = extract(src, "parse");
        assert!(!ev.kw_resolve_entities_false);
    }

    #[test]
    fn non_literal_kwarg_value_is_not_classified_falsy() {
        // Conservative: variable value is not statically False.
        let src = "\
            from lxml import etree\n\
            etree.parse(blob, etree.XMLParser(resolve_entities=flag))\n";
        let ev = extract(src, "parse");
        assert!(!ev.kw_resolve_entities_false);
    }

    // ─── User-input flow ───

    #[test]
    fn detects_request_data_within_lookback_window() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            def handle(request):\n\
            \x20   blob = request.data\n\
            \x20   return ET.parse(blob)\n";
        let ev = extract(src, "parse");
        assert!(ev.has_user_input_flow);
    }

    #[test]
    fn no_user_input_flow_for_local_file_read() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            blob = open('config.xml').read()\n\
            ET.parse(blob)\n";
        let ev = extract(src, "parse");
        assert!(!ev.has_user_input_flow);
    }

    #[test]
    fn detects_uploaded_file_input() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            uploaded = request.files['xml']\n\
            ET.parse(uploaded)\n";
        let ev = extract(src, "parse");
        assert!(ev.has_user_input_flow);
    }

    // ─── Enclosing scope ───

    #[test]
    fn detects_enclosing_function() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            def handle_upload(request):\n\
            \x20   ET.parse(request.data)\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.enclosing_function, Some("handle_upload".to_string()));
    }

    #[test]
    fn detects_enclosing_class() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            class UploadHandler:\n\
            \x20   def parse(self, blob):\n\
            \x20       ET.parse(blob)\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.enclosing_class, Some("UploadHandler".to_string()));
    }

    #[test]
    fn no_enclosing_class_at_module_level() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            ET.parse('x.xml')\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.enclosing_class, None);
    }

    // ─── Source annotations ───

    #[test]
    fn detects_xxe_safe_annotation() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            ET.parse(blob)  # repotoire: xxe-safe[xsd-validated]\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.xxe_safe_annotation, Some("xsd-validated".to_string()));
        assert_eq!(ev.xxe_vulnerable_annotation, None);
    }

    #[test]
    fn detects_xxe_vulnerable_annotation() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            ET.parse(blob)  # repotoire: xxe-vulnerable[audited]\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.xxe_vulnerable_annotation, Some("audited".to_string()));
        assert_eq!(ev.xxe_safe_annotation, None);
    }

    #[test]
    fn ignores_unrelated_annotation_kinds() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            ET.parse(blob)  # repotoire: command-static[ok]\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.xxe_safe_annotation, None);
        assert_eq!(ev.xxe_vulnerable_annotation, None);
    }

    // ─── leftmost_identifier helper ───

    #[test]
    fn leftmost_identifier_handles_dotted_chains() {
        assert_eq!(leftmost_identifier("ET.parse"), "ET");
        assert_eq!(leftmost_identifier("xml.etree.ElementTree.parse"), "xml");
        assert_eq!(leftmost_identifier("parse"), "parse");
    }

    // ─── is_xml_module helper ───

    #[test]
    fn is_xml_module_matches_exact_and_submodules() {
        assert!(is_xml_module("defusedxml"));
        assert!(is_xml_module("defusedxml.ElementTree"));
        assert!(is_xml_module("lxml.etree"));
        assert!(is_xml_module("xml.etree.ElementTree"));
        assert!(is_xml_module("xml.sax"));
        assert!(is_xml_module("xml.dom.minidom"));
        // Not XML:
        assert!(!is_xml_module("os"));
        assert!(!is_xml_module("subprocess"));
        // Substring without dot boundary is rejected:
        assert!(!is_xml_module("xmllint"));
    }

    // ─── End-to-end shape tests pinning decisions-doc worked examples ───

    #[test]
    fn worked_example_canonical_lxml_safe_extraction() {
        let src = "\
            from lxml import etree\n\
            def parse_user_xml(blob):\n\
            \x20   parser = etree.XMLParser(resolve_entities=False, no_network=True)\n\
            \x20   return etree.parse(blob, parser)\n";
        let ev = extract(src, "parse");
        assert!(ev.import_lxml_etree);
        assert_eq!(ev.api, Some(XmlApi::LxmlEtree));
        // v0 D5 #2 limitation: the parser is constructed in a SEPARATE
        // statement and passed as a variable. The kwarg signals do NOT
        // fire from the call site of `etree.parse(blob, parser)` because
        // `parser` is a bare identifier, not an inline XMLParser(...).
        // This pins the v0 limitation: a real user-facing v1 fix would
        // do intra-function flow to trace `parser` back to its
        // constructor.
        assert!(!ev.kw_resolve_entities_false);
        assert!(!ev.kw_no_network_true);
    }

    #[test]
    fn worked_example_canonical_lxml_safe_inline_extraction() {
        // Same code shape but the XMLParser is inline — the kwargs
        // DO fire.
        let src = "\
            from lxml import etree\n\
            def parse_user_xml(blob):\n\
            \x20   return etree.parse(blob, etree.XMLParser(resolve_entities=False, no_network=True))\n";
        let ev = extract(src, "parse");
        assert!(ev.import_lxml_etree);
        assert_eq!(ev.api, Some(XmlApi::LxmlEtree));
        assert!(ev.kw_resolve_entities_false);
        assert!(ev.kw_no_network_true);
    }

    #[test]
    fn worked_example_canonical_realbug_extraction() {
        let src = "\
            import xml.etree.ElementTree as ET\n\
            def handle_upload(request):\n\
            \x20   blob = request.data\n\
            \x20   return ET.parse(blob)\n";
        let ev = extract(src, "parse");
        assert!(!ev.import_defusedxml);
        assert_eq!(ev.api, Some(XmlApi::StdlibElementTree));
        assert!(ev.has_user_input_flow);
        assert_eq!(ev.enclosing_function, Some("handle_upload".to_string()));
    }

    #[test]
    fn unused_defusedxml_import_pins_v0_limitation() {
        // D5 #1 v0 limitation: file-scoped import detection means an
        // unused defusedxml import + stdlib parse still flags
        // `import_defusedxml=true`. The predictor handles this case
        // (sum = +0.10, tiebreak-close Benign with alternative); this
        // test pins the extractor side: BOTH flags fire.
        let src = "\
            import defusedxml.ElementTree  # not used\n\
            import xml.etree.ElementTree as ET\n\
            def parse_blob(blob):\n\
            \x20   return ET.parse(blob)\n";
        let ev = extract(src, "parse");
        assert!(ev.import_defusedxml);
        assert_eq!(ev.api, Some(XmlApi::StdlibElementTree));
        // The api is resolved through the alias `ET`, not affected by
        // the defusedxml file-scoped import. This pins the orthogonal
        // semantics: API classification is call-scoped, import
        // detection is file-scoped.
    }

    // ─── End-to-end with annotation collapse interaction ───

    #[test]
    fn xxe_safe_annotation_records_alongside_other_signals() {
        // Annotation parsing is orthogonal to other evidence; both
        // fire and the predictor decides priority.
        let src = "\
            import xml.etree.ElementTree as ET\n\
            def handle_upload(request):\n\
            \x20   blob = request.data\n\
            \x20   return ET.parse(blob)  # repotoire: xxe-safe[xsd-validated]\n";
        let ev = extract(src, "parse");
        assert_eq!(ev.xxe_safe_annotation, Some("xsd-validated".to_string()));
        // The other evidence is also populated (the predictor still
        // sees it, but the collapsing annotation overrides):
        assert!(ev.has_user_input_flow);
        assert_eq!(ev.enclosing_function, Some("handle_upload".to_string()));
        assert_eq!(ev.api, Some(XmlApi::StdlibElementTree));
    }
}