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 rule this pass states, each put to a declaration that breaks it.
//!
//! The refusals are asserted here rather than only as fixtures, because a `trybuild` file 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.

/// The pass under test, over a declaration written the way the derive took one — see
/// [`host::split`](crate::host::split) for why these suites keep writing it in one piece.
fn parse(input: &syn::DeriveInput) -> syn::Result<ingraph_codegen::graph::GraphModel> {
  let (host, arguments) = crate::host::split(input);
  super::parse(&host, &arguments)
}

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

/// Parse a declaration, expecting the refusal it earns.
pub(super) 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")
}

/// The list survives in the order it was written, and the root's own name and visibility travel with
/// it.
#[test]
fn an_ingraph_is_its_field_list_in_order() {
  let model = accepted(quote::quote! {
    pub struct App {
      videos: media::Video,
      scenes: Scene,
    }
  });

  assert_eq!(model.name, "App");
  assert!(matches!(model.vis, syn::Visibility::Public(_)));
  assert_eq!(model.nodes.len(), 2);
  assert_eq!(
    quote::ToTokens::to_token_stream(&model.nodes[0]).to_string(),
    "media :: Video"
  );
  assert_eq!(
    quote::ToTokens::to_token_stream(&model.nodes[1]).to_string(),
    "Scene"
  );
}

/// `::ingraph` is the default, and a declaration may move it.
#[test]
fn the_crate_path_defaults_and_is_moveable() {
  let default = accepted(quote::quote! {
    struct App {
      videos: Video,
    }
  });
  assert_eq!(
    quote::ToTokens::to_token_stream(&default.krate).to_string(),
    ":: ingraph"
  );

  let moved = accepted(quote::quote! {
    #[ingraph(crate = "shim::vendored::ingraph")]
    struct App {
      videos: Video,
    }
  });
  assert_eq!(
    quote::ToTokens::to_token_stream(&moved.krate).to_string(),
    "shim :: vendored :: ingraph"
  );
}

/// An enum declares ALTERNATIVES, and a graph holds all of its nodes at once.
#[test]
fn an_enum_is_not_an_ingraph() {
  assert!(
    refused(quote::quote! {
      enum App {
        Videos(Video),
      }
    })
    .contains("a graph root is a STRUCT")
  );
}

/// A field's name is the mount name, so a positional field would leave the mount unnamed.
#[test]
fn a_positional_field_has_no_mount_name() {
  assert!(
    refused(quote::quote! {
      struct App(Video, Scene);
    })
    .contains("fields are NAMED")
  );

  assert!(
    refused(quote::quote! {
      struct App;
    })
    .contains("fields are NAMED")
  );
}

/// A graph with no field declares no node.
#[test]
fn an_empty_ingraph_declares_nothing_to_walk() {
  assert!(
    refused(quote::quote! {
      struct App {}
    })
    .contains("no field declares no node")
  );
}

/// A parameter is not a node until it is substituted.
#[test]
fn a_generic_root_names_a_different_ingraph_per_instantiation() {
  assert!(
    refused(quote::quote! {
      struct App<T> {
        videos: T,
      }
    })
    .contains("no generic parameter")
  );
}

/// One node, one field — a second field naming it would mount the same storage twice.
#[test]
fn a_node_listed_twice_is_refused_and_the_first_field_is_named() {
  let refusal = refused(quote::quote! {
    struct App {
      videos: Video,
      clips: Scene,
      archive: Video,
    }
  });
  assert!(refusal.contains("already in the graph"), "{refusal}");
  assert!(refusal.contains("`videos`"), "{refusal}");
}

/// A field takes ONE word, and it is not a node's: what a node is, and where it is stored, is its
/// own declaration's.
#[test]
fn a_field_carries_no_declaration_of_its_own() {
  assert!(
    refused(quote::quote! {
      struct App {
        #[ingraph(sqlite)]
        videos: Video,
      }
    })
    .contains("unknown entry in `#[ingraph(…)]` on a graph root's field")
  );
}

/// An unknown struct-level entry names what the grammar does take — ALL THREE entries, since the
/// engine table and the retired ledger both joined `crate` here.
///
/// The sentence is what an author who guessed wrong reads, so it has to list the words that exist
/// rather than the one that used to be the whole of the grammar — and it must NOT list `dedup(…)`,
/// which is refused by a sentence of its own. What each of the three later entries MEANS is proved
/// elsewhere: [`super::engines`] for the engine table, [`super::generations`] for the pointer seat's
/// own word, and the `retired` suite in `ingraph-derive/tests/graphs` for the ledger's.
#[test]
fn the_root_takes_its_four_entries_and_says_so() {
  let refusal = refused(quote::quote! {
    #[ingraph(sqlite)]
    struct App {
      videos: Video,
    }
  });
  assert!(refusal.contains("takes `crate = \"…\"`"), "{refusal}");
  assert!(
    refusal.contains("engines(<word> = \"path::To::Engine\")"),
    "and it names the engine table, which is the second of what a root declares: {refusal}"
  );
  assert!(
    refusal.contains("`retired(<engine>)`"),
    "and the ledger, which is the third: {refusal}"
  );
  assert!(
    refusal.contains("`generations(<engine>)`"),
    "and the generations seat, which is the fourth — the two of them being the only entries that \
     name a durable thing: {refusal}"
  );
  // AND THE RETIRED ENTRY IS GONE: `dedup(…)` is a recipe's word now, refused by its own sentence
  // and off this roster — see `super::dedup`.
  assert!(!refusal.contains("`dedup(…)`"), "{refusal}");
}

/// **THE REGISTRY SEAT'S OWN RESERVED MOUNT.** The emitted spine holds the root-key registry's
/// timing under `registry`, so a member of that name would be a second meaning for one document
/// key — [`super::reserve_the_registry_seat`]'s own rule, pinned here the way `resources`' is in
/// [`super::resource::tests`].
#[test]
fn a_member_may_not_be_mounted_at_the_registry_seat() {
  let refusal = refused(quote::quote! {
    struct App {
      videos: Video,
      registry: Registry,
    }
  });
  assert!(
    refusal.contains("`registry` is a RESERVED mount"),
    "{refusal}"
  );
  assert!(refusal.contains("[registry]"), "{refusal}");
  assert!(refusal.contains("[registry.<family>]"), "{refusal}");
}

/// Every rule the pass can still see is reported in ONE compile, which is what the shared error
/// collector is for.
#[test]
fn one_compile_reports_every_rule_it_can_still_see() {
  let refusal = refused(quote::quote! {
    #[ingraph(sqlite)]
    struct App<T> {
      videos: Video,
      archive: Video,
      other: T,
    }
  });
  assert!(refusal.contains("nothing else"), "{refusal}");
  assert!(refusal.contains("no generic parameter"), "{refusal}");
  assert!(refusal.contains("already in the graph"), "{refusal}");
}