codegraph-ir 0.1.0__tar.gz → 0.2.1__tar.gz

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/.github/workflows/release.yml

@@ -7,7 +7,9 @@ name: release
 
 on:
   push:
-    tags: ["v*"]
+    # Version tags only — the floating `v0` Action-convenience tag must not
+    # trigger a release (its stripped form never matches __version__).
+    tags: ["v[0-9]+.[0-9]+.[0-9]+*"]
 
 jobs:
   build:

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/Code-IR.md

@@ -55,10 +55,15 @@ H --> I[LLM regenerate / test / trace]
 "inputs":{"type":"array","items":{"type":"string"}},"outputs":{"type":"array","items":{"type":"string"}},
 "effects":{"type":"array","items":{"type":"string"}},"calls":{"type":"array","items":{"type":"string"}},
 "reads":{"type":"array","items":{"type":"string"}},"writes":{"type":"array","items":{"type":"string"}},
-"purity":{"type":"number"},"algorithm":{"type":"array","items":{"type":"string"}},
+"purity":{"type":"number"},"pins":{"type":"array","items":{"type":"string"}},
+"algorithm":{"type":"array","items":{"type":"string"}},
 "trace":{"type":"array","items":{"type":"string"}}}}
 ```
 
+`pins` are developer-declared invariants extracted from `cgir:` comment
+pragmas (`pure`, `no-<tag>`, `stable-signature`, `frozen`): state pins hold on
+every scan; change pins hold across scan pairs and are always enforced.
+
 **Example Python → ComponentSpec**
 ```python
 def add_tax(price: float, rate: float) -> float: return price * (1 + rate)

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-ir
-Version: 0.1.0
+Version: 0.2.1
 Summary: The deterministic contract layer for AI-modified codebases — effects, purity, contracts, and blast radius, with zero LLM calls.
 Project-URL: Homepage, https://github.com/asonkiya/llm-semantic-compilers
 Project-URL: Repository, https://github.com/asonkiya/llm-semantic-compilers
@@ -43,6 +43,7 @@ Requires-Python: >=3.11
 Requires-Dist: jsonschema>=4.21
 Requires-Dist: networkx>=3.2
 Requires-Dist: pydantic>=2.6
+Requires-Dist: tree-sitter-go<0.25,>=0.23
 Requires-Dist: tree-sitter-python<0.24,>=0.23
 Requires-Dist: tree-sitter-typescript<0.24,>=0.23
 Requires-Dist: tree-sitter<0.25,>=0.23
@@ -89,7 +90,7 @@ For library/agent use in a project: `uv pip install codegraph-ir`
 ## The local loop
 
 ```bash
-cgir scan .                          # build the .cgir index (Python + TypeScript)
+cgir scan .                          # build the .cgir index (Python, TypeScript, Go)
 cgir watch .                         # keep it live: re-scan + show contract drift on save
 cgir pack app.service.charge --repo .   # minimal context bundle for one component
 cgir impact app.service.charge          # blast radius: affected callers, entrypoints, tests

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/README.md

@@ -23,7 +23,7 @@ For library/agent use in a project: `uv pip install codegraph-ir`
 ## The local loop
 
 ```bash
-cgir scan .                          # build the .cgir index (Python + TypeScript)
+cgir scan .                          # build the .cgir index (Python, TypeScript, Go)
 cgir watch .                         # keep it live: re-scan + show contract drift on save
 cgir pack app.service.charge --repo .   # minimal context bundle for one component
 cgir impact app.service.charge          # blast radius: affected callers, entrypoints, tests

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/docs/languages.md

@@ -27,6 +27,7 @@ full test suite green.
 | 2 | CFG statement classification + field extraction (normalized `StatementDesc`) | ✅ done |
 | 3 | ingest structural dispatch + attr extraction (normalized `Declaration`s) | ✅ done |
 | 4 | `TypeScriptAdapter` + per-file language dispatch | ✅ done |
+| 5 | `GoAdapter` (package=directory merge, struct-field DI, panic≙raise) | ✅ done |
 
 **Two languages ship (Python, TypeScript); a mixed repo scans both.**
 Zero grammar node-type strings remain outside `cgir/languages/`. The CFG builder is pure topology over statement

