@mirascript/textmate 0.1.82 → 0.1.84

package/src/index.ts

@@ -0,0 +1,10 @@
+import type { LanguageRegistration } from '@shikijs/types';
+import { createMiraScriptDocGrammar, createMiraScriptGrammar, createMiraScriptTemplateGrammar } from './grammar.ts';
+
+export const mirascript = createMiraScriptGrammar();
+export const mirascriptTemplate = createMiraScriptTemplateGrammar();
+export const mirascriptDoc = createMiraScriptDocGrammar();
+
+export { mirascriptTemplate as 'mirascript-template', mirascriptDoc as 'mirascript-doc' };
+
+export const grammars: LanguageRegistration[] = [mirascript, mirascriptTemplate, mirascriptDoc];

package/src/language.ts

@@ -0,0 +1,21 @@
+import type { LanguageRegistration } from '@shikijs/types';
+
+/** Shared TextMate language metadata. */
+export type LanguageMetadata = Pick<LanguageRegistration, 'name' | 'aliases' | 'scopeName'>;
+
+export const mirascriptLanguage = {
+    name: 'mirascript',
+    aliases: ['MiraScript', 'mira', 'Mira'],
+    scopeName: 'source.mira',
+} satisfies LanguageMetadata;
+
+export const mirascriptTemplateLanguage = {
+    name: 'mirascript-template',
+    aliases: ['MiraScript-Template', 'miratpl', 'MiraTpl'],
+    scopeName: 'text.miratpl',
+} satisfies LanguageMetadata;
+
+export const mirascriptDocLanguage = {
+    name: 'mirascript-doc',
+    scopeName: 'source.mira.doc',
+} satisfies LanguageMetadata;

package/tests/_engine.ts

@@ -0,0 +1,53 @@
+import { createHighlighter, type Highlighter } from 'shiki';
+import { INITIAL, type StateStack } from 'shiki/textmate';
+import test, { type ExecutionContext } from 'ava';
+import { grammars } from '../src/index.ts';
+
+let highlighter: Highlighter;
+
+test.before(async () => {
+    highlighter = await createHighlighter({
+        langs: grammars,
+        themes: [],
+    });
+});
+
+test.after.always(() => highlighter.dispose());
+
+/**
+ * Tokenize complete source while preserving TextMate state across lines.
+ */
+export function tokenize(
+    code: string,
+    language = 'mirascript',
+): Array<{ line: number; text: string; scopes: string[] }> {
+    const grammar = highlighter.getLanguage(language);
+    let state: StateStack = INITIAL;
+    return code.split('\n').flatMap((line, lineIndex) => {
+        const result = grammar.tokenizeLine(line, state);
+        state = result.ruleStack;
+        return result.tokens.map((token) => ({
+            line: lineIndex,
+            text: line.slice(token.startIndex, token.endIndex),
+            scopes: token.scopes,
+        }));
+    });
+}
+
+/**
+ * Assert that a selected textual token contains the expected scope.
+ */
+export function expectScope(
+    t: ExecutionContext,
+    tokens: Array<{ text: string; scopes: string[] }>,
+    text: string,
+    scope: string,
+    occurrence = 0,
+): void {
+    const matching = tokens.filter((token) => token.text === text);
+    t.true(matching.length > occurrence, `Missing token ${JSON.stringify(text)} #${occurrence}`);
+    t.true(
+        matching[occurrence].scopes.includes(scope),
+        `${JSON.stringify(text)} should include ${scope}; got ${matching[occurrence].scopes.join(', ')}`,
+    );
+}

package/tests/grammar/documentation-comments.ts

