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

codegraph_brain-0.23.4/.github/test-count-baseline

@@ -0,0 +1 @@
+2618

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

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

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

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.23.4](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.3...codegraph-brain-v0.23.4) (2026-09-17)
+
+
+### Bug Fixes
+
+* **mcp:** trace_flow/analyze_impact default to the CLI's view ([#482](https://github.com/zaebee/codegraph-brain/issues/482)) ([8877051](https://github.com/zaebee/codegraph-brain/commit/8877051d9b6f90e6df2a25480c3f608cdacb5f58))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#484](https://github.com/zaebee/codegraph-brain/issues/484)) ([2f507b0](https://github.com/zaebee/codegraph-brain/commit/2f507b004c232dae3d90577f73d763f4d27be357))
+
+## [0.23.3](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.2...codegraph-brain-v0.23.3) (2026-09-17)
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#480](https://github.com/zaebee/codegraph-brain/issues/480)) ([5379cce](https://github.com/zaebee/codegraph-brain/commit/5379cce927b5fade5e2371503a0cd9e1f8041fc7))
+* **mcp:** say when to use each overlapping graph tool ([#477](https://github.com/zaebee/codegraph-brain/issues/477)) ([f33d764](https://github.com/zaebee/codegraph-brain/commit/f33d764ebdf217359964347aaa1137dc18ced513))
+
 ## [0.23.2](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.23.1...codegraph-brain-v0.23.2) (2026-09-17)
 
 

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

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

@@ -47,7 +47,7 @@ cgis ingest ./src --output graph.json
 
 ### `cgis trace`
 
-Trace the execution call-graph **downstream** from a starting FQN.
+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`).
 
 ```bash
 cgis trace <fqn> [OPTIONS]
@@ -57,24 +57,30 @@ cgis trace <fqn> [OPTIONS]
 | :--- | :--- | :--- |
 | `--db`, `-d` | `graph.db` | Path to the graph database |
 | `--depth` | `5` | Maximum traversal depth |
-| `--format`, `-f` | `text` | Output format: `text` or `mermaid` |
-| `--internal-only` | `False` | Exclude external library nodes |
+| `--format`, `-f` | `text` | `text`, `mermaid`, or `json` (joinable `{root, nodes, edges, coverage}`) |
+| `--show-structure` | off | Also follow containment (CONTAINS/DECLARES) |
+| `--show-external` | off | Also show stdlib, third-party and unresolved call targets |
+| `--internal-only` | off | Drop those nodes again from `mermaid`/`json` output; a no-op unless `--show-external` is on, and not valid with `text` |
+| `--min-confidence` | none | Hide edges below this confidence. Resolved calls score 1.0 and inferred ones 0.8, so a threshold above 0.8 is what filters anything |
 
 **Examples:**
 
 ```bash
-# Text tree of what IngestionPipeline.run calls
+# Text tree of what IngestionPipeline.run depends on
 cgis trace "cgis.pipeline.IngestionPipeline.run" --depth 3
 
 # Mermaid diagram for pasting into docs
 cgis trace "cgis.pipeline.IngestionPipeline.run" --format mermaid
+
+# Machine-readable, with the module's own members included
+cgis trace "cgis.query.engine" --format json --show-structure
 ```
 
 ---
 
 ### `cgis impact`
 
-Trace **upstream** callers — who depends on this FQN?
+Everything that reaches a FQN **upstream**: callers, importers, subclasses, type references and DI dependents. The enclosing class or file 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_analyze_impact` uses the same defaults.
 
 ```bash
 cgis impact <fqn> [OPTIONS]
@@ -84,13 +90,16 @@ cgis impact <fqn> [OPTIONS]
 | :--- | :--- | :--- |
 | `--db`, `-d` | `graph.db` | Path to the graph database |
 | `--depth` | `5` | Maximum traversal depth |
-| `--format`, `-f` | `text` | Output format: `text` or `mermaid` |
-| `--internal-only` | `False` | Exclude external library nodes |
+| `--format`, `-f` | `text` | `text`, `mermaid`, or `json` (joinable `{root, nodes, edges, coverage}`) |
+| `--show-structure` | off | Also follow containment (CONTAINS/DECLARES) |
+| `--show-external` | off | Also show stdlib, third-party and unresolved call targets |
+| `--internal-only` | off | Drop those nodes again from `mermaid`/`json` output; a no-op unless `--show-external` is on, and not valid with `text` |
+| `--min-confidence` | none | Hide edges below this confidence. Resolved calls score 1.0 and inferred ones 0.8, so a threshold above 0.8 is what filters anything |
 
 **Examples:**
 
 ```bash
-# Who calls SQLiteStore.save_graph?
+# What depends on SQLiteStore.save_graph?
 cgis impact "cgis.storage.sqlite_store.SQLiteStore.save_graph"
 
 # Blast radius of changing the Node model

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

@@ -7,9 +7,19 @@
 
 ## `cgis_analyze_impact`
 
-Analyse transitive upstream callers of a specific FQN.
-
-    Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
+Upstream subgraph of one FQN: everything that reaches it within ``depth`` hops.
+
+    Follows every edge except containment — in practice callers, importers,
+    subclasses, type references and DI dependents — within internal code, so this
+    answers "what breaks if I change X?". The
+    enclosing class or file and stdlib/third-party nodes are left out unless
+    ``include_structure`` / ``include_external`` ask for them — the same view as
+    the CLI's ``impact``. For what X depends on use
+    ``cgis_trace_flow``; for only the members of a module or class,
+    ``cgis_get_structure``; for a source-included brief to read before editing
+    one symbol, ``cgis_context``.
+
+    ``output_format="mermaid"`` (default)
     returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
     coverage}`` payload with real FQNs — letting an agent compute set
     differences (e.g. "which route handlers never reach ``verify_ownership``?")
@@ -22,14 +32,16 @@ Analyse transitive upstream callers of a specific FQN.
 | :--- | :--- | :---: | :--- |
 | `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. |
+| `depth` | `integer` |  | Maximum edge hops upstream, over callers, importers, subclasses, type references and DI dependents (plus the enclosing class or file with include_structure). |
 | `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
+| `include_structure` | `boolean` |  | Also follow containment (CONTAINS/DECLARES): a module's or class's own members, and the class or file enclosing a symbol. Off by default, as in the CLI; cgis_get_structure is the tool for members alone. |
+| `include_external` | `boolean` |  | Also return stdlib, third-party and unresolved call targets — calls on values whose type is decided at runtime. Off by default, as in the CLI, because they dominate the payload; in json, coverage/top_unresolved still counts what was dropped. |
 
 ---
 
 ## `cgis_audit_reachability`
 
-Reachability/authorization audit — which sources never reach a checkpoint (#172).
+Reachability/authorization audit — which sources never reach a checkpoint.
 
     The headline use is **IDOR/authz coverage**: list every route handler that does
     NOT transitively reach an ownership check. Reachability follows behavioral edges
@@ -56,7 +68,15 @@ Reachability/authorization audit — which sources never reach a checkpoint (#17
 
 ## `cgis_context`
 
-Compile an agent-facing GraphRAG context package for a focal FQN (#19).
+Prompt-ready brief on one FQN: its source, class, direct callers and callees.
+
+    Call this before editing a symbol, instead of reading its files. It follows
+    calls only, one hop by default. Source is included when the file is found
+    (see ``source_root``), and the domain when the graph was tagged with one.
+    For a multi-hop subgraph
+    over calls, imports, inheritance and references without source, use
+    ``cgis_trace_flow`` (downstream) or
+    ``cgis_analyze_impact`` (upstream).
 
     Returns an XML-tagged prompt — the focal node's source, its enclosing class,
     its architectural domain boundary, direct callers (upstream ripple) and
@@ -115,7 +135,7 @@ Report per-domain architectural drift against declared ideal patterns.
 
 ## `cgis_find_orphans`
 
-Classes nothing in production builds, extends or names — dead-code candidates (#415).
+Classes nothing in production builds, extends or names — dead-code candidates.
 
     Finds classes that no test, type checker or linter flags, because each is
     still imported somewhere: a package re-export keeps a class importable long
@@ -209,10 +229,13 @@ Report the motif census across the repository's structural tiers.
 
 ## `cgis_get_structure`
 
-Show the structural layout (CONTAINS/DECLARES) of a module or class.
+Members of a module or class: the classes, functions and methods it contains.
 
-    Traverses only containment edges — no call-graph noise — matching the CLI
-    ``structure`` command. ``output_format="mermaid"`` (default) returns a
+    Follows containment (CONTAINS/DECLARES) only, so no call or import appears.
+    For how the code connects use ``cgis_trace_flow`` (what it depends on) or
+    ``cgis_analyze_impact`` (what depends on it).
+
+    Matches the CLI ``structure`` command. ``output_format="mermaid"`` (default) returns a
     diagram of the hierarchy rooted at the given FQN; ``"json"`` returns the
     joinable ``{root, nodes, edges}`` payload with real FQNs.
 
@@ -275,7 +298,7 @@ Propose a starter patterns.yaml from the measured graph (read-only).
 
 ## `cgis_metrics`
 
-Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
+Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRank.
 
     Returns JSON ``{bottlenecks, god_classes, critical}`` computed with vectorized
     DuckDB aggregations over the whole graph (fan-in/fan-out coupling,
@@ -331,7 +354,18 @@ Suggest sub-package boundaries for a package from its dependency communities.
 
 ## `cgis_trace_flow`
 
-Trace the execution call-graph starting from a specific FQN downwards.
+Downstream subgraph of one FQN: everything it reaches within ``depth`` hops.
+
+    Follows every edge except containment — in practice calls, imports,
+    inheritance, DI dependencies and references — between internal code, so this
+    answers "what does X depend on?". Containment and
+    stdlib/third-party nodes are left out unless ``include_structure`` /
+    ``include_external`` ask for them (external covers stdlib, third-party and
+    unresolved call targets) — the same view as the CLI's ``trace``.
+    For what depends on X use
+    ``cgis_analyze_impact``; for only the members of a module or class,
+    ``cgis_get_structure``; for a source-included brief to read before editing
+    one symbol, ``cgis_context``.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
     ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
@@ -346,8 +380,10 @@ Trace the execution call-graph starting from a specific FQN downwards.
 | :--- | :--- | :---: | :--- |
 | `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. |
+| `depth` | `integer` |  | Maximum edge hops downstream, over calls, imports, inheritance, DI dependencies and references (plus containment with include_structure). |
 | `output_format` | `string` |  | "mermaid" for a diagram, or "json" for a payload with real FQNs (case-insensitive). Any other value returns an error. |
+| `include_structure` | `boolean` |  | Also follow containment (CONTAINS/DECLARES): a module's or class's own members, and the class or file enclosing a symbol. Off by default, as in the CLI; cgis_get_structure is the tool for members alone. |
+| `include_external` | `boolean` |  | Also return stdlib, third-party and unresolved call targets — calls on values whose type is decided at runtime. Off by default, as in the CLI, because they dominate the payload; in json, coverage/top_unresolved still counts what was dropped. |
 
 ---
 

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

@@ -21,7 +21,7 @@ Reading files to answer a structural question is the slow, lossy path: it burns
 | "Did this change drift the architecture?" | `cgis_drift` | nothing — there is no manual equivalent |
 | "Does every handler reach its authz guard?" | `cgis_audit_reachability` | auditing routes one by one |
 
-A subgraph at depth 2 costs a few hundred tokens. The equivalent in file chunks costs thousands and is less precise.
+A depth-2 trace or impact of a function or method costs a few hundred tokens: median about 300, and 9 in 10 under 1,600. Measured over every function and method of two real graphs (700 and 5,800 symbols), in the default mermaid format and in json. The equivalent in file chunks costs thousands and is less precise. A module or a heavily used symbol costs more — the worst symbol on the larger graph returns 36k tokens, so raise `depth` deliberately and prefer `cgis_context` for a single symbol. Containment, stdlib/third-party nodes and unresolved call targets are off by default; `include_structure` and `include_external` add them when that is the question.
 
 ## First run in a repository
 

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

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.23.2"
+version = "0.23.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.23.2 → codegraph_brain-0.23.4}/scripts/check_pytest_raises.py

@@ -54,7 +54,6 @@ GRANDFATHERED: frozenset[str] = frozenset(
         "unit/test_drift_service.py::test_analyze_drift_bad_suffix_raises",
         "unit/test_drift_service.py::test_analyze_drift_missing_db_raises",
         "unit/test_drift_service.py::test_analyze_drift_missing_patterns_raises",
-        "unit/test_guardian_martian_script.py::test_a_missing_concurrency_raises_instead_of_defaulting",
         "unit/test_guardian_recording.py::test_a_non_json_path_is_rejected",
         "unit/test_metrics.py::test_missing_database_raises_file_not_found",
         "unit/test_ontology_init.py::test_propose_missing_db_raises",

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

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

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

@@ -17,7 +17,7 @@ from pydantic import Field
 from cgis import __version__
 from cgis.core.coverage import TraversalCoverage
 from cgis.core.freshness import Freshness, FreshnessState
-from cgis.core.models import Edge, Node, NodeType
+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
@@ -28,7 +28,7 @@ from cgis.query.context.orphans import find_orphan_classes
 from cgis.query.drift.drift_service import analyze_drift
 from cgis.query.drift.fractal import analyze_fractal_db
 from cgis.query.drift.ontology_init import propose_ontology
-from cgis.query.engine import QueryEngine
+from cgis.query.engine import BEHAVIORAL_EDGE_TYPES, QueryEngine
 from cgis.query.fqn import resolve_fqn
 from cgis.query.render.graph_json import graph_to_json
 from cgis.query.render.mermaid import MermaidCompiler
@@ -65,6 +65,31 @@ Fqn = Annotated[
         "to look a name up."
     ),
 ]
+IncludeStructure = Annotated[
+    bool,
+    Field(
+        description="Also follow containment (CONTAINS/DECLARES): a module's or class's own "
+        "members, and the class or file enclosing a symbol. Off by default, as in the CLI; "
+        "cgis_get_structure is the tool for members alone."
+    ),
+]
+IncludeExternal = Annotated[
+    bool,
+    Field(
+        description="Also return stdlib, third-party and unresolved call targets — calls on "
+        "values whose type is decided at runtime. Off by default, as in the CLI, because they "
+        "dominate the payload; in json, coverage/top_unresolved still counts what was dropped."
+    ),
+]
+
+
+def _traversal_filters(
+    include_structure: bool, include_external: bool
+) -> tuple[frozenset[EdgeType] | None, bool]:
+    """Edge-type allowlist and external flag for trace/impact — the CLI's defaults (#481)."""
+    return (None if include_structure else BEHAVIORAL_EDGE_TYPES), include_external
+
+
 OutputFormat = Annotated[
     str,
     Field(
@@ -363,14 +388,26 @@ def cgis_trace_flow(
     depth: Annotated[
         int,
         Field(
-            description="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."
+            description="Maximum edge hops downstream, over calls, imports, inheritance, DI "
+            "dependencies and references (plus containment with include_structure)."
         ),
     ] = 3,
     output_format: OutputFormat = "mermaid",
+    include_structure: IncludeStructure = False,
+    include_external: IncludeExternal = False,
 ) -> str:
-    """Trace the execution call-graph starting from a specific FQN downwards.
+    """Downstream subgraph of one FQN: everything it reaches within ``depth`` hops.
+
+    Follows every edge except containment — in practice calls, imports,
+    inheritance, DI dependencies and references — between internal code, so this
+    answers "what does X depend on?". Containment and
+    stdlib/third-party nodes are left out unless ``include_structure`` /
+    ``include_external`` ask for them (external covers stdlib, third-party and
+    unresolved call targets) — the same view as the CLI's ``trace``.
+    For what depends on X use
+    ``cgis_analyze_impact``; for only the members of a module or class,
+    ``cgis_get_structure``; for a source-included brief to read before editing
+    one symbol, ``cgis_context``.
 
     ``output_format="mermaid"`` (default) returns a human-readable diagram;
     ``"json"`` returns a joinable ``{root, nodes, edges, coverage}`` payload
@@ -390,8 +427,13 @@ def cgis_trace_flow(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
+            allowed, show_external = _traversal_filters(include_structure, include_external)
             result = QueryEngine(store).get_flow_result(
-                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+                res.resolved,
+                max_depth=depth,
+                allowed_edge_types=allowed,
+                show_external=show_external,
+                with_coverage=_wants_json(output_format),
             )
     except Exception as exc:
         return f"❌ {exc}"
@@ -416,16 +458,28 @@ def cgis_analyze_impact(
     depth: Annotated[
         int,
         Field(
-            description="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."
+            description="Maximum edge hops upstream, over callers, importers, subclasses, "
+            "type references and DI dependents (plus the enclosing class or file with "
+            "include_structure)."
         ),
     ] = 3,
     output_format: OutputFormat = "mermaid",
+    include_structure: IncludeStructure = False,
+    include_external: IncludeExternal = False,
 ) -> str:
-    """Analyse transitive upstream callers of a specific FQN.
-
-    Answers "what breaks if I change X?". ``output_format="mermaid"`` (default)
+    """Upstream subgraph of one FQN: everything that reaches it within ``depth`` hops.
+
+    Follows every edge except containment — in practice callers, importers,
+    subclasses, type references and DI dependents — within internal code, so this
+    answers "what breaks if I change X?". The
+    enclosing class or file and stdlib/third-party nodes are left out unless
+    ``include_structure`` / ``include_external`` ask for them — the same view as
+    the CLI's ``impact``. For what X depends on use
+    ``cgis_trace_flow``; for only the members of a module or class,
+    ``cgis_get_structure``; for a source-included brief to read before editing
+    one symbol, ``cgis_context``.
+
+    ``output_format="mermaid"`` (default)
     returns a diagram; ``"json"`` returns a joinable ``{root, nodes, edges,
     coverage}`` payload with real FQNs — letting an agent compute set
     differences (e.g. "which route handlers never reach ``verify_ownership``?")
@@ -443,8 +497,13 @@ def cgis_analyze_impact(
             res = resolve_fqn(store, fqn)
             if res.resolved is None:
                 return _resolution_error(fqn, res.candidates, res.truncated)
+            allowed, show_external = _traversal_filters(include_structure, include_external)
             result = QueryEngine(store).get_impact_result(
-                res.resolved, max_depth=depth, with_coverage=_wants_json(output_format)
+                res.resolved,
+                max_depth=depth,
+                allowed_edge_types=allowed,
+                show_external=show_external,
+                with_coverage=_wants_json(output_format),
             )
     except Exception as exc:
         return f"❌ {exc}"
@@ -471,10 +530,13 @@ def cgis_get_structure(
     ] = 2,
     output_format: OutputFormat = "mermaid",
 ) -> str:
-    """Show the structural layout (CONTAINS/DECLARES) of a module or class.
+    """Members of a module or class: the classes, functions and methods it contains.
+
+    Follows containment (CONTAINS/DECLARES) only, so no call or import appears.
+    For how the code connects use ``cgis_trace_flow`` (what it depends on) or
+    ``cgis_analyze_impact`` (what depends on it).
 
-    Traverses only containment edges — no call-graph noise — matching the CLI
-    ``structure`` command. ``output_format="mermaid"`` (default) returns a
+    Matches the CLI ``structure`` command. ``output_format="mermaid"`` (default) returns a
     diagram of the hierarchy rooted at the given FQN; ``"json"`` returns the
     joinable ``{root, nodes, edges}`` payload with real FQNs.
     """
@@ -785,7 +847,15 @@ def cgis_context(
         ),
     ] = "",
 ) -> str:
-    """Compile an agent-facing GraphRAG context package for a focal FQN (#19).
+    """Prompt-ready brief on one FQN: its source, class, direct callers and callees.
+
+    Call this before editing a symbol, instead of reading its files. It follows
+    calls only, one hop by default. Source is included when the file is found
+    (see ``source_root``), and the domain when the graph was tagged with one.
+    For a multi-hop subgraph
+    over calls, imports, inheritance and references without source, use
+    ``cgis_trace_flow`` (downstream) or
+    ``cgis_analyze_impact`` (upstream).
 
     Returns an XML-tagged prompt — the focal node's source, its enclosing class,
     its architectural domain boundary, direct callers (upstream ripple) and
@@ -836,7 +906,7 @@ def cgis_metrics(
         ),
     ] = None,
 ) -> str:
-    """Whole-graph architectural metrics — coupling bottlenecks + God classes (#16).
+    """Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRank.
 
     Returns JSON ``{bottlenecks, god_classes, critical}`` computed with vectorized
     DuckDB aggregations over the whole graph (fan-in/fan-out coupling,
@@ -894,7 +964,7 @@ def cgis_find_orphans(
         bool, Field(description="Include machine-generated classes, which are hidden by default.")
     ] = False,
 ) -> str:
-    """Classes nothing in production builds, extends or names — dead-code candidates (#415).
+    """Classes nothing in production builds, extends or names — dead-code candidates.
 
     Finds classes that no test, type checker or linter flags, because each is
     still imported somewhere: a package re-export keeps a class importable long
@@ -976,7 +1046,7 @@ def cgis_audit_reachability(
         Field(description="Maximum reachability depth; a longer path is reported as a gap."),
     ] = 5,
 ) -> str:
-    """Reachability/authorization audit — which sources never reach a checkpoint (#172).
+    """Reachability/authorization audit — which sources never reach a checkpoint.
 
     The headline use is **IDOR/authz coverage**: list every route handler that does
     NOT transitively reach an ownership check. Reachability follows behavioral edges

{codegraph_brain-0.23.2 → codegraph_brain-0.23.4}/src/cgis/extractors/python_extractor.py

@@ -76,7 +76,10 @@ def _identifiers_outside_imports(root: BaseNode, code_bytes: bytes) -> set[str]:
             # strings (parent `type`): scanning every string would let a docstring
             # mentioning a name mask a real re-export.
             text = code_bytes[node.start_byte : node.end_byte].decode("utf8")
-            used.update(re.findall(r"[A-Za-z_][A-Za-z0-9_]*", text))
+            # `\w`, so a non-ASCII identifier in a quoted annotation counts as a
+            # use. Matching more here can only mark an import used, which is the
+            # safe direction for the unused-import sweep this feeds.
+            used.update(re.findall(r"[^\W\d]\w*", text))
         stack.extend(node.children)
     return used
 
@@ -197,6 +200,47 @@ def _collect_local_type(
         )
 
 
+def _walk_one_decorator(
+    functions: FunctionHandler,
+    decorator: BaseNode,
+    code_bytes: bytes,
+    file_path: str,
+    edges: list[Edge],
+    owner_fqn: str,
+    name_refs_acc: list[tuple[str, str, int]] | None,
+) -> None:
+    """Record one decorator's calls and names, skipping its own head (#429).
+
+    Everything except the decorator's own head name, which
+    `process_function_node` already records as `raw_call:<name>` from its
+    decorator list — walking that too emitted `router.post` twice under two
+    ids, and its name a third time as a REFERENCES.
+
+    Skipping the *head* rather than "everything but the outermost call's
+    arguments" is what keeps the rarer shapes: `@a.b(X)(Y)`, `@registry[X]`
+    and `@(deco(X))` all name something the narrower rule walked straight past.
+    """
+    head = _decorator_head(decorator)
+    stack = [c for c in decorator.children if c.type not in ("comment", "@")]
+    while stack:
+        current = stack.pop()
+        if head is not None and current.id == head.id:
+            continue
+        if current.type == "call" and _calls_directly(current, head):
+            # `@router.post(...)` — the decorator list already recorded this
+            # exact call as `raw_call:router.post`. Its arguments still need
+            # walking, so recurse without processing it.
+            stack.extend(current.children)
+            continue
+        if current.type == "call":
+            functions.process_call_node(
+                current, code_bytes, file_path, owner_fqn, edges, emit_di=False
+            )
+        elif current.type == "identifier" and name_refs_acc is not None and is_name_load(current):
+            _append_name_candidates(current, code_bytes, owner_fqn, name_refs_acc)
+        stack.extend(current.children)
+
+
 class PythonExtractor(BaseExtractor):
     """
     A concrete extractor for Python source code using tree-sitter.
@@ -589,38 +633,9 @@ class PythonExtractor(BaseExtractor):
         else `_walk` would have handled here.
         """
         for decorator in (c for c in node.children if c.type == "decorator"):
-            # Everything except the decorator's own head name, which
-            # `process_function_node` already records as `raw_call:<name>` from
-            # its decorator list — walking that too emitted `router.post` twice
-            # under two ids, and its name a third time as a REFERENCES.
-            #
-            # Skipping the *head* rather than "everything but the outermost
-            # call's arguments" is what keeps the rarer shapes: `@a.b(X)(Y)`,
-            # `@registry[X]` and `@(deco(X))` all name something the narrower
-            # rule walked straight past.
-            head = _decorator_head(decorator)
-            stack = [c for c in decorator.children if c.type not in ("comment", "@")]
-            while stack:
-                current = stack.pop()
-                if head is not None and current.id == head.id:
-                    continue
-                if current.type == "call" and _calls_directly(current, head):
-                    # `@router.post(...)` — the decorator list already recorded
-                    # this exact call as `raw_call:router.post`. Its arguments
-                    # still need walking, so recurse without processing it.
-                    stack.extend(current.children)
-                    continue
-                if current.type == "call":
-                    self._functions.process_call_node(
-                        current, code_bytes, file_path, owner_fqn, edges, emit_di=False
-                    )
-                elif (
-                    current.type == "identifier"
-                    and name_refs_acc is not None
-                    and is_name_load(current)
-                ):
-                    _append_name_candidates(current, code_bytes, owner_fqn, name_refs_acc)
-                stack.extend(current.children)
+            _walk_one_decorator(
+                self._functions, decorator, code_bytes, file_path, edges, owner_fqn, name_refs_acc
+            )
 
     def _handle_decorated_definition(
         self,

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

@@ -779,14 +779,25 @@ class SQLiteStore:
                 reason=f"ingest root {base} no longer exists — {hint}",
             )
 
-        tracked = self.get_tracked_source_files()
+        changed, missing = self._count_stale(base, self.get_tracked_source_files(), ingested_at)
+        if changed or missing:
+            return Freshness(state=FreshnessState.STALE, changed=changed, missing=missing)
+        return Freshness(state=FreshnessState.FRESH)
+
+    def _count_stale(self, base: str, tracked: set[str], ingested_at: float) -> tuple[int, int]:
+        """Files newer than the ingest, and files the graph has that the tree no longer does.
+
+        The two halves are complementary: a file's own mtime catches an edit, and
+        its directory's mtime catches an addition, a deletion or a new subdirectory.
+
+        `os.stat` on joined strings, not pathlib — the PTH rules are suppressed
+        deliberately here. Measured on this repository's own graph: the same 811
+        files cost 3.7 ms this way and 18.8 ms through `Path.stat()`, which is
+        slower than the tree walk this design exists to avoid. Tidying these to
+        `Path` would triple a cost paid on every query.
+        """
         changed = 0
         missing = 0
-        # `os.stat` on joined strings, not pathlib — the PTH rules are suppressed
-        # deliberately here. Measured on this repository's own graph: the same 811
-        # files cost 3.7 ms this way and 18.8 ms through `Path.stat()`, which is
-        # slower than the tree walk this design exists to avoid. Tidying these to
-        # `Path` would triple a cost paid on every query.
         for rel in tracked:
             try:
                 if os.stat(os.path.join(base, rel)).st_mtime > ingested_at:  # noqa: PTH116,PTH118
@@ -803,10 +814,7 @@ class SQLiteStore:
                 # Nothing added: the report says "N missing" of *files*, and every
                 # file under a vanished directory has already been counted above.
                 continue
-
-        if changed or missing:
-            return Freshness(state=FreshnessState.STALE, changed=changed, missing=missing)
-        return Freshness(state=FreshnessState.FRESH)
+        return changed, missing
 
     def _directory_gained_a_source(
         self, path: str, tracked: set[str], base: str, ingested_at: float