ruff-legibility 0.1.0__py3-none-any.whl

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/__main__.py

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

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}")

ruff_legibility/config.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import fnmatch
+import tomllib
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from .rules import DEFAULT_SELECT, RULES
+
+DEFAULT_EXCLUDE = (
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+)
+
+
+@dataclass(frozen=True)
+class Settings:
+    select: tuple[str, ...] = DEFAULT_SELECT
+    ignore: tuple[str, ...] = ()
+    exclude: tuple[str, ...] = DEFAULT_EXCLUDE
+    per_file_ignores: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    max_expression_operators: int = 4
+    max_if_operators: int = 0
+    max_ternary_operators: int = 2
+    max_control_flow_depth: int = 3
+
+    def enabled(self, code: str) -> bool:
+        return selector_matches(code, self.select) and not selector_matches(code, self.ignore)
+
+    def ignored_for_path(self, code: str, path: Path) -> bool:
+        path_text = path.as_posix()
+        for pattern, selectors in self.per_file_ignores.items():
+            if fnmatch.fnmatch(path_text, pattern) and selector_matches(code, selectors):
+                return True
+        return False
+
+
+def selector_matches(code: str, selectors: tuple[str, ...] | list[str] | set[str]) -> bool:
+    return any(code.startswith(selector) for selector in selectors)
+
+
+def parse_selectors(value: str | None) -> tuple[str, ...] | None:
+    if value is None:
+        return None
+
+    selectors = tuple(part.strip().upper() for part in value.split(",") if part.strip())
+    return selectors
+
+
+def validate_selectors(selectors: tuple[str, ...]) -> None:
+    unknown_rules = [selector for selector in selectors if selector != "LEG" and selector not in RULES]
+    if unknown_rules:
+        joined = ", ".join(sorted(set(unknown_rules)))
+        raise ValueError(f"Unknown rule selector(s): {joined}")
+
+
+def find_config(start: Path | None = None) -> Path | None:
+    current = (start or Path.cwd()).resolve()
+    if current.is_file():
+        current = current.parent
+
+    for candidate in _candidate_config_paths(current):
+        if not candidate.is_file():
+            continue
+        if candidate.name == "pyproject.toml" and not _pyproject_has_config(candidate):
+            continue
+        return candidate
+
+    return None
+
+
+def load_settings(config_path: Path | None = None, cwd: Path | None = None) -> Settings:
+    settings = Settings()
+    path = config_path or find_config(cwd)
+    if path is None:
+        return settings
+
+    data = tomllib.loads(path.read_text())
+    table = _config_table(data, path)
+    return apply_config(settings, table)
+
+
+def apply_overrides(
+    settings: Settings,
+    *,
+    select: tuple[str, ...] | None = None,
+    ignore: tuple[str, ...] | None = None,
+    max_expression_operators: int | None = None,
+    max_if_operators: int | None = None,
+    max_ternary_operators: int | None = None,
+    max_control_flow_depth: int | None = None,
+) -> Settings:
+    updates: dict[str, Any] = {}
+    if select is not None:
+        validate_selectors(select)
+        updates["select"] = select
+    if ignore is not None:
+        validate_selectors(ignore)
+        updates["ignore"] = ignore
+    if max_expression_operators is not None:
+        updates["max_expression_operators"] = max_expression_operators
+    if max_if_operators is not None:
+        updates["max_if_operators"] = max_if_operators
+    if max_ternary_operators is not None:
+        updates["max_ternary_operators"] = max_ternary_operators
+    if max_control_flow_depth is not None:
+        updates["max_control_flow_depth"] = max_control_flow_depth
+    return replace(settings, **updates)
+
+
+def apply_config(settings: Settings, table: dict[str, Any]) -> Settings:
+    updates: dict[str, Any] = {}
+
+    selectors = _string_list(table.get("select"), "select")
+    if selectors is not None:
+        updates["select"] = tuple(selector.upper() for selector in selectors)
+
+    extend_selectors = _string_list(table.get("extend-select", table.get("extend_select")), "extend-select")
+    if extend_selectors is not None:
+        existing_selectors = updates.get("select", settings.select)
+        updates["select"] = (*existing_selectors, *(selector.upper() for selector in extend_selectors))
+
+    ignored = _string_list(table.get("ignore"), "ignore")
+    if ignored is not None:
+        updates["ignore"] = tuple(selector.upper() for selector in ignored)
+
+    extend_ignored = _string_list(table.get("extend-ignore", table.get("extend_ignore")), "extend-ignore")
+    if extend_ignored is not None:
+        existing_ignored = updates.get("ignore", settings.ignore)
+        updates["ignore"] = (*existing_ignored, *(selector.upper() for selector in extend_ignored))
+
+    excluded = _string_list(table.get("exclude"), "exclude")
+    if excluded is not None:
+        updates["exclude"] = tuple(excluded)
+
+    per_file_ignores = table.get("per-file-ignores", table.get("per_file_ignores"))
+    if per_file_ignores is not None:
+        if not isinstance(per_file_ignores, dict):
+            raise ValueError("per-file-ignores must be a table")
+        updates["per_file_ignores"] = {
+            str(pattern): tuple(code.upper() for code in _required_string_list(codes, str(pattern)))
+            for pattern, codes in per_file_ignores.items()
+        }
+
+    int_options = {
+        "max-expression-operators": "max_expression_operators",
+        "max-if-operators": "max_if_operators",
+        "max-ternary-operators": "max_ternary_operators",
+        "max-control-flow-depth": "max_control_flow_depth",
+    }
+    for option_name, field_name in int_options.items():
+        if option_name not in table:
+            continue
+        value = table[option_name]
+        if not isinstance(value, int):
+            raise ValueError(f"{option_name} must be an integer")
+        updates[field_name] = value
+
+    validate_selectors(updates.get("select", settings.select))
+    validate_selectors(updates.get("ignore", settings.ignore))
+
+    return replace(settings, **updates)
+
+
+def _pyproject_has_config(path: Path) -> bool:
+    try:
+        data = tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError:
+        return False
+
+    tool = data.get("tool")
+    return isinstance(tool, dict) and isinstance(tool.get("ruff-legibility"), dict)
+
+
+def _candidate_config_paths(current: Path) -> tuple[Path, ...]:
+    directories = (current, *current.parents)
+    names = ("ruff-legibility.toml", ".ruff-legibility.toml", "pyproject.toml")
+    return tuple(directory / name for directory in directories for name in names)
+
+
+def _config_table(data: dict[str, Any], path: Path) -> dict[str, Any]:
+    if path.name == "pyproject.toml":
+        tool = data.get("tool", {})
+        if not isinstance(tool, dict):
+            return {}
+        table = tool.get("ruff-legibility", {})
+        if not isinstance(table, dict):
+            raise ValueError("[tool.ruff-legibility] must be a table")
+        return table
+
+    return data
+
+
+def _string_list(value: Any, name: str) -> list[str] | None:
+    if value is None:
+        return None
+    return _required_string_list(value, name)
+
+
+def _required_string_list(value: Any, name: str) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ValueError(f"{name} must be a list of strings")
+    return value

