bug: restore a green md-to-word-swift package test baseline

[kiki830621]

Problem

packages/md-to-word-swift 在乾淨 origin/main 執行完整 swift test 時已有 42 個失敗，讓套件層的「全套件綠燈」失去回歸判別力。這次 #141 只能先以乾淨基線比對，確認沒有新增失敗，而不能宣稱完整套件通過。

Type

bug

Expected

• packages/md-to-word-swift 的完整測試應為零失敗；或在修復前，以明確的 skip／quarantine 契約把已知失敗和真正的新回歸分開。
• 新功能應可直接用完整 swift test 的退出狀態判定是否回歸，不必人工比對失敗數量與名稱。

Actual

乾淨 origin/main 執行 89 個套件測試時，共有 42 個失敗：

• E2ETests.testE2E_Tier3MetadataRestoration：1 個失敗。
• RoundTripTests：41 個失敗。

#141 候選增加 math 測試後執行 114 個測試，仍是相同兩個 suite、相同總數 42 個失敗；所有新增與直接受影響測試都通過。這證明 #141 沒有增加失敗，但也證明目前 baseline 不能作為一般的全綠 gate。

Reproduction

cd packages/md-to-word-swift
swift test

Impact

• package-wide regression gate 會永久回傳非零，CI 或開發者無法區分既有失敗與新回歸。
• 每個後續功能都必須另做乾淨基線比對，增加人工判讀與 false-green 風險。
• Round-trip 失真可能隱藏真實的 Markdown／Word 語意資料損失。

Scope boundary

本票只追蹤 md-to-word-swift 的 E2E／RoundTrip 測試與對應語意；不吸收 #127 的 OOXML package lossless/sync 主線。

---

Source: surfaced during /idd-implement #141 reproduction (Step 5.7)

[kiki830621]

Diagnosis

Type

bug

Root Cause / Analysis

The issue reports "42 failures out of 89 tests on clean origin/main". Reproduced, and the picture is sharper — and worse — than that.

There is no origin. git remote -v is empty; the package has only a local main. It is consumed solely through macdoc's path: dependency and has never been published. So "clean origin/main" cannot be reproduced literally; the nearest equivalent is a clean clone of the local HEAD.

At HEAD the test target does not compile at all:

Tests/MDToWordTests/E2ETests.swift:293:39: error:
  value of type 'MarkdownToWordConverter' has no member 'convertMarkdown'

swift build succeeds — it builds only the library — which is why this looks like a passing package until you run swift test. Two commands, two different answers, and the reassuring one is the one people run first.

The 42 failures describe the working tree, not HEAD. The uncommitted state carries a substantive rewrite, not the directory rename it first appears to be:

	HEAD	working tree (uncommitted)
Source dir	Sources/MDToWordSwift/	Sources/MDToWord/ — 5 untracked files
Public API	convert, convertToFile	+ convertToDocument, convertMarkdown

1332 deletions staged against HEAD, five new files untracked. convertMarkdown — the method the committed test calls — exists only in the uncommitted source.

So the root cause of the broken baseline is an ordering inversion: the tests were committed ahead of the implementation they exercise. HEAD is internally inconsistent. The 42 round-trip failures are a second, separate problem that only becomes visible once the uncommitted work restores compilation.

Impact

• The package has no usable test signal. swift test at HEAD fails to build, so no regression can be detected by exit status — which is exactly what this issue was filed about, though for a different reason than stated.
• It blocks a shipped data-loss fix from reaching users. macdoc CLI cannot be released from a tree whose packages/md-to-word-swift state exists in no commit; releasing would sign and distribute source that cannot be rebuilt. That release is what carries ooxml-swift#109's directory-protection fix to macdoc word render users, who currently still have the destructive path.
• Not user-visible directly — this package ships only inside macdoc, and macdoc builds against the working tree.

Strategy

Two separable problems; the first is not mine to perform.

• Make HEAD internally consistent — commit the in-flight rewrite (the five Sources/MDToWord/ files, the deletion of Sources/MDToWordSwift/, and the untracked README) so the committed tests compile against committed source. This is someone else's in-flight work; whether it is finished is a question only its author can answer. Declined to commit it unilaterally.
• Once HEAD compiles, re-baseline: run the suite and record the real failure set, rather than inheriting the "42" figure from a working tree that has since moved.
• Triage the round-trip failures. They are concentrated in RoundTripTests (MD → docx → MD comparisons), which depend on word-to-md-swift's converter output — a dependency that has since moved to 1.0.0. Some of the 42 may be stale expectations rather than defects.
• Decide the quarantine contract the issue asks for: either zero failures, or explicit XCTSkip with a recorded reason, so swift test's exit status becomes a usable regression signal again.

