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 newtype device's acceptance: what a declaration may say about its KITS, and every shape it
//! may not.
//!
//! The wire block is the other axis and lives in `graphql_tests.rs` beside this: that file is about
//! what a BACKEND does with the type and this one about the type and its kits. A reader looking for
//! either should find it whole.

use ingraph_codegen::{element::ElementFamily, model::DatabaseKind, newtype::Gate};

/// A newtype wearing whatever struct-level block a case hands it.
fn declared(
  block: proc_macro2::TokenStream,
) -> syn::Result<ingraph_codegen::newtype::NewTypeModel> {
  super::parse(&syn::parse_quote! {
    #[ingraph(#block)]
    pub struct Tag(String);
  })
}

/// Whatever ITEM a case hands it, wearing one kit pair so the shape is the only thing under test.
fn shaped(item: syn::DeriveInput) -> String {
  let Err(refused) = super::parse(&item) else {
    panic!("the declaration is refused")
  };
  refused
    .into_iter()
    .map(|error| error.to_string())
    .collect::<Vec<_>>()
    .join(" | ")
}

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

/// The model a legal block produces.
fn accepted(block: proc_macro2::TokenStream) -> ingraph_codegen::newtype::NewTypeModel {
  declared(block).expect("the block is legal")
}

/// **THE SHAPE IS ONE VALUE**, and both spellings of one are taken: a device that read the
/// punctuation would be deciding a declaration's meaning from how it was written.
#[test]
fn a_newtype_holds_exactly_one_value_however_it_is_spelled() {
  let positional = super::parse(&syn::parse_quote! {
    #[ingraph(cursor)]
    pub struct Tag(String);
  })
  .expect("a tuple newtype");
  assert!(matches!(positional.member, syn::Member::Unnamed(_)));

  let named = super::parse(&syn::parse_quote! {
    #[ingraph(cursor)]
    pub struct Caption { words: String }
  })
  .expect("a named newtype");
  assert!(matches!(&named.member, syn::Member::Named(ident) if ident == "words"));
}

/// **A declaration with no inner type has nothing to delegate to**, and one with two has two answers
/// and no rule for picking between them.
#[test]
fn a_wider_or_emptier_struct_is_refused_by_name() {
  let two = shaped(syn::parse_quote! {
    #[ingraph(cursor)]
    pub struct Pair(String, u64);
  });
  assert!(two.contains("EXACTLY ONE value"), "{two}");
  assert!(two.contains("holds 2"), "{two}");

  let none = shaped(syn::parse_quote! {
    #[ingraph(cursor)]
    pub struct Nothing;
  });
  assert!(none.contains("EXACTLY ONE value"), "{none}");
}

/// **An enum has ALTERNATIVES rather than a value**, so the refusal names the two devices that equip
/// one.
#[test]
fn an_enum_is_refused_and_pointed_at_its_own_devices() {
  let refused = shaped(syn::parse_quote! {
    #[ingraph(cursor)]
    pub enum Side { Left(u8), Right(u8) }
  });
  assert!(refused.contains("NEWTYPE"), "{refused}");
  assert!(refused.contains("ingraph::Enum"), "{refused}");
  assert!(refused.contains("ingraph::Union"), "{refused}");
}

/// **A declaration naming NO kit installs nothing**, and a derive with no effect is a line its
/// author believes did something.
#[test]
fn a_declaration_that_names_no_kit_is_refused() {
  let refused = refusals(quote::quote!(crate = "::ingraph"));
  assert!(refused.contains("names none"), "{refused}");
}

/// **THE IMPLICATION EDGE, both ways.** `marker(<family>)` and `filter` are one installation spelled
/// in two words, and each alone is refused at the declaration rather than inside an expansion.
#[test]
fn the_reading_and_the_filter_are_one_installation() {
  let lone_filter = refusals(quote::quote!(filter));
  assert!(
    lone_filter.contains("`filter` needs `marker(<family>)`"),
    "{lone_filter}"
  );

  let lone_marker = refusals(quote::quote!(marker(string)));
  assert!(
    lone_marker.contains("`marker(<family>)` needs `filter`"),
    "{lone_marker}"
  );
  assert!(lone_marker.contains("ITEM BOUND"), "{lone_marker}");

  declared(quote::quote!(marker(string), filter)).expect("the pair is the installation");
}

/// **A bare `marker` is the SCALAR family**, which is the element mode's own rule for its own bare
/// word — and the two spellings reach one family.
#[test]
fn a_bare_marker_is_the_scalar_family() {
  let bare = accepted(quote::quote!(marker, filter));
  let spelled = accepted(quote::quote!(marker(scalar), filter));
  assert_eq!(bare.kits.marker, Some(ElementFamily::Scalar));
  assert_eq!(spelled.kits.marker, bare.kits.marker);
}

