h4x0r/stem-branch

Purpose and entry points

stem-branch is a zero-dependency TypeScript library for Chinese calendrical, astronomical, astrological, and divination computation, with a Rust solar-ephemeris port. The public library boundary is src/index.ts; package/TS build settings are package.json and tsup.config.ts. A command-line interface begins at src/cli.ts and delegates formatted output to renderers under src/cli/.

Astronomical computation core

Solar, lunar, and time-scale calculations provide the numerical foundation for higher-level systems. Solar longitude and terms are centered on src/solar-longitude.ts, src/solar-terms.ts, and the VSOP87D Earth series in src/vsop87d-earth.ts. Lunar position, phases, and conjunctions are handled through src/moon/moon.ts, src/new-moon.ts, and src/lunisolar-calendar.ts. Julian-date conversion and ΔT establish the UTC/TT time boundary in src/julian-day.ts and src/delta-t.ts.

Ephemerides and planetary layer

The library computes geocentric planetary positions and related observational data rather than calling a runtime ephemeris service. The integration layer is src/planets/planets.ts, using geocentric transformations in src/planets/geocentric.ts and planet-specific VSOP/other models under src/planets/. Eclipse lookup/calculation is separated in src/eclipses.ts and src/eclipse-data.ts. Generated/reference coefficient data originates from local sources such as data/VSOP87D.ear and generation scripts in data/.

Calendar and Chinese metaphysics layer

Lunisolar dates and solar-term boundaries feed stem-branch and Four Pillars derivation. Core cycle primitives live in src/stems.ts, src/branches.ts, and src/stem-branch.ts; pillar computation is in src/four-pillars.ts. The aggregate daily API, src/daily-almanac.ts, composes pillars, lunar date, fitness, flags, Six Ren, flying stars, eclipses, and element analysis. Almanac-specific rules remain modular, including src/almanac-flags.ts, src/day-fitness.ts, and src/flying-stars.ts.

Chart and divination subsystems

Independent domain modules consume the shared calendar/astronomy layer rather than each other’s presentation code. Six Ren and Qi Men are rooted in src/six-ren.ts and src/qimen-chuanren.ts. Western/tropical and sidereal computations are in src/tropical-astrology.ts and src/sidereal-astrology.ts. Seven Governors is a substantial bounded subsystem: src/seven-governors/chart.ts orchestrates bodies, ascendant, mansions, palaces, aspects, and dignities from modules under src/seven-governors/.

User-facing surfaces

The CLI dispatches commands from src/cli.ts; specialized renderers, such as src/cli/render-almanac.ts and src/cli/render-seven-governors.ts, are presentation-only consumers of library APIs. A separate Next.js Almanac UI resides under almanac/src/app/page.tsx, with its main client presentation in almanac/src/components/almanac-view.tsx; formatting/export are isolated in almanac/src/lib/format-almanac.ts and almanac/src/lib/export-html.ts. Documentation is a VitePress site configured by docs/.vitepress/config.ts.

Rust parity and validation boundary

rust/ is an independent native implementation of the solar ephemeris core, exposed through rust/src/lib.rs and implemented primarily in rust/src/vsop87d_earth.rs, rust/src/solar_terms.rs, and rust/src/moon.rs. It has no JavaScript dependency at runtime. TypeScript-generated coefficient tables are represented in Rust data modules such as rust/src/elpmpp02_data.rs. JPL DE441, Hong Kong Observatory, Swiss Ephemeris, and other datasets are validation/reference inputs represented by local fixtures and generation scripts; they are not required production services.