willitbite 0.1.0__tar.gz

willitbite-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,10 @@
+blank_issues_enabled: false
+
+contact_links:
+  - name: Question, or a verdict you want to discuss
+    url: https://github.com/muhzuhaib/willitbite/discussions
+    about: Anything that is not yet a wrong-verdict report or a concrete request.
+
+  - name: Security vulnerability
+    url: https://github.com/muhzuhaib/willitbite/security/advisories/new
+    about: Report privately. Please do not open a public issue for these.

willitbite-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: A warning, rule or decision the tool should handle and does not
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What decision would this help you make
+      description: >
+        This tool exists to answer one question: which of these warnings can
+        reach me at runtime. Describing the decision rather than the feature
+        makes it much easier to tell whether it belongs here.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you do today instead

willitbite-0.1.0/.github/ISSUE_TEMPLATE/wrong_verdict.yml

@@ -0,0 +1,49 @@
+name: Wrong verdict
+description: The tool called a warning SAFE (or BITES) and you can show it is wrong
+labels: ["bug"]
+body:
+  - type: textarea
+    id: verdict
+    attributes:
+      label: What the tool claimed
+      description: >
+        The verdict block for the warning in question, from the tool's output
+        or --json-out. A verdict that is wrong is a defect even when nothing
+        crashed: the tool exists so you can stop reading the warnings it clears.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: The function it is wrong about
+      description: >
+        The function (and, for B023, the call site) that shows the claim is
+        wrong. Trimmed to the smallest thing that reproduces is ideal.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: What actually happens when this runs
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `willitbite --version`
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python, ruff and operating system
+      placeholder: "3.13, ruff 0.13, Windows 11"
+    validations:
+      required: true

willitbite-0.1.0/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+
+updates:
+  # Actions pin to a major tag, which keeps moving underneath until a major is
+  # deprecated and CI starts warning. A monthly check catches that without a
+  # pull request every week.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: "Update"
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # There are no runtime dependencies to update, so this only ever covers the
+  # test tooling, which is safe to group.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: "Update"
+    groups:
+      dev-dependencies:
+        dependency-type: development

