@webpieces/nx-webpieces-rules 0.0.1

package/src/executors/visualize/executor.ts

@@ -0,0 +1,65 @@
+/**
+ * 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';
+import { toError } from '../../toError';
+
+export interface VisualizeExecutorOptions {
+    graphPath?: string;
+}
+
+export interface ExecutorResult {
+    success: boolean;
+}
+
+export default async function runExecutor(
+    options: VisualizeExecutorOptions,
+    context: ExecutorContext
+): Promise<ExecutorResult> {
+    const graphPath = options.graphPath;
+    const workspaceRoot = context.root;
+
+    console.log('\n🎨 Architecture Visualization\n');
+
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    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 vizPaths = writeVisualization(graph, workspaceRoot);
+        console.log(`✅ Generated: ${vizPaths.dotPath}`);
+        console.log(`✅ Generated: ${vizPaths.htmlPath}`);
+
+        // Try to open in browser
+        console.log('\n🌐 Opening visualization in browser...');
+        if (openVisualization(vizPaths.htmlPath)) {
+            console.log('✅ Browser opened');
+        } else {
+            console.log(`⚠️  Could not auto-open. Open manually: ${vizPaths.htmlPath}`);
+        }
+
+        return { success: true };
+    } catch (err: unknown) {
+        const error = toError(err);
+        console.error('❌ Visualization failed:', error.message);
+        return { success: false };
+    }
+}

package/src/executors/visualize/schema.json

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

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './lib/graph-generator';
+export * from './lib/graph-sorter';
+export * from './lib/graph-comparator';
+export * from './lib/package-validator';
+export * from './lib/graph-loader';
+export * from './lib/graph-visualizer';
+import { createNodesV2 } from './plugin';
+export { createNodesV2 };
+export default { name: '@webpieces/nx-webpieces-rules', createNodesV2 };

package/src/lib/graph-comparator.ts

@@ -0,0 +1,154 @@
+/**
+ * Graph Comparator
+ *
+ * Compares the current generated graph with the saved (blessed) graph.
+ * Used in validate mode to ensure developers have updated the graph file.
+ */
+
+import type { EnhancedGraph } from './graph-sorter';
+
+/**
+ * Difference between two graphs
+ */
+export interface GraphDiff {
+    added: string[];
+    removed: string[];
+    modified: {
+        project: string;
+        addedDeps: string[];
+        removedDeps: string[];
+        levelChanged: { from: number; to: number } | null;
+    }[];
+}
+
+/**
+ * Comparison result
+ */
+export interface ComparisonResult {
+    identical: boolean;
+    diff: GraphDiff;
+    summary: string;
+}
+
+/**
+ * Compare two graphs and return the differences
+ *
+ * @param current - Currently generated graph
+ * @param saved - Previously saved (blessed) graph
+ * @returns Comparison result with detailed diff
+ */
+export function compareGraphs(current: EnhancedGraph, saved: EnhancedGraph): ComparisonResult {
+    const currentProjects = new Set(Object.keys(current));
+    const savedProjects = new Set(Object.keys(saved));
+
+    const diff: GraphDiff = {
+        added: [],
+        removed: [],
+        modified: [],
+    };
+
+    // Find added projects
+    for (const project of currentProjects) {
+        if (!savedProjects.has(project)) {
+            diff.added.push(project);
+        }
+    }
+
+    // Find removed projects
+    for (const project of savedProjects) {
+        if (!currentProjects.has(project)) {
+            diff.removed.push(project);
+        }
+    }
+
+    // Find modified projects
+    findModifiedProjects(current, saved, currentProjects, savedProjects, diff);
+
+    const identical =
+        diff.added.length === 0 && diff.removed.length === 0 && diff.modified.length === 0;
+
+    const summary = identical ? 'Graphs are identical' : buildSummary(diff);
+
+    return {
+        identical,
+        diff,
+        summary,
+    };
+}
+
+function findModifiedProjects(
+    current: EnhancedGraph,
+    saved: EnhancedGraph,
+    currentProjects: Set<string>,
+    savedProjects: Set<string>,
+    diff: GraphDiff
+): void {
+    for (const project of currentProjects) {
+        if (!savedProjects.has(project)) continue;
+
+        const currentEntry = current[project];
+        const savedEntry = saved[project];
+
+        const currentDeps = new Set(currentEntry.dependsOn);
+        const savedDeps = new Set(savedEntry.dependsOn);
+
+        const addedDeps: string[] = [];
+        const removedDeps: string[] = [];
+
+        for (const dep of currentDeps) {
+            if (!savedDeps.has(dep)) {
+                addedDeps.push(dep);
+            }
+        }
+
+        for (const dep of savedDeps) {
+            if (!currentDeps.has(dep)) {
+                removedDeps.push(dep);
+            }
+        }
+
+        const levelChanged =
+            currentEntry.level !== savedEntry.level
+                ? { from: savedEntry.level, to: currentEntry.level }
+                : null;
+
+        if (addedDeps.length > 0 || removedDeps.length > 0 || levelChanged) {
+            diff.modified.push({
+                project,
+                addedDeps,
+                removedDeps,
+                levelChanged,
+            });
+        }
+    }
+}
+
+function buildSummary(diff: GraphDiff): string {
+    const summaryParts: string[] = [];
+
+    if (diff.added.length > 0) {
+        summaryParts.push(`Added projects: ${diff.added.join(', ')}`);
+    }
+
+    if (diff.removed.length > 0) {
+        summaryParts.push(`Removed projects: ${diff.removed.join(', ')}`);
+    }
+
+    for (const mod of diff.modified) {
+        const parts: string[] = [];
+        if (mod.addedDeps.length > 0) {
+            parts.push(`+deps: ${mod.addedDeps.join(', ')}`);
+        }
+        if (mod.removedDeps.length > 0) {
+            parts.push(`-deps: ${mod.removedDeps.join(', ')}`);
+        }
+        if (mod.levelChanged) {
+            parts.push(`level: ${mod.levelChanged.from} -> ${mod.levelChanged.to}`);
+        }
+        if (parts.length > 0) {
+            summaryParts.push(`${mod.project}: ${parts.join('; ')}`);
+        }
+    }
+
+    return summaryParts.join('\n');
+}

