bizdays-toolkit 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,7 +4,46 @@
 
 ## [Unreleased]
 
-## [0.4.0] - 2026-10-16
+## [0.6.0] - 2026-10-16
+
+### Added
+
+- 日付の調整 `adjust(input, { convention })`（営業日カレンダー）: 休業日を `"following"`（翌営業日）・`"preceding"`（前営業日）・`"modified-following"`（翌営業日。月が変わるなら前営業日）・`"modified-preceding"`（前営業日。月が変わるなら翌営業日）で調整する。月が変わるかは調整する前の日付の月と比べる
+- 月の営業日（営業日カレンダー）: `nthBusinessDayOfMonth(month, n)`（負なら月末から数える。-1 は最終営業日）・`firstBusinessDayOfMonth(month)`・`lastBusinessDayOfMonth(month)`
+- 月の期日 `dueDate(month, { day, convention })`（営業日カレンダー）: その月の `day` 日（-1 は末日。その月にない日は末日に読み替える）を `convention` で調整する
+- 月の計算（ルート）: `monthOf(dateOrMonth, offset?)`（n か月後の月 `"YYYY-MM"`）・`closingMonth(date, closingDay)`（締め日で区切ったときの月）
+- 例外のコード `invalid-month`（月 `"YYYY-MM"` の誤り）
+- 型: `BusinessDayConvention`・`AdjustOptions`・`DueDateOptions`・`MonthString`
+
+### 開発
+
+- `pnpm check`（`scripts/check-package.ts`）で、CHANGELOG の版の節の並び・日付と、末尾のリンク定義が節とそろっていることを確かめるようにした（0.5.0 でリンク定義の更新漏れがあったため）
+- リリースのワークフローで、CHANGELOG の日付が `YYYY-MM-DD` のまま・見出しがないときの表示を分かりやすくした（止まる条件は変わらない）
+- 月の計算と日付の調整の性質のテストを追加
+- サイズの上限を上げた（`.` 16500・`./jp` 19500・`./diagnose` 22000。月の計算の追加。minify + gzip ではルートが約 7.2KB、日本の祝日込みで約 8.3KB）
+- `docs/decisions.md` に 16 番目（日付の調整と月の期日の設計）を追加
+
+## [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
 
@@ -109,7 +148,9 @@
 
 - 日本: 2026 年 2 月の官報（2027 年の春分・秋分の日）まで反映（`dataVersion: "2026-02"`、`confirmedThrough: 2027`）
 
