bizdays-toolkit 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-16
+
+### Added
+
+- 規則の診断（サブパス `bizdays-toolkit/diagnose`）: `diagnoseCalendar(options)`・`diagnoseSchedule(options)`。例外を投げず、`{ severity, code, path, message, relatedPath? }` の配列を返す
+  - `error`: 作成で例外になる誤り（`code` は例外と同じ）。作成時は最初の 1 件で止まるが、診断ではすべて返す。祝日の提供元が返すデータは、対応年のすべての年を調べる（`invalid-provider-data`）
+  - `warning`: `unknown-option`（知らないキー。近い既知のキーを候補に挙げる）・`shadowed`（同じ種類の先の規則に完全に含まれる。`relatedPath` に先の規則）・`never-matches`（当てはまる日がない繰り返しの規則）・`out-of-range`（個別の日付が祝日の提供元の対応年の外）・`no-business-day`（営業日が 1 日もない設定）
+  - `info`: `redundant`（取り除いても結果が変わらない規則）
+- 型: `Diagnostic`・`DiagnosticSeverity`・`DiagnosticCode`・`KnownDiagnosticCode`
+
+### Removed
+
+- `HolidayRule` 型（0.4.0 で非推奨）: `HolidayValueRule` を使う
+
+### 開発
+
+- 診断の性質のテスト（`test/diagnose-properties.test.ts`）: 使われない・取り除いても変わらないと診断した規則を実際に取り除き、結果が変わらないことを乱数の設定で確かめる
+- サイズの上限に `./diagnose` を追加
+- `docs/decisions.md` に 15 番目（規則の診断の設計）を追加
+
+## [0.4.0] - 2026-10-15
+
+### Added
+
+- 繰り返しの規則: 毎週（`{ weekday }`）・毎月の第 n 曜日（`{ weekday, nth }`。`nth` は 1〜5 と -1（最終））・毎月の日（`{ day }`。`day` は 1〜31 と -1（末日））。どれにも月の絞り込み（`months`）を付けられる。営業日カレンダーの `closedRecurring`・`openRecurring`、スケジュールの `recurring`
+- 祝日に当たったときの扱いを規則ごとに選ぶ `onHolidayRule`: `"under-holiday"`（祝日の扱いに従う。既定）・`"over-holiday"`（祝日でも当てはめる）・`"after-holiday"`（祝日でない翌日に振り替える。「月曜休館（祝日の場合は翌平日）」など）
+- `dayInfo()` の `shiftedFrom`: 振替で決まった日の、振替の元の日付
+- 判定の理由に `"recurring"`（スケジュール）・`"open-recurring"`・`"closed-recurring"`（営業日カレンダー）を追加
+- 型: `RecurringRule`・`RecurringValue`・`RecurringPattern`・`WeekdayPattern`・`DayOfMonthPattern`・`OnHolidayRule`・`Nth`・`DayOfMonth`・`Month`・`HolidayValueRule`
+
+### Deprecated
+
+- `HolidayRule` 型: `HolidayValueRule` に改名した（繰り返しの規則の `onHolidayRule` と紛れないため）。旧名は同じ型の別名として残し、次以降のマイナー版で削除する
+
+### 開発
+
+- 性能の計測（`pnpm bench`、依存なし）を追加
+- README に繰り返しの規則の節と、よくある設定の例（国民の休日を営業日として扱う、共通の設定から店舗ごとのカレンダーを作る）を追加。`docs/decisions.md` に 12〜14 番目（判定の順番を固定する理由、「第 n 何曜日」の定義、振替先の定義）を追加
+
 ## [0.3.1] - 2026-10-15
 
 ライブラリのコード・公開する API・祝日データに変更はありません。開発の検査を強めた版です。
@@ -90,7 +129,9 @@
 
 - 日本: 2026 年 2 月の官報（2027 年の春分・秋分の日）まで反映（`dataVersion: "2026-02"`、`confirmedThrough: 2027`）
 
