@webpieces/dev-config 0.2.95 → 0.2.97

package/architecture/executors/validate-modified-files/executor.ts

@@ -1,571 +0,0 @@
-/**
- * Validate Modified Files Executor
- *
- * Validates that modified files don't exceed a maximum line count (default 900).
- * This encourages keeping files small and focused - when you touch a file,
- * you must bring it under the limit.
- *
- * Usage:
- * nx affected --target=validate-modified-files --base=origin/main
- *
- * Escape hatch: Add webpieces-disable max-lines-modified-files comment with date and justification
- * Format: // webpieces-disable max-lines-modified-files 2025/01/15 -- [reason]
- * The disable expires after 1 month from the date specified.
- */
-
-import type { ExecutorContext } from '@nx/devkit';
-import { execSync } from 'child_process';
-import * as fs from 'fs';
-import * as path from 'path';
-
-export type FileMaxLimitMode = 'OFF' | 'MODIFIED_FILES';
-
-export interface ValidateModifiedFilesOptions {
-    limit?: number;
-    mode?: FileMaxLimitMode;
-    disableAllowed?: boolean;
-}
-
-export interface ExecutorResult {
-    success: boolean;
-}
-
-interface FileViolation {
-    file: string;
-    lines: number;
-    expiredDisable?: boolean;
-    expiredDate?: string;
-}
-
-const TMP_DIR = 'tmp/webpieces';
-const TMP_MD_FILE = 'webpieces.filesize.md';
-
-const FILESIZE_DOC_CONTENT = `# AI Agent Instructions: File Too Long
-
-**READ THIS FILE to fix files that are too long**
-
-## Core Principle
-
-With **stateless systems + dependency injection, refactor is trivial**.
-Pick a method or a few and move to new class XXXXX, then inject XXXXX
-into all users of those methods via the constructor.
-Delete those methods from original class.
-
-**99% of files can be less than the configured max lines of code.**
-
-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 under the limit
-   - Each extracted file should be under the limit
-   - 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
-  ) {}
-}
-\`\`\`
-
-## Escape Hatch
-
-If refactoring is genuinely not feasible (generated files, complex algorithms, etc.),
-add a disable comment at the TOP of the file (within first 5 lines) with a DATE:
-
-\`\`\`typescript
-// webpieces-disable max-lines-modified-files 2025/01/15 -- Complex generated file, refactoring would break generation
-\`\`\`
-
-**IMPORTANT**: The date format is yyyy/mm/dd. The disable will EXPIRE after 1 month from this date.
-After expiration, you must either fix the file or update the date to get another month.
-This ensures that disable comments are reviewed periodically.
-
-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.
-`;
-
-/**
- * Write the instructions documentation to tmp directory
- */
-function writeTmpInstructions(workspaceRoot: string): string {
-    const tmpDir = path.join(workspaceRoot, TMP_DIR);
-    const mdPath = path.join(tmpDir, TMP_MD_FILE);
-
-    fs.mkdirSync(tmpDir, { recursive: true });
-    fs.writeFileSync(mdPath, FILESIZE_DOC_CONTENT);
-
-    return mdPath;
-}
-
-/**
- * Get changed TypeScript files between base and head (or working tree if head not specified).
- * Uses `git diff base [head]` to match what `nx affected` does.
- * When head is NOT specified, also includes untracked files (matching nx affected behavior).
- */
-function getChangedTypeScriptFiles(workspaceRoot: string, base: string, head?: string): string[] {
-    try {
-        // If head is specified, diff base to head; otherwise diff base to working tree
-        const diffTarget = head ? `${base} ${head}` : base;
-        const output = execSync(`git diff --name-only ${diffTarget} -- '*.ts' '*.tsx'`, {
-            cwd: workspaceRoot,
-            encoding: 'utf-8',
-        });
-        const changedFiles = output
-            .trim()
-            .split('\n')
-            .filter((f) => f && !f.includes('.spec.ts') && !f.includes('.test.ts'));
-
-        // When comparing to working tree (no head specified), also include untracked files
-        // This matches what nx affected does: "All modified files not yet committed or tracked will also be added"
-        if (!head) {
-            try {
-                const untrackedOutput = execSync(`git ls-files --others --exclude-standard '*.ts' '*.tsx'`, {
-                    cwd: workspaceRoot,
-                    encoding: 'utf-8',
-                });
-                const untrackedFiles = untrackedOutput
-                    .trim()
-                    .split('\n')
-                    .filter((f) => f && !f.includes('.spec.ts') && !f.includes('.test.ts'));
-                // Merge and dedupe
-                const allFiles = new Set([...changedFiles, ...untrackedFiles]);
-                return Array.from(allFiles);
-            } catch {
-                // If ls-files fails, just return the changed files
-                return changedFiles;
-            }
-        }
-
-        return changedFiles;
-    } catch {
-        return [];
-    }
-}
-
-/**
- * Parse a date string in yyyy/mm/dd format and return a Date object.
- * Returns null if the format is invalid.
- */
-function parseDisableDate(dateStr: string): Date | null {
-    // Match yyyy/mm/dd format
-    const match = dateStr.match(/^(\d{4})\/(\d{2})\/(\d{2})$/);
-    if (!match) return null;
-
-    const year = parseInt(match[1], 10);
-    const month = parseInt(match[2], 10) - 1; // JS months are 0-indexed
-    const day = parseInt(match[3], 10);
-
-    const date = new Date(year, month, day);
-
-    // Validate the date is valid (e.g., not Feb 30)
-    if (date.getFullYear() !== year || date.getMonth() !== month || date.getDate() !== day) {
-        return null;
-    }
-
-    return date;
-}
-
-/**
- * Check if a date is within the last month (not expired).
- */
-function isDateWithinMonth(date: Date): boolean {
-    const now = new Date();
-    const oneMonthAgo = new Date(now.getFullYear(), now.getMonth() - 1, now.getDate());
-    return date >= oneMonthAgo;
-}
-
-interface DisableStatus {
-    hasDisable: boolean;
-    isValid: boolean;
-    isExpired: boolean;
-    date?: string;
-}
-
-/**
- * Check if a file has a valid, non-expired disable comment at the top (within first 5 lines).
- * Returns status object with details about the disable comment.
- */
-// webpieces-disable max-lines-new-methods -- Date validation logic requires checking multiple conditions
-function checkDisableComment(content: string): DisableStatus {
-    const lines = content.split('\n').slice(0, 5);
-
-    for (const line of lines) {
-        if (line.includes('webpieces-disable') && line.includes('max-lines-modified-files')) {
-            // Found disable comment, now check for date
-            // Format: // webpieces-disable max-lines-modified-files yyyy/mm/dd -- reason
-            const dateMatch = line.match(/max-lines-modified-files\s+(\d{4}\/\d{2}\/\d{2}|XXXX\/XX\/XX)/);
-
-            if (!dateMatch) {
-                // No date found - invalid disable comment
-                return { hasDisable: true, isValid: false, isExpired: false };
-            }
-
-            const dateStr = dateMatch[1];
-
-            // Secret permanent disable
-            if (dateStr === 'XXXX/XX/XX') {
-                return { hasDisable: true, isValid: true, isExpired: false, date: dateStr };
-            }
-
-            const date = parseDisableDate(dateStr);
-            if (!date) {
-                // Invalid date format
-                return { hasDisable: true, isValid: false, isExpired: false, date: dateStr };
-            }
-
-            if (!isDateWithinMonth(date)) {
-                // Date is expired (older than 1 month)
-                return { hasDisable: true, isValid: true, isExpired: true, date: dateStr };
-            }
-
-            // Valid and not expired
-            return { hasDisable: true, isValid: true, isExpired: false, date: dateStr };
-        }
-    }
-
-    return { hasDisable: false, isValid: false, isExpired: false };
-}
-
-/**
- * Count lines in a file and check for violations
- */
-// webpieces-disable max-lines-new-methods -- File iteration with disable checking logic
-function findViolations(workspaceRoot: string, changedFiles: string[], limit: number, disableAllowed: boolean): FileViolation[] {
-    const violations: FileViolation[] = [];
-
-    for (const file of changedFiles) {
-        const fullPath = path.join(workspaceRoot, file);
-
-        if (!fs.existsSync(fullPath)) continue;
-
-        const content = fs.readFileSync(fullPath, 'utf-8');
-        const lineCount = content.split('\n').length;
-
-        // Skip files under the limit
-        if (lineCount <= limit) continue;
-
-        // When disableAllowed is false, ignore all disable comments
-        if (!disableAllowed) {
-            violations.push({ file, lines: lineCount });
-            continue;
-        }
-
-        // Check for disable comment
-        const disableStatus = checkDisableComment(content);
-
-        if (disableStatus.hasDisable) {
-            if (disableStatus.isValid && !disableStatus.isExpired) {
-                // Valid, non-expired disable - skip this file
-                continue;
-            }
-
-            if (disableStatus.isExpired) {
-                // Expired disable - report as violation with expired info
-                violations.push({
-                    file,
-                    lines: lineCount,
-                    expiredDisable: true,
-                    expiredDate: disableStatus.date,
-                });
-                continue;
-            }
-
-            // Invalid disable (missing/bad date) - fall through to report as violation
-        }
-
-        violations.push({
-            file,
-            lines: lineCount,
-        });
-    }
-
-    return violations;
-}
-
-/**
- * Auto-detect the base branch by finding the merge-base with origin/main.
- */
-function detectBase(workspaceRoot: string): string | null {
-    try {
-        const mergeBase = execSync('git merge-base HEAD origin/main', {
-            cwd: workspaceRoot,
-            encoding: 'utf-8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-
-        if (mergeBase) {
-            return mergeBase;
-        }
-    } catch {
-        try {
-            const mergeBase = execSync('git merge-base HEAD main', {
-                cwd: workspaceRoot,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'pipe'],
-            }).trim();
-
-            if (mergeBase) {
-                return mergeBase;
-            }
-        } catch {
-            // Ignore
-        }
-    }
-    return null;
-}
-
-/**
- * Get today's date in yyyy/mm/dd format for error messages
- */
-function getTodayDateString(): string {
-    const now = new Date();
-    const year = now.getFullYear();
-    const month = String(now.getMonth() + 1).padStart(2, '0');
-    const day = String(now.getDate()).padStart(2, '0');
-    return `${year}/${month}/${day}`;
-}
-
-/**
- * Report violations to console
- */
-// webpieces-disable max-lines-new-methods -- Error output formatting with multiple message sections
-function reportViolations(violations: FileViolation[], limit: number, disableAllowed: boolean): void {
-    console.error('');
-    console.error('\u274c YOU MUST FIX THIS AND NOT be more than ' + limit + ' lines of code per file');
-    console.error('   as it slows down IDEs AND is VERY VERY EASY to refactor.');
-    console.error('');
-    console.error('\ud83d\udcda With stateless systems + dependency injection, refactor is trivial:');
-    console.error('   Pick a method or a few and move to new class XXXXX, then inject XXXXX');
-    console.error('   into all users of those methods via the constructor.');
-    console.error('   Delete those methods from original class.');
-    console.error('   99% of files can be less than ' + limit + ' lines of code.');
-    console.error('');
-    console.error('\u26a0\ufe0f  *** READ tmp/webpieces/webpieces.filesize.md for detailed guidance on how to fix this easily *** \u26a0\ufe0f');
-    console.error('');
-
-    for (const v of violations) {
-        if (v.expiredDisable) {
-            console.error(`  \u274c ${v.file} (${v.lines} lines, max: ${limit})`);
-            console.error(`     \u23f0 EXPIRED DISABLE: Your disable comment dated ${v.expiredDate} has expired (>1 month old).`);
-            console.error(`        You must either FIX the file or UPDATE the date to get another month.`);
-        } else {
-            console.error(`  \u274c ${v.file} (${v.lines} lines, max: ${limit})`);
-        }
-    }
-    console.error('');
-
-    // Only show escape hatch instructions when disableAllowed is true
-    if (disableAllowed) {
-        console.error('   You can disable this error, but you will be forced to fix again in 1 month');
-        console.error('   since 99% of files can be less than ' + limit + ' lines of code.');
-        console.error('');
-        console.error('   Use escape with DATE (expires in 1 month):');
-        console.error(`   // webpieces-disable max-lines-modified-files ${getTodayDateString()} -- [your reason]`);
-        console.error('');
-    } else {
-        console.error('   \u26a0\ufe0f  disableAllowed is false - disable comments are NOT allowed.');
-        console.error('   This rule must be met and cannot be disabled since nx.json disableAllowed is set to false.');
-        console.error('   You MUST refactor to reduce file size.');
-        console.error('');
-        console.error('   For a major refactor, a human can add "ignoreModifiedUntilEpoch" to nx.json validate-code options.');
-        console.error('   This is an expiry timestamp (epoch ms) for when we start forcing everyone to meet size rules again.');
-        console.error('   Sometimes for speed, we allow files to expand during a refactor and over time,');
-        console.error('   each PR reduces files as they get touched.');
-        console.error('   AI agents should NOT add ignoreModifiedUntilEpoch - ask a human to do it.');
-        console.error('');
-    }
-}
-
-export default async function runExecutor(
-    options: ValidateModifiedFilesOptions,
-    context: ExecutorContext
-): Promise<ExecutorResult> {
-    const workspaceRoot = context.root;
-    const limit = options.limit ?? 900;
-    const mode: FileMaxLimitMode = options.mode ?? 'MODIFIED_FILES';
-    const disableAllowed = options.disableAllowed ?? true;
-
-    // Skip validation entirely if mode is OFF
-    if (mode === 'OFF') {
-        console.log('\n\u23ed\ufe0f  Skipping modified files validation (mode: OFF)');
-        console.log('');
-        return { success: true };
-    }
-
-    // If NX_HEAD is set (via nx affected --head=X), use it; otherwise compare to working tree
-    let base = process.env['NX_BASE'];
-    const head = process.env['NX_HEAD'];
-
-    if (!base) {
-        base = detectBase(workspaceRoot) ?? undefined;
-
-        if (!base) {
-            console.log('\n\u23ed\ufe0f  Skipping modified files validation (could not detect base branch)');
-            console.log('   To run explicitly: nx affected --target=validate-modified-files --base=origin/main');
-            console.log('');
-            return { success: true };
-        }
-
-        console.log('\n\ud83d\udccf Validating Modified File Sizes (auto-detected base)\n');
-    } else {
-        console.log('\n\ud83d\udccf Validating Modified File Sizes\n');
-    }
-
-    console.log(`   Base: ${base}`);
-    console.log(`   Head: ${head ?? 'working tree (includes uncommitted changes)'}`);
-    console.log(`   Mode: ${mode}`);
-    console.log(`   Max lines for modified files: ${limit}`);
-    console.log(`   Disable allowed: ${disableAllowed}${!disableAllowed ? ' (no escape hatch)' : ''}`);
-    console.log('');
-
-    try {
-        const changedFiles = getChangedTypeScriptFiles(workspaceRoot, base, head);
-
-        if (changedFiles.length === 0) {
-            console.log('\u2705 No TypeScript files changed');
-            return { success: true };
-        }
-
-        console.log(`\ud83d\udcc2 Checking ${changedFiles.length} changed file(s)...`);
-
-        const violations = findViolations(workspaceRoot, changedFiles, limit, disableAllowed);
-
-        if (violations.length === 0) {
-            console.log('\u2705 All modified files are under ' + limit + ' lines');
-            return { success: true };
-        }
-
-        writeTmpInstructions(workspaceRoot);
-        reportViolations(violations, limit, disableAllowed);
-        return { success: false };
-    } catch (err: unknown) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        console.error('\u274c Modified files validation failed:', error.message);
-        return { success: false };
-    }
-}

