@webpieces/eslint-rules 0.0.1

package/src/rules/max-file-lines.ts

@@ -0,0 +1,275 @@
+/**
+ * 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';
+import * as fs from 'fs';
+import * as path from 'path';
+import { toError } from '../toError';
+
+interface FileLinesOptions {
+    max: number;
+}
+
+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: 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)) {
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.workspaces || pkg.name === 'webpieces-ts') {
+                    return dir;
+                }
+            } catch (err: unknown) {
+                //const error = toError(err);
+                void err; // Continue searching if JSON parse fails
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return process.cwd(); // Fallback
+}
+
+function ensureDocFile(docPath: string, content: string): boolean {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        fs.mkdirSync(path.dirname(docPath), { recursive: true });
+        fs.writeFileSync(docPath, content, 'utf-8');
+        return true;
+    } catch (err: unknown) {
+        const error = toError(err);
+        console.warn(`[webpieces] Could not create doc file: ${docPath}`, error);
+        return false;
+    }
+}
+
+function ensureFileDoc(context: Rule.RuleContext): void {
+    if (fileDocCreated) return; // Performance: only create once per lint run
+
+    const workspaceRoot = getWorkspaceRoot(context);
+    const docPath = path.join(workspaceRoot, '.webpieces', 'instruct-ai', 'webpieces.filesize.md');
+
+    if (ensureDocFile(docPath, FILE_DOC_CONTENT)) {
+        fileDocCreated = true;
+    }
+}
+
+const rule: Rule.RuleModule = {
+    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 .webpieces/instruct-ai/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: Rule.RuleContext): Rule.RuleListener {
+        const options = context.options[0] as FileLinesOptions | undefined;
+        const maxLines = options?.max ?? 700;
+
+        return {
+            // webpieces-disable no-any-unknown -- ESTree AST nodes require any for dynamic properties
+            Program(node: any): void {
+                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),
+                        },
+                    });
+                }
+            },
+        };
+    },
+};
+
+export = rule;

package/src/rules/max-method-lines.ts

@@ -0,0 +1,296 @@
+/**
+ * ESLint rule to enforce maximum method length
+ *
+ * Enforces a configurable maximum line count for methods, functions, and arrow functions.
+ * Default: 70 lines
+ *
+ * Configuration:
+ * '@webpieces/max-method-lines': ['error', { max: 70 }]
+ */
+
+import type { Rule } from 'eslint';
+import * as fs from 'fs';
+import * as path from 'path';
+import { toError } from '../toError';
+
+interface MethodLinesOptions {
+    max: number;
+}
+
+// webpieces-disable no-any-unknown -- ESTree AST nodes require any for dynamic properties
+interface FunctionNode {
+    type:
+        | 'FunctionDeclaration'
+        | 'FunctionExpression'
+        | 'ArrowFunctionExpression'
+        | 'MethodDefinition';
+    // webpieces-disable no-any-unknown -- ESTree AST dynamic body
+    body?: any;
+    loc?: {
+        start: { line: number };
+        end: { line: number };
+    };
+    key?: {
+        name?: string;
+    };
+    id?: {
+        name?: string;
+    };
+    // webpieces-disable no-any-unknown -- ESTree AST nodes require any for dynamic properties
+    [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**
+
+## Core Principle
+Every method should read like a TABLE OF CONTENTS of a book.
+- Each method call is a "chapter"
+- When you dive into a method, you find another table of contents
+- Keeping methods under 70 lines is achievable with proper extraction
+
+## Command: Extract Code into Named Methods
+
+### Pattern 1: Extract Loop Bodies
+\`\`\`typescript
+// 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
+for (const order of orders) {
+  validateOrder(order);
+  processOrderItems(order);
+  sendNotifications(order);
+}
+\`\`\`
+
+### Pattern 2: Try-Catch Wrapper for Exception Handling
+\`\`\`typescript
+// GOOD: Separates success path from error handling
+async function handleRequest(req: Request): Promise<Response> {
+  // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+  try {
+    return await executeRequest(req);
+  } catch (err: unknown) {
+    const error = toError(err);
+    return createErrorResponse(error);
+  }
+}
+\`\`\`
+
+### Pattern 3: Sequential Method Calls (Table of Contents)
+\`\`\`typescript
+// GOOD: Self-documenting steps
+function processOrder(order: Order): void {
+  validateOrderData(order);
+  calculateTotals(order);
+  applyDiscounts(order);
+  processPayment(order);
+  updateInventory(order);
+  sendConfirmation(order);
+}
+\`\`\`
+
+### Pattern 4: Separate Data Object Creation
+\`\`\`typescript
+// BAD: 15 lines of inline object creation
+doSomething({ field1: ..., field2: ..., field3: ..., /* 15 more fields */ });
+
+// GOOD: Extract to factory method
+const request = createRequestObject(data);
+doSomething(request);
+\`\`\`
+
+### Pattern 5: Extract Inline Logic to Named Functions
+\`\`\`typescript
+// BAD: Complex inline logic
+if (user.role === 'admin' && user.permissions.includes('write') && !user.suspended) {
+  // 30 lines of admin logic
+}
+
+// GOOD: Extract to named methods
+if (isAdminWithWriteAccess(user)) {
+  performAdminOperation(user);
+}
+\`\`\`
+
+## AI Agent Action Steps
+
+1. **IDENTIFY** the long method in the error message
+2. **READ** the method to understand its logical sections
+3. **EXTRACT** logical units into separate methods with descriptive names
+4. **REPLACE** inline code with method calls
+5. **VERIFY** each extracted method is <70 lines
+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()\`
+
+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.
+`;
+
+// Module-level flag to prevent redundant file creation
+let methodDocCreated = false;
+
+function getWorkspaceRoot(context: Rule.RuleContext): string {
+    const filename = context.filename || context.getFilename();
+    let dir = path.dirname(filename);
+
+    while (dir !== path.dirname(dir)) {
+        const pkgPath = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.workspaces || pkg.name === 'webpieces-ts') {
+                    return dir;
+                }
+            } catch (err: unknown) {
+                //const error = toError(err);
+                void err;
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return process.cwd();
+}
+
+function ensureDocFile(docPath: string, content: string): boolean {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        fs.mkdirSync(path.dirname(docPath), { recursive: true });
+        fs.writeFileSync(docPath, content, 'utf-8');
+        return true;
+    } catch (err: unknown) {
+        const error = toError(err);
+        console.warn(`[webpieces] Could not create doc file: ${docPath}`, error);
+        return false;
+    }
+}
+
+function ensureMethodDoc(context: Rule.RuleContext): void {
+    const workspaceRoot = getWorkspaceRoot(context);
+    const docPath = path.join(workspaceRoot, '.webpieces', 'instruct-ai', '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';
+}
+
+// webpieces-disable no-any-unknown -- ESTree AST nodes require any for dynamic properties
+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),
+        },
+    });
+}
+
+// webpieces-disable no-any-unknown -- ESTree AST nodes require any for dynamic properties
+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);
+    }
+}
+
+// webpieces-disable no-any-unknown -- ESTree AST nodes require any for dynamic properties
+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',
+        docs: {
+            description: 'Enforce maximum method length',
+            category: 'Best Practices',
+            recommended: false,
+            url: 'https://github.com/deanhiller/webpieces-ts',
+        },
+        messages: {
+            tooLong:
+                'AI Agent: READ .webpieces/instruct-ai/webpieces.methods.md for fix instructions. Method "{{name}}" has {{actual}} lines (max: {{max}})',
+        },
+        fixable: undefined,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: {
+                        type: 'integer',
+                        minimum: 1,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+
+    create(context: Rule.RuleContext): Rule.RuleListener {
+        const options = context.options[0] as MethodLinesOptions | undefined;
+        const ctx: CheckerContext = { context, maxLines: options?.max ?? 70 };
+
+        return {
+            FunctionDeclaration: (node) => checkFunctionNode(ctx, node),
+            FunctionExpression: (node) => checkFunctionNode(ctx, node),
+            ArrowFunctionExpression: (node) => checkFunctionNode(ctx, node),
+            MethodDefinition: (node) => checkMethodNode(ctx, node),
+        };
+    },
+};
+
+export = rule;

