Skip to content

docs: byte-equal 驗證成功訊息未說明比對單位是 XML part — 檔案大小不同會被讀成驗證失敗 #178

Description

@kiki830621

Problem

--verify-against 通過時只印一行:

$ macdoc word render x.mdocx.swift --to-docx rebuilt.docx --verify-against original.docx
已寫入: rebuilt.docx
byte-equal 驗證通過

但兩個檔案的大小不同

rebuilt.docx   15536 B
original.docx  19232 B

這是正確行為 —— byte-equal 保證的是「每個 XML part 逐位元組相同」,不是 zip 容器相同(壓縮參數、entry 順序、時間戳都可能不同)。SKILL.md 也寫對了:

驗證通過 = 重建出的每個 XML part 與參考檔逐位元組相同

問題是驗證輸出本身沒有講。使用者拿到「byte-equal 驗證通過」這句話,很自然會去 ls -la 對一下,看到差 3.7 KB,第一反應是「所以到底過了沒有」。

Type

docs

Expected

驗證成功訊息帶上範圍限定,例如:

byte-equal 驗證通過(14 個 XML part 全部逐位元組相同;zip 容器大小可能不同)

Actual

只有「byte-equal 驗證通過」,不說明比對的單位是 XML part 而非檔案。

Impact

低嚴重度,但這是會讓人懷疑工具正確性的那種不清楚——而 swiftify 的整個價值主張建立在「這個驗證可信」上。一句話的成本,換掉一次「它到底過了沒」的自我懷疑。

(實測:24,932 B 的 word/document.xml 在兩邊逐位元組相同,14 個 part 全過;差異純粹來自容器。)

環境

  • macdoc 0.7.0

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationplatform:macos含 macOS 專屬行為、實作或已驗證範圍

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions