graphite-code 0.3.0__py3-none-any.whl

graphite/engine_identity.py

@@ -0,0 +1,238 @@
+"""Deterministic, bounded identity for the installed Graphite engine."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+from importlib import metadata
+from pathlib import Path
+from typing import Final
+
+# Bumped to 2 when the grammars joined the identity (#52): a fingerprint computed
+# under schema 1 covered graphite's own files only, so the two are not comparable.
+ENGINE_SCHEMA_VERSION: Final = "2"
+
+# The tree-sitter distributions that actually produce the ASTs. Kept sorted so the
+# record is order-independent, and hyphenated because these are DISTRIBUTION names
+# (what importlib.metadata resolves), not the underscored import names used in
+# `extract.ast`.
+PARSER_DISTRIBUTIONS: Final = (
+    "tree-sitter",
+    "tree-sitter-go",
+    "tree-sitter-javascript",
+    "tree-sitter-python",
+    "tree-sitter-rust",
+    "tree-sitter-typescript",
+)
+MAX_ENGINE_FILES: Final = 512
+MAX_ENGINE_FILE_BYTES: Final = 8 * 1024 * 1024
+MAX_ENGINE_TOTAL_BYTES: Final = 64 * 1024 * 1024
+
+_SOURCE_SUFFIXES = frozenset({".py", ".mjs"})
+_EXCLUDED_DIRECTORIES = frozenset(
+    {"__pycache__", ".cache", ".mypy_cache", ".pytest_cache", ".ruff_cache"}
+)
+_REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+
+
+class EngineIdentityError(RuntimeError):
+    """A fixed, path-free engine inventory or read failure."""
+
+    def __init__(self, code: str) -> None:
+        self.code = code
+        super().__init__(code)
+
+
+def _is_reparse_point(metadata: os.stat_result) -> bool:
+    return bool(getattr(metadata, "st_file_attributes", 0) & _REPARSE_POINT)
+
+
+def _stable_signature(metadata: os.stat_result) -> tuple[int, int, int, int]:
+    return (
+        int(metadata.st_dev),
+        int(metadata.st_ino),
+        int(metadata.st_size),
+        int(metadata.st_mtime_ns),
+    )
+
+
+def _contained_relative(path: Path, root: Path) -> str:
+    try:
+        resolved = path.resolve(strict=True)
+        relative = resolved.relative_to(root)
+    except (OSError, ValueError) as exc:
+        raise EngineIdentityError("engine_root_crossing") from exc
+    normalized = relative.as_posix()
+    if not normalized or normalized.startswith("../") or normalized.startswith("/"):
+        raise EngineIdentityError("engine_root_crossing")
+    return normalized
+
+
+def _collect_engine_files(root: Path, *, max_files: int) -> list[Path]:
+    if isinstance(max_files, bool) or max_files <= 0:
+        raise EngineIdentityError("engine_file_limit")
+    try:
+        root_metadata = root.lstat()
+    except OSError as exc:
+        raise EngineIdentityError("engine_root_invalid") from exc
+    if _is_reparse_point(root_metadata) or stat.S_ISLNK(root_metadata.st_mode):
+        raise EngineIdentityError("engine_root_reparse")
+    if not stat.S_ISDIR(root_metadata.st_mode):
+        raise EngineIdentityError("engine_root_invalid")
+
+    files: list[Path] = []
+    pending = [root]
+    try:
+        while pending:
+            directory = pending.pop()
+            with os.scandir(directory) as entries:
+                for entry in entries:
+                    metadata = entry.stat(follow_symlinks=False)
+                    if entry.is_symlink() or _is_reparse_point(metadata):
+                        raise EngineIdentityError("engine_path_reparse")
+                    entry_path = Path(entry.path)
+                    if stat.S_ISDIR(metadata.st_mode):
+                        if entry.name not in _EXCLUDED_DIRECTORIES:
+                            pending.append(entry_path)
+                        continue
+                    if entry_path.suffix.lower() not in _SOURCE_SUFFIXES:
+                        continue
+                    if not stat.S_ISREG(metadata.st_mode):
+                        raise EngineIdentityError("engine_non_regular")
+                    files.append(entry_path)
+                    if len(files) > max_files:
+                        raise EngineIdentityError("engine_file_limit")
+    except EngineIdentityError:
+        raise
+    except OSError as exc:
+        raise EngineIdentityError("engine_file_unreadable") from exc
+    return files
+
+
+def _read_stable_file(path: Path, root: Path, limit: int) -> bytes:
+    _contained_relative(path, root)
+    try:
+        before = path.lstat()
+    except OSError as exc:
+        raise EngineIdentityError("engine_file_unreadable") from exc
+    if stat.S_ISLNK(before.st_mode) or _is_reparse_point(before):
+        raise EngineIdentityError("engine_path_reparse")
+    if not stat.S_ISREG(before.st_mode):
+        raise EngineIdentityError("engine_non_regular")
+    if before.st_size > limit:
+        raise EngineIdentityError("engine_file_too_large")
+
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
+    try:
+        descriptor = os.open(path, flags)
+        try:
+            opened = os.fstat(descriptor)
+            if _stable_signature(opened) != _stable_signature(before):
+                raise EngineIdentityError("engine_file_changed")
+            chunks: list[bytes] = []
+            remaining = limit + 1
+            while remaining > 0:
+                chunk = os.read(descriptor, min(64 * 1024, remaining))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            after = os.fstat(descriptor)
+        finally:
+            os.close(descriptor)
+    except EngineIdentityError:
+        raise
+    except OSError as exc:
+        raise EngineIdentityError("engine_file_unreadable") from exc
+
+    data = b"".join(chunks)
+    if len(data) > limit:
+        raise EngineIdentityError("engine_file_too_large")
+    if _stable_signature(after) != _stable_signature(opened):
+        raise EngineIdentityError("engine_file_changed")
+    return data
+
+
+def parser_inventory() -> str:
+    """Record the grammar versions that will do the parsing, deterministically.
+
+    An absent grammar is recorded as `absent` rather than omitted: "go was
+    installed" and "go was not" are different engines and must not share a
+    fingerprint. Missing a grammar degrades that one language, so it must not
+    make computing an identity fail.
+    """
+    return ",".join(_parser_record(name) for name in PARSER_DISTRIBUTIONS)
+
+
+def _parser_record(name: str) -> str:
+    try:
+        return f"{name}={metadata.version(name)}"
+    except metadata.PackageNotFoundError:
+        return f"{name}=absent"
+
+
+def engine_identity(
+    cache_version: str,
+    *,
+    package_root: Path | None = None,
+    parsers: str | None = None,
+    version: str | None = None,
+    max_files: int = MAX_ENGINE_FILES,
+    max_file_bytes: int = MAX_ENGINE_FILE_BYTES,
+    max_total_bytes: int = MAX_ENGINE_TOTAL_BYTES,
+) -> dict[str, str]:
+    """Return a public, path-free identity for trusted packaged engine files."""
+    if isinstance(max_file_bytes, bool) or max_file_bytes <= 0:
+        raise EngineIdentityError("engine_file_too_large")
+    if isinstance(max_total_bytes, bool) or max_total_bytes <= 0:
+        raise EngineIdentityError("engine_total_too_large")
+    if not isinstance(cache_version, str) or not cache_version:
+        raise EngineIdentityError("engine_cache_version_invalid")
+
+    if version is None:
+        from . import __version__
+
+        version = __version__
+    if not isinstance(version, str) or not version:
+        raise EngineIdentityError("engine_version_invalid")
+
+    if parsers is None:
+        parsers = parser_inventory()
+    if not isinstance(parsers, str) or not parsers:
+        raise EngineIdentityError("engine_parsers_invalid")
+
+    candidate_root = package_root if package_root is not None else Path(__file__).parent
+    try:
+        root = candidate_root.resolve(strict=True)
+    except OSError as exc:
+        raise EngineIdentityError("engine_root_invalid") from exc
+    paths = _collect_engine_files(root, max_files=max_files)
+
+    header = {
+        "cache_version": cache_version,
+        "parsers": parsers,
+        "schema_version": ENGINE_SCHEMA_VERSION,
+        "version": version,
+    }
+    digest = hashlib.sha256()
+    digest.update(json.dumps(header, sort_keys=True, separators=(",", ":")).encode("utf-8"))
+    total_bytes = 0
+    inventory: list[tuple[str, Path]] = [(_contained_relative(path, root), path) for path in paths]
+    for relative, path in sorted(inventory, key=lambda item: item[0]):
+        try:
+            data = _read_stable_file(path, root, max_file_bytes)
+        except EngineIdentityError:
+            raise
+        except OSError as exc:
+            raise EngineIdentityError("engine_file_unreadable") from exc
+        total_bytes += len(data)
+        if total_bytes > max_total_bytes:
+            raise EngineIdentityError("engine_total_too_large")
+        encoded_name = relative.encode("utf-8")
+        digest.update(len(encoded_name).to_bytes(4, "big"))
+        digest.update(encoded_name)
+        digest.update(len(data).to_bytes(8, "big"))
+        digest.update(data)
+
+    return {**header, "fingerprint": digest.hexdigest()}

graphite/export/__init__.py

@@ -0,0 +1,6 @@
+"""Export subpackage: JSON, HTML, Markdown, MCP."""
+from .json import to_json
+from .html import to_html
+from .md import to_markdown
+
+__all__ = ["to_json", "to_html", "to_markdown"]

graphite/export/html.py

@@ -0,0 +1,244 @@
+"""Self-contained interactive HTML graph viewer."""
+from __future__ import annotations
+
+import html
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from ..io import atomic_write_text
+
+
+_HTML_TEMPLATE = r"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Graphite — {{title}}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; font-family: ui-sans-serif, system-ui, sans-serif; overflow: hidden; background: #0f172a; color: #e2e8f0; }
+  #toolbar { position: fixed; top: 12px; left: 12px; z-index: 10; display: flex; gap: 8px; }
+  #toolbar button, #toolbar label { background: #1e293b; border: 1px solid #334155; color: #e2e8f0; padding: 6px 10px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+  #toolbar input { background: #1e293b; border: 1px solid #334155; color: #e2e8f0; padding: 6px 10px; border-radius: 6px; width: 180px; }
+  #info { position: fixed; top: 12px; right: 12px; z-index: 10; background: #1e293b; border: 1px solid #334155; padding: 12px; border-radius: 8px; max-width: 320px; font-size: 13px; }
+  #info h3 { margin: 0 0 6px; font-size: 14px; }
+  #info p { margin: 4px 0; }
+  canvas { display: block; cursor: grab; }
+  canvas:active { cursor: grabbing; }
+  #tooltip { position: fixed; pointer-events: none; background: #020617; border: 1px solid #334155; padding: 6px 8px; border-radius: 4px; font-size: 12px; z-index: 20; display: none; }
+</style>
+</head>
+<body>
+<div id="toolbar">
+  <input id="search" placeholder="Find node..." />
+  <button id="reset">Reset view</button>
+  <button id="pause">Pause sim</button>
+  <label><input type="checkbox" id="labels" checked /> Labels</label>
+</div>
+<div id="info">
+  <h3>Graphite</h3>
+  <p>{{node_count}} nodes · {{edge_count}} edges · {{cluster_count}} clusters</p>
+  <p id="selection">Hover or click a node.</p>
+</div>
+<div id="tooltip"></div>
+<canvas id="canvas"></canvas>
+<script>
+const DATA = {{data}};
+const nodes = DATA.nodes.map((n, i) => ({
+  id: n.id,
+  label: n.name || n.id,
+  kind: n.kind || 'unknown',
+  cluster: DATA.clusters.findIndex(c => c.members.includes(n.id)),
+  x: Math.random() * 800 - 400,
+  y: Math.random() * 600 - 300,
+  vx: 0, vy: 0,
+  ...n
+}));
+const edges = DATA.edges.map(e => ({ source: e.source, target: e.target, ...e }));
+const clusters = DATA.clusters;
+const palette = ['#f87171','#fb923c','#facc15','#4ade80','#22d3ee','#818cf8','#c084fc','#f472b6'];
+const canvas = document.getElementById('canvas');
+const ctx = canvas.getContext('2d');
+let width, height, transform = {x:0, y:0, k:1}, dragging = null, hovered = null, paused = false, showLabels = true;
+
+function resize() { width = canvas.width = window.innerWidth; height = canvas.height = window.innerHeight; }
+window.addEventListener('resize', resize); resize();
+
+function clusterColor(c) { return palette[c % palette.length] || '#94a3b8'; }
+
+function step() {
+  if (!paused) {
+    // Repulsion
+    for (let i = 0; i < nodes.length; i++) {
+      for (let j = i + 1; j < nodes.length; j++) {
+        const a = nodes[i], b = nodes[j];
+        let dx = a.x - b.x, dy = a.y - b.y;
+        let d = Math.sqrt(dx*dx + dy*dy) || 1;
+        const f = 120 / (d * d);
+        const fx = (dx / d) * f, fy = (dy / d) * f;
+        a.vx += fx; a.vy += fy; b.vx -= fx; b.vy -= fy;
+      }
+    }
+    // Attraction along edges
+    edges.forEach(e => {
+      const a = nodes.find(n => n.id === e.source);
+      const b = nodes.find(n => n.id === e.target);
+      if (!a || !b) return;
+      let dx = b.x - a.x, dy = b.y - a.y;
+      let d = Math.sqrt(dx*dx + dy*dy) || 1;
+      const f = d * 0.0003;
+      const fx = (dx / d) * f, fy = (dy / d) * f;
+      a.vx += fx; a.vy += fy; b.vx -= fx; b.vy -= fy;
+    });
+    // Center gravity + damp
+    nodes.forEach(n => {
+      n.vx -= n.x * 0.00005;
+      n.vy -= n.y * 0.00005;
+      n.vx *= 0.92; n.vy *= 0.92;
+      n.x += n.vx; n.y += n.vy;
+    });
+  }
+  render();
+  requestAnimationFrame(step);
+}
+
+function render() {
+  ctx.fillStyle = '#0f172a'; ctx.fillRect(0, 0, width, height);
+  ctx.save();
+  ctx.translate(transform.x + width/2, transform.y + height/2);
+  ctx.scale(transform.k, transform.k);
+  // Edges
+  ctx.strokeStyle = 'rgba(148,163,184,0.25)'; ctx.lineWidth = 1 / transform.k;
+  edges.forEach(e => {
+    const a = nodes.find(n => n.id === e.source);
+    const b = nodes.find(n => n.id === e.target);
+    if (!a || !b) return;
+    ctx.beginPath(); ctx.moveTo(a.x, a.y); ctx.lineTo(b.x, b.y); ctx.stroke();
+  });
+  // Nodes
+  nodes.forEach(n => {
+    const r = n.kind === 'file' ? 6 : 4;
+    ctx.beginPath(); ctx.arc(n.x, n.y, r, 0, Math.PI * 2);
+    ctx.fillStyle = clusterColor(n.cluster);
+    ctx.fill();
+    if (showLabels && (n.kind === 'file' || hovered === n)) {
+      ctx.fillStyle = '#e2e8f0'; ctx.font = `${12/transform.k}px sans-serif`;
+      ctx.fillText(n.label, n.x + r + 2, n.y + 3);
+    }
+  });
+  ctx.restore();
+}
+
+function worldPos(evt) {
+  return {
+    x: (evt.clientX - transform.x - width/2) / transform.k,
+    y: (evt.clientY - transform.y - height/2) / transform.k
+  };
+}
+
+canvas.addEventListener('mousedown', e => {
+  const p = worldPos(e);
+  hovered = nodes.find(n => Math.hypot(n.x - p.x, n.y - p.y) < 10) || null;
+  dragging = hovered;
+});
+canvas.addEventListener('mousemove', e => {
+  const p = worldPos(e);
+  const near = nodes.find(n => Math.hypot(n.x - p.x, n.y - p.y) < 10) || null;
+  hovered = near;
+  const tt = document.getElementById('tooltip');
+  if (near) {
+    tt.style.display = 'block'; tt.style.left = (e.clientX + 12) + 'px'; tt.style.top = (e.clientY + 12) + 'px';
+    tt.textContent = `${near.label} (${near.kind})`;
+  } else { tt.style.display = 'none'; }
+  if (dragging) { dragging.x = p.x; dragging.y = p.y; dragging.vx = 0; dragging.vy = 0; }
+  updateSelection();
+});
+canvas.addEventListener('mouseup', () => dragging = null);
+canvas.addEventListener('wheel', e => {
+  e.preventDefault();
+  const factor = e.deltaY > 0 ? 0.9 : 1.1;
+  transform.k *= factor;
+  render();
+}, {passive: false});
+
+let panning = false, lastPan = {x:0,y:0};
+canvas.addEventListener('contextmenu', e => { e.preventDefault(); panning = true; lastPan = {x:e.clientX, y:e.clientY}; });
+window.addEventListener('mouseup', () => panning = false);
+window.addEventListener('mousemove', e => {
+  if (!panning) return;
+  transform.x += e.clientX - lastPan.x; transform.y += e.clientY - lastPan.y;
+  lastPan = {x:e.clientX, y:e.clientY}; render();
+});
+
+document.getElementById('reset').onclick = () => { transform = {x:0,y:0,k:1}; };
+document.getElementById('pause').onclick = () => { paused = !paused; };
+document.getElementById('labels').onchange = e => { showLabels = e.target.checked; };
+document.getElementById('search').addEventListener('input', e => {
+  const q = e.target.value.toLowerCase();
+  const match = nodes.find(n => n.label.toLowerCase().includes(q));
+  if (match) { hovered = match; updateSelection(); }
+});
+
+function updateSelection() {
+  const el = document.getElementById('selection');
+  if (!hovered) { el.textContent = 'Hover or click a node.'; return; }
+  const incoming = edges.filter(e => e.target === hovered.id).length;
+  const outgoing = edges.filter(e => e.source === hovered.id).length;
+  const cluster = clusters[hovered.cluster];
+  const label = document.createElement('b');
+  label.textContent = hovered.label;
+  el.replaceChildren(
+    label,
+    document.createTextNode(` (${hovered.kind})`),
+    document.createElement('br'),
+    document.createTextNode(`cluster: ${cluster ? cluster.labels.join(', ') : 'none'}`),
+    document.createElement('br'),
+    document.createTextNode(`in: ${incoming} / out: ${outgoing}`)
+  );
+}
+
+step();
+</script>
+</body>
+</html>
+"""
+
+
+def _json_for_script(value: Any) -> str:
+    return (
+        json.dumps(value, ensure_ascii=False)
+        .replace("&", r"\u0026")
+        .replace("<", r"\u003c")
+        .replace(">", r"\u003e")
+    )
+
+
+def to_html(
+    graph_data: dict[str, Any],
+    clusters: dict[str, Any],
+    analysis: dict[str, Any],
+    manifest: dict[str, Any],
+    output_path: Path,
+) -> None:
+    """Write a self-contained interactive HTML viewer."""
+    bundle = {
+        "nodes": graph_data.get("nodes", []),
+        "edges": graph_data.get("edges", []),
+        "clusters": clusters.get("clusters", []),
+        "analysis": analysis,
+    }
+    substitutions = {
+        "data": _json_for_script(bundle),
+        "title": html.escape(str(manifest.get("root", "codebase"))),
+        "node_count": str(graph_data.get("metadata", {}).get("node_count", 0)),
+        "edge_count": str(graph_data.get("metadata", {}).get("edge_count", 0)),
+        "cluster_count": str(clusters.get("count", 0)),
+    }
+    document = re.sub(
+        r"\{\{(data|title|node_count|edge_count|cluster_count)\}\}",
+        lambda match: substitutions[match.group(1)],
+        _HTML_TEMPLATE,
+    )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(output_path, document)

