P3 enhancement: InsertLocationError add LocalizedError conformance (post-che-word-mcp#91 verify follow-up F5)

[kiki830621]

Current Status

Phase: implemented
Last updated: 2026-05-02
Implementation: PR #35 / commit e63baaa
Verification: swift build; focused swift test --filter InsertLocationTests|ParagraphTests|Issue56RoundtripCompletenessTests|Issue6RoundtripLoudFailTests; full swift test (830 tests, 1 skipped, 0 failures)

Notes: InsertLocationError now conforms to LocalizedError; every case has a human-readable errorDescription, with unit coverage for each case.

Problem

From verification of #91 (Devil's Advocate DA-2):
「InsertLocationError lacks LocalizedError conformance — sibling enums CommentError / FootnoteError / EndnoteError all conform. Missed opportunity to ship a human-readable message for the new case.」
— Source: team:devils-advocate

Type

enhancement

Background

InsertLocationError (Sources/OOXMLSwift/Models/InsertLocation.swift:28-42) currently:

public enum InsertLocationError: Error, Equatable {
    case invalidParagraphIndex(Int)
    case imageIdNotFound(String)
    case tableIndexOutOfRange(Int)
    case tableCellOutOfRange(tableIndex: Int, row: Int, col: Int)
    case textNotFound(searchText: String, instance: Int)
    case inlineModeRequiresParagraphIndex  // post-#91
}

Sibling enums in the same package (CommentError, FootnoteError, EndnoteError) all conform to LocalizedError and provide errorDescription strings. InsertLocationError is the odd one out — callers using error.localizedDescription get the case name string instead of a human-readable message.

Expected

extension InsertLocationError: LocalizedError {
    public var errorDescription: String? {
        switch self {
        case .invalidParagraphIndex(let idx):
            return "Paragraph index \(idx) is out of range for the document."
        case .imageIdNotFound(let rId):
            return "No image with relationship id '\(rId)' was found in the document."
        case .tableIndexOutOfRange(let idx):
            return "Table index \(idx) is out of range for the document."
        case .tableCellOutOfRange(let tableIdx, let row, let col):
            return "Table cell (table \(tableIdx), row \(row), col \(col)) is out of range."
        case .textNotFound(let searchText, let instance):
            return "Could not find instance \(instance) of text '\(searchText)' in the document."
        case .inlineModeRequiresParagraphIndex:
            return "Inline equations only support paragraphIndex anchors. Use a different anchor type or switch to displayMode: true."
        }
    }
}

Effort

Trivial — ~20 LOC + 1 test asserting errorDescription is non-nil for each case.

Related

• P2 bug: insertEquation inline-mode silent no-op + misleading invalidParagraphIndex(-1) sentinel (post-#84 follow-up) che-word-mcp#91 (verify F5 finding)
• Sibling pattern: CommentError.LocalizedError, FootnoteError.LocalizedError, EndnoteError.LocalizedError

[kiki830621]

Implementation Plan

Scope

Add human-readable LocalizedError.errorDescription strings to InsertLocationError.

Plan

• Add LocalizedError conformance to InsertLocationError.
• Cover every existing case, including inlineModeRequiresParagraphIndex.
• Add one test asserting all cases provide non-empty descriptions and key payload details.

[kiki830621]

📝 Note

Source: implementation commit e63baaa / PR #35
Date: 2026-05-02

論述

#20 的實作已完成。InsertLocationError 現在直接 conform LocalizedError，所有 case 都有 human-readable errorDescription；測試也新增每個 case 的描述覆蓋，確保 future case 或訊息回歸會被攔住。

Details

• Commit: e63baaa
• PR: Clean up comment IDs and insert location errors #35
• Verification: swift build; focused swift test --filter InsertLocationTests|ParagraphTests|Issue56RoundtripCompletenessTests|Issue6RoundtripLoudFailTests; full swift test (830 tests, 1 skipped, 0 failures)