Icyn Date

icyndate

AI エージェントや開発者のための日付コンテキスト：旧暦、二十四節気、祝日、「この日は何を意味するのか」——オフライン、検証済み、MIT。 AI エージェントと開発者向けの日付セマンティックレイヤー：旧暦、二十四節気、祝日、「この日は何を意味するのか」——オフライン、検証可能、MIT。

状況：第 1 週です。旧暦、二十四節気、祝日レイヤー（12 地域）を実装済みです。旧暦と二十四節気は 1900～2100 年の全期間で検証済み、中国本土の祝日は 2024～2026 年について日ごとに照合済みです。

インストール / 安装

npm i @icyn/date                       # library: lunar + solar terms + CN holidays (~90 KB)
import "@icyn/date/regions/all";       # opt in to the other 11 regions (+ subdivisions), or "@icyn/date/regions/JP"

npx -y @icyn/date-mcp                  # MCP server for Claude Desktop / Cursor / any MCP client

現在利用できる機能 / 现在能用的

1 回の呼び出し：

import { dateContext } from "@icyn/date";

dateContext("2026-02-17", { region: "CN" });
// {
//   date: "2026-02-17", region: "CN",
//   civil:    { weekday: 2, isoWeek: 8, isoWeekYear: 2026, dayOfYear: 48, leapYear: false },
//   workday:  { available: true, kind: "public_holiday", isWorkday: false, confidence: "certain", source: "official",
//               holiday: { id: "spring-festival", festival: "lunar-new-year", name: { "zh-Hans": "春节", en: "Chinese New Year" }, dayIndex: 3, span: 9 },
//               meta: { region: "CN", data_version: "2026.09.18", verified_until: 2026, … } },
//   lunar:    { year: 2026, month: 1, day: 1, yearGanZhi: "丙午", zodiac: "马", monthName: "正月", dayName: "初一", … },
//   solarTerm:{ onThisDay: null, current: { name: { zh: "立春", en: "Beginning of Spring" }, at: "2026-02-03T20:01:51.000Z" }, next: { zh: "雨水", … } }
// }

日付は "2026-02-17"、[2026, 2, 17]、{ year, month, day }、または Date（UTC フィールド）で指定できます。祝日に関するすべての回答には、source（official / baseline / predicted）、confidence（certain / likely / uncertain）、データのバージョンメタデータが含まれます。データがない年については、推測せず { available: false, reason } を返します。

機能：

import { solarToLunar, lunarToSolar } from "@icyn/date";

solarToLunar("2026-02-17");
// { year: 2026, month: 1, day: 1, leap: false, yearGanZhi: "丙午", dayGanZhi: "…",
//   zodiac: "马", monthName: "正月", dayName: "初一", isLeapYear: false, monthLength: 30 }

lunarToSolar({ year: 2033, month: 11, day: 1, leap: true }); // [2033, 12, 22]

import { solarTerms, solarTermAt, solarTermOnDay } from "@icyn/date";
solarTermOnDay("2026-02-04");          // { name: { zh: "立春", en: "Beginning of Spring" }, at: 2026-02-03T20:01:51Z, … }
solarTermAt(new Date());               // { current, next } with exact instants
solarTerms(2027);                      // all 24 of the year

import { dayInfo, nextWorkday, workdaysBetween, holidays } from "@icyn/date";
dayInfo("2026-02-14", "CN");           // { kind: "adjusted_workday", isWorkday: true, source: "official", confidence: "certain", … }
dayInfo("2027-02-13", "CN");           // { kind: "weekend", source: "predicted", confidence: "uncertain", note: "Within the usual 调休 window…" }
regionsObserving("lunar-new-year", 2026); // [{ region: "HK", days: [...] }, { region: "KR", … }, …]
dayInfo("2026-01-06", "DE-BY");        // Heilige Drei Könige — subdivision holiday, resolvedRegion "DE-BY"
nextLongWeekend("CN", "2026-09-18", 7); // { start: "2026-10-01", end: "2026-10-07", days: 7 }
nextLunarDate(8, 15, "2026-09-18");    // next 中秋: { date: "2026-09-25", lunarYear: 2026, adjusted: false }
describe("2026-02-17", { region: "CN" });
// "2026-02-17 星期二，农历丙午马年正月初一，CN 放假：春节（第 3/9 天）。"
nextWorkday("CN", "2026-09-30");       // "2026-10-08"
workdaysBetween("CN", "2026-02-13", "2026-02-24");

• 1900-01-31 ～ 2100-12-31 のすべての日について新暦 ⇄ 旧暦に変換します（MAX_DATE。この最終日は旧暦 2100 年の腊月の途中に当たるため、その月の monthLength は null です。テーブルが月の途中で終わるため、実際の日数は不明です）
• 年・日の干支、十二支、中国語の月名と日名、閏月への対応（2033 年の閏冬月のケースを含む）
• 二十四節気を秒単位で正確な時刻として扱います。現在・次の節気を検索でき、任意の UTC オフセットでその日に節気があるかどうかを判定できます
• 12 地域の営業日・祝日を照会でき、すべての回答に official / baseline / predicted のいずれかを付与します。黙って推測することはありません
• 依存関係ゼロで、実行時に天文計算を行いません。テーブルデータは約 480 KB で、デフォルトのエントリーポイントに含まれるのは旧暦・二十四節気のテーブルと中国のデータのみです。他の 11 地域と 70 以上の下位区分は、インポートした場合にのみ読み込まれます

