rooklang 0.0.0-stage → 0.3.0

package/dist/build.d.ts

@@ -0,0 +1,48 @@
+import type { Diagnostic } from './diagnostics.ts';
+import { SourceFile } from './source.ts';
+export interface BuildOptions {
+    /** Write the `.js` files here, keeping the folder structure; by default they go next to the sources. */
+    outDir?: string;
+    /** Check types before generating code. Defaults to `true`. */
+    typeCheck?: boolean;
+    /** Write a `.d.ts` next to each `.js`, for TypeScript code. Defaults to `typeCheck`. */
+    declarations?: boolean;
+    /** Markup and components for every file; by default as its package.json says (config.ts). */
+    markup?: boolean;
+}
+export interface BuildOutput {
+    /** Absolute path of the `.rk` file. */
+    source: string;
+    /** Absolute path of its `.js` file. */
+    output: string;
+    code: string;
+    /** Its `.d.ts` file, when declarations are written. */
+    declarations?: {
+        output: string;
+        code: string;
+    };
+    /** Its worker module, `.worker.js`, when it has `go`. */
+    worker?: {
+        output: string;
+        code: string;
+    };
+}
+/** The errors or the warnings of a file. */
+export interface BuildError {
+    file: SourceFile;
+    diagnostics: Diagnostic[];
+}
+export interface BuildResult {
+    /** Empty when there are errors: either every file is built or none. */
+    outputs: BuildOutput[];
+    errors: BuildError[];
+    /** Warnings do not stop the build. */
+    warnings: BuildError[];
+}
+/**
+ * Compiles `.rk` files and directories (recursively), together with every `.rk` file they
+ * import, since the generated imports refer to the `.js` files of those modules.
+ */
+export declare function build(entries: readonly string[], options?: BuildOptions): BuildResult;
+/** A path for messages: relative to the current directory when it is inside it. */
+export declare function displayPath(path: string): string;

package/dist/build.js

@@ -0,0 +1,112 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { compile } from "./index.js";
+import { SourceFile } from "./source.js";
+/**
+ * Compiles `.rk` files and directories (recursively), together with every `.rk` file they
+ * import, since the generated imports refer to the `.js` files of those modules.
+ */
+export function build(entries, options = {}) {
+    const directories = entries
+        .map((entry) => resolve(entry))
+        .filter((path) => statSync(path).isDirectory());
+    const queue = entries.flatMap((entry) => {
+        const path = resolve(entry);
+        return directories.includes(path) ? findRookFiles(path) : [path];
+    });
+    const seen = new Set(queue);
+    const typeCheck = options.typeCheck ?? true;
+    const declarations = typeCheck && (options.declarations ?? true);
+    const compiled = [];
+    const errors = [];
+    const warnings = [];
+    for (let i = 0; i < queue.length; i++) {
+        const source = queue[i];
+        const text = readFileSync(source, 'utf8');
+        const result = compile(text, {
+            filename: source,
+            typeCheck,
+            declarations,
+            markup: options.markup,
+        });
+        if (result.warnings.length > 0) {
+            warnings.push({
+                file: new SourceFile(displayPath(source), text),
+                diagnostics: result.warnings,
+            });
+        }
+        if (result.diagnostics.length > 0) {
+            errors.push({
+                file: new SourceFile(displayPath(source), text),
+                diagnostics: result.diagnostics,
+            });
+        }
+        else {
+            compiled.push({
+                source,
+                code: result.code,
+                declarations: result.declarations,
+                worker: result.worker,
+            });
+        }
+        for (const specifier of result.dependencies) {
+            // A missing module is reported by the type checker.
+            const dependency = resolve(dirname(source), specifier);
+            if (dependency.endsWith('.rk') && !seen.has(dependency) && existsSync(dependency)) {
+                seen.add(dependency);
+                queue.push(dependency);
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { outputs: [], errors, warnings };
+    // The output keeps the folder structure below the given directories and all the files.
+    const root = commonDirectory(queue, directories);
+    const outputs = compiled.map(({ source, code, declarations: types, worker }) => {
+        const target = options.outDir ? join(resolve(options.outDir), relative(root, source)) : source;
+        const base = target.replace(/\.rk$/, '');
+        return {
+            source,
+            output: `${base}.js`,
+            code,
+            ...(types === undefined ? {} : { declarations: { output: `${base}.d.ts`, code: types } }),
+            ...(worker === undefined ? {} : { worker: { output: `${base}.worker.js`, code: worker } }),
+        };
+    });
+    return { outputs, errors, warnings };
+}
+/** The `.rk` files in a directory and its subdirectories, except `node_modules` and hidden ones. */
+function findRookFiles(directory) {
+    const files = [];
+    const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
+                files.push(...findRookFiles(path));
+            }
+        }
+        else if (entry.name.endsWith('.rk')) {
+            files.push(path);
+        }
+    }
+    return files;
+}
+/** The deepest directory that contains all the files and directories. */
+function commonDirectory(files, directories) {
+    const inside = (path, directory) => path.startsWith(directory + sep);
+    let directory = directories[0] ?? dirname(files[0] ?? process.cwd());
+    while (!files.every((file) => inside(file, directory)) ||
+        !directories.every((other) => other === directory || inside(other, directory))) {
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return directory;
+}
+/** A path for messages: relative to the current directory when it is inside it. */
+export function displayPath(path) {
+    const fromCwd = relative(process.cwd(), path);
+    return fromCwd.startsWith('..') ? path : fromCwd;
+}

package/dist/checker/assignments.d.ts

@@ -0,0 +1,14 @@
+import type * as ast from '../ast.ts';
+import { InitializerChecker } from './initializers.ts';
+import { type Type } from './types.ts';
+export declare abstract class AssignmentChecker extends InitializerChecker {
+    /**
+     * `a, b = f()` or `return f()`: the call must return exactly `count` values. Returns their
+     * types.
+     */
+    protected unpack(value: ast.Expression, count: number, declared: Type | null, context?: 'assignment' | 'return'): Type[];
+    protected checkAssignment(node: ast.AssignmentStatement): void;
+    /** The type a value assigned to `target` must have. */
+    protected checkTarget(target: ast.Expression): Type;
+    protected checkReturn(node: ast.ReturnStatement): void;
+}

package/dist/checker/assignments.js

@@ -0,0 +1,197 @@
+import { isUntyped, countValues, callName, isCall } from "./helpers.js";
+import { InitializerChecker } from "./initializers.js";
+import { BOOL, ANY, isAssignable, isNullable, nonNull, typeToString, UNKNOWN, } from "./types.js";
+// Where values go: assignments to variables, fields and elements, and `return`. Both unpack a call
+// that returns several values.
+export class AssignmentChecker extends InitializerChecker {
+    /**
+     * `a, b = f()` or `return f()`: the call must return exactly `count` values. Returns their
+     * types.
+     */
+    unpack(value, count, declared, context = 'assignment') {
+        const type = this.checkExpression(value, null);
+        if (type.kind === 'unknown')
+            return Array(count).fill(UNKNOWN);
+        // `v, ok = <-ch`: ok is false once the channel is closed and empty.
+        if (count === 2 && value.kind === 'UnaryExpression' && value.operator === '<-') {
+            if (declared)
+                this.expectAssignable(type, declared, value);
+            return declared ? [declared, BOOL] : [type, BOOL];
+        }
+        const returned = type.kind === 'tuple' ? type.types.length : type.kind === 'void' ? 0 : 1;
+        if (type.kind !== 'tuple' || returned !== count) {
+            const prefix = context === 'return'
+                ? `wrong number of return values: expected ${count}, but`
+                : `assignment mismatch: ${count} variables but`;
+            this.error(`${prefix} ${callName(value)} returns ${countValues(returned)}`, value);
+            return Array(count).fill(UNKNOWN);
+        }
+        if (declared) {
+            for (const element of type.types)
+                this.expectAssignable(element, declared, value);
+            return type.types.map(() => declared);
+        }
+        return type.types;
+    }
+    checkAssignment(node) {
+        const { targets, values, operator } = node;
+        if (operator !== '=') {
+            const target = targets[0];
+            const targetType = this.checkTarget(target);
+            const valueType = this.checkValue(values[0], targetType);
+            const result = this.binaryResult(operator.slice(0, -1), targetType, valueType, node);
+            this.expectAssignable(result, targetType, values[0]);
+            this.forget(target);
+            return;
+        }
+        const targetTypes = targets.map((target) => this.checkTarget(target));
+        let valueTypes;
+        if (values.length === targets.length) {
+            valueTypes = values.map((value, i) => {
+                const type = this.checkValue(value, targetTypes[i] ?? null);
+                this.expectAssignable(type, targetTypes[i], value);
+                return type;
+            });
+        }
+        else {
+            valueTypes = this.unpack(values[0], targets.length, null);
+            valueTypes.forEach((type, i) => this.expectAssignable(type, targetTypes[i], values[0]));
+        }
+        targets.forEach((target, i) => {
+            this.forget(target);
+            const binding = this.narrowableBinding(target);
+            const declared = binding?.type;
+            if (binding && declared && isNullable(declared) && !isNullable(valueTypes[i] ?? UNKNOWN)) {
+                this.flow.set(binding, nonNull(declared));
+            }
+        });
+    }
+    /** The type a value assigned to `target` must have. */
+    checkTarget(target) {
+        if (this.checkDecoratorWrite(target))
+            return UNKNOWN;
+        switch (target.kind) {
+            case 'Identifier': {
+                if (target.name === '_')
+                    return ANY;
+                const binding = this.lookupValue(target.name);
+                if (!binding) {
+                    this.error(`"${target.name}" is not defined`, target);
+                    return UNKNOWN;
+                }
+                if (binding.kind === 'const') {
+                    this.error(`cannot assign to "${target.name}": it is a constant`, target);
+                }
+                else if (binding.kind === 'derived') {
+                    this.error(`cannot assign to "${target.name}": it is derived, so change what it is computed from`, target);
+                }
+                else if (binding.kind === 'ref') {
+                    this.error(`cannot assign to "${target.name}": a ref always points to its element`, target);
+                }
+                else if (binding.kind === 'loop') {
+                    this.error(`cannot assign to loop variable "${target.name}"`, target);
+                }
+                else if (binding.kind === 'prop') {
+                    this.error(this.decorator
+                        ? `cannot assign to "${target.name}": parameters of a decorator are read-only`
+                        : `cannot assign to "${target.name}": component properties are read-only; to change the parent's state, pass a function`, target);
+                }
+                else if (binding.kind !== 'let' &&
+                    binding.kind !== 'state' &&
+                    binding.kind !== 'param' &&
+                    binding.kind !== 'catch') {
+                    this.error(`cannot assign to "${target.name}"`, target);
+                }
+                return binding.type ?? UNKNOWN;
+            }
+            case 'MemberExpression': {
+                const object = this.nonNullValue(target.object);
+                const member = this.findMember(object, target.property.name, target.property);
+                if (member === 'any')
+                    return ANY;
+                if (!member)
+                    return UNKNOWN;
+                if (member.method) {
+                    this.error(`cannot assign to method "${target.property.name}"`, target);
+                    return UNKNOWN;
+                }
+                return member.type;
+            }
+            case 'IndexExpression': {
+                const object = this.nonNullValue(target.object);
+                const keyed = this.keyedIndex(object, target.index);
+                if (keyed)
+                    return keyed;
+                this.expectIndex(target.index);
+                if (object.kind === 'array')
+                    return object.element;
+                if (object.kind === 'object' && object.numberIndex)
+                    return object.numberIndex;
+                this.error(object.kind === 'string'
+                    ? 'cannot assign to a character: strings cannot be changed'
+                    : `cannot index ${typeToString(object)}`, target);
+                return UNKNOWN;
+            }
+            default:
+                this.checkValue(target);
+                return UNKNOWN;
+        }
+    }
+    checkReturn(node) {
+        const fn = this.fn;
+        if (!fn)
+            return;
+        const { values } = node;
+        if (fn.isComponent) {
+            // A component may return early; whatever it returns is its markup.
+            const [value] = values;
+            if (value === undefined || values.length > 1) {
+                this.error('a component returns its markup: "return <markup>"', node);
+                return;
+            }
+            const type = this.checkValue(value);
+            if (!isUntyped(type) && !isAssignable(type, this.dom.node)) {
+                this.error(`a component returns markup, not ${typeToString(type)}`, value);
+            }
+            return;
+        }
+        if (fn.results === null) {
+            // Results are inferred: just record what is returned.
+            if (values.length === 1) {
+                const type = this.checkExpression(values[0], null);
+                fn.returns.push(type.kind === 'tuple' ? type.types : type.kind === 'void' ? [] : [type]);
+            }
+            else {
+                fn.returns.push(values.map((value) => this.checkValue(value)));
+            }
+            return;
+        }
+        const expected = fn.results;
+        if (values.length === 0) {
+            if (expected.length > 0) {
+                this.error(`missing return values: expected ${countValues(expected.length)}`, node);
+            }
+            return;
+        }
+        if (expected.length === 0) {
+            this.error('too many return values: this function returns nothing', values[0]);
+            for (const value of values)
+                this.checkExpression(value, null);
+            return;
+        }
+        if (values.length === 1 && expected.length > 1 && isCall(values[0])) {
+            const types = this.unpack(values[0], expected.length, null, 'return');
+            types.forEach((type, i) => this.expectAssignable(type, expected[i], values[0], ' in return'));
+            return;
+        }
+        if (values.length !== expected.length) {
+            this.error(`wrong number of return values: expected ${expected.length}, got ${values.length}`, node);
+        }
+        values.forEach((value, i) => {
+            const target = expected[i];
+            const type = this.checkValue(value, target ?? null);
+            if (target)
+                this.expectAssignable(type, target, value, ' in return');
+        });
+    }
+}

package/dist/checker/base.d.ts

@@ -0,0 +1,124 @@
+import type * as ast from '../ast.ts';
+import type { Diagnostic } from '../diagnostics.ts';
+import { type CheckOptions, type BindingKind, type Binding, type ComponentInfo, type DecoratorInfo, type AliasEntry, Scope, type FunctionContext, type ClassContext, type Flow } from './context.ts';
+import { type ClassInfo, type FunctionType, type Member, type Type, type TypeParam } from './types.ts';
+export declare abstract class CheckerBase {
+    protected abstract checkClassBodies(node: ast.ClassDeclaration, info: ClassInfo): void;
+    protected abstract ensureClassResolved(info: ClassInfo): void;
+    protected abstract resolveClass(node: ast.ClassDeclaration, info: ClassInfo): void;
+    protected abstract inferredType(type: Type, node: ast.Expression): Type;
+    protected abstract resolveAlias(entry: AliasEntry): Type;
+    protected abstract resolveType(node: ast.TypeNode): Type;
+    protected abstract resolveTypeName(name: ast.Identifier, typeArgs?: readonly ast.TypeNode[]): Type;
+    protected abstract checkStatement(node: ast.Statement): void;
+    protected abstract checkFor(node: ast.ForStatement): void;
+    protected abstract checkForIn(node: ast.ForInStatement): void;
+    protected abstract checkIf(node: ast.IfStatement): void;
+    protected abstract checkSwitch(node: ast.SwitchStatement): void;
+    protected abstract checkTry(node: ast.TryStatement): void;
+    protected abstract forget(target: ast.Expression): void;
+    protected abstract narrowableBinding(node: ast.Expression): Binding | undefined;
+    protected abstract checkFunction(params: readonly ast.Parameter[], type: FunctionType, results: Type[] | null, body: ast.BlockStatement | ast.Expression, options?: {
+        isConstructor?: boolean;
+        isComponent?: boolean;
+        closure?: boolean;
+        paramKind?: BindingKind;
+        /** An async function: its body returns what the Promise of `results` gives. */
+        async?: boolean;
+        /** Sees the scope of the body once it is checked. */
+        inspect?: (scope: Scope) => void;
+    }): Type[];
+    protected abstract checkExpression(node: ast.Expression, expected: Type | null): Type;
+    protected abstract checkValue(node: ast.Expression, expected?: Type | null): Type;
+    protected abstract binaryResult(operator: ast.BinaryOperator, givenLeft: Type, givenRight: Type, node: ast.NodeBase): Type;
+    protected abstract checkBinary(node: ast.BinaryExpression, expected: Type | null): Type;
+    protected abstract checkConditional(node: ast.ConditionalExpression, expected: Type | null): Type;
+    protected abstract checkUnary(node: ast.UnaryExpression): Type;
+    protected abstract checkElement(node: ast.ElementExpression): Type;
+    protected abstract checkComponentBody(info: ComponentInfo): void;
+    protected abstract checkDecoratorBody(info: DecoratorInfo): void;
+    protected abstract resolveDecoratorParams(info: DecoratorInfo): void;
+    protected abstract checkDecoratorUses(info: ComponentInfo): void;
+    protected abstract orderByNeeds(decorators: readonly DecoratorInfo[]): DecoratorInfo[];
+    protected abstract wrappedType(info: ComponentInfo, own: Type, seen: Set<ComponentInfo>): Type;
+    protected abstract checkDecoratorMember(node: ast.DecoratorMember): Type;
+    protected abstract checkDecoratorGet(node: ast.DecoratorGet): Type;
+    protected abstract checkDecoratorWrite(target: ast.Expression): boolean;
+    protected abstract checkComponentUse(node: ast.ElementExpression, tag: ast.Identifier): Type;
+    protected abstract checkRefDeclaration(node: ast.VariableDeclaration): void;
+    protected abstract checkStyle(node: ast.StyleStatement): void;
+    protected abstract checkRefAttribute(attribute: ast.JsxAttribute, node: ast.ElementExpression): void;
+    protected abstract resolveProps(info: ComponentInfo): void;
+    protected abstract webComponentProperty(tag: string, attribute: string): Type | null;
+    protected abstract checkProp(attribute: ast.JsxAttribute, type: Type, component: string): void;
+    protected abstract checkChain(node: ast.MemberExpression | ast.IndexExpression | ast.CallExpression, expected?: Type | null): [Type, boolean];
+    protected abstract expectIndex(node: ast.Expression): void;
+    protected abstract findMember(object: Type, name: string, node: ast.NodeBase): Member | 'any' | undefined;
+    protected abstract keyedIndex(object: Type, index: ast.Expression): Type | null;
+    protected abstract nonNullValue(node: ast.Expression): Type;
+    protected abstract checkCall(node: ast.CallExpression, callee: Type, expected?: Type | null): Type;
+    protected abstract checkNew(node: ast.NewExpression, expected?: Type | null): Type;
+    protected abstract checkSuperCall(node: ast.CallExpression): Type;
+    protected readonly program: ast.Program;
+    protected readonly options: CheckOptions;
+    protected readonly diagnostics: Diagnostic[];
+    protected readonly moduleScope: Scope;
+    protected scope: Scope;
+    protected flow: Flow;
+    protected fn: FunctionContext | null;
+    protected cls: ClassContext | null;
+    /**
+     * Type parameters of the call whose arguments are being checked: they are not known yet. Other
+     * type parameters, like `T` in the body of `func first<T any>`, are types like any other.
+     */
+    protected inferring: ReadonlySet<TypeParam>;
+    /** Names assigned somewhere in the module: their narrowing does not carry into closures. */
+    protected readonly assigned: Set<string>;
+    /** Classes whose members are not resolved yet, with the code that resolves them. */
+    protected readonly unresolvedClasses: Map<ClassInfo, () => void>;
+    protected readonly resolvingClasses: Set<ClassInfo>;
+    /** The component whose body is being checked, if any. */
+    protected component: ComponentInfo | null;
+    /** The decorator whose body is being checked, if any. */
+    protected decorator: DecoratorInfo | null;
+    /** Decorators of the module by name; they are not values, so they have a namespace of their own. */
+    protected readonly decorators: Map<string, DecoratorInfo>;
+    /** Decorators imported from other modules: their code uses the names of those. */
+    protected readonly importedDecorators: Set<DecoratorInfo>;
+    protected readonly globals: Scope;
+    protected domTypes: {
+        node: Type;
+        element: Type;
+        fragment: Type;
+    } | null;
+    constructor(program: ast.Program, options: CheckOptions);
+    protected error(message: string, node: ast.NodeBase): void;
+    protected expectAssignable(source: Type, target: Type, node: ast.NodeBase, context?: string): void;
+    protected nullError(node: ast.Expression): void;
+    protected withScope<T>(check: () => T): T;
+    protected withClass<T>(context: ClassContext | null, check: () => T): T;
+    protected lookupValue(name: string): Binding | undefined;
+    protected lookupType(name: string): Type | AliasEntry | undefined;
+    /**
+     * Node, HTMLElement and DocumentFragment: from the library when there is one. Found on first
+     * use, after the imports, which may change the library.
+     */
+    protected get dom(): {
+        node: Type;
+        element: Type;
+        fragment: Type;
+    };
+    /** The `event` of an `on*` attribute: its `currentTarget` is the element. */
+    protected eventOf(attribute: string, element: Type): Type;
+    /** A member of a string, number, bigint or bool that the built-in types do not list. */
+    protected primitiveMember(kind: 'string' | 'number' | 'bigint' | 'bool', name: string): Member | undefined;
+    protected arrayMemberOf(element: Type, name: string): Member | undefined;
+    protected declareValue(id: ast.Identifier, kind: BindingKind, type: Type | null): Binding;
+    protected declareType(id: ast.Identifier, entry: Type | AliasEntry): void;
+    /**
+     * Remembers the types of checked expressions that may narrow a variable, e.g.
+     * `let u ?User = new User()` makes `u` non-null until it is assigned again.
+     */
+    protected readonly checkedTypes: WeakMap<ast.Expression, Type>;
+    protected typeOfChecked(node: ast.Expression): Type;
+}

package/dist/checker/base.js

@@ -0,0 +1,180 @@
+import { assignedNames } from "../names.js";
+import { arrayMember } from "./builtins.js";
+import { Scope, globalScope, } from "./context.js";
+import { DOCUMENT_FRAGMENT, eventType, HTML_ELEMENT, NODE } from "./dom.js";
+import { explainMismatch, isAssignable, LazyMap, memberNames, nonNull, property, typeToString, UNKNOWN, } from "./types.js";
+// The type checker is a chain of layers, one per area, like the code generator: base → imports →
+// declarations → classes → resolution → initializers → assignments → statements → control flow →
+// functions → expressions → operators → markup → forwarding → components → component values →
+// refs → styles → decorator wrappers → decorator exports → decorators → decorator members →
+// members → calls → goroutines → channels → bytes → loops → go for → iterators → completion →
+// Checker (checker.ts). Statements, expressions and markup check each other recursively, so
+// methods of later layers that earlier ones call are declared here as abstract. This layer has the
+// state of a check, diagnostics, scopes and names, and the DOM types.
+export class CheckerBase {
+    program;
+    options;
+    diagnostics = [];
+    moduleScope;
+    scope;
+    flow = new Map();
+    fn = null;
+    cls = null;
+    /**
+     * Type parameters of the call whose arguments are being checked: they are not known yet. Other
+     * type parameters, like `T` in the body of `func first<T any>`, are types like any other.
+     */
+    inferring = new Set();
+    /** Names assigned somewhere in the module: their narrowing does not carry into closures. */
+    assigned;
+    /** Classes whose members are not resolved yet, with the code that resolves them. */
+    unresolvedClasses = new Map();
+    resolvingClasses = new Set();
+    /** The component whose body is being checked, if any. */
+    component = null;
+    /** The decorator whose body is being checked, if any. */
+    decorator = null;
+    /** Decorators of the module by name; they are not values, so they have a namespace of their own. */
+    decorators = new Map();
+    /** Decorators imported from other modules: their code uses the names of those. */
+    importedDecorators = new Set();
+    globals;
+    domTypes = null;
+    constructor(program, options) {
+        this.program = program;
+        this.options = options;
+        this.globals = globalScope(options.library);
+        this.moduleScope = new Scope(this.globals);
+        this.scope = this.moduleScope;
+        this.assigned = assignedNames(program);
+    }
+    error(message, node) {
+        if (this.diagnostics.some((d) => d.start === node.start))
+            return;
+        this.diagnostics.push({ message, start: node.start, end: node.end });
+    }
+    expectAssignable(source, target, node, context = '') {
+        if (isAssignable(source, target))
+            return;
+        let message = `cannot use ${typeToString(source)} as ${typeToString(target)}${context}`;
+        const reason = explainMismatch(nonNull(source), nonNull(target));
+        if (source.kind === 'nullable' && isAssignable(nonNull(source), target)) {
+            message += ': it may be null, check it first';
+        }
+        else if (reason !== null) {
+            message += `: ${reason}`;
+        }
+        this.error(message, node);
+    }
+    nullError(node) {
+        const name = node.kind === 'Identifier' ? node.name : null;
+        this.error(name !== null
+            ? `"${name}" may be null: check it with "if ${name} != null" or use "?."`
+            : 'this value may be null: check it for null or use "?."', node);
+    }
+    withScope(check) {
+        const saved = this.scope;
+        this.scope = new Scope(saved);
+        try {
+            return check();
+        }
+        finally {
+            this.scope = saved;
+        }
+    }
+    withClass(context, check) {
+        const saved = this.cls;
+        this.cls = context;
+        try {
+            return check();
+        }
+        finally {
+            this.cls = saved;
+        }
+    }
+    lookupValue(name) {
+        for (let scope = this.scope; scope; scope = scope.parent) {
+            const binding = scope.values.get(name);
+            if (binding)
+                return binding;
+        }
+        const type = this.options.library?.value(name);
+        if (type === undefined)
+            return undefined;
+        const binding = { name, kind: 'builtin', type };
+        this.globals.values.set(name, binding);
+        return binding;
+    }
+    lookupType(name) {
+        for (let scope = this.scope; scope; scope = scope.parent) {
+            const entry = scope.types.get(name);
+            if (entry)
+                return entry;
+        }
+        const type = this.options.library?.type(name);
+        if (type !== undefined)
+            this.globals.types.set(name, type);
+        return type;
+    }
+    /**
+     * Node, HTMLElement and DocumentFragment: from the library when there is one. Found on first
+     * use, after the imports, which may change the library.
+     */
+    get dom() {
+        if (!this.domTypes) {
+            const { library } = this.options;
+            this.domTypes = {
+                node: library?.type('Node') ?? NODE,
+                element: library?.type('HTMLElement') ?? HTML_ELEMENT,
+                fragment: library?.type('DocumentFragment') ?? DOCUMENT_FRAGMENT,
+            };
+        }
+        return this.domTypes;
+    }
+    /** The `event` of an `on*` attribute: its `currentTarget` is the element. */
+    eventOf(attribute, element) {
+        const { library } = this.options;
+        if (!library)
+            return eventType(element);
+        const event = library.event(attribute.slice(2).toLowerCase()) ?? library.type('Event');
+        if (event?.kind !== 'object')
+            return eventType(element);
+        const members = new LazyMap(() => memberNames(event.members), (name) => (name === 'currentTarget' ? property(element) : event.members.get(name)));
+        return { ...event, members };
+    }
+    /** A member of a string, number, bigint or bool that the built-in types do not list. */
+    primitiveMember(kind, name) {
+        const type = this.options.library?.primitive(kind);
+        return type?.kind === 'object' ? type.members.get(name) : undefined;
+    }
+    arrayMemberOf(element, name) {
+        const builtin = arrayMember(element, name);
+        if (builtin)
+            return builtin;
+        const type = this.options.library?.array(element);
+        return type?.kind === 'object' ? type.members.get(name) : undefined;
+    }
+    declareValue(id, kind, type) {
+        const binding = { name: id.name, kind, type };
+        if (id.name === '_')
+            return binding;
+        if (this.scope.values.has(id.name)) {
+            this.error(`"${id.name}" is already declared in this scope`, id);
+        }
+        this.scope.values.set(id.name, binding);
+        return binding;
+    }
+    declareType(id, entry) {
+        if (this.scope.types.has(id.name))
+            this.error(`type "${id.name}" is already declared`, id);
+        this.scope.types.set(id.name, entry);
+    }
+    /**
+     * Remembers the types of checked expressions that may narrow a variable, e.g.
+     * `let u ?User = new User()` makes `u` non-null until it is assigned again.
+     */
+    checkedTypes = new WeakMap();
+    typeOfChecked(node) {
+        return this.checkedTypes.get(node) ?? UNKNOWN;
+    }
+}