ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! WHAT THE BY-KEY GET DOOR EMITS — `get_<field>`, its one crossing, and the judgments that moved
//! into it.
//!
//! Beside [`similar`](super::similar) rather than inside it, on this directory's own precedent: one
//! file per thing being proved. The similar door's file keeps the claims about *sugar over the
//! pair*; this one keeps the claims about the READ that sugar is now written in terms of.
//!
//! # The subject is an AUTHORITY, and an authority is proved by counting
//!
//! `get_<field>` did not add a judgment — it TOOK the three the similar door used to make. So the
//! assertions that matter here are arithmetic: `Unindexed`, `Several` and `Width` appear once per
//! gate half and no more, and the similar door's body reaches the engine's by-key read through this
//! door rather than beside it. An emission that copied the judgments into both doors would pass
//! every inclusion-only reading of this file and be exactly the duplication the door exists to end.

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

/// The emission's tokens as text — the gate-blind reading, because the doors live inside the
/// observation gate pair and the subject here is the door rather than the gate.
fn emitted(model: &IndexModel) -> String {
  model.emit().to_string()
}

/// ONE emitted method, from its own `async fn` to the start of the next item — signature, `where`
/// clause and body, and nothing of the neighbour's DOCS.
///
/// The docs are what the cut is for. Every negative assertion below names something the similar
/// door's prose mentions in words — `knn`, the by-key read — so a slice that ran to the next
/// `async fn` would carry the next door's doc attributes and answer *contains* for all of them.
fn door<'a>(emission: &'a str, name: &str) -> &'a str {
  let after = emission
    .split(&format!("async fn {name} <"))
    .nth(1)
    .unwrap_or_else(|| panic!("`{name}` is emitted: {emission}"));
  let end = [after.find("# [doc"), after.find("async fn")]
    .into_iter()
    .flatten()
    .min()
    .unwrap_or(after.len());
  &after[..end]
}

/// **ONE GET DOOR PER ELECTION, named `get_<field>`** — the pair's own naming law, spent on the
/// fourth door.
///
/// Counted at TWO per name because the retrieve face is written once per half of the observation
/// gate, which is the shape every door here already has. The two-election model is
/// [`tests::two_elections`](super::tests), whose elections declare DIFFERENT widths — so a door
/// emitted once and duplicated would be caught here by its name and next door by its type.
#[test]
fn every_election_gets_its_own_get_door() {
  let emission = emitted(&two_elections());
  for field in ["caption_embedding", "image_embedding"] {
    assert_eq!(
      emission.matches(&format!("async fn get_{field} <")).count(),
      2,
      "`get_{field}` is not written once per gate half: {emission}"
    );
  }
}

/// **A DECLARATION THAT ELECTS NOTHING GETS NO GET DOOR**, for the two reasons its similar door is
/// also absent.
///
/// A full-text index has no COLUMN to read one back by — its engine takes a slot, a scope and a
/// string — and its own by-key question is the `stored` marker's, a grammar this round does not
/// own. A `blob` is addressed rather than ranked and answers no retrieve at all.
#[test]
fn a_kind_with_no_election_gets_no_get_door() {
  for model in [
    document(),
    IndexModel {
      prefix: EmissionPrefix::default(),
      kind: NodeKind::Blob,
      ..document()
    },
  ] {
    let emission = emitted(&model);
    assert!(
      !emission.contains("async fn get_"),
      "{:?} carries a by-key door it cannot answer: {emission}",
      model.kind
    );
  }
}

/// **ONE READ SCOPE**, because the door makes ONE engine call — which is the whole of what
/// separates its signature from the similar door's.
///
/// Asserted as a pair of readings, since both scopes on the door below project the same
/// `ReadContext` and what tells one from two is the parameter NAMES.
#[test]
fn the_get_door_takes_one_scope() {
  let emission = emitted(&embedding_index());
  let signature = door(&emission, "get_image_embedding")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(
    signature.contains("own :"),
    "no own-read scope: {signature}"
  );
  assert!(
    !signature.contains("scope :"),
    "a one-crossing door takes the knn's scope: {signature}"
  );
  // The key is a BORROW, as it is on the door below: the caller keeps it.
  assert!(signature.contains("key : &"), "{signature}");
}

