cronli5 0.2.1 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cronli5",
-  "version": "0.2.1",
+  "version": "0.3.4",
   "description": "Cron Like I'm Five: A Cron to English Utility",
   "repository": {
     "type": "git",
@@ -65,11 +65,11 @@
     "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",
+    "test": "vitest run",
     "types": "tsc -p tsconfig.types.json",
     "test:types": "npm run types && tsd",
     "typecheck": "tsc -p tsconfig.json",
-    "coverage": "c8 mocha",
+    "coverage": "vitest run --coverage",
     "verify": "npm run lint && npm run typecheck && npm run test:types && npm test && npm run coverage && npm run conciseness && npm run docs -- --check && npm run build",
     "prepare": "node scripts/install-hooks.mjs",
     "prepublishOnly": "npm run lint && npm run typecheck && npm run test:types && npm run build && npm test"
@@ -90,18 +90,18 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.15.0",
-    "c8": "^10.1.3",
+    "@vitest/coverage-v8": "^4.1.9",
     "chai": "^4.5.0",
     "cronstrue": "^3.14.0",
     "esbuild": "^0.28.1",
     "eslint": "^9.15.0",
     "fast-check": "^3.23.1",
     "globals": "^15.12.0",
-    "mocha": "^11.0.1",
     "tsd": "^0.31.2",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.0"
+    "typescript-eslint": "^8.61.0",
+    "vitest": "^4.1.9"
   },
   "tsd": {
     "directory": "test-d"

package/src/core/analyze.ts

@@ -1,14 +1,14 @@
 // Semantic analysis of canonical fields: fire enumeration, windows, shape
 // classification, and description-plan selection (the `plan`). The
-// resulting IR is descriptive. Language modules handle rendering into
+// resulting Schedule is descriptive. Language modules handle rendering into
 // words (docs/i18n-design.md §2.2).
 
 import {fieldOrder, fieldSpecs, maxClockTimes} from './specs.js';
 import type {FieldSpec} from './specs.js';
 import type {
-  Analyses, ClockTime, Content, Field, HourTimesPlan, HoursPlan, IR, Pattern,
-  PlanNode, Segment, Shape, Shapes
-} from './ir.js';
+  Analyses, ClockTime, Field, HourTimesPlan, HoursPlan, Pattern,
+  PlanNode, Schedule, ScheduleFacts, Segment, Shape, Shapes
+} from './schedule.js';
 import {includes, toFieldNumber, unique} from './util.js';
 import {isDiscreteHours, isDiscreteList, isPlainRange, isSingleValue}
   from './shapes.js';
@@ -198,8 +198,8 @@ function fieldSegments(
 }
 
 // Analyze a prepared (parsed, validated, normalized) cron pattern into the
