moon_phase_tracker 1.3.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fbc22c1b9f3481bd4585f49394696bea4bbef56302467bc0d9433bc17f6c179
-  data.tar.gz: bd9d8566042eb8d1dccc4ab8ce66de2e6542e9103e3c2732ee45c0f467c98e3d
+  metadata.gz: 9c9587009682cc81b906d04054af17b88ae9863ebc56227457d507a2e484eb9c
+  data.tar.gz: 9a55ae1b9ffc3920f0fa7b9096bb5f107980efe55f646caf4d6f104890c51abb
 SHA512:
-  metadata.gz: b5575c03ca0ea020a9b9332c0c624567dd9cd370192c0db29ef5578d28c0f98bfbc8c5d2811eeb3498d270b2e1ee8ef279028c0f4638ae4063ff7958abe02457
-  data.tar.gz: ffe82390f6ad4deab517a8aaa0ef0e32541da030b0b0a10ba5d6991ae1749d2219069d5838cad8e05bff76f3c31913355536e766b50052fa590b177b046c2c7a
+  metadata.gz: '04509c13863e69615e2a4af359e997e9481fd3765e0950fe3a966a25d5f3bca4609607fbed3a1b5d2e32b375887e97ac4ec82d937224889988842b639ab26fc7'
+  data.tar.gz: 890dd9e2ec203dd22b512f50e7e5831ec7f18932ded680366627883c42307dcc3cc4f7e2009e44783b98e77791de51f34ca44512534375d7437b3b73f7c5a313

data/README.md

@@ -1,23 +1,29 @@
-# MoonPhaseTracker 🌙
+# 🌙 MoonPhaseTracker - Your Cosmic Calendar Companion
 
-A Ruby gem for tracking moon phases using the official US Naval Observatory (USNO) API. Perfect for creating lunar calendar-based scheduling applications.
+*"Because every developer deserves to howl at the right moon."*
 
-**Expected accuracy: ~85-90% (suitable for lunar calendars)**
+Ever wondered when to deploy your code for maximum lunar luck? Or perhaps you need to schedule that midnight debugging session during a proper New Moon? This delightful Ruby gem connects you to the cosmic dance above, using the official US Naval Observatory (USNO) API to bring celestial timing to your fingertips.
 
-## Features
+Whether you're building a werewolf scheduling app, a vampire calendar, or just want to impress your users with lunar-powered features, MoonPhaseTracker has got your back under every phase of the moon.
 
-- 🌑 Query moon phases by month, year, or from a specific date
-- 🌒 Complete 8-phase lunar cycle support (4 major + 4 intermediate phases)
-- 🌓 Simple and intuitive interface  
-- 🌔 Accurate data from the official USNO Navy API
-- 🌕 Visual representation with moon phase emojis
-- 🌖 Interpolated intermediate phases for enhanced precision
-- 🌗 Visual indicators for calculated vs official phases
-- 🌘 Automatic caching to optimize requests
-- ⚡ Robust error handling
-- 🚦 Configurable rate limiting to respect API limits
+**🎯 Accuracy: ~85-90%** *(Good enough for lunar calendars, probably too precise for howling)*
 
-## Installation
+## ✨ What Makes This Gem Shine
+
+- 🌑 **Time Travel Through Lunar Cycles** - Query moon phases by month, year, or from any date your heart desires
+- 🌒 **The Full Lunar Symphony** - Complete 8-phase support (4 major crescendos + 4 melodic interludes)
+- 🌓 **Simple as Moonlight** - An interface so intuitive, even a sleepy developer can use it at 3 AM
+- 🌔 **Navy-Grade Precision** - Official USNO data because the Navy doesn't mess around with moon phases
+- 🌕 **Emoji Magic** - Visual moon phases that spark joy in your terminal
+- 🌖 **Mathematical Lunar Poetry** - Interpolated intermediate phases for when precision meets artistry
+- 🌗 **Truth in Advertising** - Clear indicators showing official vs calculated phases (no moon phase imposters here!)
+- 🌘 **Memory Like an Elephant** - Automatic caching because nobody likes waiting for the moon
+- ⚡ **Bulletproof & Graceful** - Error handling that fails as elegantly as moonbeams
+- 🚦 **API Etiquette** - Respectful rate limiting because even the Navy deserves a break
+
+## 🚀 Summoning the Lunar Powers
+
+*Ready to add some celestial magic to your Ruby project?*
 
 Add this line to your application's Gemfile:
 
@@ -37,9 +43,13 @@ Or install it directly:
 gem install moon_phase_tracker
 ```
 
-## Usage
+## 🎭 Lunar Adventures Await
+
+*Time to dance with the moon phases like a cosmic choreographer!*
 
-### Basic Usage (4 Major Phases)
+### 🌟 The Essential Four - Your Lunar Greatest Hits
+
+*Start your journey with the moon's main characters: the celestial quartet that's been stealing hearts since ancient times.*
 
 ```ruby
 require 'moon_phase_tracker'
@@ -48,23 +58,26 @@ require 'moon_phase_tracker'
 phases = MoonPhaseTracker.phases_for_month(2025, 8)
 puts phases.first.to_s
 # => "🌑 New Moon - 2025-08-04 at 11:13"
+# (Perfect timing for new beginnings!)
 
-# All phases for 2025
+# All phases for 2025 - your yearly lunar roadmap
 year_phases = MoonPhaseTracker.phases_for_year(2025)
 
-# Next 6 phases from a specific date
+# Next 6 phases from a specific date - peek into the future
 future_phases = MoonPhaseTracker.phases_from_date("2025-08-01", 6)
 ```
 
-### Complete 8-Phase Lunar Cycle
+### 🎨 The Full Lunar Canvas - All 8 Phases in Their Glory
+
+*For the lunar perfectionists who want the complete story, not just the highlights reel.*
 
 ```ruby
 require 'moon_phase_tracker'
 
-# All 8 phases for August 2025 (major + intermediate)
+# All 8 phases for August 2025 - the complete lunar symphony
 all_phases = MoonPhaseTracker.all_phases_for_month(2025, 8)
 all_phases.each do |phase|
-  indicator = phase.interpolated ? "~ " : "  "
+  indicator = phase.interpolated ? "~ " : "  "  # ~ means "calculated with love"
   puts "#{indicator}#{phase}"
 end
 # =>   🌑 New Moon - 2025-08-04 at 11:13
@@ -76,48 +89,96 @@ end
 # =>   🌗 Last Quarter - 2025-08-26 at 09:26
 # => ~ 🌘 Waning Crescent - 2025-08-29 at 02:56
 
-# All 8 phases for entire year
+# All 8 phases for entire year - your cosmic annual planner
 all_year_phases = MoonPhaseTracker.all_phases_for_year(2025)
 
-# All 8 phases from specific date (2 lunar cycles)
+# All 8 phases from specific date (2 lunar cycles) - the extended edition
 extended_phases = MoonPhaseTracker.all_phases_from_date("2025-08-01", 2)
 ```
 
-### Using the Tracker Class
+### 🔮 Instant Moon Phase - No API, No Waiting
+
+*What phase is the moon right now? How bright is it? Pure math, instant answer.*
+
+These methods use a synodic month calculation — no API calls, no network, no rate limits. Perfect for display UIs and real-time widgets.
+
+```ruby
+require 'moon_phase_tracker'
+
+# What's the moon doing right now?
+phase = MoonPhaseTracker.current_phase
+puts phase.to_s
+# => "🌔 Waxing Gibbous - 2025-08-15 at 14:30"
+puts phase.illumination  # => 78.5 (percent)
+puts phase.lunar_age     # => 12.3 (days since last new moon)
+puts phase.source        # => :calculated
+
+# Phase at any date/time - past or future
+phase = MoonPhaseTracker.phase_at(Time.utc(2025, 6, 11, 7, 44))
+puts phase.name          # => "Full Moon"
+puts phase.illumination  # => ~100.0
+
+# Just the illumination percentage
+illum = MoonPhaseTracker.illumination(Date.today)
+puts "#{illum.round(1)}% illuminated"
+
+# Works with Date, Time, DateTime, or String
+MoonPhaseTracker.phase_at(Date.new(2025, 1, 15))
+MoonPhaseTracker.phase_at("2025-01-15")
+MoonPhaseTracker.phase_at(DateTime.now)
+```
+
+> **Accuracy note:** The synodic model gives the correct named phase ~99% of the time. Within ~6 hours of a phase boundary, it may differ from USNO API data. The API path gives precision for scheduling; the calculator path gives instant answers for display.
+
+### 🎯 The Tracker Class - Your Personal Lunar Assistant
+
+*Think of it as your moon phase butler, always ready to serve up cosmic timing with a bow tie.*
 
 ```ruby
 tracker = MoonPhaseTracker::Tracker.new
 
-# Automatic formatting for display
+# Automatic formatting for display - because presentation matters
 august_phases = tracker.phases_for_month(2025, 8)
 formatted = tracker.format_phases(august_phases, "August Phases")
 puts formatted
 
-# Next moon phase
+# Next moon phase - your cosmic fortune telling
 next_phase = tracker.next_phase
 puts next_phase.to_s
 
-# Current month phases
+# Current month phases - what's happening in your lunar neighborhood
 current_month = tracker.current_month_phases
+
+# Instant phase at any date - no API call needed
+phase = tracker.phase_at("2025-06-11")
+puts phase.illumination  # => Float (percent)
+
+# Just the illumination number
+illum = tracker.illumination("2025-06-11")
+
+# Current phase right now
+puts tracker.current_phase
 ```
 
-### Working with Individual Phases
+### 🔍 Getting Personal with Moon Phases
+
+*Each phase has its own personality - let's get to know them intimately.*
 
 ```ruby
 phase = phases.first
 
 # Phase information
 puts phase.name          # "New Moon"
-puts phase.symbol        # "🌑"
+puts phase.symbol        # "🌑" (isn't it beautiful?)
 puts phase.formatted_date # "2025-08-04"
-puts phase.formatted_time # "11:13"
-puts phase.interpolated   # false (official USNO data)
+puts phase.formatted_time # "11:13" (UTC - the moon doesn't do timezones)
+puts phase.interpolated   # false (certified genuine USNO data)
 
-# Working with interpolated phases
+# Working with interpolated phases - the mathematically gifted ones
 interpolated_phase = all_phases.find(&:interpolated)
-puts interpolated_phase.interpolated  # true (calculated)
+puts interpolated_phase.interpolated  # true (calculated with mathematical precision)
 puts interpolated_phase.name         # "Waxing Crescent"
-puts interpolated_phase.symbol       # "🌒"
+puts interpolated_phase.symbol       # "🌒" (still adorable)
 
 # Complete hash with all data
 details = phase.to_h
@@ -129,94 +190,191 @@ details = phase.to_h
 #   symbol: "🌑",
 #   iso_date: "2025-08-04",
 #   utc_time: "2025-08-04T11:13:00Z",
-#   interpolated: false
+#   interpolated: false,
+#   source: :api,           # :api, :interpolated, or :calculated
+#   illumination: nil,      # Float for calculated phases, nil for API
+#   lunar_age: nil          # Float for calculated phases, nil for API
 # }
 
-# Date checks
-phase.in_month?(2025, 8)  # => true
-phase.in_year?(2025)      # => true
+# Date checks - lunar detective work
+phase.in_month?(2025, 8)  # => true (August moon confirmed!)
+phase.in_year?(2025)      # => true (definitely a 2025 vintage)
 ```
 
-### Error Handling
+### 🛡️ When the Moon Plays Hard to Get
+
+*Even celestial bodies have bad days. Here's how to handle lunar tantrums gracefully.*
 
 ```ruby
 begin
   phases = MoonPhaseTracker.phases_for_month(2025, 8)
 rescue MoonPhaseTracker::NetworkError => e
-  puts "Network error: #{e.message}"
+  puts "Network hiccup: #{e.message}" # The internet is having a moment
 rescue MoonPhaseTracker::APIError => e
-  puts "API error: #{e.message}"
+  puts "API tantrum: #{e.message}"   # The Navy API is feeling moody
 rescue MoonPhaseTracker::InvalidDateError => e
-  puts "Invalid date: #{e.message}"
+  puts "Time travel error: #{e.message}" # That date doesn't exist in this dimension
+end
+```
+
+### 🎪 Real-World Lunar Magic
+
+*Because theory is nice, but seeing the moon phases in action is where the real magic happens.*
+
+#### Hybrid Architecture: USNO for Scheduling, Calculator for Display
+
+The API gives you exact dates. The calculator gives you instant answers. Use both — a background job populates a `lunar_phases` table with USNO data, and `LunarCalculator` handles the real-time display layer.
+
+```ruby
+# app/jobs/sync_lunar_phases_job.rb
+class SyncLunarPhasesJob < ApplicationJob
+  def perform(year = Date.current.year)
+    phases = MoonPhaseTracker.all_phases_for_year(year)
+
+    phases.each do |phase|
+      LunarPhase.upsert(
+        {
+          name: phase.name,
+          phase_type: phase.phase_type.to_s,
+          exact_at: phase.to_h[:utc_time],
+          source: phase.source.to_s
+        },
+        unique_by: :exact_at
+      )
+    end
+  end
+end
+```
+
+```ruby
+# app/models/lunar_phase.rb
+class LunarPhase < ApplicationRecord
+  scope :upcoming, -> { where("exact_at > ?", Time.current).order(:exact_at) }
+  scope :next_full_moon, -> { upcoming.where(phase_type: "full_moon").first }
+end
+```
+
+```ruby
+# app/helpers/moon_helper.rb
+module MoonHelper
+  def moon_badge(date = Date.current)
+    phase = MoonPhaseTracker.phase_at(date)
+    "#{phase.symbol} #{phase.illumination.round}%"
+  end
 end
 ```
 
-### Practical Examples
+Two data sources, each doing what they do best. The table owns scheduling precision (notifications, rituals, content triggers). The calculator owns display (emoji, illumination percentage, "what phase is it right now?"). They never step on each other's toes.
+
+See the `examples/usage_example.rb` and `examples/eight_phases_example.rb` files for more usage examples.
 
-See the `examples/usage_example.rb` and `examples/eight_phases_example.rb` files for complete usage examples.
+## 📚 The Lunar Grimoire - Complete API Spellbook
 
-## API Reference
+*Your comprehensive guide to all the lunar incantations at your disposal.*
 
-### Main Methods (4 Major Phases)
+### 🎭 The Core Cast - 4 Major Phase Methods
+
+*The essential methods that'll get you 80% of your lunar needs covered.*
 
 - `MoonPhaseTracker.phases_for_month(year, month)` - Major phases for a specific month
 - `MoonPhaseTracker.phases_for_year(year)` - All major phases for a year
 - `MoonPhaseTracker.phases_from_date(date, num_phases)` - Major phases from a specific date
 
-### 8-Phase Methods (Major + Intermediate)
+### 🔮 Instant Lookup - No API Required
+
+*Pure math, zero latency. For when you need the moon right now.*
+
+- `MoonPhaseTracker.phase_at(date)` - Phase at any date/time (returns `Phase` with illumination)
+- `MoonPhaseTracker.illumination(date)` - Illumination percentage (returns `Float` 0..100)
+- `MoonPhaseTracker.current_phase` - Phase right now (shortcut for `phase_at(Time.now.utc)`)
+
+No API calls — pure math under the hood.
+
+### 🌈 The Full Spectrum - 8-Phase Methods for Lunar Completionists
+
+*For those who believe in doing things thoroughly (and slightly obsessively).*
 
 - `MoonPhaseTracker.all_phases_for_month(year, month)` - All 8 phases for a specific month
 - `MoonPhaseTracker.all_phases_for_year(year)` - All 8 phases for a year
 - `MoonPhaseTracker.all_phases_from_date(date, num_cycles)` - All 8 phases from a specific date
 
-### Complete Phase Types
+### 🎨 Meet the Lunar Cast - All 8 Phase Personalities
+
+#### 🏆 The Main Characters (Official USNO Data)
+*These are the A-listers - certified by the Navy, guaranteed to impress.*
+- 🌑 `:new_moon` - New Moon *(The mysterious beginning)*
+- 🌓 `:first_quarter` - First Quarter *(Half-lit and growing strong)*
+- 🌕 `:full_moon` - Full Moon *(The showstopper, the main event)*
+- 🌗 `:last_quarter` - Last Quarter *(Gracefully waning)*
+
+#### 🎭 The Supporting Cast (Interpolated ~85-90% accuracy)
+*The understudies that complete the story - mathematically calculated with love.*
+- 🌒 `:waxing_crescent` - Waxing Crescent *(The optimistic youngster)*
+- 🌔 `:waxing_gibbous` - Waxing Gibbous *(Almost there, building anticipation)*
+- 🌖 `:waning_gibbous` - Waning Gibbous *(The wise elder, still radiant)*
+- 🌘 `:waning_crescent` - Waning Crescent *(The gentle farewell)*
+
+### 🏷️ Phase Sources - Know Where Your Data Comes From
+
+*Every phase carries a passport stamped with its origin story.*
 
-#### Major Phases (Official USNO Data)
-- 🌑 `:new_moon` - New Moon
-- 🌓 `:first_quarter` - First Quarter
-- 🌕 `:full_moon` - Full Moon
-- 🌗 `:last_quarter` - Last Quarter
+| Source | Meaning | When |
+|--------|---------|------|
+| `:api` | Official USNO data | `phases_for_month`, `phases_for_year`, etc. |
+| `:interpolated` | Calculated between two API phases | `all_phases_for_month`, `all_phases_for_year`, etc. |
+| `:calculated` | Pure synodic math model | `phase_at`, `illumination`, `current_phase` |
 
-#### Intermediate Phases (Interpolated ~85-90% accuracy)
-- 🌒 `:waxing_crescent` - Waxing Crescent 
-- 🌔 `:waxing_gibbous` - Waxing Gibbous
-- 🌖 `:waning_gibbous` - Waning Gibbous
-- 🌘 `:waning_crescent` - Waning Crescent
+```ruby
+phase = MoonPhaseTracker.phase_at(Date.today)
+phase.source        # => :calculated
+phase.illumination  # => 65.3 (percent)
+phase.lunar_age     # => 10.2 (days since last new moon)
+```
+
+## ⚓ Our Trusted Cosmic Oracle
+
+*We get our lunar wisdom from the finest source - the folks who navigate the seven seas by the stars.*
 
-## Data Source
+This gem uses the official US Naval Observatory (USNO) API - because when it comes to celestial navigation, you want the folks who've been steering ships by the stars for centuries:
 
-This gem uses the official US Naval Observatory (USNO) API:
 - **Base URL**: https://aa.usno.navy.mil/api/moon/phases/
-- **API Version**: 4.0.1
+- **API Version**: 4.0.1 (battle-tested and Navy-approved)
 - **Documentation**: https://aa.usno.navy.mil/data/api
 
-All times are provided in Universal Time (UTC).
+All times are provided in Universal Time (UTC) - because the moon doesn't care about your timezone preferences, and neither should precise astronomical data.
 
-## Rate Limiting
+## 🚦 Playing Nice with the Navy - Rate Limiting with Style
 
-The gem implements respectful rate limiting to avoid overwhelming the USNO Navy API. By default, it allows **1 request per second** with a burst size of 1.
+*Because even cosmic APIs need coffee breaks, and we're not monsters.*
 
-### Default Rate Limiting
+Think of rate limiting as the polite pause between questions when chatting with a wise oracle. We implement respectful rate limiting to keep the USNO Navy API happy (and responsive). By default, we're as patient as a monk - **1 request per second** with the restraint of a zen master.
+
+
+### 🧘 The Zen Approach - Default Rate Limiting
+
+*Slow and steady wins the lunar race.*
 
 ```ruby
-# Default: 1 request per second
+# Default: 1 request per second - the patient approach
 tracker = MoonPhaseTracker::Tracker.new
 
-# Check current rate limit configuration
+# Check current rate limit configuration - know thy limits
 puts tracker.rate_limit_info
 # => {:requests_per_second=>1.0, :burst_size=>1, :available_tokens=>1}
 
-# Multiple requests will be automatically rate limited
+# Multiple requests will be automatically rate limited - watch the magic
 start = Time.now
-tracker.phases_for_year(2025)  # Immediate
-tracker.phases_for_year(2024)  # Waits ~1 second
+tracker.phases_for_year(2025)  # Immediate (first one's free!)
+tracker.phases_for_year(2024)  # Waits ~1 second (patience, young padawan)
 puts "Total time: #{Time.now - start}s"  # ~1.0 seconds
 ```
 
-### Custom Rate Limiting
+### ⚡ Need for Speed? - Custom Rate Limiting
+
+*For when you want to live life in the fast lane (but still be respectful).*
 
 ```ruby
-# Create custom rate limiter: 3 requests per second, burst of 2
+# Create custom rate limiter: 3 requests per second, burst of 2 - living a little
 rate_limiter = MoonPhaseTracker::RateLimiter.new(
   requests_per_second: 3.0,
   burst_size: 2
@@ -224,16 +382,18 @@ rate_limiter = MoonPhaseTracker::RateLimiter.new(
 
 tracker = MoonPhaseTracker::Tracker.new(rate_limiter: rate_limiter)
 
-# Burst requests are immediate, then rate limited
-tracker.phases_for_year(2025)  # Immediate
-tracker.phases_for_year(2024)  # Immediate (burst)
-tracker.phases_for_year(2023)  # Waits ~0.33 seconds
+# Burst requests are immediate, then rate limited - controlled excitement
+tracker.phases_for_year(2025)  # Immediate (wheee!)
+tracker.phases_for_year(2024)  # Immediate (double wheee!)
+tracker.phases_for_year(2023)  # Waits ~0.33 seconds (and... breathe)
 ```
 
-### Environment Variable Configuration
+### 🌍 Set It and Forget It - Environment Variables
+
+*Configure once, smile forever.*
 
 ```ruby
-# Set via environment variables
+# Set via environment variables - the lazy developer's paradise
 ENV["MOON_PHASE_RATE_LIMIT"] = "2.5"
 ENV["MOON_PHASE_BURST_SIZE"] = "3"
 
@@ -242,20 +402,24 @@ puts tracker.rate_limit_info
 # => {:requests_per_second=>2.5, :burst_size=>3, :available_tokens=>3}
 ```
 
-### Disabling Rate Limiting
+### 🏁 Living Dangerously - Disabling Rate Limiting
+
+*For the rebels and the reckless (use responsibly, dear lunar adventurer).*
 
 ```ruby
-# Disable rate limiting completely
+# Disable rate limiting completely - for the speed demons
 ENV["MOON_PHASE_RATE_LIMIT"] = "0"
 
 tracker = MoonPhaseTracker::Tracker.new
-puts tracker.rate_limit_info  # => nil
+puts tracker.rate_limit_info  # => nil (no limits, no safety net!)
 
-# Or pass nil explicitly
+# Or pass nil explicitly - the explicit rebel
 tracker = MoonPhaseTracker::Tracker.new(rate_limiter: nil)
 ```
 
-### Rate Limit Monitoring
+### 🔬 Under the Hood - Rate Limit Monitoring
+
+*For the control freaks and performance enthusiasts among us.*
 
 ```ruby
 rate_limiter = MoonPhaseTracker::RateLimiter.new(
@@ -263,18 +427,20 @@ rate_limiter = MoonPhaseTracker::RateLimiter.new(
   burst_size: 2
 )
 
-# Check if request can proceed without waiting
-puts rate_limiter.can_proceed?  # => true
+# Check if request can proceed without waiting - the crystal ball
+puts rate_limiter.can_proceed?  # => true (or false if you've been naughty)
 
-# Check current token status
+# Check current token status - your digital wallet
 puts rate_limiter.configuration
 # => {:requests_per_second=>1.0, :burst_size=>2, :available_tokens=>2}
 
-# Manual rate limiting control
-rate_limiter.throttle  # Waits if necessary and consumes token
+# Manual rate limiting control - take the wheel
+rate_limiter.throttle  # Waits if necessary and consumes token (om nom nom)
 ```
 
-### Token Bucket Algorithm
+### 🪣 The Magic Behind the Curtain - Token Bucket Algorithm
+
+*The elegant dance of digital tokens that keeps everything flowing smoothly.*
 
 The rate limiter uses a token bucket algorithm:
 
@@ -283,20 +449,28 @@ The rate limiter uses a token bucket algorithm:
 - **Refill Rate**: How quickly tokens are replenished
 - **Thread Safe**: Handles concurrent requests safely
 
-## Development
+## 🛠️ Join the Lunar Development Cult
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+*Want to contribute to the cosmic cause? We welcome fellow moon enthusiasts!*
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+After checking out the repo, run `bin/setup` to install dependencies (like preparing your lunar laboratory). Then, run `rake spec` to run the tests (because even moon phases need quality control). You can also run `bin/console` for an interactive prompt that will allow you to experiment (perfect for midnight coding sessions under the actual moon).
 
-## Contributing
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org) (sharing lunar magic with the world!).
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/dklima/moon_phase_tracker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/dklima/moon_phase_tracker/blob/main/CODE_OF_CONDUCT.md).
+## 🤝 Become a Lunar Contributor
 
-## License
+*Every great gem needs a community of stargazers and code wizards.*
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dklima/moon_phase_tracker. Found a bug? Think of it as discovering a new lunar crater - exciting stuff! This project is intended to be a safe, welcoming space for collaboration, where all contributors can shine as bright as a Full Moon. Contributors are expected to adhere to the [code of conduct](https://github.com/dklima/moon_phase_tracker/blob/main/CODE_OF_CONDUCT.md).
+
+## 📜 Legal Lunar Stuff
+
+*Even moon phases need proper paperwork.*
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
+## 🌟 Lunar Community Guidelines
+
+*We believe in creating a space as welcoming as moonlight on a summer evening.*
 
-Everyone interacting in the MoonPhaseTracker project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/dklima/moon_phase_tracker/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the MoonPhaseTracker project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/dklima/moon_phase_tracker/blob/main/CODE_OF_CONDUCT.md). Together, we create a community as harmonious as the lunar cycles themselves.

data/Rakefile

@@ -1,8 +1,8 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/eight_phases_example.rb

@@ -1,100 +1,100 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Add the lib directory to the load path
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-
-require 'moon_phase_tracker'
-
-puts '=== Moon Phase Tracker - 8 Phases Example ==='
-puts 'Demonstrating all 8 lunar phases (4 major + 4 intermediate)'
-puts ''
-
-begin
-  # Example 1: Get all 8 phases for August 2025
-  puts '🌙 All phases for August 2025:'
-  puts '=' * 40
-  phases = MoonPhaseTracker.all_phases_for_month(2025, 8)
-
-  if phases.any?
-    phases.each do |phase|
-      prefix = phase.interpolated ? '~ ' : '  '
-      puts "#{prefix}#{phase}"
-    end
-
-    major_count = phases.count { |p| !p.interpolated }
-    interpolated_count = phases.count(&:interpolated)
-
-    puts ''
-    puts "Total: #{phases.size} phases (#{major_count} major, #{interpolated_count} interpolated)"
-    puts '~ indicates interpolated phases'
-  else
-    puts 'No phases found for this period.'
-  end
-
-  puts ''
-  puts '-' * 50
-  puts ''
-
-  # Example 2: Compare 4 vs 8 phases
-  puts '🔍 Comparison: 4 Major Phases vs 8 Complete Phases'
-  puts '=' * 55
-
-  major_phases = MoonPhaseTracker.phases_for_month(2025, 8)
-  all_phases = MoonPhaseTracker.all_phases_for_month(2025, 8)
-
-  puts "Major phases only (#{major_phases.size}):"
-  major_phases.each { |phase| puts "  #{phase}" }
-
-  puts ''
-  puts "All phases including interpolated (#{all_phases.size}):"
-  all_phases.each do |phase|
-    prefix = phase.interpolated ? '~ ' : '  '
-    puts "#{prefix}#{phase}"
-  end
-
-  puts ''
-  puts '-' * 50
-  puts ''
-
-  # Example 3: Show phase symbols
-  puts '🎭 Phase Symbols Reference'
-  puts '=' * 30
-  MoonPhaseTracker::Phase::PHASE_SYMBOLS.each do |type, symbol|
-    name = type.to_s.split('_').map(&:capitalize).join(' ')
-    puts "#{symbol} #{name}"
-  end
-
-  puts ''
-  puts '-' * 50
-  puts ''
-
-  # Example 4: Get phases from a specific date with 8 phases
-  puts '📅 8 Phases from a specific date (2025-08-01, 2 cycles)'
-  puts '=' * 60
-  date_phases = MoonPhaseTracker.all_phases_from_date('2025-08-01', 2)
-
-  if date_phases.any?
-    date_phases.each do |phase|
-      prefix = phase.interpolated ? '~ ' : '  '
-      puts "#{prefix}#{phase}"
-    end
-
-    major_count = date_phases.count { |p| !p.interpolated }
-    interpolated_count = date_phases.count(&:interpolated)
-
-    puts ''
-    puts "Total: #{date_phases.size} phases over 2 lunar cycles"
-    puts "(#{major_count} major, #{interpolated_count} interpolated)"
-  end
-rescue MoonPhaseTracker::Error => e
-  puts "Error: #{e.message}"
-rescue StandardError => e
-  puts "Unexpected error: #{e.message}"
-  puts 'This example requires an active internet connection to fetch moon phase data.'
-end
-
-puts ''
-puts 'Note: This example uses real astronomical data from the US Naval Observatory.'
-puts 'Interpolated phases (~) are calculated estimates between official phases.'
-puts 'All dates are in ISO 8601 format (YYYY-MM-DD) and times are in UTC.'
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add the lib directory to the load path
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'moon_phase_tracker'
+
+puts '=== Moon Phase Tracker - 8 Phases Example ==='
+puts 'Demonstrating all 8 lunar phases (4 major + 4 intermediate)'
+puts ''
+
+begin
+  # Example 1: Get all 8 phases for August 2025
+  puts '🌙 All phases for August 2025:'
+  puts '=' * 40
+  phases = MoonPhaseTracker.all_phases_for_month(2025, 8)
+
+  if phases.any?
+    phases.each do |phase|
+      prefix = phase.interpolated ? '~ ' : '  '
+      puts "#{prefix}#{phase}"
+    end
+
+    major_count = phases.count { |p| !p.interpolated }
+    interpolated_count = phases.count(&:interpolated)
+
+    puts ''
+    puts "Total: #{phases.size} phases (#{major_count} major, #{interpolated_count} interpolated)"
+    puts '~ indicates interpolated phases'
+  else
+    puts 'No phases found for this period.'
+  end
+
+  puts ''
+  puts '-' * 50
+  puts ''
+
+  # Example 2: Compare 4 vs 8 phases
+  puts '🔍 Comparison: 4 Major Phases vs 8 Complete Phases'
+  puts '=' * 55
+
+  major_phases = MoonPhaseTracker.phases_for_month(2025, 8)
+  all_phases = MoonPhaseTracker.all_phases_for_month(2025, 8)
+
+  puts "Major phases only (#{major_phases.size}):"
+  major_phases.each { |phase| puts "  #{phase}" }
+
+  puts ''
+  puts "All phases including interpolated (#{all_phases.size}):"
+  all_phases.each do |phase|
+    prefix = phase.interpolated ? '~ ' : '  '
+    puts "#{prefix}#{phase}"
+  end
+
+  puts ''
+  puts '-' * 50
+  puts ''
+
+  # Example 3: Show phase symbols
+  puts '🎭 Phase Symbols Reference'
+  puts '=' * 30
+  MoonPhaseTracker::Phase::PHASE_SYMBOLS.each do |type, symbol|
+    name = type.to_s.split('_').map(&:capitalize).join(' ')
+    puts "#{symbol} #{name}"
+  end
+
+  puts ''
+  puts '-' * 50
+  puts ''
+
+  # Example 4: Get phases from a specific date with 8 phases
+  puts '📅 8 Phases from a specific date (2025-08-01, 2 cycles)'
+  puts '=' * 60
+  date_phases = MoonPhaseTracker.all_phases_from_date('2025-08-01', 2)
+
+  if date_phases.any?
+    date_phases.each do |phase|
+      prefix = phase.interpolated ? '~ ' : '  '
+      puts "#{prefix}#{phase}"
+    end
+
+    major_count = date_phases.count { |p| !p.interpolated }
+    interpolated_count = date_phases.count(&:interpolated)
+
+    puts ''
+    puts "Total: #{date_phases.size} phases over 2 lunar cycles"
+    puts "(#{major_count} major, #{interpolated_count} interpolated)"
+  end
+rescue MoonPhaseTracker::Error => e
+  puts "Error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+  puts 'This example requires an active internet connection to fetch moon phase data.'
+end
+
+puts ''
+puts 'Note: This example uses real astronomical data from the US Naval Observatory.'
+puts 'Interpolated phases (~) are calculated estimates between official phases.'
+puts 'All dates are in ISO 8601 format (YYYY-MM-DD) and times are in UTC.'

data/examples/usage_example.rb

@@ -1,74 +1,74 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require_relative '../lib/moon_phase_tracker'
-
-puts '=== Moon Phase Tracker - Usage Examples =='
-puts
-
-tracker = MoonPhaseTracker::Tracker.new
-
-begin
-  puts '1. Moon phases for August 2025:'
-  puts '-' * 40
-  august_phases = MoonPhaseTracker.phases_for_month(2025, 8)
-  puts tracker.format_phases(august_phases, "#{MoonPhaseTracker::Tracker.month_name(8)} 2025 Phases")
-  puts
-
-  puts '2. All moon phases in 2025 (first 8):'
-  puts '-' * 50
-  year_phases = MoonPhaseTracker.phases_for_year(2025)
-  puts tracker.format_phases(year_phases.first(8), 'First 8 phases of 2025')
-  puts
-
-  puts '3. Next 6 phases starting from 2025-08-01:'
-  puts '-' * 45
-  future_phases = MoonPhaseTracker.phases_from_date('2025-08-01', 6)
-  puts tracker.format_phases(future_phases, 'Upcoming phases')
-  puts
-
-  puts '4. Current month phases:'
-  puts '-' * 25
-  current_phases = tracker.current_month_phases
-  if current_phases.any?
-    puts tracker.format_phases(current_phases, 'Current month phases')
-  else
-    puts 'No phases found for the current month.'
-  end
-  puts
-
-  puts '5. Next moon phase:'
-  puts '-' * 25
-  next_phase = tracker.next_phase
-  if next_phase
-    puts next_phase
-    puts "Details: #{next_phase.to_h}"
-  else
-    puts 'Could not retrieve the next phase.'
-  end
-  puts
-
-  puts '6. Different phase representations:'
-  puts '-' * 42
-  if august_phases.any?
-    phase = august_phases.first
-    puts "String: #{phase}"
-    puts "Hash: #{phase.to_h}"
-    puts "Symbol: #{phase.symbol}"
-    puts "Formatted date: #{phase.formatted_date}"
-    puts "Formatted time: #{phase.formatted_time}"
-  end
-rescue MoonPhaseTracker::NetworkError => e
-  puts "Network error: #{e.message}"
-  puts 'Please check your internet connection.'
-rescue MoonPhaseTracker::APIError => e
-  puts "API error: #{e.message}"
-  puts 'The service may be temporarily unavailable.'
-rescue MoonPhaseTracker::InvalidDateError => e
-  puts "Date error: #{e.message}"
-rescue StandardError => e
-  puts "Unexpected error: #{e.message}"
-end
-
-puts
-puts '=== End of Examples ==='
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/moon_phase_tracker'
+
+puts '=== Moon Phase Tracker - Usage Examples =='
+puts
+
+tracker = MoonPhaseTracker::Tracker.new
+
+begin
+  puts '1. Moon phases for August 2025:'
+  puts '-' * 40
+  august_phases = MoonPhaseTracker.phases_for_month(2025, 8)
+  puts tracker.format_phases(august_phases, "#{MoonPhaseTracker::Tracker.month_name(8)} 2025 Phases")
+  puts
+
+  puts '2. All moon phases in 2025 (first 8):'
+  puts '-' * 50
+  year_phases = MoonPhaseTracker.phases_for_year(2025)
+  puts tracker.format_phases(year_phases.first(8), 'First 8 phases of 2025')
+  puts
+
+  puts '3. Next 6 phases starting from 2025-08-01:'
+  puts '-' * 45
+  future_phases = MoonPhaseTracker.phases_from_date('2025-08-01', 6)
+  puts tracker.format_phases(future_phases, 'Upcoming phases')
+  puts
+
+  puts '4. Current month phases:'
+  puts '-' * 25
+  current_phases = tracker.current_month_phases
+  if current_phases.any?
+    puts tracker.format_phases(current_phases, 'Current month phases')
+  else
+    puts 'No phases found for the current month.'
+  end
+  puts
+
+  puts '5. Next moon phase:'
+  puts '-' * 25
+  next_phase = tracker.next_phase
+  if next_phase
+    puts next_phase
+    puts "Details: #{next_phase.to_h}"
+  else
+    puts 'Could not retrieve the next phase.'
+  end
+  puts
+
+  puts '6. Different phase representations:'
+  puts '-' * 42
+  if august_phases.any?
+    phase = august_phases.first
+    puts "String: #{phase}"
+    puts "Hash: #{phase.to_h}"
+    puts "Symbol: #{phase.symbol}"
+    puts "Formatted date: #{phase.formatted_date}"
+    puts "Formatted time: #{phase.formatted_time}"
+  end
+rescue MoonPhaseTracker::NetworkError => e
+  puts "Network error: #{e.message}"
+  puts 'Please check your internet connection.'
+rescue MoonPhaseTracker::APIError => e
+  puts "API error: #{e.message}"
+  puts 'The service may be temporarily unavailable.'
+rescue MoonPhaseTracker::InvalidDateError => e
+  puts "Date error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+end
+
+puts
+puts '=== End of Examples ==='

data/lib/moon_phase_tracker/lunar_calculator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  class LunarCalculator
+    SYNODIC_MONTH = 29.530588853
+    KNOWN_NEW_MOON_JD = 2451550.26 # Jan 6, 2000 18:14 UTC
+
+    PHASE_BOUNDARIES = [
+      [ 0.0,    "New Moon" ],
+      [ 0.0625, "Waxing Crescent" ],
+      [ 0.1875, "First Quarter" ],
+      [ 0.3125, "Waxing Gibbous" ],
+      [ 0.4375, "Full Moon" ],
+      [ 0.5625, "Waning Gibbous" ],
+      [ 0.6875, "Last Quarter" ],
+      [ 0.8125, "Waning Crescent" ]
+    ].freeze
+
+    def phase_at(date)
+      time = coerce_to_time(date)
+      fraction = cycle_position(time)
+      age = lunar_age(time)
+      illum = illumination_from_fraction(fraction)
+      name = classify_phase(fraction)
+
+      Phase.from_calculation(
+        name: name,
+        date: time.utc.to_date,
+        time: time.utc.strftime("%H:%M"),
+        illumination: illum,
+        lunar_age: age
+      )
+    end
+
+    def illumination(date)
+      fraction = cycle_position(coerce_to_time(date))
+      illumination_from_fraction(fraction)
+    end
+
+    def lunar_age(date)
+      time = coerce_to_time(date)
+      jd = to_julian_date(time)
+      days_since = jd - KNOWN_NEW_MOON_JD
+      days_since % SYNODIC_MONTH
+    end
+
+    def cycle_position(date)
+      time = coerce_to_time(date)
+      jd = to_julian_date(time)
+      days_since = jd - KNOWN_NEW_MOON_JD
+      (days_since % SYNODIC_MONTH) / SYNODIC_MONTH
+    end
+
+    private
+
+    def coerce_to_time(input)
+      case input
+      when Time then input.utc
+      when DateTime then input.to_time.utc
+      when Date then Time.utc(input.year, input.month, input.day, 12)
+      when String then coerce_to_time(Date.parse(input))
+      else raise ArgumentError, "Expected Date, Time, DateTime, or String. Got #{input.class}"
+      end
+    rescue Date::Error => e
+      raise ArgumentError, "Cannot parse date string: #{input.inspect} (#{e.message})"
+    end
+
+    def to_julian_date(time)
+      utc = time.utc
+      y = utc.year
+      m = utc.month
+      d = utc.day + (utc.hour + utc.min / 60.0 + utc.sec / 3600.0) / 24.0
+
+      if m <= 2
+        y -= 1
+        m += 12
+      end
+
+      a = (y / 100).floor
+      b = 2 - a + (a / 4).floor
+
+      (365.25 * (y + 4716)).floor + (30.6001 * (m + 1)).floor + d + b - 1524.5
+    end
+
+    def illumination_from_fraction(fraction)
+      ((1 - Math.cos(2 * Math::PI * fraction)) / 2.0 * 100).round(2)
+    end
+
+    def classify_phase(fraction)
+      PHASE_BOUNDARIES.reverse_each do |threshold, name|
+        return name if fraction >= threshold
+      end
+      PHASE_BOUNDARIES.first.last
+    end
+  end
+end

data/lib/moon_phase_tracker/phase/formatter.rb

@@ -36,7 +36,10 @@ module MoonPhaseTracker
           symbol: phase_attributes[:symbol],
           iso_date: phase_attributes[:date]&.iso8601,
           utc_time: phase_attributes[:time]&.utc&.iso8601,
-          interpolated: phase_attributes[:interpolated]
+          interpolated: phase_attributes[:interpolated],
+          source: phase_attributes[:source],
+          illumination: phase_attributes[:illumination],
+          lunar_age: phase_attributes[:lunar_age]
         }
       end
     end

data/lib/moon_phase_tracker/phase/parser.rb

@@ -18,10 +18,15 @@ module MoonPhaseTracker
         nil
       end
 
-      def self.parse_time(time_string)
+      def self.parse_time(time_string, date = nil)
         return nil unless time_string
 
-        Time.parse("#{time_string} UTC")
+        if date
+          hour, minute = time_string.split(":").map(&:to_i)
+          Time.utc(date.year, date.month, date.day, hour, minute)
+        else
+          Time.parse("#{time_string} UTC")
+        end
       rescue ArgumentError
         nil
       end

data/lib/moon_phase_tracker/phase.rb

@@ -9,14 +9,29 @@ module MoonPhaseTracker
   class Phase
     include Comparable
 
-    attr_reader :name, :date, :time, :phase_type, :interpolated
+    attr_reader :name, :date, :time, :phase_type, :interpolated,
+                :source, :illumination, :lunar_age
 
-    def initialize(phase_data, interpolated: false)
+    def initialize(phase_data, interpolated: false, source: :api, illumination: nil, lunar_age: nil)
       @name = phase_data["phase"]
       @phase_type = Mapper.map_phase_type(@name)
       @date = Parser.build_date(phase_data)
-      @time = Parser.parse_time(phase_data["time"])
+      @time = Parser.parse_time(phase_data["time"], @date)
       @interpolated = interpolated
+      @source = source
+      @illumination = illumination
+      @lunar_age = lunar_age
+    end
+
+    def self.from_calculation(name:, date:, time:, illumination:, lunar_age:)
+      phase_data = {
+        "phase" => name,
+        "year" => date.year,
+        "month" => date.month,
+        "day" => date.day,
+        "time" => time
+      }
+      new(phase_data, source: :calculated, illumination: illumination, lunar_age: lunar_age)
     end
 
     def formatted_date
@@ -42,7 +57,10 @@ module MoonPhaseTracker
         date: @date,
         time: @time,
         symbol: symbol,
-        interpolated: @interpolated
+        interpolated: @interpolated,
+        source: @source,
+        illumination: @illumination,
+        lunar_age: @lunar_age
       }
 
       Formatter.build_hash_representation(phase_attributes)

data/lib/moon_phase_tracker/phase_calculator/cycle_estimator.rb

@@ -15,7 +15,7 @@ module MoonPhaseTracker
         estimated_date = calculate_estimated_date(last_phase)
         phase_data = build_estimated_phase_data(estimated_date, last_phase)
 
-        Phase.new(phase_data)
+        Phase.new(phase_data, source: :interpolated)
       rescue Date::Error, ArgumentError => e
         warn "Failed to estimate next cycle phase: #{e.class}"
         nil

data/lib/moon_phase_tracker/phase_calculator/phase_interpolator.rb

@@ -60,7 +60,7 @@ module MoonPhaseTracker
         return nil unless intermediate_datetime
 
         phase_data = build_phase_data(intermediate_datetime, config[:name])
-        Phase.new(phase_data, interpolated: true)
+        Phase.new(phase_data, interpolated: true, source: :interpolated)
       rescue Date::Error, ArgumentError => e
         warn "Failed to create intermediate phase: #{e.class}"
         nil

data/lib/moon_phase_tracker/tracker.rb

@@ -43,6 +43,20 @@ module MoonPhaseTracker
       phases_from_date(Date.today, 1).first
     end
 
+    def phase_at(date)
+      parsed = @date_parser.parse(date)
+      calculator.phase_at(parsed)
+    end
+
+    def illumination(date)
+      parsed = @date_parser.parse(date)
+      calculator.illumination(parsed)
+    end
+
+    def current_phase
+      calculator.phase_at(Time.now.utc)
+    end
+
     def current_month_phases
       today = Date.today
       phases_for_month(today.year, today.month)
@@ -77,6 +91,10 @@ module MoonPhaseTracker
 
     private
 
+    def calculator
+      @calculator ||= LunarCalculator.new
+    end
+
     MONTH_NAMES = %w[
       January February March April May June
       July August September October November December

data/lib/moon_phase_tracker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MoonPhaseTracker
-  VERSION = "1.3.2"
+  VERSION = "1.4.0"
 end

data/lib/moon_phase_tracker.rb

@@ -5,6 +5,7 @@ require_relative "moon_phase_tracker/rate_limiter"
 require_relative "moon_phase_tracker/client"
 require_relative "moon_phase_tracker/phase"
 require_relative "moon_phase_tracker/phase_calculator"
+require_relative "moon_phase_tracker/lunar_calculator"
 require_relative "moon_phase_tracker/tracker"
 
 module MoonPhaseTracker
@@ -39,4 +40,20 @@ module MoonPhaseTracker
   def self.all_phases_from_date(date, num_cycles = 3)
     Tracker.new.all_phases_from_date(date, num_cycles)
   end
+
+  def self.calculator
+    @calculator ||= LunarCalculator.new
+  end
+
+  def self.phase_at(date)
+    calculator.phase_at(date)
+  end
+
+  def self.illumination(date)
+    calculator.illumination(date)
+  end
+
+  def self.current_phase
+    calculator.phase_at(Time.now.utc)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moon_phase_tracker
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0
 platform: ruby
 authors:
 - Daniel K Lima
@@ -56,6 +56,7 @@ files:
 - examples/usage_example.rb
 - lib/moon_phase_tracker.rb
 - lib/moon_phase_tracker/client.rb
+- lib/moon_phase_tracker/lunar_calculator.rb
 - lib/moon_phase_tracker/phase.rb
 - lib/moon_phase_tracker/phase/comparator.rb
 - lib/moon_phase_tracker/phase/formatter.rb