codegraph-brain 0.7.4__tar.gz → 0.8.0__tar.gz

codegraph_brain-0.8.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches: [ main, dev, "feat/**", "fix/**", "docs/**" ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  python-ci:
+    name: Python Verification
+    runs-on: ubuntu-latest
+    # Job level, not step level: a step's own `env` block is not reliably visible
+    # to that same step's `if`, and a condition that silently never fires is a
+    # gate that looks like protection and is not.
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          # Full history: the scanner computes new-code metrics by diffing against
+          # the base branch, and a depth-1 clone makes it log
+          #   WARN Could not find ref 'main' in refs/heads, refs/remotes…
+          # which silently degrades every new_* metric, new_coverage included.
+          fetch-depth: 0
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+        with:
+          enable-cache: true
+
+      - name: Lockfile in step with pyproject
+        # This is the only step that validates the lockfile. `--frozen` below stops
+        # uv rewriting uv.lock, but it does not check that the lock is current —
+        # that is `--locked`. Keeping the check explicit gives a clearer failure
+        # than a sync error, and it still runs first so an unfrozen uv could never
+        # repair the lock ahead of it.
+        run: uv lock --check
+
+      - name: Install Dependencies
+        run: uv sync --frozen --group dev
+
+      - name: Ruff Format Check
+        run: uv run --frozen ruff format --check .
+
+      - name: Ruff Lint
+        run: uv run --frozen ruff check .
+
+      - name: Interrogate (≥90% docstring coverage)
+        run: uv run --frozen interrogate -v --fail-under 90 src/cgis
+
+      - name: Mypy (strict)
+        run: uv run --frozen mypy src
+
+      - name: Pytest
+        # xml alongside term-missing: the console form is for a human reading the
+        # log, the XML is the only form SonarCloud can import.
+        run: uv run --frozen pytest --cov=cgis --cov-report=term-missing --cov-report=xml
+
+      - name: SonarQube Cloud scan
+        # Inert until SONAR_TOKEN exists, so this can land before the migration.
+        # Coverage cannot be imported by Automatic Analysis at all — see #317 —
+        # so the token must be added only AFTER Automatic Analysis is switched
+        # off in the SonarCloud UI, or the two modes conflict.
+        if: env.SONAR_TOKEN != ''
+        uses: SonarSource/sonarqube-scan-action@22918119ff8e1ca75a623e15c8296b6ea4fbe28f  # v8.2.1
+        with:
+          # Passed as args rather than a committed sonar-project.properties:
+          # SonarCloud treats that file as a signal to disable Automatic
+          # Analysis, which would break the working setup the moment this
+          # merges rather than when the migration is actually performed.
+          args: >
+            -Dsonar.projectKey=zaebee_codegraph-brain
+            -Dsonar.organization=zaebee
+            -Dsonar.sources=src,scripts
+            -Dsonar.tests=tests
+            -Dsonar.python.version=3.12
+            -Dsonar.python.coverage.reportPaths=coverage.xml

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

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

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.5...codegraph-brain-v0.8.0) (2026-08-01)
+
+
+### Features
+
+* **ontology:** bind guardian, cli and api as measured domains ([#325](https://github.com/zaebee/codegraph-brain/issues/325)) ([e7678e8](https://github.com/zaebee/codegraph-brain/commit/e7678e899bf09e5567ea1fa19180835984b652c9))
+
+## [0.7.5](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.4...codegraph-brain-v0.7.5) (2026-08-01)
+
+
+### Documentation
+
+* **spec:** record what changed for [#258](https://github.com/zaebee/codegraph-brain/issues/258) — fixture, second lever, pre-registered gate ([#322](https://github.com/zaebee/codegraph-brain/issues/322)) ([fca8da8](https://github.com/zaebee/codegraph-brain/commit/fca8da8120a7542a71c875d9a960df615f59594e))
+
 ## [0.7.4](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.3...codegraph-brain-v0.7.4) (2026-08-01)
 
 

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-brain
-Version: 0.7.4
+Version: 0.8.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.7.4 → codegraph_brain-0.8.0}/benchmarks/guardian/CURATION.md

@@ -206,3 +206,69 @@ Fixed later by human-directed review as #283 (`b2ae97b`), which is the
 Precision is unaffected: `matched` stays 0, so the entry still scores `0/10`. The
 addition supplies a recall signal — a real **0/1** where the empty ground truth
 gave a vacuous 1.0.
+
+## pr-313 (added 2026-08-01, #315) — first security fixture
+
+`security(mcp): validate db_path before cgis_ingest creates a database`.
+
+Provenance is stronger than the rest of the corpus: neither entry was mined from
+review dialogue. Both were **reproduced by execution** on the pre-fix code and
+re-run after the fix.
+
+- `dangling-symlink-write-primitive` (110-121, major, **security**, `fix-commit`
+  `8bcda77`). A `.db` symlink whose target does not exist passes every check —
+  `is_file()` is False for a dangling link, so the magic-byte test never runs —
+  and SQLite then follows it and creates the target. Demonstrated by writing a
+  SQLite header into a non-existent `.ssh/authorized_keys`; refused afterwards.
+- `oserror-escapes-the-tool` (114-124, minor, `logic`, `fix-commit` `72c34eb`).
+  The guard runs before `cgis_ingest`'s own try/except and `Path.is_dir()`,
+  `.stat()`, `.open()` propagate `OSError`, so a `PermissionError` on the parent
+  crashes the MCP tool. Demonstrated with a `chmod 000` parent.
+
+### Why `head` is `2d79671` and not the final pull head
+
+Standard policy, restated because this PR has four commits: `2d79671` is the
+snapshot the first review ran on and the only one where **both** findings are
+present. The later three are the fixes.
+
+### Overlapping ranges are deliberate
+
+The two ranges overlap on 114-121. A reviewer can legitimately anchor the
+symlink bypass either at the unresolved `Path(db_path)` (110) or at the
+`is_file()` test where it slips through (121), and the OSError leak sits across
+the whole probe block. Matching is greedy per entry, so one prediction still
+consumes only one entry.
+
+### Scoring the historical runs would be unfair
+
+Three reviews ran over this PR, but on **different commits** — guardian started
+at 23:38:58, after `72c34eb` had already fixed the OSError defect, so it never
+had a shot at that entry:
+
+| reviewer | commit reviewed | findings | GT available | GT hit |
+|---|---|---|---|---|
+| gemini (1st) | `2d79671` | 1 | 2 | 1 (OSError) |
+| guardian | `72c34eb` | 5 | 1 | 0 |
+| gemini (2nd) | `c90bbf8` | 2 | 1 | 1 (symlink) |
+
+A replay at `head` gives every reviewer both findings, which is the point of
+pinning the review head. The table above must not be read as guardian missing
+two.
+
+### A refuted claim that is deliberately absent
+
+Guardian's `multi-dot suffix` finding on this PR was a false positive — it
+asserted `graph.tar.db` should be rejected, when ending in `.db` is exactly the
+stated policy, and its suggested `path.suffixes` fix would have broken a
+legitimate `my.project.db`. Per the policy above, refuted claims are omitted
+from ground truth entirely rather than filed as `ambiguous`, so that precision
+failures stay observable. Recorded here because the cross-family skeptic
+**confirmed** it (`Verified by gemini-2.5-flash`) — the cleanest example yet of
+a skeptic passing a systematic reasoning error (#246).
+
+### `category: security`
+
+New value, added with this fixture (`findings.py`). The finder prompt does not
+yet offer it — teaching the finder to emit it is #258 and needs bench
+validation. Scoring is unaffected: `_entry_accepts` compares file and line
+range, never category.

codegraph_brain-0.8.0/benchmarks/guardian/pr-313.yaml

@@ -0,0 +1,43 @@
+# PR 313 — security(mcp): validate db_path before cgis_ingest creates a database.
+# See CURATION.md. First security fixture in the corpus (#315, taxonomy gap #258).
+#
+# Provenance is unusually strong: both findings were REPRODUCED BY EXECUTION on
+# the pre-fix code and re-run after the fix, not mined from review dialogue.
+#
+# head = review head (the snapshot the first review ran on). The three later
+# commits on that branch are the fixes, so replaying the final pull head would
+# make both findings unfindable — CURATION.md erratum on spec §3.1.
+#
+# The two ranges overlap on 114-121. That is inherent rather than sloppy: a
+# reviewer can legitimately anchor the symlink bypass either at the unresolved
+# `Path(db_path)` (110) or at the `is_file()` test where it slips through (121),
+# and the OSError leak sits across the whole probe block. Matching is greedy per
+# entry, so one prediction still consumes only one entry.
+pr: 313
+base: 411f8c5894b6
+head: 2d79671547d4
+findings:
+  - id: dangling-symlink-write-primitive
+    file: src/cgis/api/mcp_server.py
+    lines: [110, 121]
+    severity: major
+    category: security
+    summary: >
+      db_path is validated unresolved, so a `.db` symlink whose target does not
+      exist passes every check — is_file() is False for a dangling link, so the
+      magic-byte test never runs — and SQLite then follows it and creates the
+      target. Demonstrated: a symlink to a non-existent .ssh/authorized_keys was
+      created as a SQLite database (header b'SQLite format 3\x00').
+    source: fix-commit
+  - id: oserror-escapes-the-tool
+    file: src/cgis/api/mcp_server.py
+    lines: [114, 124]
+    severity: minor
+    category: logic
+    summary: >
+      The guard runs before cgis_ingest's own try/except, and Path.is_dir(),
+      .stat() and .open() all propagate OSError, so a PermissionError on the
+      parent directory escapes the MCP tool as a crash instead of a message the
+      agent can act on. Demonstrated with a chmod 000 parent directory.
+    source: fix-commit
+ambiguous: []

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/docs/ontology/patterns.yaml

@@ -153,6 +153,36 @@ project_domains:
     profile: python
     drift_tolerance: 0.20 # v2 re-baselined ≈0.19 after ontology_init joined the domain (#174) — was ≈0.14/0.18
 
+  # Bound in #182: these three were production code with no architectural gate at
+  # all — 207 of 618 internal nodes (33%) sat outside every domain, guardian alone
+  # accounting for 138. A tool that measures other people's architecture should not
+  # leave a third of its own unmeasured. Tolerances are measured + 0.03 margin via
+  # the init-ontology path, and ratchet DOWN from here like every other domain.
+  - name: "guardian"
+    fqn_prefix: "cgis.guardian"
+    expected_pattern: layered_dag
+    profile: python
+    drift_tolerance: 0.26 # v2 measured 0.2282; dag_depth 5 clears the template's min 3
+                          # (runner-up dispatcher 0.34 — a clear win, not a coin flip)
+
+  # cli and api are hygiene-only by rule, not by taste: neither has ANY
+  # intra-domain IMPORTS edge (cli is one file, api is two), so there is no
+  # import structure for a pattern to describe. A label would rest entirely on
+  # intra-file call topology, which is not what the alphabet measures.
+  # `api` made that especially plain — it best-fits pure_utility ("called by
+  # many; depends on nothing") while importing 16 internal modules and being
+  # imported by none. Every multi-file domain here has a populated IMPORTS
+  # layer; these two do not, and are labelled accordingly.
+  - name: "cli"
+    fqn_prefix: "cgis.cli"
+    profile: python
+    drift_tolerance: 0.03 # hygiene-only; measured 0.00 (no cycles, nothing unresolved)
+
+  - name: "api"
+    fqn_prefix: "cgis.api"
+    profile: python
+    drift_tolerance: 0.03 # hygiene-only; measured 0.00
+
   # TypeScript graph (ingest root: ui/src → components/Foo.tsx = components.Foo)
   - name: "components"
     fqn_prefix: "components"

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/docs/ontology/tolerances.lock

@@ -16,6 +16,9 @@ project_domains:
   pipeline: 0.25
   storage: 0.20
   query: 0.20
+  guardian: 0.26
+  cli: 0.03
+  api: 0.03
   components: 0.20
   layout: 0.50
   hooks: 0.15

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/docs/specs/2026-07-31-finder-bug-class-taxonomy.md

@@ -153,3 +153,93 @@ Steps 2–4 need a provider key, which is why they are not done here.
   instructions (we have no such capability in the finder).
 - Copying rule text verbatim — the source is Apache-2.0 Go/agentic tooling for a
   different stack; #258 asks for the taxonomy only.
+
+---
+
+# Addendum — 2026-08-01: the experiment is now runnable, and a second intervention appeared
+
+Three things changed after this document was written. None of them changes the
+conclusion above (**still nothing shipped to `prompts.py`**), but two of them
+change what the deciding experiment should measure.
+
+## 1. The top gap now has a fixture
+
+When the table above was written, the Security-Sensitive Code row was **absent**
+with no ground truth to test it against; only Resource Management (pr-278) had
+one. `benchmarks/guardian/pr-313.yaml` (#315) now carries a real security defect:
+
+    dangling-symlink-write-primitive   (major, category: security)
+
+A `.db` symlink whose target does not exist defeats a path guard —
+`is_file()` is False for a dangling link, so the magic-byte check never runs and
+SQLite creates the target. Reproduced by execution, not mined from dialogue.
+
+`category: security` was added to `Category` with that fixture. The finder prompt
+does **not** offer it — that is this document's subject and still unshipped.
+Scoring is unaffected: `_entry_accepts` compares file and line range, never
+category.
+
+So the experiment can now measure both evidenced gaps rather than one.
+
+## 2. A second, better-evidenced intervention: exculpating guards
+
+Production runs on 2026-07-31 produced a failure mode this document does not
+consider, because it is not a missing class — it is a defect in the classes that
+already exist.
+
+On PR #297 the finder returned **12** "Unvalidated dictionary access" findings
+against code that validates with `isinstance` one line above the use. On #313 it
+returned "floating-point comparison may be flaky" on a line carrying an explicit
+`+ 1e-9`. Both trace to focus-area wording that names a *shape* and never names
+the guard that makes an instance a non-finding:
+
+> **Unvalidated external data** — … used as a `dict`/… **without first checking
+> its type or presence**
+
+The finder matches the shape and does not check whether the guard is present.
+
+This matters for sequencing: **adding classes to a checklist that already
+over-fires multiplies noise.** The precision fix should be measured first, or at
+least separately — otherwise a recall gain from new classes and a noise change
+from the rewrite arrive in the same number and neither can be attributed.
+
+It is also the cheaper experiment. It needs no new fixture: if adding an
+exculpating clause to each existing focus area lowers `noise` without lowering
+`matched` on the current corpus, that is the whole result.
+
+## 3. Replay already exists
+
+This document says steps 2–4 "need a provider key". True, but worth stating
+plainly for whoever picks this up: the *machinery* is not missing.
+`uv run --frozen python scripts/guardian_bench.py --replay-finder <recording.json>`
+freezes a finder set and judges it, and `load_finder_recording` strips prior
+verdicts on read so arms stay comparable.
+(#302 was filed claiming this was absent and has been closed as redundant.)
+
+The only blocker is credentials.
+
+## Pre-registered gate
+
+Writing pass/fail criteria before spending money is what made the chunked-review
+no-go mechanical rather than motivated (#160). Same discipline here.
+
+**Arm A — exculpating-guard rewrite** (no new classes):
+1. mean `noise` per PR drops by ≥ 25% against the frozen baseline
+2. `matched` does not drop on any PR
+3. pr-141, the noise probe, does not regress
+
+**Arm B — class checklist** (security, concurrency, resource, error-handling;
+compact named classes, no per-class few-shot, per #247):
+1. pr-278 `gemini-client-never-closed` OR pr-313 `dangling-symlink-write-primitive`
+   is matched at least once in three runs — the hypothesis must show where it matters
+2. no PR drops more than 0.05 below its baseline recall
+3. mean noise does not exceed the Arm A result
+
+Ship each arm only on its own gate. If Arm B passes only with Arm A applied,
+say so explicitly rather than reporting the combined delta.
+
+## Still out of scope
+
+Unchanged from above, plus: do not run Arm B before Arm A has a number. The
+float few-shot regression happened because two effects were entangled in one
+measurement.

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.7.4"
+version = "0.8.0"
 description = "Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP."
 readme = "README.md"
 requires-python = ">=3.12"

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/src/cgis/guardian/findings.py

@@ -5,7 +5,11 @@ from typing import Literal
 from pydantic import BaseModel, Field
 
 Severity = Literal["critical", "major", "minor"]
-Category = Literal["logic", "contract", "tests", "types", "ontology"]
+# "security" exists so curated ground truth can name an exploitable defect (#315).
+# The finder prompt does not yet offer it as a choice — teaching the finder to
+# emit it is #258, and needs bench validation. Scoring is unaffected either way:
+# bench matching compares file and line range, never category.
+Category = Literal["logic", "contract", "tests", "types", "ontology", "security"]
 Verdict = Literal["confirmed", "refuted", "uncertain"]
 
 

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/src/cgis/guardian/render.py

@@ -11,6 +11,7 @@ _CATEGORY_LABEL = {
     "tests": "Test Coverage",
     "types": "Type Safety",
     "ontology": "Ontology",
+    "security": "Security",
 }
 
 

{codegraph_brain-0.7.4 → codegraph_brain-0.8.0}/uv.lock

@@ -261,7 +261,7 @@ wheels = [
 
 [[package]]
 name = "codegraph-brain"
-version = "0.7.4"
+version = "0.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

codegraph_brain-0.7.4/.github/workflows/ci.yml

@@ -1,46 +0,0 @@
-name: Continuous Integration
-
-on:
-  push:
-    branches: [ main, dev, "feat/**", "fix/**", "docs/**" ]
-  pull_request:
-    branches: [ main ]
-
-jobs:
-  python-ci:
-    name: Python Verification
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-
-      - name: Setup uv
-        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
-        with:
-          enable-cache: true
-
-      - name: Lockfile in step with pyproject
-        # This is the only step that validates the lockfile. `--frozen` below stops
-        # uv rewriting uv.lock, but it does not check that the lock is current —
-        # that is `--locked`. Keeping the check explicit gives a clearer failure
-        # than a sync error, and it still runs first so an unfrozen uv could never
-        # repair the lock ahead of it.
-        run: uv lock --check
-
-      - name: Install Dependencies
-        run: uv sync --frozen --group dev
-
-      - name: Ruff Format Check
-        run: uv run --frozen ruff format --check .
-
-      - name: Ruff Lint
-        run: uv run --frozen ruff check .
-
-      - name: Interrogate (≥90% docstring coverage)
-        run: uv run --frozen interrogate -v --fail-under 90 src/cgis
-
-      - name: Mypy (strict)
-        run: uv run --frozen mypy src
-
-      - name: Pytest
-        run: uv run --frozen pytest --cov=cgis --cov-report=term-missing

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

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