codetruth 0.2.0__py3-none-any.whl

codetruth/mcp_server.py

@@ -0,0 +1,138 @@
+"""The headline interface: CodeTruth as an MCP server.
+
+Agent workflow:
+  1. Agent identifies a symbol it wants to delete.
+  2. Agent calls check_deletion_safety(repo_path, symbol).
+  3. CodeTruth returns the evidence record.
+  4. Agent only deletes on status == "safe_to_delete"; anything else routes
+     to human review or is left alone.
+
+Register with Claude Code:
+  claude mcp add codetruth -- codetruth mcp
+"""
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from .api import check_deletion_safety as _check
+from .api import plan_deletion as _plan
+from .api import scan as _scan
+from .core.scanner import ScanResult
+
+mcp = FastMCP(
+    "codetruth",
+    instructions=(
+        "Deletion-safety verification for code symbols. Before deleting any "
+        "symbol, call check_deletion_safety and only proceed when status is "
+        "'safe_to_delete'. 'likely_dead' and 'uncertain_dynamic_risk' require "
+        "human review. Detection is deterministic — do not override it with "
+        "your own judgment about whether code looks unused."),
+)
+
+_CACHE: dict[tuple, tuple[float, ScanResult]] = {}
+_CACHE_TTL_SECONDS = 300.0
+
+
+def _cached_scan(repo_path: str, treat_public_as_api: Optional[bool],
+                 force_rescan: bool = False,
+                 reachability: str = "default",
+                 language: str = "python") -> ScanResult:
+    key = (repo_path, treat_public_as_api, reachability, language)
+    now = time.time()
+    hit = _CACHE.get(key)
+    if hit and not force_rescan and now - hit[0] < _CACHE_TTL_SECONDS:
+        return hit[1]
+    # force_rescan also busts the persistent on-disk cache, not just the
+    # in-memory TTL cache.
+    result = _scan(repo_path, language=language,
+                   treat_public_as_api=treat_public_as_api,
+                   use_cache=not force_rescan, reachability=reachability)
+    _CACHE[key] = (now, result)
+    return result
+
+
+@mcp.tool()
+def scan(repo_path: str, status: str = "", limit: int = 100,
+         treat_public_as_api: Optional[bool] = None,
+         force_rescan: bool = False, strict: bool = False,
+         language: str = "python") -> dict:
+    """Scan a repository and return deletion-safety evidence records.
+
+    Args:
+        repo_path: absolute path to the repository root.
+        status: optional filter — one of safe_to_delete, likely_dead,
+            uncertain_dynamic_risk, definitely_used. Empty = all candidates
+            (everything not proven used).
+        limit: max records returned.
+        treat_public_as_api: True for libraries (conservative). False only
+            for application repos nothing external imports. None (default)
+            defers to app_mode in the repo's .codetruth.toml, else True.
+        force_rescan: bypass the 5-minute scan cache.
+        strict: strict reachability — flag code that is internally connected
+            but not reachable from any real entry point (route, CLI command,
+            __main__, test, declared entrypoint). Orphaned clumps come back
+            grouped via each record's 'cluster' field.
+        language: 'python' (default) or 'javascript'/'typescript' (beta,
+            requires the codetruth[javascript] extra).
+    """
+    result = _cached_scan(repo_path, treat_public_as_api, force_rescan,
+                          "strict" if strict else "default", language)
+    if status:
+        records = [r for r in result.records if r.status.value == status]
+    else:
+        records = result.candidates()
+    return {
+        "summary": result.summary(),
+        "records": [r.to_dict() for r in records[:limit]],
+        "truncated": len(records) > limit,
+        "note": "Only 'safe_to_delete' may be deleted without human review.",
+    }
+
+
+@mcp.tool()
+def check_deletion_safety(repo_path: str, symbol: str,
+                          treat_public_as_api: Optional[bool] = None,
+                          force_rescan: bool = False) -> dict:
+    """Check whether one symbol is safe to delete. Call this BEFORE deleting.
+
+    Args:
+        repo_path: absolute path to the repository root.
+        symbol: symbol id ('pkg.module:Qual.name'), dotted path, or bare name.
+        treat_public_as_api: True for libraries (default, conservative).
+        force_rescan: bypass the 5-minute scan cache.
+
+    Returns the evidence record: status, risk_level, recommended_action,
+    and the evidence for/against deletion. Only delete on 'safe_to_delete'.
+    """
+    result = _cached_scan(repo_path, treat_public_as_api, force_rescan)
+    return _check(repo_path, symbol, result=result)
+
+
+@mcp.tool()
+def plan_deletion(repo_path: str, symbol: str,
+                  treat_public_as_api: Optional[bool] = None,
+                  force_rescan: bool = False) -> dict:
+    """Advisory plan describing what removing a symbol would involve: the
+    exact source span, imports that would become orphaned, and any __all__
+    entry. CodeTruth NEVER applies the plan — it is information for the
+    human/agent who decides. Only act when status is 'safe_to_delete'.
+
+    Args:
+        repo_path: absolute path to the repository root.
+        symbol: symbol id ('pkg.module:Qual.name'), dotted path, or bare name.
+        treat_public_as_api: True for libraries (default, conservative).
+        force_rescan: bypass the scan caches.
+    """
+    result = _cached_scan(repo_path, treat_public_as_api, force_rescan)
+    return _plan(repo_path, symbol, result=result)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

