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

{codegraph_brain-0.7.2 → codegraph_brain-0.7.4}/.github/workflows/autodoc.yml

@@ -28,15 +28,15 @@ jobs:
           enable-cache: true
 
       - name: Install CGIS
-        run: uv sync
+        run: uv sync --frozen
 
       - name: Self-ingest core engine
-        run: uv run cgis ingest ./src --output /tmp/self_graph.db
+        run: uv run --frozen cgis ingest ./src --output /tmp/self_graph.db
 
       - name: Generate pipeline flow diagram
         run: |
           mkdir -p docs/architecture/diagrams
-          uv run cgis trace "cgis.pipeline.IngestionPipeline.run" \
+          uv run --frozen cgis trace "cgis.pipeline.IngestionPipeline.run" \
             --db /tmp/self_graph.db \
             --depth 1 \
             --format mermaid \
@@ -44,21 +44,21 @@ jobs:
             > docs/architecture/diagrams/pipeline_flow.mermaid
 
       - name: Compute graph health badge
-        run: uv run python scripts/generate_health.py --db /tmp/self_graph.db
+        run: uv run --frozen python scripts/generate_health.py --db /tmp/self_graph.db
 
       - name: Inject graph into README.md
         run: |
-          uv run python scripts/inject_readme_graph.py \
+          uv run --frozen python scripts/inject_readme_graph.py \
             --db /tmp/self_graph.db \
             --fqn "cgis.pipeline.IngestionPipeline.run" \
             --depth 1 \
             --path-prefix "src/"
 
       - name: Generate MCP reference manual
-        run: uv run python scripts/generate_mcp_ref.py
+        run: uv run --frozen python scripts/generate_mcp_ref.py
 
       - name: Sync schema docs from source
-        run: uv run python scripts/generate_schema_docs.py
+        run: uv run --frozen python scripts/generate_schema_docs.py
 
       - name: Open PR with generated docs
         uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676  # v7

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

@@ -0,0 +1,46 @@
+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.2 → codegraph_brain-0.7.4}/.github/workflows/guardian.yml

@@ -67,10 +67,10 @@ jobs:
         uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
 
       - name: Install dependencies
-        run: uv sync --extra guardian
+        run: uv sync --frozen --extra guardian
 
       - name: Build code graph
-        run: uv run cgis ingest ./src --output graph.db
+        run: uv run --frozen cgis ingest ./src --output graph.db
 
       - name: Restore metrics from data branch
         run: |
@@ -91,7 +91,7 @@ jobs:
           GUARDIAN_SKEPTIC: ${{ vars.GUARDIAN_SKEPTIC }}
           GUARDIAN_SKEPTIC_MODEL: ${{ vars.GUARDIAN_SKEPTIC_MODEL }}
         run: |
-          uv run python scripts/guardian_review.py \
+          uv run --frozen python scripts/guardian_review.py \
             --output guardian_report.md \
             --db graph.db \
             --pr "$PR_NUMBER" \
@@ -219,7 +219,7 @@ jobs:
           git show origin/data/guardian-metrics:guardian_metrics.jsonl \
             > guardian_metrics.jsonl
 
-          uv run cgis guardian-rate "$PR_NUMBER" "$APPLIED" \
+          uv run --frozen cgis guardian-rate "$PR_NUMBER" "$APPLIED" \
             --metrics guardian_metrics.jsonl
 
           if git ls-remote --exit-code origin data/guardian-metrics > /dev/null 2>&1; then

codegraph_brain-0.7.4/.github/workflows/pr-title.yml

