@namewta/speculo 0.3.4 → 0.5.0

package/template/skills/typescript-engineering-standards/references/05-functions-async-errors-and-resources.md

@@ -1,142 +0,0 @@
-# 函数、异步、错误与资源生命周期
-
-## 函数职责
-
-函数应只处理一个可命名职责和一个抽象层级。软性目标：
-
-- 普通函数尽量不超过约 40 行。
-- 编排函数尽量不超过约 60 行。
-- 嵌套通常不超过三层。
-- 参数超过三个时考虑参数对象。
-
-这些数字用于触发审查，不是机械拆分标准。
-
-## 提前返回
-
-使用 Guard Clause 减少嵌套：
-
-```ts
-function processSession(session: Session | undefined): Result {
-  if (!session) {
-    return emptyResult
-  }
-
-  if (!session.isActive || !session.userId) {
-    return emptyResult
-  }
-
-  return createResult(session)
-}
-```
-
-## 参数对象
-
-长参数列表或布尔参数应改为具名选项：
-
-```ts
-type CreateSessionOptions = {
-  userId: string
-  timeoutMs: number
-  persistence: 'memory' | 'disk'
-  logger: Logger
-}
-```
-
-避免 `createSession(id, true, false)`。
-
-## 纯逻辑和副作用分离
-
-建议分离：
-
-- 解析。
-- 验证。
-- 领域决策。
-- 数据持久化。
-- 流程编排。
-
-纯逻辑不读取隐藏全局状态、不修改输入、不直接访问网络、磁盘、时钟或随机源。将这些依赖作为参数或端口注入。
-
-## Promise 必须有归宿
-
-所有 Promise 必须被 `await`、`return`、显式收集，或用 `void` 明确表示有意脱离当前流程，并自行处理错误：
-
-```ts
-void refreshCache().catch((error: unknown) => {
-  logger.error('Failed to refresh cache', { error })
-})
-```
-
-## 并发
-
-只有相互独立的任务才使用 `Promise.all`。有顺序、共享副作用、速率限制或资源约束时，使用顺序执行、队列或并发限制器。
-
-不要无界并发处理大型输入集合。
-
-## 取消与超时
-
-网络、子进程、文件监听、Worker 和长任务应考虑：
-
-- `AbortSignal`。
-- 明确超时。
-- 清理路径。
-- 可识别的取消错误。
-- 超时后底层资源是否真正停止。
-
-## 重试
-
-重试策略必须定义：
-
-- 最大次数。
-- 退避和抖动。
-- 可重试错误范围。
-- 幂等性。
-- 最终失败的记录与反馈。
-
-不能对所有错误无限重试。
-
-## 错误处理
-
-不得吞掉异常。允许忽略时必须说明这是最佳努力操作，并保留必要诊断信息。
-
-错误应包含上下文并保留 `cause`：
-
-```ts
-throw new Error(`Failed to load workspace config: ${configPath}`, {
-  cause: error
-})
-```
-
-需要调用方分支处理的错误使用：
-
-- 具名错误类。
-- 带 `code` 的结构化错误。
-- `Result<T, E>`。
-- 可辨识联合。
-
-不要通过匹配错误消息字符串控制流程。
-
-## `catch` 值
-
-将 `catch` 值视为 `unknown`，先通过 `instanceof`、错误守卫或标准化函数收窄。
-
-## 资源清理
-
-以下资源必须有明确生命周期：
-
-- 事件监听器。
-- Timer 和 Interval。
-- 文件句柄。
-- Socket、数据库连接。
-- Worker 和子进程。
-- `AbortController`。
-- React Effect 订阅。
-
-推荐返回清理函数或实现统一 `dispose()`：
-
-```ts
-type Disposable = {
-  dispose(): void
-}
-```
-
-创建资源的模块通常也应负责定义或暴露其清理方式。

package/template/skills/typescript-engineering-standards/references/06-comments-jsdoc-and-documentation.md

