panchanga 0.1.1

package/dist/festivals.d.ts

@@ -0,0 +1,145 @@
+/**
+ * src/festivals.ts — the observance-rule EVALUATOR.
+ *
+ * Two responsibilities:
+ *
+ *  1. `selectDayByPervasion` — a PURE, independently-testable selection
+ *     function. Given a set of candidate civil days (each with its tithi
+ *     interval ∩ the day's kāla window, plus optional nakshatra / Bhadra
+ *     facts), it applies the precedence policy, the nakshatra filter/tie-break,
+ *     and records Bhadra overlap. No ephemeris, no I/O — the keystone logic the
+ *     constructed-case tests target.
+ *
+ *  2. `computeFestival` / `computeFestivals` — resolve each `Observance.kind`
+ *     to a civil date using the real astronomy modules (`time.ts`,
+ *     `elements.ts`). These build the candidate set for `tithi-pervades` and
+ *     feed it to `selectDayByPervasion`; the other kinds resolve directly.
+ *
+ * NEVER SILENTLY DROP: a rule that yields no date still returns a
+ * `FestivalResult` (empty `date`) carrying a diagnostic, plus a top-level
+ * diagnostic from `computeFestivals`.
+ *
+ * SCOPE: this is the MECHANISM (Task 5a). The per-festival rule DATA
+ * (`src/rules.ts`) and the Drik-Panchang conformance gate are Task 5b/Phase 4.
+ */
+import type { FestivalRule, FestivalResult, GeoLocation } from "./types.js";
+/** One candidate civil day for the pervasion contest. */
+export interface PervasionCandidate {
+    /** The civil day (a UTC instant inside that local day; identity carrier). */
+    day: Date;
+    /** The festival tithi's interval (UTC). */
+    tithiInterval: {
+        start: Date;
+        end: Date;
+    };
+    /** The day's relevant kāla window (UTC). */
+    window: {
+        start: Date;
+        end: Date;
+    };
+    /**
+     * Whether the required/preferred nakshatra is satisfied on this day.
+     * `undefined` when the rule has no nakshatra clause.
+     */
+    nakshatraOk?: boolean;
+    /**
+     * Bhadra (Viṣṭi) overlap with this day's window, when `avoidKarana:"vishti"`.
+     * `null` = checked, none overlaps; `undefined` = not checked.
+     */
+    bhadraOverlap?: {
+        start: Date;
+        end: Date;
+    } | null;
+    /**
+     * Whether this day's kāla window has ANY Bhadra-free portion, when
+     * `avoidKarana:"vishti"`. `false` = Bhadra covers the WHOLE window (the
+     * observance cannot be performed Bhadra-free on this day → disqualified);
+     * `true` = at least part of the window is Bhadra-free; `undefined` = not
+     * checked (rule has no Bhadra clause).
+     */
+    bhadraFreeWindow?: boolean;
+    /**
+     * Whether the festival tithi is live at this civil day's SUNRISE (udaya
+     * tithi). Used by the Bhadra branch to pick the Bhadra-free observance day
+     * when the tithi has already left that day's (evening) window — Drik observes
+     * such Bhadra-excluded Pūrṇimā festivals on the udaya-Pūrṇimā day whose
+     * kāla window is Bhadra-free. `undefined` when not supplied.
+     */
+    tithiAtSunrise?: boolean;
+}
+export type Precedence = "max-window-fraction" | "udaya" | "first" | "second";
+export interface SelectOptions {
+    precedence: Precedence;
+    /** Nakshatra mode, if the rule has a nakshatra clause. */
+    nakshatra?: "required" | "preferred";
+    avoidKarana?: "vishti";
+    fallback?: "previous-day" | "next-day" | "nearest-window";
+}
+export interface SelectResult {
+    /** The winning candidate, or null when none qualifies. */
+    chosen: PervasionCandidate | null;
+    /** Window-coverage fraction of the chosen day (0 when none). */
+    coverageFraction: number;
+    /** The fallback that was triggered because no day pervaded, if any. */
+    fallbackApplied: "previous-day" | "next-day" | "nearest-window" | null;
+    /** Bhadra overlap recorded on the chosen day (avoidKarana:"vishti"). */
+    bhadraOverlap: {
+        start: Date;
+        end: Date;
+    } | null;
+    diagnostics: string[];
+}
+/**
+ * Select the observance day among `candidates` per the precedence policy.
+ *
+ * Pipeline:
+ *   1. `nakshatra:"required"` → drop candidates with `nakshatraOk === false`.
+ *   1b.`avoidKarana:"vishti"` → DISQUALIFY any candidate whose kāla window is
+ *      wholly covered by Bhadra (Viṣṭi) — i.e. `bhadraFreeWindow === false`.
+ *      The observance must be performed in a Bhadra-FREE window, so a fully
+ *      Bhadra-contaminated day cannot host it. (Holikā Dahan, Rakṣā Bandhan.)
+ *   2. Keep only candidates whose tithi covers a positive fraction of the
+ *      window (i.e. the tithi actually pervades the window at all). A day with
+ *      zero coverage cannot win — that is what triggers `fallback`.
+ *   3. Apply the precedence policy to the survivors:
+ *        • max-window-fraction → largest coverage fraction wins.
+ *        • udaya               → a day present at the window start beats one
+ *                                that is not; among equals, larger fraction.
+ *        • first / second      → earliest / latest survivor by day.
+ *   4. `nakshatra:"preferred"` → on an (near-)exact fraction tie, prefer the
+ *      nakshatra-matching day; never overrides a clear winner.
+ *   5. Record the chosen day's Bhadra overlap (avoidKarana:"vishti").
+ *   6. If no survivor pervades but `avoidKarana:"vishti"` left exactly the
+ *      Bhadra-free candidate(s) standing, choose the Bhadra-free day on which
+ *      the festival tithi is the UDAYA tithi (live at sunrise). This is the
+ *      Drik resolution for Bhadra-excluded Pūrṇimā festivals: when the natural
+ *      pradoṣa/aparāhna-vyāpinī day is Bhadra-contaminated, the observance
+ *      shifts to the (next) udaya-Pūrṇimā day whose window is Bhadra-free, even
+ *      though the tithi has by then left that evening window.
+ *   7. Otherwise, if no survivor, set `fallbackApplied` and explain.
+ *
+ * PURE: depends only on its arguments.
+ */
+export declare function selectDayByPervasion(candidates: PervasionCandidate[], opts: SelectOptions): SelectResult;
+export interface ComputeOptions {
+    /** The rule set to evaluate. (Task 5b supplies the real `rules.ts`.) */
+    rules?: FestivalRule[];
+}
+/**
+ * Compute one festival's result. `resolved` supplies already-computed results
+ * for `derived` rules to reference (their `from` id → FestivalResult).
+ */
+export declare function computeFestival(rule: FestivalRule, year: number, loc: GeoLocation, resolved?: Map<string, FestivalResult>): FestivalResult;
+/**
+ * Compute all festivals for `(year, loc)`.
+ *
+ * Resolves non-derived rules first, then derived rules (so their references
+ * exist). Orders results ascending by date; undated results sort last.
+ * NEVER silently drops: any undated result carries a diagnostic, and a matching
+ * top-level diagnostic is emitted.
+ */
+export declare function computeFestivals(year: number, loc: GeoLocation, opts?: ComputeOptions): {
+    results: FestivalResult[];
+    diagnostics: string[];
+};
+//# sourceMappingURL=festivals.d.ts.map

package/dist/festivals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"festivals.d.ts","sourceRoot":"","sources":["../src/festivals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EAKZ,MAAM,YAAY,CAAC;AAuCpB,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,GAAG,EAAE,IAAI,CAAC;IACV,2CAA2C;IAC3C,aAAa,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,CAAC;IAC1C,4CAA4C;IAC5C,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAAG,qBAAqB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IACrC,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,UAAU,GAAG,gBAAgB,CAAC;CAC3D;AAED,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,eAAe,EAAE,cAAc,GAAG,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC;IACvE,wEAAwE;IACxE,aAAa,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,kBAAkB,EAAE,EAChC,IAAI,EAAE,aAAa,GAClB,YAAY,CA8Ld;AA+jBD,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,GACrC,cAAc,CAgGhB;AAWD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE,cAAmB,GACxB;IAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAkDtD"}