stitchgraph 3.27.1__py3-none-any.whl

stitchgraph/__init__.py

@@ -0,0 +1,85 @@
+"""stitchgraph — local-first code-intelligence (library + CLI + MCP).
+
+The library API is the core: import the operations directly.
+
+    from stitchgraph import Store, find_symbol
+    with Store("graph.db") as s:
+        print(find_symbol(s, "UserService"))
+
+The CLI (`stitchgraph ...`) and the MCP server are thin adapters over these same
+operations — same names, same params (design §3).
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from .core import (
+    Edge,
+    Node,
+    NodeKind,
+    Provenance,
+    Relation,
+    Result,
+    Store,
+    Urgency,
+    ok,
+    refuse,
+    registry,
+)
+from .core.operations import (
+    co_change,
+    coverage_drift,
+    feature_map,
+    find_chokepoints,
+    find_core,
+    find_coupling,
+    find_gaps,
+    find_holes,
+    find_modes,
+    find_outlier_tests,
+    find_similar,
+    find_stale,
+    find_subsystems,
+    find_symbol,
+    get_callees,
+    get_callers,
+    get_matrix,
+    graph_diff,
+    impact_of,
+    ingest_trace,
+    orient,
+    redundant_tests,
+    reindex,
+    risk,
+    runtime_risk,
+    scaffold_coverage,
+    scan,
+    select_tests,
+    summarize_subsystem,
+    test_order,
+    trace_path,
+)
+
+# Single source of truth: the installed distribution metadata (driven by
+# pyproject.toml's version). A hardcoded literal drifted stale across 1.0.3→1.0.5;
+# deriving it here keeps `stitchgraph.__version__` and `stitchgraph --version` in sync.
+try:
+    __version__ = _version("stitchgraph")
+except PackageNotFoundError:  # pragma: no cover - source tree without installed dist
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    # types
+    "Store", "Result", "Node", "Edge", "NodeKind", "Relation",
+    "Provenance", "Urgency", "ok", "refuse", "registry",
+    # operations (the public API)
+    "find_symbol", "get_callers", "get_callees", "find_holes", "find_stale",
+    "orient", "impact_of", "trace_path", "scan", "reindex", "get_matrix", "risk",
+    "ingest_trace", "find_similar", "summarize_subsystem", "graph_diff",
+    "find_chokepoints", "find_subsystems", "find_modes", "scaffold_coverage",
+    "select_tests", "co_change", "find_coupling",
+    "find_gaps", "test_order", "redundant_tests", "find_core",
+    "feature_map", "find_outlier_tests", "runtime_risk", "coverage_drift",
+]

stitchgraph/adapters/__init__.py

@@ -0,0 +1,4 @@
+"""Thin surfaces over core.operations. Each renders the same Result envelope:
+CLI -> terminal, MCP -> tool result, report -> Markdown. Adapters import core;
+core never imports adapters (design §3).
+"""

stitchgraph/adapters/_guard.py

@@ -0,0 +1,47 @@
+"""Shared adapter guard: refuse queries against a missing / never-indexed DB.
+
+`Store(path)` creates an empty database on open, so a mispointed adapter
+(wrong cwd, typo'd --db, an MCP client launching the server from an arbitrary
+directory) would answer every query from a vacuum at full confidence — `orient`
+returns ok/1.0 with zero nodes and an LLM concludes "tiny repo, nothing dead,
+all green". That is the exact failure mode the envelope contract exists to
+prevent (review 2026-07-03, F2b). Query operations therefore refuse when the
+DB file doesn't exist or has never been indexed; only `reindex` may create one.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+
+from ..core.envelope import Result, refuse
+from ..core.store import Store
+
+# Operations allowed to open a DB that doesn't exist yet (they populate it).
+_CREATES_DB = {"reindex"}
+
+
+def open_store(db: str, op_name: str) -> tuple[Store | None, Result | None]:
+    """Open the index DB for an operation. Returns (store, None) on success,
+    (None, refusal Result) when the op is a query and the DB is absent, empty,
+    or unopenable — never silently creating an index to answer from."""
+    creates = op_name in _CREATES_DB
+    if not creates and db != ":memory:" and not os.path.exists(db):
+        return None, refuse(
+            f"index database {db!r} does not exist — run `reindex` first, or point "
+            "--db (or STITCHGRAPH_DB for the MCP server) at the built index")
+    try:
+        store = Store(db)
+    except (sqlite3.Error, OSError) as exc:
+        # A db path that can't back a database (a directory, FIFO, device, or
+        # unwritable location) must return an envelope, not a raw sqlite
+        # traceback (panel R12).
+        return None, refuse(f"cannot open index database {db!r}: {exc}")
+    if not creates and not store.get_meta("root"):
+        # The file exists but no reindex ever recorded a root: an empty shell
+        # (typically created by a previous mispointed open) — refusing beats
+        # confidently reporting an empty codebase.
+        store.close()
+        return None, refuse(
+            f"index database {db!r} holds no indexed project — run `reindex` first")
+    return store, None

