python-oop-analyzer 0.1.0__py3-none-any.whl

oop_analyzer/rules/encapsulation.py

@@ -0,0 +1,291 @@
+"""
+Encapsulation Rule - Tell Don't Ask principle.
+
+This rule detects violations of encapsulation where objects are accessed
+directly through their properties instead of through methods.
+
+In OOP, we should "tell" objects what to do, not "ask" them for data
+and then make decisions based on that data.
+"""
+
+import ast
+from typing import Any
+
+from .base import BaseRule, RuleResult, RuleViolation
+
+
+class EncapsulationRule(BaseRule):
+    """
+    Detects direct property access on objects (tell don't ask violations).
+
+    Violations include:
+    - Accessing object attributes directly: obj.property
+    - Especially when followed by operations on that property
+    - Chained attribute access: obj.prop1.prop2
+
+    Exceptions:
+    - Method calls: obj.method() is fine
+    - Self access within a class: self.x is often necessary
+    - Module-level constants: CONSTANT access
+    - Module attribute access: json.JSONEncoder, redis.Redis (normal Python usage)
+    - Named tuple / dataclass field access (configurable)
+    """
+
+    name = "encapsulation"
+    description = "Check for direct property access (tell don't ask)"
+    severity = "warning"
+
+    def __init__(self, options: dict[str, Any] | None = None):
+        super().__init__(options)
+        self.allow_self_access = self.options.get("allow_self_access", True)
+        self.allow_private_access = self.options.get("allow_private_access", False)
+        self.allow_dunder_access = self.options.get("allow_dunder_access", True)
+        self.max_chain_length = self.options.get("max_chain_length", 1)
+        self.warn_dependency_access = self.options.get("warn_dependency_access", True)
+
+    def analyze(
+        self,
+        tree: ast.Module,
+        source: str,
+        file_path: str,
+    ) -> RuleResult:
+        """Analyze the AST for encapsulation violations."""
+        violations: list[RuleViolation] = []
+        visitor = EncapsulationVisitor(
+            file_path=file_path,
+            source=source,
+            allow_self_access=self.allow_self_access,
+            allow_private_access=self.allow_private_access,
+            allow_dunder_access=self.allow_dunder_access,
+            max_chain_length=self.max_chain_length,
+            warn_dependency_access=self.warn_dependency_access,
+        )
+        visitor.visit(tree)
+        violations = visitor.violations
+
+        return RuleResult(
+            rule_name=self.name,
+            violations=violations,
+            summary={
+                "total_violations": len(violations),
+                "files_analyzed": 1,
+                "module_access_skipped": visitor.module_access_skipped,
+            },
+        )
+
+
+class EncapsulationVisitor(ast.NodeVisitor):
+    """AST visitor that detects encapsulation violations."""
+
+    def __init__(
+        self,
+        file_path: str,
+        source: str,
+        allow_self_access: bool = True,
+        allow_private_access: bool = False,
+        allow_dunder_access: bool = True,
+        max_chain_length: int = 1,
+        warn_dependency_access: bool = True,
+    ):
+        self.file_path = file_path
+        self.source = source
+        self.allow_self_access = allow_self_access
+        self.allow_private_access = allow_private_access
+        self.allow_dunder_access = allow_dunder_access
+        self.max_chain_length = max_chain_length
+        self.warn_dependency_access = warn_dependency_access
+        self.violations: list[RuleViolation] = []
+        self._in_class = False
+        self._current_class: str | None = None
+        self._call_targets: set[int] = set()  # IDs of nodes that are call targets
+        self._imported_modules: set[str] = set()  # Names of imported modules
+        self._class_bases: set[int] = set()  # IDs of nodes used as class bases
+        self.module_access_skipped = 0
+
+    def visit_Import(self, node: ast.Import) -> None:
+        """Track imported module names."""
+        for alias in node.names:
+            # Use the alias if provided, otherwise the module name
+            name = alias.asname if alias.asname else alias.name.split(".")[0]
+            self._imported_modules.add(name)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        """Track imported names from modules."""
+        if node.module:
+            # Track the module itself if imported with alias
+            for alias in node.names:
+                if alias.asname:
+                    self._imported_modules.add(alias.asname)
+                else:
+                    self._imported_modules.add(alias.name)
+        self.generic_visit(node)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Track when we're inside a class definition."""
+        # Mark base class nodes to skip them (e.g., json.JSONEncoder)
+        for base in node.bases:
+            self._mark_as_class_base(base)
+
+        old_in_class = self._in_class
+        old_class = self._current_class
+        self._in_class = True
+        self._current_class = node.name
+        self.generic_visit(node)
+        self._in_class = old_in_class
+        self._current_class = old_class
+
+    def _mark_as_class_base(self, node: ast.expr) -> None:
+        """Recursively mark nodes used as class bases."""
+        self._class_bases.add(id(node))
+        if isinstance(node, ast.Attribute):
+            self._class_bases.add(id(node.value))
+            self._mark_as_class_base(node.value)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        """Mark call targets so we don't flag method calls as violations."""
+        if isinstance(node.func, ast.Attribute):
+            self._call_targets.add(id(node.func))
+        self.generic_visit(node)
+
+    def visit_Attribute(self, node: ast.Attribute) -> None:
+        """Check attribute access for encapsulation violations."""
+        # Skip if this is a method call (the attribute is the target of a Call)
+        if id(node) in self._call_targets:
+            self.generic_visit(node)
+            return
+
+        # Skip if this is a class base (e.g., class Foo(json.JSONEncoder))
+        if id(node) in self._class_bases:
+            self.module_access_skipped += 1
+            self.generic_visit(node)
+            return
+
+        # Get the chain of attribute access
+        chain = self._get_attribute_chain(node)
+
+        if not chain:
+            self.generic_visit(node)
+            return
+
+        base_name = chain[0]
+        attr_names = chain[1:]
+
+        # Skip self/cls access if allowed
+        if self.allow_self_access and base_name in ("self", "cls"):
+            self.generic_visit(node)
+            return
+
+        # Skip module attribute access (e.g., json.JSONEncoder, redis.Redis)
+        # This is normal Python module usage, not an encapsulation violation
+        if base_name in self._imported_modules:
+            # Check if accessing a class/constant from a module (PascalCase or UPPER_CASE)
+            if len(attr_names) == 1:
+                attr = attr_names[0]
+                # PascalCase (class) or UPPER_CASE (constant)
+                if attr[0].isupper():
+                    self.module_access_skipped += 1
+                    self.generic_visit(node)
+                    return
+
+        # Skip dunder attributes if allowed
+        if self.allow_dunder_access:
+            if any(attr.startswith("__") and attr.endswith("__") for attr in attr_names):
+                self.generic_visit(node)
+                return
+
+        # Skip private attributes if allowed
+        if self.allow_private_access and any(attr.startswith("_") for attr in attr_names):
+            self.generic_visit(node)
+            return
+
+        # Check for violations
+        if len(attr_names) > 0:
+            # Direct property access detected
+            violation = self._create_violation(node, base_name, attr_names)
+            if violation:
+                self.violations.append(violation)
+
+        self.generic_visit(node)
+
+    def _get_attribute_chain(self, node: ast.Attribute) -> list[str]:
+        """
+        Get the full chain of attribute access.
+
+        For `obj.prop1.prop2`, returns ["obj", "prop1", "prop2"]
+        """
+        chain: list[str] = []
+        current: ast.expr = node
+
+        while isinstance(current, ast.Attribute):
+            chain.append(current.attr)
+            current = current.value
+
+        if isinstance(current, ast.Name):
+            chain.append(current.id)
+        else:
+            # Complex expression, can't determine base
+            return []
+
+        chain.reverse()
+        return chain
+
+    def _create_violation(
+        self,
+        node: ast.Attribute,
+        base_name: str,
+        attr_names: list[str],
+    ) -> RuleViolation | None:
+        """Create a violation for direct property access."""
+        # Skip module-level access patterns (all caps = constants)
+        if all(c.isupper() or c == "_" for c in attr_names[-1]):
+            return None
+
+        # Skip common module access patterns
+        if base_name in ("os", "sys", "math", "typing", "collections", "functools"):
+            return None
+
+        full_access = f"{base_name}.{'.'.join(attr_names)}"
+
+        # Check chain length
+        if len(attr_names) > self.max_chain_length:
+            message = (
+                f"Long attribute chain detected: '{full_access}'. "
+                f"This violates the Law of Demeter. Consider using delegation."
+            )
+            suggestion = (
+                f"Instead of accessing '{full_access}', consider adding a method "
+                f"to '{base_name}' that encapsulates this behavior."
+            )
+        else:
+            message = (
+                f"Direct property access: '{full_access}'. "
+                f"Consider using a method instead (Tell Don't Ask)."
+            )
+            suggestion = (
+                f"Instead of accessing '{base_name}.{attr_names[0]}', "
+                f"consider telling '{base_name}' what to do with a method call."
+            )
+
+        return RuleViolation(
+            rule_name="encapsulation",
+            message=message,
+            file_path=self.file_path,
+            line=node.lineno,
+            column=node.col_offset,
+            severity="warning",
+            suggestion=suggestion,
+            code_snippet=self._get_source_line(node.lineno),
+            metadata={
+                "base_object": base_name,
+                "accessed_attributes": attr_names,
+                "chain_length": len(attr_names),
+            },
+        )
+
+    def _get_source_line(self, line_number: int) -> str:
+        """Get a specific line from the source code."""
+        lines = self.source.splitlines()
+        if 1 <= line_number <= len(lines):
+            return lines[line_number - 1].strip()
+        return ""