package/src/lib/graph-generator.ts

@@ -0,0 +1,97 @@
+/**
+ * Graph Generator
+ *
+ * Generates dependency graph from project.json files in the workspace.
+ * Reads build.dependsOn and implicitDependencies to determine project relationships.
+ */
+
+import {
+    createProjectGraphAsync,
+    readProjectsConfigurationFromProjectGraph,
+    ProjectConfiguration,
+} from '@nx/devkit';
+
+/**
+ * Projects to exclude from graph validation (tools, configs, etc.)
+ */
+const EXCLUDED_PROJECTS = new Set<string>([]);
+
+/**
+ * Extract project dependencies from project.json's build.dependsOn and implicitDependencies
+ */
+function extractBuildDependencies(projectConfig: ProjectConfiguration): string[] {
+    const deps: string[] = [];
+
+    // 1. Read from build.dependsOn
+    const buildTarget = projectConfig.targets?.['build'];
+    if (buildTarget && buildTarget.dependsOn) {
+        for (const dep of buildTarget.dependsOn) {
+            if (typeof dep === 'string') {
+                // Format: "project-name:build" or just "build" (for self)
+                const match = dep.match(/^([^:]+):build$/);
+                if (match) {
+                    deps.push(match[1]);
+                }
+            }
+        }
+    }
+
+    // 2. Also read from implicitDependencies
+    if (projectConfig.implicitDependencies && Array.isArray(projectConfig.implicitDependencies)) {
+        for (const dep of projectConfig.implicitDependencies) {
+            if (typeof dep === 'string' && !deps.includes(dep)) {
+                deps.push(dep);
+            }
+        }
+    }
+
+    return deps.sort();
+}
+
+/**
+ * Generate raw dependency graph from project.json files
+ * Returns: { projectName: [dependencyNames] }
+ */
+export async function generateRawGraph(): Promise<Record<string, string[]>> {
+    const projectGraph = await createProjectGraphAsync();
+    const projectsConfig = readProjectsConfigurationFromProjectGraph(projectGraph);
+    const rawDeps: Record<string, string[]> = {};
+
+    for (const [projectName, projectConfig] of Object.entries(projectsConfig.projects)) {
+        // Skip excluded projects (tools, plugins)
+        if (EXCLUDED_PROJECTS.has(projectName)) {
+            continue;
+        }
+
+        // Extract dependencies from build.dependsOn in project.json
+        const deps = extractBuildDependencies(projectConfig);
+        rawDeps[projectName] = deps;
+    }
+
+    return rawDeps;
+}
+
+/**
+ * Transform project names (sorting dependencies only - no scope transformation)
+ */
+export function transformGraph(rawGraph: Record<string, string[]>): Record<string, string[]> {
+    const result: Record<string, string[]> = {};
+
+    for (const [projectName, deps] of Object.entries(rawGraph)) {
+        // Use project names as-is - don't force @webpieces scope on client projects
+        const transformedName = projectName;
+        const transformedDeps = deps.sort();
+
+        result[transformedName] = transformedDeps;
+    }
+
+    return result;
+}
+
+/**
+ * Generate complete dependency graph with transformations
+ */
+export async function generateGraph(): Promise<Record<string, string[]>> {
+    const rawGraph = await generateRawGraph();
+    return transformGraph(rawGraph);
+}

