calcpace 1.18.0 → 1.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: def270498a0b653086ac234f0eb1ad4337f961cc2b93729a4bf32c7e48df78ba
-  data.tar.gz: '075049703348c3cea1194b90a9f64f6cc37552fe360ce51e0d446a9edca5e729'
+  metadata.gz: 70f0253d8a81513d2f48082bc39c96a1c9c324fc29ffb7f64ffde0590e5134c7
+  data.tar.gz: 2add58bc0d0f904e1e4cf6e08379e495bdeef2ee74bdcb068b973e4e4f0c995a
 SHA512:
-  metadata.gz: '083ff71a2666e55994ef03bd8184c435b1006c2029c4af97ab3546683f2d64e1422fb140c6828c001f00ad630bfc05f1caf98af53fbb9ab4d29ec603cad6ef04'
-  data.tar.gz: '00833e0d9c636730852506c360e08cfec7ecc1de2b1993a4a2560dd0f0941328c48c79e6047ca143babe3545f4b57bfd8e1e47b7c1f864c10d42ab85133390e0'
+  metadata.gz: 9abfbeae4e5cccd4c9634f0abcfa7bc51a29d317f47db86aceffd4afe04b17a629f0075440cc3729fd0893d614b007d16d3f5318ee3e4c671226832fb2373327
+  data.tar.gz: 8d6f1e3e2cd0e10a0436bbdd9ea7ebfc1f0a6973d2e69a83c0419c17ce0ae12c554790d1f80b5fedf2ad047ec6c5092c03bb58710da2bdc76434b71ac9ccc071

data/CHANGELOG.md

@@ -7,14 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.18.0] - 2026-09-06
+## [1.18.1] - 2026-09-06
+
+### Fixed
+- `age_grade_label(Float::NAN)` raised an opaque `NoMethodError` (`undefined
+  method '[]' for nil`) instead of a clear error; it now raises
+  `ArgumentError`. `Float::INFINITY` is unchanged and still maps to the top
+  band, "Approximate World Record Level".
 
 ### Changed
-- `age_grade_label(percent)` — and therefore `age_grade`'s `:category` — splits
-  the old single `"Developing"` band below 60% into three: `"Intermediate"`
-  (50–59.9%), `"Recreational"` (40–49.9%) and `"Active Beginner"` (below 40%).
-  Most recreational runners grade under 60%, so the old catch-all told nearly
-  every one of them the same thing.
+- `AGE_GRADE_LABELS` is now sorted by `min` descending at load time and
+  validated to be strictly descending with a `min` of exactly `0.0` on the
+  last entry, raising `Calcpace::InvalidDataError` at require time otherwise.
+  `age_grade_label` walks the list in order and returns the first match, so
+  an out-of-order entry in the data file would have silently misclassified
+  percentages, and a missing zero floor raised an opaque `NoMethodError`
+  instead of failing loudly.
+- Corrected the provenance note for the age-grade categories in the README
+  and in `wma_2023_open_standards.yml`. The WMA / Alan Jones (Howard Grubb)
+  tables are numeric age factors and open standards only — they define no
+  categories at all. The bands from Local Class (60%) upward follow the
+  USATF Masters / National Masters News convention; the three bands below
+  60% remain calcpace's own extension for recreational runners. No band
+  boundaries or labels changed, only the attribution text.
+- Documented in the README that the bands apply to the percentage as
+  reported by `age_grade` (rounded to one decimal), so calling
+  `age_grade_label` directly on an unrounded value can land one band lower
+  at an edge.
+
+## [1.18.0] - 2026-09-06
+
+### Breaking
+- **`age_grade[:category]` and `age_grade_label` return different strings for
+  anything below 60%.** The old single `"Developing"` band below 60% is now
+  three bands: `"Intermediate"` (50–59.9%), `"Recreational"` (40–49.9%) and
+  `"Active Beginner"` (below 40%). Most recreational runners grade under 60%,
+  so the old catch-all told nearly every one of them the same thing. A caller
+  matching on the string `"Developing"` must update — that string is no
+  longer returned by either method.
 
   ```ruby
   calc.age_grade_label(55.0) # => "Intermediate"      (was "Developing")
@@ -22,10 +52,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   calc.age_grade_label(30.0) # => "Active Beginner"   (was "Developing")
   ```
 
-  The bands at 60% and above are untouched, and no numeric output changes —
-  `age_grade_percent`, `age_graded_time_seconds` and the rest are identical.
-  This is a label-only change, so callers that match on the string
-  `"Developing"` need updating.
+  The bands at 60% and above are untouched, and the numeric fields —
+  `age_grade_percent`, `age_graded_time_seconds` and the rest — are
+  unaffected; only the two label-returning methods changed.
 
 ## [1.17.0] - 2026-09-05
 
@@ -620,7 +649,9 @@ predictors are untouched.
 
 See git history for changes in earlier versions.
 
