@namewta/speculo 0.3.3 → 0.3.4

package/template/skills/typescript-engineering-standards/references/02-file-directory-and-symbol-naming.md

@@ -0,0 +1,117 @@
+# 文件、目录与标识符命名
+
+## 默认命名
+
+| 对象 | 默认规则 | 示例 |
+|---|---|---|
+| 目录 | `kebab-case` | `user-auth/` |
+| 普通 TypeScript 文件 | `kebab-case.ts` | `session-expiration-policy.ts` |
+| React 业务组件 | `PascalCase.tsx` | `SessionExpiredDialog.tsx` |
+| Hook | `use-*.ts` / `use-*.tsx` | `use-session-timeout.ts` |
+| 单元测试 | 源文件名 + `.test` | `login-service.test.ts` |
+| 集成测试 | `.integration.test` | `payment-flow.integration.test.ts` |
+| E2E | `.e2e.spec` | `checkout.e2e.spec.ts` |
+| 声明文件 | 环境或能力名 | `electron-api.d.ts` |
+| 工程脚本 | 动宾结构 | `generate-icons.ts` |
+
+若仓库已统一使用 `kebab-case.tsx` 组件文件，应保持一致。不要在同一领域混用两种组件文件命名。
+
+## 文件名表达领域和职责
+
+推荐结构：
+
+```text
+<domain>-<responsibility>.ts
+```
+
+例如：
+
+- `user-session-store.ts`
+- `payment-retry-policy.ts`
+- `terminal-output-parser.ts`
+- `github-auth-client.ts`
+- `workspace-path-validator.ts`
+
+## 职责后缀
+
+- `-service`：完成一个应用能力；不得成为万能类。
+- `-repository`：领域对象的持久化抽象。
+- `-client`：调用外部 HTTP、RPC 或 SDK。
+- `-adapter`：在两个接口或模型间适配。
+- `-gateway`：外部系统或资源边界。
+- `-store`：状态存储与更新。
+- `-selector`：从状态中派生数据。
+- `-policy`：可替换的业务决策。
+- `-validator`：校验并返回结果或错误。
+- `-parser`：把外部格式转换为结构化数据。
+- `-serializer`：把结构化数据转换为外部格式。
+- `-mapper`：在两个明确模型之间映射。
+- `-factory`：构造复杂对象或依赖图。
+- `-registry`：注册和查找一组实现。
+- `-scheduler`：计划或调度任务。
+- `-coordinator`：协调多个独立流程。
+- `-contract`：跨模块、跨进程或公开 API 契约。
+
+后缀不能替代领域信息。单独的 `service.ts`、`handler.ts`、`manager.ts` 仍然模糊。
+
+## 默认禁止的模糊名称
+
+- `utils.ts`
+- `helpers.ts`
+- `common.ts`
+- `misc.ts`
+- `general.ts`
+- `data.ts`
+- `manager.ts`
+- `processor.ts`
+- `handler.ts`
+- 全局 `types.ts`
+- 全局 `constants.ts`
+
+若父目录已提供完整语义，局部 `types.ts` 或 `constants.ts` 可以存在，但更推荐 `payment-types.ts`、`terminal-constants.ts` 等可搜索名称。
+
+## 标识符
+
+| 对象 | 规则 |
+|---|---|
+| 变量、函数、方法 | `camelCase` |
+| 类型、类、组件 | `PascalCase` |
+| 常量 | 真正全局稳定值用 `SCREAMING_SNAKE_CASE` |
+| 私有字段 | 使用 `#field` 或普通 `private`，不加 `_` 前缀 |
+| Hook | `useXxx` |
+| 事件属性 | `onXxx` |
+| 内部事件处理函数 | `handleXxx` |
+| 泛型 | 简单时 `T`，复杂时 `TResult`、`TContext` |
+
+## 布尔命名
+
+优先使用：
+
+- `isConnected`
+- `hasPendingChanges`
+- `canRetry`
+- `shouldPersist`
+- `didTimeout`
+- `willReconnect`
+
+避免 `flag`、`enabled`、`notDisabled`、`isNotInvalid` 等含义弱或双重否定名称。
+
+## 单位进入名称
+
+数值变量必须尽量包含单位或语义：
+
+```ts
+const timeoutMs = 30_000
+const payloadSizeBytes = 1_024
+const retryCount = 3
+const pageOffset = 20
+```
+
+## 避免无信息变量
+
+除极短循环或数学表达式外，避免 `obj`、`data`、`info`、`value`、`result`、`temp`。使用角色名称：
+
+- `parsedPayload`
+- `validationResult`
+- `pendingSession`
+- `persistedWorkspace`

package/template/skills/typescript-engineering-standards/references/03-modules-imports-exports-and-dependencies.md

@@ -0,0 +1,111 @@
+# 模块、导入、导出与依赖
+
+## 命名导出优先
+
+默认使用命名导出：
+
+```ts
+export function parseTerminalOutput(input: string): ParsedOutput {
+  // ...
+}
+```
+
+默认导出仅用于：
+
+- 框架规定的页面、路由或配置入口。
+- 工具链必须的默认导出。
+- 仓库已形成明确且一致的入口惯例。
+
+命名导出便于搜索、自动导入、重构和统一引用名称。
+
+## 一个文件一个主要公开概念
+
+一个文件可包含少量私有辅助函数，但通常只公开一个主要能力或一组高度相关能力。辅助函数达到独立职责后，应拆成具有具体名称的文件。
+
+不要为了测试内部细节而导出私有辅助函数；优先通过公共行为测试，或将真正独立的纯逻辑抽出。
+
+## Barrel 文件
+
+允许 `index.ts`：
+
+- 作为包或领域的明确公共入口。
+- 隐藏内部实现并稳定外部 API。
+- 作为依赖装配或框架入口。
+
+禁止：
+
+- 每个目录机械创建 `index.ts`。
+- 建立全项目万能 Barrel。
+- 通过 Barrel 暴露内部实现。
+- 通过 Barrel 形成循环依赖。
+
+## 导入顺序
+
+默认顺序：
+
+1. Node.js 内置模块。
+2. 第三方依赖。
+3. 项目别名。
+4. 相对路径实现。
+5. 类型导入按照工具规则分组或合并。
+
+```ts
+import { readFile } from 'node:fs/promises'
+
+import { z } from 'zod'
+
+import { createLogger } from '@/shared/logger'
+
+import { parseConfig } from './config-parser'
+
+import type { AppConfig } from './app-config'
+```
+
+要求：
+
+- Node 内置模块使用 `node:` 前缀。
+- 仅作为类型使用时采用 `import type`。
+- 不保留未使用或重复导入。
+- 副作用导入必须有明确原因。
+- 路径别名对应稳定边界，不用于任意跨层跳转。
+
+## 依赖方向
+
+推荐：
+
+```text
+UI / Entry
+    ↓
+Application orchestration
+    ↓
+Domain
+    ↓
+Ports / contracts
+    ↑
+Infrastructure adapters
+```
+
+- 领域逻辑不直接依赖数据库、HTTP、文件系统或 UI 框架。
+- 共享模块不依赖具体领域。
+- 底层模块不反向导入界面层。
+- 跨环境调用通过显式契约和适配器。
+
+## 循环依赖
+
+循环依赖是架构问题，不应通过调整导入顺序或增加 Barrel 隐藏。解决方式：
+
+- 提取真正共享的契约。
+- 使用依赖注入反转方向。
+- 合并实际属于同一职责的模块。
+- 将端口放在需求方而非实现方。
+- 缩小公共入口。
+
+## 公共 API
+
+公开库或跨包模块应：
+
+- 明确列出允许导出的入口。
+- 避免消费者导入内部路径。
+- 不暴露框架、数据库或第三方 SDK 的内部类型，除非这是刻意的 API 设计。
+- 保持输入、输出和错误契约稳定。
+- 变更时考虑语义化版本和迁移说明。

package/template/skills/typescript-engineering-standards/references/04-typescript-type-system.md

