@webpieces/nx-webpieces-rules 0.4.846 → 0.4.847

package/README.md

@@ -66,3 +66,29 @@ forgotten because the gate starts failing again after the date.
 Setting `circularDeps.enabled: false` in the plugin options removes the target
 entirely (rather than toggling it via config). Prefer `mode: "OFF"` instead — it
 keeps the target present so any `dependsOn` references don't dangle.
+
+## View saved architecture and refresh explicitly
+
+`pnpm arch:visualize` and `pnpm arch:visualize-runtime` open saved generated
+snapshots. They render presentation files and open the browser without regenerating
+architecture, API contract, or runtime graph facts. Source edits do not update the
+snapshot. Freshness is unknown because these artifacts do not record reliable
+generation provenance; checkout/file modification times are not generation times.
+
+Refresh explicitly, then view:
+
+```sh
+pnpm arch:generate
+pnpm arch:visualize
+pnpm arch:visualize-runtime
+```
+
+In consuming workspaces without these npm shortcuts, use
+`pnpm nx run architecture:generate`, `pnpm nx run architecture:visualize`, and
+`pnpm nx run architecture:visualize-runtime`. The compile graph's configured
+`graphPath` (or `--graphPath=...`) is still supported. Missing or unusable saved
+artifacts fail with the artifact path and refresh command; viewing never generates
+as a fallback. A failed generation remains a failure, and viewing any saved files
+afterward does not establish that refresh succeeded. Browser-open failures print
+the HTML path for manual opening. Architecture/API validation and CI still run
+their existing checks independently of visualization.

package/executors.json

