mafia-graph 0.9.0__py3-none-any.whl

mafia/__init__.py

@@ -0,0 +1,19 @@
+"""
+MAFIA — Multi-Artifact Flow Intelligence Architecture
+======================================================
+Public Python API. This is the only stable surface.
+
+Usage:
+    from mafia import MAFIA
+    m = MAFIA.from_path("/path/to/project").run_all()
+    results = m.search("getUserProfile")
+    skill = m.as_skill()
+"""
+
+from mafia.api import MAFIA
+from mafia.ids import EntityID
+from mafia.graph import Graph
+from mafia.skill import Skill
+from schemas.scope import Scope
+
+__all__ = ["MAFIA", "EntityID", "Graph", "Skill", "Scope"]

mafia/api.py

@@ -0,0 +1,240 @@
+"""
+MAFIA Public API — Façade
+==========================
+Single entry point for all MAFIA operations.
+"""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from mafia.ids import EntityID
+from mafia.graph import Graph
+
+
+class MAFIA:
+    """Main façade for MAFIA codebase intelligence."""
+
+    def __init__(self, codebase_root: Path, mafia_dir: Path):
+        self._root = codebase_root
+        self._mafia_dir = mafia_dir
+        self._output_dir = mafia_dir / "output"
+        self._graph: Optional[Graph] = None
+        self._config: dict = {}
+
+    # ── Constructors ─────────────────────────────────────────────────────────
+
+    @classmethod
+    def from_path(cls, path: str | Path, *, name: str | None = None) -> "MAFIA":
+        from phase4_source_adapters import resolve_source
+        root = resolve_source(str(path), Path(".mafia"))
+        mafia_dir = root / ".mafia"
+        mafia_dir.mkdir(parents=True, exist_ok=True)
+        (mafia_dir / "output").mkdir(parents=True, exist_ok=True)
+        inst = cls(root, mafia_dir)
+        # Apply mafia.json overrides if present
+        from mafia.config import load_config
+        inst._config = load_config(str(mafia_dir))
+        return inst
+
+    @classmethod
+    def from_archive(cls, archive: str | Path, *, name: str | None = None) -> "MAFIA":
+        from phase4_source_adapters import resolve_source
+        work_dir = Path(".mafia")
+        root = resolve_source(str(archive), work_dir)
+        mafia_dir = root / ".mafia"
+        mafia_dir.mkdir(parents=True, exist_ok=True)
+        (mafia_dir / "output").mkdir(parents=True, exist_ok=True)
+        return cls(root, mafia_dir)
+
+    @classmethod
+    def from_git(cls, url: str, *, ref: str = "HEAD", name: str | None = None) -> "MAFIA":
+        from phase4_source_adapters.git_adapter import GitAdapter
+        root = GitAdapter().resolve(url, Path(".mafia"), ref=ref)
+        mafia_dir = root / ".mafia"
+        mafia_dir.mkdir(parents=True, exist_ok=True)
+        (mafia_dir / "output").mkdir(parents=True, exist_ok=True)
+        return cls(root, mafia_dir)
+
+    @classmethod
+    def open(cls, mafia_dir: str | Path) -> "MAFIA":
+        """Open an already-initialized .mafia/ directory."""
+        md = Path(mafia_dir)
+        if not md.exists():
+            raise FileNotFoundError(f".mafia directory not found: {md}")
+        root = md.parent
+        return cls(root, md)
+
+    # ── Pipeline methods ─────────────────────────────────────────────────────
+
+    def scan(self) -> "MAFIA":
+        from phase2_repo_intake.scope_discovery import discover
+        from phase2_repo_intake.manifest_writer import write_workspace_manifest
+        result = discover(str(self._root))
+        write_workspace_manifest(result, str(self._output_dir))
+        return self
+
+    def extract(self, *, full: bool = False, workers: int = 8) -> "MAFIA":
+        # Build a minimal manifest for the dispatcher
+        manifest_path = self._output_dir / "repo_manifest.json"
+        if not manifest_path.exists():
+            self.scan()
+        from phase3_extraction_framework.dispatcher import ExtractionDispatcher
+        from phase4_extractors.generic.ast_extractor import GenericAstExtractor
+        dispatcher = ExtractionDispatcher(str(manifest_path), str(self._output_dir))
+        dispatcher.register("*", GenericAstExtractor)
+        # Try to register framework extractors if available
+        try:
+            from phase4_extractors.ui.ui_extractor import UiExtractor
+            dispatcher.register("ui", UiExtractor)
+        except Exception:
+            pass
+        try:
+            from phase4_extractors.bff.bff_extractor import BffExtractor
+            dispatcher.register("bff", BffExtractor)
+        except Exception:
+            pass
+        try:
+            from phase4_extractors.api.api_extractor import ApiExtractor
+            dispatcher.register("api", ApiExtractor)
+        except Exception:
+            pass
+        dispatcher.run(repo_workers=1, file_workers=workers)
+        return self
+
+    def stitch(self) -> "MAFIA":
+        from phase3_extraction_framework.cross_scope import run_all_stitchers
+        run_all_stitchers(str(self._output_dir))
+        return self
+
+    def build_graph(self) -> "MAFIA":
+        from phase9_graph.graph_builder import build_graph
+        build_graph(str(self._output_dir))
+        self._graph = None  # reset lazy cache
+        return self
+
+    def run_all(self, *, full: bool = False) -> "MAFIA":
+        return self.scan().extract(full=full).stitch().build_graph()
+
+    def update(self) -> "MAFIA":
+        return self.scan().extract().stitch().build_graph()
+
+    # ── Scope inspection ─────────────────────────────────────────────────────
+
+    @property
+    def codebase(self):
+        manifest = self._load_workspace_manifest()
+        if manifest:
+            return manifest.get("codebase", {})
+        return {"id": self._root.name, "root": str(self._root)}
+
+    @property
+    def repos(self) -> list:
+        manifest = self._load_workspace_manifest()
+        return manifest.get("repos", []) if manifest else []
+
+    @property
+    def workspaces(self) -> list:
+        manifest = self._load_workspace_manifest()
+        if not manifest:
+            return []
+        result = []
+        for repo in manifest.get("repos", []):
+            result.extend(repo.get("workspaces", []))
+        return result
+
+    # ── Graph queries ────────────────────────────────────────────────────────
+
+    def _get_graph(self) -> Graph:
+        if self._graph is None:
+            self._graph = Graph(str(self._output_dir))
+        return self._graph
+
+    def search(self, query: str, *, layer: str | None = None, limit: int = 10) -> list:
+        return self._get_graph().search(query, layer=layer, limit=limit)
+
+    def neighbors(self, eid: str | EntityID, *, direction: str = "both", depth: int = 1) -> dict:
+        return self._get_graph().neighbors(str(eid), direction=direction, depth=depth)
+
+    def trace(self, eid: str | EntityID, *, depth: int = 10) -> dict:
+        return self._get_graph().trace(str(eid), depth=depth)
+
+    def blast(self, eid: str | EntityID, *, direction: str = "downstream", depth: int = 4) -> dict:
+        return self._get_graph().neighbors(str(eid), direction=direction, depth=depth)
+
+    def flows(self, *, node: str | EntityID | None = None) -> list:
+        return self._get_graph().flows(node=str(node) if node else None)
+
+    def path(self, src: str | EntityID, dst: str | EntityID) -> Optional[dict]:
+        return self._get_graph().path(str(src), str(dst))
+
+    def orphans(self) -> list:
+        return self._get_graph().orphans()
+
+    # ── Cross-scope queries ──────────────────────────────────────────────────
+
+    def shared_libs(self) -> list:
+        return self._load_shared_resources().get("shared_libs", [])
+
+    def shared_tables(self) -> list:
+        return self._load_shared_resources().get("shared_tables", [])
+
+    def shared_envs(self) -> list:
+        return self._load_shared_resources().get("shared_envs", [])
+
+    def cross_repo_edges(self) -> list:
+        return self._load_cross_edges("repo")
+
+    def cross_workspace_edges(self) -> list:
+        return self._load_cross_edges("workspace")
+
+    # ── Export ────────────────────────────────────────────────────────────────
+
+    def export_graph(self, path: str | Path) -> None:
+        import shutil
+        sg = self._output_dir / "system_graph.json"
+        if sg.exists():
+            shutil.copy2(sg, path)
+
+    def networkx_graph(self):
+        import networkx as nx
+        g = self._get_graph()
+        G = nx.DiGraph()
+        for nid, node in g.nodes().items():
+            G.add_node(nid, **node)
+        for (s, t), edge in g.edges().items():
+            G.add_edge(s, t, **edge)
+        return G
+
+    # ── Skill adapter ────────────────────────────────────────────────────────
+
+    def as_skill(self) -> "Skill":
+        from mafia.skill import Skill
+        return Skill(self)
+
+    # ── Internal helpers ─────────────────────────────────────────────────────
+
+    def _load_workspace_manifest(self) -> Optional[dict]:
+        p = self._output_dir / "workspace_manifest.json"
+        if p.exists():
+            return json.loads(p.read_text(encoding="utf-8"))
+        return None
+
+    def _load_shared_resources(self) -> dict:
+        p = self._output_dir / "shared_resources.json"
+        if p.exists():
+            return json.loads(p.read_text(encoding="utf-8"))
+        return {}
+
+    def _load_cross_edges(self, boundary: str) -> list:
+        p = self._output_dir / "relations.jsonl"
+        if not p.exists():
+            return []
+        edges = []
+        for line in p.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            r = json.loads(line)
+            if r.get("cross_scope") and r.get("boundary") == boundary:
+                edges.append(r)
+        return edges