@@ -1,104 +0,0 @@
-# 注释、JSDoc 与文档
-
-## 注释解释原因
-
-注释用于解释代码本身无法清楚表达的：
-
-- 为什么必须采用此顺序。
-- 为什么不能删除看似多余的逻辑。
-- 平台、协议、性能或安全约束。
-- 第三方缺陷和规避方案。
-- 竞态条件和资源生命周期。
-- 非直观产品规则。
-
-不应逐行翻译代码。
-
-```ts
-// 不推荐：Increment retry count.
-retryCount += 1
-
-// 推荐：Provider replication can briefly return 409 after a successful write.
-retryCount += 1
-```
-
-## 注释风格
-
-- 优先一行或一个短段落。
-- 靠近被解释的逻辑。
-- 使用完整、可验证的原因。
-- 修改实现时同步更新。
-- 能用命名和拆分表达时，不靠注释补救。
-
-## 应写注释的场景
-
-- 跨平台差异。
-- 第三方类型或运行时缺陷。
-- 兼容旧协议的临时分支。
-- 性能关键路径的非直观优化。
-- 安全检查顺序。
-- 并发和竞态约束。
-- 清理顺序。
-- 特殊算法或领域公式。
-
-## 不应写的注释
-
-- 复述变量名或控制流。
-- 注释掉的旧代码。
-- 无跟踪信息的“以后优化”。
-- 与实现重复的大篇教程。
-- 无法验证的猜测。
-
-历史实现由版本控制保存，不应长期留在源码中。
-
-## JSDoc 使用范围
-
-JSDoc 主要用于：
-
-- 公共库 API。
-- 插件和扩展点。
-- 跨团队或跨进程契约。
-- 参数具有单位、边界或特殊格式。
-- 函数有重要副作用、取消、异常或线程安全语义。
-
-```ts
-/**
- * Resolves a workspace path without following symbolic links.
- *
- * @throws {WorkspacePathError} When the path escapes the configured root.
- */
-export function resolveWorkspacePath(
-  rootPath: string,
-  candidatePath: string
-): string {
-  // ...
-}
-```
-
-内部显而易见的函数不需要机械补全 JSDoc。
-
-## TODO
-
-TODO 必须包含负责人约定或可追踪编号，并说明删除条件：
-
-```ts
-// TODO(PROJ-1423): Remove after all clients send protocol v3.
-```
-
-禁止：
-
-```ts
-// TODO: fix later
-```
-
-## 设计文档
-
-以下内容更适合放入 `docs/` 或 ADR，而非源码注释：
-
-- 多方案权衡。
-- 跨服务架构。
-- 数据迁移计划。
-- 兼容性策略。
-- 长期安全模型。
-- 复杂协议说明。
-
-源码注释可以引用相应 ADR 或问题编号，但应保留理解当前代码所需的最小上下文。

package/template/skills/typescript-engineering-standards/references/07-testing-strategy.md

@@ -1,84 +0,0 @@
-# 测试策略
-
-## 测试分层
-
-| 类型 | 目标 | 默认位置 |
-|---|---|---|
-| 单元测试 | 函数、策略、解析器、状态转换 | 与源码同目录 |
-| 集成测试 | 多个真实模块协作 | `tests/integration/` |
-| 契约测试 | API、IPC、插件、适配器契约 | 源码旁或 `tests/contracts/` |
-| E2E | 用户关键路径 | `tests/e2e/` |
-| 基准测试 | 性能关键路径 | `*.bench.ts` |
-
-## 测试命名
-
-测试名描述可观察行为，而不是实现方法：
-
-```ts
-describe('quoteShellArgument', () => {
-  it('preserves an empty argument as an explicit empty string', () => {
-    // ...
-  })
-})
-```
-
-避免 `it('works')`、`describe('utils')`。
-
-## 覆盖范围
-
-关键模块应考虑：
-
-- 正常路径。
-- 边界值和空输入。
-- 无效输入。
-- 错误传播。
-- 取消和超时。
-- 并发或重复调用。
-- 资源清理。
-- 已修复缺陷的回归场景。
-
-覆盖率数字不能替代风险导向的场景设计。
-
-## 缺陷修复流程
-
-1. 添加可稳定复现问题的失败测试。
-2. 确认测试在修复前失败。
-3. 实施最小修复。
-4. 确认回归测试和相关测试通过。
-5. 必要时增加跨平台或集成测试。
-
-## 确定性
-
-测试不应依赖：
-
-- 真实当前时间。
-- 外部不稳定网络。
-- 测试执行顺序。
-- 共享可变全局状态。
-- 本机特定路径或环境配置。
-- 无种子的随机数据。
-
-通过注入时钟、随机源、文件系统和网络端口，或使用临时目录与隔离夹具保持确定性。
-
-## Mock 原则
-
-- 优先测试真实纯函数。
-- Mock 系统边界，不 Mock 被测模块内部每个调用。
-- 测试行为与输出，不锁死实现步骤。
-- 不因 Mock 方便而跳过关键集成测试。
-- 使用小而可读的夹具。
-
-## 快照
-
-快照适合结构稳定、人工审查有价值的输出。避免巨型快照、频繁无脑更新和对动态数据的快照。
-
-## 测试代码质量
-
-测试也是生产资产：
-
-- 命名清晰。
-- 无隐藏共享状态。
-- 失败信息可诊断。
-- 夹具具有领域含义。
-- 清理临时资源。
-- 不复制大量生产实现来计算期望值。

