rooklang 0.0.0-stage → 0.3.1

package/dist/checker/completion-names.js

@@ -0,0 +1,100 @@
+// Names for completion in editors that the types cannot list: the members of strings, numbers and
+// arrays in builtins.ts are found by name, and without a library there is no list of HTML tags.
+// tests/completion.test.ts checks that each member listed here exists.
+export const STRING_MEMBERS = [
+    'length',
+    'at',
+    'charAt',
+    'charCodeAt',
+    'codePointAt',
+    'indexOf',
+    'lastIndexOf',
+    'includes',
+    'startsWith',
+    'endsWith',
+    'slice',
+    'substring',
+    'toUpperCase',
+    'toLowerCase',
+    'trim',
+    'trimStart',
+    'trimEnd',
+    'normalize',
+    'toString',
+    'split',
+    'replace',
+    'replaceAll',
+    'repeat',
+    'padStart',
+    'padEnd',
+    'concat',
+    'localeCompare',
+    'match',
+];
+export const NUMBER_MEMBERS = ['toFixed', 'toPrecision', 'toString', 'toLocaleString'];
+export const BOOL_MEMBERS = ['toString'];
+export const BIGINT_MEMBERS = ['toString', 'toLocaleString', 'valueOf'];
+export const ARRAY_MEMBERS = [
+    'length',
+    'push',
+    'unshift',
+    'pop',
+    'shift',
+    'at',
+    'indexOf',
+    'lastIndexOf',
+    'includes',
+    'join',
+    'slice',
+    'splice',
+    'concat',
+    'reverse',
+    'fill',
+    'sort',
+    'map',
+    'flatMap',
+    'filter',
+    'find',
+    'findLast',
+    'findIndex',
+    'findLastIndex',
+    'some',
+    'every',
+    'forEach',
+    'reduce',
+    'entries',
+    'keys',
+    'values',
+    'toString',
+];
+/** HTML tags, for completion without TypeScript's `HTMLElementTagNameMap`. */
+export const HTML_TAGS = [
+    ...['a', 'abbr', 'address', 'article', 'aside', 'audio', 'b', 'blockquote', 'br', 'button'],
+    ...['canvas', 'caption', 'code', 'col', 'colgroup', 'data', 'datalist', 'dd', 'del', 'details'],
+    ...['dfn', 'dialog', 'div', 'dl', 'dt', 'em', 'fieldset', 'figcaption', 'figure', 'footer'],
+    ...['form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hgroup', 'hr', 'i', 'iframe', 'img'],
+    ...['input', 'ins', 'kbd', 'label', 'legend', 'li', 'main', 'mark', 'menu', 'meter', 'nav'],
+    ...['object', 'ol', 'optgroup', 'option', 'output', 'p', 'picture', 'pre', 'progress', 'q'],
+    ...['s', 'samp', 'search', 'section', 'select', 'slot', 'small', 'source', 'span', 'strong'],
+    ...['sub', 'summary', 'sup', 'svg', 'table', 'tbody', 'td', 'template', 'textarea', 'tfoot'],
+    ...['th', 'thead', 'time', 'tr', 'track', 'u', 'ul', 'var', 'video', 'wbr'],
+];
+/** Event attributes as programs write them: `on` and the event in camel case. */
+export const EVENT_ATTRIBUTES = [
+    ...['onClick', 'onDblClick', 'onContextMenu', 'onAuxClick'],
+    ...['onInput', 'onChange', 'onSubmit', 'onReset', 'onInvalid', 'onSelect'],
+    ...['onKeyDown', 'onKeyUp', 'onFocus', 'onBlur', 'onFocusIn', 'onFocusOut'],
+    ...['onMouseDown', 'onMouseUp', 'onMouseMove', 'onMouseEnter', 'onMouseLeave', 'onMouseOver'],
+    ...['onMouseOut', 'onWheel', 'onScroll', 'onScrollEnd'],
+    ...['onPointerDown', 'onPointerUp', 'onPointerMove', 'onPointerEnter', 'onPointerLeave'],
+    ...['onPointerCancel', 'onTouchStart', 'onTouchMove', 'onTouchEnd', 'onTouchCancel'],
+    ...['onDragStart', 'onDrag', 'onDragEnd', 'onDragEnter', 'onDragOver', 'onDragLeave', 'onDrop'],
+    ...['onCopy', 'onCut', 'onPaste', 'onLoad', 'onError', 'onToggle', 'onClose', 'onCancel'],
+    ...['onAnimationStart', 'onAnimationEnd', 'onTransitionEnd'],
+    ...['onPlay', 'onPause', 'onEnded', 'onTimeUpdate', 'onVolumeChange'],
+];
+/** DOM properties that attributes spell differently. */
+export const ATTRIBUTE_NAMES = new Map([
+    ['className', 'class'],
+    ['htmlFor', 'for'],
+]);

package/dist/checker/completion.d.ts

@@ -0,0 +1,25 @@
+import type * as ast from '../ast.ts';
+import { IteratorChecker } from './iterators.ts';
+import type { CompletionResult } from './context.ts';
+import { type Type } from './types.ts';
+export declare abstract class CompletionChecker extends IteratorChecker {
+    protected completion: CompletionResult | null;
+    private atCursor;
+    /** The first check of the cursor counts: a component's body, for one, is checked for each use. */
+    private complete;
+    protected checkIdentifier(node: ast.Identifier): Type;
+    protected checkChain(node: ast.MemberExpression | ast.IndexExpression | ast.CallExpression, expected?: Type | null): [Type, boolean];
+    protected resolveTypeName(name: ast.Identifier, typeArgs?: readonly ast.TypeNode[]): Type;
+    protected checkElement(node: ast.ElementExpression): Type;
+    private valueNames;
+    private bindingCompletion;
+    private typeNames;
+    private tagNames;
+    /** Properties of a component, or attributes and events of an element, not given yet. */
+    private attributeNames;
+    /** The members of a value of type `type` that the code here may use. */
+    private membersOf;
+    /** Whether the code here may use a member: private and protected ones only in their classes. */
+    private canUse;
+    private scopes;
+}

package/dist/checker/completion.js

