vizzpy 0.1.0__py3-none-any.whl

vizzpy/cli.py

@@ -0,0 +1,56 @@
+"""
+vizzpy CLI entry point.
+
+Usage:
+  vizzpy --serve [--host HOST] [--port PORT]
+  vizzpy --headless <project_path> [--output output.svg]
+"""
+from __future__ import annotations
+import argparse
+import sys
+from pathlib import Path
+
+
+def cli() -> None:
+    parser = argparse.ArgumentParser(
+        prog="vizzpy",
+        description="Python call tree visualizer",
+    )
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--serve", action="store_true", help="Start the web server")
+    mode.add_argument("--headless", metavar="PROJECT_PATH", help="Render SVG without a web server")
+
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind (serve mode)")
+    parser.add_argument("--port", type=int, default=8000, help="Port to bind (serve mode)")
+    parser.add_argument("--output", default="call_tree.svg", help="Output SVG path (headless mode)")
+
+    args = parser.parse_args()
+
+    if args.serve:
+        _run_server(args.host, args.port)
+    else:
+        _run_headless(Path(args.headless), Path(args.output))
+
+
+def _run_server(host: str, port: int) -> None:
+    try:
+        import uvicorn
+    except ImportError:
+        sys.exit("uvicorn is required for serve mode: pip install uvicorn[standard]")
+
+    from vizzpy.server import app
+    uvicorn.run(app, host=host, port=port)
+
+
+def _run_headless(project_path: Path, output_path: Path) -> None:
+    if not project_path.exists():
+        sys.exit(f"Project path does not exist: {project_path}")
+
+    from vizzpy.render import render_svg
+    print(f"Analyzing {project_path} ...")
+    render_svg(project_path, output_path)
+    print(f"SVG written to {output_path}")
+
+
+if __name__ == "__main__":
+    cli()

vizzpy/graph.py

@@ -0,0 +1,69 @@
+"""
+Converts raw (caller, callee) edges into a JSON-serializable graph structure
+that the frontend and render layer both consume.
+"""
+from __future__ import annotations
+from collections import defaultdict
+from pathlib import Path
+
+from .parser.project import analyze_project
+from .parser.scope import FuncSpan
+
+
+def build_graph(root: Path) -> dict:
+    """
+    Analyze the project at *root* and return a dict with shape:
+
+    {
+      "nodes": [{"id": str, "label": str, "module": str, "docstring": str|null}],
+      "edges": [{"source": str, "target": str, "count": int}],
+      "modules": {"module.name": ["node_id", ...]}
+    }
+    """
+    edges_raw, node_info = analyze_project(root)
+
+    # Collect unique node ids from edges only (skip isolates)
+    node_ids: set[str] = set()
+    for src, tgt in edges_raw:
+        node_ids.add(src)
+        node_ids.add(tgt)
+
+    # Deduplicate edges and count multiplicity
+    edge_counts: dict[tuple[str, str], int] = defaultdict(int)
+    for src, tgt in edges_raw:
+        edge_counts[(src, tgt)] += 1
+
+    # Build node list
+    nodes = []
+    for nid in sorted(node_ids):
+        span: FuncSpan | None = node_info.get(nid)
+        nodes.append({
+            "id": nid,
+            "label": span.display_name if span else _fallback_label(nid),
+            "module": span.module_name if span else _fallback_module(nid),
+            "docstring": span.docstring if span else None,
+        })
+
+    # Build module → [node_id] grouping
+    modules: dict[str, list[str]] = defaultdict(list)
+    for node in nodes:
+        modules[node["module"]].append(node["id"])
+
+    return {
+        "nodes": nodes,
+        "edges": [
+            {"source": src, "target": tgt, "count": cnt}
+            for (src, tgt), cnt in sorted(edge_counts.items())
+        ],
+        "modules": dict(modules),
+    }
+
+
+def _fallback_label(qname: str) -> str:
+    """Best-effort display label when a node has no FuncSpan (e.g. __main__ calls)."""
+    return qname.split(".")[-1]
+
+
+def _fallback_module(qname: str) -> str:
+    parts = qname.split(".")
+    return ".".join(parts[:-1]) if len(parts) > 1 else qname

