bizdays-toolkit 0.4.0 → 0.6.0

package/dist/core/diagnose.js

@@ -0,0 +1,386 @@
+/**
+ * 規則の診断（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 { daysInMonth, fromDayNumber, parseDate, toDayNumber } from "./date.js";
+import { compileCalendarOptions } from "./calendar.js";
+import { IssueCollector } from "./errors.js";
+import { compileScheduleOptions, createHolidayLookup, createResolver, matchAnnual, matchRecurring, } from "./schedule.js";
+// ------------------------------------------------------------
+// 知らないキーの候補
+// ------------------------------------------------------------
+/** 2 つの文字列の編集距離（挿入・削除・置換・隣り合う 2 文字の入れ替えを 1 と数える） */
+function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let v = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                v = Math.min(v, d[i - 2][j - 2] + 1);
+            }
+            d[i][j] = v;
+        }
+    }
+    return d[a.length][b.length];
+}
+/**
+ * 知らないキーに近い既知のキーを返す（なければ undefined）。
+ * 大文字・小文字の違い、打ち間違い（編集距離が短いキーで 1・長いキーで 2〜3）、
+ * 既知のキーの先頭部分（4 文字以上）の順に探す
+ */
+function closestKey(key, known) {
+    const lower = key.toLowerCase();
+    const sameCase = known.find((k) => k.toLowerCase() === lower);
+    if (sameCase !== undefined)
+        return sameCase;
+    const limit = Math.max(1, Math.floor(key.length / 4));
+    let best;
+    let bestDistance = limit + 1;
+    for (const k of known) {
+        const distance = editDistance(lower, k.toLowerCase());
+        if (distance < bestDistance) {
+            best = k;
+            bestDistance = distance;
+        }
+    }
+    if (best !== undefined)
+        return best;
+    if (key.length >= 4)
+        return known.find((k) => k.toLowerCase().startsWith(lower));
+    return undefined;
+}
+// ------------------------------------------------------------
+// 調べる期間
+// ------------------------------------------------------------
+/** 繰り返しの規則の当てはまり方は、年の種類（1 月 1 日の曜日 × うるう年か）の 14 通りで決まる。28 年でそろう */
+const PATTERN_FROM = toDayNumber("2001-01-01");
+const PATTERN_TO = toDayNumber("2028-12-31");
+/** 祝日の提供元があるときに調べる年の上限（長すぎる対応年は 1900〜2099 年に絞る） */
+const MAX_WINDOW_YEARS = 200;
+/** 個別の日付の期間で、取り除いた結果と比べる最大日数 */
+const MAX_DATE_RULE_DAYS = 366 * MAX_WINDOW_YEARS;
+/** 長すぎる年の範囲を 1900〜2099 年（重ならなければ先頭の 200 年）に絞る */
+function clipYears(from, to) {
+    if (to - from + 1 <= MAX_WINDOW_YEARS)
+        return [from, to];
+    const a = Math.max(from, 1900);
+    const b = Math.min(to, 2099);
+    return a <= b ? [a, b] : [from, from + MAX_WINDOW_YEARS - 1];
+}
+/** 毎年の月日・繰り返しの規則を調べる期間（祝日が年ごとに変わるので、提供元の対応年を使う） */
+function scanWindow(source) {
+    if (source.providers.length === 0) {
+        return { from: PATTERN_FROM, to: PATTERN_TO, label: "2001-2028" };
+    }
+    const ranges = source.providers.map((p) => p.supportedYears);
+    let from;
+    let to;
+    if (source.outOfRange === "ignore") {
+        from = Math.min(...ranges.map((r) => r.from));
+        to = Math.max(...ranges.map((r) => r.to));
+    }
+    else {
+        from = Math.max(...ranges.map((r) => r.from));
+        to = Math.min(...ranges.map((r) => r.to));
+    }
+    if (from > to)
+        return undefined;
+    [from, to] = clipYears(from, to);
+    return {
+        from: toDayNumber(`${String(from).padStart(4, "0")}-01-01`),
+        to: toDayNumber(`${String(to).padStart(4, "0")}-12-31`),
+        label: `${from}-${to}`,
+    };
+}
+// ------------------------------------------------------------
+// 規則の当てはまる日（覆われているかの判定用）
+// ------------------------------------------------------------
+/** 繰り返しの規則が当てはまる日（代表の 28 年間）。祝日・振替は考えない */
+function recurringMatches(rule) {
+    const bits = new Uint8Array(PATTERN_TO - PATTERN_FROM + 1);
+    for (let n = PATTERN_FROM; n <= PATTERN_TO; n++) {
+        if (matchRecurring(rule, fromDayNumber(n)))
+            bits[n - PATTERN_FROM] = 1;
+    }
+    return bits;
+}
+/** 毎年の月日の規則が当てはまる月日（うるう年の 366 日） */
+const LEAP_MONTH_DAYS = (() => {
+    const list = [];
+    for (let m = 1; m <= 12; m++) {
+        for (let d = 1; d <= daysInMonth(2028, m); d++) {
+            list.push(`${String(m).padStart(2, "0")}-${String(d).padStart(2, "0")}`);
+        }
+    }
+    return list;
+})();
+function annualMatches(rule) {
+    return Uint8Array.from(LEAP_MONTH_DAYS, (md) => (matchAnnual(rule, md) ? 1 : 0));
+}
+const isEmpty = (bits) => bits.every((b) => b === 0);
+/** a が当てはまる日に、b もすべて当てはまるか（a ⊆ b） */
+const isSubset = (a, b) => a.every((v, i) => v === 0 || b[i] === 1);
+/**
+ * 先の繰り返しの規則 earlier が、後の規則 later を完全に覆えるか（祝日の扱いの組み合わせ）。
+ * - "over-holiday" の規則は、祝日でも先に当てはめる "over-holiday" の規則にしか覆われない
+ * - "under-holiday" の規則は、"over-holiday"・"under-holiday" の規則に覆われる
+ * - "after-holiday" の規則は、振替先まで同じになる "after-holiday" の規則にしか覆われない
+ */
+function canCover(earlier, later) {
+    switch (later.onHolidayRule) {
+        case "over-holiday":
+            return earlier.onHolidayRule === "over-holiday";
+        case "under-holiday":
+            return earlier.onHolidayRule !== "after-holiday";
+        case "after-holiday":
+            return earlier.onHolidayRule === "after-holiday";
+        default: {
+            const unreachable = later.onHolidayRule;
+            return unreachable;
+        }
+    }
+}
+// ------------------------------------------------------------
+// 値の比較（取り除いても結果が変わらないか）
+// ------------------------------------------------------------
+/** 値が同じか。配列と普通のオブジェクトは中身で比べ、それ以外は Object.is で比べる */
+function sameValue(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return (Array.isArray(a) &&
+            Array.isArray(b) &&
+            a.length === b.length &&
+            a.every((v, i) => sameValue(v, b[i])));
+    }
+    const plain = (o) => {
+        const proto = Object.getPrototypeOf(o);
+        return proto === Object.prototype || proto === null;
+    };
+    if (!plain(a) || !plain(b))
+        return false;
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return (ka.length === kb.length &&
+        ka.every((k) => Object.hasOwn(b, k) &&
+            sameValue(a[k], b[k])));
+}
+// ------------------------------------------------------------
+// 規則どうしの診断
+// ------------------------------------------------------------
+const yearOf = (dayNumber) => parseDate(fromDayNumber(dayNumber)).year;
+function without(compiled, rule, dropDates) {
+    return {
+        ...compiled,
+        dates: dropDates ? [] : compiled.dates.filter((r) => r !== rule),
+        annual: compiled.annual.filter((r) => r !== rule),
+        recurring: compiled.recurring.filter((r) => r !== rule),
+    };
+}
+/**
+ * 祝日の提供元が返すデータを、対応年（長すぎる場合は絞った範囲）のすべての年で検証する。
+ * 作成時は年ごとに初めて使うときに検証するので、使っていない年の誤りもここで見つける
+ */
+function checkProviderData(c, source) {
+    let ok = true;
+    source.providers.forEach((provider, i) => {
+        const path = source.providers.length === 1 ? "holidays" : `holidays[${i}]`;
+        const lookup = createHolidayLookup({ ...source, providers: [provider], outOfRange: "ignore" });
+        const [from, to] = clipYears(provider.supportedYears.from, provider.supportedYears.to);
+        try {
+            for (let y = from; y <= to; y++)
+                lookup.holidaysInYear(y);
+        }
+        catch (error) {
+            ok = false;
+            c.error("invalid-provider-data", path, error instanceof Error ? error.message : `Holiday provider threw ${String(error)}`);
+        }
+    });
+    return ok;
+}
+function analyze(c, compiled, isCalendar) {
+    const { source, dates, annual, recurring } = compiled;
+    if (!checkProviderData(c, source))
+        return;
+    const lookup = createHolidayLookup(source);
+    const window = scanWindow(source);
+    /** 使われないことが分かった規則（redundant を重ねて出さない） */
+    const unused = new Set();
+    // --- 個別の日付: 対応年の外・覆われている ---
+    dates.forEach((rule, j) => {
+        const fromYear = yearOf(rule.from);
+        const toYear = yearOf(rule.to);
+        source.providers.forEach((p, i) => {
+            const { from, to } = p.supportedYears;
+            if (fromYear >= from && toYear <= to)
+                return;
+            const related = source.providers.length === 1 ? "holidays" : `holidays[${i}]`;
+            c.warning("out-of-range", rule.path, `The date is outside the years supported by holiday provider ${p.id} (${from}-${to}); ` +
+                (source.outOfRange === "throw"
+                    ? "looking up this date throws"
+                    : "holidays are not considered for this date"), related);
+        });
+        const cover = dates.slice(0, j).find((r) => r.from <= rule.from && rule.to <= r.to);
+        if (cover) {
+            unused.add(rule);
+            c.warning("shadowed", rule.path, `This rule is never used: the earlier rule ${cover.path} covers all of its days`, cover.path);
+        }
+    });
+    // --- 毎年の月日: 覆われている ---
+    const annualBits = annual.map(annualMatches);
+    annual.forEach((rule, j) => {
+        const k = annualBits.findIndex((bits, i) => i < j && isSubset(annualBits[j], bits));
+        if (k < 0)
+            return;
+        unused.add(rule);
+        c.warning("shadowed", rule.path, `This rule is never used: the earlier rule ${annual[k].path} covers all of its days`, annual[k].path);
+    });
+    // --- 繰り返しの規則: 当てはまる日がない・覆われている ---
+    const recurringBits = recurring.map(recurringMatches);
+    recurring.forEach((rule, j) => {
+        const bits = recurringBits[j];
+        if (isEmpty(bits)) {
+            unused.add(rule);
+            c.warning("never-matches", rule.path, "This rule matches no day (for example, a day that does not exist in the selected months)");
+            return;
+        }
+        const k = recurring.findIndex((r, i) => i < j && canCover(r, rule) && isSubset(bits, recurringBits[i]));
+        if (k < 0)
+            return;
+        unused.add(rule);
+        c.warning("shadowed", rule.path, `This rule is never used: the earlier rule ${recurring[k].path} covers all of its days`, recurring[k].path);
+    });
+    // --- 営業日が 1 日もない（営業日カレンダー） ---
+    // 個別の日付は有限なので、臨時営業日（値が true）がなければ、個別の日付を除いて調べる
+    if (isCalendar && window && !dates.some((r) => r.value === true)) {
+        const resolve = createResolver(without(compiled, null, true), lookup);
+        let found = false;
+        for (let n = window.from; n <= window.to && !found; n++) {
+            if (resolve(fromDayNumber(n)).day.value === true)
+                found = true;
+        }
+        if (!found) {
+            c.warning("no-business-day", "", `No day is a business day with these options (checked ${window.label}); ` +
+                "searching for a business day throws");
+        }
+    }
+    // --- 取り除いても結果が変わらない ---
+    const redundant = (rule, base, days) => {
+        const resolve = createResolver(without(base, rule, false), lookup);
+        return days.every((n) => sameValue(rule.value, resolve(fromDayNumber(n)).day.value));
+    };
+    // 個別の日付は、その期間を調べる（対応年の外で例外になる日は除く）
+    const full = createResolver(compiled, lookup);
+    for (const rule of dates) {
+        if (unused.has(rule))
+            continue;
+        const decided = [];
+        let checked = 0;
+        const last = Math.min(rule.to, rule.from + MAX_DATE_RULE_DAYS - 1);
+        for (let n = rule.from; n <= last; n++) {
+            let decidedBy;
+            try {
+                decidedBy = full(fromDayNumber(n)).rule;
+            }
+            catch {
+                continue;
+            }
+            checked++;
+            if (decidedBy === rule)
+                decided.push(n);
+        }
+        if (checked > 0 && redundant(rule, compiled, decided)) {
+            c.info("redundant", rule.path, decided.length === 0
+                ? "This rule is never used: earlier rules cover all of its days"
+                : "Removing this rule does not change any result");
+        }
+    }
+    // 毎年の月日・繰り返しの規則は、調べる期間の全日を調べる。個別の日付は有限なので除いて調べる
+    if (!window)
+        return;
+    const candidates = [...annual, ...recurring].filter((r) => !unused.has(r));
+    if (candidates.length === 0)
+        return;
+    const base = without(compiled, null, true);
+    const resolveBase = createResolver(base, lookup);
+    const decided = new Map(candidates.map((r) => [r, []]));
+    for (let n = window.from; n <= window.to; n++) {
+        const rule = resolveBase(fromDayNumber(n)).rule;
+        if (rule)
+            decided.get(rule)?.push(n);
+    }
+    for (const rule of candidates) {
+        const days = decided.get(rule);
+        if (!redundant(rule, base, days))
+            continue;
+        c.info("redundant", rule.path, days.length === 0
+            ? `This rule is never used: other rules decide every day it matches (checked ${window.label})`
+            : `Removing this rule does not change any result (checked ${window.label})`);
+    }
+}
+/** 診断を実行する。祝日の提供元の誤り（年ごとに初めて使うときに分かる）も error として返す */
+function run(c, compiled, isCalendar) {
+    if (compiled && !c.hasErrors) {
+        const before = c.issues.length;
+        try {
+            analyze(c, compiled, isCalendar);
+        }
+        catch (error) {
+            // 規則どうしの診断の途中の結果は、提供元の誤りで信頼できないので捨てる
+            c.issues.length = before;
+            const code = error?.code;
+            c.error(code === "out-of-range" ? "out-of-range" : "invalid-provider-data", "holidays", error instanceof Error ? error.message : String(error));
+        }
+    }
+    return Object.freeze(c.issues.map(({ unknownKey, knownKeys, ...issue }) => {
+        const suggestion = unknownKey === undefined || knownKeys === undefined
+            ? undefined
+            : closestKey(unknownKey, knownKeys);
+        if (suggestion !== undefined) {
+            issue.message += ` (did you mean ${JSON.stringify(suggestion)}?)`;
+        }
+        return Object.freeze(issue);
+    }));
+}
+/**
+ * 営業日カレンダーの設定を診断する。例外は投げず、見つけた問題を返す（問題がなければ空の配列）。
+ *
+ * error があるときは、規則どうしの診断（shadowed・redundant など）は行わない。
+ * JavaScript から渡された型の合わない設定も受け付ける。
+ * @public
+ */
+export function diagnoseCalendar(options = {}) {
+    const c = new IssueCollector();
+    const compiled = compileCalendarOptions(c, options);
+    return run(c, compiled?.schedule, true);
+}
+/**
+ * スケジュールの設定を診断する。例外は投げず、見つけた問題を返す（問題がなければ空の配列）。
+ *
+ * 値が同じかは、配列と普通のオブジェクトは中身で、それ以外は Object.is で比べる。
+ * error があるときは、規則どうしの診断（shadowed・redundant など）は行わない。
+ * @public
+ */
+export function diagnoseSchedule(options) {
+    const c = new IssueCollector();
+    const compiled = compileScheduleOptions(c, options);
+    return run(c, compiled, false);
+}

