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
//! Validating a MUTATION NODE's declaration into the model the emitter consumes.
//!
//! A mutation node is a struct whose FIELDS are the vocabulary an app can say to one source. Each
//! field is an exchange — the type answers what is sent, what comes back and how it fails — and the
//! words beside it answer everything a type cannot: which handler runs it, what the wire calls it,
//! what the handler was granted, and which of the three failure shapes its signature wears.
//!
//! # The field-level vocabulary is exactly TWO words
//!
//! `rename` is the SKIN and `handler` is the BEHAVIOUR, and every other fact lives inside the
//! handler block because every other fact is part of one signature:
//!
//! | segment | word | what it decides |
//! |---|---|---|
//! | who | `path = "…"` | the function that runs |
//! | which face | `async` | whether it is awaited |
//! | the arguments | `context(resource("…"), …)` | what it is handed besides the request |
//! | the return's failing half | `error(…)` | which of the three signatures it wears |
//!
//! `error` sits INSIDE `handler` rather than beside it, and that is the ruling: a failure with no
//! handler to belong to is a failure nothing renders, and the block is the signature.
//!
//! # What this pass can see, and what it cannot
//!
//! It sees TOKENS. So it enforces the SHAPE — a named-field struct, no generic parameter, a handler
//! on every field, one of `type`/`message` and not both — and nothing about whether the paths it was
//! handed resolve to anything. That half is the EMISSION's, where the compiler can see it: the
//! command arm's payload is written as `<FieldTy as Mutation>::Request`, so a field whose type is not
//! an exchange is `E0277` at the field itself.

use ingraph_codegen::{
  model::GraphqlKind,
  mutation::{DeclaredError, ExchangeModel, HandlerModel, MutationModel},
};

use crate::{attribute, errors::Errors, value};

#[cfg(test)]
mod tests;

/// Validate a decorated declaration into the model the emitter consumes.
///
/// # Errors
/// A [`syn::Error`] carrying EVERY rule the pass could still see violated, each spanned at the token
/// that violated it, so one compile reports the whole declaration's problems.
pub(crate) fn parse(
  input: &syn::DeriveInput,
  arguments: &[syn::Attribute],
) -> syn::Result<MutationModel> {
  let mut errors = Errors::default();
  crate::host::refuse_a_moved_option_block(&input.attrs, &mut errors);
  let (krate, graphql) = options(arguments, &mut errors);
  concrete(&input.generics, &mut errors);

  let fields = match named_fields(input) {
    Ok(fields) => fields,
    Err(terminal) => return Err(errors.seal(terminal)),
  };

  let exchanges = fields
    .named
    .iter()
    .filter_map(|field| {
      let name = field.ident.clone()?;
      Some(exchange(field, name, &mut errors))
    })
    .collect();

  errors.into_result(MutationModel {
    krate: krate.unwrap_or_else(|| syn::parse_quote!(::ingraph)),
    name: input.ident.clone(),
    vis: input.vis.clone(),
    graphql,
    exchanges,
  })
}

/// Walk the declaration-level attribute: where `ingraph` lives, and which wires this node is dressed
/// for.
fn options(attrs: &[syn::Attribute], errors: &mut Errors) -> (Option<syn::Path>, Vec<GraphqlKind>) {
  let mut krate: Option<syn::Path> = None;
  let mut graphql: Vec<GraphqlKind> = Vec::new();
  let mut graphql_at: Option<syn::Path> = None;

  attribute::walk(attrs, errors, |meta, errors| {
    // `crate` is a keyword; syn's nested-meta path parser takes it with `Ident::parse_any`, so it
    // arrives here as an ordinary one-segment path.
    if meta.path.is_ident("crate") {
      match value::parse_literal::<syn::Path>(
        &meta,
        "`#[ingraph(crate = \"…\")]` must be a path to the `ingraph` crate, in a string literal",
      ) {
        Ok(path) => {
          if krate.replace(path).is_some() {
            errors.push(syn::Error::new_spanned(
              &meta.path,
              "`crate` is declared more than once — one declaration names one crate",
            ));
          }
        }
        Err(e) => refuse_value(&meta, e, errors),
      }
      return Ok(());
    }

    if meta.path.is_ident("graphql") {
      if graphql_at.is_some() {
        errors.push(syn::Error::new_spanned(
          &meta.path,
          "`graphql(…)` is declared more than once — one block holds every backend, and a second \
           one could only repeat or contradict the first",
        ));
        attribute::skip_entry(&meta);
        return Ok(());
      }
      graphql_at = Some(meta.path.clone());
      return backends(&meta, &mut graphql, errors);
    }

    errors.push(attribute::unknown(
      &meta,
      "unknown entry in `#[ingraph::mutation(…)]` — it takes `graphql(…)` and `crate = \"…\"`. \
       WHAT this node's fields are is written on the fields themselves, and which source mounts it \
       is that source's own `mutation(node = \"…\")` word",
      &["graphql", "crate"],
    ));
    Ok(())
  });

  (krate, graphql)
}

