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

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

@@ -0,0 +1 @@
+2775

codegraph_brain-0.27.0/.github/workflows/ui.yml

@@ -0,0 +1,68 @@
+name: UI
+
+# The graph debugger in ui/ had no CI at all (#452): ci.yml runs only the Python
+# toolchain, so a change there could break the build and still merge green. It
+# had already happened — when this job was added, main carried six eslint errors
+# and two TypeScript errors that nothing had reported.
+#
+# Path-filtered so Python-only changes do not pay for a bun install, and the
+# workflow file itself is in the filter so an edit to it runs it.
+on:
+  push:
+    branches: [ main, dev, "feat/**", "fix/**", "docs/**" ]
+    paths: [ "ui/**", ".github/workflows/ui.yml" ]
+  pull_request:
+    branches: [ main ]
+    paths: [ "ui/**", ".github/workflows/ui.yml" ]
+
+permissions:
+  contents: read
+
+jobs:
+  ui-ci:
+    name: UI Verification
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ui
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6  # v2.2.0
+        with:
+          # Pinned rather than "latest": the lockfile format moves with bun, and
+          # a runner picking up a new release must not be what turns this red.
+          bun-version: 1.3.14
+
+      - name: Install Dependencies
+        # --frozen-lockfile fails when bun.lock is out of step with package.json,
+        # the job's equivalent of `uv lock --check` in ci.yml. --ignore-scripts
+        # because no dependency here needs an install hook — verified by running
+        # every step below from a clean install with it — so none gets to run
+        # code on the runner (Sonar githubactions:S6505).
+        run: bun install --frozen-lockfile --ignore-scripts
+
+      - name: ESLint
+        run: bun run lint
+
+      - name: Prettier
+        # eslint-config-prettier turns ESLint's style rules off, so formatting is
+        # checked here or nowhere; 31 files had drifted before this step existed.
+        run: bun run format:check
+
+      - name: TypeScript
+        # Vite transpiles TypeScript without type-checking it, so `build` below
+        # passes a type error. This is the only step that reads the types.
+        # Through a package script, so it runs the `typescript` pinned in
+        # bun.lock; `bunx tsc` could fetch an unpinned one (Sonar S8543).
+        run: bun run typecheck
+
+      - name: Tests
+        # vitest, not `bun test`: the native runner has no `vi.mock` hoisting, and
+        # component tests that use it fail under it (ui/AGENTS.md).
+        run: bun run test:run
+
+      - name: Build
+        run: bun run build

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

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

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

@@ -1,5 +1,50 @@
 # 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)