package/template/skills/typescript-engineering-standards/references/08-react-and-frontend.md

@@ -1,91 +0,0 @@
-# React 与前端规范
-
-## 组件职责
-
-组件输入由 Props 明确表达，渲染尽量纯粹。复杂功能按需拆分：
-
-- 数据获取与缓存。
-- 业务状态编排。
-- 领域交互。
-- 视觉展示。
-
-组件名称使用具体领域语义：
-
-- `WorkspaceReconnectDialog`
-- `TerminalPermissionBanner`
-- `PaymentMethodPanel`
-
-避免 `DataComponent`、`CommonModal`、`GenericPanel`。
-
-## Props
-
-```ts
-type WorkspaceCardProps = {
-  workspace: WorkspaceSummary
-  isSelected: boolean
-  onSelect(workspaceId: string): void
-}
-```
-
-要求：
-
-- 使用 `XxxProps`。
-- 布尔 Props 使用 `is`、`has`、`can`、`should`。
-- 事件 Props 使用 `onXxx`。
-- 避免大型万能对象和多个隐式控制模式的布尔值。
-- 复杂互斥状态使用联合类型。
-- 是否使用 `React.FC` 按仓库统一规则，不混用。
-
-## Hook
-
-- 自定义 Hook 以 `use` 开头。
-- 一个 Hook 处理一个可命名职责。
-- Effect 依赖完整，不通过关闭规则规避。
-- Effect 创建资源时返回清理函数。
-- 返回多个独立值时优先具名对象；稳定二元关系可用元组。
-- 避免把普通纯函数包装成 Hook。
-
-## 状态管理
-
-- 状态尽量靠近使用位置。
-- 只有多个远距离调用方共享时才提升。
-- Store 按领域切片，不创建单一巨型 Store。
-- Selector 尽量窄，避免组件订阅整个状态树。
-- 派生数据优先计算，不重复存储。
-- 服务端状态与本地 UI 状态分开管理。
-
-## Effect
-
-Effect 用于与外部系统同步，不用于替代普通计算。检查：
-
-- 是否可在渲染时直接派生。
-- 是否需要取消旧请求。
-- 是否存在竞态和过期响应。
-- 是否清理监听器、Timer 和订阅。
-- 是否因对象引用变化导致无意义重复执行。
-
-## 性能
-
-- 不因为“可能更快”滥用 `memo`、`useMemo`、`useCallback`。
-- 优化针对已识别瓶颈。
-- 长列表使用虚拟化。
-- 高频事件使用调度、批处理、节流或防抖。
-- 避免在热渲染路径创建昂贵对象。
-- 关键优化应有测试、测量或简短原因说明。
-
-## 可访问性
-
-- 优先语义化 HTML。
-- 交互元素支持键盘。
-- 图标按钮有可访问名称。
-- 表单控件有 Label 和错误关联。
-- 焦点管理可预测。
-- 不用颜色作为唯一状态表达。
-- 弹窗、菜单和提示遵守相应 ARIA 交互模式。
-
-## 浏览器边界
-
-- 验证 URL、消息、Storage 和第三方脚本输入。
-- 避免不安全原始 HTML。
-- 不把秘密放入前端 Bundle。
-- 浏览器代码不导入 Node 专属模块，除非平台明确提供安全桥接。

package/template/skills/typescript-engineering-standards/references/09-node-cli-and-cross-platform.md

@@ -1,92 +0,0 @@
-# Node.js、CLI 与跨平台规范
-
-## Node 内置模块
-
-使用 `node:` 前缀：
-
-```ts
-import { readFile } from 'node:fs/promises'
-import path from 'node:path'
-```
-
-## 路径
-
-使用 `node:path` 组合和归一化路径，不手工拼接分隔符：
-
-```ts
-const configPath = path.join(rootPath, 'config', 'app.json')
-```
-
-涉及安全或相等判断时考虑：
-
-- Windows 盘符和分隔符。
-- UNC 路径。
-- 大小写敏感差异。
-- 符号链接。
-- 相对路径和路径遍历。
-- 规范化前后的边界检查顺序。
-
-## CLI 分层
-
-推荐拆分：
-
-- `parse-cli-arguments.ts`
-- `validate-cli-options.ts`
-- `run-export-command.ts`
-- `render-cli-error.ts`
-
-要求：
-
-- 参数解析与业务执行分离。
-- 正常机器输出写 `stdout`，错误写 `stderr`。
-- 明确定义退出码。
-- 支持 `--help` 和 `--version`。
-- 底层领域代码不直接调用 `process.exit()`。
-- 信号处理和资源清理集中管理。
-
-## 环境变量
-
-在启动边界一次解析、验证和标准化：
-
-```ts
-type AppEnvironment = {
-  port: number
-  logLevel: LogLevel
-}
-
-export function loadEnvironment(
-  source: NodeJS.ProcessEnv
-): AppEnvironment {
-  // ...
-}
-```
-
-业务代码不应在各处直接读取 `process.env`。
-
-## 子进程
-
-- 优先使用参数数组，不拼接 Shell 字符串。
-- 必须拼接时按目标 Shell 正确转义。
-- 处理超时、取消、退出码、信号和输出上限。
-- 避免将不可信输入直接作为命令或参数。
-- 明确清理孤儿进程。
-
-## 文件和流
-
-- 大文件优先流式处理。
-- 关闭文件句柄和流。
-- 处理背压。
-- 临时文件使用隔离目录并在失败路径清理。
-- 写关键文件时考虑原子替换和崩溃恢复。
-
-## 跨平台
-
-跨平台逻辑应集中在适配器中。测试至少覆盖：
-
-- 路径和换行符。
-- Shell 参数引用。
-- 文件权限和可执行位。
-- 信号差异。
-- 大小写和文件锁行为。
-
-不要把平台判断散落在整个业务代码中。

package/template/skills/typescript-engineering-standards/references/10-formatting-lint-and-complexity.md

@@ -1,107 +0,0 @@
-# 格式化、Lint 与复杂度
-
-## 工具统一风格
-
-格式由 Prettier、Oxfmt、Biome 或仓库选定工具自动完成。代码评审不讨论工具已能确定的空格、换行和引号偏好。
-
-常见基线：
-
-```json
-{
-  "singleQuote": true,
-  "semi": false,
-  "printWidth": 100,
-  "trailingComma": "none"
-}
-```
-
-具体值可不同，但必须全项目一致并在 CI 检查。
-
-## 通用格式规则
-
-- 2 空格缩进，除非仓库明确不同。
-- 文件使用 LF 和末尾换行。
-- 控制结构始终使用花括号。
-- 不手工用空格对齐列。
-- 避免将功能修改与全仓库格式化混在同一变更。
-- 生成文件由生成器维护，不人工格式化修改。
-
-## Lint 覆盖
-
-### 正确性
-
-- 未使用变量和导入。
-- 浮动 Promise。
-- 不可达代码、重复分支。
-- React Hooks 规则。
-- 意外赋值或错误比较。
-- 无效正则和转义。
-
-### TypeScript
-
-- 显式 `any`。
-- 类型导入一致性。
-- 无意义断言。
-- Switch 穷尽检查。
-- `@ts-ignore`。
-- 不安全成员访问和调用；在性能允许时启用类型感知规则。
-
-### 架构与维护
-
-- 循环依赖。
-- 禁止跨层导入。
-- 文件大小。
-- 函数复杂度和嵌套。
-- 重复导入。
-- 无意义 Barrel。
-
-## 禁用规则
-
-禁用必须：
-
-- 精确到单行或最小块。
-- 指明规则名。
-- 说明无法通过设计消除的原因。
-- 有退出条件时附跟踪编号。
-
-```ts
-// eslint-disable-next-line no-await-in-loop -- Server requires ordered writes.
-await sendBatch(batch)
-```
-
-禁止文件级关闭核心类型安全、Hooks 或 Promise 规则来掩盖问题。
-
-## 文件大小预算
-
-建议触发审查的阈值：
-
-| 文件 | 软上限 |
-|---|---:|
-| 普通 `.ts` | 300 行 |
-| React `.tsx` | 400 行 |
-| 测试 | 600～800 行 |
-| 构建/生成脚本 | 600 行 |
-| 函数 | 40～60 行 |
-
-行数不是唯一指标。还应考虑：
-
-- 分支和圈复杂度。
-- 依赖数量。
-- 状态数量。
-- 修改频率。
-- 是否混合多个抽象层级。
-
-## 拆分方向
-
-- 解析与验证。
-- 领域规则与 I/O。
-- 状态定义与 Selector。
-- UI 容器与展示组件。
-- 平台无关逻辑与平台适配器。
-- 公共契约与内部实现。
-
-拆分后文件名必须具体，不得产生新的 `helpers.ts`。
-
-## 遗留文件
-
-对历史超限文件采用 Ratchet：不要求一次全部重写，但新修改不应继续扩大；每次触及时降低复杂度或提取一项明确职责。

package/template/skills/typescript-engineering-standards/references/11-configuration-dependencies-and-ci.md

@@ -1,86 +0,0 @@
-# 配置、依赖与 CI
-
-## TypeScript 配置
-
-- 不同运行环境使用独立配置或项目引用。
-- 共享基线放在 `tsconfig.base.json`。
-- 根配置只负责组合时可使用 `files: []` 和 `references`。
-- 浏览器和 Node 的 `lib`、`types`、模块解析应隔离。
-- 不通过放宽配置掩盖单个文件问题。
-
-## `package.json` 脚本
-
-提供稳定命令名，使开发者和 CI 不依赖具体工具：
-
-```json
-{
-  "scripts": {
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "tsc -b",
-    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
-  }
-}
-```
-
-实际工具可以替换，但脚本职责保持稳定。
-
-## 依赖分类
-
-- 运行时需要的包放 `dependencies`。
-- 构建、测试、类型和格式工具放 `devDependencies`。
-- 锁文件必须提交。
-- `packageManager` 固定包管理器及版本。
-- 新依赖评估维护状态、体积、许可证、安全和平台兼容性。
-- 不为一个简单函数引入大型依赖。
-- 同一能力避免并存多个库。
-
-## 配置边界
-
-配置在入口处解析并转换为只读、类型安全对象。区分：
-
-- 构建时配置。
-- 启动时环境配置。
-- 用户配置。
-- 动态远端配置。
-
-业务代码通过依赖或上下文接收配置，不到处读取全局变量。
-
-## CI 门禁
-
-推荐顺序：
-
-```text
-install
-  → format:check
-  → lint
-  → typecheck
-  → unit tests
-  → build
-  → integration/e2e
-```
-
-按项目增加：
-
-- 依赖边界检查。
-- 文件大小和复杂度检查。
-- 安全扫描。
-- 许可证检查。
-- 本地化键检查。
-- 包体积或性能预算。
-
-## 本地钩子
-
-提交前钩子可仅处理暂存文件，保证快速反馈；完整类型检查、测试和构建必须由 CI 执行。
-
-## 禁止的“通过”方式
-
-- 删除或长期跳过失败测试。
-- 关闭核心 Lint 规则。
-- 扩大 `any` 或强制断言。
-- 放宽 TypeScript 配置而无迁移计划。
-- 降低测试范围以隐藏回归。
-- 忽略构建警告或生成失败。