@futdevpro/dynamo-eslint 1.15.25 → 1.20.2

package/.husky/pre-commit

@@ -1,2 +1,2 @@
-dc sync-fdp-deps --patch-only --stage
-dc bump-version
+dc sync-fdp-deps --patch-only --stage
+dc bump-version

package/.vscode/settings.json

@@ -1,11 +1,11 @@
-{
-  "eslint.run": "onSave",
-  "eslint.workingDirectories": [{ "mode": "auto" }],
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit"
-  },
-  "eslint.validate": [
-    "javascript",
-    "typescript"
-  ]
-}
+{
+  "eslint.run": "onSave",
+  "eslint.workingDirectories": [{ "mode": "auto" }],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "eslint.validate": [
+    "javascript",
+    "typescript"
+  ]
+}

package/README.md

@@ -1,320 +1,317 @@
-# @futdevpro/dynamo-eslint
-
-Shared ESLint presets, custom Dynamo rules, and validation tools for FutDevPro TypeScript projects. This package provides standardized linting configurations optimized for **lint-on-save** functionality across different project types.
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-npm install --save-dev @futdevpro/dynamo-eslint
-```
-
-### Required Peer Dependencies
-
-```bash
+# @futdevpro/dynamo-eslint
+
+Shared ESLint presets, custom Dynamo rules, and validation tools for FutDevPro TypeScript projects. This package provides standardized linting configurations optimized for **lint-on-save** functionality across different project types.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install --save-dev @futdevpro/dynamo-eslint
+```
+
+### Required Peer Dependencies
+
+```bash
 npm install --save-dev \
-  @typescript-eslint/eslint-plugin@^8.0.0 \
-  @typescript-eslint/parser@^8.0.0 \
-  eslint@^9.0.0 \
-  eslint-plugin-import@^2.29.0 \
-  eslint-plugin-jsdoc@^48.0.0 \
-  eslint-plugin-prettier@^5.1.3 \
-  prettier@^3.3.0
-```
-
+  eslint@~9.39.5 \
+  typescript@5.9.3 \
+  typescript-eslint@~8.67.0
+```
+
 For Angular projects, also install:
-```bash
+```bash
 npm install --save-dev \