-[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.17.0...HEAD
+[Unreleased]: https://github.com/0jonjo/calcpace/compare/v1.18.1...HEAD
+[1.18.1]: https://github.com/0jonjo/calcpace/compare/v1.18.0...v1.18.1
+[1.18.0]: https://github.com/0jonjo/calcpace/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/0jonjo/calcpace/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/0jonjo/calcpace/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/0jonjo/calcpace/compare/v1.14.0...v1.15.0

data/README.md

@@ -7,7 +7,7 @@ A Ruby gem for runners: pace, time, and distance calculations, unit conversions,
 ## Installation
 
 ```ruby
-gem 'calcpace', '~> 1.18.0'
+gem 'calcpace', '~> 1.18.1'
 ```
 
 ## Usage
@@ -276,10 +276,16 @@ calc.age_grade_label(65.2)                                      # => "Local Clas
 | 40–49.9% | Recreational |
 | below 40% | Active Beginner |
 
-The bands from Local Class up are the WMA / Alan Jones convention. Those tables
-define nothing below Local Class, so the three bands under 60% are calcpace's
-own extension — most recreational runners land there, and one catch-all label
-for everybody under 60% tells them nothing.
+The WMA / Alan Jones (Howard Grubb) tables are numeric age factors and open
+standards only — they define no categories at all. The bands from Local Class
+(60%) upward follow the USATF Masters / National Masters News convention; the
+three bands below 60% are calcpace's own extension — most recreational
+runners land there, and one catch-all label for everybody under 60% tells
+them nothing.
+
+The bands apply to the percentage as reported by `age_grade`, rounded to one
+decimal, so calling `age_grade_label` directly on an unrounded value can land
+one band lower at an edge.
 
 Supported distances: 5K, 10K, half marathon, marathon.
 
@@ -685,6 +691,8 @@ All errors inherit from `Calcpace::Error`:
 - `Calcpace::InvalidTimeFormatError` — time string not in `HH:MM:SS` or `MM:SS` format
 - `Calcpace::UnsupportedUnitError` — unknown conversion (`convert`) or unknown
   `unit:` / `distance_unit:` keyword
+- `Calcpace::InvalidDataError` — the bundled data table failed its load-time
+  consistency check (raised on `require`, never for user input)
 
 Argument validation that is not about units or numbers raises a plain `ArgumentError`:
 unknown race names, unsupported age-grading distances, and invalid `age` / `sex` values.

data/lib/calcpace/age_grading.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative 'errors'
 
 # Module for age-grading race performances with a versioned table
 #
@@ -28,9 +29,18 @@ module AgeGrading
                                                                       aliases: false).freeze
   TABLE_VERSION = OPEN_STANDARDS_DATA.fetch('meta').fetch('table_version').freeze
 
-  AGE_GRADE_LABELS = OPEN_STANDARDS_DATA.fetch('age_grade_classifications').map do |entry|
+  raw_age_grade_labels = OPEN_STANDARDS_DATA.fetch('age_grade_classifications').map do |entry|
     { min: entry.fetch('min').to_f, label: entry.fetch('label') }
-  end.freeze
+  end
+  AGE_GRADE_LABELS = raw_age_grade_labels.sort_by { |entry| -entry[:min] }.freeze
+
+  age_grade_label_mins = AGE_GRADE_LABELS.map { |entry| entry[:min] }
+  unless age_grade_label_mins.all?(&:finite?) &&
+         age_grade_label_mins == age_grade_label_mins.uniq &&
+         age_grade_label_mins.last == 0.0
+    raise Calcpace::InvalidDataError,
+          "age_grade_classifications must have unique finite mins ending at 0.0, got #{age_grade_label_mins.inspect}"
+  end
 
   DISTANCE_TO_METERS = {
     5.0 => '5000',
@@ -115,6 +125,7 @@ module AgeGrading
   #
   # @param percent [Numeric] age-grade percentage
   # @return [String] category label
+  # @raise [ArgumentError] when percent is not numeric, is negative, or is NaN
   def age_grade_label(percent)
     percent_value = begin
       Float(percent)
@@ -123,6 +134,7 @@ module AgeGrading
     end
 
     raise ArgumentError, 'Age-grade percent must be greater than or equal to 0' if percent_value.negative?
+    raise ArgumentError, 'Age-grade percent must be a number' if percent_value.nan?
 
     AGE_GRADE_LABELS.find { |entry| percent_value >= entry[:min] }[:label]
   end

data/lib/calcpace/data/wma_2023_open_standards.yml

@@ -3,10 +3,12 @@ meta:
   url: "https://howardgrubb.co.uk/athletics/wmatnf23.html"
   table_version: "WMA_2023_ONE_YEAR_FACTORS_V1"
 
-# The bands from Local Class up follow the WMA / Alan Jones convention. The
-# WMA tables define nothing below Local Class, so the three bands under 60%
-# are Calcpace's own extension, added to give recreational runners a
-# meaningful label instead of a single catch-all.
+# The WMA / Alan Jones (Howard Grubb) tables are numeric age factors and open
+# standards only — they define no categories at all. The bands from Local
+# Class (60%) upward follow the USATF Masters / National Masters News
+# convention; the three bands under 60% are Calcpace's own extension, added
+# to give recreational runners a meaningful label instead of a single
+# catch-all.
 age_grade_classifications:
   - min: 100.0
     label: "Approximate World Record Level"

data/lib/calcpace/errors.rb

@@ -20,6 +20,9 @@ class Calcpace
     end
   end
 
+  # Raised when versioned/static gem data fails an internal consistency check
+  class InvalidDataError < Error; end
+
   # Raised when an unsupported unit or unit conversion is requested
   #
   # @example conversion pair

data/lib/calcpace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Calcpace
-  VERSION = '1.18.0'
+  VERSION = '1.18.1'
 end

data/lib/calcpace.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'calcpace/errors'
 require_relative 'calcpace/calculator'
 require_relative 'calcpace/cameron_predictor'
 require_relative 'calcpace/age_grading'
@@ -7,7 +8,6 @@ require_relative 'calcpace/environmental_adjuster'
 require_relative 'calcpace/checker'
 require_relative 'calcpace/converter'
 require_relative 'calcpace/converter_chain'
-require_relative 'calcpace/errors'
 require_relative 'calcpace/fitness_predictor'
 require_relative 'calcpace/lap_analyzer'
 require_relative 'calcpace/pace_calculator'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: calcpace
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.18.1
 platform: ruby
 authors:
 - João Gilberto Saraiva