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 LEADERBOARD WORD — `rrf = <bool>` read off an engine block, on BOTH kinds, and the refusals
//! it carries.
//!
//! Beside [`engine_types`](super::engine_types) rather than inside it, on that file's own precedent:
//! one file per thing being proved. `type =` is the SIXTH framework word and this is the SEVENTH,
//! and they are separate because they say different things about one leg — addressability, and
//! leaderboard membership.
//!
//! # What is asserted here, and what is asserted elsewhere
//!
//! Here: that the flag is READ, that it defaults to TRUE by absence, that it is carried to the
//! engine nowhere, and what each refusal says. What the flag DECIDES — the `Route` seats, the
//! evidence variants, whether the mini fuse door emits at all — is `ingraph-codegen`'s
//! `fuse/fanned.rs`; what it looks like when run is `ingraph`'s `tests/fanned_read.rs`.
//!
//! # The partition is stated in BOTH directions
//!
//! Every accepting test says what the read half took AND that the engine's own knobs rode through
//! beside it — a walk that read the flag and left it in the carried tokens would hand an engine an
//! `rrf` entry it never declared.

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

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

/// 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>,
    }
  }
}

/// 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,
    }
  }
}

/// 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 carried half, as a string a test can look for a knob in.
fn carried(model: &IndexModel) -> String {
  block(model).options.to_string()
}

/// **ABSENT IS TRUE**, which is the de-Option law at this word: the shape a fan had before the word
/// existed is the shape a declaration that says nothing keeps.
#[test]
fn a_bare_block_is_in_the_leaderboard() {
  let model = parse(&coordinates("embedding, knn, lance"), NodeKind::Vector).expect("accepted");
  assert!(block(&model).rrf);
}

/// **THE WORD IS READ ON BOTH KINDS**, for `type =`'s reason: whether a fan is a leaderboard or is
/// redundancy is a question about the SLOT, not about what the store holds.
#[test]
fn the_word_is_read_on_both_kinds() {
  let vector = parse(
    &coordinates("embedding, knn, lance(rrf = false)"),
    NodeKind::Vector,
  )
  .expect("accepted");
  assert!(!block(&vector).rrf);

  let text = fulltext(&document("searchable, lexical(rrf = false)")).expect("accepted");
  assert!(!block(&text).rrf);
}

/// **AND IT IS TAKEN OUT OF WHAT THE ENGINE IS HANDED**, while the engine's own knobs ride through
/// untouched — the partition, in both directions.
#[test]
fn the_word_is_taken_out_of_what_the_engine_is_handed() {
  let model = parse(
    &coordinates("embedding, knn, hnsw(rrf = false, ef = 200)"),
    NodeKind::Vector,
  )
  .expect("accepted");
  assert!(!block(&model).rrf, "the framework's word was read");
  assert!(
    !carried(&model).contains("rrf"),
    "and taken out of what the engine is handed: {}",
    carried(&model),
  );
  assert!(
    carried(&model).contains("ef") && carried(&model).contains("200"),
    "while the engine's own knob rode through untouched: {}",
    carried(&model),
  );
}

/// **IT IS ORTHOGONAL TO `type =`**, and both are read off one block — the four quadrants the
/// orthogonality law names are all writable.
#[test]
fn the_two_words_sit_beside_each_other() {
  let model = parse(
    &coordinates("embedding, knn, lance(resource = \"app::Lance\", rrf = false)"),
    NodeKind::Vector,
  )
  .expect("accepted");
  assert!(!block(&model).rrf);
  assert!(
    block(&model).resource.is_some(),
    "the typed half was eaten by the flag",
  );
}

/// **THERE IS NO BARE FORM.** The default is already `true`, so a bare marker could only turn on
/// what is on — a word with no state to change, refused with the spelling that has one.
#[test]
fn a_bare_flag_is_refused() {
  let refusal = refused(coordinates("embedding, knn, lance(rrf)"), NodeKind::Vector);
  assert!(refusal.contains("takes a BOOLEAN"), "{refusal}");
  assert!(refusal.contains("rrf = false"), "{refusal}");
  assert!(
    refusal.contains("REDUNDANCY"),
    "the refusal says what the word is FOR: {refusal}",
  );
}

/// **AND THE VALUE IS WRITTEN BARE**, not in a string literal — a flag quoted is a flag nobody
/// checks.
#[test]
fn a_quoted_flag_is_refused() {
  let refusal = refused(
    coordinates("embedding, knn, lance(rrf = \"false\")"),
    NodeKind::Vector,
  );
  assert!(refusal.contains("takes a BOOLEAN"), "{refusal}");
}

/// **ONE LEG, ONE MEMBERSHIP** — declared twice is a refusal rather than a precedence.
#[test]
fn a_block_that_declares_its_membership_twice_is_refused() {
  let refusal = refused(
    coordinates("embedding, knn, lance(rrf = true, rrf = false)"),
    NodeKind::Vector,
  );
  assert!(refusal.contains("declared more than once"), "{refusal}");
  assert!(refusal.contains("one leg, one membership"), "{refusal}");
}

/// **THE BLOCK'S VOCABULARY IS STILL OPEN**, and the seventh word did not close it: an entry outside
/// the carved list is the ENGINE's and is carried, which is why there is no did-you-mean at this
/// position.
#[test]
fn the_seventh_word_did_not_close_the_block() {
  let model = parse(
    &coordinates("embedding, knn, hnsw(rrf_of_mine = 3, ef = 200)"),
    NodeKind::Vector,
  )
  .expect("accepted");
  assert!(
    block(&model).rrf,
    "an unread entry changed a framework fact"
  );
  assert!(
    carried(&model).contains("rrf_of_mine"),
    "a near miss was swallowed instead of carried: {}",
    carried(&model),
  );
}