rooklang 0.0.0-stage → 0.3.0

package/dist/parser/types.js

@@ -0,0 +1,218 @@
+import { ClassParser } from "./classes.js";
+import { describe } from "./syntax.js";
+// Types: `?T`, `[]T`, unions, literal types, function, component and object types, type arguments.
+/** `iterator: true` for the parameters of an iterator: one, named `yield`. */
+function iterator(names) {
+    return names.length === 1 && names[0] === 'yield' ? { iterator: true } : {};
+}
+export class TypeParser extends ClassParser {
+    /** `<number, string>` after the name of a generic type. */
+    parseTypeArgs() {
+        if (!this.accept('<'))
+            return [];
+        const args = [this.parseType()];
+        while (this.accept(','))
+            args.push(this.parseType());
+        this.expectTypeClose('">" after the type arguments');
+        return args;
+    }
+    canStartType() {
+        switch (this.peek().kind) {
+            case 'Identifier':
+            case '[':
+            case '?':
+            case 'func':
+            case 'comp':
+            case 'chan':
+            case '<-':
+            case '{':
+            case '(':
+            case 'String':
+            case 'Number':
+            case 'true':
+            case 'false':
+                return true;
+            default:
+                return false;
+        }
+    }
+    /** A type, possibly a union: `string | number`. */
+    parseType() {
+        const start = this.peek().start;
+        const first = this.parsePrimaryType();
+        if (!this.check('|'))
+            return first;
+        const types = [first];
+        while (this.accept('|'))
+            types.push(this.parsePrimaryType());
+        return { kind: 'UnionType', types, ...this.span(start) };
+    }
+    parsePrimaryType() {
+        const start = this.peek().start;
+        switch (this.peek().kind) {
+            case '(':
+                return this.parseParenthesizedType();
+            case 'String': {
+                const value = this.parseStringLiteral();
+                return { kind: 'LiteralType', value, ...this.span(start) };
+            }
+            case 'Number':
+            case 'true':
+            case 'false': {
+                const value = this.parsePrimary();
+                return { kind: 'LiteralType', value, ...this.span(start) };
+            }
+            case '?': {
+                this.next();
+                const type = this.parsePrimaryType();
+                return { kind: 'NullableType', type, ...this.span(start) };
+            }
+            case '[': {
+                this.next();
+                this.expect(']', '"]" (array types are written as []T)');
+                const element = this.parsePrimaryType();
+                return { kind: 'ArrayType', element, ...this.span(start) };
+            }
+            // The parameters may have names, as in Go; `func(yield func(T) bool)` is an iterator.
+            case 'func': {
+                this.next();
+                this.expect('(');
+                const names = [];
+                const params = this.parseList(')', () => this.parseParamType(names));
+                const results = this.parseResults();
+                return { kind: 'FuncType', params, results, ...iterator(names), ...this.span(start) };
+            }
+            // `chan T`, `chan<- T` that only sends, `<-chan T` that only receives.
+            case 'chan': {
+                this.next();
+                const direction = this.accept('<-') ? 'send' : 'both';
+                const element = this.parsePrimaryType();
+                return { kind: 'ChanType', element, direction, ...this.span(start) };
+            }
+            case '<-': {
+                this.next();
+                this.expect('chan', '"chan" after "<-": a channel that only receives is <-chan T');
+                const element = this.parsePrimaryType();
+                return { kind: 'ChanType', element, direction: 'receive', ...this.span(start) };
+            }
+            // `comp(title string)`: the names are those of the attributes, so they are required.
+            case 'comp': {
+                this.requireMarkup('components are');
+                this.next();
+                const params = this.parseParams(false);
+                return { kind: 'ComponentType', params, ...this.span(start) };
+            }
+            case '{': {
+                const members = this.parseTypeMembers();
+                return { kind: 'ObjectType', members, ...this.span(start) };
+            }
+            default: {
+                const name = this.parseIdentifier('type');
+                const typeArgs = this.parseTypeArgs();
+                return { kind: 'TypeReference', name, typeArgs, ...this.span(start) };
+            }
+        }
+    }
+    /**
+     * Grouping, `[](string | number)`, or a function type written as an arrow,
+     * `(paths []string) => Shape`, the same as `func([]string) Shape`. Its parameters may have
+     * names, which only document them.
+     */
+    parseParenthesizedType() {
+        const start = this.next().start;
+        const names = [];
+        const params = this.parseList(')', () => this.parseParamType(names));
+        if (this.accept('=>')) {
+            const result = this.parseType();
+            const voids = result.kind === 'TypeReference' && result.name.name === 'void';
+            return {
+                kind: 'FuncType',
+                params,
+                results: voids ? [] : [result],
+                ...iterator(names),
+                ...this.span(start),
+            };
+        }
+        if (params.length !== 1) {
+            this.error('types in parentheses are the parameters of a function type: (a A, b B) => R', start, this.span(start).end);
+        }
+        return (params[0] ?? {
+            kind: 'TypeReference',
+            name: { kind: 'Identifier', name: 'any', start, end: start },
+            typeArgs: [],
+            start,
+            end: start,
+        });
+    }
+    /** The type of a parameter of a function type, after its name if it has one, kept in `names`. */
+    parseParamType(names) {
+        names.push(this.check('Identifier') && this.startsNamedParam() ? this.next().text : '');
+        return this.parseType();
+    }
+    /** `paths []string` in `(paths []string) => Shape`: a name before the type of a parameter. */
+    startsNamedParam() {
+        const next = this.peek(1);
+        switch (next.kind) {
+            case 'Identifier':
+            case '?':
+            case '{':
+            case '(':
+            case 'func':
+            case 'chan':
+            case '<-':
+            case 'String':
+            case 'Number':
+                return true;
+            // `x []number` is named.
+            case '[':
+                return this.peek(2).kind === ']';
+            default:
+                return false;
+        }
+    }
+    /** `{ name string; x, y number; area() number }`, separated by newlines, `;` or `,`. */
+    parseTypeMembers() {
+        this.expect('{');
+        const members = [];
+        this.parseSeparated(() => this.check('}'), () => {
+            members.push(...this.parseTypeMember());
+            if (!this.accept(',') && !this.accept(';') && !this.check('}')) {
+                this.fail(`expected newline, ";" or "}" after member, found ${describe(this.peek())}`);
+            }
+        });
+        this.expect('}');
+        return members;
+    }
+    parseTypeMember() {
+        const start = this.peek().start;
+        // `[string]: Shape`: an object used as a map.
+        if (this.accept('[')) {
+            const key = this.parseType();
+            if (key.kind !== 'TypeReference' || !['string', 'number'].includes(key.name.name)) {
+                this.error('the key of [key]: T is string or number, e.g. [string]: number', key.start, key.end);
+            }
+            this.expect(']');
+            this.expect(':', '":" and the type of the values, e.g. [string]: number');
+            const type = this.parseType();
+            return [{ kind: 'IndexSignature', key, type, ...this.span(start) }];
+        }
+        const name = this.parsePropertyName('member name');
+        if (this.check('(')) {
+            const params = this.parseParams(false);
+            const results = this.parseResults();
+            return [{ kind: 'MethodSignature', name, params, results, ...this.span(start) }];
+        }
+        // `x, y number` declares several properties of the same type.
+        const names = [name];
+        while (this.accept(','))
+            names.push(this.parsePropertyName('member name'));
+        const type = this.parseType();
+        return names.map((memberName) => ({
+            kind: 'PropertySignature',
+            name: memberName,
+            type,
+            start: memberName.start,
+            end: type.end,
+        }));
+    }
+}

package/dist/recursion.d.ts

@@ -0,0 +1,25 @@
+import type * as ast from './ast.ts';
+export interface ComponentUse {
+    tag: ast.Identifier;
+    /**
+     * Inside if/for/switch, a branch of `?:`, the right side of `&&`, `||` or `??`, a function, or
+     * a default value of a property: the use may not run every time the component is created.
+     */
+    conditional: boolean;
+}
+/** Tags with a capital letter inside a component: uses of other components, or of itself. */
+export declare function componentUses(component: ast.ComponentDeclaration): ComponentUse[];
+/** Whether a statement has a `return` of its own, not one of a nested function. */
+export declare function containsReturn(statement: ast.Statement): boolean;
+/** Components that can reach themselves through their uses. */
+export declare function recursiveComponents(components: ReadonlyMap<string, ast.ComponentDeclaration>): Set<ast.ComponentDeclaration>;
+export interface EndlessRecursion {
+    /** Names of the components on the cycle, starting and ending with the same one. */
+    cycle: string[];
+    /** The use that closes the cycle. */
+    tag: ast.Identifier;
+}
+/** Cycles of uses where every use runs each time: creating such a component never ends. */
+export declare function endlessRecursion(components: ReadonlyMap<string, ast.ComponentDeclaration>): EndlessRecursion[];
+/** What a component returns: the markup of every `return` of its own, in order. */
+export declare function returnedMarkup(component: ast.ComponentDeclaration): ast.Expression[];

