rooklang 0.0.0-stage → 0.3.0

package/dist/checker/components.js

@@ -0,0 +1,287 @@
+import { attributeName, htmlTagName, RESERVED_PROPERTIES, tagNameProblem } from "../html-tag.js";
+import { freeNames } from "../names.js";
+import { endlessRecursion } from "../recursion.js";
+import { CONTENT } from "./dom.js";
+import { lookupIn, ownStatements, isUntyped, callSignature } from "./helpers.js";
+import { ATTRIBUTES, ForwardingChecker } from "./forwarding.js";
+import { BOOL, func, hasZeroValue, isAssignable, isNullable, nonNull, spreadFields, typesEqual, typeToString, UNKNOWN, } from "./types.js";
+// Components: their bodies and uses, properties and spread, names they use from the module, recursion.
+export class ComponentChecker extends ForwardingChecker {
+    resolveProps(info) {
+        for (const param of info.node.params) {
+            // `...attrs` takes the attributes that are not properties.
+            if (param.rest)
+                continue;
+            const name = param.name.name;
+            const type = param.type ? this.resolveType(param.type) : UNKNOWN;
+            if (name === 'children' && type !== CONTENT && type.kind !== 'unknown') {
+                this.error('the "children" property has the type Content', param.type ?? param);
+            }
+            if (info.props.has(name))
+                this.error(`duplicate property "${name}"`, param.name);
+            const optional = param.defaultValue !== null || isNullable(type) || name === 'children';
+            info.props.set(name, { type, optional });
+        }
+    }
+    /** The body runs once where the component is used and must end with `return <markup>`. */
+    checkComponentBody(info) {
+        const { node } = info;
+        this.checkDecoratorUses(info);
+        const last = node.body.body.at(-1);
+        if (last?.kind !== 'ReturnStatement' || last.values.length !== 1) {
+            this.error('a component ends with "return <markup>"', {
+                start: node.body.end - 1,
+                end: node.body.end,
+            });
+        }
+        for (const statement of ownStatements(node.body)) {
+            if (statement.kind === 'DeferStatement') {
+                this.error('defer is not supported in components yet', statement);
+            }
+        }
+        const types = [];
+        this.checkAttrsSpreads(info);
+        for (const param of node.params) {
+            const prop = info.props.get(param.name.name);
+            const type = param.rest ? ATTRIBUTES : (prop?.type ?? UNKNOWN);
+            types.push(type);
+            if (param.defaultValue) {
+                const value = this.checkValue(param.defaultValue, type);
+                this.expectAssignable(value, type, param.defaultValue);
+            }
+        }
+        // Other modules get the type of <Card /> from here.
+        if (node.exported)
+            info.result = this.componentResult(info, new Set());
+        const saved = this.component;
+        this.component = info;
+        try {
+            this.withClass(null, () => this.checkFunction(node.params, func(types, []), null, node.body, {
+                paramKind: 'prop',
+                isComponent: true,
+            }));
+        }
+        finally {
+            this.component = saved;
+        }
+    }
+    /** `<Card title="Profile">...</Card>`: properties are checked like the arguments of a call. */
+    checkComponentUse(node, tag) {
+        const binding = this.lookupValue(tag.name);
+        const info = binding?.component;
+        if (!info) {
+            this.error(binding ? `"${tag.name}" is not a component` : `unknown component <${tag.name}>`, tag);
+            return UNKNOWN;
+        }
+        // The code of a function component is not inlined here, but that of another module may be.
+        if (!info.isFunction)
+            this.checkHygiene(info, tag);
+        for (const name of info.inline?.globals ?? []) {
+            const binding = this.lookupValue(name);
+            if (!binding || binding.kind === 'builtin')
+                continue;
+            this.error(`<${tag.name}> uses the global "${name}", but here it is another declaration: rename it`, tag);
+            break;
+        }
+        const given = new Set();
+        const spread = new Set();
+        for (const attribute of node.attributes) {
+            if (attribute.kind === 'JsxSpreadAttribute') {
+                this.checkSpreadProps(attribute.argument, info, tag.name, spread);
+                continue;
+            }
+            const name = attribute.name.name;
+            const prop = info.props.get(name);
+            if (name === 'ref') {
+                this.checkRefAttribute(attribute, node);
+                continue;
+            }
+            if (given.has(name))
+                this.error(`duplicate property "${name}"`, attribute.name);
+            given.add(name);
+            if (name === 'children' && prop) {
+                this.error(`pass children between the tags: <${tag.name}>...</${tag.name}>`, attribute.name);
+            }
+            else if (!prop) {
+                if (!this.checkForwarded(attribute, info, tag.name)) {
+                    this.error(`<${tag.name}> has no property "${name}"`, attribute.name);
+                }
+            }
+            else {
+                this.checkProp(attribute, prop.type, tag.name);
+            }
+        }
+        for (const [name, prop] of info.props) {
+            if (!prop.optional && !given.has(name) && !spread.has(name)) {
+                this.error(`<${tag.name}> needs the property "${name}"`, tag);
+            }
+        }
+        if (node.children.length > 0 && !info.props.has('children')) {
+            this.error(`<${tag.name}> takes no children`, node.children[0]);
+        }
+        this.checkChildren(node.children);
+        return this.componentResult(info, new Set());
+    }
+    /**
+     * `<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`.
+     */
+    checkSpreadProps(argument, info, component, given) {
+        const type = this.checkValue(argument);
+        if (isUntyped(type)) {
+            for (const name of info.props.keys())
+                given.add(name);
+            return;
+        }
+        const fields = isNullable(type) ? null : spreadFields(type);
+        if (!fields) {
+            if (isNullable(type))
+                this.nullError(argument);
+            else {
+                this.error(`cannot spread ${typeToString(type)} into the properties of <${component}>`, argument);
+            }
+            // After the error, missing properties would only repeat it.
+            for (const name of info.props.keys())
+                given.add(name);
+            return;
+        }
+        for (const [name, prop] of info.props) {
+            const field = fields.get(name);
+            if (field === undefined || name === 'children')
+                continue;
+            given.add(name);
+            this.expectAssignable(field, prop.type, argument, ` for "${name}" of <${component}>`);
+        }
+    }
+    checkProp(attribute, type, component) {
+        const name = attribute.name.name;
+        const { value } = attribute;
+        if (value?.kind === 'EventHandler') {
+            // Code for a callback property; `event` is the callback's first argument, if it has one.
+            const signature = callSignature(nonNull(type));
+            if (!signature && !isUntyped(type)) {
+                this.error(`"${name}" of <${component}> is not a function, so it needs a value`, value);
+                return;
+            }
+            this.checkEventHandler(value, signature?.params[0] ?? null);
+            return;
+        }
+        // A string gets the literal type where one is expected: <Button kind="ghost" />.
+        const valueType = value === null ? BOOL : this.checkValue(value, type);
+        this.expectAssignable(valueType, type, value ?? attribute, ` for "${name}" of <${component}>`);
+    }
+    /**
+     * 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.
+     */
+    checkHygiene(info, tag) {
+        // The code of its decorators is inlined with it.
+        info.freeNames ??= freeNames(info.expanded);
+        for (const name of info.freeNames) {
+            if (this.lookupValue(name) !== lookupIn(this.moduleScope, name)) {
+                this.error(`<${tag.name}> uses "${name}" of the module, but here "${name}" is another declaration: rename one of them`, tag);
+                return;
+            }
+        }
+    }
+    /** The type of `<Card />`: what its markup creates, through the wrappers of its decorators. */
+    componentResult(info, seen) {
+        return info.result ?? this.wrappedType(info, this.ownResult(info, seen), seen);
+    }
+    /** What the markup the component itself returns creates. */
+    ownResult(info, seen) {
+        seen.add(info);
+        // With early returns, the result is what all the returned elements have in common.
+        const types = ownStatements(info.node.body)
+            .filter((statement) => statement.kind === 'ReturnStatement')
+            .map((statement) => this.markupType(statement.values[0], seen));
+        const [first] = types;
+        if (first === undefined)
+            return this.dom.node;
+        if (types.every((type) => typesEqual(type, first)))
+            return first;
+        const { element, node } = this.dom;
+        return types.every((type) => isAssignable(type, element)) ? element : node;
+    }
+    /** The type of the markup a component returns, found without checking it again. */
+    markupType(value, seen) {
+        if (value?.kind !== 'ElementExpression')
+            return this.dom.node;
+        if (value.tag === null)
+            return this.dom.fragment;
+        if (!/^[A-Z]/.test(value.tag.name))
+            return this.elementOf(value.tag.name);
+        const other = lookupIn(this.moduleScope, value.tag.name)?.component;
+        if (!other || seen.has(other))
+            return this.dom.node;
+        return this.componentResult(other, new Set(seen));
+    }
+    /**
+     * 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.
+     */
+    checkEndlessRecursion() {
+        const components = new Map();
+        for (const statement of this.program.body) {
+            if (statement.kind !== 'ComponentDeclaration')
+                continue;
+            const info = this.moduleScope.values.get(statement.name.name)?.component;
+            components.set(statement.name.name, info?.expanded ?? statement);
+        }
+        for (const { cycle, tag } of endlessRecursion(components)) {
+            this.error(`endless recursion: ${cycle.join(' → ')} always creates itself again; put the use inside if or for`, tag);
+        }
+    }
+    /** `@html-tag` components: valid and different tags, and properties HTMLElement does not have. */
+    checkHtmlTags() {
+        const tags = new Map();
+        for (const statement of this.program.body) {
+            if (statement.kind !== 'ComponentDeclaration' || !statement.htmlTag)
+                continue;
+            const tag = htmlTagName(statement);
+            const given = statement.htmlTag.name;
+            const problem = tagNameProblem(tag);
+            const other = tags.get(tag);
+            if (problem) {
+                this.error(given
+                    ? `"${tag}" is not a valid name of a web component: ${problem}`
+                    : `the tag of "${statement.name.name}" would be "${tag}", not a valid name of a web component: ${problem}; give one, e.g. @html-tag("app-${tag}")`, given ?? statement.htmlTag);
+            }
+            else if (other) {
+                this.error(`the tag "${tag}" is already used by ${other.name.name}`, given ?? statement.htmlTag);
+            }
+            tags.set(tag, statement);
+            const info = this.moduleScope.values.get(statement.name.name)?.component;
+            for (const param of statement.params) {
+                const name = param.name.name;
+                const type = info?.props.get(name)?.type;
+                if (RESERVED_PROPERTIES.has(name)) {
+                    this.error(`a web component cannot have the property "${name}": HTMLElement has it already`, param.name);
+                }
+                else if (name !== 'children' && !param.defaultValue && type && !hasZeroValue(type)) {
+                    // `<app-card>` in HTML has no properties until they are set.
+                    this.error(`"${name}" needs a default value: the element can be created without it, e.g. in HTML, and ${typeToString(type)} has no zero value`, param.name);
+                }
+            }
+        }
+    }
+    /** The type of a property of a web component of this module, by its tag and an attribute. */
+    webComponentProperty(tag, attribute) {
+        for (const statement of this.program.body) {
+            if (statement.kind !== 'ComponentDeclaration' || !statement.htmlTag)
+                continue;
+            if (htmlTagName(statement) !== tag)
+                continue;
+            const info = this.moduleScope.values.get(statement.name.name)?.component;
+            if (!info)
+                return null;
+            for (const [name, prop] of info.props) {
+                if (name !== 'children' && (name === attribute || attributeName(name) === attribute)) {
+                    return prop.type;
+                }
+            }
+            return null;
+        }
+        return null;
+    }
+}