-  @angular-eslint/eslint-plugin@^19.0.0 \
-  @angular-eslint/eslint-plugin-template@^19.0.0 \
-  @angular-eslint/template-parser@^19.0.0
-```
-
-## 📋 Available Presets
-
-### 1. **base** - Core TypeScript Rules
-Generic TypeScript projects with browser environment.
-
-```javascript
-const baseConfig = require('@futdevpro/dynamo-eslint/base');
-
-module.exports = baseConfig;
-```
-
-**Features:**
-- Browser environment
-- 1000 line limit
-- All Dynamo custom rules enabled
-- Explicit return types required
-
-### 2. **nts** - Node TypeScript Projects
-Node.js TypeScript applications and services.
-
-```javascript
-const ntsConfig = require('@futdevpro/dynamo-eslint/nts');
-
-module.exports = ntsConfig;
-```
-
-**Features:**
-- Node environment
-- 1500 line limit (extended for server code)
-- Module source type
-- All base rules + Node-specific optimizations
-
-### 3. **ngx** - Angular Projects
-Angular applications with component and template linting.
-
-```javascript
-const ngxConfig = require('@futdevpro/dynamo-eslint/ngx');
-
-module.exports = ngxConfig;
-```
-
-**Features:**
-- Angular ESLint integration
-- Browser environment
-- Component and template linting
-- Angular-specific rules
-
-### 4. **fsm** - Full Stack Module
-Full-stack TypeScript modules (same as base).
-
-```javascript
-const fsmConfig = require('@futdevpro/dynamo-eslint/fsm');
-
-module.exports = fsmConfig;
-```
-
-### 5. **nts-package** - Node TypeScript Packages
-NPM packages and libraries built with TypeScript.
-
-```javascript
-const ntsPackageConfig = require('@futdevpro/dynamo-eslint/nts-package');
-
-module.exports = ntsPackageConfig;
-```
-
-**Features:**
-- Relaxed `@typescript-eslint/ban-types` and `no-explicit-any` rules
-- Optimized for package development
-- Extended line limits for library code
-
-### 6. **ngx-package** - Angular Packages
-Angular libraries and packages.
-
-```javascript
-const ngxPackageConfig = require('@futdevpro/dynamo-eslint/ngx-package');
-
-module.exports = ngxPackageConfig;
-```
-
-## ⚙️ Lint-on-Save Configuration
-
-**Critical: Configure ESLint to run ONLY on save, not on type!**
-
-### VSCode/Cursor Settings
-
-Create `.vscode/settings.json` in your project root:
-
-```json
-{
-  "eslint.run": "onSave",
-  "eslint.workingDirectories": [{ "mode": "auto" }],
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit"
-  },
-  "eslint.validate": [
-    "javascript",
-    "typescript"
-  ]
-}
+  angular-eslint@~20.7.0
 ```
 
-### Workspace vs User Settings
-
-- **Workspace settings** (`.vscode/settings.json`): Apply only to current project
-- **User settings**: Apply globally to all projects
-
-For team consistency, use workspace settings.
-
-### Multi-Root Workspace Configuration
-
-For workspaces with multiple projects:
-
-```json
-{
-  "eslint.run": "onSave",
-  "eslint.workingDirectories": [
-    { "mode": "auto" },
-    { "directory": "./packages/package-a" },
-    { "directory": "./packages/package-b" }
-  ],
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit"
-  }
-}
-```
-
-## 🔧 Custom Dynamo Rules
-
-This package includes custom ESLint rules for Dynamo conventions:
-
-### Import Rules
-- **`@futdevpro/dynamo/import-order`**: Enforces consistent import ordering
-- **`@futdevpro/dynamo/no-import-type`**: Forbids TypeScript `import type` syntax
-- **`@futdevpro/dynamo/no-js-import`**: Prevents importing `.js` files in TypeScript
-
-### Naming Rules
-- **`@futdevpro/dynamo/naming-patterns`**: Enforces DyFM naming conventions
-
-### Type Rules
-- **`@futdevpro/dynamo/explicit-types`**: Enforces explicit type annotations on all TypeScript declarations (functions, variables, parameters, class properties, destructuring)
-
-## 🛠️ CLI Validation Tools
-
-Use these commands to validate your codebase:
-
-```bash
-# Validate import ordering across all TypeScript files
-dynamo-validate-imports
-
-# Validate naming conventions across all TypeScript files  
-dynamo-validate-naming
-
-# Audit ESLint configurations for duplicate rules
-dynamo-eslintrc-audit
-
-# Run comprehensive fixes
-dynamo-fix
-
-# Fix missing type annotations (functions, variables, parameters, class properties)
-dynamo-fix-return-types
-```
-
-### NPM Scripts Integration
-
-Add to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "validate:imports": "dynamo-validate-imports",
-    "validate:naming": "dynamo-validate-naming",
-    "audit:eslintrc": "dynamo-eslintrc-audit",
-    "fix": "dynamo-fix",
-    "fix:types": "dynamo-fix-return-types"
-  }
-}
-```
-
-## 🔄 Migration from Manual Configs
-
-### Quick Migration Checklist
-
-1. **Install the package and peer dependencies**
-2. **Replace your `.eslintrc.json`** with the appropriate preset
-3. **Configure lint-on-save** in VSCode/Cursor settings
-4. **Run validation tools** to check for issues
-5. **Update CI/CD** to use the new configuration
-
-### Common Migration Issues
-
-- **Peer dependency conflicts**: Ensure all peer dependencies are installed
-- **Working directory issues**: Use `"eslint.workingDirectories": [{ "mode": "auto" }]`
-- **Rule conflicts**: The presets handle most conflicts automatically
-
-> 📖 **Detailed Migration Guide**: See [Migration Guide](./docs/migration.md) for step-by-step instructions.
-
-## 🐛 Troubleshooting
-
-### Lint-on-Save Not Working
-
-1. **Check ESLint is running on save only:**
-   ```json
-   {
-     "eslint.run": "onSave"  // NOT "onType"
-   }
-   ```
-
-2. **Verify working directories:**
-   ```json
-   {
-     "eslint.workingDirectories": [{ "mode": "auto" }]
-   }
-   ```
-
-3. **Check file associations:**
-   ```json
-   {
-     "eslint.validate": ["javascript", "typescript"]
-   }
-   ```
-
-### Peer Dependency Issues
-
-Ensure all peer dependencies are installed with compatible versions:
-
-```bash
-npm ls @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint
-```
-
-### ESLint v9 Flat Config
-
-This package now uses ESLint v9 flat config format (`eslint.config.js`) for all exported presets. The package itself also uses flat config for self-linting.
-
-## 📁 Examples
-
-Reference implementations are available in the `samples/` directory:
-
-- `samples/base/eslint.config.js` - Base preset example
-- `samples/nts/eslint.config.js` - Node TypeScript example  
-- `samples/ngx/eslint.config.js` - Angular example
-- `samples/fsm/eslint.config.js` - Full Stack Module example
-- `samples/nts-package/eslint.config.js` - Node TypeScript Package example
-- `samples/ngx-package/eslint.config.js` - Angular Package example
-
-## 🔧 Recent Fixes
-
-### TypeScript AST Transformation Context Fix
-
-The `dynamo-fix-return-types` script includes a fix for TypeScript AST transformation context issues. This resolves compilation errors when using `ts.visitEachChild()` by properly providing the `TransformationContext` parameter:
-
-```typescript
-// Fixed implementation
-return ts.visitEachChild(node, visit, {} as ts.TransformationContext);
-```
-
-This ensures compatibility with TypeScript's AST transformation APIs.
-
-### Enhanced Type Annotation Fixing
-
-The `dynamo-fix-return-types` script now handles comprehensive type annotation fixing:
-
-- **Function declarations**: Adds return type annotations
-- **Arrow functions**: Adds return type annotations  
-- **Variable declarations**: Adds type annotations based on initializer types
-- **Function parameters**: Adds parameter type annotations
-- **Class properties**: Adds property type annotations
-
-The script uses TypeScript's type checker to infer appropriate types and automatically adds them to your code.
-
-## 📚 Self-Linting
-
-This package uses its own presets and rules for self-linting. The ESLint v9 flat config is in `eslint.config.js` and demonstrates advanced configuration patterns.
-
-## 🏗️ Architecture
-
-- **Presets**: Standardized rule configurations for different project types
-- **Custom Rules**: Dynamo-specific linting rules for import order and naming
-- **CLI Tools**: Validation and fixing utilities
-- **TypeScript Integration**: Full TypeScript AST transformation support
-
----
-
-**Maintained by**: Future Development Program Ltd.  
-**License**: ISC  
-**Version**: 02.00.0
+`angular-eslint` is an optional peer for Node-only consumers and is required when loading the `ngx` or
+`ngx-package` preset.
+
+## 📋 Available Presets
+
+### 1. **base** - Core TypeScript Rules
+Generic TypeScript projects with browser environment.
+
+```javascript
+const baseConfig = require('@futdevpro/dynamo-eslint/base');
+
+module.exports = baseConfig;
+```
+
+**Features:**
+- Browser environment
+- 1000 line limit
+- All Dynamo custom rules enabled
+- Explicit return types required
+
+### 2. **nts** - Node TypeScript Projects
+Node.js TypeScript applications and services.
+
+```javascript
+const ntsConfig = require('@futdevpro/dynamo-eslint/nts');
+
+module.exports = ntsConfig;
+```
+
+**Features:**
+- Node environment
+- 1500 line limit (extended for server code)
+- Module source type
+- All base rules + Node-specific optimizations
+
+### 3. **ngx** - Angular Projects
+Angular applications with component and template linting.
+
+```javascript
+const ngxConfig = require('@futdevpro/dynamo-eslint/ngx');
+
+module.exports = ngxConfig;
+```
+
+**Features:**
+- Angular ESLint integration
+- Browser environment
+- Component and template linting
+- Angular-specific rules
+
+### 4. **fsm** - Full Stack Module
+Full-stack TypeScript modules (same as base).
+
+```javascript
+const fsmConfig = require('@futdevpro/dynamo-eslint/fsm');
+
+module.exports = fsmConfig;
+```
+
+### 5. **nts-package** - Node TypeScript Packages
+NPM packages and libraries built with TypeScript.
+
+```javascript
+const ntsPackageConfig = require('@futdevpro/dynamo-eslint/nts-package');
+
+module.exports = ntsPackageConfig;
+```
+
+**Features:**
+- Relaxed `@typescript-eslint/ban-types` and `no-explicit-any` rules
+- Optimized for package development
+- Extended line limits for library code
+
+### 6. **ngx-package** - Angular Packages
+Angular libraries and packages.
+
+```javascript
+const ngxPackageConfig = require('@futdevpro/dynamo-eslint/ngx-package');
+
+module.exports = ngxPackageConfig;
+```
+
+## ⚙️ Lint-on-Save Configuration
+
+**Critical: Configure ESLint to run ONLY on save, not on type!**
+
+### VSCode/Cursor Settings
+
+Create `.vscode/settings.json` in your project root:
+
+```json
+{
+  "eslint.run": "onSave",
+  "eslint.workingDirectories": [{ "mode": "auto" }],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "eslint.validate": [
+    "javascript",
+    "typescript"
+  ]
+}
+```
+
+### Workspace vs User Settings
+
+- **Workspace settings** (`.vscode/settings.json`): Apply only to current project
+- **User settings**: Apply globally to all projects
+
+For team consistency, use workspace settings.
+
+### Multi-Root Workspace Configuration
+
+For workspaces with multiple projects:
+
+```json
+{
+  "eslint.run": "onSave",
+  "eslint.workingDirectories": [
+    { "mode": "auto" },
+    { "directory": "./packages/package-a" },
+    { "directory": "./packages/package-b" }
+  ],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  }
+}
+```
+
+## 🔧 Custom Dynamo Rules
+
+This package includes custom ESLint rules for Dynamo conventions:
+
+### Import Rules
+- **`@futdevpro/dynamo/import-order`**: Enforces consistent import ordering
+- **`@futdevpro/dynamo/no-import-type`**: Forbids TypeScript `import type` syntax
+- **`@futdevpro/dynamo/no-js-import`**: Prevents importing `.js` files in TypeScript
+
+### Naming Rules
+- **`@futdevpro/dynamo/naming-patterns`**: Enforces DyFM naming conventions
+
+### Type Rules
+- **`@futdevpro/dynamo/explicit-types`**: Enforces explicit type annotations on all TypeScript declarations (functions, variables, parameters, class properties, destructuring)
+
+## 🛠️ CLI Validation Tools
+
+Use these commands to validate your codebase:
+
+```bash
+# Validate import ordering across all TypeScript files
+dynamo-validate-imports
+
+# Validate naming conventions across all TypeScript files  
+dynamo-validate-naming
+
+# Audit ESLint configurations for duplicate rules
+dynamo-eslintrc-audit
+
+# Run comprehensive fixes
+dynamo-fix
+
+# Fix missing type annotations (functions, variables, parameters, class properties)
+dynamo-fix-return-types
+```
+
+### NPM Scripts Integration
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "validate:imports": "dynamo-validate-imports",
+    "validate:naming": "dynamo-validate-naming",
+    "audit:eslintrc": "dynamo-eslintrc-audit",
+    "fix": "dynamo-fix",
+    "fix:types": "dynamo-fix-return-types"
+  }
+}
+```
+
+## 🔄 Migration from Manual Configs
+
+### Quick Migration Checklist
+
+1. **Install the package and peer dependencies**
+2. **Replace your `.eslintrc.json`** with the appropriate preset
+3. **Configure lint-on-save** in VSCode/Cursor settings
+4. **Run validation tools** to check for issues
+5. **Update CI/CD** to use the new configuration
+
+### Common Migration Issues
+
+- **Peer dependency conflicts**: Ensure all peer dependencies are installed
+- **Working directory issues**: Use `"eslint.workingDirectories": [{ "mode": "auto" }]`
+- **Rule conflicts**: The presets handle most conflicts automatically
+
+> 📖 **Detailed Migration Guide**: See [Migration Guide](./docs/migration.md) for step-by-step instructions.
+
+## 🐛 Troubleshooting
+
+### Lint-on-Save Not Working
+
+1. **Check ESLint is running on save only:**
+   ```json
+   {
+     "eslint.run": "onSave"  // NOT "onType"
+   }
+   ```
+
+2. **Verify working directories:**
+   ```json
+   {
+     "eslint.workingDirectories": [{ "mode": "auto" }]
+   }
+   ```
+
+3. **Check file associations:**
+   ```json
+   {
+     "eslint.validate": ["javascript", "typescript"]
+   }
+   ```
+
+### Peer Dependency Issues
+
+Ensure all peer dependencies are installed with compatible versions:
+
+```bash
+npm ls typescript-eslint angular-eslint eslint typescript
+```
+
+### ESLint v9 Flat Config
+
+This package now uses ESLint v9 flat config format (`eslint.config.js`) for all exported presets. The package itself also uses flat config for self-linting.
+
+## 📁 Examples
+
+Reference implementations are available in the `samples/` directory:
+
+- `samples/base/eslint.config.js` - Base preset example
+- `samples/nts/eslint.config.js` - Node TypeScript example  
+- `samples/ngx/eslint.config.js` - Angular example
+- `samples/fsm/eslint.config.js` - Full Stack Module example
+- `samples/nts-package/eslint.config.js` - Node TypeScript Package example
+- `samples/ngx-package/eslint.config.js` - Angular Package example
+
+## 🔧 Recent Fixes
+
+### TypeScript AST Transformation Context Fix
+
+The `dynamo-fix-return-types` script includes a fix for TypeScript AST transformation context issues. This resolves compilation errors when using `ts.visitEachChild()` by properly providing the `TransformationContext` parameter:
+
+```typescript
+// Fixed implementation
+return ts.visitEachChild(node, visit, {} as ts.TransformationContext);
+```
+
+This ensures compatibility with TypeScript's AST transformation APIs.
+
+### Enhanced Type Annotation Fixing
+
+The `dynamo-fix-return-types` script now handles comprehensive type annotation fixing:
+
+- **Function declarations**: Adds return type annotations
+- **Arrow functions**: Adds return type annotations  
+- **Variable declarations**: Adds type annotations based on initializer types
+- **Function parameters**: Adds parameter type annotations
+- **Class properties**: Adds property type annotations
+
+The script uses TypeScript's type checker to infer appropriate types and automatically adds them to your code.
+
+## 📚 Self-Linting
+
+This package uses its own presets and rules for self-linting. The ESLint v9 flat config is in `eslint.config.js` and demonstrates advanced configuration patterns.
+
+## 🏗️ Architecture
+
+- **Presets**: Standardized rule configurations for different project types
+- **Custom Rules**: Dynamo-specific linting rules for import order and naming
+- **CLI Tools**: Validation and fixing utilities
+- **TypeScript Integration**: Full TypeScript AST transformation support
+
+---
+
+**Maintained by**: Future Development Program Ltd.  
+**License**: ISC  
+**Version**: 1.20.2