cronli5 0.1.4 → 0.1.5

package/src/lang/en/index.ts

@@ -3,6 +3,8 @@
 // the core stays semantic, and this module's only input is the IR.
 // See docs/i18n-design.md.
 
+import {arithmeticStep} from '../../core/util.js';
+import {maxClockTimes} from '../../core/specs.js';
 import {clockDigits, numeral} from '../../core/format.js';
 import type {Cronli5Options} from '../../types.js';
 import type {
@@ -19,6 +21,18 @@ type PlanOf<K extends PlanNode['kind']> = Extract<PlanNode, {kind: K}>;
 // phrasing, where the first segment is always a step segment.
 type StepSegment = Extract<Segment, {kind: 'step'}>;
 
+// A step cadence to phrase: the `interval` repeats over a `cycle`-long field
+// (60 for minute/second, 24 for hour), running from `start` to `last`. `unit`
+// is the singular noun and `anchor` the larger unit the values count against.
+interface Stride {
+  interval: number;
+  start: number;
+  last: number;
+  cycle: number;
+  unit: string;
+  anchor: string;
+}
+
 // A clock-time entry assembled for rendering. Hour/minute/second arrive as
 // numbers or as raw field tokens (a range bound or single value is a
 // string); `plain` suppresses the noon/midnight words. `explicit` forces the
@@ -174,11 +188,35 @@ function renderSecondsWithinMinute(ir: IR, plan: PlanOf<'secondsWithinMinute'>,
     trailingQualifier(ir, opts);
 }
 
+// The hour-cadence rendering of a compose-seconds plan whose clock-time rest
+// would cross-multiply an hour stride under a single pinned minute, or null
+// when that does not apply (a non-clock rest, a multi-valued minute, or an
+// hour that is not a stride).
+function composeHourCadence(ir: IR, plan: PlanOf<'composeSeconds'>,
+  opts: NormalizedOptions): string | null {
+  const clockRest = plan.rest.kind === 'clockTimes' ||
+    plan.rest.kind === 'compactClockTimes';
+
+  return clockRest && ir.shapes.minute === 'single' ?
+    hourCadence(ir, +ir.pattern.minute, opts) :
+    null;
+}
+
 // A meaningful second under minute/hour shapes the earlier strategies
 // deferred on: the second leads with its own clause and the rest of the
 // pattern follows.
 function renderComposeSeconds(ir: IR, plan: PlanOf<'composeSeconds'>,
   opts: NormalizedOptions): string {
+  // An hour step (or arithmetic-progression hour list) under a single pinned
+  // minute is a cadence, not a wall of clock times: speak the second/minute
+  // lead, then the hour cadence ("at 30 seconds past the hour, every two
+  // hours"). The clock-time rest would otherwise cross-multiply the hours.
+  const cadence = composeHourCadence(ir, plan, opts);
+
+  if (cadence !== null) {
+    return cadence;
+  }
+
   // A wildcard or stepped second under a minute pinned to a single value
   // across one or more specific hours. The clock-time rest collapses the
   // pinned minute into the hour, and on the clock a pinned minute-0 reads as
@@ -255,6 +293,16 @@ function clockTimesOf(ir: IR, plan: PlanOf<'clockTimes'>,
 // e.g. "at 5 and 10 seconds past the minute" or "every second from zero
 // through 30 past the minute".
 function secondsLeadClause(ir: IR, opts: NormalizedOptions): string {
+  return secondsClause(ir, 'minute', opts);
+}
+
+// The second clause counted against an arbitrary anchor. The anchor is
+// "minute" in the standalone seconds path; the hour-cadence path folds a
+// pinned minute 0 into the hour and counts the second "past the hour"
+// instead ("at 30 seconds past the hour", "every second from 0 through 10
+// past the hour"), so the minute-0 confinement is stated, not dropped.
+function secondsClause(ir: IR, anchor: string,
+  opts: NormalizedOptions): string {
   const secondField = ir.pattern.second;
   const shape = ir.shapes.second;
 
@@ -266,7 +314,7 @@ function secondsLeadClause(ir: IR, opts: NormalizedOptions): string {
     // The plan reached this clause only for a stepped second field, whose
     // first segment is always a step segment.
     return stepCycle60(ir.analyses.segments.second![0] as StepSegment,
-      'second', 'minute', opts);
+      'second', anchor, opts);
   }
 
   if (shape === 'range') {
@@ -274,17 +322,20 @@ function secondsLeadClause(ir: IR, opts: NormalizedOptions): string {
     const num = seriesNumber(bounds, opts);
 
     return 'every second from ' + num(bounds[0]) +
-      through(opts) + num(bounds[1]) + ' past the minute';
+      through(opts) + num(bounds[1]) + ' past the ' + anchor;
   }
 
   if (shape === 'single') {
     return 'at ' + getNumber(secondField, opts) + ' ' +
-      pluralize(secondField, 'second') + ' past the minute';
+      pluralize(secondField, 'second') + ' past the ' + anchor;
   }
 
-  // A non-wildcard second under the list/step path always has segments.
-  return listPastThe(segmentWords(ir.analyses.segments.second!, opts),
-    'second', 'minute', opts);
+  // A non-wildcard second under the list/step path always has segments. An
+  // offset/uneven step the core enumerated to a fire list reads as a stride
+  // cadence when those fires form a long-enough progression.
+  return strideFromSegments(ir.analyses.segments.second!, 'second', anchor,
+    opts) ?? listPastThe(segmentWords(ir.analyses.segments.second!, opts),
+    'second', anchor, opts);
 }
 
 // --- Minute renderers. ---
@@ -312,9 +363,13 @@ function renderRangeOfMinutes(ir: IR, plan: PlanOf<'rangeOfMinutes'>,
 function renderMultipleMinutes(ir: IR, plan: PlanOf<'multipleMinutes'>,
   opts: NormalizedOptions): string {
   // A multiple-minutes plan is selected only for a minute list, which has
-  // segments.
-  return listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
-    'minute', 'hour', opts) + trailingQualifier(ir, opts);
+  // segments. An offset/uneven step the core enumerated to this list reads as
+  // a stride cadence when the fires form a long-enough progression.
+  const stride =
+    strideFromSegments(ir.analyses.segments.minute!, 'minute', 'hour', opts);
+
+  return (stride ?? listPastThe(segmentWords(ir.analyses.segments.minute!,
+    opts), 'minute', 'hour', opts)) + trailingQualifier(ir, opts);
 }
 
 // A repeating minute step, qualified by the active hour window(s).
@@ -376,9 +431,11 @@ function renderMinutesAcrossHours(ir: IR, plan: PlanOf<'minutesAcrossHours'>,
   const times = hourTimesFromPlan(ir, plan.times, true, opts);
   const lead = plan.form === 'range' ?
     minuteRangeLead(ir.pattern.minute, opts) :
-    // The 'list' form is a minute list, which has segments.
-    listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
-      'minute', 'hour', opts);
+    // The 'list' form is a minute list, which has segments; an offset/uneven
+    // step enumerated to that list reads as a stride.
+    strideFromSegments(ir.analyses.segments.minute!, 'minute', 'hour', opts) ??
+      listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
+        'minute', 'hour', opts);
 
   return lead + ', at ' + times + trailingQualifier(ir, opts);
 }
@@ -414,8 +471,15 @@ function renderMinuteSpanAcrossHourStep(ir: IR,
       trailingQualifier(ir, opts);
   }
 
-  return minuteRangeLead(ir.pattern.minute, opts) + ', ' +
-    stepHours(segment, opts) + trailingQualifier(ir, opts);
+  // A minute list keeps the same cadence clause; only its lead differs. An
+  // offset/uneven step the core enumerated to that list reads as a stride.
+  const lead = plan.form === 'list' ?
+    strideFromSegments(ir.analyses.segments.minute!, 'minute', 'hour', opts) ??
+      listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
+        'minute', 'hour', opts) :
+    minuteRangeLead(ir.pattern.minute, opts);
+
+  return lead + ', ' + stepHours(segment, opts) + trailingQualifier(ir, opts);
 }
 
 // Lead phrase for a plain minute range: "every minute from <a> through <b>
