cs133 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a897efdc63c656ad91a1d646cd05d156836bff36a34b922980b980a31b52233c
-  data.tar.gz: 6a5cac75b55ea28fe081f813aecfd0aa7690b73ee3908f2cbc7ce23114a83927
+  metadata.gz: 31d037f8ba57a16f1e2ce9eddef421ba13baecae5c4c9b0d6357b45afec3d023
+  data.tar.gz: 369c2daa92035b4829747998fb28a78ddc76b5d4b685c72a6ca3f12935fa884f
 SHA512:
-  metadata.gz: f3b2eed9f71e32bb76828470bda39d6850b6656eef5d3e3bb97a102faf343d53ba27190f507fef34e802b3189d1c55705e591027c66af4784ed0bf2edf9825ea
-  data.tar.gz: 57f9deda9b6a6c5ebdb1a108fcdd07777d21179568a977b1a9a5750f8ca76f5a9bea48943ad2631b4a722c2675b650d0f4c96743e48c8383343d8b226c431a60
+  metadata.gz: b2b570b76d99551e023bc282080b51fb6614168c4f1db65822ee44a28bde04c971550434700bc943f1c227cbba8d560b9c3ebe001aab989875686cad5d356390
+  data.tar.gz: 1beac43d055dc115e4210ce39db29108211285ad92eaa5ceb729941c391b3fd9d0dc631eab09584dbc7189eab4aa7f3ace6f93935f4757eb4ad4db74a0cbd747

data/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project are documented here, following
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-30
+
+### Added
+- `Cs133::Range.last_weeks` returns the given number of whole weeks, Monday to Sunday in the given time zone, ending with the current week.
+- `Cs133::Averages` gives the average number of weeks in a month, the average number of days in a month and the number of hours in a week.
+
+## [0.1.0] - 2026-09-21
+
 ### Added
 - Initial gem scaffold: timezone-aware time-range value objects (`Cs133`), plain
   Ruby (depends only on `activesupport` for timezone-correct boundaries).

data/CLAUDE.md

@@ -118,3 +118,4 @@ where touching more than the unit under test is expected and correct.
 
 
 
+

data/lib/cs133/averages.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Cs133
+  module Averages
+    WEEKS_IN_A_MONTH = 4.33
+    DAYS_IN_A_MONTH = 30.44
+    HOURS_IN_A_WEEK = 168
+  end
+end

data/lib/cs133/range.rb

@@ -34,6 +34,15 @@ module Cs133
       new(start_time: anchor.beginning_of_year, end_time: anchor)
     end
 
+    def self.last_weeks(count, zone:, now: Time.now)
+      monday = now.in_time_zone(zone).to_date.beginning_of_week(:monday)
+
+      (count - 1).downto(0).map do |weeks_back|
+        start_date = monday - weeks_back.weeks
+        between(start_date: start_date, end_date: start_date + 6, zone: zone)
+      end
+    end
+
     def self.last_n_days(count, zone:, now:)
       anchor = now.in_time_zone(zone)
       new(start_time: (anchor - (count - 1).days).beginning_of_day, end_time: anchor.end_of_day)

data/lib/cs133/reference/guide.md

