Skip to main content

Module allow

Module allow 

Source
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 $allow annotation 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_VARIANT wrapper 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_VARIANT wrapper holding the single node the annotation applies to.
ALLOW_VARIANT
Reserved ParseTree::variant spelling for an un-collapsed @allow wrapper in the text front-end.

Functions§

add_allow_syntax
Adds the reserved @allow("rule") <node> spelling to a text grammar.
collapse
Folds every ALLOW_VARIANT wrapper in tree onto its target’s ParseTree::allows.