codegraph_ir-0.2.1/docs/plan-0.2-0.4.md

@@ -0,0 +1,109 @@
+# Plan: 0.2 → 0.4 (pins, init, impact --run; data-shape contracts; Go)
+
+**Status: all three workstreams landed 2026-07-10** (single sitting; see git
+log). Shipping as one 0.2.0 release rather than three.
+
+Three workstreams, landed in this order — each one's machinery feeds the next.
+Depth before width: pins + shapes strengthen the gate for the two languages
+people can use today; Go then inherits all of it.
+
+## Workstream A — "Make it personal" (→ 0.2.0)
+
+### A1. Declarable contracts (pins)
+
+Comment pragmas pinning *intent*, enforced everywhere the pipeline runs:
+
+```python
+# cgir: pure
+def score(events): ...        # trailing form also supported
+```
+
+Module-level pins at top of file apply to every component in it.
+
+Pins split into two classes with different checkers:
+
+| pin | class | meaning | checked by |
+|---|---|---|---|
+| `pure` | state (single scan) | kind pure_function, no impure effects incl. transitive | lint, watch |
+| `no-<tag>` | state | tag not in transitive effects (closure over spec.calls) | lint, watch |
+| `stable-signature` | change (scan pair) | signature/outputs may not change | diff, hook, verify, CI |
+| `frozen` | change | no contract field may change; removal is a violation | diff, hook, verify, CI |
+
+Change pins are always evaluated — the pin is the opt-in, no --fail-on needed.
+State pins catch violations in newly added code too (drift rules can't).
+
+Design: new `report/pins.py` with `state_violations(specs)` and
+`change_violations(old, new)` — pure over specs; transitive effects computed
+by closure over `spec.calls` (no schema change beyond the `pins` field).
+Wire into lint, the diff CLI, hook, verify; pack renders `Pinned: ...` in the
+target header so rewriting agents see the invariant.
+
+Plumbing: adapter pragma extraction (generic row-based helper over tree-sitter
+`comment` nodes; `#` / `//` prefixes) → FunctionDecl.pins → node attrs →
+`pins: list[str]` on ComponentSpec (schema in both places + Code-IR.md).
+
+Honest limit: a pin is only as strong as effect detection (lexical escapes per
+status.md). Confidence tiers are the future systematic fix.
+
+### A2. `cgir init`
+
+One-command onboarding: scan → print "what your repo is" (histogram,
+entrypoints, untested-effectful) → write starter `cgir.toml` (never clobbers
+without --force) → `--hook` installs the seatbelt → append `.cgir/` to
+.gitignore → print MCP + Action next-steps.
+
+### A3. `cgir impact --run`
+
+Execute the impact test list: qualname + trace path → pytest nodeid
+(`path::Class::test_x`), subprocess, propagate exit code. Filter to
+pytest-collectable names (covered_by can include fixture helpers). v1 runs
+pytest only; TS prints the command (runner detection is v1.1).
+
+## Workstream C — Data-shape contracts (→ 0.3.0)
+
+"The rewrite dropped a field from the returned object" becomes drift — the
+residual failure class in both benchmarks.
+
+The DI work already built the foundation: `ClassDecl.fields` (name → type)
+exists in both adapters, and Python's annotated-class-body extraction already
+covers TypedDict/dataclass/pydantic. Additions:
+
+- TS: `interface_declaration` / object type-alias members → ClassDecl.fields.
+- Shape lives on the *type* (Class node), not a new spec field. `compute_diff`
+  gains a `types` section (added/removed/changed fields per type qualname),
+  with `referenced_by` computed via `referenced_type_names` over specs.
+- New violation rule `shape-change`: fires when a drifted type is referenced
+  in any component's outputs/inputs.
+- ScanResult carries `types`; diff CLI reads them from repo_graph.json; hook
+  and verify inherit.
+
+v1 exclusions (stated): inheritance (base-class fields), un-annotated
+dict-literal returns (literal-key fingerprints v1.1), Optional/default
+subtleties beyond the annotation text.
+
+## Workstream B — Go adapter (→ 0.4.0)
+
+Lands after C so GoAdapter implements fields/shape extraction as part of its
+contract rather than retrofitting.
+
+- package = directory; `type X struct/interface` → Class (struct members →
+  fields — Go composition maps directly onto the DI machinery); method
+  receivers attach methods to the receiver's Class; `raise` ≙ `panic(` only
+  (Go errors are values).
+- Effects: net (net/http), fs (os.*), db (database/sql receivers ×
+  Query/Exec), io (fmt.Print*/log.*), nondeterm (time.Now/rand/uuid).
+- Same-package cross-file calls (no import in Go): symbol tables for go
+  modules sharing a directory are merged (keyed on the module language attr).
+- v1 known limits (documented): cross-package import resolution needs go.mod
+  module-prefix stripping (follow-up); struct-in-one-file/methods-in-another
+  weakens field DI; `select`/`defer` CFG ordering approximated; `go f()` is a
+  call site (future concurrency-effect hook).
+- Validation ritual: fixture tests mirroring the TS suite, scan a real OSS Go
+  repo, byte-identical self-diff on Python/TS indexes.
+
+## Cross-cutting
+
+Every spec-vocabulary change updates Code-IR.md §Data model + both schema
+locations + a schema test. Red-green throughout. Each workstream ships as a
+minor release (0.2.0, 0.3.0, 0.4.0) — release mechanics are push-button
+(RELEASING.md).

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/docs/roadmap.md

@@ -1,5 +1,7 @@
 # Roadmap
 
+**Active plan: [`plan-0.2-0.4.md`](./plan-0.2-0.4.md)** — pins/init/impact-run (0.2.0), data-shape contracts (0.3.0), Go adapter (0.4.0).
+
 Forward-looking sequencing. The grouping mirrors `Code-IR.md` §Architecture: **P0** is "you can produce a `ComponentSpec`," **P1** is "you can trust it," **P2** is "you can scale it." Within each tier the order below reflects current dependencies, not strict chronology — feel free to interleave when dependencies allow.
 
 ## Done

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/docs/status.md

@@ -66,6 +66,11 @@ cgir scan tests/fixtures/python_sample --out /tmp/cgir-out
 | Python DI field types (`__init__` annotations, class-level annotations, direct construction) → `self.<field>.<method>()` resolution + `self.`/`this.` receiver in packs | done | `src/cgir/languages/python.py:_class_fields`, `cli._call_receivers` |
 | Per-component `language` on specs (multi-language repos) | done | `src/cgir/slicing/slicer.py:_node_language` |
 | Packaging: distribution `codegraph-ir` (import + CLI stay `cgir`), py.typed, tag-triggered PyPI release via trusted publishing | done | `pyproject.toml`, `.github/workflows/release.yml`, `RELEASING.md` |
+| Declarable contracts (`cgir:` pins — pure/no-tag/stable-signature/frozen) enforced by lint/diff/hook/verify; rendered in pack | done | `src/cgir/report/pins.py`, `languages/base.py:PinIndex` |
+| `cgir init` (scan summary, starter cgir.toml, .gitignore, `--hook`) | done | `src/cgir/cli.py:init` |
+| `cgir impact --run` (execute the blast-radius tests via pytest node-ids) | done | `report/impact.py:runnable_selectors` |
+| Data-shape contracts (`types` diff section + opt-in `shape-change` rule; TS interfaces/type-aliases, Py TypedDict/dataclass) | done | `report/diff.py:_type_shape_changes`, `json_export.read_types` |
+| Go adapter (package=dir symbol merge, struct-field DI, panic≙raise, effects tables) | done | `src/cgir/languages/go.py` |
 | Entrypoint recognition (HTTP/CLI/task decorators) | done | `src/cgir/analyses/entrypoints.py` |
 | Context packer (`cgir pack`, budget-aware, type closure + docstrings + raises) | done | `src/cgir/report/pack.py` |
 | Docstring / raises / module-variable extraction | done | `tree_sitter_source._docstring_text`, `_raised_names`, `_add_module_variables` |
@@ -85,7 +90,7 @@ cgir scan tests/fixtures/python_sample --out /tmp/cgir-out
 
 ## Test coverage
 
-`pytest -q` runs 391 tests, all green (the table below lists the load-bearing files; newer suites — `test_impact.py`, `test_watch.py`, `test_hook.py`, `test_python_di.py`, `test_typescript_adapter.py`, `test_diff.py` — are described by their docstrings):
+`pytest -q` runs 444 tests, all green (the table below lists the load-bearing files; newer suites — `test_impact.py`, `test_watch.py`, `test_hook.py`, `test_python_di.py`, `test_typescript_adapter.py`, `test_diff.py` — are described by their docstrings):
 
 | File | Covers |
 |---|---|

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 # Distribution name (the import package and CLI command are both `cgir`;
 # the PyPI project name `cgir` was already taken, so we ship as codegraph-ir).
 name = "codegraph-ir"
-version = "0.1.0"
+version = "0.2.1"
 description = "The deterministic contract layer for AI-modified codebases — effects, purity, contracts, and blast radius, with zero LLM calls."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -43,6 +43,7 @@ dependencies = [
   "tree-sitter>=0.23,<0.25",
   "tree-sitter-python>=0.23,<0.24",
   "tree-sitter-typescript>=0.23,<0.24",
+  "tree-sitter-go>=0.23,<0.25",
   "jsonschema>=4.21",
 ]
 

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/schemas/component_spec.schema.json

@@ -107,6 +107,12 @@
       "items": {
         "type": "string"
       }
+    },
+    "pins": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
     }
   },
   "additionalProperties": false

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/src/cgir/__init__.py