/// The `graphql(…)` block — one word per wire this node is dressed for.
fn backends(
  meta: &syn::meta::ParseNestedMeta<'_>,
  graphql: &mut Vec<GraphqlKind>,
  errors: &mut Errors,
) -> syn::Result<()> {
  let walked = attribute::options(meta, |inner| {
    let Some(kind) = crate::parse::graphql_kind(&inner.path) else {
      errors.push(attribute::unknown(
        &inner,
        "unknown backend in `graphql(…)` — a wire face is one backend's impls, and a word naming \
         none of them names no skin",
        &GraphqlKind::ALL.map(GraphqlKind::as_str),
      ));
      return Ok(());
    };
    if graphql.contains(&kind) {
      errors.push(syn::Error::new_spanned(
        &inner.path,
        format!(
          "`{kind}` is declared more than once in `graphql(…)` — one word per backend, because a \
           backend has ONE skin and a second word could only re-describe it",
          kind = kind.as_str(),
        ),
      ));
      attribute::skip_entry(&inner);
      return Ok(());
    }
    graphql.push(kind);
    Ok(())
  });

  if graphql.is_empty() {
    errors.push(syn::Error::new_spanned(
      &meta.path,
      format!(
        "`graphql` names no backend — write `graphql({first})`. Without the word this node still \
         emits its whole Rust surface: the command vocabulary, the row a source mounts it through \
         and the declaration record are all there, and what the block adds is a schema over them",
        first = GraphqlKind::ALL[0].as_str(),
      ),
    ));
  }
  walked
}

/// ONE field, read as the exchange it is.
fn exchange(field: &syn::Field, name: syn::Ident, errors: &mut Errors) -> ExchangeModel {
  let mut rename: Option<syn::LitStr> = None;
  let mut handler: Option<HandlerModel> = None;
  let mut handler_at: Option<syn::Path> = None;

  attribute::walk(&field.attrs, errors, |meta, errors| {
    if meta.path.is_ident("rename") {
      match value::literal(&meta, RENAME_WORD) {
        Ok(word) => {
          crate::wire::refuse_invalid_name(&word.value(), &word, errors);
          attribute::set_once(
            &mut rename,
            word,
            &meta.path,
            "`rename` is declared more than once on this exchange — one field, one published word",
            errors,
          );
        }
        Err(e) => refuse_value(&meta, e, errors),
      }
      return Ok(());
    }

    if meta.path.is_ident("handler") {
      if handler_at.is_some() {
        errors.push(syn::Error::new_spanned(
          &meta.path,
          "`handler` is declared more than once on this exchange — one field is ONE thing an app \
           can say, so a second handler could only be a second behaviour for one command",
        ));
        attribute::skip_entry(&meta);
        return Ok(());
      }
      handler_at = Some(meta.path.clone());
      handler = handler_block(&meta, errors);
      return Ok(());
    }

    errors.push(attribute::unknown(
      &meta,
      "unknown entry in `#[ingraph(…)]` on an exchange — a field takes `rename = \"…\"` (the wire's \
       skin) and `handler(…)` (the behaviour), and everything else about the signature lives INSIDE \
       the handler block",
      &["rename", "handler"],
    ));
    Ok(())
  });

  let handler = handler.unwrap_or_else(|| {
    if handler_at.is_none() {
      errors.push(syn::Error::new_spanned(&name, no_handler(&name)));
    }
    // A field whose handler could not be read still has to become a row, so the rest of the
    // declaration is checked rather than abandoned at the first bad field. Nothing is emitted from a
    // refused parse, so this placeholder never reaches a token stream.
    HandlerModel {
      path: syn::parse_quote!(__ingraph_unresolved_handler),
      awaited: false,
      context: Vec::new(),
      error: None,
    }
  });

  ExchangeModel {
    field: name,
    ty: field.ty.clone(),
    rename,
    handler,
  }
}

