@webpieces/eslint-plugin 0.0.0-dev

package/README.md

@@ -0,0 +1,11 @@
+# @webpieces/eslint-plugin
+
+ESLint plugin for WebPieces code patterns and architecture enforcement.
+
+## Rules
+
+- `catch-error-pattern` - Enforce toError() usage in catch blocks
+- `no-unmanaged-exceptions` - Discourage try-catch outside tests
+- `max-method-lines` - Enforce maximum method length
+- `max-file-lines` - Enforce maximum file length
+- `enforce-architecture` - Enforce architecture dependency boundaries

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@webpieces/eslint-plugin",
+  "version": "0.0.0-dev",
+  "description": "ESLint plugin for WebPieces code patterns and architecture enforcement",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/tooling/eslint-plugin"
+  },
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ESLint plugin for WebPieces
+ * Provides rules for enforcing WebPieces code patterns
+ *
+ * This plugin is automatically included in @webpieces/dev-config
+ *
+ * Available rules:
+ * - catch-error-pattern: Enforce toError() usage in catch blocks (HOW to handle)
+ * - no-unmanaged-exceptions: Discourage try-catch outside tests (WHERE to handle)
+ * - max-method-lines: Enforce maximum method length (default: 70 lines)
+ * - max-file-lines: Enforce maximum file length (default: 700 lines)
+ * - enforce-architecture: Enforce architecture dependency boundaries
+ */
+declare const _default: {
+    rules: {
+        'catch-error-pattern': import("eslint").Rule.RuleModule;
+        'no-unmanaged-exceptions': import("eslint").Rule.RuleModule;
+        'max-method-lines': import("eslint").Rule.RuleModule;
+        'max-file-lines': import("eslint").Rule.RuleModule;
+        'enforce-architecture': import("eslint").Rule.RuleModule;
+    };
+};
+export = _default;

package/src/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * ESLint plugin for WebPieces
+ * Provides rules for enforcing WebPieces code patterns
+ *
+ * This plugin is automatically included in @webpieces/dev-config
+ *
+ * Available rules:
+ * - catch-error-pattern: Enforce toError() usage in catch blocks (HOW to handle)
+ * - no-unmanaged-exceptions: Discourage try-catch outside tests (WHERE to handle)
+ * - max-method-lines: Enforce maximum method length (default: 70 lines)
+ * - max-file-lines: Enforce maximum file length (default: 700 lines)
+ * - enforce-architecture: Enforce architecture dependency boundaries
+ */
+const tslib_1 = require("tslib");
+const catch_error_pattern_1 = tslib_1.__importDefault(require("./rules/catch-error-pattern"));
+const no_unmanaged_exceptions_1 = tslib_1.__importDefault(require("./rules/no-unmanaged-exceptions"));
+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"));
+const enforce_architecture_1 = tslib_1.__importDefault(require("./rules/enforce-architecture"));
+module.exports = {
+    rules: {
+        'catch-error-pattern': catch_error_pattern_1.default,
+        'no-unmanaged-exceptions': no_unmanaged_exceptions_1.default,
+        'max-method-lines': max_method_lines_1.default,
+        'max-file-lines': max_file_lines_1.default,
+        'enforce-architecture': enforce_architecture_1.default,
+    },
+};
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/tooling/eslint-plugin/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAEH,8FAA4D;AAC5D,sGAAoE;AACpE,wFAAsD;AACtD,oFAAkD;AAClD,gGAA+D;AAE/D,iBAAS;IACL,KAAK,EAAE;QACH,qBAAqB,EAAE,6BAAiB;QACxC,yBAAyB,EAAE,iCAAqB;QAChD,kBAAkB,EAAE,0BAAc;QAClC,gBAAgB,EAAE,wBAAY;QAC9B,sBAAsB,EAAE,8BAAmB;KAC9C;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 * Available rules:\n * - catch-error-pattern: Enforce toError() usage in catch blocks (HOW to handle)\n * - no-unmanaged-exceptions: Discourage try-catch outside tests (WHERE to handle)\n * - max-method-lines: Enforce maximum method length (default: 70 lines)\n * - max-file-lines: Enforce maximum file length (default: 700 lines)\n * - enforce-architecture: Enforce architecture dependency boundaries\n */\n\nimport catchErrorPattern from './rules/catch-error-pattern';\nimport noUnmanagedExceptions from './rules/no-unmanaged-exceptions';\nimport maxMethodLines from './rules/max-method-lines';\nimport maxFileLines from './rules/max-file-lines';\nimport enforceArchitecture from './rules/enforce-architecture';\n\nexport = {\n    rules: {\n        'catch-error-pattern': catchErrorPattern,\n        'no-unmanaged-exceptions': noUnmanagedExceptions,\n        'max-method-lines': maxMethodLines,\n        'max-file-lines': maxFileLines,\n        'enforce-architecture': enforceArchitecture,\n    },\n};\n"]}

