codegraph-brain 0.26.0__tar.gz → 0.27.0__tar.gz

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

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

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.27.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.26.0...codegraph-brain-v0.27.0) (2026-10-02)
+
+
+### Features
+
+* **mcp:** opt-in refresh of a stale graph before read tools answer ([#538](https://github.com/zaebee/codegraph-brain/issues/538)) ([b26a2c8](https://github.com/zaebee/codegraph-brain/commit/b26a2c8d335fbb2f19a217fcaced715f16454664))
+* **orphans:** consider module-level classes only by default ([#432](https://github.com/zaebee/codegraph-brain/issues/432)) ([#534](https://github.com/zaebee/codegraph-brain/issues/534)) ([731d93a](https://github.com/zaebee/codegraph-brain/commit/731d93a8b81fd02fe6b5e71892a408341d034239))
+* **suggest-packages:** judge a package by its direct children ([#446](https://github.com/zaebee/codegraph-brain/issues/446)) ([#536](https://github.com/zaebee/codegraph-brain/issues/536)) ([fd6f05b](https://github.com/zaebee/codegraph-brain/commit/fd6f05b003ea006392e6384170a4bead227f5e85))
+
+
+### Bug Fixes
+
+* **freshness:** report a write made during ingest as stale ([#535](https://github.com/zaebee/codegraph-brain/issues/535)) ([4121919](https://github.com/zaebee/codegraph-brain/commit/4121919148affbad202156d43d01fca458beca23))
+* **resolver:** classify declared Python dependencies as external ([#495](https://github.com/zaebee/codegraph-brain/issues/495)) ([#531](https://github.com/zaebee/codegraph-brain/issues/531)) ([ca4c01d](https://github.com/zaebee/codegraph-brain/commit/ca4c01d1ffa8e8c754317af73ffcf06d534a61d7))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#532](https://github.com/zaebee/codegraph-brain/issues/532)) ([13c90fd](https://github.com/zaebee/codegraph-brain/commit/13c90fd3ebcc38271b697f514d292c7033d4f81d))
+* auto-sync architecture graph and MCP reference ([#537](https://github.com/zaebee/codegraph-brain/issues/537)) ([c03f60d](https://github.com/zaebee/codegraph-brain/commit/c03f60d4211e3029d02a624ef9d6b4fa92f184df))
+* **onboarding:** refresh the graph from hooks instead of a watcher ([#541](https://github.com/zaebee/codegraph-brain/issues/541)) ([809169d](https://github.com/zaebee/codegraph-brain/commit/809169d19797e280b0810f049215950b3eedf1df)), closes [#175](https://github.com/zaebee/codegraph-brain/issues/175)
+
 ## [0.26.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.25.4...codegraph-brain-v0.26.0) (2026-10-02)
 
 

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.26.0
+Version: 0.27.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

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/docs/architecture/HOW_IT_WORKS.md

@@ -188,35 +188,37 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_import_names["import_names.py"]
-        import_names_ImportNameCollector["ImportNameCollector (import_names.py:49)"]:::classNode
-        import_names_ImportNameCollector_collect["collect (import_names.py:64)"]:::methodNode
-        import_names_ImportNameCollector_note["note (import_names.py:57)"]:::methodNode
+        import_names_ImportNameCollector["ImportNameCollector (import_names.py:58)"]:::classNode
+        import_names_ImportNameCollector_collect["collect (import_names.py:74)"]:::methodNode
+        import_names_ImportNameCollector_note["note (import_names.py:67)"]:::methodNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:266)"]:::methodNode
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:401)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:327)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:351)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:229)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:100)"]:::methodNode
-        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:83)"]:::methodNode
+        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:292)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:427)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:353)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:377)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:252)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:115)"]:::methodNode
+        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:98)"]:::methodNode
+        pipeline_observe["_observe (pipeline.py:56)"]:::funcNode
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:49)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:80)"]:::methodNode
+        engine_ResolverEngine_resolve["resolve (engine.py:85)"]:::methodNode
     end
     subgraph sg_uplift["uplift.py"]
         uplift_SemanticUpliftEngine["SemanticUpliftEngine (uplift.py:66)"]:::classNode
         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:58)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:63)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
     pipeline_IngestionPipeline_run -->|REFERENCES| sqlite_store_SQLiteStore
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_workspace_root
     pipeline_IngestionPipeline_run -->|CALLS| import_names_ImportNameCollector
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_observe
     pipeline_IngestionPipeline_run -->|CALLS| import_names_ImportNameCollector_note
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file
@@ -235,19 +237,20 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 |--------|------|------|
 | `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
 | `Edge` | CLASS | [`models.py:142`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L142) |
-| `ImportNameCollector` | CLASS | [`import_names.py:49`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/import_names.py#L49) |
-| `note` | METHOD | [`import_names.py:57`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/import_names.py#L57) |
-| `collect` | METHOD | [`import_names.py:64`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/import_names.py#L64) |
-| `workspace_root` | METHOD | [`pipeline.py:83`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L83) |
-| `run` | METHOD | [`pipeline.py:100`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L100) |
-| `_process_file` | METHOD | [`pipeline.py:229`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L229) |
-| `_cross_file_inputs_changed` | METHOD | [`pipeline.py:266`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L266) |
-| `_is_noop_incremental` | METHOD | [`pipeline.py:327`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L327) |
-| `_persist_incremental` | METHOD | [`pipeline.py:351`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L351) |
-| `_get_extractor` | METHOD | [`pipeline.py:401`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L401) |
+| `ImportNameCollector` | CLASS | [`import_names.py:58`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/import_names.py#L58) |
+| `note` | METHOD | [`import_names.py:67`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/import_names.py#L67) |
+| `collect` | METHOD | [`import_names.py:74`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/import_names.py#L74) |
+| `_observe` | FUNCTION | [`pipeline.py:56`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L56) |
+| `workspace_root` | METHOD | [`pipeline.py:98`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L98) |
+| `run` | METHOD | [`pipeline.py:115`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L115) |
+| `_process_file` | METHOD | [`pipeline.py:252`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L252) |
+| `_cross_file_inputs_changed` | METHOD | [`pipeline.py:292`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L292) |
+| `_is_noop_incremental` | METHOD | [`pipeline.py:353`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L353) |
+| `_persist_incremental` | METHOD | [`pipeline.py:377`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L377) |
+| `_get_extractor` | METHOD | [`pipeline.py:427`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L427) |
 | `ResolverEngine` | CLASS | [`engine.py:49`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L49) |
-| `resolve` | METHOD | [`engine.py:80`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L80) |
+| `resolve` | METHOD | [`engine.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L85) |
 | `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:58`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L58) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:63`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L63) |
 <!-- END_CGIS_GRAPH -->

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -12,35 +12,37 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_import_names["import_names.py"]
-        import_names_ImportNameCollector["ImportNameCollector (import_names.py:49)"]:::classNode
-        import_names_ImportNameCollector_collect["collect (import_names.py:64)"]:::methodNode
-        import_names_ImportNameCollector_note["note (import_names.py:57)"]:::methodNode
+        import_names_ImportNameCollector["ImportNameCollector (import_names.py:58)"]:::classNode
+        import_names_ImportNameCollector_collect["collect (import_names.py:74)"]:::methodNode
+        import_names_ImportNameCollector_note["note (import_names.py:67)"]:::methodNode
     end
     subgraph sg_pipeline["pipeline.py"]
-        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:266)"]:::methodNode
-        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:401)"]:::methodNode
-        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:327)"]:::methodNode
-        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:351)"]:::methodNode
-        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:229)"]:::methodNode
-        pipeline_IngestionPipeline_run["run (pipeline.py:100)"]:::methodNode
-        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:83)"]:::methodNode
+        pipeline_IngestionPipeline_cross_file_inputs_changed["_cross_file_inputs_changed (pipeline.py:292)"]:::methodNode
+        pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:427)"]:::methodNode
+        pipeline_IngestionPipeline_is_noop_incremental["_is_noop_incremental (pipeline.py:353)"]:::methodNode
+        pipeline_IngestionPipeline_persist_incremental["_persist_incremental (pipeline.py:377)"]:::methodNode
+        pipeline_IngestionPipeline_process_file["_process_file (pipeline.py:252)"]:::methodNode
+        pipeline_IngestionPipeline_run["run (pipeline.py:115)"]:::methodNode
+        pipeline_IngestionPipeline_workspace_root["workspace_root (pipeline.py:98)"]:::methodNode
+        pipeline_observe["_observe (pipeline.py:56)"]:::funcNode
     end
     subgraph sg_engine["engine.py"]
         engine_ResolverEngine["ResolverEngine (engine.py:49)"]:::classNode
-        engine_ResolverEngine_resolve["resolve (engine.py:80)"]:::methodNode
+        engine_ResolverEngine_resolve["resolve (engine.py:85)"]:::methodNode
     end
     subgraph sg_uplift["uplift.py"]
         uplift_SemanticUpliftEngine["SemanticUpliftEngine (uplift.py:66)"]:::classNode
         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:58)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:63)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
     pipeline_IngestionPipeline_run -->|REFERENCES| sqlite_store_SQLiteStore
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_workspace_root
     pipeline_IngestionPipeline_run -->|CALLS| import_names_ImportNameCollector
+    pipeline_IngestionPipeline_run -->|CALLS| pipeline_observe
     pipeline_IngestionPipeline_run -->|CALLS| import_names_ImportNameCollector_note
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_get_extractor
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_process_file

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/docs/how-to/AGENT_ONBOARDING.md

@@ -55,6 +55,60 @@ Point `--output` at a `.db` file. For large repos, add `--incremental` to skip u
 }
 ```
 
