cal-timezone-date-mining
Read-only mining codemod for timezone-sensitive date handling in Cal.com-style TypeScript codebases. Detects date-only parsing, Date.parse, locale formatting, dayjs day boundaries, and Prisma query date comparisons without modifying source.
# cal-timezone-date-mining
Read-only mining codemod for **timezone-sensitive date handling** patterns, tailored to [Cal.com](https://github.com/calcom/cal.com)-style TypeScript codebases.
Detection only — **does not modify source code**.
## Why this exists
Cal.com schedules bookings across timezones using Prisma (`startTime`, `endTime`, `createdAt`), `@calcom/dayjs`, and API date filters. Patterns like `new Date("YYYY-MM-DD")` or local `startOf("day")` can pass mocked tests but fail under server timezone, database timezone, DST, or UTC conversion differences.
## Metric
Single metric atom: **`timezone-date-handling`**
| Cardinality | Description |
|-------------|-------------|
| `pattern` | API smell: `new_date_date_only`, `date_parse`, `to_locale_string`, `date_to_string`, `dayjs_date_only`, `dayjs_day_boundary` |
| `queryField` | Cal.com Prisma field when used in a query boundary (`startTime`, `endTime`, `createdAt`, …) or `none` |
| `queryOp` | Prisma comparator (`gte`, `lte`, `gt`, `lt`) or `none` |
| `risk` | `high` (in query boundary), `medium`, or `low` |
| `inQueryBoundary` | `true` when the value feeds a Prisma date filter |
| `file` | Relative file path |
| `line` | 1-based line of the anchor expression |
| `snippet` | Truncated source excerpt |
## Cal.com-tailored detection
Built from repo scan findings:
- **Booking Prisma fields**: `startTime`, `endTime`, `createdAt`, `updatedAt`, `periodStart*`, `highWaterMarkPeriodStart`, …
- **dayjs / @calcom/dayjs**: date-only literals and local `startOf("day")` / `endOf("day")` (excludes `.utc()` chains)
- **API filter parsing**: `Date.parse` in handlers (e.g. insights / voice-agent date filters)
- **Locale formatting**: `.toLocaleString()` in UI and email templates
### Exclusions
- Explicit UTC / offset timestamps (`2026-05-25T00:00:00.000Z`) for constructors and `Date.parse`
- `dayjs.utc(...).startOf("day")` and similar UTC-safe chains
- Test files (`*.test.ts`, `*.spec.ts`, integration tests) via workflow excludes
## Usage
```bash
# Run tests
npm test
# Dry-run against Cal.com (from repo root)
npx codemod workflow run \
-w codemods/cal-timezone-date-mining/workflow.yaml \
--target /path/to/cal.com \
--dry-run
```
## Example finding
```typescript
// Risky — date-only literal bound into Prisma startTime filter
const start = new Date("2026-05-25");
await prisma.booking.findMany({
where: { startTime: { gte: start } },
});
```
Emitted metric cardinality:
```json
{
"pattern": "new_date_date_only",
"queryField": "startTime",
"queryOp": "gte",
"risk": "high",
"inQueryBoundary": "true"
}
```
## Development
```bash
npm run check-types
npm test
```