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
use super::{Claimed, Lane, LaneIdent, Lanes, lane_collisions, lane_for};

use crate::{Slot, SlotName};

/// The roster the gate lanes below are read against — one plain lane, and one folding three tags.
static ROSTER: &[Lane] = &[
  Lane::of(LaneIdent::new("en")),
  Lane::of(LaneIdent::new("ja")),
  Lane::of(LaneIdent::new("zh")).accepting(&[
    LaneIdent::new("zh_hans"),
    LaneIdent::new("zh_hant"),
    LaneIdent::new("cmn"),
  ]),
];

/// A corpus that named no lanes — the zero-configuration slot, joining by writing nothing.
struct Unfanned;

impl Slot for Unfanned {
  type Of = ();
  const SLOT: &'static SlotName = SlotName::new("unfanned");
  const FIELD: &'static str = "body";
  const ENGINE: &'static str = "lexical";
}

impl Lanes for Unfanned {}

/// A corpus that named its own.
struct Fanned;

impl Slot for Fanned {
  type Of = ();
  const SLOT: &'static SlotName = SlotName::new("fanned");
  const FIELD: &'static str = "body";
  const ENGINE: &'static str = "lexical";
}

impl Lanes for Fanned {
  const LANES: &'static [Lane] = ROSTER;
}

/// **PRESENCE IS THE WHOLE OF IT**: a slot that said nothing has ONE lane rather than none, so no
/// reader anywhere carries an *is this fanned* fork.
#[test]
fn a_slot_that_named_no_lanes_has_the_undetermined_one() {
  assert_eq!(Unfanned::LANES.len(), 1);
  assert_eq!(Unfanned::LANES[0].key(), LaneIdent::UND);
  assert!(Unfanned::LANES[0].accepts().is_empty());

  assert_eq!(Fanned::LANES.len(), 3);
}

/// A lane states its key and whatever it accepts, and the absence of the builder IS the absence of
/// the word.
#[test]
fn a_lane_carries_its_key_and_its_aliases() {
  let plain = Lane::of(LaneIdent::new("en"));
  assert_eq!(plain.key(), LaneIdent::new("en"));
  assert!(plain.accepts().is_empty());

  // A `const` rather than an inline literal: a roster is `'static` by construction, and a `const fn`
  // call is not rvalue-promoted — which is the same reason every roster in this crate is a `static`.
  const ACCEPTS: &[&LaneIdent] = &[LaneIdent::new("en_gb")];
  let folded = plain.accepting(ACCEPTS);
  assert_eq!(folded.key(), LaneIdent::new("en"));
  assert_eq!(folded.accepts(), &[LaneIdent::new("en_gb")]);
}

/// **BROAD IN**: every spelling a tag arrives in reaches the lane it means.
#[test]
fn the_gate_accepts_broadly() {
  for (tag, key) in [
    // The key itself, in every case a producer might use.
    ("en", "en"),
    ("EN", "en"),
    ("En", "en"),
    // A region, a variant and an extension are none of a lane's business.
    ("en-US", "en"),
    ("en-GB", "en"),
    ("en-US-posix", "en"),
    ("ja-JP", "ja"),
    // The declared aliases, through the fold: the declaration wrote `_`, the caller writes `-`.
    ("zh-Hant", "zh"),
    ("zh-Hant-TW", "zh"),
    ("zh_hans", "zh"),
    ("ZH-HANS-CN", "zh"),
    // An extlang reduces to its primary, and `cmn` as a PRIMARY is a declared alias.
    ("zh-cmn-Hans", "zh"),
    ("cmn", "zh"),
  ] {
    let lane = lane_for(tag, ROSTER).unwrap_or_else(|error| panic!("{tag}: {error}"));
    assert_eq!(&**lane.key(), key, "at {tag}");
  }
}

/// **STRICT OUT**: what leaves the gate is the lane's own key and never the caller's spelling, so
/// two tags meaning one lane produce one identifier.
#[test]
fn the_gate_emits_one_canonical_key() {
  let one = lane_for("zh-Hant-TW", ROSTER).expect("a declared alias");
  let other = lane_for("cmn", ROSTER).expect("a declared alias");
  let third = lane_for("ZH", ROSTER).expect("the key itself");

  assert_eq!(one.key(), other.key());
  assert_eq!(other.key(), third.key());
  assert_eq!(&**one.key(), "zh");
}

