codegraph-ir 0.1.0__py3-none-any.whl

cgir/export/json_export.py

@@ -0,0 +1,37 @@
+"""Write the repo graph + ComponentSpec index to disk."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from cgir.ir.component_spec import ComponentSpec
+from cgir.ir.graph import RepoGraph
+from cgir.manifest import write_manifest
+
+
+def read_specs(index_dir: Path) -> list[ComponentSpec]:
+    """Load every ComponentSpec from an existing index directory."""
+    components_dir = index_dir / "components"
+    return [
+        ComponentSpec.from_dict(json.loads(p.read_text()))
+        for p in sorted(components_dir.glob("*.json"))
+    ]
+
+
+def write_index(out_dir: Path, graph: RepoGraph, specs: list[ComponentSpec]) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    (out_dir / "repo_graph.json").write_text(
+        json.dumps(graph.to_jsonable(), indent=2, sort_keys=True)
+    )
+
+    components_dir = out_dir / "components"
+    components_dir.mkdir(parents=True, exist_ok=True)
+    for spec in specs:
+        spec.validate()
+        (components_dir / f"{spec.id}.json").write_text(spec.to_json())
+
+    index = [{"id": spec.id, "kind": spec.kind.value, "trace": spec.trace} for spec in specs]
+    (out_dir / "components_index.json").write_text(json.dumps(index, indent=2, sort_keys=True))
+
+    write_manifest(out_dir, component_count=len(specs))

cgir/export/mermaid.py

@@ -0,0 +1,57 @@
+"""Mermaid call-graph rendering from ComponentSpecs.
+
+Produces ``flowchart LR`` text suitable for embedding in Markdown (GitHub,
+Obsidian, mermaid.live). One node per component, one ``subgraph`` per
+source file, one edge per resolved intra-repo call; nodes are colored by
+:class:`~cgir.ir.component_spec.ComponentKind`.
+
+Calls to components outside the spec set (stdlib, third-party) are skipped
+rather than rendered as dangling nodes — the diagram shows *this* repo.
+"""
+
+from __future__ import annotations
+
+import re
+
+from cgir.ir.component_spec import ComponentSpec
+
+_KIND_STYLES: dict[str, str] = {
+    "pure_function": "fill:#c6f6d5,stroke:#2f855a,color:#1a202c",
+    "orchestrator": "fill:#bee3f8,stroke:#2b6cb0,color:#1a202c",
+    "state_transformer": "fill:#feebc8,stroke:#c05621,color:#1a202c",
+    "effect_adapter": "fill:#fed7d7,stroke:#c53030,color:#1a202c",
+    "unknown": "fill:#e2e8f0,stroke:#4a5568,color:#1a202c",
+}
+
+
+def render_call_graph(specs: list[ComponentSpec]) -> str:
+    """Render the component call graph as Mermaid flowchart text."""
+    lines = ["flowchart LR"]
+    known_ids = {s.id for s in specs}
+
+    by_file: dict[str, list[ComponentSpec]] = {}
+    for spec in specs:
+        file = spec.trace[0].rsplit(":", 1)[0] if spec.trace else "(unknown)"
+        by_file.setdefault(file, []).append(spec)
+
+    for file, group in sorted(by_file.items()):
+        lines.append(f'    subgraph {_mermaid_id(file)}["{file}"]')
+        for spec in group:
+            lines.append(f'        {_mermaid_id(spec.id)}["{spec.id}"]')
+        lines.append("    end")
+
+    for spec in specs:
+        for callee in spec.calls:
+            if callee in known_ids:
+                lines.append(f"    {_mermaid_id(spec.id)} --> {_mermaid_id(callee)}")
+
+    for kind in sorted({s.kind.value for s in specs}):
+        lines.append(f"    classDef {kind} {_KIND_STYLES[kind]}")
+    for spec in specs:
+        lines.append(f"    class {_mermaid_id(spec.id)} {spec.kind.value}")
+
+    return "\n".join(lines) + "\n"
+
+
+def _mermaid_id(raw: str) -> str:
+    return re.sub(r"[^0-9A-Za-z_]", "_", raw)

cgir/export/neo4j.py

@@ -0,0 +1,11 @@
+"""Neo4j export — milestone: P2-neo4j."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cgir.ir.graph import RepoGraph
+
+
+def write(out_dir: Path, graph: RepoGraph) -> None:
+    raise NotImplementedError("milestone: P2-neo4j")

cgir/hooks.py

