toilet_tracker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2cd32c62afad4d76b2c46dc4747fd6140c458dd7d5d7ee63d1d4c562761087f2
+  data.tar.gz: dc38bc38cd7f5610a6fde62c861e9e38d0c46908f2703098f775ffad8f32ae71
+SHA512:
+  metadata.gz: 7f347d353402c1b4c3189ac6fabc9098b03c32caf6c04d729e17320e07693778ff81c698540f47923d24f585f189b02bdb913cc940f89dae98cb3d475c312da6
+  data.tar.gz: 7ff87b8075a25a879a96bcdb6c903e03d09419c45e1285b669a48f9184f6995852be152e1cdf98c46c08933e37515898d21818b29fc24dc5d3c3f4dc066ef1e1

data/.overcommit.yml

@@ -0,0 +1,31 @@
+# Use this file to configure the Overcommit hooks you wish to use in your
+# repository. Hooks are run in the order in which they are listed.
+
+PreCommit:
+  RuboCop:
+    enabled: true
+    on_warn: fail # Treat all warnings as failures
+
+  BundleCheck:
+    enabled: true
+
+  TrailingWhitespace:
+    enabled: true
+
+  YamlSyntax:
+    enabled: true
+
+CommitMsg:
+  CapitalizedSubject:
+    enabled: true
+
+  EmptyMessage:
+    enabled: true
+
+  TrailingPeriod:
+    enabled: true
+
+PrePush:
+  RSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'rspec']

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+
+# Disable metrics cops for now
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+# Disable documentation requirement
+Style/Documentation:
+  Enabled: false
+
+# Increase line length limit or disable
+Layout/LineLength:
+  Max: 200
+
+# Disable remaining Lint cops that need manual fixes
+Lint/DuplicateBranch:
+  Enabled: false
+
+Lint/UnreachableLoop:
+  Enabled: false

data/.standard.yml

@@ -0,0 +1,2 @@
+ruby_version: 3.4
+fix: true

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-06-26
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 NetherSoul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/PARSING_SPEC.md