/// **The four families are the four whose filter kind carries an OPERAND PARAMETER**, and a word
/// naming none of them is refused with the list.
#[test]
fn the_family_vocabulary_is_the_frameworks_four() {
  for family in ElementFamily::ALL {
    let word = syn::parse_str::<proc_macro2::TokenStream>(family.word()).expect("a word");
    let model = accepted(quote::quote!(marker(#word), filter));
    assert_eq!(model.kits.marker, Some(family));
  }

  let refused = refusals(quote::quote!(marker(duration), filter));
  assert!(
    refused.contains("unknown family in `marker(…)`"),
    "{refused}"
  );
  assert!(refused.contains("OPERAND PARAMETER"), "{refused}");
}

/// **The dialect words are the record's**, and the fourth is refused by name rather than accepted
/// and dropped.
#[test]
fn the_dialect_words_are_the_three_this_round_builds() {
  let model = accepted(quote::quote!(sqlite, postgres, mysql));
  assert_eq!(
    model.kits.databases,
    vec![
      DatabaseKind::Sqlite,
      DatabaseKind::Postgres,
      DatabaseKind::Mysql
    ]
  );

  let mongo = refusals(quote::quote!(mongo));
  assert!(mongo.contains("does not build"), "{mongo}");
  assert!(mongo.contains("document one"), "{mongo}");
}

/// **A word declared twice is refused at the repeat**, at every depth this grammar has one.
#[test]
fn a_word_declared_twice_is_refused_at_the_repeat() {
  for (block, needle) in [
    (
      quote::quote!(cursor, cursor),
      "`cursor` is declared more than once",
    ),
    (
      quote::quote!(filter, filter),
      "`filter` is declared more than once",
    ),
    (
      quote::quote!(sqlite, sqlite),
      "`sqlite` is declared more than once",
    ),
    (
      quote::quote!(marker(string), marker(bytes)),
      "`marker` is declared more than once",
    ),
    (
      quote::quote!(crate = "::a", crate = "::b"),
      "`crate` is declared more than once",
    ),
  ] {
    let refused = refusals(block);
    assert!(refused.contains(needle), "{refused}");
  }
}

/// **A kit word that installs one face takes nothing**, and whatever was written after it is refused
/// rather than swallowed.
#[test]
fn a_face_word_takes_no_options() {
  let refused = refusals(quote::quote!(cursor(rename = "Position")));
  assert!(refused.contains("`cursor` takes no options"), "{refused}");
}

/// **EVERY WORD OF THE ROSTER IS KNOWN**, and the ones this round does not build refuse BY NAME.
///
/// The distinction is the whole of the refuse-until law: an unknown-entry refusal would tell an
/// author the word does not exist, which is the one thing that is not true of any of these — and a
/// *did you mean* pointing at a neighbour would be worse still.
#[test]
fn every_unbuilt_roster_word_refuses_by_name() {
  for (block, needle) in [
    (quote::quote!(comparison), "ORPHAN RULE"),
    (
      quote::quote!(order_by),
      "`order_by` is a word this roster carries",
    ),
    (quote::quote!(collection_element), "ADMISSION"),
    (
      quote::quote!(vector(f32)),
      "`vector(…)` is a word this roster carries",
    ),
    (quote::quote!(blob), "STORE position"),
    (quote::quote!(tantivy), "full-text engine"),
    (quote::quote!(element(string)), "MINTS a filter type"),
    (quote::quote!(record_field), "ONE bundle word"),
    (
      quote::quote!(error(rename = "Bad")),
      "a door is a function the DECLARATION supplies",
    ),
  ] {
    let refused = refusals(block);
    assert!(refused.contains(needle), "{refused}");
    assert!(
      !refused.contains("did you mean"),
      "a word the sentence refuses by name earns no near miss: {refused}"
    );
  }
}

/// **A word from no roster at all takes the unknown road**, with the vocabulary this position
/// actually has.
#[test]
fn a_word_this_grammar_never_had_is_unknown() {
  let refused = refusals(quote::quote!(storage));
  assert!(
    refused.contains("unknown entry in `#[ingraph(…)]` on a newtype"),
    "{refused}"
  );
}

/// **A near miss is measured against the words this position takes.**
#[test]
fn a_near_miss_names_the_word_it_is_near() {
  let refused = refusals(quote::quote!(curser));
  assert!(refused.contains("did you mean `cursor`?"), "{refused}");
}

/// **`crate = "…"` is read UNCONDITIONALLY**, wire block or not: which crate an expansion is rooted
/// at is a constant of the grammar rather than an entry whose meaning depends on its neighbours.
#[test]
fn the_crate_root_is_read_and_defaults_to_the_framework() {
  let named = accepted(quote::quote!(crate = "other::ingraph", cursor)).krate;
  assert_eq!(quote::quote!(#named).to_string(), "other :: ingraph");

  let default = accepted(quote::quote!(cursor)).krate;
  assert_eq!(quote::quote!(#default).to_string(), ":: ingraph");
}

/// **A door is ONE function**, and the two words are the two doors a newtype may have — never both.
#[test]
fn a_declaration_has_at_most_one_door() {
  let parse = accepted(quote::quote!(graphql(async_graphql(scalar(
    parse = "door"
  )))));
  assert!(matches!(parse.kits.gate(), Some(Gate::Parse(_))));

  let check = accepted(quote::quote!(graphql(async_graphql(scalar(
    check = "door"
  )))));
  assert!(matches!(check.kits.gate(), Some(Gate::Check(_))));

  let both = refusals(quote::quote!(graphql(async_graphql(scalar(
    parse = "one",
    check = "two"
  )))));
  assert!(both.contains("the two DOORS"), "{both}");
  assert!(both.contains("Keep the one this type is"), "{both}");

  let twice = refusals(quote::quote!(graphql(async_graphql(scalar(
    parse = "one",
    parse = "two"
  )))));
  assert!(twice.contains("a door is ONE function"), "{twice}");
}

/// **A door is a PATH**, so a value that is not one is refused at the literal.
#[test]
fn a_door_is_a_path_in_a_string_literal() {
  let refused = refusals(quote::quote!(graphql(async_graphql(scalar(parse = 7)))));
  assert!(refused.contains("PATH to the door function"), "{refused}");
}