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

oop_analyzer/__init__.py

@@ -0,0 +1,12 @@
+"""
+OOP Analyzer - A static analysis tool for Python OOP best practices.
+
+This tool analyzes Python code to check adherence to Object-Oriented Programming
+principles without executing any code (safe static analysis only).
+"""
+
+from .analyzer import OOPAnalyzer
+from .config import AnalyzerConfig
+
+__version__ = "0.1.0"
+__all__ = ["OOPAnalyzer", "AnalyzerConfig"]

oop_analyzer/analyzer.py

@@ -0,0 +1,373 @@
+"""
+Core OOP Analyzer engine.
+
+This module provides the main analyzer class that orchestrates
+the analysis process using configured rules.
+"""
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from .config import AnalyzerConfig
+from .formatters import AnalysisReport, get_formatter
+from .rules import RULE_REGISTRY, BaseRule, RuleResult
+from .safety import SafetyValidator
+
+
+class OOPAnalyzer:
+    """
+    Main analyzer class for checking OOP best practices.
+
+    This class:
+    1. Safely parses Python code (never executes it)
+    2. Runs configured rules against the AST
+    3. Aggregates results into a report
+    4. Formats output in the requested format
+    """
+
+    def __init__(self, config: AnalyzerConfig | None = None):
+        """
+        Initialize the analyzer.
+
+        Args:
+            config: Configuration for the analyzer. Uses defaults if not provided.
+        """
+        self.config = config or AnalyzerConfig.default()
+        self.safety = SafetyValidator(max_file_size=self.config.max_file_size)
+        self._rules: dict[str, BaseRule] = {}
+        self._initialize_rules()
+
+    def _initialize_rules(self) -> None:
+        """Initialize enabled rules based on configuration."""
+        for rule_name in self.config.get_enabled_rules():
+            if rule_name in RULE_REGISTRY:
+                rule_config = self.config.rules.get(rule_name)
+                options = rule_config.options if rule_config else {}
+                self._rules[rule_name] = RULE_REGISTRY[rule_name](options)
+
+    def analyze_source(self, source: str, file_path: str = "<string>") -> AnalysisReport:
+        """
+        Analyze Python source code string.
+
+        Args:
+            source: Python source code as a string
+            file_path: Optional file path for reporting
+
+        Returns:
+            AnalysisReport with results from all enabled rules
+        """
+        errors: list[dict[str, Any]] = []
+        results: dict[str, RuleResult] = {}
+
+        # Validate source can be parsed
+        safety_report = self.safety.validate_source_code(source, file_path)
+        if not safety_report.is_safe:
+            errors.append(
+                {
+                    "file": file_path,
+                    "error": "Failed to parse source",
+                    "details": safety_report.issues,
+                }
+            )
+            return AnalysisReport(
+                files_analyzed=[],
+                results={},
+                config=self.config.to_dict(),
+                errors=errors,
+            )
+
+        # Parse the source
+        tree = self.safety.parse_safely(source, file_path)
+        if tree is None:
+            errors.append(
+                {
+                    "file": file_path,
+                    "error": "Failed to parse source",
+                }
+            )
+            return AnalysisReport(
+                files_analyzed=[],
+                results={},
+                config=self.config.to_dict(),
+                errors=errors,
+            )
+
+        # Run each enabled rule
+        for rule_name, rule in self._rules.items():
+            try:
+                result = rule.analyze(tree, source, file_path)
+                results[rule_name] = result
+            except Exception as e:
+                errors.append(
+                    {
+                        "file": file_path,
+                        "rule": rule_name,
+                        "error": str(e),
+                    }
+                )
+
+        return AnalysisReport(
+            files_analyzed=[file_path],
+            results=results,
+            config=self.config.to_dict(),
+            errors=errors,
+        )
+
+    def analyze_file(self, file_path: str | Path) -> AnalysisReport:
+        """
+        Analyze a single Python file.
+
+        Args:
+            file_path: Path to the Python file
+
+        Returns:
+            AnalysisReport with results from all enabled rules
+        """
+        path = Path(file_path)
+        errors: list[dict[str, Any]] = []
+
+        # Validate file
+        safety_report = self.safety.validate_file_path(path)
+        if not safety_report.is_safe:
+            errors.append(
+                {
+                    "file": str(path),
+                    "error": "File validation failed",
+                    "details": safety_report.issues,
+                }
+            )
+            return AnalysisReport(
+                files_analyzed=[],
+                results={},
+                config=self.config.to_dict(),
+                errors=errors,
+            )
+
+        # Read and analyze
+        try:
+            source = path.read_text(encoding="utf-8")
+        except Exception as e:
+            errors.append(
+                {
+                    "file": str(path),
+                    "error": f"Failed to read file: {e}",
+                }
+            )
+            return AnalysisReport(
+                files_analyzed=[],
+                results={},
+                config=self.config.to_dict(),
+                errors=errors,
+            )
+
+        return self.analyze_source(source, str(path))
+
+    def analyze_directory(self, dir_path: str | Path) -> AnalysisReport:
+        """
+        Analyze all Python files in a directory.
+
+        Args:
+            dir_path: Path to the directory
+
+        Returns:
+            AnalysisReport with aggregated results from all files
+        """
+        path = Path(dir_path)
+        errors: list[dict[str, Any]] = []
+        all_files: list[str] = []
+        parsed_files: list[tuple[ast.Module, str, str]] = []
+
+        # Validate directory
+        safety_report = self.safety.validate_directory(path)
+        if not safety_report.is_safe:
+            errors.append(
+                {
+                    "path": str(path),
+                    "error": "Directory validation failed",
+                    "details": safety_report.issues,
+                }
+            )
+            return AnalysisReport(
+                files_analyzed=[],
+                results={},
+                config=self.config.to_dict(),
+                errors=errors,
+            )
+
+        # Collect Python files
+        python_files = self.safety.collect_python_files(path)
+
+        # Filter based on include/exclude patterns
+        python_files = self._filter_files(python_files, path)
+
+        # Parse all files
+        for file_path in python_files:
+            file_safety = self.safety.validate_file_path(file_path)
+            if not file_safety.is_safe:
+                errors.append(
+                    {
+                        "file": str(file_path),
+                        "error": "File validation failed",
+                        "details": file_safety.issues,
+                    }
+                )
+                continue
+
+            try:
+                source = file_path.read_text(encoding="utf-8")
+                tree = self.safety.parse_safely(source, str(file_path))
+                if tree:
+                    parsed_files.append((tree, source, str(file_path)))
+                    all_files.append(str(file_path))
+                else:
+                    errors.append(
+                        {
+                            "file": str(file_path),
+                            "error": "Failed to parse file",
+                        }
+                    )
+            except Exception as e:
+                errors.append(
+                    {
+                        "file": str(file_path),
+                        "error": f"Failed to read file: {e}",
+                    }
+                )
+
+        # Run rules that support multi-file analysis
+        results: dict[str, RuleResult] = {}
+        for rule_name, rule in self._rules.items():
+            try:
+                # Use analyze_multiple for rules that benefit from seeing all files
+                result = rule.analyze_multiple(parsed_files)
+                results[rule_name] = result
+            except Exception as e:
+                errors.append(
+                    {
+                        "rule": rule_name,
+                        "error": str(e),
+                    }
+                )
+
+        return AnalysisReport(
+            files_analyzed=all_files,
+            results=results,
+            config=self.config.to_dict(),
+            errors=errors,
+        )
+
+    def analyze_module(self, module_path: str | Path) -> AnalysisReport:
+        """
+        Analyze a Python module (directory with __init__.py).
+
+        Args:
+            module_path: Path to the module directory
+
+        Returns:
+            AnalysisReport with results
+        """
+        path = Path(module_path)
+
+        # Check if it's a valid module
+        init_file = path / "__init__.py"
+        if not init_file.exists():
+            return AnalysisReport(
+                files_analyzed=[],
+                results={},
+                config=self.config.to_dict(),
+                errors=[
+                    {
+                        "path": str(path),
+                        "error": "Not a valid Python module (missing __init__.py)",
+                    }
+                ],
+            )
+
+        return self.analyze_directory(path)
+
+    def analyze(self, path: str | Path) -> AnalysisReport:
+        """
+        Analyze a path (file, directory, or module).
+
+        Automatically detects the type and calls the appropriate method.
+
+        Args:
+            path: Path to analyze
+
+        Returns:
+            AnalysisReport with results
+        """
+        path = Path(path)
+
+        if path.is_file():
+            return self.analyze_file(path)
+        elif path.is_dir():
+            # Check if it's a module
+            if (path / "__init__.py").exists():
+                return self.analyze_module(path)
+            return self.analyze_directory(path)
+        else:
+            return AnalysisReport(
+                files_analyzed=[],
+                results={},
+                config=self.config.to_dict(),
+                errors=[
+                    {
+                        "path": str(path),
+                        "error": "Path does not exist",
+                    }
+                ],
+            )
+
+    def format_report(self, report: AnalysisReport, format_name: str | None = None) -> str:
+        """
+        Format a report in the specified format.
+
+        Args:
+            report: The analysis report to format
+            format_name: Output format (json, xml, html). Uses config default if not specified.
+
+        Returns:
+            Formatted string
+        """
+        format_name = format_name or self.config.output_format
+        formatter_class = get_formatter(format_name)
+        formatter = formatter_class()
+        return formatter.format(report)
+
+    def _filter_files(self, files: list[Path], base_path: Path) -> list[Path]:
+        """Filter files based on include/exclude patterns."""
+        import fnmatch
+
+        filtered: list[Path] = []
+
+        for file_path in files:
+            try:
+                relative = file_path.relative_to(base_path)
+            except ValueError:
+                relative = file_path
+
+            rel_str = str(relative)
+
+            # Check exclude patterns
+            excluded = False
+            for pattern in self.config.exclude_patterns:
+                if fnmatch.fnmatch(rel_str, pattern):
+                    excluded = True
+                    break
+
+            if excluded:
+                continue
+
+            # Check include patterns
+            included = False
+            for pattern in self.config.include_patterns:
+                if fnmatch.fnmatch(file_path.name, pattern):
+                    included = True
+                    break
+
+            if included:
+                filtered.append(file_path)
+
+        return filtered

