kopscript 0.2.0 → 0.4.0

package/dist/cli.js

@@ -7,31 +7,89 @@ function outputPathFor(filePath) {
     const name = basename(filePath, ".ks");
     return join(resolve(filePath, ".."), `${name}.js`);
 }
+function collectDiagnostics(result) {
+    const all = [];
+    for (const absPath of result.order) {
+        const mod = result.modules.get(absPath);
+        for (const d of mod.diagnostics.diagnostics)
+            all.push({ ...d, file: absPath });
+    }
+    return all;
+}
+// One JSON object per invocation, always to stdout (never split across
+// lines, never mixed with human-readable output) — so a caller can pipe
+// this straight into `JSON.parse` without worrying about interleaving.
+function printJson(result, written) {
+    const diagnostics = collectDiagnostics(result);
+    console.log(JSON.stringify({ success: result.success, diagnostics, written }, null, 2));
+}
+function printJsonEntryMissing(filePath) {
+    console.log(JSON.stringify({ success: false, diagnostics: [], written: [], error: `cannot find file '${filePath}'` }, null, 2));
+}
+function printHumanDiagnostics(result) {
+    for (const absPath of result.order) {
+        const mod = result.modules.get(absPath);
+        if (mod.diagnostics.hasErrors) {
+            console.error(mod.diagnostics.format(mod.source, absPath));
+            console.error("");
+        }
+    }
+}
 // Compiles the whole module graph reachable from `filePath`, writing one
