codegraph-ir 0.1.0__py3-none-any.whl

cgir/analyses/pdg.py

@@ -0,0 +1,75 @@
+"""Program dependence graph overlay.
+
+Adds two edge kinds onto the existing CFG-enriched graph:
+
+* ``FLOWS_TO`` — data dependence. For each definition D (a ``Parameter``
+  or any CFG node with a non-empty ``writes`` attr — ``Assignment``,
+  ``for`` header, ``with`` header, ``except`` clause) writing variable v,
+  and each CFG node N that *reads* v, emit ``D -[FLOWS_TO]-> N`` iff D
+  reaches N (per :mod:`cgir.analyses.reaching_defs`).
+* ``DEPENDS_ON`` — control dependence. For each CFG node N with
+  ``attrs["controlled_by"]`` set, emit ``N -[DEPENDS_ON]-> controller``.
+  The controller is the immediately enclosing ``Branch`` or ``Loop``, as
+  recorded by :mod:`cgir.analyses.cfg`.
+
+Pure-graph pass: no ``repo_path``, no re-parse. Idempotency is *not*
+guaranteed — calling ``build`` twice will duplicate edges. The CLI calls
+it once.
+"""
+
+from __future__ import annotations
+
+from cgir.analyses import reaching_defs
+from cgir.ir.edges import Edge, EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+
+_CFG_KINDS: frozenset[NodeKind] = frozenset(
+    {
+        NodeKind.Statement,
+        NodeKind.Assignment,
+        NodeKind.Branch,
+        NodeKind.Loop,
+        NodeKind.Return,
+    }
+)
+
+
+def build(graph: RepoGraph) -> None:
+    rd = reaching_defs.compute(graph)
+    for func in list(graph.nodes()):
+        if func.kind in {NodeKind.Function, NodeKind.Method}:
+            _build_for_function(graph, func, rd)
+
+
+def _build_for_function(graph: RepoGraph, func: Node, rd: dict[str, set[str]]) -> None:
+    cfg_nodes = [c for c in graph.children(func.id) if c.kind in _CFG_KINDS]
+    if not cfg_nodes:
+        return
+    params = list(graph.children(func.id, NodeKind.Parameter))
+
+    # var → {def_id, ...} (Assignments + Parameters)
+    var_to_defs: dict[str, set[str]] = {}
+    for p in params:
+        var_to_defs.setdefault(p.name, set()).add(p.id)
+    for n in cfg_nodes:
+        writes = n.attrs.get("writes") if n.attrs else None
+        if isinstance(writes, list):
+            for v in writes:
+                var_to_defs.setdefault(v, set()).add(n.id)
+
+    # FLOWS_TO: def -> use, gated by reaching defs.
+    for n in cfg_nodes:
+        reads = n.attrs.get("reads") if n.attrs else None
+        if not isinstance(reads, list) or not reads:
+            continue
+        in_defs = rd.get(n.id, set())
+        for var in reads:
+            for def_id in var_to_defs.get(var, set()) & in_defs:
+                graph.add_edge(Edge(src=def_id, dst=n.id, kind=EdgeKind.FLOWS_TO))
+
+    # DEPENDS_ON: controlled node -> controlling Branch/Loop.
+    for n in cfg_nodes:
+        controller = n.attrs.get("controlled_by") if n.attrs else None
+        if isinstance(controller, str):
+            graph.add_edge(Edge(src=n.id, dst=controller, kind=EdgeKind.DEPENDS_ON))

cgir/analyses/purity.py

