@webpieces/dev-config 0.0.0-dev → 0.2.21

package/eslint-plugin/rules/max-method-lines.js

@@ -25,14 +25,14 @@ Every method should read like a TABLE OF CONTENTS of a book.
 
 ### Pattern 1: Extract Loop Bodies
 \`\`\`typescript
-// ❌ BAD: 50 lines embedded in loop
+// BAD: 50 lines embedded in loop
 for (const order of orders) {
   // 20 lines of validation logic
   // 15 lines of processing logic
   // 10 lines of notification logic
 }
 
-// ✅ GOOD: Extracted to named methods
+// GOOD: Extracted to named methods
 for (const order of orders) {
   validateOrder(order);
   processOrderItems(order);
@@ -42,11 +42,11 @@ for (const order of orders) {
 
 ### Pattern 2: Try-Catch Wrapper for Exception Handling
 \`\`\`typescript
-// ✅ GOOD: Separates success path from error handling
+// GOOD: Separates success path from error handling
 async function handleRequest(req: Request): Promise<Response> {
   try {
     return await executeRequest(req);
-  } catch (err: any) {
+  } catch (err: unknown) {
     const error = toError(err);
     return createErrorResponse(error);
   }
@@ -55,7 +55,7 @@ async function handleRequest(req: Request): Promise<Response> {
 
 ### Pattern 3: Sequential Method Calls (Table of Contents)
 \`\`\`typescript
-// ✅ GOOD: Self-documenting steps
+// GOOD: Self-documenting steps
 function processOrder(order: Order): void {
   validateOrderData(order);
   calculateTotals(order);
@@ -68,22 +68,22 @@ function processOrder(order: Order): void {
 
 ### Pattern 4: Separate Data Object Creation
 \`\`\`typescript
-// ❌ BAD: 15 lines of inline object creation
+// BAD: 15 lines of inline object creation
 doSomething({ field1: ..., field2: ..., field3: ..., /* 15 more fields */ });
 
-// ✅ GOOD: Extract to factory method
+// GOOD: Extract to factory method
 const request = createRequestObject(data);
 doSomething(request);
 \`\`\`
 
 ### Pattern 5: Extract Inline Logic to Named Functions
 \`\`\`typescript
-// ❌ BAD: Complex inline logic
+// BAD: Complex inline logic
 if (user.role === 'admin' && user.permissions.includes('write') && !user.suspended) {
   // 30 lines of admin logic
 }
 
-// ✅ GOOD: Extract to named methods
+// GOOD: Extract to named methods
 if (isAdminWithWriteAccess(user)) {
   performAdminOperation(user);
 }
@@ -99,12 +99,12 @@ if (isAdminWithWriteAccess(user)) {
 6. **TEST** that functionality remains unchanged
 
 ## Examples of "Logical Units" to Extract
-- Validation logic → \`validateX()\`
-- Data transformation → \`transformXToY()\`
-- API calls → \`fetchXFromApi()\`
-- Object creation → \`createX()\`
-- Loop bodies → \`processItem()\`
-- Error handling → \`handleXError()\`
+- Validation logic -> \`validateX()\`
+- Data transformation -> \`transformXToY()\`
+- API calls -> \`fetchXFromApi()\`
+- Object creation -> \`createX()\`
+- Loop bodies -> \`processItem()\`
+- Error handling -> \`handleXError()\`
 
 Remember: Methods should read like a table of contents. Each line should be a "chapter title" (method call) that describes what happens, not how it happens.
 `;