/// **NOTHING MATCHING IS A REFUSAL** — never a silent fallback, and never the `und` lane by
/// accident.
#[test]
fn an_unmatched_tag_is_refused_by_name() {
  // `zh-Latn` is NOT among them since the degradation step landed: its language is declared, so it
  // reaches `zh` as a near-home rather than being refused. What is refused is a tag whose LANGUAGE
  // nobody declared, over a roster carrying no catch-all.
  for tag in ["sw", "de", "und", "qaa"] {
    assert!(lane_for(tag, ROSTER).is_err(), "{tag} should be refused");
  }
  assert_eq!(
    &**lane_for("zh-Latn", ROSTER).expect("`zh` is declared").key(),
    "zh"
  );

  let refusal = lane_for("sw-KE", ROSTER).expect_err("no lane answers Swahili");
  let sentence = refusal.to_string();

  assert_eq!(refusal.tag(), "sw-KE");
  assert_eq!(refusal.lanes(), ROSTER);
  // THE SENTENCE IS ACTIONABLE: the tag, the roster, and every alias.
  assert!(sentence.contains("sw-KE"), "{sentence}");
  assert!(sentence.contains("`en`"), "{sentence}");
  assert!(sentence.contains("`ja`"), "{sentence}");
  assert!(sentence.contains("`zh`"), "{sentence}");
  assert!(sentence.contains("zh_hant"), "{sentence}");
  assert!(sentence.contains("cmn"), "{sentence}");
}

/// A tag this grammar cannot read at all is refused by the same door, in the same words.
#[test]
fn a_tag_that_is_not_a_tag_is_refused() {
  for tag in ["", "x-private", "i-klingon", "!!", "1"] {
    let refusal = lane_for(tag, ROSTER).expect_err("not a language tag");
    assert_eq!(refusal.tag(), tag);
  }
}

/// An EMPTY roster answers nothing and says so — the honest sentence for a corpus with no lanes.
#[test]
fn an_empty_roster_refuses_everything() {
  static NONE: &[Lane] = &[];

  let refusal = lane_for("en", NONE).expect_err("there is nothing to reach");
  assert!(refusal.to_string().contains("no lanes at all"), "{refusal}");
}

/// **KEYS BEFORE ALIASES**: a lane's own key outranks another lane's claim on the same tag.
#[test]
fn a_key_wins_over_another_lanes_alias() {
  static SPLIT: &[Lane] = &[
    // The older lane still lists the traditional tag among its aliases…
    Lane::of(LaneIdent::new("zh")).accepting(&[LaneIdent::new("zh_hant")]),
    // …and the newer one keys it directly. The key is what a tag reaches.
    Lane::of(LaneIdent::new("zh-Hant")),
  ];

  assert_eq!(&**lane_for("zh-Hant", SPLIT).unwrap().key(), "zh-Hant");
  assert_eq!(&**lane_for("zh", SPLIT).unwrap().key(), "zh");
  // And the arrangement is named for what it is by the audit, rather than left to list order.
  assert!(lane_collisions(SPLIT).is_err());
}

/// A clean roster passes its own audit.
#[test]
fn a_roster_with_no_two_claims_on_one_word_passes() {
  assert!(lane_collisions(ROSTER).is_ok());
  assert!(lane_collisions(Unfanned::LANES).is_ok());
  assert!(lane_collisions(&[]).is_ok());
}

/// **TWO LANES CANNOT CLAIM ONE WORD**, in each of the four shapes the defect takes.
#[test]
fn the_audit_names_both_claimants() {
  // Two keys that fold alike.
  static TWO_KEYS: &[Lane] = &[
    Lane::of(LaneIdent::new("zh_hant")),
    Lane::of(LaneIdent::new("ZH-HANT")),
  ];
  let collision = lane_collisions(TWO_KEYS).expect_err("one word, two lanes");
  assert_eq!(collision.word(), Some("zh_hant"));
  assert_eq!(&**collision.first(), "zh_hant");
  assert_eq!(&**collision.second(), "ZH-HANT");
  assert!(collision.to_string().contains("cannot name two lanes"));

  // A key and another lane's alias.
  static KEY_AND_ALIAS: &[Lane] = &[
    Lane::of(LaneIdent::new("zh")).accepting(&[LaneIdent::new("cmn")]),
    Lane::of(LaneIdent::new("cmn")),
  ];
  assert!(lane_collisions(KEY_AND_ALIAS).is_err());

  // Two aliases, on two lanes.
  static TWO_ALIASES: &[Lane] = &[
    Lane::of(LaneIdent::new("zh")).accepting(&[LaneIdent::new("yue")]),
    Lane::of(LaneIdent::new("ja")).accepting(&[LaneIdent::new("YUE")]),
  ];
  assert!(lane_collisions(TWO_ALIASES).is_err());

  // ONE lane listing a word twice, which is the same defect one grain in.
  static SELF_CLAIM: &[Lane] =
    &[Lane::of(LaneIdent::new("zh")).accepting(&[LaneIdent::new("cmn"), LaneIdent::new("CMN")])];
  let own = lane_collisions(SELF_CLAIM).expect_err("one lane, one word, twice");
  assert_eq!(own.word(), Some("cmn"));
  assert_eq!(own.first(), own.second());

  // And a lane that listed its own key among its aliases.
  static ECHO: &[Lane] = &[Lane::of(LaneIdent::new("zh")).accepting(&[LaneIdent::new("ZH")])];
  assert!(lane_collisions(ECHO).is_err());
}

/// A key nothing folds to is not a collision — the audit is about WORDS, not about reachability.
#[test]
fn distinct_words_never_collide() {
  static WIDE: &[Lane] = &[
    Lane::of(LaneIdent::new("en")),
    Lane::of(LaneIdent::new("ja")),
    Lane::of(LaneIdent::new("zh")).accepting(&[LaneIdent::new("zh_hans"), LaneIdent::new("cmn")]),
    Lane::of(LaneIdent::new("ko")),
    Lane::of(LaneIdent::UND),
  ];

  assert!(lane_collisions(WIDE).is_ok());
}

/// The roster the six-step resolution is read against: one lane per language, no script aliases at
/// all, and a declared catch-all at the end.
static SIX_STEP: &[Lane] = &[
  Lane::of(LaneIdent::new("en")),
  Lane::of(LaneIdent::new("zh")),
  Lane::of(LaneIdent::new("sr")),
  Lane::of(LaneIdent::new("other")).catch_all(),
];

/// The key a tag reaches, or `None` where the gate refused.
fn reached(tag: &str, lanes: &'static [Lane]) -> Option<&'static str> {
  lane_for(tag, lanes).ok().map(|lane| &**lane.key())
}

/// **STEP ③ — THE LANGUAGE-ONLY KEY.** A script nobody declared an alias for still reaches the lane
/// its language names, so a wide roster does not need a hand-written alias per script.
#[test]
fn a_script_bearing_tag_degrades_to_its_language_key() {
  assert_eq!(reached("zh-Hant", SIX_STEP), Some("zh"));
  assert_eq!(reached("zh-Hans-CN", SIX_STEP), Some("zh"));
  assert_eq!(reached("en-Latn", SIX_STEP), Some("en"));
  assert_eq!(reached("en-Latn-US", SIX_STEP), Some("en"));
  // AND THE APPROXIMATE HOME BEATS THE GENERIC CATCH-ALL: `sr-Latn` is Serbian before it is a
  // stranger, so it reaches `sr` rather than falling through.
  assert_eq!(reached("sr-Latn", SIX_STEP), Some("sr"));
  assert_eq!(reached("sr-Cyrl-RS", SIX_STEP), Some("sr"));
}

/// **THE EXACT KEY STILL COMES FIRST.** A deployment that splits Chinese into two lanes keys the
/// second one directly, and step ① takes the tag before step ③ can degrade it.
#[test]
fn an_exact_key_outranks_the_language_only_step() {
  static SPLIT: &[Lane] = &[
    Lane::of(LaneIdent::new("zh")),
    Lane::of(LaneIdent::new("zh_hant")),
  ];

  assert_eq!(reached("zh-Hant", SPLIT), Some("zh_hant"));
  assert_eq!(reached("zh-Hant-TW", SPLIT), Some("zh_hant"));
  assert_eq!(reached("zh", SPLIT), Some("zh"));
  // A third Chinese script nobody keyed degrades to the plain lane, which is step ③ again.
  assert_eq!(reached("zh-Hans", SPLIT), Some("zh"));
}

/// **DECLARED ALWAYS OUTRANKS DERIVED** — the governing law, and the one ordering a reader could
/// otherwise get backwards.
///
/// A lane that declares `zh_hant` as an ALIAS is a declaration about that exact tag. A lane keyed
/// `zh` is a declaration about the language, from which `zh-Hant` is only DERIVED. So the alias wins,
/// even though the keyed lane comes first in the roster and even though step ① is offered the tag
/// before step ②.
#[test]
fn an_exact_alias_outranks_a_language_only_key() {
  static DECLARED_FIRST: &[Lane] = &[
    // Keyed on the language, and listed FIRST.
    Lane::of(LaneIdent::new("zh")),
    // Declaring the exact tag, and listed second.
    Lane::of(LaneIdent::new("cn")).accepting(&[LaneIdent::new("zh_hant")]),
  ];

  assert_eq!(
    reached("zh-Hant", DECLARED_FIRST),
    Some("cn"),
    "an exact alias is a declaration about this tag; `zh` is only its language"
  );
  // The language-only step still serves everything the alias did not claim.
  assert_eq!(reached("zh-Hans", DECLARED_FIRST), Some("zh"));
  assert_eq!(reached("zh", DECLARED_FIRST), Some("zh"));
}

/// **STEP ⑤ FIRES ONLY AFTER BOTH LANGUAGE-ONLY STEPS MISS.**
#[test]
fn the_catch_all_takes_only_what_no_lane_has_a_home_for() {
  // A language nobody declared, and a rostered-but-unhomed script word.
  assert_eq!(reached("sw", SIX_STEP), Some("other"));
  assert_eq!(reached("sw-KE", SIX_STEP), Some("other"));
  assert_eq!(reached("beng", SIX_STEP), Some("other"));
  assert_eq!(reached("zzzz", SIX_STEP), Some("other"));
  // But never what a keyed or degraded lane already answers.
  assert_eq!(reached("en-GB", SIX_STEP), Some("en"));
  assert_eq!(reached("zh-Hant", SIX_STEP), Some("zh"));
}

/// **A CATCH-ALL CATCHES NON-TAGS TOO** — a catch-all that only caught SOME strangers would be a
/// half-promise, and the malformed ones are exactly what a producer emits by accident.
#[test]
fn the_catch_all_catches_what_is_not_a_tag_at_all() {
  for stranger in ["", "x-private", "i-klingon", "!!", "1", "toolongsubtag"] {
    assert_eq!(
      reached(stranger, SIX_STEP),
      Some("other"),
      "at {stranger:?}"
    );
  }
}

/// **THE REFUSAL PATH IS INTACT** where nobody declared a catch-all — and its text now names that
/// second road out.
#[test]
fn without_a_catch_all_a_stranger_is_still_refused() {
  static NO_CATCH_ALL: &[Lane] = &[
    Lane::of(LaneIdent::new("en")),
    Lane::of(LaneIdent::new("zh")),
  ];

  let refusal = lane_for("sw-KE", NO_CATCH_ALL).expect_err("no home, no catch-all");
  let sentence = refusal.to_string();

  assert!(sentence.contains("sw-KE"), "{sentence}");
  assert!(sentence.contains("`en`"), "{sentence}");
  assert!(
    sentence.ends_with(", and no catch-all is declared"),
    "{sentence}"
  );
  // Non-tags too, where there is nothing to catch them.
  assert!(lane_for("x-private", NO_CATCH_ALL).is_err());
  // And the language-only step still works without one.
  assert_eq!(reached("zh-Hant", NO_CATCH_ALL), Some("zh"));
}

/// **EXACTLY ONE CATCH-ALL** — a second is the collision family, naming both claimants.
#[test]
fn a_second_catch_all_is_refused_by_the_audit() {
  static TWO: &[Lane] = &[
    Lane::of(LaneIdent::new("en")).catch_all(),
    Lane::of(LaneIdent::new("zh")),
    Lane::of(LaneIdent::new("other")).catch_all(),
  ];

  let refusal = lane_collisions(TWO).expect_err("two catch-alls");
  assert_eq!(refusal.claimed(), &Claimed::CatchAll);
  assert_eq!(
    refusal.word(),
    None,
    "what was claimed is a role, not a word"
  );
  assert_eq!(&**refusal.first(), "en");
  assert_eq!(&**refusal.second(), "other");
  assert!(refusal.to_string().contains("both declared the catch-all"));

  // One is fine, and so is none.
  assert!(lane_collisions(SIX_STEP).is_ok());
  assert!(lane_collisions(ROSTER).is_ok());
}

/// The catch-all is an ordinary roster row in every other respect: it keys, it aliases, and it shows
/// up in a listing.
#[test]
fn a_catch_all_is_still_a_lane() {
  let lane = Lane::of(LaneIdent::new("other")).catch_all();

  assert!(lane.is_catch_all());
  assert_eq!(lane.key(), LaneIdent::new("other"));
  assert!(!Lane::of(LaneIdent::new("en")).is_catch_all());
  // It answers its own key through step ①, not through step ⑤.
  assert_eq!(reached("other", SIX_STEP), Some("other"));
}