@@ -0,0 +1,189 @@
+"""The git pre-commit seatbelt.
+
+A local, deterministic gate on your own — and your agent's — commits.
+On commit, ``run_check`` scans the last committed tree (``HEAD``) against
+the *staged* tree (``git write-tree``), diffs the contracts, and reports:
+
+* **violations** — the ``--fail-on`` drift rules that trip (defaults to the
+  evidence-based low-noise set from ``docs/gate-noise.md``);
+* **tests to run** — the union of :func:`compute_typed_impact` over every
+  changed component, narrowed by *its* contract delta, so a body-only
+  refactor asks for nothing downstream.
+
+Design choices that matter for a hook:
+
+* **Scans the staged tree, not the working tree** — it checks exactly what
+  will be committed (``git write-tree`` materialises the index as a tree).
+* **Fail-open on internal error** — a bug in CGIR must never block your
+  commit; only a real contract violation does.
+* **Skips non-source commits** — no scan when nothing with a supported
+  extension is staged.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from cgir.ir.component_spec import ComponentSpec
+from cgir.languages import ADAPTERS
+from cgir.pipeline import scan_repo
+from cgir.report.diff import compute_diff, render_diff, violations
+from cgir.report.impact import compute_typed_impact
+
+# The low-noise default from the real-history noise measurement: fail only
+# when something starts — or silently stops — reaching the outside world.
+DEFAULT_FAIL_ON: tuple[str, ...] = (
+    "effect-gain:net",
+    "effect-gain:fs",
+    "effect-gain:db",
+    "effect-loss:net",
+    "effect-loss:fs",
+    "effect-loss:db",
+)
+
+_SUPPORTED_EXTS: frozenset[str] = frozenset(
+    ext for adapter in ADAPTERS.values() for ext in adapter.file_extensions
+)
+
+_HOOK_TEMPLATE = """\
+#!/bin/sh
+# CGIR contract seatbelt — installed by `cgir hook install`. Delete to remove.
+if ! command -v cgir >/dev/null 2>&1; then
+  echo "cgir not on PATH; skipping contract check" >&2
+  exit 0
+fi
+exec cgir hook run {flags}
+"""
+
+
+@dataclass
+class HookResult:
+    checked: bool
+    violations: list[str] = field(default_factory=list)
+    changed: list[str] = field(default_factory=list)
+    tests: list[str] = field(default_factory=list)
+    diff_text: str = ""
+    error: str | None = None
+
+
+def _git(repo: Path, *args: str) -> str:
+    return subprocess.check_output(["git", "-C", str(repo), *args], text=True).strip()
+
+
+def _staged_supported(repo: Path) -> bool:
+    names = _git(repo, "diff", "--cached", "--name-only").splitlines()
+    return any(Path(n).suffix in _SUPPORTED_EXTS for n in names)
+
+
+def _specs_of_tree(repo: Path, tree: str) -> list[ComponentSpec]:
+    """Scan the content of a git tree-ish out-of-tree."""
+    with tempfile.TemporaryDirectory() as td:
+        src = Path(td) / "src"
+        src.mkdir()
+        archive = subprocess.check_output(["git", "-C", str(repo), "archive", tree])
+        subprocess.run(["tar", "-x", "-C", str(src)], input=archive, check=True)
+        with tempfile.TemporaryDirectory() as od:
+            return scan_repo(src, out=Path(od)).specs
+
+
+def run_check(repo: Path, fail_on: list[str] | None = None) -> HookResult:
+    """Contract-check the staged tree against HEAD. Fail-open on any error."""
+    rules = list(fail_on) if fail_on is not None else list(DEFAULT_FAIL_ON)
+    try:
+        if not _staged_supported(repo):
+            return HookResult(checked=False)
+        staged_tree = _git(repo, "write-tree")
+        try:
+            head_tree = _git(repo, "rev-parse", "HEAD^{tree}")
+        except subprocess.CalledProcessError:
+            head_tree = None  # unborn branch — the initial commit
+        if head_tree == staged_tree:
+            return HookResult(checked=False)
+
+        base_specs = _specs_of_tree(repo, head_tree) if head_tree else []
+        head_specs = _specs_of_tree(repo, staged_tree)
+    except Exception as exc:  # never block a commit because of our own bug
+        return HookResult(checked=False, error=f"{type(exc).__name__}: {exc}")
+
+    diff = compute_diff(base_specs, head_specs)
+    found = violations(diff, rules)
+    changed = [c["id"] for c in diff["changed"]]
+
+    tests: set[str] = set()
+    for change in diff["changed"]:
+        typed = compute_typed_impact(head_specs, change["id"], list(change["fields"].keys()))
+        tests |= set(typed["tests"])
+
+    return HookResult(
+        checked=True,
+        violations=found,
+        changed=changed,
+        tests=sorted(tests),
+        diff_text=render_diff(diff),
+    )
+
+
+def render_hook(result: HookResult) -> str:
+    if result.error:
+        return f"cgir: skipped contract check ({result.error})\n"
+    if not result.checked:
+        return ""
+    lines = ["cgir contract seatbelt"]
+    if result.changed:
+        lines.append(f"  contract changes in {len(result.changed)} component(s)")
+    if result.tests:
+        lines.append(f"  tests to run ({len(result.tests)}):")
+        lines.extend(f"    • {t}" for t in result.tests)
+    if result.violations:
+        lines.append("")
+        lines.append(f"  ❌ blocked — {len(result.violations)} drift violation(s):")
+        lines.extend(f"    ! {v}" for v in result.violations)
+        lines.append("  (bypass once with `git commit --no-verify`)")
+    else:
+        lines.append("  ✅ no blocking contract drift")
+    return "\n".join(lines) + "\n"
+
+
+def _hooks_dir(repo: Path) -> Path:
+    return Path(_git(repo, "rev-parse", "--git-path", "hooks"))
+
+
+def install(repo: Path, fail_on: list[str] | None = None, force: bool = False) -> Path:
+    """Write ``.git/hooks/pre-commit`` invoking ``cgir hook run``."""
+    rules = list(fail_on) if fail_on is not None else list(DEFAULT_FAIL_ON)
+    hooks = _hooks_dir(repo)
+    if not hooks.is_absolute():
+        hooks = repo / hooks
+    hooks.mkdir(parents=True, exist_ok=True)
+    path = hooks / "pre-commit"
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} exists; pass force=True to overwrite")
+    flags = " ".join(f"--fail-on {r}" for r in rules)
+    path.write_text(_HOOK_TEMPLATE.format(flags=flags))
+    path.chmod(0o755)
+    return path
+
+
+def uninstall(repo: Path) -> bool:
+    """Remove the hook if it is ours. Returns whether anything was removed."""
+    hooks = _hooks_dir(repo)
+    if not hooks.is_absolute():
+        hooks = repo / hooks
+    path = hooks / "pre-commit"
+    if path.exists() and "cgir hook run" in path.read_text():
+        path.unlink()
+        return True
+    return False
+
+
+__all__ = [
+    "DEFAULT_FAIL_ON",
+    "HookResult",
+    "install",
+    "render_hook",
+    "run_check",
+    "uninstall",
+]

cgir/ir/__init__.py

@@ -0,0 +1,16 @@
+"""Internal IR: nodes, edges, RepoGraph, and ComponentSpec."""
+
+from cgir.ir.component_spec import ComponentKind, ComponentSpec
+from cgir.ir.edges import Edge, EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+
+__all__ = [
+    "ComponentKind",
+    "ComponentSpec",
+    "Edge",
+    "EdgeKind",
+    "Node",
+    "NodeKind",
+    "RepoGraph",
+]

cgir/ir/component_spec.py

@@ -0,0 +1,100 @@
+"""ComponentSpec — the agent-facing contract (Code-IR.md §Data model)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+from functools import lru_cache
+from typing import Any
+
+from jsonschema import Draft202012Validator
+
+COMPONENT_SPEC_SCHEMA: dict[str, Any] = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://cgir.dev/schemas/component_spec.schema.json",
+    "title": "ComponentSpec",
+    "type": "object",
+    "required": ["id", "kind", "inputs", "outputs", "effects", "calls", "trace"],
+    "properties": {
+        "id": {"type": "string"},
+        "kind": {
+            "enum": [
+                "pure_function",
+                "state_transformer",
+                "effect_adapter",
+                "orchestrator",
+                "unknown",
+            ]
+        },
+        "language": {"type": "string"},
+        "signature": {"type": "string"},
+        "entrypoint": {"type": "string"},
+        "doc": {"type": "string"},
+        "raises": {"type": "array", "items": {"type": "string"}},
+        "covered_by": {"type": "array", "items": {"type": "string"}},
+        "inputs": {"type": "array", "items": {"type": "string"}},
+        "outputs": {"type": "array", "items": {"type": "string"}},
+        "effects": {"type": "array", "items": {"type": "string"}},
+        "calls": {"type": "array", "items": {"type": "string"}},
+        "constructs": {"type": "array", "items": {"type": "string"}},
+        "reads": {"type": "array", "items": {"type": "string"}},
+        "writes": {"type": "array", "items": {"type": "string"}},
+        "purity": {"type": "number", "minimum": 0, "maximum": 1},
+        "algorithm": {"type": "array", "items": {"type": "string"}},
+        "trace": {"type": "array", "items": {"type": "string"}},
+    },
+    "additionalProperties": False,
+}
+
+
+class ComponentKind(StrEnum):
+    pure_function = "pure_function"
+    state_transformer = "state_transformer"
+    effect_adapter = "effect_adapter"
+    orchestrator = "orchestrator"
+    unknown = "unknown"
+
+
+@dataclass(slots=True)
+class ComponentSpec:
+    id: str
+    kind: ComponentKind
+    inputs: list[str] = field(default_factory=list)
+    outputs: list[str] = field(default_factory=list)
+    effects: list[str] = field(default_factory=list)
+    calls: list[str] = field(default_factory=list)
+    constructs: list[str] = field(default_factory=list)
+    trace: list[str] = field(default_factory=list)
+    language: str | None = None
+    signature: str | None = None
+    entrypoint: str | None = None
+    doc: str | None = None
+    raises: list[str] = field(default_factory=list)
+    covered_by: list[str] = field(default_factory=list)
+    reads: list[str] = field(default_factory=list)
+    writes: list[str] = field(default_factory=list)
+    purity: float | None = None
+    algorithm: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["kind"] = self.kind.value
+        return {k: v for k, v in data.items() if v is not None}
+
+    def to_json(self, indent: int | None = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, sort_keys=True)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ComponentSpec:
+        payload = dict(data)
+        payload["kind"] = ComponentKind(payload["kind"])
+        return cls(**payload)
+
+    def validate(self) -> None:
+        _validator().validate(self.to_dict())
+
+
+@lru_cache(maxsize=1)
+def _validator() -> Draft202012Validator:
+    return Draft202012Validator(COMPONENT_SPEC_SCHEMA)

