feat!: 年份支援改為 runtime 探測，並修正兩個統計錯誤 (2.0.0)

[lis186]

為什麼

上游 ruyut/TaiwanCalendar 早已發布 2027 資料，但本套件把「支援到哪一年」寫死成 2026，導致查不到，已延誤約半年。

資料本來就是 runtime 從 CDN 抓的、不打包進套件 —— 把「有哪些年份」打包進發布物是設計錯誤。寫死下限（2017，上游起點）合理；寫死上限不合理。

順著這條線查出同一病灶的多個變體，以及兩個長期存在的統計錯誤。

破壞性變更

變更	影響
移除公開匯出 SUPPORTED_YEAR_RANGE	改用 MIN_SUPPORTED_YEAR + getMaxQueryableYear()。原本的 end 是個謊 —— 它宣稱是「支援上限」，實際只是打包當時的寫死值
HolidayStats.nationalHolidays 語意變更	只計具名國定假日。2026 年從 114 變成 16（另 98 個是週末，移入新欄位 weekends）
stats 的 holidayTypes 數值變更	先前在全部 11 個年度都是錯的（見下）

版號 1.0.1 → 2.0.0。MAJOR 在 cli / mcp / skills 三個專案間共享，代表同一世代；MINOR/PATCH 各自獨立。

破壞性判定不是主觀的 —— 寫一份「舊消費者」檔 import { SUPPORTED_YEAR_RANGE } 對打包產物跑 tsc：舊 dist exit 0、新 dist TS2305 has no exported member。

主要變更

年份改為 runtime 探測 — 收到年份就向上游探測，有資料就能查；上游發布新年度不需更新本套件。只有 HTTP 404 代表「上游沒有這一年」；網路故障、超時、5xx 一律往外拋。

未來年度 404 與歷史年度 404 分開處理：前者是「尚未發布」（可安全跳過），後者代表上游把已發布資料弄掉了 —— 靜默跳過會讓使用者拿到不完整答案卻以為完整。

stats 兩個錯誤 — holidayTypes 一個 map 混「分類桶」與「具體假日名」兩種語意，當上游 description 剛好等於桶名時被加兩次。用真實資料驗證：舊邏輯在全部 11 個年度（2017–2027）都算錯，碰撞的 key 有兩個 —— 補假（10 個年度）與 調整放假（2017–2023）。另修 nationalHolidays 把週末算成國定假日。

移除 386 行死碼 — year-service.ts 本意是動態探索年份，但零呼叫端、端點 URL 不存在（實測連線失敗），而它的 14 個測試全綠是因為 mock 餵入真實端點從未回傳的形狀。

新增上游哨兵 — 每月驗證上游結構與內容（型別、逐日連續、星期比對、合理區間），並偵測年度倒退。13 條測試涵蓋 10 種畸形資料。

工具鏈補洞 — npm run lint 原本 exit 127（eslint 不在 devDependencies）；npm run typecheck 從未檢查測試碼（主 tsconfig 的 exclude 含 tests，而 vitest 用 esbuild 剝型別不檢查 —— 連 satisfies HolidayStats 都只是裝飾品）。

驗證

依「差異檢查」原則：同一測試在舊碼 FAIL、新碼 PASS。

主張	舊碼實際訊息
補假不重複計數	expected 4 to be 2
調整放假不重複計數	expected 7 to be 4
國定假日桶不含週末	expected 3 to be 2
2027 不該被程式碼擋掉	ValidationError: 年份 2027 超出支援範圍
網路故障應拋錯	promise resolved "[2017…2026]" instead of rejecting
npm run lint 可執行	exit 127

Golden acceptance（真實上游 11 年）：舊統計邏輯 11/11 年皆錯、新邏輯 0/11 錯。CLI 輸出與獨立數出的 ground truth 完全一致（2026: 具名 16 / 週末 98 / 補假 6 = 120）。

發佈後行為：npm pack → 安裝到乾淨臨時專案 → npx holiday --version 回 2.0.0、years 回 2017-2027、stats 2026 三個數字全對。

離線行為（複製真實 dist、CDN 換成不可解析主機、清快取）：years 從「印出 2017-2026 並 exit 0」變成 exit 1 + 明確錯誤。

目前狀態：typecheck（含測試）0 錯誤、lint exit 0、333 測試通過、canary 對真實上游 11 年通過。

誠實標示：未驗證的部分

• CI workflow 從未實際執行。YAML 與 shell 只做靜態檢查（python3 yaml、shellcheck）；gh issue create、GITHUB_STEP_SUMMARY 渲染、以及排程觸發都要 merge 後 workflow_dispatch 才算驗證。cron 是否按月觸發無法在合理時間內驗證。
• 7 個 explicit-function-return-type warning 未處理（該規則本身設為 warn；已確認 lint script 無 --max-warnings，CI 不會因此紅）。
• 24h 快取 TTL 的真實時間軸未驗，只用假時鐘驗邏輯。
• getMaxQueryableYear() = 今年+5 的跨年翻轉無測試。
• 未來年度倒退不在 runtime 擋，只靠 canary 月檢（最多延遲一個月發現）。這是刻意取捨：runtime 保存 last-known 會引入跟上游可能不一致的永久狀態，且使用者清快取後保護就消失。
• 四個 commit 的中間狀態未逐一執行測試（刻意讓各 commit 的檔案集合互斥以保持自成一致），但 HEAD 完整驗過。

已知待辦（不在本 PR）

• holidayTypes 一個 map 混兩種語意的結構問題只做防禦性修補，未拆成兩個欄位
• stats 的 holidayTypes.補假 與 compensatoryDays 現已一致，但兩者仍是重複資訊
• skills repo 的文件與 ~/.agents/ 孤兒副本需在 npm 上架後更新

🤖 Generated with Claude Code