ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! **NAMED → KIND-VERIFIED**, read off the tokens: the audit a POINTING leg emits, the seam it
//! names, and the span it lands on.
//!
//! The first of the three binding laws is the only one a declaration can settle by itself — the
//! other two need the resource catalog, which is a graph root away — and settling it means turning
//! a path this expansion cannot resolve into a bound rustc can. What the tokens can say is that the
//! bound is EMITTED, that it names the seam this declaration's kind actually needs, and that it is
//! spanned where its author wrote the path. What they cannot say is that it refuses: that is
//! `ingraph/tests/engine_word.rs`, whose blessed fixture holds the `E0277` with the caret on the
//! word.
//!
//! Beside [`super::answers`] on this directory's one-file-per-thing precedent, and reading its
//! fixtures: the question here is about the same declarations from a different side.
//!
//! # Why the audit exists beside projections that already refuse
//!
//! A pointed leg's query package publishes `floor: <T as VectorEngine>::Score`, which refuses a
//! wrong kind on its own. Two things it does not do, and each is half of why this is written:
//!
//! 1. **it lands nowhere useful.** A projection sits inside a package row the author never wrote,
//!    so `E0277` is reported at the whole `#[ingraph::vector(…)]` attribute — see the first four
//!    errors of the blessed fixture. The audit is `quote_spanned!` at the path, so the caret sits on
//!    the word, which is what *named → kind-verified, at the word* actually asks for;
//! 2. **it is the wire's, not the axis's.** The package is minted by the question layer, and this
//!    check has to hold whatever that layer does next —
//!    [`the_audit_does_not_ride_the_wire_skin`] is that separation, measured.
//!
//! A COVERAGE claim was drafted here and withdrawn: every shape tried — set elections, fanned legs,
//! `rrf = false` legs, skinless declarations — mints the seat and therefore projects anyway. The
//! audit's value is the span and the independence, and the file says only that.

use quote::ToTokens as _;

use super::{IndexModel, NodeKind};
use crate::engine::{Engine, FieldEngines};

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

/// The whole expansion with the spaces taken out — what a claim about a projection is read off.
fn compact(model: &IndexModel) -> String {
  model
    .emit()
    .to_token_stream()
    .to_string()
    .split_whitespace()
    .collect()
}

/// A VECTOR declaration whose one election points at `resource`, or points at nothing.
fn vector(resource: Option<syn::Path>) -> IndexModel {
  let mut model = super::answers::plain();
  model.engines = vec![FieldEngines {
    field: ident("clip"),
    engines: vec![Engine {
      resource,
      ..Engine::bare(ident("toy"))
    }],
    fanout: false,
  }];
  model
}

/// [`vector`]'s twin one kind over — the same election, re-labelled onto the full-text seam.
fn fulltext(resource: Option<syn::Path>) -> IndexModel {
  let mut model = vector(resource);
  model.kind = NodeKind::Fulltext;
  model.embeddings = Vec::new();
  model.searchable = vec![ident("clip")];
  model
}

/// **THE AUDIT NAMES THE SEAM THIS KIND NEEDS**, which is the whole of the check: a vector election
/// holds coordinates and a full-text one holds documents, and the two are different traits.
#[test]
fn each_kind_audits_its_pointed_resource_against_its_own_seam() {
  assert!(
    compact(&vector(Some(syn::parse_quote!(crate::Vectors))))
      .contains("const_:fn()=::ingraph::__private::store::holds_coordinates::<crate::Vectors>;"),
    "{}",
    compact(&vector(Some(syn::parse_quote!(crate::Vectors))))
  );
  assert!(
    compact(&fulltext(Some(syn::parse_quote!(crate::Ft))))
      .contains("const_:fn()=::ingraph::__private::store::holds_documents::<crate::Ft>;"),
    "{}",
    compact(&fulltext(Some(syn::parse_quote!(crate::Ft))))
  );
}

/// **AN UNPOINTED LEG IS AUDITED AGAINST NOTHING** — the presence law at this word: saying nothing
/// costs a declaration exactly nothing, here as everywhere else.
#[test]
fn a_leg_that_points_at_nothing_emits_no_audit() {
  assert!(
    !compact(&vector(None)).contains("holds_coordinates"),
    "{}",
    compact(&vector(None))
  );
  assert!(
    !compact(&fulltext(None)).contains("holds_documents"),
    "{}",
    compact(&fulltext(None))
  );
}

/// **THE AUDIT IS INDEPENDENT OF THE WIRE**, which is what makes the kind a rule of the resource
/// axis rather than a side effect of publishing a query package.
///
/// A declaration with no GraphQL skin still points, and its deployment still has to open the right
/// KIND of store for it. The `floor` projection happens to survive that shape too — measured, not
/// assumed — so what this pins is that the audit does not RIDE it: the two are emitted from
/// different walks, and a round that changes what the wire mints cannot silently take the kind law
/// with it.
#[test]
fn the_audit_does_not_ride_the_wire_skin() {
  let mut model = vector(Some(syn::parse_quote!(crate::Vectors)));
  model.graphql = None;
  let compact = compact(&model);

  assert!(
    compact.contains("::ingraph::__private::store::holds_coordinates::<crate::Vectors>;"),
    "a skinless declaration lost its kind check: {compact}"
  );
}

/// EVERY leg of a fan is audited, not just the first — a fanned election points once per leg and
/// each one is a separate claim about a separate store.
#[test]
fn a_fan_audits_every_leg_it_points_with() {
  let mut model = vector(None);
  model.engines = vec![FieldEngines {
    field: ident("clip"),
    engines: vec![
      Engine {
        resource: Some(syn::parse_quote!(crate::Deep)),
        ..Engine::bare(ident("deep"))
      },
      Engine {
        resource: Some(syn::parse_quote!(crate::Shallow)),
        ..Engine::bare(ident("shallow"))
      },
    ],
    fanout: true,
  }];
  let compact = compact(&model);

  for resource in ["crate::Deep", "crate::Shallow"] {
    assert!(
      compact.contains(&format!(
        "::ingraph::__private::store::holds_coordinates::<{resource}>;"
      )),
      "the fan left `{resource}` unverified: {compact}"
    );
  }
}

/// The AUDIT rides the framework shelf like every other emitted name, so a declaration needs
/// `ingraph` in its manifest and nothing else — and a renamed dependency moves it.
#[test]
fn the_audit_goes_through_the_shelf_and_moves_with_a_rename() {
  let mut model = vector(Some(syn::parse_quote!(crate::Vectors)));
  model.krate = syn::parse_quote!(crate::shim);
  let compact = compact(&model);

  assert!(
    compact.contains("crate::shim::__private::store::holds_coordinates::<crate::Vectors>;"),
    "{compact}"
  );
}