@webpieces/dev-config 0.2.17 → 0.2.23

package/generators/init/generator.ts

@@ -0,0 +1,130 @@
+import { formatFiles, readNxJson, Tree, updateNxJson, updateJson, addDependenciesToPackageJson } from '@nx/devkit';
+import type { InitGeneratorSchema } from './schema';
+
+/**
+ * Init generator for @webpieces/dev-config
+ *
+ * Automatically runs when users execute: nx add @webpieces/dev-config
+ *
+ * Responsibilities:
+ * - Registers the plugin in nx.json
+ * - Creates architecture/ directory if needed
+ * - Adds madge as a devDependency (required for circular dep checking)
+ * - Adds convenient npm scripts to package.json
+ * - Provides helpful output about available targets
+ */
+export default async function initGenerator(tree: Tree, options: InitGeneratorSchema) {
+    registerPlugin(tree);
+    const installTask = addMadgeDependency(tree);
+    createArchitectureDirectory(tree);
+    addNpmScripts(tree);
+
+    if (!options.skipFormat) {
+        await formatFiles(tree);
+    }
+
+    return createSuccessCallback(installTask);
+}
+
+function registerPlugin(tree: Tree): void {
+    const nxJson = readNxJson(tree);
+    if (!nxJson) {
+        throw new Error('Could not read nx.json. Are you in an Nx workspace?');
+    }
+
+    if (!nxJson.plugins) {
+        nxJson.plugins = [];
+    }
+
+    const pluginName = '@webpieces/dev-config';
+    const alreadyRegistered = nxJson.plugins.some(
+        (p) => typeof p === 'string' ? p === pluginName : p.plugin === pluginName
+    );
+
+    if (!alreadyRegistered) {
+        nxJson.plugins.push(pluginName);
+        updateNxJson(tree, nxJson);
+        console.log(`✅ Registered ${pluginName} plugin in nx.json`);
+    } else {
+        console.log(`ℹ️  ${pluginName} plugin is already registered`);
+    }
+}
+
+function addMadgeDependency(tree: Tree) {
+    return addDependenciesToPackageJson(tree, {}, { 'madge': '^8.0.0' });
+}
+
+function createArchitectureDirectory(tree: Tree): void {
+    if (!tree.exists('architecture')) {
+        tree.write('architecture/.gitkeep', '');
+        console.log('✅ Created architecture/ directory');
+    }
+}
+
+function addNpmScripts(tree: Tree): void {
+    updateJson(tree, 'package.json', (pkgJson) => {
+        pkgJson.scripts = pkgJson.scripts ?? {};
+
+        // Add architecture validation scripts
+        pkgJson.scripts['arch:generate'] = 'nx run .:arch:generate';
+        pkgJson.scripts['arch:visualize'] = 'nx run .:arch:visualize';
+        pkgJson.scripts['arch:validate'] = 'nx run .:arch:validate-no-cycles && nx run .:arch:validate-no-skiplevel-deps';
+        pkgJson.scripts['arch:validate-all'] = 'nx run .:arch:validate-no-cycles && nx run .:arch:validate-no-skiplevel-deps && nx run .:arch:validate-architecture-unchanged';
+
+        // Add circular dependency checking scripts
+        pkgJson.scripts['arch:check-circular'] = 'nx run-many --target=check-circular-deps --all';
+        pkgJson.scripts['arch:check-circular-affected'] = 'nx affected --target=check-circular-deps';
+
+        // Complete validation including circular deps
+        pkgJson.scripts['arch:validate-complete'] = 'npm run arch:validate-all && npm run arch:check-circular';
+
+        return pkgJson;
+    });
+
+    console.log('✅ Added npm scripts for architecture validation and circular dependency checking');
+}
+
+function createSuccessCallback(installTask: ReturnType<typeof addDependenciesToPackageJson>) {
+    return async () => {
+        await installTask();
+        console.log('✅ Added madge to devDependencies');
+        console.log('');
+        console.log('✅ @webpieces/dev-config plugin initialized!');
+        console.log('');
+        printAvailableTargets();
+    };
+}
+
+function printAvailableTargets(): void {
+    console.log('📝 Available npm scripts (convenient shortcuts):');
+    console.log('');
+    console.log('  Architecture graph:');
+    console.log('    npm run arch:generate                  # Generate dependency graph');
+    console.log('    npm run arch:visualize                 # Visualize dependency graph');
+    console.log('');
+    console.log('  Validation:');
+    console.log('    npm run arch:validate                  # Quick validation (no-cycles + no-skiplevel-deps)');
+    console.log('    npm run arch:validate-all              # Full arch validation (+ unchanged check)');
+    console.log('    npm run arch:check-circular            # Check all projects for circular deps');
+    console.log('    npm run arch:check-circular-affected   # Check affected projects only');
+    console.log('    npm run arch:validate-complete         # Complete validation (arch + circular)');
+    console.log('');
+    console.log('📝 Available Nx targets:');
+    console.log('');
+    console.log('  Workspace-level architecture validation:');
+    console.log('    nx run .:arch:generate                         # Generate dependency graph');
+    console.log('    nx run .:arch:visualize                        # Visualize dependency graph');
+    console.log('    nx run .:arch:validate-no-cycles               # Check for circular dependencies');
+    console.log('    nx run .:arch:validate-no-skiplevel-deps       # Check for redundant dependencies');
+    console.log('    nx run .:arch:validate-architecture-unchanged  # Validate against blessed graph');
+    console.log('');
+    console.log('  Per-project circular dependency checking:');
+    console.log('    nx run <project>:check-circular-deps           # Check project for circular deps');
+    console.log('    nx affected --target=check-circular-deps       # Check all affected projects');
+    console.log('    nx run-many --target=check-circular-deps --all # Check all projects');
+    console.log('');
+    console.log('💡 Quick start:');
+    console.log('   npm run arch:generate           # Generate the graph first');
+    console.log('   npm run arch:validate-complete  # Run complete validation');
+    console.log('');
+}

