forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/graph/edge.py

@@ -0,0 +1,19 @@
+"""Edge value type for the code graph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from forgecli.graph.node import EdgeKind
+
+
+@dataclass(frozen=True)
+class Edge:
+    """A directed edge in the code graph."""
+
+    source: str
+    target: str
+    kind: EdgeKind
+    weight: float = 1.0
+    extra: dict[str, Any] = field(default_factory=dict)

forgecli/graph/graph.py

@@ -0,0 +1,85 @@
+"""In-memory representation of the repository code graph."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterator
+from typing import Any
+
+from forgecli.graph.edge import Edge
+from forgecli.graph.node import Node, NodeKind
+
+
+class CodeGraph:
+    """Mutable, in-memory graph of repository symbols and their relations.
+
+    The graph is intentionally simple: nodes and edges are stored in
+    dictionaries keyed by id. A real implementation may serialize to disk
+    or back this with a proper graph database; the surface area stays the
+    same.
+    """
+
+    def __init__(self) -> None:
+        self._nodes: dict[str, Node] = {}
+        self._outgoing: dict[str, list[Edge]] = defaultdict(list)
+        self._incoming: dict[str, list[Edge]] = defaultdict(list)
+
+    # --- node operations -------------------------------------------------
+
+    def add_node(self, node: Node) -> None:
+        self._nodes[node.id] = node
+
+    def remove_node(self, node_id: str) -> None:
+        self._nodes.pop(node_id, None)
+        for edge in self._outgoing.pop(node_id, ()):
+            self._incoming.get(edge.target, []).remove(edge)
+        for edge in self._incoming.pop(node_id, ()):
+            self._outgoing.get(edge.source, []).remove(edge)
+
+    def has_node(self, node_id: str) -> bool:
+        return node_id in self._nodes
+
+    def get_node(self, node_id: str) -> Node | None:
+        return self._nodes.get(node_id)
+
+    def nodes(self, kind: NodeKind | None = None) -> Iterator[Node]:
+        for node in self._nodes.values():
+            if kind is None or node.kind is kind:
+                yield node
+
+    # --- edge operations -------------------------------------------------
+
+    def add_edge(self, edge: Edge) -> None:
+        self._outgoing[edge.source].append(edge)
+        self._incoming[edge.target].append(edge)
+
+    def remove_edge(self, source: str, target: str, kind: Any | None = None) -> None:
+        self._outgoing[source] = [
+            e
+            for e in self._outgoing.get(source, ())
+            if not (e.target == target and (kind is None or e.kind is kind))
+        ]
+        self._incoming[target] = [
+            e
+            for e in self._incoming.get(target, ())
+            if not (e.source == source and (kind is None or e.kind is kind))
+        ]
+
+    def outgoing(self, node_id: str) -> list[Edge]:
+        return list(self._outgoing.get(node_id, ()))
+
+    def incoming(self, node_id: str) -> list[Edge]:
+        return list(self._incoming.get(node_id, ()))
+
+    # --- bulk helpers -----------------------------------------------------
+
+    def clear(self) -> None:
+        self._nodes.clear()
+        self._outgoing.clear()
+        self._incoming.clear()
+
+    def stats(self) -> dict[str, int]:
+        return {
+            "nodes": len(self._nodes),
+            "edges": sum(len(v) for v in self._outgoing.values()),
+        }

forgecli/graph/graphify.py