/// The `handler` word in either of its two spellings.
///
/// `handler = "path"` is the whole block when a signature has nothing else to say — the plain form,
/// and the one most exchanges take. `handler(path = "…", …)` is the same word with the rest of the
/// signature written out.
fn handler_block(
  meta: &syn::meta::ParseNestedMeta<'_>,
  errors: &mut Errors,
) -> Option<HandlerModel> {
  if attribute::has_value(meta) {
    return match value::parse_literal::<syn::Path>(meta, HANDLER_PATH) {
      Ok(path) => Some(HandlerModel {
        path,
        awaited: false,
        context: Vec::new(),
        error: None,
      }),
      Err(e) => {
        refuse_value(meta, e, errors);
        None
      }
    };
  }

  if !attribute::has_block(meta) || attribute::empty_group(meta) {
    errors.push(attribute::unknown(meta, HANDLER_EMPTY, &[]));
    return None;
  }

  let mut path: Option<syn::Path> = None;
  // The `path` WORD, whether or not its value could be read: a bad value has already earned its one
  // error, and the missing-word sentence below would be that error's echo.
  let mut path_at: Option<syn::Path> = None;
  let mut awaited: Option<syn::Path> = None;
  let mut context: Vec<syn::Path> = Vec::new();
  let mut context_at: Option<syn::Path> = None;
  let mut error: Option<DeclaredError> = None;
  let mut error_at: Option<syn::Path> = None;

  let walked = meta.parse_nested_meta(|inner| {
    if inner.path.is_ident("path") {
      path_at = Some(inner.path.clone());
      match value::parse_literal::<syn::Path>(&inner, HANDLER_PATH) {
        Ok(written) => attribute::set_once(
          &mut path,
          written,
          &inner.path,
          "`path` is declared more than once in `handler(…)` — one exchange runs one function",
          errors,
        ),
        Err(e) => refuse_value(&inner, e, errors),
      }
      return Ok(());
    }

    if inner.path.is_ident("async") {
      attribute::set_once(
        &mut awaited,
        inner.path.clone(),
        &inner.path,
        "`async` is declared more than once in `handler(…)` — one handler wears one face",
        errors,
      );
      attribute::skip_entry(&inner);
      return Ok(());
    }

    if inner.path.is_ident("context") {
      if context_at.is_some() {
        errors.push(syn::Error::new_spanned(
          &inner.path,
          "`context(…)` is declared more than once in `handler(…)` — one block holds every \
           resource this handler is granted, and a second one could only add to a list that is \
           already there",
        ));
        attribute::skip_entry(&inner);
        return Ok(());
      }
      context_at = Some(inner.path.clone());
      return granted(&inner, &mut context, errors);
    }

    if inner.path.is_ident("error") {
      if error_at.is_some() {
        errors.push(syn::Error::new_spanned(
          &inner.path,
          "`error(…)` is declared more than once in `handler(…)` — one exchange fails one way, and \
           the shape of that way IS the handler's return type",
        ));
        attribute::skip_entry(&inner);
        return Ok(());
      }
      error_at = Some(inner.path.clone());
      error = declared_error(&inner, errors);
      return Ok(());
    }

    errors.push(attribute::unknown(
      &inner,
      "unknown entry in `handler(…)` — the block IS the signature, and it takes `path = \"…\"` \
       (who), `async` (which face), `context(…)` (the arguments) and `error(…)` (the failing half \
       of the return)",
      &["path", "async", "context", "error"],
    ));
    Ok(())
  });
  if let Err(e) = walked {
    errors.push(e);
  }

  let path = match path {
    Some(path) => path,
    None => {
      if path_at.is_none() {
        errors.push(syn::Error::new_spanned(&meta.path, HANDLER_NO_PATH));
      }
      return None;
    }
  };

  Some(HandlerModel {
    path,
    awaited: awaited.is_some(),
    context,
    error,
  })
}

