dev-guru 0.1.0__py3-none-any.whl

dev_guru/__init__.py

@@ -0,0 +1,21 @@
+"""Dev Guru: a local-first developer product on the Ananke Plexus harness."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from dev_guru.version import __version__
+
+if TYPE_CHECKING:
+    from dev_guru.sdk import GuruClient
+
+__all__ = ["GuruClient", "__version__"]
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy, so `import dev_guru` stays cheap and submodules never import the package's SDK back (no cycle).
+    if name == "GuruClient":
+        from dev_guru.sdk import GuruClient
+
+        return GuruClient
+    raise AttributeError(f"module 'dev_guru' has no attribute {name!r}")

dev_guru/__main__.py

@@ -0,0 +1,3 @@
+from dev_guru.cli import app
+
+app()

dev_guru/cli.py

@@ -0,0 +1,149 @@
+"""The ``dev`` command. CLI and SDK share one service layer (dev_guru.service)."""
+
+from __future__ import annotations
+
+import json
+import platform
+import webbrowser
+from importlib import metadata
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from dev_guru import errors, service
+from dev_guru.client import TRANSPORTS, connect
+from dev_guru.version import __version__
+
+app = typer.Typer(
+    name="dev",
+    help="Dev Guru: understand, improve and verify your software, on the Ananke Plexus harness.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err = Console(stderr=True)
+TransportOpt = Annotated[str, typer.Option(help=f"Harness transport: {', '.join(TRANSPORTS)}")]
+JsonOpt = Annotated[bool, typer.Option("--json", help="Machine-readable output")]
+
+
+def _version(value: bool) -> None:
+    if value:
+        console.print(f"dev-guru {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version, is_eager=True, help="Show the version and exit"
+        ),
+    ] = False,
+) -> None:
+    """Dev Guru: understand, improve and verify your software, on the Ananke Plexus harness."""
+
+
+def _fail(exc: errors.GuruError, as_json: bool, code: int) -> None:
+    if as_json:
+        console.print_json(json.dumps({"ok": False, "error": exc.to_dict()}))
+    else:
+        err.print(f"[red]✗ {exc.code}: {exc.message}[/red]")
+        if exc.hint:
+            err.print(f"  [dim]{exc.hint}[/dim]")
+    raise typer.Exit(code) from exc
+
+
+def _optional(distribution: str) -> str | None:
+    try:
+        return metadata.version(distribution)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+@app.command()
+def doctor(transport: TransportOpt = "in-process", as_json: JsonOpt = False) -> None:
+    """Check the Ananke harness: installed version, supported range and the capabilities Dev Guru needs.
+
+    Exits 1 when the harness is missing or incompatible, 2 for an unknown transport.
+    """
+    try:
+        info = connect(transport).info()
+    except errors.GuruError as exc:
+        _fail(exc, as_json, 2)
+        return
+    dex = _optional("dex-trove")
+    report = {
+        "ok": info.compatible,
+        "dev_guru": __version__,
+        "python": platform.python_version(),
+        "harness": info.model_dump(),
+        "optional": {"dex-trove": dex},
+    }
+    if as_json:
+        console.print_json(json.dumps(report))
+    else:
+        mark = "[green]✓[/green]" if info.compatible else "[red]✗[/red]"
+        console.print(
+            f"dev-guru {__version__} · Python {report['python']} · transport {info.transport}"
+        )
+        console.print(
+            f"{mark} ananke-plexus {info.ananke_version or 'not installed'} (supported {info.supported_range})"
+        )
+        for cap, present in info.capabilities.items():
+            console.print(f"  {'✓' if present else '✗'} {cap}")
+        for reason in info.reasons:
+            console.print(f"  [red]{reason}[/red]")
+        console.print(f"  [dim]dex-trove: {dex or 'not installed (optional)'}[/dim]")
+    if not info.compatible:
+        raise typer.Exit(1)
+
+
+@app.command()
+def explore(
+    workspace: Annotated[Path, typer.Argument(help="Project to explore")] = Path("."),
+    output: Annotated[
+        Path, typer.Option("--output", "-o", help="Report file (a manifest is written next to it)")
+    ] = Path("dev-guru-explorer.html"),
+    name: Annotated[str | None, typer.Option(help="Project name shown in the report")] = None,
+    open_browser: Annotated[
+        bool, typer.Option("--open", help="Open the report when it's written")
+    ] = False,
+    transport: TransportOpt = "in-process",
+    as_json: JsonOpt = False,
+) -> None:
+    """Explore a codebase: Ananke builds the graph, Dev Guru writes an interactive, offline HTML explorer.
+
+    The report is one file with no network access: architecture constellation, dependency flow, impact rings,
+    call graph, hotspots, a guided tour, search and a source inspector.
+    """
+    try:
+        result = service.explore(workspace, client=connect(transport), name=name)
+        page, sidecar = service.export_html(result, output)
+    except errors.GuruError as exc:
+        _fail(exc, as_json, 1)
+        return
+    project = result.model["project"]
+    summary = {
+        "ok": True,
+        "report": str(page),
+        "manifest": str(sidecar),
+        "input_digest": result.manifest["input_digest"],
+        "project": project,
+        "insights": {k: len(v) for k, v in result.model["insights"].items()},
+    }
+    if as_json:
+        console.print_json(json.dumps(summary))
+    else:
+        console.print(
+            f"[green]✓[/green] {project['files']} files · {project['symbols']} symbols · "
+            f"{project['imports']} imports · {project['calls']} calls → {page}"
+        )
+        cycles = len(result.model["insights"]["cycles"])
+        if cycles:
+            console.print(f"  [yellow]{cycles} import cycle(s) found; see the Flow view[/yellow]")
+        console.print(f"  [dim]manifest {sidecar} · {result.manifest['input_digest'][:19]}…[/dim]")
+    if open_browser:
+        webbrowser.open(page.resolve().as_uri())

dev_guru/client/__init__.py

@@ -0,0 +1,22 @@
+"""The Ananke client port. Use :func:`connect` to get a client for one explicit transport."""
+
+from __future__ import annotations
+
+from dev_guru import errors
+from dev_guru.client.inprocess import InProcessAnanke
+from dev_guru.client.port import AnankeClient, GraphData, GraphSummary, HarnessInfo
+
+TRANSPORTS = ("in-process",)  # planned: "process" (isolated executable), "gateway" (local HTTP)
+
+
+def connect(transport: str = "in-process") -> AnankeClient:
+    """A client for exactly ``transport``. An unknown or unavailable transport is an error, not a fallback."""
+    if transport == "in-process":
+        return InProcessAnanke()
+    raise errors.GuruError(
+        errors.UNSUPPORTED_TRANSPORT,
+        f"transport {transport!r} is not supported; supported: {', '.join(TRANSPORTS)}",
+    )
+
+
+__all__ = ["TRANSPORTS", "AnankeClient", "GraphData", "GraphSummary", "HarnessInfo", "connect"]

dev_guru/client/inprocess.py

@@ -0,0 +1,122 @@
+"""In-process transport: calls the installed ``ananke-plexus`` package through its public facade."""
+
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+import dev_guru.client.negotiation as negotiation
+from dev_guru import errors
+from dev_guru.client.port import GraphData, GraphEdgeData, GraphNodeData, GraphSummary, HarnessInfo
+
+
+class InProcessAnanke:
+    transport = "in-process"
+
+    def info(self) -> HarnessInfo:
+        version = negotiation.installed_version()
+        if version is None:
+            return HarnessInfo(
+                transport=self.transport,
+                ananke_version=None,
+                supported_range=negotiation.SUPPORTED_ANANKE,
+                compatible=False,
+                reasons=["ananke-plexus is not installed in this environment"],
+            )
+        caps = negotiation.probe()
+        missing = [c for c in negotiation.REQUIRED if not caps.get(c)]
+        reasons: list[str] = []
+        if not negotiation.supported(version):
+            reasons.append(
+                f"ananke-plexus {version} is outside the supported range {negotiation.SUPPORTED_ANANKE}"
+            )
+        if missing:
+            reasons.append(f"required harness capabilities are missing: {', '.join(missing)}")
+        return HarnessInfo(
+            transport=self.transport,
+            ananke_version=version,
+            supported_range=negotiation.SUPPORTED_ANANKE,
+            compatible=not reasons,
+            capabilities=caps,
+            missing_required=missing,
+            reasons=reasons,
+        )
+
+    def require_compatible(self) -> HarnessInfo:
+        info = self.info()
+        if info.ananke_version is None:
+            raise errors.GuruError(
+                errors.HARNESS_MISSING,
+                "Ananke Plexus is not installed",
+                hint="pip install 'ananke-plexus" + negotiation.SUPPORTED_ANANKE + "'",
+            )
+        if info.missing_required:
+            raise errors.GuruError(errors.CAPABILITY_MISSING, "; ".join(info.reasons))
+        if not info.compatible:
+            raise errors.GuruError(
+                errors.HARNESS_INCOMPATIBLE,
+                "; ".join(info.reasons),
+                hint=f"install ananke-plexus{negotiation.SUPPORTED_ANANKE}",
+            )
+        return info
+
+    def graph_data(self, workspace: Path) -> GraphData:
+        """Ask Ananke to build the workspace graph and return the snapshot it stored."""
+        info = self.require_compatible()
+        root = workspace.expanduser().resolve()
+        if not root.is_dir():
+            raise errors.GuruError(errors.WORKSPACE_INVALID, f"workspace {root} is not a directory")
+        from ananke.plexus.api import Ananke
+        from ananke.plexus.graph.service import load_graph
+
+        result = Ananke.open(root).graph_build()
+        if not result.ok:
+            raise errors.GuruError(
+                errors.HARNESS_FAILED, f"Ananke could not build the graph: {result.summary}"
+            )
+        snapshot = load_graph(root)
+        if (
+            snapshot is None
+        ):  # a "successful" build with nothing stored is a harness fault, not an empty graph
+            raise errors.GuruError(
+                errors.HARNESS_FAILED, "Ananke reported a graph build but stored no snapshot"
+            )
+        return GraphData(
+            snapshot_id=snapshot.snapshot_id,
+            provider=snapshot.provider,
+            ananke_version=info.ananke_version,
+            nodes=[
+                GraphNodeData(
+                    id=n.node_id, kind=n.kind, name=n.name, path=n.path, metadata=dict(n.metadata)
+                )
+                for n in snapshot.nodes
+            ],
+            edges=[
+                GraphEdgeData(
+                    source=e.source,
+                    target=e.target,
+                    kind=e.kind,
+                    origin=e.origin,
+                    confidence=e.confidence,
+                    location=e.source_location,
+                )
+                for e in snapshot.edges
+            ],
+            source=str(result.details.get("path", "")),
+        )
+
+    def graph_summary(self, workspace: Path) -> GraphSummary:
+        """Ask Ananke to build the workspace graph, then summarise the snapshot it stored."""
+        data = self.graph_data(workspace)
+        return GraphSummary(
+            snapshot_id=data.snapshot_id,
+            provider=data.provider,
+            nodes=len(data.nodes),
+            edges=len(data.edges),
+            nodes_by_kind=dict(sorted(Counter(n.kind for n in data.nodes).items())),
+            edges_by_kind=dict(sorted(Counter(e.kind for e in data.edges).items())),
+            source=data.source,
+        )
+
+
+__all__ = ["InProcessAnanke"]

dev_guru/client/negotiation.py

@@ -0,0 +1,69 @@
+"""Which Ananke Plexus this Dev Guru supports, and what the installed one can do.
+
+Negotiation is explicit: Dev Guru reads the installed harness version, checks it against ``SUPPORTED_ANANKE`` and
+probes the specific interfaces it calls. An out-of-range or incomplete harness is an error with a stable code,
+never a silent downgrade.
+"""
+
+from __future__ import annotations
+
+import importlib
+import re
+from importlib import metadata
+
+SUPPORTED_ANANKE = ">=0.3.12,<0.4"  # keep in step with pyproject.toml (tests/test_packaging.py)
+_MIN = (0, 3, 12)
+_BELOW = (0, 4, 0)
+
+# Capability id -> (module, attribute path). Required ones are what this release of Dev Guru calls.
+CAPABILITIES: dict[str, tuple[str, str]] = {
+    "graph.build": ("ananke.plexus.api", "Ananke.graph_build"),
+    "graph.load": ("ananke.plexus.graph.service", "load_graph"),
+    "graph.impact": ("ananke.plexus.api", "Ananke.graph_impact"),
+    "run.status": ("ananke.plexus.api", "Ananke.run_status"),
+    "spec.create": ("ananke.plexus.api", "Ananke.create_spec"),
+    "registry.open": ("ananke.plexus.registry.registry", "Registry.open"),
+}
+REQUIRED = ("graph.build", "graph.load")
+
+
+def parse_version(text: str) -> tuple[int, int, int] | None:
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)", text.strip())
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else None
+
+
+def supported(version: str) -> bool:
+    parsed = parse_version(version)
+    return parsed is not None and _MIN <= parsed < _BELOW
+
+
+def installed_version(distribution: str = "ananke-plexus") -> str | None:
+    try:
+        return metadata.version(distribution)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def probe(capabilities: dict[str, tuple[str, str]] = CAPABILITIES) -> dict[str, bool]:
+    """Which capabilities the importable harness exposes (imports only; nothing runs)."""
+    found: dict[str, bool] = {}
+    for cap, (module, attr_path) in capabilities.items():
+        try:
+            obj: object = importlib.import_module(module)
+            for part in attr_path.split("."):
+                obj = getattr(obj, part)
+            found[cap] = callable(obj)
+        except (ImportError, AttributeError):
+            found[cap] = False
+    return found
+
+
+__all__ = [
+    "CAPABILITIES",
+    "REQUIRED",
+    "SUPPORTED_ANANKE",
+    "installed_version",
+    "parse_version",
+    "probe",
+    "supported",
+]

dev_guru/client/port.py

@@ -0,0 +1,87 @@
+"""The one port between Dev Guru and the Ananke harness.
+
+Dev Guru never analyses code itself: every domain operation goes through an :class:`AnankeClient`. Today there is
+one transport (``in-process``: the installed ``ananke-plexus`` package). An isolated executable and a local HTTP
+gateway are planned. Exactly one transport is chosen per run and recorded; a failing transport is reported, never
+silently swapped for another (docs/decisions/0001-ananke-client-port.md).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+
+class HarnessInfo(BaseModel):
+    """What negotiation found: the transport, harness version, support verdict and capabilities."""
+
+    transport: str
+    ananke_version: str | None
+    supported_range: str
+    compatible: bool
+    capabilities: dict[str, bool] = Field(default_factory=dict)
+    missing_required: list[str] = Field(default_factory=list)
+    reasons: list[str] = Field(default_factory=list)
+
+
+class GraphSummary(BaseModel):
+    """A bounded projection of an Ananke graph snapshot. Ananke keeps the snapshot itself."""
+
+    snapshot_id: str
+    provider: str
+    nodes: int
+    edges: int
+    nodes_by_kind: dict[str, int] = Field(default_factory=dict)
+    edges_by_kind: dict[str, int] = Field(default_factory=dict)
+    source: str  # where Ananke stored the snapshot (Ananke-owned workspace state)
+
+
+class GraphNodeData(BaseModel):
+    id: str
+    kind: str
+    name: str
+    path: str = ""
+    metadata: dict[str, object] = Field(default_factory=dict)
+
+
+class GraphEdgeData(BaseModel):
+    source: str
+    target: str
+    kind: str
+    origin: str = "extracted"
+    confidence: float = 1.0
+    location: str = ""
+
+
+class GraphData(BaseModel):
+    """The graph Ananke built, as plain data. Dev Guru projects it; it never adds analysis of its own."""
+
+    snapshot_id: str
+    provider: str
+    ananke_version: str | None
+    nodes: list[GraphNodeData] = Field(default_factory=list)
+    edges: list[GraphEdgeData] = Field(default_factory=list)
+    source: str = ""
+
+
+@runtime_checkable
+class AnankeClient(Protocol):
+    transport: str
+
+    def info(self) -> HarnessInfo: ...
+
+    def graph_summary(self, workspace: Path) -> GraphSummary: ...
+
+    def graph_data(self, workspace: Path) -> GraphData: ...
+
+
+__all__ = [
+    "AnankeClient",
+    "GraphData",
+    "GraphEdgeData",
+    "GraphNodeData",
+    "GraphSummary",
+    "HarnessInfo",
+]

