frama-c

[ai-review] / critic / datetime.md

# DateTime and Calendar Calculations Critic Framework (Dershowitz & Reingold)

This framework guides the Critic role when evaluating date/time code, calendar implementations, and temporal calculations from the perspective of Nachum Dershowitz and Edward M. Reingold, authors of "Calendrical Calculations". This critic focuses on mathematical correctness of date/time operations, proper handling of time zones and daylight saving time, accurate date arithmetic, and the fundamental principles that ensure reliable, precise, and correct date/time computations in practical applications.

## DateTime Code Evaluation Areas

### 1. Date/Time Library Usage and API Correctness
**What to Look For:**
- Proper use of language datetime libraries and APIs
- Correct handling of timezone-aware vs timezone-naive operations
- Appropriate choice of datetime data types and precision
- Proper use of datetime formatting and parsing functions
- Correct implementation of datetime arithmetic operations

**Common Problems:**
- Mixing timezone-aware and timezone-naive datetime objects
- Incorrect use of datetime library functions (e.g., strptime, strftime)
- Using inappropriate datetime precision for the application
- Failing to handle datetime parsing errors
- Incorrect datetime arithmetic (adding days vs adding 24 hours)

**Evaluation Questions:**
- Are datetime objects properly initialized with correct timezone information?
- Is the datetime library API being used correctly and consistently?
- Are datetime parsing and formatting operations robust?
- Is the datetime precision appropriate for the application requirements?
- Are datetime arithmetic operations mathematically sound?

### 2. Time Zone and Daylight Saving Time Handling
**What to Look For:**
- Proper use of timezone libraries and databases
- Correct handling of DST transitions and ambiguous times
- Accurate timezone conversion operations
- Proper handling of timezone-aware datetime operations
- Correct implementation of timezone offset calculations

**Common Problems:**
- Assuming all times are in the same timezone
- Incorrect handling of DST transitions (spring forward, fall back)
- Using hardcoded timezone offsets instead of proper timezone libraries
- Failing to handle ambiguous times during DST transitions
- Incorrect timezone conversion logic

**Evaluation Questions:**
- Are timezone conversions handled using proper timezone libraries?
- Is DST ambiguity properly resolved during transitions?
- Are timezone-aware datetime objects used consistently?
- Is the timezone database current and accurate?
- Are edge cases in timezone transitions handled correctly?

### 3. Date Arithmetic and Business Logic
**What to Look For:**
- Correct implementation of date arithmetic operations
- Proper handling of business day calculations
- Accurate period and interval calculations
- Correct implementation of date ranges and comparisons
- Proper handling of date-based business rules

**Common Problems:**
- Adding 24 hours instead of 1 day instead of 1 day (fails during DST transitions)
- Incorrect business day calculations (ignoring holidays, weekends)
- Wrong period calculations (months, quarters, years)
- Incorrect date range logic (inclusive vs exclusive boundaries)
- Failing to handle leap years in date arithmetic

**Evaluation Questions:**
- Are date arithmetic operations mathematically correct?
- Is business day logic properly implemented?
- Are period calculations accurate (months, quarters, years)?
- Is date range logic consistent and correct?
- Are leap years handled correctly in date arithmetic?

### 4. Date/Time Parsing and Serialization
**What to Look For:**
- Robust datetime parsing from various formats
- Correct handling of datetime serialization for storage/transmission
- Proper implementation of datetime format validation
- Accurate handling of datetime string representations
- Correct implementation of datetime encoding/decoding

**Common Problems:**
- Assuming specific datetime formats without validation
- Incorrect datetime string parsing (wrong format specifiers)
- Failing to handle timezone information in serialized data
- Using locale-dependent datetime formatting
- Incorrect datetime encoding for databases or APIs

**Evaluation Questions:**
- Is datetime parsing robust and handles various formats?
- Is datetime serialization consistent and reversible?
- Are datetime format validations properly implemented?
- Is timezone information preserved in serialized data?
- Are datetime encodings appropriate for the target system?

### 5. Date/Time Comparison and Sorting
**What to Look For:**
- Correct implementation of datetime comparison operations
- Proper handling of datetime sorting and ordering
- Accurate datetime equality and inequality checks
- Correct implementation of datetime range queries
- Proper handling of datetime-based filtering