Conflict Class

B_resource_serialize — the shared resource is the packages/md-to-word-swift working tree itself, which currently holds another session's uncommitted rewrite. Any concurrent work there risks colliding with or destroying that state. Not A_parallel_safe on those grounds alone, independent of what the fix touches.

Complexity

Plan

• Layer 1: no disqualifier.
• Layer 2 (Spectra): not met. The package is unpublished and consumed by exactly one path dependency; there is no contract for future callers to freeze.
• Layer P: several signals — the work has an ordered dependency (HEAD must compile before the failures can even be enumerated), the 42 failures need triage into "stale expectation" versus "real defect" before a strategy exists, and the quarantine-versus-fix decision is a genuine choice with two defensible answers.

Hard-gate: not triggered — insufficient signal. The file count cannot be estimated until the failures are triaged, and the shared abstraction under discussion (MarkdownToWordConverter) has one consumer.

Risks

• The in-flight rewrite may be incomplete. Committing it to make HEAD consistent could freeze a half-finished API into the one thing macdoc depends on.
• The 42 failures were measured against a word-to-md-swift that has since gone to 1.0.0 (module rename plus whatever changed between 0.4.x and 0.8.x). The failure set must be re-measured before it is trusted.
• Fixing round-trip expectations without understanding which side is wrong risks encoding the current output as correct when it is the regression.

Residue

The deeper question this issue points at but cannot settle: why did the tests get committed ahead of the implementation? A package where swift build passes and swift test does not compile can sit in that state indefinitely without anyone noticing, because the reassuring command is the one people run. Whatever process allowed that — no CI, or CI that runs build and not test — is the thing that will let it recur, and this issue does not address it.

[kiki830621]

Re-measured, and the 42 is not 42 bugs

Re-run today against the current pins (word-to-md-swift 1.0.0, ooxml-swift 3.1.0), after the module rename landed:

Executed 89 tests, with 42 failures

The count did not move — the earlier figure was measured against an older word-to-md-swift, and I flagged it as needing re-measurement. It re-measures to the same number. But the number is misleading, and that is the useful finding here.

42 failures, 41 distinct test cases, and 32 of them share one cause

Where	Distinct failing tests
RoundTripTests tier C	32
RoundTripTests tiers A + B	8
E2ETests	1

(42 vs 41: one test trips two assertions.)

Tier C is every tier-C test, including testRoundTripC_BasicParagraph, whose whole body is assertWordLevelRoundTrip("Hello world"). When the simplest possible case fails alongside tables and nested lists, the shared helper is the suspect, not thirty-two separate conversion defects.

The tier-C criterion cannot pass, independent of conversion correctness

assertWordLevelRoundTrip asserts XCTAssertEqual(w1, w2) where both sides are produced by convertMarkdown — no docx is written or read anywhere in that path. So the assertion reduces to: does building the same markdown twice produce equal documents?

Measured directly:

plain         raw-equal=false   masked-equal=true
heading+list  raw-equal=false   masked-equal=true
table         raw-equal=true    masked-equal=true
codeblock     raw-equal=false   masked-equal=true

masked = every w14ParaId / w14TextId value replaced with a constant. Masking those two fields makes the documents equal in all four shapes; the unmasked diff is exactly:

w14ParaId: Optional("34A8DA61")    vs    w14ParaId: Optional("18409210")

w14:paraId is an 8-hex identifier stamped fresh per paragraph at construction. Two documents built from identical markdown are therefore never ==, and XCTAssertEqual(w1, w2) on whole WordDocument values can never hold while that is true.

So those 32 failures are one defect in the test's equality criterion, not 32 in the converter. Whether g ∘ f = id_{W*} actually holds is currently unknown — the test that was supposed to answer it has been answering a different question.

What this does not establish

The 8 tier-A/B failures (blockquote, code block, link, thematic break, mixed content) and the 1 E2ETests failure are markdown-level assertions that do not go through this helper. They were not investigated here and may well be genuine. Restoring a green baseline needs them looked at separately — masking paraId will not touch them.

Suggested direction

Tier C needs a paraId-insensitive comparison: either compare a normalized projection, or make the ID assignment injectable so tests can pin it. Making it deterministic globally is the wrong fix — Word expects these to be unique per paragraph.

Worth noting alongside #160, which asks why macdoc convert output lacks w14:paraId. Same field, opposite end: here it is stamped and breaks equality, there it is absent and blocks DSL upgrade. Whatever policy gets written should cover both.