@@ -0,0 +1,150 @@
+# TypeScript 类型系统规范
+
+## 严格模式
+
+新项目必须启用 `strict`。建议逐步启用：
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+具体选项需与编译器版本、模块系统和构建工具兼容。
+
+## 禁止传播 `any`
+
+外部或未知值使用 `unknown`，在边界收窄：
+
+```ts
+function parsePayload(input: unknown): ParsedPayload {
+  return payloadSchema.parse(input)
+}
+```
+
+`any` 只允许存在于极小的兼容层，例如第三方类型错误或遗留迁移，并必须：
+
+- 限定最小作用域。
+- 写明原因与退出条件。
+- 经过运行时验证后再向内部传递。
+- 不进入公共 API。
+
+## 外部输入必须验证
+
+以下数据默认不可信：
+
+- HTTP、RPC、WebSocket、IPC 消息。
+- CLI 参数和环境变量。
+- JSON、数据库反序列化、本地存储。
+- 第三方 SDK 返回值。
+- 浏览器消息和插件输入。
+
+类型断言不是验证：
+
+```ts
+// 错误
+const config = JSON.parse(raw) as AppConfig
+
+// 正确
+const config = appConfigSchema.parse(JSON.parse(raw))
+```
+
+## 可辨识联合
+
+使用单一判别字段表达互斥状态：
+
+```ts
+type ConnectionState =
+  | { kind: 'idle' }
+  | { kind: 'connecting'; startedAtMs: number }
+  | { kind: 'connected'; connectionId: string }
+  | { kind: 'failed'; error: Error }
+```
+
+避免多个可能互相矛盾的布尔字段。对状态分支执行穷尽检查；需要 `default` 时使用 `never` 断言。
+
+## `type` 与 `interface`
+
+默认策略可选择其一并保持一致。推荐默认使用 `type`，以下场景使用 `interface`：
+
+- 需要声明合并。
+- 公共库希望消费者扩展契约。
+- 面向对象体系明确使用 `implements`。
+- 框架生态已有强约定。
+
+不要在同一领域无理由混用。
+
+## 显式类型和推断
+
+必须显式标注：
+
+- 导出函数返回类型。
+- 跨模块公共 API。
+- 插件、回调和扩展点。
+- 递归函数。
+- 权限、金额、状态转换等高风险函数。
+
+局部明显变量和短小私有函数可依赖推断。
+
+## 类型断言
+
+优先顺序：
+
+1. 控制流收窄。
+2. 类型守卫。
+3. 运行时 Schema 验证。
+4. `satisfies`。
+5. 最后才使用 `as`。
+
+禁止无理由双重断言：
+
+```ts
+value as unknown as UserSession
+```
+
+`@ts-ignore` 默认禁止。必须压制已知编译错误时，优先使用带原因的 `@ts-expect-error`，使错误消失后检查能够失败。
+
+## 空值语义
+
+明确区分：
+
+- `property?: T`：属性可能不存在。
+- `property: T | null`：属性存在，但值可以为空。
+- `T | undefined`：查找可能没有结果。
+- `Result<T, E>` 或异常：操作可能失败。
+
+除非外部协议明确区分，不要写 `property?: T | null | undefined`。
+
+## `.d.ts`
+
+`.d.ts` 仅用于：
+
+- 运行时已有但 TypeScript 不可见的全局声明。
+- 无类型第三方模块声明。
+- 框架或库声明扩展。
+- 发布库生成的公共声明。
+
+普通业务类型放在 `.ts` 中，通过正常模块导入。
+
+## 枚举
+
+默认优先字符串联合或 `as const` 对象。`enum` 主要用于外部协议、位标记、既有 API 或团队明确统一的运行时枚举需求。
+
+## 不可变性
+
+- 输入参数尽量使用只读结构。
+- 对外返回 `ReadonlyArray<T>` 或只读对象。
+- 不修改调用方传入对象。
+- 需要排序或变更时先复制。
+- 常量对象使用 `as const` 或 `satisfies`。

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

@@ -0,0 +1,142 @@
+# 函数、异步、错误与资源生命周期
+
+## 函数职责
+
+函数应只处理一个可命名职责和一个抽象层级。软性目标：
+
+- 普通函数尽量不超过约 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

@@ -0,0 +1,104 @@
+# 注释、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

@@ -0,0 +1,84 @@
+# 测试策略
+
+## 测试分层
+
+| 类型 | 目标 | 默认位置 |
+|---|---|---|
+| 单元测试 | 函数、策略、解析器、状态转换 | 与源码同目录 |
+| 集成测试 | 多个真实模块协作 | `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 方便而跳过关键集成测试。
+- 使用小而可读的夹具。
+
+## 快照
+
+快照适合结构稳定、人工审查有价值的输出。避免巨型快照、频繁无脑更新和对动态数据的快照。
+
+## 测试代码质量
+
+测试也是生产资产：
+
+- 命名清晰。
+- 无隐藏共享状态。
+- 失败信息可诊断。
+- 夹具具有领域含义。
+- 清理临时资源。
+- 不复制大量生产实现来计算期望值。