@webpieces/nx-webpieces-rules 0.0.1

package/src/executors/validate-no-destructure/executor.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { ExecutorResult } from '../../executor-result';
+import { validateNoDestructure } from '@webpieces/code-rules';
+
+export default async function runExecutor(
+    // webpieces-disable no-any-unknown -- options are passed through to code-rules validators
+    options: Record<string, unknown>,
+    context: ExecutorContext,
+): Promise<ExecutorResult> {
+    return validateNoDestructure(options, context.root);
+}

package/src/executors/validate-no-destructure/schema.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate No Destructure Executor",
+    "description": "Validates that destructuring patterns are not used. Uses LINE-BASED detection for git diff filtering.",
+    "type": "object",
+    "properties": {
+        "mode": {
+            "type": "string",
+            "enum": ["OFF", "MODIFIED_CODE", "MODIFIED_FILES"],
+            "description": "OFF: skip validation. MODIFIED_CODE: only changed lines in diff. MODIFIED_FILES: all in modified files. Disallows destructuring patterns.",
+            "default": "OFF"
+        },
+        "disableAllowed": {
+            "type": "boolean",
+            "description": "Whether disable comments work. When false, no escape hatch.",
+            "default": true
+        },
+        "ignoreModifiedUntilEpoch": {
+            "type": "number",
+            "description": "Epoch seconds. Until this time, skip validation entirely. When expired, normal mode resumes. Omit when not needed."
+        }
+    },
+    "required": []
+}

package/src/executors/validate-no-direct-api-resolver/executor.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { ExecutorResult } from '../../executor-result';
+import { validateNoDirectApiResolver } from '@webpieces/code-rules';
+
+export default async function runExecutor(
+    // webpieces-disable no-any-unknown -- options are passed through to code-rules validators
+    options: Record<string, unknown>,
+    context: ExecutorContext,
+): Promise<ExecutorResult> {
+    return validateNoDirectApiResolver(options, context.root);
+}

package/src/executors/validate-no-direct-api-resolver/schema.json

@@ -0,0 +1,29 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate No Direct API in Resolver Executor",
+    "description": "Validates resolvers use services (not APIs) and components subscribe to service observables (not route.snapshot.data). Uses LINE-BASED detection for git diff filtering.",
+    "type": "object",
+    "properties": {
+        "mode": {
+            "type": "string",
+            "enum": ["OFF", "MODIFIED_CODE", "NEW_AND_MODIFIED_METHODS", "MODIFIED_FILES"],
+            "description": "OFF: skip validation. MODIFIED_CODE: only changed lines in diff. NEW_AND_MODIFIED_METHODS: violations in new/modified method/route scopes. MODIFIED_FILES: all in modified files.",
+            "default": "OFF"
+        },
+        "disableAllowed": {
+            "type": "boolean",
+            "description": "Whether disable comments work. When false, no escape hatch.",
+            "default": true
+        },
+        "ignoreModifiedUntilEpoch": {
+            "type": "number",
+            "description": "Epoch seconds. Until this time, skip validation entirely. When expired, normal mode resumes. Omit when not needed."
+        },
+        "enforcePaths": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Array of directory prefixes (relative to workspace root) to scope validation to. When set, only files under these paths are checked. When empty/omitted, all changed files are checked."
+        }
+    },
+    "required": []
+}

package/src/executors/validate-no-implicit-any/executor.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { ExecutorResult } from '../../executor-result';
+import { validateNoImplicitAny } from '@webpieces/code-rules';
+
+export default async function runExecutor(
+    // webpieces-disable no-any-unknown -- options are passed through to code-rules validators
+    options: Record<string, unknown>,
+    context: ExecutorContext,
+): Promise<ExecutorResult> {
+    return validateNoImplicitAny(options, context.root);
+}

package/src/executors/validate-no-implicit-any/schema.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate No Implicit Any Executor",
+    "description": "Validates that no function parameter, variable, or property has an implicit `any` type. Uses the TypeScript compiler (with noImplicitAny override) to detect TS7006/7005/7018/etc violations on changed lines only.",
+    "type": "object",
+    "properties": {
+        "mode": {
+            "type": "string",
+            "enum": ["OFF", "MODIFIED_CODE", "MODIFIED_FILES"],
+            "description": "OFF: skip validation. MODIFIED_CODE: only implicit-any on changed lines in diff. MODIFIED_FILES: all implicit-any in modified files.",
+            "default": "OFF"
+        },
+        "disableAllowed": {
+            "type": "boolean",
+            "description": "Whether // webpieces-disable no-implicit-any comments work. When false, no escape hatch.",
+            "default": true
+        },
+        "ignoreModifiedUntilEpoch": {
+            "type": "number",
+            "description": "Epoch seconds. Until this time, skip validation entirely. When expired, normal mode resumes. Omit when not needed."
+        }
+    },
+    "required": []
+}

