adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/detectors/data_access.py

@@ -0,0 +1,128 @@
+"""Data access / ORM pattern detectors.
+
+Finds SQLAlchemy, Django ORM, Peewee, Tortoise queries.
+"""
+
+from __future__ import annotations
+
+from typing import List, Dict, Any, Optional
+from pathlib import Path
+from tree_sitter import Node, Tree
+
+from adl_drift.detectors.base import BaseDetector
+from adl_drift.utils.types import Pattern, PatternCategory
+from adl_drift.parser.core import PythonParser
+
+
+class DataAccessDetector(BaseDetector):
+    """Detects database access patterns."""
+
+    ORM_PATTERNS = {
+        "sqlalchemy": [
+            "session.query", "Query(", ".filter(", ".all()", ".first()",
+            ".join(", ".add(", ".commit()", ".rollback()",
+        ],
+        "django": [
+            ".objects.filter", ".objects.get", ".objects.all", ".objects.create",
+            ".save(", ".delete(", ".update(", ".aggregate(",
+        ],
+        "peewee": [
+            ".select()", ".where(", ".join(", ".get()", ".create(",
+        ],
+        "tortoise": [
+            ".filter(", ".get(", ".all()", ".create(", ".update(",
+        ],
+    }
+
+    def __init__(self, parser: PythonParser):
+        super().__init__(parser)
+
+    @property
+    def category(self) -> PatternCategory:
+        return PatternCategory.DATA_ACCESS
+
+    def detect(self, tree: Tree, source_bytes: bytes, file_path: Path) -> List[Pattern]:
+        patterns = []
+
+        for node in self._walk(tree.root_node):
+            if node.type == "call":
+                pattern = self._analyze_call(node, source_bytes, file_path)
+                if pattern:
+                    patterns.append(pattern)
+            elif node.type == "attribute":
+                pattern = self._analyze_attribute_chain(node, source_bytes, file_path)
+                if pattern:
+                    patterns.append(pattern)
+
+        return patterns
+
+    def _analyze_call(self, node: Node, source: bytes, path: Path) -> Optional[Pattern]:
+        text = self.parser.node_text(node, source)
+
+        for orm, markers in self.ORM_PATTERNS.items():
+            for marker in markers:
+                if marker in text:
+                    return self._make_pattern(
+                        name=f"{orm}_query",
+                        description=f"{orm.capitalize()} database query: {text[:60]}",
+                        node=node,
+                        file_path=path,
+                        confidence=0.8,
+                        metadata={
+                            "orm": orm,
+                            "operation": marker.strip(".()"),
+                            "query_text": text[:200],
+                        }
+                    )
+
+        func_node = node.child_by_field_name("function")
+        if func_node:
+            func_text = self.parser.node_text(func_node, source)
+            if func_text in {"execute", "executemany", "run"}:
+                args = node.child_by_field_name("arguments")
+                if args:
+                    for arg in args.children:
+                        if arg.type == "string":
+                            arg_text = self.parser.node_text(arg, source).lower()
+                            if any(kw in arg_text for kw in ["select", "insert", "update", "delete"]):
+                                return self._make_pattern(
+                                    name="raw_sql",
+                                    description=f"Raw SQL execution: {func_text}",
+                                    node=node,
+                                    file_path=path,
+                                    confidence=0.9,
+                                    metadata={
+                                        "type": "raw_sql",
+                                        "sql_preview": arg_text[:100],
+                                    }
+                                )
+
+        return None
+
+    def _analyze_attribute_chain(self, node: Node, source: bytes, path: Path) -> Optional[Pattern]:
+        text = self.parser.node_text(node, source)
+
+        if ".objects." in text:
+            parts = text.split(".objects.")
+            if len(parts) >= 2:
+                model = parts[0].split(".")[-1]
+                operation = parts[1].split("(")[0]
+                return self._make_pattern(
+                    name="django_orm_chain",
+                    description=f"Django ORM: {model}.objects.{operation}",
+                    node=node,
+                    file_path=path,
+                    confidence=0.85,
+                    metadata={
+                        "orm": "django",
+                        "model": model,
+                        "operation": operation,
+                    }
+                )
+
+        return None
+
+    def _walk(self, node):
+        yield node
+        for child in node.children:
+            yield from self._walk(child)

package/adl_drift/detectors/decorators.py

