converge-cli 0.1.0__py3-none-any.whl

converge/__init__.py

@@ -0,0 +1,42 @@
+"""
+Converge API
+Main entrypoints for using Converge programmatically.
+"""
+
+from converge.graph.queries import GraphQueries
+from converge.graph.store import GraphStore
+from converge.models import (
+    EntityType,
+    GraphEntity,
+    GraphRelationship,
+    Module,
+    Package,
+    RelationshipType,
+    Repository,
+    Route,
+)
+from converge.scanner.scanner import Scanner
+from converge.solver.conflict import ConflictDetector, ConflictType
+from converge.solver.planner import RepairPlan, RepairPlanner
+from converge.validation.sandbox import UVSandbox
+from converge.validation.smoke import ValidationRunner
+
+__all__ = [
+    "Scanner",
+    "GraphStore",
+    "GraphQueries",
+    "ConflictDetector",
+    "RepairPlanner",
+    "UVSandbox",
+    "ValidationRunner",
+    "EntityType",
+    "RelationshipType",
+    "GraphEntity",
+    "GraphRelationship",
+    "Repository",
+    "Package",
+    "Module",
+    "Route",
+    "ConflictType",
+    "RepairPlan",
+]

converge/cli/explain.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+import networkx as nx
+from rich.console import Console
+from rich.tree import Tree
+
+from converge.models import RelationshipType
+
+
+class ExplainabilityEngine:
+    def __init__(self, G: nx.DiGraph[Any], console: Console):
+        self.G = G
+        self.console = console
+
+    def render_dependency_tree(self, root_id: str) -> None:
+        if root_id not in self.G:
+            self.console.print(f"[red]Entity {root_id} not found in graph.[/red]")
+            return
+
+        root_data = self.G.nodes[root_id]
+        tree = Tree(f"[bold blue]{root_data.get('name', root_id)}[/bold blue] ({root_data.get('type')})")
+
+        self._build_tree(root_id, tree, RelationshipType.REQUIRES)
+        self.console.print(tree)
+
+    def _build_tree(self, node_id: str, tree: Tree, edge_type: str, depth: int = 0, max_depth: int = 3) -> None:
+        if depth > max_depth:
+            tree.add("[dim]... (max depth reached)[/dim]")
+            return
+
+        for succ in self.G.successors(node_id):
+            edge_data = self.G.get_edge_data(node_id, succ)
+            if edge_data and edge_data.get("type") == edge_type:
+                succ_data = self.G.nodes[succ]
+                branch = tree.add(f"[green]{succ_data.get('name', succ)}[/green]")
+                self._build_tree(succ, branch, edge_type, depth + 1, max_depth)
+
+    def explain_conflict(self, conflict_id: str) -> None:
+        self.console.print(f"[bold red]Conflict Analysis:[/bold red] {conflict_id}")
+        # In a real system we would extract this directly from the DB
+        self.console.print("[white]Detailed path reasoning would be rendered here.[/white]")

converge/cli/main.py

