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 seam is HAND-WRITABLE, and every row it carries is a `const` anybody can build.
//!
//! What the macro reads off a declaration is asserted against its tokens in `ingraph-derive`, and
//! what it refuses is put through a real compile by `ingraph/tests/search_words.rs`. What is here is
//! the half neither of those can state: that a recipe nobody generated is a recipe, and that the
//! table its rows are written in is a public vocabulary rather than the macro's private one.

use core::num::NonZeroU32;

use super::{Binding, Bridge, DeclaredSearch, Member, Seat, SharedQuestion, TrySharedQuestion};

/// A recipe written by hand — no macro, no members, no doors.
struct Handwritten;

/// Every seat is defaulted, so joining is ONE line and it states the honest nothing.
impl DeclaredSearch for Handwritten {}

/// A recipe nobody generated answers every question a reader can ask it.
#[test]
fn a_hand_written_recipe_states_the_honest_nothing() {
  assert!(<Handwritten as DeclaredSearch>::SEATS.is_empty());
  assert!(<Handwritten as DeclaredSearch>::MEMBERS.is_empty());
  assert!(<Handwritten as DeclaredSearch>::LIMIT.is_none());
}

/// A recipe stated in full, in the shape the emission will write it.
struct Travel;

impl DeclaredSearch for Travel {
  const SEATS: &'static [Seat] = &[Seat::of("text")];
  const MEMBERS: &'static [Member] = &[
    Member::of("subs")
      .weighted(1.0)
      .deep(50)
      .bound(&[Binding::of("zh").shared(Bridge::Total)]),
    Member::of("shots")
      .weighted(2.0)
      .deep(100)
      .floored()
      .bound(&[
        Binding::of("text").shared(Bridge::Fallible).floored(),
        Binding::of("image"),
      ]),
  ];
  const LIMIT: Option<NonZeroU32> = NonZeroU32::new(20);
}

/// The whole record, read back the way a mounting declaration reads it.
#[test]
fn a_stated_recipe_carries_its_members_in_declaration_order() {
  const SEATS: &[Seat] = <Travel as DeclaredSearch>::SEATS;
  const MEMBERS: &[Member] = <Travel as DeclaredSearch>::MEMBERS;

  assert_eq!(SEATS.len(), 1);
  assert_eq!(SEATS[0].name(), "text");

  assert_eq!(MEMBERS[0].field(), "subs");
  assert_eq!(MEMBERS[0].weight(), Some(1.0));
  assert_eq!(MEMBERS[0].depth(), NonZeroU32::new(50));
  assert!(!MEMBERS[0].is_floored(), "no floor word, no floor");

  assert_eq!(MEMBERS[1].field(), "shots");
  assert_eq!(MEMBERS[1].weight(), Some(2.0));
  assert!(MEMBERS[1].is_floored());

  assert_eq!(
    <Travel as DeclaredSearch>::LIMIT,
    NonZeroU32::new(20),
    "the head's own number, where the head named one"
  );
}

/// An ARM carries the variant's name and how the broadcast reaches it — and NOT reading the
/// broadcast is a row of its own rather than a gap.
#[test]
fn an_arm_row_carries_the_crossing_the_word_chose() {
  const ARMS: &[Binding] = <Travel as DeclaredSearch>::MEMBERS[1].bindings();

  assert_eq!(ARMS[0].name(), "text");
  assert_eq!(ARMS[0].bridge(), Some(Bridge::Fallible));
  assert!(ARMS[0].is_floored());

  assert_eq!(ARMS[1].name(), "image");
  assert_eq!(
    ARMS[1].bridge(),
    None,
    "an arm that wrote no `shared` is asked its own question"
  );
}

/// The two questions a reader spends the vocabulary on, over every word in it.
#[test]
fn every_bridge_states_whether_it_can_fail_and_who_wrote_it() {
  const TABLE: [(Bridge, bool, bool); 4] = [
    (Bridge::Total, false, false),
    (Bridge::Fallible, true, false),
    (Bridge::Hook, false, true),
    (Bridge::FallibleHook, true, true),
  ];

  for (bridge, fallible, hooked) in TABLE {
    assert_eq!(bridge.fallible(), fallible, "{bridge:?}");
    assert_eq!(bridge.hooked(), hooked, "{bridge:?}");
  }
}