@@ -0,0 +1,122 @@
+"""Decorator pattern detectors.
+
+Finds custom decorators, caching decorators, auth decorators, etc.
+"""
+
+from __future__ import annotations
+
+from typing import List, Dict, Any, Set
+from pathlib import Path
+from tree_sitter import Node, Tree
+
+from adl_drift.detectors.base import BaseDetector
+from adl_drift.utils.types import Pattern, PatternCategory
+from adl_drift.parser.core import PythonParser
+
+
+class DecoratorDetector(BaseDetector):
+    """Detects decorator usage patterns."""
+
+    BUILT_IN = {"staticmethod", "classmethod", "property", "abstractmethod", "dataclass"}
+    CACHE_DECORATORS = {"lru_cache", "cache", "cached_property", "memoize"}
+    AUTH_DECORATORS = {"login_required", "permission_required", "requires_auth", "authenticated"}
+
+    def __init__(self, parser: PythonParser):
+        super().__init__(parser)
+
+    @property
+    def category(self) -> PatternCategory:
+        return PatternCategory.DECORATORS
+
+    def detect(self, tree: Tree, source_bytes: bytes, file_path: Path) -> List[Pattern]:
+        patterns = []
+
+        for node in self._walk(tree.root_node):
+            if node.type == "decorator":
+                pattern = self._analyze_decorator(node, source_bytes, file_path)
+                if pattern:
+                    patterns.append(pattern)
+            elif node.type == "function_definition":
+                if self._is_decorator_factory(node, source_bytes):
+                    patterns.append(self._make_pattern(
+                        name="custom_decorator",
+                        description="Custom decorator factory function",
+                        node=node,
+                        file_path=file_path,
+                        confidence=0.8,
+                        metadata={"type": "decorator_factory"}
+                    ))
+
+        return patterns
+
+    def _analyze_decorator(self, node: Node, source: bytes, path: Path) -> Optional[Pattern]:
+        text = self.parser.node_text(node, source).strip()
+        name = self._extract_name(node, source)
+
+        if name in self.BUILT_IN:
+            return self._make_pattern(
+                name=f"builtin_decorator:{name}",
+                description=f"Built-in decorator: @{name}",
+                node=node,
+                file_path=path,
+                confidence=0.99,
+                metadata={"category": "builtin", "decorator": name}
+            )
+        elif name in self.CACHE_DECORATORS:
+            return self._make_pattern(
+                name=f"cache_decorator:{name}",
+                description=f"Caching decorator: @{name}",
+                node=node,
+                file_path=path,
+                confidence=0.95,
+                metadata={"category": "caching", "decorator": name}
+            )
+        elif name in self.AUTH_DECORATORS:
+            return self._make_pattern(
+                name=f"auth_decorator:{name}",
+                description=f"Authentication decorator: @{name}",
+                node=node,
+                file_path=path,
+                confidence=0.9,
+                metadata={"category": "auth", "decorator": name}
+            )
+        else:
+            return self._make_pattern(
+                name=f"custom_decorator:{name}",
+                description=f"Custom decorator: @{name}",
+                node=node,
+                file_path=path,
+                confidence=0.7,
+                metadata={"category": "custom", "decorator": name}
+            )
+
+    def _extract_name(self, node: Node, source: bytes) -> str:
+        for child in node.children:
+            if child.type == "identifier":
+                return self.parser.node_text(child, source)
+            elif child.type == "attribute":
+                attr = child.child_by_field_name("attribute")
+                if attr:
+                    return self.parser.node_text(attr, source)
+            elif child.type == "call":
+                func = child.child_by_field_name("function")
+                if func:
+                    if func.type == "identifier":
+                        return self.parser.node_text(func, source)
+                    elif func.type == "attribute":
+                        attr = func.child_by_field_name("attribute")
+                        if attr:
+                            return self.parser.node_text(attr, source)
+        return "unknown"
+
+    def _is_decorator_factory(self, node: Node, source: bytes) -> bool:
+        body = node.child_by_field_name("body")
+        if not body:
+            return False
+        body_text = self.parser.node_text(body, source)
+        return "def " in body_text and "return" in body_text
+
+    def _walk(self, node):
+        yield node
+        for child in node.children:
+            yield from self._walk(child)

package/adl_drift/detectors/dynamic_patterns.py

