pyscn - Python Code Quality Analyzer

pyscn is a code quality analyzer for Python vibe coders.

Building with Cursor, Claude, or ChatGPT? pyscn performs structural analysis to keep your codebase maintainable.

Quick Start

# Run analysis without installation
uvx pyscn analyze .
# or
pipx run pyscn analyze .

Demo

https://github.com/user-attachments/assets/07f48070-c0dd-437b-9621-cb3963f863ff

Features

• 🔍 CFG-based dead code detection – Find unreachable code after exhaustive if-elif-else chains
• 📋 Clone detection with APTED + LSH – Identify refactoring opportunities with tree edit distance
• 🔗 Coupling metrics (CBO) – Track architecture quality and module dependencies
• 📊 Cyclomatic complexity analysis – Spot functions that need breaking down

100,000+ lines/sec • Built with Go + tree-sitter

Common Commands

pyscn analyze

Run comprehensive analysis with HTML report

pyscn analyze .                              # All analyses with HTML report
pyscn analyze --json .                       # Generate JSON report
pyscn analyze --select complexity .          # Only complexity analysis
pyscn analyze --select deps .                # Only dependency analysis
pyscn analyze --select complexity,deps,deadcode . # Multiple analyses

pyscn check

Fast CI-friendly quality gate

pyscn check .                      # Quick pass/fail check
pyscn check --max-complexity 15 .  # Custom thresholds

pyscn init

Create configuration file

pyscn init                         # Generate .pyscn.toml

💡 Run pyscn --help or pyscn <command> --help for complete options

Configuration

Create a .pyscn.toml file or add [tool.pyscn] to your pyproject.toml:

# .pyscn.toml
[complexity]
max_complexity = 15

[dead_code]
min_severity = "warning"

[output]
directory = "reports"

⚙️ Run pyscn init to generate a full configuration file with all available options

Installation

# Install with pipx (recommended)
pipx install pyscn

# Or run directly with uvx
uvx pyscn

Alternative installation methods

Build from source

git clone https://github.com/ludo-technologies/pyscn.git
cd pyscn
make build

Go install

go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest

CI/CD Integration

# .github/workflows/code-quality.yml
name: Code Quality
on: [push, pull_request]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install pyscn
      - name: Quick quality check
        run: pyscn check .
      - name: Generate detailed report
        run: pyscn analyze --json --select complexity,deadcode,deps src/
      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: code-quality-report
          path: .pyscn/reports/

---

Documentation

📚 Development Guide • Architecture • Testing

License

MIT License — see LICENSE

---

Built with ❤️ using Go and tree-sitter