ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! **THE NUMBER TIERS** — the three chains a declaration's numbers resolve through, and the one
//! argument its wall reaches.
//!
//! ```text
//!   field-skin `first` → field `limit` → container-skin `first` → container `limit` → 20
//!                                                                    the WIRE DEFAULT
//!   (request `depth`) → field `depth` → container `depth` → the whole chain above
//!                                                                    the POOL DEPTH
//!   min(everything, field `ceiling` else container `ceiling`)
//!                                                                    the WALL
//! ```
//!
//! Beside [`depth`](super::depth) on this directory's one-file-per-thing precedent: that file proves
//! every fetch site resolves through the framework's law, and this one proves WHAT the second
//! argument of that law now says — the two claims are separable and a reader looking for either
//! should not have to read the other.
//!
//! # Why the chains are pinned at the MODEL rather than only at the tokens
//!
//! A chain is an ORDER, and an order is only observable where two tiers disagree. Reading it off an
//! emission would mean minting a declaration per disagreement and grepping for a literal; reading it
//! off the model states each precedence as one equation, and the emission's own half — that the wall
//! reaches `route_depth` and nothing else — is asserted below over the tokens where it belongs.

use core::num::NonZeroU32;

use super::{
  ElectionBackend, FRAMEWORK_LIMIT, FieldNumbers, IndexBackend, IndexGraphql, IndexModel, Numbers,
  tests::{document, two_elections},
};
use crate::model::GraphqlKind;

fn ident(name: &str) -> syn::Ident {
  syn::Ident::new(name, proc_macro2::Span::call_site())
}

fn n(count: u32) -> Option<NonZeroU32> {
  Some(NonZeroU32::new(count).expect("the fixture numbers are not zero"))
}

/// The declaration this file reads its chains off — two vector elections, the captions first.
fn shots() -> IndexModel {
  two_elections()
}

/// The election every claim below is about.
fn clip() -> syn::Ident {
  ident("caption_embedding")
}

/// The emission with its spaces taken out — what a claim about a call is read off.
fn tight(model: &IndexModel) -> String {
  model.emit().to_string().split_whitespace().collect()
}

/// One field's entry, with whatever a test wrote on it.
fn wrote(field: &str, numbers: Numbers, first: Option<NonZeroU32>) -> FieldNumbers {
  FieldNumbers {
    field: ident(field),
    numbers,
    skins: match first {
      Some(_) => vec![ElectionBackend {
        first,
        ..ElectionBackend::of(GraphqlKind::AsyncGraphql)
      }],
      None => Vec::new(),
    },
  }
}

/// The container's skin, carrying whatever `first` a test wrote.
fn dressed(first: Option<NonZeroU32>) -> IndexGraphql {
  IndexGraphql {
    backends: vec![IndexBackend {
      first,
      ..IndexBackend::of(GraphqlKind::AsyncGraphql)
    }],
  }
}

// -------------------------------------------------------------------------------------------
// THE WIRE DEFAULT, one step of the chain at a time
// -------------------------------------------------------------------------------------------

/// **A DECLARATION THAT WRITES NOTHING PUBLISHES THE FRAMEWORK'S OWN NUMBER.** Twenty, on the
/// ruling's own words, and it is the floor of the chain rather than a tier of it.
#[test]
fn an_unwritten_declaration_publishes_the_framework_number() {
  let model = shots();
  assert_eq!(
    model.wire_first(GraphqlKind::AsyncGraphql, Some(&clip())),
    FRAMEWORK_LIMIT,
  );
  assert_eq!(FRAMEWORK_LIMIT.get(), 20);
}

/// **EVERY STEP BEATS THE ONE BELOW IT**, asserted as four disagreements rather than four presences.
///
/// A chain read off a model that only ever writes one tier would pass for any order at all: what
/// makes the claim about PRECEDENCE is that each case writes the loser too, and the loser is a
/// different number each time so a wrong pick is a wrong assertion rather than a coincidence.
#[test]
fn each_tier_beats_the_one_below_it() {
  let kind = GraphqlKind::AsyncGraphql;

  // container `limit` over the framework's 20.
  let mut model = shots();
  model.numbers.limit = n(7);
  assert_eq!(model.wire_first(kind, Some(&clip())), n(7).unwrap());

  // container-skin `first` over container `limit`.
  model.graphql = Some(dressed(n(9)));
  assert_eq!(model.wire_first(kind, Some(&clip())), n(9).unwrap());

  // field `limit` over both container tiers.
  model.field_numbers = vec![wrote(
    "caption_embedding",
    Numbers {
      limit: n(11),
      ..Numbers::default()
    },
    None,
  )];
  assert_eq!(model.wire_first(kind, Some(&clip())), n(11).unwrap());

  // field-skin `first` over everything.
  model.field_numbers = vec![wrote(
    "caption_embedding",
    Numbers {
      limit: n(11),
      ..Numbers::default()
    },
    n(13),
  )];
  assert_eq!(model.wire_first(kind, Some(&clip())), n(13).unwrap());
}

