cg-code-graph 0.10.1__py3-none-any.whl

codegraph/core/model.py

@@ -0,0 +1,174 @@
+"""Graph data model: node/edge kinds, confidence levels, stable ids."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Confidence of an edge, strongest first.
+EXACT = "exact"          # syntactically certain (static call, `new X`, $this->m(), literal key)
+RESOLVED = "resolved"    # needed type/name resolution (typed property/param, inferred var type, model->table)
+HEURISTIC = "heuristic"  # best effort (unique-method-name fallback, unique column-name literal)
+CONFIDENCE_RANK = {EXACT: 3, RESOLVED: 2, HEURISTIC: 1}
+
+# Edge kinds. propagates=True means "src depends on dst": reverse traversal from a
+# target follows these edges to find everything that depends on it.
+EDGE_KINDS: dict[str, tuple[bool, str]] = {
+    "CALLS": (True, "function/method calls function/method"),
+    "IMPLEMENTED_BY": (True, "interface/abstract method may dispatch to implementation"),
+    "OVERRIDDEN_BY": (True, "parent method may dispatch to child override"),
+    "BOUND_TO": (True, "container binding abstract -> concrete"),
+    "ROUTES_TO": (True, "HTTP route -> controller action"),
+    "USES_MIDDLEWARE": (True, "route -> middleware handle()"),
+    "HANDLED_BY": (True, "artisan command name -> handler method"),
+    "SCHEDULES": (True, "scheduler entry -> command/job"),
+    "DISPATCHES": (True, "code dispatches job/event"),
+    "LISTENED_BY": (True, "event -> listener handler"),
+    "READS_COLUMN": (True, "code reads column"),
+    "WRITES_COLUMN": (True, "code writes column"),
+    "MENTIONS_COLUMN": (True, "string literal equal to a distinctive column name"),
+    "READS_TABLE": (True, "code reads table"),
+    "WRITES_TABLE": (True, "code writes table"),
+    "USES_CONNECTION": (True, "code/model uses DB connection"),
+    "REGISTERS_CONNECTION": (True, "code registers a (dynamic) DB connection"),
+    "READS_CONFIG": (True, "code reads config key"),
+    "WRITES_CONFIG": (True, "code sets config key at runtime"),
+    "READS_ENV": (True, "code/config reads env key"),
+    "REFERS_TO": (True, "config value names a connection/other entity"),
+    "CONFIGURED_BY": (True, "connection or external system defined by a config / env key"),
+    "CONFIG_CONTAINS": (True, "config parent key contains child key"),
+    "MAPS_TO_TABLE": (False, "model class -> table"),
+    "HAS_RELATION": (False, "model -> related model (hasMany, belongsTo, ...)"),
+    "CONTAINS": (False, "class -> member, table -> column"),
+    "EXTENDS": (False, "class extends class"),
+    "IMPLEMENTS": (False, "class implements interface"),
+    "USES_TRAIT": (False, "class uses trait"),
+    "INSTANTIATES": (False, "code instantiates class (constructor call is a separate CALLS edge)"),
+    "INJECTS": (False, "constructor-injected dependency type"),
+    "REFERENCES": (False, "X::class reference"),
+    "OBSERVED_BY": (False, "model observer registration"),
+    "DEFINES": (False, "file/migration defines table/column"),
+    "BINDS": (False, "service provider registers binding"),
+    # TypeScript / Vue / Nuxt
+    "IMPORTS": (False, "module/component imports module/component"),
+    "RENDERS": (True, "component template renders child component"),
+    "USES_COMPOSABLE": (True, "code calls a composable (useX())"),
+    "USES_STORE": (True, "code calls a Pinia store (useXStore())"),
+    "HTTP_CALLS": (True, "client code calls an HTTP endpoint (method + path template)"),
+    "MATCHES_ROUTE": (True, "client endpoint matched to a backend route (cross-repo link)"),
+    "USES_LAYOUT": (False, "page uses layout"),
+    "USES_I18N": (False, "code/template uses i18n key"),
+    "REFERENCES_TYPE": (False, "code references a type/interface"),
+    # value facts
+    "READS_SETTING": (True, "code reads a JSON settings key (getSetting('a.b', default))"),
+    "WRITES_SETTING": (True, "code writes a JSON settings key (setSetting)"),
+    "READS_INPUT": (True, "code reads an HTTP request key ($request->input('k'), $validated['k'], $filters['k'] via arg flow)"),
+    "VALIDATES": (True, "FormRequest::rules() declares a request key"),
+    "VALIDATED_BY": (True, "controller action is validated by a FormRequest (rules())"),
+    "HAS_RESOLUTION": (True, "code resolves a value through a fallback chain (resolution node)"),
+    "FALLS_BACK_TO": (True, "resolution chain step -> source node (setting, request key, column, config, env); attrs.order"),
+    # native code (Rust, C, C++)
+    "USES_TYPE": (True, "code/type refers to a type (struct, enum, union, trait, class, typedef)"),
+    "ACCESSES_FIELD": (True, "code reads/writes a struct/class field or enum variant"),
+    "READS_PROP": (True, "code reads a stored property (field node: Swift `var x`, `@State`, `@Published`)"),
+    "WRITES_PROP": (True, "code writes a stored property (assignment, compound assignment)"),
+    "USES_VALUE": (True, "code refers to an enum case, a constant, a static/global variable or an object-like macro"),
+    "REFERENCES_FN": (True, "code/data takes a function as a value (callback, dispatch table, handler registration)"),
+    "USES_UNSAFE": (True, "code contains an unsafe block or is an unsafe fn (sink node unsafe:<crate>)"),
+    "GATED_BY": (True, "code compiled only under a condition: Cargo feature, cfg predicate or preprocessor macro"),
+    "INCLUDES": (True, "source/header file #includes a header"),
+    # Python / Django
+    "USES_SCHEMA": (False, "handler/view uses a wire schema (ninja/pydantic Schema, DRF serializer) for request/response; attrs.role"),
+    # Dart / Flutter
+    "EMITS_STATE": (False, "bloc/cubit code emits a state class"),
+    "HANDLES_STATE": (False, "UI code checks for a state class (is / switch pattern / BlocListener)"),
+    "NAVIGATES_TO": (False, "UI code navigates to a page/route (Navigator.push, context.go, named route)"),
+    "PARSES_JSON": (False, "code parses an HTTP response into a model (X.fromJson) or serialises a request body (toJson)"),
+    # realtime broadcasting (Laravel channels, Echo / pusher-js subscriptions)
+    "AUTHORIZES_CHANNEL": (True, "broadcasting auth route -> channel whose authorization callback it runs"),
+    "BROADCASTS_ON": (False, "broadcast event -> channel it publishes on (broadcastOn(); attrs.name = evaluated channel name)"),
+    "SUBSCRIBES_CHANNEL": (True, "client code subscribes to a channel (Echo.private / channel / join, pusher.subscribe, useEcho)"),
+    "MATCHES_CHANNEL": (True, "client channel subscription matched to a backend channel pattern (cross-repo link)"),
+    "LISTENS_FOR": (False, "client channel subscription listens for a backend broadcast event (.listen('Name'))"),
+    # protocol endpoints (#31 model, codegraph/protocols/; web / native bridges in codegraph/bridges.py):
+    # code -> endpoint:<protocol>:<name> -> handler
+    "SENDS_TO": (True, "code sends to a protocol endpoint (publish, emit, request, invoke, enqueue; bridge call: Capacitor "
+                       "plugin / React Native module method, Flutter MethodChannel.invokeMethod); attrs.role, via"),
+    "RECEIVED_BY": (True, "protocol endpoint -> the handler receiving it (subscriber, event handler; native @PluginMethod / "
+                          "@ReactMethod / channel handler); attrs.platform"),
+    "MATCHES_ENDPOINT": (True, "send-side endpoint -> receive-side endpoint of the same protocol whose name matches by the "
+                               "protocol's rules (wildcards, {param} templates); attrs.pattern, segments"),
+    # external systems (#40, codegraph/external.py): external:<protocol>:<target>
+    "CONNECTS_TO": (True, "code or a logical connection -> external system it connects to (database, cache, broker, mail relay, "
+                          "directory, file-transfer host, object store); attrs.op, via"),
+    "CREDENTIAL_FROM": (False, "external system -> env / config node holding its password / token (never the value); attrs.kind"),
+    # AI harnesses (#66): agents and the tools they expose (tools themselves are endpoint:llm_tool / mcp_tool nodes)
+    "OFFERS_TOOL": (True, "agent -> a tool endpoint it gives the model (Agents SDK Agent(tools=), create_react_agent)"),
+    "HANDS_OFF_TO": (True, "agent -> agent it can hand the conversation to (Agents SDK handoffs=[...])"),
+    # generated / copied files (codegraph/core/generated.py), only with --include-generated
+    "COPY_OF": (False, "copied file (Capacitor / Cordova web assets in a native project) -> the source file it is copied from"),
+    # test code (tests/, *.spec.ts, ...). Never propagating: tests do not change blast radius, caller counts or entry
+    # tagging; the `tests` query walks these on purpose
+    "TEST_CALLS": (False, "test code calls / dispatches to code (attrs.orig = the original edge kind)"),
+    "TEST_USES": (False, "test code touches a table, config key, class... (attrs.orig = the original edge kind)"),
+    "TEST_HTTP": (False, "test sends an HTTP request to a route ($this->getJson('/x'), Pest get(), Playwright request)"),
+    "TEST_VISITS": (False, "browser test opens a frontend page (Playwright / Cypress page.goto('/x'))"),
+}
+TEST_EDGE_KINDS = ("TEST_CALLS", "TEST_USES", "TEST_HTTP", "TEST_VISITS")
+PROPAGATING = sorted(k for k, (p, _) in EDGE_KINDS.items() if p)
+
+ENTRY_KINDS = ("http_route", "websocket", "artisan_command", "management_command", "scheduled", "queue_job", "listener",
+               "admin_panel", "observer", "ui_page", "ui_global",
+               "main", "ffi_export", "public_api", "test", "bench", "example", "build_script")
+UI_ENTRY_KINDS = ("ui_page", "ui_global")
+# websocket = Channels consumer routes; management_command = Django `manage.py <name>` (operator, like artisan)
+RUNTIME_ENTRY_KINDS = ("http_route", "websocket", "scheduled", "queue_job", "listener", "main", "ffi_export")
+OPERATOR_ENTRY_KINDS = ("artisan_command", "management_command", "admin_panel")
+# native code: library API surface (pub items of a lib crate, exported C/C++ API) and dev/build-time entries
+LIBRARY_ENTRY_KINDS = ("public_api",)
+DEV_ENTRY_KINDS = ("test", "bench", "example", "build_script")
+# TS server frameworks: microservice / WebSocket message handlers run at runtime; CLI commands (nest-commander) are
+# operator-only, like artisan commands.
+ENTRY_KINDS += ("message_handler", "cli_command")
+RUNTIME_ENTRY_KINDS += ("message_handler",)
+# realtime: a channel authorization callback (Laravel Broadcast::channel) runs on every private/presence subscription
+ENTRY_KINDS += ("channel_auth",)
+RUNTIME_ENTRY_KINDS += ("channel_auth",)
+OPERATOR_ENTRY_KINDS += ("cli_command",)
+# AI harnesses: a tool endpoint the model (agent runner) or an MCP client calls by name
+ENTRY_KINDS += ("llm_tool",)
+RUNTIME_ENTRY_KINDS += ("llm_tool",)
+
+
+@dataclass
+class Node:
+    id: str
+    kind: str
+    name: str
+    fqn: str | None = None
+    file: str | None = None
+    line: int | None = None
+    end_line: int | None = None
+    module: str | None = None
+    doc: str | None = None
+    lang: str | None = None
+    attrs: dict[str, Any] = field(default_factory=dict)
+    entry_kind: str | None = None  # set when the node itself is an entry point
+
+
+@dataclass
+class Edge:
+    src: str
+    dst: str
+    kind: str
+    file: str | None = None
+    line: int | None = None
+    confidence: str = EXACT
+    attrs: dict[str, Any] = field(default_factory=dict)
+    # gate scenario under which this reference is dead (e.g. "new_inventory"), None = live.
+    # Set deterministically by the guard evaluator (plugins/php/gating.py); evidence in attrs["guard"].
+    gate: str | None = None
+
+
+def node_id(kind: str, key: str) -> str:
+    """Stable id = kind + ':' + canonical key (FQN, table.column, route signature...)."""
+    return f"{kind}:{key}"

codegraph/core/paths.py

@@ -0,0 +1,175 @@
+"""Shared skip rules for every directory walk: the preset skip lists plus the project's `.cg.yaml`.
+
+    exclude:            ["legacy/**", "*.generated.ts", "/tools"]   paths never indexed (gitignore-style globs)
+    skip_dirs: {add: [fixtures_big], keep: [static]}               directory names skipped / not skipped anywhere
+    include:   [src/generated, node_modules/@acme/sdk]             directories indexed although a built-in skip
+                                                                   (a directory name, generated files) leaves them out
+
+`rules(project, preset, *keys)` gives the PathRules of one walk; every language plugin, the extractors' configs and
+the coverage scan use it, so one config entry applies to the whole index."""
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+from .. import presets
+
+
+def glob_regex(pattern: str, below: bool = True) -> str:
+    """gitignore-style glob -> regex over repo-relative POSIX paths (Python and JavaScript compatible).
+    `*` and `?` stay inside one path segment, `**` spans segments, a leading `/` anchors at the root, a pattern
+    without `/` matches at any depth, and a match on a directory covers everything below it (below=False: only the
+    path itself matches, as in .gitattributes)."""
+    p = pattern.strip().replace("\\", "/")
+    anchored = p.startswith("/") or "/" in p.rstrip("/")
+    p = p.strip("/")
+    out, i = [], 0
+    while i < len(p):
+        c = p[i]
+        if p.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+        elif p.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif c == "*":
+            out.append("[^/]*")
+            i += 1
+        elif c == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(c) if c not in "/-_" else c)
+            i += 1
+    return ("^" if anchored else "^(?:.*/)?") + "".join(out) + ("(?:/.*)?$" if below else "$")
+
+
+def names_regex(names: Iterable[str]) -> str | None:
+    """Directory names anywhere in a relative path, as one regex (for the TS extractor's skip config)."""
+    names = sorted(set(names))
+    return r"(^|/)(" + "|".join(re.escape(n) for n in names) + r")(/|$)" if names else None
+
+
+class PathRules:
+    """skip(rel_dir, name) for directories, excluded(rel_path) for files; rel paths are POSIX, relative to the root.
+    `generated`: the project's generated / copied / vendored file classifier (codegraph/core/generated.py); its files
+    are excluded too unless the index includes them (`--include-generated`)."""
+
+    def __init__(self, names: Iterable[str] = (), exclude: Iterable[str] = (), paths: Iterable[str] = (), generated=None,
+                 include: Iterable[str] = (), keep: Iterable[str] = ()):
+        self.names = frozenset(names)
+        self.include = tuple(sorted({p.strip("/") for p in include if p.strip("/")}))
+        self.keep = frozenset(keep)        # names kept by .cg.yaml skip_dirs.keep (also hidden directories)
+        self._forced: dict[str, bool] = {}
+        self.exclude = tuple(exclude)
+        self.paths = frozenset(p.strip("/") for p in paths)     # root-relative directories (PHP vendor/, storage/ ...)
+        self._rx = re.compile("|".join(f"(?:{glob_regex(g)})" for g in self.exclude)) if self.exclude else None
+        self.generated = generated if generated is not None and not generated.include else None
+
+    def included(self, rel: str) -> bool:
+        """`rel` is an `include` directory or inside one."""
+        rel = rel.rstrip("/")
+        return any(rel == i or rel.startswith(i + "/") for i in self.include)
+
+    def on_include_path(self, rel: str) -> bool:
+        """`rel` is an `include` directory, inside one, or a directory on the way to one."""
+        rel = rel.rstrip("/")
+        return self.included(rel) or any(i.startswith(rel + "/") for i in self.include)
+
+    def excluded(self, rel: str, generated: bool = True) -> bool:
+        """`rel` is never indexed: a .cg.yaml exclude glob, or (generated=True) a generated / copied / vendored file
+        outside the `include` directories."""
+        if self._rx and self._rx.match(rel):
+            return True
+        if self.include and self.included(rel):
+            return False
+        return bool(generated and self.generated is not None and not rel.endswith("/") and self.generated.excludes(rel))
+
+    def _skip_own(self, rel_dir: str, name: str, dot: bool = False) -> bool:
+        if name in self.names or (dot and name.startswith(".") and name not in self.keep):
+            return True
+        rel = f"{rel_dir}/{name}" if rel_dir else name
+        return rel in self.paths or self.excluded(rel + "/") or (self.generated is not None and self.generated.dir_excluded(rel))
+
+    def _forced_dir(self, rel_dir: str, dot: bool) -> bool:
+        """`rel_dir` (or a directory above it) is skipped by itself and only walked to reach an `include` directory."""
+        if not rel_dir or self.included(rel_dir):
+            return False
+        k = f"{int(dot)}{rel_dir}"
+        if k not in self._forced:
+            parent, _, name = rel_dir.rpartition("/")
+            self._forced[k] = self._skip_own(parent, name, dot) or self._forced_dir(parent, dot)
+        return self._forced[k]
+
+    def skip(self, rel_dir: str, name: str, dot: bool = False) -> bool:
+        if not self.include:
+            return self._skip_own(rel_dir, name, dot)
+        rel = f"{rel_dir}/{name}" if rel_dir else name
+        if self._rx and self._rx.match(rel + "/"):
+            return True
+        if self.on_include_path(rel):
+            return False
+        return self._forced_dir(rel_dir, dot) or self._skip_own(rel_dir, name, dot)
+
+    def prune(self, rel_dir: str, dns: list[str], dot: bool = False) -> list[str]:
+        """Directory names of one os.walk step to descend into (sorted); dot=True also drops hidden directories
+        (except names in skip_dirs.keep)."""
+        return sorted(d for d in dns if not self.skip(rel_dir, d, dot))
+
+    def extractor_cfg(self, extra: Iterable[str] = ()) -> dict:
+        """The skip rules for an extractor that walks on its own (TS, Dart): directory names (`extra`: more names of
+        that walk, minus skip_dirs.keep), the names kept (hidden directories included) and the include paths."""
+        return {"skip_names": sorted(self.names | (set(extra) - self.keep)), "keep_names": sorted(self.keep),
+                "include": list(self.include)}
+
+    def user_exclude_regex(self) -> str | None:
+        """The .cg.yaml exclude globs as one JavaScript-compatible regex (they apply inside `include` too)."""
+        return "|".join(f"(?:{glob_regex(g)})" for g in self.exclude) or None
+
+    def generated_regex(self) -> str | None:
+        """The directories the generated-file classifier excludes as a whole, as one regex."""
+        return "|".join(self.generated.dir_regexes()) if self.generated is not None else None
+
+    def exclude_regex(self) -> str | None:
+        """The exclude globs (and the directories the generated-file classifier excludes as a whole) as one
+        JavaScript-compatible regex (None without either)."""
+        parts = [f"(?:{glob_regex(g)})" for g in self.exclude]
+        if self.generated is not None:
+            parts += self.generated.dir_regexes()
+        return "|".join(parts) or None
+
+    def excluded_files(self, exts: Iterable[str]) -> list[str]:
+        """Classified generated / copied / vendored files with one of `exts` that the scan found (for an extractor
+        that walks on its own)."""
+        if self.generated is None:
+            return []
+        exts = tuple(exts)
+        build = self.generated.build_dirs
+        # declaration files and framework build directories (Nuxt's .nuxt/) stay readable: they are resolution input
+        return sorted(f for f in self.generated.files if f.lower().endswith(exts) and not f.endswith(".d.ts")
+                      and not any(p in build for p in f.split("/")[:-1]) and not (self.include and self.included(f)))
+
+
+def project_settings(project) -> dict:
+    cfg = (getattr(project, "options", None) or {}).get("config") or {}
+    sd = cfg.get("skip_dirs") or {}
+    return {"exclude": list(cfg.get("exclude") or []), "add": list(sd.get("add") or []), "keep": list(sd.get("keep") or []),
+            "include": list(cfg.get("include") or [])}
+
+
+def rules(project, preset: str = "common", *keys: str, base: Iterable[str] | None = None, generated: bool = True) -> PathRules:
+    """PathRules of one walk: preset skip dirs (common.skip_dirs + `keys` of `preset`, or `base`) adjusted by the
+    project's .cg.yaml (skip_dirs.add / keep, exclude), plus the project's generated-file classifier (generated=False:
+    without it, for the scan that runs the classifier)."""
+    s = project_settings(project) if project is not None else {"exclude": [], "add": [], "keep": [], "include": []}
+    names = set(base if base is not None else presets.skip_dirs(preset, *keys))
+    names = (names | set(s["add"])) - set(s["keep"])
+    paths = [p for p in (presets.values(preset, "skip_paths", default=[]) or []) if p not in s["keep"]] if base is None else []
+    gen = (getattr(project, "options", None) or {}).get("generated") if generated and project is not None else None
+    return PathRules(names, s["exclude"], paths, generated=gen, include=s["include"], keep=s["keep"])
+
+
+def rel_dir(root: str, dp: str) -> str:
+    import os
+    r = os.path.relpath(dp, root)
+    return "" if r == "." else r.replace(os.sep, "/")

codegraph/core/plugin.py

@@ -0,0 +1,160 @@
+"""Plugin interfaces.
+
+LanguagePlugin   detect(project) -> bool; index(project, builder, frameworks) adds nodes/edges.
+FrameworkPlugin  sits on top of one language plugin (e.g. Laravel on PHP). It gets the
+                 language plugin's analysis context (symbol tables + resolution hooks)
+                 and contributes framework nodes/edges (routes, tables, commands...).
+ScipPlugin       a LanguagePlugin backed by any SCIP-producing indexer (scip-php,
+                 scip-typescript, scip-clang, rust-analyzer scip, scip-go...). Imports
+                 the SCIP index into the same graph (see plugins/scip/importer.py).
+"""
+from __future__ import annotations
+
+import gc
+import json
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .model import Edge, Node, node_id
+
+
+@dataclass
+class Project:
+    root: Path
+    name: str
+    # filled by detection: {"languages": {...}, "frameworks": {...}}
+    detected: dict[str, Any] = field(default_factory=dict)
+    # user options, e.g. {"gates": [scenario, ...]} loaded from config/<project>.gates.json
+    options: dict[str, Any] = field(default_factory=dict)
+
+    def exists(self, rel: str) -> bool:
+        return (self.root / rel).exists()
+
+    def read_json(self, rel: str) -> dict | None:
+        p = self.root / rel
+        if not p.exists():
+            return None
+        try:
+            return json.loads(p.read_text())
+        except Exception:
+            return None
+
+
+class GraphBuilder:
+    """In-memory accumulator; de-duplicates nodes by id and edges by (src,dst,kind,line)."""
+
+    def __init__(self):
+        self.nodes: dict[str, Node] = {}
+        self.edges: dict[tuple, Edge] = {}
+        # set by a language plugin while emitting edges for a reference that is dead under a gate
+        # scenario: {"gate": name, "guard": "file:line", "guard_call": "..."}
+        self.current_gate: dict | None = None
+        # platform conditions recorded by the language plugins (codegraph/platforms.py mark()) and Dart conditional
+        # imports / exports ({file, line, default, configs: [(name, value, file)]}); applied after all plugins ran
+        self.platform_marks: list[dict] = []
+        self.platform_imports: list[dict] = []
+        # Pigeon API definitions found by the Dart plugin ({Api: {kind: host | flutter, methods, file}}): bridges.py
+        # links their native implementations / native callers
+        self.pigeon_apis: dict = {}
+
+    def add_node(self, kind: str, key: str, name: str | None = None, **kw) -> str:
+        nid = node_id(kind, key)
+        n = self.nodes.get(nid)
+        if n is None:
+            self.nodes[nid] = Node(id=nid, kind=kind, name=name or key, **kw)
+        else:
+            for k, v in kw.items():  # fill blanks, merge attrs
+                if k == "attrs" and v:
+                    n.attrs.update(v)
+                elif v is not None and getattr(n, k, None) in (None, ""):
+                    setattr(n, k, v)
+        return nid
+
+    def has(self, nid: str) -> bool:
+        return nid in self.nodes
+
+    def add_edge(self, src: str, dst: str, kind: str, file=None, line=None, confidence="exact", **attrs) -> None:
+        if src == dst and kind == "CALLS":
+            return
+        g = self.current_gate
+        if g and g.get("src") != src:
+            g = None  # only references made by the gated function itself carry the gate
+        key = (src, dst, kind, file, line, g["gate"] if g else None)
+        if key in self.edges:
+            return
+        if g:
+            attrs = {**attrs, "guard": g["guard"], "guard_expr": g.get("expr")}
+        self.edges[key] = Edge(src=src, dst=dst, kind=kind, file=file, line=line, confidence=confidence, attrs=attrs,
+                               gate=g["gate"] if g else None)
+
+
+    def move_edges(self, moves: dict[str, list[tuple[int, int, str]]]) -> int:
+        """Re-attribute edges to a finer-grained source: moves = {src: [(lo, hi, new_src), ...]}; an edge from src
+        whose line lies in [lo, hi] now starts at new_src (the innermost range wins). Used for closures that are
+        their own graph nodes (channel callbacks, Pest tests) while the PHP plugin emits their facts from the file."""
+        n = 0
+        for key, e in list(self.edges.items()):
+            rs = moves.get(e.src)
+            if not rs or e.line is None:
+                continue
+            hit = [r for r in rs if r[0] <= e.line <= r[1]]
+            if not hit:
+                continue
+            new_src = min(hit, key=lambda r: r[1] - r[0])[2]
+            del self.edges[key]
+            nk = (new_src,) + key[1:]
+            if nk not in self.edges and not (new_src == e.dst and e.kind == "CALLS"):
+                e.src = new_src
+                self.edges[nk] = e
+            n += 1
+        return n
+
+    def retype_edge(self, key: tuple, kind: str, **attrs) -> None:
+        e = self.edges.pop(key)
+        e.kind = kind
+        e.attrs = {**e.attrs, **attrs}
+        nk = (key[0], key[1], kind) + key[3:]
+        if nk not in self.edges:
+            self.edges[nk] = e
+
+
+@contextmanager
+def gc_paused():
+    """Pause the cyclic garbage collector for a pass over the whole graph that allocates many small, acyclic objects
+    (sets, dicts, deques): on a large graph the collections that allocation triggers cost far more than the pass."""
+    was = gc.isenabled()
+    gc.disable()
+    try:
+        yield
+    finally:
+        if was:
+            gc.enable()
+
+
+class LanguagePlugin(ABC):
+    name: str = "?"
+
+    @abstractmethod
+    def detect(self, project: Project) -> bool: ...
+
+    @abstractmethod
+    def index(self, project: Project, builder: GraphBuilder, frameworks: list["FrameworkPlugin"]) -> dict:
+        """Add nodes/edges; return stats."""
+
+
+class FrameworkPlugin(ABC):
+    name: str = "?"
+    language: str = "?"
+
+    @abstractmethod
+    def detect(self, project: Project) -> bool: ...
+
+    def register_hooks(self, lang_ctx: Any) -> None:
+        """Called before the language plugin resolves references (type rules, fact handlers)."""
+
+    @abstractmethod
+    def contribute(self, project: Project, builder: GraphBuilder, lang_ctx: Any) -> dict:
+        """Called after language indexing; add framework nodes/edges; return stats."""

codegraph/core/store.py

@@ -0,0 +1,80 @@
+"""SQLite graph store. One DB per project. Traversals use recursive CTEs."""
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Iterable
+
+from .model import EDGE_KINDS, Edge, Node, CONFIDENCE_RANK
+
+SCHEMA = """
+PRAGMA journal_mode=WAL;
+CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT);
+CREATE TABLE IF NOT EXISTS nodes(
+  id TEXT PRIMARY KEY, kind TEXT NOT NULL, name TEXT NOT NULL, fqn TEXT,
+  file TEXT, line INTEGER, end_line INTEGER, module TEXT, doc TEXT, lang TEXT,
+  entry_kind TEXT, attrs TEXT);
+CREATE TABLE IF NOT EXISTS edges(
+  id INTEGER PRIMARY KEY, src TEXT NOT NULL, dst TEXT NOT NULL, kind TEXT NOT NULL,
+  file TEXT, line INTEGER, confidence TEXT NOT NULL, conf_rank INTEGER NOT NULL, attrs TEXT, gate TEXT);
+CREATE TABLE IF NOT EXISTS edge_kinds(kind TEXT PRIMARY KEY, propagates INTEGER, description TEXT);
+-- which entry-point kinds reach a node (forward closure from entry points)
+CREATE TABLE IF NOT EXISTS node_entry(node_id TEXT, entry_kind TEXT, entry_count INTEGER, sample_entry TEXT,
+  PRIMARY KEY(node_id, entry_kind));
+-- same closure, but only over edges that are live under a gate scenario (gate column NULL or != scenario)
+CREATE TABLE IF NOT EXISTS node_entry_live(scenario TEXT, node_id TEXT, entry_kind TEXT, entry_count INTEGER, sample_entry TEXT,
+  PRIMARY KEY(scenario, node_id, entry_kind));
+-- guard predicates found by the evaluator: method -> constant value under a scenario
+CREATE TABLE IF NOT EXISTS gate_predicates(scenario TEXT, method TEXT, value TEXT, how TEXT, PRIMARY KEY(scenario, method));
+CREATE INDEX IF NOT EXISTS ix_edges_src ON edges(src, kind);
+CREATE INDEX IF NOT EXISTS ix_edges_dst ON edges(dst, kind);
+CREATE INDEX IF NOT EXISTS ix_nodes_kind ON nodes(kind);
+CREATE INDEX IF NOT EXISTS ix_nodes_fqn ON nodes(fqn);
+"""
+
+
+class GraphStore:
+    def __init__(self, path: str | Path):
+        self.path = str(path)
+        self.db = sqlite3.connect(self.path)
+        self.db.row_factory = sqlite3.Row
+
+    @classmethod
+    def create(cls, path: str | Path) -> "GraphStore":
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        for suffix in ("", "-wal", "-shm"):
+            q = Path(str(p) + suffix)
+            if q.exists():
+                q.unlink()
+        s = cls(p)
+        s.db.executescript(SCHEMA)
+        s.db.executemany("INSERT INTO edge_kinds VALUES (?,?,?)",
+                         [(k, int(v[0]), v[1]) for k, v in EDGE_KINDS.items()])
+        return s
+
+    def write(self, nodes: Iterable[Node], edges: Iterable[Edge]) -> None:
+        self.db.executemany(
+            "INSERT OR REPLACE INTO nodes VALUES (?,?,?,?,?,?,?,?,?,?,?,?)",
+            [(n.id, n.kind, n.name, n.fqn, n.file, n.line, n.end_line, n.module, n.doc, n.lang,
+              n.entry_kind, json.dumps(n.attrs, default=str) if n.attrs else None) for n in nodes])
+        self.db.executemany(
+            "INSERT INTO edges(src,dst,kind,file,line,confidence,conf_rank,attrs,gate) VALUES (?,?,?,?,?,?,?,?,?)",
+            [(e.src, e.dst, e.kind, e.file, e.line, e.confidence, CONFIDENCE_RANK[e.confidence],
+              json.dumps(e.attrs, default=str) if e.attrs else None, e.gate) for e in edges])
+        self.db.commit()
+
+    def set_meta(self, **kv) -> None:
+        self.db.executemany("INSERT OR REPLACE INTO meta VALUES (?,?)",
+                            [(k, json.dumps(v, default=str)) for k, v in kv.items()])
+        self.db.commit()
+
+    def meta(self) -> dict:
+        return {r["key"]: json.loads(r["value"]) for r in self.db.execute("SELECT * FROM meta")}
+
+    def node(self, nid: str):
+        return self.db.execute("SELECT * FROM nodes WHERE id=?", (nid,)).fetchone()
+
+    def q(self, sql: str, params=()):
+        return self.db.execute(sql, params).fetchall()