scrut: A Lightweight Static Analysis Tool for Python Code Review

Scrut is an efficient, Git-aware static analysis command-line interface (CLI) designed specifically for Python development. Its core function is to enhance code quality by enabling developers to review changes before pushing them to the repository, focusing only on code that is actively being modified rather than legacy files. This reduces noise and facilitates a clearer understanding of potential issues introduced with each commit.

Key Features

• Targeted Review Sets: Unlike many static analysis tools that scan entire repositories, Scrut relies on Git to dynamically calculate the review set based on the latest changes (git diff HEAD --name-only) and includes newly created files that are not yet tracked.
• Exact Metrics: By utilizing the standard ast module, Scrut precisely measures code quality metrics such as parameter counts and nesting depth, ensuring that the analysis results are accurate and meaningful.
• Error Management: The tool categorizes unreadable or syntactically incorrect files as ERROR entries but continues to analyze other files. This approach ensures that issues are easily identifiable without disrupting the review process.
• Non-intrusive Operation: Scrut does not impose any gating mechanism with error codes. Instead, it provides comprehensive feedback with an exit code of 0, allowing developers to make corrections based on the findings before committing.
• Performance: Built solely on standard library components, Scrut runs without the need for additional daemons or network calls, making it lightweight and efficient.

Usage Example

Running Scrut is straightforward. Simply navigate to the repository and invoke the command:

cd your-repo
# After making your changes...
scrut

When executed, Scrut generates a detailed review report summarizing the state of the changed code, listing warnings, errors, and metrics checked. For example:

$ scrut

scrut [Review Summary]
╔═════════════════════════════════════════╗
║ 🟡 3 warnings      │ 📊 3 funcs checked ║
╚═════════════════════════════════════════╝

[NEEDS REVIEW] ────────────────────────────────────────────────────────────

╭─ ⚠️ buggy.py (3)
│  Component  Kind  Rule                                         Metric
│  ────────────────────────────────────────────────────────────────────
│  handle     func  Nesting too deep                                5/4
│  fake       func  Async function contains no await expression  detected
│  extra      func  Too many parameters                             6/5

Configuration Options

Configuring Scrut is both simple and flexible. Users can create a scrut.toml configuration file to adjust thresholds for different analysis rules, allowing customization based on team coding standards:

[limits]   # numeric thresholds per rule
max_parameters          = 4
max_nesting             = 5
max_function_lines      = 50
[rules]
max_parameters          = true
max_nesting             = false
max_function_lines      = false

Enhanced Code Quality

By focusing on the specific changes in the codebase and providing actionable insights, Scrut assists developers in maintaining high code quality standards. It complements typical pre-push workflows, ensuring that developers not only identify issues but also improve their coding practices incrementally.

Conclusion

Scrut is an essential tool for Python developers looking to enhance their code review processes through precise static analysis that’s quick, easy to implement, and integrated seamlessly into existing workflows.