@webpieces/dev-config 0.0.0-dev

package/bin/use-published-webpieces.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+set -e
+
+# Switch back to published webpieces packages from npm
+# This script removes local symlinks and reinstalls from npm
+
+# Detect project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ "$SCRIPT_DIR" == *"node_modules/@webpieces/dev-config"* ]]; then
+  # Running in consumer project
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+else
+  # Running in webpieces-ts workspace
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+fi
+
+cd "$PROJECT_ROOT" || exit 1
+
+echo "📦 Switching to published @webpieces packages..."
+
+# Remove all @webpieces symlinks
+echo "   Removing local symlinks..."
+rm -rf node_modules/@webpieces
+
+# Reinstall from npm
+echo "   Reinstalling from npm..."
+npm install
+
+echo ""
+echo "✅ Successfully switched to published @webpieces packages from npm"
+echo "   To switch back to local development, run: wp-use-local"
+echo "   (Make sure to set WEBPIECES_ROOT environment variable first)"

package/config/eslint/base.mjs

@@ -0,0 +1,91 @@
+// @webpieces/dev-config base ESLint configuration
+// Consumer projects can extend this configuration
+
+import webpiecesPlugin from '../../eslint-plugin/index.js';
+
+/**
+ * WebPieces base ESLint configuration using flat config format.
+ *
+ * This provides sensible defaults for TypeScript projects following
+ * WebPieces patterns and conventions.
+ *
+ * Includes custom WebPieces rules:
+ * - catch-error-pattern: Enforces toError() usage in catch blocks
+ *
+ * Usage in consumer projects:
+ *
+ * ```javascript
+ * // eslint.config.mjs
+ * import webpiecesConfig from '@webpieces/dev-config/eslint';
+ * import nx from '@nx/eslint-plugin';
+ *
+ * export default [
+ *   ...webpiecesConfig,
+ *   ...nx.configs['flat/typescript'],
+ *   {
+ *     // Project-specific overrides
+ *     rules: {}
+ *   }
+ * ];
+ * ```
+ */
+export default [
+    {
+        // Ignore common directories
+        ignores: [
+            '**/dist',
+            '**/out-tsc',
+            '**/tmp',
+            '**/coverage',
+            '**/node_modules',
+            '**/.nx',
+            '**/.vscode',
+            '**/.idea',
+        ],
+    },
+    {
+        files: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx'],
+        plugins: {
+            '@webpieces': webpiecesPlugin,
+        },
+        languageOptions: {
+            ecmaVersion: 2021,
+            sourceType: 'module',
+        },
+        rules: {
+            // WebPieces custom rules
+            '@webpieces/catch-error-pattern': 'error',
+            // General code quality
+            'no-console': 'off', // Allow console for logging
+            'no-debugger': 'warn',
+            'no-alert': 'warn',
+            'no-var': 'error',
+            'prefer-const': 'warn',
+            'prefer-arrow-callback': 'warn',
+
+            // TypeScript rules (when @typescript-eslint is available)
+            '@typescript-eslint/no-explicit-any': 'warn', // Prefer unknown over any
+            '@typescript-eslint/explicit-function-return-type': 'off', // Allow inference
+            '@typescript-eslint/no-unused-vars': [
+                'warn',
+                {
+                    argsIgnorePattern: '^_',
+                    varsIgnorePattern: '^_',
+                },
+            ],
+            '@typescript-eslint/no-empty-interface': 'off', // WebPieces uses classes for data
+            '@typescript-eslint/no-empty-function': 'off',
+
+            // Import organization
+            'sort-imports': 'off', // Handled by IDE
+        },
+    },
+    {
+        // Specific rules for test files
+        files: ['**/*.spec.ts', '**/*.test.ts'],
+        rules: {
+            '@typescript-eslint/no-explicit-any': 'off', // Allow any in tests
+            '@typescript-eslint/no-non-null-assertion': 'off',
+        },
+    },
+];

package/config/typescript/tsconfig.base.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://json.schemastore.org/tsconfig",
+    "compileOnSave": false,
+    "compilerOptions": {
+        "sourceMap": true,
+        "inlineSources": true,
+        "declaration": true,
+        "moduleResolution": "node",
+        "emitDecoratorMetadata": true,
+        "experimentalDecorators": true,
+        "importHelpers": true,
+        "target": "ES2021",
+        "module": "commonjs",
+        "lib": ["ES2021"],
+        "skipLibCheck": true,
+        "skipDefaultLibCheck": true,
+        "strict": true,
+        "esModuleInterop": true,
+        "resolveJsonModule": true,
+        "forceConsistentCasingInFileNames": true,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "exclude": ["node_modules", "tmp", "dist", "out-tsc", "**/*.spec.ts", "**/*.test.ts"]
+}

package/eslint-plugin/__tests__/catch-error-pattern.test.ts

