vibesequence 0.1.0__tar.gz

vibesequence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gery Wibowo
+
+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.

vibesequence-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: vibesequence
+Version: 0.1.0
+Summary: Turn a codebase into zoomable user sequence diagrams, for you and your AI assistant
+Author: Gery Wibowo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/monkeymars/vibesequence
+Project-URL: Documentation, https://github.com/monkeymars/vibesequence/blob/main/docs/how-it-works.md
+Project-URL: Issues, https://github.com/monkeymars/vibesequence/issues
+Keywords: sequence-diagram,code-visualization,mermaid,static-analysis,ai-assistant
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: ts
+Requires-Dist: tree-sitter>=0.23; extra == "ts"
+Requires-Dist: tree-sitter-typescript>=0.23; extra == "ts"
+Dynamic: license-file
+
+# vibesequence
+
+Turn your codebase into **zoomable sequence diagrams** that show *when a user does X, who calls whom,
+and in what order*. Use them as a map while you build, review or learn the code, on your own or with an
+AI assistant.
+
+Inspired by [graphify](https://github.com/Graphify-Labs/graphify), which turns a codebase into a knowledge
+graph so an AI assistant can navigate it without re-reading every file. vibesequence takes the same idea
+and adds what a graph leaves out: the **order** of calls and the branches around them (`if`, loops, error
+handling), drawn as user sequence diagrams that you and the assistant can both read.
+
+![vibesequence demo](https://raw.githubusercontent.com/monkeymars/vibesequence/main/demo/vibesequence-demo.gif)
+
+## Why
+
+When an AI assistant edits your code, it is hard to see what actually changed in the behavior.
+vibesequence reads your code (no running it), finds the entry points (HTTP routes, CLI commands, handlers),
+and draws each one as a sequence diagram:
+
+- **Zoom** between package, module, class and function level. Click a blue call to open it on its own.
+- **Play** a flow arrow by arrow, with the `file:line` of each step.
+- **Live**: while the AI edits, changed steps turn green and you can play only the changes.
+- **AI friendly**: the same flow is available as compact text, so your assistant reads one diagram instead of eight files.
+
+Supports Python (stdlib only) and TypeScript / JavaScript (Next.js, Express).
+
+## Does it save tokens?
+
+We benchmarked Claude Code on the same tasks with and without vibesequence. Every run passed in both setups.
+
+| task type | input tokens | cost | turns |
+|---|---|---|---|
+| understanding a flow ("what happens when…", "what breaks if I change…") | **−23%** | **−18%** | 8 → 4 |
+| small edits | +19% | +15% | 5.5 → 6 |
+
+Impact questions save the most: one `vibesequence callers` call replaced 6–7 greps and reads (−53% tokens).
+For edits, the agent still has to read the files it changes, so on the tiny example projects the map is
+extra overhead. Full method, per-task results and caveats: [docs/benchmark](https://github.com/monkeymars/vibesequence/blob/main/docs/benchmark/README.md).
+
+## Quick start
+
+```bash
+pip install vibesequence            # Python projects
+pip install "vibesequence[ts]"      # + TypeScript / JavaScript
+
+vibesequence build .                # parse the repo into vibesequence-out/
+vibesequence serve                  # open the viewer at http://127.0.0.1:8765
+```
+
+Try it on the bundled examples: clone this repo and run `vibesequence build examples`.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `vibesequence build .` | parse the repo into `vibesequence-out/` (incremental) |
+| `vibesequence serve` | live viewer; source links open your editor |
+| `vibesequence list` | list all flows |
+| `vibesequence show "POST /orders"` | one flow as Mermaid (`--format text` for the AI-friendly tree) |
+| `vibesequence callers OrderRepo.create` | who calls this, and which flows are affected |
+| `vibesequence diff` | which flows changed in the last build |
+| `vibesequence install` | add instructions to `CLAUDE.md` + a Claude Code hook that shows changed flows after each edit |
+
+## Viewer shortcuts
+
+`Space` play · `←` `→` step · `[` `]` level · `Z` zen · `D` dark mode · `\` sidebar · `⌘`+scroll zoom · drag to pan
+
+## Roadmap
+
+- [ ] **Go**: tree-sitter extractor, entry points for `net/http`, Gin, Echo, Chi and Cobra commands
+- [ ] **Java**: Spring controllers
+- [ ] **Smarter resolution**: return-type inference, dependency injection, interface → implementations
+- [ ] **Diff against a git ref**: review a PR as sequence changes, not line changes
+- [ ] **MCP server**: let the assistant call `list_flows` / `show_flow` instead of reading files
+- [ ] **Runtime traces** (optional): mark the paths that actually ran
+
+## Contributing
+
+Open for contributions! Pick a roadmap item, fix a bug, or improve the docs. Issues and pull requests are welcome.
+
+- **New language**: add one extractor class in `vibesequence/extractors/` that outputs `ModuleFacts`
+  (see `extractors/base.py`). The resolver, viewer and CLI work without changes.
+- **Set up**: clone the repo and run `pip install -e ".[ts]"`.
+- **Run the tests** before opening a PR: `python tests/test_flow.py`
+- Not sure where to start? Open an issue and say what you want to build.
+
+## Learn more
+
+How the engine turns code into sequence diagrams (extract → resolve → expand → project → render), plus
+live mode, editor links and the AI hook: [docs/how-it-works.md](https://github.com/monkeymars/vibesequence/blob/main/docs/how-it-works.md).

vibesequence-0.1.0/README.md

@@ -0,0 +1,90 @@
+# vibesequence
+
+Turn your codebase into **zoomable sequence diagrams** that show *when a user does X, who calls whom,
+and in what order*. Use them as a map while you build, review or learn the code, on your own or with an
+AI assistant.
+
+Inspired by [graphify](https://github.com/Graphify-Labs/graphify), which turns a codebase into a knowledge
+graph so an AI assistant can navigate it without re-reading every file. vibesequence takes the same idea
+and adds what a graph leaves out: the **order** of calls and the branches around them (`if`, loops, error
+handling), drawn as user sequence diagrams that you and the assistant can both read.
+
+![vibesequence demo](https://raw.githubusercontent.com/monkeymars/vibesequence/main/demo/vibesequence-demo.gif)
+
+## Why
+
+When an AI assistant edits your code, it is hard to see what actually changed in the behavior.
+vibesequence reads your code (no running it), finds the entry points (HTTP routes, CLI commands, handlers),
+and draws each one as a sequence diagram:
+
+- **Zoom** between package, module, class and function level. Click a blue call to open it on its own.
+- **Play** a flow arrow by arrow, with the `file:line` of each step.
+- **Live**: while the AI edits, changed steps turn green and you can play only the changes.
+- **AI friendly**: the same flow is available as compact text, so your assistant reads one diagram instead of eight files.
+
+Supports Python (stdlib only) and TypeScript / JavaScript (Next.js, Express).
+
+## Does it save tokens?
+
+We benchmarked Claude Code on the same tasks with and without vibesequence. Every run passed in both setups.
+
+| task type | input tokens | cost | turns |
+|---|---|---|---|
+| understanding a flow ("what happens when…", "what breaks if I change…") | **−23%** | **−18%** | 8 → 4 |
+| small edits | +19% | +15% | 5.5 → 6 |
+
+Impact questions save the most: one `vibesequence callers` call replaced 6–7 greps and reads (−53% tokens).
+For edits, the agent still has to read the files it changes, so on the tiny example projects the map is
+extra overhead. Full method, per-task results and caveats: [docs/benchmark](https://github.com/monkeymars/vibesequence/blob/main/docs/benchmark/README.md).
+
+## Quick start
+
+```bash
+pip install vibesequence            # Python projects
+pip install "vibesequence[ts]"      # + TypeScript / JavaScript
+
+vibesequence build .                # parse the repo into vibesequence-out/
+vibesequence serve                  # open the viewer at http://127.0.0.1:8765
+```
+
+Try it on the bundled examples: clone this repo and run `vibesequence build examples`.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `vibesequence build .` | parse the repo into `vibesequence-out/` (incremental) |
+| `vibesequence serve` | live viewer; source links open your editor |
+| `vibesequence list` | list all flows |
+| `vibesequence show "POST /orders"` | one flow as Mermaid (`--format text` for the AI-friendly tree) |
+| `vibesequence callers OrderRepo.create` | who calls this, and which flows are affected |
+| `vibesequence diff` | which flows changed in the last build |
+| `vibesequence install` | add instructions to `CLAUDE.md` + a Claude Code hook that shows changed flows after each edit |
+
+## Viewer shortcuts
+
+`Space` play · `←` `→` step · `[` `]` level · `Z` zen · `D` dark mode · `\` sidebar · `⌘`+scroll zoom · drag to pan
+
+## Roadmap
+
+- [ ] **Go**: tree-sitter extractor, entry points for `net/http`, Gin, Echo, Chi and Cobra commands
+- [ ] **Java**: Spring controllers
+- [ ] **Smarter resolution**: return-type inference, dependency injection, interface → implementations
+- [ ] **Diff against a git ref**: review a PR as sequence changes, not line changes
+- [ ] **MCP server**: let the assistant call `list_flows` / `show_flow` instead of reading files
+- [ ] **Runtime traces** (optional): mark the paths that actually ran
+
+## Contributing
+
+Open for contributions! Pick a roadmap item, fix a bug, or improve the docs. Issues and pull requests are welcome.
+
+- **New language**: add one extractor class in `vibesequence/extractors/` that outputs `ModuleFacts`
+  (see `extractors/base.py`). The resolver, viewer and CLI work without changes.
+- **Set up**: clone the repo and run `pip install -e ".[ts]"`.
+- **Run the tests** before opening a PR: `python tests/test_flow.py`
+- Not sure where to start? Open an issue and say what you want to build.
+
+## Learn more
+
+How the engine turns code into sequence diagrams (extract → resolve → expand → project → render), plus
+live mode, editor links and the AI hook: [docs/how-it-works.md](https://github.com/monkeymars/vibesequence/blob/main/docs/how-it-works.md).

vibesequence-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]           # 77+: SPDX `license` string (PEP 639)
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vibesequence"
+version = "0.1.0"
+description = "Turn a codebase into zoomable user sequence diagrams, for you and your AI assistant"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Gery Wibowo" }]
+requires-python = ">=3.10"
+keywords = ["sequence-diagram", "code-visualization", "mermaid", "static-analysis", "ai-assistant"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = []                       # Python projects: stdlib only
+
+[project.optional-dependencies]
+ts = ["tree-sitter>=0.23", "tree-sitter-typescript>=0.23"]   # TypeScript / JavaScript projects
+
+[project.urls]
+Homepage = "https://github.com/monkeymars/vibesequence"
+Documentation = "https://github.com/monkeymars/vibesequence/blob/main/docs/how-it-works.md"
+Issues = "https://github.com/monkeymars/vibesequence/issues"
+
+[project.scripts]
+vibesequence = "vibesequence.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["vibesequence*"]
+
+[tool.setuptools.package-data]
+"vibesequence.render" = ["viewer.html"]

vibesequence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vibesequence-0.1.0/tests/test_flow.py

@@ -0,0 +1,179 @@
+"""Smoke check: python tests/test_flow.py  (also runs under pytest)."""
+import contextlib
+import io
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from vibesequence import builder, cli  # noqa: E402
+from vibesequence.flow import expand, project  # noqa: E402
+from vibesequence.render.mermaid import render  # noqa: E402
+
+APP = textwrap.dedent('''
+    def save(x): pass
+    def notify(x): pass
+    def audit(x): pass
+
+    def handle(user, items):
+        if not user:
+            notify(user)
+        if user.admin:
+            audit(user)
+        for item in items:
+            save(item)
+
+    def main():
+        handle(None, [])
+''')
+
+
+def _run(*argv) -> str:
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        cli.main(list(argv))
+    return buf.getvalue()
+
+
+def test_flow():
+    with tempfile.TemporaryDirectory() as d:
+        root, out = Path(d, "src"), Path(d, "out")
+        root.mkdir()
+        (root / "app.py").write_text(APP)
+        graph = builder.build(root, out)
+        again = builder.build(root, out)                   # live mode relies on: same code -> same version
+        assert not again.stats["changed"] and again.stats["version"] == graph.stats["version"]
+
+        mm = render(project(graph, expand(graph, "app:handle", 3), "function"), "function")
+        assert "opt if not user" in mm, mm
+        assert "opt if user.admin" in mm, mm              # two separate ifs stay two fragments
+        assert "loop for item in items" in mm, mm
+
+        text = _run("show", "app:handle", "--out", str(out), "--format", "text", "--level", "function")
+        assert "save  app.py:2" in text, text             # definition location for the agent
+
+        callers = _run("callers", "app:save", "--out", str(out))
+        assert "app:handle  app.py:12" in callers, callers
+        assert "main()" in callers, callers                # flow that reaches it
+
+        (root / "app.py").write_text(APP.replace("        save(item)", "        save(item)\n        notify(item)"))
+        hook = _run("build", str(root), "--out", str(out), "--hook")
+        assert builder.load(out).stats["version"] != graph.stats["version"]
+        assert "+" in hook and "notify" in hook, hook
+        assert _run("build", str(root), "--out", str(out), "--hook") == ""   # no change -> silent
+
+
+def test_serve_open_guards():
+    """POST /__open must refuse other origins and files outside the project (never launches an editor)."""
+    import json
+    import threading
+    import urllib.error
+    import urllib.request
+    from http.server import ThreadingHTTPServer
+    from vibesequence import editor, serve
+
+    editor.EDITORS["missing"] = ("Missing", lambda f, n: ["vibesequence-no-such-editor", f])
+    with tempfile.TemporaryDirectory() as d:
+        root = Path(d)
+        (root / "app.py").write_text("x = 1\n")
+        srv = ThreadingHTTPServer(("127.0.0.1", 0), serve._handler(root, root.resolve(), lambda: None, "missing"))
+        threading.Thread(target=srv.serve_forever, daemon=True).start()
+        base = f"http://127.0.0.1:{srv.server_address[1]}"
+
+        def post(body, origin=base):
+            req = urllib.request.Request(base + "/__open", json.dumps(body).encode(), {"Origin": origin})
+            try:
+                return urllib.request.urlopen(req).status
+            except urllib.error.HTTPError as e:
+                return e.code
+
+        assert post({"file": "app.py", "line": 1}, "https://evil.example") == 403
+        assert post({"file": "../../etc/passwd", "line": 1}) == 403
+        assert post({"file": "app.py", "line": "x"}) == 400
+        assert post({"file": "app.py", "line": 1}) == 404                          # CLI not on PATH
+        srv.shutdown()
+
+
+def test_detect_editor():
+    from vibesequence.editor import detect
+    assert detect({"TERM_PROGRAM": "zed", "ZED_TERM": "true"})[0] == "zed"
+    assert detect({"TERM_PROGRAM": "vscode", "__CFBundleIdentifier": "com.microsoft.VSCode"})[0] == "vscode"
+    assert detect({"TERM_PROGRAM": "vscode", "__CFBundleIdentifier": "com.todesktop.230313mzl4w4u92"})[0] == "cursor"
+    assert detect({"VISUAL": "code --wait"})[0] == "vscode"
+    assert detect({"EDITOR": "vim", "TERM_PROGRAM": "vscode"})[0] == "vscode"           # terminal editors skipped
+    assert detect({"TERMINAL_EMULATOR": "JetBrains-JediTerm", "__CFBundleIdentifier": "com.jetbrains.intellij"})[0] == "idea"
+    assert detect({"VIBESEQUENCE_EDITOR": "pycharm", "TERM_PROGRAM": "zed"})[0] == "pycharm"  # explicit wins
+
+
+def test_install_keeps_user_content():
+    """install edits the user's CLAUDE.md and Claude settings: replace only our section, add the hook once."""
+    import json
+    with tempfile.TemporaryDirectory() as d:
+        md, settings = Path(d, "CLAUDE.md"), Path(d, ".claude", "settings.local.json")
+        md.write_text("# Proj\n\nKeep tests green.\n\n## vibesequence (old)\nold text\n\n## Deploy\nmake deploy\n")
+        settings.parent.mkdir()
+        settings.write_text(json.dumps({"permissions": {"allow": ["Bash(make:*)"]}}))
+        for _ in range(2):
+            with contextlib.redirect_stdout(io.StringIO()):
+                cli._install(md)
+                cli._install_hook(settings)
+        text, conf = md.read_text(), json.loads(settings.read_text())
+        assert "Keep tests green." in text and "## Deploy" in text and "old text" not in text
+        assert text.count("## vibesequence") == 1
+        assert conf["permissions"] == {"allow": ["Bash(make:*)"]}
+        assert len(conf["hooks"]["PostToolUse"]) == 1
+
+
+def test_import_root_and_ranking():
+    """Built one folder too high, imports still resolve; roots that drive more code rank first."""
+    with tempfile.TemporaryDirectory() as d:
+        pkg = Path(d, "services", "app")
+        pkg.mkdir(parents=True)
+        (pkg / "lib.py").write_text("def f(): g()\ndef g(): h()\ndef h(): pass\n")
+        (pkg / "main.py").write_text(textwrap.dedent('''
+            from app.lib import f, g, h
+
+            def run():
+                f()
+                g()
+                h()
+
+            def _cb():
+                h()
+        '''))
+        graph = builder.build(Path(d), Path(d, "out"))
+        assert graph.stats["import_roots"] == ["services"], graph.stats
+        assert "app.main:run" in graph.functions
+        assert graph.functions["app.main:run"].calls[0].resolved == "app.lib:f"
+        roots = [e.id for e in graph.entries if e.kind == "root"]
+        assert roots.index("app.main:run") < roots.index("app.main:_cb"), roots
+
+
+def test_typescript_next_and_express():
+    """examples/next_shop: Next.js route files + Express routes resolve through classes, inheritance,
+    path aliases and an imported instance. Skipped without the optional tree-sitter dependency."""
+    try:
+        import tree_sitter_typescript  # noqa: F401
+    except ImportError:
+        print("skip test_typescript_next_and_express: pip install 'vibesequence[ts]'")
+        return
+    example = Path(__file__).resolve().parents[1] / "examples" / "next_shop"
+    with tempfile.TemporaryDirectory() as d:
+        graph = builder.build(example, Path(d))
+        labels = {e.label for e in graph.entries if e.kind == "route"}
+        assert {"POST /api/orders", "GET /api/orders/[id]", "GET /api/me", "GET /orders/:id", "POST /orders/:id/cancel"} <= labels, labels
+        text = _run("show", "POST /api/orders", "--out", d, "--format", "text", "--level", "function", "--depth", "6")
+        for step in ("auth.requireUser", "OrderService.place", "BaseRepo.get", "for each in items",
+                     "PricingEngine.priceLine", "OrderRepo.markFailed", "fetch", "pool.query", "orders/route.POST"):
+            assert step in text, (step, text)
+
+
+if __name__ == "__main__":
+    test_typescript_next_and_express()
+    test_import_root_and_ranking()
+    test_flow()
+    test_serve_open_guards()
+    test_detect_editor()
+    test_install_keeps_user_content()
+    print("ok")

vibesequence-0.1.0/vibesequence/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+main()

vibesequence-0.1.0/vibesequence/builder.py

@@ -0,0 +1,179 @@
+"""Build pipeline:  files -> ModuleFacts (cached) -> resolve -> entry points -> Graph
+
+Scalability notes:
+  * Extraction is per-file and cached by content hash in vibesequence-out/cache.json.
+    A rebuild on a 2000-file repo touches only the files whose hash changed.
+  * Resolution is a cheap dictionary chain, O(total calls).
+  * Flows are NOT precomputed. The viewer / CLI expands a flow lazily from the
+    graph, so output size is O(functions + calls), not O(entries × depth).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import Counter, defaultdict
+import sys
+import time
+from dataclasses import asdict
+from pathlib import Path
+
+from .entrypoints import detect
+from .extractors.base import get_extractors
+from .model import CallSite, FunctionDef, Graph, ModuleFacts
+from .resolver import Resolver
+
+CACHE_VERSION = 2          # bump when extractor output changes, so stale facts are reparsed
+IGNORE_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build",
+               "vibesequence-out", "graphify-out", ".mypy_cache", ".pytest_cache", "site-packages",
+               ".next", ".nuxt", ".svelte-kit", ".turbo", ".vercel", "coverage", ".cache", ".strapi"}
+TS_EXTS = {".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"}
+
+
+def _hash(p: Path) -> str:
+    return hashlib.sha1(p.read_bytes()).hexdigest()
+
+
+def _facts_from_cache(d: dict) -> ModuleFacts:
+    fns = []
+    for f in d["functions"]:
+        f = dict(f)
+        f["calls"] = [CallSite(**c) for c in f["calls"]]
+        fns.append(FunctionDef(**f))
+    return ModuleFacts(module=d["module"], file=d["file"], functions=fns,
+                       imports=d["imports"], instance_hints=d["instance_hints"],
+                       bases=d.get("bases", {}), globals=d.get("globals", []), aliases=d.get("aliases", {}))
+
+
+def build(root: Path, out_dir: Path, use_cache: bool = True) -> Graph:
+    t0 = time.time()
+    root = root.resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    cache_path = out_dir / "cache.json"
+    cache: dict = json.loads(cache_path.read_text()) if (use_cache and cache_path.exists()) else {}
+    if cache.get("__version__") != CACHE_VERSION:
+        cache = {}
+    extractors = get_extractors()
+
+    modules: list[ModuleFacts] = []
+    new_cache: dict = {"__version__": CACHE_VERSION}
+    files_seen = files_parsed = ts_skipped = 0
+    for p in sorted(root.rglob("*")):
+        if not p.is_file() or p.name.endswith(".d.ts"):
+            continue
+        if p.suffix not in extractors:
+            ts_skipped += p.suffix in TS_EXTS and not any(part in IGNORE_DIRS for part in p.relative_to(root).parts)
+            continue
+        if any(part in IGNORE_DIRS for part in p.relative_to(root).parts):
+            continue
+        files_seen += 1
+        rel = str(p.relative_to(root))
+        h = _hash(p)
+        if rel in cache and cache[rel]["hash"] == h:
+            facts = _facts_from_cache(cache[rel]["facts"])
+        else:
+            try:
+                facts = extractors[p.suffix].extract(p, root)
+            except SyntaxError as e:
+                print(f"  skip {rel}: {e.msg} (line {e.lineno})", file=sys.stderr)
+                continue
+            files_parsed += 1
+        for fn in facts.functions:            # reset resolution; it depends on other files
+            for c in fn.calls:
+                c.resolved = None
+        modules.append(facts)
+        new_cache[rel] = {"hash": h, "facts": asdict(facts)}
+
+    import_roots, import_warning = _apply_import_roots(modules)
+    resolver = Resolver(modules)
+    res_stats = resolver.resolve_all()
+    entries = detect(resolver.functions)
+
+    stats = {
+        "root": str(root), "files": files_seen, "files_reparsed": files_parsed,
+        "functions": len(resolver.functions), "entries": len(entries),
+        **res_stats, "seconds": round(time.time() - t0, 3),
+        "import_roots": import_roots, "import_warning": import_warning or (
+            f"{ts_skipped} TypeScript/JavaScript files skipped: pip install 'vibesequence[ts]'" if ts_skipped else ""),
+    }
+    graph = Graph(functions=resolver.functions, entries=entries, stats=stats)
+    cache_path.write_text(json.dumps(new_cache))
+    graph_path = out_dir / "graph.json"
+    shape = _shape(graph.to_json())
+    old = _shape(json.loads(graph_path.read_text())) if graph_path.exists() else None
+    # version: changes only when functions/calls/entries change (not timings), so a live viewer
+    # and `serve` can tell "the flows changed" from "someone ran build again"
+    stats["version"] = hashlib.sha1(json.dumps(shape, sort_keys=True).encode()).hexdigest()[:12]
+    stats["changed"] = shape != old
+    # keep the graph from before the last CHANGE (not the last build) for `vibesequence diff`;
+    # a no-op rebuild must not overwrite it
+    if old is not None and stats["changed"]:
+        graph_path.replace(out_dir / "graph.prev.json")
+    graph_path.write_text(json.dumps(graph.to_json(), indent=1))
+    return graph
+
+
+def _apply_import_roots(modules: list[ModuleFacts]) -> tuple[list[str], str]:
+    """Built one level too high (monorepo, `vibesequence build .` above the project)? Then imports say
+    `app.repos.base` while the file's module is `services.app.repos.base`, and nothing resolves.
+    Find such prefixes (>= 3 imports match one folder unambiguously) and strip them from module
+    names, as if vibesequence had been run inside that folder. Skipped, with a warning, when stripping
+    would collide with an existing module or the match is ambiguous."""
+    known = {m.module for m in modules}
+    prefixes_of: dict[str, set[str]] = defaultdict(set)     # "app.repos.base" -> {"services"}
+    for name in known:
+        parts = name.split(".")
+        for i in range(1, len(parts)):
+            prefixes_of[".".join(parts[i:])].add(".".join(parts[:i]))
+    hits: Counter[str] = Counter()
+    ambiguous: Counter[str] = Counter()
+    for m in modules:
+        for target in m.imports.values():
+            candidates = [t for t in (target, target.rpartition(".")[0]) if t]
+            if any(t in known for t in candidates):
+                continue
+            for t in candidates:
+                if len(prefixes_of.get(t, ())) == 1:
+                    hits[next(iter(prefixes_of[t]))] += 1
+                    break
+                if prefixes_of.get(t):
+                    ambiguous[" / ".join(sorted(prefixes_of[t]))] += 1
+                    break
+    applied, warning = [], ""
+    for prefix, n in hits.most_common():
+        if n < 3:
+            break
+        dot = prefix + "."
+        renamed = {m.module: m.module[len(dot):] for m in modules if m.module.startswith(dot)}
+        if set(renamed.values()) & (known - set(renamed)) or len(set(renamed.values())) < len(renamed):
+            warning = f"imports match {prefix.replace('.', '/')}/ but stripping it collides with other modules: build that folder"
+            continue
+        cut = lambda s: s[len(dot):] if s.startswith(dot) else s   # noqa: E731
+        for m in modules:
+            m.module = cut(m.module)
+            m.imports = {k: cut(v) for k, v in m.imports.items()}
+            for fn in m.functions:
+                fn.module = cut(fn.module)
+                fn.id = f"{fn.module}:{fn.id.partition(':')[2]}"
+        known = {m.module for m in modules}
+        applied.append(prefix.replace(".", "/"))
+    if not applied and sum(ambiguous.values()) >= 3:
+        where = ambiguous.most_common(1)[0][0].replace(".", "/")
+        warning = f"imports match several folders ({where}): build one project at a time"
+    return applied, warning
+
+
+def _shape(d: dict) -> tuple:
+    # ponytail: line shifts count as a change, so a comment-only edit rotates graph.prev.json and
+    # `vibesequence diff` then says "no flow changes"; compare line-free shapes if that bites
+    return d["functions"], d["entries"]          # everything but stats (timings)
+
+
+def load(out_dir: Path, name: str = "graph.json") -> Graph:
+    d = json.loads((out_dir / name).read_text())
+    fns = {}
+    for k, f in d["functions"].items():
+        f = dict(f)
+        f["calls"] = [CallSite(**c) for c in f["calls"]]
+        fns[k] = FunctionDef(**f)
+    from .model import EntryPoint
+    return Graph(functions=fns, entries=[EntryPoint(**e) for e in d["entries"]], stats=d["stats"])