@webpieces/dev-config 0.0.0-dev

package/eslint-plugin/__tests__/max-method-lines.test.ts

@@ -0,0 +1,246 @@
+/**
+ * Tests for max-method-lines ESLint rule
+ */
+
+import { RuleTester } from 'eslint';
+import rule from '../rules/max-method-lines';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Use require to load parser at runtime (avoids TypeScript import issues)
+const tsParser = require('@typescript-eslint/parser');
+
+const ruleTester = new RuleTester({
+    languageOptions: {
+        parser: tsParser,
+        parserOptions: {
+            ecmaVersion: 2020,
+            sourceType: 'module',
+        },
+    },
+});
+
+ruleTester.run('max-method-lines', rule, {
+    valid: [
+        // Short function (well under limit)
+        {
+            code: `function shortFunc() {
+    return 42;
+}`,
+        },
+        // Function with exactly 70 lines (default limit)
+        {
+            code: `function exactlySeventyLines() {
+${Array(68)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+}`,
+        },
+        // Function with 69 lines (just under default limit)
+        {
+            code: `function sixtyNineLines() {
+${Array(67)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+}`,
+        },
+        // Custom limit: 10 lines
+        {
+            code: `function shortFunc() {
+    const a = 1;
+    const b = 2;
+    const c = 3;
+    const d = 4;
+    const e = 5;
+    const f = 6;
+    const g = 7;
+    return a + b + c + d + e + f + g;
+}`,
+            options: [{ max: 10 }],
+        },
+        // Arrow function under limit
+        {
+            code: `const shortArrow = () => {
+    return 42;
+};`,
+        },
+        // Method definition under limit
+        {
+            code: `class MyClass {
+    shortMethod() {
+        return 42;
+    }
+}`,
+        },
+        // Function expression under limit
+        {
+            code: `const func = function() {
+    return 42;
+};`,
+        },
+    ],
+
+    invalid: [
+        // Function with 71 lines (exceeds default limit)
+        {
+            code: `function tooLong() {
+${Array(69)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+}`,
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { name: 'tooLong', actual: '71', max: '70' },
+                },
+            ],
+        },
+        // Function with 100 lines (way over limit)
+        {
+            code: `function wayTooLong() {
+${Array(98)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+}`,
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { name: 'wayTooLong', actual: '100', max: '70' },
+                },
+            ],
+        },
+        // Custom limit: exceed 5 lines
+        {
+            code: `function tooLongForCustom() {
+    const a = 1;
+    const b = 2;
+    const c = 3;
+    const d = 4;
+    return a + b + c + d;
+}`,
+            options: [{ max: 5 }],
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { name: 'tooLongForCustom', actual: '7', max: '5' },
+                },
+            ],
+        },
+        // Arrow function exceeding limit
+        {
+            code: `const tooLongArrow = () => {
+${Array(69)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+};`,
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { name: 'anonymous', actual: '71', max: '70' },
+                },
+            ],
+        },
+        // Method definition exceeding limit
+        {
+            code: `class MyClass {
+    tooLongMethod() {
+${Array(69)
+    .fill(0)
+    .map((_, i) => `        const line${i} = ${i};`)
+    .join('\n')}
+    }
+}`,
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { name: 'tooLongMethod', actual: '71', max: '70' },
+                },
+            ],
+        },
+        // Function expression exceeding limit
+        {
+            code: `const func = function tooLongFunc() {
+${Array(69)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+};`,
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { name: 'tooLongFunc', actual: '71', max: '70' },
+                },
+            ],
+        },
+        // Multiple functions, one exceeds limit
+        {
+            code: `function shortFunc() {
+    return 42;
+}
+
+function tooLong() {
+${Array(69)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+}
+
+function anotherShort() {
+    return 24;
+}`,
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { name: 'tooLong', actual: '71', max: '70' },
+                },
+            ],
+        },
+    ],
+});
+
+console.log('✅ All max-method-lines rule tests passed!');
+
+// Test documentation file creation
+const docPath = path.join(process.cwd(), 'tmp', 'webpieces', 'webpieces.methods.md');
+
+// Run a test that triggers violation (will create doc file)
+try {
+    ruleTester.run('max-method-lines-doc-test', rule, {
+        valid: [],
+        invalid: [
+            {
+                code: `function veryLongMethod() {
+${Array(100)
+    .fill(0)
+    .map((_, i) => `    const line${i} = ${i};`)
+    .join('\n')}
+}`,
+                errors: [{ messageId: 'tooLong' }],
+            },
+        ],
+    });
+} catch (err: any) {
+    //const error = toError(err);
+    // Test may fail due to too many errors, but file should be created
+}
+
+// Verify file was created
+if (!fs.existsSync(docPath)) {
+    throw new Error('Documentation file was not created at ' + docPath);
+}
+
+// Verify content has AI directive
+const content = fs.readFileSync(docPath, 'utf-8');
+if (!content.includes('READ THIS FILE to fix methods that are too long')) {
+    throw new Error('Documentation file missing AI directive');
+}
+if (!content.includes('TABLE OF CONTENTS')) {
+    throw new Error('Documentation file missing table of contents principle');
+}
+
+console.log('✅ Documentation file creation test passed!');

