ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! THE COLUMN VOCABULARY — the `<Tier>Column` enum, the one point it translates at, and the row it
//! seats in the full-text package.
//!
//! Beside [`tests`](super::tests) rather than inside it, on `index/elections.rs`'s precedent: one
//! file per thing being proved, so a reader looking for what the M-of-N grain BUYS finds it whole.
//!
//! # What the three grains seat as, and which of them is here
//!
//! Whole-subject is the unsuffixed retrieve pair asking `All`; single-column is the per-field door
//! family; M-of-N is the `columns` row of `<Tier>FulltextOptions`. The first two are the emission's
//! and are proved in `index/elections.rs`. This file is the THIRD, plus the vocabulary all three
//! spell their columns in.
//!
//! Every assertion reads TOKENS. That the enum crosses the wire, that a variant reaches a real
//! engine and that an unelected column will not compile are facts a token stream cannot show, and
//! they are asserted where the emission can be RUN — `ingraph/tests/fulltext_grains.rs`.

use quote::ToTokens as _;

use crate::{
  engine::{Engine, FieldEngines},
  index::{Dedup, Elected, ElectionLabel, IndexGraphql, IndexModel, Upstream},
  model::{GraphqlKind, NodeKind},
  prefix::EmissionPrefix,
};

fn ident(name: &str) -> syn::Ident {
  syn::Ident::new(name, proc_macro2::Span::call_site())
}

/// A declaration of `kind` with nothing elected — the base every fixture below narrows.
fn index(name: &str, kind: NodeKind) -> IndexModel {
  IndexModel {
    prefix: EmissionPrefix::default(),
    numbers: crate::index::Numbers::default(),
    field_numbers: Vec::new(),
    index: ident(name),
    kind,
    vis: syn::parse_quote!(pub),
    krate: syn::parse_quote!(::ingraph),
    source: Upstream {
      node: syn::parse_quote!(Caption),
      projections: Vec::new(),
    },
    dedup: Dedup::Hash,
    embeddings: Vec::new(),
    labelled: Vec::new(),
    searchable: Vec::new(),
    engines: Vec::new(),
    stores: Vec::new(),
    extension: None,
    data: false,
    keys: false,
    subscribe: false,
    graphql: Some(IndexGraphql::of(GraphqlKind::AsyncGraphql)),
    rename: None,
    slot: None,
    fields: Vec::new(),
  }
}

/// A FULL-TEXT declaration electing TWO fields — the vocabulary's subject.
fn fulltext() -> IndexModel {
  let mut model = index("Transcript", NodeKind::Fulltext);
  model.searchable = vec![ident("body"), ident("title")];
  model.engines = vec![
    FieldEngines {
      field: ident("body"),
      engines: vec![Engine::bare(ident("tantivy"))],
      fanout: false,
    },
    FieldEngines {
      field: ident("title"),
      engines: vec![Engine::bare(ident("tantivy"))],
      fanout: false,
    },
  ];
  model
}

/// A VECTOR declaration electing one field — the modality mirror.
fn one_slot() -> IndexModel {
  let mut model = index("Captions", NodeKind::Vector);
  model.embeddings = vec![Elected::new(
    ident("image_embedding"),
    ElectionLabel::Embedding,
    syn::parse_quote!(::ingraph::Embedding<f32, 4, Clip>),
    None,
  )];
  model.engines = vec![FieldEngines {
    field: ident("image_embedding"),
    engines: vec![Engine::bare(ident("hnsw"))],
    fanout: false,
  }];
  model
}

/// A BLOB family — the kind that does not retrieve.
fn blob() -> IndexModel {
  let mut model = index("Posters", NodeKind::Blob);
  model.stores = vec![Engine::bare(ident("fs"))];
  model
}

/// The emitted tier, parsed.
fn emission(model: &IndexModel) -> syn::File {
  syn::parse2(model.tier().emit()).expect("the tier emission is a parsable file")
}

/// The enum this tier mints under `name`, if it mints one.
fn vocabulary(model: &IndexModel, name: &str) -> Option<syn::ItemEnum> {
  emission(model)
    .items
    .into_iter()
    .find_map(|item| match item {
      syn::Item::Enum(declared) if declared.ident == name => Some(declared),
      _ => None,
    })
}

/// Every enum this tier mints, by name — the reader the ABSENCE claims are asked through.
fn enums(model: &IndexModel) -> Vec<String> {
  emission(model)
    .items
    .into_iter()
    .filter_map(|item| match item {
      syn::Item::Enum(declared) => Some(declared.ident.to_string()),
      _ => None,
    })
    .collect()
}

