graphitect 0.2.0__py3-none-any.whl

graphify/manifest.py

@@ -0,0 +1,4 @@
+# re-export manifest helpers from detect for backwards compatibility
+from graphify.detect import save_manifest, load_manifest, detect_incremental
+
+__all__ = ["save_manifest", "load_manifest", "detect_incremental"]

graphify/manifest_ingest.py

@@ -0,0 +1,311 @@
+"""Deterministic package-manifest ingestion (#1377).
+
+Package manifests (``apm.yml``, ``pyproject.toml``, ``Cargo.toml``, ``go.mod``,
+``pom.xml``) declare a package and its dependencies. Left to the LLM document path, the same
+package gets a different file-anchored node id from its own manifest than from
+each dependent's dependency reference, so it splits into duplicate nodes. This
+module parses manifests deterministically and emits ONE canonical package node
+per package -- keyed by NAME via :func:`graphify.ids.make_id` -- plus
+``depends_on`` edges, so a package referenced from N manifests collapses to a
+single hub node (the dependency stub and the package's own definition node share
+the canonical id and merge at build time).
+
+Mirrors ``mcp_ingest``: recognized by filename, routed to the deterministic AST
+path (never the LLM), so a manifest is extracted exactly once.
+"""
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any
+
+from graphify.ids import make_id
+
+__all__ = ["is_package_manifest_path", "extract_package_manifest", "PACKAGE_MANIFEST_NAMES"]
+
+# manifest filename (lowercased) -> ecosystem tag
+PACKAGE_MANIFEST_NAMES: dict[str, str] = {
+    "apm.yml": "apm",
+    "apm.yaml": "apm",
+    "pyproject.toml": "python",
+    "cargo.toml": "cargo",
+    "go.mod": "go",
+    "pom.xml": "maven",
+}
+
+_MAX_MANIFEST_BYTES = 2_000_000  # 2 MB cap — manifests are small; this rejects junk
+
+_TOMLI_REQUIRED = (
+    "Package-manifest ingestion on Python < 3.11 needs tomli. "
+    "Install with: pip install 'tomli' "
+    "(or reinstall graphifyy, which declares tomli for python_version < '3.11')."
+)
+
+
+def _load_toml_module():
+    """Return a tomllib-compatible module, or raise ImportError (#3283).
+
+    Returning ``None`` used to look identical to a virtual workspace root with
+    nothing to emit, so missing ``tomli`` on Python 3.10 silently dropped every
+    ``Cargo.toml`` / ``pyproject.toml``. Raise instead: the caller
+    (``extract_package_manifest``) surfaces this as a visible per-manifest error
+    rather than dropping the file silently. In practice the runtime ``tomli``
+    dependency (python_version < '3.11') keeps this path unreachable for a
+    standard install.
+    """
+    try:
+        import tomllib as _toml  # type: ignore[import-not-found]
+        return _toml
+    except ImportError:
+        try:
+            import tomli as _toml  # type: ignore[import-not-found,no-redef]
+            return _toml
+        except ImportError as exc:
+            raise ImportError(_TOMLI_REQUIRED) from exc
+
+
+def is_package_manifest_path(path: Path) -> bool:
+    """True if ``path`` is a recognized package manifest (by filename)."""
+    return path.name.lower() in PACKAGE_MANIFEST_NAMES
+
+
+def _pkg_id(name: str) -> str:
+    """Canonical package node id, keyed by package NAME so every reference to the
+    same package -- its own manifest and any dependent's dependency line -- maps
+    to one node."""
+    return make_id("pkg", name)
+
+
+def extract_package_manifest(path: Path) -> dict[str, Any]:
+    """Parse a package manifest into a canonical package node + ``depends_on`` edges."""
+    try:
+        if path.stat().st_size > _MAX_MANIFEST_BYTES:
+            return {"nodes": [], "edges": [], "error": "manifest too large to index"}
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return {"nodes": [], "edges": [], "error": f"manifest read error: {exc}"}
+
+    eco = PACKAGE_MANIFEST_NAMES[path.name.lower()]
+    try:
+        info = _PARSERS[eco](text)
+    except Exception as exc:  # noqa: BLE001 — a malformed manifest must not abort extraction
+        return {"nodes": [], "edges": [], "error": f"manifest parse error: {exc}"}
+    if not info or not info.get("name"):
+        return {"nodes": [], "edges": []}
+
+    name = info["name"]
+    str_path = str(path)
+    pkg_nid = _pkg_id(name)
+    node: dict[str, Any] = {
+        "id": pkg_nid,
+        "label": name,
+        "file_type": "code",   # valid schema type; `type` distinguishes packages
+        "type": "package",
+        "ecosystem": eco,
+        "source_file": str_path,
+        "source_location": "L1",
+    }
+    if info.get("version"):
+        node["version"] = info["version"]
+    nodes: list[dict] = [node]
+    edges: list[dict] = []
+
+    seen: set[str] = set()
+    for dep in info.get("deps", []):
+        if not dep:
+            continue
+        dep_nid = _pkg_id(dep)
+        if dep_nid == pkg_nid or dep_nid in seen:
+            continue
+        seen.add(dep_nid)
+        # The edge targets the dependency's canonical package id. If that package's
+        # own manifest is in the corpus, the edge resolves to its (single) node; if
+        # the dependency is external, build_from_json prunes the dangling edge. We
+        # deliberately do NOT emit a stub node — a stub with an empty source_file
+        # would risk clobbering the real node's source_file under id-dedup.
+        edges.append({
+            "source": pkg_nid,
+            "target": dep_nid,
+            "relation": "depends_on",
+            "context": "dependency",
+            "confidence": "EXTRACTED",
+            "confidence_score": 1.0,
+            "source_file": str_path,
+            "source_location": "L1",
+            "weight": 1.0,
+        })
+    return {"nodes": nodes, "edges": edges}
+
+
+# ── per-ecosystem parsers: text -> {"name", "version"?, "deps": [str]} | None ──
+
+def _coerce_deps(value: Any) -> list[str]:
+    """A dependency block may be a list of names or a name->spec map."""
+    if isinstance(value, dict):
+        return [str(k) for k in value]
+    if isinstance(value, list):
+        out: list[str] = []
+        for item in value:
+            if isinstance(item, str):
+                out.append(item)
+            elif isinstance(item, dict) and item:
+                out.append(str(next(iter(item))))
+        return out
+    return []
+
+
+def _parse_apm(text: str) -> dict | None:
+    try:
+        import yaml
+    except ImportError:
+        return _parse_apm_fallback(text)
+    data = yaml.safe_load(text)
+    if not isinstance(data, dict):
+        return None
+    return {
+        "name": data.get("name"),
+        "version": data.get("version"),
+        "deps": _coerce_deps(data.get("dependencies")),
+    }
+
+
+def _parse_apm_fallback(text: str) -> dict | None:
+    """Minimal line parser for apm.yml when PyYAML is unavailable: a top-level
+    ``name:``/``version:`` plus a simple ``dependencies:`` block (list items or
+    a name map)."""
+    name = None
+    version = None
+    deps: list[str] = []
+    in_deps = False
+    for line in text.splitlines():
+        if not in_deps:
+            m = re.match(r'^name:\s*["\']?([^"\'\s#]+)', line)
+            if m:
+                name = m.group(1)
+                continue
+            # `version` is part of the manifest contract the YAML path already
+            # returns; dropping it here made a package node lose its version
+            # on every machine without PyYAML installed.
+            m = re.match(r'^version:\s*["\']?([^"\'\s#]+)', line)
+            if m:
+                version = m.group(1)
+                continue
+        if re.match(r'^dependencies:\s*$', line):
+            in_deps = True
+            continue
+        if in_deps:
+            dm = (re.match(r'^\s*-\s*["\']?([^"\'\s#:]+)', line)
+                  or re.match(r'^\s{2,}([A-Za-z0-9._/@-]+)\s*:', line))
+            if dm:
+                deps.append(dm.group(1))
+            elif re.match(r'^\S', line):  # next top-level key ends the block
+                in_deps = False
+    return {"name": name, "version": version, "deps": deps} if name else None
+
+
+def _pep508_name(spec: str) -> str:
+    """`requests>=2.0` -> `requests`; `pkg[extra]==1; python_version<'3.9'` -> `pkg`."""
+    return re.split(r'[\s<>=!~;\[\(]', spec.strip(), maxsplit=1)[0]
+
+
+def _parse_pyproject(text: str) -> dict | None:
+    _toml = _load_toml_module()
+    data = _toml.loads(text)
+    proj = data.get("project", {}) if isinstance(data.get("project"), dict) else {}
+    poetry = (data.get("tool", {}) or {}).get("poetry", {}) if isinstance(data.get("tool"), dict) else {}
+    name = proj.get("name") or (poetry.get("name") if isinstance(poetry, dict) else None)
+    if not name:
+        return None
+    deps: list[str] = [_pep508_name(s) for s in (proj.get("dependencies") or []) if isinstance(s, str)]
+    if isinstance(poetry, dict):
+        for dep in (poetry.get("dependencies") or {}):
+            if str(dep).lower() != "python":
+                deps.append(str(dep))
+    return {"name": name, "version": proj.get("version") or (poetry.get("version") if isinstance(poetry, dict) else None), "deps": deps}
+
+
+def _parse_cargo(text: str) -> dict | None:
+    """Cargo.toml: name/version from ``[package]``, runtime deps from
+    ``[dependencies]`` plus every ``[target.<cfg>.dependencies]`` table (mirrors
+    ``_parse_pyproject``'s runtime-only scope; dev-/build-dependencies excluded)."""
+    _toml = _load_toml_module()
+    data = _toml.loads(text)
+    pkg = data.get("package", {}) if isinstance(data.get("package"), dict) else {}
+    name = pkg.get("name")
+    # A virtual workspace root (``[workspace]``, no ``[package]``) declares no
+    # package of its own — emit nothing rather than a fabricated node. ``name`` is
+    # never workspace-inheritable in Cargo, but guard on the type anyway.
+    if not isinstance(name, str) or not name:
+        return None
+    # ``version`` may be workspace-inherited (``version.workspace = true``), which
+    # parses to a table; keep only a concrete string version.
+    version = pkg.get("version")
+    if not isinstance(version, str):
+        version = None
+    # A dependency value is a bare version string or an inline table; either way
+    # _coerce_deps keys it by the dependency NAME (the table/map key).
+    deps = _coerce_deps(data.get("dependencies"))
+    # Platform-conditional deps live under ``[target.<cfg>.dependencies]``; fold
+    # them in so a crate whose deps are entirely cfg-gated still emits its edges.
+    targets = data.get("target")
+    if isinstance(targets, dict):
+        for cfg in targets.values():
+            if isinstance(cfg, dict):
+                deps += _coerce_deps(cfg.get("dependencies"))
+    return {"name": name, "version": version, "deps": deps}
+
+
+def _parse_gomod(text: str) -> dict | None:
+    name = None
+    deps: list[str] = []
+    in_block = False
+    for line in text.splitlines():
+        s = line.strip()
+        if name is None:
+            m = re.match(r'^module\s+(\S+)', s)
+            if m:
+                name = m.group(1)
+                continue
+        if re.match(r'^require\s*\(', s):
+            in_block = True
+            continue
+        if in_block:
+            if s.startswith(')'):
+                in_block = False
+                continue
+            dm = re.match(r'^(\S+)\s+v\S+', s)
+            if dm:
+                deps.append(dm.group(1))
+        else:
+            dm = re.match(r'^require\s+(\S+)\s+v\S+', s)
+            if dm:
+                deps.append(dm.group(1))
+    return {"name": name, "version": None, "deps": deps} if name else None
+
+
+def _parse_pom(text: str) -> dict | None:
+    # Drop the default namespace so findtext/findall don't need the {uri} prefix.
+    text = re.sub(r'\sxmlns="[^"]*"', '', text, count=1)
+    root = ET.fromstring(text)
+    aid = root.findtext("artifactId")
+    gid = root.findtext("groupId")
+    if not aid:
+        return None
+    name = f"{gid}:{aid}" if gid else aid
+    deps: list[str] = []
+    for dep in root.findall(".//dependencies/dependency"):
+        da = dep.findtext("artifactId")
+        dg = dep.findtext("groupId")
+        if da:
+            deps.append(f"{dg}:{da}" if dg else da)
+    return {"name": name, "version": root.findtext("version"), "deps": deps}
+
+
+_PARSERS = {
+    "apm": _parse_apm,
+    "python": _parse_pyproject,
+    "cargo": _parse_cargo,
+    "go": _parse_gomod,
+    "maven": _parse_pom,
+}