cgir/ir/edges.py

@@ -0,0 +1,31 @@
+"""Edge vocabulary for the CGIR graph (Code-IR.md §Data model)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class EdgeKind(StrEnum):
+    CONTAINS = "CONTAINS"
+    IMPORTS = "IMPORTS"
+    CALLS = "CALLS"
+    READS = "READS"
+    WRITES = "WRITES"
+    MUTATES = "MUTATES"
+    RETURNS = "RETURNS"
+    THROWS = "THROWS"
+    FLOWS_TO = "FLOWS_TO"
+    CONTROLS = "CONTROLS"
+    DEPENDS_ON = "DEPENDS_ON"
+    TRACE_OF = "TRACE_OF"
+    REGENERATED_AS = "REGENERATED_AS"
+
+
+@dataclass(frozen=True, slots=True)
+class Edge:
+    src: str
+    dst: str
+    kind: EdgeKind
+    attrs: dict[str, Any] = field(default_factory=dict)

cgir/ir/graph.py

@@ -0,0 +1,132 @@
+"""RepoGraph: a thin wrapper over networkx.MultiDiGraph with CGIR semantics."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+import networkx as nx
+
+from cgir.ir.edges import Edge, EdgeKind
+from cgir.ir.nodes import Node, NodeKind
+
+
+class RepoGraph:
+    def __init__(self) -> None:
+        self._g: nx.MultiDiGraph = nx.MultiDiGraph()
+
+    def add_node(self, node: Node) -> None:
+        self._g.add_node(
+            node.id,
+            kind=node.kind,
+            name=node.name,
+            path=node.path,
+            start_line=node.start_line,
+            end_line=node.end_line,
+            attrs=dict(node.attrs),
+        )
+
+    def add_edge(self, edge: Edge) -> None:
+        self._g.add_edge(
+            edge.src, edge.dst, key=edge.kind.value, kind=edge.kind, attrs=dict(edge.attrs)
+        )
+
+    def has_node(self, node_id: str) -> bool:
+        return node_id in self._g
+
+    def get_node(self, node_id: str) -> Node:
+        data = self._g.nodes[node_id]
+        return Node(
+            id=node_id,
+            kind=data["kind"],
+            name=data["name"],
+            path=data.get("path"),
+            start_line=data.get("start_line"),
+            end_line=data.get("end_line"),
+            attrs=dict(data.get("attrs") or {}),
+        )
+
+    def nodes(self, kind: NodeKind | None = None) -> Iterator[Node]:
+        for node_id, data in self._g.nodes(data=True):
+            if kind is None or data["kind"] == kind:
+                yield Node(
+                    id=node_id,
+                    kind=data["kind"],
+                    name=data["name"],
+                    path=data.get("path"),
+                    start_line=data.get("start_line"),
+                    end_line=data.get("end_line"),
+                    attrs=dict(data.get("attrs") or {}),
+                )
+
+    def out_edges(self, node_id: str, kind: EdgeKind | None = None) -> Iterator[Edge]:
+        for src, dst, data in self._g.out_edges(node_id, data=True):
+            if kind is None or data["kind"] == kind:
+                yield Edge(src=src, dst=dst, kind=data["kind"], attrs=dict(data.get("attrs") or {}))
+
+    def in_edges(self, node_id: str, kind: EdgeKind | None = None) -> Iterator[Edge]:
+        for src, dst, data in self._g.in_edges(node_id, data=True):
+            if kind is None or data["kind"] == kind:
+                yield Edge(src=src, dst=dst, kind=data["kind"], attrs=dict(data.get("attrs") or {}))
+
+    def children(self, node_id: str, kind: NodeKind | None = None) -> Iterator[Node]:
+        for edge in self.out_edges(node_id, EdgeKind.CONTAINS):
+            child = self.get_node(edge.dst)
+            if kind is None or child.kind == kind:
+                yield child
+
+    def __len__(self) -> int:
+        return int(self._g.number_of_nodes())
+
+    @classmethod
+    def from_jsonable(cls, data: dict[str, Any]) -> RepoGraph:
+        """Inverse of :meth:`to_jsonable` — rebuild a graph from its JSON dump."""
+        graph = cls()
+        for n in data.get("nodes", []):
+            graph.add_node(
+                Node(
+                    id=n["id"],
+                    kind=NodeKind(n["kind"]),
+                    name=n["name"],
+                    path=n.get("path"),
+                    start_line=n.get("start_line"),
+                    end_line=n.get("end_line"),
+                    attrs=dict(n.get("attrs") or {}),
+                )
+            )
+        for e in data.get("edges", []):
+            graph.add_edge(
+                Edge(
+                    src=e["src"],
+                    dst=e["dst"],
+                    kind=EdgeKind(e["kind"]),
+                    attrs=dict(e.get("attrs") or {}),
+                )
+            )
+        return graph
+
+    def to_jsonable(self) -> dict[str, Any]:
+        nodes = []
+        for node in self.nodes():
+            nodes.append(
+                {
+                    "id": node.id,
+                    "kind": node.kind.value,
+                    "name": node.name,
+                    "path": node.path,
+                    "start_line": node.start_line,
+                    "end_line": node.end_line,
+                    "attrs": node.attrs,
+                }
+            )
+        edges = []
+        for src, dst, data in self._g.edges(data=True):
+            edges.append(
+                {
+                    "src": src,
+                    "dst": dst,
+                    "kind": data["kind"].value,
+                    "attrs": data.get("attrs") or {},
+                }
+            )
+        return {"nodes": nodes, "edges": edges}