graphite/export/json.py

@@ -0,0 +1,39 @@
+"""JSON export of the full graph bundle."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..io import atomic_write_json
+
+
+def build_bundle(
+    graph_data: dict[str, Any],
+    clusters: dict[str, Any],
+    analysis: dict[str, Any],
+    manifest: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the public graph JSON bundle used by viewers and tools."""
+    return {
+        "nodes": graph_data.get("nodes", []),
+        "edges": graph_data.get("edges", []),
+        "clusters": clusters.get("clusters", []),
+        "analysis": analysis,
+        "metadata": {
+            "node_count": graph_data.get("metadata", {}).get("node_count", 0),
+            "edge_count": graph_data.get("metadata", {}).get("edge_count", 0),
+            "community_count": clusters.get("count", 0),
+            **{k: v for k, v in manifest.items() if k not in ("files",)},
+        },
+    }
+
+
+def to_json(
+    graph_data: dict[str, Any],
+    clusters: dict[str, Any],
+    analysis: dict[str, Any],
+    manifest: dict[str, Any],
+    output_path: Path,
+) -> None:
+    """Write the bundled graph JSON used by the HTML viewer and external tools."""
+    atomic_write_json(output_path, build_bundle(graph_data, clusters, analysis, manifest), indent=2)

graphite/export/md.py