package/dist/checker/context.d.ts

@@ -0,0 +1,196 @@
+import type * as ast from '../ast.ts';
+import type { Wrapper } from '../decorators.ts';
+import type { Diagnostic } from '../diagnostics.ts';
+import type { InlinePackage } from '../inline-packages.ts';
+import type { Root } from '../refs.ts';
+import { type ClassInfo, type Type, type TypeParam } from './types.ts';
+export interface ModuleExports {
+    values: Map<string, Type>;
+    types: Map<string, Type>;
+    /** `export dec`: decorators have a namespace of their own. */
+    decorators?: Map<string, DecoratorInfo>;
+    /** `export comp`: components are used as tags, not as values. */
+    components?: Map<string, ComponentInfo>;
+}
+/** What `importModule` found: the module's exports, an error for the import, or nothing (untyped). */
+export type ImportResult = {
+    exports: ModuleExports;
+} | {
+    error: string;
+} | undefined;
+/**
+ * Types of the JS standard library and the DOM from TypeScript's lib files and global `@types`.
+ * They extend the built-in types of builtins.ts and dom.ts, which are used without them (in the
+ * browser).
+ */
+export interface Library {
+    /** A global value, e.g. `document`. */
+    value(name: string): Type | undefined;
+    /** A global type, e.g. `HTMLElement`. */
+    type(name: string): Type | undefined;
+    /** `String`, `Number`, `BigInt` or `Boolean`: members that the built-in types do not list. */
+    primitive(kind: 'string' | 'number' | 'bigint' | 'bool'): Type | undefined;
+    /** `Array<element>`: members that the built-in array type does not list. */
+    array(element: Type): Type | undefined;
+    /** What `<tag>` creates: `HTMLElementTagNameMap[tag]`, or `SVGElementTagNameMap[tag]` in SVG. */
+    element(tag: string, svg?: boolean): Type | undefined;
+    /** The event of `on<name>`: `HTMLElementEventMap[name]`, e.g. `MouseEvent` for `click`. */
+    event(name: string): Type | undefined;
+    /** For completion in editors: the names of the global values, the global types or the tags. */
+    names?(of: 'value' | 'type' | 'tag'): Iterable<string>;
+}
+export interface CheckOptions {
+    /** Called for imports of `.rk` modules; without it, every import is untyped (`any`). */
+    importModule?: (specifier: string) => ImportResult;
+    /**
+     * Called for the other imports (packages, `node:` modules, `.ts` files): their types come from
+     * TypeScript declarations. Without it, or for a module without types, the import is untyped.
+     */
+    importDeclarations?: (specifier: string) => ImportResult;
+    /** Types of the standard library and the DOM beyond the built-in ones. */
+    library?: Library;
+    /**
+     * For completion in editors: the name written where the cursor is. The result then lists what
+     * can be written there (see completion.ts).
+     */
+    completion?: string;
+}
+export interface CheckResult {
+    diagnostics: Diagnostic[];
+    /** Problems that do not stop compilation, e.g. a CSS selector that matches nothing. */
+    warnings: Diagnostic[];
+    exports: ModuleExports;
+    /** Types of every declaration at the top level of the module, exported or not. */
+    declarations: ModuleExports;
+    /** Types of checked expressions, for code generation (e.g. how to insert element children). */
+    types: WeakMap<ast.Expression, Type>;
+    /** With the `completion` option: what can be written at the cursor, if the check reached it. */
+    completion?: CompletionResult;
+}
+/** Where the cursor is: a value, a member after a dot, a type, a tag or an attribute of markup. */
+export type CompletionContext = 'value' | 'member' | 'type' | 'tag' | 'attribute';
+export interface CompletionResult {
+    context: CompletionContext;
+    items: Completion[];
+}
+export interface Completion {
+    name: string;
+    kind: 'variable' | 'constant' | 'function' | 'class' | 'component' | 'type' | 'property' | 'method' | 'keyword' | 'tag' | 'attribute';
+    /** The type, as Rook writes it. */
+    detail?: string;
+}
+export type BindingKind = 'let' | 'const' | 'state' | 'derived' | 'ref' | 'param' | 'prop' | 'function' | 'class' | 'import' | 'loop' | 'catch' | 'builtin' | 'component';
+export interface Binding {
+    name: string;
+    kind: BindingKind;
+    /** `null` while a variable is declared but its declaration has not been checked yet. */
+    type: Type | null;
+    /** For components, which exist only at compile time and are used as tags. */
+    component?: ComponentInfo;
+}
+export interface ComponentInfo {
+    node: ast.ComponentDeclaration;
+    /** Properties by name; optional ones have a default value or a nullable type. */
+    props: Map<string, {
+        type: Type;
+        optional: boolean;
+    }>;
+    /** Names from the module that the component's code uses, computed when first needed. */
+    freeNames: Set<string> | null;
+    /**
+     * Compiled to a function, not inlined: it uses itself, directly or through other components, it
+     * is a web component (`@html-tag`), or other modules use it (`export comp`).
+     */
+    isFunction: boolean;
+    /** The decorators applied to it that exist, in the order they are written. */
+    decorators: DecoratorInfo[];
+    /** The component with its decorators applied: the code that is inlined where it is used. */
+    expanded: ast.ComponentDeclaration;
+    /**
+     * The type of `<Card />` for an exported component, found in its module: the tags of its markup
+     * are names there.
+     */
+    result: Type | null;
+    /**
+     * The element at the top of what `<Card />` creates, which `<Card ref={card} />` creates in
+     * advance, or why it is not known; found in its module once its body is checked.
+     */
+    root: Root | null;
+    /**
+     * For an exported component: what another module needs to inline it instead of calling it, and
+     * the types of the expressions of this module, for the code generator there.
+     */
+    inline: InlinePackage | null;
+    expressionTypes: WeakMap<ast.Expression, Type> | null;
+}
+export interface DecoratorInfo {
+    node: ast.DecoratorDeclaration;
+    /** The types of the parameters, resolved with the other declarations of the module. */
+    params: Type[];
+    /** Public state, constants and functions, known once the body is checked. */
+    members: Map<string, PublicMember>;
+    /** The declarations of the body and the parameters: a member that is not public is one of them. */
+    names: Set<string>;
+    /** Names from the module that the decorator's code uses, computed when first needed. */
+    freeNames: Set<string> | null;
+    /** `return (content Element) => ...`, with the type of what it gets from the component. */
+    wrapper: {
+        node: Wrapper;
+        param: Type;
+        result: Type | null;
+    } | null;
+    /** The decorators after `needs` that exist; they are applied above it. */
+    needed: DecoratorInfo[];
+    /**
+     * For an exported decorator: the names of its module that its code uses, which other modules get
+     * through hidden exports, and the types of its expressions, for the code generator there.
+     */
+    moduleNames: string[];
+    expressionTypes: WeakMap<ast.Expression, Type> | null;
+    /** For an exported decorator: the components of its module that its code uses. */
+    inline: InlinePackage | null;
+}
+export interface PublicMember {
+    kind: 'state' | 'derived' | 'const' | 'func';
+    type: Type;
+}
+/** A `type` alias, resolved when first used. */
+export interface AliasEntry {
+    kind: 'alias';
+    node: ast.TypeAliasDeclaration;
+    scope: Scope;
+    /** `type Pair<A, B any> ...`: references give arguments for these. */
+    params: TypeParam[];
+    resolved: Type | null;
+    resolving: boolean;
+}
+export declare class Scope {
+    readonly parent: Scope | null;
+    readonly values: Map<string, Binding>;
+    readonly types: Map<string, Type | AliasEntry>;
+    constructor(parent: Scope | null);
+}
+export interface FunctionContext {
+    /** Declared result types, or `null` when they are inferred from the `return` statements. */
+    results: Type[] | null;
+    /** Types of the `return` statements, for inferring the results. */
+    returns: Type[][];
+    isConstructor: boolean;
+    /** The body of a component: every `return` gives markup. */
+    isComponent?: boolean;
+    /** An async function, which may wait: `await`, `<-ch`, `for v in ch`. */
+    isAsync?: boolean;
+}
+export interface ClassContext {
+    info: ClassInfo;
+    isStatic: boolean;
+}
+/**
+ * Types of variables narrowed by the code before the current point, e.g. `?User` → `User`
+ * after `if user == null { return }`.
+ */
+export type Flow = Map<Binding, Type>;
+export type Narrowing = [Binding, Type][];
+export declare const NARROWABLE: ReadonlySet<BindingKind>;
+/** Built-in globals. With a library, the untyped ones and the DOM types come from it instead. */
+export declare function globalScope(library: Library | undefined): Scope;

