ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! What the calendar seam does — including the two ruled DST pins, which it now HONOURS.
//!
//! These assertions used to be measurements of a deviation: the evaluator belonged to a third-party
//! crate, the ruling's own escape said the pins stand insofar as that crate keeps them, and two of
//! them it did not. The evaluator is this seam's own now, so both are LAW here — and each test is
//! named for the law it keeps rather than for the deviation it recorded.

use core::time::Duration;

use jiff::Timestamp;

use super::{Calendar, FIELDS};

/// A fixed instant, so a schedule's next occurrences are the same on every machine and in every
/// season.
fn at(text: &str) -> Timestamp {
  text.parse().expect("an instant")
}

/// The next `count` occurrences after `from`, as local wall-clock text with the offset.
fn walk(calendar: &Calendar, from: &str, count: usize) -> Vec<String> {
  let mut at = at(from);
  let mut fired = Vec::with_capacity(count);
  for _ in 0..count {
    let Some(next) = calendar.next_after(at) else {
      break;
    };
    fired.push(next.strftime("%Y-%m-%dT%H:%M:%S%:z").to_string());
    at = next.timestamp();
  }
  fired
}

/// The classic five fields, and nothing else — a sixth naming a zone is what `tz` says.
#[test]
fn the_dialect_is_the_classic_five_fields() {
  assert_eq!(FIELDS, 5);
  assert!(Calendar::parse("0 3 * * *").is_ok());
  assert!(Calendar::parse("*/15 * * * *").is_ok());

  let refusal = Calendar::parse("0 3 * * * Asia/Shanghai").expect_err("six fields");
  assert!(
    refusal.to_string().contains("classic 5 fields"),
    "{refusal}"
  );
  let refusal = Calendar::parse("0 3 * *").expect_err("four fields");
  assert!(refusal.to_string().contains("has 4"), "{refusal}");
}

/// Garbage carries the implementation's own diagnosis, which names the offending field.
#[test]
fn garbage_carries_the_offending_field() {
  let refusal = Calendar::parse("99 3 * * *").expect_err("a minute past 59");
  assert!(refusal.to_string().contains("99"), "{refusal}");
}

/// A zone is read by name, and a name the machine's database does not have is refused HERE — a
/// schedule that cannot be evaluated must not quietly become one that never fires.
#[test]
fn a_zone_is_read_by_name() {
  let calendar = Calendar::parse_in("0 3 * * *", "America/New_York").expect("a real zone");
  assert_eq!(calendar.expression(), "0 3 * * *");
  assert!(Calendar::parse_in("0 3 * * *", "Not/AZone").is_err());
}

/// A daily schedule is next due inside a day, whatever hour it is asked at.
#[test]
fn a_daily_schedule_is_due_inside_a_day() {
  let calendar = Calendar::parse_in("0 3 * * *", "Etc/UTC").expect("a daily schedule");
  let wait = calendar
    .until_next()
    .expect("a daily schedule is always due again");
  assert!(wait <= Duration::from_secs(24 * 60 * 60), "{wait:?}");
}

/// **A ruled pin the implementation HONOURS**: day-of-month and day-of-week are the classic OR when
/// both are restricted — `0 3 1 * MON` fires on the first AND on every Monday.
#[test]
fn dom_and_dow_are_the_classic_or() {
  let calendar = Calendar::parse_in("0 3 1 * MON", "Etc/UTC").expect("a dom/dow schedule");
  assert_eq!(
    walk(&calendar, "2026-03-01T00:00:00Z", 4),
    [
      // The first of the month, which is a Sunday in March 2026.
      "2026-03-01T03:00:00+00:00",
      // Then every Monday — which an AND reading would never reach.
      "2026-03-02T03:00:00+00:00",
      "2026-03-09T03:00:00+00:00",
      "2026-03-16T03:00:00+00:00",
    ]
  );
}

/// **THE FIRST RULED DST PIN, kept**: a NONEXISTENT local time fires ONCE, at the gap's END.
///
/// `America/New_York` springs forward on 2026-03-08, so 02:30 does not exist that morning. The
/// schedule does not skip the day and does not slide to 03:30 — it fires at 03:00-04:00, the first
/// instant that exists after the gap, which is what *the gap's end* names.
///
/// Mutation-checked: making the gap arm answer the `before` offset instead of the transition puts
/// `2026-03-08T03:30:00-04:00` on the second line, and dropping the arm entirely restores the old
/// deviation — the 8th missing altogether.
#[test]
fn a_gap_day_fires_once_at_the_gaps_end() {
  let calendar = Calendar::parse_in("30 2 * * *", "America/New_York").expect("a daily schedule");
  assert_eq!(
    walk(&calendar, "2026-03-06T12:00:00Z", 4),
    [
      "2026-03-07T02:30:00-05:00",
      // 02:30 does not exist. The gap ends at 03:00, and that is where the day fires.
      "2026-03-08T03:00:00-04:00",
      "2026-03-09T02:30:00-04:00",
      "2026-03-10T02:30:00-04:00",
    ]
  );
}

/// **The first pin's other half**: a schedule naming SEVERAL civil minutes inside one gap still
/// fires ONCE.
///
/// Every civil minute of a gap maps to the same instant — the transition — so a walk that answers
/// strictly after what it was given offers it once and then moves past the whole gap. `*/20 2 * * *`
/// names 02:00, 02:20 and 02:40, all of which are missing on the 8th, and the day gets one firing
/// rather than three identical ones.
#[test]
fn a_whole_gap_collapses_to_one_firing() {
  let calendar = Calendar::parse_in("*/20 2 * * *", "America/New_York").expect("a gap schedule");
  assert_eq!(
    walk(&calendar, "2026-03-08T06:00:00Z", 4),
    [
      // The one firing the gap earns …
      "2026-03-08T03:00:00-04:00",
      // … and then the next day's three, unremarkably.
      "2026-03-09T02:00:00-04:00",
      "2026-03-09T02:20:00-04:00",
      "2026-03-09T02:40:00-04:00",
    ]
  );
}

/// **THE SECOND RULED DST PIN, kept**: a REPEATED local time fires ONCE, at the FIRST occurrence.
///
/// `America/New_York` falls back on 2026-11-01, so 01:30 happens twice — at -04:00 and again at
/// -05:00. The schedule fires on the first and never on the second, and it is not a filter that
/// makes it so: the walk enumerates CIVIL times and maps each to exactly one instant, so the second
/// pass is never a candidate.
///
/// Mutation-checked: answering the fold with its `after` offset moves the third line to
/// `2026-11-01T01:30:00-05:00` and the whole run an hour later.
#[test]
fn a_fold_fires_once_at_the_first_occurrence() {
  let calendar = Calendar::parse_in("30 1 * * *", "America/New_York").expect("a daily schedule");
  assert_eq!(
    walk(&calendar, "2026-10-30T12:00:00Z", 4),
    [
      "2026-10-31T01:30:00-04:00",
      // One 01:30, at the FIRST of the two …
      "2026-11-01T01:30:00-04:00",
      // … and the second pass of the hour is not a candidate at all.
      "2026-11-02T01:30:00-05:00",
      "2026-11-03T01:30:00-05:00",
    ]
  );
}

/// **The second pin's PRICE, stated where a reader meets it**: a schedule firing several times
/// inside a repeated hour loses that hour's second pass.
///
/// `*/15 1 * * *` is four firings an hour. On the fold day it gets four and not eight, which is what
/// *a repeated local time fires once* means when the schedule names more than one of them. The poll
/// doctrine's own requirement that a sweep be idempotent is what makes it affordable.
#[test]
fn a_repeated_hour_costs_its_second_pass() {
  let calendar = Calendar::parse_in("*/15 1 * * *", "America/New_York").expect("a fold schedule");
  assert_eq!(
    walk(&calendar, "2026-11-01T04:00:00Z", 5),
    [
      "2026-11-01T01:00:00-04:00",
      "2026-11-01T01:15:00-04:00",
      "2026-11-01T01:30:00-04:00",
      "2026-11-01T01:45:00-04:00",
      // The hour repeats and the schedule does not: the next firing is the following day's.
      "2026-11-02T01:00:00-05:00",
    ]
  );
}

/// A day the calendar never reaches is *never*, and a clock told so stops asking.
///
/// February the thirtieth is the expression a horizon exists for: it parses, it names a real
/// day-of-month and a real month, and no year has one. The walk answers `None` rather than looking
/// forever.
#[test]
fn a_day_that_never_comes_is_never() {
  let calendar = Calendar::parse_in("0 0 30 2 *", "Etc/UTC").expect("a legal expression");
  assert!(calendar.until_next().is_none());

  // Its neighbour DOES come, which is what says the horizon is wide enough to find it: 2028 is the
  // next leap year after the instant below.
  let leap = Calendar::parse_in("0 0 29 2 *", "Etc/UTC").expect("a leap-day schedule");
  assert_eq!(
    walk(&leap, "2026-03-01T00:00:00Z", 1),
    ["2028-02-29T00:00:00+00:00"]
  );
}

/// A parse refusal QUOTES THE EXPRESSION with a caret on the run that broke it.
///
/// The span is spent rather than the sentence alone, which is what keeps this swap a strict keep:
/// the previous crate's own rendering carried the offending text under a caret, and a reader must
/// not be given less because the crate underneath changed.
#[test]
fn a_refusal_quotes_the_expression_under_a_caret() {
  let refusal = Calendar::parse_in("99 3 * * *", "Etc/UTC").expect_err("a minute past 59");
  let refusal = refusal.to_string();
  assert!(refusal.contains("minute"), "{refusal}");
  assert!(refusal.contains("99 3 * * *"), "{refusal}");
  assert!(refusal.contains('^'), "{refusal}");
  // The caret is under the offending run and not at column zero, which is the whole of what the
  // span buys over printing the sentence twice.
  let marked = refusal.lines().next_back().expect("a caret line");
  assert_eq!(marked.trim_end(), "  ^^", "{refusal}");
}

/// The two halves of the seam render ONE caret, and neither can import the other's copy.
///
/// `ingraph-codegen`'s `cron::caret` is the twin, written out because the build order forbids
/// sharing — this crate expands through the derive, which is built on that one. What keeps them
/// identical is this assertion plus its opposite number in the codegen suite: both quote the
/// expression on its own line, indented two, with the caret under the run the span names.
#[test]
fn the_two_halves_render_one_caret() {
  let refusal = Calendar::parse_in("0 3 * * MONDAY", "Etc/UTC").expect_err("not a day name");
  let rendered = refusal.to_string();
  let mut lines = rendered.lines();
  let sentence = lines.next().expect("a sentence");
  assert!(sentence.contains("day of week"), "{rendered}");
  assert_eq!(lines.next(), Some("  0 3 * * MONDAY"), "{rendered}");
  let marked = lines.next().expect("a caret line");
  assert!(marked.starts_with("  "), "{rendered}");
  assert!(marked.trim_start().starts_with('^'), "{rendered}");
  assert_eq!(lines.next(), None, "the rendering is three lines");
}