codegraph-brain 0.23.0__tar.gz → 0.23.2__tar.gz

codegraph_brain-0.23.2/.github/workflows/mcp-registry.yml

@@ -0,0 +1,81 @@
+name: Publish to MCP Registry
+
+# A separate workflow file, not a job in release-please.yml: PyPI trusted
+# publishing is bound to that file, so nothing here can mint a PyPI upload token
+# whatever the publisher's environment restriction is (#471).
+#
+# Runs after every Release Please run and publishes only a tagged version the
+# registry does not list yet (scripts/mcp_registry_gate.sh), so ordinary pushes
+# to main are no-ops.
+#
+# A failed Release Please run (PyPI publish or relock) skips this workflow: the
+# red run is the signal. Recover with "Re-run failed jobs" there, or dispatch
+# this workflow on main.
+on:
+  workflow_run:
+    workflows: ["Release Please"]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: mcp-registry
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish server.json
+    # Dispatch only from main, so an older branch can't publish its own server.json.
+    # The repository check is defence in depth: Release Please never runs for forks.
+    if: >-
+      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') ||
+      (github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.head_repository.full_name == github.repository)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # OIDC for `mcp-publisher login github-oidc`: no stored registry secret.
+      id-token: write
+    env:
+      # Pinned and checksum-verified: this job holds a registry identity, so it must
+      # not run whatever `releases/latest` happens to be. Bump both together; a
+      # binary too old for the registry fails login with "invalid audience".
+      MCP_PUBLISHER_VERSION: "1.8.1"
+      MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+    steps:
+      - name: Checkout the released commit
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+          persist-credentials: false
+
+      - name: Decide whether to publish
+        id: gate
+        run: bash scripts/mcp_registry_gate.sh check >> "$GITHUB_OUTPUT"
+
+      - name: Wait for the version on PyPI
+        if: steps.gate.outputs.publish == 'true'
+        run: bash scripts/mcp_registry_gate.sh wait-pypi
+
+      - name: Install mcp-publisher
+        if: steps.gate.outputs.publish == 'true'
+        run: |
+          set -euo pipefail
+          url="https://github.com/modelcontextprotocol/registry/releases/download/v${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz"
+          curl --proto '=https' --tlsv1.2 -fsSL "$url" -o mcp-publisher.tar.gz
+          echo "${MCP_PUBLISHER_SHA256}  mcp-publisher.tar.gz" | sha256sum --check --strict
+          tar -xzf mcp-publisher.tar.gz mcp-publisher
+
+      - name: Validate server.json
+        if: steps.gate.outputs.publish == 'true'
+        run: ./mcp-publisher validate
+
+      - name: Log in with GitHub OIDC
+        if: steps.gate.outputs.publish == 'true'
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish
+        if: steps.gate.outputs.publish == 'true'
+        run: ./mcp-publisher publish

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

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