mafia/compat.py

@@ -0,0 +1,8 @@
+"""MAFIA public API — backward compatibility helpers."""
+
+from schemas.id_format import migrate_entity_id_v1_to_v2
+
+
+def migrate_id(old_id: str) -> str:
+    """Migrate a v1 entity ID to v2 format (currently identity)."""
+    return migrate_entity_id_v1_to_v2(old_id)

mafia/config.py

@@ -0,0 +1,16 @@
+"""MAFIA config loader — reads .mafia/mafia.json."""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+def load_config(mafia_dir: str | Path) -> dict:
+    """Load .mafia/mafia.json if present, else return empty dict."""
+    p = Path(mafia_dir) / "mafia.json"
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return {}

mafia/graph.py

@@ -0,0 +1,67 @@
+"""MAFIA public API — Graph wrapper."""
+
+from pathlib import Path
+from typing import Optional
+
+
+class Graph:
+    """Lazy-loading wrapper around system_graph.json + e2e_flows.json."""
+
+    def __init__(self, output_dir: str):
+        self._output_dir = Path(output_dir)
+        self._gq = None
+
+    def _ensure_loaded(self):
+        if self._gq is not None:
+            return
+        from phase9_graph.graph_query import GraphQuery
+        sg = self._output_dir / "system_graph.json"
+        fl = self._output_dir / "e2e_flows.json"
+        self._gq = GraphQuery(
+            str(sg) if sg.exists() else None,
+            str(fl) if fl.exists() else None,
+        )
+
+    def nodes(self) -> dict:
+        self._ensure_loaded()
+        return dict(self._gq.nodes)
+
+    def edges(self) -> dict:
+        self._ensure_loaded()
+        return dict(self._gq._edges)
+
+    def node(self, eid: str) -> Optional[dict]:
+        self._ensure_loaded()
+        return self._gq.nodes.get(eid)
+
+    def neighbors(self, eid: str, direction: str = "both", depth: int = 2) -> dict:
+        self._ensure_loaded()
+        return self._gq.neighborhood(eid, direction=direction, depth=depth)
+
+    def search(self, query: str, layer: str = None, limit: int = 10) -> list:
+        self._ensure_loaded()
+        return self._gq.find_by_name(query, layer=layer, limit=limit)
+
+    def trace(self, eid: str, depth: int = 10) -> dict:
+        self._ensure_loaded()
+        return self._gq.trace_flow(eid, max_depth=depth)
+
+    def flows(self, node: str = None, limit: int = 10) -> list:
+        self._ensure_loaded()
+        if node:
+            return self._gq.flows_for_node(node, limit=limit)
+        return self._gq.complete_flows(limit=limit)
+
+    def path(self, src: str, dst: str) -> Optional[dict]:
+        self._ensure_loaded()
+        return self._gq.find_path(src, dst)
+
+    def orphans(self) -> list:
+        self._ensure_loaded()
+        return self._gq.orphan_nodes()
+
+    @property
+    def query(self):
+        """Access the underlying GraphQuery for advanced operations."""
+        self._ensure_loaded()
+        return self._gq

