cronli5 0.0.0-beta.6 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,276 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Per-language documentation** under `docs/lang/` (`en.md`, `es.md`,
+  `fi.md`): usage, style anchors, dialects, and the language's
+  distinctive conventions, each with a generated cronli5-vs-cRonstrue
+  table against the matching cRonstrue locale. The tables share a
+  twelve-row cross-language pattern set plus per-language grammar rows,
+  are regenerated by `npm run docs`, and are covered by the same
+  `--check` staleness gate as the English head-to-head. The README
+  gained a Languages section and no longer describes the library as
+  English-only.
+- Language subpaths (`cronli5/lang/en`, `cronli5/lang/es`,
+  `cronli5/lang/fi`) now ship dual built artifacts:
+  `require('cronli5/lang/es')` works alongside `import`, and each
+  subpath carries a `types` condition (a shared `Cronli5Language`
+  declaration in `lang.d.ts`). Previously the subpaths exposed ESM
+  source only.
+- **Finnish** (`cronli5/lang/fi`), the agglutinative stress test from
+  the i18n design (docs/i18n-design.md §5): a full natural-Finnish
+  renderer anchored to Kielitoimiston ohjepankki and SFS 4175 —
+  "maanantaista perjantaihin klo 9.30", "kuukauden viimeisenä
+  perjantaina keskiyöllä", "viiden minuutin välein". Weekdays are
+  stored as inflected forms (consonant gradation: keskiviikosta),
+  ranges are case pairs on names and en-dash notation on digits
+  ("klo 9.00–17.45"), and written Finnish being 24-hour only, the
+  `ampm` option is ignored. Ships with a reviewed corpus, minimal
+  pairs, language notes, and a review log under `test/lang/fi/`.
+  Like Spanish, Finnish required zero core changes.
+
+- Descriptions for **lists containing range or step segments** (e.g.
+  `0-30,45` or `9,17-19`) in every field. Minute and second lists read their
+  spans discretely (`at five through ten and 20 minutes past the hour`), hour
+  list segments expand into clock times, and date/month/weekday list segments
+  render as ordinals, names, or weekday spans.
+- A minute wildcard or plain range now composes with an **hour list**
+  (`every minute during the 9 a.m. and 5 p.m. hours`) and an **hour step**
+  (`every minute from zero through 30 past the hour, every two hours`)
+  instead of collapsing to the bare hour description.
+- A meaningful second under a restricted minute or hour now **leads with its
+  own clause** (`every 15 seconds, every day at 9:30 a.m.`) instead of being
+  silently dropped.
+- Property-based tests covering mixed-list fields, asserting interpretation
+  never throws or leaks `NaN`/`undefined` for valid patterns.
+- A `lenient` option: invalid input returns the fallback description
+  `'an unrecognizable cron pattern'` instead of throwing, making `cronli5`
+  safe to embed in UIs that render arbitrary user crontabs.
+- A `dialect` option anchored to named style guides. `'us'` (the default)
+  follows the Chicago Manual of Style; `'gb'` follows the Guardian style
+  guide: `cronli5('30 9 * * MON-FRI', {dialect: 'gb'})` reads "every Monday
+  to Friday at 9.30am", with no serial comma, "to" ranges, closed-up
+  full-point times, "midday"/"midnight", and day-first dates ("1 January").
+  `'house'` preserves cronli5's legacy voice ("9:30 AM", "Monday - Friday",
+  ordinal dates like "January 1st") on a Chicago base, and a custom style
+  object may be passed directly, with omitted fields inheriting the US
+  defaults (`{dialect: {through: ' until '}}`). The full style-field
+  reference lives in `docs/dialects.md`.
+- Input normalization: list segments are described in ascending fire order
+  (`17,9` reads "at 9 a.m. and 5 p.m."), duplicate segments collapse, and
+  degenerate ranges (`9-9`) read as their single value.
+- **Quartz-style tokens** in the date and weekday fields: `L` ("on the last
+  day of the month"), `L-n` ("five days before the last day of the month"),
+  `LW`/`WL` ("on the last weekday of the month"), `nW` ("on the weekday
+  nearest the 15th"), `nL` ("on the last Friday of the month"), `n#m` ("on
+  the second Monday of the month"), and `?` (no specific value).
+- **Wrap-around ranges** in cyclic fields: `0 22-2 * * *` reads "every hour
+  from 10 p.m. through 2 a.m.", `FRI-MON` reads "Friday-Monday", and
+  `11-2` reads "November through February". Reversed ranges remain invalid
+  where the cycle metaphor breaks down: step bounds and the year field.
+- A head-to-head cronli5 vs. cRonstrue comparison:
+  `docs/cronli5-vs-cronstrue.md` carries two generated output tables
+  (everyday patterns, and compound patterns where the gap is widest),
+  regenerated in place by `npm run docs` (with a `--check` mode CI runs);
+  `docs/cronstrue-comparison.md` holds the full architectural comparison;
+  the README links to both.
+- **Seven-field (Quartz-style) patterns** parse without any option: seven
+  fields are unambiguous (`second minute hour date month weekday year`), so
+  `'0 0 12 1 1 * 2030'` reads "on January 1, 2030 at noon". The
+  `years` option remains as the six-field disambiguator.
+- An explicitly supplied year is now always described: object input with a
+  `year` property (e.g. `{hour: 9, year: 2030}`) previously validated the
+  year and then silently dropped it from the description.
+
+### Changed
+
+- **The English `'uk'` dialect was renamed to `'gb'`.** BCP-47 reserves
+  `uk` for the Ukrainian language, so the British-English style now uses the
+  ISO-3166 country code `'gb'`. `{ dialect: 'uk' }` still works as a
+  deprecated alias for `'gb'` and will be removed in a future release.
+
+- **Spanish now defaults to the 24-hour clock** (`a las 09:30`,
+  `a las 17:00`), matching RAE convention for written Spanish. Pass
+  `{ampm: true}` for the previous 12-hour behavior with day periods
+  (`a las 9:30 de la mañana`, `al mediodía`, `a medianoche`). As part of
+  the change, one o'clock now keeps its singular article on the 24-hour
+  clock as well (`a la 01:00`, not `a las 1:00`). English stays 12-hour
+  by default; Finnish was already 24-hour only.
+- **Spanish 24-hour clock times now zero-pad the hour**, like the
+  minutes already did: `a las 09:00` (was `a las 9:00`), `a la 01:00`.
+  This matches English 24-hour output (`ampm: false`), which already
+  padded. Finnish deliberately does **not** pad the hour (`klo 9.30`,
+  `klo 9–17`), per SFS 4175, where the hour is written without a leading
+  zero and only the minute pads.
+- Finnish anchored minutes/seconds use the **`kohdalla` mark form**:
+  `30 * * * *` reads `joka tunti 30 minuutin kohdalla` (was the calque
+  `jokaisen tunnin minuutilla 30`), `15 * * * * *` reads `joka minuutti
+  15 sekunnin kohdalla`. The old adessive form was flagged as an English
+  calque by an independent review and corroborated by cRonstrue's human
+  Finnish locale.
+- Spanish weekday qualifiers drop the redundant `todos`: `0 9 * * MON`
+  reads `los lunes a las 09:00` (was `todos los lunes…`). The plural
+  definite article `los lunes` already means "every Monday" in Spanish,
+  and the other weekday forms (ranges, trailing, date-or-weekday) already
+  omitted it. `todos los días` is unchanged, since `los días` alone does
+  not mean "every day".
+- Internal restructure toward i18n (see `docs/i18n-design.md`): the
+  language-independent core (parsing, validation, normalization, semantic
+  analysis) now lives in `src/core/`, and all English — phrases, dialect
+  tables, names, time formatting — lives in `src/lang/en/`. The public API
+  and every description are unchanged; the only output difference is that
+  the too-many-fields error message no longer varies with the `short`
+  option.
+- The test tree mirrors the i18n architecture: English's expectation suite
+  is a language corpus like any other (`test/lang/en/`), validation and
+  error tests live with the core (`test/core/`), and `test/property/`
+  holds the shared invariants.
+- **Spanish** (`cronli5/lang/es`), the i18n pilot: a full natural-Spanish
+  renderer over the semantic IR, anchored to RAE/FundéuRAE conventions
+  ("todos los lunes a las 9:30 de la mañana", "el 25 de diciembre de 2030
+  al mediodía"), selected per call via the new `lang` option
+  (`cronli5(pattern, {lang: es})`). Ships with a reviewed corpus, minimal
+  pairs, language notes, and a review log under `test/lang/es/`, hardened
+  against the full English pattern set plus a hazard-hour matrix via the
+  new review-packet generator (`scripts/review-lang.mjs`). Spanish month
+  ranges read with repeated prepositions where folding would garden-path
+  ("el 1 de cada mes, de junio a septiembre"; "en enero y de marzo a
+  junio"), and step segments in month/weekday lists flatten into their
+  fires ("todos los domingos, lunes, miércoles y viernes").
+- Description-strategy selection now lives in the core as a semantic IR:
+  `analyze()` classifies field shapes and segments, precomputes windows
+  and enumerations, and selects the plan; the English module is a pure
+  plan renderer whose only input is the IR. Covered by a dedicated IR
+  spec (`test/core/analyze.js`); every description is unchanged.
+- Default output now adheres to the **Chicago Manual of Style**: serial
+  commas in lists of three or more ("9 a.m., noon, and 5 p.m."), lowercase
+  dotted meridiems ("9:30 a.m.", previously "9:30 AM"), on-the-hour times
+  without minutes ("9 a.m.", previously "9:00 AM"), "noon" and "midnight"
+  for exact 12:00, and cardinal month-day dates ("January 1", previously
+  "January 1st"). Bare days of the month keep their ordinals ("on the 1st
+  and 15th").
+- Hour windows now end at the **last actual fire** instead of the top of the
+  final hour: `*/15 9-17 * * *` reads "every 15 minutes from 9 a.m. through
+  5:45 p.m." (previously "through 5 p.m."), and `*/15 9 * * *` reads "through
+  9:45 a.m." (previously "through 9:59 a.m.").
+- Weekday ranges read as prose: `MON-FRI` is "every Monday through Friday"
+  (previously "every Monday-Friday").
+- The `short` option now compacts ranges consistently: every "A through B"
+  becomes "A-B" (`Mon-Fri` as before, and now also `Jan-Mar`, `1st-5th`,
+  `0-30` in minute lists, and clock-time windows like `9 a.m.-5:45 p.m.`).
+  Previously short mode abbreviated names but left "through" in place for
+  every field except weekdays.
+
+### Fixed
+
+- A contiguous hour range with extra discrete hours now reads with the
+  hour-range frame instead of an ambiguous clock-time span:
+  `0 9-20,22 * * *` reads "every hour from 9 a.m. through 8 p.m. and at
+  10 p.m." (was "every day at 9 a.m. through 8 p.m. and 10 p.m.", where
+  the trailing "and 10 p.m." could read as part of the span). This mirrors
+  the existing pure-range rendering (`0 9-17 * * *` → "every hour from 9
+  a.m. through 5 p.m."); the per-minute (`30 9-20,22` → "at 30 minutes
+  past the hour from 9 a.m. through 8:30 p.m. and at 10:30 p.m.") and
+  multiple-range (`0 9-12,14-20` → "every hour from 9 a.m. through noon
+  and from 2 p.m. through 8 p.m.") forms follow the same frame.
+- Clock-time lists no longer mix the words "noon"/"midnight" with numeral
+  times: `0 22-2,12 * * *` reads "every day at 12 p.m., 10 p.m., 11 p.m.,
+  12 a.m., 1 a.m., and 2 a.m." (was "noon, ..., midnight, ..."), the same
+  consistency rule the number series follows. A list that is only
+  noon/midnight keeps the words (`0 0,12 * * *` → "midnight and noon"),
+  as does a single time (`0 12 * * *` → "every day at noon").
+- English minute and second number series are now internally consistent
+  in their number style: when any value in a list or range exceeds ten,
+  the whole series uses numerals instead of mixing spelled words with
+  digits. `0-29 * * * *` reads "every minute from 0 through 29 past the
+  hour" (was "from zero through 29"), and `5,10,15 * * * * *` reads "at
+  5, 10, and 15 seconds past the minute" (was "five, ten, and 15"). All-
+  small series stay spelled ("at five and ten seconds"), as do single
+  values ("30 minutes past the hour"). This follows the Chicago rule the
+  default dialect already targets.
+- A month **range** no longer folds into a calendar date: `0 0 1 6-9 *`
+  reads "on the 1st in June through September" (previously "on June
+  through September 1", which parses as "(June) through (September 1)").
+  Single months and flat name lists still fold ("on June 1", "on June and
+  December 1"). With both a date and a weekday, the month scopes the whole
+  alternation once: "on the 1st or on Friday in June through September".
+- Minute and second lists containing **step segments** enumerate the
+  step's fires instead of leaking the raw token: `5,30-40/5 * * * *`
+  reads "at 5, 30, 35, and 40 minutes past the hour" (previously
+  "at five and 30-40/5 minutes past the hour"), matching how standalone
+  bounded steps and date lists already read.
+- Hour lists containing range or step segments (e.g. `0-30 9,17-19 * * *`)
+  no longer throw.
+- Minute lists containing a range under a specific hour (e.g.
+  `0-30,45 9 * * *`) no longer render `NaN` clock times or garbled bounds.
+- A second step under a specific minute and hour (e.g. `*/15 30 9 * * *`) no
+  longer loses its cadence.
+- Second- and minute-anchored descriptions (`30 minutes past the hour, every
+  hour`, `every 15 seconds`, etc.) no longer drop their trailing day
+  qualifier (e.g. `on Monday`).
+- Month, date, and weekday lists containing ranges or steps no longer render
+  `undefined` or garbled bounds.
+- A weekday combined with a month (e.g. `0 0 * 6 MON`) no longer drops the
+  weekday: it reads "every Monday in June at midnight".
+- Interval-one steps normalize to their equivalent range, fixing inaccurate
+  or garbled output in every field: `1/1 * * * *` read "every minute"
+  though minute :00 is excluded (now "every minute from one through 59 past
+  the hour"), `0 1/1 * * *` read "every hour" though hour 0 is excluded
+  (now "every hour from 1 a.m. through 11 p.m."), and `0 0 2/1 * *` read
+  "every 1st day of the month from the 2nd" (now "on the 2nd through 31st").
+- Offset steps starting at one are no longer ungrammatical: `1/3 * * * *`
+  reads "every three minutes from one minute past the hour" (was "one
+  minutes").
+- A discrete minute under an hour step is no longer dropped: `5 */6 * * *`
+  reads "every day at 12:05 a.m., 6:05 a.m., 12:05 p.m., and 6:05 p.m." (previously
+  "every six hours", and bounded steps even displayed ":00" times for jobs
+  firing at :05).
+- Clock-time enumeration is capped at six times. Beyond the cap, a single
+  minute folds into a compact hour phrase and a minute list leads with its
+  own clause instead of cross-multiplying into a wall of times
+  (`0,30 8-18/2 * * *` reads "at 0 and 30 minutes past the hour, at 8
+  a.m., 10 a.m., ..." — six times, not twelve).
+
+## [0.1.0]
+
+First non-beta release.
+
+### Added
+
+- Idiomatic descriptions for **lists** (`,`), **ranges** (`-`), and **compound**
+  patterns that combine multiple non-trivial fields (e.g.
+  `at 30 minutes past the hour from 9 a.m. through 5 p.m.`).
+- Trailing day qualifiers for bare frequencies (e.g. `every minute on Monday`,
+  `every hour on January 13`).
+- Dual **ESM** and **CommonJS** builds plus a minified **browser** global, an
+  `exports` map, and bundled **TypeScript** type definitions (`cronli5.d.ts`).
+- Continuous integration (GitHub Actions) across Node 18/20/22, with a
+  coverage gate.
+- Code coverage via **c8** with enforced thresholds (`npm run coverage`).
+- Property-based tests (**fast-check**), smoke tests against the built
+  ESM/CJS artifacts, and type tests (**tsd**, `npm run test:types`).
+
+### Changed
+
+- Source is now authored as an ES module in `src/` and bundled with esbuild.
+- Date descriptions always use suffixed numeric ordinals (`1st`, `2nd`, ...).
+- Modernized the toolchain: ESLint 9 (flat config), Mocha 11, Chai 4.
+- Enforced explicit ESLint budgets for cyclomatic `complexity`, `max-depth`,
+  and `max-params` as regression guards.
+
+### Fixed
+
+- Weekday/date/month-only patterns no longer drop their qualifier.
+- A specific minute within an hour range is no longer dropped.
+
+### Security
+
+- Resolved all `npm audit` advisories in the (dev-only) toolchain: bumped
+  `esbuild`, and pinned patched `diff`/`serialize-javascript` via `overrides`.
+  No runtime dependencies are affected.

package/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 
-_Copyright (c) 2016 Andrew Broz_
+_Copyright (c) 2026 Andrew Brož_
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.