ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! What the root query emits, read back out of the tokens: the projection's SHAPE, the membership
//! filter, and the two names that are not one name.

use crate::graph::GraphModel;

/// A root with the members named, and nothing else a query cares about.
fn root(queried: &[&str]) -> GraphModel {
  let nodes: Vec<syn::Type> = ["media::Reel", "media::Take", "media::Cutter"]
    .iter()
    .map(|path| syn::parse_str(path).expect("a node path"))
    .collect();
  GraphModel {
    krate: syn::parse_quote!(::ingraph),
    vis: syn::parse_quote!(pub),
    name: syn::parse_quote!(Media),
    nodes,
    mounts: vec![
      syn::parse_quote!(reels),
      syn::parse_quote!(takes),
      syn::parse_quote!(cutters),
    ],
    queried: queried
      .iter()
      .map(|path| syn::parse_str(path).expect("a node path"))
      .collect(),
    interfaces: Vec::new(),
    fused: Vec::new(),
    resources: Vec::new(),
    origins: Vec::new(),
    // No third-party engine word: these models are about the list its fields are.
    engines: Vec::new(),
    retired: None,
    generations: None,
  }
}

/// The emitted tokens, whitespace-normalised, which is how every token assertion in this crate reads
/// an emission back.
fn emitted(model: &GraphModel) -> String {
  model.query().to_string()
}

/// **THE FOLD PROJECTS TWO HOPS**, which is the ruled mechanism rather than a spelling: the wire face
/// is `Transformer`'s member and the query unit is that member's own trait's, so the member type is
/// never named and a missing impl is a compile error at the root.
#[test]
fn a_member_is_reached_by_projecting_through_the_transformer_line() {
  let tokens = emitted(&root(&["media::Reel"]));

  assert!(
    tokens.contains(
      "<< media :: Reel as :: ingraph :: __private :: transform :: Transformer > :: Graphql as :: \
       ingraph :: __private :: transform :: Graphql > :: Query"
    ),
    "{tokens}"
  );
  assert!(
    !tokens.contains("ReelQueries"),
    "the unit's NAME is never written — the projection is what names it:\n{tokens}"
  );
}

/// **MEMBERSHIP IS THE DECLARATION'S**, and the nodes that did not ask are not projected — which is
/// what keeps a graph holding an operator or a journal compiling at all.
#[test]
fn only_the_members_the_declaration_marked_are_folded() {
  let tokens = emitted(&root(&["media::Reel", "media::Take"]));

  assert!(tokens.contains("media :: Reel"), "{tokens}");
  assert!(tokens.contains("media :: Take"), "{tokens}");
  assert!(
    !tokens.contains("media :: Cutter"),
    "a node with no `query` word is no member of the fold:\n{tokens}"
  );
}

/// **A ROOT NO MEMBER JOINED EMITS NOTHING** — presence is the same mechanism one level up, and an
/// empty fold would be an object with no fields, which is not a GraphQL type.
#[test]
fn a_root_with_no_marked_field_has_no_query_at_all() {
  assert!(emitted(&root(&[])).is_empty());
}

/// **THE TWO NAMES ARE TWO NAMES.** The Rust type is per root, because two graphs in one crate are
/// two types; the published one is `Query`, because one schema has one root and its name is
/// GraphQL's convention rather than a deployment's word.
#[test]
fn the_rust_name_is_the_roots_and_the_published_name_is_the_conventional_one() {
  let tokens = emitted(&root(&["media::Reel"]));

  assert!(tokens.contains("struct MediaQuery"), "{tokens}");
  assert!(tokens.contains("name = \"Query\""), "{tokens}");
}

