Synthia Lint Plugin

Synthia Lint Plugin 是 Synthia Engine 的代码质量检查插件，提供统一的代码质量检查和格式化功能。支持 ESLint、Prettier、Stylelint 和 TSLint 等多种工具。

✨ 特性

• 🔍 多工具支持: 支持 ESLint、Prettier、Stylelint、TSLint
• 🔧 自动修复: 自动修复可修复的代码问题
• ✨ 代码格式化: 统一的代码格式化功能
• 📊 质量报告: 生成详细的代码质量报告
• 🚀 缓存加速: 使用缓存加速检查过程
• 🎯 精确配置: 灵活的配置选项支持
• 📁 文件过滤: 支持文件模式和忽略规则

📦 安装

# 使用 pnpm
pnpm add -D synthia-lint

# 使用 npm
npm install -D synthia-lint

# 使用 yarn
yarn add -D synthia-lint

🚀 快速开始

1. 在 Synthia 配置中启用插件

// synthia.config.ts
import { defineConfig } from 'synthia-cli';
import { lintPlugin } from 'synthia-lint';

export default defineConfig({
  plugins: [
    {
      name: 'lint',
      plugin: lintPlugin({
        eslint: { enabled: true },
        prettier: { enabled: true },
        stylelint: { enabled: false },
      }),
    },
  ],
});

2. 运行代码检查

# 检查代码质量
synthia lint

# 自动修复问题
synthia lint --fix

# 格式化代码
synthia lint --format

# 生成质量报告
synthia lint --report

📋 命令选项

| 选项 | 类型 | 描述 | 默认值 | | ----------- | ------- | ------------------------------------------ | ------------------------------------------------ | | --fix | boolean | 自动修复可修复的问题 | false | | --format | boolean | 格式化代码 | false | | --strict | boolean | 严格模式检查 | false | | --cache | boolean | 使用缓存加速检查 | false | | --tool | string | 指定检查工具 (eslint|prettier|stylelint) | auto | | --pattern | string | 文件匹配模式 | **/*.{js,jsx,ts,tsx,vue,css,scss,html,json,md} | | --ignore | string | 忽略文件模式 | node_modules/** | | --report | boolean | 生成代码质量报告 | false |

⚙️ 配置选项

LintPluginOptions

interface LintPluginOptions {
  enabled?: boolean; // 是否启用插件
  fix?: boolean; // 默认自动修复
  format?: boolean; // 默认格式化
  strict?: boolean; // 默认严格模式
  cache?: boolean; // 默认使用缓存
  tool?: 'eslint' | 'prettier' | 'stylelint' | 'tslint'; // 指定工具
  pattern?: string; // 文件匹配模式
  ignore?: string[]; // 忽略文件模式

  // ESLint 配置
  eslint?: {
    enabled?: boolean;
    config?: string;
    extensions?: string[];
    ignore?: string[];
  };

  // Prettier 配置
  prettier?: {
    enabled?: boolean;
    config?: string;
    extensions?: string[];
    ignore?: string[];
  };

  // Stylelint 配置
  stylelint?: {
    enabled?: boolean;
    config?: string;
    extensions?: string[];
    ignore?: string[];
  };

  // TSLint 配置
  tslint?: {
    enabled?: boolean;
    config?: string;
    extensions?: string[];
    ignore?: string[];
  };
}

🛠️ 支持的工具

ESLint

# 安装 ESLint
pnpm add -D eslint

# 运行 ESLint 检查
synthia lint --tool eslint

# 自动修复 ESLint 问题
synthia lint --tool eslint --fix

配置文件示例:

// .eslintrc.js
module.exports = {
  extends: ['@typescript-eslint/recommended'],
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  rules: {
    'no-console': 'warn',
    'prefer-const': 'error',
  },
};

Prettier

# 安装 Prettier
pnpm add -D prettier

# 运行 Prettier 检查
synthia lint --tool prettier

# 格式化代码
synthia lint --tool prettier --format

配置文件示例:

// .prettierrc
{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2
}

Stylelint

# 安装 Stylelint
pnpm add -D stylelint stylelint-config-standard

# 运行 Stylelint 检查
synthia lint --tool stylelint

# 自动修复 Stylelint 问题
synthia lint --tool stylelint --fix

配置文件示例:

// .stylelintrc.js
module.exports = {
  extends: ['stylelint-config-standard'],
  rules: {
    'color-no-invalid-hex': true,
    'font-family-no-duplicate-names': true,
  },
};

TSLint (已废弃，建议使用 ESLint)

# 安装 TSLint
pnpm add -D tslint

# 运行 TSLint 检查
synthia lint --tool tslint

🔧 高级用法

自定义文件模式

# 只检查特定文件
synthia lint --pattern "src/**/*.{ts,tsx}"

