Lint 与代码风格

从编辑到合流（本地 → CI）

  [ 编辑 / 生成代码 ]
        │
        ▼
  ┌─────────────┐     EditorConfig + 编辑器 format on save（可选）
  │  工作区约定   │──── 共享 extends：根 .eslintrc / ruff.toml / biome.json
  └─────────────┘
        │
        ▼
  ┌─────────────┐     format + lint --fix；失败则阻断提交或自动 stage
  │  pre-commit  │──── 与 CI 使用同一工具版本（锁文件或 npx/pipx pin）
  └─────────────┘
        │
        ▼
  ┌─────────────┐     lint（无 fix）/ typecheck / 测试；产物目录 paths-ignore
  │  CI 门禁    │──── 不重复跑已在钩子中且已提交的格式化 diff
  └─────────────┘
        │
        ▼
        [ 合并 ]

共享配置与 monorepo 扩展

根目录放「团队基线」包或 extends 指向的共享 preset；子包仅声明差异（如浏览器端 vs Node、测试目录覆盖）。Agent 改规则时同步 bump 版本号与变更说明。

• 行尾、缩进、字符集与 .editorconfig 一致，避免 formatter 与编辑器各写一套。
• 多运行时（如 JS + Python）为每栈保留单一事实来源，禁止复制粘贴整份配置到多个目录。
• 生成物目录（dist/、coverage/）在工具层与 CI paths-ignore 双层排除。

Prettier 完整配置与 EditorConfig 示例：

// .prettierrc.json — Prettier 完整配置
{
  "semi": true,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "trailingComma": "all",
  "tabWidth": 2,
  "useTabs": false,
  "printWidth": 100,
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "always",
  "endOfLine": "lf",
  "embeddedLanguageFormatting": "auto",
  "overrides": [
    {
      "files": ["*.json", "*.yaml", "*.yml"],
      "options": { "tabWidth": 2 }
    },
    {
      "files": "*.md",
      "options": { "proseWrap": "always", "printWidth": 80 }
    }
  ]
}

// .prettierignore
// dist/
// coverage/
// **/*.generated.ts
// pnpm-lock.yaml

# .editorconfig — 与 Prettier 保持一致
root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false
max_line_length = 80

[Makefile]
indent_style = tab  # Makefile 必须用 tab

格式化 vs Lint

pre-commit 与 CI 分工

• 钩子：快速、可修复、开发者本机可复现；缓存依赖加速。
• CI：全量矩阵（多 Node/Python 版本按需）、不可本地省略的检查、上传报告。
• 同一检查不要在钩子「仅 warn」而 CI「error」长期不一致；过渡期写进团队文档与截止日期。

lint-staged + Husky 完整配置：

// 1. 安装 Husky + lint-staged
// npm install -D husky lint-staged
// npx husky init

// package.json — lint-staged 配置（只 lint 改动的文件）
{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --max-warnings 0 --fix",
      "prettier --write"
    ],
    "*.{js,jsx,mjs,cjs}": [
      "eslint --max-warnings 0 --fix",
      "prettier --write"
    ],
    "*.{json,yaml,yml,md}": [
      "prettier --write"
    ],
    "*.py": [
      "ruff check --fix",
      "ruff format"
    ]
  }
}

# .husky/pre-commit — 提交前运行 lint-staged
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npx lint-staged

# .husky/pre-push — 推送前运行测试（可选，耗时则谨慎）
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npm run test:unit  # 只跑单测，不跑集成测试

// ESLint + Prettier 协作配置（解决冲突）
// 方案：eslint-config-prettier 关闭与 Prettier 冲突的 ESLint 规则
// npm install -D eslint-config-prettier
// .eslintrc.json 中 extends 末尾添加 "prettier"（必须最后）：
{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"    // 必须放最后，覆盖与 Prettier 冲突的规则
  ]
}

规则治理与升级

对争议规则（引号、尾逗号等）用 ADR 或配置旁注释记录决策；大版本升级 ESLint / Ruff 时分阶段迁移并保留迁移清单（破规 diff、禁用项、跟进 issue）。

• 合并后回顾：长期被大量 eslint-disable 的规则考虑降级或改范围。
• Agent 修改共享配置时，必须更新示例代码与 onboarding 文档中的「推荐扩展」一节。

命令与分工备忘录（lintfmt-page JS）

勾选技术栈与运行面，生成本地可复制的 package.json scripts 示意与 pre-commit / CI 分工备忘（需按仓库包管理器与目录结构调整）。