@webpieces/dev-config 0.2.39 → 0.2.40

package/architecture/executors/validate-new-methods/executor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validate New Methods Executor
+ *
+ * Validates that newly added methods don't exceed a maximum line count.
+ * Only runs when NX_BASE environment variable is set (affected mode).
+ *
+ * This validator encourages writing methods that read like a "table of contents"
+ * where each method call describes a larger piece of work.
+ *
+ * Usage:
+ * nx affected --target=validate-new-methods --base=origin/main
+ *
+ * Escape hatch: Add eslint-disable comment with justification
+ */
+import type { ExecutorContext } from '@nx/devkit';
+export interface ValidateNewMethodsOptions {
+    max?: number;
+}
+export interface ExecutorResult {
+    success: boolean;
+}
+export default function runExecutor(options: ValidateNewMethodsOptions, context: ExecutorContext): Promise<ExecutorResult>;

package/architecture/executors/validate-new-methods/executor.js

@@ -0,0 +1,351 @@
+"use strict";
+/**
+ * Validate New Methods Executor
+ *
+ * Validates that newly added methods don't exceed a maximum line count.
+ * Only runs when NX_BASE environment variable is set (affected mode).
+ *
+ * This validator encourages writing methods that read like a "table of contents"
+ * where each method call describes a larger piece of work.
+ *
+ * Usage:
+ * nx affected --target=validate-new-methods --base=origin/main
+ *
+ * Escape hatch: Add eslint-disable comment with justification
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = runExecutor;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const ts = tslib_1.__importStar(require("typescript"));
+const TMP_DIR = 'tmp/webpieces';
+const TMP_MD_FILE = 'webpieces.methodsize.md';
+const METHODSIZE_DOC_CONTENT = `# Instructions: New Method Too Long
+
+## The "Table of Contents" Principle
+
+Good code reads like a book's table of contents:
+- Chapter titles (method names) tell you WHAT happens
+- Reading chapter titles gives you the full story
+- You can dive into chapters (implementations) for details
+
+## Why Limit New Methods to 20-30 Lines?
+
+Methods under 20-30 lines are:
+- Easy to review in a single screen
+- Simple to understand without scrolling
+- Quick for AI to analyze and suggest improvements
+- More testable in isolation
+- Self-documenting through well-named extracted methods
+
+**~50% of the time**, you can stay under 20-30 lines in new code by extracting
+logical units into well-named methods. This makes code more readable for both
+AI and humans.
+
+## How to Refactor
+
+Instead of:
+\`\`\`typescript
+async processOrder(order: Order): Promise<Result> {
+    // 50 lines of validation, transformation, saving, notifications...
+}
+\`\`\`
+
+Write:
+\`\`\`typescript
+async processOrder(order: Order): Promise<Result> {
+    const validated = this.validateOrder(order);
+    const transformed = this.applyBusinessRules(validated);
+    const saved = await this.saveToDatabase(transformed);
+    await this.notifyStakeholders(saved);
+    return this.buildResult(saved);
+}
+\`\`\`
+
+Now the main method is a "table of contents" - each line tells part of the story!
+
+## Patterns for Extraction
+
+### Pattern 1: Extract Loop Bodies
+\`\`\`typescript
+// BEFORE
+for (const item of items) {
+    // 20 lines of processing
+}
+
+// AFTER
+for (const item of items) {
+    this.processItem(item);
+}
+\`\`\`
+
+### Pattern 2: Extract Conditional Blocks
+\`\`\`typescript
+// BEFORE
+if (isAdmin(user)) {
+    // 15 lines of admin logic
+}
+
+// AFTER
+if (isAdmin(user)) {
+    this.handleAdminUser(user);
+}
+\`\`\`
+
+### Pattern 3: Extract Data Transformations
+\`\`\`typescript
+// BEFORE
+const result = {
+    // 10+ lines of object construction
+};
+
+// AFTER
+const result = this.buildResultObject(data);
+\`\`\`
+
+## If Refactoring Is Not Feasible
+
+Sometimes methods genuinely need to be longer (complex algorithms, state machines, etc.).
+
+**Escape hatch**: Add an eslint-disable comment with justification:
+
+\`\`\`typescript
+// eslint-disable-next-line @webpieces/max-method-lines -- Complex state machine, splitting reduces clarity
+async complexStateMachine(): Promise<void> {
+    // ... longer method with justification
+}
+\`\`\`
+
+## AI Agent Action Steps
+
+1. **READ** the method to understand its logical sections
+2. **IDENTIFY** logical units that can be extracted
+3. **EXTRACT** into well-named private methods
+4. **VERIFY** the main method now reads like a table of contents
+5. **IF NOT FEASIBLE**: Add eslint-disable with clear justification
+
+## Remember
+
+- Every method you write today will be read many times tomorrow
+- The best code explains itself through structure
+- When in doubt, extract and name it
+`;
+/**
+ * Write the instructions documentation to tmp directory
+ */
+function writeTmpInstructions(workspaceRoot) {
+    const tmpDir = path.join(workspaceRoot, TMP_DIR);
+    const mdPath = path.join(tmpDir, TMP_MD_FILE);
+    fs.mkdirSync(tmpDir, { recursive: true });
+    fs.writeFileSync(mdPath, METHODSIZE_DOC_CONTENT);
+    return mdPath;
+}
+/**
+ * Get changed TypeScript files between base and head
+ */
+function getChangedTypeScriptFiles(workspaceRoot, base, head) {
+    try {
+        const output = (0, child_process_1.execSync)(`git diff --name-only ${base}...${head} -- '*.ts' '*.tsx'`, {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+        });
+        return output
+            .trim()
+            .split('\n')
+            .filter((f) => f && !f.includes('.spec.ts') && !f.includes('.test.ts'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get the diff content for a specific file
+ */
+function getFileDiff(workspaceRoot, file, base, head) {
+    try {
+        return (0, child_process_1.execSync)(`git diff ${base}...${head} -- "${file}"`, {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+        });
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Parse diff to find newly added method signatures
+ */
+function findNewMethodSignaturesInDiff(diffContent) {
+    const newMethods = new Set();
+    const lines = diffContent.split('\n');
+    // Patterns to match method definitions
+    const patterns = [
+        // async methodName( or methodName(
+        /^\+\s*(async\s+)?(\w+)\s*\(/,
+        // function methodName(
+        /^\+\s*(async\s+)?function\s+(\w+)\s*\(/,
+        // const/let methodName = (async)? (
+        /^\+\s*(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\(/,
+        // const/let methodName = (async)? function
+        /^\+\s*(?:const|let)\s+(\w+)\s*=\s*(?:async\s+)?function/,
+    ];
+    for (const line of lines) {
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            for (const pattern of patterns) {
+                const match = line.match(pattern);
+                if (match) {
+                    // Extract method name from different capture groups
+                    const methodName = match[2] || match[1];
+                    if (methodName && !['if', 'for', 'while', 'switch', 'catch', 'constructor'].includes(methodName)) {
+                        newMethods.add(methodName);
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    return newMethods;
+}
+/**
+ * Parse a TypeScript file and find methods with their line counts
+ */
+function findMethodsInFile(filePath, workspaceRoot) {
+    const fullPath = path.join(workspaceRoot, filePath);
+    if (!fs.existsSync(fullPath))
+        return [];
+    const content = fs.readFileSync(fullPath, 'utf-8');
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+    const methods = [];
+    function visit(node) {
+        let methodName;
+        let startLine;
+        let endLine;
+        if (ts.isMethodDeclaration(node) && node.name) {
+            methodName = node.name.getText(sourceFile);
+            const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+            startLine = start.line + 1;
+            endLine = end.line + 1;
+        }
+        else if (ts.isFunctionDeclaration(node) && node.name) {
+            methodName = node.name.getText(sourceFile);
+            const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+            startLine = start.line + 1;
+            endLine = end.line + 1;
+        }
+        else if (ts.isArrowFunction(node)) {
+            // Check if it's assigned to a variable
+            if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) {
+                methodName = node.parent.name.getText(sourceFile);
+                const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+                startLine = start.line + 1;
+                endLine = end.line + 1;
+            }
+        }
+        if (methodName && startLine !== undefined && endLine !== undefined) {
+            methods.push({
+                name: methodName,
+                line: startLine,
+                lines: endLine - startLine + 1,
+            });
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return methods;
+}
+/**
+ * Find new methods that exceed the line limit
+ */
+function findViolations(workspaceRoot, changedFiles, base, head, maxLines) {
+    const violations = [];
+    for (const file of changedFiles) {
+        // Get the diff to find which methods are NEW (not just modified)
+        const diff = getFileDiff(workspaceRoot, file, base, head);
+        const newMethodNames = findNewMethodSignaturesInDiff(diff);
+        if (newMethodNames.size === 0)
+            continue;
+        // Parse the current file to get method line counts
+        const methods = findMethodsInFile(file, workspaceRoot);
+        for (const method of methods) {
+            // Only check NEW methods
+            if (newMethodNames.has(method.name) && method.lines > maxLines) {
+                violations.push({
+                    file,
+                    methodName: method.name,
+                    line: method.line,
+                    lines: method.lines,
+                    isNew: true,
+                });
+            }
+        }
+    }
+    return violations;
+}
+async function runExecutor(options, context) {
+    const workspaceRoot = context.root;
+    const maxLines = options.max ?? 30;
+    // Check if running in affected mode
+    const base = process.env['NX_BASE'];
+    const head = process.env['NX_HEAD'] || 'HEAD';
+    if (!base) {
+        console.log('\n⏭️  Skipping new method validation (not in affected mode)');
+        console.log('   To run: nx affected --target=validate-new-methods --base=origin/main');
+        console.log('');
+        return { success: true };
+    }
+    console.log('\n📏 Validating New Method Sizes\n');
+    console.log(`   Base: ${base}`);
+    console.log(`   Head: ${head}`);
+    console.log(`   Max lines for new methods: ${maxLines}`);
+    console.log('');
+    try {
+        // Get changed TypeScript files
+        const changedFiles = getChangedTypeScriptFiles(workspaceRoot, base, head);
+        if (changedFiles.length === 0) {
+            console.log('✅ No TypeScript files changed');
+            return { success: true };
+        }
+        console.log(`📂 Checking ${changedFiles.length} changed file(s)...`);
+        // Find violations
+        const violations = findViolations(workspaceRoot, changedFiles, base, head, maxLines);
+        if (violations.length === 0) {
+            console.log('✅ All new methods are under ' + maxLines + ' lines');
+            return { success: true };
+        }
+        // Write instructions file
+        const mdPath = writeTmpInstructions(workspaceRoot);
+        // Report violations
+        console.error('');
+        console.error('❌ New methods exceed ' + maxLines + ' lines!');
+        console.error('');
+        console.error('📚 Methods should read like a "table of contents" - each method call');
+        console.error('   describes a larger piece of work. ~50% of the time, you can refactor');
+        console.error('   to stay under ' + maxLines + ' lines. If not feasible, use the escape hatch.');
+        console.error('');
+        for (const v of violations) {
+            console.error(`  ❌ ${v.file}:${v.line}`);
+            console.error(`     Method: ${v.methodName} (${v.lines} lines, max: ${maxLines})`);
+            console.error(`     READ ${mdPath} to fix this error properly`);
+            console.error('');
+        }
+        console.error('💡 To fix:');
+        console.error('   1. Refactor the method to read like a table of contents (preferred)');
+        console.error('   2. OR add eslint-disable comment with justification:');
+        console.error('      // eslint-disable-next-line @webpieces/max-method-lines -- [reason]');
+        console.error('');
+        console.error(`⚠️  *** READ ${mdPath} for detailed guidance *** ⚠️`);
+        console.error('');
+        return { success: false };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error('❌ New method validation failed:', error.message);
+        return { success: false };
+    }
+}
+//# sourceMappingURL=executor.js.map

package/architecture/executors/validate-new-methods/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../../../../packages/tooling/dev-config/architecture/executors/validate-new-methods/executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Validate New Methods Executor\n *\n * Validates that newly added methods don't exceed a maximum line count.\n * Only runs when NX_BASE environment variable is set (affected mode).\n *\n * This validator encourages writing methods that read like a \"table of contents\"\n * where each method call describes a larger piece of work.\n *\n * Usage:\n * nx affected --target=validate-new-methods --base=origin/main\n *\n * Escape hatch: Add eslint-disable comment with justification\n */\n\nimport type { ExecutorContext } from '@nx/devkit';\nimport { execSync } from 'child_process';\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport * as ts from 'typescript';\n\nexport interface ValidateNewMethodsOptions {\n    max?: number;\n}\n\nexport interface ExecutorResult {\n    success: boolean;\n}\n\ninterface MethodViolation {\n    file: string;\n    methodName: string;\n    line: number;\n    lines: number;\n    isNew: boolean;\n}\n\nconst TMP_DIR = 'tmp/webpieces';\nconst TMP_MD_FILE = 'webpieces.methodsize.md';\n\nconst METHODSIZE_DOC_CONTENT = `# Instructions: New Method Too Long\n\n## The \"Table of Contents\" Principle\n\nGood code reads like a book's table of contents:\n- Chapter titles (method names) tell you WHAT happens\n- Reading chapter titles gives you the full story\n- You can dive into chapters (implementations) for details\n\n## Why Limit New Methods to 20-30 Lines?\n\nMethods under 20-30 lines are:\n- Easy to review in a single screen\n- Simple to understand without scrolling\n- Quick for AI to analyze and suggest improvements\n- More testable in isolation\n- Self-documenting through well-named extracted methods\n\n**~50% of the time**, you can stay under 20-30 lines in new code by extracting\nlogical units into well-named methods. This makes code more readable for both\nAI and humans.\n\n## How to Refactor\n\nInstead of:\n\\`\\`\\`typescript\nasync processOrder(order: Order): Promise<Result> {\n    // 50 lines of validation, transformation, saving, notifications...\n}\n\\`\\`\\`\n\nWrite:\n\\`\\`\\`typescript\nasync processOrder(order: Order): Promise<Result> {\n    const validated = this.validateOrder(order);\n    const transformed = this.applyBusinessRules(validated);\n    const saved = await this.saveToDatabase(transformed);\n    await this.notifyStakeholders(saved);\n    return this.buildResult(saved);\n}\n\\`\\`\\`\n\nNow the main method is a \"table of contents\" - each line tells part of the story!\n\n## Patterns for Extraction\n\n### Pattern 1: Extract Loop Bodies\n\\`\\`\\`typescript\n// BEFORE\nfor (const item of items) {\n    // 20 lines of processing\n}\n\n// AFTER\nfor (const item of items) {\n    this.processItem(item);\n}\n\\`\\`\\`\n\n### Pattern 2: Extract Conditional Blocks\n\\`\\`\\`typescript\n// BEFORE\nif (isAdmin(user)) {\n    // 15 lines of admin logic\n}\n\n// AFTER\nif (isAdmin(user)) {\n    this.handleAdminUser(user);\n}\n\\`\\`\\`\n\n### Pattern 3: Extract Data Transformations\n\\`\\`\\`typescript\n// BEFORE\nconst result = {\n    // 10+ lines of object construction\n};\n\n// AFTER\nconst result = this.buildResultObject(data);\n\\`\\`\\`\n\n## If Refactoring Is Not Feasible\n\nSometimes methods genuinely need to be longer (complex algorithms, state machines, etc.).\n\n**Escape hatch**: Add an eslint-disable comment with justification:\n\n\\`\\`\\`typescript\n// eslint-disable-next-line @webpieces/max-method-lines -- Complex state machine, splitting reduces clarity\nasync complexStateMachine(): Promise<void> {\n    // ... longer method with justification\n}\n\\`\\`\\`\n\n## AI Agent Action Steps\n\n1. **READ** the method to understand its logical sections\n2. **IDENTIFY** logical units that can be extracted\n3. **EXTRACT** into well-named private methods\n4. **VERIFY** the main method now reads like a table of contents\n5. **IF NOT FEASIBLE**: Add eslint-disable with clear justification\n\n## Remember\n\n- Every method you write today will be read many times tomorrow\n- The best code explains itself through structure\n- When in doubt, extract and name it\n`;\n\n/**\n * Write the instructions documentation to tmp directory\n */\nfunction writeTmpInstructions(workspaceRoot: string): string {\n    const tmpDir = path.join(workspaceRoot, TMP_DIR);\n    const mdPath = path.join(tmpDir, TMP_MD_FILE);\n\n    fs.mkdirSync(tmpDir, { recursive: true });\n    fs.writeFileSync(mdPath, METHODSIZE_DOC_CONTENT);\n\n    return mdPath;\n}\n\n/**\n * Get changed TypeScript files between base and head\n */\nfunction getChangedTypeScriptFiles(workspaceRoot: string, base: string, head: string): string[] {\n    try {\n        const output = execSync(`git diff --name-only ${base}...${head} -- '*.ts' '*.tsx'`, {\n            cwd: workspaceRoot,\n            encoding: 'utf-8',\n        });\n        return output\n            .trim()\n            .split('\\n')\n            .filter((f) => f && !f.includes('.spec.ts') && !f.includes('.test.ts'));\n    } catch {\n        return [];\n    }\n}\n\n/**\n * Get the diff content for a specific file\n */\nfunction getFileDiff(workspaceRoot: string, file: string, base: string, head: string): string {\n    try {\n        return execSync(`git diff ${base}...${head} -- \"${file}\"`, {\n            cwd: workspaceRoot,\n            encoding: 'utf-8',\n        });\n    } catch {\n        return '';\n    }\n}\n\n/**\n * Parse diff to find newly added method signatures\n */\nfunction findNewMethodSignaturesInDiff(diffContent: string): Set<string> {\n    const newMethods = new Set<string>();\n    const lines = diffContent.split('\\n');\n\n    // Patterns to match method definitions\n    const patterns = [\n        // async methodName( or methodName(\n        /^\\+\\s*(async\\s+)?(\\w+)\\s*\\(/,\n        // function methodName(\n        /^\\+\\s*(async\\s+)?function\\s+(\\w+)\\s*\\(/,\n        // const/let methodName = (async)? (\n        /^\\+\\s*(?:const|let)\\s+(\\w+)\\s*=\\s*(?:async\\s*)?\\(/,\n        // const/let methodName = (async)? function\n        /^\\+\\s*(?:const|let)\\s+(\\w+)\\s*=\\s*(?:async\\s+)?function/,\n    ];\n\n    for (const line of lines) {\n        if (line.startsWith('+') && !line.startsWith('+++')) {\n            for (const pattern of patterns) {\n                const match = line.match(pattern);\n                if (match) {\n                    // Extract method name from different capture groups\n                    const methodName = match[2] || match[1];\n                    if (methodName && !['if', 'for', 'while', 'switch', 'catch', 'constructor'].includes(methodName)) {\n                        newMethods.add(methodName);\n                    }\n                    break;\n                }\n            }\n        }\n    }\n\n    return newMethods;\n}\n\n/**\n * Parse a TypeScript file and find methods with their line counts\n */\nfunction findMethodsInFile(\n    filePath: string,\n    workspaceRoot: string\n): Array<{ name: string; line: number; lines: number }> {\n    const fullPath = path.join(workspaceRoot, filePath);\n    if (!fs.existsSync(fullPath)) return [];\n\n    const content = fs.readFileSync(fullPath, 'utf-8');\n    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);\n\n    const methods: Array<{ name: string; line: number; lines: number }> = [];\n\n    function visit(node: ts.Node): void {\n        let methodName: string | undefined;\n        let startLine: number | undefined;\n        let endLine: number | undefined;\n\n        if (ts.isMethodDeclaration(node) && node.name) {\n            methodName = node.name.getText(sourceFile);\n            const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());\n            const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());\n            startLine = start.line + 1;\n            endLine = end.line + 1;\n        } else if (ts.isFunctionDeclaration(node) && node.name) {\n            methodName = node.name.getText(sourceFile);\n            const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());\n            const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());\n            startLine = start.line + 1;\n            endLine = end.line + 1;\n        } else if (ts.isArrowFunction(node)) {\n            // Check if it's assigned to a variable\n            if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) {\n                methodName = node.parent.name.getText(sourceFile);\n                const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());\n                const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());\n                startLine = start.line + 1;\n                endLine = end.line + 1;\n            }\n        }\n\n        if (methodName && startLine !== undefined && endLine !== undefined) {\n            methods.push({\n                name: methodName,\n                line: startLine,\n                lines: endLine - startLine + 1,\n            });\n        }\n\n        ts.forEachChild(node, visit);\n    }\n\n    visit(sourceFile);\n    return methods;\n}\n\n/**\n * Find new methods that exceed the line limit\n */\nfunction findViolations(\n    workspaceRoot: string,\n    changedFiles: string[],\n    base: string,\n    head: string,\n    maxLines: number\n): MethodViolation[] {\n    const violations: MethodViolation[] = [];\n\n    for (const file of changedFiles) {\n        // Get the diff to find which methods are NEW (not just modified)\n        const diff = getFileDiff(workspaceRoot, file, base, head);\n        const newMethodNames = findNewMethodSignaturesInDiff(diff);\n\n        if (newMethodNames.size === 0) continue;\n\n        // Parse the current file to get method line counts\n        const methods = findMethodsInFile(file, workspaceRoot);\n\n        for (const method of methods) {\n            // Only check NEW methods\n            if (newMethodNames.has(method.name) && method.lines > maxLines) {\n                violations.push({\n                    file,\n                    methodName: method.name,\n                    line: method.line,\n                    lines: method.lines,\n                    isNew: true,\n                });\n            }\n        }\n    }\n\n    return violations;\n}\n\nexport default async function runExecutor(\n    options: ValidateNewMethodsOptions,\n    context: ExecutorContext\n): Promise<ExecutorResult> {\n    const workspaceRoot = context.root;\n    const maxLines = options.max ?? 30;\n\n    // Check if running in affected mode\n    const base = process.env['NX_BASE'];\n    const head = process.env['NX_HEAD'] || 'HEAD';\n\n    if (!base) {\n        console.log('\\n⏭️  Skipping new method validation (not in affected mode)');\n        console.log('   To run: nx affected --target=validate-new-methods --base=origin/main');\n        console.log('');\n        return { success: true };\n    }\n\n    console.log('\\n📏 Validating New Method Sizes\\n');\n    console.log(`   Base: ${base}`);\n    console.log(`   Head: ${head}`);\n    console.log(`   Max lines for new methods: ${maxLines}`);\n    console.log('');\n\n    try {\n        // Get changed TypeScript files\n        const changedFiles = getChangedTypeScriptFiles(workspaceRoot, base, head);\n\n        if (changedFiles.length === 0) {\n            console.log('✅ No TypeScript files changed');\n            return { success: true };\n        }\n\n        console.log(`📂 Checking ${changedFiles.length} changed file(s)...`);\n\n        // Find violations\n        const violations = findViolations(workspaceRoot, changedFiles, base, head, maxLines);\n\n        if (violations.length === 0) {\n            console.log('✅ All new methods are under ' + maxLines + ' lines');\n            return { success: true };\n        }\n\n        // Write instructions file\n        const mdPath = writeTmpInstructions(workspaceRoot);\n\n        // Report violations\n        console.error('');\n        console.error('❌ New methods exceed ' + maxLines + ' lines!');\n        console.error('');\n        console.error('📚 Methods should read like a \"table of contents\" - each method call');\n        console.error('   describes a larger piece of work. ~50% of the time, you can refactor');\n        console.error('   to stay under ' + maxLines + ' lines. If not feasible, use the escape hatch.');\n        console.error('');\n\n        for (const v of violations) {\n            console.error(`  ❌ ${v.file}:${v.line}`);\n            console.error(`     Method: ${v.methodName} (${v.lines} lines, max: ${maxLines})`);\n            console.error(`     READ ${mdPath} to fix this error properly`);\n            console.error('');\n        }\n\n        console.error('💡 To fix:');\n        console.error('   1. Refactor the method to read like a table of contents (preferred)');\n        console.error('   2. OR add eslint-disable comment with justification:');\n        console.error('      // eslint-disable-next-line @webpieces/max-method-lines -- [reason]');\n        console.error('');\n        console.error(`⚠️  *** READ ${mdPath} for detailed guidance *** ⚠️`);\n        console.error('');\n\n        return { success: false };\n    } catch (err: unknown) {\n        const error = err instanceof Error ? err : new Error(String(err));\n        console.error('❌ New method validation failed:', error.message);\n        return { success: false };\n    }\n}\n"]}

package/architecture/executors/validate-new-methods/executor.ts

@@ -0,0 +1,408 @@
+/**
+ * Validate New Methods Executor
+ *
+ * Validates that newly added methods don't exceed a maximum line count.
+ * Only runs when NX_BASE environment variable is set (affected mode).
+ *
+ * This validator encourages writing methods that read like a "table of contents"
+ * where each method call describes a larger piece of work.
+ *
+ * Usage:
+ * nx affected --target=validate-new-methods --base=origin/main
+ *
+ * Escape hatch: Add eslint-disable comment with justification
+ */
+
+import type { ExecutorContext } from '@nx/devkit';
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as ts from 'typescript';
+
+export interface ValidateNewMethodsOptions {
+    max?: number;
+}
+
+export interface ExecutorResult {
+    success: boolean;
+}
+
+interface MethodViolation {
+    file: string;
+    methodName: string;
+    line: number;
+    lines: number;
+    isNew: boolean;
+}
+
+const TMP_DIR = 'tmp/webpieces';
+const TMP_MD_FILE = 'webpieces.methodsize.md';
+
+const METHODSIZE_DOC_CONTENT = `# Instructions: New Method Too Long
+
+## The "Table of Contents" Principle
+
+Good code reads like a book's table of contents:
+- Chapter titles (method names) tell you WHAT happens
+- Reading chapter titles gives you the full story
+- You can dive into chapters (implementations) for details
+
+## Why Limit New Methods to 20-30 Lines?
+
+Methods under 20-30 lines are:
+- Easy to review in a single screen
+- Simple to understand without scrolling
+- Quick for AI to analyze and suggest improvements
+- More testable in isolation
+- Self-documenting through well-named extracted methods
+
+**~50% of the time**, you can stay under 20-30 lines in new code by extracting
+logical units into well-named methods. This makes code more readable for both
+AI and humans.
+
+## How to Refactor
+
+Instead of:
+\`\`\`typescript
+async processOrder(order: Order): Promise<Result> {
+    // 50 lines of validation, transformation, saving, notifications...
+}
+\`\`\`
+
+Write:
+\`\`\`typescript
+async processOrder(order: Order): Promise<Result> {
+    const validated = this.validateOrder(order);
+    const transformed = this.applyBusinessRules(validated);
+    const saved = await this.saveToDatabase(transformed);
+    await this.notifyStakeholders(saved);
+    return this.buildResult(saved);
+}
+\`\`\`
+
+Now the main method is a "table of contents" - each line tells part of the story!
+
+## Patterns for Extraction
+
+### Pattern 1: Extract Loop Bodies
+\`\`\`typescript
+// BEFORE
+for (const item of items) {
+    // 20 lines of processing
+}
+
+// AFTER
+for (const item of items) {
+    this.processItem(item);
+}
+\`\`\`
+
+### Pattern 2: Extract Conditional Blocks
+\`\`\`typescript
+// BEFORE
+if (isAdmin(user)) {
+    // 15 lines of admin logic
+}
+
+// AFTER
+if (isAdmin(user)) {
+    this.handleAdminUser(user);
+}
+\`\`\`
+
+### Pattern 3: Extract Data Transformations
+\`\`\`typescript
+// BEFORE
+const result = {
+    // 10+ lines of object construction
+};
+
+// AFTER
+const result = this.buildResultObject(data);
+\`\`\`
+
+## If Refactoring Is Not Feasible
+
+Sometimes methods genuinely need to be longer (complex algorithms, state machines, etc.).
+
+**Escape hatch**: Add an eslint-disable comment with justification:
+
+\`\`\`typescript
+// eslint-disable-next-line @webpieces/max-method-lines -- Complex state machine, splitting reduces clarity
+async complexStateMachine(): Promise<void> {
+    // ... longer method with justification
+}
+\`\`\`
+
+## AI Agent Action Steps
+
+1. **READ** the method to understand its logical sections
+2. **IDENTIFY** logical units that can be extracted
+3. **EXTRACT** into well-named private methods
+4. **VERIFY** the main method now reads like a table of contents
+5. **IF NOT FEASIBLE**: Add eslint-disable with clear justification
+
+## Remember
+
+- Every method you write today will be read many times tomorrow
+- The best code explains itself through structure
+- When in doubt, extract and name it
+`;
+
+/**
+ * Write the instructions documentation to tmp directory
+ */
+function writeTmpInstructions(workspaceRoot: string): string {
+    const tmpDir = path.join(workspaceRoot, TMP_DIR);
+    const mdPath = path.join(tmpDir, TMP_MD_FILE);
+
+    fs.mkdirSync(tmpDir, { recursive: true });
+    fs.writeFileSync(mdPath, METHODSIZE_DOC_CONTENT);
+
+    return mdPath;
+}
+
+/**
+ * Get changed TypeScript files between base and head
+ */
+function getChangedTypeScriptFiles(workspaceRoot: string, base: string, head: string): string[] {
+    try {
+        const output = execSync(`git diff --name-only ${base}...${head} -- '*.ts' '*.tsx'`, {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+        });
+        return output
+            .trim()
+            .split('\n')
+            .filter((f) => f && !f.includes('.spec.ts') && !f.includes('.test.ts'));
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Get the diff content for a specific file
+ */
+function getFileDiff(workspaceRoot: string, file: string, base: string, head: string): string {
+    try {
+        return execSync(`git diff ${base}...${head} -- "${file}"`, {
+            cwd: workspaceRoot,
+            encoding: 'utf-8',
+        });
+    } catch {
+        return '';
+    }
+}
+
+/**
+ * Parse diff to find newly added method signatures
+ */
+function findNewMethodSignaturesInDiff(diffContent: string): Set<string> {
+    const newMethods = new Set<string>();
+    const lines = diffContent.split('\n');
+
+    // Patterns to match method definitions
+    const patterns = [
+        // async methodName( or methodName(
+        /^\+\s*(async\s+)?(\w+)\s*\(/,
+        // function methodName(
+        /^\+\s*(async\s+)?function\s+(\w+)\s*\(/,
+        // const/let methodName = (async)? (
+        /^\+\s*(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\(/,
+        // const/let methodName = (async)? function
+        /^\+\s*(?:const|let)\s+(\w+)\s*=\s*(?:async\s+)?function/,
+    ];
+
+    for (const line of lines) {
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            for (const pattern of patterns) {
+                const match = line.match(pattern);
+                if (match) {
+                    // Extract method name from different capture groups
+                    const methodName = match[2] || match[1];
+                    if (methodName && !['if', 'for', 'while', 'switch', 'catch', 'constructor'].includes(methodName)) {
+                        newMethods.add(methodName);
+                    }
+                    break;
+                }
+            }
+        }
+    }
+
+    return newMethods;
+}
+
+/**
+ * Parse a TypeScript file and find methods with their line counts
+ */
+function findMethodsInFile(
+    filePath: string,
+    workspaceRoot: string
+): Array<{ name: string; line: number; lines: number }> {
+    const fullPath = path.join(workspaceRoot, filePath);
+    if (!fs.existsSync(fullPath)) return [];
+
+    const content = fs.readFileSync(fullPath, 'utf-8');
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+
+    const methods: Array<{ name: string; line: number; lines: number }> = [];
+
+    function visit(node: ts.Node): void {
+        let methodName: string | undefined;
+        let startLine: number | undefined;
+        let endLine: number | undefined;
+
+        if (ts.isMethodDeclaration(node) && node.name) {
+            methodName = node.name.getText(sourceFile);
+            const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+            startLine = start.line + 1;
+            endLine = end.line + 1;
+        } else if (ts.isFunctionDeclaration(node) && node.name) {
+            methodName = node.name.getText(sourceFile);
+            const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+            startLine = start.line + 1;
+            endLine = end.line + 1;
+        } else if (ts.isArrowFunction(node)) {
+            // Check if it's assigned to a variable
+            if (ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) {
+                methodName = node.parent.name.getText(sourceFile);
+                const start = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+                const end = sourceFile.getLineAndCharacterOfPosition(node.getEnd());
+                startLine = start.line + 1;
+                endLine = end.line + 1;
+            }
+        }
+
+        if (methodName && startLine !== undefined && endLine !== undefined) {
+            methods.push({
+                name: methodName,
+                line: startLine,
+                lines: endLine - startLine + 1,
+            });
+        }
+
+        ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return methods;
+}
+
+/**
+ * Find new methods that exceed the line limit
+ */
+function findViolations(
+    workspaceRoot: string,
+    changedFiles: string[],
+    base: string,
+    head: string,
+    maxLines: number
+): MethodViolation[] {
+    const violations: MethodViolation[] = [];
+
+    for (const file of changedFiles) {
+        // Get the diff to find which methods are NEW (not just modified)
+        const diff = getFileDiff(workspaceRoot, file, base, head);
+        const newMethodNames = findNewMethodSignaturesInDiff(diff);
+
+        if (newMethodNames.size === 0) continue;
+
+        // Parse the current file to get method line counts
+        const methods = findMethodsInFile(file, workspaceRoot);
+
+        for (const method of methods) {
+            // Only check NEW methods
+            if (newMethodNames.has(method.name) && method.lines > maxLines) {
+                violations.push({
+                    file,
+                    methodName: method.name,
+                    line: method.line,
+                    lines: method.lines,
+                    isNew: true,
+                });
+            }
+        }
+    }
+
+    return violations;
+}
+
+export default async function runExecutor(
+    options: ValidateNewMethodsOptions,
+    context: ExecutorContext
+): Promise<ExecutorResult> {
+    const workspaceRoot = context.root;
+    const maxLines = options.max ?? 30;
+
+    // Check if running in affected mode
+    const base = process.env['NX_BASE'];
+    const head = process.env['NX_HEAD'] || 'HEAD';
+
+    if (!base) {
+        console.log('\n⏭️  Skipping new method validation (not in affected mode)');
+        console.log('   To run: nx affected --target=validate-new-methods --base=origin/main');
+        console.log('');
+        return { success: true };
+    }
+
+    console.log('\n📏 Validating New Method Sizes\n');
+    console.log(`   Base: ${base}`);
+    console.log(`   Head: ${head}`);
+    console.log(`   Max lines for new methods: ${maxLines}`);
+    console.log('');
+
+    try {
+        // Get changed TypeScript files
+        const changedFiles = getChangedTypeScriptFiles(workspaceRoot, base, head);
+
+        if (changedFiles.length === 0) {
+            console.log('✅ No TypeScript files changed');
+            return { success: true };
+        }
+
+        console.log(`📂 Checking ${changedFiles.length} changed file(s)...`);
+
+        // Find violations
+        const violations = findViolations(workspaceRoot, changedFiles, base, head, maxLines);
+
+        if (violations.length === 0) {
+            console.log('✅ All new methods are under ' + maxLines + ' lines');
+            return { success: true };
+        }
+
+        // Write instructions file
+        const mdPath = writeTmpInstructions(workspaceRoot);
+
+        // Report violations
+        console.error('');
+        console.error('❌ New methods exceed ' + maxLines + ' lines!');
+        console.error('');
+        console.error('📚 Methods should read like a "table of contents" - each method call');
+        console.error('   describes a larger piece of work. ~50% of the time, you can refactor');
+        console.error('   to stay under ' + maxLines + ' lines. If not feasible, use the escape hatch.');
+        console.error('');
+
+        for (const v of violations) {
+            console.error(`  ❌ ${v.file}:${v.line}`);
+            console.error(`     Method: ${v.methodName} (${v.lines} lines, max: ${maxLines})`);
+            console.error(`     READ ${mdPath} to fix this error properly`);
+            console.error('');
+        }
+
+        console.error('💡 To fix:');
+        console.error('   1. Refactor the method to read like a table of contents (preferred)');
+        console.error('   2. OR add eslint-disable comment with justification:');
+        console.error('      // eslint-disable-next-line @webpieces/max-method-lines -- [reason]');
+        console.error('');
+        console.error(`⚠️  *** READ ${mdPath} for detailed guidance *** ⚠️`);
+        console.error('');
+
+        return { success: false };
+    } catch (err: unknown) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error('❌ New method validation failed:', error.message);
+        return { success: false };
+    }
+}

package/architecture/executors/validate-new-methods/schema.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "title": "Validate New Methods Executor",
+    "description": "Validates that newly added methods don't exceed a maximum line count. Only runs in affected mode (when NX_BASE is set).",
+    "type": "object",
+    "properties": {
+        "max": {
+            "type": "number",
+            "description": "Maximum number of lines allowed for new methods",
+            "default": 30
+        }
+    },
+    "required": []
+}

package/executors.json

@@ -30,6 +30,11 @@
             "schema": "./architecture/executors/validate-packagejson/schema.json",
             "description": "Validate package.json dependencies match project.json build dependencies"
         },
+        "validate-new-methods": {
+            "implementation": "./architecture/executors/validate-new-methods/executor",
+            "schema": "./architecture/executors/validate-new-methods/schema.json",
+            "description": "Validate new methods don't exceed max line count (only runs in affected mode)"
+        },
         "help": {
             "implementation": "./executors/help/executor",
             "schema": "./executors/help/schema.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/dev-config",
-  "version": "0.2.39",
+  "version": "0.2.40",
   "description": "Development configuration, scripts, and patterns for WebPieces projects",
   "type": "commonjs",
   "bin": {

package/plugin.js

@@ -35,6 +35,7 @@ const DEFAULT_OPTIONS = {
             noSkipLevelDeps: true,
             architectureUnchanged: true,
             validatePackageJson: true,
+            validateNewMethods: true,
         },
         features: {
             generate: true,
@@ -161,6 +162,9 @@ function createWorkspaceTargetsWithoutPrefix(opts) {
     if (opts.workspace.validations.validatePackageJson) {
         targets['validate-packagejson'] = createValidatePackageJsonTarget();
     }
+    if (opts.workspace.validations.validateNewMethods) {
+        targets['validate-new-methods'] = createValidateNewMethodsTarget();
+    }
     // Add validate-complete target that runs all validations
     const validationTargets = [];
     if (opts.workspace.validations.noCycles) {
@@ -175,6 +179,9 @@ function createWorkspaceTargetsWithoutPrefix(opts) {
     if (opts.workspace.validations.validatePackageJson) {
         validationTargets.push('validate-packagejson');
     }
+    if (opts.workspace.validations.validateNewMethods) {
+        validationTargets.push('validate-new-methods');
+    }
     if (validationTargets.length > 0) {
         targets['validate-complete'] = createValidateCompleteTarget(validationTargets);
     }
@@ -208,6 +215,9 @@ function createWorkspaceTargets(opts) {
     if (opts.workspace.validations.validatePackageJson) {
         targets[`${prefix}validate-packagejson`] = createValidatePackageJsonTarget();
     }
+    if (opts.workspace.validations.validateNewMethods) {
+        targets[`${prefix}validate-new-methods`] = createValidateNewMethodsTarget();
+    }
     return targets;
 }
 function createGenerateTarget(graphPath) {
@@ -290,6 +300,18 @@ function createValidatePackageJsonTarget() {
         },
     };
 }
+function createValidateNewMethodsTarget() {
+    return {
+        executor: '@webpieces/dev-config:validate-new-methods',
+        cache: false, // Don't cache - depends on git state
+        inputs: ['default'],
+        options: { max: 30 },
+        metadata: {
+            technologies: ['nx'],
+            description: 'Validate new methods do not exceed max line count (only runs in affected mode)',
+        },
+    };
+}
 function createValidateCompleteTarget(validationTargets) {
     return {
         executor: 'nx:noop',