qgis-plugin-analyzer 1.3.0__py3-none-any.whl

analyzer/semantic.py

@@ -0,0 +1,213 @@
+# /***************************************************************************
+#  QGIS Plugin Analyzer
+#
+#  Semantic analysis module for cross-file dependency and resource validation.
+#  ***************************************************************************/
+
+import pathlib
+import xml.etree.ElementTree as ET
+from typing import Any, Dict, List, Set
+
+
+class DependencyGraph:
+    """Builds and analyzes the module dependency graph to detect circular imports.
+
+    Attributes:
+        adjacency_list: Maps module path to the set of imported module paths.
+        nodes: Maps module path to its extracted metadata.
+    """
+
+    def __init__(self) -> None:
+        """Initializes an empty dependency graph."""
+        # Maps module path -> set of imported module paths
+        self.adjacency_list: Dict[str, Set[str]] = {}
+        # Maps module path -> metadata (imports, functions, etc.)
+        self.nodes: Dict[str, Dict[str, Any]] = {}
+
+    def add_node(self, module_path: str, data: Dict[str, Any]) -> None:
+        """Adds a module node to the graph.
+
+        Args:
+            module_path: Relative path to the module file.
+            data: Metadata dictionary for the module.
+        """
+        self.nodes[module_path] = data
+        self.adjacency_list[module_path] = set()
+
+    def build_edges(self, project_path: pathlib.Path) -> None:
+        """Resolves module imports and builds edges between nodes.
+
+        Args:
+            project_path: Root path of the project.
+        """
+        for module_path, data in self.nodes.items():
+            current_file = project_path / module_path
+            current_dir = current_file.parent
+
+            for imp in data.get("imports", []):
+                resolved_path = self._resolve_import(imp, current_dir, project_path)
+                if resolved_path and resolved_path in self.nodes:
+                    self.adjacency_list[module_path].add(resolved_path)
+
+    def _resolve_import(
+        self, import_name: str, current_dir: pathlib.Path, project_path: pathlib.Path
+    ) -> str:
+        """Attempts to resolve a Python import string to a relative file path.
+
+        Args:
+            import_name: The name of the imported module or package.
+            current_dir: Directory containing the importing file.
+            project_path: Root directory of the project.
+
+        Returns:
+            The relative path to the resolved module, or an empty string if not found.
+        """
+        # Handle relative imports (e.g., .utils)
+        if import_name.startswith("."):
+            # This is a simplification. Ideally AST gives better level info.
+            # Assuming same package level for now if single dot
+            parts = import_name.lstrip(".").split(".")
+            target = current_dir.joinpath(*parts).with_suffix(".py")
+            try:
+                rel = str(target.relative_to(project_path))
+                return rel
+            except ValueError:
+                pass
+            return ""
+
+        # Handle absolute imports within project
+        parts = import_name.split(".")
+        target = project_path.joinpath(*parts).with_suffix(".py")
+        try:
+            rel = str(target.relative_to(project_path))
+            return rel
+        except ValueError:
+            # Maybe it is a package (__init__.py)
+            target_pkg = project_path.joinpath(*parts) / "__init__.py"
+            try:
+                rel = str(target_pkg.relative_to(project_path))
+                return rel
+            except ValueError:
+                pass
+        return ""
+
+    def detect_cycles(self) -> List[List[str]]:
+        """Detects circular import cycles using Depth First Search (DFS).
+
+        Returns:
+            A list of dependency cycles, where each cycle is a list of module paths.
+        """
+        visited = set()
+        recursion_stack = set()
+        cycles = []
+
+        def dfs(node, path):
+            visited.add(node)
+            recursion_stack.add(node)
+            path.append(node)
+
+            for neighbor in self.adjacency_list.get(node, []):
+                if neighbor not in visited:
+                    dfs(neighbor, path)
+                elif neighbor in recursion_stack:
+                    # Cycle found
+                    cycle_start_index = path.index(neighbor)
+                    cycles.append(path[cycle_start_index:] + [neighbor])
+
+            recursion_stack.remove(node)
+            path.pop()
+
+        for node in self.nodes:
+            if node not in visited:
+                dfs(node, [])
+
+        return cycles
+
+    def get_coupling_metrics(self) -> Dict[str, Dict[str, int]]:
+        """Calculates Fan-In and Fan-Out metrics for each module in the graph.
+
+        Returns:
+            A dictionary mapping module paths to their coupling metrics.
+        """
+        metrics = {node: {"fan_in": 0, "fan_out": 0} for node in self.nodes}
+
+        for source, targets in self.adjacency_list.items():
+            metrics[source]["fan_out"] = len(targets)
+            for target in targets:
+                if target in metrics:  # Should always be true if graph valid
+                    metrics[target]["fan_in"] += 1
+
+        return metrics
+
+
+class ResourceValidator:
+    """Validates Qt resource (QRC) usage against available definitions.
+
+    Attributes:
+        project_path: Path to the root of the project.
+        available_resources: A set of detected resource strings (e.g., ':/plugins/...').
+    """
+
+    def __init__(self, project_path: pathlib.Path) -> None:
+        """Initializes the resource validator.
+
+        Args:
+            project_path: Root path of the project.
+        """
+        self.project_path = project_path
+        self.available_resources: Set[str] = set()
+
+    def scan_project_resources(self, ignore_matcher: Any = None) -> None:
+        """Scans the project for .qrc files and extracts available resource paths.
+
+        Args:
+            ignore_matcher: Optional object to determine if a path should be ignored.
+        """
+        # Strategy: Parse .qrc files primarily as they are the source of truth
+        # Regex to find <file>path/to/icon.png</file> inside <qresource prefix="/plugins/myplugin">
+
+        for qrc_file in self.project_path.rglob("*.qrc"):
+            # Skip if matches ignore pattern
+            if ignore_matcher and ignore_matcher.is_ignored(qrc_file):
+                continue
+
+            try:
+                # Use standard xml.etree.ElementTree for robust parsing
+                # Note: ElementTree is safe against XXE by default in Python 3.x
+                # as it does not resolve entities unless a custom parser is provided.
+                try:
+                    tree = ET.parse(qrc_file)
+                    root = tree.getroot()
+                    for qresource in root.findall("qresource"):
+                        prefix = qresource.get("prefix", "/")
+                        if not prefix.startswith("/"):
+                            prefix = "/" + prefix
+
+                        for file_elem in qresource.findall("file"):
+                            if file_elem.text:
+                                clean_path = file_elem.text.strip()
+                                # Construct full resource path: :/prefix/path
+                                res_path = f":{prefix}/{clean_path}".replace("//", "/")
+                                self.available_resources.add(res_path)
+                except ET.ParseError:
+                    pass  # Fallback or log warning
+
+            except Exception:
+                pass
+
+    def validate_usage(self, resource_matches: List[str]) -> List[str]:
+        """Identifies resource paths used in code that are missing from definition files.
+
+        Args:
+            resource_matches: List of resource strings extracted from the code.
+
+        Returns:
+            A list of unique, missing resource strings.
+        """
+        missing = []
+        for res in resource_matches:
+            # Simple exact match check.
+            # Note: Alias handling is complex without compilation, ignoring for now.
+            if res not in self.available_resources:
+                missing.append(res)
+        return sorted(list(set(missing)))