package/src/rules/no-json-property-primitive-type.ts

@@ -0,0 +1,85 @@
+/**
+ * ESLint rule: no-json-property-primitive-type
+ *
+ * Bans @JsonProperty({ type: String }), @JsonProperty({ type: Number }),
+ * and @JsonProperty({ type: Boolean }).
+ *
+ * These pass the TypeScript build but break production deserialization.
+ * The typescript-json-serializer `type` option expects class constructors,
+ * not JavaScript primitive constructors.
+ *
+ * Correct usage:
+ *   @JsonProperty()                      - for primitive arrays (string[], number[], boolean[])
+ *   @JsonProperty({ type: MyDtoClass })  - for class types only
+ */
+
+import type { Rule } from 'eslint';
+
+// webpieces-disable no-any-unknown -- ESTree AST node interfaces require any for dynamic properties
+interface CallExpressionNode {
+    type: 'CallExpression';
+    // webpieces-disable no-any-unknown -- ESTree AST dynamic callee
+    callee: { name?: string; [key: string]: any };
+    // webpieces-disable no-any-unknown -- ESTree AST dynamic arguments array
+    arguments: any[];
+    // webpieces-disable no-any-unknown -- ESTree AST index signature
+    [key: string]: any;
+}
+
+interface ObjectExpressionNode {
+    type: 'ObjectExpression';
+    properties: PropertyNode[];
+}
+
+interface PropertyNode {
+    key?: { name?: string };
+    value?: { type?: string; name?: string };
+    // webpieces-disable no-any-unknown -- ESTree AST index signature
+    [key: string]: any;
+}
+
+const BANNED_PRIMITIVES = ['String', 'Number', 'Boolean'];
+
+const rule: Rule.RuleModule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Ban @JsonProperty({ type: String/Number/Boolean }) — breaks production deserialization',
+        },
+        messages: {
+            noPrimitiveType:
+                '@JsonProperty({ type: {{ primitive }} }) breaks production deserialization. ' +
+                'For primitive arrays (string[], number[], boolean[]), use @JsonProperty() with ' +
+                'no type parameter. The type option is only for class types: ' +
+                '@JsonProperty({ type: MyDtoClass }).',
+        },
+        schema: [],
+    },
+    create(context: Rule.RuleContext): Rule.RuleListener {
+        return {
+            CallExpression(node: CallExpressionNode): void {
+                if (node.callee.name !== 'JsonProperty') return;
+                const arg = node.arguments[0];
+                if (!arg || arg.type !== 'ObjectExpression') return;
+                const objArg = arg as ObjectExpressionNode;
+                for (const prop of objArg.properties) {
+                    if (
+                        prop.key?.name === 'type' &&
+                        prop.value?.type === 'Identifier' &&
+                        BANNED_PRIMITIVES.includes(prop.value.name!)
+                    ) {
+                        context.report({
+                            // webpieces-disable no-any-unknown -- ESTree AST cast for ESLint report
+                            node: prop as unknown as Rule.Node,
+                            messageId: 'noPrimitiveType',
+                            data: { primitive: prop.value.name! },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+
+export = rule;