codetruth/rules/python/common_dynamic.yaml

@@ -0,0 +1,70 @@
+language: python
+framework: common (celery / click / pytest / registries / event systems)
+rules:
+  - id: celery-task-decorator
+    type: decorator
+    patterns:
+      - "*.task"
+      - "shared_task"
+      - "*.shared_task"
+      - "*.periodic_task"
+    effect: entrypoint
+    reason: "Celery task — invoked by name through the task queue"
+
+  - id: cli-command-decorator
+    type: decorator
+    patterns:
+      - "*.command"
+      - "*.group"
+      - "click.command"
+      - "click.group"
+      - "*.callback"
+    effect: entrypoint
+    reason: "CLI command decorator — invoked by the CLI framework at runtime"
+
+  - id: pytest-fixture-decorator
+    type: decorator
+    patterns:
+      - "fixture"
+      - "pytest.fixture"
+      - "*.fixture"
+    effect: entrypoint
+    reason: "pytest fixture — injected by name into tests"
+
+  - id: registry-decorator
+    type: decorator
+    patterns:
+      - "register"
+      - "*.register"
+      - "*.register_*"
+    effect: entrypoint
+    reason: "registry decorator — symbol is registered and looked up dynamically"
+
+  - id: event-listener-decorator
+    type: decorator
+    patterns:
+      - "*.listens_for"
+      - "*.event"
+      - "*.on"
+      - "*.subscribe"
+      - "*.subscriber"
+      - "*.hookimpl"
+      - "atexit.register"
+    effect: entrypoint
+    reason: "event/listener decorator — invoked by an event system"
+
+  - id: property-like-decorator
+    type: decorator
+    patterns:
+      - "property"
+      - "cached_property"
+      - "functools.cached_property"
+      - "*.setter"
+      - "*.getter"
+      - "*.deleter"
+      - "*.validator"
+      - "*.field_validator"
+      - "*.model_validator"
+      - "*.root_validator"
+    effect: entrypoint
+    reason: "property/validator descriptor — invoked implicitly via attribute access or model validation"

codetruth/rules/python/django.yaml

@@ -0,0 +1,57 @@
+language: python
+framework: django
+rules:
+  - id: django-signal-receiver
+    type: decorator
+    patterns:
+      - "receiver"
+      - "*.receiver"
+    effect: entrypoint
+    reason: "Django signal receiver — connected and invoked via the signal system"
+
+  - id: django-admin-register
+    type: decorator
+    patterns:
+      - "admin.register"
+      - "*.admin.register"
+      - "register.filter"
+      - "register.simple_tag"
+      - "register.inclusion_tag"
+      - "register.tag"
+    effect: entrypoint
+    reason: "Django registration decorator — registered with a framework registry"
+
+  - id: django-settings-constants
+    type: name
+    name_regex: "^[A-Z][A-Z0-9_]*$"
+    path_glob: "*settings*.py"
+    symbol_type: variable
+    reason: "Django settings constant — consumed by the framework by name"
+
+  - id: django-management-command
+    type: name
+    name_regex: "^Command$"
+    path_glob: "*management/commands/*.py"
+    symbol_type: class
+    reason: "Django management command — discovered and invoked by manage.py"
+
+  - id: django-migration
+    type: name
+    name_regex: "^Migration$"
+    path_glob: "*migrations/*.py"
+    symbol_type: class
+    reason: "Django migration — discovered and applied by the migration framework"
+
+  - id: django-urlpatterns
+    type: name
+    name_regex: "^(urlpatterns|handler404|handler500|handler403|handler400)$"
+    path_glob: "*urls.py"
+    symbol_type: variable
+    reason: "Django URL configuration — consumed by the framework by name"
+
+  - id: wsgi-asgi-application
+    type: name
+    name_regex: "^(application|app)$"
+    path_glob: "*sgi.py"
+    symbol_type: variable
+    reason: "WSGI/ASGI application object — loaded by name by the app server"

