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

analyzer/validators.py

@@ -6,66 +6,13 @@
 
 import ipaddress
 import pathlib
+import re  # Added for folder name validation
 import socket
 import urllib.error
 import urllib.parse
 import urllib.request
 from typing import Any, Dict, List
 
-# Prohibited binary extensions per QGIS repository policy
-BINARY_EXTENSIONS = {".exe", ".dll", ".so", ".dylib", ".pyd", ".bin", ".a", ".lib"}
-
-
-def scan_for_binaries(project_path: pathlib.Path, ignore_matcher: Any = None) -> List[str]:
-    """Scans the project for prohibited binary files per QGIS policies.
-
-    Args:
-        project_path: Root path of the project.
-        ignore_matcher: Optional object to determine if a path should be ignored.
-
-    Returns:
-        A list of relative paths to any binary files found.
-    """
-    binaries = []
-
-    for file_path in project_path.rglob("*"):
-        if file_path.is_file():
-            # Skip if matches ignore pattern
-            if ignore_matcher and ignore_matcher.is_ignored(file_path):
-                continue
-
-            if file_path.suffix.lower() in BINARY_EXTENSIONS:
-                rel_path = str(file_path.relative_to(project_path))
-                binaries.append(rel_path)
-
-    return binaries
-
-
-def calculate_package_size(project_path: pathlib.Path, ignore_matcher: Any = None) -> float:
-    """Calculates the total package size in Megabytes (MB).
-
-    Args:
-        project_path: Root path of the project.
-        ignore_matcher: Optional object to determine if a path should be ignored.
-
-    Returns:
-        The total size of the plugin package in MB.
-    """
-    total_size = 0
-
-    for file_path in project_path.rglob("*"):
-        if file_path.is_file():
-            # Skip if matches ignore pattern
-            if ignore_matcher:
-                str(file_path.relative_to(project_path))
-                if ignore_matcher.is_ignored(file_path):
-                    continue
-
-            total_size += file_path.stat().st_size
-
-    # Convert bytes to MB
-    return total_size / (1024 * 1024)
-
 
 def is_ssrf_safe(url: str) -> bool:
     """Checks if a URL is safe from Server-Side Request Forgery (SSRF).
@@ -167,6 +114,39 @@ def validate_metadata_urls(metadata: Dict[str, str]) -> Dict[str, str]:
     return results
 
 
+def validate_package_constraints(total_size_mb: float, binaries: List[str]) -> Dict[str, Any]:
+    """Validates package size and binary constraints against Official Repository rules.
+
+    Args:
+        total_size_mb: Total size of the package in MB.
+        binaries: List of detected binary files.
+
+    Returns:
+        Validation results including error messages.
+    """
+    errors = []
+
+    # Rule: Max 20MB
+    if total_size_mb > 20:
+        errors.append(f"Package size ({total_size_mb:.2f}MB) exceeds the 20MB limit.")
+
+    # Rule: No Binaries
+    if binaries:
+        count = len(binaries)
+        shown = ", ".join(binaries[:3])
+        suffix = "..." if count > 3 else ""
+        errors.append(
+            f"Detected {count} binary file(s): {shown}{suffix}. Binaries are not allowed."
+        )
+
+    return {
+        "is_valid": len(errors) == 0,
+        "errors": errors,
+        "total_size_mb": total_size_mb,
+        "binary_count": len(binaries),
+    }
+
+
 def validate_plugin_structure(project_path: pathlib.Path) -> Dict[str, Any]:
     """Validates that the plugin following the required QGIS file structure.
 
@@ -193,12 +173,29 @@ def validate_plugin_structure(project_path: pathlib.Path) -> Dict[str, Any]:
     py_files = list(project_path.glob("*.py"))
     has_python = len(py_files) > 0
 
+    # Check Folder Name (Official Repo Rule: ASCII, alphanumeric, no start with digit)
+    folder_name = project_path.name
+    # Regex explanation:
+    # ^[a-zA-Z_]      : Must start with letter or underscore (cannot start with digit/hyphen)
+    # [a-zA-Z0-9_-]*$ : Followed by alphanumeric, underscore, or hyphen
+    # Note: Official repo is strictly ASCII.
+    folder_valid = False
+    try:
+        # Check ASCII encoding implicitly by regex matching on string, or strict encode check
+        folder_name.encode("ascii")
+        if re.match(r"^[a-zA-Z_][a-zA-Z0-9_-]*$", folder_name):
+            folder_valid = True
+    except UnicodeEncodeError:
+        folder_valid = False
+
     return {
         "files": found,
         "missing_files": missing,
         "has_class_factory": has_factory,
         "has_python_files": has_python,
-        "is_valid": all(found.values()) and has_factory and has_python,
+        "folder_name": folder_name,
+        "folder_name_valid": folder_valid,
+        "is_valid": all(found.values()) and has_factory and has_python and folder_valid,
     }
 
 
@@ -218,6 +215,7 @@ def validate_metadata(metadata_path: pathlib.Path) -> Dict[str, Any]:
         "qgisMinimumVersion",
         "author",
         "email",
+        "about",
     ]
 
     recommended_fields = [
@@ -261,3 +259,40 @@ def validate_metadata(metadata_path: pathlib.Path) -> Dict[str, Any]:
         "recommended_missing": recommended_missing,
         "metadata": metadata,
     }
+
+
+def calculate_package_size(directory: pathlib.Path) -> float:
+    """Calculates the total size of a directory in megabytes.
+
+    Args:
+        directory: The directory path.
+
+    Returns:
+        The total size in MB.
+    """
+    total_size = 0
+    for file in directory.rglob("*"):
+        if file.is_file():
+            total_size += file.stat().st_size
+    return total_size / (1024 * 1024)
+
+
+def scan_for_binaries(directory: pathlib.Path) -> List[str]:
+    """Scans for binary files in the directory.
+
+    Args:
+        directory: The directory path.
+
+    Returns:
+        A list of relative paths to detected binary files.
+    """
+    binary_extensions = {".dll", ".so", ".exe", ".dylib", ".pyd", ".o", ".a"}
+    binaries = []
+    for file in directory.rglob("*"):
+        if file.suffix.lower() in binary_extensions:
+            try:
+                rel_path = file.relative_to(directory)
+                binaries.append(str(rel_path))
+            except ValueError:
+                binaries.append(str(file))
+    return binaries

analyzer/visitors/__init__.py

@@ -0,0 +1,19 @@
+"""AST Visitors for QGIS Plugin Analysis.
+
+This package provides modular AST visitors for analyzing QGIS plugin code.
+Each visitor is specialized for a specific concern (imports, metrics, standards, security).
+"""
+
+from .composite_visitor import CompositeVisitor
+from .security_visitor import SecurityVisitor
+
+# Maintain backward compatibility
+QGISASTVisitor = CompositeVisitor
+QGISSecurityVisitor = SecurityVisitor
+
+__all__ = [
+    "QGISASTVisitor",
+    "QGISSecurityVisitor",
+    "CompositeVisitor",
+    "SecurityVisitor",
+]

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)