PyPI - codetruth - Versions diffs - 0.2.0__py3-none-any.whl - Mend

codetruth 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

codetruth/__init__.py +16 -0
codetruth/api.py +102 -0
codetruth/cli.py +183 -0
codetruth/core/__init__.py +0 -0
codetruth/core/cache.py +104 -0
codetruth/core/config.py +74 -0
codetruth/core/deletion.py +165 -0
codetruth/core/evidence.py +306 -0
codetruth/core/graph.py +44 -0
codetruth/core/models.py +193 -0
codetruth/core/plugin.py +88 -0
codetruth/core/report.py +107 -0
codetruth/core/scanner.py +228 -0
codetruth/languages/__init__.py +0 -0
codetruth/languages/go/__init__.py +1 -0
codetruth/languages/javascript/__init__.py +8 -0
codetruth/languages/javascript/edges.py +361 -0
codetruth/languages/javascript/extractor.py +402 -0
codetruth/languages/javascript/plugin.py +52 -0
codetruth/languages/javascript/rules.py +201 -0
codetruth/languages/python/__init__.py +0 -0
codetruth/languages/python/edges.py +474 -0
codetruth/languages/python/extractor.py +271 -0
codetruth/languages/python/plugin.py +49 -0
codetruth/languages/python/rules.py +332 -0
codetruth/mcp_server.py +138 -0
codetruth/rules/python/common_dynamic.yaml +70 -0
codetruth/rules/python/django.yaml +57 -0
codetruth/rules/python/fastapi.yaml +38 -0
codetruth/rules/python/orm_web.yaml +50 -0
codetruth/runtime/__init__.py +283 -0
codetruth-0.2.0.dist-info/METADATA +215 -0
codetruth-0.2.0.dist-info/RECORD +37 -0
codetruth-0.2.0.dist-info/WHEEL +5 -0
codetruth-0.2.0.dist-info/entry_points.txt +2 -0
codetruth-0.2.0.dist-info/licenses/LICENSE +21 -0
codetruth-0.2.0.dist-info/top_level.txt +1 -0

codetruth/core/report.py ADDED Viewed