package/dist/checker/context.js

@@ -0,0 +1,35 @@
+import { GLOBAL_TYPES, GLOBAL_VALUES, LIBRARY_TYPES } from "./builtins.js";
+import {} from "./types.js";
+export class Scope {
+    parent;
+    values = new Map();
+    types = new Map();
+    constructor(parent) {
+        this.parent = parent;
+    }
+}
+export const NARROWABLE = new Set([
+    'let',
+    'const',
+    'state',
+    'derived',
+    'param',
+    'prop',
+    'catch',
+    'loop',
+]);
+/** Built-in globals. With a library, the untyped ones and the DOM types come from it instead. */
+export function globalScope(library) {
+    const scope = new Scope(null);
+    for (const [name, type] of GLOBAL_VALUES) {
+        if (library && type.kind === 'any')
+            continue;
+        scope.values.set(name, { name, kind: 'builtin', type });
+    }
+    for (const [name, type] of GLOBAL_TYPES) {
+        if (library && LIBRARY_TYPES.has(name))
+            continue;
+        scope.types.set(name, type);
+    }
+    return scope;
+}

package/dist/checker/control-flow.d.ts

@@ -0,0 +1,24 @@
+import type * as ast from '../ast.ts';
+import { type Binding, type Flow, type Narrowing } from './context.ts';
+import { StatementChecker } from './statements.ts';
+export declare abstract class ControlFlowChecker extends StatementChecker {
+    protected checkIf(node: ast.IfStatement): void;
+    protected checkFor(node: ast.ForStatement): void;
+    protected checkSimpleStatement(node: ast.SimpleStatement): void;
+    protected checkSwitch(node: ast.SwitchStatement): void;
+    /**
+     * `switch filter { case "all": ... default: ... }`: in a case the discriminant has the literals
+     * of its tests, in `default` the literals of no case.
+     */
+    protected narrowCase(node: ast.SwitchStatement, switchCase: ast.SwitchCase, entry: Flow): Narrowing;
+    protected checkTry(node: ast.TryStatement): void;
+    protected checkCondition(node: ast.Expression): void;
+    /** Variables whose type is narrowed when `node` evaluates to `assumeTrue`. */
+    protected narrow(node: ast.Expression, assumeTrue: boolean): Narrowing;
+    /** `x instanceof Date`: an instance of the class when true, the rest of a union when false. */
+    protected narrowInstanceof(left: ast.Expression, right: ast.Expression, assumeTrue: boolean): Narrowing;
+    protected narrowableBinding(node: ast.Expression): Binding | undefined;
+    /** An assignment to a variable ends its narrowing. */
+    protected forget(target: ast.Expression): void;
+    protected dropNarrowing(names: ReadonlySet<string>): void;
+}