package/dist/core/errors.d.ts

@@ -3,6 +3,7 @@
  *
  * 例外は従来どおり RangeError・TypeError・Error のインスタンスで、code プロパティを持つ。
  * 例外のメッセージの文言は API に含まない（変わることがある）。判定には code を使う。
+ * 問題を集める仕組み（IssueCollector）は、作成時のチェックと規則の診断（diagnose）で共通。
  */
 /**
  * 既知のエラーコード（増えることがある）。
@@ -11,6 +12,8 @@
 export type KnownErrorCode = 
 /** 日付 "YYYY-MM-DD" の形式・値の誤り */
 "invalid-date"
+/** 月 "YYYY-MM" の形式・値の誤り */
+ | "invalid-month"
 /** 毎年の月日 "MM-DD" の形式・値の誤り */
  | "invalid-month-day"
 /** 時刻・日時の形式・値の誤り */
@@ -61,18 +64,28 @@ export type IssueSeverity = "error" | "warning" | "info";
 export interface Issue {
     readonly severity: IssueSeverity;
     readonly code: string;
-    /** 設定の中の位置（例: "dates[1].from"） */
+    /** 設定の中の位置（例: "dates[1].from"）。設定全体なら "" */
     readonly path: string;
     readonly message: string;
+    /** 関係する別の位置（例: 覆っている先の規則） */
+    readonly relatedPath?: string;
+    /** unknown-option の知らないキーと既知のキー（診断で候補を挙げるため。結果には出さない） */
+    readonly unknownKey?: string;
+    readonly knownKeys?: readonly string[];
 }
 /** @internal 問題を集める */
 export declare class IssueCollector {
     readonly issues: Issue[];
     error(code: KnownErrorCode, path: string, message: string): void;
-    warning(code: string, path: string, message: string): void;
+    warning(code: string, path: string, message: string, relatedPath?: string): void;
+    info(code: string, path: string, message: string, relatedPath?: string): void;
+    private add;
     get hasErrors(): boolean;
     /** 最初の誤りを例外にして投げる（誤りがなければ何もしない） */
     throwFirstError(): void;
 }