package/dist/recursion.js

@@ -0,0 +1,170 @@
+import { forEachChild } from "./walk.js";
+/** Tags with a capital letter inside a component: uses of other components, or of itself. */
+export function componentUses(component) {
+    const uses = [];
+    const visit = (node, conditional) => {
+        const visitChildren = (inside) => forEachChild(node, (child) => visit(child, inside));
+        switch (node.kind) {
+            case 'ElementExpression':
+                if (node.tag && /^[A-Z]/.test(node.tag.name))
+                    uses.push({ tag: node.tag, conditional });
+                for (const attribute of node.attributes)
+                    visit(attribute, conditional);
+                for (const child of node.children)
+                    visit(child, conditional);
+                return;
+            case 'IfStatement':
+                visit(node.condition, conditional);
+                visit(node.consequent, true);
+                if (node.alternate)
+                    visit(node.alternate, true);
+                return;
+            case 'ConditionalExpression':
+                visit(node.test, conditional);
+                visit(node.consequent, true);
+                visit(node.alternate, true);
+                return;
+            case 'BinaryExpression':
+                if (node.operator === '&&' || node.operator === '||' || node.operator === '??') {
+                    visit(node.left, conditional);
+                    visit(node.right, true);
+                    return;
+                }
+                visitChildren(conditional);
+                return;
+            case 'ForStatement':
+            case 'ForInStatement':
+            case 'SwitchStatement':
+            case 'CatchClause':
+            case 'FuncDeclaration':
+            case 'FuncExpression':
+            case 'ArrowFunction':
+            case 'EventHandler':
+            case 'MountStatement':
+            case 'EffectStatement':
+            case 'ClassDeclaration':
+            case 'Parameter':
+                visitChildren(true);
+                return;
+            default:
+                visitChildren(conditional);
+        }
+    };
+    for (const param of component.params)
+        visit(param, true);
+    // After an early return the rest of the body may not run.
+    let returned = false;
+    for (const statement of component.body.body) {
+        visit(statement, returned);
+        returned ||= containsReturn(statement);
+    }
+    return uses;
+}
+/** Whether a statement has a `return` of its own, not one of a nested function. */
+export function containsReturn(statement) {
+    let found = false;
+    const visit = (node) => {
+        if (found)
+            return;
+        switch (node.kind) {
+            case 'ReturnStatement':
+                found = true;
+                return;
+            case 'FuncDeclaration':
+            case 'FuncExpression':
+            case 'ArrowFunction':
+            case 'EventHandler':
+            case 'ClassDeclaration':
+            case 'MountStatement':
+            case 'EffectStatement':
+                return;
+            default:
+                forEachChild(node, visit);
+        }
+    };
+    visit(statement);
+    return found;
+}
+/** Components that can reach themselves through their uses. */
+export function recursiveComponents(components) {
+    const edges = new Map();
+    for (const component of components.values()) {
+        const used = componentUses(component)
+            .map((use) => components.get(use.tag.name))
+            .filter((other) => other !== undefined);
+        edges.set(component, used);
+    }
+    const recursive = new Set();
+    for (const component of components.values()) {
+        const seen = new Set();
+        const stack = [...(edges.get(component) ?? [])];
+        while (stack.length > 0) {
+            const next = stack.pop();
+            if (next === component) {
+                recursive.add(component);
+                break;
+            }
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            stack.push(...(edges.get(next) ?? []));
+        }
+    }
+    return recursive;
+}
+/** Cycles of uses where every use runs each time: creating such a component never ends. */
+export function endlessRecursion(components) {
+    const edges = new Map();
+    for (const component of components.values()) {
+        const list = [];
+        for (const use of componentUses(component)) {
+            const to = components.get(use.tag.name);
+            if (to && !use.conditional)
+                list.push({ to, tag: use.tag });
+        }
+        edges.set(component, list);
+    }
+    const found = [];
+    const state = new Map();
+    const visit = (component, path) => {
+        state.set(component, 'visiting');
+        for (const edge of edges.get(component) ?? []) {
+            if (state.get(edge.to) === 'visiting') {
+                const cycle = [...path.slice(path.indexOf(edge.to)), edge.to];
+                found.push({ cycle: cycle.map((c) => c.name.name), tag: edge.tag });
+            }
+            else if (!state.has(edge.to)) {
+                visit(edge.to, [...path, edge.to]);
+            }
+        }
+        state.set(component, 'done');
+    };
+    for (const component of components.values()) {
+        if (!state.has(component))
+            visit(component, [component]);
+    }
+    return found;
+}
+/** What a component returns: the markup of every `return` of its own, in order. */
+export function returnedMarkup(component) {
+    const found = [];
+    const visit = (node) => {
+        switch (node.kind) {
+            case 'ReturnStatement':
+                found.push(...node.values);
+                return;
+            case 'FuncDeclaration':
+            case 'FuncExpression':
+            case 'ArrowFunction':
+            case 'EventHandler':
+            case 'ClassDeclaration':
+            case 'MountStatement':
+            case 'EffectStatement':
+                return;
+            default:
+                forEachChild(node, visit);
+        }
+    };
+    visit(component.body);
+    return found;
+}