package/generators/init/schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "InitGenerator",
+  "title": "Initialize @webpieces/dev-config",
+  "description": "Initialize @webpieces/dev-config plugin in an Nx workspace",
+  "type": "object",
+  "properties": {
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files with Prettier",
+      "default": false
+    }
+  },
+  "required": []
+}

package/generators.json

@@ -0,0 +1,10 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "generators": {
+        "init": {
+            "factory": "./generators/init/generator",
+            "schema": "./generators/init/schema.json",
+            "description": "Initialize @webpieces/dev-config in an Nx workspace"
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/dev-config",
-  "version": "0.2.17",
+  "version": "0.2.23",
   "description": "Development configuration, scripts, and patterns for WebPieces projects",
   "type": "commonjs",
   "bin": {
@@ -11,21 +11,38 @@
     "wp-use-published": "./bin/use-published-webpieces.sh",
     "wp-setup-patterns": "./bin/setup-claude-patterns.sh"
   },
+  "executors": "./executors.json",
+  "generators": "./generators.json",
   "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json",
     "./eslint": "./config/eslint/base.mjs",
     "./eslint-plugin": "./eslint-plugin/index.js",
     "./jest": "./config/jest/preset.js",
-    "./tsconfig": "./config/typescript/tsconfig.base.json"
+    "./tsconfig": "./config/typescript/tsconfig.base.json",
+    "./plugin": "./plugin.js",
+    "./plugins/circular-deps": "./plugins/circular-deps/index.js",
+    "./architecture": "./architecture/index.js",
+    "./executors.json": "./executors.json",
+    "./generators.json": "./generators.json"
   },
   "files": [
     "bin/**/*",
     "config/**/*",
     "eslint-plugin/**/*",
     "patterns/**/*",
+    "plugins/**/*",
+    "plugin/**/*",
+    "plugin.js",
+    "generators/**/*",
+    "generators.json",
+    "architecture/**/*",
+    "executors.json",
     "README.md"
   ],
   "peerDependencies": {
-    "eslint": ">=8.0.0"
+    "eslint": ">=8.0.0",
+    "@nx/devkit": ">=18.0.0"
   },
   "keywords": [
     "webpieces",

package/plugin/README.md

@@ -0,0 +1,236 @@
+# @webpieces/dev-config Plugin
+
+Nx inference plugin that automatically provides architecture validation and circular dependency checking for your workspace.
+
+## Features
+
+### Workspace-Level Architecture Validation
+
+Automatically adds targets for managing and validating your project architecture:
+
+- **`arch:generate`** - Generate dependency graph from project.json files
+- **`arch:visualize`** - Create visual representations of the dependency graph
+- **`arch:validate-no-cycles`** - Validate the architecture has no circular dependencies
+- **`arch:validate-no-skiplevel-deps`** - Validate no redundant transitive dependencies
+- **`arch:validate-architecture-unchanged`** - Validate against blessed dependency graph
+
+### Per-Project Circular Dependency Checking
+
+Automatically adds a `check-circular-deps` target to every project with a `src/` directory using [madge](https://github.com/pahen/madge).
+
+## Installation
+
+Add the plugin to your Nx workspace:
+
+```bash
+nx add @webpieces/dev-config
+```
+
+This automatically:
+- Registers the plugin in `nx.json`
+- Adds `madge` as a devDependency (required for circular dependency checking)
+- Creates the `architecture/` directory
+- Adds convenient npm scripts to `package.json`
+- Makes all targets immediately available
+
+## Usage
+
+### Convenient npm Scripts
+
+The init generator adds these npm scripts for easy access:
+
+```bash
+# Generate and visualize
+npm run arch:generate     # Generate dependency graph
+npm run arch:visualize    # Visualize in browser
+
+# Validation
+npm run arch:validate                  # Quick: no-cycles + no-skiplevel-deps
+npm run arch:validate-all              # Full: adds architecture-unchanged check
+npm run arch:check-circular            # Check all projects for circular deps (madge)
+npm run arch:check-circular-affected   # Check only affected projects
+npm run arch:validate-complete         # Complete: all validations + circular deps
+
+# Recommended workflow
+npm run arch:generate           # 1. Generate graph first
+npm run arch:validate-complete  # 2. Run all validations
+```
+
+### Direct Nx Targets
+
+You can also run targets directly with Nx:
+
+```bash
+# Generate the dependency graph
+nx run .:arch:generate
+
+# Visualize the graph in your browser
+nx run .:arch:visualize
+
+# Validate no circular dependencies
+nx run .:arch:validate-no-cycles
+
+# Validate against blessed graph (for CI)
+nx run .:arch:validate-architecture-unchanged
+
+# Check for redundant dependencies
+nx run .:arch:validate-no-skiplevel-deps
+```
+
+### Per-Project Circular Dependency Checking
+
+```bash
+# Check a specific project
+nx run my-project:check-circular-deps
+
+# Check all affected projects
+nx affected --target=check-circular-deps
+
+# Check all projects
+nx run-many --target=check-circular-deps --all
+```
+
+## Configuration
+
+Configure the plugin in `nx.json`:
+
+```json
+{
+  "plugins": [
+    {
+      "plugin": "@webpieces/dev-config",
+      "options": {
+        "circularDeps": {
+          "enabled": true,
+          "targetName": "check-circular-deps",
+          "excludePatterns": ["**/test-fixtures/**"]
+        },
+        "workspace": {
+          "enabled": true,
+          "targetPrefix": "arch:",
+          "validations": {
+            "noCycles": true,
+            "noSkipLevelDeps": true,
+            "architectureUnchanged": true
+          },
+          "features": {
+            "generate": true,
+            "visualize": true
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+#### `circularDeps`
+
+- **`enabled`** (boolean, default: `true`) - Enable/disable circular dependency checking
+- **`targetName`** (string, default: `'check-circular-deps'`) - Name of the target to create
+- **`excludePatterns`** (string[], default: `[]`) - Patterns to exclude from checking
+
+#### `workspace`
+
+- **`enabled`** (boolean, default: `true`) - Enable/disable workspace-level validation
+- **`targetPrefix`** (string, default: `'arch:'`) - Prefix for workspace target names
+- **`graphPath`** (string, default: `'architecture/dependencies.json'`) - Path to dependency graph file
+
+##### `workspace.validations`
+
+- **`noCycles`** (boolean, default: `true`) - Enable no-cycles validation
+- **`noSkipLevelDeps`** (boolean, default: `true`) - Enable skip-level deps validation
+- **`architectureUnchanged`** (boolean, default: `true`) - Enable unchanged graph validation
+
+##### `workspace.features`
+
+- **`generate`** (boolean, default: `true`) - Enable graph generation target
+- **`visualize`** (boolean, default: `true`) - Enable visualization target
+
+## Examples
+
+### Disable Architecture Validation, Keep Circular Deps
+
+```json
+{
+  "plugin": "@webpieces/dev-config",
+  "options": {
+    "workspace": { "enabled": false }
+  }
+}
+```
+
+### Disable Circular Deps, Keep Architecture Validation
+
+```json
+{
+  "plugin": "@webpieces/dev-config",
+  "options": {
+    "circularDeps": { "enabled": false }
+  }
+}
+```
+
+### Disable Specific Validations
+
+```json
+{
+  "plugin": "@webpieces/dev-config",
+  "options": {
+    "workspace": {
+      "validations": {
+        "architectureUnchanged": false,
+        "noSkipLevelDeps": false
+      }
+    }
+  }
+}
+```
+
+### Exclude Test Fixtures from Circular Deps
+
+```json
+{
+  "plugin": "@webpieces/dev-config",
+  "options": {
+    "circularDeps": {
+      "excludePatterns": ["**/test-fixtures/**", "**/__tests__/**"]
+    }
+  }
+}
+```
+
+### Custom Target Names
+
+```json
+{
+  "plugin": "@webpieces/dev-config",
+  "options": {
+    "circularDeps": { "targetName": "circular-check" },
+    "workspace": { "targetPrefix": "architecture:" }
+  }
+}
+```
+
+## How It Works
+
+The plugin uses Nx's [Project Crystal (Inferred Tasks)](https://nx.dev/concepts/inferred-tasks) feature via the `createNodesV2` API to automatically detect and configure targets:
+
+1. **Workspace Detection**: Looks for a `project.json` at the workspace root to add architecture targets
+2. **Project Detection**: Scans all projects for `src/` directories to add circular-deps targets
+3. **Pattern Matching**: Respects exclude patterns for fine-grained control
+
+## Requirements
+
+- Nx >= 18.0.0
+- Node.js >= 18.0.0
+- [Graphviz](https://graphviz.org/) (for visualization)
+- [madge](https://github.com/pahen/madge) (bundled, used for circular dep checking)
+
+## Related Documentation
+
+- [Nx Inferred Tasks](https://nx.dev/concepts/inferred-tasks)
+- [Architecture Validation Guide](../../architecture/README.md)
+- [ESLint Plugin](../eslint-plugin/README.md)

package/plugin/index.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export plugin from parent directory for clean imports
+ */
+export * from '../plugin';