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
//! Every spelling the resource word takes, and every one it refuses.
//!
//! The `trybuild` fixtures beside this pin the MESSAGE a reader sees; this pins the RULE, which is
//! the division the rest of this crate's suites keep: a pass that stopped reading the word would
//! print nothing, and so would one that read it right.

use ingraph_codegen::catalog::ResourceSource;

/// The whole front end, over a declaration written the way the derive took one.
fn parse(input: proc_macro2::TokenStream) -> syn::Result<ingraph_codegen::graph::GraphModel> {
  let input: syn::DeriveInput = syn::parse2(input).expect("the declaration parses");
  let (host, arguments) = crate::host::split(&input);
  crate::graph::parse(&host, &arguments)
}

/// Parse a declaration, expecting it to be accepted.
pub(super) fn accepted(input: proc_macro2::TokenStream) -> ingraph_codegen::graph::GraphModel {
  parse(input).expect("the declaration is a graph")
}

/// Parse a declaration, expecting the refusal it earns.
pub(super) fn refused(input: proc_macro2::TokenStream) -> String {
  parse(input)
    .expect_err("this declaration breaks a rule")
    .into_iter()
    .map(|error| error.to_string())
    .collect::<Vec<_>>()
    .join("\n")
}

/// **THE THREE SPELLINGS, ON ONE ROOT.** The bare word is the document's section, bare `factory` is
/// the application's own `prepare` closure, and the assigned form is the function the walk calls —
/// each read off the field, in the order the fields were written.
#[test]
fn the_word_takes_its_three_forms_and_they_stay_in_order() {
  let model = accepted(quote::quote! {
    pub struct App {
      videos: media::Video,
      #[ingraph(resource)]
      egemma: models::Egemma,
      #[ingraph(resource(factory))]
      pool: Pool,
      #[ingraph(resource(factory = "crate::boot::cache"))]
      cache: Cache,
    }
  });

  assert_eq!(model.nodes.len(), 1, "one field of four is a node");
  assert_eq!(model.mounts.len(), 1);
  assert_eq!(model.resources.len(), 3);

  assert_eq!(model.resources[0].mount, "egemma");
  assert_eq!(model.resources[0].source, ResourceSource::Section);
  assert_eq!(
    quote::ToTokens::to_token_stream(&model.resources[0].ty).to_string(),
    "models :: Egemma"
  );

  assert_eq!(model.resources[1].mount, "pool");
  assert_eq!(model.resources[1].source, ResourceSource::Prepare);

  assert_eq!(model.resources[2].mount, "cache");
  let ResourceSource::Initializer(path) = &model.resources[2].source else {
    panic!("the assigned form names a function");
  };
  assert_eq!(
    quote::ToTokens::to_token_stream(path).to_string(),
    "crate :: boot :: cache"
  );
}

/// An empty `resource()` is the bare word, which is the three-spellings rule the shared grammar
/// layer decides once for every block that takes optional options.
#[test]
fn an_empty_block_is_the_bare_word() {
  let model = accepted(quote::quote! {
    struct App {
      videos: Video,
      #[ingraph(resource())]
      egemma: Egemma,
    }
  });
  assert_eq!(model.resources[0].source, ResourceSource::Section);
}

/// **THE RESERVED MOUNT.** The emitted spine groups every resource's section under `resources`, so a
/// member of that name would be a second meaning for one document key — and the derive is the half
/// that knows why, so the derive is where the refusal is written.
#[test]
fn a_member_may_not_be_mounted_at_the_grouping_key() {
  for declaration in [
    quote::quote! {
      struct App {
        videos: Video,
        resources: Registry,
      }
    },
    quote::quote! {
      struct App {
        videos: Video,
        #[ingraph(resource)]
        resources: Registry,
      }
    },
  ] {
    let refusal = refused(declaration);
    assert!(
      refusal.contains("`resources` is a RESERVED mount"),
      "{refusal}"
    );
    assert!(refusal.contains("[resources.<field>]"), "{refusal}");
  }
}

/// A field's word is one of three, and anything else names what the grammar takes — including the
/// node words, which belong to the node's own declaration.
#[test]
fn an_unknown_field_word_names_what_a_field_takes() {
  let refusal = refused(quote::quote! {
    struct App {
      #[ingraph(sqlite)]
      videos: Video,
    }
  });
  assert!(
    refusal.contains("unknown entry in `#[ingraph(…)]` on a graph root's field"),
    "{refusal}"
  );
  assert!(refusal.contains("`resource(factory)`"), "{refusal}");
}

/// An unknown entry INSIDE the word says the same thing one level down.
#[test]
fn an_unknown_entry_in_the_block_names_what_the_block_takes() {
  let refusal = refused(quote::quote! {
    struct App {
      #[ingraph(resource(lazy))]
      egemma: Egemma,
    }
  });
  assert!(
    refusal.contains("unknown entry in `resource(…)`"),
    "{refusal}"
  );
}

/// The named form is REFER-QUOTED, as every word in this grammar that points at something written
/// elsewhere is.
#[test]
fn the_named_factory_is_a_quoted_path() {
  let refusal = refused(quote::quote! {
    struct App {
      #[ingraph(resource(factory = boot::cache))]
      cache: Cache,
    }
  });
  assert!(refusal.contains("in a string literal"), "{refusal}");
}

/// A member is one citizen, and its options have ONE source — so the word is written once.
#[test]
fn the_word_is_written_once_per_field() {
  let refusal = refused(quote::quote! {
    struct App {
      videos: Video,
      #[ingraph(resource)]
      #[ingraph(resource(factory))]
      egemma: Egemma,
    }
  });
  assert!(
    refusal.contains("`resource` is declared more than once"),
    "{refusal}"
  );
}

/// **ONE NAMESPACE.** A type written twice is refused whichever tier the two fields are, and the
/// sentence a reader gets is about the tier that would be declared twice.
#[test]
fn one_type_is_one_member_across_both_tiers() {
  let refusal = refused(quote::quote! {
    struct App {
      #[ingraph(resource)]
      egemma: Egemma,
      #[ingraph(resource(factory))]
      second: Egemma,
    }
  });
  assert!(refusal.contains("already in the graph"), "{refusal}");
  assert!(
    refusal.contains("declare it twice under two mounts"),
    "{refusal}"
  );
}