package/dist/refs.d.ts

@@ -0,0 +1,49 @@
+import type * as ast from './ast.ts';
+/** Why markup may be created more than once, so that a ref cannot point into it. */
+export type Repeated = 'for' | 'if' | 'switch' | 'expression' | 'function' | 'block';
+/** An attribute of markup, the element it is on, and whether that markup is created once. */
+export interface MarkupBinding<A> {
+    attribute: A;
+    element: ast.ElementExpression;
+    /** Null when the markup is created exactly once. */
+    repeated: Repeated | null;
+}
+export type RefBinding = MarkupBinding<ast.JsxAttribute>;
+/** `ref={input}` of an element or a component use. */
+export declare function refAttribute(node: ast.ElementExpression): ast.JsxAttribute | undefined;
+/** The ref an element is bound to: `input` in `<input ref={input} />`. */
+export declare function refName(node: ast.ElementExpression): string | null;
+/**
+ * The attributes that are set where the ref is declared: strings and attributes without a value,
+ * before the first spread, which may override them. Values in braces, handlers and `bind:` are
+ * set by the markup.
+ */
+export declare function constantAttributes(node: ast.ElementExpression): ast.JsxAttribute[];
+/** The `ref={...}` attributes in the markup of a body; see markupBindings. */
+export declare function refBindings(body: ast.BlockStatement): RefBinding[];
+/**
+ * The attributes that `wanted` picks in the markup of a body, and whether that markup is created
+ * exactly once: what a `return` gives (also through the wrapper a decorator returns),
+ * `const x = <markup>` at the top level, and the elements and children of components inside them.
+ */
+export declare function markupBindings<A extends ast.JsxAttribute | ast.JsxSpreadAttribute>(body: ast.BlockStatement, wanted: (attribute: ast.JsxAttribute | ast.JsxSpreadAttribute) => attribute is A): MarkupBinding<A>[];
+/**
+ * For each ref of a checked body, the element its markup binds it to. The wrapper of a decorator
+ * is copied to every `return` of a component, so there may be several, all alike.
+ */
+export declare function refTargets(body: ast.BlockStatement): Map<string, ast.ElementExpression>;
+/** Why the element a component creates is not known in advance; e.g. `has several returns`. */
+export type Root = ast.ElementExpression | string;
+/**
+ * What a component returns, if it is known in advance: an element or the use of a component in
+ * its own markup. Through `const content = <markup>`, which is how the wrapper of a decorator gets
+ * it. Otherwise why it is not known, as a phrase after "it".
+ */
+export declare function ownRoot(component: ast.ComponentDeclaration): Root;
+/** `<Card />`, or a component from a value: `<section.content />`, `<Page />`. */
+export declare function isComponentUse(node: ast.ElementExpression): boolean;
+/**
+ * The element at the top of what a component creates, through the components it returns.
+ * `rootOf` gives that of another component by its tag.
+ */
+export declare function componentRoot(component: ast.ComponentDeclaration, rootOf: (tag: string) => Root | undefined): Root;

