@webpieces/dev-config 0.2.38 → 0.2.40

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

@@ -10,10 +10,164 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = runExecutor;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
 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 TMP_DIR = 'tmp/webpieces';
+const TMP_MD_FILE = 'webpieces.dependencies.md';
+const DEPENDENCIES_DOC_CONTENT = `# Instructions: Architecture Dependency Violation
+
+IN GENERAL, it is better to avoid these changes and find a different way by moving classes
+around to existing packages you already depend on. It is not always avoidable though.
+A clean dependency graph keeps you out of huge trouble later.
+
+If you are a human, simply run these commands:
+* nx run architecture:visualize - to see the new dependencies and validate that change is desired
+* nx run architecture:generate - updates the dep graph
+* git diff architecture/dependencies.json - to see the deps changes you made
+
+**READ THIS FILE FIRST before making any changes!**
+
+## ⚠️ CRITICAL WARNING ⚠️
+
+**This is a VERY IMPORTANT change that has LARGE REPERCUSSIONS later!**
+
+Adding new dependencies creates technical debt that compounds over time:
+- Creates coupling between packages that may be hard to undo
+- Can create circular dependency tangles
+- Makes packages harder to test in isolation
+- Increases build times and bundle sizes
+- May force unnecessary upgrades across the codebase
+
+**DO NOT add dependencies without senior developer approval!**
+
+## Understanding the Error
+
+You've attempted to import from a package that is not in your project's allowed dependencies.
+The architecture enforces a layered dependency structure where:
+- Level 0 packages are foundation packages with NO dependencies on other @webpieces packages
+- Higher level packages can only depend on lower level packages
+- All dependencies must be explicitly declared
+
+## Steps to Resolve
+
+### Step 1: Generate Current Dependency Graph
+Run this command to see the current architecture:
+\`\`\`bash
+npx nx run architecture:generate
+\`\`\`
+This creates/updates \`architecture/dependencies.json\` showing all packages and their levels.
+
+### Step 2: Analyze the Proposed Change
+Ask yourself:
+1. **Is this import truly necessary?** Can you refactor to avoid it?
+2. **Should the code move instead?** Maybe the code belongs in a different package.
+3. **Will this create a cycle?** Use \`npx nx graph\` to visualize dependencies.
+4. **Can you use an interface/abstraction?** Define interface in lower-level package, implement in higher-level.
+
+### Step 3: Get Senior Developer Approval
+
+## 🛑 AI AGENTS: STOP HERE AND ASK FOR HUMAN APPROVAL! 🛑
+
+**YOU MUST NOT PROCEED TO STEP 4 WITHOUT EXPLICIT HUMAN APPROVAL!**
+
+**REQUIRED**: Discuss this architectural change with a senior developer before proceeding.
+- Explain why the dependency is needed
+- Show you've considered alternatives (Step 2)
+- **WAIT for explicit approval before making ANY changes to project.json or package.json**
+
+**AI Agent Instructions:**
+1. Present your analysis from Step 2 to the human
+2. Explain which package needs which dependency and why
+3. ASK: "Do you approve adding this dependency?"
+4. **DO NOT modify project.json or package.json until you receive explicit "yes" or approval**
+
+### Step 4: If Approved, Add the Dependency
+
+## ⛔ NEVER MODIFY THESE FILES WITHOUT HUMAN APPROVAL FROM STEP 3! ⛔
+
+Only after receiving explicit human approval in Step 3, make these changes:
+
+1. **Update project.json** - Add to \`build.dependsOn\`:
+   \`\`\`json
+   {
+     "targets": {
+       "build": {
+         "dependsOn": ["^build", "dep1:build", "NEW_PACKAGE:build"]
+       }
+     }
+   }
+   \`\`\`
+
+2. **Update package.json** - Add to \`dependencies\`:
+   \`\`\`json
+   {
+     "dependencies": {
+       "@webpieces/NEW_PACKAGE": "*"
+     }
+   }
+   \`\`\`
+
+### Step 5: Update Architecture Definition
+Run this command to validate and update the architecture:
+\`\`\`bash
+npx nx run architecture:generate
+\`\`\`
+
+This will:
+- Detect any cycles (which MUST be fixed before proceeding)
+- Update \`architecture/dependencies.json\` with the new dependency
+- Recalculate package levels
+
+### Step 6: Verify No Cycles
+\`\`\`bash
+npx nx run architecture:validate-no-cycles
+\`\`\`
+
+If cycles are detected, you MUST refactor to break the cycle. Common strategies:
+- Move shared code to a lower-level package
+- Use dependency inversion (interfaces in low-level, implementations in high-level)
+- Restructure package boundaries
+
+## Alternative Solutions (Preferred over adding dependencies)
+
+### Option A: Move the Code
+If you need functionality from another package, consider moving that code to a shared lower-level package.
+
+### Option B: Dependency Inversion
+Define an interface in the lower-level package, implement it in the higher-level package:
+\`\`\`typescript
+// In foundation package (level 0)
+export interface Logger { log(msg: string): void; }
+
+// In higher-level package
+export class ConsoleLogger implements Logger { ... }
+\`\`\`
+
+### Option C: Pass Dependencies as Parameters
+Instead of importing, receive the dependency as a constructor or method parameter.
+
+## Remember
+- Every dependency you add today is technical debt for tomorrow
+- The best dependency is the one you don't need
+- When in doubt, refactor rather than add dependencies
+`;
+/**
+ * Write the instructions documentation to tmp directory
+ */
+function writeTmpInstructionsFile(workspaceRoot) {
+    const tmpDir = path.join(workspaceRoot, TMP_DIR);
+    const mdPath = path.join(tmpDir, TMP_MD_FILE);
+    // Ensure tmp directory exists
+    fs.mkdirSync(tmpDir, { recursive: true });
+    // Write documentation MD file
+    fs.writeFileSync(mdPath, DEPENDENCIES_DOC_CONTENT);
+    return mdPath;
+}
 async function runExecutor(options, context) {
     const { graphPath } = options;
     const workspaceRoot = context.root;
@@ -22,7 +176,12 @@ async function runExecutor(options, context) {
         // Check if saved graph exists
         if (!(0, graph_loader_1.graphFileExists)(workspaceRoot, graphPath)) {
             console.error('❌ No saved graph found at architecture/dependencies.json');
-            console.error('   Run: nx run architecture:generate first');
+            console.error('');
+            console.error('To initialize:');
+            console.error('  1. Run: nx run architecture:generate');
+            console.error('  2. Run: nx run architecture:visualize');
+            console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');
+            console.error('  4. Commit architecture/dependencies.json');
             return { success: false };
         }
         // Step 1: Generate current graph from project.json files
@@ -46,10 +205,15 @@ async function runExecutor(options, context) {
             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('\nTo fix:');
+            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');

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

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/dev-config/architecture/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAgBH,8BAwDC;AArED,+DAA0D;AAC1D,yDAAgE;AAChE,iEAA2D;AAC3D,yDAA2E;AAU5D,KAAK,UAAU,WAAW,CACrC,OAA6C,EAC7C,OAAwB;IAExB,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAC9B,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;IAExD,IAAI,CAAC;QACD,8BAA8B;QAC9B,IAAI,CAAC,IAAA,8BAAe,EAAC,aAAa,EAAE,SAAS,CAAC,EAAE,CAAC;YAC7C,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,yDAAyD;QACzD,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;QACzD,MAAM,QAAQ,GAAG,MAAM,IAAA,+BAAa,GAAE,CAAC;QAEvC,+DAA+D;QAC/D,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,IAAA,qCAAsB,EAAC,QAAQ,CAAC,CAAC;QAEtD,2BAA2B;QAC3B,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,IAAA,+BAAgB,EAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QAE9D,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAC9C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;QAED,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,8CAA8C,CAAC,CAAC;QAC5D,MAAM,UAAU,GAAG,IAAA,gCAAa,EAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAE3D,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;YAC5E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;YAC/D,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;YAChC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YAClC,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;YAC/C,OAAO,CAAC,KAAK,CAAC,oGAAoG,CAAC,CAAC;YACpH,OAAO,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;YACxE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC9B,CAAC;IACL,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAClE,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAClE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","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 { generateGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const { graphPath } = options;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\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('   Run: nx run architecture:generate first');\n            return { success: false };\n        }\n\n        // Step 1: Generate current graph from project.json files\n        console.log('📊 Generating current dependency graph...');\n        const rawGraph = await generateGraph();\n\n        // Step 2: Topological sort (to get enhanced graph with levels)\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(rawGraph);\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            console.error('❌ Architecture has changed since last update!');\n            console.error('\\nDifferences:');\n            console.error(comparison.summary);\n            console.error('\\nTo 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 = err instanceof Error ? err : new Error(String(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/dev-config/architecture/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 * as fs from 'fs';\nimport * as path from 'path';\nimport { generateGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { compareGraphs } from '../../lib/graph-comparator';\nimport { loadBlessedGraph, graphFileExists } from '../../lib/graph-loader';\n\nexport interface ValidateArchitectureUnchangedOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nconst TMP_DIR = 'tmp/webpieces';\nconst TMP_MD_FILE = 'webpieces.dependencies.md';\n\nconst DEPENDENCIES_DOC_CONTENT = `# Instructions: Architecture Dependency Violation\n\nIN GENERAL, it is better to avoid these changes and find a different way by moving classes\naround to existing packages you already depend on. It is not always avoidable though.\nA clean dependency graph keeps you out of huge trouble later.\n\nIf you are a human, simply run these commands:\n* nx run architecture:visualize - to see the new dependencies and validate that change is desired\n* nx run architecture:generate - updates the dep graph\n* git diff architecture/dependencies.json - to see the deps changes you made\n\n**READ THIS FILE FIRST before making any changes!**\n\n## ⚠️ CRITICAL WARNING ⚠️\n\n**This is a VERY IMPORTANT change that has LARGE REPERCUSSIONS later!**\n\nAdding new dependencies creates technical debt that compounds over time:\n- Creates coupling between packages that may be hard to undo\n- Can create circular dependency tangles\n- Makes packages harder to test in isolation\n- Increases build times and bundle sizes\n- May force unnecessary upgrades across the codebase\n\n**DO NOT add dependencies without senior developer approval!**\n\n## Understanding the Error\n\nYou've attempted to import from a package that is not in your project's allowed dependencies.\nThe architecture enforces a layered dependency structure where:\n- Level 0 packages are foundation packages with NO dependencies on other @webpieces packages\n- Higher level packages can only depend on lower level packages\n- All dependencies must be explicitly declared\n\n## Steps to Resolve\n\n### Step 1: Generate Current Dependency Graph\nRun this command to see the current architecture:\n\\`\\`\\`bash\nnpx nx run architecture:generate\n\\`\\`\\`\nThis creates/updates \\`architecture/dependencies.json\\` showing all packages and their levels.\n\n### Step 2: Analyze the Proposed Change\nAsk yourself:\n1. **Is this import truly necessary?** Can you refactor to avoid it?\n2. **Should the code move instead?** Maybe the code belongs in a different package.\n3. **Will this create a cycle?** Use \\`npx nx graph\\` to visualize dependencies.\n4. **Can you use an interface/abstraction?** Define interface in lower-level package, implement in higher-level.\n\n### Step 3: Get Senior Developer Approval\n\n## 🛑 AI AGENTS: STOP HERE AND ASK FOR HUMAN APPROVAL! 🛑\n\n**YOU MUST NOT PROCEED TO STEP 4 WITHOUT EXPLICIT HUMAN APPROVAL!**\n\n**REQUIRED**: Discuss this architectural change with a senior developer before proceeding.\n- Explain why the dependency is needed\n- Show you've considered alternatives (Step 2)\n- **WAIT for explicit approval before making ANY changes to project.json or package.json**\n\n**AI Agent Instructions:**\n1. Present your analysis from Step 2 to the human\n2. Explain which package needs which dependency and why\n3. ASK: \"Do you approve adding this dependency?\"\n4. **DO NOT modify project.json or package.json until you receive explicit \"yes\" or approval**\n\n### Step 4: If Approved, Add the Dependency\n\n## ⛔ NEVER MODIFY THESE FILES WITHOUT HUMAN APPROVAL FROM STEP 3! ⛔\n\nOnly after receiving explicit human approval in Step 3, make these changes:\n\n1. **Update project.json** - Add to \\`build.dependsOn\\`:\n   \\`\\`\\`json\n   {\n     \"targets\": {\n       \"build\": {\n         \"dependsOn\": [\"^build\", \"dep1:build\", \"NEW_PACKAGE:build\"]\n       }\n     }\n   }\n   \\`\\`\\`\n\n2. **Update package.json** - Add to \\`dependencies\\`:\n   \\`\\`\\`json\n   {\n     \"dependencies\": {\n       \"@webpieces/NEW_PACKAGE\": \"*\"\n     }\n   }\n   \\`\\`\\`\n\n### Step 5: Update Architecture Definition\nRun this command to validate and update the architecture:\n\\`\\`\\`bash\nnpx nx run architecture:generate\n\\`\\`\\`\n\nThis will:\n- Detect any cycles (which MUST be fixed before proceeding)\n- Update \\`architecture/dependencies.json\\` with the new dependency\n- Recalculate package levels\n\n### Step 6: Verify No Cycles\n\\`\\`\\`bash\nnpx nx run architecture:validate-no-cycles\n\\`\\`\\`\n\nIf cycles are detected, you MUST refactor to break the cycle. Common strategies:\n- Move shared code to a lower-level package\n- Use dependency inversion (interfaces in low-level, implementations in high-level)\n- Restructure package boundaries\n\n## Alternative Solutions (Preferred over adding dependencies)\n\n### Option A: Move the Code\nIf you need functionality from another package, consider moving that code to a shared lower-level package.\n\n### Option B: Dependency Inversion\nDefine an interface in the lower-level package, implement it in the higher-level package:\n\\`\\`\\`typescript\n// In foundation package (level 0)\nexport interface Logger { log(msg: string): void; }\n\n// In higher-level package\nexport class ConsoleLogger implements Logger { ... }\n\\`\\`\\`\n\n### Option C: Pass Dependencies as Parameters\nInstead of importing, receive the dependency as a constructor or method parameter.\n\n## Remember\n- Every dependency you add today is technical debt for tomorrow\n- The best dependency is the one you don't need\n- When in doubt, refactor rather than add dependencies\n`;\n\n/**\n * Write the instructions documentation to tmp directory\n */\nfunction writeTmpInstructionsFile(workspaceRoot: string): string {\n    const tmpDir = path.join(workspaceRoot, TMP_DIR);\n    const mdPath = path.join(tmpDir, TMP_MD_FILE);\n\n    // Ensure tmp directory exists\n    fs.mkdirSync(tmpDir, { recursive: true });\n\n    // Write documentation MD file\n    fs.writeFileSync(mdPath, DEPENDENCIES_DOC_CONTENT);\n\n    return mdPath;\n}\n\nexport default async function runExecutor(\n    options: ValidateArchitectureUnchangedOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const { graphPath } = options;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🔍 Validating Architecture Unchanged\\n');\n\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: Generate current graph from project.json files\n        console.log('📊 Generating current dependency graph...');\n        const rawGraph = await generateGraph();\n\n        // Step 2: Topological sort (to get enhanced graph with levels)\n        console.log('🔄 Computing topological layers...');\n        const currentGraph = sortGraphTopologically(rawGraph);\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 = err instanceof Error ? err : new Error(String(err));\n        console.error('❌ Architecture validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/architecture/executors/validate-architecture-unchanged/executor.ts

@@ -9,6 +9,8 @@
  */
 
 import type { ExecutorContext } from '@nx/devkit';
+import * as fs from 'fs';
+import * as path from 'path';
 import { generateGraph } from '../../lib/graph-generator';
 import { sortGraphTopologically } from '../../lib/graph-sorter';
 import { compareGraphs } from '../../lib/graph-comparator';
@@ -22,6 +24,163 @@ export interface ExecutorResult {
     success: boolean;
 }
 
+const TMP_DIR = 'tmp/webpieces';
+const TMP_MD_FILE = 'webpieces.dependencies.md';
+
+const DEPENDENCIES_DOC_CONTENT = `# Instructions: Architecture Dependency Violation
+
+IN GENERAL, it is better to avoid these changes and find a different way by moving classes
+around to existing packages you already depend on. It is not always avoidable though.
+A clean dependency graph keeps you out of huge trouble later.
+
+If you are a human, simply run these commands:
+* nx run architecture:visualize - to see the new dependencies and validate that change is desired
+* nx run architecture:generate - updates the dep graph
+* git diff architecture/dependencies.json - to see the deps changes you made
+
+**READ THIS FILE FIRST before making any changes!**
+
+## ⚠️ CRITICAL WARNING ⚠️
+
+**This is a VERY IMPORTANT change that has LARGE REPERCUSSIONS later!**
+
+Adding new dependencies creates technical debt that compounds over time:
+- Creates coupling between packages that may be hard to undo
+- Can create circular dependency tangles
+- Makes packages harder to test in isolation
+- Increases build times and bundle sizes
+- May force unnecessary upgrades across the codebase
+
+**DO NOT add dependencies without senior developer approval!**
+
+## Understanding the Error
+
+You've attempted to import from a package that is not in your project's allowed dependencies.
+The architecture enforces a layered dependency structure where:
+- Level 0 packages are foundation packages with NO dependencies on other @webpieces packages
+- Higher level packages can only depend on lower level packages
+- All dependencies must be explicitly declared
+
+## Steps to Resolve
+
+### Step 1: Generate Current Dependency Graph
+Run this command to see the current architecture:
+\`\`\`bash
+npx nx run architecture:generate
+\`\`\`
+This creates/updates \`architecture/dependencies.json\` showing all packages and their levels.
+
+### Step 2: Analyze the Proposed Change
+Ask yourself:
+1. **Is this import truly necessary?** Can you refactor to avoid it?
+2. **Should the code move instead?** Maybe the code belongs in a different package.
+3. **Will this create a cycle?** Use \`npx nx graph\` to visualize dependencies.
+4. **Can you use an interface/abstraction?** Define interface in lower-level package, implement in higher-level.
+
+### Step 3: Get Senior Developer Approval
+
+## 🛑 AI AGENTS: STOP HERE AND ASK FOR HUMAN APPROVAL! 🛑
+
+**YOU MUST NOT PROCEED TO STEP 4 WITHOUT EXPLICIT HUMAN APPROVAL!**
+
+**REQUIRED**: Discuss this architectural change with a senior developer before proceeding.
+- Explain why the dependency is needed
+- Show you've considered alternatives (Step 2)
+- **WAIT for explicit approval before making ANY changes to project.json or package.json**
+
+**AI Agent Instructions:**
+1. Present your analysis from Step 2 to the human
+2. Explain which package needs which dependency and why
+3. ASK: "Do you approve adding this dependency?"
+4. **DO NOT modify project.json or package.json until you receive explicit "yes" or approval**
+
+### Step 4: If Approved, Add the Dependency
+
+## ⛔ NEVER MODIFY THESE FILES WITHOUT HUMAN APPROVAL FROM STEP 3! ⛔
+
+Only after receiving explicit human approval in Step 3, make these changes:
+
+1. **Update project.json** - Add to \`build.dependsOn\`:
+   \`\`\`json
+   {
+     "targets": {
+       "build": {
+         "dependsOn": ["^build", "dep1:build", "NEW_PACKAGE:build"]
+       }
+     }
+   }
+   \`\`\`
+
+2. **Update package.json** - Add to \`dependencies\`:
+   \`\`\`json
+   {
+     "dependencies": {
+       "@webpieces/NEW_PACKAGE": "*"
+     }
+   }
+   \`\`\`
+
+### Step 5: Update Architecture Definition
+Run this command to validate and update the architecture:
+\`\`\`bash
+npx nx run architecture:generate
+\`\`\`
+
+This will:
+- Detect any cycles (which MUST be fixed before proceeding)
+- Update \`architecture/dependencies.json\` with the new dependency
+- Recalculate package levels
+
+### Step 6: Verify No Cycles
+\`\`\`bash
+npx nx run architecture:validate-no-cycles
+\`\`\`
+
+If cycles are detected, you MUST refactor to break the cycle. Common strategies:
+- Move shared code to a lower-level package
+- Use dependency inversion (interfaces in low-level, implementations in high-level)
+- Restructure package boundaries
+
+## Alternative Solutions (Preferred over adding dependencies)
+
+### Option A: Move the Code
+If you need functionality from another package, consider moving that code to a shared lower-level package.
+
+### Option B: Dependency Inversion
+Define an interface in the lower-level package, implement it in the higher-level package:
+\`\`\`typescript
+// In foundation package (level 0)
+export interface Logger { log(msg: string): void; }
+
+// In higher-level package
+export class ConsoleLogger implements Logger { ... }
+\`\`\`
+
+### Option C: Pass Dependencies as Parameters
+Instead of importing, receive the dependency as a constructor or method parameter.
+
+## Remember
+- Every dependency you add today is technical debt for tomorrow
+- The best dependency is the one you don't need
+- When in doubt, refactor rather than add dependencies
+`;
+
+/**
+ * Write the instructions documentation to tmp directory
+ */
+function writeTmpInstructionsFile(workspaceRoot: string): string {
+    const tmpDir = path.join(workspaceRoot, TMP_DIR);
+    const mdPath = path.join(tmpDir, TMP_MD_FILE);
+
+    // Ensure tmp directory exists
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    // Write documentation MD file
+    fs.writeFileSync(mdPath, DEPENDENCIES_DOC_CONTENT);
+
+    return mdPath;
+}
+
 export default async function runExecutor(
     options: ValidateArchitectureUnchangedOptions,
     context: ExecutorContext
@@ -35,7 +194,12 @@ export default async function runExecutor(
         // Check if saved graph exists
         if (!graphFileExists(workspaceRoot, graphPath)) {
             console.error('❌ No saved graph found at architecture/dependencies.json');
-            console.error('   Run: nx run architecture:generate first');
+            console.error('');
+            console.error('To initialize:');
+            console.error('  1. Run: nx run architecture:generate');
+            console.error('  2. Run: nx run architecture:visualize');
+            console.error('  3. Manually inspect the generated graph to confirm it is the desired architecture');
+            console.error('  4. Commit architecture/dependencies.json');
             return { success: false };
         }
 
@@ -64,10 +228,16 @@ export default async function runExecutor(
             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('\nTo fix:');
+            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');

package/architecture/executors/validate-new-methods/executor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validate New Methods Executor
+ *
+ * Validates that newly added methods don't exceed a maximum line count.
+ * Only runs when NX_BASE environment variable is set (affected mode).
+ *
+ * This validator encourages writing methods that read like a "table of contents"
+ * where each method call describes a larger piece of work.
+ *
+ * Usage:
+ * nx affected --target=validate-new-methods --base=origin/main
+ *
+ * Escape hatch: Add eslint-disable comment with justification
+ */
+import type { ExecutorContext } from '@nx/devkit';
+export interface ValidateNewMethodsOptions {
+    max?: number;
+}
+export interface ExecutorResult {
+    success: boolean;
+}
+export default function runExecutor(options: ValidateNewMethodsOptions, context: ExecutorContext): Promise<ExecutorResult>;