package/src/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: unknown) { const error = toError(err); }
+ * 2. Ignored: catch (err: unknown) { //const error = toError(err); }
+ * 3. Nested: catch (err2: unknown) { const error2 = toError(err2); }
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export = rule;

package/src/rules/catch-error-pattern.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * ESLint rule to enforce standardized catch block error handling patterns
+ *
+ * Enforces three approved patterns:
+ * 1. Standard: catch (err: unknown) { const error = toError(err); }
+ * 2. Ignored: catch (err: unknown) { //const error = toError(err); }
+ * 3. Nested: catch (err2: unknown) { const error2 = toError(err2); }
+ */
+function validateParamName(context, param, expectedParamName) {
+    if (param.type === 'Identifier' && param.name !== expectedParamName) {
+        context.report({
+            node: param,
+            messageId: 'wrongParameterName',
+            data: { actual: param.name },
+        });
+    }
+}
+function validateTypeAnnotation(context, param, expectedParamName) {
+    if (!param.typeAnnotation ||
+        !param.typeAnnotation.typeAnnotation ||
+        param.typeAnnotation.typeAnnotation.type !== 'TSUnknownKeyword') {
+        context.report({
+            node: param,
+            messageId: 'missingTypeAnnotation',
+            data: { param: param.name || expectedParamName },
+        });
+    }
+}
+function hasIgnoreComment(catchNode, sourceCode, expectedVarName, actualParamName) {
+    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}\\)`);
+    return ignorePattern.test(catchBlockText);
+}
+function reportMissingToError(context, 
+// webpieces-disable no-any-unknown -- ESLint AST node param requires any type
+node, paramName) {
+    context.report({
+        node,
+        messageId: 'missingToError',
+        data: { param: paramName },
+    });
+}
+function validateToErrorCall(context, 
+// webpieces-disable no-any-unknown -- ESLint AST node param requires any type
+firstStatement, expectedParamName, expectedVarName, actualParamName) {
+    if (firstStatement.type !== 'VariableDeclaration') {
+        reportMissingToError(context, firstStatement, expectedParamName);
+        return;
+    }
+    const varDecl = firstStatement;
+    const declaration = varDecl.declarations[0];
+    if (!declaration) {
+        reportMissingToError(context, firstStatement, expectedParamName);
+        return;
+    }
+    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;
+    }
+    if (!declaration.init || declaration.init.type !== 'CallExpression') {
+        reportMissingToError(context, declaration.init || declaration, expectedParamName);
+        return;
+    }
+    const callExpr = declaration.init;
+    const callee = callExpr.callee;
+    if (callee.type !== 'Identifier' || callee.name !== 'toError') {
+        reportMissingToError(context, callee, expectedParamName);
+        return;
+    }
+    const args = callExpr.arguments;
+    if (args.length !== 1 ||
+        args[0].type !== 'Identifier' ||
+        args[0].name !== actualParamName) {
+        reportMissingToError(context, callExpr, actualParamName);
+    }
+}
+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 "unknown": catch ({{param}}: unknown)',
+            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) {
+        const catchStack = [];
+        return {
+            // webpieces-disable no-any-unknown -- ESLint visitor callback receives untyped AST node
+            CatchClause(node) {
+                const catchNode = node;
+                const depth = catchStack.length + 1;
+                catchStack.push(catchNode);
+                const suffix = depth === 1 ? '' : String(depth);
+                const expectedParamName = 'err' + suffix;
+                const expectedVarName = 'error' + suffix;
+                const param = catchNode.param;
+                if (!param) {
+                    context.report({
+                        node: catchNode,
+                        messageId: 'missingTypeAnnotation',
+                        data: { param: expectedParamName },
+                    });
+                    return;
+                }
+                const actualParamName = param.type === 'Identifier' ? param.name : expectedParamName;
+                validateParamName(context, param, expectedParamName);
+                validateTypeAnnotation(context, param, expectedParamName);
+                const sourceCode = context.sourceCode || context.getSourceCode();
+                if (hasIgnoreComment(catchNode, sourceCode, expectedVarName, actualParamName)) {
+                    return;
+                }
+                const body = catchNode.body.body;
+                if (body.length === 0) {
+                    reportMissingToError(context, catchNode.body, expectedParamName);
+                    return;
+                }
+                validateToErrorCall(context, body[0], expectedParamName, expectedVarName, actualParamName);
+            },
+            'CatchClause:exit'() {
+                catchStack.pop();
+            },
+        };
+    },
+};
+module.exports = rule;
+//# sourceMappingURL=catch-error-pattern.js.map

package/src/rules/catch-error-pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catch-error-pattern.js","sourceRoot":"","sources":["../../../../../../packages/tooling/eslint-plugin/src/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: unknown) { const error = toError(err); }\n * 2. Ignored: catch (err: unknown) { //const error = toError(err); }\n * 3. Nested: catch (err2: unknown) { const error2 = toError(err2); }\n */\n\nimport type { Rule } from 'eslint';\n\n// webpieces-disable no-any-unknown -- ESTree AST node interfaces require any for dynamic properties\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    // webpieces-disable no-any-unknown -- ESTree AST index signature\n    [key: string]: any;\n}\n\ninterface IdentifierNode {\n    type: 'Identifier';\n    name: string;\n    typeAnnotation?: TypeAnnotationNode;\n    // webpieces-disable no-any-unknown -- ESTree AST index signature\n    [key: string]: any;\n}\n\ninterface TypeAnnotationNode {\n    typeAnnotation?: {\n        type: string;\n    };\n}\n\ninterface BlockStatementNode {\n    type: 'BlockStatement';\n    // webpieces-disable no-any-unknown -- ESTree AST dynamic body array\n    body: any[];\n    range: [number, number];\n    // webpieces-disable no-any-unknown -- ESTree AST index signature\n    [key: string]: any;\n}\n\ninterface VariableDeclarationNode {\n    type: 'VariableDeclaration';\n    declarations: VariableDeclaratorNode[];\n    // webpieces-disable no-any-unknown -- ESTree AST index signature\n    [key: string]: any;\n}\n\ninterface VariableDeclaratorNode {\n    type: 'VariableDeclarator';\n    id: IdentifierNode;\n    init?: CallExpressionNode | null;\n    // webpieces-disable no-any-unknown -- ESTree AST index signature\n    [key: string]: any;\n}\n\ninterface CallExpressionNode {\n    type: 'CallExpression';\n    callee: IdentifierNode;\n    // webpieces-disable no-any-unknown -- ESTree AST dynamic arguments array\n    arguments: any[];\n    // webpieces-disable no-any-unknown -- ESTree AST index signature\n    [key: string]: any;\n}\n\nfunction validateParamName(\n    context: Rule.RuleContext,\n    param: IdentifierNode,\n    expectedParamName: string,\n): void {\n    if (param.type === 'Identifier' && param.name !== expectedParamName) {\n        context.report({\n            node: param,\n            messageId: 'wrongParameterName',\n            data: { actual: param.name },\n        });\n    }\n}\n\nfunction validateTypeAnnotation(\n    context: Rule.RuleContext,\n    param: IdentifierNode,\n    expectedParamName: string,\n): void {\n    if (\n        !param.typeAnnotation ||\n        !param.typeAnnotation.typeAnnotation ||\n        param.typeAnnotation.typeAnnotation.type !== 'TSUnknownKeyword'\n    ) {\n        context.report({\n            node: param,\n            messageId: 'missingTypeAnnotation',\n            data: { param: param.name || expectedParamName },\n        });\n    }\n}\n\nfunction hasIgnoreComment(\n    catchNode: CatchClauseNode,\n    sourceCode: Rule.RuleContext['sourceCode'],\n    expectedVarName: string,\n    actualParamName: string,\n): boolean {\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    return ignorePattern.test(catchBlockText);\n}\n\nfunction reportMissingToError(\n    context: Rule.RuleContext,\n    // webpieces-disable no-any-unknown -- ESLint AST node param requires any type\n    node: any,\n    paramName: string,\n): void {\n    context.report({\n        node,\n        messageId: 'missingToError',\n        data: { param: paramName },\n    });\n}\n\nfunction validateToErrorCall(\n    context: Rule.RuleContext,\n    // webpieces-disable no-any-unknown -- ESLint AST node param requires any type\n    firstStatement: any,\n    expectedParamName: string,\n    expectedVarName: string,\n    actualParamName: string,\n): void {\n    if (firstStatement.type !== 'VariableDeclaration') {\n        reportMissingToError(context, firstStatement, expectedParamName);\n        return;\n    }\n\n    const varDecl = firstStatement as VariableDeclarationNode;\n    const declaration = varDecl.declarations[0];\n    if (!declaration) {\n        reportMissingToError(context, firstStatement, expectedParamName);\n        return;\n    }\n\n    if (declaration.id.type !== 'Identifier' || declaration.id.name !== expectedVarName) {\n        context.report({\n            node: declaration.id,\n            messageId: 'wrongVariableName',\n            data: { expected: expectedVarName, actual: declaration.id.name || 'unknown' },\n        });\n        return;\n    }\n\n    if (!declaration.init || declaration.init.type !== 'CallExpression') {\n        reportMissingToError(context, declaration.init || declaration, expectedParamName);\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        reportMissingToError(context, callee, expectedParamName);\n        return;\n    }\n\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        reportMissingToError(context, callExpr, actualParamName);\n    }\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 \"unknown\": catch ({{param}}: unknown)',\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        const catchStack: CatchClauseNode[] = [];\n\n        return {\n            // webpieces-disable no-any-unknown -- ESLint visitor callback receives untyped AST node\n            CatchClause(node: any): void {\n                const catchNode = node as CatchClauseNode;\n                const depth = catchStack.length + 1;\n                catchStack.push(catchNode);\n\n                const suffix = depth === 1 ? '' : String(depth);\n                const expectedParamName = 'err' + suffix;\n                const expectedVarName = 'error' + suffix;\n\n                const param = catchNode.param;\n                if (!param) {\n                    context.report({\n                        node: catchNode,\n                        messageId: 'missingTypeAnnotation',\n                        data: { param: expectedParamName },\n                    });\n                    return;\n                }\n\n                const actualParamName =\n                    param.type === 'Identifier' ? param.name : expectedParamName;\n\n                validateParamName(context, param, expectedParamName);\n                validateTypeAnnotation(context, param, expectedParamName);\n\n                const sourceCode = context.sourceCode || context.getSourceCode();\n                if (hasIgnoreComment(catchNode, sourceCode, expectedVarName, actualParamName)) {\n                    return;\n                }\n\n                const body = catchNode.body.body;\n                if (body.length === 0) {\n                    reportMissingToError(context, catchNode.body, expectedParamName);\n                    return;\n                }\n\n                validateToErrorCall(context, body[0], expectedParamName, expectedVarName, actualParamName);\n            },\n\n            'CatchClause:exit'(): void {\n                catchStack.pop();\n            },\n        };\n    },\n};\n\nexport = rule;\n"]}

package/src/rules/enforce-architecture.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ESLint rule to enforce architecture boundaries
+ *
+ * Validates that imports from @webpieces/* packages comply with the
+ * blessed dependency graph in .graphs/dependencies.json
+ *
+ * Supports transitive dependencies: if A depends on B and B depends on C,
+ * then A can import from C.
+ *
+ * Configuration:
+ * '@webpieces/enforce-architecture': 'error'
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export = rule;