@webpieces/dev-config 0.2.17 → 0.2.21

package/architecture/executors/validate-no-skiplevel-deps/executor.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Validate No Skip-Level Dependencies Executor
+ *
+ * Validates that no project has redundant transitive dependencies.
+ * If project A depends on B, and B transitively brings in C, then A should NOT
+ * also directly depend on C (it's redundant and clutters the dependency graph).
+ *
+ * This keeps the architecture graph clean for visualization and human understanding.
+ *
+ * Usage:
+ * nx run architecture:validate-no-skiplevel-deps
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = runExecutor;
+const tslib_1 = require("tslib");
+const graph_generator_1 = require("../../lib/graph-generator");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const TRANSITIVE_DEPS_DOC = `# AI Agent Instructions: Redundant Transitive Dependency Violation
+
+**READ THIS FILE FIRST before making any changes!**
+
+## Why This Rule Exists
+
+This rule keeps the architecture dependency graph **CLEAN and SIMPLE**.
+
+When you run \`npx nx run architecture:visualize\`, it generates a visual diagram of all
+package dependencies. Without this rule, you end up with a tangled mess of 100+ lines
+where everything depends on everything - making it impossible to understand.
+
+**Clean graphs = easier understanding for humans AND AI agents.**
+
+## Understanding the Error
+
+You have a **redundant transitive dependency**. This means:
+
+1. Project A directly depends on Project C
+2. BUT Project A also depends on Project B
+3. AND Project B already brings in Project C (transitively)
+
+Therefore, Project A's direct dependency on C is **redundant** - it's already available
+through B. This extra line clutters the dependency graph.
+
+**Example:**
+\`\`\`
+http-server depends on: [http-routing, http-filters, core-util]
+                                         ^^^^^^^^^    ^^^^^^^^
+                                         REDUNDANT!   REDUNDANT!
+
+Why? Because http-routing already brings in:
+  - http-filters (direct)
+  - core-util (via http-api)
+\`\`\`
+
+## How to Fix
+
+### Step 1: Identify the Redundant Dependency
+
+Look at the error message. It tells you:
+- Which project has the problem
+- Which dependency is redundant
+- Which other dependency already brings it in
+
+### Step 2: Remove from project.json
+
+Remove the redundant dependency from \`build.dependsOn\`:
+
+\`\`\`json
+{
+  "targets": {
+    "build": {
+      "dependsOn": [
+        "^build",
+        "http-routing:build"
+        // REMOVE: "http-filters:build"  <-- redundant, http-routing brings it in
+        // REMOVE: "core-util:build"     <-- redundant, http-routing brings it in
+      ]
+    }
+  }
+}
+\`\`\`
+
+### Step 3: Remove from package.json
+
+Remove the redundant dependency from \`dependencies\`:
+
+\`\`\`json
+{
+  "dependencies": {
+    "@webpieces/http-routing": "*"
+    // REMOVE: "@webpieces/http-filters": "*"  <-- redundant
+    // REMOVE: "@webpieces/core-util": "*"     <-- redundant
+  }
+}
+\`\`\`
+
+### Step 4: Regenerate Architecture
+
+\`\`\`bash
+npx nx run architecture:generate
+\`\`\`
+
+### Step 5: Verify
+
+\`\`\`bash
+npm run build-all
+\`\`\`
+
+## Important Notes
+
+- You DON'T lose access to the transitive dependency - it's still available through the parent
+- This is about keeping the DECLARED dependencies minimal and clean
+- The actual runtime/compile behavior is unchanged
+- TypeScript will still find the types through the transitive path
+
+## Remember
+
+- Fewer lines in the graph = easier to understand
+- Only declare what you DIRECTLY need that isn't already transitively available
+- When in doubt, check with \`npx nx run architecture:visualize\`
+`;
+/**
+ * Compute all transitive dependencies for a project
+ */
+function computeTransitiveDeps(project, graph, visited = new Set()) {
+    const result = new Set();
+    if (visited.has(project)) {
+        return result;
+    }
+    visited.add(project);
+    const directDeps = graph[project] || [];
+    for (const dep of directDeps) {
+        result.add(dep);
+        // Recursively get transitive deps
+        const transitive = computeTransitiveDeps(dep, graph, visited);
+        for (const t of transitive) {
+            result.add(t);
+        }
+    }
+    return result;
+}
+/**
+ * Find redundant dependencies for a project
+ */
+function findRedundantDeps(project, graph) {
+    const redundant = [];
+    const directDeps = graph[project] || [];
+    // For each direct dependency, compute what it transitively brings in
+    const transitiveByDep = new Map();
+    for (const dep of directDeps) {
+        transitiveByDep.set(dep, computeTransitiveDeps(dep, graph));
+    }
+    // Check if any direct dependency is already brought in by another
+    for (const dep of directDeps) {
+        for (const [otherDep, otherTransitive] of transitiveByDep) {
+            if (otherDep !== dep && otherTransitive.has(dep)) {
+                redundant.push({
+                    project,
+                    redundantDep: dep,
+                    alreadyBroughtInBy: otherDep,
+                });
+                break; // Only report once per redundant dep
+            }
+        }
+    }
+    return redundant;
+}
+/**
+ * Write documentation file when violations are found
+ */
+function writeDocFile(workspaceRoot) {
+    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.transitivedeps.md');
+    const docDir = path.dirname(docPath);
+    try {
+        fs.mkdirSync(docDir, { recursive: true });
+        fs.writeFileSync(docPath, TRANSITIVE_DEPS_DOC, 'utf-8');
+    }
+    catch (err) {
+        void err;
+        console.warn(`Could not write documentation file: ${docPath}`);
+    }
+}
+async function runExecutor(_options, context) {
+    console.log('\n🔄 Validating No Skip-Level Dependencies\n');
+    try {
+        // Step 1: Generate current graph from project.json files
+        console.log('📊 Generating dependency graph from project.json files...');
+        const graph = await (0, graph_generator_1.generateGraph)();
+        // Step 2: Find all redundant dependencies
+        console.log('🔍 Checking for redundant transitive dependencies...');
+        const allRedundant = [];
+        for (const project of Object.keys(graph)) {
+            const redundant = findRedundantDeps(project, graph);
+            allRedundant.push(...redundant);
+        }
+        if (allRedundant.length === 0) {
+            console.log('✅ No redundant transitive dependencies detected!');
+            console.log('\n📈 Graph is clean and minimal.');
+            return { success: true };
+        }
+        // Write documentation file
+        const workspaceRoot = context.root || process.cwd();
+        writeDocFile(workspaceRoot);
+        // Report violations
+        console.error('\n❌ Redundant transitive dependencies detected!\n');
+        console.error('⚠️  AI Agent: READ tmp/webpieces/webpieces.transitivedeps.md for fix instructions!\n');
+        for (const r of allRedundant) {
+            console.error(`  ${r.project}:`);
+            console.error(`    └─ "${r.redundantDep}" is REDUNDANT`);
+            console.error(`       (already brought in by "${r.alreadyBroughtInBy}")\n`);
+        }
+        console.error('\nTo fix:');
+        console.error('  1. READ tmp/webpieces/webpieces.transitivedeps.md');
+        console.error('  2. Remove redundant deps from project.json build.dependsOn');
+        console.error('  3. Remove redundant deps from package.json dependencies');
+        console.error('  4. Run: npx nx run architecture:generate');
+        console.error('  5. Run: npm run build-all');
+        return { success: false };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error('❌ Skip-level validation failed:', error.message);
+        return { success: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/architecture/executors/validate-no-skiplevel-deps/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/dev-config/architecture/executors/validate-no-skiplevel-deps/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate No Skip-Level Dependencies Executor\n *\n * Validates that no project has redundant transitive dependencies.\n * If project A depends on B, and B transitively brings in C, then A should NOT\n * also directly depend on C (it's redundant and clutters the dependency graph).\n *\n * This keeps the architecture graph clean for visualization and human understanding.\n *\n * Usage:\n * nx run architecture:validate-no-skiplevel-deps\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { generateGraph } from '../../lib/graph-generator';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\nexport interface ValidateNoSkipLevelDepsOptions {\n    // No options needed\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\ninterface RedundantDep {\n    project: string;\n    redundantDep: string;\n    alreadyBroughtInBy: string;\n}\n\nconst TRANSITIVE_DEPS_DOC = `# AI Agent Instructions: Redundant Transitive Dependency Violation\n\n**READ THIS FILE FIRST before making any changes!**\n\n## Why This Rule Exists\n\nThis rule keeps the architecture dependency graph **CLEAN and SIMPLE**.\n\nWhen you run \\`npx nx run architecture:visualize\\`, it generates a visual diagram of all\npackage dependencies. Without this rule, you end up with a tangled mess of 100+ lines\nwhere everything depends on everything - making it impossible to understand.\n\n**Clean graphs = easier understanding for humans AND AI agents.**\n\n## Understanding the Error\n\nYou have a **redundant transitive dependency**. This means:\n\n1. Project A directly depends on Project C\n2. BUT Project A also depends on Project B\n3. AND Project B already brings in Project C (transitively)\n\nTherefore, Project A's direct dependency on C is **redundant** - it's already available\nthrough B. This extra line clutters the dependency graph.\n\n**Example:**\n\\`\\`\\`\nhttp-server depends on: [http-routing, http-filters, core-util]\n                                         ^^^^^^^^^    ^^^^^^^^\n                                         REDUNDANT!   REDUNDANT!\n\nWhy? Because http-routing already brings in:\n  - http-filters (direct)\n  - core-util (via http-api)\n\\`\\`\\`\n\n## How to Fix\n\n### Step 1: Identify the Redundant Dependency\n\nLook at the error message. It tells you:\n- Which project has the problem\n- Which dependency is redundant\n- Which other dependency already brings it in\n\n### Step 2: Remove from project.json\n\nRemove the redundant dependency from \\`build.dependsOn\\`:\n\n\\`\\`\\`json\n{\n  \"targets\": {\n    \"build\": {\n      \"dependsOn\": [\n        \"^build\",\n        \"http-routing:build\"\n        // REMOVE: \"http-filters:build\"  <-- redundant, http-routing brings it in\n        // REMOVE: \"core-util:build\"     <-- redundant, http-routing brings it in\n      ]\n    }\n  }\n}\n\\`\\`\\`\n\n### Step 3: Remove from package.json\n\nRemove the redundant dependency from \\`dependencies\\`:\n\n\\`\\`\\`json\n{\n  \"dependencies\": {\n    \"@webpieces/http-routing\": \"*\"\n    // REMOVE: \"@webpieces/http-filters\": \"*\"  <-- redundant\n    // REMOVE: \"@webpieces/core-util\": \"*\"     <-- redundant\n  }\n}\n\\`\\`\\`\n\n### Step 4: Regenerate Architecture\n\n\\`\\`\\`bash\nnpx nx run architecture:generate\n\\`\\`\\`\n\n### Step 5: Verify\n\n\\`\\`\\`bash\nnpm run build-all\n\\`\\`\\`\n\n## Important Notes\n\n- You DON'T lose access to the transitive dependency - it's still available through the parent\n- This is about keeping the DECLARED dependencies minimal and clean\n- The actual runtime/compile behavior is unchanged\n- TypeScript will still find the types through the transitive path\n\n## Remember\n\n- Fewer lines in the graph = easier to understand\n- Only declare what you DIRECTLY need that isn't already transitively available\n- When in doubt, check with \\`npx nx run architecture:visualize\\`\n`;\n\n/**\n * Compute all transitive dependencies for a project\n */\nfunction computeTransitiveDeps(\n    project: string,\n    graph: Record<string, string[]>,\n    visited: Set<string> = new Set()\n): Set<string> {\n    const result = new Set<string>();\n\n    if (visited.has(project)) {\n        return result;\n    }\n    visited.add(project);\n\n    const directDeps = graph[project] || [];\n    for (const dep of directDeps) {\n        result.add(dep);\n        // Recursively get transitive deps\n        const transitive = computeTransitiveDeps(dep, graph, visited);\n        for (const t of transitive) {\n            result.add(t);\n        }\n    }\n\n    return result;\n}\n\n/**\n * Find redundant dependencies for a project\n */\nfunction findRedundantDeps(\n    project: string,\n    graph: Record<string, string[]>\n): RedundantDep[] {\n    const redundant: RedundantDep[] = [];\n    const directDeps = graph[project] || [];\n\n    // For each direct dependency, compute what it transitively brings in\n    const transitiveByDep = new Map<string, Set<string>>();\n    for (const dep of directDeps) {\n        transitiveByDep.set(dep, computeTransitiveDeps(dep, graph));\n    }\n\n    // Check if any direct dependency is already brought in by another\n    for (const dep of directDeps) {\n        for (const [otherDep, otherTransitive] of transitiveByDep) {\n            if (otherDep !== dep && otherTransitive.has(dep)) {\n                redundant.push({\n                    project,\n                    redundantDep: dep,\n                    alreadyBroughtInBy: otherDep,\n                });\n                break; // Only report once per redundant dep\n            }\n        }\n    }\n\n    return redundant;\n}\n\n/**\n * Write documentation file when violations are found\n */\nfunction writeDocFile(workspaceRoot: string): void {\n    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.transitivedeps.md');\n    const docDir = path.dirname(docPath);\n\n    try {\n        fs.mkdirSync(docDir, { recursive: true });\n        fs.writeFileSync(docPath, TRANSITIVE_DEPS_DOC, 'utf-8');\n    } catch (err: any) {\n        void err;\n        console.warn(`Could not write documentation file: ${docPath}`);\n    }\n}\n\nexport default async function runExecutor(\n    _options: ValidateNoSkipLevelDepsOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    console.log('\\n🔄 Validating No Skip-Level Dependencies\\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 graph = await generateGraph();\n\n        // Step 2: Find all redundant dependencies\n        console.log('🔍 Checking for redundant transitive dependencies...');\n        const allRedundant: RedundantDep[] = [];\n\n        for (const project of Object.keys(graph)) {\n            const redundant = findRedundantDeps(project, graph);\n            allRedundant.push(...redundant);\n        }\n\n        if (allRedundant.length === 0) {\n            console.log('✅ No redundant transitive dependencies detected!');\n            console.log('\\n📈 Graph is clean and minimal.');\n            return { success: true };\n        }\n\n        // Write documentation file\n        const workspaceRoot = context.root || process.cwd();\n        writeDocFile(workspaceRoot);\n\n        // Report violations\n        console.error('\\n❌ Redundant transitive dependencies detected!\\n');\n        console.error('⚠️  AI Agent: READ tmp/webpieces/webpieces.transitivedeps.md for fix instructions!\\n');\n\n        for (const r of allRedundant) {\n            console.error(`  ${r.project}:`);\n            console.error(`    └─ \"${r.redundantDep}\" is REDUNDANT`);\n            console.error(`       (already brought in by \"${r.alreadyBroughtInBy}\")\\n`);\n        }\n\n        console.error('\\nTo fix:');\n        console.error('  1. READ tmp/webpieces/webpieces.transitivedeps.md');\n        console.error('  2. Remove redundant deps from project.json build.dependsOn');\n        console.error('  3. Remove redundant deps from package.json dependencies');\n        console.error('  4. Run: npx nx run architecture:generate');\n        console.error('  5. Run: npm run build-all');\n\n        return { success: false };\n    } catch (err: any) {\n        const error = err instanceof Error ? err : new Error(String(err));\n        console.error('❌ Skip-level validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/architecture/executors/validate-no-skiplevel-deps/executor.ts

@@ -0,0 +1,267 @@
+/**
+ * Validate No Skip-Level Dependencies Executor
+ *
+ * Validates that no project has redundant transitive dependencies.
+ * If project A depends on B, and B transitively brings in C, then A should NOT
+ * also directly depend on C (it's redundant and clutters the dependency graph).
+ *
+ * This keeps the architecture graph clean for visualization and human understanding.
+ *
+ * Usage:
+ * nx run architecture:validate-no-skiplevel-deps
+ */
+
+import type { ExecutorContext } from '@nx/devkit';
+import { generateGraph } from '../../lib/graph-generator';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface ValidateNoSkipLevelDepsOptions {
+    // No options needed
+}
+
+export interface ExecutorResult {
+    success: boolean;
+}
+
+interface RedundantDep {
+    project: string;
+    redundantDep: string;
+    alreadyBroughtInBy: string;
+}
+
+const TRANSITIVE_DEPS_DOC = `# AI Agent Instructions: Redundant Transitive Dependency Violation
+
+**READ THIS FILE FIRST before making any changes!**
+
+## Why This Rule Exists
+
+This rule keeps the architecture dependency graph **CLEAN and SIMPLE**.
+
+When you run \`npx nx run architecture:visualize\`, it generates a visual diagram of all
+package dependencies. Without this rule, you end up with a tangled mess of 100+ lines
+where everything depends on everything - making it impossible to understand.
+
+**Clean graphs = easier understanding for humans AND AI agents.**
+
+## Understanding the Error
+
+You have a **redundant transitive dependency**. This means:
+
+1. Project A directly depends on Project C
+2. BUT Project A also depends on Project B
+3. AND Project B already brings in Project C (transitively)
+
+Therefore, Project A's direct dependency on C is **redundant** - it's already available
+through B. This extra line clutters the dependency graph.
+
+**Example:**
+\`\`\`
+http-server depends on: [http-routing, http-filters, core-util]
+                                         ^^^^^^^^^    ^^^^^^^^
+                                         REDUNDANT!   REDUNDANT!
+
+Why? Because http-routing already brings in:
+  - http-filters (direct)
+  - core-util (via http-api)
+\`\`\`
+
+## How to Fix
+
+### Step 1: Identify the Redundant Dependency
+
+Look at the error message. It tells you:
+- Which project has the problem
+- Which dependency is redundant
+- Which other dependency already brings it in
+
+### Step 2: Remove from project.json
+
+Remove the redundant dependency from \`build.dependsOn\`:
+
+\`\`\`json
+{
+  "targets": {
+    "build": {
+      "dependsOn": [
+        "^build",
+        "http-routing:build"
+        // REMOVE: "http-filters:build"  <-- redundant, http-routing brings it in
+        // REMOVE: "core-util:build"     <-- redundant, http-routing brings it in
+      ]
+    }
+  }
+}
+\`\`\`
+
+### Step 3: Remove from package.json
+
+Remove the redundant dependency from \`dependencies\`:
+
+\`\`\`json
+{
+  "dependencies": {
+    "@webpieces/http-routing": "*"
+    // REMOVE: "@webpieces/http-filters": "*"  <-- redundant
+    // REMOVE: "@webpieces/core-util": "*"     <-- redundant
+  }
+}
+\`\`\`
+
+### Step 4: Regenerate Architecture
+
+\`\`\`bash
+npx nx run architecture:generate
+\`\`\`
+
+### Step 5: Verify
+
+\`\`\`bash
+npm run build-all
+\`\`\`
+
+## Important Notes
+
+- You DON'T lose access to the transitive dependency - it's still available through the parent
+- This is about keeping the DECLARED dependencies minimal and clean
+- The actual runtime/compile behavior is unchanged
+- TypeScript will still find the types through the transitive path
+
+## Remember
+
+- Fewer lines in the graph = easier to understand
+- Only declare what you DIRECTLY need that isn't already transitively available
+- When in doubt, check with \`npx nx run architecture:visualize\`
+`;
+
+/**
+ * Compute all transitive dependencies for a project
+ */
+function computeTransitiveDeps(
+    project: string,
+    graph: Record<string, string[]>,
+    visited: Set<string> = new Set()
+): Set<string> {
+    const result = new Set<string>();
+
+    if (visited.has(project)) {
+        return result;
+    }
+    visited.add(project);
+
+    const directDeps = graph[project] || [];
+    for (const dep of directDeps) {
+        result.add(dep);
+        // Recursively get transitive deps
+        const transitive = computeTransitiveDeps(dep, graph, visited);
+        for (const t of transitive) {
+            result.add(t);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Find redundant dependencies for a project
+ */
+function findRedundantDeps(
+    project: string,
+    graph: Record<string, string[]>
+): RedundantDep[] {
+    const redundant: RedundantDep[] = [];
+    const directDeps = graph[project] || [];
+
+    // For each direct dependency, compute what it transitively brings in
+    const transitiveByDep = new Map<string, Set<string>>();
+    for (const dep of directDeps) {
+        transitiveByDep.set(dep, computeTransitiveDeps(dep, graph));
+    }
+
+    // Check if any direct dependency is already brought in by another
+    for (const dep of directDeps) {
+        for (const [otherDep, otherTransitive] of transitiveByDep) {
+            if (otherDep !== dep && otherTransitive.has(dep)) {
+                redundant.push({
+                    project,
+                    redundantDep: dep,
+                    alreadyBroughtInBy: otherDep,
+                });
+                break; // Only report once per redundant dep
+            }
+        }
+    }
+
+    return redundant;
+}
+
+/**
+ * Write documentation file when violations are found
+ */
+function writeDocFile(workspaceRoot: string): void {
+    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.transitivedeps.md');
+    const docDir = path.dirname(docPath);
+
+    try {
+        fs.mkdirSync(docDir, { recursive: true });
+        fs.writeFileSync(docPath, TRANSITIVE_DEPS_DOC, 'utf-8');
+    } catch (err: any) {
+        void err;
+        console.warn(`Could not write documentation file: ${docPath}`);
+    }
+}
+
+export default async function runExecutor(
+    _options: ValidateNoSkipLevelDepsOptions,
+    context: ExecutorContext
+): Promise<ExecutorResult> {
+    console.log('\n🔄 Validating No Skip-Level Dependencies\n');
+
+    try {
+        // Step 1: Generate current graph from project.json files
+        console.log('📊 Generating dependency graph from project.json files...');
+        const graph = await generateGraph();
+
+        // Step 2: Find all redundant dependencies
+        console.log('🔍 Checking for redundant transitive dependencies...');
+        const allRedundant: RedundantDep[] = [];
+
+        for (const project of Object.keys(graph)) {
+            const redundant = findRedundantDeps(project, graph);
+            allRedundant.push(...redundant);
+        }
+
+        if (allRedundant.length === 0) {
+            console.log('✅ No redundant transitive dependencies detected!');
+            console.log('\n📈 Graph is clean and minimal.');
+            return { success: true };
+        }
+
+        // Write documentation file
+        const workspaceRoot = context.root || process.cwd();
+        writeDocFile(workspaceRoot);
+
+        // Report violations
+        console.error('\n❌ Redundant transitive dependencies detected!\n');
+        console.error('⚠️  AI Agent: READ tmp/webpieces/webpieces.transitivedeps.md for fix instructions!\n');
+
+        for (const r of allRedundant) {
+            console.error(`  ${r.project}:`);
+            console.error(`    └─ "${r.redundantDep}" is REDUNDANT`);
+            console.error(`       (already brought in by "${r.alreadyBroughtInBy}")\n`);
+        }
+
+        console.error('\nTo fix:');
+        console.error('  1. READ tmp/webpieces/webpieces.transitivedeps.md');
+        console.error('  2. Remove redundant deps from project.json build.dependsOn');
+        console.error('  3. Remove redundant deps from package.json dependencies');
+        console.error('  4. Run: npx nx run architecture:generate');
+        console.error('  5. Run: npm run build-all');
+
+        return { success: false };
+    } catch (err: any) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error('❌ Skip-level validation failed:', error.message);
+        return { success: false };
+    }
+}

package/architecture/executors/validate-no-skiplevel-deps/schema.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate No Skip-Level Dependencies Executor",
+    "description": "Validates that no project has redundant transitive dependencies",
+    "type": "object",
+    "properties": {},
+    "required": []
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Visualize Executor
+ *
+ * Generates visual representations of the architecture graph (DOT + HTML)
+ * and opens the visualization in a browser.
+ *
+ * Usage:
+ * nx run architecture:visualize
+ */
+import type { ExecutorContext } from '@nx/devkit';
+export interface VisualizeExecutorOptions {
+    graphPath?: string;
+}
+export interface ExecutorResult {
+    success: boolean;
+}
+export default function runExecutor(options: VisualizeExecutorOptions, context: ExecutorContext): Promise<ExecutorResult>;

package/architecture/executors/visualize/executor.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Visualize Executor
+ *
+ * Generates visual representations of the architecture graph (DOT + HTML)
+ * and opens the visualization in a browser.
+ *
+ * Usage:
+ * nx run architecture:visualize
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = runExecutor;
+const graph_loader_1 = require("../../lib/graph-loader");
+const graph_visualizer_1 = require("../../lib/graph-visualizer");
+async function runExecutor(options, context) {
+    const { graphPath } = options;
+    const workspaceRoot = context.root;
+    console.log('\n🎨 Architecture Visualization\n');
+    try {
+        // Load the saved graph
+        console.log('📂 Loading saved graph...');
+        const graph = (0, graph_loader_1.loadBlessedGraph)(workspaceRoot, graphPath);
+        if (!graph) {
+            console.error('❌ No saved graph found at architecture/dependencies.json');
+            console.error('   Run: nx run architecture:generate first');
+            return { success: false };
+        }
+        // Generate visualization
+        console.log('🎨 Generating visualization...');
+        const { dotPath, htmlPath } = (0, graph_visualizer_1.writeVisualization)(graph, workspaceRoot);
+        console.log(`✅ Generated: ${dotPath}`);
+        console.log(`✅ Generated: ${htmlPath}`);
+        // Try to open in browser
+        console.log('\n🌐 Opening visualization in browser...');
+        if ((0, graph_visualizer_1.openVisualization)(htmlPath)) {
+            console.log('✅ Browser opened');
+        }
+        else {
+            console.log(`⚠️  Could not auto-open. Open manually: ${htmlPath}`);
+        }
+        return { success: true };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error('❌ Visualization failed:', error.message);
+        return { success: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/dev-config/architecture/executors/visualize/executor.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAcH,8BAwCC;AAnDD,yDAA0D;AAC1D,iEAAmF;AAUpE,KAAK,UAAU,WAAW,CACrC,OAAiC,EACjC,OAAwB;IAExB,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAC9B,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IAEjD,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,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAA,qCAAkB,EAAC,KAAK,EAAE,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,GAAG,CAAC,gBAAgB,OAAO,EAAE,CAAC,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,gBAAgB,QAAQ,EAAE,CAAC,CAAC;QAExC,yBAAyB;QACzB,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;QACxD,IAAI,IAAA,oCAAiB,EAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,GAAG,CAAC,2CAA2C,QAAQ,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,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,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';\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;\n    const workspaceRoot = context.root;\n\n    console.log('\\n🎨 Architecture Visualization\\n');\n\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 { dotPath, htmlPath } = writeVisualization(graph, workspaceRoot);\n        console.log(`✅ Generated: ${dotPath}`);\n        console.log(`✅ Generated: ${htmlPath}`);\n\n        // Try to open in browser\n        console.log('\\n🌐 Opening visualization in browser...');\n        if (openVisualization(htmlPath)) {\n            console.log('✅ Browser opened');\n        } else {\n            console.log(`⚠️  Could not auto-open. Open manually: ${htmlPath}`);\n        }\n\n        return { success: true };\n    } catch (err: unknown) {\n        const error = err instanceof Error ? err : new Error(String(err));\n        console.error('❌ Visualization failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/architecture/executors/visualize/executor.ts

@@ -0,0 +1,63 @@
+/**
+ * Visualize Executor
+ *
+ * Generates visual representations of the architecture graph (DOT + HTML)
+ * and opens the visualization in a browser.
+ *
+ * Usage:
+ * nx run architecture:visualize
+ */
+
+import type { ExecutorContext } from '@nx/devkit';
+import { loadBlessedGraph } from '../../lib/graph-loader';
+import { writeVisualization, openVisualization } from '../../lib/graph-visualizer';
+
+export interface VisualizeExecutorOptions {
+    graphPath?: string;
+}
+
+export interface ExecutorResult {
+    success: boolean;
+}
+
+export default async function runExecutor(
+    options: VisualizeExecutorOptions,
+    context: ExecutorContext
+): Promise<ExecutorResult> {
+    const { graphPath } = options;
+    const workspaceRoot = context.root;
+
+    console.log('\n🎨 Architecture Visualization\n');
+
+    try {
+        // Load the saved graph
+        console.log('📂 Loading saved graph...');
+        const graph = loadBlessedGraph(workspaceRoot, graphPath);
+
+        if (!graph) {
+            console.error('❌ No saved graph found at architecture/dependencies.json');
+            console.error('   Run: nx run architecture:generate first');
+            return { success: false };
+        }
+
+        // Generate visualization
+        console.log('🎨 Generating visualization...');
+        const { dotPath, htmlPath } = writeVisualization(graph, workspaceRoot);
+        console.log(`✅ Generated: ${dotPath}`);
+        console.log(`✅ Generated: ${htmlPath}`);
+
+        // Try to open in browser
+        console.log('\n🌐 Opening visualization in browser...');
+        if (openVisualization(htmlPath)) {
+            console.log('✅ Browser opened');
+        } else {
+            console.log(`⚠️  Could not auto-open. Open manually: ${htmlPath}`);
+        }
+
+        return { success: true };
+    } catch (err: unknown) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error('❌ Visualization failed:', error.message);
+        return { success: false };
+    }
+}