@@ -113,7 +113,6 @@ let methodDocCreated = false;
 function getWorkspaceRoot(context) {
     const filename = context.filename || context.getFilename();
     let dir = path.dirname(filename);
-    // Walk up directory tree to find workspace root
     while (dir !== path.dirname(dir)) {
         const pkgPath = path.join(dir, 'package.json');
         if (fs.existsSync(pkgPath)) {
@@ -125,12 +124,12 @@ function getWorkspaceRoot(context) {
             }
             catch (err) {
                 //const error = toError(err);
-                // Continue searching if JSON parse fails
+                void err;
             }
         }
         dir = path.dirname(dir);
     }
-    return process.cwd(); // Fallback
+    return process.cwd();
 }
 function ensureDocFile(docPath, content) {
     try {
@@ -140,20 +139,66 @@ function ensureDocFile(docPath, content) {
     }
     catch (err) {
         //const error = toError(err);
-        // Graceful degradation: log warning but don't break lint
+        // err is used in console.warn below
         console.warn(`[webpieces] Could not create doc file: ${docPath}`, err);
         return false;
     }
 }
 function ensureMethodDoc(context) {
-    if (methodDocCreated)
-        return; // Performance: only create once per lint run
     const workspaceRoot = getWorkspaceRoot(context);
     const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.methods.md');
+    // Check if file exists AND flag is true - if both, skip
+    if (methodDocCreated && fs.existsSync(docPath))
+        return;
     if (ensureDocFile(docPath, METHOD_DOC_CONTENT)) {
         methodDocCreated = true;
     }
 }
+function getFunctionName(funcNode) {
+    if (funcNode.type === 'FunctionDeclaration' && funcNode.id?.name) {
+        return funcNode.id.name;
+    }
+    if (funcNode.type === 'FunctionExpression' && funcNode.id?.name) {
+        return funcNode.id.name;
+    }
+    return 'anonymous';
+}
+function reportTooLong(ctx, node, name, lineCount) {
+    ctx.context.report({
+        node,
+        messageId: 'tooLong',
+        data: {
+            name,
+            actual: String(lineCount),
+            max: String(ctx.maxLines),
+        },
+    });
+}
+function checkFunctionNode(ctx, node) {
+    ensureMethodDoc(ctx.context);
+    const funcNode = node;
+    // Skip function expressions inside method definitions
+    if (funcNode.type === 'FunctionExpression' && funcNode['parent']?.type === 'MethodDefinition') {
+        return;
+    }
+    if (!funcNode.loc || !funcNode.body)
+        return;
+    const name = getFunctionName(funcNode);
+    const lineCount = funcNode.loc.end.line - funcNode.loc.start.line + 1;
+    if (lineCount > ctx.maxLines) {
+        reportTooLong(ctx, funcNode, name, lineCount);
+    }
+}
+function checkMethodNode(ctx, node) {
+    ensureMethodDoc(ctx.context);
+    if (!node.loc || !node.value)
+        return;
+    const name = node.key?.name || 'anonymous';
+    const lineCount = node.loc.end.line - node.loc.start.line + 1;
+    if (lineCount > ctx.maxLines) {
+        reportTooLong(ctx, node, name, lineCount);
+    }
+}
 const rule = {
     meta: {
         type: 'suggestion',
@@ -182,74 +227,12 @@ const rule = {
     },
     create(context) {
         const options = context.options[0];
-        const maxLines = options?.max ?? 70;
-        function checkFunction(node) {
-            ensureMethodDoc(context);
-            const funcNode = node;
-            // Skip if this is a function expression that's part of a method definition
-            // (method definitions will be handled by checkMethod)
-            if (funcNode.type === 'FunctionExpression' &&
-                funcNode['parent']?.type === 'MethodDefinition') {
-                return;
-            }
-            // Skip if no location info or no body
-            if (!funcNode.loc || !funcNode.body) {
-                return;
-            }
-            // Get function name
-            let name = 'anonymous';
-            if (funcNode.type === 'FunctionDeclaration' && funcNode.id?.name) {
-                name = funcNode.id.name;
-            }
-            else if (funcNode.type === 'FunctionExpression' && funcNode.id?.name) {
-                name = funcNode.id.name;
-            }
-            // Calculate line count
-            const startLine = funcNode.loc.start.line;
-            const endLine = funcNode.loc.end.line;
-            const lineCount = endLine - startLine + 1;
-            if (lineCount > maxLines) {
-                context.report({
-                    node: funcNode,
-                    messageId: 'tooLong',
-                    data: {
-                        name,
-                        actual: String(lineCount),
-                        max: String(maxLines),
-                    },
-                });
-            }
-        }
-        function checkMethod(node) {
-            ensureMethodDoc(context);
-            const methodNode = node;
-            // Skip if no location info
-            if (!methodNode.loc || !methodNode.value) {
-                return;
-            }
-            // Get method name from key
-            const name = methodNode.key?.name || 'anonymous';
-            // Calculate line count for the method (including the method definition)
-            const startLine = methodNode.loc.start.line;
-            const endLine = methodNode.loc.end.line;
-            const lineCount = endLine - startLine + 1;
-            if (lineCount > maxLines) {
-                context.report({
-                    node: methodNode,
-                    messageId: 'tooLong',
-                    data: {
-                        name,
-                        actual: String(lineCount),
-                        max: String(maxLines),
-                    },
-                });
-            }
-        }
+        const ctx = { context, maxLines: options?.max ?? 70 };
         return {
-            FunctionDeclaration: checkFunction,
-            FunctionExpression: checkFunction,
-            ArrowFunctionExpression: checkFunction,
-            MethodDefinition: checkMethod,
+            FunctionDeclaration: (node) => checkFunctionNode(ctx, node),
+            FunctionExpression: (node) => checkFunctionNode(ctx, node),
+            ArrowFunctionExpression: (node) => checkFunctionNode(ctx, node),
+            MethodDefinition: (node) => checkMethodNode(ctx, node),
         };
     },
 };

package/eslint-plugin/rules/max-method-lines.js.map

@@ -1 +1 @@
-{"version":3,"file":"max-method-lines.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/eslint-plugin/rules/max-method-lines.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ESLint rule to enforce maximum method length\n *\n * Enforces a configurable maximum line count for methods, functions, and arrow functions.\n * Default: 70 lines\n *\n * Configuration:\n * '@webpieces/max-method-lines': ['error', { max: 70 }]\n */\n\nimport type { Rule } from 'eslint';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\ninterface MethodLinesOptions {\n    max: number;\n}\n\ninterface FunctionNode {\n    type:\n        | 'FunctionDeclaration'\n        | 'FunctionExpression'\n        | 'ArrowFunctionExpression'\n        | 'MethodDefinition';\n    body?: any;\n    loc?: {\n        start: { line: number };\n        end: { line: number };\n    };\n    key?: {\n        name?: string;\n    };\n    id?: {\n        name?: string;\n    };\n    [key: string]: any;\n}\n\nconst METHOD_DOC_CONTENT = `# AI Agent Instructions: Method Too Long\n\n**READ THIS FILE to fix methods that are too long**\n\n## Core Principle\nEvery method should read like a TABLE OF CONTENTS of a book.\n- Each method call is a \"chapter\"\n- When you dive into a method, you find another table of contents\n- Keeping methods under 70 lines is achievable with proper extraction\n\n## Command: Extract Code into Named Methods\n\n### Pattern 1: Extract Loop Bodies\n\\`\\`\\`typescript\n// ❌ BAD: 50 lines embedded in loop\nfor (const order of orders) {\n  // 20 lines of validation logic\n  // 15 lines of processing logic\n  // 10 lines of notification logic\n}\n\n// ✅ GOOD: Extracted to named methods\nfor (const order of orders) {\n  validateOrder(order);\n  processOrderItems(order);\n  sendNotifications(order);\n}\n\\`\\`\\`\n\n### Pattern 2: Try-Catch Wrapper for Exception Handling\n\\`\\`\\`typescript\n// ✅ GOOD: Separates success path from error handling\nasync function handleRequest(req: Request): Promise<Response> {\n  try {\n    return await executeRequest(req);\n  } catch (err: any) {\n    const error = toError(err);\n    return createErrorResponse(error);\n  }\n}\n\\`\\`\\`\n\n### Pattern 3: Sequential Method Calls (Table of Contents)\n\\`\\`\\`typescript\n// ✅ GOOD: Self-documenting steps\nfunction processOrder(order: Order): void {\n  validateOrderData(order);\n  calculateTotals(order);\n  applyDiscounts(order);\n  processPayment(order);\n  updateInventory(order);\n  sendConfirmation(order);\n}\n\\`\\`\\`\n\n### Pattern 4: Separate Data Object Creation\n\\`\\`\\`typescript\n// ❌ BAD: 15 lines of inline object creation\ndoSomething({ field1: ..., field2: ..., field3: ..., /* 15 more fields */ });\n\n// ✅ GOOD: Extract to factory method\nconst request = createRequestObject(data);\ndoSomething(request);\n\\`\\`\\`\n\n### Pattern 5: Extract Inline Logic to Named Functions\n\\`\\`\\`typescript\n// ❌ BAD: Complex inline logic\nif (user.role === 'admin' && user.permissions.includes('write') && !user.suspended) {\n  // 30 lines of admin logic\n}\n\n// ✅ GOOD: Extract to named methods\nif (isAdminWithWriteAccess(user)) {\n  performAdminOperation(user);\n}\n\\`\\`\\`\n\n## AI Agent Action Steps\n\n1. **IDENTIFY** the long method in the error message\n2. **READ** the method to understand its logical sections\n3. **EXTRACT** logical units into separate methods with descriptive names\n4. **REPLACE** inline code with method calls\n5. **VERIFY** each extracted method is <70 lines\n6. **TEST** that functionality remains unchanged\n\n## Examples of \"Logical Units\" to Extract\n- Validation logic → \\`validateX()\\`\n- Data transformation → \\`transformXToY()\\`\n- API calls → \\`fetchXFromApi()\\`\n- Object creation → \\`createX()\\`\n- Loop bodies → \\`processItem()\\`\n- Error handling → \\`handleXError()\\`\n\nRemember: Methods should read like a table of contents. Each line should be a \"chapter title\" (method call) that describes what happens, not how it happens.\n`;\n\n// Module-level flag to prevent redundant file creation\nlet methodDocCreated = false;\n\nfunction getWorkspaceRoot(context: Rule.RuleContext): string {\n    const filename = context.filename || context.getFilename();\n    let dir = path.dirname(filename);\n\n    // Walk up directory tree to find workspace root\n    while (dir !== path.dirname(dir)) {\n        const pkgPath = path.join(dir, 'package.json');\n        if (fs.existsSync(pkgPath)) {\n            try {\n                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));\n                if (pkg.workspaces || pkg.name === 'webpieces-ts') {\n                    return dir;\n                }\n            } catch (err: any) {\n                //const error = toError(err);\n                // Continue searching if JSON parse fails\n            }\n        }\n        dir = path.dirname(dir);\n    }\n    return process.cwd(); // Fallback\n}\n\nfunction ensureDocFile(docPath: string, content: string): boolean {\n    try {\n        fs.mkdirSync(path.dirname(docPath), { recursive: true });\n        fs.writeFileSync(docPath, content, 'utf-8');\n        return true;\n    } catch (err: any) {\n        //const error = toError(err);\n        // Graceful degradation: log warning but don't break lint\n        console.warn(`[webpieces] Could not create doc file: ${docPath}`, err);\n        return false;\n    }\n}\n\nfunction ensureMethodDoc(context: Rule.RuleContext): void {\n    if (methodDocCreated) return; // Performance: only create once per lint run\n\n    const workspaceRoot = getWorkspaceRoot(context);\n    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.methods.md');\n\n    if (ensureDocFile(docPath, METHOD_DOC_CONTENT)) {\n        methodDocCreated = true;\n    }\n}\n\nconst rule: Rule.RuleModule = {\n    meta: {\n        type: 'suggestion',\n        docs: {\n            description: 'Enforce maximum method length',\n            category: 'Best Practices',\n            recommended: false,\n            url: 'https://github.com/deanhiller/webpieces-ts',\n        },\n        messages: {\n            tooLong:\n                'AI Agent: READ tmp/webpieces/webpieces.methods.md for fix instructions. Method \"{{name}}\" has {{actual}} lines (max: {{max}})',\n        },\n        fixable: undefined,\n        schema: [\n            {\n                type: 'object',\n                properties: {\n                    max: {\n                        type: 'integer',\n                        minimum: 1,\n                    },\n                },\n                additionalProperties: false,\n            },\n        ],\n    },\n\n    create(context: Rule.RuleContext): Rule.RuleListener {\n        const options = context.options[0] as MethodLinesOptions | undefined;\n        const maxLines = options?.max ?? 70;\n\n        function checkFunction(node: any): void {\n            ensureMethodDoc(context);\n\n            const funcNode = node as FunctionNode;\n\n            // Skip if this is a function expression that's part of a method definition\n            // (method definitions will be handled by checkMethod)\n            if (\n                funcNode.type === 'FunctionExpression' &&\n                funcNode['parent']?.type === 'MethodDefinition'\n            ) {\n                return;\n            }\n\n            // Skip if no location info or no body\n            if (!funcNode.loc || !funcNode.body) {\n                return;\n            }\n\n            // Get function name\n            let name = 'anonymous';\n            if (funcNode.type === 'FunctionDeclaration' && funcNode.id?.name) {\n                name = funcNode.id.name;\n            } else if (funcNode.type === 'FunctionExpression' && funcNode.id?.name) {\n                name = funcNode.id.name;\n            }\n\n            // Calculate line count\n            const startLine = funcNode.loc.start.line;\n            const endLine = funcNode.loc.end.line;\n            const lineCount = endLine - startLine + 1;\n\n            if (lineCount > maxLines) {\n                context.report({\n                    node: funcNode as any,\n                    messageId: 'tooLong',\n                    data: {\n                        name,\n                        actual: String(lineCount),\n                        max: String(maxLines),\n                    },\n                });\n            }\n        }\n\n        function checkMethod(node: any): void {\n            ensureMethodDoc(context);\n\n            const methodNode = node;\n\n            // Skip if no location info\n            if (!methodNode.loc || !methodNode.value) {\n                return;\n            }\n\n            // Get method name from key\n            const name = methodNode.key?.name || 'anonymous';\n\n            // Calculate line count for the method (including the method definition)\n            const startLine = methodNode.loc.start.line;\n            const endLine = methodNode.loc.end.line;\n            const lineCount = endLine - startLine + 1;\n\n            if (lineCount > maxLines) {\n                context.report({\n                    node: methodNode as any,\n                    messageId: 'tooLong',\n                    data: {\n                        name,\n                        actual: String(lineCount),\n                        max: String(maxLines),\n                    },\n                });\n            }\n        }\n\n        return {\n            FunctionDeclaration: checkFunction,\n            FunctionExpression: checkFunction,\n            ArrowFunctionExpression: checkFunction,\n            MethodDefinition: checkMethod,\n        };\n    },\n};\n\nexport = rule;\n"]}
+{"version":3,"file":"max-method-lines.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/eslint-plugin/rules/max-method-lines.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ESLint rule to enforce maximum method length\n *\n * Enforces a configurable maximum line count for methods, functions, and arrow functions.\n * Default: 70 lines\n *\n * Configuration:\n * '@webpieces/max-method-lines': ['error', { max: 70 }]\n */\n\nimport type { Rule } from 'eslint';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\ninterface MethodLinesOptions {\n    max: number;\n}\n\ninterface FunctionNode {\n    type:\n        | 'FunctionDeclaration'\n        | 'FunctionExpression'\n        | 'ArrowFunctionExpression'\n        | 'MethodDefinition';\n    body?: any;\n    loc?: {\n        start: { line: number };\n        end: { line: number };\n    };\n    key?: {\n        name?: string;\n    };\n    id?: {\n        name?: string;\n    };\n    [key: string]: any;\n}\n\ninterface CheckerContext {\n    context: Rule.RuleContext;\n    maxLines: number;\n}\n\nconst METHOD_DOC_CONTENT = `# AI Agent Instructions: Method Too Long\n\n**READ THIS FILE to fix methods that are too long**\n\n## Core Principle\nEvery method should read like a TABLE OF CONTENTS of a book.\n- Each method call is a \"chapter\"\n- When you dive into a method, you find another table of contents\n- Keeping methods under 70 lines is achievable with proper extraction\n\n## Command: Extract Code into Named Methods\n\n### Pattern 1: Extract Loop Bodies\n\\`\\`\\`typescript\n// BAD: 50 lines embedded in loop\nfor (const order of orders) {\n  // 20 lines of validation logic\n  // 15 lines of processing logic\n  // 10 lines of notification logic\n}\n\n// GOOD: Extracted to named methods\nfor (const order of orders) {\n  validateOrder(order);\n  processOrderItems(order);\n  sendNotifications(order);\n}\n\\`\\`\\`\n\n### Pattern 2: Try-Catch Wrapper for Exception Handling\n\\`\\`\\`typescript\n// GOOD: Separates success path from error handling\nasync function handleRequest(req: Request): Promise<Response> {\n  try {\n    return await executeRequest(req);\n  } catch (err: unknown) {\n    const error = toError(err);\n    return createErrorResponse(error);\n  }\n}\n\\`\\`\\`\n\n### Pattern 3: Sequential Method Calls (Table of Contents)\n\\`\\`\\`typescript\n// GOOD: Self-documenting steps\nfunction processOrder(order: Order): void {\n  validateOrderData(order);\n  calculateTotals(order);\n  applyDiscounts(order);\n  processPayment(order);\n  updateInventory(order);\n  sendConfirmation(order);\n}\n\\`\\`\\`\n\n### Pattern 4: Separate Data Object Creation\n\\`\\`\\`typescript\n// BAD: 15 lines of inline object creation\ndoSomething({ field1: ..., field2: ..., field3: ..., /* 15 more fields */ });\n\n// GOOD: Extract to factory method\nconst request = createRequestObject(data);\ndoSomething(request);\n\\`\\`\\`\n\n### Pattern 5: Extract Inline Logic to Named Functions\n\\`\\`\\`typescript\n// BAD: Complex inline logic\nif (user.role === 'admin' && user.permissions.includes('write') && !user.suspended) {\n  // 30 lines of admin logic\n}\n\n// GOOD: Extract to named methods\nif (isAdminWithWriteAccess(user)) {\n  performAdminOperation(user);\n}\n\\`\\`\\`\n\n## AI Agent Action Steps\n\n1. **IDENTIFY** the long method in the error message\n2. **READ** the method to understand its logical sections\n3. **EXTRACT** logical units into separate methods with descriptive names\n4. **REPLACE** inline code with method calls\n5. **VERIFY** each extracted method is <70 lines\n6. **TEST** that functionality remains unchanged\n\n## Examples of \"Logical Units\" to Extract\n- Validation logic -> \\`validateX()\\`\n- Data transformation -> \\`transformXToY()\\`\n- API calls -> \\`fetchXFromApi()\\`\n- Object creation -> \\`createX()\\`\n- Loop bodies -> \\`processItem()\\`\n- Error handling -> \\`handleXError()\\`\n\nRemember: Methods should read like a table of contents. Each line should be a \"chapter title\" (method call) that describes what happens, not how it happens.\n`;\n\n// Module-level flag to prevent redundant file creation\nlet methodDocCreated = false;\n\nfunction getWorkspaceRoot(context: Rule.RuleContext): string {\n    const filename = context.filename || context.getFilename();\n    let dir = path.dirname(filename);\n\n    while (dir !== path.dirname(dir)) {\n        const pkgPath = path.join(dir, 'package.json');\n        if (fs.existsSync(pkgPath)) {\n            try {\n                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));\n                if (pkg.workspaces || pkg.name === 'webpieces-ts') {\n                    return dir;\n                }\n            } catch (err: any) {\n                //const error = toError(err);\n                void err;\n            }\n        }\n        dir = path.dirname(dir);\n    }\n    return process.cwd();\n}\n\nfunction ensureDocFile(docPath: string, content: string): boolean {\n    try {\n        fs.mkdirSync(path.dirname(docPath), { recursive: true });\n        fs.writeFileSync(docPath, content, 'utf-8');\n        return true;\n    } catch (err: any) {\n        //const error = toError(err);\n        // err is used in console.warn below\n        console.warn(`[webpieces] Could not create doc file: ${docPath}`, err);\n        return false;\n    }\n}\n\nfunction ensureMethodDoc(context: Rule.RuleContext): void {\n    const workspaceRoot = getWorkspaceRoot(context);\n    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.methods.md');\n\n    // Check if file exists AND flag is true - if both, skip\n    if (methodDocCreated && fs.existsSync(docPath)) return;\n\n    if (ensureDocFile(docPath, METHOD_DOC_CONTENT)) {\n        methodDocCreated = true;\n    }\n}\n\nfunction getFunctionName(funcNode: FunctionNode): string {\n    if (funcNode.type === 'FunctionDeclaration' && funcNode.id?.name) {\n        return funcNode.id.name;\n    }\n    if (funcNode.type === 'FunctionExpression' && funcNode.id?.name) {\n        return funcNode.id.name;\n    }\n    return 'anonymous';\n}\n\nfunction reportTooLong(ctx: CheckerContext, node: any, name: string, lineCount: number): void {\n    ctx.context.report({\n        node,\n        messageId: 'tooLong',\n        data: {\n            name,\n            actual: String(lineCount),\n            max: String(ctx.maxLines),\n        },\n    });\n}\n\nfunction checkFunctionNode(ctx: CheckerContext, node: any): void {\n    ensureMethodDoc(ctx.context);\n    const funcNode = node as FunctionNode;\n\n    // Skip function expressions inside method definitions\n    if (funcNode.type === 'FunctionExpression' && funcNode['parent']?.type === 'MethodDefinition') {\n        return;\n    }\n\n    if (!funcNode.loc || !funcNode.body) return;\n\n    const name = getFunctionName(funcNode);\n    const lineCount = funcNode.loc.end.line - funcNode.loc.start.line + 1;\n\n    if (lineCount > ctx.maxLines) {\n        reportTooLong(ctx, funcNode, name, lineCount);\n    }\n}\n\nfunction checkMethodNode(ctx: CheckerContext, node: any): void {\n    ensureMethodDoc(ctx.context);\n\n    if (!node.loc || !node.value) return;\n\n    const name = node.key?.name || 'anonymous';\n    const lineCount = node.loc.end.line - node.loc.start.line + 1;\n\n    if (lineCount > ctx.maxLines) {\n        reportTooLong(ctx, node, name, lineCount);\n    }\n}\n\nconst rule: Rule.RuleModule = {\n    meta: {\n        type: 'suggestion',\n        docs: {\n            description: 'Enforce maximum method length',\n            category: 'Best Practices',\n            recommended: false,\n            url: 'https://github.com/deanhiller/webpieces-ts',\n        },\n        messages: {\n            tooLong:\n                'AI Agent: READ tmp/webpieces/webpieces.methods.md for fix instructions. Method \"{{name}}\" has {{actual}} lines (max: {{max}})',\n        },\n        fixable: undefined,\n        schema: [\n            {\n                type: 'object',\n                properties: {\n                    max: {\n                        type: 'integer',\n                        minimum: 1,\n                    },\n                },\n                additionalProperties: false,\n            },\n        ],\n    },\n\n    create(context: Rule.RuleContext): Rule.RuleListener {\n        const options = context.options[0] as MethodLinesOptions | undefined;\n        const ctx: CheckerContext = { context, maxLines: options?.max ?? 70 };\n\n        return {\n            FunctionDeclaration: (node) => checkFunctionNode(ctx, node),\n            FunctionExpression: (node) => checkFunctionNode(ctx, node),\n            ArrowFunctionExpression: (node) => checkFunctionNode(ctx, node),\n            MethodDefinition: (node) => checkMethodNode(ctx, node),\n        };\n    },\n};\n\nexport = rule;\n"]}