-// IR a language module renders from.
-function analyze(pattern: Pattern): IR {
+// Schedule a language module renders from.
+function analyze(pattern: Pattern): Schedule {
   const shapes = {} as Shapes;
   const segments = {} as Analyses['segments'];
 
@@ -216,18 +216,18 @@ function analyze(pattern: Pattern): IR {
     segments
   };
 
-  const content: Content = {analyses, pattern, shapes};
+  const facts: ScheduleFacts = {analyses, pattern, shapes};
 
-  return {...content, plan: selectPlan(content)};
+  return {...facts, plan: selectPlan(facts)};
 }
 
-// Select the description plan from the neutral content. This is the
+// Select the description plan from the neutral facts. This is the
 // core's *suggestion*: a language may override it via `Language.plan`
-// without re-deriving it (the content-plan / overridable-plan split).
+// without re-deriving it (the facts / overridable-plan split).
 // The selection mirrors the interpreter chain ordering exactly; renderers
 // must not re-derive it.
-function selectPlan(content: Content): PlanNode {
-  const {analyses, pattern, shapes} = content;
+function selectPlan(facts: ScheduleFacts): PlanNode {
+  const {analyses, pattern, shapes} = facts;
 
   if (pattern.second !== '0') {
     const seconds = planSeconds(pattern, shapes, analyses);

package/src/core/cadence.ts

@@ -0,0 +1,164 @@
+// Cadence analysis: recognizing arithmetic progressions and step strides in a
+// field's values, and the segment accessors renderers use to reach them.
+// Output-neutral and language-agnostic; renderers speak the cadence they find.
+
+import type {Field, Schedule, Segment} from './schedule.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'}>;
+
+// 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]};
+}
+
+// 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(schedule: Schedule, field: Field): Segment[] {
+  return schedule.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(schedule: Schedule, field: Field): StepSegment {
+  return segmentsOf(schedule, 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;
+}
+
+// The three branches of the stride/cadence decision tree, supplied by a
+// renderer as its own words. The core picks the branch; the language owns the
+// prose. `bare` is the clean cadence ("every N <unit>"); `offset` names only
+// the start (a clean wrap with no distinct endpoint); `bounded` pins both
+// endpoints (a non-wrapping set). Each is a thunk so the renderer evaluates
+// only the branch the core selects (e.g. a stateful bound formatter is never
+// constructed for the bare case). The words differ per language — case
+// inflection, a measure word, a trailing idiom — so the leaves stay here, not
+// in core.
+interface StrideParts {
+  bare(): string;
+  offset(): string;
+  bounded(): string;
+}
+
+// Choose the stride/cadence branch for a step over a `cycle`-long field and
+// emit the renderer's words for it. 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
+// with 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 decision tree every
+// renderer's `renderStride`/`hourStrideCadence` shared (cycle 60 for
+// minute/second, 24 for the hour); the branch lives here once, the prose in
+// each language's `parts`.
+function renderStride(
+  spec: {start: number; interval: number; cycle: number},
+  parts: StrideParts
+): string {
+  const {start, interval, cycle} = spec;
+  const tiles = cycle % interval === 0;
+
+  if (start === 0 && tiles) {
+    return parts.bare();
+  }
+
+  if (start < interval && tiles) {
+    return parts.offset();
+  }
+
+  return parts.bounded();
+}
+
+// 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 Schedule 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, hourListStride, offsetCleanStride, renderStride, segmentsOf,
+  singleValues, stepSegment
+};
+export type {StrideParts};

package/src/core/index.ts

@@ -4,7 +4,7 @@
 // See docs/i18n-design.md.
 
 import {applyQuartzAliases, normalizeCronPattern} from './normalize.js';
-import type {NormalizedOptions, Pattern} from './ir.js';
+import type {NormalizedOptions, Pattern} from './schedule.js';
 import {parseCronPattern} from './parse.js';
 import type {CronPattern} from '../types.js';
 import {validateCronPattern} from './validate.js';
@@ -24,5 +24,7 @@ function prepare(cronPattern: CronPattern, opts: NormalizedOptions): Pattern {
 export {prepare};
 export * from './specs.js';
 export * from './util.js';
+export * from './weekday.js';
+export * from './cadence.js';
 export * from './shapes.js';
 export * from './analyze.js';

package/src/core/normalize.ts

@@ -4,7 +4,7 @@
 
 import {fieldOrder, fieldSpecs} from './specs.js';
 import type {CronLike, FieldSpec} from './specs.js';
-import type {Field, Pattern} from './ir.js';
+import type {Field, Pattern} from './schedule.js';
 import {includes, toFieldNumber, unique} from './util.js';
 import {isQuartzDate, isQuartzWeekday} from './validate.js';
 
@@ -68,7 +68,7 @@ function normalizeField(value: string, field: Field, spec: FieldSpec): string {
   const cycle = timeFieldCycle[field];
   const segments = stringValue.split(',').map(function canonical(segment) {
     return canonicalizeTokens(collapseFullSpanRange(
-      enumerateNonUniformStep(
+      enumerateIfNonUniform(
         collapseFullSpanStep(
           collapseDegenerateRange(
             collapseOnceStep(collapseUnitStep(segment, spec), spec), spec),
@@ -172,7 +172,7 @@ function collapseOnceStep(segment: string, spec: FieldSpec): string {
 // list of those fires (`*/7` is `0,7,14,…`), the same as if it were written
 // out. Calendar fields (no `cycle`), bounded steps (`9-17/2`, a per-window
 // stride), and non-step segments are left untouched.
-function enumerateNonUniformStep(
+function enumerateIfNonUniform(
   segment: string,
   spec: FieldSpec,
   cycle: number | undefined

package/src/core/parse.ts

@@ -2,7 +2,7 @@
 
 import {macros} from './specs.js';
 import type {CronLike} from './specs.js';
-import type {NormalizedOptions} from './ir.js';
+import type {NormalizedOptions} from './schedule.js';
 import type {CronPattern, CronPatternObject} from '../types.js';
 
 // Take a cron pattern as a cron pattern string, an array of cron fields, a

package/src/core/{ir.ts → schedule.ts}

@@ -1,8 +1,7 @@
-// An Intermediate Representation (`IR`) is the semantic contract between
-// the core and a language renderer. The core (parse → validate →
-// normalize → analyze) produces an IR, then a language module renders it to
-// prose. These shapes are what any new language module interacts with. See
-// docs/i18n-design.md.
+// A `Schedule` is the semantic contract between the core and a language
+// renderer. The core (parse → validate → normalize → analyze) produces a
+// `Schedule`, then a language module renders it to prose. These shapes are
+// what any new language module interacts with. See docs/i18n-design.md.
 
 import type {Cronli5Options} from '../types.js';
 
@@ -42,8 +41,7 @@ export type HoursPlan =
   | {kind: 'none'}
   | {kind: 'step'}
   | {kind: 'window'; from: number; to: number; last: number}
-  | {kind: 'during'; times: HourTimesPlan}
-  | {kind: 'single'; from: number; to: number; last: number};
+  | {kind: 'during'; times: HourTimesPlan};
 
 /** Hour times: enumerated fires, or deferred to per-segment rendering. */
 export type HourTimesPlan =
@@ -99,24 +97,25 @@ export interface Analyses {
 }
 
 /**
- * The neutral content plan: the language-independent facts about a pattern,
+ * The neutral schedule facts: the language-independent facts about a pattern,
  * 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).
+ * part of the neutral facts (docs/i18n-design.md §2.2).
  */
-export interface Content {
+export interface ScheduleFacts {
   pattern: Pattern;
   shapes: Shapes;
   analyses: Analyses;
 }
 
 /**
- * The semantic intermediate representation a language renders: the neutral
- * `Content` plus the selected `plan`. A language may widen `plan` with its
- * own `Extra` plan kinds via `Language.plan`; by default there are
- * none, so `IR` is the neutral content with a core `PlanNode`.
+ * The semantic schedule a language renders: the neutral `ScheduleFacts`
+ * plus the selected `plan`. A language may widen `plan` with its own
+ * `Extra` plan kinds via `Language.plan`; by default there are none, so
+ * `Schedule` is the neutral facts with a core `PlanNode`.
  */
-export interface IR<Extra extends {kind: string} = never> extends Content {
+export interface Schedule<Extra extends {kind: string} = never>
+  extends ScheduleFacts {
   plan: PlanNode | Extra;
 }
 
@@ -163,7 +162,7 @@ export interface Language<
   Style = DialectStyle,
   Extra extends {kind: string} = never
 > {
-  describe(ir: IR<Extra>, opts: NormalizedOptions<Style>): string;
+  describe(schedule: Schedule<Extra>, opts: NormalizedOptions<Style>): string;
   fallback: string;
   options(options?: Cronli5Options): NormalizedOptions<Style>;
   reboot: string;
@@ -171,8 +170,8 @@ export interface Language<
   // form); each language owns its lead verb and punctuation.
   sentence(description: string): string;
   // Optionally override the core's suggested plan. Receives the neutral
-  // `content` and the core's suggestion (`base`), so overriding is a thin
+  // `facts` 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).
-  plan?(content: Content, base: PlanNode): PlanNode | Extra;
+  plan?(facts: ScheduleFacts, base: PlanNode): PlanNode | Extra;
 }

package/src/core/specs.ts

@@ -1,6 +1,6 @@
 // Field specifications, macros, and core policy constants.
 
-import type {Field} from './ir.js';
+import type {Field} from './schedule.js';
 
 /**
  * A parsed but not-yet-canonical cron pattern: every field present, values

package/src/core/util.ts

@@ -1,12 +1,6 @@
-// Small shared utilities for the core.
-
-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'}>;
+// Generic pure helpers shared across the core.
 
+// Whether a string contains a substring (coercing numbers to strings).
 function includes(str: string | number, sub: string): boolean {
   return ('' + str).indexOf(sub) !== -1;
 }
@@ -23,82 +17,6 @@ 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]};
-}
-
-// The display sort key for a canonical weekday number: Monday (1) first,
-// Sunday (0) last. The IR keeps Sunday=0 canonical; this is display-only.
-function weekdayDisplayKey(value: number): number {
-  return value === 0 ? 7 : value;
-}
-
-// A weekday display segment: a single day or a (possibly wrap) range. Steps
-// are flattened away into singles before sorting, so the result is only these
-// two kinds; each renderer turns them into names exactly as it does today.
-type WeekdaySegment =
-  | {kind: 'single'; value: string}
-  | {kind: 'range'; bounds: [string, string]};
-
-// Reorder weekday segments Monday-first (Sunday last) for display, so a weekend
-// list reads "Saturday and Sunday" rather than the canonical Sunday-first
-// "Sunday and Saturday". Display-only: the IR / canonical order is unchanged (a
-// fresh array is returned). A step expands to its fires as singles so the days
-// sort into the list; a range stays one unit and keeps its own bounds order (a
-// wrap range is not reordered into a list), sorting by its opening bound — so a
-// lone range sorts to a one-element list and is unchanged. The sort is stable,
-// so equal opening days keep input order.
-function orderWeekdaysForDisplay(segments: Segment[]): WeekdaySegment[] {
-  const flattened: WeekdaySegment[] = segments.flatMap(function flat(segment) {
-    return segment.kind === 'step' ?
-      segment.fires.map(function single(value): WeekdaySegment {
-        return {kind: 'single', value: '' + value};
-      }) :
-      [segment];
-  });
-
-  function key(segment: WeekdaySegment): number {
-    return segment.kind === 'range' ?
-      weekdayDisplayKey(+segment.bounds[0]) :
-      weekdayDisplayKey(+segment.value);
-  }
-
-  return flattened
-    .map(function index(segment, position): [WeekdaySegment, number] {
-      return [segment, position];
-    })
-    .sort(function byDisplayKey(a, b): number {
-      return key(a[0]) - key(b[0]) || a[1] - b[1];
-    })
-    .map(function unwrap(pair): WeekdaySegment {
-      return pair[0];
-    });
-}
-
 // Resolve a numeric or named field token (e.g. '5' or 'FRI') to its number.
 function toFieldNumber(
   token: string,
@@ -108,85 +26,5 @@ 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, hourListStride, includes, isNonNegativeInteger,
-  offsetCleanStride, orderWeekdaysForDisplay, segmentsOf, singleValues,
-  stepSegment, toFieldNumber, unique
-};
+export {includes, isNonNegativeInteger, toFieldNumber, unique};

package/src/core/validate.ts

@@ -3,7 +3,7 @@
 
 import {fieldOrder, fieldSpecs} from './specs.js';
 import type {CronLike, FieldSpec} from './specs.js';
-import type {Field} from './ir.js';
+import type {Field} from './schedule.js';
 import {includes, isNonNegativeInteger, toFieldNumber} from './util.js';
 
 // Validate every field of a cron-like object, throwing on the first

package/src/core/weekday.ts

@@ -0,0 +1,54 @@
+// Weekday display ordering: present weekdays Monday-first (Sunday last),
+// independent of the Schedule's canonical Sunday=0 order. Display-only.
+
+import type {Segment} from './schedule.js';
+
+// The display sort key for a canonical weekday number: Monday (1) first,
+// Sunday (0) last. The Schedule keeps Sunday=0 canonical; this is display-only.
+function weekdayDisplayKey(value: number): number {
+  return value === 0 ? 7 : value;
+}
+
+// A weekday display segment: a single day or a (possibly wrap) range. Steps
+// are flattened away into singles before sorting, so the result is only these
+// two kinds; each renderer turns them into names exactly as it does today.
+type WeekdaySegment =
+  | {kind: 'single'; value: string}
+  | {kind: 'range'; bounds: [string, string]};
+
+// Reorder weekday segments Monday-first (Sunday last) for display, so a weekend
+// list reads "Saturday and Sunday" rather than the canonical Sunday-first
+// "Sunday and Saturday". Display-only: the Schedule / canonical order is
+// unchanged (a fresh array is returned). A step expands to its fires as singles
+// so the days sort into the list; a range stays one unit and keeps its own
+// bounds order (a wrap range is not reordered into a list), sorting by its
+// opening bound — so a lone range sorts to a one-element list and is unchanged.
+// The sort is stable, so equal opening days keep input order.
+function orderWeekdaysForDisplay(segments: Segment[]): WeekdaySegment[] {
+  const flattened: WeekdaySegment[] = segments.flatMap(function flat(segment) {
+    return segment.kind === 'step' ?
+      segment.fires.map(function single(value): WeekdaySegment {
+        return {kind: 'single', value: '' + value};
+      }) :
+      [segment];
+  });
+
+  function key(segment: WeekdaySegment): number {
+    return segment.kind === 'range' ?
+      weekdayDisplayKey(+segment.bounds[0]) :
+      weekdayDisplayKey(+segment.value);
+  }
+
+  return flattened
+    .map(function index(segment, position): [WeekdaySegment, number] {
+      return [segment, position];
+    })
+    .sort(function byDisplayKey(a, b): number {
+      return key(a[0]) - key(b[0]) || a[1] - b[1];
+    })
+    .map(function unwrap(pair): WeekdaySegment {
+      return pair[0];
+    });
+}
+
+export {orderWeekdaysForDisplay};