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::{FanAll, LaneRouter, ScriptRouter, ScriptWeightedFan};

use crate::{Lane, LaneIdent};

/// A deployment indexing English and Japanese, with the Japanese lane fed by all three of the
/// scripts a Japanese sentence is written in.
static CORPUS: &[Lane] = &[
  Lane::of(LaneIdent::new("en")).accepting(&[LaneIdent::new("latn")]),
  Lane::of(LaneIdent::new("ja")).accepting(&[
    LaneIdent::new("hani"),
    LaneIdent::new("hira"),
    LaneIdent::new("kana"),
  ]),
];

/// One lane, which is the shape an unfanned corpus has.
static SOLE: &[Lane] = &[Lane::of(LaneIdent::new("en")).accepting(&[LaneIdent::new("latn")])];

/// The routed dispatches as `(lane, probe)` — the shape every assertion below reads.
fn routed<T: LaneRouter<Routed = String>>(
  router: &T,
  question: &T::Question,
) -> Vec<(String, String)>
where
  T::Error: core::fmt::Debug,
{
  router
    .route(question)
    .expect("routing answers")
    .into_iter()
    .map(|probe| {
      let (lane, probe, _) = probe.into_components();
      ((**lane).to_owned(), probe)
    })
    .collect()
}

/// **EVERY LANE, THE WHOLE QUESTION** — no cutting and no cleverness.
#[test]
fn fan_all_asks_every_lane_with_the_whole_question() {
  let all = FanAll::<str>::new(CORPUS);

  assert_eq!(
    routed(&all, "hello 世界"),
    vec![
      ("en".to_owned(), "hello 世界".to_owned()),
      ("ja".to_owned(), "hello 世界".to_owned()),
    ]
  );
  assert_eq!(all.lanes(), CORPUS);
}

/// **IDENTITY DEGRADATION, STRUCTURALLY**: over a one-lane corpus the fan produces exactly one
/// dispatch carrying the whole question — which is the unfanned read, unchanged.
#[test]
fn fan_all_over_one_lane_is_the_unfanned_question() {
  let question = "  A GOOD film, 2024.  ";
  let dispatches = routed(&FanAll::<str>::new(SOLE), question);

  assert_eq!(dispatches.len(), 1);
  assert_eq!(dispatches[0].0, "en");
  // BYTE-IDENTICAL: not trimmed, not normalised, not cut.
  assert_eq!(dispatches[0].1, question);
}

/// `FanAll` cannot fail, and the type says so.
#[test]
fn fan_all_is_infallible() {
  let all = FanAll::<str>::new(CORPUS);
  let answered: Result<_, core::convert::Infallible> = all.route("anything at all");
  assert!(answered.is_ok());

  // Even over an empty roster: no lanes means no dispatches, which is the empty set.
  static NONE: &[Lane] = &[];
  assert!(
    FanAll::<str>::new(NONE)
      .route("x")
      .expect("infallible")
      .is_empty()
  );
}

/// **SAME-LANE RUNS MERGE**, in first-appearance order, joined by one space.
#[test]
fn the_script_router_merges_the_runs_that_share_a_lane() {
  assert_eq!(
    routed(&ScriptRouter::new(CORPUS), "日本語 report テキスト"),
    vec![
      ("ja".to_owned(), "日本語 テキスト".to_owned()),
      ("en".to_owned(), "report ".to_owned()),
    ]
  );
}

/// A lane enters the answer where its FIRST run occurred, whatever order the rest arrive in.
#[test]
fn a_lane_takes_the_place_of_its_first_run() {
  assert_eq!(
    routed(&ScriptRouter::new(CORPUS), "hello 世界 again かな more"),
    vec![
      ("en".to_owned(), "hello again more".to_owned()),
      ("ja".to_owned(), "世界 かな ".to_owned()),
    ]
  );
}

/// One script, one lane, one probe — the question crosses untouched.
#[test]
fn a_single_script_question_is_one_dispatch() {
  assert_eq!(
    routed(&ScriptRouter::new(CORPUS), "hello world"),
    vec![("en".to_owned(), "hello world".to_owned())]
  );
  assert_eq!(
    routed(&ScriptRouter::new(CORPUS), "日本語"),
    vec![("ja".to_owned(), "日本語".to_owned())]
  );
}

/// **GUARDRAIL ③ AT THE ROUTER**: nothing in the question means no dispatches, which is the empty
/// set rather than a refusal.
#[test]
fn an_empty_question_routes_to_nothing() {
  assert!(
    ScriptRouter::new(CORPUS)
      .route("")
      .expect("no runs")
      .is_empty()
  );
}

/// A run whose script no lane accepts is REFUSED BY NAME — never dropped, and never guessed at.
#[test]
fn a_script_no_lane_accepts_is_refused_with_the_roster() {
  // `zyyy` — a wholly punctuation-and-digit question, which the segmenter files under the fallback
  // bucket and no lane here accepts.
  let refusal = ScriptRouter::new(CORPUS)
    .route("123 !!!")
    .expect_err("the fallback bucket reaches no lane here");
  assert_eq!(refusal.tag(), "zzzz");
  assert!(refusal.to_string().contains("`en`"), "{refusal}");
  assert!(refusal.to_string().contains("`ja`"), "{refusal}");

  // And a real script this corpus declared nothing for.
  let cyrillic = ScriptRouter::new(CORPUS)
    .route("Привет")
    .expect_err("no Cyrillic lane");
  assert_eq!(cyrillic.tag(), "cyrl");
}

/// **A CORPUS THAT DECLARES NO SCRIPT ALIASES ROUTES NOTHING**, and says so — the guardrail working
/// rather than a gap.
#[test]
fn a_corpus_with_no_script_aliases_refuses_by_name() {
  static BARE: &[Lane] = &[Lane::of(LaneIdent::new("en"))];

  let refusal = ScriptRouter::new(BARE)
    .route("hello")
    .expect_err("`latn` is not accepted anywhere");
  assert_eq!(refusal.tag(), "latn");
}

/// **A DECLARED CATCH-ALL SENDS THE STRANGERS SOMEWHERE**, and leaves the homed runs alone.
#[test]
fn a_catch_all_lane_takes_the_runs_no_lane_has_a_home_for() {
  static WITH_REST: &[Lane] = &[
    Lane::of(LaneIdent::new("en")).accepting(&[LaneIdent::new("latn")]),
    Lane::of(LaneIdent::new("ja")).accepting(&[
      LaneIdent::new("hani"),
      LaneIdent::new("hira"),
      LaneIdent::new("kana"),
    ]),
    Lane::of(LaneIdent::new("rest")).catch_all(),
  ];

  // A SWEPT-IN SCRIPT with no lane of its own — Bengali — lands in the lane somebody wrote down.
  assert_eq!(
    routed(&ScriptRouter::new(WITH_REST), "hello বাংলা 日本語"),
    vec![
      ("en".to_owned(), "hello ".to_owned()),
      ("rest".to_owned(), "বাংলা ".to_owned()),
      ("ja".to_owned(), "日本語".to_owned()),
    ]
  );

  // So does the fallback bucket's own word, and so does a script nobody swept in.
  assert_eq!(
    routed(&ScriptRouter::new(WITH_REST), "123 !!!"),
    vec![("rest".to_owned(), "123 !!!".to_owned())]
  );
  assert_eq!(
    routed(&ScriptRouter::new(WITH_REST), "ᚠᚢᚦ"),
    vec![("rest".to_owned(), "ᚠᚢᚦ".to_owned())]
  );

  // And the homed runs are untouched — a catch-all takes only what nothing else does.
  assert_eq!(
    routed(&ScriptRouter::new(WITH_REST), "hello 日本語"),
    vec![
      ("en".to_owned(), "hello ".to_owned()),
      ("ja".to_owned(), "日本語".to_owned()),
    ]
  );
}

/// **WITHOUT A CATCH-ALL, THE REFUSAL STANDS** — the same corpus, the same run, the other answer.
#[test]
fn the_same_run_refuses_where_no_catch_all_is_declared() {
  let refusal = ScriptRouter::new(CORPUS)
    .route("hello বাংলা")
    .expect_err("Bengali has no home here and no catch-all exists");

  assert_eq!(refusal.tag(), "beng");
  assert!(
    refusal
      .to_string()
      .ends_with(", and no catch-all is declared"),
    "{refusal}"
  );
}

/// **DETERMINISM**: the same question routes the same way, every time.
#[test]
fn the_same_question_routes_the_same_way() {
  for question in [
    "",
    "hello",
    "日本語 report テキスト",
    "hello 世界 again かな more",
    "アイウ ABC 漢字",
  ] {
    let once = routed(&ScriptRouter::new(CORPUS), question);
    let twice = routed(&ScriptRouter::new(CORPUS), question);
    assert_eq!(once, twice, "at {question:?}");
  }
}

/// **NOTHING IS LOST AND NOTHING IS INVENTED**: every non-space character of the question ends up in
/// exactly one lane's probe, once and only once.
///
/// Whitespace is excluded from the comparison because the merge is allowed to add a separator where
/// two runs of one lane meet — and only there, which is what the count below would catch if it ever
/// started adding them anywhere else.
#[test]
fn every_run_reaches_exactly_one_lane() {
  let question = "hello 世界 again かな more 漢字";
  let dispatches = routed(&ScriptRouter::new(CORPUS), question);

  let mut asked: Vec<char> = dispatches
    .iter()
    .flat_map(|(_, probe)| probe.chars())
    .filter(|character| !character.is_whitespace())
    .collect();
  let mut wrote: Vec<char> = question.chars().filter(|c| !c.is_whitespace()).collect();
  asked.sort_unstable();
  wrote.sort_unstable();

  assert_eq!(asked, wrote, "the fan lost or duplicated content");
  assert_eq!(dispatches.len(), 2, "two lanes, however many runs");
}