/// The `context(…)` block — the resources this handler is handed besides the request.
///
/// Every entry is a `resource("…")` line, and a word that is not one is refused rather than ignored:
/// a handler's arguments are the whole of what it can reach, so an entry nobody reads is an argument
/// its author believes they granted.
fn granted(
  meta: &syn::meta::ParseNestedMeta<'_>,
  context: &mut Vec<syn::Path>,
  errors: &mut Errors,
) -> syn::Result<()> {
  if !attribute::has_block(meta) || attribute::empty_group(meta) {
    errors.push(attribute::unknown(meta, CONTEXT_EMPTY, &[]));
    return Ok(());
  }

  meta.parse_nested_meta(|inner| {
    if !inner.path.is_ident("resource") {
      errors.push(attribute::unknown(&inner, CONTEXT_LINE, &["resource"]));
      return Ok(());
    }
    if !attribute::has_block(&inner) || attribute::empty_group(&inner) {
      errors.push(attribute::unknown(&inner, CONTEXT_LINE, &[]));
      return Ok(());
    }
    let held;
    syn::parenthesized!(held in inner.input);
    match held
      .parse::<syn::LitStr>()
      .and_then(|written| written.parse::<syn::Path>())
    {
      Ok(path) => context.push(path),
      Err(e) => errors.push(syn::Error::new(e.span(), CONTEXT_LINE)),
    }
    Ok(())
  })
}

/// The `error(…)` word — one of two shapes, each optionally headed by a code.
fn declared_error(
  meta: &syn::meta::ParseNestedMeta<'_>,
  errors: &mut Errors,
) -> Option<DeclaredError> {
  if !attribute::has_block(meta) || attribute::empty_group(meta) {
    errors.push(attribute::unknown(meta, ERROR_EMPTY, &[]));
    return None;
  }

  let mut ty: Option<syn::Path> = None;
  let mut message: Option<syn::LitStr> = None;
  let mut code: Option<syn::LitStr> = None;
  // The `code` WORD, kept beside its value: a heading with nothing under it is refused at the word
  // the author has to move, and the value is not that token.
  let mut code_at: Option<syn::Path> = None;
  // Whether a SHAPE word was written at all, however badly. A `type` whose value could not be read
  // has earned its one error already, and the sentences below would be that error's echo.
  let mut shape_at: Option<syn::Path> = None;

  let walked = meta.parse_nested_meta(|inner| {
    // `type` is a Rust keyword, and syn's nested-meta parser takes it with `Ident::parse_any` — so
    // it arrives as an ordinary one-segment path exactly as `crate` does.
    if inner.path.is_ident("type") {
      shape_at = Some(inner.path.clone());
      if message.is_some() {
        errors.push(attribute::named(&inner, ERROR_BOTH.to_owned()));
        return Ok(());
      }
      match value::parse_literal::<syn::Path>(&inner, ERROR_TYPE) {
        Ok(path) => attribute::set_once(
          &mut ty,
          path,
          &inner.path,
          "`type` is declared more than once in `error(…)` — one exchange fails as one type",
          errors,
        ),
        Err(e) => refuse_value(&inner, e, errors),
      }
      return Ok(());
    }

    if inner.path.is_ident("message") {
      shape_at = Some(inner.path.clone());
      if ty.is_some() {
        errors.push(attribute::named(&inner, ERROR_BOTH.to_owned()));
        return Ok(());
      }
      match value::literal(&inner, ERROR_MESSAGE) {
        Ok(sentence) => attribute::set_once(
          &mut message,
          sentence,
          &inner.path,
          "`message` is declared more than once in `error(…)` — one canned failure is one sentence",
          errors,
        ),
        Err(e) => refuse_value(&inner, e, errors),
      }
      return Ok(());
    }

    if inner.path.is_ident("code") {
      match value::literal(&inner, ERROR_CODE) {
        Ok(word) => {
          code_at = Some(inner.path.clone());
          attribute::set_once(
            &mut code,
            word,
            &inner.path,
            "`code` is declared more than once in `error(…)` — one failure renders under one \
             heading",
            errors,
          );
        }
        Err(e) => refuse_value(&inner, e, errors),
      }
      return Ok(());
    }

    errors.push(attribute::unknown(
      &inner,
      "unknown entry in `error(…)` — it takes `type = \"…\"` OR `message = \"…\"`, and `code = \
       \"…\"` may head either",
      &["type", "message", "code"],
    ));
    Ok(())
  });
  if let Err(e) = walked {
    errors.push(e);
  }

  match (ty, message) {
    (Some(ty), _) => Some(DeclaredError::Rich { ty, code }),
    (None, Some(message)) => Some(DeclaredError::Canned { message, code }),
    // A shape word WAS written and could not be read; that refusal is the one error this block
    // earns, and either sentence below would be its echo.
    (None, None) if shape_at.is_some() => None,
    (None, None) => {
      // A `code` with neither shape under it — the heading with nothing under it. Spanned at the
      // `code` WORD, because that is the token the author has to move; a block that named no shape
      // at all earns the empty-word sentence instead, at the `error` word.
      errors.push(code_at.as_ref().map_or_else(
        || syn::Error::new_spanned(&meta.path, ERROR_EMPTY),
        |at| syn::Error::new_spanned(at, ERROR_CODE_ALONE),
      ));
      None
    }
  }
}