@@ -0,0 +1,68 @@
+"""Markdown report generation."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..io import atomic_write_text
+
+
+def to_markdown(
+    graph_data: dict[str, Any],
+    clusters: dict[str, Any],
+    analysis: dict[str, Any],
+    manifest: dict[str, Any],
+    output_path: Path,
+) -> None:
+    """Write a human-readable Markdown audit report."""
+    lines: list[str] = []
+    lines.append(f"# Graphite Report: `{manifest.get('root', 'codebase')}`")
+    lines.append("")
+    lines.append("## Summary")
+    lines.append(f"- **Files scanned:** {manifest.get('file_count', 0)}")
+    lines.append(f"- **Total nodes:** {graph_data.get('metadata', {}).get('node_count', 0)}")
+    lines.append(f"- **Total edges:** {graph_data.get('metadata', {}).get('edge_count', 0)}")
+    lines.append(f"- **Communities detected:** {clusters.get('count', 0)}")
+    lines.append("")
+
+    lines.append("## Top Files by Connectivity")
+    for item in analysis.get("top_files_by_links", [])[:10]:
+        lines.append(f"- `{item['name']}` — degree {item['degree']}")
+    lines.append("")
+
+    lines.append("## God Nodes")
+    for item in analysis.get("god_nodes", [])[:10]:
+        lines.append(
+            f"- `{item['name']}` ({item['kind']}) — "
+            f"in {item['in_degree']} / out {item['out_degree']}"
+        )
+    lines.append("")
+
+    lines.append("## Entry Points")
+    for item in analysis.get("entry_points", [])[:10]:
+        lines.append(
+            f"- `{item['name']}` — out {item['out_degree']} / "
+            f"in {item['in_degree']} (ratio {item['ratio']:.1f})"
+        )
+    lines.append("")
+
+    lines.append("## Surprising Connections")
+    for item in analysis.get("surprising_connections", [])[:10]:
+        lines.append(f"- `{item['source']}` -> `{item['target']}` ({item['relation']})")
+    lines.append("")
+
+    lines.append("## Communities")
+    for c in clusters.get("clusters", [])[:20]:
+        labels = ", ".join(c.get("labels", [])) or "mixed"
+        lines.append(f"### Community {c['id']} ({labels})")
+        lines.append(
+            f"- size: {c['size']} (files: {c['file_count']}, "
+            f"functions: {c['function_count']}, classes: {c['class_count']})"
+        )
+        file_members = [m for m in c.get("members", []) if any(chr.isalnum() for chr in m)]
+        suffix = " ..." if len(file_members) > 15 else ""
+        lines.append(f"- members: {', '.join(f'`{m}`' for m in file_members[:15])}{suffix}")
+    lines.append("")
+
+    atomic_write_text(output_path, "\n".join(lines))
+

graphite/extract/__init__.py

@@ -0,0 +1,4 @@
+"""Extraction subpackage: AST + comments + optional LLM."""
+from .ast import extract_file
+
+__all__ = ["extract_file"]