@@ -0,0 +1,222 @@
+import { IteratorChecker } from "./iterators.js";
+import { ARRAY_MEMBERS, ATTRIBUTE_NAMES, BIGINT_MEMBERS, BOOL_MEMBERS, EVENT_ATTRIBUTES, HTML_TAGS, NUMBER_MEMBERS, STRING_MEMBERS, } from "./completion-names.js";
+import { isSubclass, literalBase, memberNames, memberTypeOf, nonNull, typeToString, union, UNKNOWN, } from "./types.js";
+// Completion in editors (src/completion.ts): the editor writes the name `options.completion` where
+// the cursor is, and this layer lists what can be written there when the check reaches that name:
+// the names in scope, the members of the value before a dot, the types, the tags of markup or the
+// attributes of an element. The name itself is not an error: the check goes on as if it were
+// `unknown`.
+const PRIMITIVE_MEMBERS = {
+    string: STRING_MEMBERS,
+    number: NUMBER_MEMBERS,
+    bigint: BIGINT_MEMBERS,
+    bool: BOOL_MEMBERS,
+};
+export class CompletionChecker extends IteratorChecker {
+    completion = null;
+    atCursor(node) {
+        return node.name === this.options.completion;
+    }
+    /** The first check of the cursor counts: a component's body, for one, is checked for each use. */
+    complete(context, items) {
+        this.completion ??= { context, items: items() };
+    }
+    checkIdentifier(node) {
+        if (!this.atCursor(node))
+            return super.checkIdentifier(node);
+        this.complete('value', () => this.valueNames());
+        return UNKNOWN;
+    }
+    checkChain(node, expected = null) {
+        if (node.kind !== 'MemberExpression' || !this.atCursor(node.property)) {
+            return super.checkChain(node, expected);
+        }
+        const [object] = node.object.kind === 'SuperExpression'
+            ? [this.superType(node.object)]
+            : this.chainPart(node.object);
+        this.complete('member', () => [...this.membersOf(nonNull(object))].map(([name, member]) => ({
+            name,
+            kind: member.method ? 'method' : 'property',
+            detail: typeToString(member.type),
+        })));
+        return [UNKNOWN, false];
+    }
+    resolveTypeName(name, typeArgs = []) {
+        if (!this.atCursor(name))
+            return super.resolveTypeName(name, typeArgs);
+        this.complete('type', () => this.typeNames());
+        return UNKNOWN;
+    }
+    checkElement(node) {
+        const { tag } = node;
+        if (tag && this.atCursor(tag)) {
+            this.complete('tag', () => this.tagNames());
+            return UNKNOWN;
+        }
+        const cursor = node.attributes.some((attribute) => attribute.kind === 'JsxAttribute' && this.atCursor(attribute.name));
+        if (tag && cursor)
+            this.complete('attribute', () => this.attributeNames(node, tag.name));
+        return super.checkElement(node);
+    }
+    // ─── Lists ─────────────────────────────────────────────────────────────────────────────────────
+    valueNames() {
+        const found = new Map();
+        // An inner declaration hides an outer one with the same name.
+        for (const scope of this.scopes()) {
+            for (const binding of scope.values.values()) {
+                if (!found.has(binding.name))
+                    found.set(binding.name, this.bindingCompletion(binding));
+            }
+        }
+        for (const name of this.options.library?.names?.('value') ?? []) {
+            if (!found.has(name))
+                found.set(name, { name, kind: 'variable' });
+        }
+        return [...found.values()];
+    }
+    bindingCompletion(binding) {
+        const { name, kind, component } = binding;
+        if (component) {
+            return { name, kind: 'component', detail: typeToString(this.componentValue(component)) };
+        }
+        const type = binding.type && (this.flow.get(binding) ?? binding.type);
+        const detail = type ? { detail: typeToString(type) } : {};
+        if (kind === 'function' || type?.kind === 'function')
+            return { name, kind: 'function', ...detail };
+        if (kind === 'class' || type?.kind === 'classValue')
+            return { name, kind: 'class', ...detail };
+        return { name, kind: kind === 'const' ? 'constant' : 'variable', ...detail };
+    }
+    typeNames() {
+        const found = new Map();
+        for (const scope of this.scopes()) {
+            for (const [name, entry] of scope.types) {
+                if (!found.has(name)) {
+                    found.set(name, { name, kind: entry.kind === 'class' ? 'class' : 'type' });
+                }
+            }
+        }
+        for (const name of this.options.library?.names?.('type') ?? []) {
+            if (!found.has(name))
+                found.set(name, { name, kind: 'type' });
+        }
+        return [...found.values()];
+    }
+    tagNames() {
+        const components = [...this.scopes()].flatMap((scope) => [...scope.values.values()].flatMap((binding) => binding.component ? [this.bindingCompletion(binding)] : []));
+        const tags = this.options.library?.names?.('tag') ?? HTML_TAGS;
+        return [...components, ...[...tags].map((name) => ({ name, kind: 'tag' }))];
+    }
+    /** Properties of a component, or attributes and events of an element, not given yet. */
+    attributeNames(node, tag) {
+        const given = new Set(node.attributes.flatMap((attribute) => attribute.kind === 'JsxAttribute' ? [attribute.name.name] : []));
+        const items = [{ name: 'ref', kind: 'attribute' }];
+        if (/^[A-Z]/.test(tag)) {
+            const info = this.lookupValue(tag)?.component;
+            if (!info)
+                return [];
+            this.resolveProps(info);
+            for (const [name, prop] of info.props) {
+                if (name !== 'children') {
+                    items.push({ name, kind: 'property', detail: typeToString(prop.type) });
+                }
+            }
+        }
+        else {
+            for (const [property, member] of this.membersOf(this.elementOf(tag))) {
+                // Members like `onclick` from TypeScript's lib are events, which are written `onClick`.
+                if (member.method || member.type.kind === 'function' || property.startsWith('on'))
+                    continue;
+                const name = ATTRIBUTE_NAMES.get(property) ?? property;
+                items.push({ name, kind: 'attribute', detail: typeToString(member.type) });
+            }
+            for (const name of EVENT_ATTRIBUTES)
+                items.push({ name, kind: 'attribute' });
+        }
+        return items.filter((item) => !given.has(item.name));
+    }
+    // ─── Members ───────────────────────────────────────────────────────────────────────────────────
+    /** The members of a value of type `type` that the code here may use. */
+    membersOf(type) {
+        const members = new Map();
+        const add = (names, find) => {
+            for (const name of names) {
+                const member = members.has(name) ? undefined : find(name);
+                if (member && member !== 'any')
+                    members.set(name, member);
+            }
+        };
+        switch (type.kind) {
+            case 'literal':
+                return this.membersOf(literalBase(type));
+            case 'param':
+                return type.constraint ? this.membersOf(type.constraint) : members;
+            case 'string':
+            case 'number':
+            case 'bigint':
+            case 'bool': {
+                const library = this.options.library?.primitive(type.kind);
+                add(PRIMITIVE_MEMBERS[type.kind], (name) => this.memberOf(type, name));
+                if (library?.kind === 'object')
+                    add(memberNames(library.members), (name) => this.memberOf(type, name));
+                break;
+            }
+            case 'array': {
+                const library = this.options.library?.array(type.element);
+                const find = (name) => this.arrayMemberOf(type.element, name);
+                add(ARRAY_MEMBERS, find);
+                if (library?.kind === 'object')
+                    add(memberNames(library.members), find);
+                break;
+            }
+            case 'object':
+                add(memberNames(type.members), (name) => type.members.get(name));
+                break;
+            case 'class':
+            case 'classValue':
+                for (let info = type.info; info; info = info.superClass) {
+                    this.ensureClassResolved(info);
+                    for (const [name, member] of type.kind === 'class' ? info.members : info.statics) {
+                        if (members.has(name) || !this.canUse(member))
+                            continue;
+                        members.set(name, type.kind === 'class' && type.args
+                            ? { ...member, type: memberTypeOf(type, member) }
+                            : member);
+                    }
+                }
+                break;
+            // The members that every type of the union has.
+            case 'union': {
+                const [first, ...rest] = type.types.map((each) => this.membersOf(each));
+                for (const [name, member] of first ?? []) {
+                    const others = rest.map((each) => each.get(name));
+                    if (others.some((other) => other === undefined))
+                        continue;
+                    const all = [member, ...others];
+                    members.set(name, {
+                        ...member,
+                        type: union(all.map((each) => each.type)),
+                        method: all.every((each) => each.method),
+                    });
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        return members;
+    }
+    /** Whether the code here may use a member: private and protected ones only in their classes. */
+    canUse({ owner, visibility }) {
+        if (!owner || visibility === 'public')
+            return true;
+        const current = this.cls?.info;
+        return visibility === 'private'
+            ? current === owner
+            : current !== undefined && isSubclass(current, owner);
+    }
+    *scopes() {
+        for (let scope = this.scope; scope; scope = scope.parent)
+            yield scope;
+    }
+}

package/dist/checker/component-values.d.ts

@@ -0,0 +1,11 @@
+import type * as ast from '../ast.ts';
+import { ComponentChecker } from './components.ts';
+import type { ComponentInfo } from './context.ts';
+import { type ComponentType, type Type } from './types.ts';
+export declare abstract class ComponentValueChecker extends ComponentChecker {
+    /** `Card` as a value: `comp(title string, kind ?Kind)`, without `...attrs`. */
+    protected componentValue(info: ComponentInfo): ComponentType;
+    /** `<section.content title="Hi" />`: the attributes are checked against the type of the value. */
+    protected checkValueTagUse(node: ast.ElementExpression, tag: ast.Identifier, value: ast.Expression): Type;
+    private checkValueTagAttributes;
+}

package/dist/checker/component-values.js

@@ -0,0 +1,88 @@
+import { ComponentChecker } from "./components.js";
+import { isUntyped } from "./helpers.js";
+const upperFirst = (name) => name.charAt(0).toUpperCase() + name.slice(1);
+import { isNullable, typeToString, UNKNOWN, } from "./types.js";
+// Components as values: `content: Intro` has the type `comp()`, and a tag takes the component
+// from a value, `<section.content />`, or `<Page />` when `Page` is a variable. Such a tag passes
+// the properties by their positions in the type, so the component is a function in its module.
+export class ComponentValueChecker extends ComponentChecker {
+    /** `Card` as a value: `comp(title string, kind ?Kind)`, without `...attrs`. */
+    componentValue(info) {
+        const params = info.node.params.flatMap((param) => {
+            const prop = info.props.get(param.name.name);
+            return param.rest || !prop ? [] : [{ name: param.name.name, ...prop }];
+        });
+        return { kind: 'component', params };
+    }
+    /** `<section.content title="Hi" />`: the attributes are checked against the type of the value. */
+    checkValueTagUse(node, tag, value) {
+        const type = this.checkValue(value);
+        const name = tag.name;
+        if (isUntyped(type) || type.kind !== 'component') {
+            if (isNullable(type)) {
+                // Only variables are narrowed, so a path goes into one first.
+                const variable = /^[A-Z]/.test(name) ? name : upperFirst(name.split('.').at(-1));
+                const show = `{if ${variable} != null { <${variable} /> }}`;
+                this.error(name === variable
+                    ? `<${name}> may be null: show it with {if}, e.g. ${show}`
+                    : `<${name}> may be null: put it into a variable and show it with {if}, e.g. const ${variable} = ${name}, then ${show}`, tag);
+            }
+            else if (!isUntyped(type)) {
+                this.error(`<${name}> is ${typeToString(type)}, not a component: give it a type like comp(title string)`, tag);
+            }
+            else if (type.kind === 'any' && (node.attributes.length > 0 || node.children.length > 0)) {
+                // The tag passes the properties by position, which only the type knows.
+                this.error(`<${name}> is any, so the order of its properties is not known: give it a type like comp(title string)`, tag);
+            }
+            this.checkValueTagAttributes(node, null);
+            return this.dom.node;
+        }
+        this.checkValueTagAttributes(node, type);
+        return this.dom.node;
+    }
+    checkValueTagAttributes(node, type) {
+        const name = node.tag.name;
+        const given = new Set();
+        for (const attribute of node.attributes) {
+            if (attribute.kind === 'JsxSpreadAttribute') {
+                this.checkValue(attribute.argument);
+                // After the error, missing properties would only repeat it.
+                for (const param of type?.params ?? [])
+                    given.add(param.name);
+                this.error(`<${name}> takes its component from a value, so its properties are passed one by one, not spread`, attribute);
+                continue;
+            }
+            const attributeName = attribute.name.name;
+            const param = type?.params.find((each) => each.name === attributeName);
+            if (attributeName === 'ref') {
+                this.error(`ref cannot point to <${name}>: its component is a value, so its element is not known in advance`, attribute);
+                continue;
+            }
+            if (given.has(attributeName)) {
+                this.error(`duplicate property "${attributeName}"`, attribute.name);
+            }
+            given.add(attributeName);
+            if (attributeName === 'children' && param) {
+                this.error(`pass children between the tags: <${name}>...</${name}>`, attribute.name);
+            }
+            else if (param) {
+                this.checkProp(attribute, param.type, name);
+            }
+            else if (type) {
+                this.error(`<${name}> has no property "${attributeName}"`, attribute.name);
+            }
+            else {
+                this.checkProp(attribute, UNKNOWN, name);
+            }
+        }
+        for (const param of type?.params ?? []) {
+            if (!param.optional && !given.has(param.name)) {
+                this.error(`<${name}> needs the property "${param.name}"`, node.tag);
+            }
+        }
+        if (type && node.children.length > 0 && !type.params.some((each) => each.name === 'children')) {
+            this.error(`<${name}> takes no children`, node.children[0]);
+        }
+        this.checkChildren(node.children);
+    }
+}

package/dist/checker/components.d.ts

@@ -0,0 +1,37 @@
+import type * as ast from '../ast.ts';
+import type { ComponentInfo } from './context.ts';
+import { ForwardingChecker } from './forwarding.ts';
+import { type Type } from './types.ts';
+export declare abstract class ComponentChecker extends ForwardingChecker {
+    protected resolveProps(info: ComponentInfo): void;
+    /** The body runs once where the component is used and must end with `return <markup>`. */
+    protected checkComponentBody(info: ComponentInfo): void;
+    /** `<Card title="Profile">...</Card>`: properties are checked like the arguments of a call. */
+    protected checkComponentUse(node: ast.ElementExpression, tag: ast.Identifier): Type;
+    /**
+     * `<Product {...product} />`: fields of the object with the names of properties are passed as
+     * those properties; other fields are ignored. Adds the names of the given properties to `given`.
+     */
+    protected checkSpreadProps(argument: ast.Expression, info: ComponentInfo, component: string, given: Set<string>): void;
+    protected checkProp(attribute: ast.JsxAttribute, type: Type, component: string): void;
+    /**
+     * The component's code is inlined where it is used, so the names of the module that it uses
+     * must not be hidden there by local declarations.
+     */
+    protected checkHygiene(info: ComponentInfo, tag: ast.Identifier): void;
+    /** The type of `<Card />`: what its markup creates, through the wrappers of its decorators. */
+    protected componentResult(info: ComponentInfo, seen: Set<ComponentInfo>): Type;
+    /** What the markup the component itself returns creates. */
+    protected ownResult(info: ComponentInfo, seen: Set<ComponentInfo>): Type;
+    /** The type of the markup a component returns, found without checking it again. */
+    protected markupType(value: ast.Expression | undefined, seen: Set<ComponentInfo>): Type;
+    /**
+     * A component may use itself, but some use on the cycle must be under a condition (if, for, a
+     * branch of `?:`...), or creating the component never ends.
+     */
+    protected checkEndlessRecursion(): void;
+    /** `@html-tag` components: valid and different tags, and properties HTMLElement does not have. */
+    protected checkHtmlTags(): void;
+    /** The type of a property of a web component of this module, by its tag and an attribute. */
+    protected webComponentProperty(tag: string, attribute: string): Type | null;
+}