codegraph-brain 0.23.4__tar.gz → 0.24.0__tar.gz

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

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

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.24.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.4...codegraph-brain-v0.24.0) (2026-09-17)
+
+
+### Features
+
+* **mcp:** cgis_overview — a starting map when you have no FQN yet ([#486](https://github.com/zaebee/codegraph-brain/issues/486)) ([1580cfe](https://github.com/zaebee/codegraph-brain/commit/1580cfe53325241e149ba3bbb9388c4ddc7718d7))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#488](https://github.com/zaebee/codegraph-brain/issues/488)) ([9f169ce](https://github.com/zaebee/codegraph-brain/commit/9f169ce364f0d778c0c59b4de607a3433b800dbd))
+
 ## [0.23.4](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.3...codegraph-brain-v0.23.4) (2026-09-17)
 
 

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.23.4
+Version: 0.24.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
@@ -143,6 +143,7 @@ The main tools:
 | Tool | Answers |
 | :--- | :--- |
 | `cgis_ingest` | Build or incrementally refresh the graph |
+| `cgis_overview` | Where to start: sizes and the largest packages, when you have no FQN yet |
 | `cgis_find_symbol` | Partial name → candidate FQNs |
 | `cgis_analyze_impact` | What breaks upstream if this changes? |
 | `cgis_trace_flow` | What does this call, transitively? |

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/README.md

@@ -93,6 +93,7 @@ The main tools:
 | Tool | Answers |
 | :--- | :--- |
 | `cgis_ingest` | Build or incrementally refresh the graph |
+| `cgis_overview` | Where to start: sizes and the largest packages, when you have no FQN yet |
 | `cgis_find_symbol` | Partial name → candidate FQNs |
 | `cgis_analyze_impact` | What breaks upstream if this changes? |
 | `cgis_trace_flow` | What does this call, transitively? |

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/docs/architecture/HOW_IT_WORKS.md

@@ -204,7 +204,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:42)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:48)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -237,5 +237,5 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 | `resolve` | METHOD | [`engine.py:37`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L37) |
 | `SemanticUpliftEngine` | CLASS | [`uplift.py:66`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L66) |
 | `execute_uplift` | METHOD | [`uplift.py:91`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L91) |
