analyze-timezone-sensitive-scheduling-boundaries

Public Insights analysis package for detecting likely timezone-sensitive scheduling and date boundary handling in JavaScript and TypeScript repositories.

This package is read-only. It does not rewrite source files. It scans JS/TS/TSX code and increments one Insights metric per finding.

What It Detects

The workflow records findings for these risky patterns:

• new Date("YYYY-MM-DD")
• Date.parse(...)
• new Date() or Date.now() in scheduling/query boundary logic
• .toISOString() in scheduling/query boundary logic
• toLocaleString(), toLocaleDateString(), and toLocaleTimeString() without explicit timeZone options
• ORM/query/filter boundary objects on startTime, endTime, createdAt, updatedAt, start, end, and expiresAt

The analysis boosts confidence when the file path or nearby code suggests scheduling-related domains such as booking, scheduling, slot, calendar, availability, appointment, attendee, event, meeting, or reservation.

Targeting And Exclusions

• Included: **/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}
• Excluded: tests, fixtures, mocks, snapshots, e2e, coverage, generated files, build output, and node_modules

Metric

This package uses exactly one metric:

• Metric name: timezone-sensitive-scheduling-boundary

Cardinality keys emitted on every increment:

• kind: date-only-construction, date-parse, now-boundary, iso-boundary, locale-format, query-boundary
• boundaryField: startTime, endTime, createdAt, updatedAt, start, end, expiresAt, or unknown
• confidence: low, medium, high
• domain: booking, scheduling, slot, calendar, availability, appointment, attendee, event, meeting, reservation, or generic
• timezoneContext: input.timeZone, user.timeZone, schedule.timeZone, teamTimeZone, orgTimeZone, calendarTimeZone, attendeeTimeZone, timeZone, timezone, tz, or none
• api: new-date, date-parse, date-now, toISOString, or query-filter
• filename: basename of the analyzed file such as query.ts, bookings.repository.ts, or AvailabilityTable.tsx
• language: typescript, tsx, or javascript

Workflow

• Workflow name: main
• Workflow step name: analyze-timezone-boundaries

Example Insights metric source:

ts
Copy
{
  packageId: "<returned packageId>",
  packageVersionId: "<returned packageVersionId>",
  workflowName: "main",
  stepName: "analyze-timezone-boundaries",
  select: { type: "metric", metricName: "timezone-sensitive-scheduling-boundary" }
}

Example query grouped by kind:

ts
Copy
{
  packageId: "<returned packageId>",
  packageVersionId: "<returned packageVersionId>",
  workflowName: "main",
  stepName: "analyze-timezone-boundaries",
  select: { type: "metric", metricName: "timezone-sensitive-scheduling-boundary" },
  groupBy: [{ name: "cardinality", key: "kind" }]
}

Example query grouped by boundaryField:

ts
Copy
{
  packageId: "<returned packageId>",
  packageVersionId: "<returned packageVersionId>",
  workflowName: "main",
  stepName: "analyze-timezone-boundaries",
  select: { type: "metric", metricName: "timezone-sensitive-scheduling-boundary" },
  groupBy: [{ name: "cardinality", key: "boundaryField" }]
}

Example query grouped by repository:

ts
Copy
{
  packageId: "<returned packageId>",
  packageVersionId: "<returned packageVersionId>",
  workflowName: "main",
  stepName: "analyze-timezone-boundaries",
  select: { type: "metric", metricName: "timezone-sensitive-scheduling-boundary" },
  groupBy: [{ name: "repository" }]
}

Example query grouped by filename:

ts
Copy
{
  packageId: "<returned packageId>",
  packageVersionId: "<returned packageVersionId>",
  workflowName: "main",
  stepName: "analyze-timezone-boundaries",
  select: { type: "metric", metricName: "timezone-sensitive-scheduling-boundary" },
  groupBy: [{ name: "cardinality", key: "filename" }]
}

Usage

Run locally:

bash
Copy
pnpm dlx codemod@latest workflow run -w . -t /path/to/repository

Run tests:

bash
Copy
pnpm test
pnpm check-types
pnpm dlx codemod@latest workflow validate -w workflow.yaml

Test Coverage

Fixtures cover these scenarios without modifying source output:

• no-op read-only behavior
• new Date().toISOString() in a startTime query boundary
• new Date("YYYY-MM-DD")
• createdAt and updatedAt range filters
• nearby timezone identifiers contributing timezoneContext
• nested file fixtures proving filename is emitted as a basename only
• safe timezone validation/import code producing no edits and no intended findings

The JSSG fixture harness in this package validates both read-only behavior and metric output through metrics.json snapshots. Those fixtures now assert that the package still emits exactly one metric via useMetricAtom("timezone-sensitive-scheduling-boundary") and that each finding includes the basename-only filename cardinality.

License

MIT