graphify-mesh 0.0.22__py3-none-any.whl

graphify_mesh/__init__.py

@@ -0,0 +1,20 @@
+"""graphify-mesh — a scheduled sync engine + companion MCP server that merges
+many per-repo `graphify` knowledge graphs into one safe, repo-attributed,
+human-named global graph with a cross-project dependency/similarity/API overlay.
+
+See the `sync` subpackage for the merge/naming/embed/overlay/publish pipeline
+and the `server` subpackage for the stdio MCP query server.
+"""
+
+from __future__ import annotations
+
+try:
+    # Generated by hatch-vcs at build time from the git tag (see
+    # [tool.hatch.build.hooks.vcs] in pyproject.toml) — never hand-edit
+    # _version.py, and never hand-edit a version string here either.
+    from graphify_mesh._version import __version__
+except ImportError:
+    # No git tags reachable and no build has run yet (e.g. a shallow clone
+    # with no tags, or source copied without git metadata) — better than a
+    # crash on import, but callers should not trust this as a real version.
+    __version__ = "0+unknown"

graphify_mesh/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.22'
+__version_tuple__ = version_tuple = (0, 0, 22)
+
+__commit_id__ = commit_id = None

graphify_mesh/server/__init__.py

@@ -0,0 +1,61 @@
+"""graphify-mesh: companion stdio MCP server for the merged global graph.
+
+Two constraints are the most load-bearing for this package: the `project_map`
+input must resolve a registered `repo_id` (never an arbitrary on-disk path),
+and a generation is only ever served whole once its manifest passes a
+consistency check.
+
+## Dependency decision
+
+This server is implemented with the Python STANDARD LIBRARY ONLY — no `mcp`
+SDK package, no third-party JSON-RPC/transport library, and therefore no
+dedicated virtualenv is required. It runs under the same interpreter as
+`graphify_mesh.sync`.
+
+This section is historical: the server has since moved onto the official
+`mcp` SDK (`server/sdk_app.py`, `server/stdio_guard.py`) for its stdio
+transport, because a second transport (streamable HTTP, for the shared
+daemon) needed a real MCP session/protocol implementation rather than a
+hand-rolled newline-delimited JSON-RPC loop. The size-cap guard the old
+hand-rolled reader provided (`MAX_LINE_BYTES`) is carried forward in
+`stdio_guard.capped_stdin`, since the SDK's own stdio reader has no such
+bound.
+
+## Two MCP servers: this one vs graphify's own
+
+graphify's own MCP server (`graphify.serve`) can be repointed to read the
+PUBLISHED `<mesh_root>/graphify/global/current/global-graph.json` for
+STRUCTURAL/PR tools only: `god_nodes`, `shortest_path`, `get_pr_impact`,
+`get_community`, `get_neighbors`, `get_node`, `graph_stats`, `list_prs`,
+`triage_prs`. Those tools operate purely on the structural graph shape and
+gain nothing from this package's scope/fusion/overlay logic — repointing them
+is a config change (point at the new published path instead of
+`~/.graphify/global-graph.json`), not a rewrite.
+
+graphify-mesh (this package) owns everything hybrid/cross-project/evidence-
+oriented: `search`, `cross_project`, `find_similar`, `project_map`,
+`context_pack`. These need scope resolution, the lexical index, the embedding
+index, and the cross-project overlay — none of which graphify's own server
+has access to.
+
+**By design, the two servers can show different community names** for the
+same node: graphify's server reads the published graph's `community_name`
+attribute directly, but graphify-mesh's naming stage strips and relabels
+community names during the sync pipeline (see
+`graphify_mesh.sync.naming.strip_project_community_attrs`). Historical caches
+or a not-yet-repointed upstream instance may still show an old per-project
+name for a transitional period. This is not a bug to reconcile; it is a known
+consequence of the relabeling running only in this pipeline. Route
+accordingly: local per-project structural questions and PR tools -> graphify's
+server; concept/cross-project/evidence-pack questions -> graphify-mesh.
+
+## No arbitrary-path caching
+
+This server never exposes a "give me any path on disk and I'll load/cache it"
+parameter. `project_map(repo)` takes a `repo_id` that MUST resolve against the
+registry (see `scope.py`) — there is no arbitrary-path acceptance and
+therefore no unbounded per-path cache: the only thing ever cached is the
+single current *generation* (`store.py`'s `GenerationStore`), reloaded
+wholesale (never partially) on hot-reload and not keyed by caller-supplied
+paths at all.
+"""

