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 union's WIRE WORD: which schema positions a declaration may ask for, and every way of asking
//! that is refused.
//!
//! Beside [`tests`](super::tests) rather than inside it, on `index/rename_seats.rs`' precedent: that
//! file is about the member SET and this one is about what a backend does with it. A reader looking
//! for either should find it whole.
//!
//! What the positions do to an EMISSION is `ingraph-codegen`'s `union/wire.rs`, where the naming law
//! can be read off the token stream, and `ingraph`'s `tests/union_faces.rs`, where it can be read
//! off a real schema. Here it is the GRAMMAR and the SENTENCE.

use ingraph_codegen::{model::GraphqlKind, union::UnionModel};

/// A union wearing whatever enum-level block a case hands it.
fn declared(block: proc_macro2::TokenStream) -> syn::Result<UnionModel> {
  super::parse(&syn::parse_quote! {
    #[ingraph(#block)]
    pub enum Found {
      Media(Media),
      Clip(Clip),
    }
  })
}

/// The ONE backend a case declared, as the model holds it.
fn skin(model: &UnionModel) -> &ingraph_codegen::union::UnionSkin {
  model
    .graphql
    .first()
    .expect("the declaration named a backend")
}

/// Every refusal a block earns, joined.
fn refusals(block: proc_macro2::TokenStream) -> String {
  declared(block)
    .expect_err("the block is refused")
    .into_iter()
    .map(|error| error.to_string())
    .collect::<Vec<_>>()
    .join(" | ")
}

/// **A UNION THAT WRITES NO WIRE WORD IS COMPLETE**, and is what every union in this tree was before
/// the round that added the word: a Rust face, and no schema presence at all.
#[test]
fn a_union_with_no_graphql_block_is_dressed_for_nothing() {
  let model = super::parse(&syn::parse_quote! {
    enum Found { Media(Media) }
  })
  .expect("the wire word is optional");

  assert!(model.graphql.is_empty());
}

/// **EACH POSITION REACHES ITS OWN SEAT AND NEITHER IMPLIES THE OTHER.**
///
/// The claim the two-word vocabulary rests on, and it cannot be made one position at a time: a word
/// wired to its neighbour's slot would show as one position filled twice and one never.
#[test]
fn each_position_fills_its_own_seat() {
  let output = declared(quote::quote!(graphql(async_graphql(output)))).expect("output alone");
  assert!(skin(&output).output.is_some());
  assert!(skin(&output).input.is_none());

  let input = declared(quote::quote!(graphql(async_graphql(input)))).expect("input alone");
  assert!(skin(&input).output.is_none());
  assert!(skin(&input).input.is_some());

  let both = declared(quote::quote!(graphql(async_graphql(output, input)))).expect("both");
  assert!(skin(&both).output.is_some());
  assert!(skin(&both).input.is_some());
  assert_eq!(skin(&both).kind, GraphqlKind::AsyncGraphql);
}

/// **The INPUT's name is the one word a declaration can move**, and it moves the SCHEMA's name
/// rather than a Rust one: both faces are impls on the enum the declaration already wrote, so there
/// is no Rust type here to rename.
#[test]
fn the_input_object_takes_the_word_the_declaration_gives_it() {
  let model = declared(quote::quote! {
    graphql(async_graphql(output, input(rename = "FoundChoice")))
  })
  .expect("the input names itself");

  assert_eq!(skin(&model).input_sdl(&model.name), "FoundChoice");
  assert_eq!(skin(&model).output_sdl(&model.name), "Found");
}

/// A SCHEMA name is a word in GraphQL's own Name grammar and not a Rust identifier — the 2026-08-13
/// ruling's fence, reached through the reader every string-kind rename goes through.
#[test]
fn refuses_an_input_name_outside_graphqls_own_grammar() {
  for spelling in ["", "Not A Name", "9Lives"] {
    let refused = refusals(quote::quote! {
      graphql(async_graphql(input(rename = #spelling)))
    });
    assert!(
      refused.contains("GraphQL") || refused.contains("a word in a string literal"),
      "{spelling:?}: {refused}"
    );
  }
}

/// **A SCHEMA HAS ONE NAMESPACE FOR TYPE NAMES**, so a union rendering both faces cannot give them
/// one word — and the same word is legal the moment there is no output face to collide with.
#[test]
fn refuses_an_input_renamed_onto_the_output_face() {
  let refused = refusals(quote::quote! {
    graphql(async_graphql(output, input(rename = "Found")))
  });
  assert!(
    refused.contains("which is what this union's OUTPUT face already publishes"),
    "{refused}"
  );

  let alone = declared(quote::quote!(graphql(async_graphql(input(
    rename = "Found"
  )))))
  .expect("with no output face there is nothing to collide with");
  assert_eq!(skin(&alone).input_sdl(&alone.name), "Found");
}

/// A block that dresses NO position is a face nothing renders, which is an entry nobody reads.
#[test]
fn refuses_a_backend_that_names_neither_position() {
  for block in [
    quote::quote!(graphql(async_graphql)),
    quote::quote!(graphql(async_graphql())),
  ] {
    let refused = refusals(block);
    assert!(
      refused.contains("dresses this union for no position"),
      "{refused}"
    );
  }
}

/// One word per position: a schema renders a union at each of them once, so a second could only
/// re-describe the first.
#[test]
fn refuses_a_position_declared_twice() {
  let output = refusals(quote::quote!(graphql(async_graphql(output, output))));
  assert!(
    output.contains("`output` is declared more than once"),
    "{output}"
  );

  let input = refusals(quote::quote!(graphql(async_graphql(
    input,
    input(rename = "X")
  ))));
  assert!(
    input.contains("`input` is declared more than once"),
    "{input}"
  );
}

/// **THE OUTPUT FACE HAS A WORD TOO**, and writing it re-bases the derived input twin.
///
/// The rename-parity ruling's row for this device. Before it, `output` took no options at all and
/// the refusal sent every author to `input(rename = "…")` — which answered *which face keeps the
/// union's own name by default* rather than the question actually being asked.
///
/// Three claims, and the third is the one that keeps this from being a half-working rename: the
/// output moves, the untouched input MOVES WITH IT, and a word written at the input still wins.
#[test]
fn the_output_face_takes_the_word_the_declaration_gives_it() {
  let alone = declared(quote::quote!(graphql(async_graphql(output(
    rename = "Sighting"
  )))))
  .expect("the output names itself");
  assert_eq!(skin(&alone).output_sdl(&alone.name), "Sighting");

  let both = declared(quote::quote! {
    graphql(async_graphql(output(rename = "Sighting"), input))
  })
  .expect("both faces, one renamed");
  assert_eq!(skin(&both).output_sdl(&both.name), "Sighting");
  assert_eq!(
    skin(&both).input_sdl(&both.name),
    "SightingInput",
    "the derived twin composes off the OUTPUT's word, not the Rust ident"
  );

  let named = declared(quote::quote! {
    graphql(async_graphql(output(rename = "Sighting"), input(rename = "Pick")))
  })
  .expect("both faces, both named");
  assert_eq!(skin(&named).input_sdl(&named.name), "Pick");
}

/// The output's word rides the same fences the input's does — GraphQL's Name grammar, and one word
/// per position.
#[test]
fn refuses_an_output_name_outside_the_grammar_or_written_twice() {
  let outside = refusals(quote::quote!(graphql(async_graphql(output(
    rename = "Not A Name"
  )))));
  assert!(outside.contains("GraphQL"), "{outside}");

  let twice = refusals(quote::quote!(graphql(async_graphql(output(
    rename = "A",
    rename = "B"
  )))));
  assert!(
    twice.contains("`rename` is declared more than once in `output(…)`"),
    "{twice}"
  );
}

/// The output block takes `rename` and nothing else, and its sentence says what the face publishes
/// instead of listing a vocabulary it does not have.
#[test]
fn refuses_a_word_the_output_block_does_not_take() {
  let refused = refusals(quote::quote!(graphql(async_graphql(output(operand)))));
  assert!(
    refused.contains("unknown entry in `output(…)`"),
    "{refused}"
  );
}

/// **A SCHEMA HAS ONE NAMESPACE FOR TYPE NAMES**, read from the OUTPUT's side: a word written there
/// can land on the input's derived name exactly as the reverse already could.
#[test]
fn refuses_an_output_renamed_onto_the_input_face() {
  let refused = refusals(quote::quote! {
    graphql(async_graphql(output(rename = "Pick"), input(rename = "Pick")))
  });
  assert!(
    refused.contains("which is what this union's OUTPUT face already publishes"),
    "{refused}"
  );
}

/// Every unrecognised word at either depth is refused rather than ignored, and each sentence names
/// what its own level takes.
#[test]
fn refuses_a_word_neither_depth_knows() {
  let position = refusals(quote::quote!(graphql(async_graphql(operand))));
  assert!(
    position.contains("unknown entry in a union's backend block"),
    "{position}"
  );

  let option = refusals(quote::quote!(graphql(async_graphql(input(name = "X")))));
  assert!(option.contains("unknown entry in `input(…)`"), "{option}");

  let backend = refusals(quote::quote!(graphql(juniper(output))));
  assert!(
    backend.contains("unknown backend in `graphql(…)`"),
    "{backend}"
  );
}

/// One block holds every backend, and one word per backend inside it.
#[test]
fn refuses_a_second_block_and_a_second_backend() {
  let twice = refusals(quote::quote! {
    graphql(async_graphql(output)), graphql(async_graphql(input))
  });
  assert!(
    twice.contains("`graphql(…)` is declared more than once"),
    "{twice}"
  );

  let repeated = refusals(quote::quote! {
    graphql(async_graphql(output), async_graphql(input))
  });
  assert!(
    repeated.contains("`async_graphql` is declared more than once"),
    "{repeated}"
  );
}

/// A `graphql` block with nothing in it names no backend, and the refusal writes out the spelling
/// that does.
#[test]
fn refuses_a_graphql_block_that_names_no_backend() {
  for block in [quote::quote!(graphql), quote::quote!(graphql())] {
    let refused = refusals(block);
    assert!(refused.contains("`graphql` names no backend"), "{refused}");
    assert!(
      refused.contains("graphql(async_graphql(output))"),
      "{refused}"
    );
  }
}