# 检查多个模式
synthia lint --pattern "src/**/*.ts" --pattern "tests/**/*.js"

忽略文件

# 忽略特定文件
synthia lint --ignore "dist/**" --ignore "build/**"

# 忽略多个模式
synthia lint --ignore "node_modules/**" --ignore "*.min.js"

严格模式

# 启用严格模式检查
synthia lint --strict

# 结合其他选项
synthia lint --strict --fix --cache

缓存优化

# 使用缓存加速检查
synthia lint --cache

# 清除缓存后检查
synthia lint --cache --strict

📊 质量报告

生成报告

# 生成代码质量报告
synthia lint --report

# 生成详细报告
synthia lint --report --strict

报告内容

报告包含以下信息：

• 📈 代码质量评分
• 🔍 问题统计和分类
• 📁 文件级别的检查结果
• 🎯 修复建议
• 📊 趋势分析

🎯 最佳实践

1. 配置文件管理

// synthia.config.ts
export default defineConfig({
  plugins: [
    {
      name: 'lint',
      plugin: lintPlugin({
        eslint: {
          enabled: true,
          config: '.eslintrc.js',
          extensions: ['.js', '.jsx', '.ts', '.tsx'],
        },
        prettier: {
          enabled: true,
          config: '.prettierrc',
          extensions: ['.js', '.jsx', '.ts', '.tsx', '.json', '.md'],
        },
        stylelint: {
          enabled: true,
          config: '.stylelintrc.js',
          extensions: ['.css', '.scss', '.vue'],
        },
      }),
    },
  ],
});

2. Git Hooks 集成

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "synthia lint --fix",
      "pre-push": "synthia lint --strict"
    }
  }
}

3. CI/CD 集成

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: pnpm install
      - run: synthia lint --strict --report

📁 项目结构

your-project/
├── src/
│   ├── components/
│   │   ├── Button.tsx
│   │   └── Button.test.tsx
│   ├── styles/
│   │   ├── main.css
│   │   └── components.scss
│   └── utils/
│       └── helpers.ts
├── .eslintrc.js          # ESLint 配置
├── .prettierrc           # Prettier 配置
├── .stylelintrc.js       # Stylelint 配置
├── .gitignore
└── synthia.config.ts     # Synthia 配置

🐛 故障排除

常见问题

Q: 工具未检测到

# 确保已安装相应工具
pnpm add -D eslint prettier

# 手动指定工具
synthia lint --tool eslint

Q: 配置文件未找到

# 检查配置文件是否存在
ls -la .eslintrc.js .prettierrc

# 指定配置文件路径
synthia lint --tool eslint --config custom-eslint.config.js

Q: 修复后仍有问题

# 使用严格模式检查
synthia lint --strict --fix

# 检查忽略规则
synthia lint --ignore "node_modules/**"

调试模式

# 启用详细日志
synthia lint --verbose

# 查看检测到的工具
synthia lint --tool auto

🔧 自定义规则

ESLint 自定义规则

// .eslintrc.js
module.exports = {
  rules: {
    // 自定义规则
    'custom/no-console': 'error',
    'custom/prefer-arrow-functions': 'warn',
  },
  plugins: ['custom'],
};

Prettier 自定义配置

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 4,
  "trailingComma": "all",
  "printWidth": 100
}

🤝 贡献

欢迎贡献代码！请查看 贡献指南 了解详细信息。

开发环境设置

# 克隆仓库
git clone https://github.com/your-org/synthia-engine.git

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 构建插件
pnpm build

📄 许可证

MIT License - 查看 LICENSE 文件了解详细信息。

🔗 相关链接

• Synthia Engine 主页
• 插件开发指南
• API 文档
• 更新日志

📞 支持

如果您遇到问题或有任何疑问，请：

1. 查看 FAQ
2. 搜索 Issues
3. 创建新的 Issue
4. 加入我们的 Discord 社区