/// Record a refusal about an entry's VALUE, and swallow the entry it was written in.
///
/// [`attribute::unknown`]'s law, applied to the other half of a grammar. A value reader leaves the
/// token it could not read where it found it, so a walk that resumed there would earn syn's own
/// `expected ,` at the same column — and, inside a field's attribute, would abandon the rest of the
/// list and earn a second rule about the `handler` word it never reached. One rule broken costs one
/// error, and this is what keeps that true where a value rather than a word is wrong.
fn refuse_value(meta: &syn::meta::ParseNestedMeta<'_>, error: syn::Error, errors: &mut Errors) {
  errors.push(error);
  attribute::skip_entry(meta);
}

/// A mutation node takes no generic parameter.
///
/// The emission mints ONE command enum and writes ONE pair of impls for ONE type; a parameter is not
/// a type until it is substituted, so a generic declaration would mint a vocabulary per
/// instantiation and a source's `Mutation` seat could name none of them.
fn concrete(generics: &syn::Generics, errors: &mut Errors) {
  const WHY: &str = "a mutation node takes no generic parameter — the declaration mints ONE command \
                     vocabulary and states ONE record for it, and a parameter is not a type until \
                     it is substituted";
  if !generics.params.is_empty() {
    errors.push(syn::Error::new_spanned(generics, WHY));
  } else if let Some(clause) = &generics.where_clause {
    errors.push(syn::Error::new_spanned(clause, WHY));
  }
}

/// The declaration's named fields — the only shape a mutation node may take, its whole content being
/// the exchanges it declares BY NAME.
fn named_fields(input: &syn::DeriveInput) -> syn::Result<&syn::FieldsNamed> {
  match &input.data {
    syn::Data::Struct(data) => match &data.fields {
      syn::Fields::Named(named) => Ok(named),
      syn::Fields::Unnamed(_) | syn::Fields::Unit => Err(syn::Error::new_spanned(
        &input.ident,
        "a mutation node must be a struct with named fields — a field's NAME is the command's name, \
         the arm it mints in the vocabulary and the word the wire publishes, and a positional one \
         has none of them",
      )),
    },
    syn::Data::Enum(_) | syn::Data::Union(_) => Err(syn::Error::new_spanned(
      &input.ident,
      "`#[ingraph::mutation]` supports structs only — a node's FIELDS are its exchanges, and \
       variants are a choice between things rather than a list of them",
    )),
  }
}

