codegraph-ir 0.1.0__py3-none-any.whl

cgir/manifest.py

@@ -0,0 +1,77 @@
+"""Index manifest — provenance + compatibility for a written index.
+
+Every index carries a ``manifest.json`` recording which ``cgir`` version
+and ComponentSpec schema version produced it. ``cgir diff`` (and any tool
+comparing two indexes, e.g. the CI Action) reads both manifests so a
+base/head comparison produced by *different* cgir versions is a warning,
+not a silent wrong answer.
+
+``SCHEMA_VERSION`` bumps whenever the ComponentSpec contract changes shape
+(a field added/removed/repurposed). It is independent of ``cgir.__version__``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from cgir import __version__
+
+SCHEMA_VERSION = "1.0"
+MANIFEST_NAME = "manifest.json"
+
+
+@dataclass(slots=True)
+class Manifest:
+    cgir_version: str
+    schema_version: str
+    component_count: int
+    created_at: str
+
+    @classmethod
+    def create(cls, component_count: int) -> Manifest:
+        return cls(
+            cgir_version=__version__,
+            schema_version=SCHEMA_VERSION,
+            component_count=component_count,
+            created_at=datetime.now(UTC).isoformat(),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def write_manifest(index_dir: Path, component_count: int) -> Manifest:
+    index_dir.mkdir(parents=True, exist_ok=True)
+    manifest = Manifest.create(component_count)
+    (index_dir / MANIFEST_NAME).write_text(json.dumps(manifest.to_dict(), indent=2, sort_keys=True))
+    return manifest
+
+
+def read_manifest(index_dir: Path) -> Manifest | None:
+    """Load an index's manifest, or None for a pre-manifest (old) index."""
+    path = index_dir / MANIFEST_NAME
+    if not path.exists():
+        return None
+    data = json.loads(path.read_text())
+    return Manifest(
+        cgir_version=str(data.get("cgir_version", "unknown")),
+        schema_version=str(data.get("schema_version", "unknown")),
+        component_count=int(data.get("component_count", 0)),
+        created_at=str(data.get("created_at", "")),
+    )
+
+
+def compatibility_warning(old: Manifest | None, new: Manifest | None) -> str | None:
+    """A human-readable warning if two indexes may not be safely comparable."""
+    old_schema = old.schema_version if old else "unknown"
+    new_schema = new.schema_version if new else "unknown"
+    if old_schema != new_schema:
+        return (
+            f"warning: schema version mismatch ({old_schema} vs {new_schema}); "
+            "diff may be unreliable — rescan both with the same cgir version"
+        )
+    return None

cgir/pipeline.py

