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 MINTS-NONE AUDIT** — seats may sit EMPTY, and a written word must point at something
//! MINTED.
//!
//! ```text
//! #[ingraph(embedding, knn, lance(resource = "…"), hnsw(resource = "…"), fanout,
//!           graphql(async_graphql(keys(rename = "clipNeighbours"))))]
//!                                 └── a FANNED election mounts its fused field and no keys field
//! ```
//!
//! # The distinction the law rests on
//!
//! An UNWRITTEN seat is a capability awaiting a user, and the whole grammar is unwritten on most
//! declarations — so silence is not a defect. A WRITTEN word that reaches no emitted name is a
//! swallowed authoring error: its author believes they renamed a query field, and the schema
//! publishes the derived name or publishes nothing at all. That is a class this house already
//! refuses — `lineage(rename)` on a lineage-less record, `fuse_options` on a one-route tier — and
//! these seats join it.
//!
//! # THE SCOPE, and it is a declaration that PUBLISHES FIELDS
//!
//! Every case audited here is one where the election's own shape picks among roads that DO exist.
//! Three shapes publish no field surface at all, and each is left alone with its measurement:
//!
//! - a declaration whose HEAD names no backend mounts nothing, so every seat on every one of its
//!   elections is unspent at once. That is one fact about the declaration rather than one per seat,
//!   and a refusal at the head would answer it better than N refusals at N words.
//! - a FULL-TEXT election mounts no query field yet, its answer face not having arrived.
//! - an election naming its engines BY WORD alone is the PORTABLE case — legal, and publishing
//!   nothing is what the presence law says it means.
//!
//! Each seat's own predicate is `ingraph-codegen`'s `IndexModel::unmounted` and `unminted_engines`,
//! which sit beside the emitter whose conditions they mirror.
//!
//! Beside [`rename_seats`](super::rename_seats) rather than inside it: that file is about which
//! WORDS reach which seats, and this one is about which words a SHAPE may write at all.

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

/// A VECTOR declaration DRESSED AT THE HEAD, whose one election wears `markers` and whose backend
/// block on that election says `skin`.
///
/// The head's `graphql(async_graphql)` is what makes the fixture auditable at all: a declaration
/// that names no backend publishes no field, so every seat on it is unspent for one reason and the
/// audit deliberately stands aside. `head` carries whatever else the case needs — the `keys` word,
/// mostly.
fn declared(
  head: proc_macro2::TokenStream,
  markers: proc_macro2::TokenStream,
  skin: proc_macro2::TokenStream,
) -> syn::Result<IndexModel> {
  let (host, arguments) = crate::host::split(&syn::parse_quote! {
    #[ingraph(
      upstream(node = "a::A", clip = "clip"),
      dedup(hash),
      graphql(async_graphql),
      #head
    )]
    struct D {
      #[ingraph(#markers, graphql(async_graphql(#skin)))]
      clip: ::ingraph::Embedding<f32, 4, Clip>,
    }
  });
  super::super::index::parse(&host, &arguments, NodeKind::Vector)
}

/// The election a PLAIN road is mounted from: one typed store.
fn plain() -> proc_macro2::TokenStream {
  quote::quote! { embedding, knn, lance(resource = "crate::Lance") }
}

/// The election a FANNED road is mounted from: two typed stores, fanned.
fn fanned() -> proc_macro2::TokenStream {
  quote::quote! {
    embedding, knn, lance(resource = "crate::Lance"), hnsw(resource = "crate::Hnsw"), fanout
  }
}

/// Every refusal a declaration earns, joined.
fn refusals(
  head: proc_macro2::TokenStream,
  markers: proc_macro2::TokenStream,
  skin: proc_macro2::TokenStream,
) -> String {
  declared(head, markers, skin)
    .expect_err("the declaration is refused")
    .into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>()
    .join("\n")
}

/// **A FANNED ELECTION MOUNTS ITS FUSED FIELD AND NOTHING ELSE**, so each of the four per-store road
/// words names a field it does not publish.
///
/// All four, because the law is about the SHAPE rather than about one word: an author who wrote
/// `keys` on a fanned election will write `similar` next.
#[test]
fn the_four_per_store_roads_are_refused_on_a_fanned_election() {
  for road in ["keys", "hydrated", "similar", "similar_hydrated"] {
    let written = format!("{road}(rename = \"aWord\")");
    let skin: proc_macro2::TokenStream = written.parse().expect("a block entry");
    let refused = refusals(quote::quote! {}, fanned(), skin);
    assert!(
      refused.contains("this election publishes none"),
      "`{written}` was not audited: {refused}",
    );
    assert!(
      refused.contains("a FANNED election publishes its fused field and nothing else"),
      "and the sentence names the shape: {refused}",
    );
    assert!(
      refused.contains("`fused(rename = \"…\")`"),
      "and the word this shape DOES have: {refused}",
    );
  }
}

/// **THE FUSED WORD ITSELF IS LEGAL THERE**, which is the exclusion that makes the test above about
/// the shape rather than about the block being refused wholesale.
#[test]
fn the_fused_word_is_what_a_fanned_election_publishes() {
  declared(
    quote::quote! {},
    fanned(),
    quote::quote! { fused(rename = "clipLeaderboard") },
  )
  .expect("a fanned election publishes exactly this road");
}