@@ -0,0 +1,157 @@
+import test from 'ava';
+import { mirascriptLanguage } from '../../src/language.ts';
+import { tokenize, expectScope } from '../_engine.ts';
+
+test('separates documentation prefixes from bold and italic markup', (t) => {
+    const tokens = tokenize(
+        [
+            '/**',
+            ' * - *a*: 第一个操作数',
+            ' * - **b**: 第二个操作数',
+            ' * ```mirascript',
+            ' * matrix.add([1, 2], [3, 4]) // [4, 6]',
+            ' * ```',
+            ' */',
+        ].join('\n'),
+    );
+    expectScope(t, tokens, '*a*', 'markup.italic.documentation.mira');
+    expectScope(t, tokens, '**b**', 'markup.bold.documentation.mira');
+    for (const line of [1, 2, 3, 4, 5]) {
+        const prefix = tokens.find((token) => token.line === line && token.text.trim() === '*');
+        t.truthy(prefix, `Missing documentation prefix on line ${line}`);
+        t.is(prefix!.scopes.at(-1), 'comment.block.documentation.mira');
+    }
+});
+
+test('does not consume a documentation terminator as italic markup', (t) => {
+    const tokens = tokenize('/**\n * *1*/\nlet x = 12;');
+    expectScope(t, tokens, 'let', 'keyword.declaration.mira');
+    expectScope(t, tokens, 'x', 'variable.other.mira');
+    t.false(tokens.some((token) => token.text === '*1*' && token.scopes.includes('markup.italic.documentation.mira')));
+});
+
+test('ends a documentation fence before a prefixed comment terminator', (t) => {
+    const tokens = tokenize('/**\n * ```mirascript\n * */\n * ```');
+    const trailingLine = tokens.filter((token) => token.line === 3);
+    t.true(trailingLine.length > 0);
+    for (const token of trailingLine) {
+        t.false(token.scopes.includes('comment.block.documentation.mira'), token.scopes.join(', '));
+        t.false(token.scopes.includes('markup.fenced_code.block.mira'), token.scopes.join(', '));
+    }
+});
+
+test('closes documentation before an embedded string can consume its terminator', (t) => {
+    const tokens = tokenize("/**\n * ```mirascript\n * '*/\nlet recovered = 1;");
+    expectScope(t, tokens, 'let', 'keyword.declaration.mira');
+    expectScope(t, tokens, 'recovered', 'variable.other.mira');
+    const recovered = tokens.find((token) => token.text === 'recovered');
+    t.false(recovered!.scopes.includes('comment.block.documentation.mira'));
+    t.false(recovered!.scopes.includes('markup.fenced_code.block.mira'));
+});
+
+test('preserves multiline embedded source state between safe documentation lines', (t) => {
+    const tokens = tokenize("/**\n * ```mirascript\n * 'first\n * second'\n * ```\n */");
+    expectScope(t, tokens, 'second', 'string.quoted.single.mira');
+});
+
+test('highlights documentation fences for the MiraScript name, aliases, and an omitted tag', (t) => {
+    const tags = [undefined, mirascriptLanguage.name, ...(mirascriptLanguage.aliases ?? []), 'mIrAsCrIpT'];
+    for (const tag of tags) {
+        const tokens = tokenize(['/**', ` * \`\`\`${tag ?? ''}`, ' * matrix.identity(3)', ' * ```', ' */'].join('\n'));
+        if (tag) expectScope(t, tokens, tag, 'fenced_code.block.language.mira');
+        expectScope(t, tokens, 'identity', 'entity.name.function.member.mira');
+    }
+});
+
+test('supports documentation fences with three or more backticks', (t) => {
+    for (const [openingLength, closingLength] of [
+        [3, 3],
+        [4, 4],
+        [8, 8],
+        [12, 16],
+    ] as const) {
+        const opening = '`'.repeat(openingLength);
+        const closing = '`'.repeat(closingLength);
+        const tokens = tokenize(
+            [
+                '/**',
+                ` * ${opening}mirascript`,
+                ' * matrix.identity(3)',
+                ` * ${closing}`,
+                ' */',
+                'let outside = 1;',
+            ].join('\n'),
+        );
+        expectScope(t, tokens, 'identity', 'entity.name.function.member.mira');
+        expectScope(t, tokens, 'outside', 'variable.other.mira');
+    }
+});
+
+test('keeps unknown documentation fence tags as unparsed code blocks', (t) => {
+    const tokens = tokenize(
+        ['/**', ' * ````javascript', ' * let value = call(1);', ' * ````', ' */', 'let outside = 1;'].join('\n'),
+    );
+    expectScope(t, tokens, 'javascript', 'fenced_code.block.language.mira');
+    const body = tokens.find((token) => token.line === 2 && token.text.includes('let value'));
+    t.truthy(body);
+    t.true(body!.scopes.includes('markup.fenced_code.block.mira'));
+    t.true(body!.scopes.includes('markup.raw.block.mira'));
+    t.false(body!.scopes.includes('keyword.declaration.mira'));
+    t.false(body!.scopes.includes('entity.name.function.mira'));
+    expectScope(t, tokens, 'outside', 'variable.other.mira');
+});
+
+test('highlights MiraScript fenced code inside documentation comments', (t) => {
+    const tokens = tokenize(
+        [
+            '/**',
+            ' * 创建一个单位矩阵',
+            ' *',
+            ' * - `..size`: 矩阵的维度',
+            ' *',
+            ' * ### 示例',
+            ' * ```mirascript',
+            ' * matrix.identity(3) // [[1, 0, 0], [0, 1, 0], [0, 0, 1]]',
+            ' * ```',
+            ' * @returns the matrix',
+            ' */',
+            'let outside = 2;',
+        ].join('\n'),
+    );
+    expectScope(t, tokens, 'mirascript', 'fenced_code.block.language.mira');
+    expectScope(t, tokens, 'identity', 'entity.name.function.member.mira');
+    expectScope(t, tokens, '3', 'constant.numeric.float.mira');
+    expectScope(t, tokens, '// [[1, 0, 0], [0, 1, 0], [0, 0, 1]]', 'comment.line.double-slash.mira');
+    expectScope(t, tokens, '@returns', 'storage.type.class.documentation.mira');
+    expectScope(t, tokens, 'let', 'keyword.declaration.mira');
+    expectScope(t, tokens, 'outside', 'variable.other.mira');
+});
+
+test('ends an unterminated documentation fence at the comment boundary', (t) => {
+    const tokens = tokenize('/**\n * ```mirascript\n * fn call() { nil }\n */\nlet recovered = 1;');
+    expectScope(t, tokens, 'call', 'entity.name.function.mira');
+    expectScope(t, tokens, 'let', 'keyword.declaration.mira');
+    expectScope(t, tokens, 'recovered', 'variable.other.mira');
+    const recovered = tokens.find((token) => token.text === 'recovered');
+    t.false(recovered!.scopes.includes('comment.block.documentation.mira'));
+});
+
+test('highlights documentation comments inside documentation mode', (t) => {
+    const tokens = tokenize(
+        [
+            '/**',
+            ' * **bold** and *italic*',
+            ' * ```mirascript',
+            ' * matrix.identity(3)',
+            ' * ```',
+            ' */',
+            'fn recovered(value: number) -> number',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, '**bold**', 'markup.bold.documentation.mira');
+    expectScope(t, tokens, '*italic*', 'markup.italic.documentation.mira');
+    expectScope(t, tokens, 'identity', 'entity.name.function.member.mira');
+    expectScope(t, tokens, 'recovered', 'entity.name.function.mira');
+    expectScope(t, tokens, 'number', 'support.type.builtin.mira');
+});

package/tests/grammar/documentation-mode.ts

@@ -0,0 +1,372 @@
+import test from 'ava';
+import { tokenize, expectScope } from '../_engine.ts';
+
+test('highlights types', (t) => {
+    const types = ['boolean', 'true', 'false', 'number', 'string', 'array', 'record', 'extern', 'any', 'nil'];
+    const tokens = tokenize(types.map((type) => `fn _${type}(v: ${type}) -> ${type}`).join('\n'), 'mirascript-doc');
+    for (const type of types) {
+        expectScope(t, tokens, type, 'support.type.builtin.mira');
+    }
+});
+
+test('highlights generated documentation syntax', (t) => {
+    const tokens = tokenize(
+        [
+            '\0(parameter) mut value',
+            '\0(parameter) plain',
+            '(field) description',
+            'let immutable',
+            'const @constant',
+            'let mut mutable',
+            'item: /* <extern function> */ fn(arg: number) -> string',
+            'fn transform<T>(value: record<string, T>, callback: fn(result: T) -> boolean) -> T[] | nil',
+            'reflected: type(MyValue)',
+            '(field?: number, nested: (name: string))',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, '(parameter)', 'entity.name.label.mira');
+    expectScope(t, tokens, '(field)', 'entity.name.label.mira');
+    expectScope(t, tokens, 'value', 'variable.emphasis.mira');
+    expectScope(t, tokens, 'plain', 'variable.other.constant.emphasis.mira');
+    expectScope(t, tokens, 'immutable', 'variable.other.constant.mira');
+    expectScope(t, tokens, '@constant', 'variable.other.constant.mira');
+    expectScope(t, tokens, 'mutable', 'variable.other.readwrite.mira');
+    expectScope(t, tokens, 'extern', 'keyword.declaration.extern.mira');
+    expectScope(t, tokens, 'function', 'keyword.js');
+    expectScope(t, tokens, 'transform', 'entity.name.function.mira');
+    expectScope(t, tokens, 'record', 'support.type.builtin.mira');
+    expectScope(t, tokens, 'callback', 'entity.name.function.emphasis.mira');
+    expectScope(t, tokens, 'boolean', 'support.type.builtin.mira');
+    expectScope(t, tokens, 'MyValue', 'variable.other.mira');
+    expectScope(t, tokens, 'field', 'variable.emphasis.mira');
+    expectScope(t, tokens, 'nested', 'variable.emphasis.mira');
+    expectScope(t, tokens, 'name', 'variable.other.property.mira');
+    t.false(
+        tokens.filter((token) => token.line === 9).some((token) => token.scopes.includes('entity.name.label.mira')),
+    );
+    expectScope(t, tokens, '->', 'keyword.operator.type.mira');
+});
+
+test('distinguishes doc declarations, globals, and nested function types', (t) => {
+    const tokens = tokenize(
+        [
+            'mod matrix {',
+            '  pub fn determinant(data: array | record) -> number',
+            '}',
+            '\0(global) mod matrix',
+            '\0PI',
+            '\0(global) PI',
+            '\0(global) fn map(',
+            '  data: array | record,',
+            '  f: fn(value: any, key: number | string, input: type(data)) -> any,',
+            ') -> type(data)',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, 'mod', 'keyword.control.module.mira', 0);
+    expectScope(t, tokens, 'matrix', 'entity.name.namespace.mira', 0);
+    expectScope(t, tokens, 'pub', 'keyword.control.module.mira');
+    expectScope(t, tokens, 'PI', 'variable.other.constant.mira', 0);
+    expectScope(t, tokens, 'PI', 'variable.other.constant.mira', 1);
+    expectScope(t, tokens, '(global)', 'entity.name.label.mira', 0);
+    expectScope(t, tokens, 'fn', 'keyword.declaration.function.mira', 0);
+    expectScope(t, tokens, 'fn', 'support.type.function.mira', 2);
+    expectScope(t, tokens, 'data', 'variable.emphasis.mira', 1);
+    expectScope(t, tokens, 'f', 'entity.name.function.emphasis.mira');
+    expectScope(t, tokens, 'value', 'variable.emphasis.mira');
+    expectScope(t, tokens, 'type', 'support.type.type.mira');
+    expectScope(t, tokens, 'data', 'variable.other.mira', 2);
+});
+
+test('keeps nested types in unlabelled and module function signatures', (t) => {
+    const tokens = tokenize(
+        [
+            'fn map(',
+            '  data: array | record,',
+            '  f: fn(value: any, key: number | string, input: type(data)) -> any,',
+            ') -> type(data)',
+            'mod matrix {',
+            '  pub fn entrywise(',
+            '    a: any | any[] | any[][],',
+            '    b: any | any[] | any[][],',
+            '    f: fn(a: any, b: any) -> any,',
+            '  ) -> any | any[] | any[][];',
+            '}',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    const declarationFns = tokens.filter((token) => token.text === 'fn' && (token.line === 0 || token.line === 5));
+    const typeFns = tokens.filter((token) => token.text === 'fn' && (token.line === 2 || token.line === 8));
+    t.is(declarationFns.length, 2);
+    t.is(typeFns.length, 2);
+    for (const token of declarationFns) {
+        t.true(token.scopes.includes('keyword.declaration.function.mira'), token.scopes.join(', '));
+        t.false(token.scopes.includes('support.type.function.mira'), token.scopes.join(', '));
+    }
+    for (const token of typeFns) {
+        t.true(token.scopes.includes('support.type.function.mira'), token.scopes.join(', '));
+        t.false(token.scopes.includes('keyword.declaration.function.mira'), token.scopes.join(', '));
+    }
+    for (const token of tokens.filter((token) => token.text === 'type')) {
+        t.true(token.scopes.includes('support.type.type.mira'), token.scopes.join(', '));
+    }
+    t.is(tokens.filter((token) => token.text === 'type').length, 2);
+    for (const token of tokens.filter((token) => token.text === 'data' && (token.line === 2 || token.line === 3))) {
+        t.true(token.scopes.includes('variable.other.mira'), token.scopes.join(', '));
+    }
+    t.is(tokens.filter((token) => token.text === 'data' && (token.line === 2 || token.line === 3)).length, 2);
+});
+
+test('keeps tuple and array element types inside their type context', (t) => {
+    const tokens = tokenize(
+        [
+            'fn size(matrix: any[][]) -> [number, number]',
+            'fn identity(..size: [number] | [number, number]) -> number[][]',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, 'matrix', 'variable.emphasis.mira');
+    expectScope(t, tokens, 'size', 'variable.emphasis.mira', 1);
+    for (const token of tokens.filter((candidate) => candidate.text === 'number')) {
+        t.true(
+            token.scopes.includes('support.type.builtin.mira'),
+            `${JSON.stringify(token.text)} should stay a built-in type; got ${token.scopes.join(', ')}`,
+        );
+    }
+    t.is(tokens.filter((token) => token.text === 'number').length, 6);
+});
+
+test('highlights serialized extern record values in documentation mode', (t) => {
+    const tokens = tokenize(
+        [
+            '(global) globalThis = /* <extern Window> */ (',
+            '  event: nil,',
+            '  customElements: /* <extern CustomElementRegistry> */ (',
+            '    define: /* <extern function> */,',
+            '    get: /* <extern function getValue> */,',
+            '    iterate: /* <extern function*> */,',
+            '    resolve: /* <extern async function resolveValue> */,',
+            '    initialize: /* <extern async function* initializeValue> */,',
+            '    Constructor: /* <extern class> */,',
+            '    Widget: /* <extern class HTMLElement> */',
+            '  ),',
+            '  ../* x162 */',
+            ')',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, '(global)', 'entity.name.label.mira');
+    expectScope(t, tokens, 'globalThis', 'variable.other.mira');
+    expectScope(t, tokens, 'event', 'variable.other.property.mira');
+    expectScope(t, tokens, 'nil', 'constant.language.mira');
+    expectScope(t, tokens, 'customElements', 'variable.other.property.mira');
+    expectScope(t, tokens, 'define', 'entity.name.function.mira');
+    expectScope(t, tokens, 'get', 'entity.name.function.mira');
+    expectScope(t, tokens, 'iterate', 'entity.name.function.mira');
+    expectScope(t, tokens, 'resolve', 'entity.name.function.mira');
+    expectScope(t, tokens, 'initialize', 'entity.name.function.mira');
+    expectScope(t, tokens, 'Constructor', 'entity.name.type.mira');
+    expectScope(t, tokens, 'Widget', 'entity.name.type.mira');
+    expectScope(t, tokens, 'Window', 'entity.name.type.js');
+    expectScope(t, tokens, 'CustomElementRegistry', 'entity.name.type.js');
+    for (const token of tokens.filter((candidate) => candidate.text === 'function')) {
+        t.true(token.scopes.includes('keyword.js'));
+    }
+    t.is(tokens.filter((token) => token.text === 'function').length, 5);
+    for (const token of tokens.filter((candidate) => candidate.text === 'async')) {
+        t.true(token.scopes.includes('keyword.js'));
+    }
+    t.is(tokens.filter((token) => token.text === 'async').length, 2);
+    for (const token of tokens.filter((candidate) => candidate.text === '*')) {
+        t.true(token.scopes.includes('keyword.operator.generator.js'));
+    }
+    t.is(tokens.filter((token) => token.text === '*').length, 2);
+    expectScope(t, tokens, 'getValue', 'entity.name.function.js');
+    expectScope(t, tokens, 'resolveValue', 'entity.name.function.js');
+    expectScope(t, tokens, 'initializeValue', 'entity.name.function.js');
+    expectScope(t, tokens, 'class', 'keyword.js', 0);
+    expectScope(t, tokens, 'class', 'keyword.js', 1);
+    expectScope(t, tokens, 'HTMLElement', 'entity.name.type.js');
+    expectScope(t, tokens, ' x162 ', 'comment.block.mira');
+    for (const delimiter of tokens.filter((token) => ['/*', '*/'].includes(token.text))) {
+        t.true(delimiter.scopes.includes('comment.block.mira'), delimiter.scopes.join(', '));
+    }
+    for (const delimiter of tokens.filter((token) => ['<', '>'].includes(token.text))) {
+        t.true(
+            delimiter.scopes.some((scope) => scope.startsWith('punctuation.definition.tag.')),
+            delimiter.scopes.join(', '),
+        );
+    }
+});
+
+test('highlights inline and comment-only documentation tags', (t) => {
+    const tokens = tokenize(
+        [
+            '<module matrix / arbitrary name>',
+            '<function global.to-string (value)>',
+            '  <extern async function* request animation frame>  ',
+            '/* <module matrix> */',
+            '/*<function render>*/',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, 'module', 'keyword.declaration.module.mira', 0);
+    expectScope(t, tokens, 'module', 'keyword.declaration.module.mira', 1);
+    expectScope(t, tokens, 'matrix / arbitrary name', 'entity.name.namespace.mira');
+    expectScope(t, tokens, 'matrix', 'entity.name.namespace.mira');
+    expectScope(t, tokens, 'function', 'keyword.declaration.function.mira', 0);
+    expectScope(t, tokens, 'function', 'keyword.declaration.function.mira', 2);
+    expectScope(t, tokens, 'global.to-string (value)', 'entity.name.function.mira');
+    expectScope(t, tokens, 'render', 'entity.name.function.mira');
+    expectScope(t, tokens, 'extern', 'keyword.declaration.extern.mira');
+    expectScope(t, tokens, 'async', 'keyword.js');
+    expectScope(t, tokens, 'function', 'keyword.js', 1);
+    expectScope(t, tokens, '*', 'keyword.operator.generator.js');
+    expectScope(t, tokens, 'request animation frame', 'entity.name.function.js');
+    t.is(tokens.filter((token) => token.text === '<').length, 5);
+    t.is(tokens.filter((token) => token.text === '>').length, 5);
+    for (const delimiter of tokens.filter((token) => token.text === '<')) {
+        t.true(delimiter.scopes.includes('punctuation.definition.tag.begin.mira'), delimiter.scopes.join(', '));
+    }
+    for (const delimiter of tokens.filter((token) => token.text === '>')) {
+        t.true(delimiter.scopes.includes('punctuation.definition.tag.end.mira'), delimiter.scopes.join(', '));
+    }
+});
+
+test('highlights multiple inline tags while keeping tag delimiters tight', (t) => {
+    const tokens = tokenize(
+        ['value = <module matrix>', '<extern Array(3)> [1, <extern Object>, [1, <extern Object>]]'].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, 'module', 'keyword.declaration.module.mira');
+    expectScope(t, tokens, 'matrix', 'entity.name.namespace.mira');
+    expectScope(t, tokens, 'Array', 'entity.name.type.js');
+    expectScope(t, tokens, '(', 'punctuation.section.parens.begin.mira');
+    expectScope(t, tokens, '3', 'constant.numeric.mira');
+    expectScope(t, tokens, ')', 'punctuation.section.parens.end.mira');
+    expectScope(t, tokens, 'Object', 'entity.name.type.js', 0);
+    expectScope(t, tokens, 'Object', 'entity.name.type.js', 1);
+    t.is(tokens.filter((token) => token.text === 'extern').length, 3);
+    t.true(tokens.some((token) => token.scopes.includes('meta.documentation.tag.mira')));
+
+    const invalidTokens = tokenize(
+        [
+            '/* prefix <module matrix> */',
+            '< module matrix>',
+            '<module matrix >',
+            '/* <module matrix> suffix */',
+            '/*',
+            '<module matrix>',
+            '*/',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    t.false(
+        invalidTokens.some((token) => token.scopes.includes('meta.documentation.tag.mira')),
+        invalidTokens
+            .map((token) => `${token.line}:${JSON.stringify(token.text)} ${token.scopes.join(', ')}`)
+            .join('\n'),
+    );
+    t.false(
+        invalidTokens.some((token) => token.scopes.some((scope) => scope.startsWith('punctuation.definition.tag.'))),
+    );
+
+    const sourceTokens = tokenize('<module matrix>\n/* <extern Navigator> */');
+    t.false(sourceTokens.some((token) => token.scopes.includes('meta.documentation.tag.mira')));
+    t.false(
+        sourceTokens.some((token) => token.scopes.some((scope) => scope.startsWith('punctuation.definition.tag.'))),
+    );
+});
+
+test('highlights extern tags while preserving surrounding document declarations', (t) => {
+    const tokens = tokenize(
+        [
+            'let navigator = /* <extern Navigator> */ (',
+            '  scheduling: /* <extern Scheduling> */,',
+            '  getGamepads: /* <extern function> */,',
+            ');',
+            'let AbortController = /* <extern class AbortController> */;',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, 'navigator', 'variable.other.constant.mira');
+    expectScope(t, tokens, 'scheduling', 'variable.other.property.mira');
+    expectScope(t, tokens, 'getGamepads', 'entity.name.function.mira');
+    expectScope(t, tokens, 'AbortController', 'variable.other.constant.mira', 0);
+    expectScope(t, tokens, 'extern', 'keyword.declaration.extern.mira');
+    expectScope(t, tokens, 'Navigator', 'entity.name.type.js');
+    expectScope(t, tokens, 'Scheduling', 'entity.name.type.js');
+    expectScope(t, tokens, 'function', 'keyword.js');
+    expectScope(t, tokens, 'class', 'keyword.js');
+    expectScope(t, tokens, 'AbortController', 'entity.name.type.js', 1);
+    for (const delimiter of tokens.filter((token) => ['/*', '*/'].includes(token.text))) {
+        t.true(delimiter.scopes.includes('comment.block.mira'), delimiter.scopes.join(', '));
+    }
+});
+
+test('highlights extern tags nested in document value arrays', (t) => {
+    const tokens = tokenize(
+        ['a: /* <extern Array(3)> */ [', '  1,', '  /* <extern Object> */,', '  /* <extern Array(2)> */', ']'].join(
+            '\n',
+        ),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, 'a', 'variable.other.property.mira');
+    expectScope(t, tokens, 'Array', 'entity.name.type.js', 0);
+    expectScope(t, tokens, 'Array', 'entity.name.type.js', 1);
+    expectScope(t, tokens, 'Object', 'entity.name.type.js');
+    expectScope(t, tokens, '3', 'constant.numeric.mira');
+    expectScope(t, tokens, '2', 'constant.numeric.mira');
+    for (const delimiter of tokens.filter((token) => ['(', ')'].includes(token.text))) {
+        t.true(
+            delimiter.scopes.includes(`punctuation.section.parens.${delimiter.text === '(' ? 'begin' : 'end'}.mira`),
+        );
+    }
+    t.is(tokens.filter((token) => token.text === 'extern').length, 3);
+    for (const delimiter of tokens.filter((token) => ['/*', '*/'].includes(token.text))) {
+        t.true(delimiter.scopes.includes('comment.block.mira'), delimiter.scopes.join(', '));
+    }
+});
+
+test('highlights line-leading field declarations and infers callable and class field names', (t) => {
+    const tokens = tokenize(
+        [
+            '(field) navigator: /* <extern Navigator> */',
+            'scheduling: /* <extern Scheduling> */',
+            'getGamepads: /* <extern function> */',
+            'AbortController: /* <extern class AbortController> */;',
+            '(field) requestAnimationFrame: /* <extern function> */;',
+            '(field) 1: value',
+            '(field) "invalid-name": value',
+            '2: /* <extern function> */;',
+            '"class-name": /* <extern class HTMLElement> */;',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    expectScope(t, tokens, '(field)', 'entity.name.label.mira');
+    expectScope(t, tokens, 'navigator', 'variable.other.property.mira');
+    expectScope(t, tokens, 'scheduling', 'variable.other.property.mira');
+    expectScope(t, tokens, 'getGamepads', 'entity.name.function.mira');
+    expectScope(t, tokens, 'AbortController', 'entity.name.type.mira', 0);
+    expectScope(t, tokens, 'AbortController', 'entity.name.type.js', 1);
+    expectScope(t, tokens, 'requestAnimationFrame', 'entity.name.function.mira');
+    expectScope(t, tokens, '1', 'variable.other.property.mira');
+    expectScope(t, tokens, '"invalid-name"', 'variable.other.property.mira');
+    expectScope(t, tokens, '2', 'entity.name.function.mira');
+    expectScope(t, tokens, '"class-name"', 'entity.name.type.mira');
+    t.true(tokens.some((token) => token.scopes.includes('meta.documentation.field.mira')));
+
+    const indented = tokenize(
+        [
+            '  (field) indented: /* <extern function> */',
+            '  plain: /* <extern class HTMLElement> */',
+            '  (global) value = /* <extern Window> */',
+            '(field) legacy = /* <extern function> */',
+            'legacy = /* <extern class HTMLElement> */',
+        ].join('\n'),
+        'mirascript-doc',
+    );
+    t.false(indented.some((token) => token.scopes.includes('meta.documentation.field.mira')));
+    t.false(indented.some((token) => token.scopes.includes('meta.documentation.global-value.mira')));
+});