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 two words the resource axis added — the BUILTIN KIND WORD and the MODE WORD — each put to a
//! declaration that spells it and to every declaration that breaks a rule about it.
//!
//! Beside `tests.rs` for the reason its own header gives one file over: that suite is about the
//! declaration a resource has always been, and this one is about the axis. The refusals are
//! asserted here as well as in `tests/refusals/`, because a fixture pins the MESSAGE a user sees and
//! this pins the RULE: a pass that stopped checking would still print nothing, and an empty error
//! list is what both look like from the outside.

use ingraph_codegen::resource::{ResourceKind, ResourceMode};

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

/// Parse a declaration, expecting it to be accepted.
fn accepted(input: proc_macro2::TokenStream) -> ingraph_codegen::resource::ResourceModel {
  parse(&syn::parse2(input).expect("the declaration parses"))
    .expect("the declaration is a resource")
}

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

/// A BARE declaration is the FOREIGN form on the BLOCKING face — the two defaults nobody writes.
#[test]
fn a_bare_declaration_is_foreign_and_blocking() {
  let model = accepted(quote::quote! {
    pub struct MyAnn(MyAnnEngine);
  });

  assert_eq!(model.kind, None);
  assert_eq!(model.mode, ResourceMode::Block);
}

/// THE MODE WORD is the FOREIGN form's, and it is the whole of what it does: the faces stay the
/// author's, and this is where the declaration says which pair they are.
#[test]
fn the_async_word_puts_a_foreign_resource_on_the_awaited_face() {
  let model = accepted(quote::quote! {
    #[ingraph(async)]
    pub struct MyRemote(RemoteQdrant);
  });

  assert_eq!(model.kind, None);
  assert_eq!(model.mode, ResourceMode::Async);
}

/// THE KIND WORD names one of the framework's own engines, and the declaration it takes holds
/// nothing: the expansion is what puts the engine there.
#[test]
fn a_kind_word_names_a_builtin_engine() {
  let model = accepted(quote::quote! {
    #[ingraph(tantivy)]
    pub struct Ft;
  });

  assert_eq!(model.kind, Some(ResourceKind::Tantivy));
}

/// THE KIND WORD CARRIES THE MODE, so an author writes nothing about a face for a builtin — and
/// nothing they could write would change it.
#[test]
fn a_kind_word_carries_its_own_mode() {
  let model = accepted(quote::quote! {
    #[ingraph(tantivy)]
    pub struct Ft;
  });

  assert_eq!(
    model.mode,
    ResourceMode::Block,
    "tantivy is a synchronous engine, and the word knows it"
  );
}

/// A kind word and `async` together are refused, and the sentence says which of them already
/// answered.
#[test]
fn a_builtin_takes_no_second_opinion_about_its_mode() {
  let refusal = refused(quote::quote! {
    #[ingraph(tantivy, async)]
    pub struct Ft;
  });

  assert!(
    refusal.contains("already knows which face"),
    "the refusal names the rule: {refusal}"
  );
  assert!(
    refusal.contains("FOREIGN form"),
    "and says whose word it is: {refusal}"
  );
}

/// A kind word MINTS the engine, so a declaration that already holds one is refused — in every
/// shape that holds something.
#[test]
fn a_builtin_declaration_holds_nothing_of_its_own() {
  for declaration in [
    quote::quote! {
      #[ingraph(tantivy)]
      pub struct Ft(TantivyStore);
    },
    quote::quote! {
      #[ingraph(tantivy)]
      pub struct Ft { store: TantivyStore }
    },
    quote::quote! {
      #[ingraph(tantivy)]
      pub enum Ft { One }
    },
  ] {
    let refusal = refused(declaration);
    assert!(
      refusal.contains("MINTS this resource's engine"),
      "the refusal names the rule: {refusal}"
    );
    assert!(
      refusal.contains("FOREIGN form"),
      "and names the form that wants the inner type: {refusal}"
    );
  }
}

/// The FOREIGN form still admits every shape there is, which is the rule the kind word narrows
/// rather than replaces.
#[test]
fn the_foreign_form_still_admits_every_shape() {
  for declaration in [
    quote::quote!(
      pub struct MyAnn;
    ),
    quote::quote!(
      pub struct MyAnn(MyAnnEngine);
    ),
    quote::quote! { pub struct MyAnn { engine: MyAnnEngine } },
    quote::quote! { pub enum Backend { Cpu, Metal } },
  ] {
    assert_eq!(accepted(declaration).kind, None);
  }
}

/// An unknown kind word is refused by a message LISTING the ones this build knows, which is the
/// closed vocabulary teaching itself.
#[test]
fn an_unknown_kind_word_is_refused_by_the_list() {
  let refusal = refused(quote::quote! {
    #[ingraph(lance)]
    pub struct VectorsA;
  });

  assert!(
    refusal.contains("BUILTIN KIND WORD"),
    "the refusal names the axis: {refusal}"
  );
  for word in ResourceKind::WORDS {
    assert!(
      refusal.contains(word),
      "and lists `{word}`, which this build knows: {refusal}"
    );
  }
}

/// Both words are BARE, and a value or a block on either is refused with the sentence saying where
/// that fact actually lives.
#[test]
fn neither_word_is_configured() {
  let refusal = refused(quote::quote! {
    #[ingraph(tantivy(heap = 200))]
    pub struct Ft;
  });
  assert!(
    refusal.contains("bare word"),
    "the kind word takes nothing: {refusal}"
  );
  assert!(
    refusal.contains("[resources."),
    "and says where an engine's knobs go: {refusal}"
  );

  let refusal = refused(quote::quote! {
    #[ingraph(async = "true")]
    pub struct MyRemote;
  });
  assert!(
    refusal.contains("bare word"),
    "the mode word takes nothing either: {refusal}"
  );
}

/// One resource is one engine, and one declaration wears one face.
#[test]
fn neither_word_is_written_twice() {
  let refusal = refused(quote::quote! {
    #[ingraph(tantivy, tantivy)]
    pub struct Ft;
  });
  assert!(refusal.contains("one resource is one engine"), "{refusal}");

  let refusal = refused(quote::quote! {
    #[ingraph(async, async)]
    pub struct MyRemote;
  });
  assert!(
    refusal.contains("one declaration wears one face"),
    "{refusal}"
  );
}

/// The words compose with `crate = "…"`, which is where every emitted path is read from — the kind
/// word's expansion naming more of them than any other declaration here.
#[test]
fn a_kind_word_composes_with_the_crate_word() {
  let model = accepted(quote::quote! {
    #[ingraph(crate = "crate::shim", tantivy)]
    pub struct Ft;
  });

  assert_eq!(model.kind, Some(ResourceKind::Tantivy));
  assert_eq!(
    quote::ToTokens::to_token_stream(&model.krate).to_string(),
    "crate :: shim"
  );
}