ether-to-astro 1.0.0

package/tests/unit/solver-edges.test.ts

@@ -0,0 +1,197 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import { EphemerisCalculator } from '../../src/ephemeris.js';
+import { TransitCalculator, deduplicateTransits } from '../../src/transits.js';
+import { PLANETS, type PlanetPosition, type Transit } from '../../src/types.js';
+
+describe('Solver and transit edge policies', () => {
+  let ephem: EphemerisCalculator;
+  let transitCalc: TransitCalculator;
+
+  beforeAll(async () => {
+    ephem = new EphemerisCalculator();
+    await ephem.init();
+    transitCalc = new TransitCalculator(ephem);
+  });
+
+  it('captures root at coarse-scan endpoint', () => {
+    const startDate = new Date('2024-03-20T00:00:00Z');
+    const startJD = ephem.dateToJulianDay(startDate);
+    const endJD = startJD + 30;
+
+    const sun = ephem.getAllPlanets(startJD, [PLANETS.SUN])[0];
+    const roots = ephem.findExactTransitTimes(PLANETS.SUN, sun.longitude, startJD, endJD);
+
+    expect(roots.length).toBeGreaterThan(0);
+    expect(Math.abs(roots[0] - startJD)).toBeLessThan(1 / 1440);
+  });
+
+  it('returns multiple roots in a large interval', () => {
+    const startDate = new Date('2024-01-01T00:00:00Z');
+    const startJD = ephem.dateToJulianDay(startDate);
+    const endJD = startJD + 800;
+
+    const targetLongitude = 0;
+    const roots = ephem.findExactTransitTimes(PLANETS.SUN, targetLongitude, startJD, endJD);
+
+    expect(roots.length).toBeGreaterThanOrEqual(2);
+    for (let i = 1; i < roots.length; i++) {
+      expect(roots[i]).toBeGreaterThan(roots[i - 1]);
+    }
+  });
+
+  it('finds tangential root near station without sign-change bracketing', () => {
+    // Mercury station region creates local minima/maxima in longitude.
+    // Targeting a sampled local minimum should produce a tangential root.
+    const centerDate = new Date('2023-12-13T00:00:00Z');
+    const centerJD = ephem.dateToJulianDay(centerDate);
+    const startJD = centerJD - 2;
+    const endJD = centerJD + 2;
+
+    // Find a local minimum longitude sample in this station window.
+    let minSampleJD = startJD;
+    let minSampleLon = Infinity;
+    for (let i = 0; i <= 96; i++) {
+      const jd = startJD + (i * (endJD - startJD)) / 96;
+      const lon = ephem.getAllPlanets(jd, [PLANETS.MERCURY])[0].longitude;
+      if (lon < minSampleLon) {
+        minSampleLon = lon;
+        minSampleJD = jd;
+      }
+    }
+
+    const signedDiff = (lon: number, target: number): number => {
+      let d = lon - target;
+      if (d > 180) d -= 360;
+      if (d < -180) d += 360;
+      return d;
+    };
+
+    const startLon = ephem.getAllPlanets(startJD, [PLANETS.MERCURY])[0].longitude;
+    const endLon = ephem.getAllPlanets(endJD, [PLANETS.MERCURY])[0].longitude;
+    const startDiff = signedDiff(startLon, minSampleLon);
+    const endDiff = signedDiff(endLon, minSampleLon);
+
+    // Tangential case: endpoints are on the same side (or very near) of target.
+    expect(startDiff).toBeGreaterThanOrEqual(-0.05);
+    expect(endDiff).toBeGreaterThanOrEqual(-0.05);
+
+    const roots = ephem.findExactTransitTimes(
+      PLANETS.MERCURY,
+      minSampleLon,
+      startJD,
+      endJD,
+      0.01
+    );
+
+    expect(roots.length).toBeGreaterThan(0);
+
+    const nearest = roots.reduce((best, jd) =>
+      Math.abs(jd - minSampleJD) < Math.abs(best - minSampleJD) ? jd : best
+    , roots[0]);
+
+    expect(Math.abs(nearest - minSampleJD)).toBeLessThan(0.5);
+    const nearestLon = ephem.getAllPlanets(nearest, [PLANETS.MERCURY])[0].longitude;
+    expect(ephem.calculateAspectAngle(nearestLon, minSampleLon)).toBeLessThan(0.1);
+  });
+
+  it('uses root-based applying/separating when exact root is selected', () => {
+    const now = new Date('2024-03-15T00:00:00Z');
+    const currentJD = ephem.dateToJulianDay(now);
+    const mars = ephem.getAllPlanets(currentJD, [PLANETS.MARS])[0];
+
+    const applyingNatal: PlanetPosition = {
+      planetId: PLANETS.VENUS,
+      planet: 'Venus',
+      longitude: (mars.longitude + 92) % 360,
+      latitude: 0,
+      distance: 1,
+      speed: 1,
+      sign: 'Cancer',
+      degree: 2,
+      isRetrograde: false,
+    };
+
+    const separatingNatal: PlanetPosition = {
+      ...applyingNatal,
+      longitude: (mars.longitude + 88 + 360) % 360,
+    };
+
+    const applying = transitCalc.findTransits([mars], [applyingNatal], currentJD)
+      .find((t) => t.aspect === 'square');
+    const separating = transitCalc.findTransits([mars], [separatingNatal], currentJD)
+      .find((t) => t.aspect === 'square');
+
+    expect(applying).toBeDefined();
+    expect(separating).toBeDefined();
+
+    if (applying?.exactTimeStatus === 'within_preview' && applying.exactTime) {
+      expect(applying.isApplying).toBe(true);
+      expect(applying.exactTime.getTime()).toBeGreaterThanOrEqual(now.getTime());
+    }
+
+    if (separating?.exactTimeStatus === 'within_preview' && separating.exactTime) {
+      expect(separating.isApplying).toBe(false);
+      expect(separating.exactTime.getTime()).toBeLessThanOrEqual(now.getTime());
+    }
+  });
+
+  it('marks unsupported bodies honestly', () => {
+    const now = new Date('2024-03-15T00:00:00Z');
+    const currentJD = ephem.dateToJulianDay(now);
+
+    const unsupportedTransit: PlanetPosition = {
+      planetId: 9999,
+      planet: 'Sun',
+      longitude: 120,
+      latitude: 0,
+      distance: 1,
+      speed: 1,
+      sign: 'Cancer',
+      degree: 0,
+      isRetrograde: false,
+    };
+
+    const natal: PlanetPosition = {
+      planetId: PLANETS.MARS,
+      planet: 'Mars',
+      longitude: 120,
+      latitude: 0,
+      distance: 1,
+      speed: 1,
+      sign: 'Cancer',
+      degree: 0,
+      isRetrograde: false,
+    };
+
+    const transit = transitCalc.findTransits([unsupportedTransit], [natal], currentJD)
+      .find((t) => t.aspect === 'conjunction');
+
+    expect(transit).toBeDefined();
+    expect(transit?.exactTimeStatus).toBe('unsupported_body');
+    expect(transit?.exactTime).toBeUndefined();
+  });
+
+  it('deduplicates deterministically under total ties', () => {
+    const a: Transit = {
+      transitingPlanet: 'Mars',
+      natalPlanet: 'Venus',
+      aspect: 'square',
+      orb: 0.5,
+      isApplying: true,
+      transitLongitude: 100,
+      natalLongitude: 81,
+      exactTimeStatus: 'not_found',
+    };
+
+    const b: Transit = {
+      ...a,
+      natalLongitude: 80,
+    };
+
+    const first = deduplicateTransits([a, b])[0];
+    const second = deduplicateTransits([b, a])[0];
+
+    expect(first.natalLongitude).toBe(second.natalLongitude);
+    expect(first.natalLongitude).toBe(80);
+  });
+});