@@ -0,0 +1,37 @@
+"""Purity scoring from the effects dict produced by :mod:`cgir.analyses.effects`.
+
+Rubric:
+    1.0  no own impure effects AND only calls into pure components
+    0.7  ``calls_effectful`` only (orchestrates effectful callees but does
+         no direct IO/state writes itself)
+    0.0  any direct impure effect (io, net, fs, nondeterm, db)
+
+``raise`` is *not* impure (settled Sprint 13): exceptions are control flow,
+so a raise-only validator scores 1.0 while keeping the ``raise`` tag in its
+effects list.
+"""
+
+from __future__ import annotations
+
+from cgir.analyses.effects import IMPURE_EFFECT_TAGS, TRANSITIVE_TAG
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import NodeKind
+
+# Retained so callers that compute specs without a purity pass still get a
+# defined value; downstream code can treat this as "no information".
+PLACEHOLDER_SCORE = 0.5
+
+
+def score(graph: RepoGraph, effects: dict[str, list[str]]) -> dict[str, float]:
+    scores: dict[str, float] = {}
+    for node in graph.nodes():
+        if node.kind not in {NodeKind.Function, NodeKind.Method}:
+            continue
+        tags = set(effects.get(node.id, []))
+        if tags & IMPURE_EFFECT_TAGS:
+            scores[node.id] = 0.0
+        elif TRANSITIVE_TAG in tags:
+            scores[node.id] = 0.7
+        else:
+            scores[node.id] = 1.0
+    return scores

cgir/analyses/reaching_defs.py

