isentinel 是一套针对 roblox-ts 开发的、带有明确倾向性的工具与模式偏好集合,适用于搭建新的 roblox-ts 项目,或在出现代码风格与工具链决策时参考。
一、用途 该偏好集合用于统一 roblox-ts 项目的开发工具与代码规范,涵盖包管理、语言配置、Lint、测试、提交规范等方面。
二、主要内容(快速摘要)
- 包管理器:pnpm,bun 可作为可选运行时
- 语言:TypeScript(严格模式加额外检查)
- TypeScript 配置:@isentinel/tsconfig
- 代码检查:@isentinel/eslint-config(不使用 Prettier)
- 测试:Jest-roblox,采用 TDD 方法
- Git 钩子:husky + lint-staged
- 提交:Conventional Commits
三、包管理器 使用 pnpm 作为包管理器,脚本运行时可选使用 bun。推荐使用 @antfu/ni 统一包管理命令,它会根据 lockfile 自动检测包管理器(pnpm/npm/yarn/bun)。常用命令包括:ni(安装依赖)、ni <pkg>(添加依赖)、ni -D <pkg>(添加开发依赖)、nr <script>(运行脚本)、nu(升级依赖)、nun <pkg>(卸载依赖)、nci(干净安装)、nlx <pkg>(执行包)。
四、TypeScript 使用 @isentinel/tsconfig 的 roblox 预设,严格模式并附加以下检查:exactOptionalPropertyTypes、noUncheckedIndexedAccess、noPropertyAccessFromIndexSignature、noImplicitOverride、noImplicitReturns、noFallthroughCasesInSwitch。配置示例为在配置文件中通过 "extends": "@isentinel/tsconfig/roblox" 继承该预设。
五、代码检查 使用 @isentinel/eslint-config,不使用 Prettier,由 ESLint 负责格式化。配置方式为在 eslint.config.ts 中导入 isentinel 并导出 isentinel()。使用 nr lint --fix 修复错误。
六、错误处理 倾向于使用断言而非静默失败,即快速失败、明显报错(Fail fast, fail loud)。相关模式见 error-handling.md。
七、测试驱动开发 遵循 红 → 绿 → 重构 流程:先写一个失败的测试,再写最小代码使其通过,最后在测试保护下重构。简洁性规则按顺序为:通过所有测试、清晰表达意图、无重复、元素最少。三行相似代码优于过早的抽象。Jest-roblox 的设置见 testing.md。
八、参考资料 工具细节见 tooling.md,TypeScript 配置见 typescript.md,Lint 规则见 linting.md,测试(TDD)见 testing.md,错误处理见 error-handling.md。
九、限制 资料仅给出上述偏好与引用文件名称,未提供这些引用文件的具体内容、完整的配置代码、安装步骤、适用平台范围或性能效果数据,这些信息暂未提供。