+
+
+### Features
+
+* **metrics:** LCOM4 class cohesion ([#521](https://github.com/zaebee/codegraph-brain/issues/521)) ([ed46366](https://github.com/zaebee/codegraph-brain/commit/ed46366f57af23e8b4aba66b6346c246d47a1c24))
+* **metrics:** per-file afferent/efferent coupling and instability ([#520](https://github.com/zaebee/codegraph-brain/issues/520)) ([32393e6](https://github.com/zaebee/codegraph-brain/commit/32393e63f4f8dc9a193cfd6ccba4a18a0d52268a))
+* **metrics:** report the unresolved-edge share beside the rankings ([#519](https://github.com/zaebee/codegraph-brain/issues/519)) ([97699f8](https://github.com/zaebee/codegraph-brain/commit/97699f8bd52eb97c6dc32cbf5d6fcc1bfa752d1b)), closes [#451](https://github.com/zaebee/codegraph-brain/issues/451)
+
+
+### Bug Fixes
+
+* **drift:** measure unresolved_ratio on stored graphs, carry it to the quotient ([#149](https://github.com/zaebee/codegraph-brain/issues/149)) ([#526](https://github.com/zaebee/codegraph-brain/issues/526)) ([80c3b5a](https://github.com/zaebee/codegraph-brain/commit/80c3b5a0a41bd45ab37cc24d2f4ae06fe24e752c))
+* **guardian:** record GUARDIAN_FEATURES on each review row ([#516](https://github.com/zaebee/codegraph-brain/issues/516)) ([007408c](https://github.com/zaebee/codegraph-brain/commit/007408c0f96e9b175b389db773e51d6838b0738b))
+* **resolver:** resolve TypeScript imports through tsconfig paths aliases ([#513](https://github.com/zaebee/codegraph-brain/issues/513)) ([94219d7](https://github.com/zaebee/codegraph-brain/commit/94219d7e136195bad4eac69a72e25dfd2b3e621f))
+* **resolver:** strip only corroborated layout prefixes when reconciling an FQN ([#319](https://github.com/zaebee/codegraph-brain/issues/319)) ([#527](https://github.com/zaebee/codegraph-brain/issues/527)) ([5fe77f4](https://github.com/zaebee/codegraph-brain/commit/5fe77f47c0ac251a73c8820f91f1cc1f1bc13020))
+* **ui:** fit the view after React Flow renders the new layout ([#523](https://github.com/zaebee/codegraph-brain/issues/523)) ([7be630f](https://github.com/zaebee/codegraph-brain/commit/7be630f5d3734b3d2b7ff23d032380af4a90f19c))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#514](https://github.com/zaebee/codegraph-brain/issues/514)) ([5abdebd](https://github.com/zaebee/codegraph-brain/commit/5abdebd482071e8e1f24c19559c984fc874d86b6))
+
 ## [0.25.4](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.25.3...codegraph-brain-v0.25.4) (2026-09-25)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.25.4
+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.25.4 → codegraph_brain-0.27.0}/docs/architecture/HOW_IT_WORKS.md

@@ -187,50 +187,48 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Edge["Edge (models.py:142)"]:::classNode
         models_Node["Node (models.py:85)"]:::classNode
     end
+    subgraph sg_import_names["import_names.py"]
+        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:77)"]:::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:56)"]:::classNode
-        sqlite_store_SQLiteStore_get_workspace_packages["get_workspace_packages (sqlite_store.py:1085)"]:::methodNode
-        sqlite_store_SQLiteStore_record_workspace_packages["record_workspace_packages (sqlite_store.py:1071)"]:::methodNode
-    end
-    subgraph sg_workspaces["workspaces.py"]
-        workspaces_WorkspacePackages["WorkspacePackages (workspaces.py:23)"]:::classNode
-        workspaces_WorkspacePackages_note["note (workspaces.py:39)"]:::methodNode
-        workspaces_WorkspacePackages_unambiguous["unambiguous (workspaces.py:67)"]:::methodNode
+        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| workspaces_WorkspacePackages
-    pipeline_IngestionPipeline_run -->|CALLS| workspaces_WorkspacePackages_note
+    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
-    pipeline_IngestionPipeline_run -->|CALLS| workspaces_WorkspacePackages_unambiguous
-    pipeline_IngestionPipeline_run -->|CALLS| sqlite_store_SQLiteStore_get_workspace_packages
+    pipeline_IngestionPipeline_run -->|CALLS| import_names_ImportNameCollector_collect
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine_resolve
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_run
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_cross_file_inputs_changed
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_persist_incremental
-    pipeline_IngestionPipeline_run -->|CALLS| sqlite_store_SQLiteStore_record_workspace_packages
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine_execute_uplift
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine
 ```
@@ -239,21 +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) |
-| `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:77`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L77) |
+| `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:56`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L56) |
-| `record_workspace_packages` | METHOD | [`sqlite_store.py:1071`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L1071) |
-| `get_workspace_packages` | METHOD | [`sqlite_store.py:1085`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L1085) |
-| `WorkspacePackages` | CLASS | [`workspaces.py:23`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/workspaces.py#L23) |
-| `note` | METHOD | [`workspaces.py:39`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/workspaces.py#L39) |
-| `unambiguous` | METHOD | [`workspaces.py:67`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/workspaces.py#L67) |
+| `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.25.4 → codegraph_brain-0.27.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -11,49 +11,47 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         models_Edge["Edge (models.py:142)"]:::classNode
         models_Node["Node (models.py:85)"]:::classNode
     end
+    subgraph sg_import_names["import_names.py"]
+        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:77)"]:::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:56)"]:::classNode
-        sqlite_store_SQLiteStore_get_workspace_packages["get_workspace_packages (sqlite_store.py:1085)"]:::methodNode
-        sqlite_store_SQLiteStore_record_workspace_packages["record_workspace_packages (sqlite_store.py:1071)"]:::methodNode
-    end
-    subgraph sg_workspaces["workspaces.py"]
-        workspaces_WorkspacePackages["WorkspacePackages (workspaces.py:23)"]:::classNode
-        workspaces_WorkspacePackages_note["note (workspaces.py:39)"]:::methodNode
-        workspaces_WorkspacePackages_unambiguous["unambiguous (workspaces.py:67)"]:::methodNode
+        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| workspaces_WorkspacePackages
-    pipeline_IngestionPipeline_run -->|CALLS| workspaces_WorkspacePackages_note
+    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
-    pipeline_IngestionPipeline_run -->|CALLS| workspaces_WorkspacePackages_unambiguous
-    pipeline_IngestionPipeline_run -->|CALLS| sqlite_store_SQLiteStore_get_workspace_packages
+    pipeline_IngestionPipeline_run -->|CALLS| import_names_ImportNameCollector_collect
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_is_noop_incremental
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine
     pipeline_IngestionPipeline_run -->|CALLS| engine_ResolverEngine_resolve
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_run
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_cross_file_inputs_changed
     pipeline_IngestionPipeline_run -->|CALLS| pipeline_IngestionPipeline_persist_incremental
-    pipeline_IngestionPipeline_run -->|CALLS| sqlite_store_SQLiteStore_record_workspace_packages
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine_execute_uplift
     pipeline_IngestionPipeline_run -->|CALLS| uplift_SemanticUpliftEngine

{codegraph_brain-0.25.4 → 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.25.4 → 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. |
 
 ---
 
@@ -302,12 +310,28 @@ Propose a starter patterns.yaml from the measured graph (read-only).
 
 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,
-    declared-member counts, PageRank) — the global "what are the hotspots?" view
-    that complements the node-local trace/impact/context tools. Requires the
-    optional ``duckdb`` extra; an unavailable dependency is reported as a normal
-    ❌ message.
+    Returns JSON ``{bottlenecks, god_classes, critical, file_coupling, class_cohesion,
+    resolution}``
+    computed with vectorized DuckDB aggregations over the whole graph (fan-in/fan-out
+    coupling, declared-member counts, PageRank, per-file Ca/Ce/instability) — the
+    global "what are the hotspots?" view that complements the node-local
+    trace/impact/context tools. Requires the optional ``duckdb`` extra; an
+    unavailable dependency is reported as a normal ❌ message.
+
+    ``file_coupling`` counts *files*, not calls: Ca is how many other files
+    depend on a file (by IMPORTS or CALLS), Ce how many it depends on, and
+    instability ``I = Ce / (Ca + Ce)`` runs from 0 (stable, expensive to change)
+    to 1 (volatile); it is null for a file linked to no other.
+
+    ``class_cohesion`` ranks classes by LCOM4: the number of groups their instance
+    methods fall into when linked by a shared ``self`` attribute or a call. 1 is
+    cohesive; 2+ is a class doing unrelated jobs. Dunders (``__init__`` above
+    all), abstract, static and class methods are not counted.
+
+    ``resolution`` is the share of edges the resolver could not place, by the
+    same rule as ``cgis validate``. Read the rankings through it: a node whose
+    calls are mostly unresolved looks uncoupled because its edges point nowhere.
+    Under ``scope``/``exclude`` it counts the edges the selected code *emits*.
 
     ``exclude`` drops any node whose FQN contains one of the given dot-segments
     (e.g. ``["tests"]`` removes both ``tests.*`` and ``domains.*.tests.*``) so
@@ -361,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.
 
@@ -374,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.25.4 → codegraph_brain-0.27.0}/docs/ontology/patterns.yaml

@@ -128,18 +128,24 @@ project_domains:
     # deflating this domain's drift; 0.37 is the honest census of the real structure (no real
     # edges lost — verified by edge-diff). Correctness-driven re-baseline, not ratchet loosening.
     drift_tolerance: 0.40
+    hygiene_baseline:
+      unresolved_ratio: 0.37 # measured 0.3604 when the gate came alive (#149)
 
   - name: "resolution"
     fqn_prefix: "cgis.resolver"
     expected_pattern: pipeline_stage
     profile: python
     drift_tolerance: 0.40 # v2 measured ≈0.25 post-#115 split (tv_imp 0.00 — real 021C chain engine→symbols→indices; residual is tv_calls)
+    hygiene_baseline:
+      unresolved_ratio: 0.45 # measured 0.4451 when the gate came alive (#149)
 
   - name: "pipeline"
     fqn_prefix: "cgis.pipeline"
     expected_pattern: orchestrator
     profile: python
     drift_tolerance: 0.25 # v2 measured ≈0.20 (tv_calls .36)
+    hygiene_baseline:
+      unresolved_ratio: 0.43 # measured 0.4220 when the gate came alive (#149)
 
   - name: "storage"
     fqn_prefix: "cgis.storage"
@@ -151,7 +157,17 @@ project_domains:
     fqn_prefix: "cgis.query"
     expected_pattern: layered_dag
     profile: python
-    drift_tolerance: 0.20 # v2 re-baselined ≈0.19 after ontology_init joined the domain (#174) — was ≈0.14/0.18
+    # Re-baselined 0.20 -> 0.21 for #451 LCOM4: origin/main 32393e6 scored 0.1997, one
+    # rounding step under the line; the class-cohesion metric's reuse of the shared
+    # scope/exclusion helpers adds fan-in calls (T_calls 021U 0.128 -> 0.133) and
+    # scores 0.2006. History: v2 ≈0.19 after ontology_init joined (#174), was ≈0.14/0.18.
+    # Re-baselined 0.21 -> 0.23 in #149: unresolved_ratio read 0 on every stored graph
+    # (only `raw_call:` targets were counted, and the resolver turns those into UNKNOWN
+    # nodes before saving). Measured honestly it is 0.2787: the acknowledged debt still
+    # scores, and discounts the CALLS layer — 0.2026 -> 0.2212. Correctness-driven, like #183.
+    drift_tolerance: 0.23
+    hygiene_baseline:
+      unresolved_ratio: 0.28 # measured 0.2787 when the gate came alive (#149)
 
   # Bound in #182: these three were production code with no architectural gate at
   # all — 207 of 618 internal nodes (33%) sat outside every domain, guardian alone
@@ -164,6 +180,8 @@ project_domains:
     profile: python
     drift_tolerance: 0.26 # v2 measured 0.2282; dag_depth 5 clears the template's min 3
                           # (runner-up dispatcher 0.34 — a clear win, not a coin flip)
+    hygiene_baseline:
+      unresolved_ratio: 0.28 # measured 0.2778 when the gate came alive (#149)
 
   # cli and api are hygiene-only by rule, not by taste: neither has ANY
   # intra-domain IMPORTS edge (cli is one file, api is two), so there is no
@@ -176,7 +194,9 @@ project_domains:
   - name: "cli"
     fqn_prefix: "cgis.cli"
     profile: python
-    drift_tolerance: 0.03 # hygiene-only; measured 0.00 (no cycles, nothing unresolved)
+    drift_tolerance: 0.03 # hygiene-only; measured 0.00 (no cycles)
+    hygiene_baseline:
+      unresolved_ratio: 0.24 # measured 0.2309 when the gate came alive (#149)
 
   - name: "api"
     fqn_prefix: "cgis.api"
@@ -189,19 +209,29 @@ project_domains:
     expected_pattern: layered_dag
     profile: typescript
     params: {min_depth: 2} # JSX component trees are legitimately shallower
-    drift_tolerance: 0.20 # v2 measured ≈0.17 (tv_imp .28; CALLS layer empty → excluded)
+    # Re-baselined 0.20 -> 0.24 in #149: unresolved_ratio now counts UNKNOWN targets
+    # (0.9036 — the TS resolver places few calls), 0.1667 -> 0.2370. See query.
+    drift_tolerance: 0.24
+    hygiene_baseline:
+      unresolved_ratio: 0.91 # measured 0.9036 when the gate came alive (#149)
 
   - name: "layout"
     fqn_prefix: "layout"
     expected_pattern: pure_utility
     profile: typescript
     drift_tolerance: 0.50 # v2 measured ≈0.46 — 4 CALLS triples (small-N, spec §3.6.1); revisit with TS resolver
+    hygiene_baseline:
+      unresolved_ratio: 0.66 # measured 0.6522 when the gate came alive (#149)
 
   # Hygiene-only domains (no expected_pattern → v1 gate path): acyclic + resolved.
+  # hooks, providers and utils: re-baselined in #149 from 0.15. Their whole score is
+  # the acknowledged unresolved_ratio debt now that it is measured (see query).
   - name: "hooks"
     fqn_prefix: "hooks"
     profile: typescript
-    drift_tolerance: 0.15 # measured 0.00
+    drift_tolerance: 0.22 # measured 0.2117
+    hygiene_baseline:
+      unresolved_ratio: 0.84 # measured 0.8351 when the gate came alive (#149)
 
   - name: "store"
     fqn_prefix: "store"
@@ -211,12 +241,16 @@ project_domains:
   - name: "providers"
     fqn_prefix: "providers"
     profile: typescript
-    drift_tolerance: 0.15 # measured 0.00
+    drift_tolerance: 0.17 # measured 0.1641
+    hygiene_baseline:
+      unresolved_ratio: 0.70 # measured 0.6923 when the gate came alive (#149)
 
   - name: "utils"
     fqn_prefix: "utils"
     profile: typescript
-    drift_tolerance: 0.15 # measured 0.00
+    drift_tolerance: 0.20 # measured 0.1952
+    hygiene_baseline:
+      unresolved_ratio: 0.79 # measured 0.7857 when the gate came alive (#149)
 
 # ── Project-level quotient binding (spec §3.4) — OBSERVE-ONLY burn-in ────────
 # Measured quotient IMPORTS census {021D .4, 021U .4, 030T .2}: the domain

{codegraph_brain-0.25.4 → codegraph_brain-0.27.0}/docs/ontology/tolerances.lock

@@ -15,16 +15,16 @@ project_domains:
   resolution: 0.40
   pipeline: 0.25
   storage: 0.20
-  query: 0.20
+  query: 0.23
   guardian: 0.26
   cli: 0.03
   api: 0.03
-  components: 0.20
+  components: 0.24
   layout: 0.50
-  hooks: 0.15
+  hooks: 0.22
   store: 0.15
-  providers: 0.15
-  utils: 0.15
+  providers: 0.17
+  utils: 0.20
 
 project_level:
   cgis-project: 0.15

{codegraph_brain-0.25.4 → 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,