@codacy/tools-prospector-1

Table of Contents

• Overview
• Updating patterns
• Updating the Prospector version
• Development
• Notes for maintainers

Overview

Prospector is a meta-tool for Python static analysis that orchestrates multiple linters (pylint, pyflakes, pycodestyle, mccabe, dodgy, pydocstyle) and optional tools (bandit, mypy, vulture, pyroma, pyright), running them against the same codebase and merging their output with cross-tool deduplication ("blending").

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

Updating the Prospector version

1. Update preferredVersion and PIP_PACKAGES version pin in src/adapter.ts
2. Update pinned pylint/mypy versions if the Codacy wrapper changes them
3. Run pnpm prefetch to check for new/removed sub-tools
4. Run pnpm test to verify compatibility
5. If the major version changes, create a new adapter package (prospector-2/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests

To run integration tests locally, install prospector:

pip install prospector[with_everything]==1.19.1

Notes for maintainers

• Meta-tool architecture: Prospector wraps multiple sub-tools. Patterns are tool-level (e.g. Prospector_pylint), not per-rule. The source field in Prospector's JSON output identifies which sub-tool produced each message.

• Blending: Prospector deduplicates equivalent messages across tools (e.g. pylint's unused-import and pyflakes' F401). The adapter runs with blending enabled (default) to match the existing Codacy wrapper behavior.

• Denylist codes: Messages with codes failure, django-not-configured, and import-error are filtered out, matching the existing wrapper.

• File chunking: Files are processed in chunks of 50 per invocation to avoid command-line length limits.

• Framework detection: The adapter uses --no-autodetect for deterministic behavior. Django/Flask/Celery plugins are not auto-loaded.

• Overlap with standalone adapters: Since Prospector wraps pylint, pyflakes, etc., there is overlap with standalone adapters (e.g. pylint-4, bandit-1). Prospector's sub-tool versions may differ from standalone adapter versions. Users should choose one approach per tool, not both.

• Column numbers: Some sub-tools (mccabe, dodgy) report null for columns. Since Issue.column is required, the adapter defaults to column 1 when the sub-tool does not report a column offset.