analyzer/transformers.py

@@ -0,0 +1,190 @@
+# /***************************************************************************
+#  QGIS Plugin Analyzer
+#
+#  AST-based code transformers for auto-fixing common issues.
+#  ***************************************************************************/
+
+import ast
+import pathlib
+from typing import Optional
+
+
+class GDALImportTransformer(ast.NodeTransformer):
+    """AST transformer that replaces direct GDAL imports with the OSGeo version.
+
+    Transforms 'import gdal' into 'from osgeo import gdal'.
+    """
+
+    def __init__(self) -> None:
+        """Initializes the transformer state."""
+        self.changes_made = False
+
+    def visit_Import(self, node: ast.Import) -> Optional[ast.AST]:
+        for alias in node.names:
+            if alias.name == "gdal":
+                self.changes_made = True
+                # Create 'from osgeo import gdal'
+                return ast.ImportFrom(
+                    module="osgeo",
+                    names=[ast.alias(name="gdal", asname=alias.asname)],
+                    level=0,
+                )
+        return node
+
+
+class LegacyImportTransformer(ast.NodeTransformer):
+    """AST transformer that modernizes PyQt4/PyQt5 imports to qgis.PyQt.
+
+    Attributes:
+        changes_made: Boolean flag indicating if any changes were applied.
+    """
+
+    def __init__(self) -> None:
+        """Initializes the transformer state."""
+        self.changes_made = False
+
+    def visit_Import(self, node: ast.Import) -> ast.Import:
+        for alias in node.names:
+            if alias.name.startswith(("PyQt4", "PyQt5")):
+                self.changes_made = True
+                # Replace PyQt5.QtCore -> qgis.PyQt.QtCore
+                new_name = alias.name.replace("PyQt5", "qgis.PyQt").replace("PyQt4", "qgis.PyQt")
+                alias.name = new_name
+        return node
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> ast.ImportFrom:
+        if node.module and node.module.startswith(("PyQt4", "PyQt5")):
+            self.changes_made = True
+            node.module = node.module.replace("PyQt5", "qgis.PyQt").replace("PyQt4", "qgis.PyQt")
+        return node
+
+
+class PrintToLogTransformer(ast.NodeTransformer):
+    """AST transformer that replaces print() calls with QgsMessageLog.logMessage().
+
+    Attributes:
+        changes_made: Boolean flag indicating if any changes were applied.
+        needs_import: Boolean flag indicating if a new import is required.
+    """
+
+    def __init__(self) -> None:
+        """Initializes the transformer state."""
+        self.changes_made = False
+        self.needs_import = False
+
+    def visit_Expr(self, node: ast.Expr) -> ast.Expr:
+        # Check if it's a print() call
+        if isinstance(node.value, ast.Call):
+            if isinstance(node.value.func, ast.Name) and node.value.func.id == "print":
+                self.changes_made = True
+                self.needs_import = True
+
+                # Get the message argument
+                if node.value.args:
+                    message = node.value.args[0]
+                else:
+                    message = ast.Constant(value="")
+
+                # Create QgsMessageLog.logMessage(message, "Plugin", Qgis.Info)
+                new_call = ast.Expr(
+                    value=ast.Call(
+                        func=ast.Attribute(
+                            value=ast.Name(id="QgsMessageLog", ctx=ast.Load()),
+                            attr="logMessage",
+                            ctx=ast.Load(),
+                        ),
+                        args=[
+                            message,
+                            ast.Constant(value="Plugin"),
+                            ast.Attribute(
+                                value=ast.Name(id="Qgis", ctx=ast.Load()),
+                                attr="Info",
+                                ctx=ast.Load(),
+                            ),
+                        ],
+                        keywords=[],
+                    )
+                )
+                return new_call
+        return node
+
+
+class I18nTransformer(ast.NodeTransformer):
+    """AST transformer that wraps UI strings in self.tr() for internationalization.
+
+    Attributes:
+        changes_made: Boolean flag indicating if any changes were applied.
+        i18n_methods: Set of method names that accept strings for UI display.
+    """
+
+    def __init__(self) -> None:
+        """Initializes the transformer state."""
+        self.changes_made = False
+        self.i18n_methods = {
+            "setText",
+            "setWindowTitle",
+            "setTitle",
+            "setToolTip",
+            "setPlaceholderText",
+            "setTabText",
+        }
+
+    def visit_Call(self, node: ast.Call) -> ast.Call:
+        # Check if it's a UI method call with a string literal
+        if isinstance(node.func, ast.Attribute):
+            if node.func.attr in self.i18n_methods:
+                # Check if first argument is a string literal
+                if node.args and isinstance(node.args[0], ast.Constant):
+                    if isinstance(node.args[0].value, str):
+                        val = node.args[0].value
+                        # Skip empty strings or placeholders
+                        if val.strip() and not val.startswith("%"):
+                            self.changes_made = True
+                            # Wrap in self.tr()
+                            node.args[0] = ast.Call(
+                                func=ast.Attribute(
+                                    value=ast.Name(id="self", ctx=ast.Load()),
+                                    attr="tr",
+                                    ctx=ast.Load(),
+                                ),
+                                args=[ast.Constant(value=val)],
+                                keywords=[],
+                            )
+        self.generic_visit(node)
+        return node
+
+
+def apply_transformation(file_path: pathlib.Path, transformer: ast.NodeTransformer) -> bool:
+    """Applies an AST transformation to a file and writes back the modified code.
+
+    Args:
+        file_path: Path to the Python file to transform.
+        transformer: The AST node transformer to apply.
+
+    Returns:
+        True if the file was modified, False otherwise.
+    """
+    try:
+        content = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(content)
+
+        # Apply transformation
+        new_tree = transformer.visit(tree)
+        ast.fix_missing_locations(new_tree)
+
+        if hasattr(transformer, "changes_made") and transformer.changes_made:
+            # Unparse back to code
+            new_code = ast.unparse(new_tree)
+
+            # Add necessary imports if needed
+            if hasattr(transformer, "needs_import") and transformer.needs_import:
+                if "from qgis.core import QgsMessageLog, Qgis" not in new_code:
+                    new_code = "from qgis.core import QgsMessageLog, Qgis\n\n" + new_code
+
+            file_path.write_text(new_code, encoding="utf-8")
+            return True
+
+        return False
+    except Exception as e:
+        print(f"Error transforming {file_path}: {e}")
+        return False

