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 THREE ROADS, exercised — and the CONVERTER ASSERTION LAW, stated as measurements rather
//! than as prose.
//!
//! Beside [`tests`](super::tests) rather than inside it, on this repository's own precedent: one
//! file per thing being proved. That file proves the SINK — a push is a segment, the buffer is
//! never handed out whole. This one proves what the declaration's words do with it.
//!
//! # The law, and which half of it a document can carry
//!
//! *Round-trip always; ORDER only where indexed — a joined list needs only the first.* Both halves
//! are asserted below for the two builtins, because both are checkable there. What is NOT asserted,
//! and cannot be, is a round-trip through a DECLARED converter: a full-text document has no `into`
//! leg — it is written and searched, never hydrated back — so there is no inverse for a generated
//! assertion to call. That is the axis the address row ([`Field`](crate::Field)) has and this one
//! does not,
//! and it is why the law's teeth here are the framework's own builtins: the two roads that ARE
//! written by the framework are the two it can prove.

use super::{BoxWriter, Searchable};

/// The segments a road produced, as a `Vec` a test can compare whole.
fn segments(writer: &BoxWriter) -> Vec<&str> {
  writer.segments().collect()
}

/// THE IDENTITY ROAD over the shipped shapes. Not an allowlist — the blanket is over `AsRef<str>`,
/// so what is listed here is what `std` already says is text, and a domain type joins by
/// implementing the same trait.
#[test]
fn the_identity_road_takes_every_shape_std_already_calls_text() {
  /// One value's road, run into a fresh sink.
  fn road(value: &(impl Searchable + ?Sized)) -> Vec<String> {
    let mut out = BoxWriter::new();
    value.write(&mut out);
    out.segments().map(str::to_owned).collect()
  }

  let owned = String::from("a red car");
  let cow: std::borrow::Cow<'_, str> = std::borrow::Cow::Borrowed("a red car");
  let boxed: Box<str> = Box::from("a red car");
  let sliced: &str = "a red car";

  assert_eq!(road(&owned), ["a red car"]);
  assert_eq!(road(sliced), ["a red car"]);
  assert_eq!(road(&cow), ["a red car"]);
  assert_eq!(road(&boxed), ["a red car"]);
  // A BORROW rides its referent's row, which is what makes `&entry.field` — the only shape an
  // emitted road ever writes — reach the same impl the value would.
  assert_eq!(road(&&owned), ["a red car"]);
}

/// A DOMAIN TYPE joins the identity road with one impl on itself — which is the claim the
/// `on_unimplemented` note makes, so it is the claim a test has to keep true.
#[test]
fn a_domain_type_joins_the_identity_road_by_being_readable_as_text() {
  struct Caption(String);

  impl AsRef<str> for Caption {
    fn as_ref(&self) -> &str {
      &self.0
    }
  }

  let mut out = BoxWriter::new();
  Searchable::write(&Caption("a blue sky".to_owned()), &mut out);
  assert_eq!(segments(&out), ["a blue sky"]);
}

/// ROUND-TRIP, the `multi` road: the segments ARE the values, so recovering them is reading them
/// back and no inverse function is involved at all. The strongest form the obligation takes.
#[test]
fn the_multi_road_round_trips_by_construction() {
  let labels = vec!["red car".to_owned(), "blue sky".to_owned(), String::new()];
  let mut out = BoxWriter::new();
  out.push_each(&labels);
  assert_eq!(segments(&out), ["red car", "blue sky", ""]);
}

/// ROUND-TRIP, the `join` road, and it is CONDITIONAL: splitting the one segment on the separator
/// recovers the values exactly while no value contains the separator.
#[test]
fn the_join_road_round_trips_while_no_value_holds_the_separator() {
  let labels = vec!["red car".to_owned(), "blue sky".to_owned()];
  let mut out = BoxWriter::new();
  out.push_joined(&labels, ", ");
  let joined = segments(&out);
  assert_eq!(joined, ["red car, blue sky"]);
  assert_eq!(
    joined[0].split(", ").collect::<Vec<_>>(),
    ["red car", "blue sky"]
  );
}

/// THE CONDITION'S FAILURE, pinned rather than trusted. A value holding the separator makes the
/// joined form non-injective — three values come back out of two — and the framework cannot check
/// it: which separator is safe is a fact about the DATA, and the declaration is the party choosing.
///
/// It is a measurement and not a defect: `join` is documented as the road where a phrase may match
/// ACROSS two values, and a separator inside a value is the same collapse taken one step further.
/// What the test buys is that nobody later reads the round-trip obligation as unconditional.
#[test]
fn a_value_holding_the_separator_is_where_the_join_road_stops_round_tripping() {
  let labels = vec!["red, blue".to_owned(), "sky".to_owned()];
  let mut out = BoxWriter::new();
  out.push_joined(&labels, ", ");
  let joined = segments(&out);
  assert_eq!(joined, ["red, blue, sky"]);
  assert_eq!(
    joined[0].split(", ").count(),
    3,
    "two values went in and three come back out — the separator is not recoverable"
  );
}

/// ORDER, both roads. The obligation binds *only where indexed*, and a document's segments are not
/// sorted by anything — so a joined list needs only the round-trip half. Order is preserved anyway,
/// because both builtins are loops in the iterator's own order, and a test is what keeps that from
/// quietly becoming a set.
#[test]
fn both_roads_preserve_the_order_their_values_were_written_in() {
  let labels = vec!["a".to_owned(), "b".to_owned(), "c".to_owned()];
  let mut each = BoxWriter::new();
  each.push_each(&labels);
  assert_eq!(segments(&each), ["a", "b", "c"]);

  let mut joined = BoxWriter::new();
  joined.push_joined(&labels, "-");
  assert_eq!(segments(&joined), ["a-b-c"]);
}

/// THE DIFFERENCE THE TWO ROADS EXIST FOR, stated over the same input: one segment against three.
/// It is the boundary a positional engine puts a gap at, so a declaration picking the wrong word
/// gets a different corpus and not merely a different spelling.
#[test]
fn the_two_roads_disagree_about_exactly_one_thing() {
  let labels = vec!["a".to_owned(), "b".to_owned(), "c".to_owned()];
  let mut each = BoxWriter::new();
  each.push_each(&labels);
  let mut joined = BoxWriter::new();
  joined.push_joined(&labels, " ");
  assert_eq!(each.segments().len(), 3);
  assert_eq!(joined.segments().len(), 1);
}