@@ -0,0 +1,115 @@
+"""Reaching-definitions analysis.
+
+Classical forward may-analysis over each function's CFG:
+
+* Any CFG node A with a non-empty ``writes`` attr is a definition of those
+  variables: ``gen[A] = {A.id}`` and ``kill[A]`` contains every other def
+  of any variable A writes. This covers ``Assignment`` nodes, ``for``-loop
+  headers (loop targets), ``with`` headers (``as`` aliases), and ``except``
+  clauses (``as`` aliases).
+* ``Parameter`` nodes count as initial defs at function entry.
+* ``in[n] = union of out[pred]`` over ``CONTROLS`` predecessors within
+  the same function; for the entry node(s), ``in`` also contains the
+  parameter defs.
+* ``out[n] = gen[n] | (in[n] - kill[n])``.
+
+This is the first pure-graph analysis: it reads the ``writes`` attrs
+populated by :mod:`cgir.analyses.cfg` and walks the graph. It does not
+re-parse source. See ``docs/roadmap.md`` "Grammar-agnostic core refactor".
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+from cgir.ir.edges import EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+
+_CFG_KINDS: frozenset[NodeKind] = frozenset(
+    {
+        NodeKind.Statement,
+        NodeKind.Assignment,
+        NodeKind.Branch,
+        NodeKind.Loop,
+        NodeKind.Return,
+    }
+)
+
+
+def compute(graph: RepoGraph) -> dict[str, set[str]]:
+    """Return ``{cfg_node_id: {def_id, ...}}`` across every function/method.
+
+    ``def_id`` is the id of a ``Parameter`` node or any CFG node with a
+    non-empty ``writes`` attr.
+    """
+    result: dict[str, set[str]] = {}
+    for func in list(graph.nodes()):
+        if func.kind in {NodeKind.Function, NodeKind.Method}:
+            result.update(_compute_for_function(graph, func))
+    return result
+
+
+def _compute_for_function(graph: RepoGraph, func: Node) -> dict[str, set[str]]:
+    cfg_nodes = [c for c in graph.children(func.id) if c.kind in _CFG_KINDS]
+    if not cfg_nodes:
+        return {}
+    params = list(graph.children(func.id, NodeKind.Parameter))
+
+    cfg_ids: set[str] = {n.id for n in cfg_nodes}
+
+    # var -> {def_id, ...} (Assignment and Parameter)
+    defs_by_var: dict[str, set[str]] = {}
+    for p in params:
+        defs_by_var.setdefault(p.name, set()).add(p.id)
+    writes_per_node: dict[str, list[str]] = {}
+    for n in cfg_nodes:
+        writes_raw = n.attrs.get("writes") if n.attrs else None
+        writes = list(writes_raw) if isinstance(writes_raw, list) else []
+        if writes:
+            writes_per_node[n.id] = writes
+        for var in writes:
+            defs_by_var.setdefault(var, set()).add(n.id)
+
+    gen: dict[str, set[str]] = {}
+    kill: dict[str, set[str]] = {}
+    for n in cfg_nodes:
+        if n.id in writes_per_node:
+            gen[n.id] = {n.id}
+            kill_set: set[str] = set()
+            for var in writes_per_node[n.id]:
+                kill_set |= defs_by_var.get(var, set()) - {n.id}
+            kill[n.id] = kill_set
+        else:
+            gen[n.id] = set()
+            kill[n.id] = set()
+
+    entry_defs: set[str] = {p.id for p in params}
+
+    in_set: dict[str, set[str]] = {nid: set() for nid in cfg_ids}
+    out_set: dict[str, set[str]] = {nid: set() for nid in cfg_ids}
+
+    worklist: deque[str] = deque(cfg_ids)
+    queued: set[str] = set(cfg_ids)
+
+    while worklist:
+        nid = worklist.popleft()
+        queued.discard(nid)
+
+        new_in: set[str] = set()
+        for pred_edge in graph.in_edges(nid, EdgeKind.CONTROLS):
+            if pred_edge.src == func.id:
+                new_in |= entry_defs
+            elif pred_edge.src in cfg_ids:
+                new_in |= out_set[pred_edge.src]
+        in_set[nid] = new_in
+
+        new_out = gen[nid] | (new_in - kill[nid])
+        if new_out != out_set[nid]:
+            out_set[nid] = new_out
+            for succ_edge in graph.out_edges(nid, EdgeKind.CONTROLS):
+                if succ_edge.dst in cfg_ids and succ_edge.dst not in queued:
+                    worklist.append(succ_edge.dst)
+                    queued.add(succ_edge.dst)
+
+    return {nid: in_set[nid] for nid in cfg_ids}

cgir/analyses/symbols.py

@@ -0,0 +1,106 @@
+"""Per-module symbol tables + cross-file import resolution for Python.
+
+Resolution rules:
+* ``import x.y.z`` binds the local name ``x`` to module ``x.y.z`` (Python's
+  actual semantics differ, but for call-graph purposes we only care that the
+  dotted target resolves).
+* ``from a.b import c`` binds the local name ``c`` to the qualified symbol
+  ``a.b.c``. If that resolves to a known ``Function``/``Class`` node, we
+  record it; otherwise the binding stays opaque (third-party).
+* ``import x as y`` / ``from a import b as c`` bind the *alias* (recorded
+  by the ingester on the Import node); the original name is not bound.
+* Top-level ``def``/``class`` in a module bind their names in that module's
+  table.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from cgir.ir.edges import EdgeKind
+from cgir.ir.graph import RepoGraph
+from cgir.ir.nodes import Node, NodeKind
+
+
+@dataclass
+class SymbolTable:
+    """Local name → graph node id (or ``None`` for opaque external symbols)."""
+
+    module_id: str
+    bindings: dict[str, str | None] = field(default_factory=dict)
+
+
+def build_symbol_tables(graph: RepoGraph) -> dict[str, SymbolTable]:
+    qualname_index = _qualname_index(graph)
+    tables: dict[str, SymbolTable] = {}
+
+    for module in graph.nodes(NodeKind.Module):
+        table = SymbolTable(module_id=module.id)
+        for child in graph.children(module.id):
+            if child.kind in {NodeKind.Function, NodeKind.Class}:
+                table.bindings[child.name] = child.id
+        tables[module.id] = table
+
+    for module in graph.nodes(NodeKind.Module):
+        table = tables[module.id]
+        for child in graph.children(module.id, NodeKind.Import):
+            target = str(child.attrs.get("target") or child.name)
+            alias = child.attrs.get("alias")
+            local = alias if isinstance(alias, str) else target.rsplit(".", 1)[-1]
+            table.bindings[local] = _resolve_target(qualname_index, target)
+
+    return tables
+
+
+def _resolve_target(qualname_index: dict[str, str], target: str) -> str | None:
+    """Exact qualname match, else a *unique* suffix match.
+
+    The suffix fallback bridges source-root prefixes: a repo whose package
+    lives in ``backend/`` (or ``src/``) has module qualnames like
+    ``backend.app.repos.chapter`` while its code imports
+    ``app.repos.chapter``. Ambiguous suffixes stay unresolved — don't guess.
+    """
+    hit = qualname_index.get(target)
+    if hit is not None:
+        return hit
+    suffix = "." + target
+    candidates = {nid for qual, nid in qualname_index.items() if qual.endswith(suffix)}
+    if len(candidates) == 1:
+        return next(iter(candidates))
+    return None
+
+
+def _qualname_index(graph: RepoGraph) -> dict[str, str]:
+    index: dict[str, str] = {}
+    for node in graph.nodes():
+        if node.kind not in {NodeKind.Function, NodeKind.Method, NodeKind.Class, NodeKind.Module}:
+            continue
+        qual = node.attrs.get("qualname") if node.attrs else None
+        if isinstance(qual, str):
+            index[qual] = node.id
+        else:
+            index[node.name] = node.id
+    return index
+
+
+def resolve(tables: dict[str, SymbolTable], module_id: str, name: str) -> str | None:
+    table = tables.get(module_id)
+    if table is None:
+        return None
+    return table.bindings.get(name)
+
+
+def module_of(graph: RepoGraph, func_node: Node) -> str | None:
+    """Walk CONTAINS edges upward to find the owning Module id."""
+    current_id = func_node.id
+    visited: set[str] = set()
+    while current_id not in visited:
+        visited.add(current_id)
+        parents = list(graph.in_edges(current_id, EdgeKind.CONTAINS))
+        if not parents:
+            return None
+        parent = graph.get_node(parents[0].src)
+        if parent.kind == NodeKind.Module:
+            return parent.id
+        current_id = parent.id
+    return None

