repotoire 0.7.0

//! Shared AST helpers for security detectors.
//!
//! Consolidates `unwrap_callee`, `collect_named_args`, `node_text`,
//! `receiver_chain_label`, `receiver_chain_label_go`, and
//! `receiver_chain_label_js` formerly duplicated across 5+ detectors.
//! Caught by `AIDuplicateBlockDetector` during repotoire dogfooding (see
//! `docs/plans/2026-05-08-security-detector-ast-architecture.md`).
//!
//! Layering: this module depends only on `tree_sitter`. It MUST NOT depend
//! on any other module in the crate to avoid circular imports.

use tree_sitter::Node;

/// Decode a node's source-text slice as UTF-8.
///
/// Returns `None` if the byte range is not valid UTF-8. The end byte is
/// clamped to `source.len()` to defend against tree-sitter overshoot on
/// truncated input.
///
/// Formerly duplicated 6 times across the security detectors.
pub(crate) fn node_text<'a>(node: Node<'_>, source: &'a [u8]) -> Option<&'a str> {
    let start = node.start_byte();
    let end = node.end_byte().min(source.len());
    std::str::from_utf8(&source[start..end]).ok()
}

/// Strip parenthesisation and JS comma-operator wrappers from a callee
/// expression, returning the innermost expression that should be matched
/// against the call shape.
///
/// Handles:
/// - `parenthesized_expression` → first named child
/// - `sequence_expression` → last named child (comma operator: result is
///   the rightmost expression)
///
/// Formerly duplicated 5 times across the security detectors with
/// identical bodies (only comments differed).
pub(crate) fn unwrap_callee(mut node: Node<'_>) -> Node<'_> {
    loop {
        match node.kind() {
            "parenthesized_expression" => {
                let mut next = None;
                for i in 0..node.named_child_count() {
                    if let Some(c) = node.named_child(i) {
                        next = Some(c);
                        break;
                    }
                }
                match next {
                    Some(n) => node = n,
                    None => return node,
                }
            }
            "sequence_expression" => {
                // Last named child wins (comma operator).
                let last = (0..node.named_child_count())
                    .rev()
                    .find_map(|i| node.named_child(i));
                match last {
                    Some(n) => node = n,
                    None => return node,
                }
            }
            _ => return node,
        }
    }
}

/// Collect the named children of an arguments / parameter-list node.
///
/// This is the standard "give me the actual argument expressions, not
/// commas/parens" walk used in every JS/TS/Python call-shape matcher in
/// the security layer.
///
/// Formerly duplicated 6 times (5 as `collect_named_args`, once as
/// `collect_call_args` in `cleartext_credentials.rs` — functionally
/// identical, unified under the more descriptive name).
pub(crate) fn collect_named_args<'a>(args: Node<'a>) -> Vec<Node<'a>> {
    let mut out = Vec::new();
    let mut cursor = args.walk();
    for child in args.children(&mut cursor) {
        if child.is_named() {
            out.push(child);
        }
    }
    out
}

/// Locate a Python `keyword_argument` by name and return its value node.
///
/// Handles the common case where security detectors need to inspect a
/// specific kwarg passed to a function call (e.g. `shell` in
/// `subprocess.run(...)`, `Loader` in `yaml.load(...)`,
/// `allow_pickle` in `numpy.load(...)`).
///
/// The input slice is expected to be the named children of an
/// `argument_list` node (typically obtained via [`collect_named_args`]).
/// Non-keyword positional arguments are ignored.
pub(crate) fn python_kwarg_value<'a>(
    args: &[Node<'a>],
    name: &str,
    source: &[u8],
) -> Option<Node<'a>> {
    for a in args {
        if a.kind() != "keyword_argument" {
            continue;
        }
        let arg_name = a
            .child_by_field_name("name")
            .and_then(|n| node_text(n, source));
        if arg_name == Some(name) {
            return a.child_by_field_name("value");
        }
    }
    None
}