stitchgraph/adapters/cli.py

@@ -0,0 +1,219 @@
+"""CLI adapter (design §3). Built by introspecting core.operations so the CLI
+maps 1:1 onto the library API — same names (kebab-cased), same params.
+
+Typer is an optional dependency (`pip install stitchgraph[cli]`); imported lazily
+so `import stitchgraph` never requires it.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json as _json
+import sqlite3
+from typing import Any
+
+from ..core.operations import Operation, registry
+from ..core.store import Store
+from ._guard import open_store
+from .render import render_text
+
+
+def _require_typer():
+    try:
+        import typer
+    except ModuleNotFoundError as exc:  # pragma: no cover
+        raise SystemExit(
+            "The CLI needs Typer. Install it with:  pip install 'stitchgraph[cli]'"
+        ) from exc
+    return typer
+
+
+def build_app():
+    typer = _require_typer()
+    # no_args_is_help: bare `stitchgraph` shows help (not a silent exit) — the
+    # invoke_without_command callback below would otherwise swallow it (issue #19).
+    app = typer.Typer(add_completion=False, no_args_is_help=True,
+                      help="stitchgraph — code intelligence")
+
+    def _version_callback(value: bool) -> None:
+        if not value:
+            return
+        from importlib.metadata import PackageNotFoundError, version
+
+        from ..core.extract import treesitter as ts
+        try:
+            ver = version("stitchgraph")
+        except PackageNotFoundError:  # pragma: no cover - not installed as a dist
+            ver = "unknown"
+        typer.echo(f"stitchgraph {ver}")
+        # The install model is version-keyed (bundled vs download grammar line, #12),
+        # so report the active tree-sitter-language-pack line too — exactly what a bug
+        # report needs (issue #19).
+        backend = ts.grammar_backend()
+        if backend.get("installed"):
+            typer.echo(f"tree-sitter-language-pack {backend['version']}  [{backend['model']}]")
+        else:
+            typer.echo("tree-sitter-language-pack not installed (Python-only extraction)")
+        raise typer.Exit()
+
+    @app.callback(invoke_without_command=True)
+    def _root(
+        version: bool = typer.Option(
+            False, "--version", callback=_version_callback, is_eager=True,
+            help="Show the stitchgraph version (and active grammar line) and exit."),
+    ) -> None:
+        pass
+
+    for op in registry():
+        app.command(name=op.name.replace("_", "-"), help=op.summary)(_make_command(typer, op))
+
+    @app.command(name="watch", help="Re-index on file changes (Ctrl-C to stop).")
+    def _watch(
+        path: str = typer.Argument(".", help="repo root to watch"),
+        db: str = typer.Option("stitchgraph.db", help="index database path"),
+        interval: float = typer.Option(2.0, help="poll interval (seconds)"),
+    ) -> None:
+        import time
+
+        from ..core import operations as ops
+        from ..core.watch import changed, snapshot
+
+        try:
+            store = Store(db)
+        except (sqlite3.Error, OSError) as exc:
+            typer.echo(f"cannot open index database {db!r}: {exc}")
+            raise typer.Exit(1) from exc
+        with store:
+            typer.echo(ops.reindex(store, path).meta)
+            state = snapshot(path)
+            typer.echo(f"watching {path} (every {interval}s)…")
+            try:
+                while True:
+                    time.sleep(interval)
+                    new = snapshot(path)
+                    if changed(state, new):
+                        state = new
+                        typer.echo(f"change detected — reindexing… {ops.reindex(store, path).meta}")
+            except KeyboardInterrupt:
+                typer.echo("stopped")
+
+    @app.command(name="report", help="Full Markdown report (orientation + issues + risk).")
+    def _report(
+        db: str = typer.Option("stitchgraph.db", help="index database path"),
+        repo: str | None = typer.Option(
+            None, help="repo root for git risk (default: the indexed root in the DB)"),
+    ) -> None:
+        from .report import build_report
+        typer.echo(build_report(db, repo))
+
+    @app.command(name="doctor",
+                 help="Check tree-sitter grammar availability (polyglot offline-readiness).")
+    def _doctor(
+        strict: bool = typer.Option(
+            False, "--strict", help="exit non-zero if any supported grammar can't load"),
+    ) -> None:
+        from ..core.extract import treesitter as ts
+        backend = ts.grammar_backend()
+        if not backend.get("installed"):
+            typer.echo("tree-sitter not installed — polyglot extraction is OFF "
+                       "(Python still works). Install:  pip install 'stitchgraph[treesitter]'")
+            raise typer.Exit(1 if strict else 0)
+        typer.echo(f"tree-sitter-language-pack {backend['version']}  [{backend['model']}]")
+        if "cache_dir" in backend:
+            typer.echo(f"  grammar cache: {backend['cache_dir']}")
+        all_ok, rows = ts.grammar_status()
+        for lang, ok, detail in rows:
+            typer.echo(f"  {'ok  ' if ok else 'FAIL'}  {lang:12} {detail}")
+        n_ok = sum(1 for _, ok, _ in rows if ok)
+        typer.echo(f"{n_ok}/{len(rows)} grammars load"
+                   + ("" if all_ok else "  — missing grammars are skipped (their files "
+                      "won't be analysed); see 'pip install stitchgraph[treesitter]'"))
+        raise typer.Exit(1 if strict and not all_ok else 0)
+
+    return app
+
+
+def _make_command(typer, op: Operation):
+    """Wrap an operation as a Typer command with the same caller-facing params."""
+    op_params = op.exposed_params()
+
+    def command(**kwargs: Any) -> None:
+        db = kwargs.pop("db")
+        as_json = kwargs.pop("json")
+        # Refuse (rather than silently create) a missing/never-indexed DB, and
+        # refuse cleanly on an unopenable --db (a directory, FIFO, device) instead
+        # of a raw sqlite traceback (panel R12; review 2026-07-03, F2b).
+        store, refusal = open_store(db, op.name)
+        if refusal is not None:
+            result = refusal
+        else:
+            assert store is not None
+            with store:
+                result = op.func(store, **kwargs)
+        if as_json:
+            typer.echo(_json.dumps(result.to_dict(), indent=2))
+        else:
+            typer.echo(render_text(op.name, result))
+        # An OPERATIONAL failure (missing/unopenable db) exits 2 so scripts can't mistake
+        # it for a clean result (review 2026-07-03, F10c); an op-level advisory refusal
+        # (e.g. get_matrix's too-broad-scope) keeps the envelope exit codes (RED=1, else 0).
+        raise typer.Exit(2 if refusal is not None else _exit_code(result))
+
+    # Give the wrapper a signature Typer can introspect: the op's params + --db/--json.
+    # Preserve each param's real type so Typer parses/validates it — rebuilding every
+    # param as `str` made `--limit 5` arrive as "5" (crashing int comparisons) and
+    # inverted bool flags.
+    params = []
+    for p in op_params:
+        anno = _anno_type(p.annotation)
+        if p.default is inspect.Parameter.empty:
+            params.append(inspect.Parameter(p.name, p.kind, annotation=anno))
+        else:
+            params.append(inspect.Parameter(
+                p.name, inspect.Parameter.KEYWORD_ONLY,
+                default=typer.Option(p.default, help=f"{p.name}"), annotation=anno))
+    params.append(inspect.Parameter(
+        "db", inspect.Parameter.KEYWORD_ONLY,
+        default=typer.Option("stitchgraph.db", help="index database path"), annotation=str))
+    params.append(inspect.Parameter(
+        "json", inspect.Parameter.KEYWORD_ONLY,
+        default=typer.Option(False, "--json", help="emit the raw envelope as JSON"),
+        annotation=bool))
+    command.__signature__ = inspect.Signature(params)  # type: ignore[attr-defined]
+    command.__name__ = op.name
+    return command
+
+
+_ANNO_TYPES = {"str": str, "int": int, "float": float, "bool": bool}
+
+
+def _anno_type(annotation: Any) -> type:
+    """Resolve an operation param's annotation to a concrete type for Typer.
+
+    Annotations are JSON-simple (operations.exposed_params filters to those) but
+    arrive as strings under `from __future__ import annotations`; default to `str`
+    for anything unrecognised (e.g. `int | None`)."""
+    if isinstance(annotation, type):
+        return annotation if annotation in _ANNO_TYPES.values() else str
+    if isinstance(annotation, str):
+        base = annotation.replace("Optional[", "").replace("]", "").split("|")[0].strip()
+        return _ANNO_TYPES.get(base, str)
+    return str
+
+
+def _exit_code(result) -> int:
+    """scan-style exit codes (design §13.3): non-zero when red issues exist. Operational
+    failures (missing/unopenable --db) exit 2 at the command level (review 2026-07-03,
+    F10c); an op-level advisory refusal deliberately stays 0 — it IS a clean answer."""
+    from ..core.envelope import Urgency
+    if result.urgency is Urgency.RED:
+        return 1
+    return 0
+
+
+def main() -> None:
+    build_app()()
+
+
+if __name__ == "__main__":
+    main()

stitchgraph/adapters/mcp.py

@@ -0,0 +1,88 @@
+"""MCP adapter (design §3). Registers each core operation as an MCP tool by the
+same name, deriving the schema from the operation's signature + docstring.
+
+The MCP SDK is an optional dependency (`pip install stitchgraph[mcp]`); imported
+lazily so `import stitchgraph` never requires it.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from ..core.operations import Operation, registry
+from ._guard import open_store
+
+
+def _require_mcp():
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ModuleNotFoundError as exc:  # pragma: no cover
+        raise SystemExit(
+            "The MCP server needs the MCP SDK. Install it with: "
+            "pip install 'stitchgraph[mcp]'"
+        ) from exc
+    return FastMCP
+
+
+def build_server(db: str = "stitchgraph.db"):
+    FastMCP = _require_mcp()
+    server = FastMCP("stitchgraph")
+    for op in registry():
+        server.add_tool(_make_tool(op, db), name=op.name, description=op.summary)
+    return server
+
+
+def _make_tool(op: Operation, db: str):
+    """Wrap an operation as an MCP tool: open the store, call, return the envelope."""
+
+    def tool(**kwargs: Any) -> dict:
+        # Refuse (rather than silently create) a missing/never-indexed DB, and
+        # return an envelope instead of a raw sqlite traceback on an unopenable
+        # path (panel R12; review 2026-07-03, F2b).
+        store, refusal = open_store(db, op.name)
+        if refusal is not None:
+            return refusal.to_dict()
+        assert store is not None
+        with store:
+            result = op.func(store, **kwargs)
+        return result.to_dict()
+
+    # Expose only JSON-simple params (drop `store` and internal objects like
+    # `detector`, which pydantic can't schema-ify) — they fall back to defaults.
+    params = [
+        inspect.Parameter(p.name, inspect.Parameter.KEYWORD_ONLY,
+                          default=(p.default if p.default is not inspect.Parameter.empty
+                                   else inspect.Parameter.empty),
+                          annotation=(p.annotation if p.annotation is not inspect.Parameter.empty
+                                      else str))
+        for p in op.exposed_params()
+    ]
+    tool.__signature__ = inspect.Signature(params)  # type: ignore[attr-defined]
+    tool.__name__ = op.name
+    tool.__doc__ = op.summary
+    return tool
+
+
+def main() -> None:
+    """Entry point (`stitchgraph-mcp`). The DB path is configurable because MCP
+    clients launch servers with an arbitrary cwd — a hardcoded relative default
+    would resolve to the wrong directory and (pre-guard) answer from a fresh
+    empty index (review 2026-07-03, F2a). Precedence: --db > STITCHGRAPH_DB >
+    ./stitchgraph.db."""
+    import argparse
+    import os
+
+    parser = argparse.ArgumentParser(
+        prog="stitchgraph-mcp",
+        description="stitchgraph MCP server — code-intelligence tools for LLM agents")
+    parser.add_argument(
+        "--db",
+        default=os.environ.get("STITCHGRAPH_DB", "stitchgraph.db"),
+        help="index database path (env: STITCHGRAPH_DB; default: ./stitchgraph.db)")
+    args = parser.parse_args()
+    build_server(db=args.db).run()
+
+
+if __name__ == "__main__":
+    main()