codetruth/rules/python/fastapi.yaml

@@ -0,0 +1,38 @@
+language: python
+framework: fastapi / flask / starlette
+rules:
+  - id: http-route-decorator
+    type: decorator
+    patterns:
+      - "*.get"
+      - "*.post"
+      - "*.put"
+      - "*.delete"
+      - "*.patch"
+      - "*.options"
+      - "*.head"
+      - "*.trace"
+      - "*.route"
+      - "*.api_route"
+      - "*.websocket"
+      - "*.websocket_route"
+    effect: entrypoint
+    reason: "HTTP route decorator — handler is invoked by the web framework"
+
+  - id: web-lifecycle-decorator
+    type: decorator
+    patterns:
+      - "*.middleware"
+      - "*.exception_handler"
+      - "*.on_event"
+      - "*.errorhandler"
+      - "*.before_request"
+      - "*.after_request"
+      - "*.before_first_request"
+      - "*.teardown_request"
+      - "*.teardown_appcontext"
+      - "*.context_processor"
+      - "*.template_filter"
+      - "*.template_global"
+    effect: entrypoint
+    reason: "web framework lifecycle/handler decorator — invoked by the framework"

codetruth/rules/python/orm_web.yaml

@@ -0,0 +1,50 @@
+language: python
+framework: sqlalchemy / starlette / typer / setuptools
+rules:
+  - id: sqlalchemy-event-listener
+    type: decorator
+    patterns:
+      - "*.listens_for"
+      - "event.listens_for"
+      - "*.validates"
+      - "validates"
+    effect: entrypoint
+    reason: "SQLAlchemy event/validator hook — invoked by the ORM, not called directly"
+
+  - id: sqlalchemy-declarative-hook
+    type: decorator
+    patterns:
+      - "declared_attr"
+      - "*.declared_attr"
+      - "hybrid_property"
+      - "*.hybrid_property"
+      - "hybrid_method"
+      - "*.expression"
+      - "*.inplace"
+    effect: entrypoint
+    reason: "SQLAlchemy declarative/hybrid attribute — resolved by the ORM at mapping time"
+
+  - id: typer-command
+    type: decorator
+    patterns:
+      - "*.command"
+      - "*.callback"
+    effect: entrypoint
+    reason: "Typer command/callback — invoked by the CLI framework"
+
+  - id: starlette-route-decorator
+    type: decorator
+    patterns:
+      - "*.route"
+      - "*.websocket_route"
+      - "*.on_event"
+      - "*.add_event_handler"
+    effect: entrypoint
+    reason: "Starlette route/lifecycle handler — invoked by the ASGI framework"
+
+  - id: setuptools-entrypoint-name
+    type: name
+    name_regex: "^main$"
+    path_glob: "*/__main__.py"
+    symbol_type: function
+    reason: "package __main__ entry point — run via `python -m package`"

codetruth/runtime/__init__.py

