fix(markdown): honour dotted qualifiers and explicit relative cites in mention resolution

Three findings from the automated review of #3562, all reproduced:

A dotted span with a non-code extension (README.md, pyproject.toml) was classified as a
symbol because only CODE_EXTENSIONS was checked, and every dotted form was reduced to its
last segment, so time.sleep matched a repo's own sleep(). The dotted form now keeps its
whole chain, the file early-exit also checks DOC_EXTENSIONS, and a bare-name match must
carry every qualifier as an owner label or a segment or stem of its source path.

_match_cited_file used lstrip("./"), which strips characters, so a .github/... cite could
never match by suffix. The leading ./ and ../ segments are now stripped as segments, and
the suffix form also matches a root-level file.

An explicit ./ or ../ cite that escaped the corpus fell through to the suffix rule and
could land on an unrelated copy of the file. It now resolves relative to the document
only.

(cherry picked from commit 3f84e7f3e2)

graphify/extractors/markdown.py

@@ -6,7 +6,7 @@ import os
 import unicodedata
 
 from pathlib import Path
-from graphify.detect import CODE_EXTENSIONS
+from graphify.detect import CODE_EXTENSIONS, DOC_EXTENSIONS
 from graphify.extractors.base import _file_stem, _make_id
 from graphify.security import sanitize_metadata
 
@@ -27,7 +27,8 @@ _MD_CODE_SPAN_RE = re.compile(r'(?<!`)(`+)(?!`)(.+?)(?<!`)\1(?!`)')
 # (``src/pkg/mod.py::Widget::render``) names the defining file and a
 # ``::``-separated symbol chain, exactly as pytest node ids and cite-lint
 # citations do. A bare mention (``Widget``, ``render()``, ``pkg.Widget``) names
-# a symbol with no file evidence, so it resolves only on a unique match.
+# a symbol with no file evidence, so it resolves only on a unique match; the
+# dotted form keeps its qualifiers (``pkg``) as evidence the resolver checks.
 _MD_PATH_MENTION_RE = re.compile(
     r'^([A-Za-z0-9_./\-]+\.[A-Za-z0-9]+)::([A-Za-z_]\w*(?:::[A-Za-z_]\w*)*)(?:\(\))?$'
 )
@@ -257,10 +258,12 @@ def _code_span_mention(span: str) -> "tuple[str | None, list[str]] | None":
 
     Returns ``(path, names)``: ``path`` is the cited file for the
     ``path::Name`` form and None for a bare or dotted mention; ``names`` is the
-    symbol chain, outermost first. A trailing ``()`` is dropped from the last
-    name so ``render()`` and ``render`` cite the same symbol. Spans that read
-    as a file (``setup.py``), a shell command, an expression or prose are not
-    mentions and yield None.
+    symbol chain, outermost first, so ``pkg.sub.Widget`` yields
+    ``["pkg", "sub", "Widget"]`` and the resolver can hold the match to that
+    evidence. A trailing ``()`` is dropped from the last name so ``render()``
+    and ``render`` cite the same symbol. Spans that read as a file
+    (``setup.py``, ``README.md``), a shell command, an expression or prose are
+    not mentions and yield None.
     """
     text = span.strip()
     if not text or " " in text:
@@ -272,10 +275,14 @@ def _code_span_mention(span: str) -> "tuple[str | None, list[str]] | None":
     if not m:
         return None
     if "." in text:
-        # ``a.b.Name`` is a qualified symbol; ``setup.py`` is a file. A dotted
-        # span whose last segment is a code extension is the latter.
-        if "." + m.group(1) in CODE_EXTENSIONS:
+        # ``a.b.Name`` is a qualified symbol; ``setup.py`` and ``README.md``
+        # are files. A dotted span whose last segment is a code or document
+        # extension is the latter. Other file-like spans (``pyproject.toml``)
+        # classify as a mention and are rejected at resolution, where the
+        # qualifier ``pyproject`` matches no callable's file or owner.
+        if "." + m.group(1) in CODE_EXTENSIONS or "." + m.group(1) in DOC_EXTENSIONS:
             return None
+        return None, text.rstrip("()").split(".")
     return None, [m.group(1)]
 
 
@@ -311,7 +318,9 @@ def extract_markdown(path: Path) -> dict:
     edges: the symbol they cite lives in another file, so the match is made
     once every file is extracted and ids are final, by the
     ``markdown_mentions`` language resolver (see
-    ``graphify.markdown_resolution``). That pass emits
+    ``graphify.markdown_resolution``). The dotted form travels with its
+    qualifiers, which the resolver checks against the match's owners and
+    file path. That pass emits
     heading --references--> code symbol (page --references--> symbol for a
     mention above the first heading): EXTRACTED for the path-qualified form,
     INFERRED for a bare name that matches exactly one code symbol. The shared

graphify/markdown_resolution.py

@@ -25,8 +25,17 @@ to the code node that defines it:
   Only nodes the extractors marked ``_callable`` qualify, for the reason the
   indirect-call pass gives (#1566): a by-name match must land on a real
   function, method or class, never on a same-named data symbol such as a
-  JSON key. No tie-breaking: an ambiguous name is a guess, and a guess is
-  not an edge. The match is INFERRED (0.95, a named cross-file reference).
+  JSON key. A dotted mention (``pkg.Widget``, ``Widget.render``) keeps its
+  qualifiers, and a candidate survives only when every qualifier is a label
+  on its ``contains`` / ``method`` owner chain or a segment (or stem) of its
+  source path: ``time.sleep`` never lands on a repo's own ``sleep``, and
+  ``Widget.render`` picks the ``render`` that ``Widget`` owns. No other
+  tie-breaking: an ambiguous name is a guess, and a guess is not an edge.
+  The match is INFERRED (0.95, a named cross-file reference).
+
+An explicit relative cite (``./`` or ``../``) resolves against the document's
+directory only; it never falls through to the suffix rule, so a path that
+escapes the corpus cannot land on an unrelated copy of the file elsewhere.
 
 The shared cross-file call pass in ``extract`` skips ``markdown`` raw calls,
 so a mention never surfaces as a ``calls`` edge.
@@ -34,6 +43,7 @@ so a mention never surfaces as a ``calls`` edge.
 from __future__ import annotations
 
 import os
+import re
 from typing import Any
 
 from graphify.extractors.base import _LANGUAGE_BUILTIN_GLOBALS
@@ -42,6 +52,10 @@ MARKDOWN_MENTION_SUFFIXES = frozenset({".md", ".mdx", ".qmd", ".skill"})
 
 _CONTAINMENT_RELATIONS = frozenset({"contains", "method"})
 
+#: Leading ``./`` and ``../`` segments of a cited path, stripped as whole
+#: segments (``lstrip("./")`` would eat the dot of ``.github/...``).
+_RELATIVE_PREFIX_RE = re.compile(r"^(\.\.?/)+")
+
 
 def _symbol_label(node: dict[str, Any]) -> str:
     """A node's label as a document would write it: no ``()``, no leading dot."""
@@ -63,19 +77,56 @@ def _match_cited_file(cited: str, doc_file: str, source_files: set[str]) -> str
 
     Tries the path relative to the citing document first (``../src/mod.py``
     from ``docs/guide.md``), then an exact match, then a unique
-    segment-aligned suffix (``src/mod.py`` naming ``/repo/src/mod.py``).
+    segment-aligned suffix (``src/mod.py`` naming ``/repo/src/mod.py``). A
+    cite that is explicitly relative (``./x`` or ``../x``) stops after the
+    first step: it names one location, and a suffix match elsewhere would be a
+    different file.
     """
     cited_posix = _posix(cited)
     doc_dir = os.path.dirname(doc_file)
-    relative = _posix(os.path.normpath(os.path.join(doc_dir, cited)))
-    for candidate in (relative, cited_posix):
-        if candidate in source_files:
-            return candidate
-    suffix = "/" + cited_posix.lstrip("./")
-    matches = [sf for sf in source_files if sf.endswith(suffix)]
+    relative = _posix(os.path.normpath(os.path.join(doc_dir, cited_posix)))
+    if relative in source_files:
+        return relative
+    if cited_posix.startswith(("./", "../")):
+        return None
+    if cited_posix in source_files:
+        return cited_posix
+    stripped = _RELATIVE_PREFIX_RE.sub("", cited_posix)
+    matches = [sf for sf in source_files
+               if sf == stripped or sf.endswith("/" + stripped)]
     return matches[0] if len(matches) == 1 else None
 
 
+def _evidence(node_id: str, nodes_by_id: dict[str, dict[str, Any]],
+              parents: dict[str, set[str]]) -> set[str]:
+    """Labels a dotted mention may qualify ``node_id`` with.
+
+    The labels of every node on its ``contains`` / ``method`` owner chain
+    (``Widget`` for ``Widget.render``) plus each segment and stem of its
+    source path (``pkg`` and ``mod`` for ``pkg.mod.Widget``).
+    """
+    evidence: set[str] = set()
+    frontier = {node_id}
+    seen: set[str] = set()
+    while frontier:
+        nid = frontier.pop()
+        if nid in seen:
+            continue
+        seen.add(nid)
+        owners = parents.get(nid, set())
+        for owner in owners:
+            node = nodes_by_id.get(owner)
+            if node is not None:
+                evidence.add(_symbol_label(node))
+        frontier |= owners
+    node = nodes_by_id.get(node_id, {})
+    for segment in _posix(str(node.get("source_file", ""))).split("/"):
+        if segment:
+            evidence.add(segment)
+            evidence.add(os.path.splitext(segment)[0])
+    return evidence
+
+
 def _markdown_raw_calls(per_file: list[dict]) -> list[dict]:
     calls: list[dict] = []
     for result in per_file:
@@ -118,7 +169,8 @@ def resolve_markdown_mentions(
     for e in all_edges:
         if e.get("relation") in _CONTAINMENT_RELATIONS:
             parents.setdefault(str(e.get("target")), set()).add(str(e.get("source")))
-    node_ids = {n["id"] for n in all_nodes if n.get("id")}
+    nodes_by_id = {n["id"]: n for n in all_nodes if n.get("id")}
+    node_ids = set(nodes_by_id)
     existing = {
         (e.get("source"), e.get("target"))
         for e in all_edges if e.get("relation") == "references"
@@ -156,7 +208,11 @@ def resolve_markdown_mentions(
         else:
             if callee in _LANGUAGE_BUILTIN_GLOBALS:
                 continue
-            candidates = by_label.get(callee, [])
+            qualifiers = set(names[:-1])
+            candidates = [
+                c for c in by_label.get(callee, [])
+                if qualifiers <= _evidence(c, nodes_by_id, parents)
+            ]
             target = candidates[0] if len(candidates) == 1 else None
             confidence, score = "INFERRED", 0.95
         if target is None or target == caller or (caller, target) in existing:

tests/test_markdown_code_spans.py

@@ -8,11 +8,13 @@ resolver matches them against the merged corpus after the id-remap passes.
 """
 from __future__ import annotations
 
+import json
 import os
 from pathlib import Path
 
 from graphify.extract import extract
 from graphify.extractors.markdown import _code_span_mention, extract_markdown
