dagward 0.1.0 → 0.2.0

package/README.md

@@ -44,6 +44,14 @@ Requirements: Node.js ≥ 20, a TypeScript project with a `tsconfig.json`. Monor
 - **`ARCHITECTURE.md`** — a human-readable snapshot of your system as it actually is: layers, module boundaries, existing cycles, and the edges that look accidental. Useful on its own, even if you never adopt the rules.
 - **`dagward.yml`** — a draft rule file. Nothing is enforced until you review, edit, and commit it. Confirming is a 10-minute job; writing from scratch would take days.
 
+## Visualize
+
+```bash
+npx dagward init && npx dagward viz
+```
+
+`dagward viz` renders the graphs in `dagward-out/` to a single self-contained `viz.html` — no network, no CDN, works offline — and opens it in your default browser (`--no-open` to skip). Tabs switch between folder, file, and function level; dependencies point downward, type-only imports are dashed, and cycle members are flagged red.
+
 ## The rule file
 
 Rules are declarative YAML — language-agnostic by design, and readable by both humans and agents. MVP supports three rule types:
@@ -126,6 +134,10 @@ With `--format agent`, a violation looks like this:
 
 The Claude Code hook feeds this back automatically after each edit. In practice, agents fix their own violations on the next turn without human intervention.
 
+## Annotations
+
+Graph nodes can carry an optional `annotation` object — `summary`, `inputs`, `outputs`, `should`, `shouldNot`, `side` (frontend/backend/shared/tooling), `pure` — written by a human or an AI pass, never by dagward itself. Dagward preserves annotations by node id when regenerating graphs, so `dagward init` can run on every change without losing them. Enforcement remains purely deterministic; annotations are context for humans and agents reading the graph.
+
 ## Exemptions
 
 Real architectures have exceptions. Unexplained exceptions are how architectures rot — so every exemption requires a reason, and lives in git:

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -6,24 +7,33 @@ import { parseArgs } from "node:util";
 import { buildFileGraph } from "./fileGraph.js";
 import { buildFolderGraph } from "./folderGraph.js";
 import { buildFunctionGraph } from "./functionGraph.js";
-import { serializeGraph } from "./graph.js";
+import { carryAnnotations, serializeGraph } from "./graph.js";
 import { ConfigError, loadProject } from "./project.js";
 import { renderArchitectureMd } from "./report.js";
+import { renderVizHtml } from "./viz.js";
 const HELP = `dagward — multi-level dependency graphs for TypeScript projects
 
 Usage:
-  dagward graph [dir] [options]   Analyze the project and write graphs + report
-  dagward init  [dir] [options]   Alias of \`graph\` (rule inference coming later)
+  dagward init [dir] [options]   Analyze the project and write graphs + report (dir defaults to .)
+  dagward viz  [dir] [options]   Render dagward-out graphs to an interactive viz.html
 
 Options:
   --project <path>   Explicit tsconfig.json (default: nearest to [dir])
   --out <dir>        Output directory (default: <dir>/dagward-out)
+  --no-open          viz: do not open viz.html in the browser
   --help             Show this help
   --version          Show version
 
 Outputs: graph.folders.json, graph.files.json, graph.functions.json, ARCHITECTURE.md
 
 Exit codes: 0 ok, 2 config error.`;