-| `SQLiteStore` | CLASS | [`sqlite_store.py:42`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L42) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:48`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L48) |
 <!-- END_CGIS_GRAPH -->

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -29,7 +29,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:42)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:48)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/docs/how-to/CLI_USAGE.md

@@ -45,6 +45,33 @@ cgis ingest ./src --output graph.json
 
 ---
 
+### `cgis overview`
+
+Where to start in a graph you know nothing about: how big it is, how much of it resolved, and the largest packages with production and tests listed separately. Every prefix it prints is one `find --prefix` and `metrics --scope` accept. `structure` takes a node's FQN instead — a package is a node only when it has an `__init__.py` — so reach a module through `find` first. The MCP tool is `cgis_overview`.
+
+```bash
+cgis overview [OPTIONS]
+```
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `--db`, `-d` | `graph.db` | Path to the graph database |
+| `--depth` | `2` | FQN segments per package prefix; `1` is the top level |
+| `--limit`, `-n` | `15` | Maximum packages listed per section |
+| `--format`, `-f` | `text` | `text` or `json` |
+
+**Examples:**
+
+```bash
+# First call in an unfamiliar repository
+cgis overview
+
+# Top-level map only, as JSON
+cgis overview --depth 1 --format json
+```
+
+---
+
 ### `cgis trace`
 
 Everything a FQN reaches **downstream**: every edge except containment, which in practice means calls, imports, inheritance, DI dependencies and references between internal code. Containment stays out unless `--show-structure` adds it, and so do stdlib, third-party and unresolved call targets unless `--show-external` does. The MCP tool `cgis_trace_flow` uses the same defaults (`include_structure`, `include_external`).

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/docs/how-to/MCP_REFERENCE.md

@@ -330,6 +330,31 @@ Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRan
 
 ---
 
+## `cgis_overview`
+
+Where to start in a graph you know nothing about: sizes and a package map.
+
+    Call this first in an unfamiliar repository — every other tool needs a name,
+    and this is the one that hands you some. Returns JSON: symbol counts by type,
+    file and edge totals, the unresolved-edge ratio, and the largest packages with
+    production and tests listed separately. Each ``prefix`` goes straight into
+    ``cgis_find_symbol`` (``fqn_prefix``) or ``cgis_metrics`` (``scope``), which
+    match on prefixes. ``cgis_get_structure`` takes a node id, not a prefix: a
+    package is a node only when it has an ``__init__.py``, and then holds no
+    members of its own — reach a module through ``cgis_find_symbol`` first.
+
+    Listings are capped; ``packages_omitted`` appears when rows were cut. Entry
+    points are deliberately not reported — "nothing calls it" is not one on a
+    framework codebase, where most handlers have no incoming call edge.
+
+| Argument | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `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` |  | FQN segments per package prefix; 1 is the top level. |
+| `limit` | `integer` |  | Maximum packages listed per section. |
+
+---
+
 ## `cgis_suggest_packages`
 
 Suggest sub-package boundaries for a package from its dependency communities.

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/plugin/skills/cgis/SKILL.md

@@ -11,6 +11,7 @@ Reading files to answer a structural question is the slow, lossy path: it burns
 
 | Question | Tool | Instead of |
 | :--- | :--- | :--- |
+| "Where do I even start?" | `cgis_overview` | opening files to find the shape of the repo |
 | "What calls this?" | `cgis_analyze_impact` | grepping the name and hoping |
 | "Is this rename safe?" | `cgis_analyze_impact` | reading every plausible caller |
 | "What does this end up calling?" | `cgis_trace_flow` | following imports by hand |

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.23.4"
+version = "0.24.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.23.4 → codegraph_brain-0.24.0}/server.json

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

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/src/cgis/api/mcp_server.py

@@ -21,6 +21,7 @@ from cgis.core.models import Edge, EdgeType, Node, NodeType
 from cgis.extractors.python_extractor import PythonExtractor
 from cgis.extractors.typescript_extractor import TypeScriptExtractor
 from cgis.pipeline import IngestionPipeline
+from cgis.query.analysis.overview import DEFAULT_DEPTH, DEFAULT_LIMIT, build_overview
 from cgis.query.analysis.suggest_service import report_to_dict, suggest_packages
 from cgis.query.context.audit import audit_reachability
 from cgis.query.context.context_service import build_context
@@ -722,6 +723,42 @@ def cgis_validate(
         return f"❌ {exc}"
 
 
+@mcp.tool()
+def cgis_overview(
+    db_path: DbPath = _DEFAULT_DB,
+    depth: Annotated[
+        int,
+        Field(description="FQN segments per package prefix; 1 is the top level."),
+    ] = DEFAULT_DEPTH,
+    limit: Annotated[
+        int, Field(description="Maximum packages listed per section.")
+    ] = DEFAULT_LIMIT,
+) -> str:
+    """Where to start in a graph you know nothing about: sizes and a package map.
+
+    Call this first in an unfamiliar repository — every other tool needs a name,
+    and this is the one that hands you some. Returns JSON: symbol counts by type,
+    file and edge totals, the unresolved-edge ratio, and the largest packages with
+    production and tests listed separately. Each ``prefix`` goes straight into
+    ``cgis_find_symbol`` (``fqn_prefix``) or ``cgis_metrics`` (``scope``), which
+    match on prefixes. ``cgis_get_structure`` takes a node id, not a prefix: a
+    package is a node only when it has an ``__init__.py``, and then holds no
+    members of its own — reach a module through ``cgis_find_symbol`` first.
+
+    Listings are capped; ``packages_omitted`` appears when rows were cut. Entry
+    points are deliberately not reported — "nothing calls it" is not one on a
+    framework codebase, where most handlers have no incoming call edge.
+    """
+    if not Path(db_path).exists():
+        return f"❌ Database not found at: {db_path}. Run cgis_ingest first."
+    try:
+        with SQLiteStore(db_path) as store:
+            report = build_overview(store, depth=depth, limit=limit)
+    except Exception as exc:
+        return f"❌ {exc}"
+    return json.dumps(_with_freshness(db_path, report), indent=2)
+
+
 @mcp.tool()
 def cgis_find_symbol(
     query: Annotated[

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/src/cgis/cli.py

@@ -23,6 +23,7 @@ import json as _json
 from collections.abc import Callable
 from enum import StrEnum
 from pathlib import Path
+from typing import Any
 
 import typer
 import yaml
@@ -42,6 +43,7 @@ from cgis.pipeline import IngestionPipeline
 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.overview import DEFAULT_DEPTH, DEFAULT_LIMIT, build_overview
 from cgis.query.analysis.suggest_service import SuggestReport, report_to_dict, suggest_packages
 from cgis.query.context.audit import NoAuditSourcesError, ReachabilityAudit, audit_reachability
 from cgis.query.context.context_service import build_context
@@ -620,6 +622,68 @@ def impact(
             console.print(tree)
 
 
+@app.command()
+def overview(
+    db: str = typer.Option(_DEFAULT_DB, "--db", "-d", help=_DEFAULT_DB_HELP),
+    depth: int = typer.Option(
+        DEFAULT_DEPTH, "--depth", min=1, help="FQN segments per package prefix."
+    ),
+    limit: int = typer.Option(
+        DEFAULT_LIMIT, "--limit", "-n", min=1, help="Max packages listed per section."
+    ),
+    output_format: OutputFormat = typer.Option(
+        OutputFormat.TEXT, "--format", "-f", help=_TEXT_JSON_FORMAT_HELP
+    ),
+) -> None:
+    """Where to start in a graph you know nothing about: sizes and a package map (#478).
+
+    Every other command needs an FQN. This one hands you some: the largest
+    packages, production and tests apart, as prefixes `structure`, `find` and
+    `metrics --scope` accept directly.
+    """
+    if output_format == OutputFormat.MERMAID:
+        console.print("[bold red]❌ overview supports --format text or json only.[/bold red]")
+        raise typer.Exit(code=2)
+    if not Path(db).is_file():
+        console.print(
+            f"[bold red]❌ Database not found:[/bold red] {escape(db)}. Run `ingest` first."
+        )
+        raise typer.Exit(code=1)
+    _warn_if_not_fresh(db)
+
+    with SQLiteStore(db) as store:
+        report = build_overview(store, depth=depth, limit=limit)
+
+    if output_format == OutputFormat.JSON:
+        typer.echo(_json.dumps(report, indent=2))
+        return
+    _render_overview(report)
+
+
+def _render_overview(report: dict[str, Any]) -> None:
+    """Print the overview as two small tables plus a one-line size summary."""
+    counts = ", ".join(
+        f"{count} {kind.lower()}" for kind, count in sorted(report["symbols"].items())
+    )
+    console.print(
+        f"[bold]{report['files']} files[/bold] · {counts or 'no symbols'} · "
+        f"{report['edges']} edges · {report['unresolved_ratio'] * 100:.1f}% unresolved\n"
+    )
+    for key, title in (("packages", "Packages"), ("test_packages", "Test packages")):
+        rows = report[key]
+        if not rows:
+            continue
+        table = Table(title=title)
+        table.add_column("Prefix", style="cyan")
+        table.add_column("Symbols", style="magenta", justify="right")
+        for row in rows:
+            table.add_row(escape(str(row["prefix"])), str(row["symbols"]))
+        console.print(table)
+        omitted = report.get(f"{key}_omitted")
+        if omitted:
+            console.print(f"[dim]… {omitted} more not shown (raise --limit)[/dim]")
+
+
 @app.command()
 def validate(
     db: str = typer.Option(_DEFAULT_DB, "--db", "-d", help=_DEFAULT_DB_HELP),

codegraph_brain-0.24.0/src/cgis/query/analysis/overview.py

@@ -0,0 +1,87 @@
+"""The map an agent reads before it knows a single FQN (#478).
+
+Every other query tool takes a name: `cgis_get_structure` wants a module,
+`cgis_analyze_impact` wants a symbol, and `cgis_find_symbol` wants something to
+search for. In an unfamiliar repository an agent has none of them, so its first
+move is to read files — the thing the graph exists to replace.
+
+This answers "what is in this graph, and where do I start?" and nothing else.
+Two rules follow from that:
+
+**It stays small.** The listing is capped and says how much it cut. A map that
+costs as much as the files it replaces is not a map.
+
+**Every prefix it prints is usable — by the tools that match on prefixes.**
+`cgis_find_symbol(fqn_prefix=…)` and `cgis_metrics(scope=[…])` take a package
+prefix as it appears here. `cgis_get_structure` does not: it looks a node up by
+id, and a package has a node only when it has an `__init__.py` — and even then
+containment runs file→symbol, so the answer is that one empty file. Measured on
+this repository: of ten printed prefixes, four are not nodes at all and three
+resolve to a single node with no edges. So the route to a module is
+`cgis_find_symbol(fqn_prefix=…)` first, `cgis_get_structure` on what it returns.
+
+Entry points are deliberately absent. "A function nothing calls" is not one: on
+a 512-file FastAPI backend 4,612 of 5,846 functions and methods have no incoming
+CALLS edge, because frameworks, DI and dynamic dispatch do the calling. Listing
+them would be noise wearing the name of an answer.
+"""
+
+from typing import Any
+
+from cgis.storage.sqlite_store import SQLiteStore
+
+#: Rows per listing. Two of these fit in the budget an agent would otherwise
+#: spend opening a single file.
+DEFAULT_LIMIT = 15
+
+#: Dot-segments of a package prefix. Two is where a real tree separates:
+#: `domains.admin` and `domains.reservation` are different places to look,
+#: `domains` alone is not a lead.
+DEFAULT_DEPTH = 2
+
+
+def _package_rows(census: list[tuple[str, int]], limit: int) -> tuple[list[dict[str, Any]], int]:
+    """Cap a census, largest first, and report how many rows were dropped."""
+    rows = [{"prefix": prefix, "symbols": count} for prefix, count in census[:limit]]
+    return rows, max(len(census) - limit, 0)
+
+
+def build_overview(
+    store: SQLiteStore, depth: int = DEFAULT_DEPTH, limit: int = DEFAULT_LIMIT
+) -> dict[str, Any]:
+    """Sizes, a capped package map, and what to call next.
+
+    Production and test packages are listed separately because on a real tree the
+    test packages are the largest ones: on a 512-file backend three of the six
+    biggest are under `tests.`, which makes an undivided listing point an agent
+    at the tests first. A prefix can appear in both lists when tests live inside
+    the package they cover (`domains/admin/tests/`), and the two lists do not sum
+    to `symbols` once the cap bites.
+    """
+    depth = max(depth, 1)
+    limit = max(limit, 1)
+    stats = store.get_edge_stats()
+    production, tests = store.package_census(depth)
+    package_rows, omitted = _package_rows(production, limit)
+    test_rows, test_omitted = _package_rows(tests, limit)
+
+    report: dict[str, Any] = {
+        "symbols": store.symbol_census(),
+        "files": store.file_count(),
+        "edges": stats.total,
+        "unresolved_ratio": stats.unresolved_ratio,
+        "packages": package_rows,
+        "test_packages": test_rows,
+        "next": [
+            "cgis_find_symbol(<name>, fqn_prefix=<prefix>) — symbols inside a package",
+            "cgis_metrics(scope=[<prefix>]) — coupling and God classes in one package",
+            "cgis_get_structure(<fqn>) — members of a module or class, once you have its "
+            "FQN from cgis_find_symbol (a package prefix is not a node)",
+            "cgis_validate() — how much of the graph resolved",
+        ],
+    }
+    if omitted:
+        report["packages_omitted"] = omitted
+    if test_omitted:
+        report["test_packages_omitted"] = test_omitted
+    return report

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/src/cgis/storage/sqlite_store.py

@@ -4,6 +4,7 @@ import json
 import os
 import sqlite3
 import time
+from collections import Counter
 from collections.abc import Iterable
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -39,6 +40,11 @@ class EdgeStats:
     top_unresolved: list[tuple[str, int]] = field(default_factory=list)  # top UNKNOWN targets
 
 
+def _ranked(census: Counter[str]) -> list[tuple[str, int]]:
+    """Largest first, ties broken by prefix — `most_common` alone orders ties by rowid."""
+    return sorted(census.items(), key=lambda row: (-row[1], row[0]))
+
+
 class SQLiteStore:
     """
     Deterministic SQLite Graph Store.
@@ -385,6 +391,67 @@ class SQLiteStore:
         row = self._conn.execute("SELECT COUNT(*) AS n FROM edges").fetchone()
         return int(row["n"]) if row else 0
 
+    def symbol_census(self) -> dict[str, int]:
+        """Internal declared symbols by node type — CLASS/FUNCTION/METHOD, not FILE.
+
+        Virtual nodes are excluded by file path: `--domains` mints DOMAIN_CONCEPT
+        nodes that are INTERNAL and not FILE, so without this a domain counts as a
+        symbol and shows up as a `domain:` package row, pushing real packages off a
+        capped listing.
+        """
+        if not self._conn:
+            raise RuntimeError(self._error_message)
+        rows = self._conn.execute(
+            """
+            SELECT type, COUNT(*) FROM nodes
+            WHERE namespace = 'INTERNAL' AND type != 'FILE' AND file_path != ?
+            GROUP BY type ORDER BY type
+            """,
+            (VIRTUAL_FILE_PATH,),
+        ).fetchall()
+        return {row[0]: row[1] for row in rows}
+
+    def file_count(self) -> int:
+        """Internal FILE nodes — the size of the tree the graph was built from."""
+        if not self._conn:
+            raise RuntimeError(self._error_message)
+        row = self._conn.execute(
+            "SELECT COUNT(*) FROM nodes WHERE namespace = 'INTERNAL' AND type = 'FILE'"
+        ).fetchone()
+        return int(row[0]) if row else 0
+
+    def package_census(self, depth: int) -> tuple[list[tuple[str, int]], list[tuple[str, int]]]:
+        """Internal symbols grouped by their first `depth` FQN segments, production and test.
+
+        The prefix never swallows the symbol's own name: `mod.func` at depth 2 is
+        `mod`, not `mod.func`, or the map would list one row per symbol. Grouping
+        happens in Python because the cut is per-id — SQL would need a recursive
+        expression to find the nth dot, for a pass over ids this already makes.
+
+        Virtual `domain:` nodes are excluded with the same file-path predicate
+        `symbol_census` uses, and ties are broken by prefix so the map is
+        reproducible across re-ingests.
+        """
+        if not self._conn:
+            raise RuntimeError(self._error_message)
+        # Clamped here too, not only in `build_overview`: depth 0 would key every
+        # row on the empty string, which is not an FQN prefix anything accepts.
+        depth = max(depth, 1)
+        rows = self._conn.execute(
+            """
+            SELECT id, is_test FROM nodes
+            WHERE namespace = 'INTERNAL' AND type != 'FILE' AND file_path != ?
+            """,
+            (VIRTUAL_FILE_PATH,),
+        ).fetchall()
+        production: Counter[str] = Counter()
+        tests: Counter[str] = Counter()
+        for node_id, is_test in rows:
+            parts = node_id.split(".")
+            prefix = ".".join(parts[: min(depth, max(len(parts) - 1, 1))])
+            (tests if is_test else production)[prefix] += 1
+        return _ranked(production), _ranked(tests)
+
     def get_node(self, node_id: str) -> Node | None:
         """Return a single node by FQN, or None if not found."""
         if not self._conn:

codegraph_brain-0.24.0/tests/self_parsing/test_overview.py

@@ -0,0 +1,74 @@
+"""The overview measured against a real tree, not a flat fixture (#478, #486 review).
+
+The unit fixture is flat, so every prefix it can produce is a module — which is
+exactly the shape that always works. cgis's own `src/` has the shape that does
+not: `cgis/query/` has no `__init__.py`, so no node bears that name, and
+`cgis/guardian/` has one whose containment edges point at nothing. A promise
+about "the next call" has to be checked here or it checks nothing.
+"""
+
+from cgis.core.models import Node
+from cgis.query.analysis.overview import build_overview
+from cgis.query.render.metrics import DuckDBAnalyzer
+from cgis.storage.sqlite_store import SQLiteStore
+
+
+def _prefixes(store: SQLiteStore) -> list[str]:
+    report = build_overview(store)
+    rows = report["packages"] + report["test_packages"]
+    assert rows, "cgis's own graph has packages"
+    return [str(row["prefix"]) for row in rows]
+
+
+def test_every_prefix_finds_symbols_under_it(
+    root_graph_data: tuple[SQLiteStore, list[Node], list],
+) -> None:
+    """`cgis_find_symbol(fqn_prefix=…)` is the documented next call, so it must hold here.
+
+    Walked the way an agent would: take a symbol the package really holds, search
+    for it scoped to the prefix, and expect it back.
+    """
+    store, nodes, _edges = root_graph_data
+
+    for prefix in _prefixes(store):
+        under = [n for n in nodes if n.id.startswith(f"{prefix}.") and n.name]
+        assert under, f"{prefix} names a package with no symbols under it"
+        wanted = under[0]
+        matches = store.search_nodes(wanted.name, kinds=(), fqn_prefix=prefix, limit=20)
+        assert any(node.id == wanted.id for node in matches), f"{prefix}: {wanted.id} not found"
+
+
+def test_every_prefix_scopes_a_metrics_run(
+    root_graph_data: tuple[SQLiteStore, list, list],
+) -> None:
+    """`cgis_metrics(scope=[…])` is the other documented next call."""
+    store, _nodes, _edges = root_graph_data
+
+    for prefix in _prefixes(store):
+        with DuckDBAnalyzer(store.db_path) as analyzer:
+            coupling = analyzer.get_coupling_metrics(limit=3, scope=[prefix])
+        assert coupling, f"{prefix} scopes a metrics run to nothing"
+        assert all(metric.node_id.startswith(prefix) for metric in coupling)
+
+
+def test_the_map_names_packages_that_are_not_nodes(
+    root_graph_data: tuple[SQLiteStore, list, list],
+) -> None:
+    """Why `cgis_get_structure` is *not* offered for a prefix.
+
+    A package is a node only when it has an `__init__.py`, and even then holds no
+    members: `CONTAINS`/`DECLARES` run file → symbol, never package → module. This
+    pins the fact the docs now state, so a future graph model that adds package
+    nodes fails here and the wording gets revisited.
+    """
+    store, _nodes, _edges = root_graph_data
+    prefixes = _prefixes(store)
+
+    missing = [prefix for prefix in prefixes if store.get_node(prefix) is None]
+    childless = [
+        prefix
+        for prefix in prefixes
+        if store.get_node(prefix) is not None and not store.get_outgoing_edges(prefix)
+    ]
+    assert missing, "cgis/query has no __init__.py — expected some prefixes to have no node"
+    assert childless, "a package node holds no members of its own"

{codegraph_brain-0.23.4 → codegraph_brain-0.24.0}/tests/self_parsing/test_receiver_resolution.py

@@ -32,7 +32,13 @@ _KNOWN_FABRICATED = frozenset(
     }
 )
 
-_EXPECTED_PLACEHOLDERS = 46
+#: Re-measured on a fresh self-ingest, 2026-09-17: 54 on `main`, 57 with the three
+#: `cgis_overview` store methods added here. All three are `self._conn.execute(...)`
+#: on a `sqlite3.Connection`, which rule D1 declines by design — a stdlib receiver
+#: has no node to resolve to. The centre was 46 and had drifted 8 low, so the band
+#: was measuring less each time something was added to a store method rather than
+#: catching a regression.
+_EXPECTED_PLACEHOLDERS = 57
 _TOLERANCE = 10