@redocly/recheck 0.15.0 → 2.58.0

package/dist/parser/markdoc/span.js

@@ -1,729 +0,0 @@
-// Pure, micromark-free parser for the interior of a single Markdoc
-// `{% ... %}` span: kind, name, attributes, and 0-based offsets into the span
-// text it was given. The tokenizer only locates span BOUNDARIES; all interior
-// structure comes from this single-pass scanner, which depends on no
-// document-level state and so is testable on plain strings.
-//
-// Invariant: never throws. A linter's primary input is broken documents, so
-// anything unparseable comes back as `kind: 'malformed'` with a
-// human-readable `reason`; callers always get a `ParsedMarkdocSpan`.
-//
-// Ground truth is the Markdoc RENDERER, not `tag.pegjs`'s raw grammar. The
-// renderer collapses every line ending to a single `\n` before the grammar's
-// whitespace rule runs, so a `\r\n` pair (or a lone `\r`) counts as ONE
-// whitespace unit here -- see `scanMarkdocSpaceUnit`.
-//
-// Deliberate divergences from upstream Markdoc follow. Unless noted, each is
-// a leniency: we accept what upstream rejects as a parse error.
-//
-// - Barewords: an unquoted identifier in a value slot (`{% t name=star %}`,
-//   `{% if maybe %}`) gets its own `'bareword'` kind and offsets so a rule can
-//   point at it, instead of collapsing the whole span to `malformed`.
-// - Annotation bodies are never parsed -- `kind: 'annotation'`, no
-//   `attributes`, no `shortcuts` -- an extension point for the LSP phase. So
-//   sigil-first bodies upstream rejects still classify as annotations here:
-//   `{% .a.b %}`, `{% . %}`, `{% .a junk %}`, `{% #a=1 %}`. (Shortcuts inside
-//   a NAMED tag are a different matter: those are fully parsed into
-//   `shortcuts` -- see `MarkdocShortcut`.)
-// - The attribute-first annotation form (`{% width="30%" %}`) does scan its
-//   body, so rather than adding a divergence it inherits the ones below:
-//   `{% a=1b=2 %}`, `{% a=1\fb=2 %}`, `{% a=fn(1,) %}`, `{% a="a\qb" %}` all
-//   classify as annotations. Genuinely broken bodies still land `malformed`
-//   (`{% a=b %}`, `{% a=1 b %}`, `{% width = "30%" %}`, `{% a="x" /%}`).
-// - Glued attributes: `{% t a=1b=2 %}` parses as two attributes. The
-//   separator guard in `scanAttributes` gates only its shortcut branch, not
-//   the plain attribute-name scan.
-// - `\f`/`\v` pass as an item separator, for attributes and shortcuts alike
-//   since both ride the same `scanAttributes` loop: `{% t a=1\fb=2 %}`,
-//   `{% t .a\f.b %}`. The one exception is the primary-to-first-attribute gap,
-//   which uses the strict `isMarkdocSpace`.
-// - Lenient strings: `scanString` validates nothing between the quotes beyond
-//   finding the closing `"`, so it accepts any `\<char>` escape
-//   (`{% a="a\qb" %}`) and a raw, unescaped newline inside the quotes. Shared
-//   by attribute values, array/object interiors, and a variable's bracket tail
-//   (`{% $foo["a\qb"] %}`).
-// - Array, object, and function interiors are only balanced and sliced, never
-//   validated. Upstream's `Function` production is the strict one, so
-//   `{% fn(1,) %}`, `{% fn(1 ) %}`, and the multiline `{% fn(\n 1,\n 2\n) %}`
-//   parse here but error upstream; the equivalent array forms
-//   (`{% t x=[1,] %}`) are upstream-valid anyway.
-// - `{%- -%}` trim markers are stripped and ignored; `tag.pegjs` has no such
-//   syntax.
-// - A self-close marker on a top-level value parses as a plain
-//   `variable`/`function`: `{% $foo/%}`, `{% @foo.bar/%}`, `{% $foo["a"]/%}`,
-//   `{% equals(1,1)/%}`. The shared pre-dispatch scan strips the marker before
-//   the first character is examined.
-// - Close tags may carry a parsed attribute list, though `TagClose` upstream
-//   is just `'/' tag:TagName`.
-// - Duplicate attributes are never flagged. `{% t a=1 a=2 %}`, `{% t #a #b %}`,
-//   `{% t #a id="b" %}`, and `{% t .a class="b" %}` are all upstream
-//   `duplicate-attribute` warnings; detecting them needs the schema-level
-//   `class`/`id` view with shortcuts folded in, which only a schema-aware rule
-//   has. Note two shortcuts naming the same class (`{% t .a .a %}`) is clean
-//   upstream too -- they merge into one `class` entry.
-// - Keyword literals are the one SHAPE-only divergence: `null`/`true`/`false`
-//   match boundary-free upstream but as maximal identifiers here, so
-//   accept/reject agrees while the parse differs on keyword-prefixed names.
-//   Upstream reads `{% t nullable=true %}` as attribute `{able: true}` and
-//   `{% t truey=1 %}` as primary `true` plus `{y: 1}`; this keeps the whole
-//   identifier (`nullable`/`truey`). In value position it becomes a bareword.
-function isSpace(ch) {
-    return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r' || ch === '\f' || ch === '\v';
-}
-// Markdoc's own grammar whitespace class: exactly space/tab/newline, narrower
-// than `isSpace` above. Used for the primary-to-first-attribute gap, where the
-// grammar allows at most one whitespace character.
-function isMarkdocSpace(ch) {
-    return ch === ' ' || ch === '\t' || ch === '\n';
-}
-/**
- * Consumes ONE Markdoc whitespace unit starting at `pos`. Markdoc's grammar
- * runs after the renderer has collapsed every line ending to a single '\n', so
- * a '\r\n' pair or a lone '\r' each count as one unit here despite spanning two
- * raw characters. Recheck deliberately does not normalize span text (see
- * `core/line-endings.ts`), hence the collapse by hand.
- *
- * Returns `pos` unchanged if no unit starts there -- notably for '\f'/'\v',
- * which are outside Markdoc's whitespace class and must not be consumed here.
- */
-function scanMarkdocSpaceUnit(text, pos, end) {
-    if (pos >= end)
-        return pos;
-    const ch = text[pos];
-    if (isMarkdocSpace(ch))
-        return pos + 1;
-    if (ch === '\r')
-        return pos + 1 < end && text[pos + 1] === '\n' ? pos + 2 : pos + 1;
-    return pos;
-}
-function isDigit(ch) {
-    return ch !== undefined && ch >= '0' && ch <= '9';
-}
-function isAlpha(ch) {
-    return ch !== undefined && ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z'));
-}
-// Markdoc's `Identifier` is a single uniform `[a-zA-Z0-9_-]+` class with no
-// distinct "start" rule, so digit-leading (`1x`) and dash-leading (`-x`) names
-// are legal for tags and attributes alike. Hence this accepts exactly the same
-// characters as `isIdentChar`.
-function isIdentStart(ch) {
-    return isAlpha(ch) || isDigit(ch) || ch === '_' || ch === '-';
-}
-function isIdentChar(ch) {
-    return isAlpha(ch) || isDigit(ch) || ch === '_' || ch === '-';
-}
-/** Scans `[A-Za-z0-9_-]+` starting at `pos`. Returns `pos` unchanged if no identifier starts there. */
-function scanIdentifier(text, pos, end) {
-    let p = pos;
-    if (p < end && isIdentStart(text[p])) {
-        p++;
-        while (p < end && isIdentChar(text[p]))
-            p++;
-    }
-    return p;
-}
-/**
- * Scans a bracketed run (`[...]`, `{...}`, or `(...)`) starting at `pos`,
- * skipping quoted string contents so brackets inside strings
- * (`{title: "a]b"}`) don't miscount. Only the outer pair's own characters need
- * counting: a mismatched nested pair can't affect when the outer bracket
- * closes, and nested same-type pairs still balance correctly.
- *
- * Returns the position just past the matching close bracket, or -1 if the text
- * ends before the brackets balance.
- */
-function scanBalanced(text, pos, end, open, close) {
-    let depth = 0;
-    let p = pos;
-    while (p < end) {
-        const ch = text[p];
-        if (ch === '"' || ch === "'") {
-            const quote = ch;
-            p++;
-            while (p < end && text[p] !== quote) {
-                p += text[p] === '\\' && p + 1 < end ? 2 : 1;
-            }
-            if (p >= end)
-                return -1; // unterminated string inside the bracketed value
-            p++; // consume the closing quote
-            continue;
-        }
-        if (ch === open) {
-            depth++;
-            p++;
-            continue;
-        }
-        if (ch === close) {
-            depth--;
-            p++;
-            if (depth === 0)
-                return p;
-            continue;
-        }
-        p++;
-    }
-    return -1; // never balanced
-}
-/** Scans a double-quoted string starting at `text[pos] === '"'`, decoding `\"` and `\\` escapes. */
-function scanString(text, pos, end) {
-    let p = pos + 1;
-    let decoded = '';
-    while (p < end) {
-        const ch = text[p];
-        if (ch === '"') {
-            return { kind: 'string', value: decoded, endPos: p + 1 };
-        }
-        if (ch === '\\' && p + 1 < end) {
-            const next = text[p + 1];
-            decoded += next === '"' || next === '\\' ? next : `\\${next}`;
-            p += 2;
-            continue;
-        }
-        decoded += ch;
-        p++;
-    }
-    return null; // unterminated string
-}
-/**
- * Scans Markdoc's `ValueNumber`, `'-'? [0-9]+ ('.'[0-9]+)?`. Notably NOT a
- * JSON/JavaScript number: the grammar has no exponent alternative, so the `e`
- * in `2e3` is not part of the number and `{% img scale=2e3 %}` is an upstream
- * parse error. Matching that greed exactly is what makes leftover text land in
- * the next slot the way it does upstream.
- *
- * Caller has already confirmed a digit (or `-` + digit) at `pos`.
- */
-function scanNumber(text, pos, end) {
-    let p = pos;
-    if (text[p] === '-')
-        p++;
-    while (p < end && isDigit(text[p]))
-        p++;
-    if (text[p] === '.' && isDigit(text[p + 1])) {
-        p++;
-        while (p < end && isDigit(text[p]))
-            p++;
-    }
-    return { kind: 'number', value: Number(text.slice(pos, p)), endPos: p };
-}
-/**
- * Scans zero or more Markdoc `VariableTail` segments starting at `pos`:
- * `'.' Identifier` or `'[' (ValueNumber | ValueString) ']'`. Shared by a
- * `$`/`@` variable's value position and its top-level position, because
- * upstream reuses the one production for both.
- *
- * Neither alternative allows any whitespace -- not around the `.`, not inside
- * the brackets -- and a bracket's contents must be exactly a number or a
- * string, never a bare identifier or an expression. So `$foo[bar]`,
- * `$foo[ 0 ]`, and `$foo[]` are upstream errors while `$foo[0]`, `$foo["bar"]`,
- * and chains like `$foo.bar["x"].baz` are fine.
- *
- * A segment that fails to match consumes nothing, leaving `pos` at the start of
- * the offending segment so the caller's trailing-content check rejects it. That
- * is how a trailing dot (`$foo.`) or doubled dot (`$foo..bar`) is caught.
- *
- * Returns `pos` unchanged if no tail segment starts there.
- */
-function scanVariableTail(text, pos, end) {
-    let p = pos;
-    for (;;) {
-        if (text[p] === '.') {
-            const segEnd = scanIdentifier(text, p + 1, end);
-            if (segEnd === p + 1)
-                break;
-            p = segEnd;
-            continue;
-        }
-        if (text[p] === '[') {
-            const bracketValueStart = p + 1;
-            let valueEnd;
-            if (text[bracketValueStart] === '"') {
-                const str = scanString(text, bracketValueStart, end);
-                if (!str)
-                    break; // unterminated string inside the brackets
-                valueEnd = str.endPos;
-            }
-            else if (isDigit(text[bracketValueStart]) ||
-                (text[bracketValueStart] === '-' && isDigit(text[bracketValueStart + 1]))) {
-                valueEnd = scanNumber(text, bracketValueStart, end).endPos;
-            }
-            else {
-                break; // bracket contents are neither a ValueNumber nor a ValueString
-            }
-            if (text[valueEnd] !== ']')
-                break;
-            p = valueEnd + 1;
-            continue;
-        }
-        break;
-    }
-    return p;
-}
-/**
- * Scans one value at `pos`, recognizing exactly Markdoc's `Value` production
- * and nothing more: quoted string, number, `true`/`false`/`null`, `$`/`@`
- * variable[.path], `identifier(...)` function call, balanced `[...]` array, or
- * balanced `{...}` object. A bare unquoted identifier (the `star` in
- * `name=star`) is deliberately NOT recognized here, since `Value` has no such
- * alternative upstream -- see `scanBareword`.
- *
- * Returns `null` if no `Value` starts at `pos`.
- */
-function scanValue(text, pos, end) {
-    const ch = text[pos];
-    if (ch === '"')
-        return scanString(text, pos, end);
-    // `$` and `@` are two prefixes of the same upstream `Variable` production, so
-    // a value in attribute or primary position accepts either (`{% t x=@foo /%}`).
-    if (ch === '$' || ch === '@') {
-        const identEnd = scanIdentifier(text, pos + 1, end);
-        if (identEnd === pos + 1)
-            return null; // '$'/'@' not followed by an identifier
-        const p = scanVariableTail(text, identEnd, end);
-        return { kind: 'variable', value: text.slice(pos, p), endPos: p };
-    }
-    if (isDigit(ch) || (ch === '-' && isDigit(text[pos + 1]))) {
-        return scanNumber(text, pos, end);
-    }
-    if (ch === '[') {
-        const closeEnd = scanBalanced(text, pos, end, '[', ']');
-        return closeEnd === -1
-            ? null
-            : { kind: 'array', value: text.slice(pos, closeEnd), endPos: closeEnd };
-    }
-    if (ch === '{') {
-        const closeEnd = scanBalanced(text, pos, end, '{', '}');
-        return closeEnd === -1
-            ? null
-            : { kind: 'object', value: text.slice(pos, closeEnd), endPos: closeEnd };
-    }
-    if (isIdentStart(ch)) {
-        const identEnd = scanIdentifier(text, pos, end);
-        const word = text.slice(pos, identEnd);
-        if (word === 'true')
-            return { kind: 'boolean', value: true, endPos: identEnd };
-        if (word === 'false')
-            return { kind: 'boolean', value: false, endPos: identEnd };
-        if (word === 'null')
-            return { kind: 'null', value: null, endPos: identEnd };
-        if (text[identEnd] === '(') {
-            const closeEnd = scanBalanced(text, identEnd, end, '(', ')');
-            return closeEnd === -1
-                ? null
-                : { kind: 'function', value: text.slice(pos, closeEnd), endPos: closeEnd };
-        }
-    }
-    return null;
-}
-/**
- * A bare unquoted identifier in a value slot (`name=star`, `{% if maybe %}`).
- * Markdoc rejects these outright; recognizing the shape anyway -- instead of
- * collapsing the whole span to `malformed` -- is what lets a rule point at the
- * offending value and say "quote it".
- *
- * The identifier scanned is the maximal `[A-Za-z0-9_-]+` run, so a
- * keyword-prefixed word like `nullx` is one bareword here where upstream
- * prefix-matches `null` and then fails on the leftover. Either way the span is
- * one Markdoc rejects, and the bareword reading is the actionable one.
- */
-function scanBareword(text, pos, end) {
-    const identEnd = scanIdentifier(text, pos, end);
-    if (identEnd === pos)
-        return null;
-    return { kind: 'bareword', value: text.slice(pos, identEnd), endPos: identEnd };
-}
-/**
- * Detects Markdoc's positional value slot right after the tag name
- * (`{% if $flag %}`, `{% image "a.png" /%}`). Upstream attempts a plain `Value`
- * there BEFORE the attribute list and with no lookahead for a following `=`:
- * whatever `Value` matches, it takes, and the attribute list starts at the
- * leftover text. That greed shows wherever a `Value` is a strict prefix of an
- * identifier:
- *
- *   `{% icon 1x="star" %}` -> primary number `1`, then attribute `x="star"`
- *   `{% t 123="x" %}`      -> primary number `123`, then `="x"` is a parse error
- *   `{% t null=1 %}`       -> primary `null`, then `=1` is a parse error
- *
- * so a digit run must be consumed as a number here, not as the head of a `1x=`
- * attribute name. An identifier in a non-first slot has no `Value` attempt in
- * front of it, which is why `1bar="b"` is a legal attribute in
- * `{% x foo="a" 1bar="b" %}`.
- *
- * When `Value` matches nothing the slot holds a bare identifier, which Markdoc
- * rejects either way, so we pick the reading a rule can act on: an identifier
- * followed by `=` is reported as the first ATTRIBUTE's name -- including across
- * whitespace, so `{% t a = 1 %}` is diagnosed as the `=`-spacing error it is
- * rather than a bareword primary trailed by junk. Any other identifier becomes
- * a bareword primary.
- *
- * Returns `null` if nothing recognizable starts at `pos`.
- */
-function scanPrimaryValue(text, pos, end) {
-    const value = scanValue(text, pos, end);
-    if (value)
-        return value;
-    const bareword = scanBareword(text, pos, end);
-    if (!bareword)
-        return null;
-    let p = bareword.endPos;
-    while (p < end && isSpace(text[p]))
-        p++;
-    if (p < end && text[p] === '=')
-        return null; // "name=..." starts attributes
-    return bareword;
-}
-const NO_SPACES_AROUND_EQUALS = "Markdoc allows no spaces around an attribute's '='";
-/**
- * Scans `identifier=value` pairs and (when `allowShortcuts`) `.class`/`#id`
- * shortcuts, whitespace-separated, from `startPos` to `end`. Stops successfully
- * at `end`, or reports the first syntax error it finds.
- *
- * Markdoc puts no whitespace rule on either side of an attribute's `=`, so
- * `a = 1`, `a= 1`, and `a =1` are all parse errors and `a=1` is the only
- * accepted spelling. Whitespace separates one attribute from the next, never a
- * name from its own value.
- *
- * `leadingIsSpace` governs only the FIRST whitespace skip (the gap before the
- * first item this call sees); later gaps always use the lax `isSpace`. The
- * primary-value caller passes the strict `isMarkdocSpace` because it has
- * already consumed the one grammar-legal whitespace unit into `startPos`, so
- * this skip should find nothing and must not swallow a stray '\f'/'\v'.
- *
- * `allowShortcuts` is `false` for close tags and `true` for named
- * tag-open/self-closing spans, where upstream puts shortcuts and named
- * attributes in the same item slot. `sawItem` tracks whether this call has
- * produced an item yet: the first item may follow zero separating whitespace
- * (the caller has already arranged that before `startPos`), but a SHORTCUT
- * after the first item requires at least one whitespace unit. When that
- * separator is missing, the loop deliberately skips the shortcut branch and
- * falls through to the attribute-name scan, which fails on the sigil and so
- * reproduces upstream's rejection of `{% t .a.b %}`, `{% t .a#b %}`, and
- * `{% t b=1.a %}` for free. The guard covers only shortcuts -- glued named
- * attributes still both parse (see the header ledger).
- */
-function scanAttributes(text, startPos, end, leadingIsSpace = isSpace, allowShortcuts = false) {
-    const attributes = [];
-    const shortcuts = [];
-    let pos = startPos;
-    let isSpaceHere = leadingIsSpace;
-    let sawItem = false;
-    for (;;) {
-        const beforeSkip = pos;
-        while (pos < end && isSpaceHere(text[pos]))
-            pos++;
-        const skippedSeparator = pos > beforeSkip;
-        isSpaceHere = isSpace;
-        if (pos >= end)
-            return { pos, error: null, attributes, shortcuts };
-        const ch = text[pos];
-        if (allowShortcuts && (ch === '.' || ch === '#') && (!sawItem || skippedSeparator)) {
-            const sigilStart = pos;
-            const shortcutNameStart = pos + 1;
-            const shortcutNameEnd = scanIdentifier(text, shortcutNameStart, end);
-            if (shortcutNameEnd === shortcutNameStart) {
-                return {
-                    pos,
-                    error: `expected an identifier after "${ch}"`,
-                    attributes,
-                    shortcuts,
-                };
-            }
-            shortcuts.push({
-                kind: ch === '.' ? 'class' : 'id',
-                name: text.slice(shortcutNameStart, shortcutNameEnd),
-                start: sigilStart,
-                end: shortcutNameEnd,
-            });
-            pos = shortcutNameEnd;
-            sawItem = true;
-            continue;
-        }
-        const nameStart = pos;
-        const nameEnd = scanIdentifier(text, pos, end);
-        if (nameEnd === nameStart) {
-            return {
-                pos,
-                error: `expected an attribute name`,
-                attributes,
-                shortcuts,
-            };
-        }
-        const name = text.slice(nameStart, nameEnd);
-        pos = nameEnd;
-        if (pos >= end || text[pos] !== '=') {
-            return {
-                pos,
-                error: pos < end && isSpace(text[pos])
-                    ? `expected '=' immediately after attribute name "${name}" (${NO_SPACES_AROUND_EQUALS})`
-                    : `expected '=' after attribute name "${name}"`,
-                attributes,
-                shortcuts,
-            };
-        }
-        pos++; // consume '='
-        if (pos >= end) {
-            return {
-                pos,
-                error: `expected a value after '=' for attribute "${name}"`,
-                attributes,
-                shortcuts,
-            };
-        }
-        if (isSpace(text[pos])) {
-            return {
-                pos,
-                error: `expected a value immediately after '=' for attribute "${name}" (${NO_SPACES_AROUND_EQUALS})`,
-                attributes,
-                shortcuts,
-            };
-        }
-        const valueStart = pos;
-        const scanned = scanValue(text, pos, end) ?? scanBareword(text, pos, end);
-        if (!scanned) {
-            return {
-                pos,
-                error: `unrecognized attribute value`,
-                attributes,
-                shortcuts,
-            };
-        }
-        attributes.push({
-            name,
-            valueKind: scanned.kind,
-            value: scanned.value,
-            nameStart,
-            nameEnd,
-            valueStart,
-            valueEnd: scanned.endPos,
-        });
-        pos = scanned.endPos;
-        sawItem = true;
-    }
-}
-function malformed(reason, reasonOffset) {
-    return {
-        kind: 'malformed',
-        name: null,
-        attributes: [],
-        nameStart: 0,
-        nameEnd: 0,
-        reason,
-        ...(reasonOffset === undefined ? {} : { reasonOffset }),
-    };
-}
-/**
- * The one shape every annotation classifies to, whichever entry point
- * recognized it: no tag name and a deliberately unparsed body.
- */
-function annotation() {
-    return { kind: 'annotation', name: null, attributes: [], nameStart: 0, nameEnd: 0 };
-}
-/**
- * Parses one Markdoc `{% ... %}` span's text into its kind, name,
- * attributes, and offsets. `spanText` is expected to be exactly the span
- * (e.g. as recognized by the tokenizer) -- offsets in the result are
- * 0-based indexes into this same string. Never throws; unparseable input
- * comes back as `{ kind: 'malformed', reason }`.
- */
-export function parseMarkdocSpan(spanText) {
-    if (!spanText.startsWith('{%')) {
-        return malformed("span text does not start with the opening delimiter '{%'");
-    }
-    if (!spanText.endsWith('%}')) {
-        return malformed("span text has no closing '%}' delimiter");
-    }
-    let start = 2;
-    let end = spanText.length - 2;
-    // `{%-`/`-%}` whitespace-trim markers. The `end - 1 >= start` guard
-    // stops a single `-` sitting exactly between the delimiters (e.g. the
-    // degenerate `{%-%}`) from being consumed by both checks.
-    if (spanText[start] === '-')
-        start++;
-    if (end - 1 >= start && spanText[end - 1] === '-')
-        end--;
-    if (start > end) {
-        return malformed('span delimiters leave no room for a body');
-    }
-    // A trailing `/` (before the close delimiter, whitespace-trim markers
-    // already stripped) marks a self-closing tag, e.g. `{% partial ... /%}`.
-    let bodyEnd = end;
-    let selfClosing = false;
-    while (bodyEnd > start && isSpace(spanText[bodyEnd - 1]))
-        bodyEnd--;
-    if (bodyEnd > start && spanText[bodyEnd - 1] === '/') {
-        selfClosing = true;
-        bodyEnd--;
-        while (bodyEnd > start && isSpace(spanText[bodyEnd - 1]))
-            bodyEnd--;
-    }
-    let pos = start;
-    while (pos < bodyEnd && isSpace(spanText[pos]))
-        pos++;
-    if (pos >= bodyEnd) {
-        return malformed('span body is empty or contains only whitespace');
-    }
-    const first = spanText[pos];
-    // Close tag: `{% /name %}`.
-    if (first === '/') {
-        const nameStart = pos + 1;
-        const nameEnd = scanIdentifier(spanText, nameStart, bodyEnd);
-        if (nameEnd === nameStart) {
-            return malformed('close tag is missing a tag name after "/"', nameStart);
-        }
-        const scanned = scanAttributes(spanText, nameEnd, bodyEnd);
-        if (scanned.error)
-            return malformed(scanned.error, scanned.pos);
-        if (scanned.pos !== bodyEnd) {
-            return malformed('unexpected trailing content in close tag', scanned.pos);
-        }
-        return {
-            kind: 'tag-close',
-            name: spanText.slice(nameStart, nameEnd),
-            attributes: scanned.attributes,
-            nameStart,
-            nameEnd,
-        };
-    }
-    // Annotation, sigil-first form: `{% #id .class ... %}`. The name is null (an
-    // annotation has no tag name) and the body is left unparsed. The
-    // attribute-first form of the same production sits further down, after the
-    // variable/function branches, because upstream tries top-level values first.
-    if (first === '#' || first === '.') {
-        return annotation();
-    }
-    // Variable interpolation: `{% $name %}` / `{% @name %}`, plus any dotted or
-    // bracket-indexed tail (`{% $frontmatter.title %}`, `{% @foo["bar"].baz %}`).
-    // `$` and `@` are two prefixes of the same upstream production, not two
-    // shapes, so both classify as `'variable'` with identical handling. The tail
-    // is not broken out into structured internals -- that is an LSP-phase concern.
-    if (first === '$' || first === '@') {
-        const identStart = pos + 1;
-        const identEnd = scanIdentifier(spanText, identStart, bodyEnd);
-        if (identEnd === identStart) {
-            return malformed(`variable interpolation is missing a name after "${first}"`, identStart);
-        }
-        let p = scanVariableTail(spanText, identEnd, bodyEnd);
-        while (p < bodyEnd && isSpace(spanText[p]))
-            p++;
-        if (p !== bodyEnd) {
-            return malformed('unexpected trailing content after variable interpolation', p);
-        }
-        return { kind: 'variable', name: null, attributes: [], nameStart: 0, nameEnd: 0 };
-    }
-    // Bare top-level function call: `{% equals(1,1) %}`, the other half of the
-    // same upstream production as the variable branch above. The `(` must be
-    // glued to the identifier: `{% fn (1) %}` is an upstream error, and here it
-    // falls through to the tag-name branch below, which fails on the stray `(`
-    // naturally. Once the glued shape IS seen, upstream commits to a function
-    // with no fallback to a tag-name reading (`{% fn(1) junk %}` and
-    // `{% fn(1)/%}` are both errors there), so this must short-circuit ahead of
-    // that branch. Interiors stay opaque, matching function values elsewhere.
-    if (isIdentStart(first)) {
-        const funcNameEnd = scanIdentifier(spanText, pos, bodyEnd);
-        if (spanText[funcNameEnd] === '(') {
-            const closeEnd = scanBalanced(spanText, funcNameEnd, bodyEnd, '(', ')');
-            if (closeEnd === -1) {
-                return malformed('unterminated function call parentheses', funcNameEnd);
-            }
-            let p = closeEnd;
-            while (p < bodyEnd && isSpace(spanText[p]))
-                p++;
-            if (p !== bodyEnd) {
-                return malformed('unexpected trailing content after function interpolation', p);
-            }
-            return { kind: 'function', name: null, attributes: [], nameStart: 0, nameEnd: 0 };
-        }
-    }
-    // Annotation, attribute-first form: `{% width="30%" %}`,
-    // `{% colspan=2 align="center" %}`, `{% class="x" #id .cls %}`. Upstream
-    // tries its annotation production -- a bare attribute list with no leading
-    // tag name -- BEFORE tag-open, so a body that is nothing but attributes and
-    // shortcuts is a valid annotation there, never a tag whose name happens to be
-    // followed by `=`. This branch's position between the variable/function
-    // branches and the tag-name branch reproduces that ordering.
-    //
-    // Because an annotation body is unparsed by design, nothing downstream would
-    // report a problem inside one. Three conditions therefore narrow the branch
-    // to genuinely upstream-valid bodies so it can never launder a real error
-    // into a silent `annotation`:
-    // - The whole body must be consumed with no scan error. A trailing bareword
-    //   (`{% a=1 b %}`), a stray value (`{% a=1 "str" %}`), or a spaced `=`
-    //   (`{% width = "30%" %}`) falls through to the tag-name reading and lands
-    //   `malformed`, as upstream also rejects all three.
-    // - No bareword values. An attribute's value must be a real `Value` upstream,
-    //   so `{% a=b %}` is an error there. The bareword leniency exists to give a
-    //   better diagnostic inside an otherwise well-formed named tag; here it
-    //   would only hide an error, so the probe rejects it.
-    // - Not self-closing. Only tag-open has a self-close alternative upstream, so
-    //   `{% a="x" /%}` must stay `malformed`. The sigil-first branch above has no
-    //   such gate -- `{% .foo /%}` still classifies as an annotation -- which is
-    //   the pre-existing leniency of its unparsed body, left as-is.
-    //
-    // `isIdentStart(first)` gates the branch because the sigils are already
-    // claimed above, which also makes the first item scanned here necessarily an
-    // attribute.
-    if (!selfClosing && isIdentStart(first)) {
-        const probe = scanAttributes(spanText, pos, bodyEnd, isSpace, true);
-        if (!probe.error &&
-            probe.pos === bodyEnd &&
-            !probe.attributes.some((attribute) => attribute.valueKind === 'bareword')) {
-            return annotation();
-        }
-    }
-    // Otherwise it must be an open/self-closing tag: `{% name attr=val ... %}`,
-    // optionally with a positional primary value right after the name:
-    // `{% name primaryValue attr=val ... %}` (e.g. `{% if $flag %}`).
-    if (isIdentStart(first)) {
-        const nameStart = pos;
-        const nameEnd = scanIdentifier(spanText, nameStart, bodyEnd);
-        let afterPos = nameEnd;
-        while (afterPos < bodyEnd && isSpace(spanText[afterPos]))
-            afterPos++;
-        let primary;
-        let attrStart = nameEnd;
-        const primaryScan = scanPrimaryValue(spanText, afterPos, bodyEnd);
-        if (primaryScan) {
-            primary = {
-                valueKind: primaryScan.kind,
-                value: primaryScan.value,
-                valueStart: afterPos,
-                valueEnd: primaryScan.endPos,
-            };
-            // Exactly one optional whitespace character may separate the primary from
-            // the attribute list, where every other gap in the grammar allows any
-            // number. So `{% t 1 x="y" %}` parses but `{% t 1  x="y" %}` is an
-            // upstream error, as is a primary followed by a newline plus indentation.
-            // (`bodyEnd` is already right-trimmed, so leftover whitespace here is
-            // always followed by more content, never by the delimiter.)
-            attrStart = primaryScan.endPos;
-            const afterOneUnit = scanMarkdocSpaceUnit(spanText, attrStart, bodyEnd);
-            if (afterOneUnit > attrStart) {
-                attrStart = afterOneUnit;
-                if (scanMarkdocSpaceUnit(spanText, attrStart, bodyEnd) > attrStart) {
-                    return malformed("only one whitespace character may separate a tag's primary value from its first attribute", attrStart);
-                }
-            }
-        }
-        // The strict `isMarkdocSpace` (not the lax default) stops a stray '\f'/'\v'
-        // right after the primary from being skipped as if it were legal
-        // whitespace: `attrStart` has already consumed the one grammar-legal unit,
-        // so such a character should fail the attribute-name scan instead.
-        const scanned = scanAttributes(spanText, attrStart, bodyEnd, primary ? isMarkdocSpace : isSpace, true);
-        if (scanned.error)
-            return malformed(scanned.error, scanned.pos);
-        if (scanned.pos !== bodyEnd) {
-            return malformed('unexpected trailing content in tag', scanned.pos);
-        }
-        return {
-            kind: selfClosing ? 'tag-self-closing' : 'tag-open',
-            name: spanText.slice(nameStart, nameEnd),
-            attributes: scanned.attributes,
-            nameStart,
-            nameEnd,
-            ...(primary ? { primary } : {}),
-            ...(scanned.shortcuts.length ? { shortcuts: scanned.shortcuts } : {}),
-        };
-    }
-    return malformed(`unexpected character "${first}"`, pos);
-}
-//# sourceMappingURL=span.js.map