analyzer/utils/__init__.py

@@ -0,0 +1,39 @@
+"""Utilities package for the QGIS Plugin Analyzer."""
+
+from .ast_utils import (
+    calculate_complexity,
+    calculate_module_complexity,
+    check_main_guard,
+    extract_classes_from_ast,
+    extract_functions_from_ast,
+    extract_imports_from_ast,
+)
+from .config_utils import _minimal_toml_load, load_profile_config
+from .logging_utils import logger, setup_logger
+from .path_utils import (
+    DEFAULT_EXCLUDE,
+    IgnoreMatcher,
+    load_ignore_patterns,
+    safe_path_resolve,
+)
+from .performance_utils import LRUCache, ProgressTracker, timeout_manager
+
+__all__ = [
+    "calculate_complexity",
+    "extract_functions_from_ast",
+    "extract_classes_from_ast",
+    "extract_imports_from_ast",
+    "calculate_module_complexity",
+    "check_main_guard",
+    "setup_logger",
+    "logger",
+    "safe_path_resolve",
+    "IgnoreMatcher",
+    "load_ignore_patterns",
+    "DEFAULT_EXCLUDE",
+    "load_profile_config",
+    "_minimal_toml_load",
+    "LRUCache",
+    "ProgressTracker",
+    "timeout_manager",
+]

