mindfulness/spec_kit/Text Wrap/modules/core-contract/tasks.md

core-contract（任务清单）

对应计划：spec_kit/Text Wrap/modules/core-contract/plan.md

状态含义：[ ] 未完成，[x] 已完成。
执行完本清单后，需要在 spec_kit/overview.md 的 Text Wrap 条目下补充“已完成编码/任务执行完毕”的标记（见最后一节）。

---

0. 任务标记规则

• 用勾选框标记执行状态：
  • [ ] 未完成
  • [x] 已完成
• 每个任务必须可独立验收（有明确产出与检查方式）。
• 涉及“口径”的任务，必须在代码注释中写清楚（简体中文），避免后续模块实现漂移。

---

1. 文档对齐（先把口径写死，避免实现漂移）

• 1.1 复核 core-contract/spec.md 与 core-contract/plan.md 的一致性

  • 检查点：
    • whitespacePolicy（NORMALIZE/PRESERVE）语义一致
    • EN token 规则为“极简派”（不拆标点、不生成 SPACE token）
    • EN 关键词命中为“全词等值匹配”（禁止 substring）
    • breaks 字典序比较规则清晰且无歧义
  • 验收：两份文档无冲突描述；关键字段命名一致。

• 1.2 明确 start/end 的索引口径（以 normalizedText 为基准）并写入代码注释与 README（如有）

  • 原因：跨端 span/调试定位会依赖该口径
  • 验收：任意 token 的 start/end 都可映射到同一份文本基准（normalizedText）。

---

2. 目录与代码骨架（客户端侧优先落地）

说明：当前仓库已有 client/src/features/* 结构，Text Wrap 建议也放到 features/ 下，便于后续 Home/Widget 复用。

• 2.1 新建目录 client/src/features/textWrap/core/

  • 产出（建议文件）：
    • types.ts：Token/Config/Options 类型
    • normalizeWhitespace.ts
    • tokenizeEN.ts
    • joinTokens.ts
    • enKeyword.ts（normalizeENKeyword/matchENKeyword）
    • compare.ts（breaks 字典序比较）
    • index.ts（统一导出）
  • 验收：目录存在且可被 TS 正常 import（不报路径错误）。

• 2.2 定义 Token 与基础配置类型（只含 core-contract 需要的字段）

  • 要求：
    • Token 至少包含 text/start/end
    • CoreConfig 至少包含 whitespacePolicy 与 punctuationStripSetEN
  • 验收：类型定义满足后续函数签名需要，且命名清晰。

---

3. 核心函数实现（纯函数 + 确定性）

• 3.1 实现 normalizeWhitespace(text)（默认 NORMALIZE）

  • 规则：
    • 连续空白折叠为单个空格
    • 去除首尾空白
    • 返回 hadMultiWhitespace（用于后续 meta 打点）
  • 验收：
    • 输入 " a b \n c " 输出 "a b c"
    • hadMultiWhitespace 在出现折叠/trim 时为 true

• 3.2 实现 tokenizeEN(normalizedText)（极简派）

  • 规则：
    • 以空格切分为 WORD tokens
    • 标点作为 token.text 的一部分（不拆）
    • 不生成 SPACE token
  • 验收：
    • "I am so tired" → [I, am, so, tired]
    • "tired." 为单 token

• 3.3 实现 joinTokens(tokens, start, end, separators?)

  • 规则：
    • 默认用单空格 join [start..end) 的 token.text
    • start/end 为半开区间，越界/空区间需有明确行为（建议：空区间返回空字符串，交由上层硬约束处理）
  • 验收：
    • tokens=[I, am, so, tired]，join(0,2) 为 "I am"

• 3.4 实现 EN 关键词命中：normalizeENKeyword + matchENKeyword

  • 规则：
    • lowercase
    • strip 两端常见标点（使用配置 punctuationStripSetEN，全端一致）
    • 等值比较（禁止 substring）
  • 验收：
    • keyword=but：but, 命中；rebuttal 不命中

• 3.5 实现 breaks 字典序比较 compareBreaksLexicographically(a, b)

  • 规则：
    • 从 index=0 起逐项比较，首个不同元素更小者更小
    • 公共前缀相同则更短数组更小
  • 验收：
    • [2] < [3]
    • [2] < [2, 5]
    • [2, 3] > [2]

---

4. 单元测试（Vitest，纯函数为主）

• 4.1 新建测试目录 client/src/features/textWrap/core/__tests__/

  • 验收：测试文件可被现有 test runner 发现。

• 4.2 为 normalizeWhitespace 增加用例

  • 覆盖：多空格、换行、首尾空白、空字符串、全空白字符串
  • 验收：测试断言输出字符串与 hadMultiWhitespace 符合预期。

• 4.3 为 tokenizeEN + joinTokens 增加用例

  • 覆盖：普通句子、带标点的 token、单词间多个空格（先 normalize 再 tokenize）
  • 验收：tokens 序列与 join 后文本完全一致且确定。

• 4.4 为 matchENKeyword 增加用例

  • 覆盖：大小写、两端标点、误伤样例（rebuttal vs but）
  • 验收：命中与不命中行为符合 spec。

• 4.5 为 breaks 字典序比较增加用例

  • 验收：比较规则在多组数组上输出稳定顺序。

---

5. 最终自检清单（合入前）

• 5.1 tsc --noEmit 通过（或项目既有 TS 检查命令通过）

  • 验收：无类型错误。

• 5.2 vitest 通过（或项目既有测试命令通过）

  • 验收：新增用例全部通过，不影响现有测试。

• 5.3 代码注释口径检查（简体中文）

  • 检查点：
    • EN 极简派与“断点只在词间”
    • 全词等值匹配（禁止 substring）
    • start/end 基于 normalizedText 的口径说明
  • 验收：后续模块开发者只看代码也不会产生歧义。

---

6. 文档回写（任务清单执行完毕后必须做）

• 6.1 在 spec_kit/overview.md 的 Text Wrap 条目下补充执行状态
  • 建议写法：
    • 增加一行：- **已完成编码（阶段性）**：core-contract（核心口径与契约）
  • 验收：overview 能反映该子模块已完成，便于全局追踪。