/// **THE HEAD'S `keys` WORD WITHHOLDS THE TWO HYDRATED ROADS**, so their seats name fields that are
/// not emitted — the contract's own example, in a compile.
///
/// The sentence names BOTH repairs, because either is the author's to choose: the upstream may have
/// rows after all, or the word may be the one to drop.
#[test]
fn the_two_hydrated_roads_are_refused_where_the_upstream_is_an_entity() {
  for road in ["hydrated", "similar_hydrated"] {
    let written = format!("{road}(rename = \"aWord\")");
    let skin: proc_macro2::TokenStream = written.parse().expect("a block entry");
    let refused = refusals(quote::quote! { keys, }, plain(), skin);
    assert!(
      refused.contains("wears the head's `keys` word"),
      "`{written}` was not audited: {refused}",
    );
    assert!(
      refused.contains("Drop `keys` where the upstream does have rows, or drop this word"),
      "and both repairs are named: {refused}",
    );
  }
}

/// **THE KEYS-TIER ROADS STAY LEGAL UNDER THAT SAME WORD** — the exclusion beside the test above.
///
/// A `keys` declaration mounts the two ADDRESS roads and withholds their hydrated twins, so an audit
/// that refused all four would be refusing the shape rather than the mismatch.
#[test]
fn the_address_roads_are_what_a_keys_tier_declaration_still_publishes() {
  declared(
    quote::quote! { keys, },
    plain(),
    quote::quote! { keys(rename = "clipKeys"), similar(rename = "clipNeighbourKeys") },
  )
  .expect("the keys tier publishes both address roads");
}

/// **`engines` NAMES A PRODUCT ONLY A FANNED ELECTION MINTS.**
///
/// The per-leg product is what a fused read states one floor per leg in, so a one-store election has
/// one leg and no product — and the sentence sends its author to the seat that DOES name their
/// engine.
#[test]
fn the_per_leg_product_is_refused_on_a_one_store_election() {
  let refused = refusals(
    quote::quote! {},
    plain(),
    quote::quote! { engines(rename = "ClipLegs") },
  );
  assert!(refused.contains("this election mints none"), "{refused}");
  assert!(
    refused.contains("answered by ONE typed store"),
    "the sentence names the shape: {refused}",
  );
  assert!(
    refused.contains("`engine(rename = \"…\")`"),
    "and the seat that names its engine instead: {refused}",
  );
}

/// **AND IT IS LEGAL WHERE THE PRODUCT EXISTS** — the exclusion, at the shape that mints one.
#[test]
fn the_per_leg_product_is_nameable_on_a_fanned_election() {
  declared(
    quote::quote! {},
    fanned(),
    quote::quote! { engines(rename = "ClipLegs") },
  )
  .expect("a fanned election mints the per-leg product");
}

/// **`question` IS AUDITED AND FOUND ALWAYS-SPENT**, which is a different answer from unaudited.
///
/// `question_input` runs for every election that mounts a road, on every road, so the question type
/// is minted wherever the seat is reachable. Asserted at BOTH shapes, since *always* is a claim
/// about the set rather than about one member of it.
#[test]
fn the_question_seat_is_spent_at_every_shape_that_can_write_it() {
  for markers in [plain(), fanned()] {
    declared(
      quote::quote! {},
      markers,
      quote::quote! { question(rename = "ClipAsk") },
    )
    .expect("every mounted election mints its question type");
  }
}

/// **AN UNWRITTEN SEAT IS NEVER A REFUSAL** — the law's first half, which is what keeps the audit
/// from being a strictness.
///
/// The shape below mounts one road of five and writes nothing, and it compiles: four seats sit empty
/// and cost their author nothing.
#[test]
fn a_shape_that_writes_no_seat_is_audited_into_silence() {
  declared(
    quote::quote! { keys, },
    plain(),
    quote::quote! { first = 7 },
  )
  .expect("empty seats are capabilities awaiting a user");
}

/// **THE SCOPE LINE, STATED FROM ITS OTHER SIDE**: a declaration whose HEAD names no backend
/// publishes nothing, and the audit stands aside rather than refusing every seat at once.
///
/// Written as a test because it is a decision rather than an accident — see this module's note for
/// the three shapes it covers and why a head-level refusal would answer them better.
#[test]
fn a_declaration_that_publishes_no_field_is_left_to_a_refusal_of_its_own() {
  let (host, arguments) = crate::host::split(&syn::parse_quote! {
    #[ingraph(upstream(node = "a::A", clip = "clip"), dedup(hash))]
    struct D {
      #[ingraph(
        embedding,
        knn,
        lance(resource = "crate::Lance"),
        hnsw(resource = "crate::Hnsw"),
        fanout,
        graphql(async_graphql(keys(rename = "clipNeighbours")))
      )]
      clip: ::ingraph::Embedding<f32, 4, Clip>,
    }
  });
  super::super::index::parse(&host, &arguments, NodeKind::Vector)
    .expect("an undressed head mounts nothing, and this round does not refuse there");
}