codegraph-brain 0.30.0__tar.gz → 0.31.0__tar.gz

codegraph_brain-0.31.0/.github/test-count-baseline

@@ -0,0 +1 @@
+3417

codegraph_brain-0.31.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.31.0"
+}

{codegraph_brain-0.30.0 → codegraph_brain-0.31.0}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.31.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.30.0...codegraph-brain-v0.31.0) (2026-10-16)
+
+
+### Features
+
+* **bench:** score Go method spellings ([#653](https://github.com/zaebee/codegraph-brain/issues/653)) ([3eccec7](https://github.com/zaebee/codegraph-brain/commit/3eccec74a01af9c128431714d47270badf739e7c))
+* **go:** interface satisfaction compares arity, not just names ([#651](https://github.com/zaebee/codegraph-brain/issues/651)) ([05a8dd2](https://github.com/zaebee/codegraph-brain/commit/05a8dd2b5d7486733d74d9c139519c873a43d523))
+* **go:** interface satisfaction dispatches; embedding no longer does ([#647](https://github.com/zaebee/codegraph-brain/issues/647)) ([ff785f7](https://github.com/zaebee/codegraph-brain/commit/ff785f7e40a91e159266d1c7cb38ed912a1ed676))
+* **query:** a DISPATCHES hop costs no traversal depth ([#649](https://github.com/zaebee/codegraph-brain/issues/649)) ([b5c9ed9](https://github.com/zaebee/codegraph-brain/commit/b5c9ed91bec8b7c857e17f974f5d351c0c745094))
+* **query:** coverage note screens test callers and says where each gap is ([#644](https://github.com/zaebee/codegraph-brain/issues/644)) ([814a679](https://github.com/zaebee/codegraph-brain/commit/814a67904f980048f9d699f14408b6f4a3732c4f))
+
+
+### Bug Fixes
+
+* **logging:** the CLI and the MCP server log to stderr ([#619](https://github.com/zaebee/codegraph-brain/issues/619)) ([#622](https://github.com/zaebee/codegraph-brain/issues/622)) ([3fc1db2](https://github.com/zaebee/codegraph-brain/commit/3fc1db20d5c8a1cdb5793d357550c7854f499161))
+* **resolver:** an Any-typed receiver declares no type ([#638](https://github.com/zaebee/codegraph-brain/issues/638)) ([4cb43b6](https://github.com/zaebee/codegraph-brain/commit/4cb43b676e43a82b3a9edf3a6175e34623b68bba))
+
+
+### Documentation
+
+* **lab-notes:** exp1 — change radius and indirection vs agent cost (pre-registered) ([#633](https://github.com/zaebee/codegraph-brain/issues/633)) ([b6c002c](https://github.com/zaebee/codegraph-brain/commit/b6c002c9522a863b2412c06ca5130f622887ee40))
+* **lab-notes:** exp2 — indirection at fixed radius and answer size, on cgis (pre-registered) ([#634](https://github.com/zaebee/codegraph-brain/issues/634)) ([c74c90d](https://github.com/zaebee/codegraph-brain/commit/c74c90d6dd4e13d5fcd52339ed7b699bce6fa535))
+* **lab-notes:** exp3 — does cgis help an agent (pre-registered, kill criterion) ([#635](https://github.com/zaebee/codegraph-brain/issues/635)) ([507ada5](https://github.com/zaebee/codegraph-brain/commit/507ada5561147b7ec94fab9e8a3a21eb673755eb))
+* **lab-notes:** exp3b — rerun after the [#636](https://github.com/zaebee/codegraph-brain/issues/636) fix (pre-registered) ([#640](https://github.com/zaebee/codegraph-brain/issues/640)) ([c5cb290](https://github.com/zaebee/codegraph-brain/commit/c5cb290eb993cbf7fcee78c092d7f6bb61aa22b0))
+
 ## [0.30.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.29.0...codegraph-brain-v0.30.0) (2026-10-15)
 
 

{codegraph_brain-0.30.0 → codegraph_brain-0.31.0}/CLAUDE.md

@@ -80,7 +80,8 @@ IngestionPipeline (pipeline/__init__.py)
    (`name`, `extensions`, `code_fence`, `is_test`, `scope_of`, `extractor`, `project_reader`,
    `index_facts`, `classify`, `resolution`). `resolution()` returns `ResolutionRules`
    (`cgis.core.resolution`): type normalizers, steps at a position (`after:import_map`), a
-   fallback with its confidence, `reconcile_import` — all reading the index as `ResolutionView`.
+   fallback with its confidence, `reconcile_import`, and optionally `dispatch` (which methods a call through
+   another type's may run; default: class hierarchy) — all reading the index as `ResolutionView`.
    Metadata other files resolve against goes in the manifest's `cross_file_metadata`. `classify` answers for references from the pack's own files and
    runs the whole chain; a source with no pack gets the generic tail in `SymbolIndex.classify_fqn`.
 3. Add one `Manifest` to `MANIFESTS` in `src/cgis/languages/__init__.py`, with a `load` function that

{codegraph_brain-0.30.0 → codegraph_brain-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.30.0
+Version: 0.31.0
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain

codegraph_brain-0.31.0/benchmarks/agent_ab/analysis/exp1_gates.py

@@ -0,0 +1,88 @@
+"""Exp1 gates, exactly as pre-registered (docs/lab-notes/2026-10-15-exp1-radius-indirection.md)."""
+import json
+import statistics as st
+import sys
+from collections import defaultdict
+
+results, drift_path = sys.argv[1], sys.argv[2]
+rows = [json.loads(l) for l in open(results)]
+drift = json.load(open(drift_path))
+by = defaultdict(list)
+for r in rows:
+    by[r["task"]].append(r)
+
+billing_note = f"runs {len(rows)}, failed {sum(1 for r in rows if r.get('is_error') or r.get('subtype') != 'success')}, total ${sum(r.get('cost_usd') or 0 for r in rows):.2f}"
+print(billing_note)
+
+tasks = {}
+for t, rs in by.items():
+    cell = t.split("owner-exp1-")[1].split("-")[:2]
+    tasks[t] = {
+        "row": cell[0], "ind": cell[1] == "ind",
+        "cost": st.median(r["cost_usd"] for r in rs),
+        "recall": st.median(r["recall"] for r in rs),
+        "precision": st.median(r["precision"] for r in rs),
+        "calls": st.median(r["total_tool_calls"] for r in rs),
+        "n": len(rs), **drift[t],
+    }
+
+print(f"\n{'task':52} {'cost':>6} {'recall':>6} {'prec':>5} {'calls':>5} {'files':>5} {'drift':>5}")
+for t, v in sorted(tasks.items(), key=lambda kv: (kv[1]["row"], kv[1]["ind"], kv[1]["cost"])):
+    print(f"{t:52} {v['cost']:6.3f} {v['recall']:6.2f} {v['precision']:5.2f} {v['calls']:5.1f} {v['files']:5} {v['drift']:5.3f}")
+
+
+def med(sel, key="cost"):
+    xs = [v[key] for v in tasks.values() if sel(v)]
+    return (st.median(xs), len(xs)) if xs else (float("nan"), 0)
+
+
+print("\ncell medians (cost, recall):")
+for row in ("big", "small"):
+    for ind in (False, True):
+        c, n = med(lambda v: v["row"] == row and v["ind"] == ind)
+        r, _ = med(lambda v: v["row"] == row and v["ind"] == ind, "recall")
+        print(f"  {row:5} {'indirect' if ind else 'direct  '} n={n:2} cost {c:.3f} recall {r:.2f}")
+
+big, nb = med(lambda v: v["row"] == "big")
+small, ns = med(lambda v: v["row"] == "small")
+print(f"\nG1 radius: big {big:.3f} (n={nb}) / small {small:.3f} (n={ns}) = x{big / small:.2f} -> {'PASS' if big >= 1.5 * small else 'FAIL'} (>= x1.5)")
+
+print("G2 indirection (descriptive; big x direct n=2):")
+for row in ("big", "small"):
+    d, nd = med(lambda v: v["row"] == row and not v["ind"])
+    i, ni = med(lambda v: v["row"] == row and v["ind"])
+    rd, _ = med(lambda v: v["row"] == row and not v["ind"], "recall")
+    ri, _ = med(lambda v: v["row"] == row and v["ind"], "recall")
+    print(f"  {row}: indirect/direct cost x{i / d:.2f} (n {ni}/{nd}), recall drop {rd - ri:+.2f}")
+
+
+def ranks(xs):
+    order = sorted(range(len(xs)), key=lambda i: xs[i])
+    r = [0.0] * len(xs)
+    i = 0
+    while i < len(order):
+        j = i
+        while j + 1 < len(order) and xs[order[j + 1]] == xs[order[i]]:
+            j += 1
+        for k in range(i, j + 1):
+            r[order[k]] = (i + j) / 2 + 1
+        i = j + 1
+    return r
+
+
+def pearson(a, b):
+    ma, mb = st.mean(a), st.mean(b)
+    num = sum((x - ma) * (y - mb) for x, y in zip(a, b))
+    den = (sum((x - ma) ** 2 for x in a) * sum((y - mb) ** 2 for y in b)) ** 0.5
+    return num / den
+
+
+vs = list(tasks.values())
+c, d, f = ranks([v["cost"] for v in vs]), ranks([v["drift"] for v in vs]), ranks([v["files"] for v in vs])
+rcd, rcf, rdf = pearson(c, d), pearson(c, f), pearson(d, f)
+partial = (rcd - rcf * rdf) / ((1 - rcf**2) * (1 - rdf**2)) ** 0.5
+verdict = "PASS (drift adds nothing)" if abs(partial) < 0.2 else ("FAIL: drift matters, H1 refuted" if abs(partial) >= 0.3 else "INCONCLUSIVE")
+print(f"\nG3 Spearman: cost~files {rcf:+.2f}, cost~drift {rcd:+.2f}, drift~files {rdf:+.2f}; partial cost~drift|files {partial:+.2f} -> {verdict}")
+allr = [r["recall"] for r in rows]
+print(f"G4 ceiling: recall 1.00 in {sum(x >= 0.999 for x in allr)}/{len(allr)} runs; min {min(allr):.2f}; "
+      f"{'every cell at 1.00 -> cost-only' if all(v['recall'] >= 0.999 for v in vs) else 'not every task at 1.00'}")

codegraph_brain-0.31.0/benchmarks/agent_ab/analysis/exp2_gates.py

@@ -0,0 +1,54 @@
+"""Exp2 gates as pre-registered (paired). Usage: gates2.py results.jsonl pairs.json"""
+import json, math, random, statistics as st, sys
+from collections import defaultdict
+
+rows = [json.loads(l) for l in open(sys.argv[1])]
+pairs = json.load(open(sys.argv[2]))["pairs"]
+by = defaultdict(list)
+for r in rows:
+    by[r["task"]].append(r)
+print(f"runs {len(rows)}, errors {sum(1 for r in rows if r.get('is_error') or r.get('subtype') != 'success')}, "
+      f"contaminated {sum(r['contaminated'] for r in rows)}, total ${sum(r['cost_usd'] or 0 for r in rows):.2f}")
+
+
+def tid(fqn, cell):
+    return f"cgis-exp2-{cell}-" + fqn.rsplit(".", 1)[-1].strip("_").replace("_", "-")
+
+
+def med(t, k):
+    return st.median(r[k] for r in by[t])
+
+
+P = []
+for n, (d, fd, sd, i, fi, si) in enumerate(pairs, 1):
+    td, ti = tid(d, "dir"), tid(i, "ind")
+    P.append({"n": n, "d": td, "i": ti, "ratio": med(ti, "cost_usd") / med(td, "cost_usd"),
+              "drec": med(td, "recall") - med(ti, "recall"),
+              "cd": med(td, "cost_usd"), "ci": med(ti, "cost_usd"), "rd": med(td, "recall"), "ri": med(ti, "recall")})
+print(f"\n{'#':>2} {'direct':38} {'cost':>6} {'rec':>5} | {'indirect':38} {'cost':>6} {'rec':>5} | ratio  Δrec")
+for p in P:
+    print(f"{p['n']:>2} {p['d'][10:]:38} {p['cd']:6.3f} {p['rd']:5.2f} | {p['i'][10:]:38} {p['ci']:6.3f} {p['ri']:5.2f} | {p['ratio']:5.2f} {p['drec']:+.2f}")
+
+
+def gate(ps, label):
+    ratios = [p["ratio"] for p in ps]
+    mr = st.median(ratios)
+    wins = sum(r > 1 for r in ratios)
+    need = math.ceil(0.75 * len(ps))
+    v = "PASS" if mr >= 1.3 and wins >= need else ("REFUTED (≤1.1)" if mr <= 1.1 else "INCONCLUSIVE")
+    rnd = random.Random(0)
+    boots = sorted(st.median(rnd.choice(ratios) for _ in ratios) for _ in range(10000))
+    lo, hi = boots[250], boots[9749]
+    md = st.median(p["drec"] for p in ps)
+    print(f"\n[{label}] n={len(ps)}  G1 cost: median ratio {mr:.2f} (95% CI {lo:.2f}–{hi:.2f}), indirect dearer in {wins}/{len(ps)} (need {need}) -> {v}")
+    print(f"[{label}]       G2 recall: median Δ(direct−indirect) {md:+.2f} -> {'PASS' if md >= 0.10 else 'not met'}")
+
+
+gate(P, "all pairs")
+gate([p for p in P if p["n"] != 3], "without pair 3")
+allr = [r["recall"] for r in rows if "-desc-" not in r["task"]]
+print(f"\nG4 ceiling: per run {sum(x >= 0.999 for x in allr)}/{len(allr)} paired runs at 1.00 (min {min(allr):.2f}); "
+      f"per pair-task median: {sum(1 for p in P for x in (p['rd'], p['ri']) if x >= 0.999)}/{2 * len(P)} at 1.00")
+print("\nDescriptive (unpaired, dynamic hops):")
+for t in sorted(t for t in by if "-desc-" in t):
+    print(f"  {t[10:]:36} cost {med(t, 'cost_usd'):.3f} recall {med(t, 'recall'):.2f} precision {med(t, 'precision'):.2f}")

codegraph_brain-0.31.0/benchmarks/agent_ab/analysis/exp2_pairs.json

@@ -0,0 +1,71 @@
+{
+ "pairs": [
+  [
+   "cgis.guardian.metrics.reject_metrics_path",
+   3,
+   5,
+   "cgis.guardian.core.GuardianReviewer._finder_pass",
+   3,
+   5
+  ],
+  [
+   "cgis.languages.extractors",
+   4,
+   4,
+   "cgis.storage.sqlite_store.SQLiteStore.get_edge_stats",
+   5,
+   6
+  ],
+  [
+   "cgis.query.drift.fractal.build_ladder",
+   4,
+   6,
+   "cgis.guardian.core._sanitize_finder_result",
+   4,
+   10
+  ],
+  [
+   "cgis.query.fqn.resolve_fqn",
+   4,
+   13,
+   "cgis.query.render.metrics._as_terms",
+   4,
+   12
+  ],
+  [
+   "cgis.guardian.skeptic.visible_findings",
+   5,
+   6,
+   "cgis.storage.sqlite_store.SQLiteStore.get_incoming_edges",
+   5,
+   8
+  ],
+  [
+   "cgis.query.context.prompt._loc",
+   5,
+   10,
+   "cgis.query.drift.drift.DriftScorer.fit_templates",
+   6,
+   10
+  ],
+  [
+   "cgis.query.fqn.effective_prefix",
+   7,
+   15,
+   "cgis.query.drift.drift._fit_config",
+   6,
+   12
+  ]
+ ],
+ "unpaired": [
+  "cgis.guardian.render.render_finding",
+  "cgis.languages.go.naming._relative",
+  "cgis.languages.python._syntax.resolve_relative_module",
+  "cgis.languages.python._types.TypeResolver._first_top_level_arg",
+  "cgis.query.render.metrics._segment_exclusion",
+  "cgis.languages.python._annotations._collect",
+  "cgis.core.js_globals.specifier_fqn",
+  "cgis.guardian.providers.base.BaseProvider._record_usage",
+  "cgis.pipeline.refresh_dispatch"
+ ]
+}

codegraph_brain-0.31.0/benchmarks/agent_ab/analysis/exp2_post_review.py

@@ -0,0 +1,34 @@
+"""Exp2 post-review recompute (#634 review C1): pair 2 dropped, extractors rescored on corrected gold.
+
+Run from the repository root: uv run python benchmarks/agent_ab/analysis/exp2_post_review.py
+"""
+import json, random, statistics as st
+from pathlib import Path
+from cgis.bench.agent_task import load_tasks, score_answer
+from cgis.bench.transcript import parse_transcript
+
+tasks = {t.id: t for t in load_tasks(Path("benchmarks/agent_ab/tasks"))}
+rows = [json.loads(l) for l in open("benchmarks/agent_ab/results-exp2-full.jsonl")]
+for r in rows:
+    if r["task"].endswith("dir-extractors"):
+        tr = Path(r["transcript"])
+        if not tr.is_file():  # transcripts are git-ignored; a clean clone has only the stored scores
+            print(f"extractors run {r['run']}: transcript absent, stored precision {r['precision']:.2f}")
+            continue
+        s = score_answer(tasks[r["task"]], parse_transcript(tr.read_text().splitlines()).answer)
+        print(f"extractors run {r['run']}: recall {s.recall:.2f} precision {s.precision:.2f} (stored {r['precision']:.2f})")
+cost = {}
+for r in rows:
+    cost.setdefault(r["task"], []).append(r["cost_usd"])
+pairs = [("reject-metrics-path", "finder-pass"), ("build-ladder", "sanitize-finder-result"), ("resolve-fqn", "as-terms"),
+         ("visible-findings", "get-incoming-edges"), ("loc", "fit-templates"), ("effective-prefix", "fit-config")]
+rat = [st.median(cost["cgis-exp2-ind-" + i]) / st.median(cost["cgis-exp2-dir-" + d]) for d, i in pairs]
+rnd = random.Random(0)
+b = sorted(st.median(rnd.choice(rat) for _ in rat) for _ in range(10000))
+m = st.median(rat)
+v = "PASS" if m >= 1.3 and sum(x > 1 for x in rat) >= 5 else ("REFUTED" if m <= 1.1 else "INCONCLUSIVE")
+print(f"6 pairs: ratios {[round(x, 2) for x in rat]}, median {m:.3f}, 95% CI {b[250]:.2f}-{b[9749]:.2f}, dearer {sum(x > 1 for x in rat)}/6 -> {v}")
+gm = 1.0
+for x in rat:
+    gm *= x
+print(f"geometric mean {gm ** (1 / len(rat)):.3f}")

codegraph_brain-0.31.0/benchmarks/agent_ab/analysis/exp3_gates.py

@@ -0,0 +1,76 @@
+"""Exp3 gates as pre-registered. Usage: exp3_gates.py forced.jsonl (control is the stored exp1/exp2 full runs)."""
+import json, random, statistics as st, sys
+from collections import defaultdict
+
+FORCED = sys.argv[1]
+CONTROL = ["benchmarks/agent_ab/results-exp1-full.jsonl", "benchmarks/agent_ab/results-exp2-full.jsonl"]
+# Declared post-hoc gold corrections to stored control recall (lab notes exp1 C1, exp2 C1).
+RECALL_FIX = {("owner-exp1-big-ind-thread-for", 0): 1.0, ("owner-exp1-big-ind-thread-for", 1): 1.0,
+              ("owner-exp1-big-ind-thread-for", 2): 0.949}
+
+
+def load(paths, arm):
+    by = defaultdict(list)
+    for p in paths:
+        for line in open(p):
+            r = json.loads(line)
+            if r["arm"] != arm:
+                continue
+            r["recall"] = RECALL_FIX.get((r["task"], r["run"]), r["recall"]) if arm == "control" else r["recall"]
+            by[r["task"]].append(r)
+    return by
+
+
+ctl, frc = load(CONTROL, "control"), load([FORCED], "cgis-forced")
+rows = [r for rs in frc.values() for r in rs]
+print(f"forced runs {len(rows)}, errors {sum(1 for r in rows if r.get('is_error') or r.get('subtype') != 'success')}, "
+      f"contaminated {sum(r['contaminated'] for r in rows)}, cost ${sum(r['cost_usd'] or 0 for r in rows):.2f}, "
+      f"sessions with 0 cgis calls {sum(1 for r in rows if not r.get('cgis_calls'))}")
+
+
+def med(rs, k):
+    return st.median(r[k] for r in rs)
+
+
+def is_primary(t):
+    return t.startswith("owner-exp1-big-ind-") or t.startswith("cgis-exp2-desc-")
+
+
+T = {}
+for t in sorted(set(ctl) & set(frc)):
+    T[t] = {"ratio": med(frc[t], "cost_usd") / med(ctl[t], "cost_usd"),
+            "drec": med(frc[t], "recall") - med(ctl[t], "recall"),
+            "pc": med(ctl[t], "precision"), "pf": med(frc[t], "precision"),
+            "cc": med(ctl[t], "cost_usd"), "cf": med(frc[t], "cost_usd"),
+            "calls": med(frc[t], "cgis_calls"), "turns_c": med(ctl[t], "turns"), "turns_f": med(frc[t], "turns")}
+missing = sorted(set(ctl) ^ set(frc))
+if missing:
+    print("tasks not in both arms:", missing)
+print(f"\n{'task':52} {'ctl$':>6} {'cgis$':>6} {'ratio':>5} {'Δrec':>6} {'P ctl':>5} {'P cgis':>6} {'calls':>5}")
+for t, v in T.items():
+    print(f"{'*' if is_primary(t) else ' '}{t:51} {v['cc']:6.3f} {v['cf']:6.3f} {v['ratio']:5.2f} {v['drec']:+6.2f} {v['pc']:5.2f} {v['pf']:6.2f} {v['calls']:5.1f}")
+
+prim = [v for t, v in T.items() if is_primary(t)]
+r = [v["ratio"] for v in prim]
+mr, md = st.median(r), st.median(v["drec"] for v in prim)
+rnd = random.Random(0)
+b = sorted(st.median(rnd.choice(r) for _ in r) for _ in range(10000))
+helps = mr <= 0.80 and md >= -0.02
+print(f"\nPRIMARY (n={len(prim)}): median cost ratio {mr:.3f} (95% CI {b[250]:.2f}-{b[9749]:.2f}), "
+      f"median Δrecall {md:+.3f} -> {'HELPS (keep positioning)' if helps else 'DOES NOT HELP (kill agent-context positioning)'}")
+print(f"PRIMARY precision: control {st.median(v['pc'] for v in prim):.2f}, cgis-forced {st.median(v['pf'] for v in prim):.2f}")
+
+
+def cell(t):
+    p = t.split("-")
+    return "-".join(p[:4]) if t.startswith("owner-exp1") else "-".join(p[:3])
+
+
+groups = defaultdict(list)
+for t, v in T.items():
+    groups[cell(t)].append(v)
+print("\nSECONDARY by cell:")
+for g, vs in sorted(groups.items()):
+    print(f"  {g:24} n={len(vs):2} median ratio {st.median(v['ratio'] for v in vs):.2f}  Δrecall {st.median(v['drec'] for v in vs):+.2f}")
+allr = [v["ratio"] for v in T.values()]
+print(f"  ALL n={len(allr)} median ratio {st.median(allr):.2f}")