ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
//! **THE ANSWER FAMILY AND THE QUERY FIELDS** — what an election publishes, where each piece
//! lands, and the four conditions that decide whether it publishes anything at all.
//!
//! ```text
//!   #[ingraph(embedding, knn, toy(type = "…"))]           →  shotsByClipKeys(…): [<Key>Match!]!
//!                                                         →  shotsByClip(…):     [<Entity>Match!]!
//!   #[ingraph(embedding, knn, a(type=…), b(type=…), fanout)] →  shotsFusedByClipKeys(…): [ …FusedKeyMatch!]!
//!   #[ingraph(embedding, knn, toy)]                       →  nothing
//! ```
//!
//! Beside [`citizen`](super::citizen) on this directory's one-file-per-thing precedent: that file
//! proves the MOUNTING — the unit, the seat, the roster row — and this one proves what the unit
//! carries.
//!
//! # What is asserted HERE and nowhere else
//!
//! | the ruling | the assertion |
//! |---|---|
//! | a road needs a TYPED engine | [`an_untyped_election_publishes_nothing`] |
//! | a fanned road needs EVERY leg typed | [`a_fan_with_an_untyped_leg_publishes_no_fused_road`] |
//! | the declarations stand OUTSIDE the gate | [`every_answer_type_is_a_module_scope_item`] |
//! | the roster names what the emission lands | [`the_roster_names_every_answer_type`] |
//! | the bones rename moves the whole family | [`the_base_rename_moves_the_answer_family_and_its_fields`] |
//! | a declared word replaces ONE field's name | [`a_declared_word_names_one_field_and_no_other`] |
//!
//! The EXECUTING half — that a question parses, that a floor reaches the engine, that `first: 0`
//! touches no door — is `ingraph/tests/search_wire.rs`, which is the only place those can be run.

use quote::ToTokens as _;

use super::{
  Dedup, Elected, ElectionBackend, ElectionLabel, FieldNumbers, IndexBackend, IndexGraphql,
  IndexModel, IndexRename, Numbers, Upstream,
};
use crate::{
  engine::{Engine, FieldEngines},
  model::{GraphqlKind, NodeKind, Role},
  prefix::EmissionPrefix,
};

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

/// One engine block, typed or not, in or out of the leaderboard.
fn leg(word: &str, typed: bool) -> Engine {
  Engine {
    resource: typed.then(|| syn::parse_quote!(crate::Store)),
    ..Engine::bare(ident(word))
  }
}

/// A vector declaration over ONE election, wearing whatever engines and label a case hands it.
fn declared(legs: Vec<Engine>, fanout: bool, label: ElectionLabel) -> IndexModel {
  IndexModel {
    prefix: EmissionPrefix::default(),
    numbers: Numbers::default(),
    field_numbers: Vec::new(),
    index: ident("Shots"),
    kind: NodeKind::Vector,
    vis: syn::parse_quote!(pub),
    krate: syn::parse_quote!(::ingraph),
    source: Upstream {
      node: syn::parse_quote!(Keyframe),
      projections: Vec::new(),
    },
    dedup: Dedup::Hash,
    embeddings: vec![Elected::new(
      ident("clip"),
      label,
      syn::parse_quote!(::ingraph::Embedding<f32, 4, Clip>),
      None,
    )],
    labelled: Vec::new(),
    searchable: Vec::new(),
    engines: vec![FieldEngines {
      field: ident("clip"),
      engines: legs,
      fanout,
    }],
    stores: Vec::new(),
    data: false,
    keys: false,
    subscribe: false,
    extension: None,
    graphql: Some(IndexGraphql::of(GraphqlKind::AsyncGraphql)),
    rename: None,
    slot: None,
    fields: Vec::new(),
  }
}

/// The PLAIN road's shape: one typed engine, unfanned.
///
/// `pub(super)` because [`super::hydrated`] proves the TIER below these fields and needs the same
/// declaration to read it off — one fixture for one shape, on `similar`'s own precedent.
pub(super) fn plain() -> IndexModel {
  declared(vec![leg("toy", true)], false, ElectionLabel::Embedding)
}

/// The FANNED road's shape: two typed legs, both in the leaderboard.
///
/// `pub(super)` for [`plain`]'s reason.
pub(super) fn fanned() -> IndexModel {
  declared(
    vec![leg("deep", true), leg("shallow", true)],
    true,
    ElectionLabel::Embedding,
  )
}

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

/// EVERY TYPE the expansion lands at MODULE SCOPE, by name — WITHOUT opening any gate, which is
/// what makes the placement claim a claim.
fn landed(model: &IndexModel) -> Vec<String> {
  let file: syn::File = syn::parse2(model.emit()).expect("the emission parses");
  file
    .items
    .into_iter()
    .filter_map(|item| match item {
      syn::Item::Struct(declared) => Some(declared.ident.to_string()),
      syn::Item::Enum(declared) => Some(declared.ident.to_string()),
      _ => None,
    })
    .collect()
}

/// Every `#[graphql(name = "…")]` the expansion writes on a QUERY FIELD, in emission order.
///
/// Read off the METHODS of the query unit's own `#[Object]` block rather than off the whole token
/// stream, because the wire faces beside it name their own fields the same way — an assertion over
/// the whole emission would pass for a name that landed on a hit's `score`.
///
/// `pub(super)` for [`plain`]'s reason: [`super::rename_resolution`] reads the same five roads off
/// the same two fixtures, and a second copy of this walk is a second thing to keep in step.
pub(super) fn fields(model: &IndexModel) -> Vec<String> {
  let file: syn::File = syn::parse2(model.emit()).expect("the emission parses");
  let unit = model.queries_name();
  crate::tests::ungate(file.items)
    .into_iter()
    .flat_map(|item| match item {
      syn::Item::Const(anonymous) => match *anonymous.expr {
        syn::Expr::Block(block) => block
          .block
          .stmts
          .into_iter()
          .filter_map(|statement| match statement {
            syn::Stmt::Item(syn::Item::Impl(block)) => Some(block),
            _ => None,
          })
          .collect::<Vec<_>>(),
        _ => Vec::new(),
      },
      _ => Vec::new(),
    })
    .filter(|block| block.trait_.is_none() && unit == block.self_ty.to_token_stream().to_string())
    .flat_map(|block| block.items)
    .filter_map(|item| match item {
      syn::ImplItem::Fn(method) => method.attrs.iter().find_map(|attribute| {
        let written = attribute.to_token_stream().to_string().replace(' ', "");
        written
          .strip_prefix("#[graphql(name=\"")
          .and_then(|rest| rest.strip_suffix("\")]"))
          .map(ToOwned::to_owned)
      }),
      _ => None,
    })
    .collect()
}

/// **THE PLAIN ROAD PUBLISHES FOUR FIELDS AND ONE INPUT**, and nothing of the fused family.
///
/// Two questions — a QUESTION and an EXAMPLE KEY — at two tiers each. The two keys fields stand on
/// one condition rather than two: the by-example door takes a `SlotHandle` and no `AsyncGather`, so
/// whatever mounts either mounts both. The two HYDRATED fields stand on that same condition plus
/// the SQL family, which is a gate rather than a declaration fact — this walk opens it, so what is
/// read here is what a build carrying sqlx compiles. Their ORDER is the emitter's own walk, which is
/// what makes this an equality rather than a membership test.
///
/// ONE input between all four, because only the question roads take a minted one and the two tiers
/// SHARE it: the by-example argument is the upstream's own key crossing inward through the operand
/// map, and whatever type that is belongs to the RECORD's emission.
#[test]
fn a_typed_unfanned_election_publishes_the_plain_road_at_both_tiers() {
  let model = plain();
  assert_eq!(
    fields(&model),
    vec![
      "shotsByClipKeys".to_owned(),
      "shotsSimilarByClipKeys".to_owned(),
      "shotsByClip".to_owned(),
      "shotsSimilarByClip".to_owned(),
    ],
  );

  let landed = landed(&model);
  assert!(
    landed.contains(&"ShotsClipQuestion".to_owned()),
    "{landed:?}"
  );
  for absent in [
    "ShotsClipFusedKeyMatch",
    "ShotsClipSighting",
    "ShotsClipEngines",
  ] {
    assert!(
      !landed.contains(&absent.to_owned()),
      "the plain road minted a fused type: {landed:?}",
    );
  }
}

/// **THE ANSWER IS THE FRAMEWORK'S OWN HIT**, reached through the shelf — nothing is minted for it.
///
/// The claim is the ABSENCE of a `<Index><Field>KeyMatch` beside the presence of `Match`: a two-row
/// object of this emission's own would have dropped the engine ordinal, which is the number a
/// single-shot answer is continued from.
#[test]
fn the_keys_road_answers_the_frameworks_own_hit() {
  let emitted = tight(&plain());
  assert!(
    emitted.contains("::ingraph::__private::graphql::Match<"),
    "{emitted}",
  );
  assert!(
    emitted.contains("::ingraph::__private::graphql::matches"),
    "{emitted}",
  );
  assert!(
    !landed(&plain()).contains(&"ShotsClipKeyMatch".to_owned()),
    "a second hit shape was minted beside the framework's",
  );
}

/// **THE FANNED ROAD PUBLISHES ITS OWN ANSWER FAMILY** — one object per leg, the union over them,
/// the hit, and the per-leg engines product.
#[test]
fn a_fanned_election_publishes_the_fused_road() {
  let model = fanned();
  assert_eq!(fields(&model), vec!["shotsFusedByClipKeys".to_owned()]);

  let landed = landed(&model);
  for minted in [
    "ShotsClipQuestion",
    "ShotsClipEngines",
    "ShotsClipDeepSighting",
    "ShotsClipShallowSighting",
    "ShotsClipSighting",
    "ShotsClipFusedKeyMatch",
  ] {
    assert!(landed.contains(&minted.to_owned()), "{minted}: {landed:?}");
  }
}

/// **AN ELECTION THAT TYPED NO ENGINE PUBLISHES NOTHING**, and the wall is the resolver's own: a
/// slot lookup is a `TypeId` on a concrete pairing, so there is no `E` for one to name.
#[test]
fn an_untyped_election_publishes_nothing() {
  let model = declared(vec![leg("toy", false)], false, ElectionLabel::Embedding);
  assert!(fields(&model).is_empty(), "{:?}", fields(&model));
  assert!(
    !landed(&model).contains(&"ShotsClipQuestion".to_owned()),
    "{:?}",
    landed(&model),
  );
}

/// **A DECLARATION WEARING NO BACKEND WORD PUBLISHES NOTHING EITHER** — the presence law, at the
/// tier that mints the fields.
#[test]
fn an_undressed_declaration_publishes_nothing() {
  let model = IndexModel {
    prefix: EmissionPrefix::default(),
    graphql: None,
    ..plain()
  };
  assert!(fields(&model).is_empty());
  assert!(!landed(&model).contains(&"ShotsClipQuestion".to_owned()));
}

/// **A FAN WITH ONE UNTYPED LEG PUBLISHES NO FUSED ROAD**, and the exclusion is stricter than *some
/// leg is typed*: the door is generic over one engine per LEG and the call spells them all, so a
/// slot with an untyped leg has a call this emission cannot write.
#[test]
fn a_fan_with_an_untyped_leg_publishes_no_fused_road() {
  let model = declared(
    vec![leg("deep", true), leg("shallow", false)],
    true,
    ElectionLabel::Embedding,
  );
  assert!(fields(&model).is_empty(), "{:?}", fields(&model));
  assert!(!landed(&model).contains(&"ShotsClipFusedKeyMatch".to_owned()));
}

/// **A FANNED SET ELECTION PUBLISHES NO FUSED ROAD** — the same exclusion `fanned_slots` makes one
/// grain down, and for its reason: RRF joins ordinals, and a set election's `m` streams have no
/// order between them to read one from, so the door it would call is not emitted.
#[test]
fn a_fanned_set_election_publishes_no_fused_road() {
  let model = declared(
    vec![leg("deep", true), leg("shallow", true)],
    true,
    ElectionLabel::List,
  );
  assert!(fields(&model).is_empty(), "{:?}", fields(&model));
}

/// **EVERY ANSWER TYPE IS A MODULE-SCOPE ITEM, OUTSIDE THE BINDING GATE** — the Q1 rider.
///
/// [`landed`] opens no gate, so a name it finds is a name a build with no async-graphql also has.
/// A type minted inside the gate would compile everywhere the feature is on and would vanish from
/// every other build — taking the roster's own answer with it, since the enumeration names what
/// this walk sees.
#[test]
fn every_answer_type_is_a_module_scope_item() {
  let landed = landed(&fanned());
  for minted in [
    "ShotsClipQuestion",
    "ShotsClipEngines",
    "ShotsClipDeepSighting",
    "ShotsClipSighting",
    "ShotsClipFusedKeyMatch",
  ] {
    assert!(landed.contains(&minted.to_owned()), "{minted}: {landed:?}");
  }
}

/// **THE ROSTER NAMES EXACTLY WHAT THE EMISSION LANDS**, so a collision refusal is measured against
/// a name the expansion actually declares.
#[test]
fn the_roster_names_every_answer_type() {
  for model in [plain(), fanned()] {
    let rostered: Vec<String> = model
      .emitted_types()
      .iter()
      .map(|declared| declared.name.to_string())
      .collect();
    assert_eq!(landed(&model), rostered);
  }

  // AND THE ROLE IS THE ANSWER FAMILY'S OWN, carrying the election a refusal would point at.
  assert!(
    fanned()
      .emitted_types()
      .iter()
      .any(|declared| matches!(&declared.role, Role::Answer(field) if field == "clip")),
  );
}

/// **THE BONES RENAME MOVES THE WHOLE FAMILY AND THE FIELD NAMES WITH IT** — one stem per
/// declaring scope, and one subject per schema.
#[test]
fn the_base_rename_moves_the_answer_family_and_its_fields() {
  let renamed = IndexModel {
    prefix: EmissionPrefix::default(),
    rename: Some(IndexRename::Base(ident("ShotSearch"))),
    ..fanned()
  };
  assert_eq!(
    fields(&renamed),
    vec!["shotSearchFusedByClipKeys".to_owned()]
  );
  assert!(
    landed(&renamed).contains(&"ShotSearchClipFusedKeyMatch".to_owned()),
    "{:?}",
    landed(&renamed),
  );
  assert!(
    !landed(&renamed).contains(&"ShotsClipFusedKeyMatch".to_owned()),
    "a name kept the old stem",
  );
}

/// **THE SKIN'S BASE PREFIX MOVES THE SDL NAMES AND LEAVES THE RUST ONES**, which is the axis law
/// this family already lives under.
#[test]
fn a_skin_prefix_moves_the_published_names_alone() {
  let mut skin = IndexBackend::of(GraphqlKind::AsyncGraphql);
  skin.prefix = Some(syn::LitStr::new("Reels", proc_macro2::Span::call_site()));
  let model = IndexModel {
    prefix: EmissionPrefix::default(),
    graphql: Some(IndexGraphql {
      backends: vec![skin],
    }),
    ..plain()
  };
  let emitted = tight(&model);
  assert!(
    emitted.contains(r#"Cow::Borrowed("ReelsClipQuestion")"#),
    "{emitted}"
  );
  assert!(
    landed(&model).contains(&"ShotsClipQuestion".to_owned()),
    "the Rust name moved with a schema word",
  );
}

/// **A DECLARED WORD NAMES ONE FIELD AND NO OTHER**, verbatim.
///
/// Every seat is written on one election so the claim is that they are three names rather than one
/// word spent three times. The PLAIN declaration is where `keys` and `similar` are told apart —
/// both roads are live there, so a word that reached the wrong one would show as the other field's
/// name moving; and the FANNED declaration publishes only its fused field, so `keys` is written
/// there and must reach nothing.
///
/// The two HYDRATED fields stay derived in every case, and that is the second claim rather than
/// noise in the first: there are three seats for five roads, so a word written for a keys-tier field
/// must not compose its way onto the tier below — a declared word is VERBATIM, and a name derived
/// from one would be a rename its author could not predict.
#[test]
fn a_declared_word_names_one_field_and_no_other() {
  let named = |keys: Option<&str>, fused: Option<&str>, similar: Option<&str>| ElectionBackend {
    keys: keys.map(|word| syn::LitStr::new(word, proc_macro2::Span::call_site())),
    fused: fused.map(|word| syn::LitStr::new(word, proc_macro2::Span::call_site())),
    similar: similar.map(|word| syn::LitStr::new(word, proc_macro2::Span::call_site())),
    ..ElectionBackend::of(GraphqlKind::AsyncGraphql)
  };

  let renamed = IndexModel {
    prefix: EmissionPrefix::default(),
    field_numbers: vec![FieldNumbers {
      field: ident("clip"),
      numbers: Numbers::default(),
      skins: vec![named(Some("clipNeighbours"), None, None)],
    }],
    ..plain()
  };
  assert_eq!(
    fields(&renamed),
    vec![
      "clipNeighbours".to_owned(),
      "shotsSimilarByClipKeys".to_owned(),
      "shotsByClip".to_owned(),
      "shotsSimilarByClip".to_owned(),
    ],
    "the question road's word moved the by-example field or its own hydrated twin",
  );

  // The SIMILAR seat, on the same declaration and at the other field — the pair that makes the two
  // words two names rather than one.
  let renamed = IndexModel {
    prefix: EmissionPrefix::default(),
    field_numbers: vec![FieldNumbers {
      field: ident("clip"),
      numbers: Numbers::default(),
      skins: vec![named(None, None, Some("clipLikeThis"))],
    }],
    ..plain()
  };
  assert_eq!(
    fields(&renamed),
    vec![
      "shotsByClipKeys".to_owned(),
      "clipLikeThis".to_owned(),
      "shotsByClip".to_owned(),
      "shotsSimilarByClip".to_owned(),
    ],
    "the by-example word moved the question field or its own hydrated twin",
  );

  // The FUSED seat is the plain one's twin and reaches the other field alone: a declaration that
  // renamed its plain road has said nothing about its fused one.
  let renamed = IndexModel {
    prefix: EmissionPrefix::default(),
    field_numbers: vec![FieldNumbers {
      field: ident("clip"),
      numbers: Numbers::default(),
      skins: vec![named(
        Some("clipNeighbours"),
        Some("clipEverywhere"),
        Some("clipLikeThis"),
      )],
    }],
    ..fanned()
  };
  assert_eq!(fields(&renamed), vec!["clipEverywhere".to_owned()]);
}

/// **THE `first` DEFAULT IS THE RESOLVED CHAIN'S ANSWER, WRITTEN AS AN SDL LITERAL**, and `depth`
/// carries none — a preference a client may write past has a default and a fetch depth defers.
#[test]
fn the_published_numbers_are_the_resolved_chain() {
  let model = IndexModel {
    prefix: EmissionPrefix::default(),
    field_numbers: vec![FieldNumbers {
      field: ident("clip"),
      numbers: Numbers::default(),
      skins: vec![ElectionBackend {
        first: core::num::NonZeroU32::new(7),
        ..ElectionBackend::of(GraphqlKind::AsyncGraphql)
      }],
    }],
    ..plain()
  };
  let emitted = tight(&model);
  assert!(
    emitted.contains(r#"#[graphql(name="first",default=7)]"#),
    "{emitted}"
  );
  assert!(emitted.contains(r#"#[graphql(name="depth")]"#), "{emitted}");

  // NO `ceiling` ROW ANYWHERE ON THE REQUEST SURFACE: a protective number never crosses the wire.
  assert!(!emitted.contains(r#"name="ceiling""#), "{emitted}");
}

/// **THE WALL CAPS THE PUBLISHED DEFAULT** — a schema promising a page size the fetch silently cuts
/// is the one thing an SDL literal must not be able to do.
#[test]
fn the_declared_ceiling_caps_the_published_default() {
  let model = IndexModel {
    prefix: EmissionPrefix::default(),
    numbers: Numbers {
      limit: core::num::NonZeroU32::new(50),
      depth: None,
      ceiling: core::num::NonZeroU32::new(4),
      streams: None,
    },
    ..plain()
  };
  assert!(
    tight(&model).contains(r#"#[graphql(name="first",default=4)]"#),
    "{}",
    tight(&model),
  );
}

/// **A FULL-TEXT DECLARATION PUBLISHES NO ANSWER FAMILY**, and the absence is scope rather than a
/// wall: the road built here is the VECTOR keys road, and a full-text subject's question is a
/// string against whatever grammar its engine has.
#[test]
fn a_full_text_declaration_publishes_no_answer_family() {
  let model = IndexModel {
    prefix: EmissionPrefix::default(),
    kind: NodeKind::Fulltext,
    embeddings: Vec::new(),
    searchable: vec![ident("body")],
    ..plain()
  };
  assert!(fields(&model).is_empty(), "{:?}", fields(&model));
}