/// The BUILD PIN, at the one item on a graph root that carries a foreign derive: the derive's own
/// PATH goes through the shelf, and the `crate = "…"` key names the same shelf — either half alone
/// leaves a declaring crate with a name that does not resolve.
#[test]
fn the_merged_object_derive_carries_both_halves_of_the_shelf_rule() {
  let tokens = emitted(&root(&["media::Reel"]));

  assert!(
    tokens.contains(":: ingraph :: __private :: async_graphql :: MergedObject"),
    "the derive's own path is the shelf's:\n{tokens}"
  );
  assert!(
    tokens.contains("crate = \"::ingraph::__private::async_graphql\""),
    "and so is what it expands to:\n{tokens}"
  );
  assert!(
    !tokens.contains(":: async_graphql :: MergedObject ,")
      || tokens.contains(":: ingraph :: __private :: async_graphql :: MergedObject"),
    "no bare async-graphql path anywhere:\n{tokens}"
  );
}

/// The whole item rides the BINDING GATE, so a build with no GraphQL library has no root query and
/// no unresolved name where one would have been.
#[test]
fn the_root_query_is_written_inside_the_binding_gate() {
  let tokens = emitted(&root(&["media::Reel"]));

  assert!(
    tokens.starts_with(":: ingraph :: __private :: gate :: if_async_graphql !"),
    "{tokens}"
  );
}

/// No DOC anywhere on the emitted struct: `MergedObject` reads one and publishes it as the root
/// type's SDL description, which is the emission writing prose into somebody's schema.
#[test]
fn the_root_carries_no_description_for_a_derive_to_publish() {
  let tokens = emitted(&root(&["media::Reel"]));

  assert!(!tokens.contains("# [doc"), "{tokens}");
  assert!(
    tokens.contains("allow (missing_docs"),
    "and the absence is declared, so a crate under `missing_docs` is not warned about a type it \
     did not write:\n{tokens}"
  );
}

/// The visibility is the ROOT's, so a private graph's query stays private rather than leaking into
/// its crate's public API.
#[test]
fn the_query_takes_the_roots_own_visibility() {
  let mut model = root(&["media::Reel"]);
  model.vis = syn::parse_quote!(pub(crate));
  let tokens = emitted(&model);

  assert!(tokens.contains("pub (crate) struct MediaQuery"), "{tokens}");
}

/// A root holding one RETRIEVING member, mounted or not.
fn retrieving(queried: bool) -> GraphModel {
  let mut model = root(&[]);
  model.fused = vec![crate::graph::FusedMember {
    mount: syn::parse_quote!(shots),
    ty: syn::parse_quote!(media::Shots),
    queried,
  }];
  model
}

/// **A RETRIEVING MEMBER JOINS THE FOLD ON THE INTERFACE'S ROAD** — one projection rather than two,
/// because a retrieving declaration implements no `Transformer` and binds [`Graphql`] directly.
///
/// This is the ROOT QUERY-SURFACE gap closed: an index minted `<Decl>Queries`, bound it at the seat
/// and put it on its own roster, and no emitted root could reach it.
#[test]
fn a_retrieving_member_joins_through_the_one_hop_projection() {
  let tokens = emitted(&retrieving(true));
  assert!(
    tokens
      .contains("< media :: Shots as :: ingraph :: __private :: transform :: Graphql > :: Query"),
    "{tokens}"
  );
  assert!(
    !tokens.contains("Transformer > :: Graphql as"),
    "a retrieving member took the node's two-hop road: {tokens}"
  );
  assert!(
    !tokens.contains("ShotsQueries"),
    "the unit's NAME is written where the projection should be: {tokens}"
  );
}

/// **MEMBERSHIP IS THE MOUNT WORD HERE TOO** — a retrieving member on the index tier that did not
/// write `#[ingraph(query)]` is walked, launched and given its slots, and publishes nothing.
#[test]
fn an_unmounted_retrieving_member_is_not_projected() {
  assert!(
    emitted(&retrieving(false)).is_empty(),
    "a root whose only marked member is unmounted emitted a query",
  );
}

/// **A ROOT WHOSE ONLY QUERIED MEMBER IS A RETRIEVING ONE STILL EMITS ITS QUERY**, which is the
/// presence law read at the new list rather than at the two it was written for.
#[test]
fn a_retrieving_member_alone_is_enough_to_mint_the_root_query() {
  let tokens = emitted(&retrieving(true));
  assert!(tokens.contains("MergedObject"), "{tokens}");
  assert!(tokens.contains("name = \"Query\""), "{tokens}");
}