ether-to-astro 1.0.0

package/tests/validation/adapters/astrolog.ts

@@ -0,0 +1,306 @@
+import { spawnSync } from 'node:child_process';
+import type { NormalizedBody, NormalizedHouseResult } from '../utils/fixtureTypes.js';
+
+const BODY_NAMES = [
+  'Sun',
+  'Moon',
+  'Mercury',
+  'Venus',
+  'Mars',
+  'Jupiter',
+  'Saturn',
+  'Uranus',
+  'Neptune',
+  'Pluto',
+];
+
+export interface AstrologProbe {
+  enabled: boolean;
+  available: boolean;
+  bin: string;
+  reason?: string;
+}
+
+interface AstrologRunOptions {
+  longitude?: number;
+  latitude?: number;
+  houseSystem?: 'P' | 'W';
+}
+
+export function probeAstrolog(): AstrologProbe {
+  const enabled = process.env.VALIDATE_WITH_ASTROLOG === '1';
+  const bin = process.env.ASTROLOG_BIN || 'astrolog';
+
+  if (!enabled) {
+    return {
+      enabled: false,
+      available: false,
+      bin,
+      reason: 'VALIDATE_WITH_ASTROLOG is not enabled',
+    };
+  }
+
+  const probe = spawnSync(bin, ['-Hc'], { encoding: 'utf8' });
+  const probeText = `${probe.stdout || ''}\n${probe.stderr || ''}`;
+  if (probe.error || (probe.status !== 0 && !/Astrolog\s+version/i.test(probeText))) {
+    return {
+      enabled,
+      available: false,
+      bin,
+      reason: probe.error?.message || probe.stderr || `Exit ${probe.status}`,
+    };
+  }
+
+  return { enabled, available: true, bin };
+}
+
+function parsePositionsFromStdout(stdout: string): NormalizedBody[] {
+  const lines = stdout.split(/\r?\n/);
+  const parsed: NormalizedBody[] = [];
+
+  for (const line of lines) {
+    // Common Astrolog table line format:
+    // "Sun :  6Ari38 ..."
+    const tableMatch = line.match(
+      /^(Sun|Moon|Merc|Venu|Mars|Jupi|Satu|Uran|Nept|Plut)\s*:\s*([0-9]{1,2})([A-Za-z]{3})([0-9]{1,2})\s*(R?)\s*[+-]/i
+    );
+    if (tableMatch) {
+      const bodyMap: Record<string, string> = {
+        Sun: 'Sun',
+        Moon: 'Moon',
+        Merc: 'Mercury',
+        Venu: 'Venus',
+        Mars: 'Mars',
+        Jupi: 'Jupiter',
+        Satu: 'Saturn',
+        Uran: 'Uranus',
+        Nept: 'Neptune',
+        Plut: 'Pluto',
+      };
+      const signOrder = [
+        'Ari',
+        'Tau',
+        'Gem',
+        'Can',
+        'Leo',
+        'Vir',
+        'Lib',
+        'Sco',
+        'Sag',
+        'Cap',
+        'Aqu',
+        'Pis',
+      ];
+      const body = bodyMap[tableMatch[1]];
+      const degree = Number(tableMatch[2]);
+      const signIndex = signOrder.indexOf(tableMatch[3]);
+      const minutes = Number(tableMatch[4]);
+      if (body && signIndex >= 0) {
+        parsed.push({
+          body,
+          longitude: signIndex * 30 + degree + minutes / 60,
+          retrograde: tableMatch[5] === 'R',
+        });
+      }
+      continue;
+    }
+
+    // Example-ish line formats across Astrolog builds often include:
+    // "Sun  6Ar19  ..." or "Sun 6.32"
+    const plainMatch = line.match(
+      /^(Sun|Moon|Mercury|Venus|Mars|Jupiter|Saturn|Uranus|Neptune|Pluto)\s+([0-9]+(?:\.[0-9]+)?)/i
+    );
+    if (plainMatch) {
+      parsed.push({ body: plainMatch[1], longitude: Number(plainMatch[2]) });
+      continue;
+    }
+
+    const zodiacMatch = line.match(
+      /^(Sun|Moon|Mercury|Venus|Mars|Jupiter|Saturn|Uranus|Neptune|Pluto)\s+([0-9]{1,2})([A-Za-z]{2})([0-9]{1,2})/i
+    );
+    if (zodiacMatch) {
+      const signOrder = ['Ar', 'Ta', 'Ge', 'Cn', 'Le', 'Vi', 'Li', 'Sc', 'Sg', 'Cp', 'Aq', 'Pi'];
+      const degree = Number(zodiacMatch[2]);
+      const sign = zodiacMatch[3];
+      const minutes = Number(zodiacMatch[4]);
+      const signIndex = signOrder.indexOf(sign);
+      if (signIndex >= 0) {
+        parsed.push({
+          body: zodiacMatch[1],
+          longitude: signIndex * 30 + degree + minutes / 60,
+        });
+      }
+    }
+  }
+
+  // Keep only one row per body.
+  const byBody = new Map<string, NormalizedBody>();
+  for (const row of parsed) {
+    if (!byBody.has(row.body)) byBody.set(row.body, row);
+  }
+
+  return BODY_NAMES.map((body) => byBody.get(body)).filter((row): row is NormalizedBody =>
+    Boolean(row)
+  );
+}
+
+function toAstrologCoord(
+  value: number,
+  positiveHemisphere: string,
+  negativeHemisphere: string
+): string {
+  const abs = Math.abs(value);
+  let degrees = Math.floor(abs);
+  let minutes = Math.round((abs - degrees) * 60);
+  if (minutes === 60) {
+    degrees += 1;
+    minutes = 0;
+  }
+  const hemisphere = value >= 0 ? positiveHemisphere : negativeHemisphere;
+  return `${degrees}${hemisphere}${String(minutes).padStart(2, '0')}`;
+}
+
+function runAstrologChart(
+  isoUtc: string,
+  probe: AstrologProbe,
+  options: AstrologRunOptions = {}
+): { ok: boolean; stdout?: string; reason?: string } {
+  if (!probe.enabled || !probe.available) {
+    return { ok: false, reason: probe.reason ?? 'Astrolog not available' };
+  }
+
+  const d = new Date(isoUtc);
+  const month = d.getUTCMonth() + 1;
+  const day = d.getUTCDate();
+  const year = d.getUTCFullYear();
+  const hour = String(d.getUTCHours()).padStart(2, '0');
+  const minute = String(d.getUTCMinutes()).padStart(2, '0');
+  const longitude = options.longitude ?? 0;
+  const latitude = options.latitude ?? 0;
+  const lonToken = toAstrologCoord(longitude, 'E', 'W');
+  const latToken = toAstrologCoord(latitude, 'N', 'S');
+
+  const args = [
+    '-qa',
+    String(month),
+    String(day),
+    String(year),
+    `${hour}:${minute}`,
+    '0',
+    lonToken,
+    latToken,
+  ];
+
+  if (options.houseSystem === 'W') {
+    args.push('-c', '14');
+  } else if (options.houseSystem === 'P') {
+    args.push('-c', '0');
+  }
+
+  const result = spawnSync(probe.bin, args, { encoding: 'utf8' });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      reason: result.error?.message || result.stderr || `Exit ${result.status}`,
+    };
+  }
+
+  return { ok: true, stdout: result.stdout };
+}
+
+function parseHouseSystem(stdout: string): 'P' | 'W' | null {
+  const match = stdout.match(/(Placidus|Whole)\s+Houses/i);
+  if (!match) return null;
+  if (match[1].toLowerCase() === 'whole') return 'W';
+  return 'P';
+}
+
+function parseHouseCusps(stdout: string): number[] {
+  const cusps: number[] = new Array(12).fill(Number.NaN);
+  const signOrder = [
+    'Ari',
+    'Tau',
+    'Gem',
+    'Can',
+    'Leo',
+    'Vir',
+    'Lib',
+    'Sco',
+    'Sag',
+    'Cap',
+    'Aqu',
+    'Pis',
+  ];
+
+  const lines = stdout.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/House cusp\s+(\d+):\s+([0-9]{1,2})([A-Za-z]{3})([0-9]{1,2})/i);
+    if (!m) continue;
+    const cuspIndex = Number(m[1]);
+    if (cuspIndex < 1 || cuspIndex > 12) continue;
+    const degree = Number(m[2]);
+    const signIndex = signOrder.indexOf(m[3]);
+    const minutes = Number(m[4]);
+    if (signIndex < 0) continue;
+    cusps[cuspIndex - 1] = signIndex * 30 + degree + minutes / 60;
+  }
+
+  return cusps;
+}
+
+export function getAstrologPositions(
+  isoUtc: string,
+  probe: AstrologProbe
+): { ok: boolean; positions?: NormalizedBody[]; reason?: string } {
+  const chart = runAstrologChart(isoUtc, probe);
+  if (!chart.ok || !chart.stdout) {
+    return { ok: false, reason: chart.reason };
+  }
+
+  const parsed = parsePositionsFromStdout(chart.stdout);
+  if (parsed.length >= 5) {
+    return { ok: true, positions: parsed };
+  }
+
+  return {
+    ok: false,
+    reason: 'Astrolog is installed but output parsing/flags did not yield usable position rows',
+  };
+}
+
+export function getAstrologHouses(
+  input: {
+    isoUtc: string;
+    latitude: number;
+    longitude: number;
+    houseSystem: 'P' | 'W';
+  },
+  probe: AstrologProbe
+): { ok: boolean; houses?: NormalizedHouseResult; reason?: string } {
+  const chart = runAstrologChart(input.isoUtc, probe, {
+    latitude: input.latitude,
+    longitude: input.longitude,
+    houseSystem: input.houseSystem,
+  });
+  if (!chart.ok || !chart.stdout) {
+    return { ok: false, reason: chart.reason };
+  }
+
+  const cusps = parseHouseCusps(chart.stdout);
+  if (cusps.some((c) => !Number.isFinite(c))) {
+    return { ok: false, reason: 'Could not parse all 12 house cusps from Astrolog output' };
+  }
+
+  const system = parseHouseSystem(chart.stdout) ?? input.houseSystem;
+  return {
+    ok: true,
+    houses: {
+      system,
+      cusps,
+      // Astrolog textual chart output doesn't expose explicit ASC/MC values;
+      // use cusp 1/10 proxies for parity sanity.
+      ascendant: cusps[0],
+      mc: cusps[9],
+    },
+  };
+}

