codegraph-brain 0.13.0__tar.gz → 0.14.1__tar.gz

codegraph_brain-0.14.1/.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+repos:
+  - repo: local
+    hooks:
+      # SonarCloud's python:S5778, enforced before the push rather than after it.
+      # Sonar only decorates a pull request, so the loop was write -> push ->
+      # get told -> fix -> forget, five times over. `pass_filenames: false`
+      # because the check is a repo-wide ratchet (a stale baseline entry is a
+      # failure too), which a staged-files-only view cannot see.
+      #
+      # This hook is the fast half, not the gate: CI does not run pre-commit,
+      # so `tests/unit/test_check_pytest_raises.py` is what actually blocks a
+      # merge. Both call the same `check()`.
+      - id: pytest-raises-single-call
+        name: one throwing call per pytest.raises block (S5778)
+        entry: python scripts/check_pytest_raises.py
+        language: system
+        pass_filenames: false
+        files: ^tests/.*\.py$
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+      - id: mypy
+        args: [--config-file=pyproject.toml]
+        files: ^src/
+        additional_dependencies:
+          - httpx>=0.27  # imported directly by guardian/providers/base.py (#275)
+          - pydantic>=2.13.4
+          - structlog>=25.5.0
+          - types-pyyaml>=6.0.12.20260518
+          - rich>=15.0.0
+          - typer>=0.26.7
+          - tree-sitter>=0.25.2
+          - tree-sitter-python>=0.25.0
+          - tree-sitter-typescript>=0.23.2
+          - pytest>=9.0.3
+          - "mcp[cli]>=2"  # must match the pyproject bound
+          - duckdb>=1.1.0

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

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

