jw_calendar 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: beca66c4a6a4fd8b0dfffca8bdd1a3beac47660d3a87b0295eed510ba9f8f9fa
+  data.tar.gz: 2cc6a2d0a7b6b70bd6c7c14fbf13da897d47ad197f649e8a2607d0dc723cd892
+SHA512:
+  metadata.gz: 337e84b8ccf6756b1b9ace6eec56066dcb2857593d2cb2bf0f375c3a9886c5a7812b6270711e86b8122b07827a9f46d63f375d4675006c30bb9143774415fe7c
+  data.tar.gz: 1b732076abff0d37fda3639d2204d85817ae89b4320de2145c6b12b229ec81edb3560f5eb14a2ec172f51c9ab7ceb97c2d18e0e5c24effed0699a098aa764bb6

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-10-01
+
+### Added
+
+- Immutable Gregorian and Julian civil dates with validation, arithmetic, comparison, and ordinal day.
+- Integer JDN conversion and exact rational JD/MJD day fractions.
+- Gregorian/Julian conversion, ISO week dates, and ordinal date values.
+- Structured natural and fixed-size month grids with adjacent or blank cells.
+- Configurable reform calendars with Papal and British Empire cutover profiles.
+- Lazy inclusive date ranges and structured calendar-boundary reports.
+- `jwcalendar` CLI with inspection, conversion, grid, JDN, ISO-week, boundary, and JSON output commands.
+- Minitest suite, examples, technical documentation, CI, and OIDC-based release workflow.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,17 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We are committed to making participation in this project a welcoming and respectful experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include respectful language, patience with differing viewpoints, constructive feedback, and accepting responsibility for mistakes.
+
+Examples of unacceptable behavior include harassment, insults, personal attacks, unwelcome sexual attention, publishing private information without permission, and other conduct that would be inappropriate in a professional setting.
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject contributions that violate this Code of Conduct and may temporarily or permanently exclude contributors. Report conduct concerns privately through the repository's GitHub security contact or by contacting a maintainer through GitHub.
+
+This policy is adapted from the Contributor Covenant, version 2.1: <https://www.contributor-covenant.org/version/2/1/code_of_conduct/>.

data/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+## Development setup
+
+Use Ruby 3.3 or newer, then run:
+
+```sh
+bundle install
+bundle exec rake
+```
+
+Run an example with `ruby -Ilib examples/inspect_date.rb`.
+
+## Calendar correctness
+
+Calendar code needs explicit, independently checked expected values. Keep civil labels separate from instants and timezones. When changing an algorithm, add boundary regressions (especially month/year transitions, ISO week-years, leap rules, and calendar cutovers), plus deterministic round-trip or invariant coverage. Use Ruby's `Date` only as an independent test oracle for Gregorian cross-checks; the library implementation must remain its own integer arithmetic.
+
+## Pull requests and bug reports
+
+Describe the observed behavior, expected behavior, Ruby version, and a minimal date example. For pull requests, explain the calendar convention and cite a reliable reference if the change follows a published rule. Keep changes focused and update relevant docs and executable examples.
+
+## Architecture expectations
+
+Runtime dependencies should remain zero unless a concrete need is demonstrated. Public API belongs under `JWCalendar::`; calculations must be deterministic and free of mutable process-global state. Do not add timezone behavior to `CivilDate`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JW Calendar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

data/README.md