@@ -8,12 +8,12 @@
         "visualize": {
             "implementation": "./src/executors/visualize/executor",
             "schema": "./src/executors/visualize/schema.json",
-            "description": "Generate visual representations of the architecture graph"
+            "description": "View saved architecture without refreshing; refresh: pnpm nx run architecture:generate"
         },
         "visualize-runtime": {
             "implementation": "./src/executors/visualize-runtime/executor",
             "schema": "./src/executors/visualize-runtime/schema.json",
-            "description": "Render the runtime microservice graph (runtime-dependencies.json)"
+            "description": "View saved runtime architecture without refreshing; refresh: pnpm nx run architecture:generate"
         },
         "validate-runtime-architecture": {
             "implementation": "./src/executors/validate-runtime-architecture/executor",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.4.846",
+  "version": "0.4.847",
   "description": "Nx-specific webpieces validation rules, graph tooling, executors, and inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -19,13 +19,13 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/api-doc-model": "0.4.846",
-    "@webpieces/code-rules": "0.4.846",
-    "@webpieces/core-util": "0.4.846",
-    "@webpieces/eslint-rules": "0.4.846",
-    "@webpieces/rules-config": "0.4.846",
+    "@webpieces/api-doc-model": "0.4.847",
+    "@webpieces/code-rules": "0.4.847",
+    "@webpieces/core-util": "0.4.847",
+    "@webpieces/eslint-rules": "0.4.847",
+    "@webpieces/rules-config": "0.4.847",
     "madge": "8.0.0",
-    "@webpieces/rules-sdk": "0.4.846"
+    "@webpieces/rules-sdk": "0.4.847"
   },
   "peerDependencies": {
     "@nx/devkit": ">=18.0.0"
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@webpieces/tooling-testkit": "0.4.846"
+    "@webpieces/tooling-testkit": "0.4.847"
   },
   "types": "./src/index.d.ts",
   "bin": {

package/src/executors/help/executor.js

@@ -12,8 +12,9 @@ async function helpExecutor(options, context) {
     console.log(`${BOLD}📝 Available npm scripts (convenient shortcuts):${RESET}`);
     console.log('');
     console.log('  Architecture graph:');
-    console.log('    npm run arch:generate                  # Generate dependency graph');
-    console.log('    npm run arch:visualize                 # Visualize dependency graph');
+    console.log('    npm run arch:generate                  # Explicitly refresh architecture/API/runtime facts');
+    console.log('    npm run arch:visualize                 # View saved snapshot (does not refresh)');
+    console.log('    npm run arch:visualize-runtime         # View saved runtime snapshot (does not refresh)');
     console.log('');
     console.log('  Validation:');
     console.log('    npm run arch:validate                  # Quick validation (no-cycles)');
@@ -25,8 +26,9 @@ async function helpExecutor(options, context) {
     console.log(`${BOLD}📝 Available Nx targets:${RESET}`);
     console.log('');
     console.log('  Workspace-level architecture validation:');
-    console.log('    nx run architecture:generate                         # Generate dependency graph');
-    console.log('    nx run architecture:visualize                        # Visualize dependency graph');
+    console.log('    nx run architecture:generate                         # Explicitly refresh architecture/API/runtime facts');
+    console.log('    nx run architecture:visualize                        # View saved snapshot (does not refresh)');
+    console.log('    nx run architecture:visualize-runtime                # View saved runtime snapshot (does not refresh)');
     console.log('    nx run architecture:validate-no-architecture-cycles  # Check for circular project dependencies');
     console.log('    nx run architecture:validate-architecture-unchanged  # Validate against blessed graph');
     console.log('');

package/src/executors/help/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/help/executor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ExecutorContext } from '@nx/devkit';\n\nexport interface HelpExecutorOptions {}\n\ntype HelpExecutorResult = { success: true };\n\nexport default async function helpExecutor(\n    options: HelpExecutorOptions,\n    context: ExecutorContext\n): Promise<HelpExecutorResult> {\n    // ANSI color codes\n    const GREEN = '\\x1b[32m\\x1b[1m';\n    const BOLD = '\\x1b[1m';\n    const RESET = '\\x1b[0m';\n\n    console.log('');\n    console.log(`${GREEN}💡 @webpieces/nx-webpieces-rules - Available Commands${RESET}`);\n    console.log('');\n    console.log(`${BOLD}📝 Available npm scripts (convenient shortcuts):${RESET}`);\n    console.log('');\n    console.log('  Architecture graph:');\n    console.log('    npm run arch:generate                  # Generate dependency graph');\n    console.log('    npm run arch:visualize                 # Visualize dependency graph');\n    console.log('');\n    console.log('  Validation:');\n    console.log('    npm run arch:validate                  # Quick validation (no-cycles)');\n    console.log('    npm run arch:validate-all              # Full arch validation (+ unchanged check)');\n    console.log('    npm run arch:check-circular            # Check all projects for circular deps');\n    console.log('    npm run arch:check-circular-affected   # Check affected projects only');\n    console.log('    npm run arch:validate-complete         # Complete validation (arch + circular)');\n    console.log('');\n    console.log(`${BOLD}📝 Available Nx targets:${RESET}`);\n    console.log('');\n    console.log('  Workspace-level architecture validation:');\n    console.log('    nx run architecture:generate                         # Generate dependency graph');\n    console.log('    nx run architecture:visualize                        # Visualize dependency graph');\n    console.log('    nx run architecture:validate-no-architecture-cycles  # Check for circular project dependencies');\n    console.log('    nx run architecture:validate-architecture-unchanged  # Validate against blessed graph');\n    console.log('');\n    console.log('  Per-project file import cycle checking:');\n    console.log('    nx run <project>:validate-no-file-import-cycles           # Check project for file import cycles');\n    console.log('    nx affected --target=validate-no-file-import-cycles       # Check all affected projects');\n    console.log('    nx run-many --target=validate-no-file-import-cycles --all # Check all projects');\n    console.log('');\n    console.log('  Per-project CI target (lint + build + test):');\n    console.log('    nx run <project>:ci                    # Run lint, build, test together');\n    console.log('    nx run-many --target=ci --all          # Run ci for all projects');\n    console.log('');\n    console.log('    Execution order (test waits for build via targetDefaults):');\n    console.log('    ci (nx:noop)');\n    console.log('    ├── lint ─────────────────┐');\n    console.log('    ├── build ────────────────┼── run in parallel');\n    console.log('    └── test ─────────────────┘');\n    console.log('        └── depends on build (waits)');\n    console.log('');\n    console.log(`${GREEN}💡 Quick start:${RESET}`);\n    console.log(`   ${BOLD}npm run arch:generate${RESET}           # Generate the graph first`);\n    console.log(`   ${BOLD}npm run arch:validate-complete${RESET}  # Run complete validation`);\n    console.log('');\n\n    return { success: true };\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/help/executor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ExecutorContext } from '@nx/devkit';\n\nexport interface HelpExecutorOptions {}\n\ntype HelpExecutorResult = { success: true };\n\nexport default async function helpExecutor(\n    options: HelpExecutorOptions,\n    context: ExecutorContext\n): Promise<HelpExecutorResult> {\n    // ANSI color codes\n    const GREEN = '\\x1b[32m\\x1b[1m';\n    const BOLD = '\\x1b[1m';\n    const RESET = '\\x1b[0m';\n\n    console.log('');\n    console.log(`${GREEN}💡 @webpieces/nx-webpieces-rules - Available Commands${RESET}`);\n    console.log('');\n    console.log(`${BOLD}📝 Available npm scripts (convenient shortcuts):${RESET}`);\n    console.log('');\n    console.log('  Architecture graph:');\n    console.log('    npm run arch:generate                  # Explicitly refresh architecture/API/runtime facts');\n    console.log('    npm run arch:visualize                 # View saved snapshot (does not refresh)');\n    console.log('    npm run arch:visualize-runtime         # View saved runtime snapshot (does not refresh)');\n    console.log('');\n    console.log('  Validation:');\n    console.log('    npm run arch:validate                  # Quick validation (no-cycles)');\n    console.log('    npm run arch:validate-all              # Full arch validation (+ unchanged check)');\n    console.log('    npm run arch:check-circular            # Check all projects for circular deps');\n    console.log('    npm run arch:check-circular-affected   # Check affected projects only');\n    console.log('    npm run arch:validate-complete         # Complete validation (arch + circular)');\n    console.log('');\n    console.log(`${BOLD}📝 Available Nx targets:${RESET}`);\n    console.log('');\n    console.log('  Workspace-level architecture validation:');\n    console.log('    nx run architecture:generate                         # Explicitly refresh architecture/API/runtime facts');\n    console.log('    nx run architecture:visualize                        # View saved snapshot (does not refresh)');\n    console.log('    nx run architecture:visualize-runtime                # View saved runtime snapshot (does not refresh)');\n    console.log('    nx run architecture:validate-no-architecture-cycles  # Check for circular project dependencies');\n    console.log('    nx run architecture:validate-architecture-unchanged  # Validate against blessed graph');\n    console.log('');\n    console.log('  Per-project file import cycle checking:');\n    console.log('    nx run <project>:validate-no-file-import-cycles           # Check project for file import cycles');\n    console.log('    nx affected --target=validate-no-file-import-cycles       # Check all affected projects');\n    console.log('    nx run-many --target=validate-no-file-import-cycles --all # Check all projects');\n    console.log('');\n    console.log('  Per-project CI target (lint + build + test):');\n    console.log('    nx run <project>:ci                    # Run lint, build, test together');\n    console.log('    nx run-many --target=ci --all          # Run ci for all projects');\n    console.log('');\n    console.log('    Execution order (test waits for build via targetDefaults):');\n    console.log('    ci (nx:noop)');\n    console.log('    ├── lint ─────────────────┐');\n    console.log('    ├── build ────────────────┼── run in parallel');\n    console.log('    └── test ─────────────────┘');\n    console.log('        └── depends on build (waits)');\n    console.log('');\n    console.log(`${GREEN}💡 Quick start:${RESET}`);\n    console.log(`   ${BOLD}npm run arch:generate${RESET}           # Generate the graph first`);\n    console.log(`   ${BOLD}npm run arch:validate-complete${RESET}  # Run complete validation`);\n    console.log('');\n\n    return { success: true };\n}\n"]}

package/src/executors/visualize/executor.js

@@ -10,24 +10,22 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
+const saved_snapshot_1 = require("../../lib/saved-snapshot");
 const graph_loader_1 = require("../../lib/graph-loader");
 const graph_visualizer_1 = require("../../lib/graph-visualizer");
 const rules_config_1 = require("@webpieces/rules-config");
 const toError_1 = require("../../toError");
 async function runExecutor(options, context) {
-    const graphPath = options.graphPath;
+    const graphPath = options.graphPath ?? graph_loader_1.DEFAULT_GRAPH_PATH;
     const workspaceRoot = context.root;
+    const snapshot = new saved_snapshot_1.SavedSnapshot();
     console.log('\n🎨 Architecture Visualization\n');
-    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    console.log(snapshot.message());
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Nx command rendering boundary; success:false propagates failure to Nx
     try {
         // Load the saved graph
         console.log('📂 Loading saved graph...');
-        const graphFile = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
-        if (!graphFile) {
-            console.error('❌ No saved graph found at architecture/dependencies.json');
-            console.error('   Run: nx run architecture:generate first');
-            return { success: false };
-        }
+        const graphFile = snapshot.loadProjects(workspaceRoot, graphPath);
         const graph = graphFile.projects;
         // Generate visualization
         console.log('🎨 Generating visualization...');
@@ -47,7 +45,7 @@ async function runExecutor(options, context) {
     catch (err) {
         const error = (0, toError_1.toError)(err);
         const rendered = error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message;
-        console.error('❌ Visualization failed:', rendered);
+        console.error(`❌ Visualization failed for ${graphPath}:`, rendered);
         return { success: false };
     }
 }

package/src/executors/visualize/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAgBH,8BA2CC;AAxDD,yDAA0D;AAC1D,iEAA6D;AAC7D,0DAAgF;AAChF,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,OAAiC,EACjC,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IAEjD,8DAA8D;IAC9D,IAAI,CAAC;QACD,uBAAuB;QACvB,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAE7D,IAAI,CAAC,SAAS,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;YAC1E,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QACD,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC;QAEjC,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,kCAAe,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACrE,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,QAAQ,GAAG,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QAChG,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,QAAQ,CAAC,CAAC;QACnD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Visualize Executor\n *\n * Generates visual representations of the architecture graph (DOT + HTML)\n * and opens the visualization in a browser.\n *\n * Usage:\n * nx run architecture:visualize\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadBlessedGraph } from '../../lib/graph-loader';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { toError } from '../../toError';\n\nexport interface VisualizeExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    options: VisualizeExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🎨 Architecture Visualization\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Load the saved graph\n        console.log('📂 Loading saved graph...');\n        const graphFile = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!graphFile) {\n            console.error('❌ No saved graph found at architecture/dependencies.json');\n            console.error('   Run: nx run architecture:generate first');\n            return { success: false };\n        }\n        const graph = graphFile.projects;\n\n        // Generate visualization\n        console.log('🎨 Generating visualization...');\n        const visualizer = new GraphVisualizer();\n        const vizPaths = visualizer.writeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        // Try to open in browser\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (visualizer.openVisualization(vizPaths.htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Visualization failed:', rendered);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAiBH,8BAuCC;AArDD,6DAAyD;AACzD,yDAA4D;AAC5D,iEAA6D;AAC7D,0DAAgF;AAChF,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,OAAiC,EACjC,OAAwB;IAExB,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,iCAAkB,CAAC;IAC1D,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IACnC,MAAM,QAAQ,GAAkB,IAAI,8BAAa,EAAE,CAAC;IAEpD,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAEhC,uIAAuI;IACvI,IAAI,CAAC;QACD,uBAAuB;QACvB,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,QAAQ,CAAC,YAAY,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAClE,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC;QAEjC,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,kCAAe,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACrE,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,UAAU,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,QAAQ,GAAG,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QAChG,OAAO,CAAC,KAAK,CAAC,8BAA8B,SAAS,GAAG,EAAE,QAAQ,CAAC,CAAC;QACpE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Visualize Executor\n *\n * Generates visual representations of the architecture graph (DOT + HTML)\n * and opens the visualization in a browser.\n *\n * Usage:\n * nx run architecture:visualize\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { SavedSnapshot } from '../../lib/saved-snapshot';\nimport { DEFAULT_GRAPH_PATH } from '../../lib/graph-loader';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { toError } from '../../toError';\n\nexport interface VisualizeExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    options: VisualizeExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath ?? DEFAULT_GRAPH_PATH;\n    const workspaceRoot = context.root;\n    const snapshot: SavedSnapshot = new SavedSnapshot();\n\n    console.log('\\n🎨 Architecture Visualization\\n');\n    console.log(snapshot.message());\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Nx command rendering boundary; success:false propagates failure to Nx\n    try {\n        // Load the saved graph\n        console.log('📂 Loading saved graph...');\n        const graphFile = snapshot.loadProjects(workspaceRoot, graphPath);\n        const graph = graphFile.projects;\n\n        // Generate visualization\n        console.log('🎨 Generating visualization...');\n        const visualizer = new GraphVisualizer();\n        const vizPaths = visualizer.writeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        // Try to open in browser\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (visualizer.openVisualization(vizPaths.htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error(`❌ Visualization failed for ${graphPath}:`, rendered);\n        return { success: false };\n    }\n}\n"]}

package/src/executors/visualize/schema.json

@@ -1,7 +1,7 @@
 {
     "$schema": "http://json-schema.org/schema",
     "title": "Visualize Executor",
-    "description": "Generates visual representations of the architecture graph",
+    "description": "View the saved architecture snapshot without refreshing. Refresh: pnpm nx run architecture:generate.",
     "type": "object",
     "properties": {
         "graphPath": {

package/src/executors/visualize-runtime/executor.js

@@ -9,22 +9,20 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
-const runtime_graph_1 = require("../../lib/runtime-graph");
+const saved_snapshot_1 = require("../../lib/saved-snapshot");
+const rules_config_1 = require("@webpieces/rules-config");
 const runtime_visualizer_1 = require("../../lib/runtime-visualizer");
 const runtime_config_1 = require("../../lib/runtime-config");
 const graph_visualizer_1 = require("../../lib/graph-visualizer");
 const toError_1 = require("../../toError");
 async function runExecutor(_options, context) {
     const workspaceRoot = context.root;
+    const snapshot = new saved_snapshot_1.SavedSnapshot();
     console.log('\n🎨 Runtime Microservice Visualization\n');
-    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    console.log(snapshot.message());
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Nx command rendering boundary; success:false propagates failure to Nx
     try {
-        const graph = (0, runtime_graph_1.loadRuntimeGraph)(workspaceRoot);
-        if (!graph) {
-            console.error('❌ No architecture/runtime-dependencies.json found');
-            console.error('   Run: nx run architecture:generate first');
-            return { success: false };
-        }
+        const graph = snapshot.loadRuntime(workspaceRoot);
         const config = (0, runtime_config_1.loadRuntimeConfig)(workspaceRoot);
         const options = new runtime_visualizer_1.RuntimeVizOptions(config.showExternalNodes);
         const vizPaths = (0, runtime_visualizer_1.writeRuntimeVisualization)(graph, workspaceRoot, undefined, options);
@@ -41,7 +39,8 @@ async function runExecutor(_options, context) {
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);
-        console.error('❌ Runtime visualization failed:', error.message);
+        const rendered = error instanceof rules_config_1.RuleFailError ? (0, rules_config_1.renderRuleFailForHuman)(error) : error.message;
+        console.error('❌ Runtime visualization failed for architecture/runtime-dependencies.json:', rendered);
         return { success: false };
     }
 }

package/src/executors/visualize-runtime/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize-runtime/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAiBH,8BAoCC;AAlDD,2DAA2D;AAC3D,qEAA4F;AAC5F,6DAA6D;AAC7D,iEAA6D;AAC7D,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,QAAiC,EACjC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;IAEzD,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,IAAA,gCAAgB,EAAC,aAAa,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,OAAO,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;YACnE,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,MAAM,GAAG,IAAA,kCAAiB,EAAC,aAAa,CAAC,CAAC;QAChD,MAAM,OAAO,GAAG,IAAI,sCAAiB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAG,IAAA,8CAAyB,EAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QACrF,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,IAAI,kCAAe,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7D,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAChE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Visualize Runtime Executor\n *\n * Renders the runtime microservice graph (committed\n * architecture/runtime-dependencies.json) to DOT + HTML and opens it.\n *\n * Usage: nx run architecture:visualize-runtime\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { loadRuntimeGraph } from '../../lib/runtime-graph';\nimport { writeRuntimeVisualization, RuntimeVizOptions } from '../../lib/runtime-visualizer';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { toError } from '../../toError';\n\nexport interface VisualizeRuntimeOptions {\n    // No options.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    _options: VisualizeRuntimeOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n\n    console.log('\\n🎨 Runtime Microservice Visualization\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const graph = loadRuntimeGraph(workspaceRoot);\n        if (!graph) {\n            console.error('❌ No architecture/runtime-dependencies.json found');\n            console.error('   Run: nx run architecture:generate first');\n            return { success: false };\n        }\n\n        const config = loadRuntimeConfig(workspaceRoot);\n        const options = new RuntimeVizOptions(config.showExternalNodes);\n        const vizPaths = writeRuntimeVisualization(graph, workspaceRoot, undefined, options);\n        console.log(`✅ Generated: ${vizPaths.dotPath}`);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (new GraphVisualizer().openVisualization(vizPaths.htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Runtime visualization failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/visualize-runtime/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAkBH,8BAiCC;AAhDD,6DAAyD;AACzD,0DAAgF;AAChF,qEAA4F;AAC5F,6DAA6D;AAC7D,iEAA6D;AAC7D,2CAAwC;AAUzB,KAAK,UAAU,WAAW,CACrC,QAAiC,EACjC,OAAwB;IAExB,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IACnC,MAAM,QAAQ,GAAkB,IAAI,8BAAa,EAAE,CAAC;IAEpD,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAEhC,uIAAuI;IACvI,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAA,kCAAiB,EAAC,aAAa,CAAC,CAAC;QAChD,MAAM,OAAO,GAAG,IAAI,sCAAiB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAG,IAAA,8CAAyB,EAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QACrF,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,IAAI,kCAAe,EAAE,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7D,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,QAAQ,GAAG,KAAK,YAAY,4BAAa,CAAC,CAAC,CAAC,IAAA,qCAAsB,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;QAChG,OAAO,CAAC,KAAK,CAAC,4EAA4E,EAAE,QAAQ,CAAC,CAAC;QACtG,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","sourcesContent":["/**\n * Visualize Runtime Executor\n *\n * Renders the runtime microservice graph (committed\n * architecture/runtime-dependencies.json) to DOT + HTML and opens it.\n *\n * Usage: nx run architecture:visualize-runtime\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { SavedSnapshot } from '../../lib/saved-snapshot';\nimport { RuleFailError, renderRuleFailForHuman } from '@webpieces/rules-config';\nimport { writeRuntimeVisualization, RuntimeVizOptions } from '../../lib/runtime-visualizer';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { GraphVisualizer } from '../../lib/graph-visualizer';\nimport { toError } from '../../toError';\n\nexport interface VisualizeRuntimeOptions {\n    // No options.\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    _options: VisualizeRuntimeOptions,\n    context: ExecutorContext,\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const snapshot: SavedSnapshot = new SavedSnapshot();\n\n    console.log('\\n🎨 Runtime Microservice Visualization\\n');\n    console.log(snapshot.message());\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- Nx command rendering boundary; success:false propagates failure to Nx\n    try {\n        const graph = snapshot.loadRuntime(workspaceRoot);\n        const config = loadRuntimeConfig(workspaceRoot);\n        const options = new RuntimeVizOptions(config.showExternalNodes);\n        const vizPaths = writeRuntimeVisualization(graph, workspaceRoot, undefined, options);\n        console.log(`✅ Generated: ${vizPaths.dotPath}`);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (new GraphVisualizer().openVisualization(vizPaths.htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        const rendered = error instanceof RuleFailError ? renderRuleFailForHuman(error) : error.message;\n        console.error('❌ Runtime visualization failed for architecture/runtime-dependencies.json:', rendered);\n        return { success: false };\n    }\n}\n"]}

package/src/executors/visualize-runtime/schema.json

@@ -1,7 +1,7 @@
 {
     "$schema": "http://json-schema.org/schema",
     "title": "Visualize Runtime Executor",
-    "description": "Render the runtime microservice graph (runtime-dependencies.json) to DOT + HTML.",
+    "description": "View the saved runtime snapshot as DOT + HTML without refreshing. Refresh: pnpm nx run architecture:generate.",
     "type": "object",
     "properties": {},
     "required": []

package/src/lib/graph-loader.js

@@ -67,9 +67,9 @@ exports.GRAPH_COMMANDS = {
         'architecture/apis/<ApiName>.json and architecture/runtime-dependencies.json; run after ' +
         'adding/removing project dependencies or changing an API\'s endpoints',
     visualizeArchitecture: 'pnpm nx run architecture:visualize — opens the monorepo dependency graph (this file) ' +
-        'as HTML in a browser',
+        'as HTML in a browser from saved data, without refreshing; freshness unknown',
     visualizeRuntimeArchitecture: 'pnpm nx run architecture:visualize-runtime — opens the runtime microservice call graph ' +
-        'as HTML in a browser',
+        'as HTML in a browser from saved data, without refreshing; freshness unknown',
     regenerateDesigns: "pnpm nx run-many --target=di-graph-generate — rewrites every project's " +
         'design.json/design.md (also runs automatically on every build)',
     visualizeDesign: "pnpm wp-design-visualize <project> — opens a project's DI designs (its designFile) as " +

package/src/lib/graph-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"graph-loader.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-loader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Loader\n *\n * Handles loading and saving the blessed dependency graph file.\n * The graph is stored at architecture/dependencies.json in the workspace root.\n *\n * File format (schema aimed at AI consumers):\n * {\n *     \"aiInstructions\": \"...how AI should use the per-project fields...\",\n *     \"apiContractFiles\": { \"<ApiName>\": \"apis/<ApiName>.json\" },\n *     \"projects\": {\n *         \"<project>\": { level, framework, shortDescription,\n *                        responsibilitiesFile, designFile, dependsOn }\n *     }\n * }\n *\n * `framework` is the project's libType — the SET of runtime environments it is\n * validated to run in, drawn from browser | react | angular | node | express\n * (e.g. [\"browser\",\"node\"]). It comes from the project's `framework:` nx tags\n * and is enforced across edges by the `library-types-match-client` rule.\n *\n * The legacy format (flat { \"<project>\": { level, dependsOn } } map) is still\n * readable so validation against a pre-upgrade file produces a clean\n * \"re-run architecture:generate\" diff instead of a parse failure.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { RuleFailError, Option } from '@webpieces/rules-config';\nimport type { ExternalSystemDecls, ProjectApiRelations } from './api-usage/api-relations';\nimport { API_CONTRACT_FILES_RULE, API_CONTRACTS_DIR } from './api-contract-files';\nimport type { ApiContractFileRefs } from './api-contract-files';\nimport { toError } from '../toError';\n\n/**\n * Default path for the dependencies file (relative to workspace root)\n */\nexport const DEFAULT_GRAPH_PATH = 'architecture/dependencies.json';\n\n/**\n * Top-level instructions embedded in dependencies.json telling AI how to use\n * the per-project metadata fields.\n */\nexport const AI_INSTRUCTIONS =\n    \"Each project's shortDescription is only a summary. BEFORE adding code to a project, \" +\n    'read its responsibilitiesFile for the full responsibilities (what belongs in that ' +\n    'project and what does not), and read its designFile to understand the DI design ' +\n    'before reading the code. Use the entries in `commands` to regenerate these files ' +\n    'or display any of the graphs in a browser. To hide a project (its box AND every ' +\n    \"edge touching it) from BOTH rendered architecture graphs, add the nx tag \" +\n    \"'drawOnGraph:false' to that project's project.json tags and regenerate; it stays \" +\n    'in this file (marked \"drawOnGraph\": false) but is omitted from the HTML. A role:server ' +\n    'with no webpiecesRuntime package anywhere in its dependency closure and no apiRelations is ' +\n    'omitted from the RUNTIME drawing the same way — it speaks none of the webpieces runtime, so ' +\n    'it can only ever draw as a disconnected box; it stays in both JSON files. An API\\'s endpoints ' +\n    '(name, kind, path, httpMethod, parameters, queueName, caller) are NOT in this file: ' +\n    '`apiContractFiles` maps each API to its generated contract file, apis/<ApiName>.json relative to ' +\n    'this file — read that file for the API\\'s endpoints.';\n\n/**\n * Named command → \"command — what it does\" map embedded in dependencies.json.\n */\nexport type CommandMap = Record<string, string>;\n\n/**\n * Commands embedded in dependencies.json so AI (and humans) know how to\n * regenerate and DISPLAY the architecture + design graphs. These work in any\n * repo consuming @webpieces/nx-webpieces-rules.\n */\nexport const GRAPH_COMMANDS: CommandMap = {\n    regenerateArchitecture:\n        'pnpm nx run architecture:generate — rewrites architecture/dependencies.json, ' +\n        'architecture/apis/<ApiName>.json and architecture/runtime-dependencies.json; run after ' +\n        'adding/removing project dependencies or changing an API\\'s endpoints',\n    visualizeArchitecture:\n        'pnpm nx run architecture:visualize — opens the monorepo dependency graph (this file) ' +\n        'as HTML in a browser',\n    visualizeRuntimeArchitecture:\n        'pnpm nx run architecture:visualize-runtime — opens the runtime microservice call graph ' +\n        'as HTML in a browser',\n    regenerateDesigns:\n        \"pnpm nx run-many --target=di-graph-generate — rewrites every project's \" +\n        'design.json/design.md (also runs automatically on every build)',\n    visualizeDesign:\n        \"pnpm wp-design-visualize <project> — opens a project's DI designs (its designFile) as \" +\n        'HTML, one graph per controller with the controller at the top; no args = interactive picker',\n};\n\n/**\n * The full contents of architecture/dependencies.json.\n */\nexport class DependenciesFile {\n    constructor(\n        public readonly aiInstructions: string,\n        public readonly commands: CommandMap,\n        public readonly projects: EnhancedGraph,\n        /**\n         * apiClassName -> its contract file (`apis/<ApiName>.json`, relative to this file's\n         * directory). Only the LINK lives here, so adding an endpoint never changes dependencies.json;\n         * the contract itself is read with ApiContractFiles.load.\n         */\n        public readonly apiContractFiles: ApiContractFileRefs = {},\n        /**\n         * Declared external systems (databases, buckets, ...) keyed by identity. MUST be persisted:\n         * the runtime graph is derived from the committed files, so a declaration that is scanned but\n         * not written would make generate and validate disagree.\n         */\n        public readonly externalSystems: ExternalSystemDecls = {}\n    ) {}\n}\n\n/**\n * Load the blessed graph from disk. Understands both the current wrapper\n * format and the legacy flat map (which loads with empty aiInstructions).\n *\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n * @returns The blessed graph file, or null if it doesn't exist\n */\nexport function loadBlessedGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): DependenciesFile | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n\n    if (!fs.existsSync(fullPath)) {\n        return null;\n    }\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const content = fs.readFileSync(fullPath, 'utf-8');\n        const parsed = JSON.parse(content);\n        if (parsed !== null && typeof parsed === 'object' && 'apiContracts' in parsed) {\n            throw movedApiContractsError(fullPath, graphPath);\n        }\n        if (parsed !== null && typeof parsed === 'object' && 'projects' in parsed) {\n            return new DependenciesFile(\n                typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '',\n                parsed.commands !== null && typeof parsed.commands === 'object' ? (parsed.commands as CommandMap) : {},\n                parsed.projects as EnhancedGraph,\n                parsed.apiContractFiles !== null && typeof parsed.apiContractFiles === 'object'\n                    ? (parsed.apiContractFiles as ApiContractFileRefs)\n                    : {},\n                // Absent in any file written before external systems could be declared; an empty\n                // table simply draws no shaped nodes, which is exactly the old rendering.\n                parsed.externalSystems !== null && typeof parsed.externalSystems === 'object'\n                    ? (parsed.externalSystems as ExternalSystemDecls)\n                    : {}\n            );\n        }\n        // Legacy flat format: the whole object is the project map\n        return new DependenciesFile('', {}, parsed as EnhancedGraph);\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) throw error;\n        throw new Error(`Failed to load graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/**\n * The endpoint table moved out of dependencies.json (#949). A file still carrying `apiContracts` was\n * written by an older generator; it is REJECTED rather than read, so there is one place a contract\n * lives and the runtime graph can never read a stale copy of it.\n */\n// webpieces-disable no-function-outside-class -- error builder for loadBlessedGraph, module-scope like its siblings\nfunction movedApiContractsError(fullPath: string, graphPath: string): RuleFailError {\n    const apisDir = path.join(path.dirname(graphPath), API_CONTRACTS_DIR);\n    return new RuleFailError(\n        API_CONTRACT_FILES_RULE,\n        `${fullPath} still carries the \\`apiContracts\\` key. It moved: each API's contract now lives in ` +\n            `${apisDir}/<ApiName>.json, and dependencies.json only links to it under \\`apiContractFiles\\`.`,\n        undefined,\n        undefined,\n        [new Option('Regenerate the architecture files and commit the result: pnpm nx run architecture:generate', true)],\n    );\n}\n\n/**\n * Format the dependencies file as JSON with multi-line arrays for readability\n */\nfunction formatGraphJson(file: DependenciesFile): string {\n    const lines: string[] = ['{'];\n    lines.push(`    \"aiInstructions\": ${JSON.stringify(file.aiInstructions)},`);\n    lines.push(`    \"commands\": {`);\n    const commandNames = Object.keys(file.commands);\n    commandNames.forEach((name: string, index: number) => {\n        const comma = index === commandNames.length - 1 ? '' : ',';\n        lines.push(`        ${JSON.stringify(name)}: ${JSON.stringify(file.commands[name])}${comma}`);\n    });\n    lines.push(`    },`);\n    lines.push(...apiContractFilesLines(file.apiContractFiles));\n    lines.push(...externalSystemsLines(file.externalSystems));\n    lines.push(`    \"projects\": {`);\n\n    const keys = Object.keys(file.projects).sort();\n    keys.forEach((key: string, index: number) => {\n        const entry = file.projects[key];\n        const isLast = index === keys.length - 1;\n        const comma = isLast ? '' : ',';\n\n        lines.push(`        ${JSON.stringify(key)}: {`);\n        lines.push(...formatEntryLines(entry));\n        lines.push(`        }${comma}`);\n    });\n\n    lines.push('    }');\n    lines.push('}');\n    return lines.join('\\n') + '\\n';\n}\n\n/**\n * The `\"apiContractFiles\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows it. Omitted entirely when empty. Keys are sorted, so the output is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction apiContractFilesLines(refs: ApiContractFileRefs): string[] {\n    if (Object.keys(refs).length === 0) return [];\n    const sorted: ApiContractFileRefs = {};\n    for (const api of Object.keys(refs).sort()) sorted[api] = refs[api];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiContractFiles\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * The `\"externalSystems\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows. Omitted entirely when empty, so a repo that declares none keeps the exact file\n * shape it had before this existed — which is what makes adopting it a no-op diff.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction externalSystemsLines(systems: ExternalSystemDecls): string[] {\n    if (Object.keys(systems).length === 0) return [];\n    const sorted: ExternalSystemDecls = {};\n    for (const identity of Object.keys(systems).sort()) sorted[identity] = systems[identity];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"externalSystems\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * Format one project entry's fields (12-space indent). Optional metadata\n * fields are only emitted when present.\n */\nfunction formatEntryLines(entry: GraphEntry): string[] {\n    const lines: string[] = [];\n    lines.push(`            \"level\": ${entry.level},`);\n\n    pushOptionalArrayField(lines, 'framework', entry.framework);\n    pushOptionalField(lines, 'role', entry.role);\n    // Right after role — role says what the project IS, this says what runtime it speaks. MUST be\n    // persisted: validate re-derives the runtime graph from this file, so a field written only\n    // in-memory by generate would make the two derive different graphs.\n    pushOptionalArrayField(lines, 'webpiecesRuntime', entry.webpiecesRuntime);\n    pushOptionalField(lines, 'serviceName', entry.serviceName);\n    pushOptionalCallsServiceField(lines, entry.callsService);\n    pushOptionalBooleanField(lines, 'drawOnGraph', entry.drawOnGraph);\n    // MUST be persisted: validate re-derives the runtime graph from this file, so a cut written only\n    // in-memory by generate would make generate and validate level (and cycle-check) different graphs.\n    pushOptionalArrayField(lines, 'cutLegacyCycle', entry.cutLegacyCycle);\n    pushOptionalField(lines, 'shortDescription', entry.shortDescription);\n    pushOptionalField(lines, 'responsibilitiesFile', entry.responsibilitiesFile);\n    pushOptionalField(lines, 'designFile', entry.designFile);\n    pushApiRelationsField(lines, entry.apiRelations);\n\n    if (entry.dependsOn.length === 0) {\n        lines.push(`            \"dependsOn\": []`);\n    } else {\n        lines.push(`            \"dependsOn\": [`);\n        entry.dependsOn.forEach((dep: string, depIndex: number) => {\n            const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';\n            lines.push(`                ${JSON.stringify(dep)}${depComma}`);\n        });\n        lines.push(`            ]`);\n    }\n    return lines;\n}\n\n/**\n * Emit one optional string field (12-space indent), skipped when undefined.\n */\nfunction pushOptionalField(lines: string[], field: string, value: string | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `callsService` field (12-space indent). Unlike serviceName it may be EITHER a\n * single service name (string) OR an { apiClassName: serviceName } map, so it is emitted with\n * JSON.stringify to cover both inline. MUST be persisted here: the runtime graph's target resolution\n * reads it back from the committed dependencies.json during validate — dropping it would make\n * generate (which enriches it in-memory) and validate (which loads this file) derive different graphs.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalCallsServiceField(\n    lines: string[],\n    value: string | Record<string, string> | undefined,\n): void {\n    if (value !== undefined) {\n        lines.push(`            \"callsService\": ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional boolean field (12-space indent) as a raw JSON boolean\n * (e.g. `\"drawOnGraph\": false,`), skipped when undefined.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalBooleanField(lines: string[], field: string, value: boolean | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional string-array field (12-space indent) as a compact inline\n * JSON array (e.g. `\"framework\": [\"browser\",\"node\"],`), skipped when undefined.\n */\nfunction pushOptionalArrayField(lines: string[], field: string, value: string[] | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `apiRelations` object (pretty, multi-line, reindented under\n * the 12-space entry block) with a trailing comma, since `dependsOn` always\n * follows it. Skipped when absent/empty so plain-lib-only projects stay compact.\n * The scanner already sorts owners + refs, so the JSON is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushApiRelationsField(lines: string[], value: ProjectApiRelations | undefined): void {\n    if (value === undefined || Object.keys(value).length === 0) return;\n    const pretty = JSON.stringify(value, null, 4).split('\\n');\n    pretty.forEach((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiRelations\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        lines.push(`            ${prefix}${line}${suffix}`);\n    });\n}\n\n/**\n * Save the graph to disk in the wrapper format with the standard aiInstructions.\n *\n * @param graph - The enriched project graph to save\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n */\nexport function saveGraph(\n    graph: EnhancedGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH,\n    apiContractFiles: ApiContractFileRefs = {},\n    externalSystems: ExternalSystemDecls = {}\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n\n    // Ensure directory exists\n    if (!fs.existsSync(dir)) {\n        fs.mkdirSync(dir, { recursive: true });\n    }\n\n    // Sort keys for deterministic output\n    const sortedGraph: EnhancedGraph = {};\n    const sortedKeys = Object.keys(graph).sort();\n    for (const key of sortedKeys) {\n        sortedGraph[key] = graph[key];\n    }\n\n    const content = formatGraphJson(\n        new DependenciesFile(AI_INSTRUCTIONS, GRAPH_COMMANDS, sortedGraph, apiContractFiles, externalSystems)\n    );\n    fs.writeFileSync(fullPath, content, 'utf-8');\n}\n\n/**\n * Check if the graph file exists\n */\nexport function graphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): boolean {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    return fs.existsSync(fullPath);\n}\n"]}
+{"version":3,"file":"graph-loader.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-loader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Loader\n *\n * Handles loading and saving the blessed dependency graph file.\n * The graph is stored at architecture/dependencies.json in the workspace root.\n *\n * File format (schema aimed at AI consumers):\n * {\n *     \"aiInstructions\": \"...how AI should use the per-project fields...\",\n *     \"apiContractFiles\": { \"<ApiName>\": \"apis/<ApiName>.json\" },\n *     \"projects\": {\n *         \"<project>\": { level, framework, shortDescription,\n *                        responsibilitiesFile, designFile, dependsOn }\n *     }\n * }\n *\n * `framework` is the project's libType — the SET of runtime environments it is\n * validated to run in, drawn from browser | react | angular | node | express\n * (e.g. [\"browser\",\"node\"]). It comes from the project's `framework:` nx tags\n * and is enforced across edges by the `library-types-match-client` rule.\n *\n * The legacy format (flat { \"<project>\": { level, dependsOn } } map) is still\n * readable so validation against a pre-upgrade file produces a clean\n * \"re-run architecture:generate\" diff instead of a parse failure.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\nimport { RuleFailError, Option } from '@webpieces/rules-config';\nimport type { ExternalSystemDecls, ProjectApiRelations } from './api-usage/api-relations';\nimport { API_CONTRACT_FILES_RULE, API_CONTRACTS_DIR } from './api-contract-files';\nimport type { ApiContractFileRefs } from './api-contract-files';\nimport { toError } from '../toError';\n\n/**\n * Default path for the dependencies file (relative to workspace root)\n */\nexport const DEFAULT_GRAPH_PATH = 'architecture/dependencies.json';\n\n/**\n * Top-level instructions embedded in dependencies.json telling AI how to use\n * the per-project metadata fields.\n */\nexport const AI_INSTRUCTIONS =\n    \"Each project's shortDescription is only a summary. BEFORE adding code to a project, \" +\n    'read its responsibilitiesFile for the full responsibilities (what belongs in that ' +\n    'project and what does not), and read its designFile to understand the DI design ' +\n    'before reading the code. Use the entries in `commands` to regenerate these files ' +\n    'or display any of the graphs in a browser. To hide a project (its box AND every ' +\n    \"edge touching it) from BOTH rendered architecture graphs, add the nx tag \" +\n    \"'drawOnGraph:false' to that project's project.json tags and regenerate; it stays \" +\n    'in this file (marked \"drawOnGraph\": false) but is omitted from the HTML. A role:server ' +\n    'with no webpiecesRuntime package anywhere in its dependency closure and no apiRelations is ' +\n    'omitted from the RUNTIME drawing the same way — it speaks none of the webpieces runtime, so ' +\n    'it can only ever draw as a disconnected box; it stays in both JSON files. An API\\'s endpoints ' +\n    '(name, kind, path, httpMethod, parameters, queueName, caller) are NOT in this file: ' +\n    '`apiContractFiles` maps each API to its generated contract file, apis/<ApiName>.json relative to ' +\n    'this file — read that file for the API\\'s endpoints.';\n\n/**\n * Named command → \"command — what it does\" map embedded in dependencies.json.\n */\nexport type CommandMap = Record<string, string>;\n\n/**\n * Commands embedded in dependencies.json so AI (and humans) know how to\n * regenerate and DISPLAY the architecture + design graphs. These work in any\n * repo consuming @webpieces/nx-webpieces-rules.\n */\nexport const GRAPH_COMMANDS: CommandMap = {\n    regenerateArchitecture:\n        'pnpm nx run architecture:generate — rewrites architecture/dependencies.json, ' +\n        'architecture/apis/<ApiName>.json and architecture/runtime-dependencies.json; run after ' +\n        'adding/removing project dependencies or changing an API\\'s endpoints',\n    visualizeArchitecture:\n        'pnpm nx run architecture:visualize — opens the monorepo dependency graph (this file) ' +\n        'as HTML in a browser from saved data, without refreshing; freshness unknown',\n    visualizeRuntimeArchitecture:\n        'pnpm nx run architecture:visualize-runtime — opens the runtime microservice call graph ' +\n        'as HTML in a browser from saved data, without refreshing; freshness unknown',\n    regenerateDesigns:\n        \"pnpm nx run-many --target=di-graph-generate — rewrites every project's \" +\n        'design.json/design.md (also runs automatically on every build)',\n    visualizeDesign:\n        \"pnpm wp-design-visualize <project> — opens a project's DI designs (its designFile) as \" +\n        'HTML, one graph per controller with the controller at the top; no args = interactive picker',\n};\n\n/**\n * The full contents of architecture/dependencies.json.\n */\nexport class DependenciesFile {\n    constructor(\n        public readonly aiInstructions: string,\n        public readonly commands: CommandMap,\n        public readonly projects: EnhancedGraph,\n        /**\n         * apiClassName -> its contract file (`apis/<ApiName>.json`, relative to this file's\n         * directory). Only the LINK lives here, so adding an endpoint never changes dependencies.json;\n         * the contract itself is read with ApiContractFiles.load.\n         */\n        public readonly apiContractFiles: ApiContractFileRefs = {},\n        /**\n         * Declared external systems (databases, buckets, ...) keyed by identity. MUST be persisted:\n         * the runtime graph is derived from the committed files, so a declaration that is scanned but\n         * not written would make generate and validate disagree.\n         */\n        public readonly externalSystems: ExternalSystemDecls = {}\n    ) {}\n}\n\n/**\n * Load the blessed graph from disk. Understands both the current wrapper\n * format and the legacy flat map (which loads with empty aiInstructions).\n *\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n * @returns The blessed graph file, or null if it doesn't exist\n */\nexport function loadBlessedGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): DependenciesFile | null {\n    const fullPath = path.join(workspaceRoot, graphPath);\n\n    if (!fs.existsSync(fullPath)) {\n        return null;\n    }\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const content = fs.readFileSync(fullPath, 'utf-8');\n        const parsed = JSON.parse(content);\n        if (parsed !== null && typeof parsed === 'object' && 'apiContracts' in parsed) {\n            throw movedApiContractsError(fullPath, graphPath);\n        }\n        if (parsed !== null && typeof parsed === 'object' && 'projects' in parsed) {\n            return new DependenciesFile(\n                typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '',\n                parsed.commands !== null && typeof parsed.commands === 'object' ? (parsed.commands as CommandMap) : {},\n                parsed.projects as EnhancedGraph,\n                parsed.apiContractFiles !== null && typeof parsed.apiContractFiles === 'object'\n                    ? (parsed.apiContractFiles as ApiContractFileRefs)\n                    : {},\n                // Absent in any file written before external systems could be declared; an empty\n                // table simply draws no shaped nodes, which is exactly the old rendering.\n                parsed.externalSystems !== null && typeof parsed.externalSystems === 'object'\n                    ? (parsed.externalSystems as ExternalSystemDecls)\n                    : {}\n            );\n        }\n        // Legacy flat format: the whole object is the project map\n        return new DependenciesFile('', {}, parsed as EnhancedGraph);\n    } catch (err: unknown) {\n        const error = toError(err);\n        if (error instanceof RuleFailError) throw error;\n        throw new Error(`Failed to load graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/**\n * The endpoint table moved out of dependencies.json (#949). A file still carrying `apiContracts` was\n * written by an older generator; it is REJECTED rather than read, so there is one place a contract\n * lives and the runtime graph can never read a stale copy of it.\n */\n// webpieces-disable no-function-outside-class -- error builder for loadBlessedGraph, module-scope like its siblings\nfunction movedApiContractsError(fullPath: string, graphPath: string): RuleFailError {\n    const apisDir = path.join(path.dirname(graphPath), API_CONTRACTS_DIR);\n    return new RuleFailError(\n        API_CONTRACT_FILES_RULE,\n        `${fullPath} still carries the \\`apiContracts\\` key. It moved: each API's contract now lives in ` +\n            `${apisDir}/<ApiName>.json, and dependencies.json only links to it under \\`apiContractFiles\\`.`,\n        undefined,\n        undefined,\n        [new Option('Regenerate the architecture files and commit the result: pnpm nx run architecture:generate', true)],\n    );\n}\n\n/**\n * Format the dependencies file as JSON with multi-line arrays for readability\n */\nfunction formatGraphJson(file: DependenciesFile): string {\n    const lines: string[] = ['{'];\n    lines.push(`    \"aiInstructions\": ${JSON.stringify(file.aiInstructions)},`);\n    lines.push(`    \"commands\": {`);\n    const commandNames = Object.keys(file.commands);\n    commandNames.forEach((name: string, index: number) => {\n        const comma = index === commandNames.length - 1 ? '' : ',';\n        lines.push(`        ${JSON.stringify(name)}: ${JSON.stringify(file.commands[name])}${comma}`);\n    });\n    lines.push(`    },`);\n    lines.push(...apiContractFilesLines(file.apiContractFiles));\n    lines.push(...externalSystemsLines(file.externalSystems));\n    lines.push(`    \"projects\": {`);\n\n    const keys = Object.keys(file.projects).sort();\n    keys.forEach((key: string, index: number) => {\n        const entry = file.projects[key];\n        const isLast = index === keys.length - 1;\n        const comma = isLast ? '' : ',';\n\n        lines.push(`        ${JSON.stringify(key)}: {`);\n        lines.push(...formatEntryLines(entry));\n        lines.push(`        }${comma}`);\n    });\n\n    lines.push('    }');\n    lines.push('}');\n    return lines.join('\\n') + '\\n';\n}\n\n/**\n * The `\"apiContractFiles\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows it. Omitted entirely when empty. Keys are sorted, so the output is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction apiContractFilesLines(refs: ApiContractFileRefs): string[] {\n    if (Object.keys(refs).length === 0) return [];\n    const sorted: ApiContractFileRefs = {};\n    for (const api of Object.keys(refs).sort()) sorted[api] = refs[api];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiContractFiles\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * The `\"externalSystems\": {...}` block (4-space indent), with a trailing comma since `projects`\n * always follows. Omitted entirely when empty, so a repo that declares none keeps the exact file\n * shape it had before this existed — which is what makes adopting it a no-op diff.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling formatters here\nfunction externalSystemsLines(systems: ExternalSystemDecls): string[] {\n    if (Object.keys(systems).length === 0) return [];\n    const sorted: ExternalSystemDecls = {};\n    for (const identity of Object.keys(systems).sort()) sorted[identity] = systems[identity];\n    const pretty = JSON.stringify(sorted, null, 4).split('\\n');\n    return pretty.map((line: string, index: number) => {\n        const prefix = index === 0 ? '\"externalSystems\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        return `    ${prefix}${line}${suffix}`;\n    });\n}\n\n/**\n * Format one project entry's fields (12-space indent). Optional metadata\n * fields are only emitted when present.\n */\nfunction formatEntryLines(entry: GraphEntry): string[] {\n    const lines: string[] = [];\n    lines.push(`            \"level\": ${entry.level},`);\n\n    pushOptionalArrayField(lines, 'framework', entry.framework);\n    pushOptionalField(lines, 'role', entry.role);\n    // Right after role — role says what the project IS, this says what runtime it speaks. MUST be\n    // persisted: validate re-derives the runtime graph from this file, so a field written only\n    // in-memory by generate would make the two derive different graphs.\n    pushOptionalArrayField(lines, 'webpiecesRuntime', entry.webpiecesRuntime);\n    pushOptionalField(lines, 'serviceName', entry.serviceName);\n    pushOptionalCallsServiceField(lines, entry.callsService);\n    pushOptionalBooleanField(lines, 'drawOnGraph', entry.drawOnGraph);\n    // MUST be persisted: validate re-derives the runtime graph from this file, so a cut written only\n    // in-memory by generate would make generate and validate level (and cycle-check) different graphs.\n    pushOptionalArrayField(lines, 'cutLegacyCycle', entry.cutLegacyCycle);\n    pushOptionalField(lines, 'shortDescription', entry.shortDescription);\n    pushOptionalField(lines, 'responsibilitiesFile', entry.responsibilitiesFile);\n    pushOptionalField(lines, 'designFile', entry.designFile);\n    pushApiRelationsField(lines, entry.apiRelations);\n\n    if (entry.dependsOn.length === 0) {\n        lines.push(`            \"dependsOn\": []`);\n    } else {\n        lines.push(`            \"dependsOn\": [`);\n        entry.dependsOn.forEach((dep: string, depIndex: number) => {\n            const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';\n            lines.push(`                ${JSON.stringify(dep)}${depComma}`);\n        });\n        lines.push(`            ]`);\n    }\n    return lines;\n}\n\n/**\n * Emit one optional string field (12-space indent), skipped when undefined.\n */\nfunction pushOptionalField(lines: string[], field: string, value: string | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `callsService` field (12-space indent). Unlike serviceName it may be EITHER a\n * single service name (string) OR an { apiClassName: serviceName } map, so it is emitted with\n * JSON.stringify to cover both inline. MUST be persisted here: the runtime graph's target resolution\n * reads it back from the committed dependencies.json during validate — dropping it would make\n * generate (which enriches it in-memory) and validate (which loads this file) derive different graphs.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalCallsServiceField(\n    lines: string[],\n    value: string | Record<string, string> | undefined,\n): void {\n    if (value !== undefined) {\n        lines.push(`            \"callsService\": ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional boolean field (12-space indent) as a raw JSON boolean\n * (e.g. `\"drawOnGraph\": false,`), skipped when undefined.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushOptionalBooleanField(lines: string[], field: string, value: boolean | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit one optional string-array field (12-space indent) as a compact inline\n * JSON array (e.g. `\"framework\": [\"browser\",\"node\"],`), skipped when undefined.\n */\nfunction pushOptionalArrayField(lines: string[], field: string, value: string[] | undefined): void {\n    if (value !== undefined) {\n        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);\n    }\n}\n\n/**\n * Emit the optional `apiRelations` object (pretty, multi-line, reindented under\n * the 12-space entry block) with a trailing comma, since `dependsOn` always\n * follows it. Skipped when absent/empty so plain-lib-only projects stay compact.\n * The scanner already sorts owners + refs, so the JSON is deterministic.\n */\n// webpieces-disable no-function-outside-class -- module-scope formatter, matches the sibling push*Field helpers here\nfunction pushApiRelationsField(lines: string[], value: ProjectApiRelations | undefined): void {\n    if (value === undefined || Object.keys(value).length === 0) return;\n    const pretty = JSON.stringify(value, null, 4).split('\\n');\n    pretty.forEach((line: string, index: number) => {\n        const prefix = index === 0 ? '\"apiRelations\": ' : '';\n        const suffix = index === pretty.length - 1 ? ',' : '';\n        lines.push(`            ${prefix}${line}${suffix}`);\n    });\n}\n\n/**\n * Save the graph to disk in the wrapper format with the standard aiInstructions.\n *\n * @param graph - The enriched project graph to save\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)\n */\nexport function saveGraph(\n    graph: EnhancedGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH,\n    apiContractFiles: ApiContractFileRefs = {},\n    externalSystems: ExternalSystemDecls = {}\n): void {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    const dir = path.dirname(fullPath);\n\n    // Ensure directory exists\n    if (!fs.existsSync(dir)) {\n        fs.mkdirSync(dir, { recursive: true });\n    }\n\n    // Sort keys for deterministic output\n    const sortedGraph: EnhancedGraph = {};\n    const sortedKeys = Object.keys(graph).sort();\n    for (const key of sortedKeys) {\n        sortedGraph[key] = graph[key];\n    }\n\n    const content = formatGraphJson(\n        new DependenciesFile(AI_INSTRUCTIONS, GRAPH_COMMANDS, sortedGraph, apiContractFiles, externalSystems)\n    );\n    fs.writeFileSync(fullPath, content, 'utf-8');\n}\n\n/**\n * Check if the graph file exists\n */\nexport function graphFileExists(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): boolean {\n    const fullPath = path.join(workspaceRoot, graphPath);\n    return fs.existsSync(fullPath);\n}\n"]}

package/src/lib/graph-visualizer.d.ts

@@ -44,6 +44,7 @@ export declare const CLIENT_DESIGN_LINKS_PLACEHOLDER: string;
 export declare function readCompiledClient(name: string): string;
 export declare class GraphVisualizer {
     private readonly clientJs;
+    private readonly snapshot;
     private readonly names;
     private readonly responsibilities;
     private readonly bandLayout;

package/src/lib/graph-visualizer.js

@@ -15,6 +15,7 @@ exports.GraphVisualizer = exports.CLIENT_DESIGN_LINKS_PLACEHOLDER = exports.CLIE
 exports.readCompiledClient = readCompiledClient;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
+const saved_snapshot_1 = require("./saved-snapshot");
 const path = tslib_1.__importStar(require("path"));
 const child_process_1 = require("child_process");
 const graph_names_1 = require("./graph-names");
@@ -93,6 +94,7 @@ function readCompiledClient(name) {
 }
 class GraphVisualizer {
     clientJs;
+    snapshot = new saved_snapshot_1.SavedSnapshot();
     names = new graph_names_1.GraphNames();
     responsibilities = new graph_responsibilities_1.ResponsibilitiesRenderer();
     bandLayout = new graph_level_bands_1.LevelBandLayout();
@@ -353,6 +355,7 @@ class GraphVisualizer {
 </head>
 <body>
     <h1>${title}</h1>
+    ${this.snapshot.html()}
     <p class="hint">💡 <strong>Click any box</strong> for its menu — <strong>View Design</strong> (only where that project has a generated <strong>design.html</strong>, i.e. what the AI sees inside it) and <strong>Lock/Unlock</strong>, which is the same lock as the dropdown below.</p>
     <p class="hint">🔦 <strong>Hover any box</strong> to trace its <em>entire</em> dependency chain — every ancestor above it (all the way up) <em>and</em> every dependency below it (all the way down), with all the boxes and lines between — while the rest of the graph dims so you can follow one box at a glance.</p>
     ${legend}