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
//! Usage-site lint suppression: the reserved `$allow` annotation and
//! the diagnostics it can produce.
//!
//! A lint rule fires at a node. Sometimes the author of that node knows
//! better than the rule, and the only place that knowledge lives is the
//! node itself — not a project-wide configuration file, which would
//! switch the rule off everywhere and lose the reason. So a document
//! may annotate a node with the rule names it accepts there:
//!
//! ```json
//! { "type": "Par", "$allow": ["max-fan-out"], "branches": [ … ] }
//! ```
//!
//! ## Reserved key
//!
//! The annotation is spelled [`ALLOW_KEY`] (`"$allow"`). The `$` sigil
//! cannot appear in a Rust identifier, so the key can never collide
//! with a field or child slot a DSL author declares — the same
//! reservation that lets [`crate::import::IMPORT_VARIANT`] spell
//! `$import` without a namespace. Keys are dispatched against the
//! schema by name, so a reserved key is recognised before schema
//! dispatch and never reaches the unknown-key path.
//!
//! One interaction with `$import` is worth naming: an object carrying
//! both `$import` and `$allow` is rejected as
//! [`crate::import::import_codes::SPEC_SHAPE`], because an import
//! placeholder must be a single-key object. Annotate the imported
//! source's own nodes instead.
//!
//! The text spelling is refused symmetrically: `@allow("x") @import
//! "y"` is a [`codes::UNCOLLAPSED`] diagnostic from [`collapse`]. The
//! loader replaces the placeholder with the imported tree, which would
//! carry the annotation away with the node it was written on — and a
//! suppression that quietly does nothing is exactly what the shape
//! rules here exist to prevent.
//!
//! ## Shape
//!
//! The value must be an array of rule-name strings. An empty array is
//! accepted and means the same as no annotation at all. Anything else
//! — a bare string, a number, an array with a non-string element — is
//! a [`codes::ALLOW_SHAPE`] diagnostic rather than a silently ignored
//! key, because a mis-spelled suppression that quietly does nothing is
//! worse than one that fails loudly.
//!
//! ## Where the names go
//!
//! The front-end stores them verbatim on [`ParseTree::allows`]; the
//! names are not validated against a rule registry here, since the
//! parse trunk does not know which rules exist. `#[derive(DslBuild)]`
//! carries them to [`dsl_kit_core::AllowTable`], keyed on the
//! [`NodeId`](dsl_kit_core::NodeId) minted for the annotated node,
//! and a linter resolves them there.
//!
//! ## The text spelling
//!
//! The two front-ends are deliberately asymmetric. JSON recognises
//! `$allow` unconditionally — a reserved key costs a document nothing
//! until it spells one. The canonical text front-end is opt-in:
//! [`add_allow_syntax`] injects the `@allow("rule") <node>` spelling
//! into a [`Grammar`], and a grammar that never passes through it does
//! not accept `@allow` anywhere, the same shape
//! [`crate::import::add_import_syntax`] has.
//!
//! Where the annotation sits differs too, because the two surfaces
//! differ: an object has a spare key, a text node has only the
//! position in front of it. So text spells it as a **wrapper**:
//!
//! ```text
//! @allow("max-fan-out") Par(branches: [ … ])
//! @allow("max-fan-out", "max-depth") Par(branches: [ … ])
//! ```
//!
//! parses to a reserved [`ALLOW_VARIANT`] node holding the annotated
//! node in its [`ALLOW_TARGET_SLOT`] child, and [`collapse`] — which
//! [`Grammar::parse`] runs on every text parse — folds the wrapper
//! away onto its target's [`ParseTree::allows`]. Downstream therefore
//! never sees the wrapper, and the two front-ends hand it the same
//! tree for the same document. A wrapper that does reach
//! [`check_conformance`](crate::check_conformance) is a
//! [`codes::UNCOLLAPSED`] diagnostic there, the way an unexpanded
//! `$import` is.
//!
//! [`ParseTree::allows`]: crate::ParseTree::allows
//! [`Grammar::parse`]: crate::peg::Grammar::parse
use crateIMPORT_VARIANT;
use crate;
use crate::;
use IdGen;
use Value;
/// Reserved object key carrying a node's usage-site lint suppressions
/// in the JSON front-end.
pub const ALLOW_KEY: &str = "$allow";
/// Reserved [`ParseTree::variant`](crate::ParseTree::variant) spelling
/// for an un-collapsed `@allow` wrapper in the text front-end.
///
/// Same `$` sigil, same reservation argument as [`ALLOW_KEY`]: it
/// cannot collide with a variant a DSL author declares. The two
/// constants share a spelling but not a position — one is an object
/// key, the other a variant name.
pub const ALLOW_VARIANT: &str = "$allow";
/// Payload field on an [`ALLOW_VARIANT`] wrapper carrying one rule
/// name. A wrapper naming several rules carries the field once per
/// name, in the order written.
pub const ALLOW_RULES_FIELD: &str = "rules";
/// Child slot on an [`ALLOW_VARIANT`] wrapper holding the single node
/// the annotation applies to.
pub const ALLOW_TARGET_SLOT: &str = "target";
/// Diagnostic codes emitted by the `$allow` annotation machinery.
// ---------------------------------------------------------------------------
// Text syntax injection
// ---------------------------------------------------------------------------
/// Adds the reserved `@allow("rule") <node>` spelling to a text
/// grammar.
///
/// Appends a rule named [`ALLOW_VARIANT`] whose body is
/// `Node("$allow", %kw:@allow "(" Field("rules", %str)+ ")"
/// Field("target", <start>))`, and makes it an alternative of the
/// grammar's start rule — for grammars generated by
/// [`crate::schema_gen`], the start rule is the `node` choice every
/// child slot references, so an annotation is writable at every node
/// position. A start rule whose body is not a [`Peg::Choice`] is
/// wrapped in one.
///
/// Opt-in by design: a grammar that never passes through this function
/// accepts no `@allow` syntax at all, and the reserved rule is
/// invisible to [`crate::example_gen`] (examples never spell `@allow`)
/// and exempt from [`crate::grammar_check`]'s schema-consistency pass.
///
/// Idempotent — a grammar that already carries the reserved rule is
/// returned unchanged. Fails with [`crate::peg::codes::UNKNOWN_RULE`]
/// if the start rule is not defined.
// ---------------------------------------------------------------------------
// Collapse
// ---------------------------------------------------------------------------
/// Folds every [`ALLOW_VARIANT`] wrapper in `tree` onto its target's
/// [`ParseTree::allows`](crate::ParseTree::allows).
///
/// [`Grammar::parse`](crate::peg::Grammar::parse) applies this to
/// every text parse, so a host wires up nothing: a document that never
/// spells `@allow` has no wrapper to fold and comes back as it went
/// in. Front-ends that build wrappers themselves call it directly.
///
/// Stacked wrappers (`@allow("a") @allow("b") X`) fold onto the same
/// target, outermost name first. The surviving node keeps the
/// **target's** span: the wrapper's span covers the annotation the
/// author wrote, which is not where a diagnostic about the annotated
/// node should point.
///
/// Fails with [`codes::UNCOLLAPSED`] on a wrapper the fold cannot
/// consume — no target, more than one, a `rules` payload that is not a
/// string, any other slot. The injected grammar cannot produce those
/// shapes; a hand-built tree can, and dropping the annotated subtree
/// quietly would be the wrong kind of forgiving.
///
/// It fails the same way on a wrapper whose target is an
/// [`IMPORT_VARIANT`] placeholder, which the grammar *can* produce:
/// the annotation would survive the fold only to be discarded when the
/// loader substitutes the imported tree.
/// Recursive half of [`collapse`]. Diagnostics from distinct wrappers
/// are collected before failing, as everywhere else in the trunk.
/// Folds one wrapper: read its names, take its single target, fold
/// that target in turn, and prepend the names to whatever the target
/// already carries.