package/eslint-plugin/rules/max-method-lines.ts

@@ -36,6 +36,11 @@ interface FunctionNode {
     [key: string]: any;
 }
 
+interface CheckerContext {
+    context: Rule.RuleContext;
+    maxLines: number;
+}
+
 const METHOD_DOC_CONTENT = `# AI Agent Instructions: Method Too Long
 
 **READ THIS FILE to fix methods that are too long**
@@ -50,14 +55,14 @@ Every method should read like a TABLE OF CONTENTS of a book.
 
 ### Pattern 1: Extract Loop Bodies
 \`\`\`typescript
-// ❌ BAD: 50 lines embedded in loop
+// BAD: 50 lines embedded in loop
 for (const order of orders) {
   // 20 lines of validation logic
   // 15 lines of processing logic
   // 10 lines of notification logic
 }
 
-// ✅ GOOD: Extracted to named methods
+// GOOD: Extracted to named methods
 for (const order of orders) {
   validateOrder(order);
   processOrderItems(order);
@@ -67,11 +72,11 @@ for (const order of orders) {
 
 ### Pattern 2: Try-Catch Wrapper for Exception Handling
 \`\`\`typescript
-// ✅ GOOD: Separates success path from error handling
+// GOOD: Separates success path from error handling
 async function handleRequest(req: Request): Promise<Response> {
   try {
     return await executeRequest(req);
-  } catch (err: any) {
+  } catch (err: unknown) {
     const error = toError(err);
     return createErrorResponse(error);
   }
@@ -80,7 +85,7 @@ async function handleRequest(req: Request): Promise<Response> {
 
 ### Pattern 3: Sequential Method Calls (Table of Contents)
 \`\`\`typescript
-// ✅ GOOD: Self-documenting steps
+// GOOD: Self-documenting steps
 function processOrder(order: Order): void {
   validateOrderData(order);
   calculateTotals(order);
@@ -93,22 +98,22 @@ function processOrder(order: Order): void {
 
 ### Pattern 4: Separate Data Object Creation
 \`\`\`typescript
-// ❌ BAD: 15 lines of inline object creation
+// BAD: 15 lines of inline object creation
 doSomething({ field1: ..., field2: ..., field3: ..., /* 15 more fields */ });
 
-// ✅ GOOD: Extract to factory method
+// GOOD: Extract to factory method
 const request = createRequestObject(data);
 doSomething(request);
 \`\`\`
 
 ### Pattern 5: Extract Inline Logic to Named Functions
 \`\`\`typescript
-// ❌ BAD: Complex inline logic
+// BAD: Complex inline logic
 if (user.role === 'admin' && user.permissions.includes('write') && !user.suspended) {
   // 30 lines of admin logic
 }
 
-// ✅ GOOD: Extract to named methods
+// GOOD: Extract to named methods
 if (isAdminWithWriteAccess(user)) {
   performAdminOperation(user);
 }
@@ -124,12 +129,12 @@ if (isAdminWithWriteAccess(user)) {
 6. **TEST** that functionality remains unchanged
 
 ## Examples of "Logical Units" to Extract
-- Validation logic → \`validateX()\`
-- Data transformation → \`transformXToY()\`
-- API calls → \`fetchXFromApi()\`
-- Object creation → \`createX()\`
-- Loop bodies → \`processItem()\`
-- Error handling → \`handleXError()\`
+- Validation logic -> \`validateX()\`
+- Data transformation -> \`transformXToY()\`
+- API calls -> \`fetchXFromApi()\`
+- Object creation -> \`createX()\`
+- Loop bodies -> \`processItem()\`
+- Error handling -> \`handleXError()\`
 
 Remember: Methods should read like a table of contents. Each line should be a "chapter title" (method call) that describes what happens, not how it happens.
 `;