+function timed(label, fn) {
+    const start = performance.now();
+    const result = fn();
+    const text = typeof label === "string" ? label : label(result);
+    console.error(`→ ${text} … ${Math.round(performance.now() - start)}ms`);
+    return result;
+}
 function version() {
     const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
     return pkg.version;
@@ -34,6 +44,7 @@ export function main(argv) {
         options: {
             project: { type: "string" },
             out: { type: "string" },
+            "no-open": { type: "boolean" },
             help: { type: "boolean" },
             version: { type: "boolean" },
         },
@@ -48,18 +59,19 @@ export function main(argv) {
         return 0;
     }
     const [command, dirArg] = positionals;
-    if (command !== "graph" && command !== "init") {
+    if (command !== "init" && command !== "viz") {
         console.error(command ? `Unknown command: ${command}` : HELP);
         return command ? 2 : 0;
     }
-    if (command === "init") {
-        console.error("Note: `init` currently behaves like `graph`; rule inference is coming later.");
-    }
     const targetDir = path.resolve(dirArg ?? ".");
     const outDir = path.resolve(values.out ?? path.join(targetDir, "dagward-out"));
+    if (command === "viz") {
+        return runViz(outDir, values["no-open"] ?? false);
+    }
+    console.error(`Initializing dagward in ${targetDir}`);
     let project;
     try {
-        project = loadProject(targetDir, values.project ? path.resolve(values.project) : undefined);
+        project = timed((p) => `load project (${p.sourceFiles.length} files, tsconfig at ${p.rootDir})`, () => loadProject(targetDir, values.project ? path.resolve(values.project) : undefined));
     }
     catch (error) {
         if (error instanceof ConfigError) {
@@ -68,15 +80,16 @@ export function main(argv) {
         }
         throw error;
     }
-    console.error(`Analyzing ${project.sourceFiles.length} files (tsconfig at ${project.rootDir})`);
-    const { graph: files, skippedDynamicImports } = buildFileGraph(project);
-    const folders = buildFolderGraph(files);
-    const functions = buildFunctionGraph(project);
-    fs.mkdirSync(outDir, { recursive: true });
-    fs.writeFileSync(path.join(outDir, "graph.folders.json"), serializeGraph(folders));
-    fs.writeFileSync(path.join(outDir, "graph.files.json"), serializeGraph(files));
-    fs.writeFileSync(path.join(outDir, "graph.functions.json"), serializeGraph(functions));
-    fs.writeFileSync(path.join(outDir, "ARCHITECTURE.md"), renderArchitectureMd({ folders, files, functions, skippedDynamicImports, version: version() }));
+    const { graph: files, skippedDynamicImports } = timed("file graph", () => buildFileGraph(project));
+    const folders = timed("folder graph", () => buildFolderGraph(files));
+    const functions = timed("function graph", () => buildFunctionGraph(project));
+    timed("write outputs", () => {
+        fs.mkdirSync(outDir, { recursive: true });
+        writeGraph(path.join(outDir, "graph.folders.json"), folders);
+        writeGraph(path.join(outDir, "graph.files.json"), files);
+        writeGraph(path.join(outDir, "graph.functions.json"), functions);
+        fs.writeFileSync(path.join(outDir, "ARCHITECTURE.md"), renderArchitectureMd({ folders, files, functions, skippedDynamicImports, version: version() }));
+    });
     for (const graph of [folders, files, functions]) {
         const cycles = graph.cycles.length > 0 ? `${graph.cycles.length} cycle(s)!` : "no cycles";
         console.error(`  ${graph.level}: ${graph.nodes.length} nodes, ${graph.edges.length} edges, ${cycles}`);
@@ -84,6 +97,50 @@ export function main(argv) {
     console.error(`Wrote 4 files to ${outDir}`);
     return 0;
 }
+// Node annotations are authored externally (AI or human) but live on the
+// graph nodes; regenerating must not wipe them.
+function writeGraph(file, graph) {
+    try {
+        const prev = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (Array.isArray(prev?.nodes))
+            carryAnnotations(prev, graph);
+    }
+    catch {
+        // absent or malformed previous output: nothing to preserve
+    }
+    fs.writeFileSync(file, serializeGraph(graph));
+}
+function runViz(outDir, noOpen) {
+    const graphs = {};
+    for (const level of ["folders", "files", "functions"]) {
+        const file = path.join(outDir, `graph.${level}.json`);
+        try {
+            graphs[level] = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            console.error(`Cannot read ${file}. Run \`dagward init\` first.`);
+            return 2;
+        }
+    }
+    const htmlPath = path.join(outDir, "viz.html");
+    timed("write viz.html", () => fs.writeFileSync(htmlPath, renderVizHtml(graphs)));
+    console.error(`Wrote ${htmlPath}`);
+    if (!noOpen)
+        openInBrowser(htmlPath);
+    return 0;
+}
+// Never shell: true — the path goes through as a plain argv element, and
+// rundll32 (not `cmd /c start`) avoids cmd.exe re-parsing it on Windows.
+function openInBrowser(file) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [file]]
+        : process.platform === "win32"
+            ? ["rundll32", ["url.dll,FileProtocolHandler", file]]
+            : ["xdg-open", [file]];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => { }); // a missing opener is not a CLI failure
+    child.unref();
+}
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     process.exit(main(process.argv.slice(2)));
 }

package/dist/graph.js

@@ -86,3 +86,16 @@ export function buildGraph(level, root, nodes, edges) {
 export function serializeGraph(graph) {
     return JSON.stringify(graph, null, 2) + "\n";
 }
+// Copy node annotations from a previous graph onto a freshly built one, by
+// node id. A node that was rebuilt with its own annotation keeps it.
+export function carryAnnotations(prev, next) {
+    const previous = new Map(prev.nodes.filter((n) => n.annotation).map((n) => [n.id, n.annotation]));
+    for (const node of next.nodes) {
+        if (!node.annotation) {
+            const annotation = previous.get(node.id);
+            if (annotation)
+                node.annotation = annotation;
+        }
+    }
+    return next;
+}

package/dist/viz.js

@@ -0,0 +1,286 @@
+const STYLE = `
+* { margin: 0; box-sizing: border-box; }
+html, body { height: 100%; }
+body { font: 13px/1.4 ui-sans-serif, system-ui, sans-serif; display: flex; flex-direction: column; background: #f8fafc; color: #0f172a; }
+header { display: flex; align-items: center; gap: 12px; padding: 8px 14px; background: #0f172a; color: #e2e8f0; }
+.brand { font-weight: 700; margin-right: 8px; }
+.tab { background: none; border: 1px solid #334155; color: #cbd5e1; border-radius: 6px; padding: 4px 10px; cursor: pointer; font: inherit; }
+.tab.active { background: #1e293b; color: #fff; border-color: #64748b; }
+.tab span { opacity: 0.6; font-size: 11px; }
+#legend { margin-left: auto; font-size: 11px; color: #94a3b8; }
+#canvas { flex: 1; touch-action: none; cursor: grab; }
+.node { cursor: pointer; }
+.node rect { fill: #fff; stroke: #94a3b8; }
+.node text { font: 11px ui-monospace, Menlo, monospace; fill: #0f172a; pointer-events: none; }
+.node.cyclic rect { stroke: #dc2626; fill: #fef2f2; }
+.edge { fill: none; stroke: #94a3b8; stroke-width: 1.2; }
+.edge.cyc { stroke: #dc2626; }
+.k-type { stroke-dasharray: 4 3; }
+.k-dynamic { stroke-dasharray: 1.5 3; }
+.dimmed .node:not(.hi), .dimmed .edge:not(.hi) { opacity: 0.12; }
+.edge.hi { stroke: #0f766e; stroke-width: 1.8; }
+#details { position: fixed; right: 12px; top: 54px; background: #fff; border: 1px solid #cbd5e1; border-radius: 8px; padding: 10px 12px; max-width: 380px; box-shadow: 0 4px 14px rgba(15, 23, 42, 0.12); font-size: 12px; word-break: break-all; }
+#details div { margin: 2px 0; }
+`;
+// Client-side JS. Lives inside a TS template literal, so it must not contain
+// backticks, \${, or a literal </script> sequence.
+const SCRIPT = `
+"use strict";
+var DATA = JSON.parse(document.getElementById("data").textContent);
+var NW = 170, NH = 26, HGAP = 14, VGAP = 64;
+var svg = document.getElementById("canvas");
+var world = document.getElementById("world");
+var details = document.getElementById("details");
+var layouts = {};
+var current = null;
+var view = { s: 1, tx: 0, ty: 0 };
+var nodeEls = {}, incident = {}, neighbors = {};
+
+// graph.cycles is exactly the set of non-trivial SCCs, so the condensation
+// (collapse each cycle to one component) is acyclic by construction.
+function condense(graph) {
+  var compOf = {};
+  graph.nodes.forEach(function (n) { compOf[n.id] = n.id; });
+  graph.cycles.forEach(function (c) {
+    c.nodes.forEach(function (id) { compOf[id] = "cycle:" + c.id; });
+  });
+  var deps = {};
+  graph.nodes.forEach(function (n) { deps[compOf[n.id]] = deps[compOf[n.id]] || {}; });
+  graph.edges.forEach(function (e) {
+    var a = compOf[e.from], b = compOf[e.to];
+    if (a !== b) deps[a][b] = true;
+  });
+  return { compOf: compOf, deps: deps };
+}
+
+// Longest-path layering: depth 0 depends on nothing; cycle members share a depth.
+function layerDepths(deps) {
+  var depth = {};
+  function resolve(c) {
+    if (depth[c] !== undefined) return depth[c];
+    var d = 0;
+    Object.keys(deps[c]).forEach(function (t) { d = Math.max(d, resolve(t) + 1); });
+    depth[c] = d;
+    return d;
+  }
+  Object.keys(deps).forEach(resolve);
+  return depth;
+}
+
+function computeLayout(graph) {
+  var c = condense(graph);
+  var depth = layerDepths(c.deps);
+  var rows = {}, maxDepth = 0;
+  graph.nodes.forEach(function (n) {
+    var d = depth[c.compOf[n.id]];
+    (rows[d] = rows[d] || []).push(n.id);
+    maxDepth = Math.max(maxDepth, d);
+  });
+  var maxRowWidth = 0;
+  Object.keys(rows).forEach(function (d) {
+    rows[d].sort();
+    maxRowWidth = Math.max(maxRowWidth, rows[d].length * (NW + HGAP) - HGAP);
+  });
+  var pos = {};
+  Object.keys(rows).forEach(function (d) {
+    var row = rows[d];
+    var x0 = (maxRowWidth - (row.length * (NW + HGAP) - HGAP)) / 2;
+    row.forEach(function (id, i) {
+      pos[id] = { x: x0 + i * (NW + HGAP), y: (maxDepth - d) * (NH + VGAP) };
+    });
+  });
+  var cyclic = {};
+  graph.cycles.forEach(function (cy) { cy.nodes.forEach(function (id) { cyclic[id] = cy.id; }); });
+  return { pos: pos, cyclic: cyclic, width: maxRowWidth, height: maxDepth * (NH + VGAP) + NH };
+}
+
+function el(tag, attrs) {
+  var e = document.createElementNS("http://www.w3.org/2000/svg", tag);
+  for (var k in attrs) e.setAttribute(k, attrs[k]);
+  return e;
+}
+
+function edgePath(p1, p2, self) {
+  if (self) {
+    var rx = p1.x + NW, ry = p1.y + NH / 2;
+    return "M" + rx + " " + (ry - 6) + " C " + (rx + 34) + " " + (ry - 20) + ", " + (rx + 34) + " " + (ry + 20) + ", " + rx + " " + (ry + 6);
+  }
+  if (p1.y === p2.y) {
+    var leftToRight = p1.x < p2.x;
+    var x1 = p1.x + (leftToRight ? NW : 0), x2 = p2.x + (leftToRight ? 0 : NW);
+    var y = p1.y + NH / 2, mx = (x1 + x2) / 2;
+    return "M" + x1 + " " + y + " C " + mx + " " + (y - 34) + ", " + mx + " " + (y - 34) + ", " + x2 + " " + y;
+  }
+  var sx = p1.x + NW / 2, sy = p1.y + NH, tx = p2.x + NW / 2, ty = p2.y;
+  var my = (sy + ty) / 2;
+  return "M" + sx + " " + sy + " C " + sx + " " + my + ", " + tx + " " + my + ", " + tx + " " + ty;
+}
+
+function label(id) {
+  return id.length > 24 ? "\\u2026" + id.slice(-23) : id;
+}
+
+function reg(id, edgeEl, neighborId) {
+  (incident[id] = incident[id] || []).push(edgeEl);
+  (neighbors[id] = neighbors[id] || []).push(neighborId);
+}
+
+function highlight(id) {
+  svg.classList.add("dimmed");
+  nodeEls[id].classList.add("hi");
+  (incident[id] || []).forEach(function (p) { p.classList.add("hi"); });
+  (neighbors[id] || []).forEach(function (nb) { if (nodeEls[nb]) nodeEls[nb].classList.add("hi"); });
+}
+
+function clearHighlight() {
+  svg.classList.remove("dimmed");
+  world.querySelectorAll(".hi").forEach(function (e) { e.classList.remove("hi"); });
+}
+
+function showDetails(n) {
+  var graph = DATA[current], fanIn = 0, fanOut = 0;
+  graph.edges.forEach(function (e) {
+    if (e.from === n.id) fanOut++;
+    if (e.to === n.id) fanIn++;
+  });
+  details.hidden = false;
+  details.textContent = "";
+  var rows = [["id", n.id]];
+  if (n.file) rows.push(["file", n.file + (n.line ? ":" + n.line : "")]);
+  rows.push(["depends on", fanOut], ["depended on by", fanIn]);
+  var cyc = layouts[current].cyclic[n.id];
+  if (cyc !== undefined) rows.push(["cycle", "#" + cyc]);
+  rows.forEach(function (r) {
+    var d = document.createElement("div");
+    var b = document.createElement("b");
+    b.textContent = r[0] + ": ";
+    d.appendChild(b);
+    d.appendChild(document.createTextNode(r[1]));
+    details.appendChild(d);
+  });
+}
+
+function render(level) {
+  current = level;
+  var graph = DATA[level];
+  if (!layouts[level]) layouts[level] = computeLayout(graph);
+  var L = layouts[level];
+  world.textContent = "";
+  nodeEls = {}; incident = {}; neighbors = {};
+  graph.edges.forEach(function (e) {
+    var sameCycle = L.cyclic[e.from] !== undefined && L.cyclic[e.from] === L.cyclic[e.to];
+    var p = el("path", {
+      d: edgePath(L.pos[e.from], L.pos[e.to], e.from === e.to),
+      "class": "edge k-" + e.kind + (sameCycle ? " cyc" : ""),
+      "marker-end": "url(#arrow)",
+    });
+    world.appendChild(p);
+    reg(e.from, p, e.to);
+    if (e.from !== e.to) reg(e.to, p, e.from);
+  });
+  graph.nodes.forEach(function (n) {
+    var p = L.pos[n.id];
+    var g = el("g", {
+      "class": "node" + (L.cyclic[n.id] !== undefined ? " cyclic" : ""),
+      transform: "translate(" + p.x + "," + p.y + ")",
+    });
+    g.appendChild(el("rect", { width: NW, height: NH, rx: 6 }));
+    var t = el("text", { x: 8, y: 17 });
+    t.textContent = label(n.id);
+    g.appendChild(t);
+    var title = el("title", {});
+    title.textContent = n.id;
+    g.appendChild(title);
+    g.addEventListener("mouseenter", function () { highlight(n.id); });
+    g.addEventListener("mouseleave", clearHighlight);
+    g.addEventListener("click", function () { showDetails(n); });
+    world.appendChild(g);
+    nodeEls[n.id] = g;
+  });
+}
+
+function applyView() {
+  world.setAttribute("transform", "translate(" + view.tx + "," + view.ty + ") scale(" + view.s + ")");
+}
+
+function fit(L) {
+  var vw = svg.clientWidth, vh = svg.clientHeight;
+  view.s = Math.min(vw / (L.width + 80), vh / (L.height + 80), 1.5);
+  view.tx = (vw - L.width * view.s) / 2;
+  view.ty = (vh - L.height * view.s) / 2;
+  applyView();
+}
+
+svg.addEventListener("wheel", function (ev) {
+  ev.preventDefault();
+  var rect = svg.getBoundingClientRect();
+  var mx = ev.clientX - rect.left, my = ev.clientY - rect.top;
+  var s2 = Math.min(4, Math.max(0.05, view.s * Math.exp(-ev.deltaY * 0.0015)));
+  var f = s2 / view.s;
+  view.tx = mx - (mx - view.tx) * f;
+  view.ty = my - (my - view.ty) * f;
+  view.s = s2;
+  applyView();
+}, { passive: false });
+
+var drag = null;
+svg.addEventListener("pointerdown", function (ev) {
+  if (ev.target.closest(".node")) return;
+  details.hidden = true;
+  drag = { x: ev.clientX, y: ev.clientY, tx: view.tx, ty: view.ty };
+  svg.setPointerCapture(ev.pointerId);
+});
+svg.addEventListener("pointermove", function (ev) {
+  if (!drag) return;
+  view.tx = drag.tx + ev.clientX - drag.x;
+  view.ty = drag.ty + ev.clientY - drag.y;
+  applyView();
+});
+svg.addEventListener("pointerup", function () { drag = null; });
+
+function setLevel(level) {
+  document.querySelectorAll(".tab").forEach(function (b) {
+    b.classList.toggle("active", b.dataset.level === level);
+  });
+  details.hidden = true;
+  clearHighlight();
+  render(level);
+  fit(layouts[level]);
+}
+
+document.querySelectorAll(".tab").forEach(function (b) {
+  b.addEventListener("click", function () { setLevel(b.dataset.level); });
+});
+setLevel("folders");
+`;
+function escapeHtml(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export function renderVizHtml(input) {
+    // <-escape so a node id containing </script> cannot terminate the data
+    // tag; the blob stays valid JSON.
+    const data = JSON.stringify(input).replaceAll("<", "\\u003c");
+    const tabs = ["folders", "files", "functions"]
+        .map((level) => {
+        const graph = input[level];
+        return `<button class="tab" data-level="${level}">${level} <span>${graph.nodes.length}·${graph.edges.length}</span></button>`;
+    })
+        .join("");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>dagward — ${escapeHtml(input.files.root)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header><span class="brand">dagward</span><nav>${tabs}</nav><span id="legend">dependencies point down · dashed = type-only · red = cycle · scroll zoom · drag pan</span></header>
+<svg id="canvas"><defs><marker id="arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="6" markerHeight="6" orient="auto"><path d="M0 0 L8 4 L0 8 z" fill="#94a3b8"/></marker></defs><g id="world"></g></svg>
+<div id="details" hidden></div>
+<script id="data" type="application/json">${data}</script>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dagward",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deterministic architecture review for TypeScript projects: dependency graphs at folder, file, and function level.",
   "license": "Apache-2.0",
   "repository": {