graphify_mesh/server/anchors.py

@@ -0,0 +1,223 @@
+"""Symbol-anchored ranking for `search`.
+
+A multi-token query often names one symbol (`export`, `AbstractCronJob`) plus
+words describing its context. Each query token that resolves through the
+exact-alias table to a RARE alias (few members) yields anchor candidates. A
+candidate is scored by the idf of the OTHER query tokens found in its own
+lexical fields and in its depth-1 EXTRACTED neighbours' fields. Only a
+candidate that clears an absolute floor AND dominates the next one is pinned
+right after the exact-alias hits; otherwise ranking is left untouched.
+"""
+
+from __future__ import annotations
+
+import math
+import weakref
+from dataclasses import dataclass, field
+
+from graphify_mesh.server import lexical_read, ranking
+from graphify_mesh.server.store import Generation
+from graphify_mesh.sync.lexical_index import normalize_alias_query, tokenize_text
+
+# An alias form yields candidates only with 1..N members after the repo
+# filter. Rarity is the alias member count, NOT the token's document
+# frequency: a symbol name such as `export` can have the highest df in the
+# query while its `.export()` alias still names only a handful of methods.
+ANCHOR_MAX_ALIAS_MEMBERS = 10
+
+# Absolute score floor a pinned anchor must reach, in idf units.
+ANCHOR_MIN_SCORE = 10.0
+
+# A pinned anchor must score at least this multiple of the next candidate.
+ANCHOR_DOMINANCE = 2.0
+
+ANCHOR_MAX_PINS = 2
+
+# Score carried by anchor hits: below `retrieval.EXACT_MATCH_SCORE` so exact
+# hits stay first, above every fused score (RRF sums stay below 1.0).
+ANCHOR_MATCH_SCORE = 500_000.0
+
+# Query tokens are caller-chosen, so the per-generation df memo is bounded;
+# past the cap it is cleared and refilled.
+_DOC_FREQ_CACHE_MAX = 4096
+
+
+@dataclass
+class _GenerationCache:
+    generation_id: str
+    # Identity check on top of the id: a weakref, so a replaced generation is
+    # never kept alive by this cache.
+    generation: weakref.ref[Generation]
+    doc_ids_by_key: dict[str, list[int]] | None
+    doc_freq: dict[str, int] = field(default_factory=dict)
+
+
+# Only the most recent generation's cache is kept. Concurrent readers may
+# race on this assignment; the loser just rebuilds, the content is the same,
+# so no lock is needed.
+_cache: _GenerationCache | None = None
+
+
+def _generation_cache(generation: Generation) -> _GenerationCache:
+    global _cache
+    cache = _cache
+    if (
+        cache is None
+        or cache.generation_id != generation.generation_id
+        or cache.generation() is not generation
+    ):
+        cache = _GenerationCache(
+            generation_id=generation.generation_id,
+            generation=weakref.ref(generation),
+            doc_ids_by_key=lexical_read.doc_ids_by_key(generation.lexical),
+        )
+        _cache = cache
+    return cache
+
+
+def _doc_freq(token: str, generation: Generation, cache: _GenerationCache) -> int:
+    df = cache.doc_freq.get(token)
+    if df is None:
+        df = lexical_read.term_doc_freq(generation.lexical, token)
+        if len(cache.doc_freq) >= _DOC_FREQ_CACHE_MAX:
+            cache.doc_freq.clear()
+        cache.doc_freq[token] = df
+    return df
+
+
+def _alias_members(
+    form: str, generation: Generation, repo_filter: frozenset[str] | None
+) -> set[str]:
+    refs = lexical_read.alias_refs(generation.lexical, normalize_alias_query(form))
+    return {key for repo, key in refs if repo_filter is None or repo in repo_filter}
+
+
+def _neighbor_keys(
+    key: str, generation: Generation, repo_filter: frozenset[str] | None
+) -> set[str]:
+    node_id = generation.node_id_by_key.get(key)
+    if node_id is None:
+        return set()
+    keys: set[str] = set()
+    for neighbor_id, edge in generation.adjacency.get(node_id, []):
+        # Ignores the caller's `include_inferred` on purpose: a pin must rest
+        # on EXTRACTED evidence only.
+        if not ranking.edge_followable(edge, include_inferred=False):
+            continue
+        neighbor_key = generation.key_by_node_id.get(neighbor_id)
+        if neighbor_key is None:
+            continue
+        neighbor_node = generation.node_by_id.get(neighbor_id, {})
+        if repo_filter is not None and neighbor_node.get("repo") not in repo_filter:
+            continue
+        keys.add(neighbor_key)
+    return keys
+
+
+def _full_token_keys(
+    token: str, generation: Generation, repo_filter: frozenset[str] | None
+) -> set[str]:
+    """Every key `token` has a posting for (v2 path)."""
+    return {
+        key
+        for repo, key, _field in lexical_read.term_postings(generation.lexical, token)
+        if key is not None and (repo_filter is None or repo in repo_filter)
+    }
+
+
+def _probe_token_keys(
+    token: str, generation: Generation, key_docs: dict[str, list[int]], doc_ids: set[int]
+) -> set[str]:
+    """The probe keys `token` has a posting for (v3 path). Probe keys are
+    already repo-filtered, so no posting-level filter is needed."""
+    hits = lexical_read.term_doc_hits(generation.lexical, token, doc_ids)
+    return {key for key, ids in key_docs.items() if not hits.isdisjoint(ids)}
+
+
+def _candidate_scores(
+    tokens: list[str],
+    via: dict[str, set[str]],
+    generation: Generation,
+    repo_filter: frozenset[str] | None,
+) -> list[tuple[str, float]]:
+    """Candidates with their idf score, best first. Only candidates and
+    their neighbours are ever tested for membership, so on v3 the posting
+    lookup is restricted to those keys instead of every posting."""
+    cache = _generation_cache(generation)
+    neighbors_by_key = {key: _neighbor_keys(key, generation, repo_filter) for key in via}
+    needed = [t for t in tokens if any(t not in via_tokens for via_tokens in via.values())]
+
+    # idf is corpus-wide by design (one df table per generation), not per
+    # scope, so under `repo:<id>` it and ANCHOR_MIN_SCORE stay corpus-relative.
+    # Clamped at 0: a v2 index without `doc_freq.global` counts field
+    # postings, so df can exceed total_docs.
+    total_docs = lexical_read.document_count(generation.lexical)
+    token_idf: dict[str, float] = {}
+    for token in needed:
+        df = _doc_freq(token, generation, cache)
+        token_idf[token] = max(0.0, math.log(total_docs / df)) if df > 0 and total_docs > 0 else 0.0
+
+    token_keys: dict[str, set[str]] = {}
+    if cache.doc_ids_by_key is None:
+        for token in needed:
+            token_keys[token] = _full_token_keys(token, generation, repo_filter)
+    else:
+        probe = set(via).union(*neighbors_by_key.values())
+        key_docs = {key: cache.doc_ids_by_key[key] for key in probe if key in cache.doc_ids_by_key}
+        doc_ids = {doc_id for ids in key_docs.values() for doc_id in ids}
+        for token in needed:
+            token_keys[token] = _probe_token_keys(token, generation, key_docs, doc_ids)
+
+    scores: list[tuple[str, float]] = []
+    for key, via_tokens in via.items():
+        neighbors = neighbors_by_key[key]
+        score = 0.0
+        for token in tokens:
+            if token in via_tokens:
+                continue
+            keys = token_keys[token]
+            if key in keys:
+                score += token_idf[token]
+            if not neighbors.isdisjoint(keys):
+                score += token_idf[token]
+        scores.append((key, score))
+    scores.sort(key=lambda kv: (-kv[1], kv[0]))
+    return scores
+
+
+def anchor_keys(
+    query: str,
+    generation: Generation,
+    repo_filter: frozenset[str] | None,
+    exclude: set[str],
+) -> list[str]:
+    """Keys to pin right after the exact-alias hits, best first; `[]` when
+    no candidate is both above `ANCHOR_MIN_SCORE` and dominant."""
+    tokens = list(dict.fromkeys(tokenize_text(query)))
+    if len(tokens) < 2:
+        return []
+
+    via: dict[str, set[str]] = {}
+    for token in tokens:
+        for form in (token, f".{token}()"):
+            members = _alias_members(form, generation, repo_filter)
+            if not 1 <= len(members) <= ANCHOR_MAX_ALIAS_MEMBERS:
+                continue
+            for key in members:
+                if key in exclude or key not in generation.node_id_by_key:
+                    continue
+                via.setdefault(key, set()).add(token)
+    if not via:
+        return []
+
+    scores = _candidate_scores(tokens, via, generation, repo_filter)
+
+    pinned: list[str] = []
+    for index, (key, score) in enumerate(scores):
+        if len(pinned) >= ANCHOR_MAX_PINS:
+            break
+        next_score = scores[index + 1][1] if index + 1 < len(scores) else 0.0
+        if score < ANCHOR_MIN_SCORE or score < ANCHOR_DOMINANCE * next_score:
+            break
+        pinned.append(key)
+    return pinned

