ingraph-derive 0.1.0

The attribute and derive macros for ingraph: the words a record, node, key, filter and vocabulary declaration is written in.
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
//! AN ARTIFACT FAMILY'S HEAD — where its objects are stored, how its addresses end, and whether the
//! bytes may ride beside them.
//!
//! Beside [`engines`](super::engines) rather than inside it, on that file's own precedent: one file
//! per thing being proved. What differs is the GRAIN, and the difference is the whole reason this
//! file exists — a full-text or vector slot is `(field × engine)` and is named on the field, while
//! an artifact family elects nothing and holds one object per message, so its slot is
//! `(declaration × engine)` and the head is the only position coarse enough to name it.
//!
//! # What is asserted here
//!
//! The MODEL a declaration produces and the SENTENCE a refusal carries. Nothing about emission: the
//! `extension` word's dynamic forms have no emitted half yet — the seam that would carry a per-entry
//! suffix to a by-key `get` is lettered, not built — so what a parse test can honestly claim is that
//! the grammar READS, FENCES and REFUSES, which is exactly what the round's T1 is.
//!
//! `data` stands in the same place for the same reason: what the word grants is a PERMISSION, and a
//! permission is settled at the declaration whether or not anything has yet been written to spend
//! it. So it is read, refused and pinned here, and which face serves the bytes is that face's round.
//!
//! # Every acceptance also states an EXCLUSION
//!
//! The engine vocabulary is OPEN, so the head admits any word it does not own. A test that only
//! checked *this word parsed* would pass for a parser that swallowed `upstream(…)` too. So the
//! accepting tests name what the word must NOT have taken, and the refusing ones pin the sentence.

use ingraph_codegen::{extension::Extension, index::IndexModel, prelude::NodeKind};

use super::tests::refused;

/// The pass under test at the BLOB kind.
fn blob(input: &syn::DeriveInput) -> syn::Result<IndexModel> {
  let (host, arguments) = crate::host::split(input);
  super::super::index::parse(&host, &arguments, NodeKind::Blob)
}

/// An artifact family whose head is written verbatim.
fn family(head: &str) -> syn::DeriveInput {
  let head: proc_macro2::TokenStream = head.parse().expect("a head");
  syn::parse_quote! {
    #[ingraph(upstream(node = "video::Keyframe", payload = "pixels"), #head)]
    pub struct Thumbnail {
      #[ingraph(repeated)]
      payload: Vec<u8>,
    }
  }
}

/// The model, or the refusals joined.
fn accepted(head: &str) -> IndexModel {
  blob(&family(head)).expect("the declaration is accepted")
}

fn refusal(head: &str) -> String {
  refused(family(head), NodeKind::Blob)
}

/// Every store word the head declared, in written order.
fn stores(model: &IndexModel) -> Vec<String> {
  model
    .stores
    .iter()
    .map(|engine| engine.word.to_string())
    .collect()
}

// -------------------------------------------------------------------------------------------
// THE STORE WORDS
// -------------------------------------------------------------------------------------------

/// The shipped word reaches the model, and it does not eat the block beside it.
#[test]
fn a_shipped_store_word_is_read_at_the_head() {
  let model = accepted("fs");

  assert_eq!(stores(&model), ["fs"]);
  // The EXCLUSION: `upstream(…)` is still the upstream, not a store called `source`.
  let upstream = &model.source.node;
  assert_eq!(
    quote::quote!(#upstream).to_string().replace(' ', ""),
    "video::Keyframe"
  );
}

/// A word the framework does not ship is admitted — which is what the open vocabulary IS, and it is
/// pinned because closing it is a one-line edit that would compile.
#[test]
fn a_third_party_store_word_is_admitted_at_the_head() {
  assert_eq!(stores(&accepted("s3")), ["s3"]);
}

/// SEVERAL words are PORTABILITY, in written order — the record side's semantics, one axis over.
#[test]
fn several_stores_are_declared_portability_in_written_order() {
  assert_eq!(stores(&accepted("fs, s3, gcs")), ["fs", "s3", "gcs"]);
}

/// A store's own knobs are CARRIED and never read, so a word this crate has never heard of can be
/// tuned without this grammar learning its options.
#[test]
fn a_stores_own_knobs_are_carried_uninterpreted() {
  let model = accepted(r#"s3(bucket = "cards", region = "eu-west-1")"#);

  assert_eq!(stores(&model), ["s3"]);
  let carried = model.stores[0].options.to_string().replace(' ', "");
  assert!(carried.contains("bucket=\"cards\""), "{carried}");
  assert!(carried.contains("region=\"eu-west-1\""), "{carried}");
}

/// DECLARING NONE is legal and means the deployment says instead — a record with no `persist(…)`,
/// one family over.
#[test]
fn a_family_may_declare_no_store_at_all() {
  assert!(stores(&accepted(r#"extension = "png""#)).is_empty());
}

/// The engine `ingraph` ships for the OTHER seam is a category error, and the sentence says which
/// seam it belongs to.
#[test]
fn a_full_texts_engine_on_an_artifact_family_is_refused_by_name() {
  let e = refusal("tantivy");

  assert!(
    e.contains("`tantivy` is the engine `ingraph` ships for"),
    "{e}"
  );
  assert!(e.contains("full-text indexes"), "{e}");
  assert!(
    e.contains("engines(tantivy_of_mine = \"path::To::Store\")"),
    "{e}"
  );
}

/// One word names one store, so a repeat picks nothing.
#[test]
fn a_repeated_store_word_is_refused() {
  let e = refusal("fs, fs");

  assert!(e.contains("`fs` is declared more than once"), "{e}");
  assert!(e.contains("declared PORTABILITY"), "{e}");
}

/// A store is a BLOCK, so the key-value spelling is refused with the two shapes that work.
#[test]
fn a_store_written_as_a_key_value_is_refused() {
  let e = refusal(r#"s3 = "bucket""#);

  assert!(
    e.contains("`s3` is a STORE and a store is declared as a BLOCK"),
    "{e}"
  );
  assert!(e.contains("belongs to the store"), "{e}");
}

/// A multi-segment path names no store, and the sentence says why the word is bare.
#[test]
fn a_path_at_the_head_names_no_store() {
  let e = refusal("app::S3");

  assert!(e.contains("an engine is named by ONE word"), "{e}");
  assert!(e.contains("a NAME the deployment binds"), "{e}");
}

/// FANOUT is DEFERRED and the refusal says so — an author who reached for it is owed the difference
/// between a word that does not exist and a feature that is not built.
#[test]
fn fanout_on_an_artifact_family_names_its_own_deferral() {
  let e = refusal("fs, s3, fanout");

  assert!(e.contains("answers an ADDRESS"), "{e}");
  assert!(e.contains("recorded"), "{e}");
  assert!(e.contains("declared PORTABILITY"), "{e}");
}

// -------------------------------------------------------------------------------------------
// THE EXTENSION WORD — six forms
// -------------------------------------------------------------------------------------------

/// FORM 1, static: one suffix for the whole family.
#[test]
fn a_static_extension_is_one_suffix_for_the_family() {
  let model = accepted(r#"fs, extension = "png""#);
  let suffix = model
    .extension
    .as_ref()
    .and_then(Extension::statik)
    .expect("the static form");

  assert_eq!(suffix.value(), "png");
  // The EXCLUSION: the store beside it is still a store.
  assert_eq!(stores(&model), ["fs"]);
}

/// FORM 2, omitted: extensionless storage, and it is a REAL form rather than an unset field.
#[test]
fn an_omitted_extension_is_extensionless_storage() {
  assert!(accepted("fs").extension.is_none());
}

/// FORM 3, the string column: `from` names the entity's own column and `any_of` fences the output.
#[test]
fn a_string_column_decides_the_suffix_and_any_of_fences_it() {
  let model = accepted(r#"fs, extension(from = "format", any_of = ["png", "jpg"])"#);
  let column = model
    .extension
    .as_ref()
    .and_then(Extension::column)
    .expect("the block form");

  assert_eq!(column.source.field(), "format");
  assert!(
    column.source.enumerated().is_none(),
    "the string road names no type"
  );
  assert_eq!(
    column
      .any_of
      .iter()
      .map(syn::LitStr::value)
      .collect::<Vec<_>>(),
    ["png", "jpg"]
  );
  assert!(column.variants.is_empty());
  assert!(column.with.is_none());
}

/// FORM 4, the enum column: `from(…)` names the column AND its type, written out.
#[test]
fn an_enum_column_names_its_type_explicitly() {
  let model =
    accepted(r#"fs, extension(from(field = "format", type = "app::media::ImageFormat"))"#);
  let column = model
    .extension
    .as_ref()
    .and_then(Extension::column)
    .expect("the block form");

  assert_eq!(column.source.field(), "format");
  let ty = column
    .source
    .enumerated()
    .expect("the enum road names its type");
  assert_eq!(
    quote::quote!(#ty).to_string().replace(' ', ""),
    "app::media::ImageFormat"
  );
  // The full set fences the input by construction, so no `any_of` is owed.
  assert!(column.any_of.is_empty());
}

/// FORM 5, the enum SUBSET: full variant paths, prefix-checked against `from`'s own type.
#[test]
fn an_enum_subset_is_named_by_full_variant_paths() {
  let model = accepted(
    r#"fs, extension(from(field = "format", type = "app::Format"), variants = ["app::Format::Png", "app::Format::Jpg"])"#,
  );
  let column = model
    .extension
    .as_ref()
    .and_then(Extension::column)
    .expect("the block form");

  assert_eq!(
    column
      .variants
      .iter()
      .map(syn::LitStr::value)
      .collect::<Vec<_>>(),
    ["app::Format::Png", "app::Format::Jpg"]
  );
}

/// FORM 6, the hook: the author's own render, composing with BOTH fences.
#[test]
fn a_hook_composes_with_both_fences() {
  let model = accepted(
    r#"fs, extension(from(field = "format", type = "app::Format"), variants = ["app::Format::Png"], any_of = ["png"], with = "app::suffix_of")"#,
  );
  let column = model
    .extension
    .as_ref()
    .and_then(Extension::column)
    .expect("the block form");

  let with = column.with.as_ref().expect("the hook");
  assert_eq!(
    quote::quote!(#with).to_string().replace(' ', ""),
    "app::suffix_of"
  );
  assert_eq!(column.variants.len(), 1);
  assert_eq!(column.any_of.len(), 1);
}

// -------------------------------------------------------------------------------------------
// THE EXTENSION WORD — the refusals
// -------------------------------------------------------------------------------------------

/// The BARE ARRAY, refused by name: a set of suffixes is not a decision.
#[test]
fn a_bare_array_of_suffixes_is_refused_because_it_decides_nothing() {
  let e = refusal(r#"fs, extension = ["png", "jpg"]"#);

  assert!(e.contains("says nothing about which one an entry"), "{e}");
  assert!(e.contains("a set is not a decision"), "{e}");
  assert!(e.contains("from = \"<column>\""), "{e}");
}

/// The parenthesized SINGLE VALUE, refused by name: a single fact stays a key-value.
#[test]
fn a_parenthesized_single_suffix_is_refused() {
  let e = refusal(r#"fs, extension("png")"#);

  assert!(e.contains("is a single fact written as a block"), "{e}");
  assert!(e.contains("`extension = \"png\"`"), "{e}");
}

/// The STRING road owes `any_of`, and the sentence says why an enum road does not.
#[test]
fn a_string_column_without_any_of_is_refused() {
  let e = refusal(r#"fs, extension(from = "format")"#);

  assert!(e.contains("a STRING column needs `any_of`"), "{e}");
  assert!(e.contains("its own variants are the set"), "{e}");
}

/// `variants` is the ENUM road's word — a string column has no variants to name.
#[test]
fn variants_on_a_string_column_is_refused() {
  let e =
    refusal(r#"fs, extension(from = "format", any_of = ["png"], variants = ["app::Format::Png"])"#);

  assert!(
    e.contains("fences the INPUT by naming a type's variants"),
    "{e}"
  );
  assert!(e.contains("a string column has none"), "{e}");
}

/// A variant path under some OTHER type is refused at the string that named it — the half this
/// expansion can check, rustc answering existence at the emitted reference.
#[test]
fn a_variant_of_another_type_is_refused() {
  let e = refusal(
    r#"fs, extension(from(field = "format", type = "app::Format"), variants = ["other::Codec::Png"])"#,
  );

  assert!(e.contains("is not a variant of `app::Format`"), "{e}");
  assert!(e.contains("FULL path under that type"), "{e}");
}

/// The enum road needs BOTH halves, and the refusal names the one that is missing.
#[test]
fn an_enum_road_missing_its_type_is_refused() {
  let e = refusal(r#"fs, extension(from(field = "format"))"#);

  assert!(e.contains("`type` is not written"), "{e}");
  assert!(
    e.contains("a string column takes the shorter spelling"),
    "{e}"
  );
}

/// A block with no column decides nothing.
#[test]
fn an_extension_block_with_no_column_is_refused() {
  let e = refusal(r#"fs, extension(any_of = ["png"])"#);

  assert!(e.contains("`from` is where it names one"), "{e}");
  assert!(e.contains("has nothing to decide by"), "{e}");
}

/// An EMPTY fence admits nothing, which is a family that can store nothing.
#[test]
fn an_empty_fence_is_refused() {
  let e = refusal(r#"fs, extension(from = "format", any_of = [])"#);

  assert!(e.contains("fences nothing in"), "{e}");
  assert!(e.contains("Leave the word out"), "{e}");
}

/// A suffix no address could end with is refused where it was written.
#[test]
fn a_suffix_that_could_not_end_an_address_is_refused() {
  for written in [
    r#"extension = "a/b""#,
    r#"extension = """#,
    r#"extension = "..""#,
  ] {
    let e = refusal(&format!("fs, {written}"));
    assert!(e.contains("cannot end an address"), "{written}: {e}");
    assert!(e.contains("invent a directory level"), "{written}: {e}");
  }
}

/// A bare `extension` says nothing, and the sentence names all three forms it could have meant.
#[test]
fn a_bare_extension_word_is_refused_with_its_three_forms() {
  let e = refusal("fs, extension");

  assert!(e.contains("says nothing on its own"), "{e}");
  assert!(e.contains("LEAVE IT OUT for extensionless storage"), "{e}");
}

/// One family ends its addresses ONE way.
#[test]
fn a_repeated_extension_is_refused() {
  let e = refusal(r#"fs, extension = "png", extension = "jpg""#);

  assert!(e.contains("`extension` is declared more than once"), "{e}");
}

/// An unknown key inside the block names the four that exist.
#[test]
fn an_unknown_entry_in_the_block_names_the_four_keys() {
  let e = refusal(r#"fs, extension(from = "format", any_of = ["png"], suffix = "x")"#);

  assert!(e.contains("unknown entry in `extension(…)`"), "{e}");
  assert!(e.contains("Four keys, each one meaning"), "{e}");
}

/// The word belongs to the ARTIFACT family and is refused by name on the kinds that have no
/// addresses to end.
#[test]
fn extension_on_another_kind_is_refused_by_name() {
  let document: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", body = "text"), dedup(hash), extension = "png")]
    pub struct SearchDocument {
      #[ingraph(searchable)]
      body: String,
    }
  };
  let e = refused(document, NodeKind::Fulltext);

  assert!(
    e.contains("`extension` is an ARTIFACT FAMILY's word"),
    "{e}"
  );
  assert!(e.contains("no addresses to end"), "{e}");
}

// -------------------------------------------------------------------------------------------
// THE DATA WORD — a presence, and the three ways of getting it wrong
// -------------------------------------------------------------------------------------------

/// WRITTEN: the permission reaches the model, and the store beside it is still a store.
#[test]
fn the_data_word_is_read_at_the_head() {
  let model = accepted("fs, data");

  assert!(model.data);
  // The EXCLUSION, and it is the one this word actually risks: on a blob every name the framework
  // does not own is somebody's ENGINE, so a `data` read one arm too late would be swallowed as a
  // store called `data` and this family would declare two.
  assert_eq!(stores(&model), ["fs"]);
}

/// OMITTED: the address is the whole of the answer. A real form rather than an unset field, and the
/// default for the reason every default is one — it is the reading that cannot surprise anybody.
#[test]
fn an_omitted_data_word_serves_the_address_alone() {
  assert!(!accepted("fs").data);
}

/// The word is presence and NOTHING else, so both head words it sits between come through whole —
/// the store is still the store and the suffix is still decided per entry off its column.
#[test]
fn data_eats_neither_the_store_word_nor_the_extension_block() {
  let model = accepted(r#"fs, data, extension(from = "format", any_of = ["png", "jpg"])"#);

  assert!(model.data);
  assert_eq!(stores(&model), ["fs"]);
  let column = model
    .extension
    .as_ref()
    .and_then(Extension::column)
    .expect("the block form");
  assert_eq!(column.source.field(), "format");
  assert_eq!(column.any_of.len(), 2);
}

/// A presence word has no stronger form to reach for, so the second one says what the first said.
#[test]
fn a_repeated_data_word_is_refused() {
  let e = refusal("fs, data, data");

  assert!(e.contains("`data` is declared more than once"), "{e}");
  assert!(e.contains("the word is PRESENCE"), "{e}");
}

/// EVERY shape that would carry something is refused by name — a value, an empty block, a block with
/// a knob in it — because *the bytes may ride along* has nothing left inside it once the address's
/// two other questions have been answered by the words that own them.
#[test]
fn a_data_word_that_carries_anything_is_refused() {
  for written in [r#"data = "inline""#, "data()", "data(limit = 4096)"] {
    let e = refusal(&format!("fs, {written}"));
    assert!(e.contains("`data` is a BARE word"), "{written}: {e}");
    assert!(e.contains("nothing for it to carry"), "{written}: {e}");
  }
}

/// The word belongs to the ARTIFACT family and is refused by name on the kinds that store no object
/// and mint no address to put one beside.
#[test]
fn data_on_another_kind_is_refused_by_name() {
  let document: syn::DeriveInput = syn::parse_quote! {
    #[ingraph(upstream(node = "asr::Segment", body = "text"), dedup(hash), data)]
    pub struct SearchDocument {
      #[ingraph(searchable)]
      body: String,
    }
  };
  let e = refused(document, NodeKind::Fulltext);

  assert!(e.contains("`data` is an ARTIFACT FAMILY's word"), "{e}");
  assert!(e.contains("no bytes to send"), "{e}");
}