apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/parsing/python/expression_utils.py

@@ -0,0 +1,221 @@
+"""CST expression analysis utilities.
+
+Standalone functions for analyzing LibCST expression nodes — detecting
+string interpolation, concatenation, container types, collecting referenced
+variable names, etc.  These are pure functions with no visitor state dependency.
+"""
+
+from __future__ import annotations
+
+import libcst as cst
+
+
+def collect_name_nodes(node: cst.BaseExpression) -> list[str]:
+    """
+    Recursively collect all variable Name nodes from an expression.
+
+    Descends through Call arguments, BinaryOperations, Attributes,
+    Subscripts, f-string interpolations, comparisons, unary ops,
+    ternaries, and container literals to find every referenced variable.
+
+    Excludes keywords like True/False/None and builtin function names
+    when they appear as the func of a Call (those are the transformation,
+    not the source).
+    """
+    results: list[str] = []
+    seen: set[str] = set()
+
+    def _add(name: str) -> None:
+        if name and name not in seen and name not in ("True", "False", "None"):
+            seen.add(name)
+            results.append(name)
+
+    def _walk(expr: cst.BaseExpression) -> None:
+        if isinstance(expr, cst.Name):
+            _add(expr.value)
+
+        elif isinstance(expr, cst.Attribute):
+            root = get_root_name(expr)
+            if root:
+                _add(root)
+
+        elif isinstance(expr, cst.Call):
+            # For x.method(a, b): receiver is a source variable, args too
+            if isinstance(expr.func, cst.Attribute):
+                root = get_root_name(expr.func.value)
+                if root:
+                    _add(root)
+            # Walk call arguments
+            for arg in expr.args:
+                _walk(arg.value)
+
+        elif isinstance(expr, cst.BinaryOperation):
+            _walk(expr.left)
+            _walk(expr.right)
+
+        elif isinstance(expr, cst.UnaryOperation):
+            _walk(expr.expression)
+
+        elif isinstance(expr, cst.BooleanOperation):
+            _walk(expr.left)
+            _walk(expr.right)
+
+        elif isinstance(expr, cst.Comparison):
+            _walk(expr.left)
+            for target in expr.comparisons:
+                _walk(target.comparator)
+
+        elif isinstance(expr, cst.IfExp):
+            _walk(expr.body)
+            _walk(expr.test)
+            _walk(expr.orelse)
+
+        elif isinstance(expr, cst.Subscript):
+            _walk(expr.value)
+
+        elif isinstance(expr, (cst.FormattedString, cst.ConcatenatedString)):
+            walk_fstring_parts(expr, _walk)
+
+        elif isinstance(expr, cst.Tuple):
+            for el in expr.elements:
+                _walk(el.value)
+
+        elif isinstance(expr, (cst.List, cst.Set)):
+            for el in expr.elements:
+                if isinstance(el, (cst.Element, cst.StarredElement)):
+                    _walk(el.value)
+
+        elif isinstance(expr, cst.Dict):
+            for el in expr.elements:
+                if isinstance(el, cst.DictElement):
+                    _walk(el.key)
+                    _walk(el.value)
+                elif isinstance(el, cst.StarredDictElement):
+                    _walk(el.value)
+
+        elif isinstance(expr, (cst.FormattedStringExpression, cst.Await)):
+            _walk(expr.expression)
+
+    _walk(node)
+    return results
+
+
+def get_root_name(node: cst.BaseExpression) -> str | None:
+    """
+    Walk through nested Attribute / Subscript to find the root Name.
+    For ``a.b.c`` returns ``"a"``, for ``items[0].x`` returns ``"items"``.
+    """
+    while True:
+        if isinstance(node, cst.Name):
+            return node.value
+        if isinstance(node, (cst.Attribute, cst.Subscript)):
+            node = node.value
+        elif isinstance(node, cst.Call):
+            node = node.func
+        else:
+            return None
+
+
+def walk_fstring_parts(
+    node: cst.BaseExpression,
+    walker: callable,
+) -> None:
+    """Walk parts of a FormattedString / ConcatenatedString."""
+    if isinstance(node, cst.FormattedString):
+        for part in node.parts:
+            if isinstance(part, cst.FormattedStringExpression):
+                walker(part.expression)
+    elif isinstance(node, cst.ConcatenatedString):
+        walk_fstring_parts(node.left, walker)
+        walk_fstring_parts(node.right, walker)
+
+
+def detect_fstring(value: cst.BaseExpression) -> bool:
+    """Return True if the expression is or contains an f-string."""
+    if isinstance(value, cst.FormattedString):
+        return any(isinstance(p, cst.FormattedStringExpression) for p in value.parts)
+    if isinstance(value, cst.ConcatenatedString):
+        return detect_fstring(value.left) or detect_fstring(value.right)
+    return False
+
+
+def detect_concatenation(value: cst.BaseExpression) -> bool:
+    """Return True if the expression is a string concatenation with +."""
+    if isinstance(value, cst.BinaryOperation) and isinstance(value.operator, cst.Add):
+        left_might_be_str = isinstance(
+            value.left, (cst.SimpleString, cst.FormattedString, cst.ConcatenatedString)
+        ) or detect_concatenation(value.left)
+        right_might_be_str = isinstance(
+            value.right, (cst.SimpleString, cst.FormattedString, cst.ConcatenatedString)
+        ) or detect_concatenation(value.right)
+        if left_might_be_str or right_might_be_str:
+            return True
+        # Also flag any + with a Name operand: "SELECT " + uid
+        if isinstance(value.left, cst.Name) or isinstance(value.right, cst.Name):
+            return True
+    return bool(isinstance(value, cst.ConcatenatedString))
+
+
+def detect_format_call(value: cst.BaseExpression) -> bool:
+    """Return True if the expression uses .format() or % string formatting."""
+    if isinstance(value, cst.Call) and isinstance(value.func, cst.Attribute):
+        if value.func.attr.value == "format":
+            return True
+    if isinstance(value, cst.BinaryOperation) and isinstance(value.operator, cst.Modulo):
+        if isinstance(value.left, (cst.SimpleString, cst.FormattedString, cst.ConcatenatedString)):
+            return True
+    return False
+
+
+def detect_container_type(value: cst.BaseExpression) -> str | None:
+    """Detect if value is a container literal and return its type."""
+    if isinstance(value, cst.List):
+        return "list"
+    if isinstance(value, cst.Tuple):
+        return "tuple"
+    if isinstance(value, cst.Dict):
+        return "dict"
+    if isinstance(value, cst.Set):
+        return "set"
+    return None
+
+
+def detect_method_call(value: cst.BaseExpression) -> bool:
+    """Return True if the expression is a method call on a variable."""
+    if not isinstance(value, cst.Call):
+        return False
+    func = value.func
+    if not isinstance(func, cst.Attribute):
+        return False
+    root = get_root_name(func.value)
+    return root is not None
+
+
+def extract_value_metadata(
+    value: cst.BaseExpression | None,
+) -> tuple[list[str], bool, bool]:
+    """
+    Analyze a value expression and return:
+    (source_variables, is_method_call, is_string_interpolation).
+    """
+    if value is None:
+        return [], False, False
+    source_vars = collect_name_nodes(value)
+    is_method = detect_method_call(value)
+    is_fstr = detect_fstring(value)
+    return source_vars, is_method, is_fstr
+
+
+def is_classvar_annotation(annotation: cst.BaseExpression) -> bool:
+    """Return True if the annotation is ``ClassVar`` or ``ClassVar[...]``."""
+    if isinstance(annotation, cst.Name) and annotation.value == "ClassVar":
+        return True
+    if isinstance(annotation, cst.Subscript):
+        base = annotation.value
+        if isinstance(base, cst.Name) and base.value == "ClassVar":
+            return True
+        if isinstance(base, cst.Attribute):
+            attr = base.attr
+            if isinstance(attr, cst.Name) and attr.value == "ClassVar":
+                return True
+    return False