@@ -0,0 +1,360 @@
+/**
+ * Tests for catch-error-pattern ESLint rule
+ */
+
+/* eslint-disable @webpieces/catch-error-pattern */
+import { RuleTester } from 'eslint';
+import rule from '../rules/catch-error-pattern';
+
+// Use require to load parser at runtime (avoids TypeScript import issues)
+const tsParser = require('@typescript-eslint/parser');
+
+const ruleTester = new RuleTester({
+    languageOptions: {
+        parser: tsParser,
+        parserOptions: {
+            ecmaVersion: 2020,
+            sourceType: 'module',
+        },
+    },
+});
+
+ruleTester.run('catch-error-pattern', rule, {
+    valid: [
+        // Pattern 1: Standard toError usage
+        {
+            code: `try {
+    doSomething();
+} catch (err: any) {
+    const error = toError(err);
+}`,
+        },
+        // Pattern 1 with additional statements after toError
+        {
+            code: `try {
+    doSomething();
+} catch (err: any) {
+    const error = toError(err);
+    console.log('Error occurred:', error);
+    throw error;
+}`,
+        },
+        // Pattern 2: Explicitly ignored error
+        {
+            code: `try {
+    doSomething();
+} catch (err: any) {
+    //const error = toError(err);
+}`,
+        },
+        // Pattern 2 with extra whitespace
+        {
+            code: `try {
+    doSomething();
+} catch (err: any) {
+    // const error = toError(err);
+}`,
+        },
+        // Pattern 3: Nested catch blocks
+        {
+            code: `try {
+    doSomething();
+} catch (err: any) {
+    const error = toError(err);
+    try {
+        cleanup();
+    } catch (err2: any) {
+        const error2 = toError(err2);
+    }
+}`,
+        },
+        // Triple nested
+        {
+            code: `try {
+    operation1();
+} catch (err: any) {
+    const error = toError(err);
+    try {
+        operation2();
+    } catch (err2: any) {
+        const error2 = toError(err2);
+        try {
+            operation3();
+        } catch (err3: any) {
+            const error3 = toError(err3);
+        }
+    }
+}`,
+        },
+        // With finally block
+        {
+            code: `try {
+    doSomething();
+} catch (err: any) {
+    const error = toError(err);
+} finally {
+    cleanup();
+}`,
+        },
+        // Re-throwing after toError
+        {
+            code: `try {
+    doSomething();
+} catch (err: any) {
+    const error = toError(err);
+    logger.error(error);
+    throw error;
+}`,
+        },
+    ],
+
+    invalid: [
+        // Wrong parameter name (e instead of err)
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (e: any) {
+                    const error = toError(e);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'wrongParameterName',
+                    data: { actual: 'e' },
+                },
+            ],
+        },
+        // Wrong parameter name (error instead of err) AND wrong variable name
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (error: any) {
+                    const error2 = toError(error);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'wrongParameterName',
+                    data: { actual: 'error' },
+                },
+                {
+                    messageId: 'wrongVariableName',
+                    data: { expected: 'error', actual: 'error2' },
+                },
+            ],
+        },
+        // Missing type annotation
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err) {
+                    const error = toError(err);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingTypeAnnotation',
+                },
+            ],
+        },
+        // Wrong type annotation (Error instead of any)
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: Error) {
+                    const error = toError(err);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingTypeAnnotation',
+                },
+            ],
+        },
+        // Empty catch block
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingToError',
+                },
+            ],
+        },
+        // Missing toError call
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                    console.log(err);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingToError',
+                },
+            ],
+        },
+        // Wrong variable name (e instead of error)
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                    const e = toError(err);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'wrongVariableName',
+                    data: { expected: 'error', actual: 'e' },
+                },
+            ],
+        },
+        // Wrong variable name (myError instead of error)
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                    const myError = toError(err);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'wrongVariableName',
+                    data: { expected: 'error', actual: 'myError' },
+                },
+            ],
+        },
+        // toError not first statement
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                    console.log('caught error');
+                    const error = toError(err);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingToError',
+                },
+            ],
+        },
+        // Using wrong function (not toError)
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                    const error = handleError(err);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingToError',
+                },
+            ],
+        },
+        // Nested: wrong parameter name for err2
+        {
+            code: `
+                try {
+                    operation1();
+                } catch (err: any) {
+                    const error = toError(err);
+                    try {
+                        operation2();
+                    } catch (e: any) {
+                        const error2 = toError(e);
+                    }
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'wrongParameterName',
+                    data: { actual: 'e' },
+                },
+            ],
+        },
+        // Nested: wrong variable name for error2
+        {
+            code: `
+                try {
+                    operation1();
+                } catch (err: any) {
+                    const error = toError(err);
+                    try {
+                        operation2();
+                    } catch (err2: any) {
+                        const err = toError(err2);
+                    }
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'wrongVariableName',
+                    data: { expected: 'error2', actual: 'err' },
+                },
+            ],
+        },
+        // No parameter at all
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch {
+                    console.log('error');
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingTypeAnnotation',
+                },
+            ],
+        },
+        // Variable declared but not initialized
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                    const error;
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingToError',
+                },
+            ],
+        },
+        // Using new Error instead of toError
+        {
+            code: `
+                try {
+                    doSomething();
+                } catch (err: any) {
+                    const error = new Error(err.message);
+                }
+            `,
+            errors: [
+                {
+                    messageId: 'missingToError',
+                },
+            ],
+        },
+    ],
+});
+
+console.log('✅ All catch-error-pattern rule tests passed!');

