codmap 0.0.3__py3-none-any.whl

codemap/incremental.py

@@ -0,0 +1,195 @@
+"""Incremental graph rebuild — recompute only what changed (R1-C9).
+
+A full deep extract of bquant is ~97s, and **~93s of that is the jedi type-inference
+tier** (the two passes ``add_behavior(deep=True)`` and ``add_attrflow(deep=True)``);
+everything else — griffe load, structural nodes/edges, dispatch, family links,
+string-key dataflow — is ~4s together. So the incremental win is entirely in *not
+re-running jedi on modules that didn't change*.
+
+The strategy, given that split:
+
+1. Rebuild the **cheap, deterministic** part whole and fresh every time (structural
+   base + dispatch + family + dataflow). This is always identical to a full build, so
+   there is zero splice risk there.
+2. Run the **expensive** jedi passes only on the *affected* modules.
+3. **Splice** the two jedi-produced contributions (behavioral ``calls`` edges +
+   ``accesses`` edges, and the per-function ``calls``/``control``/``complexity``/
+   ``attr_access`` node extras) for the unaffected modules straight from the old graph.
+
+**Affected set** = changed/added/removed modules, plus any module that (a) freshly
+imports a changed/added module, or (b) had an old behavioral edge into a changed or
+removed module. That covers both fast-tier (import/module resolution to a renamed
+symbol) and deep-tier (jedi reaching a changed target) staleness. When the affected
+set is large relative to the package, a full rebuild is cheaper and certainly correct,
+so we fall back to it.
+
+The acceptance bar (BACKLOG R1-C9) is **byte-identical to a full rebuild**; the test
+suite pins exactly that across edit / add / remove scenarios on both tiers.
+"""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+
+from codemap.extract.griffe_extractor import (
+    add_behavioral_layer, build_structural, extract,
+)
+from codemap.model import Graph
+from codemap.provenance import build_provenance, tool_identity
+from codemap.scope import diff_scopes
+
+# Behavioral `calls` resolutions produced by add_behavior (vs registry-dispatch,
+# which add_dispatch produces whole & fresh — those must NOT be spliced from old).
+_BEHAVIOR_CALL_RES = frozenset({"module", "self", "imported", "deep"})
+# R1-C22: `references` resolutions the behavioral pass owns (a name used as a value, or
+# as a type annotation). The consumer/doc references carry other resolutions and belong
+# to the repo-scope pass, which the incremental path does not touch.
+_BEHAVIOR_REF_RES = frozenset({"name", "annotation"})
+# Node-extras keys owned by the two jedi-sensitive passes (spliced for unaffected).
+_BEHAVIORAL_EXTRAS = ("calls", "control", "complexity", "attr_access")
+# Old edge types whose target landing in a changed/removed module makes the source
+# module stale (it must re-resolve). Only the spliced passes matter here.
+_DEP_EDGE_TYPES = frozenset({"calls", "accesses", "references"})
+
+# Above this fraction of modules affected, a full rebuild is cheaper (and trivially
+# correct) — no point splicing most of the graph.
+_FULL_FALLBACK_FRACTION = 0.5
+
+
+def _path_to_module(rel_path: str, target_pkg: str) -> str | None:
+    """Map a scope file path to a package module id, or None if it's not package code.
+
+    ``bquant/analysis/pipeline.py`` → ``bquant.analysis.pipeline``;
+    ``bquant/analysis/__init__.py`` → ``bquant.analysis``; ``bquant/__init__.py`` →
+    ``bquant``. Non-``.py`` files and files outside the package return None (they
+    don't produce module nodes in a single-package extract).
+    """
+    p = rel_path.replace("\\", "/")
+    if not p.endswith(".py"):
+        return None
+    parts = p.split("/")
+    if not parts or parts[0] != target_pkg:
+        return None
+    if parts[-1] == "__init__.py":
+        parts = parts[:-1]
+    else:
+        parts[-1] = parts[-1][:-3]  # strip .py
+    return ".".join(parts)
+
+
+def _module_indexer(module_ids):
+    """Return ``module_of(node_id)`` — the longest module id that owns the node."""
+    ordered = sorted(module_ids, key=len, reverse=True)
+
+    def module_of(node_id: str) -> str | None:
+        for m in ordered:
+            if node_id == m or node_id.startswith(m + "."):
+                return m
+        return None
+
+    return module_of
+
+
+def _affected_modules(old_graph, new_graph, base_mods, changed_removed, module_of):
+    """Modules whose jedi passes must re-run (see module docstring for the rules)."""
+    affected = set(base_mods)
+    # rule (a): a module that freshly imports a changed/added module.
+    for e in new_graph.edges:
+        if e.type == "imports" and e.target in base_mods:
+            affected.add(e.source)
+    # rule (b): a module whose old behavioral edge targeted a changed/removed module.
+    for e in old_graph.edges:
+        if e.type in _DEP_EDGE_TYPES:
+            tgt_mod = module_of(e.target)
+            if tgt_mod in changed_removed:
+                src_mod = module_of(e.source)
+                if src_mod is not None:
+                    affected.add(src_mod)
+    return affected
+
+
+def _splice_unaffected(new_graph, old_graph, unaffected, module_of) -> None:
+    """Copy the two jedi passes' output for unaffected modules from the old graph."""
+    for e in old_graph.edges:
+        keep = False
+        if e.type == "calls" and e.extras.get("resolution") in _BEHAVIOR_CALL_RES:
+            keep = module_of(e.source) in unaffected
+        elif e.type == "accesses":
+            keep = module_of(e.source) in unaffected
+        elif e.type == "references" and e.extras.get("resolution") in _BEHAVIOR_REF_RES:
+            keep = module_of(e.source) in unaffected  # R1-C22: name/annotation refs
+        if keep:
+            new_graph.add_edge(copy.deepcopy(e))
+    for nid, node in new_graph.nodes.items():
+        if module_of(nid) in unaffected and nid in old_graph.nodes:
+            old_extras = old_graph.nodes[nid].extras
+            for k in _BEHAVIORAL_EXTRAS:
+                if k in old_extras:
+                    node.extras[k] = copy.deepcopy(old_extras[k])
+
+
+def _same_builder(provenance: dict, tier: str) -> bool:
+    """Was the old graph produced by *this* codemap, on this tier? (R1-C25)
+
+    A graph with no provenance (pre-0.12) cannot answer, so it is treated as a
+    different builder — the conservative direction: a needless full rebuild costs a
+    minute, a silently stale graph costs a wrong answer.
+    """
+    if not provenance:
+        return False
+    return (provenance.get("tool") == tool_identity()
+            and provenance.get("tier") == tier)
+
+
+def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dict,
+                 *, deep: bool = False) -> tuple[Graph, dict]:
+    """Incrementally rebuild ``old_graph`` for the current source tree.
+
+    Returns ``(graph, info)`` where ``info`` records the decision (``mode``:
+    ``unchanged`` | ``incremental`` | ``full`` and the affected module list). The
+    result is byte-identical to ``extract(package_path, deep=deep)`` — the cheap
+    layers are rebuilt whole and the expensive jedi passes are recomputed for the
+    affected modules and spliced from the old graph for the rest.
+    """
+    target_pkg = old_graph.target
+    tier = "deep" if deep else "fast"
+    # R1-C25: the input is not the only thing that can change. `unchanged` below decides
+    # from the source tree alone, so an upgraded codemap over an untouched tree used to
+    # return yesterday's graph built by yesterday's extractor — the exact confusion the
+    # provenance block exists to name. A different tool or tier is a full rebuild.
+    if not _same_builder(old_graph.provenance, tier):
+        graph = extract(package_path, deep=deep)
+        return graph, {"mode": "full", "affected": [], "reason": "builder-changed"}
+
+    d = diff_scopes(old_scope, new_scope)
+    changed = {m for p in d["changed"] if (m := _path_to_module(p, target_pkg))}
+    added = {m for p in d["added"] if (m := _path_to_module(p, target_pkg))}
+    removed = {m for p in d["removed"] if (m := _path_to_module(p, target_pkg))}
+
+    # No package .py file changed → a single-package graph is unaffected (doc/consumer
+    # edits don't touch it). Return the old graph untouched.
+    if not (changed or added or removed):
+        return old_graph, {"mode": "unchanged", "affected": []}
+
+
+    graph, root, module_name, search_path = build_structural(package_path)
+    module_ids = {n.id for n in graph.nodes.values() if n.kind == "module"}
+    module_of = _module_indexer(module_ids)
+
+    base_mods = (changed | added | removed) & module_ids
+    changed_removed = (changed | removed)
+    affected = _affected_modules(old_graph, graph, base_mods, changed_removed,
+                                 module_of) & module_ids
+
+    if not module_ids or len(affected) >= _FULL_FALLBACK_FRACTION * len(module_ids):
+        add_behavioral_layer(graph, root, module_name, search_path, deep=deep)
+        graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"))
+        return graph, {"mode": "full", "affected": sorted(affected)}
+
+    add_behavioral_layer(graph, root, module_name, search_path, deep=deep,
+                         behavior_only=affected, attr_only=affected)
+    unaffected = module_ids - affected
+    _splice_unaffected(graph, old_graph, unaffected, module_of)
+    graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"))
+    return graph, {"mode": "incremental", "affected": sorted(affected)}