oop_analyzer/cli.py

@@ -0,0 +1,160 @@
+"""
+Command-line interface for OOP Analyzer.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .analyzer import OOPAnalyzer
+from .config import AnalyzerConfig
+
+
+def main() -> int:
+    """Main entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="oop-analyzer",
+        description="Analyze Python code for OOP best practices",
+    )
+
+    parser.add_argument(
+        "path",
+        type=str,
+        nargs="?",
+        help="Path to Python file, module, or directory to analyze",
+    )
+
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=["json", "xml", "html"],
+        default="json",
+        help="Output format (default: json)",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        help="Output file path (default: stdout)",
+    )
+
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=str,
+        help="Path to configuration file",
+    )
+
+    parser.add_argument(
+        "--rules",
+        type=str,
+        nargs="+",
+        help="Enable only specific rules",
+    )
+
+    parser.add_argument(
+        "--disable-rules",
+        type=str,
+        nargs="+",
+        help="Disable specific rules",
+    )
+
+    parser.add_argument(
+        "--list-rules",
+        action="store_true",
+        help="List available rules and exit",
+    )
+
+    parser.add_argument(
+        "--init-config",
+        type=str,
+        metavar="FILE",
+        help="Generate a default configuration file",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+
+    args = parser.parse_args()
+
+    # Handle --list-rules
+    if args.list_rules:
+        print("Available rules:")
+        for name, desc in AnalyzerConfig.AVAILABLE_RULES.items():
+            print(f"  {name}: {desc}")
+        return 0
+
+    # Handle --init-config
+    if args.init_config:
+        config = AnalyzerConfig.default()
+        config.save(args.init_config)
+        print(f"Configuration saved to: {args.init_config}")
+        return 0
+
+    # Load or create configuration
+    if args.config:
+        try:
+            config = AnalyzerConfig.from_file(args.config)
+        except FileNotFoundError:
+            print(f"Error: Config file not found: {args.config}", file=sys.stderr)
+            return 1
+    else:
+        config = AnalyzerConfig.default()
+
+    # Apply command-line rule overrides
+    if args.rules:
+        config.enable_only(*args.rules)
+
+    if args.disable_rules:
+        for rule in args.disable_rules:
+            config.disable_rule(rule)
+
+    # Set output format
+    config.output_format = args.format
+
+    # Validate path (required for analysis)
+    if not args.path:
+        print("Error: path is required for analysis", file=sys.stderr)
+        parser.print_help()
+        return 1
+
+    path = Path(args.path)
+    if not path.exists():
+        print(f"Error: Path does not exist: {args.path}", file=sys.stderr)
+        return 1
+
+    # Run analysis
+    if args.verbose:
+        print(f"Analyzing: {path}", file=sys.stderr)
+        print(f"Enabled rules: {config.get_enabled_rules()}", file=sys.stderr)
+
+    analyzer = OOPAnalyzer(config)
+    report = analyzer.analyze(path)
+
+    # Format output
+    output = analyzer.format_report(report)
+
+    # Write output
+    if args.output:
+        output_path = Path(args.output)
+        output_path.write_text(output, encoding="utf-8")
+        if args.verbose:
+            print(f"Report saved to: {output_path}", file=sys.stderr)
+    else:
+        print(output)
+
+    # Return non-zero if there are errors or violations
+    if report.errors:
+        return 2
+    if report.total_violations > 0:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

oop_analyzer/config.py

@@ -0,0 +1,155 @@
+"""
+Configuration module for OOP Analyzer.
+
+Provides configuration options for selecting which rules to run
+and customizing analyzer behavior.
+"""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class RuleConfig:
+    """Configuration for a specific rule."""
+
+    enabled: bool = True
+    severity: str = "warning"  # "error", "warning", "info"
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AnalyzerConfig:
+    """
+    Configuration for the OOP Analyzer.
+
+    Attributes:
+        rules: Dictionary mapping rule names to their configurations
+        output_format: Output format ("json", "xml", "html")
+        include_patterns: Glob patterns for files to include
+        exclude_patterns: Glob patterns for files to exclude
+        max_file_size: Maximum file size in bytes to analyze
+    """
+
+    rules: dict[str, RuleConfig] = field(default_factory=dict)
+    output_format: str = "json"
+    include_patterns: list[str] = field(default_factory=lambda: ["*.py"])
+    exclude_patterns: list[str] = field(
+        default_factory=lambda: ["**/test_*.py", "**/*_test.py", "**/tests/**"]
+    )
+    max_file_size: int = 10 * 1024 * 1024  # 10 MB
+
+    # Available rules with their default configurations
+    AVAILABLE_RULES = {
+        "encapsulation": "Check for direct property access (tell don't ask)",
+        "coupling": "Measure coupling and show dependency graph",
+        "null_object": "Detect None usage replaceable by Null Object pattern",
+        "polymorphism": "Find if blocks replaceable by polymorphism",
+        "functions_to_objects": "Detect functions that could be objects",
+        "type_code": "Detect type code conditionals replaceable by polymorphism",
+        "reference_exposure": "Detect methods exposing internal mutable state",
+        "dictionary_usage": "Detect dictionary usage that should be objects",
+        "boolean_flag": "Detect boolean flag parameters causing behavior branching",
+    }
+
+    def __post_init__(self) -> None:
+        # Initialize all rules with defaults if not specified
+        for rule_name in self.AVAILABLE_RULES:
+            if rule_name not in self.rules:
+                self.rules[rule_name] = RuleConfig()
+
+    def enable_rule(self, rule_name: str, **options: Any) -> None:
+        """Enable a specific rule with optional configuration."""
+        if rule_name not in self.AVAILABLE_RULES:
+            raise ValueError(f"Unknown rule: {rule_name}")
+        self.rules[rule_name] = RuleConfig(enabled=True, options=options)
+
+    def disable_rule(self, rule_name: str) -> None:
+        """Disable a specific rule."""
+        if rule_name in self.rules:
+            self.rules[rule_name].enabled = False
+
+    def enable_only(self, *rule_names: str) -> None:
+        """Enable only the specified rules, disable all others."""
+        for rule_name in self.AVAILABLE_RULES:
+            if rule_name in rule_names:
+                self.rules[rule_name] = RuleConfig(enabled=True)
+            else:
+                self.rules[rule_name] = RuleConfig(enabled=False)
+
+    def get_enabled_rules(self) -> list[str]:
+        """Get list of enabled rule names."""
+        return [name for name, config in self.rules.items() if config.enabled]
+
+    def is_rule_enabled(self, rule_name: str) -> bool:
+        """Check if a rule is enabled."""
+        return rule_name in self.rules and self.rules[rule_name].enabled
+
+    @classmethod
+    def from_file(cls, config_path: str | Path) -> "AnalyzerConfig":
+        """Load configuration from a JSON file."""
+        path = Path(config_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Config file not found: {path}")
+
+        with open(path) as f:
+            data = json.load(f)
+
+        rules = {}
+        for rule_name, rule_data in data.get("rules", {}).items():
+            if isinstance(rule_data, bool):
+                rules[rule_name] = RuleConfig(enabled=rule_data)
+            elif isinstance(rule_data, dict):
+                rules[rule_name] = RuleConfig(
+                    enabled=rule_data.get("enabled", True),
+                    severity=rule_data.get("severity", "warning"),
+                    options=rule_data.get("options", {}),
+                )
+
+        return cls(
+            rules=rules,
+            output_format=data.get("output_format", "json"),
+            include_patterns=data.get("include_patterns", ["*.py"]),
+            exclude_patterns=data.get(
+                "exclude_patterns",
+                ["**/test_*.py", "**/*_test.py", "**/tests/**"],
+            ),
+            max_file_size=data.get("max_file_size", 10 * 1024 * 1024),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert configuration to dictionary."""
+        return {
+            "rules": {
+                name: {
+                    "enabled": config.enabled,
+                    "severity": config.severity,
+                    "options": config.options,
+                }
+                for name, config in self.rules.items()
+            },
+            "output_format": self.output_format,
+            "include_patterns": self.include_patterns,
+            "exclude_patterns": self.exclude_patterns,
+            "max_file_size": self.max_file_size,
+        }
+
+    def save(self, config_path: str | Path) -> None:
+        """Save configuration to a JSON file."""
+        path = Path(config_path)
+        with open(path, "w") as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+    @classmethod
+    def default(cls) -> "AnalyzerConfig":
+        """Create a default configuration with all rules enabled."""
+        return cls()
+
+    @classmethod
+    def minimal(cls) -> "AnalyzerConfig":
+        """Create a minimal configuration with only essential rules."""
+        config = cls()
+        config.enable_only("encapsulation", "coupling")
+        return config