@formaui-net/nexo 0.0.0 → 1.0.0-preview.1

package/src/language/SyntaxTree.mjs

@@ -0,0 +1,203 @@
+/**
+ * SyntaxTree — the lossless syntax tree of a Nexo text: its constructs, each a node named after the grammar rule that produces it, holding its tokens and the nodes within it, every token with the trivia before it
+ */
+
+/** @typedef {import('./Tokenizer.mjs').Token} Token */
+/** @typedef {{ kind: string, children: (SyntaxNode | Token)[] }} SyntaxNode */
+/** @typedef {{ kind: 'script', text: string, children: (SyntaxNode | Token)[] }} ScriptNode The script's import declarations, its body and the end of its text, with the trivia before it. */
+/** @typedef {{ kind: 'whitespace' | 'line-comment' | 'block-comment', start: number, end: number }} TriviaPiece */
+
+/**
+ * The kinds a node is, each a construct of the grammar, which tooling reads as they are; a rule that only passes an operand on, a level of precedence or a repetition, is none of them.
+ * A contract within Nexo until a public tooling API stabilizes it.
+ */
+export const SYNTAX_NODE_KINDS = Object.freeze([
+    'script',
+    'import-declaration',
+    'list-expression',
+    'dictionary-expression',
+    'dictionary-entry',
+    'conditional-expression',
+    'body',
+    'do-expression',
+    'function-expression',
+    'arrow-function',
+    'function-call',
+    'conditional-binding',
+    'disjunction',
+    'conjunction',
+    'negation',
+    'equality',
+    'comparison',
+    'additive',
+    'multiplicative',
+    'arithmetic-negation',
+    'from-end-index',
+    'range-expression',
+    'coalescing',
+    'attempt',
+    'conversion',
+    'cast',
+    'type-name',
+    'chain',
+    'namespace-access',
+    'dot-property-access',
+    'computed-property-access',
+    'member-call',
+    'indexer',
+    'extension-access',
+    'parenthesized-expression',
+    'optional-enclosed-access',
+    'member-chain',
+    'receiver',
+    'object',
+    'interpolated-string',
+    'interpolation',
+    'local',
+    'field',
+]);
+
+/** The tokens that make an access optional: a property access's or a call's `?.`, an indexer's `?[` and an extension access's `?:`. */
+const OPTIONAL_ACCESSES = new Set(['?.', '?[', '?:']);
+
+export class SyntaxTree {
+    /** Whether a token of the type makes the access it begins optional, so it answers null for a null receiver and ends its chain there. */
+    static isOptionalAccess(tokenType) {
+        return OPTIONAL_ACCESSES.has(tokenType);
+    }
+
+    /**
+     * The import an import declaration writes, in a definition's shape: its module, its type where it imports one, and its alias where it gives a local name other than its own, each the word the text spells.
+     * @param {SyntaxNode} declaration
+     * @param {string} text
+     */
+    static importOf(declaration, text) {
+        const words = declaration.children.slice(1);
+        const hasAlias = words[1]?.type === '=';
+        const source = hasAlias ? words.slice(2) : words;
+        const module = SyntaxTree.wordOf(source[0], text);
+        const type = source.length > 1 ? SyntaxTree.wordOf(source[2], text) : undefined;
+        const alias = hasAlias ? SyntaxTree.wordOf(words[0], text) : undefined;
+
+        return {
+            module,
+            ...(type === undefined ? {} : { type }),
+            ...(alias === undefined || alias === (type ?? module) ? {} : { alias }),
+        };
+    }
+
+    /** The body a script holds, after its import declarations. */
+    static bodyOf(script) {
+        return script.children.at(-2);
+    }
+
+    /** Whether the child is a token rather than a node. */
+    static isToken(child) {
+        return child.kind === undefined;
+    }
+
+    /** Where the node's first token begins, its trivia left out. */
+    static startOf(child) {
+        let current = child;
+
+        while (!SyntaxTree.isToken(current)) {
+            current = current.children[0];
+        }
+
+        return current.start;
+    }
+
+    /** Where the node's last token ends. */
+    static endOf(child) {
+        let current = child;
+
+        while (!SyntaxTree.isToken(current)) {
+            current = current.children.at(-1);
+        }
+
+        return current.end;
+    }
+
+    /**
+     * The word a token writes, as the text spells it.
+     * @param {Token} token
+     * @param {string} text The text the token was read from.
+     */
+    static wordOf(token, text) {
+        return text.slice(token.start, token.end);
+    }
+
+    /**
+     * The name of the type a cast's or a conversion's type part writes: its local name, or its module's name, a dot and its local name, whatever trivia the text puts between them.
+     * @param {SyntaxNode | Token} part A name token or a `type-name` node.
+     * @param {string} text The text the part was read from.
+     */
+    static typeNameOf(part, text) {
+        return SyntaxTree.isToken(part) ? SyntaxTree.wordOf(part, text) : `${SyntaxTree.wordOf(part.children[0], text)}.${SyntaxTree.wordOf(part.children[2], text)}`;
+    }
+
+    /**
+     * The tokens of the node, in the order of the text.
+     * @param {SyntaxNode | Token} child
+     * @returns {Generator<Token>}
+     */
+    static *tokensOf(child) {
+        if (SyntaxTree.isToken(child)) {
+            yield child;
+
+            return;
+        }
+
+        for (const each of child.children) {
+            yield* SyntaxTree.tokensOf(each);
+        }
+    }
+
+    /**
+     * The text the tree was read from, rebuilt from its tokens and the trivia before each, the end of the text's included.
+     * @param {ScriptNode} tree
+     */
+    static textOf(tree) {
+        let text = '';
+
+        for (const token of SyntaxTree.tokensOf(tree)) {
+            text += tree.text.slice(token.triviaStart, token.end);
+        }
+
+        return text;
+    }
+
+    /**
+     * The trivia before the token, each piece whitespace, a line comment or a block comment, in the order of the text.
+     * @param {Token} token
+     * @param {string} text The text the token was read from.
+     * @returns {TriviaPiece[]}
+     */
+    static triviaOf(token, text) {
+        const pieces = [];
+
+        for (let offset = token.triviaStart; offset < token.start;) {
+            const start = offset;
+
+            if (text.startsWith('//', offset)) {
+                const lineEnd = text.slice(offset, token.start).search(/[\n\r]/);
+                // The comment holds the line break that ends it, CRLF one, or runs to the token where none does.
+                const breakLength = lineEnd !== -1 && text.startsWith('\r\n', offset + lineEnd) ? 2 : 1;
+
+                offset = lineEnd === -1 ? token.start : offset + lineEnd + breakLength;
+                pieces.push({ kind: 'line-comment', start, end: offset });
+            } else if (text.startsWith('/*', offset)) {
+                offset = text.indexOf('*/', offset + 2) + 2;
+                pieces.push({ kind: 'block-comment', start, end: offset });
+            } else {
+                while (offset < token.start && !text.startsWith('//', offset) && !text.startsWith('/*', offset)) {
+                    offset++;
+                }
+
+                pieces.push({ kind: 'whitespace', start, end: offset });
+            }
+        }
+
+        return pieces;
+    }
+}

