Metadata-Version: 2.4
Name: ruff-score
Version: 0.2.1
Summary: A Pylint-style scoring system for Ruff linter output
Project-URL: Homepage, https://github.com/AISHIK999/ruff-score
Project-URL: Repository, https://github.com/AISHIK999/ruff-score
Project-URL: Issues, https://github.com/AISHIK999/ruff-score/issues
Author-email: Aishik Mukherjee <aishikm2002@gmail.com>
License: MIT
License-File: LICENSE.md
Keywords: code-quality,linter,pylint,ruff,scoring
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Requires-Dist: build>=1.2.2.post1
Requires-Dist: ruff>=0.12.0
Requires-Dist: twine>=6.1.0
Description-Content-Type: text/markdown

# Ruff Score 🎯

A Pylint‑style scoring system for Ruff linter output. Get a numerical quality score (0‑10) for your Python code based on Ruff's analysis, with fine‑grained rule mapping and customizable severity weights.

## Features

- 🎯 **Pylint‑inspired scoring**: A familiar 0‑10 quality score, but improved to be more sensitive to real issues.
- 🔧 **Ruff integration**: Built on the fast Ruff linter – just point it at a file or directory.
- 🗂️ **Full rule coverage**: Every Ruff prefix (E, F, PLE/PLC/PLR/PLW, ASYNC, S, TRY, RUF, and 40+ more) is mapped to a Pylint‑style category and severity weight.
- ⚖️ **Two‑level weighting**: Issues are bucketed into `error` / `warning` / `convention` / `refactor`, and within a category individual rules can carry different weights (e.g. a security finding counts more than a stray `print`).
- 📊 **Per‑file averaging**: Directory scores are the average of each file’s score – so a few problem files can’t hide behind a pile of clean code.
- 📁 **File & directory support**: Analyze single files or whole projects.
- ⚙️ **Configurable**: Use your existing Ruff configuration file, and override weights/categories in Python.

## Installation

```bash
pip install ruff-score
```

## Quick Start
```python
from ruff_score import RuffScorer

scorer = RuffScorer()

# Score a single file
result = scorer.score_file("myfile.py")
print(f"Score: {result['score']:.2f}/10.00")

# Score a directory (averages per‑file scores)
result = scorer.score_directory("src/")
scorer.print_report(result)

# Score against a specific Ruff config
result = scorer.score_directory("src/", config_file="pyproject.toml")
```

## How It Works
Ruff Score uses the Pylint‑style formula, but with a more sensitive penalty:

```text
Score = 10.0 - ((error_multiplier * errors + warnings + refactor + convention) / denominator * 10)
```

Where:

denominator is the number of non‑blank, non‑comment lines of code (by default). This makes each issue affect the score more than counting AST statements. You can switch back to statement counting by passing use_lines=False to the constructor.

error_multiplier is configurable and defaults to 10 (was 5 in the original Pylint formula). This amplifies the impact of real bugs.

## Score Interpretation:
9.0‑10.0: Excellent code quality (10.0 means no issues at all

7.0‑8.9: Good code quality

5.0‑6.9: Needs improvement

0.0‑4.9: Poor code quality

## Example Output
```text
==================================================
RUFF QUALITY SCORE REPORT
==================================================
Target: src/
Score: 7.85/10.00
Total lines analyzed: 1,247
Files analyzed: 23
Total issues: 12

Issues by category:
  Error: 0
  Warning: 3
  Convention: 8
  Refactor: 1

Good code quality
```

## Advanced Usage
Custom Weights and Categories
```python
from ruff_score import RuffScorer

# Change the fallback used for any rule prefix not in the tables
scorer = RuffScorer(default_weight=2, default_category="warning")

# Override the weight or category for a specific prefix
scorer.RULE_WEIGHTS["D"] = 1        # docstring issues
scorer.RULE_CATEGORIES["D"] = "convention"

# Adjust the error multiplier (default is 10)
scorer.error_multiplier = 15

# Switch to statement‑based denominator (AST nodes)
scorer.use_lines = False

# Inspect how a given rule code resolves
scorer.get_rule_weight("S608")      # -> 4
scorer.get_rule_category("S608")    # -> "warning"
```

## Integration with CI/CD
```python
# check_quality.py
import sys
from ruff_score import RuffScorer

scorer = RuffScorer()
result = scorer.score_directory("src/")
scorer.print_report(result)

THRESHOLD = 7.0
sys.exit(0 if result["score"] >= THRESHOLD else 1)
bash
python check_quality.py && echo "Quality check passed!" || echo "Quality check failed!"
```

## Configuration
Ruff Score respects your existing Ruff configuration by passing it straight through to ruff check --config. Place your settings in:

- pyproject.toml
- ruff.toml
- .ruff.toml

## Example configuration:

```toml
[tool.ruff]
line-length = 88
target-version = "py38"

[tool.ruff.lint]
select = ["E", "F", "W", "C", "N", "D", "S", "B"]
ignore = ["E501", "D100"]
```

## Requirements
- Python 3.8+
- Ruff installed and available on your PATH

## License
MIT License – see LICENSE file for details.

## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.

## Related Projects
Ruff – The fast Python linter
Pylint – The original Python code quality tool
