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
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
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
//! The flags door's acceptance: what a manifest may say, every shape it may not, and the one place
//! this kind is STRICTER than the vocabulary it mirrors — a bit's number is the author's, always.

use ingraph_codegen::flags::{BitWidth, FlagsModel};
use quote::quote;

/// The pass under test.
///
/// An attribute macro takes its own arguments SEPARATELY from the item it sits on, so the two halves
/// arrive apart here where a derive's suite hands over one piece. [`host::options`] is the wrap that
/// makes the second half read as the `#[ingraph(…)]` the shared grammar already parses, which is why
/// every assertion below is about the GRAMMAR and none of them about the entry point.
///
/// [`host::options`]: crate::host::options
fn parse(input: &syn::DeriveInput, args: proc_macro2::TokenStream) -> syn::Result<FlagsModel> {
  super::parse(input, &crate::host::options(args))
}

/// The refusal a declaration gets, as one string — every rule the pass could still see violated,
/// which is what makes the accumulation assertable.
fn refusal(input: &syn::DeriveInput, args: proc_macro2::TokenStream) -> String {
  parse(input, args)
    .expect_err("the declaration is refused")
    .into_iter()
    .map(|error| error.to_string())
    .collect::<Vec<_>>()
    .join(" | ")
}

/// Every bit a model kept, as Rust spells them.
fn idents(model: &FlagsModel) -> Vec<String> {
  model.bits.iter().map(|bit| bit.ident.to_string()).collect()
}

/// Tokens as they would be written, with the spacing removed.
fn rendered(tokens: impl quote::ToTokens) -> String {
  tokens.to_token_stream().to_string().replace(' ', "")
}

/// **A bare manifest is a NAME, a WIDTH and its bits**, and there is nothing else to say: a flags
/// column stores its bit pattern in every database, so the whole per-face apparatus a vocabulary
/// needs is absent rather than defaulted.
#[test]
fn a_bare_manifest_is_a_name_a_width_and_its_bits() {
  let model = parse(
    &syn::parse_quote! {
      pub enum Disposition {
        Default = 0x1,
        Forced = 0x2,
        HearingImpaired = 0x4,
      }
    },
    quote!(u32),
  )
  .expect("unit variants with explicit values is the whole shape");

  assert_eq!(model.name, "Disposition");
  assert_eq!(model.width, BitWidth::U32);
  assert_eq!(rendered(&model.krate), "::ingraph");
  assert_eq!(rendered(&model.vis), "pub");
  assert_eq!(idents(&model), ["Default", "Forced", "HearingImpaired"]);
  assert_eq!(
    model.bits.iter().map(|bit| bit.value).collect::<Vec<_>>(),
    [0x1, 0x2, 0x4]
  );
  assert_eq!(
    model.bits.iter().map(|bit| bit.word()).collect::<Vec<_>>(),
    ["DEFAULT", "FORCED", "HEARING_IMPAIRED"]
  );
  assert_eq!(
    model.bits.iter().map(|bit| bit.field()).collect::<Vec<_>>(),
    ["default", "forced", "hearingImpaired"]
  );
}

/// **One `rename` moves the WORD and the wire FIELD together**, because they are two readings of one
/// declaration rather than two declarations — which is also why a flags bit takes one rename where a
/// vocabulary variant takes a per-face block.
#[test]
fn a_rename_moves_the_word_and_the_wire_field_together() {
  let model = parse(
    &syn::parse_quote! {
      enum Disposition {
        Default = 0x1,
        #[ingraph(rename = "COMMENT")]
        Commentary = 0x2,
      }
    },
    quote!(u32),
  )
  .expect("a bit names the word it is spelled with");

  assert_eq!(model.bits[1].rename.as_deref(), Some("COMMENT"));
  assert_eq!(model.bits[1].word(), "COMMENT");
  assert_eq!(
    model.bits[1].field(),
    "comment",
    "the field follows the word, not the identifier"
  );
  assert_eq!(model.bits[0].word(), "DEFAULT");
}

