codegraph-brain 0.23.2__py3-none-any.whl → 0.23.4__py3-none-any.whl

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

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,

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

{codegraph_brain-0.23.2.dist-info → codegraph_brain-0.23.4.dist-info}/METADATA

@@ -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.dist-info → codegraph_brain-0.23.4.dist-info}/RECORD

@@ -5,7 +5,7 @@ cgis/pipeline.py,sha256=c-z6MJb9H06hWZQfvVwGQL2PUN3k0-Am-PCAHfMK0nQ,17048
 cgis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/api/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/api/__init__.py,sha256=wvFZK6oZspFGmonBz2rDg1aXxK7DHuE87or_w_cwY28,91
-cgis/api/mcp_server.py,sha256=M2lq_Eo8UO0H47yTrbyBvSPzsp8sKH01jQ4B2HWH1dg,44602
+cgis/api/mcp_server.py,sha256=b3HiTphKD1UcmKP1XwsawTrRLkvAAPRZLACxy1z1X8Y,47917
 cgis/core/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cgis/core/coverage.py,sha256=AmeZ_mij5Q382MAqtUmDRmJ_lHLPsV73k0_zksaWc6c,2469
 cgis/core/freshness.py,sha256=s1ahMqizX5jRo5Sj6T-2YfNq1d-jsRqisfne5m4yagw,1395
@@ -22,7 +22,7 @@ cgis/extractors/_python_imports.py,sha256=qvrO6sUG0O9O4k_P0TzibEu0dPwciW_A25CREy
 cgis/extractors/_python_types.py,sha256=N6xIOxVikpwkwrPfv1s_MwX6rw8QwzW2VeBXi7-g328,3462
 cgis/extractors/_typescript_bindings.py,sha256=_G7rN30LVMTeNBuEHY9LeLOM6PZV3J_2qYp42PRNDcg,6099
 cgis/extractors/base.py,sha256=4lhdFRqsj-3vBpeHZjnE3f9IWZ_WhbKQBxVAMuhzTho,1502
-cgis/extractors/python_extractor.py,sha256=KLp9bq4Bcqa6_upZdFGjTW8S-wOpHTGJMkNoAR3lcs0,29533
+cgis/extractors/python_extractor.py,sha256=U6MegkLa8rt33DGiv_4rNgNWYEocTqbv5hQ1lctOCb0,29884
 cgis/extractors/registry.py,sha256=SUZmkx34gfrCUa1cT09lWrT_Ngk1OK4fTMm4XJhwFWM,4078
 cgis/extractors/typescript_extractor.py,sha256=fs8l-KsyY35KnnsbWp9c5D_xeWdWRaCSLR_3N_S2ORA,11879
 cgis/guardian/__init__.py,sha256=H6BlKTayCLP34uGRC1zVt9NhN7RGo3tN9oep9Ja5SK0,48
@@ -86,9 +86,9 @@ cgis/resolver/js_builtins.py,sha256=cZ0F6DyqmPWVGHMgh0PVAv1VqGHO3IHs65cK9sX57CQ,
 cgis/resolver/symbols.py,sha256=A88dOb7ciEfWaS4KCK0Ho4cBC2IZisNrBfYp-f1LFYs,12545
 cgis/resolver/uplift.py,sha256=Hkye1q-kI-gKO6GIBYv3gUZj1AC0-_mkpoIpmwVsG4g,9591
 cgis/storage/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cgis/storage/sqlite_store.py,sha256=tlkg9kbiAFm0rth7ndsRPyv3cjDCj3dpvs7Pp_FTBno,45671
-codegraph_brain-0.23.2.dist-info/METADATA,sha256=Ul_KuCONXckwgxLZ6rE6LxtefLk-IQVyDmsJVKGhw9E,11771
-codegraph_brain-0.23.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-codegraph_brain-0.23.2.dist-info/entry_points.txt,sha256=mWajEQlAoWuiLyCQdD1TvvguloKQFmzKb52-g9PB_R4,123
-codegraph_brain-0.23.2.dist-info/licenses/LICENSE,sha256=1X36nOG5VocDaEGzAZqIv7uawy_7sWlFoiwECwx5aBI,1065
-codegraph_brain-0.23.2.dist-info/RECORD,,
+cgis/storage/sqlite_store.py,sha256=AXPlL1RGs38DmpIXuzrBY3JOavpSJDbwP5jorwAlD1c,46112
+codegraph_brain-0.23.4.dist-info/METADATA,sha256=kyI_tand59eW6i0ggOa3KEBMDiagLy07Z5LtdntTjn4,11771
+codegraph_brain-0.23.4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+codegraph_brain-0.23.4.dist-info/entry_points.txt,sha256=mWajEQlAoWuiLyCQdD1TvvguloKQFmzKb52-g9PB_R4,123
+codegraph_brain-0.23.4.dist-info/licenses/LICENSE,sha256=1X36nOG5VocDaEGzAZqIv7uawy_7sWlFoiwECwx5aBI,1065
+codegraph_brain-0.23.4.dist-info/RECORD,,