mm_eslint 1.4.2 → 1.4.4

package/README.md

@@ -0,0 +1,325 @@
+# MM ESLint Plugin
+
+基于个人命名规范的ESLint插件，支持类名、类实例名、函数名、参数名、变量名、常量名等命名规范检测。
+
+[![npm version](https://img.shields.io/npm/v/mm_eslint.svg)](https://www.npmjs.com/package/mm_eslint)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D12.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## 功能特性
+
+- ✅ **类名检测** - 大驼峰命名法（PascalCase）
+- ✅ **类实例名检测** - 小驼峰命名法（camelCase）
+- ✅ **函数名检测** - 小驼峰命名法（camelCase）
+- ✅ **参数名检测** - 小写蛇形命名法（snake_case）
+- ✅ **变量名检测** - 小写蛇形命名法（snake_case）
+- ✅ **常量名检测** - 大写蛇形命名法（UPPER_SNAKE_CASE）
+- ✅ **长度限制** - 所有命名长度限制在1-20字符
+- ✅ **单词长度限制** - 每个单词限制在最大8字符
+- ✅ **禁止废话词** - 避免使用Manager、Handler等冗余词汇
+- ✅ **命名推荐功能** - 推荐更短的替代名称，同时保持语义不变
+
+## 实际支持的规则
+
+插件实际支持以下ESLint规则：
+- `naming-convention/class-name` - 类名检测
+- `naming-convention/class-instance-name` - 类实例名检测  
+- `naming-convention/function-name` - 函数名检测
+- `naming-convention/param-name` - 参数名检测
+- `naming-convention/variable-name` - 变量名检测
+- `naming-convention/constant-name` - 常量名检测
+
+## 安装
+
+### npm安装
+
+```bash
+npm install mm_eslint --save-dev
+```
+
+### 本地安装
+
+如果您想使用本地版本，可以将插件文件复制到项目中：
+
+```bash
+# 复制插件文件到您的项目
+cp mm_eslint/index.js your-project/eslint-plugins/
+```
+
+## 快速开始
+
+### 1. 基本配置
+
+在您的ESLint配置文件中引入插件：
+
+```javascript
+// eslint.config.js
+const namingConventionPlugin = require("mm_eslint");
+
+module.exports = [
+  {
+    files: ["**/*.js"],
+    plugins: {
+      "naming-convention": namingConventionPlugin,
+    },
+    rules: {
+      // 命名规范插件规则
+      "naming-convention/class-name": "error",
+      "naming-convention/class-instance-name": "error",
+      "naming-convention/function-name": "error",
+      "naming-convention/param-name": "warn",
+      "naming-convention/variable-name": "warn",
+      "naming-convention/constant-name": "error",
+
+      // 禁用与命名规范插件冲突的默认规则
+      camelcase: "off",
+      "id-match": "off",
+      "new-cap": "off",
+      "id-length": "off",
+    },
+  },
+];
+```
+
+### 2. 命令行使用
+
+```bash
+# 验证单个文件
+npx eslint your-file.js
+
+# 验证所有JS文件
+npx eslint "**/*.js"
+
+# 验证并自动修复
+npx eslint --fix your-file.js
+```
+
+## 命名规范规则
+
+### 类名规则（class-name）
+
+- **级别**: error
+- **要求**: 大驼峰命名法（PascalCase）
+- **长度**: 1-20字符
+- **单词长度**: 每个单词≤8字符
+- **示例**: `User`, `DbConn`
+- **错误示例**: `user`, `user_manager`, `UserManager`
+
+### 类实例名规则（class-instance-name）
+
+- **级别**: error
+- **要求**: 小驼峰命名法（camelCase）
+- **长度**: 1-20字符
+- **单词长度**: 每个单词≤8字符
+- **示例**: `userInstance`, `dbConn`
+- **错误示例**: `UserInstance`, `db_conn`, `DB_CONN`
+
+### 函数名规则（function-name）
+
+- **级别**: error
+- **要求**: 小驼峰命名法（camelCase）
+- **长度**: 1-20字符
+- **单词长度**: 每个单词≤8字符
+- **示例**: `get`, `getName`, `process`
+- **错误示例**: `Get`, `get_name`, `PROCESS`
+
+### 参数名规则（param-name）
+
+- **级别**: warn
+- **要求**: 小写蛇形命名法（snake_case）
+- **长度**: 1-20字符
+- **示例**: `user_name`, `max_count`
+- **错误示例**: `userName`, `maxCount`, `MAX_COUNT`
+
+### 变量名规则（variable-name）
+
+- **级别**: warn
+- **要求**: 小写蛇形命名法（snake_case）
+- **长度**: 1-20字符
+- **示例**: `user_count`, `max_retry`
+- **错误示例**: `userCount`, `maxRetry`, `MAX_RETRY`
+
+### 常量名规则（constant-name）
+
+- **级别**: error
+- **要求**: 大写蛇形命名法（UPPER_SNAKE_CASE）
+- **长度**: 1-20字符
+- **示例**: `MAX_RETRY`, `DEFAULT_TIMEOUT`
+- **错误示例**: `maxRetry`, `defaultTimeout`, `DefaultTimeout`
+
+## 错误示例
+
+```javascript
+// ❌ 错误的命名示例
+class user {}                           // 类名应该使用 PascalCase
+class user_manager {}                   // 类名应该使用 PascalCase
+class UserManager {}                    // 类名应该使用 PascalCase
+
+const userInstance = new User();        // 类实例名应该使用 camelCase
+const UserInstance = new User();       // 类实例名应该使用 camelCase
+
+function GetUser() {}                   // 函数名应该使用 camelCase
+function get_user() {}                  // 函数名应该使用 camelCase
+
+function process(userName) {}          // 参数名应该使用 snake_case
+const maxRetry = 5;                     // 变量名应该使用 snake_case
+const defaultTimeout = 1000;           // 常量名应该使用 UPPER_SNAKE_CASE
+
+// ✅ 正确的命名示例
+class User {}
+class DbConn {}
+
+const userInstance = new User();
+const dbConn = new DbConn();
+
+function getUser() {}
+function process() {}
+
+function process(user_name) {}
+const max_retry = 5;
+const DEFAULT_TIMEOUT = 1000;
+```
+
+## 单词长度验证
+
+插件验证复合名称中的每个单词不超过8个字符：
+
+- **有效**: `UserService`（"User"=4, "Service"=7）
+- **无效**: `UserConfiguration`（"Configuration"=13 > 8）
+- **有效**: `getUser`（"get"=3, "User"=4）
+- **无效**: `getConfiguration`（"Configuration"=13 > 8）
+
+## 禁止的冗余词汇
+
+插件会自动检测并禁止使用以下冗余词汇：
+
+**类名禁止词**: manager, handler, processor, controller, service, provider, factory, builder, adapter, decorator, proxy, facade, mediator, observer, strategy, command, visitor, iterator, template, flyweight, memento, interpreter, model, view, route, router, component, widget, panel, dialog, window, form, field, property, entity
+
+**函数名禁止词**: data, result, output, input, param, params, parameter, parameters, value, values, item, items, process, processor, provider, builder, adapter, decorator, proxy, facade, mediator, observer, strategy, command, visitor, iterator, template, flyweight, memento, interpreter, temp, tmp, temporary, cached, buffered, idx, counter, with
+
+**变量名禁止词**: object, array, map, set, collection, container, instance, data, item, items, element, elements, entry, entries, temp, tmp, temporary, cached, buffer, buffered, input, output, result, destination, index, idx, counter, length, total, sum, pointer, reference, ref, handle, handler, entity, column, property, attribute, manager, processor, controller, service, middleware, component, provider
+
+## 命名推荐功能
+
+插件包含智能命名推荐系统，建议使用更短的替代名称，同时保持语义不变。
+
+### 核心原则
+
+核心原则是**"缩短命名而不改变语义"**。推荐系统：
+- 推荐更短的单词，同时保持相同含义
+- 避免会改变功能的概念性变化
+- 确保推荐词始终比原词短
+- 保留编程特定术语和概念差异
+
+### 可用推荐
+
+插件为常见编程操作提供推荐：
+
+| 原词         | 推荐词   | 描述       |
+| ------------ | -------- | ---------- |
+| `calculate`  | `calc`   | 数学运算   |
+| `generate`   | `gen`    | 数据生成   |
+| `initialize` | `init`   | 初始化操作 |
+| `execute`    | `exec`   | 命令执行   |
+| `process`    | `run`    | 数据处理   |
+| `retrieve`   | `load`   | 数据加载   |
+| `persist`    | `save`   | 数据存储   |
+| `compare`    | `cmp`    | 比较操作   |
+| `duplicate`  | `copy`   | 数据复制   |
+| `transfer`   | `move`   | 数据移动   |
+| `convert`    | `to`     | 类型转换   |
+| `verify`     | `check`  | 验证检查   |
+| `construct`  | `create` | 对象创建   |
+| `handle`     | `run`    | 事件处理   |
+
+### 示例
+
+```javascript
+// ❌ 原词（较长名称）
+function calculateTotal() {}
+function generateUserData() {}
+function initializeSystem() {}
+function executeCommand() {}
+function processData() {}
+
+// ✅ 推荐词（较短名称）
+function calcTotal() {}
+function genUserData() {}
+function initSystem() {}
+function execCommand() {}
+function runData() {}
+```
+
+### 带推荐的错误消息
+
+启用推荐功能后，ESLint将建议替代名称：
+
+```bash
+# ESLint输出示例
+function calculateTotal() {}
+# ^ 建议使用'calc'替代'calculate'以获得更短的命名
+```
+
+## 开发
+
+### 项目结构
+
+```
+mm_eslint/
+├── index.js          # 主插件文件
+├── config.js         # 配置管理
+├── detector.js       # 命名检测器
+├── validator.js      # 验证器
+├── corrector.js      # 命名修正器
+├── tip.js            # 提示信息
+├── util.js           # 工具函数
+├── package.json      # npm配置
+├── README.md         # 中文说明文档
+├── README_EN.md      # 英文说明文档
+├── LICENSE           # 许可证
+└── tests/            # 测试文件
+    ├── success/      # 正确示例
+    ├── error/        # 错误示例
+    └── scence/       # 场景测试
+```
+
+### 运行测试
+
+```bash
+# 运行单元测试
+npm test
+
+# 运行ESLint检查
+npm run lint
+```
+
+## 许可证
+
+ISC License
+
+## 贡献
+
+欢迎提交Issue和Pull Request来改进这个插件。
+
+## 更新日志
+
+### v1.4.3
+- 优化模块结构和文件组织
+- 增强测试覆盖率和错误处理
+- 改进文档和示例
+
+### v1.2.0
+- 模块化重构版，职责分离
+- 增强配置管理
+- 改进命名检测算法
+
+### v1.1.0
+- 添加单词长度验证（每个单词最大8字符）
+- 添加入参名和属性名检测
+- 增强配置，包含完整的ESLint规则
+
+### v1.0.0
+- 初始版本发布
+- 支持类名、函数名、变量名、常量名、私有成员命名规范检测
+- 支持长度限制和单个单词优先规则
+- 支持禁止废话词检测

package/README_EN.md

@@ -0,0 +1,325 @@
+# MM ESLint Plugin
+
+ESLint plugin for personal naming conventions - supports PascalCase, camelCase, snake_case, and UPPER_SNAKE_CASE naming rules.
+
+[![npm version](https://img.shields.io/npm/v/mm_eslint.svg)](https://www.npmjs.com/package/mm_eslint)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D12.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## Features
+
+- ✅ **Class Name Detection** - PascalCase naming convention
+- ✅ **Class Instance Name Detection** - camelCase naming convention
+- ✅ **Function Name Detection** - camelCase naming convention
+- ✅ **Parameter Name Detection** - snake_case naming convention
+- ✅ **Variable Name Detection** - snake_case naming convention
+- ✅ **Constant Name Detection** - UPPER_SNAKE_CASE naming convention
+- ✅ **Length Limitation** - All names limited to 1-20 characters
+- ✅ **Word Length Limitation** - Each word limited to maximum 8 characters
+- ✅ **Redundant Word Prevention** - Avoids redundant words like Manager, Handler
+- ✅ **Name Recommendation** - Recommends shorter alternative names while preserving semantics
+
+## Actual Supported Rules
+
+The plugin actually supports the following ESLint rules:
+- `naming-convention/class-name` - Class name detection
+- `naming-convention/class-instance-name` - Class instance name detection  
+- `naming-convention/function-name` - Function name detection
+- `naming-convention/param-name` - Parameter name detection
+- `naming-convention/variable-name` - Variable name detection
+- `naming-convention/constant-name` - Constant name detection
+
+## Installation
+
+### npm Installation
+
+```bash
+npm install mm_eslint --save-dev
+```
+
+### Local Installation
+
+If you want to use a local version, you can copy the plugin files to your project:
+
+```bash
+# Copy plugin files to your project
+cp mm_eslint/index.js your-project/eslint-plugins/
+```
+
+## Quick Start
+
+### 1. Basic Configuration
+
+Import the plugin in your ESLint configuration file:
+
+```javascript
+// eslint.config.js
+const namingConventionPlugin = require("mm_eslint");
+
+module.exports = [
+  {
+    files: ["**/*.js"],
+    plugins: {
+      "naming-convention": namingConventionPlugin,
+    },
+    rules: {
+      // Naming convention plugin rules
+      "naming-convention/class-name": "error",
+      "naming-convention/class-instance-name": "error",
+      "naming-convention/function-name": "error",
+      "naming-convention/param-name": "warn",
+      "naming-convention/variable-name": "warn",
+      "naming-convention/constant-name": "error",
+
+      // Disable default rules conflicting with naming convention plugin
+      camelcase: "off",
+      "id-match": "off",
+      "new-cap": "off",
+      "id-length": "off",
+    },
+  },
+];
+```
+
+### 2. Command Line Usage
+
+```bash
+# Validate single file
+npx eslint your-file.js
+
+# Validate all JS files
+npx eslint "**/*.js"
+
+# Validate and auto-fix
+npx eslint --fix your-file.js
+```
+
+## Naming Convention Rules
+
+### Class Name Rule (class-name)
+
+- **Level**: error
+- **Requirement**: PascalCase naming convention
+- **Length**: 1-20 characters
+- **Word Length**: Each word ≤8 characters
+- **Example**: `User`, `DbConn`
+- **Error Example**: `user`, `user_manager`, `UserManager`
+
+### Class Instance Name Rule (class-instance-name)
+
+- **Level**: error
+- **Requirement**: camelCase naming convention
+- **Length**: 1-20 characters
+- **Word Length**: Each word ≤8 characters
+- **Example**: `userInstance`, `dbConn`
+- **Error Example**: `UserInstance`, `db_conn`, `DB_CONN`
+
+### Function Name Rule (function-name)
+
+- **Level**: error
+- **Requirement**: camelCase naming convention
+- **Length**: 1-20 characters
+- **Word Length**: Each word ≤8 characters
+- **Example**: `get`, `getName`, `process`
+- **Error Example**: `Get`, `get_name`, `PROCESS`
+
+### Parameter Name Rule (param-name)
+
+- **Level**: warn
+- **Requirement**: snake_case naming convention
+- **Length**: 1-20 characters
+- **Example**: `user_name`, `max_count`
+- **Error Example**: `userName`, `maxCount`, `MAX_COUNT`
+
+### Variable Name Rule (variable-name)
+
+- **Level**: warn
+- **Requirement**: snake_case naming convention
+- **Length**: 1-20 characters
+- **Example**: `user_count`, `max_retry`
+- **Error Example**: `userCount`, `maxRetry`, `MAX_RETRY`
+
+### Constant Name Rule (constant-name)
+
+- **Level**: error
+- **Requirement**: UPPER_SNAKE_CASE naming convention
+- **Length**: 1-20 characters
+- **Example**: `MAX_RETRY`, `DEFAULT_TIMEOUT`
+- **Error Example**: `maxRetry`, `defaultTimeout`, `DefaultTimeout`
+
+## Error Examples
+
+```javascript
+// ❌ Incorrect naming examples
+class user {}                           // Class name should use PascalCase
+class user_manager {}                   // Class name should use PascalCase
+class UserManager {}                    // Class name should use PascalCase
+
+const userInstance = new User();        // Class instance name should use camelCase
+const UserInstance = new User();       // Class instance name should use camelCase
+
+function GetUser() {}                   // Function name should use camelCase
+function get_user() {}                  // Function name should use camelCase
+
+function process(userName) {}          // Parameter name should use snake_case
+const maxRetry = 5;                     // Variable name should use snake_case
+const defaultTimeout = 1000;           // Constant name should use UPPER_SNAKE_CASE
+
+// ✅ Correct naming examples
+class User {}
+class DbConn {}
+
+const userInstance = new User();
+const dbConn = new DbConn();
+
+function getUser() {}
+function process() {}
+
+function process(user_name) {}
+const max_retry = 5;
+const DEFAULT_TIMEOUT = 1000;
+```
+
+## Word Length Validation
+
+The plugin validates that each word in compound names does not exceed 8 characters:
+
+- **Valid**: `UserService` ("User"=4, "Service"=7)
+- **Invalid**: `UserConfiguration` ("Configuration"=13 > 8)
+- **Valid**: `getUser` ("get"=3, "User"=4)
+- **Invalid**: `getConfiguration` ("Configuration"=13 > 8)
+
+## Prohibited Redundant Words
+
+The plugin automatically detects and prohibits the use of the following redundant words:
+
+**Class Name Prohibited Words**: manager, handler, processor, controller, service, provider, factory, builder, adapter, decorator, proxy, facade, mediator, observer, strategy, command, visitor, iterator, template, flyweight, memento, interpreter, model, view, route, router, component, widget, panel, dialog, window, form, field, property, entity
+
+**Function Name Prohibited Words**: data, result, output, input, param, params, parameter, parameters, value, values, item, items, process, processor, provider, builder, adapter, decorator, proxy, facade, mediator, observer, strategy, command, visitor, iterator, template, flyweight, memento, interpreter, temp, tmp, temporary, cached, buffered, idx, counter, with
+
+**Variable Name Prohibited Words**: object, array, map, set, collection, container, instance, data, item, items, element, elements, entry, entries, temp, tmp, temporary, cached, buffer, buffered, input, output, result, destination, index, idx, counter, length, total, sum, pointer, reference, ref, handle, handler, entity, column, property, attribute, manager, processor, controller, service, middleware, component, provider
+
+## Name Recommendation Feature
+
+The plugin includes an intelligent name recommendation system that suggests shorter alternative names while preserving semantics.
+
+### Core Principle
+
+The core principle is **"shorten names without changing semantics"**. The recommendation system:
+- Recommends shorter words while maintaining the same meaning
+- Avoids conceptual changes that would alter functionality
+- Ensures recommended words are always shorter than the original
+- Preserves programming-specific terminology and conceptual differences
+
+### Available Recommendations
+
+The plugin provides recommendations for common programming operations:
+
+| Original Word | Recommended | Description |
+| ------------- | ----------- | ----------- |
+| `calculate`   | `calc`      | Math operations |
+| `generate`    | `gen`       | Data generation |
+| `initialize`  | `init`      | Initialization operations |
+| `execute`     | `exec`      | Command execution |
+| `process`     | `run`       | Data processing |
+| `retrieve`    | `load`      | Data loading |
+| `persist`     | `save`      | Data storage |
+| `compare`     | `cmp`       | Comparison operations |
+| `duplicate`   | `copy`      | Data duplication |
+| `transfer`    | `move`      | Data transfer |
+| `convert`     | `to`        | Type conversion |
+| `verify`      | `check`     | Verification checks |
+| `construct`   | `create`    | Object creation |
+| `handle`      | `run`       | Event handling |
+
+### Examples
+
+```javascript
+// ❌ Original words (longer names)
+function calculateTotal() {}
+function generateUserData() {}
+function initializeSystem() {}
+function executeCommand() {}
+function processData() {}
+
+// ✅ Recommended words (shorter names)
+function calcTotal() {}
+function genUserData() {}
+function initSystem() {}
+function execCommand() {}
+function runData() {}
+```
+
+### Error Messages with Recommendations
+
+When the recommendation feature is enabled, ESLint will suggest alternative names:
+
+```bash
+# ESLint output example
+function calculateTotal() {}
+# ^ Suggestion: Use 'calc' instead of 'calculate' for shorter naming
+```
+
+## Development
+
+### Project Structure
+
+```
+mm_eslint/
+├── index.js          # Main plugin file
+├── config.js         # Configuration management
+├── detector.js       # Naming detector
+├── validator.js      # Validator
+├── corrector.js      # Name corrector
+├── tip.js            # Tip messages
+├── util.js           # Utility functions
+├── package.json      # npm configuration
+├── README.md         # Chinese documentation
+├── README_EN.md      # English documentation
+├── LICENSE           # License
+└── tests/            # Test files
+    ├── success/      # Correct examples
+    ├── error/        # Error examples
+    └── scence/       # Scenario tests
+```
+
+### Running Tests
+
+```bash
+# Run unit tests
+npm test
+
+# Run ESLint checks
+npm run lint
+```
+
+## License
+
+ISC License
+
+## Contributing
+
+Issues and Pull Requests are welcome to improve this plugin.
+
+## Changelog
+
+### v1.4.3
+- Optimized module structure and file organization
+- Enhanced test coverage and error handling
+- Improved documentation and examples
+
+### v1.2.0
+- Modular refactoring version, separation of responsibilities
+- Enhanced configuration management
+- Improved naming detection algorithm
+
+### v1.1.0
+- Added word length validation (max 8 characters per word)
+- Added parameter name and property name detection
+- Enhanced configuration with complete ESLint rules
+
+### v1.0.0
+- Initial version release
+- Support for class, function, variable, constant, and private member naming conventions
+- Support for length limitations and single word priority rules
+- Support for redundant word prevention