/// A ROW IS A `const` ANYBODY CAN BUILD, which is what makes the table public rather than emitted.
#[test]
fn the_rows_are_const_constructible_outside_an_expansion() {
  const ROSTER: &[Member] = &[Member::of("subs"), Member::of("shots").weighted(2.0)];

  assert_eq!(ROSTER[0].field(), "subs");
  assert_eq!(ROSTER[0].weight(), None, "no word, no coefficient stated");
  assert_eq!(ROSTER[1].weight(), Some(2.0));
  assert!(ROSTER[1].bindings().is_empty());
}

/// The seat MARKERS a recipe mints — one per declared `shared(…)` seat, never a value anybody holds.
struct Text;
struct Point;

/// One member's question, reachable from BOTH seats — which is the whole reason the crossing is
/// keyed on a marker rather than written as a bare conversion.
#[derive(Debug, PartialEq)]
struct MemberQuestion(String);

impl SharedQuestion<Text, str> for MemberQuestion {
  fn from_shared(shared: &str) -> Option<Self> {
    (!shared.is_empty()).then(|| Self(shared.to_owned()))
  }
}

impl SharedQuestion<Point, [f32]> for MemberQuestion {
  fn from_shared(shared: &[f32]) -> Option<Self> {
    Some(Self(format!("{} coordinates", shared.len())))
  }
}

/// A member that answers the broadcast FALLIBLY, and only fallibly.
#[derive(Debug, PartialEq)]
struct Picky(String);

impl TrySharedQuestion<Text, str> for Picky {
  type Error = &'static str;

  fn try_from_shared(shared: &str) -> Result<Option<Self>, Self::Error> {
    if shared.len() > 3 {
      Ok(Some(Self(shared.to_owned())))
    } else {
      Err("too short to ask")
    }
  }
}

/// **ONE QUESTION READS TWO BROADCASTS, and the SEAT is what tells them apart.** Written as two
/// impls of one trait, which is only coherent because the marker is a parameter — a bare
/// `From<&str>` beside a `From<&[f32]>` would have said nothing about WHICH seat fed which.
#[test]
fn the_seat_marker_is_what_keeps_two_crossings_apart() {
  assert_eq!(
    <MemberQuestion as SharedQuestion<Text, str>>::from_shared("harbour"),
    Some(MemberQuestion("harbour".to_owned())),
  );
  assert_eq!(
    <MemberQuestion as SharedQuestion<Point, [f32]>>::from_shared(&[0.0, 1.0]),
    Some(MemberQuestion("2 coordinates".to_owned())),
  );
}

/// **THE HONEST EMPTY IS `None` AND NOT A REFUSAL** — a member with nothing to ask is structurally
/// absent from the fold, which is the participation rule read at the question's own crossing.
#[test]
fn a_member_with_nothing_to_ask_answers_none() {
  assert_eq!(
    <MemberQuestion as SharedQuestion<Text, str>>::from_shared(""),
    None,
  );
}

/// **EVERY TOTAL CROSSING IS A FALLIBLE ONE**, through the blanket — so a door written against the
/// `Try` face alone reaches an author who implemented either, which is what keeps ONE face on the
/// consumer's side.
#[test]
fn the_try_face_absorbs_the_total_one() {
  fn asked<Q, S>(shared: &S) -> Result<Option<Q>, Q::Error>
  where
    Q: TrySharedQuestion<Text, S>,
    S: ?Sized,
  {
    Q::try_from_shared(shared)
  }

  assert_eq!(
    asked::<MemberQuestion, str>("harbour"),
    Ok(Some(MemberQuestion("harbour".to_owned()))),
  );
  assert_eq!(
    asked::<Picky, str>("harbour"),
    Ok(Some(Picky("harbour".to_owned())))
  );
  assert_eq!(asked::<Picky, str>("no"), Err("too short to ask"));
}

/// **THE TOTAL FACE'S REFUSAL TYPE IS `Infallible`**, which is what says *this crossing cannot fail*
/// in the type system rather than in prose.
#[test]
fn a_total_crossing_refuses_with_a_type_that_has_no_value() {
  const _: fn(
    core::convert::Infallible,
  ) -> <MemberQuestion as TrySharedQuestion<Text, str>>::Error = core::convert::identity;
}