cgir/ir/nodes.py

@@ -0,0 +1,38 @@
+"""Node vocabulary for the CGIR graph (Code-IR.md §Data model)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class NodeKind(StrEnum):
+    Repository = "Repository"
+    File = "File"
+    Module = "Module"
+    Class = "Class"
+    Function = "Function"
+    Method = "Method"
+    Parameter = "Parameter"
+    Variable = "Variable"
+    Assignment = "Assignment"
+    Expr = "Expr"
+    Statement = "Statement"
+    Branch = "Branch"
+    Loop = "Loop"
+    Return = "Return"
+    Import = "Import"
+    Effect = "Effect"
+    Test = "Test"
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    id: str
+    kind: NodeKind
+    name: str
+    path: str | None = None
+    start_line: int | None = None
+    end_line: int | None = None
+    attrs: dict[str, Any] = field(default_factory=dict)

cgir/languages/__init__.py

@@ -0,0 +1,25 @@
+"""Language adapters — the per-language seam over a shared analysis pipeline.
+
+Add a language by implementing :class:`LanguageAdapter`; register it in
+``registry.ADAPTERS`` and everything downstream (stats, viz, flow, diff,
+pack, lint, verify) works on it.
+"""
+
+from __future__ import annotations
+
+from cgir.languages.base import CallSite, LanguageAdapter
+from cgir.languages.cache import SourceCache
+from cgir.languages.python import PythonAdapter
+from cgir.languages.registry import ADAPTERS, DEFAULT_ADAPTER, adapter_for_extension
+from cgir.languages.typescript import TypeScriptAdapter
+
+__all__ = [
+    "ADAPTERS",
+    "DEFAULT_ADAPTER",
+    "CallSite",
+    "LanguageAdapter",
+    "PythonAdapter",
+    "SourceCache",
+    "TypeScriptAdapter",
+    "adapter_for_extension",
+]