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 WATERSHED, read — which identity a declaration took, and every refusal the marked side
//! carries.
//!
//! `tests/refusals/` proves the messages REACH a user, spanned at the token that broke the rule;
//! these prove the reader decides correctly in the first place, which is the half a compile-fail
//! fixture cannot separate out: a declaration that took the wrong identity would fail for a reason
//! of the other mode's rather than for none at all.

use super::{Face, Mode};

/// EVERY refusal a declaration produced, one per line.
///
/// Joined rather than read off the head, because one compile reports the whole declaration's
/// problems: `syn::Error`'s own `Display` renders the FIRST of a sealed set, so a test reading it
/// would be asserting about which rule happened to be checked first.
fn refused(read: syn::Result<Mode>) -> String {
  match read {
    Ok(_) => panic!("the declaration is refused"),
    Err(errors) => errors
      .into_iter()
      .map(|error| error.to_string())
      .collect::<Vec<_>>()
      .join("\n"),
  }
}

/// The element model a marked declaration reads as.
fn element(read: syn::Result<Mode>) -> ingraph_codegen::element::ElementModel {
  match read.expect("a marked declaration reads as an element") {
    Mode::Element(model) => *model,
    Mode::Composed(_) | Mode::Struct(_) => panic!("`operator(…)` is the element mode's watershed"),
  }
}

/// **THE MARKER IS THE WATERSHED, AND THE SHAPE IS NOT.**
///
/// Two declarations of one shape — a struct with named fields — and the only difference between
/// them is whether `operator(…)` was written. The reader takes one as a row of columns and the other
/// as a value, which is the whole of what the ruling settled: a newtype and a named-field struct are
/// both legal Rust for either reading, so a door that guessed from the punctuation would be deciding
/// a declaration's meaning from how it was spelled.
#[test]
fn the_marker_decides_the_identity_and_the_shape_does_not() {
  let unmarked: syn::DeriveInput = syn::parse_quote! {
    pub struct Caption {
      words: String,
    }
  };
  assert!(matches!(
    super::parse(&unmarked, Face::Filter).expect("an unmarked struct is the struct mode"),
    Mode::Struct(_)
  ));

  let marked: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(string))]
    pub struct Caption {
      words: String,
    }
  };
  let model = element(super::parse(&marked, Face::Filter));
  assert_eq!(model.filter.safe().to_string(), "CaptionFilter");
  assert_eq!(
    model.family,
    ingraph_codegen::element::ElementFamily::String
  );
}

/// **A BARE `operator` IS THE SCALAR FAMILY**, which is the default the ruling names.
#[test]
fn a_bare_marker_is_the_scalar_family() {
  let bare: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator)]
    pub struct Weight(i64);
  };
  let spelled: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(scalar))]
    pub struct Weight(i64);
  };

  assert_eq!(
    element(super::parse(&bare, Face::Filter)).family,
    element(super::parse(&spelled, Face::Filter)).family
  );
  assert_eq!(
    element(super::parse(&bare, Face::Filter)).family,
    ingraph_codegen::element::ElementFamily::Scalar
  );
}

/// **EVERY FAMILY WITH AN ELEMENT MODE RESOLVES**, and the four are the four.
#[test]
fn each_family_word_resolves_to_its_own_family() {
  for family in ingraph_codegen::element::ElementFamily::ALL {
    let word = syn::Ident::new_raw(family.word(), proc_macro2::Span::call_site());
    let input: syn::DeriveInput = syn::parse_quote! {
      #[ingraph(operator(#word))]
      pub struct Value(String);
    };
    assert_eq!(element(super::parse(&input, Face::Filter)).family, family);
  }
}

/// **A FAMILY WITHOUT AN ELEMENT MODE IS REFUSED BY NAME**, and the sentence says WHY the word is
/// not among them rather than only that it is not.
#[test]
fn a_family_with_no_operand_parameter_refuses_by_name() {
  for word in ["bool", "duration"] {
    let ident = syn::Ident::new(word, proc_macro2::Span::call_site());
    let input: syn::DeriveInput = syn::parse_quote! {
      #[ingraph(operator(#ident))]
      pub struct Value(i64);
    };
    let sentence = refused(super::parse(&input, Face::Filter));
    assert!(sentence.contains(word), "{sentence}");
    assert!(sentence.contains("no operand parameter"), "{sentence}");
  }
}