@@ -0,0 +1,51 @@
+name: PR Title
+
+# The repository squash-merges, so the PR title becomes the commit subject that
+# release-please parses. A title it does not recognise is dropped from the
+# changelog silently — no warning, no failure. That has now happened twice:
+# #297 ("drift trust batch: …", a descriptive title) and #313
+# ("security(mcp): …", a type that does not exist), the second of which would
+# have shipped a security fix invisibly.
+on:
+  pull_request:
+    branches: [ main ]
+    # `edited` matters: without it, fixing a rejected title would not re-run
+    # the check. Kept in a separate workflow from ci.yml so retitling does not
+    # replay the whole test suite.
+    types: [ opened, edited, reopened, synchronize ]
+
+permissions: {}
+
+jobs:
+  conventional-title:
+    name: Conventional commit title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check the title release-please will parse
+        env:
+          # Never interpolate an untrusted title straight into `run:` — it is
+          # attacker-controlled text. Through the environment it is just data.
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -euo pipefail
+          # Types release-please understands. Anything else is dropped from the
+          # changelog without complaint, which is the failure being prevented.
+          TYPES='feat|fix|docs|chore|style|refactor|perf|test|build|ci|revert'
+          if printf '%s' "$PR_TITLE" | grep -qE "^($TYPES)(\([a-z0-9._/-]+\))?!?: .+"; then
+            printf '::notice::PR title is a conventional commit.\n'
+            exit 0
+          fi
+          printf '::error::PR title is not a conventional commit: %s\n' "$PR_TITLE"
+          cat >&2 <<'MSG'
+
+          This repository squash-merges, so the PR title becomes the commit
+          subject release-please reads. An unrecognised type is dropped from the
+          CHANGELOG silently.
+
+          Expected:  <type>(<optional scope>): <description>
+          Types:     feat fix docs chore style refactor perf test build ci revert
+
+          Note there is no `security` type — use `fix` with a scope:
+              fix(mcp): validate db_path before cgis_ingest creates a database
+          MSG
+          exit 1

codegraph_brain-0.7.4/.github/workflows/release-please.yml

