@webpieces/dev-config 0.0.0-dev

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

@@ -0,0 +1,281 @@
+/**
+ * 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';
+
+// Using any for ESTree nodes to avoid complex type gymnastics
+// ESLint rules work with dynamic AST nodes anyway
+interface CatchClauseNode {
+    type: 'CatchClause';
+    param?: IdentifierNode | null;
+    body: BlockStatementNode;
+    [key: string]: any;
+}
+
+interface IdentifierNode {
+    type: 'Identifier';
+    name: string;
+    typeAnnotation?: TypeAnnotationNode;
+    [key: string]: any;
+}
+
+interface TypeAnnotationNode {
+    typeAnnotation?: {
+        type: string;
+    };
+}
+
+interface BlockStatementNode {
+    type: 'BlockStatement';
+    body: any[];
+    range: [number, number];
+    [key: string]: any;
+}
+
+interface VariableDeclarationNode {
+    type: 'VariableDeclaration';
+    declarations: VariableDeclaratorNode[];
+    [key: string]: any;
+}
+
+interface VariableDeclaratorNode {
+    type: 'VariableDeclarator';
+    id: IdentifierNode;
+    init?: CallExpressionNode | null;
+    [key: string]: any;
+}
+
+interface CallExpressionNode {
+    type: 'CallExpression';
+    callee: IdentifierNode;
+    arguments: any[];
+    [key: string]: any;
+}
+
+const rule: Rule.RuleModule = {
+    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: Rule.RuleContext): Rule.RuleListener {
+        // Track nesting depth for err, err2, err3, etc.
+        const catchStack: CatchClauseNode[] = [];
+
+        return {
+            CatchClause(node: any): void {
+                const catchNode = node as CatchClauseNode;
+
+                // 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 as VariableDeclarationNode;
+                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 as CallExpressionNode;
+                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] as IdentifierNode).name !== actualParamName
+                ) {
+                    context.report({
+                        node: callExpr,
+                        messageId: 'missingToError',
+                        data: {
+                            param: actualParamName,
+                        },
+                    });
+                    return;
+                }
+
+                // All checks passed! ✅
+            },
+
+            'CatchClause:exit'(): void {
+                catchStack.pop();
+            },
+        };
+    },
+};
+
+export = rule;

package/eslint-plugin/rules/max-file-lines.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ESLint rule to enforce maximum file length
+ *
+ * Enforces a configurable maximum line count for files.
+ * Default: 700 lines
+ *
+ * Configuration:
+ * '@webpieces/max-file-lines': ['error', { max: 700 }]
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export = rule;

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

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * ESLint rule to enforce maximum file length
+ *
+ * Enforces a configurable maximum line count for files.
+ * Default: 700 lines
+ *
+ * Configuration:
+ * '@webpieces/max-file-lines': ['error', { max: 700 }]
+ */
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const FILE_DOC_CONTENT = `# AI Agent Instructions: File Too Long
+
+**READ THIS FILE to fix files that are too long**
+
+## Core Principle
+Files should contain a SINGLE COHESIVE UNIT.
+- One class per file (Java convention)
+- If class is too large, extract child responsibilities
+- Use dependency injection to compose functionality
+
+## Command: Reduce File Size
+
+### Step 1: Check for Multiple Classes
+If the file contains multiple classes, **SEPARATE each class into its own file**.
+
+\`\`\`typescript
+// ❌ BAD: UserController.ts (multiple classes)
+export class UserController { /* ... */ }
+export class UserValidator { /* ... */ }
+export class UserNotifier { /* ... */ }
+
+// ✅ GOOD: Three separate files
+// UserController.ts
+export class UserController { /* ... */ }
+
+// UserValidator.ts
+export class UserValidator { /* ... */ }
+
+// UserNotifier.ts
+export class UserNotifier { /* ... */ }
+\`\`\`
+
+### Step 2: Extract Child Responsibilities (if single class is too large)
+
+#### Pattern: Create New Service Class with Dependency Injection
+
+\`\`\`typescript
+// ❌ BAD: UserController.ts (800 lines, single class)
+@provideSingleton()
+@Controller()
+export class UserController {
+  // 200 lines: CRUD operations
+  // 300 lines: validation logic
+  // 200 lines: notification logic
+  // 100 lines: analytics logic
+}
+
+// ✅ GOOD: Extract validation service
+// 1. Create UserValidationService.ts
+@provideSingleton()
+export class UserValidationService {
+  validateUserData(data: UserData): ValidationResult {
+    // 300 lines of validation logic moved here
+  }
+
+  validateEmail(email: string): boolean { /* ... */ }
+  validatePassword(password: string): boolean { /* ... */ }
+}
+
+// 2. Inject into UserController.ts
+@provideSingleton()
+@Controller()
+export class UserController {
+  constructor(
+    @inject(TYPES.UserValidationService)
+    private validator: UserValidationService
+  ) {}
+
+  async createUser(data: UserData): Promise<User> {
+    const validation = this.validator.validateUserData(data);
+    if (!validation.isValid) {
+      throw new ValidationError(validation.errors);
+    }
+    // ... rest of logic
+  }
+}
+\`\`\`
+
+## AI Agent Action Steps
+
+1. **ANALYZE** the file structure:
+   - Count classes (if >1, separate immediately)
+   - Identify logical responsibilities within single class
+
+2. **IDENTIFY** "child code" to extract:
+   - Validation logic → ValidationService
+   - Notification logic → NotificationService
+   - Data transformation → TransformerService
+   - External API calls → ApiService
+   - Business rules → RulesEngine
+
+3. **CREATE** new service file(s):
+   - Start with temporary name: \`XXXX.ts\` or \`ChildService.ts\`
+   - Add \`@provideSingleton()\` decorator
+   - Move child methods to new class
+
+4. **UPDATE** dependency injection:
+   - Add to \`TYPES\` constants (if using symbol-based DI)
+   - Inject new service into original class constructor
+   - Replace direct method calls with \`this.serviceName.method()\`
+
+5. **RENAME** extracted file:
+   - Read the extracted code to understand its purpose
+   - Rename \`XXXX.ts\` to logical name (e.g., \`UserValidationService.ts\`)
+
+6. **VERIFY** file sizes:
+   - Original file should now be <700 lines
+   - Each extracted file should be <700 lines
+   - If still too large, extract more services
+
+## Examples of Child Responsibilities to Extract
+
+| If File Contains | Extract To | Pattern |
+|-----------------|------------|---------|
+| Validation logic (200+ lines) | \`XValidator.ts\` or \`XValidationService.ts\` | Singleton service |
+| Notification logic (150+ lines) | \`XNotifier.ts\` or \`XNotificationService.ts\` | Singleton service |
+| Data transformation (200+ lines) | \`XTransformer.ts\` | Singleton service |
+| External API calls (200+ lines) | \`XApiClient.ts\` | Singleton service |
+| Complex business rules (300+ lines) | \`XRulesEngine.ts\` | Singleton service |
+| Database queries (200+ lines) | \`XRepository.ts\` | Singleton service |
+
+## WebPieces Dependency Injection Pattern
+
+\`\`\`typescript
+// 1. Define service with @provideSingleton
+import { provideSingleton } from '@webpieces/http-routing';
+
+@provideSingleton()
+export class MyService {
+  doSomething(): void { /* ... */ }
+}
+
+// 2. Inject into consumer
+import { inject } from 'inversify';
+import { TYPES } from './types';
+
+@provideSingleton()
+@Controller()
+export class MyController {
+  constructor(
+    @inject(TYPES.MyService) private service: MyService
+  ) {}
+}
+\`\`\`
+
+Remember: Find the "child code" and pull it down into a new class. Once moved, the code's purpose becomes clear, making it easy to rename to a logical name.
+`;
+// Module-level flag to prevent redundant file creation
+let fileDocCreated = 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)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.workspaces || pkg.name === 'webpieces-ts') {
+                    return dir;
+                }
+            }
+            catch (err) {
+                //const error = toError(err);
+                // Continue searching if JSON parse fails
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return process.cwd(); // Fallback
+}
+function ensureDocFile(docPath, content) {
+    try {
+        fs.mkdirSync(path.dirname(docPath), { recursive: true });
+        fs.writeFileSync(docPath, content, 'utf-8');
+        return true;
+    }
+    catch (err) {
+        //const error = toError(err);
+        // Graceful degradation: log warning but don't break lint
+        console.warn(`[webpieces] Could not create doc file: ${docPath}`, err);
+        return false;
+    }
+}
+function ensureFileDoc(context) {
+    if (fileDocCreated)
+        return; // Performance: only create once per lint run
+    const workspaceRoot = getWorkspaceRoot(context);
+    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.filesize.md');
+    if (ensureDocFile(docPath, FILE_DOC_CONTENT)) {
+        fileDocCreated = true;
+    }
+}
+const rule = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforce maximum file length',
+            category: 'Best Practices',
+            recommended: false,
+            url: 'https://github.com/deanhiller/webpieces-ts',
+        },
+        messages: {
+            tooLong: 'AI Agent: READ tmp/webpieces/webpieces.filesize.md for fix instructions. File has {{actual}} lines (max: {{max}})',
+        },
+        fixable: undefined,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: {
+                        type: 'integer',
+                        minimum: 1,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    create(context) {
+        const options = context.options[0];
+        const maxLines = options?.max ?? 700;
+        return {
+            Program(node) {
+                ensureFileDoc(context);
+                const sourceCode = context.sourceCode || context.getSourceCode();
+                const lines = sourceCode.lines;
+                const lineCount = lines.length;
+                if (lineCount > maxLines) {
+                    context.report({
+                        node,
+                        messageId: 'tooLong',
+                        data: {
+                            actual: String(lineCount),
+                            max: String(maxLines),
+                        },
+                    });
+                }
+            },
+        };
+    },
+};
+module.exports = rule;
+//# sourceMappingURL=max-file-lines.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"max-file-lines.js","sourceRoot":"","sources":["../../../../../../packages/tooling/dev-config/eslint-plugin/rules/max-file-lines.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ESLint rule to enforce maximum file length\n *\n * Enforces a configurable maximum line count for files.\n * Default: 700 lines\n *\n * Configuration:\n * '@webpieces/max-file-lines': ['error', { max: 700 }]\n */\n\nimport type { Rule } from 'eslint';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\ninterface FileLinesOptions {\n    max: number;\n}\n\nconst FILE_DOC_CONTENT = `# AI Agent Instructions: File Too Long\n\n**READ THIS FILE to fix files that are too long**\n\n## Core Principle\nFiles should contain a SINGLE COHESIVE UNIT.\n- One class per file (Java convention)\n- If class is too large, extract child responsibilities\n- Use dependency injection to compose functionality\n\n## Command: Reduce File Size\n\n### Step 1: Check for Multiple Classes\nIf the file contains multiple classes, **SEPARATE each class into its own file**.\n\n\\`\\`\\`typescript\n// ❌ BAD: UserController.ts (multiple classes)\nexport class UserController { /* ... */ }\nexport class UserValidator { /* ... */ }\nexport class UserNotifier { /* ... */ }\n\n// ✅ GOOD: Three separate files\n// UserController.ts\nexport class UserController { /* ... */ }\n\n// UserValidator.ts\nexport class UserValidator { /* ... */ }\n\n// UserNotifier.ts\nexport class UserNotifier { /* ... */ }\n\\`\\`\\`\n\n### Step 2: Extract Child Responsibilities (if single class is too large)\n\n#### Pattern: Create New Service Class with Dependency Injection\n\n\\`\\`\\`typescript\n// ❌ BAD: UserController.ts (800 lines, single class)\n@provideSingleton()\n@Controller()\nexport class UserController {\n  // 200 lines: CRUD operations\n  // 300 lines: validation logic\n  // 200 lines: notification logic\n  // 100 lines: analytics logic\n}\n\n// ✅ GOOD: Extract validation service\n// 1. Create UserValidationService.ts\n@provideSingleton()\nexport class UserValidationService {\n  validateUserData(data: UserData): ValidationResult {\n    // 300 lines of validation logic moved here\n  }\n\n  validateEmail(email: string): boolean { /* ... */ }\n  validatePassword(password: string): boolean { /* ... */ }\n}\n\n// 2. Inject into UserController.ts\n@provideSingleton()\n@Controller()\nexport class UserController {\n  constructor(\n    @inject(TYPES.UserValidationService)\n    private validator: UserValidationService\n  ) {}\n\n  async createUser(data: UserData): Promise<User> {\n    const validation = this.validator.validateUserData(data);\n    if (!validation.isValid) {\n      throw new ValidationError(validation.errors);\n    }\n    // ... rest of logic\n  }\n}\n\\`\\`\\`\n\n## AI Agent Action Steps\n\n1. **ANALYZE** the file structure:\n   - Count classes (if >1, separate immediately)\n   - Identify logical responsibilities within single class\n\n2. **IDENTIFY** \"child code\" to extract:\n   - Validation logic → ValidationService\n   - Notification logic → NotificationService\n   - Data transformation → TransformerService\n   - External API calls → ApiService\n   - Business rules → RulesEngine\n\n3. **CREATE** new service file(s):\n   - Start with temporary name: \\`XXXX.ts\\` or \\`ChildService.ts\\`\n   - Add \\`@provideSingleton()\\` decorator\n   - Move child methods to new class\n\n4. **UPDATE** dependency injection:\n   - Add to \\`TYPES\\` constants (if using symbol-based DI)\n   - Inject new service into original class constructor\n   - Replace direct method calls with \\`this.serviceName.method()\\`\n\n5. **RENAME** extracted file:\n   - Read the extracted code to understand its purpose\n   - Rename \\`XXXX.ts\\` to logical name (e.g., \\`UserValidationService.ts\\`)\n\n6. **VERIFY** file sizes:\n   - Original file should now be <700 lines\n   - Each extracted file should be <700 lines\n   - If still too large, extract more services\n\n## Examples of Child Responsibilities to Extract\n\n| If File Contains | Extract To | Pattern |\n|-----------------|------------|---------|\n| Validation logic (200+ lines) | \\`XValidator.ts\\` or \\`XValidationService.ts\\` | Singleton service |\n| Notification logic (150+ lines) | \\`XNotifier.ts\\` or \\`XNotificationService.ts\\` | Singleton service |\n| Data transformation (200+ lines) | \\`XTransformer.ts\\` | Singleton service |\n| External API calls (200+ lines) | \\`XApiClient.ts\\` | Singleton service |\n| Complex business rules (300+ lines) | \\`XRulesEngine.ts\\` | Singleton service |\n| Database queries (200+ lines) | \\`XRepository.ts\\` | Singleton service |\n\n## WebPieces Dependency Injection Pattern\n\n\\`\\`\\`typescript\n// 1. Define service with @provideSingleton\nimport { provideSingleton } from '@webpieces/http-routing';\n\n@provideSingleton()\nexport class MyService {\n  doSomething(): void { /* ... */ }\n}\n\n// 2. Inject into consumer\nimport { inject } from 'inversify';\nimport { TYPES } from './types';\n\n@provideSingleton()\n@Controller()\nexport class MyController {\n  constructor(\n    @inject(TYPES.MyService) private service: MyService\n  ) {}\n}\n\\`\\`\\`\n\nRemember: Find the \"child code\" and pull it down into a new class. Once moved, the code's purpose becomes clear, making it easy to rename to a logical name.\n`;\n\n// Module-level flag to prevent redundant file creation\nlet fileDocCreated = 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 ensureFileDoc(context: Rule.RuleContext): void {\n    if (fileDocCreated) return; // Performance: only create once per lint run\n\n    const workspaceRoot = getWorkspaceRoot(context);\n    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.filesize.md');\n\n    if (ensureDocFile(docPath, FILE_DOC_CONTENT)) {\n        fileDocCreated = true;\n    }\n}\n\nconst rule: Rule.RuleModule = {\n    meta: {\n        type: 'suggestion',\n        docs: {\n            description: 'Enforce maximum file 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.filesize.md for fix instructions. File 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 FileLinesOptions | undefined;\n        const maxLines = options?.max ?? 700;\n\n        return {\n            Program(node: any): void {\n                ensureFileDoc(context);\n\n                const sourceCode = context.sourceCode || context.getSourceCode();\n                const lines = sourceCode.lines;\n                const lineCount = lines.length;\n\n                if (lineCount > maxLines) {\n                    context.report({\n                        node,\n                        messageId: 'tooLong',\n                        data: {\n                            actual: String(lineCount),\n                            max: String(maxLines),\n                        },\n                    });\n                }\n            },\n        };\n    },\n};\n\nexport = rule;\n"]}