@@ -0,0 +1,283 @@
+"""Phase 6 — runtime usage evidence.
+
+`@codetruth.track` records real invocations of a function in a running app.
+"Zero calls observed over N days" is the strongest evidence for deletion —
+and the only answer to cross-service usage that static analysis can't see.
+
+Production-hardened:
+- **Multiprocess-safe**: each process appends to its own file
+  (`runtime-<pid>.jsonl` next to the configured path); readers merge every
+  sibling, so concurrent workers never contend or corrupt a shared log.
+- **Interval flushing**: a daemon thread flushes counts every
+  $CODETRUTH_FLUSH_INTERVAL seconds (default 60) — long-running servers
+  don't have to exit cleanly for evidence to land.
+- **Auto-instrumentation**: `instrument_package("pkg")` wraps every function
+  and method of a package (already-imported modules immediately, future
+  imports via an import hook) — no source edits needed.
+
+Log location: $CODETRUTH_RUNTIME_LOG (default .codetruth/runtime.jsonl in
+the CWD); the per-process suffix is added automatically.
+Entries:
+  {"event": "register", "symbol": "pkg.mod:func", "ts": 1710000000.0}
+  {"event": "calls", "symbol": "pkg.mod:func", "count": 17, "ts": ...}
+"""
+from __future__ import annotations
+
+import atexit
+import functools
+import importlib.util
+import json
+import os
+import sys
+import threading
+import time
+import types
+from collections import Counter
+from pathlib import Path
+
+from ..core.models import Marker, MarkerKind
+
+_lock = threading.Lock()
+_counts: Counter = Counter()
+_registered: set[str] = set()
+_flusher_installed = False
+
+
+def _base_log_path() -> Path:
+    return Path(os.environ.get("CODETRUTH_RUNTIME_LOG",
+                               ".codetruth/runtime.jsonl"))
+
+
+def _log_path() -> Path:
+    """Per-process log file: '<stem>-<pid><suffix>' beside the base path."""
+    base = _base_log_path()
+    return base.with_name(f"{base.stem}-{os.getpid()}{base.suffix}")
+
+
+def _append(entry: dict) -> None:
+    path = _log_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass  # tracing must never take the application down
+
+
+def _flush() -> None:
+    with _lock:
+        counts = dict(_counts)
+        _counts.clear()
+    if not counts:
+        return
+    ts = time.time()
+    for symbol, count in counts.items():
+        _append({"event": "calls", "symbol": symbol, "count": count, "ts": ts})
+
+
+def _flush_loop(interval: float) -> None:
+    while True:
+        time.sleep(interval)
+        _flush()
+
+
+def _install_flusher() -> None:
+    global _flusher_installed
+    if _flusher_installed:
+        return
+    _flusher_installed = True
+    atexit.register(_flush)
+    interval = float(os.environ.get("CODETRUTH_FLUSH_INTERVAL", "60"))
+    if interval > 0:
+        threading.Thread(target=_flush_loop, args=(interval,),
+                         daemon=True, name="codetruth-flush").start()
+
+
+def track(fn=None, *, name: str | None = None):
+    """Decorator: register the symbol at import, count real invocations.
+
+    Usage:  @codetruth.track          or   @codetruth.track(name="pkg.mod:func")
+    """
+    def decorate(func):
+        if getattr(func, "_codetruth_tracked", False):
+            return func
+        symbol = name or f"{func.__module__}:{func.__qualname__}"
+        with _lock:
+            if symbol not in _registered:
+                _registered.add(symbol)
+                _append({"event": "register", "symbol": symbol,
+                         "ts": time.time()})
+        _install_flusher()
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            with _lock:
+                _counts[symbol] += 1
+                total = sum(_counts.values())
+            if total >= 1000:  # bound memory between flushes
+                _flush()
+            return func(*args, **kwargs)
+
+        wrapper._codetruth_tracked = True
+        return wrapper
+
+    return decorate(fn) if fn is not None else decorate
+
+
+# --- auto-instrumentation ----------------------------------------------------
+
+def _instrument_module(mod: types.ModuleType) -> int:
+    """Wrap every function and public method defined in this module."""
+    wrapped = 0
+    for attr, obj in list(vars(mod).items()):
+        if isinstance(obj, types.FunctionType) \
+                and obj.__module__ == mod.__name__ \
+                and not getattr(obj, "_codetruth_tracked", False):
+            setattr(mod, attr, track(obj))
+            wrapped += 1
+        elif isinstance(obj, type) and obj.__module__ == mod.__name__:
+            for mname, meth in list(vars(obj).items()):
+                if isinstance(meth, types.FunctionType) \
+                        and not mname.startswith("__") \
+                        and not getattr(meth, "_codetruth_tracked", False):
+                    setattr(obj, mname, track(meth))
+                    wrapped += 1
+    return wrapped
+
+
+class _AutoTrackLoader:
+    def __init__(self, loader):
+        self._loader = loader
+
+    def __getattr__(self, item):
+        return getattr(self._loader, item)
+
+    def create_module(self, spec):
+        create = getattr(self._loader, "create_module", None)
+        return create(spec) if create else None
+
+    def exec_module(self, module):
+        self._loader.exec_module(module)
+        _instrument_module(module)
+
+
+class _AutoTrackFinder:
+    """Meta-path finder that instruments configured packages on import."""
+
+    def __init__(self):
+        self.packages: set[str] = set()
+        self._resolving = threading.local()
+
+    def _matches(self, fullname: str) -> bool:
+        return any(fullname == p or fullname.startswith(p + ".")
+                   for p in self.packages)
+
+    def find_spec(self, fullname, path=None, target=None):
+        if getattr(self._resolving, "active", False) or not self._matches(fullname):
+            return None
+        self._resolving.active = True
+        try:
+            spec = importlib.util.find_spec(fullname)
+        except (ImportError, ValueError):
+            return None
+        finally:
+            self._resolving.active = False
+        if spec and spec.loader:
+            spec.loader = _AutoTrackLoader(spec.loader)
+        return spec
+
+
+_FINDER = _AutoTrackFinder()
+
+
+def instrument_package(package_name: str) -> int:
+    """Auto-track every function/method of a package without source edits.
+
+    Instruments modules already imported and installs an import hook for the
+    rest. Returns the number of callables wrapped so far.
+    """
+    if _FINDER not in sys.meta_path:
+        sys.meta_path.insert(0, _FINDER)
+    _FINDER.packages.add(package_name)
+    wrapped = 0
+    for mod_name, mod in list(sys.modules.items()):
+        if mod is not None and (mod_name == package_name
+                                or mod_name.startswith(package_name + ".")):
+            wrapped += _instrument_module(mod)
+    _install_flusher()
+    return wrapped
+
+
+def autotrack() -> int:
+    """Instrument every package named in $CODETRUTH_AUTOTRACK (comma-sep)."""
+    wrapped = 0
+    for pkg in os.environ.get("CODETRUTH_AUTOTRACK", "").split(","):
+        if pkg.strip():
+            wrapped += instrument_package(pkg.strip())
+    return wrapped
+
+
+# --- reading logs back -------------------------------------------------------
+
+def _log_files(path: str | Path) -> list[Path]:
+    """The given file plus every per-process sibling ('<stem>-*<suffix>')."""
+    p = Path(path)
+    files = [p] if p.is_file() else []
+    if p.parent.is_dir():
+        files += sorted(f for f in p.parent.glob(f"{p.stem}-*{p.suffix}")
+                        if f.is_file())
+    return files
+
+
+def load_runtime_log(path: str | Path) -> dict[str, dict]:
+    """Aggregate (merging per-process files): symbol -> {calls,
+    registered_ts, last_ts}."""
+    out: dict[str, dict] = {}
+    for file in _log_files(path):
+        try:
+            text = file.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            sym = entry.get("symbol")
+            if not sym:
+                continue
+            rec = out.setdefault(sym, {"calls": 0, "registered_ts": None,
+                                       "last_ts": None})
+            if entry.get("event") == "register":
+                ts = entry.get("ts")
+                if rec["registered_ts"] is None or (ts and ts < rec["registered_ts"]):
+                    rec["registered_ts"] = ts
+            elif entry.get("event") == "calls":
+                rec["calls"] += int(entry.get("count", 0))
+                rec["last_ts"] = entry.get("ts") or rec["last_ts"]
+    return out
+
+
+def load_runtime_markers(path: str | Path,
+                         known_symbols: set[str]) -> list[Marker]:
+    """Convert runtime logs into evidence markers for the classifier."""
+    markers: list[Marker] = []
+    now = time.time()
+    for symbol, rec in load_runtime_log(path).items():
+        if symbol not in known_symbols:
+            continue
+        if rec["calls"] > 0:
+            markers.append(Marker(
+                symbol, MarkerKind.RUNTIME_USED,
+                f"observed {rec['calls']} runtime call(s) in production "
+                "tracing — definitely used", rule="runtime-tracking"))
+        elif rec["registered_ts"]:
+            days = max(0.0, (now - rec["registered_ts"]) / 86400)
+            markers.append(Marker(
+                symbol, MarkerKind.RUNTIME_ZERO,
+                f"0 runtime calls observed over {days:.1f} day(s) of "
+                "production tracing", rule="runtime-tracking"))
+    return markers