/// A bit is written as a LITERAL or as a shift of one, and the shift is the spelling a wide
/// declaration reaches for.
#[test]
fn a_bit_may_be_written_as_a_shift() {
  let model = parse(
    &syn::parse_quote! {
      enum Disposition {
        Default = 1 << 0,
        Forced = (1 << 1),
        HearingImpaired = 1 << 2,
        Commentary = 0b1000,
      }
    },
    quote!(u32),
  )
  .expect("a shift of a literal is a value this door can evaluate");

  assert_eq!(
    model.bits.iter().map(|bit| bit.value).collect::<Vec<_>>(),
    [0x1, 0x2, 0x4, 0x8]
  );
}

/// Every width the carrier table holds is one a declaration may write, and the width is the
/// ATTRIBUTE's own argument — a `#[repr(…)]` would describe a type that does not survive the
/// expansion.
#[test]
fn every_width_the_table_carries_is_one_a_declaration_may_write() {
  for width in BitWidth::ALL {
    let word = syn::Ident::new(width.as_str(), proc_macro2::Span::call_site());
    let model = parse(
      &syn::parse_quote! {
        enum Channel { Left = 0x1 }
      },
      quote!(#word),
    )
    .expect("every width this kind carries is one a declaration may write");
    assert_eq!(model.width, width, "{}", width.as_str());
  }
}

/// The `crate` option is the shared parsing layer's, and it behaves here exactly as it does on a
/// record — which is the whole reason that layer is separate.
#[test]
fn the_crate_path_overrides_the_default() {
  let model = parse(
    &syn::parse_quote! {
      enum Channel { Left = 0x1 }
    },
    quote!(u16, crate = "shim::ingraph"),
  )
  .expect("a re-export shim is a path like any other");

  assert_eq!(rendered(&model.krate), "shim::ingraph");
  assert_eq!(model.width, BitWidth::U16);
}

/// **The forwarding law, at both grains.** What an author wrote about their type stays true of the
/// type `bitflags!` mints, and a bit's doc comment reaches the `const` — so the model carries the
/// attributes verbatim, in order, minus the markers this door consumed.
#[test]
fn the_authors_own_attributes_survive_on_the_item_and_on_a_bit() {
  let model = parse(
    &syn::parse_quote! {
      /// The dispositions a track may carry.
      #[derive(Debug, Clone, Copy)]
      #[non_exhaustive]
      pub enum Disposition {
        /// The default track for its kind.
        #[ingraph(rename = "DEFAULT")]
        Default = 0x1,
      }
    },
    quote!(u32),
  )
  .expect("attributes this door does not own are not this door's to read");

  let item = model.attrs.iter().map(rendered).collect::<Vec<_>>();
  assert_eq!(
    item,
    [
      "#[doc=r\"Thedispositionsatrackmaycarry.\"]",
      "#[derive(Debug,Clone,Copy)]",
      "#[non_exhaustive]"
    ]
  );

  let bit = model.bits[0].attrs.iter().map(rendered).collect::<Vec<_>>();
  assert_eq!(
    bit,
    ["#[doc=r\"Thedefaulttrackforitskind.\"]"],
    "the marker this door read is gone, and nothing else is"
  );
}

/// **The width is REQUIRED**, because there is no honest default: a declaration's bits are somebody's
/// stored integer and the width is the column they live in.
#[test]
fn refuses_a_declaration_that_names_no_width() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1 }
    },
    quote!(),
  );
  assert!(refused.contains("names its WIDTH"), "{refused}");
  assert!(refused.contains("`u8`, `u16`, `u32`"), "{refused}");
}

/// **A width-shaped word this kind does not carry gets the TABLE's sentence**, not the grammar's:
/// what is wrong with `u64` is not that it is unrecognised, and what is wrong with `i32` is that a
/// sign bit is not a flag.
#[test]
fn refuses_a_width_the_carrier_table_does_not_hold() {
  for word in super::UNCARRIED {
    let name = syn::Ident::new(word, proc_macro2::Span::call_site());
    let refused = refusal(
      &syn::parse_quote! {
        enum Disposition { Default = 0x1 }
      },
      quote!(#name),
    );
    assert!(
      refused.contains("is not a width a flags set can be stored at"),
      "{word}: {refused}"
    );
  }

  let signed = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1 }
    },
    quote!(i32),
  );
  assert!(signed.contains("`iN`'s top bit is negative"), "{signed}");
}

/// One column has one width, so a second is refused rather than silently overriding the first.
#[test]
fn refuses_a_width_declared_twice() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1 }
    },
    quote!(u32, u16),
  );
  assert!(
    refused.contains("the width is declared more than once"),
    "{refused}"
  );
}

/// An entry nobody reads is a rule its author believes they declared, so an unrecognised one is
/// refused rather than ignored — and the sentence names everything this door does take.
#[test]
fn refuses_an_entry_a_flags_declaration_does_not_take() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1 }
    },
    quote!(u32, sqlite(text)),
  );
  assert!(
    refused.contains("unknown entry in `#[ingraph::flags(…)]`"),
    "{refused}"
  );
}

/// One `crate` names one crate, and the shared layer's refusal arrives through this door unchanged.
#[test]
fn refuses_a_crate_declared_twice_and_a_crate_that_is_not_a_path() {
  let twice = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1 }
    },
    quote!(u32, crate = "a", crate = "b"),
  );
  assert!(
    twice.contains("`crate` is declared more than once"),
    "{twice}"
  );

  let unquoted = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1 }
    },
    quote!(u32, crate = ingraph),
  );
  assert!(
    unquoted.contains("must be a path to the `ingraph` crate"),
    "{unquoted}"
  );
}

/// **The options belong in the attribute's own parentheses.** A block left beside the declaration is
/// the derive's spelling: the rewrite would strip it and every rule it carried would vanish without a
/// word, so it is named as a migration rather than dropped.
#[test]
fn refuses_an_option_block_left_beside_the_declaration() {
  let refused = refusal(
    &syn::parse_quote! {
      #[ingraph(crate = "shim::ingraph")]
      enum Disposition { Default = 0x1 }
    },
    quote!(u32),
  );
  assert!(
    refused.contains("options are the MACRO's arguments"),
    "{refused}"
  );
  assert!(
    refused.contains("`#[ingraph::flags(u32)]`"),
    "the sentence names THIS door and not the record's: {refused}"
  );
}

/// A manifest is a set of NAMES with VALUES, which is what an enum spells and what a struct body
/// cannot hold — the expansion is a `bitflags!` struct either way.
#[test]
fn refuses_a_declaration_that_is_not_an_enum() {
  let refused = refusal(
    &syn::parse_quote! {
      struct Disposition { bits: u32 }
    },
    quote!(u32),
  );
  assert!(refused.contains("supports enums only"), "{refused}");
}

#[test]
fn refuses_an_enum_with_no_variants() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {}
    },
    quote!(u32),
  );
  assert!(refused.contains("declares no flags"), "{refused}");
}

/// A bit is a NAME and a NUMBER, and every offender is named rather than only the first — the
/// accumulation the shared error layer exists for.
#[test]
fn refuses_every_variant_that_carries_data() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Shape { Unit = 0x1, Tuple(u8), Named { width: u8 } }
    },
    quote!(u32),
  );
  assert!(refused.contains("`Tuple` carries data"), "{refused}");
  assert!(refused.contains("`Named` carries data"), "{refused}");
}

/// The expansion is one `bitflags!` type with one bit table, and a parameter has no type until it is
/// substituted — so all three ways of writing one are refused for the one reason.
#[test]
fn refuses_a_generic_flags_set() {
  for input in [
    syn::parse_quote! {
      enum Disposition<T> { Default = 0x1 }
    },
    syn::parse_quote! {
      enum Disposition<'a> { Default = 0x1 }
    },
    syn::parse_quote! {
      enum Disposition where Self: Sized { Default = 0x1 }
    },
  ] {
    let refused = refusal(&input, quote!(u32));
    assert!(refused.contains("generic flags sets"), "{refused}");
  }
}

