@descent-vtt/spec-guard 0.26.0 → 0.28.0

package/dist/polyglot.js

@@ -81,7 +81,7 @@ function mask(source, language) {
     // The opening delimiter is left visible so a reader can see that a literal
     // starts here; everything inside it is blanked so no keyword can hide there.
     const blanks = [...comments, ...strings.map(([start, end]) => [start + 1, end])];
-    return { code: maskRanges(source, blanks), strings, source, starts: lineStarts(source), unterminated };
+    return { code: maskRanges(source, blanks), strings, comments, source, starts: lineStarts(source), unterminated };
 }
 /** The literal that starts exactly at `offset`, or null. */
 function literalAt(masked, offset) {
@@ -132,13 +132,25 @@ export function literalValue(raw) {
     return text;
 }
 /* ------------------------------------------------------------------ reading */
-const IDENTIFIER = /[A-Za-z_][A-Za-z0-9_]*/y;
 /**
- * Whitespace-skipping cursor over masked code.
+ * A Go identifier: a letter, then letters and decimal digits, where a letter
+ * is `_` or a character of a Letter category, Lu, Ll, Lt, Lm or Lo, and a
+ * digit one of Nd (The Go Programming Language Specification, "Characters",
+ * "Letters and digits" and "Identifiers", go1.27, read on 2026-10-19). The
+ * page has those categories as Unicode 8.0 gives them; it follows from it,
+ * and is not on it, that a later Unicode's letters, which the Node that runs
+ * spec-guard has, are read as letters. A mark is no letter, so `cafe` with a
+ * combining accent is no identifier, and the text is not normalised: `café`
+ * written so is two characters of which the second is none.
+ */
+const IDENTIFIER = /[\p{L}_][\p{L}\p{Nd}_]*/uy;
+/**
+ * Whitespace-skipping cursor over masked code, which a Go import and a Python
+ * dynamic import are read with.
  *
  * Exported so its edges can be pinned directly. Reaching "what does peek() do
- * at the end of the file" through a C# source string is possible but says
- * nothing about C#.
+ * at the end of the file" through a Go source string is possible but says
+ * nothing about Go.
  */
 export class Reader {
     text;
@@ -160,26 +172,6 @@ export class Reader {
     peek() {
         return this.text[this.index] ?? '';
     }
-    eat(token) {
-        if (!this.text.startsWith(token, this.index))
-            return false;
-        this.index += token.length;
-        return true;
-    }
-    /**
-     * Eats a word only when it really is the whole word.
-     *
-     * `eat('static')` also matches the first six characters of a namespace called
-     * `staticfiles`, and would then read the dependency as `files`.
-     */
-    keyword(word) {
-        if (!this.text.startsWith(word, this.index))
-            return false;
-        if (/[A-Za-z0-9_]/.test(this.text[this.index + word.length] ?? ''))
-            return false;
-        this.index += word.length;
-        return true;
-    }
     identifier() {
         IDENTIFIER.lastIndex = this.index;
         const match = IDENTIFIER.exec(this.text);
@@ -188,49 +180,6 @@ export class Reader {
         this.index += match[0].length;
         return match[0];
     }
-    /**
-     * Reads `a.b.c`, leaving out a C# alias qualifier.
-     *
-     * `global::A.B` and `Legacy::A.B` both name the namespace `A.B`: what comes
-     * before `::` says where to look it up - the global namespace, or the
-     * assembly an extern alias names - and is not part of the name. Until 0.10.2
-     * this read `global.A.B`, and no pattern written for `A.B` matched it.
-     */
-    dotted() {
-        let parts = [];
-        for (;;) {
-            const part = this.identifier();
-            if (!part)
-                break;
-            parts.push(part);
-            if (this.eat('::'))
-                parts = [];
-            else if (!this.eat('.'))
-                break;
-        }
-        return parts.join('.');
-    }
-    /**
-     * Skips a generic argument list, so an alias target's `<...>` does not end
-     * the read.
-     *
-     * No bracket counting. A `using` directive ends at the first `;` or newline
-     * whatever is nested inside its angle brackets, and the caller's only
-     * question is whether the next non-space character is that `;` - so `A<B>`
-     * and `A<B<C>>` are both passed over by the same rule. The depth counter
-     * that used to be here could not change an answer for any input C# accepts,
-     * which is another way of saying no test could hold it in place.
-     */
-    skipGenerics() {
-        if (this.peek() !== '<')
-            return;
-        while (this.index < this.text.length) {
-            const char = this.text[this.index];
-            if (char === ';' || char === '\n')
-                return;
-            this.index += 1;
-        }
-    }
 }
 /** Offset of the matching close, given the depth-tracking characters. */
 export function matchingClose(text, open, opener, closer) {
@@ -442,12 +391,18 @@ function readPython(collector) {
         while ((match = PYTHON_STATEMENT.exec(line.text)) !== null) {
             const tokens = pythonTokens(line.text, PYTHON_STATEMENT.lastIndex);
             const modules = tokens === null ? null : pythonImports(tokens, match[4] === 'from', match[3] !== undefined);
-            if (modules === null)
-                continue;
             // Reported on the line its first word stands on, at that line's head,
             // as an import at the head of a logical line always was.
             const first = match.index + match[1].length + match[2].length;
             const [, offset] = line.starts.findLast(([at]) => at <= first);
+            // A statement that starts as an import and that Python refuses names no
+            // module, and is said, as everything that could not be read is: a rule
+            // that passes over it under --strict fails (ADR-0008, amended
+            // 2026-10-18).
+            if (modules === null) {
+                note(collector, 'refused', offset, 'a statement that starts as an import is one Python refuses, and no module is read from it');
+                continue;
+            }
             // Python reads a name in the form NFKC gives it.
             for (const module of modules)
                 emit(collector, module.normalize('NFKC'), 'import', offset);
@@ -468,6 +423,11 @@ function readPython(collector) {
 }
 /* ----------------------------------------------------------------------- go */
 const GO_IMPORT = /\bimport\b/g;
+/** Go's keywords, which no identifier is, so no package name ("Keywords"). */
+const GO_KEYWORDS = new Set([
+    ...['break', 'case', 'chan', 'const', 'continue', 'default', 'defer', 'else', 'fallthrough', 'for', 'func', 'go', 'goto'],
+    ...['if', 'import', 'interface', 'map', 'package', 'range', 'return', 'select', 'struct', 'switch', 'type', 'var'],
+]);
 function readGo(collector) {
     const { code } = collector.masked;
     GO_IMPORT.lastIndex = 0;
@@ -484,11 +444,29 @@ function readGo(collector) {
             GO_IMPORT.lastIndex = close;
             continue;
         }
-        // A single import may carry an alias: `import fmt2 "fmt"`, `import _ "x"`.
-        if (reader.peek() === '_' || reader.peek() === '.')
+        // A single import may carry a package name, `import fmt2 "fmt"`, `import
+        // 名 "fmt"` or `import _ "x"`, or a `.` ("Import declarations"). A name at
+        // the end of its line has a semicolon put after it, and a comment that
+        // holds a line break ends the line too ("Semicolons", "Comments"): the
+        // import ends there, with no path, which Go refuses.
+        if (reader.peek() === '.') {
             reader.index += 1;
-        else
-            reader.identifier();
+        }
+        else {
+            const name = reader.identifier();
+            // On from the keyword, so that `import import "x"` is read as no
+            // import, and not as a second.
+            if (GO_KEYWORDS.has(name)) {
+                GO_IMPORT.lastIndex = reader.index;
+                continue;
+            }
+            // With no name the space after `import` was passed over already, so
+            // this finds a line break only after one.
+            const after = reader.index;
+            reader.skipSpace();
+            if (code.slice(after, reader.index).includes('\n'))
+                continue;
+        }
         reader.skipSpace();
         const literal = literalAt(collector.masked, reader.index);
         if (literal !== null)
@@ -496,94 +474,679 @@ function readGo(collector) {
     }
 }
 /* --------------------------------------------------------------------- rust */
-const RUST_USE = /\b(?:use|extern[ \t\r\n]+crate)\b/g;
+/** Rust's white space, Unicode's Pattern_White_Space, which a masked comment is too. */
+const RUST_SPACE = String.raw `\t\n\v\f\r \u{85}\u{200e}\u{200f}\u{2028}\u{2029}`;
+/**
+ * Where a use declaration or an extern crate starts. The keyword is a whole
+ * word, so not the tail of `r#use`, a raw identifier.
+ */
+const RUST_USE = new RegExp(String.raw `(?<![\p{XID_Continue}#])(?:use|extern[${RUST_SPACE}]+crate)(?!\p{XID_Continue})`, 'gu');
 /**
- * Expands one `use` path into the module paths it actually names.
+ * One token of a use declaration, after any white space: a name, raw or not,
+ * `$crate` or another of a macro's names, or a mark. Nothing need separate two
+ * tokens that cannot be read as one.
+ */
+const RUST_TOKEN = new RegExp(String.raw `[${RUST_SPACE}]*(?:(r#)?([\p{XID_Start}_]\p{XID_Continue}*)|(\$[\p{XID_Start}_]\p{XID_Continue}*|::|[{},*;]))`, 'uy');
+/** Nothing but white space, to the end of the text. */
+const RUST_BLANK = new RegExp(String.raw `^[${RUST_SPACE}]*$`, 'u');
+/** What `r#` cannot make a raw identifier of. */
+const RUST_NOT_RAW = new Set(['_', 'crate', 'self', 'Self', 'super']);
+/**
+ * What no segment of a path, alias or crate name is unless written raw:
+ * `_`, and Rust's keywords in every edition, strict and reserved (Keywords,
+ * as read on 2026-10-19), `Self` among them, which no use path holds
+ * (Use declarations, "use Paths"). So a declaration left open is never read
+ * on into the next, whose `use` or `extern` is one. `crate`, `self` and
+ * `super` are not here: they stand where `rustPathRefused` lets them.
+ * `async`, `await` and `dyn` are keywords from the 2018 edition on, `try`
+ * from 2018 and `gen` from 2024, and the edition is in `Cargo.toml`, which
+ * the reader does not open, so each is read as the name it is before them.
+ */
+const RUST_NOT_SEGMENT = new Set([
+    '_',
+    ...['as', 'break', 'const', 'continue', 'else', 'enum', 'extern', 'false', 'fn', 'for', 'if', 'impl', 'in', 'let', 'loop'],
+    ...['match', 'mod', 'move', 'mut', 'pub', 'ref', 'return', 'Self', 'static', 'struct', 'trait', 'true', 'type', 'unsafe'],
+    ...['use', 'where', 'while', 'abstract', 'become', 'box', 'do', 'final', 'macro', 'override', 'priv', 'typeof', 'unsized'],
+    ...['virtual', 'yield'],
+]);
+/** The words a path starts with to name a module, which an import binds only under a name of its own. */
+const RUST_PATH_KEYWORDS = new Set(['crate', 'self', 'super', '$crate']);
+/** The token at `index`, or null where none starts. */
+function rustToken(text, index) {
+    RUST_TOKEN.lastIndex = index;
+    const match = RUST_TOKEN.exec(text);
+    if (match === null)
+        return null;
+    const [, raw, word, mark] = match;
+    // `r#` stands only before a name.
+    if (raw !== undefined && RUST_NOT_RAW.has(word))
+        return null;
+    return { text: word?.normalize('NFC') ?? mark, name: word !== undefined, raw: raw !== undefined, end: RUST_TOKEN.lastIndex };
+}
+/**
+ * Whether rustc refuses a path of a use tree for where `crate`, `self`,
+ * `super` or `$crate` stands in it (Paths, "Path qualifiers"), or for
+ * importing a module that it binds only under a name given with `as` (Use
+ * declarations, "Restrictions"), each as read on 2026-10-19, and each held
+ * to rustc 1.97.1 in every edition.
+ */
+function rustPathRefused({ segments, global, bare }) {
+    const last = segments.length - 1;
+    const misplaced = segments.some((segment, at) => {
+        // First, and not after a `::`.
+        if (segment === 'crate' || segment === '$crate')
+            return at > 0 || global;
+        // First and not after a `::`, or last after one: `a::self` names `a`.
+        // `::{self as root}` imports the crate root in the 2015 edition and is
+        // refused from 2018, which the reader cannot tell apart, so it is read.
+        if (segment === 'self')
+            return at < last && (at > 0 || global);
+        // Only after other `super`s, or after a first `self`: a `self` anywhere
+        // else before it is refused where it stands.
+        if (segment === 'super')
+            return global || !segments.slice(0, at).every((before) => before === 'super' || before === 'self');
+        return false;
+    });
+    // `use crate;`, `use self;`, `use super::super;` and `use a::{self}` with
+    // `a` one of them: the module is bound only under a name given with `as`.
+    // `use crate::{};` binds nothing, and rustc takes it. A trailing `self`
+    // is one of those words too, so `use crate::self;` is refused alike.
+    return misplaced || (bare && segments.every((segment) => RUST_PATH_KEYWORDS.has(segment)));
+}
+/**
+ * The paths one use tree names, segment by segment, read as the Rust
+ * Reference's grammar has it:
+ *
+ *   (path ::)? *    (path ::)? { tree, ... }    path (as name)?
  *
- * `a::{b, c::{d, e}}` is three dependencies written as one statement, and a
- * rule about `a::c` has to see them. Returns null when the expansion would
- * exceed MAX_EXPANSION, which the caller reports rather than truncating.
+ * `refused` where rustc would refuse the text, and `overflow` past
+ * MAX_EXPANSION paths or groups nested that deep. `end` is where reading
+ * stopped, past the tree or at the token it could not read.
  */
-export function expandUsePath(input) {
-    const text = input.trim();
-    const open = text.indexOf('{');
-    if (open === -1) {
-        // `a::b as c` and `a::b;` both name `a::b`. Only what stands before the
-        // alias is read, and white space left at its end is taken off on the next
-        // line: one space on either side of `as` splits at a place that reads the
-        // same, so the pattern without either `+` is an equivalent mutant.
-        const leaf = text.split(/\s+as\s+/)[0];
-        const trimmed = leaf.replace(/[;\s]+$/, '').replace(/^::/, '');
-        return trimmed ? [trimmed] : [];
-    }
-    const close = matchingClose(text, open, '{', '}');
-    const prefix = text.slice(0, open).replace(/::\s*$/, '').trim();
-    const inner = text.slice(open + 1, close);
-    const parts = [];
-    let depth = 0;
-    let current = '';
-    for (const char of inner) {
-        if (char === '{')
-            depth += 1;
-        if (char === '}')
-            depth -= 1;
-        if (char === ',' && depth === 0) {
-            parts.push(current);
-            current = '';
-            continue;
-        }
-        current += char;
-    }
-    parts.push(current);
-    const results = [];
-    for (const part of parts) {
-        const expanded = expandUsePath(part);
-        if (expanded === null)
+function readUseTree(text, from) {
+    let index = from;
+    const take = (accept) => {
+        const token = rustToken(text, index);
+        if (token === null || !accept(token))
             return null;
-        for (const item of expanded) {
-            // `use a::{self, b}` names `a` itself alongside `a::b`.
-            results.push(item === 'self' || !prefix ? prefix || item : `${prefix}::${item}`);
-            if (results.length > MAX_EXPANSION)
-                return null;
+        index = token.end;
+        return token;
+    };
+    // No name is written as a mark is.
+    const mark = (text) => take((token) => token.text === text) !== null;
+    // A name, or `$crate` or another name of a macro's, which rustc reads
+    // where the macro is expanded.
+    const named = (token) => token.name || token.text.startsWith('$');
+    // `_` is a token of its own, and stands in a path only after `as`.
+    const segment = () => take((token) => named(token) && (token.raw || !RUST_NOT_SEGMENT.has(token.text)))?.text ?? null;
+    // A name given with `as`: `_`, or a name that is no keyword and no word a path starts with.
+    const alias = (token) => named(token) && (token.raw || token.text === '_' || !(RUST_NOT_SEGMENT.has(token.text) || RUST_PATH_KEYWORDS.has(token.text)));
+    const paths = [];
+    const tree = (head, rooted, depth) => {
+        if (depth > MAX_EXPANSION)
+            return 'overflow';
+        const path = [...head];
+        // A `::` before the first segment of all is the global root, and rustc
+        // refuses one anywhere else: `use a::{::b};`.
+        const leading = mark('::');
+        if (leading && head.length > 0)
+            return 'refused';
+        const global = rooted || leading;
+        for (let name = segment(); name !== null; name = segment()) {
+            path.push(name);
+            if (mark('::'))
+                continue;
+            const renamed = take((token) => !token.raw && token.text === 'as') !== null;
+            if (renamed && take(alias) === null)
+                return 'refused';
+            paths.push({ segments: path, global, bare: !renamed });
+            return 'read';
+        }
+        // A separator was the last token read, or nothing was.
+        if (mark('*')) {
+            // A glob binds no module of its own; its `*` is no word a path starts
+            // with either, so `bare` is never what decides it.
+            paths.push({ segments: [...path, '*'], global, bare: false });
+            return 'read';
         }
+        if (!mark('{'))
+            return 'refused';
+        if (mark('}')) {
+            // An empty group imports nothing, and rustc still reads the path before
+            // it as an import: its lint names `use a::{};` an unused one.
+            paths.push({ segments: path, global, bare: false });
+            return 'read';
+        }
+        do {
+            const read = tree(path, global, depth + 1);
+            if (read !== 'read')
+                return read;
+            if (paths.length > MAX_EXPANSION)
+                return 'overflow';
+        } while (mark(',') && rustToken(text, index)?.text !== '}');
+        return mark('}') ? 'read' : 'refused';
+    };
+    const read = tree([], false, 0);
+    return { paths: read !== 'read' ? read : paths.some(rustPathRefused) ? 'refused' : paths, end: index };
+}
+/** The module a path of a use tree names, in the notation a rule writes, or nothing. */
+function usePath({ segments }) {
+    // `a::b::self` names `a::b`, as `a::{self}` names `a`. A glob of nothing,
+    // the one path a `*` starts, names no module.
+    const named = segments.length > 1 && segments.at(-1) === 'self' ? segments.slice(0, -1) : segments;
+    return named[0] === '*' ? '' : named.join('::');
+}
+/**
+ * Expands one use tree, with its `;` or without, into the module paths it
+ * names.
+ *
+ * `a::{b, c::{d, e}}` is three dependencies written as one declaration, and a
+ * rule about `a::c` has to see them. A tree is read as rustc reads it: white
+ * space and comments between its tokens, a raw identifier without its `r#`, a
+ * name in its NFC form, and `self` at the end of a path naming what is before
+ * it. Text that is no use tree, which rustc refuses, names nothing (ADR-0008,
+ * amended 2026-10-18), and so does a tree with a keyword for a segment, or
+ * with `crate`, `self` or `super` where rustc refuses it (amended
+ * 2026-10-19). A `$` name is read as a macro's, as a tree alone says nothing
+ * of where it stands. Returns null when the tree would name more than
+ * MAX_EXPANSION paths, or nest its groups deeper than that, which the caller
+ * reports rather than truncating.
+ */
+export function expandUsePath(input) {
+    const { paths, end } = readUseTree(input, 0);
+    if (paths === 'overflow')
+        return null;
+    const semicolon = rustToken(input, end);
+    const rest = input.slice(semicolon?.text === ';' ? semicolon.end : end);
+    return paths !== 'refused' && RUST_BLANK.test(rest) ? paths.map(usePath).filter((path) => path !== '') : [];
+}
+/**
+ * The crate an extern crate declaration names, read from after `crate`, or
+ * null where rustc refuses it: `extern crate name (as alias)? ;`, the name an
+ * identifier that is no keyword, or `self` with an alias, which rustc takes
+ * only so, and the end of its `;`.
+ */
+function externCrate(text, from) {
+    // A name that is no keyword and no word a path starts with, raw or not.
+    const name = (token) => token.name && (token.raw || !(RUST_NOT_SEGMENT.has(token.text) || RUST_PATH_KEYWORDS.has(token.text)));
+    const crate = rustToken(text, from);
+    if (crate === null || !(name(crate) || crate.text === 'self'))
+        return null;
+    let next = rustToken(text, crate.end);
+    const renamed = next !== null && !next.raw && next.text === 'as';
+    if (renamed) {
+        const alias = rustToken(text, next.end);
+        next = alias !== null && (name(alias) || alias.text === '_') ? rustToken(text, alias.end) : null;
     }
-    return results;
+    return next?.text === ';' && (renamed || crate.text !== 'self') ? { crate: crate.text, end: next.end } : null;
 }
+/**
+ * Where a macro's tokens stand: the group of an invocation, `m!(...)`,
+ * `path::m![...]` or `m! {...}`, of a definition, `macro_rules! m {...}`
+ * and `macro m(...) {...}`, and of an attribute, `#[...]` and `#![...]`.
+ * rustc reads them as tokens and refuses none of them for not being a
+ * declaration: a matcher holds the word `use`, and `quote!` writes
+ * `use #name::Thing;`. Too wide a reach costs a note, never a reading: a
+ * declaration in one is read as everywhere else.
+ */
+const RUST_MACRO = new RegExp(String.raw `(?:(?<!\p{XID_Continue})macro_rules[${RUST_SPACE}]*![${RUST_SPACE}]*[\p{XID_Start}_]\p{XID_Continue}*|(?<![\p{XID_Continue}#])(macro)[${RUST_SPACE}]+[\p{XID_Start}_]\p{XID_Continue}*|\p{XID_Continue}!|#!?)[${RUST_SPACE}]*([(\[{])`, 
+// Emptied, the flags leave each `exec` in `macroRanges` reading from the
+// start, and on a file with an attribute its loop pushes a range a turn
+// for ever. The thread runs out of memory, and no test's timer fires
+// inside the loop, so a sweep counts an error: the tests of a macro's
+// tokens see the mutant where they run before any test that meets it.
+'gu');
+const RUST_CLOSERS = { '(': ')', '[': ']', '{': '}' };
+/** The brace a `macro` definition's body opens after its parameters. */
+const RUST_BODY = new RegExp(String.raw `[${RUST_SPACE}]*\{`, 'uy');
+/** The half-open ranges of a file's macro tokens, outermost only, ascending. */
+function macroRanges(code) {
+    const ranges = [];
+    RUST_MACRO.lastIndex = 0;
+    let match;
+    while ((match = RUST_MACRO.exec(code)) !== null) {
+        const opener = match[2];
+        let end = matchingClose(code, RUST_MACRO.lastIndex - 1, opener, RUST_CLOSERS[opener]) + 1;
+        // The body ends at its `}`, and `- 1` for its `+ 1` is an equivalent
+        // mutant: no `use` starts in the body's last two characters.
+        RUST_BODY.lastIndex = end;
+        if (match[1] !== undefined && RUST_BODY.test(code))
+            end = matchingClose(code, RUST_BODY.lastIndex - 1, '{', '}') + 1;
+        ranges.push([match.index, end]);
+        // Outermost only: each is read to its end once, so nesting costs nothing.
+        RUST_MACRO.lastIndex = end;
+    }
+    return ranges;
+}
+const RUST_SPACE_CHARACTER = new RegExp(`[${RUST_SPACE}]`, 'u');
+/** Whether `at` is where an item or a statement may start: at the head of the file, or after `;`, a brace, an attribute's `]`, `pub` or its `(...)`. */
+function startsAnItem(code, at) {
+    let before = at;
+    while (RUST_SPACE_CHARACTER.test(code[before - 1] ?? ''))
+        before -= 1;
+    return before === 0 || ';{}])'.includes(code[before - 1]) || /(?<!\p{XID_Continue})pub$/u.test(code.slice(Math.max(0, before - 4), before));
+}
+/**
+ * A doc comment, which rustc reads as an attribute: three slashes and no
+ * fourth, `//!`, a block opened with two stars and no third that holds
+ * something, and a block opened with `/*!` (Comments, as read on
+ * 2026-10-19).
+ */
+const RUST_DOC = /^(?:\/\/\/(?!\/)|\/\/!|\/\*\*(?![*/])|\/\*!)/;
 function readRust(collector) {
-    const { code } = collector.masked;
+    const { code, comments, source } = collector.masked;
+    const macros = macroRanges(code);
+    let macro = 0;
+    let comment = 0;
     RUST_USE.lastIndex = 0;
     let match;
     while ((match = RUST_USE.exec(code)) !== null) {
-        const start = match.index + match[0].length;
-        let end = start;
-        let depth = 0;
-        while (end < code.length) {
-            const char = code[end];
-            if (char === '{')
-                depth += 1;
-            else if (char === '}') {
-                if (depth === 0)
-                    break;
-                depth -= 1;
+        const at = match.index;
+        while (macro < macros.length && macros[macro][1] <= at)
+            macro += 1;
+        // A range starts at a macro's name or an attribute's `#`, never where a
+        // `use` does, so `<` for `<=` is an equivalent mutant; and no comment
+        // starts where a `use` does, so `<=` for the `<` after it is one too.
+        const inMacro = macro < macros.length && macros[macro][0] <= at;
+        while (comment < comments.length && comments[comment][0] < at)
+            comment += 1;
+        // A doc comment between `use` and the end of the declaration, which rustc
+        // reads as an attribute where no attribute may stand.
+        const documented = (end) => {
+            for (let next = comment; next < comments.length && comments[next][0] < end; next++) {
+                if (RUST_DOC.test(source.slice(comments[next][0], comments[next][0] + 4)))
+                    return true;
+            }
+            return false;
+        };
+        // What rustc refuses is said where it starts as a declaration: where an
+        // item or a statement may start, and not among a macro's tokens, which
+        // rustc does not read as one (ADR-0008, amended 2026-10-19).
+        const refused = () => {
+            if (!inMacro && startsAnItem(code, at)) {
+                note(collector, 'refused', at, 'a declaration that starts as a use or an extern crate is one rustc refuses, and no module is read from it');
             }
-            else if (char === ';' && depth === 0)
-                break;
-            end += 1;
+        };
+        const start = at + match[0].length;
+        if (match[0] !== 'use') {
+            const extern = externCrate(code, start);
+            if (extern !== null && !documented(extern.end))
+                emit(collector, extern.crate, 'use', at);
+            else
+                refused();
+            continue;
+        }
+        const { paths, end } = readUseTree(code, start);
+        const semicolon = rustToken(code, end);
+        if (paths === 'overflow') {
+            note(collector, 'truncated', at, `a use declaration expands to more than ${MAX_EXPANSION} module paths, or nests its groups deeper than that`);
         }
-        const expanded = expandUsePath(code.slice(start, end));
-        if (expanded === null) {
-            note(collector, 'truncated', match.index, `a use declaration expands to more than ${MAX_EXPANSION} module paths`);
+        else if (paths !== 'refused' &&
+            semicolon?.text === ';' &&
+            !documented(semicolon.end) &&
+            // A `$` name stands only in a macro's tokens, where it is read as the
+            // macro is expanded.
+            (inMacro || !paths.some(({ segments }) => segments.some((segment) => segment.startsWith('$'))))) {
+            for (const path of paths)
+                emit(collector, usePath(path), 'use', at);
         }
         else {
-            for (const specifier of expanded)
-                emit(collector, specifier, 'use', match.index);
+            refused();
         }
+        // On from where reading stopped, past the tree or at the token rustc
+        // would refuse, so that no token is read twice. No segment is `use` or
+        // `extern`, so no declaration is read into the next.
         RUST_USE.lastIndex = end;
     }
 }
 /* -------------------------------------------------------------------- c-sharp */
-/** Everything the C# reader stops at: a using, a namespace, or a brace. */
-const CSHARP_TOKEN = /\b(?:using|namespace)\b|[{}]/g;
+/** What C# lets continue an identifier beside a letter: a mark, a digit, a connector, a formatting character. */
+const CSHARP_PART = String.raw `\p{L}\p{Nl}\p{Mn}\p{Mc}\p{Nd}\p{Pc}\p{Cf}`;
+/** C#'s white space, and what ends a line. */
+const CSHARP_BLANK = String.raw `\p{Zs}\t\v\f`;
+const CSHARP_BREAK = String.raw `\r\n\u{85}\u{2028}\u{2029}`;
+/**
+ * Everything the C# reader stops at: a using, a namespace, or a brace. Each
+ * keyword is a whole word, so neither the identifier `@using` nor a word an
+ * escape goes on with.
+ */
+const CSHARP_TOKEN = new RegExp(String.raw `(?<![${CSHARP_PART}@\\])(?:using|namespace)(?![${CSHARP_PART}\\])|[{}]`, 'gu');
+/**
+ * A pre-processing directive, which takes the whole of its line, so that the
+ * message of a `#region` is no code.
+ */
+const CSHARP_DIRECTIVE = new RegExp(String.raw `^[${CSHARP_BLANK}]*#[^${CSHARP_BREAK}]*`, 'gmu');
+/**
+ * One token of a using directive or a namespace declaration, after any white
+ * space or end of a line, which a masked comment is too: a word, as an
+ * identifier and a keyword are both written, or a mark.
+ */
+const CSHARP_WORD = new RegExp(String.raw `[${CSHARP_BLANK}${CSHARP_BREAK}]*(?:(@?(?:[${CSHARP_PART}]|\\u[\dA-Fa-f]{4}|\\U[\dA-Fa-f]{8})+)|(::|[.;=<>,?*\[\](){}]))`, 'uy');
+const CSHARP_ESCAPE = /\\u([\dA-Fa-f]{4})|\\U([\dA-Fa-f]{8})/g;
+const CSHARP_IDENTIFIER = new RegExp(String.raw `^[\p{L}\p{Nl}_][${CSHARP_PART}]*$`, 'u');
+/**
+ * C#'s keywords (6.4.4, as read on 2026-10-19), which no identifier is
+ * unless written with `@`, or with an escape in it, which no keyword holds.
+ * Its contextual keywords, `global`, `var` and `dynamic` among them, are
+ * identifiers where a name stands.
+ */
+const CSHARP_KEYWORDS = new Set([
+    ...['abstract', 'as', 'base', 'bool', 'break', 'byte', 'case', 'catch', 'char', 'checked', 'class', 'const', 'continue'],
+    ...['decimal', 'default', 'delegate', 'do', 'double', 'else', 'enum', 'event', 'explicit', 'extern', 'false', 'finally'],
+    ...['fixed', 'float', 'for', 'foreach', 'goto', 'if', 'implicit', 'in', 'int', 'interface', 'internal', 'is', 'lock'],
+    ...['long', 'namespace', 'new', 'null', 'object', 'operator', 'out', 'override', 'params', 'private', 'protected'],
+    ...['public', 'readonly', 'ref', 'return', 'sbyte', 'sealed', 'short', 'sizeof', 'stackalloc', 'static', 'string'],
+    ...['struct', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'uint', 'ulong', 'unchecked', 'unsafe', 'ushort'],
+    ...['using', 'virtual', 'void', 'volatile', 'while'],
+]);
+/** The keywords that name a type (8.2.1, 8.3.1): `void` is one only before a `*`. */
+const CSHARP_TYPE_KEYWORDS = new Set([
+    ...['bool', 'byte', 'char', 'decimal', 'double', 'float', 'int', 'long', 'object', 'sbyte', 'short', 'string', 'uint'],
+    ...['ulong', 'ushort'],
+]);
+/**
+ * The identifier a word is, as C# compares two: with no `@`, each escape the
+ * character it stands for, and no formatting character. Null for a word that
+ * is no identifier: a digit first, or an escape of what no identifier holds.
+ */
+function csharpIdentifier(word) {
+    // A word holds an `@` only as its first character.
+    const decoded = word.replace('@', '').replace(CSHARP_ESCAPE, (_, short, long) => {
+        try {
+            return String.fromCodePoint(Number.parseInt(short ?? long, 16));
+        }
+        catch {
+            // \U can write a number no character has. A dot is no part of a name.
+            return '.';
+        }
+    });
+    return CSHARP_IDENTIFIER.test(decoded) ? decoded.replace(/\p{Cf}/gu, '') : null;
+}
+/** A cursor over the tokens of one directive or declaration. */
+class CsharpTokens {
+    text;
+    index;
+    /** How deep the type being read is. */
+    nesting = 0;
+    /** Whether a type nested deeper than MAX_EXPANSION, and was not read. */
+    overflow = false;
+    /** The name of each type read, in the order written: a type is its name, then its arguments. */
+    names = [];
+    constructor(text, index) {
+        this.text = text;
+        this.index = index;
+    }
+    next() {
+        CSHARP_WORD.lastIndex = this.index;
+        const match = CSHARP_WORD.exec(this.text);
+        return match === null ? null : { word: match[1], mark: match[2], end: CSHARP_WORD.lastIndex };
+    }
+    mark(mark) {
+        const token = this.next();
+        if (token?.mark !== mark)
+            return false;
+        this.index = token.end;
+        return true;
+    }
+    /** A keyword, as it is written: `@static`, and `static` with an escape in it, are identifiers. */
+    keyword(word) {
+        const token = this.next();
+        if (token?.word !== word)
+            return false;
+        this.index = token.end;
+        return true;
+    }
+    /**
+     * An identifier, which is never a keyword as it is written: so `using
+     * class.N;` names nothing, and a directive left open is never read on
+     * into the next, whose `using` or `namespace` is one.
+     */
+    identifier() {
+        const token = this.next();
+        const name = token?.word === undefined || CSHARP_KEYWORDS.has(token.word) ? null : csharpIdentifier(token.word);
+        if (name !== null)
+            this.index = token.end;
+        return name;
+    }
+    /** `name (. name)*`, the name of a namespace declaration. */
+    qualified() {
+        const parts = [];
+        for (let part = this.identifier(); part !== null; part = this.identifier()) {
+            parts.push(part);
+            if (!this.mark('.'))
+                return parts.join('.');
+        }
+        return null;
+    }
+    /**
+     * A namespace or type name, `(alias ::)? name (. name)*`, or null. What
+     * stands before `::` says where to look the name up, the global namespace
+     * or an extern alias, and is no part of it. Where `generic` allows them, a
+     * type argument list after a name is passed over.
+     */
+    name(generic) {
+        let part = this.identifier();
+        if (part !== null && this.mark('::'))
+            part = this.identifier();
+        const parts = [];
+        for (; part !== null; part = this.identifier()) {
+            parts.push(part);
+            if (generic && !this.typeArguments())
+                return null;
+            if (!this.mark('.'))
+                return parts.join('.');
+        }
+        return null;
+    }
+    /**
+     * Passes over a type argument list, `<` to the `>` that closes it, each
+     * argument a type and none a pointer, which the compiler refuses there;
+     * false where something else stands. Token by token, so it never reads
+     * past a `;`, a brace or the next directive.
+     */
+    typeArguments() {
+        if (!this.mark('<'))
+            return true;
+        do {
+            if (!this.type(false))
+                return false;
+        } while (this.mark(','));
+        return this.mark('>');
+    }
+    /**
+     * Passes over a type, as the specification has one (8.1 and 24.3): a
+     * tuple of two or more, a keyword that names a type, a function pointer
+     * or a name with its type arguments, then the marks of a nullable, an
+     * array and a pointer. A pointer, a function pointer among them, only where
+     * `pointers` lets one stand: in an alias that is `unsafe`, and never in a
+     * tuple or a type argument. False where the text is none, and where it
+     * nests deeper than MAX_EXPANSION, as a Rust use group may not, with
+     * `overflow` set: so no type nested twenty thousand deep runs the reader
+     * out of stack.
+     */
+    type(pointers) {
+        if (this.nesting >= MAX_EXPANSION) {
+            this.overflow = true;
+            return false;
+        }
+        this.nesting += 1;
+        const read = this.typeWithin(pointers);
+        this.nesting -= 1;
+        return read;
+    }
+    typeWithin(pointers) {
+        let pointer = false;
+        // Where no word is next, at the end of the text or before a mark, `''`
+        // is none of what a word is compared with, `delegate`, `void` and the
+        // type keywords: any other such string for it is an equivalent mutant.
+        const word = this.next()?.word ?? '';
+        if (this.mark('(')) {
+            let elements = 0;
+            do {
+                if (!this.type(false))
+                    return false;
+                // The name an element may have.
+                this.identifier();
+                elements += 1;
+            } while (this.mark(','));
+            if (elements < 2 || !this.mark(')'))
+                return false;
+        }
+        else if (word === 'delegate' || word === 'void') {
+            this.keyword(word);
+            if (!this.mark('*') || (word === 'delegate' && !this.functionPointer()))
+                return false;
+            pointer = true;
+        }
+        else if (CSHARP_TYPE_KEYWORDS.has(word)) {
+            this.keyword(word);
+        }
+        else {
+            // Before the names its arguments hold, which reading it put here.
+            const at = this.names.length;
+            const name = this.name(true);
+            if (name === null)
+                return false;
+            this.names.splice(at, 0, name);
+        }
+        for (;;) {
+            if (this.mark('?'))
+                continue;
+            if (this.mark('*')) {
+                pointer = true;
+                continue;
+            }
+            if (!this.mark('['))
+                return pointers || !pointer;
+            while (this.mark(','))
+                continue;
+            if (!this.mark(']'))
+                return false;
+        }
+    }
+    /**
+     * What follows `delegate*`: a calling convention or none, then `<`, the
+     * parameters, each `ref`, `ref readonly`, `in` or `out` or none, and the
+     * return type, `void` among them, then `>` (24.3.3).
+     */
+    functionPointer() {
+        if (this.keyword('unmanaged') && this.mark('[')) {
+            do {
+                if (this.identifier() === null)
+                    return false;
+            } while (this.mark(','));
+            if (!this.mark(']'))
+                return false;
+        }
+        else {
+            this.keyword('managed');
+        }
+        if (!this.mark('<'))
+            return false;
+        do {
+            if (this.keyword('ref'))
+                this.keyword('readonly');
+            else if (!this.keyword('in'))
+                this.keyword('out');
+            if (!this.keyword('void') && !this.type(true))
+                return false;
+        } while (this.mark(','));
+        return this.mark('>');
+    }
+}
+/**
+ * The namespaces and types a using directive names, read from after
+ * `using`, or null where C# would refuse it:
+ *
+ *   using static unsafe? type ;    using unsafe? alias = name-or-type ;    using namespace ;
+ *
+ * `global` before `using` changes nothing of it. A type is read whole: a
+ * name, then each type its arguments name, and each element of a tuple; a
+ * keyword that names a type, `int` or `string`, names nothing, and nor does
+ * a tuple element's own name, and an alias of a type that names nothing is
+ * no refusal. A using statement and a using declaration are none of these,
+ * and are read as nothing.
+ */
+function usingDirective(tokens) {
+    let target;
+    if (tokens.keyword('static')) {
+        tokens.keyword('unsafe');
+        const name = tokens.name(true);
+        target = name === null ? null : [name, ...tokens.names];
+    }
+    else {
+        const unsafe = tokens.keyword('unsafe');
+        const start = tokens.index;
+        if (tokens.identifier() !== null && tokens.mark('=')) {
+            // An alias may name any type (14.6.2), and a pointer of one where it
+            // is `unsafe`.
+            if (!tokens.type(unsafe))
+                return null;
+            target = tokens.names;
+        }
+        else if (unsafe) {
+            return null;
+        }
+        else {
+            tokens.index = start;
+            const name = tokens.name(false);
+            target = name === null ? null : [name];
+        }
+    }
+    // A type named twice, `G.L<G.L<int>>`, is one dependency. A refused
+    // directive stays null, not an empty list, which is what says it refused.
+    return tokens.mark(';') && target !== null ? [...new Set(target)] : null;
+}
+/**
+ * Whether the tokens after a `using` start a using statement or a using
+ * declaration, which top-level statements may hold where a directive may
+ * stand: `(`, or a type and the name of a local, `using var x = ...;` and
+ * `using N.D? d = null;` among them. Each is a statement the compiler reads
+ * as one, refused or not, and no directive it refuses.
+ */
+function startsAStatement(code, from) {
+    const tokens = new CsharpTokens(code, from);
+    return tokens.mark('(') || (tokens.type(true) && tokens.identifier() !== null);
+}
+const CSHARP_SPACE_CHARACTER = new RegExp(`[${CSHARP_BLANK}${CSHARP_BREAK}]`, 'u');
+const CSHARP_GLOBAL_BEFORE = new RegExp(String.raw `(?<![${CSHARP_PART}@\\])global$`, 'u');
+/**
+ * Whether a `using` at `at` stands where a directive may start: at the head
+ * of the file, after `;` or a brace, or after `global`. Where it follows
+ * anything else, `await` or an `)`, it starts a statement.
+ */
+function startsADirective(code, at) {
+    let before = at;
+    while (CSHARP_SPACE_CHARACTER.test(code[before - 1] ?? ''))
+        before -= 1;
+    return before === 0 || ';{}'.includes(code[before - 1]) || CSHARP_GLOBAL_BEFORE.test(code.slice(Math.max(0, before - 7), before));
+}
+/** The `#if` or `#endif` a pre-processing line is, or neither. */
+const CSHARP_CONDITION = new RegExp(String.raw `^[${CSHARP_BLANK}]*#[${CSHARP_BLANK}]*(if|endif)(?![${CSHARP_PART}])`, 'u');
+/**
+ * The half-open ranges from each outermost `#if` to the end of its `#endif`.
+ * The compiler skips the text of a section whose condition is false and reads
+ * none of it (6.5.5), and which condition holds is the build's to say: so a
+ * directive there is read as one anywhere else, and none is said to be
+ * refused. One left open runs to the end of the file.
+ */
+function conditionalRanges(code) {
+    const ranges = [];
+    let depth = 0;
+    let start = 0;
+    CSHARP_DIRECTIVE.lastIndex = 0;
+    let line;
+    while ((line = CSHARP_DIRECTIVE.exec(code)) !== null) {
+        const kind = CSHARP_CONDITION.exec(line[0])?.[1];
+        if (kind === 'if' && depth++ === 0)
+            start = line.index;
+        if (kind === 'endif' && depth > 0 && --depth === 0)
+            ranges.push([start, line.index + line[0].length]);
+    }
+    if (depth > 0)
+        ranges.push([start, code.length]);
+    return ranges;
+}
 /**
  * Reads using directives and the namespaces a file declares, in one pass.
  *
@@ -597,10 +1160,24 @@ const CSHARP_TOKEN = /\b(?:using|namespace)\b|[{}]/g;
  * the brace depth falls below its body's, so nothing here compares an offset
  * with the offset of a delimiter - which no keyword can ever sit on, and which
  * would leave `<` and `<=` meaning the same thing to every test. The code is
- * masked, so no brace in a string or a comment counts.
+ * masked, so no brace in a string, a comment or a pre-processing directive
+ * counts.
+ *
+ * A directive and a declaration are read token by token, as the C#
+ * specification has them (ADR-0008, amended 2026-10-18): white space and
+ * comments between the tokens, an identifier as C# compares two, and what
+ * C# refuses read as nothing. Each type a directive names is read whole,
+ * the types its arguments name and a tuple's elements among them, and each
+ * is a reference. What it refuses is said where it starts as a directive:
+ * in no brace but a namespace's, where a directive may start, where no
+ * statement does, and outside every `#if` (amended 2026-10-19).
  */
 function readCsharp(collector) {
-    const { code } = collector.masked;
+    // A byte order mark at the head of a file is no character of its text.
+    const marked = collector.masked.code.replace(/^\u{feff}/u, ' ');
+    const conditions = conditionalRanges(marked);
+    let condition = 0;
+    const code = marked.replace(CSHARP_DIRECTIVE, (line) => ' '.repeat(line.length));
     const declared = new Set();
     const open = [];
     let fileScoped;
@@ -619,52 +1196,47 @@ function readCsharp(collector) {
                 open.pop();
             continue;
         }
-        const reader = new Reader(code);
-        reader.index = match.index + token.length;
-        reader.skipSpace();
+        const tokens = new CsharpTokens(code, CSHARP_TOKEN.lastIndex);
         if (token === 'namespace') {
-            // `@namespace` is an identifier rather than the keyword, and no name
-            // follows it.
-            const name = reader.dotted();
-            if (name === '')
-                continue;
-            reader.skipSpace();
-            const outer = open.at(-1);
-            const full = outer === undefined ? name : `${outer.name}.${name}`;
-            // A file-scoped namespace covers the rest of the file, and C# allows
-            // neither a second one nor a block beside it.
-            if (reader.peek() === ';')
-                fileScoped = full;
-            else if (reader.peek() === '{')
-                open.push({ name: full, depth: depth + 1 });
-            else
-                continue;
-            declared.add(full);
-            continue;
+            const name = tokens.qualified();
+            if (name !== null) {
+                const scoped = tokens.mark(';');
+                if (scoped || tokens.mark('{')) {
+                    const outer = open.at(-1);
+                    const full = outer === undefined ? name : `${outer.name}.${name}`;
+                    // A file-scoped namespace covers the rest of the file, and C# allows
+                    // neither a second one nor a block beside it. A block's brace is
+                    // read here, and counted.
+                    if (scoped)
+                        fileScoped = full;
+                    else
+                        open.push({ name: full, depth: (depth += 1) });
+                    declared.add(full);
+                }
+            }
         }
-        if (reader.keyword('static'))
-            reader.skipSpace();
-        let target = reader.dotted();
-        reader.skipSpace();
-        // `using Alias = System.Text.Json;` - the dependency is the right-hand side.
-        if (reader.eat('=')) {
-            reader.skipSpace();
-            target = reader.dotted();
-            reader.skipSpace();
-            reader.skipGenerics();
-            reader.skipSpace();
+        else {
+            const targets = usingDirective(tokens);
+            // A section starts at the head of its `#if` line and ends at its
+            // `#endif` line's end, where no `using` starts: `<` for either `<=`
+            // is an equivalent mutant.
+            while (condition < conditions.length && conditions[condition][1] <= match.index)
+                condition += 1;
+            const conditional = condition < conditions.length && conditions[condition][0] <= match.index;
+            if (targets !== null) {
+                for (const target of targets)
+                    emit(collector, target, 'using', match.index, open.at(-1)?.name ?? fileScoped);
+            }
+            else if (tokens.overflow) {
+                note(collector, 'truncated', match.index, `a using directive nests its types deeper than ${MAX_EXPANSION}`);
+            }
+            else if (!conditional && depth === (open.at(-1)?.depth ?? 0) && startsADirective(code, match.index) && !startsAStatement(code, CSHARP_TOKEN.lastIndex)) {
+                note(collector, 'refused', match.index, 'a directive that starts as a using is one the C# compiler refuses, and no namespace is read from it');
+            }
         }
-        // The whole of what separates a directive from a resource statement, and
-        // it is one condition on purpose. `using (var s = ...)` reads no name at
-        // all and stops on `(`; `using var s = ...` reads `var` and then finds `s`
-        // where a terminator has to be. Earlier versions guarded those two shapes
-        // explicitly, and a third time against an empty name - none of the three
-        // changed an outcome, which mutation testing established by leaving the
-        // tests green with each of them defeated. `emit` refuses an empty
-        // specifier, so this line is the only check that has to be right.
-        if (reader.peek() !== ';')
-            continue;
-        emit(collector, target, 'using', match.index, open.at(-1)?.name ?? fileScoped);
+        // On from where reading stopped, so that no token is read twice. No name
+        // is `using` or `namespace`, so no directive is read into the next.
+        CSHARP_TOKEN.lastIndex = tokens.index;
     }
     collector.namespaces = [...declared];
 }