@webpieces/dev-config 0.2.94 → 0.2.97

package/executors/validate-versions-locked/executor.ts

@@ -1,367 +0,0 @@
-/**
- * Validate Versions Locked Executor
- *
- * Validates that package.json versions are:
- * 1. LOCKED (exact versions, no semver ranges like ^, ~, *)
- * 2. CONSISTENT across all package.json files (no version conflicts)
- *
- * Why locked versions matter:
- * - Micro bugs ARE introduced via patch versions (1.4.5 → 1.4.6)
- * - git bisect fails when software changes OUTSIDE of git
- * - Library upgrades must be explicit via PR/commit, not implicit drift
- *
- * Usage:
- * nx run architecture:validate-versions-locked
- */
-
-import type { ExecutorContext } from '@nx/devkit';
-import * as fs from 'fs';
-import * as path from 'path';
-
-export interface ValidateVersionsLockedOptions {
-    // No options needed
-}
-
-export interface ExecutorResult {
-    success: boolean;
-}
-
-// webpieces-disable max-lines-new-methods -- Existing method from renamed validate-versions file
-// Find all package.json files except node_modules, dist, .nx, .angular
-function findPackageJsonFiles(dir: string, basePath = ''): string[] {
-    const files: string[] = [];
-    const items = fs.readdirSync(dir);
-
-    for (const item of items) {
-        const fullPath = path.join(dir, item);
-        const relativePath = path.join(basePath, item);
-
-        // Skip these directories
-        if (
-            ['node_modules', 'dist', '.nx', '.angular', 'tmp', '.git'].includes(
-                item,
-            )
-        ) {
-            continue;
-        }
-
-        // Skip all hidden directories (starting with .)
-        if (item.startsWith('.')) {
-            continue;
-        }
-
-        const stat = fs.statSync(fullPath);
-        if (stat.isDirectory()) {
-            files.push(...findPackageJsonFiles(fullPath, relativePath));
-        } else if (item === 'package.json') {
-            files.push(fullPath);
-        }
-    }
-
-    return files;
-}
-
-// Check if a version string uses semver ranges
-function hasSemverRange(version: string): boolean {
-    // Allow workspace protocol
-    if (version.startsWith('workspace:')) {
-        return false;
-    }
-
-    // Allow file: protocol (for local packages)
-    if (version.startsWith('file:')) {
-        return false;
-    }
-
-    // Check for common semver range patterns
-    const semverPatterns = [
-        /^\^/, // ^1.2.3
-        /^~/, // ~1.2.3
-        /^\+/, // +1.2.3
-        /^\*/, // *
-        /^>/, // >1.2.3
-        /^</, // <1.2.3
-        /^>=/, // >=1.2.3
-        /^<=/, // <=1.2.3
-        /\|\|/, // 1.2.3 || 2.x
-        / - /, // 1.2.3 - 2.3.4
-        /^\d+\.x/, // 1.x, 1.2.x
-        /^latest$/, // latest
-        /^next$/, // next
-    ];
-
-    return semverPatterns.some((pattern) => pattern.test(version));
-}
-
-// webpieces-disable max-lines-new-methods -- Existing method from renamed validate-versions file
-// Validate a single package.json file for semver ranges
-function validatePackageJson(filePath: string): string[] {
-    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-    try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const pkg = JSON.parse(content);
-        const errors: string[] = [];
-
-        // Check dependencies
-        if (pkg.dependencies) {
-            for (const [name, version] of Object.entries(pkg.dependencies)) {
-                // Skip internal workspace packages
-                if (name.startsWith('@webpieces/')) {
-                    continue;
-                }
-
-                if (hasSemverRange(version as string)) {
-                    errors.push(
-                        `dependencies.${name}: "${version}" uses semver range (must be locked to exact version)`,
-                    );
-                }
-            }
-        }
-
-        // Check devDependencies
-        if (pkg.devDependencies) {
-            for (const [name, version] of Object.entries(pkg.devDependencies)) {
-                // Skip internal workspace packages
-                if (name.startsWith('@webpieces/')) {
-                    continue;
-                }
-
-                if (hasSemverRange(version as string)) {
-                    errors.push(
-                        `devDependencies.${name}: "${version}" uses semver range (must be locked to exact version)`,
-                    );
-                }
-            }
-        }
-
-        // Check peerDependencies (these can have ranges for compatibility)
-        // We don't validate peerDependencies for semver ranges since they're meant to be flexible
-
-        return errors;
-    } catch (err: any) {
-        //const error = toError(err);
-        return [`Failed to parse ${filePath}: ${err.message}`];
-    }
-}
-
-// Track all dependency versions across the monorepo
-interface DependencyUsage {
-    version: string;
-    file: string;
-    type: 'dependencies' | 'devDependencies';
-}
-
-// webpieces-disable max-lines-new-methods -- Collecting dependencies from all package.json files
-// Collect all dependency versions from all package.json files
-function collectAllDependencies(workspaceRoot: string): Map<string, DependencyUsage[]> {
-    const dependencyMap = new Map<string, DependencyUsage[]>();
-    const packageFiles = findPackageJsonFiles(workspaceRoot);
-
-    for (const filePath of packageFiles) {
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-        try {
-            const content = fs.readFileSync(filePath, 'utf-8');
-            const pkg = JSON.parse(content);
-            const relativePath = path.relative(workspaceRoot, filePath);
-
-            // Collect dependencies
-            if (pkg.dependencies) {
-                for (const [name, version] of Object.entries(pkg.dependencies)) {
-                    // Skip internal workspace packages
-                    if (name.startsWith('@webpieces/')) continue;
-
-                    const usage: DependencyUsage = {
-                        version: version as string,
-                        file: relativePath,
-                        type: 'dependencies'
-                    };
-
-                    if (!dependencyMap.has(name)) {
-                        dependencyMap.set(name, []);
-                    }
-                    dependencyMap.get(name)!.push(usage);
-                }
-            }
-
-            // Collect devDependencies
-            if (pkg.devDependencies) {
-                for (const [name, version] of Object.entries(pkg.devDependencies)) {
-                    // Skip internal workspace packages
-                    if (name.startsWith('@webpieces/')) continue;
-
-                    const usage: DependencyUsage = {
-                        version: version as string,
-                        file: relativePath,
-                        type: 'devDependencies'
-                    };
-
-                    if (!dependencyMap.has(name)) {
-                        dependencyMap.set(name, []);
-                    }
-                    dependencyMap.get(name)!.push(usage);
-                }
-            }
-        } catch (err: any) {
-            // const error = toError(err);
-            // Intentionally skip files that can't be parsed - this is expected for some package.json files
-        }
-    }
-
-    return dependencyMap;
-}
-
-// webpieces-disable max-lines-new-methods -- Simple iteration logic, splitting would reduce clarity
-// Check for version conflicts across package.json files
-function checkVersionConflicts(workspaceRoot: string): string[] {
-    console.log('\n🔍 Checking for version conflicts across package.json files:');
-
-    const dependencyMap = collectAllDependencies(workspaceRoot);
-    const conflicts: string[] = [];
-
-    for (const [packageName, usages] of dependencyMap.entries()) {
-        // Get unique versions (ignoring workspace: and file: protocols)
-        const versions = new Set(
-            usages
-                .map(u => u.version)
-                .filter(v => !v.startsWith('workspace:') && !v.startsWith('file:'))
-        );
-
-        if (versions.size > 1) {
-            const conflictDetails = usages
-                .filter(u => !u.version.startsWith('workspace:') && !u.version.startsWith('file:'))
-                .map(u => `      ${u.file} (${u.type}): ${u.version}`)
-                .join('\n');
-
-            conflicts.push(`   ❌ ${packageName} has ${versions.size} different versions:\n${conflictDetails}`);
-        }
-    }
-
-    if (conflicts.length === 0) {
-        console.log('   ✅ No version conflicts found');
-    } else {
-        for (const conflict of conflicts) {
-            console.log(conflict);
-        }
-    }
-
-    return conflicts;
-}
-
-/**
- * Prints the educational message explaining why semver ranges are forbidden.
- * This helps developers understand the rationale behind locked versions.
- */
-// webpieces-disable max-lines-new-methods -- Educational message template, splitting reduces clarity
-function printSemverRangeEducationalMessage(semverErrors: number): void {
-    console.log(`
-❌ SEMVER RANGES DETECTED - BUILD FAILED
-
-Found ${semverErrors} package(s) using semver ranges (^, ~, *, etc.) instead of locked versions.
-
-WHY THIS IS A HARD FAILURE:
-═══════════════════════════════════════════════════════════════════════════════
-
-1. MICRO BUGS ARE REAL
-   Thinking that patch versions (1.4.5 → 1.4.6) don't introduce bugs is wrong.
-   They do. Sometimes what looks like an "easy fix" breaks things in subtle ways.
-
-2. GIT BISECT BECOMES USELESS
-   When you run "git bisect" to find when a bug was introduced, it fails if
-   software changed OUTSIDE of git. You checkout an old commit, but node_modules
-   has different versions than when that commit was made. The bug persists even
-   in "known good" commits because the library versions drifted.
-
-3. THE "MAGIC BUG" PROBLEM
-   You checkout code from 6 months ago to debug an issue. The bug is still there!
-   But it wasn't there 6 months ago... The culprit: a minor version upgrade that
-   happened silently without any PR or git commit. Impossible to track down.
-
-4. CHANGES OUTSIDE GIT = BAD
-   Every change to your software should be tracked in version control.
-   Implicit library upgrades via semver ranges violate this principle.
-
-THE SOLUTION:
-═══════════════════════════════════════════════════════════════════════════════
-
-Use LOCKED (exact) versions for all dependencies:
-  ❌ "lodash": "^4.17.21"    <- BAD: allows 4.17.22, 4.18.0, etc.
-  ❌ "lodash": "~4.17.21"    <- BAD: allows 4.17.22, 4.17.23, etc.
-  ✅ "lodash": "4.17.21"     <- GOOD: locked to this exact version
-
-To upgrade libraries, use an explicit process:
-  1. Run: npm update <package-name>
-  2. Test thoroughly
-  3. Commit the package.json AND package-lock.json changes
-  4. Create a PR so the upgrade is reviewed and tracked in git history
-
-This way, every library change is:
-  • Intentional (not accidental)
-  • Reviewed (via PR)
-  • Tracked (in git history)
-  • Bisectable (git bisect works correctly)
-
-`);
-}
-
-// Check semver ranges in all package.json files - FAILS if any found
-function checkSemverRanges(workspaceRoot: string): { errors: number } {
-    console.log('\n📋 Checking for unlocked versions (semver ranges):');
-    const packageFiles = findPackageJsonFiles(workspaceRoot);
-    let semverErrors = 0;
-
-    for (const filePath of packageFiles) {
-        const relativePath = path.relative(workspaceRoot, filePath);
-        const errors = validatePackageJson(filePath);
-
-        if (errors.length > 0) {
-            console.log(`   ❌ ${relativePath}:`);
-            for (const error of errors) {
-                console.log(`      ${error}`);
-            }
-            semverErrors += errors.length;
-        } else {
-            console.log(`   ✅ ${relativePath}`);
-        }
-    }
-
-    return { errors: semverErrors };
-}
-
-export default async function runExecutor(
-    _options: ValidateVersionsLockedOptions,
-    context: ExecutorContext
-): Promise<ExecutorResult> {
-    console.log('\n🔒 Validating Package Versions are LOCKED and CONSISTENT\n');
-
-    const workspaceRoot = context.root;
-
-    // Step 1: Check for semver ranges (FAILS if any found)
-    const { errors: semverErrors } = checkSemverRanges(workspaceRoot);
-    const packageFiles = findPackageJsonFiles(workspaceRoot);
-
-    // Step 2: Check for version conflicts across package.json files
-    const versionConflicts = checkVersionConflicts(workspaceRoot);
-
-    // Summary
-    console.log(`\n📊 Summary:`);
-    console.log(`   Files checked: ${packageFiles.length}`);
-    console.log(`   Unlocked versions (semver ranges): ${semverErrors}`);
-    console.log(`   Version conflicts: ${versionConflicts.length}`);
-
-    // Fail on semver ranges with educational message
-    if (semverErrors > 0) {
-        printSemverRangeEducationalMessage(semverErrors);
-        return { success: false };
-    }
-
-    // Fail on version conflicts
-    if (versionConflicts.length > 0) {
-        console.log('\n❌ VALIDATION FAILED!');
-        console.log('   Fix version conflicts - all package.json files must use the same version for each dependency.');
-        console.log('   This prevents "works on my machine" bugs where different projects use different library versions.\n');
-        return { success: false };
-    }
-
-    console.log('\n✅ VALIDATION PASSED! All versions are locked and consistent.');
-    return { success: true };
-}