{codegraph_brain-0.13.0 → codegraph_brain-0.14.1}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.14.1](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.14.0...codegraph-brain-v0.14.1) (2026-08-16)
+
+
+### Bug Fixes
+
+* **bench:** cutting a release turned the new reachability tests red ([#397](https://github.com/zaebee/codegraph-brain/issues/397)) ([efbca37](https://github.com/zaebee/codegraph-brain/commit/efbca37c13e452fdf7266619b36d86b0e11bb795))
+
+## [0.14.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.13.0...codegraph-brain-v0.14.0) (2026-08-16)
+
+
+### Features
+
+* **guardian:** give measured recall a reviewer it can name ([#390](https://github.com/zaebee/codegraph-brain/issues/390)) ([#391](https://github.com/zaebee/codegraph-brain/issues/391)) ([acc1887](https://github.com/zaebee/codegraph-brain/commit/acc18874b7ce67fa38b7dab41552838f9578516d))
+* **guardian:** say whether a temperature was chosen or inherited ([#393](https://github.com/zaebee/codegraph-brain/issues/393)) ([#395](https://github.com/zaebee/codegraph-brain/issues/395)) ([1b2c3c3](https://github.com/zaebee/codegraph-brain/commit/1b2c3c3f1619f00d20c36fb315eaca3dce5661d9))
+
+
+### Bug Fixes
+
+* **guardian:** close the deferred cleanups that could only narrow silently ([#385](https://github.com/zaebee/codegraph-brain/issues/385)) ([#386](https://github.com/zaebee/codegraph-brain/issues/386)) ([e7020ff](https://github.com/zaebee/codegraph-brain/commit/e7020ff237964a66728f0b437f13b70dc8bfe2f9))
+* **guardian:** refuse a model name carrying whitespace ([#382](https://github.com/zaebee/codegraph-brain/issues/382)) ([#389](https://github.com/zaebee/codegraph-brain/issues/389)) ([45fb110](https://github.com/zaebee/codegraph-brain/commit/45fb110d3e440e858f57c28cd3e343e61218697c))
+
+
+### Documentation
+
+* **bench:** a failed parse is not a draw ([#394](https://github.com/zaebee/codegraph-brain/issues/394)) ([a70b09b](https://github.com/zaebee/codegraph-brain/commit/a70b09bf1faf67ddefff2d7fdcf555aba51ced9f))
+* **bench:** repeated rows are samples, not corrections ([#392](https://github.com/zaebee/codegraph-brain/issues/392)) ([e1fcc3f](https://github.com/zaebee/codegraph-brain/commit/e1fcc3f4728e61363d06b022b14bc66f45f3a031))
+
 ## [0.13.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.12.0...codegraph-brain-v0.13.0) (2026-08-15)
 
 

{codegraph_brain-0.13.0 → codegraph_brain-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.13.0
+Version: 0.14.1
 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.13.0 → codegraph_brain-0.14.1}/benchmarks/guardian/CURATION.md

@@ -54,6 +54,103 @@ carries `matched`, `noise` and `ambiguous_hits`, so either definition can be
 re-derived from it. (Contrast `calibration.jsonl`, which *was* rewritten — that
 was a scorer bug, wrong under its own stated algorithm, not a policy change.)
 
+## Repeated rows are samples, not corrections (2026-08-16, #390)
+
+**Do not deduplicate any corpus in this repository by "one row per subject,
+latest wins."** Every repeat here was paid for on purpose, and collapsing to the
+newest draw silently discards the experiment it belongs to.
+
+Written down because a downstream consumer adopted exactly that rule — reasoning
+that a re-run is a correction, so counting both would let a reviewer improve its
+record by re-running — and nothing in this repository contradicted it. The
+reasoning is sound for a corpus of corrections. It is wrong for these.
+
+### `benchmarks/martian-*.jsonl` — 115 review rows, 83 distinct subjects
+
+Keyed by subject and genome (`url`, `head_sha`, `review_fingerprint`,
+`finder_model`, `had_graph`), 32 of 115 rows are repeats. Every one of them
+comes from a registered sampling arm:
+
+| repeat group | count | source |
+|---|---|---|
+| `p3-run1` + `p3-run2` | 12 | Phase 3 union arm |
+| `p3-run1` + `p3-run2` + `p3-run3` | 7 | Phase 3 union arm |
+| `reviews` + `repeat-reviews` | 6 | R5 repeat probe |
+
+Phase 3 registered three runs at `temperature = 0.7` **because the runs must
+differ** — see the spec, "Configuration under test": at temperature 0 "the three
+runs collapse toward one and the union arm becomes identically equal to a single
+run." Gate G8 is defined as `F₂(union) > F₂(mean of the 3 runs)`; a mean over
+three draws is not computable from one of them.
+
+The variance is not theoretical. **21 of the 25 repeat groups disagree on how
+many findings the review produced**, with spreads including 8→14, 15→24, 26→38
+and one 0→25 — the same reviewer, the same commit, the same configuration. Keep
+one draw and the number you publish is a coin flip over that range.
+
+### `benchmarks/guardian/results.jsonl` — 118 scored rows, 53 distinct
+
+Repeats here carry an explicit `run` index (0/1/2) for the same reason. A row is
+identified by `pr` + `model` + `guardian_sha` + `run`, and dropping `run` averages
+away the per-PR sampling noise that R5 was written to measure.
+
+### `benchmarks/guardian/calibration.jsonl` — 236 rows, 118 subjects
+
+Exactly two rows per recorded review, one per judge (`gemini-2.5-flash` and
+`mistral-medium-latest`). The pair *is* the measurement — inter-judge agreement
+is the G3 statistic — so `row_key` alone is not a unique key here; `row_key` +
+`judge_model` is.
+
+### If you do need one row per reviewer
+
+Aggregate over the draws (mean, or union where the arm defines one); do not
+select among them. Selecting by recency is the one choice guaranteed to be
+uncorrelated with quality, and it deletes 28% of this corpus.
+
+**Aggregate over the subject's *draws*, which is not the same set as its rows.**
+Say what a draw is rather than which rows to exclude: an exclusion list is
+open-ended and the next entry arrives after it has already been believed, while
+a positive definition is closed.
+
+**A draw is a review that completed and whose output was parsed** — a row with
+`parse_failed: false`. That is the whole test; `error` is `None` on all 115 rows,
+because a run that failed outright never reached a record.
+
+**A `parse_failed` row is not a draw.** Its structured output could not be read,
+so it carries zero findings, and averaging it in charges the model for a harness
+failure. This is exactly the distinction #374 established ("a truncated review is
+not a review that found nothing"); before it, `parse_failed` was recorded and
+read by nothing.
+
+**A row with zero findings and `parse_failed: false` *is* a draw.** Three exist
+(PRs 6, 77754 and 107534, all gemini), and each spent real tokens — 106, 117 and
+124 completion tokens. The reviewer ran and said nothing, which is evidence about
+the reviewer. Same output shape as the parse failure, opposite meaning; keeping
+them and dropping the parse failure is the one combination that is right about
+both. The `arm` field exists for the mirror of this hazard: a failure and a
+controlled removal must not look alike in the record.
+
+There is exactly **one** parse-failed row in the review corpora:
+`martian-p3-run1.jsonl` for PR 11059 — the same row #374 was written about. One
+row out of 115 sounds ignorable and is not, because of how the averaging works:
+
+- PR 11059 has three rows. Dropping the parse-failed one leaves draws of `9/13`
+  and `8/8`, so the subject contributes mean `c = 8.5` over mean `n = 10.5` —
+  a rate of **81.0%**, which is *below* mistral/graph's pooled 86.6%.
+- Averaging the parse failure in as a third draw keeps that 81.0% but shrinks the
+  subject to `c = 5.667` over `n = 7.0`. Its **weight** falls, not its rate.
+- A below-average subject carrying less weight pulls the pooled figure **up**:
+  86.6% → **86.9%**.
+
+So including the harness failure makes the reviewer look better, which is the
+direction that makes this easy to leave in. That is how the gap was found — a
+downstream consumer computed 86.6%, this repository computed 86.9%, and the
+disagreement had exactly one cause.
+
+The same applies to the `error` rows in `results.jsonl`, for the same reason and
+by the same rule: they are already excluded there because `is_scored` requires
+`matched` and `precision`, which a failed run never gets.
+
 ## Curation policy
 
 - Style/idiom-only findings → `ambiguous` (guardian's PRECISION RULES forbid