ingraph-derive 0.1.0

The attribute and derive macros for ingraph: the words a record, node, key, filter and vocabulary declaration is written in.
Documentation
//! **THE ADDRESS BLOCK'S THREE SEATS** — `key(rename = "…", input(rename = "…"),
//! output(rename = "…"))`, the shape the 2026-08-16 rename ruling put in place of the single word.
//!
//! ```text
//!   key(rename = "Address")                    →  base:   Rust `Address`, schema `Address`/`AddressInput`
//!   key(output(rename = "AddressM"))           →  member: the READING half alone
//!   key(input(rename = "AddressIn"))           →  member: the SENDING half alone
//! ```
//!
//! Beside [`tests`](super::tests) for [`output_field_tests`](super::output_field_tests)' reason: that
//! suite's subject is the record's whole option set and this one's is a single block that grew two
//! members, so a reader looking for what `input(…)` MEANS finds it whole.
//!
//! # What is asserted here and what is asserted elsewhere
//!
//! Here: the GRAMMAR — which spellings parse into which slot, and what a refusal says. What the
//! seats do to the PUBLISHED names, and the resolution order between them, is `ingraph-codegen`'s
//! `emit/wire/key_faces_tests.rs`; the base's own long-standing behaviour is the neighbouring
//! `key_rename_tests.rs` there, which this file does not re-assert.
//!
//! # Why only this one of the four emitted-type blocks grew members
//!
//! An address publishes TWO schema names out of ONE Rust type, GraphQL keeping input and output
//! types in one namespace. `filter` and `order_by` publish one type each, so a second word in either
//! would name nothing — which is why they are still the plain rename block they always were, and why
//! that is stated here rather than left to be inferred from an absence.

use ingraph_codegen::prelude::*;

/// The pass under test, at the kind an address is minted on.
fn record(input: &syn::DeriveInput) -> syn::Result<RecordModel> {
  let (host, options) = crate::host::split(input);
  crate::parse::parse(&host, &options, NodeKind::Record)
}

/// A record whose `graphql(…)` carries whatever address block a case hands it.
///
/// It has a LINEAGE, and that is load-bearing rather than decorative: a root's address crosses
/// inward as its id and mints no `KeyInput` at all, so `input(rename = "…")` on one is refused by
/// the mints-none audit and this file's subject is the GRAMMAR. The compound shape is the one where
/// all three seats are reachable at once — see [`a_root_has_no_sending_face_for_a_word_to_move`],
/// which is the other side of the same fact.
fn addressed(block: proc_macro2::TokenStream) -> syn::Result<RecordModel> {
  record(&syn::parse_quote! {
    #[ingraph(table = "shots", sqlite, lineage(fields(reel_id)), graphql(async_graphql, #block))]
    struct Shot {
      #[ingraph(id)]
      id: String,
      reel_id: String,
      body: String,
    }
  })
}

/// The same declaration as a ROOT — no lineage, so its address is its id alone.
fn rooted(block: proc_macro2::TokenStream) -> syn::Result<RecordModel> {
  record(&syn::parse_quote! {
    #[ingraph(table = "shots", sqlite, graphql(async_graphql, #block))]
    struct Shot {
      #[ingraph(id)]
      id: String,
      body: String,
    }
  })
}

/// The three address names one parsed declaration holds: the Rust base, and the two schema words.
fn seats(model: &RecordModel) -> (String, Option<String>, Option<String>) {
  let graphql = model.graphql.as_ref().expect("a wire face");
  (
    graphql.key_output.to_string(),
    graphql.key_object.clone(),
    graphql.key_argument.clone(),
  )
}

/// Every refusal one declaration collects, as one string.
fn refusal(block: proc_macro2::TokenStream) -> String {
  addressed(block)
    .expect_err("the declaration is refused")
    .into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>()
    .join(" | ")
}