package/eslint-plugin/__tests__/max-file-lines.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Tests for max-file-lines ESLint rule
+ */
+
+import { RuleTester } from 'eslint';
+import rule from '../rules/max-file-lines';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Use require to load parser at runtime (avoids TypeScript import issues)
+const tsParser = require('@typescript-eslint/parser');
+
+const ruleTester = new RuleTester({
+    languageOptions: {
+        parser: tsParser,
+        parserOptions: {
+            ecmaVersion: 2020,
+            sourceType: 'module',
+        },
+    },
+});
+
+ruleTester.run('max-file-lines', rule, {
+    valid: [
+        // Short file (well under limit)
+        {
+            code: `function shortFunc() {
+    return 42;
+}`,
+        },
+        // File with exactly 700 lines (default limit)
+        {
+            code: Array(700)
+                .fill(0)
+                .map((_, i) => `const line${i} = ${i};`)
+                .join('\n'),
+        },
+        // File with 699 lines (just under default limit)
+        {
+            code: Array(699)
+                .fill(0)
+                .map((_, i) => `const line${i} = ${i};`)
+                .join('\n'),
+        },
+        // Custom limit: 10 lines
+        {
+            code: `function shortFunc() {
+    const a = 1;
+    const b = 2;
+    const c = 3;
+    const d = 4;
+    const e = 5;
+    return a + b + c + d + e;
+}`,
+            options: [{ max: 10 }],
+        },
+        // Empty file
+        {
+            code: '',
+        },
+        // File with comments and blank lines (all count)
+        {
+            code: `// Comment line 1
+// Comment line 2
+
+function func() {
+    return 42;
+}
+
+// Another comment`,
+            options: [{ max: 10 }],
+        },
+    ],
+
+    invalid: [
+        // File with 701 lines (exceeds default limit)
+        {
+            code: Array(701)
+                .fill(0)
+                .map((_, i) => `const line${i} = ${i};`)
+                .join('\n'),
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { actual: '701', max: '700' },
+                },
+            ],
+        },
+        // File with 1000 lines (way over limit)
+        {
+            code: Array(1000)
+                .fill(0)
+                .map((_, i) => `const line${i} = ${i};`)
+                .join('\n'),
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { actual: '1000', max: '700' },
+                },
+            ],
+        },
+        // Custom limit: exceed 5 lines
+        {
+            code: `function func() {
+    const a = 1;
+    const b = 2;
+    const c = 3;
+    const d = 4;
+    return a + b + c + d;
+}`,
+            options: [{ max: 5 }],
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { actual: '7', max: '5' },
+                },
+            ],
+        },
+        // Custom limit: exceed 100 lines
+        {
+            code: Array(101)
+                .fill(0)
+                .map((_, i) => `const line${i} = ${i};`)
+                .join('\n'),
+            options: [{ max: 100 }],
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { actual: '101', max: '100' },
+                },
+            ],
+        },
+        // File with blank lines and comments (all lines count)
+        {
+            code: `// Line 1
+// Line 2
+// Line 3
+
+function func() {
+    return 42;
+}
+
+// Line 9
+// Line 10
+// Line 11`,
+            options: [{ max: 10 }],
+            errors: [
+                {
+                    messageId: 'tooLong',
+                    data: { actual: '11', max: '10' },
+                },
+            ],
+        },
+    ],
+});
+
+console.log('✅ All max-file-lines rule tests passed!');
+
+// Test documentation file creation
+const docPath = path.join(process.cwd(), 'tmp', 'webpieces', 'webpieces.filesize.md');
+
+// Run a test that triggers violation
+try {
+    ruleTester.run('max-file-lines-doc-test', rule, {
+        valid: [],
+        invalid: [
+            {
+                code: Array(800)
+                    .fill(0)
+                    .map((_, i) => `const line${i} = ${i};`)
+                    .join('\n'),
+                errors: [{ messageId: 'tooLong' }],
+            },
+        ],
+    });
+} catch (err: any) {
+    //const error = toError(err);
+    // Test may fail, but file should be created
+}
+
+// Verify file was created
+if (!fs.existsSync(docPath)) {
+    throw new Error('Documentation file was not created at ' + docPath);
+}
+
+// Verify content has AI directive
+const content = fs.readFileSync(docPath, 'utf-8');
+if (!content.includes('READ THIS FILE to fix files that are too long')) {
+    throw new Error('Documentation file missing AI directive');
+}
+if (!content.includes('SINGLE COHESIVE UNIT')) {
+    throw new Error('Documentation file missing single cohesive unit principle');
+}
+
+console.log('✅ Documentation file creation test passed!');