package/eslint-plugin/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ESLint plugin for WebPieces
+ * Provides rules for enforcing WebPieces code patterns
+ *
+ * This plugin is automatically included in @webpieces/dev-config
+ */
+declare const _default: {
+    rules: {
+        'catch-error-pattern': import("eslint").Rule.RuleModule;
+        'max-method-lines': import("eslint").Rule.RuleModule;
+        'max-file-lines': import("eslint").Rule.RuleModule;
+    };
+};
+export = _default;

package/eslint-plugin/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * ESLint plugin for WebPieces
+ * Provides rules for enforcing WebPieces code patterns
+ *
+ * This plugin is automatically included in @webpieces/dev-config
+ */
+const tslib_1 = require("tslib");
+const catch_error_pattern_1 = tslib_1.__importDefault(require("./rules/catch-error-pattern"));
+const max_method_lines_1 = tslib_1.__importDefault(require("./rules/max-method-lines"));
+const max_file_lines_1 = tslib_1.__importDefault(require("./rules/max-file-lines"));
+module.exports = {
+    rules: {
+        'catch-error-pattern': catch_error_pattern_1.default,
+        'max-method-lines': max_method_lines_1.default,
+        'max-file-lines': max_file_lines_1.default,
+    },
+};
+//# sourceMappingURL=index.js.map

package/eslint-plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/dev-config/eslint-plugin/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAEH,8FAA4D;AAC5D,wFAAsD;AACtD,oFAAkD;AAElD,iBAAS;IACL,KAAK,EAAE;QACH,qBAAqB,EAAE,6BAAiB;QACxC,kBAAkB,EAAE,0BAAc;QAClC,gBAAgB,EAAE,wBAAY;KACjC;CACJ,CAAC","sourcesContent":["/**\n * ESLint plugin for WebPieces\n * Provides rules for enforcing WebPieces code patterns\n *\n * This plugin is automatically included in @webpieces/dev-config\n */\n\nimport catchErrorPattern from './rules/catch-error-pattern';\nimport maxMethodLines from './rules/max-method-lines';\nimport maxFileLines from './rules/max-file-lines';\n\nexport = {\n    rules: {\n        'catch-error-pattern': catchErrorPattern,\n        'max-method-lines': maxMethodLines,\n        'max-file-lines': maxFileLines,\n    },\n};\n"]}

package/eslint-plugin/index.ts

@@ -0,0 +1,18 @@
+/**
+ * ESLint plugin for WebPieces
+ * Provides rules for enforcing WebPieces code patterns
+ *
+ * This plugin is automatically included in @webpieces/dev-config
+ */
+
+import catchErrorPattern from './rules/catch-error-pattern';
+import maxMethodLines from './rules/max-method-lines';
+import maxFileLines from './rules/max-file-lines';
+
+export = {
+    rules: {
+        'catch-error-pattern': catchErrorPattern,
+        'max-method-lines': maxMethodLines,
+        'max-file-lines': maxFileLines,
+    },
+};