/// Decide whether a Python boolean keyword argument is passed truthy.
///
/// Returns:
/// - `true` if the kwarg's value is the literal `True`.
/// - `false` if the kwarg's value is the literal `False`.
/// - `unknown_default` if the kwarg is present but the value is a
///   non-literal expression (variable, function call, attribute, ...).
///   Detectors choose this based on whether the unsafe path is the
///   conservative default for the call site (e.g. `shell=` and
///   `allow_pickle=` use `true`; `weights_only=` uses `false`).
/// - `false` if the kwarg is absent.
pub(crate) fn python_kwarg_truthy(
    args: &[Node<'_>],
    name: &str,
    source: &[u8],
    unknown_default: bool,
) -> bool {
    match python_kwarg_value(args, name, source) {
        Some(value) => match value.kind() {
            "true" => true,
            "false" => false,
            _ => unknown_default,
        },
        None => false,
    }
}

/// Compute the lower-cased "label" of a receiver expression in a method
/// chain — i.e. the last name in the chain (`a.b.c` → `"c"`,
/// `os.path.join` → `"join"`).
///
/// `call_resolver` is invoked when the receiver itself is a
/// `call_expression`; it lets the detector recognise patterns like
/// `require('child_process').exec` or `(await import('crypto')).randomBytes`
/// by mapping the call to a canonical module name. Pass `None` if the
/// detector does not need module-aware resolution.
///
/// Recognised receiver shapes:
/// - `member_expression` (JS/TS): take the `property` field.
/// - `attribute` (Python): take the `attribute` field.
/// - `selector_expression` (Go): take the `field` field.
/// - `member_access_expression` (C#): take the `name` field.
/// - `call_expression`: try `call_resolver`, otherwise fall back to text.
/// - `await_expression` / `parenthesized_expression`: descend into the
///   first named child.
/// - Anything else: lower-cased source text (covers bare identifiers,
///   `this`, `self`, `super`, etc.).
///
/// Formerly five separate impls with overlapping but divergent shape
/// support. The unified version is a strict superset of every prior
/// behavior. See the migration commit message for the per-detector
/// before/after.
pub(crate) fn receiver_chain_label(
    node: Node<'_>,
    source: &[u8],
    call_resolver: Option<&dyn Fn(Node<'_>, &[u8]) -> Option<&'static str>>,
) -> String {
    match node.kind() {
        // JS/TS `member_expression` and Python `attribute` are unified
        // here: try both field names so a grammar quirk in either
        // language doesn't silently fall through. (`cleartext_credentials`
        // historically did this defensive `or_else` chain.)
        "member_expression" | "attribute" => {
            if let Some(prop) = node
                .child_by_field_name("property")
                .or_else(|| node.child_by_field_name("attribute"))
            {
                if let Some(s) = node_text(prop, source) {
                    return s.to_lowercase();
                }
            }
            node_text(node, source).unwrap_or("").to_lowercase()
        }
        "selector_expression" => {
            if let Some(field) = node.child_by_field_name("field") {
                if let Some(s) = node_text(field, source) {
                    return s.to_lowercase();
                }
            }
            node_text(node, source).unwrap_or("").to_lowercase()
        }
        "member_access_expression" => {
            if let Some(name) = node.child_by_field_name("name") {
                if let Some(s) = node_text(name, source) {
                    return s.to_lowercase();
                }
            }
            node_text(node, source).unwrap_or("").to_lowercase()
        }
        "call_expression" => {
            if let Some(resolver) = call_resolver {
                if let Some(label) = resolver(node, source) {
                    return label.to_string();
                }
            }
            node_text(node, source).unwrap_or("").to_lowercase()
        }
        "await_expression" | "parenthesized_expression" => {
            for i in 0..node.named_child_count() {
                if let Some(c) = node.named_child(i) {
                    return receiver_chain_label(c, source, call_resolver);
                }
            }
            node_text(node, source).unwrap_or("").to_lowercase()
        }
        _ => node_text(node, source).unwrap_or("").to_lowercase(),
    }
}

/// Go-specific receiver-chain label.
///
/// Tree-sitter-go represents method-chains as `selector_expression` with a
/// `field` child, so we don't need the broader JS/Python repertoire here.
/// Kept separate from the unified [`receiver_chain_label`] for clarity at
/// the callsite — `match_go_call` should never see a `member_expression`
/// or `attribute` node.
pub(crate) fn receiver_chain_label_go(node: Node<'_>, source: &[u8]) -> String {
    match node.kind() {
        "selector_expression" => {
            if let Some(field) = node.child_by_field_name("field") {
                if let Some(s) = node_text(field, source) {
                    return s.to_lowercase();
                }
            }
            node_text(node, source).unwrap_or("").to_lowercase()
        }
        _ => node_text(node, source).unwrap_or("").to_lowercase(),
    }
}

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

    fn parse_js(src: &str) -> tree_sitter::Tree {
        let mut parser = Parser::new();
        parser
            .set_language(&tree_sitter_javascript::LANGUAGE.into())
            .expect("load js grammar");
        parser.parse(src, None).expect("parse")
    }

    fn parse_ts(src: &str) -> tree_sitter::Tree {
        let mut parser = Parser::new();
        parser
            .set_language(&tree_sitter_typescript::LANGUAGE_TYPESCRIPT.into())
            .expect("load ts grammar");
        parser.parse(src, None).expect("parse")
    }

    fn parse_python(src: &str) -> tree_sitter::Tree {
        let mut parser = Parser::new();
        parser
            .set_language(&tree_sitter_python::LANGUAGE.into())
            .expect("load python grammar");
        parser.parse(src, None).expect("parse")
    }

    fn parse_go(src: &str) -> tree_sitter::Tree {
        let mut parser = Parser::new();
        parser
            .set_language(&tree_sitter_go::LANGUAGE.into())
            .expect("load go grammar");
        parser.parse(src, None).expect("parse")
    }

    /// Walk the tree and return the first node whose `kind()` matches.
    fn find_kind<'a>(root: Node<'a>, kind: &str) -> Option<Node<'a>> {
        let mut stack = vec![root];
        while let Some(n) = stack.pop() {
            if n.kind() == kind {
                return Some(n);
            }
            for i in (0..n.child_count()).rev() {
                if let Some(c) = n.child(i) {
                    stack.push(c);
                }
            }
        }
        None
    }

    // ----- unwrap_callee -----

    #[test]
    fn unwrap_callee_parenthesized() {
        // `(eval)("alert(1)")` — the call expression's `function` field is a
        // parenthesized_expression wrapping `eval`.
        let src = "(eval)('x');\n";
        let tree = parse_js(src);
        let call = find_kind(tree.root_node(), "call_expression").expect("call");
        let func = call.child_by_field_name("function").expect("func");
        assert_eq!(func.kind(), "parenthesized_expression");
        let unwrapped = unwrap_callee(func);
        assert_eq!(unwrapped.kind(), "identifier");
        assert_eq!(node_text(unwrapped, src.as_bytes()), Some("eval"));
    }

    #[test]
    fn unwrap_callee_ts_passthrough() {
        // TS `as_expression` is NOT handled here (out of scope of the
        // current consolidated behavior — none of the prior copies handled
        // it either). This test pins that contract: `as` casts pass
        // through unchanged.
        let src = "(x as Foo)();\n";
        let tree = parse_ts(src);
        let call = find_kind(tree.root_node(), "call_expression").expect("call");
        let func = call.child_by_field_name("function").expect("func");
        // The outer wrap is a parenthesized_expression around `x as Foo`.
        let unwrapped = unwrap_callee(func);
        // Should descend through the parens to the as_expression.
        assert_eq!(unwrapped.kind(), "as_expression");
    }

    #[test]
    fn unwrap_callee_plain_identifier() {
        let src = "eval('x');\n";
        let tree = parse_js(src);
        let call = find_kind(tree.root_node(), "call_expression").expect("call");
        let func = call.child_by_field_name("function").expect("func");
        let unwrapped = unwrap_callee(func);
        assert_eq!(unwrapped.kind(), "identifier");
        assert_eq!(unwrapped.id(), func.id());
    }

    // ----- collect_named_args -----

    #[test]
    fn collect_named_args_positional_only() {
        let src = "f(1, 2, 3);\n";
        let tree = parse_js(src);
        let call = find_kind(tree.root_node(), "call_expression").expect("call");
        let args = call.child_by_field_name("arguments").expect("args");
        let collected = collect_named_args(args);
        assert_eq!(collected.len(), 3);
        assert!(collected.iter().all(|n| n.kind() == "number"));
    }

    #[test]
    fn collect_named_args_python_keyword() {
        // Python lets us mix kwargs; both kinds are named children of the
        // argument_list.
        let src = "f(name='x')\n";
        let tree = parse_python(src);
        let call = find_kind(tree.root_node(), "call").expect("call");
        let args = call.child_by_field_name("arguments").expect("args");
        let collected = collect_named_args(args);
        assert_eq!(collected.len(), 1);
        assert_eq!(collected[0].kind(), "keyword_argument");
    }

    #[test]
    fn collect_named_args_mixed() {
        let src = "f(1, 'two', x);\n";
        let tree = parse_js(src);
        let call = find_kind(tree.root_node(), "call_expression").expect("call");
        let args = call.child_by_field_name("arguments").expect("args");
        let collected = collect_named_args(args);
        assert_eq!(collected.len(), 3);
        // commas are unnamed and must be filtered out.
        assert!(!collected.iter().any(|n| n.kind() == ","));
    }

    // ----- python_kwarg_value / python_kwarg_truthy -----

    fn collect_py_call_args<'a>(tree: &'a tree_sitter::Tree) -> Vec<Node<'a>> {
        let call = find_kind(tree.root_node(), "call").expect("call");
        let args = call.child_by_field_name("arguments").expect("args");
        collect_named_args(args)
    }

    #[test]
    fn python_kwarg_value_locates_named_arg() {
        let src = "f(shell=True, timeout=30)\n";
        let tree = parse_python(src);
        let args = collect_py_call_args(&tree);
        let v = python_kwarg_value(&args, "shell", src.as_bytes()).expect("shell value");
        assert_eq!(v.kind(), "true");
        let v2 = python_kwarg_value(&args, "timeout", src.as_bytes()).expect("timeout value");
        assert_eq!(v2.kind(), "integer");
    }

    #[test]
    fn python_kwarg_value_returns_none_for_absent() {
        let src = "f(shell=True)\n";
        let tree = parse_python(src);
        let args = collect_py_call_args(&tree);
        assert!(python_kwarg_value(&args, "missing", src.as_bytes()).is_none());
    }

    #[test]
    fn python_kwarg_value_skips_positional_args() {
        // Positional args are not keyword_arguments; the helper must not
        // misidentify them.
        let src = "f(\"shell\", x)\n";
        let tree = parse_python(src);
        let args = collect_py_call_args(&tree);
        assert!(python_kwarg_value(&args, "shell", src.as_bytes()).is_none());
    }

    #[test]
    fn python_kwarg_truthy_literal_true() {
        let src = "f(shell=True)\n";
        let tree = parse_python(src);
        let args = collect_py_call_args(&tree);
        assert!(python_kwarg_truthy(&args, "shell", src.as_bytes(), false));
        assert!(python_kwarg_truthy(&args, "shell", src.as_bytes(), true));
    }

    #[test]
    fn python_kwarg_truthy_literal_false() {
        let src = "f(shell=False)\n";
        let tree = parse_python(src);
        let args = collect_py_call_args(&tree);
        // Literal False overrides unknown_default in either direction.
        assert!(!python_kwarg_truthy(&args, "shell", src.as_bytes(), false));
        assert!(!python_kwarg_truthy(&args, "shell", src.as_bytes(), true));
    }

    #[test]
    fn python_kwarg_truthy_non_literal_uses_default() {
        let src = "f(shell=some_var)\n";
        let tree = parse_python(src);
        let args = collect_py_call_args(&tree);
        assert!(python_kwarg_truthy(&args, "shell", src.as_bytes(), true));
        assert!(!python_kwarg_truthy(&args, "shell", src.as_bytes(), false));
    }

    #[test]
    fn python_kwarg_truthy_absent_is_false() {
        // Absent kwarg always returns false regardless of unknown_default —
        // the default semantic only kicks in when the kwarg is *present*
        // but its value is non-literal.
        let src = "f(timeout=5)\n";
        let tree = parse_python(src);
        let args = collect_py_call_args(&tree);
        assert!(!python_kwarg_truthy(&args, "shell", src.as_bytes(), true));
        assert!(!python_kwarg_truthy(&args, "shell", src.as_bytes(), false));
    }

    // ----- receiver_chain_label -----

    #[test]
    fn receiver_chain_label_simple_identifier() {
        // For a bare identifier, the label is just its lowercased text.
        let src = "x;\n";
        let tree = parse_js(src);
        let id = find_kind(tree.root_node(), "identifier").expect("id");
        assert_eq!(receiver_chain_label(id, src.as_bytes(), None), "x");
    }

    #[test]
    fn receiver_chain_label_member_chain() {
        // `a.b.c` — the outer member_expression's property is `c`.
        let src = "a.b.c;\n";
        let tree = parse_js(src);
        let mem = find_kind(tree.root_node(), "member_expression").expect("mem");
        // `find_kind` returns the first match found via the LIFO stack walk;
        // for `a.b.c`, that's the outermost expression with property `c`.
        let label = receiver_chain_label(mem, src.as_bytes(), None);
        assert_eq!(label, "c");
    }

    #[test]
    fn receiver_chain_label_python_attribute() {
        let src = "os.path.join\n";
        let tree = parse_python(src);
        let attr = find_kind(tree.root_node(), "attribute").expect("attr");
        let label = receiver_chain_label(attr, src.as_bytes(), None);
        assert_eq!(label, "join");
    }

    #[test]
    fn receiver_chain_label_call_with_resolver() {
        // `require('fs').readFile` — when the resolver matches the
        // `require('fs')` call_expression, it returns `"fs"` and that
        // wins over the raw text.
        let src = "require('fs');\n";
        let tree = parse_js(src);
        let call = find_kind(tree.root_node(), "call_expression").expect("call");
        let resolver = |n: Node<'_>, _src: &[u8]| -> Option<&'static str> {
            if n.kind() == "call_expression" {
                Some("fs")
            } else {
                None
            }
        };
        let label = receiver_chain_label(call, src.as_bytes(), Some(&resolver));
        assert_eq!(label, "fs");
        // Without the resolver, the raw call text falls through.
        let label_noresolve = receiver_chain_label(call, src.as_bytes(), None);
        assert_eq!(label_noresolve, "require('fs')");
    }

    // ----- receiver_chain_label_go -----

    #[test]
    fn receiver_chain_label_go_selector() {
        let src = "package m\nfunc f() { exec.Command(\"ls\") }\n";
        let tree = parse_go(src);
        let sel = find_kind(tree.root_node(), "selector_expression").expect("sel");
        let label = receiver_chain_label_go(sel, src.as_bytes());
        assert_eq!(label, "command");
    }
}