/// **IT ANSWERS THE CHECKED EMBEDDING** — the elected field's own type, width and space, not the
/// engine's raw coordinates.
///
/// That is what makes it a door rather than a forwarding of the seam: a caller past it takes the
/// width from the type, and there is no second place where a stored vector could be trusted.
#[test]
fn the_get_door_answers_the_checked_embedding() {
  let emission = emitted(&embedding_index());
  let signature = door(&emission, "get_image_embedding")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(
    signature.contains("Embedding"),
    "the door answers something else: {signature}"
  );
  // NOT a page: no ranking, no scoring, no budget — the three things a retrieve door's return says.
  assert!(!signature.contains("Ranked"), "{signature}");
  assert!(!signature.contains("floor"), "{signature}");
  assert!(!signature.contains("limit"), "{signature}");
}

/// **NO `Admits` BOUND**, because nothing here builds a dedup membership.
///
/// The declaration's `dedup` word picks the bound its retrieve doors carry; this door walks an
/// address and checks a width, and asking a key for `Hash` or `PartialEq` to do that would be a
/// demand the read does not make. Read off the `where` clause rather than off the whole method,
/// since `HashSeen` is named in the similar door's body one item down.
#[test]
fn the_get_door_carries_no_dedup_bound() {
  let emission = emitted(&embedding_index());
  let signature = door(&emission, "get_image_embedding")
    .split('{')
    .next()
    .expect("the door has a signature");
  assert!(
    signature.contains(":: Field"),
    "the address walk's own bound is missing: {signature}"
  );
  // And it is the MERGED row rather than the retired per-engine one — the walk's bound stopped being
  // keyed on the engine when the column language landed.
  assert!(!signature.contains("VectorField"), "{signature}");
  for bound in ["Hash", "PartialEq", "Seen"] {
    assert!(
      !signature.contains(bound),
      "the read asks a key for `{bound}`: {signature}"
    );
  }
}

/// **THE BODY IS THE BY-KEY READ AND NOTHING ELSE** — build the address, ask the seam, check what
/// came back.
///
/// The exclusions are the half worth having: a read that reached a `knn`, a walk or a query would
/// be a second query path wearing a getter's name, and no inclusion-only assertion would notice.
#[test]
fn the_get_door_is_the_by_key_read_and_nothing_else() {
  let emission = emitted(&embedding_index());
  let body = door(&emission, "get_image_embedding");
  for call in ["vector_addressed", "get_vectors"] {
    assert!(body.contains(call), "the read is missing `{call}`: {body}");
  }
  for search in ["knn", "ranked_keys", "VectorQuery", "vector_keyed"] {
    assert!(
      !body.contains(search),
      "the read reaches `{search}` — a getter that searches is a second query path: {body}"
    );
  }
}

/// **THE THREE JUDGMENTS ARE WRITTEN ONCE**, and this is the assertion the whole rework exists for.
///
/// Twice in the emission means once per half of the observation gate — the shape every door here
/// has. FOUR would mean the similar door kept its own copy, which is the duplication that made two
/// doors able to drift about what a stored vector has to be.
///
/// The words are counted over the WHOLE emission rather than inside one door, because the claim is
/// about how many places state them at all.
#[test]
fn the_arity_and_width_judgments_are_written_once() {
  let emission = emitted(&embedding_index());
  for judgment in ["Unindexed", "Several", "Width"] {
    assert_eq!(
      emission.matches(judgment).count(),
      2,
      "`{judgment}` is stated in more than one place — once per gate half is the whole budget: \
       {emission}"
    );
  }
}

/// **THE SIMILAR DOOR REACHES THE ENGINE THROUGH THIS ONE**, rather than beside it.
///
/// The mutation this exists for is the one a refactor invites: leave the old body alone and add the
/// get door beside it. Both doors then answer correctly and forever, until the day one of them
/// learns something the other does not.
#[test]
fn the_similar_door_delegates_to_the_get_door() {
  let emission = emitted(&embedding_index());
  let body = door(&emission, "retrieve_similar_by_image_embedding");
  assert!(
    body.contains("get_image_embedding"),
    "the similar door does not go through the read: {body}"
  );
  for own in ["vector_addressed", "get_vectors", "Unindexed", "Width"] {
    assert!(
      !body.contains(own),
      "the similar door still does the read's own work (`{own}`): {body}"
    );
  }
}

/// **IT WEARS ITS OWN SPAN**, named by its own `entry` — the sixth door of the instrumented half.
#[test]
fn the_get_door_names_itself_in_its_span() {
  let emission = emitted(&embedding_index());
  assert!(
    emission.contains("entry = \"get_image_embedding\""),
    "the door opens no span of its own: {emission}"
  );
}