package/eslint-plugin/rules/catch-error-pattern.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ESLint rule to enforce standardized catch block error handling patterns
+ *
+ * Enforces three approved patterns:
+ * 1. Standard: catch (err: any) { const error = toError(err); }
+ * 2. Ignored: catch (err: any) { //const error = toError(err); }
+ * 3. Nested: catch (err2: any) { const error2 = toError(err2); }
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export = rule;

package/eslint-plugin/rules/catch-error-pattern.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * ESLint rule to enforce standardized catch block error handling patterns
+ *
+ * Enforces three approved patterns:
+ * 1. Standard: catch (err: any) { const error = toError(err); }
+ * 2. Ignored: catch (err: any) { //const error = toError(err); }
+ * 3. Nested: catch (err2: any) { const error2 = toError(err2); }
+ */
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce standardized catch block error handling patterns',
+            category: 'Best Practices',
+            recommended: true,
+            url: 'https://github.com/deanhiller/webpieces-ts/blob/main/claude.patterns.md#error-handling-pattern',
+        },
+        messages: {
+            missingToError: 'Catch block must call toError({{param}}) as first statement or comment it out to explicitly ignore errors',
+            wrongVariableName: 'Error variable must be named "{{expected}}", got "{{actual}}"',
+            missingTypeAnnotation: 'Catch parameter must be typed as "any": catch ({{param}}: any)',
+            wrongParameterName: 'Catch parameter must be named "err" (or "err2", "err3" for nested catches), got "{{actual}}"',
+            toErrorNotFirst: 'toError({{param}}) must be the first statement in the catch block',
+        },
+        fixable: undefined,
+        schema: [],
+    },
+    create(context) {
+        // Track nesting depth for err, err2, err3, etc.
+        const catchStack = [];
+        return {
+            CatchClause(node) {
+                const catchNode = node;
+                // Calculate depth (1-based: first catch is depth 1)
+                const depth = catchStack.length + 1;
+                catchStack.push(catchNode);
+                // Build expected names based on depth
+                const suffix = depth === 1 ? '' : String(depth);
+                const expectedParamName = 'err' + suffix;
+                const expectedVarName = 'error' + suffix;
+                // Get the catch parameter
+                const param = catchNode.param;
+                if (!param) {
+                    // No parameter - unusual but technically valid (though not our pattern)
+                    context.report({
+                        node: catchNode,
+                        messageId: 'missingTypeAnnotation',
+                        data: { param: expectedParamName },
+                    });
+                    return;
+                }
+                // Track the actual parameter name for validation (may differ from expected)
+                const actualParamName = param.type === 'Identifier' ? param.name : expectedParamName;
+                // RULE 1: Parameter must be named correctly (err, err2, err3, etc.)
+                if (param.type === 'Identifier' && param.name !== expectedParamName) {
+                    context.report({
+                        node: param,
+                        messageId: 'wrongParameterName',
+                        data: {
+                            actual: param.name,
+                        },
+                    });
+                }
+                // RULE 2: Must have type annotation ": any"
+                if (!param.typeAnnotation ||
+                    !param.typeAnnotation.typeAnnotation ||
+                    param.typeAnnotation.typeAnnotation.type !== 'TSAnyKeyword') {
+                    context.report({
+                        node: param,
+                        messageId: 'missingTypeAnnotation',
+                        data: {
+                            param: param.name || expectedParamName,
+                        },
+                    });
+                }
+                // RULE 3: Check first statement in catch block
+                const body = catchNode.body.body;
+                const sourceCode = context.sourceCode || context.getSourceCode();
+                // IMPORTANT: Check for commented ignore pattern FIRST (before checking if body is empty)
+                // This allows Pattern 2 (empty catch with only comment) to be valid
+                // Look for: //const error = toError(err);
+                const catchBlockStart = catchNode.body.range[0];
+                const catchBlockEnd = catchNode.body.range[1];
+                const catchBlockText = sourceCode.text.substring(catchBlockStart, catchBlockEnd);
+                const ignorePattern = new RegExp(`//\\s*const\\s+${expectedVarName}\\s*=\\s*toError\\(${actualParamName}\\)`);
+                if (ignorePattern.test(catchBlockText)) {
+                    // Pattern 2: Explicitly ignored - valid!
+                    return;
+                }
+                // Now check if body is empty (after checking for commented pattern)
+                if (body.length === 0) {
+                    // Empty catch block without comment - not allowed
+                    context.report({
+                        node: catchNode.body,
+                        messageId: 'missingToError',
+                        data: {
+                            param: expectedParamName,
+                        },
+                    });
+                    return;
+                }
+                const firstStatement = body[0];
+                // Check if first statement is: const error = toError(err)
+                if (firstStatement.type !== 'VariableDeclaration') {
+                    context.report({
+                        node: firstStatement,
+                        messageId: 'missingToError',
+                        data: {
+                            param: expectedParamName,
+                        },
+                    });
+                    return;
+                }
+                const varDecl = firstStatement;
+                const declaration = varDecl.declarations[0];
+                if (!declaration) {
+                    context.report({
+                        node: firstStatement,
+                        messageId: 'missingToError',
+                        data: {
+                            param: expectedParamName,
+                        },
+                    });
+                    return;
+                }
+                // Check variable name
+                if (declaration.id.type !== 'Identifier' ||
+                    declaration.id.name !== expectedVarName) {
+                    context.report({
+                        node: declaration.id,
+                        messageId: 'wrongVariableName',
+                        data: {
+                            expected: expectedVarName,
+                            actual: declaration.id.name || 'unknown',
+                        },
+                    });
+                    return;
+                }
+                // Check initialization: toError(err)
+                if (!declaration.init) {
+                    context.report({
+                        node: declaration,
+                        messageId: 'missingToError',
+                        data: {
+                            param: expectedParamName,
+                        },
+                    });
+                    return;
+                }
+                if (declaration.init.type !== 'CallExpression') {
+                    context.report({
+                        node: declaration.init,
+                        messageId: 'missingToError',
+                        data: {
+                            param: expectedParamName,
+                        },
+                    });
+                    return;
+                }
+                const callExpr = declaration.init;
+                const callee = callExpr.callee;
+                if (callee.type !== 'Identifier' || callee.name !== 'toError') {
+                    context.report({
+                        node: callee,
+                        messageId: 'missingToError',
+                        data: {
+                            param: expectedParamName,
+                        },
+                    });
+                    return;
+                }
+                // Check argument: must be the catch parameter (use actual param name)
+                const args = callExpr.arguments;
+                if (args.length !== 1 ||
+                    args[0].type !== 'Identifier' ||
+                    args[0].name !== actualParamName) {
+                    context.report({
+                        node: callExpr,
+                        messageId: 'missingToError',
+                        data: {
+                            param: actualParamName,
+                        },
+                    });
+                    return;
+                }
+                // All checks passed! ✅
+            },
+            'CatchClause:exit'() {
+                catchStack.pop();
+            },
+        };
+    },
+};
+module.exports = rule;
+//# sourceMappingURL=catch-error-pattern.js.map

