@webpieces/dev-config 0.0.0-dev

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

@@ -0,0 +1,304 @@
+/**
+ * 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';
+
+interface MethodLinesOptions {
+    max: number;
+}
+
+interface FunctionNode {
+    type:
+        | 'FunctionDeclaration'
+        | 'FunctionExpression'
+        | 'ArrowFunctionExpression'
+        | 'MethodDefinition';
+    body?: any;
+    loc?: {
+        start: { line: number };
+        end: { line: number };
+    };
+    key?: {
+        name?: string;
+    };
+    id?: {
+        name?: string;
+    };
+    [key: string]: any;
+}
+
+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> {
+  try {
+    return await executeRequest(req);
+  } catch (err: any) {
+    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);
+
+    // 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: any) {
+                //const error = toError(err);
+                // Continue searching if JSON parse fails
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return process.cwd(); // Fallback
+}
+
+function ensureDocFile(docPath: string, content: string): boolean {
+    try {
+        fs.mkdirSync(path.dirname(docPath), { recursive: true });
+        fs.writeFileSync(docPath, content, 'utf-8');
+        return true;
+    } catch (err: any) {
+        //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 ensureMethodDoc(context: Rule.RuleContext): void {
+    if (methodDocCreated) return; // Performance: only create once per lint run
+
+    const workspaceRoot = getWorkspaceRoot(context);
+    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.methods.md');
+
+    if (ensureDocFile(docPath, METHOD_DOC_CONTENT)) {
+        methodDocCreated = true;
+    }
+}
+
+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 tmp/webpieces/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 maxLines = options?.max ?? 70;
+
+        function checkFunction(node: any): void {
+            ensureMethodDoc(context);
+
+            const funcNode = node as FunctionNode;
+
+            // Skip if this is a function expression that's part of a method definition
+            // (method definitions will be handled by checkMethod)
+            if (
+                funcNode.type === 'FunctionExpression' &&
+                funcNode['parent']?.type === 'MethodDefinition'
+            ) {
+                return;
+            }
+
+            // Skip if no location info or no body
+            if (!funcNode.loc || !funcNode.body) {
+                return;
+            }
+
+            // Get function name
+            let name = 'anonymous';
+            if (funcNode.type === 'FunctionDeclaration' && funcNode.id?.name) {
+                name = funcNode.id.name;
+            } else if (funcNode.type === 'FunctionExpression' && funcNode.id?.name) {
+                name = funcNode.id.name;
+            }
+
+            // Calculate line count
+            const startLine = funcNode.loc.start.line;
+            const endLine = funcNode.loc.end.line;
+            const lineCount = endLine - startLine + 1;
+
+            if (lineCount > maxLines) {
+                context.report({
+                    node: funcNode as any,
+                    messageId: 'tooLong',
+                    data: {
+                        name,
+                        actual: String(lineCount),
+                        max: String(maxLines),
+                    },
+                });
+            }
+        }
+
+        function checkMethod(node: any): void {
+            ensureMethodDoc(context);
+
+            const methodNode = node;
+
+            // Skip if no location info
+            if (!methodNode.loc || !methodNode.value) {
+                return;
+            }
+
+            // Get method name from key
+            const name = methodNode.key?.name || 'anonymous';
+
+            // Calculate line count for the method (including the method definition)
+            const startLine = methodNode.loc.start.line;
+            const endLine = methodNode.loc.end.line;
+            const lineCount = endLine - startLine + 1;
+
+            if (lineCount > maxLines) {
+                context.report({
+                    node: methodNode as any,
+                    messageId: 'tooLong',
+                    data: {
+                        name,
+                        actual: String(lineCount),
+                        max: String(maxLines),
+                    },
+                });
+            }
+        }
+
+        return {
+            FunctionDeclaration: checkFunction,
+            FunctionExpression: checkFunction,
+            ArrowFunctionExpression: checkFunction,
+            MethodDefinition: checkMethod,
+        };
+    },
+};
+
+export = rule;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@webpieces/dev-config",
+  "version": "0.0.0-dev",
+  "description": "Development configuration, scripts, and patterns for WebPieces projects",
+  "type": "commonjs",
+  "bin": {
+    "wp-start": "./bin/start.sh",
+    "wp-stop": "./bin/stop.sh",
+    "wp-set-version": "./bin/set-version.sh",
+    "wp-use-local": "./bin/use-local-webpieces.sh",
+    "wp-use-published": "./bin/use-published-webpieces.sh",
+    "wp-setup-patterns": "./bin/setup-claude-patterns.sh"
+  },
+  "exports": {
+    "./eslint": "./config/eslint/base.mjs",
+    "./eslint-plugin": "./eslint-plugin/index.js",
+    "./jest": "./config/jest/preset.js",
+    "./tsconfig": "./config/typescript/tsconfig.base.json"
+  },
+  "files": [
+    "bin/**/*",
+    "config/**/*",
+    "eslint-plugin/**/*",
+    "patterns/**/*",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "eslint": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@types/eslint": "^9.6.1",
+    "eslint": "^9.39.1"
+  },
+  "keywords": [
+    "webpieces",
+    "config",
+    "eslint",
+    "scripts",
+    "typescript",
+    "jest"
+  ],
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/tooling/dev-config"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./src/index.d.ts",
+  "main": "./src/index.js"
+}