package/src/language/TextLocations.mjs

@@ -0,0 +1,185 @@
+/**
+ * TextLocations — where in a source text each part of its definition came from, by JSON Pointer
+ */
+
+import { Lowering } from './Lowering.mjs';
+import { Parser } from './Parser.mjs';
+import { TextPositions } from './TextPositions.mjs';
+
+/** @typedef {import('./Parser.mjs').Span} Span */
+
+export class TextLocations {
+    #text;
+
+    /** The imports a host supplied to the text, which decide how it reads. @type {readonly object[]} */
+    #suppliedImports;
+
+    /**
+     * The span of each part of the definition by its pointer, collected at the first location asked for, from the text read again, and kept from then on; null until then. A text reads into one definition alone, so the
+     * spans read again are the ones it was parsed with. Collecting them as each text was parsed measured a seventh of parsing, for a location most texts are never asked for, and keeping the definition it lowered until
+     * then would hold more than the text it reads from.
+     * @type {Map<string, Span> | null}
+     */
+    #spans = null;
+
+    /**
+     * @param {string} text The source text, which parsed.
+     * @param {readonly object[]} [suppliedImports] The imports a host supplied to it, in a definition's shape, checked already.
+     */
+    constructor(text, suppliedImports = []) {
+        this.#text = text;
+        this.#suppliedImports = suppliedImports;
+    }
+
+    /** The span of each part of the definition by its pointer, collected from the text read again where none was collected yet. */
+    #getSpans() {
+        if (this.#spans === null) {
+            const { definition, spans } = Lowering.lower(new Parser(this.#text, this.#suppliedImports).parse(), this.#suppliedImports);
+
+            this.#spans = new Map();
+            definition.imports.forEach((entry, index) => {
+                const span = spans.get(entry);
+
+                if (span) {
+                    this.#spans.set(`/imports/${index}`, span);
+                }
+            });
+            this.#collect(definition.expression, '/expression', spans);
+        }
+
+        return this.#spans;
+    }
+
+    /** The text the definition was read from, from which its syntax tree is read again where a tool asks for it, since no definition keeps one. */
+    get text() {
+        return this.#text;
+    }
+
+    /** The text position the pointer's part began at, or the nearest enclosing part's. */
+    locate(pointer) {
+        const spans = this.#getSpans();
+
+        for (let current = pointer; ; current = current.slice(0, current.lastIndexOf('/'))) {
+            const span = spans.get(current);
+
+            if (span) {
+                return { pointer, ...TextPositions.locate(this.#text, span.start) };
+            }
+
+            if (current === '') {
+                return { pointer };
+            }
+        }
+    }
+
+    /** Records the span of the node at the pointer, and of every part beneath it. */
+    #collect(node, pointer, spans) {
+        const span = spans.get(node);
+
+        if (span) {
+            this.#spans.set(pointer, span);
+        }
+
+        // A property access, an indexer, a call's member and what an object expression or an optional chain holds, each the node it continues from or ends at.
+        for (const property of ['receiver', 'callee', 'context', 'chain']) {
+            if (node[property]) {
+                this.#collect(node[property], `${pointer}/${property}`, spans);
+            }
+        }
+
+        if (node.kind === 'memberAccess' && typeof node.name !== 'string') {
+            this.#collect(node.name, `${pointer}/name`, spans);
+        }
+
+        if (node.argument) {
+            this.#collect(node.argument, `${pointer}/argument`, spans);
+        }
+
+        if (node.kind === 'conditional') {
+            if (node.binding !== undefined) {
+                const bindingSpan = spans.get(node.binding);
+
+                if (bindingSpan) {
+                    this.#spans.set(`${pointer}/binding`, bindingSpan);
+                }
+
+                this.#collect(node.binding.value, `${pointer}/binding/value`, spans);
+            }
+
+            for (const branch of ['condition', 'consequent', 'alternative']) {
+                if (node[branch] !== undefined) {
+                    this.#collect(node[branch], `${pointer}/${branch}`, spans);
+                }
+            }
+        }
+
+        if (node.kind === 'equality') {
+            this.#collect(node.left, `${pointer}/left`, spans);
+            this.#collect(node.right, `${pointer}/right`, spans);
+        }
+
+        if (node.kind === 'arithmetic') {
+            this.#collect(node.left, `${pointer}/left`, spans);
+            this.#collect(node.right, `${pointer}/right`, spans);
+        }
+
+        // A negation's, an arithmetic negation's, a cast's, a conversion's and an attempt's operand.
+        if (node.operand) {
+            this.#collect(node.operand, `${pointer}/operand`, spans);
+        }
+
+        // An index's offset, and a range's boundaries where it holds them.
+        for (const property of ['offset', 'start', 'end']) {
+            if (node.kind === 'fromEndIndex' || node.kind === 'range') {
+                if (node[property] !== undefined) {
+                    this.#collect(node[property], `${pointer}/${property}`, spans);
+                }
+            }
+        }
+
+        if (node.kind === 'coalescing') {
+            this.#collect(node.value, `${pointer}/value`, spans);
+            this.#collect(node.fallback, `${pointer}/fallback`, spans);
+        }
+
+        node.operands?.forEach((operand, index) => this.#collect(operand, `${pointer}/operands/${index}`, spans));
+
+        if (node.kind === 'interpolatedString') {
+            node.parts.forEach((part, index) => {
+                if (part.kind === 'expression') {
+                    this.#collect(part.expression, `${pointer}/parts/${index}/expression`, spans);
+                }
+            });
+        }
+
+        if (node.kind === 'body') {
+            this.#collect(node.result, `${pointer}/result`, spans);
+        }
+
+        if (node.kind === 'function' || node.kind === 'do') {
+            this.#collect(node.body, `${pointer}/body`, spans);
+        }
+
+        if (node.kind === 'call') {
+            node.arguments.forEach((argument, index) => this.#collect(argument, `${pointer}/arguments/${index}`, spans));
+        }
+
+        if (node.kind === 'list') {
+            node.items.forEach((item, index) => this.#collect(item, `${pointer}/items/${index}`, spans));
+        }
+
+        // An object expression's locals and object fields, and a dictionary's entries, each spanning its head and its value.
+        for (const entriesProperty of ['locals', 'objectFields', 'entries']) {
+            node[entriesProperty]?.forEach((entry, index) => {
+                const entryPointer = `${pointer}/${entriesProperty}/${index}`;
+                const entrySpan = spans.get(entry);
+
+                if (entrySpan) {
+                    this.#spans.set(entryPointer, entrySpan);
+                }
+
+                this.#collect(entry.value, `${entryPointer}/value`, spans);
+            });
+        }
+    }
+}

package/src/language/TextPositions.mjs

@@ -0,0 +1,23 @@
+/**
+ * TextPositions — where an offset stands in a text: its line and its column, as a location gives them
+ */
+
+export class TextPositions {
+    /** The offset's line and column in the text, each line break, LF, CRLF or a lone CR, beginning a line, so CRLF advances it once and its two characters count toward the offset. */
+    static locate(text, offset) {
+        let line = 1;
+        let lineStart = 0;
+
+        for (let index = 0; index < offset; index++) {
+            const character = text[index];
+
+            // A carriage return before a line feed is one line break with it, which the line feed ends.
+            if (character === '\n' || (character === '\r' && text[index + 1] !== '\n')) {
+                line++;
+                lineStart = index + 1;
+            }
+        }
+
+        return { offset, line, column: offset - lineStart + 1 };
+    }
+}