-/** @internal 設定のオブジェクトに、知らないキーがあれば警告として記録する */
+/**
+ * @internal 設定のオブジェクトに、知らないキーがあれば警告として記録する。
+ * 近い既知のキーを候補に挙げるのは規則の診断で行う（作成時は警告を使わないので、ここでは既知のキーを渡すだけ）
+ */
 export declare function checkUnknownKeys(collector: IssueCollector, path: string, value: object, known: readonly string[]): void;

package/dist/core/errors.js

@@ -3,6 +3,7 @@
  *
  * 例外は従来どおり RangeError・TypeError・Error のインスタンスで、code プロパティを持つ。
  * 例外のメッセージの文言は API に含まない（変わることがある）。判定には code を使う。
+ * 問題を集める仕組み（IssueCollector）は、作成時のチェックと規則の診断（diagnose）で共通。
  */
 /**
  * このライブラリが投げた例外（code 付き）か。
@@ -36,8 +37,16 @@ export class IssueCollector {
     error(code, path, message) {
         this.issues.push({ severity: "error", code, path, message });
     }
-    warning(code, path, message) {
-        this.issues.push({ severity: "warning", code, path, message });
+    warning(code, path, message, relatedPath) {
+        this.add("warning", code, path, message, relatedPath);
+    }
+    info(code, path, message, relatedPath) {
+        this.add("info", code, path, message, relatedPath);
+    }
+    add(severity, code, path, message, relatedPath) {
+        this.issues.push(relatedPath === undefined
+            ? { severity, code, path, message }
+            : { severity, code, path, message, relatedPath });
     }
     get hasErrors() {
         return this.issues.some((i) => i.severity === "error");
@@ -51,11 +60,21 @@ export class IssueCollector {
         throw rangeError(first.code, message);
     }
 }
-/** @internal 設定のオブジェクトに、知らないキーがあれば警告として記録する */
+/**
+ * @internal 設定のオブジェクトに、知らないキーがあれば警告として記録する。
+ * 近い既知のキーを候補に挙げるのは規則の診断で行う（作成時は警告を使わないので、ここでは既知のキーを渡すだけ）
+ */
 export function checkUnknownKeys(collector, path, value, known) {
     for (const key of Object.keys(value)) {
         if (!known.includes(key)) {
-            collector.warning("unknown-option", path ? `${path}.${key}` : key, `Unknown option ${JSON.stringify(key)} is ignored`);
+            collector.issues.push({
+                severity: "warning",
+                code: "unknown-option",
+                path: path ? `${path}.${key}` : key,
+                message: `Unknown option ${JSON.stringify(key)} is ignored`,
+                unknownKey: key,
+                knownKeys: known,
+            });
         }
     }
 }