{codegraph_brain-0.23.0 → codegraph_brain-0.23.2}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.23.2](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.1...codegraph-brain-v0.23.2) (2026-09-17)
+
+
+### Bug Fixes
+
+* **cli:** impact/trace list each neighbour once, JSON each edge once ([#475](https://github.com/zaebee/codegraph-brain/issues/475)) ([9c93b4b](https://github.com/zaebee/codegraph-brain/commit/9c93b4ba5748f99fe2aeb43d698c9d9628e6295a))
+
+## [0.23.1](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.0...codegraph-brain-v0.23.1) (2026-09-17)
+
+
+### Bug Fixes
+
+* **audit:** an audit that selects no sources is an error, not an empty pass ([#472](https://github.com/zaebee/codegraph-brain/issues/472)) ([9f93010](https://github.com/zaebee/codegraph-brain/commit/9f93010c286d0b189f3c3350833a5cf557316d8f))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#468](https://github.com/zaebee/codegraph-brain/issues/468)) ([4c02171](https://github.com/zaebee/codegraph-brain/commit/4c021719776d00ae2f3539409ba847995f79c48e))
+* auto-sync architecture graph and MCP reference ([#473](https://github.com/zaebee/codegraph-brain/issues/473)) ([567b091](https://github.com/zaebee/codegraph-brain/commit/567b09190c61ab5fc2b5b26c0b445bff2cbe5a12))
+
 ## [0.23.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.22.0...codegraph-brain-v0.23.0) (2026-09-17)
 
 

{codegraph_brain-0.23.0 → codegraph_brain-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.23.0
+Version: 0.23.2
 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.23.0 → codegraph_brain-0.23.2}/docs/how-to/MCP_REFERENCE.md

@@ -20,10 +20,10 @@ Analyse transitive upstream callers of a specific FQN.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `output_format` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Maximum edge hops upstream. Every edge type counts as a hop — CALLS, but also IMPORTS, CONTAINS and REFERENCES — so modules importing the target and the file containing it appear alongside its callers. |
+| `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---
 
@@ -41,13 +41,16 @@ Reachability/authorization audit — which sources never reach a checkpoint (#17
     ``fqn``/``file``/``line``. Generalizes to validators, event tracking, or
     service-layer-boundary rules by pointing ``target`` at the required node.
 
+    A selection that matches no source returns a ❌ message, not an empty
+    ``{covered: [], gaps: []}`` that would read as a passing audit (#467).
+
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `target` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `from_type` | `any` |  |  |
-| `from_prefix` | `any` |  |  |
-| `depth` | `integer` |  |  |
+| `target` | `string` | ✓ | FQN of the checkpoint every source must reach, e.g. an ownership check. A unique dot-boundary suffix also resolves. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `from_type` | `any` |  | NodeType of the sources to audit, e.g. ROUTE_HANDLER, API_ENDPOINT or FUNCTION (any case). Give this, from_prefix, or both. |
+| `from_prefix` | `any` |  | Only audit sources at or under this FQN prefix, matched on whole dot-segments. A selection matching no source is an error naming the whole-segment prefixes it may have meant. Combined with from_type when both are given. |
+| `depth` | `integer` |  | Maximum reachability depth; a longer path is reported as a gap. |
 
 ---
 
@@ -70,10 +73,10 @@ Compile an agent-facing GraphRAG context package for a focal FQN (#19).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `source_root` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Call hops around the focal node; 1 means direct callers and callees. |
+| `source_root` | `string` |  | Directory the graph's stored file paths are relative to — normally the project_path given to cgis_ingest; prefer an absolute path. Empty means the server's working directory, so source shows as unavailable when the server runs elsewhere. |
 
 ---
 
@@ -102,11 +105,11 @@ Report per-domain architectural drift against declared ideal patterns.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `patterns_path` | `string` |  |  |
-| `max_drift` | `number` |  |  |
-| `profile` | `any` |  |  |
-| `max_residual` | `number` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `patterns_path` | `string` |  | patterns.yaml (.yaml or .yml) declaring each domain's expected pattern and tolerance, relative to the server's working directory. cgis_init_ontology proposes one. |
+| `max_drift` | `number` |  | Drift tolerance for domains that declare no drift_tolerance of their own. |
+| `profile` | `any` |  | Score only domains with this profile, plus profile-less ones — e.g. one language when patterns.yaml mixes several. |
+| `max_residual` | `number` |  | Distance to the nearest template beyond which a domain's fit band is "none" (no template fits). |
 
 ---
 
@@ -150,10 +153,10 @@ Classes nothing in production builds, extends or names — dead-code candidates
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `prefix` | `any` |  |  |
-| `include_tests` | `boolean` |  |  |
-| `include_generated` | `boolean` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `prefix` | `any` |  | Only consider classes under this FQN prefix, cut on a dot boundary. |
+| `include_tests` | `boolean` |  | Count test code as a user, so the report means "unreachable from anywhere". |
+| `include_generated` | `boolean` |  | Include machine-generated classes, which are hidden by default. |
 
 ---
 
@@ -170,11 +173,11 @@ Resolve a partial symbol name to candidate FQNs (substring match, ranked).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `query` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `kind` | `any` |  |  |
-| `fqn_prefix` | `any` |  |  |
-| `limit` | `integer` |  |  |
+| `query` | `string` | ✓ | Leaf symbol name to search for, without dots (e.g. get_flow_result) — not an FQN. Case-insensitive substring match, ranked exact > prefix > substring. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `kind` | `any` |  | Only return this node type, e.g. FUNCTION, METHOD or CLASS (any case). An unknown type matches nothing rather than raising an error. |
+| `fqn_prefix` | `any` |  | Only return symbols at or under this FQN prefix, matched on whole dot-segments: app.svc does not match app.svc_alt, and a partial segment matches nothing. |
+| `limit` | `integer` |  | Maximum number of candidates to return. |
 
 ---
 
@@ -200,7 +203,7 @@ Report the motif census across the repository's structural tiers.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
 
 ---
 
@@ -215,10 +218,10 @@ Show the structural layout (CONTAINS/DECLARES) of a module or class.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `output_format` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Maximum containment levels to descend (module → class → method). |
+| `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---
 
@@ -245,9 +248,9 @@ Scan a local directory, extract all symbols, resolve links, and build the graph
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `project_path` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `full_rebuild` | `boolean` |  |  |
+| `project_path` | `string` | ✓ | Root directory of the project to scan. A relative path resolves against the MCP server's working directory. |
+| `db_path` | `string` |  | Where to write the graph: must end in .db, .sqlite or .sqlite3, in a directory that already exists, and must not be an existing non-SQLite file. A relative path resolves against the server's working directory. |
+| `full_rebuild` | `boolean` |  | Re-scan every file from scratch instead of the incremental default. |
 
 ---
 
@@ -263,10 +266,10 @@ Propose a starter patterns.yaml from the measured graph (read-only).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `margin` | `number` |  |  |
-| `min_nodes` | `integer` |  |  |
-| `depth` | `any` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `margin` | `number` |  | Headroom added to each measured score to form the proposed tolerance. |
+| `min_nodes` | `integer` |  | Domains with fewer nodes stay hygiene-only instead of getting a label. |
+| `depth` | `any` |  | Fixed FQN segment depth for domain discovery (positive); omit to pick it automatically. |
 
 ---
 
@@ -297,10 +300,10 @@ Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `limit` | `integer` |  |  |
-| `exclude` | `any` |  |  |
-| `scope` | `any` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `limit` | `integer` |  | Top-N rows returned per section. |
+| `exclude` | `any` |  | Drop nodes whose FQN contains any of these dot-segments, e.g. ["tests"]; they are removed from PageRank propagation too. |
+| `scope` | `any` |  | Keep only nodes under any of these dot-prefixes, e.g. ["domains.billing"]; rank still propagates over the whole graph. |
 
 ---
 
@@ -319,10 +322,10 @@ Suggest sub-package boundaries for a package from its dependency communities.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `prefix` | `any` |  |  |
-| `with_calls` | `boolean` |  |  |
-| `min_q` | `number` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `prefix` | `any` |  | FQN prefix of the package to analyse, e.g. cgis.query, matched on whole dot-segments. Needed in practice: without it the verdict is no_signal. |
+| `with_calls` | `boolean` |  | Use the combined import + call graph instead of imports only. |
+| `min_q` | `number` |  | Modularity threshold: at or above it, a package whose layout disagrees with its communities is flagged split (or consolidate, if over-split). |
 
 ---
 
@@ -341,10 +344,10 @@ Trace the execution call-graph starting from a specific FQN downwards.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `fqn` | `string` | ✓ |  |
-| `db_path` | `string` |  |  |
-| `depth` | `integer` |  |  |
-| `output_format` | `string` |  |  |
+| `fqn` | `string` | ✓ | Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up. |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `depth` | `integer` |  | Maximum edge hops downstream. Every edge type counts as a hop — CALLS, but also IMPORTS, CONTAINS and REFERENCES — so from a module the first hops are mostly imports and structure. |
+| `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
 
 ---
 
@@ -357,7 +360,7 @@ Report graph integrity as JSON: edge resolution stats + health verdict.
 
 | Argument | Type | Required | Description |
 | :--- | :--- | :---: | :--- |
-| `db_path` | `string` |  |  |
-| `threshold` | `number` |  |  |
+| `db_path` | `string` |  | SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path. |
+| `threshold` | `number` |  | Highest unresolved-edge ratio (0-1) still reported as healthy. |
 
 ---

{codegraph_brain-0.23.0 → codegraph_brain-0.23.2}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.23.0"
+version = "0.23.2"
 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.23.2/scripts/mcp_registry_gate.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Decide whether server.json's version should be published to the MCP Registry,
+# and wait until PyPI can back it (#471).
+#
+#   scripts/mcp_registry_gate.sh check     → prints publish=true|false (for $GITHUB_OUTPUT)
+#   scripts/mcp_registry_gate.sh wait-pypi → blocks until PyPI serves the version
+#
+# `check` is what makes the workflow safe to run after *every* Release Please run:
+# only a tagged release that the registry does not list yet is published, so a
+# docs push to main is a no-op and a re-run never double-publishes.
+#
+# Every lookup fails closed. `publish=false` is printed only on a definite answer
+# (no such tag, version already listed); a network error or an unexpected
+# response exits non-zero, because a silently skipped release is exactly what
+# this automation exists to prevent.
+#
+# `wait-pypi` exists because the registry verifies ownership by fetching
+# pypi.org/pypi/<pkg>/<version>/json and looking for the mcp-name marker, and a
+# fresh upload is not always visible there straight away (0.23.0 and 0.23.1 both
+# failed a `pip install` for a few minutes after the publish job went green).
+set -euo pipefail
+
+REGISTRY="${MCP_REGISTRY_URL:-https://registry.modelcontextprotocol.io}"
+PYPI="${PYPI_URL:-https://pypi.org}"
+TAG_PREFIX="${TAG_PREFIX:-codegraph-brain-v}"
+WAIT_SECONDS="${WAIT_SECONDS:-600}"
+POLL_SECONDS="${POLL_SECONDS:-15}"
+
+fail() {
+  echo "::error::$*" >&2
+  exit 1
+}
+
+read_field() {
+  local filter="$1" label="$2" value
+  value=$(jq -r "${filter} // empty" server.json) || fail "server.json is not valid JSON."
+  [[ -n "$value" ]] || fail "server.json has no ${label} (${filter})."
+  printf '%s' "$value"
+}
+
+name=$(read_field .name "server name")
+version=$(read_field .version "version")
+package=$(read_field 'first(.packages[]? | select(.registryType == "pypi") | .identifier)' "PyPI package")
+
+check() {
+  local tag="refs/tags/${TAG_PREFIX}${version}" rc=0
+  git ls-remote --exit-code --tags origin "$tag" >/dev/null || rc=$?
+  case "$rc" in
+    0) ;;
+    2)
+      echo "No tag ${TAG_PREFIX}${version}: not a release, nothing to publish." >&2
+      echo "publish=false"
+      return
+      ;;
+    *) fail "git ls-remote for ${tag} failed (exit ${rc}); cannot tell whether this is a release." ;;
+  esac
+
+  # The status alone is not enough: a moved API also answers 404, and a proxy can
+  # answer 200 with nothing. Each answer must also carry the body that means it.
+  local encoded body status
+  encoded=$(jq -rn --arg n "$name" '$n | @uri')
+  body=$(mktemp)
+  status=$(curl -sS -o "$body" -w '%{http_code}' \
+    "${REGISTRY}/v0/servers/${encoded}/versions/${version}") ||
+    fail "Registry lookup for ${name} ${version} failed."
+  if [[ "$status" == 200 ]] &&
+    jq -e --arg n "$name" --arg v "$version" \
+      '.server.name == $n and .server.version == $v' "$body" >/dev/null 2>&1; then
+    echo "${name} ${version} is already in the registry." >&2
+    echo "publish=false"
+  elif [[ "$status" == 404 ]] &&
+    jq -e '.detail == "Server not found"' "$body" >/dev/null 2>&1; then
+    echo "${name} ${version} is released and not in the registry yet." >&2
+    echo "publish=true"
+  else
+    fail "Unexpected registry answer for ${name} ${version}: HTTP ${status}, $(head -c 200 "$body")"
+  fi
+  rm -f "$body"
+}
+
+wait_pypi() {
+  local marker="mcp-name: ${name}" deadline=$((SECONDS + WAIT_SECONDS))
+  until curl -fsS "${PYPI}/pypi/${package}/${version}/json" 2>/dev/null |
+    jq -e --arg m "$marker" '(.info.description // "") | contains($m)' >/dev/null 2>&1; do
+    if [[ "$SECONDS" -ge "$deadline" ]]; then
+      fail "${package} ${version} with '${marker}' not on PyPI after ${WAIT_SECONDS}s." \
+        "Publish manually once it is: mcp-publisher login github && mcp-publisher publish"
+    fi
+    sleep "$POLL_SECONDS"
+  done
+  echo "${package} ${version} is on PyPI with the mcp-name marker." >&2
+}
+
+case "${1:-}" in
+  check) check ;;
+  wait-pypi) wait_pypi ;;
+  *)
+    echo "usage: $0 check|wait-pypi" >&2
+    exit 2
+    ;;
+esac

{codegraph_brain-0.23.0 → codegraph_brain-0.23.2}/server.json

@@ -8,13 +8,13 @@
     "source": "github",
     "id": "1260843154"
   },
-  "version": "0.23.0",
+  "version": "0.23.2",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "codegraph-brain",
-      "version": "0.23.0",
+      "version": "0.23.2",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{codegraph_brain-0.23.0 → codegraph_brain-0.23.2}/src/cgis/api/mcp_server.py

@@ -966,8 +966,9 @@ def cgis_audit_reachability(
         str | None,
         Field(
             description="Only audit sources at or under this FQN prefix, matched on whole "
-            "dot-segments — a partial segment selects nothing and returns an empty audit, "
-            "not a clean one. Combined with from_type when both are given."
+            "dot-segments. A selection matching no source is an error naming the "
+            "whole-segment prefixes it may have meant. Combined with from_type when both "
+            "are given."
         ),
     ] = None,
     depth: Annotated[
@@ -986,6 +987,9 @@ def cgis_audit_reachability(
     one is required. Returns JSON ``{target, covered, gaps}`` where each gap carries
     ``fqn``/``file``/``line``. Generalizes to validators, event tracking, or
     service-layer-boundary rules by pointing ``target`` at the required node.
+
+    A selection that matches no source returns a ❌ message, not an empty
+    ``{covered: [], gaps: []}`` that would read as a passing audit (#467).
     """
     if blank := _blank_fqn_error(target):
         return blank

{codegraph_brain-0.23.0 → codegraph_brain-0.23.2}/src/cgis/cli.py

@@ -20,6 +20,7 @@ style tags you wrote yourself and pure numbers need no escaping.
 
 import dataclasses
 import json as _json
+from collections.abc import Callable
 from enum import StrEnum
 from pathlib import Path
 
@@ -42,7 +43,7 @@ from cgis.query.analysis.analyzer import AnalyzerEngine
 from cgis.query.analysis.anomaly import AnomalyType, ArchitecturalAnomaly
 from cgis.query.analysis.health import HealthScorer
 from cgis.query.analysis.suggest_service import SuggestReport, report_to_dict, suggest_packages
-from cgis.query.context.audit import ReachabilityAudit, audit_reachability
+from cgis.query.context.audit import NoAuditSourcesError, ReachabilityAudit, audit_reachability
 from cgis.query.context.context_service import build_context
 from cgis.query.context.orphans import OrphanReport, find_orphan_classes
 from cgis.query.drift.drift import DriftReport, FitQuality
@@ -318,6 +319,40 @@ def _resolve_cli_fqn(store: SQLiteStore, target: str, kind: str) -> str:
     return resolution.resolved
 
 
+def _tree_neighbours(
+    store: SQLiteStore,
+    edges: list[Edge],
+    neighbour_of: Callable[[Edge], str],
+    *,
+    allowed_edge_types: frozenset[EdgeType] | None,
+    show_external: bool,
+    min_confidence: float | None,
+) -> list[tuple[str, Node | None]]:
+    """The neighbours one tree level shows: filtered, in edge order, each id once.
+
+    One entry per neighbour, not per edge: two call sites are separate edges to the
+    same node, and a tree row shows neither line nor edge type to tell them apart
+    (#463). A neighbour absent from the store (an unresolved target) comes back with
+    ``None``, and is dropped with the non-INTERNAL ones when ``show_external`` is off.
+    """
+    if allowed_edge_types is not None:
+        edges = [e for e in edges if e.type in allowed_edge_types]
+    if min_confidence is not None:
+        edges = [e for e in edges if e.confidence >= min_confidence]
+    ids = list(dict.fromkeys(neighbour_of(e) for e in edges))
+    nodes = {n.id: n for n in store.get_nodes(ids)}
+    return [
+        (node_id, nodes.get(node_id))
+        for node_id in ids
+        if show_external or _is_internal(nodes.get(node_id))
+    ]
+
+
+def _is_internal(node: Node | None) -> bool:
+    """True for a stored node from the ingested repository."""
+    return node is not None and node.namespace == NodeNamespace.INTERNAL
+
+
 def build_trace_tree(
     store: SQLiteStore,
     current_id: str,
@@ -333,21 +368,15 @@ def build_trace_tree(
     if current_depth >= max_depth:
         return
 
-    outgoing = store.get_outgoing_edges(current_id)
-    if allowed_edge_types is not None:
-        outgoing = [e for e in outgoing if e.type in allowed_edge_types]
-    if min_confidence is not None:
-        outgoing = [e for e in outgoing if e.confidence >= min_confidence]
-    nodes_map = {n.id: n for n in store.get_nodes([e.target for e in outgoing])}
-    for edge in outgoing:
-        target_id = edge.target
-        target_node = nodes_map.get(target_id)
-
-        if not show_external and (
-            target_node is None or target_node.namespace != NodeNamespace.INTERNAL
-        ):
-            continue
-
+    callees = _tree_neighbours(
+        store,
+        store.get_outgoing_edges(current_id),
+        lambda edge: edge.target,
+        allowed_edge_types=allowed_edge_types,
+        show_external=show_external,
+        min_confidence=min_confidence,
+    )
+    for target_id, target_node in callees:
         if target_node:
             label = (
                 f"[bold green]{target_node.type.value}[/bold green] "
@@ -470,21 +499,15 @@ def build_impact_tree(
     if current_depth >= max_depth:
         return
 
-    incoming = store.get_incoming_edges(current_id)
-    if allowed_edge_types is not None:
-        incoming = [e for e in incoming if e.type in allowed_edge_types]
-    if min_confidence is not None:
-        incoming = [e for e in incoming if e.confidence >= min_confidence]
-    nodes_map = {n.id: n for n in store.get_nodes([e.source for e in incoming])}
-    for edge in incoming:
-        source_id = edge.source
-        source_node = nodes_map.get(source_id)
-
-        if not show_external and (
-            source_node is None or source_node.namespace != NodeNamespace.INTERNAL
-        ):
-            continue
-
+    callers = _tree_neighbours(
+        store,
+        store.get_incoming_edges(current_id),
+        lambda edge: edge.source,
+        allowed_edge_types=allowed_edge_types,
+        show_external=show_external,
+        min_confidence=min_confidence,
+    )
+    for source_id, source_node in callers:
         if source_node:
             label = (
                 f"[bold magenta]{source_node.type.value}[/bold magenta] "
@@ -1445,7 +1468,7 @@ def audit(
         help="Only audit nodes of this type (e.g. ROUTE_HANDLER, API_ENDPOINT).",
     ),
     from_prefix: str | None = typer.Option(
-        None, "--from-prefix", help="Only audit nodes whose FQN starts with this prefix."
+        None, "--from-prefix", help="Only audit nodes under this FQN prefix (whole dot-segments)."
     ),
     db: str = typer.Option(_DEFAULT_DB, "--db", "-d", help=_DEFAULT_DB_HELP),
     depth: int = typer.Option(
@@ -1487,13 +1510,19 @@ def audit(
 
     with SQLiteStore(db) as store:
         resolved = _resolve_checkpoint(store, target)
-        result = audit_reachability(
-            store,
-            target_fqn=resolved,
-            from_type=from_type,
-            from_prefix=from_prefix,
-            max_depth=depth,
-        )
+        try:
+            result = audit_reachability(
+                store,
+                target_fqn=resolved,
+                from_type=from_type,
+                from_prefix=from_prefix,
+                max_depth=depth,
+            )
+        except NoAuditSourcesError as exc:
+            # Exit 2 like a bad selector: exit 0 here let a typo'd prefix pass a CI gate (#467).
+            # stderr, like _resolve_checkpoint: `--format json` stdout stays a clean payload.
+            err_console.print(f"[bold red]❌ {escape(str(exc))}[/bold red]")
+            raise typer.Exit(code=2) from exc
 
     if output_format == OutputFormat.JSON:
         typer.echo(_json.dumps(dataclasses.asdict(result), indent=2))