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 SUGAR WORD, READ: `knn(searchable(tower = "…"))` reaching its seat, and the four refusals
//! that keep it from meaning anything else.
//!
//! The word is the FULL-TEXT election marker's spelling in a second position, and that is deliberate
//! — one word means *a question can reach this column* on both kinds, and what it takes in each is
//! the difference between them: nothing where a question is already text, a TOWER where the column
//! holds coordinates. So the refusals here are mostly about the shape, and the one that is not is
//! the bare form: an author who wrote `knn(searchable)` wrote the word they know from the other
//! kind, and is owed the reason rather than the rule.
//!
//! What the word EXPANDS to is `search::sugar`'s, pinned there against a hand-written recipe.

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

/// The pass under test, under the one kind an election exists on.
fn parse(input: &syn::DeriveInput) -> syn::Result<IndexModel> {
  let (host, arguments) = crate::host::split(input);
  super::parse(&host, &arguments, NodeKind::Vector)
}

/// One `knn(…)` block over one election, so every case below differs by exactly its entry.
fn declaration(entry: proc_macro2::TokenStream) -> syn::DeriveInput {
  syn::parse_quote! {
    #[ingraph(upstream(node = "media::Keyframe", clip = "clip"), dedup(hash))]
    pub struct Shots {
      #[ingraph(embedding, knn(#entry), toy)]
      clip: Embedding<f32, 4, Clip>,
    }
  }
}

/// Every refusal the pass reported, JOINED — one compile reports every rule it can still see.
fn refusals(entry: proc_macro2::TokenStream) -> String {
  parse(&declaration(entry))
    .expect_err("the declaration is refused")
    .into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>()
    .join("\n")
}

/// **THE WORD REACHES ITS SEAT, CARRYING THE TOWER VERBATIM** — the path is the author's tokens and
/// nothing resolved them, which is what lets a tower in a crate this pass cannot see be named.
#[test]
fn the_road_reaches_the_election_as_the_type_its_author_wrote() {
  let model = parse(&declaration(
    quote::quote! { searchable(tower = "media::ClipText") },
  ))
  .expect("an election naming its tower road is legal");
  let road = model.embeddings[0]
    .tower_road
    .as_ref()
    .expect("the road did not reach its seat");
  assert_eq!(
    quote::quote!(#road).to_string().replace(' ', ""),
    "media::ClipText",
  );
}

/// **AN ELECTION THAT SAYS NOTHING KEEPS SAYING NOTHING** — the seat is empty, so every declaration
/// written before this word existed expands to exactly what it expanded to before.
#[test]
fn an_election_with_no_road_word_carries_none() {
  let model = parse(&syn::parse_quote! {
    #[ingraph(upstream(node = "media::Keyframe", clip = "clip"), dedup(hash))]
    pub struct Shots {
      #[ingraph(embedding, knn, toy)]
      clip: Embedding<f32, 4, Clip>,
    }
  })
  .expect("an election with a bare marker is legal");
  assert!(
    model.embeddings[0].tower_road.is_none(),
    "a road appeared on an election that wrote no word",
  );
}

/// **THE BARE FORM IS REFUSED WITH THE DIFFERENCE RATHER THAN THE RULE** — an author who wrote it
/// wrote the full-text marker they already know, and the sentence has to say why the same word takes
/// something here.
///
/// The empty block is the same mistake with parentheses on it and reaches the same sentence: a word
/// that decided nothing is a word that decided nothing either way.
#[test]
fn the_bare_word_is_told_what_the_two_positions_differ_by() {
  for entry in [quote::quote! { searchable }, quote::quote! { searchable() }] {
    let refused = refusals(entry.clone());
    assert!(
      refused.contains("names the TOWER"),
      "`{entry}` was not refused as a shape: {refused}",
    );
    assert!(
      refused.contains("It is BARE on a full-text election"),
      "the sentence does not say why the other position takes nothing: {refused}",
    );
    assert!(
      refused.contains("knn(searchable(tower = \"path::to::Tower\"))"),
      "the sentence does not spell the form: {refused}",
    );
  }
}

/// **THE TOWER IS QUOTED, AND AN UNQUOTED ONE IS TOLD WHICH LAW THAT IS** — mint bare, refer quoted,
/// the same crossing `fold = "…"` and `node = "…"` are written under.
#[test]
fn an_unquoted_tower_is_refused_under_the_crossing_law() {
  let refused = refusals(quote::quote! { searchable(tower = media::ClipText) });
  assert!(
    refused.contains("names the tower that walks a question"),
    "{refused}",
  );
  assert!(
    refused.contains("QUOTED"),
    "the sentence does not name the law: {refused}",
  );
}

/// **ONE ELECTION IS REACHED BY ONE ROAD**, and a second is told where two roads live — which is a
/// recipe with two members, not a word written twice.
#[test]
fn a_second_road_names_the_declaration_that_holds_two() {
  let refused = refusals(quote::quote! {
    searchable(tower = "media::ClipText", tower = "media::ClipImage")
  });
  assert!(
    refused.contains("`tower` is declared more than once"),
    "{refused}",
  );
  assert!(
    refused.contains("`#[ingraph::search]` recipe"),
    "the sentence does not say where a second road goes: {refused}",
  );
}

/// **THE BLOCK TAKES ONE WORD**, and the sentence draws the support boundary rather than listing a
/// near miss: every other knob a search has is the recipe's, and the answer to wanting one is to
/// write the recipe.
///
/// The entry is `weight`, which is a real `#[ingraph::search]` word, because the boundary this
/// sentence draws is only readable against one: an author who writes a knob the framework has
/// nowhere else would be answered *that word does not exist*, and this position's answer is the
/// stronger *that word exists, one grain up, and here is how to reach it*.
#[test]
fn an_unknown_entry_inside_the_block_draws_the_boundary() {
  let refused = refusals(quote::quote! { searchable(weight = 1.0) });
  assert!(
    refused.contains("unknown entry in `searchable(…)`"),
    "{refused}"
  );
  assert!(
    refused.contains("Every other knob a search has is the RECIPE's"),
    "the sentence does not draw the boundary: {refused}",
  );
}

/// **THE BLOCK'S TWO WORDS ARE NAMED TOGETHER** — `knn(…)` held one live entry until this round, and
/// an unknown one has to offer both or a did-you-mean is reading half a vocabulary.
#[test]
fn the_unknown_entry_sentence_offers_both_of_the_blocks_words() {
  let refused = refusals(quote::quote! { searchably(tower = "media::ClipText") });
  assert!(refused.contains("unknown entry in `knn(…)`"), "{refused}");
  assert!(refused.contains("`searchable(tower = \"…\")`"), "{refused}");
  assert!(refused.contains("`semantics(<kind> = \"…\")`"), "{refused}");
  assert!(
    refused.contains("did you mean `searchable`"),
    "the near miss is not offered: {refused}",
  );
}

/// **THE RETIRED WORD POINTS AT THE SUGAR** — `ask` stays buried, and its sentence now names the one
/// word that is shorter than the recipe it sends an author to write.
#[test]
fn the_retired_road_word_names_the_word_that_replaced_it() {
  let refused = refusals(quote::quote! { ask = "ClipTextTower" });
  assert!(refused.contains("`ask` has retired"), "{refused}");
  assert!(
    refused.contains("knn(searchable(tower = \"path::to::Tower\"))"),
    "the retirement does not name the short road: {refused}",
  );
}