codemap/integrations/__init__.py

@@ -0,0 +1,51 @@
+"""External-tool integration layer (DESIGN §13 / §13.1).
+
+The opt-in adapter/router framework over third-party code-analysis tools. The core
+never depends on it — an integration is only reached when a user opts in
+(``codemap.toml``) and the tool is installed. See :mod:`codemap.integrations.base`
+for the five-mode model and the two output contracts.
+
+Concrete integrations register themselves on import (gitnexus router — PolyForm-NC;
+cocoindex adapter — Apache-2.0); importing this package must have no external side
+effects (dict inserts only; subprocess/availability calls are lazy).
+"""
+
+from __future__ import annotations
+
+from .base import (
+    GraphFragment,
+    Integration,
+    IntegrationMode,
+    RawAnswer,
+    SemanticHit,
+    is_permissive,
+)
+from .gate import IntegrationConfig, load_config
+from .registry import (
+    all_integrations,
+    get,
+    register,
+    resolve,
+    unregister,
+)
+
+# Import concrete integrations so they self-register (dict inserts only — no I/O;
+# availability/subprocess calls happen lazily at resolve/route time). DESIGN §13.1.
+from . import gitnexus as _gitnexus  # noqa: E402,F401  (router, PolyForm-NC)
+from . import cocoindex as _cocoindex  # noqa: E402,F401  (adapter, Apache-2.0)
+
+__all__ = [
+    "GraphFragment",
+    "Integration",
+    "IntegrationMode",
+    "RawAnswer",
+    "SemanticHit",
+    "is_permissive",
+    "IntegrationConfig",
+    "load_config",
+    "all_integrations",
+    "get",
+    "register",
+    "resolve",
+    "unregister",
+]