/// **ONE FIELD'S NUMBER IS ONE FIELD'S** — the second election falls to the container, which is what
/// makes the tier a TIER rather than a declaration-wide switch written in an odd place.
#[test]
fn a_fields_number_does_not_reach_the_field_beside_it() {
  let kind = GraphqlKind::AsyncGraphql;
  let mut model = shots();
  model.numbers.limit = n(7);
  model.field_numbers = vec![wrote(
    "caption_embedding",
    Numbers {
      limit: n(11),
      ..Numbers::default()
    },
    None,
  )];
  assert_eq!(model.wire_first(kind, Some(&clip())), n(11).unwrap());
  assert_eq!(
    model.wire_first(kind, Some(&ident("image_embedding"))),
    n(7).unwrap(),
    "a sibling election took the number the other one wrote",
  );
}

/// **A SKIN'S NUMBER IS ONE BACKEND'S.** The `first` a declaration writes for one library is not a
/// number another library's schema publishes — the axis law, read at the one word that is not a
/// name.
#[test]
fn a_skins_number_belongs_to_the_backend_that_wrote_it() {
  let mut model = shots();
  model.numbers.limit = n(7);
  model.graphql = Some(dressed(n(9)));
  assert_eq!(
    model.wire_first(GraphqlKind::AsyncGraphql, Some(&clip())),
    n(9).unwrap(),
  );
  // There is one backend in this framework today, so the claim is stated where it can be: the skin
  // is found BY KIND, and a lookup that ignored the kind would answer `9` for any word at all.
  assert!(
    model
      .graphql
      .as_ref()
      .and_then(|block| block.skin(GraphqlKind::AsyncGraphql))
      .is_some_and(|skin| skin.first == n(9)),
  );
}

// -------------------------------------------------------------------------------------------
// THE POOL DEPTH
// -------------------------------------------------------------------------------------------

/// **AN UNDEPTHED DECLARATION FALLS TO ITS OWN LIMIT CHAIN**, which is the same statement
/// `Route::depth`'s `None` makes one grain up: *as deep as the answer is wide*.
#[test]
fn an_unwritten_depth_is_the_whole_limit_chain() {
  let kind = GraphqlKind::AsyncGraphql;
  let mut model = shots();
  model.numbers.limit = n(7);
  assert_eq!(model.pool_depth(kind, Some(&clip())), n(7).unwrap());

  model.graphql = Some(dressed(n(9)));
  assert_eq!(
    model.pool_depth(kind, Some(&clip())),
    n(9).unwrap(),
    "the fall-through reads the WHOLE chain rather than the bones alone",
  );
}

/// **A WRITTEN DEPTH IS SPENT, AND THE FIELD'S BEATS THE CONTAINER'S** — the same two tiers, and a
/// depth is never widened up to the limit beside it.
#[test]
fn a_written_depth_wins_at_the_tier_that_wrote_it() {
  let kind = GraphqlKind::AsyncGraphql;
  let mut model = shots();
  model.numbers.limit = n(7);
  model.numbers.depth = n(200);
  assert_eq!(model.pool_depth(kind, Some(&clip())), n(200).unwrap());

  model.field_numbers = vec![wrote(
    "caption_embedding",
    Numbers {
      depth: n(50),
      ..Numbers::default()
    },
    None,
  )];
  assert_eq!(model.pool_depth(kind, Some(&clip())), n(50).unwrap());
  assert_eq!(
    model.pool_depth(kind, Some(&ident("image_embedding"))),
    n(200).unwrap(),
  );
}

// -------------------------------------------------------------------------------------------
// THE WALL — over everything, and never a preference
// -------------------------------------------------------------------------------------------

/// **THE WALL CAPS THE PUBLISHED DEFAULT.**
///
/// A schema whose `first:` literal sat above the ceiling would promise a page size the fetch
/// silently cuts, which is the one thing an SDL default must not be able to do. Both directions are
/// asserted, because a `min` that only ever fired one way would be indistinguishable from the wall
/// REPLACING the chain — the exact confusion the #293-B ruling corrected one grain down.
#[test]
fn the_wall_caps_the_published_default_and_does_not_replace_it() {
  let kind = GraphqlKind::AsyncGraphql;
  let mut model = shots();
  model.numbers.limit = n(500);
  model.numbers.ceiling = n(100);
  assert_eq!(model.wire_first(kind, Some(&clip())), n(100).unwrap());

  model.numbers.limit = n(10);
  assert_eq!(
    model.wire_first(kind, Some(&clip())),
    n(10).unwrap(),
    "the wall replaced the chain instead of capping it",
  );
}

