ether-to-astro 1.0.0

package/src/types.ts

@@ -0,0 +1,547 @@
+// Type unions for domain constraints
+export type HouseSystem =
+  | 'P'
+  | 'K'
+  | 'W'
+  | 'E'
+  | 'O'
+  | 'R'
+  | 'C'
+  | 'A'
+  | 'V'
+  | 'X'
+  | 'H'
+  | 'T'
+  | 'B';
+export type SolarEclipseType = 'partial' | 'annular' | 'total' | 'annular-total';
+export type LunarEclipseType = 'penumbral' | 'partial' | 'total';
+export type PlanetName =
+  | 'Sun'
+  | 'Moon'
+  | 'Mercury'
+  | 'Venus'
+  | 'Mars'
+  | 'Jupiter'
+  | 'Saturn'
+  | 'Uranus'
+  | 'Neptune'
+  | 'Pluto'
+  | 'Chiron'
+  | 'North Node (Mean)'
+  | 'North Node (True)'
+  | 'Ceres'
+  | 'Pallas'
+  | 'Juno'
+  | 'Vesta';
+
+/**
+ * Represents a complete natal birth chart with all necessary data for calculations
+ *
+ * @remarks
+ * This is the core data structure for the MCP server. All calculations (transits,
+ * houses, charts) are based on this chart data.
+ *
+ * The julianDay field is calculated during set_natal_chart and should always be
+ * present for charts created in the current session.
+ */
+export interface NatalChart {
+  name: string;
+  /** Birth date and time in local timezone */
+  birthDate: {
+    /** Full year (e.g., 1990) */
+    year: number;
+    /** Month number (1-12) */
+    month: number;
+    /** Day of month (1-31) */
+    day: number;
+    /** Hour in 24-hour format (0-23) */
+    hour: number;
+    /** Minute (0-59) */
+    minute: number;
+    /** Optional seconds for precision */
+    second?: number;
+  };
+  /** Birth location coordinates and timezone */
+  location: {
+    /** Latitude in decimal degrees (-90 to 90, negative for South) */
+    latitude: number;
+    /** Longitude in decimal degrees (-180 to 180, negative for West) */
+    longitude: number;
+    /** IANA timezone identifier (e.g., 'America/New_York') */
+    timezone: string;
+  };
+  /** Optional pre-calculated planet positions (rarely used) */
+  planets?: PlanetPosition[];
+  /**
+   * Cached Julian Day for birth time (UTC)
+   * @remarks
+   * This is calculated during set_natal_chart and should always be present.
+   * Required for chart generation and transit calculations.
+   */
+  julianDay?: number;
+  /**
+   * Preferred house system for calculations
+   * @default 'P' (Placidus)
+   * @remarks
+   * For polar latitudes (>66°), Whole Sign ('W') may be used as fallback.
+   */
+  houseSystem?: HouseSystem;
+  /**
+   * UTC equivalent of birth time
+   * @remarks
+   * Calculated from local birth time using timezone conversion.
+   * Used for Julian Day calculation to avoid timezone bugs.
+   */
+  utcDateTime?: {
+    /** UTC year */
+    year: number;
+    /** UTC month */
+    month: number;
+    /** UTC day */
+    day: number;
+    /** UTC hour */
+    hour: number;
+    /** UTC minute */
+    minute: number;
+    /** Optional UTC seconds */
+    second?: number;
+  };
+}
+
+/**
+ * Represents a planet's position at a specific time
+ *
+ * @remarks
+ * All angular measurements are in degrees. Longitude is along the ecliptic,
+ * latitude is celestial latitude (distance from ecliptic).
+ */
+export interface PlanetPosition {
+  /** Swiss Ephemeris planet ID */
+  planetId: number;
+  /** Planet name (e.g., 'Sun', 'Moon', 'Mercury') */
+  planet: PlanetName;
+  /**
+   * Ecliptic longitude in degrees (0-360)
+   * @remarks
+   * 0° Aries, 90° Cancer, 180° Libra, 270° Capricorn
+   */
+  longitude: number;
+  /**
+   * Celestial latitude in degrees (-90 to 90)
+   * @remarks
+   * Positive is north of ecliptic, negative is south
+   */
+  latitude: number;
+  /** Distance from Earth in AU (Astronomical Units) */
+  distance: number;
+  /**
+   * Daily motion in degrees per day
+   * @remarks
+   * Positive = direct motion, Negative = retrograde
+   */
+  speed: number;
+  /** Zodiac sign the planet is in (e.g., 'Aries', 'Taurus') */
+  sign: string;
+  /** Degree within the sign (0-30) */
+  degree: number;
+  /**
+   * Whether the planet is in retrograde motion
+   * @remarks
+   * Retrograde means the planet appears to move backward from Earth's perspective
+   */
+  isRetrograde: boolean;
+}
+
+/**
+ * Base interface for all transit data
+ *
+ * @remarks
+ * Contains the core transit information shared between internal Transit
+ * and serialized TransitData types.
+ */
+interface BaseTransit {
+  /** Planet currently transiting (moving) */
+  transitingPlanet: PlanetName;
+  /** Planet in the natal chart being aspected */
+  natalPlanet: PlanetName;
+  /** Type of aspect between the planets */
+  aspect: AspectType;
+  /**
+   * Angular distance from exact aspect in degrees
+   * @remarks
+   * Lower values indicate stronger aspects. 0° is exact.
+   */
+  orb: number;
+  /**
+   * Whether the aspect is applying (getting stronger) or separating (weakening)
+   * @remarks
+   * true = applying (getting closer to exact)
+   * false = separating (moving away from exact)
+   */
+  isApplying: boolean;
+  /** Status of exact time lookup for this transit */
+  exactTimeStatus?: 'within_preview' | 'outside_preview' | 'not_found' | 'unsupported_body';
+  /** Current longitude of transiting planet */
+  transitLongitude: number;
+  /** Longitude of natal planet at birth time */
+  natalLongitude: number;
+}
+
+/**
+ * Internal transit representation with Date object
+ *
+ * @remarks
+ * Used for calculations and internal storage. The exactTime is a Date object
+ * for precise time comparisons.
+ */
+export interface Transit extends BaseTransit {
+  /**
+   * Exact time when aspect becomes perfect (0° orb)
+   * @remarks
+   * May be undefined if aspect is not within orb or exact time not calculated
+   */
+  exactTime?: Date;
+}
+
+/**
+ * Serialized transit representation for API responses
+ *
+ * @remarks
+ * Used when sending transit data to MCP clients. The exactTime is an ISO string
+ * for JSON serialization.
+ */
+export interface TransitData extends BaseTransit {
+  /**
+   * Exact time when aspect becomes perfect (0° orb) as ISO string
+   * @remarks
+   * May be undefined if aspect is not within orb or exact time not calculated
+   */
+  exactTime?: string; // ISO timestamp
+}
+
+/**
+ * Response wrapper for transit data
+ *
+ * @remarks
+ * Contains all transits for a specific date along with metadata
+ * about the calculation context.
+ */
+export interface TransitResponse {
+  /** ISO date of the transit calculation (YYYY-MM-DD) */
+  date: string;
+  /** Timezone used for the calculation */
+  timezone: string;
+  /** Array of all active transits for the date */
+  transits: TransitData[];
+}
+
+/**
+ * Response wrapper for planet position data
+ *
+ * @remarks
+ * Contains positions for all requested planets at a specific time.
+ */
+export interface PlanetPositionResponse {
+  /** ISO date of the position calculation (YYYY-MM-DD) */
+  date: string;
+  /** Timezone used for the calculation */
+  timezone: string;
+  /** Array of planet positions */
+  positions: PlanetPosition[];
+}
+
+/**
+ * Types of astrological aspects
+ *
+ * @remarks
+ * Aspects are angular relationships between planets that indicate
+ * specific types of interactions and energies.
+ */
+export type AspectType = 'conjunction' | 'opposition' | 'square' | 'trine' | 'sextile';
+
+/**
+ * Aspect definitions with angles and default orbs
+ *
+ * @remarks
+ * Each aspect has a specific angular relationship and an orb (tolerance).
+ * The orb determines how far from exact the aspect can still be considered active.
+ */
+export const ASPECTS: Array<{ name: AspectType; angle: number; orb: number }> = [
+  { name: 'conjunction', angle: 0, orb: 8 },
+  { name: 'opposition', angle: 180, orb: 8 },
+  { name: 'square', angle: 90, orb: 7 },
+  { name: 'trine', angle: 120, orb: 7 },
+  { name: 'sextile', angle: 60, orb: 6 },
+];
+
+/**
+ * Swiss Ephemeris planet IDs
+ *
+ * @remarks
+ * These are the numeric IDs used by the Swiss Ephemeris library.
+ * The `as const` assertion ensures type safety when referencing planets.
+ */
+export const PLANETS = {
+  /** Sun */
+  SUN: 0,
+  /** Moon */
+  MOON: 1,
+  /** Mercury */
+  MERCURY: 2,
+  /** Venus */
+  VENUS: 3,
+  /** Mars */
+  MARS: 4,
+  /** Jupiter */
+  JUPITER: 5,
+  /** Saturn */
+  SATURN: 6,
+  /** Uranus */
+  URANUS: 7,
+  /** Neptune */
+  NEPTUNE: 8,
+  /** Pluto */
+  PLUTO: 9,
+  /** Mean North Node (average position) */
+  MEAN_NODE: 10,
+  /** True North Node (actual position) */
+  TRUE_NODE: 11,
+  /** Chiron (comet/centaur) */
+  CHIRON: 15,
+  /** Ceres (dwarf planet/asteroid) */
+  CERES: 17,
+  /** Pallas (asteroid) */
+  PALLAS: 18,
+  /** Juno (asteroid) */
+  JUNO: 19,
+  /** Vesta (asteroid) */
+  VESTA: 20,
+} as const;
+
+/**
+ * Type derived from PLANETS constants
+ *
+ * @remarks
+ * Ensures type safety when working with planet IDs.
+ * Only values present in PLANETS are valid PlanetId values.
+ */
+export type PlanetId = (typeof PLANETS)[keyof typeof PLANETS];
+
+/**
+ * Mapping from planet IDs to human-readable names
+ *
+ * @remarks
+ * Used for display purposes and converting between numeric IDs
+ * and string names. Index signature allows number-based lookup.
+ */
+export const PLANET_NAMES: { [key: number]: PlanetName } = {
+  0: 'Sun',
+  1: 'Moon',
+  2: 'Mercury',
+  3: 'Venus',
+  4: 'Mars',
+  5: 'Jupiter',
+  6: 'Saturn',
+  7: 'Uranus',
+  8: 'Neptune',
+  9: 'Pluto',
+  10: 'North Node (Mean)',
+  11: 'North Node (True)',
+  15: 'Chiron',
+  17: 'Ceres',
+  18: 'Pallas',
+  19: 'Juno',
+  20: 'Vesta',
+};
+
+/**
+ * Personal planets (inner planets)
+ *
+ * @remarks
+ * These planets move quickly and represent personal, day-to-day concerns:
+ * - Sun: Identity, vitality
+ * - Moon: Emotions, instincts
+ * - Mercury: Communication, thinking
+ * - Venus: Values, relationships
+ * - Mars: Action, desire
+ */
+export const PERSONAL_PLANETS = [
+  PLANETS.SUN,
+  PLANETS.MOON,
+  PLANETS.MERCURY,
+  PLANETS.VENUS,
+  PLANETS.MARS,
+];
+/**
+ * Slow-moving planets (Jupiter through Pluto)
+ *
+ * @remarks
+ * These planets move slowly and represent generational, societal themes.
+ * Note: Includes Jupiter and Saturn (social planets) plus the true outer planets.
+ */
+export const OUTER_PLANETS = [
+  PLANETS.JUPITER,
+  PLANETS.SATURN,
+  PLANETS.URANUS,
+  PLANETS.NEPTUNE,
+  PLANETS.PLUTO,
+];
+/**
+ * Major asteroids
+ *
+ * @remarks
+ * The four main asteroids used in astrology, representing feminine archetypes:
+ * - Ceres: Nurturing, agriculture
+ * - Pallas: Wisdom, strategy
+ * - Juno: Partnership, commitment
+ * - Vesta: Devotion, service
+ */
+export const ASTEROIDS = [
+  PLANETS.CHIRON,
+  PLANETS.CERES,
+  PLANETS.PALLAS,
+  PLANETS.JUNO,
+  PLANETS.VESTA,
+];
+/**
+ * Lunar nodes
+ *
+ * @remarks
+ * The North and South Nodes represent points where the Moon's orbit
+ * crosses the ecliptic. They indicate life path and evolutionary direction.
+ */
+export const NODES = [PLANETS.MEAN_NODE, PLANETS.TRUE_NODE];
+
+/**
+ * Zodiac signs in order
+ *
+ * @remarks
+ * The 12 signs of the tropical zodiac, each spanning 30° of the ecliptic.
+ * Used for determining which sign a planet is in.
+ */
+export const ZODIAC_SIGNS = [
+  'Aries',
+  'Taurus',
+  'Gemini',
+  'Cancer',
+  'Leo',
+  'Virgo',
+  'Libra',
+  'Scorpio',
+  'Sagittarius',
+  'Capricorn',
+  'Aquarius',
+  'Pisces',
+];
+
+/**
+ * House cusps in Swiss Ephemeris 1-based format
+ *
+ * @remarks
+ * - Index 0: Unused (by convention)
+ * - Index 1-12: Houses 1-12
+ * - Length: 13
+ *
+ * The Swiss Ephemeris uses 1-based indexing for house cusps,
+ * with index 0 unused by convention.
+ */
+export type HouseCusps = number[];
+
+/**
+ * Complete house system calculation results
+ *
+ * @remarks
+ * Contains the angles (Ascendant, MC) and all house cusps for a given
+ * time and location. The cusps array follows Swiss Ephemeris 1-based format.
+ */
+export interface HouseData {
+  /**
+   * Ascendant angle in degrees (0-360)
+   * @remarks
+   * The point where the ecliptic crosses the eastern horizon.
+   * Represents the self, identity, and personal appearance.
+   */
+  ascendant: number;
+  /**
+   * Midheaven (Medium Coeli) angle in degrees (0-360)
+   * @remarks
+   * The highest point in the sky at the time of birth.
+   * Represents career, public life, and reputation.
+   */
+  mc: number;
+  /**
+   * House cusps in Swiss 1-based format
+   * @remarks
+   * cusps[1] = House 1, cusps[2] = House 2, ..., cusps[12] = House 12
+   * cusps[0] is unused by convention
+   */
+  cusps: HouseCusps;
+  /**
+   * The house system actually used for calculation
+   * @remarks
+   * May differ from requested system if fallback was used
+   * (e.g., Whole Sign for polar latitudes)
+   */
+  system: HouseSystem;
+}
+
+/**
+ * Rise, set, and meridian transit times for a celestial body
+ *
+ * @remarks
+ * Contains the times when a planet rises above the horizon, sets below it,
+ * and crosses the upper and lower meridians. Times may be undefined for
+ * circumpolar objects (never rise/set) or at extreme latitudes.
+ */
+export interface RiseSetTime {
+  /** Planet name */
+  planet: string;
+  /**
+   * Time when planet rises above eastern horizon
+   * @remarks
+   * Undefined for circumpolar objects (always visible)
+   */
+  rise?: Date;
+  /**
+   * Time when planet sets below western horizon
+   * @remarks
+   * Undefined for circumpolar objects (always visible)
+   */
+  set?: Date;
+  /**
+   * Time when planet crosses upper meridian (highest point)
+   * @remarks
+   * This is the planet's "culmination" or "upper transit"
+   */
+  upperMeridianTransit?: Date;
+  /**
+   * Time when planet crosses lower meridian (lowest point)
+   * @remarks
+   * This is the planet's "lower transit" or "anti-culmination"
+   */
+  lowerMeridianTransit?: Date;
+}
+
+/**
+ * Basic eclipse information
+ *
+ * @remarks
+ * TODO: This should be replaced with a discriminated union for solar vs lunar eclipses
+ * with richer phase timing data. See planning documents for details.
+ */
+export interface EclipseInfo {
+  /** Type of eclipse: 'solar' or 'lunar' */
+  type: 'solar' | 'lunar';
+  /** Date of the eclipse */
+  date: Date;
+  /**
+   * Eclipse classification
+   * @remarks
+   * TODO: Should use constrained union types:
+   * - Solar: 'partial' | 'annular' | 'total' | 'annular-total'
+   * - Lunar: 'penumbral' | 'partial' | 'total'
+   */
+  eclipseType: string;
+  /** Time of maximum eclipse */
+  maxTime: Date;
+}

