ruff-legibility 0.1.0__tar.gz

ruff_legibility-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+.coverage*
+htmlcov/
+build/
+dist/
+*.egg-info/
+
+# Beads / Dolt files (added by bd init)
+.dolt/
+*.db
+.beads-credential-key
+.claude/
+CLAUDE.md
+.beads/
+venv/
+*.pyc

ruff_legibility-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeffry Wainwright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ruff_legibility-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: ruff-legibility
+Version: 0.1.0
+Summary: Ruff-adjacent Python legibility rules for readable, reviewable code.
+Project-URL: Homepage, https://github.com/yowainwright/ruff-legibility
+Project-URL: Issues, https://github.com/yowainwright/ruff-legibility/issues
+Project-URL: Repository, https://github.com/yowainwright/ruff-legibility
+Author: Jeffry Wainwright
+License-Expression: MIT
+License-File: LICENSE
+Keywords: legibility,lint,python,readability,ruff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ruff-legibility
+
+[![PyPI version](https://img.shields.io/pypi/v/ruff-legibility.svg)](https://pypi.org/project/ruff-legibility/)
+[![CI](https://github.com/yowainwright/ruff-legibility/actions/workflows/ci.yml/badge.svg)](https://github.com/yowainwright/ruff-legibility/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/yowainwright/ruff-legibility/badge)](https://scorecard.dev/viewer/?uri=github.com/yowainwright/ruff-legibility)
+
+`ruff-legibility` is a Ruff-adjacent Python linter for readability and reviewability rules inspired by `eslint-plugin-legibility`.
+
+Ruff does not currently load third-party rule implementations from Python packages. This package therefore runs beside Ruff and emits Ruff-style diagnostics with `LEG###` codes.
+
+```sh
+ruff check .
+ruff-legibility check .
+```
+
+To keep `# noqa: LEG001` comments valid when Ruff checks unused or unknown `noqa` codes, add `LEG` as an external prefix in Ruff:
+
+```toml
+[tool.ruff.lint]
+external = ["LEG"]
+```
+
+## Install
+
+```sh
+pip install ruff-legibility
+```
+
+For local development:
+
+```sh
+uv sync --all-groups
+make check
+```
+
+## Usage
+
+```sh
+ruff-legibility check .
+ruff-legibility check src tests --output-format json
+ruff-legibility check . --select LEG001,LEG002 --ignore LEG007
+ruff-legibility check . --exit-zero
+```
+
+Default text output is intentionally close to Ruff:
+
+```text
+example.py:4:8: LEG002 If condition has 2 boolean operators (max 0). Hoist it into a named boolean.
+```
+
+## Configuration
+
+Configuration can live in `pyproject.toml` under `[tool.ruff-legibility]`, or in `ruff-legibility.toml` / `.ruff-legibility.toml`.
+
+```toml
+[tool.ruff-legibility]
+select = ["LEG"]
+extend-select = []
+ignore = ["LEG007"]
+extend-ignore = []
+exclude = [".venv", "build", "dist"]
+max-expression-operators = 4
+max-if-operators = 0
+max-ternary-operators = 2
+max-control-flow-depth = 3
+
+[tool.ruff-legibility.per-file-ignores]
+"tests/*" = ["LEG003"]
+```
+
+Standalone config files omit the `tool.ruff-legibility` wrapper:
+
+```toml
+select = ["LEG"]
+ignore = ["LEG007"]
+```
+
+This repository includes a `ruff-legibility.toml` for its own source. The default package thresholds stay stricter than the project-local development config.
+
+## Rules
+
+| Code | Rule | Default |
+| --- | --- | --- |
+| `LEG001` | Limit readability operators inside a single expression. | on |
+| `LEG002` | Prefer a named boolean before operator-heavy `if` / `while` conditions. | on |
+| `LEG003` | Limit nested control-flow depth. | on |
+| `LEG004` | Avoid complex ternary expressions. | on |
+| `LEG005` | Flag likely quadratic patterns such as nested loops and repeated membership checks in loops. | on |
+| `LEG006` | Avoid redundant boolean comparisons like `flag == True`. | on |
+| `LEG007` | Prefer positive condition names over names like `is_not_ready`. | on |
+
+## Pre-commit
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-legibility
+        name: ruff-legibility
+        entry: ruff-legibility check
+        language: system
+        types: [python]
+```
+
+## Development
+
+Common commands:
+
+```sh
+uv sync --all-groups
+uv run ruff check .
+uv run ruff-legibility check src tests
+uv run pytest
+uv build
+```
+
+Release builds should use:
+
+```sh
+uv build --no-sources
+```
+
+Publishing is configured for PyPI Trusted Publishing:
+
+```sh
+uv publish
+```

ruff_legibility-0.1.0/README.md

@@ -0,0 +1,127 @@
+# ruff-legibility
+
+[![PyPI version](https://img.shields.io/pypi/v/ruff-legibility.svg)](https://pypi.org/project/ruff-legibility/)
+[![CI](https://github.com/yowainwright/ruff-legibility/actions/workflows/ci.yml/badge.svg)](https://github.com/yowainwright/ruff-legibility/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/yowainwright/ruff-legibility/badge)](https://scorecard.dev/viewer/?uri=github.com/yowainwright/ruff-legibility)
+
+`ruff-legibility` is a Ruff-adjacent Python linter for readability and reviewability rules inspired by `eslint-plugin-legibility`.
+
+Ruff does not currently load third-party rule implementations from Python packages. This package therefore runs beside Ruff and emits Ruff-style diagnostics with `LEG###` codes.
+
+```sh
+ruff check .
+ruff-legibility check .
+```
+
+To keep `# noqa: LEG001` comments valid when Ruff checks unused or unknown `noqa` codes, add `LEG` as an external prefix in Ruff:
+
+```toml
+[tool.ruff.lint]
+external = ["LEG"]
+```
+
+## Install
+
+```sh
+pip install ruff-legibility
+```
+
+For local development:
+
+```sh
+uv sync --all-groups
+make check
+```
+
+## Usage
+
+```sh
+ruff-legibility check .
+ruff-legibility check src tests --output-format json
+ruff-legibility check . --select LEG001,LEG002 --ignore LEG007
+ruff-legibility check . --exit-zero
+```
+
+Default text output is intentionally close to Ruff:
+
+```text
+example.py:4:8: LEG002 If condition has 2 boolean operators (max 0). Hoist it into a named boolean.
+```
+
+## Configuration
+
+Configuration can live in `pyproject.toml` under `[tool.ruff-legibility]`, or in `ruff-legibility.toml` / `.ruff-legibility.toml`.
+
+```toml
+[tool.ruff-legibility]
+select = ["LEG"]
+extend-select = []
+ignore = ["LEG007"]
+extend-ignore = []
+exclude = [".venv", "build", "dist"]
+max-expression-operators = 4
+max-if-operators = 0
+max-ternary-operators = 2
+max-control-flow-depth = 3
+
+[tool.ruff-legibility.per-file-ignores]
+"tests/*" = ["LEG003"]
+```
+
+Standalone config files omit the `tool.ruff-legibility` wrapper:
+
+```toml
+select = ["LEG"]
+ignore = ["LEG007"]
+```
+
+This repository includes a `ruff-legibility.toml` for its own source. The default package thresholds stay stricter than the project-local development config.
+
+## Rules
+
+| Code | Rule | Default |
+| --- | --- | --- |
+| `LEG001` | Limit readability operators inside a single expression. | on |
+| `LEG002` | Prefer a named boolean before operator-heavy `if` / `while` conditions. | on |
+| `LEG003` | Limit nested control-flow depth. | on |
+| `LEG004` | Avoid complex ternary expressions. | on |
+| `LEG005` | Flag likely quadratic patterns such as nested loops and repeated membership checks in loops. | on |
+| `LEG006` | Avoid redundant boolean comparisons like `flag == True`. | on |
+| `LEG007` | Prefer positive condition names over names like `is_not_ready`. | on |
+
+## Pre-commit
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-legibility
+        name: ruff-legibility
+        entry: ruff-legibility check
+        language: system
+        types: [python]
+```
+
+## Development
+
+Common commands:
+
+```sh
+uv sync --all-groups
+uv run ruff check .
+uv run ruff-legibility check src tests
+uv run pytest
+uv build
+```
+
+Release builds should use:
+
+```sh
+uv build --no-sources
+```
+
+Publishing is configured for PyPI Trusted Publishing:
+
+```sh
+uv publish
+```

ruff_legibility-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ruff-legibility"
+version = "0.1.0"
+description = "Ruff-adjacent Python legibility rules for readable, reviewable code."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jeffry Wainwright" }]
+keywords = ["ruff", "lint", "legibility", "readability", "python"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.15",
+]
+
+[project.urls]
+Homepage = "https://github.com/yowainwright/ruff-legibility"
+Issues = "https://github.com/yowainwright/ruff-legibility/issues"
+Repository = "https://github.com/yowainwright/ruff-legibility"
+
+[project.scripts]
+ruff-legibility = "ruff_legibility.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ruff_legibility"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml", "ruff-legibility.toml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

ruff_legibility-0.1.0/ruff-legibility.toml

@@ -0,0 +1,3 @@
+select = ["LEG"]
+max-if-operators = 3
+max-control-flow-depth = 6

ruff_legibility-0.1.0/src/ruff_legibility/__init__.py

@@ -0,0 +1,13 @@
+"""Ruff-adjacent legibility checks for Python."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .core import Diagnostic, check_path, check_source
+from .rules import RULES
+
+__all__ = ["Diagnostic", "RULES", "check_path", "check_source"]
+
+try:
+    __version__ = version("ruff-legibility")
+except PackageNotFoundError:
+    __version__ = "0.1.0"

ruff_legibility-0.1.0/src/ruff_legibility/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

ruff_legibility-0.1.0/src/ruff_legibility/cli.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .config import apply_overrides, load_settings, parse_selectors
+from .core import Diagnostic, check_path, discover_python_files
+from .rules import RULES
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parse_args(list(argv) if argv is not None else sys.argv[1:])
+
+    if args.command == "rules":
+        _print_rules()
+        return 0
+
+    try:
+        settings = load_settings(Path(args.config) if args.config else None)
+        settings = apply_overrides(
+            settings,
+            select=parse_selectors(args.select),
+            ignore=parse_selectors(args.ignore),
+            max_expression_operators=args.max_expression_operators,
+            max_if_operators=args.max_if_operators,
+            max_ternary_operators=args.max_ternary_operators,
+            max_control_flow_depth=args.max_control_flow_depth,
+        )
+    except ValueError as error:
+        print(f"ruff-legibility: {error}", file=sys.stderr)
+        return 2
+
+    paths = [Path(path) for path in args.paths]
+    files = discover_python_files(paths, settings)
+    diagnostics = _check_files(files, settings)
+    _print_diagnostics(diagnostics, output_format=args.output_format)
+
+    if args.exit_zero:
+        return 0
+    return 1 if diagnostics else 0
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    top_level_flags = {"-h", "--help", "--version"}
+    if not argv or (argv[0] not in {"check", "rules"} and argv[0] not in top_level_flags):
+        argv = ["check", *argv]
+
+    parser = argparse.ArgumentParser(prog="ruff-legibility")
+    parser.add_argument("--version", action="version", version=f"ruff-legibility {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    check = subparsers.add_parser("check", help="check Python files")
+    check.add_argument("paths", nargs="*", default=["."], help="files or directories to check")
+    check.add_argument("--config", help="path to ruff-legibility.toml or pyproject.toml")
+    check.add_argument("--select", help="comma-separated rule selectors to enable")
+    check.add_argument("--ignore", help="comma-separated rule selectors to ignore")
+    check.add_argument(
+        "--output-format",
+        "--format",
+        choices=("text", "json", "github"),
+        default="text",
+        help="diagnostic output format",
+    )
+    check.add_argument("--exit-zero", action="store_true", help="always exit successfully")
+    check.add_argument("--max-expression-operators", type=int)
+    check.add_argument("--max-if-operators", type=int)
+    check.add_argument("--max-ternary-operators", type=int)
+    check.add_argument("--max-control-flow-depth", type=int)
+
+    subparsers.add_parser("rules", help="list available rules")
+    return parser.parse_args(argv)
+
+
+def _check_files(files: list[Path], settings) -> list[Diagnostic]:
+    diagnostics: list[Diagnostic] = []
+    for file in files:
+        diagnostics.extend(check_path(file, settings))
+    return sorted(diagnostics)
+
+
+def _print_diagnostics(diagnostics: list[Diagnostic], *, output_format: str) -> None:
+    if output_format == "json":
+        print(json.dumps([diagnostic.to_json() for diagnostic in diagnostics], indent=2))
+        return
+
+    for diagnostic in diagnostics:
+        if output_format == "github":
+            file_name = _escape_github_command_property(diagnostic.path.as_posix())
+            message = _escape_github_command_data(f"{diagnostic.code} {diagnostic.message}")
+            print(
+                f"::warning file={file_name},"
+                f"line={diagnostic.line},col={diagnostic.column}::"
+                f"{message}"
+            )
+        else:
+            print(
+                f"{diagnostic.path.as_posix()}:{diagnostic.line}:{diagnostic.column}: "
+                f"{diagnostic.code} {diagnostic.message}"
+            )
+
+
+def _escape_github_command_data(value: str) -> str:
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _escape_github_command_property(value: str) -> str:
+    return _escape_github_command_data(value).replace(":", "%3A").replace(",", "%2C")
+
+
+def _print_rules() -> None:
+    for code, rule in RULES.items():
+        print(f"{code} {rule.name}: {rule.summary}")