+from graphify.markdown_resolution import _match_cited_file
 
 _WIDGET_PY = '''\
 class Widget:
@@ -81,15 +83,42 @@ def _references(r):
 def test_code_span_mentions_are_classified():
     assert _code_span_mention("Widget") == (None, ["Widget"])
     assert _code_span_mention("render()") == (None, ["render"])
-    assert _code_span_mention("pkg.sub.Widget") == (None, ["Widget"])
+    assert _code_span_mention("pkg.sub.Widget") == (None, ["pkg", "sub", "Widget"])
+    assert _code_span_mention("Widget.render()") == (None, ["Widget", "render"])
+    # A file-like span with an unknown extension classifies as a mention and
+    # is rejected at resolution, where `pyproject` matches no callable.
+    assert _code_span_mention("pyproject.toml") == (None, ["pyproject", "toml"])
     pinned = ("src/widget.py", ["Widget", "render"])
     assert _code_span_mention("src/widget.py::Widget::render") == pinned
     assert _code_span_mention("src/widget.py::Widget::render()") == pinned
     # Files, commands, expressions and prose are not symbol mentions.
-    for span in ("setup.py", "git revert", "x = 1", "a-b", "--flag", "", "src/widget.py"):
+    for span in ("setup.py", "README.md", "notes.txt", "git revert", "x = 1", "a-b",
+                 "--flag", "", "src/widget.py"):
         assert _code_span_mention(span) is None, span
 
 
+def test_cited_file_matching():
+    sources = {"src/mod.py", ".github/scripts/check.py", "lib/x.py", "vendor/lib/x.py",
+               "docs/src/mod.py"}
+    # Doc-relative first, then exact, then a unique segment-aligned suffix.
+    assert _match_cited_file("src/mod.py", "docs/guide.md", sources) == "docs/src/mod.py"
+    assert _match_cited_file("src/mod.py", "README.md", sources) == "src/mod.py"
+    assert _match_cited_file("mod.py", "README.md", sources) is None
+    assert _match_cited_file("scripts/check.py", "README.md", sources) == (
+        ".github/scripts/check.py")
+    # `./` and `../` are stripped as segments: a hidden directory keeps its dot.
+    assert _match_cited_file(".github/scripts/check.py", "docs/guide.md", sources) == (
+        ".github/scripts/check.py")
+    assert _match_cited_file("./src/mod.py", "README.md", sources) == "src/mod.py"
+    # The suffix form also names a root-level file.
+    assert _match_cited_file("lib/x.py", "docs/guide.md", {"lib/x.py"}) == "lib/x.py"
+    # An explicit relative cite resolves against the document only: escaping
+    # the corpus never falls through to another copy of the file.
+    assert _match_cited_file("../lib/x.py", "docs/guide.md", sources) == "lib/x.py"
+    assert _match_cited_file("../lib/x.py", "README.md", sources) is None
+    assert _match_cited_file("../../vendor/lib/x.py", "docs/guide.md", sources) is None
+
+
 def test_extract_markdown_reports_mentions_as_markdown_raw_calls(tmp_path):
     doc = tmp_path / "docs" / "guide.md"
     doc.parent.mkdir()
@@ -152,9 +181,11 @@ def test_mentions_resolve_to_references_edges_end_to_end(tmp_path):
     assert refs[(guide["id"], widget["id"])]["confidence"] == "INFERRED"
     assert refs[(guide["id"], widget["id"])]["confidence_score"] == 0.95
     assert (rendering["id"], widget["id"]) in refs
-    # Dotted `Widget.render()` resolves by its last segment: `render` is
-    # ambiguous (two classes define it), so no edge; same for `helper()`.
-    assert {t for (s, t) in refs if s == rendering["id"]} == {widget["id"]}
+    # `render` is defined twice, but the qualifier in `Widget.render()` names
+    # the owner, so the mention resolves; the bare `helper()` stays ambiguous.
+    assert {t for (s, t) in refs if s == rendering["id"]} == {
+        widget["id"], widget_render["id"]}
+    assert refs[(rendering["id"], widget_render["id"])]["confidence"] == "INFERRED"
     # Path-qualified mentions are EXTRACTED and scoped to the cited file.
     assert refs[(pinned["id"], widget_render["id"])]["confidence"] == "EXTRACTED"
     assert refs[(pinned["id"], widget_render["id"])]["confidence_score"] == 1.0
@@ -183,6 +214,27 @@ def test_ambiguous_bare_name_yields_no_edge(tmp_path):
     assert {t for (s, t) in _references(r) if s == notes["id"]} == set()
 
 
+def test_dotted_mentions_need_qualifier_evidence(tmp_path):
+    r = _extract(tmp_path, {
+        "src/widget.py": _WIDGET_PY + "\n\ndef sleep():\n    pass\n",
+        "src/gadget.py": _GADGET_PY + "\n\ndef toml():\n    pass\n",
+        "docs/notes.md": (
+            "# Notes\n\n"
+            "`time.sleep` and `pyproject.toml` are not this repo's sleep or toml.\n"
+            "`widget.Widget`, `src.gadget.Gadget` and `Widget.render` are.\n"
+            "`Gadget.helper` is not: `helper` is not owned by `Gadget`.\n"
+        ),
+    })
+
+    notes = _node(r, "Notes")
+    cited = {t for (s, t) in _references(r) if s == notes["id"]}
+    widget = _node(r, "Widget", "widget.py")
+    gadget = _node(r, "Gadget", "gadget.py")
+    widget_render = next(
+        n for n in r["nodes"] if n["label"] == ".render()" and "widget" in n["id"])
+    assert cited == {widget["id"], gadget["id"], widget_render["id"]}
+
+
 def test_mentions_survive_the_extraction_cache(tmp_path):
     files = {"src/widget.py": _WIDGET_PY, "docs/guide.md": _GUIDE_MD}
     first = _extract(tmp_path, files)