graphify/mcp_ingest.py

@@ -0,0 +1,386 @@
+"""mcp_ingest.py — Extract MCP (Model Context Protocol) server configuration files.
+
+Reads `.mcp.json` / `claude_desktop_config.json` / `mcp.json` / `mcp_servers.json`
+and turns the `mcpServers` map into Graphify nodes and edges.
+
+Symmetry with `serve.py`: Graphify exposes itself AS an MCP server. This module
+indexes MCP servers AS a corpus type, completing the loop — an agent that runs
+graphify with `--mcp` can now query its own configured MCP layer.
+
+Entry point:
+  extract_mcp_config(path: Path) -> dict[str, list[dict]]
+
+  Returns `{"nodes": [...], "edges": [...]}` compatible with Graphify's
+  extraction-result format. Returns `{"nodes": [...], "edges": [...], "error": "..."}`
+  when the file is malformed, too large, or has no `mcpServers` map — the empty
+  result keeps it indistinguishable from "no MCP config here" for downstream
+  callers.
+
+Detected filenames (case-sensitive, matched on basename):
+  - .mcp.json                       (Claude Code project config)
+  - claude_desktop_config.json      (Claude Desktop)
+  - mcp.json                        (generic / per-tool)
+  - mcp_servers.json                (alternate naming)
+
+Schema emitted:
+  Node kinds:
+    - file              the config file itself (label = filename)
+    - mcp_server        one per entry under mcpServers
+    - mcp_command       executable (npx, uvx, node, python, ...) — global ID
+    - mcp_package       npm / pypi package id parsed from args — global ID
+    - env_var           env variable NAME only — global ID. VALUES ARE NEVER READ.
+
+  Edge relations:
+    - contains          file -> mcp_server
+    - references        mcp_server -> mcp_command
+    - references        mcp_server -> mcp_package
+    - requires_env      mcp_server -> env_var   (new relation; distinguishes
+                                                  env dependencies from generic refs)
+
+Security:
+  - Env var VALUES are never read, persisted, labelled, or surfaced. Only env
+    var NAMES become nodes. (`env: {"API_KEY": "sk-..."}` -> node "API_KEY" only.)
+  - File size capped at 1 MiB (matches extract_json).
+  - All labels go through `sanitize_label` (control characters stripped, length
+    capped) before emission.
+  - Args are NOT persisted as nodes/edges to avoid leaking paths or secrets that
+    some servers embed as positional args.
+
+Cross-config emergent edges:
+  Because `mcp_command`, `mcp_package`, and `env_var` nodes use global IDs (no
+  per-file stem prefix), the same package or env var across two MCP configs
+  produces shared nodes — naturally surfacing "what configs depend on this
+  thing?" via graph traversal. Server nodes ARE stem-scoped so two configs
+  declaring different servers under the same key (e.g., both have "filesystem")
+  do not collide.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from pathlib import Path
+from typing import Any
+
+from graphify.ids import make_id as _shared_make_id
+from graphify.security import sanitize_label
+
+
+MCP_CONFIG_FILENAMES: frozenset[str] = frozenset({
+    ".mcp.json",
+    "claude_desktop_config.json",
+    "mcp.json",
+    "mcp_servers.json",
+})
+
+_MAX_BYTES = 1_048_576  # 1 MiB — same cap as extract_json
+_MAX_SERVERS_PER_FILE = 200  # generous; flags pathological configs
+
+
+def is_mcp_config_path(path: Path) -> bool:
+    """Return True when ``path`` is a recognised MCP config filename."""
+    return path.name in MCP_CONFIG_FILENAMES
+
+
+def extract_mcp_config(path: Path) -> dict[str, Any]:
+    """Parse an MCP config file into Graphify nodes and edges.
+
+    Behaviour matches other extractors in `extract.py`:
+      - returns ``{"nodes": [...], "edges": [...]}`` on success
+      - returns ``{"nodes": [], "edges": [], "error": "<reason>"}`` on parse
+        failure, oversize file, or missing ``mcpServers`` map
+    """
+    try:
+        with path.open("rb") as fh:
+            raw = fh.read(_MAX_BYTES + 1)
+    except OSError as exc:
+        return {"nodes": [], "edges": [], "error": f"mcp_ingest read error: {exc}"}
+
+    if len(raw) > _MAX_BYTES:
+        return {"nodes": [], "edges": [], "error": "mcp config too large to index"}
+
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        return {"nodes": [], "edges": [], "error": f"mcp_ingest decode error: {exc}"}
+
+    try:
+        doc = json.loads(text)
+    except json.JSONDecodeError as exc:
+        return {"nodes": [], "edges": [], "error": f"mcp_ingest json error: {exc}"}
+
+    if not isinstance(doc, dict):
+        return {"nodes": [], "edges": [], "error": "mcp_ingest: root is not an object"}
+
+    servers = doc.get("mcpServers")
+    if not isinstance(servers, dict):
+        # Some tools nest the map (e.g., {"mcp": {"servers": {...}}}). Try one
+        # well-known alternate shape but do not search exhaustively.
+        nested = doc.get("mcp")
+        if isinstance(nested, dict):
+            servers = nested.get("servers")
+        if not isinstance(servers, dict):
+            return {"nodes": [], "edges": [], "error": "mcp_ingest: no mcpServers map"}
+
+    str_path = str(path)
+    file_nid = _make_id(str_path)
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+    seen_node_ids: set[str] = set()
+    seen_edge_keys: set[tuple[str, str, str]] = set()
+
+    _add_node(
+        nodes, seen_node_ids,
+        nid=file_nid,
+        label=path.name,
+        kind="mcp_config_file",
+        source_file=str_path,
+        line=1,
+    )
+
+    file_stem = _file_stem(path)
+    server_count = 0
+    for server_name, spec in servers.items():
+        if not isinstance(server_name, str) or not server_name:
+            continue
+        if not isinstance(spec, dict):
+            # Skip non-object server entries silently — the broken entry is
+            # the user's, not ours.
+            continue
+        if server_count >= _MAX_SERVERS_PER_FILE:
+            break
+        server_count += 1
+        _emit_server(
+            server_name=server_name,
+            spec=spec,
+            file_nid=file_nid,
+            file_stem=file_stem,
+            source_file=str_path,
+            nodes=nodes,
+            edges=edges,
+            seen_node_ids=seen_node_ids,
+            seen_edge_keys=seen_edge_keys,
+        )
+
+    return {"nodes": nodes, "edges": edges}
+
+
+def _emit_server(
+    *,
+    server_name: str,
+    spec: dict[str, Any],
+    file_nid: str,
+    file_stem: str,
+    source_file: str,
+    nodes: list[dict[str, Any]],
+    edges: list[dict[str, Any]],
+    seen_node_ids: set[str],
+    seen_edge_keys: set[tuple[str, str, str]],
+) -> None:
+    """Emit nodes/edges for one entry under ``mcpServers``."""
+    server_nid = _make_id(file_stem, "mcp_server", server_name)
+    _add_node(
+        nodes, seen_node_ids,
+        nid=server_nid,
+        label=server_name,
+        kind="mcp_server",
+        source_file=source_file,
+        line=1,  # JSON doesn't expose line numbers without a parser pass
+    )
+    _add_edge(
+        edges, seen_edge_keys,
+        source=file_nid,
+        target=server_nid,
+        relation="contains",
+        source_file=source_file,
+        line=1,
+    )
+
+    command = spec.get("command")
+    if isinstance(command, str) and command.strip():
+        cmd_label = command.strip()
+        cmd_nid = _make_id("mcp_command", cmd_label)
+        _add_node(
+            nodes, seen_node_ids,
+            nid=cmd_nid,
+            label=cmd_label,
+            kind="mcp_command",
+            source_file=source_file,
+            line=1,
+        )
+        _add_edge(
+            edges, seen_edge_keys,
+            source=server_nid,
+            target=cmd_nid,
+            relation="references",
+            source_file=source_file,
+            line=1,
+            context="command",
+        )
+
+    args = spec.get("args")
+    if isinstance(args, list):
+        package = _detect_package_from_args(args)
+        if package:
+            pkg_nid = _make_id("mcp_package", package)
+            _add_node(
+                nodes, seen_node_ids,
+                nid=pkg_nid,
+                label=package,
+                kind="mcp_package",
+                source_file=source_file,
+                line=1,
+            )
+            _add_edge(
+                edges, seen_edge_keys,
+                source=server_nid,
+                target=pkg_nid,
+                relation="references",
+                source_file=source_file,
+                line=1,
+                context="package",
+            )
+
+    env = spec.get("env")
+    if isinstance(env, dict):
+        # ONLY KEYS. Values may contain secrets and are never read here.
+        for env_name in env.keys():
+            if not isinstance(env_name, str) or not env_name:
+                continue
+            env_nid = _make_id("env_var", env_name)
+            _add_node(
+                nodes, seen_node_ids,
+                nid=env_nid,
+                label=env_name,
+                kind="env_var",
+                source_file=source_file,
+                line=1,
+            )
+            _add_edge(
+                edges, seen_edge_keys,
+                source=server_nid,
+                target=env_nid,
+                relation="requires_env",
+                source_file=source_file,
+                line=1,
+            )
+
+
+# ── Package detection from args ───────────────────────────────────────────────
+
+# Patterns observed in real MCP server configs:
+#   ["-y", "@modelcontextprotocol/server-filesystem", "/data"]   (npx)
+#   ["-y", "@org/pkg@1.2.3"]
+#   ["mcp-server-fetch"]                                          (uvx / python)
+#   ["mcp-server-time", "--local-timezone=UTC"]
+#   ["@scoped/some-mcp"]                                          (pnpx)
+#   ["mcp-server-fetch"]                                          (uvx direct)
+_NPM_PKG_RE = re.compile(r"^@[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*(?:@[\w.\-+]+)?$")
+_PY_MCP_PKG_RE = re.compile(r"^[a-z0-9][a-z0-9._-]*-mcp(?:-[a-z0-9._-]+)?$|^mcp-[a-z0-9][a-z0-9._-]*$")
+_ARG_FLAG_RE = re.compile(r"^-{1,2}\w")
+
+
+def _detect_package_from_args(args: list[Any]) -> str | None:
+    """Return the first arg that looks like an npm or pypi package id, else None.
+
+    Skips short flags (-y, --yes) and option arguments (--local-timezone=UTC).
+    """
+    for raw in args:
+        if not isinstance(raw, str):
+            continue
+        arg = raw.strip()
+        if not arg or _ARG_FLAG_RE.match(arg):
+            continue
+        if _NPM_PKG_RE.match(arg):
+            return _strip_version(arg)
+        if _PY_MCP_PKG_RE.match(arg):
+            return arg
+    return None
+
+
+def _strip_version(pkg: str) -> str:
+    """Drop the ``@version`` suffix from an npm package id, preserving the scope.
+
+    Scoped:   ``@scope/name`` or ``@scope/name@1.2.3`` — there are at most two
+              ``@`` chars; the second is the version separator.
+    Unscoped: ``name`` or ``name@1.2.3``.
+    """
+    if pkg.startswith("@"):
+        version_at = pkg.find("@", 1)
+        return pkg if version_at == -1 else pkg[:version_at]
+    version_at = pkg.find("@")
+    return pkg if version_at == -1 else pkg[:version_at]
+
+
+# ── Node / edge construction (Graphify schema) ────────────────────────────────
+
+
+def _add_node(
+    nodes: list[dict[str, Any]],
+    seen: set[str],
+    *,
+    nid: str,
+    label: str,
+    kind: str,
+    source_file: str,
+    line: int,
+) -> None:
+    """Append a node if not already present. ``kind`` is metadata, not file_type."""
+    if not nid or nid in seen:
+        return
+    seen.add(nid)
+    nodes.append({
+        "id": nid,
+        "label": sanitize_label(label),
+        "file_type": "code",
+        "source_file": source_file,
+        "source_location": f"L{line}",
+        "metadata": {"mcp_kind": kind},
+    })
+
+
+def _add_edge(
+    edges: list[dict[str, Any]],
+    seen: set[tuple[str, str, str]],
+    *,
+    source: str,
+    target: str,
+    relation: str,
+    source_file: str,
+    line: int,
+    context: str | None = None,
+) -> None:
+    """Append an edge if (source, target, relation) is not already present."""
+    if not source or not target or source == target:
+        return
+    key = (source, target, relation)
+    if key in seen:
+        return
+    seen.add(key)
+    edge: dict[str, Any] = {
+        "source": source,
+        "target": target,
+        "relation": relation,
+        "confidence": "EXTRACTED",
+        "confidence_score": 1.0,
+        "source_file": source_file,
+        "source_location": f"L{line}",
+        "weight": 1.0,
+    }
+    if context:
+        edge["context"] = context
+    edges.append(edge)
+
+
+# ── ID helpers (kept local; mirror extract.py shape) ──────────────────────────
+
+
+def _make_id(*parts: str) -> str:
+    """Build a stable node ID via the single shared recipe (#1378)."""
+    return _shared_make_id(*parts)
+
+
+# Canonical recipe imported directly (no import cycle: extractors.base imports
+# only graphify.ids), so this can no longer drift from extract._file_stem.
+from graphify.extractors.base import _file_stem  # noqa: E402