agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/knowledge/adr.py

@@ -0,0 +1,136 @@
+"""``ADRParser`` — parse an architecture decision record markdown file into a
+format-neutral ``ParsedADR`` (feat-010 MVP).
+
+Tolerant of MADR (YAML frontmatter), Nygard, and adr-tools layouts: read a
+frontmatter block if present, else scan headings/lines for the title, status,
+date, and supersedes link. A file that yields no recognisable ADR shape still
+becomes a ``Decision`` titled from its filename — degrade, never drop (spec §8).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+
+import yaml
+
+_STATUSES = {"proposed", "accepted", "superseded", "deprecated", "rejected"}
+_DATE_RE = re.compile(r"\b(\d{4}-\d{2}-\d{2})\b")
+# "Supersedes ADR-0007", "supersede 0007", "Superseded by ADR-0012"
+_SUPERSEDES_RE = re.compile(r"supersedes?\s+(?:adr-?)?(\d+)", re.IGNORECASE)
+_ADR_NUM_RE = re.compile(r"(\d+)")
+
+
+@dataclass
+class DocSection:
+    heading: str
+    text: str
+
+
+@dataclass
+class ParsedADR:
+    title: str
+    status: str = "proposed"
+    date: str = ""
+    adr_id: str = ""  # e.g. "ADR-0012" (from filename number or frontmatter)
+    supersedes_num: str = ""  # the numeric id of a superseded ADR, if any
+    body: str = ""
+    sections: list[DocSection] = field(default_factory=list)
+    well_formed: bool = True  # False → fell back to filename title
+
+
+def _split_frontmatter(text: str) -> tuple[dict[str, object], str]:
+    if not text.startswith("---"):
+        return {}, text
+    parts = text.split("\n", 1)
+    rest = parts[1] if len(parts) > 1 else ""
+    end = rest.find("\n---")
+    if end == -1:
+        return {}, text
+    block = rest[:end]
+    remainder = rest[end + len("\n---") :].lstrip("\n")
+    try:
+        data = yaml.safe_load(block)
+    except yaml.YAMLError:
+        return {}, text
+    return (data if isinstance(data, dict) else {}), remainder
+
+
+def _sections(body: str) -> list[DocSection]:
+    sections: list[DocSection] = []
+    heading = ""
+    buf: list[str] = []
+    for line in body.splitlines():
+        if line.startswith("#"):
+            if buf or heading:
+                sections.append(DocSection(heading=heading, text="\n".join(buf).strip()))
+            heading = line.lstrip("#").strip()
+            buf = []
+        else:
+            buf.append(line)
+    if buf or heading:
+        sections.append(DocSection(heading=heading, text="\n".join(buf).strip()))
+    return [s for s in sections if s.text or s.heading]
+
+
+def _first_heading_title(body: str) -> str:
+    for line in body.splitlines():
+        s = line.strip()
+        if s.startswith("#"):
+            return s.lstrip("#").strip()
+    return ""
+
+
+def _status_from(text: str) -> str:
+    # a "Status: accepted" line, a "## Status\naccepted" section, or a bare word
+    for raw in text.splitlines():
+        low = raw.strip().lower().lstrip("#").strip()
+        low = low.removeprefix("status:").strip()
+        for token in re.split(r"[\s,]+", low):
+            if token in _STATUSES:
+                return token
+    return ""
+
+
+class ADRParser:
+    name = "adr-parser"
+
+    def parse(self, path: str, text: str) -> ParsedADR:
+        fm, body = _split_frontmatter(text)
+        stem = PurePosixPath(path).stem
+        num_match = _ADR_NUM_RE.search(stem)
+        adr_id = f"ADR-{int(num_match.group(1)):04d}" if num_match else ""
+
+        title = str(fm.get("title") or _first_heading_title(body) or "").strip()
+        well_formed = bool(title)
+        if not title:
+            title = stem.replace("-", " ").replace("_", " ").strip() or path
+
+        status = str(fm.get("status") or "").strip().lower() or _status_from(body)
+        status = status if status in _STATUSES else "proposed"
+
+        date = str(fm.get("date") or "").strip()
+        if not date:
+            m = _DATE_RE.search(body)
+            date = m.group(1) if m else ""
+
+        supersedes_num = ""
+        fm_sup = fm.get("superseded-by") or fm.get("supersedes")
+        if fm_sup:
+            m = _ADR_NUM_RE.search(str(fm_sup))
+            supersedes_num = str(int(m.group(1))) if m else ""
+        if not supersedes_num:
+            m = _SUPERSEDES_RE.search(body)
+            supersedes_num = str(int(m.group(1))) if m else ""
+
+        return ParsedADR(
+            title=title,
+            status=status,
+            date=date,
+            adr_id=adr_id,
+            supersedes_num=supersedes_num,
+            body=body,
+            sections=_sections(body),
+            well_formed=well_formed,
+        )

agentforge_graph/knowledge/commits.py

@@ -0,0 +1,152 @@
+"""``CommitIngestor`` — turn meaningful git commit messages into graph facts
+(feat-010 follow-up).
+
+A commit whose subject is a *conventional commit* (``feat:`` / ``fix:`` / …) or
+carries an *issue reference* (``#123`` / ``PROJ-45``) is high-signal: it records
+*why* a change was made. We ingest the subjects of the last ``limit`` such commits
+as ``DocChunk``s that ``DESCRIBES`` the in-repo files they touched — so "why did
+the retry logic change?" can reach the commit and the code it touched.
+
+Git is read via ``git log`` (subprocess; no ``agentforge`` import — the knowledge
+package stays deterministic, ADR-0001). Commit chunks are keyed by sha and added
+idempotently (a re-index skips shas already present); they are immutable, so there
+is no per-file GC.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import subprocess
+from pathlib import Path
+
+from agentforge_graph.core import (
+    Edge,
+    EdgeKind,
+    GraphQuery,
+    GraphStore,
+    Node,
+    NodeKind,
+    Provenance,
+    SymbolID,
+)
+
+_ALL = 10_000_000
+_DOC_LANG = "doc"
+_COMMITS_PATH = "<commits>"  # synthetic SymbolID path namespace for commit chunks
+_RS = "\x1e"  # record separator between commits
+_US = "\x1f"  # field separator within a commit's header line
+
+# conventional commit: `type(scope)?!: summary`
+_CONVENTIONAL = re.compile(
+    r"^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]*\))?!?:",
+    re.IGNORECASE,
+)
+# an issue reference: `#123` or `PROJ-45`
+_ISSUE_REF = re.compile(r"(#\d+|\b[A-Z][A-Z0-9]+-\d+\b)")
+
+
+def _qualifies(subject: str) -> bool:
+    return bool(_CONVENTIONAL.match(subject.strip()) or _ISSUE_REF.search(subject))
+
+
+class CommitIngestor:
+    def __init__(self, repo: str, root: str | Path, commit: str = "", limit: int = 50) -> None:
+        self.repo = repo
+        self.root = str(root)
+        self.commit = commit
+        self.limit = max(1, limit)
+
+    async def ingest(self, store: GraphStore) -> int:
+        commits = self._git_log()
+        if not commits:
+            return 0
+        path_index = await self._path_index(store)
+        existing = await self._existing_shas(store)
+        prov = Provenance.parsed("commit-ingestor", self.commit)
+        facts: list[Node | Edge] = []
+        count = 0
+        for sha, ts, author, subject, files in commits:
+            if sha in existing or not _qualifies(subject):
+                continue
+            targets = [path_index[f] for f in files if f in path_index]
+            if not targets:  # touched no in-repo code → nothing to describe
+                continue
+            chunk_id = SymbolID.for_symbol(
+                _DOC_LANG, self.repo, _COMMITS_PATH, f"commit({sha[:12]})."
+            )
+            facts.append(
+                Node(
+                    id=chunk_id,
+                    kind=NodeKind.DOC_CHUNK,
+                    name=subject[:80],
+                    attrs={
+                        "path": _COMMITS_PATH,
+                        "heading": subject[:80],
+                        "text": subject,
+                        "doc_source": "commit",
+                        "commit": sha,
+                        "author": author,
+                        "ts": ts,
+                        "content_hash": hashlib.sha256(f"{sha}:{subject}".encode()).hexdigest(),
+                    },
+                    provenance=prov,
+                )
+            )
+            for target in sorted(set(targets)):
+                facts.append(
+                    Edge(src=chunk_id, dst=target, kind=EdgeKind.DESCRIBES, provenance=prov)
+                )
+            count += 1
+        if facts:
+            await store.add(facts)
+        return count
+
+    async def _path_index(self, store: GraphStore) -> dict[str, str]:
+        return {
+            SymbolID.parse(n.id).path: n.id
+            for n in (await store.query(GraphQuery(kinds=[NodeKind.FILE], limit=_ALL))).nodes
+        }
+
+    async def _existing_shas(self, store: GraphStore) -> set[str]:
+        nodes = (await store.query(GraphQuery(kinds=[NodeKind.DOC_CHUNK], limit=_ALL))).nodes
+        return {
+            str(n.attrs.get("commit", "")) for n in nodes if n.attrs.get("doc_source") == "commit"
+        }
+
+    def _git_log(self) -> list[tuple[str, int, str, str, list[str]]]:
+        """Last ``limit`` non-merge commits as (sha, author_ts, author, subject,
+        touched files). Subject-only keeps the ``--name-only`` parse unambiguous;
+        full-body ingestion is a refinement."""
+        try:
+            out = subprocess.run(
+                [
+                    "git",
+                    "-C",
+                    self.root,
+                    "log",
+                    f"-n{self.limit}",
+                    "--no-merges",
+                    "--no-color",
+                    "--name-only",
+                    f"--format={_RS}%H{_US}%ct{_US}%an{_US}%s",
+                ],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+        except (subprocess.SubprocessError, OSError):
+            return []
+        commits: list[tuple[str, int, str, str, list[str]]] = []
+        for block in out.stdout.split(_RS):
+            block = block.strip("\n")
+            if not block:
+                continue
+            head, _, rest = block.partition("\n")
+            parts = head.split(_US)
+            if len(parts) < 4:
+                continue
+            sha, ts_s, author, subject = parts[0], parts[1], parts[2], parts[3]
+            files = [ln for ln in rest.splitlines() if ln.strip()]
+            commits.append((sha, int(ts_s) if ts_s.isdigit() else 0, author, subject, files))
+        return commits

agentforge_graph/knowledge/ingest.py

@@ -0,0 +1,312 @@
+"""``KnowledgeIngestor`` — turn ADR markdown into graph facts (feat-010 MVP).
+
+Each ADR becomes its own ``FileSubgraph`` keyed by its path: a ``Decision``
+node, body ``DocChunk`` nodes (``CONTAINS``-linked; not embedded at MVP),
+``GOVERNS`` edges to the code it unambiguously mentions, and a ``SUPERSEDES``
+edge to the ADR it replaces. Upserting per ADR means edits/deletes ride the
+store's per-file machinery (feat-004) with no ChangeDetector change. Runs after
+code indexing so the mention indices see current code; re-runs each index, and
+GCs decisions whose ADR file is gone.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+from agentforge_graph.core import (
+    Edge,
+    EdgeKind,
+    FileSubgraph,
+    GraphQuery,
+    GraphStore,
+    Node,
+    NodeKind,
+    Provenance,
+    SymbolID,
+)
+from agentforge_graph.core.symbols import normalize_path
+
+from .adr import ADRParser, _sections
+from .mentions import extract_mentions, resolve_mentions
+from .report import KnowledgeStats
+
+_ALL = 10_000_000
+_DOC_LANG = "doc"  # SymbolID lang slug — keeps decision ids in their own namespace
+_SYMBOL_KINDS = {NodeKind.CLASS, NodeKind.FUNCTION, NodeKind.METHOD}
+_NUM_RE = re.compile(r"(\d+)")
+
+
+class KnowledgeIngestor:
+    def __init__(self, repo: str, commit: str = "") -> None:
+        self.repo = repo
+        self.commit = commit
+        self.parser = ADRParser()
+
+    async def ingest(
+        self,
+        store: GraphStore,
+        repo_path: str | Path,
+        adr_globs: list[str],
+        code_exts: set[str],
+        doc_globs: list[str] | None = None,
+    ) -> KnowledgeStats:
+        root = Path(repo_path)
+        files = self._discover(root, adr_globs)
+        adr_paths = {rel for rel, _ in files}
+
+        # GC decisions whose ADR file vanished
+        for path in await self._existing_decision_paths(store):
+            if path not in adr_paths:
+                await store.delete_file(path)
+
+        stats = KnowledgeStats()
+        doc_globs = doc_globs or []
+        # both the ADR and the general-doc passes need the code indices, and the
+        # doc pass must still run (to GC vanished docs) even when there are no ADRs.
+        if not files and not doc_globs:
+            return stats
+
+        path_index, name_index = await self._code_indices(store)
+
+        if files:
+            num_to_decision = {self._adr_num(rel): self._decision_id(rel) for rel, _ in files}
+            prov = Provenance.parsed(self.parser.name, self.commit)
+            built: list[tuple[FileSubgraph, bool]] = []
+            for rel, text in files:
+                sg, has_supersedes, resolved, unresolved = self._build(
+                    rel, text, prov, path_index, name_index, num_to_decision, code_exts
+                )
+                built.append((sg, has_supersedes))
+                stats.decisions_indexed += 1
+                stats.governs_resolved += resolved
+                stats.mentions_unresolved += unresolved
+            # round A: land every Decision/DocChunk/GOVERNS (no SUPERSEDES yet)
+            for sg, _ in built:
+                await store.upsert(self._without(sg, EdgeKind.SUPERSEDES))
+            # round B: re-upsert ADRs that supersede, now that all Decisions exist
+            for sg, has_supersedes in built:
+                if has_supersedes:
+                    await store.upsert(sg)
+
+        if doc_globs:
+            await self._ingest_docs(
+                store, root, doc_globs, adr_paths, path_index, name_index, code_exts, stats
+            )
+        return stats
+
+    # --- discovery & indices ---------------------------------------------
+
+    # Index/landing/template pages that live under the ADR globs but are not
+    # decisions (BUG-003).
+    _NON_ADR_STEMS = {"readme", "index", "template", "_template", "0000-template"}
+
+    @classmethod
+    def _discover(cls, root: Path, adr_globs: list[str]) -> list[tuple[str, str]]:
+        seen: dict[str, str] = {}
+        for pattern in adr_globs:
+            for path in sorted(root.glob(pattern)):
+                if not path.is_file() or path.stem.lower() in cls._NON_ADR_STEMS:
+                    continue
+                rel = path.relative_to(root).as_posix()
+                if rel not in seen:
+                    seen[rel] = path.read_text(encoding="utf-8", errors="replace")
+        return sorted(seen.items())
+
+    async def _existing_decision_paths(self, store: GraphStore) -> set[str]:
+        nodes = (await store.query(GraphQuery(kinds=[NodeKind.DECISION], limit=_ALL))).nodes
+        return {SymbolID.parse(n.id).path for n in nodes}
+
+    async def _code_indices(self, store: GraphStore) -> tuple[dict[str, str], dict[str, list[str]]]:
+        path_index: dict[str, str] = {}
+        name_index: dict[str, list[str]] = {}
+        for n in (await store.query(GraphQuery(limit=_ALL))).nodes:
+            if n.kind is NodeKind.FILE:
+                path_index[SymbolID.parse(n.id).path] = n.id
+            elif n.kind in _SYMBOL_KINDS:
+                name_index.setdefault(n.name, []).append(n.id)
+        return path_index, name_index
+
+    # --- building one ADR subgraph ---------------------------------------
+
+    def _decision_id(self, rel: str) -> str:
+        return SymbolID.for_symbol(_DOC_LANG, self.repo, rel, "decision.")
+
+    @staticmethod
+    def _adr_num(rel: str) -> str:
+        m = _NUM_RE.search(Path(rel).stem)
+        return str(int(m.group(1))) if m else ""
+
+    def _build(
+        self,
+        rel: str,
+        text: str,
+        prov: Provenance,
+        path_index: dict[str, str],
+        name_index: dict[str, list[str]],
+        num_to_decision: dict[str, str],
+        code_exts: set[str],
+    ) -> tuple[FileSubgraph, bool, int, int]:
+        adr = self.parser.parse(rel, text)
+        decision_id = self._decision_id(rel)
+        nodes: list[Node] = [
+            Node(
+                id=decision_id,
+                kind=NodeKind.DECISION,
+                name=adr.title,
+                attrs={
+                    "title": adr.title,
+                    "status": adr.status,
+                    "date": adr.date,
+                    "adr_id": adr.adr_id,
+                    "path": normalize_path(rel),
+                    "well_formed": adr.well_formed,
+                },
+                provenance=prov,
+            )
+        ]
+        edges: list[Edge] = []
+        for i, section in enumerate(adr.sections):
+            chunk_id = SymbolID.for_symbol(_DOC_LANG, self.repo, rel, f"docchunk({i}).")
+            nodes.append(
+                Node(
+                    id=chunk_id,
+                    kind=NodeKind.DOC_CHUNK,
+                    name=section.heading or f"section{i}",
+                    attrs={
+                        "path": normalize_path(rel),
+                        "heading": section.heading,
+                        "text": section.text,
+                        "seq": i,
+                        # hash of the embeddable text (heading + body) — lets the
+                        # embed pass detect changed doc chunks (feat-010 follow-up).
+                        "content_hash": hashlib.sha256(
+                            f"{section.heading}\n{section.text}".encode()
+                        ).hexdigest(),
+                    },
+                    provenance=prov,
+                )
+            )
+            edges.append(
+                Edge(src=decision_id, dst=chunk_id, kind=EdgeKind.CONTAINS, provenance=prov)
+            )
+
+        mentions = extract_mentions(adr.body, code_exts)
+        targets, unresolved = resolve_mentions(mentions, path_index, name_index)
+        for target in sorted(targets):
+            edges.append(Edge(src=decision_id, dst=target, kind=EdgeKind.GOVERNS, provenance=prov))
+
+        has_supersedes = False
+        if adr.supersedes_num and adr.supersedes_num in num_to_decision:
+            superseded = num_to_decision[adr.supersedes_num]
+            if superseded != decision_id:
+                edges.append(
+                    Edge(
+                        src=decision_id,
+                        dst=superseded,
+                        kind=EdgeKind.SUPERSEDES,
+                        provenance=prov,
+                    )
+                )
+                has_supersedes = True
+
+        content_hash = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        sg = FileSubgraph(path=rel, content_hash=content_hash, nodes=nodes, edges=edges)
+        return sg, has_supersedes, len(targets), unresolved
+
+    @staticmethod
+    def _without(sg: FileSubgraph, kind: EdgeKind) -> FileSubgraph:
+        return sg.model_copy(update={"edges": [e for e in sg.edges if e.kind is not kind]})
+
+    # --- general docs (doc_globs) ----------------------------------------
+
+    @classmethod
+    def _discover_docs(
+        cls, root: Path, doc_globs: list[str], adr_paths: set[str]
+    ) -> list[tuple[str, str]]:
+        """Markdown docs under ``doc_globs``, minus files already ingested as ADRs.
+        Unlike ADR discovery, README/index pages ARE kept — they're general docs."""
+        seen: dict[str, str] = {}
+        for pattern in doc_globs:
+            for path in sorted(root.glob(pattern)):
+                if not path.is_file():
+                    continue
+                rel = path.relative_to(root).as_posix()
+                if rel in adr_paths or rel in seen:
+                    continue
+                seen[rel] = path.read_text(encoding="utf-8", errors="replace")
+        return sorted(seen.items())
+
+    async def _existing_doc_paths(self, store: GraphStore) -> set[str]:
+        nodes = (await store.query(GraphQuery(kinds=[NodeKind.DOC_CHUNK], limit=_ALL))).nodes
+        return {SymbolID.parse(n.id).path for n in nodes if n.attrs.get("doc_source") == "doc"}
+
+    async def _ingest_docs(
+        self,
+        store: GraphStore,
+        root: Path,
+        doc_globs: list[str],
+        adr_paths: set[str],
+        path_index: dict[str, str],
+        name_index: dict[str, list[str]],
+        code_exts: set[str],
+        stats: KnowledgeStats,
+    ) -> None:
+        doc_files = self._discover_docs(root, doc_globs, adr_paths)
+        current = {rel for rel, _ in doc_files}
+        # GC general-doc DocChunks whose source file vanished (per-file like ADRs)
+        for path in await self._existing_doc_paths(store):
+            if path not in current:
+                await store.delete_file(path)
+        prov = Provenance.parsed("doc-ingestor", self.commit)
+        for rel, text in doc_files:
+            sg, resolved = self._build_doc(rel, text, prov, path_index, name_index, code_exts)
+            if not sg.nodes:  # an empty/section-less doc contributes nothing
+                continue
+            await store.upsert(sg)
+            stats.docs_indexed += 1
+            stats.describes_resolved += resolved
+
+    def _build_doc(
+        self,
+        rel: str,
+        text: str,
+        prov: Provenance,
+        path_index: dict[str, str],
+        name_index: dict[str, list[str]],
+        code_exts: set[str],
+    ) -> tuple[FileSubgraph, int]:
+        """A general doc → one DocChunk per markdown section, each ``DESCRIBES`` the
+        code it unambiguously mentions (no Decision; docs describe, ADRs govern)."""
+        nodes: list[Node] = []
+        edges: list[Edge] = []
+        resolved = 0
+        for i, section in enumerate(_sections(text)):
+            chunk_id = SymbolID.for_symbol(_DOC_LANG, self.repo, rel, f"docchunk({i}).")
+            body = f"{section.heading}\n{section.text}"
+            nodes.append(
+                Node(
+                    id=chunk_id,
+                    kind=NodeKind.DOC_CHUNK,
+                    name=section.heading or f"section{i}",
+                    attrs={
+                        "path": normalize_path(rel),
+                        "heading": section.heading,
+                        "text": section.text,
+                        "seq": i,
+                        "doc_source": "doc",  # distinguishes general docs from ADR chunks
+                        "content_hash": hashlib.sha256(body.encode()).hexdigest(),
+                    },
+                    provenance=prov,
+                )
+            )
+            mentions = extract_mentions(body, code_exts)
+            targets, _unresolved = resolve_mentions(mentions, path_index, name_index)
+            for target in sorted(targets):
+                edges.append(
+                    Edge(src=chunk_id, dst=target, kind=EdgeKind.DESCRIBES, provenance=prov)
+                )
+                resolved += 1
+        content_hash = hashlib.sha256(text.encode("utf-8")).hexdigest()
+        return FileSubgraph(path=rel, content_hash=content_hash, nodes=nodes, edges=edges), resolved

agentforge_graph/knowledge/mentions.py

@@ -0,0 +1,71 @@
+"""Extract code mentions from an ADR body and resolve them — precisely — to
+graph nodes (feat-010). Only **unambiguous** matches become ``GOVERNS`` edges;
+ambiguous or unresolved mentions are counted, never guessed (ADR-0004)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from agentforge_graph.core.symbols import normalize_path
+
+_BACKTICK_RE = re.compile(r"`([^`]+)`")
+# A qualified name: identifiers joined by '.' or '#', e.g. app.auth.login,
+# Auth#login, PaymentService. No spaces, at least one identifier char.
+_QUALNAME_RE = re.compile(r"^[A-Za-z_][\w]*(?:[.#][A-Za-z_][\w]*)*$")
+
+
+@dataclass
+class Mentions:
+    paths: set[str] = field(default_factory=set)  # normalised repo-relative paths
+    names: set[str] = field(default_factory=set)  # bare symbol names (last segment)
+
+
+def _looks_like_path(token: str, code_exts: set[str]) -> bool:
+    return "/" in token and any(token.endswith(ext) for ext in code_exts)
+
+
+def _leaf_name(qualname: str) -> str:
+    return re.split(r"[.#]", qualname.strip())[-1]
+
+
+def extract_mentions(body: str, code_exts: set[str]) -> Mentions:
+    m = Mentions()
+    # backtick code spans: paths or qualified names
+    for span in _BACKTICK_RE.findall(body):
+        token = span.strip()
+        if _looks_like_path(token, code_exts):
+            m.paths.add(normalize_path(token))
+        elif _QUALNAME_RE.match(token):
+            m.names.add(_leaf_name(token))
+    # bare path-like tokens anywhere (e.g. mentioned in prose without backticks)
+    ext_alt = "|".join(re.escape(e.lstrip(".")) for e in sorted(code_exts))
+    if ext_alt:
+        for token in re.findall(rf"[\w./-]+\.(?:{ext_alt})\b", body):
+            if "/" in token:
+                m.paths.add(normalize_path(token))
+    return m
+
+
+def resolve_mentions(
+    mentions: Mentions,
+    path_index: dict[str, str],
+    name_index: dict[str, list[str]],
+) -> tuple[set[str], int]:
+    """Map mentions to node ids. Returns (resolved target ids, unresolved count).
+    A path → its FILE id (exact). A name → its symbol id **iff unique**."""
+    targets: set[str] = set()
+    unresolved = 0
+    for path in mentions.paths:
+        file_id = path_index.get(path)
+        if file_id is not None:
+            targets.add(file_id)
+        else:
+            unresolved += 1
+    for name in mentions.names:
+        candidates = name_index.get(name, [])
+        if len(candidates) == 1:
+            targets.add(candidates[0])
+        else:
+            unresolved += 1  # 0 (unknown) or >1 (ambiguous) — never guess
+    return targets, unresolved