/// One package's rows, in emission order — `member: ty`, as a reader of the struct sees them.
fn rows(model: &IndexModel, name: &str) -> Vec<String> {
  emission(model)
    .items
    .into_iter()
    .find_map(|item| match item {
      syn::Item::Struct(declared) if declared.ident == name => Some(declared),
      _ => None,
    })
    .expect("the package is emitted")
    .fields
    .iter()
    .map(|field| {
      format!(
        "{}: {}",
        field.ident.as_ref().expect("a named field"),
        field.ty.to_token_stream().to_string().replace(' ', ""),
      )
    })
    .collect()
}

/// THE VARIANTS ARE THE ELECTED FIELDS, in declared order and upper-camelled.
///
/// The order is load-bearing for the same reason it is in the subject: a vocabulary built from
/// `fields` or from `source.projections` would carry a payload column, and one built from a sorted
/// list would disagree with the wire's own ordering the day a field is added in the middle.
#[test]
fn the_vocabulary_is_the_elected_fields_in_declared_order() {
  let minted = vocabulary(&fulltext(), "TranscriptColumn").expect("the vocabulary is emitted");

  assert_eq!(
    minted
      .variants
      .iter()
      .map(|variant| variant.ident.to_string())
      .collect::<Vec<_>>(),
    ["Body", "Title"],
    "one variant per election, in the order the declaration wrote them",
  );
}

/// ONE TRANSLATION POINT, and every variant goes through it to its OWN column.
///
/// The mutation this pins is the cheap one: a `column` written from the first election for every arm
/// — which compiles, is exhaustive, and answers `body` for `Title`. Each arm is therefore read for
/// its own field name, and for the ABSENCE of the other's.
#[test]
fn every_variant_translates_to_its_own_column_at_one_point() {
  let file = emission(&fulltext());
  let translations: Vec<syn::ImplItemFn> = file
    .items
    .iter()
    .filter_map(|item| match item {
      syn::Item::Impl(declared) if declared.trait_.is_none() => Some(declared),
      _ => None,
    })
    .flat_map(|declared| declared.items.iter())
    .filter_map(|inner| match inner {
      syn::ImplItem::Fn(method) if method.sig.ident == "column" => Some(method.clone()),
      _ => None,
    })
    .collect();

  assert_eq!(
    translations.len(),
    1,
    "the vocabulary translates at exactly ONE function; two would be two places to learn a \
     different answer",
  );
  // Each arm is read on its OWN, split off at the next `Self::`, and the framework PATH is not
  // spelled: `framework` resolves through the shelf, so pinning the path here would make this a test
  // of where `ingraph` re-exports its store rather than of which column a variant names.
  let body = translations[0]
    .block
    .to_token_stream()
    .to_string()
    .replace(' ', "");
  for (variant, column, other) in [("Body", "body", "title"), ("Title", "title", "body")] {
    let arm = body
      .split(&format!("Self::{variant}=>"))
      .nth(1)
      .map(|rest| rest.split("Self::").next().unwrap_or(rest).to_owned())
      .unwrap_or_else(|| panic!("`{variant}` has an arm: {body}"));

    assert!(
      arm.contains(&format!("FulltextColumn::new(\"{column}\")")),
      "`{variant}` names `{column}`: {arm}",
    );
    assert!(
      !arm.contains(&format!("\"{other}\"")),
      "and never the other election's: {arm}",
    );
  }
}

/// The translation is `const` and takes `self` BY VALUE — the shape an emitted door can spend.
///
/// A caller of this vocabulary is as often an expansion as a person, and an expansion writing a
/// `const` column list needs both halves: `const fn` so the call is legal in that position, and a
/// `Copy` receiver so a variant read out of a package is not moved out of it.
#[test]
fn the_translation_is_const_and_takes_the_variant_by_value() {
  let file = emission(&fulltext());
  let method = file
    .items
    .iter()
    .filter_map(|item| match item {
      syn::Item::Impl(declared) if declared.trait_.is_none() => Some(declared),
      _ => None,
    })
    .flat_map(|declared| declared.items.iter())
    .find_map(|inner| match inner {
      syn::ImplItem::Fn(method) if method.sig.ident == "column" => Some(method.clone()),
      _ => None,
    })
    .expect("the translation is emitted");

  assert!(method.sig.constness.is_some(), "`column` is `const`");
  let receiver = method
    .sig
    .inputs
    .first()
    .expect("`column` takes a receiver")
    .to_token_stream()
    .to_string();
  assert_eq!(
    receiver, "self",
    "`column` takes `self` by value, not by reference: {receiver}",
  );
}

