cronli5 0.2.0 → 0.2.1

package/dist/lang/zh.js

@@ -41,6 +41,22 @@ function orderWeekdaysForDisplay(segments) {
 function toFieldNumber(token, numberMap) {
   return isNonNegativeInteger(token) ? +token : numberMap[token.toUpperCase()];
 }
+function segmentsOf(ir, field) {
+  return ir.analyses.segments[field] ?? [];
+}
+function stepSegment(ir, field) {
+  return segmentsOf(ir, field)[0];
+}
+function singleValues(segments) {
+  const values = [];
+  for (const segment of segments) {
+    if (segment.kind !== "single") {
+      return null;
+    }
+    values.push(+segment.value);
+  }
+  return values;
+}
 
 // src/core/specs.ts
 var weekdayNumbers = {
@@ -88,12 +104,6 @@ function joinAnd(items) {
   }
   return items.slice(0, -1).join("\u3001") + "\u548C" + items[items.length - 1];
 }
-function fieldSegments(ir, field) {
-  return ir.analyses.segments[field] || [];
-}
-function stepSegment(ir, field) {
-  return fieldSegments(ir, field)[0];
-}
 function cadence(interval, unit) {
   return interval === 1 ? "\u6BCF" + unit : "\u6BCF" + interval + unit;
 }
@@ -106,16 +116,6 @@ function renderStride(stride) {
   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);
@@ -179,7 +179,7 @@ function hourWord(hour) {
 }
 function hourFires(ir) {
   const fires = [];
-  fieldSegments(ir, "hour").forEach(function expand(segment) {
+  segmentsOf(ir, "hour").forEach(function expand(segment) {
     if (segment.kind === "step") {
       fires.push(...segment.fires);
     } else if (segment.kind === "range") {
@@ -234,7 +234,7 @@ function renderEveryHour() {
   return "\u6BCF\u5C0F\u65F6";
 }
 function minuteHourClause(ir) {
-  const segments = fieldSegments(ir, "minute");
+  const segments = segmentsOf(ir, "minute");
   if (ir.shapes.minute === "step") {
     return stepClause(stepSegment(ir, "minute"), "\u5206\u949F", "\u5206", "\u6BCF\u5C0F\u65F6");
   }
@@ -253,12 +253,12 @@ function hourSegmentWords(segment) {
   return [hourWord(+segment.value)];
 }
 function hourList(ir) {
-  const words = fieldSegments(ir, "hour").flatMap(hourSegmentWords);
+  const words = segmentsOf(ir, "hour").flatMap(hourSegmentWords);
   return joinAnd(words);
 }
 function hourFrame(ir) {
   if (ir.shapes.hour === "range") {
-    const [from, to] = fieldSegments(ir, "hour")[0].bounds;
+    const [from, to] = segmentsOf(ir, "hour")[0].bounds;
     return "\u5728" + hourWord(+from) + "\u81F3" + hourWord(+to) + "\u4E4B\u95F4\uFF0C";
   }
   return "\u5728" + hourList(ir) + "\uFF0C";
@@ -329,7 +329,7 @@ function renderCompactClockTimes(ir, plan) {
     return cad;
   }
   const compact = plan;
-  const secs = fieldSegments(ir, "second");
+  const secs = segmentsOf(ir, "second");
   const tail = secs.length && ir.pattern.second !== "0" ? "\uFF0C\u7B2C" + valueText(secs) + "\u79D2" : "";
   if (!compact.fold) {
     const hourCad = hourCadencePhrase(ir);
@@ -343,12 +343,12 @@ function renderCompactClockTimes(ir, plan) {
 function renderHourRange(ir, plan) {
   const range = plan;
   if (range.minuteForm === "lead") {
-    const minuteSegs = fieldSegments(ir, "minute");
+    const minuteSegs = segmentsOf(ir, "minute");
     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") {
-    return "\u5728" + hourWord(range.from) + "\u81F3" + hourWord(range.to) + "\u4E4B\u95F4\uFF0C\u6BCF\u5C0F\u65F6" + valueList(fieldSegments(ir, "minute"), "\u5206") + "\uFF0C\u6BCF\u5206\u949F";
+    return "\u5728" + hourWord(range.from) + "\u81F3" + hourWord(range.to) + "\u4E4B\u95F4\uFF0C\u6BCF\u5C0F\u65F6" + valueList(segmentsOf(ir, "minute"), "\u5206") + "\uFF0C\u6BCF\u5206\u949F";
   }
   return "\u5728" + hourWord(range.from) + "\u81F3" + range.to + "\u70B9" + range.last + "\u5206\u4E4B\u95F4\uFF0C\u6BCF\u5206\u949F";
 }
@@ -360,7 +360,7 @@ function renderHourStep(ir) {
   return hourCadencePhrase(ir);
 }
 function hourStride(ir) {
-  const segments = fieldSegments(ir, "hour");
+  const segments = segmentsOf(ir, "hour");
   if (segments.length === 1 && segments[0].kind === "step") {
     const { fires, interval } = segments[0];
     return { interval, start: fires[0], last: fires[fires.length - 1] };
@@ -427,7 +427,7 @@ function renderRangeOfMinutes(ir) {
   return minuteHourClause(ir) + "\uFF0C\u6BCF\u5206\u949F";
 }
 function renderStandaloneSeconds(ir) {
-  const segs = fieldSegments(ir, "second");
+  const segs = segmentsOf(ir, "second");
   const first = segs[0];
   if (segs.length === 1 && first.kind === "step" && first.startToken === "*") {
     return cadence(first.interval, UNITS.second);
@@ -435,11 +435,11 @@ function renderStandaloneSeconds(ir) {
   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";
+  return "\u6BCF\u5206\u949F\u7B2C" + valueText(segmentsOf(ir, "second")) + "\u79D2";
 }
 function renderSecondsWithinMinute(ir) {
   const base = "\u6BCF\u5C0F\u65F6" + ir.pattern.minute + "\u5206";
-  const segs = fieldSegments(ir, "second");
+  const segs = segmentsOf(ir, "second");
   const first = segs[0];
   if (segs.length === 1 && first.kind === "step" && first.startToken === "*") {
     return base + "\uFF0C" + cadence(first.interval, UNITS.second);
@@ -447,7 +447,7 @@ function renderSecondsWithinMinute(ir) {
   return base + "\u7B2C" + valueText(segs) + "\u79D2";
 }
 function secondClause(ir) {
-  const segs = fieldSegments(ir, "second");
+  const segs = segmentsOf(ir, "second");
   if (!segs.length) {
     return "\u6BCF\u79D2";
   }
@@ -464,7 +464,7 @@ function minuteClause(ir) {
   if (ir.shapes.minute === "step") {
     return cadence(stepSegment(ir, "minute").interval, UNITS.minute);
   }
-  return valueList(fieldSegments(ir, "minute"), "\u5206");
+  return valueList(segmentsOf(ir, "minute"), "\u5206");
 }
 function clockRestCarriesSecond(rest) {
   return rest.kind === "clockTimes" && rest.times.some((time) => Boolean(time.second));
@@ -499,13 +499,13 @@ 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 nested = strideFromSegments(segmentsOf(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 hasHourWindow(ir) {
-  return fieldSegments(ir, "hour").some(function range(segment) {
+  return segmentsOf(ir, "hour").some(function range(segment) {
     return segment.kind === "range";
   });
 }
@@ -541,7 +541,7 @@ function composeSecondsListed(ir) {
   const sec = secondClause(ir);
   const minutes = minuteHourClause(ir);
   if (ir.shapes.hour === "single" && sec === "\u6BCF\u79D2") {
-    const minuteSegs = fieldSegments(ir, "minute");
+    const minuteSegs = segmentsOf(ir, "minute");
     const minuteCad = strideFromSegments(minuteSegs, "\u5206\u949F", "\u5206", "") ?? valueList(minuteSegs, "\u5206");
     return hourWord(hourFires(ir)[0]) + minuteCad + "\u7684\u6BCF\u4E00\u79D2";
   }
@@ -597,7 +597,7 @@ function monthPhrase(ir) {
   if (ir.pattern.month === "*") {
     return "";
   }
-  const segs = fieldSegments(ir, "month");
+  const segs = segmentsOf(ir, "month");
   const first = segs[0];
   if (segs.length === 1 && first.kind === "step" && first.interval === 2) {
     return "\u6BCF\u4E2A" + (first.fires[0] % 2 ? "\u5947" : "\u5076") + "\u6570\u6708";
@@ -616,7 +616,7 @@ function monthPhrase(ir) {
   return nums.join("\u3001") + "\u6708";
 }
 function dayList(ir) {
-  const segs = fieldSegments(ir, "date");
+  const segs = segmentsOf(ir, "date");
   if (segs.every((seg) => seg.kind === "single")) {
     return segs.map((seg) => seg.value).join("\u3001") + "\u65E5";
   }
@@ -691,7 +691,7 @@ function weekdayPhrase(ir, orContext, monthPrefix) {
   if (ir.shapes.weekday === "quartz") {
     return quartzWeekday(ir.pattern.weekday, monthPrefix);
   }
-  const segs = fieldSegments(ir, "weekday");
+  const segs = segmentsOf(ir, "weekday");
   if (segs.length === 1 && segs[0].kind === "range") {
     const [from, to] = segs[0].bounds;
     return "\u6BCF" + weekdayName(from) + "\u81F3" + weekdayName(to);
@@ -785,7 +785,7 @@ function describe(ir, opts) {
   if (ir.pattern.year === "*") {
     return composed;
   }
-  const year = fieldSegments(ir, "year").map(function part(seg) {
+  const year = segmentsOf(ir, "year").map(function part(seg) {
     if (seg.kind === "range") {
       return seg.bounds[0] + "\u5E74\u81F3" + seg.bounds[1] + "\u5E74";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cronli5",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Cron Like I'm Five: A Cron to English Utility",
   "repository": {
     "type": "git",

package/src/core/analyze.ts

@@ -1,5 +1,5 @@
 // Semantic analysis of canonical fields: fire enumeration, windows, shape
-// classification, and description-strategy selection (the `plan`). The
+// classification, and description-plan selection (the `plan`). The
 // resulting IR is descriptive. Language modules handle rendering into
 // words (docs/i18n-design.md §2.2).
 
@@ -14,7 +14,8 @@ import {isDiscreteHours, isDiscreteList, isPlainRange, isSingleValue}
   from './shapes.js';
 import {isQuartzDate, isQuartzWeekday} from './validate.js';
 
-// List the values a `start/interval` step fires on within [0, max].
+// List the values a `start/interval` step fires on from `start` up to `max`,
+// stepping by `interval`.
 function getOccurrences(
   start: number,
   interval: number,
@@ -217,15 +218,15 @@ function analyze(pattern: Pattern): IR {
 
   const content: Content = {analyses, pattern, shapes};
 
-  return {...content, plan: selectStrategy(content)};
+  return {...content, plan: selectPlan(content)};
 }
 
-// Select the description strategy from the neutral content. This is the
-// core's *suggestion*: a language may override it via `Language.strategy`
-// without re-deriving it (the content-plan / overridable-strategy split).
+// Select the description plan from the neutral content. This is the
+// core's *suggestion*: a language may override it via `Language.plan`
+// without re-deriving it (the content-plan / overridable-plan split).
 // The selection mirrors the interpreter chain ordering exactly; renderers
 // must not re-derive it.
-function selectStrategy(content: Content): PlanNode {
+function selectPlan(content: Content): PlanNode {
   const {analyses, pattern, shapes} = content;
 
   if (pattern.second !== '0') {
@@ -240,7 +241,7 @@ function selectStrategy(content: Content): PlanNode {
     planHours(pattern, shapes, analyses);
 }
 
-// Seconds strategies, or null when the second folds into the clock time
+// Seconds plans, or null when the second folds into the clock time
 // downstream (a single second under discrete minutes and hours).
 function planSeconds(
   pattern: Pattern,
@@ -301,8 +302,8 @@ function planStandaloneSeconds(
   return {kind: 'standaloneSeconds'};
 }
 
-// Minute strategies, in the interpreter-chain order, or null to defer to
-// the hour strategies.
+// Minute plans, in the interpreter-chain order, or null to defer to
+// the hour plans.
 function planMinutes(
   pattern: Pattern,
   shapes: Shapes,
@@ -459,7 +460,7 @@ function planMinutesAcrossHours(
   return null;
 }
 
-// Minute strategies that only stand on their own under a wildcard hour.
+// Minute plans that only stand on their own under a wildcard hour.
 function planMinutesUnderOpenHour(
   pattern: Pattern,
   shapes: Shapes,
@@ -484,7 +485,7 @@ function planMinutesUnderOpenHour(
   }
 }
 
-// Hour strategies: the chain's last resort always produces a plan. Under a
+// Hour plans: the chain's last resort always produces a plan. Under a
 // sub-minute second a minute of 0 is a real restriction, so the absorbing
 // idioms (hour range, hour step, every hour) are skipped for it and the hour
 // is enumerated as clock times instead, stating the :00.
@@ -591,4 +592,4 @@ function hourTimesPlan(hourField: string): HourTimesPlan {
 }
 
 export {analyze, clockSecond, enumerateFires, enumerateStep,
-  enumerateValues, getOccurrences, lastMinuteFire, minuteSpan, selectStrategy};
+  enumerateValues, getOccurrences, lastMinuteFire, minuteSpan, selectPlan};

package/src/core/ir.ts

@@ -51,7 +51,7 @@ export type HourTimesPlan =
   | {kind: 'segments'};
 
 /**
- * The rendering strategy the core selects for a pattern. The `kind`
+ * The rendering plan the core selects for a pattern. The `kind`
  * discriminant tells a renderer which fields are present.
  */
 export type PlanNode =
@@ -100,8 +100,8 @@ export interface Analyses {
 
 /**
  * The neutral content plan: the language-independent facts about a pattern,
- * carrying no phrasing decision. `analyze` produces this; `selectStrategy`
- * reads it to suggest a `plan`. The phrasing strategy is deliberately *not*
+ * carrying no phrasing decision. `analyze` produces this; `selectPlan`
+ * reads it to suggest a `plan`. The phrasing plan is deliberately *not*
  * part of the neutral content (docs/i18n-design.md §2.2).
  */
 export interface Content {
@@ -113,7 +113,7 @@ export interface Content {
 /**
  * The semantic intermediate representation a language renders: the neutral
  * `Content` plus the selected `plan`. A language may widen `plan` with its
- * own `Extra` strategy kinds via `Language.strategy`; by default there are
+ * own `Extra` plan kinds via `Language.plan`; by default there are
  * none, so `IR` is the neutral content with a core `PlanNode`.
  */
 export interface IR<Extra extends {kind: string} = never> extends Content {
@@ -156,8 +156,8 @@ export interface NormalizedOptions<Style = DialectStyle> {
 
 /**
  * The interface every language module's default export implements. `Extra`
- * lets a language add its own strategy kinds (default: none), which its
- * `strategy` override emits and its `describe` renders.
+ * lets a language add its own plan kinds (default: none), which its
+ * `plan` override emits and its `describe` renders.
  */
 export interface Language<
   Style = DialectStyle,
@@ -170,9 +170,9 @@ export interface Language<
   // Wrap a rendered description into a complete standalone sentence (the CLI
   // form); each language owns its lead verb and punctuation.
   sentence(description: string): string;
-  // Optionally override the core's suggested strategy. Receives the neutral
+  // Optionally override the core's suggested plan. Receives the neutral
   // `content` and the core's suggestion (`base`), so overriding is a thin
   // remap, not a re-derivation. Omitted by languages that accept the core's
   // choice (all of en/de/es/fi today).
-  strategy?(content: Content, base: PlanNode): PlanNode | Extra;
+  plan?(content: Content, base: PlanNode): PlanNode | Extra;
 }

package/src/core/shapes.ts

@@ -37,5 +37,12 @@ function isDiscreteHours(hourField: string): boolean {
   return hourField !== '*' && !isPlainRange(hourField) &&
     !isPlainStep(hourField);
 }
-export {isDiscreteHours, isDiscreteList, isPlainRange, isPlainStep,
+
+// Whether a field is an "open" step (`*/n` or `a/n`, not a bounded range or a
+// list). Open steps read as a frequency rather than an enumeration.
+function isOpenStep(field: string): boolean {
+  return field.indexOf('/') !== -1 && field.indexOf('-') === -1 &&
+    field.indexOf(',') === -1;
+}
+export {isDiscreteHours, isDiscreteList, isOpenStep, isPlainRange, isPlainStep,
   isSingleValue};

package/src/core/util.ts

@@ -1,6 +1,11 @@
 // Small shared utilities for the core.
 
-import type {Segment} from './ir.js';
+import type {Field, IR, Segment} from './ir.js';
+
+// A step segment of a classified field, carrying its `fires`/`interval`/
+// `startToken`. The plan only routes step-shaped fields to step phrasing,
+// where the first segment is always a step segment.
+type StepSegment = Extract<Segment, {kind: 'step'}>;
 
 function includes(str: string | number, sub: string): boolean {
   return ('' + str).indexOf(sub) !== -1;
@@ -103,7 +108,85 @@ function toFieldNumber(
   // weekday) reach here. They always have an associated `numberMap`.
   return isNonNegativeInteger(token) ? +token : numberMap![token.toUpperCase()];
 }
+// A field's classified segments, or an empty list when the field is a
+// wildcard or Quartz shape (no segments). Renderers reach a non-empty list
+// only on the field shapes the analysis segmented; the empty fallback keeps
+// callers that touch a possibly-unsegmented field (a `.map`/`.forEach`) safe.
+function segmentsOf(ir: IR, field: Field): Segment[] {
+  return ir.analyses.segments[field] ?? [];
+}
+
+// The first segment of a step field, narrowed to its step variant. The plan
+// only routes step shapes here, whose (single) segment always classifies as a
+// step; this asserts what the analysis guarantees but the type cannot express.
+function stepSegment(ir: IR, field: Field): StepSegment {
+  return segmentsOf(ir, field)[0] as StepSegment;
+}
+
+// The sorted numeric values a field's segments cover, or null if any segment
+// is not a discrete single (a range or sub-step is not a plain fire list).
+function singleValues(segments: Segment[]): number[] | null {
+  const values: number[] = [];
+
+  for (const segment of segments) {
+    if (segment.kind !== 'single') {
+      return null;
+    }
+
+    values.push(+segment.value);
+  }
+
+  return values;
+}
+
+// Whether an hour stride wraps the day cleanly from within its first interval
+// (a `*/n` from the top, or a `m/n` offset with m < n that divides 24): such a
+// stride has no distinct endpoint and keeps its bare or "from M" cadence. Every
+// other stride — a uneven interval, or one starting at or past its interval (a
+// bounded `a-b/n`) — is a bounded set the cadence pins both endpoints of.
+function offsetCleanStride(
+  stride: {start: number; interval: number}
+): boolean {
+  return stride.start < stride.interval && 24 % stride.interval === 0;
+}
+
+// An hour list's arithmetic progression, or null when its values are not a
+// step the renderer should speak as a cadence. The core rewrites a uneven hour
+// step (whose interval does not tile 24, e.g. `*/5` → 0,5,10,15,20) to its
+// literal fire list, indistinguishable in the IR from a hand-written list; the
+// renderer recovers the cadence from the values. A progression starting at
+// zero is a `*/n` step however short (0,7,14,21 is `*/7`); a non-zero one is
+// only a step when it is too long to be a deliberate clock-time list (e.g.
+// 9,17 is two named times, not a cadence), the same length the minute/second
+// list path uses. Interval one is a plain range, never a step.
+function hourListStride(
+  values: number[]
+): {start: number; interval: number; last: number} | null {
+  if (values.length < 2) {
+    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;
+    }
+  }
+
+  if (values[0] !== 0 && values.length < 5) {
+    return null;
+  }
+
+  return {interval, last: values[values.length - 1], start: values[0]};
+}
+
 export {
-  arithmeticStep, includes, isNonNegativeInteger, orderWeekdaysForDisplay,
-  toFieldNumber, unique
+  arithmeticStep, hourListStride, includes, isNonNegativeInteger,
+  offsetCleanStride, orderWeekdaysForDisplay, segmentsOf, singleValues,
+  stepSegment, toFieldNumber, unique
 };

package/src/core/validate.ts

@@ -1,4 +1,4 @@
-// Loosely alidate a cron-like object against the field specifications,
+// Loosely validate a cron-like object against the field specifications,
 // including Quartz tokens and wrap-around range rules.
 
 import {fieldOrder, fieldSpecs} from './specs.js';

package/src/cronli5.ts

@@ -80,10 +80,10 @@ function interpretCronPattern(
   }
 
   // Analyze into the neutral content + the core's suggested plan, then let the
-  // language optionally override the strategy before rendering. A language
-  // without a `strategy` hook renders the core's suggestion unchanged.
+  // language optionally override the plan before rendering. A language
+  // without a `plan` hook renders the core's suggestion unchanged.
   const ir = analyze(prepare(cronPattern, opts));
-  const plan = lang.strategy ? lang.strategy(ir, ir.plan) : ir.plan;
+  const plan = lang.plan ? lang.plan(ir, ir.plan) : ir.plan;
 
   return lang.describe({...ir, plan}, opts);
 }