-// .js file next to each .ks source.
-function build(filePath) {
+// .js file next to each .ks source. With `jsonMode`, nothing but a single
+// JSON object goes to stdout (no "Wrote ..." line, no human diagnostics) —
+// see `printJson` for the shape.
+function build(filePath, jsonMode = false) {
     const result = compileGraph(filePath);
     if (result.entryMissing) {
-        console.error(`ks: cannot find file '${filePath}'`);
+        if (jsonMode)
+            printJsonEntryMissing(filePath);
+        else
+            console.error(`ks: cannot find file '${filePath}'`);
         process.exitCode = 1;
         return { outPath: null, watchFiles: [] };
     }
     if (!result.success) {
-        for (const absPath of result.order) {
-            const mod = result.modules.get(absPath);
-            if (mod.diagnostics.hasErrors) {
-                console.error(mod.diagnostics.format(mod.source, absPath));
-                console.error("");
-            }
-        }
+        if (jsonMode)
+            printJson(result, []);
+        else
+            printHumanDiagnostics(result);
         process.exitCode = 1;
         return { outPath: null, watchFiles: result.order };
     }
     for (const absPath of result.order) {
         writeFileSync(outputPathFor(absPath), result.outputs.get(absPath), "utf-8");
     }
+    if (jsonMode)
+        printJson(result, result.order.map(outputPathFor));
     return { outPath: outputPathFor(filePath), watchFiles: result.order };
 }
+// Type-checks the graph without writing any output — for CI or an editor/
+// agent that wants pass/fail plus diagnostics without touching the
+// filesystem. Same exit-code convention as `build` (0 clean, 1 on any
+// error or a missing entry file).
+function checkCommand(filePath, jsonMode) {
+    const result = compileGraph(filePath);
+    if (result.entryMissing) {
+        if (jsonMode)
+            printJsonEntryMissing(filePath);
+        else
+            console.error(`ks: cannot find file '${filePath}'`);
+        process.exitCode = 1;
+        return;
+    }
+    if (jsonMode) {
+        printJson(result, []);
+    }
+    else if (result.success) {
+        console.log("No errors.");
+    }
+    else {
+        printHumanDiagnostics(result);
+    }
+    if (!result.success)
+        process.exitCode = 1;
+}
 function run(filePath) {
     const { outPath } = build(filePath);
     if (!outPath)
@@ -77,17 +135,28 @@ function watchCommand(filePath) {
     console.log(`[watch] ${filePath} — watching for changes. Press Ctrl+C to stop.`);
     rebuild();
 }
+const COMMANDS = ["build", "run", "watch", "check"];
 function main() {
-    const [, , command, file] = process.argv;
-    if (!command || !file || (command !== "build" && command !== "run" && command !== "watch")) {
-        console.error("Usage: ks <build|run|watch> <file.ks>");
+    const args = process.argv.slice(2);
+    const jsonMode = args.includes("--json");
+    const [command, file] = args.filter((a) => a !== "--json");
+    if (!command || !file || !COMMANDS.includes(command)) {
+        console.error("Usage: ks <build|run|watch|check> <file.ks> [--json]");
+        process.exitCode = 1;
+        return;
+    }
+    if (jsonMode && command !== "build" && command !== "check") {
+        console.error("ks: --json is only supported with 'build' and 'check'");
         process.exitCode = 1;
         return;
     }
     const filePath = resolve(file);
-    if (command === "build") {
-        const { outPath } = build(filePath);
-        if (outPath)
+    if (command === "check") {
+        checkCommand(filePath, jsonMode);
+    }
+    else if (command === "build") {
+        const { outPath } = build(filePath, jsonMode);
+        if (outPath && !jsonMode)
             console.log(`Wrote ${outPath}`);
     }
     else if (command === "watch") {

package/dist/codegen.js

@@ -253,6 +253,8 @@ export class CodeGenerator {
                 return JSON.stringify(expr.value);
             case "BoolLiteral":
                 return String(expr.value);
+            case "NullLiteral":
+                return "null";
             case "InterpolatedStringLiteral":
                 return this.genInterpolatedString(expr);
             case "ArrayLiteral":
@@ -309,13 +311,24 @@ export class CodeGenerator {
         // Array.Push is non-mutating in KopScript, unlike JS's own (mutating,
         // length-returning) Array.prototype.push — so it can't just be a member
         // rename like Map/Filter/ForEach; it needs an entirely different call
-        // shape (a spread into a fresh array).
-        if (expr.callee.kind === "MemberExpr" && expr.callee.property === "Push" && expr.args.length === 1) {
+        // shape (a spread into a fresh array). Gated on `isBuiltin` (set by the
+        // checker only when the receiver is actually an array) so a user class
+        // with its own same-named `Push(x)` method — a natural name for any
+        // Stack<T>/List<T>-style container, now that generics exist — still
+        // compiles to a normal method call instead of this rewrite.
+        if (expr.callee.kind === "MemberExpr" && expr.callee.isBuiltin && expr.callee.property === "Push" && expr.args.length === 1) {
             return `[...${this.genExpr(expr.callee.object)}, ${this.genExpr(expr.args[0])}]`;
         }
         return `${this.genExpr(expr.callee)}(${expr.args.map((a) => this.genExpr(a)).join(", ")})`;
     }
     genMember(expr) {
+        // PascalCase -> camelCase (and Length -> length) only applies to a
+        // genuine string/array built-in — see MemberExpr.isBuiltin's own
+        // comment for why this can't just be a name match. Anything else
+        // (including a user member that happens to share one of these names)
+        // passes through with its real, declared name untouched.
+        if (!expr.isBuiltin)
+            return `${this.genExpr(expr.object)}.${expr.property}`;
         const jsProperty = expr.property === "Length" ? "length" : MEMBER_METHOD_MAP[expr.property] ?? expr.property;
         return `${this.genExpr(expr.object)}.${jsProperty}`;
     }

package/dist/lexer.js

@@ -34,6 +34,7 @@ const KEYWORDS = {
     void: TokenKind.Void,
     true: TokenKind.True,
     false: TokenKind.False,
+    null: TokenKind.Null,
     task: TokenKind.Task,
     state: TokenKind.State,
     async: TokenKind.Async,
@@ -214,6 +215,8 @@ export class Lexer {
                 return this.make(TokenKind.Semicolon, c, line, col);
             case ".":
                 return this.make(TokenKind.Dot, c, line, col);
+            case "?":
+                return this.make(TokenKind.Question, c, line, col);
             case "+":
                 return this.make(TokenKind.Plus, c, line, col);
             case "-":

package/dist/modules.js

@@ -29,7 +29,7 @@ export function loadModuleGraph(entryAbsPath) {
         const diagnostics = new DiagnosticBag();
         const tokens = new Lexer(source, diagnostics).tokenize();
         const program = new Parser(tokens, diagnostics).parseProgram();
-        const record = { absPath, source, program, diagnostics, dependencies: [] };
+        const record = { absPath, source, program, diagnostics, dependencies: [], hoverEntries: [] };
         modules.set(absPath, record);
         stack.push(absPath);
         for (const u of program.usings) {
@@ -107,6 +107,7 @@ export function compileGraph(entryAbsPath) {
         }
         const checker = new Checker(mod.program, mod.diagnostics, merged, absPath);
         checker.check();
+        mod.hoverEntries = checker.hoverEntries;
         if (mod.diagnostics.hasErrors)
             hasErrors = true;
         exportsByModule.set(absPath, checker.getExports());

package/dist/parser.js

@@ -153,7 +153,8 @@ export class Parser {
             this.advance();
         }
         const type = this.parseType();
-        const name = this.consume(TokenKind.Identifier, "Expected name").lexeme;
+        const nameTok = this.consume(TokenKind.Identifier, "Expected name");
+        const name = nameTok.lexeme;
         if (this.check(TokenKind.LParen)) {
             const params = this.parseParamList();
             const body = this.parseBlock();
@@ -165,7 +166,7 @@ export class Parser {
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
         this.consume(TokenKind.Semicolon, "Expected ';' after variable declaration");
-        return { kind: "VarDecl", isConst: false, name, type, init, line: start.line, col: start.col };
+        return { kind: "VarDecl", isConst: false, name, nameLine: nameTok.line, nameCol: nameTok.col, type, init, line: start.line, col: start.col };
     }
     // Parses `Type name = init` without consuming a trailing terminator — used
     // both for top-level/block statements (which add the `;`) and for-loop
@@ -173,18 +174,18 @@ export class Parser {
     parseVarDeclHeader() {
         const start = this.peek();
         const type = this.parseType();
-        const name = this.consume(TokenKind.Identifier, "Expected variable name").lexeme;
+        const nameTok = this.consume(TokenKind.Identifier, "Expected variable name");
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
-        return { kind: "VarDecl", isConst: false, name, type, init, line: start.line, col: start.col };
+        return { kind: "VarDecl", isConst: false, name: nameTok.lexeme, nameLine: nameTok.line, nameCol: nameTok.col, type, init, line: start.line, col: start.col };
     }
     parseConstDecl() {
         const start = this.advance(); // 'const'
         const type = this.parseType();
-        const name = this.consume(TokenKind.Identifier, "Expected constant name").lexeme;
+        const nameTok = this.consume(TokenKind.Identifier, "Expected constant name");
         this.consume(TokenKind.Assign, "Expected '=' in constant declaration");
         const init = this.parseExpression();
-        return { kind: "VarDecl", isConst: true, name, type, init, line: start.line, col: start.col };
+        return { kind: "VarDecl", isConst: true, name: nameTok.lexeme, nameLine: nameTok.line, nameCol: nameTok.col, type, init, line: start.line, col: start.col };
     }
     parseParamList() {
         this.consume(TokenKind.LParen, "Expected '('");
@@ -199,9 +200,20 @@ export class Parser {
         this.consume(TokenKind.RParen, "Expected ')' after parameters");
         return params;
     }
+    // `<T>` right after a class/interface name — a single, unconstrained type
+    // parameter (v1 has no `Map<K, V>`, no `T : IFoo` constraints). Null if
+    // absent, the overwhelmingly common case.
+    parseOptionalTypeParam() {
+        if (!this.match(TokenKind.Lt))
+            return null;
+        const name = this.consume(TokenKind.Identifier, "Expected a type parameter name").lexeme;
+        this.consume(TokenKind.Gt, "Expected '>' after type parameter");
+        return name;
+    }
     parseClassDecl(isExported) {
         const start = this.advance(); // 'class'
         const name = this.consume(TokenKind.Identifier, "Expected class name").lexeme;
+        const typeParam = this.parseOptionalTypeParam();
         const baseList = [];
         if (this.match(TokenKind.Colon)) {
             do {
@@ -260,7 +272,8 @@ export class Parser {
             }
             const memberStart = this.peek();
             const type = this.parseType();
-            const memberName = this.consume(TokenKind.Identifier, "Expected field, property, or method name").lexeme;
+            const memberNameTok = this.consume(TokenKind.Identifier, "Expected field, property, or method name");
+            const memberName = memberNameTok.lexeme;
             if (this.check(TokenKind.LParen)) {
                 const params = this.parseParamList();
                 const body = this.parseBlock();
@@ -275,6 +288,8 @@ export class Parser {
                     isVirtual,
                     isOverride,
                     name: memberName,
+                    nameLine: memberNameTok.line,
+                    nameCol: memberNameTok.col,
                     params,
                     returnType: type,
                     body,
@@ -307,6 +322,8 @@ export class Parser {
                     visibility,
                     hasSetter,
                     name: memberName,
+                    nameLine: memberNameTok.line,
+                    nameCol: memberNameTok.col,
                     type,
                     line: memberStart.line,
                     col: memberStart.col,
@@ -331,6 +348,8 @@ export class Parser {
                     isStatic,
                     initializer,
                     name: memberName,
+                    nameLine: memberNameTok.line,
+                    nameCol: memberNameTok.col,
                     type,
                     line: memberStart.line,
                     col: memberStart.col,
@@ -338,11 +357,12 @@ export class Parser {
             }
         }
         this.consume(TokenKind.RBrace, "Expected '}' after class body");
-        return { kind: "ClassDecl", isExported, name, baseList, fields, properties, constructor: ctor, methods, line: start.line, col: start.col };
+        return { kind: "ClassDecl", isExported, name, typeParam, baseList, fields, properties, constructor: ctor, methods, line: start.line, col: start.col };
     }
     parseInterfaceDecl(isExported) {
         const start = this.advance(); // 'interface'
         const name = this.consume(TokenKind.Identifier, "Expected interface name").lexeme;
+        const typeParam = this.parseOptionalTypeParam();
         const baseList = [];
         if (this.match(TokenKind.Colon)) {
             do {
@@ -354,13 +374,21 @@ export class Parser {
         while (!this.check(TokenKind.RBrace) && !this.check(TokenKind.EOF)) {
             const memberStart = this.peek();
             const returnType = this.parseType();
-            const methodName = this.consume(TokenKind.Identifier, "Expected method name").lexeme;
+            const methodNameTok = this.consume(TokenKind.Identifier, "Expected method name");
             const params = this.parseParamList();
             this.consume(TokenKind.Semicolon, "Expected ';' after interface method signature");
-            methods.push({ name: methodName, params, returnType, line: memberStart.line, col: memberStart.col });
+            methods.push({
+                name: methodNameTok.lexeme,
+                nameLine: methodNameTok.line,
+                nameCol: methodNameTok.col,
+                params,
+                returnType,
+                line: memberStart.line,
+                col: memberStart.col,
+            });
         }
         this.consume(TokenKind.RBrace, "Expected '}' after interface body");
-        return { kind: "InterfaceDecl", isExported, name, baseList, methods, line: start.line, col: start.col };
+        return { kind: "InterfaceDecl", isExported, name, typeParam, baseList, methods, line: start.line, col: start.col };
     }
     parseEnumDecl(isExported) {
         const start = this.advance(); // 'enum'
@@ -604,8 +632,8 @@ export class Parser {
             type = this.parseFunctionType();
         }
         else if (this.check(TokenKind.Task)) {
-            this.advance();
-            let resultType = { kind: "NamedType", name: "void" };
+            const taskTok = this.advance();
+            let resultType = { kind: "NamedType", name: "void", typeArgs: null, line: taskTok.line, col: taskTok.col };
             if (this.match(TokenKind.Lt)) {
                 resultType = this.parseType();
                 this.consume(TokenKind.Gt, "Expected '>' after task result type");
@@ -621,12 +649,31 @@ export class Parser {
         }
         else {
             const nameToken = this.check(TokenKind.Void) ? this.advance() : this.consume(TokenKind.Identifier, "Expected type name");
-            type = { kind: "NamedType", name: nameToken.lexeme };
+            // `Box<number>` — a generic type reference. At most one type argument
+            // in v1 (matching ClassDecl/InterfaceDecl's single type parameter);
+            // whether `name` actually refers to a declared generic type is a
+            // semantic question the checker answers, not the parser.
+            let typeArgs = null;
+            if (this.check(TokenKind.Lt)) {
+                this.advance();
+                typeArgs = [this.parseType()];
+                this.consume(TokenKind.Gt, "Expected '>' after type argument");
+            }
+            type = { kind: "NamedType", name: nameToken.lexeme, typeArgs, line: nameToken.line, col: nameToken.col };
         }
-        while (this.check(TokenKind.LBracket)) {
-            this.advance();
-            this.consume(TokenKind.RBracket, "Expected ']' after '[' in array type");
-            type = { kind: "ArrayType", element: type };
+        // `[]` and `?` are both postfix and can alternate in either order —
+        // `string?[]` (array of nullable strings) and `string[]?` (nullable
+        // array of strings) parse with the nesting their order implies.
+        while (this.check(TokenKind.LBracket) || this.check(TokenKind.Question)) {
+            if (this.check(TokenKind.LBracket)) {
+                this.advance();
+                this.consume(TokenKind.RBracket, "Expected ']' after '[' in array type");
+                type = { kind: "ArrayType", element: type };
+            }
+            else {
+                const q = this.advance();
+                type = { kind: "NullableType", inner: type, line: q.line, col: q.col };
+            }
         }
         return type;
     }
@@ -779,6 +826,10 @@ export class Parser {
             this.advance();
             return { kind: "BoolLiteral", value: t.kind === TokenKind.True, line: t.line, col: t.col };
         }
+        if (this.check(TokenKind.Null)) {
+            this.advance();
+            return { kind: "NullLiteral", line: t.line, col: t.col };
+        }
         if (this.check(TokenKind.This)) {
             this.advance();
             return { kind: "ThisExpr", line: t.line, col: t.col };
@@ -786,6 +837,15 @@ export class Parser {
         if (this.check(TokenKind.New)) {
             this.advance();
             const className = this.consume(TokenKind.Identifier, "Expected class name after 'new'").lexeme;
+            // `new Box<number>(...)` — unambiguous here: `new <Identifier>` is
+            // always followed by `(`, generic type args or not, so seeing `<`
+            // instead can only mean a type argument list, never a comparison.
+            let typeArgs = null;
+            if (this.check(TokenKind.Lt)) {
+                this.advance();
+                typeArgs = [this.parseType()];
+                this.consume(TokenKind.Gt, "Expected '>' after type argument");
+            }
             this.consume(TokenKind.LParen, "Expected '(' after class name");
             const args = [];
             if (!this.check(TokenKind.RParen)) {
@@ -794,7 +854,7 @@ export class Parser {
                 } while (this.match(TokenKind.Comma));
             }
             this.consume(TokenKind.RParen, "Expected ')' after constructor arguments");
-            return { kind: "NewExpr", className, args, line: t.line, col: t.col };
+            return { kind: "NewExpr", className, typeArgs, args, line: t.line, col: t.col };
         }
         if (this.check(TokenKind.LBracket)) {
             this.advance();
@@ -832,26 +892,39 @@ export class Parser {
         this.diagnostics.error(`Unexpected token '${t.lexeme || t.kind}'`, t.line, t.col);
         throw new ParseError();
     }
-    // Lightweight lookahead (not a trial parse) distinguishing a lambda's
-    // parameter list from a parenthesized expression. A lambda parameter is
-    // always `Type name` (types are required, no inference in v1), so seeing
-    // two consecutive identifiers — or an empty `()` followed by `=>` — is
-    // unambiguous. This doesn't handle a lambda whose own first parameter is
-    // itself a function type (e.g. a higher-order lambda); that's a known v1
-    // gap in favor of keeping this check cheap.
+    // Distinguishes a lambda's parameter list from a parenthesized expression.
+    // A lambda parameter is always `Type name` (types are required, no
+    // inference in v1), so seeing a full type followed by an identifier — or
+    // an empty `()` followed by `=>` — is unambiguous. Uses a real speculative
+    // parse of the candidate type (same save-position/try/rollback shape as
+    // isDeclStart) rather than hand-rolled token lookahead, so it stays
+    // correct as parseType grows new postfix/prefix forms (`?`, `<T>`, ...)
+    // without needing a matching update here every time. This doesn't handle
+    // a lambda whose own first parameter is itself a function type (e.g. a
+    // higher-order lambda); that's a known v1 gap in favor of keeping this
+    // check simple.
     looksLikeLambda() {
-        let i = this.pos + 1; // just past '('
+        const i = this.pos + 1; // just past '('
         if (this.tokens[i]?.kind === TokenKind.RParen) {
             return this.tokens[i + 1]?.kind === TokenKind.Arrow;
         }
         const startKind = this.tokens[i]?.kind;
         if (startKind !== TokenKind.Identifier && startKind !== TokenKind.Void)
             return false;
-        i++;
-        while (this.tokens[i]?.kind === TokenKind.LBracket && this.tokens[i + 1]?.kind === TokenKind.RBracket) {
-            i += 2;
+        const savedPos = this.pos;
+        const savedDiagnosticsLength = this.diagnostics.diagnostics.length;
+        this.pos = i;
+        let result;
+        try {
+            this.parseType();
+            result = this.check(TokenKind.Identifier);
         }
-        return this.tokens[i]?.kind === TokenKind.Identifier;
+        catch {
+            result = false;
+        }
+        this.pos = savedPos;
+        this.diagnostics.diagnostics.length = savedDiagnosticsLength;
+        return result;
     }
     parseLambda() {
         const start = this.peek(); // '('

package/dist/tokens.js

@@ -8,6 +8,7 @@ export var TokenKind;
     TokenKind["Identifier"] = "Identifier";
     TokenKind["True"] = "True";
     TokenKind["False"] = "False";
+    TokenKind["Null"] = "Null";
     // Keywords
     TokenKind["Using"] = "Using";
     TokenKind["Extern"] = "Extern";
@@ -62,6 +63,7 @@ export var TokenKind;
     TokenKind["Dot"] = "Dot";
     TokenKind["Arrow"] = "Arrow";
     TokenKind["Underscore"] = "Underscore";
+    TokenKind["Question"] = "Question";
     // Operators
     TokenKind["Plus"] = "Plus";
     TokenKind["Minus"] = "Minus";

package/dist/types.js

@@ -6,11 +6,14 @@ export const UNKNOWN = { kind: "unknown" };
 export function arrayOf(element) {
     return { kind: "array", element };
 }
-export function classType(name) {
-    return { kind: "class", name };
+export function classType(name, typeArg) {
+    return typeArg ? { kind: "class", name, typeArg } : { kind: "class", name };
 }
-export function interfaceType(name) {
-    return { kind: "interface", name };
+export function interfaceType(name, typeArg) {
+    return typeArg ? { kind: "interface", name, typeArg } : { kind: "interface", name };
+}
+export function typeParamType(name) {
+    return { kind: "typeParam", name };
 }
 export function enumType(name) {
     return { kind: "enum", name };
@@ -24,6 +27,9 @@ export function taskType(resultType) {
 export function stateType(valueType) {
     return { kind: "state", valueType };
 }
+export function nullableOf(inner) {
+    return inner.kind === "nullable" ? inner : { kind: "nullable", inner };
+}
 export function typeToString(t) {
     switch (t.kind) {
         case "number":
@@ -34,56 +40,88 @@ export function typeToString(t) {
             return t.kind;
         case "array":
             return `${typeToString(t.element)}[]`;
-        case "class":
-        case "interface":
         case "enum":
             return t.name;
+        case "class":
+        case "interface":
+            return t.typeArg ? `${t.name}<${typeToString(t.typeArg)}>` : t.name;
         case "function":
             return `(${t.params.map(typeToString).join(", ")}) => ${typeToString(t.returnType)}`;
         case "task":
             return t.resultType.kind === "void" ? "task" : `task<${typeToString(t.resultType)}>`;
         case "state":
             return `state<${typeToString(t.valueType)}>`;
+        case "nullable":
+            return `${typeToString(t.inner)}?`;
+        case "typeParam":
+            return t.name;
     }
 }
 const PRIMITIVE_NAMES = new Set(["number", "string", "bool", "void"]);
 // Resolves a syntactic type annotation to a Type, given the kind of every known
-// user-declared name (class, interface, or enum).
-export function resolveTypeNode(node, namedTypes) {
+// user-declared name (class, interface, or enum). `onNamedType`, when given, is
+// called with every `NamedType` leaf visited and the Type it resolved to — a
+// hook for tools (e.g. hover) that want to know what a type annotation in
+// source actually refers to, without duplicating this resolution logic.
+export function resolveTypeNode(node, namedTypes, onNamedType) {
     if (node.kind === "ArrayType") {
-        const element = resolveTypeNode(node.element, namedTypes);
+        const element = resolveTypeNode(node.element, namedTypes, onNamedType);
         return element ? arrayOf(element) : null;
     }
     if (node.kind === "FunctionType") {
         const params = [];
         for (const p of node.params) {
-            const resolved = resolveTypeNode(p, namedTypes);
+            const resolved = resolveTypeNode(p, namedTypes, onNamedType);
             if (!resolved)
                 return null;
             params.push(resolved);
         }
-        const returnType = resolveTypeNode(node.returnType, namedTypes);
+        const returnType = resolveTypeNode(node.returnType, namedTypes, onNamedType);
         return returnType ? functionType(params, returnType) : null;
     }
     if (node.kind === "TaskType") {
-        const resultType = resolveTypeNode(node.resultType, namedTypes);
+        const resultType = resolveTypeNode(node.resultType, namedTypes, onNamedType);
         return resultType ? taskType(resultType) : null;
     }
     if (node.kind === "StateType") {
-        const valueType = resolveTypeNode(node.valueType, namedTypes);
+        const valueType = resolveTypeNode(node.valueType, namedTypes, onNamedType);
         return valueType ? stateType(valueType) : null;
     }
+    if (node.kind === "NullableType") {
+        const inner = resolveTypeNode(node.inner, namedTypes, onNamedType);
+        return inner ? nullableOf(inner) : null;
+    }
+    // At most one type argument in v1 — resolve it once, up front; a
+    // primitive/enum/type-param name below never accepts one (arity error,
+    // caught as a plain resolution failure here — a class/interface's own
+    // required-vs-supplied arity mismatch is a separate check the caller
+    // makes, since only it knows which names are actually declared generic).
+    let typeArg = null;
+    if (node.typeArgs) {
+        typeArg = resolveTypeNode(node.typeArgs[0], namedTypes, onNamedType);
+        if (!typeArg)
+            return null;
+    }
+    let resolved;
     if (PRIMITIVE_NAMES.has(node.name)) {
-        return { kind: node.name };
+        resolved = typeArg ? null : { kind: node.name };
+    }
+    else {
+        const kind = namedTypes.get(node.name);
+        if (kind === "class")
+            resolved = classType(node.name, typeArg ?? undefined);
+        else if (kind === "interface")
+            resolved = interfaceType(node.name, typeArg ?? undefined);
+        else if (kind === "enum")
+            resolved = typeArg ? null : enumType(node.name);
+        else if (kind === "typeParam")
+            resolved = typeArg ? null : typeParamType(node.name);
+        else
+            resolved = null;
     }
-    const kind = namedTypes.get(node.name);
-    if (kind === "class")
-        return classType(node.name);
-    if (kind === "interface")
-        return interfaceType(node.name);
-    if (kind === "enum")
-        return enumType(node.name);
-    return null;
+    if (resolved)
+        onNamedType?.(node, resolved);
+    return resolved;
 }
 export function typesEqual(a, b) {
     if (a.kind === "unknown" || b.kind === "unknown")
@@ -101,8 +139,28 @@ export function typesEqual(a, b) {
     if (a.kind === "state" && b.kind === "state") {
         return typesEqual(a.valueType, b.valueType);
     }
-    if ((a.kind === "class" || a.kind === "interface" || a.kind === "enum") && "name" in b) {
+    if (a.kind === "nullable" && b.kind === "nullable") {
+        return typesEqual(a.inner, b.inner);
+    }
+    if (a.kind === "typeParam" && b.kind === "typeParam") {
         return a.name === b.name;
     }
+    // Invariant generics: Box<number> and Box<string> are unrelated types,
+    // and so are Box<number> and bare (non-generic-reference) Box — the
+    // latter only arises from an arity error already diagnosed elsewhere, so
+    // treating it as unequal here (rather than papering over it) is right.
+    if ((a.kind === "class" || a.kind === "interface" || a.kind === "enum") && "name" in b) {
+        const other = b;
+        if (a.name !== other.name)
+            return false;
+        if ("typeArg" in a || "typeArg" in other) {
+            const aArg = a.typeArg;
+            const bArg = other.typeArg;
+            if (!aArg || !bArg)
+                return false;
+            return typesEqual(aArg, bArg);
+        }
+        return true;
+    }
     return true;
 }