vizzpy/parser/project.py

@@ -0,0 +1,87 @@
+"""
+Multi-file project analysis: discovers all .py files, builds scopes,
+resolves cross-module imports, and emits the full edge list.
+"""
+from __future__ import annotations
+import ast
+import logging
+from pathlib import Path
+
+from .scope import FuncSpan
+from .walker import build_scope, build_import_map, CallVisitor
+
+logger = logging.getLogger(__name__)
+
+
+def _is_test_file(f: Path) -> bool:
+    """Return True for files that are part of a test suite."""
+    parts = f.parts
+    return (
+        f.name.startswith("test_")
+        or f.name.endswith("_test.py")
+        or any(p in ("tests", "test") for p in parts)
+    )
+
+
+def get_module_name(file_path: Path, root: Path) -> str:
+    """Convert an absolute file path to its dotted module name relative to *root*."""
+    rel = file_path.relative_to(root)
+    parts = list(rel.parts)
+    if parts[-1] == "__init__.py":
+        parts = parts[:-1]
+    else:
+        parts[-1] = parts[-1][:-3]  # strip .py
+    return ".".join(parts) if parts else "__root__"
+
+
+def analyze_project(root: Path) -> tuple[list[tuple[str, str]], dict[str, FuncSpan]]:
+    """
+    Parse every .py file under *root* and return:
+      edges      — list of (caller_qname, callee_qname)
+      node_info  — dict mapping qname -> FuncSpan (for label/docstring lookup)
+    """
+    py_files = sorted(f for f in root.rglob("*.py") if not _is_test_file(f))
+
+    # Pass 1: parse every file and build per-module scopes
+    modules: dict[str, tuple[ast.AST, object]] = {}  # module_name -> (tree, scope)
+    for f in py_files:
+        module_name = get_module_name(f, root)
+        try:
+            source = f.read_text(encoding="utf-8", errors="replace")
+            tree = ast.parse(source, filename=str(f))
+            scope = build_scope(module_name, tree)
+            modules[module_name] = (tree, scope)
+        except SyntaxError as exc:
+            logger.warning("Skipping %s — syntax error: %s", f, exc)
+
+    # Collect the project-wide set of known qualified names
+    all_names: set[str] = set()
+    node_info: dict[str, FuncSpan] = {}
+    for _module_name, (_tree, scope) in modules.items():
+        all_names |= scope.names
+        for span in scope.spans:
+            node_info[span.qualified_name] = span
+
+    # Build suffix index: maps every trailing dotted suffix of each qname to that qname.
+    # Used to resolve imports whose top-level package name differs from the folder name
+    # (e.g. code imports "xml_framework.x" but the folder is "xml_framework_updated").
+    # Values of None indicate an ambiguous suffix (two qnames share the same suffix).
+    suffix_index: dict[str, str | None] = {}
+    for qname in all_names:
+        parts = qname.split(".")
+        for i in range(1, len(parts)):        # skip i=0 (full name already in all_names)
+            suffix = ".".join(parts[i:])
+            if suffix in suffix_index:
+                suffix_index[suffix] = None   # ambiguous — mark, don't use
+            else:
+                suffix_index[suffix] = qname
+
+    # Pass 2: extract edges from each module
+    edges: list[tuple[str, str]] = []
+    for module_name, (tree, _scope) in modules.items():
+        import_map = build_import_map(tree, module_name)
+        visitor = CallVisitor(module_name, import_map, all_names, suffix_index)
+        visitor.visit(tree)
+        edges.extend(visitor.edges)
+
+    return edges, node_info

vizzpy/parser/scope.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class FuncSpan:
+    qualified_name: str   # e.g. "services.order.OrderService.process"
+    display_name: str     # e.g. "OrderService.process" or "OrderService" for __init__
+    module_name: str      # e.g. "services.order"
+    start: int
+    end: int
+    docstring: Optional[str] = None
+
+
+class FuncScope:
+    """Registry of all function/method definitions within a single module."""
+
+    def __init__(self, module_name: str):
+        self.module_name = module_name
+        self._spans: list[FuncSpan] = []
+        self._names: set[str] = set()
+
+    def add(self, span: FuncSpan) -> None:
+        self._spans.append(span)
+        self._names.add(span.qualified_name)
+
+    @property
+    def names(self) -> set[str]:
+        return self._names
+
+    @property
+    def spans(self) -> list[FuncSpan]:
+        return list(self._spans)

