wildlint 0.1.0__py3-none-any.whl

wildlint/__init__.py

@@ -0,0 +1,15 @@
+"""wildlint — static checks distilled from real upstream bugs.
+
+Each rule was born from a concrete bug fixed in a public project, generalized to
+the smallest form that catches the class without flooding you with false
+positives. See ``checkers.py`` for the rule provenance.
+"""
+
+from __future__ import annotations
+
+from .checkers import CHECKERS, Finding, check_source
+from .cli import main
+
+__version__ = "0.1.0"
+
+__all__ = ["CHECKERS", "Finding", "check_source", "main", "__version__"]

wildlint/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m wildlint``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wildlint/checkers.py

@@ -0,0 +1,245 @@
+"""Detector registry for wildlint.
+
+Each checker is distilled from a *real* bug found in the wild (a public upstream
+PR), generalized into the smallest static rule that still catches the class
+without drowning the user in false positives. Checkers that could only be made
+to fire with an unacceptable false-positive rate are documented in
+``NON_GENERALIZED`` rather than shipped.
+
+A checker is any object exposing ``code``, ``name``, ``tier`` and a
+``check(tree, path) -> list[Finding]`` method. Register one by appending an
+instance to ``CHECKERS``.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+DEFAULT = "default"  # low false-positive; on unless deselected
+PEDANTIC = "pedantic"  # higher false-positive; opt-in via --pedantic
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: str
+    line: int
+    col: int
+    code: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}:{self.col}: {self.code} {self.message}"
+
+
+def _str_const(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# WL001 — replace-to-empty used as a prefix/suffix strip
+# Origin: nephila/giturlparse PR #149
+# --------------------------------------------------------------------------- #
+class ReplaceToEmptyPrefix:
+    """``x.replace(P, "")`` guarded by ``x.startswith(P)`` / ``x.endswith(P)``.
+
+    ``str.replace`` removes *every* occurrence, so a value that contains the
+    marker twice is silently corrupted (``"/blob/x/blob/y" -> "x/y"``). The
+    author meant ``str.removeprefix`` / ``str.removesuffix``. Narrow by design:
+    fires only when the *same receiver* is guarded by the *same* literal.
+    """
+
+    code = "WL001"
+    name = "replace-to-empty-prefix"
+    tier = DEFAULT
+
+    @staticmethod
+    def _guard(test: ast.expr) -> tuple[str, str, str] | None:
+        if not (isinstance(test, ast.Call) and isinstance(test.func, ast.Attribute)):
+            return None
+        method = test.func.attr
+        if method not in ("startswith", "endswith"):
+            return None
+        if len(test.args) != 1 or test.keywords:
+            return None
+        literal = _str_const(test.args[0])
+        if literal is None:
+            return None
+        suggestion = "removeprefix" if method == "startswith" else "removesuffix"
+        return ast.unparse(test.func.value), literal, suggestion
+
+    @staticmethod
+    def _is_replace_to_empty(node: ast.Call, receiver_src: str, literal: str) -> bool:
+        if not (isinstance(node.func, ast.Attribute) and node.func.attr == "replace"):
+            return False
+        if len(node.args) != 2 or node.keywords:
+            return False
+        if _str_const(node.args[0]) != literal or _str_const(node.args[1]) != "":
+            return False
+        return ast.unparse(node.func.value) == receiver_src
+
+    def check(self, tree: ast.AST, path: str) -> list[Finding]:
+        out: list[Finding] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.If):
+                continue
+            guard = self._guard(node.test)
+            if guard is None:
+                continue
+            receiver_src, literal, suggestion = guard
+            for inner in ast.walk(node):
+                if isinstance(inner, ast.Call) and self._is_replace_to_empty(
+                    inner, receiver_src, literal
+                ):
+                    out.append(
+                        Finding(
+                            path,
+                            inner.lineno,
+                            inner.col_offset,
+                            self.code,
+                            f'.replace({literal!r}, "") guarded by '
+                            f"{'startswith' if suggestion == 'removeprefix' else 'endswith'}"
+                            f"({literal!r}) removes every occurrence; "
+                            f"use str.{suggestion}({literal!r})",
+                        )
+                    )
+        return out
+
+
+# --------------------------------------------------------------------------- #
+# WL002 — str.split(' ') instead of str.split()
+# Origin: derek73/python-nameparser PR #164
+# --------------------------------------------------------------------------- #
+class SplitSingleSpace:
+    """``s.split(' ')`` where ``s.split()`` was almost certainly meant.
+
+    ``"a  b ".split(' ')`` -> ``['a', '', 'b', '']`` keeps empty tokens and does
+    not collapse runs or trim ends, while ``.split()`` does both. The single
+    blanks then leak downstream (``['']`` where ``[]`` was expected, a leading
+    space on a field). Only an *exact single space* literal fires — ``'  '`` or
+    ``','`` are treated as deliberate delimiters and left alone.
+    """
+
+    code = "WL002"
+    name = "split-single-space"
+    tier = DEFAULT
+
+    def check(self, tree: ast.AST, path: str) -> list[Finding]:
+        out: list[Finding] = []
+        for node in ast.walk(tree):
+            if not (
+                isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
+            ):
+                continue
+            if node.func.attr not in ("split", "rsplit"):
+                continue
+            if not node.args:
+                continue
+            if _str_const(node.args[0]) != " ":
+                continue
+            out.append(
+                Finding(
+                    path,
+                    node.lineno,
+                    node.col_offset,
+                    self.code,
+                    f".{node.func.attr}(' ') keeps empty tokens and will not "
+                    "collapse/trim whitespace; use "
+                    f".{node.func.attr}() unless single-space splitting is intended",
+                )
+            )
+        return out
+
+
+# --------------------------------------------------------------------------- #
+# WL003 — deep negative index without a length guard  (PEDANTIC)
+# Origin: savoirfairelinux/num2words PR #661
+# --------------------------------------------------------------------------- #
+class NegativeIndexNoGuard:
+    """``x[-k]`` with ``k >= 2`` — IndexError if the sequence is shorter than k.
+
+    The num2words bug indexed ``number_str[-2]`` unconditionally; ``"0"`` has
+    length 1 and crashed. Pedantic because ``x[-2]`` is frequently safe (the
+    length is known from context the checker cannot see), so this is opt-in.
+    """
+
+    code = "WL003"
+    name = "negative-index-no-guard"
+    tier = PEDANTIC
+
+    def check(self, tree: ast.AST, path: str) -> list[Finding]:
+        out: list[Finding] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Subscript):
+                continue
+            idx = node.slice
+            if (
+                isinstance(idx, ast.UnaryOp)
+                and isinstance(idx.op, ast.USub)
+                and isinstance(idx.operand, ast.Constant)
+                and isinstance(idx.operand.value, int)
+                and idx.operand.value >= 2
+            ):
+                target = ast.unparse(node.value)
+                out.append(
+                    Finding(
+                        path,
+                        node.lineno,
+                        node.col_offset,
+                        self.code,
+                        f"{target}[-{idx.operand.value}] raises IndexError if "
+                        f"len({target}) < {idx.operand.value}; add a length guard",
+                    )
+                )
+        return out
+
+
+CHECKERS = [
+    ReplaceToEmptyPrefix(),
+    SplitSingleSpace(),
+    NegativeIndexNoGuard(),
+]
+
+
+def select_checkers(*, pedantic: bool = False, codes: set[str] | None = None) -> list:
+    """Return the active checkers.
+
+    ``pedantic`` includes the opt-in tier. ``codes`` (e.g. ``{"WL001"}``)
+    restricts to those rules and, when given, overrides the tier filter.
+    """
+    if codes is not None:
+        return [c for c in CHECKERS if c.code in codes]
+    return [c for c in CHECKERS if c.tier == DEFAULT or pedantic]
+
+
+def check_source(
+    source: str,
+    path: str = "<unknown>",
+    *,
+    pedantic: bool = False,
+    codes: set[str] | None = None,
+) -> list[Finding]:
+    """Run the selected checkers over one source string; sorted findings."""
+    tree = ast.parse(source)
+    findings: list[Finding] = []
+    for checker in select_checkers(pedantic=pedantic, codes=codes):
+        findings.extend(checker.check(tree, path))
+    findings.sort(key=lambda f: (f.line, f.col, f.code))
+    return findings
+
+
+# Bug classes considered but NOT shipped — each would only fire with an
+# unacceptable false-positive rate as a purely-static rule. Kept here so the
+# reasoning is not lost and a future, smarter implementation can revisit.
+NON_GENERALIZED = {
+    "break-vs-continue": "jkwill87/mnamer #371 — whether `break` should be "
+    "`continue` is entirely loop-intent dependent; both are usually correct.",
+    "sign-doubling": "python-humanize/humanize #326 — negative whole+fraction "
+    "double-sign is a numeric-formatting specific, not a syntactic, pattern.",
+    "validation-branch-order": "python-validators/validators #463 — the unsafe "
+    "ordering of `,` vs `-`/`/` handling is specific to that parser's structure.",
+    "radix-from-ignored-param": "skorokithakis/shortuuid #115 — requires reading "
+    "the docstring contract ('alphabet is ignored') and matching it to impl.",
+}

wildlint/cli.py

@@ -0,0 +1,85 @@
+"""Command-line entry point for wildlint."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .checkers import CHECKERS, Finding, check_source
+
+
+def _iter_python_files(paths: list[str]):
+    for raw in paths:
+        p = Path(raw)
+        if p.is_dir():
+            yield from sorted(p.rglob("*.py"))
+        elif p.suffix == ".py":
+            yield p
+
+
+def check_file(
+    path: Path, *, pedantic: bool = False, codes: set[str] | None = None
+) -> list[Finding]:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    try:
+        return check_source(source, str(path), pedantic=pedantic, codes=codes)
+    except SyntaxError:
+        return []
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    from . import __version__
+
+    rules = ", ".join(f"{c.code} ({c.name}, {c.tier})" for c in CHECKERS)
+    parser = argparse.ArgumentParser(
+        prog="wildlint",
+        description="Static checks distilled from real upstream bugs. "
+        f"Rules: {rules}.",
+    )
+    parser.add_argument(
+        "paths", nargs="*", default=["."], help="files or dirs (default: .)"
+    )
+    parser.add_argument(
+        "--pedantic",
+        action="store_true",
+        help="also run opt-in higher-false-positive rules",
+    )
+    parser.add_argument(
+        "--select",
+        metavar="CODES",
+        help="comma-separated rule codes to run exclusively, e.g. WL001,WL002",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    codes = (
+        {c.strip().upper() for c in args.select.split(",") if c.strip()}
+        if args.select
+        else None
+    )
+    paths = args.paths or ["."]
+
+    findings: list[Finding] = []
+    for file in _iter_python_files(paths):
+        findings.extend(check_file(file, pedantic=args.pedantic, codes=codes))
+
+    for f in findings:
+        print(f)
+
+    if findings:
+        print(f"\n{len(findings)} finding(s).", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wildlint-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: wildlint
+Version: 0.1.0
+Summary: Static checks distilled from real upstream bugs that off-the-shelf linters miss.
+License: MIT
+Project-URL: Homepage, https://github.com/patchwright/wildlint
+Project-URL: Issues, https://github.com/patchwright/wildlint/issues
+Keywords: lint,linter,ast,static-analysis,bugs,removeprefix
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# wildlint
+
+[![CI](https://github.com/patchwright/wildlint/actions/workflows/ci.yml/badge.svg)](https://github.com/patchwright/wildlint/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/wildlint.svg)](https://pypi.org/project/wildlint/)
+
+Static checks distilled from **real upstream bugs** — the kind off-the-shelf
+linters miss because they look like ordinary, working code.
+
+Every rule here was born from a concrete bug that was found and fixed in a
+public project, then generalized to the smallest static check that still catches
+the *class* without flooding you with false positives. If a bug could not be
+turned into a low-noise rule, it is documented as not-shipped rather than added
+as noise (see [Not shipped](#bugs-considered-but-not-shipped)).
+
+## Install
+
+```bash
+pip install wildlint
+```
+
+## Use
+
+```bash
+wildlint path/to/code        # scan a file or directory (default: .)
+wildlint --select WL001,WL002 src/
+wildlint --pedantic src/     # also run opt-in, higher-false-positive rules
+```
+
+Exits non-zero when anything is found, so it drops straight into CI or a
+pre-commit hook.
+
+### pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/patchwright/wildlint
+    rev: v0.1.0
+    hooks:
+      - id: wildlint
+```
+
+### CI (GitHub Actions)
+
+```yaml
+- run: pip install wildlint
+- run: wildlint src/
+```
+
+## Rules
+
+| Code  | Tier     | Catches | Distilled from |
+|-------|----------|---------|----------------|
+| WL001 | default  | `x.replace(P, "")` guarded by `x.startswith(P)`/`endswith(P)` — removes *every* occurrence, silently corrupting values that contain the marker twice. Meant `str.removeprefix`/`removesuffix`. | [nephila/giturlparse#149](https://github.com/nephila/giturlparse/pull/149) |
+| WL002 | default  | `s.split(' ')` where `s.split()` was meant — keeps empty tokens and skips whitespace collapsing/trimming, leaking blanks downstream. Advisory: only an exact single-space literal fires. | [derek73/python-nameparser#164](https://github.com/derek73/python-nameparser/pull/164) |
+| WL003 | pedantic | `x[-k]` with `k >= 2` — `IndexError` when the sequence is shorter than `k`. Opt-in because deep negative indexing is often provably safe from context the checker can't see. | [savoirfairelinux/num2words#661](https://github.com/savoirfairelinux/num2words/pull/661) |
+
+Each rule is verified against the *actual pre-fix source* of the project it came
+from — see the tests, and the rule docstrings in `src/wildlint/checkers.py`.
+
+## Bugs considered but not shipped
+
+Some real bugs do not generalize into a low-false-positive static rule. They are
+recorded in `NON_GENERALIZED` in `checkers.py` so the reasoning is preserved:
+
+- **break-vs-continue** ([mnamer#371](https://github.com/jkwill87/mnamer/pull/371)) — whether `break` should be `continue` is entirely loop-intent dependent.
+- **sign-doubling** ([humanize#326](https://github.com/python-humanize/humanize/pull/326)) — a numeric-formatting concern, not a syntactic pattern.
+- **validation-branch-order** ([validators#463](https://github.com/python-validators/validators/pull/463)) — specific to one parser's control flow.
+- **radix-from-ignored-param** ([shortuuid#115](https://github.com/skorokithakis/shortuuid/pull/115)) — requires matching a docstring contract to the implementation.
+
+## Adding a rule
+
+A checker is any object with `code`, `name`, `tier`, and
+`check(tree, path) -> list[Finding]`. Append an instance to `CHECKERS` in
+`checkers.py` and add positive/negative tests mirroring the wild bug. That's the
+whole extension surface — the suite grows one real bug at a time.
+
+## License
+
+MIT.

wildlint-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+wildlint/__init__.py,sha256=dyj72Fjmt-fmByp2zSkBvxVe5pE4qAEpSfU4DjawL3w,490
+wildlint/__main__.py,sha256=hCKx5U22ApzqOPylHHCHVYdOorDWigDefj31P-E1d0c,117
+wildlint/checkers.py,sha256=mu9RPpNbfIOFpWQ7S8UwucRmmTpw3KbYnNIAnXr2E1A,9488
+wildlint/cli.py,sha256=vOPCrxhiVSaNu4GViKS4DF7EcYlc4NssCOKbGMMel2Q,2239
+wildlint-0.1.0.dist-info/licenses/LICENSE,sha256=11DE3zrWsWwkP3B70LTau54zWqchBlfJC5XQfsWTXLE,1068
+wildlint-0.1.0.dist-info/METADATA,sha256=koX27MsWLCSJXLJlUUf1efz9zjsRLvYXzDSzA1UBOHQ,4262
+wildlint-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+wildlint-0.1.0.dist-info/entry_points.txt,sha256=Qe0ROTsVZP9fjyk80qx3yvwo_5Xf-K3xVZQcYRA7qf8,43
+wildlint-0.1.0.dist-info/top_level.txt,sha256=HD-ukuR0QoYvzFRVtWCcgjDn-uA0uhy1cG_DZ1ONRmo,9
+wildlint-0.1.0.dist-info/RECORD,,

wildlint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

wildlint-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+wildlint = wildlint:main

wildlint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 patchwright
+
+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.

wildlint-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wildlint