package/patterns/CLAUDE.md

@@ -0,0 +1,293 @@
+# Claude Code Guidelines for webpieces-ts
+
+This document contains guidelines and patterns for Claude Code when working on the webpieces-ts codebase.
+
+## Core Principles
+
+### 1. Classes Over Interfaces for Data Structures
+
+**RULE: All data-only structures MUST be classes, not interfaces.**
+
+**What is a data-only structure?**
+- Contains only fields/properties
+- No methods with business logic
+- Used purely for data transfer or configuration
+
+**Examples of DATA ONLY (use classes):**
+- `ClientConfig` - Configuration data
+- `FilterDefinition` - Filter metadata
+- `RouteDefinition` - Route metadata
+- `RouteRequest` - Request data
+- `RouteContext` - Context data
+- `MethodMeta` - Method metadata
+- `Action` - Response data
+- `RouteMetadata` - Route decorator metadata
+- `JsonFilterConfig` - Configuration data
+- `RegisteredRoute` - Extended route data
+
+**Examples of BUSINESS LOGIC (use interfaces):**
+- `Filter` - Has `filter(meta, next)` method with logic
+- `Routes` - Has `configure(routeBuilder)` method with logic
+- `RouteBuilder` - Has `addRoute()`, `addFilter()` methods
+- `WebAppMeta` - Has `getDIModules()`, `getRoutes()` methods
+- `SaveApi` - Has `save(request)` method with logic
+- `RemoteApi` - Has `fetchValue(request)` method with logic
+- `Counter` - Has `inc()`, `get()` methods with logic
+
+**Why classes for data?**
+1. No anonymous object literals - explicit construction
+2. Better type safety
+3. Clear instantiation points
+4. Easier to trace in debugger
+5. Can add validation/defaults in constructor
+
+**Pattern:**
+```typescript
+// BAD - Interface for data
+export interface UserData {
+  name: string;
+  age: number;
+}
+
+const user = { name: 'John', age: 30 }; // Anonymous object literal
+
+// GOOD - Class for data
+export class UserData {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+
+const user = new UserData('John', 30); // Explicit construction
+```
+
+### 2. Filter Chain Architecture
+
+**Pattern inspired by Java webpieces:**
+
+The filter system uses filepath-based matching:
+- Filters are registered with glob patterns (e.g., `'src/controllers/admin/**/*.ts'`)
+- `FilterMatcher` matches filters to routes based on controller filepath
+- Filters without a pattern (or pattern `'*'`) apply globally
+- Filter matching happens at startup (no runtime overhead)
+
+**Key classes:**
+- `FilterDefinition(priority, filterClass, filepathPattern)` - Filter registration
+- `FilterMatcher.findMatchingFilters()` - Pattern matching logic
+- `FilterChain` - Executes filters in priority order
+
+**Example:**
+```typescript
+export class FilterRoutes implements Routes {
+  configure(routeBuilder: RouteBuilder): void {
+    // Global filter (pattern '*' matches all)
+    routeBuilder.addFilter(
+      new FilterDefinition(140, ContextFilter, '*')
+    );
+
+    // Admin-only filter
+    routeBuilder.addFilter(
+      new FilterDefinition(100, AdminAuthFilter, 'src/controllers/admin/**/*.ts')
+    );
+  }
+}
+```
+
+### 3. No Anonymous Object Literals
+
+**RULE: Avoid anonymous object structures - use explicit class constructors.**
+
+**BAD:**
+```typescript
+routeBuilder.addRoute({
+  method: 'POST',
+  path: '/api/save',
+  handler: myHandler,
+});
+```
+
+**GOOD:**
+```typescript
+routeBuilder.addRoute(
+  new RouteDefinition('POST', '/api/save', myHandler)
+);
+```
+
+### 4. Type Safety
+
+- Use `unknown` instead of `any` for better type safety
+- Use generics for type-safe route handlers: `RouteHandler<TResult>`
+- Prefer explicit types over inference when defining public APIs
+
+### 5. Dependency Injection
+
+**Use Inversify for DI:**
+- `@injectable()` - Mark classes as injectable
+- `@inject(TYPES.Something)` - Inject dependencies
+- `@provideSingleton()` - Register singleton in container
+- `@unmanaged()` - Mark constructor params that aren't injected
+
+**Pattern:**
+```typescript
+@provideSingleton()
+@Controller()
+export class SaveController {
+  constructor(
+    @inject(TYPES.Counter) private counter: Counter,
+    @inject(TYPES.RemoteApi) private remoteService: RemoteApi
+  ) {}
+}
+```
+
+### 6. Decorators
+
+**API Decorators (shared between client and server):**
+- `@ApiInterface()` - Mark API prototype class
+- `@Post()`, `@Get()`, `@Put()`, `@Delete()`, `@Patch()` - HTTP methods
+- `@Path('/path')` - Route path
+
+**Server-only Decorators:**
+- `@Controller()` - Mark controller class
+- `@SourceFile('path/to/controller.ts')` - Explicit filepath for filter matching
+- `@provideSingleton()` - Register as singleton
+
+### 7. Testing
+
+**Unit tests:**
+- Test filter matching logic in isolation
+- Mock dependencies using classes
+- Verify priority ordering
+
+**Integration tests:**
+- Use `WebpiecesServer.createApiClient()` for testing without HTTP
+- Test full filter chain execution
+- Verify end-to-end behavior
+
+### 8. Documentation
+
+- Use JSDoc for all public APIs
+- Explain WHY, not just WHAT
+- Include usage examples
+- Document differences from Java version when applicable
+
+## Common Patterns
+
+### Creating a New Filter
+
+```typescript
+import { injectable } from 'inversify';
+import { Filter, MethodMeta, Action, NextFilter } from '@webpieces/http-filters';
+
+@injectable()
+export class MyFilter implements Filter {
+  priority = 100;
+
+  async filter(meta: MethodMeta, next: NextFilter): Promise<Action> {
+    // Before logic
+    console.log(`Request: ${meta.httpMethod} ${meta.path}`);
+
+    // Execute next filter/controller
+    const action = await next.execute();
+
+    // After logic
+    console.log(`Response: ${action.statusCode}`);
+
+    return action;
+  }
+}
+```
+
+### Creating a New Controller
+
+```typescript
+import { provideSingleton, Controller } from '@webpieces/http-routing';
+
+@provideSingleton()
+@Controller()
+export class MyController extends MyApiPrototype implements MyApi {
+  private readonly __validator!: ValidateImplementation<MyController, MyApi>;
+
+  async myMethod(request: MyRequest): Promise<MyResponse> {
+    // Implementation
+  }
+}
+```
+
+### Registering Routes and Filters
+
+```typescript
+export class MyRoutes implements Routes {
+  configure(routeBuilder: RouteBuilder): void {
+    // Register filters
+    routeBuilder.addFilter(
+      new FilterDefinition(140, ContextFilter, '*')
+    );
+
+    // Register API routes
+    // (handled automatically by RESTApiRoutes)
+  }
+}
+```
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────┐
+│                 WebAppMeta                      │
+│  - getDIModules() - Returns DI modules         │
+│  - getRoutes() - Returns route configurations  │
+└─────────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────┐
+│              WebpiecesServer                    │
+│  - Initializes DI containers                   │
+│  - Registers routes using RouteBuilder         │
+│  - Matches filters to routes (FilterMatcher)   │
+│  - Creates filter chains per route             │
+└─────────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────┐
+│               FilterChain                       │
+│  - Executes filters in priority order          │
+│  - Wraps controller invocation                 │
+└─────────────────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────┐
+│              Controller                         │
+│  - Implements API interface                    │
+│  - Business logic                              │
+│  - Returns response                            │
+└─────────────────────────────────────────────────┘
+```
+
+## Key Differences from Java Version
+
+1. **Glob patterns instead of Regex**: TypeScript uses glob patterns for filepath matching
+2. **Class-based data structures**: All data structures are classes, not interfaces
+3. **Decorator-based metadata**: Uses TypeScript decorators instead of annotations
+4. **Inversify instead of Guice**: Different DI framework but similar patterns
+5. **Class name fallback**: Since TypeScript doesn't provide source paths at runtime, we use class name patterns like `**/SaveController.ts`
+
+## When Adding New Features
+
+1. **Check for data-only structures** - If it's just data, use a class
+2. **Add filter matching support** - Consider if filters need to scope to it
+3. **Write tests first** - Unit tests for logic, integration tests for behavior
+4. **Update documentation** - Keep this file and claude.patterns.md up to date
+5. **Follow existing patterns** - Look at similar features for consistency
+
+## Common Mistakes to Avoid
+
+1. ❌ Using interfaces for data structures
+2. ❌ Creating anonymous object literals for configs/definitions
+3. ❌ Forgetting to export classes from index.ts
+4. ❌ Using `any` instead of `unknown` for generic types
+5. ❌ Skipping tests for new features
+6. ❌ Not documenting differences from Java version