/// The wire words are SCREAMING_SNAKE, which is this grammar's own casing in the GraphQL namespace.
#[test]
fn the_wire_words_are_screaming_snake() {
  let mut model = fulltext();
  model.searchable = vec![ident("spoken_labels"), ident("title")];
  let said = model.tier().emit().to_string();

  assert!(
    said.contains("\"SPOKEN_LABELS\""),
    "a multi-word field screams with its underscores kept: {said}",
  );
  assert!(said.contains("\"TITLE\""), "{said}");
  assert!(
    !said.contains("\"spokenLabels\""),
    "and the input-object casing does not leak onto an enum: {said}",
  );
}

/// TWO FIELDS UNDER ONE VARIANT is refused BY NAME, naming both fields and the variant they collide
/// on.
///
/// `spoken_labels` and `spokenLabels` are two legal fields of one struct that upper-camel to one
/// word. Without this the emission writes `enum … { SpokenLabels, SpokenLabels }` and rustc reports
/// `E0428` about a type nobody wrote, at a span nobody can edit.
#[test]
fn two_fields_spelling_one_variant_are_refused_by_name() {
  let mut model = fulltext();
  model.searchable = vec![ident("spoken_labels"), ident("spokenLabels")];
  let said = model.tier().emit().to_string();

  assert!(said.contains("compile_error"), "it is refused: {said}");
  assert!(said.contains("spoken_labels"), "naming the first: {said}");
  assert!(said.contains("spokenLabels"), "and the second: {said}");
  assert!(
    said.contains("SpokenLabels"),
    "and the variant they collide on: {said}",
  );
}

/// THE `columns` ROW SITS IN THE PACKAGE, typed on this tier's own vocabulary.
///
/// It read *beside `ceiling` rather than instead of it* while the package carried both; the wall law
/// retired that row — a protective number never crosses the wire — and `columns` is what the package
/// carries now. The claim is unmoved and is a claim about THIS row: its presence, its type, and the
/// de-Option law over it.
#[test]
fn the_package_carries_a_columns_row_over_this_tier_s_own_vocabulary() {
  assert_eq!(
    rows(&fulltext(), "TranscriptFulltextOptions"),
    ["columns: ::core::option::Option<::std::vec::Vec<TranscriptColumn>>"],
    "the de-Option law holds over the new row too: absent means the declaration's own subject",
  );
}

/// A VECTOR tier mints no column vocabulary and no `columns` row — the modality presence law, over
/// the new type.
///
/// A vector declaration elects columns too, and they already have a selector of their own
/// (`VectorColumn`, one per door). A second vocabulary over them would be a type meaning nothing
/// that a full-text package could not use anyway.
#[test]
fn a_vector_tier_mints_no_column_vocabulary() {
  assert!(
    !enums(&one_slot())
      .iter()
      .any(|minted| minted.ends_with("Column")),
    "a vector tier's enums are its fold vocabularies alone: {:?}",
    enums(&one_slot()),
  );
  assert!(
    !rows(&one_slot(), "CaptionsImageEmbeddingVectorOptions")
      .iter()
      .any(|row| row.starts_with("columns:")),
    "and no vector package grows a column subset",
  );
}

/// A BLOB family mints nothing at all, this type included.
#[test]
fn a_blob_family_mints_no_column_vocabulary() {
  assert!(
    blob().tier().emit().is_empty(),
    "the kind that does not retrieve emits no package and no vocabulary",
  );
}

/// A declaration electing NOTHING mints neither the enum nor a row typed on it.
///
/// The two are one decision and this is what pins them together: a `columns` row emitted without the
/// enum names a type the expansion did not write, which is `E0412` inside the package rather than a
/// refusal anybody can read. The derive refuses an electionless full-text declaration long before
/// here, so this is the emitter holding its own half rather than a case a user reaches.
#[test]
fn no_election_mints_no_vocabulary_and_no_row() {
  let mut model = fulltext();
  model.searchable = Vec::new();

  assert!(
    !enums(&model)
      .iter()
      .any(|minted| minted == "TranscriptColumn"),
    "no elected field, no vocabulary: {:?}",
    enums(&model),
  );
  // EMPTY, and it is the two retirements meeting: no election means no `columns` row, and the wall
  // law means no `ceiling` row for it to stand beside. A package with nothing to say is what a
  // declaration electing nothing and naming no engine has.
  assert_eq!(
    rows(&model, "TranscriptFulltextOptions"),
    [] as [&str; 0],
    "and the package carries no row at all",
  );
}