panchanga 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * src/types.ts — the observance-rule GRAMMAR (the engine's keystone).
+ *
+ * This module is the CANONICAL home for the festival rule algebra. It declares
+ * the `Observance` union (how a festival's civil date is determined), the
+ * `FestivalRule` record (the authored datum), and the `FestivalResult` output.
+ *
+ * The grammar is taken verbatim from the plan
+ * (`docs/superpowers/plans/2026-06-23-festivals-page-v2.md`, "Rule grammar (the
+ * keystone)"). It is the widened algebra derived from the verified spec table —
+ * the v1 grammar could not express the festivals it named.
+ *
+ * SINGLE-DEFINITION POLICY
+ * ────────────────────────
+ * `Kala` is defined here (it names kāla windows AND the moonrise/sunset/ingress
+ * instants observances key on). `GeoLocation` lives in `time.ts` (next to the
+ * rise/set machinery that consumes it) and is RE-EXPORTED here so callers can
+ * import the whole grammar from one place. There is exactly one definition of
+ * each — no divergent duplicates.
+ */
+export type { GeoLocation } from "./time.js";
+/**
+ * A named time anchor. The first nine resolve to a kāla *window* (`{start,end}`)
+ * via the corresponding `time.ts` function and are usable as a `tithi-pervades`
+ * window; the last three (`moonrise`, `sunset`, `sankrantiPunyaKala`) are
+ * instants used by the non-`tithi-pervades` observances.
+ *
+ * Note: `time.ts` exposes `pratahkala` (alias of `sunriseWindow`) for the
+ * `"sunrise"` kāla, and `arunodaya` is the pre-sunrise window (4 ghaṭikās
+ * before sunrise) for aruṇodaya-vyāpinī observances.
+ */
+export type Kala = "sunrise" | "purvahna" | "madhyahna" | "aparahna" | "pradosha" | "nishita" | "pratahkala" | "brahmaMuhurta" | "moonrise" | "sunset" | "arunodaya" | "sankrantiPunyaKala";
+/**
+ * A tithi reference within a paksha: 1..15 (Pratipadā..Pūrṇimā/Amāvāsyā), or a
+ * boundary alias. `"purnima"` ≡ tithi 15 of śukla pakṣa; `"amavasya"` ≡ tithi
+ * 15 of kṛṣṇa pakṣa.
+ */
+export type TithiRef = number | "purnima" | "amavasya";
+/** Lunar fortnight. */
+export type Paksha = "shukla" | "krishna";
+/**
+ * The five ways a festival date resolves. The discriminant is `kind`.
+ */
+export type Observance = 
+/**
+ * Most lunar festivals: the tithi must PERVADE a kāla window on the chosen
+ * civil day. Among the (usually two) candidate days the tithi touches, a
+ * `precedence` policy selects the winner.
+ *
+ *  • "max-window-fraction" — the day whose tithi interval covers the larger
+ *    fraction of that day's `window` wins (the vyāpti/pervasion rule).
+ *  • "udaya" — the day on which the tithi is present at the window's start
+ *    (sunrise-prevailing).
+ *  • "first" / "second" — fixed: the earlier / later candidate.
+ *
+ * `nakshatra` (e.g. Janmāṣṭamī's Rohiṇī): `"required"` filters out days where
+ * the nakshatra is absent; `"preferred"` is only a tie-break.
+ * `avoidKarana: "vishti"` (Bhadra — Holikā, Rakhi): the Bhadra overlap is
+ * recorded, and (via `bhadraSplit`) its Mukha/Pucchā windows and Vāsa are
+ * surfaced in the result instants.
+ * `fallback` applies when the tithi pervades the window on NO candidate day:
+ *  • previous-day / next-day — shift one civil day either way;
+ *  • nearest-window — keep the candidate day whose kāla window is closest to
+ *    the tithi (for niśīta festivals where the tithi straddles two midnights
+ *    without covering either, e.g. Masik Śivarātri at far-western longitudes).
+ */
+{
+    kind: "tithi-pervades";
+    paksha: Paksha;
+    tithi: TithiRef;
+    window: Kala;
+    precedence: "max-window-fraction" | "udaya" | "first" | "second";
+    nakshatra?: {
+        name: string;
+        window?: Kala;
+        mode: "required" | "preferred";
+    };
+    avoidKarana?: "vishti";
+    fallback?: "previous-day" | "next-day" | "nearest-window";
+    /**
+     * Adhika-māsa policy in a leap-month year. Default = the nija (regular)
+     * lunation. `"prefer-adhika"` observes in the ADHIKA lunation of the named
+     * month when one exists that year, else falls back to nija — for festivals
+     * Drik places in the leap month (e.g. Ganga Dussehra in Adhika Jyeṣṭha).
+     */
+    adhika?: "prefer-adhika";
+}
+/** Pure solar: the Sun's sidereal ingress into a rāśi. */
+ | {
+    kind: "solar-ingress";
+    rashi: number;
+    punyaKala?: "after-moment-to-sunset" | "around-moment";
+}
+/** Moon-sighting festivals: tithi live at moonrise (Karva Chauth, Sankashti). */
+ | {
+    kind: "moonrise";
+    paksha: Paksha;
+    tithi: TithiRef;
+}
+/** Sūrya-arghya festivals: tithi at sunset, and next sunrise (Chhath). */
+ | {
+    kind: "solar-arghya";
+    paksha: Paksha;
+    tithi: TithiRef;
+}
+/** Offset from another festival (Holi = Holikā +1). */
+ | {
+    kind: "derived";
+    from: string;
+    offsetDays: number;
+}
+/**
+ * Nakṣatra-anchored solar-month festival: the day the Moon occupies
+ * `nakshatra` (at sunrise) while the Sun is in rāśi `solarRashi`. E.g. Onam =
+ * Śravaṇa (Thiruvoṇam) nakṣatra with the Sun in Siṃha.
+ */
+ | {
+    kind: "nakshatra-pervades";
+    nakshatra: string;
+    solarRashi: number;
+}
+/**
+ * Weekday-anchored relative to another festival: the latest `weekday`
+ * (0 = Sunday … 6 = Saturday) strictly before the `from` festival's date.
+ * E.g. Varalakṣmī Vrat = the Friday before Śrāvaṇa Pūrṇimā.
+ */
+ | {
+    kind: "weekday-relative";
+    from: string;
+    weekday: number;
+};
+export type FestivalRule = {
+    /** Stable slug. */
+    id: string;
+    displayName: string;
+    /**
+     * Pūrṇimānta month label; the amānta label is derived at output time.
+     * OPTIONAL: solar-ingress and derived rules don't key on a lunar month, so
+     * they omit it rather than carry an empty-string placeholder. For lunar-tithi
+     * / moonrise / solar-arghya rules it is required to anchor the lunation.
+     */
+    month?: {
+        purnimanta: string;
+    };
+    category: "lunar-tithi" | "solar" | "moonrise" | "derived" | "nakshatra";
+    /** True if this is part of the §4b extended set. */
+    extended?: boolean;
+    observance: Observance;
+    /** Default "smarta". */
+    sampradaya?: "smarta" | "vaishnava";
+    meta?: {
+        deity?: string;
+        note?: string;
+    };
+};
+export type FestivalResult = {
+    id: string;
+    /** Local civil date (YYYY-MM-DD) in `loc` tz. Empty string when unresolved. */
+    date: string;
+    /** Key instants (tithi start/end, window start/end, moment, …) as ISO UTC. */
+    instants: Record<string, string>;
+    monthLabel: {
+        purnimanta: string;
+        amanta: string;
+    };
+    /** Never silently drop: any miss is explained here. */
+    diagnostics: string[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAM7C;;;;;;;;;GASG;AACH,MAAM,MAAM,IAAI,GACZ,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,GAC9D,SAAS,GAAG,YAAY,GAAG,eAAe,GAC1C,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,oBAAoB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAEvD,uBAAuB;AACvB,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAM1C;;GAEG;AACH,MAAM,MAAM,UAAU;AACpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC;IACtE,UAAU,EAAE,qBAAqB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;IACjE,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAAA;KAAE,CAAC;IAC5E,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,UAAU,GAAG,gBAAgB,CAAC;IAC1D;;;;;OAKG;IACH,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE;AAC9B,0DAA0D;GACxD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAA0B;IAC9D,SAAS,CAAC,EAAE,wBAAwB,GAAG,eAAe,CAAA;CAAE;AAC5D,iFAAiF;GAC/E;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE;AACvD,0EAA0E;GACxE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE;AAC3D,uDAAuD;GACrD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE;AACvD;;;;GAIG;GACD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE;AACvE;;;;GAIG;GACD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAMhE,MAAM,MAAM,YAAY,GAAG;IACzB,mBAAmB;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,QAAQ,EAAE,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACzE,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,wBAAwB;IACxB,UAAU,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IACpC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C,CAAC;AAMF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,uDAAuD;IACvD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC"}

package/dist/types.js

@@ -0,0 +1,22 @@
+/**
+ * src/types.ts — the observance-rule GRAMMAR (the engine's keystone).
+ *
+ * This module is the CANONICAL home for the festival rule algebra. It declares
+ * the `Observance` union (how a festival's civil date is determined), the
+ * `FestivalRule` record (the authored datum), and the `FestivalResult` output.
+ *
+ * The grammar is taken verbatim from the plan
+ * (`docs/superpowers/plans/2026-06-23-festivals-page-v2.md`, "Rule grammar (the
+ * keystone)"). It is the widened algebra derived from the verified spec table —
+ * the v1 grammar could not express the festivals it named.
+ *
+ * SINGLE-DEFINITION POLICY
+ * ────────────────────────
+ * `Kala` is defined here (it names kāla windows AND the moonrise/sunset/ingress
+ * instants observances key on). `GeoLocation` lives in `time.ts` (next to the
+ * rise/set machinery that consumes it) and is RE-EXPORTED here so callers can
+ * import the whole grammar from one place. There is exactly one definition of
+ * each — no divergent duplicates.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "panchanga",
+  "version": "0.1.1",
+  "description": "Drik Panchanga (Smārta, pūrṇimānta) engine for HSNA — computes tithi, vara, nakshatra, yoga, karana, festivals and eclipses from astronomical first principles.",
+  "license": "MIT",
+  "author": "Hindu Society of North America",
+  "homepage": "https://github.com/SODIYAL/panchanga#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SODIYAL/panchanga.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SODIYAL/panchanga/issues"
+  },
+  "keywords": [
+    "panchang",
+    "panchanga",
+    "hindu-calendar",
+    "tithi",
+    "nakshatra",
+    "vedic",
+    "jyotish",
+    "drik-panchang",
+    "festivals",
+    "ayanamsha",
+    "ephemeris"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "dependencies": {
+    "astronomy-engine": "^2"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}