qgis-plugin-analyzer 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

analyzer/visitors/base.py

@@ -0,0 +1,75 @@
+"""Base visitor class with shared functionality for all AST visitors."""
+
+import ast
+from typing import Any, Dict, List, Optional
+
+
+class BaseVisitor(ast.NodeVisitor):
+    """Base class for AST visitors with common reporting and configuration logic.
+
+    Attributes:
+        rel_path: Relative path to the file being analyzed.
+        issues: List of detected issues.
+        rules_config: Configuration for audit rules and severities.
+    """
+
+    def __init__(self, rel_path: str, rules_config: Optional[Dict[str, Any]] = None) -> None:
+        """Initializes the base visitor.
+
+        Args:
+            rel_path: Relative path to the file being analyzed.
+            rules_config: Optional configuration for audit rules and severities.
+        """
+        self.rel_path = rel_path
+        self.issues: List[Dict[str, Any]] = []
+        self.rules_config = rules_config or {}
+
+    def _should_report(self, rule_id: str) -> bool:
+        """Check if rule should be reported based on config.
+
+        Args:
+            rule_id: The rule identifier.
+
+        Returns:
+            True if the rule should be reported, False otherwise.
+        """
+        severity = self.rules_config.get(rule_id, "warning")
+        return bool(severity != "ignore")
+
+    def _get_severity(self, rule_id: str) -> str:
+        """Get configured severity for rule (maps to 'high', 'medium', 'low').
+
+        Args:
+            rule_id: The rule identifier.
+
+        Returns:
+            The severity level as a string.
+        """
+        config_severity = self.rules_config.get(rule_id, "warning")
+        severity_map = {
+            "error": "high",
+            "warning": "medium",
+            "info": "low",
+        }
+        return severity_map.get(config_severity, "medium")
+
+    def _report_issue(self, rule_id: str, line: int, message: str, code: str = "") -> None:
+        """Helper to report an issue if enabled.
+
+        Args:
+            rule_id: The rule identifier.
+            line: Line number where the issue was detected.
+            message: Description of the issue.
+            code: Optional code snippet related to the issue.
+        """
+        if self._should_report(rule_id):
+            self.issues.append(
+                {
+                    "file": self.rel_path,
+                    "line": line,
+                    "type": rule_id,
+                    "severity": self._get_severity(rule_id),
+                    "message": message,
+                    "code": code,
+                }
+            )

analyzer/visitors/composite_visitor.py

@@ -0,0 +1,73 @@
+"""Composite visitor that orchestrates all specialized visitors."""
+
+import ast
+from typing import Any, Dict, List, Optional
+
+from .imports_visitor import ImportsVisitor
+from .metrics_visitor import MetricsVisitor
+from .standards_visitor import StandardsVisitor
+
+
+class CompositeVisitor(ast.NodeVisitor):
+    """Orchestrator that combines all specialized visitors.
+
+    This class maintains compatibility with the original QGISASTVisitor API
+    while delegating work to specialized visitors.
+
+    Attributes:
+        rel_path: Relative path to the file being analyzed.
+        issues: Aggregated list of all issues from all visitors.
+        docstring_styles: Aggregated docstring styles from metrics visitor.
+        type_hint_stats: Type hint statistics from metrics visitor.
+        docstring_stats: Docstring statistics from metrics visitor.
+    """
+
+    def __init__(self, rel_path: str, rules_config: Optional[Dict[str, Any]] = None) -> None:
+        """Initializes the composite visitor.
+
+        Args:
+            rel_path: Relative path to the file being analyzed.
+            rules_config: Optional configuration for audit rules and severities.
+        """
+        self.rel_path = rel_path
+        self.rules_config = rules_config or {}
+
+        # Initialize specialized visitors
+        self._imports_visitor = ImportsVisitor(rel_path, rules_config)
+        self._metrics_visitor = MetricsVisitor(rel_path, rules_config)
+        self._standards_visitor = StandardsVisitor(rel_path, rules_config)
+
+        # Aggregated results
+        self.issues: List[Dict[str, Any]] = []
+
+    @property
+    def docstring_styles(self) -> List[str]:
+        """Returns docstring styles from metrics visitor."""
+        return self._metrics_visitor.docstring_styles
+
+    @property
+    def type_hint_stats(self) -> Dict[str, int]:
+        """Returns type hint statistics from metrics visitor."""
+        return self._metrics_visitor.type_hint_stats
+
+    @property
+    def docstring_stats(self) -> Dict[str, int]:
+        """Returns docstring statistics from metrics visitor."""
+        return self._metrics_visitor.docstring_stats
+
+    def visit(self, node: ast.AST) -> None:
+        """Visits a node with all specialized visitors.
+
+        Args:
+            node: The AST node to visit.
+        """
+        # Dispatch to all specialized visitors
+        self._imports_visitor.visit(node)
+        self._metrics_visitor.visit(node)
+        self._standards_visitor.visit(node)
+
+        # Aggregate issues
+        self.issues = []
+        self.issues.extend(self._imports_visitor.issues)
+        self.issues.extend(self._metrics_visitor.issues)
+        self.issues.extend(self._standards_visitor.issues)

analyzer/visitors/imports_visitor.py

@@ -0,0 +1,85 @@
+"""AST visitor for import validation and analysis."""
+
+import ast
+from typing import Any, cast
+
+from .base import BaseVisitor
+
+
+class ImportsVisitor(BaseVisitor):
+    """Visitor focused on import-related checks.
+
+    Detects issues like:
+    - Direct GDAL imports
+    - Legacy PyQt4/PyQt5 imports
+    - Protected member imports
+    - Heavy dependencies in UI files
+    """
+
+    def visit_Import(self, node: ast.Import) -> None:
+        """Analyzes import nodes.
+
+        Args:
+            node: The import AST node.
+        """
+        for alias in node.names:
+            self._check_import_name(alias.name, node, ast.unparse(node))
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        """Analyzes 'from import' nodes.
+
+        Args:
+            node: The import-from AST node.
+        """
+        if node.module:
+            self._check_import_name(node.module, node, ast.unparse(node))
+
+            # HEAVY_LOGIC_UI check
+            heavy_libs = {"pandas", "numpy", "scipy", "sklearn", "matplotlib"}
+            is_ui_file = "gui" in self.rel_path.lower() or "ui" in self.rel_path.lower()
+            if is_ui_file and (
+                node.module in heavy_libs or node.module.split(".")[0] in heavy_libs
+            ):
+                self._report_issue(
+                    "HEAVY_LOGIC_UI",
+                    node.lineno,
+                    f"Heavy dependency '{node.module}' detected in UI file. Move logic to core.",
+                    ast.unparse(node),
+                )
+        self.generic_visit(node)
+
+    def _check_import_name(self, name: str, node: ast.AST, code_snippet: str) -> None:
+        """Checks a single import name for violations.
+
+        Args:
+            name: The import name to check.
+            node: The AST node containing the import.
+            code_snippet: String representation of the import statement.
+        """
+        # QGIS_PROTECTED_MEMBER
+        if name.startswith("qgis._") and not name.startswith("qgis._3d"):
+            self._report_issue(
+                "QGIS_PROTECTED_MEMBER",
+                cast(Any, node).lineno,
+                f"Protected member import detected: '{name}'. Protected members are unstable.",
+                code_snippet,
+            )
+
+        # GDAL_DIRECT_IMPORT
+        if name == "gdal":
+            self._report_issue(
+                "GDAL_DIRECT_IMPORT",
+                cast(Any, node).lineno,
+                "Direct 'gdal' import detected. Use 'from osgeo import gdal'.",
+                code_snippet,
+            )
+
+        # QGIS_LEGACY_IMPORT
+        if name.startswith(("PyQt4", "PyQt5")):
+            self._report_issue(
+                "QGIS_LEGACY_IMPORT",
+                cast(Any, node).lineno,
+                f"Legacy import detected: '{name}'. Use 'qgis.PyQt' for compatibility.",
+                code_snippet,
+            )

analyzer/visitors/metrics_visitor.py

