codegraph-engine 2.3.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

codegraph/__init__.py

@@ -1,6 +1,6 @@
 """CodeGraph MCP: local, evidence-backed codebase intelligence."""
 
-__version__ = "2.3.0"
+__version__ = "3.0.1"
 from codegraph.errors import (
     CodeGraphError,
     ErrorCode,

codegraph/__main__.py

@@ -0,0 +1,7 @@
+"""Entrypoint for `python -m codegraph`."""
+from __future__ import annotations
+
+from codegraph.cli import app
+
+if __name__ == "__main__":
+    app()

codegraph/agent_brain.py

@@ -644,6 +644,256 @@ RELATIONSHIP_SEMANTICS_REGISTRY: dict[str, RelationshipSemanticsSpec] = {
         common_tool="get_db_schema / get_context",
         example="`src/config.py` -> `READS_ENV` (`AST_VERIFIED`) -> `env:DATABASE_URL`",
     ),
+    "RENDERS": RelationshipSemanticsSpec(
+        relationship="RENDERS",
+        meaning="React JSX component renders a child component element (`<ChildComponent ... />`).",
+        typical_source="Parent component symbol (`DashboardPage`, `InvoiceTable`)",
+        typical_target="Child component symbol (`InvoiceCard`, `Button`)",
+        proves="Static JSX component composition tree hierarchy.",
+        does_not_prove="Does not prove conditional branch execution at runtime unless inspected.",
+        common_tool="find_callers / find_callees / get_references",
+        example="`Dashboard` -> `RENDERS` (`AST_VERIFIED`) -> `InvoiceTable`",
+    ),
+    "USES_HOOK": RelationshipSemanticsSpec(
+        relationship="USES_HOOK",
+        meaning="React component or custom hook calls a state/lifecycle hook (`useAuth()`, `useInvoices()`).",
+        typical_source="Component or custom hook (`UserProfile`, `useOrderDetails`)",
+        typical_target="Hook function symbol (`useAuth`, `useQuery`)",
+        proves="Component or custom hook lifecycle dependency on target hook.",
+        does_not_prove="Does not prove hook return value shape without inspecting hook definition.",
+        common_tool="find_callers / get_references / trace_path",
+        example="`UserProfile` -> `USES_HOOK` (`FRAMEWORK_VERIFIED`) -> `useAuth`",
+    ),
+    "IMPORTS_STYLE": RelationshipSemanticsSpec(
+        relationship="IMPORTS_STYLE",
+        meaning="Component or module imports a CSS/SCSS stylesheet or CSS module (`import styles from './Button.module.css'`).",
+        typical_source="Component or page file (`Button.tsx`)",
+        typical_target="Stylesheet file (`Button.module.css`, `globals.css`)",
+        proves="Component imports style definitions from target stylesheet.",
+        does_not_prove="Does not prove all style classes in the file are actively applied.",
+        common_tool="find_references / get_file / get_context",
+        example="`Button.tsx` -> `IMPORTS_STYLE` (`AST_VERIFIED`) -> `Button.module.css`",
+    ),
+    "USES_STYLE_CLASS": RelationshipSemanticsSpec(
+        relationship="USES_STYLE_CLASS",
+        meaning="JSX element or component references a CSS class selector (`className={styles.header}` or `className='btn-primary'`).",
+        typical_source="Component or JSX element (`Header.tsx`)",
+        typical_target="CSS class symbol (`.header-title`, `.btn-primary`)",
+        proves="Component applies the named CSS style class.",
+        does_not_prove="Does not prove CSS specificity or cascade overrides.",
+        common_tool="find_references / search_code / get_context",
+        example="`Header.tsx` -> `USES_STYLE_CLASS` (`FRAMEWORK_VERIFIED`) -> `.header-title`",
+    ),
+    "FETCHES_ROUTE": RelationshipSemanticsSpec(
+        relationship="FETCHES_ROUTE",
+        meaning="Frontend component, hook, or API client invokes a backend HTTP route (`fetch('/api/v1/invoices')`, `axios.get(...)`).",
+        typical_source="Frontend component or data hook (`useInvoices`, `createInvoiceForm`)",
+        typical_target="Backend route endpoint (`POST /api/v1/invoices`, `GET /api/v1/users`)",
+        proves="Frontend client-side network request targeting a backend route.",
+        does_not_prove="Does not prove backend server availability at runtime.",
+        common_tool="find_callers / trace_path / list_routes",
+        example="`useInvoices` -> `FETCHES_ROUTE` (`FRAMEWORK_VERIFIED`) -> `GET /api/v1/invoices`",
+    ),
+    "LOADS_SCRIPT": RelationshipSemanticsSpec(
+        relationship="LOADS_SCRIPT",
+        meaning="HTML template or page loads a JavaScript/TypeScript script bundle (`<script src='...'>`).",
+        typical_source="HTML file (`index.html`)",
+        typical_target="Script file (`src/main.tsx`, `bundle.js`)",
+        proves="HTML document includes and executes target script.",
+        does_not_prove="Does not prove script execution order if async/defer are used.",
+        common_tool="find_references / get_file",
+        example="`index.html` -> `LOADS_SCRIPT` (`STATIC_VERIFIED`) -> `src/main.tsx`",
+    ),
+    "LOADS_STYLESHEET": RelationshipSemanticsSpec(
+        relationship="LOADS_STYLESHEET",
+        meaning="HTML template or page loads an external stylesheet (`<link rel='stylesheet' href='...'>`).",
+        typical_source="HTML file (`index.html`)",
+        typical_target="Stylesheet file (`src/index.css`, `theme.css`)",
+        proves="HTML document links target stylesheet for presentation.",
+        does_not_prove="Does not prove runtime CDN stylesheet availability.",
+        common_tool="find_references / get_file",
+        example="`index.html` -> `LOADS_STYLESHEET` (`STATIC_VERIFIED`) -> `src/index.css`",
+    ),
+    "MAPS_TO_COLLECTION": RelationshipSemanticsSpec(
+        relationship="MAPS_TO_COLLECTION",
+        meaning="NoSQL document model (Mongoose model) maps to an underlying MongoDB collection.",
+        typical_source="Mongoose model (`InvoiceModel`)",
+        typical_target="MongoDB collection (`invoices`)",
+        proves="Static mapping between document model and database collection.",
+        does_not_prove="Does not prove database schema strictness unless validation options are inspected.",
+        common_tool="find_db_tables / find_db_models / get_db_table",
+        example="`InvoiceModel` -> `MAPS_TO_COLLECTION` (`FRAMEWORK_VERIFIED`) -> `db.UNKNOWN.UNKNOWN.invoices`",
+    ),
+    "WRITES_COLLECTION": RelationshipSemanticsSpec(
+        relationship="WRITES_COLLECTION",
+        meaning="Function or route writes (insert, update, delete) documents to a MongoDB collection.",
+        typical_source="Caller symbol or API handler (`createInvoice`)",
+        typical_target="MongoDB collection (`invoices`)",
+        proves="Write operation (`Model.create`, `Model.updateOne`, `insertOne`) against target collection.",
+        does_not_prove="Does not prove transaction commit or replica-set write concern acknowledgment.",
+        common_tool="find_db_writers / get_context / trace_path",
+        example="`createInvoice` -> `WRITES_COLLECTION` (`AST_VERIFIED`) -> `db.UNKNOWN.UNKNOWN.invoices`",
+    ),
+    "READS_COLLECTION": RelationshipSemanticsSpec(
+        relationship="READS_COLLECTION",
+        meaning="Function or route reads (find, aggregate, count) documents from a MongoDB collection.",
+        typical_source="Caller symbol or API handler (`listInvoices`)",
+        typical_target="MongoDB collection (`invoices`)",
+        proves="Read query (`Model.find`, `Model.findOne`, `aggregate`) against target collection.",
+        does_not_prove="Does not prove document existence at runtime.",
+        common_tool="find_db_readers / get_context / trace_path",
+        example="`listInvoices` -> `READS_COLLECTION` (`AST_VERIFIED`) -> `db.UNKNOWN.UNKNOWN.invoices`",
+    ),
+    "DISPATCHES_TASK": RelationshipSemanticsSpec(
+        relationship="DISPATCHES_TASK",
+        meaning="Caller function or route dispatches a background task (.delay(), .apply_async(), .send_task()).",
+        typical_source="Caller symbol or API handler (`checkout_order`, `register_user`)",
+        typical_target="Task handler function (`process_order_payment`, `send_welcome_email`)",
+        proves="Background task invocation connects caller to the queued task handler.",
+        does_not_prove="Does not prove queue worker status or job execution timing.",
+        common_tool="trace_path / find_callees / get_context",
+        example="`checkout_order` -> `DISPATCHES_TASK` (`FRAMEWORK_VERIFIED`) -> `process_order_payment`",
+    ),
+    "TRIGGERS_SIGNAL": RelationshipSemanticsSpec(
+        relationship="TRIGGERS_SIGNAL",
+        meaning="Model lifecycle action (save, delete) or signal emission triggers a signal receiver.",
+        typical_source="Model or lifecycle method (`Customer.save`, `signal.send`)",
+        typical_target="Signal receiver function (`on_customer_created`)",
+        proves="Django signal linkage connects the model or trigger site to registered receivers.",
+        does_not_prove="Does not prove transaction commit before receiver execution.",
+        common_tool="trace_path / find_callees / get_context",
+        example="`Customer.save` -> `TRIGGERS_SIGNAL` (`FRAMEWORK_VERIFIED`) -> `on_customer_created`",
+    ),
+    "HANDLES_SIGNAL": RelationshipSemanticsSpec(
+        relationship="HANDLES_SIGNAL",
+        meaning="Signal receiver function handles lifecycle events or domain signals from a sender model.",
+        typical_source="Receiver function (`on_customer_created`)",
+        typical_target="Sender model symbol (`Customer`)",
+        proves="Receiver function is bound to the sender model via @receiver or signal.connect.",
+        does_not_prove="Does not prove receiver handles all signal kwargs.",
+        common_tool="find_callers / get_references / get_context",
+        example="`on_customer_created` -> `HANDLES_SIGNAL` (`FRAMEWORK_VERIFIED`) -> `Customer`",
+    ),
+    "RENDERS_TEMPLATE": RelationshipSemanticsSpec(
+        relationship="RENDERS_TEMPLATE",
+        meaning="View or controller renders an HTML or Jinja template (render_template, TemplateResponse, template_name).",
+        typical_source="View handler symbol (`dashboard_view`)",
+        typical_target="Template file path (`templates/dashboard.html`)",
+        proves="Deterministic linkage between backend view function and frontend HTML template.",
+        does_not_prove="Does not prove all template context variables are provided.",
+        common_tool="list_routes / get_context / find_callees",
+        example="`dashboard_view` -> `RENDERS_TEMPLATE` (`FRAMEWORK_VERIFIED`) -> `templates/dashboard.html`",
+    ),
+    "DISPATCHES_FORWARD": RelationshipSemanticsSpec(
+        relationship="DISPATCHES_FORWARD",
+        meaning="Neural network module invocation (model(inputs), self.submodule(x)) dispatches to nn.Module.forward().",
+        typical_source="Caller function or model forward pass (`predict`, `Classifier.forward`)",
+        typical_target="Submodule or model forward method (`Encoder.forward`, `Linear.forward`)",
+        proves="PyTorch __call__ dispatch to forward method on a concrete or resolved module instance.",
+        does_not_prove="Does not prove runtime execution if forward hooks or dynamic wrappers abort execution.",
+        common_tool="trace_path / find_callees / get_context",
+        example="`predict` -> `DISPATCHES_FORWARD` (`AST_VERIFIED`) -> `Classifier.forward`",
+    ),
+    "TOOL_HANDLER": RelationshipSemanticsSpec(
+        relationship="TOOL_HANDLER",
+        meaning="Function or method is decorated as an agentic AI tool (@tool, @function_tool, @agent).",
+        typical_source="Tool function (`search_web_tool`, `execute_sql`)",
+        typical_target="Agent framework registration decorator (`@tool`)",
+        proves="Function is registered as a callable tool in an agentic workflow.",
+        does_not_prove="Does not prove tool argument schema compatibility with LLM runtime.",
+        common_tool="find_references / get_symbol / get_context",
+        example="`search_web_tool` -> `TOOL_HANDLER` (`FRAMEWORK_VERIFIED`) -> `@tool`",
+    ),
+    "PIPELINE_STEP": RelationshipSemanticsSpec(
+        relationship="PIPELINE_STEP",
+        meaning="Sequential execution link in an AI/ML pipeline or LangChain LCEL chain (prompt | llm | parser).",
+        typical_source="Upstream pipeline component or prompt template (`prompt_template`)",
+        typical_target="Downstream pipeline component or model runner (`chat_model`)",
+        proves="Dataflow pipe composition between execution steps in an AI/ML workflow.",
+        does_not_prove="Does not prove runtime type convergence between pipe boundaries.",
+        common_tool="trace_path / find_callees / get_context",
+        example="`prompt_template` -> `PIPELINE_STEP` (`DATAFLOW_VERIFIED`) -> `chat_model`",
+    ),
+    "REQUIRES_MODULE": RelationshipSemanticsSpec(
+        relationship="REQUIRES_MODULE",
+        meaning="Luau or Roblox module requires another ModuleScript via `require(...)` using Rojo DataModel paths or `script.Parent` traversal.",
+        typical_source="Caller Luau module or function (`ClientController`, `InventoryService`)",
+        typical_target="Target ModuleScript (`Packages.Knit`, `src.shared.Types`)",
+        proves="Deterministic module dependency via Rojo project mapping (`ROJO_VERIFIED`) or bounded relative script path (`AST_VERIFIED`).",
+        does_not_prove="Does not prove runtime execution order when `require` is inside a conditional branch.",
+        common_tool="get_imports / trace_path / get_context",
+        example="`InventoryService` -> `REQUIRES_MODULE` (`ROJO_VERIFIED`) -> `Packages.Knit`",
+    ),
+    "CLIENT_DISPATCHES_REMOTE": RelationshipSemanticsSpec(
+        relationship="CLIENT_DISPATCHES_REMOTE",
+        meaning="Roblox client script or controller dispatches a `RemoteEvent:FireServer(...)` or `RemoteFunction:InvokeServer(...)` call across the client-server boundary.",
+        typical_source="Client controller or LocalScript (`ClientController.RequestInventoryUpdate`)",
+        typical_target="Canonical Roblox Remote node (`ReplicatedStorage.Remotes.Inventory`)",
+        proves="Client-to-server network dispatch targeting the resolved Remote instance (`ROJO_VERIFIED` or `FRAMEWORK_VERIFIED`).",
+        does_not_prove="Never collapsed into generic `CALLS`; does not prove server validation success at runtime.",
+        common_tool="trace_path / find_callees / get_context",
+        example="`ClientController` -> `CLIENT_DISPATCHES_REMOTE` (`ROJO_VERIFIED`) -> `ReplicatedStorage.Remotes.Inventory`",
+    ),
+    "SERVER_HANDLES_REMOTE": RelationshipSemanticsSpec(
+        relationship="SERVER_HANDLES_REMOTE",
+        meaning="Roblox server script or service connects a handler to `RemoteEvent.OnServerEvent:Connect(...)` or assigns `RemoteFunction.OnServerInvoke`.",
+        typical_source="Canonical Roblox Remote node (`ReplicatedStorage.Remotes.Inventory`)",
+        typical_target="Server service or handler method (`InventoryService.KnitInit`, `InventoryService`)",
+        proves="Server-side network handler registration for the canonical Remote channel (`ROJO_VERIFIED` or `FRAMEWORK_VERIFIED`).",
+        does_not_prove="Never collapsed into generic `CALLS`; does not prove payload schema validation.",
+        common_tool="trace_path / find_callers / get_context",
+        example="`ReplicatedStorage.Remotes.Inventory` -> `SERVER_HANDLES_REMOTE` (`ROJO_VERIFIED`) -> `InventoryService`",
+    ),
+    "PROVIDES_SERVICE": RelationshipSemanticsSpec(
+        relationship="PROVIDES_SERVICE",
+        meaning="Knit (`Knit.CreateService`) or Flamework (`@Service`, `@Controller`) declares a named singleton service or controller.",
+        typical_source="Service class or table symbol (`src.server.Services.InventoryService.InventoryService`)",
+        typical_target="Registered service identifier (`InventoryService`, `CombatService`)",
+        proves="Framework service provider registration (`FRAMEWORK_VERIFIED`).",
+        does_not_prove="Does not prove `Knit.Start()` has completed at runtime.",
+        common_tool="trace_path / find_references / get_context",
+        example="`InventoryService` -> `PROVIDES_SERVICE` (`FRAMEWORK_VERIFIED`) -> `InventoryService`",
+    ),
+    "GETS_SERVICE": RelationshipSemanticsSpec(
+        relationship="GETS_SERVICE",
+        meaning="Knit (`Knit.GetService(...)`) or Flamework (`Dependency<T>()`) resolves a framework service or controller dependency.",
+        typical_source="Consumer controller or service method (`RewardService.GrantStarterPack`, `CombatController`)",
+        typical_target="Target service symbol (`src.server.Services.InventoryService.InventoryService`)",
+        proves="Framework dependency resolution linking consumer to service provider (`FRAMEWORK_VERIFIED`).",
+        does_not_prove="Does not prove runtime initialization order.",
+        common_tool="trace_path / find_callees / analyze_impact",
+        example="`RewardService.GrantStarterPack` -> `GETS_SERVICE` (`FRAMEWORK_VERIFIED`) -> `InventoryService`",
+    ),
+    "CONFIGURES_PERSISTENCE": RelationshipSemanticsSpec(
+        relationship="CONFIGURES_PERSISTENCE",
+        meaning="Roblox server service configures a `DataStoreService:GetDataStore(...)` or `ProfileService.GetProfileStore(...)` persistence store.",
+        typical_source="Server service or module (`InventoryService`)",
+        typical_target="Canonical Roblox persistence entity (`persistence.roblox.datastore.<name>`)",
+        proves="Static persistence store binding (`FRAMEWORK_VERIFIED`), kept distinct from SQL tables.",
+        does_not_prove="Does not prove Roblox Studio API Services are enabled at runtime.",
+        common_tool="trace_path / analyze_impact / get_context",
+        example="`InventoryService` -> `CONFIGURES_PERSISTENCE` (`FRAMEWORK_VERIFIED`) -> `persistence.roblox.datastore.PlayerInventory_v1`",
+    ),
+    "READS_PERSISTENCE": RelationshipSemanticsSpec(
+        relationship="READS_PERSISTENCE",
+        meaning="Function or method reads from a Roblox DataStore or ProfileStore (`GetAsync`, `LoadProfileAsync`).",
+        typical_source="Service method (`InventoryService.HandleInventoryRequest`)",
+        typical_target="Canonical Roblox persistence entity (`persistence.roblox.datastore.<name>`)",
+        proves="Static persistence read operation targeting the store (`FRAMEWORK_VERIFIED`).",
+        does_not_prove="Does not prove key existence or throttling budget at runtime.",
+        common_tool="trace_path / analyze_impact / get_context",
+        example="`InventoryService.HandleInventoryRequest` -> `READS_PERSISTENCE` (`FRAMEWORK_VERIFIED`) -> `persistence.roblox.datastore.PlayerInventory_v1`",
+    ),
+    "WRITES_PERSISTENCE": RelationshipSemanticsSpec(
+        relationship="WRITES_PERSISTENCE",
+        meaning="Function or method writes or mutates a Roblox DataStore or ProfileStore (`SetAsync`, `UpdateAsync`, `IncrementAsync`, `RemoveAsync`, `Save`).",
+        typical_source="Service method (`InventoryService.HandleInventoryRequest`)",
+        typical_target="Canonical Roblox persistence entity (`persistence.roblox.datastore.<name>`)",
+        proves="Static persistence mutation targeting the store (`FRAMEWORK_VERIFIED`).",
+        does_not_prove="Does not prove runtime `pcall` success or DataStore queue limits.",
+        common_tool="trace_path / analyze_impact / get_context",
+        example="`InventoryService.HandleInventoryRequest` -> `WRITES_PERSISTENCE` (`FRAMEWORK_VERIFIED`) -> `persistence.roblox.datastore.PlayerInventory_v1`",
+    ),
 }
 
 