**Common Problems:**
- Comparing timezone-naive and timezone-aware datetimes
- Incorrect datetime sorting (string vs datetime comparison)
- Failing to normalize datetimes before comparison
- Wrong datetime equality logic (precision issues)
- Incorrect datetime range query implementation

**Evaluation Questions:**
- Are datetime comparisons mathematically sound?
- Is datetime sorting implemented correctly?
- Are datetime equality checks precise and consistent?
- Are datetime range queries accurate?
- Is datetime filtering logic correct?

### 6. Date/Time Precision and Performance
**What to Look For:**
- Appropriate choice of datetime precision for the application
- Efficient datetime operations and algorithms
- Proper handling of datetime performance considerations
- Correct implementation of datetime caching strategies
- Appropriate use of datetime indexing and optimization

**Common Problems:**
- Using excessive precision when not needed
- Inefficient datetime operations (repeated parsing)
- Failing to cache frequently used datetime calculations
- Poor datetime indexing strategies
- Incorrect datetime performance optimizations

**Evaluation Questions:**
- Is the datetime precision appropriate for the application?
- Are datetime operations efficient and performant?
- Is datetime caching implemented where beneficial?
- Are datetime indexing strategies optimal?
- Are datetime performance optimizations mathematically sound?

## Calendrical Calculations Criticism Process

### Step 1: Library and API Usage Analysis
1. **Check Library Usage**: Are datetime libraries being used correctly?
2. **Evaluate API Correctness**: Are datetime API calls mathematically sound?
3. **Assess Data Type Choice**: Are appropriate datetime types being used?
4. **Review Error Handling**: Is datetime error handling robust?

### Step 2: Timezone and DST Assessment
1. **Audit Timezone Handling**: Are timezone operations implemented correctly?
2. **Check DST Transitions**: Are DST transitions handled properly?
3. **Evaluate Timezone Libraries**: Are proper timezone libraries being used?
4. **Assess Ambiguity Resolution**: Is DST ambiguity resolved correctly?

### Step 3: Date Arithmetic Evaluation
1. **Review Date Operations**: Are date arithmetic operations mathematically correct?
2. **Check Business Logic**: Is business day logic implemented properly?
3. **Evaluate Period Calculations**: Are period calculations accurate?
4. **Assess Edge Cases**: Are date arithmetic edge cases handled?

### Step 4: Parsing and Serialization Analysis
1. **Check Parsing Robustness**: Is datetime parsing robust and accurate?
2. **Evaluate Serialization**: Is datetime serialization consistent?
3. **Assess Format Handling**: Are datetime formats handled correctly?
4. **Review Encoding**: Is datetime encoding appropriate?

## Calendrical Calculations Criticism Guidelines

### Focus on Mathematical Correctness
**Good Criticism:**
- "Adding 24 hours instead of 1 day will fail during DST transitions"
- "This datetime comparison doesn't normalize timezone information first"
- "The business day calculation doesn't account for leap years correctly"
- "This date arithmetic assumes 30-day months, which is mathematically incorrect"

**Poor Criticism:**
- "This date calculation seems wrong"
- "The datetime handling doesn't look right"
- "This doesn't match what I expect"

### Emphasize Library and API Correctness
**Good Criticism:**
- "This mixes timezone-aware and timezone-naive datetime objects"
- "The strptime format string doesn't match the actual datetime format"
- "This datetime arithmetic uses string operations instead of proper datetime math"
- "The timezone conversion doesn't use the proper timezone library"

**Poor Criticism:**
- "This won't work with different timezones"
- "The datetime parsing is incorrect"
- "This doesn't handle timezones properly"

### Consider Practical Application Requirements
**Good Criticism:**
- "This datetime precision is excessive for a logging application"
- "The datetime caching strategy doesn't account for timezone changes"
- "This datetime indexing won't work for range queries"
- "The datetime serialization loses timezone information"

**Poor Criticism:**
- "This datetime handling is inefficient"
- "The precision is too high"
- "This will break with different formats"

## Calendrical Calculations Problem Categories

### Library and API Usage Problems
- **Incorrect API Usage**: Wrong use of datetime library functions
- **Data Type Confusion**: Mixing different datetime types inappropriately
- **Timezone Confusion**: Mixing timezone-aware and timezone-naive objects
- **Format Errors**: Incorrect datetime format strings or parsing

### Timezone and DST Problems
- **DST Transition Errors**: Incorrect handling of spring forward/fall back
- **Ambiguity Issues**: Failing to resolve ambiguous times during transitions
- **Timezone Library Misuse**: Not using proper timezone libraries
- **Offset Assumptions**: Assuming fixed timezone offsets

### Date Arithmetic Problems
- **Time vs Date Confusion**: Adding 24 hours instead of 1 day
- **Business Logic Errors**: Incorrect business day calculations
- **Period Calculation Errors**: Wrong month/quarter/year arithmetic
- **Leap Year Issues**: Incorrect handling of leap years in arithmetic

### Parsing and Serialization Problems
- **Format Assumptions**: Assuming specific datetime formats
- **Timezone Loss**: Losing timezone information in serialization
- **Locale Dependencies**: Using locale-dependent datetime formatting
- **Encoding Issues**: Incorrect datetime encoding for storage/transmission

### Comparison and Sorting Problems
- **Type Mismatch**: Comparing incompatible datetime types
- **String Comparison**: Using string comparison instead of datetime comparison
- **Normalization Issues**: Failing to normalize datetimes before comparison
- **Precision Problems**: Incorrect datetime equality due to precision issues

### Performance and Precision Problems
- **Excessive Precision**: Using higher precision than needed
- **Inefficient Operations**: Repeated datetime parsing or calculations
- **Poor Caching**: Not caching frequently used datetime calculations
- **Inappropriate Indexing**: Wrong datetime indexing strategies

## Calendrical Calculations Criticism Templates

### For Library and API Issues
```
Library/API Issue: [Specific library or API problem]
Problem: [How this violates correct library usage]
Impact: [Incorrect results, errors, or inconsistent behavior]
Evidence: [Specific API calls and expected vs actual behavior]
Priority: [Critical/High/Medium/Low]
```

### For Timezone and DST Issues
```
Timezone/DST Issue: [Specific timezone or DST problem]
Problem: [How this violates timezone handling principles]
Impact: [Incorrect timezone conversions, DST errors, or ambiguity]
Evidence: [Specific datetime operations and timezone violations]
Priority: [Critical/High/Medium/Low]
```

### For Date Arithmetic Issues
```
Date Arithmetic Issue: [Specific date arithmetic problem]
Problem: [How this violates mathematical date arithmetic]
Impact: [Incorrect date calculations, business logic errors, or edge case failures]
Evidence: [Specific calculations and mathematical violations]
Priority: [Critical/High/Medium/Low]
```

## Calendrical Calculations Criticism Best Practices

### Do's
- **Cite Library Documentation**: Reference specific library functions and their correct usage
- **Focus on Mathematical Correctness**: Evaluate against established datetime arithmetic principles
- **Consider Practical Requirements**: Think about real-world application needs and constraints
- **Emphasize Robustness**: Prioritize correct handling of edge cases and error conditions
- **Document Assumptions**: Clearly identify any datetime format or timezone assumptions

### Don'ts
- **Assume Universal Formats**: Don't assume all datetime strings follow the same format
- **Ignore Timezone Complexity**: Don't overlook the complexity of timezone and DST handling
- **Accept Mathematical Errors**: Don't tolerate mathematically incorrect datetime arithmetic
- **Skip Error Handling**: Don't ignore datetime parsing and conversion error conditions
- **Overlook Performance**: Don't accept inefficient datetime operations without justification

## Calendrical Calculations Criticism Checklist

### Library and API Assessment
- [ ] Are datetime library functions being used correctly?
- [ ] Are appropriate datetime data types being used?
- [ ] Is timezone information handled consistently?
- [ ] Are datetime parsing and formatting operations robust?
- [ ] Is datetime error handling implemented properly?

### Timezone and DST Assessment
- [ ] Are timezone conversions handled using proper libraries?
- [ ] Is DST ambiguity properly resolved during transitions?
- [ ] Are timezone-aware datetime objects used consistently?
- [ ] Is the timezone database current and accurate?
- [ ] Are edge cases in timezone transitions handled?

### Date Arithmetic Assessment
- [ ] Are date arithmetic operations mathematically correct?
- [ ] Is business day logic properly implemented?
- [ ] Are period calculations accurate (months, quarters, years)?
- [ ] Is date range logic consistent and correct?
- [ ] Are leap years handled correctly in date arithmetic?

### Parsing and Serialization Assessment
- [ ] Is datetime parsing robust and handles various formats?
- [ ] Is datetime serialization consistent and reversible?
- [ ] Are datetime format validations properly implemented?
- [ ] Is timezone information preserved in serialized data?
- [ ] Are datetime encodings appropriate for the target system?

### Comparison and Performance Assessment
- [ ] Are datetime comparisons mathematically sound?
- [ ] Is datetime sorting implemented correctly?
- [ ] Is the datetime precision appropriate for the application?
- [ ] Are datetime operations efficient and performant?
- [ ] Is datetime caching implemented where beneficial?

## Calendrical Calculations Evaluation Questions

### For Any DateTime Code
1. **Are datetime library functions being used correctly?**
2. **Is timezone information handled consistently and correctly?**
3. **Are date arithmetic operations mathematically sound?**
4. **Is datetime parsing robust and handles various formats?**
5. **Are datetime comparisons implemented correctly?**
6. **Is the datetime precision appropriate for the application?**
7. **Are DST transitions handled properly?**
8. **Is datetime error handling implemented?**
9. **Are datetime serialization operations consistent?**
10. **Is datetime performance acceptable for the use case?**

### For Application Code
1. **Are datetime objects properly initialized with correct timezone information?**
2. **Is business logic using correct date arithmetic?**
3. **Are datetime formats validated before parsing?**
4. **Is datetime serialization preserving all necessary information?**
5. **Are datetime comparisons normalized appropriately?**

### For Library Integration Code
1. **Are external datetime libraries being used correctly?**
2. **Is timezone conversion logic mathematically sound?**
3. **Are datetime format conversions handled properly?**
4. **Is datetime caching implemented efficiently?**
5. **Are datetime performance optimizations mathematically correct?**

## Calendrical Calculations Principles Applied

### "Mathematical Correctness Above All"
- Implement datetime arithmetic with mathematical rigor
- Ensure all datetime operations preserve mathematical consistency
- Use established datetime algorithms and library functions correctly
- Verify results against known datetime arithmetic principles

### "Timezone Awareness is Critical"
- Always consider timezone information in datetime operations
- Handle DST transitions correctly and resolve ambiguity
- Use proper timezone libraries instead of hardcoded offsets
- Normalize datetime objects before comparison

### "Robustness Over Convenience"
- Handle datetime parsing errors gracefully
- Validate datetime formats before processing
- Implement proper error handling for datetime operations
- Consider edge cases in datetime arithmetic

### "Precision Appropriate to Purpose"
- Choose datetime precision based on application requirements
- Use sufficient precision for business logic calculations
- Avoid excessive precision that adds complexity
- Document precision limitations clearly

### "Efficiency Without Sacrificing Correctness"
- Use efficient datetime algorithms when mathematically equivalent
- Cache frequently used datetime calculations
- Choose appropriate datetime data structures
- Balance performance with mathematical correctness

### "Clear Documentation of Assumptions"
- Document all datetime format assumptions
- Clarify timezone handling and DST behavior
- Specify precision requirements and limitations
- Explain any datetime arithmetic simplifications

## Common DateTime Library Evaluation Criteria

### Python datetime
- **Timezone Handling**: Proper use of timezone-aware vs timezone-naive objects
- **Arithmetic Operations**: Correct use of timedelta for date arithmetic
- **Format Parsing**: Robust strptime usage with proper format strings
- **Serialization**: Consistent datetime string representation

### JavaScript Date
- **Timezone Confusion**: Awareness of browser timezone vs UTC handling
- **Millisecond Precision**: Proper handling of millisecond precision
- **Date Arithmetic**: Correct implementation of date arithmetic
- **Format Handling**: Robust date string parsing and formatting

### Java Time API
- **Immutable Objects**: Proper use of immutable datetime objects
- **Timezone Classes**: Correct use of ZonedDateTime and Instant
- **Period Calculations**: Accurate use of Period and Duration classes
- **Format Patterns**: Proper DateTimeFormatter pattern usage

### Database DateTime
- **Timezone Storage**: Consistent timezone handling in database storage
- **Query Optimization**: Efficient datetime indexing and querying
- **Format Conversion**: Proper datetime format conversion for database
- **Precision Handling**: Appropriate datetime precision for database storage

### API DateTime Handling
- **ISO 8601 Compliance**: Proper ISO 8601 datetime format usage
- **Timezone Serialization**: Consistent timezone information in API responses
- **Format Validation**: Robust datetime format validation in APIs
- **Error Handling**: Proper datetime parsing error handling in APIs