package/tests/unit/time-utils-temporal.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Comprehensive tests for Temporal-based time-utils
+ * 
+ * Covers:
+ * - Timezone validity
+ * - Normal UTC <-> local round-trip
+ * - DST spring-forward gap (nonexistent times)
+ * - DST fall-back overlap (ambiguous times)
+ * - Non-hour offsets (Asia/Kolkata, Asia/Kathmandu)
+ * - Offset sign convention and correctness
+ * - Midnight handling
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  localToUTC,
+  utcToLocal,
+  isValidTimezone,
+  getTimezoneOffset,
+  type LocalDateTime,
+} from '../../src/time-utils.js';
+
+describe('Time utils with Temporal', () => {
+  describe('Timezone validity', () => {
+    it('should accept valid IANA timezone', () => {
+      expect(isValidTimezone('America/New_York')).toBe(true);
+      expect(isValidTimezone('Europe/London')).toBe(true);
+      expect(isValidTimezone('Asia/Tokyo')).toBe(true);
+      expect(isValidTimezone('UTC')).toBe(true);
+    });
+
+    it('should reject invalid timezone', () => {
+      expect(isValidTimezone('Invalid/Garbage')).toBe(false);
+      expect(isValidTimezone('')).toBe(false);
+      expect(isValidTimezone('NotAZone')).toBe(false);
+      expect(isValidTimezone('123456')).toBe(false);
+    });
+  });
+
+  describe('Normal conversion round-trip', () => {
+    it('should round-trip UTC <-> local for normal date', () => {
+      const local: LocalDateTime = {
+        year: 2024,
+        month: 6,
+        day: 15,
+        hour: 14,
+        minute: 30,
+        second: 0,
+      };
+
+      const utc = localToUTC(local, 'America/Los_Angeles');
+      const roundTrip = utcToLocal(utc, 'America/Los_Angeles');
+
+      expect(roundTrip.year).toBe(local.year);
+      expect(roundTrip.month).toBe(local.month);
+      expect(roundTrip.day).toBe(local.day);
+      expect(roundTrip.hour).toBe(local.hour);
+      expect(roundTrip.minute).toBe(local.minute);
+    });
+
+    it('should convert UTC to local correctly', () => {
+      // 2024-06-15 21:30 UTC = 2024-06-15 14:30 PDT (UTC-7)
+      const utc = new Date('2024-06-15T21:30:00Z');
+      const local = utcToLocal(utc, 'America/Los_Angeles');
+
+      expect(local.year).toBe(2024);
+      expect(local.month).toBe(6);
+      expect(local.day).toBe(15);
+      expect(local.hour).toBe(14);
+      expect(local.minute).toBe(30);
+    });
+  });
+
+  describe('DST spring-forward gap (nonexistent times)', () => {
+    it('should handle nonexistent time in America/New_York with compatible', () => {
+      // March 10, 2024, 2:30 AM doesn't exist (clock jumps 2:00 -> 3:00)
+      const nonexistent: LocalDateTime = {
+        year: 2024,
+        month: 3,
+        day: 10,
+        hour: 2,
+        minute: 30,
+        second: 0,
+      };
+
+      // 'compatible' should shift forward
+      const utc = localToUTC(nonexistent, 'America/New_York', 'compatible');
+      expect(utc).toBeDefined();
+
+      // Verify it shifted to 3:30 AM EDT (which is 7:30 UTC)
+      const local = utcToLocal(utc, 'America/New_York');
+      expect(local.hour).toBe(3); // Shifted forward
+      expect(local.minute).toBe(30);
+    });
+
+    it('should reject nonexistent time with reject disambiguation', () => {
+      const nonexistent: LocalDateTime = {
+        year: 2024,
+        month: 3,
+        day: 10,
+        hour: 2,
+        minute: 30,
+        second: 0,
+      };
+
+      expect(() => {
+        localToUTC(nonexistent, 'America/New_York', 'reject');
+      }).toThrow();
+    });
+  });
+
+  describe('DST fall-back overlap (ambiguous times)', () => {
+    it('should handle ambiguous time in America/New_York with compatible', () => {
+      // November 3, 2024, 1:30 AM happens twice (clock falls back 2:00 -> 1:00)
+      const ambiguous: LocalDateTime = {
+        year: 2024,
+        month: 11,
+        day: 3,
+        hour: 1,
+        minute: 30,
+        second: 0,
+      };
+
+      // 'compatible' should pick the earlier occurrence (EDT, before fall-back)
+      const utc = localToUTC(ambiguous, 'America/New_York', 'compatible');
+      expect(utc).toBeDefined();
+
+      // The earlier 1:30 AM EDT is 5:30 UTC
+      // The later 1:30 AM EST is 6:30 UTC
+      // 'compatible' picks earlier, so should be 5:30 UTC
+      expect(utc.getUTCHours()).toBe(5);
+      expect(utc.getUTCMinutes()).toBe(30);
+    });
+
+    it('should handle ambiguous time with earlier disambiguation', () => {
+      const ambiguous: LocalDateTime = {
+        year: 2024,
+        month: 11,
+        day: 3,
+        hour: 1,
+        minute: 30,
+        second: 0,
+      };
+
+      const utc = localToUTC(ambiguous, 'America/New_York', 'earlier');
+      expect(utc.getUTCHours()).toBe(5); // Earlier occurrence
+    });
+
+    it('should handle ambiguous time with later disambiguation', () => {
+      const ambiguous: LocalDateTime = {
+        year: 2024,
+        month: 11,
+        day: 3,
+        hour: 1,
+        minute: 30,
+        second: 0,
+      };
+
+      const utc = localToUTC(ambiguous, 'America/New_York', 'later');
+      expect(utc.getUTCHours()).toBe(6); // Later occurrence
+    });
+
+    it('should reject ambiguous time with reject disambiguation', () => {
+      const ambiguous: LocalDateTime = {
+        year: 2024,
+        month: 11,
+        day: 3,
+        hour: 1,
+        minute: 30,
+        second: 0,
+      };
+
+      expect(() => {
+        localToUTC(ambiguous, 'America/New_York', 'reject');
+      }).toThrow();
+    });
+  });
+
+  describe('Non-hour offsets', () => {
+    it('should handle Asia/Kolkata (UTC+5:30)', () => {
+      const local: LocalDateTime = {
+        year: 2024,
+        month: 6,
+        day: 15,
+        hour: 14,
+        minute: 30,
+        second: 0,
+      };
+
+      const utc = localToUTC(local, 'Asia/Kolkata');
+      const roundTrip = utcToLocal(utc, 'Asia/Kolkata');
+
+      expect(roundTrip.hour).toBe(local.hour);
+      expect(roundTrip.minute).toBe(local.minute);
+
+      // Verify offset is +330 minutes (5.5 hours)
+      const offset = getTimezoneOffset(utc, 'Asia/Kolkata');
+      expect(offset).toBe(330);
+    });
+
+    it('should handle Asia/Kathmandu (UTC+5:45)', () => {
+      const local: LocalDateTime = {
+        year: 2024,
+        month: 6,
+        day: 15,
+        hour: 14,
+        minute: 30,
+        second: 0,
+      };
+
+      const utc = localToUTC(local, 'Asia/Kathmandu');
+      const roundTrip = utcToLocal(utc, 'Asia/Kathmandu');
+
+      expect(roundTrip.hour).toBe(local.hour);
+      expect(roundTrip.minute).toBe(local.minute);
+
+      // Verify offset is +345 minutes (5.75 hours)
+      const offset = getTimezoneOffset(utc, 'Asia/Kathmandu');
+      expect(offset).toBe(345);
+    });
+  });
+
+  describe('Offset sign convention and correctness', () => {
+    it('should return negative offset for America/Los_Angeles (west of UTC)', () => {
+      // Winter (PST, UTC-8)
+      const winterDate = new Date('2024-01-15T12:00:00Z');
+      const winterOffset = getTimezoneOffset(winterDate, 'America/Los_Angeles');
+      expect(winterOffset).toBe(-480); // -8 hours
+
+      // Summer (PDT, UTC-7)
+      const summerDate = new Date('2024-07-15T12:00:00Z');
+      const summerOffset = getTimezoneOffset(summerDate, 'America/Los_Angeles');
+      expect(summerOffset).toBe(-420); // -7 hours
+    });
+
+    it('should return positive offset for Asia/Tokyo (east of UTC)', () => {
+      const date = new Date('2024-06-15T12:00:00Z');
+      const offset = getTimezoneOffset(date, 'Asia/Tokyo');
+      expect(offset).toBe(540); // +9 hours
+    });
+
+    it('should return zero offset for UTC', () => {
+      const date = new Date('2024-06-15T12:00:00Z');
+      const offset = getTimezoneOffset(date, 'UTC');
+      expect(offset).toBe(0);
+    });
+  });
+
+  describe('Midnight handling', () => {
+    it('should handle midnight without 24:00 weirdness', () => {
+      const midnight: LocalDateTime = {
+        year: 2024,
+        month: 6,
+        day: 15,
+        hour: 0,
+        minute: 0,
+        second: 0,
+      };
+
+      const utc = localToUTC(midnight, 'America/New_York');
+      const roundTrip = utcToLocal(utc, 'America/New_York');
+
+      expect(roundTrip.hour).toBe(0);
+      expect(roundTrip.minute).toBe(0);
+      expect(roundTrip.day).toBe(15);
+    });
+
+    it('should handle 23:59:59 without overflow', () => {
+      const almostMidnight: LocalDateTime = {
+        year: 2024,
+        month: 6,
+        day: 15,
+        hour: 23,
+        minute: 59,
+        second: 59,
+      };
+
+      const utc = localToUTC(almostMidnight, 'America/New_York');
+      const roundTrip = utcToLocal(utc, 'America/New_York');
+
+      expect(roundTrip.hour).toBe(23);
+      expect(roundTrip.minute).toBe(59);
+      expect(roundTrip.second).toBe(59);
+      expect(roundTrip.day).toBe(15);
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should throw on invalid timezone in localToUTC', () => {
+      const local: LocalDateTime = {
+        year: 2024,
+        month: 6,
+        day: 15,
+        hour: 12,
+        minute: 0,
+      };
+
+      expect(() => {
+        localToUTC(local, 'Invalid/Timezone');
+      }).toThrow(/Invalid timezone/);
+    });
+  });
+});

