@webpieces/dev-config 0.2.94 → 0.2.97

package/architecture/executors/diff-utils.ts

@@ -1,127 +0,0 @@
-/**
- * Shared diff utility functions for executor validators.
- * These are used by multiple executors for git diff parsing and line-level detection.
- */
-
-import { execSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-
-/**
- * Get the diff content for a specific file.
- */
-export function getFileDiff(workspaceRoot: string, file: string, base: string, head?: string): string {
-    try {
-        const diffTarget = head ? `${base} ${head}` : base;
-        const diff = execSync(`git diff ${diffTarget} -- "${file}"`, {
-            cwd: workspaceRoot,
-            encoding: 'utf-8',
-        });
-
-        if (!diff && !head) {
-            const fullPath = path.join(workspaceRoot, file);
-            if (fs.existsSync(fullPath)) {
-                const isUntracked = execSync(`git ls-files --others --exclude-standard "${file}"`, {
-                    cwd: workspaceRoot,
-                    encoding: 'utf-8',
-                }).trim();
-
-                if (isUntracked) {
-                    const content = fs.readFileSync(fullPath, 'utf-8');
-                    const lines = content.split('\n');
-                    return lines.map((line) => `+${line}`).join('\n');
-                }
-            }
-        }
-
-        return diff;
-    } catch {
-        return '';
-    }
-}
-
-/**
- * Parse diff to extract changed line numbers (additions only - lines starting with +).
- */
-export function getChangedLineNumbers(diffContent: string): Set<number> {
-    const changedLines = new Set<number>();
-    const lines = diffContent.split('\n');
-    let currentLine = 0;
-
-    for (const line of lines) {
-        const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
-        if (hunkMatch) {
-            currentLine = parseInt(hunkMatch[1], 10);
-            continue;
-        }
-
-        if (line.startsWith('+') && !line.startsWith('+++')) {
-            changedLines.add(currentLine);
-            currentLine++;
-        } else if (line.startsWith('-') && !line.startsWith('---')) {
-            // Deletions don't increment line number
-        } else {
-            currentLine++;
-        }
-    }
-
-    return changedLines;
-}
-
-/**
- * Parse diff to find newly added method signatures.
- */
-export function findNewMethodSignaturesInDiff(diffContent: string): Set<string> {
-    const newMethods = new Set<string>();
-    const lines = diffContent.split('\n');
-
-    const patterns = [
-        /^\+\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/,
-        /^\+\s*(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\(/,
-        /^\+\s*(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:async\s+)?function/,
-        /^\+\s*(?:(?:public|private|protected)\s+)?(?:static\s+)?(?:async\s+)?(\w+)\s*\(/,
-    ];
-
-    for (const line of lines) {
-        if (line.startsWith('+') && !line.startsWith('+++')) {
-            for (const pattern of patterns) {
-                const match = line.match(pattern);
-                if (match) {
-                    const methodName = match[1];
-                    if (methodName && !['if', 'for', 'while', 'switch', 'catch', 'constructor'].includes(methodName)) {
-                        newMethods.add(methodName);
-                    }
-                    break;
-                }
-            }
-        }
-    }
-
-    return newMethods;
-}
-
-/**
- * Check if any line in [startLine, endLine] is in the changedLines set.
- */
-export function hasChangesInRange(startLine: number, endLine: number, changedLines: Set<number>): boolean {
-    for (let line = startLine; line <= endLine; line++) {
-        if (changedLines.has(line)) {
-            return true;
-        }
-    }
-    return false;
-}
-
-/**
- * Check if a node (method or function) is new or has changed lines in its range.
- */
-export function isNewOrModified(
-    name: string,
-    startLine: number,
-    endLine: number,
-    changedLines: Set<number>,
-    newMethodNames: Set<string>
-): boolean {
-    if (newMethodNames.has(name)) return true;
-    return hasChangesInRange(startLine, endLine, changedLines);
-}

package/architecture/executors/generate/executor.d.ts

@@ -1,16 +0,0 @@
-/**
- * Generate Executor
- *
- * Generates the architecture dependency graph and saves it to architecture/dependencies.json.
- *
- * Usage:
- * nx run architecture:generate
- */
-import type { ExecutorContext } from '@nx/devkit';
-export interface GenerateExecutorOptions {
-    graphPath?: string;
-}
-export interface ExecutorResult {
-    success: boolean;
-}
-export default function runExecutor(options: GenerateExecutorOptions, context: ExecutorContext): Promise<ExecutorResult>;

package/architecture/executors/generate/executor.js

@@ -1,44 +0,0 @@
-"use strict";
-/**
- * Generate Executor
- *
- * Generates the architecture dependency graph and saves it to architecture/dependencies.json.
- *
- * Usage:
- * nx run architecture:generate
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = runExecutor;
-const graph_generator_1 = require("../../lib/graph-generator");
-const graph_sorter_1 = require("../../lib/graph-sorter");
-const graph_loader_1 = require("../../lib/graph-loader");
-async function runExecutor(options, context) {
-    const { graphPath } = options;
-    const workspaceRoot = context.root;
-    console.log('\n📊 Architecture Graph Generator\n');
-    try {
-        // Step 1: Generate current graph from project.json files
-        console.log('📊 Generating dependency graph from project.json files...');
-        const rawGraph = await (0, graph_generator_1.generateGraph)();
-        // Step 2: Topological sort (to assign levels for visualization)
-        console.log('🔄 Computing topological layers...');
-        const enhancedGraph = (0, graph_sorter_1.sortGraphTopologically)(rawGraph);
-        // Step 3: Save the graph
-        console.log('💾 Saving graph to architecture/dependencies.json...');
-        (0, graph_loader_1.saveGraph)(enhancedGraph, workspaceRoot, graphPath);
-        console.log('✅ Graph saved successfully');
-        // Print summary
-        const projectCount = Object.keys(enhancedGraph).length;
-        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));
-        console.log(`\n📈 Graph Summary:`);
-        console.log(`   Projects: ${projectCount}`);
-        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);
-        return { success: true };
-    }
-    catch (err) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        console.error('❌ Graph generation failed:', error.message);
-        return { success: false };
-    }
-}
-//# sourceMappingURL=executor.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/dev-config/architecture/executors/generate/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAeH,8BAoCC;AAhDD,+DAA0D;AAC1D,yDAAgE;AAChE,yDAAmD;AAUpC,KAAK,UAAU,WAAW,CACrC,OAAgC,EAChC,OAAwB;IAExB,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAC9B,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;IAEnD,IAAI,CAAC;QACD,yDAAyD;QACzD,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,MAAM,IAAA,+BAAa,GAAE,CAAC;QAEvC,gEAAgE;QAChE,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;QAClD,MAAM,aAAa,GAAG,IAAA,qCAAsB,EAAC,QAAQ,CAAC,CAAC;QAEvD,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;QACpE,IAAA,wBAAS,EAAC,aAAa,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;QAE1C,gBAAgB;QAChB,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACzE,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,gBAAgB,YAAY,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,GAAG,CAAC,cAAc,MAAM,CAAC,IAAI,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAEpE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7B,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,4BAA4B,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;AACL,CAAC","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 { generateGraph } from '../../lib/graph-generator';\nimport { sortGraphTopologically } from '../../lib/graph-sorter';\nimport { saveGraph } from '../../lib/graph-loader';\n\nexport interface GenerateExecutorOptions {\n    graphPath?: string;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\nexport default async function runExecutor(\n    options: GenerateExecutorOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const { graphPath } = options;\n    const workspaceRoot = context.root;\n\n    console.log('\\n📊 Architecture Graph Generator\\n');\n\n    try {\n        // Step 1: Generate current graph from project.json files\n        console.log('📊 Generating dependency graph from project.json files...');\n        const rawGraph = await generateGraph();\n\n        // Step 2: Topological sort (to assign levels for visualization)\n        console.log('🔄 Computing topological layers...');\n        const enhancedGraph = sortGraphTopologically(rawGraph);\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        // 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 = err instanceof Error ? err : new Error(String(err));\n        console.error('❌ Graph generation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/architecture/executors/generate/executor.ts

@@ -1,59 +0,0 @@
-/**
- * Generate Executor
- *
- * Generates the architecture dependency graph and saves it to architecture/dependencies.json.
- *
- * Usage:
- * nx run architecture:generate
- */
-
-import type { ExecutorContext } from '@nx/devkit';
-import { generateGraph } from '../../lib/graph-generator';
-import { sortGraphTopologically } from '../../lib/graph-sorter';
-import { saveGraph } from '../../lib/graph-loader';
-
-export interface GenerateExecutorOptions {
-    graphPath?: string;
-}
-
-export interface ExecutorResult {
-    success: boolean;
-}
-
-export default async function runExecutor(
-    options: GenerateExecutorOptions,
-    context: ExecutorContext
-): Promise<ExecutorResult> {
-    const { graphPath } = options;
-    const workspaceRoot = context.root;
-
-    console.log('\n📊 Architecture Graph Generator\n');
-
-    try {
-        // Step 1: Generate current graph from project.json files
-        console.log('📊 Generating dependency graph from project.json files...');
-        const rawGraph = await generateGraph();
-
-        // Step 2: Topological sort (to assign levels for visualization)
-        console.log('🔄 Computing topological layers...');
-        const enhancedGraph = sortGraphTopologically(rawGraph);
-
-        // Step 3: Save the graph
-        console.log('💾 Saving graph to architecture/dependencies.json...');
-        saveGraph(enhancedGraph, workspaceRoot, graphPath);
-        console.log('✅ Graph saved successfully');
-
-        // Print summary
-        const projectCount = Object.keys(enhancedGraph).length;
-        const levels = new Set(Object.values(enhancedGraph).map((e) => e.level));
-        console.log(`\n📈 Graph Summary:`);
-        console.log(`   Projects: ${projectCount}`);
-        console.log(`   Levels: ${levels.size} (0-${Math.max(...levels)})`);
-
-        return { success: true };
-    } catch (err: unknown) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        console.error('❌ Graph generation failed:', error.message);
-        return { success: false };
-    }
-}

package/architecture/executors/generate/schema.json

@@ -1,14 +0,0 @@
-{
-    "$schema": "http://json-schema.org/schema",
-    "title": "Generate Executor",
-    "description": "Generates the architecture dependency graph and saves it",
-    "type": "object",
-    "properties": {
-        "graphPath": {
-            "type": "string",
-            "description": "Path to the graph file (relative to workspace root)",
-            "default": "architecture/dependencies.json"
-        }
-    },
-    "required": []
-}

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

@@ -1,17 +0,0 @@
-/**
- * Validate Architecture Unchanged Executor
- *
- * Validates that the current architecture graph matches the saved blessed graph.
- * This ensures no unapproved architecture changes have been made.
- *
- * Usage:
- * nx run architecture:validate-architecture-unchanged
- */
-import type { ExecutorContext } from '@nx/devkit';
-export interface ValidateArchitectureUnchangedOptions {
-    graphPath?: string;
-}
-export interface ExecutorResult {
-    success: boolean;
-}
-export default function runExecutor(options: ValidateArchitectureUnchangedOptions, context: ExecutorContext): Promise<ExecutorResult>;

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

@@ -1,229 +0,0 @@
-"use strict";
-/**
- * Validate Architecture Unchanged Executor
- *
- * Validates that the current architecture graph matches the saved blessed graph.
- * This ensures no unapproved architecture changes have been made.
- *
- * Usage:
- * nx run architecture:validate-architecture-unchanged
- */
-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-architecture-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;
-    console.log('\n🔍 Validating Architecture Unchanged\n');
-    try {
-        // 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('');
-            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
-        console.log('📊 Generating current dependency graph...');
-        const rawGraph = await (0, graph_generator_1.generateGraph)();
-        // Step 2: Topological sort (to get enhanced graph with levels)
-        console.log('🔄 Computing topological layers...');
-        const currentGraph = (0, graph_sorter_1.sortGraphTopologically)(rawGraph);
-        // Step 3: 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
-        console.log('🔍 Comparing current graph to saved graph...');
-        const comparison = (0, graph_comparator_1.compareGraphs)(currentGraph, savedGraph);
-        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 };
-        }
-    }
-    catch (err) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        console.error('❌ Architecture validation failed:', error.message);
-        return { success: false };
-    }
-}
-//# sourceMappingURL=executor.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/dev-config/architecture/executors/validate-architecture-unchanged/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA+KH,8BAmEC;;AA/OD,+CAAyB;AACzB,mDAA6B;AAC7B,+DAA0D;AAC1D,yDAAgE;AAChE,iEAA2D;AAC3D,yDAA2E;AAU3E,MAAM,OAAO,GAAG,eAAe,CAAC;AAChC,MAAM,WAAW,GAAG,2BAA2B,CAAC;AAEhD,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwIhC,CAAC;AAEF;;GAEG;AACH,SAAS,wBAAwB,CAAC,aAAqB;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAE9C,8BAA8B;IAC9B,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,8BAA8B;IAC9B,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAEnD,OAAO,MAAM,CAAC;AAClB,CAAC;AAEc,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,EAAE,CAAC,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;YAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;YACxD,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;YACzD,OAAO,CAAC,KAAK,CAAC,qFAAqF,CAAC,CAAC;YACrG,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,uCAAuC;YACvC,MAAM,MAAM,GAAG,wBAAwB,CAAC,aAAa,CAAC,CAAC;YAEvD,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,EAAE,CAAC,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,MAAM,GAAG,wCAAwC,CAAC,CAAC;YACvF,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACzB,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 * 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-architecture-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"]}