{"id":48327249,"url":"https://github.com/devdanzin/cext-review-toolkit","last_synced_at":"2026-04-05T00:55:18.902Z","repository":{"id":346029720,"uuid":"1186774445","full_name":"devdanzin/cext-review-toolkit","owner":"devdanzin","description":"A Claude Code plugin for reviewing CPython C extensions — finding API misuse, memory safety bugs, compatibility issues, and correctness problems.","archived":false,"fork":false,"pushed_at":"2026-03-29T15:22:40.000Z","size":446,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-29T16:32:16.349Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devdanzin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T01:18:52.000Z","updated_at":"2026-03-29T15:22:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/devdanzin/cext-review-toolkit","commit_stats":null,"previous_names":["devdanzin/cext-review-toolkit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devdanzin/cext-review-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Fcext-review-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Fcext-review-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Fcext-review-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Fcext-review-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devdanzin","download_url":"https://codeload.github.com/devdanzin/cext-review-toolkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Fcext-review-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31420785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T00:55:18.440Z","updated_at":"2026-04-05T00:55:18.894Z","avatar_url":"https://github.com/devdanzin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C Extension Review Toolkit\n\nA [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for reviewing CPython C extensions -- finding API misuse, memory safety bugs, compatibility issues, and correctness problems specific to code that *consumes* the Python/C API.\n\nBuilt for the specific concerns of C extension authors -- reference counting from the caller's perspective, borrowed reference lifetimes, module state management, type slot correctness, stable ABI compliance, and version compatibility -- not general-purpose C analysis.\n\n## Why a Separate Tool?\n\n| Concern | CPython internals (cpython-review-toolkit) | C extensions (this toolkit) |\n|---------|-------------------------------------------|----------------------------|\n| **Perspective** | Code that *implements* the C API | Code that *calls* the C API |\n| **Parsing** | Regex (PEP 7 code is regular) | Tree-sitter (extension code varies wildly) |\n| **Top bug class** | Refcount leaks in runtime code | Borrowed refs held across callbacks |\n| **Module state** | N/A (CPython manages its own) | Core concern -- init style, global state |\n| **Type definitions** | Part of the runtime | Must follow slot contracts correctly |\n| **ABI** | Defines the ABI | Must comply with the ABI |\n| **Dependencies** | stdlib only | tree-sitter, tree-sitter-c |\n\n## Installation\n\n### Marketplace install (recommended)\n\n```bash\nclaude plugin marketplace add devdanzin/cext-review-toolkit\nclaude plugin install cext-review-toolkit@cext-review-toolkit\n```\n\n### Direct install from GitHub\n\n```bash\nclaude plugin install cext-review-toolkit --source github:devdanzin/cext-review-toolkit --path plugins/cext-review-toolkit\n```\n\n### Without installing (try it first)\n\n```bash\ngit clone https://github.com/devdanzin/cext-review-toolkit.git\nclaude --plugin-dir cext-review-toolkit/plugins/cext-review-toolkit\n```\n\n### Prerequisites\n\n- **Claude Code** installed and running\n- **Python 3.10+** for the analysis scripts\n- **tree-sitter** and **tree-sitter-c**: `pip install tree-sitter tree-sitter-c`\n\n## Quick Start\n\nNavigate to a C extension project, then:\n\n```bash\n/cext-review-toolkit:health       # Quick health dashboard\n/cext-review-toolkit:hotspots     # Refcount leaks + error bugs + complexity\n/cext-review-toolkit:explore      # Full exploration (all 10 agents)\n/cext-review-toolkit:migrate      # Modernization checklist\n```\n\nStart with `health` for a quick overview, then `hotspots` to find the highest-impact bugs.\n\n## What's Included\n\n### Agents\n\n#### Safety-Critical (script-backed, Tree-sitter-powered)\n\n| Agent | What It Finds | Script |\n|-------|--------------|--------|\n| **refcount-auditor** | Leaked refs, borrowed-ref-across-callback, stolen-ref misuse, missing Py_CLEAR | `scan_refcounts.py` |\n| **error-path-analyzer** | Missing NULL checks, exception clobbering, return-without-exception | `scan_error_paths.py` |\n| **null-safety-scanner** | Unchecked allocations, deref-before-check | `scan_null_checks.py` |\n| **gil-discipline-checker** | GIL released during Python API, blocking I/O with GIL, callback GIL issues, free-threading readiness | `scan_gil_usage.py` |\n\n#### Extension-Specific (script-backed, Tree-sitter-powered)\n\n| Agent | What It Finds | Script |\n|-------|--------------|--------|\n| **module-state-checker** | Legacy single-phase init, global PyObject* state, missing m_traverse/m_clear, static types | `scan_module_state.py` |\n| **type-slot-checker** | Missing tp_free, traverse gaps, wrong Py_NotImplemented handling, heap type issues | `scan_type_slots.py` |\n\n#### Compatibility (qualitative)\n\n| Agent | What It Finds |\n|-------|--------------|\n| **stable-abi-checker** | Internal struct access, private API calls, limited API violations |\n| **version-compat-scanner** | API calls without version guards, dead compatibility code, deprecated APIs |\n\n#### Code Quality and History\n\n| Agent | What It Finds | Script |\n|-------|--------------|--------|\n| **c-complexity-analyzer** | Functions scored by complexity, nesting, line count | `measure_c_complexity.py` |\n| **git-history-analyzer** | Similar bugs elsewhere, churn-based risk prioritization | `analyze_history.py` |\n\n### Commands\n\n| Command | Purpose | Agents Used |\n|---------|---------|-------------|\n| `explore` | Full analysis with selectable aspects | All (configurable) |\n| `health` | Quick scored dashboard | All in summary mode |\n| `hotspots` | Find worst functions to fix first | refcount + errors + complexity |\n| `migrate` | Modernization checklist | module-state + type-slots + abi + compat |\n\n## How It Works\n\n### Tree-sitter Parsing\n\nUnlike cpython-review-toolkit (regex-based), this toolkit uses Tree-sitter for C parsing. This enables analysis that regex fundamentally cannot do:\n\n- **Borrowed reference lifetime tracking**: Detect when a borrowed ref survives across a call back into Python -- the #1 extension-specific bug pattern\n- **Type slot cross-referencing**: Connect a PyTypeObject/PyType_Spec to its struct definition and slot function implementations\n- **Accurate scope analysis**: Distinguish file-scope static variables from local ones, track variable assignments within functions\n\n### Extension Discovery\n\nThe toolkit auto-detects C extensions in diverse project layouts:\n- `setup.py` with `ext_modules`\n- `pyproject.toml` with setuptools, meson-python, or scikit-build\n- `meson.build` with `py.extension_module()`\n- `CMakeLists.txt` with pybind11 or Python3 library targets\n- Fallback: any `.c` file containing `#include \u003cPython.h\u003e`\n\n### Classification System\n\nEvery finding is tagged:\n\n| Tag | Meaning | Example |\n|-----|---------|---------|\n| **FIX** | Bug causing crashes, leaks, or wrong behavior | Borrowed ref across callback, missing DECREF |\n| **CONSIDER** | Likely improvement, may have migration cost | Single-phase init, missing Py_TPFLAGS_BASETYPE |\n| **POLICY** | Design decision for the maintainer | Whether to adopt stable ABI, drop old Python versions |\n| **ACCEPTABLE** | Noted but no action needed | Intentional global state for singleton module |\n\n### External Tool Integration (Optional)\n\nIf available, the toolkit can use:\n- **clang-tidy** with `compile_commands.json` for deeper data-flow analysis\n- **cppcheck** for buffer overflow and uninitialized variable detection\n\nThese are never required -- the Tree-sitter-based analysis is the baseline.\n\n## Recommended Workflows\n\n### Reviewing an unfamiliar extension\n\n```\n1. /cext-review-toolkit:health              -\u003e Quick overview\n2. /cext-review-toolkit:hotspots            -\u003e Where are the bugs?\n3. /cext-review-toolkit:explore . refcounts errors deep  -\u003e Deep dive on safety\n```\n\n### Preparing for a Python version upgrade\n\n```\n1. /cext-review-toolkit:explore . compat abi  -\u003e What needs to change?\n2. /cext-review-toolkit:migrate               -\u003e Full migration checklist\n```\n\n### Modernizing an extension\n\n```\n1. /cext-review-toolkit:migrate               -\u003e What to modernize\n2. /cext-review-toolkit:explore . module-state type-slots deep  -\u003e Detailed guidance\n```\n\n### Pre-release safety audit\n\n```\n1. /cext-review-toolkit:explore . all deep    -\u003e Full analysis\n2. Focus on FIX findings\n3. Re-run on specific files after fixes\n```\n\n## Explore Command Phases\n\n| Phase | Agents | Purpose |\n|-------|--------|---------|\n| **0** | Extension discovery | Detect layout, source files, Python targets |\n| **1** | (git history noted) | Temporal context available for Phase 2F |\n| **2A** | refcount-auditor, error-path-analyzer | Safety-critical (highest value) |\n| **2B** | null-safety-scanner, gil-discipline-checker | Memory safety |\n| **2C** | module-state-checker, type-slot-checker | Extension correctness |\n| **2D** | stable-abi-checker, version-compat-scanner | Compatibility |\n| **2E** | c-complexity-analyzer | Code quality |\n| **2F** | git-history-analyzer | Similar bugs, risk prioritization |\n| **3** | Synthesis | Deduplicate, resolve conflicts, produce summary |\n\n## Limitations\n\n- **Tree-sitter, not a compiler**: Cannot resolve macros, follow pointer aliasing, or track through complex preprocessor conditionals. Reports candidates with expected 20-40% false positive rate; agents confirm or dismiss each finding.\n- **Single-file scope for scripts**: Scripts analyze each function independently. Cross-function reference ownership transfer is tracked only at the API boundary level.\n- **External tools are optional**: Without `compile_commands.json`, no clang-tidy or cppcheck integration. The Tree-sitter analysis is comprehensive but has inherent limits.\n- **Struct-to-type matching is heuristic**: Connecting a PyTypeObject to its backing struct uses name matching and `tp_basicsize` analysis. Unusual naming or indirection may cause mismatches.\n\n## Comparison with Sibling Projects\n\n| Dimension | code-review-toolkit | cpython-review-toolkit | cext-review-toolkit |\n|-----------|--------------------|-----------------------|--------------------|\n| **Language** | Python | C (CPython source) | C (extensions) |\n| **Parsing** | Python `ast` | Regex | Tree-sitter |\n| **Target** | Python projects | CPython runtime | C extensions |\n| **Agents** | 14 | 10 | 10 |\n| **Scripts** | 8 | 7 | 10 |\n| **Unique value** | Test coverage, architecture | GIL, PEP 7, include graph | Module state, type slots, ABI, migrate |\n\n## Author\n\nDanzin\n\n## License\n\nMIT -- see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevdanzin%2Fcext-review-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevdanzin%2Fcext-review-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevdanzin%2Fcext-review-toolkit/lists"}