codemap/integrations/base.py

@@ -0,0 +1,196 @@
+"""Integration contracts — the two deep-coupling modes that need shared infra.
+
+DESIGN §13 / §13.1. Five integration modes exist on a depth×license gradient:
+
+    0. reimplement (learn-and-build)  — our own code, their idea; no tool, no infra
+    1. vendoring (copy source in)     — like `_scip_pb2.py`; permissive license only
+    2. library embed (pip dependency) — an extractor plugin; permissive license only
+    3. adapter                        — call user-installed tool, TRANSLATE its output
+                                        into our neutral graph; permissive only
+    4. router / passthrough           — call user-installed tool, FORWARD its answer
+                                        as-is; even non-commercial OK (opt-in + notice)
+
+Modes 0–2 reuse existing patterns (native code, vendored subpackage, `extract/`
+plugin). Only **adapter** and **router** need this package: they call an external
+tool the user installed and either absorb its output (adapter) or forward it
+(router). The invariant (DESIGN §13): the core never depends on an external tool —
+every integration is opt-in and the baseline works without it.
+
+Two output contracts, because the modes return fundamentally different things:
+
+  * an **adapter** yields a :class:`GraphFragment` — nodes/edges in our schema,
+    tagged ``provenance: external`` + resolver name, written to a **non-canonical
+    sidecar** (the canonical core graph stays deterministic — many external tools
+    are not);
+  * a **router** yields a :class:`RawAnswer` — the tool's answer untouched, which
+    never enters the graph.
+"""
+
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class IntegrationMode(str, Enum):
+    """The coupling mode of an integration (the two that need this infra)."""
+
+    ADAPTER = "adapter"  # translate the tool's output into our graph (permissive only)
+    ROUTER = "router"    # forward the tool's answer as-is (any license, opt-in)
+
+
+# Licenses under which we may **absorb** a tool's output into our artifact (adapter)
+# or depend on it. Anything else is router-only: we forward, never incorporate.
+# This is the machine-checkable half of the DESIGN §13.1 licensing policy.
+_PERMISSIVE = frozenset({
+    "mit", "apache-2.0", "apache 2.0", "apache", "bsd", "bsd-2-clause",
+    "bsd-3-clause", "isc", "unlicense", "0bsd", "psf",
+})
+
+
+def is_permissive(license_id: str) -> bool:
+    """True if ``license_id`` permits absorbing the tool's output (adapter-eligible).
+
+    Normalizes case/spacing; unknown or non-commercial licenses (e.g. PolyForm
+    Noncommercial) return False → such a tool may only be a :class:`IntegrationMode.ROUTER`.
+    """
+    return license_id.strip().lower() in _PERMISSIVE
+
+
+@dataclass
+class GraphFragment:
+    """Adapter output — graph nodes/edges to be merged into a **non-canonical sidecar**.
+
+    Every node/edge is stamped with provenance so it never masquerades as part of
+    the deterministic core graph: ``extras.provenance = 'external'`` and
+    ``extras.resolver = <tool name>``. ``deterministic`` records whether the source
+    tool produces stable output — False (the common case, e.g. graphlens' SQLite)
+    is why fragments live in a sidecar, not the canonical graph.
+    """
+
+    resolver: str
+    nodes: list[dict[str, Any]] = field(default_factory=list)
+    edges: list[dict[str, Any]] = field(default_factory=list)
+    deterministic: bool = False
+
+    def stamped(self) -> "GraphFragment":
+        """Return a copy with every node/edge tagged external + resolver."""
+        tag = {"provenance": "external", "resolver": self.resolver}
+        nodes = [{**n, "extras": {**n.get("extras", {}), **tag}} for n in self.nodes]
+        edges = [{**e, "extras": {**e.get("extras", {}), **tag}} for e in self.edges]
+        return GraphFragment(self.resolver, nodes, edges, self.deterministic)
+
+    def to_sidecar_dict(self) -> dict[str, Any]:
+        """Serialize for the ``external_edges.json`` sidecar (non-canonical)."""
+        f = self.stamped()
+        return {
+            "resolver": f.resolver,
+            "deterministic": f.deterministic,
+            "canonical": False,  # explicit: never part of the deterministic core graph
+            "nodes": f.nodes,
+            "edges": f.edges,
+        }
+
+
+@dataclass
+class RawAnswer:
+    """Router output — the external tool's answer, forwarded untouched.
+
+    It is never parsed into our schema. ``source`` names the tool; ``disclaimer`` is
+    the licensing notice shown to the user; ``payload`` is whatever the tool returned.
+    """
+
+    source: str
+    payload: Any
+    disclaimer: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"source": self.source, "passthrough": True,
+                "disclaimer": self.disclaimer, "payload": self.payload}
+
+
+@dataclass
+class SemanticHit:
+    """Retrieval-adapter output — one hit, **enriched to a codemap symbol**.
+
+    A retrieval adapter (a semantic-search tool) returns fuzzy locations (``file`` +
+    line range + ``score``). codemap's own graph then resolves each to the exact
+    symbol at that location (``Query.symbol_at``), so the answer is codemap-native —
+    the "fuzzy retrieval → exact structure" composition neither tool gives alone.
+    ``symbol`` is the resolved node id (None when the location isn't in the graph);
+    ``resolution`` records how it resolved.
+    """
+
+    file: str
+    start_line: int
+    score: float
+    end_line: int | None = None
+    symbol: str | None = None            # codemap node id at (file, start_line)
+    resolution: str = "unresolved"       # "symbol" | "unresolved"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "symbol": self.symbol,
+            "resolution": self.resolution,
+            "score": self.score,
+            "file": self.file,
+            "lines": [self.start_line, self.end_line],
+        }
+
+
+class Integration(abc.ABC):
+    """One external tool, wired in adapter or router mode.
+
+    Subclasses declare identity + the capabilities they provide and implement
+    availability detection. Adapters implement :meth:`extract_fragments`; routers
+    implement :meth:`route`. The registry enforces the licensing policy
+    (adapters must be permissive-licensed) at registration time.
+    """
+
+    #: short, stable identifier (e.g. "graphlens", "gitnexus")
+    name: str
+    #: :class:`IntegrationMode`
+    mode: IntegrationMode
+    #: SPDX-ish license id (checked by :func:`is_permissive`)
+    license: str
+    #: capability keys this tool provides (e.g. ("resolve-into-deps",))
+    capabilities: tuple[str, ...] = ()
+
+    @abc.abstractmethod
+    def is_available(self) -> bool:
+        """True if the user has the tool installed and it is usable."""
+
+    def disclaimer(self) -> str | None:
+        """One-time licensing notice, or None for a permissive tool.
+
+        For a non-commercial tool the notice is worded on **use**, not reselling
+        (DESIGN §13.1 п.3): routing to it is only for non-commercial use.
+        """
+        if is_permissive(self.license):
+            return None
+        return (
+            f"Tool '{self.name}' is licensed {self.license}. This route is for "
+            f"non-commercial use only; for commercial use of codemap, do not enable "
+            f"it, or obtain a commercial license from the tool's author."
+        )
+
+    # -- mode-specific surfaces (implement the one for your mode) -------------
+
+    def extract_fragments(self, target: str, **kw: Any) -> GraphFragment:  # adapter
+        raise NotImplementedError(f"{self.name} is not an adapter")
+
+    def search(self, capability: str, query: str, **kw: Any) -> list[dict[str, Any]]:
+        """Retrieval-adapter surface: run the tool, return raw hits.
+
+        Each hit is a plain dict ``{file, start_line, end_line, score}`` (locations,
+        not yet codemap symbols). codemap's ``serve.semantic.semantic_search``
+        enriches these into :class:`SemanticHit`\\s against the graph — the adapter
+        itself never needs the graph (which keeps ``integrations`` a near-leaf layer,
+        below ``query``). Implement this for a retrieval-class adapter.
+        """
+        raise NotImplementedError(f"{self.name} is not a search adapter")
+
+    def route(self, capability: str, question: str, **kw: Any) -> RawAnswer:  # router
+        raise NotImplementedError(f"{self.name} is not a router")

