codehound 0.1.0__tar.gz → 1.1.0__tar.gz

{codehound-0.1.0 → codehound-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codehound
-Version: 0.1.0
+Version: 1.1.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
@@ -20,9 +20,10 @@ Description-Content-Type: text/markdown
 
 # 🐕 codehound
 
-**An AST-based static analyzer that hunts *real* bugs in large Python codebases — every rule is backed by a bug that was actually found and merged into a major open-source AI framework.**
+**An AST-based static analyzer that hunts *real* bugs in large Python codebases — six of the seven rules are backed by a bug that was actually found and merged into a major open-source AI framework; the seventh is a hardening rule verified against real false positives instead.**
 
 [![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/)
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21851079.svg)](https://doi.org/10.5281/zenodo.21851079)
@@ -63,13 +64,23 @@ I was contributing bug fixes to large AI frameworks and noticed the same handful
 ## Install
 
 ```bash
-# from a clone (modern pip)
+pip install codehound
+```
+
+Zero dependencies — it's ~750 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>
+
+```bash
 pip install -e .
 
 # or run straight from source, no install needed
 PYTHONPATH=src python -m codehound.cli scan path/to/project
 ```
 
+</details>
+
 ## Usage
 
 ```bash
@@ -105,9 +116,26 @@ codehound list
 | **CH004** | `deprecated-get-event-loop` | `asyncio.get_event_loop()` outside a running loop — deprecated since 3.10. | crewAI structured-tool / Snowflake search tool |
 | **CH005** | `unclosed-file-handle` | `f = open(...)` with no `with` and no matching `.close()` — leaks descriptors until `RLIMIT_NOFILE` is exhausted. | agno `OpenAITools.transcribe_audio` |
 | **CH006** | `floating-task` | `asyncio.create_task(...)` whose result is discarded — the loop keeps only a *weak* reference, so the task can be GC'd before it finishes. (Ruff RUF006) | hardening rule — the most under-caught async bug |
+| **CH007** | `unawaited-coroutine-call` | `foo()` where `foo` is `async def`, called as a bare statement — no `await`, no scheduling. The coroutine object is created and dropped; the body **never runs at all**. | hardening rule — see below |
 
 `codehound list` prints this from the source of truth.
 
+CH007 doesn't have a found-and-merged bug behind it like the other six -
+it targets a well-known Python correctness gotcha (the
+`RuntimeWarning: coroutine 'foo' was never awaited` you get when a
+coroutine is created and discarded) rather than one this project
+personally tracked down. What it does have is two real false positives
+caught and fixed while building it, both against agno: a bare `self.foo()`
+call matched against an unrelated same-named `async def foo` on a
+*different* class (agno's own sync/async "twin method" convention, e.g.
+`ZepTools`/`ZepAsyncTools`), and a plain callable parameter shadowed by an
+unrelated same-named async function hundreds of lines away in the same
+file. Scanning ~20 major Python AI/ML frameworks after fixing both turned
+up zero real instances - itself a result, not a null: it suggests either
+that mature async test suites catch this before merge, or that most real
+cases are cross-module calls, which this check deliberately doesn't chase
+(same-file name matching only, consistent with every other rule here).
+
 ---
 
 ## How it works
@@ -124,12 +152,13 @@ codehound/
     ├── datetime_utcnow.py    (CH003)
     ├── get_event_loop.py     (CH004)
     ├── resource_leak.py      (CH005)
-    └── floating_task.py      (CH006)
+    ├── floating_task.py      (CH006)
+    └── unawaited_coroutine.py (CH007)
 ```
 
 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`. 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 - both guards exist because of real false positives caught while building it (see above). The test suite asserts both "bad code is flagged" and "correct code is not."
 
 ---
 
@@ -146,10 +175,12 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 
 ## Roadmap
 
-- [ ] `await` on a non-awaited coroutine (missing-await detection)
+- [x] `await` on a non-awaited coroutine (missing-await detection) — CH007
+- [x] PyPI release — `pip install codehound`
+- [ ] Cross-module resolution for CH007 (currently same-file only)
 - [ ] Sync HTTP clients constructed inside async request handlers
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
-- [ ] Pre-commit hook + PyPI release
+- [ ] Pre-commit hook
 
 ---
 

{codehound-0.1.0 → codehound-1.1.0}/README.md

@@ -1,8 +1,9 @@
 # 🐕 codehound
 
-**An AST-based static analyzer that hunts *real* bugs in large Python codebases — every rule is backed by a bug that was actually found and merged into a major open-source AI framework.**
+**An AST-based static analyzer that hunts *real* bugs in large Python codebases — six of the seven rules are backed by a bug that was actually found and merged into a major open-source AI framework; the seventh is a hardening rule verified against real false positives instead.**
 
 [![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/)
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21851079.svg)](https://doi.org/10.5281/zenodo.21851079)
@@ -43,13 +44,23 @@ I was contributing bug fixes to large AI frameworks and noticed the same handful
 ## Install
 
 ```bash
-# from a clone (modern pip)
+pip install codehound
+```
+
+Zero dependencies — it's ~750 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>
+
+```bash
 pip install -e .
 
 # or run straight from source, no install needed
 PYTHONPATH=src python -m codehound.cli scan path/to/project
 ```
 
+</details>
+
 ## Usage
 
 ```bash
@@ -85,9 +96,26 @@ codehound list
 | **CH004** | `deprecated-get-event-loop` | `asyncio.get_event_loop()` outside a running loop — deprecated since 3.10. | crewAI structured-tool / Snowflake search tool |
 | **CH005** | `unclosed-file-handle` | `f = open(...)` with no `with` and no matching `.close()` — leaks descriptors until `RLIMIT_NOFILE` is exhausted. | agno `OpenAITools.transcribe_audio` |
 | **CH006** | `floating-task` | `asyncio.create_task(...)` whose result is discarded — the loop keeps only a *weak* reference, so the task can be GC'd before it finishes. (Ruff RUF006) | hardening rule — the most under-caught async bug |
+| **CH007** | `unawaited-coroutine-call` | `foo()` where `foo` is `async def`, called as a bare statement — no `await`, no scheduling. The coroutine object is created and dropped; the body **never runs at all**. | hardening rule — see below |
 
 `codehound list` prints this from the source of truth.
 
+CH007 doesn't have a found-and-merged bug behind it like the other six -
+it targets a well-known Python correctness gotcha (the
+`RuntimeWarning: coroutine 'foo' was never awaited` you get when a
+coroutine is created and discarded) rather than one this project
+personally tracked down. What it does have is two real false positives
+caught and fixed while building it, both against agno: a bare `self.foo()`
+call matched against an unrelated same-named `async def foo` on a
+*different* class (agno's own sync/async "twin method" convention, e.g.
+`ZepTools`/`ZepAsyncTools`), and a plain callable parameter shadowed by an
+unrelated same-named async function hundreds of lines away in the same
+file. Scanning ~20 major Python AI/ML frameworks after fixing both turned
+up zero real instances - itself a result, not a null: it suggests either
+that mature async test suites catch this before merge, or that most real
+cases are cross-module calls, which this check deliberately doesn't chase
+(same-file name matching only, consistent with every other rule here).
+
 ---
 
 ## How it works
@@ -104,12 +132,13 @@ codehound/
     ├── datetime_utcnow.py    (CH003)
     ├── get_event_loop.py     (CH004)
     ├── resource_leak.py      (CH005)
-    └── floating_task.py      (CH006)
+    ├── floating_task.py      (CH006)
+    └── unawaited_coroutine.py (CH007)
 ```
 
 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`. 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 - both guards exist because of real false positives caught while building it (see above). The test suite asserts both "bad code is flagged" and "correct code is not."
 
 ---
 
@@ -126,10 +155,12 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 
 ## Roadmap
 
-- [ ] `await` on a non-awaited coroutine (missing-await detection)
+- [x] `await` on a non-awaited coroutine (missing-await detection) — CH007
+- [x] PyPI release — `pip install codehound`
+- [ ] Cross-module resolution for CH007 (currently same-file only)
 - [ ] Sync HTTP clients constructed inside async request handlers
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
-- [ ] Pre-commit hook + PyPI release
+- [ ] Pre-commit hook
 
 ---
 

{codehound-0.1.0 → codehound-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codehound"
-version = "0.1.0"
+dynamic = ["version"]
 description = "An AST-based static analyzer that hunts real correctness and async-safety bugs in Python code."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -30,6 +30,9 @@ codehound = "codehound.cli:main"
 [project.optional-dependencies]
 dev = ["pytest>=7"]
 
+[tool.hatch.version]
+path = "src/codehound/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/codehound"]
 

{codehound-0.1.0 → codehound-1.1.0}/src/codehound/__init__.py

@@ -1,7 +1,9 @@
 """codehound - an AST-based static analyzer that hunts real bugs in Python code.
 
-Six checks, each backed by a bug that was actually found and fixed in a popular
-open-source AI framework (agno, crewAI, mem0, huggingface_hub).
+Seven checks. Six are each backed by a bug that was actually found and
+fixed in a popular open-source AI framework (agno, crewAI, mem0,
+llama_index, huggingface_hub). The seventh (CH007) is a hardening rule
+verified against real false positives instead - see docs/FINDINGS.md.
 """
 
 from __future__ import annotations
@@ -9,7 +11,7 @@ from __future__ import annotations
 from codehound.checks import ALL_CHECKS, get_checks
 from codehound.core import Check, Finding, scan_file, scan_path
 
-__version__ = "0.1.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "ALL_CHECKS",

{codehound-0.1.0 → codehound-1.1.0}/src/codehound/checks/__init__.py

@@ -8,6 +8,7 @@ from codehound.checks.floating_task import FloatingTask
 from codehound.checks.get_event_loop import DeprecatedGetEventLoop
 from codehound.checks.mutable_defaults import MutableDefaultArgument
 from codehound.checks.resource_leak import UnclosedFileHandle
+from codehound.checks.unawaited_coroutine import UnawaitedCoroutineCall
 from codehound.core import Check
 
 ALL_CHECKS: list[type[Check]] = [
@@ -17,6 +18,7 @@ ALL_CHECKS: list[type[Check]] = [
     DeprecatedGetEventLoop,
     UnclosedFileHandle,
     FloatingTask,
+    UnawaitedCoroutineCall,
 ]
 
 

codehound-1.1.0/src/codehound/checks/unawaited_coroutine.py

@@ -0,0 +1,113 @@
+"""CH007 - Coroutine called without ``await`` (or scheduling).
+
+Calling an ``async def`` function produces a coroutine object; it does not run
+any of the function's body until something ``await``s it, wraps it in
+``asyncio.create_task``/``asyncio.gather``, or otherwise drives it. A bare
+``foo()`` where ``foo`` is a coroutine function, used as a standalone
+statement, creates the coroutine and immediately discards it - the work
+inside never executes at all, and Python emits a
+``RuntimeWarning: coroutine 'foo' was never awaited`` (easy to miss if
+warnings aren't surfaced in CI).
+
+This is a stricter cousin of CH006 (floating-task): CH006's task is at least
+*scheduled* and can still fail mid-run; here nothing ever starts.
+
+Precision matters a lot here specifically because the sync/async "twin
+method" convention (a `def foo` and an `async def foo` on two different
+classes, e.g. `Toolkit` vs `AsyncToolkit`) is common in exactly the
+codebases this tool targets - a naive whole-file name match flags every
+`self.foo()` call against *any* same-named async method anywhere in the
+file, sync twin included. Two real false positives found this way while
+building this check (agno's `ZepTools`/`ZepAsyncTools.initialize`, and a
+`write` call parameter shadowed by an unrelated same-named async closure
+hundreds of lines away) are why the matching below is scoped:
+
+- `foo()` (bare name): only matches a module-level `async def foo`, and
+  only if `foo` isn't also a parameter of the enclosing function (a
+  parameter shadows any outer name with the same spelling).
+- `self.foo()` / `cls.foo()`: only matches an `async def foo` defined
+  directly in the *same* enclosing class as the call site - not a
+  same-named method on an unrelated class elsewhere in the file.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding, enclosing_class, enclosing_function
+
+
+class UnawaitedCoroutineCall(Check):
+    code = "CH007"
+    name = "unawaited-coroutine-call"
+    description = "async function called without await/create_task; the coroutine never runs."
+
+    def run(self, tree: ast.AST, parents: dict, path: str) -> list[Finding]:
+        module_level_async: set[str] = set()
+        class_async_methods: dict[int, set[str]] = {}
+
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.AsyncFunctionDef):
+                continue
+            parent = parents.get(id(node))
+            if isinstance(parent, ast.Module):
+                module_level_async.add(node.name)
+            elif isinstance(parent, ast.ClassDef):
+                class_async_methods.setdefault(id(parent), set()).add(node.name)
+
+        if not module_level_async and not class_async_methods:
+            return []
+
+        findings: list[Finding] = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call):
+                continue
+            call = node.value
+            func = call.func
+            called_name = None
+
+            if isinstance(func, ast.Name):
+                if func.id in module_level_async and not self._is_shadowed_param(
+                    func.id, node, parents
+                ):
+                    called_name = func.id
+            elif isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+                if func.value.id in ("self", "cls"):
+                    owning_class = enclosing_class(node, parents)
+                    if owning_class is not None and func.attr in class_async_methods.get(
+                        id(owning_class), set()
+                    ):
+                        called_name = func.attr
+
+            if called_name is None:
+                continue
+
+            findings.append(
+                Finding(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset,
+                    code=self.code,
+                    message=(
+                        f"`{called_name}(...)` is an async function called without `await` "
+                        f"or scheduling; the coroutine is created and immediately discarded, "
+                        f"so its body never runs."
+                    ),
+                )
+            )
+        return findings
+
+    @staticmethod
+    def _is_shadowed_param(name: str, node: ast.AST, parents: dict) -> bool:
+        fn = enclosing_function(node, parents)
+        if fn is None:
+            return False
+        args = fn.args
+        all_params = (
+            args.posonlyargs
+            + args.args
+            + args.kwonlyargs
+            + ([args.vararg] if args.vararg else [])
+            + ([args.kwarg] if args.kwarg else [])
+        )
+        return any(a.arg == name for a in all_params)

{codehound-0.1.0 → codehound-1.1.0}/src/codehound/core.py

@@ -110,6 +110,25 @@ def enclosing_function(node: ast.AST, parents: dict):
     return None
 
 
+def enclosing_class(node: ast.AST, parents: dict) -> ast.ClassDef | None:
+    """Return the nearest enclosing ClassDef, or None.
+
+    Stops at the first FunctionDef/AsyncFunctionDef boundary that isn't
+    itself inside the class body being searched for - i.e. this walks up
+    through nested functions too, so a method's inner helper still resolves
+    to the class it's defined in.
+    """
+    cur = node
+    while cur is not None:
+        p = parents.get(id(cur))
+        if p is None:
+            return None
+        if isinstance(p, ast.ClassDef):
+            return p
+        cur = p
+    return None
+
+
 def is_awaited(node: ast.AST, parents: dict) -> bool:
     """True if the call ``node`` is the direct operand of an ``await``.
 

{codehound-0.1.0 → codehound-1.1.0}/tests/test_checks.py

@@ -170,3 +170,113 @@ def test_ch006_ignores_taskgroup_create_task():
         "    tg.create_task(coro)\n"
     )
     assert _run(code, ["CH006"]) == []
+
+
+# --- CH007 unawaited-coroutine-call ------------------------------------------------
+
+
+def test_ch007_flags_bare_call_to_async_function():
+    code = (
+        "async def fetch():\n"
+        "    ...\n"
+        "async def f():\n"
+        "    fetch()\n"
+    )
+    findings = _run(code, ["CH007"])
+    assert len(findings) == 1
+    assert findings[0].code == "CH007"
+
+
+def test_ch007_ignores_awaited_call():
+    code = (
+        "async def fetch():\n"
+        "    ...\n"
+        "async def f():\n"
+        "    await fetch()\n"
+    )
+    assert _run(code, ["CH007"]) == []
+
+
+def test_ch007_ignores_call_wrapped_in_create_task():
+    code = (
+        "import asyncio\n"
+        "async def fetch():\n"
+        "    ...\n"
+        "async def f():\n"
+        "    asyncio.create_task(fetch())\n"
+    )
+    assert _run(code, ["CH007"]) == []
+
+
+def test_ch007_ignores_assigned_result():
+    code = (
+        "async def fetch():\n"
+        "    ...\n"
+        "async def f():\n"
+        "    coro = fetch()\n"
+        "    await coro\n"
+    )
+    assert _run(code, ["CH007"]) == []
+
+
+def test_ch007_ignores_call_to_sync_function():
+    code = (
+        "def fetch():\n"
+        "    ...\n"
+        "async def f():\n"
+        "    fetch()\n"
+    )
+    assert _run(code, ["CH007"]) == []
+
+
+def test_ch007_flags_bare_call_to_async_method_via_self():
+    code = (
+        "class C:\n"
+        "    async def fetch(self):\n"
+        "        ...\n"
+        "    async def f(self):\n"
+        "        self.fetch()\n"
+    )
+    findings = _run(code, ["CH007"])
+    assert len(findings) == 1
+    assert findings[0].code == "CH007"
+
+
+def test_ch007_ignores_returned_coroutine():
+    code = (
+        "async def fetch():\n"
+        "    ...\n"
+        "def f():\n"
+        "    return fetch()\n"
+    )
+    assert _run(code, ["CH007"]) == []
+
+
+def test_ch007_ignores_sync_twin_method_on_different_class():
+    # Real false positive found in agno: ZepTools.initialize is sync,
+    # ZepAsyncTools.initialize (a different class) is async - calling
+    # self.initialize() from ZepTools must not match the unrelated twin.
+    code = (
+        "class ZepTools:\n"
+        "    def __init__(self):\n"
+        "        self.initialize()\n"
+        "    def initialize(self):\n"
+        "        ...\n"
+        "class ZepAsyncTools:\n"
+        "    async def initialize(self):\n"
+        "        ...\n"
+    )
+    assert _run(code, ["CH007"]) == []
+
+
+def test_ch007_ignores_name_shadowed_by_parameter():
+    # Real false positive found in agno: an unrelated `async def write`
+    # exists elsewhere in the file, but `write` here is a plain callable
+    # parameter, not a reference to that function.
+    code = (
+        "def run_with_retry(write):\n"
+        "    write()\n"
+        "async def write():\n"
+        "    ...\n"
+    )
+    assert _run(code, ["CH007"]) == []