kopscript 0.2.0 → 0.4.0

package/dist/checker.js

@@ -18,6 +18,12 @@ class Scope {
     constructor(parent = null) {
         this.parent = parent;
         this.vars = new Map();
+        // Names known non-null *in this scope specifically* — an overlay checked
+        // independently of where a name was actually declared (which can be many
+        // scopes up), set only on the narrow child scope an `if (x != null)`
+        // branch (or `&&`/`||` short-circuit) is checked in. See
+        // Checker.detectNullCheck/narrowedChild.
+        this.narrowed = new Set();
     }
     declare(name, type, isConst) {
         this.vars.set(name, { type, isConst });
@@ -25,11 +31,20 @@ class Scope {
     resolve(name) {
         return this.vars.get(name) ?? this.parent?.resolve(name) ?? null;
     }
+    narrowNonNull(name) {
+        this.narrowed.add(name);
+    }
+    isNarrowedNonNull(name) {
+        return this.narrowed.has(name) || (this.parent?.isNarrowedNonNull(name) ?? false);
+    }
     child() {
         return new Scope(this);
     }
 }
 export class Checker {
+    recordHover(line, col, text) {
+        this.hoverEntries.push({ line, col, text });
+    }
     constructor(program, diagnostics, imports = emptyModuleExports(), currentFilePath = "test.ks") {
         this.program = program;
         this.diagnostics = diagnostics;
@@ -41,18 +56,31 @@ export class Checker {
         this.functions = new Map();
         this.externValues = new Map();
         this.namedTypes = new Map();
+        // className/interfaceName -> its type parameter's name (e.g. "Box" -> "T"),
+        // for every generic class/interface — populated up front, before any type
+        // resolution runs, specifically so a forward reference (class A's field
+        // referencing generic class B, declared later in the same file) still
+        // resolves B's genericity correctly. See resolveType/validateGenericArity.
+        this.genericTypeParams = new Map();
         this.importedNames = new Set();
         this.rawContents = new Map();
+        this.hoverEntries = [];
     }
     check() {
         for (const [name, kind] of this.imports.namedTypes) {
             this.namedTypes.set(name, kind);
             this.importedNames.add(name);
         }
-        for (const [name, info] of this.imports.classes)
+        for (const [name, info] of this.imports.classes) {
             this.classes.set(name, info);
-        for (const [name, info] of this.imports.interfaces)
+            if (info.typeParam)
+                this.genericTypeParams.set(name, info.typeParam);
+        }
+        for (const [name, info] of this.imports.interfaces) {
             this.interfaces.set(name, info);
+            if (info.typeParam)
+                this.genericTypeParams.set(name, info.typeParam);
+        }
         for (const [name, info] of this.imports.enums)
             this.enums.set(name, info);
         for (const [name, info] of this.imports.functions) {
@@ -80,6 +108,12 @@ export class Checker {
             this.namedTypes.set(e.name, "enum");
         for (const c of externClassDecls)
             this.namedTypes.set(c.name, "class");
+        for (const c of classDecls)
+            if (c.typeParam)
+                this.genericTypeParams.set(c.name, c.typeParam);
+        for (const i of interfaceDecls)
+            if (i.typeParam)
+                this.genericTypeParams.set(i.name, i.typeParam);
         for (const e of enumDecls)
             this.registerEnum(e);
         for (const i of interfaceDecls)
@@ -156,6 +190,7 @@ export class Checker {
         const ownCtorParams = decl.hasConstructor ? decl.ctorParams.map((p) => this.resolveType(p.type, decl.line, decl.col)) : null;
         this.classes.set(decl.name, {
             name: decl.name,
+            typeParam: null,
             superclass: null,
             interfaces: [],
             fields,
@@ -291,14 +326,116 @@ export class Checker {
     }
     // ---------- registration ----------
     resolveType(node, line, col) {
-        const resolved = T.resolveTypeNode(node, this.namedTypes);
+        const resolved = T.resolveTypeNode(node, this.namedTypes, (namedNode, type) => {
+            this.recordHover(namedNode.line, namedNode.col, T.typeToString(type));
+        });
         if (!resolved) {
             const name = node.kind === "NamedType" ? node.name : "[]";
-            this.diagnostics.error(`Unknown type '${name}'`, line, col);
+            if (name !== "[]" && this.genericTypeParams.has(name) && !node.typeArgs) {
+                this.diagnostics.error(`Generic type '${name}' requires a type argument (e.g. '${name}<T>')`, line, col);
+            }
+            else {
+                this.diagnostics.error(`Unknown type '${name}'`, line, col);
+            }
             return T.UNKNOWN;
         }
+        this.validateGenericArity(resolved, line, col);
         return resolved;
     }
+    // resolveTypeNode mechanically attaches whatever type argument a
+    // NamedType node happened to carry, without knowing which names are
+    // actually declared generic (that's checker state, not something the
+    // pure type-resolution function has access to) — this is the other half:
+    // walking the successfully-resolved type looking for a class/interface
+    // whose generic-ness doesn't match whether it got a type argument.
+    validateGenericArity(type, line, col) {
+        switch (type.kind) {
+            case "array":
+                this.validateGenericArity(type.element, line, col);
+                return;
+            case "function":
+                type.params.forEach((p) => this.validateGenericArity(p, line, col));
+                this.validateGenericArity(type.returnType, line, col);
+                return;
+            case "task":
+                this.validateGenericArity(type.resultType, line, col);
+                return;
+            case "state":
+                this.validateGenericArity(type.valueType, line, col);
+                return;
+            case "nullable":
+                this.validateGenericArity(type.inner, line, col);
+                return;
+            case "class":
+            case "interface": {
+                const isGeneric = this.genericTypeParams.has(type.name);
+                if (isGeneric && !type.typeArg) {
+                    this.diagnostics.error(`Generic type '${type.name}' requires a type argument (e.g. '${type.name}<T>')`, line, col);
+                }
+                else if (!isGeneric && type.typeArg) {
+                    this.diagnostics.error(`Type '${type.name}' is not generic — it doesn't take a type argument`, line, col);
+                }
+                if (type.typeArg)
+                    this.validateGenericArity(type.typeArg, line, col);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    // Temporarily makes `name` (a class/interface's own type parameter, e.g.
+    // "T") resolve as a TypeParamType, for the duration of `fn` — used only
+    // while registering that class/interface's own declaration (fields,
+    // methods, ctor params), so `T Value;` resolves correctly. Scoped this
+    // narrowly (set, run, delete/restore) rather than left in `namedTypes`
+    // permanently, since it's only ever meaningful inside that one
+    // declaration's own body.
+    withTypeParamInScope(typeParam, fn) {
+        if (!typeParam)
+            return fn();
+        const previous = this.namedTypes.get(typeParam);
+        this.namedTypes.set(typeParam, "typeParam");
+        try {
+            return fn();
+        }
+        finally {
+            if (previous === undefined)
+                this.namedTypes.delete(typeParam);
+            else
+                this.namedTypes.set(typeParam, previous);
+        }
+    }
+    // Replaces every occurrence of the class/interface's own type parameter
+    // (by name) inside `type` with `arg` — the substitution step that turns
+    // Box<T>'s abstractly-stored field type `T` into `number` when someone
+    // actually asks about `Box<number>.Value`. A type with no occurrence of
+    // `paramName` anywhere in it is returned unchanged (including every
+    // non-generic type, the overwhelming majority).
+    substituteTypeParam(type, paramName, arg) {
+        switch (type.kind) {
+            case "typeParam":
+                return type.name === paramName ? arg : type;
+            case "array":
+                return T.arrayOf(this.substituteTypeParam(type.element, paramName, arg));
+            case "nullable":
+                return T.nullableOf(this.substituteTypeParam(type.inner, paramName, arg));
+            case "task":
+                return T.taskType(this.substituteTypeParam(type.resultType, paramName, arg));
+            case "state":
+                return T.stateType(this.substituteTypeParam(type.valueType, paramName, arg));
+            case "function":
+                return T.functionType(type.params.map((p) => this.substituteTypeParam(p, paramName, arg)), this.substituteTypeParam(type.returnType, paramName, arg));
+            // A nested generic's own type argument can itself mention the outer
+            // T (`Box<T[]>`'s field being List<T> — a v1 corner case, but cheap
+            // to handle correctly): substitute inside it too.
+            case "class":
+                return type.typeArg ? T.classType(type.name, this.substituteTypeParam(type.typeArg, paramName, arg)) : type;
+            case "interface":
+                return type.typeArg ? T.interfaceType(type.name, this.substituteTypeParam(type.typeArg, paramName, arg)) : type;
+            default:
+                return type;
+        }
+    }
     registerEnum(decl) {
         const members = new Map();
         decl.members.forEach((name, index) => {
@@ -309,12 +446,14 @@ export class Checker {
             members.set(name, index);
         });
         this.enums.set(decl.name, { name: decl.name, members });
+        this.recordHover(decl.line, decl.col, `enum ${decl.name}`);
     }
     registerInterface(decl) {
-        const methods = decl.methods.map((m) => ({
-            name: m.name,
-            params: m.params.map((p) => this.resolveType(p.type, m.line, m.col)),
-            returnType: this.resolveType(m.returnType, m.line, m.col),
+        const methods = this.withTypeParamInScope(decl.typeParam, () => decl.methods.map((m) => {
+            const params = m.params.map((p) => this.resolveType(p.type, m.line, m.col));
+            const returnType = this.resolveType(m.returnType, m.line, m.col);
+            this.recordHover(m.nameLine, m.nameCol, `${m.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
+            return { name: m.name, params, returnType };
         }));
         const bases = [];
         for (const baseName of decl.baseList) {
@@ -322,9 +461,17 @@ export class Checker {
                 this.diagnostics.error(`Interface '${decl.name}' can only extend other interfaces (unknown interface '${baseName}')`, decl.line, decl.col);
                 continue;
             }
+            // v1 generics can't appear in a base list at all — only as a
+            // standalone type (field/param/return/local, `new Box<T>()`). A
+            // class/interface always implements/extends a *bare* name.
+            if (this.genericTypeParams.has(baseName)) {
+                this.diagnostics.error(`Interface '${decl.name}' cannot extend generic interface '${baseName}' — not supported in v1`, decl.line, decl.col);
+                continue;
+            }
             bases.push(baseName);
         }
-        this.interfaces.set(decl.name, { name: decl.name, bases, methods });
+        this.interfaces.set(decl.name, { name: decl.name, typeParam: decl.typeParam, bases, methods });
+        this.recordHover(decl.line, decl.col, decl.typeParam ? `interface ${decl.name}<${decl.typeParam}>` : `interface ${decl.name}`);
     }
     checkInterfaceHierarchy(decl) {
         const info = this.interfaces.get(decl.name);
@@ -367,33 +514,48 @@ export class Checker {
         return info.bases.some((b) => this.interfaceExtends(b, sup));
     }
     registerClass(decl) {
-        const fields = new Map();
-        const staticFields = new Map();
-        for (const f of decl.fields) {
-            const info = { type: this.resolveType(f.type, f.line, f.col), visibility: f.visibility, hasSetter: true };
-            (f.isStatic ? staticFields : fields).set(f.name, info);
-        }
-        for (const p of decl.properties) {
-            fields.set(p.name, { type: this.resolveType(p.type, p.line, p.col), visibility: p.visibility, hasSetter: p.hasSetter });
-        }
-        const methods = new Map();
-        const staticMethods = new Map();
-        for (const m of decl.methods) {
-            const info = {
-                params: m.params.map((p) => this.resolveType(p.type, m.line, m.col)),
-                returnType: this.resolveType(m.returnType, m.line, m.col),
-                visibility: m.visibility,
-                isVirtual: m.isVirtual,
-                isOverride: m.isOverride,
-            };
-            (m.isStatic ? staticMethods : methods).set(m.name, info);
-        }
-        const ownCtorParams = decl.constructor
-            ? decl.constructor.params.map((p) => this.resolveType(p.type, decl.constructor.line, decl.constructor.col))
-            : null;
+        this.recordHover(decl.line, decl.col, decl.typeParam ? `class ${decl.name}<${decl.typeParam}>` : `class ${decl.name}`);
+        const { fields, staticFields, methods, staticMethods, ownCtorParams } = this.withTypeParamInScope(decl.typeParam, () => {
+            const fields = new Map();
+            const staticFields = new Map();
+            for (const f of decl.fields) {
+                const info = { type: this.resolveType(f.type, f.line, f.col), visibility: f.visibility, hasSetter: true };
+                this.recordHover(f.nameLine, f.nameCol, `${f.name}: ${T.typeToString(info.type)}`);
+                (f.isStatic ? staticFields : fields).set(f.name, info);
+            }
+            for (const p of decl.properties) {
+                const type = this.resolveType(p.type, p.line, p.col);
+                this.recordHover(p.nameLine, p.nameCol, `${p.name}: ${T.typeToString(type)}`);
+                fields.set(p.name, { type, visibility: p.visibility, hasSetter: p.hasSetter });
+            }
+            const methods = new Map();
+            const staticMethods = new Map();
+            for (const m of decl.methods) {
+                const info = {
+                    params: m.params.map((p) => this.resolveType(p.type, m.line, m.col)),
+                    returnType: this.resolveType(m.returnType, m.line, m.col),
+                    visibility: m.visibility,
+                    isVirtual: m.isVirtual,
+                    isOverride: m.isOverride,
+                };
+                this.recordHover(m.nameLine, m.nameCol, `${m.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
+                (m.isStatic ? staticMethods : methods).set(m.name, info);
+            }
+            const ownCtorParams = decl.constructor
+                ? decl.constructor.params.map((p) => this.resolveType(p.type, decl.constructor.line, decl.constructor.col))
+                : null;
+            return { fields, staticFields, methods, staticMethods, ownCtorParams };
+        });
         let superclass = null;
         const interfaces = [];
         for (const baseName of decl.baseList) {
+            // v1 generics can't appear in a base list at all — only as a
+            // standalone type (field/param/return/local, `new Box<T>()`). A
+            // class always extends/implements a *bare* name.
+            if (this.genericTypeParams.has(baseName)) {
+                this.diagnostics.error(`Class '${decl.name}' cannot extend/implement generic type '${baseName}' — not supported in v1`, decl.line, decl.col);
+                continue;
+            }
             const kind = this.namedTypes.get(baseName);
             if (kind === "class") {
                 if (superclass !== null) {
@@ -412,6 +574,7 @@ export class Checker {
         }
         this.classes.set(decl.name, {
             name: decl.name,
+            typeParam: decl.typeParam,
             superclass,
             interfaces,
             fields,
@@ -515,10 +678,10 @@ export class Checker {
         }
     }
     registerFunction(decl) {
-        this.functions.set(decl.name, {
-            params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
-            returnType: this.resolveType(decl.returnType, decl.line, decl.col),
-        });
+        const params = decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col));
+        const returnType = this.resolveType(decl.returnType, decl.line, decl.col);
+        this.functions.set(decl.name, { params, returnType });
+        this.recordHover(decl.line, decl.col, `function ${decl.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
     }
     isSubclass(sub, sup) {
         let current = sub;
@@ -612,7 +775,25 @@ export class Checker {
     isAssignableType(from, to) {
         if (from.kind === "unknown" || to.kind === "unknown")
             return true;
+        // Widening: a non-null T (or another T?) is always fine where T? is
+        // expected. The reverse — a possibly-null value where a non-null type
+        // is expected — is never allowed here; that's exactly what narrowing
+        // (see detectNullCheck) exists to get past by changing `from` itself
+        // at the reference site, not by relaxing this rule.
+        if (to.kind === "nullable") {
+            return from.kind === "nullable" ? this.isAssignableType(from.inner, to.inner) : this.isAssignableType(from, to.inner);
+        }
+        if (from.kind === "nullable")
+            return false;
         if (to.kind === "interface") {
+            // Invariant generics: v1 has no generic inheritance (a class/interface
+            // base list can only name a non-generic type — see registerClass/
+            // registerInterface), so the *only* way `from`'s interface name can
+            // ever match `to`'s is a literal same-interface reference (never a
+            // distinct generic instantiation implementing another) — still worth
+            // checking the type argument actually matches, same as the class case.
+            if (from.kind === "interface" && from.name === to.name)
+                return this.typeArgsMatch(from, to);
             if (from.kind === "class")
                 return this.classImplementsInterface(from.name, to.name);
             if (from.kind === "interface")
@@ -620,13 +801,26 @@ export class Checker {
             return false;
         }
         if (from.kind === "class" && to.kind === "class") {
-            return from.name === to.name || this.isSubclass(from.name, to.name);
+            if (from.name === to.name)
+                return this.typeArgsMatch(from, to);
+            return this.isSubclass(from.name, to.name);
         }
         if (from.kind === "array" && to.kind === "array") {
             return this.isAssignableType(from.element, to.element);
         }
         return T.typesEqual(from, to);
     }
+    // Invariant: Box<number> and Box<string> are unrelated, and so is a
+    // generic type referenced with vs. without its type argument (the latter
+    // only ever arises from an arity error already diagnosed at the
+    // reference site — see validateGenericArity).
+    typeArgsMatch(a, b) {
+        if (!a.typeArg && !b.typeArg)
+            return true;
+        if (!a.typeArg || !b.typeArg)
+            return false;
+        return T.typesEqual(a.typeArg, b.typeArg);
+    }
     // ---------- top-level ----------
     // Validates that `isAsync` and the declared return type agree — `async`
     // requires `task`/`task<T>`, and `task`/`task<T>` requires `async` (there's
@@ -723,6 +917,7 @@ export class Checker {
         switch (stmt.kind) {
             case "VarDecl": {
                 const declaredType = this.resolveType(stmt.type, stmt.line, stmt.col);
+                this.recordHover(stmt.nameLine, stmt.nameCol, `${stmt.isConst ? "const" : "let"} ${stmt.name}: ${T.typeToString(declaredType)}`);
                 const initType = this.checkExpressionExpecting(stmt.init, declaredType, scope, ctx);
                 if (!this.isAssignableType(initType, declaredType)) {
                     this.diagnostics.error(`Cannot assign value of type '${T.typeToString(initType)}' to variable of type '${T.typeToString(declaredType)}'`, stmt.line, stmt.col);
@@ -736,12 +931,19 @@ export class Checker {
             case "IfStatement": {
                 const condType = this.checkExpression(stmt.condition, scope, ctx);
                 this.expectType(condType, T.BOOL, stmt.line, stmt.col, "if condition");
-                this.checkBlock(stmt.thenBranch, scope, ctx);
+                // `if (x != null)` narrows x to non-null in the then-branch;
+                // `if (x == null) ... else ...` narrows it in the else-branch —
+                // see detectNullCheck for exactly what's recognized (bare
+                // identifier vs. `null`, either operand order, `==`/`!=` only).
+                const nullCheck = this.detectNullCheck(stmt.condition);
+                const thenScope = nullCheck?.positiveWhenTrue ? this.narrowedChild(scope, nullCheck.name) : scope;
+                const elseScope = nullCheck && !nullCheck.positiveWhenTrue ? this.narrowedChild(scope, nullCheck.name) : scope;
+                this.checkBlock(stmt.thenBranch, thenScope, ctx);
                 if (stmt.elseBranch) {
                     if (stmt.elseBranch.kind === "IfStatement")
-                        this.checkStatement(stmt.elseBranch, scope, ctx);
+                        this.checkStatement(stmt.elseBranch, elseScope, ctx);
                     else
-                        this.checkBlock(stmt.elseBranch, scope, ctx);
+                        this.checkBlock(stmt.elseBranch, elseScope, ctx);
                 }
                 return;
             }
@@ -844,8 +1046,41 @@ export class Checker {
             this.diagnostics.error(`Expected type '${T.typeToString(expected)}' for ${context}, got '${T.typeToString(actual)}'`, line, col);
         }
     }
+    // Recognizes `name != null` / `name == null` (either operand order) as a
+    // null-check on a bare identifier — the only shape narrowing understands.
+    // `positiveWhenTrue: true` means the condition being true implies `name`
+    // is non-null (`!=`); `false` means the condition being *false* implies
+    // that (`==`). Deliberately narrow: no `this.Field != null`, no `&&`-
+    // chains inside the checked expression itself, no reachability analysis
+    // for an early-return guard clause (`if (x == null) { return; }` doesn't
+    // narrow `x` afterward) — each would need tracking narrowing by path or
+    // by control-flow reachability rather than by scope, real additional
+    // machinery this v1 doesn't take on.
+    detectNullCheck(condition) {
+        if (condition.kind !== "BinaryExpr" || (condition.op !== "==" && condition.op !== "!="))
+            return null;
+        const { left, right } = condition;
+        const ident = left.kind === "Identifier" ? left : right.kind === "Identifier" ? right : null;
+        const other = ident === left ? right : left;
+        if (!ident || other.kind !== "NullLiteral")
+            return null;
+        return { name: ident.name, positiveWhenTrue: condition.op === "!=" };
+    }
+    narrowedChild(scope, name) {
+        const child = scope.child();
+        child.narrowNonNull(name);
+        return child;
+    }
     // ---------- expressions ----------
     checkExpression(expr, scope, ctx) {
+        const type = this.checkExpressionInner(expr, scope, ctx);
+        if (expr.kind === "Identifier")
+            this.recordHover(expr.line, expr.col, `${expr.name}: ${T.typeToString(type)}`);
+        if (expr.kind === "ThisExpr")
+            this.recordHover(expr.line, expr.col, `this: ${T.typeToString(type)}`);
+        return type;
+    }
+    checkExpressionInner(expr, scope, ctx) {
         switch (expr.kind) {
             case "NumberLiteral":
                 return T.NUMBER;
@@ -853,6 +1088,15 @@ export class Checker {
                 return T.STRING;
             case "BoolLiteral":
                 return T.BOOL;
+            // Modeled as UNKNOWN rather than a dedicated Type — typesEqual/
+            // isAssignableType already treat UNKNOWN as compatible with anything,
+            // which is exactly right for a bare `null` with no expected type
+            // (e.g. `x == null`). The real enforcement (null only assignable
+            // where a nullable type is actually expected) lives in
+            // checkExpressionExpecting below, the same place LambdaExpr gets its
+            // expected-type-aware handling.
+            case "NullLiteral":
+                return T.UNKNOWN;
             case "InterpolatedStringLiteral":
                 for (const part of expr.parts) {
                     if (part.kind === "Expr")
@@ -874,8 +1118,16 @@ export class Checker {
             }
             case "Identifier": {
                 const found = scope.resolve(expr.name);
-                if (found)
+                if (found) {
+                    // A nullable local/param narrowed by an enclosing `if (x != null)`
+                    // (or equivalent — see detectNullCheck) type-checks as its
+                    // non-null inner type at this specific reference, without
+                    // changing what's actually declared. Narrowing only applies to
+                    // bare names, not member-access paths like `this.Field`.
+                    if (found.type.kind === "nullable" && scope.isNarrowedNonNull(expr.name))
+                        return found.type.inner;
                     return found.type;
+                }
                 const externValue = this.externValues.get(expr.name);
                 if (externValue)
                     return externValue;
@@ -910,7 +1162,14 @@ export class Checker {
             }
             case "LogicalExpr": {
                 const leftType = this.checkExpression(expr.left, scope, ctx);
-                const rightType = this.checkExpression(expr.right, scope, ctx);
+                // `x != null && x.Foo` narrows x for the right operand (only
+                // reached once the left side is true, i.e. x is non-null); by De
+                // Morgan's, `x == null || x.Foo` narrows it the same way (the
+                // right side only runs once the left is false, i.e. x is non-null).
+                const nullCheck = this.detectNullCheck(expr.left);
+                const narrowRight = nullCheck && ((expr.op === "&&" && nullCheck.positiveWhenTrue) || (expr.op === "||" && !nullCheck.positiveWhenTrue));
+                const rightScope = narrowRight ? this.narrowedChild(scope, nullCheck.name) : scope;
+                const rightType = this.checkExpression(expr.right, rightScope, ctx);
                 this.expectType(leftType, T.BOOL, expr.line, expr.col, `'${expr.op}' operand`);
                 this.expectType(rightType, T.BOOL, expr.line, expr.col, `'${expr.op}' operand`);
                 return T.BOOL;
@@ -988,6 +1247,13 @@ export class Checker {
     checkExpressionExpecting(expr, expected, scope, ctx) {
         if (expr.kind === "LambdaExpr")
             return this.checkLambda(expr, expected, scope, ctx);
+        if (expr.kind === "NullLiteral") {
+            if (expected.kind !== "nullable" && expected.kind !== "unknown") {
+                this.diagnostics.error(`Cannot assign 'null' to non-nullable type '${T.typeToString(expected)}'`, expr.line, expr.col);
+                return T.UNKNOWN;
+            }
+            return expected;
+        }
         return this.checkExpression(expr, scope, ctx);
     }
     checkLambda(expr, expected, scope, ctx) {
@@ -1065,6 +1331,21 @@ export class Checker {
             return T.NUMBER;
         }
         if (op === "==" || op === "!=") {
+            // A literal `null` type-checks as UNKNOWN with no expected type (see
+            // checkExpressionInner), which typesEqual would happily accept
+            // against anything — including a type that can never actually be
+            // null. Checked here, against the AST node itself, specifically so
+            // `nonNullableThing == null` (almost always a leftover from before a
+            // type was made non-nullable, or a copy-pasted guard that can't
+            // trigger) is a compile error instead of a silently-always-false comparison.
+            const nullSide = expr.left.kind === "NullLiteral" ? "left" : expr.right.kind === "NullLiteral" ? "right" : null;
+            if (nullSide) {
+                const otherType = nullSide === "left" ? rightType : leftType;
+                if (otherType.kind !== "nullable" && otherType.kind !== "unknown") {
+                    this.diagnostics.error(`Type '${T.typeToString(otherType)}' can never be null — only a nullable type (e.g. '${T.typeToString(otherType)}?') can be compared to 'null'`, line, col);
+                }
+                return T.BOOL;
+            }
             if (!T.typesEqual(leftType, rightType)) {
                 this.diagnostics.error(`Cannot compare '${T.typeToString(leftType)}' with '${T.typeToString(rightType)}'`, line, col);
             }
@@ -1091,6 +1372,7 @@ export class Checker {
                 expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
                 return T.UNKNOWN;
             }
+            this.recordHover(expr.callee.line, expr.callee.col, `function ${expr.callee.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
             this.checkArgs(expr, info.params, scope, ctx);
             return info.returnType;
         }
@@ -1101,6 +1383,7 @@ export class Checker {
             if (expr.callee.property === "Map") {
                 const objectType = this.checkExpression(expr.callee.object, scope, ctx);
                 if (objectType.kind === "array") {
+                    expr.callee.isBuiltin = true; // see checkMemberInner's string/array branches
                     return this.checkArrayMap(expr, objectType.element, scope, ctx);
                 }
             }
@@ -1159,7 +1442,31 @@ export class Checker {
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
-        const ctorParams = this.lookupCtorParams(expr.className);
+        let typeArg;
+        if (info.typeParam && !expr.typeArgs) {
+            this.diagnostics.error(`Generic class '${expr.className}' requires a type argument (e.g. 'new ${expr.className}<T>(...)')`, expr.line, expr.col);
+            // Abstractly-typed (T-containing) ctor params, un-substitutable
+            // without a real type argument, would otherwise cascade into a
+            // confusing "expected 'T'" error on every argument — one clear error
+            // beats that pile-on.
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        if (!info.typeParam && expr.typeArgs) {
+            this.diagnostics.error(`Class '${expr.className}' is not generic — it doesn't take a type argument`, expr.line, expr.col);
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        if (info.typeParam && expr.typeArgs) {
+            typeArg = this.resolveType(expr.typeArgs[0], expr.line, expr.col);
+        }
+        this.recordHover(expr.line, expr.col, typeArg ? `class ${expr.className}<${T.typeToString(typeArg)}>` : `class ${expr.className}`);
+        let ctorParams = this.lookupCtorParams(expr.className);
+        if (info.typeParam && typeArg) {
+            const paramName = info.typeParam;
+            const arg = typeArg;
+            ctorParams = ctorParams.map((p) => this.substituteTypeParam(p, paramName, arg));
+        }
         if (expr.args.length !== ctorParams.length) {
             this.diagnostics.error(`Expected ${ctorParams.length} constructor argument(s), got ${expr.args.length}`, expr.line, expr.col);
         }
@@ -1170,7 +1477,7 @@ export class Checker {
                 this.diagnostics.error(`Constructor argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
             }
         });
-        return T.classType(expr.className);
+        return T.classType(expr.className, typeArg);
     }
     lookupCtorParams(className) {
         let current = className;
@@ -1231,11 +1538,20 @@ export class Checker {
         return T.arrayOf(argType.returnType);
     }
     checkMember(expr, scope, ctx, isAssignTarget = false) {
+        const result = this.checkMemberInner(expr, scope, ctx, isAssignTarget);
+        const text = result.methodInfo
+            ? `${expr.property}(${result.methodInfo.params.map(T.typeToString).join(", ")}): ${T.typeToString(result.methodInfo.returnType)}`
+            : `${expr.property}: ${T.typeToString(result.type)}`;
+        this.recordHover(expr.line, expr.col, text);
+        return result;
+    }
+    checkMemberInner(expr, scope, ctx, isAssignTarget) {
         // A bare type name as the "object" — Color.Red (enum) or Dog.Count (static) —
         // is a type reference, not a value, so it's handled before the general expression check.
         if (expr.object.kind === "Identifier" && !scope.resolve(expr.object.name)) {
             const objName = expr.object.name;
             if (this.enums.has(objName)) {
+                this.recordHover(expr.object.line, expr.object.col, `enum ${objName}`);
                 const enumInfo = this.enums.get(objName);
                 if (!enumInfo.members.has(expr.property)) {
                     this.diagnostics.error(`Enum '${objName}' has no member '${expr.property}'`, expr.line, expr.col);
@@ -1244,6 +1560,7 @@ export class Checker {
                 return { type: T.enumType(objName), methodInfo: null };
             }
             if (this.classes.has(objName)) {
+                this.recordHover(expr.object.line, expr.object.col, `class ${objName}`);
                 const field = this.lookupStaticField(objName, expr.property);
                 if (field) {
                     this.checkAccessibility(field.info.visibility, field.owner, ctx, expr.property, expr.line, expr.col);
@@ -1259,7 +1576,16 @@ export class Checker {
             }
         }
         const objectType = this.checkExpression(expr.object, scope, ctx);
+        if (objectType.kind === "nullable") {
+            this.diagnostics.error(`Cannot access member '${expr.property}' on possibly-null type '${T.typeToString(objectType)}' — check for null first (e.g. 'if (x != null) { ... }')`, expr.line, expr.col);
+            return { type: T.UNKNOWN, methodInfo: null };
+        }
         if (objectType.kind === "string") {
+            // Marks this specific access as resolved against string's own
+            // built-ins, not some user member that merely shares the name —
+            // codegen's PascalCase -> camelCase renames rely on this, since they
+            // have no type information of their own to tell the two apart.
+            expr.isBuiltin = true;
             if (expr.property === "Length")
                 return { type: T.NUMBER, methodInfo: null };
             const method = STRING_METHODS[expr.property];
@@ -1269,6 +1595,7 @@ export class Checker {
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "array") {
+            expr.isBuiltin = true; // see the string branch above
             if (expr.property === "Length")
                 return { type: T.NUMBER, methodInfo: null };
             const method = this.arrayMethod(objectType.element, expr.property);
@@ -1300,6 +1627,12 @@ export class Checker {
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "class") {
+            // v1 has no generic inheritance (a generic class's base list can only
+            // name non-generic types), so a member found on a generic instance
+            // was always declared directly on that same class — substituting by
+            // its own type parameter, not some ancestor's, is always correct.
+            const paramName = objectType.typeArg ? this.genericTypeParams.get(objectType.name) : undefined;
+            const substitute = (type) => (paramName && objectType.typeArg ? this.substituteTypeParam(type, paramName, objectType.typeArg) : type);
             const field = this.lookupField(objectType.name, expr.property);
             if (field) {
                 this.checkAccessibility(field.info.visibility, field.owner, ctx, expr.property, expr.line, expr.col);
@@ -1309,12 +1642,13 @@ export class Checker {
                         this.diagnostics.error(`'${expr.property}' has no setter and can only be assigned within ${field.owner}'s constructor`, expr.line, expr.col);
                     }
                 }
-                return { type: field.info.type, methodInfo: null };
+                return { type: substitute(field.info.type), methodInfo: null };
             }
             const method = this.lookupMethod(objectType.name, expr.property);
             if (method) {
                 this.checkAccessibility(method.info.visibility, method.owner, ctx, expr.property, expr.line, expr.col);
-                return { type: method.info.returnType, methodInfo: method.info };
+                const info = paramName ? { ...method.info, params: method.info.params.map(substitute), returnType: substitute(method.info.returnType) } : method.info;
+                return { type: info.returnType, methodInfo: info };
             }
             this.diagnostics.error(`Class '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
@@ -1322,7 +1656,14 @@ export class Checker {
         if (objectType.kind === "interface") {
             const sig = this.collectInterfaceMethods(objectType.name).find((m) => m.name === expr.property);
             if (sig) {
-                return { type: sig.returnType, methodInfo: { params: sig.params, returnType: sig.returnType, visibility: "public", isVirtual: false, isOverride: false } };
+                // v1 has no generic interface inheritance either (same restriction
+                // as classes — see registerInterface), so a signature found here
+                // was always declared directly on this same interface.
+                const paramName = objectType.typeArg ? this.genericTypeParams.get(objectType.name) : undefined;
+                const substitute = (type) => (paramName && objectType.typeArg ? this.substituteTypeParam(type, paramName, objectType.typeArg) : type);
+                const params = sig.params.map(substitute);
+                const returnType = substitute(sig.returnType);
+                return { type: returnType, methodInfo: { params, returnType, visibility: "public", isVirtual: false, isOverride: false } };
             }
             this.diagnostics.error(`Interface '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };