decodie-verify

Decodie — 验证模式

确认 .decodie/index.json 中的每条学习条目仍与其引用的源代码匹配，将不匹配的条目标记为过时，并为已确认的条目记录当前提交 SHA。

此模式仅修改 .decodie/index.json。它不会修改会话文件、源代码或 .decodie/ 目录之外的任何内容。

激活

解析可选的路径参数：

• 如果未提供路径，则验证所有条目。
• 如果提供了路径，则仅验证其 sources（或 references[].file）与该路径重叠的条目。对于目录，只要条目的任一源文件以该目录开头，该条目就属于范围内。
• 如果路径不存在，则报告错误并停止。

设置

1. 确认 .decodie/ 存在。如果不存在："未找到 .decodie/ 目录——无需验证。"停止。
2. 读取 .decodie/index.json。如果为空："没有要验证的条目。"停止。
3. 确定当前提交 SHA：

   git rev-parse HEAD
   

   如果当前目录不是 git 仓库，则发出警告并继续（仍会检查锚点，但无法设置 verified_sha）。

验证流程

对于范围内的每个条目：

1. 解析源文件。 优先使用 sources；否则使用去重后的 references[].file 值。如果使用后备值，回填 sources 字段。

2. 检查每个引用 { file, anchor, anchor_hash }：

   • 文件不存在 → 引用验证失败。
   • 文件存在 → 搜索字面字符串 anchor。如果找到，则重新计算 SHA-256 哈希，并确认前 8 个十六进制字符与 anchor_hash 匹配。

3. 判定结果：

   • 所有引用均解析成功 → stale: false，verified_sha = HEAD SHA。
   • 任一引用验证失败 → stale: true，保持 verified_sha 不变。

4. 写回 index.json。保留所有其他字段和排序顺序。

报告

Decodie verify
  Verified:  N entries (verified_sha -> <short-sha>)
  Stale:     M entries
  Skipped:   K entries (out of scope)
  Backfilled sources on: B entries

如果存在过时条目，则列出这些条目：

Stale entries:
  - entry-1711540000-a1b2 -- references/0: src/lib/foo.ts (anchor not found)
  - entry-1711540123-c3d4 -- references/1: src/lib/bar.ts (file missing)

重要说明

• 条目内容仅允许追加。 仅可更新 sources、verified_sha 和 stale。
• 幂等。 在没有变更的情况下运行两次，不会产生任何变化。
• 路径仅用于筛选。 范围外的条目会被跳过，不会清除。
• 不重写 git 历史。 仅通过 git rev-parse 读取 HEAD。