dagward 0.1.1 → 0.2.0

package/README.md

@@ -47,7 +47,7 @@ Requirements: Node.js ≥ 20, a TypeScript project with a `tsconfig.json`. Monor
 ## Visualize
 
 ```bash
-npx dagward graph && npx dagward viz
+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.
@@ -134,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

@@ -7,16 +7,15 @@ 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 viz   [dir] [options]   Render dagward-out graphs to an interactive viz.html
+  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])
@@ -60,18 +59,16 @@ export function main(argv) {
         return 0;
     }
     const [command, dirArg] = positionals;
-    if (command !== "graph" && command !== "init" && command !== "viz") {
+    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 = timed((p) => `load project (${p.sourceFiles.length} files, tsconfig at ${p.rootDir})`, () => loadProject(targetDir, values.project ? path.resolve(values.project) : undefined));
@@ -88,9 +85,9 @@ export function main(argv) {
     const functions = timed("function graph", () => buildFunctionGraph(project));
     timed("write outputs", () => {
         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));
+        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]) {
@@ -100,6 +97,19 @@ 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"]) {
@@ -108,7 +118,7 @@ function runViz(outDir, noOpen) {
             graphs[level] = JSON.parse(fs.readFileSync(file, "utf8"));
         }
         catch {
-            console.error(`Cannot read ${file}. Run \`dagward graph\` first.`);
+            console.error(`Cannot read ${file}. Run \`dagward init\` first.`);
             return 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/package.json

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