package/architecture/executors/validate-modified-files/schema.json

@@ -1,25 +0,0 @@
-{
-    "$schema": "http://json-schema.org/schema",
-    "title": "Validate Modified Files Executor",
-    "description": "Validates that modified files don't exceed a maximum line count. Encourages keeping files small and focused.",
-    "type": "object",
-    "properties": {
-        "limit": {
-            "type": "number",
-            "description": "Maximum number of lines allowed for modified files",
-            "default": 900
-        },
-        "mode": {
-            "type": "string",
-            "enum": ["OFF", "MODIFIED_FILES"],
-            "description": "OFF: skip validation. MODIFIED_FILES: validate all code in modified files.",
-            "default": "MODIFIED_FILES"
-        },
-        "disableAllowed": {
-            "type": "boolean",
-            "description": "Whether disable comments work. When false, no escape hatch (like old STRICT mode).",
-            "default": true
-        }
-    },
-    "required": []
-}

package/architecture/executors/validate-modified-methods/executor.d.ts

@@ -1,31 +0,0 @@
-/**
- * Validate Modified Methods Executor
- *
- * Validates that modified methods don't exceed a maximum line count (default 80).
- * This encourages gradual cleanup of legacy long methods - when you touch a method,
- * you must bring it under the limit.
- *
- * Combined with validate-new-methods, this creates a gradual
- * transition to cleaner code:
- * - New methods: must be under limit
- * - Modified methods: must be under limit (cleanup when touched)
- * - Untouched methods: no limit (legacy allowed)
- *
- * Usage:
- * nx affected --target=validate-modified-methods --base=origin/main
- *
- * Escape hatch: Add webpieces-disable max-lines-modified comment with date and justification
- * Format: // webpieces-disable max-lines-modified 2025/01/15 -- [reason]
- * The disable expires after 1 month from the date specified.
- */
-import type { ExecutorContext } from '@nx/devkit';
-export type MethodMaxLimitMode = 'OFF' | 'NEW_METHODS' | 'NEW_AND_MODIFIED_METHODS' | 'MODIFIED_FILES';
-export interface ValidateModifiedMethodsOptions {
-    limit?: number;
-    mode?: MethodMaxLimitMode;
-    disableAllowed?: boolean;
-}
-export interface ExecutorResult {
-    success: boolean;
-}
-export default function runExecutor(options: ValidateModifiedMethodsOptions, context: ExecutorContext): Promise<ExecutorResult>;