@@ -0,0 +1,107 @@
+"""Standalone HTML report for a scan — a single self-contained file, no
+external assets, so it opens anywhere and can be attached to a PR or CI run."""
+from __future__ import annotations
+import html
+from pathlib import Path
+from typing import TYPE_CHECKING
+from .models import Status
+if TYPE_CHECKING:
+    from .scanner import ScanResult
+_STATUS_META = {
+    Status.SAFE_TO_DELETE: ("safe to delete", "#1a7f37"),
+    Status.LIKELY_DEAD: ("likely dead", "#9a6700"),
+    Status.UNCERTAIN_DYNAMIC_RISK: ("uncertain / dynamic risk", "#bc4c00"),
+    Status.DEFINITELY_USED: ("definitely used", "#57606a"),
+}
+def _esc(x) -> str:
+    return html.escape(str(x))
+def render_html(result: "ScanResult") -> str:
+    s = result.summary()
+    c = s["status_counts"]
+    rows = []
+    for r in result.candidates():
+        label, color = _STATUS_META[r.status]
+        ev_for = "".join(f"<li>{_esc(e)}</li>" for e in r.evidence_for_deletion)
+        ev_against = "".join(f"<li>{_esc(e)}</li>"
+                             for e in r.evidence_against_deletion)
+        cluster = ""
+        if r.cluster:
+            cluster = ("<div class='cluster'>clump: "
+                       + ", ".join(_esc(x) for x in r.cluster) + "</div>")
+        rows.append(f"""
+        <tr data-status="{r.status.value}">
+          <td><span class="pill" style="background:{color}">{label}</span></td>
+          <td class="rank">{r.rank_score:.2f}</td>
+          <td><code>{_esc(r.symbol)}</code><div class="loc">{_esc(r.file)}:{r.line}</div>{cluster}</td>
+          <td class="ev">
+            <ul class="for">{ev_for}</ul>
+            <ul class="against">{ev_against}</ul>
+          </td>
+        </tr>""")
+    return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>CodeTruth report — {_esc(s['repo'])}</title>
+<style>
+ :root {{ color-scheme: light dark; }}
+ body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; padding: 1.5rem;
+        max-width: 1100px; margin-inline: auto; }}
+ h1 {{ font-size: 1.25rem; margin: 0 0 .25rem; }}
+ .sub {{ color: #6e7781; margin-bottom: 1rem; }}
+ .counts {{ display: flex; gap: .5rem; flex-wrap: wrap; margin-bottom: 1rem; }}
+ .count {{ padding: .35rem .7rem; border-radius: 6px; background: #f6f8fa;
+          border: 1px solid #d0d7de; }}
+ .count b {{ font-size: 1.1rem; }}
+ @media (prefers-color-scheme: dark) {{
+   .count {{ background: #161b22; border-color: #30363d; }} }}
+ table {{ border-collapse: collapse; width: 100%; }}
+ th, td {{ text-align: left; padding: .5rem .6rem; vertical-align: top;
+          border-top: 1px solid #d0d7de40; }}
+ th {{ position: sticky; top: 0; background: Canvas; }}
+ .pill {{ color: #fff; padding: .1rem .5rem; border-radius: 999px;
+         font-size: .75rem; white-space: nowrap; }}
+ .rank {{ font-variant-numeric: tabular-nums; text-align: right; }}
+ .loc {{ color: #6e7781; font-size: .8rem; }}
+ .cluster {{ color: #bc4c00; font-size: .78rem; margin-top: .2rem; }}
+ code {{ font: 12px ui-monospace, monospace; }}
+ .ev ul {{ margin: 0; padding-left: 1.1rem; }}
+ .ev .for li {{ color: #1a7f37; }}
+ .ev .against li {{ color: #a04100; }}
+ .note {{ margin-top: 1.5rem; color: #6e7781; font-size: .85rem; }}
+ input {{ margin-bottom: 1rem; padding: .4rem; width: 16rem; }}
+</style></head><body>
+<h1>CodeTruth report</h1>
+<div class="sub">{_esc(s['repo'])} · {s['symbols']} symbols · {s['edges']} edges</div>
+<div class="counts">
+  <div class="count"><b>{c['safe_to_delete']}</b> safe to delete</div>
+  <div class="count"><b>{c['likely_dead']}</b> likely dead</div>
+  <div class="count"><b>{c['uncertain_dynamic_risk']}</b> uncertain</div>
+  <div class="count"><b>{c['definitely_used']}</b> used</div>
+</div>
+<input id="filter" placeholder="filter symbols…" oninput="filt()">
+<table id="t"><thead><tr><th>status</th><th>rank</th><th>symbol</th>
+<th>evidence (for / against deletion)</th></tr></thead>
+<tbody>{''.join(rows)}</tbody></table>
+<p class="note">Advisory only — CodeTruth never deletes code. Act on
+<b>safe to delete</b>; everything else needs human review.</p>
+<script>
+ function filt() {{
+   const q = document.getElementById('filter').value.toLowerCase();
+   for (const tr of document.querySelectorAll('#t tbody tr'))
+     tr.style.display = tr.textContent.toLowerCase().includes(q) ? '' : 'none';
+ }}
+</script>
+</body></html>"""
+def write_html_report(result: "ScanResult", path: str | Path) -> None:
+    Path(path).write_text(render_html(result), encoding="utf-8")

codetruth/core/scanner.py ADDED Viewed

@@ -0,0 +1,228 @@
+"""Orchestrator: repo path in, ScanResult out. Runs all four layers."""
+from __future__ import annotations
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+from . import cache
+from .config import load_config
+from .deletion import build_deletion_plan
+from .evidence import build_records
+from .graph import CodeGraph
+from .models import (Action, EvidenceRecord, Marker, MarkerKind, RiskLevel,
+                     Status, Symbol)
+from .plugin import RuleContext, get_plugin
+@dataclass
+class ScanResult:
+    repo_path: str
+    language: str
+    records: list[EvidenceRecord]
+    symbol_count: int
+    edge_count: int
+    warnings: list[str] = field(default_factory=list)
+    def summary(self) -> dict:
+        counts = {s.value: 0 for s in Status}
+        for r in self.records:
+            counts[r.status.value] += 1
+        return {
+            "repo": self.repo_path, "language": self.language,
+            "symbols": self.symbol_count, "edges": self.edge_count,
+            "status_counts": counts, "warnings": len(self.warnings),
+        }
+    def candidates(self) -> list[EvidenceRecord]:
+        """Everything not proven used — the review queue. Ordered by status
+        tier, then by rank_score (strongest deletion targets first within a
+        tier), so the top of the list is where an agent should look first."""
+        order = {Status.SAFE_TO_DELETE: 0, Status.LIKELY_DEAD: 1,
+                 Status.UNCERTAIN_DYNAMIC_RISK: 2}
+        return sorted((r for r in self.records
+                       if r.status is not Status.DEFINITELY_USED),
+                      key=lambda r: (order[r.status], -r.rank_score,
+                                     r.file, r.line))
+    def find(self, query: str) -> list[EvidenceRecord]:
+        """Locate records by exact id, dotted path, or trailing name match."""
+        exact = [r for r in self.records if r.symbol == query]
+        if exact:
+            return exact
+        norm = query.replace(":", ".")
+        dotted = [r for r in self.records
+                  if r.symbol.replace(":", ".") == norm]
+        if dotted:
+            return dotted
+        return [r for r in self.records
+                if r.symbol.replace(":", ".").endswith("." + norm)
+                or r.name == query]
+    def to_dict(self, include_used: bool = True) -> dict:
+        records = self.records if include_used else self.candidates()
+        return {
+            "summary": self.summary(),
+            "records": [r.to_dict() for r in records],
+            "warnings": self.warnings,
+        }
+    def save(self, path: str | Path) -> None:
+        Path(path).write_text(json.dumps(self.to_dict(), indent=2),
+                              encoding="utf-8")
+def _verify_safe_candidates(repo: Path, records: list[EvidenceRecord],
+                            modules: list, config_files: list[Path],
+                            symbols: list[Symbol]) -> None:
+    """Independent textual audit of every safe_to_delete verdict.
+    The graph proves no *structural* usage path. This pass additionally
+    requires the symbol's name to appear nowhere else in the repository's
+    text — source, comments, docstrings, or config. Any stray occurrence is
+    a possible usage path, so the verdict is demoted to
+    uncertain_dynamic_risk. This makes the core guarantee mechanical:
+    safe_to_delete is only ever emitted when no usage path can be found.
+    """
+    candidates = [r for r in records if r.status is Status.SAFE_TO_DELETE]
+    if not candidates:
+        return
+    symbols_by_id = {s.id: s for s in symbols}
+    texts: dict[str, str] = {}
+    for m in modules:
+        try:
+            texts[m.rel_path] = Path(m.abs_path).read_text(
+                encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+    for path in config_files:
+        try:
+            texts[path.relative_to(repo).as_posix()] = path.read_text(
+                encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+    for rec in candidates:
+        pattern = re.compile(rf"\b{re.escape(rec.name)}\b")
+        end_line = symbols_by_id[rec.symbol].end_line
+        hit = _find_external_occurrence(rec, end_line, pattern, texts)
+        if hit is None:
+            rec.evidence_for_deletion.append(
+                "Verified: symbol name occurs nowhere else in the "
+                "repository's text (source, comments, or config)")
+            continue
+        rec.status = Status.UNCERTAIN_DYNAMIC_RISK
+        rec.risk_level = RiskLevel.HIGH
+        rec.recommended_action = Action.REVIEW_REQUIRED
+        # A bare text mention (comment/docstring/config) is weak evidence of
+        # use, so this ranks near the top of the uncertain tier — but it must
+        # no longer carry its former safe-tier score.
+        rec.rank_score = 0.40
+        rec.evidence_against_deletion.append(
+            f"Text occurrence outside the definition at {hit} — possible "
+            "usage path the graph cannot classify")
+def _find_external_occurrence(rec: EvidenceRecord, end_line: int,
+                              pattern: re.Pattern,
+                              texts: dict[str, str]) -> Optional[str]:
+    """First occurrence of the symbol's name outside its own definition
+    span, as 'file:line' — or None if the name appears nowhere else.
+    The span in the home file (decorators through end of block) is 'self';
+    anything beyond it, in any file, counts as a possible usage path."""
+    for rel, text in texts.items():
+        for lineno, line in enumerate(text.splitlines(), 1):
+            if not pattern.search(line):
+                continue
+            if rel == rec.file and rec.line <= lineno <= end_line:
+                continue
+            return f"{rel}:{lineno}"
+    return None
+def scan_repo(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:
+    repo = Path(repo_path).resolve()
+    if not repo.is_dir():
+        raise FileNotFoundError(f"Not a directory: {repo}")
+    if reachability not in ("default", "strict"):
+        raise ValueError("reachability must be 'default' or 'strict'")
+    plugin = get_plugin(language)
+    repo_cfg = load_config(repo)
+    if treat_public_as_api is None:
+        # .codetruth.toml app_mode=true means "application code":
+        # public symbols are internal.
+        treat_public_as_api = not repo_cfg.app_mode if repo_cfg.app_mode is not None \
+            else True
+    ignores = tuple(repo_cfg.ignore_paths)
+    # Persistent cache: a scan is a pure function of the source+config bytes
+    # (the .codetruth.toml is fingerprinted too). Runtime logs are not part
+    # of the fingerprint, so bypass the cache when one is supplied.
+    fp = None
+    if use_cache and not runtime_log and hasattr(plugin, "source_files"):
+        fp = cache.fingerprint(repo, plugin.source_files(repo, ignores))
+        cached = cache.load(repo, language, treat_public_as_api, fp,
+                            reachability)
+        if cached is not None:
+            return cached
+    # Layer 1 — symbols
+    modules, warnings = plugin.extract(repo, ignores)
+    index = plugin.build_index(modules)
+    symbols: list[Symbol] = plugin.symbols(modules)
+    # Layer 2 — relationship graph
+    graph = CodeGraph()
+    markers: list[Marker] = []
+    plugin.build_edges(repo, modules, index, graph, markers)
+    # Layer 3 — semantic safety rules
+    config_files = plugin.config_files(repo, ignores) \
+        if hasattr(plugin, "config_files") else []
+    ctx = RuleContext(repo_path=repo, modules=modules, index=index,
+                      graph=graph, markers=markers, config_files=config_files)
+    for rule in plugin.rules():
+        rule.apply(ctx)
+    # Phase 6 — runtime evidence (strongest tier when present)
+    if runtime_log:
+        from ..runtime import load_runtime_markers
+        markers.extend(load_runtime_markers(runtime_log, {s.id for s in symbols}))
+    # Layer 4 — evidence + decision
+    records = build_records(symbols, graph, markers,
+                            treat_public_as_api=treat_public_as_api,
+                            reachability=reachability)
+    # Final backstop: never emit safe_to_delete when ANY usage path exists —
+    # including ones the AST can't see (comments, docstrings, templates).
+    _verify_safe_candidates(repo, records, modules, config_files, symbols)
+    # Attach advisory deletion plans to the records that earned one.
+    symbols_by_id = {s.id: s for s in symbols}
+    for rec in records:
+        if rec.status is Status.SAFE_TO_DELETE:
+            try:
+                rec.deletion_plan = build_deletion_plan(repo,
+                                                        symbols_by_id[rec.symbol])
+            except Exception:  # a plan is advice; never fail the scan for it
+                rec.deletion_plan = None
+    result = ScanResult(
+        repo_path=str(repo), language=language, records=records,
+        symbol_count=len(symbols), edge_count=len(graph.edges),
+        warnings=warnings,
+    )
+    if fp is not None:
+        cache.save(repo, result, language, treat_public_as_api, fp,
+                   reachability)
+    return result

codetruth/languages/__init__.py ADDED Viewed

File without changes

codetruth/languages/go/__init__.py ADDED Viewed

	@@ -0,0 +1 @@
1	+ """Go plugin — v2+ stub. See PLAN.md §7."""

codetruth/languages/javascript/__init__.py ADDED Viewed

@@ -0,0 +1,8 @@
+"""JavaScript/TypeScript plugin (beta).
+Extraction and edge building via tree-sitter; Layer 3 covers package.json
+entry points, constructors, eval/new Function poisoning, string references,
+and declared entrypoints. Install the parser dependency with:
+    pip install codetruth[javascript]
+"""