+### Keeping the graph current (opt-in)
+
+Set `"CGIS_AUTO_REFRESH": "1"` in the server's `env` and every graph-reading
+tool first checks whether the files behind the graph changed since the last
+ingest; if they did, it runs an incremental `cgis_ingest` from the recorded
+root with the recorded `--source-root`/`--domains` options before answering.
+A fresh graph costs a few milliseconds of `stat` calls. A stale one costs an
+incremental ingest: under a second for a body edit, a full rebuild when a
+symbol was added, renamed or removed. It never creates a missing database,
+and a graph ingested before this option existed is only reported stale, not
+refreshed, until it is ingested once more.
+
+### Refreshing outside the MCP server: hooks, not a watcher
+
+cgis has no watch mode, on purpose (#175). A watcher re-ingests on every save,
+and an agent's multi-file edit is a burst of saves, each of which can cost a
+full rebuild; the graph only needs to be current when something reads it. If
+you query from the CLI, or want the graph current before the agent's next
+turn, hang an incremental ingest on an event that ends a burst instead. Use the
+same path and `--source-root`/`--domains` the graph was built with (`./src`
+as in Step 1); a different path renames every node.
+
+**Claude Code** — once per finished turn, not once per edit
+(`.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && cgis ingest ./src -o graph.db -i >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**git** — after a checkout, pull or rebase swaps many files at once
+(`.git/hooks/post-checkout`, and the same body in `post-merge` and
+`post-rewrite`; make each executable):
+
+```sh
+#!/bin/sh
+cgis ingest ./src -o graph.db -i >/dev/null 2>&1 || true
+```
+
+`|| true` keeps a failed ingest from failing the hook; the read commands will
+still say the graph is stale.
+
 ---
 
 ## Step 3: Available MCP tools

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/docs/how-to/MCP_REFERENCE.md

@@ -160,7 +160,14 @@ Classes nothing in production builds, extends or names — dead-code candidates.
     reported orphans were generated entities and the sixth a nested pydantic
     ``Config``: the unfiltered report had no actionable row in it (#432).
 
-    Returns JSON ``{orphans, considered, test_sources, generated_excluded}``;
+    Only **module-level** classes are considered by default; ``include_nested``
+    adds classes defined inside a class or function. Across eight measured
+    repositories none of the 46 nested rows was dead: most were a ``Meta`` /
+    ``Config`` a metaclass reads, the rest live classes reached as
+    ``self.Nested(...)``, which the resolver does not follow (#432).
+
+    Returns JSON ``{orphans, considered, test_sources, generated_excluded,
+    nested_excluded}``;
     each orphan carries ``fqn``/``file``/``line``. **A listing is a candidate for
     deletion, not a proof** — a class named only inside a decorator (#429) or
     arriving through a star import is invisible here, so the sweep errs towards
@@ -177,6 +184,7 @@ Classes nothing in production builds, extends or names — dead-code candidates.
 | `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. |
+| `include_nested` | `boolean` |  | Include classes nested in a class or function, which are hidden by default. |
 
 ---
 
@@ -377,10 +385,14 @@ Suggest sub-package boundaries for a package from its dependency communities.
 
     Returns JSON: modularity_q, divergence, direction (under/over/matched),
     verdict (split/consolidate/aligned/leave/borderline/no_signal), the detected
-    communities (id + member files), the cross-community bridge edges (cost of
+    communities (id + members), the cross-community bridge edges (cost of
     splitting), and the thresholds used. Default layer is IMPORTS; set
     ``with_calls`` for the combined import+call graph. Run ``cgis_ingest`` first.
 
+    Members are the package's direct children by default, each sub-package one
+    node, so the verdict says whether to regroup them; ``level`` in the result
+    says which. ``all_descendants`` clusters every file below the package.
+
     A mis-rooted graph (import targets resolve to no internal file) returns
     ``no_signal`` with a diagnostic note rather than a silent clean verdict.
 
@@ -390,6 +402,7 @@ Suggest sub-package boundaries for a package from its dependency communities.
 | `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). |
+| `all_descendants` | `boolean` |  | Cluster every file below the package and compare with its sub-directories, instead of treating each sub-package as one node. |
 
 ---
 

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/docs/specs/2026-06-11-fastapi-di-edges-design.md

@@ -135,6 +135,31 @@ parameter also matched case (b) (an explicit `Depends` inside its
 `raw_dep:` candidate for the *outer* annotation is still emitted too — it
 will resolve to a CLASS/external and be dropped; no dedup logic needed.
 
+**d) DI in a route decorator (#429, added after slice 1).**
+`@router.post(..., dependencies=[Depends(guard)])` declares a guard at the
+decorator instead of the signature. The `Depends`/`Security` call there is
+handled by the same hook as §3.2b, with one deliberate exception to the rule
+that an edge's source is its lexical owner: the DEPENDS_ON edge is sourced at
+the **decorated function**, not the module the decorator sits in. FastAPI runs
+the dependency before that function, and `cgis audit` reads DEPENDS_ON as the
+evidence a route is guarded, so a module-sourced edge would be accurate about
+location and useless as evidence.
+
+- Only a decorated `function_definition` / `async_function_definition`
+  (including methods) gets the edge. A decorated **class** keeps the
+  CALLS-only treatment: FastAPI never treats a class decorator as a
+  dependant.
+- Name-extraction rules are §3.2b's: first positional argument only; argless
+  and keyword-only (`Depends(dependency=guard)`) calls emit no edge.
+- This is the only place the exception applies. Calls and name references in
+  decorators were already sourced at the decorated definition (#434) — a
+  decorator has no other owner — so the exception is confined to DI, which is
+  the edge kind that carries "this runs before that" semantics.
+
+Population note: on owner-api at `b7d02fe6` one route declared its guard this
+way, against 238 in the signature. The edge is cheap and closes a false
+"unguarded" in a security-facing report; it is not expected to move counts.
+
 ### 3.3 Resolver (`src/cgis/resolver/engine.py`)
 
 - `RAW_DEP_PREFIX = "raw_dep:"` defined here as a module-level constant,

{codegraph_brain-0.26.0 → codegraph_brain-0.27.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["src/cgis"]
 
 [project]
 name = "codegraph-brain"
-version = "0.26.0"
+version = "0.27.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.26.0 → codegraph_brain-0.27.0}/server.json

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

codegraph_brain-0.27.0/src/cgis/api/auto_refresh.py

@@ -0,0 +1,110 @@
+"""Refresh a stale graph before a read tool answers from it (#175).
+
+Opt-in: set `CGIS_AUTO_REFRESH=1` in the MCP server's environment. Off by
+default, because it turns every graph-reading tool into one that may write
+the database and take as long as a full rebuild.
+
+A refresh is an incremental ingest from the recorded root with the recorded
+options, so it is the same graph `cgis_ingest` would leave, not a guess at it.
+It never runs on a missing database (there is no root to ingest from), on an
+`UNKNOWN` graph, or on one whose ingest options were never recorded. Whatever
+it declines or fails to do, the tool still answers and its freshness note
+still says the graph is stale.
+"""
+
+import os
+import threading
+import time
+from collections.abc import Callable
+from functools import wraps
+from inspect import signature
+from pathlib import Path
+
+import structlog
+
+from cgis.core.freshness import FreshnessState
+from cgis.extractors.registry import build_extractors
+from cgis.pipeline import IngestionPipeline
+from cgis.storage.sqlite_store import SQLiteStore
+
+logger = structlog.getLogger(__name__)
+
+#: The environment variable that turns refreshing on.
+AUTO_REFRESH_ENV = "CGIS_AUTO_REFRESH"
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+#: One refresh at a time in this process. A second caller waits, then finds the
+#: graph fresh and returns, rather than racing the first into "database is
+#: locked" once a rebuild outlasts SQLite's busy timeout.
+_LOCK = threading.Lock()
+
+
+def auto_refresh_enabled() -> bool:
+    """True when the server's environment opts in to refreshing stale graphs."""
+    return os.environ.get(AUTO_REFRESH_ENV, "").strip().lower() in _TRUTHY
+
+
+def refresh_if_stale(db_path: str) -> bool:
+    """Bring `db_path` up to date if it is stale and can be refreshed; True if it ran.
+
+    Never raises: a refresh is a courtesy on top of the query the caller asked
+    for, and a failed one leaves the stored graph as it was.
+    """
+    if not auto_refresh_enabled() or not Path(db_path).is_file():
+        return False
+    with _LOCK:
+        try:
+            return _refresh(db_path)
+        except Exception as exc:
+            logger.warning("Auto-refresh failed; answering from the stored graph", error=str(exc))
+            return False
+
+
+def _refresh(db_path: str) -> bool:
+    """The refresh itself, run under the lock: freshness is re-read here, not before."""
+    with SQLiteStore(db_path) as store:
+        if store.freshness().state is not FreshnessState.STALE:
+            return False
+        recorded = store.get_ingest_state()
+        options = store.get_ingest_options()
+        if recorded is None or options is None:
+            logger.info("Graph is stale but its ingest options were never recorded; not refreshing")
+            return False
+        root = recorded[0]
+        source_roots, domains = options
+        if domains is not None and not Path(domains).is_file():
+            logger.info(
+                "Graph is stale but its domains file is gone; not refreshing", domains=domains
+            )
+            return False
+        started = time.perf_counter()
+        pipeline = IngestionPipeline(build_extractors(source_roots), domains_config=domains)
+        nodes, _raw, _resolved = pipeline.run(root, store=store)
+        if nodes:
+            store.record_ingest(root, pipeline.observed_mtimes)
+        logger.info(
+            "Auto-refreshed stale graph",
+            db=db_path,
+            root=root,
+            seconds=round(time.perf_counter() - started, 3),
+        )
+        return True
+
+
+def refreshes_graph[**P, R](tool: Callable[P, R]) -> Callable[P, R]:
+    """Refresh the tool's `db_path` graph, if opted in and stale, before the tool runs.
+
+    `wraps` keeps the signature the MCP SDK builds the tool's schema from.
+    """
+    params = signature(tool)
+
+    @wraps(tool)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        bound = params.bind(*args, **kwargs)
+        bound.apply_defaults()
+        db_path = bound.arguments.get("db_path")
+        if isinstance(db_path, str):
+            refresh_if_stale(db_path)
+        return tool(*args, **kwargs)
+
+    return wrapper