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 RETIRED QUESTION ROAD: what an author who writes `ask` — or the word it was almost called —
//! is told, and the shape of `knn(…)` now that neither is in it.
//!
//! `ask = "Tower"` / `ask = ["A", "B"]` named a chain of hops that turned a question into this
//! column's coordinates. It retired on 2026-08-19 with the erasure road it was the last caller of,
//! and this file is what is left of its acceptance suite: the two forms it took, the four spellings
//! it refused, and the road's own emission are all gone, so what remains to assert is that the word
//! is REFUSED and that the refusal is USEFUL.
//!
//! # Why a by-name refusal and not an unknown entry
//!
//! An author writing `ask` has a coherent idea — *a road from what a person typed to what this
//! column can be asked with* — and that idea still exists. It is a `#[ingraph::tower]`'s. The
//! unknown-entry sentence would answer *this position does not take that word*, which is true and
//! useless; the retirement sentence answers *the road moved, and here it is*.
//!
//! # What the move bought, which is the half a sentence has to earn
//!
//! A chain of N hops has N error types and one `Result` has one, so `ask` ERASED every hop's
//! refusal into a boxed `AskRefusal` carrying the hop's name as a string: a road could say WHICH hop
//! said no and never in what TYPE. A tower mints `<Tower>Error` — one arm per step, each carrying
//! that step's own error — so the same refusal is matchable. The refusal says so, and the assertion
//! below reads it, because a retirement sentence that only says *gone* leaves an author with the
//! belief that they lost something.
//!
//! # A word came back into the block, and it is NOT this one
//!
//! `knn(searchable(tower = "…"))` is a SECOND live entry as of the same day. It is not a revival:
//! what it names is a TOWER, singular and typed, and its whole expansion is the `#[ingraph::search]`
//! recipe that binds one — so every hop's error type survives, which is the exact property `ask`
//! could not have. The retirement sentence names it, because the shorter road is the one an author
//! who reached for `ask` wanted. What it is read by is `index/searchable_road.rs`.

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)
}

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

/// One `knn(…)` block over one election, so every case below differs by exactly its entry.
fn block(entry: proc_macro2::TokenStream) -> String {
  refusals(syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", vec = "vec"), dedup(hash))]
    pub struct Voiceprints {
      #[ingraph(embedding, knn(#entry))]
      vec: Embedding<f32, 512>,
    }
  })
}

/// **THE RETIRED WORD IS REFUSED BY NAME, IN BOTH ITS ARITIES** — the single hop and the chain, since
/// an author standing in this migration wrote one or the other and neither is a spelling any more.
///
/// Three claims per form, and they are the three things the sentence owes: that the word is gone,
/// WHERE the road went, and WHY — because a reader who is told only the first will conclude the
/// framework dropped a capability.
#[test]
fn the_retired_road_word_is_refused_by_name_at_either_arity() {
  for entry in [
    quote::quote! { ask = "ClipTextTower" },
    quote::quote! { ask = ["media::AudioDecode", "media::ClipAudioTower"] },
  ] {
    let refused = block(entry.clone());
    assert!(
      refused.contains("`ask` has retired"),
      "`{entry}` was not refused as a retirement: {refused}",
    );
    assert!(
      refused.contains("`#[ingraph::tower]`"),
      "the successor is not named: {refused}",
    );
    assert!(
      refused.contains("<Tower>Error"),
      "the sentence does not say what the move bought: {refused}",
    );
    assert!(
      refused.contains("The RAW road is untouched"),
      "the sentence does not say what did NOT change: {refused}",
    );
  }
}

/// **THE CONTAINER FORM RETIRES WITH THE WORD, AND WITH ONE SENTENCE** — `ask("A", "B")` was already
/// superseded by `ask = ["A", "B"]`, so an author who wrote it is two migrations behind and is owed
/// the destination rather than the intermediate stop.
#[test]
fn the_superseded_container_form_reaches_the_same_sentence() {
  let refused = block(quote::quote! { ask("A", "B") });
  assert!(refused.contains("`ask` has retired"), "{refused}");
  assert!(refused.contains("`#[ingraph::tower]`"), "{refused}");
}

/// **THE WORD IT WAS ALMOST CALLED KEEPS ITS OWN OPENER**, because telling an author that `via` has
/// retired would be false about the grammar they are standing in: it never was a word.
///
/// One BODY and two openers — the destination is the same, so a second sentence would be a second
/// place for the successor to go stale.
#[test]
fn the_near_miss_word_is_told_the_truth_about_itself() {
  let refused = block(quote::quote! { via = "ClipTextTower" });
  assert!(
    refused.contains("`via` is not the word, and `ask` is no longer one either"),
    "{refused}",
  );
  assert!(
    !refused.contains("`ask` has retired"),
    "the wrong opener reached the near-miss word: {refused}",
  );
  assert!(refused.contains("`#[ingraph::tower]`"), "{refused}");
}

/// **THE BLOCK'S LIVE WORDS ARE THE ONES THE SENTENCE OFFERS**, and the retired spelling is in
/// neither the sentence nor the did-you-mean.
///
/// The near-miss vocabulary and the teaching sentence are two lists over ONE set, which is the
/// property that makes a did-you-mean readable. `ask` is in neither, which is the assertion that
/// would fail if the retirement had been done by deleting the reader and leaving the sentence.
#[test]
fn an_unknown_word_inside_the_block_names_the_entries_that_are_left() {
  let refused = block(quote::quote! { asks = "ClipTextTower" });
  assert!(refused.contains("unknown entry in `knn(…)`"), "{refused}");
  assert!(refused.contains("`semantics(<kind> = \"…\")`"), "{refused}");
  assert!(refused.contains("`searchable(tower = \"…\")`"), "{refused}");
  assert!(refused.contains("the field this marker is on"), "{refused}");
  assert!(
    !refused.contains("`ask = \"Tower\"`"),
    "the sentence still offers the retired word: {refused}",
  );
}

/// **THE LIVE WORD STILL PARSES**, which is what keeps the retirement from having been a deletion of
/// the block: `semantics(…)` is read exactly as it was, on the election it qualifies.
#[test]
fn the_blocks_one_live_word_is_untouched() {
  let model = parse(&syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", vec = "vec"), dedup(hash))]
    pub struct Voiceprints {
      #[ingraph(list(embedding), knn(semantics(fold(max))))]
      vec: Vec<Embedding<f32, 512>>,
    }
  })
  .expect("a set election declaring its fold is legal");
  assert!(
    model.embeddings[0].fold.is_some(),
    "the fold word did not reach its seat",
  );
}