codetruth 0.2.0__tar.gz

codetruth-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alaik Asif Sheik
+
+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.

codetruth-0.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: codetruth
+Version: 0.2.0
+Summary: A verification layer that lets AI agents safely delete code in large codebases
+Author: Alaik Asif Sheik
+License: MIT
+Project-URL: Homepage, https://github.com/AlaikAsif/CodeTruth
+Project-URL: Repository, https://github.com/AlaikAsif/CodeTruth
+Project-URL: Issues, https://github.com/AlaikAsif/CodeTruth/issues
+Keywords: dead-code,static-analysis,ai-agents,mcp,deletion-safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=3.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: javascript
+Requires-Dist: tree-sitter>=0.21; extra == "javascript"
+Requires-Dist: tree-sitter-language-pack>=0.6; extra == "javascript"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: tree-sitter>=0.21; extra == "dev"
+Requires-Dist: tree-sitter-language-pack>=0.6; extra == "dev"
+Dynamic: license-file
+
+# CodeTruth
+
+[![CI](https://github.com/AlaikAsif/CodeTruth/actions/workflows/ci.yml/badge.svg)](https://github.com/AlaikAsif/CodeTruth/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+**A verification layer that lets AI agents safely delete code in large codebases.**
+
+Agents hallucinate absence of usage. CodeTruth inverts the question — instead of
+*"is this code used?"* it asks **"can we prove this code is used?"** — and only
+surfaces a symbol for deletion when it fails to find *any* usage path: no call,
+no import, no inheritance, no string reference, no reflection target, no
+framework registration. Detection is deterministic; the agent only reads the
+evidence and decides. It is a **risk assessor for code deletion**, not a dead
+code detector.
+
+## Statuses
+
+| Status | Meaning | Recommended action |
+|---|---|---|
+| `safe_to_delete` | zero usage paths found under every analysis rule, **and** the name verified absent from all repo text outside its own definition | `delete` |
+| `likely_dead` | no usage found, but external exposure can't be ruled out (public API, module, test-only) | `review_required` |
+| `uncertain_dynamic_risk` | weak evidence exists (string refs, reflection, dynamic module) | `review_required` |
+| `definitely_used` | strong reference or framework entry point proven | `keep` |
+
+## Install
+
+```bash
+pip install -e .          # from this repo
+pip install -e .[mcp]     # with the MCP server
+```
+
+## MCP (the primary interface — for agents)
+
+```bash
+claude mcp add codetruth -- codetruth mcp
+```
+
+Tools exposed: `scan(repo_path, ...)` and `check_deletion_safety(repo_path, symbol)`.
+The agent workflow: identify symbol → call `check_deletion_safety` → only delete
+on `safe_to_delete`; everything else routes to human review.
+
+## CLI
+
+```bash
+codetruth scan ./repo                     # review queue, strongest candidates first
+codetruth scan ./repo -v --json out.json  # full evidence
+codetruth scan ./repo --app-mode          # application (not library) repos:
+                                          # public symbols may be safe_to_delete
+codetruth scan ./repo --strict            # flag orphaned "useless clumps"
+codetruth scan ./repo --min-rank 0.5 --group   # trim the tail, group by file
+codetruth scan ./repo --html report.html  # self-contained HTML report
+codetruth scan ./repo --ci                # exit 1 if dead code exists (report gate)
+codetruth check ./repo pkg.module:func    # one symbol's evidence record
+codetruth plan  ./repo pkg.module:func    # advisory deletion plan (never applied)
+```
+
+The `--ci` gate is advisory like everything else: it *fails the build* so a
+human looks at provably-dead code — it never deletes. Mark false alarms with
+`# codetruth: keep` or a `.codetruth.toml` entrypoint.
+
+## Python API
+
+```python
+from codetruth import scan, check_deletion_safety
+
+result = scan("./repo")
+for rec in result.candidates():
+    print(rec.status.value, rec.symbol, rec.evidence_against_deletion)
+```
+
+## Runtime evidence (v1.5)
+
+Static analysis can't see cross-service usage (HTTP calls, queues, cron in
+other repos). `@codetruth.track` logs real invocations in production:
+
+```python
+import codetruth
+
+@codetruth.track
+def maybe_dead(): ...
+```
+
+Or instrument a whole package with zero source edits:
+
+```python
+import codetruth.runtime
+codetruth.runtime.instrument_package("myapp")   # or CODETRUTH_AUTOTRACK=myapp
+```
+
+Then feed the trace back: `codetruth scan ./repo --runtime-log runtime.jsonl`.
+Observed calls promote a symbol to `definitely_used`; *"0 calls over N days"*
+becomes the strongest evidence tier for deletion.
+
+Tracing is production-safe: each process writes its own `runtime-<pid>.jsonl`
+(merged at read — no lock contention between workers), and a daemon thread
+flushes counts every `$CODETRUTH_FLUSH_INTERVAL` seconds (default 60), so
+long-running servers land evidence without a clean exit.
+
+## Finding useless clumps (strict reachability)
+
+`codetruth scan ./repo --strict` asks a harder question: *is this code
+reachable from any real entry point* (HTTP route, CLI command, `__main__`,
+test, declared entrypoint)? Code that is internally well-connected — functions
+calling each other — but never reached from an entry point surfaces as an
+orphaned clump, with every member carrying a `cluster` field listing its
+fellow members so the whole island can be reviewed (and deleted) as a group.
+Dead-cluster grouping also applies in default mode whenever unreachable
+symbols reference each other.
+
+## Configuration (`.codetruth.toml`)
+
+Teach the scanner about usage it can't see:
+
+```toml
+[codetruth]
+app_mode = true                    # public symbols are internal (application)
+entrypoints = [                    # externally-reached symbols (cron, RPC, ...)
+    "jobs.nightly:run",
+    "services.handlers.*",
+]
+ignore_paths = ["migrations/", "vendor/**"]
+```
+
+Inline: a `# codetruth: keep` comment on (or above) a definition marks it as
+an entry point.
+
+## Deletion plans (advisory)
+
+`codetruth plan ./repo pkg.mod:symbol` (also the `plan_deletion` MCP tool, and
+attached automatically to every `safe_to_delete` record) describes exactly what
+a removal would involve: the decorator-to-end source span, imports that become
+orphaned, and any `__all__` entry. CodeTruth **never applies** a plan — it is
+information for whoever decides.
+
+## Review-queue ranking
+
+Every record carries a `rank_score` in `[0, 1]` — a deterministic ordering
+heuristic (not a calibrated probability; see PLAN.md §4). Higher means weaker
+evidence of use, so `scan()` and the CLI surface the strongest deletion
+targets first. Within `uncertain_dynamic_risk` it separates a lone
+string-literal reference from forty fuzzy attribute-name matches, so a big
+review queue is triageable instead of flat.
+
+## Performance
+
+Scans are cached at `<repo>/.codetruth/index.json`, keyed by a fingerprint of
+every source and config file's `(mtime, size)`. An unchanged repo returns the
+cached result (≈15× faster on an 8k-symbol repo); any file change triggers a
+full rescan. The cache never patches the graph incrementally — a stale
+cross-file edge could mask a real usage path, so correctness always wins.
+Bypass with `--no-cache` (CLI) or `force_rescan` (MCP). Add `.codetruth/` to
+`.gitignore`.
+
+## Architecture
+
+```
+Layer 1  Symbol Extraction    codetruth/languages/python/extractor.py
+Layer 2  Relationship Graph   codetruth/languages/python/edges.py   (strong/weak edges)
+Layer 3  Semantic Rules       codetruth/languages/python/rules.py + codetruth/rules/python/*.yaml
+Layer 4  Evidence + Decision  codetruth/core/evidence.py            (4-way status)
+```
+
+The core engine is language-agnostic (`codetruth/core/`, `LanguagePlugin`
+interface). **Python** is the full v1 plugin (FastAPI, Django, Celery, click,
+pytest, SQLAlchemy, Typer rule coverage). **JavaScript/TypeScript** is a beta
+plugin (`pip install codetruth[javascript]`, then `scan --language javascript`):
+tree-sitter extraction, ESM/CommonJS import resolution, package.json
+entry points, string/config wiring, eval poisoning, and external-base cautions
+— with the shared evidence, ranking, cluster, backstop, and cache layers
+working unchanged. Go remains a stub.
+
+## Known limitations
+
+- Cross-service usage is invisible to static analysis alone — runtime tracing
+  is the partial fix.
+- 100% certainty is impossible; `safe_to_delete` means "no usage path found
+  under the defined rules," not a mathematical proof.
+- Framework rule coverage (Layer 3) is a maintained knowledge base, never
+  finished. New rules go in `codetruth/rules/python/*.yaml` — no code changes.

codetruth-0.2.0/README.md

@@ -0,0 +1,180 @@
+# CodeTruth
+
+[![CI](https://github.com/AlaikAsif/CodeTruth/actions/workflows/ci.yml/badge.svg)](https://github.com/AlaikAsif/CodeTruth/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+**A verification layer that lets AI agents safely delete code in large codebases.**
+
+Agents hallucinate absence of usage. CodeTruth inverts the question — instead of
+*"is this code used?"* it asks **"can we prove this code is used?"** — and only
+surfaces a symbol for deletion when it fails to find *any* usage path: no call,
+no import, no inheritance, no string reference, no reflection target, no
+framework registration. Detection is deterministic; the agent only reads the
+evidence and decides. It is a **risk assessor for code deletion**, not a dead
+code detector.
+
+## Statuses
+
+| Status | Meaning | Recommended action |
+|---|---|---|
+| `safe_to_delete` | zero usage paths found under every analysis rule, **and** the name verified absent from all repo text outside its own definition | `delete` |
+| `likely_dead` | no usage found, but external exposure can't be ruled out (public API, module, test-only) | `review_required` |
+| `uncertain_dynamic_risk` | weak evidence exists (string refs, reflection, dynamic module) | `review_required` |
+| `definitely_used` | strong reference or framework entry point proven | `keep` |
+
+## Install
+
+```bash
+pip install -e .          # from this repo
+pip install -e .[mcp]     # with the MCP server
+```
+
+## MCP (the primary interface — for agents)
+
+```bash
+claude mcp add codetruth -- codetruth mcp
+```
+
+Tools exposed: `scan(repo_path, ...)` and `check_deletion_safety(repo_path, symbol)`.
+The agent workflow: identify symbol → call `check_deletion_safety` → only delete
+on `safe_to_delete`; everything else routes to human review.
+
+## CLI
+
+```bash
+codetruth scan ./repo                     # review queue, strongest candidates first
+codetruth scan ./repo -v --json out.json  # full evidence
+codetruth scan ./repo --app-mode          # application (not library) repos:
+                                          # public symbols may be safe_to_delete
+codetruth scan ./repo --strict            # flag orphaned "useless clumps"
+codetruth scan ./repo --min-rank 0.5 --group   # trim the tail, group by file
+codetruth scan ./repo --html report.html  # self-contained HTML report
+codetruth scan ./repo --ci                # exit 1 if dead code exists (report gate)
+codetruth check ./repo pkg.module:func    # one symbol's evidence record
+codetruth plan  ./repo pkg.module:func    # advisory deletion plan (never applied)
+```
+
+The `--ci` gate is advisory like everything else: it *fails the build* so a
+human looks at provably-dead code — it never deletes. Mark false alarms with
+`# codetruth: keep` or a `.codetruth.toml` entrypoint.
+
+## Python API
+
+```python
+from codetruth import scan, check_deletion_safety
+
+result = scan("./repo")
+for rec in result.candidates():
+    print(rec.status.value, rec.symbol, rec.evidence_against_deletion)
+```
+
+## Runtime evidence (v1.5)
+
+Static analysis can't see cross-service usage (HTTP calls, queues, cron in
+other repos). `@codetruth.track` logs real invocations in production:
+
+```python
+import codetruth
+
+@codetruth.track
+def maybe_dead(): ...
+```
+
+Or instrument a whole package with zero source edits:
+
+```python
+import codetruth.runtime
+codetruth.runtime.instrument_package("myapp")   # or CODETRUTH_AUTOTRACK=myapp
+```
+
+Then feed the trace back: `codetruth scan ./repo --runtime-log runtime.jsonl`.
+Observed calls promote a symbol to `definitely_used`; *"0 calls over N days"*
+becomes the strongest evidence tier for deletion.
+
+Tracing is production-safe: each process writes its own `runtime-<pid>.jsonl`
+(merged at read — no lock contention between workers), and a daemon thread
+flushes counts every `$CODETRUTH_FLUSH_INTERVAL` seconds (default 60), so
+long-running servers land evidence without a clean exit.
+
+## Finding useless clumps (strict reachability)
+
+`codetruth scan ./repo --strict` asks a harder question: *is this code
+reachable from any real entry point* (HTTP route, CLI command, `__main__`,
+test, declared entrypoint)? Code that is internally well-connected — functions
+calling each other — but never reached from an entry point surfaces as an
+orphaned clump, with every member carrying a `cluster` field listing its
+fellow members so the whole island can be reviewed (and deleted) as a group.
+Dead-cluster grouping also applies in default mode whenever unreachable
+symbols reference each other.
+
+## Configuration (`.codetruth.toml`)
+
+Teach the scanner about usage it can't see:
+
+```toml
+[codetruth]
+app_mode = true                    # public symbols are internal (application)
+entrypoints = [                    # externally-reached symbols (cron, RPC, ...)
+    "jobs.nightly:run",
+    "services.handlers.*",
+]
+ignore_paths = ["migrations/", "vendor/**"]
+```
+
+Inline: a `# codetruth: keep` comment on (or above) a definition marks it as
+an entry point.
+
+## Deletion plans (advisory)
+
+`codetruth plan ./repo pkg.mod:symbol` (also the `plan_deletion` MCP tool, and
+attached automatically to every `safe_to_delete` record) describes exactly what
+a removal would involve: the decorator-to-end source span, imports that become
+orphaned, and any `__all__` entry. CodeTruth **never applies** a plan — it is
+information for whoever decides.
+
+## Review-queue ranking
+
+Every record carries a `rank_score` in `[0, 1]` — a deterministic ordering
+heuristic (not a calibrated probability; see PLAN.md §4). Higher means weaker
+evidence of use, so `scan()` and the CLI surface the strongest deletion
+targets first. Within `uncertain_dynamic_risk` it separates a lone
+string-literal reference from forty fuzzy attribute-name matches, so a big
+review queue is triageable instead of flat.
+
+## Performance
+
+Scans are cached at `<repo>/.codetruth/index.json`, keyed by a fingerprint of
+every source and config file's `(mtime, size)`. An unchanged repo returns the
+cached result (≈15× faster on an 8k-symbol repo); any file change triggers a
+full rescan. The cache never patches the graph incrementally — a stale
+cross-file edge could mask a real usage path, so correctness always wins.
+Bypass with `--no-cache` (CLI) or `force_rescan` (MCP). Add `.codetruth/` to
+`.gitignore`.
+
+## Architecture
+
+```
+Layer 1  Symbol Extraction    codetruth/languages/python/extractor.py
+Layer 2  Relationship Graph   codetruth/languages/python/edges.py   (strong/weak edges)
+Layer 3  Semantic Rules       codetruth/languages/python/rules.py + codetruth/rules/python/*.yaml
+Layer 4  Evidence + Decision  codetruth/core/evidence.py            (4-way status)
+```
+
+The core engine is language-agnostic (`codetruth/core/`, `LanguagePlugin`
+interface). **Python** is the full v1 plugin (FastAPI, Django, Celery, click,
+pytest, SQLAlchemy, Typer rule coverage). **JavaScript/TypeScript** is a beta
+plugin (`pip install codetruth[javascript]`, then `scan --language javascript`):
+tree-sitter extraction, ESM/CommonJS import resolution, package.json
+entry points, string/config wiring, eval poisoning, and external-base cautions
+— with the shared evidence, ranking, cluster, backstop, and cache layers
+working unchanged. Go remains a stub.
+
+## Known limitations
+
+- Cross-service usage is invisible to static analysis alone — runtime tracing
+  is the partial fix.
+- 100% certainty is impossible; `safe_to_delete` means "no usage path found
+  under the defined rules," not a mathematical proof.
+- Framework rule coverage (Layer 3) is a maintained knowledge base, never
+  finished. New rules go in `codetruth/rules/python/*.yaml` — no code changes.

codetruth-0.2.0/codetruth/__init__.py

@@ -0,0 +1,16 @@
+"""CodeTruth — a verification layer that lets AI agents safely delete code.
+
+    from codetruth import scan, check_deletion_safety, track
+"""
+from .api import check_deletion_safety, plan_deletion, scan
+from .core.models import (Action, Edge, EvidenceRecord, RiskLevel, Status,
+                          Symbol)
+from .runtime import track
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "scan", "check_deletion_safety", "plan_deletion", "track",
+    "Status", "RiskLevel", "Action", "Symbol", "Edge", "EvidenceRecord",
+    "__version__",
+]

codetruth-0.2.0/codetruth/api.py

@@ -0,0 +1,102 @@
+"""Programmatic API — what the MCP server and scripts call.
+
+    from codetruth import scan, check_deletion_safety, plan_deletion
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from .core.deletion import build_deletion_plan
+from .core.plugin import get_plugin
+from .core.scanner import ScanResult, scan_repo
+
+
+def scan(repo_path: str | Path, language: str = "python",
+         treat_public_as_api: Optional[bool] = None,
+         runtime_log: Optional[str | Path] = None,
+         use_cache: bool = True,
+         reachability: str = "default") -> ScanResult:
+    """Run all four layers over a repository and return the evidence set.
+
+    treat_public_as_api: True (conservative, the default when neither the
+    caller nor .codetruth.toml says otherwise) caps unreferenced public
+    symbols at `likely_dead` because a library's consumers are invisible.
+    False for application code; None defers to `app_mode` in .codetruth.toml.
+
+    reachability: "default", or "strict" to detect useless clumps — code
+    that is internally connected but never reached from any real entry point
+    (route, CLI command, __main__, test, declared entrypoint). Strict-mode
+    findings surface in the review queue with cluster grouping.
+
+    use_cache=True reuses a persisted result (<repo>/.codetruth/index.json)
+    when no source or config file has changed since the last scan.
+    """
+    return scan_repo(repo_path, language=language,
+                     treat_public_as_api=treat_public_as_api,
+                     runtime_log=runtime_log, use_cache=use_cache,
+                     reachability=reachability)
+
+
+def check_deletion_safety(repo_path: str | Path, symbol: str,
+                          result: Optional[ScanResult] = None,
+                          **scan_kwargs) -> dict:
+    """The agent-facing question: 'may I delete this symbol?'
+
+    Returns the evidence record(s) for the symbol, or candidate matches if
+    the name is ambiguous. The agent should only act on `safe_to_delete`.
+    """
+    if result is None:
+        result = scan(repo_path, **scan_kwargs)
+    matches = result.find(symbol)
+    if not matches:
+        return {
+            "found": False, "symbol": symbol,
+            "message": "Symbol not found in the scanned repository. "
+                       "Do NOT delete based on this response — verify the "
+                       "symbol id (format: 'pkg.module:Qual.name').",
+        }
+    if len(matches) > 1:
+        return {
+            "found": True, "ambiguous": True, "symbol": symbol,
+            "message": f"{len(matches)} symbols match — re-query with an exact id.",
+            "candidates": [m.to_dict() for m in matches[:20]],
+        }
+    record = matches[0]
+    return {"found": True, "ambiguous": False, "record": record.to_dict()}
+
+
+def plan_deletion(repo_path: str | Path, symbol: str,
+                  language: str = "python",
+                  result: Optional[ScanResult] = None,
+                  **scan_kwargs) -> dict:
+    """Advisory plan for removing one symbol: exact span, orphaned imports,
+    __all__ entry. Works for any status — the response carries the verdict so
+    the reader knows whether acting on the plan is advised. CodeTruth never
+    applies the plan.
+    """
+    safety = check_deletion_safety(repo_path, symbol, result=result,
+                                   **scan_kwargs)
+    if not safety.get("found") or safety.get("ambiguous"):
+        return safety
+
+    record = safety["record"]
+    if record.get("deletion_plan"):
+        plan = record["deletion_plan"]
+    else:
+        repo = Path(repo_path).resolve()
+        plugin = get_plugin(language)
+        modules, _warnings = plugin.extract(repo)
+        sym = next((s for m in modules for s in m.symbols
+                    if s.id == record["symbol"]), None)
+        plan = build_deletion_plan(repo, sym) if sym is not None else None
+
+    return {
+        "found": True, "symbol": record["symbol"],
+        "status": record["status"],
+        "recommended_action": record["recommended_action"],
+        "plan": plan,
+        "warning": None if record["status"] == "safe_to_delete" else
+                   f"status is {record['status']} — this plan is informational; "
+                   "review is required before anyone acts on it",
+    }