[Bug]: `ImmaculateHeart` is half temporale half sanctorale

[JohnRDOrazio]

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

The liturgical celebration ImmaculateHeart is currently defined in the temporale along with the i18n translations; while the lectionary readings are defined under sanctorale. It is a mobile celebration; the sanctorale generally deals with fixed date celebrations whereas the temporale generally deals with the mobile celebrations, though there are exceptions (i.e. Mary Mother of God is a fixed date celebration but is found in the temporale within the Roman Missal; Immaculate Heart of Mary is a mobile celebration but is found in the sanctorale within the Roman Missal). The reasoning behind placing it under temporale here was probably because it was a mobile celebration rather than a fixed date celebration; however this does not quite align with the Roman Missal.

Expected Behavior

All celebrations should be categorized as they are categorized in the Roman Missal. Therefore it would be expected to define ImmaculateHeart under sanctorale rather than temporale, though this may cause some problems with the schemas (it will not have day and month properties). We will have to think this through. Perhaps rather than categorize celebrations as temporale or sanctorale we should categorize them as mobile or fixed? Or if we keep the temporale and sanctorale distinctions perhaps we need to create sub-type schemas of mobile or fixed within each of these categories?

Steps To Reproduce

No response

Environment

- **OS**:
- **PHP**:

Anything else?

Version

dev (Unstable)

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

_{You can configure auto-planning by selecting labels in the issue_enrichment configuration.}

🔗 Similar Issues

Related Issues

• [Bug]: schemas not enforcing minItems: 1 for litcal payloads #414
• refine solemnities collection #351
• refactor schemas - strtotime property placement #319
• [Feature]: Liturgical Calendar for Vietnam #384

👤 Suggested Assignees

• JohnRDOrazio
• tommai4881

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Implementation Plan

Approach

Move the ImmaculateHeart celebration from temporale to sanctorale to align with Roman Missal categorization, while extending the sanctorale schema to support mobile celebrations that calculate dates relative to Easter.

Observations

This is a PHP-based liturgical calendar system that generates Roman Catholic liturgical calendars. Celebrations are categorized as temporale (seasonal) or sanctorale (saints), with data stored in JSON files (missal definitions, lectionary readings, i18n translations). The CalendarHandler orchestrates calendar generation, loading celebrations from JSON and calculating mobile feast dates relative to Easter. The sanctorale schema currently requires fixed day/month properties, while mobile celebrations exist only in temporale.

Assumptions

Assumption 1: How to handle mobile date specification in sanctorale schema

Options Considered:

• Add a "strtotime" property similar to temporale patterns for flexible date expressions
• Add an "offset_from_easter" property with a specific format (e.g., "P63D")
• Keep mobile date calculations hardcoded in CalendarHandler

Chosen Option: Keep mobile date calculations hardcoded in CalendarHandler

Rationale: This maintains consistency with how all other mobile feasts are calculated (Easter-relative calculations are centralized in CalendarHandler rather than data-driven). For this single mobile sanctorale celebration, the calculation can be moved from the createImmaculateHeart() method to the sanctorale loading logic, where it checks if the event_key is "ImmaculateHeart" and applies the Easter+63 days calculation. This avoids introducing new schema complexity for a single edge case, and keeps the calculation logic centralized where other mobile feast calculations already exist.

Assumption 2: Schema validation approach for conditional properties

Options Considered:

• Use JSON Schema conditional validation (if/then/else)
• Split into separate schemas (one for fixed, one for mobile)
• Make day/month always optional and validate in code

Chosen Option: Use JSON Schema conditional validation (if/then/else)

Rationale: This is the standard JSON Schema approach for conditional requirements, keeps validation in the schema where it belongs, and avoids schema proliferation. Modern JSON Schema validators support this pattern well.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Plan

Phase 1: Extend Sanctorale Schema for Mobile Celebrations

Update the PropriumDeSanctis schema to support both fixed and mobile celebrations while maintaining backward compatibility with existing fixed-date entries.

Add type property and conditional validation

Modify the sanctorale schema to support mobile celebrations

• Update jsondata/schemas/PropriumDeSanctis.json to add optional "type" property referencing CommonDef.json's LitEventType definition
• Implement JSON Schema conditional validation: when type="mobile", day/month are not required; when type="fixed" or absent, day/month are required
• Keep additionalProperties:false to maintain schema strictness
• Add schema examples showing both fixed and mobile celebration formats

🤖 Prompt for AI agents

Extend the PropriumDeSanctis schema to support mobile celebrations with
conditional validation.

In `jsondata/schemas/PropriumDeSanctis.json`:
- Add an optional "type" property that references the LitEventType definition
from CommonDef.json
- Implement JSON Schema conditional validation (if/then/else):
  - When type="mobile": day and month properties are NOT required
  - When type="fixed" or type is absent: day and month properties ARE required
- Maintain additionalProperties:false to preserve schema strictness
- Add schema examples demonstrating both fixed and mobile celebration formats

Phase 2: Migrate ImmaculateHeart Data to Sanctorale

Move ImmaculateHeart celebration definition and translations from temporale to sanctorale, while keeping lectionary readings in their current location.

Task 1: Move celebration definition to sanctorale missal files

Transfer the ImmaculateHeart event from temporale to sanctorale missal data

• Add ImmaculateHeart entry to relevant missal files in jsondata/sourcedata/missals/propriumdesanctis_*/propriumdesanctis_*.json directories (starting with 1970 edition)
• Include properties: event_key="ImmaculateHeart", grade=3 (Memorial), type="mobile", color=["white"], common=[appropriate common]
• Omit day/month properties since type="mobile"
• Verify lectionary readings remain in jsondata/sourcedata/lectionary/sanctorum/{language}.json (already correctly placed)

Task 2: Migrate i18n translations

Move ImmaculateHeart translations from temporale to sanctorale i18n structure

• Copy translation entries from jsondata/sourcedata/missals/propriumdetempore/i18n/*.json to corresponding jsondata/sourcedata/missals/propriumdesanctis_*/i18n/*.json files
• Maintain the existing translation structure and language coverage (pl, vi, pt, nl, la, it, id, hu, hr, fr, de, es, sk)
• Keep the event_key as "ImmaculateHeart" for consistent linking

🤖 Prompt for AI agents

Migrate ImmaculateHeart celebration data and translations from temporale to
sanctorale.

Move celebration definition:
- Add ImmaculateHeart entry to relevant missal files in
`jsondata/sourcedata/missals/propriumdesanctis_*/propriumdesanctis_*.json`
(starting with 1970 edition)
- Set properties: event_key="ImmaculateHeart", grade=3 (Memorial),
type="mobile", color=["white"], common=[appropriate common]
- Do NOT include day/month properties (type is mobile)
- Verify lectionary readings stay in
`jsondata/sourcedata/lectionary/sanctorum/{language}.json`

Migrate translations:
- Copy ImmaculateHeart entries from
`jsondata/sourcedata/missals/propriumdetempore/i18n/*.json` to corresponding
`jsondata/sourcedata/missals/propriumdesanctis_*/i18n/*.json` files
- Preserve existing translation structure and all language coverage (pl, vi, pt,
nl, la, it, id, hu, hr, fr, de, es, sk)
- Keep event_key="ImmaculateHeart" for consistent linking

Phase 3: Update Mobile Date Calculation Logic

Adapt the CalendarHandler to recognize and calculate dates for mobile sanctorale celebrations, specifically handling ImmaculateHeart's Easter-relative calculation.

Task 1: Detect and calculate mobile sanctorale events

Extend sanctorale loading logic to identify and compute dates for mobile celebrations

• Modify loadPropriumDeSanctisFromFile() method in src/Handlers/CalendarHandler.php to check the type property of loaded sanctorale events
• When a sanctorale event has type="mobile" and event_key="ImmaculateHeart", calculate the date using the existing pattern: Utilities::calcGregEaster($year)->add(new \DateInterval('P63D'))
• Set the calculated date on the PropriumDeSanctisEvent object before creating the LiturgicalEvent
• Ensure the event is properly added to the calendar with the computed date

Task 2: Adapt coincidence handling

Update the logic that handles ImmaculateHeart collisions with obligatory memorials

• Modify checkImmaculateHeartCoincidence() in src/Handlers/CalendarHandler.php to retrieve ImmaculateHeart from the sanctorale collection instead of temporale
• Maintain existing collision detection logic (comparing dates with format('U'))
• Keep the downgrade behavior (both celebrations become optional memorials) when coincidence occurs
• Ensure coincidence checks still happen at the appropriate point in calendar generation

🤖 Prompt for AI agents

Update CalendarHandler to handle mobile sanctorale celebrations and adapt
ImmaculateHeart-specific logic.

Detect and calculate mobile sanctorale dates:
- Modify `loadPropriumDeSanctisFromFile()` in `src/Handlers/CalendarHandler.php`
to check the type property of loaded sanctorale events
- When type="mobile" and event_key="ImmaculateHeart", calculate date as Easter +
63 days using: `Utilities::calcGregEaster($year)->add(new
\DateInterval('P63D'))`
- Set the calculated date on the PropriumDeSanctisEvent object before creating
the LiturgicalEvent
- Ensure the event is added to the calendar with the computed date

Adapt coincidence handling:
- Update `checkImmaculateHeartCoincidence()` to retrieve ImmaculateHeart from
sanctorale collection instead of temporale
- Maintain existing collision detection logic (comparing dates with format('U'))
- Preserve downgrade behavior (both celebrations become optional memorials) when
coincidence occurs
- Ensure coincidence checks happen at the correct point in calendar generation

Phase 4: Remove Temporale ImmaculateHeart Implementation

Clean up the original temporale-based ImmaculateHeart code now that it's handled through sanctorale.

Task 1: Remove temporale creation methods

Delete the temporale-specific ImmaculateHeart implementation

• Remove createImmaculateHeart() method from src/Handlers/CalendarHandler.php
• Remove the call to createImmaculateHeart() from the calendar generation workflow
• Remove ImmaculateHeart from $this->PropriumDeTempore collection references
• Remove the ImmaculateHeart entry from jsondata/sourcedata/missals/propriumdetempore/propriumdetempore.json

Task 2: Clean up temporale i18n files

Remove ImmaculateHeart translations from temporale i18n structure

• Delete ImmaculateHeart entries from all jsondata/sourcedata/missals/propriumdetempore/i18n/*.json files
• Verify no orphaned references remain in temporale data files

🤖 Prompt for AI agents

Remove all temporale-based ImmaculateHeart implementation code and data.

Remove temporale creation methods:
- Delete `createImmaculateHeart()` method from
`src/Handlers/CalendarHandler.php`
- Remove the call to createImmaculateHeart() from the calendar generation
workflow
- Remove ImmaculateHeart from `$this->PropriumDeTempore` collection references
- Remove ImmaculateHeart entry from
`jsondata/sourcedata/missals/propriumdetempore/propriumdetempore.json`

Clean up temporale i18n:
- Delete ImmaculateHeart entries from all
`jsondata/sourcedata/missals/propriumdetempore/i18n/*.json` files
- Verify no orphaned references remain in temporale data files

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend the PropriumDeSanctis schema to support mobile celebrations with
conditional validation.

In `jsondata/schemas/PropriumDeSanctis.json`:
- Add an optional "type" property that references the LitEventType definition
from CommonDef.json
- Implement JSON Schema conditional validation (if/then/else):
  - When type="mobile": day and month properties are NOT required
  - When type="fixed" or type is absent: day and month properties ARE required
- Maintain additionalProperties:false to preserve schema strictness
- Add schema examples demonstrating both fixed and mobile celebration formats
===============================================================================

Task: 2

Migrate ImmaculateHeart celebration data and translations from temporale to
sanctorale.

Move celebration definition:
- Add ImmaculateHeart entry to relevant missal files in
`jsondata/sourcedata/missals/propriumdesanctis_*/propriumdesanctis_*.json`
(starting with 1970 edition)
- Set properties: event_key="ImmaculateHeart", grade=3 (Memorial),
type="mobile", color=["white"], common=[appropriate common]
- Do NOT include day/month properties (type is mobile)
- Verify lectionary readings stay in
`jsondata/sourcedata/lectionary/sanctorum/{language}.json`

Migrate translations:
- Copy ImmaculateHeart entries from
`jsondata/sourcedata/missals/propriumdetempore/i18n/*.json` to corresponding
`jsondata/sourcedata/missals/propriumdesanctis_*/i18n/*.json` files
- Preserve existing translation structure and all language coverage (pl, vi, pt,
nl, la, it, id, hu, hr, fr, de, es, sk)
- Keep event_key="ImmaculateHeart" for consistent linking
===============================================================================

Task: 3

Update CalendarHandler to handle mobile sanctorale celebrations and adapt
ImmaculateHeart-specific logic.

Detect and calculate mobile sanctorale dates:
- Modify `loadPropriumDeSanctisFromFile()` in `src/Handlers/CalendarHandler.php`
to check the type property of loaded sanctorale events
- When type="mobile" and event_key="ImmaculateHeart", calculate date as Easter +
63 days using: `Utilities::calcGregEaster($year)->add(new
\DateInterval('P63D'))`
- Set the calculated date on the PropriumDeSanctisEvent object before creating
the LiturgicalEvent
- Ensure the event is added to the calendar with the computed date

Adapt coincidence handling:
- Update `checkImmaculateHeartCoincidence()` to retrieve ImmaculateHeart from
sanctorale collection instead of temporale
- Maintain existing collision detection logic (comparing dates with format('U'))
- Preserve downgrade behavior (both celebrations become optional memorials) when
coincidence occurs
- Ensure coincidence checks happen at the correct point in calendar generation
===============================================================================

Task: 4

Remove all temporale-based ImmaculateHeart implementation code and data.

Remove temporale creation methods:
- Delete `createImmaculateHeart()` method from
`src/Handlers/CalendarHandler.php`
- Remove the call to createImmaculateHeart() from the calendar generation
workflow
- Remove ImmaculateHeart from `$this->PropriumDeTempore` collection references
- Remove ImmaculateHeart entry from
`jsondata/sourcedata/missals/propriumdetempore/propriumdetempore.json`

Clean up temporale i18n:
- Delete ImmaculateHeart entries from all
`jsondata/sourcedata/missals/propriumdetempore/i18n/*.json` files
- Verify no orphaned references remain in temporale data files

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

💬 Have feedback or questions? Drop into our discord or schedule a call!