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 EQUIVALENCE PIN** — the sugar word's expansion, against the expansion of the recipe an
//! author would have written by hand.
//!
//! # What an equality alone would NOT prove, and why the inequality rides beside it
//!
//! Two token streams built by one function are equal for free. So every equality here is paired with
//! a case that DIFFERS by one word of the sugared declaration and is asserted UNEQUAL — the same
//! discipline `search::fuse::dedup_tests` is written under. Without it, an expansion that had
//! quietly stopped reading the tower would pass.
//!
//! # The comparison is on the EXPANSION and not on the declaration
//!
//! The forged declaration carries its types as string literals, and a literal this crate builds from
//! tokens is spelled with the spacing `quote!` gives it — `"< crate :: T as … >"` where an author
//! writes `"<crate::T as …>"`. Those are the same TYPE and different BYTES, so the claim worth
//! pinning is the one downstream of the parse: what the two declarations EMIT.

use ingraph_codegen::{index::IndexModel, prelude::*};

/// A token stream with its whitespace collapsed — the shape a token-equality assertion is readable
/// in, and `search::fuse`'s own convention for one.
fn tight(tokens: &proc_macro2::TokenStream) -> String {
  tokens.to_string().split_whitespace().collect()
}

/// The index declaration under test, parsed — one election, whose road the caller writes.
fn index(road: proc_macro2::TokenStream) -> IndexModel {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(
      upstream(node = "media::Keyframe", clip = "clip"),
      dedup(hash),
      graphql(async_graphql)
    )]
    pub struct Shots {
      #[ingraph(embedding, knn(searchable(tower = #road)), toy)]
      clip: Embedding<f32, 4, Clip>,
    }
  };
  let (host, arguments) = crate::host::split(&input);
  crate::index::parse(&host, &arguments, NodeKind::Vector).expect("the declaration is legal")
}

/// The SUGAR's whole output for that declaration.
fn sugared(road: proc_macro2::TokenStream) -> proc_macro2::TokenStream {
  super::recipes(&index(road))
}

/// What the recipe macro emits for a declaration written BY HAND — `equipped`'s body, spelled out.
fn handwritten(
  arguments: proc_macro2::TokenStream,
  item: syn::DeriveInput,
) -> proc_macro2::TokenStream {
  let arguments = crate::host::options(arguments);
  let host = crate::host::echo(&item);
  let expansion = crate::search::parse(&item, &arguments)
    .as_ref()
    .map_or_else(
      syn::Error::to_compile_error,
      ingraph_codegen::search::SearchModel::emit,
    );
  quote::quote!(#host #expansion)
}

/// The hand-written twin of `sugared(quote!("media::ClipText"))`, verbatim.
fn twin() -> proc_macro2::TokenStream {
  handwritten(
    quote::quote! {
      crate = "::ingraph",
      shared(question(type = "<media::ClipText as ::ingraph::SearchTower>::Question")),
      graphql(async_graphql)
    },
    syn::parse_quote! {
      pub struct ShotsClipSearch {
        #[ingraph(tower(question(type = "media::ClipText", shared)))]
        shots: Shots,
      }
    },
  )
}

/// **THE WORD IS THE RECIPE, TOKEN FOR TOKEN** — the whole claim of the sugar, and the reason
/// nothing downstream can tell a sugared column from a typed one.
#[test]
fn the_sugars_expansion_is_the_hand_written_recipes() {
  assert_eq!(
    tight(&sugared(quote::quote!("media::ClipText"))),
    tight(&twin()),
    "the forged recipe is not the hand-written one",
  );
}

/// **THE EQUALITY IS ABOUT THIS DECLARATION AND NOT ABOUT ALL OF THEM** — a different tower forges a
/// different expansion, so the pin above is reading the word rather than a constant.
#[test]
fn a_different_tower_forges_a_different_expansion() {
  assert_ne!(
    tight(&sugared(quote::quote!("media::ClipImage"))),
    tight(&twin()),
    "the expansion does not depend on the tower the election named",
  );
}

/// **AN ELECTION WITH NO ROAD FORGES NOTHING**, which is what keeps the word from moving a
/// declaration that never wrote it.
#[test]
fn an_election_with_no_road_forges_no_recipe() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(upstream(node = "media::Keyframe", clip = "clip"), dedup(hash))]
    pub struct Shots {
      #[ingraph(embedding, knn, toy)]
      clip: Embedding<f32, 4, Clip>,
    }
  };
  let (host, arguments) = crate::host::split(&input);
  let model = crate::index::parse(&host, &arguments, NodeKind::Vector).expect("legal");
  assert!(
    super::recipes(&model).is_empty(),
    "a declaration that wrote no road forged a recipe anyway",
  );
}

/// **THE FORGED DECLARATION IS THE ONE A READER CAN PICTURE** — its name, its member and the two
/// quoted types, read off the tokens rather than off the expansion.
///
/// The name is load-bearing beyond Rust: the recipe's wire fields are `lower_initial` of exactly it,
/// so `shotsClipSearch` and `shotsClipSearchKeys` are what a client asks.
#[test]
fn the_forged_declaration_names_the_index_and_the_column() {
  let model = index(quote::quote!("media::ClipText"));
  let elected = &model.embeddings[0];
  let road = elected.tower_road.as_ref().expect("a road");
  let (arguments, item) = super::declaration(&model, elected, road);

  assert_eq!(item.ident, "ShotsClipSearch");
  let syn::Data::Struct(data) = &item.data else {
    panic!("the forged declaration is a struct")
  };
  let member = data.fields.iter().next().expect("one member");
  assert_eq!(member.ident.as_ref().expect("a named member"), "shots");
  let typed = quote::quote!(#member).to_string();
  assert!(typed.contains("Shots"), "{typed}");

  let head = tight(&quote::quote!(#(#arguments)*));
  assert!(head.contains("SearchTower>::Question"), "{head}");
  assert!(head.contains("graphql(async_graphql)"), "{head}");
}

/// **THE INDEX'S OWN `graphql(…)` IS WHAT DRESSES THE RECIPE**, so a declaration that dresses
/// nothing forges a recipe that mounts nothing — the word invents no wire face.
#[test]
fn an_undressed_index_forges_an_undressed_recipe() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(upstream(node = "media::Keyframe", clip = "clip"), dedup(hash))]
    pub struct Shots {
      #[ingraph(embedding, knn(searchable(tower = "media::ClipText")), toy)]
      clip: Embedding<f32, 4, Clip>,
    }
  };
  let (host, arguments) = crate::host::split(&input);
  let model = crate::index::parse(&host, &arguments, NodeKind::Vector).expect("legal");
  let elected = &model.embeddings[0];
  let (head, _) = super::declaration(
    &model,
    elected,
    elected.tower_road.as_ref().expect("a road"),
  );
  assert!(
    !tight(&quote::quote!(#(#head)*)).contains("graphql"),
    "an index that named no backend forged a dressed recipe",
  );
}