stitchgraph/adapters/render.py

@@ -0,0 +1,56 @@
+"""Envelope -> human-readable text. Shared by the CLI and the report.
+
+Stdlib-only so it can render without any optional dependency installed.
+"""
+
+from __future__ import annotations
+
+from ..core.envelope import Result, Urgency
+
+_URGENCY_TAG = {Urgency.RED: "[RED]", Urgency.ORANGE: "[ORANGE]", Urgency.GREEN: "[GREEN]"}
+
+
+def render_text(op_name: str, result: Result) -> str:
+    lines: list[str] = []
+    status = "ok" if result.ok else "no result"
+    head = f"{op_name}: {status}  (confidence {result.confidence:.2f}, {result.provenance.value})"
+    if result.urgency:
+        head = f"{_URGENCY_TAG[result.urgency]} {head}"
+    lines.append(head)
+
+    if result.needs_review:
+        lines.append("  needs review:")
+        for reason in result.review_reasons:
+            lines.append(f"    - {reason}")
+
+    lines.append(_render_payload(result.result))
+
+    if result.alternatives:
+        lines.append(f"  alternatives: {len(result.alternatives)}")
+    if result.meta:
+        meta = ", ".join(f"{k}={v}" for k, v in result.meta.items())
+        lines.append(f"  ({meta})")
+    return "\n".join(lines)
+
+
+def _render_payload(payload: object, indent: str = "  ") -> str:
+    if payload is None:
+        return f"{indent}(none)"
+    if isinstance(payload, list):
+        if not payload:
+            return f"{indent}(empty)"
+        out = "\n".join(f"{indent}- {_one(item)}" for item in payload[:50])
+        if len(payload) > 50:
+            # Say the output was cut — silent truncation reads as "that's everything"
+            # (review 2026-07-03, F10e). --json always carries the full payload.
+            out += f"\n{indent}… {len(payload) - 50} more (use --json for the full list)"
+        return out
+    if isinstance(payload, dict):
+        return "\n".join(f"{indent}{k}: {_one(v)}" for k, v in payload.items())
+    return f"{indent}{payload}"
+
+
+def _one(item: object) -> str:
+    if isinstance(item, dict):
+        return ", ".join(f"{k}={v}" for k, v in item.items())
+    return str(item)

