index-graph 1.0.0

Compact JSON repository inventory maps for multi-repo workspaces.

index

See the shape of any codebase: a repo-dependency graph + an interactive HTML dashboard, built from real code evidence — zero dependencies.

index scans a workspace for Git repositories and renders a dependency and topology graph of them — as an interactive self-contained HTML dashboard, layered SVG, Mermaid, and a JSON context manifest. Every edge in the graph carries its own evidence (the file and line that witnesses it, plus a confidence grade). Output is deterministic; nothing to install beyond Python.

30-second quickstart

pip install index-graph
index viz --root /path/to/your/workspace --format html --out graph.html
open graph.html   # or: start graph.html on Windows

That produces a self-contained HTML file with an interactive dashboard: clickable nodes, layered layout, dependency lanes, and summary charts — no server, no assets, nothing to host.

To also write the raw JSON manifest:

index map --root /path/to/your/workspace --output INDEX.json

What you get

Output	Command	Description
Interactive HTML dashboard	index viz --format html	Self-contained; click nodes, explore layers and charts
Layered SVG	index viz --format svg	Static vector graph suitable for docs/CI artifacts
Mermaid diagram	index viz --format mermaid	Paste into GitHub markdown or any Mermaid renderer
All three at once	index viz --format all --out-dir ./out	Writes graph.html, graph.svg, graph.mmd
JSON context manifest	index map	Machine-readable inventory: remotes, branches, dirty counts, classification
Dependency graph (text/JSON)	index graph	Repo→repo edges with evidence; each edge carries its witness
Context pack (prose + relations)	index context	Synthesis pack: roles, relations, narrative summary

CLI reference

index map     [--root ROOT] [--output FILE] [--json] [--config CFG]
index graph   [--root ROOT] [--json]
index context [--root ROOT] [--focus REPO]
index viz     [--root ROOT] [--format {html,svg,mermaid,all}]
              [--focus REPO] [--no-external] [--out FILE] [--out-dir DIR]

--focus REPO narrows any render to a single repo's bidirectional dependency neighborhood. --no-external hides stdlib/third-party nodes, keeping the graph to workspace repos only.

Dependency graph example

Running index viz --root ./my-workspace --format mermaid produces a Mermaid flowchart where workspace repos are rectangular nodes and external dependencies are rounded nodes:

flowchart TD
    n_api["api"]
    n_core["core"]
    n_cli["cli"]
    n_pathlib(("pathlib"))
    n_requests(("requests"))
    n_core --> n_pathlib
    n_api --> n_core
    n_cli --> n_api
    n_cli --> n_requests

Every --> edge in the real output carries the file (and line) that witnesses it.

Configuration

Place an optional .index.toml at your workspace root to control classification rules, which remotes to drop, and parallel worker count:

# .index.toml — at your workspace root
[[rule]]                  # classify repos by workspace-relative path; first match wins
pattern = "oss/**"
class   = "public"

[[rule]]
pattern = "work/**"
class   = "internal"

[scan]
jobs  = 16                    # parallel workers
prune = ["vendor", "target"]  # extra dirs to skip (added to the built-in safety set)

[privacy]
omit_origin_classes = ["internal"]   # drop remote URLs for repos in these classes

[output]
portable = true               # root-relative paths + hashed root (default on)

See example.index.toml for the full schema and USAGE.md for the complete flag reference, the importable Python API, and worked examples with expected output.

Guarantees

• Evidence on every edge. No edge appears in the graph without a file (and line) that witnesses it and a confidence grade (high when both a declared dependency and an observed import agree).
• Deterministic output. The same workspace produces the same JSON and renders every time.
• Zero runtime dependencies. Pure Python stdlib; nothing to install beyond Python 3.11+.
• Portable maps. Repository paths are root-relative; the local root is represented by a short hash; credential-shaped strings in remote URLs are always redacted.

Install

pip install index-graph

Or from a checkout:

pip install -e .

---

Zain Dana Harper — small tools with explicit edges. Portfolio · HarperZ9 _{Built with Claude Code; reviewed, tested, and owned by me.}