toilet_tracker 0.1.0

data/README.md

@@ -0,0 +1,253 @@
+# ToiletTracker
+
+A modern Ruby gem for parsing WhatsApp messages containing toilet tracking data using emoji-based commands. Built with clean architecture principles and comprehensive timezone support.
+
+## Features
+
+- 🚽 **Settings**: Set timezone shifts and preferences
+- 💩 **Event Tracking**: Log events with automatic timezone adjustments
+- ⏰ **Timezone Support**: Handle multiple timezones and retroactive shifts
+- 📊 **Multiple Output Formats**: JSON, CSV, and formatted tables
+- 🔧 **Thor CLI**: Interactive command-line interface with TTY::Prompt
+- 🧪 **Comprehensive Testing**: 77 tests with 96%+ coverage
+- 🏗️ **Clean Architecture**: Modular design with clear separation of concerns
+- 📋 **Statistics**: Detailed parsing statistics and error reporting
+
+## Requirements
+
+- **Ruby 3.4+** - Uses modern Ruby features for optimal performance
+- **StandardRB** - Zero-configuration linting and formatting
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'toilet_tracker'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install toilet_tracker
+```
+
+## Usage
+
+### Command Line Interface
+
+Process WhatsApp export files:
+
+```bash
+# Basic usage
+toilet_tracker parse whatsapp_export.txt
+
+# Parse WhatsApp zip exports (automatically extracts _chat.txt)
+toilet_tracker parse whatsapp_export.zip
+
+# JSON output
+toilet_tracker parse --format json messages.txt
+
+# Custom timezone
+toilet_tracker parse --timezone "Europe/Rome" messages.txt
+
+# Show statistics
+toilet_tracker stats messages.txt
+
+# Interactive mode
+toilet_tracker interactive
+
+# Show version
+toilet_tracker version
+```
+
+### Ruby API
+
+```ruby
+require 'toilet_tracker'
+
+# Parse individual lines
+result = ToiletTracker.parse_line("[01/01/25, 12:00:00] Alice: 💩")
+puts result.type  # => :event_now
+
+# Parse multiple lines
+lines = [
+  "[01/01/25, 10:00:00] Alice: 🚽 +2",
+  "[01/01/25, 12:00:00] Alice: 💩"
+]
+results = ToiletTracker.parse_lines(lines)
+
+# Configure settings
+ToiletTracker.configure do |config|
+  config.default_timezone = "Europe/Rome"
+  config.max_shift_hours = 12
+end
+```
+
+### Supported Message Formats
+
+#### 🚽 Settings (Functional - Affect Timestamps)
+- `🚽 +2` - Set timezone shift to +2 hours (immediate)
+- `🚽 -1` - Set timezone shift to -1 hour (immediate)
+- `🚽 +1 2025-01-15 14:30` - Set shift effective from specific time (retroactive)
+- `🚽 Europe/Rome` - Set timezone by name
+- `🚽 PST` - Set timezone by abbreviation
+
+#### 💩 Events
+
+**Functional Shifts (Affect Actual Times):**
+- `💩` - Log live event with current active shift
+- `💩 +1` - Log live event with +1 hour shift override
+- `💩 PST` - Log live event converted to PST timezone
+
+**Fixed Times (No Shift Applied):**
+- `💩 2025-01-15 14:30` - Log event at exact time specified
+
+**Decorative Data (For Statistics Only):**
+- `💩 +2 2025-01-15 14:30` - Log event at 14:30 exactly, +2 shift stored for display
+- `💩 EST 2025-01-15 14:30` - Log event at 14:30 exactly, EST timezone stored for display
+
+> **Important**: In decorative patterns, the shift/timezone is stored for statistics but does NOT modify the actual poop timestamp.
+
+### Configuration Options
+
+```ruby
+ToiletTracker.configure do |config|
+  # Default timezone for parsing timestamps
+  config.default_timezone = "UTC"
+
+  # Maximum allowed shift hours
+  config.max_shift_hours = 12
+
+  # Custom message patterns (advanced)
+  config.message_patterns[:custom] = /custom_pattern/
+
+  # Supported date formats
+  config.date_formats = ["%Y-%m-%d %H:%M:%S", "%Y/%m/%d %H:%M"]
+end
+```
+
+## Examples
+
+### Basic Usage Scenarios
+
+#### Setting Up Timezone Shifts
+```
+[15/01/25, 10:00:00] Alice: 🚽 +2
+[15/01/25, 12:00:00] Alice: 💩
+# Result: Event logged at 14:00 (12:00 + 2 hours)
+```
+
+#### Retroactive Timezone Adjustments  
+```
+[15/01/25, 10:00:00] Alice: 💩
+[15/01/25, 14:00:00] Alice: 🚽 +3 2025-01-15 09:00:00
+# Result: First event adjusted to 13:00 (10:00 + 3 hours)
+```
+
+#### Decorative vs Functional Shifts
+```
+# Functional: Affects timestamp
+[15/01/25, 12:00:00] Alice: 💩 +2
+# Result: Event at 14:00 (12:00 + 2 hours)
+
+# Decorative: Only for statistics  
+[15/01/25, 12:00:00] Alice: 💩 +2 2025-01-15 10:00:00
+# Result: Event at exactly 10:00, +2 stored for display
+```
+
+#### Complex Multi-User Scenario
+```
+[15/01/25, 09:00:00] Alice: 🚽 +2
+[15/01/25, 09:30:00] Bob: 🚽 Europe/Rome  
+[15/01/25, 10:00:00] Alice: 💩
+[15/01/25, 10:30:00] Bob: 💩
+[15/01/25, 11:00:00] Alice: 💩 +1
+[15/01/25, 11:30:00] Bob: 💩 EST 2025-01-15 08:00:00
+```
+
+Results:
+- Alice's first event: 12:00 (10:00 + 2 hours active shift)
+- Bob's first event: ~11:30 (10:30 converted from UTC to Rome time)
+- Alice's override event: 12:00 (11:00 + 1 hour override)
+- Bob's decorative event: exactly 08:00 (EST is decorative only)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run the following commands:
+
+```bash
+# Run tests
+bundle exec rspec
+
+# Check code style (StandardRB)
+bundle exec standardrb
+
+# Auto-fix style issues
+bundle exec standardrb --fix
+
+# Install gem locally
+bundle exec rake install
+```
+
+### Code Quality
+
+This project uses **StandardRB** for zero-configuration Ruby linting and formatting. StandardRB eliminates style debates by providing an opinionated, unconfigurable set of rules.
+
+Key principles:
+- **Ruby 3.4+ features** - Modern syntax and performance optimizations
+- **KISS principle** - Keep code simple and readable
+- **Test-driven development** - Comprehensive RSpec test suite
+- **Clean architecture** - Clear separation of concerns
+
+### Creating a Release
+
+To release a new version:
+
+1. **Update the version** in `lib/toilet_tracker/version.rb`:
+   ```ruby
+   module ToiletTracker
+     VERSION = "1.2.3"
+   end
+   ```
+
+2. **Update CHANGELOG.md** with release notes (optional but recommended)
+
+3. **Commit your changes**:
+   ```bash
+   git add -A
+   git commit -m "Bump version to 1.2.3"
+   ```
+
+4. **Create and push a git tag**:
+   ```bash
+   git tag v1.2.3
+   git push origin main --tags
+   ```
+
+5. **Automated Release Process**: The GitHub Actions workflow will automatically:
+   - Run tests and linting to validate the release
+   - Build the gem
+   - Publish to RubyGems.org (requires `RUBYGEMS_API_KEY` secret)
+   - Create a GitHub release with auto-generated changelog
+   - Upload the gem file as a release asset
+
+**Note**: Ensure the `RUBYGEMS_API_KEY` secret is configured in your GitHub repository settings for automatic publishing to work.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/toilet_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/[USERNAME]/toilet_tracker/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ToiletTracker project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/toilet_tracker/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/STYLE_GUIDE.md

@@ -0,0 +1,377 @@
+# ToiletTracker Ruby Style Guide
+
+## Overview
+
+This project follows Ruby 3.4 best practices with StandardRB for consistent code formatting. The guide emphasizes KISS (Keep It Simple, Stupid) principles and modern Ruby idioms.
+
+## Ruby Version & Features
+
+**Target Ruby Version**: 3.4+
+
+### Ruby 3.4 Modern Features
+
+#### Use `it` for Single Block Parameters
+```ruby
+# ✅ Preferred (Ruby 3.4+)
+[1, 2, 3].map { it * 2 }
+results.filter { it.success? }
+
+# ❌ Avoid (outdated)
+[1, 2, 3].map { _1 * 2 }
+results.filter { _1.success? }
+```
+
+#### Frozen Strings by Default
+```ruby
+# ✅ Remove these comments (redundant in Ruby 3.4)
+# frozen_string_literal: true
+
+# Ruby 3.4 makes strings frozen by default
+```
+
+#### Modern Hash Syntax
+```ruby
+# ✅ Preferred - Symbol keys without fat arrow
+user_data = { name: "Alice", age: 30, active: true }
+
+# ✅ Other keys with spaces around fat arrow
+mixed_data = { "user-id" => 123, :name => "Alice" }
+
+# ❌ Avoid - Old symbol syntax
+user_data = { :name => "Alice", :age => 30 }
+```
+
+## Code Style (StandardRB)
+
+### Linting & Formatting
+```bash
+# Check code style
+bundle exec standardrb
+
+# Auto-fix issues
+bundle exec standardrb --fix
+```
+
+### Configuration
+StandardRB is **unconfigurable by design** to eliminate style debates. The `.standard.yml` file contains:
+```yaml
+ruby_version: 3.4
+fix: true
+ignore:
+  - 'vendor/**/*'
+```
+
+### Event Naming Convention
+We use clear, unified event names:
+- **Settings**: `shift_set`, `shift_set_at_time`, `timezone_set`
+- **Events**: `event_now`, `event_now_shifted`, `event_at_time`, `event_at_time_shifted`, `event_in_timezone`, `event_in_timezone_at_time`
+
+This naming is consistent, self-explanatory, and avoids domain-specific jargon.
+
+## KISS Principles Applied
+
+### 1. Simple Method Design
+```ruby
+# ✅ Good - Single responsibility, clear intent
+def parse_shift(shift_string)
+  return nil if shift_string.nil? || shift_string.empty?
+
+  shift = Integer(shift_string)
+  validate_shift_range(shift)
+  shift
+rescue ArgumentError
+  raise Core::InvalidShift, shift_string
+end
+
+# ❌ Avoid - Complex, multiple responsibilities
+def parse_shift_and_maybe_validate_and_log(shift_string, should_log = false)
+  # ... complex logic mixing concerns
+end
+```
+
+### 2. Clear Variable Naming
+```ruby
+# ✅ Self-documenting names
+effective_time = result.effective_time || result.message.timestamp
+user_timezone_shift = shift_service.get_active_shift(user, timestamp)
+
+# ❌ Unclear abbreviations
+eff_t = result.eff_t || result.msg.ts
+usr_tz_sh = shift_svc.get_act_sh(usr, ts)
+```
+
+### 3. Prefer Simple Data Structures
+```ruby
+# ✅ Use Ruby 3+ Data classes for immutable structs
+ParseResult = Data.define(:type, :status, :message, :error_details)
+
+# ✅ Simple hash for configuration
+config = {
+  default_timezone: "UTC",
+  max_shift_hours: 12
+}
+
+# ❌ Avoid over-engineered class hierarchies for simple data
+```
+
+### 4. Error Handling
+```ruby
+# ✅ Explicit error types with clear messages
+def parse_datetime(datetime_string)
+  # Try each format
+  config.date_formats.each do |format|
+    return parse_with_format(datetime_string, format)
+  rescue ArgumentError
+    next
+  end
+
+  raise Core::InvalidDateTime, "Unable to parse: #{datetime_string}"
+end
+
+# ❌ Generic error swallowing
+def parse_datetime(datetime_string)
+  begin
+    # ... complex parsing
+  rescue => e
+    nil # Lost error context
+  end
+end
+```
+
+## Method Organization
+
+### Size Limits
+- **Methods**: Max 15 lines (StandardRB default)
+- **Classes**: Max 100 lines for clarity
+- **Files**: Single responsibility per file
+
+### Method Structure
+```ruby
+def process_toilet_shift(result)
+  user = result.message.sender
+  effective_time = determine_effective_time(result)
+  
+  if retroactive_shift?(result)
+    apply_retroactive_shift(user, result.shift, effective_time)
+  else
+    apply_immediate_shift(user, result.shift, effective_time)
+  end
+
+  result
+rescue Core::Error => e
+  create_error_result(result, e)
+end
+
+private
+
+def retroactive_shift?(result)
+  result.effective_time && result.effective_time < result.message.timestamp
+end
+```
+
+## Testing Style
+
+### RSpec Conventions
+```ruby
+# ✅ Clear, descriptive test names
+RSpec.describe MessageParser do
+  describe "#parse" do
+    context "when parsing toilet shift commands" do
+      it "creates ToiletShiftResult for valid shift" do
+        message = build_message("🚽 +2")
+        result = parser.parse(message)
+        
+        expect(result).to be_success
+        expect(result.value.shift).to eq(2)
+      end
+    end
+  end
+end
+
+# ✅ Use subject and let for clarity
+subject(:parser) { described_class.new }
+let(:message) { build_message(content) }
+let(:content) { "🚽 +2" }
+```
+
+### Test Organization
+- One test file per class/module
+- Group related tests with `describe` and `context`
+- Use `let` for test data setup
+- Keep tests focused on single behavior
+
+## Performance Considerations
+
+### Array and Hash Operations
+```ruby
+# ✅ Leverage Ruby 3.4 performance improvements
+large_array.each { process_item(it) }  # 7x faster in Ruby 3.4
+results.select { it.success? }         # Optimized in Ruby 3.4
+
+# ✅ Use appropriate collection methods
+timezone_map = timezones.to_h { [it.name, it.offset] }
+valid_results = results.filter_map { it if it.valid? }
+```
+
+### Regex Compilation
+```ruby
+# ✅ Compile expensive regexes once
+class Configuration
+  def whatsapp_message_pattern
+    @whatsapp_message_pattern ||= compile_whatsapp_pattern
+  end
+  
+  private
+  
+  def compile_whatsapp_pattern
+    # Complex regex compilation
+  end
+end
+```
+
+## Documentation
+
+### Inline Comments
+```ruby
+# ✅ Explain business logic, not obvious code
+def determine_status(event_time, message_time)
+  return :error unless event_time && message_time
+
+  # Alert if the time difference is suspiciously large (>30 days)
+  # This catches potential data entry errors
+  time_diff = (message_time - event_time).abs
+  time_diff > 30.days ? :alert : :ok
+end
+
+# ❌ Don't comment obvious code
+# Set user to the message sender
+user = message.sender
+```
+
+### Method Documentation
+```ruby
+# Document complex public APIs only
+def analyze_lines(lines)
+  # Parse all lines first
+  results = lines.filter_map { analyze_line(it) }
+
+  # Apply retroactive shifts to adjust timestamps
+  apply_retroactive_shifts_to_results(results)
+end
+```
+
+## File Organization
+
+### Directory Structure
+```
+lib/
+├── toilet_tracker.rb              # Main entry point & API
+├── toilet_tracker/
+│   ├── version.rb                 # Gem version
+│   ├── configuration.rb           # Config & patterns
+│   ├── core/                      # Domain objects
+│   │   ├── errors.rb              # Custom exceptions
+│   │   ├── message.rb             # Message value object
+│   │   ├── result.rb              # Result monad
+│   │   └── parse_result.rb        # Data classes for results
+│   ├── parsers/                   # Parsing logic
+│   │   ├── base_parser.rb         # Shared behavior
+│   │   ├── whatsapp_parser.rb     # WhatsApp format
+│   │   └── message_parser.rb      # Content parsing
+│   └── services/                  # Business logic
+│       ├── analysis_service.rb    # Main orchestrator
+│       ├── shift_service.rb       # Timezone shifts
+│       └── timezone_service.rb    # Timezone handling
+
+exe/
+└── toilet_tracker                 # Thor CLI executable
+
+spec/
+├── spec_helper.rb                 # Test configuration
+├── toilet_tracker_spec.rb         # Main API tests
+└── toilet_tracker/                # Organized test structure
+    ├── core/
+    ├── parsers/
+    └── services/
+```
+
+### Naming Conventions
+- **Files**: `snake_case.rb`
+- **Classes/Modules**: `PascalCase`
+- **Methods/Variables**: `snake_case`
+- **Constants**: `SCREAMING_SNAKE_CASE`
+
+## Dependencies
+
+### Runtime Dependencies
+```ruby
+# Keep minimal, prefer standard library
+gem "activesupport", "~> 8.0"   # For TimeZone support only
+gem "thor", "~> 1.3"            # CLI framework
+gem "tty-prompt", "~> 0.23"     # Interactive CLI
+gem "csv", "~> 3.3"             # Ruby 3.4 compatibility
+```
+
+### Development Dependencies
+```ruby
+gem "standard"       # Zero-config linting
+gem "rspec"          # Testing framework
+gem "simplecov"      # Code coverage
+gem "rake"           # Task runner
+```
+
+## Anti-Patterns to Avoid
+
+### ❌ Over-Engineering
+```ruby
+# Don't create complex inheritance hierarchies for simple data
+class BaseResult < AbstractResult
+  include ResultBehaviors
+  extend ResultClassMethods
+  # ... 50 lines of abstract methods
+end
+```
+
+### ❌ Magic Numbers
+```ruby
+# Don't use unexplained constants
+time_diff > 2592000 ? :alert : :ok  # What is 2592000?
+
+# ✅ Use named constants
+time_diff > 30.days ? :alert : :ok
+```
+
+### ❌ Method Chaining Abuse
+```ruby
+# Don't create unreadable chains
+result.message.content.strip.downcase.gsub(/\s+/, " ").split.first&.upcase
+
+# ✅ Break into readable steps
+content = result.message.content
+normalized_content = normalize_whitespace(content)
+first_word = normalized_content.split.first
+first_word&.upcase
+```
+
+## Tools Integration
+
+### Git Hooks (Overcommit)
+```yaml
+# .overcommit.yml
+PreCommit:
+  StandardRb:
+    enabled: true
+    command: ['bundle', 'exec', 'standardrb']
+```
+
+### CI/CD
+```yaml
+# GitHub Actions
+- name: Run StandardRB
+  run: bundle exec standardrb
+
+- name: Run Tests  
+  run: bundle exec rspec
+```
+
+This style guide ensures ToiletTracker follows modern Ruby best practices while maintaining simplicity and readability.