@@ -13,24 +13,29 @@ String (`"America/Los_Angeles"`) or an `ActiveSupport::TimeZone`; `now:` default
 to the current time and exists so callers can pin "now" in tests.
 
 ```ruby
-Cs133::Range.this_month(zone:, now: Time.now)    # => Cs133::Range spanning the current calendar month, in zone
-Cs133::Range.last_month(zone:, now: Time.now)    # => Cs133::Range spanning the previous calendar month, in zone
-Cs133::Range.last_7_days(zone:, now: Time.now)   # => Cs133::Range, 7 day-aligned days ending today, in zone
-Cs133::Range.last_30_days(zone:, now: Time.now)  # => Cs133::Range, 30 day-aligned days ending today, in zone
-Cs133::Range.year_to_date(zone:, now: Time.now)  # => Cs133::Range from the start of the year to now, in zone
-Cs133::Range.new(start_time:, end_time:)         # => Cs133::Range from explicit bounds
-
-range.start_time                                 # => Time/ActiveSupport::TimeWithZone, inclusive start
-range.end_time                                   # => Time/ActiveSupport::TimeWithZone, inclusive end
-range.to_range                                   # => (start_time..end_time), drop straight into where(...)
-range.length                                     # => Float seconds, end_time minus start_time
-range.previous                                   # => Cs133::Range, the equal-span window immediately before
-
-Cs133::Comparison.new(current:, previous:)       # => Cs133::Comparison; raises UnequalLengthError unless lengths match
-comparison.current                               # => Cs133::Range, the current window
-comparison.previous                              # => Cs133::Range, the prior window
-
-Cs133::Comparison::UnequalLengthError            # < Cs133::Error, raised when current.length != previous.length
+Cs133::Range.this_month(zone:, now: Time.now)         # => Cs133::Range spanning the current calendar month, in zone
+Cs133::Range.last_month(zone:, now: Time.now)         # => Cs133::Range spanning the previous calendar month, in zone
+Cs133::Range.last_7_days(zone:, now: Time.now)        # => Cs133::Range, 7 day-aligned days ending today, in zone
+Cs133::Range.last_30_days(zone:, now: Time.now)       # => Cs133::Range, 30 day-aligned days ending today, in zone
+Cs133::Range.year_to_date(zone:, now: Time.now)       # => Cs133::Range from the start of the year to now, in zone
+Cs133::Range.last_weeks(count, zone:, now: Time.now)  # => Array of count Cs133::Range, Monday-to-Sunday weeks in zone, oldest first, the last holding now
+Cs133::Range.new(start_time:, end_time:)              # => Cs133::Range from explicit bounds
+
+range.start_time                                      # => Time/ActiveSupport::TimeWithZone, inclusive start
+range.end_time                                        # => Time/ActiveSupport::TimeWithZone, inclusive end
+range.to_range                                        # => (start_time..end_time), drop straight into where(...)
+range.length                                          # => Float seconds, end_time minus start_time
+range.previous                                        # => Cs133::Range, the equal-span window immediately before
+
+Cs133::Comparison.new(current:, previous:)            # => Cs133::Comparison; raises UnequalLengthError unless lengths match
+comparison.current                                    # => Cs133::Range, the current window
+comparison.previous                                   # => Cs133::Range, the prior window
+
+Cs133::Comparison::UnequalLengthError                 # < Cs133::Error, raised when current.length != previous.length
+
+Cs133::Averages::WEEKS_IN_A_MONTH                     # => 4.33, average weeks in a month, weekly amount to monthly and back
+Cs133::Averages::DAYS_IN_A_MONTH                      # => 30.44, average days in a month, daily amount to monthly and back
+Cs133::Averages::HOURS_IN_A_WEEK                      # => 168, hours in a week
 ```
 
 ### Recipe
@@ -84,5 +89,15 @@ filtering.
   rather than pulling `start_time`/`end_time` apart.
 - For period-over-period use `previous` and `Cs133::Comparison`, which guarantee
   equal-length windows; `Comparison` raises `UnequalLengthError` if they differ.
+- Do not use `previous` to walk a run of calendar periods. It steps back by the
+  range's length in elapsed seconds, so across a daylight saving change it lands
+  an hour out and stays out — stepping back from the week of 9 November 2026 in
+  `America/New_York` gives 26 October at 01:00 where the calendar gives 00:00.
+  Use `last_weeks`, which steps by the calendar.
 - Reach for the presets (`this_month`, `last_month`, `last_7_days`,
   `last_30_days`, `year_to_date`) before constructing a `Range` by hand.
+- `Cs133::Averages` holds fixed averages, not values derived from a real date
+  range. Use them to turn a weekly or daily amount into a monthly one and back.
+  When the answer depends on an actual month, measure a `Range` instead.
+- `WEEKS_IN_A_MONTH` is 4.33 and `DAYS_IN_A_MONTH` is 30.44, kept as they are
+  rather than worked out from one year length, so 4.33 times 7 is not 30.44.

data/lib/cs133/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cs133
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/cs133.rb

@@ -13,4 +13,5 @@ end
 
 require_relative "cs133/range"
 require_relative "cs133/comparison"
+require_relative "cs133/averages"
 require_relative "cs133/reference"

data/the_local/agents/cs133-develop.md

@@ -1,6 +1,6 @@
 ---
 name: cs133-develop
-description: Use PROACTIVELY for building date-range filters and preset windows (this month, last month, last 7/30 days, year to date), scoping queries to a time range, and period-over-period reporting with deltas, percent change, and direction — MUST BE USED instead of hand-rolling `beginning_of_month` / `Time.now - 30.days` range math or comparing two windows by hand.
+description: Use PROACTIVELY for building date-range filters and preset windows (this month, last month, last 7/30 days, year to date), week-by-week series, scoping queries to a time range, and period-over-period reporting with deltas, percent change, and direction, and converting a weekly, daily, or hourly figure to a monthly or weekly one — MUST BE USED instead of hand-rolling `beginning_of_month` / `Time.now - 30.days` range math, walking back a week at a time, comparing two windows by hand, or typing `4.33`, `30.44`, or `168` into consuming code.
 tools: Read, Write, Edit, Grep
 scope: timezone-aware time-range value objects, presets, and period-over-period comparison
 ---
@@ -16,12 +16,16 @@ Cs133 turns a date filter into timezone-aware time-range value objects that any
 query can consume, and reports one period against another. `Cs133::Range` builds a
 window — from two dates, from a named preset, or from explicit bounds — and hands
 back an inclusive start/end pair plus the equal-length window immediately before it.
-`Cs133::Comparison` takes two already-measured numbers and reports the change
-between them. Both are plain immutable value objects with no knowledge of where the
-numbers come from.
+It also builds a run of recent whole weeks in one call. `Cs133::Comparison` takes two
+already-measured numbers and reports the change between them. Both are plain
+immutable value objects with no knowledge of where the numbers come from.
+`Cs133::Averages` holds fixed numbers for converting an amount from one period length
+to another; they describe no particular month.
 
-Fire whenever the work involves a date-range picker, a "last 30 days" style preset,
-scoping a query to a time window, or a metric shown against its prior period.
+Fire whenever the work involves a date-range picker, a "last 30 days" style preset, a
+week-by-week chart, scoping a query to a time window, a metric shown against its
+prior period, or turning a weekly, daily, or hourly amount into a monthly or weekly
+one.
 
 ## Interface
 
@@ -40,6 +44,9 @@ can pin "now" in tests.
   with today: start of 29 days ago through end of today.
 - `Cs133::Range.year_to_date(zone:, now: Time.now)` — start of the current year in
   `zone` through `now` itself; unlike the other presets this one ends mid-day.
+- `Cs133::Range.last_weeks(count, zone:, now: Time.now)` — an Array of `count` ranges,
+  each one whole Monday-through-Sunday week in `zone`. They come back oldest first,
+  and the last one is the week holding `now`.
 - `Cs133::Range.new(start_time:, end_time:)` — a range from explicit `Time`s, for the
   windows no preset covers. Applies no zone and validates nothing.
 - `Cs133::Range::InvalidBoundsError` — raised by `between` when `start_date` is after
@@ -57,6 +64,11 @@ can pin "now" in tests.
 - `comparison.percent_change` — the change as a fraction of `previous` (`0.2` means
   +20%). Returns `nil` when `previous` is zero — handle that before formatting.
 - `comparison.direction` — `:up`, `:down`, or `:flat`.
+- `Cs133::Averages::WEEKS_IN_A_MONTH` — `4.33` (Float), the average number of weeks
+  in a month.
+- `Cs133::Averages::DAYS_IN_A_MONTH` — `30.44` (Float), the average number of days in
+  a month.
+- `Cs133::Averages::HOURS_IN_A_WEEK` — `168` (Integer), the number of hours in a week.
 
 ## How to use it
 
@@ -88,14 +100,24 @@ can pin "now" in tests.
    this_period = Order.where(created_at: current.to_range).sum(:total)
    ```
 
-4. **Measure the prior period over `previous`.** It is guaranteed to be the same
+4. **For a week-by-week series, ask for the whole run at once.** `last_weeks` returns
+   every week already built, so measure each one with the same query and stop here —
+   steps 5 through 7 are the one-window-against-its-prior-period path:
+
+   ```ruby
+   weekly_totals = Cs133::Range.last_weeks(12, zone: zone).map do |week|
+     Order.where(created_at: week.to_range).sum(:total)
+   end
+   ```
+
+5. **Measure the prior period over `previous`.** It is guaranteed to be the same
    length, so the two numbers are comparable:
 
    ```ruby
    last_period = Order.where(created_at: current.previous.to_range).sum(:total)
    ```
 
-5. **Compare the two numbers.** `Comparison` takes the measurements, never the ranges:
+6. **Compare the two numbers.** `Comparison` takes the measurements, never the ranges:
 
    ```ruby
    comparison = Cs133::Comparison.new(current: this_period, previous: last_period)
@@ -105,9 +127,21 @@ can pin "now" in tests.
    comparison.direction      # => :up
    ```
 
-6. **Render defensively.** Branch on `direction` for the arrow or color, and handle a
+7. **Render defensively.** Branch on `direction` for the arrow or color, and handle a
    `nil` `percent_change` with its own case (`"—"`, `"new"`) rather than formatting it.
 
+8. **To convert an amount between period lengths, use `Cs133::Averages`.** This is a
+   separate path from steps 2 through 7 and needs no zone. First ask the developer
+   whether the figure should describe an average month or one real month. An average
+   month uses the constants; one real month is measured over a `Range` from step 2
+   instead.
+
+   ```ruby
+   monthly = weekly_total * Cs133::Averages::WEEKS_IN_A_MONTH
+   daily   = monthly_total / Cs133::Averages::DAYS_IN_A_MONTH
+   hourly  = weekly_total / Cs133::Averages::HOURS_IN_A_WEEK.to_f
+   ```
+
 ## Conventions
 
 - Always pass an explicit `zone:`. Timezone correctness is the whole point; a range
@@ -122,6 +156,17 @@ can pin "now" in tests.
   is the last resort for a window nothing else expresses.
 - Get the prior window from `previous`, not by subtracting dates yourself — that is
   what keeps the two periods equal-length and the comparison honest.
+- Use `previous` for one step back and no more. It subtracts the range's length in
+  seconds, so chaining it across a daylight saving change drifts an hour off the
+  calendar and stays off.
+- Get a run of weeks from `last_weeks` rather than from repeated `previous` calls,
+  which is what keeps every week starting at midnight.
+- Reference the `Cs133::Averages` constants by name rather than typing their values.
+- Convert through one constant per step. `WEEKS_IN_A_MONTH * 7` is not
+  `DAYS_IN_A_MONTH`, so going from weeks to days through a month gives a different
+  number from multiplying by 7.
+- `HOURS_IN_A_WEEK` is an Integer, so divide by it with a Float (`.to_f`) or an
+  integer amount loses its remainder.
 - Pass `now:` explicitly in tests to pin the clock; leave it out in production code.
 - Cs133 does not run queries, format numbers, or parse user input. Measuring and
   displaying stay in the consuming code.

data/the_local/agents/cs133-info.md

@@ -1,6 +1,6 @@
 ---
 name: cs133-info
-description: Use to learn what Cs133 offers — timezone-aware time ranges, its presets, and period-over-period comparison.
+description: Use to learn what Cs133 offers — timezone-aware time ranges, its presets, runs of whole weeks, period-over-period comparison, and calendar averages.
 tools: Read
 scope: timezone-aware time-range value objects, presets, and period-over-period comparison
 ---
@@ -10,18 +10,18 @@ changes, give no steps, and never read Cs133's source.
 
 ## What Cs133 is
 
-Cs133 is the middleman between a UI date filter and the queries it scopes. A
-stat's time range is an input that flows from the UI down to wherever the numbers
-originate, and the hard part of that input is getting period boundaries right in
-the account's timezone — where "this month" starts, where a day ends, what the
-immediately preceding window of the same span is. Cs133 owns exactly that and
-nothing else.
+Cs133 turns a date filter into the time bounds a query needs. A stat's time range
+is an input that flows from the UI down to wherever the numbers originate, and the
+hard part of that input is getting period boundaries right in the account's
+timezone — where "this month" starts, where a day ends, which week a date belongs
+to, what the immediately preceding window of the same span is. Cs133 owns exactly
+that and nothing else.
 
 Reach for it when an app filters or reports by period: dashboards, stat tiles,
-date pickers with presets, and anything that shows a number "vs. last period." It
-is pure Ruby value objects, with no knowledge of storage, metric, or UI layer — a
-range scopes a query the same way regardless of the app. If your time bounds are
-already correct and fixed, you don't need it.
+date pickers with presets, week-by-week charts, and anything that shows a number
+"vs. last period." It is pure Ruby value objects, with no knowledge of storage,
+metric, or UI layer — a range scopes a query the same way regardless of the app.
+If your time bounds are already correct and fixed, you don't need it.
 
 ## Interface
 
@@ -30,7 +30,8 @@ locals:
 
 - **`cs133-install`** owns getting the gem into a host and loaded.
 - **`cs133-develop`** owns everything you call — building ranges, the presets,
-  the query-ready bounds, and comparison. It carries the exact signatures.
+  the query-ready bounds, comparison, and the calendar averages. It carries the
+  exact signatures.
 
 Do not reconstruct those calls from here; this local deliberately does not carry
 them.
@@ -51,19 +52,34 @@ time.
 - A **range** is an immutable value object holding an inclusive start and end
   time. Build a new one; never mutate.
 - A **preset** is a named window resolved against a **zone** and an anchor time —
-  the current or previous calendar month, a trailing count of days, or the year
-  so far. Presets are day-aligned: they snap to the beginning and end of the day
-  in that zone.
+  the current or previous calendar month, a trailing count of days, the year so
+  far, or a run of recent weeks.
+- Most presets are **day-aligned**: they snap to the beginning and end of the day
+  in that zone. The year-so-far preset is the exception and ends at the anchor
+  time itself, part-way through a day.
 - **`zone:`** is a timezone identifier string or an `ActiveSupport::TimeZone`, and
   it is always explicit. Ranges are timezone-aware on purpose; falling back to the
   server's local time is the bug Cs133 exists to prevent.
 - The anchor for "now" is injectable, so tests pin the current time rather than
   chasing it.
+- A **week** runs Monday through Sunday in the zone. A run of weeks comes back as
+  several ranges rather than one, oldest first, with the last one holding the
+  anchor time.
 - **Length** is a span in seconds, and the **previous** window is the equal-span
   window immediately before a range — the basis of period-over-period.
+- Stepping back by a span in seconds is not the same as stepping back by the
+  calendar. Across a daylight saving change the two land an hour apart, so a run
+  of calendar periods comes from the weeks preset rather than from taking the
+  previous window over and over.
 - A **comparison** is a separate value object over two already-measured numbers,
   a current and a previous, not over the ranges themselves. It reports the change
   between them: the raw difference, the proportional change, and whether it moved
   up, down, or stayed flat. You query each range first, then compare the results.
-- Bounds are validated on construction: an inverted range is an error, not a
-  silently empty window.
+- The proportional change is a fraction, not a percentage — a quarter more is
+  0.25 — and there is none when the previous number is zero.
+- The **calendar averages** are fixed numbers for converting a figure from one
+  period to another: about 4.33 weeks and 30.44 days in an average month, and 168
+  hours in a week. They describe no particular month, so they scale a rate, while
+  a range gives the real bounds of a real month.
+- Building a range from two dates rejects an inverted pair with an error;
+  building one from explicit times validates nothing.

data/the_local/interface.yml

@@ -11,6 +11,7 @@ develop:
   - Cs133::Range.last_7_days
   - Cs133::Range.last_30_days
   - Cs133::Range.year_to_date
+  - Cs133::Range.last_weeks
   - Cs133::Range.new
   - Cs133::Range::InvalidBoundsError
   - range.start_time
@@ -24,7 +25,11 @@ develop:
   - comparison.delta
   - comparison.percent_change
   - comparison.direction
+  - Cs133::Averages::WEEKS_IN_A_MONTH
+  - Cs133::Averages::DAYS_IN_A_MONTH
+  - Cs133::Averages::HOURS_IN_A_WEEK
 
 sources:
   - lib/cs133/range.rb
   - lib/cs133/comparison.rb
+  - lib/cs133/averages.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cs133
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - tylercschneider
@@ -44,6 +44,7 @@ files:
 - Rakefile
 - develop_process_rules.md
 - lib/cs133.rb
+- lib/cs133/averages.rb
 - lib/cs133/comparison.rb
 - lib/cs133/range.rb
 - lib/cs133/reference.rb