graphite-code 0.3.0__py3-none-any.whl

graphite/usage_ledger.py

@@ -0,0 +1,156 @@
+"""Machine-local usage ledger backing the savings display.
+
+Everything here is best-effort by contract: recording, toggling, and cursor
+IO must never break the command or hook that calls them, so every public
+function swallows its own errors. The ledger lives under ``.graphite/local/``,
+which the standard gitignore lines already ignore (``**/.graphite/``).
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+from .io import atomic_write_text
+
+MAX_LEDGER_BYTES = 5 * 1024 * 1024
+MAX_FILES_PER_ENTRY = 100
+_FILE_KEYS = frozenset({"source_file", "file", "path"})
+_FILE_LIST_KEYS = frozenset({"impacted_files", "likely_tests", "files"})
+
+
+def local_dir(root: Path) -> Path:
+    return root / ".graphite" / "local"
+
+
+def ledger_path(root: Path) -> Path:
+    return local_dir(root) / "usage.jsonl"
+
+
+def _settings_path(root: Path) -> Path:
+    return local_dir(root) / "settings.json"
+
+
+def _cursor_path(root: Path) -> Path:
+    return local_dir(root) / "stop-cursor.json"
+
+
+def rotated_ledger_path(root: Path) -> Path:
+    path = ledger_path(root)
+    return path.parent / (path.name + ".1")
+
+
+def collect_answer_files(result: Any, root: Path, cap: int = MAX_FILES_PER_ENTRY) -> list[dict[str, Any]]:
+    """File paths named by an answer, with on-disk sizes; best-effort, capped."""
+    seen: dict[str, None] = {}
+
+    def _walk(value: Any) -> None:
+        if len(seen) >= cap:
+            return
+        if isinstance(value, dict):
+            for key, item in value.items():
+                if key in _FILE_KEYS and isinstance(item, str) and item:
+                    seen.setdefault(item)
+                elif key in _FILE_LIST_KEYS and isinstance(item, list):
+                    for path in item:
+                        if isinstance(path, str) and path:
+                            seen.setdefault(path)
+                        if len(seen) >= cap:
+                            return
+                else:
+                    _walk(item)
+        elif isinstance(value, list):
+            for item in value:
+                _walk(item)
+
+    _walk(result)
+    files: list[dict[str, Any]] = []
+    for path in list(seen)[:cap]:
+        size = 0
+        try:
+            candidate = Path(path)
+            if not candidate.is_absolute():
+                candidate = root / candidate
+            size = candidate.stat().st_size
+        except OSError:
+            size = 0
+        files.append({"path": path, "bytes": size})
+    return files
+
+
+def record_usage(root: Path, *, cmd: str, wall_ms: int, result: Any) -> None:
+    """Append one usage record; rotate at the byte cap; never raise."""
+    try:
+        try:
+            output_bytes = len(json.dumps(result, ensure_ascii=False))
+        except (TypeError, ValueError):
+            output_bytes = 0
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "cmd": cmd,
+            "wall_ms": int(wall_ms),
+            "output_bytes": output_bytes,
+            "files": collect_answer_files(result, root),
+        }
+        path = ledger_path(root)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists() and path.stat().st_size > MAX_LEDGER_BYTES:
+            os.replace(path, rotated_ledger_path(root))
+        with open(path, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except Exception:
+        return
+
+
+def iter_entries(root: Path) -> Iterator[dict[str, Any]]:
+    """All entries, rotated generation first; corrupt lines skipped; never raises."""
+    try:
+        current = ledger_path(root)
+        for path in (rotated_ledger_path(root), current):
+            if not path.exists():
+                continue
+            for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if isinstance(entry, dict):
+                    yield entry
+    except Exception:
+        return
+
+
+def _read_local_json(path: Path) -> dict[str, Any]:
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def savings_display_enabled(root: Path) -> bool:
+    value = _read_local_json(_settings_path(root)).get("savings_display")
+    return True if not isinstance(value, bool) else value
+
+
+def set_savings_display(root: Path, enabled: bool) -> dict[str, Any]:
+    settings = _read_local_json(_settings_path(root))
+    settings["savings_display"] = bool(enabled)
+    try:
+        atomic_write_text(_settings_path(root), json.dumps(settings, ensure_ascii=False, indent=2) + "\n")
+    except Exception:
+        pass
+    return settings
+
+
+def read_cursor(root: Path) -> dict[str, Any]:
+    return _read_local_json(_cursor_path(root))
+
+
+def write_cursor(root: Path, cursor: dict[str, Any]) -> None:
+    try:
+        atomic_write_text(_cursor_path(root), json.dumps(cursor, ensure_ascii=False) + "\n")
+    except Exception:
+        return

graphite/validation.py

@@ -0,0 +1,148 @@
+"""Validation for Graphite graph artifacts."""
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from pathlib import PurePosixPath
+from typing import Any
+
+_WINDOWS_ABS_RE = re.compile(r"^[A-Za-z]:[\\/]")
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    severity: str
+    code: str
+    message: str
+    path: str
+
+
+def validate_graph_bundle(bundle: dict[str, Any]) -> dict[str, Any]:
+    """Validate the public graph.json bundle and return a machine-readable report."""
+    issues: list[ValidationIssue] = []
+
+    nodes = bundle.get("nodes")
+    edges = bundle.get("edges")
+    metadata = bundle.get("metadata")
+    clusters = bundle.get("clusters", [])
+    analysis = bundle.get("analysis", {})
+
+    if not isinstance(nodes, list):
+        issues.append(_error("nodes_type", "nodes must be a list", "nodes"))
+        nodes = []
+    if not isinstance(edges, list):
+        issues.append(_error("edges_type", "edges must be a list", "edges"))
+        edges = []
+    if not isinstance(metadata, dict):
+        issues.append(_error("metadata_type", "metadata must be an object", "metadata"))
+        metadata = {}
+    if not isinstance(clusters, list):
+        issues.append(_warn("clusters_type", "clusters should be a list", "clusters"))
+        clusters = []
+    if not isinstance(analysis, dict):
+        issues.append(_warn("analysis_type", "analysis should be an object", "analysis"))
+
+    node_ids: set[str] = set()
+    for index, node in enumerate(nodes):
+        path = f"nodes[{index}]"
+        if not isinstance(node, dict):
+            issues.append(_error("node_type", "node must be an object", path))
+            continue
+        node_id = node.get("id")
+        if not isinstance(node_id, str) or not node_id.strip():
+            issues.append(_error("node_id_missing", "node id must be a non-empty string", f"{path}.id"))
+            continue
+        if node_id in node_ids:
+            issues.append(_error("node_id_duplicate", f"duplicate node id: {node_id}", f"{path}.id"))
+        node_ids.add(node_id)
+        source_file = node.get("source_file")
+        if isinstance(source_file, str) and _is_absolute_or_unsafe_path(source_file):
+            issues.append(_error("absolute_source_file", f"source_file must be project-relative: {source_file}", f"{path}.source_file"))
+
+    seen_edges: set[tuple[str, str, str]] = set()
+    for index, edge in enumerate(edges):
+        path = f"edges[{index}]"
+        if not isinstance(edge, dict):
+            issues.append(_error("edge_type", "edge must be an object", path))
+            continue
+        source = edge.get("source")
+        target = edge.get("target")
+        relation = edge.get("relation")
+        if not isinstance(source, str) or not source:
+            issues.append(_error("edge_source_missing", "edge source must be a non-empty string", f"{path}.source"))
+            continue
+        if not isinstance(target, str) or not target:
+            issues.append(_error("edge_target_missing", "edge target must be a non-empty string", f"{path}.target"))
+            continue
+        if not isinstance(relation, str) or not relation:
+            issues.append(_error("edge_relation_missing", "edge relation must be a non-empty string", f"{path}.relation"))
+            continue
+        if source not in node_ids:
+            issues.append(_error("edge_source_unknown", f"edge source does not exist: {source}", f"{path}.source"))
+        if target not in node_ids:
+            issues.append(_error("edge_target_unknown", f"edge target does not exist: {target}", f"{path}.target"))
+        key = (source, target, relation)
+        if key in seen_edges:
+            issues.append(_warn("edge_duplicate", f"duplicate edge: {source} -> {target} ({relation})", path))
+        seen_edges.add(key)
+        source_file = edge.get("source_file")
+        if isinstance(source_file, str) and _is_absolute_or_unsafe_path(source_file):
+            issues.append(_error("absolute_edge_source_file", f"edge source_file must be project-relative: {source_file}", f"{path}.source_file"))
+
+    expected_nodes = metadata.get("node_count")
+    expected_edges = metadata.get("edge_count")
+    if isinstance(expected_nodes, int) and expected_nodes != len(nodes):
+        issues.append(_error("metadata_node_count", f"metadata node_count {expected_nodes} != actual {len(nodes)}", "metadata.node_count"))
+    if isinstance(expected_edges, int) and expected_edges != len(edges):
+        issues.append(_error("metadata_edge_count", f"metadata edge_count {expected_edges} != actual {len(edges)}", "metadata.edge_count"))
+
+    for cidx, cluster in enumerate(clusters):
+        if not isinstance(cluster, dict):
+            issues.append(_warn("cluster_type", "cluster should be an object", f"clusters[{cidx}]"))
+            continue
+        members = cluster.get("members", [])
+        if not isinstance(members, list):
+            issues.append(_warn("cluster_members_type", "cluster members should be a list", f"clusters[{cidx}].members"))
+            continue
+        for midx, member in enumerate(members):
+            if isinstance(member, str) and member not in node_ids:
+                issues.append(_warn("cluster_member_unknown", f"cluster member does not exist: {member}", f"clusters[{cidx}].members[{midx}]"))
+
+    if not nodes:
+        issues.append(_warn("empty_graph", "graph contains no nodes", "nodes"))
+
+    errors = [issue for issue in issues if issue.severity == "error"]
+    warnings = [issue for issue in issues if issue.severity == "warning"]
+    return {
+        "ok": not errors,
+        "error_count": len(errors),
+        "warning_count": len(warnings),
+        "node_count": len(nodes),
+        "edge_count": len(edges),
+        "errors": [asdict(issue) for issue in errors],
+        "warnings": [asdict(issue) for issue in warnings],
+    }
+
+
+def assert_valid_graph_bundle(bundle: dict[str, Any]) -> dict[str, Any]:
+    """Validate or raise a concise ValueError suitable for build failure."""
+    report = validate_graph_bundle(bundle)
+    if not report["ok"]:
+        first = report["errors"][0]
+        raise ValueError(f"graph validation failed: {first['code']}: {first['message']} at {first['path']}")
+    return report
+
+
+def _error(code: str, message: str, path: str) -> ValidationIssue:
+    return ValidationIssue("error", code, message, path)
+
+
+def _warn(code: str, message: str, path: str) -> ValidationIssue:
+    return ValidationIssue("warning", code, message, path)
+
+
+def _is_absolute_or_unsafe_path(value: str) -> bool:
+    if _WINDOWS_ABS_RE.match(value) or value.startswith(("/", "\\")):
+        return True
+    parts = PurePosixPath(value.replace("\\", "/")).parts
+    return any(part == ".." for part in parts)

graphite/watch.py

@@ -0,0 +1,167 @@
+"""Lightweight local watcher for keeping Graphite graphs current."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from threading import Event
+from typing import Callable
+
+from .config import Config
+from .ingest import collect_files
+
+Snapshot = dict[str, str]
+SleepFn = Callable[[float], None]
+
+
+@dataclass(frozen=True)
+class WatchChange:
+    """File-hash changes detected between two Graphite scans."""
+
+    added: tuple[str, ...] = field(default_factory=tuple)
+    changed: tuple[str, ...] = field(default_factory=tuple)
+    removed: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def paths(self) -> tuple[str, ...]:
+        return tuple(sorted(set(self.added).union(self.changed).union(self.removed)))
+
+    @property
+    def has_changes(self) -> bool:
+        return bool(self.added or self.changed or self.removed)
+
+    def to_dict(self) -> dict[str, list[str]]:
+        return {
+            "added": list(self.added),
+            "changed": list(self.changed),
+            "removed": list(self.removed),
+        }
+
+
+@dataclass(frozen=True)
+class WatchOptions:
+    interval_seconds: float = 1.5
+    debounce_seconds: float = 0.75
+    max_cycles: int | None = None
+    build_now: bool = True
+    once: bool = False
+
+    def validate(self) -> None:
+        if self.interval_seconds <= 0:
+            raise ValueError("watch interval must be greater than zero")
+        if self.debounce_seconds < 0:
+            raise ValueError("watch debounce must be zero or greater")
+        if self.max_cycles is not None and self.max_cycles <= 0:
+            raise ValueError("watch max cycles must be greater than zero")
+
+
+def snapshot(root: Path, cfg: Config) -> Snapshot:
+    """Return a stable content-hash snapshot for files Graphite would ingest."""
+    cfg = cfg.canonical_graph()
+    return {entry.rel_path: entry.content_hash for entry in collect_files(root, cfg)}
+
+
+def diff_snapshots(previous: Snapshot, current: Snapshot) -> WatchChange:
+    """Compute deterministic file additions, content changes, and removals."""
+    previous_paths = set(previous)
+    current_paths = set(current)
+    added = tuple(sorted(current_paths - previous_paths))
+    removed = tuple(sorted(previous_paths - current_paths))
+    changed = tuple(sorted(path for path in previous_paths & current_paths if previous[path] != current[path]))
+    return WatchChange(added=added, changed=changed, removed=removed)
+
+
+def wait_for_stable_snapshot(
+    root: Path,
+    cfg: Config,
+    first: Snapshot,
+    debounce_seconds: float,
+    *,
+    sleep: SleepFn = time.sleep,
+    max_rounds: int = 5,
+) -> Snapshot:
+    """Wait until the ingest snapshot stops changing across the debounce window."""
+    if debounce_seconds <= 0:
+        return first
+
+    candidate = first
+    for _ in range(max_rounds):
+        sleep(debounce_seconds)
+        next_snapshot = snapshot(root, cfg)
+        if next_snapshot == candidate:
+            return next_snapshot
+        candidate = next_snapshot
+    return candidate
+
+
+def watch_loop(
+    root: Path,
+    cfg: Config,
+    on_change: Callable[[WatchChange], bool],
+    options: WatchOptions,
+    *,
+    stop_event: Event | None = None,
+    sleep: SleepFn = time.sleep,
+    on_error: Callable[[Exception], None] | None = None,
+) -> int:
+    """Poll for content changes and call `on_change` after debounced stable updates.
+
+    `on_change` returns True when downstream processing succeeded. Failed callbacks leave the
+    previous snapshot unchanged so the same change can be retried on the next cycle.
+    """
+    options.validate()
+    cfg = cfg.canonical_graph()
+    root = root.resolve()
+    if not root.exists():
+        raise FileNotFoundError(root)
+
+    previous = snapshot(root, cfg)
+    processed = 0
+
+    if options.build_now:
+        initial = WatchChange(added=tuple(sorted(previous)))
+        if on_change(initial):
+            processed += 1
+        elif options.once:
+            return processed
+
+    cycles = 0
+    while True:
+        if stop_event and stop_event.is_set():
+            return processed
+        if options.once and cycles > 0:
+            return processed
+        if options.max_cycles is not None and cycles >= options.max_cycles:
+            return processed
+
+        sleep(options.interval_seconds)
+        cycles += 1
+
+        try:
+            current = snapshot(root, cfg)
+            change = diff_snapshots(previous, current)
+            if not change.has_changes:
+                continue
+
+            stable = wait_for_stable_snapshot(
+                root,
+                cfg,
+                current,
+                options.debounce_seconds,
+                sleep=sleep,
+            )
+            change = diff_snapshots(previous, stable)
+            if not change.has_changes:
+                previous = stable
+                continue
+
+            if on_change(change):
+                previous = stable
+                processed += 1
+        except Exception as exc:
+            if on_error:
+                on_error(exc)
+            else:
+                raise
+
+    return processed