graphitect 0.2.0__py3-none-any.whl

graphify/report.py

@@ -0,0 +1,346 @@
+# generate GRAPH_REPORT.md - the human-readable audit trail
+from __future__ import annotations
+import re
+from datetime import date
+from pathlib import Path
+import networkx as nx
+
+
+def _portable_root_label(root: str) -> str:
+    """Portable label for the report header — the project directory basename.
+
+    GRAPH_REPORT.md is a tracked artifact in practice, so its header must not
+    bake the generator host's absolute path into the file: the same graph would
+    otherwise produce different bytes on different machines and leak the build
+    machine's directory layout into git history (#2628, same class as #2598).
+
+    Taking the basename strips any leading absolute path without touching the
+    filesystem, and makes `graphify update .`, `graphify update ./proj`, and
+    `graphify update /abs/path/proj` all label the header `proj`. Only the
+    degenerate `.`/``/`..` cases need a cwd resolve to recover the real name;
+    if even that fails, fall back to the raw value.
+    """
+    raw = str(root).replace("\\", "/")
+    name = Path(raw).name
+    if name in ("", ".", ".."):
+        try:
+            name = Path(raw).resolve().name
+        except (OSError, RuntimeError):
+            name = ""
+    return name or raw
+
+
+def _safe_community_name(label: str) -> str:
+    """Mirrors export.safe_name so community hub filenames and report wikilinks always agree."""
+    cleaned = re.sub(r'[\\/*?:"<>|#^[\]]', "", label.replace("\r\n", " ").replace("\r", " ").replace("\n", " ")).strip()
+    cleaned = re.sub(r"\.(md|mdx|markdown)$", "", cleaned, flags=re.IGNORECASE)
+    return cleaned or "unnamed"
+
+
+def load_learning_for_report(graph_path) -> dict | None:
+    """Assemble the report's work-memory inputs from sibling artifacts.
+
+    Reads the ``.graphify_learning.json`` overlay (preferred sources) next to
+    ``graph_path`` and re-aggregates the memory docs for the query-scoped
+    dead-ends. Best-effort: returns None if neither is available, so the report
+    simply omits the section. Never raises.
+    """
+    from pathlib import Path as _Path
+    try:
+        gp = _Path(graph_path)
+        from graphify.reflect import load_learning_overlay, load_memory_docs, aggregate_lessons
+        overlay = load_learning_overlay(gp)
+        dead_ends: list[dict] = []
+        mem = gp.parent / "memory"
+        if mem.is_dir():
+            agg = aggregate_lessons(load_memory_docs(mem))
+            dead_ends = agg.get("dead_ends", [])
+        if not overlay and not dead_ends:
+            return None
+        return {"overlay": overlay, "dead_ends": dead_ends}
+    except Exception:
+        return None
+
+
+def _learning_section(lines: list, learning: dict | None, top_n: int = 10) -> None:
+    """Append the ``## Work-memory lessons`` section, or nothing when empty."""
+    if not learning:
+        return
+    overlay = learning.get("overlay") or {}
+    dead_ends = learning.get("dead_ends") or []
+    preferred = [
+        (nid, e) for nid, e in overlay.items()
+        if isinstance(e, dict) and e.get("status") == "preferred"
+    ]
+    # Most-corroborated first (uses desc), then by score, then id for stability.
+    preferred.sort(key=lambda kv: (-kv[1].get("uses", 0),
+                                   -float(kv[1].get("score", 0) or 0), kv[0]))
+    if not preferred and not dead_ends:
+        return
+    lines += ["", "## Work-memory lessons"]
+    if preferred:
+        lines += ["", "**Preferred sources** — corroborated by past sessions; start here."]
+        for nid, e in preferred[:top_n]:
+            label = e.get("label") or nid
+            stale = " _(code changed — re-verify)_" if e.get("stale") else ""
+            lines.append(f"- `{label}` ({e.get('uses', 0)}× useful, "
+                         f"score={e.get('score', 0)}){stale}")
+    if dead_ends:
+        lines += ["", "**Known dead ends** — questions that led nowhere; don't re-derive."]
+        for d in dead_ends:
+            nodes = ", ".join(f"`{n}`" for n in d.get("nodes", []))
+            lines.append(f"- \"{d.get('question', '')}\""
+                         + (f" -> {nodes}" if nodes else ""))
+
+
+def generate(
+    G: nx.Graph,
+    communities: dict[int, list[str]],
+    cohesion_scores: dict[int, float],
+    community_labels: dict[int, str],
+    god_node_list: list[dict],
+    surprise_list: list[dict],
+    detection_result: dict,
+    token_cost: dict,
+    root: str,
+    suggested_questions: list[dict] | None = None,
+    min_community_size: int = 3,
+    built_at_commit: str | None = None,
+    learning: dict | None = None,
+    obsidian: bool = False,
+) -> str:
+    today = date.today().isoformat()
+
+    # JSON deserialization produces string keys; normalize to int so .get(cid) works.
+    if community_labels:
+        community_labels = {int(k) if isinstance(k, str) else k: v for k, v in community_labels.items()}
+
+    confidences = [d.get("confidence", "EXTRACTED") for _, _, d in G.edges(data=True)]
+    total = len(confidences) or 1
+    ext_pct = round(confidences.count("EXTRACTED") / total * 100)
+    inf_pct = round(confidences.count("INFERRED") / total * 100)
+    amb_pct = round(confidences.count("AMBIGUOUS") / total * 100)
+
+    inf_edges = [(u, v, d) for u, v, d in G.edges(data=True) if d.get("confidence") == "INFERRED"]
+    inf_scores = [d.get("confidence_score", 0.5) for _, _, d in inf_edges]
+    inf_avg = round(sum(inf_scores) / len(inf_scores), 2) if inf_scores else None
+
+    lines = [
+        f"# Graph Report - {_portable_root_label(root)}  ({today})",
+        "",
+        "## Corpus Check",
+    ]
+    if detection_result.get("warning"):
+        lines.append(f"- {detection_result['warning']}")
+    else:
+        lines += [
+            f"- {detection_result['total_files']} files · ~{detection_result['total_words']:,} words",
+            "- Verdict: corpus is large enough that graph structure adds value.",
+        ]
+
+    from .analyze import _is_file_node as _ifn
+
+    def _real_count(nodes) -> int:
+        return sum(1 for n in nodes if not _ifn(G, n))
+
+    non_empty = {cid: nodes for cid, nodes in communities.items()
+                 if any(not _ifn(G, n) for n in nodes)}
+    # One predicate for every figure the report prints about itself (#3148):
+    # "thin" is 0 < real < min_community_size, and "shown" is what the render
+    # loop below actually renders (real >= min_community_size) - previously
+    # shown was total-thin, which also counted communities with ZERO real
+    # nodes that the loop skips, overstating the count (#2129's residual).
+    thin_count_summary = sum(
+        1 for nodes in communities.values()
+        if 0 < _real_count(nodes) < min_community_size
+    )
+    shown_count = sum(
+        1 for nodes in communities.values()
+        if _real_count(nodes) >= min_community_size
+    )
+
+    lines += [
+        "",
+        "## Summary",
+        f"- {G.number_of_nodes()} nodes · {G.number_of_edges()} edges · {len(communities)} communities"
+        + (f" ({shown_count} shown, {thin_count_summary} thin omitted)" if thin_count_summary else ""),
+        f"- Extraction: {ext_pct}% EXTRACTED · {inf_pct}% INFERRED · {amb_pct}% AMBIGUOUS"
+        + (f" · INFERRED: {len(inf_edges)} edges (avg confidence: {inf_avg})" if inf_avg is not None else ""),
+        f"- Token cost: {token_cost.get('input', 0):,} input · {token_cost.get('output', 0):,} output",
+    ]
+
+    if built_at_commit:
+        lines += [
+            "",
+            "## Graph Freshness",
+            f"- Built from commit: `{built_at_commit[:8]}`",
+            "- Run `git rev-parse HEAD` and compare to check if the graph is stale.",
+            "- Run `graphify update .` after code changes (no API cost).",
+        ]
+
+    # Community hub navigation. The `_COMMUNITY_*.md` notes these wikilinks target
+    # are only created by the opt-in `--obsidian` export, and the report is written
+    # at build time (before any export runs), so emitting wikilinks by default left
+    # every link dangling — polluting an Obsidian vault's graph view and rendering as
+    # literal brackets everywhere else (#1712). Emit wikilinks only when the caller
+    # signals Obsidian output; otherwise a plain list, which navigates nowhere-to-break.
+    if non_empty:
+        lines += ["", "## Community Hubs (Navigation)"]
+        for cid in non_empty:
+            label = community_labels.get(cid, f"Community {cid}")
+            if obsidian:
+                safe = _safe_community_name(label)
+                lines.append(f"- [[_COMMUNITY_{safe}|{label}]]")
+            else:
+                lines.append(f"- {label}")
+
+    lines += [
+        "",
+        "## God Nodes (most connected - your core abstractions)",
+    ]
+    for i, node in enumerate(god_node_list, 1):
+        lines.append(f"{i}. `{node['label']}` - {node['degree']} edges")
+
+    lines += ["", "## Surprising Connections (you probably didn't know these)"]
+    if surprise_list:
+        for s in surprise_list:
+            relation = s.get("relation", "related_to")
+            note = s.get("note", "")
+            files = s.get("source_files", ["", ""])
+            conf = s.get("confidence", "EXTRACTED")
+            cscore = s.get("confidence_score")
+            if conf == "INFERRED" and cscore is not None:
+                conf_tag = f"INFERRED {cscore:.2f}"
+            else:
+                conf_tag = conf
+            sem_tag = " [semantically similar]" if relation == "semantically_similar_to" else ""
+            lines += [
+                f"- `{s['source']}` --{relation}--> `{s['target']}`  [{conf_tag}]{sem_tag}",
+                f"  {files[0]} → {files[1]}" + (f"  _{note}_" if note else ""),
+            ]
+    else:
+        lines.append("- None detected - all connections are within the same source files.")
+
+    # Circular imports surfaced from file-level dependency graph. Only meaningful
+    # for code — a documents-only corpus has no imports, so the section is pure
+    # noise there ("None detected" on every run). Emit it only when the graph
+    # actually contains code (#1657).
+    _has_code = any(
+        d.get("file_type") == "code" for _, d in G.nodes(data=True)
+    ) or any(
+        d.get("relation") in ("imports", "imports_from")
+        for *_e, d in G.edges(data=True)
+    )
+    if _has_code:
+        from .analyze import find_import_cycles
+        cycles = find_import_cycles(G)
+        lines += ["", "## Import Cycles"]
+        if cycles:
+            for c in cycles:
+                cycle = c.get("cycle", [])
+                length = c.get("length", len(cycle))
+                if not cycle:
+                    continue
+                cycle_path = " -> ".join(cycle + [cycle[0]])
+                lines.append(f"- {length}-file cycle: `{cycle_path}`")
+        else:
+            lines.append("- None detected.")
+
+    hyperedges = G.graph.get("hyperedges", [])
+    if hyperedges:
+        lines += ["", "## Hyperedges (group relationships)"]
+        for h in hyperedges:
+            node_labels = ", ".join(h.get("nodes", []))
+            conf = h.get("confidence", "INFERRED")
+            cscore = h.get("confidence_score")
+            conf_tag = f"{conf} {cscore:.2f}" if cscore is not None else conf
+            lines.append(f"- **{h.get('label', h.get('id', ''))}** — {node_labels} [{conf_tag}]")
+
+    lines += ["", f"## Communities ({len(communities)} total, {thin_count_summary} thin omitted)"]
+    for cid, nodes in communities.items():
+        label = community_labels.get(cid, f"Community {cid}")
+        score = cohesion_scores.get(cid, 0.0)
+        # Filter method/function stubs from display - they're structural noise
+        real_nodes = [n for n in nodes if not _ifn(G, n)]
+        if not real_nodes:
+            continue
+        if len(real_nodes) < min_community_size:
+            continue
+        display = [G.nodes[n].get("label", n) for n in real_nodes[:8]]
+        suffix = f" (+{len(real_nodes)-8} more)" if len(real_nodes) > 8 else ""
+        lines += [
+            "",
+            f"### Community {cid} - \"{label}\"",
+            f"Cohesion: {score:.2f}",
+            f"Nodes ({len(real_nodes)}): {', '.join(display)}{suffix}",
+        ]
+
+    ambiguous = [(u, v, d) for u, v, d in G.edges(data=True) if d.get("confidence") == "AMBIGUOUS"]
+    if ambiguous:
+        lines += ["", "## Ambiguous Edges - Review These"]
+        for u, v, d in ambiguous:
+            ul = G.nodes[u].get("label", u)
+            vl = G.nodes[v].get("label", v)
+            lines += [
+                f"- `{ul}` → `{vl}`  [AMBIGUOUS]",
+                f"  {d.get('source_file', '')} · relation: {d.get('relation', 'unknown')}",
+            ]
+
+    # --- Gaps section ---
+    from .analyze import _is_file_node, _is_concept_node
+
+    isolated = [
+        n for n in G.nodes()
+        if G.degree(n) <= 1
+        and not _is_file_node(G, n)
+        and not _is_concept_node(G, n)
+        and G.nodes[n].get("file_type") != "rationale"
+    ]
+    # Same threshold the Summary and Communities headers used (#3148): this
+    # was a hardcoded 3, so with --min-community-size anything else the count
+    # here disagreed with the label text beside it, which already printed
+    # min_community_size.
+    thin_communities = {
+        cid: nodes for cid, nodes in communities.items()
+        if 0 < sum(1 for n in nodes if not _is_file_node(G, n)) < min_community_size
+    }
+    gap_count = len(isolated) + len(thin_communities)
+
+    if gap_count > 0 or amb_pct > 20:
+        lines += ["", "## Knowledge Gaps"]
+        if isolated:
+            isolated_labels = [G.nodes[n].get("label", n) for n in isolated[:5]]
+            suffix = f" (+{len(isolated)-5} more)" if len(isolated) > 5 else ""
+            raw_isolated = sum(1 for n in G.nodes() if G.degree(n) <= 1)
+            lines.append(f"- **{len(isolated)} isolated node(s):** {', '.join(f'`{l}`' for l in isolated_labels)}{suffix}")
+            lines.append(
+                "  These have ≤1 connection - possible missing edges or undocumented components. "
+                f"(Counts symbols only; {raw_isolated} node(s) total have ≤1 connection when "
+                "file, concept and rationale nodes are included.)"
+            )
+        if thin_communities:
+            lines.append(f"- **{len(thin_communities)} thin communities (<{min_community_size} nodes) omitted from report** — run `graphify query` to explore isolated nodes.")
+        if amb_pct > 20:
+            lines.append(f"- **High ambiguity: {amb_pct}% of edges are AMBIGUOUS.** Review the Ambiguous Edges section above.")
+
+    # --- Work-memory lessons (derived overlay) ---
+    # Preferred sources come from the .graphify_learning.json sidecar; the
+    # query-scoped dead-ends come from the reflect aggregate. Section omitted
+    # entirely when neither is present, so a graph with no work-memory is
+    # byte-identical to the pre-feature report.
+    _learning_section(lines, learning)
+
+    if suggested_questions:
+        lines += ["", "## Suggested Questions"]
+        no_signal = len(suggested_questions) == 1 and suggested_questions[0].get("type") == "no_signal"
+        if no_signal:
+            lines.append(f"_{suggested_questions[0]['why']}_")
+        else:
+            lines.append("_Questions this graph is uniquely positioned to answer:_")
+            lines.append("")
+            for q in suggested_questions:
+                if q.get("question"):
+                    lines.append(f"- **{q['question']}**")
+                    lines.append(f"  _{q['why']}_")
+
+    return "\n".join(lines)

