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
//! The rows [`subtag_citizen`](super::subtag_citizen) writes for all three at once, asserted once
//! for all three: the DOCUMENT form, the DOCUMENT READ and the KEY.
//!
//! Every other row the macro emits is about ONE type's grammar and is asserted in that type's own
//! file — the door, the fold, the refusals. These three are about the SHAPE the three share, and a
//! shape asserted three times is three places for one claim to drift.
//!
//! The bind and the SQL decode are not here for `id/storage/tests.rs`'s reason: a bind renders SQL,
//! so what proves it is an engine taking the statement, which `tests/subtag_citizen.rs` is. A BSON
//! value is a value and needs no engine to be looked at, which is what makes the MONGO read
//! assertable here beside the write it mirrors.

use smol_bytes::Utf8Bytes;

use super::{Language, Region, ScriptSubtag};

/// **A SUBTAG CARRIES AS BSON's `String`, HOLDING THE CANONICAL WORD** — the same text the `TEXT`
/// column binds and the same bytes the cursor writes.
///
/// The fold is the second half and the one that matters at a boundary: an mkv's `GER` and an mp4's
/// `deu` reach a document as the `de` a query built from `de` compares against, because both sides
/// canonicalised before they met.
#[cfg(feature = "mongo")]
#[test]
fn a_subtag_carries_as_the_canonical_word() {
  use crate::MongoCarrier;
  use bson::Bson;

  assert_eq!(
    Language::new("de").unwrap().to_bson(),
    Bson::String(String::from("de"))
  );
  assert_eq!(
    ScriptSubtag::new("Hans").unwrap().to_bson(),
    Bson::String(String::from("Hans"))
  );
  assert_eq!(
    Region::new("419").unwrap().to_bson(),
    Bson::String(String::from("419")),
    "a numeric region is a STRING and never a BSON number — the leading-zero argument the wire \
     door makes, one layer down",
  );

  for (sent, canonical) in [("GER", "de"), ("deu", "de"), ("iw", "he"), ("DE", "de")] {
    assert_eq!(
      Language::new(sent).unwrap().to_bson(),
      Language::new(canonical).unwrap().to_bson(),
      "`{sent}` and `{canonical}` reach one document",
    );
  }

  // The BSON the carrier writes is the BSON the type's own text is, so a row that had spelled its
  // own conversion would agree today and be free to stop.
  assert_eq!(
    ScriptSubtag::new("latn").unwrap().to_bson(),
    Bson::String(String::from(ScriptSubtag::new("Latn").unwrap().as_str())),
  );
}

/// **THE READ IS THE WRITE'S MIRROR** — a subtag written through [`MongoCarrier`] reads back through
/// [`MongoExtract`] as the same value, for all three at once.
///
/// The carrier's own round trip, checked here rather than left to the shared suite's generic
/// `round_trip` helper: that helper lives in `query::mongo::extract::tests` and is private to it, so
/// the three subtags' own identity is proven beside their write above instead.
#[cfg(feature = "mongo")]
#[test]
fn a_subtag_reads_back_the_document_it_carried_as() {
  use crate::{MongoCarrier, query::mongo::MongoExtract};

  for sent in ["de", "ger", "iw", "und"] {
    let language = Language::new(sent).unwrap();
    let written = language.to_bson();
    assert_eq!(Language::extract(Some(&written)), Ok(language), "`{sent}`");
  }

  for sent in ["Hans", "latn", "Hant"] {
    let script = ScriptSubtag::new(sent).unwrap();
    let written = script.to_bson();
    assert_eq!(
      ScriptSubtag::extract(Some(&written)),
      Ok(script),
      "`{sent}`"
    );
  }

  for sent in ["DE", "419", "bu"] {
    let region = Region::new(sent).unwrap();
    let written = region.to_bson();
    assert_eq!(Region::extract(Some(&written)), Ok(region), "`{sent}`");
  }
}

/// **THE REFUSAL NAMES BOTH ABSENCES AND THE WRONG TYPE, BY NAME** — the same three-way vocabulary
/// every other row in this register answers a read with.
#[cfg(feature = "mongo")]
#[test]
fn a_subtag_read_refuses_absence_and_the_wrong_type_by_name() {
  use crate::query::mongo::{MongoExtract, MongoTypeError};
  use bson::Bson;

  assert_eq!(Language::extract(None), Err(MongoTypeError::Absent));
  assert_eq!(
    Language::extract(Some(&Bson::Null)),
    Err(MongoTypeError::wrong_type("string", "null"))
  );
  assert_eq!(
    ScriptSubtag::extract(Some(&Bson::Int32(4))),
    Err(MongoTypeError::wrong_type("string", "int")),
    "the alias NAMES what was found rather than spelling `not a string`",
  );
  assert_eq!(
    Region::extract(Some(&Bson::Document(bson::doc! {}))),
    Err(MongoTypeError::wrong_type("string", "object"))
  );
}

