In a textual DSL editor - for example one built with Xtext - what are 'scope rules' (a scoping provider) responsible for, and why does getting them right matter so much once a DSL model spans many files?

## Parsing establishes structure, linking establishes meaning Parsing a DSL document only establishes its syntactic structure - that a token sequence matches the grammar's rules. It says nothing about whether a name used in one place actually refers to something real, or to the correct 'something real' among several candidates with the same name. That second job is **scoping**, sometimes called **linking**: for every cross-reference in the model (a feature typed as `[SomeType]` in the grammar, pointing at another element by name rather than embedding it inline), a scope provider computes the set of elements that are visible and eligible at that specific point in the model, and the linker then matches the referenced name against that set to bind the reference to a concrete target element. ## Where the naive scope breaks down The simplest possible scope rule is 'every element of the right type anywhere in this same file is visible,' and for a small single-file DSL that's often good enough as a default. The moment a DSL model is expected to span multiple files - a common requirement once a language is used for anything beyond toy examples, such as splitting a large domain model into one file per bounded context - that default breaks down in two ways. 1. **Mechanically.** First, purely mechanically, a same-file-only scope can no longer find legitimate cross-file references at all, so references that should resolve now report as unresolved. 2. **Dangerously.** Second, and more dangerously, if the scope is widened naively to 'every element of the right type in the entire workspace,' name collisions become likely: two unrelated files can easily define an element with the same name for entirely different purposes, and a reference with no disambiguating qualifier or import now has multiple equally 'visible' candidates, forcing the linker to pick one, often the first one found, which may not be the one the author intended. ## What real tooling does instead The fix real DSL tooling uses mirrors what general-purpose languages have always done: - introduce a notion of modules, packages, or files as named units; - require explicit import statements or fully qualified names to bring an element from another unit into scope; - build a workspace-wide index of exported (publicly visible) named elements that the scope provider can query efficiently instead of re-parsing every other file on every keystroke. In Xtext specifically, this index is the `IResourceDescription` mechanism: as files are edited, Xtext maintains an incrementally updated index of each file's exported elements, and a custom scope provider can query that index, filtered by import statements or naming conventions, to compute the correct visible set for any given reference point without a full workspace reparse. ## Why it is the load-bearing wall Why this matters so much in practice is that scoping correctness is the load-bearing wall underneath almost every editor feature a DSL user actually relies on day to day. - **Content-assist (autocomplete)** for a cross-reference feature literally enumerates the scope provider's computed candidate set and offers it as proposals - a scope that's too broad pollutes suggestions with irrelevant or even private elements from unrelated modules, while a scope that's too narrow hides legitimate valid choices. - **'Find references' and 'rename refactoring'** both depend on correctly identifying every place a given element is actually referenced, which is impossible if the scope logic used during linking doesn't match reality. - **Validation** - flagging a reference as an error when it doesn't resolve - depends entirely on the linker's scope computation being correct; a scope that's accidentally too permissive means a genuinely broken or unintended reference silently resolves to *something* and passes validation without any warning. ## The insidious failure mode The most insidious failure mode in production is exactly that last case: a scope provider that's too permissive doesn't crash or show an obvious error, it silently resolves an ambiguous reference to the wrong element, most often to a same-named element in an unrelated file that happened to be indexed first or last. The author sees a model that looks entirely valid in the editor - no red squiggles, autocomplete worked - but the generated output (code, configuration, documentation) is quietly wrong, because behind the scenes the reference bound to the wrong `Customer` or `Order` definition. This class of bug is notoriously hard to catch because nothing in the editor experience signals that anything went wrong; it typically surfaces much later, as unexplained behavior in generated artifacts, and root-causing it requires specifically suspecting and inspecting the scope resolution rather than the grammar or the generator. ## How to defend against it A good way to defend against this is to unit test the scope provider directly and in isolation: - construct small in-memory models with deliberately colliding names across simulated files or modules; - assert that a reference resolves to the specific expected element (not merely 'some' element); - add negative test cases asserting that a reference with no valid import should fail to resolve and produce a validation error rather than silently binding to an unintended candidate.