/// **THE REFUSAL THAT IS THIS KIND'S ALONE.** A bit with no value would be numbered from its
/// POSITION, so reordering a list of names — the most ordinary edit there is — would rewrite every
/// stored row in silence. The vocabulary kind defaults a discriminant because a reordered enum still
/// stores what it stored; this one cannot.
#[test]
fn refuses_a_bit_that_names_no_number() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default, Forced }
    },
    quote!(u32),
  );
  assert!(refused.contains("`Default` names no bit"), "{refused}");
  assert!(refused.contains("`Forced` names no bit"), "{refused}");
  assert!(refused.contains("reordering the declaration"), "{refused}");
}

/// `0` sets no bit, so it is not a flag — it is the EMPTY set, and every flags type already has one.
#[test]
fn refuses_a_bit_whose_value_is_zero() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { None = 0, Default = 0x1 }
    },
    quote!(u32),
  );
  assert!(refused.contains("`None` is `0`"), "{refused}");
  assert!(refused.contains("EMPTY set"), "{refused}");
}

/// A value past the declared width would be TRUNCATED into a bit the declaration did not write, so
/// the ceiling is the width's and the message names the highest bit it holds.
#[test]
fn refuses_a_value_past_the_declared_width() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1, Ninth = 0x100 }
    },
    quote!(u8),
  );
  assert!(refused.contains("`0x100` does not fit `u8`"), "{refused}");
  assert!(refused.contains("numbers 8 bits"), "{refused}");
  assert!(refused.contains("`0x80`"), "{refused}");

  parse(
    &syn::parse_quote! {
      enum Disposition { Ninth = 0x100 }
    },
    quote!(u16),
  )
  .expect("the same value is the ninth bit of a wider column");
}

/// **A composite mask is refused in v1**, which `bitflags` itself allows: a mask has no per-flag
/// boolean a client could ask for and no single answer to *is it set*.
#[test]
fn refuses_a_composite_mask() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1, Forced = 0x2, Either = 0x3 }
    },
    quote!(u32),
  );
  assert!(refused.contains("`0x3` sets 2 bits"), "{refused}");
  assert!(refused.contains("a declared flag is ONE bit"), "{refused}");
}

/// The grammar is literals and shifts of literals and no wider, because a value this pass cannot see
/// is one whose single-bit-ness it would have to take on faith — which is the guarantee the whole
/// kind rests on.
#[test]
fn refuses_a_value_this_door_cannot_evaluate() {
  for expression in [
    quote!(FORCED_BIT),
    quote!(1 + 1),
    quote!(Self::DEFAULT.bits()),
    quote!(1 << 128),
  ] {
    let refused = refusal(
      &syn::parse_quote! {
        enum Disposition { Default = #expression }
      },
      quote!(u32),
    );
    assert!(
      refused.contains("an integer LITERAL or a shift of one"),
      "{expression}: {refused}"
    );
  }
}

/// Two names for one bit is one value that reads back as two flags, and a client asking for either
/// would be asking the same question.
#[test]
fn refuses_two_bits_on_one_value() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1, Primary = 1 << 0 }
    },
    quote!(u32),
  );
  assert!(
    refused.contains("`Primary` and `Default` are both bit `0x1`"),
    "{refused}"
  );
}

/// One word spelling two bits is a text form that reads back as two of them — and a shared word is
/// necessarily a shared field, so both sentences arrive.
#[test]
fn refuses_two_bits_on_one_word() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = "FORCED")]
        Default = 0x1,
        Forced = 0x2,
      }
    },
    quote!(u32),
  );
  assert!(
    refused.contains("`Forced` and `Default` are both `FORCED` as a word"),
    "{refused}"
  );
}