/// **A `string` THAT DOES NOT NAME A SUBTAG IS A READ ERROR**, rather than a value whose type says
/// it cannot exist — [`MongoExtract`]'s own mirror of `id/storage/tests.rs`'s SQL claim.
#[cfg(feature = "mongo")]
#[test]
fn a_subtag_read_refuses_a_string_that_names_no_subtag() {
  use crate::query::mongo::{MongoExtract, MongoTypeError};
  use bson::Bson;

  assert!(matches!(
    Language::extract(Some(&Bson::String(String::from("1")))),
    Err(MongoTypeError::Range(_))
  ));
  assert!(matches!(
    ScriptSubtag::extract(Some(&Bson::String(String::new()))),
    Err(MongoTypeError::Range(_))
  ));
  assert!(matches!(
    Region::extract(Some(&Bson::String(String::from("ZZZZ")))),
    Err(MongoTypeError::Range(_))
  ));
}

/// **THE READ CANONICALISES, WHICH IS WHAT A HAND-WRITTEN DOCUMENT PROVES AND A ROUND TRIP CANNOT.**
///
/// `MongoCarrier` writes CANONICAL text only — `Language::new("GER")?.to_bson()` is already `"de"`
/// — so no write path this crate has can ever PRODUCE a document holding `"GER"`. The only way to
/// ask what the READ does with one is to build it by hand, which is what a foreign writer's document
/// — another driver, an older declaration, a migration — actually is. The answer mirrors the SQL
/// decode's own re-validation: the door FOLDS rather than refuses, so a document holding `"GER"`
/// reads back as the same value as one holding `"de"`.
#[cfg(feature = "mongo")]
#[test]
fn a_hand_written_document_folds_at_the_read_door_too() {
  use crate::query::mongo::MongoExtract;
  use bson::Bson;

  let foreign = Bson::String(String::from("GER"));
  let canonical = Bson::String(String::from("de"));

  assert_eq!(
    Language::extract(Some(&foreign)),
    Language::extract(Some(&canonical)),
    "an mkv's alpha-3 spelling and the canonical one read as ONE value",
  );
  assert_eq!(
    Language::extract(Some(&foreign)),
    Ok(Language::new("de").unwrap())
  );

  // The same fold, over the region's OWN column: `Preferred-Value`, not case.
  assert_eq!(
    Region::extract(Some(&Bson::String(String::from("BU")))),
    Region::extract(Some(&Bson::String(String::from("MM")))),
    "a deprecated region code and its preferred value read as ONE value",
  );

  // Case alone is the script's fold, and a hand-written lowercase document proves it the same way.
  assert_eq!(
    ScriptSubtag::extract(Some(&Bson::String(String::from("hans")))),
    Ok(ScriptSubtag::new("Hans").unwrap()),
  );
}

/// **A SUBTAG IS A KEY, AND ITS SEGMENT IS ITS DELEGATE'S** — the whole content of the transparency
/// assertion, measured rather than asserted about.
///
/// `Segments::push` is generic over the sealed vocabulary, so the call below is the ADMISSION as
/// much as the rendering: a type with no row does not compile here. What is compared is the segment
/// against the one the [`Utf8Bytes`] it delegates to renders — if the two ever parted, one value
/// would address two files.
#[test]
fn a_subtag_addresses_exactly_the_path_its_text_addresses() {
  fn keyed<I: crate::store::Segment>(id: &I) -> Vec<String> {
    let mut segments = crate::store::Segments::new();
    segments.push(id);
    segments.as_slice().to_vec()
  }

  fn delegated(word: &str) -> Vec<String> {
    keyed(&Utf8Bytes::from(word))
  }

  assert_eq!(keyed(&Language::new("de").unwrap()), delegated("de"));
  assert_eq!(
    keyed(&ScriptSubtag::new("Hans").unwrap()),
    delegated("Hans")
  );
  assert_eq!(keyed(&Region::new("DE").unwrap()), delegated("DE"));

  // The delegate is the FOLDED text, which is what makes the key useful: two containers' spellings
  // of German are one value before anything addresses them, so they are one file and not two.
  assert_eq!(
    keyed(&Language::new("ger").unwrap()),
    keyed(&Language::new("de").unwrap()),
  );
  assert_eq!(
    keyed(&Region::new("bu").unwrap()),
    keyed(&Region::new("MM").unwrap()),
    "the region's preferred-value fold reaches the address too",
  );
}

/// **THE COMPOSITES MAKE NO SUCH CLAIM**, and the vocabulary is what refuses them.
///
/// A delegation is TRANSPARENCY over one member; [`LanguageId`](super::LanguageId) holds four values
/// and [`DetectedLanguage`](super::DetectedLanguage) five, so neither has a member to be transparent
/// to. The assertion is a compilation: the three subtags resolve the bound and the row that would
/// have admitted a composite is not written, so a key position naming one is `E0277` at the
/// declaration.
#[test]
fn the_key_vocabulary_admits_the_three_subtags() {
  const fn admits<I: crate::Id>() {}

  const _: () = admits::<Language>();
  const _: () = admits::<ScriptSubtag>();
  const _: () = admits::<Region>();

  // And the delegate the three are admitted ON, which is what keeps the chain grounded in a MEASURED
  // member rather than in another delegation.
  const _: () = admits::<Utf8Bytes>();
}