/// **THE WALL CAPS THE POOL DEPTH TOO**, which is the fetch the ruling was actually decided on: a
/// request writing half a million against a wall of a hundred fetches a hundred, and a DECLARATION
/// writing it is no different.
#[test]
fn the_wall_caps_a_written_depth() {
  let kind = GraphqlKind::AsyncGraphql;
  let mut model = shots();
  model.numbers.depth = n(500_000);
  model.numbers.ceiling = n(100);
  assert_eq!(model.pool_depth(kind, Some(&clip())), n(100).unwrap());
}

/// **THE FIELD'S WALL BEATS THE CONTAINER'S, AND AN ABSENT ONE IS OPENNESS.**
///
/// Two tiers and no third: there is no framework ceiling and there never will be one, because a
/// number invented on an author's behalf would be the framework deciding what a deployment can
/// afford.
#[test]
fn the_wall_has_two_tiers_and_no_framework_floor() {
  let mut model = shots();
  assert_eq!(model.declared_ceiling(Some(&clip())), None);

  model.numbers.ceiling = n(1_000);
  assert_eq!(model.declared_ceiling(Some(&clip())), n(1_000));

  model.field_numbers = vec![wrote(
    "caption_embedding",
    Numbers {
      ceiling: n(100),
      ..Numbers::default()
    },
    None,
  )];
  assert_eq!(model.declared_ceiling(Some(&clip())), n(100));
  assert_eq!(
    model.declared_ceiling(Some(&ident("image_embedding"))),
    n(1_000),
    "a sibling election took the wall the other one wrote",
  );
}

// -------------------------------------------------------------------------------------------
// THE EMISSION'S HALF — the wall reaches `route_depth` and nothing else
// -------------------------------------------------------------------------------------------

/// **AN UNWRITTEN DECLARATION EXPANDS TO EXACTLY THE TOKENS IT DID BEFORE THE WORD EXISTED.**
///
/// The additive claim, and it is the one that keeps the word free: every emitted call passed
/// `::core::option::Option::None` for the wall while there was no word to write, and a declaration
/// that writes none still does. A number appearing here without a declaration asking for it would be
/// the framework inventing a bound.
#[test]
fn a_declaration_that_writes_no_wall_still_passes_none() {
  let emitted = tight(&shots());
  assert!(
    emitted.contains("route_depth("),
    "the fixture resolves its fetches through the law: {emitted}",
  );
  assert!(
    !emitted.contains("NonZeroU32::new("),
    "a wall nobody declared reached an emitted call: {emitted}",
  );
}

/// **THE DECLARED WALL REACHES THE LAW'S SECOND ARGUMENT**, at the width a declaration publishes one
/// at, and it reaches nothing else.
///
/// The second assertion is the wall law itself, read off the tokens: a protective number never
/// crosses the wire, so the number that caps a fetch must appear in the fetch and in no package, no
/// input face and no SDL string.
#[test]
fn a_declared_wall_reaches_the_law_and_no_other_surface() {
  let mut model = shots();
  model.numbers.ceiling = n(100);
  let emitted = tight(&model);
  assert!(
    emitted.contains("route_depth(::core::option::Option::and_then(__ingraph_route,"),
    "{emitted}",
  );
  assert!(
    emitted
      .contains("::core::option::Option::as_ref(&::core::num::NonZeroU32::new(100u32)),limit,"),
    "the declared wall did not arrive at the law's second argument: {emitted}",
  );
  assert!(
    !emitted.contains("\"ceiling\""),
    "a protective number reached a wire surface: {emitted}",
  );
}

/// **THE ELECTION'S OWN WALL IS THE ONE ITS ROUTE IS CAPPED BY**, which is what makes the tier real
/// in the emission rather than only in the model.
#[test]
fn each_route_is_capped_by_its_own_elections_wall() {
  let mut model = shots();
  model.numbers.ceiling = n(1_000);
  model.field_numbers = vec![wrote(
    "caption_embedding",
    Numbers {
      ceiling: n(100),
      ..Numbers::default()
    },
    None,
  )];
  let emitted = tight(&model);
  assert!(emitted.contains("NonZeroU32::new(100u32)"), "{emitted}");
  assert!(
    emitted.contains("NonZeroU32::new(1000u32)"),
    "the second election kept the container's wall: {emitted}",
  );
}

/// **A FULL-TEXT DECLARATION'S UNSUFFIXED SUBJECT TAKES THE CONTAINER'S WALL**, which is the whole
/// chain at a grain that has no election to name.
#[test]
fn the_unelected_subject_is_capped_by_the_container() {
  let mut model = document();
  model.numbers.ceiling = n(64);
  let emitted = tight(&model);
  assert!(emitted.contains("NonZeroU32::new(64u32)"), "{emitted}");
}