decodie-flag-stale

Decodie — 标记过期模式

verify 模式的快速、适用于 CI 的替代方案。对于每个包含 verified_sha 的条目，检查其源文件自该 SHA 以来是否有更改，并将有更改的条目标记为 stale: true。不会读取源文件或重新计算锚点哈希——只会将文件名与 git 历史进行差异比较。

此模式仅修改 .decodie/index.json。

激活

不接受任何参数。始终针对完整索引运行。

设置

1. 确认 .decodie/ 存在。如果不存在：显示“未找到 .decodie/ 目录——无需检查。”然后停止。
2. 确认这是 git 仓库：

   git rev-parse --git-dir
   

   如果不是：显示“这不是 git 仓库——flag-stale 需要 git 历史。请改为运行 verify 模式。”然后停止。
3. 读取 .decodie/index.json。如果为空：显示“没有需要检查的条目。”然后停止。

检测流程

对每个条目：

1. **跳过没有 verified_sha 的条目。**将其报告为 unverified。
2. 跳过没有 sources 的条目（且没有 references[].file 可作为备用）。将其报告为 no-sources。
3. 计算已更改的文件：

   git diff --name-only <verified_sha>..HEAD
   

   如果 git 中不存在该 SHA（历史已重写），则将其视为过期。
4. 比较已更改的文件与条目的源文件。如果有任何匹配，则该条目已过期。
5. 更新：
   • 新近过期 → 设置 stale: true。保持 verified_sha 不变。
   • 已过期 → 不作更改（仍计入统计）。
   • 差异中没有源文件 → 保持 stale 原样。不要将过期状态改回未过期——只有 verify 模式可以执行此操作。

将更新写回 index.json。

报告

Decodie flag-stale
  Newly stale:  N entries
  Already stale: M entries
  Fresh:        F entries
  Unverified:   U entries (no verified_sha -- run verify mode)
  No sources:   K entries

如果有新近过期的条目，请列出：

Newly stale:
  - entry-1711540000-a1b2 -- src/lib/foo.ts
  - entry-1711540123-c3d4 -- src/lib/bar.ts, src/lib/baz.ts

重要说明

• **单向标记。**只会将 stale 设为 true。清除标记需要使用 verify 模式。
• **不读取源文件。**完全基于 git diff --name-only。因此它足够快，可以用于 CI。
• **没有退出代码策略。**过期条目是否会阻止 PR，取决于各个仓库的决定。
• **不会重写 git 历史。**只执行只读 git 命令。