@@ -0,0 +1,147 @@
+name: Release Please
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  release-please:
+    name: Release Please
+    runs-on: ubuntu-latest
+    permissions:
+      # Scoped to this job only: the publish job below must never inherit
+      # write access to the repository.
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      release_pr: ${{ steps.release.outputs.pr }}
+    steps:
+      - name: Mint a GitHub App token
+        id: app-token
+        # A GITHUB_TOKEN-authored PR leaves its checks parked in
+        # `action_required` forever, so release-please needs an identity of its
+        # own. App tokens beat a PAT: one hour of life, auto-rotated, scoped to
+        # this repo, and not tied to anyone's personal account.
+        # continue-on-error: an unconfigured App must degrade, not break the release.
+        continue-on-error: true
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+        with:
+          # Accepted from either store: the App ID is not sensitive, so a repo
+          # variable is conventional, but it is commonly filed as a secret.
+          app-id: ${{ vars.CGIS_APP_ID || secrets.CGIS_APP_ID }}
+          private-key: ${{ secrets.CGIS_APP_PRIVATE_KEY }}
+
+      - name: Run release-please
+        id: release
+        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071  # v4.4.1
+        with:
+          # Falls back to GITHUB_TOKEN when the App is not configured — the
+          # release still opens, its checks just need a manual nudge.
+          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  relock:
+    name: Re-lock the release PR
+    needs: release-please
+    # Only when release-please actually has an open release PR to amend.
+    if: needs.release-please.outputs.release_pr != ''
+    runs-on: ubuntu-latest
+    permissions:
+      # Narrower than the release job: this one only pushes a lockfile.
+      contents: write
+    steps:
+      - name: Mint a GitHub App token
+        id: app-token
+        # A GITHUB_TOKEN-authored PR leaves its checks parked in
+        # `action_required` forever, so release-please needs an identity of its
+        # own. App tokens beat a PAT: one hour of life, auto-rotated, scoped to
+        # this repo, and not tied to anyone's personal account.
+        # continue-on-error: an unconfigured App must degrade, not break the release.
+        continue-on-error: true
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+        with:
+          # Accepted from either store: the App ID is not sensitive, so a repo
+          # variable is conventional, but it is commonly filed as a secret.
+          app-id: ${{ vars.CGIS_APP_ID || secrets.CGIS_APP_ID }}
+          private-key: ${{ secrets.CGIS_APP_PRIVATE_KEY }}
+
+      - name: Checkout the release branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: ${{ fromJSON(needs.release-please.outputs.release_pr).headBranchName }}
+          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+        with:
+          enable-cache: true
+
+      - name: Re-lock and push if the version moved
+        run: |
+          set -euo pipefail
+          # release-please bumps pyproject.toml but never re-resolves uv.lock, so
+          # the lockfile's own version entry falls a release behind and the CI
+          # `uv lock --check` gate fails on every release PR (#303).
+          uv lock
+          if git diff --quiet -- uv.lock; then
+            echo "uv.lock already in step with pyproject.toml"
+            exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add uv.lock
+          git commit -m "chore: re-lock uv.lock for the release"
+          git push
+
+  publish:
+    name: Publish to PyPI
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codegraph-brain
+    permissions:
+      # Mints the short-lived OIDC token PyPI exchanges for an upload token.
+      # This is the whole point of trusted publishing: no API token in secrets.
+      id-token: write
+      # Lets the publish action attach PEP 740 provenance attestations.
+      attestations: write
+      contents: read
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+        with:
+          enable-cache: true
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify metadata
+        # Pinned and wheel-only: this job holds publish rights, so the tooling
+        # it pulls in must not be a floating version that can run setup scripts.
+        run: uvx --no-build --from "twine==7.0.0" twine check dist/*
+
+      - name: Verify version matches the tag
+        env:
+          TAG_NAME: ${{ needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          built=$(ls dist/*.whl | sed -E 's/.*-([0-9][^-]*)-py3.*/\1/')
+          echo "tag=$TAG_NAME built=$built"
+          case "$TAG_NAME" in
+            *"$built") ;;
+            *) echo "::error::tag $TAG_NAME does not match built version $built"; exit 1 ;;
+          esac
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2

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

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

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

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.7.4](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.3...codegraph-brain-v0.7.4) (2026-08-01)
+
+
+### Bug Fixes
+
+* **mcp:** validate db_path before cgis_ingest creates a database ([#313](https://github.com/zaebee/codegraph-brain/issues/313)) ([2c5499b](https://github.com/zaebee/codegraph-brain/commit/2c5499b8fb7f0d40a03144417c3210900371d499)), closes [#312](https://github.com/zaebee/codegraph-brain/issues/312)
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#314](https://github.com/zaebee/codegraph-brain/issues/314)) ([7d5b666](https://github.com/zaebee/codegraph-brain/commit/7d5b66669f9dfa40e2fc86dd59a4baf492a9342e))
+
+## [0.7.3](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.2...codegraph-brain-v0.7.3) (2026-07-31)
+
+
+### Bug Fixes
+
+* **assets:** drop the argv-driven output path from the avatar generator ([#308](https://github.com/zaebee/codegraph-brain/issues/308)) ([d118074](https://github.com/zaebee/codegraph-brain/commit/d118074a6b2137f789b4978f870f5496ee1135b5))
+* **ci:** read the App ID from a secret as well as a variable ([#306](https://github.com/zaebee/codegraph-brain/issues/306)) ([90513bc](https://github.com/zaebee/codegraph-brain/commit/90513bc3f588241848fd7404f9be5b6479a72293))
+
 ## [0.7.2](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.7.1...codegraph-brain-v0.7.2) (2026-07-31)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-brain
-Version: 0.7.2
+Version: 0.7.4
 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/docs/assets/.gitignore

@@ -0,0 +1 @@
+_variants/

codegraph_brain-0.7.4/docs/assets/cgis-app-avatar.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" width="200" height="200"><rect width="200" height="200" rx="44" fill="#0d1526"/><line x1="113.2" y1="55.7" x2="142.8" y2="86.3" stroke="#64748b" stroke-width="8" stroke-linecap="round"/><line x1="142.8" y1="113.7" x2="113.2" y2="144.3" stroke="#64748b" stroke-width="8" stroke-linecap="round"/><line x1="86.8" y1="55.7" x2="57.2" y2="86.3" stroke="#fbbf24" stroke-width="9" stroke-linecap="round"/><line x1="57.2" y1="113.7" x2="86.8" y2="144.3" stroke="#fbbf24" stroke-width="9" stroke-linecap="round"/><circle cx="100" cy="42" r="18" fill="#22d3ee"/><circle cx="44" cy="100" r="18" fill="#fbbf24"/><circle cx="156" cy="100" r="18" fill="#a78bfa"/><circle cx="100" cy="158" r="18" fill="#22d3ee"/></svg>

codegraph_brain-0.7.4/docs/assets/generate_avatar.py

@@ -0,0 +1,123 @@
+"""Generate the cgis GitHub App avatar.
+
+Ships `v3-lit-path` as `cgis-app-avatar.png`; the other two are kept so the
+alternatives are on the record rather than lost in a chat log.
+
+The motif comes from the domain rather than decoration: cgis's drift alphabet is
+built on directed triads (`_TRICODES` / `TRIAD_ORDER`), so the glyphs are actual
+triad shapes — 021D (diverging) and the layered_dag ideal.
+
+No arrowheads. SVG markers scale by stroke-width by default (a 4.5-unit head at
+stroke 9 renders as a 40-unit blob), and even sized correctly an arrowhead is
+mush at the 40px a bot avatar occupies in a PR thread. Hierarchy is carried by
+node size and colour instead.
+
+Rendered at 400px for upload and 40px to check legibility at comment size.
+"""
+
+import pathlib
+
+import cairosvg
+
+BG = "#0d1526"
+EDGE = "#64748b"
+CYAN = "#22d3ee"
+VIOLET = "#a78bfa"
+AMBER = "#fbbf24"
+
+HEAD = (
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" width="200" height="200">'
+    f'<rect width="200" height="200" rx="44" fill="{BG}"/>'
+)
+TAIL = "</svg>"
+
+
+def edge(
+    p1: tuple[float, float], p2: tuple[float, float], *, colour: str = EDGE, w: float = 8
+) -> str:
+    """A graph edge, trimmed at both ends so it meets the node rims cleanly."""
+    (x1, y1), (x2, y2) = p1, p2
+    dx, dy = x2 - x1, y2 - y1
+    length = (dx * dx + dy * dy) ** 0.5
+    ux, uy = dx / length, dy / length
+    pad = 19
+    return (
+        f'<line x1="{x1 + ux * pad:.1f}" y1="{y1 + uy * pad:.1f}" '
+        f'x2="{x2 - ux * pad:.1f}" y2="{y2 - uy * pad:.1f}" '
+        f'stroke="{colour}" stroke-width="{w}" stroke-linecap="round"/>'
+    )
+
+
+def node(p: tuple[float, float], colour: str, r: float = 18) -> str:
+    """A graph node."""
+    return f'<circle cx="{p[0]}" cy="{p[1]}" r="{r}" fill="{colour}"/>'
+
+
+TOP, LEFT, RIGHT, BOTTOM = (100, 42), (44, 100), (156, 100), (100, 158)
+
+# 1. layered_dag — diverge at the top, converge at the bottom.
+v1 = (
+    HEAD
+    + edge(TOP, LEFT)
+    + edge(TOP, RIGHT)
+    + edge(LEFT, BOTTOM)
+    + edge(RIGHT, BOTTOM)
+    + node(TOP, CYAN)
+    + node(LEFT, VIOLET)
+    + node(RIGHT, VIOLET)
+    + node(BOTTOM, CYAN)
+    + TAIL
+)
+
+# 2. 021D on its own — fewest strokes, best legibility at 40px.
+T2, BL2, BR2 = (100, 54), (48, 144), (152, 144)
+v2 = (
+    HEAD
+    + edge(T2, BL2, w=9)
+    + edge(T2, BR2, w=9)
+    + node(T2, CYAN, 21)
+    + node(BL2, VIOLET, 21)
+    + node(BR2, VIOLET, 21)
+    + TAIL
+)
+
+# 3. layered_dag with one path lit — structure, plus the analysis laid over it.
+v3 = (
+    HEAD
+    + edge(TOP, RIGHT)
+    + edge(RIGHT, BOTTOM)
+    + edge(TOP, LEFT, colour=AMBER, w=9)
+    + edge(LEFT, BOTTOM, colour=AMBER, w=9)
+    + node(TOP, CYAN)
+    + node(LEFT, AMBER)
+    + node(RIGHT, VIOLET)
+    + node(BOTTOM, CYAN)
+    + TAIL
+)
+
+HERE = pathlib.Path(__file__).parent
+# Variants land in a gitignored scratch dir; only the chosen one is versioned,
+# so re-running this never litters docs/assets.
+VARIANTS = HERE / "_variants"
+VARIANTS.mkdir(parents=True, exist_ok=True)
+
+CHOSEN = "v3-lit-path"
+
+for name, svg in (("v1-layered-dag", v1), ("v2-fanout", v2), ("v3-lit-path", v3)):
+    (VARIANTS / f"{name}.svg").write_text(svg)
+    for px in (400, 40):
+        cairosvg.svg2png(
+            bytestring=svg.encode(),
+            write_to=str(VARIANTS / f"{name}-{px}.png"),
+            output_width=px,
+            output_height=px,
+        )
+    if name == CHOSEN:
+        (HERE / "cgis-app-avatar.svg").write_text(svg)
+        cairosvg.svg2png(
+            bytestring=svg.encode(),
+            write_to=str(HERE / "cgis-app-avatar.png"),
+            output_width=400,
+            output_height=400,
+        )
+    print(f"rendered {name}" + ("  <- shipped as cgis-app-avatar.*" if name == CHOSEN else ""))

{codegraph_brain-0.7.2 → codegraph_brain-0.7.4}/docs/how-to/MCP_REFERENCE.md

@@ -176,9 +176,14 @@ Show the structural layout (CONTAINS/DECLARES) of a module or class.
 Scan a local directory, extract all symbols, resolve links, and build the graph DB.
 
     Use this to initialise or refresh the code knowledge graph for a project.
-    Paths are normalised relative to the workspace root so the database is
+    Node FQNs are normalised relative to the workspace root so the graph is
     portable across machines.
 
+    ``db_path`` must name a database — it has to end in ``.db``, ``.sqlite`` or
+    ``.sqlite3``, live in a directory that already exists, and not point at an
+    existing file that is not a SQLite database. cgis will not create parent
+    directories.
+
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
     whole-graph total. Set ``full_rebuild=True`` to re-scan every file and

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

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.7.2"
+version = "0.7.4"
 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.2 → codegraph_brain-0.7.4}/src/cgis/api/mcp_server.py

@@ -85,20 +85,92 @@ def _render_subgraph(
     return f"❌ Unknown format '{output_format}'. Use 'mermaid' or 'json'."
 
 
+#: Names cgis will create a database under. Everything else is refused, so an
+#: agent cannot be talked into materialising `~/.ssh/authorized_keys` (#312).
+_DB_SUFFIXES = frozenset({".db", ".sqlite", ".sqlite3"})
+
+#: First 16 bytes of any SQLite file.
+_SQLITE_MAGIC = b"SQLite format 3\x00"
+
+
+def _reject_db_path(db_path: str) -> str | None:
+    """Return a refusal message for an unusable ``db_path``, or None if it is fine.
+
+    ``cgis_ingest`` is the only MCP tool that creates its database — the other
+    twelve refuse a path that does not already exist, which is guard enough for
+    them. It needs a different one: it reads untrusted repository content and is
+    then told by the same agent where to write, so ``db_path`` is attacker-
+    reachable in a way the read-only tools' paths are not.
+
+    Refuses an unexpected suffix, a missing parent directory (creating a tree is
+    never wanted), a directory target, and an existing file that is not a
+    database. The last is belt-and-braces — SQLite already declines to open a
+    non-database — but it fails with a message that says why.
+
+    Everything is judged on the **resolved** path. A dangling symlink is the
+    bypass this guard exists to stop: ``attack.db`` pointing at a target that
+    does not exist yet makes ``is_file()`` return False, every check passes, and
+    SQLite creates the target. Resolving first means the suffix rule applies to
+    where the write actually lands. (A symlink to an *existing* non-database was
+    already refused by the magic-byte check.)
+
+    The filesystem probes are wrapped: this runs *before* ``cgis_ingest``'s own
+    try/except, and ``Path.resolve()``, ``Path.is_dir()`` and friends propagate
+    ``OSError`` (a ``PermissionError`` on the parent, or a symlink loop), which
+    would escape the tool as a crash instead of a message the agent can act on.
+    """
+    try:
+        path = Path(db_path).resolve()
+    except OSError as exc:
+        return f"❌ Refusing db_path '{db_path}': path is inaccessible ({exc})."
+    # Case-insensitive: `.DB` carries the same intent, and on a case-insensitive
+    # filesystem it is literally the same file.
+    if path.suffix.lower() not in _DB_SUFFIXES:
+        allowed = ", ".join(sorted(_DB_SUFFIXES))
+        return f"❌ Refusing db_path '{db_path}': name must end in one of {allowed}."
+    try:
+        if path.is_dir():
+            return f"❌ Refusing db_path '{db_path}': it is a directory."
+        if not path.parent.is_dir():
+            return (
+                f"❌ Refusing db_path '{db_path}': parent directory does not exist. "
+                "cgis will not create one."
+            )
+        if path.is_file() and path.stat().st_size > 0:
+            with path.open("rb") as fh:
+                if fh.read(len(_SQLITE_MAGIC)) != _SQLITE_MAGIC:
+                    return (
+                        f"❌ Refusing db_path '{db_path}': existing file is not a SQLite database."
+                    )
+    except OSError as exc:
+        return f"❌ Refusing db_path '{db_path}': path is inaccessible ({exc})."
+    return None
+
+
 @mcp.tool()
 def cgis_ingest(project_path: str, db_path: str = _DEFAULT_DB, full_rebuild: bool = False) -> str:
     """Scan a local directory, extract all symbols, resolve links, and build the graph DB.
 
     Use this to initialise or refresh the code knowledge graph for a project.
-    Paths are normalised relative to the workspace root so the database is
+    Node FQNs are normalised relative to the workspace root so the graph is
     portable across machines.
 
+    ``db_path`` must name a database — it has to end in ``.db``, ``.sqlite`` or
+    ``.sqlite3``, live in a directory that already exists, and not point at an
+    existing file that is not a SQLite database. cgis will not create parent
+    directories.
+
     By default the ingest is **incremental**: only changed/new files are
     re-scanned, and the summary reports both what changed this run and the
     whole-graph total. Set ``full_rebuild=True`` to re-scan every file and
     overwrite the database from scratch — use this to drop nodes for files that
     were deleted or renamed, which an incremental run leaves behind.
     """
+    refusal = _reject_db_path(db_path)
+    if refusal is not None:
+        logger.warning("MCP ingest refused db_path", db=db_path)
+        return refusal
+
     pipeline = IngestionPipeline(_EXTRACTORS)
     try:
         with SQLiteStore(db_path) as store:

{codegraph_brain-0.7.2 → codegraph_brain-0.7.4}/src/cgis/resolver/engine.py

@@ -126,7 +126,7 @@ class ResolverEngine:
 
     def _ensure_virtual_node(self, target: str, virtual_nodes: dict[str, Node]) -> None:
         """Create a virtual boundary node for target if it is not already in the graph."""
-        if target not in self._index.nodes and target not in virtual_nodes:
+        if not self._index.has_node(target) and target not in virtual_nodes:
             virtual_nodes[target] = self._make_virtual_node(
                 target, self._index.classify_fqn(target)
             )