@qvaroo/configs 1.0.0

package/README.md

@@ -0,0 +1,391 @@
+# @qvaro/configs
+
+> **Centralized Qvaro coding standards for TypeScript frontend projects.**
+>
+> This library acts as the **single source of truth** for all coding, architecture, and tooling standards. All rule violations **fail CI/CD pipelines**, removing human discretion from standards enforcement.
+
+[![npm version](https://img.shields.io/npm/v/@qvaro/configs.svg)](https://www.npmjs.com/package/@qvaro/configs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install --save-dev @qvaro/configs
+```
+
+### Peer Dependencies
+
+Ensure these are installed in your project:
+
+```bash
+npm install --save-dev eslint prettier typescript
+```
+
+---
+
+## 🚀 Quick Setup
+
+### 1. ESLint Configuration
+
+Create `.eslintrc.js` in your project root:
+
+**For React/Next.js projects:**
+```javascript
+module.exports = {
+  extends: ['./node_modules/@qvaro/configs/eslint/react.js'],
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
+};
+```
+
+**For Node.js/Backend projects:**
+```javascript
+module.exports = {
+  extends: ['./node_modules/@qvaro/configs/eslint/node.js'],
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
+};
+```
+
+**For base TypeScript projects:**
+```javascript
+module.exports = {
+  extends: ['./node_modules/@qvaro/configs/eslint/index.js'],
+  parserOptions: {
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
+  },
+};
+```
+
+### 2. Prettier Configuration
+
+Create `prettier.config.js`:
+
+```javascript
+module.exports = require('@qvaro/configs/prettier');
+```
+
+### 3. TypeScript Configuration
+
+Create `tsconfig.json`:
+
+**For React projects:**
+```json
+{
+  "extends": "@qvaro/configs/typescript/react",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**For Node.js projects:**
+```json
+{
+  "extends": "@qvaro/configs/typescript/node",
+  "compilerOptions": {
+    "baseUrl": "."
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+---
+
+## 📐 Enforced Standards
+
+### Naming Conventions
+
+| Element | Format | Example |
+|---------|--------|---------|
+| Classes, Controllers, Models | `PascalCase` | `UserController` |
+| UI Components | `PascalCase` | `NavigationBar` |
+| Interfaces | `IPascalCase` | `IUserService` |
+| Local variables | `camelCase` | `userData` |
+| Method parameters | `camelCase` | `userId` |
+| Constants | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` |
+| Private methods | `_camelCase` | `_validateInput` |
+| Async methods | `*Async` suffix | `fetchUserAsync` |
+
+### Code Quality Limits
+
+| Rule | Limit | Severity |
+|------|-------|----------|
+| Method length | 40 lines max | ❌ Error |
+| File/Class length | 300 lines max | ❌ Error |
+| Nested if statements | 2 levels max | ❌ Error |
+| Cyclomatic complexity | 10 max | ❌ Error |
+| Function parameters | 4 max | ❌ Error |
+
+### Prohibited Patterns
+
+- ❌ Magic strings/numbers (use constants)
+- ❌ Empty catch blocks (must log & rethrow)
+- ❌ Deeply nested code (use guard clauses)
+- ❌ Floating promises (must await or handle)
+- ❌ Any type usage (must be explicit)
+
+---
+
+## 🏗️ Folder Structure Enforcement
+
+Required project structure:
+
+```
+src/
+├── api/          # API clients & endpoints
+├── components/   # Reusable UI components
+├── services/     # Business logic layer
+├── events/       # Event handlers & emitters
+├── animations/   # Animation definitions
+├── styles/       # Global styles & themes
+├── hooks/        # Custom React hooks
+├── views/        # Page-level components (presentation only)
+├── types/        # TypeScript interfaces & types
+├── constants/    # Application constants
+└── utils/        # Utility functions
+```
+
+### Boundary Rules
+
+| Layer | Can Import From |
+|-------|-----------------|
+| `views` | components, styles, hooks, animations, constants |
+| `components` | components, styles, hooks, utils, types, animations |
+| `hooks` | services, api, types, utils |
+| `services` | api, types, utils, constants |
+| `api` | types, utils, constants |
+
+> ⚠️ **Views cannot import from `api` or `services` directly!** Use hooks instead.
+
+---
+
+## 🔧 CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Lint & Type Check
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+      - run: npm run lint
+        # Fails on any lint error
+      - run: npx tsc --noEmit
+        # Fails on type errors
+```
+
+### Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "lint": "eslint . --ext .ts,.tsx --max-warnings 0",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,json,css}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,css}\"",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+---
+
+## 📝 Examples
+
+### ✅ Correct Naming
+
+```typescript
+// Constants - UPPER_SNAKE_CASE
+const MAX_RETRY_ATTEMPTS = 3;
+const API_BASE_URL = 'https://api.example.com';
+
+// Interface - IPascalCase
+interface IUserProfile {
+  id: string;
+  displayName: string;
+}
+
+// Class - PascalCase
+class UserService {
+  // Private property - _camelCase
+  private readonly _httpClient: IHttpClient;
+
+  // Async method - ends with Async
+  public async fetchUserAsync(userId: string): Promise<IUserProfile> {
+    return await this._httpClient.getAsync(`/users/${userId}`);
+  }
+
+  // Private async method
+  private async _validateTokenAsync(): Promise<boolean> {
+    // ...
+  }
+}
+```
+
+### ❌ Incorrect (Will Fail)
+
+```typescript
+// ❌ Magic number
+if (retryCount > 3) { }
+
+// ❌ Interface without I prefix
+interface UserProfile { }
+
+// ❌ Async method without Async suffix
+async function fetchUser() { }
+
+// ❌ Empty catch block
+try {
+  await riskyOperation();
+} catch (e) {
+  // Empty - will error!
+}
+
+// ❌ Too much nesting
+if (a) {
+  if (b) {
+    if (c) { // Error: max depth 2
+    }
+  }
+}
+```
+
+### ✅ Guard Clause Pattern
+
+```typescript
+// ✅ Preferred: Early returns
+function processUser(user: IUser | null): void {
+  if (!user) {
+    throw new Error('User is required');
+  }
+
+  if (!user.isActive) {
+    return;
+  }
+
+  // Main logic here (flat, readable)
+  performAction(user);
+}
+
+// ❌ Avoid: Deep nesting
+function processUser(user: IUser | null): void {
+  if (user) {
+    if (user.isActive) {
+      performAction(user);
+    }
+  } else {
+    throw new Error('User is required');
+  }
+}
+```
+
+---
+
+## 🔄 Extending Rules
+
+Override specific rules in your project's `.eslintrc.js`:
+
+```javascript
+module.exports = {
+  extends: ['./node_modules/@qvaro/configs/eslint/react.js'],
+  rules: {
+    // Relax for specific project needs
+    'max-lines-per-function': ['error', { max: 60 }],
+
+    // Add project-specific rules
+    'no-restricted-imports': ['error', {
+      patterns: ['lodash/*'],
+    }],
+  },
+};
+```
+
+---
+
+## 📋 Spellcheck Configuration
+
+Variable names are checked for spelling. Add project-specific terms:
+
+```javascript
+module.exports = {
+  extends: ['./node_modules/@qvaro/configs/eslint'],
+  rules: {
+    'spellcheck/spell-checker': ['warn', {
+      skipWords: [
+        // Add your domain terms
+        'qvaro',
+        'oauth',
+        'saml',
+      ],
+    }],
+  },
+};
+```
+
+---
+
+## 🛡️ Enforcement Philosophy
+
+> *"All rules are strictly enforced. Violations fail CI/CD pipelines. This library acts as the single source of truth, removing human discretion from coding standards enforcement."*
+
+### Why Strict Enforcement?
+
+1. **Consistency** - Every project follows identical standards
+2. **Onboarding** - New developers learn patterns immediately
+3. **Code Review** - Focus on logic, not style debates
+4. **Maintainability** - Consistent code is easier to maintain
+5. **Quality** - Prevents common bugs before they ship
+
+---
+
+## 📁 Package Contents
+
+```
+@qvaro/configs/
+├── eslint/
+│   ├── index.js          # Base ESLint config
+│   ├── react.js          # React/Next.js config
+│   ├── node.js           # Node.js/Backend config
+│   └── rules/
+│       ├── naming-conventions.js
+│       ├── code-quality.js
+│       ├── architecture.js
+│       └── spellcheck.js
+├── prettier/
+│   └── index.js          # Prettier config
+├── typescript/
+│   ├── tsconfig.json         # Base TS config
+│   ├── tsconfig.react.json   # React TS config
+│   └── tsconfig.node.json    # Node.js TS config
+├── index.js
+├── index.d.ts
+└── package.json
+```
+
+---
+
+## 📄 License
+
+MIT © Qvaro DevOps Team

package/eslint/index.js

@@ -0,0 +1,222 @@
+/**
+ * @qvaroo/configs - ESLint Configuration
+ * 
+ * Strict Qvaroo-wide ESLint rules for TypeScript projects.
+ * All violations will fail CI/CD pipelines.
+ * 
+ * @author Qvaroo DevOps Team
+ * @version 1.0.0
+ */
+
+const namingConventionRules = require('./rules/naming-conventions');
+const codeQualityRules = require('./rules/code-quality');
+const architectureRules = require('./rules/architecture');
+const spellcheckRules = require('./rules/spellcheck');
+
+/** @type {import('eslint').Linter.Config} */
+module.exports = {
+    root: true,
+
+    parser: '@typescript-eslint/parser',
+
+    parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        project: './tsconfig.json',
+        tsconfigRootDir: process.cwd(),
+    },
+
+    plugins: [
+        '@typescript-eslint',
+        'spellcheck',
+        'boundaries',
+        'import',
+        'promise',
+        'unicorn',
+        'sonarjs',
+    ],
+
+    extends: [
+        'eslint:recommended',
+        'plugin:@typescript-eslint/recommended',
+        'plugin:@typescript-eslint/recommended-requiring-type-checking',
+        'plugin:@typescript-eslint/strict',
+        'plugin:import/recommended',
+        'plugin:import/typescript',
+        'plugin:promise/recommended',
+        'plugin:sonarjs/recommended',
+        'prettier', // Must be last to override formatting rules
+    ],
+
+    settings: {
+        'import/resolver': {
+            typescript: {
+                alwaysTryTypes: true,
+                project: './tsconfig.json',
+            },
+        },
+        'boundaries/elements': [
+            { type: 'api', pattern: 'src/api/*' },
+            { type: 'components', pattern: 'src/components/*' },
+            { type: 'services', pattern: 'src/services/*' },
+            { type: 'events', pattern: 'src/events/*' },
+            { type: 'animations', pattern: 'src/animations/*' },
+            { type: 'styles', pattern: 'src/styles/*' },
+            { type: 'utils', pattern: 'src/utils/*' },
+            { type: 'types', pattern: 'src/types/*' },
+            { type: 'constants', pattern: 'src/constants/*' },
+            { type: 'hooks', pattern: 'src/hooks/*' },
+            { type: 'views', pattern: 'src/views/*' },
+        ],
+    },
+
+    rules: {
+        // ═══════════════════════════════════════════════════════════════════════
+        // NAMING CONVENTIONS - Strict enforcement
+        // ═══════════════════════════════════════════════════════════════════════
+        ...namingConventionRules,
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // CODE QUALITY - Method/class length, nesting, magic values
+        // ═══════════════════════════════════════════════════════════════════════
+        ...codeQualityRules,
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // ARCHITECTURE - Folder boundaries and separation of concerns
+        // ═══════════════════════════════════════════════════════════════════════
+        ...architectureRules,
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // SPELLCHECK - Variable name clarity
+        // ═══════════════════════════════════════════════════════════════════════
+        ...spellcheckRules,
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // ERROR HANDLING - No empty catches, must log & rethrow
+        // ═══════════════════════════════════════════════════════════════════════
+        'no-empty': ['error', { allowEmptyCatch: false }],
+        '@typescript-eslint/no-empty-function': 'error',
+        'no-useless-catch': 'error',
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // PROMISE/ASYNC HANDLING
+        // ═══════════════════════════════════════════════════════════════════════
+        '@typescript-eslint/no-floating-promises': 'error',
+        '@typescript-eslint/no-misused-promises': 'error',
+        '@typescript-eslint/promise-function-async': 'error',
+        'promise/always-return': 'error',
+        'promise/no-return-wrap': 'error',
+        'promise/param-names': 'error',
+        'promise/catch-or-return': 'error',
+        'promise/no-nesting': 'warn',
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // IMPORT ORGANIZATION
+        // ═══════════════════════════════════════════════════════════════════════
+        'import/order': [
+            'error',
+            {
+                groups: [
+                    'builtin',
+                    'external',
+                    'internal',
+                    'parent',
+                    'sibling',
+                    'index',
+                    'type',
+                ],
+                'newlines-between': 'always',
+                alphabetize: { order: 'asc', caseInsensitive: true },
+            },
+        ],
+        'import/no-duplicates': 'error',
+        'import/no-unresolved': 'error',
+        'import/no-cycle': 'error',
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // GENERAL BEST PRACTICES
+        // ═══════════════════════════════════════════════════════════════════════
+        'no-console': ['error', { allow: ['warn', 'error', 'info'] }],
+        'no-debugger': 'error',
+        'no-alert': 'error',
+        'prefer-const': 'error',
+        'no-var': 'error',
+        'eqeqeq': ['error', 'always'],
+        'curly': ['error', 'all'],
+        'no-eval': 'error',
+        'no-implied-eval': 'error',
+        'no-new-func': 'error',
+        'no-return-await': 'off', // Handled by @typescript-eslint/return-await
+        '@typescript-eslint/return-await': ['error', 'in-try-catch'],
+        '@typescript-eslint/explicit-function-return-type': [
+            'error',
+            {
+                allowExpressions: true,
+                allowTypedFunctionExpressions: true,
+                allowHigherOrderFunctions: true,
+            },
+        ],
+        '@typescript-eslint/explicit-member-accessibility': [
+            'error',
+            { accessibility: 'explicit' },
+        ],
+        '@typescript-eslint/no-explicit-any': 'error',
+        '@typescript-eslint/no-unused-vars': [
+            'error',
+            { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+        ],
+
+        // ═══════════════════════════════════════════════════════════════════════
+        // UNICORN - Modern JavaScript practices
+        // ═══════════════════════════════════════════════════════════════════════
+        'unicorn/prefer-module': 'error',
+        'unicorn/prefer-node-protocol': 'error',
+        'unicorn/prefer-top-level-await': 'error',
+        'unicorn/no-null': 'off', // Allow null for React patterns
+        'unicorn/prevent-abbreviations': [
+            'error',
+            {
+                replacements: {
+                    props: false,
+                    params: false,
+                    args: false,
+                    ref: false,
+                    err: false,
+                    ctx: false,
+                    req: false,
+                    res: false,
+                },
+            },
+        ],
+    },
+
+    overrides: [
+        // Test files - relaxed rules
+        {
+            files: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx'],
+            rules: {
+                '@typescript-eslint/no-explicit-any': 'off',
+                'sonarjs/no-duplicate-string': 'off',
+                'max-lines-per-function': 'off',
+            },
+        },
+        // Configuration files
+        {
+            files: ['*.config.js', '*.config.ts', '.eslintrc.js'],
+            rules: {
+                '@typescript-eslint/no-var-requires': 'off',
+                'unicorn/prefer-module': 'off',
+            },
+        },
+    ],
+
+    ignorePatterns: [
+        'node_modules/',
+        'dist/',
+        'build/',
+        'coverage/',
+        '.next/',
+        '*.min.js',
+        '*.generated.ts',
+    ],
+};