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 LAUNCH WORD**, read: bare `subscribe` reaching its seat on the one kind that has the road,
//! and the four refusals that keep it from meaning anything else.
//!
//! The word is spelled the same as an operator's and a record's, and it does a DIFFERENT job here —
//! which is the whole of what these tests are about. Elsewhere `subscribe = "…"` NAMES an upstream;
//! on a derived index the upstream is `upstream(…)`'s already, because every field of a document is
//! read out of the message it was derived from and the edge and the projection are one entry. So
//! what is left for the word to say is the other half: that this declaration LAUNCHES.
//!
//! What it EXPANDS to is `ingraph-codegen`'s `index/subscriber.rs`, and whether the emitted node
//! actually fills a corpus is `ingraph`'s `tests/subscriber_fulltext_road.rs`.

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

/// The pass under test, at whichever kind a case is about.
fn parse(input: &syn::DeriveInput, kind: NodeKind) -> syn::Result<IndexModel> {
  let (host, arguments) = crate::host::split(input);
  super::parse(&host, &arguments, kind)
}

/// A full-text declaration whose head carries `entry`, so every case differs by exactly that.
fn fulltext(entry: proc_macro2::TokenStream) -> syn::DeriveInput {
  syn::parse_quote! {
    #[ingraph(#entry, upstream(node = "asr::Segment", body = "text"), dedup(hash))]
    pub struct Transcript {
      #[ingraph(searchable, lexical(resource = "crate::Ft"))]
      body: String,
    }
  }
}

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

/// **THE WORD REACHES ITS SEAT**, and the declaration without it is the road that shipped.
///
/// Stated as a PAIR, because a seat that was always `true` would pass an assertion about the word
/// alone — and the `false` arm is the hand road, which this whole feature is additive to.
#[test]
fn the_bare_word_is_the_launch_seat_and_its_absence_is_the_hand_road() {
  let wearing = parse(&fulltext(quote::quote!(subscribe)), NodeKind::Fulltext)
    .expect("a full-text declaration may launch");
  assert!(wearing.subscribe, "the word did not reach the model");

  let bare = parse(
    &syn::parse_quote! {
      #[ingraph(upstream(node = "asr::Segment", body = "text"), dedup(hash))]
      pub struct Transcript {
        #[ingraph(searchable, lexical(resource = "crate::Ft"))]
        body: String,
      }
    },
    NodeKind::Fulltext,
  )
  .expect("a declaration with no word is the road that shipped");
  assert!(
    !bare.subscribe,
    "a declaration that wrote nothing was read as launching",
  );
}

/// **THE VALUE FORM IS REFUSED, AND THE SENTENCE NAMES THE ENTRY THAT ALREADY HAS THE EDGE.**
///
/// This is the refusal an author most likely reaches: `subscribe = "…"` is what an operator and a
/// record write, and transplanting it here is the mistake worth answering at the word rather than at
/// a bound somewhere else. The sentence has to say WHY the value has nowhere to go, which is that
/// `upstream(…)` carries both halves.
#[test]
fn a_valued_word_is_refused_with_the_entry_that_already_names_the_edge() {
  let refused = refusals(
    &fulltext(quote::quote!(subscribe = "asr::Segment")),
    NodeKind::Fulltext,
  );
  assert!(refused.contains("BARE"), "{refused}");
  assert!(refused.contains("upstream(…)"), "{refused}");
  assert!(refused.contains("LAUNCHES"), "{refused}");
}

/// **A BLOCK IS REFUSED, AND THE PER-EDGE WORDS ARE NAMED AS DEFERRED RATHER THAN UNKNOWN.**
///
/// An author who wrote `subscribe(channel = bounded(8))` reached for a grammar that exists one kind
/// over, and is owed the difference rather than *unknown entry*.
#[test]
fn a_block_is_refused_with_the_per_edge_words_it_would_have_carried() {
  let refused = refusals(
    &fulltext(quote::quote!(subscribe(channel = bounded(8)))),
    NodeKind::Fulltext,
  );
  assert!(refused.contains("no block"), "{refused}");
  assert!(refused.contains("channel"), "{refused}");
  assert!(refused.contains("changes(<db>)"), "{refused}");
}

/// **TWICE IS REFUSED**, on the SECOND one — the presence law every bare word here lives under.
#[test]
fn the_word_written_twice_is_refused_as_a_presence() {
  let refused = refusals(
    &fulltext(quote::quote!(subscribe, subscribe)),
    NodeKind::Fulltext,
  );
  assert!(refused.contains("more than once"), "{refused}");
  assert!(refused.contains("PRESENCE"), "{refused}");
}

/// **THE OTHER TWO KINDS ARE REFUSED BY NAME, AS A DEFERRAL** — the road is one write-lane seam per
/// storage family, and the full-text one landed first because it is the family with a live engine.
///
/// A refusal that reported the word as unknown would tell an author to stop asking; this one tells
/// them what is missing and that it is coming.
#[test]
fn the_word_on_a_kind_without_the_road_names_the_deferral() {
  let vector = refusals(
    &syn::parse_quote! {
      #[ingraph(subscribe, upstream(node = "media::Keyframe", clip = "clip"), dedup(hash))]
      pub struct Shots {
        #[ingraph(embedding, knn, lance(resource = "crate::Lance"))]
        clip: Embedding<f32, 4, Clip>,
      }
    },
    NodeKind::Vector,
  );
  assert!(vector.contains("LAUNCHABLE NODE"), "{vector}");
  assert!(vector.contains("deferred"), "{vector}");
  assert!(vector.contains("FulltextLane"), "{vector}");

  let blob = refusals(
    &syn::parse_quote! {
      #[ingraph(subscribe, upstream(node = "media::Shot", frame = "frame"), fs)]
      pub struct Thumbs {
        frame: String,
      }
    },
    NodeKind::Blob,
  );
  assert!(blob.contains("LAUNCHABLE NODE"), "{blob}");
  assert!(blob.contains("deferred"), "{blob}");
}

/// **THE NEAR-MISS ROSTER CARRIES THE WORD ON THE KIND THAT HAS IT, AND NOT ON THE ONE THAT DOES
/// NOT.**
///
/// The unknown-entry sentence is a suggestion table as well as a refusal, so offering `subscribe` to
/// a vector declaration would send an author to write a word their next compile refuses.
#[test]
fn the_unknown_entry_roster_offers_the_word_only_where_it_is_taken() {
  let fulltext = refusals(&fulltext(quote::quote!(subscribed)), NodeKind::Fulltext);
  assert!(fulltext.contains("`subscribe`"), "{fulltext}");

  let vector = refusals(
    &syn::parse_quote! {
      #[ingraph(subscribed, upstream(node = "media::Keyframe", clip = "clip"), dedup(hash))]
      pub struct Shots {
        #[ingraph(embedding, knn, lance(resource = "crate::Lance"))]
        clip: Embedding<f32, 4, Clip>,
      }
    },
    NodeKind::Vector,
  );
  assert!(
    !vector.contains("`subscribe`"),
    "a vector declaration was offered a word its next compile refuses: {vector}",
  );
}