codehound 1.6.0__tar.gz → 1.8.0__tar.gz

{codehound-1.6.0 → codehound-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codehound
-Version: 1.6.0
+Version: 1.8.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
@@ -16,6 +16,7 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.9
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: tomli>=2; (python_version < '3.11') and extra == 'dev'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -24,7 +25,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-eight 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 +66,29 @@ 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.
+
+**Closing the "toy project" gaps, honestly.** Ruff is a single, fast binary with editor integrations, a plugin-free config file, autofix, and inline suppression - table stakes for a tool people actually adopt, not just admire. `codehound` isn't going to out-perform a Rust tool by staying pure Python, but it now has the parts of that list that don't require rewriting the whole thing: a `[tool.codehound]` block in `pyproject.toml`, `# noqa`/`# noqa: CH001` inline suppression (same syntax flake8/ruff already use, so it doesn't collide with either), `--fix` for the two checks where the rewrite is genuinely unambiguous (CH017 always, CH004 only inside `async def` - guessing wrong on the rest would be worse than not fixing them), and scanning parallelized across a process pool once there's enough files to make that worth it. Measured, not claimed: a full scan of HuggingFace's `transformers` (thousands of files) went from 57 seconds to 12 - verified byte-identical against the sequential result first, not just "seems faster."
+
+---
+
 ## Install
 
 ```bash
 pip install codehound
 ```
 
-Zero dependencies — it's ~3,200 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 ~4,000 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>
@@ -97,6 +114,9 @@ codehound scan file1.py file2.py src/
 # only run specific checks
 codehound scan path/to/project --select CH001,CH006
 
+# also skip extra directories beyond the built-in defaults
+codehound scan path/to/project --exclude migrations,generated
+
 # machine-readable output for CI dashboards
 codehound scan path/to/project --format json
 codehound scan path/to/project --format csv
@@ -104,6 +124,9 @@ codehound scan path/to/project --format csv
 # GitHub Code Scanning (Security tab) can ingest this directly
 codehound scan path/to/project --format sarif > results.sarif
 
+# rewrite the fixable findings in place, then report what's left
+codehound scan path/to/project --fix
+
 # list every available check
 codehound list
 ```
@@ -114,6 +137,32 @@ codehound list
 - run: codehound scan src   # fails the build on a regression
 ```
 
+A finding you've reviewed and want to keep suppresses the same way flake8/ruff findings do - a trailing `# noqa` (everything on that line) or `# noqa: CH001` (just that code):
+
+```python
+time.sleep(1)  # noqa: CH001 - deliberate; this branch only runs at startup, before the loop exists
+```
+
+### Config file
+
+Drop defaults into `[tool.codehound]` in `pyproject.toml` so you don't have to repeat flags on every invocation - explicit CLI flags always win over these:
+
+```toml
+[tool.codehound]
+select = ["CH001", "CH006"]   # same as --select
+exclude = ["migrations"]      # extra directories to skip, merged with the built-in defaults
+paths = ["src"]                # what `codehound scan` (no path args) scans
+```
+
+Requires Python 3.11+ to load (uses the standard-library `tomllib`) - on 3.9/3.10 the config file is silently skipped and every flag still works exactly the same via the CLI, since nothing about codehound itself depends on being able to read it.
+
+### `--fix`
+
+Only two checks ship an autofix, and deliberately so - every other check either needs a judgment call (is this "leak" actually intentional?) or an import that may or may not already be in scope, and guessing wrong there is worse than just reporting the finding:
+
+- **CH017** - `collections.<ABC>` → `collections.abc.<ABC>`, a pure rename, always safe.
+- **CH004** - `asyncio.get_event_loop()` → `asyncio.get_running_loop()`, but *only* inside an `async def`. Outside one, `get_running_loop()` raises where `get_event_loop()` wouldn't, so those calls are left as detection-only.
+
 ### GitHub Action
 
 ```yaml
@@ -132,7 +181,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.6.0
+    rev: v1.8.0
     hooks:
       - id: codehound
 ```
@@ -171,10 +220,13 @@ repos:
 | **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-CH028 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
@@ -331,6 +383,25 @@ 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
@@ -394,12 +465,15 @@ codehound/
     ├── is_literal_comparison.py (CH025)
     ├── mutable_class_attribute.py (CH026)
     ├── unwaited_subprocess.py  (CH027)
-    └── floating_timer.py       (CH028)
+    ├── 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. 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. 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."
 
 ---
 
@@ -434,9 +508,20 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 - [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
+- [x] Inline `# noqa` / `# noqa: CH001` suppression
+- [x] `[tool.codehound]` project config in `pyproject.toml` (`select`,
+      `exclude`, `paths` — Python 3.11+ to load, every flag still works
+      without it on 3.9/3.10)
+- [x] `--fix` — CH017 always, CH004 only inside `async def` (CH002/CH003
+      turned out to need judgment calls or import-injection this tool
+      won't guess at, so they stay detection-only; see docs/ARCHITECTURE.md)
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
-- [ ] Sync HTTP clients constructed inside async request handlers
-- [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
+- [ ] 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
+- [x] Parallelize scanning across files for large codebases — a full
+      HuggingFace transformers scan went from 57s to 12s (measured,
+      byte-identical output verified against the sequential run)
 
 ---
 

{codehound-1.6.0 → codehound-1.8.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-eight 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,29 @@ 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.
+
+**Closing the "toy project" gaps, honestly.** Ruff is a single, fast binary with editor integrations, a plugin-free config file, autofix, and inline suppression - table stakes for a tool people actually adopt, not just admire. `codehound` isn't going to out-perform a Rust tool by staying pure Python, but it now has the parts of that list that don't require rewriting the whole thing: a `[tool.codehound]` block in `pyproject.toml`, `# noqa`/`# noqa: CH001` inline suppression (same syntax flake8/ruff already use, so it doesn't collide with either), `--fix` for the two checks where the rewrite is genuinely unambiguous (CH017 always, CH004 only inside `async def` - guessing wrong on the rest would be worse than not fixing them), and scanning parallelized across a process pool once there's enough files to make that worth it. Measured, not claimed: a full scan of HuggingFace's `transformers` (thousands of files) went from 57 seconds to 12 - verified byte-identical against the sequential result first, not just "seems faster."
+
+---
+
 ## Install
 
 ```bash
 pip install codehound
 ```
 
-Zero dependencies — it's ~3,200 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 ~4,000 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>
@@ -77,6 +93,9 @@ codehound scan file1.py file2.py src/
 # only run specific checks
 codehound scan path/to/project --select CH001,CH006
 
+# also skip extra directories beyond the built-in defaults
+codehound scan path/to/project --exclude migrations,generated
+
 # machine-readable output for CI dashboards
 codehound scan path/to/project --format json
 codehound scan path/to/project --format csv
@@ -84,6 +103,9 @@ codehound scan path/to/project --format csv
 # GitHub Code Scanning (Security tab) can ingest this directly
 codehound scan path/to/project --format sarif > results.sarif
 
+# rewrite the fixable findings in place, then report what's left
+codehound scan path/to/project --fix
+
 # list every available check
 codehound list
 ```
@@ -94,6 +116,32 @@ codehound list
 - run: codehound scan src   # fails the build on a regression
 ```
 
+A finding you've reviewed and want to keep suppresses the same way flake8/ruff findings do - a trailing `# noqa` (everything on that line) or `# noqa: CH001` (just that code):
+
+```python
+time.sleep(1)  # noqa: CH001 - deliberate; this branch only runs at startup, before the loop exists
+```
+
+### Config file
+
+Drop defaults into `[tool.codehound]` in `pyproject.toml` so you don't have to repeat flags on every invocation - explicit CLI flags always win over these:
+
+```toml
+[tool.codehound]
+select = ["CH001", "CH006"]   # same as --select
+exclude = ["migrations"]      # extra directories to skip, merged with the built-in defaults
+paths = ["src"]                # what `codehound scan` (no path args) scans
+```
+
+Requires Python 3.11+ to load (uses the standard-library `tomllib`) - on 3.9/3.10 the config file is silently skipped and every flag still works exactly the same via the CLI, since nothing about codehound itself depends on being able to read it.
+
+### `--fix`
+
+Only two checks ship an autofix, and deliberately so - every other check either needs a judgment call (is this "leak" actually intentional?) or an import that may or may not already be in scope, and guessing wrong there is worse than just reporting the finding:
+
+- **CH017** - `collections.<ABC>` → `collections.abc.<ABC>`, a pure rename, always safe.
+- **CH004** - `asyncio.get_event_loop()` → `asyncio.get_running_loop()`, but *only* inside an `async def`. Outside one, `get_running_loop()` raises where `get_event_loop()` wouldn't, so those calls are left as detection-only.
+
 ### GitHub Action
 
 ```yaml
@@ -112,7 +160,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.6.0
+    rev: v1.8.0
     hooks:
       - id: codehound
 ```
@@ -151,10 +199,13 @@ repos:
 | **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-CH028 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
@@ -311,6 +362,25 @@ 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
@@ -374,12 +444,15 @@ codehound/
     ├── is_literal_comparison.py (CH025)
     ├── mutable_class_attribute.py (CH026)
     ├── unwaited_subprocess.py  (CH027)
-    └── floating_timer.py       (CH028)
+    ├── 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. 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. 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."
 
 ---
 
@@ -414,9 +487,20 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 - [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
+- [x] Inline `# noqa` / `# noqa: CH001` suppression
+- [x] `[tool.codehound]` project config in `pyproject.toml` (`select`,
+      `exclude`, `paths` — Python 3.11+ to load, every flag still works
+      without it on 3.9/3.10)
+- [x] `--fix` — CH017 always, CH004 only inside `async def` (CH002/CH003
+      turned out to need judgment calls or import-injection this tool
+      won't guess at, so they stay detection-only; see docs/ARCHITECTURE.md)
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
-- [ ] Sync HTTP clients constructed inside async request handlers
-- [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
+- [ ] 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
+- [x] Parallelize scanning across files for large codebases — a full
+      HuggingFace transformers scan went from 57s to 12s (measured,
+      byte-identical output verified against the sequential run)
 
 ---
 

{codehound-1.6.0 → codehound-1.8.0}/pyproject.toml

@@ -28,7 +28,7 @@ Issues = "https://github.com/kratos0718/codehound/issues"
 codehound = "codehound.cli:main"
 
 [project.optional-dependencies]
-dev = ["pytest>=7"]
+dev = ["pytest>=7", "tomli>=2; python_version < '3.11'"]
 
 [tool.hatch.version]
 path = "src/codehound/__init__.py"

codehound-1.8.0/src/codehound/__init__.py

@@ -0,0 +1,33 @@
+"""codehound - an AST-based static analyzer that hunts real bugs in Python code.
+
+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-CH031) are hardening rules verified against real
+false positives across a ~29-framework validation corpus instead - see
+docs/FINDINGS.md.
+
+Also has the parts of a production-grade linter that don't require
+rewriting the whole thing in Rust: inline `# noqa` suppression,
+`[tool.codehound]` project config, `--fix` for the checks where the
+rewrite is genuinely unambiguous, and scanning parallelized across a
+process pool for large codebases.
+"""
+
+from __future__ import annotations
+
+from codehound.checks import ALL_CHECKS, get_checks
+from codehound.core import Check, Finding, scan_file, scan_files, scan_path
+
+__version__ = "1.8.0"
+
+__all__ = [
+    "ALL_CHECKS",
+    "get_checks",
+    "Check",
+    "Finding",
+    "scan_file",
+    "scan_files",
+    "scan_path",
+    "__version__",
+]

{codehound-1.6.0 → codehound-1.8.0}/src/codehound/checks/__init__.py

@@ -10,6 +10,7 @@ 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
@@ -17,6 +18,7 @@ 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
@@ -26,6 +28,7 @@ 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
@@ -61,6 +64,9 @@ ALL_CHECKS: list[type[Check]] = [
     MutableClassAttribute,
     UnwaitedSubprocess,
     FloatingTimer,
+    FinallySwallowsException,
+    LruCacheOnAsyncFunction,
+    UnclosedPool,
 ]
 
 

codehound-1.8.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