Markdown TimeSheet

A command-line tool for parsing time tracking data from markdown files and generating daily, weekly, and monthly summaries with configurable weekly hour targets and shortage tracking.

Overview

This tool parses markdown files containing time entries in natural language format and calculates total hours worked per day, week, and month. It's designed to work with simple markdown files where you log your work start/stop times, direct work time entries, and holidays. The tool can track weekly hour shortages against configurable targets.

Features

• Natural Language Parsing: Recognizes various formats like "Start work 9:00", "Started working at 8:30", "Stop work 17:30"
• Case Insensitive: Works with different capitalizations
• Multiple Entries: Supports multiple work sessions per day (e.g., breaks for lunch)
• Overnight Support: Handles work sessions that cross midnight
• Direct Time Entries: Supports "Work time X hours/minutes" for flexible logging
• Holiday Support: Automatically adds 8 hours for holidays, PTO, and statutory holidays
• Configurable Weekly Hours: Set custom weekly hour targets (default: 40 hours)
• Hour Shortage Tracking: Shows how many hours short when weekly target isn't met
• Daily Summaries: Shows total hours worked each day (filtered to last 2 weeks)
• Weekly Summaries: Groups days by week with shortage indicators
• Monthly Summaries: Shows total hours by month
• Status Bar Mode: Compact summary for current day and week, perfect for status bars
• Flexible Time Format: Supports both 12-hour and 24-hour time formats

Usage

Run the tool on a directory containing markdown files named in YYYY-MM-DD.md format:

# Basic usage (scans current directory, 40-hour weeks)
cargo run

# Specify directory
cargo run /path/to/timesheets

# Set custom weekly hours target
cargo run --weekly-hours 37.5

# Combined options
cargo run /path/to/timesheets --weekly-hours 35

# Status bar summary (compact output for current day/week)
cargo run -- --summarize

# Status bar with custom weekly hours
cargo run -- --summarize --weekly-hours 35

# Show help
cargo run -- --help

Command Line Options

• directory: Directory containing markdown timesheet files (default: current directory)
• --weekly-hours HOURS: Expected weekly work hours for shortage calculation (default: 40)
• --summarize: Show compact current day and week summary for status bar
• --debug: Show detailed debug information and error locations
• --help, -h: Show usage information

File Format

Create markdown files with names like 2025-08-25.md containing time entries:

# Daily Notes

Start work 9:00
Had a productive morning working on the project.

Stop work 12:00

Lunch break

Start work 13:00
Afternoon session focused on testing.

Stop work 17:30

# Alternative: Direct time logging
Work time 2 hours code review
Work time 30 minutes documentation

# Holiday/PTO examples
Stat holiday
PTO
Holiday day

Supported Time Entry Formats

The parser recognizes these patterns (case insensitive):

Start/Stop Time Entries

• Start work 9:00
• Started working at 8:30
• Stop work 17:30
• Stopped working at 16:45

Direct Time Entries

• Work time 2 hours project work
• Work time 30 minutes meeting
• Work time 1 hour documentation
• Work time 90 minutes code review

Holiday/PTO Entries (automatically adds 8 hours)

• Stat holiday or Statutory holiday
• PTO
• Holiday day

Installation

1. Clone the repository
2. Run cargo build --release
3. The binary will be available at target/release/markdown_timesheet

Requirements

• Rust 2021 edition or later
• Dependencies: chrono, regex

Example Output

Daily Summary (Last 2 Weeks):
==============================
2025-08-25 Mon - 8h 30m
2025-08-26 Tue - 7h 00m  
2025-08-27 Wed - 6h 15m
2025-08-28 Thu - 8h 00m
2025-08-29 Fri - 4h 15m

Monthly Summary:
================
August 2025: 156h 45m
September 2025: 42h 30m

Weekly Summary:
===============
Week of 2025-08-25 - 2025-08-31: 34h 00m [6h 00m short]
Week of 2025-09-01 - 2025-09-07: 42h 30m

The weekly summary shows shortages when using the default 40-hour target. Weeks that meet or exceed the target show no shortage indicator.

Status Bar Output

When using the --summarize flag, the tool outputs a compact single-line format perfect for status bars:

Today: 5h 30m * | Week: 32h 15m (7.8h short)

Status Indicators

• *: Tentative time (current incomplete session still running)
• E!: Error flag (incomplete or orphaned time entries)
• (X.Xh short): Hours remaining to meet weekly target

Examples

# Normal completed day
Today: 8h 00m | Week: 40h 00m

# Day with tentative time (currently working)  
Today: 5h 30m * | Week: 32h 15m (7.8h short)

# Day with errors (incomplete entries)
Today: 3h 45m E! | Week: 25h 30m (14.5h short)

# No data available
Today: No data | Week: No data

# Week target exceeded
Today: 9h 15m | Week: 42h 30m

Testing

Run tests with:

cargo test

Code Quality

The codebase follows Rust best practices and passes all quality checks with zero warnings:

# Run clippy for linting (strict mode with pedantic checks)
cargo clippy -- -D warnings -D clippy::all -D clippy::pedantic

# Run tests (42 tests, all passing)
cargo test

# Build optimized release
cargo build --release

Performance Features

The code is optimized for maximum performance:

• Efficient Iterator Chains: Uses filter_map() and sum() for optimal processing
• Zero-Copy Operations: Employs slices (&[T]) instead of owned vectors where possible
• Optimized Sorting: Uses sort_unstable_by_key() for better performance than stable sorting
• Minimal Allocations: Avoids unnecessary string allocations and temporary objects
• Modern Rust Idioms: Leverages latest Rust patterns for optimal compilation

Contributing

The code is optimized for performance and follows canonical Rust patterns:

• Uses iterator chains with filter_map() and sum() for efficiency
• Employs sort_unstable_by_key() for better performance than stable sorting
• Avoids unnecessary allocations and uses slices where possible
• Passes clippy with zero warnings on pedantic mode
• All 42 tests pass with no regressions
• Modern inline format syntax for optimal string handling