# parse-time-sheet.lua

## Description

This Lua script parses time sheet markdown files and converts them to structured JSON format. It validates time entries, detects errors, and provides detailed error reporting with context.

## Usage

```bash
lua parse-time-sheet.lua
```

The script processes predefined markdown files containing time sheet data and outputs JSON files with parsed events and error information.

## Input Format

The script supports multiple time sheet formats:

### Format 1: Day entries with project lines

```markdown
- Mon 2025-01-01
  project1: 09:00-12:00 Task description
  project2: 13:00-17:00 Another task
```

### Format 2: Inline day entries

```markdown
Mon 2025-01-01 09:00-17:00 Work description
```

### Format 3: Mixed format with tasks

```markdown
- Mon 2025-01-01
  project1: 09:00-12:00 Main task
    subtask details
    more subtask info
  project2: 13:00-17:00 Another task
```

## Output

The script generates JSON files with the following structure:

```json
{
  "file_path": "/path/to/input.md",
  "parse_time": "2025-01-01 12:00:00",
  "person": "username",
  "event_count": 1713,
  "error_count": 10,
  "warning_count": 1,
  "day_count": 68,
  "created_at_seconds": 1234567890,
  "event": [
    {
      "level": 1,
      "date": "2025-01-01",
      "day_name": "Mon",
      "project": "project1",
      "start_time": "2025-01-01 09:00:00",
      "end_time": "2025-01-01 12:00:00",
      "description": "Task description",
      "line_number": 2,
      "original_line": "  project1: 09:00-12:00 Task description"
    }
  ]
}
```

## Error Types

The script detects and reports the following error types:

### Errors

- `invalid_date_format`: Date format is not recognized
- `invalid_start_time_format`: Start time format is invalid
- `invalid_end_time_format`: End time format is invalid
- `time_overlap_with_previous`: Time range overlaps with previous entry
- `end_time_before_start_time`: End time is before start time
- `datetime_out_of_sequence`: Events are not in chronological order

### Warnings

- `date_in_description`: Date pattern found in task description

## Features

### Time Validation

- Validates time formats (HH:MM, H:MM, HH:MM:SS)
- Detects time overlaps between consecutive entries
- Handles next-day morning hours (for configured users)
- Validates chronological sequence of events

### Context-Aware Parsing

- Two-pass parsing system for better context understanding
- Smart indentation-based hierarchy detection
- Support for both project-based and inline time entry formats
- Correctly handles short project names (e.g., "ai", "nc", "ui")

### Error Reporting

- Shows first 6 errors per category
- Provides context lines before and after errors
- Reduces excessive context with ellipsis (...) when needed
- Color-coded output for better readability
- Error messages include parsed times on the same line

### Output Management

- JSON files written to current working directory
- Filename based on input file (e.g., `pasi-hours-2025-01-01.md` → `pasi-hours-2025-01-01.json`)
- Summary statistics included in output

## Configuration

### User Settings

- `nextDayUserIdx`: Users allowed to have next-day morning hours
- `morningHourCutoff`: Morning hour cutoff for next-day detection (default: 8 AM)

### File Processing

- Input files are hardcoded in the `parseTimeSheet()` function
- Currently processes:
  - `/Volumes/nc/nc-doc/memo/pasi/pasi-hours-2025-01-01.md`
  - `/Volumes/nc/nc-doc/memo/Paavo/paavo-tunnit-2024-08-07-alkaen.md`

## Dependencies

- `fs`: File system operations
- `peg`: Pattern matching library
- `dt`: Date/time utilities
- `util`: General utilities
- `ansicolor`: Color output formatting
- `start`: Path configuration

## Error Display Format

The error output provides clear context for each error:

```text
- nc-frontend: 14:30-14:20 <<< end_time_before_start_time, parsed: 14:30-14:20
- calc-server: 14:20-14:25 <<< datetime_out_of_sequence
    - fix: "action_limit": false
- ai: 16:30-19:20 <<< invalid_date_format, parsed: 16:30-19:20
```

### Error Format Details

- **Context lines**: Shows parent, siblings, and children around the error (reduced with "..." if too many)
- **Overlap errors**: Shows previous line with time, then current line with `<<< previous hh:mm-hh:mm`
- **Datetime sequence errors**: Include fix suggestion: `- fix: "action_limit": false`
- **Time format errors**: Include parsed times on same line: `, parsed: hh:mm-hh:mm`
- **Maximum errors**: Shows up to 6 errors per category (configurable with `maxErrorPrintCount`)

## Current Configuration

### File Processing

Currently configured to process:

- `/Volumes/nc/nc-doc/memo/pasi/pasi-hours-2025-01-01.md`

Other files are commented out for future use.

## Notes

- The script follows strict naming conventions from AGENTS.md
- No fallback values are used - errors are reported immediately
- All paths must be absolute (starting with `/Volumes/nc/`)
- Output is concise but comprehensive, focusing on actionable error information
- Short project names (2-3 characters) are correctly identified and processed as project entries, not day entries
