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

package/src/language/TypeChecker.mjs

@@ -0,0 +1,449 @@
+/**
+ * TypeChecker — every relation between two types: assignability, merging, the types an equality compares, and the receivers a member applies to, read from what declares the types
+ */
+
+import { Type } from './Type.mjs';
+import { NexoModule } from './vocabulary/NexoModule.mjs';
+
+/**
+ * The answers to whether a value of one type is assignable to another: assignable, assignable once its value is checked when it is evaluated, as a value of `Any` is, or refused.
+ * @typedef {'assignable' | 'checked' | 'refused'} Assignability
+ */
+
+export class TypeChecker {
+    /**
+     * The registry that declares the types the checker relates, of which it reads these four methods: a value type's declaration, a generic one's variances among it, a reference type's supertype, whether a type is a
+     * reference type, and a member's receiver types.
+     * @type {{ getTypeDeclaration(type: Type): { kind: string, variances?: readonly ('covariant' | 'invariant')[] } | undefined, getSupertype(type: Type): Type | null, isReferenceType(type: Type): boolean, getReceiverTypes(declaration: object): Type[] }}
+     */
+    #registry;
+
+    /** @param {object} registry The registry that declares the types the checker relates. */
+    constructor(registry) {
+        this.#registry = registry;
+    }
+
+    /**
+     * Whether a value of the type is assignable to the declared type: `assignable`, `refused`, or `checked`, assignable once its value is checked against the declared
+     * type when it is evaluated, which a value of `Any` asks for, the check refusing null where the declared type isn't nullable.
+     * @param {Type} type
+     * @param {Type} declaredType
+     * @returns {Assignability}
+     */
+    assignabilityOf(type, declaredType) {
+        if (type.kind === 'never') {
+            return 'assignable';
+        }
+
+        if (type.kind === 'null') {
+            return declaredType.isNullable ? 'assignable' : 'refused';
+        }
+
+        // A value of `Any` waits for its value, whatever is declared but `Any` itself, whose nullability the value's must fit; no value is a never, and only a nullable one is null.
+        if (type.kind === 'any') {
+            if (declaredType.kind === 'never' || (declaredType.kind === 'null' && !type.isNullable)) {
+                return 'refused';
+            }
+
+            return declaredType.kind === 'any' && (declaredType.isNullable || !type.isNullable) ? 'assignable' : 'checked';
+        }
+
+        if (type.isNullable && !declaredType.isNullable) {
+            return 'refused';
+        }
+
+        if (declaredType.kind === 'any') {
+            return 'assignable';
+        }
+
+        if (type.kind !== declaredType.kind) {
+            return 'refused';
+        }
+
+        switch (type.kind) {
+            case 'named':
+                return this.#isSameOrSupertypeByName(declaredType, type) ? this.#getTypeArgumentsAssignability(type, declaredType) : 'refused';
+            case 'object':
+                return TypeChecker.#holdsFieldsOf(type, declaredType) ? TypeChecker.#combineAssignabilities([...type.fieldTypes].map(([name, fieldType]) => this.assignabilityOf(fieldType, declaredType.fieldTypes.get(name)))) : 'refused';
+            // An object root stands where one of its object expression reads the fields it does, and a function reference where one that may be any of its functions does.
+            case 'objectRoot':
+                return type.toNonNullable().equals(declaredType.toNonNullable()) ? 'assignable' : 'refused';
+            case 'function':
+                return type.functions.every(candidate => declaredType.functions.includes(candidate)) ? 'assignable' : 'refused';
+            default:
+                return type.name === declaredType.name ? 'assignable' : 'refused';
+        }
+    }
+
+    /** Whether a value of the type is proven assignable to the declared type; one that waits for a check is not, so a caller that records no check refuses it. */
+    isAssignable(type, declaredType) {
+        return this.assignabilityOf(type, declaredType) === 'assignable';
+    }
+
+    /**
+     * The least type holding a value of either type, nullable where either can be null; null where the two don't merge.
+     * @param {Type} firstType
+     * @param {Type} secondType
+     * @returns {Type | null}
+     */
+    merge(firstType, secondType) {
+        if (firstType.kind === 'never') {
+            return secondType;
+        }
+
+        if (secondType.kind === 'never') {
+            return firstType;
+        }
+
+        if (firstType.kind === 'null') {
+            return secondType.toNullable();
+        }
+
+        if (secondType.kind === 'null') {
+            return firstType.toNullable();
+        }
+
+        const isNullable = firstType.isNullable || secondType.isNullable;
+
+        // Object roots merge where they identify one object expression and read the same fields, and with nothing else, `Any` included, which holds values alone.
+        if (firstType.kind === 'objectRoot' || secondType.kind === 'objectRoot') {
+            return firstType.toNonNullable().equals(secondType.toNonNullable()) ? (isNullable ? firstType.toNullable() : firstType.toNonNullable()) : null;
+        }
+
+        // Function types merge into one that may be any of their functions, and with nothing else, `Any` included.
+        if (firstType.kind === 'function' || secondType.kind === 'function') {
+            return firstType.kind === secondType.kind ? Type.createFunctionType([...firstType.functions, ...secondType.functions], isNullable) : null;
+        }
+
+        // `Any` holds a value of any type.
+        if (firstType.kind === 'any' || secondType.kind === 'any') {
+            return isNullable ? Type.any.toNullable() : Type.any;
+        }
+
+        // Two reference types of one hierarchy merge to the nearest supertype they share, and of two hierarchies to none.
+        if (firstType.kind === 'named' && secondType.kind === 'named' && firstType.identity !== secondType.identity && this.#registry.isReferenceType(firstType) && this.#registry.isReferenceType(secondType)) {
+            const shared = this.#lineageOf(firstType).find(ancestor => this.#lineageOf(secondType).some(other => other.identity === ancestor.identity));
+
+            return shared === undefined ? null : isNullable ? shared.toNullable() : shared.toNonNullable();
+        }
+
+        if (firstType.kind !== secondType.kind || firstType.name !== secondType.name || firstType.moduleName !== secondType.moduleName) {
+            return null;
+        }
+
+        if (firstType.kind === 'object') {
+            if (!TypeChecker.#holdsFieldsOf(firstType, secondType)) {
+                return null;
+            }
+
+            const fieldTypes = new Map();
+
+            for (const [name, fieldType] of firstType.fieldTypes) {
+                const merged = this.merge(fieldType, secondType.fieldTypes.get(name));
+
+                if (merged === null) {
+                    return null;
+                }
+
+                fieldTypes.set(name, merged);
+            }
+
+            return Type.createObjectType(fieldTypes, isNullable);
+        }
+
+        if (firstType.typeArguments.length > 0) {
+            const typeArguments = this.#mergeTypeArguments(firstType, secondType);
+
+            return typeArguments === null ? null : new Type(firstType.kind, { name: firstType.name, moduleName: firstType.moduleName, typeArguments, isNullable });
+        }
+
+        return isNullable ? firstType.toNullable() : firstType.toNonNullable();
+    }
+
+    /** Whether two values an equality compares are of types that fit one way or the other, each proven assignable to the other's. */
+    fitsEitherWay(firstType, secondType) {
+        return this.isAssignable(firstType, secondType) || this.isAssignable(secondType, firstType);
+    }
+
+    /** Whether values of the type are compared with each other by an equality, rather than with null alone: strings, numbers and Booleans by their values, and references by their identity. */
+    isComparable(type) {
+        return type.kind === 'named' && ((type.moduleName === null && NexoModule.scalarTypeNames.includes(type.name)) || this.#registry.isReferenceType(type));
+    }
+
+    /** Whether the member applies to the receiver, by one of its receiver types, as inferring its receiver's type arguments succeeds; it records nothing. */
+    matchesReceiver(declaration, receiverType) {
+        return this.inferReceiverTypeArguments(declaration, receiverType) !== null;
+    }
+
+    /**
+     * The member's receiver type where the receiver applies to it by that type: a type, or a type parameter alone, which takes a receiver of any type a value has; undefined where it does not apply, a module member's
+     * among them, which takes no receiver.
+     * @returns {Type | undefined}
+     */
+    resolveApplyingReceiverType(declaration, receiverType) {
+        const base = receiverType.toNonNullable();
+        const isValue = base.kind === 'named' || base.kind === 'object';
+
+        return this.#registry.getReceiverTypes(declaration).find(type => (type.kind !== 'typeParameter' || isValue) && this.matchesType(type, base));
+    }
+
+    /**
+     * The arguments of the type parameters the member's receiver type binds for the receiver: an empty map where it binds none, or null where the member does not apply to the receiver.
+     * @returns {Map<string, Type> | null}
+     */
+    inferReceiverTypeArguments(declaration, receiverType) {
+        const type = this.resolveApplyingReceiverType(declaration, receiverType);
+
+        return type === undefined ? null : this.inferTypeArguments(type, receiverType.toNonNullable());
+    }
+
+    /**
+     * The applicable declaration of those given whose receiver type is more specific than every other applicable declaration's, alone, as `Light` is than `Device` and `List<Light>` than `List<Device>`, a type parameter
+     * that takes a receiver of any type the least specific: a type's member hides one of its name its supertype declares. Where no declaration is, it answers the competing ones, each applicable and none less specific than another, which make the access ambiguous;
+     * none where none applies.
+     */
+    mostSpecificOf(declarations, receiverType) {
+        const applying = declarations.map(declaration => ({ declaration, type: this.resolveApplyingReceiverType(declaration, receiverType) })).filter(({ type }) => type !== undefined);
+        const selected = applying.find(candidate => applying.every(other => other === candidate || this.#isMoreSpecific(candidate.type, other.type)));
+
+        if (selected !== undefined) {
+            return [selected.declaration];
+        }
+
+        return applying.filter(({ type }) => !applying.some(other => this.#isMoreSpecific(other.type, type))).map(({ declaration }) => declaration);
+    }
+
+    /** Whether the one receiver type is more specific than the other: assignable to it by the type relationships, the other matching it and not it the other, so a type parameter, which matches every type, is the least specific. */
+    #isMoreSpecific(one, other) {
+        return this.matchesType(other, one) && !this.matchesType(one, other);
+    }
+
+    /** Whether the actual type matches the declared one, structure for structure, as inferring the declared type's parameters from it succeeds; it records nothing. */
+    matchesType(declaredType, actualType) {
+        return this.inferTypeArguments(declaredType, actualType) !== null;
+    }
+
+    /**
+     * The arguments of the type parameters the declared type writes, inferred from the actual type, structure for structure, beside those bound already: an empty map where it writes none, or null where the actual type does not
+     * match. A type parameter matches any type the first time it is met, and binds to it; met again, or bound already, it matches the type it binds to, nullability aside where it stands alone, its caller's to apply.
+     * Within a type argument a type that can be null matches only a declared one that can be, as a `List<Number?>` matches no `List<Number>`, and a parameter met again there matches its binding null and all, so a
+     * `Pair<T, T>` matches no `Pair<Number, Number?>`; the actual type's own null is its caller's, which a receiver's `?.` handles.
+     * @param {Type} declaredType
+     * @param {Type} actualType
+     * @param {ReadonlyMap<string, Type>} [bound] The arguments bound already, by parameter name, which it never changes.
+     * @returns {Map<string, Type> | null}
+     */
+    inferTypeArguments(declaredType, actualType, bound = new Map()) {
+        const typeArguments = new Map(bound);
+
+        return this.#inferInto(declaredType, actualType, typeArguments) ? typeArguments : null;
+    }
+
+    /**
+     * Adds to the evidence the actual type gives each type parameter the declared type writes, by exact extraction, structure for structure: a parameter written `T` is given the type as it is, and one written `T?` the
+     * type without null; a null is evidence that its occurrence accepts null, kept with whether that occurrence is written `T?`, and a never, the item of an empty list, is evidence of no type. A part of the actual type
+     * whose structure the declared one doesn't share gives nothing, since checking the argument against its binding refuses it apart.
+     * @param {Type} declaredType
+     * @param {Type} actualType
+     * @param {Map<string, ({ kind: 'type', type: Type } | { kind: 'null', isNullableOccurrence: boolean } | { kind: 'never' })[]>} evidence The evidence by parameter name, which it adds to.
+     */
+    extractTypeArgumentEvidence(declaredType, actualType, evidence) {
+        const add = entry => evidence.set(declaredType.name, [...(evidence.get(declaredType.name) ?? []), entry]);
+
+        if (declaredType.kind === 'typeParameter') {
+            if (declaredType.name === '@selected') {
+                return;
+            }
+
+            if (actualType.kind === 'never') {
+                add({ kind: 'never' });
+            } else if (actualType.kind === 'null') {
+                add({ kind: 'null', isNullableOccurrence: declaredType.isNullable });
+            } else {
+                add({ kind: 'type', type: declaredType.isNullable ? actualType.toNonNullable() : actualType });
+            }
+
+            return;
+        }
+
+        if (declaredType.kind === 'object' && actualType.kind === 'object') {
+            for (const [name, fieldType] of declaredType.fieldTypes) {
+                const actualField = actualType.getObjectFieldType(name);
+
+                if (actualField !== null) {
+                    this.extractTypeArgumentEvidence(fieldType, actualField, evidence);
+                }
+            }
+
+            return;
+        }
+
+        if (declaredType.kind === 'named' && actualType.kind === 'named' && declaredType.identity === actualType.identity && declaredType.typeArguments.length === actualType.typeArguments.length) {
+            declaredType.typeArguments.forEach((typeArgument, index) => this.extractTypeArgumentEvidence(typeArgument, actualType.typeArguments[index], evidence));
+        }
+    }
+
+    /**
+     * The type a type parameter binds to from the evidence its sources gave it: the one type its candidates are, made nullable where one is nullable or an occurrence written `T` was given null, so a `Device` and a
+     * `Device?` give `Device?`; `null` where an occurrence written `T` was given null alone; and `Never` where it was given only nevers, or only nulls at occurrences written `T?`, so that `T?` is `null`. It answers the
+     * candidates where they are of different types, which no binding reconciles, whichever came first, and null where there is no evidence.
+     * @returns {{ type: Type } | { candidates: Type[] } | null}
+     */
+    resolveTypeArgument(evidence) {
+        const types = evidence.filter(entry => entry.kind === 'type').map(entry => entry.type);
+        const acceptsNull = evidence.some(entry => entry.kind === 'null' && !entry.isNullableOccurrence);
+
+        if (types.length > 0) {
+            const base = types[0].toNonNullable();
+
+            if (types.some(type => !type.toNonNullable().equals(base))) {
+                return { candidates: types.filter((type, index) => types.findIndex(other => other.equals(type)) === index) };
+            }
+
+            return { type: acceptsNull || types.some(type => type.isNullable) ? base.toNullable() : base };
+        }
+
+        if (acceptsNull) {
+            return { type: Type.null };
+        }
+
+        return evidence.length > 0 ? { type: Type.never } : null;
+    }
+
+    /**
+     * Matches the actual type against the declared one, adding each argument it binds to the map: the one relation matching and inferring share. Binding is exact: a parameter written `T` binds the type as it is, and one
+     * written `T?` the type without null, since the `?` it is written with gives it that.
+     */
+    #inferInto(declaredType, actualType, typeArguments, isNested = false) {
+        if (declaredType.kind === 'typeParameter') {
+            const typeArgument = typeArguments.get(declaredType.name);
+
+            if (typeArgument === undefined) {
+                typeArguments.set(declaredType.name, declaredType.isNullable ? actualType.toNonNullable() : actualType);
+
+                return true;
+            }
+
+            // Within a type argument a parameter written alone holds what it bound, null and all; one written nullable, or one standing alone, takes its argument with null or without.
+            return isNested && !declaredType.isNullable ? typeArgument.equals(actualType) : typeArgument.toNonNullable().equals(actualType.toNonNullable());
+        }
+
+        // No value is a never, so a never matches whatever is declared, and binds to a never each type parameter written there that nothing bound yet, as `[].flatten` binds T.
+        if (actualType.kind === 'never') {
+            TypeChecker.#bindToNever(declaredType, typeArguments);
+
+            return true;
+        }
+
+        if (declaredType.kind !== actualType.kind || !this.#isSameOrSupertypeByName(declaredType, actualType)) {
+            return false;
+        }
+
+        return declaredType.typeArguments.length === actualType.typeArguments.length && declaredType.typeArguments.every((typeArgument, index) => {
+            const actualArgument = actualType.typeArguments[index];
+
+            // A type argument that can be null fits only one declared nullable, or a type parameter, which binds the null with it.
+            if (actualArgument.isNullable && !typeArgument.isNullable && typeArgument.kind !== 'typeParameter') {
+                return false;
+            }
+
+            return this.#inferInto(typeArgument, actualArgument, typeArguments, true);
+        });
+    }
+
+    /** Binds to a never each type parameter the declared type writes, at any depth, that nothing bound yet. */
+    static #bindToNever(declaredType, typeArguments) {
+        if (declaredType.kind === 'typeParameter') {
+            if (!typeArguments.has(declaredType.name)) {
+                typeArguments.set(declaredType.name, Type.never);
+            }
+
+            return;
+        }
+
+        declaredType.typeArguments.forEach(typeArgument => TypeChecker.#bindToNever(typeArgument, typeArguments));
+    }
+
+    /**
+     * Whether the declared type is the actual type or one of its supertypes by name: the same named type, by its module-qualified identity, or a named type the actual type's declared supertype chain reaches. A local name that
+     * matches alone never makes two types compatible, and their type arguments are checked apart.
+     */
+    #isSameOrSupertypeByName(declaredType, actualType) {
+        if (declaredType.name === actualType.name && declaredType.moduleName === actualType.moduleName) {
+            return true;
+        }
+
+        return declaredType.kind === 'named' && actualType.kind === 'named' && this.#lineageOf(actualType).some(ancestor => ancestor.identity === declaredType.identity);
+    }
+
+    /** The reference type and each supertype above it, nearest first, each without null; the type alone for any other type. */
+    #lineageOf(type) {
+        const lineage = [];
+
+        for (let current = type.toNonNullable(); current !== null; current = this.#registry.getSupertype(current)) {
+            lineage.push(current.toNonNullable());
+        }
+
+        return lineage;
+    }
+
+    /**
+     * Gets the assignability of two types of one generic declaration, or of none, argument by argument, a covariant one by assignability and an invariant one by equality: refused where an argument is refused, checked where one
+     * waits for its value, and assignable where every one is. An invariant argument of a never fits any, since the one invariant parameter, a dictionary's key, is a never only for a dictionary of no entries.
+     */
+    #getTypeArgumentsAssignability(type, declaredType) {
+        if (type.typeArguments.length === 0) {
+            return 'assignable';
+        }
+
+        const { variances } = this.#registry.getTypeDeclaration(declaredType);
+
+        return TypeChecker.#combineAssignabilities(type.typeArguments.map((typeArgument, index) => {
+            const declaredArgument = declaredType.typeArguments[index];
+
+            if (variances[index] === 'covariant') {
+                return this.assignabilityOf(typeArgument, declaredArgument);
+            }
+
+            return typeArgument.kind === 'never' || typeArgument.equals(declaredArgument) ? 'assignable' : 'refused';
+        }));
+    }
+
+    /** The invariant argument two arguments merge to: the one where they are equal, the other where one is a never, and none otherwise. */
+    static #mergeInvariant(one, other) {
+        if (one.kind === 'never') {
+            return other;
+        }
+
+        return other.kind === 'never' || one.equals(other) ? one : null;
+    }
+
+    /** The type arguments two types of one generic declaration merge to, each a covariant one's merge and an invariant one's where they are equal or one is a never, the other; null where one doesn't merge. */
+    #mergeTypeArguments(firstType, secondType) {
+        const { variances } = this.#registry.getTypeDeclaration(firstType);
+        const typeArguments = [];
+
+        for (const [index, typeArgument] of firstType.typeArguments.entries()) {
+            const other = secondType.typeArguments[index];
+            const merged = variances[index] === 'covariant' ? this.merge(typeArgument, other) : TypeChecker.#mergeInvariant(typeArgument, other);
+
+            if (merged === null) {
+                return null;
+            }
+
+            typeArguments.push(merged);
+        }
+
+        return typeArguments;
+    }
+
+    /** Whether two object types hold the same field names, none more and none fewer. */
+    static #holdsFieldsOf(type, otherType) {
+        return type.fieldTypes.size === otherType.fieldTypes.size && [...type.fieldTypes.keys()].every(name => otherType.fieldTypes.has(name));
+    }
+
+    /** Combines the assignability its parts answer into a type's own, by precedence: refused where one is, then checked where one waits for evaluation, and assignable where every one is. */
+    static #combineAssignabilities(answers) {
+        return answers.includes('refused') ? 'refused' : answers.includes('checked') ? 'checked' : 'assignable';
+    }
+}