/// **A COLLECTION POSITION IS NOT AN ELEMENT**, refused by name and told apart from the two above.
#[test]
fn a_collection_word_refuses_as_a_position_rather_than_as_a_kind() {
  for word in ["list", "set", "quantified"] {
    let ident = syn::Ident::new(word, proc_macro2::Span::call_site());
    let input: syn::DeriveInput = syn::parse_quote! {
      #[ingraph(operator(#ident))]
      pub struct Value(i64);
    };
    let sentence = refused(super::parse(&input, Face::Filter));
    assert!(sentence.contains("collection POSITIONS"), "{sentence}");
  }
}

/// **A WORD OUTSIDE THE VOCABULARY LISTS THE ONES INSIDE IT.**
#[test]
fn an_unknown_family_names_the_four() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(colour))]
    pub struct Value(i64);
  };
  let sentence = refused(super::parse(&input, Face::Filter));
  for family in ingraph_codegen::element::ElementFamily::ALL {
    assert!(sentence.contains(family.word()), "{sentence}");
  }
}

/// **A MARKED DECLARATION THAT IS NOT ONE VALUE IS REFUSED, AND NOTHING IS INVENTED.**
///
/// The STOP-ON-FORK case the ruling left open. With two fields there is no ONE field for *the whole
/// declaration crosses as one operand* to be about — which of them is the wire form, and what the
/// other becomes, are questions the marker does not answer — so the door names the fork rather than
/// picking a side of it. A unit struct is the same refusal from the other end: nothing to cross.
#[test]
fn a_marked_declaration_that_is_not_one_value_refuses_by_name() {
  let two: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(string))]
    pub struct Span {
      from: String,
      to: String,
    }
  };
  let sentence = refused(super::parse(&two, Face::Filter));
  assert!(sentence.contains("holds ONE value"), "{sentence}");
  assert!(sentence.contains("holds 2"), "{sentence}");

  let unit: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(string))]
    pub struct Nothing;
  };
  let sentence = refused(super::parse(&unit, Face::Filter));
  assert!(sentence.contains("holds 0"), "{sentence}");
}

/// **A VOCABULARY IS NOT AN ELEMENT**, and the refusal names the door that serves one.
#[test]
fn a_marked_enum_names_the_vocabulary_door() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(r#enum))]
    pub enum Codec {
      H264,
    }
  };
  let sentence = refused(super::parse(&input, Face::Filter));
  assert!(sentence.contains("ingraph::Enum"), "{sentence}");
}

/// **THE MARKER IS THE FILTER DOOR'S WORD**, refused at the other two — whose faces are over a row's
/// COLUMNS, and an element has none.
#[test]
fn the_marker_refuses_at_the_two_doors_that_face_a_row() {
  for face in [Face::Comparison, Face::OrderBy] {
    let input: syn::DeriveInput = syn::parse_quote! {
      #[ingraph(operator(string))]
      pub struct Tag(String);
    };
    let sentence = refused(super::parse(&input, face));
    assert!(sentence.contains("declares an ELEMENT"), "{sentence}");
    assert!(
      sentence.contains("#[derive(ingraph::Filter)]"),
      "{sentence}"
    );
  }
}

/// **THE WORDS AN ELEMENT DOES NOT SPEND REFUSE BY NAME**, each at the token that wrote it — the
/// struct mode's own rule, applied to the container words a value has no use for.
#[test]
fn the_container_words_an_element_does_not_spend_refuse_by_name() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(
      operator(string),
      sqlite,
      comparison(rename = "TagPredicate"),
      order_by(rename = "TagOrder"),
      filter = "TagWhere"
    )]
    pub struct Tag(String);
  };
  let sentence = refused(super::parse(&input, Face::Filter));
  // Every row quotes the WORD the author typed, the storage one included. It used to quote the
  // wrapper — `persist(…)` — and the unwrap left it with four possible spellings, so it quotes
  // whichever was written rather than a description of the family.
  for word in [
    "`sqlite`",
    "comparison(rename",
    "order_by(rename",
    "filter = ",
  ] {
    assert!(sentence.contains(word), "{sentence}");
  }
}

