@webpieces/dev-config 0.0.0-dev → 0.2.21

package/eslint-plugin/rules/enforce-architecture.ts

@@ -0,0 +1,469 @@
+/**
+ * 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';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const DEPENDENCIES_DOC_CONTENT = `# AI Agent Instructions: Architecture Dependency Violation
+
+**READ THIS FILE FIRST before making any changes!**
+
+## ⚠️ CRITICAL WARNING ⚠️
+
+**This is a VERY IMPORTANT change that has LARGE REPERCUSSIONS later!**
+
+Adding new dependencies creates technical debt that compounds over time:
+- Creates coupling between packages that may be hard to undo
+- Can create circular dependency tangles
+- Makes packages harder to test in isolation
+- Increases build times and bundle sizes
+- May force unnecessary upgrades across the codebase
+
+**DO NOT add dependencies without senior developer approval!**
+
+## Understanding the Error
+
+You've attempted to import from a package that is not in your project's allowed dependencies.
+The architecture enforces a layered dependency structure where:
+- Level 0 packages are foundation packages with NO dependencies on other @webpieces packages
+- Higher level packages can only depend on lower level packages
+- All dependencies must be explicitly declared
+
+## Steps to Resolve
+
+### Step 1: Generate Current Dependency Graph
+Run this command to see the current architecture:
+\`\`\`bash
+npx nx run architecture:generate
+\`\`\`
+This creates/updates \`architecture/dependencies.json\` showing all packages and their levels.
+
+### Step 2: Analyze the Proposed Change
+Ask yourself:
+1. **Is this import truly necessary?** Can you refactor to avoid it?
+2. **Should the code move instead?** Maybe the code belongs in a different package.
+3. **Will this create a cycle?** Use \`npx nx graph\` to visualize dependencies.
+4. **Can you use an interface/abstraction?** Define interface in lower-level package, implement in higher-level.
+
+### Step 3: Get Senior Developer Approval
+
+## 🛑 AI AGENTS: STOP HERE AND ASK FOR HUMAN APPROVAL! 🛑
+
+**YOU MUST NOT PROCEED TO STEP 4 WITHOUT EXPLICIT HUMAN APPROVAL!**
+
+**REQUIRED**: Discuss this architectural change with a senior developer before proceeding.
+- Explain why the dependency is needed
+- Show you've considered alternatives (Step 2)
+- **WAIT for explicit approval before making ANY changes to project.json or package.json**
+
+**AI Agent Instructions:**
+1. Present your analysis from Step 2 to the human
+2. Explain which package needs which dependency and why
+3. ASK: "Do you approve adding this dependency?"
+4. **DO NOT modify project.json or package.json until you receive explicit "yes" or approval**
+
+### Step 4: If Approved, Add the Dependency
+
+## ⛔ NEVER MODIFY THESE FILES WITHOUT HUMAN APPROVAL FROM STEP 3! ⛔
+
+Only after receiving explicit human approval in Step 3, make these changes:
+
+1. **Update project.json** - Add to \`build.dependsOn\`:
+   \`\`\`json
+   {
+     "targets": {
+       "build": {
+         "dependsOn": ["^build", "dep1:build", "NEW_PACKAGE:build"]
+       }
+     }
+   }
+   \`\`\`
+
+2. **Update package.json** - Add to \`dependencies\`:
+   \`\`\`json
+   {
+     "dependencies": {
+       "@webpieces/NEW_PACKAGE": "*"
+     }
+   }
+   \`\`\`
+
+### Step 5: Update Architecture Definition
+Run this command to validate and update the architecture:
+\`\`\`bash
+npx nx run architecture:validate --mode=update
+\`\`\`
+
+This will:
+- Detect any cycles (which MUST be fixed before proceeding)
+- Update \`architecture/dependencies.json\` with the new dependency
+- Recalculate package levels
+
+### Step 6: Verify No Cycles
+\`\`\`bash
+npx nx run architecture:validate
+\`\`\`
+
+If cycles are detected, you MUST refactor to break the cycle. Common strategies:
+- Move shared code to a lower-level package
+- Use dependency inversion (interfaces in low-level, implementations in high-level)
+- Restructure package boundaries
+
+## Alternative Solutions (Preferred over adding dependencies)
+
+### Option A: Move the Code
+If you need functionality from another package, consider moving that code to a shared lower-level package.
+
+### Option B: Dependency Inversion
+Define an interface in the lower-level package, implement it in the higher-level package:
+\`\`\`typescript
+// In foundation package (level 0)
+export interface Logger { log(msg: string): void; }
+
+// In higher-level package
+export class ConsoleLogger implements Logger { ... }
+\`\`\`
+
+### Option C: Pass Dependencies as Parameters
+Instead of importing, receive the dependency as a constructor or method parameter.
+
+## Remember
+- Every dependency you add today is technical debt for tomorrow
+- The best dependency is the one you don't need
+- When in doubt, refactor rather than add dependencies
+`;
+
+// Module-level flag to prevent redundant file creation
+let dependenciesDocCreated = false;
+
+/**
+ * Ensure a documentation file exists at the given path.
+ */
+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) {
+        void err;
+        console.warn(`[webpieces] Could not create doc file: ${docPath}`);
+        return false;
+    }
+}
+
+/**
+ * Ensure the dependencies documentation file exists.
+ * Called when an architecture violation is detected.
+ */
+function ensureDependenciesDoc(workspaceRoot: string): void {
+    if (dependenciesDocCreated) return;
+    const docPath = path.join(workspaceRoot, 'tmp', 'webpieces', 'webpieces.dependencies.md');
+    if (ensureDocFile(docPath, DEPENDENCIES_DOC_CONTENT)) {
+        dependenciesDocCreated = true;
+    }
+}
+
+/**
+ * Graph entry format from .graphs/dependencies.json
+ */
+interface GraphEntry {
+    level: number;
+    dependsOn: string[];
+}
+
+type EnhancedGraph = Record<string, GraphEntry>;
+
+/**
+ * Project mapping entry
+ */
+interface ProjectMapping {
+    root: string;
+    name: string;
+}
+
+// Cache for blessed graph (loaded once per lint run)
+let cachedGraph: EnhancedGraph | null = null;
+let cachedGraphPath: string | null = null;
+
+// Cache for project mappings
+let cachedProjectMappings: ProjectMapping[] | null = null;
+
+/**
+ * Find workspace root by walking up from file location
+ */
+function findWorkspaceRoot(startPath: string): string {
+    let currentDir = path.dirname(startPath);
+
+    for (let i = 0; i < 20; i++) {
+        const packagePath = path.join(currentDir, 'package.json');
+        if (fs.existsSync(packagePath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
+                if (pkg.workspaces || pkg.name === 'webpieces-ts') {
+                    return currentDir;
+                }
+            } catch (err: any) {
+                //const error = toError(err);
+                void err;
+            }
+        }
+
+        const parent = path.dirname(currentDir);
+        if (parent === currentDir) break;
+        currentDir = parent;
+    }
+
+    return process.cwd();
+}
+
+/**
+ * Load blessed graph from architecture/dependencies.json
+ */
+function loadBlessedGraph(workspaceRoot: string): EnhancedGraph | null {
+    const graphPath = path.join(workspaceRoot, 'architecture', 'dependencies.json');
+
+    // Return cached if same path
+    if (cachedGraphPath === graphPath && cachedGraph !== null) {
+        return cachedGraph;
+    }
+
+    if (!fs.existsSync(graphPath)) {
+        return null;
+    }
+
+    try {
+        const content = fs.readFileSync(graphPath, 'utf-8');
+        cachedGraph = JSON.parse(content) as EnhancedGraph;
+        cachedGraphPath = graphPath;
+        return cachedGraph;
+    } catch (err: any) {
+        //const error = toError(err);
+        // err is used below
+        console.error(`[ESLint @webpieces/enforce-architecture] Could not load graph: ${err}`);
+        return null;
+    }
+}
+
+/**
+ * Build project mappings from project.json files in workspace
+ */
+function buildProjectMappings(workspaceRoot: string): ProjectMapping[] {
+    if (cachedProjectMappings !== null) {
+        return cachedProjectMappings;
+    }
+
+    const mappings: ProjectMapping[] = [];
+
+    // Scan common locations for project.json files
+    const searchDirs = ['packages', 'apps', 'libs', 'libraries', 'services'];
+
+    for (const searchDir of searchDirs) {
+        const searchPath = path.join(workspaceRoot, searchDir);
+        if (!fs.existsSync(searchPath)) continue;
+
+        scanForProjects(searchPath, workspaceRoot, mappings);
+    }
+
+    // Sort by path length (longest first) for more specific matching
+    mappings.sort((a, b) => b.root.length - a.root.length);
+
+    cachedProjectMappings = mappings;
+    return mappings;
+}
+
+/**
+ * Recursively scan for project.json files
+ */
+function scanForProjects(
+    dir: string,
+    workspaceRoot: string,
+    mappings: ProjectMapping[]
+): void {
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+
+            if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                // Check for project.json in this directory
+                const projectJsonPath = path.join(fullPath, 'project.json');
+                if (fs.existsSync(projectJsonPath)) {
+                    try {
+                        const projectJson = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'));
+                        const projectRoot = path.relative(workspaceRoot, fullPath);
+
+                        // Determine project name
+                        let projectName = projectJson.name || entry.name;
+
+                        // Add @webpieces/ prefix if not present
+                        if (!projectName.startsWith('@webpieces/')) {
+                            projectName = `@webpieces/${projectName}`;
+                        }
+
+                        mappings.push({
+                            root: projectRoot,
+                            name: projectName,
+                        });
+                    } catch (err: any) {
+                        //const error = toError(err);
+                        void err;
+                    }
+                }
+
+                // Continue scanning subdirectories
+                scanForProjects(fullPath, workspaceRoot, mappings);
+            }
+        }
+    } catch (err: any) {
+        //const error = toError(err);
+        void err;
+    }
+}
+
+/**
+ * Get project name from file path
+ */
+function getProjectFromFile(filePath: string, workspaceRoot: string): string | null {
+    const relativePath = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
+    const mappings = buildProjectMappings(workspaceRoot);
+
+    for (const mapping of mappings) {
+        if (relativePath.startsWith(mapping.root + '/') || relativePath.startsWith(mapping.root)) {
+            return mapping.name;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Compute all transitive dependencies for a project
+ */
+function computeTransitiveDependencies(project: string, graph: EnhancedGraph): Set<string> {
+    const result = new Set<string>();
+    const visited = new Set<string>();
+
+    function visit(currentProject: string): void {
+        if (visited.has(currentProject)) return;
+        visited.add(currentProject);
+
+        const entry = graph[currentProject];
+        if (!entry || !entry.dependsOn) return;
+
+        for (const dep of entry.dependsOn) {
+            result.add(dep);
+            visit(dep);
+        }
+    }
+
+    visit(project);
+    return result;
+}
+
+const rule: Rule.RuleModule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Enforce blessed architecture dependencies',
+            category: 'Best Practices',
+            recommended: true,
+            url: 'https://github.com/deanhiller/webpieces-ts',
+        },
+        messages: {
+            illegalImport:
+                "⚠️ AI Agent: READ tmp/webpieces/webpieces.dependencies.md for resolution steps!\n\n" +
+                "Import '{{imported}}' violates architecture boundaries.\n\n" +
+                "Project '{{project}}' (level {{level}}) can only import from:\n" +
+                '{{allowedList}}',
+            noGraph:
+                'No architecture graph found at architecture/dependencies.json\n' +
+                'Run: nx run architecture:validate --mode=update',
+        },
+        schema: [],
+    },
+
+    create(context: Rule.RuleContext): Rule.RuleListener {
+        const filename = context.filename || context.getFilename();
+        const workspaceRoot = findWorkspaceRoot(filename);
+
+        return {
+            ImportDeclaration(node: any): void {
+                const importPath = node.source.value as string;
+
+                // Only check @webpieces/* imports
+                if (!importPath.startsWith('@webpieces/')) {
+                    return;
+                }
+
+                // Determine which project this file belongs to
+                const project = getProjectFromFile(filename, workspaceRoot);
+                if (!project) {
+                    // File not in any known project (e.g., tools/, scripts/)
+                    return;
+                }
+
+                // Self-import is always allowed
+                if (importPath === project) {
+                    return;
+                }
+
+                // Load blessed graph
+                const graph = loadBlessedGraph(workspaceRoot);
+                if (!graph) {
+                    // No graph file - warn but don't fail (allows gradual adoption)
+                    // Uncomment below to enforce graph existence:
+                    // context.report({ node: node.source, messageId: 'noGraph' });
+                    return;
+                }
+
+                // Get project entry
+                const projectEntry = graph[project];
+                if (!projectEntry) {
+                    // Project not in graph (new project?) - allow
+                    return;
+                }
+
+                // Compute allowed dependencies (direct + transitive)
+                const allowedDeps = computeTransitiveDependencies(project, graph);
+
+                // Check if import is allowed
+                if (!allowedDeps.has(importPath)) {
+                    // Write documentation file for AI/developer to read
+                    ensureDependenciesDoc(workspaceRoot);
+
+                    const directDeps = projectEntry.dependsOn || [];
+                    const allowedList =
+                        directDeps.length > 0
+                            ? directDeps.map((dep) => `  - ${dep}`).join('\n') +
+                              '\n  (and their transitive dependencies)'
+                            : '  (none - this is a foundation project)';
+
+                    context.report({
+                        node: node.source,
+                        messageId: 'illegalImport',
+                        data: {
+                            imported: importPath,
+                            project: project,
+                            level: String(projectEntry.level),
+                            allowedList: allowedList,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};
+
+export = rule;

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

@@ -27,12 +27,12 @@ Files should contain a SINGLE COHESIVE UNIT.
 If the file contains multiple classes, **SEPARATE each class into its own file**.
 
 \`\`\`typescript
-// ❌ BAD: UserController.ts (multiple classes)
+// BAD: UserController.ts (multiple classes)
 export class UserController { /* ... */ }
 export class UserValidator { /* ... */ }
 export class UserNotifier { /* ... */ }
 
-// ✅ GOOD: Three separate files
+// GOOD: Three separate files
 // UserController.ts
 export class UserController { /* ... */ }
 
@@ -48,7 +48,7 @@ export class UserNotifier { /* ... */ }
 #### Pattern: Create New Service Class with Dependency Injection
 
 \`\`\`typescript
-// ❌ BAD: UserController.ts (800 lines, single class)
+// BAD: UserController.ts (800 lines, single class)
 @provideSingleton()
 @Controller()
 export class UserController {
@@ -58,7 +58,7 @@ export class UserController {
   // 100 lines: analytics logic
 }
 
-// ✅ GOOD: Extract validation service
+// GOOD: Extract validation service
 // 1. Create UserValidationService.ts
 @provideSingleton()
 export class UserValidationService {
@@ -96,11 +96,11 @@ export class UserController {
    - 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
+   - 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\`
@@ -175,7 +175,7 @@ function getWorkspaceRoot(context) {
             }
             catch (err) {
                 //const error = toError(err);
-                // Continue searching if JSON parse fails
+                void err; // Continue searching if JSON parse fails
             }
         }
         dir = path.dirname(dir);
@@ -190,7 +190,7 @@ function ensureDocFile(docPath, content) {
     }
     catch (err) {
         //const error = toError(err);
-        // Graceful degradation: log warning but don't break lint
+        // err is used in console.warn below
         console.warn(`[webpieces] Could not create doc file: ${docPath}`, err);
         return false;
     }

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

@@ -1 +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"]}
+{"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                void err; // 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        // err is used in console.warn below\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"]}

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

@@ -32,12 +32,12 @@ Files should contain a SINGLE COHESIVE UNIT.
 If the file contains multiple classes, **SEPARATE each class into its own file**.
 
 \`\`\`typescript
-// ❌ BAD: UserController.ts (multiple classes)
+// BAD: UserController.ts (multiple classes)
 export class UserController { /* ... */ }
 export class UserValidator { /* ... */ }
 export class UserNotifier { /* ... */ }
 
-// ✅ GOOD: Three separate files
+// GOOD: Three separate files
 // UserController.ts
 export class UserController { /* ... */ }
 
@@ -53,7 +53,7 @@ export class UserNotifier { /* ... */ }
 #### Pattern: Create New Service Class with Dependency Injection
 
 \`\`\`typescript
-// ❌ BAD: UserController.ts (800 lines, single class)
+// BAD: UserController.ts (800 lines, single class)
 @provideSingleton()
 @Controller()
 export class UserController {
@@ -63,7 +63,7 @@ export class UserController {
   // 100 lines: analytics logic
 }
 
-// ✅ GOOD: Extract validation service
+// GOOD: Extract validation service
 // 1. Create UserValidationService.ts
 @provideSingleton()
 export class UserValidationService {
@@ -101,11 +101,11 @@ export class UserController {
    - 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
+   - 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\`
@@ -182,7 +182,7 @@ function getWorkspaceRoot(context: Rule.RuleContext): string {
                 }
             } catch (err: any) {
                 //const error = toError(err);
-                // Continue searching if JSON parse fails
+                void err; // Continue searching if JSON parse fails
             }
         }
         dir = path.dirname(dir);
@@ -197,7 +197,7 @@ function ensureDocFile(docPath: string, content: string): boolean {
         return true;
     } catch (err: any) {
         //const error = toError(err);
-        // Graceful degradation: log warning but don't break lint
+        // err is used in console.warn below
         console.warn(`[webpieces] Could not create doc file: ${docPath}`, err);
         return false;
     }