codemap/integrations/cocoindex.py

@@ -0,0 +1,78 @@
+"""cocoindex-code adapter (DESIGN §13.1, mode 3 — adapter / retrieval).
+
+cocoindex-code (`ccc`, github.com/cocoindex-io/cocoindex-code) is an **Apache-2.0**
+semantic code-search CLI: tree-sitter chunking + local embeddings, an embedded
+index (no DB, no API key). codemap has no fuzzy/semantic layer by design, so this
+is the first tool that fills that gap — and because its license is permissive, it
+can be an **adapter** (we translate its output into codemap's own contract), not a
+router. See ``research/tools/cocoindex-code.md``.
+
+The "translation" is the whole point: `ccc` returns fuzzy locations
+(``file`` + line range + score); codemap resolves each to the **exact symbol** at
+that location via its graph (:func:`codemap.integrations.semantic.semantic_search`).
+So a concept query comes back as ranked codemap symbols — the "fuzzy retrieval →
+exact structure" composition neither tool gives alone.
+
+This module only builds the argv and returns raw hits; enrichment against the graph
+lives in the semantic module (the adapter never needs the graph). Opt-in (the
+registry gates on ``codemap.toml``); reached only when `ccc` is installed. Anything
+wrong — missing binary, non-JSON — degrades to "no hits" (``run_json`` → None).
+
+`ccc` keys off its per-repo index in the working directory, so the caller passes the
+repo ``root`` as the subprocess cwd (that's where ``ccc index`` was run).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import Integration, IntegrationMode
+from .registry import register
+from .transport import run_json, which
+
+_BINARY = "ccc"
+
+
+class CocoIndexAdapter(Integration):
+    name = "cocoindex"
+    mode = IntegrationMode.ADAPTER
+    license = "Apache-2.0"
+    capabilities = ("semantic-search",)
+
+    def is_available(self) -> bool:
+        return which(_BINARY) is not None
+
+    def _argv(self, query: str, limit: int) -> list[str]:
+        """`ccc search <query> --limit N --json` (version-tolerant; drift → no hits)."""
+        return [_BINARY, "search", query, "--limit", str(limit), "--json"]
+
+    def search(self, capability: str, query: str, **kw: Any) -> list[dict[str, Any]]:
+        """Run `ccc search` in the repo ``root`` and return raw location hits.
+
+        Returns ``[{file, start_line, end_line, score}, …]`` (already sorted by score
+        by `ccc`); enrichment to codemap symbols happens in the semantic module.
+        """
+        if capability not in self.capabilities:
+            raise ValueError(f"cocoindex does not provide {capability!r}")
+        root = kw.get("root")
+        limit = int(kw.get("limit", 10))
+        payload = run_json(self._argv(query, limit),
+                           timeout=float(kw.get("timeout", 120.0)), cwd=root)
+        if not isinstance(payload, dict) or not payload.get("success"):
+            return []
+        hits = []
+        for r in payload.get("results", []):
+            fp = r.get("file_path")
+            sl = r.get("start_line")
+            if fp is None or sl is None:
+                continue  # a hit we can't anchor is useless for enrichment
+            hits.append({
+                "file": fp,
+                "start_line": int(sl),
+                "end_line": r.get("end_line"),
+                "score": float(r.get("score", 0.0)),
+            })
+        return hits
+
+
+register(CocoIndexAdapter())

codemap/integrations/gate.py

@@ -0,0 +1,58 @@
+"""Opt-in gate + licensing disclaimer for external integrations (DESIGN §13.1).
+
+Every integration is **off by default** (invariant: the core works with no external
+tool). A user enables one explicitly in ``codemap.toml``::
+
+    [integrations]
+    enabled = ["graphlens", "gitnexus"]     # opt-in, not default
+    acknowledged = ["gitnexus"]             # licensing notice already accepted
+
+``enabled`` is the opt-in list (DESIGN §13.1 п.2). ``acknowledged`` records which
+non-commercial notices the user has already accepted, so the disclaimer (п.3) is
+shown once rather than every call. Absent config → nothing enabled.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from codemap.tomlio import read_toml
+
+
+@dataclass
+class IntegrationConfig:
+    """Resolved ``[integrations]`` config — which tools are opted in / acknowledged.
+
+    ``error`` carries the reason ``codemap.toml`` could not be read, if it could not be
+    (R1-C27). Nothing is enabled either way — the opt-in invariant is not weakened by a
+    read failure — but a user who wrote an opt-in list and got a typo deserves to hear
+    that, rather than watch the integration quietly stay off.
+    """
+
+    enabled: frozenset[str] = frozenset()
+    acknowledged: frozenset[str] = frozenset()
+    error: str | None = None
+
+    def is_enabled(self, name: str) -> bool:
+        return name in self.enabled
+
+    def is_acknowledged(self, name: str) -> bool:
+        return name in self.acknowledged
+
+
+def load_config(root: str | Path = ".") -> IntegrationConfig:
+    """Read ``[integrations]`` from ``codemap.toml`` under ``root`` (empty if absent).
+
+    A malformed file yields an empty config rather than raising — a bad opt-in list must
+    never break a plain build — but the reason travels back in ``error`` instead of being
+    indistinguishable from "no config" (R1-C27).
+    """
+    data, error = read_toml(Path(root) / "codemap.toml")
+    if error:
+        return IntegrationConfig(error=error)
+    section = data.get("integrations", {})
+    return IntegrationConfig(
+        enabled=frozenset(section.get("enabled", []) or []),
+        acknowledged=frozenset(section.get("acknowledged", []) or []),
+    )