/// **EVERY LANE, THE WHOLE QUESTION, AND THE MATCHED ONE LEANED ON** — the recommended default's
/// whole shape in one assertion.
#[test]
fn the_weighted_fan_probes_every_lane_and_emphasizes_the_matched_ones() {
  let fan = ScriptWeightedFan::<str>::new(CORPUS);
  let routed = fan.route("Rust guide").expect("cannot fail");

  assert_eq!(routed.len(), 2, "every declared lane is asked");
  assert!(
    routed.iter().all(|probe| probe.probe() == "Rust guide"),
    "each with the WHOLE question — never a per-run slice"
  );
  // The question is Latin, so `en` counts double and `ja` keeps the identity.
  assert_eq!(routed[0].lane(), LaneIdent::new("en"));
  assert_eq!(routed[0].weight(), 2.0);
  assert_eq!(routed[1].lane(), LaneIdent::new("ja"));
  assert_eq!(routed[1].weight(), 1.0);
}

/// **A MIXED QUESTION EMPHASIZES BOTH** — several runs, several lanes.
#[test]
fn several_runs_emphasize_several_lanes() {
  let routed = ScriptWeightedFan::<str>::new(CORPUS)
    .route("good report 日本語 テキスト")
    .expect("cannot fail");

  assert_eq!(routed.len(), 2);
  assert!(routed.iter().all(|probe| probe.weight() == 2.0));
  assert!(
    routed
      .iter()
      .all(|probe| probe.probe() == "good report 日本語 テキスト")
  );
}

/// **A RUN RESOLVING TO THE CATCH-ALL EMPHASIZES THE CATCH-ALL**, because that is where the gate
/// sends it.
#[test]
fn a_swept_script_question_emphasizes_the_catch_all() {
  static WITH_REST: &[Lane] = &[
    Lane::of(LaneIdent::new("en")).accepting(&[LaneIdent::new("latn")]),
    Lane::of(LaneIdent::new("ja")).accepting(&[LaneIdent::new("hani")]),
    Lane::of(LaneIdent::new("rest")).catch_all(),
  ];

  let routed = ScriptWeightedFan::<str>::new(WITH_REST)
    .route("বাংলা")
    .expect("cannot fail");

  assert_eq!(routed.len(), 3, "every lane is still asked");
  assert_eq!(routed[0].weight(), 1.0, "en");
  assert_eq!(routed[1].weight(), 1.0, "ja");
  assert_eq!(
    routed[2].weight(),
    2.0,
    "the catch-all is where Bengali resolves"
  );
}

/// **IT NEVER REFUSES.** A run the gate has no home for emphasizes nothing, and every lane is probed
/// either way — there is no dispatch to lose and nothing to report.
#[test]
fn the_weighted_fan_never_refuses_on_routing_grounds() {
  // CORPUS declares no catch-all, so `beng` and `cyrl` reach no lane at all — the very inputs
  // `ScriptRouter` refuses on.
  for question in ["বাংলা", "Привет", "123 !!!", "ᚠᚢᚦ", ""] {
    let routed: Result<_, core::convert::Infallible> =
      ScriptWeightedFan::<str>::new(CORPUS).route(question);
    let routed = routed.expect("this router cannot fail");
    assert_eq!(routed.len(), CORPUS.len(), "at {question:?}");
    assert!(
      routed.iter().all(|probe| probe.weight() == 1.0),
      "nothing resolved, so nothing is emphasized: {question:?}"
    );
  }
  // And the same questions ARE refused by the strict router, which is what each is for.
  assert!(ScriptRouter::new(CORPUS).route("বাংলা").is_err());
}

/// The knob round-trips, and turning it to the identity makes this `FanAll` exactly.
#[test]
fn the_emphasis_knob_round_trips() {
  assert_eq!(
    ScriptWeightedFan::<str>::new(CORPUS).emphasis(),
    ScriptWeightedFan::<str>::DEFAULT_EMPHASIS
  );

  let leaned = ScriptWeightedFan::<str>::new(CORPUS).with_emphasis(3.5);
  assert_eq!(leaned.emphasis(), 3.5);
  assert_eq!(leaned.route("Rust").expect("cannot fail")[0].weight(), 3.5);

  let mut held = ScriptWeightedFan::<str>::new(CORPUS);
  held.set_emphasis(1.0);
  let flat = held.route("Rust").expect("cannot fail");
  assert!(
    flat.iter().all(|probe| probe.weight() == 1.0),
    "an emphasis of one is FanAll, and needs no second type to say so"
  );
  assert_eq!(
    flat.iter().map(|p| p.probe().clone()).collect::<Vec<_>>(),
    routed(&FanAll::<str>::new(CORPUS), "Rust")
      .into_iter()
      .map(|(_, probe)| probe)
      .collect::<Vec<_>>()
  );
}