decodie-verify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Decodie — Verify Mode

Decodie — 验证模式

Confirm that every learning entry in

.decodie/index.json

still matches the source code it references, mark mismatches as stale, and stamp confirmed entries with the current commit SHA.

This mode modifies
.decodie/index.json
only. It never modifies session files, source code, or anything outside

.decodie/

确认

.decodie/index.json

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

此模式仅修改
.decodie/index.json
。它绝不会修改会话文件、源代码或

.decodie/

目录以外的任何内容。

Activation

激活方式

Parse the optional path argument:

If no path provided, verify all entries.
If a path is provided, verify only entries whose
```
sources
```
(or
```
references[].file
```
) overlap that path. For a directory, an entry is in scope if any source file starts with that directory.
If the path does not exist, report the error and stop.

解析可选的路径参数：

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

Setup

设置步骤

Confirm
```
.decodie/
```
exists. If not: "No
```
.decodie/
```
directory found — nothing to verify." Stop.
Read
```
.decodie/index.json
```
. If empty: "No entries to verify." Stop.
Determine current commit SHA:
bash
```
git rev-parse HEAD
```
If not a git repo, warn and continue (anchor checks still run, but
```
verified_sha
```
cannot be set).

确认
```
.decodie/
```
目录存在。如果不存在：“未找到
```
.decodie/
```
目录——无可验证内容。” 停止操作。
读取
```
.decodie/index.json
```
。如果为空：“无可验证的条目。” 停止操作。
获取当前提交SHA：
bash
```
git rev-parse HEAD
```
如果当前不是git仓库，发出警告并继续执行（仍会进行锚点检查，但无法设置
```
verified_sha
```
）。

Verification Process

验证流程

For each entry in scope:

Resolve source files. Prefer
```
sources
```
; fall back to unique
```
references[].file
```
values. If falling back, backfill the
```
sources
```
field.
Check each reference
```
{ file, anchor, anchor_hash }
```
:
- File missing → reference fails.
- File exists → search for literal
```
anchor
```
  string. If found, recompute SHA-256 hash and confirm first 8 hex chars match
```
anchor_hash
```
  .
Decide outcome:
- All references resolve →
```
stale: false
```
  ,
```
verified_sha
```
  = HEAD SHA.
- Any reference fails →
```
stale: true
```
  , leave
```
verified_sha
```
  unchanged.
Write back to
```
index.json
```
. Preserve all other fields and sort order.

对于每个在范围内的条目：

解析源文件。优先使用
```
sources
```
字段；如果没有，则使用唯一的
```
references[].file
```
值。如果使用后者，回填
```
sources
```
字段。
检查每个引用
```
{ file, anchor, anchor_hash }
```
：
- 文件缺失 → 引用验证失败。
- 文件存在 → 搜索字面量
```
anchor
```
  字符串。如果找到，重新计算SHA-256哈希值，并确认其前8位十六进制字符与
```
anchor_hash
```
  匹配。
判定结果：
- 所有引用解析成功 → 设置
```
stale: false
```
  ，
```
verified_sha
```
  = HEAD SHA。
- 任何引用验证失败 → 设置
```
stale: true
```
  ，保留
```
verified_sha
```
  不变。
写回文件至
```
index.json
```
。保留所有其他字段和排序顺序。

Reporting

报告输出

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

If stale entries exist, list them:

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)

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)

Important Notes

重要说明

Append-only for entry content. Only
```
sources
```
,
```
verified_sha
```
, and
```
stale
```
may be updated.
Idempotent. Running twice with no changes is a no-op.
Path is a filter. Out-of-scope entries are skipped, not cleared.
No git history rewriting. Only reads HEAD via
```
git rev-parse
```
.

条目内容仅追加。仅允许更新
```
sources
```
、
```
verified_sha
```
和
```
stale
```
字段。
幂等性。在无变更的情况下运行两次不会产生任何操作。
路径作为过滤器。超出范围的条目会被跳过，而非清除。
不重写git历史。仅通过
```
git rev-parse
```
读取HEAD。