pray-calc/.github/wiki/Contributing.md

Contributing

Prerequisites

• Node.js 20 or later
• pnpm (enabled via corepack: corepack enable)

Setup

git clone https://github.com/acamarata/pray-calc.git
cd pray-calc
pnpm install

Development

pnpm build          # compile TypeScript
pnpm test           # build + run full test suite (ESM + CJS, 106 tests)
pnpm run typecheck  # type-check without emitting
pnpm run lint       # ESLint
pnpm run format     # Prettier format

Project Structure

src/
  index.ts              main exports
  types.ts              all TypeScript types
  getSolarEphemeris.ts  Jean Meeus Ch. 25 (decl, r, eclLon)
  getMSC.ts             MSC piecewise seasonal model
  getAngles.ts          dynamic angle algorithm (3 layers)
  getAsr.ts             pure-math Asr
  getQiyam.ts           last-third-of-night
  getTimes.ts           raw fractional-hour output
  calcTimes.ts          formatted HH:MM:SS output
  getTimesAll.ts        all-methods batch SPA call
  calcTimesAll.ts       all-methods formatted output
test.mjs               ESM test suite (94 tests)
test-cjs.cjs           CJS subset (12 tests)

Making Changes

1. Algorithm changes: read Dynamic Algorithm and Twilight Physics first.
2. Any new export must have TypeScript types and JSDoc.
3. Tests use node:test. Add tests in test.mjs for new behavior.
4. All 106 tests must pass before submitting.

Timezone Note

The test suite uses explicit UTC offset values, not new Date() local timezone parsing. Keep this pattern when adding tests — CI runs in UTC and tests must pass there.

Pull Requests

• One logical change per PR
• Include tests covering the new behavior
• Update CHANGELOG.md under [Unreleased]
• Do not bump the version number