@@ -0,0 +1,361 @@
+# ToiletTracker Parsing Specification
+
+## Overview
+
+ToiletTracker is a Ruby gem that parses WhatsApp message exports to track toilet-related events using emoji-based commands. This specification defines all supported message formats, parsing behaviors, and expected outcomes.
+
+## Core Concepts
+
+### Message Structure
+All WhatsApp messages follow this format:
+```
+[DD/MM/YY, HH:MM:SS] Sender: Content
+```
+
+### Command Types
+- **🚽 (Settings)**: Configure timezone shifts and preferences
+- **💩 (Events)**: Log toilet events with timestamps and timezone handling
+
+### Shift Types
+- **Functional Shifts**: Applied to event timestamps (patterns 1, 2, 5)
+- **Decorative Shifts**: For statistics only, do not affect timestamps (patterns 7, 9)
+
+## Supported Parsing Patterns
+
+### WhatsApp Message Format
+**Pattern**: `\[(?<day>\d{2})/(?<month>\d{2})/(?<year>\d{2}),\s*(?<time>\d{2}:\d{2}:\d{2})\]\s*(?<sender>[^:]+):\s*(?<content>.+?)(?:\s*‎<This message was edited>)?$`
+
+**Examples**:
+- `[01/01/25, 12:00:00] Alice: 💩`
+- `[25/12/24, 23:59:59] Bob: 🚽 +2`
+- `[15/06/25, 14:30:15] Charlie: 💩 +1 2025-06-15 12:00:00`
+
+**Behavior**:
+- Extracts day, month, year (2-digit), time, sender, content
+- Handles edited messages with suffix `‎<This message was edited>`
+- Year is converted to 20XX format (25 → 2025)
+
+### 1. Shift Set (Functional)
+**Pattern**: `🚽\s*([+-]?\d+)$`
+**Type**: `shift_set`
+
+**Examples**:
+- `🚽 +2` → Set +2 hour shift effective immediately
+- `🚽 -1` → Set -1 hour shift effective immediately
+- `🚽+3` → Set +3 hour shift (no space required)
+- `🚽 0` → Reset to no shift
+
+**Behavior**:
+- Sets timezone shift for the user
+- Effective time is the message timestamp
+- Applies to all future events until changed
+- Validates shift is within configured max_shift_hours
+
+### 2. Shift Set at Time (Functional)
+**Pattern**: `🚽\s*([+-]?\d+)\s+(.+)$`
+**Type**: `shift_set_at_time`
+
+**Examples**:
+- `🚽 +2 2025-01-15 14:30` → Set +2 shift effective from Jan 15, 14:30
+- `🚽 -1 2024/12/25 10:00:00` → Set -1 shift effective from Dec 25, 10:00
+
+**Behavior**:
+- Sets timezone shift with retroactive effective time
+- If effective_time < message_timestamp, applies retroactively
+- Affects past events after the effective time
+- Status becomes `:alert` if time difference > 30 days
+
+### 3. Timezone Set
+**Pattern**: `🚽\s*([A-Za-z_/][A-Za-z0-9_/+-]*)$`
+**Type**: `timezone_set`
+
+**Examples**:
+- `🚽 Europe/Rome` → Set timezone to Europe/Rome
+- `🚽 PST` → Set timezone to PST
+- `🚽 UTC` → Set timezone to UTC
+
+**Behavior**:
+- Converts timezone name to appropriate shift
+- Calculates shift relative to default_timezone
+- Creates a ToiletShiftResult with calculated shift
+- Validates timezone exists in ActiveSupport::TimeZone
+
+### 4. Event Now
+**Pattern**: `💩$`
+**Type**: `event_now`
+
+**Examples**:
+- `💩` → Log event at message timestamp
+
+**Behavior**:
+- Uses message timestamp as event time
+- Applies user's current active shift
+- Most common usage pattern
+
+### 5. Event Now Shifted (Functional)
+**Pattern**: `💩\s*([+-]?\d+)$`
+**Type**: `event_now_shifted`
+
+**Examples**:
+- `💩 +2` → Log event at message time + 2 hours
+- `💩 -1` → Log event at message time - 1 hour
+
+**Behavior**:
+- Overrides user's active shift for this event only
+- Shift is applied to message timestamp
+- Validates shift is within max_shift_hours
+
+### 6. Event at Time
+**Pattern**: `💩\s+(\d{4}[-/]\d{1,2}[-/]\d{1,2}\s+\d{1,2}:\d{1,2}(?::\d{1,2})?)$`
+**Type**: `event_at_time`
+
+**Examples**:
+- `💩 2025-01-15 14:30` → Log event at specific past time
+- `💩 2024/12/25 10:00:00` → Supports both - and / separators
+- `💩 2025-1-1 9:30` → Single digit months/days allowed
+
+**Behavior**:
+- Uses explicit timestamp, no shift applied
+- Status becomes `:alert` if |event_time - message_time| > 30 days
+- Records user's active shift for statistics only
+
+### 7. Event at Time Shifted (Decorative)
+**Pattern**: `💩\s*([+-]?\d+)\s+(\d{4}[-/]\d{1,2}[-/]\d{1,2}\s+\d{1,2}:\d{1,2}(?::\d{1,2})?)$`
+**Type**: `event_at_time_shifted`
+
+**Examples**:
+- `💩 +2 2025-01-15 14:30` → Log event at 14:30 (shift is decorative)
+- `💩 -1 2024/12/25 10:00:00` → Log event at 10:00 (shift ignored)
+
+**Behavior**:
+- **CRITICAL**: Shift is decorative only, does not affect event_time
+- Uses explicit timestamp as-is
+- Shift is stored for statistics/display purposes
+- Status determination same as event_at_time
+
+### 8. Event in Timezone
+**Pattern**: `💩\s*([A-Za-z_/][A-Za-z0-9_/+-]*)\s*$`
+**Type**: `event_in_timezone`
+
+**Examples**:
+- `💩 PST` → Log event at message time converted to PST
+- `💩 Europe/Rome` → Log event at message time in Rome timezone
+
+**Behavior**:
+- Calculates shift from default_timezone to specified timezone
+- Applies calculated shift to message timestamp
+- Validates timezone exists
+
+### 9. Event in Timezone at Time (Decorative)
+**Pattern**: `💩\s*([A-Za-z_/][A-Za-z0-9_/+-]*)\s+(\d{4}[-/]\d{1,2}[-/]\d{1,2}\s+\d{1,2}:\d{1,2}(?::\d{1,2})?)$`
+**Type**: `event_in_timezone_at_time`
+
+**Examples**:
+- `💩 EST 2025-01-15 14:30` → Log event at 14:30 (timezone decorative)
+- `💩 Europe/Rome 2024/12/25 10:00` → Log event at 10:00 (timezone ignored)
+
+**Behavior**:
+- **CRITICAL**: Timezone is decorative only, does not affect event_time
+- Uses explicit timestamp as-is
+- Timezone is stored for statistics/display purposes
+- Status determination same as event_at_time
+
+## Date Format Support
+
+Supported input formats:
+1. `YYYY-MM-DD HH:MM:SS` (e.g., `2025-01-15 14:30:00`)
+2. `YYYY-MM-DD HH:MM` (e.g., `2025-01-15 14:30`)
+3. `YYYY/MM/DD HH:MM:SS` (e.g., `2025/01/15 14:30:00`)
+4. `YYYY/MM/DD HH:MM` (e.g., `2025/01/15 14:30`)
+
+**Parsing behavior**:
+- Try formats in order, use first successful parse
+- Fallback to ActiveSupport::TimeZone.parse
+- Parse in context of default_timezone
+- Single-digit months/days are accepted
+
+## Status Determination
+
+### Success Status (`:ok`)
+- Valid message format
+- Valid shift/timezone
+- Time difference ≤ 30 days
+
+### Alert Status (`:alert`)
+- Valid parsing but suspicious timing
+- |event_time - message_time| > 30 days
+- User should verify the timestamp
+
+### Error Status (`:error`)
+- Invalid message format
+- Invalid shift (exceeds max_shift_hours)
+- Invalid timezone
+- Invalid datetime format
+- Parsing exceptions
+
+## Error Handling
+
+### Invalid Message Format
+```ruby
+Core::InvalidMessageFormat.new(content, expected_format)
+```
+
+### Invalid Shift
+```ruby
+Core::InvalidShift.new(shift_string)
+# Triggered when:
+# - Shift is not a valid integer
+# - |shift| > max_shift_hours
+```
+
+### Invalid DateTime
+```ruby
+Core::InvalidDateTime.new(datetime_string)
+# Triggered when:
+# - None of the date formats match
+# - ActiveSupport can't parse the string
+```
+
+### Invalid Timezone
+```ruby
+Core::InvalidTimezone.new(timezone_string)
+# Triggered when:
+# - Timezone not found in ActiveSupport::TimeZone
+```
+
+## Configuration
+
+### Default Settings
+```ruby
+default_timezone: "UTC"
+max_shift_hours: 12
+```
+
+### Validation Rules
+- Shifts must be integers between -max_shift_hours and +max_shift_hours
+- Timezones must exist in ActiveSupport::TimeZone
+- Message timestamps must parse successfully
+
+## Processing Flow
+
+1. **Parse WhatsApp Format**: Extract timestamp, sender, content
+2. **Pattern Matching**: Try patterns in configuration order
+3. **Type-Specific Parsing**: Handle based on matched pattern
+4. **Validation**: Check shifts, timezones, timestamps
+5. **Status Determination**: Set :ok, :alert, or :error
+6. **Result Creation**: Return appropriate result object
+
+## Retroactive Shift Application
+
+When timezone shifts are set retroactively:
+1. Process all messages in chronological order
+2. Track shift changes with effective times
+3. Apply correct shift to event_now events based on their timestamp
+4. Only affects functional shifts (patterns 1, 2, 5)
+5. Decorative shifts (patterns 7, 9) are never modified
+
+## Expected Result Objects
+
+### ToiletShiftResult
+```ruby
+{
+  type: :shift_set | :shift_set_at_time | :timezone_set,
+  status: :ok | :alert | :error,
+  message: Core::Message,
+  shift: Integer,
+  effective_time: Time,
+  error_details: String | nil
+}
+```
+
+### PoopEventResult
+```ruby
+{
+  type: :event_now | :event_now_shifted | :event_at_time | :event_at_time_shifted | 
+        :event_in_timezone | :event_in_timezone_at_time,
+  status: :ok | :alert | :error,
+  message: Core::Message,
+  shift: Integer | nil,
+  poop_time: Time,
+  timezone: String | nil,
+  error_details: String | nil
+}
+```
+
+### ParseResult (Errors)
+```ruby
+{
+  type: :parse_error,
+  status: :error,
+  message: nil,
+  error_details: String
+}
+```
+
+## Test Requirements
+
+### Unit Tests
+- Each pattern should be tested individually
+- Edge cases for each pattern
+- Invalid input handling
+- Configuration boundary testing
+
+### Integration Tests
+- Multi-message scenarios with retroactive shifts
+- Complex timezone interactions
+- Large dataset performance
+- CLI functionality
+
+### Performance Benchmarks
+- Process 1000+ message files efficiently
+- Memory usage should remain reasonable
+- Regex compilation should be optimized
+
+## CLI Features
+
+### Commands
+- `parse FILE` - Parse WhatsApp messages from file
+- `interactive` - Interactive mode with TTY::Prompt
+- `stats FILE` - Show parsing statistics
+- `version` - Show version information
+
+### Output Formats
+- **table** - Formatted table with dynamic column widths
+- **json** - Pretty-printed JSON
+- **csv** - CSV format for spreadsheet import
+
+### Statistics
+- Total chat lines vs toilet-tracking messages
+- Success rate for toilet-tracking parsing
+- Message type breakdown
+- Top senders
+- Common errors
+
+## Examples and Edge Cases
+
+### Valid Examples
+```
+[01/01/25, 10:00:00] Alice: 🚽 +2
+[01/01/25, 12:00:00] Alice: 💩
+[01/01/25, 14:00:00] Alice: 💩 +1 2025-01-01 13:30:00
+[02/01/25, 09:00:00] Bob: 🚽 Europe/Rome
+[02/01/25, 15:00:00] Bob: 💩 PST 2025-01-02 12:00:00
+```
+
+### Invalid Examples
+```
+[01/01/25, 10:00:00] Alice: 🚽 +25        # Exceeds max_shift_hours
+[01/01/25, 12:00:00] Alice: 💩 invalid    # Invalid shift format
+[01/01/25, 14:00:00] Alice: 💩 2025-13-01 # Invalid date
+[02/01/25, 09:00:00] Bob: 🚽 Mars/Phobos  # Invalid timezone
+```
+
+### Edge Cases
+```
+[01/01/25, 10:00:00] Alice: 🚽+0          # No space before shift
+[01/01/25, 12:00:00] Alice: 💩            # Simple live event
+[01/01/25, 14:00:00] Alice: 💩 2025-1-1 9:30  # Single digits
+[02/01/25, 09:00:00] Bob: Some regular message  # Ignored
+```
+
+This specification serves as the authoritative reference for implementing and testing the ToiletTracker parsing functionality.