package/src/lib/graph-loader.ts

@@ -0,0 +1,119 @@
+/**
+ * Graph Loader
+ *
+ * Handles loading and saving the blessed dependency graph file.
+ * The graph is stored at architecture/dependencies.json in the workspace root.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { EnhancedGraph } from './graph-sorter';
+import { toError } from '../toError';
+
+/**
+ * Default path for the dependencies file (relative to workspace root)
+ */
+export const DEFAULT_GRAPH_PATH = 'architecture/dependencies.json';
+
+/**
+ * Load the blessed graph from disk
+ *
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ * @returns The blessed graph, or null if file doesn't exist
+ */
+export function loadBlessedGraph(
+    workspaceRoot: string,
+    graphPath: string = DEFAULT_GRAPH_PATH
+): EnhancedGraph | null {
+    const fullPath = path.join(workspaceRoot, graphPath);
+
+    if (!fs.existsSync(fullPath)) {
+        return null;
+    }
+
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        return JSON.parse(content) as EnhancedGraph;
+    } catch (err: unknown) {
+        const error = toError(err);
+        throw new Error(`Failed to load graph from ${fullPath}: ${error.message}`);
+    }
+}
+
+/**
+ * Format a graph as JSON with multi-line arrays for readability
+ */
+function formatGraphJson(graph: EnhancedGraph): string {
+    const lines: string[] = ['{'];
+    const keys = Object.keys(graph).sort();
+
+    keys.forEach((key, index) => {
+        const entry = graph[key];
+        const isLast = index === keys.length - 1;
+        const comma = isLast ? '' : ',';
+
+        lines.push(`    "${key}": {`);
+        lines.push(`        "level": ${entry.level},`);
+
+        if (entry.dependsOn.length === 0) {
+            lines.push(`        "dependsOn": []`);
+        } else {
+            lines.push(`        "dependsOn": [`);
+            entry.dependsOn.forEach((dep, depIndex) => {
+                const depComma = depIndex === entry.dependsOn.length - 1 ? '' : ',';
+                lines.push(`            "${dep}"${depComma}`);
+            });
+            lines.push(`        ]`);
+        }
+
+        lines.push(`    }${comma}`);
+
+    });
+
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+
+/**
+ * Save the graph to disk
+ *
+ * @param graph - The graph to save
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param graphPath - Relative path to graph file (default: .graphs/dependencies.json)
+ */
+export function saveGraph(
+    graph: EnhancedGraph,
+    workspaceRoot: string,
+    graphPath: string = DEFAULT_GRAPH_PATH
+): void {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    const dir = path.dirname(fullPath);
+
+    // Ensure directory exists
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+
+    // Sort keys for deterministic output
+    const sortedGraph: EnhancedGraph = {};
+    const sortedKeys = Object.keys(graph).sort();
+    for (const key of sortedKeys) {
+        sortedGraph[key] = graph[key];
+    }
+
+    const content = formatGraphJson(sortedGraph);
+    fs.writeFileSync(fullPath, content, 'utf-8');
+}
+
+/**
+ * Check if the graph file exists
+ */
+export function graphFileExists(
+    workspaceRoot: string,
+    graphPath: string = DEFAULT_GRAPH_PATH
+): boolean {
+    const fullPath = path.join(workspaceRoot, graphPath);
+    return fs.existsSync(fullPath);
+}

package/src/lib/graph-sorter.ts

@@ -0,0 +1,137 @@
+/**
+ * Graph Sorter
+ *
+ * Performs topological sorting on the dependency graph to:
+ * 1. Detect circular dependencies (fails if cycle found)
+ * 2. Assign level numbers to each project (level 0 = no deps, level 1 = depends on level 0, etc.)
+ * 3. Group projects into layers for deterministic ordering
+ */
+
+/**
+ * Graph entry with level metadata
+ */
+export interface GraphEntry {
+    level: number;
+    dependsOn: string[];
+}
+
+/**
+ * Enhanced graph format with level information
+ */
+export type EnhancedGraph = Record<string, GraphEntry>;
+
+/**
+ * Compute topological layers for dependency graph using Kahn's algorithm
+ *
+ * Projects are grouped into layers where each layer only depends on previous layers.
+ * Throws an error if a circular dependency is detected.
+ *
+ * @param graph - Dependency graph { project: [deps] }
+ * @returns Array of layers, each containing sorted project names
+ */
+export function computeTopologicalLayers(graph: Record<string, string[]>): string[][] {
+    const layers: string[][] = [];
+    const processed = new Set<string>();
+    const allProjects = Object.keys(graph);
+
+    while (processed.size < allProjects.length) {
+        const currentLayer: string[] = [];
+
+        for (const project of allProjects) {
+            if (processed.has(project)) continue;
+
+            const deps = graph[project] || [];
+            // Check if all dependencies are in previous layers (already processed)
+            const allDepsInPrevLayers = deps.every((dep) => processed.has(dep));
+
+            if (allDepsInPrevLayers) {
+                currentLayer.push(project);
+            }
+        }
+
+        if (currentLayer.length === 0) {
+            // No progress made = circular dependency detected
+            const remaining = allProjects.filter((p) => !processed.has(p));
+
+            // Try to identify the cycle
+            const cycleInfo = findCycle(graph, remaining);
+
+            throw new Error(
+                `Circular dependency detected among: ${remaining.join(', ')}\n` +
+                    (cycleInfo ? `Cycle: ${cycleInfo}\n` : '') +
+                    'Fix: Remove one of the dependencies to break the cycle.'
+            );
+        }
+
+        // Sort alphabetically within layer for deterministic output
+        currentLayer.sort();
+        layers.push(currentLayer);
+
+        // Mark as processed
+        currentLayer.forEach((p) => processed.add(p));
+    }
+
+    return layers;
+}
+
+/**
+ * Try to find and describe a cycle in the graph
+ */
+function findCycle(graph: Record<string, string[]>, remaining: string[]): string | null {
+    const visited = new Set<string>();
+    const path: string[] = [];
+
+    function dfs(node: string): string | null {
+        if (path.includes(node)) {
+            const cycleStart = path.indexOf(node);
+            return [...path.slice(cycleStart), node].join(' -> ');
+        }
+        if (visited.has(node)) return null;
+
+        visited.add(node);
+        path.push(node);
+
+        const deps = graph[node] || [];
+        for (const dep of deps) {
+            if (remaining.includes(dep)) {
+                const result = dfs(dep);
+                if (result) return result;
+            }
+        }
+
+        path.pop();
+        return null;
+    }
+
+    for (const node of remaining) {
+        const cycle = dfs(node);
+        if (cycle) return cycle;
+    }
+
+    return null;
+}
+
+/**
+ * Sort graph in topological order with alphabetical sorting within layers
+ * Returns enhanced format with level metadata
+ *
+ * @param graph - Unsorted dependency graph { project: [deps] }
+ * @returns Sorted graph with level metadata { project: { level: number, dependsOn: [deps] } }
+ */
+export function sortGraphTopologically(graph: Record<string, string[]>): EnhancedGraph {
+    const layers = computeTopologicalLayers(graph);
+    const result: EnhancedGraph = {};
+
+    // Add projects layer by layer (dependencies before dependents)
+    layers.forEach((layer, levelIndex) => {
+        for (const project of layer) {
+            // Already sorted alphabetically within layer
+            result[project] = {
+                level: levelIndex,
+                dependsOn: (graph[project] || []).sort(),
+            };
+        }
+    });
+
+    return result;
+}