-[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.1.2...v0.2.0

package/README.md

@@ -17,10 +17,12 @@
 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダーです。
 
 - **日本の祝日を内閣府のデータで全日照合**: 1955 年〜官報公表済みの年まで、内閣府「国民の祝日」CSV のすべての日付と一致することをテストで確かめています（振替休日・国民の休日・皇室行事による休日・五輪特措法による移動を含む）
+- **繰り返しの規則**: 「第 3 水曜定休」「毎月末日は棚卸」「月曜休館（祝日の場合は翌平日）」のような規則を、祝日に当たったときの扱い（祝日に従う・祝日でも当てはめる・翌日に振り替える）とあわせて指定できます
 - **日ごとの値（営業時間など）**: 「火曜定休、祝日は日曜の営業時間、元日は休業、大晦日は短縮営業」のように、曜日・祝日・特定日で変わる値を同じ規則で引けます
+- **設定の診断**: `bizdays-toolkit/diagnose` の `diagnoseCalendar`・`diagnoseSchedule` が、決して使われない規則・取り除いても結果が変わらない規則・キーの打ち間違い・営業日が 1 日もない設定などを、例外を投げずに一覧で返します。テストに 1 行足せば、設定の変更で規則が死んでいないかを確かめられます
 - **営業日の計算**: 定休日の曜日・毎年の休業日（年末年始のような年をまたぐ期間も可）・臨時休業日・臨時営業日と祝日を組み合わせ、「N 営業日後」「締め時刻を過ぎたら翌営業日」などを計算します
 - **タイムゾーンを間違えない**: `Date` などの瞬間は、カレンダーのタイムゾーン（日本は `Asia/Tokyo`）で暦日に変換してから判定します。UTC で動くサーバーでも、日本時間 0〜9 時が前日扱いになりません
-- **軽量・依存ゼロ**: minify + gzip で約 5.5KB（日本の祝日込みで約 7KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
+- **軽量・依存ゼロ**: minify + gzip で約 6.5KB（日本の祝日込みで約 7.5KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
 - **他の国・地域に拡張できる**: 祝日の提供元はインターフェース（`HolidayProvider`）で差し替えられます。現在は日本のみ同梱しています
 
 [English](#english)
@@ -84,9 +86,96 @@ shipping.dayInfo("2027-01-01");
 1. `openDates`（臨時営業日）
 2. `closedDates`（臨時休業日）
 3. `closedAnnual`（毎年の休業日）
-4. 祝日（`holidayPolicy` に従う。`"open"` は定休日の曜日より優先して営業日にする）
-5. `closedWeekdays`（定休日の曜日）
-6. それ以外は営業日
+4. `openRecurring`・`closedRecurring` のうち `onHolidayRule: "over-holiday"` の規則（祝日でも当てはめる）
+5. 祝日（`holidayPolicy` に従う。`"open"` は定休日の曜日より優先して営業日にする）
+6. `openRecurring`・`closedRecurring`（既定の `"under-holiday"` と、`"after-holiday"` の振替先）
+7. `closedWeekdays`（定休日の曜日）
+8. それ以外は営業日
+
+この順番は固定です。繰り返しの規則と祝日の関係だけは、規則ごとに `onHolidayRule` で選べます（次の節）。
+
+### 繰り返しの規則（毎週・毎月の第 n 曜日・毎月の日）
+
+「第 3 水曜定休」「第 2・第 4 土曜休業」「毎月末日は棚卸」「月曜休館（祝日の場合は翌平日）」のような繰り返しの休業日・営業日は、`closedRecurring`・`openRecurring` で指定します。
+
+```ts
+const museum = createCalendar({
+  holidays: jp,
+  holidayPolicy: "open", // 祝日は開館
+  closedRecurring: [
+    { weekday: 1, name: "月曜休館", onHolidayRule: "after-holiday" }, // 祝日の場合は翌平日に休館
+    { weekday: 3, nth: 3, months: [2, 8], name: "2 月・8 月の第 3 水曜は臨時休館" },
+    { day: -1, name: "月末棚卸", onHolidayRule: "over-holiday" }, // 祝日でも休館
+  ],
+});
+
+museum.isBusinessDay("2026-10-12"); // true（スポーツの日の月曜は開館）
+museum.dayInfo("2026-10-13");
+// { date: "2026-10-13", weekday: 2, businessDay: false, reason: "closed-recurring",
+//   name: "月曜休館", shiftedFrom: "2026-10-12" }
+```
+
+| 書き方                   | 意味                                                                            |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `{ weekday: 1 }`         | 毎週月曜日                                                                      |
+| `{ weekday: 3, nth: 3 }` | 第 3 水曜日。`nth` は 1〜5 と -1（最終）。`[2, 4]` のように配列で複数指定できる |
+| `{ day: 20 }`            | 毎月 20 日。`day` は 1〜31 と -1（末日）。配列で複数指定できる                  |
+| `months: [8, 12]`        | どの書き方にも付けられる、月の絞り込み                                          |
+
+- **第 n 何曜日**は「その月で n 回目のその曜日」です（1〜7 日が第 1）。カレンダーの第 n 週の行にある曜日ではありません
+- **その月にない日**（`nth: 5` がない月、`day: 31` がない月）は当てはまりません。末日は `day: -1` で指定します
+- 繰り返しの規則どうしは配列で先に書いたものが優先で、`openRecurring` は `closedRecurring` より優先です
+
+**祝日に当たったときの扱い**（`onHolidayRule`）は、規則ごとに選べます。
+
+| 値                        | 意味                                                     | 店舗の告知での書き方                  |
+| ------------------------- | -------------------------------------------------------- | ------------------------------------- |
+| `"under-holiday"`（既定） | 祝日の下。祝日の扱い（`holidayPolicy`）に従う            | 「第 3 水曜定休（祝日の場合は営業）」 |
+| `"over-holiday"`          | 祝日の上。祝日でも当てはめる                             | 「第 3 水曜定休（祝日も休み）」       |
+| `"after-holiday"`         | 祝日の後。祝日には当てはめず、祝日でない翌日に振り替える | 「月曜休館（祝日の場合は翌平日）」    |
+
+- `"under-holiday"` の規則は、`holidayPolicy: "ignore"`（祝日を判定に使わない）なら祝日にも当てはまります
+- `"after-holiday"` の振替先は「その日以降で最初の祝日でない日」です。祝日が続く場合（GW など）は連休が明けた日になります。振替先の日に臨時営業日・臨時休業日・毎年の休業日があれば、そちらが優先です。振替で決まった日の `dayInfo()` には、振替の元の日付 `shiftedFrom` が付きます
+- 振替の判断に使う「祝日」は、祝日の提供元（`jp` など）の祝日だけです（毎年の休業日などは含みません）
+
+スケジュールでは、同じ書き方の規則に `value` を付けて `recurring` に指定します。
+
+```ts
+const hours = createSchedule<Hours>({
+  holidays: jp,
+  weekly: [sunday, weekday, weekday, weekday, weekday, weekday, weekday],
+  recurring: [
+    { weekday: 1, value: null, name: "月曜休業", onHolidayRule: "after-holiday" },
+    { day: -1, value: { open: "10:00", close: "17:00" }, name: "月末は短縮営業" },
+  ],
+});
+```
+
+### よくある設定の例
+
+**国民の休日（祝日に挟まれた日）を営業日として扱う**：祝日の提供元を包んで、種別で除外します。
+
+```ts
+import { jp } from "bizdays-toolkit/jp";
+
+const jpWithoutCitizensHoliday = {
+  ...jp,
+  holidaysInYear: (year: number) => jp.holidaysInYear(year).filter((h) => h.kind !== "citizens"),
+};
+const calendar = createCalendar({ holidays: jpWithoutCitizensHoliday, closedWeekdays: [0, 6] });
+```
+
+**共通の設定から店舗ごとのカレンダーを作る**：設定は普通のオブジェクトなので、展開して足します。
+
+```ts
+const base = {
+  holidays: jp,
+  closedWeekdays: [0],
+  closedAnnual: [{ from: "12-31", to: "01-03" }],
+} as const;
+const shibuya = createCalendar({ ...base, openDates: ["2026-12-27"] });
+const yokohama = createCalendar({ ...base, closedRecurring: [{ weekday: 3, nth: 3 }] });
+```
 
 ### 日ごとの値（営業時間など）
 
@@ -113,7 +202,7 @@ storeHours.dayInfo("2027-01-01");
 // { date: "2027-01-01", weekday: 5, value: null, reason: "annual", name: "元日休業", holiday: {…} }
 ```
 
-値は `dates`（個別の日付・期間）→ `annual`（毎年の月日・期間）→ 祝日 → `weekly`（曜日）の順に決まります。同じ種類の規則が重なる場合は、配列で先に書いたものが優先です。
+値は `dates`（個別の日付・期間）→ `annual`（毎年の月日・期間）→ `recurring`（`"over-holiday"`）→ 祝日 → `recurring`（既定・振替先）→ `weekly`（曜日）の順に決まります。同じ種類の規則が重なる場合は、配列で先に書いたものが優先です。
 
 「今、営業時間内か」のような時刻の範囲の判定は、業種ごとの決まり（深夜をまたぐ営業、休憩時間など）があるためライブラリでは行いません。`civilOf` でタイムゾーンでの暦日と時刻を取り出せば、アプリ側で簡単に書けます。
 
@@ -187,6 +276,64 @@ try {
 
 主なコード: `invalid-date`・`invalid-month-day`・`invalid-time`・`invalid-range`・`invalid-weekday`・`invalid-time-zone`・`invalid-option`・`out-of-range`・`invalid-provider`・`invalid-provider-data`・`no-business-day`。将来の版でコードが増えることがあります。
 
+### 設定の診断
+
+`bizdays-toolkit/diagnose` の `diagnoseCalendar`・`diagnoseSchedule` は、設定を調べて問題を一覧で返します。例外は投げません（問題がなければ空の配列）。
+
+```ts
+import { diagnoseCalendar } from "bizdays-toolkit/diagnose";
+import { jp } from "bizdays-toolkit/jp";
+
+diagnoseCalendar({
+  holidays: jp,
+  closedWeekdays: [0],
+  closedRecurring: [
+    { weekday: 3, nth: 3, name: "第 3 水曜定休" },
+    { weekday: 3, nth: 3, months: [8], name: "8 月の第 3 水曜" }, // 先の規則に含まれる
+    { weekday: 0, name: "日曜休み" }, // 定休日の曜日と同じ
+  ],
+  closedDates: ["2100-01-05"], // 日本の祝日の対応年（1955〜2099 年）の外
+  closeAnnual: ["12-31"], // 打ち間違い
+});
+// [
+//   { severity: "warning", code: "unknown-option", path: "closeAnnual", message: '… (did you mean "closedAnnual"?)' },
+//   { severity: "warning", code: "out-of-range", path: "closedDates[0]", relatedPath: "holidays", message: "…" },
+//   { severity: "warning", code: "shadowed", path: "closedRecurring[1]", relatedPath: "closedRecurring[0]", message: "…" },
+//   { severity: "info", code: "redundant", path: "closedRecurring[2]", message: "…" },
+// ]
+```
+
+| 重さ（`severity`） | `code`                  | 内容                                                                                                                       |
+| ------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `error`            | 例外と同じコード        | `createCalendar`・`createSchedule` で例外になる誤り。作成時は最初の 1 件で止まりますが、診断ではすべて返します             |
+| `error`            | `invalid-provider-data` | 祝日の提供元が返したデータの誤り。作成時は使った年だけを調べますが、診断では対応年のすべての年を調べます                   |
+| `warning`          | `unknown-option`        | 知らないキー（作成時は無視されます）。近い既知のキーがあれば `message` に候補を挙げます                                    |
+| `warning`          | `shadowed`              | 同じ種類の先の規則（`relatedPath`）に完全に含まれ、決して使われない規則                                                    |
+| `warning`          | `never-matches`         | 当てはまる日がない繰り返しの規則（`{ day: 30, months: [2] }` など）                                                        |
+| `warning`          | `out-of-range`          | 個別の日付が祝日の提供元（`relatedPath`）の対応年の外                                                                      |
+| `warning`          | `no-business-day`       | 営業日が 1 日もない設定（営業日カレンダーのみ。営業日を探すと例外になります）                                              |
+| `info`             | `redundant`             | 取り除いても結果が変わらない規則（先の規則の組み合わせに覆われる、定休日の曜日と同じ、スケジュールで曜日の値と同じ値など） |
+
+- 判定には `code` を使ってください。`message` は英語で、文言は変わることがあります。`code` は将来の版で増えることがあります
+- `error` があるときは、規則どうしの診断（`shadowed`・`redundant` など）は行いません
+- `shadowed` は同じ種類の規則どうし（個別の日付どうし、毎年の月日どうし、繰り返しの規則どうし）だけを調べます。判定の順番は固定なので、種類をまたいで使われない規則は `redundant` として見つかります。臨時営業日（`openDates`）と臨時休業日（`closedDates`）は同じ種類で、先の臨時営業日に含まれる臨時休業日は `shadowed` です
+- 繰り返しの規則の `shadowed` は、祝日の扱い（`onHolidayRule`）も見ます。たとえば `"under-holiday"` の規則は、同じ日に当たる `"over-holiday"` の規則を覆いません（祝日には後の規則が当たるため）
+- `redundant` は、規則を取り除いた結果と 1 日ずつ比べます。個別の日付はその期間を、毎年の月日と繰り返しの規則は個別の日付を除いた設定で、祝日の提供元の対応年（日本は 1955〜2099 年）を、提供元がなければ 2001〜2028 年（曜日と月日の組み合わせが一巡する 28 年）を調べます。スケジュールの値は、配列と普通のオブジェクトなら中身で、それ以外（`Date` など）は同じものかで比べます
+- 日本の祝日を使う設定では、全日を調べるため数百ミリ秒かかります。リクエストごとではなく、テストや起動時の確認で使ってください。開発・テスト用の道具なので、アプリの本体のバンドルに入らないようサブパスに分けています
+
+テストで設定を守る例:
+
+```ts
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { diagnoseCalendar } from "bizdays-toolkit/diagnose";
+import { shippingOptions } from "../src/calendar.ts";
+
+test("出荷カレンダーの設定に問題がない", () => {
+  assert.deepEqual(diagnoseCalendar(shippingOptions), []);
+});
+```
+
 ## バージョン番号とデータの更新
 
 [Semantic Versioning](https://semver.org/lang/ja/) に従います。詳しくは [RELEASING.md](./RELEASING.md) を参照してください。
@@ -195,7 +342,7 @@ try {
 - 祝日の判定結果を固定したい場合は、版を完全一致で指定してください（例: `"bizdays-toolkit": "0.1.0"`）
 - 反映済みのデータは `dataVersion`（日本は反映済みの官報の年月）と `confirmedThrough` で確認できます
 - 1.0.0 までは、マイナー版で破壊的変更を行うことがあります
-- 判定の理由（`reason`）・祝日の種別（`kind`）・エラーコードは、将来の版で値が増えることがあります。値を列挙して分岐するときは「その他」も扱ってください（[RELEASING.md](./RELEASING.md) の「互換性の約束」）
+- 判定の理由（`reason`）・祝日の種別（`kind`）・エラーコード・診断のコードは、将来の版で値が増えることがあります。値を列挙して分岐するときは「その他」も扱ってください（[RELEASING.md](./RELEASING.md) の「互換性の約束」）
 
 ## 出典
 
@@ -213,9 +360,11 @@ A business-day calendar that combines public holidays with company or store clos
 
 - **Japanese holidays verified day by day** against the Cabinet Office CSV, from 1955 through the latest year officially announced (substitute holidays, citizens' holidays, imperial ceremonies, and the Olympic moves included)
 - **Day-by-day schedules**: `createSchedule` returns any value per day (e.g. store hours) from weekly values, a holiday rule (`"weekday"`, `{ sameAs: 0 }`, or `{ value }`), annual dates and specific dates
+- **Recurring rules**: weekly, nth-weekday-of-month (`{ weekday: 3, nth: 3 }`) and day-of-month (`{ day: -1 }`) rules, with per-rule holiday handling (`onHolidayRule`: `"under-holiday"`, `"over-holiday"`, or `"after-holiday"` to move the rule to the next non-holiday, e.g. "closed on Mondays; if Monday is a holiday, closed on the next weekday")
+- **Option diagnostics**: `diagnoseCalendar` / `diagnoseSchedule` from `bizdays-toolkit/diagnose` return a list of problems without throwing: rules that can never apply (`shadowed`, `never-matches`), rules whose removal changes nothing (`redundant`), typos in option keys with a suggestion (`unknown-option`), dates outside the holiday provider's years (`out-of-range`), and calendars with no business day. Use `code` to branch; `message` is for humans
 - **Business-day arithmetic**: closed weekdays, annual closures (including ranges across the new year), specific closed/open dates, holiday policy, `addBusinessDays`, cut-off times, and more
 - **Time-zone safe**: instants (`Date`, ISO strings with offsets, Temporal) are converted to a civil date in the calendar's time zone before evaluation
-- **Lightweight, zero dependencies**: about 5.5 KB min+gzip (about 7 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
+- **Lightweight, zero dependencies**: about 6.5 KB min+gzip (about 7.5 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
 - **Extensible** through the `HolidayProvider` interface (only Japan is bundled for now)
 
 ```ts

package/dist/core/calendar.d.ts

@@ -5,16 +5,21 @@
  *   1. openDates      … 臨時営業日（個別の日付・期間）
  *   2. closedDates    … 臨時休業日（個別の日付・期間）
  *   3. closedAnnual   … 毎年の休業日（月日・月日の期間。年をまたぐ期間も可）
- *   4. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
- *   5. closedWeekdays … 定休日の曜日
- *   6. それ以外は営業日
+ *   4. openRecurring・closedRecurring（onHolidayRule: "over-holiday"）… 祝日でも当てはめる繰り返しの規則
+ *   5. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
+ *   6. openRecurring・closedRecurring（"under-holiday"・"after-holiday" の振替先）… 繰り返しの規則
+ *   7. closedWeekdays … 定休日の曜日
+ *   8. それ以外は営業日
+ *
+ * 繰り返しの規則は openRecurring が closedRecurring より優先。"after-holiday" の規則は、
+ * 祝日には当てはめず、その日以降で最初の祝日でない日に当てはめる（振替）
  *
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
 import { type DateString, type Weekday } from "./date.ts";
 import { IssueCollector } from "./errors.ts";
 import { type DateInput } from "./input.ts";
-import { type CompiledSchedule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
+import { type CompiledSchedule, type RecurringRule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
 import type { Holiday } from "./types.ts";
 /**
  * 祝日の扱い。
@@ -68,6 +73,13 @@ export interface CalendarOptions<Kind extends string = string> extends HolidaySo
     readonly closedDates?: readonly (SpecificDate | DateRange)[];
     /** 臨時営業日（ほかのすべての規則より優先） */
     readonly openDates?: readonly (SpecificDate | DateRange)[];
+    /**
+     * 繰り返しの休業日（毎週・毎月の第 n 曜日・毎月の日）。
+     * 祝日に当たったときの扱いは規則ごとに onHolidayRule で指定する（既定: "under-holiday"）
+     */
+    readonly closedRecurring?: readonly RecurringRule[];
+    /** 繰り返しの営業日。closedRecurring と同じ日に当たる場合はこちらが優先 */
+    readonly openRecurring?: readonly RecurringRule[];
     /** 祝日の扱い（既定: "closed"） */
     readonly holidayPolicy?: HolidayPolicy;
     /** 営業日を探すときに調べる最大日数（既定: 3660）。超えたら Error */
@@ -77,7 +89,7 @@ export interface CalendarOptions<Kind extends string = string> extends HolidaySo
  * 営業・休業を決めた規則（既知の値）。
  * @public
  */
-export type KnownDayReason = "open-date" | "closed-date" | "closed-annual" | "holiday" | "closed-weekday" | "regular";
+export type KnownDayReason = "open-date" | "closed-date" | "closed-annual" | "open-recurring" | "closed-recurring" | "holiday" | "closed-weekday" | "regular";
 /**
  * 営業・休業を決めた規則。将来の版で値が増えることがあるので、分岐では「その他」も扱うこと。
  * すべての値を網羅したことを型で確かめたい場合は KnownDayReason を使う。
@@ -98,6 +110,8 @@ export interface DayInfo<Kind extends string = string> {
     readonly name?: string;
     /** その日が祝日なら祝日（holidayPolicy に関係なく付く） */
     readonly holiday?: Holiday<Kind>;
+    /** 祝日から振り替えられた繰り返しの規則で決まった場合、振替の元の日付（onHolidayRule: "after-holiday"） */
+    readonly shiftedFrom?: DateString;
 }
 /**
  * 営業日を探すときのオプション。

package/dist/core/calendar.js

@@ -5,16 +5,21 @@
  *   1. openDates      … 臨時営業日（個別の日付・期間）
  *   2. closedDates    … 臨時休業日（個別の日付・期間）
  *   3. closedAnnual   … 毎年の休業日（月日・月日の期間。年をまたぐ期間も可）
- *   4. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
- *   5. closedWeekdays … 定休日の曜日
- *   6. それ以外は営業日
+ *   4. openRecurring・closedRecurring（onHolidayRule: "over-holiday"）… 祝日でも当てはめる繰り返しの規則
+ *   5. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
+ *   6. openRecurring・closedRecurring（"under-holiday"・"after-holiday" の振替先）… 繰り返しの規則
+ *   7. closedWeekdays … 定休日の曜日
+ *   8. それ以外は営業日
+ *
+ * 繰り返しの規則は openRecurring が closedRecurring より優先。"after-holiday" の規則は、
+ * 祝日には当てはめず、その日以降で最初の祝日でない日に当てはめる（振替）
  *
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
 import { addDays, fromDayNumber, toDayNumber } from "./date.js";
 import { checkUnknownKeys, IssueCollector, plainError, rangeError } from "./errors.js";
 import { parseTimeOfDay, toCivil } from "./input.js";
-import { buildSchedule, compileAnnualRules, compileDateRules, compileHolidaySource, isWeekday, } from "./schedule.js";
+import { buildSchedule, compileAnnualRules, compileDateRules, compileHolidaySource, compileRecurringRules, isWeekday, RECURRING_RULE_KEYS, } from "./schedule.js";
 const CALENDAR_OPTION_KEYS = [
     "holidays",
     "timeZone",
@@ -23,6 +28,8 @@ const CALENDAR_OPTION_KEYS = [
     "closedAnnual",
     "closedDates",
     "openDates",
+    "closedRecurring",
+    "openRecurring",
     "holidayPolicy",
     "maxSearchDays",
 ];
@@ -61,6 +68,8 @@ export function compileCalendarOptions(c, options) {
     const annual = compileAnnualRules(c, "closedAnnual", o["closedAnnual"], () => false, true);
     const open = compileDateRules(c, "openDates", o["openDates"], () => true, true);
     const closed = compileDateRules(c, "closedDates", o["closedDates"], () => false, true);
+    const openRecurring = compileRecurringRules(c, "openRecurring", o["openRecurring"], () => true, RECURRING_RULE_KEYS);
+    const closedRecurring = compileRecurringRules(c, "closedRecurring", o["closedRecurring"], () => false, RECURRING_RULE_KEYS);
     return {
         schedule: {
             source,
@@ -69,6 +78,8 @@ export function compileCalendarOptions(c, options) {
             annual,
             // 臨時営業日を先に並べて、臨時休業日より優先する
             dates: [...open, ...closed],
+            // 繰り返しの営業日を先に並べて、繰り返しの休業日より優先する
+            recurring: [...openRecurring, ...closedRecurring],
         },
         maxSearchDays: Number.isInteger(maxSearchDays) ? maxSearchDays : 3660,
     };
@@ -98,6 +109,9 @@ export function createCalendar(options = {}) {
             case "annual":
                 reason = "closed-annual";
                 break;
+            case "recurring":
+                reason = day.value ? "open-recurring" : "closed-recurring";
+                break;
             case "holiday":
                 reason = "holiday";
                 break;
@@ -120,6 +134,8 @@ export function createCalendar(options = {}) {
             result.name = day.name;
         if (day.holiday !== undefined)
             result.holiday = day.holiday;
+        if (day.shiftedFrom !== undefined)
+            result.shiftedFrom = day.shiftedFrom;
         return Object.freeze(result);
     }
     const isOpen = (date) => schedule.valueOn(date);

package/dist/core/diagnose.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 規則の診断（diagnoseCalendar・diagnoseSchedule）。
+ *
+ * 設定を作るときと同じ検証（IssueCollector）で誤りと知らないキーを集め、誤りがなければ
+ * 規則どうしの関係を調べる。例外は投げず、見つけた問題を配列で返す。
+ *
+ * - error   … createCalendar・createSchedule で例外になる誤り（code は例外と同じ）
+ * - warning … 作れるが、意図と違う可能性が高いもの
+ *     unknown-option … 知らないキー（作成時は無視される）。近い既知のキーがあれば message に候補を挙げる
+ *     shadowed       … 同じ種類の先の規則に完全に覆われ、決して使われない（relatedPath に先の規則）
+ *     never-matches  … 当てはまる日がない繰り返しの規則（2 月 30 日など）
+ *     out-of-range   … 個別の日付が祝日の提供元の対応年の外にある（relatedPath に提供元）
+ *     no-business-day … 営業日が 1 日もない設定（営業日カレンダーのみ）
+ * - info    … redundant: 取り除いても結果が変わらない規則
+ *
+ * 判定の順番（個別の日付 → 毎年の月日 → 繰り返し（over）→ 祝日 → 繰り返し（under・振替先）→ 曜日）は
+ * 固定なので、shadowed は同じ種類の規則どうしに限って調べる。種類をまたいで使われない規則は
+ * redundant（取り除いても結果が変わらない）として見つかる。
+ */
+import { type CalendarOptions } from "./calendar.ts";
+import { type KnownErrorCode } from "./errors.ts";
+import { type ScheduleOptions } from "./schedule.ts";
+/**
+ * 診断の重さ。
+ * - "error": 作成すると例外になる誤り
+ * - "warning": 作れるが、意図と違う可能性が高い
+ * - "info": 結果には影響しないが、整理できる
+ *
+ * 出力の列挙だが、重さの段階は増やさないため閉じた型にしている（docs/decisions.md の 15）。
+ * @public
+ */
+export type DiagnosticSeverity = "error" | "warning" | "info";
+/**
+ * 既知の診断コード（増えることがある）。error の code は例外の code（KnownErrorCode）と同じ。
+ * @public
+ */
+export type KnownDiagnosticCode = KnownErrorCode
+/** 知らないキー（作成時は無視される） */
+ | "unknown-option"
+/** 同じ種類の先の規則に完全に覆われ、決して使われない */
+ | "shadowed"
+/** 当てはまる日がない繰り返しの規則 */
+ | "never-matches"
+/** 取り除いても結果が変わらない */
+ | "redundant";
+/**
+ * 診断コード。将来の版で値が増えることがあるので、分岐では「その他」も扱うこと。
+ * @public
+ */
+export type DiagnosticCode = KnownDiagnosticCode | (string & {});
+/**
+ * 診断の結果 1 件。message は英語で、文言は API に含まない（判定には code を使う）。
+ * @public
+ */
+export interface Diagnostic {
+    readonly severity: DiagnosticSeverity;
+    readonly code: DiagnosticCode;
+    /** 設定の中の位置（例: "closedRecurring[1]"・"closedDates[0].date"）。設定全体なら "" */
+    readonly path: string;
+    readonly message: string;
+    /** 関係する別の位置（shadowed では覆っている先の規則、out-of-range では祝日の提供元） */
+    readonly relatedPath?: string;
+}
+/**
+ * 営業日カレンダーの設定を診断する。例外は投げず、見つけた問題を返す（問題がなければ空の配列）。
+ *
+ * error があるときは、規則どうしの診断（shadowed・redundant など）は行わない。
+ * JavaScript から渡された型の合わない設定も受け付ける。
+ * @public
+ */
+export declare function diagnoseCalendar(options?: CalendarOptions | object): readonly Diagnostic[];
+/**
+ * スケジュールの設定を診断する。例外は投げず、見つけた問題を返す（問題がなければ空の配列）。
+ *
+ * 値が同じかは、配列と普通のオブジェクトは中身で、それ以外は Object.is で比べる。
+ * error があるときは、規則どうしの診断（shadowed・redundant など）は行わない。
+ * @public
+ */
+export declare function diagnoseSchedule(options: ScheduleOptions<unknown> | object): readonly Diagnostic[];