Expand description
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:
{ "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 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:
@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 is a
codes::UNCOLLAPSED diagnostic there, the way an unexpanded
$import is.
Modules§
- codes
- Diagnostic codes emitted by the
$allowannotation machinery.
Constants§
- ALLOW_
KEY - Reserved object key carrying a node’s usage-site lint suppressions in the JSON front-end.
- ALLOW_
RULES_ FIELD - Payload field on an
ALLOW_VARIANTwrapper carrying one rule name. A wrapper naming several rules carries the field once per name, in the order written. - ALLOW_
TARGET_ SLOT - Child slot on an
ALLOW_VARIANTwrapper holding the single node the annotation applies to. - ALLOW_
VARIANT - Reserved
ParseTree::variantspelling for an un-collapsed@allowwrapper in the text front-end.
Functions§
- add_
allow_ syntax - Adds the reserved
@allow("rule") <node>spelling to a text grammar. - collapse
- Folds every
ALLOW_VARIANTwrapper intreeonto its target’sParseTree::allows.