graphitect 0.2.0__py3-none-any.whl

graphify/_minhash.py

@@ -0,0 +1,107 @@
+"""MinHash + band-LSH — datasketch-compatible drop-in (no scipy).
+
+datasketch.lsh has `from scipy.integrate import quad` at module level.
+scipy's array_api_compat layer then lazily loads numpy.testing, which calls
+platform.machine() at import time to set test-skip decorator constants — and
+that in turn spawns cmd.exe via subprocess, hanging for minutes under EDR
+software in corporate Windows environments.
+
+Covers the exact MinHash/MinHashLSH API surface used by dedup.py.
+Hash family (Mersenne-prime permutations) and LSH band structure are
+equivalent to datasketch so dedup quality is unchanged.
+"""
+from __future__ import annotations
+import hashlib
+import struct
+
+import numpy as np
+
+
+_MP = np.uint64((1 << 61) - 1)  # Mersenne prime for the hash family
+_MH = np.uint64(0xFFFF_FFFF)    # mask to 32-bit values
+
+# One (a, b) coefficient array per num_perm, shared across all instances.
+_MH_COEFFS: dict[int, tuple[np.ndarray, np.ndarray]] = {}
+
+
+def _mh_coeffs(num_perm: int) -> tuple[np.ndarray, np.ndarray]:
+    if num_perm not in _MH_COEFFS:
+        rng = np.random.RandomState(1)
+        a = rng.randint(1, int(_MP), num_perm, dtype=np.uint64)
+        b = rng.randint(0, int(_MP), num_perm, dtype=np.uint64)
+        _MH_COEFFS[num_perm] = (a, b)
+    return _MH_COEFFS[num_perm]
+
+
+class MinHash:
+    """MinHash sketch — same API as datasketch.MinHash for the subset used here."""
+
+    __slots__ = ("num_perm", "hashvalues", "_a", "_b")
+
+    def __init__(self, num_perm: int = 128) -> None:
+        self.num_perm = num_perm
+        self.hashvalues = np.full(num_perm, int(_MH), dtype=np.uint64)
+        self._a, self._b = _mh_coeffs(num_perm)
+
+    def update(self, v: bytes) -> None:
+        hv = np.uint64(struct.unpack("<I", hashlib.sha1(v).digest()[:4])[0])
+        phv = np.bitwise_and((self._a * hv + self._b) % _MP, _MH)
+        self.hashvalues = np.minimum(self.hashvalues, phv)
+
+
+def _lsh_integrate(f, lo: float, hi: float, n: int = 128) -> float:
+    """Numerical integration — replaces scipy.integrate.quad for LSH param search."""
+    h = (hi - lo) / n
+    return h * sum(f(lo + i * h) for i in range(n))
+
+
+_LSH_PARAMS_CACHE: dict[tuple[float, int], tuple[int, int]] = {}
+
+
+def _optimal_lsh_params(threshold: float, num_perm: int) -> tuple[int, int]:
+    """Find (bands, rows) that minimise weighted FP+FN error, without scipy."""
+    key = (threshold, num_perm)
+    if key in _LSH_PARAMS_CACHE:
+        return _LSH_PARAMS_CACHE[key]
+    best_err, best = float("inf"), (1, 1)
+    for b in range(1, num_perm + 1):
+        for r in range(1, num_perm // b + 1):
+            fp = _lsh_integrate(
+                lambda s, _b=float(b), _r=float(r): 1 - (1 - s ** _r) ** _b,
+                0.0, threshold,
+            )
+            fn = _lsh_integrate(
+                lambda s, _b=float(b), _r=float(r): 1 - (1 - (1 - s ** _r) ** _b),
+                threshold, 1.0,
+            )
+            err = 0.5 * fp + 0.5 * fn
+            if err < best_err:
+                best_err, best = err, (b, r)
+    _LSH_PARAMS_CACHE[key] = best
+    return best
+
+
+class MinHashLSH:
+    """Band-hashing LSH — same API as datasketch.MinHashLSH for the subset used here."""
+
+    def __init__(self, threshold: float = 0.5, num_perm: int = 128) -> None:
+        self.b, self.r = _optimal_lsh_params(threshold, num_perm)
+        self._tables: list[dict[bytes, list[str]]] = [{} for _ in range(self.b)]
+        self._keys: set[str] = set()
+
+    def insert(self, key: str, minhash: MinHash) -> None:
+        if key in self._keys:
+            raise ValueError(f"Key {key!r} already exists in MinHashLSH")
+        self._keys.add(key)
+        hv = minhash.hashvalues
+        for i, table in enumerate(self._tables):
+            band = hv[i * self.r : (i + 1) * self.r].tobytes()
+            table.setdefault(band, []).append(key)
+
+    def query(self, minhash: MinHash) -> list[str]:
+        hv = minhash.hashvalues
+        candidates: set[str] = set()
+        for i, table in enumerate(self._tables):
+            band = hv[i * self.r : (i + 1) * self.r].tobytes()
+            candidates.update(table.get(band, []))
+        return list(candidates)

graphify/affected.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+import unicodedata
+
+import networkx as nx
+
+
+DEFAULT_AFFECTED_RELATIONS = (
+    "calls",
+    "indirect_call",
+    "references",
+    "imports",
+    "imports_from",
+    # `import('…')` — emitted by the Svelte/Astro/Vue rescue passes and (since
+    # #2575) by plain JS/TS too. Omitting it made every dynamic import
+    # invisible to blast-radius traversal even where the edge WAS in the
+    # graph, and dynamic import is precisely how codebases break require
+    # cycles, so the missing edges sat under the most load-bearing modules.
+    "dynamic_import",
+    "re_exports",
+    "inherits",
+    "extends",
+    "implements",
+    "uses",
+    "mixes_in",
+    "embeds",
+    "requires",
+)
+
+
+@dataclass(frozen=True)
+class AffectedHit:
+    node_id: str
+    depth: int
+    via_relation: str
+    # The traversed edge's location — the actual call/import/reference SITE in
+    # this node's file, not the node's own definition line (#BUG1). Defaults keep
+    # existing constructors/tests working; None falls back to the node's def line.
+    via_file: "str | None" = None
+    via_location: "str | None" = None
+
+
+def _node_label(graph: nx.Graph, node_id: str) -> str:
+    data = graph.nodes[node_id]
+    return str(data.get("label") or node_id)
+
+
+def _format_location(data: dict) -> str:
+    source_file = data.get("source_file") or "-"
+    source_location = data.get("source_location")
+    if source_location:
+        return f"{source_file}:{source_location}"
+    return str(source_file)
+
+
+def _bare_name(label: str) -> str:
+    """Lowercased label with the callable decoration (trailing "()") removed."""
+    label = _normalize_label(label)
+    return label[:-2] if label.endswith("()") else label
+
+
+def _normalize_label(label: str) -> str:
+    return unicodedata.normalize("NFC", label).casefold()
+
+
+def _as_repo_relative(query: str, root: Path | None = None) -> str:
+    """Repo-relative form of a path query, for matching a stored `source_file`.
+
+    The graph stores repo-relative paths, so `./src/x.py` and
+    `/abs/repo/src/x.py` name the same file as `src/x.py` and yet matched
+    nothing. `affected` then printed an empty list and exited 0 — a blast-radius
+    tool answering "nothing depends on this" about a file with sixteen
+    dependents, and indistinguishable from a genuine zero or a typo.
+
+    An absolute path is anchored to `root` when given — the repo root derived
+    from the graph's own location — so a seed resolves regardless of the caller's
+    working directory (#2706: an absolute-path seed previously only matched when
+    cwd happened to be the analysed repo root, which no editor or script can
+    guarantee). `root` falls back to the current directory to preserve the prior
+    behaviour when a caller has no graph location to derive it from.
+
+    Non-path queries pass through unchanged: `Path("myFunc()").as_posix()` is
+    `"myFunc()"`, so label resolution is untouched. An absolute path rooted
+    outside `root` is left alone — no basename guessing.
+    """
+    path = Path(query)
+    if path.is_absolute():
+        anchor = root if root is not None else Path.cwd()
+        try:
+            return path.relative_to(anchor).as_posix()
+        except ValueError:
+            # Rooted outside the repo: nothing here can make it repo-relative,
+            # so leave it alone rather than guess at a basename that would match
+            # some unrelated file with the same name.
+            return query
+    return path.as_posix()
+
+
+def _prefer_file_node(
+    graph: nx.Graph,
+    node_ids: list[str],
+    query: str,
+) -> str | None:
+    """Return the file-level node when a source_file query matches many nodes."""
+    query_basename = _normalize_label(Path(query).name)
+    exact_file_nodes = [
+        node_id
+        for node_id in node_ids
+        if str(graph.nodes[node_id].get("source_location", "")) == "L1"
+        and _normalize_label(str(graph.nodes[node_id].get("label", ""))) == query_basename
+    ]
+    if len(exact_file_nodes) == 1:
+        return exact_file_nodes[0]
+
+    l1_nodes = [
+        node_id
+        for node_id in node_ids
+        if str(graph.nodes[node_id].get("source_location", "")) == "L1"
+    ]
+    if len(l1_nodes) == 1:
+        return l1_nodes[0]
+
+    basename_nodes = [
+        node_id
+        for node_id in node_ids
+        if _normalize_label(str(graph.nodes[node_id].get("label", ""))) == query_basename
+    ]
+    if len(basename_nodes) == 1:
+        return basename_nodes[0]
+
+    return None
+
+
+def resolve_seed(graph: nx.Graph, query: str, root: Path | None = None) -> str | None:
+    # A trailing path separator must not change a source-file match — serve's
+    # _find_node tokenizes the path (which drops it), so strip it here for parity
+    # (otherwise `affected "src/x.ts/"` returned None while `explain` resolved it).
+    query = query.rstrip("/\\") or query
+    if query in graph:
+        return query
+    query_lower = _normalize_label(query)
+    exact_label_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if _normalize_label(str(data.get("label", ""))) == query_lower
+    ]
+    if len(exact_label_matches) == 1:
+        return exact_label_matches[0]
+    # Callable labels are decorated ("name()"), so a bare "name" query falls
+    # through exact matching and then ties with any "name*" sibling in the
+    # contains pass. Match on the undecorated name before giving up.
+    query_bare = _bare_name(query_lower)
+    bare_name_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if _bare_name(str(data.get("label", ""))) == query_bare
+    ]
+    if len(bare_name_matches) == 1:
+        return bare_name_matches[0]
+    # Compare paths in repo-relative form. Only this branch is path-shaped; the
+    # label branches above keep the query verbatim.
+    query_path = _normalize_label(_as_repo_relative(query, root))
+    exact_source_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if _normalize_label(str(data.get("source_file", ""))) in (query_lower, query_path)
+    ]
+    if len(exact_source_matches) == 1:
+        return exact_source_matches[0]
+    if exact_source_matches:
+        preferred_file_node = _prefer_file_node(
+            graph, exact_source_matches, _as_repo_relative(query, root)
+        )
+        if preferred_file_node is not None:
+            return preferred_file_node
+    contains_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if query_lower in _normalize_label(str(data.get("label", "")))
+    ]
+    if len(contains_matches) == 1:
+        return contains_matches[0]
+    return None
+
+
+def affected_nodes(
+    graph: nx.Graph,
+    seed: str,
+    *,
+    relations: Iterable[str] = DEFAULT_AFFECTED_RELATIONS,
+    depth: int = 2,
+) -> list[AffectedHit]:
+    relation_set = set(relations)
+    seen = {seed}
+    queue: deque[tuple[str, int]] = deque([(seed, 0)])
+    hits: list[AffectedHit] = []
+
+    # #1669: seed the reverse walk with the root's own member nodes (one outward
+    # `method`/`contains` hop). A caller can bind to a class's method node rather
+    # than the class node itself (e.g. `Service.call` resolves to the `def
+    # self.call` node, #1634), so those callers are unreachable from the class
+    # otherwise. The member nodes are seeds only (not reported as hits), and
+    # `method`/`contains` stay out of the general relation-filtered walk, so this
+    # adds no forward noise anywhere else.
+    if hasattr(graph, "out_edges"):
+        member_edges = graph.out_edges(seed, data=True)
+    else:
+        member_edges = (
+            (s, t, d) for s, t, d in graph.edges(data=True) if s == seed
+        )
+    for _s, member, data in member_edges:
+        if str(data.get("relation", "")) not in ("method", "contains"):
+            continue
+        member = str(member)
+        if member not in seen:
+            seen.add(member)
+            queue.append((member, 0))
+
+    while queue:
+        current, current_depth = queue.popleft()
+        if current_depth >= depth:
+            continue
+        if hasattr(graph, "in_edges"):
+            incoming = graph.in_edges(current, data=True)
+        else:
+            incoming = (
+                (source, target, data)
+                for source, target, data in graph.edges(data=True)
+                if target == current
+            )
+        for source, _target, data in incoming:
+            relation = str(data.get("relation", ""))
+            if relation not in relation_set:
+                continue
+            source = str(source)
+            if source in seen:
+                continue
+            seen.add(source)
+            # Carry the matched edge's location (taken from the SAME edge dict
+            # whose relation passed the filter, so relation and location stay
+            # consistent) — that is the call/import/reference site in `source`'s
+            # own file, which is where the user should click (#BUG1).
+            hit = AffectedHit(
+                source, current_depth + 1, relation,
+                via_file=str(data.get("source_file") or "") or None,
+                via_location=str(data.get("source_location") or "") or None,
+            )
+            hits.append(hit)
+            queue.append((source, current_depth + 1))
+
+    return hits
+
+
+def format_affected(
+    graph: nx.Graph,
+    query: str,
+    *,
+    relations: Iterable[str] = DEFAULT_AFFECTED_RELATIONS,
+    depth: int = 2,
+    root: Path | None = None,
+) -> str:
+    relation_list = tuple(relations)
+    seed = resolve_seed(graph, query, root)
+    if seed is None:
+        return f"No unique node match for {query}"
+
+    hits = affected_nodes(graph, seed, relations=relation_list, depth=depth)
+    lines = [
+        f"Affected nodes for {_node_label(graph, seed)}",
+        f"Relations: {', '.join(relation_list)}",
+        f"Depth: {depth}",
+    ]
+    if not hits:
+        lines.append("No affected nodes found.")
+        return "\n".join(lines)
+
+    for hit in hits:
+        data = graph.nodes[hit.node_id]
+        if hit.via_location:
+            # The relation SITE in this node's file (call/import/reference line),
+            # labeled by [via_relation] so it's never mistaken for a def line.
+            location = f"{hit.via_file or data.get('source_file') or '-'}:{hit.via_location}"
+        else:
+            location = _format_location(data)  # honest fallback: the node's own def line
+        lines.append(
+            f"- {_node_label(graph, hit.node_id)} [{hit.via_relation}] {location}"
+        )
+    return "\n".join(lines)
+
+
+def load_graph(path: Path) -> nx.Graph:
+    import json
+    from networkx.readwrite import json_graph
+
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        raise RuntimeError(
+            f"Cannot read graph file {path}: {exc}. "
+            "Re-run 'graphify extract' to regenerate it."
+        ) from exc
+    # Force directed so stored caller→callee direction survives the round-trip;
+    # mirrors serve.py and __main__.py (#1174).
+    raw = {**raw, "directed": True}
+    # Normalize the edge key: graphify's `extract` output uses "edges" while
+    # networkx's node_link_data default is "links". Without this, an edges-keyed
+    # graph.json raises an uncaught KeyError: 'links' here — every other loader
+    # (__main__.py) already normalizes this (#738; same class as #1198).
+    if "links" not in raw and "edges" in raw:
+        raw = dict(raw, links=raw["edges"])
+    try:
+        return json_graph.node_link_graph(raw, edges="links")
+    except TypeError:
+        return json_graph.node_link_graph(raw)

