forgeoptimizer 1.0.0__py3-none-any.whl

forgecli/graph/graphify.py

@@ -0,0 +1,412 @@
+"""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}: "
+                f"{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)

forgecli/graph/repository.py

@@ -0,0 +1,164 @@
+"""Abstract interface for a repository knowledge graph.
+
+This module is the boundary between ForgeCLI's graph-aware features and any
+concrete back-end (Graphify today; custom AST-based backends tomorrow). The
+interface is intentionally small: build, query, explain, path, affected.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class GraphNode:
+    """A typed view of a single node from the knowledge graph."""
+
+    id: str
+    label: str
+    file_type: str | None = None
+    source_file: str | None = None
+    source_location: str | None = None
+    community: int | None = None
+    norm_label: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GraphEdge:
+    """A typed view of a directed/undirected edge."""
+
+    source: str
+    target: str
+    relation: str
+    confidence: str | None = None
+    confidence_score: float | None = None
+    source_file: str | None = None
+    source_location: str | None = None
+    weight: float = 1.0
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GraphCommunity:
+    """A Leiden-detected community of nodes."""
+
+    id: int
+    size: int
+    label: str | None = None
+    members: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class GraphSnapshot:
+    """An immutable view of a fully-built knowledge graph."""
+
+    root: str
+    nodes: tuple[GraphNode, ...]
+    edges: tuple[GraphEdge, ...]
+    communities: tuple[GraphCommunity, ...] = ()
+    directed: bool = False
+    multigraph: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def node(self, node_id: str) -> GraphNode | None:
+        """Return the node with ``node_id`` or ``None``."""
+        for node in self.nodes:
+            if node.id == node_id:
+                return node
+        return None
+
+    def neighbors(self, node_id: str) -> list[GraphEdge]:
+        """Return all edges incident to ``node_id`` (in or out)."""
+        return [e for e in self.edges if e.source == node_id or e.target == node_id]
+
+    def search(self, query: str, *, limit: int = 20) -> list[GraphNode]:
+        """Return nodes whose ``label`` or ``norm_label`` contain ``query``."""
+        needle = query.lower()
+        hits: list[GraphNode] = []
+        for node in self.nodes:
+            if needle in (node.label or "").lower() or needle in (node.norm_label or "").lower():
+                hits.append(node)
+                if len(hits) >= limit:
+                    break
+        return hits
+
+
+@dataclass(frozen=True)
+class BuildResult:
+    """The outcome of :meth:`RepositoryGraph.build`."""
+
+    snapshot: GraphSnapshot
+    artifacts: dict[str, str] = field(default_factory=dict)
+    raw_output: str = ""
+
+
+@dataclass(frozen=True)
+class QueryResult:
+    """A natural-language answer produced by :meth:`RepositoryGraph.query`."""
+
+    question: str
+    answer: str
+    cited_nodes: tuple[str, ...] = ()
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ExplainResult:
+    """A plain-language explanation of a node and its neighbors."""
+
+    target: str
+    explanation: str
+    related: tuple[GraphNode, ...] = ()
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+class RepositoryGraph(ABC):
+    """Strategy interface for any repository knowledge graph backend."""
+
+    name: str = "abstract"
+
+    @abstractmethod
+    async def is_available(self) -> bool:
+        """Return True if the back-end is installed and runnable."""
+
+    @abstractmethod
+    async def build(self, *, force: bool = False) -> BuildResult:
+        """Build (or rebuild) the graph rooted at the configured path."""
+
+    @abstractmethod
+    async def load(self) -> GraphSnapshot:
+        """Load a previously-built graph from disk without rebuilding."""
+
+    @abstractmethod
+    async def query(self, question: str, *, budget: int = 2000) -> QueryResult:
+        """Ask a free-form question; the back-end traverses the graph."""
+
+    @abstractmethod
+    async def explain(self, target: str) -> ExplainResult:
+        """Return a plain-language explanation of ``target`` and its neighbors."""
+
+    @abstractmethod
+    async def shortest_path(self, a: str, b: str) -> list[GraphEdge]:
+        """Return the shortest edge path between two node labels/ids."""
+
+    @abstractmethod
+    async def affected(
+        self, target: str, *, relation: Iterable[str] | None = None, depth: int = 2
+    ) -> list[GraphEdge]:
+        """Return the reverse-traversal edges from ``target``."""
+
+
+__all__ = [
+    "BuildResult",
+    "ExplainResult",
+    "GraphCommunity",
+    "GraphEdge",
+    "GraphNode",
+    "GraphSnapshot",
+    "QueryResult",
+    "RepositoryGraph",
+]