package/dist/core/month.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 月（"YYYY-MM"）の計算。締め日の月（closingMonth）や、n か月後の月（monthOf）。
+ *
+ * 営業日を考えない暦の計算なので、カレンダーなしで使える。営業日を考えた月の計算
+ * （月の第 n 営業日・期日）は営業日カレンダーのメソッドにある。
+ */
+import { type DateString } from "./date.ts";
+/**
+ * 月を表す "YYYY-MM" 文字列。
+ * @public
+ */
+export type MonthString = string;
+/** @internal 年と月 */
+export interface YearMonth {
+    readonly year: number;
+    readonly month: number;
+}
+/** @internal "YYYY-MM" を年と月に分解する（誤りは code: "invalid-month"） */
+export declare function parseMonth(value: unknown): YearMonth;
+/** @internal 年と月を "YYYY-MM" にする（年が 1000〜9999 の外なら code: "out-of-range"） */
+export declare function formatMonth({ year, month }: YearMonth): MonthString;
+/** @internal n か月後（負なら前）の年と月 */
+export declare function shiftMonth({ year, month }: YearMonth, offset: number): YearMonth;
+/** @internal その月の d 日（その月にない日・-1 は末日に読み替える） */
+export declare function dayOfMonth({ year, month }: YearMonth, day: number): DateString;
+/** @internal 月の日（1〜31、-1 は末日）として正しいか */
+export declare const isDayOfMonthValue: (v: unknown) => v is number;
+/**
+ * 日付または月の、offset か月後（負なら前）の月 "YYYY-MM"。
+ *
+ * @example
+ * monthOf("2026-10-16"); // "2026-10"
+ * monthOf("2026-10-16", 1); // "2026-11"
+ * monthOf("2026-01", -1); // "2025-12"
+ * @public
+ */
+export declare function monthOf(input: DateString | MonthString, offset?: number): MonthString;
+/**
+ * 締め日で区切ったときに、日付が属する月 "YYYY-MM"。
+ *
+ * 締め日の翌日から次の締め日までを、次の締め日の月とする（例: 20 日締めなら 10 月 21 日〜11 月 20 日が 11 月分）。
+ * closingDay が -1 またはその月の日数以上なら、締め日はその月の末日（例: 31 日締めの 2 月は 28 日か 29 日締め）。
+ *
+ * @example
+ * closingMonth("2026-10-20", 20); // "2026-10"
+ * closingMonth("2026-10-21", 20); // "2026-11"
+ * closingMonth("2026-10-31", -1); // "2026-10"（末日締め）
+ * @public
+ */
+export declare function closingMonth(date: DateString, closingDay: number): MonthString;

