biome-validator

Biome 验证器

验证 Biome 2.3+ 配置，并防止使用过时模式。确保正确配置类型感知 lint、领域和现代 Biome 功能。

何时启用

• 为新项目设置 lint
• 开始任何代码质量相关工作前
• 审查现有 Biome 配置
• AI 生成 biome.json 后
• 验证 CI/CD 管道

快速开始

python3 ~/.claude/skills/biome-validator/scripts/validate.py --root .
python3 ~/.claude/skills/biome-validator/scripts/validate.py --root . --strict

检查内容

1. Biome 版本和 Schema

良好 - Biome 2.3+：

{
  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json"
}

不良 - 旧版 Schema：

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json"
}

2. 软件包版本

// GOOD: v2.3+
"@biomejs/biome": "^2.3.0"

// BAD: v1.x or v2.0-2.2
"@biomejs/biome": "^1.9.0"

3. Linter 配置

良好 - Biome 2.x：

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "warn"
      }
    }
  }
}

4. Biome Assist（2.0+）

良好 - 使用 assist：

{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

不良 - 旧版 organizeImports 位置：

{
  "organizeImports": {
    "enabled": true
  }
}

5. 领域（2.0+）

良好 - 使用领域配置框架专属规则：

{
  "linter": {
    "domains": {
      "react": "on",
      "next": "on"
    }
  }
}

6. 抑制注释

良好 - Biome 2.0+ 注释：

// biome-ignore lint/suspicious/noExplicitAny: legacy code
// biome-ignore-all lint/style/useConst
// biome-ignore-start lint/complexity
// biome-ignore-end

不良 - 格式错误：

// @ts-ignore  // Not Biome
// eslint-disable  // Wrong tool

Biome 2.3+ 功能

类型感知 lint

Biome 2.0+ 支持类型推断，无需 TypeScript 编译器：

{
  "linter": {
    "rules": {
      "correctness": {
        "noUndeclaredVariables": "error",
        "useAwaitThenable": "error"
      }
    }
  }
}

Assist 操作

{
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on",
        "useSortedKeys": "on"
      }
    }
  }
}

多文件分析

Lint 规则可以查询其他文件中的信息，从而进行更强大的分析。

框架领域

{
  "linter": {
    "domains": {
      "react": "on",       // React-specific rules
      "next": "on",        // Next.js rules
      "test": "on"         // Testing framework rules
    }
  }
}

推荐配置

{
  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "complexity": {
        "noForEach": "off"
      },
      "style": {
        "noNonNullAssertion": "off"
      },
      "suspicious": {
        "noArrayIndexKey": "off",
        "noExplicitAny": "warn"
      },
      "correctness": {
        "useAwaitThenable": "error",
        "noLeakedRender": "error"
      }
    },
    "domains": {
      "react": "on",
      "next": "on"
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "always"
    }
  },
  "files": {
    "ignore": [
      "node_modules",
      "dist",
      "build",
      ".next",
      "out",
      ".cache",
      ".turbo",
      "coverage"
    ]
  }
}

已弃用模式

已弃用	替代方案（2.3+）
organizeImports.enabled	assist.actions.source.organizeImports
Schema < 2.0	Schema 2.3.11+
@biomejs/biome < 2.3	@biomejs/biome@latest
未配置领域	为框架使用 linter.domains

验证输出

=== Biome 2.3+ Validation Report ===

Package Version: @biomejs/[email protected] ✓

Configuration:
  ✓ Schema version: 2.3.11
  ✓ Linter enabled with recommended rules
  ✓ Using assist.actions for imports
  ✗ No domains configured (consider enabling react, next)
  ✓ Formatter configured

Rules:
  ✓ noExplicitAny: warn
  ✓ useAwaitThenable: error
  ✗ noLeakedRender not enabled (recommended)

Summary: 2 issues found

从 ESLint 迁移

步骤 1：安装 Biome

bun remove eslint prettier eslint-config-* eslint-plugin-*
bun add -D @biomejs/biome@latest

步骤 2：创建 biome.json

bunx biome init

步骤 3：迁移规则

bunx biome migrate eslint --write

步骤 4：更新脚本

{
  "scripts": {
    "lint": "biome lint .",
    "lint:fix": "biome lint --write .",
    "format": "biome format --write .",
    "check": "biome check .",
    "check:fix": "biome check --write ."
  }
}

步骤 5：移除旧配置

rm .eslintrc* .prettierrc* .eslintignore .prettierignore

VS Code 集成

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "quickfix.biome": "explicit"
  }
}

CI/CD 集成

# .github/workflows/lint.yml
- name: Validate Biome Config
  run: |
    python3 ~/.claude/skills/biome-validator/scripts/validate.py \
      --root . \
      --strict \
      --ci

- name: Lint
  run: bunx biome check --error-on-warnings .

集成

• linter-formatter-init - 从头开始设置 Biome
• nextjs-validator - 验证 Next.js（启用 next 领域）
• bun-validator - 验证 Bun 工作区