/// **THE THREE SEATS ARE THREE SLOTS**, filled independently — which is the whole of what
/// *separating the base from the output* means.
///
/// Written as ONE declaration carrying all three, because that is the case a wiring mistake hides
/// in: a member landing in the base's slot would still look right in a test that wrote one word at a
/// time.
#[test]
fn the_base_and_the_two_faces_each_fill_their_own_slot() {
  let model = addressed(quote::quote! {
    key(rename = "Address", input(rename = "AddressIn"), output(rename = "AddressM"))
  })
  .expect("the ruling's canonical spelling");
  assert_eq!(
    seats(&model),
    (
      "Address".to_owned(),
      Some("AddressM".to_owned()),
      Some("AddressIn".to_owned()),
    ),
  );
}

/// **A MEMBER IS STANDALONE-LEGAL** — a face named with no base above it is a complete declaration.
///
/// Both directions, because the two members are two slots and a walk that required the base would
/// fail identically on each.
#[test]
fn a_face_may_be_named_with_no_base_above_it() {
  let model = addressed(quote::quote! { key(output(rename = "AddressM")) })
    .expect("one member is a whole declaration");
  assert_eq!(
    seats(&model),
    (
      "ShotKeyOutput".to_owned(),
      Some("AddressM".to_owned()),
      None,
    ),
    "the base slot took a default it was not given",
  );

  let model = addressed(quote::quote! { key(input(rename = "AddressIn")) })
    .expect("its twin, by the same reading");
  assert_eq!(
    seats(&model),
    (
      "ShotKeyOutput".to_owned(),
      None,
      Some("AddressIn".to_owned()),
    ),
  );
}

/// **THE BASE ALONE STILL MEANS WHAT IT MEANT** — the seat that shipped before the ruling, unmoved.
///
/// The reshape adds seats and must not change what an existing declaration says: a record that wrote
/// `key(rename = "Address")` and nothing else names the Rust type and leaves both members empty, so
/// the published pair is derived exactly as it was.
#[test]
fn the_base_alone_names_the_rust_type_and_leaves_both_members_empty() {
  let model = addressed(quote::quote! { key(rename = "Address") }).expect("the shipped spelling");
  assert_eq!(seats(&model), ("Address".to_owned(), None, None));
}

/// **A MEMBER IS A SCHEMA WORD AND THE BASE IS A RUST NAME**, which is the axis this block spans and
/// the one thing a reader has to hold about it.
///
/// A Rust KEYWORD is the measurement: it is a legal GraphQL name — GraphQL's own keywords are
/// contextual — and an ident parse refuses it, so the two seats must disagree about `type` or one of
/// them has the wrong fence. The 2026-08-13 ruling is what made that a requirement rather than a
/// curiosity.
#[test]
fn a_member_takes_a_keyword_and_the_base_refuses_one() {
  let model = addressed(quote::quote! { key(output(rename = "type")) })
    .expect("a schema type may be called `type`");
  assert_eq!(seats(&model).1, Some("type".to_owned()));

  let refused = refusal(quote::quote! { key(rename = "type") });
  assert!(
    refused.contains("must be a valid identifier"),
    "the base is a Rust name and is fenced as one: {refused}",
  );
}

/// **A MEMBER IS HELD TO GRAPHQL'S OWN NAME GRAMMAR**, at the literal that wrote it — the one fence
/// on a schema word, because nothing below this layer refuses a type name a schema cannot export.
#[test]
fn a_member_is_held_to_the_wire_alphabet() {
  for block in [
    quote::quote! { key(output(rename = "9lives")) },
    quote::quote! { key(input(rename = "9lives")) },
  ] {
    let refused = refusal(block);
    assert!(refused.contains("9lives"), "{refused}");
  }
}

/// **THE BLOCK'S VOCABULARY IS CLOSED AND WIRED TO THE SUGGESTION ENGINE**, like every other block in
/// this grammar.
#[test]
fn an_unknown_entry_is_measured_against_the_three_seats() {
  let refused = refusal(quote::quote! { key(outputs(rename = "AddressM")) });
  assert!(refused.contains("unknown entry in `key(…)`"), "{refused}");
  assert!(
    refused.contains("did you mean `output`"),
    "a near miss is measured against the seats: {refused}",
  );
  assert!(
    refused.contains("takes it with `Input` on the end"),
    "and the sentence states the one composition, which is what an author needs to predict the \
     name they did not write: {refused}",
  );
}