package/dist/core/month.js

@@ -0,0 +1,76 @@
+/**
+ * 月（"YYYY-MM"）の計算。締め日の月（closingMonth）や、n か月後の月（monthOf）。
+ *
+ * 営業日を考えない暦の計算なので、カレンダーなしで使える。営業日を考えた月の計算
+ * （月の第 n 営業日・期日）は営業日カレンダーのメソッドにある。
+ */
+import { daysInMonth, formatDate, parseDate } from "./date.js";
+import { rangeError } from "./errors.js";
+const MONTH_RE = /^(\d{4})-(\d{2})$/;
+/** @internal "YYYY-MM" を年と月に分解する（誤りは code: "invalid-month"） */
+export function parseMonth(value) {
+    const m = typeof value === "string" ? MONTH_RE.exec(value) : null;
+    const year = Number(m?.[1]);
+    const month = Number(m?.[2]);
+    if (!m || year < 1000 || month < 1 || month > 12) {
+        throw rangeError("invalid-month", `Invalid month: ${JSON.stringify(value)} (expected YYYY-MM)`);
+    }
+    return { year, month };
+}
+/** @internal 年と月を "YYYY-MM" にする（年が 1000〜9999 の外なら code: "out-of-range"） */
+export function formatMonth({ year, month }) {
+    if (year < 1000 || year > 9999) {
+        throw rangeError("out-of-range", `Year out of range (1000-9999): ${year}`);
+    }
+    return `${year}-${String(month).padStart(2, "0")}`;
+}
+/** @internal n か月後（負なら前）の年と月 */
+export function shiftMonth({ year, month }, offset) {
+    const index = year * 12 + (month - 1) + offset;
+    return { year: Math.floor(index / 12), month: (index % 12) + 1 };
+}
+/** @internal その月の d 日（その月にない日・-1 は末日に読み替える） */
+export function dayOfMonth({ year, month }, day) {
+    const last = daysInMonth(year, month);
+    return formatDate(year, month, day === -1 || day > last ? last : day);
+}
+/** @internal 月の日（1〜31、-1 は末日）として正しいか */
+export const isDayOfMonthValue = (v) => v === -1 || (Number.isInteger(v) && v >= 1 && v <= 31);
+/**
+ * 日付または月の、offset か月後（負なら前）の月 "YYYY-MM"。
+ *
+ * @example
+ * monthOf("2026-10-16"); // "2026-10"
+ * monthOf("2026-10-16", 1); // "2026-11"
+ * monthOf("2026-01", -1); // "2025-12"
+ * @public
+ */
+export function monthOf(input, offset = 0) {
+    if (!Number.isInteger(offset)) {
+        throw rangeError("invalid-argument", `offset must be an integer: ${offset}`);
+    }
+    const base = typeof input === "string" && input.split("-").length === 3
+        ? parseDate(input)
+        : parseMonth(input);
+    return formatMonth(shiftMonth(base, offset));
+}
+/**
+ * 締め日で区切ったときに、日付が属する月 "YYYY-MM"。
+ *
+ * 締め日の翌日から次の締め日までを、次の締め日の月とする（例: 20 日締めなら 10 月 21 日〜11 月 20 日が 11 月分）。
+ * closingDay が -1 またはその月の日数以上なら、締め日はその月の末日（例: 31 日締めの 2 月は 28 日か 29 日締め）。
+ *
+ * @example
+ * closingMonth("2026-10-20", 20); // "2026-10"
+ * closingMonth("2026-10-21", 20); // "2026-11"
+ * closingMonth("2026-10-31", -1); // "2026-10"（末日締め）
+ * @public
+ */
+export function closingMonth(date, closingDay) {
+    if (!isDayOfMonthValue(closingDay)) {
+        throw rangeError("invalid-argument", `closingDay must be an integer from 1 to 31, or -1 (last day): ${closingDay}`);
+    }
+    const { year, month, day } = parseDate(date);
+    const closing = closingDay === -1 ? daysInMonth(year, month) : closingDay;
+    return formatMonth(shiftMonth({ year, month }, day <= closing ? 0 : 1));
+}