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
//! `engines(<word> = "path::To::Engine")` — the ROOT's half of the engine grammar.
//!
//! A field names its engines by WORD, and this is where a word means something. The two halves are
//! two expansions apart on purpose: a declaration is written before any deployment exists, so a path
//! written there would bind the engine in a library that cannot know which one an application
//! compiled.
//!
//! # What that division costs, stated because it is not free
//!
//! This pass cannot see the declarations, and they cannot see it. So *this word is bound* is not a
//! question either side can answer alone, and what is proved here is the half that IS answerable:
//! the entries this root wrote, the table they become, and every shape refused by name. The JOIN —
//! demanding that every word a member's field named has a row here — needs a projection through the
//! member, which is the face round's.

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

/// The bound words of a model, as `word=path` strings in declared order.
fn bound(model: &ingraph_codegen::graph::GraphModel) -> Vec<String> {
  model
    .engines
    .iter()
    .map(|binding| {
      format!(
        "{}={}",
        binding.word,
        quote::ToTokens::to_token_stream(&binding.engine)
          .to_string()
          .replace(' ', "")
      )
    })
    .collect()
}

#[test]
fn a_root_binds_a_word_to_a_concrete_engine() {
  let model = accepted(quote::quote! {
    #[ingraph(engines(hnsw = "app::hnsw::Hnsw"))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert_eq!(bound(&model), ["hnsw=app::hnsw::Hnsw"]);
}

/// ORDER is kept, so the emitted table reads down the declaration.
#[test]
fn several_words_keep_the_order_they_were_written_in() {
  let model = accepted(quote::quote! {
    #[ingraph(engines(hnsw = "app::Hnsw", lance = "app::Lance", sonic = "app::Sonic"))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert_eq!(
    bound(&model),
    ["hnsw=app::Hnsw", "lance=app::Lance", "sonic=app::Sonic"]
  );
}

/// The block is OPTIONAL and empty is the ordinary state: a deployment whose fields name only
/// shipped words binds nothing here.
#[test]
fn a_root_that_binds_nothing_is_the_ordinary_root() {
  let model = accepted(quote::quote! {
    pub struct App {
      frames: Keyframes,
    }
  });
  assert!(model.engines.is_empty());
}

/// `crate = "…"` is unaffected — the entry that was the graph root's whole grammar before this one
/// arrived.
#[test]
fn the_crate_entry_still_reads_beside_it() {
  let model = accepted(quote::quote! {
    #[ingraph(crate = "shim::ingraph", engines(hnsw = "app::Hnsw"))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert_eq!(
    quote::ToTokens::to_token_stream(&model.krate)
      .to_string()
      .replace(' ', ""),
    "shim::ingraph"
  );
  assert_eq!(bound(&model), ["hnsw=app::Hnsw"]);
}

/// A word `ingraph` SHIPS binds itself, under its own feature — the record side's law read onto this
/// axis. Rebinding it would give one word two meanings inside one program.
#[test]
fn a_shipped_word_cannot_be_rebound() {
  let refusal = refused(quote::quote! {
    #[ingraph(engines(tantivy = "app::MyTantivy"))]
    pub struct App {
      docs: SearchDocument,
    }
  });
  assert!(
    refusal.contains("BINDS ITSELF"),
    "the refusal says the word is already bound: {refusal}"
  );
  assert!(
    refusal.contains("feature = \"tantivy\""),
    "and where it is bound: {refusal}"
  );
}

#[test]
fn a_word_is_bound_once() {
  let refusal = refused(quote::quote! {
    #[ingraph(engines(hnsw = "app::Hnsw", hnsw = "app::Other"))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert!(
    refusal.contains("bound more than once"),
    "the refusal names the repeat: {refusal}"
  );
}

#[test]
fn one_root_holds_one_engine_table() {
  let refusal = refused(quote::quote! {
    #[ingraph(engines(hnsw = "app::Hnsw"), engines(lance = "app::Lance"))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert!(
    refusal.contains("declared more than once"),
    "the refusal names the second block: {refusal}"
  );
}

/// REFER-QUOTED, as every word in this grammar that points at something written elsewhere is.
#[test]
fn the_engine_is_quoted() {
  let refusal = refused(quote::quote! {
    #[ingraph(engines(hnsw = app::Hnsw))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert!(
    refusal.contains("in a string literal"),
    "the refusal states the spelling: {refusal}"
  );
}

/// The WORD is the entry's own name and the PATH is on the right, which is the one mistake this
/// shape invites.
#[test]
fn the_word_is_one_segment_and_the_path_goes_on_the_right() {
  let refusal = refused(quote::quote! {
    #[ingraph(engines(app::hnsw = "app::Hnsw"))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert!(
    refusal.contains("an engine word is ONE word"),
    "the refusal states the shape: {refusal}"
  );
  assert!(
    refusal.contains("goes on the right"),
    "and where the path belongs: {refusal}"
  );
}

/// The unknown-entry sentence NAMES the new word, so an author who guessed wrong is told what a root
/// actually takes.
#[test]
fn the_unknown_entry_sentence_names_the_engine_table() {
  let refusal = refused(quote::quote! {
    #[ingraph(backends(hnsw = "app::Hnsw"))]
    pub struct App {
      frames: Keyframes,
    }
  });
  assert!(
    refusal.contains("engines(<word> = \"path::To::Engine\")"),
    "the sentence lists what a root takes: {refusal}"
  );
}