ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! WHAT THE INSTRUMENT CLAUSE EMITS ON A DERIVED INDEX — the gate pair the retrieve face rides, and
//! the span each of its doors opens.
//!
//! A suite of its own beside [`super::tests`], for the reason [`crate::emit::tracing_tests`] gives:
//! what is asserted here is ONE clause — which items it doubles, which gate each half rides, and
//! that a build without observation gets back exactly the tokens it got before the clause existed.
//!
//! Every assertion reads the emission AS WRITTEN, gates and all, rather than through
//! [`super::tests`]'s opener — because the subject IS the gate. A walk that opened it would be
//! asserting about a build rather than about what an expansion hands the compiler.

use super::{
  IndexModel,
  tests::{document, embedding_index},
};
use crate::{model::NodeKind, prefix::EmissionPrefix};

/// The emission's tokens as text, which is what a gate can be read out of: a gate is a macro
/// invocation, so its contents are tokens and not items until the macro runs.
fn emitted(model: &IndexModel) -> String {
  model.emit().to_string()
}

/// **THE RETRIEVE FACE IS WRITTEN TWICE**, once inside each half of the gate pair — the shape the
/// query face already uses, and for the same reason: an attribute cannot be added by a macro that
/// expands to nothing, and neither can a wrapper be subtracted by one.
#[test]
fn the_retrieve_face_is_written_once_per_half() {
  let emission = emitted(&document());
  assert!(emission.contains("if_tracing"), "{emission}");
  assert!(emission.contains("if_no_tracing"), "{emission}");
  // Counted with the generic list's own `<` on the end, because `retrieve` is a PREFIX of
  // `retrieve_keys` and a bare name would count both doors as one.
  for door in ["async fn retrieve_keys <", "async fn retrieve <"] {
    assert_eq!(
      emission.matches(door).count(),
      2,
      "`{door}` is not written once per half: {emission}"
    );
  }
}

/// **THE INSTRUMENTED HALF opens one span per door, named and fielded** — and the level is a
/// CONSTANT, which is what lets an emitted span be cheaper than a framework one.
#[test]
fn the_instrumented_half_opens_a_named_span_per_door() {
  let emission = emitted(&embedding_index());
  assert!(emission.contains("\"ingraph.query\""), "{emission}");
  assert!(emission.contains("tracing :: Level :: INFO"), "{emission}");
  for field in ["record", "entry", "engine"] {
    assert!(
      emission.contains(&format!("{field} =")),
      "the span carries no `{field}`: {emission}"
    );
  }
  // The declaration names itself, so one pane holds every door of one node.
  assert!(
    emission.contains("record = \"SegmentEmbedding\""),
    "{emission}"
  );
  // ALL FOUR doors, each under its own name — the raw pair, and the two the by-key read bought: the
  // read itself and the similar-by-example door written in terms of it. It was SIX until the `ask`
  // road retired on 2026-08-19, and the two that left are the two a declaration no longer mints.
  //
  // The get door matters MOST here of the four, because it is the one a trace shows NESTED: a
  // similar retrieve opens its own span and then the read's inside it, and a door that were
  // silently uninstrumented would leave that inner interval charged to its caller.
  for entry in [
    "retrieve_keys_by_image_embedding",
    "retrieve_by_image_embedding",
    "get_image_embedding",
    "retrieve_similar_by_image_embedding",
  ] {
    assert!(
      emission.contains(&format!("entry = \"{entry}\"")),
      "no door named `{entry}`: {emission}"
    );
  }
}

/// The THIRD FIELD names what the door crossed to, and a derived index crosses to an ENGINE.
///
/// Read per kind rather than asserted once, because the value is the declaration's own storage and a
/// clause that hardcoded one would put `fulltext` on a knn.
#[test]
fn each_kind_names_the_engine_it_crossed() {
  for (model, engine) in [(document(), "fulltext"), (embedding_index(), "vector")] {
    let emission = emitted(&model);
    assert!(
      emission.contains(&format!("engine = \"{engine}\"")),
      "{:?} names no engine: {emission}",
      model.kind
    );
    assert!(
      !emission.contains("db ="),
      "a derived index has no database to name: {emission}"
    );
  }
}

/// **THE GATE-SHUT BUILD IS UNCHANGED**, which is the clause's own acceptance and the one claim a
/// reader of a `git diff` cannot check by eye.
///
/// The shut half is the tokens `if_no_tracing!` holds — what a build with observation off compiles.
/// What it asserts is that no `tracing` name survives into such a build and that the doors it exists
/// to keep are still there.
#[test]
fn the_gate_shut_build_names_no_tracing() {
  let shut = shut_halves(embedding_index().emit());
  assert!(!shut.is_empty(), "there is no shut half to check");
  assert!(
    !shut.contains("tracing"),
    "a build with observation off still names tracing: {shut}"
  );
  assert!(
    !shut.contains("async move"),
    "the uninstrumented half carries the wrapper the span needed: {shut}"
  );
  for door in [
    "retrieve_keys_by_image_embedding",
    "retrieve_by_image_embedding",
    "get_image_embedding",
    "retrieve_similar_by_image_embedding",
  ] {
    assert!(
      shut.contains(&format!("async fn {door}")),
      "the shut half lost the door it exists to keep: {shut}"
    );
  }
}

/// A KIND THAT ANSWERS NO RETRIEVE emits NEITHER half, and not two empty gates either.
///
/// `blob` is addressed rather than ranked, so there is no door for a span to time — and an empty
/// gate pair in its expansion would be two macro invocations standing for nothing.
#[test]
fn the_artifact_family_rides_no_gate() {
  let emission = emitted(&IndexModel {
    prefix: EmissionPrefix::default(),
    kind: NodeKind::Blob,
    ..document()
  });
  assert!(
    !emission.contains("if_tracing"),
    "a node with no retrieve carries the gate: {emission}"
  );
  assert!(
    !emission.contains("if_no_tracing"),
    "a node with no retrieve carries the complement: {emission}"
  );
}

/// Every `if_no_tracing!` group's contents, as text — what a build WITHOUT observation compiles.
///
/// A TOKEN walk rather than an item walk, and the reason is where the retrieve face lands: an
/// emission nests its impls inside an anonymous `const`, so a gate is a `Stmt::Macro` one level down
/// and an item walk over the file's own list finds nothing. Tokens have no such layers.
fn shut_halves(tokens: proc_macro2::TokenStream) -> String {
  let mut kept = String::new();
  // Whether the ident just read was the gate's own name, so the group that follows its `!` is the
  // one to keep. Reset by every other ident, which is what makes this a match on the PAIR rather
  // than on a name appearing anywhere.
  let mut named = false;
  for tree in tokens {
    match tree {
      proc_macro2::TokenTree::Ident(ident) => named = ident == "if_no_tracing",
      proc_macro2::TokenTree::Group(group) if named => {
        kept.push_str(&group.stream().to_string());
        named = false;
      }
      proc_macro2::TokenTree::Group(group) => kept.push_str(&shut_halves(group.stream())),
      _ => {}
    }
  }
  kept
}