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 TOP-LEVEL `rename` — the BONE axis, in both of its forms and at every kind.
//!
//! Beside [`skins`](super::skins) rather than inside it, and the split is the axis law read as a
//! file layout: that file is what a SCHEMA calls things and this one is what RUST calls them. A
//! reader looking for either should find it whole and should not have to hold the other.
//!
//! What the rename does to an EMISSION is `ingraph-codegen`'s `index/bones.rs`, where the roster and
//! the landed items can be compared to each other. What is here is the grammar: the two forms, the
//! closed vocabulary, and the refusals each earns.

use ingraph_codegen::{
  index::{IndexModel, RenamePiece},
  prelude::NodeKind,
};

use super::tests::{fulltext, refused};

/// A VECTOR declaration electing two fields, whose head says `head` — the shape that mints the
/// widest family, so that a piece word has something to name.
fn vector(head: proc_macro2::TokenStream) -> syn::Result<IndexModel> {
  let (host, arguments) = crate::host::split(&syn::parse_quote! {
    #[ingraph(
      upstream(node = "a::A", clip = "clip", poster = "poster"),
      dedup(hash),
      #head
    )]
    struct D {
      #[ingraph(embedding, knn, lance)]
      clip: ::ingraph::Embedding<f32, 4, Clip>,
      #[ingraph(embedding, knn, lance)]
      poster: ::ingraph::Embedding<f32, 4, Clip>,
    }
  });
  super::super::index::parse(&host, &arguments, NodeKind::Vector)
}

#[test]
fn the_value_form_carries_a_base_and_the_declarations_own_ident_stays_put() {
  let model = vector(quote::quote! { rename = "ShotSearch" }).expect("a base rename is legal");
  assert_eq!(model.base().to_string(), "ShotSearch");
  // THE EXCLUSION, and it is the word's whole boundary: the author's struct is theirs.
  assert_eq!(model.index.to_string(), "D");
}

#[test]
fn the_block_form_carries_the_pieces_it_named_and_the_base_stays_the_declarations() {
  let model = vector(quote::quote! {
    rename(fuse_options = "MyKnobs", evidence = "WhoAgreed")
  })
  .expect("a piece rename is legal");
  assert_eq!(model.base().to_string(), "D", "no base was written");
  let rename = model.rename.as_ref().expect("the word was written");
  assert_eq!(
    rename
      .piece(RenamePiece::FuseOptions)
      .map(ToString::to_string),
    Some("MyKnobs".to_owned()),
  );
  assert_eq!(
    rename.piece(RenamePiece::Evidence).map(ToString::to_string),
    Some("WhoAgreed".to_owned()),
  );
  assert!(rename.piece(RenamePiece::FuseQuestion).is_none());
}

#[test]
fn the_two_forms_are_one_word_and_a_second_one_is_refused() {
  // VALUE XOR BLOCK, and the grammar is what makes it so: the two spellings cannot both be written
  // at ONE occurrence, so what is left to refuse is the second occurrence — whichever form it took.
  let e = refused(
    syn::parse_quote! {
      #[ingraph(
        upstream(node = "a::A", body = "text"),
        dedup(hash),
        rename = "ShotSearch",
        rename(fulltext_options = "MyKnobs"),
      )]
      struct D { #[ingraph(searchable)] body: String }
    },
    NodeKind::Fulltext,
  );
  assert!(e.contains("declared more than once"), "{e}");
  assert!(
    e.contains("the two forms are ONE word"),
    "and the sentence says what the two spellings are for: {e}",
  );
}

#[test]
fn a_bare_word_and_an_empty_block_are_told_both_forms() {
  for head in [quote::quote! { rename }, quote::quote! { rename() }] {
    let e = vector(head)
      .expect_err("a rename with nothing in it is refused")
      .into_iter()
      .map(|e| e.to_string())
      .collect::<Vec<_>>()
      .join("\n");
    assert!(e.contains("says nothing on its own"), "{e}");
    assert!(e.contains("rename(<piece>"), "{e}");
    assert!(
      e.contains("graphql(<backend>(prefix"),
      "and where the OTHER axis lives — under its own word, a skin's base being a STEM: {e}",
    );
  }
}

#[test]
fn the_piece_vocabulary_is_closed_and_wired_to_the_suggestion_engine() {
  let e = vector(quote::quote! { rename(fuse_option = "MyKnobs") })
    .expect_err("`fuse_option` is not a word")
    .into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>()
    .join("\n");
  assert!(e.contains("unknown mint in `rename(…)`"), "{e}");
  assert!(
    e.contains("did you mean `fuse_options`"),
    "a near miss is measured against the closed vocabulary: {e}",
  );
  // And the sentence says what the PER-FIELD mints take instead, which is the thing the vocabulary
  // deliberately does not cover.
  assert!(e.contains("re-bases all of them at once"), "{e}");
}

#[test]
fn every_word_in_the_vocabulary_is_a_word_the_grammar_reads() {
  // The vocabulary and the reader are one list: `RenamePiece::of` is what the walk asks, and
  // `RenamePiece::ALL` is what a near miss is measured against. A word in one and not the other
  // would be offered by a suggestion and refused by the next compile.
  for piece in RenamePiece::ALL {
    let path: syn::Path = syn::parse_str(piece.as_str()).expect("a word is a path");
    assert_eq!(RenamePiece::of(&path), Some(piece));
  }
}

#[test]
fn a_mint_this_declaration_does_not_have_is_refused_with_the_reason() {
  // The word is RIGHT and the declaration is the wrong shape for it, so the sentence says which
  // shape mints one rather than offering a near miss to a word already spelled correctly.
  let e = refused(
    syn::parse_quote! {
      #[ingraph(
        upstream(node = "a::A", body = "text"),
        dedup(hash),
        rename(fuse_options = "MyKnobs"),
      )]
      struct D { #[ingraph(searchable)] body: String }
    },
    NodeKind::Fulltext,
  );
  assert!(e.contains("mints none"), "{e}");
  assert!(
    e.contains("a full-text declaration is one route"),
    "and which shape does: {e}",
  );
}

#[test]
fn the_selector_is_nameable_only_where_the_declaration_mints_exactly_one() {
  let one = vector(quote::quote! { rename(engine_input = "WhichStore") });
  assert!(
    one.is_err(),
    "the fixture types no engine word, so it mints no selector",
  );

  let (host, arguments) = crate::host::split(&syn::parse_quote! {
    #[ingraph(
      upstream(node = "a::A", clip = "clip"),
      dedup(hash),
      rename(engine_input = "WhichStore"),
    )]
    struct D {
      #[ingraph(embedding, knn, lance(resource = "crate::Lance"))]
      clip: ::ingraph::Embedding<f32, 4, Clip>,
    }
  });
  let model = super::super::index::parse(&host, &arguments, NodeKind::Vector)
    .expect("one typed election mints one selector");
  assert_eq!(
    model
      .rename
      .as_ref()
      .and_then(|rename| rename.piece(RenamePiece::EngineInput))
      .map(ToString::to_string),
    Some("WhichStore".to_owned()),
  );
}

#[test]
fn an_artifact_family_is_told_it_mints_no_type_and_which_word_it_does_have() {
  let e = refused(
    syn::parse_quote! {
      #[ingraph(upstream(node = "a::A", payload = "pixels"), fs, rename = "Poster")]
      struct D { #[ingraph(repeated)] payload: Vec<u8> }
    },
    NodeKind::Blob,
  );
  // THE MEASUREMENT, and it is pinned in `ingraph-codegen`'s `index/bones.rs`: this kind lands no
  // type at all, so the word would move nothing.
  assert!(e.contains("lands no type in your scope"), "{e}");
  assert!(
    e.contains("slot = \"…\""),
    "and the durable name is what its author probably wants: {e}",
  );
  assert!(
    !e.contains("an engine is named by ONE word"),
    "the word was read as an engine rather than as this grammar's: {e}",
  );
}

#[test]
fn the_roster_a_collision_is_measured_against_moves_with_the_base() {
  // The roster is what the front end's collision refusals read, so a rename that reached the
  // emission and missed the roster would report a clash under a name nothing mints. Both sides move
  // together — `ingraph-codegen`'s `index/bones.rs` compares them item-for-item; here the claim is
  // that the FRONT END is reading the moved one.
  let model = fulltext(&syn::parse_quote! {
    #[ingraph(upstream(node = "a::A", body = "text"), dedup(hash), rename = "Shots")]
    struct D { #[ingraph(searchable)] body: String }
  })
  .expect("a legal renamed declaration");
  let rostered: Vec<String> = model
    .emitted_types()
    .iter()
    .map(|declared| declared.name.to_string())
    .collect();
  assert!(!rostered.is_empty(), "the fixture mints a family");
  assert!(
    rostered.iter().all(|name| name.starts_with("Shots")),
    "the roster is built on the new base: {rostered:?}",
  );
}

#[test]
fn a_base_is_an_identifier_and_a_piece_name_is_too() {
  // RUST names, unlike a skin's: these land as `struct`/`enum` idents in the declaring scope, so a
  // Rust keyword is not writable and neither is an empty string. The fence is the shared one every
  // emitted-type rename in this workspace takes.
  for head in [
    quote::quote! { rename = "" },
    quote::quote! { rename(fuse_options = "") },
  ] {
    let e = vector(head)
      .expect_err("an empty string is not an identifier")
      .into_iter()
      .map(|e| e.to_string())
      .collect::<Vec<_>>()
      .join("\n");
    assert!(e.contains("must be a valid identifier"), "{e}");
  }
}

#[test]
fn a_declaration_that_wrote_no_rename_is_built_on_its_own_ident() {
  let model = fulltext(&syn::parse_quote! {
    #[ingraph(upstream(node = "a::A", body = "text"), dedup(hash))]
    struct D { #[ingraph(searchable)] body: String }
  })
  .expect("legal");
  assert!(model.rename.is_none());
  assert_eq!(model.base().to_string(), "D");
}