feat(export): add zoom-html, a three-level architecture view

ARCHITECTURE.md

@@ -25,6 +25,7 @@ Signatures below are the real ones - `tests/test_architecture_doc.py` imports ev
 | `export.py` | `to_json`, `to_html`, `to_obsidian`, `to_svg`, `to_graphml`, `to_canvas`, `to_cypher` | graph → graph.json, graph.html, Obsidian vault, graph.svg, … one function per format |
 | `wiki.py` | `to_wiki(G, communities, output_dir, ...)` | graph → one markdown article per community + `index.md` |
 | `callflow_html.py` | `write_callflow_html(...)` | graphify-out files → Mermaid architecture/call-flow HTML |
+| `zoom_html.py` | `build_zoom_data(graph, project="")`, `write_zoom_html(graph_path, output_path, *, project_label=None)` | graph.json → one offline HTML page with three zoom levels: domains, a domain's classes by layer, a class's methods and call sites |
 | `ingest.py` | `ingest(url, target_dir, ...)` | URL → file saved to corpus dir |
 | `cache.py` | `check_semantic_cache(files, root)`, `save_semantic_cache(nodes, edges, ...)` | files → cached nodes / edges / hyperedges + the list of files still needing extraction |
 | `security.py` | `validate_url`, `safe_fetch`, `validate_graph_path`, `sanitize_label` | URL / path / label → validated value, or raises |

README.md

@@ -346,6 +346,7 @@ graphify parses ~40 programming languages locally with tree-sitter AST, and maps
 /graphify . --no-viz               # skip the HTML, just the report + JSON
 /graphify . --wiki                 # build a markdown wiki from the graph
 graphify export callflow-html      # Mermaid architecture/call-flow HTML (auto-regenerates on every git commit if hook is installed)
+graphify export zoom-html          # offline architecture view: domains, then one domain's classes by layer, then one class
 
 /graphify query "what connects auth to the database?"
 /graphify path "UserService" "DatabasePool"

graphify/__main__.py

@@ -989,6 +989,8 @@ def _run_cli() -> None:
         print("  export callflow-html    emit Mermaid-based architecture/call-flow HTML")
         print("                          [GRAPH|DIR] [--graph PATH] [--labels PATH] [--report PATH] [--sections PATH] [--output HTML]")
         print("                          [--lang auto|zh-CN|en] [--max-sections N] [--diagram-scale N]")
+        print("  export zoom-html        emit an offline three-level architecture view (domains, layers, class)")
+        print("                          [--graph PATH] [--output HTML] [--label NAME]")
         print("  export obsidian         emit Obsidian vault notes + canvas [--graph PATH] [--labels PATH] [--dir PATH]")
         print("  export wiki             emit wiki markdown articles [--graph PATH] [--labels PATH]")
         print("  export svg              emit graph.svg [--graph PATH] [--labels PATH]")

graphify/cli.py

@@ -2974,11 +2974,12 @@ def _to_simple(g: "_nx.Graph") -> "_nx.Graph":
 
     elif cmd == "export":
         subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
-        if subcmd not in ("html", "callflow-html", "obsidian", "wiki", "svg", "graphml", "neo4j", "falkordb"):
+        if subcmd not in ("html", "callflow-html", "zoom-html", "obsidian", "wiki", "svg", "graphml", "neo4j", "falkordb"):
             print("Usage: graphify export <format>", file=sys.stderr)
             print("  html      [--graph PATH] [--labels PATH] [--node-limit N] [--no-viz]", file=sys.stderr)
             print("  callflow-html [GRAPH|DIR] [--graph PATH] [--labels PATH] [--report PATH] [--sections PATH] [--output HTML]", file=sys.stderr)
             print("            [--lang auto|zh-CN|en] [--max-sections N] [--diagram-scale N]", file=sys.stderr)
+            print("  zoom-html [--graph PATH] [--output HTML] [--label NAME]", file=sys.stderr)
             print("  obsidian  [--graph PATH] [--labels PATH] [--dir PATH]", file=sys.stderr)
             print("  wiki      [--graph PATH] [--labels PATH]", file=sys.stderr)
             print("  svg       [--graph PATH] [--labels PATH]", file=sys.stderr)
@@ -3004,6 +3005,7 @@ def _to_simple(g: "_nx.Graph") -> "_nx.Graph":
         callflow_diagram_scale = 1.0
         callflow_max_diagram_nodes = 18
         callflow_max_diagram_edges = 24
+        zoom_label: str | None = None
         analysis_path = Path(_GRAPHIFY_OUT) / ".graphify_analysis.json"
         node_limit = 5000
         no_viz = False
@@ -3063,6 +3065,8 @@ def _to_simple(g: "_nx.Graph") -> "_nx.Graph":
                 print("  --max-diagram-nodes N  representative nodes per section (default 18)")
                 print("  --max-diagram-edges N  representative edges per section (default 24)")
                 sys.exit(0)
+            elif a == "--label" and i + 1 < len(args) and subcmd == "zoom-html":
+                zoom_label = args[i + 1]; i += 2
             elif a == "--node-limit" and i + 1 < len(args):
                 node_limit = int(args[i + 1]); i += 2
             elif a == "--no-viz":
@@ -3120,6 +3124,20 @@ def _to_simple(g: "_nx.Graph") -> "_nx.Graph":
             print(f"callflow HTML written - open in any browser: {out}")
             sys.exit(0)
 
+        if subcmd == "zoom-html":
+            from graphify.zoom_html import write_zoom_html as _write_zoom_html
+            try:
+                out = _write_zoom_html(
+                    graph_path,
+                    callflow_output or graph_path.parent / "GRAPH_ZOOM.html",
+                    project_label=zoom_label,
+                )
+            except ValueError as exc:
+                print(f"error: {exc}", file=sys.stderr)
+                sys.exit(1)
+            print(f"zoom HTML written - open in any browser: {out}")
+            sys.exit(0)
+
         from networkx.readwrite import json_graph as _jg
         from graphify.build import build_from_json as _bfj
         from graphify.security import check_graph_file_size_cap as _check_cap