ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! **THE HYDRATED TIER** — the two fields a plain road mounts beside its keys pair, the gate pair
//! that decides where they exist, and the projection they are keyed on.
//!
//! ```text
//!   if_sqlx! {                                      the SQL family's half
//!     type __INGRAPH_ANSWER_DB__ = <Keyframe as Hydrates>::Db;
//!     #[Object] impl ShotsQueries {
//!       shotsByClipKeys …  shotsSimilarByClipKeys …   the keys pair
//!       shotsByClip …      shotsSimilarByClip …       the hydrated pair
//!     }
//!   }
//!   if_no_sqlx! { #[Object] impl ShotsQueries { … the keys pair alone … } }
//! ```
//!
//! Beside [`answers`](super::answers) on this directory's one-file-per-thing precedent: that file
//! proves what the ANSWER FAMILY is and how a declared word reaches one field. This one proves the
//! tier below it — which is a different subject, because the whole of what makes it a tier is a
//! projection and a gate rather than a name.
//!
//! # What is asserted HERE and nowhere else
//!
//! | the claim | the assertion |
//! |---|---|
//! | the tier noun tells the two pairs apart | [`the_hydrated_pair_drops_the_tier_noun`] |
//! | the hydrated legs exist per SQL FAMILY | [`the_hydrated_legs_ride_the_family_gate`] |
//! | the shut half is the keys pair alone | [`the_shut_half_is_the_unit_without_the_store`] |
//! | the door is keyed on the record's own projection | [`the_door_is_keyed_on_the_upstream_projection`] |
//! | a fanned road demands no store at all | [`a_fanned_election_mounts_no_hydrated_leg`] |
//! | nothing is minted for the hydrated hit | [`the_hydrated_answer_is_the_frameworks_own_entity_hit`] |
//!
//! The EXECUTING half — that the door opens, that a lost row leaves a hole, that `depth` refills a
//! page — is `ingraph/tests/emitted_hydrated_road.rs`, which is the only place those can be run.

use super::{
  IndexModel,
  answers::{fanned, plain},
};
use crate::prefix::EmissionPrefix;

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

/// The tokens ONE gate holds, as text — read off the emission AS WRITTEN rather than through
/// [`crate::tests::ungate`], because the question here is what a build with that feature ON and OFF
/// sees, which is decided by the wrapper and not by its contents.
///
/// The walk is over the raw token stream rather than over parsed items for the reason
/// `emit::tracing_tests` states one emitter over: a gate is a macro INVOCATION, so its body is a
/// delimited group and the ident before it is the whole of what says which gate it is. Nested gates
/// are reached because the walk recurses into every group it did not claim.
fn inside(model: &IndexModel, gate: &str) -> String {
  fn walk(stream: proc_macro2::TokenStream, gate: &str, into: &mut String) {
    let mut named = false;
    for tree in stream {
      match tree {
        proc_macro2::TokenTree::Ident(ident) => named = ident == gate,
        proc_macro2::TokenTree::Group(group) => {
          if named {
            into.push_str(
              &group
                .stream()
                .to_string()
                .split_whitespace()
                .collect::<String>(),
            );
            named = false;
          } else {
            walk(group.stream(), gate, into);
          }
        }
        _ => {}
      }
    }
  }

  let mut held = String::new();
  walk(model.emit(), gate, &mut held);
  held
}

/// A FULL-TEXT declaration over one searched field — the kind that publishes no answer family at
/// all, and therefore no tier below one either.
fn document() -> IndexModel {
  IndexModel {
    prefix: EmissionPrefix::default(),
    kind: crate::model::NodeKind::Fulltext,
    embeddings: Vec::new(),
    searchable: vec![syn::Ident::new("body", proc_macro2::Span::call_site())],
    ..plain()
  }
}

