sembl-stack 0.1.0__py3-none-any.whl

sembl_stack/config.py

@@ -0,0 +1,87 @@
+"""Load sembl.stack.yaml and resolve it into wired-up adapters."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from . import registry
+
+DEFAULTS = {
+    "layers": {"spec": "sembl", "execute": "mock",
+               "sandbox": "worktree", "verify": "sembl", "context": "none",
+               "codegraph": "cbm", "review": "mock",
+               "merge": "git", "deploy": "vercel", "postdeploy": "http"},
+    "transport": {"spec": "mcp", "verify": "mcp",
+                  "mcp_server": ["uvx", "--from", "sembl[mcp]", "sembl-mcp"]},
+    "loop": {"max_attempts": 3, "strict": True},
+    "tracing": {"langfuse": False},
+}
+
+
+@dataclass
+class StackConfig:
+    spec: object
+    execute: object
+    sandbox: object
+    verify: object
+    context: object = None
+    codegraph: object = None
+    review: object = None
+    merge: object = None
+    deploy: object = None
+    postdeploy: object = None
+    max_attempts: int = 3
+    strict: bool = True
+    langfuse: bool = False
+    raw: dict = field(default_factory=dict)
+
+
+def _merge(base: dict, over: dict) -> dict:
+    out = dict(base)
+    for k, v in (over or {}).items():
+        out[k] = _merge(base[k], v) if isinstance(v, dict) and isinstance(base.get(k), dict) else v
+    return out
+
+
+def load(path: str | None, overrides: dict | None = None) -> StackConfig:
+    """Resolve DEFAULTS < overrides < file. `overrides` is where the onboarding profile
+    plugs in (profile.to_stack_overrides) — passed explicitly by the caller, never read
+    from global state here, so resolution stays deterministic and testable. An explicit
+    sembl.stack.yaml always wins over a profile."""
+    cfg = _merge(DEFAULTS, overrides or {})
+    if path and Path(path).is_file():
+        cfg = _merge(cfg, yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {})
+
+    layers = cfg["layers"]
+    tr = cfg["transport"]
+    server = tr.get("mcp_server", DEFAULTS["transport"]["mcp_server"])
+    opts = cfg.get("options", {})   # per-layer adapter knobs (e.g. execute.model)
+
+    return StackConfig(
+        spec=registry.build("spec", layers["spec"], tr.get("spec", "mcp"), server,
+                            opts.get("spec")),
+        execute=registry.build("execute", layers["execute"], "cli", server,
+                               opts.get("execute")),
+        sandbox=registry.build("sandbox", layers["sandbox"], "cli", server,
+                               opts.get("sandbox")),
+        verify=registry.build("verify", layers["verify"], tr.get("verify", "mcp"), server,
+                              opts.get("verify")),
+        context=registry.build("context", layers.get("context", "none"), "cli", server,
+                               opts.get("context")),
+        codegraph=registry.build("codegraph", layers.get("codegraph", "cbm"), "cli", server,
+                                 opts.get("codegraph")),
+        review=registry.build("review", layers.get("review", "mock"), "cli", server,
+                              opts.get("review")),
+        merge=registry.build("merge", layers.get("merge", "git"), "cli", server,
+                             opts.get("merge")),
+        deploy=registry.build("deploy", layers.get("deploy", "vercel"), "cli", server,
+                              opts.get("deploy")),
+        postdeploy=registry.build("postdeploy", layers.get("postdeploy", "http"), "cli",
+                                  server, opts.get("postdeploy")),
+        max_attempts=cfg["loop"]["max_attempts"],
+        strict=cfg["loop"]["strict"],
+        langfuse=cfg["tracing"]["langfuse"],
+        raw=cfg,
+    )

sembl_stack/contextgraph.py

@@ -0,0 +1,154 @@
+"""L1 Context: a swappable semantic code graph + graph-based bounds expansion.
+
+Two contender tools (both local, deterministic, MIT) sit behind one protocol:
+  * symgraph  (Rust; tree-sitter + SQLite; `--format json`; has a file-level module
+    dependency graph) — the default.
+  * codegraph (Node; tree-sitter + SQLite/FTS5) — a second adapter (TODO).
+
+The capability the gate actually needs is **bounds expansion**: given the seed paths a
+spec/issue names, add the files they are genuinely coupled to (the dependency closure),
+so a legitimate multi-file change does not false-alarm the scope check. EXP-04 showed the
+scope check over-fires precisely because a real fix touches sibling modules the spec never
+named; the coupling graph recovers exactly those. (It does NOT recover changelog/docs/test
+files — those are not code edges and are handled by the separate docs-auto-in-scope rule.)
+
+`expand_paths()` is a pure function over a file graph, so it is unit-testable without the
+binary; the adapter only has to produce the graph.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass
+class FileGraph:
+    """A directed file-dependency graph: edge from -> to means `from` uses `to`."""
+    nodes: list[str] = field(default_factory=list)
+    edges: list[dict] = field(default_factory=list)   # {"from","to","strength",...}
+
+    def neighbors(self, path: str, min_strength: int = 0) -> set[str]:
+        """Files directly coupled to `path` in EITHER direction (callers + callees)."""
+        out: set[str] = set()
+        for e in self.edges:
+            if e.get("strength", 1) < min_strength:
+                continue
+            if e["from"] == path:
+                out.add(e["to"])
+            elif e["to"] == path:
+                out.add(e["from"])
+        return out
+
+
+class ContextGraph(Protocol):
+    def available(self) -> bool: ...
+    def index(self, repo: str) -> None: ...
+    def file_graph(self, repo: str) -> FileGraph: ...
+
+
+# --- helpers ------------------------------------------------------------------
+
+def _norm(p: str) -> str:
+    return p.replace("\\", "/").strip().lstrip("./")
+
+
+def expand_paths(seed: list[str], graph: FileGraph, *, hops: int = 1,
+                 min_strength: int = 0, max_fraction: float = 0.4) -> list[str]:
+    """Grow a seed set of files along the coupling graph, up to `hops` away.
+
+    Returns the union of the seed and every file reachable within `hops` edges of any seed
+    file (whose coupling strength clears `min_strength`). Deterministic; the seed is always
+    included even if it has no edges.
+
+    Defaults are deliberately conservative (EXP-05): `hops=1` keeps the closure tight
+    (~10-22% of a real repo) while still recovering a third to a half of the legitimate
+    sibling files; two hops balloons to ~the whole repo and destroys the gate. The
+    `max_fraction` cap is the safety net for small, densely-cyclic repos (e.g. flask) where
+    even one hop engulfs the codebase: if the closure would exceed `max_fraction` of the
+    indexed files, expansion is **abandoned and the bare seed is returned** — better a
+    noisier scope check than a gate that silently whitelists everything.
+    """
+    seed_n = {_norm(p) for p in seed if p}
+    g = FileGraph(
+        nodes=[_norm(n) for n in graph.nodes],
+        edges=[{**e, "from": _norm(e["from"]), "to": _norm(e["to"])} for e in graph.edges],
+    )
+    frontier = set(seed_n)
+    seen = set(seed_n)
+    for _ in range(max(0, hops)):
+        nxt: set[str] = set()
+        for f in frontier:
+            nxt |= g.neighbors(f, min_strength)
+        nxt -= seen
+        if not nxt:
+            break
+        seen |= nxt
+        frontier = nxt
+    if g.nodes and len(seen) > max_fraction * len(g.nodes):
+        return sorted(seed_n)   # too dense to be informative — don't whitelist the repo
+    return sorted(seen)
+
+
+def _under(path: str, prefix: str) -> bool:
+    path, prefix = _norm(path), _norm(prefix).rstrip("/")
+    return path == prefix or path.startswith(prefix + "/")
+
+
+def expand_bounds(editable_paths: list[str], graph: FileGraph, *, hops: int = 1,
+                  min_strength: int = 0, max_fraction: float = 0.4) -> list[str]:
+    """Expand a bounds `editable_paths` list along the coupling graph (EXP-05).
+
+    Each declared path (file or directory prefix) seeds the indexed files it covers; those
+    are grown one hop (by default) into their coupling closure. The ORIGINAL entries are
+    always preserved (so directory bounds keep working even if no file under them is
+    indexed); the recovered sibling FILES are added. Returns a de-duplicated, sorted list.
+    """
+    seed_files = [n for n in graph.nodes
+                  if any(_under(n, p) for p in editable_paths)]
+    if not seed_files:
+        return sorted({_norm(p) for p in editable_paths})
+    grown = expand_paths(seed_files, graph, hops=hops, min_strength=min_strength,
+                         max_fraction=max_fraction)
+    return sorted({_norm(p) for p in editable_paths} | set(grown))
+
+
+# --- symgraph adapter ---------------------------------------------------------
+
+class SymgraphGraph:
+    """Drives the `symgraph` Rust binary. Index once, then read the file module-graph."""
+
+    def __init__(self, binary: str = "symgraph", timeout: int = 300):
+        self.binary = binary
+        self.timeout = timeout
+
+    def _exe(self) -> str | None:
+        return shutil.which(self.binary)
+
+    def available(self) -> bool:
+        return self._exe() is not None
+
+    def _run(self, args: list[str], repo: str) -> subprocess.CompletedProcess:
+        exe = self._exe()
+        if not exe:
+            raise RuntimeError(
+                f"L1: `{self.binary}` not found on PATH. Install it, or disable graph expansion.")
+        return subprocess.run([exe, *args], cwd=repo, capture_output=True,
+                              text=True, timeout=self.timeout)
+
+    def index(self, repo: str) -> None:
+        self._run(["index", "."], repo)
+
+    def file_graph(self, repo: str) -> FileGraph:
+        proc = self._run(
+            ["module-graph", "--granularity", "file", "--format", "json"], repo)
+        try:
+            data = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            return FileGraph()
+        return FileGraph(
+            nodes=[n["id"] for n in data.get("nodes", [])],
+            edges=data.get("edges", []),
+        )

