@oculum/scanner 1.0.14 → 1.0.15

package/dist/detect/ast-rules/helpers/python-helpers.js

@@ -0,0 +1,935 @@
+"use strict";
+/**
+ * Python AST Analysis Helpers
+ *
+ * Python-specific equivalents of JS/TS helpers.
+ * Kept separate because Python AST nodes are structurally different
+ * (different node types, field names, scoping rules).
+ *
+ * Node type mapping (JS → Python):
+ *   call_expression → call
+ *   member_expression → attribute
+ *   import_statement → import_statement / import_from_statement
+ *   statement_block → block
+ *   catch_clause → except_clause
+ *   string (with backticks) → string (with f-prefix for f-strings)
+ *   template_substitution → interpolation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectPythonImportBindings = collectPythonImportBindings;
+exports.hasPythonImport = hasPythonImport;
+exports.getPythonImportedModules = getPythonImportedModules;
+exports.isPythonImportedFrom = isPythonImportedFrom;
+exports.resolvePythonCallTarget = resolvePythonCallTarget;
+exports.isPythonCallTo = isPythonCallTo;
+exports.getPythonCallArguments = getPythonCallArguments;
+exports.getPythonCallArgument = getPythonCallArgument;
+exports.getPythonKeywordArgument = getPythonKeywordArgument;
+exports.isPythonMethodCallOn = isPythonMethodCallOn;
+exports.getPythonAttributeChain = getPythonAttributeChain;
+exports.collectPythonVariableDeclarations = collectPythonVariableDeclarations;
+exports.collectPythonVariableAliases = collectPythonVariableAliases;
+exports.resolvePythonVariableDefinition = resolvePythonVariableDefinition;
+exports.extractPythonStringValue = extractPythonStringValue;
+exports.getPythonFirstStringArg = getPythonFirstStringArg;
+exports.isPythonFString = isPythonFString;
+exports.getPythonFStringParts = getPythonFStringParts;
+exports.isInsidePythonTryExcept = isInsidePythonTryExcept;
+exports.isInsidePythonExceptClause = isInsidePythonExceptClause;
+exports.getEnclosingPythonBlock = getEnclosingPythonBlock;
+exports.getPythonDecorators = getPythonDecorators;
+exports.hasPythonDecorator = hasPythonDecorator;
+exports.isPythonUserInputExpression = isPythonUserInputExpression;
+exports.isPythonDynamicString = isPythonDynamicString;
+exports.isPythonLLMOutputExpression = isPythonLLMOutputExpression;
+exports.isPyConstantExpression = isPyConstantExpression;
+exports.getPythonDictProperty = getPythonDictProperty;
+exports.classifyPythonMessageDict = classifyPythonMessageDict;
+const ast_1 = require("../../../parse/ast");
+// Cache import bindings per root node to avoid redundant AST traversals
+// when hasPythonImport / getPythonImportedModules / isPythonImportedFrom
+// are called in sequence by the same rule.
+const importBindingsCache = new WeakMap();
+// ============================================================================
+// Import Analysis
+// ============================================================================
+/**
+ * Collect all import bindings from a Python file.
+ *
+ * Handles:
+ *   import os                     → { 'os': { module: 'os', originalName: 'default' } }
+ *   import os.path                → { 'os': { module: 'os.path', originalName: 'default' } }
+ *   from os import path           → { 'path': { module: 'os', originalName: 'path' } }
+ *   from os.path import join      → { 'join': { module: 'os.path', originalName: 'join' } }
+ *   from os import path as p     → { 'p': { module: 'os', originalName: 'path' } }
+ *   from . import utils           → { 'utils': { module: '.', originalName: 'utils' } }
+ */
+function collectPythonImportBindings(root) {
+    const cached = importBindingsCache.get(root);
+    if (cached)
+        return cached;
+    const bindings = new Map();
+    (0, ast_1.walkAST)(root, (node) => {
+        // import os / import os.path
+        if (node.type === "import_statement") {
+            for (const child of node.namedChildren) {
+                if (child.type === "dotted_name") {
+                    const fullModule = child.text;
+                    // Local name is the first identifier (import os.path → local name 'os')
+                    const firstIdent = child.namedChildren[0];
+                    if (firstIdent) {
+                        bindings.set(firstIdent.text, {
+                            module: fullModule,
+                            originalName: "default",
+                        });
+                    }
+                }
+                if (child.type === "aliased_import") {
+                    const dottedName = child.namedChildren.find((c) => c.type === "dotted_name");
+                    const alias = child.namedChildren.find((c) => c.type === "identifier");
+                    if (dottedName && alias) {
+                        bindings.set(alias.text, {
+                            module: dottedName.text,
+                            originalName: "default",
+                        });
+                    }
+                }
+            }
+            return true;
+        }
+        // from X import Y
+        if (node.type === "import_from_statement") {
+            // Resolve module name
+            let moduleName = "";
+            const relImport = node.namedChildren.find((c) => c.type === "relative_import");
+            if (relImport) {
+                // from .foo import bar / from ..package.sub import x
+                const prefix = relImport.descendantsOfType("import_prefix")[0];
+                const submodule = relImport.descendantsOfType("dotted_name")[0];
+                moduleName = (prefix?.text ?? ".") + (submodule ? submodule.text : "");
+            }
+            else {
+                // from os.path import join
+                const modNode = node.namedChildren.find((c) => c.type === "dotted_name");
+                moduleName = modNode?.text ?? "";
+            }
+            // Collect imported names (skip the module dotted_name — it's the first one)
+            let skippedModule = false;
+            for (const child of node.namedChildren) {
+                // Skip the module name (first dotted_name or relative_import)
+                if (!skippedModule &&
+                    (child.type === "dotted_name" || child.type === "relative_import")) {
+                    skippedModule = true;
+                    continue;
+                }
+                if (child.type === "dotted_name") {
+                    // from X import name
+                    bindings.set(child.text, {
+                        module: moduleName,
+                        originalName: child.text,
+                    });
+                }
+                if (child.type === "aliased_import") {
+                    // from X import name as alias
+                    const dottedName = child.namedChildren.find((c) => c.type === "dotted_name");
+                    const alias = child.namedChildren.find((c) => c.type === "identifier");
+                    if (dottedName && alias) {
+                        bindings.set(alias.text, {
+                            module: moduleName,
+                            originalName: dottedName.text,
+                        });
+                    }
+                }
+            }
+            return true;
+        }
+        return false;
+    });
+    importBindingsCache.set(root, bindings);
+    return bindings;
+}
+/**
+ * Quick check: does the Python file import `name` from `module`?
+ */
+function hasPythonImport(root, module, name) {
+    const bindings = collectPythonImportBindings(root);
+    for (const [local, binding] of bindings) {
+        const moduleMatch = typeof module === "string"
+            ? binding.module === module
+            : module.test(binding.module);
+        if (!moduleMatch)
+            continue;
+        if (!name)
+            return true;
+        if (binding.originalName === name || local === name)
+            return true;
+    }
+    return false;
+}
+/**
+ * Get all imported module names (unique set).
+ */
+function getPythonImportedModules(root) {
+    const modules = new Set();
+    const bindings = collectPythonImportBindings(root);
+    for (const binding of bindings.values()) {
+        modules.add(binding.module);
+    }
+    return modules;
+}
+/**
+ * Check if a local name was imported from a module matching a pattern.
+ */
+function isPythonImportedFrom(root, localName, modulePattern) {
+    const bindings = collectPythonImportBindings(root);
+    const binding = bindings.get(localName);
+    if (!binding)
+        return null;
+    if (typeof modulePattern === "string") {
+        return binding.module === modulePattern ? binding.module : null;
+    }
+    return modulePattern.test(binding.module) ? binding.module : null;
+}
+// ============================================================================
+// Call Analysis
+// ============================================================================
+/**
+ * Resolve the target of a Python `call` node.
+ * Python uses 'call' (not 'call_expression') and 'attribute' (not 'member_expression').
+ */
+function resolvePythonCallTarget(node, aliases) {
+    if (node.type !== "call")
+        return null;
+    const fn = node.childForFieldName("function");
+    if (!fn)
+        return null;
+    // Direct call: print(...)
+    if (fn.type === "identifier") {
+        const aliasTarget = aliases?.get(fn.text);
+        if (aliasTarget) {
+            const parts = aliasTarget.split(".");
+            return {
+                type: parts.length > 1 ? "member" : "direct",
+                name: parts[parts.length - 1],
+                object: parts.length > 1 ? parts.slice(0, -1).join(".") : undefined,
+                fullChain: aliasTarget,
+                aliased: true,
+            };
+        }
+        return {
+            type: "direct",
+            name: fn.text,
+            fullChain: fn.text,
+            aliased: false,
+        };
+    }
+    // Member call: obj.method(...) / obj.a.b.method(...)
+    if (fn.type === "attribute") {
+        const attr = fn.childForFieldName("attribute");
+        const obj = fn.childForFieldName("object");
+        if (!attr)
+            return null;
+        return {
+            type: "member",
+            name: attr.text,
+            object: obj?.text,
+            fullChain: fn.text,
+            aliased: false,
+        };
+    }
+    return null;
+}
+/**
+ * Check if a `call` node calls a specific function name.
+ * Handles both direct calls and attribute (member) calls.
+ */
+function isPythonCallTo(node, name) {
+    if (node.type !== "call")
+        return false;
+    const fn = node.childForFieldName("function");
+    if (!fn)
+        return false;
+    // Direct: name(...)
+    if (fn.type === "identifier" && fn.text === name)
+        return true;
+    // Member: obj.name(...)
+    if (fn.type === "attribute") {
+        const attr = fn.childForFieldName("attribute");
+        if (attr?.text === name)
+            return true;
+    }
+    return false;
+}
+/**
+ * Get positional arguments from a Python call node.
+ * Excludes keyword_argument, list_splat, and dictionary_splat.
+ */
+function getPythonCallArguments(node) {
+    if (node.type !== "call")
+        return [];
+    const argList = node.childForFieldName("arguments");
+    if (!argList)
+        return [];
+    return argList.namedChildren.filter((c) => c.type !== "keyword_argument" &&
+        c.type !== "list_splat" &&
+        c.type !== "dictionary_splat");
+}
+/**
+ * Get the Nth positional argument (0-indexed).
+ */
+function getPythonCallArgument(node, index) {
+    const args = getPythonCallArguments(node);
+    return args[index] ?? null;
+}
+/**
+ * Extract a keyword argument value from a Python call.
+ * e.g., foo(model='gpt-4') → getPythonKeywordArgument(node, 'model') → string node
+ */
+function getPythonKeywordArgument(node, keyword) {
+    if (node.type !== "call")
+        return null;
+    const argList = node.childForFieldName("arguments");
+    if (!argList)
+        return null;
+    for (const child of argList.namedChildren) {
+        if (child.type === "keyword_argument") {
+            const nameNode = child.childForFieldName("name");
+            if (nameNode?.text === keyword) {
+                return child.childForFieldName("value") ?? null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Check if a call matches `obj.method(...)` pattern.
+ */
+function isPythonMethodCallOn(node, objectPattern, methodName) {
+    if (node.type !== "call")
+        return false;
+    const fn = node.childForFieldName("function");
+    if (!fn || fn.type !== "attribute")
+        return false;
+    const attr = fn.childForFieldName("attribute");
+    const obj = fn.childForFieldName("object");
+    if (!attr || !obj)
+        return false;
+    const methods = Array.isArray(methodName) ? methodName : [methodName];
+    if (!methods.includes(attr.text))
+        return false;
+    if (typeof objectPattern === "string") {
+        return obj.text === objectPattern;
+    }
+    return objectPattern.test(obj.text);
+}
+/**
+ * Extract the full attribute chain from nested attribute nodes.
+ * e.g., `a.b.c.d` → ['a', 'b', 'c', 'd']
+ */
+function getPythonAttributeChain(node) {
+    const chain = [];
+    function walk(n) {
+        if (n.type === "attribute") {
+            const obj = n.childForFieldName("object");
+            const attr = n.childForFieldName("attribute");
+            if (obj)
+                walk(obj);
+            if (attr)
+                chain.push(attr.text);
+        }
+        else if (n.type === "identifier") {
+            chain.push(n.text);
+        }
+    }
+    walk(node);
+    return chain;
+}
+// ============================================================================
+// Scope & Variable Analysis
+// ============================================================================
+/**
+ * Collect variable declarations/assignments in a Python file.
+ *
+ * Handles:
+ *   x = 1                (assignment)
+ *   x: int = 2           (annotated assignment)
+ *   def foo(x, y=1)      (parameters)
+ *   for x in items       (for variable)
+ *   with open(f) as fh   (with variable)
+ *   except E as e        (except variable)
+ */
+function collectPythonVariableDeclarations(root) {
+    const bindings = new Map();
+    (0, ast_1.walkAST)(root, (node) => {
+        // x = 1 / x: int = 2
+        // TODO: Handle tuple unpacking (a, b = func()) — left side is pattern_list/expression_list
+        if (node.type === "assignment") {
+            const left = node.childForFieldName("left");
+            const right = node.childForFieldName("right");
+            const typeNode = node.childForFieldName("type");
+            if (left?.type === "identifier") {
+                bindings.set(left.text, {
+                    name: left.text,
+                    node,
+                    initValue: right ?? null,
+                    kind: typeNode ? "annotated" : "assignment",
+                });
+            }
+        }
+        // Function parameters
+        if (node.type === "parameters") {
+            const PARAM_TYPES_WITH_IDENT = [
+                "default_parameter",
+                "typed_parameter",
+                "list_splat_pattern",
+                "dictionary_splat_pattern",
+            ];
+            for (const child of node.namedChildren) {
+                if (child.type === "identifier") {
+                    bindings.set(child.text, {
+                        name: child.text,
+                        node: child,
+                        initValue: null,
+                        kind: "parameter",
+                    });
+                }
+                else if (PARAM_TYPES_WITH_IDENT.includes(child.type)) {
+                    const nameNode = child.namedChildren.find((c) => c.type === "identifier");
+                    if (nameNode) {
+                        bindings.set(nameNode.text, {
+                            name: nameNode.text,
+                            node: child,
+                            initValue: child.type === "default_parameter"
+                                ? (child.childForFieldName("value") ?? null)
+                                : null,
+                            kind: "parameter",
+                        });
+                    }
+                }
+            }
+        }
+        // for x in items
+        if (node.type === "for_statement") {
+            const left = node.childForFieldName("left");
+            if (left?.type === "identifier") {
+                bindings.set(left.text, {
+                    name: left.text,
+                    node,
+                    initValue: null,
+                    kind: "for",
+                });
+            }
+        }
+        // with open(f) as fh / except Exception as e
+        if (node.type === "as_pattern") {
+            const kind = node.parent?.type === "with_item"
+                ? "with"
+                : node.parent?.type === "except_clause"
+                    ? "except"
+                    : null;
+            if (kind) {
+                const target = node.namedChildren.find((c) => c.type === "as_pattern_target");
+                const ident = target?.namedChildren.find((c) => c.type === "identifier");
+                if (ident) {
+                    bindings.set(ident.text, {
+                        name: ident.text,
+                        node,
+                        initValue: null,
+                        kind,
+                    });
+                }
+            }
+        }
+        return false;
+    });
+    return bindings;
+}
+/**
+ * Build alias map: tracks `e = eval` style variable aliases.
+ * Only tracks simple identifier-to-identifier or identifier-to-attribute assignments.
+ */
+function collectPythonVariableAliases(root) {
+    const aliases = new Map();
+    (0, ast_1.walkAST)(root, (node) => {
+        if (node.type === "assignment") {
+            const left = node.childForFieldName("left");
+            const right = node.childForFieldName("right");
+            if (left?.type === "identifier" && right) {
+                if (right.type === "identifier" || right.type === "attribute") {
+                    aliases.set(left.text, right.text);
+                }
+            }
+        }
+        return false;
+    });
+    return aliases;
+}
+/**
+ * Resolve a Python variable identifier to its assigned value node.
+ * Walks backward from the reference to find the most recent assignment
+ * where the left side matches the identifier name.
+ *
+ * Example: resolves `user_query` in `execute(text(user_query))` to the
+ * value node of `user_query = f"SELECT * FROM users WHERE username = '{username}'"`
+ */
+function resolvePythonVariableDefinition(fromNode, name) {
+    // Walk the enclosing function or module to find assignments
+    let searchRoot = fromNode.tree.rootNode;
+    let current = fromNode.parent;
+    while (current) {
+        if (current.type === "function_definition" || current.type === "module") {
+            searchRoot = current;
+            break;
+        }
+        current = current.parent;
+    }
+    let lastAssignment = null;
+    (0, ast_1.walkAST)(searchRoot, (node) => {
+        if (node.type === "assignment" &&
+            node.startPosition.row < fromNode.startPosition.row) {
+            const left = node.childForFieldName("left");
+            const right = node.childForFieldName("right");
+            if (left?.type === "identifier" && left.text === name && right) {
+                lastAssignment = right;
+            }
+        }
+        return false;
+    });
+    return lastAssignment;
+}
+// ============================================================================
+// String Analysis
+// ============================================================================
+/**
+ * Extract the string value from a Python string node.
+ * Handles single, double, triple-quoted strings.
+ * Returns the content text (without quotes/prefix).
+ */
+function extractPythonStringValue(node) {
+    if (node.type !== "string")
+        return null;
+    // Collect string_content children and join them
+    const parts = [];
+    for (const child of node.namedChildren) {
+        if (child.type === "string_content") {
+            parts.push(child.text);
+        }
+    }
+    if (parts.length > 0)
+        return parts.join("");
+    // Fallback: strip quotes manually
+    const text = node.text;
+    // Triple-quoted
+    for (const prefix of [
+        '"""',
+        "'''",
+        'f"""',
+        "f'''",
+        'b"""',
+        "b'''",
+        'r"""',
+        "r'''",
+    ]) {
+        if (text.startsWith(prefix)) {
+            const suffix = prefix.slice(-3);
+            if (text.endsWith(suffix)) {
+                return text.slice(prefix.length, -suffix.length);
+            }
+        }
+    }
+    // Single-quoted
+    for (const prefix of ['"', "'", 'f"', "f'", 'b"', "b'", 'r"', "r'"]) {
+        if (text.startsWith(prefix)) {
+            const quote = prefix.slice(-1);
+            if (text.endsWith(quote)) {
+                return text.slice(prefix.length, -1);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Get the first positional string argument from a Python call.
+ */
+function getPythonFirstStringArg(callNode) {
+    const firstArg = getPythonCallArgument(callNode, 0);
+    if (!firstArg)
+        return null;
+    return extractPythonStringValue(firstArg);
+}
+/**
+ * Check if a Python string node is an f-string.
+ * In tree-sitter-python, f-strings are `string` nodes whose string_start begins with 'f' or 'F'.
+ */
+function isPythonFString(node) {
+    if (node.type !== "string")
+        return false;
+    const start = node.children.find((c) => c.type === "string_start");
+    if (!start)
+        return false;
+    return start.text.startsWith("f") || start.text.startsWith("F");
+}
+/**
+ * Get the static and dynamic parts of an f-string.
+ */
+function getPythonFStringParts(node) {
+    const staticParts = [];
+    const dynamicParts = [];
+    if (node.type !== "string")
+        return { staticParts, dynamicParts };
+    for (const child of node.namedChildren) {
+        if (child.type === "string_content") {
+            staticParts.push(child.text);
+        }
+        else if (child.type === "interpolation") {
+            dynamicParts.push(child);
+        }
+    }
+    return { staticParts, dynamicParts };
+}
+// ============================================================================
+// Control Flow
+// ============================================================================
+/**
+ * Check if a node is inside a Python try block (not except/finally).
+ */
+function isInsidePythonTryExcept(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === "try_statement") {
+            // Verify node is in the try body, not except/finally
+            const tryBody = current.childForFieldName("body");
+            if (tryBody && isDescendantOf(node, tryBody))
+                return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Check if a node is inside an except clause.
+ */
+function isInsidePythonExceptClause(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === "except_clause")
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Get the nearest enclosing Python block node.
+ */
+function getEnclosingPythonBlock(node) {
+    let current = node.parent;
+    while (current) {
+        if (current.type === "block")
+            return current;
+        current = current.parent;
+    }
+    return null;
+}
+// ============================================================================
+// Decorator Detection
+// ============================================================================
+/**
+ * Get decorator names for a function_definition or class_definition.
+ * Looks at the parent decorated_definition node for decorator children.
+ *
+ * @app.route('/api') → 'app.route'
+ * @login_required → 'login_required'
+ * @staticmethod → 'staticmethod'
+ */
+function getPythonDecorators(node) {
+    // The decorated_definition wraps decorators + the actual definition
+    const parent = node.parent;
+    if (parent?.type !== "decorated_definition")
+        return [];
+    const decorators = [];
+    for (const child of parent.namedChildren) {
+        if (child.type !== "decorator")
+            continue;
+        // Decorator can contain an identifier or a call
+        for (const dChild of child.namedChildren) {
+            if (dChild.type === "identifier") {
+                decorators.push(dChild.text);
+            }
+            else if (dChild.type === "call") {
+                const fn = dChild.childForFieldName("function");
+                if (fn)
+                    decorators.push(fn.text);
+            }
+            else if (dChild.type === "attribute") {
+                decorators.push(dChild.text);
+            }
+        }
+    }
+    return decorators;
+}
+/**
+ * Check if a function_definition has a specific decorator (exact or regex).
+ */
+function hasPythonDecorator(node, pattern) {
+    const decorators = getPythonDecorators(node);
+    for (const dec of decorators) {
+        if (typeof pattern === "string") {
+            if (dec === pattern)
+                return true;
+        }
+        else {
+            if (pattern.test(dec))
+                return true;
+        }
+    }
+    return false;
+}
+// ============================================================================
+// User Input Detection (Python)
+// ============================================================================
+/** Known Python user input attribute paths */
+const PYTHON_USER_INPUT_PATTERNS = [
+    // Flask (including common aliases like flask_request, http_request)
+    { object: /^(?:flask_)?request$/, property: "form" },
+    { object: /^(?:flask_)?request$/, property: "args" },
+    { object: /^(?:flask_)?request$/, property: "json" },
+    { object: /^(?:flask_)?request$/, property: "data" },
+    { object: /^(?:flask_)?request$/, property: "files" },
+    { object: /^(?:flask_)?request$/, property: "values" },
+    { object: /^(?:flask_)?request$/, property: "cookies" },
+    { object: /^(?:flask_)?request$/, property: "headers" },
+    // Django (including common aliases like django_request, http_request)
+    { object: /^(?:django_|http_)?request$/, property: "GET" },
+    { object: /^(?:django_|http_)?request$/, property: "POST" },
+    { object: /^(?:django_|http_)?request$/, property: "body" },
+    { object: /^(?:django_|http_)?request$/, property: "FILES" },
+    { object: /^(?:django_|http_)?request$/, property: "data" },
+    // General
+    { object: /^sys$/, property: "argv" },
+    { object: /^os$/, property: "environ" },
+];
+/**
+ * Check if a Python node accesses user input.
+ *
+ * Handles:
+ *   request.form, request.args, request.json, request.data, request.GET, etc.
+ *   sys.argv, os.environ
+ *   request.form['key'], request.args.get('key')
+ *   input()
+ */
+function isPythonUserInputExpression(node) {
+    // input() builtin
+    if (node.type === "call") {
+        const fn = node.childForFieldName("function");
+        if (fn?.type === "identifier" && fn.text === "input")
+            return true;
+        // request.get_json()
+        if (fn?.type === "attribute") {
+            const obj = fn.childForFieldName("object");
+            const attr = fn.childForFieldName("attribute");
+            if (/^(?:flask_|http_)?request$/.test(obj?.text ?? "") &&
+                attr?.text === "get_json")
+                return true;
+            // Method call on user input source: request.form.get('key'), request.args.get('q')
+            if (obj && isPythonUserInputExpression(obj))
+                return true;
+        }
+    }
+    // attribute access: request.form, sys.argv, etc.
+    if (node.type === "attribute") {
+        const obj = node.childForFieldName("object");
+        const attr = node.childForFieldName("attribute");
+        if (obj && attr) {
+            for (const pattern of PYTHON_USER_INPUT_PATTERNS) {
+                const objMatch = pattern.object.test(obj.text);
+                const propMatch = typeof pattern.property === "string"
+                    ? attr.text === pattern.property
+                    : pattern.property.test(attr.text);
+                if (objMatch && propMatch)
+                    return true;
+            }
+            // Recursive: request.form.get('key') → check object chain
+            if (isPythonUserInputExpression(obj))
+                return true;
+        }
+    }
+    // subscript: request.form['key'], request.args['q']
+    if (node.type === "subscript") {
+        const obj = node.childForFieldName("value");
+        if (obj && isPythonUserInputExpression(obj))
+            return true;
+    }
+    return false;
+}
+// ============================================================================
+// Dynamic String Detection (Python)
+// ============================================================================
+/**
+ * Check if a Python expression contains dynamic string content.
+ *
+ * Returns true for:
+ *   - f-strings with interpolation: f"Hello {name}"
+ *   - .format() calls: "Hello {}".format(name)
+ *   - % formatting: "Hello %s" % name
+ *   - String concatenation with non-literals: "Hello " + name
+ */
+function isPythonDynamicString(node) {
+    // f-string with interpolation
+    if (node.type === "string" && isPythonFString(node)) {
+        return node.namedChildren.some((c) => c.type === "interpolation");
+    }
+    // .format() call: "...".format(...)
+    if (node.type === "call") {
+        const fn = node.childForFieldName("function");
+        if (fn?.type === "attribute") {
+            const attr = fn.childForFieldName("attribute");
+            if (attr?.text === "format") {
+                const obj = fn.childForFieldName("object");
+                if (obj?.type === "string")
+                    return true;
+            }
+        }
+    }
+    // % formatting: "..." % (name,) or "..." % name
+    if (node.type === "binary_operator") {
+        const opNode = node.children.find((c) => c.type === "%");
+        if (opNode) {
+            const left = node.childForFieldName("left");
+            if (left?.type === "string")
+                return true;
+        }
+    }
+    // String concatenation with non-literal
+    if (node.type === "binary_operator") {
+        const opNode = node.children.find((c) => c.type === "+");
+        if (opNode) {
+            const left = node.childForFieldName("left");
+            const right = node.childForFieldName("right");
+            if (left && right) {
+                const leftLiteral = left.type === "string" ||
+                    left.type === "integer" ||
+                    left.type === "float";
+                const rightLiteral = right.type === "string" ||
+                    right.type === "integer" ||
+                    right.type === "float";
+                if (!leftLiteral || !rightLiteral)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// ============================================================================
+// LLM Output Detection (Python)
+// ============================================================================
+/** Patterns that indicate LLM API response content in Python */
+const PYTHON_LLM_OUTPUT_PATTERNS = [
+    /response\.choices\[?\d*\]?\.message\.content/,
+    /completion\.choices\[?\d*\]?\.message\.content/,
+    /result\.choices\[?\d*\]?\.message\.content/,
+    /response\.content\[?\d*\]?\.text/, // Anthropic SDK
+    /message\.content/,
+    /response\.text/,
+    /result\.text/,
+    /result\.content/,
+    /response\.output_text/,
+    /result\[["']output["']\]/,
+    /response\[["']text["']\]/,
+    /response\.response/, // LlamaIndex
+    /response\.source_nodes/, // LlamaIndex
+    /completion\.text/, // litellm
+];
+/**
+ * Check if a Python node accesses LLM output content.
+ *
+ * Handles:
+ *   response.choices[0].message.content (OpenAI)
+ *   response.content[0].text (Anthropic)
+ *   result.content, response.text
+ *   result["output"], response["text"]
+ */
+function isPythonLLMOutputExpression(node) {
+    if (node.type !== "attribute" && node.type !== "subscript") {
+        return false;
+    }
+    const fullText = node.text;
+    return PYTHON_LLM_OUTPUT_PATTERNS.some((p) => p.test(fullText));
+}
+// ============================================================================
+// Dictionary Analysis (for LLM message dict classification)
+// ============================================================================
+/**
+ * Check if a Python AST node is a constant expression.
+ * Used to skip static/hardcoded values when classifying LLM sinks.
+ */
+function isPyConstantExpression(node) {
+    if (node.type === "string" && !isPythonFString(node))
+        return true;
+    if (node.type === "integer" || node.type === "float" || node.type === "none")
+        return true;
+    if (node.type === "true" || node.type === "false")
+        return true;
+    if (node.type === "concatenated_string") {
+        return node.namedChildren.every((c) => c.type === "string" && !isPythonFString(c));
+    }
+    return false;
+}
+/**
+ * Extract a value from a Python dictionary literal by key.
+ * Handles both string keys {"role": "system"} and identifier keys {role: "system"}.
+ */
+function getPythonDictProperty(node, key) {
+    if (node.type !== "dictionary")
+        return null;
+    for (const child of node.namedChildren) {
+        if (child.type !== "pair")
+            continue;
+        const keyNode = child.childForFieldName("key");
+        if (!keyNode)
+            continue;
+        if (keyNode.type === "string") {
+            const keyText = extractPythonStringValue(keyNode);
+            if (keyText === key)
+                return child.childForFieldName("value") ?? null;
+        }
+        if (keyNode.type === "identifier" && keyNode.text === key) {
+            return child.childForFieldName("value") ?? null;
+        }
+    }
+    return null;
+}
+/**
+ * Classify a Python message dictionary as system_prompt or prompt_construction.
+ * Examines {"role": "system"|"user", "content": <dynamic>} patterns.
+ * Returns null if content is static or missing.
+ */
+function classifyPythonMessageDict(dictNode) {
+    if (dictNode.type !== "dictionary")
+        return null;
+    const contentValue = getPythonDictProperty(dictNode, "content");
+    if (!contentValue || isPyConstantExpression(contentValue))
+        return null;
+    const roleValue = getPythonDictProperty(dictNode, "role");
+    if (roleValue) {
+        const roleText = extractPythonStringValue(roleValue);
+        if (roleText === "system")
+            return "system_prompt";
+        // User input in user/assistant role is expected — not a prompt injection vector
+        if (roleText === "user" || roleText === "assistant")
+            return null;
+    }
+    return "prompt_construction";
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+function isDescendantOf(node, ancestor) {
+    let current = node;
+    while (current) {
+        if (current.id === ancestor.id)
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+//# sourceMappingURL=python-helpers.js.map