package/tests/unit/time-utils.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest';
+import { localToUTC, utcToLocal, isValidTimezone, getTimezoneOffset } from '../../src/time-utils.js';
+import type { LocalDateTime } from '../../src/time-utils.js';
+
+describe('Time conversion utility', () => {
+  describe('localToUTC', () => {
+    it('should convert EDT to UTC correctly', () => {
+      // Oct 17 1977, 1:06 PM EDT = Oct 17 1977, 5:06 PM UTC
+      // EDT is UTC-4
+      const local: LocalDateTime = {
+        year: 1977,
+        month: 10,
+        day: 17,
+        hour: 13,
+        minute: 6,
+      };
+
+      const utc = localToUTC(local, 'America/New_York');
+
+      expect(utc.getUTCFullYear()).toBe(1977);
+      expect(utc.getUTCMonth()).toBe(9); // October = 9 (0-indexed)
+      expect(utc.getUTCDate()).toBe(17);
+      expect(utc.getUTCHours()).toBe(17); // 1:06 PM + 4 hours = 5:06 PM
+      expect(utc.getUTCMinutes()).toBe(6);
+    });
+
+    it('should handle DST transitions correctly', () => {
+      // Test date in EDT (summer) - UTC-4
+      const summer: LocalDateTime = {
+        year: 2024,
+        month: 7,
+        day: 15,
+        hour: 12,
+        minute: 0,
+      };
+      const summerUTC = localToUTC(summer, 'America/New_York');
+      expect(summerUTC.getUTCHours()).toBe(16); // EDT = UTC-4
+
+      // Test date in EST (winter) - UTC-5
+      const winter: LocalDateTime = {
+        year: 2024,
+        month: 1,
+        day: 15,
+        hour: 12,
+        minute: 0,
+      };
+      const winterUTC = localToUTC(winter, 'America/New_York');
+      expect(winterUTC.getUTCHours()).toBe(17); // EST = UTC-5
+    });
+
+    it('should handle multiple timezones', () => {
+      const local: LocalDateTime = {
+        year: 2024,
+        month: 3,
+        day: 15,
+        hour: 14,
+        minute: 30,
+      };
+
+      const utcNY = localToUTC(local, 'America/New_York');
+      const utcLA = localToUTC(local, 'America/Los_Angeles');
+      const utcSydney = localToUTC(local, 'Australia/Sydney');
+
+      // LA is 3 hours behind NY
+      expect(utcLA.getTime() - utcNY.getTime()).toBe(3 * 60 * 60 * 1000);
+
+      // Sydney is ahead of UTC
+      expect(utcSydney.getUTCHours()).toBeLessThan(local.hour);
+    });
+
+    it('should handle midnight correctly', () => {
+      const local: LocalDateTime = {
+        year: 2024,
+        month: 3,
+        day: 15,
+        hour: 0,
+        minute: 0,
+      };
+
+      const utc = localToUTC(local, 'America/New_York');
+
+      // Midnight EDT (March 15 is after DST starts) = 4 AM UTC
+      expect(utc.getUTCHours()).toBe(4);
+    });
+
+    it('should handle date rollover when converting to UTC', () => {
+      // 11 PM PDT should become next day in UTC
+      const local: LocalDateTime = {
+        year: 2024,
+        month: 3,
+        day: 15,
+        hour: 23,
+        minute: 0,
+      };
+
+      const utc = localToUTC(local, 'America/Los_Angeles');
+
+      // 11 PM PDT (March 15 is after DST) = 6 AM UTC next day
+      expect(utc.getUTCDate()).toBe(16);
+      expect(utc.getUTCHours()).toBe(6);
+    });
+  });
+
+  describe('utcToLocal', () => {
+    it('should convert UTC to local time correctly', () => {
+      const utc = new Date(Date.UTC(1977, 9, 17, 17, 6));
+
+      const local = utcToLocal(utc, 'America/New_York');
+
+      expect(local.year).toBe(1977);
+      expect(local.month).toBe(10);
+      expect(local.day).toBe(17);
+      expect(local.hour).toBe(13); // 5:06 PM UTC - 4 hours = 1:06 PM EDT
+      expect(local.minute).toBe(6);
+    });
+
+    it('should handle DST in reverse', () => {
+      // Summer: UTC to EDT
+      const summerUTC = new Date(Date.UTC(2024, 6, 15, 16, 0));
+      const summerLocal = utcToLocal(summerUTC, 'America/New_York');
+      expect(summerLocal.hour).toBe(12); // 4 PM UTC - 4 hours = 12 PM EDT
+
+      // Winter: UTC to EST
+      const winterUTC = new Date(Date.UTC(2024, 0, 15, 17, 0));
+      const winterLocal = utcToLocal(winterUTC, 'America/New_York');
+      expect(winterLocal.hour).toBe(12); // 5 PM UTC - 5 hours = 12 PM EST
+    });
+  });
+
+  describe('isValidTimezone', () => {
+    it('should validate correct timezone strings', () => {
+      expect(isValidTimezone('America/New_York')).toBe(true);
+      expect(isValidTimezone('America/Los_Angeles')).toBe(true);
+      expect(isValidTimezone('Europe/London')).toBe(true);
+      expect(isValidTimezone('Australia/Sydney')).toBe(true);
+      expect(isValidTimezone('UTC')).toBe(true);
+      expect(isValidTimezone('EST')).toBe(true);
+      expect(isValidTimezone('GMT')).toBe(true);
+    });
+
+    it('should reject invalid timezone strings', () => {
+      expect(isValidTimezone('Invalid/Timezone')).toBe(false);
+      expect(isValidTimezone('NotAZone')).toBe(false);
+      expect(isValidTimezone('')).toBe(false);
+    });
+  });
+
+  describe('getTimezoneOffset', () => {
+    it('should return correct offset for EDT', () => {
+      const date = new Date(Date.UTC(1977, 9, 17, 17, 6));
+      const offset = getTimezoneOffset(date, 'America/New_York');
+
+      // EDT is UTC-4, so offset should be -240 minutes
+      expect(offset).toBe(-240);
+    });
+
+    it('should return correct offset for EST', () => {
+      const date = new Date(Date.UTC(2024, 0, 15, 12, 0));
+      const offset = getTimezoneOffset(date, 'America/New_York');
+
+      // EST is UTC-5, so offset should be -300 minutes
+      expect(offset).toBe(-300);
+    });
+
+    it('should handle positive offsets', () => {
+      const date = new Date(Date.UTC(2024, 6, 15, 12, 0));
+      const offset = getTimezoneOffset(date, 'Australia/Sydney');
+
+      // AEST is UTC+10, so offset should be 600 minutes
+      expect(offset).toBe(600);
+    });
+  });
+});