sembl_stack/doctor.py

@@ -0,0 +1,111 @@
+"""`doctor` (C4) — a config-aware environment preflight.
+
+A stranger's first failure should be a clear diagnosis, not a stack trace. `run_checks`
+inspects only what the (optional) config actually uses — it won't fail on a missing `claude`
+when `execute: mock` — and returns structured `Check`s with actionable hints. The checks are
+pure (no side effects) and don't import the heavy optionals, so they're unit-testable by
+monkeypatching `shutil.which` / `find_spec`.
+"""
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sys
+from dataclasses import dataclass
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    hint: str = ""
+    required: bool = True       # an optional check that's missing -> WARN, not failure
+
+
+def _have_module(name: str) -> bool:
+    try:
+        return importlib.util.find_spec(name) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+# executor layer name -> (binary on PATH, install hint)
+_EXECUTOR_BINARY = {
+    "claude": ("claude", "install Claude Code and log in (`claude`)"),
+    "aider": ("aider", "`pip install aider-chat` and set your model env (OPENAI_API_KEY…)"),
+    "opencode": ("opencode", "install OpenCode and ensure `opencode` is on PATH"),
+}
+
+
+def run_checks(cfg=None) -> list[Check]:
+    """Structured preflight. `cfg` is an optional loaded StackConfig (config-aware checks)."""
+    layers = (getattr(cfg, "raw", {}) or {}).get("layers", {}) if cfg else {}
+    transport = (getattr(cfg, "raw", {}) or {}).get("transport", {}) if cfg else {}
+    checks: list[Check] = []
+
+    # --- always required ---
+    py_ok = sys.version_info >= (3, 10)
+    checks.append(Check(
+        "python", py_ok, f"{sys.version_info.major}.{sys.version_info.minor}",
+        "" if py_ok else "sembl-stack needs Python >= 3.10"))
+    checks.append(Check(
+        "git", shutil.which("git") is not None,
+        shutil.which("git") or "not found", "install git (the sandbox clones the repo)"))
+
+    # The gate (sembl) is the heart of the factory — required whenever verify=sembl.
+    sembl_ok = _have_module("sembl")
+    checks.append(Check(
+        "sembl (gate)", sembl_ok, "importable" if sembl_ok else "missing",
+        "" if sembl_ok else "`pip install sembl` into this environment", required=True))
+
+    # --- transport-dependent (only when MCP transport is selected) ---
+    uses_mcp = "mcp" in (transport.get("spec"), transport.get("verify"))
+    if uses_mcp or cfg is None:
+        mcp_ok = _have_module("mcp")
+        checks.append(Check(
+            "mcp (transport)", mcp_ok, "importable" if mcp_ok else "missing",
+            "`pip install \"sembl[mcp]\"` — or use transport: cli (no MCP needed)",
+            required=uses_mcp))
+        server = transport.get("mcp_server", []) if cfg else ["uvx"]
+        if server and server[0] == "uvx":
+            uvx_ok = shutil.which("uvx") is not None
+            checks.append(Check(
+                "uvx (mcp launcher)", uvx_ok, shutil.which("uvx") or "not found",
+                "install uv (`pip install uv`) — or point mcp_server at a local `sembl-mcp`",
+                required=uses_mcp))
+
+    # --- orchestration (optional: the loop has a zero-dep fallback) ---
+    lg_ok = _have_module("langgraph")
+    checks.append(Check(
+        "langgraph (orchestration)", lg_ok, "importable" if lg_ok else "missing",
+        "optional — the loop falls back to a built-in runner; `pip install langgraph` for "
+        "the real retry graph", required=False))
+
+    # --- executor binary (only the one the config actually selects) ---
+    execute = layers.get("execute", "mock")
+    if execute in _EXECUTOR_BINARY:
+        binary, hint = _EXECUTOR_BINARY[execute]
+        present = shutil.which(binary) is not None
+        checks.append(Check(
+            f"executor: {execute}", present, shutil.which(binary) or "not found",
+            "" if present else hint, required=True))
+    elif execute == "mock":
+        checks.append(Check("executor: mock", True, "no binary needed", required=False))
+
+    # --- context graph (only when context: symgraph) ---
+    if layers.get("context") == "symgraph":
+        sg_ok = shutil.which("symgraph") is not None
+        checks.append(Check(
+            "context: symgraph", sg_ok, shutil.which("symgraph") or "not found",
+            "optional — `cargo install symgraph`; only needed for bounds --expand",
+            required=False))
+
+    return checks
+
+
+def summarize(checks: list[Check]) -> tuple[bool, list[Check], list[Check]]:
+    """Return (ready, blocking_failures, optional_warnings)."""
+    blocking = [c for c in checks if c.required and not c.ok]
+    warnings = [c for c in checks if not c.required and not c.ok]
+    return (not blocking), blocking, warnings