React Doctor 贡献者指南：代码规范、测试命令与 GitHub Action 发布流程完全讲解

React Doctor 贡献者指南代码规范、测试命令与 GitHub Action 发布流程完全讲解【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctorReact Doctor 是一款专为 React 项目打造的确定性代码体检工具能够扫描状态与副作用、性能、安全、可访问性与可维护性问题并给代码打出 0–100 的健康分。本文将作为 React Doctor 贡献者指南完整讲解其代码规范、常用测试命令、Changesets 发布流程以及 GitHub Action 独立版本化与打 tag 的发布流程帮助新手贡献者快速上手。快速了解项目你将要改动的代码库React Doctor 的核心卖点是确定性扫描——同一段代码每次扫描结果一致因此它非常适合被集成到 CI 与编码 Agent 中。项目采用pnpm workspace Turbo管理的 monorepo 结构主要包如下包路径说明packages/core私有诊断引擎项目发现、Lint、评分、抑制逻辑packages/react-doctor公开的 CLI 与inspect()APIpackages/oxlint-plugin-react-doctor公开的 100 条 lint 规则实现packages/eslint-plugin-react-doctoroxlint 插件的 ESLint 镜像packages/api可编程的diagnose()入口完整目录职责说明见 AGENTS.md它是贡献者必读的包布局地图。核心编排器诊断流水线的心脏位于 run-inspect.ts。环境准备与安装命令使用git clone https://gitcode.com/GitHub_Trending/re/react-doctor克隆仓库并进入目录确认 Node.js 版本满足要求^20.19.0 || 22.13.0包管理器为pnpm 8版本约束声明在 package.json项目约定使用antfu/ni封装命令ni安装依赖、nr SCRIPT_NAME运行脚本、nun卸载详见 AGENTS.md核心代码规范动手前必须知道的 8 条铁律项目的编码风格写在 AGENTS.md 的 General Rules 一节中贡献者包括 AI 助手都必须遵守命名与组织文件名一律 kebab-case变量名要有描述性避免x、moved这类缩写优先didPositionChangeTypeScript优先使用interface而非type类型放在全局作用域尽量避免as断言函数使用箭头函数而非function声明魔法数字必须放进constants.ts用SCREAMING_SNAKE_CASE并带单位后缀如_MS、_PX工具函数小而专注的 utility 放进utils/一个文件一个工具函数注释几乎不写注释确属 hack 的代码必须加// HACK: 原因前缀去重新增工具函数前先搜索现有符号项目用truffler做模糊符号检索任务结束后再搜一遍删除被取代的旧代码Effect v4 运行时约定核心引擎基于effect4.0.0-beta.102几条硬性约定值得提前了解每个 Effect 模块单独导入import * as Effect from effect/Effect禁止伞形导入所有可失败服务统一抛出ReactDoctorErrorSchema.TaggedErrorClass叶子 联合类型Effect.gen内部严禁try/catch同步抛错要用Effect.try包裹测试层命名有固定词汇表layerNode、layerOf、layerInMemory、layerCapture、layerNoop完整约定见 AGENTS.md。测试命令一览提交前的检查清单测试框架是vite-plus/testvitest 封装测试与源码同包存放packages/core/tests/服务与编排测试、packages/react-doctor/tests/CLI 与端到端测试。提交前必须依次运行来自 AGENTS.mdpnpm test # 运行全部包的测试 pnpm lint # 代码检查 pnpm typecheck # 类型检查 pnpm format # 格式化仅校验用 pnpm format:check pnpm smoke:json-report # 校验构建产物的 JSON 报告是否符合 schema其他常用命令脚本定义在 package.json命令用途pnpm build通过 Turbo 构建所有包pnpm dev开发模式运行 CLIpnpm fuzz运行模糊测试规则鲁棒性验证pnpm check:published-deps审计发布产物未声明的运行时依赖pnpm smoke:packed-cli-install冒烟测试打包后的 CLI 安装CI 中这些检查如何执行测试矩阵覆盖 Ubuntu / Windows / macOS 与 Node 20–26Windows 与 Node 20 腿串行执行格式化检查、CLI 冒烟、JSON 报告 schema 校验只在 Ubuntu Node 22 腿跑一次详见 ci.yml。任务依赖与缓存配置在 turbo.json。发布流程Changesets 驱动的 npm 版本化npm 包发布完全由Changesets托管工作流在 publish.yml在 PR 中执行pnpm changeset添加版本变更贡献者默认只加patch级 Changesetminor/major 需维护者明确要求合并到main后publish.yml 中的changesets/action自动创建 chore: version packages 版本 PR合并后执行pnpm releaserelease脚本package.json依次执行构建 → 依赖审计 → 注入 Sentry source maps →changeset publish发布使用npm Trusted PublishingOIDC无需长期 npm token每次稳定发布后publish-dev作业还会发布一个X.Y.Z-dev.sha快照版本方便内部联调⚠️发布授权红线AGENTS.md合并任何触发发布的 PR、打 tag、推 tag 都必须获得维护者针对具体版本的明确确认——通用放行不构成发布授权。GitHub Action 独立版本化最容易被忽视的细节React Doctor 仓库根部的 action.yml 是一个 composite GitHub Action它与 npm 包版本完全独立有自己的 tag 体系npm 包 tagreact-doctorX.Y.Z无前缀Changesets 在 CI 中创建Action tag带v前缀的语义化版本vX.Y.Z 浮动主版本指针vN如v2v前缀用于与包 tag 区分哪些改动算 Action 发布改动了下列任一文件就必须打新的 Action tag。该清单定义在 recommend-action-version-bump.mjs文件职责action.yml复合 Action 主定义inputs/outputs/stepsscripts/ensure-json-report.mjs校验扫描输出的 JSON 报告scripts/normalize-changed-files.mjs归一化 PR 变更文件列表scripts/render-github-action-comment.mjs渲染 PR 汇总评论scripts/resolve-package-spec.mjs解析版本号为可缓存的安装规格版本号如何递增由 recommend-action-version-bump.mjs 按 conventional commit 分类feat(action)→minorfix/refactor/chore/docs →patchinputs/outputs 或运行时契约的破坏性变更 →major。打 tag 的完整步骤tag 为GPG 签名的附注 tagtag.gpgsigntrue必须在本地显式带消息创建# 1. 在改动 Action 的合并提交上打新 tag git tag -a v2.2.3 commit -m react-doctor action v2.2.3 # 2. 将浮动主版本指针 v2 移到同一提交 git tag -fa v2 commit -m react-doctor action v2 (floating major - v2.2.3) # 3. 推送普通推送 vX.Y.Z仅浮动主版本指针需要 force git push origin v2.2.3 git push --force origin v2另外两点最佳实践自动提醒action-version-bump.yml 工作流会检测 PR 中是否触碰 Action 发布面并在 PR 下评论推荐的版本号与打 tag 命令设置仓库变量AUTO_BUMP_ACTION_TAGtrue后合并时可自动完成引用方式文档中永远不要让消费方引用main存在供应链风险推荐完整 commit SHA # v2.2.2强 pin 或vN浮动主版本新手贡献者速查清单git clone https://gitcode.com/GitHub_Trending/re/react-doctor后用ni安装依赖通读 AGENTS.md包布局、Effect v4 约定、测试要求、发布红线写规则优先复用现有符号truffler检索一个utils/文件只放一个函数提交前跑完pnpm test pnpm lint pnpm typecheck pnpm format用pnpm changeset添加 patch 级变更说明若触碰action.yml或四个发布脚本记得走独立的vX.Y.ZvN打 tag 流程掌握以上规范与流程你就可以顺畅地为 React Doctor 提交第一个 PR 了 【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考