decodie-flag-stale

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Decodie — Flag Stale Mode

Decodie — 标记过时模式

Fast, CI-friendly counterpart to verify mode. For every entry with a

verified_sha

, check whether any of its source files have changed since that SHA, and flip

stale: true

on entries that have. Does not read source files or recompute anchor hashes — only diffs filenames against git history.

This mode modifies
.decodie/index.json
only.

作为验证模式的快速、适配CI的替代方案。对于每个带有

verified_sha

的条目，检查其任意源文件自该SHA以来是否已更改，并将已更改条目的

stale

设为

true

。无需读取源文件或重新计算锚点哈希值——仅对比文件名与git历史记录的差异。

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

Activation

激活方式

Takes no arguments. Always operates on the full index.

无需参数。始终对完整索引进行操作。

Setup

设置步骤

Confirm
```
.decodie/
```
exists. If not: "No
```
.decodie/
```
directory found — nothing to check." Stop.
Confirm git repository:
bash
```
git rev-parse --git-dir
```
If not: "Not a git repository —
```
flag-stale
```
requires git history. Run verify mode instead." Stop.
Read
```
.decodie/index.json
```
. If empty: "No entries to check." Stop.

确认
```
.decodie/
```
目录存在。若不存在：“未找到
```
.decodie/
```
目录——无可检查内容。”停止操作。
确认当前为git仓库：
bash
```
git rev-parse --git-dir
```
若不是git仓库：“当前不是git仓库——
```
flag-stale
```
需要git历史记录。请改用验证模式。”停止操作。
读取
```
.decodie/index.json
```
。若为空：“无可检查的条目。”停止操作。

Detection Process

检测流程

For each entry:

Skip entries with no
verified_sha
. Report as
```
unverified
```
.
Skip entries with no
sources
(and no
```
references[].file
```
fallback). Report as
```
no-sources
```
.
Compute changed files:
bash
```
git diff --name-only <verified_sha>..HEAD
```
If the SHA is unknown to git (history rewritten), treat as stale.
Compare changed files against entry's source files. If any match, the entry is stale.
Update:
- Newly stale → set
```
stale: true
```
  . Leave
```
verified_sha
```
  unchanged.
- Already stale → no change (still counted).
- No source files in diff → leave
```
stale
```
  as-is. Do not flip stale back to fresh — only verify mode can do that.

Write updates back to

index.json

针对每个条目：

跳过无
verified_sha
的条目，标记为
```
unverified
```
。
跳过无
sources
的条目（且无
```
references[].file
```
作为备选），标记为
```
no-sources
```
。
计算已更改文件：
bash
```
git diff --name-only <verified_sha>..HEAD
```
若git无法识别该SHA（历史记录已重写），则视为过时。
对比已更改文件与条目的源文件。若存在匹配项，则该条目为过时状态。
更新条目：
- 新变为过时 → 设置
```
stale: true
```
  ，保留
```
verified_sha
```
  不变。
- 已处于过时状态 → 不做更改（仍计入统计）。
- 源文件未出现在差异结果中 → 保留
```
stale
```
  原有状态。请勿将过时状态改回正常——仅验证模式可执行此操作。

将更新结果写回

index.json

。

Reporting

报告输出

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

If newly stale, list them:

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

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

Important Notes

重要说明

One-way flag. Only flips
```
stale
```
to
```
true
```
. Clearing requires verify mode.
No source file reads. Based purely on
```
git diff --name-only
```
. This is what makes it fast enough for CI.
No exit-code policy. Whether stale entries block a PR is a per-repo decision.
No git history rewriting. Only read-only git commands.

单向标记：仅将
```
stale
```
设为
```
true
```
。清除过时状态需使用验证模式。
不读取源文件：完全基于
```
git diff --name-only
```
实现，这也是其能够在CI中快速运行的原因。
无退出码规则：是否因过时条目阻塞PR需由各仓库自行决定。
不修改git历史：仅使用只读git命令。