package/tests/validation/adapters/internal.ts

@@ -0,0 +1,184 @@
+import { EclipseCalculator } from '../../../src/eclipses.js';
+import { EphemerisCalculator } from '../../../src/ephemeris.js';
+import { HouseCalculator } from '../../../src/houses.js';
+import { RiseSetCalculator } from '../../../src/riseset.js';
+import { TransitCalculator } from '../../../src/transits.js';
+import type { PlanetPosition, Transit } from '../../../src/types.js';
+import type {
+  NormalizedBody,
+  NormalizedEclipse,
+  NormalizedHouseResult,
+  NormalizedRiseSet,
+  NormalizedRoot,
+  NormalizedTransit,
+} from '../utils/fixtureTypes.js';
+
+export class InternalValidationAdapter {
+  readonly ephem: EphemerisCalculator;
+  readonly houseCalc: HouseCalculator;
+  readonly transitCalc: TransitCalculator;
+  readonly riseSetCalc: RiseSetCalculator;
+  readonly eclipseCalc: EclipseCalculator;
+
+  private constructor(ephem: EphemerisCalculator) {
+    this.ephem = ephem;
+    this.houseCalc = new HouseCalculator(ephem);
+    this.transitCalc = new TransitCalculator(ephem);
+    this.riseSetCalc = new RiseSetCalculator(ephem);
+    this.eclipseCalc = new EclipseCalculator(ephem);
+  }
+
+  static async create(): Promise<InternalValidationAdapter> {
+    const ephem = new EphemerisCalculator();
+    await ephem.init();
+    return new InternalValidationAdapter(ephem);
+  }
+
+  getPositions(isoUtc: string, planetIds: number[]): NormalizedBody[] {
+    const jd = this.ephem.dateToJulianDay(new Date(isoUtc));
+    return this.ephem.getAllPlanets(jd, planetIds).map((p) => this.normalizeBody(p));
+  }
+
+  getHouseResult(
+    isoUtc: string,
+    latitude: number,
+    longitude: number,
+    houseSystem: string
+  ): NormalizedHouseResult {
+    const jd = this.ephem.dateToJulianDay(new Date(isoUtc));
+    const result = this.houseCalc.calculateHouses(jd, latitude, longitude, houseSystem);
+    return {
+      system: result.system,
+      ascendant: result.ascendant,
+      mc: result.mc,
+      cusps: result.cusps.slice(1),
+    };
+  }
+
+  getTransitsFromOffsets(input: {
+    currentIsoUtc: string;
+    transitingPlanetId: number;
+    natalPlanetId: number;
+    natalOffsetDegrees: number;
+  }): NormalizedTransit[] {
+    const currentJD = this.ephem.dateToJulianDay(new Date(input.currentIsoUtc));
+    const transiting = this.ephem.getPlanetPosition(input.transitingPlanetId, currentJD);
+
+    const natal: PlanetPosition = {
+      planetId: input.natalPlanetId,
+      planet: this.ephem.getPlanetPosition(input.natalPlanetId, currentJD).planet,
+      longitude: (transiting.longitude + input.natalOffsetDegrees + 360) % 360,
+      latitude: 0,
+      distance: 1,
+      speed: 1,
+      sign: 'Aries',
+      degree: 0,
+      isRetrograde: false,
+    };
+
+    return this.transitCalc
+      .findTransits([transiting], [natal], currentJD)
+      .map((t) => this.normalizeTransit(t));
+  }
+
+  getTransits(
+    transitingPlanets: PlanetPosition[],
+    natalPlanets: PlanetPosition[],
+    currentIsoUtc: string
+  ): NormalizedTransit[] {
+    const currentJD = this.ephem.dateToJulianDay(new Date(currentIsoUtc));
+    return this.transitCalc
+      .findTransits(transitingPlanets, natalPlanets, currentJD)
+      .map((t) => this.normalizeTransit(t));
+  }
+
+  getExactRoots(
+    planetId: number,
+    targetLongitude: number,
+    startIsoUtc: string,
+    endIsoUtc: string
+  ): NormalizedRoot[] {
+    const startJD = this.ephem.dateToJulianDay(new Date(startIsoUtc));
+    const endJD = this.ephem.dateToJulianDay(new Date(endIsoUtc));
+    const roots = this.ephem.findExactTransitTimes(planetId, targetLongitude, startJD, endJD);
+    return roots.map((jd) => ({ jd, isoUtc: this.ephem.julianDayToDate(jd).toISOString() }));
+  }
+
+  getRiseSet(
+    isoUtc: string,
+    planetId: number,
+    latitude: number,
+    longitude: number
+  ): NormalizedRiseSet {
+    const jd = this.ephem.dateToJulianDay(new Date(isoUtc));
+    const result = this.riseSetCalc.calculateRiseSet(jd, planetId, latitude, longitude);
+    return {
+      body: result.planet,
+      rise: result.rise?.toISOString(),
+      set: result.set?.toISOString(),
+      upperMeridianTransit: result.upperMeridianTransit?.toISOString(),
+      lowerMeridianTransit: result.lowerMeridianTransit?.toISOString(),
+    };
+  }
+
+  getNextEclipse(startIsoUtc: string, type: 'solar' | 'lunar'): NormalizedEclipse | null {
+    const startJD = this.ephem.dateToJulianDay(new Date(startIsoUtc));
+    const result =
+      type === 'solar'
+        ? this.eclipseCalc.findNextSolarEclipse(startJD)
+        : this.eclipseCalc.findNextLunarEclipse(startJD);
+
+    if (!result) {
+      return null;
+    }
+
+    return {
+      type: result.type,
+      eclipseType: result.eclipseType,
+      maxTime: result.maxTime.toISOString(),
+    };
+  }
+
+  canComputeRiseSet(): boolean {
+    try {
+      const probeJd = this.ephem.dateToJulianDay(new Date('2024-03-26T12:00:00Z'));
+      this.riseSetCalc.calculateRiseSet(probeJd, 0, 34.0522, -118.2437);
+      return true;
+    } catch (error) {
+      return !String(error).includes('is not a function');
+    }
+  }
+
+  canComputeEclipses(): boolean {
+    try {
+      const probeJd = this.ephem.dateToJulianDay(new Date('2024-03-26T00:00:00Z'));
+      this.ephem.eph?.sol_eclipse_when_glob(probeJd, 0, 0, false);
+      this.ephem.eph?.lun_eclipse_when(probeJd, 0, 0, false);
+      return true;
+    } catch (error) {
+      return !String(error).includes('is not a function');
+    }
+  }
+
+  normalizeBody(p: PlanetPosition): NormalizedBody {
+    return {
+      body: p.planet,
+      longitude: p.longitude,
+      latitude: p.latitude,
+      speed: p.speed,
+      retrograde: p.isRetrograde,
+    };
+  }
+
+  normalizeTransit(t: Transit): NormalizedTransit {
+    return {
+      transitingPlanet: t.transitingPlanet,
+      natalPlanet: t.natalPlanet,
+      aspect: t.aspect,
+      orb: t.orb,
+      exactTime: t.exactTime?.toISOString(),
+      exactTimeStatus: t.exactTimeStatus,
+      isApplying: t.isApplying,
+    };
+  }
+}