@@ -0,0 +1,260 @@
+"""Dynamic dispatch / reflection pattern detector (P2.12).
+
+Flags 8 categories of dynamic code that defeat static analysis:
+  getattr/setattr/delattr with non-literal name args,
+  __getattr__/__getattribute__ definitions (open attribute universe),
+  exec/eval (cross-tagged with SECURITY),
+  importlib.import_module / __import__ calls,
+  metaclass= class kwargs,
+  __init_subclass__ definitions (subclass registries),
+  subscript-call dispatch (d[k]()),
+  decorator bodies that return a new locally-defined class (decorator rebind).
+
+Each Pattern.metadata carries:
+  resolvable: "candidates" (literals available), "partial", or "none"
+  reason: short human-readable explanation for the agent
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from tree_sitter import Node, Tree
+
+from adl_drift.detectors.base import BaseDetector
+from adl_drift.utils.types import Pattern, PatternCategory, SourcePosition
+
+
+class DynamicPatternDetector(BaseDetector):
+    """Detects patterns where static resolution is unreliable or impossible."""
+
+    @property
+    def category(self) -> PatternCategory:
+        return PatternCategory.DYNAMIC
+
+    def detect(self, tree: Tree, source_bytes: bytes, file_path: Path) -> List[Pattern]:
+        patterns: List[Pattern] = []
+        for node in self._walk(tree.root_node):
+            t = node.type
+            if t == "call":
+                patterns.extend(self._check_call(node, source_bytes, file_path))
+            elif t == "subscript":
+                patterns.extend(self._check_subscript_call(node, source_bytes, file_path))
+            elif t == "class_definition":
+                patterns.extend(self._check_class_def(node, source_bytes, file_path))
+            elif t == "function_definition":
+                patterns.extend(self._check_func_def(node, source_bytes, file_path))
+        return patterns
+
+    # ------------------------------------------------------------------ calls
+
+    def _check_call(self, node: Node, source: bytes, file_path: Path) -> List[Pattern]:
+        out: List[Pattern] = []
+        func = node.child_by_field_name("function")
+        if func is None:
+            return out
+        func_text = self.parser.node_text(func, source).strip()
+
+        # getattr / setattr / delattr with non-literal name argument
+        if func_text in ("getattr", "setattr", "delattr"):
+            args = node.child_by_field_name("arguments")
+            name_arg = self._nth_positional_arg(args, 1)  # second positional
+            if name_arg is not None and not self._is_literal_string(name_arg):
+                resolvable = "candidates" if self._is_prefixed_fstring(name_arg, source) else "none"
+                out.append(self._make_pattern(
+                    name=f"dynamic_{func_text}",
+                    description=(
+                        f"{func_text}() with non-literal name — "
+                        "attribute resolution bypasses static analysis"
+                    ),
+                    node=node, file_path=file_path, confidence=0.9,
+                    metadata={
+                        "function": func_text,
+                        "resolvable": resolvable,
+                        "reason": "non-literal attribute name; candidates may be recoverable from f-string prefix",
+                    },
+                ))
+
+        # importlib.import_module / __import__
+        elif func_text in ("importlib.import_module", "__import__"):
+            args = node.child_by_field_name("arguments")
+            mod_arg = self._nth_positional_arg(args, 0)
+            resolvable = "candidates" if (
+                mod_arg is not None and self._is_literal_string(mod_arg)
+            ) else ("candidates" if (
+                mod_arg is not None and self._is_prefixed_fstring(mod_arg, source)
+            ) else "none")
+            out.append(self._make_pattern(
+                name="dynamic_import",
+                description=(
+                    f"{func_text}() — dynamically imported module "
+                    "invisible to import graph"
+                ),
+                node=node, file_path=file_path, confidence=0.85,
+                metadata={
+                    "function": func_text,
+                    "resolvable": resolvable,
+                    "reason": "dynamic import; module may be inferrable from literal prefix",
+                },
+            ))
+
+        # exec / eval (cross-tag: also caught by SecurityDetector with HIGH severity)
+        elif func_text in ("exec", "eval"):
+            args = node.child_by_field_name("arguments")
+            code_arg = self._nth_positional_arg(args, 0)
+            resolvable = "candidates" if (
+                code_arg is not None and self._is_literal_string(code_arg)
+            ) else "none"
+            out.append(self._make_pattern(
+                name="dynamic_exec_eval",
+                description=(
+                    f"{func_text}() — emitted symbols invisible to graph; "
+                    "static analysis confidence reduced"
+                ),
+                node=node, file_path=file_path, confidence=0.8,
+                metadata={
+                    "function": func_text,
+                    "resolvable": resolvable,
+                    "reason": "synthesized symbols not in graph; recoverable when arg is a literal template",
+                },
+            ))
+
+        return out
+
+    # ---------------------------------------------------- subscript-call dispatch
+
+    def _check_subscript_call(self, node: Node, source: bytes, file_path: Path) -> List[Pattern]:
+        """Detect d[k]() — parent of subscript node is a call."""
+        parent = node.parent
+        if parent is None or parent.type != "call":
+            return []
+        func_field = parent.child_by_field_name("function")
+        if func_field is None or func_field != node:
+            return []
+        return [self._make_pattern(
+            name="subscript_dispatch",
+            description=(
+                "subscript-call dispatch d[k]() — target determined at runtime; "
+                "CALLS edges missing for all candidates"
+            ),
+            node=parent, file_path=file_path, confidence=0.8,
+            metadata={
+                "resolvable": "candidates",
+                "reason": "literal dict values may be recoverable as candidate targets",
+            },
+        )]
+
+    # ------------------------------------------------------------ class-level
+
+    def _check_class_def(self, node: Node, source: bytes, file_path: Path) -> List[Pattern]:
+        out: List[Pattern] = []
+
+        # metaclass= keyword argument
+        args_node = node.child_by_field_name("superclasses")
+        if args_node is not None:
+            for child in args_node.children:
+                if child.type == "keyword_argument":
+                    kname = child.child_by_field_name("name")
+                    if kname is not None and self.parser.node_text(kname, source).strip() == "metaclass":
+                        out.append(self._make_pattern(
+                            name="metaclass_class",
+                            description=(
+                                "class uses metaclass= — injected attributes/methods "
+                                "invisible to static graph"
+                            ),
+                            node=node, file_path=file_path, confidence=0.9,
+                            metadata={
+                                "resolvable": "partial",
+                                "reason": "metaclass __new__ may inject literal-keyed namespace entries",
+                            },
+                        ))
+                        break
+
+        return out
+
+    # ----------------------------------------------------------- function-level
+
+    def _check_func_def(self, node: Node, source: bytes, file_path: Path) -> List[Pattern]:
+        out: List[Pattern] = []
+        name_node = node.child_by_field_name("name")
+        if name_node is None:
+            return out
+        name = self.parser.node_text(name_node, source).strip()
+
+        # __getattr__ / __getattribute__ definitions → open attribute universe
+        if name in ("__getattr__", "__getattribute__"):
+            out.append(self._make_pattern(
+                name="open_attr_universe",
+                description=(
+                    f"{name}() defined — attribute reads on instances are "
+                    "unresolvable; impact routed through this method"
+                ),
+                node=node, file_path=file_path, confidence=0.9,
+                metadata={
+                    "function": name,
+                    "resolvable": "none",
+                    "reason": "open attribute universe; unresolved reads should emit DYNAMIC_ATTR edges",
+                },
+            ))
+
+        # __init_subclass__ → subclass registry pattern
+        elif name == "__init_subclass__":
+            out.append(self._make_pattern(
+                name="subclass_registry",
+                description=(
+                    "__init_subclass__ defined — subclasses auto-registered; "
+                    "registry lookup may be recoverable via INHERITS walk"
+                ),
+                node=node, file_path=file_path, confidence=0.85,
+                metadata={
+                    "function": name,
+                    "resolvable": "candidates",
+                    "reason": "INHERITS edges to subclasses exist; kwarg literals identify registry keys",
+                },
+            ))
+
+        return out
+
+    # ----------------------------------------------------------------- helpers
+
+    @staticmethod
+    def _nth_positional_arg(args_node: Optional[Node], n: int) -> Optional[Node]:
+        """Return the n-th positional argument node, skipping *args/**kwargs."""
+        if args_node is None:
+            return None
+        pos = 0
+        for child in args_node.children:
+            if child.type in (",", "(", ")", "*", "**"):
+                continue
+            if child.type in ("keyword_argument", "dictionary_splat_argument",
+                               "list_splat_argument"):
+                continue
+            if pos == n:
+                return child
+            pos += 1
+        return None
+
+    @staticmethod
+    def _is_literal_string(node: Node) -> bool:
+        return node.type in ("string", "concatenated_string")
+
+    @staticmethod
+    def _is_prefixed_fstring(node: Node, source: bytes) -> bool:
+        """True when the node is an f-string with at least one literal prefix."""
+        if node.type not in ("string", "concatenated_string"):
+            return False
+        try:
+            text = source[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+        except Exception:
+            return False
+        return text.startswith(('f"', "f'", 'f"""', "f'''"))
+
+    def _walk(self, node: Node):
+        yield node
+        for child in node.children:
+            yield from self._walk(child)
+
+    @staticmethod
+    def _line_position(line: int) -> SourcePosition:
+        return SourcePosition(line=line, column=0, end_line=line, end_column=0)

package/adl_drift/detectors/errors.py

@@ -0,0 +1,134 @@
+"""Error handling pattern detectors.
+
+Finds try/except blocks, custom exceptions, error propagation patterns.
+"""
+
+from __future__ import annotations
+
+from typing import List, Dict, Any
+from pathlib import Path
+from tree_sitter import Node, Tree
+
+from adl_drift.detectors.base import BaseDetector
+from adl_drift.utils.types import Pattern, PatternCategory
+from adl_drift.parser.core import PythonParser
+
+
+class ErrorPatternDetector(BaseDetector):
+    """Detects error handling patterns."""
+
+    def __init__(self, parser: PythonParser):
+        super().__init__(parser)
+
+    @property
+    def category(self) -> PatternCategory:
+        return PatternCategory.ERRORS
+
+    def detect(self, tree: Tree, source_bytes: bytes, file_path: Path) -> List[Pattern]:
+        patterns = []
+
+        for node in self._walk(tree.root_node):
+            if node.type == "try_statement":
+                patterns.extend(self._analyze_try_block(node, source_bytes, file_path))
+            elif node.type == "raise_statement":
+                patterns.extend(self._analyze_raise(node, source_bytes, file_path))
+            elif node.type == "class_definition":
+                patterns.extend(self._analyze_exception_class(node, source_bytes, file_path))
+
+        return patterns
+
+    def _analyze_try_block(self, node: Node, source: bytes, path: Path) -> List[Pattern]:
+        patterns = []
+
+        for child in node.children:
+            if child.type != "except_clause":
+                continue
+
+            except_text = self.parser.node_text(child, source)
+
+            if "except:" in except_text and "except Exception" not in except_text:
+                patterns.append(self._make_pattern(
+                    name="bare_except",
+                    description="Bare except clause catches KeyboardInterrupt, SystemExit",
+                    node=child,
+                    file_path=path,
+                    confidence=0.85,
+                    metadata={"severity": "warning", "fix": "Use 'except Exception:'"}
+                ))
+            elif "except Exception:" in except_text:
+                patterns.append(self._make_pattern(
+                    name="broad_exception",
+                    description="Catching all exceptions may hide bugs",
+                    node=child,
+                    file_path=path,
+                    confidence=0.7,
+                    metadata={"severity": "info"}
+                ))
+
+            except_body = child.child_by_field_name("body")
+            if except_body:
+                body_text = self.parser.node_text(except_body, source)
+                if "pass" in body_text and len(body_text.strip()) < 10:
+                    patterns.append(self._make_pattern(
+                        name="empty_except",
+                        description="Except block does nothing (pass)",
+                        node=child,
+                        file_path=path,
+                        confidence=0.9,
+                        metadata={"severity": "error"}
+                    ))
+
+        return patterns
+
+    def _analyze_raise(self, node: Node, source: bytes, path: Path) -> List[Pattern]:
+        patterns = []
+        text = self.parser.node_text(node, source)
+
+        if "from" not in text:
+            parent = node.parent
+            while parent:
+                if parent.type == "except_clause":
+                    patterns.append(self._make_pattern(
+                        name="raise_without_from",
+                        description="Re-raising without 'from' loses original traceback context",
+                        node=node,
+                        file_path=path,
+                        confidence=0.6,
+                        metadata={"severity": "info", "fix": "Use 'raise NewError from old_e'"}
+                    ))
+                    break
+                parent = parent.parent
+
+        return patterns
+
+    def _analyze_exception_class(self, node: Node, source: bytes, path: Path) -> List[Pattern]:
+        patterns = []
+
+        bases = node.child_by_field_name("superclasses")
+        if not bases:
+            return patterns
+
+        bases_text = self.parser.node_text(bases, source)
+        if "Exception" in bases_text or "BaseException" in bases_text:
+            name_node = node.child_by_field_name("name")
+            name = self.parser.node_text(name_node, source) if name_node else "<unknown>"
+
+            patterns.append(self._make_pattern(
+                name="custom_exception",
+                description=f"Custom exception class: {name}",
+                node=node,
+                file_path=path,
+                confidence=0.95,
+                metadata={
+                    "exception_name": name,
+                    "bases": bases_text,
+                    "severity": "info",
+                }
+            ))
+
+        return patterns
+
+    def _walk(self, node):
+        yield node
+        for child in node.children:
+            yield from self._walk(child)