cronli5 0.1.5 → 0.1.7

package/src/lang/es/index.ts

@@ -10,7 +10,9 @@
 
 import {clockDigits, numeral} from '../../core/format.js';
 import {maxClockTimes, weekdayNumbers} from '../../core/specs.js';
-import {arithmeticStep, toFieldNumber} from '../../core/util.js';
+import {
+  arithmeticStep, orderWeekdaysForDisplay, toFieldNumber
+} from '../../core/util.js';
 import type {Cronli5Options} from '../../types.js';
 import type {
   Field, HourTimesPlan, IR, Language, NormalizedOptions, PlanNode,
@@ -259,9 +261,24 @@ function composeHourCadence(
   const clockRest = plan.rest.kind === 'clockTimes' ||
     plan.rest.kind === 'compactClockTimes';
 
-  return clockRest && ir.shapes.minute === 'single' ?
-    hourCadence(ir, +ir.pattern.minute, opts) :
-    null;
+  if (!clockRest || ir.shapes.minute !== 'single') {
+    return null;
+  }
+
+  const minute = +ir.pattern.minute;
+
+  return hourCadence(ir, minute, opts) ?? hourRangeCadence(ir, minute, opts);
+}
+
+// A wildcard or stepped second with a fixed minute across one or more specific
+// hours: the seconds confine to the clock time(s), each minute named.
+function isPinnedMinuteSeconds(
+  ir: IR,
+  plan: Extract<PlanNode, {kind: 'composeSeconds'}>
+): plan is Extract<PlanNode, {kind: 'composeSeconds'}> &
+  {rest: Extract<PlanNode, {kind: 'clockTimes'}>} {
+  return plan.rest.kind === 'clockTimes' &&
+    (ir.shapes.second === 'wildcard' || ir.shapes.second === 'step');
 }
 
 function renderComposeSeconds(
@@ -281,8 +298,7 @@ function renderComposeSeconds(
 
   // A wildcard or stepped second with the minute pinned to a single value
   // across one or more specific hours: the seconds confine to the clock time.
-  if (plan.rest.kind === 'clockTimes' &&
-      (ir.shapes.second === 'wildcard' || ir.shapes.second === 'step')) {
+  if (isPinnedMinuteSeconds(ir, plan)) {
     return pinnedMinuteSeconds(ir, plan.rest, opts);
   }
 
@@ -299,7 +315,7 @@ function renderComposeSeconds(
   if (plan.rest.kind === 'hourRange' && ir.shapes.second === 'step' &&
       ir.pattern.weekday !== '*') {
     const restNode = plan.rest;
-    const window = hourWindow(restNode, opts);
+    const window = hourWindow(boundedWindow(restNode), opts);
     const dayFrame = weekdayQualifier(ir) + monthScope(ir);
     const cadence = 'cada ' +
       numero(stepSegment(ir.analyses.segments.second).interval, opts) +
@@ -317,7 +333,15 @@ function renderComposeSeconds(
     return secondsLeadClause(ir, opts) + ' de ' + render(ir, plan.rest, opts);
   }
 
-  return secondsLeadClause(ir, opts) + ', ' + render(ir, plan.rest, opts);
+  // A compact clock-time rest folds a meaningful SINGLE second into its own
+  // leading clause, so the composer must not prepend a second lead that would
+  // double it. A wildcard or stepped second is not folded there (no
+  // clockSecond), so it still leads its own clause here.
+  const restOwnsLead = plan.rest.kind === 'compactClockTimes' &&
+    ir.analyses.clockSecond;
+  const lead = restOwnsLead ? '' : secondsLeadClause(ir, opts) + ', ';
+
+  return lead + render(ir, plan.rest, opts);
 }
 
 // A wildcard second over an unoffset minute */2 with a wildcard hour: the two
@@ -354,7 +378,12 @@ function pinnedMinuteSeconds(
   const dayTrail = leadingQualifier(ir, opts).trimEnd();
   const trail = dayTrail ? ', ' + dayTrail : '';
 
-  if (+rest.times[0].minute === 0) {
+  // The "durante un minuto a las 9" duration form drops the clock minute, so it
+  // is correct only when the minute is a SINGLE 0 — every clock time at :00. A
+  // minute LIST whose first value is 0 (e.g. */45 → :00, :45) must name each
+  // minute, never collapse to the bare hour (which once repeated it, "a las 9 y
+  // 9"), so it takes the explicit clock list.
+  if (+rest.times[0].minute === 0 && ir.shapes.minute === 'single') {
     return secondsLeadClause(ir, opts) + ' durante un minuto ' +
       durationHourList(rest.times, opts) + trail;
   }
@@ -555,11 +584,20 @@ function renderMinuteFrequency(
     'hora', opts);
 
   if (plan.hours.kind === 'during') {
-    // An offset step (e.g. 1/2) arrives here; a single step reads as a
-    // confinement, not the verbose window list.
-    phrase += singleHourStep(ir.analyses.segments.hour) ?
-      ', ' + stepHourSpan(stepSegment(ir.analyses.segments.hour), opts) :
-      ' ' + hourSpanFromTimes(ir, plan.hours.times, opts);
+    // A uneven hour stride confines the minute cadence to its own bounded hour
+    // cadence ("cada 15 minutos, cada cinco horas de las 00:00 a las 20:00").
+    const cadence = unevenHourCadence(ir, opts);
+
+    if (cadence) {
+      phrase += ', ' + cadence;
+    }
+    else {
+      // An offset step (e.g. 1/2) arrives here; a single step reads as a
+      // confinement, not the verbose window list.
+      phrase += singleHourStep(ir.analyses.segments.hour) ?
+        ', ' + stepHourSpan(stepSegment(ir.analyses.segments.hour), opts) :
+        ' ' + hourSpanFromTimes(ir, plan.hours.times, opts);
+    }
   }
   else if (plan.hours.kind === 'window') {
     phrase += ' ' + hourWindow(plan.hours, opts);
@@ -602,7 +640,15 @@ function renderMinutesAcrossHours(
   plan: Extract<PlanNode, {kind: 'minutesAcrossHours'}>,
   opts: Opts
 ): string {
+  // A uneven hour stride reads as a cadence, not a wall of hour columns: the
+  // minute lead, then "cada N horas de las X a las Y".
+  const cadence = unevenHourCadence(ir, opts);
+
   if (plan.form === 'wildcard') {
+    if (cadence !== null) {
+      return 'cada minuto, ' + cadence + trailingQualifier(ir, opts);
+    }
+
     if (singleHourStep(ir.analyses.segments.hour)) {
       return 'cada minuto, ' +
         stepHourSpan(stepSegment(ir.analyses.segments.hour), opts) +
@@ -617,6 +663,10 @@ function renderMinutesAcrossHours(
     minuteRangeLead(ir.pattern.minute) :
     minutesList(ir, opts);
 
+  if (cadence !== null) {
+    return lead + ', ' + cadence + trailingQualifier(ir, opts);
+  }
+
   return lead + ', ' + atHourTimes(ir, plan.times, opts) +
     trailingQualifier(ir, opts);
 }
@@ -627,9 +677,12 @@ function renderMinuteSpanAcrossHourStep(
   opts: Opts
 ): string {
   const segment = stepSegment(ir.analyses.segments.hour);
+  // A bounded or uneven hour step reads as its endpoint-pinning cadence; an
+  // offset-clean step keeps its confinement / per-step phrasing.
+  const cadence = unevenHourCadence(ir, opts);
 
-  // A wildcard minute (a cadence) is reached only for a clean stride and is
-  // confined; a plain range is a per-hour window keyed to the step.
+  // A wildcard minute (a cadence) is reached only for a clean stride (a bounded
+  // or uneven step routes through minutesAcrossHours instead) and is confined.
   if (plan.form === 'wildcard') {
     return 'cada minuto, ' + stepHourSpan(segment, opts) +
       trailingQualifier(ir, opts);
@@ -642,7 +695,8 @@ function renderMinuteSpanAcrossHourStep(
     minutesList(ir, opts) :
     minuteRangeLead(ir.pattern.minute);
 
-  return lead + ', ' + stepHours(segment, opts) + trailingQualifier(ir, opts);
+  return lead + ', ' +
+    (cadence ?? stepHours(segment, opts)) + trailingQualifier(ir, opts);
 }
 
 // --- Hour renderers. ---
@@ -689,17 +743,31 @@ function renderHourStep(
   plan: Extract<PlanNode, {kind: 'hourStep'}>,
   opts: Opts
 ): string {
+  // A bounded or uneven hour step reads as its endpoint-pinning cadence ("cada
+  // dos horas de las 09:00 a las 17:00"); an offset-clean step keeps its bare
+  // or "a partir de" cadence.
+  const cadence = unevenHourCadence(ir, opts);
+
+  if (cadence !== null) {
+    return cadence + trailingQualifier(ir, opts);
+  }
+
   return stepHours(stepSegment(ir.analyses.segments.hour), opts) +
     trailingQualifier(ir, opts);
 }
 
-// The hour-range plan as a window whose closing minute honors `boundMinute`:
-// a bare close (`null`) lands on the top of the final hour (minute 0),
-// matching the minute-0 baseline, with the minutes stated separately.
+// The hour-range plan as a window. The close lands on the top of the final
+// hour (minute 0) unless the minute genuinely runs to the end of that hour —
+// i.e. a wildcard minute, which fills every minute and states no separate
+// clause. A pinned/listed/ranged minute is named in its own lead clause, so
+// folding it into the close too would read as a span ("a las 17:05") that
+// contradicts the minute clause; the window stays bare ("a las 17:00").
 function boundedWindow(
   plan: Extract<PlanNode, {kind: 'hourRange'}>
 ): {from: number; to: number; last: number} {
-  return {from: plan.from, last: plan.boundMinute ?? 0, to: plan.to};
+  const last = plan.minuteForm === 'wildcard' ? plan.boundMinute ?? 0 : 0;
+
+  return {from: plan.from, last, to: plan.to};
 }
 
 // "de las 9:00 a las 17:45": a window from the top of the first hour to
@@ -778,7 +846,9 @@ function dowArm(ir: IR): string {
     return quartz;
   }
 
-  const segments = flattenSteps(fieldSegments(ir, 'weekday'));
+  // Weekday lists display Monday-first (Sunday last); a lone range keeps its
+  // form. The IR stays canonical (Sunday=0). The helper flattens steps.
+  const segments = orderWeekdaysForDisplay(fieldSegments(ir, 'weekday'));
   const allSingles = segments.every(function single(segment) {
     return segment.kind === 'single';
   });
@@ -817,10 +887,13 @@ function renderClockTimes(
   plan: Extract<PlanNode, {kind: 'clockTimes'}>,
   opts: Opts
 ): 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.
+  // An hour step or range (or arithmetic-progression hour list) under a single
+  // pinned minute reads as a cadence or window rather than a cross-product of
+  // clock times.
   if (ir.shapes.minute === 'single') {
-    const cadence = hourCadence(ir, +ir.pattern.minute, opts);
+    const minute = +ir.pattern.minute;
+    const cadence = hourCadence(ir, minute, opts) ??
+      hourRangeCadence(ir, minute, opts);
 
     if (cadence !== null) {
       return cadence;
@@ -1162,10 +1235,11 @@ function renderCompactClockTimes(
   opts: Opts
 ): 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);
+    // An hour step or range (or arithmetic-progression hour list) under the
+    // single pinned minute reads as a cadence or window, not a wall of clock
+    // times. (Returns null for an irregular list, which keeps folding below.)
+    const cadence = hourCadence(ir, plan.minute, opts) ??
+      hourRangeCadence(ir, plan.minute, opts);
 
     if (cadence !== null) {
       return cadence;
@@ -1187,8 +1261,13 @@ function renderCompactClockTimes(
       hourSegmentTimes(ir, plan.minute, ir.analyses.clockSecond, opts);
   }
 
-  const phrase = minutesList(ir, opts) + ', ' +
-    hourSegmentTimes(ir, 0, null, opts) + trailingQualifier(ir, opts);
+  // A uneven hour stride reads as a cadence after the minute lead, not a wall
+  // of clock-time columns.
+  const cadence = unevenHourCadence(ir, opts);
+  const phrase = cadence ?
+    minutesList(ir, opts) + ', ' + cadence + trailingQualifier(ir, opts) :
+    minutesList(ir, opts) + ', ' +
+      hourContextTimes(ir, opts) + trailingQualifier(ir, opts);
 
   return ir.analyses.clockSecond ?
     secondsLeadClause(ir, opts) + ', ' + phrase :
@@ -1373,12 +1452,75 @@ function hourStrideCadence(
     timePhrase(last, 0, null, opts);
 }
 
+// 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 "a partir de" 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 the ends of.
+function offsetCleanStride(
+  stride: {start: number; interval: number}
+): boolean {
+  return stride.start < stride.interval && 24 % stride.interval === 0;
+}
+
+// The bounded cadence for an hour stride that pins both clock-time endpoints,
+// or null when the hour is not such a stride. The core rewrites a uneven step
+// to its fire list, so a minute window/list/step crossed with it lands in the
+// enumerating list paths; there the bounded hour reads better as its cadence
+// ("…, cada cinco horas de las 00:00 a las 20:00") than as a wall of clock
+// times. An offset-clean stride keeps its existing confinement form, so only
+// the endpoint-bearing case routes here.
+function unevenHourCadence(ir: IR, opts: Opts): string | null {
+  const stride = hourStride(ir);
+
+  if (!stride || offsetCleanStride(stride)) {
+    return null;
+  }
+
+  return hourStrideCadence(stride, opts);
+}
+
+// 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 progression 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). 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]};
+}
+
 // 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.
+// list yields one only when its values form a step 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 {
@@ -1386,6 +1528,13 @@ function hourStride(
 
   if (segments.length === 1 && segments[0].kind === 'step') {
     const segment = segments[0];
+
+    // A bounded step that fires only once (e.g. `9-10/5` -> just 9) is a single
+    // value, not a stride: it has no interval to speak and no endpoint to pin.
+    if (segment.fires.length < 2) {
+      return null;
+    }
+
     const start = segment.startToken === '*' ?
       0 :
       +segment.startToken.split('-')[0];
@@ -1395,9 +1544,8 @@ function hourStride(
   }
 
   const values = singleValues(segments);
-  const step = values && arithmeticStep(values);
 
-  return step || null;
+  return values && hourListStride(values);
 }
 
 // The second's status against a pinned minute: a wildcard or sub-minute step
@@ -1452,7 +1600,13 @@ function hourCadence(ir: IR, minute: number, opts: Opts): string | null {
 
   const fires = (stride.last - stride.start) / stride.interval + 1;
 
-  if (ir.pattern.second === '0' && fires <= maxClockTimes) {
+  // A short stride that spells out as few clock times stays an enumeration only
+  // when it wraps cleanly (an offset-clean stride with no endpoint): the bare
+  // or "a partir de" form is no shorter than the list. A bounded or uneven
+  // stride has no clean wrap, so its endpoint-pinning cadence ("cada cinco
+  // horas de las 00:00 a las 20:00") reads better however short.
+  if (ir.pattern.second === '0' && fires <= maxClockTimes &&
+      offsetCleanStride(stride)) {
     return null;
   }
 
@@ -1468,6 +1622,13 @@ function hourCadence(ir: IR, minute: number, opts: Opts): string | null {
       stepHourSpan(confinement, opts) + trailingQualifier(ir, opts);
   }
 
+  // A plain top-of-the-hour fire (minute 0 with no meaningful second) has no
+  // lead clause to fold in, so the bounded cadence stands on its own ("cada
+  // cinco horas de las 00:00 a las 20:00").
+  if (minute === 0 && ir.pattern.second === '0') {
+    return hourStrideCadence(stride, opts) + trailingQualifier(ir, opts);
+  }
+
   return hourCadenceLead(ir, minute, opts) + ', ' +
     hourStrideCadence(stride, opts) + trailingQualifier(ir, opts);
 }
@@ -1488,8 +1649,112 @@ function cleanStrideSegment(ir: IR): StepSegment | null {
   return segment;
 }
 
+// Whether the hour field is a range — or a list whose segments include a
+// range — and so forms a window rather than a cross-product of clock times.
+// A pure single-value list (9,17) has no range to span and still enumerates;
+// a step is handled by hourStride/hourCadence.
+function hasHourWindow(ir: IR): boolean {
+  return hourSegments(ir).some(function range(segment) {
+    return segment.kind === 'range';
+  });
+}
+
+// Render an hour range (or a list whose segments include a range) under
+// minute 0 and a meaningful second as the hour-range window — the lead clause,
+// then "de las 09:00 a las 17:00" (and any non-contiguous hour joined with
+// "y también") — instead of cross-multiplying the hours into a wall of clock
+// times. The hour-RANGE analog of hourCadence. Returns null when the hour has
+// no range, when the minute is non-zero (a real clock minute the existing
+// window form already speaks), or when a plain :00 set carries no clause.
+// Renderer-only; the IR is unchanged.
+function hourRangeCadence(ir: IR, minute: number, opts: Opts): string | null {
+  if (minute !== 0 || !hasHourWindow(ir) || ir.pattern.second === '0') {
+    return null;
+  }
+
+  // A wildcard or sub-minute step second confined to minute 0 is the whole
+  // minute-0 window ("durante un minuto"), confined to the hour range with the
+  // "durante las horas …" idiom — kept distinct from the bare minute-0 window
+  // ("cada hora de las 09:00 a las 17:00") so the confinement is never heard
+  // as it — the hour-range analog of "durante un minuto, durante las horas
+  // pares".
+  if (subMinuteSecond(ir)) {
+    return secondsClause(ir, 'minuto', opts) + ' durante un minuto, ' +
+      'durante las horas ' + hourSegmentTimes(ir, 0, null, opts) +
+      trailingQualifier(ir, opts);
+  }
+
+  return hourCadenceLead(ir, minute, opts) + ', ' +
+    hourSegmentTimes(ir, 0, null, opts) + trailingQualifier(ir, opts);
+}
+
 // --- Hour-time phrasing. ---
 
+// The fixed hour(s) of a stepped/listed minute, named as the HOUR rather than a
+// "a las HH:00" clock instant the minute never fires at: noon and midnight read
+// as the hour word ("al mediodía"/"a medianoche"), any other hour as the whole
+// hour "de la hora de las HH:00" (the idiom a wildcard minute already uses).
+// Used by the compact-clock non-fold path, where the minute is a step or list
+// (a single-value minute keeps its real "a las HH:MM" clock time elsewhere).
+function hourContextTimes(ir: IR, opts: Opts): string {
+  const segments = hourSegments(ir);
+
+  // Collect the point hours (singles and step fires) — a range stays a window.
+  const points: number[] = [];
+  const hasRange = segments.some(function range(segment) {
+    return segment.kind === 'range';
+  });
+
+  segments.forEach(function collect(segment) {
+    if (segment.kind === 'step') {
+      points.push(...segment.fires);
+    }
+    else if (segment.kind === 'single') {
+      points.push(+segment.value);
+    }
+  });
+
+  // All point hours, all noon/midnight: stand alone as their own words ("a
+  // medianoche y al mediodía").
+  function isWord(hour: number): boolean {
+    return !opts.ampm && (hour === 0 || hour === 12);
+  }
+
+  if (!hasRange && points.every(isWord)) {
+    return joinList(points.map(function each(hour) {
+      return atTime(bareHourPhrase(hour, opts));
+    }));
+  }
+
+  // A point hour as the whole hour: "de la hora de las HH:00".
+  function wholeHour(hour: number): string {
+    return 'de la hora ' + fromTime(explicitTimePhrase(hour, 0, opts));
+  }
+
+  // Otherwise each whole hour reads as a window ("de las HH:00 a las HH:00" for
+  // a range, "de la hora de las HH:00" for a point), never a false "a las
+  // HH:00" clock instant the stepped minute never fires at.
+  const pieces: string[] = [];
+
+  segments.forEach(function place(segment) {
+    if (segment.kind === 'range') {
+      pieces.push(timeRange(
+        {hour: +segment.bounds[0], minute: 0},
+        {hour: +segment.bounds[1], minute: 0}, opts));
+    }
+    else if (segment.kind === 'step') {
+      segment.fires.forEach(function each(hour) {
+        pieces.push(wholeHour(hour));
+      });
+    }
+    else {
+      pieces.push(wholeHour(+segment.value));
+    }
+  });
+
+  return joinList(pieces);
+}
+
 // "a las 9:00" / "a la 1:00" / "al mediodía" for each fire hour.
 function atTimes(hours: number[], opts: Opts): string[] {
   return hours.map(function each(hour) {
@@ -1940,7 +2205,9 @@ function weekdayQualifier(ir: IR): string {
     return quartz;
   }
 
-  const segments = flattenSteps(fieldSegments(ir, 'weekday'));
+  // Weekday lists display Monday-first (Sunday last); a lone range keeps its
+  // form. The IR stays canonical (Sunday=0). The helper flattens steps.
+  const segments = orderWeekdaysForDisplay(fieldSegments(ir, 'weekday'));
   const allSingles = segments.every(function single(segment) {
     return segment.kind === 'single';
   });