codehound 1.5.0__tar.gz → 1.7.0__tar.gz

{codehound-1.5.0 → codehound-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codehound
-Version: 1.5.0
+Version: 1.7.0
 Summary: An AST-based static analyzer that hunts real correctness and async-safety bugs in Python code.
 Project-URL: Homepage, https://github.com/kratos0718/codehound
 Project-URL: Issues, https://github.com/kratos0718/codehound/issues
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
 
 <h1 align="center">codehound</h1>
 
-**An AST-based static analyzer that hunts *real* bugs in large Python codebases — twenty-two checks, eight backed by a bug that was actually found and merged (or opened as a PR) into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~29-framework validation corpus instead of just reasoned about.**
+**An AST-based static analyzer that hunts *real* bugs in large Python codebases — thirty-one checks, eight backed by a bug that was actually found and merged (or opened as a PR) into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~29-framework validation corpus instead of just reasoned about.**
 
 [![CI](https://github.com/kratos0718/codehound/actions/workflows/ci.yml/badge.svg)](https://github.com/kratos0718/codehound/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codehound.svg)](https://pypi.org/project/codehound/)
@@ -65,13 +65,27 @@ I was contributing bug fixes to large AI frameworks and noticed the same handful
 
 ---
 
+## How this compares
+
+Being upfront about overlap: `codehound` is not the only tool that catches some of these patterns, and pretending otherwise wouldn't survive five minutes of someone actually checking. [Ruff](https://docs.astral.sh/ruff/)'s `RUF006` already catches a discarded `asyncio.create_task()` (CH006), `flake8-async`'s `ASYNC300` predates it. Ruff's `RUF012` already catches mutable class-level defaults (CH026), `F632` catches `is`-literal comparisons (CH025), `B006`/`UP005`/`E722` cover mutable-default-arguments/deprecated-unittest-aliases/bare-except (CH002/CH024/CH020). Pylint's `W1518` (`method-cache-max-size-none`) is close to a name-for-name match for CH011's `lru_cache`-on-instance-method leak. If you already run ruff and pylint, several of `codehound`'s checks will feel familiar.
+
+What actually seems to be missing elsewhere, as far as I've been able to find:
+
+- **Floating threading/multiprocessing primitives.** `flake8-async`'s blocking-call rules (`ASYNC2xx`) and Ruff's `RUF006` cover `asyncio` specifically; I couldn't find any linter — Ruff, flake8-async, pylint, bandit — that flags a `threading.Thread`/`multiprocessing.Process`/`threading.Timer`/`multiprocessing.Pool` that's started but never joined, cancelled, or closed (CH009, CH012, CH028, CH031). This isn't a niche pattern; it's the exact same bug as the asyncio case, just one abstraction layer down, and nothing else checks for it.
+- **Unawaited coroutines.** Calling an `async def` function as a bare statement — no `await`, no scheduling — silently drops the whole call (CH007). Ruff has an [open, unresolved issue](https://github.com/astral-sh/ruff/issues/9833) asking for exactly this; as of writing, nothing ships it.
+- **Blocking calls to non-stdlib clients inside async functions.** `flake8-async`'s `ASYNC2xx` family only recognizes a fixed denylist (`requests`, `httpx`, `urllib3`, `subprocess`, `open`, `time.sleep`) — a synchronous call to a vector-DB client, an LLM SDK, or any other third-party library inside an `async def` isn't on anyone's list yet. CH001 is on that same denylist today; extending it to common AI/agent SDKs (the exact libraries the frameworks this tool is validated against actually use) is on the roadmap below.
+
+And a difference in kind, not just coverage: every check here is checked against a real corpus, not just reasoned about. [`docs/FINDINGS.md`](docs/FINDINGS.md) has a running ledger of every false positive found while building each check (with the exact framework and line), and two checks that were built, measured, and **rejected outright** when the pattern turned out to be either too common to be a defensible finding (1,911 hits) or premised on something that was actually false (the first two real hits checked turned out to be correct code). I haven't found another static-analysis tool — commercial or open-source — that publishes this kind of "we built it, checked it against real code, and turned it down" ledger. Most tools that market themselves on "catches real bugs" (Greptile, Qodo, CodeRabbit) report an aggregate detection-rate benchmark, not per-rule provenance you can click through to an actual merged fix.
+
+---
+
 ## Install
 
 ```bash
 pip install codehound
 ```
 
-Zero dependencies — it's ~2,600 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
+Zero dependencies — it's ~3,600 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
 
 <details>
 <summary>From a clone instead (for development)</summary>
@@ -132,7 +146,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.5.0
+    rev: v1.7.0
     hooks:
       - id: codehound
 ```
@@ -165,10 +179,19 @@ repos:
 | **CH020** | `bare-except` | A bare `except:` (or unused `except BaseException:`) — also catches `KeyboardInterrupt`/`SystemExit`, so Ctrl-C stops working and `sys.exit()` gets silently absorbed. | hardening rule — real hits in agno, llama_index, marimo, litellm |
 | **CH021** | `removed-stdlib-module` | `import distutils` (removed 3.12) or any of the 19 PEP 594 "dead battery" modules (`cgi`, `imghdr`, `telnetlib`, `nntplib`, …, removed 3.13) — `ImportError` the moment the module loads. | hardening rule — real hit in agno (already guarded, see below) |
 | **CH022** | `removed-asyncio-coroutine-decorator` | `@asyncio.coroutine` — removed in Python 3.11 after a generator-based-coroutine bridge that predates `async def`; `AttributeError` the moment the decorator line runs. | hardening rule |
+| **CH023** | `removed-stdlib-attribute` | A specific removed function on a module that still imports fine — `time.clock()` (3.8), `platform.linux_distribution()`/`.dist()` (3.8), `cgi.escape()` (3.8), `base64.encodestring()`/`.decodestring()` (3.9). | hardening rule — real hit in scikit-learn |
+| **CH024** | `unittest-deprecated-alias` | `self.assertEquals(...)`/`self.failUnless(...)` and a dozen other legacy `unittest.TestCase` aliases — removed in Python 3.12. | hardening rule |
+| **CH025** | `is-literal-comparison` | `x is 1000` / `x is not "foo"` — `is` checks identity, not equality; relies on CPython's small-int caching / string interning, neither guaranteed. (pyflakes F632) | hardening rule — real false positive fixed in litellm's own code, see below |
+| **CH026** | `mutable-class-attribute` | `class C: items = []` mutated via `self.items.append(...)` without ever being reassigned per instance — every instance shares and mutates the *same* list. | **vllm**, **llama_index**, **optuna**, **transformers** — see below |
+| **CH027** | `unwaited-subprocess` | `subprocess.Popen(...)` never `.wait()`ed/`.communicate()`d with, and not context-managed — risks a zombie process and a full pipe buffer deadlocking the child. | hardening rule — real hit in dspy (already handled, see below) |
+| **CH028** | `floating-timer` | `threading.Timer(...)` started but never `.cancel()`ed or handed off — nothing can stop the callback from firing later, on stale context. | hardening rule — real hits in marimo, transformers |
+| **CH029** | `finally-swallows-exception` | `return`/`break`/`continue` in a `finally:` block silently discards any exception from the `try:` — the caller never sees it. | hardening rule — real hits in letta |
+| **CH030** | `lru-cache-on-async-function` | `@lru_cache`/`@cache` on `async def` caches the coroutine *object*, not its result — the second call with the same arguments crashes. | hardening rule |
+| **CH031** | `unclosed-pool` | `multiprocessing.Pool()` never `.close()`d/`.terminate()`d — worker processes leak for the life of the parent. | hardening rule |
 
 `codehound list` prints this from the source of truth.
 
-CH007-CH022 don't have found-and-merged bugs behind all of them the way
+CH007-CH031 don't have found-and-merged bugs behind all of them the way
 CH001-CH006 do - most are hardening rules for well-known Python
 correctness gotchas rather than something this project personally
 tracked down first. CH010 and CH011 are the exceptions: both found
@@ -271,6 +294,79 @@ a `try:` body whose `except` catches `ImportError` (or anything
 broader). A full corpus rescan after both fixes found zero remaining
 CH021 hits.
 
+**CH026 found four real, previously-unreported bugs on its first real
+scan.** All four are the exact same shape: a class-level mutable default
+(`items = []`) mutated in place via `self.items.append(...)` (or
+subscript assignment) with no per-instance reassignment anywhere, so
+every instance of the class shares and corrupts the *same* object. In
+vllm's `AXK1ForCausalLM`, `self.packed_modules_mapping["qkv_proj"] =
+[...]` patches a routing table shared by every instance of the model
+class. In llama_index's `ZapierToolSpec`, `self.spec_functions.append(...)`
+means a second tool-spec instance (a different API key, a different
+user) inherits every action name the first instance ever registered. In
+optuna's CLI `_Studies` command, `self._study_list_header.append(...)`
+does the same to a table-header list. In HuggingFace transformers'
+`CodeGenTokenizer`, `self.model_input_names.append("token_type_ids")`
+means constructing one tokenizer with `return_token_type_ids=True`
+silently changes what field every *other* `CodeGenTokenizer` instance in
+the same process expects, regardless of how it was configured - exactly
+the "spooky action at a distance" class of bug this project exists to
+catch. None have PRs yet: vllm and transformers both require AI-assisted
+PRs to carry an explicit disclosure, which this project's own policy
+doesn't do, so those two are documented here rather than filed.
+
+**CH028 hit the exact same name-collision problem CH018/CH022 already
+had a guard for, because that guard didn't get reused.** The very first
+corpus scan came back with ~30 hits, almost all in agno - which doesn't
+use `threading.Timer` at all. `from agno.utils.timer import Timer` is
+agno's own unrelated stopwatch class, called as `Timer()` with zero
+arguments (real `threading.Timer` requires `interval` and `function` and
+would raise `TypeError` immediately). Fixed by requiring `from threading
+import Timer` before trusting a bare `Timer(...)` call - the same guard
+already built for CH022's `coroutine` minutes earlier in the same
+session, just not applied here the first time. Also missed CH009's
+`daemon=True` escape entirely (found in weaviate-python-client's
+watchdog timer, `_timeout_timer.daemon = True`, a deliberate
+"outlive the caller" choice) - added both a constructor-kwarg and a
+post-construction-assignment check for it, matching CH009 exactly. Real
+hits remain in marimo (a non-daemon browser-opening timer, never
+cancelled) and transformers (a chained, never-captured checkpoint-retry
+timer).
+
+**CH025 and CH027 each found one real bug in the first scan, and one
+real gap in the check.** CH025 (is-literal-comparison) flagged litellm's
+`if "usage" in response_obj is not None:` - but for the wrong reason.
+`ast.Compare` puts every operand and every op from a chained comparison
+in one node; checking "is there a literal anywhere" and "is there an
+`is`/`is not` anywhere" independently, without pairing each op with its
+own adjacent operands, matched the string literal (paired with `in`)
+against the wrong op (`is not`, actually comparing `response_obj` to the
+allowed singleton `None`). Fixed by walking the chain as adjacent
+`(left, op, right)` triples. CH027 (unwaited-subprocess) flagged dspy's
+`process = subprocess.Popen(...)`, followed by `lm.process = process` -
+a real hand-off to a different object, reaped later through a separate
+`terminate_process(lm.process)` call, the same "stored as any object's
+attribute" escape CH009/CH016/CH028 already needed. Added it.
+
+**CH029 found a real bug in letta on day one, and its own precision gap
+right after.** The first corpus scan flagged `except Exception as e:
+result["error"] = str(e)` followed by `finally: return result` in
+letta's job-callback dispatcher - but that except deliberately never
+re-raises (the code comment says so directly: "callback failures should
+not affect job completion"), so nothing is actually pending to swallow
+by the time `finally` runs. Fixed by skipping a `try` whose `except`
+clauses never re-raise anywhere in their own scope - there's nothing
+live left to discard at that point. The same scan also turned up a
+*more serious*, still-real instance in two of letta's LLM streaming
+adapters: `except BaseException: <log, then re-raise a typed error>`
+immediately followed by `finally: if not stream_started: return` -
+except `stream_started` is unconditionally set `True` a few lines
+earlier with no other assignment anywhere in the function, so today
+that specific `return` is dead code, not a currently-live swallow. Read
+carefully rather than assumed, and not filed as a bug report since it
+isn't actually firing right now - but flagged as exactly the kind of
+fragile code a future refactor could silently turn into a real one.
+
 **Two checks we built and did not ship.** `exception-chaining` (`except X
 as e: raise Y(...)` with no `from e`, discarding the real traceback -
 overlaps flake8-bugbear B904) worked exactly as designed, but at a scale
@@ -328,12 +424,21 @@ codehound/
     ├── removed_getargspec.py   (CH019)
     ├── bare_except.py          (CH020)
     ├── removed_stdlib_module.py (CH021)
-    └── asyncio_coroutine_decorator.py (CH022)
+    ├── asyncio_coroutine_decorator.py (CH022)
+    ├── removed_stdlib_attribute.py (CH023)
+    ├── unittest_deprecated_alias.py (CH024)
+    ├── is_literal_comparison.py (CH025)
+    ├── mutable_class_attribute.py (CH026)
+    ├── unwaited_subprocess.py  (CH027)
+    ├── floating_timer.py       (CH028)
+    ├── finally_swallows_exception.py (CH029)
+    ├── lru_cache_on_async_function.py (CH030)
+    └── unclosed_pool.py        (CH031)
 ```
 
 Each check receives a parsed `ast` tree plus the precomputed parent map and returns `Finding`s. Adding a rule is one file + one registry line + a test. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a full walkthrough of the engine, the parent map, and the design decisions.
 
-**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. CH021 doesn't flag a relative import (`node.level != 0`) of a same-named local module, or an import already inside a `try:`/`except ImportError:` fallback — real patterns found in vllm and agno respectively. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
+**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. CH021 doesn't flag a relative import (`node.level != 0`) of a same-named local module, or an import already inside a `try:`/`except ImportError:` fallback — real patterns found in vllm and agno respectively. CH025 pairs each chained comparison's op with only its own adjacent operands, rather than matching a literal and an `is`/`is not` anywhere in the same chain independently — a real pattern found in litellm. CH027 and CH028 both recognize a handle stored as *any* object's attribute as a hand-off, matching CH009/CH016's precedent — real patterns found in dspy and weaviate-python-client respectively. CH028 also only trusts a bare `Timer(...)` when `from threading import Timer` was actually seen — real hits in agno were its own unrelated stopwatch class. CH029 skips a `try` whose `except` clauses never re-raise anywhere in their own scope — a real pattern in letta where the exception is deliberately logged and recorded, never propagated, so a `return` in `finally` isn't discarding anything live. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
 
 ---
 
@@ -365,8 +470,13 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
       sockets, removed-in-3.9/3.10/3.11 stdlib APIs, bare `except:` — CH011-CH020
 - [x] 22 checks — removed stdlib modules (`distutils`, PEP 594 "dead
       batteries"), removed `@asyncio.coroutine` decorator — CH021-CH022
+- [x] 28 checks — removed stdlib functions, deprecated unittest aliases,
+      `is`-literal comparisons, mutable class attributes, unwaited
+      subprocesses, floating timers — CH023-CH028
+- [x] 31 checks — `finally:` blocks that swallow exceptions, `lru_cache`
+      on async functions, unclosed `multiprocessing.Pool` — CH029-CH031
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
-- [ ] Sync HTTP clients constructed inside async request handlers
+- [ ] Extend CH001 to a curated denylist of sync AI/agent SDK client calls inside async functions (vector-DB clients, LLM SDKs) — the gap flake8-async's stdlib-only denylist leaves open
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
 
 ---

{codehound-1.5.0 → codehound-1.7.0}/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">codehound</h1>
 
-**An AST-based static analyzer that hunts *real* bugs in large Python codebases — twenty-two checks, eight backed by a bug that was actually found and merged (or opened as a PR) into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~29-framework validation corpus instead of just reasoned about.**
+**An AST-based static analyzer that hunts *real* bugs in large Python codebases — thirty-one checks, eight backed by a bug that was actually found and merged (or opened as a PR) into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~29-framework validation corpus instead of just reasoned about.**
 
 [![CI](https://github.com/kratos0718/codehound/actions/workflows/ci.yml/badge.svg)](https://github.com/kratos0718/codehound/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/codehound.svg)](https://pypi.org/project/codehound/)
@@ -45,13 +45,27 @@ I was contributing bug fixes to large AI frameworks and noticed the same handful
 
 ---
 
+## How this compares
+
+Being upfront about overlap: `codehound` is not the only tool that catches some of these patterns, and pretending otherwise wouldn't survive five minutes of someone actually checking. [Ruff](https://docs.astral.sh/ruff/)'s `RUF006` already catches a discarded `asyncio.create_task()` (CH006), `flake8-async`'s `ASYNC300` predates it. Ruff's `RUF012` already catches mutable class-level defaults (CH026), `F632` catches `is`-literal comparisons (CH025), `B006`/`UP005`/`E722` cover mutable-default-arguments/deprecated-unittest-aliases/bare-except (CH002/CH024/CH020). Pylint's `W1518` (`method-cache-max-size-none`) is close to a name-for-name match for CH011's `lru_cache`-on-instance-method leak. If you already run ruff and pylint, several of `codehound`'s checks will feel familiar.
+
+What actually seems to be missing elsewhere, as far as I've been able to find:
+
+- **Floating threading/multiprocessing primitives.** `flake8-async`'s blocking-call rules (`ASYNC2xx`) and Ruff's `RUF006` cover `asyncio` specifically; I couldn't find any linter — Ruff, flake8-async, pylint, bandit — that flags a `threading.Thread`/`multiprocessing.Process`/`threading.Timer`/`multiprocessing.Pool` that's started but never joined, cancelled, or closed (CH009, CH012, CH028, CH031). This isn't a niche pattern; it's the exact same bug as the asyncio case, just one abstraction layer down, and nothing else checks for it.
+- **Unawaited coroutines.** Calling an `async def` function as a bare statement — no `await`, no scheduling — silently drops the whole call (CH007). Ruff has an [open, unresolved issue](https://github.com/astral-sh/ruff/issues/9833) asking for exactly this; as of writing, nothing ships it.
+- **Blocking calls to non-stdlib clients inside async functions.** `flake8-async`'s `ASYNC2xx` family only recognizes a fixed denylist (`requests`, `httpx`, `urllib3`, `subprocess`, `open`, `time.sleep`) — a synchronous call to a vector-DB client, an LLM SDK, or any other third-party library inside an `async def` isn't on anyone's list yet. CH001 is on that same denylist today; extending it to common AI/agent SDKs (the exact libraries the frameworks this tool is validated against actually use) is on the roadmap below.
+
+And a difference in kind, not just coverage: every check here is checked against a real corpus, not just reasoned about. [`docs/FINDINGS.md`](docs/FINDINGS.md) has a running ledger of every false positive found while building each check (with the exact framework and line), and two checks that were built, measured, and **rejected outright** when the pattern turned out to be either too common to be a defensible finding (1,911 hits) or premised on something that was actually false (the first two real hits checked turned out to be correct code). I haven't found another static-analysis tool — commercial or open-source — that publishes this kind of "we built it, checked it against real code, and turned it down" ledger. Most tools that market themselves on "catches real bugs" (Greptile, Qodo, CodeRabbit) report an aggregate detection-rate benchmark, not per-rule provenance you can click through to an actual merged fix.
+
+---
+
 ## Install
 
 ```bash
 pip install codehound
 ```
 
-Zero dependencies — it's ~2,600 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
+Zero dependencies — it's ~3,600 lines on top of the standard-library `ast` module, so this installs instantly and runs fully offline, no API key or network call involved.
 
 <details>
 <summary>From a clone instead (for development)</summary>
@@ -112,7 +126,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.5.0
+    rev: v1.7.0
     hooks:
       - id: codehound
 ```
@@ -145,10 +159,19 @@ repos:
 | **CH020** | `bare-except` | A bare `except:` (or unused `except BaseException:`) — also catches `KeyboardInterrupt`/`SystemExit`, so Ctrl-C stops working and `sys.exit()` gets silently absorbed. | hardening rule — real hits in agno, llama_index, marimo, litellm |
 | **CH021** | `removed-stdlib-module` | `import distutils` (removed 3.12) or any of the 19 PEP 594 "dead battery" modules (`cgi`, `imghdr`, `telnetlib`, `nntplib`, …, removed 3.13) — `ImportError` the moment the module loads. | hardening rule — real hit in agno (already guarded, see below) |
 | **CH022** | `removed-asyncio-coroutine-decorator` | `@asyncio.coroutine` — removed in Python 3.11 after a generator-based-coroutine bridge that predates `async def`; `AttributeError` the moment the decorator line runs. | hardening rule |
+| **CH023** | `removed-stdlib-attribute` | A specific removed function on a module that still imports fine — `time.clock()` (3.8), `platform.linux_distribution()`/`.dist()` (3.8), `cgi.escape()` (3.8), `base64.encodestring()`/`.decodestring()` (3.9). | hardening rule — real hit in scikit-learn |
+| **CH024** | `unittest-deprecated-alias` | `self.assertEquals(...)`/`self.failUnless(...)` and a dozen other legacy `unittest.TestCase` aliases — removed in Python 3.12. | hardening rule |
+| **CH025** | `is-literal-comparison` | `x is 1000` / `x is not "foo"` — `is` checks identity, not equality; relies on CPython's small-int caching / string interning, neither guaranteed. (pyflakes F632) | hardening rule — real false positive fixed in litellm's own code, see below |
+| **CH026** | `mutable-class-attribute` | `class C: items = []` mutated via `self.items.append(...)` without ever being reassigned per instance — every instance shares and mutates the *same* list. | **vllm**, **llama_index**, **optuna**, **transformers** — see below |
+| **CH027** | `unwaited-subprocess` | `subprocess.Popen(...)` never `.wait()`ed/`.communicate()`d with, and not context-managed — risks a zombie process and a full pipe buffer deadlocking the child. | hardening rule — real hit in dspy (already handled, see below) |
+| **CH028** | `floating-timer` | `threading.Timer(...)` started but never `.cancel()`ed or handed off — nothing can stop the callback from firing later, on stale context. | hardening rule — real hits in marimo, transformers |
+| **CH029** | `finally-swallows-exception` | `return`/`break`/`continue` in a `finally:` block silently discards any exception from the `try:` — the caller never sees it. | hardening rule — real hits in letta |
+| **CH030** | `lru-cache-on-async-function` | `@lru_cache`/`@cache` on `async def` caches the coroutine *object*, not its result — the second call with the same arguments crashes. | hardening rule |
+| **CH031** | `unclosed-pool` | `multiprocessing.Pool()` never `.close()`d/`.terminate()`d — worker processes leak for the life of the parent. | hardening rule |
 
 `codehound list` prints this from the source of truth.
 
-CH007-CH022 don't have found-and-merged bugs behind all of them the way
+CH007-CH031 don't have found-and-merged bugs behind all of them the way
 CH001-CH006 do - most are hardening rules for well-known Python
 correctness gotchas rather than something this project personally
 tracked down first. CH010 and CH011 are the exceptions: both found
@@ -251,6 +274,79 @@ a `try:` body whose `except` catches `ImportError` (or anything
 broader). A full corpus rescan after both fixes found zero remaining
 CH021 hits.
 
+**CH026 found four real, previously-unreported bugs on its first real
+scan.** All four are the exact same shape: a class-level mutable default
+(`items = []`) mutated in place via `self.items.append(...)` (or
+subscript assignment) with no per-instance reassignment anywhere, so
+every instance of the class shares and corrupts the *same* object. In
+vllm's `AXK1ForCausalLM`, `self.packed_modules_mapping["qkv_proj"] =
+[...]` patches a routing table shared by every instance of the model
+class. In llama_index's `ZapierToolSpec`, `self.spec_functions.append(...)`
+means a second tool-spec instance (a different API key, a different
+user) inherits every action name the first instance ever registered. In
+optuna's CLI `_Studies` command, `self._study_list_header.append(...)`
+does the same to a table-header list. In HuggingFace transformers'
+`CodeGenTokenizer`, `self.model_input_names.append("token_type_ids")`
+means constructing one tokenizer with `return_token_type_ids=True`
+silently changes what field every *other* `CodeGenTokenizer` instance in
+the same process expects, regardless of how it was configured - exactly
+the "spooky action at a distance" class of bug this project exists to
+catch. None have PRs yet: vllm and transformers both require AI-assisted
+PRs to carry an explicit disclosure, which this project's own policy
+doesn't do, so those two are documented here rather than filed.
+
+**CH028 hit the exact same name-collision problem CH018/CH022 already
+had a guard for, because that guard didn't get reused.** The very first
+corpus scan came back with ~30 hits, almost all in agno - which doesn't
+use `threading.Timer` at all. `from agno.utils.timer import Timer` is
+agno's own unrelated stopwatch class, called as `Timer()` with zero
+arguments (real `threading.Timer` requires `interval` and `function` and
+would raise `TypeError` immediately). Fixed by requiring `from threading
+import Timer` before trusting a bare `Timer(...)` call - the same guard
+already built for CH022's `coroutine` minutes earlier in the same
+session, just not applied here the first time. Also missed CH009's
+`daemon=True` escape entirely (found in weaviate-python-client's
+watchdog timer, `_timeout_timer.daemon = True`, a deliberate
+"outlive the caller" choice) - added both a constructor-kwarg and a
+post-construction-assignment check for it, matching CH009 exactly. Real
+hits remain in marimo (a non-daemon browser-opening timer, never
+cancelled) and transformers (a chained, never-captured checkpoint-retry
+timer).
+
+**CH025 and CH027 each found one real bug in the first scan, and one
+real gap in the check.** CH025 (is-literal-comparison) flagged litellm's
+`if "usage" in response_obj is not None:` - but for the wrong reason.
+`ast.Compare` puts every operand and every op from a chained comparison
+in one node; checking "is there a literal anywhere" and "is there an
+`is`/`is not` anywhere" independently, without pairing each op with its
+own adjacent operands, matched the string literal (paired with `in`)
+against the wrong op (`is not`, actually comparing `response_obj` to the
+allowed singleton `None`). Fixed by walking the chain as adjacent
+`(left, op, right)` triples. CH027 (unwaited-subprocess) flagged dspy's
+`process = subprocess.Popen(...)`, followed by `lm.process = process` -
+a real hand-off to a different object, reaped later through a separate
+`terminate_process(lm.process)` call, the same "stored as any object's
+attribute" escape CH009/CH016/CH028 already needed. Added it.
+
+**CH029 found a real bug in letta on day one, and its own precision gap
+right after.** The first corpus scan flagged `except Exception as e:
+result["error"] = str(e)` followed by `finally: return result` in
+letta's job-callback dispatcher - but that except deliberately never
+re-raises (the code comment says so directly: "callback failures should
+not affect job completion"), so nothing is actually pending to swallow
+by the time `finally` runs. Fixed by skipping a `try` whose `except`
+clauses never re-raise anywhere in their own scope - there's nothing
+live left to discard at that point. The same scan also turned up a
+*more serious*, still-real instance in two of letta's LLM streaming
+adapters: `except BaseException: <log, then re-raise a typed error>`
+immediately followed by `finally: if not stream_started: return` -
+except `stream_started` is unconditionally set `True` a few lines
+earlier with no other assignment anywhere in the function, so today
+that specific `return` is dead code, not a currently-live swallow. Read
+carefully rather than assumed, and not filed as a bug report since it
+isn't actually firing right now - but flagged as exactly the kind of
+fragile code a future refactor could silently turn into a real one.
+
 **Two checks we built and did not ship.** `exception-chaining` (`except X
 as e: raise Y(...)` with no `from e`, discarding the real traceback -
 overlaps flake8-bugbear B904) worked exactly as designed, but at a scale
@@ -308,12 +404,21 @@ codehound/
     ├── removed_getargspec.py   (CH019)
     ├── bare_except.py          (CH020)
     ├── removed_stdlib_module.py (CH021)
-    └── asyncio_coroutine_decorator.py (CH022)
+    ├── asyncio_coroutine_decorator.py (CH022)
+    ├── removed_stdlib_attribute.py (CH023)
+    ├── unittest_deprecated_alias.py (CH024)
+    ├── is_literal_comparison.py (CH025)
+    ├── mutable_class_attribute.py (CH026)
+    ├── unwaited_subprocess.py  (CH027)
+    ├── floating_timer.py       (CH028)
+    ├── finally_swallows_exception.py (CH029)
+    ├── lru_cache_on_async_function.py (CH030)
+    └── unclosed_pool.py        (CH031)
 ```
 
 Each check receives a parsed `ast` tree plus the precomputed parent map and returns `Finding`s. Adding a rule is one file + one registry line + a test. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for a full walkthrough of the engine, the parent map, and the design decisions.
 
-**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. CH021 doesn't flag a relative import (`node.level != 0`) of a same-named local module, or an import already inside a `try:`/`except ImportError:` fallback — real patterns found in vllm and agno respectively. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
+**False-positive discipline is a feature.** CH005 won't flag a handle that's `return`ed (the caller owns it) or explicitly `.close()`d. CH006 won't flag `TaskGroup.create_task` (the group holds the reference). CH001 only fires when the *enclosing* function is `async`. CH007 scopes `self.foo()` matches to async methods on the *same* class as the call site, and bare `foo()` matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as *any* object's attribute, not just `self`. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a `BaseException` handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. CH021 doesn't flag a relative import (`node.level != 0`) of a same-named local module, or an import already inside a `try:`/`except ImportError:` fallback — real patterns found in vllm and agno respectively. CH025 pairs each chained comparison's op with only its own adjacent operands, rather than matching a literal and an `is`/`is not` anywhere in the same chain independently — a real pattern found in litellm. CH027 and CH028 both recognize a handle stored as *any* object's attribute as a hand-off, matching CH009/CH016's precedent — real patterns found in dspy and weaviate-python-client respectively. CH028 also only trusts a bare `Timer(...)` when `from threading import Timer` was actually seen — real hits in agno were its own unrelated stopwatch class. CH029 skips a `try` whose `except` clauses never re-raise anywhere in their own scope — a real pattern in letta where the exception is deliberately logged and recorded, never propagated, so a `return` in `finally` isn't discarding anything live. All of those guards exist because of real false positives caught while building the checks (see above and [`docs/FINDINGS.md`](docs/FINDINGS.md)). The test suite asserts both "bad code is flagged" and "correct code is not."
 
 ---
 
@@ -345,8 +450,13 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
       sockets, removed-in-3.9/3.10/3.11 stdlib APIs, bare `except:` — CH011-CH020
 - [x] 22 checks — removed stdlib modules (`distutils`, PEP 594 "dead
       batteries"), removed `@asyncio.coroutine` decorator — CH021-CH022
+- [x] 28 checks — removed stdlib functions, deprecated unittest aliases,
+      `is`-literal comparisons, mutable class attributes, unwaited
+      subprocesses, floating timers — CH023-CH028
+- [x] 31 checks — `finally:` blocks that swallow exceptions, `lru_cache`
+      on async functions, unclosed `multiprocessing.Pool` — CH029-CH031
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
-- [ ] Sync HTTP clients constructed inside async request handlers
+- [ ] Extend CH001 to a curated denylist of sync AI/agent SDK client calls inside async functions (vector-DB clients, LLM SDKs) — the gap flake8-async's stdlib-only denylist leaves open
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
 
 ---

{codehound-1.5.0 → codehound-1.7.0}/src/codehound/__init__.py

@@ -1,9 +1,9 @@
 """codehound - an AST-based static analyzer that hunts real bugs in Python code.
 
-Twenty-two checks. Eight are each backed by a bug that was actually found
-and fixed (or opened as a PR) in a popular open-source AI framework
+Thirty-one checks. Eight are each backed by a bug that was actually
+found and fixed (or opened as a PR) in a popular open-source AI framework
 (agno, crewAI, mem0, llama_index, accelerate, optuna, litellm). The rest
-(CH007-CH009, CH012-CH022) are hardening rules verified against real
+(CH007-CH009, CH012-CH031) are hardening rules verified against real
 false positives across a ~29-framework validation corpus instead - see
 docs/FINDINGS.md.
 """
@@ -13,7 +13,7 @@ from __future__ import annotations
 from codehound.checks import ALL_CHECKS, get_checks
 from codehound.core import Check, Finding, scan_file, scan_path
 
-__version__ = "1.5.0"
+__version__ = "1.7.0"
 
 __all__ = [
     "ALL_CHECKS",

{codehound-1.5.0 → codehound-1.7.0}/src/codehound/checks/__init__.py

@@ -10,20 +10,29 @@ from codehound.checks.blocking_async import BlockingCallInAsync
 from codehound.checks.collections_abc_import import CollectionsAbcImport
 from codehound.checks.datetime_utcnow import DeprecatedDatetimeUtcnow
 from codehound.checks.discarded_future import DiscardedFuture
+from codehound.checks.finally_swallows_exception import FinallySwallowsException
 from codehound.checks.floating_process import FloatingProcess
 from codehound.checks.floating_task import FloatingTask
 from codehound.checks.floating_thread import FloatingThread
+from codehound.checks.floating_timer import FloatingTimer
 from codehound.checks.get_event_loop import DeprecatedGetEventLoop
+from codehound.checks.is_literal_comparison import IsLiteralComparison
 from codehound.checks.loop_closure_capture import LoopClosureCapture
+from codehound.checks.lru_cache_on_async_function import LruCacheOnAsyncFunction
 from codehound.checks.lru_cache_on_method import LruCacheOnMethod
+from codehound.checks.mutable_class_attribute import MutableClassAttribute
 from codehound.checks.mutable_defaults import MutableDefaultArgument
 from codehound.checks.removed_asyncio_task_methods import RemovedAsyncioTaskMethods
 from codehound.checks.removed_getargspec import RemovedGetargspec
+from codehound.checks.removed_stdlib_attribute import RemovedStdlibAttribute
 from codehound.checks.removed_stdlib_module import RemovedStdlibModule
 from codehound.checks.resource_leak import UnclosedFileHandle
 from codehound.checks.unawaited_coroutine import UnawaitedCoroutineCall
+from codehound.checks.unclosed_pool import UnclosedPool
 from codehound.checks.unclosed_socket import UnclosedSocket
+from codehound.checks.unittest_deprecated_alias import UnittestDeprecatedAlias
 from codehound.checks.unprotected_lock import UnprotectedLockAcquire
+from codehound.checks.unwaited_subprocess import UnwaitedSubprocess
 from codehound.core import Check
 
 ALL_CHECKS: list[type[Check]] = [
@@ -49,6 +58,15 @@ ALL_CHECKS: list[type[Check]] = [
     BareExcept,
     RemovedStdlibModule,
     AsyncioCoroutineDecorator,
+    RemovedStdlibAttribute,
+    UnittestDeprecatedAlias,
+    IsLiteralComparison,
+    MutableClassAttribute,
+    UnwaitedSubprocess,
+    FloatingTimer,
+    FinallySwallowsException,
+    LruCacheOnAsyncFunction,
+    UnclosedPool,
 ]
 
 

codehound-1.7.0/src/codehound/checks/finally_swallows_exception.py

@@ -0,0 +1,146 @@
+"""CH029 - ``return``/``break``/``continue`` in a ``finally:`` block silently drops any pending exception.
+
+If the `try:` body raises, and the matching `finally:` block runs a
+`return`, or a `break`/`continue` that jumps to a loop outside the
+`finally` block itself, the exception is discarded entirely - not
+logged, not re-raised, nothing. Verified directly:
+
+    def f():
+        try:
+            raise ValueError("boom")
+        finally:
+            return 5
+
+`f()` returns `5`. The `ValueError` never happens as far as the caller
+can tell. This is documented CPython behavior, not a bug in Python
+itself, but it means an exception can vanish from a `finally:` block
+that looks like ordinary cleanup code, with nothing in the syntax
+calling out that it swallows errors - pylint's own `lost-exception`
+(W0150) exists for exactly this.
+
+A `break`/`continue` fully contained within a loop that itself lives
+inside the `finally:` block is a different, local loop and does not
+escape - only a `break`/`continue` whose target loop is *outside* the
+`finally:` block (an ancestor of the whole `try` statement) swallows
+the pending exception. Verified directly for both shapes.
+
+Not flagged when the `try` has at least one `except` clause and none of
+them ever re-raise: at that point every exception the `try` body could
+produce has already been fully handled by the time control reaches
+`finally`, so a `return`/`break`/`continue` there is just the
+function's normal exit for the already-handled path, not a swallow.
+Real pattern found in letta: `except Exception as e: result["error"] =
+str(e)` (logged, recorded, deliberately not re-raised, the docstring
+literally says "callback failures should not affect job completion")
+followed by `finally: return result` - nothing is pending to discard.
+A `try` with *no* `except` at all is unaffected by this guard, since
+nothing there could have absorbed anything.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding
+
+
+def _has_escaping_return(stmts: list[ast.stmt]) -> ast.Return | None:
+    def walk(node: ast.AST) -> ast.Return | None:
+        if isinstance(node, ast.Return):
+            return node
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            return None
+        for child in ast.iter_child_nodes(node):
+            found = walk(child)
+            if found is not None:
+                return found
+        return None
+
+    for stmt in stmts:
+        found = walk(stmt)
+        if found is not None:
+            return found
+    return None
+
+
+def _owning_loop_is_outside_finally(node: ast.AST, try_node: ast.Try, parents: dict) -> bool:
+    cur: ast.AST | None = node
+    while cur is not None and cur is not try_node:
+        if isinstance(cur, (ast.For, ast.AsyncFor, ast.While)):
+            return False
+        cur = parents.get(id(cur))
+    return True
+
+
+def _find_escaping_break_or_continue(
+    stmts: list[ast.stmt], try_node: ast.Try, parents: dict
+) -> ast.stmt | None:
+    for stmt in stmts:
+        for node in ast.walk(stmt):
+            if isinstance(node, (ast.Break, ast.Continue)) and _owning_loop_is_outside_finally(
+                node, try_node, parents
+            ):
+                return node
+    return None
+
+
+def _has_raise_in_own_scope(handler: ast.ExceptHandler) -> bool:
+    """Any `raise` in the handler's own reachable body - not counting a
+    nested try/except's own handler, which is a different scope."""
+    found = False
+
+    def walk(node: ast.AST) -> None:
+        nonlocal found
+        if found:
+            return
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, ast.Raise):
+                found = True
+                return
+            if isinstance(child, ast.ExceptHandler):
+                continue
+            walk(child)
+
+    walk(handler)
+    return found
+
+
+def _fully_absorbs_exceptions(try_node: ast.Try) -> bool:
+    if not try_node.handlers:
+        return False
+    return all(not _has_raise_in_own_scope(h) for h in try_node.handlers)
+
+
+class FinallySwallowsException(Check):
+    code = "CH029"
+    name = "finally-swallows-exception"
+    description = "return/break/continue in a finally: block silently discards any exception from the try:."
+
+    def run(self, tree: ast.AST, parents: dict, path: str) -> list[Finding]:
+        findings: list[Finding] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Try) or not node.finalbody:
+                continue
+            if _fully_absorbs_exceptions(node):
+                continue
+            culprit: ast.stmt | None = _has_escaping_return(node.finalbody)
+            kind = "return"
+            if culprit is None:
+                culprit = _find_escaping_break_or_continue(node.finalbody, node, parents)
+                kind = "break" if isinstance(culprit, ast.Break) else "continue"
+            if culprit is None:
+                continue
+            findings.append(
+                Finding(
+                    path=path,
+                    line=culprit.lineno,
+                    col=culprit.col_offset,
+                    code=self.code,
+                    message=(
+                        f"`{kind}` in this `finally:` block silently discards any exception "
+                        f"raised in the `try:` body - the caller never sees it. Move the "
+                        f"{kind} out of `finally:`, or re-raise explicitly if that's intended."
+                    ),
+                )
+            )
+        return findings