stitchgraph/adapters/report.py

@@ -0,0 +1,99 @@
+"""Report adapter (design §8): point at an index, get a Markdown report.
+
+The report is a fourth renderer over the same operations, organised into the
+urgency tiers (Fix now / Look closer / Cleanup). Stdlib-only.
+"""
+
+from __future__ import annotations
+
+from ..core import operations as ops
+from ._guard import open_store
+
+
+def build_report(db: str = "stitchgraph.db", repo: str | None = None) -> str:
+    # A missing/never-indexed or unopenable db yields a one-line report, not a raw
+    # sqlite traceback or a confidently-empty report (panel R12; review 2026-07-03 F2b).
+    store, refusal = open_store(db, "report")
+    if refusal is not None:
+        return f"# stitchgraph report\n\n{'; '.join(refusal.review_reasons)}\n"
+    assert store is not None
+    with store:
+        orient = ops.orient(store)
+        scan = ops.scan(store)
+        stale = ops.find_stale(store)
+        # repo=None lets risk() default to the indexed root recorded in the DB, so
+        # `report --db <db>` includes the risk section from any cwd (issue #18).
+        risk = ops.risk(store, repo)
+
+    issues = scan.result or []
+    by_urgency = {u: [i for i in issues if i["urgency"] == u]
+                  for u in ("red", "orange", "green")}
+
+    out: list[str] = ["# stitchgraph report", ""]
+
+    out += ["## Orientation", ""]
+    counts = (orient.result or {}).get("node_counts", {})
+    out.append(f"- Nodes indexed: {orient.meta.get('total_nodes', 0)}")
+    out.append(f"- By kind: {counts or '(none)'}")
+    hubs = (orient.result or {}).get("top_hubs", [])
+    out.append("- Read these first (hubs): "
+               f"{[h['id'].split('::')[-1] for h in hubs[:8]] or '(none)'}")
+    out.append("")
+
+    out += ["## \U0001f534 Fix now", ""]
+    _emit_issues(out, by_urgency["red"])
+
+    out += ["", "## \U0001f7e0 Look closer", ""]
+    _emit_issues(out, by_urgency["orange"])
+
+    out += ["", "## \U0001f7e2 Cleanup", ""]
+    stale_list = stale.result or []
+    out.append(f"- Stale code candidates: {len(stale_list)} "
+               f"(confidence {stale.confidence:.2f}, verify before removing)")
+    for c in stale_list[:20]:
+        out.append(f"  - {c['id']}")
+    if len(stale_list) > 20:
+        out.append(f"  - … {len(stale_list) - 20} more (run `stitchgraph find-stale --json`)")
+    _emit_issues(out, by_urgency["green"])
+
+    out += ["", "## Risk (git × structure)", ""]
+    if risk.ok:
+        hotspots = (risk.result or {}).get("hotspots", [])
+        hidden = (risk.result or {}).get("hidden_coupling", [])
+        for h in hotspots[:5]:
+            out.append(f"- {h['urgency']} {h['file']} "
+                       f"(churn {h['churn']}, risk {h['risk']})")
+        if hidden:
+            out.append(f"- Hidden coupling pairs: {len(hidden)} "
+                       "(co-change with no structural edge)")
+        # risk ran but found nothing notable (every churned file has zero centrality,
+        # no hidden coupling). Render an explicit marker so the section is never blank —
+        # mirrors how the Cleanup section reports an empty stale list (panels SS/TT).
+        if not hotspots and not hidden:
+            out.append("- (no risk hotspots or hidden coupling found)")
+    else:
+        out.append(f"- (skipped: {risk.review_reasons[0] if risk.review_reasons else 'no git'})")
+
+    return "\n".join(out)
+
+
+def _emit_issues(out: list[str], issues: list[dict]) -> None:
+    if not issues:
+        out.append("- (none)")
+        return
+    for i in issues[:25]:
+        node = i.get("node", "").split("::")[-1]
+        out.append(f"- **{i['kind']}** `{node}` — {i.get('reason', '')}")
+    if len(issues) > 25:
+        out.append(f"- … {len(issues) - 25} more (run `stitchgraph scan --json`)")
+
+
+def main() -> None:
+    import sys
+    db = sys.argv[1] if len(sys.argv) > 1 else "stitchgraph.db"
+    repo = sys.argv[2] if len(sys.argv) > 2 else None
+    print(build_report(db, repo))
+
+
+if __name__ == "__main__":
+    main()

