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 BODY WORD's grammar, read straight off the pass.
//!
//! A suite of its own beside [`crate::parse::tests`] for [`crate::parse::channel_tests`]' reason:
//! what is asserted here is one word and the rule it completes — every `poll(…)` entry NAMES its
//! body, with `handler = "…"` or with `light`, and the older implicit form (neither word, meaning
//! the sweep method) is gone.
//!
//! The word is written BARE, and that is the mint-bare/refer-quoted law rather than an exception to
//! it: `light` refers to nothing a declaration named. It is the framework's own word for a road the
//! framework owns — the node's own `<Node>Sweeps` method, on the operator the driver lends for the
//! call — in the position `handler = "…"` writes a type path.

use ingraph_codegen::prelude::*;

/// The pass under test, at the kind these words belong to.
fn operator(input: &syn::DeriveInput) -> syn::Result<RecordModel> {
  let (host, options) = crate::host::split(input);
  crate::parse::parse(&host, &options, NodeKind::Operator)
}

/// Every refusal one declaration collects, as text.
fn refusals(input: syn::DeriveInput) -> Vec<String> {
  operator(&input)
    .expect_err("the declaration is refused")
    .into_iter()
    .map(|e| e.to_string())
    .collect()
}

/// Whether any of `messages` names `rule`.
fn names(messages: &[String], rule: &str) -> bool {
  messages.iter().any(|message| message.contains(rule))
}

/// The entries a model settled, as `(name, mounted)` pairs in declaration order.
fn bodies(model: &RecordModel) -> Vec<(String, bool)> {
  model
    .polls
    .as_ref()
    .map(|polls| {
      polls
        .entries
        .iter()
        .map(|entry| (entry.name.to_string(), entry.mounted()))
        .collect()
    })
    .unwrap_or_default()
}

/// The word runs the node's own sweep method, and the model records it as the unmounted road.
#[test]
fn a_light_entry_is_the_nodes_own_body() {
  let model = operator(&syn::parse_quote! {
    #[ingraph(poll(orphans, every = "10m", light, async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  })
  .expect("`light` names this node's own sweep method");
  assert_eq!(bodies(&model), [("orphans".to_owned(), false)]);
}

/// THE PRESENCE SPLIT, read off two words rather than off a silence: a node may mix the two roads,
/// and only the `light` clock reaches the sweep trait.
#[test]
fn a_mixed_node_splits_by_the_word_each_entry_wrote() {
  let model = operator(&syn::parse_quote! {
    #[ingraph(
      poll(scrape, every = "10m", handler = "app::Scraper", async(inline)),
      poll(vacuum, cron = "0 3 * * *", light, async(inline)),
    )]
    struct Indexer { #[ingraph(id)] id: Uuid7 }
  })
  .expect("a node may mix a mounted clock with a light one");
  assert_eq!(
    bodies(&model),
    [("scrape".to_owned(), true), ("vacuum".to_owned(), false)]
  );
  let polls = model.polls.expect("the clocks were read");
  assert_eq!(
    polls
      .sweeping()
      .map(|(_, entry)| entry.name.to_string())
      .collect::<Vec<_>>(),
    ["vacuum"],
    "the sweep trait holds the `light` clock and nothing else"
  );
}

/// ① NEITHER WORD — the implicit form is gone, and what replaces it is a sentence naming both roads.
#[test]
fn an_entry_that_names_no_body_is_refused() {
  let messages = refusals(syn::parse_quote! {
    #[ingraph(poll(orphans, every = "10m", async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  });
  assert!(names(&messages, "does not say WHO runs it"), "{messages:?}");
  // Both roads by name, and the trait a `light` body would be a method on.
  assert!(
    names(&messages, "`handler = \"…\"`")
      && names(&messages, "`light`")
      && names(&messages, "ReaperSweeps"),
    "{messages:?}"
  );
}

/// ② BOTH WORDS — one clock runs one body, which is the cadence pair's rule one question over.
#[test]
fn an_entry_that_names_both_bodies_is_refused() {
  let messages = refusals(syn::parse_quote! {
    #[ingraph(poll(orphans, every = "10m", light, handler = "app::Scraper", async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  });
  assert!(
    names(&messages, "names both `handler = \"…\"` and `light`"),
    "{messages:?}"
  );
}

/// ③ `light` × A DETACHED MODE — a borrow of the operator cannot be handed to another thread, and
/// the refusal is the same one whichever of the three words detached it.
#[test]
fn a_light_entry_cannot_be_detached() {
  for detached in ["spawn", "rayon", "async(spawn)"] {
    let mode: proc_macro2::TokenStream = detached.parse().expect("a mode word");
    let messages = refusals(syn::parse_quote! {
      #[ingraph(poll(orphans, every = "10m", light, #mode))]
      struct Reaper { #[ingraph(id)] id: Uuid7 }
    });
    assert!(
      names(&messages, "is `light` and runs") && names(&messages, "DETACHES the tick"),
      "{detached}: {messages:?}"
    );
  }
}

/// The two INLINE modes are exactly the ones a light body can take, and both are legal.
#[test]
fn a_light_entry_runs_in_place() {
  for inline in ["block", "async(inline)"] {
    let mode: proc_macro2::TokenStream = inline.parse().expect("a mode word");
    operator(&syn::parse_quote! {
      #[ingraph(poll(orphans, every = "10m", light, #mode))]
      struct Reaper { #[ingraph(id)] id: Uuid7 }
    })
    .unwrap_or_else(|e| panic!("`light` runs in place under `{inline}`: {e}"));
  }
}

/// A MOUNTED clock keeps every mode, the detached ones included — the rule is the light body's, not
/// the detached word's.
#[test]
fn a_mounted_clock_may_still_detach() {
  operator(&syn::parse_quote! {
    #[ingraph(poll(orphans, every = "10m", handler = "app::Scraper", spawn))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  })
  .expect("a citizen is a value the deployment built, so it can be handed over");
}

/// The word is BARE — presence is the whole answer, and the word that carries a value is the mount.
#[test]
fn light_carries_nothing() {
  for written in [
    quote::quote!(light = "app::Scraper"),
    quote::quote!(light(app::Scraper)),
  ] {
    let messages = refusals(syn::parse_quote! {
      #[ingraph(poll(orphans, every = "10m", #written, async(inline)))]
      struct Reaper { #[ingraph(id)] id: Uuid7 }
    });
    assert!(
      names(&messages, "`light` is a BARE word"),
      "{written}: {messages:?}"
    );
  }
}

/// Presence twice says what presence once already said.
#[test]
fn light_is_declared_once() {
  let messages = refusals(syn::parse_quote! {
    #[ingraph(poll(orphans, every = "10m", light, light, async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  });
  assert!(
    names(&messages, "`light` is declared more than once"),
    "{messages:?}"
  );
}

/// The word is this POSITION's, so an entry cannot also mint a clock called it — said in the
/// sentence about the missing name, where an author who wrote `light` and meant a name will read it.
#[test]
fn light_is_not_a_clocks_name() {
  let messages = refusals(syn::parse_quote! {
    #[ingraph(poll(light, every = "10m", async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  });
  assert!(
    names(&messages, "opens with the NAME this entry is minting")
      && names(&messages, "cannot also mint a clock called that"),
    "{messages:?}"
  );
}

/// A near miss of the new word, in the BARE position — the second bare word is measured against the
/// words this position takes bare, because a typo of `light` now reads as a second clock's name.
#[test]
fn a_near_miss_of_light_is_named_where_it_was_written() {
  let messages = refusals(syn::parse_quote! {
    #[ingraph(poll(orphans, ligth, every = "10m", async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  });
  assert!(
    names(&messages, "mints ONE name") && names(&messages, "did you mean `light`?"),
    "{messages:?}"
  );
}

/// The unknown-entry row learned the word too, so a near miss written in the KEYED shape lands on
/// the position's own vocabulary rather than on nothing.
#[test]
fn the_unknown_entry_row_offers_light() {
  let messages = refusals(syn::parse_quote! {
    #[ingraph(poll(orphans, every = "10m", ligth = "yes", async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  });
  assert!(
    names(&messages, "unknown entry in `poll(…)`") && names(&messages, "did you mean `light`?"),
    "{messages:?}"
  );
}

/// A NAME that is a near miss of nothing keeps the sentence it always had — the suggestion is a
/// second thing said about the same token, never a replacement for the first.
#[test]
fn a_second_clock_name_that_is_near_nothing_gains_no_clause() {
  let messages = refusals(syn::parse_quote! {
    #[ingraph(poll(orphans, stale, every = "10m", light, async(inline)))]
    struct Reaper { #[ingraph(id)] id: Uuid7 }
  });
  assert!(names(&messages, "mints ONE name"), "{messages:?}");
  assert!(!names(&messages, "did you mean"), "{messages:?}");
}