package/src/executors/validate-no-inline-types/executor.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { ExecutorResult } from '../../executor-result';
+import { validateNoInlineTypes } from '@webpieces/code-rules';
+
+export default async function runExecutor(
+    // webpieces-disable no-any-unknown -- options are passed through to code-rules validators
+    options: Record<string, unknown>,
+    context: ExecutorContext,
+): Promise<ExecutorResult> {
+    return validateNoInlineTypes(options, context.root);
+}

package/src/executors/validate-no-inline-types/schema.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate No Inline Types Executor",
+    "description": "Validates that inline type literals are not used - prefer named types/interfaces/classes.",
+    "type": "object",
+    "properties": {
+        "mode": {
+            "type": "string",
+            "enum": ["OFF", "NEW_METHODS", "NEW_AND_MODIFIED_METHODS", "MODIFIED_FILES"],
+            "description": "OFF: skip validation. NEW_METHODS: only new methods in diff. NEW_AND_MODIFIED_METHODS: new methods + methods with changes. MODIFIED_FILES: all inline types in modified files.",
+            "default": "OFF"
+        },
+        "disableAllowed": {
+            "type": "boolean",
+            "description": "Whether disable comments work. When false, no escape hatch.",
+            "default": true
+        },
+        "ignoreModifiedUntilEpoch": {
+            "type": "number",
+            "description": "Epoch seconds. Until this time, skip validation entirely. When expired, normal mode resumes. Omit when not needed."
+        }
+    },
+    "required": []
+}

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

@@ -0,0 +1,274 @@
+/**
+ * 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';
+import { toError } from '../../toError';
+
+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
+    const transitiveEntries = Array.from(transitiveByDep.entries());
+    for (const dep of directDeps) {
+        for (const entry of transitiveEntries) {
+            const otherDep = entry[0];
+            const otherTransitive = entry[1];
+            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, '.webpieces', 'instruct-ai', 'webpieces.transitivedeps.md');
+    const docDir = path.dirname(docPath);
+
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        fs.mkdirSync(docDir, { recursive: true });
+        fs.writeFileSync(docPath, TRANSITIVE_DEPS_DOC, 'utf-8');
+    } catch (err: unknown) {
+        //const error = toError(err);
+        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');
+
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    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 .webpieces/instruct-ai/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 .webpieces/instruct-ai/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: unknown) {
+        const error = toError(err);
+        console.error('❌ Skip-level validation failed:', error.message);
+        return { success: false };
+    }
+}

package/src/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/src/executors/validate-no-unmanaged-exceptions/executor.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { ExecutorResult } from '../../executor-result';
+import { validateNoUnmanagedExceptions } from '@webpieces/code-rules';
+
+export default async function runExecutor(
+    // webpieces-disable no-any-unknown -- options are passed through to code-rules validators
+    options: Record<string, unknown>,
+    context: ExecutorContext,
+): Promise<ExecutorResult> {
+    return validateNoUnmanagedExceptions(options, context.root);
+}

package/src/executors/validate-no-unmanaged-exceptions/schema.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate No Unmanaged Exceptions Executor",
+    "description": "Validates that try/catch blocks are not used outside chokepoints. Uses LINE-BASED detection for git diff filtering.",
+    "type": "object",
+    "properties": {
+        "mode": {
+            "type": "string",
+            "enum": ["OFF", "MODIFIED_CODE", "MODIFIED_FILES"],
+            "description": "OFF: skip validation. MODIFIED_CODE: only changed lines in diff. MODIFIED_FILES: all in modified files. Disallows try/catch blocks.",
+            "default": "OFF"
+        },
+        "disableAllowed": {
+            "type": "boolean",
+            "description": "Whether disable comments work. When false, no escape hatch.",
+            "default": true
+        },
+        "ignoreModifiedUntilEpoch": {
+            "type": "number",
+            "description": "Epoch seconds. Until this time, skip validation entirely. When expired, normal mode resumes. Omit when not needed."
+        }
+    },
+    "required": []
+}

package/src/executors/validate-packagejson/executor.ts

@@ -0,0 +1,76 @@
+/**
+ * Validate Package.json Executor
+ *
+ * Validates that package.json dependencies match project.json build dependencies.
+ * This ensures the two sources of truth don't drift apart.
+ *
+ * Usage:
+ * nx run architecture:validate-packagejson
+ */
+
+import type { ExecutorContext } from '@nx/devkit';
+import { generateGraph } from '../../lib/graph-generator';
+import { sortGraphTopologically } from '../../lib/graph-sorter';
+import { validatePackageJsonDependencies } from '../../lib/package-validator';
+import { toError } from '../../toError';
+
+export interface ValidatePackageJsonOptions {
+    // No options needed for now
+}
+
+export interface ExecutorResult {
+    success: boolean;
+}
+
+export default async function runExecutor(
+    options: ValidatePackageJsonOptions,
+    context: ExecutorContext
+): Promise<ExecutorResult> {
+    const workspaceRoot = context.root;
+
+    console.log('\n📦 Validating Package.json Dependencies\n');
+
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    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 get enhanced graph with levels)
+        console.log('🔄 Computing topological layers...');
+        const enhancedGraph = sortGraphTopologically(rawGraph);
+
+        // Step 3: Validate package.json dependencies match
+        console.log('📦 Validating package.json dependencies match project.json...');
+        const packageValidation = await validatePackageJsonDependencies(enhancedGraph, workspaceRoot);
+
+        if (!packageValidation.valid) {
+            console.error('❌ Package.json validation failed!');
+            console.error('\nErrors:');
+            for (const error of packageValidation.errors) {
+                console.error(`  ${error}`);
+            }
+            console.error('\nTo fix:');
+            console.error('  1. Review the missing dependencies above');
+            console.error('  2. Add the missing dependencies to the respective package.json files');
+            console.error('  3. Ensure dependencies in package.json match build.dependsOn in project.json');
+            return { success: false };
+        }
+
+        console.log('✅ Package.json dependencies match project.json');
+
+        // Print summary
+        const validProjects = packageValidation.projectResults.filter(r => r.valid).length;
+        const totalProjects = packageValidation.projectResults.length;
+        console.log(`\n📈 Validation Summary:`);
+        console.log(`   Projects validated: ${totalProjects}`);
+        console.log(`   Valid: ${validProjects}`);
+        console.log(`   Invalid: ${totalProjects - validProjects}`);
+
+        return { success: true };
+    } catch (err: unknown) {
+        const error = toError(err);
+        console.error('❌ Package.json validation failed:', error.message);
+        return { success: false };
+    }
+}