-[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.5.0...v0.6.0
+[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

package/README.md

@@ -19,9 +19,11 @@
 - **日本の祝日を内閣府のデータで全日照合**: 1955 年〜官報公表済みの年まで、内閣府「国民の祝日」CSV のすべての日付と一致することをテストで確かめています（振替休日・国民の休日・皇室行事による休日・五輪特措法による移動を含む）
 - **繰り返しの規則**: 「第 3 水曜定休」「毎月末日は棚卸」「月曜休館（祝日の場合は翌平日）」のような規則を、祝日に当たったときの扱い（祝日に従う・祝日でも当てはめる・翌日に振り替える）とあわせて指定できます
 - **日ごとの値（営業時間など）**: 「火曜定休、祝日は日曜の営業時間、元日は休業、大晦日は短縮営業」のように、曜日・祝日・特定日で変わる値を同じ規則で引けます
+- **設定の診断**: `bizdays-toolkit/diagnose` の `diagnoseCalendar`・`diagnoseSchedule` が、決して使われない規則・取り除いても結果が変わらない規則・キーの打ち間違い・営業日が 1 日もない設定などを、例外を投げずに一覧で返します。テストに 1 行足せば、設定の変更で規則が死んでいないかを確かめられます
+- **月の期日**: 「20 日締め翌月 10 日払い（休業日なら翌営業日）」「月末の最終営業日」のような期日を、金融で使われる 4 つの調整方法（following・preceding・modified-following・modified-preceding）で計算します
 - **営業日の計算**: 定休日の曜日・毎年の休業日（年末年始のような年をまたぐ期間も可）・臨時休業日・臨時営業日と祝日を組み合わせ、「N 営業日後」「締め時刻を過ぎたら翌営業日」などを計算します
 - **タイムゾーンを間違えない**: `Date` などの瞬間は、カレンダーのタイムゾーン（日本は `Asia/Tokyo`）で暦日に変換してから判定します。UTC で動くサーバーでも、日本時間 0〜9 時が前日扱いになりません
-- **軽量・依存ゼロ**: minify + gzip で約 6.5KB（日本の祝日込みで約 7.5KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
+- **軽量・依存ゼロ**: minify + gzip で約 7KB（日本の祝日込みで約 8.3KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
 - **他の国・地域に拡張できる**: 祝日の提供元はインターフェース（`HolidayProvider`）で差し替えられます。現在は日本のみ同梱しています
 
 [English](#english)
@@ -176,6 +178,56 @@ const shibuya = createCalendar({ ...base, openDates: ["2026-12-27"] });
 const yokohama = createCalendar({ ...base, closedRecurring: [{ weekday: 3, nth: 3 }] });
 ```
 
+### 月の期日と日付の調整
+
+休業日に当たった日付を、指定した方法で営業日に調整します。月の第 n 営業日や、「毎月 n 日（休業日なら翌営業日）」のような期日も求められます。
+
+```ts
+import { closingMonth, createCalendar, monthOf } from "bizdays-toolkit";
+import { jp } from "bizdays-toolkit/jp";
+
+const calendar = createCalendar({
+  holidays: jp,
+  closedWeekdays: [0, 6],
+  closedAnnual: [{ from: "12-31", to: "01-03", name: "年末年始" }],
+});
+
+calendar.adjust("2026-10-31", { convention: "following" }); // "2026-11-02"（10/31 は土曜日）
+calendar.adjust("2026-10-31", { convention: "modified-following" }); // "2026-10-30"（月が変わるので前へ）
+
+calendar.firstBusinessDayOfMonth("2027-01"); // "2027-01-04"
+calendar.lastBusinessDayOfMonth("2026-12"); // "2026-12-30"
+calendar.nthBusinessDayOfMonth("2026-10", 5); // "2026-10-07"（-1 は最終、-2 は最後から 2 番目）
+
+// 毎月 10 日払い（休業日なら翌営業日）
+calendar.dueDate("2026-10", { day: 10, convention: "following" }); // "2026-10-13"（12 日はスポーツの日）
+
+// 20 日締め・翌月末払い（休業日なら前営業日）
+const billing = closingMonth("2026-10-21", 20); // "2026-11"（10/21〜11/20 が 11 月分）
+calendar.dueDate(monthOf(billing, 1), { day: -1, convention: "preceding" }); // "2026-12-30"
+```
+
+**調整の方法**（`convention`、必須）
+
+| 方法                   | 休業日のとき                           |
+| ---------------------- | -------------------------------------- |
+| `"following"`          | 翌営業日                               |
+| `"preceding"`          | 前営業日                               |
+| `"modified-following"` | 翌営業日。ただし月が変わるなら前営業日 |
+| `"modified-preceding"` | 前営業日。ただし月が変わるなら翌営業日 |
+
+- 営業日ならどの方法でもその日のままです
+- 月が変わるかは、**調整する前の日付の月**と比べます。`dueDate` では、末日に読み替えた後の日付の月です（例: 2 月の 31 日払いは 2 月末日を基準にし、`"modified-following"` なら 2 月の中で調整します）
+- `modified-…` で、同じ月に反対向きの営業日もない（その月が全部休業日）ときは、月が変わっても元の向きに調整します
+- 「最も近い営業日」（nearest）はありません。前後が同じ距離のときの決め方が業種ごとに違うためです
+
+**月の計算**（ルートの関数。営業日は考えません）
+
+- `monthOf(dateOrMonth, offset?)`: 日付または月 `"YYYY-MM"` の、`offset` か月後（負なら前）の月
+- `closingMonth(date, closingDay)`: 締め日（1〜31、`-1` は末日）で区切ったときに日付が属する月。締め日の翌日から次の締め日までを、次の締め日の月とします。締め日がその月にない日（31 日締めの 2 月など）は末日締めです
+
+`dueDate` の `day` も、その月にない日（2 月 30 日など）は末日に読み替えます。繰り返しの規則（`{ day: 31 }`）はその月にない日に当てはまらないので、扱いが異なります。期日は「その月のどこか」に必ず決まる必要があるためです。
+
 ### 日ごとの値（営業時間など）
 
 `createSchedule` は、曜日・祝日・特定日の規則から、日ごとに任意の値を返します。値の型は自由なので、営業時間のほか、受付枠や配送料の区分などにも使えます。
@@ -273,7 +325,65 @@ 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`。将来の版でコードが増えることがあります。
+主なコード: `invalid-date`・`invalid-month`・`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), []);
+});
+```
 
 ## バージョン番号とデータの更新
 
@@ -283,7 +393,7 @@ try {
 - 祝日の判定結果を固定したい場合は、版を完全一致で指定してください（例: `"bizdays-toolkit": "0.1.0"`）
 - 反映済みのデータは `dataVersion`（日本は反映済みの官報の年月）と `confirmedThrough` で確認できます
 - 1.0.0 までは、マイナー版で破壊的変更を行うことがあります
-- 判定の理由（`reason`）・祝日の種別（`kind`）・エラーコードは、将来の版で値が増えることがあります。値を列挙して分岐するときは「その他」も扱ってください（[RELEASING.md](./RELEASING.md) の「互換性の約束」）
+- 判定の理由（`reason`）・祝日の種別（`kind`）・エラーコード・診断のコードは、将来の版で値が増えることがあります。値を列挙して分岐するときは「その他」も扱ってください（[RELEASING.md](./RELEASING.md) の「互換性の約束」）
 
 ## 出典
 
@@ -302,9 +412,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
+- **Month-based due dates**: `adjust` with `following` / `preceding` / `modified-following` / `modified-preceding`, the nth / first / last business day of a month, `dueDate(month, { day, convention })`, and the calendar helpers `closingMonth` and `monthOf`
 - **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 6.5 KB min+gzip (about 7.5 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
+- **Lightweight, zero dependencies**: about 7 KB min+gzip (about 8.3 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

@@ -19,7 +19,8 @@
 import { type DateString, type Weekday } from "./date.ts";
 import { IssueCollector } from "./errors.ts";
 import { type DateInput } from "./input.ts";
-import { type CompiledSchedule, type RecurringRule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
+import { type MonthString } from "./month.ts";
+import { type CompiledSchedule, type DayOfMonth, type RecurringRule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
 import type { Holiday } from "./types.ts";
 /**
  * 祝日の扱い。
@@ -124,6 +125,35 @@ export interface BusinessDayOptions {
      */
     readonly cutoff?: string;
 }
+/**
+ * 休業日に当たった日付の調整の方法（営業日の慣行）。
+ * - "following": 翌営業日
+ * - "preceding": 前営業日
+ * - "modified-following": 翌営業日。ただし月が変わるなら前営業日
+ * - "modified-preceding": 前営業日。ただし月が変わるなら翌営業日
+ *
+ * 月が変わるかは、調整する前の日付の月と比べる。
+ * @public
+ */
+export type BusinessDayConvention = "following" | "preceding" | "modified-following" | "modified-preceding";
+/**
+ * 日付の調整のオプション。
+ * @public
+ */
+export interface AdjustOptions {
+    /** 調整の方法 */
+    readonly convention: BusinessDayConvention;
+}
+/**
+ * 月の期日のオプション。
+ * @public
+ */
+export interface DueDateOptions {
+    /** 期日の日（1〜31、-1 は末日）。その月にない日（2 月 30 日など）は末日に読み替える */
+    readonly day: DayOfMonth;
+    /** 期日が休業日のときの調整の方法 */
+    readonly convention: BusinessDayConvention;
+}
 /**
  * 営業日カレンダー。
  * @public
@@ -150,6 +180,25 @@ export interface Calendar<Kind extends string = string> extends HolidayLookup<Ki
     businessDaysBetween(from: DateInput, to: DateInput): number;
     /** 期間内の営業日（両端を含む） */
     listBusinessDays(from: DateInput, to: DateInput): readonly DateString[];
+    /**
+     * 営業日ならその日、休業日なら convention に従って調整した営業日。
+     * 月が変わるか（modified-…）は、調整する前の日付の月と比べる
+     */
+    adjust(input: DateInput, options: AdjustOptions): DateString;
+    /**
+     * 月 "YYYY-MM" の第 n 営業日。n が負なら月末から数える（-1 は最終営業日）。
+     * その月の営業日が足りなければ code: "no-business-day" の Error
+     */
+    nthBusinessDayOfMonth(month: MonthString, n: number): DateString;
+    /** 月 "YYYY-MM" の最初の営業日（nthBusinessDayOfMonth(month, 1)） */
+    firstBusinessDayOfMonth(month: MonthString): DateString;
+    /** 月 "YYYY-MM" の最後の営業日（nthBusinessDayOfMonth(month, -1)） */
+    lastBusinessDayOfMonth(month: MonthString): DateString;
+    /**
+     * 月 "YYYY-MM" の day 日を期日とし、休業日なら convention で調整した日。
+     * その月にない日は末日に読み替えてから調整する（例: 2 月の 30 日払いは 2 月末日）
+     */
+    dueDate(month: MonthString, options: DueDateOptions): DateString;
 }
 interface CompiledCalendar<Kind extends string> {
     readonly schedule: CompiledSchedule<boolean, Kind>;

package/dist/core/calendar.js

@@ -16,9 +16,10 @@
  *
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
-import { addDays, fromDayNumber, toDayNumber } from "./date.js";
+import { addDays, daysInMonth, formatDate, fromDayNumber, toDayNumber, } from "./date.js";
 import { checkUnknownKeys, IssueCollector, plainError, rangeError } from "./errors.js";
 import { parseTimeOfDay, toCivil } from "./input.js";
+import { dayOfMonth, isDayOfMonthValue, parseMonth } from "./month.js";
 import { buildSchedule, compileAnnualRules, compileDateRules, compileHolidaySource, compileRecurringRules, isWeekday, RECURRING_RULE_KEYS, } from "./schedule.js";
 const CALENDAR_OPTION_KEYS = [
     "holidays",
@@ -156,6 +157,74 @@ export function createCalendar(options = {}) {
                 count++;
         return count;
     }
+    const CONVENTIONS = [
+        "following",
+        "preceding",
+        "modified-following",
+        "modified-preceding",
+    ];
+    function adjustDate(date, options) {
+        const convention = options?.convention;
+        if (!CONVENTIONS.includes(convention)) {
+            throw rangeError("invalid-argument", `convention must be one of ${CONVENTIONS.map((v) => `"${v}"`).join(", ")}`);
+        }
+        if (isOpen(date))
+            return date;
+        const month = date.slice(0, 7);
+        switch (convention) {
+            case "following":
+                return search(date, 1);
+            case "preceding":
+                return search(date, -1);
+            case "modified-following": {
+                const next = search(date, 1);
+                if (next.startsWith(month))
+                    return next;
+                // 同じ月に前営業日がなければ、月が変わっても翌営業日にする
+                const previous = searchWithin(date, -1, month);
+                return previous ?? next;
+            }
+            case "modified-preceding": {
+                const previous = search(date, -1);
+                if (previous.startsWith(month))
+                    return previous;
+                const next = searchWithin(date, 1, month);
+                return next ?? previous;
+            }
+            default:
+                throw rangeError("invalid-argument", `Unknown convention: ${String(convention)}`);
+        }
+    }
+    /** 同じ月の中だけで営業日を探す（なければ undefined） */
+    function searchWithin(start, step, month) {
+        for (let date = start; date.startsWith(month); date = addDays(date, step)) {
+            if (isOpen(date))
+                return date;
+        }
+        return undefined;
+    }
+    /** 月の営業日（月初から順） */
+    function businessDaysOfMonth(month) {
+        const { year, month: m } = parseMonth(month);
+        const result = [];
+        for (let d = 1; d <= daysInMonth(year, m); d++) {
+            const date = formatDate(year, m, d);
+            if (isOpen(date))
+                result.push(date);
+        }
+        return result;
+    }
+    function nthOfMonth(month, n) {
+        if (!Number.isInteger(n) || n === 0) {
+            throw rangeError("invalid-argument", `n must be a non-zero integer: ${n}`);
+        }
+        const days = businessDaysOfMonth(month);
+        const found = n > 0 ? days[n - 1] : days[days.length + n];
+        if (found === undefined) {
+            throw plainError("no-business-day", `${month} has ${days.length} business day(s); requested ${n > 0 ? "" : "last "}#${Math.abs(n)}`);
+        }
+        return found;
+    }
     const calendar = {
         timeZone: schedule.timeZone,
         providers: schedule.providers,
@@ -211,6 +280,17 @@ export function createCalendar(options = {}) {
             }
             return Object.freeze(result);
         },
+        adjust: (input, options) => adjustDate(dateOf(input), options),
+        nthBusinessDayOfMonth: nthOfMonth,
+        firstBusinessDayOfMonth: (month) => nthOfMonth(month, 1),
+        lastBusinessDayOfMonth: (month) => nthOfMonth(month, -1),
+        dueDate(month, options) {
+            const day = options?.day;
+            if (!isDayOfMonthValue(day)) {
+                throw rangeError("invalid-argument", `day must be an integer from 1 to 31, or -1 (last day): ${String(day)}`);
+            }
+            return adjustDate(dayOfMonth(parseMonth(month), day), options);
+        },
     };
     return Object.freeze(calendar);
 }

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[];