graphify/always_on/agents-md.md

@@ -0,0 +1,12 @@
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

graphify/always_on/antigravity-rules.md

@@ -0,0 +1,14 @@
+---
+trigger: always_on
+description: Consult the graphify knowledge graph at graphify-out/ for codebase and architecture questions.
+---
+
+## graphify
+
+This project has a graphify knowledge graph at graphify-out/.
+
+Rules:
+- For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (CLI) or `query_graph` (MCP). Use `graphify path "<A>" "<B>"` / `shortest_path` for relationships and `graphify explain "<concept>"` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
+- If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context
+- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

graphify/always_on/claude-md.md

@@ -0,0 +1,9 @@
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

graphify/always_on/gemini-md.md

@@ -0,0 +1,9 @@
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

graphify/always_on/kiro-steering.md

@@ -0,0 +1,5 @@
+---
+inclusion: always
+---
+
+graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.

graphify/always_on/vscode-instructions.md

@@ -0,0 +1,17 @@
+## graphify
+
+For any question about this repo's architecture, structure, components, or how to add/modify/find
+code, your first action should be `graphify query "<question>"` when `graphify-out/graph.json`
+exists. Use `graphify path "<A>" "<B>"` for relationship questions and `graphify explain "<concept>"`
+for focused-concept questions. These return a scoped subgraph, usually much smaller than the full
+report or raw grep output.
+
+Triggers: "how do I…", "where is…", "what does … do", "add/modify a <component>",
+"explain the architecture", or anything that depends on how files or classes relate.
+
+If `graphify-out/wiki/index.md` exists, use it for broad navigation. Read `graphify-out/GRAPH_REPORT.md`
+only for broad architecture review or when query/path/explain do not surface enough context. Only read
+source files when (a) modifying/debugging specific code, (b) the graph lacks the needed detail, or
+(c) the graph is missing or stale.
+
+Type `/graphify` in Copilot Chat to build or update the graph.