package/dist/refs.js

@@ -0,0 +1,210 @@
+import { forEachChild } from "./walk.js";
+/** `ref={input}` of an element or a component use. */
+export function refAttribute(node) {
+    return node.attributes.find((attribute) => attribute.kind === 'JsxAttribute' && attribute.name.name === 'ref');
+}
+/** The ref an element is bound to: `input` in `<input ref={input} />`. */
+export function refName(node) {
+    const value = refAttribute(node)?.value;
+    return value?.kind === 'Identifier' ? value.name : null;
+}
+/**
+ * The attributes that are set where the ref is declared: strings and attributes without a value,
+ * before the first spread, which may override them. Values in braces, handlers and `bind:` are
+ * set by the markup.
+ */
+export function constantAttributes(node) {
+    const found = [];
+    for (const attribute of node.attributes) {
+        if (attribute.kind === 'JsxSpreadAttribute')
+            break;
+        const { name, value } = attribute;
+        if (name.name === 'ref' || name.name.startsWith('bind:') || /^on[A-Z]/.test(name.name)) {
+            continue;
+        }
+        if (value === null || value.kind === 'StringLiteral')
+            found.push(attribute);
+    }
+    return found;
+}
+/** The `ref={...}` attributes in the markup of a body; see markupBindings. */
+export function refBindings(body) {
+    return markupBindings(body, (attribute) => attribute.kind === 'JsxAttribute' && attribute.name.name === 'ref');
+}
+/**
+ * The attributes that `wanted` picks in the markup of a body, and whether that markup is created
+ * exactly once: what a `return` gives (also through the wrapper a decorator returns),
+ * `const x = <markup>` at the top level, and the elements and children of components inside them.
+ */
+export function markupBindings(body, wanted) {
+    const found = [];
+    const markup = (node, repeated) => {
+        for (const attribute of node.attributes) {
+            if (wanted(attribute)) {
+                found.push({ attribute, element: node, repeated });
+            }
+            else {
+                visit(attribute, repeated ?? 'expression');
+            }
+        }
+        for (const child of node.children) {
+            // The children of a component are created by the markup that uses it, once.
+            if (child.kind === 'ElementExpression')
+                markup(child, repeated);
+            else if (child.kind !== 'JsxStatementContainer')
+                visit(child, repeated ?? 'expression');
+            else
+                visit(child.statement, flowOf(child.statement));
+        }
+    };
+    const visit = (node, repeated) => {
+        switch (node.kind) {
+            case 'ElementExpression':
+                markup(node, repeated);
+                return;
+            case 'ReturnStatement':
+                // An early return of the body runs once, wherever it is.
+                if (repeated === 'block')
+                    returned(node);
+                else
+                    forEachChild(node, (child) => visit(child, repeated));
+                return;
+            case 'IfStatement':
+            case 'ForStatement':
+            case 'ForInStatement':
+            case 'SwitchStatement': {
+                // Control flow in markup; that of the body is a block, which runs once or in a loop.
+                const inner = repeated === 'block' || repeated === 'function' ? repeated : flowOf(node);
+                forEachChild(node, (child) => visit(child, inner));
+                return;
+            }
+            case 'FuncDeclaration':
+            case 'FuncExpression':
+            case 'ArrowFunction':
+            case 'EventHandler':
+            case 'MountStatement':
+            case 'EffectStatement':
+            case 'ClassDeclaration':
+                forEachChild(node, (child) => visit(child, 'function'));
+                return;
+            default:
+                forEachChild(node, (child) => visit(child, repeated));
+        }
+    };
+    const returned = (node) => {
+        for (const value of node.values) {
+            if (value.kind === 'ElementExpression')
+                markup(value, null);
+            else if (value.kind === 'ArrowFunction' || value.kind === 'FuncExpression')
+                wrapper(value);
+            else
+                visit(value, 'expression');
+        }
+    };
+    // The wrapper of a decorator runs once, where the component returns.
+    const wrapper = (fn) => {
+        for (const param of fn.params)
+            visit(param, 'function');
+        if (fn.body.kind === 'BlockStatement')
+            statements(fn.body.body);
+        else if (fn.body.kind === 'ElementExpression')
+            markup(fn.body, null);
+        else
+            visit(fn.body, 'expression');
+    };
+    const statements = (list) => {
+        for (const statement of list) {
+            const [value] = statement.kind === 'VariableDeclaration' ? statement.values : [];
+            if (statement.kind === 'ReturnStatement') {
+                returned(statement);
+            }
+            else if (value?.kind === 'ElementExpression' && statement.kind === 'VariableDeclaration') {
+                if (statement.names.length === 1)
+                    markup(value, null);
+                else
+                    visit(statement, 'block');
+            }
+            else {
+                visit(statement, 'block');
+            }
+        }
+    };
+    statements(body.body);
+    return found;
+}
+function flowOf(node) {
+    return node.kind === 'IfStatement' ? 'if' : node.kind === 'SwitchStatement' ? 'switch' : 'for';
+}
+/**
+ * For each ref of a checked body, the element its markup binds it to. The wrapper of a decorator
+ * is copied to every `return` of a component, so there may be several, all alike.
+ */
+export function refTargets(body) {
+    const targets = new Map();
+    const visit = (node) => {
+        const name = node.kind === 'ElementExpression' ? refName(node) : null;
+        if (name !== null && !targets.has(name))
+            targets.set(name, node);
+        forEachChild(node, visit);
+    };
+    visit(body);
+    return targets;
+}
+/**
+ * What a component returns, if it is known in advance: an element or the use of a component in
+ * its own markup. Through `const content = <markup>`, which is how the wrapper of a decorator gets
+ * it. Otherwise why it is not known, as a phrase after "it".
+ */
+export function ownRoot(component) {
+    const returns = [];
+    const visit = (node) => {
+        if (node.kind === 'ReturnStatement')
+            returns.push(node);
+        if (node.kind !== 'FuncDeclaration' &&
+            node.kind !== 'FuncExpression' &&
+            node.kind !== 'ArrowFunction' &&
+            node.kind !== 'ClassDeclaration' &&
+            node.kind !== 'MountStatement' &&
+            node.kind !== 'EffectStatement') {
+            forEachChild(node, visit);
+        }
+    };
+    forEachChild(component.body, visit);
+    if (returns.length > 1)
+        return 'has several returns, so its element is not known in advance';
+    const constants = new Map();
+    for (const statement of component.body.body) {
+        const [name] = statement.kind === 'VariableDeclaration' ? statement.names : [];
+        if (statement.kind === 'VariableDeclaration' && statement.keyword === 'const' && name) {
+            if (statement.names.length === 1 && statement.values.length === 1) {
+                constants.set(name.name, statement.values[0]);
+            }
+        }
+    }
+    let [value] = returns[0]?.values ?? [];
+    const seen = new Set();
+    while (value?.kind === 'Identifier' && constants.has(value.name) && !seen.has(value.name)) {
+        seen.add(value.name);
+        value = constants.get(value.name);
+    }
+    if (value?.kind !== 'ElementExpression') {
+        return 'does not return markup of its own, so its element is not known in advance';
+    }
+    return value.tag === null ? 'returns a fragment, which is empty once inserted' : value;
+}
+/** `<Card />`, or a component from a value: `<section.content />`, `<Page />`. */
+export function isComponentUse(node) {
+    return node.value !== null || (node.tag !== null && /^[A-Z]/.test(node.tag.name));
+}
+/**
+ * The element at the top of what a component creates, through the components it returns.
+ * `rootOf` gives that of another component by its tag.
+ */
+export function componentRoot(component, rootOf) {
+    const own = ownRoot(component);
+    if (typeof own === 'string' || !isComponentUse(own))
+        return own;
+    const tag = own.tag.name;
+    const inner = rootOf(tag) ?? 'is not known in advance';
+    return typeof inner === 'string' ? `returns <${tag}>, which ${inner}` : inner;
+}

package/dist/run.d.ts

@@ -0,0 +1 @@
+export {};