vizzpy/parser/walker.py

@@ -0,0 +1,297 @@
+"""
+AST visitors for building function scopes and extracting call edges.
+"""
+from __future__ import annotations
+import ast
+from typing import Optional
+
+from .scope import FuncScope, FuncSpan
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _qualified_name(module: str, class_stack: list[str], func_name: str) -> str:
+    if class_stack:
+        class_name = class_stack[-1]
+        if func_name == "__init__":
+            return f"{module}.{class_name}"
+        return f"{module}.{class_name}.{func_name}"
+    return f"{module}.{func_name}"
+
+
+def _display_name(class_stack: list[str], func_name: str) -> str:
+    if class_stack:
+        class_name = class_stack[-1]
+        if func_name == "__init__":
+            return class_name
+        return f"{class_name}.{func_name}"
+    return func_name
+
+
+# ---------------------------------------------------------------------------
+# Scope builder: first pass — collect all function/method definitions
+# ---------------------------------------------------------------------------
+
+class ScopeBuilder(ast.NodeVisitor):
+    """Collects FuncSpan entries for every top-level function and class method."""
+
+    def __init__(self, module_name: str):
+        self.scope = FuncScope(module_name)
+        self._module = module_name
+        self._class_stack: list[str] = []
+        self._in_func = False  # True once inside any function body
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self._class_stack.append(node.name)
+        self.generic_visit(node)
+        self._class_stack.pop()
+
+    def _visit_funcdef(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        # Only register top-level functions and direct class methods, not nested functions.
+        if not self._in_func:
+            qname = _qualified_name(self._module, self._class_stack, node.name)
+            dname = _display_name(self._class_stack, node.name)
+            self.scope.add(FuncSpan(
+                qualified_name=qname,
+                display_name=dname,
+                module_name=self._module,
+                start=node.lineno,
+                end=node.end_lineno,
+                docstring=ast.get_docstring(node),
+            ))
+        prev = self._in_func
+        self._in_func = True
+        self.generic_visit(node)
+        self._in_func = prev
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_funcdef(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_funcdef(node)
+
+
+def build_scope(module_name: str, tree: ast.AST) -> FuncScope:
+    builder = ScopeBuilder(module_name)
+    builder.visit(tree)
+    return builder.scope
+
+
+# ---------------------------------------------------------------------------
+# Import resolution: build a map from local alias → qualified name
+# ---------------------------------------------------------------------------
+
+def build_import_map(tree: ast.AST, module_name: str) -> dict[str, str]:
+    """
+    Returns {local_name: qualified_name} for all imports in the file.
+
+    Examples:
+      from services.order import OrderService       -> {'OrderService': 'services.order.OrderService'}
+      from services.order import OrderService as OS -> {'OS': 'services.order.OrderService'}
+      import services.order                         -> {'services': 'services', 'services.order': 'services.order'}
+    """
+    import_map: dict[str, str] = {}
+    module_parts = module_name.split(".")
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if node.names and node.names[0].name == "*":
+                continue  # skip star imports — can't resolve statically
+
+            mod = node.module or ""
+
+            # Resolve relative imports
+            if node.level > 0:
+                base = module_parts[:max(0, len(module_parts) - node.level)]
+                mod = ".".join(base + ([mod] if mod else []))
+
+            for alias in node.names:
+                local = alias.asname if alias.asname else alias.name
+                import_map[local] = f"{mod}.{alias.name}" if mod else alias.name
+
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                local = alias.asname if alias.asname else alias.name
+                import_map[local] = alias.name
+                # Also register dotted prefix so `services.order.func` resolves
+                if "." in alias.name:
+                    parts = alias.name.split(".")
+                    for i in range(1, len(parts) + 1):
+                        prefix = ".".join(parts[:i])
+                        import_map.setdefault(prefix, prefix)
+
+    return import_map
+
+
+# ---------------------------------------------------------------------------
+# Call visitor: second pass — extract caller → callee edges
+# ---------------------------------------------------------------------------
+
+class CallVisitor(ast.NodeVisitor):
+    """
+    Walks the AST of a single module and emits (caller_qname, callee_qname) edges.
+    Only edges where the callee is in *all_names* (the project-wide set of known
+    function qualified names) are recorded.
+    """
+
+    def __init__(
+        self,
+        module_name: str,
+        import_map: dict[str, str],
+        all_names: set[str],
+        suffix_index: dict[str, "str | None"] | None = None,
+    ):
+        self._module = module_name
+        self._import_map = import_map
+        self._all_names = all_names
+        self._suffix_index: dict[str, str | None] = suffix_index or {}
+        self.edges: list[tuple[str, str]] = []
+
+        self._class_stack: list[str] = []
+        # Stack of qualified names representing the current call chain.
+        # Nested functions fall back to their parent's qname as the caller.
+        self._func_stack: list[str] = []
+
+    # -- context tracking ----------------------------------------------------
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self._class_stack.append(node.name)
+        self.generic_visit(node)
+        self._class_stack.pop()
+
+    def _visit_funcdef(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        # Determine the qualified name to use as caller context.
+        # For nested functions, reuse the enclosing registered function's qname.
+        if not self._func_stack:
+            qname = _qualified_name(self._module, self._class_stack, node.name)
+        else:
+            qname = self._func_stack[-1]  # nested → attribute calls still emit from parent
+
+        self._func_stack.append(qname)
+        self.generic_visit(node)
+        self._func_stack.pop()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._visit_funcdef(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._visit_funcdef(node)
+
+    # -- call extraction -----------------------------------------------------
+
+    def visit_Call(self, node: ast.Call) -> None:
+        caller = self._func_stack[-1] if self._func_stack else f"{self._module}.__main__"
+        callee = self._resolve_call(node)
+        if callee and callee in self._all_names and callee != caller:
+            self.edges.append((caller, callee))
+        self.generic_visit(node)
+
+    def _resolve_call(self, node: ast.Call) -> Optional[str]:
+        if isinstance(node.func, ast.Name):
+            return self._resolve_name(node.func.id)
+        if isinstance(node.func, ast.Attribute):
+            return self._resolve_attr(node.func)
+        return None
+
+    def _resolve_name(self, name: str) -> Optional[str]:
+        # Check import map first
+        if name in self._import_map:
+            candidate = self._import_map[name]
+            if candidate in self._all_names:
+                return candidate
+            # Import found but qname unknown — try suffix matching to handle
+            # package renames (e.g. folder is "pkg_v2" but code imports "pkg")
+            result = self._resolve_via_suffix(candidate)
+            if result:
+                return result
+        # Try as a function in this module
+        qname = f"{self._module}.{name}"
+        return qname if qname in self._all_names else None
+
+    def _resolve_via_suffix(self, candidate: str) -> Optional[str]:
+        """
+        Try progressively shorter suffixes of *candidate* against the suffix index.
+        Returns the unambiguous match, or None if not found / ambiguous.
+        """
+        parts = candidate.split(".")
+        for i in range(1, len(parts)):
+            suffix = ".".join(parts[i:])
+            if suffix in self._suffix_index:
+                return self._suffix_index[suffix]  # None if ambiguous
+        return None
+
+    def _resolve_attr(self, node: ast.Attribute) -> Optional[str]:
+        attr = node.attr
+
+        # self.method()
+        if isinstance(node.value, ast.Name) and node.value.id == "self":
+            return self._resolve_self_attr(attr)
+
+        # cls.method()
+        if isinstance(node.value, ast.Name) and node.value.id == "cls":
+            return self._resolve_cls_attr(attr)
+
+        # SomeName.method() — could be ClassName.method, module.func, or imported.func
+        if isinstance(node.value, ast.Name):
+            return self._resolve_dotted(node.value.id, attr)
+
+        # module.submodule.func() — e.g. ast.Attribute chain
+        if isinstance(node.value, ast.Attribute):
+            # Reconstruct the dotted prefix as best we can
+            prefix = self._unparse_attr_chain(node.value)
+            if prefix:
+                qname = f"{prefix}.{attr}"
+                if qname in self._all_names:
+                    return qname
+                # Maybe prefix is an import alias
+                if prefix in self._import_map:
+                    qname = f"{self._import_map[prefix]}.{attr}"
+                    if qname in self._all_names:
+                        return qname
+                # Suffix fallback for chained attribute calls
+                result = self._resolve_via_suffix(qname)
+                if result:
+                    return result
+
+        return None
+
+    def _resolve_self_attr(self, attr: str) -> Optional[str]:
+        if not self._class_stack:
+            return None
+        class_name = self._class_stack[-1]
+        if attr == "__init__":
+            qname = f"{self._module}.{class_name}"
+        else:
+            qname = f"{self._module}.{class_name}.{attr}"
+        return qname if qname in self._all_names else None
+
+    def _resolve_cls_attr(self, attr: str) -> Optional[str]:
+        if not self._class_stack:
+            return None
+        class_name = self._class_stack[-1]
+        qname = f"{self._module}.{class_name}.{attr}"
+        return qname if qname in self._all_names else None
+
+    def _resolve_dotted(self, obj_name: str, attr: str) -> Optional[str]:
+        # obj is an import alias pointing to a module or class
+        if obj_name in self._import_map:
+            base = self._import_map[obj_name]
+            qname = f"{base}.{attr}"
+            if qname in self._all_names:
+                return qname
+        # obj is a class in this module (ClassName.method or ClassName() == __init__)
+        qname = f"{self._module}.{obj_name}.{attr}"
+        if qname in self._all_names:
+            return qname
+        return None
+
+    def _unparse_attr_chain(self, node: ast.expr) -> Optional[str]:
+        """Reconstruct a dotted name from a chain of ast.Attribute nodes."""
+        if isinstance(node, ast.Name):
+            return node.id
+        if isinstance(node, ast.Attribute):
+            prefix = self._unparse_attr_chain(node.value)
+            return f"{prefix}.{node.attr}" if prefix else None
+        return None

vizzpy/render.py

@@ -0,0 +1,67 @@
+"""
+Headless SVG rendering via the graphviz Python package.
+
+The graphviz package is a thin wrapper around the `dot` binary (Graphviz).
+Install Graphviz system package first:
+  macOS:  brew install graphviz
+  Ubuntu: apt install graphviz
+"""
+from __future__ import annotations
+from pathlib import Path
+
+import graphviz  # type: ignore
+
+from .graph import build_graph
+
+
+def render_svg(project_root: Path, output_path: Path) -> None:
+    """
+    Analyze *project_root* and write the call graph as an SVG to *output_path*.
+    """
+    graph_data = build_graph(project_root)
+    dot = _to_dot(graph_data)
+    svg_source = dot.pipe(format="svg").decode("utf-8")
+    output_path.write_text(svg_source, encoding="utf-8")
+
+
+def _to_dot(graph_data: dict) -> graphviz.Digraph:
+    dot = graphviz.Digraph(
+        graph_attr={
+            "rankdir": "LR",
+            "fontname": "Helvetica",
+            "splines": "ortho",
+            "nodesep": "0.5",
+            "ranksep": "1.0",
+        },
+        node_attr={
+            "shape": "box",
+            "style": "rounded,filled",
+            "fillcolor": "#dbe9f4",
+            "fontname": "Helvetica",
+            "fontsize": "11",
+        },
+        edge_attr={
+            "fontname": "Helvetica",
+            "fontsize": "9",
+        },
+    )
+
+    # Add module subgraphs (clusters)
+    for module_name, node_ids in graph_data["modules"].items():
+        with dot.subgraph(name=f"cluster_{module_name}") as sub:
+            sub.attr(label=module_name, style="rounded", color="#aaaaaa", fontsize="10")
+            for nid in node_ids:
+                # Find label for this node
+                label = nid  # fallback
+                for n in graph_data["nodes"]:
+                    if n["id"] == nid:
+                        label = n["label"]
+                        break
+                sub.node(nid, label=label)
+
+    # Add edges
+    for edge in graph_data["edges"]:
+        label = str(edge["count"]) if edge["count"] > 1 else ""
+        dot.edge(edge["source"], edge["target"], label=label)
+
+    return dot