codemap/integrations/gitnexus.py

@@ -0,0 +1,93 @@
+"""GitNexus router (DESIGN §13.1, mode 4 — passthrough).
+
+GitNexus (github.com/…/gitnexus) is a TS/Node code-graph tool with capabilities
+codemap lacks: **BM25 + local-embedding semantic search (RRF)**, Leiden community
+clusters, and process/flow tracing. It is licensed **PolyForm Noncommercial 1.0.0**,
+so per DESIGN §13.1 it can only be a **router**: we forward the question and return
+its answer untouched — never absorb it into our graph (that would require a
+permissive license), never bundle it (calling ≠ distributing, п.1).
+
+This module only builds the argv and wraps the reply; it is opt-in (the registry
+gates on ``codemap.toml``) and reached only when the user has ``gitnexus`` installed.
+Anything wrong — missing binary, bad flag, non-JSON — degrades to "unavailable"
+(``transport.run_json`` returns None), never wrong data.
+
+GitNexus ships as an npm package; a plain ``npm install gitnexus`` puts the binary
+in a local ``node_modules/.bin`` (1.7 GB of native modules), **not** on the global
+PATH — so ``which('gitnexus')`` alone would report "unavailable" even right after a
+successful install. ``_launcher`` therefore prefers a global binary but falls back
+to ``npx --no-install gitnexus``, which runs a locally-installed package **without**
+triggering a surprise network download (if it isn't installed, ``npx --no-install``
+fails and we degrade to None — on-brand: no egress, no bundling).
+
+CLI flag details are version-specific (measured against v1.6.9, see
+``research/tools/gitnexus.md``); the graceful-degrade contract means a flag drift
+surfaces as "no answer", not a crash.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import Integration, IntegrationMode, RawAnswer
+from .registry import register
+from .transport import run_json, which
+
+_BINARY = "gitnexus"
+
+# capability → the GitNexus verb that serves it (documented verbs, v1.6.9).
+_VERB = {
+    "semantic-search": "search",   # BM25 + local embeddings + RRF
+    "flow-narrative": "trace",     # process/flow tracing from entry points
+    "community-clusters": "check",  # Leiden clusters (with --clusters)
+}
+
+
+class GitNexusRouter(Integration):
+    name = "gitnexus"
+    mode = IntegrationMode.ROUTER
+    license = "PolyForm-Noncommercial-1.0.0"
+    capabilities = tuple(_VERB)
+
+    def _launcher(self) -> list[str] | None:
+        """How to invoke gitnexus, or None if it can't be reached.
+
+        Global binary on PATH wins; else ``npx --no-install gitnexus`` (serves a
+        local ``npm install gitnexus`` without a global install and without a
+        surprise download); else None → the capability is unavailable.
+        """
+        if which(_BINARY) is not None:
+            return [_BINARY]
+        if which("npx") is not None:
+            return ["npx", "--no-install", _BINARY]
+        return None
+
+    def is_available(self) -> bool:
+        return self._launcher() is not None
+
+    def _verb_argv(self, capability: str, question: str) -> list[str]:
+        """The gitnexus-specific argv tail (verb + args), launcher-independent."""
+        verb = _VERB[capability]
+        argv = [verb]
+        if capability == "community-clusters":
+            argv += ["--clusters"]
+        else:
+            argv += [question]
+        return argv + ["--json"]
+
+    def _argv(self, capability: str, question: str, launcher: list[str]) -> list[str]:
+        """Full argv = how-to-invoke + what-to-run (best-effort, version-specific)."""
+        return launcher + self._verb_argv(capability, question)
+
+    def route(self, capability: str, question: str, **kw: Any) -> RawAnswer:
+        if capability not in self.capabilities:
+            raise ValueError(f"gitnexus does not provide {capability!r}")
+        launcher = self._launcher()
+        payload = None if launcher is None else run_json(
+            self._argv(capability, question, launcher),
+            timeout=float(kw.get("timeout", 120.0)))
+        return RawAnswer(source=self.name, payload=payload,
+                         disclaimer=self.disclaimer())
+
+
+register(GitNexusRouter())