isentinel 定义了一套面向 roblox-ts 开发的、带有明确主张的工具与模式偏好集合,主要用途是在新建 roblox-ts 项目时,或当出现代码风格与工具链选型问题时,提供可直接采纳的默认约定。它不是某个可安装运行的独立软件,而是一份偏好清单与配套配置说明。
一、主要偏好 资料以表格形式列出了核心偏好:包管理器使用 pnpm(bun 可作为可选运行时);语言使用 TypeScript(严格模式加额外检查);TypeScript 配置使用 @isentinel/tsconfig;Lint 使用 @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。配置示例为在 tsconfig 中扩展 "@isentinel/tsconfig/roblox"。
四、Linting 推荐使用 @isentinel/eslint-config,不使用 Prettier,由 ESLint 负责格式化。示例配置使用 eslint.config.ts,从 "@isentinel/eslint-config" 导入 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。这些文件的具体内容在给出的资料中暂未提供。
八、适用场景与限制 适用场景:初始化或维护 roblox-ts 项目、统一团队在包管理、TypeScript 严格度、Lint、测试流程、Git 钩子与提交规范方面的约定。限制:资料仅给出偏好与配置片段,未提供完整实现细节、版本要求、安装步骤、收费或价格信息;部分引用文件(tooling.md、typescript.md、linting.md、testing.md、error-handling.md)内容暂未提供。