@@ -0,0 +1,405 @@
+"""Thin wrapper around the Graphify CLI.
+
+Graphify is an external tool installed as ``graphify`` on the user's PATH
+(typically via ``uv tool install graphifyy``). This module:
+
+* detects whether ``graphify`` is installed;
+* invokes it as an async subprocess (never imports its Python package);
+* parses the resulting ``graph.json`` and ``manifest.json`` into typed
+  dataclasses that satisfy the :mod:`forgecli.graph.repository` interface.
+
+The CLI surface we use is intentionally small:
+
+* ``graphify .``         - default full extraction (alias for ``extract``)
+* ``graphify extract``   - same thing, with extra flags
+* ``graphify query``     - free-form BFS/DFS question
+* ``graphify explain``   - plain-language explanation
+* ``graphify path``      - shortest path between two nodes
+* ``graphify affected``  - reverse-traversal blast radius
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from forgecli.core.errors import ForgeCLIError
+
+DEFAULT_OUTPUT_DIR = "graphify-out"
+DEFAULT_GRAPH_FILE = "graph.json"
+DEFAULT_MANIFEST_FILE = "manifest.json"
+
+
+class GraphifyNotFoundError(ForgeCLIError):
+    """Raised when the ``graphify`` executable is not on the user's PATH."""
+
+
+class GraphifyInvocationError(ForgeCLIError):
+    """Raised when the ``graphify`` subprocess exits with a non-zero status."""
+
+
+@dataclass(frozen=True)
+class GraphifyArtifacts:
+    """Filesystem locations of the artifacts produced by Graphify."""
+
+    root: Path
+    output_dir: Path
+    graph_json: Path
+    manifest_json: Path
+    graph_html: Path
+    graph_report: Path
+
+    @classmethod
+    def for_root(cls, root: Path) -> GraphifyArtifacts:
+        out = root / DEFAULT_OUTPUT_DIR
+        return cls(
+            root=root,
+            output_dir=out,
+            graph_json=out / DEFAULT_GRAPH_FILE,
+            manifest_json=out / DEFAULT_MANIFEST_FILE,
+            graph_html=out / "graph.html",
+            graph_report=out / "GRAPH_REPORT.md",
+        )
+
+
+class GraphifyClient:
+    """Async subprocess wrapper around the ``graphify`` CLI.
+
+    Instances are cheap to construct; they do not touch the filesystem
+    until :meth:`detect`, :meth:`build`, :meth:`query`, etc. are called.
+    """
+
+    def __init__(
+        self,
+        *,
+        executable: str | None = None,
+        timeout: float = 600.0,
+    ) -> None:
+        self._executable = executable or os.environ.get("FORGECLI_GRAPHIFY_BIN", "graphify")
+        self._timeout = timeout
+
+    @property
+    def executable(self) -> str:
+        return self._executable
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+
+    async def detect(self) -> str | None:
+        """Return the resolved path of the ``graphify`` binary, or ``None``."""
+        path = shutil.which(self._executable)
+        return path
+
+    async def is_installed(self) -> bool:
+        """Return True if ``graphify`` is on the user's PATH."""
+        return await self.detect() is not None
+
+    async def version(self) -> str:
+        """Return the version string reported by ``graphify --version``."""
+        binary = await self.detect()
+        if binary is None:
+            raise GraphifyNotFoundError(
+                f"Graphify executable {self._executable!r} not found on PATH"
+            )
+        proc = await asyncio.create_subprocess_exec(
+            binary,
+            "--version",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await proc.communicate()
+        if proc.returncode != 0:  # pragma: no cover - graphify exits 0 on --version
+            raise GraphifyInvocationError(
+                f"graphify --version failed: {stderr.decode(errors='replace').strip()}"
+            )
+        return stdout.decode(errors="replace").strip() or "unknown"
+
+    # ------------------------------------------------------------------
+    # Build / update
+    # ------------------------------------------------------------------
+
+    async def build(
+        self,
+        root: Path,
+        *,
+        force: bool = False,
+        no_cluster: bool = False,
+        extra_args: Iterable[str] = (),
+    ) -> GraphifyBuildOutcome:
+        """Run ``graphify extract <root>`` and return the parsed outcome.
+
+        The default subcommand (``graphify .``) is a thin alias for
+        ``extract``; we use ``extract`` explicitly so we can pass flags
+        like ``--no-cluster`` and ``--force`` deterministically.
+        """
+        binary = await self.detect()
+        if binary is None:
+            raise GraphifyNotFoundError(
+                f"Graphify executable {self._executable!r} not found on PATH"
+            )
+
+        root = root.resolve()
+        args: list[str] = [
+            binary,
+            "extract",
+            str(root),
+            "--out",
+            str(root),
+        ]
+        if force:
+            args.append("--force")
+        if no_cluster:
+            args.append("--no-cluster")
+        args.extend(extra_args)
+
+        proc = await asyncio.create_subprocess_exec(
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(root),
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=self._timeout)
+        except TimeoutError as exc:
+            proc.kill()
+            raise GraphifyInvocationError(
+                f"graphify extract timed out after {self._timeout}s"
+            ) from exc
+
+        if proc.returncode != 0:
+            raise GraphifyInvocationError(
+                "graphify extract failed (exit "
+                f"{proc.returncode}):\n{stderr.decode(errors='replace').strip()}"
+            )
+
+        artifacts = GraphifyArtifacts.for_root(root)
+        if not no_cluster:
+            await self.cluster_only(root)
+
+        return GraphifyBuildOutcome(
+            root=root,
+            artifacts=artifacts,
+            stdout=stdout.decode(errors="replace"),
+            stderr=stderr.decode(errors="replace"),
+        )
+
+    async def update(
+        self,
+        root: Path,
+        *,
+        force: bool = False,
+        no_cluster: bool = False,
+    ) -> GraphifyBuildOutcome:
+        """Run ``graphify update <root>`` and return the parsed outcome."""
+        binary = await self.detect()
+        if binary is None:
+            raise GraphifyNotFoundError(
+                f"Graphify executable {self._executable!r} not found on PATH"
+            )
+
+        root = root.resolve()
+        args: list[str] = [
+            binary,
+            "update",
+            str(root),
+        ]
+        if force:
+            args.append("--force")
+        if no_cluster:
+            args.append("--no-cluster")
+
+        proc = await asyncio.create_subprocess_exec(
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(root),
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=self._timeout)
+        except TimeoutError as exc:
+            proc.kill()
+            raise GraphifyInvocationError(
+                f"graphify update timed out after {self._timeout}s"
+            ) from exc
+
+        if proc.returncode != 0:
+            raise GraphifyInvocationError(
+                "graphify update failed (exit "
+                f"{proc.returncode}):\n{stderr.decode(errors='replace').strip()}"
+            )
+
+        artifacts = GraphifyArtifacts.for_root(root)
+        return GraphifyBuildOutcome(
+            root=root,
+            artifacts=artifacts,
+            stdout=stdout.decode(errors="replace"),
+            stderr=stderr.decode(errors="replace"),
+        )
+
+    async def cluster_only(
+        self,
+        root: Path,
+        *,
+        backend: str | None = None,
+    ) -> str:
+        """Run ``graphify cluster-only <root>`` to update HTML viz and Graph Report."""
+        args: list[str] = ["cluster-only", str(root.resolve())]
+        if backend:
+            args.append(f"--backend={backend}")
+        return await self._run_capture(root, args)
+
+    # ------------------------------------------------------------------
+    # JSON parsers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def load_graph(path: Path) -> dict[str, Any]:
+        """Read and return the raw ``graph.json`` payload."""
+        if not path.exists():
+            raise FileNotFoundError(f"graph.json not found at {path}")
+        with path.open("r", encoding="utf-8") as fh:
+            return json.load(fh)
+
+    @staticmethod
+    def load_manifest(path: Path) -> dict[str, Any]:
+        """Read and return the raw ``manifest.json`` payload (may be missing)."""
+        if not path.exists():
+            return {}
+        with path.open("r", encoding="utf-8") as fh:
+            return json.load(fh)
+
+    # ------------------------------------------------------------------
+    # Query / explain / path / affected
+    # ------------------------------------------------------------------
+
+    async def _run_capture(
+        self,
+        root: Path,
+        args: list[str],
+        *,
+        timeout: float | None = None,
+    ) -> str:
+        binary = await self.detect()
+        if binary is None:
+            raise GraphifyNotFoundError(
+                f"Graphify executable {self._executable!r} not found on PATH"
+            )
+        proc = await asyncio.create_subprocess_exec(
+            binary,
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(root),
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=timeout or self._timeout
+            )
+        except TimeoutError as exc:
+            proc.kill()
+            raise GraphifyInvocationError(f"graphify {' '.join(args[:1])} timed out") from exc
+        if proc.returncode != 0:
+            raise GraphifyInvocationError(
+                f"graphify exited with {proc.returncode}: {stderr.decode(errors='replace').strip()}"
+            )
+        return stdout.decode(errors="replace")
+
+    async def query(
+        self,
+        root: Path,
+        question: str,
+        *,
+        budget: int = 2000,
+        graph_path: Path | None = None,
+        dfs: bool = False,
+    ) -> str:
+        """Run ``graphify query "<question>"`` and return its stdout text."""
+        args: list[str] = ["query", question, "--budget", str(budget)]
+        if graph_path is not None:
+            args += ["--graph", str(graph_path)]
+        if dfs:
+            args.append("--dfs")
+        return await self._run_capture(root, args)
+
+    async def explain(
+        self,
+        root: Path,
+        target: str,
+        *,
+        graph_path: Path | None = None,
+    ) -> str:
+        """Run ``graphify explain "<target>"`` and return its stdout text."""
+        args: list[str] = ["explain", target]
+        if graph_path is not None:
+            args += ["--graph", str(graph_path)]
+        return await self._run_capture(root, args)
+
+    async def path(
+        self,
+        root: Path,
+        a: str,
+        b: str,
+        *,
+        graph_path: Path | None = None,
+    ) -> str:
+        """Run ``graphify path "<a>" "<b>"`` and return its stdout text."""
+        args: list[str] = ["path", a, b]
+        if graph_path is not None:
+            args += ["--graph", str(graph_path)]
+        return await self._run_capture(root, args)
+
+    async def affected(
+        self,
+        root: Path,
+        target: str,
+        *,
+        relation: Iterable[str] | None = None,
+        depth: int = 2,
+        graph_path: Path | None = None,
+    ) -> str:
+        """Run ``graphify affected "<target>"`` and return its stdout text."""
+        args: list[str] = ["affected", target, "--depth", str(depth)]
+        for rel in relation or ():
+            args += ["--relation", rel]
+        if graph_path is not None:
+            args += ["--graph", str(graph_path)]
+        return await self._run_capture(root, args)
+
+
+@dataclass(frozen=True)
+class GraphifyBuildOutcome:
+    """The captured result of a ``graphify extract`` invocation."""
+
+    root: Path
+    artifacts: GraphifyArtifacts
+    stdout: str
+    stderr: str
+
+    @property
+    def graph_payload(self) -> dict[str, Any]:
+        """The parsed ``graph.json`` payload (reads from disk on each call)."""
+        return GraphifyClient.load_graph(self.artifacts.graph_json)
+
+    @property
+    def manifest_payload(self) -> dict[str, Any]:
+        """The parsed ``manifest.json`` payload (may be empty)."""
+        return GraphifyClient.load_manifest(self.artifacts.manifest_json)
+
+
+__all__ = [
+    "DEFAULT_GRAPH_FILE",
+    "DEFAULT_MANIFEST_FILE",
+    "DEFAULT_OUTPUT_DIR",
+    "GraphifyArtifacts",
+    "GraphifyBuildOutcome",
+    "GraphifyClient",
+    "GraphifyInvocationError",
+    "GraphifyNotFoundError",
+]

forgecli/graph/indexer.py

@@ -0,0 +1,82 @@
+"""Repository indexer: walk the filesystem and populate the :class:`CodeGraph`."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from forgecli.core.service import Service
+from forgecli.graph.graph import CodeGraph
+from forgecli.graph.node import Node, NodeKind
+from forgecli.utils.fs import iter_files
+
+
+class Indexer(Service):
+    """Walks a project directory and adds file-level nodes to the graph.
+
+    The real implementation will plug in tree-sitter to extract symbols;
+    this scaffold only produces file/package nodes and leaves symbol
+    extraction to language-specific analyzers added later.
+    """
+
+    name = "graph.indexer"
+
+    DEFAULT_GLOBS: tuple[str, ...] = ("**/*.py", "**/*.ts", "**/*.js", "**/*.go", "**/*.rs")
+
+    def __init__(
+        self,
+        graph: CodeGraph,
+        *,
+        root: Path,
+        languages: Iterable[str] | None = None,
+        ignore_patterns: Iterable[str] | None = None,
+    ) -> None:
+        super().__init__()
+        self._graph = graph
+        self._root = Path(root).resolve()
+        self._languages = list(languages) if languages else ["python", "typescript"]
+        self._ignore = list(ignore_patterns) if ignore_patterns else []
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def index(self) -> dict[str, Any]:
+        """Walk ``root`` and add file nodes to the graph.
+
+        Returns a small summary useful for logging and tests.
+        """
+        files = list(self._discover_files())
+        for path in files:
+            rel = str(path.relative_to(self._root))
+            node = Node(
+                id=f"file:{rel}",
+                kind=NodeKind.FILE,
+                name=path.name,
+                path=rel,
+                language=self._infer_language(path),
+            )
+            self._graph.add_node(node)
+        return {"files_indexed": len(files)}
+
+    def _discover_files(self) -> Iterable[Path]:
+        for path in iter_files(self._root, list(self.DEFAULT_GLOBS)):
+            if not path.is_file():
+                continue
+            if any(part in self._ignore for part in path.parts):
+                continue
+            yield path
+
+    @staticmethod
+    def _infer_language(path: Path) -> str | None:
+        suffix = path.suffix.lower()
+        return {
+            ".py": "python",
+            ".ts": "typescript",
+            ".tsx": "typescript",
+            ".js": "javascript",
+            ".jsx": "javascript",
+            ".go": "go",
+            ".rs": "rust",
+        }.get(suffix)

forgecli/graph/node.py

@@ -0,0 +1,47 @@
+"""Node and edge value types for the code graph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class NodeKind(str, Enum):
+    """The kind of entity represented by a graph node."""
+
+    FILE = "file"
+    MODULE = "module"
+    PACKAGE = "package"
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+    VARIABLE = "variable"
+    IMPORT = "import"
+    SYMBOL = "symbol"
+
+
+class EdgeKind(str, Enum):
+    """The kind of relationship represented by a graph edge."""
+
+    CONTAINS = "contains"
+    IMPORTS = "imports"
+    CALLS = "calls"
+    INHERITS = "inherits"
+    REFERENCES = "references"
+    DEFINED_IN = "defined_in"
+    OVERRIDES = "overrides"
+
+
+@dataclass(frozen=True)
+class Node:
+    """A node in the code graph."""
+
+    id: str
+    kind: NodeKind
+    name: str
+    path: str | None = None
+    start_line: int | None = None
+    end_line: int | None = None
+    language: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)