codehound 1.4.0__tar.gz → 1.4.1__tar.gz

{codehound-1.4.0 → codehound-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codehound
-Version: 1.4.0
+Version: 1.4.1
 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
@@ -132,7 +132,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.4.0
+    rev: v1.4.1
     hooks:
       - id: codehound
 ```
@@ -153,7 +153,7 @@ repos:
 | **CH008** | `asyncio-run-in-running-loop` | `asyncio.run(...)` called from inside an `async def` — always raises `RuntimeError`, immediately, every time. | hardening rule — zero corpus hits (see below) |
 | **CH009** | `floating-thread` | A non-daemon `threading.Thread` that's `.start()`ed but never `.join()`ed — the thread analog of CH006. | hardening rule — see below |
 | **CH010** | `loop-closure-capture` | A `lambda` inside a `for` loop (or comprehension) that's *stored* (appended, assigned, returned) and captures the loop variable by reference — every stored instance ends up sharing the loop's **final** value. | **accelerate** (HuggingFace) — `MegatronEngine.get_module_config`'s `param_sync_func` list, PR #4273 |
-| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | hardening rule — real hits across litellm, vllm, accelerate, marimo, dspy |
+| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | **optuna** — `_FanovaTree`'s node-lookup methods leaked every tree built for a `get_param_importances()` call; **llama_index** — `VectaraIndex._get_corpus_key` leaked the index *and* broke its own `__del__`-based HTTP session cleanup |
 | **CH012** | `floating-process` | A non-daemon `multiprocessing.Process` that's `.start()`ed but never `.join()`ed — the process analog of CH009. | hardening rule |
 | **CH013** | `discarded-future` | `ThreadPoolExecutor`/`ProcessPoolExecutor.submit(...)` called as a bare statement — the returned `Future` (and any exception raised inside the submitted work) is silently discarded. | hardening rule — real hits in litellm, accelerate, langchain |
 | **CH014** | `unprotected-lock-acquire` | `lock.acquire()` outside a `with`, whose matching `.release()` isn't inside a `finally:` — an exception between acquire and release deadlocks every future caller of that lock. | hardening rule — real hits in vllm, accelerate, torchtune |
@@ -167,11 +167,12 @@ repos:
 `codehound list` prints this from the source of truth.
 
 CH007-CH020 don't have found-and-merged bugs behind all of them the way
-CH001-CH006 and CH010 do - most are hardening rules for well-known Python
+CH001-CH006 do - most are hardening rules for well-known Python
 correctness gotchas rather than something this project personally
-tracked down first. CH010 is the exception: it found a genuine, serious
-bug on its own, in HuggingFace's `accelerate` - see below. Building
-CH007-CH010 surfaced real false positives, each one fixed before shipping:
+tracked down first. CH010 and CH011 are the exceptions: both found
+genuine bugs on their own, in HuggingFace's `accelerate`, optuna, and
+llama_index - see below. Building CH007-CH010 surfaced real false
+positives, each one fixed before shipping:
 
 - **CH007** (agno): a bare `self.foo()` call matched against an unrelated
   same-named `async def foo` on a *different* class (agno's own
@@ -209,6 +210,33 @@ it's very unlikely to survive basic testing; CH007 and CH009 both only
 match same-file names by design, and most real cases of either are
 plausibly cross-module.
 
+**The optuna and llama_index finds (CH011):** both are `@lru_cache(maxsize=
+None)` decorating an instance method - a strong reference to `self`
+retained forever. In optuna, `_FanovaTree`'s node-lookup methods leak
+every tree built for a `get_param_importances()` call (one per
+random-forest estimator). In llama_index, `VectaraIndex._get_corpus_key`
+leaks the index itself - and since `VectaraIndex.__del__` exists
+specifically to close the index's `requests.Session` on garbage
+collection, the leak silently disables that cleanup too, so an HTTP
+session leaks along with every index. Both fixed the same way: move the
+cache from a class-level decorator to a per-instance one built in
+`__init__`, so it's freed with the instance instead of outliving it. Both
+have a regression test verified to fail pre-fix and pass post-fix.
+PRs: [optuna/optuna#6859](https://github.com/optuna/optuna/pull/6859),
+[run-llama/llama_index#23089](https://github.com/run-llama/llama_index/pull/23089).
+
+**CH016 found and fixed its own false positive the day it shipped.** The
+first real-corpus scan of `unclosed-socket` turned up three hits in
+vllm's distributed process-group rendezvous code - all three sockets were
+actually handed off correctly (returned inside a tuple, collected into a
+list that's itself returned, passed as an argument into a function that
+takes ownership), just not in a shape CH005 (the check this one was
+modeled on) ever needed to recognize, since files aren't handed off this
+way nearly as often as rendezvous sockets are. Fixed by treating a name
+as escaped when it's returned as part of a tuple/list or passed as an
+argument to any call. A full corpus rescan afterward found zero remaining
+CH016 hits.
+
 **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
@@ -269,7 +297,7 @@ codehound/
 
 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. 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. 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. 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."
 
 ---
 

{codehound-1.4.0 → codehound-1.4.1}/README.md

@@ -112,7 +112,7 @@ Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in
 ```yaml
 repos:
   - repo: https://github.com/kratos0718/codehound
-    rev: v1.4.0
+    rev: v1.4.1
     hooks:
       - id: codehound
 ```
@@ -133,7 +133,7 @@ repos:
 | **CH008** | `asyncio-run-in-running-loop` | `asyncio.run(...)` called from inside an `async def` — always raises `RuntimeError`, immediately, every time. | hardening rule — zero corpus hits (see below) |
 | **CH009** | `floating-thread` | A non-daemon `threading.Thread` that's `.start()`ed but never `.join()`ed — the thread analog of CH006. | hardening rule — see below |
 | **CH010** | `loop-closure-capture` | A `lambda` inside a `for` loop (or comprehension) that's *stored* (appended, assigned, returned) and captures the loop variable by reference — every stored instance ends up sharing the loop's **final** value. | **accelerate** (HuggingFace) — `MegatronEngine.get_module_config`'s `param_sync_func` list, PR #4273 |
-| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | hardening rule — real hits across litellm, vllm, accelerate, marimo, dspy |
+| **CH011** | `lru-cache-on-method` | `@lru_cache`/`@cache` decorating an instance method — the cache holds a strong reference to `self` forever, so every instance that ever calls the method leaks for the process lifetime. | **optuna** — `_FanovaTree`'s node-lookup methods leaked every tree built for a `get_param_importances()` call; **llama_index** — `VectaraIndex._get_corpus_key` leaked the index *and* broke its own `__del__`-based HTTP session cleanup |
 | **CH012** | `floating-process` | A non-daemon `multiprocessing.Process` that's `.start()`ed but never `.join()`ed — the process analog of CH009. | hardening rule |
 | **CH013** | `discarded-future` | `ThreadPoolExecutor`/`ProcessPoolExecutor.submit(...)` called as a bare statement — the returned `Future` (and any exception raised inside the submitted work) is silently discarded. | hardening rule — real hits in litellm, accelerate, langchain |
 | **CH014** | `unprotected-lock-acquire` | `lock.acquire()` outside a `with`, whose matching `.release()` isn't inside a `finally:` — an exception between acquire and release deadlocks every future caller of that lock. | hardening rule — real hits in vllm, accelerate, torchtune |
@@ -147,11 +147,12 @@ repos:
 `codehound list` prints this from the source of truth.
 
 CH007-CH020 don't have found-and-merged bugs behind all of them the way
-CH001-CH006 and CH010 do - most are hardening rules for well-known Python
+CH001-CH006 do - most are hardening rules for well-known Python
 correctness gotchas rather than something this project personally
-tracked down first. CH010 is the exception: it found a genuine, serious
-bug on its own, in HuggingFace's `accelerate` - see below. Building
-CH007-CH010 surfaced real false positives, each one fixed before shipping:
+tracked down first. CH010 and CH011 are the exceptions: both found
+genuine bugs on their own, in HuggingFace's `accelerate`, optuna, and
+llama_index - see below. Building CH007-CH010 surfaced real false
+positives, each one fixed before shipping:
 
 - **CH007** (agno): a bare `self.foo()` call matched against an unrelated
   same-named `async def foo` on a *different* class (agno's own
@@ -189,6 +190,33 @@ it's very unlikely to survive basic testing; CH007 and CH009 both only
 match same-file names by design, and most real cases of either are
 plausibly cross-module.
 
+**The optuna and llama_index finds (CH011):** both are `@lru_cache(maxsize=
+None)` decorating an instance method - a strong reference to `self`
+retained forever. In optuna, `_FanovaTree`'s node-lookup methods leak
+every tree built for a `get_param_importances()` call (one per
+random-forest estimator). In llama_index, `VectaraIndex._get_corpus_key`
+leaks the index itself - and since `VectaraIndex.__del__` exists
+specifically to close the index's `requests.Session` on garbage
+collection, the leak silently disables that cleanup too, so an HTTP
+session leaks along with every index. Both fixed the same way: move the
+cache from a class-level decorator to a per-instance one built in
+`__init__`, so it's freed with the instance instead of outliving it. Both
+have a regression test verified to fail pre-fix and pass post-fix.
+PRs: [optuna/optuna#6859](https://github.com/optuna/optuna/pull/6859),
+[run-llama/llama_index#23089](https://github.com/run-llama/llama_index/pull/23089).
+
+**CH016 found and fixed its own false positive the day it shipped.** The
+first real-corpus scan of `unclosed-socket` turned up three hits in
+vllm's distributed process-group rendezvous code - all three sockets were
+actually handed off correctly (returned inside a tuple, collected into a
+list that's itself returned, passed as an argument into a function that
+takes ownership), just not in a shape CH005 (the check this one was
+modeled on) ever needed to recognize, since files aren't handed off this
+way nearly as often as rendezvous sockets are. Fixed by treating a name
+as escaped when it's returned as part of a tuple/list or passed as an
+argument to any call. A full corpus rescan afterward found zero remaining
+CH016 hits.
+
 **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
@@ -249,7 +277,7 @@ codehound/
 
 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. 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. 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. 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."
 
 ---
 

{codehound-1.4.0 → codehound-1.4.1}/src/codehound/__init__.py

@@ -12,7 +12,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.4.0"
+__version__ = "1.4.1"
 
 __all__ = [
     "ALL_CHECKS",

{codehound-1.4.0 → codehound-1.4.1}/src/codehound/checks/unclosed_socket.py

@@ -2,10 +2,22 @@
 
 The same shape as CH005's unclosed file handle, for a different resource:
 `s = socket.socket(...)` outside a `with` block, with no matching
-`s.close()` anywhere in the function and no `return`ed ownership hand-off,
-leaks the file descriptor exactly like an unclosed file does - sockets are
-file descriptors on POSIX systems, and Python's socket module supports
-the context-manager protocol specifically so this doesn't happen.
+`s.close()` anywhere in the function and no ownership hand-off, leaks the
+file descriptor exactly like an unclosed file does - sockets are file
+descriptors on POSIX systems, and Python's socket module supports the
+context-manager protocol specifically so this doesn't happen.
+
+Unlike a file handle, a socket used for rendezvous/handshake code is
+routinely handed off by passing it into another call rather than by
+`return`ing it bare or closing it locally - real false positives found in
+vllm's distributed process-group setup: `return port, s` (returned inside
+a tuple, not as the bare name), `socks.append(s)` with the list itself
+returned, and `listen_socket=listen_socket` passed straight into a
+`create_tcp_store(...)` call that takes ownership of it. So a socket name
+is also treated as escaped if it's returned as part of a tuple/list, or
+passed as an argument to any call other than a method called *on* the
+socket itself (`s.bind(...)`, `s.close()`, etc., where the socket is the
+receiver, not an argument).
 """
 
 from __future__ import annotations
@@ -50,6 +62,36 @@ def _has_close_call(scope: ast.AST, name: str) -> bool:
     return False
 
 
+def _is_passed_as_argument(scope: ast.AST, name: str) -> bool:
+    """Is `name` ever passed into a call as an argument (not as the receiver
+    of an attribute call, e.g. `name.bind(...)`)? A socket handed to another
+    call - `store_it(s)`, `things.append(s)`, `f(listen_socket=s)` - has its
+    ownership transferred there, same as a `return`."""
+    for node in ast.walk(scope):
+        if not isinstance(node, ast.Call):
+            continue
+        for arg in node.args:
+            if isinstance(arg, ast.Name) and arg.id == name:
+                return True
+        for kw in node.keywords:
+            if isinstance(kw.value, ast.Name) and kw.value.id == name:
+                return True
+    return False
+
+
+def _return_targets(value: ast.expr | None) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, ast.Name):
+        return [value.id]
+    if isinstance(value, (ast.Tuple, ast.List)):
+        out: list[str] = []
+        for elt in value.elts:
+            out.extend(_return_targets(elt))
+        return out
+    return []
+
+
 class UnclosedSocket(Check):
     code = "CH016"
     name = "unclosed-socket"
@@ -70,12 +112,18 @@ class UnclosedSocket(Check):
             fn = enclosing_function(node, parents)
             if fn is None:
                 continue
-            returns_socket = any(
-                isinstance(n, ast.Return) and isinstance(n.value, ast.Name) and n.value.id in names
-                for n in ast.walk(fn)
-            )
+            returned_names = {
+                n
+                for r in ast.walk(fn)
+                if isinstance(r, ast.Return)
+                for n in _return_targets(r.value)
+            }
             for name in names:
-                if returns_socket or _has_close_call(fn, name):
+                if (
+                    name in returned_names
+                    or _has_close_call(fn, name)
+                    or _is_passed_as_argument(fn, name)
+                ):
                     continue
                 findings.append(
                     Finding(

{codehound-1.4.0 → codehound-1.4.1}/tests/test_checks.py

@@ -724,6 +724,72 @@ def test_ch016_ignores_returned_socket():
     assert _run(code, ["CH016"]) == []
 
 
+def test_ch016_ignores_socket_returned_inside_a_tuple():
+    # Real false positive found in vllm's distributed process-group setup:
+    # `return port, s` hands the socket off to the caller just as much as a
+    # bare `return s` does - it's just wrapped in a tuple alongside other data.
+    code = (
+        "import socket\n"
+        "def bind():\n"
+        "    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
+        "    s.bind(('localhost', 0))\n"
+        "    port = s.getsockname()[1]\n"
+        "    return port, s\n"
+    )
+    assert _run(code, ["CH016"]) == []
+
+
+def test_ch016_ignores_socket_appended_to_a_returned_list():
+    # Real false positive found in vllm: sockets are collected into a list
+    # inside a loop, and the list itself (not any individual socket name) is
+    # returned - `socks.append(s)` is the hand-off.
+    code = (
+        "import socket\n"
+        "def bind_group():\n"
+        "    socks = []\n"
+        "    for _ in range(3):\n"
+        "        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
+        "        s.bind(('localhost', 0))\n"
+        "        socks.append(s)\n"
+        "    return socks\n"
+    )
+    assert _run(code, ["CH016"]) == []
+
+
+def test_ch016_ignores_socket_passed_as_call_argument():
+    # Real false positive found in vllm: a listen socket is built, then
+    # handed straight into another function that takes ownership of it
+    # (`create_tcp_store(..., listen_socket=listen_socket)`), never returned
+    # and never closed in this function because the callee owns it now.
+    code = (
+        "import socket\n"
+        "def setup(host, port):\n"
+        "    listen_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
+        "    listen_socket.bind((host, port))\n"
+        "    listen_socket.listen()\n"
+        "    store = create_tcp_store(host, port, listen_socket=listen_socket)\n"
+        "    return store\n"
+    )
+    assert _run(code, ["CH016"]) == []
+
+
+def test_ch016_still_flags_socket_used_only_as_a_call_receiver():
+    # Guard against the passed-as-argument escape swallowing real bugs:
+    # `s.connect(...)`/`s.recv(...)` use `s` as the receiver of the call, not
+    # as an argument, so this must still be flagged.
+    code = (
+        "import socket\n"
+        "def f():\n"
+        "    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n"
+        "    s.connect(('localhost', 80))\n"
+        "    data = s.recv(1024)\n"
+        "    print(data)\n"
+    )
+    findings = _run(code, ["CH016"])
+    assert len(findings) == 1
+    assert findings[0].code == "CH016"
+
+
 # --- CH017 collections-abc-import ----------------------------------------------------