@@ -0,0 +1,158 @@
+"""AST visitor for docstring and metrics collection."""
+
+import ast
+import re
+from typing import Any, Dict, List, Optional
+
+from ..utils.ast_utils import calculate_complexity
+from .base import BaseVisitor
+
+
+class MetricsVisitor(BaseVisitor):
+    """Visitor focused on collecting research-based metrics.
+
+    Collects:
+    - Docstring coverage and styles
+    - Type hint coverage
+    - Complexity metrics
+    """
+
+    def __init__(self, rel_path: str, rules_config: Optional[Dict[str, Any]] = None) -> None:
+        """Initializes the metrics visitor.
+
+        Args:
+            rel_path: Relative path to the file being analyzed.
+            rules_config: Optional configuration for audit rules and severities.
+        """
+        super().__init__(rel_path, rules_config)
+        self.docstring_styles: List[str] = []
+        self.type_hint_stats = {
+            "total_parameters": 0,
+            "annotated_parameters": 0,
+            "has_return_hint": 0,
+            "total_functions": 0,
+        }
+        self.docstring_stats = {"total_public_items": 0, "has_docstring": 0}
+
+    def visit_Module(self, node: ast.Module) -> None:
+        """Analyzes a module-level AST node.
+
+        Args:
+            node: The module AST node.
+        """
+        doc = ast.get_docstring(node)
+        self.docstring_stats["total_public_items"] += 1
+        if doc:
+            self.docstring_stats["has_docstring"] += 1
+            self._check_docstring_style(doc)
+        else:
+            self._report_issue(
+                "MISSING_DOCSTRING",
+                1,
+                "Module is missing a docstring (PEP 257).",
+                f"Module: {self.rel_path}",
+            )
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Analyzes function definitions.
+
+        Args:
+            node: The function definition AST node.
+        """
+        # HIGH_COMPLEXITY
+        complexity = calculate_complexity(node)
+        if complexity > 15:
+            self._report_issue(
+                "HIGH_COMPLEXITY",
+                node.lineno,
+                f"Function '{node.name}' is too complex (CC={complexity} > 15). Consider extracting methods.",
+                f"def {node.name}...",
+            )
+
+        self._check_docstring_and_metrics(node)
+        self._check_type_hints(node)
+        self.generic_visit(node)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Analyzes class definitions.
+
+        Args:
+            node: The class definition AST node.
+        """
+        # Missing Docstring
+        if not node.name.startswith("_"):
+            doc = ast.get_docstring(node)
+            self.docstring_stats["total_public_items"] += 1
+            if doc:
+                self.docstring_stats["has_docstring"] += 1
+                self._check_docstring_style(doc)
+            else:
+                self._report_issue(
+                    "MISSING_DOCSTRING",
+                    node.lineno,
+                    f"Public class '{node.name}' is missing a docstring.",
+                    f"class {node.name}...",
+                )
+
+        self.generic_visit(node)
+
+    def _check_docstring_style(self, doc: Optional[str]) -> None:
+        """Identifies Google or NumPy docstring styles within a string.
+
+        Args:
+            doc: The docstring to analyze.
+        """
+        if not doc:
+            return
+        # Google: Args: or Returns: or Raises: as headers
+        if re.search(r"\n\s*(Args|Returns|Raises|Yields):\s*\n", doc):
+            self.docstring_styles.append("Google")
+        # NumPy: Underlined headers
+        elif re.search(r"\n(Parameters|Returns|Raises|Yields)\n\s*-{3,}", doc):
+            self.docstring_styles.append("NumPy")
+
+    def _check_docstring_and_metrics(self, node: ast.FunctionDef) -> None:
+        """Checks docstrings and collects metrics.
+
+        Args:
+            node: The function definition AST node.
+        """
+        if not node.name.startswith("_") and node.name != "__init__":
+            doc = ast.get_docstring(node)
+            self.docstring_stats["total_public_items"] += 1
+            if doc:
+                self.docstring_stats["has_docstring"] += 1
+                self._check_docstring_style(doc)
+            else:
+                self._report_issue(
+                    "MISSING_DOCSTRING",
+                    node.lineno,
+                    f"Public function '{node.name}' is missing a docstring.",
+                    f"def {node.name}...",
+                )
+
+    def _check_type_hints(self, node: ast.FunctionDef) -> None:
+        """Checks for type hints.
+
+        Args:
+            node: The function definition AST node.
+        """
+        if node.name == "__init__":
+            return
+
+        self.type_hint_stats["total_functions"] += 1
+        params = [a for a in node.args.args if a.arg != "self" and a.arg != "cls"]
+        self.type_hint_stats["total_parameters"] += len(params)
+        annotated = [a for a in params if a.annotation]
+        self.type_hint_stats["annotated_parameters"] += len(annotated)
+        if node.returns:
+            self.type_hint_stats["has_return_hint"] += 1
+
+        if params and not annotated and not node.returns:
+            self._report_issue(
+                "MISSING_TYPE_HINTS",
+                node.lineno,
+                f"Function '{node.name}' has no type annotations.",
+                f"def {node.name}...",
+            )

analyzer/visitors/security_visitor.py

@@ -0,0 +1,52 @@
+"""AST visitor for security vulnerability detection."""
+
+import ast
+from typing import Any, Dict, List
+
+from ..security_checker import SecurityContext, SecurityRegistry
+
+
+class SecurityVisitor(ast.NodeVisitor):
+    """AST visitor focused on security vulnerabilities (Bandit-inspired).
+
+    Attributes:
+        rel_path: Relative path to the file being analyzed.
+        findings: List of security findings detected.
+    """
+
+    def __init__(self, rel_path: str):
+        """Initializes the security visitor.
+
+        Args:
+            rel_path: Relative path to the file being analyzed.
+        """
+        self.rel_path = rel_path
+        self.findings: List[Dict[str, Any]] = []
+
+    def visit(self, node: ast.AST):
+        """Dispatches security checks for the current node.
+
+        Args:
+            node: The AST node to analyze.
+        """
+        checks = SecurityRegistry.get_checks_for_node(type(node))
+        context = SecurityContext(node, self.rel_path)
+
+        for check_func in checks:
+            finding = check_func(context)
+            if finding:
+                self.findings.append(
+                    {
+                        "file": self.rel_path,
+                        "line": finding.line,
+                        "type": finding.id,
+                        "severity": finding.severity.lower(),
+                        "message": finding.message,
+                        "code": finding.code_snippet,
+                        "confidence": finding.confidence.lower()
+                        if hasattr(finding, "confidence")
+                        else "medium",
+                    }
+                )
+
+        super().generic_visit(node)