@@ -463,8 +527,10 @@ function rangeMinuteLead(ir: IR, opts: NormalizedOptions): string {
     return 'every hour';
   }
 
-  // A non-"0" minute here is a discrete list, which has segments.
-  return listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
+  // A non-"0" minute here is a discrete list, which has segments; an
+  // offset/uneven step enumerated to that list reads as a stride.
+  return strideFromSegments(ir.analyses.segments.minute!, 'minute', 'hour',
+    opts) ?? listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
     'minute', 'hour', opts);
 }
 
@@ -497,6 +563,16 @@ function hourWindow(window: {from: number; to: number; last: number},
 // a day-level qualifier, e.g. "every day at 9 a.m. and 9:30 a.m.".
 function renderClockTimes(ir: IR, plan: PlanOf<'clockTimes'>,
   opts: NormalizedOptions): string {
+  // An hour step (or arithmetic-progression hour list) under a single pinned
+  // minute reads as a cadence rather than a cross-product of clock times.
+  if (ir.shapes.minute === 'single') {
+    const cadence = hourCadence(ir, +ir.pattern.minute, opts);
+
+    if (cadence !== null) {
+      return cadence;
+    }
+  }
+
   const plain = mixedTwelve(plan.times);
   const times = plan.times.map(function clock(time) {
     return getTime({
@@ -516,6 +592,15 @@ function renderClockTimes(ir: IR, plan: PlanOf<'clockTimes'>,
 function renderCompactClockTimes(ir: IR, plan: PlanOf<'compactClockTimes'>,
   opts: NormalizedOptions): string {
   if (plan.fold) {
+    // An hour step (or arithmetic-progression hour list) under the single
+    // pinned minute reads as a cadence, not a wall of clock times. (Returns
+    // null for an irregular list or a range, which keep folding below.)
+    const cadence = hourCadence(ir, +plan.minute, opts);
+
+    if (cadence !== null) {
+      return cadence;
+    }
+
     // A compact clock-time plan is reached only for discrete hours, which
     // have segments.
     const hasRange = ir.analyses.segments.hour!.some(function range(segment) {
@@ -535,9 +620,11 @@ function renderCompactClockTimes(ir: IR, plan: PlanOf<'compactClockTimes'>,
   }
 
   const phrase =
-    // The non-fold branch is a minute list, which has segments.
-    listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
-      'minute', 'hour', opts) +
+    // The non-fold branch is a minute list, which has segments. An
+    // offset/uneven step enumerated to that list reads as a stride.
+    (strideFromSegments(ir.analyses.segments.minute!, 'minute', 'hour', opts) ??
+      listPastThe(segmentWords(ir.analyses.segments.minute!, opts),
+        'minute', 'hour', opts)) +
     ', at ' + hourSegmentTimes(ir, {minute: 0, second: null}, true, opts) +
     trailingQualifier(ir, opts);
 
@@ -609,6 +696,71 @@ const renderers = {
 
 // --- Step phrases. ---
 
+// Speak a step cadence over a `cycle`-long field ("every N <unit>s [from M
+// [through K]] past the <anchor>"). A clean stride from the top of the cycle
+// is the bare cadence; a uniform offset (start within the first interval, the
+// interval still tiling the cycle) names only its start, since it wraps cleanly
+// and has no distinct endpoint; a non-uniform stride (start >= interval, or an
+// interval that does not tile the cycle) pins both endpoints so the bounded,
+// non-wrapping set reads unambiguously. This is the one phrasing for every
+// step the renderer speaks, whether the core kept it a step shape (a clean
+// cadence) or enumerated it to a fire list (an offset/uneven set the list
+// path recognizes as an arithmetic progression).
+function renderStride(stride: Stride, opts: NormalizedOptions): string {
+  const {interval, start, last, cycle, unit, anchor} = stride;
+  const cadence = 'every ' + getNumber(interval, opts) + ' ' + unit + 's';
+  const tiles = cycle % interval === 0;
+
+  if (start === 0 && tiles) {
+    return cadence;
+  }
+
+  if (start < interval && tiles) {
+    // A clean wrap from a non-zero offset: name the start, no endpoint.
+    return cadence + ' from ' + getNumber(start, opts) + ' ' +
+      pluralize(start, unit) + ' past the ' + anchor;
+  }
+
+  // A bounded, non-wrapping set: pin both endpoints. The two bounds share one
+  // number style (all spelled, or all numerals once either crosses ten),
+  // matching the range idiom ("from 0 through 30").
+  const num = seriesNumber([start, last], opts);
+
+  return cadence + ' from ' + num(start) + through(opts) + num(last) + ' ' +
+    pluralize(last, unit) + ' past the ' + anchor;
+}
+
+// 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;
+}
+
+// Speak a minute/second field's enumerated fires as a step cadence when they
+// form an arithmetic progression long enough to beat the list (the core
+// enumerates an offset/uneven step to this fire list; the IR is unchanged, so
+// the renderer recognizes the progression). Returns null for a non-progression
+// or a too-short list, leaving the caller to enumerate.
+function strideFromSegments(segments: Segment[], unit: string, anchor: string,
+  opts: NormalizedOptions): string | null {
+  const values = singleValues(segments);
+  const step = values && arithmeticStep(values);
+
+  return step ?
+    renderStride({...step, cycle: 60, unit, anchor}, opts) :
+    null;
+}
+
 // Phrase a `start/interval` step segment for a field that cycles every 60
 // units (seconds and minutes). `unit` is the singular noun and `anchor` is
 // the larger unit the values are counted against. Interval-one steps never
@@ -624,23 +776,23 @@ function stepCycle60(segment: StepSegment, unit: string,
   }
 
   const start = segment.startToken === '*' ? 0 : +segment.startToken;
-  const interval = segment.interval;
 
-  if (start !== 0) {
-    // A short offset cadence lists its fires; a longer one names the
-    // interval and its starting offset ("every six minutes from five …").
-    if (segment.fires.length <= 3) {
-      return listPastThe(numberWords(segment.fires, opts), unit, anchor,
-        opts);
-    }
-
-    return 'every ' + getNumber(interval, opts) + ' ' + unit + 's from ' +
-      getNumber(start, opts) + ' ' + pluralize(start, unit) +
-      ' past the ' + anchor;
+  // A short offset cadence lists its fires; otherwise the stride phrasing
+  // names the interval and its offset ("every six minutes from five …"). A
+  // step shape only reaches here as a clean cadence (the interval tiles 60),
+  // so the stride collapses to the bare or uniform-offset form.
+  if (start !== 0 && segment.fires.length <= 3) {
+    return listPastThe(numberWords(segment.fires, opts), unit, anchor, opts);
   }
 
-  // A clean stride from the top of the cycle is the bare cadence.
-  return 'every ' + getNumber(interval, opts) + ' ' + unit + 's';
+  return renderStride({
+    interval: segment.interval,
+    start,
+    last: segment.fires[segment.fires.length - 1],
+    cycle: 60,
+    unit,
+    anchor
+  }, opts);
 }
 
 // Phrase a `start/interval` step segment for the hour field (cycles every
@@ -670,6 +822,154 @@ function stepHours(segment: StepSegment, opts: NormalizedOptions): string {
     getTime({hour: start, minute: 0}, opts);
 }
 
+// Speak an hour stride as a cadence with clock-time bounds, the 24-cycle
+// analog of renderStride: a clean stride from midnight is the bare cadence
+// ("every two hours"); a clean offset names only its start ("every six hours
+// from 2 a.m."); a bounded or non-tiling stride pins both clock-time endpoints
+// ("every two hours from 9 a.m. through 5 p.m.") so the bounded set reads
+// unambiguously. Used wherever an hour step (or arithmetic-progression hour
+// list) would otherwise be cross-multiplied into a wall of clock times.
+function hourStrideCadence(stride: {start: number; interval: number;
+  last: number}, opts: NormalizedOptions): string {
+  const {start, interval, last} = stride;
+  const cadence = 'every ' + getNumber(interval, opts) + ' hours';
+  const tiles = 24 % interval === 0;
+
+  if (start === 0 && tiles) {
+    return cadence;
+  }
+
+  if (start < interval && tiles) {
+    return cadence + ' from ' + getTime({hour: start, minute: 0}, opts);
+  }
+
+  return cadence + ' from ' + getTime({hour: start, minute: 0}, opts) +
+    through(opts) + getTime({hour: last, minute: 0}, opts);
+}
+
+// The hour field's stride, or null when the hour is not a cadence: a step
+// segment yields its {start, interval, last} directly; an all-single hour
+// list yields one only when its values form a long-enough arithmetic
+// progression (so an irregular list like 9,17 keeps enumerating). The IR is
+// unchanged — the renderer recognizes the stride and speaks it as a cadence
+// instead of the clock-time cross-product.
+function hourStride(ir: IR):
+  {start: number; interval: number; last: number} | null {
+  // Reached only from the clock-time paths, which run under discrete hours
+  // and so always carry hour segments.
+  const segments = ir.analyses.segments.hour!;
+
+  if (segments.length === 1 && segments[0].kind === 'step') {
+    const segment = segments[0];
+    const start = segment.startToken === '*' ?
+      0 :
+      +segment.startToken.split('-')[0];
+
+    return {interval: segment.interval, last: segment.fires[
+      segment.fires.length - 1], start};
+  }
+
+  const values = singleValues(segments);
+  const step = values && arithmeticStep(values);
+
+  return step || null;
+}
+
+// The second's status against a pinned minute: a wildcard or sub-minute step
+// fills the minute (a "for one minute" frame at minute 0); a single 0 is just
+// the top of the minute (no clause); anything else needs its own clause.
+function subMinuteSecond(ir: IR): boolean {
+  return ir.pattern.second === '*' || ir.shapes.second === 'step';
+}
+
+// The lead clause for an hour-cadence rendering: the second and the pinned
+// minute, before the hour cadence. A pinned minute 0 folds in — a single,
+// list, or range second is counted "past the hour" (the minute-0 is the top
+// of the hour), and a wildcard or sub-minute step second takes a "for one
+// minute" frame (the whole minute-0 window). A non-zero minute is a real
+// clock minute: the second leads with its own "past the minute" clause (if
+// any), then the minute reads "M minutes past the hour".
+function hourCadenceLead(ir: IR, minute: number,
+  opts: NormalizedOptions): string {
+  if (minute === 0) {
+    if (subMinuteSecond(ir)) {
+      return secondsClause(ir, 'minute', opts) + ' for one minute';
+    }
+
+    return secondsClause(ir, 'hour', opts);
+  }
+
+  const minutePhrase = getNumber(minute, opts) + ' ' +
+    pluralize(minute, 'minute') + ' past the hour';
+
+  // A single 0 second is just the top of the minute, so the minute leads
+  // alone; any other second prefixes its own clause.
+  if (ir.pattern.second === '0') {
+    return minutePhrase;
+  }
+
+  return secondsClause(ir, 'minute', opts) + ', ' + minutePhrase;
+}
+
+// Render an hour step (or arithmetic-progression hour list) under a single
+// pinned minute and a second as a cadence — the lead clause, then the hour
+// cadence — instead of cross-multiplying the hours into a wall of clock
+// times. Returns null when the hour is not a stride (an irregular list, a
+// single hour, or a range), or when the cross-product is short enough that
+// enumeration is no longer than the cadence: a meaningful second (anything
+// but a plain :00) makes every clock time three digit-groups, so any stride
+// is worth compacting; otherwise the stride must exceed the clock-time cap,
+// the same point at which the core itself stops enumerating. Renderer-only;
+// the IR is unchanged.
+function hourCadence(ir: IR, minute: number,
+  opts: NormalizedOptions): string | null {
+  const stride = hourStride(ir);
+
+  if (!stride) {
+    return null;
+  }
+
+  const fires = (stride.last - stride.start) / stride.interval + 1;
+
+  if (ir.pattern.second === '0' && fires <= maxClockTimes) {
+    return null;
+  }
+
+  // A wildcard or sub-minute step second confined to minute 0 of a clean
+  // hour stride is a confinement, not a juxtaposed cadence: it reads "for one
+  // minute during every other hour", matching the "every minute during every
+  // other hour" idiom and keeping it distinct from the bare hour-step form
+  // ("every two hours") so the minute-0 confinement is never heard as it.
+  const confinement = minute === 0 && subMinuteSecond(ir) &&
+    cleanStrideSegment(ir);
+
+  if (confinement) {
+    return secondsClause(ir, 'minute', opts) + ' for one minute ' +
+      everyNthHour(confinement, opts) + trailingQualifier(ir, opts);
+  }
+
+  return hourCadenceLead(ir, minute, opts) + ', ' +
+    hourStrideCadence(stride, opts) + trailingQualifier(ir, opts);
+}
+
+// The hour step segment when the hour is a clean stride with an idiomatic
+// ordinal ("every other", "every sixth"), suitable for the "during every Nth
+// hour" confinement frame; null otherwise (an uneven stride, a bounded step,
+// or an arithmetic-progression list, which keep the bounded cadence form).
+function cleanStrideSegment(ir: IR): StepSegment | null {
+  // Reached only after hourStride confirmed a stride, so hour segments exist.
+  const segments = ir.analyses.segments.hour!;
+  const segment = segments.length === 1 && segments[0];
+
+  if (!segment || segment.kind !== 'step' ||
+      segment.startToken.indexOf('-') !== -1 ||
+      !(segment.interval in stepOrdinals)) {
+    return null;
+  }
+
+  return segment;
+}
+
 // --- List and segment phrasing. ---
 
 // Chicago number style for a series: if any value crosses the spell-out