@@ -3,4 +3,4 @@
 See ``Code-IR.md`` at the repo root for the product specification.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/src/cgir/analyses/cfg.py

@@ -79,7 +79,13 @@ def build(graph: RepoGraph, repo_path: Path, adapter: LanguageAdapter | None = N
         body = file_adapter.function_body(func_ts)
         if body is None:
             continue
-        builder = _CFGBuilder(graph=graph, owner=func, source=source, adapter=file_adapter)
+        builder = _CFGBuilder(
+            graph=graph,
+            owner=func,
+            source=source,
+            adapter=file_adapter,
+            global_names=file_adapter.global_declared_names(func_ts, source),
+        )
         builder.build_block(body, predecessors=[func.id], controller=None)
 
 
@@ -89,6 +95,9 @@ class _CFGBuilder:
     owner: Node
     source: bytes
     adapter: LanguageAdapter
+    # names declared global/nonlocal in this function: writes to them mutate
+    # outer state and are recorded as `mutates`, not local `writes`.
+    global_names: set[str] = field(default_factory=set)
     _counter: int = field(default=0, init=False)
 
     def build_block(
@@ -102,6 +111,11 @@ class _CFGBuilder:
 
     def build_stmt(self, ts_node: TSNode, preds: list[str], controller: str | None) -> list[str]:
         desc = self.adapter.describe_statement(ts_node, self.source)
+        if isinstance(desc, AssignDesc) and self.global_names:
+            outer = [w for w in desc.writes if w in self.global_names]
+            if outer:
+                desc.writes = [w for w in desc.writes if w not in self.global_names]
+                desc.mutates = list(desc.mutates) + outer
         if isinstance(desc, BranchDesc):
             return self._build_branch(ts_node, desc, preds, controller)
         if isinstance(desc, LoopDesc):

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/src/cgir/analyses/symbols.py

@@ -41,6 +41,8 @@ def build_symbol_tables(graph: RepoGraph) -> dict[str, SymbolTable]:
                 table.bindings[child.name] = child.id
         tables[module.id] = table
 
+    _merge_go_packages(graph, tables)
+
     for module in graph.nodes(NodeKind.Module):
         table = tables[module.id]
         for child in graph.children(module.id, NodeKind.Import):
@@ -52,6 +54,31 @@ def build_symbol_tables(graph: RepoGraph) -> dict[str, SymbolTable]:
     return tables
 
 
+def _merge_go_packages(graph: RepoGraph, tables: dict[str, SymbolTable]) -> None:
+    """Go's package scope: files in one directory share top-level names.
+
+    Modules are per-file, but Go code calls sibling-file functions with no
+    import. Union the local bindings of go modules that share a directory
+    (existing bindings win, so a file's own names shadow siblings').
+    """
+    by_dir: dict[str, list[Node]] = {}
+    for module in graph.nodes(NodeKind.Module):
+        if module.attrs.get("language") != "go" or not module.path:
+            continue
+        directory = module.path.rsplit("/", 1)[0] if "/" in module.path else ""
+        by_dir.setdefault(directory, []).append(module)
+    for modules in by_dir.values():
+        if len(modules) < 2:
+            continue
+        union: dict[str, str | None] = {}
+        for module in modules:
+            union.update(tables[module.id].bindings)
+        for module in modules:
+            merged = dict(union)
+            merged.update(tables[module.id].bindings)  # own names shadow siblings
+            tables[module.id].bindings = merged
+
+
 def _resolve_target(qualname_index: dict[str, str], target: str) -> str | None:
     """Exact qualname match, else a *unique* suffix match.
 

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/src/cgir/cli.py

@@ -188,6 +188,75 @@ def stats(
         typer.echo(render_text(result), nl=False)
 
 
+_STARTER_CONFIG = """\
+# CGIR architecture rules — see docs/architecture-rules.md.
+# Pins (`# cgir: pure`, `no-net`, `stable-signature`, `frozen`) need no config;
+# they are enforced by `cgir lint`, the pre-commit hook, and `cgir diff`.
+#
+# [[rule]]
+# name = "core stays pure"
+# in = "app.core.*"
+# forbid-effect = ["net", "db"]
+"""
+
+_NEXT_STEPS = """\
+Next steps:
+  cgir watch {repo}                 # live index + contract drift on save
+  cgir hook install                 # pre-commit seatbelt (or: cgir init --hook)
+  cgir mcp --index {index}          # serve the index to your agent over MCP
+  CI gate: see docs/github-action.md
+"""
+
+
+@app.command()
+def init(
+    repo: Annotated[Path, typer.Argument(exists=True, file_okay=False)] = Path("."),
+    hook: Annotated[
+        bool, typer.Option("--hook", help="Also install the pre-commit seatbelt.")
+    ] = False,
+    force: Annotated[
+        bool, typer.Option("--force", help="Overwrite an existing cgir.toml.")
+    ] = False,
+) -> None:
+    """One-command onboarding: scan, starter config, .gitignore, next steps."""
+    result = scan_repo(repo, repo / ".cgir")
+    typer.echo(f"Indexed {len(result.specs)} components:")
+    _print_kind_histogram(result.specs)
+    entrypoints = [s for s in result.specs if s.entrypoint]
+    if entrypoints:
+        typer.echo(f"  entrypoints: {len(entrypoints)}")
+    untested = [s for s in result.specs if s.effects and not s.covered_by]
+    if untested:
+        typer.echo(f"  effectful without linked tests: {len(untested)}")
+
+    config = repo / "cgir.toml"
+    if config.exists() and not force:
+        typer.echo(f"kept existing {config.name}")
+    else:
+        config.write_text(_STARTER_CONFIG)
+        typer.echo(f"wrote {config.name} (report-only starter)")
+
+    gitignore = repo / ".gitignore"
+    existing = gitignore.read_text() if gitignore.exists() else ""
+    if ".cgir/" not in existing:
+        gitignore.write_text(
+            existing + ("" if existing.endswith("\n") or not existing else "\n") + ".cgir/\n"
+        )
+        typer.echo("added .cgir/ to .gitignore")
+
+    if hook:
+        from cgir.hooks import install as install_hook
+
+        try:
+            path = install_hook(repo)
+            typer.echo(f"installed contract seatbelt at {path}")
+        except FileExistsError:
+            typer.echo("pre-commit hook already exists — skipped (cgir hook install --force)")
+
+    typer.echo("")
+    typer.echo(_NEXT_STEPS.format(repo=repo, index=repo / ".cgir"), nl=False)
+
+
 @app.command()
 def watch(
     repo: Annotated[Path, typer.Argument(exists=True, file_okay=False)] = Path("."),
@@ -243,12 +312,20 @@ def impact(
         ),
     ] = None,
     repo: Annotated[
-        Path | None, typer.Option("--repo", help="Repo root (with --candidate).")
+        Path | None,
+        typer.Option("--repo", help="Repo root (with --candidate or --run)."),
     ] = None,
+    run: Annotated[
+        bool,
+        typer.Option(
+            "--run", help="Execute the selected tests (pytest) and exit with their status."
+        ),
+    ] = False,
 ) -> None:
     """Blast radius of changing a component: affected callers, entrypoints at risk, tests to run.
 
     Worst-case by default; narrowed by --changed or by a --candidate's actual contract delta.
+    --run executes exactly the tests the radius names.
     """
     specs = _load_specs(index_dir)
     try:
@@ -273,6 +350,35 @@ def impact(
         )
     except KeyError as exc:
         raise typer.BadParameter(f"Unknown component: {component_id}") from exc
+    if run:
+        _run_impact_tests(specs, list(data["tests"]), repo or Path.cwd())
+
+
+def _run_impact_tests(specs: list[ComponentSpec], test_ids: list[str], repo: Path) -> None:
+    """Execute the impact-selected tests with pytest; exit with their status."""
+    import subprocess
+    import sys
+
+    from cgir.report.impact import runnable_selectors
+
+    selectors, skipped = runnable_selectors(specs, test_ids)
+    for test_id in skipped:
+        typer.echo(f"  (skipped, not pytest-runnable: {test_id})")
+    if not selectors:
+        typer.echo("no runnable tests selected.")
+        return
+    typer.echo(f"running {len(selectors)} test(s):")
+    proc = subprocess.run(
+        [sys.executable, "-m", "pytest", "-q", *selectors],
+        cwd=repo,
+        capture_output=True,
+        text=True,
+    )
+    typer.echo(proc.stdout, nl=False)
+    if proc.stderr:
+        typer.echo(proc.stderr, nl=False)
+    if proc.returncode != 0:
+        raise typer.Exit(code=proc.returncode)
 
 
 @app.command()
@@ -458,26 +564,36 @@ def lint(
     config: Annotated[Path, typer.Option("--config", help="Rules file.")] = Path("cgir.toml"),
     as_json: Annotated[bool, typer.Option("--json")] = False,
 ) -> None:
-    """Check the index against semantic architecture rules (effects, kind, calls)."""
+    """Check the index against semantic architecture rules (effects, kind, calls).
+
+    Pin invariants (`# cgir: pure`, `no-<tag>`) are always checked — no rules
+    file needed for those.
+    """
     from cgir.report.lint import lint as run_lint
     from cgir.report.lint import load_rules, render_lint
+    from cgir.report.pins import state_violations
 
-    if not config.exists():
-        raise typer.BadParameter(f"No rules file at {config}")
-    violations = run_lint(_load_specs(index_dir), load_rules(config))
+    specs = _load_specs(index_dir)
+    violations = run_lint(specs, load_rules(config)) if config.exists() else []
+    pin_lines = state_violations(specs)
     if as_json:
         typer.echo(
             json.dumps(
-                [
-                    {"rule": v.rule, "component": v.component, "detail": v.detail}
-                    for v in violations
+                [{"rule": v.rule, "component": v.component, "detail": v.detail} for v in violations]
+                + [
+                    {"rule": "pin", "component": line.split(":")[0], "detail": line}
+                    for line in pin_lines
                 ],
                 indent=2,
             )
         )
     else:
         typer.echo(render_lint(violations), nl=False)
-    if violations:
+        if pin_lines:
+            typer.echo(f"pin violations ({len(pin_lines)}):")
+            for line in pin_lines:
+                typer.echo(f"  ! {line}")
+    if violations or pin_lines:
         raise typer.Exit(code=1)
 
 
@@ -562,10 +678,22 @@ def diff(
         ),
     ] = None,
 ) -> None:
-    """Compare two scan indexes: added/removed components and contract drift."""
+    """Compare two scan indexes: added/removed components and contract drift.
+
+    Pin invariants are always enforced: change pins (stable-signature, frozen)
+    across the pair, state pins (pure, no-<tag>) on the new index.
+    """
+    from cgir.export.json_export import read_types
+    from cgir.report.pins import change_violations, state_violations
+
     warning = compatibility_warning(read_manifest(old_index), read_manifest(new_index))
-    result = compute_diff(_load_specs(old_index), _load_specs(new_index))
+    old_specs, new_specs = _load_specs(old_index), _load_specs(new_index)
+    result = compute_diff(
+        old_specs, new_specs, old_types=read_types(old_index), new_types=read_types(new_index)
+    )
     found = violations(result, list(fail_on or []))
+    found += change_violations(old_specs, new_specs)
+    found += state_violations(new_specs)
     if as_json:
         payload = dict(result)
         if warning:

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/src/cgir/export/json_export.py

@@ -19,6 +19,28 @@ def read_specs(index_dir: Path) -> list[ComponentSpec]:
     ]
 
 
+def read_types(index_dir: Path) -> dict[str, dict[str, str]]:
+    """Type shapes (qualname -> field name -> type text) from an index's graph.
+
+    Sourced from Class nodes' ``fields`` attr — TypedDict/dataclass/pydantic
+    bodies and TS interfaces/type-aliases. Empty-field types are skipped.
+    """
+    graph_path = index_dir / "repo_graph.json"
+    if not graph_path.exists():
+        return {}
+    data = json.loads(graph_path.read_text())
+    out: dict[str, dict[str, str]] = {}
+    for node in data.get("nodes", []):
+        if node.get("kind") != "Class":
+            continue
+        attrs = node.get("attrs") or {}
+        fields = attrs.get("fields")
+        qual = attrs.get("qualname")
+        if isinstance(fields, dict) and fields and isinstance(qual, str):
+            out[qual] = {str(k): str(v) for k, v in fields.items()}
+    return out
+
+
 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(

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/src/cgir/hooks.py

@@ -32,6 +32,7 @@ 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
+from cgir.report.pins import change_violations, state_violations
 
 # The low-noise default from the real-history noise measurement: fail only
 # when something starts — or silently stops — reaching the outside world.
@@ -78,15 +79,16 @@ def _staged_supported(repo: Path) -> bool:
     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."""
+def _scan_tree(repo: Path, tree: str) -> tuple[list[ComponentSpec], dict[str, dict[str, str]]]:
+    """Scan the content of a git tree-ish out-of-tree: (specs, type shapes)."""
     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
+            result = scan_repo(src, out=Path(od))
+            return result.specs, result.types
 
 
 def run_check(repo: Path, fail_on: list[str] | None = None) -> HookResult:
@@ -103,13 +105,16 @@ def run_check(repo: Path, fail_on: list[str] | None = None) -> HookResult:
         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)
+        base_specs, base_types = _scan_tree(repo, head_tree) if head_tree else ([], {})
+        head_specs, head_types = _scan_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)
+    diff = compute_diff(base_specs, head_specs, old_types=base_types, new_types=head_types)
     found = violations(diff, rules)
+    # Pin invariants are always enforced, independent of --fail-on rules.
+    found += change_violations(base_specs, head_specs)
+    found += state_violations(head_specs)
     changed = [c["id"] for c in diff["changed"]]
 
     tests: set[str] = set()

{codegraph_ir-0.1.0 → codegraph_ir-0.2.1}/src/cgir/ir/component_spec.py

@@ -41,6 +41,7 @@ COMPONENT_SPEC_SCHEMA: dict[str, Any] = {
         "reads": {"type": "array", "items": {"type": "string"}},
         "writes": {"type": "array", "items": {"type": "string"}},
         "purity": {"type": "number", "minimum": 0, "maximum": 1},
+        "pins": {"type": "array", "items": {"type": "string"}},
         "algorithm": {"type": "array", "items": {"type": "string"}},
         "trace": {"type": "array", "items": {"type": "string"}},
     },
@@ -75,6 +76,7 @@ class ComponentSpec:
     reads: list[str] = field(default_factory=list)
     writes: list[str] = field(default_factory=list)
     purity: float | None = None
+    pins: list[str] = field(default_factory=list)
     algorithm: list[str] = field(default_factory=list)
 
     def to_dict(self) -> dict[str, Any]: