readmenator 1.3.2__tar.gz → 1.3.3__tar.gz

{readmenator-1.3.2 → readmenator-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readmenator
-Version: 1.3.2
+Version: 1.3.3
 Summary: Zero-token polyglot codebase knowledge graph generator
 Project-URL: Homepage, https://github.com/grisuno/ReadMenator
 Project-URL: Repository, https://github.com/grisuno/ReadMenator
@@ -95,6 +95,7 @@ python -m readmenator /path/to/project --svg                       # graph.svg (
 python -m readmenator /path/to/project --graphml                   # graph.graphml (Gephi/yEd)
 python -m readmenator /path/to/project obsidian                    # Obsidian vault (wikilinks)
 python -m readmenator /path/to/project wiki                       # Agent wiki (index + community pages)
+python -m readmenator /path/to/project components                # Component diagrams (analysis.json + graph LR markdown + index.html)
 python -m readmenator /path/to/project lint-wiki                  # Wiki health check
 python -m readmenator /path/to/project lint                        # Architecture violations (exit 1 on errors)
 python -m readmenator /path/to/project strip-dead-code             # Orphaned symbol report
@@ -203,6 +204,49 @@ external in a 2D map or a 3D space:
   `#path=<a>~<b>`, `#lens=cycles`, `#edge=<key>`. The page also exposes
   `window.ReadmenatorExplorer` for console scripting.
 
+The **Edge Bundle Explorer** (`readmenator-maps/graph-bundle.html`, its own gallery
+card next to the force graph, `readmenator . bundles` to export it alone) is the
+hierarchical edge bundling view from the video, live. It needs no network: one
+canvas, no CDN.
+
+- **Circle (2D).** Files sit on a ring grouped into community arcs (hubs first);
+  every resolved import is a B-spline routed through the community tree, so thick
+  bundles are the real seams between subsystems.
+- **Sphere (3D).** The same hierarchy on a globe: each community owns a contiguous
+  cap sized by its file count, wires dive through the core between caps. Drag to
+  rotate, wheel to zoom, optional auto-rotate; selecting a file or community flies
+  the camera to face it.
+- **Reading it.** Hover a file: cyan wires are what it imports, pink what imports it.
+  Click to pin it (imports and importers listed, one click to open it in the force
+  graph in 2D or 3D). Click an arc, cap label or legend row to focus a community
+  (inside/out/in counts, cohesion, top flows to other communities).
+- **Controls.** Beta slider (0 straight chords, 1 fully bundled, recomputed live),
+  crossing-only filter, direction (both, imports, imported by), color by community,
+  layer or language, search, PNG export, light/dark theme. Deep links:
+  `#view=3d&node=<id>&group=<key>&beta=0.7&color=layer&dir=out&cross=1`; console API
+  `window.ReadmenatorBundles`.
+
+### Component Diagrams
+
+`readmenator-diagrams/` holds a component architecture map built with zero
+tokens: `analysis.json` (components with key entities and file/line spans,
+relations with method-level call evidence), `overview.md` with the `graph LR`
+diagram, one page per expandable component, and `index.html` — the diagram
+drawn as an offline interactive page in the readmenator dark theme (layered
+left-to-right boxes enriched with key symbols, layer colors and PageRank hubs,
+labeled arrows weighted by call/import evidence, hover descriptions,
+click-to-component, pan/zoom, PNG export). The maps gallery links it with a
+**Component Diagrams** card that opens a self-contained copy living inside the
+maps directory itself, so the link never leaves the site (safe on GitHub Pages
+project subpaths, where `../..` hrefs would escape the project). The docs site
+ships the markdown in its reader. No external service needed: structure and
+call evidence are pure static analysis; a local Ollama daemon only ever
+enriches prose descriptions, and only when `OLLAMA_ENABLED` is set.
+
+```bash
+python -m readmenator /path/to/project components  # rebuild only the diagrams
+```
+
 Serve the `docs/` directory directly with GitHub Pages (Settings -> Pages ->
 Deploy from branch -> folder `docs/`). The gallery `index.html` links every map
 with relative paths, works fully offline, and needs no build step.
@@ -213,13 +257,20 @@ gallery, every `--rebuild` refreshes it (video and docs included).
 
 ### Overview Video
 
-`readmenator . video` renders a synthwave mp4 from real scan data in seven acts:
+`readmenator . video` renders a synthwave mp4 from real scan data in nine acts:
 layers, god nodes, blast-radius tree, communities, **Emergence** (ForceAtlas2
 LinLog with adaptive speed, animated from seeded chaos to convergence, nodes
-sized by PageRank with random-surfer particles on the hottest edges), **The Wiring**
-(Holten hierarchical edge bundling: files on a circle by community, imports routed
-as B-splines through the community tree, a spotlight sweeping each community and a
-live flow ranking), and code DNA.
+sized by PageRank with random-surfer particles on the hottest edges), **Orbit**
+(the force graph laid out by ForceAtlas2 in 3D and flown by a camera: color by
+community, layer and language in turn, a tour that zooms into the largest
+communities with their cohesion and seams, then the 1-hop reach of the top hub),
+**The Wiring** (Holten hierarchical edge bundling: files on a circle by community,
+imports routed as B-splines through the community tree, a spotlight sweeping each
+community and a live flow ranking), **The Sphere** (the 3D layout folds onto a globe
+of community caps and every import bundles through its core), and code DNA. A
+closing invitation shows both explorers spinning with their paths, so viewers know
+where to go next. Set an act's duration (`VIDEO_ORBIT_S`, `VIDEO_SPHERE_S`,
+`VIDEO_INVITE_S`, ...) to 0 to drop it with its card.
 
 ### GraphRAG for agents (zero tokens to build, cheap to query)
 
@@ -331,9 +382,15 @@ Supported target languages (12): C++, Java, C#, Python, Go, Rust, PHP, Kotlin, S
 | Watcher | `_watcher.py` | Filesystem polling watcher for auto-rebuild |
 | README Injector | `_readme_injector.py` | Auto-injects KB link into project README |
 | GraphRAG | `_graphrag.py` | Entities, relationships, text units, community report hierarchy, local/global search |
-| Graph layouts | `_graphlayout.py` | ForceAtlas2 snapshots and hierarchical edge bundling |
+| Graph layouts | `_graphlayout.py` | ForceAtlas2 (2D/3D) snapshots, circular and spherical hierarchical edge bundling |
+| Edge bundles | `_bundlegraph.py` | Circle + sphere bundle payload, settings, thumbnail |
+| Bundle page | `_bundlegraph_page.py` | Self-contained canvas page: 2D circle, 3D sphere, live beta, focus panels |
 | Force graph | `_forcegraph.py` | Heterogeneous explorer payload, settings, thumbnail |
 | Explorer page | `_forcegraph_page.py` | 2D/3D explorer HTML: hit-testing, overlay glyphs, node and edge actions |
+| Source viewer | `_sourceview.py` | Bounded per-file source texts for the explorer View drawer |
+| Symbol index | `_symindex.py` | Definition spans, call sites with lines, BUILTIN/SAME_FILE/IMPORTED/UNIQUE/AMBIGUOUS/UNRESOLVED resolver |
+| Component diagrams | `_components.py` | analysis.json, graph LR markdown, offline interactive index.html, gallery card |
+| Local Ollama | `_ollama.py` | Optional localhost LLM client for prose only (bounded, never fatal) |
 | Memory | `_memory.py` | MEMORY.md: declared rules, measured baselines, preserved session log |
 | Skills | `_skill_installer.py` | Installs packaged agent skills from `_skills/` |
 | Application | `_app.py` | Application orchestrator |

{readmenator-1.3.2 → readmenator-1.3.3}/README.md

@@ -71,6 +71,7 @@ python -m readmenator /path/to/project --svg                       # graph.svg (
 python -m readmenator /path/to/project --graphml                   # graph.graphml (Gephi/yEd)
 python -m readmenator /path/to/project obsidian                    # Obsidian vault (wikilinks)
 python -m readmenator /path/to/project wiki                       # Agent wiki (index + community pages)
+python -m readmenator /path/to/project components                # Component diagrams (analysis.json + graph LR markdown + index.html)
 python -m readmenator /path/to/project lint-wiki                  # Wiki health check
 python -m readmenator /path/to/project lint                        # Architecture violations (exit 1 on errors)
 python -m readmenator /path/to/project strip-dead-code             # Orphaned symbol report
@@ -179,6 +180,49 @@ external in a 2D map or a 3D space:
   `#path=<a>~<b>`, `#lens=cycles`, `#edge=<key>`. The page also exposes
   `window.ReadmenatorExplorer` for console scripting.
 
+The **Edge Bundle Explorer** (`readmenator-maps/graph-bundle.html`, its own gallery
+card next to the force graph, `readmenator . bundles` to export it alone) is the
+hierarchical edge bundling view from the video, live. It needs no network: one
+canvas, no CDN.
+
+- **Circle (2D).** Files sit on a ring grouped into community arcs (hubs first);
+  every resolved import is a B-spline routed through the community tree, so thick
+  bundles are the real seams between subsystems.
+- **Sphere (3D).** The same hierarchy on a globe: each community owns a contiguous
+  cap sized by its file count, wires dive through the core between caps. Drag to
+  rotate, wheel to zoom, optional auto-rotate; selecting a file or community flies
+  the camera to face it.
+- **Reading it.** Hover a file: cyan wires are what it imports, pink what imports it.
+  Click to pin it (imports and importers listed, one click to open it in the force
+  graph in 2D or 3D). Click an arc, cap label or legend row to focus a community
+  (inside/out/in counts, cohesion, top flows to other communities).
+- **Controls.** Beta slider (0 straight chords, 1 fully bundled, recomputed live),
+  crossing-only filter, direction (both, imports, imported by), color by community,
+  layer or language, search, PNG export, light/dark theme. Deep links:
+  `#view=3d&node=<id>&group=<key>&beta=0.7&color=layer&dir=out&cross=1`; console API
+  `window.ReadmenatorBundles`.
+
+### Component Diagrams
+
+`readmenator-diagrams/` holds a component architecture map built with zero
+tokens: `analysis.json` (components with key entities and file/line spans,
+relations with method-level call evidence), `overview.md` with the `graph LR`
+diagram, one page per expandable component, and `index.html` — the diagram
+drawn as an offline interactive page in the readmenator dark theme (layered
+left-to-right boxes enriched with key symbols, layer colors and PageRank hubs,
+labeled arrows weighted by call/import evidence, hover descriptions,
+click-to-component, pan/zoom, PNG export). The maps gallery links it with a
+**Component Diagrams** card that opens a self-contained copy living inside the
+maps directory itself, so the link never leaves the site (safe on GitHub Pages
+project subpaths, where `../..` hrefs would escape the project). The docs site
+ships the markdown in its reader. No external service needed: structure and
+call evidence are pure static analysis; a local Ollama daemon only ever
+enriches prose descriptions, and only when `OLLAMA_ENABLED` is set.
+
+```bash
+python -m readmenator /path/to/project components  # rebuild only the diagrams
+```
+
 Serve the `docs/` directory directly with GitHub Pages (Settings -> Pages ->
 Deploy from branch -> folder `docs/`). The gallery `index.html` links every map
 with relative paths, works fully offline, and needs no build step.
@@ -189,13 +233,20 @@ gallery, every `--rebuild` refreshes it (video and docs included).
 
 ### Overview Video
 
-`readmenator . video` renders a synthwave mp4 from real scan data in seven acts:
+`readmenator . video` renders a synthwave mp4 from real scan data in nine acts:
 layers, god nodes, blast-radius tree, communities, **Emergence** (ForceAtlas2
 LinLog with adaptive speed, animated from seeded chaos to convergence, nodes
-sized by PageRank with random-surfer particles on the hottest edges), **The Wiring**
-(Holten hierarchical edge bundling: files on a circle by community, imports routed
-as B-splines through the community tree, a spotlight sweeping each community and a
-live flow ranking), and code DNA.
+sized by PageRank with random-surfer particles on the hottest edges), **Orbit**
+(the force graph laid out by ForceAtlas2 in 3D and flown by a camera: color by
+community, layer and language in turn, a tour that zooms into the largest
+communities with their cohesion and seams, then the 1-hop reach of the top hub),
+**The Wiring** (Holten hierarchical edge bundling: files on a circle by community,
+imports routed as B-splines through the community tree, a spotlight sweeping each
+community and a live flow ranking), **The Sphere** (the 3D layout folds onto a globe
+of community caps and every import bundles through its core), and code DNA. A
+closing invitation shows both explorers spinning with their paths, so viewers know
+where to go next. Set an act's duration (`VIDEO_ORBIT_S`, `VIDEO_SPHERE_S`,
+`VIDEO_INVITE_S`, ...) to 0 to drop it with its card.
 
 ### GraphRAG for agents (zero tokens to build, cheap to query)
 
@@ -307,9 +358,15 @@ Supported target languages (12): C++, Java, C#, Python, Go, Rust, PHP, Kotlin, S
 | Watcher | `_watcher.py` | Filesystem polling watcher for auto-rebuild |
 | README Injector | `_readme_injector.py` | Auto-injects KB link into project README |
 | GraphRAG | `_graphrag.py` | Entities, relationships, text units, community report hierarchy, local/global search |
-| Graph layouts | `_graphlayout.py` | ForceAtlas2 snapshots and hierarchical edge bundling |
+| Graph layouts | `_graphlayout.py` | ForceAtlas2 (2D/3D) snapshots, circular and spherical hierarchical edge bundling |
+| Edge bundles | `_bundlegraph.py` | Circle + sphere bundle payload, settings, thumbnail |
+| Bundle page | `_bundlegraph_page.py` | Self-contained canvas page: 2D circle, 3D sphere, live beta, focus panels |
 | Force graph | `_forcegraph.py` | Heterogeneous explorer payload, settings, thumbnail |
 | Explorer page | `_forcegraph_page.py` | 2D/3D explorer HTML: hit-testing, overlay glyphs, node and edge actions |
+| Source viewer | `_sourceview.py` | Bounded per-file source texts for the explorer View drawer |
+| Symbol index | `_symindex.py` | Definition spans, call sites with lines, BUILTIN/SAME_FILE/IMPORTED/UNIQUE/AMBIGUOUS/UNRESOLVED resolver |
+| Component diagrams | `_components.py` | analysis.json, graph LR markdown, offline interactive index.html, gallery card |
+| Local Ollama | `_ollama.py` | Optional localhost LLM client for prose only (bounded, never fatal) |
 | Memory | `_memory.py` | MEMORY.md: declared rules, measured baselines, preserved session log |
 | Skills | `_skill_installer.py` | Installs packaged agent skills from `_skills/` |
 | Application | `_app.py` | Application orchestrator |

{readmenator-1.3.2 → readmenator-1.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "readmenator"
-version = "1.3.2"
+version = "1.3.3"
 description = "Zero-token polyglot codebase knowledge graph generator"
 readme = "README.md"
 requires-python = ">=3.10"

{readmenator-1.3.2 → readmenator-1.3.3}/readmenator/__init__.py

@@ -29,6 +29,9 @@ from readmenator._diagrams import (  # noqa: F401
     VisNetworkRenderer,
 )
 from readmenator._mcp_server import MCPServer  # noqa: F401
+from readmenator._components import ComponentDiagramBuilder, sanitize  # noqa: F401
+from readmenator._ollama import OllamaClient  # noqa: F401
+from readmenator._symindex import SymbolIndex  # noqa: F401
 from readmenator._concepts import ConceptExtractor, verb_for_relation  # noqa: F401
 from readmenator._models import (  # noqa: F401
     AnalysisResult,

{readmenator-1.3.2 → readmenator-1.3.3}/readmenator/__main__.py

@@ -54,6 +54,8 @@ def build_parser() -> argparse.ArgumentParser:
             "  gh-wiki --dry-run       Render GitHub wiki pages locally, no git calls\n"
             "  explorer                Serve force-graph explorer locally\n"
             "  forcegraph              Export force-graph explorer HTML (readmenator-maps/graph-force.html)\n"
+            "  bundles                 Export edge bundle explorer HTML, circle + sphere (readmenator-maps/graph-bundle.html)\n"
+            "  components              Export component diagrams (analysis.json + graph LR markdown + index.html)\n"
             "  analytics               Print corpus analytics JSON (funnel, layers, hotspots)\n"
             "  near <file|text>        Nearest files by scan-text similarity (offline Jaccard)\n"
             "  scan-text               Print synthesized scan-text blobs per file\n"
@@ -327,6 +329,15 @@ def main() -> None:
             out = app.export_forcegraph(target)
             print(out)
             return
+        elif command == "bundles":
+            out = app.export_bundlegraph(target)
+            print(out)
+            return
+        elif command == "components":
+            written = app.export_components(target)
+            for kind, path in sorted(written.items()):
+                print(f"{kind}: {path}")
+            return
         elif command == "analytics":
             import json as _json