package/src/executors/validate-packagejson/schema.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate Package.json Executor",
+    "description": "Validates that package.json dependencies match project.json build dependencies",
+    "type": "object",
+    "properties": {},
+    "required": []
+}

package/src/executors/validate-prisma-converters/executor.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { ExecutorResult } from '../../executor-result';
+import { validatePrismaConverters } from '@webpieces/code-rules';
+
+export default async function runExecutor(
+    // webpieces-disable no-any-unknown -- options are passed through to code-rules validators
+    options: Record<string, unknown>,
+    context: ExecutorContext,
+): Promise<ExecutorResult> {
+    return validatePrismaConverters(options, context.root);
+}

package/src/executors/validate-prisma-converters/schema.json

@@ -0,0 +1,38 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate Prisma Converters Executor",
+    "description": "Validates that Prisma converter methods follow scalable patterns: correct Dbo parameter, no async, no standalone functions, and Dto creation only in converter directories.",
+    "type": "object",
+    "properties": {
+        "mode": {
+            "type": "string",
+            "enum": ["OFF", "NEW_AND_MODIFIED_METHODS", "MODIFIED_FILES"],
+            "description": "OFF: skip validation. NEW_AND_MODIFIED_METHODS: validate methods that are new or have changed lines. MODIFIED_FILES: validate all methods in modified files.",
+            "default": "OFF"
+        },
+        "schemaPath": {
+            "type": "string",
+            "description": "Relative path from workspace root to schema.prisma"
+        },
+        "convertersPaths": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Array of directories (relative to workspace root) containing converter files"
+        },
+        "enforcePaths": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Array of directory prefixes (relative to workspace root) to scope validation to. When set, only files under these paths are checked. When empty/omitted, all changed files are checked."
+        },
+        "disableAllowed": {
+            "type": "boolean",
+            "description": "Whether disable comments work. When false, no escape hatch.",
+            "default": true
+        },
+        "ignoreModifiedUntilEpoch": {
+            "type": "number",
+            "description": "Epoch seconds. Until this time, skip prisma-converter validation entirely. When expired, normal mode resumes. Omit when not needed."
+        }
+    },
+    "required": []
+}

package/src/executors/validate-return-types/executor.ts

@@ -0,0 +1,11 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { ExecutorResult } from '../../executor-result';
+import { validateReturnTypes } from '@webpieces/code-rules';
+
+export default async function runExecutor(
+    // webpieces-disable no-any-unknown -- options are passed through to code-rules validators
+    options: Record<string, unknown>,
+    context: ExecutorContext,
+): Promise<ExecutorResult> {
+    return validateReturnTypes(options, context.root);
+}

package/src/executors/validate-return-types/schema.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate Return Types Executor",
+    "description": "Validates that methods have explicit return type annotations for better code readability.",
+    "type": "object",
+    "properties": {
+        "mode": {
+            "type": "string",
+            "enum": ["OFF", "NEW_METHODS", "NEW_AND_MODIFIED_METHODS", "MODIFIED_FILES"],
+            "description": "OFF: skip validation. NEW_METHODS: only new methods in diff. NEW_AND_MODIFIED_METHODS: new methods + methods with changes. MODIFIED_FILES: all methods in modified files.",
+            "default": "NEW_METHODS"
+        },
+        "disableAllowed": {
+            "type": "boolean",
+            "description": "Whether disable comments work. When false, no escape hatch.",
+            "default": true
+        },
+        "ignoreModifiedUntilEpoch": {
+            "type": "number",
+            "description": "Epoch seconds. Until this time, skip validation entirely. When expired, normal mode resumes. Omit when not needed."
+        }
+    },
+    "required": []
+}