@@ -0,0 +1,184 @@
+import typer
+from rich.console import Console
+
+from converge.cli.explain import ExplainabilityEngine
+from converge.graph.store import GraphStore
+from converge.scanner.scanner import Scanner
+from converge.solver.conflict import Conflict, ConflictDetector, ConflictType
+from converge.solver.planner import RepairPlan, RepairPlanner
+from converge.validation.sandbox import UVSandbox
+from converge.validation.smoke import ValidationRunner
+
+app = typer.Typer(
+    help="Converge: A Python-first repository intelligence and environment convergence platform.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def scan(
+    path: str = typer.Argument(".", help="Path to the repository to scan"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Perform a dry run without saving to the database"),
+) -> None:
+    """
+    Scan a codebase to build a graph of repositories, packages, modules, and services.
+    """
+    console.print(f"[bold green]Scanning repository at:[/bold green] {path}")
+
+    scanner = Scanner(path)
+    entities, rels = scanner.scan_all()
+
+    console.print(f"Found [bold cyan]{len(entities)}[/bold cyan] entities and [bold cyan]{len(rels)}[/bold cyan] relationships.")
+
+    if dry_run:
+        console.print("[yellow]Dry run mode enabled. Results will not be saved.[/yellow]")
+    else:
+        store = GraphStore()
+        # Save to SQLite
+        for e in entities:
+            store.add_entity(e)
+        for r in rels:
+            store.add_relationship(r)
+        console.print("[green]Successfully persisted graph to converge_graph.db[/green]")
+
+
+
+def _run_validation(
+    path: str, conflicts: list[Conflict], plans: list[RepairPlan], console: Console
+) -> None:
+    console.print("\n[bold green]Validating plans in sandboxed environment...[/bold green]")
+    sandbox = UVSandbox(path)
+    runner = ValidationRunner(sandbox)
+
+    # Determine packages to smoke test based on unresolved imports
+    smoke_targets = []
+    for c in conflicts:
+        if c.type == ConflictType.UNRESOLVED_IMPORT:
+            smoke_targets.append(c.involved_entities[1].replace("pkg:", ""))
+
+    scores = runner.score_plans(plans, smoke_targets)
+
+    best_plan = None
+    for plan_id, success in scores.items():
+        if success:
+            best_plan = next(p for p in plans if p.id == plan_id)
+            console.print(f"[green]Plan {plan_id} passed validation![/green]")
+            break
+        else:
+            console.print(f"[red]Plan {plan_id} failed validation.[/red]")
+
+    if best_plan:
+        console.print(f"\n[bold green]Successfully found working plan: {best_plan.id}[/bold green]")
+        console.print("[white]In a full implementation, Converge would now rewrite pyproject.toml and your lockfile.[/white]")
+    else:
+        console.print("\n[bold red]All candidate plans failed validation.[/bold red]")
+
+
+@app.command()
+def fix(
+    path: str = typer.Argument(".", help="Path to the repository to fix"),
+    apply: bool = typer.Option(False, "--apply", help="Apply the fix plan after validation"),
+) -> None:
+    """
+    Identify conflicts in the environment and automatically generate and apply a repair plan.
+    """
+    console.print(f"[bold blue]Analyzing environment conflicts for:[/bold blue] {path}")
+
+    store = GraphStore()
+    try:
+        G = store.load_networkx()
+    except Exception as e:
+        console.print(f"[red]Failed to load graph. Did you run `converge scan` first? Error: {e}[/red]")
+        return
+
+    detector = ConflictDetector(G)
+    conflicts = list(detector.detect_all())
+
+    if not conflicts:
+        console.print("[green]No conflicts detected in the graph![/green]")
+        return
+
+    console.print(f"[yellow]Detected {len(conflicts)} conflicts. Generating repair plans...[/yellow]")
+    planner = RepairPlanner(conflicts)
+    plans = planner.generate_plans()
+
+    for plan in plans:
+        console.print(f"\n[cyan]Candidate Plan:[/cyan] {plan.id}")
+        console.print(f"[white]Rationale: {plan.rationale}[/white]")
+        for action in plan.actions:
+            console.print(f"  - [magenta]{action.action_type}[/magenta]: {action.description}")
+
+    if not apply:
+        console.print("\n[yellow]Running in dry-run mode. Use --apply to execute the fix.[/yellow]")
+    else:
+        _run_validation(path, conflicts, plans, console)
+
+
+
+@app.command()
+def doctor() -> None:
+    """
+    Diagnose issues with the environment, parsers, resolvers, or cache.
+    """
+    console.print("[bold cyan]Running Converge Diagnostics...[/bold cyan]")
+    # TODO: Implement checks for uv, python, sqlite, etc.
+    console.print("[green]System looks good![/green]")
+
+
+@app.command()
+def deps(
+    target: str = typer.Argument(..., help="Entity ID to trace (e.g. repo:converge)"),
+) -> None:
+    """
+    Show the dependency tree for a particular entity.
+    """
+    store = GraphStore()
+    try:
+        G = store.load_networkx()
+    except Exception as e:
+        console.print(f"[red]Failed to load graph. Error: {e}[/red]")
+        return
+
+    engine = ExplainabilityEngine(G, console)
+    engine.render_dependency_tree(target)
+
+
+@app.command()
+def validate(
+    path: str = typer.Argument(".", help="Path to the repository to validate"),
+) -> None:
+    """
+    Run isolation and validation checks on the current environment without attempting a fix.
+    """
+    console.print("[bold blue]Running pure validation phase on environment...[/bold blue]")
+    sandbox = UVSandbox(path)
+    # Simply create sandbox to verify toolchain
+    sandbox.create()
+    console.print("[green]Sandbox toolchain is working and isolated execution succeeded.[/green]")
+    sandbox.cleanup()
+
+
+@app.command()
+def explain(
+    target: str = typer.Argument(..., help="Entity or conflict ID to explain"),
+) -> None:
+    """
+    Explain the current state of the graph or details of a specific conflict/fix.
+    """
+    store = GraphStore()
+    try:
+        G = store.load_networkx()
+    except Exception as e:
+        console.print(f"[red]Failed to load graph. Error: {e}[/red]")
+        return
+
+    engine = ExplainabilityEngine(G, console)
+    if "conflict:" in target:
+        engine.explain_conflict(target)
+    else:
+        engine.render_dependency_tree(target)
+
+
+if __name__ == "__main__":
+    app()

converge/graph/queries.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+import networkx as nx
+
+from converge.models import RelationshipType
+
+
+class GraphQueries:
+    """
+    Abstractions for traversing the NetworkX graph.
+    Used for inferring constraints and paths.
+    """
+    def __init__(self, G: nx.DiGraph[Any]):
+        self.G = G
+
+    def get_dependencies_for_package(self, package_id: str) -> list[str]:
+        """Returns all packages that this package requires directly."""
+        deps = []
+        if package_id in self.G:
+            for neighbor in self.G.successors(package_id):
+                edge_data = self.G.get_edge_data(package_id, neighbor)
+                if edge_data and edge_data.get("type") == RelationshipType.REQUIRES:
+                    deps.append(neighbor)
+        return deps
+
+    def get_version_conflicts(self) -> list[tuple[str, str]]:
+        """Returns all edges of type CONFLICTS_WITH"""
+        conflicts = []
+        for u, v, data in self.G.edges(data=True):
+            if data.get("type") == RelationshipType.CONFLICTS_WITH:
+                conflicts.append((u, v))
+        return conflicts
+
+    def find_shortest_dependency_path(self, root_id: str, target_id: str) -> list[str] | None:
+        """Finds the shortest REQUIRES path from root to target."""
+        try:
+            # Only traverse REQUIRES edges
+            requires_graph = nx.DiGraph(
+                ((u, v, d) for u, v, d in self.G.edges(data=True) if d.get('type') == RelationshipType.REQUIRES)
+            )
+            return nx.shortest_path(requires_graph, source=root_id, target=target_id)
+        except nx.NetworkXNoPath:
+            return None

converge/graph/store.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Generator
+from typing import Any
+
+import networkx as nx
+from sqlalchemy import text
+from sqlmodel import Field, Session, SQLModel, create_engine, select
+
+from converge.models import EntityType, GraphEntity, GraphRelationship, RelationshipType
+
+
+# SQLModel classes for SQLite persistence
+class SQLEntity(SQLModel, table=True):
+    id: str = Field(primary_key=True)
+    type: str # Map to EntityType
+    name: str
+    metadata_json: str = "{}" # JSON serialized metadata
+
+    def to_pydantic(self) -> GraphEntity:
+        return GraphEntity(
+            id=self.id,
+            type=EntityType(self.type),
+            name=self.name,
+            metadata=json.loads(self.metadata_json)
+        )
+
+    @classmethod
+    def from_pydantic(cls, entity: GraphEntity) -> SQLEntity:
+        return cls(
+            id=entity.id,
+            type=entity.type.value,
+            name=entity.name,
+            metadata_json=json.dumps(entity.metadata)
+        )
+
+
+class SQLRelationship(SQLModel, table=True):
+    # Composite PK logically: source, target, type
+    # For SQLModel without explicit composite primary key class simplicity, we use a surrogate
+    id: int | None = Field(default=None, primary_key=True)
+    source_id: str = Field(index=True)
+    target_id: str = Field(index=True)
+    type: str # Map to RelationshipType
+    metadata_json: str = "{}"
+
+    def to_pydantic(self) -> GraphRelationship:
+        return GraphRelationship(
+            source_id=self.source_id,
+            target_id=self.target_id,
+            type=RelationshipType(self.type),
+            metadata=json.loads(self.metadata_json)
+        )
+
+    @classmethod
+    def from_pydantic(cls, rel: GraphRelationship) -> SQLRelationship:
+        return cls(
+            source_id=rel.source_id,
+            target_id=rel.target_id,
+            type=rel.type.value,
+            metadata_json=json.dumps(rel.metadata)
+        )
+
+
+class GraphStore:
+    """
+    Manages physical persistence of the graph using SQLModel (SQLite).
+    Provides methods to persist and re-hydrate NetworkX graphs.
+    """
+    def __init__(self, db_url: str = "sqlite:///converge_graph.db"):
+        self.engine = create_engine(db_url)
+        SQLModel.metadata.create_all(self.engine)
+
+    def get_session(self) -> Generator[Session, None, None]:
+        with Session(self.engine) as session:
+            yield session
+
+    def add_entity(self, entity: GraphEntity) -> None:
+        with Session(self.engine) as session:
+            sql_ent = SQLEntity.from_pydantic(entity)
+            session.merge(sql_ent)
+            session.commit()
+
+    def add_relationship(self, rel: GraphRelationship) -> None:
+        with Session(self.engine) as session:
+            # Simple deduplication strategy
+            stmt = select(SQLRelationship).where(
+                SQLRelationship.source_id == rel.source_id,
+                SQLRelationship.target_id == rel.target_id,
+                SQLRelationship.type == rel.type.value
+            )
+            existing = session.exec(stmt).first()
+            if not existing:
+                sql_rel = SQLRelationship.from_pydantic(rel)
+                session.add(sql_rel)
+                session.commit()
+
+    def load_networkx(self) -> nx.DiGraph[Any]:
+        """Hydrates a fully loaded NetworkX directed graph from SQLite."""
+        G: nx.DiGraph[Any] = nx.DiGraph()
+        with Session(self.engine) as session:
+            entities = session.exec(select(SQLEntity)).all()
+            for e in entities:
+                p_ent = e.to_pydantic()
+                G.add_node(p_ent.id, **p_ent.model_dump())
+
+            rels = session.exec(select(SQLRelationship)).all()
+            for r in rels:
+                p_rel = r.to_pydantic()
+                G.add_edge(p_rel.source_id, p_rel.target_id, type=p_rel.type, metadata=p_rel.metadata)
+        return G
+
+    def save_networkx(self, G: nx.DiGraph[Any]) -> None:
+        """Persists a NetworkX digraph into SQLite."""
+        with Session(self.engine) as session:
+            # Clear existing logic for hard reset, or intelligent merge.
+            # Fast path: wipe and replace
+            session.execute(text("DELETE FROM sqlrelationship"))
+            session.execute(text("DELETE FROM sqlentity"))
+
+            for _node_id, data in G.nodes(data=True):
+                ent = GraphEntity.model_validate(data)
+                session.add(SQLEntity.from_pydantic(ent))
+
+            for src, dst, data in G.edges(data=True):
+                rel = GraphRelationship(
+                    source_id=src,
+                    target_id=dst,
+                    type=data["type"],
+                    metadata=data.get("metadata", {})
+                )
+                session.add(SQLRelationship.from_pydantic(rel))
+
+            session.commit()

converge/models.py

@@ -0,0 +1,83 @@
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class EntityType(StrEnum):
+    REPOSITORY = "repository"
+    PACKAGE = "package"
+    ENVIRONMENT = "environment"
+    PYTHON_VERSION = "python_version"
+    MODULE = "module"
+    ROUTE = "route"
+    EXTERNAL_API = "external_api"
+
+
+class RelationshipType(StrEnum):
+    IMPORTS = "imports"
+    REQUIRES = "requires"
+    CONFLICTS_WITH = "conflicts_with"
+    CALLS = "calls"
+    EXPOSES = "exposes"
+    CONFIGURED_BY = "configured_by"
+    DEPENDS_ON = "depends_on"
+    VALIDATED_BY = "validated_by"
+    BROKEN_BY = "broken_by"
+    FIXED_BY = "fixed_by"
+    SERVED_AT = "served_at"
+    REFERENCES_ENV = "references_env"
+    USES_INTERPRETER = "uses_interpreter"
+    BELONGS_TO = "belongs_to"
+
+
+class GraphEntity(BaseModel):
+    id: str
+    type: EntityType
+    name: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphRelationship(BaseModel):
+    source_id: str
+    target_id: str
+    type: RelationshipType
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+# Specialized Entity Models
+class Repository(GraphEntity):
+    type: EntityType = EntityType.REPOSITORY
+    path: str
+
+
+class Package(GraphEntity):
+    type: EntityType = EntityType.PACKAGE
+    version: str | None = None
+    source: str = "pypi"
+
+
+class Environment(GraphEntity):
+    type: EntityType = EntityType.ENVIRONMENT
+    path: str
+
+
+class PythonVersion(GraphEntity):
+    type: EntityType = EntityType.PYTHON_VERSION
+    version: str
+
+
+class Module(GraphEntity):
+    type: EntityType = EntityType.MODULE
+    file_path: str
+
+
+class Route(GraphEntity):
+    type: EntityType = EntityType.ROUTE
+    method: str
+    path: str
+
+
+class ExternalAPI(GraphEntity):
+    type: EntityType = EntityType.EXTERNAL_API
+    url: str

converge/scanner/ast_parser.py

@@ -0,0 +1,63 @@
+import ast
+from pathlib import Path
+
+from converge.models import GraphRelationship, Module, RelationshipType
+
+
+class PythonASTParser:
+    """
+    Parses Python files to extract imports and module relationships.
+    """
+    def __init__(self, root_dir: str):
+        self.root_dir = Path(root_dir)
+
+    def scan_directory(self) -> tuple[list[Module], list[GraphRelationship]]:
+        """Walks the directory and parses all Python files."""
+        modules = []
+        relationships = []
+
+        for p in self.root_dir.rglob("*.py"):
+            # Skip hidden dirs or common virtualenvs
+            if any(part.startswith(".") or part in ("venv", "env", "node_modules") for part in p.parts):
+                continue
+
+            mod_id = f"mod:{p.relative_to(self.root_dir)}"
+            mod = Module(
+                id=mod_id,
+                name=p.name,
+                file_path=str(p)
+            )
+            modules.append(mod)
+
+            try:
+                content = p.read_text(encoding="utf-8")
+                tree = ast.parse(content, filename=str(p))
+
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.Import):
+                        for name in node.names:
+                            target_pkg = name.name.split('.')[0] # Heuristic: top level package
+                            relationships.append(
+                                GraphRelationship(
+                                    source_id=mod_id,
+                                    target_id=f"pkg:{target_pkg}",
+                                    type=RelationshipType.IMPORTS,
+                                    metadata={"full_import": name.name, "line": node.lineno}
+                                )
+                            )
+                    elif isinstance(node, ast.ImportFrom):
+                        if node.module:
+                            target_pkg = node.module.split('.')[0]
+                            relationships.append(
+                                GraphRelationship(
+                                    source_id=mod_id,
+                                    target_id=f"pkg:{target_pkg}",
+                                    type=RelationshipType.IMPORTS,
+                                    metadata={"full_import": node.module, "line": node.lineno}
+                                )
+                            )
+            except (SyntaxError, UnicodeDecodeError):
+                # We skip files we can't parse safely
+                continue
+
+        return modules, relationships

