mirror of
https://github.com/acamarata/qibla.git
synced 2026-07-03 20:30:41 +00:00
30a74c12dc
- Flatten exports map to ADR-015 standard - Add coverage script (c8) - Migrate CI to corepack enable
57 lines
2.3 KiB
Markdown
57 lines
2.3 KiB
Markdown
# qibla — PRI (Per-Repo Instructions)
|
|
|
|
**Cascade:** GCI → ASI → PPI (`/Volumes/X9/Sites/acamarata/.claude/CLAUDE.md`) → **PRI (this file)**
|
|
|
|
## Repo Overview
|
|
|
|
**Package:** `@acamarata/qibla@1.0.0`
|
|
**Registry:** npm (public, `access: public`)
|
|
**Scoped name:** `@acamarata/qibla` — note the `@acamarata/` scope prefix in all install/publish commands
|
|
**Language:** TypeScript
|
|
**Runtime deps:** zero — pure math, no external dependencies
|
|
**Build:** tsup, dual CJS (`index.cjs`) + ESM (`index.mjs`) output
|
|
**Dart counterpart:** `qibla@1.0.0` on pub.dev (publisher: ariccamarata.com), repo: `qibla-dart`
|
|
|
|
## What It Does
|
|
|
|
Qibla direction, great-circle path, and haversine distance toward the Ka'bah (Mecca).
|
|
|
|
Exported functions:
|
|
- `qiblaAngle(lat, lng)` — initial bearing to Ka'bah, clockwise from north (0-360)
|
|
- `compassDir(bearing)` — 8-point compass abbreviation (N, NE, E, SE, S, SW, W, NW)
|
|
- `compassName(bearing)` — full compass name (North, Northeast, etc.)
|
|
- `qiblaGreatCircle(lat, lng, steps?)` — Slerp waypoints along the great-circle path to Ka'bah
|
|
- `distanceKm(lat1, lng1, lat2, lng2)` — haversine distance in km
|
|
|
|
Exported constants:
|
|
- `KAABA_LAT = 21.422511`
|
|
- `KAABA_LNG = 39.826150`
|
|
- `EARTH_RADIUS_KM = 6371`
|
|
|
|
## Project Rules (inherits from acamarata PPI)
|
|
|
|
This repo follows the full acamarata npm package standard. Key points:
|
|
|
|
- pnpm only — `pnpm install`, `pnpm test`, `pnpm run build`
|
|
- No AI attribution anywhere in tracked files
|
|
- Writing quality: no em dashes as connectors, no AI tells, academic technical tone
|
|
- Publishing requires explicit user approval
|
|
- Version bumps require CHANGELOG.md update first
|
|
|
|
## Dart Counterpart Relationship
|
|
|
|
The JS and Dart packages implement the same algorithm. Keep them in sync on:
|
|
- Ka'bah coordinate constants (KAABA_LAT / KAABA_LNG)
|
|
- Algorithm correctness (forward azimuth formula, haversine, Slerp)
|
|
- API surface parity (functions and constants match across both)
|
|
|
|
When updating the JS package in a way that affects algorithm or constants, note whether the Dart package (`qibla-dart`) needs the same fix.
|
|
|
|
## npm Publish Command
|
|
|
|
```bash
|
|
npm publish --access public
|
|
```
|
|
|
|
The `@acamarata/` scope requires `--access public` on first publish. Already set in `publishConfig` but include it explicitly to avoid accidental private publish.
|
|
|