mafia/ids.py

@@ -0,0 +1,60 @@
+"""MAFIA public API — EntityID type."""
+
+from schemas.id_format import parse_entity_id, ParsedEntityId
+
+
+class EntityID:
+    """Thin wrapper around a parsed entity ID string."""
+
+    def __init__(self, eid: str):
+        self._raw = eid
+        self._parsed = parse_entity_id(eid)
+
+    @classmethod
+    def from_string(cls, s: str) -> "EntityID":
+        return cls(s)
+
+    @property
+    def layer(self) -> str:
+        return self._parsed.layer
+
+    @property
+    def entity_type(self) -> str:
+        return self._parsed.entity_type
+
+    @property
+    def scope_path(self) -> str:
+        return self._parsed.scope_path
+
+    @property
+    def qualifier(self) -> str:
+        return self._parsed.qualifier
+
+    @property
+    def codebase(self) -> str:
+        parts = self._parsed.scope_path.split("/")
+        return parts[0]
+
+    @property
+    def repo(self) -> str:
+        parts = self._parsed.scope_path.split("/")
+        return parts[1] if len(parts) > 1 else parts[0]
+
+    @property
+    def workspace(self) -> str:
+        parts = self._parsed.scope_path.split("/")
+        return parts[-1]
+
+    def __str__(self) -> str:
+        return self._raw
+
+    def __repr__(self) -> str:
+        return f"EntityID({self._raw!r})"
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, EntityID):
+            return self._raw == other._raw
+        return self._raw == str(other)
+
+    def __hash__(self) -> int:
+        return hash(self._raw)