@@ -1248,7 +1498,7 @@ CodeGraph enforces nine canonical `evidence_class` values defined in `ALLOWED_EV
 
 ## 5. Relationship Model
 
-CodeGraph enforces the 56 canonical relationship types in `ALLOWED_RELATIONSHIP_EVIDENCE_MATRIX`. It **never** collapses framework routing, database operations, registry registration, or dependency injection into generic `CALLS` or `DEPENDS_ON`.
+CodeGraph enforces the {len(ALLOWED_RELATIONSHIP_EVIDENCE_MATRIX)} canonical relationship types in `ALLOWED_RELATIONSHIP_EVIDENCE_MATRIX`. It **never** collapses framework routing, database operations, registry registration, or dependency injection into generic `CALLS` or `DEPENDS_ON`.
 
 {relationships_block}
 
@@ -1547,7 +1797,7 @@ Repository -> Candidate Facts -> Task-Aware Filtering (RetrievalPolicy)
 
 - **Hard Invariants & Output Boundaries of `get_context`**:
   - Primary input is `query` (`task` is also supported as a string or `TaskSpec` dict alias).
-  - Enforces strict output boundaries BEFORE MCP serialization: `max_tokens` (default `4000`, hard cap `20000`), `max_files` (default `15`, hard cap `30`), and `max_lines` (default `500`, hard cap `1500`).
+  - Enforces strict output boundaries BEFORE MCP serialization: `max_tokens` (default `4000`, hard cap `20000`), `max_files` (default `25`, hard cap `40`), and `max_lines` (default `500`, hard cap `1500`).
   - Returns explicit budget metadata: `selected_tokens`, `candidate_tokens`, `selected_files`, `selected_lines`, `coverage_score`, and `truncated`.
   - Preserves `unknowns` and `ambiguities` explicitly—never drops uncertainty to save tokens.
   - Compresses duplicate `(source, target, relationship)` edges into a single record with `occurrence_count` and `supporting_locations`.
@@ -1768,6 +2018,7 @@ def render_tool_capabilities_summary() -> str:
 | **`STATIC_VERIFIED`** | Proven by static SQL DDL/DML or migration parsing | Rely on table/column/query/migration relationship as verified static fact. |
 | **`FRAMEWORK_VERIFIED`** | Proven by deterministic framework rules | Rely on route/ORM/DI/task/event relationship as verified framework fact. |
 | **`DATAFLOW_VERIFIED`** | Proven by conservative local/container binding | Rely on resolved target as verified dataflow fact. |
+| **`ROJO_VERIFIED`** | Proven by deterministic Rojo `default.project.json` DataModel mapping | Rely on virtual-to-physical Luau module resolution as verified fact. |
 | **`RUNTIME_OBSERVED`** | Observed in an ingested runtime trace (`observation_count >= 1`) | Treat as verified runtime execution fact; never promote to static `AST_VERIFIED` proof. |
 | **`RUNTIME_UNOBSERVED`** | Not observed in the ingested runtime trace sample | Never claim the static path is dead code or impossible at runtime. |
 | **`POSSIBLE`** | Plausible candidate, not statically guaranteed | Treat as lead; verify with targeted `get_file` / `read_file` before claiming as fact. |