👉 View Full Rules Catalog (RULES.md)

Quality Metrics:

The QGIS Plugin Analyzer is a static analysis tool designed specifically for QGIS (PyQGIS) plugin developers. Its goal is to elevate plugin quality by ensuring they follow community best practices and are optimized for AI-assisted development.

• Security Core (Bandit-inspired): Professional vulnerability scanning detecting eval, exec, shell injections, and SQL injection risks.
• Deep Entropy Secret Scanner: Detects hardcoded API keys, passwords, and sensitive tokens using regex and information entropy.
• High-Performance Engine: Parallel analysis powered by ProcessPoolExecutor with single-pass AST traversal and shared worker context.
• Project Auto-Detection: Intelligently distinguishes between official QGIS Plugins and Generic Python Projects, tailoring validation logic accordingly.
• Advanced Ignore Engine: Robust .analyzerignore support with non-anchored patterns and smart default excludes (.venv, build, etc.).
• Deep Semantic Analysis: Cross-file dependency graphing (Mermaid), circular import detection, and module coupling metrics.
• Interactive Auto-Fix Mode: Automatically fix common QGIS issues (GDAL imports, PyQt bridge, logging, i18n) with safety checks.
• Official Repository Compliance: Proactive validation of binaries, package size, and metadata URLs.
• Real-time Progress: CLI feedback with a progress bar and ETA tracking.
• Enhanced Configuration Profiles: Rule-level severity control (error, warning, info, ignore) via pyproject.toml.
• Integrated Ruff Analysis: Combines custom QGIS rules with the fastest linter in the Python ecosystem.
• Qt Resource Validation: Detect missing or broken resource paths (:/plugins/...) in your code.
• Extended Safety Audit: Detection of signal leaks, missing slots, and UI-blocking loops (QgsTask suggestions).
• Embedded Web Server: View reports instantly with the built-in serve command.
• AI-Ready: Generates structured summaries and optimized contexts for LLMs.
• Zero Runtime Dependencies: Works using only the Python standard library (Ruff as an external tool).

Robust Project Discovery & Dynamic Versioning - Major improvements to the core engine and project identification logic:

• 📁 Bulletproof Project Detection - Fixed a critical issue where QGIS plugins were incorrectly identified as generic projects if metadata.txt was listed in .analyzerignore. Metadata detection now correctly prioritizes plugin identification over ignore rules.
• 🔄 Dynamic Versioning - The analyzer now uses a dynamic versioning system that automatically stays in sync with pyproject.toml, ensuring accuracy across all interfaces without hardcoded values.
• 🧹 Clean Analysis Logs - Removed redundant project type reporting to provide a more focused and professional terminal output.

From v1.10.1:

• ⚡ Async Support - Full AST support for AsyncFunctionDef in metrics calculations.

📖 Full Release Notes | 🗺️ CLI Commands Roadmap

1. Shift Left (Run Locally): The biggest advantage is being able to run the same high-standard checks as the Official Repository before you upload your plugin. No more "reject-fix-upload" loops.
2. High-Performance Hybrid Engine: Combines multi-core AST processing with deep understanding of cross-file relationships and Qt-specific patterns.
3. Safety-First Auto-Fixing: AST-based transformations with Git status verification and interactive diff previews.
4. Zero Runtime Stack: Minimal footprint, ultra-fast execution, and easy CI integration.
5. AI-Centric Design: Built to help developers and AI agents understand complex QGIS plugins instantly.

If you have uv installed, you can install the analyzer quickly and in isolation:

1. As a global tool (isolated):

uv tool install git+https://github.com/geociencio/qgis-plugin-analyzer.git

2. Standard pip installation (Git):

pip install git+https://github.com/geociencio/qgis-plugin-analyzer.git

2. Local installation for development:

git clone https://github.com/geociencio/qgis-plugin-analyzer
cd qgis-plugin-analyzer
uv sync

pip install .

1. Analyze a Plugin (Full Analysis):

qgis-analyzer analyze /path/to/your/plugin -o ./quality_report

2. Specialized Analysis (NEW in v1.9.0):

# Internationalization audit only
qgis-analyzer analyze i18n /path/to/your/plugin

# Security vulnerability scanning only
qgis-analyzer analyze security /path/to/your/plugin

# Performance and UI blocking detection only
qgis-analyzer analyze performance /path/to/your/plugin

# Dependency and coupling analysis only
qgis-analyzer analyze architecture /path/to/your/plugin

# QGIS metadata validation only
qgis-analyzer analyze metadata /path/to/your/plugin

3. Auto-Fix issues (Dry Run):

qgis-analyzer fix /path/to/your/plugin

4. Legacy Support: The default command remains analysis if no subcommand is specified:

qgis-analyzer /path/to/your/plugin

You can run qgis-plugin-analyzer automatically before every commit to ensure quality. Add this to your .pre-commit-config.yaml:

  - repo: https://github.com/geociencio/qgis-plugin-analyzer
    rev: main  # Use 'main' for latest features or a specific tag like v1.5.0
    hooks:
      - id: qgis-plugin-analyzer

Use it directly in your CI/CD workflows:

steps:
  - uses: actions/checkout@v4
  - name: Run QGIS Quality Check
    uses: geociencio/qgis-plugin-analyzer@main
    with:
      path: .
      output: quality_report
      args: --profile release

You can customize the analyzer's behavior using a [tool.qgis-analyzer] section in your pyproject.toml.

[tool.qgis-analyzer]
# Profiles allow different settings for CI vs Local
[tool.qgis-analyzer.profiles.default]
strict = false
generate_html = false  # CLI default

[tool.qgis-analyzer.profiles.release]
strict = true
fail_on_error = true

[tool.qgis-analyzer.profiles.default.rules]
QGS101 = "error"    # Ban specific module imports
QGS105 = "warning"  # Warn on iface usage
QGS303 = "ignore"   # Ignore resource path checks

This tool performs Static Analysis (AST & Regex parsing). It does not execute your code or load QGIS libraries.

• Dynamic Imports: Imports inside functions or conditional blocks might be analyzed differently than top-level imports.
• Runtime Validation: Checks like "Missing Resources" rely on static string analysis of .qrc files and path strings. It cannot verify resources loaded dynamically at runtime.
• False Positives: While we strive for accuracy, complex meta-programming or unusual patterns might trigger false positives. Use # noqa or .analyzerignore to handle these cases.

Note: The Python package is named qgis-plugin-analyzer, but the command-line tool is installed as qgis-analyzer.

Audits an existing QGIS plugin repository with optional specialized scopes.

NEW in v1.9.0: Specialized analysis scopes for targeted auditing.

Available Scopes:

• i18n - Internationalization and translation audit (detects untranslated strings)
• security - Security vulnerability scanning (unsafe calls, hardcoded secrets, SQL injection)
• performance - Performance and UI blocking detection (blocking loops, missing indexes)
• architecture - Dependency and coupling analysis (imports, QGIS API usage)
• metadata - QGIS metadata validation (metadata.txt compliance)
• all or no scope - Full analysis (default, legacy compatible)

Arguments:

Examples:

# Full analysis (legacy compatible)
qgis-analyzer analyze .
qgis-analyzer analyze /path/to/plugin

# Specialized i18n analysis
qgis-analyzer analyze i18n .

# Security-only scan with reports
qgis-analyzer analyze security . --report

Automatically fix common QGIS issues identified during analysis.

Shows a professional, color-coded summary of findings directly in your terminal.

Performs a focused security scan on a file or directory.

Shows the current version of the analyzer.

Example:

# Executive summary
qgis-analyzer summary

# Identify high-complexity functions
qgis-analyzer summary --by functions

Displays the full catalog of implemented QGIS audit rules with their severity and descriptions.

Visualizes the project's dependency graph.

Starts a local web server to view the generated HTML reports.

Initializes a recommended .analyzerignore file in the current directory with common Python and QGIS development exclusions.

• project_context.json: Full structured data for external integrations.

For a complete list of all implemented checks, their severity, and recommendations, please refer to the:

👉 Detailed Rules Catalog (RULES.md)

The development of this analyzer is based on official QGIS community guidelines, geospatial standards, and industry best practices:

• PyQGIS Developer Cookbook: The primary resource for PyQGIS API usage and standards.
• QGIS Plugin Repository Requirements: Mandatory criteria for plugin approval in the official repository.
• QGIS Coding Standards: Core style and organization guidelines for the QGIS project.
• QGIS HIG (Human Interface Guidelines): Standards for consistent and accessible user interface design.
• QGIS Security Scanning Documentation: Official guide on automated security analysis (Bandit, detect-secrets) for plugins.

• flake8-qgis Rules: Community-driven linting rules for PyQGIS (QGS101-106).
• PEP 8 Style Guide: The fundamental style guide for Python code.
• PEP 257 Docstring Conventions: Standards for docstring structure and content.
• Maintainability Index (SEI): Methodology for measuring software maintainability.
• Conventional Commits: Standard for clear, machine-readable commit history.
• Keep a Changelog: Best practices for maintainable version history.

• Bandit (PyCQA): The security rules implemented (B1xx - B6xx) are directly derived from the Bandit project's rule set for identifying common security issues in Python code.
• CWE (Common Weakness Enumeration): Security findings are mapped to standard CWE IDs (e.g., CWE-78 Command Injection, CWE-89 SQL Injection) for industry-standard classification.
• OWASP Top 10: The "Hardcoded Secret" and "Injection" checks align with critical OWASP vulnerabilities.

• Detailed Rules Catalog: Full documentation of all audit rules implemented in this analyzer.
• Standardized Scoring Metrics: Mathematical logic and thresholds for project evaluation.
• Project Roadmap: Current status and future plans for the analyzer.
• Documentation Folder: Historical release notes, competitive analysis, and modernization guides.

Contributions are welcome! Please refer to our Contributing Guide to learn how to report bugs, propose rules, and submit code changes.

Audit rules are located in src/analyzer/scanner.py. Feel free to add new rules following the existing pattern!

This project is licensed under the GNU General Public License v3 (GPL v3). See the LICENSE file for details.

Developed for the SecInterp team and the QGIS community.