oop_analyzer/rules/functions_to_objects.py

@@ -0,0 +1,331 @@
+"""
+Functions to Objects Rule.
+
+This rule detects standalone functions that could be better represented
+as objects/classes, following OOP principles.
+"""
+
+import ast
+from typing import Any
+
+from .base import BaseRule, RuleResult, RuleViolation
+
+
+class FunctionsToObjectsRule(BaseRule):
+    """
+    Detects functions that could be replaced by objects.
+
+    Patterns detected:
+    - Functions with many parameters (could be a class with attributes)
+    - Functions that operate on the same data repeatedly (could be methods)
+    - Groups of related functions (could be a class)
+    - Functions with complex state management (could be objects)
+    - Functions returning dictionaries that could be objects
+    """
+
+    name = "functions_to_objects"
+    description = "Detect functions that could be objects"
+    severity = "info"
+
+    def __init__(self, options: dict[str, Any] | None = None):
+        super().__init__(options)
+        self.max_params = self.options.get("max_params", 4)
+        self.check_dict_returns = self.options.get("check_dict_returns", True)
+        self.check_related_functions = self.options.get("check_related_functions", True)
+
+    def analyze(
+        self,
+        tree: ast.Module,
+        source: str,
+        file_path: str,
+    ) -> RuleResult:
+        """Analyze the AST for functions that could be objects."""
+        visitor = FunctionVisitor(
+            file_path=file_path,
+            source=source,
+            max_params=self.max_params,
+            check_dict_returns=self.check_dict_returns,
+        )
+        visitor.visit(tree)
+
+        violations = visitor.violations.copy()
+
+        # Check for related functions (functions with similar prefixes/suffixes)
+        if self.check_related_functions:
+            related_violations = self._check_related_functions(
+                visitor.function_info,
+                file_path,
+                source,
+            )
+            violations.extend(related_violations)
+
+        return RuleResult(
+            rule_name=self.name,
+            violations=violations,
+            summary={
+                "total_functions": len(visitor.function_info),
+                "functions_with_many_params": visitor.many_params_count,
+                "functions_returning_dicts": visitor.dict_return_count,
+                "related_function_groups": len(self._find_function_groups(visitor.function_info)),
+            },
+            metadata={
+                "functions": visitor.function_info,
+                "function_groups": self._find_function_groups(visitor.function_info),
+            },
+        )
+
+    def _check_related_functions(
+        self,
+        function_info: list[dict[str, Any]],
+        file_path: str,
+        source: str,
+    ) -> list[RuleViolation]:
+        """Check for groups of related functions that could be a class."""
+        violations: list[RuleViolation] = []
+        groups = self._find_function_groups(function_info)
+
+        for prefix, functions in groups.items():
+            if len(functions) >= 3:
+                func_names = [f["name"] for f in functions]
+                first_line = min(f["line"] for f in functions)
+
+                violations.append(
+                    RuleViolation(
+                        rule_name="functions_to_objects",
+                        message=(
+                            f"Found {len(functions)} related functions with prefix '{prefix}_': "
+                            f"{', '.join(func_names[:5])}{'...' if len(func_names) > 5 else ''}. "
+                            f"Consider grouping into a class."
+                        ),
+                        file_path=file_path,
+                        line=first_line,
+                        column=0,
+                        severity="info",
+                        suggestion=(
+                            f"These functions appear related. Consider creating a class "
+                            f"'{prefix.title().replace('_', '')}' with these as methods."
+                        ),
+                        metadata={
+                            "pattern": "related_functions",
+                            "prefix": prefix,
+                            "functions": func_names,
+                        },
+                    )
+                )
+
+        return violations
+
+    def _find_function_groups(
+        self,
+        function_info: list[dict[str, Any]],
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Find groups of functions with common prefixes."""
+        from collections import defaultdict
+
+        groups: dict[str, list[dict[str, Any]]] = defaultdict(list)
+
+        for func in function_info:
+            name = func["name"]
+            # Skip private/dunder functions
+            if name.startswith("_"):
+                continue
+
+            # Extract prefix (first word before underscore)
+            parts = name.split("_")
+            if len(parts) >= 2:
+                prefix = parts[0]
+                if len(prefix) >= 3:  # Meaningful prefix
+                    groups[prefix].append(func)
+
+        # Filter to groups with multiple functions
+        return {k: v for k, v in groups.items() if len(v) >= 2}
+
+
+class FunctionVisitor(ast.NodeVisitor):
+    """AST visitor that analyzes functions."""
+
+    def __init__(
+        self,
+        file_path: str,
+        source: str,
+        max_params: int = 4,
+        check_dict_returns: bool = True,
+    ):
+        self.file_path = file_path
+        self.source = source
+        self.max_params = max_params
+        self.check_dict_returns = check_dict_returns
+
+        self.violations: list[RuleViolation] = []
+        self.function_info: list[dict[str, Any]] = []
+        self.many_params_count = 0
+        self.dict_return_count = 0
+
+        self._in_class = False
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Track when inside a class (skip methods)."""
+        old_in_class = self._in_class
+        self._in_class = True
+        self.generic_visit(node)
+        self._in_class = old_in_class
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Analyze function definitions."""
+        # Skip methods (inside classes)
+        if self._in_class:
+            self.generic_visit(node)
+            return
+
+        # Skip private/dunder functions for some checks
+        is_private = node.name.startswith("_")
+
+        # Count parameters
+        num_params = self._count_params(node)
+
+        # Check for dict returns
+        returns_dict = self._returns_dict(node) if self.check_dict_returns else False
+
+        # Store function info
+        self.function_info.append(
+            {
+                "name": node.name,
+                "line": node.lineno,
+                "params": num_params,
+                "returns_dict": returns_dict,
+                "is_private": is_private,
+            }
+        )
+
+        # Check for too many parameters
+        if num_params > self.max_params and not is_private:
+            self.many_params_count += 1
+            self._add_many_params_violation(node, num_params)
+
+        # Check for dict returns
+        if returns_dict and not is_private:
+            self.dict_return_count += 1
+            self._add_dict_return_violation(node)
+
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        """Handle async functions same as regular functions."""
+        if self._in_class:
+            self.generic_visit(node)
+            return
+
+        is_private = node.name.startswith("_")
+        num_params = self._count_params(node)
+        returns_dict = self._returns_dict(node) if self.check_dict_returns else False
+
+        self.function_info.append(
+            {
+                "name": node.name,
+                "line": node.lineno,
+                "params": num_params,
+                "returns_dict": returns_dict,
+                "is_private": is_private,
+                "is_async": True,
+            }
+        )
+
+        if num_params > self.max_params and not is_private:
+            self.many_params_count += 1
+            self._add_many_params_violation(node, num_params)
+
+        if returns_dict and not is_private:
+            self.dict_return_count += 1
+            self._add_dict_return_violation(node)
+
+        self.generic_visit(node)
+
+    def _count_params(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> int:
+        """Count the number of parameters in a function."""
+        args = node.args
+        count = len(args.args) + len(args.kwonlyargs)
+        if args.vararg:
+            count += 1
+        if args.kwarg:
+            count += 1
+        return count
+
+    def _returns_dict(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+        """Check if function returns a dictionary literal."""
+        for child in ast.walk(node):
+            if isinstance(child, ast.Return) and child.value:
+                if isinstance(child.value, ast.Dict):
+                    return True
+                # Check for dict() call
+                if isinstance(child.value, ast.Call):
+                    if isinstance(child.value.func, ast.Name):
+                        if child.value.func.id == "dict":
+                            return True
+        return False
+
+    def _add_many_params_violation(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        num_params: int,
+    ) -> None:
+        """Add violation for function with too many parameters."""
+        self.violations.append(
+            RuleViolation(
+                rule_name="functions_to_objects",
+                message=(
+                    f"Function '{node.name}' has {num_params} parameters. "
+                    f"Consider converting to a class."
+                ),
+                file_path=self.file_path,
+                line=node.lineno,
+                column=node.col_offset,
+                severity="info",
+                suggestion=(
+                    "Functions with many parameters often indicate the need for an object. "
+                    "Consider creating a class where parameters become attributes, "
+                    "and the function becomes a method."
+                ),
+                code_snippet=self._get_source_line(node.lineno),
+                metadata={
+                    "pattern": "many_parameters",
+                    "function": node.name,
+                    "param_count": num_params,
+                },
+            )
+        )
+
+    def _add_dict_return_violation(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+    ) -> None:
+        """Add violation for function returning a dict."""
+        self.violations.append(
+            RuleViolation(
+                rule_name="functions_to_objects",
+                message=(
+                    f"Function '{node.name}' returns a dictionary. "
+                    f"Consider using a dataclass or named tuple instead."
+                ),
+                file_path=self.file_path,
+                line=node.lineno,
+                column=node.col_offset,
+                severity="info",
+                suggestion=(
+                    "Returning dictionaries loses type information and makes code "
+                    "harder to maintain. Consider using a dataclass, named tuple, "
+                    "or a proper class to represent the returned data."
+                ),
+                code_snippet=self._get_source_line(node.lineno),
+                metadata={
+                    "pattern": "dict_return",
+                    "function": node.name,
+                },
+            )
+        )
+
+    def _get_source_line(self, line_number: int) -> str:
+        """Get a specific line from the source code."""
+        lines = self.source.splitlines()
+        if 1 <= line_number <= len(lines):
+            return lines[line_number - 1].strip()
+        return ""