ruff_legibility/core.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Settings
+from .noqa import is_noqa_suppressed
+from .rules import LegibilityVisitor
+
+
+@dataclass(frozen=True, order=True)
+class Diagnostic:
+    path: Path
+    line: int
+    column: int
+    code: str
+    message: str
+    end_line: int | None = None
+    end_column: int | None = None
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "filename": self.path.as_posix(),
+            "location": {"row": self.line, "column": self.column},
+            "end_location": {
+                "row": self.end_line or self.line,
+                "column": self.end_column or self.column,
+            },
+            "code": self.code,
+            "message": self.message,
+        }
+
+
+def check_path(path: Path, settings: Settings) -> list[Diagnostic]:
+    source = path.read_text(encoding="utf-8")
+    return check_source(source, path=path, settings=settings)
+
+
+def check_source(source: str, *, path: Path, settings: Settings) -> list[Diagnostic]:
+    try:
+        tree = ast.parse(source, filename=path.as_posix(), type_comments=True)
+    except SyntaxError as error:
+        line = error.lineno or 1
+        column = (error.offset or 1) - 1
+        return [
+            Diagnostic(
+                path=path,
+                line=line,
+                column=column + 1,
+                code="LEG999",
+                message=f"SyntaxError: {error.msg}",
+            )
+        ]
+
+    visitor = LegibilityVisitor(path=path, settings=settings)
+    visitor.visit(tree)
+    lines = source.splitlines()
+    diagnostics = [
+        diagnostic
+        for diagnostic in visitor.diagnostics
+        if not settings.ignored_for_path(diagnostic.code, path)
+        and not is_noqa_suppressed(lines, diagnostic.line, diagnostic.code)
+    ]
+    return sorted(diagnostics)
+
+
+def discover_python_files(paths: Iterable[Path], settings: Settings) -> list[Path]:
+    files: list[Path] = []
+    for path in paths:
+        if path.is_file():
+            if path.suffix == ".py" and not _is_excluded(path, settings):
+                files.append(path)
+            continue
+
+        if path.is_dir():
+            files.extend(_discover_directory_python_files(path, settings))
+
+    return sorted(set(files))
+
+
+def _discover_directory_python_files(path: Path, settings: Settings) -> list[Path]:
+    return [candidate for candidate in path.rglob("*.py") if not _is_excluded(candidate, settings)]
+
+
+def _is_excluded(path: Path, settings: Settings) -> bool:
+    parts = set(path.parts)
+    return any(excluded in parts or path.match(excluded) for excluded in settings.exclude)

