codehound 0.1.0__tar.gz

codehound-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.DS_Store

codehound-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhinav Tarigoppula
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codehound-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: codehound
+Version: 0.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
+Author: Abhinav Tarigoppula
+License: MIT
+License-File: LICENSE
+Keywords: ast,asyncio,bug-finder,linter,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+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.**
+
+[![CI](https://github.com/kratos0718/codehound/actions/workflows/ci.yml/badge.svg)](https://github.com/kratos0718/codehound/actions/workflows/ci.yml)
+![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)
+
+Most linters flag style. `codehound` flags the *subtle correctness and async-safety bugs* that slip past code review and only bite in production — event-loop stalls, shared mutable state, leaked file descriptors, fire-and-forget tasks that get garbage-collected mid-run.
+
+Each of the six checks below isn't theoretical. **I wrote it after finding — and fixing, via a merged pull request — that exact bug in a real, popular framework** (agno 25k⭐, crewAI 30k⭐, mem0, huggingface_hub).
+
+---
+
+## See it in action
+
+Pointing `codehound` at [agno](https://github.com/agno-agi/agno) (a 25k⭐ AI agent framework) surfaced real, previously-unreported bugs:
+
+```console
+$ codehound scan agno/libs/agno/agno --select CH001,CH006
+
+agno/integrations/discord/client.py:90:26: CH001 `requests.get()` blocks the event loop
+    inside async function `on_message`; use the async equivalent.
+agno/tracing/exporter.py:112:16: CH006 `asyncio.create_task(...)` result is discarded;
+    keep a reference (the loop only holds a weak ref, so the task may be GC'd mid-run).
+
+Found 2 issue(s) (CH001: 1, CH006: 1)
+```
+
+**Both of these became merged/​open fixes upstream.** The first froze the Discord bot's event loop on every video/document attachment; the second could silently drop telemetry when its export task was garbage-collected mid-run. `codehound` found them in seconds — see [`docs/FINDINGS.md`](docs/FINDINGS.md) for the full provenance of every rule.
+
+---
+
+## Why this exists
+
+I was contributing bug fixes to large AI frameworks and noticed the same handful of mistakes recurring across codebases. Instead of hunting them by hand, I encoded each one as an AST rule. `codehound` is the result: point it at a repo and it finds the bugs I'd otherwise have to read 100k lines to spot.
+
+> It found the bugs behind these merged fixes — and is built to find the next one.
+
+---
+
+## Install
+
+```bash
+# from a clone (modern pip)
+pip install -e .
+
+# or run straight from source, no install needed
+PYTHONPATH=src python -m codehound.cli scan path/to/project
+```
+
+## Usage
+
+```bash
+# scan a project (skips tests/, docs/, examples/, vendored code by default)
+codehound scan path/to/project
+
+# only run specific checks
+codehound scan path/to/project --select CH001,CH006
+
+# machine-readable output for CI dashboards
+codehound scan path/to/project --format json
+codehound scan path/to/project --format csv
+
+# list every available check
+codehound list
+```
+
+`codehound scan` exits **non-zero when it finds issues**, so it drops straight into CI:
+
+```yaml
+- run: codehound scan src   # fails the build on a regression
+```
+
+---
+
+## The checks
+
+| Code | Name | What it catches | Found in the wild |
+|------|------|-----------------|-------------------|
+| **CH001** | `blocking-call-in-async` | A synchronous blocking call (`time.sleep`, `requests.*`, `subprocess.*`) inside an `async def` — it freezes the **entire** event loop, stalling every other coroutine. | agno Couchbase vector store (`time.sleep` in an `async` collection-overwrite path) |
+| **CH002** | `mutable-default-argument` | `def f(x=[])` — the default is created once and shared across every call, silently leaking state. (flake8-bugbear B006) | agno toolkits; mem0 proxy & embedder configs |
+| **CH003** | `deprecated-datetime-utcnow` | `datetime.utcnow()` / `utcfromtimestamp()` — deprecated since 3.12, returns a naive datetime that lies about its timezone. | crewAI memory subsystem (9 sites, 4 files) |
+| **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 |
+
+`codehound list` prints this from the source of truth.
+
+---
+
+## How it works
+
+```
+codehound/
+├── core.py          # file discovery, AST parsing, the Finding/Check contract,
+│                    #   and a child→parent map so checks can ask "what's my
+│                    #   enclosing function / am I inside a `with`?"
+├── cli.py           # `scan` / `list`, text|json|csv output, CI-friendly exit codes
+└── checks/          # one small, independently-tested class per rule
+    ├── blocking_async.py     (CH001)
+    ├── mutable_defaults.py   (CH002)
+    ├── datetime_utcnow.py    (CH003)
+    ├── get_event_loop.py     (CH004)
+    ├── resource_leak.py      (CH005)
+    └── floating_task.py      (CH006)
+```
+
+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."
+
+---
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic fix is *not*.
+
+---
+
+## Roadmap
+
+- [ ] `await` on a non-awaited coroutine (missing-await detection)
+- [ ] Sync HTTP clients constructed inside async request handlers
+- [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
+- [ ] Pre-commit hook + PyPI release
+
+---
+
+## License
+
+MIT © Abhinav Tarigoppula

codehound-0.1.0/README.md

@@ -0,0 +1,138 @@
+# 🐕 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.**
+
+[![CI](https://github.com/kratos0718/codehound/actions/workflows/ci.yml/badge.svg)](https://github.com/kratos0718/codehound/actions/workflows/ci.yml)
+![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)
+
+Most linters flag style. `codehound` flags the *subtle correctness and async-safety bugs* that slip past code review and only bite in production — event-loop stalls, shared mutable state, leaked file descriptors, fire-and-forget tasks that get garbage-collected mid-run.
+
+Each of the six checks below isn't theoretical. **I wrote it after finding — and fixing, via a merged pull request — that exact bug in a real, popular framework** (agno 25k⭐, crewAI 30k⭐, mem0, huggingface_hub).
+
+---
+
+## See it in action
+
+Pointing `codehound` at [agno](https://github.com/agno-agi/agno) (a 25k⭐ AI agent framework) surfaced real, previously-unreported bugs:
+
+```console
+$ codehound scan agno/libs/agno/agno --select CH001,CH006
+
+agno/integrations/discord/client.py:90:26: CH001 `requests.get()` blocks the event loop
+    inside async function `on_message`; use the async equivalent.
+agno/tracing/exporter.py:112:16: CH006 `asyncio.create_task(...)` result is discarded;
+    keep a reference (the loop only holds a weak ref, so the task may be GC'd mid-run).
+
+Found 2 issue(s) (CH001: 1, CH006: 1)
+```
+
+**Both of these became merged/​open fixes upstream.** The first froze the Discord bot's event loop on every video/document attachment; the second could silently drop telemetry when its export task was garbage-collected mid-run. `codehound` found them in seconds — see [`docs/FINDINGS.md`](docs/FINDINGS.md) for the full provenance of every rule.
+
+---
+
+## Why this exists
+
+I was contributing bug fixes to large AI frameworks and noticed the same handful of mistakes recurring across codebases. Instead of hunting them by hand, I encoded each one as an AST rule. `codehound` is the result: point it at a repo and it finds the bugs I'd otherwise have to read 100k lines to spot.
+
+> It found the bugs behind these merged fixes — and is built to find the next one.
+
+---
+
+## Install
+
+```bash
+# from a clone (modern pip)
+pip install -e .
+
+# or run straight from source, no install needed
+PYTHONPATH=src python -m codehound.cli scan path/to/project
+```
+
+## Usage
+
+```bash
+# scan a project (skips tests/, docs/, examples/, vendored code by default)
+codehound scan path/to/project
+
+# only run specific checks
+codehound scan path/to/project --select CH001,CH006
+
+# machine-readable output for CI dashboards
+codehound scan path/to/project --format json
+codehound scan path/to/project --format csv
+
+# list every available check
+codehound list
+```
+
+`codehound scan` exits **non-zero when it finds issues**, so it drops straight into CI:
+
+```yaml
+- run: codehound scan src   # fails the build on a regression
+```
+
+---
+
+## The checks
+
+| Code | Name | What it catches | Found in the wild |
+|------|------|-----------------|-------------------|
+| **CH001** | `blocking-call-in-async` | A synchronous blocking call (`time.sleep`, `requests.*`, `subprocess.*`) inside an `async def` — it freezes the **entire** event loop, stalling every other coroutine. | agno Couchbase vector store (`time.sleep` in an `async` collection-overwrite path) |
+| **CH002** | `mutable-default-argument` | `def f(x=[])` — the default is created once and shared across every call, silently leaking state. (flake8-bugbear B006) | agno toolkits; mem0 proxy & embedder configs |
+| **CH003** | `deprecated-datetime-utcnow` | `datetime.utcnow()` / `utcfromtimestamp()` — deprecated since 3.12, returns a naive datetime that lies about its timezone. | crewAI memory subsystem (9 sites, 4 files) |
+| **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 |
+
+`codehound list` prints this from the source of truth.
+
+---
+
+## How it works
+
+```
+codehound/
+├── core.py          # file discovery, AST parsing, the Finding/Check contract,
+│                    #   and a child→parent map so checks can ask "what's my
+│                    #   enclosing function / am I inside a `with`?"
+├── cli.py           # `scan` / `list`, text|json|csv output, CI-friendly exit codes
+└── checks/          # one small, independently-tested class per rule
+    ├── blocking_async.py     (CH001)
+    ├── mutable_defaults.py   (CH002)
+    ├── datetime_utcnow.py    (CH003)
+    ├── get_event_loop.py     (CH004)
+    ├── resource_leak.py      (CH005)
+    └── floating_task.py      (CH006)
+```
+
+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."
+
+---
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic fix is *not*.
+
+---
+
+## Roadmap
+
+- [ ] `await` on a non-awaited coroutine (missing-await detection)
+- [ ] Sync HTTP clients constructed inside async request handlers
+- [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
+- [ ] Pre-commit hook + PyPI release
+
+---
+
+## License
+
+MIT © Abhinav Tarigoppula

codehound-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codehound"
+version = "0.1.0"
+description = "An AST-based static analyzer that hunts real correctness and async-safety bugs in Python code."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Abhinav Tarigoppula" }]
+keywords = ["static-analysis", "linter", "ast", "asyncio", "bug-finder"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/kratos0718/codehound"
+Issues = "https://github.com/kratos0718/codehound/issues"
+
+[project.scripts]
+codehound = "codehound.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codehound"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

codehound-0.1.0/src/codehound/__init__.py

@@ -0,0 +1,22 @@
+"""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).
+"""
+
+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"
+
+__all__ = [
+    "ALL_CHECKS",
+    "get_checks",
+    "Check",
+    "Finding",
+    "scan_file",
+    "scan_path",
+    "__version__",
+]

codehound-0.1.0/src/codehound/checks/__init__.py

@@ -0,0 +1,32 @@
+"""Registry of all available checks."""
+
+from __future__ import annotations
+
+from codehound.checks.blocking_async import BlockingCallInAsync
+from codehound.checks.datetime_utcnow import DeprecatedDatetimeUtcnow
+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.core import Check
+
+ALL_CHECKS: list[type[Check]] = [
+    BlockingCallInAsync,
+    MutableDefaultArgument,
+    DeprecatedDatetimeUtcnow,
+    DeprecatedGetEventLoop,
+    UnclosedFileHandle,
+    FloatingTask,
+]
+
+
+def get_checks(selected: list[str] | None = None) -> list[Check]:
+    """Instantiate checks, optionally filtered by a list of codes/names."""
+    if not selected:
+        return [cls() for cls in ALL_CHECKS]
+    wanted = {s.upper() for s in selected}
+    out: list[Check] = []
+    for cls in ALL_CHECKS:
+        if cls.code.upper() in wanted or cls.name.upper() in wanted:
+            out.append(cls())
+    return out

codehound-0.1.0/src/codehound/checks/blocking_async.py

@@ -0,0 +1,87 @@
+"""CH001 - Blocking call inside an async function.
+
+A synchronous, blocking call (``time.sleep``, ``requests.get`` ...) executed
+directly inside an ``async def`` freezes the *entire* event loop: every other
+coroutine, task and the agent loop itself stalls for the duration of the call.
+The fix is the async equivalent (``await asyncio.sleep``, ``httpx.AsyncClient``,
+``loop.run_in_executor`` ...).
+
+Real-world: this is exactly the bug fixed in agno's Couchbase vector store,
+where ``time.sleep(1)`` sat inside ``_async_create_collection_and_scope``.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding, enclosing_function, is_awaited
+
+# (module, attribute) pairs that block the calling thread.
+_BLOCKING_CALLS = {
+    ("time", "sleep"),
+    ("requests", "get"),
+    ("requests", "post"),
+    ("requests", "put"),
+    ("requests", "delete"),
+    ("requests", "patch"),
+    ("requests", "head"),
+    ("requests", "request"),
+    ("subprocess", "run"),
+    ("subprocess", "call"),
+    ("subprocess", "check_call"),
+    ("subprocess", "check_output"),
+    ("os", "system"),
+    ("urllib.request", "urlopen"),
+}
+
+
+class BlockingCallInAsync(Check):
+    code = "CH001"
+    name = "blocking-call-in-async"
+    description = "Synchronous blocking call inside an async function freezes the event loop."
+
+    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.Call):
+                continue
+            func = node.func
+            if not isinstance(func, ast.Attribute):
+                continue
+            value = func.value
+            # resolve dotted module prefix (e.g. urllib.request)
+            if isinstance(value, ast.Name):
+                module = value.id
+            elif isinstance(value, ast.Attribute):
+                parts = []
+                cur = value
+                while isinstance(cur, ast.Attribute):
+                    parts.append(cur.attr)
+                    cur = cur.value
+                if isinstance(cur, ast.Name):
+                    parts.append(cur.id)
+                module = ".".join(reversed(parts))
+            else:
+                continue
+            if (module, func.attr) not in _BLOCKING_CALLS:
+                continue
+            # An awaited call (e.g. `await client.post(...)`) does not block the
+            # event loop, even if the receiver name collides with a sync library.
+            if is_awaited(node, parents):
+                continue
+            fn = enclosing_function(node, parents)
+            if fn is None or not isinstance(fn, ast.AsyncFunctionDef):
+                continue
+            findings.append(
+                Finding(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset,
+                    code=self.code,
+                    message=(
+                        f"`{module}.{func.attr}()` blocks the event loop inside "
+                        f"async function `{fn.name}`; use the async equivalent."
+                    ),
+                )
+            )
+        return findings

codehound-0.1.0/src/codehound/checks/datetime_utcnow.py

@@ -0,0 +1,52 @@
+"""CH003 - Deprecated ``datetime.utcnow()`` / ``datetime.utcfromtimestamp()``.
+
+These return a *naive* datetime that silently claims to be local time, a
+long-standing footgun. They are deprecated since Python 3.12 and slated for
+removal. Replacement: ``datetime.now(timezone.utc)`` (or, for a naive-UTC
+drop-in, ``datetime.now(timezone.utc).replace(tzinfo=None)``).
+
+Real-world: fixed across crewAI's memory subsystem (9 call sites, 4 files).
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding
+
+_DEPRECATED = {"utcnow", "utcfromtimestamp"}
+
+
+class DeprecatedDatetimeUtcnow(Check):
+    code = "CH003"
+    name = "deprecated-datetime-utcnow"
+    description = "datetime.utcnow()/utcfromtimestamp() are deprecated and return naive datetimes."
+
+    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.Call):
+                continue
+            func = node.func
+            if not isinstance(func, ast.Attribute) or func.attr not in _DEPRECATED:
+                continue
+            # value should be `datetime` (Name) or `<something>.datetime` (Attribute)
+            value = func.value
+            target_ok = (isinstance(value, ast.Name) and value.id == "datetime") or (
+                isinstance(value, ast.Attribute) and value.attr == "datetime"
+            )
+            if not target_ok:
+                continue
+            findings.append(
+                Finding(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset,
+                    code=self.code,
+                    message=(
+                        f"`datetime.{func.attr}()` is deprecated; use "
+                        f"`datetime.now(timezone.utc)`."
+                    ),
+                )
+            )
+        return findings

codehound-0.1.0/src/codehound/checks/floating_task.py

@@ -0,0 +1,58 @@
+"""CH006 - Fire-and-forget asyncio task (Ruff RUF006).
+
+``asyncio.create_task(...)`` / ``asyncio.ensure_future(...)`` whose result is
+discarded is a real, hard-to-debug bug: the event loop keeps only a *weak*
+reference to the task, so it can be garbage-collected before it finishes,
+silently cancelling the work mid-flight. The fix is to keep a strong reference
+(store it in a set, await it, or hand it to a TaskGroup).
+
+This finds expression-statement calls (result not assigned/awaited/returned) to
+``asyncio.create_task``, ``asyncio.ensure_future`` or ``<loop>.create_task``.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding
+
+_CREATORS = {"create_task", "ensure_future"}
+
+
+class FloatingTask(Check):
+    code = "CH006"
+    name = "floating-task"
+    description = "Result of create_task()/ensure_future() discarded; task may be GC'd before completion."
+
+    def run(self, tree: ast.AST, parents: dict, path: str) -> list[Finding]:
+        findings: list[Finding] = []
+        for node in ast.walk(tree):
+            # Only bare expression statements: `asyncio.create_task(...)` on its own line.
+            if not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call):
+                continue
+            call = node.value
+            func = call.func
+            if not isinstance(func, ast.Attribute) or func.attr not in _CREATORS:
+                continue
+            value = func.value
+            if not isinstance(value, ast.Name):
+                continue
+            owner = value.id
+            # asyncio.create_task / asyncio.ensure_future, or a loop-ish receiver.
+            is_asyncio = owner == "asyncio"
+            is_loop = "loop" in owner.lower()
+            if not (is_asyncio or is_loop):
+                continue
+            findings.append(
+                Finding(
+                    path=path,
+                    line=node.lineno,
+                    col=node.col_offset,
+                    code=self.code,
+                    message=(
+                        f"`{owner}.{func.attr}(...)` result is discarded; keep a reference "
+                        f"(the loop only holds a weak ref, so the task may be GC'd mid-run)."
+                    ),
+                )
+            )
+        return findings

codehound-0.1.0/src/codehound/checks/get_event_loop.py

@@ -0,0 +1,47 @@
+"""CH004 - Deprecated ``asyncio.get_event_loop()``.
+
+Calling ``asyncio.get_event_loop()`` when there is no running loop is deprecated
+since Python 3.10 and emits a ``DeprecationWarning`` from 3.12. Inside a
+coroutine, use ``asyncio.get_running_loop()``; to run a coroutine from sync
+code, use ``asyncio.run()``.
+
+Real-world: fixed in crewAI's structured-tool / Snowflake search tool.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding
+
+
+class DeprecatedGetEventLoop(Check):
+    code = "CH004"
+    name = "deprecated-get-event-loop"
+    description = "asyncio.get_event_loop() is deprecated outside a running loop."
+
+    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.Call):
+                continue
+            func = node.func
+            if (
+                isinstance(func, ast.Attribute)
+                and func.attr == "get_event_loop"
+                and isinstance(func.value, ast.Name)
+                and func.value.id == "asyncio"
+            ):
+                findings.append(
+                    Finding(
+                        path=path,
+                        line=node.lineno,
+                        col=node.col_offset,
+                        code=self.code,
+                        message=(
+                            "`asyncio.get_event_loop()` is deprecated; use "
+                            "`asyncio.get_running_loop()` (in async) or `asyncio.run()`."
+                        ),
+                    )
+                )
+        return findings

codehound-0.1.0/src/codehound/checks/mutable_defaults.py

@@ -0,0 +1,53 @@
+"""CH002 - Mutable default argument (Ruff B006 / flake8-bugbear).
+
+``def f(x=[])`` evaluates the default exactly once, at definition time, so the
+*same* list/dict/set is shared across every call. Mutating it leaks state
+between calls - a classic, subtle source of bugs. Fix: default to ``None`` and
+build the container inside the body.
+
+Real-world: fixed across agno's toolkits and mem0's proxy/embedder configs.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding
+
+_MUTABLE_FACTORIES = {"list", "dict", "set", "Counter", "defaultdict", "OrderedDict", "deque"}
+
+
+def _is_mutable_default(node: ast.expr) -> bool:
+    if isinstance(node, (ast.List, ast.Dict, ast.Set)):
+        return True
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+        return node.func.id in _MUTABLE_FACTORIES
+    return False
+
+
+class MutableDefaultArgument(Check):
+    code = "CH002"
+    name = "mutable-default-argument"
+    description = "Mutable default argument is shared across all calls to the function."
+
+    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.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            defaults = list(node.args.defaults) + [d for d in node.args.kw_defaults if d is not None]
+            for default in defaults:
+                if _is_mutable_default(default):
+                    findings.append(
+                        Finding(
+                            path=path,
+                            line=default.lineno,
+                            col=default.col_offset,
+                            code=self.code,
+                            message=(
+                                f"Mutable default in `{node.name}` is shared across calls; "
+                                f"use `None` and create the value inside the body."
+                            ),
+                        )
+                    )
+        return findings

codehound-0.1.0/src/codehound/checks/resource_leak.py

@@ -0,0 +1,95 @@
+"""CH005 - File handle assigned from ``open()`` without a context manager.
+
+``f = open(path)`` outside a ``with`` block leaks the descriptor unless an
+explicit ``f.close()`` runs on every path. Under load this exhausts
+``RLIMIT_NOFILE``. CPython's GC eventually reclaims it, but only when the object
+dies - which may be never if it is captured in a long-lived attribute.
+
+This check flags an ``open(...)`` whose result is assigned to a name, is not
+inside a ``with``, and has no matching ``.close()`` anywhere in the enclosing
+function.
+
+Real-world: fixed in agno's ``OpenAITools.transcribe_audio``.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.core import Check, Finding, enclosing_function, inside_with_statement
+
+
+def _is_open_call(node: ast.expr) -> bool:
+    return isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "open"
+
+
+def _name_targets(target: ast.expr) -> list[str]:
+    if isinstance(target, ast.Name):
+        return [target.id]
+    if isinstance(target, (ast.Tuple, ast.List)):
+        out: list[str] = []
+        for elt in target.elts:
+            out.extend(_name_targets(elt))
+        return out
+    return []
+
+
+def _has_close_call(scope: ast.AST, name: str) -> bool:
+    for node in ast.walk(scope):
+        if isinstance(node, ast.Call):
+            f = node.func
+            if (
+                isinstance(f, ast.Attribute)
+                and f.attr == "close"
+                and isinstance(f.value, ast.Name)
+                and f.value.id == name
+            ):
+                return True
+    return False
+
+
+class UnclosedFileHandle(Check):
+    code = "CH005"
+    name = "unclosed-file-handle"
+    description = "open() result stored without a context manager or matching close()."
+
+    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.Assign) or not _is_open_call(node.value):
+                continue
+            if inside_with_statement(node, parents):
+                continue
+            names: list[str] = []
+            for tgt in node.targets:
+                names.extend(_name_targets(tgt))
+            if not names:
+                continue
+            fn = enclosing_function(node, parents)
+            if fn is None:
+                # module/class-level open() is also suspicious, but we focus on
+                # function scopes where close-tracking is reliable.
+                continue
+            # If the function returns the handle, the caller owns closing it.
+            returns_handle = any(
+                isinstance(n, ast.Return)
+                and isinstance(n.value, ast.Name)
+                and n.value.id in names
+                for n in ast.walk(fn)
+            )
+            for name in names:
+                if returns_handle or _has_close_call(fn, name):
+                    continue
+                findings.append(
+                    Finding(
+                        path=path,
+                        line=node.lineno,
+                        col=node.col_offset,
+                        code=self.code,
+                        message=(
+                            f"`{name} = open(...)` in `{fn.name}` is never closed; "
+                            f"use `with open(...) as {name}:`."
+                        ),
+                    )
+                )
+        return findings

codehound-0.1.0/src/codehound/cli.py

@@ -0,0 +1,102 @@
+"""Command-line interface: ``codehound scan <path>``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from codehound import __version__
+from codehound.checks import ALL_CHECKS, get_checks
+from codehound.core import DEFAULT_SKIP_DIRS, scan_path
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    selected = [s.strip() for s in args.select.split(",")] if args.select else None
+    checks = get_checks(selected)
+    if not checks:
+        print(f"No checks matched: {args.select}", file=sys.stderr)
+        return 2
+
+    skip = set(DEFAULT_SKIP_DIRS)
+    if args.include_tests:
+        skip -= {"tests", "test", "testing"}
+    findings = scan_path(args.path, checks, skip_dirs=frozenset(skip))
+
+    if args.format == "json":
+        print(json.dumps([f.as_dict() for f in findings], indent=2))
+    elif args.format == "csv":
+        print("path,line,col,code,message")
+        for f in findings:
+            msg = f.message.replace('"', "'")
+            print(f'{f.path},{f.line},{f.col},{f.code},"{msg}"')
+    else:  # text
+        for f in findings:
+            print(f.as_text())
+        counts: dict[str, int] = {}
+        for f in findings:
+            counts[f.code] = counts.get(f.code, 0) + 1
+        summary = ", ".join(f"{k}: {v}" for k, v in sorted(counts.items()))
+        print(
+            f"\nFound {len(findings)} issue(s)"
+            + (f" ({summary})" if summary else ""),
+            file=sys.stderr,
+        )
+
+    if findings and not args.exit_zero:
+        return 1
+    return 0
+
+
+def _cmd_list(_args: argparse.Namespace) -> int:
+    for cls in ALL_CHECKS:
+        print(f"{cls.code}  {cls.name}\n      {cls.description}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codehound",
+        description="AST-based static analyzer that hunts real bugs in Python code.",
+    )
+    parser.add_argument("--version", action="version", version=f"codehound {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="scan a file or directory for issues")
+    scan.add_argument("path", help="file or directory to scan")
+    scan.add_argument(
+        "--select",
+        help="comma-separated check codes/names to run (default: all), e.g. CH001,CH006",
+    )
+    scan.add_argument(
+        "--format",
+        choices=["text", "json", "csv"],
+        default="text",
+        help="output format (default: text)",
+    )
+    scan.add_argument(
+        "--include-tests",
+        action="store_true",
+        help="also scan tests/ directories (skipped by default)",
+    )
+    scan.add_argument(
+        "--exit-zero",
+        action="store_true",
+        help="always exit 0, even when issues are found",
+    )
+    scan.set_defaults(func=_cmd_scan)
+
+    listp = sub.add_parser("list", help="list available checks")
+    listp.set_defaults(func=_cmd_list)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codehound-0.1.0/src/codehound/core.py

@@ -0,0 +1,206 @@
+"""Core scanning engine: file discovery, AST parsing, the Finding/Check contract.
+
+The design goal is that every check is a small, independently testable class that
+receives a parsed AST plus a precomputed child->parent map (so checks can ask
+"what is the enclosing function?" cheaply) and returns a list of Findings.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+from dataclasses import dataclass
+from typing import Iterator
+
+
+# Directories we never want to descend into. Third-party and generated code is
+# not ours to fix, and test/example dirs deliberately contain "bad" patterns.
+DEFAULT_SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        "node_modules",
+        "dist",
+        "build",
+        ".venv",
+        "venv",
+        ".tox",
+        ".nox",
+        "vendor",
+        "site-packages",
+        "tests",
+        "test",
+        "testing",
+        "examples",
+        "example",
+        "cookbook",
+        "docs",
+    }
+)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A single rule violation at a specific source location."""
+
+    path: str
+    line: int
+    col: int
+    code: str
+    message: str
+
+    def as_text(self) -> str:
+        return f"{self.path}:{self.line}:{self.col}: {self.code} {self.message}"
+
+    def as_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "line": self.line,
+            "col": self.col,
+            "code": self.code,
+            "message": self.message,
+        }
+
+
+class Check:
+    """Base class for a single static-analysis rule.
+
+    Subclasses set ``code``/``name``/``description`` and implement ``run``.
+    """
+
+    code: str = ""
+    name: str = ""
+    description: str = ""
+
+    def run(self, tree: ast.AST, parents: dict, path: str) -> list[Finding]:
+        raise NotImplementedError
+
+
+# --- AST helpers shared by checks -------------------------------------------------
+
+
+def build_parents(tree: ast.AST) -> dict:
+    """Map ``id(child) -> parent_node`` for the whole tree.
+
+    Python's ``ast`` does not record parents, but several checks need to walk
+    upward (e.g. "is this call inside a ``with`` statement / an ``async def``?").
+    """
+    parents: dict = {}
+    for parent in ast.walk(tree):
+        for child in ast.iter_child_nodes(parent):
+            parents[id(child)] = parent
+    return parents
+
+
+def enclosing_function(node: ast.AST, parents: dict):
+    """Return the nearest enclosing FunctionDef/AsyncFunctionDef, or None."""
+    cur = node
+    while cur is not None:
+        p = parents.get(id(cur))
+        if p is None:
+            return None
+        if isinstance(p, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            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``.
+
+    ``await client.get(...)`` does not block the event loop even though the
+    receiver/attribute name might look like a synchronous library (e.g. a local
+    variable also named ``requests`` that is actually an async HTTP client).
+    """
+    parent = parents.get(id(node))
+    return isinstance(parent, ast.Await)
+
+
+def inside_with_statement(node: ast.AST, parents: dict) -> bool:
+    """True if ``node`` is (transitively) inside a with/async-with, stopping at
+    the enclosing function/class/module boundary."""
+    cur = node
+    while cur is not None:
+        p = parents.get(id(cur))
+        if p is None:
+            return False
+        if isinstance(p, (ast.With, ast.AsyncWith)):
+            return True
+        if isinstance(p, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Module)):
+            return False
+        cur = p
+    return False
+
+
+def attr_call_parts(node: ast.AST):
+    """For a Call like ``a.b()`` return ``("a", "b")``; for ``a.b.c()`` return
+    ``("a.b", "c")``. Returns ``(None, None)`` for non attribute-calls."""
+    if not isinstance(node, ast.Call):
+        return None, None
+    func = node.func
+    if not isinstance(func, ast.Attribute):
+        return None, None
+    attr = func.attr
+    value = func.value
+    if isinstance(value, ast.Name):
+        return value.id, attr
+    if isinstance(value, ast.Attribute):
+        # best-effort dotted prefix, e.g. urllib.request.urlopen
+        parts = []
+        cur = value
+        while isinstance(cur, ast.Attribute):
+            parts.append(cur.attr)
+            cur = cur.value
+        if isinstance(cur, ast.Name):
+            parts.append(cur.id)
+        return ".".join(reversed(parts)), attr
+    return None, attr
+
+
+# --- File discovery and orchestration ---------------------------------------------
+
+
+def iter_python_files(root: str, skip_dirs: frozenset = DEFAULT_SKIP_DIRS) -> Iterator[str]:
+    if os.path.isfile(root):
+        if root.endswith(".py"):
+            yield root
+        return
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in skip_dirs]
+        for fname in filenames:
+            if fname.endswith(".py"):
+                yield os.path.join(dirpath, fname)
+
+
+def scan_file(path: str, checks: list[Check]) -> list[Finding]:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            source = fh.read()
+    except (OSError, UnicodeDecodeError):
+        return []
+    try:
+        tree = ast.parse(source, filename=path)
+    except SyntaxError:
+        return []
+    parents = build_parents(tree)
+    findings: list[Finding] = []
+    for check in checks:
+        findings.extend(check.run(tree, parents, path))
+    return findings
+
+
+def scan_path(
+    root: str,
+    checks: list[Check],
+    skip_dirs: frozenset = DEFAULT_SKIP_DIRS,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    for path in iter_python_files(root, skip_dirs):
+        findings.extend(scan_file(path, checks))
+    findings.sort(key=lambda f: (f.path, f.line, f.col, f.code))
+    return findings

codehound-0.1.0/tests/test_checks.py

@@ -0,0 +1,172 @@
+"""Unit tests for every check, using small inline source snippets.
+
+Each test asserts both that the bad pattern is flagged and that a corrected
+version is *not* flagged (no false positives).
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codehound.checks import get_checks
+from codehound.core import build_parents
+
+
+def _run(code: str, select: list[str]) -> list:
+    tree = ast.parse(code)
+    parents = build_parents(tree)
+    findings = []
+    for check in get_checks(select):
+        findings.extend(check.run(tree, parents, "<test>"))
+    return findings
+
+
+# --- CH001 blocking-call-in-async -------------------------------------------------
+
+
+def test_ch001_flags_time_sleep_in_async():
+    code = (
+        "import time\n"
+        "async def f():\n"
+        "    time.sleep(1)\n"
+    )
+    findings = _run(code, ["CH001"])
+    assert len(findings) == 1
+    assert findings[0].code == "CH001"
+
+
+def test_ch001_ignores_sleep_in_sync_function():
+    code = (
+        "import time\n"
+        "def f():\n"
+        "    time.sleep(1)\n"
+    )
+    assert _run(code, ["CH001"]) == []
+
+
+def test_ch001_ignores_awaited_call_on_sync_named_receiver():
+    # A local variable named `requests` that is actually an async client; the
+    # call is awaited, so it does not block the loop. (Real false positive seen
+    # in AutoGPT's MCP client.)
+    code = (
+        "async def f(self):\n"
+        "    requests = AsyncClient()\n"
+        "    response = await requests.post(self.url, json={})\n"
+    )
+    assert _run(code, ["CH001"]) == []
+
+
+def test_ch001_still_flags_unawaited_blocking_call_in_async():
+    code = (
+        "import requests\n"
+        "async def f(url):\n"
+        "    return requests.get(url)\n"
+    )
+    assert len(_run(code, ["CH001"])) == 1
+
+
+def test_ch001_ignores_await_asyncio_sleep():
+    code = (
+        "import asyncio\n"
+        "async def f():\n"
+        "    await asyncio.sleep(1)\n"
+    )
+    assert _run(code, ["CH001"]) == []
+
+
+# --- CH002 mutable-default-argument -----------------------------------------------
+
+
+def test_ch002_flags_list_default():
+    code = "def f(x=[]):\n    return x\n"
+    findings = _run(code, ["CH002"])
+    assert len(findings) == 1
+
+
+def test_ch002_flags_dict_factory_default():
+    code = "def f(x=dict()):\n    return x\n"
+    assert len(_run(code, ["CH002"])) == 1
+
+
+def test_ch002_ignores_none_default():
+    code = "def f(x=None):\n    return x or []\n"
+    assert _run(code, ["CH002"]) == []
+
+
+# --- CH003 deprecated-datetime-utcnow ---------------------------------------------
+
+
+def test_ch003_flags_utcnow():
+    code = "from datetime import datetime\nx = datetime.utcnow()\n"
+    assert len(_run(code, ["CH003"])) == 1
+
+
+def test_ch003_ignores_now_with_tz():
+    code = "from datetime import datetime, timezone\nx = datetime.now(timezone.utc)\n"
+    assert _run(code, ["CH003"]) == []
+
+
+# --- CH004 deprecated-get-event-loop ----------------------------------------------
+
+
+def test_ch004_flags_get_event_loop():
+    code = "import asyncio\nloop = asyncio.get_event_loop()\n"
+    assert len(_run(code, ["CH004"])) == 1
+
+
+def test_ch004_ignores_get_running_loop():
+    code = "import asyncio\nloop = asyncio.get_running_loop()\n"
+    assert _run(code, ["CH004"]) == []
+
+
+# --- CH005 unclosed-file-handle ---------------------------------------------------
+
+
+def test_ch005_flags_unclosed_open():
+    code = "def f(p):\n    fh = open(p)\n    return fh.read()\n"
+    assert len(_run(code, ["CH005"])) == 1
+
+
+def test_ch005_ignores_with_open():
+    code = "def f(p):\n    with open(p) as fh:\n        return fh.read()\n"
+    assert _run(code, ["CH005"]) == []
+
+
+def test_ch005_ignores_explicit_close():
+    code = "def f(p):\n    fh = open(p)\n    data = fh.read()\n    fh.close()\n    return data\n"
+    assert _run(code, ["CH005"]) == []
+
+
+def test_ch005_ignores_returned_handle():
+    code = "def open_reader(p):\n    fh = open(p, 'rb')\n    return fh\n"
+    assert _run(code, ["CH005"]) == []
+
+
+# --- CH006 floating-task ----------------------------------------------------------
+
+
+def test_ch006_flags_discarded_create_task():
+    code = (
+        "import asyncio\n"
+        "async def f(coro):\n"
+        "    asyncio.create_task(coro)\n"
+    )
+    assert len(_run(code, ["CH006"])) == 1
+
+
+def test_ch006_ignores_referenced_task():
+    code = (
+        "import asyncio\n"
+        "async def f(coro):\n"
+        "    t = asyncio.create_task(coro)\n"
+        "    await t\n"
+    )
+    assert _run(code, ["CH006"]) == []
+
+
+def test_ch006_ignores_taskgroup_create_task():
+    code = (
+        "async def f(tg, coro):\n"
+        "    tg.create_task(coro)\n"
+    )
+    assert _run(code, ["CH006"]) == []