stitchgraph/core/__init__.py

@@ -0,0 +1,12 @@
+"""stitchgraph core — pure, stdlib-only. Never imports CLI/MCP libraries."""
+
+from .envelope import Provenance, Result, Urgency, ok, refuse
+from .model import Edge, Node, NodeKind, Relation
+from .operations import Operation, registry
+from .store import Store
+
+__all__ = [
+    "Provenance", "Result", "Urgency", "ok", "refuse",
+    "Edge", "Node", "NodeKind", "Relation",
+    "Operation", "registry", "Store",
+]

stitchgraph/core/_scc.py

@@ -0,0 +1,60 @@
+"""Tarjan strongly-connected-components — shared core.
+
+Extracted in v2.3.0: the SCC algorithm was duplicated verbatim in `reach.py` (call / import
+cycles) and `dataloop.py` (data-feedback loops). The two call sites differ only in how they
+build the adjacency and what they do with the result — the *core* (a recursive Tarjan under a
+temporarily-raised recursion limit) is identical — so it lives here once.
+
+`tarjan_scc` is behaviour-preserving: same component output, same iteration order (driven by the
+caller-supplied `seeds`), same recursion-limit handling (raised for deep graphs, restored in a
+`finally` so a raised limit never leaks to the host — panel QQQ LOW).
+"""
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable, Mapping, Sequence
+
+
+def tarjan_scc(
+    adj: Mapping[str, Sequence[str]], seeds: Iterable[str], node_count: int,
+) -> list[list[str]]:
+    """Tarjan's SCC over `adj`, visiting `seeds` in order. `node_count` sizes the temporary
+    recursion-limit raise for deep graphs. Returns components in reverse-topological order."""
+    index: dict[str, int] = {}
+    low: dict[str, int] = {}
+    on_stack: set[str] = set()
+    stack: list[str] = []
+    counter = [0]
+    out: list[list[str]] = []
+
+    _old_limit = sys.getrecursionlimit()
+    sys.setrecursionlimit(max(10000, node_count * 4 + 1000))
+
+    def strongconnect(v: str) -> None:
+        index[v] = low[v] = counter[0]
+        counter[0] += 1
+        stack.append(v)
+        on_stack.add(v)
+        for w in adj.get(v, ()):
+            if w not in index:
+                strongconnect(w)
+                low[v] = min(low[v], low[w])
+            elif w in on_stack:
+                low[v] = min(low[v], index[w])
+        if low[v] == index[v]:
+            comp: list[str] = []
+            while True:
+                w = stack.pop()
+                on_stack.discard(w)
+                comp.append(w)
+                if w == v:
+                    break
+            out.append(comp)
+
+    try:
+        for v in seeds:
+            if v not in index:
+                strongconnect(v)
+    finally:
+        sys.setrecursionlimit(_old_limit)
+    return out