@webpieces/nx-webpieces-rules 0.3.238 → 0.3.240

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/nx-webpieces-rules",
-  "version": "0.3.238",
+  "version": "0.3.240",
   "description": "Nx-specific webpieces validation rules and graph tooling. Bundles all @webpieces rule packages with Nx graph validators and an inference plugin.",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -18,11 +18,11 @@
     "README.md"
   ],
   "dependencies": {
-    "@webpieces/ai-hook-rules": "0.3.238",
-    "@webpieces/code-rules": "0.3.238",
-    "@webpieces/eslint-rules": "0.3.238",
-    "@webpieces/pr-gate": "0.3.238",
-    "@webpieces/rules-config": "0.3.238",
+    "@webpieces/ai-hook-rules": "0.3.240",
+    "@webpieces/code-rules": "0.3.240",
+    "@webpieces/eslint-rules": "0.3.240",
+    "@webpieces/pr-gate": "0.3.240",
+    "@webpieces/rules-config": "0.3.240",
     "madge": "8.0.0"
   },
   "peerDependencies": {

package/src/executors/generate/executor.js

@@ -9,9 +9,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
+const rules_config_1 = require("@webpieces/rules-config");
 const graph_generator_1 = require("../../lib/graph-generator");
 const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_loader_1 = require("../../lib/graph-loader");
+const graph_metadata_1 = require("../../lib/graph-metadata");
 const runtime_markers_1 = require("../../lib/runtime-markers");
 const runtime_graph_1 = require("../../lib/runtime-graph");
 const runtime_config_1 = require("../../lib/runtime-config");
@@ -46,11 +48,17 @@ async function runExecutor(options, context) {
         // Step 2: Topological sort (to assign levels for visualization)
         console.log('🔄 Computing topological layers...');
         const enhancedGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
-        // Step 3: Save the graph
+        // Step 3: Enrich with AI metadata (framework, shortDescription, file
+        // pointers). This VALIDATES (responsibilities.md required per project)
+        // and throws before any write, so a failure never clobbers the file.
+        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
+        const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
+        (0, graph_metadata_1.enrichGraph)(enhancedGraph, projectInfos, workspaceRoot);
+        // Step 4: Save the graph
         console.log('💾 Saving graph to architecture/dependencies.json...');
         (0, graph_loader_1.saveGraph)(enhancedGraph, workspaceRoot, graphPath);
         console.log('✅ Graph saved successfully');
-        // Step 4: Generate the runtime microservice graph at the same time
+        // Step 5: Generate the runtime microservice graph at the same time
         await generateRuntimeGraph(workspaceRoot);
         // Print summary
         const projectCount = Object.keys(enhancedGraph).length;
@@ -63,6 +71,11 @@ async function runExecutor(options, context) {
     catch (err) {
         const error = (0, toError_1.toError)(err);
         console.error('❌ Graph generation failed:', error.message);
+        if (error instanceof graph_metadata_1.MetadataValidationError) {
+            const mdPath = (0, rules_config_1.writeTemplate)(workspaceRoot, 'webpieces.responsibilities.md');
+            console.error('');
+            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');
+        }
         return { success: false };
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json.\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { saveGraph } from '../../lib/graph-loader';\nimport { buildWorkspaceModel } from '../../lib/runtime-markers';\nimport { assembleRuntimeGraph, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/**\n * Generate the runtime microservice graph alongside the compile-time graph, so\n * one regenerate produces both committed files. Skipped when the\n * runtime-architecture rule is OFF or no apiProjectPaths are configured.\n */\nasync function generateRuntimeGraph(workspaceRoot: string): Promise<void> {\n    const config = loadRuntimeConfig(workspaceRoot);\n    if (config.off || config.servicePaths.length === 0) {\n        console.log('⏭️  Runtime graph skipped (runtime-architecture OFF or no servicePaths)');\n        return;\n    }\n    console.log('📡 Generating runtime graph from service-contract.json files...');\n    const model = await buildWorkspaceModel(workspaceRoot, config.apiProjectPaths, config.servicePaths);\n    const runtimeGraph = assembleRuntimeGraph(model, workspaceRoot);\n    saveRuntimeGraph(runtimeGraph, workspaceRoot);\n    const serviceCount = Object.keys(runtimeGraph.services).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${runtimeGraph.runtimeEdges.length} runtime edges)`,\n    );\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Step 1: Build the full graph from nx, then transitively reduce it to the view\n        console.log(\"📊 Generating dependency graph from nx's project graph...\");\n        const reducedGraph = await generateReducedGraph();\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(reducedGraph);\n\n        // Step 3: Save the graph\n        console.log('💾 Saving graph to architecture/dependencies.json...');\n        saveGraph(enhancedGraph, workspaceRoot, graphPath);\n        console.log('✅ Graph saved successfully');\n\n        // Step 4: Generate the runtime microservice graph at the same time\n        await generateRuntimeGraph(workspaceRoot);\n\n        // Print summary\n        const projectCount = Object.keys(enhancedGraph).length;\n        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));\n        console.log(`\\n📈 Graph Summary:`);\n        console.log(`   Projects: ${projectCount}`);\n        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Graph generation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/generate/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generate Executor\n *\n * Generates the architecture dependency graph and saves it to architecture/dependencies.json.\n *\n * Usage:\n * nx run architecture:generate\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { saveGraph } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { buildWorkspaceModel } from '../../lib/runtime-markers';\nimport { assembleRuntimeGraph, saveRuntimeGraph } from '../../lib/runtime-graph';\nimport { loadRuntimeConfig } from '../../lib/runtime-config';\nimport { toError } from '../../toError';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\n/**\n * Generate the runtime microservice graph alongside the compile-time graph, so\n * one regenerate produces both committed files. Skipped when the\n * runtime-architecture rule is OFF or no apiProjectPaths are configured.\n */\nasync function generateRuntimeGraph(workspaceRoot: string): Promise<void> {\n    const config = loadRuntimeConfig(workspaceRoot);\n    if (config.off || config.servicePaths.length === 0) {\n        console.log('⏭️  Runtime graph skipped (runtime-architecture OFF or no servicePaths)');\n        return;\n    }\n    console.log('📡 Generating runtime graph from service-contract.json files...');\n    const model = await buildWorkspaceModel(workspaceRoot, config.apiProjectPaths, config.servicePaths);\n    const runtimeGraph = assembleRuntimeGraph(model, workspaceRoot);\n    saveRuntimeGraph(runtimeGraph, workspaceRoot);\n    const serviceCount = Object.keys(runtimeGraph.services).length;\n    console.log(\n        `✅ Runtime graph saved (${serviceCount} services, ${runtimeGraph.runtimeEdges.length} runtime edges)`,\n    );\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Step 1: Build the full graph from nx, then transitively reduce it to the view\n        console.log(\"📊 Generating dependency graph from nx's project graph...\");\n        const reducedGraph = await generateReducedGraph();\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(reducedGraph);\n\n        // Step 3: Enrich with AI metadata (framework, shortDescription, file\n        // pointers). This VALIDATES (responsibilities.md required per project)\n        // and throws before any write, so a failure never clobbers the file.\n        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n        const projectInfos = await collectProjectInfo();\n        enrichGraph(enhancedGraph, projectInfos, workspaceRoot);\n\n        // Step 4: Save the graph\n        console.log('💾 Saving graph to architecture/dependencies.json...');\n        saveGraph(enhancedGraph, workspaceRoot, graphPath);\n        console.log('✅ Graph saved successfully');\n\n        // Step 5: Generate the runtime microservice graph at the same time\n        await generateRuntimeGraph(workspaceRoot);\n\n        // Print summary\n        const projectCount = Object.keys(enhancedGraph).length;\n        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));\n        console.log(`\\n📈 Graph Summary:`);\n        console.log(`   Projects: ${projectCount}`);\n        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Graph generation failed:', error.message);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/validate-architecture-unchanged/executor.js

@@ -15,6 +15,7 @@ const graph_generator_1 = require("../../lib/graph-generator");
 const graph_sorter_1 = require("../../lib/graph-sorter");
 const graph_comparator_1 = require("../../lib/graph-comparator");
 const graph_loader_1 = require("../../lib/graph-loader");
+const graph_metadata_1 = require("../../lib/graph-metadata");
 const toError_1 = require("../../toError");
 const TMP_MD_FILE = 'webpieces.dependencies.md';
 /**
@@ -25,6 +26,22 @@ function writeTmpInstructionsFile(workspaceRoot) {
     const mdPath = (0, rules_config_1.writeTemplate)(workspaceRoot, TMP_MD_FILE);
     return mdPath;
 }
+/**
+ * Report a current-vs-saved graph mismatch and write the AI instructions file.
+ */
+function reportMismatch(summary, workspaceRoot) {
+    const mdPath = writeTmpInstructionsFile(workspaceRoot);
+    console.error('❌ Architecture has changed since last update!');
+    console.error('\nDifferences:');
+    console.error(summary);
+    console.error('');
+    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');
+    console.error('');
+    console.error('To fix:');
+    console.error('  1. Review the changes above');
+    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');
+    console.error('  3. Commit the updated architecture/dependencies.json');
+}
 async function runExecutor(options, context) {
     const graphPath = options.graphPath;
     const workspaceRoot = context.root;
@@ -48,39 +65,36 @@ async function runExecutor(options, context) {
         // Step 2: Topological sort (to get enhanced graph with levels)
         console.log('🔄 Computing topological layers...');
         const currentGraph = (0, graph_sorter_1.sortGraphTopologically)(reducedGraph);
-        // Step 3: Load saved graph
+        // Step 3: Enrich with AI metadata so edits to responsibilities.md,
+        // framework tags, or project moves are caught as graph changes
+        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');
+        const projectInfos = await (0, graph_metadata_1.collectProjectInfo)();
+        (0, graph_metadata_1.enrichGraph)(currentGraph, projectInfos, workspaceRoot);
+        // Step 4: Load saved graph
         console.log('📂 Loading saved graph...');
         const savedGraph = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
         if (!savedGraph) {
             console.error('❌ Could not load saved graph');
             return { success: false };
         }
-        // Step 4: Compare graphs
+        // Step 5: Compare graphs
         console.log('🔍 Comparing current graph to saved graph...');
-        const comparison = (0, graph_comparator_1.compareGraphs)(currentGraph, savedGraph);
+        const comparison = (0, graph_comparator_1.compareGraphs)(currentGraph, savedGraph.projects);
         if (comparison.identical) {
             console.log('✅ Architecture unchanged - current graph matches saved graph');
             return { success: true };
         }
-        else {
-            // Write instructions file for AI agent
-            const mdPath = writeTmpInstructionsFile(workspaceRoot);
-            console.error('❌ Architecture has changed since last update!');
-            console.error('\nDifferences:');
-            console.error(comparison.summary);
-            console.error('');
-            console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');
-            console.error('');
-            console.error('To fix:');
-            console.error('  1. Review the changes above');
-            console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');
-            console.error('  3. Commit the updated architecture/dependencies.json');
-            return { success: false };
-        }
+        reportMismatch(comparison.summary, workspaceRoot);
+        return { success: false };
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);
         console.error('❌ Architecture validation failed:', error.message);
+        if (error instanceof graph_metadata_1.MetadataValidationError) {
+            const mdPath = (0, rules_config_1.writeTemplate)(workspaceRoot, 'webpieces.responsibilities.md');
+            console.error('');
+            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');
+        }
         return { success: false };
     }
 }

package/src/executors/validate-architecture-unchanged/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            console.error('❌ No saved graph found at architecture/dependencies.json');\n            console.error('');\n            console.error('To initialize:');\n            console.error('  1. Run: nx run architecture:generate');\n            console.error('  2. Run: nx run architecture:visualize');\n            console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n            console.error('  4. Commit architecture/dependencies.json');\n            return { success: false };\n        }\n\n        // Step 1: Build the full graph from nx, then transitively reduce it\n        console.log('📊 Generating current dependency graph...');\n        const reducedGraph = await generateReducedGraph();\n\n        // Step 2: Topological sort (to get enhanced graph with levels)\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(reducedGraph);\n\n        // Step 3: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 4: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph, savedGraph);\n\n        if (comparison.identical) {\n            console.log('✅ Architecture unchanged - current graph matches saved graph');\n            return { success: true };\n        } else {\n            // Write instructions file for AI agent\n            const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n            console.error('❌ Architecture has changed since last update!');\n            console.error('\\nDifferences:');\n            console.error(comparison.summary);\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n            console.error('');\n            console.error('To fix:');\n            console.error('  1. Review the changes above');\n            console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n            console.error('  3. Commit the updated architecture/dependencies.json');\n            return { success: false };\n        }\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Architecture validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/nx-webpieces-rules/src/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate Architecture Unchanged Executor\n *\n * Validates that the current architecture graph matches the saved blessed graph.\n * This ensures no unapproved architecture changes have been made.\n *\n * Usage:\n * nx run architecture:validate-architecture-unchanged\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { writeTemplate } from '@webpieces/rules-config';\nimport { generateReducedGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\nimport { collectProjectInfo, enrichGraph, MetadataValidationError } from '../../lib/graph-metadata';\nimport { toError } from '../../toError';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\n/**\n * Write the instructions documentation to .webpieces/instruct-ai/.\n * Sourced from @webpieces/rules-config.\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const mdPath = writeTemplate(workspaceRoot, TMP_MD_FILE);\n\n    return mdPath;\n}\n\n/**\n * Report a current-vs-saved graph mismatch and write the AI instructions file.\n */\nfunction reportMismatch(summary: string, workspaceRoot: string): void {\n    const mdPath = writeTmpInstructionsFile(workspaceRoot);\n\n    console.error('❌ Architecture has changed since last update!');\n    console.error('\\nDifferences:');\n    console.error(summary);\n    console.error('');\n    console.error('⚠️  *** Refer to ' + mdPath + ' for instructions on how to fix *** ⚠️');\n    console.error('');\n    console.error('To fix:');\n    console.error('  1. Review the changes above');\n    console.error('  2. If intentional, ASK USER to run: nx run architecture:generate since this is a critical change');\n    console.error('  3. Commit the updated architecture/dependencies.json');\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const graphPath = options.graphPath;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        // Check if saved graph exists\n        if (!graphFileExists(workspaceRoot, graphPath)) {\n            console.error('❌ No saved graph found at architecture/dependencies.json');\n            console.error('');\n            console.error('To initialize:');\n            console.error('  1. Run: nx run architecture:generate');\n            console.error('  2. Run: nx run architecture:visualize');\n            console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');\n            console.error('  4. Commit architecture/dependencies.json');\n            return { success: false };\n        }\n\n        // Step 1: Build the full graph from nx, then transitively reduce it\n        console.log('📊 Generating current dependency graph...');\n        const reducedGraph = await generateReducedGraph();\n\n        // Step 2: Topological sort (to get enhanced graph with levels)\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(reducedGraph);\n\n        // Step 3: Enrich with AI metadata so edits to responsibilities.md,\n        // framework tags, or project moves are caught as graph changes\n        console.log('🏷️  Enriching graph with framework + responsibilities metadata...');\n        const projectInfos = await collectProjectInfo();\n        enrichGraph(currentGraph, projectInfos, workspaceRoot);\n\n        // Step 4: Load saved graph\n        console.log('📂 Loading saved graph...');\n        const savedGraph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!savedGraph) {\n            console.error('❌ Could not load saved graph');\n            return { success: false };\n        }\n\n        // Step 5: Compare graphs\n        console.log('🔍 Comparing current graph to saved graph...');\n        const comparison = compareGraphs(currentGraph, savedGraph.projects);\n\n        if (comparison.identical) {\n            console.log('✅ Architecture unchanged - current graph matches saved graph');\n            return { success: true };\n        }\n        reportMismatch(comparison.summary, workspaceRoot);\n        return { success: false };\n    } catch (err: unknown) {\n        const error = toError(err);\n        console.error('❌ Architecture validation failed:', error.message);\n        if (error instanceof MetadataValidationError) {\n            const mdPath = writeTemplate(workspaceRoot, 'webpieces.responsibilities.md');\n            console.error('');\n            console.error('⚠️  *** Refer to ' + mdPath + ' for how to author responsibilities.md files *** ⚠️');\n        }\n        return { success: false };\n    }\n}\n"]}

package/src/executors/visualize/executor.js

@@ -21,12 +21,13 @@ async function runExecutor(options, context) {
     try {
         // Load the saved graph
         console.log('📂 Loading saved graph...');
-        const graph = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
-        if (!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 graph = graphFile.projects;
         // Generate visualization
         console.log('🎨 Generating visualization...');
         const vizPaths = (0, graph_visualizer_1.writeVisualization)(graph, workspaceRoot);

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;;AAeH,8BAyCC;AArDD,yDAA0D;AAC1D,iEAAmF;AACnF,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,KAAK,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAEzD,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,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;QAED,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAA,qCAAkB,EAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,IAAA,oCAAiB,EAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,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,yBAAyB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACxD,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 { writeVisualization, openVisualization } from '../../lib/graph-visualizer';\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 graph = loadBlessedGraph(workspaceRoot, graphPath);\n\n        if (!graph) {\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\n        // Generate visualization\n        console.log('🎨 Generating visualization...');\n        const vizPaths = writeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${vizPaths.dotPath}`);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        // Try to open in browser\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (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('❌ 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/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAeH,8BA0CC;AAtDD,yDAA0D;AAC1D,iEAAmF;AACnF,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,QAAQ,GAAG,IAAA,qCAAkB,EAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEjD,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,IAAA,oCAAiB,EAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,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,yBAAyB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACxD,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 { writeVisualization, openVisualization } from '../../lib/graph-visualizer';\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 vizPaths = writeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${vizPaths.dotPath}`);\n        console.log(`✅ Generated: ${vizPaths.htmlPath}`);\n\n        // Try to open in browser\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (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('❌ Visualization failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/src/index.d.ts

@@ -4,6 +4,10 @@ export * from './lib/graph-comparator';
 export * from './lib/package-validator';
 export * from './lib/graph-loader';
 export * from './lib/graph-visualizer';
+export * from './lib/graph-metadata';
+export * from './lib/framework-resolver';
+export * from './lib/project-info';
+export * from './lib/responsibilities';
 import { createNodesV2 } from './plugin';
 export { createNodesV2 };
 declare const _default: {

package/src/index.js

@@ -8,6 +8,10 @@ tslib_1.__exportStar(require("./lib/graph-comparator"), exports);
 tslib_1.__exportStar(require("./lib/package-validator"), exports);
 tslib_1.__exportStar(require("./lib/graph-loader"), exports);
 tslib_1.__exportStar(require("./lib/graph-visualizer"), exports);
+tslib_1.__exportStar(require("./lib/graph-metadata"), exports);
+tslib_1.__exportStar(require("./lib/framework-resolver"), exports);
+tslib_1.__exportStar(require("./lib/project-info"), exports);
+tslib_1.__exportStar(require("./lib/responsibilities"), exports);
 const plugin_1 = require("./plugin");
 Object.defineProperty(exports, "createNodesV2", { enumerable: true, get: function () { return plugin_1.createNodesV2; } });
 exports.default = { name: '@webpieces/nx-webpieces-rules', createNodesV2: plugin_1.createNodesV2 };

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/nx-webpieces-rules/src/index.ts"],"names":[],"mappings":";;;;AAAA,gEAAsC;AACtC,6DAAmC;AACnC,iEAAuC;AACvC,kEAAwC;AACxC,6DAAmC;AACnC,iEAAuC;AACvC,qCAAyC;AAChC,8FADA,sBAAa,OACA;AACtB,kBAAe,EAAE,IAAI,EAAE,+BAA+B,EAAE,aAAa,EAAb,sBAAa,EAAE,CAAC","sourcesContent":["export * from './lib/graph-generator';\nexport * from './lib/graph-sorter';\nexport * from './lib/graph-comparator';\nexport * from './lib/package-validator';\nexport * from './lib/graph-loader';\nexport * from './lib/graph-visualizer';\nimport { createNodesV2 } from './plugin';\nexport { createNodesV2 };\nexport default { name: '@webpieces/nx-webpieces-rules', createNodesV2 };\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/nx-webpieces-rules/src/index.ts"],"names":[],"mappings":";;;;AAAA,gEAAsC;AACtC,6DAAmC;AACnC,iEAAuC;AACvC,kEAAwC;AACxC,6DAAmC;AACnC,iEAAuC;AACvC,+DAAqC;AACrC,mEAAyC;AACzC,6DAAmC;AACnC,iEAAuC;AACvC,qCAAyC;AAChC,8FADA,sBAAa,OACA;AACtB,kBAAe,EAAE,IAAI,EAAE,+BAA+B,EAAE,aAAa,EAAb,sBAAa,EAAE,CAAC","sourcesContent":["export * from './lib/graph-generator';\nexport * from './lib/graph-sorter';\nexport * from './lib/graph-comparator';\nexport * from './lib/package-validator';\nexport * from './lib/graph-loader';\nexport * from './lib/graph-visualizer';\nexport * from './lib/graph-metadata';\nexport * from './lib/framework-resolver';\nexport * from './lib/project-info';\nexport * from './lib/responsibilities';\nimport { createNodesV2 } from './plugin';\nexport { createNodesV2 };\nexport default { name: '@webpieces/nx-webpieces-rules', createNodesV2 };\n"]}

package/src/lib/framework-resolver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Framework Resolver
+ *
+ * Determines the `framework` field written per project into
+ * architecture/dependencies.json (angular, react, express, all-ts, ...).
+ *
+ * Resolution order:
+ * 1. Explicit nx tag `framework:<value>` on the project (project.json tags) —
+ *    any value is allowed so new frameworks need no code change here.
+ * 2. Inference from the project's package.json dependencies.
+ * 3. Fallback: 'all-ts' (plain TypeScript library).
+ */
+import { ProjectInfo } from './project-info';
+export declare const FRAMEWORK_TAG_PREFIX = "framework:";
+export declare class FrameworkResolution {
+    /** Resolved framework name, or null when resolution failed */
+    readonly framework: string | null;
+    /** Problem description when resolution failed, otherwise null */
+    readonly problem: string | null;
+    constructor(
+    /** Resolved framework name, or null when resolution failed */
+    framework: string | null, 
+    /** Problem description when resolution failed, otherwise null */
+    problem: string | null);
+}
+export declare function resolveFramework(info: ProjectInfo, workspaceRoot: string): FrameworkResolution;

package/src/lib/framework-resolver.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Framework Resolver
+ *
+ * Determines the `framework` field written per project into
+ * architecture/dependencies.json (angular, react, express, all-ts, ...).
+ *
+ * Resolution order:
+ * 1. Explicit nx tag `framework:<value>` on the project (project.json tags) —
+ *    any value is allowed so new frameworks need no code change here.
+ * 2. Inference from the project's package.json dependencies.
+ * 3. Fallback: 'all-ts' (plain TypeScript library).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameworkResolution = exports.FRAMEWORK_TAG_PREFIX = void 0;
+exports.resolveFramework = resolveFramework;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const toError_1 = require("../toError");
+exports.FRAMEWORK_TAG_PREFIX = 'framework:';
+/**
+ * A package.json dependency name that identifies a framework.
+ */
+class FrameworkMarker {
+    dependency;
+    framework;
+    constructor(dependency, framework) {
+        this.dependency = dependency;
+        this.framework = framework;
+    }
+}
+/**
+ * Dependency name → framework, checked in order (first match wins).
+ */
+const FRAMEWORK_DEPENDENCY_MARKERS = [
+    new FrameworkMarker('@angular/core', 'angular'),
+    new FrameworkMarker('react', 'react'),
+    new FrameworkMarker('express', 'express'),
+];
+class FrameworkResolution {
+    framework;
+    problem;
+    constructor(
+    /** Resolved framework name, or null when resolution failed */
+    framework, 
+    /** Problem description when resolution failed, otherwise null */
+    problem) {
+        this.framework = framework;
+        this.problem = problem;
+    }
+}
+exports.FrameworkResolution = FrameworkResolution;
+function resolveFramework(info, workspaceRoot) {
+    const tagValues = info.tags
+        .filter((tag) => tag.startsWith(exports.FRAMEWORK_TAG_PREFIX))
+        .map((tag) => tag.slice(exports.FRAMEWORK_TAG_PREFIX.length).trim());
+    if (tagValues.length > 1) {
+        return new FrameworkResolution(null, `${info.name}: has ${tagValues.length} 'framework:' tags (${tagValues.join(', ')}) — a project must have at most one`);
+    }
+    if (tagValues.length === 1) {
+        if (tagValues[0].length === 0) {
+            return new FrameworkResolution(null, `${info.name}: 'framework:' tag has an empty value`);
+        }
+        return new FrameworkResolution(tagValues[0], null);
+    }
+    return new FrameworkResolution(inferFromPackageJson(info, workspaceRoot), null);
+}
+function inferFromPackageJson(info, workspaceRoot) {
+    const pkgJsonPath = path.join(workspaceRoot, info.root, 'package.json');
+    if (!fs.existsSync(pkgJsonPath)) {
+        return 'all-ts';
+    }
+    let allDeps;
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        allDeps = {
+            ...(pkgJson.dependencies ?? {}),
+            ...(pkgJson.devDependencies ?? {}),
+            ...(pkgJson.peerDependencies ?? {}),
+        };
+    }
+    catch (err) {
+        const error = (0, toError_1.toError)(err);
+        throw new Error(`Failed to parse ${pkgJsonPath} while inferring framework for ${info.name}`, {
+            cause: error,
+        });
+    }
+    for (const marker of FRAMEWORK_DEPENDENCY_MARKERS) {
+        if (marker.dependency in allDeps) {
+            return marker.framework;
+        }
+    }
+    return 'all-ts';
+}
+//# sourceMappingURL=framework-resolver.js.map

package/src/lib/framework-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-resolver.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/framework-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Framework Resolver\n *\n * Determines the `framework` field written per project into\n * architecture/dependencies.json (angular, react, express, all-ts, ...).\n *\n * Resolution order:\n * 1. Explicit nx tag `framework:<value>` on the project (project.json tags) —\n *    any value is allowed so new frameworks need no code change here.\n * 2. Inference from the project's package.json dependencies.\n * 3. Fallback: 'all-ts' (plain TypeScript library).\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { ProjectInfo } from './project-info';\nimport { toError } from '../toError';\n\nexport const FRAMEWORK_TAG_PREFIX = 'framework:';\n\n/**\n * A package.json dependency name that identifies a framework.\n */\nclass FrameworkMarker {\n    constructor(\n        public readonly dependency: string,\n        public readonly framework: string\n    ) {}\n}\n\n/**\n * Dependency name → framework, checked in order (first match wins).\n */\nconst FRAMEWORK_DEPENDENCY_MARKERS: ReadonlyArray<FrameworkMarker> = [\n    new FrameworkMarker('@angular/core', 'angular'),\n    new FrameworkMarker('react', 'react'),\n    new FrameworkMarker('express', 'express'),\n];\n\nexport class FrameworkResolution {\n    constructor(\n        /** Resolved framework name, or null when resolution failed */\n        public readonly framework: string | null,\n        /** Problem description when resolution failed, otherwise null */\n        public readonly problem: string | null\n    ) {}\n}\n\nexport function resolveFramework(info: ProjectInfo, workspaceRoot: string): FrameworkResolution {\n    const tagValues = info.tags\n        .filter((tag: string) => tag.startsWith(FRAMEWORK_TAG_PREFIX))\n        .map((tag: string) => tag.slice(FRAMEWORK_TAG_PREFIX.length).trim());\n\n    if (tagValues.length > 1) {\n        return new FrameworkResolution(\n            null,\n            `${info.name}: has ${tagValues.length} 'framework:' tags (${tagValues.join(', ')}) — a project must have at most one`\n        );\n    }\n    if (tagValues.length === 1) {\n        if (tagValues[0].length === 0) {\n            return new FrameworkResolution(null, `${info.name}: 'framework:' tag has an empty value`);\n        }\n        return new FrameworkResolution(tagValues[0], null);\n    }\n\n    return new FrameworkResolution(inferFromPackageJson(info, workspaceRoot), null);\n}\n\nfunction inferFromPackageJson(info: ProjectInfo, workspaceRoot: string): string {\n    const pkgJsonPath = path.join(workspaceRoot, info.root, 'package.json');\n    if (!fs.existsSync(pkgJsonPath)) {\n        return 'all-ts';\n    }\n\n    let allDeps: Record<string, string>;\n    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n    try {\n        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));\n        allDeps = {\n            ...(pkgJson.dependencies ?? {}),\n            ...(pkgJson.devDependencies ?? {}),\n            ...(pkgJson.peerDependencies ?? {}),\n        };\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to parse ${pkgJsonPath} while inferring framework for ${info.name}`, {\n            cause: error,\n        });\n    }\n\n    for (const marker of FRAMEWORK_DEPENDENCY_MARKERS) {\n        if (marker.dependency in allDeps) {\n            return marker.framework;\n        }\n    }\n    return 'all-ts';\n}\n"]}

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

@@ -5,6 +5,14 @@
  * Used in validate mode to ensure developers have updated the graph file.
  */
 import type { EnhancedGraph } from './graph-sorter';
+/**
+ * A changed metadata field on a project (framework, shortDescription, ...)
+ */
+export interface FieldChange {
+    field: string;
+    from: string | undefined;
+    to: string | undefined;
+}
 /**
  * Difference between two graphs
  */
@@ -19,6 +27,7 @@ export interface GraphDiff {
             from: number;
             to: number;
         } | null;
+        changedFields: FieldChange[];
     }[];
 }
 /**

package/src/lib/graph-comparator.js

@@ -7,6 +7,15 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compareGraphs = compareGraphs;
+/**
+ * Metadata fields compared per project (beyond level + dependsOn)
+ */
+const METADATA_FIELDS = [
+    'framework',
+    'shortDescription',
+    'responsibilitiesFile',
+    'designFile',
+];
 /**
  * Compare two graphs and return the differences
  *
@@ -67,16 +76,37 @@ function findModifiedProjects(current, saved, currentProjects, savedProjects, di
         const levelChanged = currentEntry.level !== savedEntry.level
             ? { from: savedEntry.level, to: currentEntry.level }
             : null;
-        if (addedDeps.length > 0 || removedDeps.length > 0 || levelChanged) {
+        const changedFields = findChangedFields(currentEntry, savedEntry);
+        if (addedDeps.length > 0 || removedDeps.length > 0 || levelChanged || changedFields.length > 0) {
             diff.modified.push({
                 project,
                 addedDeps,
                 removedDeps,
                 levelChanged,
+                changedFields,
             });
         }
     }
 }
+function findChangedFields(currentEntry, savedEntry) {
+    const changes = [];
+    for (const field of METADATA_FIELDS) {
+        const from = savedEntry[field];
+        const to = currentEntry[field];
+        if (from !== to) {
+            changes.push({ field, from, to });
+        }
+    }
+    return changes;
+}
+function formatFieldValue(value) {
+    if (value === undefined)
+        return '(none)';
+    const MAX_SUMMARY_VALUE_CHARS = 60;
+    return value.length > MAX_SUMMARY_VALUE_CHARS
+        ? `"${value.slice(0, MAX_SUMMARY_VALUE_CHARS)}..."`
+        : `"${value}"`;
+}
 function buildSummary(diff) {
     const summaryParts = [];
     if (diff.added.length > 0) {
@@ -96,6 +126,9 @@ function buildSummary(diff) {
         if (mod.levelChanged) {
             parts.push(`level: ${mod.levelChanged.from} -> ${mod.levelChanged.to}`);
         }
+        for (const change of mod.changedFields) {
+            parts.push(`${change.field}: ${formatFieldValue(change.from)} -> ${formatFieldValue(change.to)}`);
+        }
         if (parts.length > 0) {
             summaryParts.push(`${mod.project}: ${parts.join('; ')}`);
         }

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

@@ -1 +1 @@
-{"version":3,"file":"graph-comparator.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-comparator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Comparator\n *\n * Compares the current generated graph with the saved (blessed) graph.\n * Used in validate mode to ensure developers have updated the graph file.\n */\n\nimport type { EnhancedGraph } from './graph-sorter';\n\n/**\n * Difference between two graphs\n */\nexport interface GraphDiff {\n    added: string[];\n    removed: string[];\n    modified: {\n        project: string;\n        addedDeps: string[];\n        removedDeps: string[];\n        levelChanged: { from: number; to: number } | null;\n    }[];\n}\n\n/**\n * Comparison result\n */\nexport interface ComparisonResult {\n    identical: boolean;\n    diff: GraphDiff;\n    summary: string;\n}\n\n/**\n * Compare two graphs and return the differences\n *\n * @param current - Currently generated graph\n * @param saved - Previously saved (blessed) graph\n * @returns Comparison result with detailed diff\n */\nexport function compareGraphs(current: EnhancedGraph, saved: EnhancedGraph): ComparisonResult {\n    const currentProjects = new Set(Object.keys(current));\n    const savedProjects = new Set(Object.keys(saved));\n\n    const diff: GraphDiff = {\n        added: [],\n        removed: [],\n        modified: [],\n    };\n\n    // Find added projects\n    for (const project of currentProjects) {\n        if (!savedProjects.has(project)) {\n            diff.added.push(project);\n        }\n    }\n\n    // Find removed projects\n    for (const project of savedProjects) {\n        if (!currentProjects.has(project)) {\n            diff.removed.push(project);\n        }\n    }\n\n    // Find modified projects\n    findModifiedProjects(current, saved, currentProjects, savedProjects, diff);\n\n    const identical =\n        diff.added.length === 0 && diff.removed.length === 0 && diff.modified.length === 0;\n\n    const summary = identical ? 'Graphs are identical' : buildSummary(diff);\n\n    return {\n        identical,\n        diff,\n        summary,\n    };\n}\n\nfunction findModifiedProjects(\n    current: EnhancedGraph,\n    saved: EnhancedGraph,\n    currentProjects: Set<string>,\n    savedProjects: Set<string>,\n    diff: GraphDiff\n): void {\n    for (const project of currentProjects) {\n        if (!savedProjects.has(project)) continue;\n\n        const currentEntry = current[project];\n        const savedEntry = saved[project];\n\n        const currentDeps = new Set(currentEntry.dependsOn);\n        const savedDeps = new Set(savedEntry.dependsOn);\n\n        const addedDeps: string[] = [];\n        const removedDeps: string[] = [];\n\n        for (const dep of currentDeps) {\n            if (!savedDeps.has(dep)) {\n                addedDeps.push(dep);\n            }\n        }\n\n        for (const dep of savedDeps) {\n            if (!currentDeps.has(dep)) {\n                removedDeps.push(dep);\n            }\n        }\n\n        const levelChanged =\n            currentEntry.level !== savedEntry.level\n                ? { from: savedEntry.level, to: currentEntry.level }\n                : null;\n\n        if (addedDeps.length > 0 || removedDeps.length > 0 || levelChanged) {\n            diff.modified.push({\n                project,\n                addedDeps,\n                removedDeps,\n                levelChanged,\n            });\n        }\n    }\n}\n\nfunction buildSummary(diff: GraphDiff): string {\n    const summaryParts: string[] = [];\n\n    if (diff.added.length > 0) {\n        summaryParts.push(`Added projects: ${diff.added.join(', ')}`);\n    }\n\n    if (diff.removed.length > 0) {\n        summaryParts.push(`Removed projects: ${diff.removed.join(', ')}`);\n    }\n\n    for (const mod of diff.modified) {\n        const parts: string[] = [];\n        if (mod.addedDeps.length > 0) {\n            parts.push(`+deps: ${mod.addedDeps.join(', ')}`);\n        }\n        if (mod.removedDeps.length > 0) {\n            parts.push(`-deps: ${mod.removedDeps.join(', ')}`);\n        }\n        if (mod.levelChanged) {\n            parts.push(`level: ${mod.levelChanged.from} -> ${mod.levelChanged.to}`);\n        }\n        if (parts.length > 0) {\n            summaryParts.push(`${mod.project}: ${parts.join('; ')}`);\n        }\n    }\n\n    return summaryParts.join('\\n');\n}\n"]}
+{"version":3,"file":"graph-comparator.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-comparator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Comparator\n *\n * Compares the current generated graph with the saved (blessed) graph.\n * Used in validate mode to ensure developers have updated the graph file.\n */\n\nimport type { EnhancedGraph, GraphEntry } from './graph-sorter';\n\n/**\n * A changed metadata field on a project (framework, shortDescription, ...)\n */\nexport interface FieldChange {\n    field: string;\n    from: string | undefined;\n    to: string | undefined;\n}\n\n/**\n * Difference between two graphs\n */\nexport interface GraphDiff {\n    added: string[];\n    removed: string[];\n    modified: {\n        project: string;\n        addedDeps: string[];\n        removedDeps: string[];\n        levelChanged: { from: number; to: number } | null;\n        changedFields: FieldChange[];\n    }[];\n}\n\n/**\n * Metadata fields compared per project (beyond level + dependsOn)\n */\nconst METADATA_FIELDS: ReadonlyArray<keyof GraphEntry & string> = [\n    'framework',\n    'shortDescription',\n    'responsibilitiesFile',\n    'designFile',\n];\n\n/**\n * Comparison result\n */\nexport interface ComparisonResult {\n    identical: boolean;\n    diff: GraphDiff;\n    summary: string;\n}\n\n/**\n * Compare two graphs and return the differences\n *\n * @param current - Currently generated graph\n * @param saved - Previously saved (blessed) graph\n * @returns Comparison result with detailed diff\n */\nexport function compareGraphs(current: EnhancedGraph, saved: EnhancedGraph): ComparisonResult {\n    const currentProjects = new Set(Object.keys(current));\n    const savedProjects = new Set(Object.keys(saved));\n\n    const diff: GraphDiff = {\n        added: [],\n        removed: [],\n        modified: [],\n    };\n\n    // Find added projects\n    for (const project of currentProjects) {\n        if (!savedProjects.has(project)) {\n            diff.added.push(project);\n        }\n    }\n\n    // Find removed projects\n    for (const project of savedProjects) {\n        if (!currentProjects.has(project)) {\n            diff.removed.push(project);\n        }\n    }\n\n    // Find modified projects\n    findModifiedProjects(current, saved, currentProjects, savedProjects, diff);\n\n    const identical =\n        diff.added.length === 0 && diff.removed.length === 0 && diff.modified.length === 0;\n\n    const summary = identical ? 'Graphs are identical' : buildSummary(diff);\n\n    return {\n        identical,\n        diff,\n        summary,\n    };\n}\n\nfunction findModifiedProjects(\n    current: EnhancedGraph,\n    saved: EnhancedGraph,\n    currentProjects: Set<string>,\n    savedProjects: Set<string>,\n    diff: GraphDiff\n): void {\n    for (const project of currentProjects) {\n        if (!savedProjects.has(project)) continue;\n\n        const currentEntry = current[project];\n        const savedEntry = saved[project];\n\n        const currentDeps = new Set(currentEntry.dependsOn);\n        const savedDeps = new Set(savedEntry.dependsOn);\n\n        const addedDeps: string[] = [];\n        const removedDeps: string[] = [];\n\n        for (const dep of currentDeps) {\n            if (!savedDeps.has(dep)) {\n                addedDeps.push(dep);\n            }\n        }\n\n        for (const dep of savedDeps) {\n            if (!currentDeps.has(dep)) {\n                removedDeps.push(dep);\n            }\n        }\n\n        const levelChanged =\n            currentEntry.level !== savedEntry.level\n                ? { from: savedEntry.level, to: currentEntry.level }\n                : null;\n\n        const changedFields = findChangedFields(currentEntry, savedEntry);\n\n        if (addedDeps.length > 0 || removedDeps.length > 0 || levelChanged || changedFields.length > 0) {\n            diff.modified.push({\n                project,\n                addedDeps,\n                removedDeps,\n                levelChanged,\n                changedFields,\n            });\n        }\n    }\n}\n\nfunction findChangedFields(currentEntry: GraphEntry, savedEntry: GraphEntry): FieldChange[] {\n    const changes: FieldChange[] = [];\n    for (const field of METADATA_FIELDS) {\n        const from = savedEntry[field] as string | undefined;\n        const to = currentEntry[field] as string | undefined;\n        if (from !== to) {\n            changes.push({ field, from, to });\n        }\n    }\n    return changes;\n}\n\nfunction formatFieldValue(value: string | undefined): string {\n    if (value === undefined) return '(none)';\n    const MAX_SUMMARY_VALUE_CHARS = 60;\n    return value.length > MAX_SUMMARY_VALUE_CHARS\n        ? `\"${value.slice(0, MAX_SUMMARY_VALUE_CHARS)}...\"`\n        : `\"${value}\"`;\n}\n\nfunction buildSummary(diff: GraphDiff): string {\n    const summaryParts: string[] = [];\n\n    if (diff.added.length > 0) {\n        summaryParts.push(`Added projects: ${diff.added.join(', ')}`);\n    }\n\n    if (diff.removed.length > 0) {\n        summaryParts.push(`Removed projects: ${diff.removed.join(', ')}`);\n    }\n\n    for (const mod of diff.modified) {\n        const parts: string[] = [];\n        if (mod.addedDeps.length > 0) {\n            parts.push(`+deps: ${mod.addedDeps.join(', ')}`);\n        }\n        if (mod.removedDeps.length > 0) {\n            parts.push(`-deps: ${mod.removedDeps.join(', ')}`);\n        }\n        if (mod.levelChanged) {\n            parts.push(`level: ${mod.levelChanged.from} -> ${mod.levelChanged.to}`);\n        }\n        for (const change of mod.changedFields) {\n            parts.push(\n                `${change.field}: ${formatFieldValue(change.from)} -> ${formatFieldValue(change.to)}`\n            );\n        }\n        if (parts.length > 0) {\n            summaryParts.push(`${mod.project}: ${parts.join('; ')}`);\n        }\n    }\n\n    return summaryParts.join('\\n');\n}\n"]}

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

@@ -3,6 +3,19 @@
  *
  * Handles loading and saving the blessed dependency graph file.
  * The graph is stored at architecture/dependencies.json in the workspace root.
+ *
+ * File format (schema aimed at AI consumers):
+ * {
+ *     "aiInstructions": "...how AI should use the per-project fields...",
+ *     "projects": {
+ *         "<project>": { level, framework, shortDescription,
+ *                        responsibilitiesFile, designFile, dependsOn }
+ *     }
+ * }
+ *
+ * The legacy format (flat { "<project>": { level, dependsOn } } map) is still
+ * readable so validation against a pre-upgrade file produces a clean
+ * "re-run architecture:generate" diff instead of a parse failure.
  */
 import type { EnhancedGraph } from './graph-sorter';
 /**
@@ -10,19 +23,33 @@ import type { EnhancedGraph } from './graph-sorter';
  */
 export declare const DEFAULT_GRAPH_PATH = "architecture/dependencies.json";
 /**
- * Load the blessed graph from disk
+ * Top-level instructions embedded in dependencies.json telling AI how to use
+ * the per-project metadata fields.
+ */
+export declare const AI_INSTRUCTIONS: string;
+/**
+ * The full contents of architecture/dependencies.json.
+ */
+export declare class DependenciesFile {
+    readonly aiInstructions: string;
+    readonly projects: EnhancedGraph;
+    constructor(aiInstructions: string, projects: EnhancedGraph);
+}
+/**
+ * Load the blessed graph from disk. Understands both the current wrapper
+ * format and the legacy flat map (which loads with empty aiInstructions).
  *
  * @param workspaceRoot - Absolute path to workspace root
- * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
- * @returns The blessed graph, or null if file doesn't exist
+ * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)
+ * @returns The blessed graph file, or null if it doesn't exist
  */
-export declare function loadBlessedGraph(workspaceRoot: string, graphPath?: string): EnhancedGraph | null;
+export declare function loadBlessedGraph(workspaceRoot: string, graphPath?: string): DependenciesFile | null;
 /**
- * Save the graph to disk
+ * Save the graph to disk in the wrapper format with the standard aiInstructions.
  *
- * @param graph - The graph to save
+ * @param graph - The enriched project graph to save
  * @param workspaceRoot - Absolute path to workspace root
- * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)
  */
 export declare function saveGraph(graph: EnhancedGraph, workspaceRoot: string, graphPath?: string): void;
 /**

package/src/lib/graph-loader.js

@@ -4,9 +4,22 @@
  *
  * Handles loading and saving the blessed dependency graph file.
  * The graph is stored at architecture/dependencies.json in the workspace root.
+ *
+ * File format (schema aimed at AI consumers):
+ * {
+ *     "aiInstructions": "...how AI should use the per-project fields...",
+ *     "projects": {
+ *         "<project>": { level, framework, shortDescription,
+ *                        responsibilitiesFile, designFile, dependsOn }
+ *     }
+ * }
+ *
+ * The legacy format (flat { "<project>": { level, dependsOn } } map) is still
+ * readable so validation against a pre-upgrade file produces a clean
+ * "re-run architecture:generate" diff instead of a parse failure.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_GRAPH_PATH = void 0;
+exports.DependenciesFile = exports.AI_INSTRUCTIONS = exports.DEFAULT_GRAPH_PATH = void 0;
 exports.loadBlessedGraph = loadBlessedGraph;
 exports.saveGraph = saveGraph;
 exports.graphFileExists = graphFileExists;
@@ -19,11 +32,32 @@ const toError_1 = require("../toError");
  */
 exports.DEFAULT_GRAPH_PATH = 'architecture/dependencies.json';
 /**
- * Load the blessed graph from disk
+ * Top-level instructions embedded in dependencies.json telling AI how to use
+ * the per-project metadata fields.
+ */
+exports.AI_INSTRUCTIONS = "Each project's shortDescription is only a summary. BEFORE adding code to a project, " +
+    'read its responsibilitiesFile for the full responsibilities (what belongs in that ' +
+    'project and what does not), and read its designFile to understand the DI design ' +
+    'before reading the code.';
+/**
+ * The full contents of architecture/dependencies.json.
+ */
+class DependenciesFile {
+    aiInstructions;
+    projects;
+    constructor(aiInstructions, projects) {
+        this.aiInstructions = aiInstructions;
+        this.projects = projects;
+    }
+}
+exports.DependenciesFile = DependenciesFile;
+/**
+ * Load the blessed graph from disk. Understands both the current wrapper
+ * format and the legacy flat map (which loads with empty aiInstructions).
  *
  * @param workspaceRoot - Absolute path to workspace root
- * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
- * @returns The blessed graph, or null if file doesn't exist
+ * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)
+ * @returns The blessed graph file, or null if it doesn't exist
  */
 function loadBlessedGraph(workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH) {
     const fullPath = path.join(workspaceRoot, graphPath);
@@ -33,7 +67,12 @@ function loadBlessedGraph(workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH)
     // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
     try {
         const content = fs.readFileSync(fullPath, 'utf-8');
-        return JSON.parse(content);
+        const parsed = JSON.parse(content);
+        if (parsed !== null && typeof parsed === 'object' && 'projects' in parsed) {
+            return new DependenciesFile(typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '', parsed.projects);
+        }
+        // Legacy flat format: the whole object is the project map
+        return new DependenciesFile('', parsed);
     }
     catch (err) {
         const error = (0, toError_1.toError)(err);
@@ -41,39 +80,63 @@ function loadBlessedGraph(workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH)
     }
 }
 /**
- * Format a graph as JSON with multi-line arrays for readability
+ * Format the dependencies file as JSON with multi-line arrays for readability
  */
-function formatGraphJson(graph) {
+function formatGraphJson(file) {
     const lines = ['{'];
-    const keys = Object.keys(graph).sort();
+    lines.push(`    "aiInstructions": ${JSON.stringify(file.aiInstructions)},`);
+    lines.push(`    "projects": {`);
+    const keys = Object.keys(file.projects).sort();
     keys.forEach((key, index) => {
-        const entry = graph[key];
+        const entry = file.projects[key];
         const isLast = index === keys.length - 1;
         const comma = isLast ? '' : ',';
-        lines.push(`    "${key}": {`);
-        lines.push(`        "level": ${entry.level},`);
-        if (entry.dependsOn.length === 0) {
-            lines.push(`        "dependsOn": []`);
-        }
-        else {
-            lines.push(`        "dependsOn": [`);
-            entry.dependsOn.forEach((dep, depIndex) => {
-                const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';
-                lines.push(`            "${dep}"${depComma}`);
-            });
-            lines.push(`        ]`);
-        }
-        lines.push(`    }${comma}`);
+        lines.push(`        ${JSON.stringify(key)}: {`);
+        lines.push(...formatEntryLines(entry));
+        lines.push(`        }${comma}`);
     });
+    lines.push('    }');
     lines.push('}');
     return lines.join('\n') + '\n';
 }
 /**
- * Save the graph to disk
+ * Format one project entry's fields (12-space indent). Optional metadata
+ * fields are only emitted when present.
+ */
+function formatEntryLines(entry) {
+    const lines = [];
+    lines.push(`            "level": ${entry.level},`);
+    pushOptionalField(lines, 'framework', entry.framework);
+    pushOptionalField(lines, 'shortDescription', entry.shortDescription);
+    pushOptionalField(lines, 'responsibilitiesFile', entry.responsibilitiesFile);
+    pushOptionalField(lines, 'designFile', entry.designFile);
+    if (entry.dependsOn.length === 0) {
+        lines.push(`            "dependsOn": []`);
+    }
+    else {
+        lines.push(`            "dependsOn": [`);
+        entry.dependsOn.forEach((dep, depIndex) => {
+            const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';
+            lines.push(`                ${JSON.stringify(dep)}${depComma}`);
+        });
+        lines.push(`            ]`);
+    }
+    return lines;
+}
+/**
+ * Emit one optional string field (12-space indent), skipped when undefined.
+ */
+function pushOptionalField(lines, field, value) {
+    if (value !== undefined) {
+        lines.push(`            ${JSON.stringify(field)}: ${JSON.stringify(value)},`);
+    }
+}
+/**
+ * Save the graph to disk in the wrapper format with the standard aiInstructions.
  *
- * @param graph - The graph to save
+ * @param graph - The enriched project graph to save
  * @param workspaceRoot - Absolute path to workspace root
- * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)
  */
 function saveGraph(graph, workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH) {
     const fullPath = path.join(workspaceRoot, graphPath);
@@ -88,7 +151,7 @@ function saveGraph(graph, workspaceRoot, graphPath = exports.DEFAULT_GRAPH_PATH)
     for (const key of sortedKeys) {
         sortedGraph[key] = graph[key];
     }
-    const content = formatGraphJson(sortedGraph);
+    const content = formatGraphJson(new DependenciesFile(exports.AI_INSTRUCTIONS, sortedGraph));
     fs.writeFileSync(fullPath, content, 'utf-8');
 }
 /**

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\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { EnhancedGraph } from './graph-sorter';\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 * Load the blessed graph from disk\n *\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)\n * @returns The blessed graph, or null if file doesn't exist\n */\nexport function loadBlessedGraph(\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\n): EnhancedGraph | 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        return JSON.parse(content) as EnhancedGraph;\n    } catch (err: unknown) {\n        const error = toError(err);\n        throw new Error(`Failed to load graph from ${fullPath}`, { cause: error });\n    }\n}\n\n/**\n * Format a graph as JSON with multi-line arrays for readability\n */\nfunction formatGraphJson(graph: EnhancedGraph): string {\n    const lines: string[] = ['{'];\n    const keys = Object.keys(graph).sort();\n\n    keys.forEach((key, index) => {\n        const entry = graph[key];\n        const isLast = index === keys.length - 1;\n        const comma = isLast ? '' : ',';\n\n        lines.push(`    \"${key}\": {`);\n        lines.push(`        \"level\": ${entry.level},`);\n\n        if (entry.dependsOn.length === 0) {\n            lines.push(`        \"dependsOn\": []`);\n        } else {\n            lines.push(`        \"dependsOn\": [`);\n            entry.dependsOn.forEach((dep, depIndex) => {\n                const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';\n                lines.push(`            \"${dep}\"${depComma}`);\n            });\n            lines.push(`        ]`);\n        }\n\n        lines.push(`    }${comma}`);\n\n    });\n\n    lines.push('}');\n    return lines.join('\\n') + '\\n';\n}\n\n/**\n * Save the graph to disk\n *\n * @param graph - The graph to save\n * @param workspaceRoot - Absolute path to workspace root\n * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)\n */\nexport function saveGraph(\n    graph: EnhancedGraph,\n    workspaceRoot: string,\n    graphPath: string = DEFAULT_GRAPH_PATH\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(sortedGraph);\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":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAwCH,4CA0BC;AAoED,8BAsBC;AAKD,0CAMC;;AArKD,+CAAyB;AACzB,mDAA6B;AAE7B,wCAAqC;AAErC;;GAEG;AACU,QAAA,kBAAkB,GAAG,gCAAgC,CAAC;AAEnE;;;GAGG;AACU,QAAA,eAAe,GACxB,sFAAsF;IACtF,oFAAoF;IACpF,kFAAkF;IAClF,0BAA0B,CAAC;AAE/B;;GAEG;AACH,MAAa,gBAAgB;IAEL;IACA;IAFpB,YACoB,cAAsB,EACtB,QAAuB;QADvB,mBAAc,GAAd,cAAc,CAAQ;QACtB,aAAQ,GAAR,QAAQ,CAAe;IACxC,CAAC;CACP;AALD,4CAKC;AAED;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAC5B,aAAqB,EACrB,YAAoB,0BAAkB;IAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAErD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,8DAA8D;IAC9D,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;YACxE,OAAO,IAAI,gBAAgB,CACvB,OAAO,MAAM,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,EACtE,MAAM,CAAC,QAAyB,CACnC,CAAC;QACN,CAAC;QACD,0DAA0D;QAC1D,OAAO,IAAI,gBAAgB,CAAC,EAAE,EAAE,MAAuB,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,IAAA,iBAAO,EAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,IAAsB;IAC3C,MAAM,KAAK,GAAa,CAAC,GAAG,CAAC,CAAC;IAC9B,KAAK,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAEhC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,OAAO,CAAC,CAAC,GAAW,EAAE,KAAa,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAEhC,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAAiB;IACvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,wBAAwB,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;IAEnD,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IACvD,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACrE,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC7E,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAEzD,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACJ,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QACzC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,GAAW,EAAE,QAAgB,EAAE,EAAE;YACtD,MAAM,QAAQ,GAAG,QAAQ,KAAK,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;YACpE,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,QAAQ,EAAE,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAS,iBAAiB,CAAC,KAAe,EAAE,KAAa,EAAE,KAAyB;IAChF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClF,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CACrB,KAAoB,EACpB,aAAqB,EACrB,YAAoB,0BAAkB;IAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEnC,0BAA0B;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,qCAAqC;IACrC,MAAM,WAAW,GAAkB,EAAE,CAAC;IACtC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC3B,WAAW,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,gBAAgB,CAAC,uBAAe,EAAE,WAAW,CAAC,CAAC,CAAC;IACpF,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAC3B,aAAqB,EACrB,YAAoB,0BAAkB;IAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACrD,OAAO,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC","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 *     \"projects\": {\n *         \"<project>\": { level, framework, shortDescription,\n *                        responsibilitiesFile, designFile, dependsOn }\n *     }\n * }\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 { 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.';\n\n/**\n * The full contents of architecture/dependencies.json.\n */\nexport class DependenciesFile {\n    constructor(\n        public readonly aiInstructions: string,\n        public readonly projects: EnhancedGraph\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' && 'projects' in parsed) {\n            return new DependenciesFile(\n                typeof parsed.aiInstructions === 'string' ? parsed.aiInstructions : '',\n                parsed.projects as EnhancedGraph\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        throw new Error(`Failed to load graph from ${fullPath}`, { cause: error });\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(`    \"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 * 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    pushOptionalField(lines, 'framework', entry.framework);\n    pushOptionalField(lines, 'shortDescription', entry.shortDescription);\n    pushOptionalField(lines, 'responsibilitiesFile', entry.responsibilitiesFile);\n    pushOptionalField(lines, 'designFile', entry.designFile);\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 * 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): 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(new DependenciesFile(AI_INSTRUCTIONS, sortedGraph));\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-metadata.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Graph Metadata Enrichment
+ *
+ * Fills the AI-oriented fields on each architecture/dependencies.json entry:
+ *   framework            — from `framework:<x>` nx tag or package.json inference
+ *   shortDescription     — first paragraph of the project's responsibilities.md
+ *   responsibilitiesFile — repo-relative path to the required responsibilities.md
+ *   designFile           — repo-relative path to the generated DI design.json
+ *
+ * Validation is aggregated: ALL problems across ALL projects are collected and
+ * thrown as one MetadataValidationError so a repo adopting this sees the full
+ * seeding list in a single run. Callers must enrich BEFORE writing any file so
+ * a failed run never clobbers dependencies.json.
+ */
+import type { EnhancedGraph } from './graph-sorter';
+import { ProjectInfo } from './project-info';
+export declare const RESPONSIBILITIES_FILE_NAME = "responsibilities.md";
+/**
+ * Thrown when one or more projects fail metadata validation (missing/invalid
+ * responsibilities.md, bad framework tags, ...). Executors catch this to point
+ * AI at the webpieces.responsibilities.md instructions template.
+ */
+export declare class MetadataValidationError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/**
+ * Read per-project root + tags from nx's project graph.
+ */
+export declare function collectProjectInfo(): Promise<Map<string, ProjectInfo>>;
+/**
+ * Enrich every graph entry in place with framework, shortDescription,
+ * responsibilitiesFile and designFile. Throws MetadataValidationError listing
+ * every problem when any project fails validation.
+ */
+export declare function enrichGraph(graph: EnhancedGraph, infos: Map<string, ProjectInfo>, workspaceRoot: string): void;

package/src/lib/graph-metadata.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Graph Metadata Enrichment
+ *
+ * Fills the AI-oriented fields on each architecture/dependencies.json entry:
+ *   framework            — from `framework:<x>` nx tag or package.json inference
+ *   shortDescription     — first paragraph of the project's responsibilities.md
+ *   responsibilitiesFile — repo-relative path to the required responsibilities.md
+ *   designFile           — repo-relative path to the generated DI design.json
+ *
+ * Validation is aggregated: ALL problems across ALL projects are collected and
+ * thrown as one MetadataValidationError so a repo adopting this sees the full
+ * seeding list in a single run. Callers must enrich BEFORE writing any file so
+ * a failed run never clobbers dependencies.json.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataValidationError = exports.RESPONSIBILITIES_FILE_NAME = void 0;
+exports.collectProjectInfo = collectProjectInfo;
+exports.enrichGraph = enrichGraph;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const devkit_1 = require("@nx/devkit");
+const project_info_1 = require("./project-info");
+const framework_resolver_1 = require("./framework-resolver");
+const responsibilities_1 = require("./responsibilities");
+exports.RESPONSIBILITIES_FILE_NAME = 'responsibilities.md';
+/**
+ * Thrown when one or more projects fail metadata validation (missing/invalid
+ * responsibilities.md, bad framework tags, ...). Executors catch this to point
+ * AI at the webpieces.responsibilities.md instructions template.
+ */
+class MetadataValidationError extends Error {
+    problems;
+    constructor(problems) {
+        super(`Architecture metadata validation failed (${problems.length} problem(s)):\n` +
+            problems.map((problem) => `  - ${problem}`).join('\n'));
+        this.problems = problems;
+        this.name = 'MetadataValidationError';
+    }
+}
+exports.MetadataValidationError = MetadataValidationError;
+/**
+ * Read per-project root + tags from nx's project graph.
+ */
+async function collectProjectInfo() {
+    const projectGraph = await (0, devkit_1.createProjectGraphAsync)();
+    const infos = new Map();
+    for (const [name, node] of Object.entries(projectGraph.nodes)) {
+        infos.set(name, new project_info_1.ProjectInfo(name, node.data.root, node.data.tags ?? []));
+    }
+    return infos;
+}
+/**
+ * Enrich every graph entry in place with framework, shortDescription,
+ * responsibilitiesFile and designFile. Throws MetadataValidationError listing
+ * every problem when any project fails validation.
+ */
+function enrichGraph(graph, infos, workspaceRoot) {
+    const problems = [];
+    for (const [projectName, entry] of Object.entries(graph)) {
+        const info = infos.get(projectName);
+        if (!info) {
+            problems.push(`${projectName}: not found in nx project graph`);
+            continue;
+        }
+        const resolution = (0, framework_resolver_1.resolveFramework)(info, workspaceRoot);
+        if (resolution.problem !== null) {
+            problems.push(resolution.problem);
+        }
+        else if (resolution.framework !== null) {
+            entry.framework = resolution.framework;
+        }
+        enrichResponsibilities(entry, info, workspaceRoot, problems);
+        // Only project.json projects get a generated design.json (see di-graph-targets.ts)
+        if (fs.existsSync(path.join(workspaceRoot, info.root, 'project.json'))) {
+            entry.designFile = toRepoRelative(info.root, 'design.json');
+        }
+    }
+    if (problems.length > 0) {
+        throw new MetadataValidationError(problems);
+    }
+}
+function enrichResponsibilities(entry, info, workspaceRoot, problems) {
+    const responsibilitiesFile = toRepoRelative(info.root, exports.RESPONSIBILITIES_FILE_NAME);
+    entry.responsibilitiesFile = responsibilitiesFile;
+    const absolutePath = path.join(workspaceRoot, info.root, exports.RESPONSIBILITIES_FILE_NAME);
+    if (!fs.existsSync(absolutePath)) {
+        problems.push(`${info.name}: missing required ${responsibilitiesFile} — create it with a heading, ` +
+            `one short summary paragraph, then the full responsibilities of the module`);
+        return;
+    }
+    const summary = (0, responsibilities_1.extractShortDescription)(fs.readFileSync(absolutePath, 'utf-8'));
+    const summaryProblem = (0, responsibilities_1.validateShortDescription)(summary, responsibilitiesFile);
+    if (summaryProblem !== null) {
+        problems.push(`${info.name}: ${summaryProblem}`);
+        return;
+    }
+    entry.shortDescription = summary;
+}
+/**
+ * Repo-relative path with forward slashes (stable across platforms in the
+ * committed JSON).
+ */
+function toRepoRelative(projectRoot, fileName) {
+    return [projectRoot.replace(/\\/g, '/').replace(/\/+$/, ''), fileName].join('/');
+}
+//# sourceMappingURL=graph-metadata.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph-metadata.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-metadata.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Metadata Enrichment\n *\n * Fills the AI-oriented fields on each architecture/dependencies.json entry:\n *   framework            — from `framework:<x>` nx tag or package.json inference\n *   shortDescription     — first paragraph of the project's responsibilities.md\n *   responsibilitiesFile — repo-relative path to the required responsibilities.md\n *   designFile           — repo-relative path to the generated DI design.json\n *\n * Validation is aggregated: ALL problems across ALL projects are collected and\n * thrown as one MetadataValidationError so a repo adopting this sees the full\n * seeding list in a single run. Callers must enrich BEFORE writing any file so\n * a failed run never clobbers dependencies.json.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { createProjectGraphAsync } from '@nx/devkit';\nimport type { EnhancedGraph } from './graph-sorter';\nimport { ProjectInfo } from './project-info';\nimport { resolveFramework } from './framework-resolver';\nimport { extractShortDescription, validateShortDescription } from './responsibilities';\n\nexport const RESPONSIBILITIES_FILE_NAME = 'responsibilities.md';\n\n/**\n * Thrown when one or more projects fail metadata validation (missing/invalid\n * responsibilities.md, bad framework tags, ...). Executors catch this to point\n * AI at the webpieces.responsibilities.md instructions template.\n */\nexport class MetadataValidationError extends Error {\n    constructor(public readonly problems: string[]) {\n        super(\n            `Architecture metadata validation failed (${problems.length} problem(s)):\\n` +\n                problems.map((problem: string) => `  - ${problem}`).join('\\n')\n        );\n        this.name = 'MetadataValidationError';\n    }\n}\n\n/**\n * Read per-project root + tags from nx's project graph.\n */\nexport async function collectProjectInfo(): Promise<Map<string, ProjectInfo>> {\n    const projectGraph = await createProjectGraphAsync();\n    const infos = new Map<string, ProjectInfo>();\n    for (const [name, node] of Object.entries(projectGraph.nodes)) {\n        infos.set(name, new ProjectInfo(name, node.data.root, node.data.tags ?? []));\n    }\n    return infos;\n}\n\n/**\n * Enrich every graph entry in place with framework, shortDescription,\n * responsibilitiesFile and designFile. Throws MetadataValidationError listing\n * every problem when any project fails validation.\n */\nexport function enrichGraph(\n    graph: EnhancedGraph,\n    infos: Map<string, ProjectInfo>,\n    workspaceRoot: string\n): void {\n    const problems: string[] = [];\n\n    for (const [projectName, entry] of Object.entries(graph)) {\n        const info = infos.get(projectName);\n        if (!info) {\n            problems.push(`${projectName}: not found in nx project graph`);\n            continue;\n        }\n\n        const resolution = resolveFramework(info, workspaceRoot);\n        if (resolution.problem !== null) {\n            problems.push(resolution.problem);\n        } else if (resolution.framework !== null) {\n            entry.framework = resolution.framework;\n        }\n\n        enrichResponsibilities(entry, info, workspaceRoot, problems);\n\n        // Only project.json projects get a generated design.json (see di-graph-targets.ts)\n        if (fs.existsSync(path.join(workspaceRoot, info.root, 'project.json'))) {\n            entry.designFile = toRepoRelative(info.root, 'design.json');\n        }\n    }\n\n    if (problems.length > 0) {\n        throw new MetadataValidationError(problems);\n    }\n}\n\nfunction enrichResponsibilities(\n    entry: EnhancedGraph[string],\n    info: ProjectInfo,\n    workspaceRoot: string,\n    problems: string[]\n): void {\n    const responsibilitiesFile = toRepoRelative(info.root, RESPONSIBILITIES_FILE_NAME);\n    entry.responsibilitiesFile = responsibilitiesFile;\n\n    const absolutePath = path.join(workspaceRoot, info.root, RESPONSIBILITIES_FILE_NAME);\n    if (!fs.existsSync(absolutePath)) {\n        problems.push(\n            `${info.name}: missing required ${responsibilitiesFile} — create it with a heading, ` +\n                `one short summary paragraph, then the full responsibilities of the module`\n        );\n        return;\n    }\n\n    const summary = extractShortDescription(fs.readFileSync(absolutePath, 'utf-8'));\n    const summaryProblem = validateShortDescription(summary, responsibilitiesFile);\n    if (summaryProblem !== null) {\n        problems.push(`${info.name}: ${summaryProblem}`);\n        return;\n    }\n    entry.shortDescription = summary;\n}\n\n/**\n * Repo-relative path with forward slashes (stable across platforms in the\n * committed JSON).\n */\nfunction toRepoRelative(projectRoot: string, fileName: string): string {\n    return [projectRoot.replace(/\\\\/g, '/').replace(/\\/+$/, ''), fileName].join('/');\n}\n"]}

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

@@ -7,11 +7,21 @@
  * 3. Group projects into layers for deterministic ordering
  */
 /**
- * Graph entry with level metadata
+ * Graph entry with level metadata plus AI-oriented metadata filled in by
+ * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:
+ *  - framework: angular | react | express | all-ts | ... (nx tag or inferred)
+ *  - shortDescription: summary extracted from the project's responsibilities.md
+ *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc
+ *  - designFile: repo-relative path to the generated DI design.json (only for
+ *    project.json projects)
  */
 export interface GraphEntry {
     level: number;
     dependsOn: string[];
+    framework?: string;
+    shortDescription?: string;
+    responsibilitiesFile?: string;
+    designFile?: string;
 }
 /**
  * Enhanced graph format with level information

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

@@ -1 +1 @@
-{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-sorter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Graph Sorter\n *\n * Performs topological sorting on the dependency graph to:\n * 1. Detect circular dependencies (fails if cycle found)\n * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)\n * 3. Group projects into layers for deterministic ordering\n */\n\n/**\n * Graph entry with level metadata\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n}\n\n/**\n * Enhanced graph format with level information\n */\nexport type EnhancedGraph = Record<string, GraphEntry>;\n\n/**\n * Compute topological layers for dependency graph using Kahn's algorithm\n *\n * Projects are grouped into layers where each layer only depends on previous layers.\n * Throws an error if a circular dependency is detected.\n *\n * @param graph - Dependency graph { project: [deps] }\n * @returns Array of layers, each containing sorted project names\n */\nexport function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {\n    const layers: string[][] = [];\n    const processed = new Set<string>();\n    const allProjects = Object.keys(graph);\n\n    while (processed.size < allProjects.length) {\n        const currentLayer: string[] = [];\n\n        for (const project of allProjects) {\n            if (processed.has(project)) continue;\n\n            const deps = graph[project] || [];\n            // Check if all dependencies are in previous layers (already processed)\n            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));\n\n            if (allDepsInPrevLayers) {\n                currentLayer.push(project);\n            }\n        }\n\n        if (currentLayer.length === 0) {\n            // No progress made = circular dependency detected\n            const remaining = allProjects.filter((p) => !processed.has(p));\n\n            // Try to identify the cycle\n            const cycleInfo = findCycle(graph, remaining);\n\n            throw new Error(\n                `Circular dependency detected among: ${remaining.join(', ')}\\n` +\n                    (cycleInfo ? `Cycle: ${cycleInfo}\\n` : '') +\n                    'Fix: Remove one of the dependencies to break the cycle.'\n            );\n        }\n\n        // Sort alphabetically within layer for deterministic output\n        currentLayer.sort();\n        layers.push(currentLayer);\n\n        // Mark as processed\n        currentLayer.forEach((p) => processed.add(p));\n    }\n\n    return layers;\n}\n\n/**\n * Try to find and describe a cycle in the graph\n */\nfunction findCycle(graph: Record<string, string[]>, remaining: string[]): string | null {\n    const visited = new Set<string>();\n    const path: string[] = [];\n\n    function dfs(node: string): string | null {\n        if (path.includes(node)) {\n            const cycleStart = path.indexOf(node);\n            return [...path.slice(cycleStart), node].join(' -> ');\n        }\n        if (visited.has(node)) return null;\n\n        visited.add(node);\n        path.push(node);\n\n        const deps = graph[node] || [];\n        for (const dep of deps) {\n            if (remaining.includes(dep)) {\n                const result = dfs(dep);\n                if (result) return result;\n            }\n        }\n\n        path.pop();\n        return null;\n    }\n\n    for (const node of remaining) {\n        const cycle = dfs(node);\n        if (cycle) return cycle;\n    }\n\n    return null;\n}\n\n/**\n * Sort graph in topological order with alphabetical sorting within layers\n * Returns enhanced format with level metadata\n *\n * @param graph - Unsorted dependency graph { project: [deps] }\n * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }\n */\nexport function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {\n    const layers = computeTopologicalLayers(graph);\n    const result: EnhancedGraph = {};\n\n    // Add projects layer by layer (dependencies before dependents)\n    layers.forEach((layer, levelIndex) => {\n        for (const project of layer) {\n            // Already sorted alphabetically within layer\n            result[project] = {\n                level: levelIndex,\n                dependsOn: (graph[project] || []).sort(),\n            };\n        }\n    });\n\n    return result;\n}\n"]}
+{"version":3,"file":"graph-sorter.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/graph-sorter.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAkCH,4DA2CC;AA8CD,wDAgBC;AAlHD;;;;;;;;GAQG;AACH,SAAgB,wBAAwB,CAAC,KAA+B;IACpE,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEvC,OAAO,SAAS,CAAC,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC;QACzC,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,SAAS;YAErC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClC,uEAAuE;YACvE,MAAM,mBAAmB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;YAEpE,IAAI,mBAAmB,EAAE,CAAC;gBACtB,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,kDAAkD;YAClD,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAE/D,4BAA4B;YAC5B,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAE9C,MAAM,IAAI,KAAK,CACX,uCAAuC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAC3D,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1C,yDAAyD,CAChE,CAAC;QACN,CAAC;QAED,4DAA4D;QAC5D,YAAY,CAAC,IAAI,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAE1B,oBAAoB;QACpB,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,KAA+B,EAAE,SAAmB;IACnE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,SAAS,GAAG,CAAC,IAAY;QACrB,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACtC,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAEnC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACrB,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;gBACxB,IAAI,MAAM;oBAAE,OAAO,MAAM,CAAC;YAC9B,CAAC;QACL,CAAC;QAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC5B,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,KAA+B;IAClE,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,+DAA+D;IAC/D,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;QACjC,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC1B,6CAA6C;YAC7C,MAAM,CAAC,OAAO,CAAC,GAAG;gBACd,KAAK,EAAE,UAAU;gBACjB,SAAS,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;aAC3C,CAAC;QACN,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Graph Sorter\n *\n * Performs topological sorting on the dependency graph to:\n * 1. Detect circular dependencies (fails if cycle found)\n * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)\n * 3. Group projects into layers for deterministic ordering\n */\n\n/**\n * Graph entry with level metadata plus AI-oriented metadata filled in by\n * enrichGraph() (lib/graph-metadata.ts) before the graph is saved:\n *  - framework: angular | react | express | all-ts | ... (nx tag or inferred)\n *  - shortDescription: summary extracted from the project's responsibilities.md\n *  - responsibilitiesFile: repo-relative path to the FULL responsibilities doc\n *  - designFile: repo-relative path to the generated DI design.json (only for\n *    project.json projects)\n */\nexport interface GraphEntry {\n    level: number;\n    dependsOn: string[];\n    framework?: string;\n    shortDescription?: string;\n    responsibilitiesFile?: string;\n    designFile?: string;\n}\n\n/**\n * Enhanced graph format with level information\n */\nexport type EnhancedGraph = Record<string, GraphEntry>;\n\n/**\n * Compute topological layers for dependency graph using Kahn's algorithm\n *\n * Projects are grouped into layers where each layer only depends on previous layers.\n * Throws an error if a circular dependency is detected.\n *\n * @param graph - Dependency graph { project: [deps] }\n * @returns Array of layers, each containing sorted project names\n */\nexport function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {\n    const layers: string[][] = [];\n    const processed = new Set<string>();\n    const allProjects = Object.keys(graph);\n\n    while (processed.size < allProjects.length) {\n        const currentLayer: string[] = [];\n\n        for (const project of allProjects) {\n            if (processed.has(project)) continue;\n\n            const deps = graph[project] || [];\n            // Check if all dependencies are in previous layers (already processed)\n            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));\n\n            if (allDepsInPrevLayers) {\n                currentLayer.push(project);\n            }\n        }\n\n        if (currentLayer.length === 0) {\n            // No progress made = circular dependency detected\n            const remaining = allProjects.filter((p) => !processed.has(p));\n\n            // Try to identify the cycle\n            const cycleInfo = findCycle(graph, remaining);\n\n            throw new Error(\n                `Circular dependency detected among: ${remaining.join(', ')}\\n` +\n                    (cycleInfo ? `Cycle: ${cycleInfo}\\n` : '') +\n                    'Fix: Remove one of the dependencies to break the cycle.'\n            );\n        }\n\n        // Sort alphabetically within layer for deterministic output\n        currentLayer.sort();\n        layers.push(currentLayer);\n\n        // Mark as processed\n        currentLayer.forEach((p) => processed.add(p));\n    }\n\n    return layers;\n}\n\n/**\n * Try to find and describe a cycle in the graph\n */\nfunction findCycle(graph: Record<string, string[]>, remaining: string[]): string | null {\n    const visited = new Set<string>();\n    const path: string[] = [];\n\n    function dfs(node: string): string | null {\n        if (path.includes(node)) {\n            const cycleStart = path.indexOf(node);\n            return [...path.slice(cycleStart), node].join(' -> ');\n        }\n        if (visited.has(node)) return null;\n\n        visited.add(node);\n        path.push(node);\n\n        const deps = graph[node] || [];\n        for (const dep of deps) {\n            if (remaining.includes(dep)) {\n                const result = dfs(dep);\n                if (result) return result;\n            }\n        }\n\n        path.pop();\n        return null;\n    }\n\n    for (const node of remaining) {\n        const cycle = dfs(node);\n        if (cycle) return cycle;\n    }\n\n    return null;\n}\n\n/**\n * Sort graph in topological order with alphabetical sorting within layers\n * Returns enhanced format with level metadata\n *\n * @param graph - Unsorted dependency graph { project: [deps] }\n * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }\n */\nexport function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {\n    const layers = computeTopologicalLayers(graph);\n    const result: EnhancedGraph = {};\n\n    // Add projects layer by layer (dependencies before dependents)\n    layers.forEach((layer, levelIndex) => {\n        for (const project of layer) {\n            // Already sorted alphabetically within layer\n            result[project] = {\n                level: levelIndex,\n                dependsOn: (graph[project] || []).sort(),\n            };\n        }\n    });\n\n    return result;\n}\n"]}

package/src/lib/project-info.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Project Info
+ *
+ * Per-project metadata pulled from nx's project graph (root + tags), used to
+ * enrich architecture/dependencies.json with AI-oriented fields.
+ */
+export declare class ProjectInfo {
+    readonly name: string;
+    /** Project root, relative to the workspace root (e.g. packages/http/http-routing) */
+    readonly root: string;
+    readonly tags: string[];
+    constructor(name: string, 
+    /** Project root, relative to the workspace root (e.g. packages/http/http-routing) */
+    root: string, tags: string[]);
+}

package/src/lib/project-info.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Project Info
+ *
+ * Per-project metadata pulled from nx's project graph (root + tags), used to
+ * enrich architecture/dependencies.json with AI-oriented fields.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectInfo = void 0;
+class ProjectInfo {
+    name;
+    root;
+    tags;
+    constructor(name, 
+    /** Project root, relative to the workspace root (e.g. packages/http/http-routing) */
+    root, tags) {
+        this.name = name;
+        this.root = root;
+        this.tags = tags;
+    }
+}
+exports.ProjectInfo = ProjectInfo;
+//# sourceMappingURL=project-info.js.map

package/src/lib/project-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-info.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/project-info.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,MAAa,WAAW;IAEA;IAEA;IACA;IAJpB,YACoB,IAAY;IAC5B,qFAAqF;IACrE,IAAY,EACZ,IAAc;QAHd,SAAI,GAAJ,IAAI,CAAQ;QAEZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAU;IAC/B,CAAC;CACP;AAPD,kCAOC","sourcesContent":["/**\n * Project Info\n *\n * Per-project metadata pulled from nx's project graph (root + tags), used to\n * enrich architecture/dependencies.json with AI-oriented fields.\n */\n\nexport class ProjectInfo {\n    constructor(\n        public readonly name: string,\n        /** Project root, relative to the workspace root (e.g. packages/http/http-routing) */\n        public readonly root: string,\n        public readonly tags: string[]\n    ) {}\n}\n"]}

package/src/lib/responsibilities.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Responsibilities Extraction
+ *
+ * Every project must have a human-authored `responsibilities.md` at its root
+ * describing the FULL responsibilities of the module (what belongs in it and
+ * what does not). The first paragraph of that file is embedded into
+ * architecture/dependencies.json as the project's `shortDescription` so AI
+ * gets a summary just by reading the graph file.
+ */
+/**
+ * Maximum length of the shortDescription embedded in dependencies.json.
+ * The summary must stay small — full detail belongs in responsibilities.md.
+ */
+export declare const MAX_SHORT_DESCRIPTION_LENGTH = 300;
+/**
+ * Extract the shortDescription from responsibilities.md content:
+ * the first non-empty paragraph after any leading markdown headings,
+ * with newlines collapsed to single spaces.
+ *
+ * Returns '' when the file has no summary paragraph.
+ */
+export declare function extractShortDescription(markdown: string): string;
+/**
+ * Validate an extracted shortDescription. Returns a problem description,
+ * or null when the summary is valid.
+ */
+export declare function validateShortDescription(summary: string, sourceFile: string): string | null;

package/src/lib/responsibilities.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Responsibilities Extraction
+ *
+ * Every project must have a human-authored `responsibilities.md` at its root
+ * describing the FULL responsibilities of the module (what belongs in it and
+ * what does not). The first paragraph of that file is embedded into
+ * architecture/dependencies.json as the project's `shortDescription` so AI
+ * gets a summary just by reading the graph file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SHORT_DESCRIPTION_LENGTH = void 0;
+exports.extractShortDescription = extractShortDescription;
+exports.validateShortDescription = validateShortDescription;
+/**
+ * Maximum length of the shortDescription embedded in dependencies.json.
+ * The summary must stay small — full detail belongs in responsibilities.md.
+ */
+exports.MAX_SHORT_DESCRIPTION_LENGTH = 300;
+/**
+ * Extract the shortDescription from responsibilities.md content:
+ * the first non-empty paragraph after any leading markdown headings,
+ * with newlines collapsed to single spaces.
+ *
+ * Returns '' when the file has no summary paragraph.
+ */
+function extractShortDescription(markdown) {
+    const lines = markdown.split('\n');
+    const paragraph = [];
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith('#')) {
+            // Blank line or heading ends the paragraph once started;
+            // before that, keep scanning for the first paragraph.
+            if (paragraph.length > 0)
+                break;
+            continue;
+        }
+        paragraph.push(line);
+    }
+    return paragraph.join(' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Validate an extracted shortDescription. Returns a problem description,
+ * or null when the summary is valid.
+ */
+function validateShortDescription(summary, sourceFile) {
+    if (summary.length === 0) {
+        return (`${sourceFile} has no summary paragraph. ` +
+            `Start the file with a heading, then ONE short paragraph ` +
+            `(max ${exports.MAX_SHORT_DESCRIPTION_LENGTH} chars) summarizing the module.`);
+    }
+    if (summary.length > exports.MAX_SHORT_DESCRIPTION_LENGTH) {
+        return (`${sourceFile} summary paragraph is ${summary.length} chars ` +
+            `(max ${exports.MAX_SHORT_DESCRIPTION_LENGTH}). Shorten the first paragraph; ` +
+            `move detail into later sections of the file.`);
+    }
+    return null;
+}
+//# sourceMappingURL=responsibilities.js.map

package/src/lib/responsibilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responsibilities.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/responsibilities.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAeH,0DAkBC;AAMD,4DAgBC;AArDD;;;GAGG;AACU,QAAA,4BAA4B,GAAG,GAAG,CAAC;AAEhD;;;;;;GAMG;AACH,SAAgB,uBAAuB,CAAC,QAAgB;IACpD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAE5B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5C,yDAAyD;YACzD,sDAAsD;YACtD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM;YAChC,SAAS;QACb,CAAC;QAED,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,OAAe,EAAE,UAAkB;IACxE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,CACH,GAAG,UAAU,6BAA6B;YAC1C,0DAA0D;YAC1D,QAAQ,oCAA4B,iCAAiC,CACxE,CAAC;IACN,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,oCAA4B,EAAE,CAAC;QAChD,OAAO,CACH,GAAG,UAAU,yBAAyB,OAAO,CAAC,MAAM,SAAS;YAC7D,QAAQ,oCAA4B,kCAAkC;YACtE,8CAA8C,CACjD,CAAC;IACN,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Responsibilities Extraction\n *\n * Every project must have a human-authored `responsibilities.md` at its root\n * describing the FULL responsibilities of the module (what belongs in it and\n * what does not). The first paragraph of that file is embedded into\n * architecture/dependencies.json as the project's `shortDescription` so AI\n * gets a summary just by reading the graph file.\n */\n\n/**\n * Maximum length of the shortDescription embedded in dependencies.json.\n * The summary must stay small — full detail belongs in responsibilities.md.\n */\nexport const MAX_SHORT_DESCRIPTION_LENGTH = 300;\n\n/**\n * Extract the shortDescription from responsibilities.md content:\n * the first non-empty paragraph after any leading markdown headings,\n * with newlines collapsed to single spaces.\n *\n * Returns '' when the file has no summary paragraph.\n */\nexport function extractShortDescription(markdown: string): string {\n    const lines = markdown.split('\\n');\n    const paragraph: string[] = [];\n\n    for (const rawLine of lines) {\n        const line = rawLine.trim();\n\n        if (line.length === 0 || line.startsWith('#')) {\n            // Blank line or heading ends the paragraph once started;\n            // before that, keep scanning for the first paragraph.\n            if (paragraph.length > 0) break;\n            continue;\n        }\n\n        paragraph.push(line);\n    }\n\n    return paragraph.join(' ').replace(/\\s+/g, ' ').trim();\n}\n\n/**\n * Validate an extracted shortDescription. Returns a problem description,\n * or null when the summary is valid.\n */\nexport function validateShortDescription(summary: string, sourceFile: string): string | null {\n    if (summary.length === 0) {\n        return (\n            `${sourceFile} has no summary paragraph. ` +\n            `Start the file with a heading, then ONE short paragraph ` +\n            `(max ${MAX_SHORT_DESCRIPTION_LENGTH} chars) summarizing the module.`\n        );\n    }\n    if (summary.length > MAX_SHORT_DESCRIPTION_LENGTH) {\n        return (\n            `${sourceFile} summary paragraph is ${summary.length} chars ` +\n            `(max ${MAX_SHORT_DESCRIPTION_LENGTH}). Shorten the first paragraph; ` +\n            `move detail into later sections of the file.`\n        );\n    }\n    return null;\n}\n"]}