cronli5 0.1.2 → 0.1.5

package/dist/lang/zh.js

@@ -3,6 +3,21 @@ function isNonNegativeInteger(value) {
   const digits = /^\d+$/;
   return digits.test(value);
 }
+function arithmeticStep(values) {
+  if (values.length < 5) {
+    return null;
+  }
+  const interval = values[1] - values[0];
+  if (interval < 2) {
+    return null;
+  }
+  for (let i = 2; i < values.length; i += 1) {
+    if (values[i] - values[i - 1] !== interval) {
+      return null;
+    }
+  }
+  return { start: values[0], interval, last: values[values.length - 1] };
+}
 function toFieldNumber(token, numberMap) {
   return isNonNegativeInteger(token) ? +token : numberMap[token.toUpperCase()];
 }
@@ -31,6 +46,7 @@ var monthNumbers = {
   NOV: 11,
   DEC: 12
 };
+var maxClockTimes = 6;
 
 // src/lang/zh/dialects.ts
 var zh = { variant: "Hans" };
@@ -61,6 +77,46 @@ function stepSegment(ir, field) {
 function cadence(interval, unit) {
   return interval === 1 ? "\u6BCF" + unit : "\u6BCF" + interval + unit;
 }
+function renderStride(stride) {
+  const { interval, start, last, cycle, unit, mark, anchor } = stride;
+  const tiles = cycle % interval === 0;
+  if (start === 0 && tiles) {
+    return cadence(interval, unit);
+  }
+  const lead = anchor + "\u4ECE" + start + mark + "\u8D77" + cadence(interval, unit);
+  return start < interval && tiles ? lead : lead + "\uFF0C\u81F3" + last + mark;
+}
+function singleValues(segments) {
+  const values = [];
+  for (const segment of segments) {
+    if (segment.kind !== "single") {
+      return null;
+    }
+    values.push(+segment.value);
+  }
+  return values;
+}
+function strideFromSegments(segments, unit, mark, anchor) {
+  const values = singleValues(segments);
+  const step = values && arithmeticStep(values);
+  return step ? renderStride({ ...step, cycle: 60, unit, mark, anchor }) : null;
+}
+function stepClause(segment, unit, mark, anchor) {
+  const start = segment.startToken === "*" ? 0 : +segment.startToken;
+  const short = start !== 0 && segment.fires.length <= 3;
+  if (segment.startToken.indexOf("-") !== -1 || short) {
+    return anchor + segment.fires.join("\u3001") + mark;
+  }
+  return renderStride({
+    interval: segment.interval,
+    start,
+    last: segment.fires[segment.fires.length - 1],
+    cycle: 60,
+    unit,
+    mark,
+    anchor
+  });
+}
 function dayPeriod(hour) {
   if (hour < 6) {
     return "\u51CC\u6668";
@@ -157,8 +213,15 @@ function renderEveryMinute() {
 function renderEveryHour() {
   return "\u6BCF\u5C0F\u65F6";
 }
+function minuteHourClause(ir) {
+  const segments = fieldSegments(ir, "minute");
+  if (ir.shapes.minute === "step") {
+    return stepClause(stepSegment(ir, "minute"), "\u5206\u949F", "\u5206", "\u6BCF\u5C0F\u65F6");
+  }
+  return strideFromSegments(segments, "\u5206\u949F", "\u5206", "\u6BCF\u5C0F\u65F6") ?? "\u6BCF\u5C0F\u65F6" + valueList(segments, "\u5206");
+}
 function renderMinutePast(ir) {
-  return "\u6BCF\u5C0F\u65F6" + valueList(fieldSegments(ir, "minute"), "\u5206");
+  return minuteHourClause(ir);
 }
 function hourList(ir) {
   return joinAnd(hourFires(ir).map(hourWord));
@@ -172,10 +235,11 @@ function hourFrame(ir) {
 }
 function renderMinuteFrequency(ir, plan) {
   const minuteStep = stepSegment(ir, "minute");
-  const base = minuteStep.startToken === "*" ? cadence(minuteStep.interval, UNITS.minute) : renderMinutePast(ir);
+  const base = stepClause(minuteStep, UNITS.minute, "\u5206", "\u6BCF\u5C0F\u65F6");
   const { hours } = plan;
   if (hours.kind === "step") {
-    return cadence(stepSegment(ir, "hour").interval, UNITS.hour) + base;
+    const hourStep = stepSegment(ir, "hour");
+    return hourStep.startToken === "*" ? cadence(hourStep.interval, UNITS.hour) + base : "\u5728" + hourList(ir) + "\uFF0C" + base;
   }
   if (hours.kind === "single" || hours.kind === "window" && hours.from === hours.to) {
     return "\u5728" + hourWord(hours.from) + "\u81F3" + hours.from + "\u70B9" + hours.last + "\u5206\u4E4B\u95F4\uFF0C" + base;
@@ -190,6 +254,9 @@ function renderMinuteFrequency(ir, plan) {
 }
 function renderMinuteSpanInHour(ir, plan) {
   const span = plan;
+  if (ir.pattern.minute === "*") {
+    return hourWord(span.hour) + "\u7684\u6BCF\u4E00\u5206\u949F";
+  }
   return "\u5728" + hourWord(span.hour) + "\u81F3" + span.hour + "\u70B9" + span.span[1] + "\u5206\u4E4B\u95F4\uFF0C\u6BCF\u5206\u949F";
 }
 function renderMinutesAcrossHours(ir, plan) {
@@ -197,26 +264,46 @@ function renderMinutesAcrossHours(ir, plan) {
   if (form === "wildcard") {
     return "\u5728" + hourList(ir) + "\uFF0C\u6BCF\u5206\u949F";
   }
-  return hourList(ir) + "\uFF0C\u6BCF\u5C0F\u65F6" + valueList(fieldSegments(ir, "minute"), "\u5206") + "\uFF0C\u6BCF\u5206\u949F";
+  return hourList(ir) + "\uFF0C" + minuteHourClause(ir) + "\uFF0C\u6BCF\u5206\u949F";
 }
 function renderMinuteSpanAcrossHourStep(ir, plan) {
-  const cad = cadence(stepSegment(ir, "hour").interval, UNITS.hour);
+  const hourStep = stepSegment(ir, "hour");
   const { form } = plan;
-  if (form === "wildcard") {
-    return cad + "\u5185\uFF0C\u6BCF\u5206\u949F";
+  if (form === "list") {
+    return renderMinutePast(ir) + "\uFF0C\u5728" + hourList(ir);
+  }
+  const minuteTail = form === "wildcard" ? "\u6BCF\u5206\u949F" : minuteHourClause(ir) + "\uFF0C\u6BCF\u5206\u949F";
+  if (hourStep.startToken !== "*") {
+    return form === "wildcard" ? "\u5728" + hourList(ir) + "\uFF0C" + minuteTail : hourList(ir) + "\uFF0C" + minuteTail;
+  }
+  if (hourStep.interval === 2 && form === "wildcard") {
+    return "\u5728\u5076\u6570\u5C0F\u65F6\uFF0C" + minuteTail;
   }
-  return cad + "\uFF0C\u6BCF\u5C0F\u65F6" + valueList(fieldSegments(ir, "minute"), "\u5206") + "\uFF0C\u6BCF\u5206\u949F";
+  const cad = cadence(hourStep.interval, UNITS.hour);
+  return form === "wildcard" ? cad + "\u5185\uFF0C" + minuteTail : cad + "\uFF0C" + minuteTail;
 }
 function renderClockTimes(ir, plan, opts) {
+  if (ir.shapes.minute === "single") {
+    const cad = hourCadence(ir);
+    if (cad !== null) {
+      return cad;
+    }
+  }
   const { times } = plan;
   return joinAnd(times.map((t) => clockTime(t.hour, t.minute, t.second, opts)));
 }
 function renderCompactClockTimes(ir, plan) {
+  if (ir.shapes.minute === "single") {
+    const cad = hourCadence(ir);
+    if (cad !== null) {
+      return cad;
+    }
+  }
   const { minute } = plan;
   const secs = fieldSegments(ir, "second");
   const tail = secs.length && ir.pattern.second !== "0" ? "\uFF0C\u7B2C" + valueText(secs) + "\u79D2" : "";
   if (minute > 0) {
-    return "\u6BCF\u5C0F\u65F6" + valueList(fieldSegments(ir, "minute"), "\u5206") + "\uFF0C\u5728" + hourList(ir) + tail;
+    return minuteHourClause(ir) + "\uFF0C\u5728" + hourList(ir) + tail;
   }
   return hourList(ir) + tail;
 }
@@ -224,7 +311,7 @@ function renderHourRange(ir, plan) {
   const range = plan;
   if (range.minuteForm === "lead") {
     const minuteSegs = fieldSegments(ir, "minute");
-    const past = minuteSegs.length && ir.pattern.minute !== "0" ? "\u6BCF\u5C0F\u65F6" + valueList(minuteSegs, "\u5206") : "\u6BCF\u5C0F\u65F6";
+    const past = minuteSegs.length && ir.pattern.minute !== "0" ? minuteHourClause(ir) : "\u6BCF\u5C0F\u65F6";
     return "\u5728" + hourWord(range.from) + "\u81F3" + hourWord(range.to) + "\u4E4B\u95F4\uFF0C" + past;
   }
   if (range.minuteForm === "range") {
@@ -242,8 +329,52 @@ function renderHourStep(ir) {
   }
   return cadence(segment.interval, UNITS.hour);
 }
+function hourStride(ir) {
+  const segments = fieldSegments(ir, "hour");
+  if (segments.length === 1 && segments[0].kind === "step") {
+    const segment = segments[0];
+    const start = segment.startToken === "*" ? 0 : +segment.startToken;
+    if (start !== 0 || 24 % segment.interval !== 0) {
+      return null;
+    }
+    return {
+      interval: segment.interval,
+      last: segment.fires[segment.fires.length - 1]
+    };
+  }
+  const values = singleValues(segments);
+  const step = values && arithmeticStep(values);
+  if (!step || step.start !== 0 || 24 % step.interval !== 0) {
+    return null;
+  }
+  return { interval: step.interval, last: step.last };
+}
+function hourCadence(ir) {
+  const stride = hourStride(ir);
+  if (!stride) {
+    return null;
+  }
+  const fires = stride.last / stride.interval + 1;
+  if (ir.pattern.second === "0" && fires <= maxClockTimes) {
+    return null;
+  }
+  const prefix = cadence(stride.interval, UNITS.hour);
+  const minute = +ir.pattern.minute;
+  const subMinute = ir.pattern.second === "*" || ir.shapes.second === "step";
+  if (minute === 0 && subMinute) {
+    return stride.interval === 2 ? "\u5728\u5076\u6570\u5C0F\u65F60\u5206" + secondTail(ir) : null;
+  }
+  if (minute === 0) {
+    return prefix + "0\u5206" + secondTail(ir);
+  }
+  return ir.pattern.second === "0" ? prefix + minute + "\u5206" : prefix + minute + "\u5206" + secondTail(ir);
+}
+function secondTail(ir) {
+  const sec = secondClause(ir);
+  return sec === "\u6BCF\u79D2" ? "\u7684\u6BCF\u4E00\u79D2" : "\u7684" + sec;
+}
 function renderRangeOfMinutes(ir) {
-  return "\u6BCF\u5C0F\u65F6" + valueList(fieldSegments(ir, "minute"), "\u5206") + "\uFF0C\u6BCF\u5206\u949F";
+  return minuteHourClause(ir) + "\uFF0C\u6BCF\u5206\u949F";
 }
 function renderStandaloneSeconds(ir) {
   const segs = fieldSegments(ir, "second");
@@ -251,7 +382,7 @@ function renderStandaloneSeconds(ir) {
   if (segs.length === 1 && first.kind === "step" && first.startToken === "*") {
     return cadence(first.interval, UNITS.second);
   }
-  return "\u6BCF\u5206\u949F\u7B2C" + valueText(segs) + "\u79D2";
+  return strideFromSegments(segs, "\u79D2", "\u79D2", "\u6BCF\u5206\u949F") ?? "\u6BCF\u5206\u949F\u7B2C" + valueText(segs) + "\u79D2";
 }
 function renderSecondPastMinute(ir) {
   return "\u6BCF\u5206\u949F\u7B2C" + valueText(fieldSegments(ir, "second")) + "\u79D2";
@@ -274,7 +405,7 @@ function secondClause(ir) {
   if (segs.length === 1 && first.kind === "step" && first.startToken === "*") {
     return cadence(first.interval, UNITS.second);
   }
-  return "\u7B2C" + valueText(segs) + "\u79D2";
+  return strideFromSegments(segs, "\u79D2", "\u79D2", "\u6BCF\u5206\u949F") ?? "\u7B2C" + valueText(segs) + "\u79D2";
 }
 function minuteClause(ir) {
   if (ir.pattern.minute === "*") {
@@ -291,15 +422,36 @@ function isHourCadence(ir) {
 function composeSecondsOnHour(ir, plan, opts) {
   const sec = secondClause(ir);
   const { rest } = plan;
+  const composedClock = rest.kind === "clockTimes" || rest.kind === "compactClockTimes";
+  if (composedClock) {
+    const hourCad = hourCadence(ir);
+    if (hourCad !== null) {
+      return hourCad;
+    }
+  }
+  if (composedClock && ir.pattern.minute === "0") {
+    return composeMinuteZeroClocks(ir, sec);
+  }
   const restText = render(ir, rest, opts);
-  if ((rest.kind === "clockTimes" || rest.kind === "compactClockTimes") && isDaily(ir)) {
-    return "\u6BCF\u5929" + restText + sec;
+  if (rest.kind === "clockTimes" || rest.kind === "compactClockTimes") {
+    if (isDaily(ir)) {
+      return "\u6BCF\u5929" + restText + sec;
+    }
   }
   if (rest.kind === "singleMinute") {
     return restText + "\uFF0C" + sec;
   }
   return restText + sec;
 }
+function composeMinuteZeroClocks(ir, sec) {
+  const clocks = hourFires(ir).map(function clock(hour) {
+    return hour === 12 ? "\u6B63\u5348" : hourWord(hour) + "0\u5206";
+  });
+  const nested = strideFromSegments(fieldSegments(ir, "second"), "\u79D2", "\u79D2", "");
+  const tail = sec === "\u6BCF\u79D2" ? "\u7684\u6BCF\u4E00\u79D2" : "\u7684" + (nested ?? sec);
+  const core = joinAnd(clocks) + tail;
+  return isDaily(ir) ? "\u6BCF\u5929" + core : core;
+}
 function composeSecondsCadence(ir) {
   const sec = secondClause(ir);
   const tail = minuteClause(ir) + sec;
@@ -310,13 +462,24 @@ function composeSecondsCadence(ir) {
     return hourWord(hourFires(ir)[0]) + "\u7684" + tail;
   }
   if (ir.shapes.hour === "wildcard") {
+    if (ir.shapes.minute === "step" && sec === "\u6BCF\u79D2") {
+      const minuteStep = stepSegment(ir, "minute");
+      if (minuteStep.startToken === "*" && minuteStep.interval === 2) {
+        return "\u6BCF\u5076\u6570\u5206\u949F\u7684\u6BCF\u4E00\u79D2";
+      }
+    }
     return sec + "\uFF0C" + minuteClause(ir);
   }
   return hourFrame(ir) + tail;
 }
 function composeSecondsListed(ir) {
   const sec = secondClause(ir);
-  const minutes = "\u6BCF\u5C0F\u65F6" + valueList(fieldSegments(ir, "minute"), "\u5206");
+  const minutes = minuteHourClause(ir);
+  if (ir.shapes.hour === "single" && sec === "\u6BCF\u79D2") {
+    const minuteSegs = fieldSegments(ir, "minute");
+    const minuteCad = strideFromSegments(minuteSegs, "\u5206\u949F", "\u5206", "") ?? valueList(minuteSegs, "\u5206");
+    return hourWord(hourFires(ir)[0]) + minuteCad + "\u7684\u6BCF\u4E00\u79D2";
+  }
   if (ir.shapes.hour === "wildcard") {
     return minutes + "\uFF0C" + sec;
   }
@@ -326,10 +489,13 @@ function composeSecondsListed(ir) {
   return hourFrame(ir) + minutes + "\uFF0C" + sec;
 }
 function renderComposeSeconds(ir, plan, opts) {
-  if (ir.pattern.minute === "0") {
+  const { rest } = plan;
+  const composedClock = rest.kind === "clockTimes" || rest.kind === "compactClockTimes";
+  if (ir.pattern.minute === "0" || composedClock && ir.shapes.minute === "single") {
     return composeSecondsOnHour(ir, plan, opts);
   }
-  if (ir.pattern.minute === "*" || ir.shapes.minute === "step") {
+  const minuteCadence = ir.pattern.minute === "*" || ir.shapes.minute === "step" && stepSegment(ir, "minute").startToken === "*";
+  if (minuteCadence) {
     return composeSecondsCadence(ir);
   }
   return composeSecondsListed(ir);
@@ -529,11 +695,16 @@ function composeCadence(ir, core) {
 function composeWindow(ir, core) {
   return qualifier(ir) + core;
 }
+function hourCadenceApplies(ir) {
+  return ir.shapes.minute === "single" && hourCadence(ir) !== null;
+}
 function describe(ir, opts) {
   const { kind } = ir.plan;
   const core = render(ir, ir.plan, opts);
   let composed = core;
-  if (kind === "clockTimes" || kind === "compactClockTimes" && ir.pattern.minute === "0") {
+  if (hourCadenceApplies(ir)) {
+    composed = composeCadence(ir, core);
+  } else if (kind === "clockTimes" || kind === "compactClockTimes" && ir.pattern.minute === "0") {
     composed = composePoint(ir, core);
   } else if (kind === "hourStep" || kind === "minuteFrequency" || kind === "minuteSpanAcrossHourStep" || kind === "compactClockTimes") {
     composed = composeCadence(ir, core);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cronli5",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Cron Like I'm Five: A Cron to English Utility",
   "repository": {
     "type": "git",
@@ -60,8 +60,10 @@
   "scripts": {
     "build": "node scripts/build.mjs && npm run types",
     "docs": "node --import tsx scripts/docs.mjs",
+    "conciseness": "node --import tsx tooling/scripts/conciseness.mjs",
     "fuzz": "node --import tsx scripts/fuzz-lang.mjs",
     "lint": "eslint src test cli.js eslint.config.js scripts tooling/scripts",
+    "metamorphic": "node --import tsx tooling/scripts/metamorphic.mjs",
     "lint:fix": "eslint src test cli.js eslint.config.js scripts tooling/scripts --fix",
     "test": "mocha",
     "types": "tsc -p tsconfig.types.json",

package/src/core/analyze.ts

@@ -376,6 +376,13 @@ function planMinuteUnderHourStep(
     return {form: 'range', kind: 'minuteSpanAcrossHourStep'};
   }
 
+  // A minute list under a clean stride keeps the cadence too, so the hour
+  // reads the same whatever the minute's shape. An unclean stride falls
+  // through to compactClockTimes and enumerates its hours.
+  if (shapes.minute === 'list' && cleanHourStride(pattern.hour)) {
+    return {form: 'list', kind: 'minuteSpanAcrossHourStep'};
+  }
+
   return null;
 }
 

package/src/core/ir.ts

@@ -71,7 +71,7 @@ export type PlanNode =
       form: 'wildcard' | 'range' | 'list';
       times: HourTimesPlan;
     }
-  | {kind: 'minuteSpanAcrossHourStep'; form: 'wildcard' | 'range'}
+  | {kind: 'minuteSpanAcrossHourStep'; form: 'wildcard' | 'range' | 'list'}
   | {kind: 'everyHour'}
   | {
       kind: 'hourRange';

package/src/core/normalize.ts

@@ -67,10 +67,13 @@ function normalizeField(value: string, field: Field, spec: FieldSpec): string {
 
   const cycle = timeFieldCycle[field];
   const segments = stringValue.split(',').map(function canonical(segment) {
-    return enumerateNonUniformStep(
-      collapseDegenerateRange(
-        collapseOnceStep(collapseUnitStep(segment, spec), spec), spec),
-      spec, cycle);
+    return canonicalizeTokens(collapseFullSpanRange(
+      enumerateNonUniformStep(
+        collapseFullSpanStep(
+          collapseDegenerateRange(
+            collapseOnceStep(collapseUnitStep(segment, spec), spec), spec),
+          spec),
+        spec, cycle), spec), spec);
   }).join(',').split(',');
 
   // A full-cycle segment covers the whole field.
@@ -83,6 +86,40 @@ function normalizeField(value: string, field: Field, spec: FieldSpec): string {
   }).join(',');
 }
 
+// Rewrite a segment's value tokens to their canonical numbers: a name
+// (`MON`, `JAN`) becomes its index, and a weekday `7` (Sunday again, above
+// `top`) folds to the field minimum (`0`). Applied to every token position —
+// a single, both range bounds, and a step's start — so a normalized field
+// never carries a surface name or the 7-for-Sunday alias. `*` and Quartz
+// tokens (resolved earlier) are left untouched. Output is unchanged: a
+// renderer maps the number back to its own name.
+function canonicalizeTokens(segment: string, spec: FieldSpec): string {
+  // Only the named fields (month, weekday) carry name tokens or the
+  // weekday `7`-for-Sunday alias; every other field is already numeric.
+  if (!spec.numbers) {
+    return segment;
+  }
+
+  const parts = segment.split('/');
+  const start = parts[0].split('-').map(function fold(token) {
+    return canonicalizeToken(token, spec);
+  }).join('-');
+
+  return parts.length === 2 ? start + '/' + parts[1] : start;
+}
+
+// A single token to its canonical number string (`*` passes through).
+function canonicalizeToken(token: string, spec: FieldSpec): string {
+  if (token === '*') {
+    return token;
+  }
+
+  const number = toFieldNumber(token, spec.numbers);
+
+  // A value above `top` (weekday 7) is the field minimum again.
+  return '' + (number > (spec.top as number) ? spec.min : number);
+}
+
 // An interval-one step enumerates every value from its start, so it reads
 // as the equivalent range: `1/1` is `1-59` and `5-30/1` is `5-30`. A start
 // at the bottom of the cycle covers the whole field (`0/1` is `*`).
@@ -163,6 +200,59 @@ function enumerateNonUniformStep(
   return fires.join(',');
 }
 
+// A step whose range part covers the whole field (`0-59/2`, `0-23/2`) strides
+// across the entire cycle, so the bound adds nothing — it reads as the
+// unbounded `*/N` step (which the cycle test then renders as "every N" or its
+// fires). Partial-range steps (`9-17/2`) keep their window.
+function collapseFullSpanStep(segment: string, spec: FieldSpec): string {
+  const parts = segment.split('/');
+
+  if (parts.length !== 2 || !includes(parts[0], '-')) {
+    return segment;
+  }
+
+  return collapseFullSpanRange(parts[0], spec) === '*' ?
+    '*/' + parts[1] :
+    segment;
+}
+
+// A plain range whose enumerated values cover the whole field imposes no
+// restriction, so it reads identically to `*` (`0-59` minute, `0-23` hour,
+// `1-31` date, `1-12` month, and every seven-day weekday range — `0-6`,
+// `1-7`, `0-7`, `SUN-SAT` — since cron's 7 is Sunday again, folding to the
+// field minimum). Only bare ranges qualify: a step (`0-59/2`) keeps its
+// cadence, so segments carrying a `/` are left untouched.
+function collapseFullSpanRange(segment: string, spec: FieldSpec): string {
+  if (typeof spec.top !== 'number' || includes(segment, '/') ||
+      !includes(segment, '-')) {
+    return segment;
+  }
+
+  const bounds = segment.split('-');
+  const low = toFieldNumber(bounds[0], spec.numbers);
+  const high = toFieldNumber(bounds[1], spec.numbers);
+
+  if (low > high) {
+    return segment;
+  }
+
+  // The full field is min..top; a value above top (weekday 7) folds to min.
+  const top = spec.top as number;
+  const fired: Record<number, boolean> = {};
+
+  for (let value = low; value <= high; value += 1) {
+    fired[value > top ? spec.min : value] = true;
+  }
+
+  for (let value = spec.min; value <= top; value += 1) {
+    if (!fired[value]) {
+      return segment;
+    }
+  }
+
+  return '*';
+}
+
 // A degenerate range (`9-9`) fires once, so it reads as its single value.
 // A stepped degenerate range (`9-9/5`) likewise fires only at its start.
 function collapseDegenerateRange(segment: string, spec: FieldSpec): string {

package/src/core/util.ts

@@ -16,6 +16,34 @@ function isNonNegativeInteger(value: string): boolean {
   return digits.test(value);
 }
 
+// Recognize an arithmetic progression in a sorted, distinct numeric set: a
+// run of length >= 5 whose consecutive gaps are all equal and >= 2. Returns
+// its {start, interval, last}; null for anything shorter, with a gap of one
+// (a plain run, which reads as a range), or irregular. Output-neutral and
+// language-agnostic: renderers use it to speak a bounded/offset step cadence
+// ("every N from M [through K]") instead of enumerating the fires. The set is
+// the field's full value list, which the core has already sorted and deduped.
+function arithmeticStep(values: number[]):
+  {start: number; interval: number; last: number} | null {
+  if (values.length < 5) {
+    return null;
+  }
+
+  const interval = values[1] - values[0];
+
+  if (interval < 2) {
+    return null;
+  }
+
+  for (let i = 2; i < values.length; i += 1) {
+    if (values[i] - values[i - 1] !== interval) {
+      return null;
+    }
+  }
+
+  return {start: values[0], interval, last: values[values.length - 1]};
+}
+
 // Resolve a numeric or named field token (e.g. '5' or 'FRI') to its number.
 function toFieldNumber(
   token: string,
@@ -25,4 +53,6 @@ function toFieldNumber(
   // weekday) reach here. They always have an associated `numberMap`.
   return isNonNegativeInteger(token) ? +token : numberMap![token.toUpperCase()];
 }
-export {includes, isNonNegativeInteger, toFieldNumber, unique};
+export {
+  arithmeticStep, includes, isNonNegativeInteger, toFieldNumber, unique
+};