/// The wire field is the word under GraphQL's own casing, so two DIFFERENT words can case into one
/// field — which is the collision only this second pass sees.
#[test]
fn refuses_two_bits_on_one_wire_field() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = "FOO_BAR")]
        Default = 0x1,
        #[ingraph(rename = "FooBar")]
        Forced = 0x2,
      }
    },
    quote!(u32),
  );
  assert!(
    refused.contains("`Forced` and `Default` are both `fooBar` as a wire field"),
    "{refused}"
  );
  assert!(
    !refused.contains("as a word"),
    "two spellings are two words: {refused}"
  );
}

/// A word is held to GraphQL's own Name production, because nothing downstream refuses one: the
/// schema builds and the SDL it exports is not parseable GraphQL.
#[test]
fn refuses_a_rename_that_is_not_a_graphql_name() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = "hearing impaired")]
        HearingImpaired = 0x1,
      }
    },
    quote!(u32),
  );
  assert!(
    refused.contains("`hearing impaired` is not a GraphQL name"),
    "{refused}"
  );
}

/// **A flag's word becomes a Rust IDENTIFIER as well as a wire one**, which is the second grammar
/// this kind alone has to hold a `rename` to.
///
/// Every other rename in this crate lands in a string literal. This one lands in the emitted
/// `const`'s name too, so a Rust KEYWORD would reach `bitflags!` as `const type = 0x2u32;` — a
/// syntax error inside somebody else's expansion, at a span the declaration cannot edit. The
/// GraphQL production admits keywords, so it is not the whole gate.
#[test]
fn refuses_a_rename_that_is_a_rust_keyword() {
  for keyword in ["type", "const", "move", "fn"] {
    let word = syn::LitStr::new(keyword, proc_macro2::Span::call_site());
    let refused = refusal(
      &syn::parse_quote! {
        enum Disposition {
          #[ingraph(rename = #word)]
          Default = 0x1,
        }
      },
      quote!(u32),
    );
    assert!(
      refused.contains("is not usable as a Rust identifier"),
      "`{keyword}`: {refused}"
    );
  }
}

/// A word that is legal in BOTH grammars passes, so the second check refuses nothing the first
/// already admitted for a good reason.
#[test]
fn a_rename_legal_in_both_grammars_is_taken() {
  let model = parse(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = "TYPE_HINT")]
        Default = 0x1,
      }
    },
    quote!(u32),
  )
  .expect("`TYPE_HINT` is a GraphQL name and a Rust identifier");

  assert_eq!(model.bits[0].word(), "TYPE_HINT");
  assert_eq!(model.bits[0].field(), "typeHint");
}

/// The TYPE's own name is held to the same production, and unconditionally — the wire face is
/// emitted for every declaration, so there is no build for the check to be premature for.
#[test]
fn refuses_a_type_name_that_is_not_a_graphql_name() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Dispositión { Default = 0x1 }
    },
    quote!(u32),
  );
  assert!(refused.contains("is not a GraphQL name"), "{refused}");
}

/// One declaration names one word, and a `rename` that is not a string is refused at its own span
/// rather than read as something else.
#[test]
fn refuses_a_rename_declared_twice_or_written_as_something_else() {
  let twice = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = "A", rename = "B")]
        Default = 0x1,
      }
    },
    quote!(u32),
  );
  assert!(
    twice.contains("`rename` is declared more than once"),
    "{twice}"
  );

  let unquoted = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = DEFAULT)]
        Default = 0x1,
      }
    },
    quote!(u32),
  );
  assert!(unquoted.contains("must be a string literal"), "{unquoted}");
}

/// A bit takes `rename = "…"` and nothing else, because a flags column stores its BIT PATTERN in
/// every database — the wire is the only face with a word for a per-face block to move.
#[test]
fn refuses_an_entry_a_bit_does_not_take() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(sqlite(rename = "d"))]
        Default = 0x1,
      }
    },
    quote!(u32),
  );
  assert!(
    refused.contains("unknown entry in `#[ingraph(…)]` on a flag"),
    "{refused}"
  );
}