mafia/migrate.py

@@ -0,0 +1,92 @@
+"""
+MAFIA Migrate
+==============
+Rewrites v1 artifacts to v2 format in place. Backs up originals.
+"""
+
+import json
+import shutil
+from pathlib import Path
+
+from schemas.id_format import migrate_entity_id_v1_to_v2, ID_FORMAT_VERSION
+
+
+def migrate(output_dir: str) -> dict:
+    """Migrate v1 artifacts to v2 in place. Returns migration stats."""
+    out = Path(output_dir)
+    backup = out / "backup-v1"
+
+    stats = {"entities_migrated": 0, "relations_migrated": 0, "already_v2": False}
+
+    # Check if already v2
+    sidecar = out / "id_format.json"
+    if sidecar.exists():
+        data = json.loads(sidecar.read_text(encoding="utf-8"))
+        if data.get("id_format_version", 1) >= 2:
+            stats["already_v2"] = True
+            return stats
+
+    # Backup
+    backup.mkdir(parents=True, exist_ok=True)
+    for fname in ("entities.jsonl", "relations.jsonl", "system_graph.json", "e2e_flows.json"):
+        src = out / fname
+        if src.exists():
+            shutil.copy2(src, backup / fname)
+
+    # Migrate entities.jsonl
+    ent_path = out / "entities.jsonl"
+    if ent_path.exists():
+        lines = ent_path.read_text(encoding="utf-8").splitlines()
+        migrated = []
+        for line in lines:
+            if not line.strip():
+                continue
+            e = json.loads(line)
+            eid = e.get("id", "")
+            try:
+                e["id"] = migrate_entity_id_v1_to_v2(eid)
+            except Exception:
+                pass
+            # Add v2 fields if missing
+            if "scope_path" not in e:
+                e["scope_path"] = e.get("repo", "")
+            if "codebase" not in e:
+                e["codebase"] = e.get("repo", "")
+            if "workspace" not in e:
+                e["workspace"] = e.get("repo", "")
+            migrated.append(json.dumps(e, ensure_ascii=False))
+            stats["entities_migrated"] += 1
+        ent_path.write_text("\n".join(migrated) + "\n", encoding="utf-8")
+
+    # Migrate relations.jsonl
+    rel_path = out / "relations.jsonl"
+    if rel_path.exists():
+        lines = rel_path.read_text(encoding="utf-8").splitlines()
+        migrated = []
+        for line in lines:
+            if not line.strip():
+                continue
+            r = json.loads(line)
+            if "cross_scope" not in r:
+                r["cross_scope"] = False
+            if "boundary" not in r:
+                r["boundary"] = None
+            migrated.append(json.dumps(r, ensure_ascii=False))
+            stats["relations_migrated"] += 1
+        rel_path.write_text("\n".join(migrated) + "\n", encoding="utf-8")
+
+    # Migrate system_graph.json
+    sg_path = out / "system_graph.json"
+    if sg_path.exists():
+        sg = json.loads(sg_path.read_text(encoding="utf-8"))
+        if "id_format_version" not in sg:
+            sg["id_format_version"] = ID_FORMAT_VERSION
+            for node in sg.get("nodes", []):
+                if "scope_path" not in node:
+                    node["scope_path"] = node.get("repo", "")
+            sg_path.write_text(json.dumps(sg, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # Write sidecar
+    sidecar.write_text(json.dumps({"id_format_version": ID_FORMAT_VERSION}), encoding="utf-8")
+
+    return stats

mafia/plugins.py

@@ -0,0 +1,64 @@
+"""
+MAFIA Plugin Loader
+====================
+Discovers plugins via importlib.metadata entry points.
+Groups: mafia.extractors, mafia.workspace_detectors, mafia.source_adapters
+"""
+
+from typing import Optional
+
+
+def load_plugins(group: str, config: Optional[dict] = None) -> dict[str, type]:
+    """Load plugins from entry points for the given group.
+
+    Args:
+        group: entry point group name (e.g. 'mafia.extractors')
+        config: optional plugins config from mafia.json with enable/disable/order
+
+    Returns:
+        dict of name → class, filtered and ordered per config.
+    """
+    try:
+        from importlib.metadata import entry_points
+        eps = entry_points(group=group)
+    except Exception:
+        return {}
+
+    plugins = {}
+    for ep in eps:
+        try:
+            plugins[ep.name] = ep.load()
+        except Exception:
+            continue
+
+    if not config:
+        return plugins
+
+    # Apply enable/disable/order from config
+    enable = config.get("enable")
+    disable = set(config.get("disable", []))
+    order = config.get("order", [])
+
+    if enable is not None:
+        enable_set = set(enable)
+        plugins = {k: v for k, v in plugins.items() if k in enable_set}
+
+    plugins = {k: v for k, v in plugins.items() if k not in disable}
+
+    if order:
+        ordered = {}
+        for name in order:
+            if name == "..." :
+                # "..." means "all remaining in original order"
+                for k, v in plugins.items():
+                    if k not in ordered:
+                        ordered[k] = v
+            elif name in plugins:
+                ordered[name] = plugins[name]
+        # Add any remaining not in order list
+        for k, v in plugins.items():
+            if k not in ordered:
+                ordered[k] = v
+        plugins = ordered
+
+    return plugins