Skip to content

fix: byte-equal 驗證成功訊息說出比對範圍 (#178) - #180

Merged
kiki830621 merged 1 commit into
mainfrom
idd/178-verify-message-scope
Sep 1, 2026
Merged

fix: byte-equal 驗證成功訊息說出比對範圍 (#178)#180
kiki830621 merged 1 commit into
mainfrom
idd/178-verify-message-scope

Conversation

@kiki830621

Copy link
Copy Markdown
Member

Refs #178

Summary

byte-equal 驗證通過 單獨一句沒有說明比對範圍。實測 15,536 B 的重建檔對 19,232 B 的參考檔,驗證通過——差異來自 zip 容器(entry 順序、壓縮參數、時間戳),而比對是 per part、容器從不進入比較。但成功訊息沒有任何地方透露這件事,讀者 ls -la 一對就會懷疑工具。

改為:byte-equal 驗證通過(N 個 part 逐位元組相同;zip 容器大小可能不同)

順帶修 --verify-against 的 help 字串:readAllParts 收所有 entry.type == .file(含 binary),原本寫「XML part set」不精確。

N 是精確值,不是近似

原本的 diagnosis 打算在 ScriptExecuteResult 加欄位以維持與 MCP 面的 parity。但 packages/ooxml-swift 是獨立 repo(macdoc .gitignore:21packages/ 不含它的 ! 例外),那會變成跨三個 repo 的協調。

重新推導後不需要:compareParts 走兩邊 key 的聯集,只在一邊出現的 path 得 .missingInRebuilt / .unexpectedInRebuilt,兩者都不是 .equal,必然落進 broken。訊息只在 broken.isEmpty 時印,所以此時聯集內每個 path 都 .equal ⟹ 兩邊 key 集合相同 ⟹ 聯集大小=參考檔 part 數。CLI 端自己讀參考檔數 part,在會印訊息的那條路徑上精確。

代價:一次多餘的 zip 讀取,且只在使用者要求驗證時。

已知缺口(刻意留下)

MCP 面的 execute_script 拿不到這個改善。 要 parity 仍需在 ooxml-swift 的 ScriptExecuteResult 加欄位——跨 repo 工作,該另開 issue 而非塞進本次。明寫在這裡而不是靜默留著。

Verification

  • swift test --filter WordRenderTests13 tests / 0 failed(1 skip 是既有的 testRawChannelDocumentStillRoundTripsByteEqual,非本次新增)
  • 新增測試斷言訊息含 part 數,數字直接對照 RawPartChannel.readAllParts(...).count

另有一個「count 須涵蓋非 XML part」的測試寫了又移除:合成 fixture 全是 XML,該測試永遠 skip。永遠 skip 的測試等於沒有,而它宣稱的事已被上面那個斷言涵蓋(對照的就是含 binary 的同一個 API)。

Checklist

  • Diagnose(含跨 repo 前提的更正)
  • Implement(1 commit)
  • 目標測試 13/13 綠
  • 完整套件:32 tests / 0 failures

🤖 Generated by /idd-all。不得加 close trailer——IDD 要求 merge 後手動 /idd-close

「byte-equal 驗證通過」單獨一句會讓人去 `ls -la` 對一下兩個檔案,看到大小
不同,然後懷疑工具。實測:15,536 B 的重建檔對 19,232 B 的參考檔,驗證通過。

差異是正常的——比對是 per part,zip 容器(entry 順序、壓縮參數、時間戳)
從不進入比較(`RawPartChannel.readAllParts` 以 part path 為 key、只取內容)。
但成功訊息沒有任何地方透露這件事。

改為:`byte-equal 驗證通過(N 個 part 逐位元組相同;zip 容器大小可能不同)`

**N 由 CLI 端讀參考檔取得,且在會印訊息的那條路徑上是精確值不是近似。**
`compareParts` 走的是兩邊 key 的聯集,只在一邊出現的 path 會得
`.missingInRebuilt` / `.unexpectedInRebuilt`——兩者都不是 `.equal`,必然
落進 `broken`。訊息只在 `broken.isEmpty` 時印,所以此時聯集內每個 path 都
`.equal`,兩邊 key 集合必然相同,聯集大小=參考檔 part 數。

原本的 diagnosis 打算在 `ScriptExecuteResult` 加欄位以維持與 MCP 面的
parity,但 `packages/ooxml-swift` 是獨立 repo(macdoc `.gitignore:21` 的
`packages/` 不含它的 `!` 例外),那會變成跨三個 repo 的協調。上面的推導
讓 CLI 端自足,範圍收回單一 repo。

**已知缺口(刻意留下並記錄)**:MCP 面的 `execute_script` 拿不到這個改善。
要 parity 仍需在 ooxml-swift 的 `ScriptExecuteResult` 加欄位——那是跨 repo
工作,該另開 issue,不塞進本次。

順帶修 `--verify-against` 的 help 字串:`readAllParts` 收所有
`entry.type == .file`(含 binary),不只 XML,原本寫「XML part set」不精確。

測試:新增一例斷言訊息含 part 數與容器說明,數字對照
`RawPartChannel.readAllParts(...).count`。

(另有一個「count 須涵蓋非 XML part」的測試寫了又移除——合成 fixture 全是
XML,該測試永遠 skip。永遠 skip 的測試等於沒有,而它宣稱的事已被上面那個
斷言涵蓋:那裡直接對照的就是含 binary 的同一個 API。)

Refs #178
@kiki830621
kiki830621 merged commit bd033c8 into main Sep 1, 2026
2 checks passed
@kiki830621
kiki830621 deleted the idd/178-verify-message-scope branch September 1, 2026 03:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant