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 REWRITE MODE's front half: what the word accepts, what it replaces, and the two attribute
//! rules the rewrite would otherwise swallow.
//!
//! The EMISSION's own rules are asserted where they can only be asserted — by a program that
//! compiles a wrapper and reaches its surface (`tests/entity_record_remote.rs`) and by the refusal
//! goldens beside it. What is here is the pass: the word reaches the model, the manifest survives
//! it, and the item the macro emits is the one the mode promises.

use ingraph_codegen::{model::NodeKind, prelude::*};
use quote::ToTokens as _;

/// The pass under test, over a declaration written the way the derive took one.
fn parse(input: &syn::DeriveInput, kind: NodeKind) -> syn::Result<RecordModel> {
  let (host, arguments) = crate::host::split(input);
  crate::parse::parse(&host, &arguments, kind)
}

/// Every refusal the pass reported, JOINED — one compile reports every rule it can still see, and a
/// `syn::Error` renders only the first of a combined one.
fn refusals(input: &syn::DeriveInput, kind: NodeKind) -> String {
  parse(input, kind)
    .expect_err("the declaration is refused")
    .into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>()
    .join("\n")
}

/// A declaration whose fields RESTATE a foreign type — the shape every case below varies.
fn manifest() -> syn::DeriveInput {
  syn::parse_quote! {
    #[ingraph(remote = "upstream::Dimensions")]
    pub struct Dimensions {
      /// The width, in pixels.
      #[ingraph(id, copy)]
      width: u32,
      #[ingraph(copy)]
      height: u32,
    }
  }
}

#[test]
fn the_word_reaches_the_model_as_the_path_it_names() {
  let m = parse(&manifest(), NodeKind::Entity).expect("a wrapping entity");
  let remote = m.remote.expect("the wrapped type").into_token_stream();
  assert_eq!(remote.to_string().replace(' ', ""), "upstream::Dimensions");
}

/// The manifest is READ exactly as a declaration's fields are read — that is the whole of "zero new
/// vocabulary". A column keeps its name, its type and its projection, and the identity words mean
/// what they mean anywhere else.
#[test]
fn the_manifest_is_read_as_ordinary_columns() {
  let m = parse(&manifest(), NodeKind::Entity).expect("a wrapping entity");
  let names: Vec<String> = m
    .fields
    .iter()
    .map(|field| field.column.source.to_string())
    .collect();
  assert_eq!(names, ["width", "height"]);
  assert!(m.fields[0].identity, "the `id` field bears identity");
  assert!(!m.fields[1].identity);
  assert_eq!(m.key.id.source, "width");
}

/// A field's doc comments are gathered in this mode and in no other, because this is the only mode
/// in which the field they were written on stops existing.
#[test]
fn a_manifest_fields_docs_are_carried_and_an_ordinary_fields_are_not() {
  let wrapping = parse(&manifest(), NodeKind::Entity).expect("a wrapping entity");
  assert_eq!(wrapping.fields[0].docs.len(), 1, "the `///` is carried");
  assert!(wrapping.fields[1].docs.is_empty(), "and only where written");

  let plain = parse(
    &syn::parse_quote! {
      pub struct Dimensions {
        /// The width, in pixels.
        #[ingraph(id, copy)]
        width: u32,
      }
    },
    NodeKind::Entity,
  )
  .expect("an ordinary entity");
  assert!(
    plain.fields[0].docs.is_empty(),
    "an ordinary declaration keeps its own fields, so nothing has to carry their docs"
  );
}

/// An OPERATOR does not take the word, because a wrapper exists to give a foreign type this
/// framework's faces and an operator publishes none of them.
///
/// The refusal names the declarations that DO, and there are three now: the two publishing rungs,
/// and the FIELD-FRAGMENT tier — which publishes no address either and needs none, its faces being
/// projections a holder resolves through rather than a key.
#[test]
fn an_operator_publishes_no_address_and_takes_no_wrapper() {
  let refused = refusals(&manifest(), NodeKind::Operator);
  assert!(
    refused.contains("publishes no address"),
    "the refusal names the rung's own absence: {refused}"
  );
  assert!(
    refused.contains("`entity`, `record` and `fields`"),
    "and names the three that take it: {refused}"
  );
}

#[test]
fn a_record_takes_the_word_beside_its_stores() {
  let m = parse(
    &syn::parse_quote! {
      #[ingraph(remote = "upstream::Dimensions", sqlite)]
      pub struct Dimensions {
        #[ingraph(id, copy)]
        width: u32,
        #[ingraph(copy)]
        height: u32,
      }
    },
    NodeKind::Record,
  )
  .expect("a wrapping record");
  assert!(m.remote.is_some());
  assert!(m.persist.is_some(), "the store words are untouched by it");
}

#[test]
fn one_declaration_wraps_one_type() {
  let refused = refusals(
    &syn::parse_quote! {
      #[ingraph(remote = "a::One", remote = "b::Two")]
      pub struct Dimensions {
        #[ingraph(id, copy)]
        width: u32,
      }
    },
    NodeKind::Entity,
  );
  assert!(
    refused.contains("`remote` is declared more than once"),
    "{refused}"
  );
}

/// A fan-in's ancestry is a field the macro MINTS, and a transparent wrapper's one position is the
/// wrapped type.
#[test]
fn a_wrapper_cannot_also_fan_in() {
  let refused = refusals(
    &syn::parse_quote! {
      #[ingraph(
        remote = "upstream::Dimensions",
        upstream(node = "a::One"),
        upstream(node = "b::Two"),
      )]
      pub struct Dimensions {
        #[ingraph(id, copy)]
        width: u32,
      }
    },
    NodeKind::Entity,
  );
  assert!(
    refused.contains("cannot also draw from several independent upstreams"),
    "{refused}"
  );
}

/// The macro OWNS the representation — it is the premise the reference family stands on.
#[test]
fn the_representation_is_the_macros_own() {
  let refused = refusals(
    &syn::parse_quote! {
      #[ingraph(remote = "upstream::Dimensions")]
      #[repr(C)]
      pub struct Dimensions {
        #[ingraph(id, copy)]
        width: u32,
      }
    },
    NodeKind::Entity,
  );
  assert!(
    refused.contains("does not choose its own representation"),
    "{refused}"
  );
}

/// A manifest field has no emitted body, so an attribute on one would be read by nobody.
#[test]
fn a_manifest_field_carries_no_attribute_of_its_own() {
  let refused = refusals(
    &syn::parse_quote! {
      #[ingraph(remote = "upstream::Dimensions")]
      pub struct Dimensions {
        #[ingraph(id, copy)]
        #[serde(rename = "w")]
        width: u32,
      }
    },
    NodeKind::Entity,
  );
  assert!(
    refused.contains("is a MANIFEST entry"),
    "the refusal names what a manifest field is: {refused}"
  );
}

/// `cfg` and `cfg_attr` are the two that are ACCEPTED, and the seat is why: the first reaches the
/// manifest field's whole generated family and the second rides its reader, so neither is an
/// attribute with nowhere to land. The refuse-until this replaces named that family and promised
/// exactly this.
#[test]
fn a_conditional_manifest_field_takes_its_seat() {
  for word in [
    quote::quote!(#[cfg(feature = "x")]),
    quote::quote!(#[cfg_attr(feature = "x", derive(Debug))]),
  ] {
    let input: syn::DeriveInput = syn::parse_quote! {
      #[ingraph(remote = "upstream::Dimensions")]
      pub struct Dimensions {
        #[ingraph(id, copy)]
        width: u32,
        #word
        height: u32,
      }
    };
    parse(&input, NodeKind::Entity).expect("a manifest field's condition has a seat");
  }
}

/// The ordinary declaration is untouched by every rule above — the two-mode discipline, asserted
/// rather than assumed.
#[test]
fn an_ordinary_declaration_keeps_every_attribute_it_writes() {
  let m = parse(
    &syn::parse_quote! {
      #[repr(C)]
      pub struct Dimensions {
        #[ingraph(id, copy)]
        #[serde(rename = "w")]
        #[cfg_attr(feature = "x", derive(Debug))]
        width: u32,
      }
    },
    NodeKind::Entity,
  )
  .expect("an ordinary entity is refused none of the rewrite's rules");
  assert!(m.remote.is_none());
}

/// The HOST a rewrite emits: the transparent wrapper, the author's own item attributes forwarded in
/// order, and the `#[ingraph(…)]` markers consumed.
#[test]
fn the_host_is_replaced_by_the_transparent_wrapper() {
  let input: syn::DeriveInput = syn::parse_quote! {
    /// A frame's dimensions.
    #[derive(Debug, Clone)]
    #[ingraph(remote = "upstream::Dimensions")]
    pub struct Dimensions {
      #[ingraph(id, copy)]
      width: u32,
    }
  };
  let remote: syn::Path = syn::parse_quote!(upstream::Dimensions);
  let host = crate::host::transparent(&input, &remote).to_string();
  let host = host.replace(' ', "");
  assert!(
    host.contains("#[repr(transparent)]"),
    "the representation is the macro's: {host}"
  );
  assert!(
    host.contains("pubstructDimensions(upstream::Dimensions)"),
    "one unnamed position holding the wrapped type: {host}"
  );
  assert!(
    host.contains("#[derive(Debug,Clone)]"),
    "the author's derives are forwarded: {host}"
  );
  assert!(
    host.contains("Aframe'sdimensions."),
    "and so is their documentation: {host}"
  );
  assert!(
    !host.contains("ingraph("),
    "the markers this macro read are consumed: {host}"
  );
}