@@ -0,0 +1,54 @@
+"""The scan pipeline — single driver shared by the CLI and the HTTP API.
+
+Pipeline order is fixed by the spec:
+``ingest → symbols → call_graph → cfg → pdg → effects → purity → slice →
+export``. New analyses wire in here (see ``CLAUDE.md`` working
+conventions); the CLI and API are thin surfaces over :func:`scan_repo`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from cgir.analyses import effects as effects_pass
+from cgir.analyses import purity as purity_pass
+from cgir.analyses.call_graph import build_call_graph
+from cgir.analyses.cfg import build as build_cfg
+from cgir.analyses.pdg import build as build_pdg
+from cgir.analyses.symbols import build_symbol_tables
+from cgir.config import CGIRConfig
+from cgir.export import json_export
+from cgir.ir.component_spec import ComponentSpec
+from cgir.slicing import slice_components
+from cgir.sources import TreeSitterSource
+from cgir.trace import build_trace_map
+
+
+@dataclass(slots=True)
+class ScanResult:
+    out_dir: Path
+    specs: list[ComponentSpec]
+
+
+def scan_repo(
+    repo: Path,
+    out: Path | None = None,
+    exclude: Iterable[str] | None = None,
+) -> ScanResult:
+    """Run the full pipeline over ``repo`` and write the index to disk."""
+    config = CGIRConfig.for_scan(repo, out)
+    source = TreeSitterSource(ignore_dirs=set(exclude or ()))
+    graph = source.ingest(config.repo_path)
+    tables = build_symbol_tables(graph)
+    build_call_graph(graph, tables, config.repo_path)
+    build_cfg(graph, config.repo_path)
+    build_pdg(graph)
+    effects = effects_pass.classify(graph, config.repo_path)
+    purity_scores = purity_pass.score(graph, effects)
+    specs = slice_components(graph, effects=effects, purity_scores=purity_scores)
+    trace_map = build_trace_map(graph)
+    json_export.write_index(config.out_dir, graph, specs)
+    trace_map.write(config.out_dir / "trace_map.json")
+    return ScanResult(out_dir=config.out_dir, specs=specs)

cgir/regenerate/__init__.py

@@ -0,0 +1,6 @@
+"""Prompt-pack + regeneration. The LLM call is an injectable generator seam."""
+
+from cgir.regenerate.prompt_pack import build_prompt
+from cgir.regenerate.regenerator import regenerate
+
+__all__ = ["build_prompt", "regenerate"]

cgir/regenerate/prompt_pack.py

@@ -0,0 +1,16 @@
+"""Render the prompt-pack template from Code-IR.md §Analysis/workflow."""
+
+from __future__ import annotations
+
+from cgir.ir.component_spec import ComponentSpec
+
+PROMPT_TEMPLATE = (
+    "Given ComponentSpec + dependent interfaces + tests, recreate this component in "
+    "{target_language}. Preserve contracts, effects, and trace IDs. Do not invent "
+    "hidden dependencies.\n\n"
+    "ComponentSpec:\n{spec_json}\n"
+)
+
+
+def build_prompt(spec: ComponentSpec, target_language: str) -> str:
+    return PROMPT_TEMPLATE.format(target_language=target_language, spec_json=spec.to_json())

cgir/regenerate/regenerator.py

@@ -0,0 +1,108 @@
+"""LLM-driven regeneration.
+
+The generation seam is an injectable ``Callable[[str], str]`` so the
+pipeline stays testable offline — only :func:`anthropic_generator` touches
+the network, and only when explicitly requested (``cgir regenerate
+--live``). Per the spec, the LLM sees the prompt-pack built from the
+``ComponentSpec``, never raw source.
+
+Round-tripping generated code through compile/test verification before
+tagging ``REGENERATED_AS`` edges is future work — the result carries
+``live`` so callers can tell a real generation from a dry run.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from cgir.ir.component_spec import ComponentSpec
+from cgir.regenerate.prompt_pack import build_prompt
+
+DEFAULT_MODEL = "claude-sonnet-4-6"
+
+_SYSTEM_PROMPT = (
+    "You are a code regeneration engine. You receive a ComponentSpec (a "
+    "language-agnostic contract for one component: inputs, effects, calls, "
+    "purity, trace IDs) and produce an implementation in the requested "
+    "target language. Respond with code only — no prose, no fences."
+)
+
+_DRY_RUN_NOTE = (
+    "// dry run: no generator supplied.\n"
+    "// Pass --live (requires `pip install cgir[llm]` and ANTHROPIC_API_KEY)\n"
+    "// or inject a generator callable to produce code.\n"
+)
+
+
+@dataclass(slots=True)
+class RegenerationResult:
+    spec_id: str
+    target_language: str
+    prompt: str
+    code: str
+    live: bool = False
+
+
+def regenerate(
+    spec: ComponentSpec,
+    target_language: str,
+    generator: Callable[[str], str] | None = None,
+) -> RegenerationResult:
+    """Build the prompt-pack for ``spec`` and (optionally) generate code.
+
+    Without a ``generator`` this is a dry run: the prompt is returned for
+    inspection and ``code`` explains how to go live.
+    """
+    prompt = build_prompt(spec, target_language)
+    if generator is None:
+        return RegenerationResult(
+            spec_id=spec.id,
+            target_language=target_language,
+            prompt=prompt,
+            code=_DRY_RUN_NOTE,
+            live=False,
+        )
+    return RegenerationResult(
+        spec_id=spec.id,
+        target_language=target_language,
+        prompt=prompt,
+        code=generator(prompt),
+        live=True,
+    )
+
+
+def anthropic_generator(model: str | None = None) -> Callable[[str], str]:
+    """A generator backed by the Anthropic SDK (``pip install cgir[llm]``).
+
+    The system prompt is marked for prompt caching from day one (see
+    ``docs/roadmap.md``). Model defaults to :data:`DEFAULT_MODEL`; override
+    with the ``CGIR_MODEL`` environment variable or the ``model`` argument.
+    """
+    try:
+        import anthropic
+    except ImportError as exc:
+        raise RuntimeError(
+            "Install cgir[llm] to use live regeneration (adds the anthropic package)"
+        ) from exc
+
+    client = anthropic.Anthropic()
+    resolved_model = model or os.environ.get("CGIR_MODEL", DEFAULT_MODEL)
+
+    def generate(prompt: str) -> str:
+        message = client.messages.create(
+            model=resolved_model,
+            max_tokens=4096,
+            system=[
+                {
+                    "type": "text",
+                    "text": _SYSTEM_PROMPT,
+                    "cache_control": {"type": "ephemeral"},
+                }
+            ],
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return "".join(block.text for block in message.content if block.type == "text")
+
+    return generate

cgir/report/__init__.py

@@ -0,0 +1,5 @@
+"""Human-facing reports derived from ComponentSpecs."""
+
+from cgir.report.stats import compute_stats
+
+__all__ = ["compute_stats"]

cgir/report/diff.py

@@ -0,0 +1,226 @@
+"""Index diff — architecture drift between two scans (Sprint 16).
+
+``compute_diff`` is pure over two spec lists (same pattern as
+:mod:`cgir.report.stats`): which components appeared, disappeared, or
+changed on the *contract* fields — kind, purity, effects, signature,
+outputs. ``violations`` evaluates CI fail rules against a diff, so
+"this PR made a pure function effectful" — or silently dropped a network
+call — can fail a build:
+
+    cgir diff old-index new-index --fail-on effect-gain:net --fail-on effect-loss:net
+
+Rules only fire for components present in *both* scans — new effectful
+code is a choice, drift in existing code is a regression.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cgir.ir.component_spec import ComponentSpec
+
+CONTRACT_FIELDS = ("kind", "purity", "effects", "signature", "outputs")
+
+
+def compute_diff(old_specs: list[ComponentSpec], new_specs: list[ComponentSpec]) -> dict[str, Any]:
+    old = {s.id: s for s in old_specs}
+    new = {s.id: s for s in new_specs}
+
+    changed: list[dict[str, Any]] = []
+    for spec_id in sorted(old.keys() & new.keys()):
+        fields = _field_changes(old[spec_id], new[spec_id])
+        if fields:
+            changed.append({"id": spec_id, "fields": fields})
+
+    return {
+        "added": sorted(new.keys() - old.keys()),
+        "removed": sorted(old.keys() - new.keys()),
+        "changed": changed,
+        "entrypoints": _entrypoint_surface(old, new),
+    }
+
+
+def _entrypoint_surface(
+    old: dict[str, ComponentSpec], new: dict[str, ComponentSpec]
+) -> dict[str, list[dict[str, Any]]]:
+    """The externally-reachable surface that appeared, vanished, or moved."""
+    added = [
+        {"id": sid, "entrypoint": new[sid].entrypoint}
+        for sid in sorted(new.keys() - old.keys())
+        if new[sid].entrypoint
+    ]
+    removed = [
+        {"id": sid, "entrypoint": old[sid].entrypoint}
+        for sid in sorted(old.keys() - new.keys())
+        if old[sid].entrypoint
+    ]
+    changed = [
+        {"id": sid, "old": old[sid].entrypoint, "new": new[sid].entrypoint}
+        for sid in sorted(old.keys() & new.keys())
+        if old[sid].entrypoint != new[sid].entrypoint
+    ]
+    return {"added": added, "removed": removed, "changed": changed}
+
+
+def _field_changes(old: ComponentSpec, new: ComponentSpec) -> dict[str, dict[str, Any]]:
+    fields: dict[str, dict[str, Any]] = {}
+    for name in CONTRACT_FIELDS:
+        old_value = getattr(old, name)
+        new_value = getattr(new, name)
+        if name == "kind":
+            old_value, new_value = old_value.value, new_value.value
+        if old_value != new_value:
+            fields[name] = {"old": old_value, "new": new_value}
+    return fields
+
+
+def violations(diff: dict[str, Any], rules: list[str]) -> list[str]:
+    """Evaluate fail rules against a diff; each hit is a human-readable line."""
+    found: list[str] = []
+    for change in diff["changed"]:
+        fields = change["fields"]
+        spec_id = change["id"]
+        for rule in rules:
+            if rule.startswith("effect-gain"):
+                _, _, wanted = rule.partition(":")
+                gained = _gained_effects(fields)
+                if wanted:
+                    gained = [t for t in gained if t == wanted]
+                if gained:
+                    found.append(f"{spec_id}: gained effect(s) {', '.join(gained)}")
+            elif rule.startswith("effect-loss"):
+                _, _, wanted = rule.partition(":")
+                lost = _lost_effects(fields)
+                if wanted:
+                    lost = [t for t in lost if t == wanted]
+                # Indirection, not removal: if the component *simultaneously*
+                # gained calls_effectful, the effect most likely moved behind a
+                # call and is still transitively reachable (the one false-alarm
+                # class in the real-history noise replay — see gate-noise.md).
+                # Trade-off: a true removal paired with a new unrelated
+                # effectful call is masked; the loss stays visible in the diff
+                # report, it just doesn't fail the build.
+                if lost and "calls_effectful" in _gained_effects(fields):
+                    lost = []
+                if lost:
+                    found.append(f"{spec_id}: lost effect(s) {', '.join(lost)}")
+            elif rule == "purity-drop":
+                purity = fields.get("purity")
+                if purity and _as_float(purity["new"]) < _as_float(purity["old"]):
+                    found.append(f"{spec_id}: purity dropped {purity['old']} -> {purity['new']}")
+            elif rule == "kind-change":
+                kind = fields.get("kind")
+                if kind:
+                    found.append(f"{spec_id}: kind changed {kind['old']} -> {kind['new']}")
+    surface = diff.get("entrypoints", {})
+    for rule in rules:
+        if rule == "entrypoint-added":
+            for e in surface.get("added", []):
+                found.append(f"{e['id']}: new entrypoint {e['entrypoint']}")
+        elif rule == "entrypoint-change":
+            for e in surface.get("changed", []):
+                found.append(f"{e['id']}: entrypoint changed {e['old']} -> {e['new']}")
+    return found
+
+
+def _gained_effects(fields: dict[str, dict[str, Any]]) -> list[str]:
+    effects = fields.get("effects")
+    if not effects:
+        return []
+    return sorted(set(effects["new"]) - set(effects["old"]))
+
+
+def _lost_effects(fields: dict[str, dict[str, Any]]) -> list[str]:
+    effects = fields.get("effects")
+    if not effects:
+        return []
+    return sorted(set(effects["old"]) - set(effects["new"]))
+
+
+def _as_float(value: Any) -> float:
+    return float(value) if value is not None else 0.0
+
+
+def render_diff(diff: dict[str, Any]) -> str:
+    surface = diff.get("entrypoints", {"added": [], "removed": [], "changed": []})
+    has_surface = surface["added"] or surface["removed"] or surface["changed"]
+    if not (diff["added"] or diff["removed"] or diff["changed"] or has_surface):
+        return "no changes\n"
+    lines: list[str] = []
+    if has_surface:
+        lines.append("entrypoint surface:")
+        lines.extend(f"  + {e['entrypoint']}  ({e['id']})" for e in surface["added"])
+        lines.extend(f"  - {e['entrypoint']}  ({e['id']})" for e in surface["removed"])
+        lines.extend(f"  ~ {e['old']} -> {e['new']}  ({e['id']})" for e in surface["changed"])
+    if diff["added"]:
+        lines.append(f"added ({len(diff['added'])}):")
+        lines.extend(f"  + {spec_id}" for spec_id in diff["added"])
+    if diff["removed"]:
+        lines.append(f"removed ({len(diff['removed'])}):")
+        lines.extend(f"  - {spec_id}" for spec_id in diff["removed"])
+    if diff["changed"]:
+        lines.append(f"changed ({len(diff['changed'])}):")
+        for change in diff["changed"]:
+            lines.append(f"  ~ {change['id']}")
+            for name, values in change["fields"].items():
+                lines.append(f"      {name}: {values['old']} -> {values['new']}")
+    return "\n".join(lines) + "\n"
+
+
+def render_diff_markdown(
+    diff: dict[str, Any],
+    violations: list[str] | None = None,
+    warning: str | None = None,
+) -> str:
+    """A PR-comment-ready markdown report of an index diff."""
+    surface = diff.get("entrypoints", {"added": [], "removed": [], "changed": []})
+    has_surface = bool(surface["added"] or surface["removed"] or surface["changed"])
+    has_any = bool(diff["added"] or diff["removed"] or diff["changed"] or has_surface)
+
+    out: list[str] = ["## 🔍 CGIR contract diff", ""]
+    if warning:
+        out += [f"> ⚠️ {warning}", ""]
+    if not has_any:
+        out.append("✅ No contract changes.")
+        return "\n".join(out) + "\n"
+
+    if violations:
+        out.append(f"> ❌ **{len(violations)} drift violation(s)** — gate failed:")
+        out += [f"> - {line}" for line in violations]
+        out.append("")
+
+    if has_surface:
+        out += ["### Entrypoint surface", ""]
+        out += [f"- 🟢 `{e['entrypoint']}` — new (`{e['id']}`)" for e in surface["added"]]
+        out += [f"- 🔴 `{e['entrypoint']}` — removed (`{e['id']}`)" for e in surface["removed"]]
+        out += [f"- 🟡 `{e['old']}` → `{e['new']}` (`{e['id']}`)" for e in surface["changed"]]
+        out.append("")
+
+    if diff["changed"]:
+        out += [f"### Contract drift ({len(diff['changed'])})", ""]
+        for change in diff["changed"]:
+            out.append(f"<details><summary><code>{change['id']}</code></summary>")
+            out += ["", "| field | before | after |", "|---|---|---|"]
+            for name, values in change["fields"].items():
+                old_v = _md_cell(values["old"])
+                new_v = _md_cell(values["new"])
+                out.append(f"| {name} | {old_v} | {new_v} |")
+            out += ["", "</details>", ""]
+
+    counts = []
+    if diff["added"]:
+        counts.append(f"**{len(diff['added'])}** added")
+    if diff["removed"]:
+        counts.append(f"**{len(diff['removed'])}** removed")
+    if counts:
+        out.append(" · ".join(counts))
+
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _md_cell(value: Any) -> str:
+    if value is None or value == [] or value == "":
+        return "—"
+    if isinstance(value, list):
+        return ", ".join(f"`{v}`" for v in value)
+    return f"`{value}`"

cgir/report/flow.py

@@ -0,0 +1,84 @@
+"""Component flow tracing — who calls it, what it calls, what it builds.
+
+``render_flow`` is pure over ComponentSpecs (same pattern as
+:mod:`cgir.report.stats`): upstream callers and downstream callees as
+depth-limited trees, each node annotated with kind, effects, and the
+declared return type. Cycles are marked and not re-expanded.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from cgir.ir.component_spec import ComponentSpec
+
+DEFAULT_DEPTH = 3
+
+
+def render_flow(specs: list[ComponentSpec], root_id: str, depth: int = DEFAULT_DEPTH) -> str:
+    by_id = {s.id: s for s in specs}
+    if root_id not in by_id:
+        raise KeyError(root_id)
+
+    callers: dict[str, list[str]] = {}
+    for spec in specs:
+        for callee in spec.calls:
+            if callee in by_id:
+                callers.setdefault(callee, []).append(spec.id)
+
+    def upstream(node_id: str) -> list[str]:
+        return sorted(callers.get(node_id, []))
+
+    def downstream(node_id: str) -> list[str]:
+        return [c for c in by_id[node_id].calls if c in by_id]
+
+    lines: list[str] = [_describe(by_id[root_id]), ""]
+    lines.append("called by (upstream):")
+    _walk(root_id, upstream, by_id, lines, "<-", depth, indent=1, seen={root_id})
+    lines.append("")
+    lines.append("calls (downstream):")
+    _walk(root_id, downstream, by_id, lines, "->", depth, indent=1, seen={root_id})
+    root_constructs = by_id[root_id].constructs
+    if root_constructs:
+        lines.append("")
+        lines.append("constructs:")
+        for type_name in root_constructs:
+            lines.append(f"  + {type_name}")
+    return "\n".join(lines) + "\n"
+
+
+def _walk(
+    node_id: str,
+    next_ids: Callable[[str], list[str]],
+    by_id: dict[str, ComponentSpec],
+    lines: list[str],
+    arrow: str,
+    depth: int,
+    indent: int,
+    seen: set[str],
+) -> None:
+    children = next_ids(node_id)
+    if not children and indent == 1:
+        lines.append("  (none)")
+        return
+    for child in children:
+        pad = "  " * indent
+        if child in seen:
+            lines.append(f"{pad}{arrow} {child}  (cycle)")
+            continue
+        lines.append(f"{pad}{arrow} {_describe(by_id[child])}")
+        if indent < depth:
+            _walk(child, next_ids, by_id, lines, arrow, depth, indent + 1, seen | {child})
+
+
+def _describe(spec: ComponentSpec) -> str:
+    parts = [spec.id, f"[{spec.kind.value}"]
+    effects = [e for e in spec.effects if e != "calls_effectful"]
+    if effects:
+        parts[-1] += " · " + ",".join(effects)
+    parts[-1] += "]"
+    if spec.outputs:
+        parts.append(f"-> {spec.outputs[0]}")
+    if spec.entrypoint:
+        parts.append(f"({spec.entrypoint})")
+    return "  ".join(parts)