src2sink 1.0.0__py3-none-any.whl

src2sink/aggregators/index_v2.py

@@ -0,0 +1,138 @@
+"""v2 repo index (replaces v1 index/ for flow-graph metabase)."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+from ..graph_common import iter_nodes, load_v2_repo_records
+from ..renderers.markdown import md_table
+
+
+def _row_from_record(data: dict[str, Any]) -> dict[str, Any]:
+    """Summarise one repo record into an index row of per-family node counts."""
+    families: Counter[str] = Counter()
+    weak_algos: list[str] = []
+    for node in iter_nodes(data):
+        families[node.get("family", "")] += 1
+        if node.get("family") == "crypto-algorithm":
+            algo = (node.get("detail") or {}).get("algorithm", "")
+            if algo and algo.upper() in {"MD5", "SHA1", "SHA-1", "DES", "RC4"}:
+                weak_algos.append(algo)
+    return {
+        "group": data["group"],
+        "name": data["name"],
+        "path": data.get("path", ""),
+        "primary_language": data.get("primary_language", "unknown"),
+        "frameworks": data.get("frameworks") or [],
+        "nodes": len(data.get("nodes", [])),
+        "edges": len(data.get("edges", [])),
+        "http_in": families.get("http-in", 0),
+        "http_out": families.get("http-out", 0),
+        "sql": families.get("sql", 0),
+        "raw_payload": families.get("raw-code-payload", 0),
+        "pii_field": families.get("pii-field", 0),
+        "pii_log": families.get("pii-log", 0),
+        "queue": families.get("queue-pub", 0) + families.get("queue-sub", 0),
+        "crypto": families.get("crypto-algorithm", 0),
+        "weak_algos": sorted(set(weak_algos)),
+    }
+
+
+def write_index_v2(metabase_root: Path, repo_jsons: list[Path]) -> None:
+    """Write the v2 repo index JSON and the all/by-group/by-language markdown pages."""
+    records = load_v2_repo_records(metabase_root, json_paths=repo_jsons)
+    rows = [_row_from_record(data) for data in records]
+    index_dir = metabase_root / "index"
+    index_dir.mkdir(parents=True, exist_ok=True)
+
+    (index_dir / "repos.json").write_text(
+        json.dumps(rows, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )
+
+    ts = dt.datetime.now(dt.timezone.utc).isoformat()
+    md = [
+        "# All repos (v2 index)\n",
+        f"_Generated {ts} from `schema_version: 2` JSON summaries._\n",
+        f"_{len(rows)} repos._\n\n",
+        md_table(
+            [
+                "Group / Repo",
+                "Lang",
+                "Frameworks",
+                "Nodes",
+                "HTTP-in",
+                "HTTP-out",
+                "SQL",
+                "Raw payload",
+                "PII fields",
+            ],
+            sorted(
+                [
+                    [
+                        f"[{r['group']}/{r['name']}](../repos/{r['group']}/{r['name']}.md)",
+                        r["primary_language"],
+                        ", ".join(r["frameworks"]) or "—",
+                        str(r["nodes"]),
+                        str(r["http_in"]),
+                        str(r["http_out"]),
+                        str(r["sql"]),
+                        str(r["raw_payload"]),
+                        str(r["pii_field"]),
+                    ]
+                    for r in rows
+                ],
+                key=lambda row: row[0].lower(),
+            ),
+        ),
+    ]
+    (index_dir / "repos.md").write_text("\n".join(md), encoding="utf-8")
+
+    by_group: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for r in rows:
+        by_group[r["group"]].append(r)
+    out = [f"# Repos by group (v2)\n\n_Generated {ts}._\n\n"]
+    for g in sorted(by_group):
+        out.append(f"## {g} ({len(by_group[g])} repos)\n")
+        out.append(
+            md_table(
+                ["Repo", "Lang", "Nodes", "Raw payload", "PII"],
+                [
+                    [
+                        f"[{r['name']}](../repos/{g}/{r['name']}.md)",
+                        r["primary_language"],
+                        str(r["nodes"]),
+                        str(r["raw_payload"]),
+                        str(r["pii_field"]),
+                    ]
+                    for r in sorted(by_group[g], key=lambda x: x["name"].lower())
+                ],
+            ),
+        )
+    (index_dir / "by-group.md").write_text("\n".join(out), encoding="utf-8")
+
+    by_lang: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for r in rows:
+        by_lang[r["primary_language"]].append(r)
+    out = ["# Repos by primary language (v2)\n\n"]
+    for lang in sorted(by_lang):
+        out.append(f"## {lang} ({len(by_lang[lang])} repos)\n")
+        out.append(
+            md_table(
+                ["Group", "Repo", "Nodes", "HTTP-in"],
+                [
+                    [
+                        r["group"],
+                        f"[{r['name']}](../repos/{r['group']}/{r['name']}.md)",
+                        str(r["nodes"]),
+                        str(r["http_in"]),
+                    ]
+                    for r in sorted(by_lang[lang], key=lambda x: (x["group"], x["name"]))
+                ],
+            ),
+        )
+    (index_dir / "by-language.md").write_text("\n".join(out), encoding="utf-8")

src2sink/aggregators/library_source_map.py

@@ -0,0 +1,188 @@
+"""Generator and loader for library-source-map.json.
+
+Maps Maven/npm coordinates to source-repo clone paths. Generated by
+src2sink-build from per-repo dependency data; manual edits to
+``status`` and ``clone_path`` fields are preserved on regeneration.
+"""
+
+from __future__ import annotations
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+STATUS_PENDING = "pending"
+STATUS_CLONED = "cloned"
+STATUS_EXCLUDED = "excluded"
+STATUS_AMBIGUOUS = "ambiguous"
+
+
+def load_library_source_map(path: Path) -> dict[str, dict[str, Any]]:
+    """Return coord -> entry dict, or {} if the file is missing/invalid."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return {m["coordinate"]: m for m in data.get("mappings", []) if "coordinate" in m}
+
+
+def generate_library_source_map(metabase_root: Path, repo_jsons: list[Path]) -> None:
+    """Write/update library-source-map.json from per-repo internal dependency data."""
+    map_path = metabase_root / "library-source-map.json"
+    existing = load_library_source_map(map_path)
+
+    # Collect all internal deps from per-repo JSONs
+    coord_consumers: dict[str, int] = defaultdict(int)
+    coord_versions: dict[str, set[str]] = defaultdict(set)
+
+    for jp in repo_jsons:
+        try:
+            data = json.loads(jp.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        for dep in data.get("dependencies_internal", []):
+            gid = dep.get("groupId", "")
+            aid = dep.get("artifactId", "")
+            ver = dep.get("version", "")
+            if not aid:
+                continue
+            coord = f"{gid}:{aid}" if gid else aid
+            coord_consumers[coord] += 1
+            if ver:
+                coord_versions[coord].add(ver)
+
+    # Build updated mappings, preserving manual overrides
+    mappings: list[dict[str, Any]] = []
+    for coord, count in sorted(coord_consumers.items(), key=lambda x: -x[1]):
+        prev = existing.get(coord, {})
+        # Preserve manually-set status and clone_path overrides
+        status = prev.get("status", STATUS_PENDING)
+        clone_path = prev.get("clone_path") or _infer_clone_path(coord)
+        entry: dict[str, Any] = {
+            "coordinate": coord,
+            "clone_path": clone_path or "",
+            "status": status,
+            "consumers": count,
+        }
+        versions = sorted(coord_versions.get(coord, set()))
+        if versions:
+            entry["versions"] = versions
+        if prev.get("notes"):
+            entry["notes"] = prev["notes"]
+        mappings.append(entry)
+
+    out = {
+        "_comment": (
+            "Map of Maven/npm coordinates to source-repo clone paths. "
+            "Generated by src2sink-build from per-repo dependency data. "
+            "Edit 'status' ('pending'|'cloned'|'excluded') and 'clone_path' to "
+            "guide curate_internal_libraries.py. Changes are preserved on regeneration."
+        ),
+        "mappings": mappings,
+    }
+    map_path.write_text(json.dumps(out, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+
+
+def _resolve_clone_path(
+    coord: str,
+    by_coord: dict[tuple[str, str], str],
+    by_name: dict[str, list[str]],
+    by_full: dict[str, str],
+) -> str | None:
+    """Resolve a dependency coordinate to a clone path via the identity index."""
+    # 1. Exact canonical-coordinate match.
+    if coord in by_full:
+        return by_full[coord]
+    if ":" in coord:
+        group, artifact = coord.split(":", 1)
+        # 2. group:artifact pair.
+        hit = by_coord.get((group, artifact))
+        if hit:
+            return hit
+        # 3. The artifact half may itself be a full name (scoped npm, vendor/pkg).
+        if artifact in by_full:
+            return by_full[artifact]
+        candidates = by_name.get(artifact, [])
+        return candidates[0] if len(candidates) == 1 else None
+    # No group: try a group-less pair, then a unique bare-name match.
+    hit = by_coord.get(("", coord))
+    if hit:
+        return hit
+    candidates = by_name.get(coord, [])
+    return candidates[0] if len(candidates) == 1 else None
+
+
+def _entry_needs_resolution(entry: dict[str, Any]) -> bool:
+    """True if a source-map entry is still flagged and worth resolving."""
+    if not entry.get("coordinate"):
+        return False
+    status = entry.get("status")
+    if status == STATUS_EXCLUDED:
+        return False
+    if status == STATUS_CLONED and entry.get("clone_path"):
+        return False
+    return True
+
+
+def fix_flagged_mappings(metabase_root: Path, repos_root: Path) -> int:
+    """Resolve flagged source-map entries from on-disk project manifests.
+
+    Walks every recognised project-definition file under ``repos_root`` —
+    Maven (``pom.xml``), Gradle (``build.gradle``/``settings.gradle`` ±kts),
+    npm (``package.json``), Python (``pyproject.toml``/``setup.cfg``), Rust
+    (``Cargo.toml``), Go (``go.mod``), PHP (``composer.json``), .NET
+    (``*.csproj``/``*.fsproj``/``*.vbproj``) and Ruby (``*.gemspec``) — and
+    reads each project's declared identity. For any mapping still flagged
+    (status ``pending`` / ``ambiguous``, or missing a ``clone_path``) whose
+    coordinate matches a discovered project, sets ``clone_path`` to that repo's
+    path (relative to ``repos_root``) and marks the status ``cloned``.
+    ``excluded`` and already-resolved ``cloned`` entries are left untouched.
+
+    Matching tries, in order: the exact coordinate string (npm ``@scope/pkg``,
+    Composer ``vendor/pkg``, Go module path, bare names), then the
+    ``group:artifact`` pair, then a unique bare-name match.
+
+    Returns the number of mappings corrected.
+    """
+    map_path = metabase_root / "library-source-map.json"
+    try:
+        data = json.loads(map_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return 0
+    mappings = data.get("mappings")
+    if not isinstance(mappings, list) or not mappings:
+        return 0
+
+    from ..repo_utils import _build_component_identity_index
+
+    by_coord, by_name, by_full = _build_component_identity_index(repos_root)
+
+    fixed = 0
+    for entry in mappings:
+        if not isinstance(entry, dict) or not _entry_needs_resolution(entry):
+            continue
+        clone_path = _resolve_clone_path(entry["coordinate"], by_coord, by_name, by_full)
+        if not clone_path:
+            continue
+        entry["clone_path"] = clone_path
+        entry["status"] = STATUS_CLONED
+        entry.pop("notes", None)
+        fixed += 1
+
+    if fixed:
+        map_path.write_text(
+            json.dumps(data, indent=2, sort_keys=False) + "\n", encoding="utf-8"
+        )
+    return fixed
+
+
+def _infer_clone_path(coord: str) -> str | None:
+    """Best-effort inference of group/artifact from a Maven coordinate."""
+    if ":" not in coord:
+        return None
+    group, artifact = coord.split(":", 1)
+    # Strip common org prefix patterns to get a GitLab group name
+    parts = group.split(".")
+    # Heuristic: last meaningful segment of the group + artifact name
+    group_hint = parts[-1] if len(parts) > 2 else parts[-1]
+    return f"{group_hint}/{artifact}"

src2sink/aggregators/openapi_discovery.py

@@ -0,0 +1,113 @@
+"""Discover OpenAPI specs and Helm ingress hosts under repos/."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ..graph_common import normalize_path_template as norm_path
+
+from .openapi_models import OpenApiSpec
+
+OPENAPI_GLOBS = ("openapi.yaml", "openapi.yml", "swagger.yaml", "swagger.yml")
+PATH_LINE_RX = re.compile(
+    r"^\s{2,}(/[/\w{}.:$-]+)\s*:\s*$",
+    re.MULTILINE,
+)
+SERVERS_URL_RX = re.compile(
+    r"^\s*-\s*url:\s*['\"]?(https?://[^'\"\s]+)",
+    re.MULTILINE | re.IGNORECASE,
+)
+HELM_VALUES_NAMES = ("values.yaml", "values.yml")
+HELM_HOST_RX = re.compile(
+    r"^\s*(?:host|hostname|externalHost|ingress\.host)\s*:\s*['\"]?([^\s#'\"]+)",
+    re.MULTILINE | re.IGNORECASE,
+)
+
+_SKIP_DIR_PARTS = frozenset({".git", "node_modules", "target", "build", "charts"})
+
+
+def repo_from_under_repos(spec_path: Path, repos_root: Path) -> str | None:
+    """Return the ``org/repo`` id for a path under repos_root, or None."""
+    try:
+        rel = spec_path.relative_to(repos_root)
+    except ValueError:
+        return None
+    parts = rel.parts
+    if len(parts) < 2:
+        return None
+    return f"{parts[0]}/{parts[1]}"
+
+
+def _should_skip_path(path: Path) -> bool:
+    """True if the path lies within a skipped directory (.git, node_modules, ...)."""
+    return any(p in path.parts for p in _SKIP_DIR_PARTS)
+
+
+def discover_openapi_specs(repos_root: Path) -> list[OpenApiSpec]:
+    """Scan repos_root for OpenAPI/Swagger specs and return parsed OpenApiSpec rows."""
+    if not repos_root.is_dir():
+        return []
+    specs: list[OpenApiSpec] = []
+    seen: set[tuple[str, str]] = set()
+    for name in OPENAPI_GLOBS:
+        for path in repos_root.rglob(name):
+            if _should_skip_path(path):
+                continue
+            try:
+                if path.stat().st_size > 2_000_000:
+                    continue
+                text = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            target = repo_from_under_repos(path, repos_root)
+            if not target:
+                continue
+            key = (target, str(path))
+            if key in seen:
+                continue
+            seen.add(key)
+            paths = sorted({norm_path(m.group(1)) for m in PATH_LINE_RX.finditer(text)})
+            servers = [m.group(1) for m in SERVERS_URL_RX.finditer(text)]
+            specs.append(OpenApiSpec(
+                target_repo=target,
+                spec_path=str(path.relative_to(repos_root)),
+                paths=[p for p in paths if p and p != "/"],
+                servers=servers[:5],
+            ))
+    return specs
+
+
+def discover_helm_hosts(repos_root: Path) -> list[dict[str, str]]:
+    """Scan Helm values for declared ingress/service hostnames."""
+    if not repos_root.is_dir():
+        return []
+    rows: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for name in HELM_VALUES_NAMES:
+        for path in repos_root.rglob(name):
+            if _should_skip_path(path):
+                continue
+            try:
+                if path.stat().st_size > 500_000:
+                    continue
+                text = path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            target = repo_from_under_repos(path, repos_root)
+            if not target:
+                continue
+            for m in HELM_HOST_RX.finditer(text):
+                host = m.group(1).strip().strip("'\"")
+                if not host or host.startswith("{{"):
+                    continue
+                key = (target, host)
+                if key in seen:
+                    continue
+                seen.add(key)
+                rows.append({
+                    "target_repo": target,
+                    "host": host,
+                    "values_path": str(path.relative_to(repos_root)),
+                })
+    return rows

src2sink/aggregators/openapi_edges.py

@@ -0,0 +1,30 @@
+"""OpenAPI / Swagger path ingestion for authoritative inbound route index."""
+
+from __future__ import annotations
+
+from .openapi_discovery import (
+    OPENAPI_GLOBS,
+    PATH_LINE_RX,
+    discover_helm_hosts,
+    discover_openapi_specs,
+    repo_from_under_repos,
+)
+from .openapi_match import (
+    build_openapi_inbound_index,
+    match_http_out_to_openapi,
+)
+from .openapi_models import OpenApiInbound, OpenApiSpec
+from .openapi_report import write_openapi_artifacts
+
+__all__ = [
+    "OPENAPI_GLOBS",
+    "PATH_LINE_RX",
+    "OpenApiInbound",
+    "OpenApiSpec",
+    "build_openapi_inbound_index",
+    "discover_helm_hosts",
+    "discover_openapi_specs",
+    "match_http_out_to_openapi",
+    "repo_from_under_repos",
+    "write_openapi_artifacts",
+]

src2sink/aggregators/openapi_match.py

@@ -0,0 +1,81 @@
+"""Match http-out nodes to OpenAPI-discovered inbound paths."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..graph_common import (
+    build_repo_alias_index,
+    extract_urls_and_paths,
+    iter_nodes,
+    match_path_in_inbound_index,
+    normalize_path_template as norm_path,
+    repo_id,
+)
+
+from .openapi_models import OpenApiSpec
+
+
+def build_openapi_inbound_index(
+    specs: list[OpenApiSpec],
+) -> dict[str, list[tuple[str, str, str]]]:
+    """normalized_path -> [(repo, original_path, spec_path)]."""
+    index: dict[str, list[tuple[str, str, str]]] = {}
+    for spec in specs:
+        for path in spec.paths:
+            key = norm_path(path)
+            index.setdefault(key, []).append(
+                (spec.target_repo, path, spec.spec_path),
+            )
+    return index
+
+
+def _paths_from_http_out(detail: dict[str, Any], raw: str) -> list[str]:
+    """Collect candidate request paths from an http-out node detail and raw text."""
+    paths: list[str] = list(detail.get("paths") or [])
+    if detail.get("path"):
+        paths.insert(0, detail["path"])
+    _, extra_paths = extract_urls_and_paths(raw)
+    paths.extend(p for p in extra_paths if p not in paths)
+    return paths
+
+
+def match_http_out_to_openapi(
+    records: list[dict[str, Any]],
+    inbound: dict[str, list[tuple[str, str, str]]],
+    alias_to_repo: dict[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    """Return edges from http-out call sites that match an OpenAPI path."""
+    _ = alias_to_repo or build_repo_alias_index(records)
+    edges: list[dict[str, Any]] = []
+    seen: set[tuple[str, str, str]] = set()
+
+    for data in records:
+        src = repo_id(data)
+        for node in iter_nodes(data):
+            if node.get("family") != "http-out":
+                continue
+            detail = node.get("detail") or {}
+            raw = detail.get("raw", "")
+            ref = f"{node.get('file')}:{node.get('line')}"
+
+            for path in _paths_from_http_out(detail, raw):
+                targets, _conf = match_path_in_inbound_index(path, inbound)
+                for tgt_repo, tgt_path, spec_path in targets:
+                    if tgt_repo == src:
+                        continue
+                    key = (src, tgt_repo, norm_path(tgt_path))
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    edges.append({
+                        "source_repo": src,
+                        "target_repo": tgt_repo,
+                        "target_path": tgt_path,
+                        "confidence": "openapi",
+                        "evidence": f"http-out path matches OpenAPI in {spec_path}",
+                        "refs": [ref],
+                        "spec_path": spec_path,
+                    })
+
+    return edges

src2sink/aggregators/openapi_models.py

@@ -0,0 +1,25 @@
+"""Data types for OpenAPI graph ingestion."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class OpenApiSpec:
+    """A discovered OpenAPI/Swagger spec: its owning repo, file, paths and servers."""
+
+    target_repo: str
+    spec_path: str
+    paths: list[str] = field(default_factory=list)
+    servers: list[str] = field(default_factory=list)
+
+
+@dataclass
+class OpenApiInbound:
+    """A single inbound OpenAPI route: repo, path, HTTP method and spec file."""
+
+    target_repo: str
+    path: str
+    method: str
+    spec_path: str

src2sink/aggregators/openapi_report.py

@@ -0,0 +1,75 @@
+"""Write OpenAPI / Helm discovery artefacts under metabase/graphs/."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..graph_common import build_repo_alias_index, load_v2_repo_records
+from ..renderers.markdown import md_table
+
+from .openapi_discovery import OPENAPI_GLOBS, discover_helm_hosts, discover_openapi_specs
+from .openapi_match import build_openapi_inbound_index, match_http_out_to_openapi
+from .openapi_models import OpenApiSpec
+
+
+def write_openapi_artifacts(
+    metabase_root: Path,
+    repos_root: Path | None,
+    repo_jsons: list[Path] | None = None,
+) -> list[OpenApiSpec]:
+    """Discover specs/Helm hosts, write JSONL + markdown artefacts, return the specs."""
+    graphs_dir = metabase_root / "graphs"
+    graphs_dir.mkdir(parents=True, exist_ok=True)
+
+    specs: list[OpenApiSpec] = []
+    if repos_root and repos_root.is_dir():
+        specs = discover_openapi_specs(repos_root)
+
+    jsonl_path = graphs_dir / "openapi-specs.jsonl"
+    with jsonl_path.open("w", encoding="utf-8") as fh:
+        for spec in specs:
+            fh.write(json.dumps({
+                "target_repo": spec.target_repo,
+                "spec_path": spec.spec_path,
+                "paths": spec.paths,
+                "servers": spec.servers,
+            }, ensure_ascii=False) + "\n")
+
+    inbound = build_openapi_inbound_index(specs)
+    openapi_edges: list[dict[str, object]] = []
+    if repo_jsons and inbound:
+        records = load_v2_repo_records(metabase_root, json_paths=repo_jsons)
+        alias_to_repo = build_repo_alias_index(records)
+        openapi_edges = match_http_out_to_openapi(records, inbound, alias_to_repo)
+
+    edges_path = graphs_dir / "openapi-service-edges.jsonl"
+    with edges_path.open("w", encoding="utf-8") as fh:
+        for row in openapi_edges:
+            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+    helm_hosts = discover_helm_hosts(repos_root) if repos_root else []
+    helm_path = graphs_dir / "helm-service-hosts.jsonl"
+    with helm_path.open("w", encoding="utf-8") as fh:
+        for helm_row in helm_hosts:
+            fh.write(json.dumps(helm_row, ensure_ascii=False) + "\n")
+
+    md: list[str] = [
+        "# OpenAPI / Swagger specs (discovered)\n",
+        f"_Scanned under `repos/` for `{'`, `'.join(OPENAPI_GLOBS)}`._\n",
+        f"\n**Specs:** {len(specs)}. **Cross-repo edges (openapi confidence):** "
+        f"{len(openapi_edges)}. **Helm host hints:** {len(helm_hosts)}.\n",
+        "\n## Specs by service\n",
+        md_table(
+            ["Target repo", "Path count", "Spec file"],
+            [
+                [spec.target_repo, str(len(spec.paths)), spec.spec_path]
+                for spec in sorted(specs, key=lambda s: -len(s.paths))[:80]
+            ],
+        ),
+    ]
+    if len(specs) > 80:
+        md.append(f"\n_{len(specs) - 80} more in `openapi-specs.jsonl`._\n")
+
+    (graphs_dir / "openapi-specs.md").write_text("\n".join(md), encoding="utf-8")
+    return specs