@@ -0,0 +1,214 @@
+# JW Calendar for Ruby
+
+JW Calendar is a deterministic, dependency-free civil-calendar engine for Ruby. It implements proleptic Gregorian and Julian arithmetic, exact day-number conversions, ISO week dates, ordinal dates, month grids, configurable calendar reforms, lazy date ranges, and boundary reports.
+
+**A civil date is a calendar label, not a timestamp.** `2027-01-01` does not imply midnight UTC or any other instant. JWCalendar does not consult the machine timezone, locale, or clock.
+
+## Why this library exists
+
+Date boundaries are easy to get subtly wrong: a date's ISO week-year can differ from its calendar year, Julian and Gregorian labels diverge, and a month grid may need dates from adjacent months. JWCalendar keeps those rules explicit and uses integer day arithmetic so the same input produces the same result on every host.
+
+## Installation
+
+```sh
+gem install jw_calendar
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "jw_calendar"
+```
+
+## Quick Start
+
+```ruby
+require "jw_calendar"
+
+date = JWCalendar::CivilDate.gregorian(2027, 1, 1)
+date.to_s                  # => "2027-01-01"
+date.weekday_name          # => "Friday"
+date.iso_week.to_s         # => "2026-W53-5"
+date.ordinal_day           # => 1
+date.to_jdn                # => 2461407
+date.add_days(1).to_s      # => "2027-01-02"
+```
+
+## Civil Dates
+
+`JWCalendar::CivilDate` is an immutable value object with a positive year, month, day, and explicit `:gregorian` or `:julian` calendar. Dates compare by absolute day; equality and hashing also include the calendar label. `#next_day`, `#previous_day`, `#add_days`, and `#subtract_days` preserve the selected calendar.
+
+```ruby
+date = JWCalendar::CivilDate.new(2024, 2, 29, calendar: :gregorian)
+date.frozen? # => true
+date.ordinal_day # => 60
+```
+
+The supported year domain starts at 1 CE; year zero and BCE labels are not represented.
+
+## Gregorian Calendar
+
+`JWCalendar::Calendars::Gregorian` implements proleptic Gregorian leap years, month lengths, validation, ordinal day, and integer JDN conversion. “Proleptic” means the modern Gregorian rules are applied consistently to dates before their historical adoption.
+
+## Julian Calendar
+
+`JWCalendar::Calendars::Julian` is a distinct civil calendar with every fourth year leap. A **Julian calendar date** is not a **Julian Day Number**; the latter is an integer count of days used to map dates onto a common absolute timeline.
+
+```ruby
+gregorian = JWCalendar::CivilDate.gregorian(1582, 10, 15)
+julian = JWCalendar::Conversion::CalendarConverter.convert(gregorian, to: :julian)
+julian.to_s # => "1582-10-05"
+```
+
+## Julian Day Numbers
+
+Use `JWCalendar::Conversion::JulianDayNumber` for JDN, JD, and MJD operations. JDN is an integer associated with astronomical noon. The exact JD for the start of a civil date is therefore `JDN - 1/2`; MJD is `JD - 2_400_000.5`. Fractions are represented as `Rational` when supplied as exact values.
+
+```ruby
+date = JWCalendar::CivilDate.gregorian(2000, 1, 1)
+JWCalendar::Conversion::JulianDayNumber.jd(date)  # => (4903089/2)
+JWCalendar::Conversion::JulianDayNumber.mjd(date) # => (51544/1)
+JWCalendar::CivilDate.from_jdn(date.to_jdn)       # => same date
+```
+
+`jd(date, fraction: Rational(1, 4))` adds an explicitly supplied fraction of that civil day. This is a day fraction, not a timezone-aware time-of-day object.
+
+## ISO Week Dates
+
+`date.iso_week` returns an immutable `JWCalendar::ISO::WeekDate` with ISO week-year, week, and weekday (Monday=1 through Sunday=7). `#to_date` converts it back to a proleptic Gregorian `CivilDate`.
+
+```ruby
+JWCalendar::CivilDate.gregorian(2027, 1, 1).iso_week.to_s # => "2026-W53-5"
+JWCalendar::ISO::WeekDate.new(2026, 53, 5).to_date.to_s   # => "2027-01-01"
+```
+
+ISO week dates follow the ISO week-year boundary rule: week 1 contains January 4, equivalently the first Thursday of the ISO week-year.
+
+## Ordinal Dates
+
+`JWCalendar::Conversion::OrdinalDate` represents year plus day-of-year, such as `2028-366`.
+
+```ruby
+ordinal = JWCalendar::Conversion::OrdinalDate.for(JWCalendar::CivilDate.gregorian(2028, 12, 31))
+ordinal.to_s     # => "2028-366"
+ordinal.to_date  # => 2028-12-31
+```
+
+## Month Grids
+
+`JWCalendar::Grid::MonthGrid` returns immutable rows of seven semantic `Cell` values; it does not render HTML. Choose Monday or Sunday (or ISO weekday 1–7), adjacent dates, blank spillover cells, natural row count, or a fixed four-, five-, or six-week layout.
+
+```ruby
+grid = JWCalendar::Grid::MonthGrid.new(
+  year: 2027, month: 1, week_start: :sunday,
+  fixed_weeks: 6, include_adjacent: true
+)
+grid.rows.length # => 6
+grid.cells.length # => 42
+grid.rows.first.first.date.to_s # => "2026-12-27"
+```
+
+Each cell exposes its date (or `nil` in blank mode), `in_current_month?`, weekday, week index, and column index. `#to_h` provides a JSON-friendly structure.
+
+## Calendar Reform
+
+`JWCalendar::Calendars::ReformCalendar` models one explicitly configured local Julian-to-Gregorian cutover. It rejects skipped labels with `ReformGapError` and maps absolute days to the appropriate side. `ReformCalendar.papal` and `.british_empire` provide the named 1582 and 1752 profiles. These are examples of local historical rules, not a claim that one cutover applied everywhere.
+
+```ruby
+reform = JWCalendar::Calendars::ReformCalendar.papal
+reform.date(1582, 10, 4).calendar # => :julian
+reform.date(1582, 10, 15).calendar # => :gregorian
+reform.valid_date?(1582, 10, 10) # => false
+```
+
+## Boundary Analysis
+
+`JWCalendar::Boundary::Analyzer.year(2027)` returns a `Report` containing structured events for leap days, month/year ends, six-row months, ISO week-year rollovers, ISO week 53 dates, and Gregorian/Julian offset changes. `Analyzer.range(date_range)` analyzes an explicit lazy range. Pass `reform_calendar: JWCalendar::Calendars::ReformCalendar.papal` to include labels skipped by that profile.
+
+```ruby
+report = JWCalendar::Boundary::Analyzer.year(2024)
+report.select { |event| event[:type] == :leap_day }
+# => [{ type: :leap_day, date: "2024-02-29", calendar: :gregorian }]
+```
+
+## CLI
+
+The `jwcalendar` executable is installed with the gem:
+
+```sh
+jwcalendar --help
+jwcalendar --version
+jwcalendar inspect 2027-01-01
+jwcalendar iso-week 2027-01-01
+jwcalendar jdn 2000-01-01
+jwcalendar convert 2027-01-01 --from gregorian --to julian
+jwcalendar grid 2027-01 --week-start monday --fixed-weeks 6
+jwcalendar boundary 2027
+```
+
+Invalid input prints a concise error to standard error and exits non-zero.
+
+## JSON Output
+
+Add `--json` to structured commands. Output uses stable field names and exact day fractions are serialized as rational strings.
+
+```sh
+jwcalendar inspect 2027-01-01 --json
+```
+
+The JSON includes `date`, `calendar`, `weekday`, `weekday_number`, `ordinal_day`, `jdn`, `iso_week_year`, `iso_week`, and `iso_weekday`.
+
+## Architecture
+
+The public API is organized under `JWCalendar::CivilDate`, `Calendars`, `Conversion`, `ISO`, `Grid`, `Boundary`, and `DateRange`. Core date operations use integer arithmetic and contain no mutable global calendar state. Runtime dependencies are zero; CLI parsing and JSON use the Ruby standard library.
+
+## Correctness Model
+
+Gregorian and Julian dates map to integer JDNs. Weekdays are calculated from the absolute day; ISO week-years are derived using the Thursday rule. Month grids are assembled from those same date operations. Tests include deterministic round trips, broad year samples, Ruby's independent `Date` implementation for proleptic Gregorian checks, and known boundary dates. Arithmetic methods are O(1), apart from output-sized operations such as iterating a range or building a grid.
+
+## Time Zones and Non-Goals
+
+JWCalendar models civil dates only. It does not replace timezone databases, `TZInfo`, `ActiveSupport::TimeZone`, event scheduling, recurrence-rule engines, or a localization framework. It never assumes a civil date means midnight UTC. A caller that has an instant must choose its timezone policy before obtaining a civil date.
+
+## Performance
+
+Gregorian/Julian conversion, weekday, ordinal lookup, ISO week conversion, and date arithmetic are constant-time integer operations. Date ranges are lazy. The `benchmark/` directory contains reproducible Ruby `Benchmark` scripts; results depend on runtime and hardware, and no universal throughput claim is made.
+
+## Supported Ruby Versions
+
+JWCalendar requires Ruby 3.3 or newer. CI tests Ruby 3.3, 3.4, and 4.0.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+```
+
+The default task runs Minitest, RuboCop, and gem packaging. Examples can be run with `ruby -Ilib examples/NAME.rb`.
+
+## Testing
+
+```sh
+bundle exec rake test
+bundle exec rubocop
+gem build jw_calendar.gemspec
+```
+
+Tests cover leap rules, invalid labels, arithmetic, JDN/JD/MJD, ISO weeks, ordinals, reform gaps, grids, ranges, CLI behavior, JSON output, and deterministic round trips.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). The gem has no runtime dependencies and declares RubyGems MFA as required for publishing.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Changes to date math should include independently checked examples and regression tests for boundaries.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).
+
+## Project Website
+
+JW Calendar's main project website is [jwcalendar.com](https://jwcalendar.com/).

data/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported releases
+
+Security fixes are provided for the latest released version. Please update to the latest version before reporting an issue.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting for this repository: <https://github.com/karencohenjw/jw_calendar/security/advisories/new>. Do not include exploit details in a public issue. Reports should describe the affected version, impact, and a minimal reproduction where possible.
+
+JWCalendar performs deterministic arithmetic on caller-provided values and has no runtime network access or runtime dependencies. Reports about parsing, denial-of-service inputs, package integrity, or release workflow permissions are in scope.

data/docs/architecture.md

@@ -0,0 +1,26 @@
+# Architecture
+
+## Public layers
+
+- `CivilDate` stores a validated immutable calendar label and maps it to an integer JDN.
+- `Calendars::Gregorian` and `Calendars::Julian` own their respective leap rules and JDN algorithms.
+- `Conversion` handles cross-calendar and ordinal/JD representations.
+- `ISO::WeekDate` handles ISO week-year value conversion.
+- `Grid`, `DateRange`, and `Boundary` compose the date primitives without owning a clock or timezone.
+- `CLI::Runner` is a small standard-library interface around the public operations.
+
+The library uses positive civil years beginning at 1 CE and has no runtime dependencies. Constructors validate inputs before storing them. Value objects freeze their instance state; there is no process-global calendar selection.
+
+## Determinism
+
+All date calculations use integers. JD/MJD fractions use `Rational` when produced by the library or supplied exactly. Nothing reads local time, environment locale, or system timezone. Range enumeration is lazy; a grid allocates only its four-to-six rows.
+
+## Complexity
+
+Leap checks, conversion, weekday, ordinal lookup, comparison, and adding a fixed number of days are O(1). A month grid is O(1) in its fixed maximum size. Range traversal is O(n) time and O(1) extra space, excluding objects yielded to the caller. Boundary reports take O(days in the requested year/range) because they emit date-level ISO conditions.
+
+## References
+
+- ISO week numbering is specified by [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).
+- Julian date conventions are described by the [U.S. Naval Observatory](https://aa.usno.navy.mil/data/JulianDate).
+- Ruby's `Date` is used only as a test oracle for Gregorian arithmetic: [Ruby Date documentation](https://docs.ruby-lang.org/en/master/Date.html).

data/docs/civil-dates.md

@@ -0,0 +1,14 @@
+# Civil dates
+
+`CivilDate` stores `(year, month, day, calendar)` and no time-of-day fields. Its default constructor calendar is Gregorian; explicit class constructors are available:
+
+```ruby
+gregorian = JWCalendar::CivilDate.gregorian(2027, 1, 1)
+julian = JWCalendar::CivilDate.julian(1582, 10, 4)
+```
+
+Years are positive integers (1 CE and later). Invalid month/day combinations raise `InvalidDateError`; an unsupported calendar raises `InvalidCalendarError`. The date is frozen after validation.
+
+Ordering compares absolute JDN values, so distinct calendar labels can represent the same day and compare equally in ordering. `==` and `hash` include the calendar system, which keeps each labelled representation distinct as a value. Arithmetic preserves the source calendar system. Converting a day to a Gregorian/Julian label is an explicit operation through `CalendarConverter` or `CivilDate.from_jdn`.
+
+No conversion to midnight UTC is implied. If an application starts from an instant, it must apply its own timezone policy before creating a civil date.

data/docs/cli.md

@@ -0,0 +1,14 @@
+# Command-line interface
+
+The `jwcalendar` executable wraps the library with stable, deterministic commands:
+
+```text
+jwcalendar inspect DATE [--calendar gregorian|julian] [--json]
+jwcalendar iso-week DATE [--calendar gregorian|julian] [--json]
+jwcalendar jdn DATE [--calendar gregorian|julian] [--json]
+jwcalendar convert DATE [--from gregorian|julian] [--to gregorian|julian] [--json]
+jwcalendar grid YYYY-MM [--week-start monday|sunday] [--fixed-weeks 4|5|6] [--no-adjacent] [--json]
+jwcalendar boundary YEAR [--json]
+```
+
+Structured commands accept `--json`. Invalid arguments are written to standard error and return exit status 2. The default output is intended for people; scripts should request JSON. JDN is emitted as an integer, and JD/MJD at midnight as exact rational strings.

data/docs/correctness.md

@@ -0,0 +1,7 @@
+# Correctness model
+
+The core invariant is that a Gregorian or Julian label maps to one integer JDN and inverse conversion returns the same label. Cross-calendar conversion preserves JDN. Weekday derives from the same absolute day. ISO conversion uses the Monday containing January 4 and round-trips every sampled day.
+
+Tests cover leap centuries, known historical and epoch values, New Year ISO transitions, deterministic year samples, cutover gaps, 7-column grids, exact JD/MJD fractions, and the Julian/Gregorian offset change after February in century years such as 1700. For supported positive Gregorian years, the test suite compares JDN results with Ruby's independent `Date` implementation configured for proleptic Gregorian rules.
+
+The supported civil label domain is 1 CE onward, with no year zero. Time scales, leap seconds, timezone interpretation, and locale-specific week displays are outside this version's correctness claim.

data/docs/gregorian.md

@@ -0,0 +1,9 @@
+# Proleptic Gregorian calendar
+
+The Gregorian leap-year rule is divisibility by 4, except century years must also be divisible by 400. Thus 1600 and 2000 are leap years, while 1700, 1800, 1900, and 2100 are not.
+
+`Calendars::Gregorian` uses closed-form integer arithmetic to map a valid positive-year label to JDN and invert an integer JDN. The proleptic model applies Gregorian rules consistently before historical adoption; it does not itself model a jurisdiction's changeover. For a historical Julian-to-Gregorian switch, use `ReformCalendar`.
+
+Weekday derives from `JDN mod 7`, with Monday=1 and Sunday=7. Day-of-year is computed from the same validated Gregorian month lengths. These operations do not iterate from an epoch.
+
+Ruby's standard `Date` is used in tests as an independent cross-check, not as the implementation: [Date documentation](https://docs.ruby-lang.org/en/master/Date.html).

data/docs/iso-week.md

@@ -0,0 +1,12 @@
+# ISO week dates
+
+An ISO week begins Monday. Week 1 is the week containing January 4 (equivalently the year's first Thursday). Therefore dates near New Year can have a week-year different from their Gregorian calendar year.
+
+`CivilDate#iso_week` returns `ISO::WeekDate`. `WeekDate#to_date` returns the corresponding proleptic Gregorian date; construction validates whether the year has 52 or 53 weeks.
+
+```ruby
+date = JWCalendar::CivilDate.gregorian(2027, 1, 1)
+date.iso_week.to_s # => "2026-W53-5"
+```
+
+The ISO weekday is Monday=1 through Sunday=7. The week-year is determined by moving to the date's Thursday, which is constant-time. Normative rules are in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).

