ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! WHAT THE ENGINE BLOCKS SPEND — the slots a declaration mints, and the door a `fanout` field gets.
//!
//! Beside [`elections`](super::elections) rather than inside it, on that file's own precedent: one
//! file per thing being proved.
//!
//! # The two emissions, and why one of them is deliberately absent
//!
//! A slot becomes a MARKER TYPE at module scope, because a deployment names one when it opens a
//! handle. Every declared slot gets one, whether or not the field is fanned.
//!
//! The DEFAULT single-write case gets no door at all, and that is the mirror rather than a gap: the
//! record side needs `insert_postgres` beside `insert_sqlite` because the row type is what picks the
//! database and a caller cannot name it, and here the handle's own brand has already picked the
//! slot. The fan is the case no existing door covers, so the fan is what is emitted — which makes
//! the marker's meaning readable in the expansion.
//!
//! Every assertion is written as an EXCLUSION as well: a portable field must get NO door, because an
//! emission that fanned by default would pass an inclusion-only suite while writing every store on
//! every call.

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

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

fn column(name: &str, ty: &str) -> Column {
  Column {
    name: ident(name),
    source: ident(name),
    ty: syn::parse_str(ty).expect("a type"),
    project: Projection::Borrowed,
  }
}

fn projected(field: &str, ty: &str) -> Projected {
  Projected {
    field: ident(field),
    from: ident(field),
    ty: syn::parse_str(ty).expect("a type"),
  }
}

fn stored(field: &str, engines: &[&str], fanout: bool) -> FieldEngines {
  FieldEngines {
    field: ident(field),
    engines: engines
      .iter()
      .map(|word| Engine::bare(ident(word)))
      .collect(),
    fanout,
  }
}

/// A full-text declaration over two searched fields, each storing where the caller says.
fn document(engines: Vec<FieldEngines>) -> IndexModel {
  IndexModel {
    prefix: EmissionPrefix::default(),
    numbers: crate::index::Numbers::default(),
    field_numbers: Vec::new(),
    stores: Vec::new(),
    extension: None,
    data: false,
    keys: false,
    subscribe: false,
    graphql: Some(IndexGraphql::of(GraphqlKind::AsyncGraphql)),
    rename: None,
    slot: None,
    index: ident("SearchDocument"),
    kind: NodeKind::Fulltext,
    vis: syn::Visibility::Public(syn::token::Pub::default()),
    krate: syn::parse_quote!(::ingraph),
    source: Upstream {
      node: syn::parse_quote!(asr::Segment),
      projections: vec![projected("title", "String"), projected("body", "String")],
    },
    dedup: Dedup::Hash,
    embeddings: Vec::new(),
    labelled: Vec::new(),
    searchable: vec![ident("title"), ident("body")],
    engines,
    fields: vec![column("title", "String"), column("body", "String")],
  }
}

/// A VECTOR declaration over one elected embedding, storing where the caller says.
///
/// A model of its own rather than [`document`] with its kind swapped: the vector emission reads the
/// elected field's DECLARED TYPE off the columns, so a model whose election names no column of its
/// own is not a vector model at all.
fn frames(engines: Vec<FieldEngines>) -> IndexModel {
  let ty: syn::Type = syn::parse_str("Embedding<f32, 4>").expect("a type");
  IndexModel {
    prefix: EmissionPrefix::default(),
    numbers: crate::index::Numbers::default(),
    field_numbers: Vec::new(),
    stores: Vec::new(),
    extension: None,
    data: false,
    keys: false,
    subscribe: false,
    graphql: Some(IndexGraphql::of(GraphqlKind::AsyncGraphql)),
    rename: None,
    slot: None,
    index: ident("Keyframes"),
    kind: NodeKind::Vector,
    vis: syn::Visibility::Public(syn::token::Pub::default()),
    krate: syn::parse_quote!(::ingraph),
    source: Upstream {
      node: syn::parse_quote!(asr::Segment),
      projections: vec![projected("image", "Embedding<f32, 4>")],
    },
    dedup: Dedup::Hash,
    embeddings: vec![Elected::new(
      ident("image"),
      ElectionLabel::Embedding,
      ty.clone(),
      None,
    )],
    labelled: Vec::new(),
    searchable: Vec::new(),
    engines,
    fields: vec![column("image", "Embedding<f32, 4>")],
  }
}