graphify/resolver_registry.py

@@ -0,0 +1,85 @@
+"""Registry for cross-file, language-specific resolution passes.
+
+Some call/reference edges can only be resolved with language-specific knowledge
+(receiver typing, qualified member calls, framework conventions). Historically
+these ran as a hand-wired sequence of suffix-gated
+``if <lang>_paths: try: _resolve_<lang>(...)`` blocks at the tail of
+``extract.extract()``. That pattern is the de-facto extension point for
+per-language resolution; this module formalizes it so a new language plugs in by
+registering one ``LanguageResolver`` instead of editing ``extract()``'s body.
+
+This module deliberately knows nothing about any specific language — languages
+register themselves (see ``extract.py``), keeping the dependency direction one
+way (``extract`` → ``resolver_registry``) and this seam small and reviewable on
+its own, separate from the multi-thousand-line ``extract`` module.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+_LOG = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class LanguageResolver:
+    """One cross-file, language-specific resolution pass.
+
+    ``resolve`` has the signature ``(per_file, all_nodes, all_edges) -> None`` and
+    mutates ``all_nodes`` / ``all_edges`` in place, matching the existing
+    member-call resolvers. ``suffixes`` gates activation: the pass runs only when
+    the corpus contains at least one file with one of these extensions.
+    """
+
+    name: str
+    suffixes: frozenset
+    resolve: Callable
+
+
+# Module-level registry, populated by callers via register(). Ordered: resolvers
+# run in registration order, preserving any required sequencing between passes.
+_REGISTRY: list[LanguageResolver] = []
+
+
+def register(resolver: LanguageResolver) -> LanguageResolver:
+    """Append a resolver to the global registry and return it (for inline use)."""
+    _REGISTRY.append(resolver)
+    return resolver
+
+
+def registered_resolvers() -> list[LanguageResolver]:
+    """Return a copy of the registered resolvers, in registration order."""
+    return list(_REGISTRY)
+
+
+def run_language_resolvers(
+    paths: Sequence[Path],
+    per_file: list[dict],
+    all_nodes: list[dict],
+    all_edges: list[dict],
+    *,
+    resolvers: Sequence[LanguageResolver] | None = None,
+) -> None:
+    """Run every resolver whose suffix appears in ``paths``.
+
+    Behaviorally identical to the prior hand-wired sequence of suffix-gated,
+    try/except-wrapped passes: same activation rule (suffix present), same
+    failure handling (log a warning and continue to the next pass), same
+    execution order (registration order).
+
+    ``resolvers`` defaults to the global registry; tests pass an explicit list to
+    exercise the driver in isolation.
+    """
+    active = _REGISTRY if resolvers is None else resolvers
+    suffixes_present = {p.suffix for p in paths}
+    for resolver in active:
+        if not (resolver.suffixes & suffixes_present):
+            continue
+        try:
+            resolver.resolve(per_file, all_nodes, all_edges)
+        except Exception as exc:
+            _LOG.warning("%s resolution failed, skipping: %s", resolver.name, exc)

graphify/ruby_resolution.py

@@ -0,0 +1,242 @@
+"""Type-aware cross-file resolution for Ruby member calls.
+
+Ruby has no type annotations and reuses method names heavily, so resolving
+``obj.method()`` by globally-unique name is both lossy (drops on collision) and
+unsafe (can attach to the wrong same-named method). This resolver instead uses
+the receiver's *type*, inferred at extraction time from local
+``var = ClassName.new`` bindings and carried on each member-call raw_call as
+``receiver_type``.
+
+It resolves two shapes, both at EXTRACTED (1.0) confidence and only when the
+target is certain (single owning class, single owned method) — bail otherwise:
+
+  * ``Processor.new``          -> a ``calls`` edge to the ``Processor`` class
+  * ``p.run`` where ``p`` is a ``Processor`` -> a ``calls`` edge to ``Processor#run``
+
+Registered into graphify.resolver_registry and run by extract() after id
+disambiguation, so node ids and raw_call caller_nids are final.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+def _key(label: str) -> str:
+    """Normalize a class/method label to a comparison key (drop punctuation)."""
+    return re.sub(r"[^a-zA-Z0-9]+", "", str(label)).lower()
+
+
+# A Ruby class/module container node is labelled with a constant path, bare or
+# ``::``-qualified (``Processor``, ``Billing::Rounding``); methods end in ``()``
+# and files in ``.rb``. Lets us register method-less containers (a
+# ``Class.new(StandardError)`` error class, an empty module) that have no
+# `method` edge to be found by.
+_BARE_CONST_RE = re.compile(r"^[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*$")
+
+
+def _ruby_raw_calls(per_file: list[dict]) -> list[dict]:
+    calls: list[dict] = []
+    for result in per_file:
+        if not isinstance(result, dict):
+            continue
+        for rc in result.get("raw_calls", []):
+            if not isinstance(rc, dict):
+                continue
+            sf = str(rc.get("source_file", ""))
+            if sf.endswith((".rb", ".rake")):
+                calls.append(rc)
+    return calls
+
+
+def resolve_ruby_member_calls(
+    per_file: list[dict],
+    all_nodes: list[dict],
+    all_edges: list[dict],
+) -> None:
+    """Resolve Ruby ``Class.new`` and typed ``var.method`` calls by receiver type.
+
+    Purely additive: only emits edges the shared (name-based) call pass skips
+    because they are member calls. Each emission requires a single owning class
+    (god-node guard) so an ambiguous class name resolves to nothing rather than a
+    wrong edge.
+    """
+    node_by_id: dict[str, dict] = {n.get("id"): n for n in all_nodes}
+
+    # class label key -> [class node ids]; (class_node_id, method_key) -> method id
+    class_def_nids: dict[str, list[str]] = {}
+    method_index: dict[tuple[str, str], str] = {}
+    for e in all_edges:
+        if e.get("relation") != "method":
+            continue
+        src, tgt = e.get("source"), e.get("target")
+        cnode = node_by_id.get(src)
+        if cnode is not None:
+            clabel = str(cnode.get("label", ""))
+            class_def_nids.setdefault(_key(clabel), []).append(str(src))
+            # A nested/compact declaration labels the node fully qualified
+            # (`Billing::Processor`), but its receivers reference the bare last
+            # segment (`Processor.new`), so index that too — the unique-match
+            # guard below still bails on genuine collisions (#2302).
+            if "::" in clabel:
+                class_def_nids.setdefault(_key(clabel.split("::")[-1]), []).append(str(src))
+        tnode = node_by_id.get(tgt)
+        if tnode is not None:
+            method_name = str(tnode.get("label", "")).strip("()").lstrip(".")
+            method_index[(str(src), method_name)] = str(tgt)
+    # Also register class/module container nodes that own no `method` edge — a
+    # method-less `Class.new(StandardError)` or an empty module — so a constant
+    # receiver still resolves to a real node (#1640/#1634). External base stubs
+    # carry an empty source_file, so the `.rb` filter keeps them out.
+    for n in all_nodes:
+        nid = n.get("id")
+        sf = str(n.get("source_file", ""))
+        label = str(n.get("label", ""))
+        if nid and sf.endswith((".rb", ".rake")) and _BARE_CONST_RE.match(label):
+            class_def_nids.setdefault(_key(label), []).append(str(nid))
+            if "::" in label:
+                class_def_nids.setdefault(_key(label.split("::")[-1]), []).append(str(nid))
+    for k in list(class_def_nids):
+        class_def_nids[k] = sorted(set(class_def_nids[k]))
+
+    def _segment_path(label: str) -> list[str]:
+        return [s.strip().lower() for s in str(label).split("::") if s.strip()]
+
+    # Fully-qualified and last-segment views of the same definitions, for the
+    # scoped mixin lookup: `include Foo::Bar` must match a `Foo::Bar` label as a
+    # whole path, never just its tail.
+    fq_label_map: dict[tuple[str, ...], list[str]] = {}
+    last_segment_map: dict[str, list[str]] = {}
+    for nid in sorted({nid for nids in class_def_nids.values() for nid in nids}):
+        segs = _segment_path(str(node_by_id.get(nid, {}).get("label", "")))
+        if segs:
+            fq_label_map.setdefault(tuple(segs), []).append(nid)
+            last_segment_map.setdefault(segs[-1], []).append(nid)
+
+    existing_pairs = {(e.get("source"), e.get("target")) for e in all_edges}
+
+    def _unique_class(name: str) -> str | None:
+        nids = class_def_nids.get(_key(name), [])
+        return nids[0] if len(nids) == 1 else None
+
+    def _class_by_const_path(raw: str) -> str | None:
+        """Resolve a qualified constant receiver (``Billing::Processor``) to one class.
+
+        Matches on the constant path rather than its tail: a class qualifies when its
+        own label ends with the referenced segments, so ``Billing::Processor`` still
+        finds an ``App::Billing::Processor`` while ``ActiveRecord::Base`` no longer
+        binds to an unrelated ``Thing::Base`` (#3078). A leading ``::`` pins the
+        reference to top level, so it must match the label whole. Ambiguous, or
+        matching nothing in the corpus (the usual case for a framework constant) ->
+        no edge, never a guess.
+        """
+        segs = tuple(_segment_path(raw))
+        if not segs:
+            return None
+        if raw.strip().startswith("::"):
+            nids = fq_label_map.get(segs, [])
+            return nids[0] if len(nids) == 1 else None
+        hits = {nid for path, nids in fq_label_map.items()
+                if len(path) >= len(segs) and path[-len(segs):] == segs
+                for nid in nids}
+        return next(iter(hits)) if len(hits) == 1 else None
+
+    def _emit(caller: str, target: str, rc: dict[str, Any],
+              relation: str = "calls", context: str = "call") -> None:
+        if not caller or not target or caller == target:
+            return
+        if (caller, target) in existing_pairs:
+            return
+        existing_pairs.add((caller, target))
+        all_edges.append({
+            "source": caller,
+            "target": target,
+            "relation": relation,
+            "context": context,
+            "confidence": "EXTRACTED",
+            "confidence_score": 1.0,
+            "source_file": rc.get("source_file", ""),
+            "source_location": rc.get("source_location"),
+            "weight": 1.0,
+        })
+
+    # `include`/`extend`/`prepend <Const>` mixins (#1668): resolve the module
+    # reference lexically, the way Ruby constant lookup works (#2302) — try the
+    # reference under each enclosing scope of the including class, innermost
+    # first, then top level (a leading `::` pins it to top level). A qualified
+    # external like `ActiveSupport::Concern` matches no in-corpus path and
+    # produces no edge; an unqualified reference with no lexical match falls
+    # back to a globally unique last segment, under the same single-definition
+    # god-node guard. Ambiguous at any step -> bail, no wrong edge.
+    for rc in _ruby_raw_calls(per_file):
+        if not rc.get("is_mixin"):
+            continue
+        caller = str(rc.get("caller_nid", ""))
+        module_name = rc.get("callee")
+        if not caller or not module_name:
+            continue
+        raw_ref = str(module_name)
+        absolute = raw_ref.startswith("::")
+        ref_segs = _segment_path(raw_ref)
+        caller_node = node_by_id.get(caller)
+        caller_segs = [] if absolute else _segment_path(
+            str(caller_node.get("label", "")) if caller_node else "")
+        target: str | None = None
+        for i in range(len(caller_segs), -1, -1):
+            nids = fq_label_map.get(tuple(caller_segs[:i] + ref_segs), [])
+            if len(nids) == 1:
+                target = nids[0]
+                break
+            if len(nids) > 1:
+                break  # reopened/ambiguous definition: bail
+        if target is None and len(ref_segs) == 1 and not absolute:
+            nids = last_segment_map.get(ref_segs[0], [])
+            if len(nids) == 1:
+                target = nids[0]
+        if target is not None:
+            _emit(caller, target, rc, relation="mixes_in", context="mixin")
+
+    for rc in _ruby_raw_calls(per_file):
+        if not rc.get("is_member_call"):
+            continue
+        caller = str(rc.get("caller_nid", ""))
+        callee = rc.get("callee")
+        if not caller or not callee:
+            continue
+
+        # Constant receiver: `Processor.new` (instantiation) or `Service.call` /
+        # `Model.where` (singleton / class method). The bare method name would
+        # collide with unrelated same-named methods, so we resolve by the
+        # receiver's class under the single-owning-class god-node guard.
+        receiver = rc.get("receiver")
+        # `lstrip(":")` so a top-level-pinned `::Processor.call` is still recognised
+        # as a constant receiver now that the whole path is captured (#3078).
+        if receiver and str(receiver).lstrip(":")[:1].isupper():
+            recv_raw = str(receiver)
+            class_nid = (_class_by_const_path(recv_raw) if "::" in recv_raw
+                         else _unique_class(recv_raw))
+            if class_nid is not None:
+                if callee == "new":
+                    _emit(caller, class_nid, rc)
+                else:
+                    # Emit to the singleton/instance method the class owns
+                    # (`def self.call`, which the extractor indexes); otherwise
+                    # to the class node itself, so inherited/dynamic class methods
+                    # like ActiveRecord `where`/`find_by` still give correct
+                    # blast-radius. An ambiguous receiver bails to nothing.
+                    method_nid = method_index.get((class_nid, str(callee)))
+                    _emit(caller, method_nid or class_nid, rc)
+            continue
+
+        # `p.run` where p's type is known -> edge to that class's method.
+        receiver_type = rc.get("receiver_type")
+        if not receiver_type:
+            continue
+        class_nid = _unique_class(str(receiver_type))
+        if class_nid is None:
+            continue
+        method_nid = method_index.get((class_nid, str(callee)))
+        if method_nid is None:
+            continue
+        _emit(caller, method_nid, rc)