/// **One compile reports the whole manifest.** Four bits are wrong in four different ways and all
/// four are named, which is what the accumulating error layer buys: a declaration with four mistakes
/// is one compile, not four.
#[test]
fn one_pass_reports_every_bit_it_can_still_see() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {
        Default,
        Forced = 0,
        HearingImpaired = 0x3,
        Commentary = 0x100,
        Original = 0x8,
      }
    },
    quote!(u8),
  );

  assert!(refused.contains("`Default` names no bit"), "{refused}");
  assert!(refused.contains("`Forced` is `0`"), "{refused}");
  assert!(refused.contains("`0x3` sets 2 bits"), "{refused}");
  assert!(refused.contains("`0x100` does not fit `u8`"), "{refused}");
  assert_eq!(
    refused.matches(" | ").count(),
    3,
    "four refusals and no more — the legal bit is not one of them: {refused}"
  );
}

/// The grammar mistake and the shape mistake come out of ONE pass, from the two halves of the door
/// that do not know about each other.
#[test]
fn one_pass_reports_the_grammar_and_the_shape_together() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Tuple(u8) }
    },
    quote!(u32, sqlite),
  );
  assert!(
    refused.contains("unknown entry in `#[ingraph::flags(…)]`"),
    "{refused}"
  );
  assert!(refused.contains("`Tuple` carries data"), "{refused}");
}

/// **A MIRROR names its upstream and restates it, and nothing else about the declaration moves.**
///
/// The two-mode law at the model: a set that mirrors carries an upstream path and, per bit, whichever
/// upstream `const` it claims — and its own words, fields and numbers are what they would have been
/// with no upstream named at all.
#[test]
fn a_mirror_names_an_upstream_and_keeps_its_own_words() {
  let model = parse(
    &syn::parse_quote! {
      pub enum Disposition {
        Default = 0x1,
        #[ingraph(rename = "HEARING_IMPAIRED")]
        Hi = 0x4,
      }
    },
    quote!(u32, remote = "upstream::Disposition"),
  )
  .expect("a mirror is a manifest with an upstream named beside it");

  assert_eq!(
    rendered(model.remote.as_ref().expect("the upstream")),
    "upstream::Disposition"
  );
  assert_eq!(
    model
      .bits
      .iter()
      .map(|bit| bit.upstream().to_string())
      .collect::<Vec<_>>(),
    ["DEFAULT", "HEARING_IMPAIRED"],
    "the knob names the upstream `const`, and a bit that shares its name inherits it"
  );
  assert_eq!(
    model.bits.iter().map(|bit| bit.word()).collect::<Vec<_>>(),
    ["DEFAULT", "HI"],
    "and moves no word of this declaration's"
  );
  assert_eq!(
    model.bits.iter().map(|bit| bit.field()).collect::<Vec<_>>(),
    ["default", "hi"]
  );
  assert!(model.bits.iter().all(|bit| bit.rename.is_none()));
}

/// **A declaration naming no upstream carries none**, which is the other half of the same law: the
/// axis costs a set of this crate's own exactly nothing.
#[test]
fn a_declaration_naming_no_upstream_carries_none() {
  let model = parse(
    &syn::parse_quote! {
      pub enum Disposition {
        #[ingraph(rename = "COMMENT")]
        Commentary = 0x8,
      }
    },
    quote!(u32),
  )
  .expect("the ordinary declaration");

  assert!(model.remote.is_none());
  assert!(model.bits[0].upstream.is_none());
  assert_eq!(
    model.bits[0].word(),
    "COMMENT",
    "and its `rename` still moves the word"
  );
}

/// **On a mirror, `rename` is an IDENTIFIER**, because what it names is a `const` — so a word is
/// refused with the sentence that says what the knob is FOR, rather than with the declared mode's
/// sentence about GraphQL names.
#[test]
fn refuses_a_mirrors_rename_that_names_no_const() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = "not a const")]
        Default = 0x1,
      }
    },
    quote!(u32, remote = "upstream::Disposition"),
  );
  assert!(
    refused.contains("it names the UPSTREAM `const` this bit restates"),
    "{refused}"
  );
}