dev_guru/errors.py

@@ -0,0 +1,44 @@
+"""Errors with stable codes, so the CLI, the SDK and later the web UI report failures the same way."""
+
+from __future__ import annotations
+
+# Stable codes: callers and tests branch on these, never on message text.
+HARNESS_MISSING = "HARNESS_MISSING"
+HARNESS_INCOMPATIBLE = "HARNESS_INCOMPATIBLE"
+CAPABILITY_MISSING = "CAPABILITY_MISSING"
+UNSUPPORTED_TRANSPORT = "UNSUPPORTED_TRANSPORT"
+WORKSPACE_INVALID = "WORKSPACE_INVALID"
+HARNESS_FAILED = "HARNESS_FAILED"
+CODES = frozenset(
+    {
+        HARNESS_MISSING,
+        HARNESS_INCOMPATIBLE,
+        CAPABILITY_MISSING,
+        UNSUPPORTED_TRANSPORT,
+        WORKSPACE_INVALID,
+        HARNESS_FAILED,
+    }
+)
+
+
+class GuruError(Exception):
+    """A failure Dev Guru can explain: a stable ``code``, a message, an optional hint and run id."""
+
+    def __init__(
+        self, code: str, message: str, *, hint: str = "", run_id: str | None = None
+    ) -> None:
+        if code not in CODES:
+            raise ValueError(f"unknown error code {code!r}")
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint
+        self.run_id = run_id
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "hint": self.hint,
+            "run_id": self.run_id,
+        }

dev_guru/reports/__init__.py

@@ -0,0 +1 @@
+"""Report view models and renderers. Presentation only: the analysis comes from Ananke."""