package/plugin/README.md

@@ -1,243 +0,0 @@
-# @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-architecture-cycles`** - Validate the architecture has no circular project dependencies
-- **`arch:validate-no-skiplevel-deps`** - Validate no redundant transitive dependencies
-- **`arch:validate-architecture-unchanged`** - Validate against blessed dependency graph
-
-### Per-Project File Import Cycle Checking
-
-Automatically adds a `validate-no-file-import-cycles` 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`
-- Creates `eslint.webpieces.config.mjs` with @webpieces ESLint rules
-- Creates `eslint.config.mjs` (if you don't have one) that imports the webpieces rules
-- If you already have `eslint.config.mjs`, shows you how to import the webpieces rules (one line)
-- Makes all targets immediately available
-
-**For new projects: Zero configuration needed!** All architecture validation, circular dependency checking, and ESLint rules are active.
-
-**For existing projects with ESLint:** Just add one import line shown during installation to enable the @webpieces ESLint rules.
-
-## 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 architecture:generate
-
-# Visualize the graph in your browser
-nx run architecture:visualize
-
-# Validate no circular project dependencies
-nx run architecture:validate-no-architecture-cycles
-
-# Validate against blessed graph (for CI)
-nx run architecture:validate-architecture-unchanged
-
-# Check for redundant dependencies
-nx run architecture:validate-no-skiplevel-deps
-```
-
-### Per-Project File Import Cycle Checking
-
-```bash
-# Check a specific project
-nx run my-project:validate-no-file-import-cycles
-
-# Check all affected projects
-nx affected --target=validate-no-file-import-cycles
-
-# Check all projects
-nx run-many --target=validate-no-file-import-cycles --all
-```
-
-## Configuration
-
-Configure the plugin in `nx.json`:
-
-```json
-{
-  "plugins": [
-    {
-      "plugin": "@webpieces/dev-config",
-      "options": {
-        "circularDeps": {
-          "enabled": true,
-          "targetName": "validate-no-file-import-cycles",
-          "excludePatterns": ["**/test-fixtures/**"]
-        },
-        "workspace": {
-          "enabled": true,
-          "targetPrefix": "architecture:",
-          "validations": {
-            "noCycles": true,
-            "noSkipLevelDeps": true,
-            "architectureUnchanged": true
-          },
-          "features": {
-            "generate": true,
-            "visualize": true
-          }
-        }
-      }
-    }
-  ]
-}
-```
-
-### Configuration Options
-
-#### `circularDeps`
-
-- **`enabled`** (boolean, default: `true`) - Enable/disable file import cycle checking
-- **`targetName`** (string, default: `'validate-no-file-import-cycles'`) - 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.d.ts

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

package/plugin/index.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-/**
- * Re-export plugin from parent directory for clean imports
- */
-tslib_1.__exportStar(require("../plugin"), exports);
-//# sourceMappingURL=index.js.map

package/plugin/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/dev-config/plugin/index.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,oDAA0B","sourcesContent":["/**\n * Re-export plugin from parent directory for clean imports\n */\nexport * from '../plugin';\n"]}

package/plugin/index.ts

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