@@ -141,7 +146,6 @@ function getWorkspaceRoot(context: Rule.RuleContext): string {
     const filename = context.filename || context.getFilename();
     let dir = path.dirname(filename);
 
-    // Walk up directory tree to find workspace root
     while (dir !== path.dirname(dir)) {
         const pkgPath = path.join(dir, 'package.json');
         if (fs.existsSync(pkgPath)) {
@@ -152,12 +156,12 @@ function getWorkspaceRoot(context: Rule.RuleContext): string {
                 }
             } catch (err: any) {
                 //const error = toError(err);
-                // Continue searching if JSON parse fails
+                void err;
             }
         }
         dir = path.dirname(dir);
     }
-    return process.cwd(); // Fallback
+    return process.cwd();
 }
 
 function ensureDocFile(docPath: string, content: string): boolean {
@@ -167,23 +171,78 @@ function ensureDocFile(docPath: string, content: string): boolean {
         return true;
     } catch (err: any) {
         //const error = toError(err);
-        // Graceful degradation: log warning but don't break lint
+        // err is used in console.warn below
         console.warn(`[webpieces] Could not create doc file: ${docPath}`, err);
         return false;
     }
 }
 
 function ensureMethodDoc(context: Rule.RuleContext): void {
-    if (methodDocCreated) return; // Performance: only create once per lint run
-
     const workspaceRoot = getWorkspaceRoot(context);
     const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.methods.md');
 
+    // Check if file exists AND flag is true - if both, skip
+    if (methodDocCreated && fs.existsSync(docPath)) return;
+
     if (ensureDocFile(docPath, METHOD_DOC_CONTENT)) {
         methodDocCreated = true;
     }
 }
 