data/docs/julian-day-number.md

@@ -0,0 +1,9 @@
+# JDN, JD, and MJD
+
+`CivilDate#to_jdn` returns the integer Julian Day Number associated with that date at astronomical noon. JDNs provide a common integer coordinate for Gregorian and Julian labels.
+
+JD is fractional. The start of a civil day at midnight is half a day before its noon-labelled integer: `JD = JDN - 1/2`. The inverse splits an exact JD into a date and a fraction since midnight. MJD uses `MJD = JD - 2,400,000.5`; at midnight, MJD equals `JDN - 2,400,001`.
+
+The conversion methods accept or return rational values. For example, a quarter-day offset should be supplied as `Rational(1, 4)` when exactness matters. A fraction denotes a mathematical fraction of a day; this API does not model leap seconds or a timescale such as UTC, TT, or TAI.
+
+For background on Julian date conventions, see the [U.S. Naval Observatory](https://aa.usno.navy.mil/data/JulianDate).

data/docs/julian.md

@@ -0,0 +1,13 @@
+# Julian calendar
+
+The Julian civil calendar inserts a leap day every four years. It is implemented separately from Gregorian arithmetic under `Calendars::Julian`.
+
+Both calendar systems map to JDN, which lets `CalendarConverter` translate a date label while preserving its absolute day:
+
+```ruby
+day = JWCalendar::CivilDate.gregorian(1582, 10, 15)
+JWCalendar::Conversion::CalendarConverter.convert(day, to: :julian).to_s
+# => "1582-10-05"
+```
+
+“Julian calendar” refers to a civil calendar rule. “Julian Day Number” refers to an integer day count; the shared word does not make them the same concept. The library supports positive year labels and does not encode historical jurisdiction-specific adoption dates unless a `ReformCalendar` is selected.

data/docs/month-grid.md

@@ -0,0 +1,7 @@
+# Month grids
+
+`Grid::MonthGrid` produces rows of seven immutable cells. Each nonblank cell has a `CivilDate`, a current-month flag, weekday, zero-based row index, and zero-based column index.
+
+`week_start` accepts `:monday`, `:sunday`, or an ISO weekday integer. By default the grid has the natural four, five, or six weeks needed to contain all dates. Set `fixed_weeks: 6` for a 42-cell layout. A shorter fixed size that cannot contain the month raises `ArgumentError`.
+
+With `include_adjacent: true`, cells before and after the month are real dates. With `false`, those cells are blank (`date == nil`) while retaining their grid position. `#to_h` returns JSON-friendly row and weekday data; presentation remains the caller's responsibility.

data/docs/reform-calendars.md

@@ -0,0 +1,14 @@
+# Reform calendars
+
+Historical adoption of Gregorian rules happened on different dates in different places. A reform profile therefore requires an explicit local cutover pair:
+
+```ruby
+reform = JWCalendar::Calendars::ReformCalendar.new(
+  last_julian_date: [1582, 10, 4],
+  first_gregorian_date: [1582, 10, 15]
+)
+```
+
+The pair must represent consecutive absolute days. Labels after the last Julian label and before the first Gregorian label raise `ReformGapError`. `date` selects the appropriate underlying calendar for labels on either side; `from_jdn` does the inverse. Optional constructors `.papal` and `.british_empire` are named profiles for commonly cited transitions, not universal history settings.
+
+`CivilDate` intentionally records only its underlying proleptic Gregorian or Julian system. Keep the `ReformCalendar` instance with application data when the selected jurisdiction's reform rule matters.

data/exe/jwcalendar

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "jw_calendar"
+require "jw_calendar/cli/runner"
+
+exit JWCalendar::CLI::Runner.new.run(ARGV)

data/lib/jw_calendar/arithmetic/floor_division.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Arithmetic
+    # Integer division rounded toward negative infinity, unlike Ruby's Integer#div
+    # only in its explicit validation and documentation of the calendar use case.
+    module FloorDivision
+      module_function
+
+      def div(numerator, denominator)
+        unless numerator.is_a?(Integer) && denominator.is_a?(Integer) && denominator.positive?
+          raise ArgumentError, "expected an Integer numerator and positive Integer denominator"
+        end
+
+        numerator.div(denominator)
+      end
+    end
+  end
+end

data/lib/jw_calendar/boundary/analyzer.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module JWCalendar
+  module Boundary
+    # Finds deterministic high-risk boundaries useful for regression tests.
+    class Analyzer
+      class << self
+        def year(year, calendar: :gregorian, reform_calendar: nil)
+          return reform_year(year, reform_calendar) if reform_calendar
+
+          unless CivilDate::CALENDARS.include?(calendar)
+            raise InvalidCalendarError, "calendar must be :gregorian or :julian"
+          end
+
+          engine = calendar == :gregorian ? Calendars::Gregorian : Calendars::Julian
+          engine.days_in_year(year)
+          events = []
+          months = (1..12).map do |month|
+            days = engine.days_in_month(year, month)
+            first_date = CivilDate.new(year, month, 1, calendar:)
+            grid = Grid::MonthGrid.new(year:, month:, calendar:)
+            events << event(:six_row_month, first_date, rows: grid.weeks) if grid.weeks == 6
+            events << event(:leap_day, CivilDate.new(year, 2, 29, calendar:)) if month == 2 && days == 29
+            events << event(:month_end, CivilDate.new(year, month, days, calendar:), month:)
+            days
+          end
+          events << event(:year_end, CivilDate.new(year, 12, months.last, calendar:))
+
+          first = CivilDate.new(year, 1, 1, calendar:)
+          last = CivilDate.new(year, 12, months.last, calendar:)
+          add_absolute_day_events(events, first.to_jdn, last.to_jdn, calendar:)
+          add_offset_change_events(events, first.to_jdn, last.to_jdn, calendar:)
+          Report.new(events)
+        end
+
+        def range(date_range)
+          raise ArgumentError, "date_range must be a DateRange" unless date_range.is_a?(DateRange)
+
+          events = []
+          previous_offset = nil
+          date_range.each do |date|
+            append_range_date_events(events, date)
+            previous_offset = append_offset_change_event(events, date, previous_offset)
+          end
+          Report.new(events)
+        end
+
+        private
+
+        def add_absolute_day_events(events, first_jdn, last_jdn, calendar:)
+          (first_jdn..last_jdn).each do |jdn|
+            date = CivilDate.from_jdn(jdn, calendar:)
+            append_iso_week_events(events, date)
+          end
+        end
+
+        def add_offset_change_events(events, first_jdn, last_jdn, calendar:)
+          previous_offset = nil
+          (first_jdn..last_jdn).each do |jdn|
+            date = CivilDate.from_jdn(jdn, calendar:)
+            previous_offset = append_offset_change_event(events, date, previous_offset)
+          end
+        end
+
+        def reform_year(year, reform)
+          validate_reform_year!(year, reform)
+
+          events = reform_gap_events(year, reform)
+          year_dates = reform_year_dates(year, reform, events)
+          raise InvalidDateError, "reform calendar has no valid dates in year #{year}" if year_dates.empty?
+
+          events << event(:year_end, year_dates.last)
+          year_dates.each { |date| append_iso_week_events(events, date) }
+          Report.new(events)
+        end
+
+        def append_range_date_events(events, date)
+          events << event(:leap_day, date) if date.month == 2 && date.day == 29
+          engine = date.calendar == :gregorian ? Calendars::Gregorian : Calendars::Julian
+          events << event(:month_end, date) if date.day == engine.days_in_month(date.year, date.month)
+          append_iso_week_events(events, date)
+        end
+
+        def append_iso_week_events(events, date)
+          gregorian_date = CivilDate.from_jdn(date.to_jdn)
+          iso = gregorian_date.iso_week
+          if iso.week_year != gregorian_date.year
+            events << event(:iso_week_year_rollover, date, iso_week_year: iso.week_year,
+                                                           iso_week: iso.week)
+          end
+          events << event(:iso_week_53, date, iso_week_year: iso.week_year, iso_week: iso.week) if iso.week == 53
+        end
+
+        def append_offset_change_event(events, date, previous_offset)
+          return previous_offset unless valid_in_both_calendars?(date)
+
+          offset = Calendars::Julian.to_jdn(date.year, date.month, date.day) -
+                   Calendars::Gregorian.to_jdn(date.year, date.month, date.day)
+          if previous_offset && offset != previous_offset
+            events << event(:gregorian_julian_offset_change, date, previous_offset:, offset:)
+          end
+          offset
+        end
+
+        def valid_in_both_calendars?(date)
+          Calendars::Gregorian.valid_date?(date.year, date.month, date.day) &&
+            Calendars::Julian.valid_date?(date.year, date.month, date.day)
+        end
+
+        def validate_reform_year!(year, reform)
+          raise ArgumentError, "reform_calendar must be a ReformCalendar" unless reform.is_a?(Calendars::ReformCalendar)
+          raise ArgumentError, "year must be a positive Integer" unless year.is_a?(Integer) && year.positive?
+        end
+
+        def reform_gap_events(year, reform)
+          reform.skipped_labels.filter_map do |label|
+            { type: :reform_gap, date: label, calendar: :reform } if label.start_with?(format("%04d-", year))
+          end
+        end
+
+        def reform_year_dates(year, reform, events)
+          1.upto(12).flat_map do |month|
+            dates = (1..31).filter_map do |day|
+              reform.date(year, month, day) if reform.valid_date?(year, month, day)
+            end
+            append_reform_month_events(events, year, month, dates) unless dates.empty?
+            dates
+          end
+        end
+
+        def append_reform_month_events(events, year, month, dates)
+          leap_day = dates.find { |date| date.day == 29 } if month == 2
+          events << event(:leap_day, leap_day) if leap_day
+          events << event(:month_end, dates.last, month:)
+          return unless dates.map(&:calendar).uniq.length == 1
+
+          grid = Grid::MonthGrid.new(year:, month:, calendar: dates.first.calendar)
+          events << event(:six_row_month, dates.first, rows: grid.weeks) if grid.weeks == 6
+        end
+
+        def event(type, date, extra = {})
+          { type:, date: date.to_s, calendar: date.calendar }.merge(extra)
+        end
+      end
+    end
+  end
+end