/// The refusal a field with no `handler` earns, naming the field it is about.
fn no_handler(field: &syn::Ident) -> String {
  format!(
    "`{field}` declares no `handler` — a field of a mutation node IS an exchange, and an exchange \
     nobody runs is a command with no behaviour. Write `handler = \"path::to::fn\"` for the plain \
     form, or `handler(path = \"…\", …)` where the rest of the signature has something to say"
  )
}

/// The refusal a `rename` that is not a written word earns.
///
/// A STRING and not an ident, per the string-kind law: this word names a field in a SCHEMA's own
/// namespace, where Rust's keywords are ordinary words, so it is carried as a literal and fenced by
/// GraphQL's Name grammar rather than by Rust's.
const RENAME_WORD: &str = "`rename` is the word this exchange is PUBLISHED under, in a string literal — a schema name is \
   not a Rust identifier, and the two grammars disagree about which words are legal";

/// The refusal a `handler` written as a bare word or an empty block earns.
const HANDLER_EMPTY: &str = "`handler` names nothing — write `handler = \"path::to::fn\"` for the plain form, or \
   `handler(path = \"…\", …)` where the rest of the signature has something to say";

/// The refusal a `handler(…)` block with no `path` earns.
const HANDLER_NO_PATH: &str = "`handler(…)` names no `path` — the block IS the signature, and every other word in it describes \
   a function that has to exist first";

/// The refusal a handler path that is not a quoted path earns.
///
/// ONE sentence for both spellings, because the rule belongs to the WORD rather than to either
/// block: quoted, as every referring word in this grammar is, since it names a function this
/// declaration cannot resolve and the compiler resolves where the expansion lands.
const HANDLER_PATH: &str = "the function an exchange runs is named in a string literal — `handler = \"path::to::fn\"` or \
   `handler(path = \"…\")` — because the word names a PATH this declaration cannot resolve and the \
   compiler resolves where the expansion lands";

/// The refusal a `context` written as a bare word or an empty block earns.
const CONTEXT_EMPTY: &str = "`context()` grants nothing — a handler that reaches for a resource writes \
   `context(resource(\"…\"))`, and one that reaches for none omits the word, which is the signature \
   with the request and nothing beside it";

/// The refusal an entry in `context(…)` that is not a resource line earns.
const CONTEXT_LINE: &str = "a handler's `context(…)` is the RESOURCES it was granted, one `resource(\"…\")` line each — \
   quoted, because the word names a type this declaration cannot resolve. Nothing else reaches a \
   handler that way: the request arrives as the argument the exchange's own type named";

/// The refusal an `error` written as a bare word or an empty block earns.
const ERROR_EMPTY: &str = "`error()` declares no failure — a field that CAN fail names how (`type = \"…\"` for an error the \
   application owns, `message = \"…\"` for a sentence this declaration writes), and a field that \
   cannot omits the word, which is the signature with no `Result` in it";

/// The refusal a field claiming both failure shapes earns.
const ERROR_BOTH: &str = "`type` and `message` are the two shapes of ONE word — a failure is a type the application owns \
   OR a sentence this declaration writes, and an exchange claiming both leaves its handler's return \
   type undecided";

/// The refusal a `code` with nothing under it earns.
const ERROR_CODE_ALONE: &str = "`code` heads a failure and this one heads nothing — write it beside `type = \"…\"` or `message = \
   \"…\"`, which are the two things there are to head. A field that cannot fail omits `error(…)` \
   entirely";

/// The refusal an `error(type = …)` that is not a quoted path earns.
const ERROR_TYPE: &str = "`error(type = \"…\")` names the error this exchange fails as — quoted, because the word names a \
   TYPE this declaration cannot resolve and the compiler resolves where the expansion lands";

/// The refusal an `error(message = …)` that is not a string earns.
const ERROR_MESSAGE: &str =
  "`error(message = \"…\")` is the whole sentence a canned failure renders, in a string literal";

/// The refusal an `error(code = …)` that is not a string earns.
const ERROR_CODE: &str =
  "`error(code = \"…\")` is the heading a failure renders under, in a string literal";