/// **A BLOCK THAT NAMED NOTHING IS REFUSED WITH ALL THREE SEATS.**
#[test]
fn an_empty_block_is_told_what_it_could_have_said() {
  for block in [quote::quote! { key }, quote::quote! { key() }] {
    let refused = refusal(block);
    assert!(refused.contains("`key(…)` names the ADDRESS"), "{refused}");
    assert!(refused.contains("output(rename"), "{refused}");
    assert!(refused.contains("input(rename"), "{refused}");
  }
}

/// **ONE SEAT, ONE WORD**, at each of the three.
#[test]
fn each_seat_is_named_once() {
  for (block, sentence) in [
    (
      quote::quote! { key(rename = "A", rename = "B") },
      "declared more than once in `key(…)`",
    ),
    (
      quote::quote! { key(output(rename = "A"), output(rename = "B")) },
      "declared more than once in `output(…)`",
    ),
    (
      quote::quote! { key(input(rename = "A"), input(rename = "B")) },
      "declared more than once in `input(…)`",
    ),
  ] {
    let refused = refusal(block);
    assert!(refused.contains(sentence), "{refused}");
  }
}

/// **THE TWO NEIGHBOURS DID NOT GROW MEMBERS**, and the reason is stated in the refusal they give:
/// each publishes ONE type, so a face word there would name nothing.
///
/// Asserted rather than left to an absence, because *the grammar refuses it* and *the grammar has
/// not been taught it yet* look the same from outside — and this one is a decision.
#[test]
fn the_single_faced_blocks_still_take_a_rename_and_nothing_else() {
  for what in ["filter", "order_by"] {
    let entry: proc_macro2::TokenStream = format!(r#"{what}(output(rename = "X"))"#)
      .parse()
      .expect("a block");
    let refused = refusal(entry);
    assert!(
      refused.contains(&format!("unknown entry in `{what}(…)`")),
      "{refused}",
    );
    assert!(
      refused.contains("it takes `rename = \"…\"` and nothing else"),
      "{refused}",
    );
  }
}

/// **A ROOT HAS NO SENDING FACE FOR A WORD TO MOVE** — the mints-none audit at this block, and the
/// one seat here that has a shape it is unreachable on.
///
/// A root's address IS its id, so it crosses inward as that id's own wire form and no `KeyInput`
/// type is emitted at all: the word would be a rename its author could not find in any schema. The
/// sentence says what a client actually sends instead, which is the half that turns a refusal into
/// an answer.
#[test]
fn a_root_has_no_sending_face_for_a_word_to_move() {
  let refused = rooted(quote::quote! { key(input(rename = "AddressIn")) })
    .expect_err("a root mints no argument object")
    .into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>()
    .join(" | ");
  assert!(refused.contains("`Shot` is a ROOT"), "{refused}");
  assert!(
    refused.contains("no `KeyInput` type is minted"),
    "the sentence names the type that is absent: {refused}",
  );
  assert!(
    refused.contains("shot(id: …)"),
    "and what a client sends instead: {refused}",
  );
  assert!(
    refused.contains("The word opens where the record has a LINEAGE"),
    "and the shape it opens on: {refused}",
  );
}

/// **THE READING FACE IS AUDITED AND FOUND ALWAYS-SPENT**, which is a different answer from
/// unaudited.
///
/// Every record whose `graphql(…)` names a backend emits `key_output_face`, and a block naming no
/// backend is already refused by name — so there is no shape in which `output(rename = "…")` is
/// writable and the object is absent. A key always has at least one column, an id being mandatory.
/// Asserted at the ROOT, which is the shape where its twin is refused: the two together are what
/// says the audit reads the FACE rather than the block.
#[test]
fn the_reading_face_is_minted_on_every_shape_including_a_root() {
  let model = rooted(quote::quote! { key(output(rename = "AddressM")) })
    .expect("every record reads its address back out of an object");
  assert_eq!(
    seats(&model),
    (
      "ShotKeyOutput".to_owned(),
      Some("AddressM".to_owned()),
      None,
    ),
  );

  // …and the BASE stays legal on a root too: it re-bases the reading face, which every record has.
  rooted(quote::quote! { key(rename = "Address") }).expect("the base names the face that exists");
}