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 `lanes(…)` WORD, read off an engine block — the roster it mints, the ENGINE's half it does
//! not read, and every refusal it carries.
//!
//! Beside [`engines`](super::engines) rather than inside it, on that file's own precedent: one file
//! per thing being proved, so a reader looking for what a fan MEANS in a declaration finds it whole.
//!
//! # What is asserted here, and what is asserted elsewhere
//!
//! Here: the MODEL a declaration produces, and the SENTENCE a refusal carries. What an expansion
//! WRITES — the `Lanes` impl, the probe seat, the per-word `const` audits — is `ingraph-codegen`'s;
//! that a declared roster reaches a real tantivy index and answers is `ingraph`'s
//! `tests/fulltext_lanes.rs`; and the compile-time collision refusal is a trybuild golden, because
//! the only honest way to read a `const` that will not evaluate is to compile it.
//!
//! # The PARTITION is asserted from BOTH sides
//!
//! A test that only checked *`accepts` was read* would pass for a walk that read everything,
//! including the knobs a backend owns. So every accepting test names what the walk must NOT have
//! swallowed — `tokenizer = "…"` still reaches the carried tokens, whole and in place.

use super::tests::{fulltext, refused};
use ingraph_codegen::prelude::NodeKind;

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

/// The roster one declaration's single leg minted, as `key(alias, …)[!]` strings — `!` marking the
/// catch-all — in declared order.
fn roster(spoken: &str) -> Vec<String> {
  let model = fulltext(&document(spoken)).expect("accepted");
  model.engines[0].engines[0]
    .lanes
    .iter()
    .map(|lane| {
      let accepts = lane
        .accepts
        .iter()
        .map(ToString::to_string)
        .collect::<Vec<_>>()
        .join(", ");
      let catch_all = if lane.catch_all.is_some() { "!" } else { "" };
      format!("{}({accepts}){catch_all}", lane.key)
    })
    .collect()
}

/// The tokens that leg carried to its engine, spaces squeezed out so a comparison reads.
fn carried(spoken: &str) -> String {
  let model = fulltext(&document(spoken)).expect("accepted");
  model.engines[0].engines[0]
    .options
    .to_string()
    .replace(' ', "")
}

/// The refusals a full-text declaration earns for `spoken`.
fn refusals(spoken: &str) -> String {
  refused(document(spoken), NodeKind::Fulltext)
}

/// **NO WORD, NO ROSTER** — and that is the whole of what absence means, since `Lanes` already
/// defaults to the undetermined lane.
#[test]
fn a_leg_that_named_no_lanes_mints_nothing() {
  assert!(roster("searchable, lexical").is_empty());
  assert!(roster("searchable, lexical(stored)").is_empty());
}

/// **A BARE WORD IS A LANE** — the minimal entry, answering only its own key.
#[test]
fn a_bare_word_is_a_lane_that_answers_its_own_key() {
  assert_eq!(
    roster("searchable, lexical(lanes(en, zh))"),
    ["en()", "zh()"]
  );
}

/// **THE ALIASES AND THE CATCH-ALL ARE READ**, in the order they were written.
#[test]
fn a_lane_carries_its_aliases_and_its_role() {
  assert_eq!(
    roster(
      "searchable, lexical(lanes(en(accepts(latn)), zh(accepts(hani, cmn)), rest(catch_all)))"
    ),
    ["en(latn)", "zh(hani, cmn)", "rest()!"],
  );
}

/// **THE ENGINE'S HALF IS NOT READ, AND IT IS NOT LOST** — `tokenizer = "…"` reaches the carried
/// tokens under its own lane, which is the block's own partition one grain down.
#[test]
fn a_lanes_own_knobs_are_carried_to_the_engine_verbatim() {
  let carried = carried(
    "searchable, lexical(lanes(en(accepts(latn), tokenizer = \"en_stem\"), zh(tokenizer = \
     \"jieba\")))",
  );
  assert_eq!(
    carried, "lanes(en(tokenizer=\"en_stem\"),zh(tokenizer=\"jieba\"))",
    "the lane keys, and inside each one exactly what this grammar did not read",
  );
  assert_eq!(
    roster(
      "searchable, lexical(lanes(en(accepts(latn), tokenizer = \"en_stem\"), zh(tokenizer = \
       \"jieba\")))"
    ),
    ["en(latn)", "zh()"],
    "and the framework's half is still read",
  );
}

/// **A LANE THAT CARRIED NOTHING DOES NOT APPEAR IN THE CARRIED TOKENS**, and a fan where no lane
/// did is not written at all — so an engine sees a fan only where there was something in it for the
/// engine.
#[test]
fn a_fan_of_framework_words_alone_carries_nothing() {
  assert_eq!(
    carried("searchable, lexical(lanes(en, zh(accepts(cmn))))"),
    ""
  );
  assert_eq!(
    carried("searchable, lexical(lanes(en, zh(tokenizer = \"jieba\")))"),
    "lanes(zh(tokenizer=\"jieba\"))",
  );
}

/// **THE FAN RIDES BESIDE THE BLOCK'S OTHER WORDS**, and takes none of them.
#[test]
fn the_fan_sits_beside_the_words_that_were_already_there() {
  let model = fulltext(&document(
    "searchable, lexical(stored, multi, lanes(en, zh), rrf = false)",
  ))
  .expect("accepted");
  let leg = &model.engines[0].engines[0];
  assert!(leg.stored, "`stored` is still read");
  assert!(!leg.rrf, "`rrf` is still read");
  assert_eq!(leg.lanes.len(), 2, "and the fan beside them");
}

// ─── THE TEETH ─────────────────────────────────────────────────────────────────────────────────

/// **REFUSED BY NAME ON A KIND WITH NO LANE STORY** — the courtesy every misplaced word in this
/// grammar gets, rather than a sweep into the carried half where it would go silent.
#[test]
fn a_fan_on_a_vector_election_is_refused_by_name() {
  let input: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", image = "pixels"), dedup(hash))]
    pub struct Frames {
      #[ingraph(knn, hnsw(lanes(en, zh)))]
      image: ingraph::Embedding<f32, 8>,
    }
  };
  let refusal = refused(input, NodeKind::Vector);
  assert!(
    refusal.contains("`lanes(…)` is the FULL-TEXT kind's"),
    "{refusal}"
  );
  assert!(refusal.contains("indexes no text"), "{refusal}");
}

/// **AN EMPTY FAN IS NOT THE UNFANNED CORPUS** — the refusal says which word means which.
#[test]
fn an_empty_fan_names_the_word_that_means_the_unfanned_corpus() {
  let refusal = refusals("searchable, lexical(lanes())");
  assert!(refusal.contains("names at least one lane"), "{refusal}");
  assert!(
    refusal.contains("leave `lanes` off"),
    "the reader is told what saying nothing already means: {refusal}",
  );
  assert!(
    refusals("searchable, lexical(lanes)").contains("names at least one lane"),
    "a bare word is the same mistake",
  );
}

/// **A FAN IS A BLOCK AND NOT A VALUE.**
#[test]
fn a_fan_written_as_a_value_is_refused() {
  let refusal = refusals("searchable, lexical(lanes = \"en\")");
  assert!(refusal.contains("is a BLOCK and not a value"), "{refusal}");
}

/// **ONE CORPUS, ONE SET OF PARTITIONS.**
#[test]
fn two_fans_on_one_leg_are_refused() {
  let refusal = refusals("searchable, lexical(lanes(en), lanes(zh))");
  assert!(
    refusal.contains("declared more than once") && refusal.contains("one set of partitions"),
    "{refusal}",
  );
}

/// **A LANE IS A WORD**, and the refusal names the two the framework claims inside one.
#[test]
fn a_lane_written_as_a_value_is_refused_and_names_the_claimed_words() {
  let refusal = refusals("searchable, lexical(lanes(zh = \"cmn\"))");
  assert!(
    refusal.contains("`zh` is a LANE and a lane is a WORD"),
    "{refusal}"
  );
  assert!(
    refusal.contains("`accepts` and `catch_all`"),
    "the sentence names what this grammar claims inside a lane: {refusal}",
  );
}

/// **THE CATCH-ALL IS BARE, AND ONE PER LANE.**
#[test]
fn the_catch_all_takes_no_value_and_is_written_once() {
  assert!(
    refusals("searchable, lexical(lanes(rest(catch_all = true)))").contains("is a BARE marker"),
  );
  let twice = refusals("searchable, lexical(lanes(rest(catch_all, catch_all)))");
  assert!(
    twice.contains("declared more than once on lane `rest`"),
    "{twice}",
  );
}

/// **`accepts` TAKES A LIST, NOT A VALUE, AND NOT AN EMPTY ONE.**
#[test]
fn the_alias_list_is_a_block_with_something_in_it() {
  let valued = refusals("searchable, lexical(lanes(zh(accepts = \"cmn\")))");
  assert!(valued.contains("as bare words in a block"), "{valued}");

  let empty = refusals("searchable, lexical(lanes(zh(accepts())))");
  assert!(empty.contains("names no tag at all"), "{empty}");

  let twice = refusals("searchable, lexical(lanes(zh(accepts(cmn), accepts(hani))))");
  assert!(
    twice.contains("declared more than once on lane `zh`"),
    "{twice}",
  );
}

/// **AN ACCEPTED TAG IS A BARE WORD.**
#[test]
fn an_accepted_tag_carries_nothing_inside_it() {
  let refusal = refusals("searchable, lexical(lanes(zh(accepts(cmn = 1))))");
  assert!(refusal.contains("a tag is a bare word"), "{refusal}");
}

/// **THE CLAIMED-WORD LIST GREW BY ONE**, and the sentence that quotes it says so.
///
/// The refusal an `engine = …` author earns names every word this grammar claims inside a block, so
/// a seventh word that did not reach it would be a word the sentence lied about.
#[test]
fn the_block_words_sentence_names_the_fan() {
  let refusal = refusals("searchable, lexical = \"x\"");
  assert!(
    refusal.contains("`multi`, `join`, `from`, `stored`, `resource`, `rrf`, `lanes`"),
    "{refusal}",
  );
}