Code Quality Scanning

Codity scans pull request diffs for code quality issues and posts findings as review comments. Scanning runs in two phases: a fast pattern-based pass followed by an optional LLM-based analysis.

Overview

Every time a PR is opened or updated, Codity analyzes the changed lines and reports issues across eight quality categories:

Complexity: oversized functions, deep nesting, high cyclomatic complexity
Duplication: copy-pasted blocks, DRY violations
Error handling: bare except, swallowed exceptions, missing null checks
Performance: N+1 queries, blocking I/O in async contexts, unnecessary loops
Documentation: missing docstrings or JSDoc for public APIs
Testability: global state mutation, hard-coded dependencies
Maintainability: magic numbers, poorly named variables, dead code
Style: lines exceeding 120 characters

Two-Phase Analysis

Phase 1: Pattern Detection

Phase 1 runs on every PR using static pattern matching. It is fast and deterministic.

Rule	Category	Severity	What it checks
CQ-001	Complexity	High	Functions adding more than 50 lines
CQ-002	Complexity	Medium	Nesting depth of 5 or more levels
CQ-003	Error Handling	High	Bare `except` or empty `catch` blocks
CQ-004	Error Handling	High	Exception caught and swallowed with `pass`
CQ-005	Maintainability	Low	`TODO`, `FIXME`, or `HACK` comments
CQ-006	Performance	Medium	`SELECT *` or `.all()` called inside a loop
CQ-007	Documentation	Low	Public function missing a docstring
CQ-008	Maintainability	Low	Magic numbers used directly in code
CQ-009	Style	Low	Lines longer than 120 characters
CQ-010	Testability	Medium	Global variable mutation
CQ-011	Duplication	Low	Duplicate import statements
CQ-012	Performance	High	Synchronous I/O (`open`, `requests.get`, `sleep`) in an async context

Phase 2: LLM Analysis

Phase 2 uses an LLM to review the same diff with deeper reasoning. It catches nuanced issues that pattern matching misses, such as subtle logic errors, architectural concerns, and context-dependent duplication.

Phase 2 is available when a custom LLM API key (BYOK) is configured. Without BYOK, Codity scans up to 10 files per PR using its built-in model. With BYOK, up to 50 files are scanned.

Quality Score

Every scan produces a score from 0 to 100. It starts at 100 and decays based on the number and severity of findings.

Penalty Weights

Severity	Penalty per finding
Critical	10
High	5
Medium	2
Low / Info	0.5

Formula

penalty = (critical × 10) + (high × 5) + (medium × 2) + (low × 0.5)
score   = max(0, round(100 × (1 / (1 + penalty / 20))))

This is a harmonic decay, not linear subtraction. Here is why each part exists:

1 +: prevents division by zero when penalty is 0, and sets the clean baseline. With zero findings the denominator is 1, giving 100 / 1 = 100. Every unit of penalty is measured relative to that 1.
penalty / 20: the 20 is the pivot point. When total penalty equals 20, the denominator becomes 2 and the score halves to 50. This means two critical issues (or four high issues) put you at exactly 50.
Harmonic decay: each additional finding hurts less than the previous one. Going from 0 to 1 critical issue drops the score by 33 points. Going from 10 to 11 critical issues drops it by roughly 1 point. This reflects reality: the gap between a clean codebase and one with a single critical issue is far more meaningful than the gap between a very poor codebase and a slightly worse one.
max(0, ...): a safety floor. The formula asymptotically approaches zero but never actually reaches it, so this guard exists only for floating-point edge cases.

Example scores

Findings	Score
None	100
1 critical	67
2 critical	50
1 critical + 2 high	43
4 high + 5 medium	33

Finding Severity Levels

Each finding is assigned one of five severity levels:

Severity	Description
Critical	Must be fixed before merge
High	Significant quality or correctness risk
Medium	Should be addressed soon
Low	Minor quality concern
Info	Informational, no action required

Whole-Repository Scanning

In addition to PR-level scanning, Codity supports scanning your entire repository. Whole-repository scans require a custom LLM API key and scan up to 50 files at a time.

To enable whole-repository scanning:

Go to Settings in the Codity dashboard.
Enable Whole Repository Scan.
Enter your custom LLM API key and select the provider (OpenAI, Anthropic, or Google).

Bring Your Own Key (BYOK)

To configure BYOK:

Go to Settings in the Codity dashboard.
Enter your API key under Custom LLM API Key.
Select the provider.
Save settings.

Downloading Reports

Quality scan reports can be downloaded from the dashboard in two formats:

Markdown (.md): human-readable report
JSON (.json): machine-readable for integration with other tools

Next Steps

Configure which repositories are scanned: Auto-Review Configuration
Set up policy checks to enforce test file requirements: Policy Checks

PreviousPull Requests NextArchitecture Diagram & Connection Details