import type { Bilingual, Deity } from '../types.js'
import type { MantraSlug } from '../mantras/index.js'
import type { PujaSlug } from '../puja/index.js'

// Tīrtha — sacred geography. Finite, canonical pan-Hindu lists of holy sites:
// the 12 Jyotirliṅgas (Śiva), the 51 Śakti Pīṭhas (+ the 18 Aṣṭādaśa Mahā
// subset), the Char Dhām + Chota Char Dhām, the Sapta Purī (seven mokṣa-cities),
// and the seven sacred rivers (sapta nadī). This is **geographic reference**,
// not deity-keyed recitation — a standalone module like `vaar/` (no `Category`
// value, no `getContentForDeity` wiring; reverse lookup via
// `getTirthasForDeity` only).
//
// Content-accuracy posture (researched, cross-checked, shipped provisional —
// the puja/navratri/vaar footing, NOT the hand-typed-from-one-text footing):
//  - Every entry is widely-attested traditional sacred-geography, cross-checked
//    across ≥2 references; provenance lives in `tirtha/SOURCES.md`, never in a
//    user-facing field.
//  - `deity` cross-links the site to the per-deity roster content when an
//    in-scope `Deity` is the presiding form, else `null` (e.g. the river
//    goddesses Ganga/Yamuna/Narmada are not in the 19-deity roster).
//  - The Śakti-Pīṭha bundle (body-part / Śakti / Bhairava) is the module's
//    largest soft spot: the lists vary by source and the Bhairava names are
//    thinly sourced. The whole module ships flagged provisional — see
//    `TIRTHA_REVIEW_PENDING` and SOURCES.md.

/** The canonical list a tīrtha belongs to (the entry discriminator). */
export type TirthaCategory =
  | 'jyotirlinga' // one of the 12 Dvādaśa Jyotirliṅga (Śiva)
  | 'shakti-peetha' // one of the 51 Śakti Pīṭha / 18 Aṣṭādaśa Mahā (Devī)
  | 'char-dham' // one of the four pan-India Char Dhām (Śaṅkarācārya)
  | 'chota-char-dham' // one of the four Uttarakhand Himalayan dhāms
  | 'sapta-puri' // one of the seven mokṣa-giving holy cities
  | 'sacred-river' // one of the seven sacred rivers (sapta nadī)

/**
 * A unified entry across every category — a single shape with a `category`
 * discriminator and category-specific OPTIONAL fields (chosen over a
 * discriminated union so `getAllTirthas()` returns one array type and the data
 * files stay uniform). Which optionals are populated is governed by `category`:
 *  - `jyotirlinga`   → `jyotirlingaNumber`
 *  - `shakti-peetha` → `bodyPart`, `shakti`, `bhairava?`, `isAshtadasha?`
 *  - `char-dham`     → `direction`
 *  - others          → none beyond the base.
 */
export interface TirthaEntry {
  /** Stable kebab-case slug, unique across the whole module ('somnath', 'kamakhya'). */
  id: string
  category: TirthaCategory
  /** Display name of the site. */
  name: Bilingual
  /** Devanagari proper name, where it differs usefully from `name.hi`. */
  nameSanskrit?: string
  /** Town / place. */
  location: Bilingual
  /** Modern Indian state — or country, for the overseas Śakti Pīṭhas. */
  state?: Bilingual
  /**
   * Roster cross-link to per-deity content (aarti/chalisa/…). `null` when the
   * presiding form is not in the 19-deity roster (e.g. the river goddesses).
   */
  deity: Deity | null
  /** One- or two-sentence significance / distinguishing note. */
  significance: Bilingual

  // ── category-specific optionals ──────────────────────────────────────────
  /** 1..12 — position in the Dvādaśa-Jyotirliṅga stotra (jyotirlinga only). */
  jyotirlingaNumber?: number
  /** Cardinal direction the dhām represents — N/W/E/S (char-dham only). */
  direction?: Bilingual
  /** The aṅga of Satī that fell at the site (shakti-peetha only). */
  bodyPart?: Bilingual
  /** The presiding Śakti / Devī name (shakti-peetha only). */
  shakti?: Bilingual
  /** The accompanying Bhairava (Śiva form) — thinly sourced, provisional. */
  bhairava?: Bilingual
  // ── Śakti-Pīṭha tradition membership (shakti-peetha only) ────────────────
  // There is no single canonical Śakti-Pīṭha list — the count runs 51 / 52 /
  // 64 / 108 across different texts, and the named sets only partly overlap. So
  // instead of asserting one "the list", each pīṭha carries which traditions
  // include it. The two genuinely-fixed canonical sets (the 18 Aṣṭādaśa and the
  // 4 Ādi) are firm; `inSati51` / `inAshtottara108` flag the broader, recension-
  // variable enumerations. Every shakti-peetha sets at least one of these.
  /** One of the **18 Aṣṭādaśa Mahā** Śakti Pīṭha (the "Laṅkāyāṃ Śāṅkarī…" stotra). */
  isAshtadasha?: boolean
  /** One of the **4 Ādi** (Chatasraḥ Ādi) Śakti Pīṭha: Kāmākhyā, Kālīghāṭ, Vimalā, Tārā-Tāriṇī. */
  isAdiShaktiPeetha?: boolean
  /** In the widely-published **Sati-aṅga 51** (the body-part list). */
  inSati51?: boolean
  /** In the **Devī Bhāgavata Aṣṭottara-śata (108)** enumeration (identifiable sites only). */
  inAshtottara108?: boolean

  // ── optional cross-links into other modules ──────────────────────────────
  storySlug?: string
  pujaSlug?: PujaSlug
  mantraSlug?: MantraSlug
}

/**
 * A short reference śloka attached to a list (the Dvādaśa-Jyotirliṅga stotra,
 * the Sapta-Purī śloka, the sapta-nadī invocation). `iast` is machine-generated
 * from `devanagari` with sanscript and round-trip-verified — the Geeta/mantra
 * bar (anusvāra normalised to `ṃ`). Asserted in `scripts/audit-verify.cjs`.
 */
export interface TirthaSloka {
  devanagari: string
  iast: string
}