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 ENGINE WORD'S TYPE — `resource = "path::To::Resource"` read off a block, on BOTH kinds, and the
//! two refusals it carries.
//!
//! Beside [`roads`](super::roads) rather than inside it, on that file's own precedent: one file per
//! thing being proved. The conversion grammar's five words stay there; this is the sixth, and it is
//! separate for a reason a reader should not have to infer — the other five are a FULL-TEXT
//! declaration's alone and this one is asked on both kinds, because a floor's currency is the
//! engine's whether the slot holds documents or coordinates.
//!
//! # What is asserted here, and what is asserted elsewhere
//!
//! Here: that the path is READ, that it is CARRIED nowhere else, and what a refusal says. What the
//! path becomes — the `@oneOf`, the variant packages, the `Score` projection — is
//! `ingraph-codegen`'s `fuse/engines.rs`, and whether a type that is not an engine is refused at
//! the declaration is `ingraph`'s `tests/engine_word/`, where there is a compiler to answer.
//!
//! # The partition is stated in BOTH directions
//!
//! The block is half read and half carried, so every accepting test below says what the read half
//! took AND that the carried half did not also take it. A walk that read the word and left it in
//! the engine's knobs would hand an engine a `type` entry it never declared.

use ingraph_codegen::{index::IndexModel, model::NodeKind};

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

/// A full-text document whose `title` wears the given marker list verbatim.
fn document(title: &str) -> syn::DeriveInput {
  let title: proc_macro2::TokenStream = title.parse().expect("a marker list");
  syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", title = "speaker", body = "text"), dedup(hash))]
    pub struct SearchDocument {
      #[ingraph(#title)]
      title: Vec<String>,
      #[ingraph(searchable)]
      body: String,
    }
  }
}

/// A knn declaration whose one election wears the given marker list verbatim.
fn coordinates(clip: &str) -> syn::DeriveInput {
  let clip: proc_macro2::TokenStream = clip.parse().expect("a marker list");
  syn::parse_quote! {
    #[ingraph(upstream(node = "media::Keyframe", clip = "clip"), dedup(hash))]
    pub struct Shots {
      #[ingraph(#clip)]
      clip: ::ingraph::Embedding<f32, 4, Clip>,
    }
  }
}

/// The FIRST engine block of the first field that declared one.
fn block(model: &IndexModel) -> &ingraph_codegen::engine::Engine {
  &model.engines[0].engines[0]
}

/// That block's pointed resource, as text a test can compare.
fn typed(model: &IndexModel) -> Option<String> {
  block(model).resource.as_ref().map(|path| {
    quote::ToTokens::to_token_stream(path)
      .to_string()
      .replace(' ', "")
  })
}

/// That block's carried half, as a string a test can look for a knob in.
fn carried(model: &IndexModel) -> String {
  block(model).options.to_string()
}

/// **A BLOCK THAT NAMES NO TYPE HAS NONE**, and that is the additive law's whole input: the word is
/// absent far more often than it is written, and absence has to reach the emission as absence.
#[test]
fn a_bare_block_names_no_type() {
  let model = fulltext(&document("searchable, lexical")).expect("accepted");
  assert_eq!(typed(&model), None);
  let model = parse(&coordinates("embedding, knn, lance"), NodeKind::Vector).expect("accepted");
  assert_eq!(typed(&model), None);
}

/// **THE PATH IS READ, ON BOTH KINDS** — REFER-QUOTED, so it arrives as the author's own tokens and
/// resolves at the span they wrote.
#[test]
fn the_word_is_read_on_both_kinds() {
  let model = fulltext(&document(
    r#"searchable, lexical(resource = "app::Tantivy")"#,
  ))
  .expect("accepted");
  assert_eq!(typed(&model), Some("app::Tantivy".to_owned()));

  let model = parse(
    &coordinates(r#"embedding, knn, lance(resource = "app::vector::Lance")"#),
    NodeKind::Vector,
  )
  .expect("accepted");
  assert_eq!(typed(&model), Some("app::vector::Lance".to_owned()));
}

/// **IT IS READ AND NOT CARRIED.** The partition's other direction: an engine handed a `type` entry
/// it never declared is an engine asked to interpret one of the framework's own words.
#[test]
fn the_word_is_taken_out_of_what_the_engine_is_handed() {
  let model = parse(
    &coordinates(r#"embedding, knn, lance(resource = "app::Lance", nprobes = 8)"#),
    NodeKind::Vector,
  )
  .expect("accepted");
  assert_eq!(typed(&model), Some("app::Lance".to_owned()));
  assert!(
    !carried(&model).contains("type"),
    "the framework's word reached the engine: {}",
    carried(&model),
  );
  assert!(
    carried(&model).contains("nprobes"),
    "the engine's own knob was swallowed with it: {}",
    carried(&model),
  );
}

/// **IT COMPOSES WITH THE WORDS BESIDE IT.** `type` says which engine, `stored` says what that
/// engine keeps, and a road says how a value reaches it — three orthogonal facts about one block,
/// and reading one must not consume another.
#[test]
fn the_word_sits_beside_the_five_it_joined() {
  let model = fulltext(&document(
    r#"searchable, lexical(resource = "app::Tantivy", stored, join = ", ")"#,
  ))
  .expect("accepted");
  assert_eq!(typed(&model), Some("app::Tantivy".to_owned()));
  assert!(block(&model).stored, "the marker beside it was lost");
  assert_eq!(
    block(&model).road,
    ingraph_codegen::engine::Road::Join(syn::parse_quote!(", ")),
  );
}

/// **A WORD IS TYPED ONCE.** Two paths in one block are two engines behind one word, and there is
/// no reading of it more likely than the other.
#[test]
fn a_block_that_types_itself_twice_is_refused() {
  let refusal = refused(
    coordinates(r#"embedding, knn, lance(resource = "app::A", resource = "app::B")"#),
    NodeKind::Vector,
  );
  assert!(refusal.contains("more than once"), "{refusal}");
  assert!(refusal.contains("one leg, one store"), "{refusal}");
}

/// **IT IS A PATH IN A STRING LITERAL, and a bare one is refused BY NAME.** The refer-quoted law:
/// a word that points at something written elsewhere is written in a literal, so an author who
/// wrote the path bare is told the shape rather than left with a parse error about tokens.
#[test]
fn a_bare_path_is_refused() {
  let refusal = refused(
    coordinates("embedding, knn, lance(resource = app::Lance)"),
    NodeKind::Vector,
  );
  assert!(refusal.contains("path::To::Resource"), "{refusal}");
}