MCP 層補 handler 行為 unit test（get_chat_history）

[kiki830621]

Problem

From verification of #3, #4:
「MCP 層的測試只驗 schema，沒有驗 handler 行為。ServerDumpChatToolTests.swift:71 只確認 get_chat_history 有六個欄位，沒有驗證 from_message_id == 0 時是否真的自動把 max_messages = limit，也沒有驗證 since_date / until_date / max_messages 是否真的傳進 TDLibClient」
— Sources: codex + team:regression

目前 get_chat_history 的 MCP 層只有 schema shape test，沒有 handler 行為 test。#3 的核心 fix（fromMsgId==0 時自動帶 maxMessages=limit）完全沒有 unit test 保護，只靠間接的 E2E test。

Type

enhancement

Expected

加入 unit tests 驗證 MCP handler 行為（至少不依賴真實 TDLib 連線）：

• fromMsgId == 0 且無 max_messages → TDLibClient.getChatHistory 被呼叫時帶 maxMessages == limit
• fromMsgId > 0 且無 max_messages → maxMessages == nil（backward-compat path）
• 傳入 since_date / until_date → 正確解析為 Date 並傳入
• 傳入 max_messages → 覆蓋上面的隱式默認

Actual

只有 testGetChatHistoryProperties 驗證 schema 有 6 個 properties。

Impact

• get_chat_history: from_message_id=0 首次呼叫只回傳 1 則訊息 #3 的 fix 如果未來被改壞（例如有人把 fromMsgId == 0 ? limit : nil 移除），沒有 unit test 會 fail
• 回歸保護不足

Technical Approach

可能需要 mock 或 fake TDLibClient 來驗證 handler 傳給 library 層的參數。參考 TDLibClientBackwardCompatTests 的 pattern（pure compilation + signature tests）。

Code Reference

• Handler: Sources/CheTelegramAllMCPCore/Server.swift:345-363
• Existing schema test: Tests/CheTelegramAllMCPTests/ServerDumpChatToolTests.swift:71-82

Related: #3, #4

Current Status

Phase: closed
Last updated: 2026-04-26 by idd-close

Key Decisions

• Pure-function extraction strategy validated by full 6-AI review
• 11 regression tests lock get_chat_history: from_message_id=0 首次呼叫只回傳 1 則訊息 #3/get_chat_history: MCP 層未暴露 sinceDate/untilDate/maxMessages 參數 #4/日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5/max_messages 邊界防護: 加硬上限 + 0/負數處理 #6 behaviors
• Handler 35 → 16 lines (responsibility separation)
• 5 non-blocking findings → follow-up issues Test: assert MCP handler error message text (contract test) #11/Test: backward-compat numeric-string chat_id / from_message_id parsing #12/Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13/Test: handler glue integration (errorResult conversion + tdlib wiring) #14/Test hardening: int64 helper DRY + boundary + TZ assertions #15

Scope Changes

(none)

Follow-up

• Test: assert MCP handler error message text (contract test) #11 error text 斷言測試
• Test: backward-compat numeric-string chat_id / from_message_id parsing #12 numeric-string backward-compat 測試
• Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 dump_chat_to_markdown 同步 refactor (HIGH)
• Test: handler glue integration (errorResult conversion + tdlib wiring) #14 handler glue integration tests
• Test hardening: int64 helper DRY + boundary + TZ assertions #15 int64Arg helper DRY + 10_001 boundary + TZ assertions

Commits