package/tests/validation/compare/eclipses.ts

@@ -0,0 +1,47 @@
+import type { NormalizedEclipse } from '../utils/fixtureTypes.js';
+import type { ValidationReport } from '../utils/report.js';
+import { minutesBetweenIso, TOLERANCES } from '../utils/tolerances.js';
+
+export function compareEclipses(
+  fixtureName: string,
+  expected: NormalizedEclipse,
+  actual: NormalizedEclipse,
+  report: ValidationReport
+): void {
+  if (expected.type !== actual.type) {
+    report.addHard({
+      fixture: fixtureName,
+      subsystem: 'eclipses',
+      expected: expected.type,
+      actual: actual.type,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Eclipse type mismatch',
+    });
+  }
+
+  if (expected.eclipseType !== actual.eclipseType) {
+    report.addHard({
+      fixture: fixtureName,
+      subsystem: 'eclipses',
+      expected: expected.eclipseType,
+      actual: actual.eclipseType,
+      delta: null,
+      tolerance: 'exact',
+      message: 'Eclipse subtype mismatch',
+    });
+  }
+
+  const delta = minutesBetweenIso(expected.maxTime, actual.maxTime);
+  if (delta > TOLERANCES.eclipseMinutes) {
+    report.addHard({
+      fixture: fixtureName,
+      subsystem: 'eclipses',
+      expected: expected.maxTime,
+      actual: actual.maxTime,
+      delta,
+      tolerance: TOLERANCES.eclipseMinutes,
+      message: 'Eclipse maxTime delta exceeds tolerance',
+    });
+  }
+}