/// **THE HYDRATED PAIR DROPS THE TIER NOUN, AND THAT IS THE WHOLE OF HOW A CLIENT TELLS THEM
/// APART** — `shotsByClipKeys` beside `shotsByClip`, `shotsSimilarByClipKeys` beside
/// `shotsSimilarByClip`.
///
/// Read off the emitted `#[graphql(name = …)]` strings rather than off a name this test builds, so
/// the claim is about what a client reads.
#[test]
fn the_hydrated_pair_drops_the_tier_noun() {
  let emitted = tight(&plain());
  for name in [
    r#"#[graphql(name="shotsByClipKeys")]"#,
    r#"#[graphql(name="shotsByClip")]"#,
    r#"#[graphql(name="shotsSimilarByClipKeys")]"#,
    r#"#[graphql(name="shotsSimilarByClip")]"#,
  ] {
    assert!(emitted.contains(name), "{name} is missing: {emitted}");
  }
}

/// **THE HYDRATED LEGS RIDE THE SQL FAMILY'S GATE**, where the keys legs ride the build.
///
/// The pair is FORCED rather than chosen: a type has ONE `#[Object]` impl, and the attribute reads
/// the block whole — so a gate around one method would be a macro invocation the attribute expands
/// before, and never a field. The block is therefore written twice.
///
/// The three PROJECTIONS ride the open half with them, because they resolve through `Hydrates`,
/// whose impl the record emits inside its own database's gate.
#[test]
fn the_hydrated_legs_ride_the_family_gate() {
  let open = inside(&plain(), "if_sqlx");
  assert!(open.contains(r#"#[graphql(name="shotsByClip")]"#), "{open}");
  assert!(
    open.contains(r#"#[graphql(name="shotsSimilarByClip")]"#),
    "{open}"
  );
  assert!(
    open.contains(
      "type__INGRAPH_ANSWER_DB__=<Keyframeas::ingraph::__private::transform::Hydrates>::Db;"
    ),
    "{open}",
  );
  assert!(open.contains("type__INGRAPH_ANSWER_ROW__="), "{open}");
  assert!(open.contains("type__INGRAPH_ANSWER_ENTITY__="), "{open}");
}

/// **THE SHUT HALF IS THE UNIT WITHOUT THE STORE** — the keys pair, and nothing that names one.
///
/// The second half of the pair's claim, and the one that makes the arrival ADDITIVE: a build with no
/// SQL family compiles exactly the fields it compiled before, so the family's presence adds fields
/// rather than moving any. Stated as an absence over the shut half's own tokens, which is where a
/// leaked name would land.
#[test]
fn the_shut_half_is_the_unit_without_the_store() {
  let shut = inside(&plain(), "if_no_sqlx");
  assert!(
    shut.contains(r#"#[graphql(name="shotsByClipKeys")]"#),
    "{shut}"
  );
  assert!(
    shut.contains(r#"#[graphql(name="shotsSimilarByClipKeys")]"#),
    "{shut}"
  );
  assert!(
    !shut.contains(r#"#[graphql(name="shotsByClip")]"#),
    "a hydrated field reached the family-less half: {shut}",
  );
  for named in [
    "SqlDoor",
    "SqlPooledGather",
    "Hydrates",
    "__INGRAPH_ANSWER_DB__",
  ] {
    assert!(
      !shut.contains(named),
      "`{named}` reached the family-less half: {shut}",
    );
  }
}

/// **THE DOOR IS KEYED ON THE UPSTREAM'S OWN PROJECTION**, and the gather reads the row that same
/// projection names.
///
/// The claim is that ONE binding feeds both: a door opened on one database while the gather read
/// another's columns is the failure the shared alias exists to make unspellable, and two independent
/// spellings of `<Upstream as Hydrates>::Db` is where it would come from.
#[test]
fn the_door_is_keyed_on_the_upstream_projection() {
  let emitted = tight(&plain());
  assert!(
    emitted.contains(
      "::ingraph::__private::graphql::SqlDoor<__INGRAPH_ANSWER_DB__>>(__async_graphql_ctx)?"
    ),
    "{emitted}",
  );
  assert!(
    emitted.contains(
      "::ingraph::__private::retrieve::SqlPooledGather::<__INGRAPH_ANSWER_ROW__,\
       __INGRAPH_ANSWER_DB__>::new"
    ),
    "{emitted}",
  );
  // The ROW is projected THROUGH the database, so the two cannot name different stores.
  assert!(
    emitted.contains(
      "type__INGRAPH_ANSWER_ROW__=<Keyframeas::ingraph::__private::transform::Record<\
       __INGRAPH_ANSWER_DB__>>::Row;"
    ),
    "{emitted}",
  );
}

/// **A FANNED ELECTION MOUNTS NO HYDRATED LEG AND DEMANDS NO STORE** — the projection is written
/// where it is SPENT, so a declaration that publishes no hydrated road asks nothing of its upstream's
/// storage.
///
/// That is not a saving: `Hydrates` is unimplemented for a record stored nowhere, so a demand
/// emitted for a road that does not exist would refuse a fanned declaration over an unstored
/// upstream for a field it never publishes.
#[test]
fn a_fanned_election_mounts_no_hydrated_leg() {
  let emitted = tight(&fanned());
  assert!(!emitted.contains("Hydrates"), "{emitted}");
  assert!(!emitted.contains("__INGRAPH_ANSWER_DB__"), "{emitted}");
  assert!(!emitted.contains("SqlPooledGather"), "{emitted}");
  // AND NO PAIR AT ALL: one `#[Object]` block, in the build's own scope.
  assert!(!emitted.contains("if_no_sqlx"), "{emitted}");
}

/// **A KIND THAT PUBLISHES NO ANSWER FAMILY PUBLISHES NO TIER BELOW ONE** — the full-text arm, whose
/// absence is scope rather than a wall and is [`super::answers`]' own measurement, read here for the
/// half this file owns: no gate pair is minted for a declaration with no road at all.
#[test]
fn a_full_text_declaration_mints_no_gate_pair() {
  let emitted = tight(&document());
  assert!(!emitted.contains("if_no_sqlx"), "{emitted}");
  assert!(!emitted.contains("Hydrates"), "{emitted}");
}

/// **THE HYDRATED ANSWER IS THE FRAMEWORK'S OWN ENTITY HIT**, reached through the shelf — nothing is
/// minted for it, exactly as nothing is minted for the keys tier's.
///
/// `Match` is ONE type at two instantiations since the 2026-08-19 retirement: same numbers, same
/// SDL rule, and a third row whose TYPE is the tier's node. A shape of this emission's own at either
/// tier would have put a second hit type in a schema that already has one per node.
#[test]
fn the_hydrated_answer_is_the_frameworks_own_entity_hit() {
  let emitted = tight(&plain());
  assert!(
    emitted.contains("::ingraph::__private::graphql::Match<__INGRAPH_ANSWER_ENTITY__,"),
    "{emitted}",
  );
  let file: syn::File = syn::parse2(plain().emit()).expect("the emission parses");
  let landed: Vec<String> = file
    .items
    .into_iter()
    .filter_map(|item| match item {
      syn::Item::Struct(declared) => Some(declared.ident.to_string()),
      syn::Item::Enum(declared) => Some(declared.ident.to_string()),
      _ => None,
    })
    .collect();
  assert!(
    !landed.iter().any(|name| name.contains("Entity")),
    "the hydrated tier minted a shape of its own: {landed:?}",
  );
}

/// **THE ROSTER IS UNCHANGED BY THE HYDRATED TIER**, which is the emitted-type rule read at a round
/// that added fields and no types.
///
/// The tier's whole surface is two resolvers, three type aliases private to one gate's own block,
/// and a framework hit — so there is nothing new in a declaring scope for a collision to be measured
/// against. [`super::answers`]' own roster equality is what proves the list matches the emission;
/// this proves the round did not need to grow it.
#[test]
fn the_hydrated_tier_adds_nothing_to_the_roster() {
  for name in plain()
    .emitted_types()
    .iter()
    .map(|declared| declared.name.to_string())
  {
    assert!(
      !name.contains("Entity") && !name.contains("Hydrat"),
      "the hydrated tier put a name in the declaring scope: {name}",
    );
  }
}