/// The emitted file, parsed — with the FUSION TREE subtracted, for [`super::tests`]'s reason: the
/// packages [`crate::fuse`] mints are module-scope structs carrying module-scope inherent methods,
/// so leaving them in would make every count below an assertion about a family this file does not
/// own — a package's own `new()` would read as a door. Subtracted by TOKEN IDENTITY against the
/// tier's own emission, so nothing here holds a list of names that could drift.
fn emission(model: &IndexModel) -> syn::File {
  use quote::ToTokens as _;

  let file: syn::File = syn::parse2(model.emit()).expect("the emission is a parsable file");
  let tier: syn::File =
    syn::parse2(model.tier().emit()).expect("the fusion tree is a parsable file");
  // THE WIRE CITIZENSHIP is subtracted beside the fusion tree and for its reason: the query unit is
  // a third family at module scope, with its own suite, and a marker count that included it would be
  // an assertion about a file this one does not own.
  let citizen: syn::File =
    syn::parse2(model.citizen()).expect("the wire citizenship is a parsable file");
  let fusion: std::collections::HashSet<String> = tier
    .items
    .iter()
    .chain(citizen.items.iter())
    .map(|item| item.to_token_stream().to_string())
    .collect();
  syn::File {
    items: file
      .items
      .into_iter()
      .filter(|item| !fusion.contains(&item.to_token_stream().to_string()))
      .collect(),
    ..file
  }
}

/// Every STRUCT the expansion declares at module scope, by name.
fn structs(model: &IndexModel) -> Vec<String> {
  emission(model)
    .items
    .into_iter()
    .filter_map(|item| match item {
      syn::Item::Struct(declared) => Some(declared.ident.to_string()),
      _ => None,
    })
    .collect()
}

/// Every INHERENT method the expansion declares at MODULE SCOPE — which is where the fan lives, the
/// retrieve pair being inside the anonymous const.
fn doors(model: &IndexModel) -> Vec<String> {
  emission(model)
    .items
    .into_iter()
    .filter_map(|item| match item {
      syn::Item::Impl(declared) if declared.trait_.is_none() => Some(declared),
      _ => None,
    })
    .flat_map(|declared| {
      declared.items.into_iter().filter_map(|inner| match inner {
        syn::ImplItem::Fn(method) => Some(method.sig.ident.to_string()),
        _ => None,
      })
    })
    .collect()
}

/// The whole expansion as one string, for the assertions about a token rather than a shape.
fn tokens(model: &IndexModel) -> String {
  model.emit().to_string()
}

/// ONE MARKER PER (field × engine) — the slot set, made into types.
#[test]
fn every_declared_slot_becomes_a_marker_type() {
  let model = document(vec![
    stored("title", &["tantivy", "hnsw"], false),
    stored("body", &["tantivy"], false),
  ]);
  let declared = structs(&model);
  assert!(
    declared.contains(&"SearchDocumentTitleTantivy".to_owned()),
    "{declared:?}"
  );
  assert!(
    declared.contains(&"SearchDocumentTitleHnsw".to_owned()),
    "{declared:?}"
  );
  assert!(
    declared.contains(&"SearchDocumentBodyTantivy".to_owned()),
    "{declared:?}"
  );
  assert_eq!(declared.len(), 3, "and nothing else: {declared:?}");
}

/// Two fields sharing an engine are TWO markers, which is the whole content of the field half of the
/// pair being in the identity.
#[test]
fn two_fields_sharing_an_engine_get_two_markers() {
  let model = document(vec![
    stored("title", &["tantivy"], false),
    stored("body", &["tantivy"], false),
  ]);
  assert_eq!(
    structs(&model),
    ["SearchDocumentTitleTantivy", "SearchDocumentBodyTantivy"]
  );
}

/// A declaration that named no engine mints no marker — the portable case, where the deployment
/// says.
#[test]
fn a_declaration_that_named_no_engine_mints_no_marker() {
  let model = document(vec![
    stored("title", &[], false),
    stored("body", &[], false),
  ]);
  assert!(structs(&model).is_empty());
}

/// The slot's NAME reaches the expansion, and it is the three-part one.
#[test]
fn a_slot_marker_carries_its_durable_name() {
  let emitted = tokens(&document(vec![stored("title", &["tantivy"], false)]));
  assert!(
    emitted.contains("\"search_document__title__tantivy\""),
    "the minted name is in the expansion: {emitted}"
  );
}

