@first-ch/tools-mcp 0.4.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/cron.mjs ADDED
@@ -0,0 +1,633 @@
1
+ /* Cron式の解説+次回発火日時(cron_explain)
2
+ * アルゴリズムは FirstCHTools の site/cron/app.js と同一
3
+ * (2箇所ルール: site側が正本・片方を直したらもう片方も同じ内容で反映する)。
4
+ *
5
+ * 解釈は Vixie cron(crontab(5))準拠。5フィールド(分 時 日 月 曜日)を基本とし、
6
+ * 6フィールドのときは先頭を秒として扱う(node-cron / Spring 形式)。
7
+ * 「日」と「曜日」の両方が指定されたときは AND ではなく OR(どちらかに一致すれば実行)。
8
+ * 次回発火はタイムゾーンの壁時計(wall clock)上で探索し、見つかった壁時計を
9
+ * 実時刻へ戻してから表示用に再フォーマットする(DSTのある地域でも嘘をつかないため)。 */
10
+
11
+ const MACROS = {
12
+ '@yearly': '0 0 1 1 *',
13
+ '@annually': '0 0 1 1 *',
14
+ '@monthly': '0 0 1 * *',
15
+ '@weekly': '0 0 * * 0',
16
+ '@daily': '0 0 * * *',
17
+ '@midnight': '0 0 * * *',
18
+ '@hourly': '0 * * * *',
19
+ };
20
+
21
+ const MONTH_ALIASES = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];
22
+ const DOW_ALIASES = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
23
+
24
+ // dow は解析中だけ 0-7 を許し(7=日曜)、展開後に 7→0 へ正規化する。
25
+ // こうすると 0-7 や 1-7 のような「7を終端に使う書き方」が素直に全曜日になる。
26
+ const DEFS = {
27
+ second: { key: 'second', min: 0, max: 59 },
28
+ minute: { key: 'minute', min: 0, max: 59 },
29
+ hour: { key: 'hour', min: 0, max: 23 },
30
+ dom: { key: 'dom', min: 1, max: 31 },
31
+ month: { key: 'month', min: 1, max: 12, aliases: MONTH_ALIASES, aliasBase: 1, wrap: true },
32
+ dow: { key: 'dow', min: 0, max: 7, aliases: DOW_ALIASES, aliasBase: 0, wrap: true, normalize: true },
33
+ };
34
+
35
+ export class CronError extends Error {
36
+ constructor(code, params) {
37
+ super(code);
38
+ this.code = code;
39
+ this.params = params || {};
40
+ this.message = formatError(this);
41
+ }
42
+ }
43
+
44
+ const FIELD_JA = { second: '秒', minute: '分', hour: '時', dom: '日', month: '月', dow: '曜日' };
45
+ const FIELD_EN = { second: 'second', minute: 'minute', hour: 'hour', dom: 'day of month', month: 'month', dow: 'day of week' };
46
+
47
+ const ERR_JA = {
48
+ empty: () => 'Cron式が空です。',
49
+ bad_arity: (q) => `Cron式は5フィールド(分 時 日 月 曜日)、秒を付ける場合は6フィールドです(入力は ${q.count} フィールド)。`,
50
+ bad_macro: (q) => `未対応の省略記法 ${q.token} です。使えるのは @yearly @annually @monthly @weekly @daily @midnight @hourly です。`,
51
+ reboot: () => '@reboot は「起動時に1回」で、日時が決まらないため次回発火は計算できません。',
52
+ empty_field: (q) => `${FIELD_JA[q.field]}のフィールドが空です。`,
53
+ bad_token: (q) => `${FIELD_JA[q.field]}のフィールドの "${q.token}" が解釈できません。`,
54
+ bad_step: (q) => `${FIELD_JA[q.field]}の "${q.token}" のステップ(/ のうしろ)は1以上の整数にしてください。`,
55
+ out_of_range: (q) => `"${q.token}" は${FIELD_JA[q.field]}の範囲(${q.min}〜${q.max})の外です。`,
56
+ bad_range: (q) => `${FIELD_JA[q.field]}の "${q.token}" は範囲の向きが逆です。小さい方から大きい方へ書いてください(折り返しが使えるのは月と曜日だけです)。`,
57
+ unsupported_ext: (q) => `"${q.token}" は Quartz 拡張(L / W / #)です。このツールは標準のUnix cron準拠のため対応していません。`,
58
+ };
59
+
60
+ const ERR_EN = {
61
+ empty: () => 'The cron expression is empty.',
62
+ bad_arity: (q) => `A cron expression needs 5 fields (minute hour day month weekday), or 6 with a leading seconds field — got ${q.count}.`,
63
+ bad_macro: (q) => `Unknown shorthand ${q.token}. Supported: @yearly @annually @monthly @weekly @daily @midnight @hourly.`,
64
+ reboot: () => '@reboot fires when the machine (or the daemon) starts, so it has no scheduled date and time.',
65
+ empty_field: (q) => `The ${FIELD_EN[q.field]} field is empty.`,
66
+ bad_token: (q) => `Cannot read "${q.token}" in the ${FIELD_EN[q.field]} field.`,
67
+ bad_step: (q) => `The step in "${q.token}" (${FIELD_EN[q.field]}) must be an integer of 1 or more.`,
68
+ out_of_range: (q) => `"${q.token}" is outside the ${FIELD_EN[q.field]} range (${q.min}-${q.max}).`,
69
+ bad_range: (q) => `"${q.token}" (${FIELD_EN[q.field]}) counts down; a range must go from smaller to larger. Wrap-around is only allowed for month and weekday.`,
70
+ unsupported_ext: (q) => `"${q.token}" is a Quartz extension (L / W / #). This tool follows standard Unix cron and does not support it.`,
71
+ };
72
+
73
+ /** 例外メッセージは日英併記(呼び出し側の言語が分からないため) */
74
+ export function formatError(err) {
75
+ const ja = (ERR_JA[err.code] || (() => 'この式は解釈できませんでした。'))(err.params);
76
+ const en = (ERR_EN[err.code] || (() => 'Could not parse this expression.'))(err.params);
77
+ return `${ja} / ${en}`;
78
+ }
79
+
80
+ /** 単一の値トークン(数値 or JAN/SUN 等の別名)を数値へ解決する */
81
+ function resolveValue(tok, def) {
82
+ const t = String(tok).trim();
83
+ if (!t) throw new CronError('bad_token', { field: def.key, token: tok });
84
+ if (/^\d+$/.test(t)) {
85
+ const n = parseInt(t, 10);
86
+ if (n < def.min || n > def.max) {
87
+ throw new CronError('out_of_range', { field: def.key, token: t, min: def.min, max: def.max });
88
+ }
89
+ return n;
90
+ }
91
+ if (def.aliases) {
92
+ const i = def.aliases.indexOf(t.toUpperCase());
93
+ if (i >= 0) return i + def.aliasBase;
94
+ }
95
+ // Quartz拡張(L / W / #)はこのツールでは扱わない。誤って通さず、はっきり伝える
96
+ if (/^\d*[LW]$/i.test(t) || t.includes('#')) throw new CronError('unsupported_ext', { field: def.key, token: t });
97
+ throw new CronError('bad_token', { field: def.key, token: t });
98
+ }
99
+
100
+ /**
101
+ * 1フィールドを解析して、一致する値の集合と、書き方の内訳(items)を返す。
102
+ * @returns {{values:number[], set:Set<number>, all:boolean, items:Array}}
103
+ */
104
+ function parseField(raw, def) {
105
+ const src = String(raw).trim();
106
+ if (!src) throw new CronError('empty_field', { field: def.key });
107
+ const set = new Set();
108
+ const items = [];
109
+ const N = def.max - def.min + 1;
110
+
111
+ for (const part of src.split(',')) {
112
+ const p = part.trim();
113
+ if (!p) throw new CronError('bad_token', { field: def.key, token: part });
114
+
115
+ let rangeTxt = p;
116
+ let stepTxt = null;
117
+ const slash = p.indexOf('/');
118
+ if (slash >= 0) {
119
+ rangeTxt = p.slice(0, slash).trim();
120
+ stepTxt = p.slice(slash + 1).trim();
121
+ }
122
+ let step = 1;
123
+ if (stepTxt !== null) {
124
+ if (!/^\d+$/.test(stepTxt) || parseInt(stepTxt, 10) < 1) {
125
+ throw new CronError('bad_step', { field: def.key, token: p });
126
+ }
127
+ step = parseInt(stepTxt, 10);
128
+ }
129
+
130
+ let from;
131
+ let to;
132
+ let kind;
133
+ if (rangeTxt === '*' || rangeTxt === '?') {
134
+ from = def.min;
135
+ to = def.max;
136
+ kind = 'all';
137
+ } else {
138
+ const dash = rangeTxt.indexOf('-');
139
+ if (dash >= 0) {
140
+ from = resolveValue(rangeTxt.slice(0, dash), def);
141
+ to = resolveValue(rangeTxt.slice(dash + 1), def);
142
+ kind = 'range';
143
+ } else {
144
+ from = resolveValue(rangeTxt, def);
145
+ // Vixie拡張: `5/10` は「5から最大値まで10おき」
146
+ to = stepTxt !== null ? def.max : from;
147
+ kind = stepTxt !== null ? 'range' : 'single';
148
+ }
149
+ }
150
+
151
+ let count;
152
+ if (from <= to) count = to - from + 1;
153
+ else if (def.wrap) count = ((to - from + N) % N) + 1; // 月/曜日だけ NOV-FEB のような折り返しを許す
154
+ else throw new CronError('bad_range', { field: def.key, token: p, from, to });
155
+
156
+ for (let k = 0; k < count; k += step) set.add(def.min + ((from - def.min + k) % N));
157
+ items.push({ text: p, kind, from, to, step, wrapped: from > to });
158
+ }
159
+
160
+ if (def.normalize) {
161
+ // 曜日の 7 は 0(日曜)と同じ
162
+ if (set.has(7)) {
163
+ set.delete(7);
164
+ set.add(0);
165
+ }
166
+ }
167
+ const effMax = def.normalize ? 6 : def.max;
168
+ const values = [...set].sort((a, b) => a - b);
169
+ return { values, set, all: values.length === effMax - def.min + 1, items, def, effMax };
170
+ }
171
+
172
+ /**
173
+ * Cron式を解析する。5フィールド(分 時 日 月 曜日)または6フィールド(先頭が秒)。
174
+ * @throws {CronError}
175
+ */
176
+ export function parseCron(expr) {
177
+ let src = String(expr == null ? '' : expr).trim().replace(/\s+/g, ' ');
178
+ if (!src) throw new CronError('empty');
179
+
180
+ let macro = null;
181
+ if (src.startsWith('@')) {
182
+ const key = src.toLowerCase();
183
+ if (key === '@reboot') throw new CronError('reboot');
184
+ if (!Object.prototype.hasOwnProperty.call(MACROS, key)) throw new CronError('bad_macro', { token: src });
185
+ macro = key;
186
+ src = MACROS[key];
187
+ }
188
+
189
+ const parts = src.split(' ');
190
+ if (parts.length !== 5 && parts.length !== 6) throw new CronError('bad_arity', { count: parts.length });
191
+ const hasSeconds = parts.length === 6;
192
+ const order = hasSeconds
193
+ ? ['second', 'minute', 'hour', 'dom', 'month', 'dow']
194
+ : ['minute', 'hour', 'dom', 'month', 'dow'];
195
+
196
+ const fields = {};
197
+ order.forEach((key, i) => {
198
+ fields[key] = parseField(parts[i], DEFS[key]);
199
+ fields[key].text = parts[i];
200
+ });
201
+ if (!hasSeconds) {
202
+ fields.second = { values: [0], set: new Set([0]), all: false, items: [], def: DEFS.second, effMax: 59, text: '0' };
203
+ }
204
+
205
+ const warnings = [];
206
+ if (hasSeconds) warnings.push({ code: 'six_fields' });
207
+ // `*/7` のような「範囲を割り切らないステップ」は、境界で数え直すので等間隔にならない
208
+ for (const key of order) {
209
+ const f = fields[key];
210
+ const d = DEFS[key];
211
+ const span = (d.normalize ? 6 : d.max) - d.min + 1;
212
+ for (const it of f.items) {
213
+ if (it.kind === 'all' && it.step > 1 && span % it.step !== 0) {
214
+ warnings.push({ code: 'uneven_step', field: key, step: it.step, span });
215
+ }
216
+ }
217
+ }
218
+ if (!fields.dom.all && !fields.dow.all) warnings.push({ code: 'dom_dow_or' });
219
+
220
+ return {
221
+ expression: expr,
222
+ normalized: order.map((k) => fields[k].text).join(' '),
223
+ macro,
224
+ hasSeconds,
225
+ order,
226
+ fields,
227
+ warnings,
228
+ };
229
+ }
230
+
231
+ /* ---- タイムゾーン付きの壁時計計算 ---- */
232
+
233
+ const fmtCache = new Map();
234
+ function partsFormatter(timeZone) {
235
+ let f = fmtCache.get(timeZone);
236
+ if (!f) {
237
+ f = new Intl.DateTimeFormat('en-US', {
238
+ timeZone,
239
+ hourCycle: 'h23',
240
+ year: 'numeric',
241
+ month: '2-digit',
242
+ day: '2-digit',
243
+ hour: '2-digit',
244
+ minute: '2-digit',
245
+ second: '2-digit',
246
+ });
247
+ fmtCache.set(timeZone, f);
248
+ }
249
+ return f;
250
+ }
251
+
252
+ /** 実時刻(ms) → そのタイムゾーンの壁時計 */
253
+ export function tzParts(ms, timeZone) {
254
+ const o = {};
255
+ for (const p of partsFormatter(timeZone).formatToParts(new Date(ms))) {
256
+ if (p.type !== 'literal') o[p.type] = p.value;
257
+ }
258
+ return { y: +o.year, mo: +o.month, d: +o.day, h: +o.hour, mi: +o.minute, s: +o.second };
259
+ }
260
+
261
+ function tzOffset(ms, timeZone) {
262
+ const p = tzParts(ms, timeZone);
263
+ return Date.UTC(p.y, p.mo - 1, p.d, p.h, p.mi, p.s) - Math.floor(ms / 1000) * 1000;
264
+ }
265
+
266
+ /** 壁時計 → 実時刻(ms)。オフセットを2回引き直してDSTの境目でもずれないようにする */
267
+ function zonedToMs(w, timeZone) {
268
+ const guess = Date.UTC(w.y, w.mo - 1, w.d, w.h, w.mi, w.s);
269
+ let ms = guess - tzOffset(guess, timeZone);
270
+ ms = guess - tzOffset(ms, timeZone);
271
+ return ms;
272
+ }
273
+
274
+ const daysInMonth = (y, mo) => new Date(Date.UTC(y, mo, 0)).getUTCDate();
275
+ const dowOf = (y, mo, d) => new Date(Date.UTC(y, mo - 1, d)).getUTCDay();
276
+
277
+ /**
278
+ * 次に発火する時刻を count 件返す(fromより後)。
279
+ * @returns {{fires:number[], exhausted:boolean}} fires は実時刻(ms)の昇順
280
+ */
281
+ export function nextFires(parsed, opts) {
282
+ const timeZone = opts.timeZone;
283
+ const count = opts.count || 5;
284
+ const from = opts.from;
285
+ const hasSec = parsed.hasSeconds;
286
+
287
+ const sSet = parsed.fields.second.set;
288
+ const miSet = parsed.fields.minute.set;
289
+ const hSet = parsed.fields.hour.set;
290
+ const domSet = parsed.fields.dom.set;
291
+ const moSet = parsed.fields.month.set;
292
+ const dowSet = parsed.fields.dow.set;
293
+ const bothRestricted = !parsed.fields.dom.all && !parsed.fields.dow.all;
294
+
295
+ // 「今より後」から探す。分精度なら次の分の0秒から
296
+ const cur = tzParts(from + (hasSec ? 1000 : 60000), timeZone);
297
+ if (!hasSec) cur.s = 0;
298
+
299
+ const rollDay = () => {
300
+ cur.d += 1;
301
+ cur.h = 0;
302
+ cur.mi = 0;
303
+ cur.s = 0;
304
+ if (cur.d > daysInMonth(cur.y, cur.mo)) {
305
+ cur.d = 1;
306
+ cur.mo += 1;
307
+ if (cur.mo > 12) {
308
+ cur.mo = 1;
309
+ cur.y += 1;
310
+ }
311
+ }
312
+ };
313
+ const rollMonth = () => {
314
+ cur.mo += 1;
315
+ cur.d = 1;
316
+ cur.h = 0;
317
+ cur.mi = 0;
318
+ cur.s = 0;
319
+ if (cur.mo > 12) {
320
+ cur.mo = 1;
321
+ cur.y += 1;
322
+ }
323
+ };
324
+ const rollHour = () => {
325
+ cur.h += 1;
326
+ cur.mi = 0;
327
+ cur.s = 0;
328
+ if (cur.h > 23) rollDay();
329
+ };
330
+ const rollMinute = () => {
331
+ cur.mi += 1;
332
+ cur.s = 0;
333
+ if (cur.mi > 59) rollHour();
334
+ };
335
+ const rollSecond = () => {
336
+ cur.s += 1;
337
+ if (cur.s > 59) rollMinute();
338
+ };
339
+
340
+ const limitYear = cur.y + 6; // 6年探して見つからなければ「発火しない式」とみなす
341
+ const fires = [];
342
+ let prev = -Infinity;
343
+ let guard = 0;
344
+ let exhausted = false;
345
+ let dstSkipped = 0;
346
+
347
+ while (fires.length < count) {
348
+ if (cur.y > limitYear || guard++ > 3000000) {
349
+ exhausted = true;
350
+ break;
351
+ }
352
+ if (!moSet.has(cur.mo)) {
353
+ rollMonth();
354
+ continue;
355
+ }
356
+ if (cur.d > daysInMonth(cur.y, cur.mo)) {
357
+ rollDay();
358
+ continue;
359
+ }
360
+ const okDom = domSet.has(cur.d);
361
+ const okDow = dowSet.has(dowOf(cur.y, cur.mo, cur.d));
362
+ const dayOk = bothRestricted ? okDom || okDow : okDom && okDow;
363
+ if (!dayOk) {
364
+ rollDay();
365
+ continue;
366
+ }
367
+ if (!hSet.has(cur.h)) {
368
+ rollHour();
369
+ continue;
370
+ }
371
+ if (!miSet.has(cur.mi)) {
372
+ rollMinute();
373
+ continue;
374
+ }
375
+ if (hasSec && !sSet.has(cur.s)) {
376
+ rollSecond();
377
+ continue;
378
+ }
379
+ const ms = zonedToMs(cur, timeZone);
380
+ // 夏時間の飛びでその壁時計が存在しない日は、戻したときに別の時刻になる。
381
+ // 実行されない時刻を並べても仕方がないので、その回は落とす(cron実装によって挙動が割れる部分)。
382
+ const back = tzParts(ms, timeZone);
383
+ const exists =
384
+ back.y === cur.y && back.mo === cur.mo && back.d === cur.d && back.h === cur.h && back.mi === cur.mi && back.s === cur.s;
385
+ if (!exists) dstSkipped += 1;
386
+ else if (ms > from && ms > prev) {
387
+ fires.push(ms);
388
+ prev = ms;
389
+ }
390
+ if (hasSec) rollSecond();
391
+ else rollMinute();
392
+ }
393
+ return { fires, exhausted, dstSkipped };
394
+ }
395
+
396
+ /* ---- 値の並びを人間向けに縮める ---- */
397
+
398
+ const DOW_JA = ['日', '月', '火', '水', '木', '金', '土'];
399
+ const DOW_EN = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
400
+ const MONTH_EN = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
401
+ const JA_UNIT = { second: '秒', minute: '分', hour: '時', dom: '日', month: '月' };
402
+
403
+ function valueName(v, key, en) {
404
+ if (key === 'dow') return en ? DOW_EN[v] : DOW_JA[v] + '曜';
405
+ if (en) return key === 'month' ? MONTH_EN[v - 1] : String(v);
406
+ return `${v}${JA_UNIT[key] || ''}`;
407
+ }
408
+
409
+ /** [0,1,2,3,7] → 「0〜3, 7」のように、3つ以上続く部分だけ範囲へまとめる */
410
+ function compressValues(values, key, en, maxGroups) {
411
+ const cap = maxGroups || 10;
412
+ const groups = [];
413
+ let i = 0;
414
+ while (i < values.length) {
415
+ let j = i;
416
+ while (j + 1 < values.length && values[j + 1] === values[j] + 1) j++;
417
+ if (j - i >= 2) {
418
+ groups.push(`${valueName(values[i], key, en)}${en ? '–' : '〜'}${valueName(values[j], key, en)}`);
419
+ } else {
420
+ for (let k = i; k <= j; k++) groups.push(valueName(values[k], key, en));
421
+ }
422
+ i = j + 1;
423
+ }
424
+ const sep = en ? ', ' : '・';
425
+ if (groups.length > cap) return groups.slice(0, cap).join(sep) + (en ? ', …' : ' …');
426
+ return groups.join(sep);
427
+ }
428
+
429
+ /** 全値が等間隔で、かつ範囲を割り切るときだけ「Nおき」と言い切れる */
430
+ function evenStep(field) {
431
+ const v = field.values;
432
+ const d = field.def;
433
+ if (v.length < 2) return 0;
434
+ const step = v[1] - v[0];
435
+ if (step < 2) return 0;
436
+ for (let i = 2; i < v.length; i++) if (v[i] - v[i - 1] !== step) return 0;
437
+ const span = field.effMax - d.min + 1;
438
+ if (v[0] !== d.min || span % step !== 0 || v.length !== span / step) return 0;
439
+ return step;
440
+ }
441
+
442
+ /* ---- 日本語・英語の読み下し ---- */
443
+
444
+ function timePhrase(p, en) {
445
+ const h = p.fields.hour;
446
+ const mi = p.fields.minute;
447
+ const s = p.fields.second;
448
+ const pad = (n) => String(n).padStart(2, '0');
449
+ const miStep = evenStep(mi);
450
+ const hStep = evenStep(h);
451
+
452
+ const hourList = compressValues(h.values, 'hour', en);
453
+ const minList = compressValues(mi.values, 'minute', en);
454
+ // en は :00, :15 の形で読ませるが、長くなりすぎるものは打ち切る
455
+ const enClock = (vals) =>
456
+ vals.length > 10 ? `:${vals.slice(0, 10).map(pad).join(', :')}, …` : `:${vals.map(pad).join(', :')}`;
457
+
458
+ let base;
459
+ if (en) {
460
+ const hourPart = h.all ? 'every hour' : hStep ? `every ${hStep} hours (${hourList})` : `hour ${hourList}`;
461
+ if (h.all && mi.all) base = 'every minute';
462
+ else if (h.all) base = miStep ? `every ${miStep} minutes (at ${enClock(mi.values)})` : `every hour at ${enClock(mi.values)}`;
463
+ else if (mi.all) base = `every minute of ${hourPart}`;
464
+ else if (h.values.length === 1 && mi.values.length === 1) base = `at ${pad(h.values[0])}:${pad(mi.values[0])}`;
465
+ else base = `${hourPart} at ${enClock(mi.values)}`;
466
+ } else {
467
+ const hourPart = h.all ? '毎時' : hStep ? `${hStep}時間ごと(${hourList})` : hourList;
468
+ if (h.all && mi.all) base = '毎分';
469
+ else if (h.all) base = miStep ? `${miStep}分ごと(毎時 ${minList})` : `毎時 ${minList}`;
470
+ else if (mi.all) base = `${hourPart}の毎分`;
471
+ else if (h.values.length === 1 && mi.values.length === 1) base = `${h.values[0]}時${pad(mi.values[0])}分`;
472
+ else base = `${hourPart}の${minList}`;
473
+ }
474
+
475
+ if (!p.hasSeconds) return base;
476
+ if (s.all) return en ? `${base}, every second` : `${base}の毎秒`;
477
+ const sStep = evenStep(s);
478
+ if (sStep) return en ? `${base} (every ${sStep} seconds)` : `${base}の${sStep}秒ごと`;
479
+ if (en) return `${base} (second ${enClock(s.values)})`;
480
+ return `${base}${compressValues(s.values, 'second', false)}`;
481
+ }
482
+
483
+ function datePhrase(p, en) {
484
+ const dom = p.fields.dom;
485
+ const dow = p.fields.dow;
486
+ const mo = p.fields.month;
487
+
488
+ const moPart = mo.all ? null : compressValues(mo.values, 'month', en);
489
+ const domList = compressValues(dom.values, 'dom', en);
490
+ const dowList = compressValues(dow.values, 'dow', en);
491
+ let dayPart;
492
+ if (dom.all && dow.all) dayPart = en ? 'every day' : '毎日';
493
+ else if (!dom.all && dow.all) {
494
+ // 月が絞られていれば「1月1日」、絞られていなければ「毎月1日」
495
+ dayPart = en ? `on day ${domList} of the month` : `${moPart ? '' : '毎月'}${domList}`;
496
+ if (!en && moPart) return `${moPart}${domList}`;
497
+ } else if (dom.all && !dow.all) dayPart = en ? `on ${dowList}` : `毎週${dowList}`;
498
+ else {
499
+ // Cronの仕様: 日と曜日の両方が指定されたときは AND ではなく OR
500
+ dayPart = en
501
+ ? `on day ${domList} of the month, or on ${dowList} (whichever matches)`
502
+ : `毎月${domList} または 毎週${dowList}(どちらかに一致した日)`;
503
+ }
504
+ if (!moPart) return dayPart;
505
+ return en ? `in ${moPart}, ${dayPart}` : `${moPart}の${dayPart}`;
506
+ }
507
+
508
+ /** 「毎日、15分おき(毎時 0分・15分・30分・45分)に実行します。」のような1文を返す */
509
+ export function describe(p, en) {
510
+ if (en) return `Runs ${datePhrase(p, true)}, ${timePhrase(p, true)}.`;
511
+ return `${datePhrase(p, false)}、${timePhrase(p, false)}に実行します。`;
512
+ }
513
+
514
+ /* ---- 注意書き ---- */
515
+
516
+ const WARN_JA = {
517
+ six_fields: () => '6フィールドのため、先頭を「秒」として解釈しました(node-cron / Spring 形式)。標準のUnix crontab は5フィールドです。',
518
+ uneven_step: (q) => `${FIELD_JA[q.field]}の */${q.step} は境界(0)から数え直すため、最後の値と次の0の間だけ間隔が ${q.step} より短くなります。等間隔にはなりません。`,
519
+ dom_dow_or: () => '「日」と「曜日」の両方が指定されています。Cronはこれを AND ではなく OR として扱うため、どちらかに一致した日すべてで実行されます。',
520
+ never: () => '今後6年以内に一致する日時がありませんでした。2月30日のような存在しない組み合わせになっていないか確認してください。',
521
+ limited: (q) => `今後6年以内に見つかったのは ${q.found} 件までです(それより先は探索していません)。`,
522
+ dst_skip: (q) => `夏時間の切り替えで存在しない現地時刻になる回が ${q.count} 件あったため、一覧から除いています(この場合の挙動はcron実装によって異なります)。`,
523
+ };
524
+
525
+ const WARN_EN = {
526
+ six_fields: () => 'Six fields: the first one is read as seconds (node-cron / Spring style). Standard Unix crontab uses five fields.',
527
+ uneven_step: (q) => `*/${q.step} in the ${FIELD_EN[q.field]} field restarts from the beginning of each cycle, so the gap around the boundary is shorter than ${q.step} — the interval is not uniform.`,
528
+ dom_dow_or: () => 'Both "day of month" and "day of week" are restricted. Cron treats this as OR, not AND — it fires on days matching either one.',
529
+ never: () => 'No matching date and time was found within the next six years. Check for impossible combinations such as February 30th.',
530
+ limited: (q) => `Only ${q.found} run time(s) fall within the next six years; the search stops there.`,
531
+ dst_skip: (q) => `${q.count} occurrence(s) fall on local times that do not exist because of a daylight-saving jump and were left out (real cron implementations differ here).`,
532
+ };
533
+
534
+ const warnJa = (w) => (WARN_JA[w.code] || (() => w.code))(w);
535
+ const warnEn = (w) => (WARN_EN[w.code] || (() => w.code))(w);
536
+
537
+ /* ---- 出力の組み立て ---- */
538
+
539
+ const pad2 = (n) => String(n).padStart(2, '0');
540
+ const fmtWall = (w) => `${w.y}-${pad2(w.mo)}-${pad2(w.d)} ${pad2(w.h)}:${pad2(w.mi)}:${pad2(w.s)}`;
541
+
542
+ /** 実時刻(ms) + タイムゾーン → オフセット付きISO8601(例 2026-08-08T12:15:00+09:00) */
543
+ function isoWithOffset(ms, timeZone) {
544
+ const w = tzParts(ms, timeZone);
545
+ const offMin = Math.round(tzOffset(ms, timeZone) / 60000);
546
+ const sign = offMin < 0 ? '-' : '+';
547
+ const a = Math.abs(offMin);
548
+ return `${w.y}-${pad2(w.mo)}-${pad2(w.d)}T${pad2(w.h)}:${pad2(w.mi)}:${pad2(w.s)}${sign}${pad2(Math.floor(a / 60))}:${pad2(a % 60)}`;
549
+ }
550
+
551
+ function humanIn(ms, en) {
552
+ const total = Math.floor(ms / 1000);
553
+ if (total < 60) return en ? 'under a minute' : '1分以内';
554
+ const d = Math.floor(total / 86400);
555
+ const h = Math.floor((total % 86400) / 3600);
556
+ const mi = Math.floor((total % 3600) / 60);
557
+ if (en) {
558
+ if (d) return `in ${d}d ${h}h`;
559
+ if (h) return `in ${h}h ${mi}m`;
560
+ return `in ${mi}m`;
561
+ }
562
+ if (d) return `${d}日${h}時間後`;
563
+ if (h) return `${h}時間${mi}分後`;
564
+ return `${mi}分後`;
565
+ }
566
+
567
+ /**
568
+ * Cron式を解説し、次回の発火日時を返す。
569
+ * @param {string} expression Cron式(5フィールド / 6フィールド / @daily 等)
570
+ * @param {{timeZone?:string, count?:number, from?:string|number|Date}} [opts]
571
+ */
572
+ export function cronExplain(expression, opts = {}) {
573
+ const timeZone = opts.timeZone || 'UTC';
574
+ const count = Math.min(Math.max(parseInt(opts.count, 10) || 5, 1), 100);
575
+ // タイムゾーン名が不正なら Intl がここで投げる(探索の途中で落とさない)
576
+ try {
577
+ tzParts(Date.now(), timeZone);
578
+ } catch (e) {
579
+ throw new Error(`不明なタイムゾーン "${timeZone}" です(IANA名で指定してください。例: Asia/Tokyo) / Unknown time zone "${timeZone}" (use an IANA name such as Asia/Tokyo)`);
580
+ }
581
+ const fromMs = opts.from === undefined ? Date.now() : new Date(opts.from).getTime();
582
+ if (!Number.isFinite(fromMs)) throw new Error(`from の日時が解釈できません: ${opts.from} / Cannot parse "from": ${opts.from}`);
583
+
584
+ const p = parseCron(expression);
585
+ const { fires, exhausted, dstSkipped } = nextFires(p, { from: fromMs, timeZone, count });
586
+ const warnings = p.warnings.slice();
587
+ if (dstSkipped) warnings.push({ code: 'dst_skip', count: dstSkipped });
588
+ if (!fires.length) warnings.push({ code: 'never' });
589
+ else if (exhausted) warnings.push({ code: 'limited', found: fires.length });
590
+
591
+ const fieldOut = p.order.map((key) => {
592
+ const f = p.fields[key];
593
+ return {
594
+ field: key,
595
+ label_ja: FIELD_JA[key],
596
+ label_en: FIELD_EN[key],
597
+ expr: f.text,
598
+ values: f.values,
599
+ matches_all: f.all,
600
+ summary_ja: compressValues(f.values, key, false),
601
+ summary_en: compressValues(f.values, key, true),
602
+ };
603
+ });
604
+
605
+ return {
606
+ expression: String(expression),
607
+ normalized: p.normalized,
608
+ macro: p.macro,
609
+ has_seconds: p.hasSeconds,
610
+ valid: true,
611
+ description_ja: describe(p, false),
612
+ description_en: describe(p, true),
613
+ fields: fieldOut,
614
+ time_zone: timeZone,
615
+ from: isoWithOffset(fromMs, timeZone),
616
+ next: fires.map((ms) => {
617
+ const w = tzParts(ms, timeZone);
618
+ const wd = dowOf(w.y, w.mo, w.d);
619
+ return {
620
+ iso: isoWithOffset(ms, timeZone),
621
+ local: fmtWall(w),
622
+ epoch_ms: ms,
623
+ weekday_ja: DOW_JA[wd],
624
+ weekday_en: DOW_EN[wd],
625
+ in_ja: humanIn(ms - fromMs, false),
626
+ in_en: humanIn(ms - fromMs, true),
627
+ };
628
+ }),
629
+ never_fires: fires.length === 0,
630
+ warnings_ja: warnings.map(warnJa),
631
+ warnings_en: warnings.map(warnEn),
632
+ };
633
+ }