cgir/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API surface — a thin FastAPI layer over :mod:`cgir.pipeline`."""

cgir/api/mcp_server.py

@@ -0,0 +1,172 @@
+"""MCP server — the semantic index as agent tools.
+
+Agents are CGIR's target user, and agents call tools rather than reading
+dashboards. The ``tool_*`` functions below are plain callables over an
+index directory, each returning a string; :func:`create_server` wraps
+them in FastMCP behind a lazy import (``pip install cgir[mcp]``),
+mirroring the anthropic pattern in :mod:`cgir.regenerate.regenerator`.
+
+Run it: ``cgir mcp --index .cgir`` (stdio transport), then register the
+command as an MCP server in your agent's config.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cgir.export.json_export import read_specs
+from cgir.report.flow import render_flow
+from cgir.report.impact import render_impact, render_typed_impact
+from cgir.report.pack import build_pack, render_pack
+from cgir.report.stats import compute_stats, render_text
+
+
+def tool_stats(index_dir: Path) -> str:
+    """Structure report: kinds, purity, effects, hotspots, entrypoints."""
+    return render_text(compute_stats(read_specs(index_dir)))
+
+
+def tool_component(index_dir: Path, component_id: str) -> str:
+    """One ComponentSpec as JSON."""
+    spec_path = index_dir / "components" / f"{component_id}.json"
+    if not spec_path.exists():
+        return f"unknown component: {component_id}"
+    return spec_path.read_text()
+
+
+def tool_flow(index_dir: Path, component_id: str, depth: int = 3) -> str:
+    """Upstream callers and downstream callees, annotated."""
+    try:
+        return render_flow(read_specs(index_dir), component_id, depth)
+    except KeyError:
+        return f"unknown component: {component_id}"
+
+
+def tool_impact(index_dir: Path, component_id: str) -> str:
+    """Blast radius of changing a component: affected callers, entrypoints, tests."""
+    try:
+        return render_impact(read_specs(index_dir), component_id)
+    except KeyError:
+        return f"unknown component: {component_id}"
+
+
+def tool_impact_of_change(index_dir: Path, repo: Path, component_id: str, candidate: str) -> str:
+    """Blast radius of a *specific* proposed edit — narrowed by its real contract delta."""
+    from cgir.verify import verify
+
+    try:
+        result = verify(index_dir, component_id, candidate, repo)
+    except KeyError:
+        return f"unknown component: {component_id}"
+    delta = list(result.drift.keys())
+    return render_typed_impact(read_specs(index_dir), component_id, delta)
+
+
+def tool_pack(index_dir: Path, component_id: str, budget: int = 4000) -> str:
+    """The minimal context bundle for working on one component."""
+    try:
+        bundle = build_pack(read_specs(index_dir), component_id, budget=budget)
+    except KeyError:
+        return f"unknown component: {component_id}"
+    return render_pack(bundle)
+
+
+def tool_search(index_dir: Path, query: str) -> str:
+    """Components whose id, entrypoint, or effects match a substring."""
+    needle = query.lower()
+    hits: list[str] = []
+    for spec in read_specs(index_dir):
+        haystack = " ".join([spec.id, spec.entrypoint or "", " ".join(spec.effects)]).lower()
+        if needle in haystack:
+            line = f"{spec.id}  [{spec.kind.value}]"
+            if spec.entrypoint:
+                line += f"  ({spec.entrypoint})"
+            hits.append(line)
+    if not hits:
+        return f"no components match {query!r}"
+    return "\n".join(hits) + "\n"
+
+
+def tool_entrypoints(index_dir: Path) -> str:
+    """The repo's external surface: HTTP routes, CLI commands, tasks."""
+    entries = [s for s in read_specs(index_dir) if s.entrypoint]
+    if not entries:
+        return "no entrypoints detected"
+    entries.sort(key=lambda s: (s.entrypoint or "", s.id))
+    return "\n".join(f"{s.entrypoint}  {s.id}" for s in entries) + "\n"
+
+
+def tool_verify(index_dir: Path, repo: Path, component_id: str, candidate: str) -> str:
+    """Contract-check a candidate implementation before proposing it."""
+    from cgir.verify import verify
+
+    try:
+        result = verify(index_dir, component_id, candidate, repo)
+    except KeyError:
+        return f"unknown component: {component_id}"
+    lines = [f"contract: {'ok' if result.contract_ok else 'CHANGED'}"]
+    for name, values in result.drift.items():
+        lines.append(f"  {name}: {values['old']} -> {values['new']}")
+    return "\n".join(lines) + "\n"
+
+
+def create_server(index_dir: Path) -> Any:
+    """Build the FastMCP server (requires the ``cgir[mcp]`` extra)."""
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:
+        raise RuntimeError(
+            "Install cgir[mcp] to serve the index over MCP (adds the mcp package)"
+        ) from exc
+
+    server = FastMCP("cgir")
+
+    @server.tool()
+    def stats() -> str:
+        """Codebase structure report: kinds, purity, effects, hotspots."""
+        return tool_stats(index_dir)
+
+    @server.tool()
+    def component(component_id: str) -> str:
+        """Get one ComponentSpec (contract: inputs/outputs/effects/calls) as JSON."""
+        return tool_component(index_dir, component_id)
+
+    @server.tool()
+    def flow(component_id: str, depth: int = 3) -> str:
+        """Trace a component: upstream callers and downstream callees."""
+        return tool_flow(index_dir, component_id, depth)
+
+    @server.tool()
+    def impact(component_id: str) -> str:
+        """Before editing a component, see its blast radius: which callers are affected,
+        which entrypoints are at risk, and exactly which tests to run."""
+        return tool_impact(index_dir, component_id)
+
+    @server.tool()
+    def impact_of_change(repo: str, component_id: str, candidate: str) -> str:
+        """After drafting an edit, see its *narrowed* blast radius: the contract delta
+        your candidate causes and only the callers/entrypoints/tests that delta reaches."""
+        return tool_impact_of_change(index_dir, Path(repo), component_id, candidate)
+
+    @server.tool()
+    def pack(component_id: str, budget: int = 4000) -> str:
+        """Minimal context bundle (spec, callee interfaces, callers) for editing a component."""
+        return tool_pack(index_dir, component_id, budget)
+
+    @server.tool()
+    def search(query: str) -> str:
+        """Find components by id / entrypoint / effect substring."""
+        return tool_search(index_dir, query)
+
+    @server.tool()
+    def entrypoints() -> str:
+        """The repo's external surface: HTTP routes, CLI commands, tasks."""
+        return tool_entrypoints(index_dir)
+
+    @server.tool()
+    def verify(repo: str, component_id: str, candidate: str) -> str:
+        """Contract-check a candidate implementation of a component before proposing it."""
+        return tool_verify(index_dir, Path(repo), component_id, candidate)
+
+    return server