ruff_legibility/noqa.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import re
+
+NOQA_PATTERN = re.compile(r"#\s*noqa(?::\s*(?P<codes>[A-Z0-9,\s]+))?", re.IGNORECASE)
+
+
+def is_noqa_suppressed(lines: list[str], line_number: int, code: str) -> bool:
+    if line_number < 1 or line_number > len(lines):
+        return False
+
+    line = lines[line_number - 1]
+    match = NOQA_PATTERN.search(line)
+    if match is None:
+        return False
+
+    codes = match.group("codes")
+    if codes is None:
+        return True
+
+    selectors = [part.strip().upper() for part in codes.split(",") if part.strip()]
+    return any(code.startswith(selector) for selector in selectors)

ruff_legibility/py.typed

@@ -0,0 +1 @@
+

ruff_legibility/rules.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import ast
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import Settings
+    from .core import Diagnostic
+
+
+@dataclass(frozen=True)
+class Rule:
+    code: str
+    name: str
+    summary: str
+
+
+RULES = {
+    "LEG001": Rule(
+        "LEG001",
+        "max-expression-operators",
+        "Limit readability operators inside a single expression.",
+    ),
+    "LEG002": Rule(
+        "LEG002",
+        "hoist-if-operators",
+        "Prefer named booleans before operator-heavy conditions.",
+    ),
+    "LEG003": Rule(
+        "LEG003",
+        "max-control-flow-depth",
+        "Limit nested control-flow depth.",
+    ),
+    "LEG004": Rule(
+        "LEG004",
+        "no-complex-ternary",
+        "Avoid complex ternary expressions.",
+    ),
+    "LEG005": Rule(
+        "LEG005",
+        "no-quadratic-patterns",
+        "Flag likely quadratic loops and repeated searches.",
+    ),
+    "LEG006": Rule(
+        "LEG006",
+        "no-redundant-boolean-logic",
+        "Avoid redundant boolean comparisons.",
+    ),
+    "LEG007": Rule(
+        "LEG007",
+        "prefer-positive-condition-names",
+        "Prefer positive condition names.",
+    ),
+}
+
+DEFAULT_SELECT = ("LEG",)
+
+CONTROL_FLOW_NODES = (
+    ast.AsyncFor,
+    ast.AsyncWith,
+    ast.For,
+    ast.If,
+    ast.Match,
+    ast.Try,
+    ast.While,
+    ast.With,
+)
+
+BOOLEAN_NAME_PATTERN = re.compile(r"^(?:is|are|was|were|has|have|had|can|could|should|will|would|did|does)_")
+NEGATIVE_CONDITION_PATTERN = re.compile(
+    r"^(?:is|are|was|were|has|have|had|can|could|should|will|would|did|does)_"
+    r"(?:not|no|without)_"
+)
+
+
+class LegibilityVisitor(ast.NodeVisitor):
+    def __init__(self, *, path: Path, settings: Settings) -> None:
+        self.path = path
+        self.settings = settings
+        self.diagnostics: list[Diagnostic] = []
+        self.control_depth = 0
+        self.loop_depth = 0
+
+    def visit_If(self, node: ast.If) -> None:
+        self._check_condition(node.test)
+        self._visit_control_body(node, body=node.body, orelse=node.orelse)
+
+    def visit_While(self, node: ast.While) -> None:
+        self._check_condition(node.test)
+        self._visit_loop(node)
+
+    def visit_For(self, node: ast.For) -> None:
+        self._visit_loop(node)
+
+    def visit_AsyncFor(self, node: ast.AsyncFor) -> None:
+        self._visit_loop(node)
+
+    def visit_With(self, node: ast.With) -> None:
+        self._visit_control_body(node, body=node.body)
+
+    def visit_AsyncWith(self, node: ast.AsyncWith) -> None:
+        self._visit_control_body(node, body=node.body)
+
+    def visit_Try(self, node: ast.Try) -> None:
+        self._enter_control(node)
+        self._visit_many(node.body)
+        for handler in node.handlers:
+            self.visit(handler)
+        self._visit_many(node.orelse)
+        self._visit_many(node.finalbody)
+        self._leave_control()
+
+    def visit_Match(self, node: ast.Match) -> None:
+        self._enter_control(node)
+        for case in node.cases:
+            self._visit_many(case.body)
+        self._leave_control()
+
+    def visit_IfExp(self, node: ast.IfExp) -> None:
+        if self.settings.enabled("LEG004"):
+            count = count_readability_operators(node)
+            if count > self.settings.max_ternary_operators:
+                self._add(
+                    node,
+                    "LEG004",
+                    f"Ternary expression has {count} readability operators "
+                    f"(max {self.settings.max_ternary_operators}). Extract it into named branches.",
+                )
+        self.generic_visit(node)
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        self._check_expression(node.value)
+        for target in node.targets:
+            self._check_condition_name(target)
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        if node.value is not None:
+            self._check_expression(node.value)
+        self._check_condition_name(node.target)
+        self.generic_visit(node)
+
+    def visit_NamedExpr(self, node: ast.NamedExpr) -> None:
+        self._check_condition_name(node.target)
+        self._check_expression(node.value)
+        self.generic_visit(node)
+
+    def visit_Return(self, node: ast.Return) -> None:
+        if node.value is not None:
+            self._check_expression(node.value)
+        self.generic_visit(node)
+
+    def visit_Expr(self, node: ast.Expr) -> None:
+        self._check_expression(node.value)
+        self.generic_visit(node)
+
+    def visit_arg(self, node: ast.arg) -> None:
+        self._check_name(node.arg, node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._check_name(node.name, node)
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._check_name(node.name, node)
+        self.generic_visit(node)
+
+    def visit_Compare(self, node: ast.Compare) -> None:
+        if self.settings.enabled("LEG006") and _has_redundant_boolean_compare(node):
+            self._add(
+                node,
+                "LEG006",
+                "Avoid redundant boolean comparisons. Use the boolean value directly.",
+            )
+
+        if self.loop_depth > 0 and self.settings.enabled("LEG005") and _has_membership_search(node):
+            self._add(
+                node,
+                "LEG005",
+                "Membership test inside a loop can become O(n^2). Use a set or dict for repeated lookups.",
+            )
+        self.generic_visit(node)
+
+    def visit_BoolOp(self, node: ast.BoolOp) -> None:
+        if self.settings.enabled("LEG006") and _has_redundant_boolean_operand(node):
+            self._add(
+                node,
+                "LEG006",
+                "Avoid redundant boolean operands like `and True` or `or False`.",
+            )
+        self.generic_visit(node)
+
+    def _visit_loop(self, node: ast.For | ast.AsyncFor | ast.While) -> None:
+        if self.loop_depth > 0 and self.settings.enabled("LEG005"):
+            self._add(
+                node,
+                "LEG005",
+                "Nested loop detected. Consider restructuring around a set, dict, or precomputed lookup.",
+            )
+
+        self.loop_depth += 1
+        self._visit_control_body(node, body=node.body, orelse=node.orelse)
+        self.loop_depth -= 1
+
+    def _visit_control_body(
+        self,
+        node: ast.AST,
+        *,
+        body: Iterable[ast.stmt],
+        orelse: Iterable[ast.stmt] = (),
+    ) -> None:
+        self._enter_control(node)
+        self._visit_many(body)
+        self._visit_many(orelse)
+        self._leave_control()
+
+    def _enter_control(self, node: ast.AST) -> None:
+        self.control_depth += 1
+        if self.settings.enabled("LEG003") and self.control_depth > self.settings.max_control_flow_depth:
+            self._add(
+                node,
+                "LEG003",
+                f"Control-flow depth is {self.control_depth} "
+                f"(max {self.settings.max_control_flow_depth}). Prefer guard clauses or extraction.",
+            )
+
+    def _leave_control(self) -> None:
+        self.control_depth -= 1
+
+    def _visit_many(self, nodes: Iterable[ast.AST]) -> None:
+        for node in nodes:
+            self.visit(node)
+
+    def _check_condition(self, expression: ast.expr) -> None:
+        if not self.settings.enabled("LEG002"):
+            return
+
+        count = count_condition_operators(expression)
+        if count > self.settings.max_if_operators:
+            self._add(
+                expression,
+                "LEG002",
+                f"If condition has {count} boolean operators "
+                f"(max {self.settings.max_if_operators}). Hoist it into a named boolean.",
+            )
+
+    def _check_expression(self, expression: ast.expr) -> None:
+        if not self.settings.enabled("LEG001"):
+            return
+
+        if isinstance(expression, (ast.Constant, ast.Name)):
+            return
+
+        count = count_readability_operators(expression)
+        if count > self.settings.max_expression_operators:
+            self._add(
+                expression,
+                "LEG001",
+                f"Expression has {count} readability operators "
+                f"(max {self.settings.max_expression_operators}). Extract named sub-expressions.",
+            )
+
+    def _check_condition_name(self, target: ast.AST) -> None:
+        if isinstance(target, ast.Name):
+            self._check_name(target.id, target)
+
+    def _check_name(self, name: str, node: ast.AST) -> None:
+        if not self.settings.enabled("LEG007"):
+            return
+
+        if BOOLEAN_NAME_PATTERN.match(name) and NEGATIVE_CONDITION_PATTERN.match(name):
+            self._add(
+                node,
+                "LEG007",
+                f"Prefer a positive condition name instead of `{name}`.",
+            )
+
+    def _add(self, node: ast.AST, code: str, message: str) -> None:
+        if not self.settings.enabled(code):
+            return
+
+        from .core import Diagnostic
+
+        self.diagnostics.append(
+            Diagnostic(
+                path=self.path,
+                line=getattr(node, "lineno", 1),
+                column=getattr(node, "col_offset", 0) + 1,
+                end_line=getattr(node, "end_lineno", None),
+                end_column=(getattr(node, "end_col_offset", 0) or 0) + 1,
+                code=code,
+                message=message,
+            )
+        )
+
+
+def count_condition_operators(node: ast.AST) -> int:
+    count = 0
+    for child in _walk_expression(node):
+        if isinstance(child, ast.BoolOp):
+            count += max(len(child.values) - 1, 0)
+        elif isinstance(child, ast.IfExp) or (isinstance(child, ast.UnaryOp) and isinstance(child.op, ast.Not)):
+            count += 1
+    return count
+
+
+def count_readability_operators(node: ast.AST) -> int:
+    count = 0
+    for child in _walk_expression(node):
+        if isinstance(child, ast.BoolOp):
+            count += max(len(child.values) - 1, 0)
+        elif isinstance(child, ast.BinOp):
+            count += 1
+        elif isinstance(child, ast.Compare):
+            count += len(child.ops)
+        elif isinstance(child, ast.IfExp) or (
+            isinstance(child, ast.UnaryOp) and isinstance(child.op, (ast.Not, ast.Invert))
+        ):
+            count += 1
+    return count
+
+
+def _walk_expression(node: ast.AST) -> Iterable[ast.AST]:
+    for child in ast.walk(node):
+        if child is not node and isinstance(child, (ast.Lambda, ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        yield child
+
+
+def _has_redundant_boolean_compare(node: ast.Compare) -> bool:
+    comparisons = zip(node.ops, node.comparators, strict=False)
+    return any(
+        isinstance(operator, (ast.Eq, ast.NotEq))
+        and isinstance(comparator, ast.Constant)
+        and isinstance(comparator.value, bool)
+        for operator, comparator in comparisons
+    )
+
+
+def _has_redundant_boolean_operand(node: ast.BoolOp) -> bool:
+    constants = [value for value in node.values if isinstance(value, ast.Constant)]
+    if isinstance(node.op, ast.And):
+        return any(value.value is True for value in constants)
+    if isinstance(node.op, ast.Or):
+        return any(value.value is False for value in constants)
+    return False
+
+
+def _has_membership_search(node: ast.Compare) -> bool:
+    return any(isinstance(operator, (ast.In, ast.NotIn)) for operator in node.ops)

ruff_legibility-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+ruff_legibility/__init__.py,sha256=O0T487GI-lHC7ONZEVvX_nmGeOZLlp6oqEf1LjtKtmU,364
+ruff_legibility/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+ruff_legibility/cli.py,sha256=u8uUh6zZ89PP8-K_PnZ7KZgzUpMkM-zlZsbsNr0bPU8,4387
+ruff_legibility/config.py,sha256=FwlXFs7vHINECyE4pwG_MQI2ndQ9ccPtorO0UBFlL8s,7533
+ruff_legibility/core.py,sha256=fvjeHBKPsYp6w7HzKi636aEN3ZbOnExxO7IVR_2_vYM,2723
+ruff_legibility/noqa.py,sha256=m6PkvGLA4VDv_09Yi7Raj7YxVqBc8Hna1_JWCNxBxhg,632
+ruff_legibility/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ruff_legibility/rules.py,sha256=zuCVYbbH_wWZT3irUoQc1TOBlVzLVX8CmepgzjTSgK8,11551
+ruff_legibility-0.1.0.dist-info/METADATA,sha256=jGdLGJ4wxhTmAm2sa3c81339C20nL1bezAbtsJJcbfU,4369
+ruff_legibility-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ruff_legibility-0.1.0.dist-info/entry_points.txt,sha256=x_ubGENVPXMQ1lk294NEFVRLxL8wF8MZ76PUr8sBmW8,61
+ruff_legibility-0.1.0.dist-info/licenses/LICENSE,sha256=YfsKGD4MeecsEoE27qIRRfgbcN_LPOWTPnjU5rkRgSw,1074
+ruff_legibility-0.1.0.dist-info/RECORD,,

ruff_legibility-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ruff_legibility-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ruff-legibility = ruff_legibility.cli:main

ruff_legibility-0.1.0.dist-info/licenses/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.