package/tests/README.md

@@ -0,0 +1,173 @@
+# Astro Test Suite
+
+Comprehensive unit and validation tests for the `e2a` CLI and `e2a-mcp` server, with an 80% global coverage target.
+
+## Test Structure
+
+```
+tests/
+├── unit/                      # Unit tests for runtime and domain modules
+│   ├── astro-service.test.ts  # Service orchestration and tool-facing behavior
+│   ├── cli*.test.ts           # CLI contracts, profiles, error handling
+│   ├── tool-registry.test.ts  # MCP tool spec mapping and execution wrappers
+│   ├── ephemeris/transits/*   # Core astrology math and solver behavior
+│   ├── riseset/eclipses/*     # Event calculators and edge flags
+│   └── charts/houses/*        # Rendering and house-system behavior
+├── helpers/                   # Reusable test helpers/builders
+├── fixtures/                  # Test data and fixtures
+│   ├── bowen-yang-chart.ts    # Bowen Yang's birth chart
+│   └── expected-results.ts    # Known calculation results
+├── setup.ts                   # Test environment setup
+└── validation/                # End-to-end validation harness
+
+Total: 150+ tests
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests with UI
+npm run test:ui
+
+# Run specific test file
+npm test tests/unit/ephemeris.test.ts
+
+# Watch mode
+npm test -- --watch
+```
+
+## Test Data
+
+### Bowen Yang's Birth Chart
+- **Born:** November 6, 1990, 11:30 AM
+- **Location:** Brisbane, Australia (27.4705°S, 153.0260°E)
+- **Timezone:** Australia/Brisbane (UTC+10)
+
+This real-world chart is used throughout the test suite to ensure calculations work with actual astrological data.
+
+## Test Philosophy
+
+### User Story Format
+Tests are written as user stories to make them readable and maintainable:
+
+```typescript
+describe('When an AI asks "What transits is Bowen experiencing today?"', () => {
+  it('should find transits between current planets and natal planets', () => {
+    // Test implementation
+  });
+});
+```
+
+### Coverage Goals
+- **Minimum 80%** across lines, functions, branches, and statements
+- Preserve high-fidelity solver tests while adding deterministic orchestration tests
+- Exclude logging/entrypoint-only modules from coverage gates
+
+### Testing Strategy
+1. **Core math lane:** Real ephemeris/solver behavior (minimal mocking)
+2. **Orchestration lane:** Fast deterministic tests with injected mocks/fakes
+3. **Filesystem/profile lane:** Temp-fs integration style for precedence and parsing
+4. **Validation lane:** Cross-check production outputs with oracle comparators
+
+## Current Status
+
+✅ **Completed:**
+- Unit suites for service, CLI, registry, domain calculators, and profile store
+- Validation harness with subsystem comparators and dense root oracle
+- Deterministic time setup and fixture-driven real-world chart checks
+
+## Known Issues
+
+### Ephemeris in Tests
+The project uses native `sweph` bindings in Node.js:
+- **Setup:** `tests/setup.ts` fixes test time for deterministic output
+- **Data:** tests use real ephemeris logic with local ephemeris files when available
+- **Fallback:** Moshier mode remains available when ephemeris files are missing
+
+### AstroChart Browser Dependencies
+The chart library expects browser-like globals:
+- Use `jsdom` test environment
+- Polyfill `self` in `tests/setup.ts`
+
+## Coverage Reports
+
+After running `npm run test:coverage`, view reports at:
+- **HTML:** `coverage/index.html`
+- **LCOV:** `coverage/lcov.info` (for CI/CD)
+- **JSON:** `coverage/coverage-final.json`
+
+## CI/CD Integration
+
+Tests are designed to run in GitHub Actions:
+```yaml
+- name: Run tests with coverage
+  run: npm run test:coverage
+- name: Upload coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Writing New Tests
+
+### Example Test Structure
+```typescript
+import { describe, it, expect, beforeAll } from 'vitest';
+import { ModuleToTest } from '../../src/module.js';
+import { bowenYangChart } from '../fixtures/bowen-yang-chart.js';
+
+describe('When a user wants to [action]', () => {
+  let instance: ModuleToTest;
+
+  beforeAll(async () => {
+    instance = new ModuleToTest();
+    await instance.init();
+  });
+
+  describe('Given [context]', () => {
+    it('should [expected behavior]', () => {
+      // Arrange
+      const input = bowenYangChart;
+      
+      // Act
+      const result = instance.method(input);
+      
+      // Assert
+      expect(result).toBeDefined();
+      expect(result.property).toBe(expectedValue);
+    });
+  });
+});
+```
+
+### Best Practices
+1. Use descriptive test names that read like sentences
+2. Follow Arrange-Act-Assert pattern
+3. Use Bowen Yang's chart for realistic data
+4. Mock external dependencies (file I/O, network)
+5. Test edge cases (polar regions, retrograde planets, etc.)
+6. Keep tests fast (<30s total runtime)
+
+## Troubleshooting
+
+### Tests Timeout
+Increase timeout in `vitest.config.ts`:
+```typescript
+testTimeout: 30000 // 30 seconds
+```
+
+### Ephemeris Data Missing
+Check that `data/ephemeris` exists or reinstall with `npm install` (runs postinstall downloader).
+
+### Coverage Too Low
+Run with `--coverage` to see which lines aren't covered, then add targeted tests.
+
+## Future Enhancements
+
+- [ ] Thread-level MCP request/response integration tests
+- [ ] CI flake detector pass (repeat-run sampling on key suites)
+- [ ] Additional chart rendering failure-path contract tests