/// **AN ELEMENT'S FIELD TAKES NO WORD**, the container's marker having already said what it is read
/// as.
#[test]
fn a_word_on_the_elements_own_field_refuses_by_name() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(string))]
    pub struct Tag(#[ingraph(string)] String);
  };
  let sentence = refused(super::parse(&input, Face::Filter));
  assert!(sentence.contains("takes no `#[ingraph(…)]`"), "{sentence}");
}

/// **`filter(rename = "…")` MOVES THE MINTED NAME**, which is the one container word an element
/// keeps: it names the type this door emits, exactly as it names the struct mode's.
#[test]
fn the_rename_word_moves_the_minted_filters_name() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(string), filter(rename = "LabelPredicate"))]
    pub struct Label(String);
  };
  assert_eq!(
    element(super::parse(&input, Face::Filter))
      .filter
      .safe()
      .to_string(),
    "LabelPredicate"
  );
}

/// **ONE DECLARATION IS ONE ELEMENT**, so a second marker is refused rather than silently taken.
#[test]
fn a_second_marker_refuses() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(operator(string), operator(scalar))]
    pub struct Tag(String);
  };
  let sentence = refused(super::parse(&input, Face::Filter));
  assert!(sentence.contains("more than once"), "{sentence}");
}

/// **`graphql(rename = "…")` NAMES THE ELEMENT'S SCALAR** — the rename-parity ruling's row for this
/// door, and the axis it does not touch is the point.
///
/// An element publishes two schema entities: the SCALAR its value crosses as, and the input object
/// its minted filter is. `filter(rename = "…")` already moved the second — and moved the Rust type
/// with it, both being the filter's — while the first had nowhere to go at all.
#[test]
fn the_element_scalar_takes_the_word_the_declaration_gives_it() {
  let model = element(super::parse(
    &syn::parse_quote! {
      #[ingraph(operator(string), graphql(rename = "Label"))]
      pub struct Tag(String);
    },
    Face::Filter,
  ));

  assert_eq!(model.wire_name.as_deref(), Some("Label"));
  assert_eq!(model.subject, "Tag", "the Rust name does not move");
  assert_eq!(
    model.filter.external(),
    "TagFilter",
    "and neither does the minted filter's, which has a word of its own"
  );

  let bare = element(super::parse(
    &syn::parse_quote! {
      #[ingraph(operator(string))]
      pub struct Tag(String);
    },
    Face::Filter,
  ));
  assert_eq!(bare.wire_name, None);
}

/// A schema name is GraphQL's word rather than Rust's, so the fence is the Name grammar and a Rust
/// keyword is ordinary here.
#[test]
fn the_element_scalars_word_rides_the_name_grammar() {
  let refused = refused(super::parse(
    &syn::parse_quote! {
      #[ingraph(operator(string), graphql(rename = "Not A Name"))]
      pub struct Tag(String);
    },
    Face::Filter,
  ));
  assert!(refused.contains("is not a GraphQL name"), "{refused}");

  let keyword = element(super::parse(
    &syn::parse_quote! {
      #[ingraph(operator(string), graphql(rename = "type"))]
      pub struct Tag(String);
    },
    Face::Filter,
  ));
  assert_eq!(keyword.wire_name.as_deref(), Some("type"));
}

/// **THE OTHER TWO MODES MINT NO SCALAR, AND EACH REFUSES THE WORD BY NAME.**
///
/// A composed filter IS an input object, and a struct-mode face is a predicate over somebody else's
/// columns — so in both the one wire name a client reads is the filter's, which already has a seat.
/// A word parsed into a model nothing spends is a promise rather than a rule.
#[test]
fn refuses_the_scalars_word_where_no_scalar_is_minted() {
  let composed = refused(super::parse(
    &syn::parse_quote! {
      #[ingraph(composed, graphql(rename = "Rate"))]
      pub struct RateFilter { eq: Option<u32> }
    },
    Face::Filter,
  ));
  assert!(
    composed.contains("mints no scalar for a schema to name"),
    "{composed}"
  );

  let plain = refused(super::parse(
    &syn::parse_quote! {
      #[ingraph(graphql(rename = "Rate"))]
      pub struct Rate { hz: u32 }
    },
    Face::Filter,
  ));
  assert!(
    plain.contains("names the SCALAR an element publishes"),
    "{plain}"
  );
  assert!(
    plain.contains("`operator(<family>)`"),
    "and it names the reading that would give it one: {plain}"
  );
}