converge/scanner/project.py

@@ -0,0 +1,87 @@
+import tomllib
+from pathlib import Path
+
+from converge.models import GraphRelationship, Package, RelationshipType
+
+
+class ProjectParser:
+    """
+    Scans project configuration files like pyproject.toml and requirements.txt.
+    """
+    def __init__(self, root_dir: str):
+        self.root_dir = Path(root_dir)
+
+    def parse_pyproject(self) -> tuple[list[Package], list[GraphRelationship]]:
+        """Parses pyproject.toml returning Package entities and REQUIRES relationships."""
+        toml_path = self.root_dir / "pyproject.toml"
+        if not toml_path.exists():
+            return [], []
+
+        with open(toml_path, "rb") as f:
+            try:
+                data = tomllib.load(f)
+            except tomllib.TOMLDecodeError:
+                return [], []
+
+        packages = []
+        relationships = []
+
+        # Extract dependencies
+        deps = data.get("project", {}).get("dependencies", [])
+        for dep in deps:
+            # Very basic parsing, a real implementation would use packaging.requirements
+            pkg_name = dep.split(">=")[0].split("==")[0].split("<=")[0].split("~=")[0].strip()
+            pkg_id = f"pkg:{pkg_name}"
+
+            pkg = Package(
+                id=pkg_id,
+                name=pkg_name,
+                metadata={"constraint": dep}
+            )
+            packages.append(pkg)
+
+            # The repository requires this package
+            rel = GraphRelationship(
+                source_id=f"repo:{self.root_dir.name}",
+                target_id=pkg_id,
+                type=RelationshipType.REQUIRES,
+                metadata={"source": "pyproject.toml"}
+            )
+            relationships.append(rel)
+
+        return packages, relationships
+
+    def parse_requirements_txt(self) -> tuple[list[Package], list[GraphRelationship]]:
+        """Parses requirements.txt returning Package entities and REQUIRES relationships."""
+        req_path = self.root_dir / "requirements.txt"
+        if not req_path.exists():
+            return [], []
+
+        packages = []
+        relationships = []
+
+        with open(req_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                # Same naive split
+                pkg_name = line.split(">=")[0].split("==")[0].split("<=")[0].split("~=")[0].strip()
+                pkg_id = f"pkg:{pkg_name}"
+
+                pkg = Package(
+                    id=pkg_id,
+                    name=pkg_name,
+                    metadata={"constraint": line}
+                )
+                packages.append(pkg)
+
+                rel = GraphRelationship(
+                    source_id=f"repo:{self.root_dir.name}",
+                    target_id=pkg_id,
+                    type=RelationshipType.REQUIRES,
+                    metadata={"source": "requirements.txt"}
+                )
+                relationships.append(rel)
+
+        return packages, relationships

converge/scanner/scanner.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+
+from converge.models import GraphEntity, GraphRelationship
+from converge.scanner.ast_parser import PythonASTParser
+from converge.scanner.project import ProjectParser
+from converge.scanner.service_detector import ServiceDetector
+
+
+class Scanner:
+    """
+    Orchestrates the different parsers to build a comprehensive graph of the codebase.
+    """
+    def __init__(self, root_dir: str):
+        self.root_dir = Path(root_dir)
+        self.entities: list[GraphEntity] = []
+        self.relationships: list[GraphRelationship] = []
+
+    def scan_all(self) -> tuple[list[GraphEntity], list[GraphRelationship]]:
+        # 1. Parse Project files
+        project_parser = ProjectParser(str(self.root_dir))
+
+        pkgs, rels = project_parser.parse_pyproject()
+        self.entities.extend(pkgs)
+        self.relationships.extend(rels)
+
+        pkgs_req, rels_req = project_parser.parse_requirements_txt()
+        self.entities.extend(pkgs_req)
+        self.relationships.extend(rels_req)
+
+        # 2. Parse Python AST for imports
+        ast_parser = PythonASTParser(str(self.root_dir))
+        mods, mod_rels = ast_parser.scan_directory()
+        self.entities.extend(mods)
+        self.relationships.extend(mod_rels)
+
+        # 3. Detect services and routes
+        for p in self.root_dir.rglob("*.py"):
+            if any(part.startswith(".") or part in ("venv", "env", "node_modules") for part in p.parts):
+                continue
+
+            # Use relative paths for IDs to match ast_parser
+            rel_path = p.relative_to(self.root_dir)
+            routes, route_rels = ServiceDetector.scan_file(p)
+
+            # Map absolute path back to relative mod ID in relationships
+            for r in route_rels:
+                r.source_id = f"mod:{rel_path}"
+
+            self.entities.extend(routes)
+            self.relationships.extend(route_rels)
+
+        return self.entities, self.relationships

converge/scanner/service_detector.py

@@ -0,0 +1,69 @@
+import ast
+from pathlib import Path
+
+from converge.models import GraphRelationship, RelationshipType, Route
+
+
+class ServiceDetector(ast.NodeVisitor):
+    """
+    Heuristic AST visitor to detect FastAPI/Flask routes and services.
+    """
+    def __init__(self, file_path: Path):
+        self.file_path = file_path
+        self.routes: list[Route] = []
+        self.relationships: list[GraphRelationship] = []
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """
+        Looks for decorators like @app.get('/path') to infer routes.
+        """
+        for decorator in node.decorator_list:
+            if isinstance(decorator, ast.Call):
+                func = decorator.func
+
+                # Check for forms like app.get(...) or router.post(...)
+                if isinstance(func, ast.Attribute):
+                    method_name = func.attr.upper()
+
+                    if method_name in {"GET", "POST", "PUT", "DELETE", "PATCH"}:
+                        # Try to extract the path from the first argument
+                        if decorator.args and isinstance(decorator.args[0], ast.Constant):
+                            route_path = decorator.args[0].value
+
+                            # Ensure route_path is a string
+                            if isinstance(route_path, bytes):
+                                route_path = route_path.decode("utf-8")
+                            elif not isinstance(route_path, str):
+                                route_path = str(route_path)
+
+                            route_id = f"route:{method_name}:{route_path}"
+                            route = Route(
+                                id=route_id,
+                                name=f"{method_name} {route_path}",
+                                method=method_name,
+                                path=route_path,
+                                metadata={"file": str(self.file_path), "line": node.lineno}
+                            )
+                            self.routes.append(route)
+
+                            # The module exposes this route
+                            mod_id = f"mod:{self.file_path}"
+                            rel = GraphRelationship(
+                                source_id=mod_id,
+                                target_id=route_id,
+                                type=RelationshipType.EXPOSES
+                            )
+                            self.relationships.append(rel)
+
+        self.generic_visit(node)
+
+    @classmethod
+    def scan_file(cls, path: Path) -> tuple[list[Route], list[GraphRelationship]]:
+        try:
+            content = path.read_text(encoding="utf-8")
+            tree = ast.parse(content, filename=str(path))
+            detector = cls(path)
+            detector.visit(tree)
+            return detector.routes, detector.relationships
+        except (SyntaxError, UnicodeDecodeError):
+            return [], []

converge/solver/conflict.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+
+import networkx as nx
+from pydantic import BaseModel
+
+from converge.graph.queries import GraphQueries
+from converge.models import RelationshipType
+
+
+class ConflictType(str):
+    MISSING_PACKAGE = "missing_package"
+    VERSION_CLASH = "version_clash"
+    UNRESOLVED_IMPORT = "unresolved_import"
+
+class Conflict(BaseModel):
+    id: str
+    type: str # ConflictType
+    description: str
+    involved_entities: list[str]
+    metadata: dict[str, Any] = {}
+
+class ConflictDetector:
+    """
+    Analyzes the graph to find broken relationships or unmet constraints.
+    """
+    def __init__(self, G: nx.DiGraph[Any]):
+        self.G = G
+        self.queries = GraphQueries(G)
+
+    def detect_all(self) -> list[Conflict]:
+        conflicts = []
+        conflicts.extend(self._detect_unresolved_imports())
+        conflicts.extend(self._detect_version_clashes())
+        # In a real system, we'd also check if the installed environment matches requirements
+        return conflicts
+
+    def _detect_unresolved_imports(self) -> list[Conflict]:
+        """
+        Finds IMPORTS edges that do not point to a known installed package or internal module.
+        """
+        conflicts = []
+        for u, v, data in self.G.edges(data=True):
+            if data.get("type") == RelationshipType.IMPORTS or data.get("type") == RelationshipType.IMPORTS.value:
+                # An import is valid if the target package has been declared via REQUIRES from a repo/project
+                has_requires = False
+                for predecessor in self.G.predecessors(v):
+                    edge_preds = self.G.get_edge_data(predecessor, v)
+                    if edge_preds and (edge_preds.get("type") == RelationshipType.REQUIRES or edge_preds.get("type") == RelationshipType.REQUIRES.value):
+                        has_requires = True
+                        break
+
+                if not has_requires:
+                    # We might have imported a third-party package without adding to pyproject.toml
+                    c = Conflict(
+                        id=f"conflict:unresolved_{u}_{v}",
+                        type=ConflictType.UNRESOLVED_IMPORT,
+                        description=f"Module {u} imports {v}, but it is not declared in dependencies.",
+                        involved_entities=[u, v],
+                        metadata={"import_data": data}
+                    )
+                    conflicts.append(c)
+        return conflicts
+
+    def _detect_version_clashes(self) -> list[Conflict]:
+        clashes = self.queries.get_version_conflicts()
+        conflicts = []
+        for u, v in clashes:
+            c = Conflict(
+                id=f"conflict:clash_{u}_{v}",
+                type=ConflictType.VERSION_CLASH,
+                description=f"Version conflict between {u} and {v}.",
+                involved_entities=[u, v]
+            )
+            conflicts.append(c)
+        return conflicts

converge/solver/planner.py

@@ -0,0 +1,67 @@
+from pydantic import BaseModel
+
+from converge.solver.conflict import Conflict, ConflictType
+
+
+class RepairActionType(str):
+    ADD_DEPENDENCY = "add_dependency"
+    PIN_VERSION = "pin_version"
+    UPGRADE_DEPENDENCY = "upgrade_dependency"
+    DOWNGRADE_DEPENDENCY = "downgrade_dependency"
+
+class RepairAction(BaseModel):
+    action_type: str
+    target_package: str
+    target_version: str = "latest"
+    description: str
+
+class RepairPlan(BaseModel):
+    id: str
+    rationale: str
+    actions: list[RepairAction]
+
+class RepairPlanner:
+    """
+    Generates Candidate Repair Plans based on detected conflicts.
+    """
+    def __init__(self, conflicts: list[Conflict]):
+        self.conflicts = conflicts
+
+    def generate_plans(self) -> list[RepairPlan]:
+        plans = []
+
+        # We handle generating plans for unhandled imports
+        actions = []
+        for c in self.conflicts:
+            if c.type == ConflictType.UNRESOLVED_IMPORT:
+                # Extract the package name from 'pkg:name'
+                target = c.involved_entities[1]
+                pkg_name = target.replace("pkg:", "")
+                # Simple rule: add dependency to pyproject.toml
+                action = RepairAction(
+                    action_type=RepairActionType.ADD_DEPENDENCY,
+                    target_package=pkg_name,
+                    description=f"Add {pkg_name} to pyproject.toml dependencies to satisfy import."
+                )
+                actions.append(action)
+
+            elif c.type == ConflictType.VERSION_CLASH:
+                # In a real engine, we calculate the intersection of semver ranges.
+                target = c.involved_entities[1]
+                pkg_name = target.replace("pkg:", "")
+                action = RepairAction(
+                    action_type=RepairActionType.PIN_VERSION,
+                    target_package=pkg_name,
+                    description=f"Pin {pkg_name} to a safe version."
+                )
+                actions.append(action)
+
+        if actions:
+            plan = RepairPlan(
+                id="plan:001",
+                rationale="Candidate plan to fix missing and conflicting dependencies.",
+                actions=actions
+            )
+            plans.append(plan)
+
+        return plans

converge/validation/sandbox.py

@@ -0,0 +1,68 @@
+import shutil
+import subprocess
+from pathlib import Path
+
+from converge.solver.planner import RepairActionType, RepairPlan
+
+
+class SandboxError(Exception):
+    pass
+
+class UVSandbox:
+    """
+    Manages isolated Python environments using `uv`.
+    """
+    def __init__(self, base_dir: str):
+        self.base_dir = Path(base_dir)
+        self.venv_path = self.base_dir / ".venv-converge-test"
+
+    def create(self, python_version: str | None = None) -> None:
+        """Creates a fresh virtual environment."""
+        if self.venv_path.exists():
+            shutil.rmtree(self.venv_path)
+
+        cmd = ["uv", "venv", str(self.venv_path)]
+        if python_version:
+            cmd.extend(["--python", python_version])
+
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise SandboxError(f"Failed to create venv: {result.stderr}")
+
+    def apply_plan(self, plan: RepairPlan) -> None:
+        """Installs exactly what the repair plan dictates."""
+        # For a real implementation, we would modify pyproject.toml in a temp dir.
+        # Here we just `uv pip install` into the sandbox.
+        to_install = []
+        for action in plan.actions:
+            if action.action_type in (
+                RepairActionType.ADD_DEPENDENCY,
+                RepairActionType.PIN_VERSION,
+                RepairActionType.UPGRADE_DEPENDENCY,
+                RepairActionType.DOWNGRADE_DEPENDENCY
+            ):
+                if action.target_version and action.target_version != "latest":
+                    to_install.append(f"{action.target_package}=={action.target_version}")
+                else:
+                    to_install.append(action.target_package)
+
+        if to_install:
+            self._uv_pip_install(to_install)
+
+    def _uv_pip_install(self, packages: list[str]) -> None:
+        python_exec = str(self.venv_path / "bin" / "python")
+        cmd = ["uv", "pip", "install", "--python", python_exec] + packages
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise SandboxError(f"uv install failed: {result.stderr}")
+
+    def run_python_cmd(self, code: str) -> bool:
+        """Runs a snippet of Python code in the sandbox and returns True if successful."""
+        python_exec = str(self.venv_path / "bin" / "python")
+        cmd = [python_exec, "-c", code]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        return result.returncode == 0
+
+    def cleanup(self) -> None:
+        if self.venv_path.exists():
+            shutil.rmtree(self.venv_path)

converge/validation/smoke.py

@@ -0,0 +1,43 @@
+
+from converge.solver.planner import RepairPlan
+from converge.validation.sandbox import UVSandbox
+
+
+class ValidationRunner:
+    """
+    Validates candidate repair plans by executing tests in a sandbox.
+    """
+    def __init__(self, sandbox: UVSandbox):
+        self.sandbox = sandbox
+
+    def validate_plan(self, plan: RepairPlan, smoke_imports: list[str]) -> bool:
+        """
+        Applies a plan to the sandbox and checks if smoke_imports are resolvable.
+        """
+        try:
+            self.sandbox.create()
+            self.sandbox.apply_plan(plan)
+
+            # Smoke tests: ensure we can import the target packages
+            success = True
+            for imp in smoke_imports:
+                if not self.sandbox.run_python_cmd(f"import {imp}"):
+                    success = False
+                    break
+
+            return success
+        except Exception:
+            return False
+        finally:
+            self.sandbox.cleanup()
+
+    def score_plans(self, plans: list[RepairPlan], smoke_imports: list[str]) -> dict[str, bool]:
+        """
+        Scores multiple plans by attempting them in isolated sandboxes.
+        Returns a dict mapping plan ID to Success (True/False).
+        """
+        results = {}
+        for plan in plans:
+            success = self.validate_plan(plan, smoke_imports)
+            results[plan.id] = success
+        return results

converge_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: converge-cli
+Version: 0.1.0
+Summary: A Python-first repository intelligence and environment convergence platform.
+Author-email: Converge Authors <authors@example.com>
+Requires-Python: >=3.12
+Requires-Dist: networkx>=3.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sqlmodel>=0.0.16
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uv>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Converge
+
+A Python-first repository intelligence and environment convergence platform. It scans a codebase, builds a graph of repositories, packages, modules, services, routes, environment dependencies, and external APIs, detects dependency and compatibility failures, and automatically iterates toward a working environment using deterministic resolution, validation, and repair loops.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+converge --help
+```

converge_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+converge/__init__.py,sha256=-nG6rBT_RMWfkXmvLGXRgWBJ8iQ2iX8fr3qW0ZjDtwA,948
+converge/models.py,sha256=q2mEbuO7CCu1HBFPQDnrni9hAlaFjnlClRbzAkeD0KE,1800
+converge/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+converge/cli/explain.py,sha256=hSggwWcqCwgxfHt0fZfab73E-cxZorjDQpvBMdrGF9Q,1690
+converge/cli/main.py,sha256=6YTq7copBpgib2Co0ePB43brCXeN4y5d0ZAiFr2Q5mQ,6262
+converge/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+converge/graph/queries.py,sha256=RHNKYR2Rpbjf_lHb9EGEFq-Qawe1OB_8N9MYKacgcxY,1660
+converge/graph/store.py,sha256=4V_YDVuSiDonuqCb2dtCh8qVe6oMoyqJQjP0i5kAbEM,4853
+converge/scanner/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+converge/scanner/ast_parser.py,sha256=aZheFmYdrVjubr0iRwKr9MB5OmHjO1e7XsysvUzI3Kg,2545
+converge/scanner/project.py,sha256=f-lBd8JtVv_1BB0WDZAZognyegkmv9gN6-WDGYwKQuc,2971
+converge/scanner/scanner.py,sha256=kTKLCKDwvh0dZw-mxNHAIX16SJe5D_DQXA5Meqb3cGU,1930
+converge/scanner/service_detector.py,sha256=9PllLNGTo_t-j02RTqO7eg-Gson8D24_ZfAv0e3ZfaQ,2908
+converge/solver/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+converge/solver/conflict.py,sha256=PnOXqw9cg_L9vHDq747HcT5FxfxVpYW3tq__7LP8apc,2961
+converge/solver/planner.py,sha256=QLhFD8lUKIy4-Y57R4Ri1mfnZlwZDFQrpOXCPLYM7UA,2262
+converge/validation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+converge/validation/sandbox.py,sha256=oSXIYt52Ea5e32CqFOtUCjUPKasEuHkQEPXnFZquwhI,2623
+converge/validation/smoke.py,sha256=G1K9n3xtjHvyEwo2OvFW82IiXL4H5WSKk6dFcS7dodY,1388
+converge_cli-0.1.0.dist-info/METADATA,sha256=sywu5iiU6-LgdNPlbPc5--h2q2CrTA9GobfDlBt9bNI,1060
+converge_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+converge_cli-0.1.0.dist-info/entry_points.txt,sha256=cjU4H0wcPaj4RYKZffhCTqq98AjBBTgUM2aRtBqLmzs,51
+converge_cli-0.1.0.dist-info/RECORD,,

converge_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

converge_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+converge = converge.cli.main:app