cgir/api/server.py

@@ -0,0 +1,107 @@
+"""FastAPI surface over the scan pipeline.
+
+Only available with ``pip install cgir[api]``. Per ``docs/roadmap.md``,
+the API is a thin surface over the same driver the CLI uses
+(:func:`cgir.pipeline.scan_repo`) — no separate pipeline.
+
+The app is bound to an index directory (default ``.cgir``); a successful
+``POST /scan`` re-points it at the freshly written index. Reads against a
+missing index answer 409 rather than 404 so "no scan yet" is
+distinguishable from "unknown component".
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from cgir.export.json_export import read_specs
+from cgir.pipeline import scan_repo
+from cgir.regenerate import regenerate as run_regenerate
+from cgir.report.stats import compute_stats
+from cgir.trace import TraceMap
+
+
+class ScanRequest(BaseModel):
+    repo: str
+    out: str | None = None
+    exclude: list[str] = []
+
+
+class RegenerateRequest(BaseModel):
+    component_id: str
+    lang: str = "typescript"
+
+
+def create_app(index_dir: Path | None = None) -> Any:
+    try:
+        from fastapi import FastAPI, HTTPException
+    except ImportError as exc:
+        raise RuntimeError("Install cgir[api] to use the HTTP surface") from exc
+
+    app = FastAPI(title="CGIR", version="0.1.0")
+    state: dict[str, Path] = {"index_dir": index_dir or Path(".cgir")}
+
+    def _index() -> Path:
+        current = state["index_dir"]
+        if not (current / "components").is_dir():
+            raise HTTPException(status_code=409, detail=f"No index at {current}; POST /scan first")
+        return current
+
+    def _spec_path(component_id: str) -> Path:
+        path = _index() / "components" / f"{component_id}.json"
+        if not path.exists():
+            raise HTTPException(status_code=404, detail=f"Unknown component: {component_id}")
+        return path
+
+    @app.post("/scan")
+    def scan(req: ScanRequest) -> dict[str, Any]:
+        repo = Path(req.repo)
+        if not repo.is_dir():
+            raise HTTPException(status_code=400, detail=f"Not a directory: {repo}")
+        result = scan_repo(repo, Path(req.out) if req.out else None, req.exclude)
+        state["index_dir"] = result.out_dir
+        return {"out_dir": str(result.out_dir), "components": len(result.specs)}
+
+    @app.get("/components")
+    def list_components() -> list[dict[str, Any]]:
+        index_path = _index() / "components_index.json"
+        entries: list[dict[str, Any]] = json.loads(index_path.read_text())
+        return entries
+
+    @app.get("/components/{component_id}")
+    def get_component(component_id: str) -> dict[str, Any]:
+        payload: dict[str, Any] = json.loads(_spec_path(component_id).read_text())
+        return payload
+
+    @app.get("/trace")
+    def trace(path: str, line: int) -> dict[str, str]:
+        trace_path = _index() / "trace_map.json"
+        if not trace_path.exists():
+            raise HTTPException(status_code=409, detail=f"No trace map at {trace_path}")
+        hit = TraceMap.read(trace_path).lookup(path, line)
+        if hit is None:
+            raise HTTPException(status_code=404, detail=f"No component covers {path}:{line}")
+        return {"component_id": hit}
+
+    @app.post("/regenerate")
+    def regenerate(req: RegenerateRequest) -> dict[str, str]:
+        from cgir.ir.component_spec import ComponentSpec
+
+        spec = ComponentSpec.from_dict(json.loads(_spec_path(req.component_id).read_text()))
+        result = run_regenerate(spec, req.lang)
+        return {
+            "component_id": result.spec_id,
+            "lang": result.target_language,
+            "prompt": result.prompt,
+            "code": result.code,
+        }
+
+    @app.get("/stats")
+    def stats() -> dict[str, Any]:
+        return compute_stats(read_specs(_index()))
+
+    return app