graphify_mesh/server/citation.py

@@ -0,0 +1,17 @@
+"""The `[repo:source_file:line]` citation every node-returning tool emits.
+
+Kept in its own module so `server.py` (search/cross_project/find_similar
+hits) and `traverse.py` (the `neighbors` tool) render citations through one
+function and can never drift apart. The line comes from
+`graphify_mesh.sync.embedding.node_line`, which also reads graphify's
+`source_location: "L34"` form; an unknown line renders as `?`.
+"""
+
+from __future__ import annotations
+
+from graphify_mesh.sync.embedding import node_line
+
+
+def citation(repo: str, source_file: str, node: dict) -> str:
+    line = node_line(node)
+    return f"[{repo}:{source_file}:{line if line is not None else '?'}]"

graphify_mesh/server/config.py

@@ -0,0 +1,195 @@
+"""Resolved runtime configuration for one graphify-mesh server process.
+
+Mirrors `graphify_mesh.sync.config.Settings`'s "all paths configurable"
+convention so tests never touch a real filesystem tree; the default below is
+a placeholder — override via GRAPHIFY_MESH_ROOT for your environment.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_HTTP_HOST = "127.0.0.1"
+DEFAULT_HTTP_PORT = 19744
+DEFAULT_HTTP_PATH = "/mcp"
+
+# Hostnames that mean loopback without being parseable as an IP address. Any
+# other name is treated as public: the bind guard never resolves DNS, so a name
+# it cannot decide is a name it refuses.
+_LOOPBACK_HOST_NAMES = frozenset(
+    {"localhost", "localhost.localdomain", "ip6-localhost", "ip6-loopback"}
+)
+
+# The bearer token is the only gate on a TCP port every local process can reach.
+MIN_HTTP_TOKEN_CHARS = 32
+
+
+class ConfigError(ValueError):
+    """Invalid transport configuration. Raised at startup, never per request."""
+
+
+def is_loopback_bind(host: str) -> bool:
+    """True when binding to `host` reaches loopback only.
+
+    Everything else, wildcards and unresolvable names included, counts as a
+    public bind and needs the explicit opt-in.
+    """
+    candidate = host.strip()
+    if candidate.startswith("[") and candidate.endswith("]"):
+        candidate = candidate[1:-1]
+    # Drop an IPv6 zone index ("fe80::1%eth0"), which ip_address rejects.
+    candidate = candidate.split("%", 1)[0]
+    if not candidate:
+        return False
+    try:
+        address = ipaddress.ip_address(candidate)
+    except ValueError:
+        return candidate.lower() in _LOOPBACK_HOST_NAMES
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped is not None:
+        return address.ipv4_mapped.is_loopback
+    return address.is_loopback
+
+
+@dataclass
+class ServerConfig:
+    mesh_root: Path
+    registry_path: Path
+    transport: str = "stdio"
+    http_host: str = DEFAULT_HTTP_HOST
+    http_port: int = DEFAULT_HTTP_PORT
+    http_path: str = DEFAULT_HTTP_PATH
+    http_token: str | None = field(default=None, repr=False)
+    allow_public_bind: bool = False
+
+    @property
+    def global_dir(self) -> Path:
+        return self.mesh_root / "graphify" / "global"
+
+    @property
+    def current_symlink(self) -> Path:
+        return self.global_dir / "current"
+
+    @property
+    def embeddings_current_symlink(self) -> Path:
+        return self.global_dir / "embeddings" / "current"
+
+    @classmethod
+    def from_env(
+        cls,
+        mesh_root: Path | None = None,
+        registry_path: Path | None = None,
+        transport: str | None = None,
+        http_host: str | None = None,
+        http_port: int | None = None,
+        http_path: str | None = None,
+        allow_public_bind: bool | None = None,
+    ) -> ServerConfig:
+        # Defaults to the current working directory (no machine-specific
+        # path); set GRAPHIFY_MESH_ROOT for a real deployment.
+        resolved_mesh_root = Path(
+            mesh_root or os.environ.get("GRAPHIFY_MESH_ROOT") or Path.cwd()
+        ).resolve()
+        resolved_registry = Path(
+            registry_path
+            or os.environ.get(
+                "GRAPHIFY_MESH_REGISTRY", str(resolved_mesh_root / "bin" / "registry.json")
+            )
+        ).resolve()
+
+        # Resolve transport (explicit argument > environment > default)
+        if transport is not None:
+            resolved_transport = transport
+        elif "GRAPHIFY_MESH_TRANSPORT" in os.environ:
+            resolved_transport = os.environ["GRAPHIFY_MESH_TRANSPORT"]
+        else:
+            resolved_transport = "stdio"
+
+        if resolved_transport not in ("stdio", "http"):
+            raise ConfigError(
+                f"Invalid transport '{resolved_transport}'; must be 'stdio' or 'http'"
+            )
+
+        # Resolve HTTP host (explicit argument > environment > default)
+        resolved_http_host = (
+            http_host or os.environ.get("GRAPHIFY_MESH_HTTP_HOST") or DEFAULT_HTTP_HOST
+        )
+
+        # Resolve HTTP port (explicit argument > environment > default)
+        resolved_http_port: int
+        if http_port is not None:
+            resolved_http_port = http_port
+        else:
+            port_str = os.environ.get("GRAPHIFY_MESH_HTTP_PORT")
+            if port_str:
+                try:
+                    resolved_http_port = int(port_str)
+                except ValueError as err:
+                    raise ConfigError(
+                        f"GRAPHIFY_MESH_HTTP_PORT must be an integer, got '{port_str}'"
+                    ) from err
+            else:
+                resolved_http_port = DEFAULT_HTTP_PORT
+
+        # Validate port is in valid range
+        if resolved_http_port < 1 or resolved_http_port > 65535:
+            raise ConfigError(
+                f"HTTP port must be between 1 and 65535, got {resolved_http_port}"  # noqa: E501
+            )
+
+        # Resolve HTTP path (explicit argument > environment > default)
+        resolved_http_path = (
+            http_path or os.environ.get("GRAPHIFY_MESH_HTTP_PATH") or DEFAULT_HTTP_PATH
+        )
+
+        # Validate path starts with /
+        if not resolved_http_path.startswith("/"):
+            raise ConfigError(f"HTTP path must start with '/', got '{resolved_http_path}'")
+
+        # Resolve allow_public_bind (explicit argument > environment > default)
+        resolved_allow_public_bind: bool
+        if allow_public_bind is not None:
+            resolved_allow_public_bind = allow_public_bind
+        else:
+            env_val = os.environ.get("GRAPHIFY_MESH_ALLOW_PUBLIC_BIND", "").lower()
+            resolved_allow_public_bind = env_val in ("1", "true", "yes")
+
+        # Check for public bind without opt-in
+        if not is_loopback_bind(resolved_http_host) and not resolved_allow_public_bind:
+            raise ConfigError(
+                f"Cannot bind to '{resolved_http_host}': any non-loopback bind requires "
+                "the --allow-public-bind flag (or GRAPHIFY_MESH_ALLOW_PUBLIC_BIND=1). "
+                "A hostname that is not localhost and does not parse as an IP address "
+                "counts as non-loopback."
+            )
+
+        # Resolve HTTP token (explicit argument > environment > default)
+        resolved_http_token: str | None = None
+        if resolved_transport == "http":
+            token = (os.environ.get("GRAPHIFY_MESH_HTTP_TOKEN") or "").strip()
+            if not token:
+                raise ConfigError(
+                    "HTTP transport requires a bearer token: set GRAPHIFY_MESH_HTTP_TOKEN "
+                    "(a loopback TCP port is reachable by every local process, unlike the "
+                    "unix socket it replaces)"
+                )
+            if len(token) < MIN_HTTP_TOKEN_CHARS:
+                raise ConfigError(
+                    "GRAPHIFY_MESH_HTTP_TOKEN is too short: at least "
+                    f"{MIN_HTTP_TOKEN_CHARS} characters are required. Generate one with: "
+                    'python -c "import secrets; print(secrets.token_urlsafe(32))"'
+                )
+            resolved_http_token = token
+
+        return cls(
+            mesh_root=resolved_mesh_root,
+            registry_path=resolved_registry,
+            transport=resolved_transport,
+            http_host=resolved_http_host,
+            http_port=resolved_http_port,
+            http_path=resolved_http_path,
+            http_token=resolved_http_token,
+            allow_public_bind=resolved_allow_public_bind,
+        )