/// One declaration mirrors one flags set, and one bit restates one `const`.
#[test]
fn refuses_a_second_upstream() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition {
        #[ingraph(rename = "DEFAULT", rename = "FORCED")]
        Default = 0x1,
      }
    },
    quote!(u32, remote = "a::One", remote = "b::Other"),
  );
  assert!(
    refused.contains("one declaration mirrors one flags set"),
    "{refused}"
  );
  assert!(
    refused.contains("one bit restates one upstream `const`"),
    "{refused}"
  );
}

/// The upstream is a PATH, in a string literal — re-parsed at the door so a value that cannot BE a
/// type is refused at this token rather than inside an expansion.
#[test]
fn refuses_an_upstream_that_is_not_a_path() {
  let refused = refusal(
    &syn::parse_quote! {
      enum Disposition { Default = 0x1 }
    },
    quote!(u32, remote = "not a path"),
  );
  assert!(
    refused.contains("must be a path to the flags set this one mirrors"),
    "{refused}"
  );
}

/// **`graphql(rename = "…")` MOVES THE WHOLE SDL FAMILY AND NOTHING IN RUST** — the rename-parity
/// ruling's row for this device.
///
/// Three published names come off one string: the object face takes it, the operand scalar is
/// `<it>Input` and the filter is `<it>Filter`. So the assertion worth making is that ONE word moved
/// all three and the `bitflags!` type moved with none of them.
#[test]
fn the_wire_name_is_the_declarations_and_the_bitflags_type_keeps_its_own() {
  let model = parse(
    &syn::parse_quote! {
      pub enum TrackDispositionFlags { Default = 0x1, Forced = 0x2 }
    },
    quote::quote!(u32, graphql(rename = "TrackDisposition")),
  )
  .expect("a width and a name");

  assert_eq!(model.sdl_name(), "TrackDisposition");
  assert_eq!(
    model.name, "TrackDispositionFlags",
    "the minted Rust type keeps the declaration's own name"
  );
}

/// A declaration that writes no word emits what it emitted before the word existed.
#[test]
fn the_wire_name_defaults_to_the_rust_name() {
  let model = parse(
    &syn::parse_quote! {
      pub enum Disposition { Default = 0x1 }
    },
    quote::quote!(u32),
  )
  .expect("a width is the whole requirement");

  assert_eq!(model.wire_name, None);
  assert_eq!(model.sdl_name(), "Disposition");
}

/// The block's word rides GraphQL's Name grammar and no other fence — a Rust KEYWORD is ordinary
/// here, where a BIT's word is not: a bit becomes a `const` a caller writes `Self::…` to reach, and
/// a type name reaches only a registry entry.
#[test]
fn the_wire_name_rides_the_name_grammar_alone() {
  let refused = refusal(
    &syn::parse_quote! {
      pub enum Disposition { Default = 0x1 }
    },
    quote::quote!(u32, graphql(rename = "Not A Name")),
  );
  assert!(refused.contains("is not a GraphQL name"), "{refused}");

  let keyword = parse(
    &syn::parse_quote! {
      pub enum Disposition { Default = 0x1 }
    },
    quote::quote!(u32, graphql(rename = "type")),
  )
  .expect("a schema name has no Rust item behind it");
  assert_eq!(keyword.sdl_name(), "type");
}

/// One declaration, one schema name — and an empty block names none, which the shared block reader
/// answers with the sentence naming what it is for.
#[test]
fn refuses_a_wire_name_written_twice_or_not_at_all() {
  let twice = refusal(
    &syn::parse_quote! {
      pub enum Disposition { Default = 0x1 }
    },
    quote::quote!(u32, graphql(rename = "A", rename = "B")),
  );
  assert!(
    twice.contains("`rename` is declared more than once"),
    "{twice}"
  );

  let empty = refusal(
    &syn::parse_quote! {
      pub enum Disposition { Default = 0x1 }
    },
    quote::quote!(u32, graphql),
  );
  assert!(empty.contains("`graphql(…)` needs `rename"), "{empty}");
}