apisec_code_bolt/parsing/python/extraction_types.py

@@ -0,0 +1,271 @@
+"""Extraction data types for Python code analysis.
+
+Pure data models representing structural elements extracted from Python CST:
+- Function/method definitions
+- Class definitions
+- Import statements
+- Function calls
+- Assignments
+- Decorators
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ...core.types import CodeLocation
+
+
+@dataclass
+class ExtractedDecorator:
+    """A decorator extracted from the CST."""
+
+    name: str
+    full_name: str  # e.g., "app.get" for @app.get(...)
+    arguments: dict[str, Any]
+    positional_args: list[Any]
+    location: CodeLocation
+    raw_source: str | None = None
+
+
+@dataclass
+class ExtractedParameter:
+    """A function parameter extracted from the CST."""
+
+    name: str
+    annotation: str | None = None
+    default: str | None = None
+    is_variadic: bool = False  # *args
+    is_keyword_variadic: bool = False  # **kwargs
+    is_positional_only: bool = False
+    is_keyword_only: bool = False
+
+
+@dataclass
+class ExtractedFunction:
+    """A function or method extracted from the CST."""
+
+    name: str
+    qualified_name: str
+    parameters: list[ExtractedParameter]
+    return_annotation: str | None
+    decorators: list[ExtractedDecorator]
+
+    is_async: bool = False
+    binding: str = "free"  # "instance", "static", or "free"
+
+    docstring: str | None = None
+    body_source: str | None = None  # For complex analysis
+
+    # Location info
+    line: int = 0
+    end_line: int = 0
+    column: int = 0
+
+    # Owner class if this is a method
+    owner_type: str | None = None
+
+    # Local variable names (for data flow)
+    local_variables: list[str] = field(default_factory=list)
+
+    # Control flow information
+    control_flow_info: dict[str, Any] = field(default_factory=dict)
+    has_yield: bool = False
+    has_return: bool = False
+
+    # Return statement analysis
+    return_statements: list[ExtractedReturn] = field(default_factory=list)
+
+
+@dataclass
+class ExtractedReturn:
+    """A return statement extracted from the CST."""
+
+    line: int
+
+    # What is being returned
+    returns_none: bool = False  # return or return None
+    returns_call: bool = False  # return func()
+    returns_variable: bool = False  # return x
+    returns_literal: bool = False  # return "string" or return 42
+    returns_expression: bool = False  # return x + y
+
+    # Details about what's returned
+    call_name: str | None = None  # Name of the called function
+    variable_name: str | None = None  # Name of the variable
+    literal_value: Any = None  # Literal value
+    literal_type: str | None = None  # Type of literal
+    expression_text: str | None = None  # Expression source
+
+    # For comprehensions and lambdas
+    returns_comprehension: bool = False
+    returns_lambda: bool = False
+
+
+@dataclass
+class ExtractedControlFlowBlock:
+    """A control flow structure (if/for/while/try/with)."""
+
+    block_type: str  # "if", "for", "while", "try", "with", "comprehension"
+    start_line: int
+    end_line: int
+
+    # For if blocks
+    has_elif: bool = False
+    has_else: bool = False
+    elif_lines: list[int] = field(default_factory=list)
+    else_line: int | None = None
+
+    # For try blocks
+    except_blocks: list[tuple[int, int]] = field(default_factory=list)  # (start, end) pairs
+    finally_block: tuple[int, int] | None = None
+
+    # For loops
+    has_break: bool = False
+    has_continue: bool = False
+
+    # For with blocks
+    context_expr: str | None = None
+    # All context-manager expressions (supports ``with a, b:``)
+    with_items: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ExtractedClass:
+    """A class extracted from the CST."""
+
+    name: str
+    qualified_name: str
+    bases: list[str]
+    decorators: list[ExtractedDecorator]
+
+    methods: list[ExtractedFunction] = field(default_factory=list)
+    class_variables: list[str] = field(default_factory=list)
+    instance_variables: list[str] = field(default_factory=list)
+
+    docstring: str | None = None
+
+    is_dataclass: bool = False
+    is_pydantic_model: bool = False
+
+    # Pydantic/dataclass fields
+    fields: list[ExtractedField] = field(default_factory=list)
+
+    # Location info
+    line: int = 0
+    end_line: int = 0
+    column: int = 0
+
+
+@dataclass
+class ExtractedField:
+    """A class field (for Pydantic models, dataclasses)."""
+
+    name: str
+    annotation: str | None = None
+    default: str | None = None
+    field_info: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ExtractedImport:
+    """An import statement extracted from the CST."""
+
+    module: str
+    names: list[tuple[str, str | None]]  # (name, alias)
+    is_from_import: bool
+    is_relative: bool = False
+    relative_level: int = 0
+    line: int = 0
+
+
+@dataclass
+class ExtractedCall:
+    """A function call extracted from the CST."""
+
+    callee: str  # Full call expression, e.g., "db.execute"
+    arguments: list[ExtractedArgument]
+
+    # Context
+    line: int = 0
+    column: int = 0
+    end_line: int = 0
+    in_function: str | None = None  # Enclosing function name
+
+    # Receiver info for method calls
+    is_method_call: bool = False
+    receiver: str | None = None
+
+    # Control flow context
+    in_loop: bool = False
+    in_conditional: bool = False
+    in_try: bool = False
+    in_except: bool = False
+    in_finally: bool = False
+    in_with: bool = False
+    in_comprehension: bool = False
+    loop_depth: int = 0
+    conditional_depth: int = 0
+
+
+@dataclass
+class ExtractedArgument:
+    """An argument in a function call."""
+
+    value_source: str  # Source code of the value (required)
+
+    # Optional fields with defaults
+    position: int | None = None
+    keyword: str | None = None
+
+    is_literal: bool = False
+    literal_value: Any = None
+    literal_type: str | None = None
+
+    is_name: bool = False
+    name_value: str | None = None
+
+    is_starred: bool = False
+    is_double_starred: bool = False
+
+    # Argument construction details (language-agnostic)
+    is_string_interpolation: bool = False
+    is_concatenation: bool = False
+    is_format_call: bool = False
+    container_type: str | None = None  # "list", "tuple", "dict", "set"
+    source_variables: list[str] = field(default_factory=list)
+
+    # For call-wrapped arguments: func(int(x)) -> called_function = "int"
+    is_call_result: bool = False
+    called_function: str | None = None
+
+
+@dataclass
+class ExtractedAssignment:
+    """A variable assignment extracted from the CST."""
+
+    target: str
+    value_source: str
+    annotation: str | None = None
+
+    line: int = 0
+    in_function: str | None = None
+
+    # Value type hints
+    is_literal: bool = False
+    is_call: bool = False
+    called_function: str | None = None
+    is_name: bool = False
+    referenced_name: str | None = None
+
+    # Variables in the RHS expression that the target derives from.
+    # For "x = int(y)" → ["y"], for "q = f'{a} {b}'" → ["a", "b"],
+    # for "x = obj.method()" → ["obj"].
+    source_variables: list[str] = field(default_factory=list)
+
+    # True when value is a method call on a variable (y = x.strip())
+    is_method_call: bool = False
+
+    # True when value is a string interpolation (f-string / FormattedString)
+    is_string_interpolation: bool = False