archview 0.2.0__tar.gz

archview-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lorenzo Mirante
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archview-0.2.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: archview
+Version: 0.2.0
+Summary: Interactive live architecture viewer for Python projects
+Requires-Python: >=3.9
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Dynamic: license-file

archview-0.2.0/README.md

@@ -0,0 +1,112 @@
+# ArchView
+
+**See your codebase. Understand it. Then change it.**
+
+ArchView gives you a live, interactive map of any Python project's architecture — right in your browser. It parses real Python (via AST, not regex), watches for changes, and updates the graph in real time.
+
+Built for developers who vibe-code and need to stay oriented, or anyone inheriting a codebase they didn't write.
+
+![ArchView interface](docs/interface.png)
+
+## Why
+
+You're 200 files deep in someone else's project. Or you're building fast and your own code is getting tangled. You need to *see* the structure — what depends on what, where the entry points are, which modules are isolated.
+
+ArchView shows you all of that in seconds, and keeps updating as you code.
+
+## Install
+
+```bash
+pip install archview
+```
+
+Available on [PyPI](https://pypi.org/project/archview/). Pure Python, works anywhere with Python 3.9+.
+
+## Usage
+
+```bash
+archview /path/to/your/project
+```
+
+Open http://localhost:9090 — that's it.
+
+```bash
+# Custom port and refresh interval
+archview /path/to/project --port 8080 --interval 5
+```
+
+## What you see
+
+| Color | Meaning |
+|-------|---------|
+| **Green** | Entry points — modules that import but aren't imported |
+| **Blue** | Connectors — modules that both import and are imported |
+| **Red** | Utilities — leaf modules only imported by others |
+| **Gray** | Isolated — no import relationships |
+| **Red (bright)** | Syntax errors — files that failed to parse |
+
+<!-- TODO: replace with actual GIF -->
+![Node colors and types](docs/colors.gif)
+
+## Features
+
+### Live refresh
+Edit your code, save — the graph updates automatically. No restart needed.
+
+<!-- TODO: replace with actual GIF -->
+![Live refresh](docs/live-refresh.gif)
+
+### Interactive exploration
+- **Hover** a node to see its docstring, type, and exported symbols
+- **Click** a node to highlight its direct dependencies
+- **Double-click** to open the file in VS Code
+- **Drag** nodes to rearrange the layout
+- **Click folders** to collapse/expand entire packages
+
+<!-- TODO: replace with actual GIF -->
+![Interactive exploration](docs/interaction.gif)
+
+### Dependency highlighting
+Hover over an edge to see exactly which symbols are imported. Click a node and its entire dependency chain lights up — everything else fades.
+
+### Export
+- **PNG** — screenshot the current view
+- **Save** — persist node positions (restored on next launch)
+
+### Ignore patterns
+
+```bash
+# Exclude directories from analysis
+archview ignore tests __pycache__ venv
+
+# List current patterns
+archview ignore --list
+
+# Remove a pattern
+archview ignore --remove tests
+```
+
+## How it works
+
+1. Collects all `.py` files (git-aware, respects `.archviewignore`)
+2. Parses each file's AST to extract imports, functions, classes
+3. Builds a dependency graph with classified nodes
+4. Renders it with [Cytoscape.js](https://js.cytoscape.org/) + [Dagre](https://github.com/dagrejs/dagre) layout
+5. Watches for changes and re-generates every N seconds
+
+**Zero dependencies** — pure Python stdlib. The frontend ships bundled.
+
+## Example
+
+Try it on the example project (hosted on GitHub):
+
+```bash
+git clone https://github.com/lm17918/archview.git archview-demo
+cd archview-demo
+pip install archview
+archview example_project
+```
+
+## License
+
+MIT

archview-0.2.0/archview/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

archview-0.2.0/archview/annotations.py

@@ -0,0 +1,26 @@
+"""Node annotations persistence."""
+
+import json
+
+
+def handle_annotations_get(handler):
+    path = handler.data_dir / "annotations.json"
+    if not path.exists():
+        handler.send_response(404)
+        handler.end_headers()
+        return
+    data = path.read_bytes()
+    handler.send_response(200)
+    handler.send_header("Content-Type", "application/json")
+    handler.send_header("Content-Length", str(len(data)))
+    handler.end_headers()
+    handler.wfile.write(data)
+
+
+def handle_annotations_post(handler):
+    data = handler._read_json_body()
+    if data is None:
+        return
+    (handler.data_dir / "annotations.json").write_text(
+        json.dumps(data, indent=2))
+    handler._json_response({"ok": True})

archview-0.2.0/archview/cli.py

@@ -0,0 +1,236 @@
+import argparse
+import hashlib
+import importlib.resources
+import os
+import signal
+import sys
+import threading
+from pathlib import Path
+
+from archview.graph import generate_graph
+from archview.server import make_server
+
+# Known stdlib module names that are commonly shadowed by project folders
+_STDLIB_NAMES = {
+    "abc", "ast", "asyncio", "base64", "calendar", "collections", "copy",
+    "csv", "ctypes", "datetime", "decimal", "difflib", "email", "enum",
+    "fractions", "functools", "glob", "gzip", "hashlib", "html", "http",
+    "importlib", "inspect", "io", "itertools", "json", "logging", "math",
+    "multiprocessing", "numbers", "operator", "os", "pathlib", "pickle",
+    "platform", "pprint", "profile", "queue", "random", "re", "secrets",
+    "select", "shelve", "shutil", "signal", "socket", "sqlite3",
+    "statistics", "string", "struct", "subprocess", "sys", "tempfile",
+    "test", "textwrap", "threading", "time", "timeit", "token", "tokenize",
+    "trace", "traceback", "types", "typing", "unittest", "urllib", "uuid",
+    "warnings", "weakref", "xml", "xmlrpc", "zipfile", "zipimport",
+}
+
+
+def _check_stdlib_shadowing(project_dir: Path):
+    """Warn if any folder in the project shadows a Python stdlib module."""
+    shadowed = []
+    for item in project_dir.iterdir():
+        if item.is_dir() and item.name in _STDLIB_NAMES:
+            init = item / "__init__.py"
+            if init.exists() or any(item.glob("*.py")):
+                shadowed.append(item.name)
+    if shadowed:
+        print(f"\n  WARNING: These project folders shadow Python stdlib modules:")
+        for name in sorted(shadowed):
+            print(f"    - {name}/")
+        print(f"  This may cause crashes in archview or pip.")
+        print(f"  Consider renaming them.\n")
+
+IGNORE_FILENAME = ".archviewignore"
+
+DEFAULT_IGNORE_PATTERNS = [
+    ".archview",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "node_modules",
+    ".git",
+    "build",
+    "dist",
+    "*.egg-info",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+]
+
+
+def _ignore_file_path(project_dir: Path) -> Path:
+    return project_dir / IGNORE_FILENAME
+
+
+def _ensure_default_ignore_file(project_dir: Path) -> Path:
+    ignore_file = _ignore_file_path(project_dir)
+    if ignore_file.exists():
+        return ignore_file
+    header = "# Auto-generated by archview. Folders/patterns to exclude from analysis (one per line).\n"
+    ignore_file.write_text(header + "\n".join(DEFAULT_IGNORE_PATTERNS) + "\n")
+    print(f"Created default {IGNORE_FILENAME}")
+    return ignore_file
+
+
+def _read_patterns(ignore_file: Path) -> list[str]:
+    if not ignore_file.exists():
+        return []
+    lines = ignore_file.read_text().splitlines()
+    return [l for l in lines if l.strip() and not l.strip().startswith("#")]
+
+
+def _cmd_ignore(args):
+    project_dir = Path(args.project_dir).resolve()
+    ignore_file = _ignore_file_path(project_dir)
+
+    if args.list:
+        patterns = _read_patterns(ignore_file)
+        if not patterns:
+            print("No patterns in .archviewignore")
+        else:
+            print(f"{ignore_file}:")
+            for p in patterns:
+                print(f"  {p}")
+        return
+
+    if args.remove:
+        if not ignore_file.exists():
+            print("No .archviewignore file found")
+            return
+        lines = ignore_file.read_text().splitlines()
+        new_lines = [l for l in lines if l.strip() != args.remove]
+        if len(new_lines) == len(lines):
+            print(f"Pattern not found: {args.remove}")
+            return
+        ignore_file.write_text("\n".join(new_lines) + "\n")
+        print(f"Removed: {args.remove}")
+        return
+
+    if not args.patterns:
+        print("Usage: archview ignore <pattern> [pattern ...]")
+        print("       archview ignore --list")
+        print("       archview ignore --remove <pattern>")
+        return
+
+    existing = _read_patterns(ignore_file)
+    added = []
+    for pattern in args.patterns:
+        if pattern in existing:
+            print(f"Already ignored: {pattern}")
+        else:
+            added.append(pattern)
+
+    if added:
+        write_header = not ignore_file.exists() or ignore_file.stat().st_size == 0
+        with ignore_file.open("a") as f:
+            if write_header:
+                f.write("# Folders/patterns to exclude from analysis (one per line)\n")
+            for p in added:
+                f.write(p + "\n")
+        for p in added:
+            print(f"Added: {p}")
+
+
+def _project_cache_dir(project_dir: Path) -> Path:
+    """Per-project cache dir outside the repo (XDG-style)."""
+    base = Path(
+        os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    ) / "archview"
+    digest = hashlib.sha1(str(project_dir).encode("utf-8")).hexdigest()[:10]
+    return base / f"{project_dir.name}-{digest}"
+
+
+def _cmd_serve(args):
+    project_dir = Path(args.project_dir).resolve()
+    data_dir = _project_cache_dir(project_dir)
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    ignore_file = _ensure_default_ignore_file(project_dir)
+
+    static_dir = Path(str(importlib.resources.files("archview"))) / "static"
+    graph_path = data_dir / "graph.json"
+
+    _check_stdlib_shadowing(project_dir)
+    print("Running initial analysis...")
+    generate_graph(project_dir, ignore_file, graph_path)
+    print(f"Graph generated. Open http://localhost:{args.port}")
+
+    stop_event = threading.Event()
+
+    def watcher():
+        while not stop_event.wait(args.interval):
+            try:
+                generate_graph(project_dir, ignore_file, graph_path)
+            except Exception:
+                pass
+
+    threading.Thread(target=watcher, daemon=True).start()
+
+    server = make_server("127.0.0.1", args.port, static_dir, data_dir,
+                         project_dir, args.interval, ignore_file)
+
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    print("Press Ctrl+C to stop\n")
+
+    shutdown_requested = threading.Event()
+
+    def _request_shutdown(signum, frame):
+        shutdown_requested.set()
+
+    signal.signal(signal.SIGTERM, _request_shutdown)
+    signal.signal(signal.SIGHUP, _request_shutdown)
+
+    try:
+        while server_thread.is_alive() and not shutdown_requested.is_set():
+            server_thread.join(timeout=1)
+    except KeyboardInterrupt:
+        pass
+    stop_event.set()
+    server.shutdown()
+    print("\nStopped.")
+
+
+def main():
+    # If first positional arg is not a known subcommand, inject "serve"
+    # so that `archview example_project` works as `archview serve example_project`
+    known_commands = {"ignore", "serve"}
+    if len(sys.argv) > 1 and sys.argv[1] not in known_commands and not sys.argv[1].startswith("-"):
+        sys.argv.insert(1, "serve")
+
+    parser = argparse.ArgumentParser(
+        prog="archview",
+        description="Interactive live architecture viewer for Python projects",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # --- ignore subcommand ---
+    ignore_parser = subparsers.add_parser("ignore", help="Manage .archviewignore patterns")
+    ignore_parser.add_argument("patterns", nargs="*", help="Patterns to add")
+    ignore_parser.add_argument("--list", "-l", action="store_true", help="List current patterns")
+    ignore_parser.add_argument("--remove", "-r", metavar="PATTERN", help="Remove a pattern")
+    ignore_parser.add_argument("--project-dir", default=".", metavar="DIR")
+
+    # --- serve (default) ---
+    serve_parser = subparsers.add_parser("serve", help="Start the live architecture viewer")
+    serve_parser.add_argument("project_dir", nargs="?", default=".")
+    serve_parser.add_argument("--port", "-p", type=int, default=9090,
+                              choices=range(1, 65536), metavar="PORT")
+    serve_parser.add_argument("--interval", type=int, default=10,
+                              choices=range(1, 3601), metavar="SEC",
+                              help="Graph refresh interval in seconds (default: 10)")
+
+    args = parser.parse_args()
+
+    if args.command == "ignore":
+        _cmd_ignore(args)
+    elif args.command == "serve":
+        _cmd_serve(args)
+    else:
+        # No args at all → default to serve current dir
+        sys.argv.insert(1, "serve")
+        args = parser.parse_args()
+        _cmd_serve(args)

archview-0.2.0/archview/diff.py

@@ -0,0 +1,161 @@
+"""Diff view: compare current graph against a git ref."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+import threading
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+from archview.graph import generate_graph_json
+
+_diff_lock = threading.Lock()
+
+
+def handle_refs(handler):
+    handler._json_response(_list_refs(handler.project_dir))
+
+
+def handle_diff(handler):
+    qs = parse_qs(urlparse(handler.path).query)
+    ref = qs.get("ref", [None])[0]
+    if not ref:
+        handler._json_response({"error": "missing ref param"}, 400)
+        return
+
+    if not _diff_lock.acquire(blocking=False):
+        handler._json_response({"error": "diff already running"}, 429)
+        return
+    try:
+        old = _generate_old_graph(
+            handler.project_dir, ref, handler.ignore_file)
+        cur = generate_graph_json(
+            handler.project_dir, handler.ignore_file)
+        handler._json_response(_compute_diff(cur, old, ref))
+    except subprocess.CalledProcessError:
+        handler._json_response({"error": f"invalid ref: {ref}"}, 400)
+    finally:
+        _diff_lock.release()
+
+
+def _list_refs(project_dir: Path) -> dict:
+    project_dir = Path(project_dir)
+    result: dict[str, list] = {"commits": [], "branches": [], "tags": []}
+
+    try:
+        log = subprocess.run(
+            ["git", "log", "--oneline", "-20"],
+            cwd=project_dir, capture_output=True, text=True, check=True,
+        )
+        for line in log.stdout.strip().splitlines():
+            if not line:
+                continue
+            parts = line.split(None, 1)
+            result["commits"].append({
+                "hash": parts[0],
+                "message": parts[1] if len(parts) > 1 else "",
+            })
+    except subprocess.CalledProcessError:
+        pass
+
+    try:
+        branches = subprocess.run(
+            ["git", "branch", "--format=%(refname:short)"],
+            cwd=project_dir, capture_output=True, text=True, check=True,
+        )
+        result["branches"] = [
+            b.strip() for b in branches.stdout.strip().splitlines()
+            if b.strip()
+        ]
+    except subprocess.CalledProcessError:
+        pass
+
+    try:
+        tags = subprocess.run(
+            ["git", "tag"],
+            cwd=project_dir, capture_output=True, text=True, check=True,
+        )
+        result["tags"] = [
+            t.strip() for t in tags.stdout.strip().splitlines()
+            if t.strip()
+        ]
+    except subprocess.CalledProcessError:
+        pass
+
+    return result
+
+
+def _generate_old_graph(project_dir: Path, ref: str,
+                        ignore_file: Path | None) -> list[dict]:
+    project_dir = Path(project_dir)
+    subprocess.run(
+        ["git", "rev-parse", "--verify", ref],
+        cwd=project_dir, capture_output=True, text=True, check=True,
+    )
+    tmpdir = tempfile.mkdtemp(prefix="archview_diff_")
+    try:
+        subprocess.run(
+            ["git", "worktree", "add", "--detach", tmpdir, ref],
+            cwd=project_dir, capture_output=True, text=True, check=True,
+        )
+        return generate_graph_json(Path(tmpdir), ignore_file)
+    finally:
+        subprocess.run(
+            ["git", "worktree", "remove", "--force", tmpdir],
+            cwd=project_dir, capture_output=True, text=True,
+        )
+        shutil.rmtree(tmpdir, ignore_errors=True)
+
+
+def _element_fingerprint(el: dict) -> str:
+    d = el["data"]
+    if "source" in d:
+        return f"{d.get('source')}|{d.get('target')}|{d.get('label', '')}"
+    return (f"{d.get('type', '')}|{d.get('symbols', '')}"
+            f"|{d.get('docstring', '')}")
+
+
+def _compute_diff(current: list[dict], old: list[dict], ref: str) -> dict:
+    def index(elements):
+        nodes, edges = {}, {}
+        for el in elements:
+            eid = el["data"]["id"]
+            if "source" in el["data"]:
+                edges[eid] = el
+            else:
+                nodes[eid] = el
+        return nodes, edges
+
+    cur_nodes, cur_edges = index(current)
+    old_nodes, old_edges = index(old)
+
+    added_nodes = sorted(set(cur_nodes) - set(old_nodes))
+    removed_nodes = sorted(set(old_nodes) - set(cur_nodes))
+    added_edges = sorted(set(cur_edges) - set(old_edges))
+    removed_edges = sorted(set(old_edges) - set(cur_edges))
+
+    modified_nodes = []
+    for nid in sorted(set(cur_nodes) & set(old_nodes)):
+        if _element_fingerprint(cur_nodes[nid]) != \
+           _element_fingerprint(old_nodes[nid]):
+            modified_nodes.append(nid)
+
+    removed_elements = []
+    for nid in removed_nodes:
+        el = old_nodes[nid]
+        if not el["data"].get("is_folder"):
+            removed_elements.append(el)
+    for eid in removed_edges:
+        removed_elements.append(old_edges[eid])
+
+    return {
+        "ref": ref,
+        "added_nodes": added_nodes,
+        "removed_nodes": removed_nodes,
+        "modified_nodes": modified_nodes,
+        "added_edges": added_edges,
+        "removed_edges": removed_edges,
+        "removed_elements": removed_elements,
+    }