エラーモデル / 失敗行为

• 情報オブジェクトを返す関数（dayInfo、dateContext、holidays）は、データがない場合も例外をスローしません。代わりに { available: false, reason } または空のリストを返します。
• スカラー値を返す関数（isWorkday、addWorkdays、nextWorkday、workdayCount）は、対象の地域・年がデータ範囲外の場合に RangeError をスローします。
• 検索関数（nextLongWeekend、nextLunarDate）は、範囲内に結果が見つからない場合は null を返し、データが尽きた場合は例外をスローします。
• 不正な入力（不明な地域、不正な形式の日付、2 月 30 日）は常に TypeError / RangeError をスローします。地域コードでは大文字と小文字を区別しません（"us-ca" = "US-CA"）。まったくデータがないコードを指定した場合も例外をスローします。
• 予測は未来に対してのみ行います。 まだデータを登録していない年は、最後に登録した年（coverage(region).predictedFrom）より後の場合に限り外挿します。過去のデータ未収録年については推測せず、{ available: false } を返します。現在の《放假办法》を過去にさかのぼって外挿すると、存在しなかった履歴を作り出してしまいます（清明節・端午節・中秋節が法定祝日になったのは 2008 年からで、春節の休みが除夕から初三までとなったのは 2025 年からです）。

検証方法 / 验证方式

tools/gen_fixtures.py と tools/gen_solar_terms.py は、独立した 2 つの参照実装（sxtwl、lunar_python）から fixtures/lunar-1900-2100.json（73,384 行）を生成します。テストスイートはすべての行について、双方向の変換を検証します。2 つの参照実装で結果が異なるものは fixtures/lunar-disagreements.json に記録し、手作業で判定します（NOTES.md を参照）。すべての行が 100% 合格しない限り、リリースは行われません。

npm install
npm test                 # Node only

# the full release gate: build + tsc + tests + the CN cross-check
python3 -m pip install -r tools/requirements.txt   # one pure-Python package
npm run check

npm run check の最終ステップでは、CN.json を chinesecalendar と日ごとに照合します。そのパッケージが見つからない場合は、検証をスキップせず、明確に失敗します。未検証のテーブルが検査に合格したように見えてはなりません。

ロードマップ / 路線図

• Lunar コアと1900～2100年のフィクスチャ
• 24節気の正確な時刻（2つの参照値は55秒以内で一致します。リリース前に紫金山天文台の公開値と抜き取り照合します）
• 2024～2026年の中国の公式祝日（振替出勤日を含む）。chinesecalendar と日ごとに照合済み。それ以降の年は、旧暦・節気の規則に基づいて法定休日を predicted として推定します（将来の年のみを対象とし、過去の年を推測することはありません）
• HK/MO/TW/JP/KR/VN/SG/US/GB/DE/FR の2024～2028年の祝日を baseline として収録（python-holidays の規則）。旧正月の日付は独自の旧暦テーブルと照合済み
• 地域のタイムゾーン（Intl による DST 対応）により、JP/KR/EU では各地域のタイムゾーンで節気の日を判定します。地域階層（US-CA、DE-BY、GB-SCT、差分として70以上の下位地域を収録）、祝日の kind（public/federal/bank/substitute）、previousWorkday / addWorkdays / workdayCount / holidaysBetween / isHolidayEve / nextLongWeekend、月・時の干支、nextLunarDate（旧暦の誕生日）、MCP 用の zh/en による一文出力 describe()
• dateContext() による1回の呼び出しで使える API、標準日付入力、信頼度レベル、en と zh-Hans を必ず含む BCP-47 名称、地域をまたいだ標準的な祭日 ID、データバージョンのメタデータ、available: false の場合も適切に処理
• 各年の官報と照合し、baseline 地域を年ごとに official に更新（まず TW の補班、HK の官報、KR の振替休日に対応）
• Wikipedia の「今日は何の日」（CC BY-SA、項目ごとに出典を明記）
• @icyn/date npm パッケージ（esbuild ESM、地域ごとのエントリポイント、d.ts）・@icyn/date-mcp MCP サーバー（11個のツール、stdio、エンドツーエンドのスモークテスト済み）
• icyndate pip パッケージ（同一のテストベクトル）
• ホスト型 API

リポジトリ構成 / ディレクトリ

docs/        product & technical plan（产品与技术方案）, worklog
fixtures/    reference test vectors (generated, committed)
tools/       fixture generators (Python, not shipped)
packages/core/  @icyn/date — the library
packages/mcp/   @icyn/date-mcp — MCP server

ライセンス

コードと派生した旧暦・節気テーブルには MIT ライセンスを適用します。中国以外の11地域の baseline 祝日テーブルは python-holidays（MIT）から派生しています。ライセンスは THIRD-PARTY-LICENSES に収録し、各生成ファイルに正確なバージョンを baseline_note として記録しています。その他のサードパーティーデータ（Wikipedia、政府の祝日告示）には、それぞれのライセンスが適用され、項目ごとに出典を明記しています。