/// The FIELD and the ENGINE are both readable off the marker, which is what lets the join be checked
/// rather than trusted.
#[test]
fn a_slot_marker_names_its_field_and_its_engine() {
  let emitted = tokens(&document(vec![stored("title", &["hnsw"], false)]));
  assert!(emitted.contains("const FIELD"), "{emitted}");
  assert!(emitted.contains("const ENGINE"), "{emitted}");
  assert!(emitted.contains("\"title\""), "{emitted}");
  assert!(emitted.contains("\"hnsw\""), "{emitted}");
}

/// SINGLE-WRITE emits NO door. The exclusion is the assertion: a fan by default would be the
/// marker's meaning given away for free, and every inclusion test above would still pass.
#[test]
fn a_portable_field_gets_no_fan_door() {
  let model = document(vec![stored("title", &["tantivy", "hnsw"], false)]);
  assert!(
    doors(&model).is_empty(),
    "portability is written through the one slot a deployment opened: {:?}",
    doors(&model)
  );
}

#[test]
fn a_fanned_field_gets_one_door_named_after_it() {
  let model = document(vec![
    stored("title", &["tantivy", "hnsw"], true),
    stored("body", &["tantivy", "hnsw"], false),
  ]);
  assert_eq!(doors(&model), ["fan_title"]);
}

/// ONE ENGINE PARAMETER PER LEG. A door that named one parameter twice would refuse the very case
/// the marker exists for — two engines are two types.
#[test]
fn a_fan_door_takes_one_engine_parameter_per_leg() {
  let model = document(vec![stored("title", &["tantivy", "hnsw"], true)]);
  let emitted = tokens(&model);
  assert!(emitted.contains("__INGRAPH_ENGINE_0__"), "{emitted}");
  assert!(emitted.contains("__INGRAPH_ENGINE_1__"), "{emitted}");
  assert!(
    !emitted.contains("__INGRAPH_ENGINE_2__"),
    "and no more than there are legs: {emitted}"
  );
}

/// The legs are branded by THEIR OWN slot, so a handle opened on one cannot be passed to the other.
#[test]
fn each_leg_is_branded_with_its_own_slot() {
  let emitted = tokens(&document(vec![stored("title", &["tantivy", "hnsw"], true)]));
  assert!(emitted.contains("SearchDocumentTitleTantivy"), "{emitted}");
  assert!(emitted.contains("SearchDocumentTitleHnsw"), "{emitted}");
}

/// The full-text kind writes DOCUMENTS and the vector kind writes COORDINATES, and the door names
/// the verb of the seam it crosses.
#[test]
fn the_fan_names_its_kind_s_write_verb() {
  let full_text = tokens(&document(vec![stored("title", &["tantivy", "hnsw"], true)]));
  assert!(full_text.contains("upsert_document"), "{full_text}");
  assert!(!full_text.contains("upsert_vector"), "{full_text}");

  let coordinates = tokens(&frames(vec![stored("image", &["lance", "hnsw"], true)]));
  assert!(coordinates.contains("upsert_vector"), "{coordinates}");
  assert!(!coordinates.contains("upsert_document"), "{coordinates}");
}

/// THREE LEGS nest, which is the arity mechanism: a wider enum per arity would be a family of types
/// that must agree and are free to stop.
#[test]
fn a_three_legged_fan_nests_its_refusal() {
  let emitted = tokens(&document(vec![stored(
    "title",
    &["tantivy", "hnsw", "sonic"],
    true,
  )]));
  assert_eq!(
    emitted.matches("Refused").count(),
    // TWO in the return type — `Refused<A, Refused<B, C>>` — and FIVE across the three legs'
    // wrappers: `First(_)`, `Second(First(_))`, `Second(Second(_))`.
    7,
    "the nesting is written once per position: {emitted}"
  );
}

/// A `blob` elects nothing, declares no engine, and fans nothing.
#[test]
fn an_artifact_family_emits_no_slot_and_no_fan() {
  let mut artifacts = document(Vec::new());
  artifacts.kind = NodeKind::Blob;
  artifacts.searchable = Vec::new();
  assert!(structs(&artifacts).is_empty());
  assert!(doors(&artifacts).is_empty());
}

/// The MARKER is a fact of the DECLARATION and rides no gate, so a build compiling no engine at all
/// still has the names its declaration minted. What rides a gate is an impl naming a CONCRETE type —
/// and this emission names none, the engine being a parameter everywhere it appears.
#[test]
fn a_slot_marker_rides_no_engine_gate() {
  let emitted = tokens(&document(vec![stored("title", &["tantivy", "hnsw"], true)]));
  assert!(
    !emitted.contains("if_tantivy"),
    "nothing here names a concrete engine, so nothing here is gated: {emitted}"
  );
}