• f8a7d51 refactor: extract parseGetChatHistoryArgs pure function + handler tests (MCP 層補 handler 行為 unit test（get_chat_history） #7)

[kiki830621]

Diagnosis

Type

feature — 補測試覆蓋

Analysis

目前 get_chat_history MCP handler（Server.swift:345-363）只有 schema shape test（ServerDumpChatToolTests.swift:71-82），驗證 tool 有 6 個 properties，但完全沒測 handler 行為。

缺的測試覆蓋

Behavior	目前狀態
fromMsgId == 0 時 handler 傳 maxMessages: limit 給 TDLibClient（#3 fix 核心）	❌ 無 test
fromMsgId > 0 時 handler 傳 maxMessages: nil（backward-compat path）	❌ 無 test
since_date/until_date string → Date 正確轉換	❌ 無 test
max_messages 明確傳入時覆蓋 fromMsgId=0 的隱式默認	❌ 無 test
各種 invalid input 的 error path	❌ 無 test

風險：如果未來有人改 handler 把 fromMsgId == 0 ? limit : nil 這段移除，沒有 unit test 會 fail — #3 的 bug 會無聲回歸。

Impact

• 影響檔案：新增 Tests/CheTelegramAllMCPTests/ServerHandlerLogicTests.swift（或類似）
• 可能改動：Sources/CheTelegramAllMCPCore/Server.swift（為了 testability 做小 refactor）

Strategy

核心挑戰：handler 內部呼叫 tdlib.getChatHistory(...)，這需要真實 TDLib 連線，不能在 unit test 執行。兩種解法：

解法 A: 抽取 pure function，測 arg parsing

將 handler 的「從 args dict 解析出參數 tuple」這段抽成 pure function：

// In Server.swift, extract:
internal struct GetChatHistoryArgs {
    let chatId: Int64
    let limit: Int
    let fromMessageId: Int64
    let maxMessages: Int?
    let sinceDate: Date?
    let untilDate: Date?
}

internal func parseGetChatHistoryArgs(_ args: [String: Value]) throws -> GetChatHistoryArgs {
    // 現有 handler 的 guard / parseISODate / default 邏輯搬過來
}

• Refactor handler 提取 parseGetChatHistoryArgs function
• Handler 呼叫 try parseGetChatHistoryArgs(args) 後再傳給 tdlib.getChatHistory
• 新增 test file 測 parseGetChatHistoryArgs 各種 input

解法 B: Protocol-based mock

在 TDLibClient 上定義 protocol，test 時注入 mock：

• 工作量大（需要改 Server.swift 持有 protocol，整個 MCP 層都改）
• 但能測更完整的 handler behavior（包含錯誤傳遞）

推薦：解法 A（更 surgical，工作量小，涵蓋本 issue 的核心關切——「#3 的 fix 能被 regression test 保護」）。

Complexity

Simple — 1 個新 test 檔案 + 1 個 handler refactor（抽 function）。無新抽象跨檔案，無架構決策。

Risks

• Refactor 本身是小改動，但 handler 是 hot path，要確保 behavior 等價
• 測試撰寫需注意：since_date="not-a-date" 的期待行為依賴 日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5 的決定（throw vs silent nil）
• max_messages=0 的期待行為依賴 max_messages 邊界防護: 加硬上限 + 0/負數處理 #6 的決定（error vs empty array）

Related & Ordering

必須在 #5 和 #6 實作後才能寫測試，因為測 case 需要知道 error 的 expected behavior。建議 implement 順序：#5 → #6 → #7（或 #5 + #6 同 PR，#7 接續）。

[kiki830621]

Implementation Plan

Strategy: 抽 pure function + 加 handler argument parsing tests

目的：為 #3 的 fix（`fromMsgId == 0 → maxMessages = limit`）和 #4 的參數接線（date parsing, max_messages validation）加 regression test，避免未來誤改。

Changes

• Refactor: 抽 `GetChatHistoryArgs` struct + `parseGetChatHistoryArgs(_ args:) throws -> GetChatHistoryArgs` pure function
  • 把 handler 的 guard/parse/validate 邏輯搬到 pure function
  • `Server.swift` handler 改呼叫 `try parseGetChatHistoryArgs(args)` 後 destructure
  • 保持 behavior 等價（不改語義，只是搬家）
• Tests: 新 `ServerHandlerLogicTests.swift` 驗證 handler arg parsing
  • `fromMsgId == 0` 且無 `max_messages` → `maxMessages == limit`
  • `fromMsgId > 0` 且無 `max_messages` → `maxMessages == nil` (backward-compat path)
  • 顯式 `max_messages: 5` → `maxMessages == 5`
  • `max_messages <= 0` → throws（errorResult path）
  • `max_messages > 10000` → throws
  • `since_date: "2026-04-17"` → Date parsed correctly
  • `since_date: "invalid"` → throws DateParseError
  • `chat_id` missing → throws

Scope check

每個 item 對應 #7 的 diagnosis strategy ✓。不混入 #8 (string bypass)、#9 (log formatting)、#10 (truncate / sanity)。

Commit strategy: 一個 commit — refactor + tests together (atomic)。

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• Refactor: 抽 GetChatHistoryArgs struct + parseGetChatHistoryArgs(_ args:) throws -> GetChatHistoryArgs pure function
• Handler 改呼叫 pure function（Server.swift 從 35 行縮到 16 行）
• ServerHandlerLogicTests.swift 加 11 個 unit test

測試覆蓋表

Test	Locks behavior
testFromMsgIdZeroDefaultsMaxMessagesToLimit	#3 auto-pagination fix
testFromMsgIdNonZeroLeavesMaxMessagesNil	backward-compat path
testExplicitMaxMessagesOverridesImplicit	#4 param precedence
testMaxMessagesRejectsZeroOrNegative	#6-B2 boundary
testMaxMessagesRejectsOverCap	#6 handler cap visibility
testMaxMessagesAtCapAccepted	10_000 is inclusive upper
testSinceDateValidParsed	#5 since_date → start-of-day
testUntilDateUsesEndOfDay	#5-A1 until_date → 23:59:59
testInvalidDateFormatThrows	#5-A2 throw on invalid
testMissingChatIdThrows	required field
testDefaultLimitIs50	default behavior

Legend: - [x] done · - [~] skipped (may revisit) · - [-] won't fix (scope)

Changes

• f8a7d51: refactor: extract parseGetChatHistoryArgs pure function + handler tests (MCP 層補 handler 行為 unit test（get_chat_history） #7)

Files Changed

• Sources/CheTelegramAllMCPCore/HandlerArgs.swift: +79 (new file)
• Sources/CheTelegramAllMCPCore/Server.swift: +10 -25 (handler thinned)
• Tests/CheTelegramAllMCPTests/ServerHandlerLogicTests.swift: +138 (new file)
• CHANGELOG.md: +3 (refactored section)

Key implementation decisions

1. Module-level pure function (同 DateParsing.swift pattern)：parseGetChatHistoryArgs 是 internal func，test 直接 import，無 server instance 依賴。
2. Private helper int64ArgValue：HandlerArgs.swift 需要 Int64 parsing，但 Server.swift 的 int64Arg 是 private method。我在新檔案 duplicate 了一份 private function，避免改 Server.swift 的 private surface。未來可考慮移到共用 module。
3. HandlerArgError 跟 DateParseError 並存：兩層不同原因的 error（argument validation vs date format）各有自己的 type，handler catch 兩個 case。

Scope Compliance

所有改動都在 #7 diagnosis strategy 裡。無 scope creep。77 tests pass（11 new + 66 existing），無 regression。

Next: verification pending

[kiki830621]

Verify: #7

Engine

Codex (gpt-5.4 xhigh) 獨立審查。Claude Agent Team（5 reviewers）略過——先前的 verify-5-6 team 卡在 shutdown 流程無法 TeamDelete，#7 是低風險 refactor（behavior equivalent + pure function extraction）所以單 AI 審查可接受。

要求覆蓋率

FULLY addressed。11 個新 test 完整鎖住 #3 / #4 / #5 / #6 的 behavior contracts。

Findings

#	Severity	Finding	Source	Action
1	—	Behavior equivalence 保留（判斷順序 + 預設值 + 驗證 sequence 都一致）	codex	PASS
2	—	11 個測試覆蓋所有 locked behavior（fromMsgId==0 → maxMessages=limit, >0 → nil, 顯式覆寫, bounds, date parsing, invalid throws, required fields, defaults）	codex	PASS
3	—	無 scope creep	codex	PASS
4	LOW	測試鎖了「throws」但沒 assert specific error text	codex	Follow-up 候選
5	LOW	舊 handler 支援數字字串形式 `chat_id` / `from_message_id`，新 helper 保留但無專屬測試	codex	Follow-up 候選

Scope Check

PASS — 4 files changed，全部可追溯 #7：

• HandlerArgs.swift（新 pure function）
• Server.swift（handler 改薄）
• ServerHandlerLogicTests.swift（11 tests）
• CHANGELOG.md（v0.4.2 Refactored section）

Tests

77 tests pass（11 new + 66 previous），0 failures。

Commits

• f8a7d51 refactor: extract parseGetChatHistoryArgs pure function + handler tests (MCP 層補 handler 行為 unit test（get_chat_history） #7)

判決

PASS — 無 blocking，2 個 LOW non-blocking 可 triage。

[kiki830621]

Verify: #7 (Full 6-AI — updated)

Engine

Agent Team (5 Claude reviewers: requirements / logic / security / regression / devils-advocate) + Codex (gpt-5.4 xhigh)。前次 verify 僅跑 Codex 因 team 卡 shutdown，重跑後取得完整 6-AI review。

要求覆蓋率

FULLY addressed — 11 個新 test 完整鎖住 #3/#4/#5/#6 的 behavior contracts。

Findings（合併去重後）

#	Severity	Finding	Source	Action
1	—	Behavior equivalence 完整保留	team:logic + codex + requirements	PASS
2	—	5/5 requirements FULLY	team:requirements + regression	PASS
3	—	無安全風險	team:security	PASS
4	—	無 scope creep	team:regression	PASS
5	HIGH	`dump_chat_to_markdown` handler 有相同驗證邏輯但未被 refactor → silent drift risk	team:devils-advocate	Follow-up
6	MEDIUM	Tests 只測 parser 不測 handler glue（errorResult / tdlib wiring）	codex	Follow-up
7	MEDIUM	`int64ArgValue` vs `int64Arg` 兩份 private helper 並存 → 違反 DRY	team:devils-advocate	Follow-up
8	MEDIUM	10_001 boundary test 缺失	team:devils-advocate	Follow-up
9	LOW	`testUntilDateUsesEndOfDay` 沒 assert year/month/day（TZ 盲點）	team:devils-advocate	Follow-up
10	LOW	Error message format contract 未 lock	team:devils-advocate + codex	已在 #11
11	LOW	Tests 沒覆蓋 `.string("123")` → Int64 fallback	team:security	已在 #12

Devil's Advocate

提出 7 個反駁，其中 HIGH 1 個（dump_chat_to_markdown drift）+ MEDIUM 3 個，但都歸類為 follow-up 非 blocker——refactor 本身確認 behavior-preserving。

Scope Check

PASS — 4 files 全部可追溯 #7。

Tests

77 pass, 0 failures（Codex 獨立跑過 35 個 CheTelegramAllMCPTests 全數通過）。

Commits

• `f8a7d51` refactor: extract parseGetChatHistoryArgs pure function + handler tests (MCP 層補 handler 行為 unit test（get_chat_history） #7)

判決

PASS — 核心 goal 達成（refactor behavior-preserving + 11 regression tests 鎖住 #3/#4/#5/#6）。所有 findings 為 follow-up 級別，不阻擋 close。

[kiki830621]

Closing Summary

Problem

get_chat_history MCP handler 之前只有 schema shape test (testGetChatHistoryProperties)——驗證 tool 有 6 個 properties，但完全沒測 handler 行為。這代表 #3（fromMsgId==0 auto-pagination）、#4（date/max_messages wiring）、#5（date throws on invalid）、#6（max_messages bounds）的核心 fix 全部沒有 regression test 保護。未來有人改 handler 就可能 silently 回歸這四個 bug。

Root Cause

Handler 邏輯 coupled 到 tdlib.getChatHistory 真實連線，導致純 unit test 困難。歷史上選擇靠 E2E test 間接驗證，但 E2E 慢且需要 Telegram credentials，不適合做 fine-grained regression rules 的 lock。

Solution

Strategy A: 抽 pure function（diagnosis 推薦的解法，避開 protocol-based mock 的工作量）。

具體改動（commit f8a7d51）：

1. 新檔 Sources/CheTelegramAllMCPCore/HandlerArgs.swift（79 行）

   • GetChatHistoryArgs struct（parsed tuple）
   • HandlerArgError type（structured validation 錯誤）
   • parseGetChatHistoryArgs(_ args:) throws -> GetChatHistoryArgs pure function

2. Server.swift get_chat_history handler 改寫

   • 從 35 行縮到 16 行（純 dispatch + 兩層 catch）
   • 所有 parsing/validation 邏輯轉到 pure function

3. 新檔 Tests/CheTelegramAllMCPTests/ServerHandlerLogicTests.swift（11 tests, 138 行）

   • testFromMsgIdZeroDefaultsMaxMessagesToLimit — get_chat_history: from_message_id=0 首次呼叫只回傳 1 則訊息 #3 核心 lock
   • testFromMsgIdNonZeroLeavesMaxMessagesNil — backward-compat path
   • testExplicitMaxMessagesOverridesImplicit — get_chat_history: MCP 層未暴露 sinceDate/untilDate/maxMessages 參數 #4 precedence
   • testMaxMessagesRejectsZeroOrNegative — max_messages 邊界防護: 加硬上限 + 0/負數處理 #6-B2 boundary
   • testMaxMessagesRejectsOverCap — max_messages 邊界防護: 加硬上限 + 0/負數處理 #6 handler cap visibility
   • testMaxMessagesAtCapAccepted — 10_000 inclusive upper
   • testSinceDateValidParsed — 日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5 since_date → start-of-day
   • testUntilDateUsesEndOfDay — 日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5-A1 until_date → 23:59:59
   • testInvalidDateFormatThrows — 日期處理改善: until_date 語義偏差 + parseISODate 靜默 nil #5-A2 throw
   • testMissingChatIdThrows — required field
   • testDefaultLimitIs50 — default

Verification

Full 6-AI verification（5 Claude teammates + Codex）：

• Requirements: 5/5 FULLY addressed
• Logic: behavior-preserving 確認（判斷順序 + 錯誤訊息字字一致）
• Security: 4/4 checks PASS（無 injection / DRY safe / visibility 合理）
• Regression: PASS（無 scope creep + 11 tests 無 redundancy + 77 tests 全綠）
• Codex: behavior equivalence 確認
• Devil's Advocate: 提出 7 個反駁，全為 follow-up 級別（HIGH 1 + MEDIUM 3 + LOW 3）

所有反駁均為 follow-up，無 blocking findings。

Changes

• f8a7d51 refactor: extract parseGetChatHistoryArgs pure function + handler tests (MCP 層補 handler 行為 unit test（get_chat_history） #7)

Follow-up Issues

從本次 verification 開出的 5 個 follow-up：

• Test: assert MCP handler error message text (contract test) #11 error text 斷言測試（lock MCP error message contract）
• Test: backward-compat numeric-string chat_id / from_message_id parsing #12 numeric-string chat_id/from_message_id backward-compat 測試
• Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 dump_chat_to_markdown 同步 refactor（HIGH — silent drift risk）
• Test: handler glue integration (errorResult conversion + tdlib wiring) #14 handler glue integration tests
• Test hardening: int64 helper DRY + boundary + TZ assertions #15 int64Arg helper DRY + 10_001 boundary + TZ assertions