package/tests/validation/compare/houses.ts

@@ -0,0 +1,76 @@
+import type { NormalizedHouseResult } from '../utils/fixtureTypes.js';
+import type { ValidationReport } from '../utils/report.js';
+import { TOLERANCES } from '../utils/tolerances.js';
+
+export function compareHouses(
+  fixtureName: string,
+  expected: NormalizedHouseResult,
+  actual: NormalizedHouseResult,
+  report: ValidationReport
+): void {
+  if (expected.system !== actual.system) {
+    report.addHard({
+      fixture: fixtureName,
+      subsystem: 'houses',
+      expected: expected.system,
+      actual: actual.system,
+      delta: null,
+      tolerance: 'exact',
+      message: 'House system mismatch (including fallback system)',
+    });
+  }
+
+  const ascDelta = Math.abs(expected.ascendant - actual.ascendant);
+  if (ascDelta > TOLERANCES.houseDeg) {
+    report.addHard({
+      fixture: fixtureName,
+      subsystem: 'houses',
+      expected: expected.ascendant,
+      actual: actual.ascendant,
+      delta: ascDelta,
+      tolerance: TOLERANCES.houseDeg,
+      message: 'Ascendant delta exceeds tolerance',
+    });
+  }
+
+  const mcDelta = Math.abs(expected.mc - actual.mc);
+  if (mcDelta > TOLERANCES.houseDeg) {
+    report.addHard({
+      fixture: fixtureName,
+      subsystem: 'houses',
+      expected: expected.mc,
+      actual: actual.mc,
+      delta: mcDelta,
+      tolerance: TOLERANCES.houseDeg,
+      message: 'MC delta exceeds tolerance',
+    });
+  }
+
+  if (expected.cusps.length !== actual.cusps.length) {
+    report.addHard({
+      fixture: fixtureName,
+      subsystem: 'houses',
+      expected: expected.cusps.length,
+      actual: actual.cusps.length,
+      delta: actual.cusps.length - expected.cusps.length,
+      tolerance: 0,
+      message: 'Cusp count mismatch',
+    });
+    return;
+  }
+
+  for (let i = 0; i < expected.cusps.length; i++) {
+    const delta = Math.abs(expected.cusps[i] - actual.cusps[i]);
+    if (delta > TOLERANCES.houseDeg) {
+      report.addHard({
+        fixture: fixtureName,
+        subsystem: 'houses',
+        expected: expected.cusps[i],
+        actual: actual.cusps[i],
+        delta,
+        tolerance: TOLERANCES.houseDeg,
+        message: `House cusp ${i + 1} delta exceeds tolerance`,
+      });
+    }
+  }
+}