willitbite-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,105 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Oldest supported and newest released. The versions in between rarely
+        # break independently and cost minutes for no signal.
+        python-version: ["3.10", "3.13"]
+        os: [ubuntu-latest]
+        include:
+          # The analysis reads files off disk and reports paths, both of which
+          # differ on Windows. One job keeps that honest.
+          - python-version: "3.13"
+            os: windows-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Test
+        run: pytest -q
+
+  selfcheck:
+    # The tool is run against its own source. A tool that reports on Python
+    # code and has never been pointed at any is untested in the way that
+    # matters, and this also proves the ruff subprocess path works, which the
+    # unit tests deliberately avoid depending on.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Run it on itself
+        run: willitbite src --all
+
+  install:
+    # Verifies the way a stranger gets it: build the wheel, install it into a
+    # clean environment with nothing else present, and run it against a file
+    # with a known answer. A suite that runs from the source tree would not
+    # notice a packaging mistake that leaves a module out of the wheel.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Build the wheel
+        run: |
+          pip install build
+          python -m build --wheel
+
+      - name: Install it somewhere clean and run it
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install --quiet dist/*.whl ruff
+          /tmp/clean/bin/willitbite --version
+          /tmp/clean/bin/willitbite --help
+
+      - name: Decide a file whose answer is known
+        run: |
+          mkdir -p /tmp/subject
+          cat > /tmp/subject/known.py <<'PY'
+          handlers = []
+          for i in range(3):
+              def handler():
+                  return i
+              handlers.append(handler)
+
+
+          def safe(items=[]):
+              return len(items)
+          PY
+          /tmp/clean/bin/willitbite /tmp/subject --json-out > out.json || true
+          python -c "
+          import json
+          data = json.load(open('out.json'))
+          assert data['bites'] == 1, data
+          biting = [r for r in data['results'] if r['verdict'] == 'BITES']
+          assert biting[0]['code'] == 'B023', biting
+          assert 'handler' in biting[0]['reason'], biting
+          print('decided', data['warnings'], 'warnings,', data['bites'], 'reachable')
+          "

willitbite-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    # Trusted publishing. PyPI verifies this workflow's identity through
+    # OpenID Connect and issues a short lived token for the upload, so there
+    # is no API token stored anywhere: not in a repository secret, not on a
+    # laptop, and nothing to leak or rotate.
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Check the tag matches the version in the package
+        # A tag that disagrees with __version__ publishes a release whose
+        # metadata lies about itself, and it cannot be corrected afterwards
+        # because PyPI does not allow a version to be reuploaded.
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python -c "import re,pathlib; print(re.search(r'__version__ = \"(.*)\"', pathlib.Path('src/willitbite/__init__.py').read_text()).group(1))")
+          echo "tag=$tag package=$version"
+          test "$tag" = "$version"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

willitbite-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/

willitbite-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-08
+
+### Added
+
+- First release.
+
+- B023 escape analysis: decides whether a closure that captures a loop variable
+  can still be called after the loop has moved on.
+- B006 mutable default analysis: decides whether a shared default is ever
+  actually mutated, accounting for the common `items = items or []` rebind and
+  for augmented assignment, which mutates a list in place rather than rebinding.
+- A third verdict, `CALLEE`, for the cases where the answer depends on a
+  function the tool cannot see into. It names that function instead of guessing.
+- Call-site analysis for B006. A mutable default can only be corrupted by a
+  caller that omits the argument, so warnings that survive the first pass are
+  checked against every call site under the path. When all of them pass the
+  argument explicitly the verdict becomes `LATENT`: the defect is real and is
+  still reported, but nothing in the tree can trigger it today. Anything the
+  scan cannot resolve stays at `BITES`, including a `*args` or `**kwargs` splat
+  at the call site and the case of no caller at all, which usually means a
+  public entry point called from outside the tree.
+- `LATENT` does not set a failing exit code. The exit code answers whether
+  something can bite today.
+- Command line with `--json` input, `--json-out`, `--all` and `--exit-zero`.

willitbite-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thanks for looking. This is a small tool with one job: decide which of ruff's
+B006 and B023 warnings can actually reach you at runtime. The bar for a change
+is whether it makes that decision more trustworthy.
+
+## The most valuable report
+
+**A verdict that is wrong.** This tool does not just count warnings, it claims
+things about your code: that a warning is `SAFE`, that a defect is `LATENT`,
+that a closure `DEPENDS ON A CALLEE`. A warning marked `SAFE` that can really
+bite is the worst defect this tool can have, because the whole point is that
+you stop reading the ones it clears. A `BITES` verdict on code that is fine
+costs the trust the tool lives on too. There is an issue form for exactly this.
+Please include the tool's output for the file and the code of the function in
+question; both together make a report reproducible in minutes.
+
+## Known limitations, stated so they do not come back as bug reports
+
+- **A warning with no caller found anywhere stays `BITES`.** Absence of
+  evidence never downgrades anything. If the call site is behind a decorator,
+  a framework, or a language we do not model, the tool refuses to guess.
+- **`*args` and `**kwargs` splats keep a warning.** A splat can pass anything,
+  including the omitted argument, so the honest verdict is the loud one.
+- **`CALLEE` is a verdict on purpose.** When safety depends on what some other
+  function does with your callable, the tool names that function instead of
+  pretending to know. It will not chase into other modules for you.
+- **Call sites are found within the path you scanned.** Point it at `./src`
+  and that is the world it reasons about.
+
+## Running the tests
+
+```console
+pip install -e ".[dev]"
+pytest -q
+```
+
+Nothing in the suite touches the network and it does not need ruff installed:
+the tests build ruff's own JSON output shape inline and run the real code path
+over files written to a temporary directory.
+
+## What a change needs
+
+- **A test that fails without it.** For anything that changes a verdict, the
+  test should be a control case: it must fail if the behaviour is removed, not
+  merely pass while it is present.
+- **A note in the README if it changes what a verdict means.** The Design
+  decisions section is the contract people read before trusting an exit code.
+- **One concern per pull request.** Small is easy to read and easy to merge.
+
+## What is deliberately out of scope
+
+- **Other ruff rules.** B006 and B023 produce most of the noise when a project
+  adopts ruff's bugbear set, and depth on two rules beats shallowness on twenty.
+  A third rule is welcome as a proposal, with the same four-verdict honesty.
+- **Fixing the code.** This decides what is worth a person's time; it does not
+  rewrite your functions.
+- **Runtime dependencies.** The analysis uses the standard library's `ast`
+  module, and ruff is invoked as a subprocess only when it is already on your
+  PATH. A tool that tells you about your linter should not force a version of
+  it on you.
+
+## Code style
+
+Plain Python, type hints on anything that crosses a module boundary, and
+comments that say why rather than what. Line length 100.

willitbite-0.1.0/LICENSE

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

willitbite-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: willitbite
+Version: 0.1.0
+Summary: Tell which of ruff's loop-closure and mutable-default warnings can actually reach you at runtime
+Project-URL: Homepage, https://github.com/muhzuhaib/willitbite
+Project-URL: Issues, https://github.com/muhzuhaib/willitbite/issues
+Project-URL: Changelog, https://github.com/muhzuhaib/willitbite/blob/main/CHANGELOG.md
+Author: Muhammad Zuhaib Zahid
+License: MIT License
+        
+        Copyright (c) 2026 Muhammad Zuhaib Zahid
+        
+        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.
+License-File: LICENSE
+Keywords: cli,linting,python,ruff,static-analysis,triage
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# willitbite
+
+[![CI](https://github.com/muhzuhaib/willitbite/actions/workflows/ci.yml/badge.svg)](https://github.com/muhzuhaib/willitbite/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/willitbite.svg)](https://pypi.org/project/willitbite/)
+
+Ruff will tell you that 99 closures in your codebase capture a loop variable. It will not tell you
+that none of them can actually bite you.
+
+`willitbite` takes the two rules that produce most of the noise when a project first adopts ruff and
+asks the question the linter cannot: **can this one reach you at runtime?**
+
+Here it is on [ragflow](https://github.com/infiniflow/ragflow), 1,259 files of Python, at commit
+`0c28d59`:
+
+```
+$ willitbite .
+B006  mutable default arguments
+  34 warning(s)   0 can bite   1 latent   13 depend on a callee   20 safe
+    [LATENT] agent/component/message.py:159
+             `kwargs` is mutated before it is rebound (kwargs[...] assigned on line
+             181), but all 2 call sites of `get_kwargs()` pass it explicitly, so the
+             shared default is never the one being changed
+
+B023  closures capturing a loop variable
+  99 warning(s)   0 can bite   15 depend on a callee   84 safe
+
+Nothing here can bite today. 133 warning(s), 0 reachable defects, 1 latent.
+```
+
+133 warnings, ten seconds, and 29 of them are worth a person's time: the one latent
+defect and the 28 that turn on a function the tool cannot see into. The other 104 need nobody.
+
+## Why this exists
+
+Both rules describe a shape, and the shape is not the bug.
+
+**B023** flags every closure inside a loop that reads the loop variable. The bug it is looking for is
+late binding: if the closure is still callable after the loop moves on, every copy sees the loop
+variable's final value. A closure that is built and called inside the same iteration sees the value
+it was written next to, which is what the author meant.
+
+**B006** flags every mutable default argument. A mutable default is evaluated once and shared by
+every call that omits it, but that only matters if the function changes it. A default that is only
+read behaves exactly like the immutable one the author probably had in mind.
+
+So a team switching these rules on faces a few hundred warnings, most of which are fine, with no way
+to tell which is which except by reading all of them. That is the job this does.
+
+## Install and run
+
+```
+pip install willitbite
+willitbite ./src
+```
+
+Python 3.10 or newer. To work from a checkout instead:
+
+```
+git clone https://github.com/muhzuhaib/willitbite
+pip install ./willitbite
+```
+
+Ruff is called as a subprocess if it is on your PATH. If you would rather run your own:
+
+```
+ruff check --select B006,B023 --output-format json ./src > warnings.json
+willitbite --json warnings.json
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--all` | list the safe warnings too, not just the actionable ones |
+| `--json-out` | print results as JSON |
+| `--exit-zero` | always exit 0, for a first run that should not fail a build |
+
+Exit code is 1 when something can bite, 0 when nothing can, 2 when the tool could not run.
+
+## Design decisions
+
+**A linter has two states, warned and silent. This has four.** Two of the four exist because the
+honest answer is sometimes neither of the other two.
+
+`CALLEE` is for a closure handed to `run_with_retry(...)`, which is safe if that helper calls it and
+dangerous if it stores it. Guessing safe would clear a real defect. Guessing unsafe would raise a
+false alarm on every codebase this was built against. So it names the function you have to look at
+and stops there.
+
+`LATENT` is for a function that is genuinely wrong and that nothing currently calls in the way that
+would hurt. It has its own section below.
+
+**Ruff finds the candidates; this decides them.** Reimplementing the rules would be slower, less
+correct, and would drift from ruff's behaviour. Ruff is invoked with `--isolated` on purpose, so the
+answer does not depend on whether the project has enabled these rules: a team that has not adopted
+them yet is exactly the team that wants this.
+
+**Ruff is not a dependency.** A tool that reports on your linter should not pin a version of it.
+
+**Every verdict carries a reason you can check without rerunning anything.** The reason names the
+identifier and the line, never restates the rule. A verdict you have to take on trust is worth about
+as much as the warning it replaced.
+
+## Latent defects: real, but nothing calls them that way
+
+A function that mutates its own mutable default is wrong on its own terms. Whether the wrongness can
+reach you is a separate question, and it is answered in the callers: the shared default is only ever
+the object being mutated when somebody omits the argument.
+
+So B006 warnings that survive the first pass get a second one, across every `.py` file under the
+path you gave. If some caller omits the argument, the verdict stays `BITES`. If every caller passes
+it explicitly, the verdict becomes `LATENT`: still a defect, still reported, but nothing in the tree
+triggers it today.
+
+```
+B006  mutable default arguments
+  2 warning(s)   1 can bite   1 latent   0 depend on a callee   0 safe
+    [BITES] live.py:1
+           `cache` is mutated before it is rebound (cache[...] assigned on line 2),
+           so every call that omits it sees the previous call's changes
+    [LATENT] lib.py:1
+           `items` is mutated before it is rebound (items.append() on line 2), but all
+           2 call sites of `collect()` pass it explicitly, so the shared default is
+           never the one being changed
+```
+
+Those two functions have the same shape. Only their callers differ.
+
+**A latent defect does not fail the build.** The exit code answers "can this bite today", and this
+one cannot, so failing on it would fail every build until somebody rewrote code that currently
+works. It is in the report because it will bite the first caller who leaves the argument out.
+
+## Known boundary: which callers get matched
+
+Call sites are matched **by name**. Resolving `x.send()` to a definition properly needs type
+inference, which this does not do, so a call counts whenever the called name matches, wherever it
+appears. That over-matches, and the over-matching is deliberate: an unrelated `send` elsewhere can
+only add an omission, and an omission is the answer that keeps the warning.
+
+Three things count as no evidence at all, and each of them leaves a warning at `BITES`:
+
+- a `**kwargs` splat at the call site, which might be carrying the argument
+- a `*args` splat, which might be filling the position
+- **no caller anywhere**, which usually means a public entry point called from outside the tree you
+  scanned, and is the case most likely to bite a stranger
+
+The index is only built when something came back `BITES`, so a run that finds nothing reachable
+never pays for the scan.
+
+## Where this came from
+
+It was written while triaging 138 ruff warnings across two large open-source Python codebases by
+hand. All 99 loop-closure warnings turned out to be false alarms, as did every mutable-default
+warning that was actually reachable. Reading them one at a time to learn that took most of a day,
+which seemed like a poor way to spend the next one.
+
+## License
+
+MIT