@draht/tools 2026.7.7 → 2026.7.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -6
- package/bin/draht-tools.cjs +1808 -988
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -32,15 +32,16 @@ All `graph-*` commands are **read-only** (never mutate `MAP.json`), print concis
|
|
|
32
32
|
|
|
33
33
|
`map-graph` builds an interactive, graphify-style **knowledge graph** of your codebase — not just stats:
|
|
34
34
|
|
|
35
|
-
- **MAP.json** (schemaVersion
|
|
35
|
+
- **MAP.json** (schemaVersion 5) — entry points (CLI bins, HTTP routes, library main exports), sinks (FS / net / DB / stdout / exec calls), bounded contexts (packages), cross-package dataflow edges, symbol-resolved call edges, flows, per-module architectural layer (presentation / application / domain / infrastructure / support), exports and imports per file — **plus**: `symbols` (symbol-level nodes with line numbers), `clusters` (deterministic label-propagation neighborhoods) + per-module `cluster`, `hotspots` (god-nodes / most-depended-on / orchestrators / largest), `surprisingConnections` (bridge / cross-group / layer-violating edges), `rationaleIndex` (inline `NOTE`/`WHY`/`HACK`/`TODO`/`FIXME`/`SECURITY` notes), and `EXTRACTED` / `INFERRED` / `AMBIGUOUS` confidence on every edge. Only code-language files become `modules` — docs/config/lockfiles/images etc. are excluded from the module graph (to keep imports/clusters/hotspots free of non-code noise) but still show up in `stats.languages` and are still scanned for `rationaleIndex` notes. Read once and you know how the software actually works — or query it with the `graph-*` commands instead of grepping.
|
|
36
36
|
- **GRAPH_REPORT.md** — a deterministic, skimmable narrative: overview, key concepts (top clusters), god nodes, surprising connections, rationale highlights, and templated suggested questions. The one page to read first.
|
|
37
|
-
- **MAP.html** —
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
37
|
+
- **MAP.html** — an interactive viewer with three tabs:
|
|
38
|
+
- **Graph** — the interactive force-directed canvas graph: nodes colored by cluster and sized by degree, collapsed to one supernode per cluster by default; search, layer/cluster/edge-confidence filters, an inspector (file, symbols, importers, callers), and PNG/SVG export.
|
|
39
|
+
- **Architecture** — package containers in layer bands with cross-package dataflow arrows (thickness = import count); click a package for detail, double-click a group header to focus.
|
|
40
40
|
- **Flows** — entry points on top, sinks on bottom, intermediate modules ranked by depth. Pick an entry → trace which sinks it reaches and through which module.
|
|
41
|
-
- **Insights** — modules colored by cluster, god-nodes enlarged, surprising connections drawn as hot edges. Hover any node for detail.
|
|
42
41
|
|
|
43
|
-
|
|
42
|
+
`MAP.html` embeds the map data inline, so it works fully offline via `file://` — no server needed. Run `draht-tools map-serve` instead for a live-reloading dev view that pushes updates over SSE as you edit.
|
|
43
|
+
|
|
44
|
+
`map-graph` and `map-codebase` always map the **whole repository** from the git root, regardless of any `[dir]` argument — a directory argument only scopes the narrative analysis (`map-codebase`'s STACK/ARCHITECTURE/CONVENTIONS/CONCERNS docs), never the graph itself. The map regenerates on every code-file save (docs/asset saves are ignored by design) in `map-serve` mode (`fs.watch` + Server-Sent Events), and on every commit if you `graph-hook install`. The build is **deterministic** (git-committable) and writes are idempotent — a no-op rebuild produces zero diff. No need to write architecture docs by hand — the map is always current.
|
|
44
45
|
|
|
45
46
|
## Querying the graph (instead of grepping)
|
|
46
47
|
|