package/eslint-plugin/rules/catch-error-pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catch-error-pattern.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/eslint-plugin/rules/catch-error-pattern.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ESLint rule to enforce standardized catch block error handling patterns\n *\n * Enforces three approved patterns:\n * 1. Standard: catch (err: any) { const error = toError(err); }\n * 2. Ignored: catch (err: any) { //const error = toError(err); }\n * 3. Nested: catch (err2: any) { const error2 = toError(err2); }\n */\n\nimport type { Rule } from 'eslint';\n\n// Using any for ESTree nodes to avoid complex type gymnastics\n// ESLint rules work with dynamic AST nodes anyway\ninterface CatchClauseNode {\n    type: 'CatchClause';\n    param?: IdentifierNode | null;\n    body: BlockStatementNode;\n    [key: string]: any;\n}\n\ninterface IdentifierNode {\n    type: 'Identifier';\n    name: string;\n    typeAnnotation?: TypeAnnotationNode;\n    [key: string]: any;\n}\n\ninterface TypeAnnotationNode {\n    typeAnnotation?: {\n        type: string;\n    };\n}\n\ninterface BlockStatementNode {\n    type: 'BlockStatement';\n    body: any[];\n    range: [number, number];\n    [key: string]: any;\n}\n\ninterface VariableDeclarationNode {\n    type: 'VariableDeclaration';\n    declarations: VariableDeclaratorNode[];\n    [key: string]: any;\n}\n\ninterface VariableDeclaratorNode {\n    type: 'VariableDeclarator';\n    id: IdentifierNode;\n    init?: CallExpressionNode | null;\n    [key: string]: any;\n}\n\ninterface CallExpressionNode {\n    type: 'CallExpression';\n    callee: IdentifierNode;\n    arguments: any[];\n    [key: string]: any;\n}\n\nconst rule: Rule.RuleModule = {\n    meta: {\n        type: 'problem',\n        docs: {\n            description: 'Enforce standardized catch block error handling patterns',\n            category: 'Best Practices',\n            recommended: true,\n            url: 'https://github.com/deanhiller/webpieces-ts/blob/main/claude.patterns.md#error-handling-pattern',\n        },\n        messages: {\n            missingToError:\n                'Catch block must call toError({{param}}) as first statement or comment it out to explicitly ignore errors',\n            wrongVariableName: 'Error variable must be named \"{{expected}}\", got \"{{actual}}\"',\n            missingTypeAnnotation: 'Catch parameter must be typed as \"any\": catch ({{param}}: any)',\n            wrongParameterName:\n                'Catch parameter must be named \"err\" (or \"err2\", \"err3\" for nested catches), got \"{{actual}}\"',\n            toErrorNotFirst: 'toError({{param}}) must be the first statement in the catch block',\n        },\n        fixable: undefined,\n        schema: [],\n    },\n\n    create(context: Rule.RuleContext): Rule.RuleListener {\n        // Track nesting depth for err, err2, err3, etc.\n        const catchStack: CatchClauseNode[] = [];\n\n        return {\n            CatchClause(node: any): void {\n                const catchNode = node as CatchClauseNode;\n\n                // Calculate depth (1-based: first catch is depth 1)\n                const depth = catchStack.length + 1;\n                catchStack.push(catchNode);\n\n                // Build expected names based on depth\n                const suffix = depth === 1 ? '' : String(depth);\n                const expectedParamName = 'err' + suffix;\n                const expectedVarName = 'error' + suffix;\n\n                // Get the catch parameter\n                const param = catchNode.param;\n                if (!param) {\n                    // No parameter - unusual but technically valid (though not our pattern)\n                    context.report({\n                        node: catchNode,\n                        messageId: 'missingTypeAnnotation',\n                        data: { param: expectedParamName },\n                    });\n                    return;\n                }\n\n                // Track the actual parameter name for validation (may differ from expected)\n                const actualParamName =\n                    param.type === 'Identifier' ? param.name : expectedParamName;\n\n                // RULE 1: Parameter must be named correctly (err, err2, err3, etc.)\n                if (param.type === 'Identifier' && param.name !== expectedParamName) {\n                    context.report({\n                        node: param,\n                        messageId: 'wrongParameterName',\n                        data: {\n                            actual: param.name,\n                        },\n                    });\n                }\n\n                // RULE 2: Must have type annotation \": any\"\n                if (\n                    !param.typeAnnotation ||\n                    !param.typeAnnotation.typeAnnotation ||\n                    param.typeAnnotation.typeAnnotation.type !== 'TSAnyKeyword'\n                ) {\n                    context.report({\n                        node: param,\n                        messageId: 'missingTypeAnnotation',\n                        data: {\n                            param: param.name || expectedParamName,\n                        },\n                    });\n                }\n\n                // RULE 3: Check first statement in catch block\n                const body = catchNode.body.body;\n                const sourceCode = context.sourceCode || context.getSourceCode();\n\n                // IMPORTANT: Check for commented ignore pattern FIRST (before checking if body is empty)\n                // This allows Pattern 2 (empty catch with only comment) to be valid\n                // Look for: //const error = toError(err);\n                const catchBlockStart = catchNode.body.range![0];\n                const catchBlockEnd = catchNode.body.range![1];\n                const catchBlockText = sourceCode.text.substring(catchBlockStart, catchBlockEnd);\n\n                const ignorePattern = new RegExp(\n                    `//\\\\s*const\\\\s+${expectedVarName}\\\\s*=\\\\s*toError\\\\(${actualParamName}\\\\)`,\n                );\n\n                if (ignorePattern.test(catchBlockText)) {\n                    // Pattern 2: Explicitly ignored - valid!\n                    return;\n                }\n\n                // Now check if body is empty (after checking for commented pattern)\n                if (body.length === 0) {\n                    // Empty catch block without comment - not allowed\n                    context.report({\n                        node: catchNode.body,\n                        messageId: 'missingToError',\n                        data: {\n                            param: expectedParamName,\n                        },\n                    });\n                    return;\n                }\n\n                const firstStatement = body[0];\n\n                // Check if first statement is: const error = toError(err)\n                if (firstStatement.type !== 'VariableDeclaration') {\n                    context.report({\n                        node: firstStatement,\n                        messageId: 'missingToError',\n                        data: {\n                            param: expectedParamName,\n                        },\n                    });\n                    return;\n                }\n\n                const varDecl = firstStatement as VariableDeclarationNode;\n                const declaration = varDecl.declarations[0];\n                if (!declaration) {\n                    context.report({\n                        node: firstStatement,\n                        messageId: 'missingToError',\n                        data: {\n                            param: expectedParamName,\n                        },\n                    });\n                    return;\n                }\n\n                // Check variable name\n                if (\n                    declaration.id.type !== 'Identifier' ||\n                    declaration.id.name !== expectedVarName\n                ) {\n                    context.report({\n                        node: declaration.id,\n                        messageId: 'wrongVariableName',\n                        data: {\n                            expected: expectedVarName,\n                            actual: declaration.id.name || 'unknown',\n                        },\n                    });\n                    return;\n                }\n\n                // Check initialization: toError(err)\n                if (!declaration.init) {\n                    context.report({\n                        node: declaration,\n                        messageId: 'missingToError',\n                        data: {\n                            param: expectedParamName,\n                        },\n                    });\n                    return;\n                }\n\n                if (declaration.init.type !== 'CallExpression') {\n                    context.report({\n                        node: declaration.init,\n                        messageId: 'missingToError',\n                        data: {\n                            param: expectedParamName,\n                        },\n                    });\n                    return;\n                }\n\n                const callExpr = declaration.init as CallExpressionNode;\n                const callee = callExpr.callee;\n                if (callee.type !== 'Identifier' || callee.name !== 'toError') {\n                    context.report({\n                        node: callee,\n                        messageId: 'missingToError',\n                        data: {\n                            param: expectedParamName,\n                        },\n                    });\n                    return;\n                }\n\n                // Check argument: must be the catch parameter (use actual param name)\n                const args = callExpr.arguments;\n                if (\n                    args.length !== 1 ||\n                    args[0].type !== 'Identifier' ||\n                    (args[0] as IdentifierNode).name !== actualParamName\n                ) {\n                    context.report({\n                        node: callExpr,\n                        messageId: 'missingToError',\n                        data: {\n                            param: actualParamName,\n                        },\n                    });\n                    return;\n                }\n\n                // All checks passed! ✅\n            },\n\n            'CatchClause:exit'(): void {\n                catchStack.pop();\n            },\n        };\n    },\n};\n\nexport = rule;\n"]}