+function getFunctionName(funcNode: FunctionNode): string {
+    if (funcNode.type === 'FunctionDeclaration' && funcNode.id?.name) {
+        return funcNode.id.name;
+    }
+    if (funcNode.type === 'FunctionExpression' && funcNode.id?.name) {
+        return funcNode.id.name;
+    }
+    return 'anonymous';
+}
+
+function reportTooLong(ctx: CheckerContext, node: any, name: string, lineCount: number): void {
+    ctx.context.report({
+        node,
+        messageId: 'tooLong',
+        data: {
+            name,
+            actual: String(lineCount),
+            max: String(ctx.maxLines),
+        },
+    });
+}
+
+function checkFunctionNode(ctx: CheckerContext, node: any): void {
+    ensureMethodDoc(ctx.context);
+    const funcNode = node as FunctionNode;
+
+    // Skip function expressions inside method definitions
+    if (funcNode.type === 'FunctionExpression' && funcNode['parent']?.type === 'MethodDefinition') {
+        return;
+    }
+
+    if (!funcNode.loc || !funcNode.body) return;
+
+    const name = getFunctionName(funcNode);
+    const lineCount = funcNode.loc.end.line - funcNode.loc.start.line + 1;
+
+    if (lineCount > ctx.maxLines) {
+        reportTooLong(ctx, funcNode, name, lineCount);
+    }
+}
+
+function checkMethodNode(ctx: CheckerContext, node: any): void {
+    ensureMethodDoc(ctx.context);
+
+    if (!node.loc || !node.value) return;
+
+    const name = node.key?.name || 'anonymous';
+    const lineCount = node.loc.end.line - node.loc.start.line + 1;
+
+    if (lineCount > ctx.maxLines) {
+        reportTooLong(ctx, node, name, lineCount);
+    }
+}
+
 const rule: Rule.RuleModule = {
     meta: {
         type: 'suggestion',
@@ -214,89 +273,13 @@ const rule: Rule.RuleModule = {
 
     create(context: Rule.RuleContext): Rule.RuleListener {
         const options = context.options[0] as MethodLinesOptions | undefined;
-        const maxLines = options?.max ?? 70;
-
-        function checkFunction(node: any): void {
-            ensureMethodDoc(context);
-
-            const funcNode = node as FunctionNode;
-
-            // Skip if this is a function expression that's part of a method definition
-            // (method definitions will be handled by checkMethod)
-            if (
-                funcNode.type === 'FunctionExpression' &&
-                funcNode['parent']?.type === 'MethodDefinition'
-            ) {
-                return;
-            }
-
-            // Skip if no location info or no body
-            if (!funcNode.loc || !funcNode.body) {
-                return;
-            }
-
-            // Get function name
-            let name = 'anonymous';
-            if (funcNode.type === 'FunctionDeclaration' && funcNode.id?.name) {
-                name = funcNode.id.name;
-            } else if (funcNode.type === 'FunctionExpression' && funcNode.id?.name) {
-                name = funcNode.id.name;
-            }
-
-            // Calculate line count
-            const startLine = funcNode.loc.start.line;
-            const endLine = funcNode.loc.end.line;
-            const lineCount = endLine - startLine + 1;
-
-            if (lineCount > maxLines) {
-                context.report({
-                    node: funcNode as any,
-                    messageId: 'tooLong',
-                    data: {
-                        name,
-                        actual: String(lineCount),
-                        max: String(maxLines),
-                    },
-                });
-            }
-        }
-
-        function checkMethod(node: any): void {
-            ensureMethodDoc(context);
-
-            const methodNode = node;
-
-            // Skip if no location info
-            if (!methodNode.loc || !methodNode.value) {
-                return;
-            }
-
-            // Get method name from key
-            const name = methodNode.key?.name || 'anonymous';
-
-            // Calculate line count for the method (including the method definition)
-            const startLine = methodNode.loc.start.line;
-            const endLine = methodNode.loc.end.line;
-            const lineCount = endLine - startLine + 1;
-
-            if (lineCount > maxLines) {
-                context.report({
-                    node: methodNode as any,
-                    messageId: 'tooLong',
-                    data: {
-                        name,
-                        actual: String(lineCount),
-                        max: String(maxLines),
-                    },
-                });
-            }
-        }
+        const ctx: CheckerContext = { context, maxLines: options?.max ?? 70 };
 
         return {
-            FunctionDeclaration: checkFunction,
-            FunctionExpression: checkFunction,
-            ArrowFunctionExpression: checkFunction,
-            MethodDefinition: checkMethod,
+            FunctionDeclaration: (node) => checkFunctionNode(ctx, node),
+            FunctionExpression: (node) => checkFunctionNode(ctx, node),
+            ArrowFunctionExpression: (node) => checkFunctionNode(ctx, node),
+            MethodDefinition: (node) => checkMethodNode(ctx, node),
         };
     },
 };

package/eslint-plugin/rules/no-unmanaged-exceptions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ESLint rule to discourage try-catch blocks outside test files
+ *
+ * Works alongside catch-error-pattern rule:
+ * - catch-error-pattern: Enforces HOW to handle exceptions (with toError())
+ * - no-unmanaged-exceptions: Enforces WHERE try-catch is allowed (tests only by default)
+ *
+ * Philosophy: Exceptions should bubble to global error handlers where they are logged
+ * with traceId and stored for debugging via /debugLocal and /debugCloud endpoints.
+ * Local try-catch blocks break this architecture and create blind spots in production.
+ *
+ * Auto-allowed in:
+ * - Test files (.test.ts, .spec.ts, __tests__/)
+ *
+ * Requires eslint-disable comment in:
+ * - Retry loops with exponential backoff
+ * - Batch processing where partial failure is expected
+ * - Resource cleanup (with approval)
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export = rule;