analyzer/utils/ast_utils.py

@@ -0,0 +1,133 @@
+"""AST utilities for Python code analysis.
+
+This module provides helper functions for extracting information and calculating
+metrics from Python Abstract Syntax Trees (AST).
+"""
+
+import ast
+from typing import Any, Dict, List
+
+
+def calculate_complexity(node: ast.AST) -> int:
+    """Calculates Cyclomatic Complexity for a node.
+
+    Args:
+        node: The AST node to analyze.
+
+    Returns:
+        The cyclomatic complexity score.
+    """
+    complexity = 1
+    for child in ast.walk(node):
+        if isinstance(
+            child,
+            (
+                ast.If,
+                ast.For,
+                ast.While,
+                ast.And,
+                ast.Or,
+                ast.ExceptHandler,
+                ast.With,
+                ast.AsyncWith,
+            ),
+        ):
+            complexity += 1
+    return complexity
+
+
+def extract_functions_from_ast(tree: ast.AST) -> List[Dict[str, Any]]:
+    """Extracts function information from AST.
+
+    Args:
+        tree: The AST tree root.
+
+    Returns:
+        A list of dictionaries containing function metadata (name, args, line, complexity, etc.).
+    """
+    functions = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            func_complexity = calculate_complexity(node)
+            functions.append(
+                {
+                    "name": node.name,
+                    "args": [arg.arg for arg in node.args.args],
+                    "line": node.lineno,
+                    "end_line": getattr(node, "end_lineno", node.lineno),
+                    "complexity": func_complexity,
+                    "docstring": ast.get_docstring(node) is not None,
+                }
+            )
+    return functions
+
+
+def extract_classes_from_ast(tree: ast.AST) -> List[str]:
+    """Extracts class information from AST.
+
+    Args:
+        tree: The AST tree root.
+
+    Returns:
+        A list of class signatures (e.g., "ClassName(BaseClass)").
+    """
+    classes = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            bases = [ast.unparse(b) for b in node.bases]
+            classes.append(f"{node.name}({', '.join(bases)})" if bases else node.name)
+    return classes
+
+
+def extract_imports_from_ast(tree: ast.AST) -> List[str]:
+    """Extracts import information from AST.
+
+    Args:
+        tree: The AST tree root.
+
+    Returns:
+        A sorted list of imported module names.
+    """
+    imports: list[str] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imports.extend(n.name for n in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            if node.module:
+                imports.append(node.module)
+    return sorted(set(imports))
+
+
+def calculate_module_complexity(tree: ast.AST) -> int:
+    """Calculates module-level complexity based on decision points.
+
+    Args:
+        tree: The AST tree root.
+
+    Returns:
+        The module-level complexity score.
+    """
+    complexity = 1
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.If, ast.For, ast.While, ast.And, ast.Or, ast.ExceptHandler)):
+            complexity += 1
+    return complexity
+
+
+def check_main_guard(tree: ast.AST) -> bool:
+    """Checks if module has __name__ == '__main__' guard.
+
+    Args:
+        tree: The AST tree root.
+
+    Returns:
+        True if the main guard is found, False otherwise.
+    """
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If):
+            if isinstance(node.test, ast.Compare) and isinstance(node.test.left, ast.Name):
+                if node.test.left.id == "__name__":
+                    for cmp in node.test.comparators:
+                        if isinstance(cmp, ast.Constant) and cmp.value == "__main__":
+                            return True
+    return False