kopscript 0.18.0 → 0.19.1

package/LLM.md

@@ -167,13 +167,51 @@ string Classify(string input) {
   return match input {
     "cat", "dog" => "animal",     // comma = OR within one arm
     r"^[0-9]+$" => "number",      // regex pattern, r"..."
-    _ => "unknown"                // wildcard REQUIRED — exhaustiveness-checked
+    _ => "unknown"                // wildcard REQUIRED for a string subject
   };
 }
 ```
 
-`match` is an expression (has a value), matches on literal/regex patterns only (not
-type patterns, not destructuring), and always requires a trailing `_` arm.
+`match` is an expression (has a value) over one of two kinds of subject:
+
+- **`string`** — literal/regex patterns only (not type patterns, not destructuring),
+  and always requires a trailing `_` arm, exactly as above.
+- **an `enum`** — patterns name a member of that same enum (`EnumName.Member`, comma
+  for OR within one arm, same as a string match); no regex patterns (there's nothing
+  to run a regex against). **Real exhaustiveness**: covering every declared member
+  lets the trailing `_` be omitted entirely — there's nothing left for it to catch —
+  and a member missing from BOTH the arms and a trailing wildcard is a compile error
+  naming exactly which member(s) are missing:
+
+```ks
+enum OrderState { Pending, Shipped, Delivered, Cancelled }
+
+string Describe(OrderState s) {
+  return match s {
+    OrderState.Pending => "placed",
+    OrderState.Shipped => "shipped",
+    OrderState.Delivered => "delivered",
+    OrderState.Cancelled => "cancelled"
+    // no `_` needed — every member is covered; add a 5th enum member later
+    // without updating this match, and this stops compiling.
+  };
+}
+```
+
+A partial enum match still works exactly like a string match — cover the cases you
+care about and fall back with `_`:
+
+```ks
+string UrgencyOf(OrderState s) {
+  return match s {
+    OrderState.Cancelled => "none",
+    _ => "normal"
+  };
+}
+```
+
+`match` still doesn't support type patterns or destructuring for either subject kind
+— an enum match's patterns are exactly its own members, nothing more general.
 
 ## Statements
 
@@ -233,6 +271,18 @@ literal in the language, which do interpret `\n`/`\t`/`\\`/etc.
 lambda's own first parameter cannot itself be a function type (a rare v1 parser
 limitation, not a semantic one).
 
+**An expression-bodied lambda may discard a non-`void` result where `() => void` is
+expected** — the fire-and-forget shape a `setTimeout`/`setInterval` callback needs:
+```ks
+public async task DoWork() { ... }
+SetTimeout(() => this.DoWork(), 300);   // () => task discarded into () => void — fine
+```
+This is narrower than "anything is assignable to `void`": a `void`-returning
+function's own `return expr;` is still a real error, checked separately — this only
+relaxes a lambda's own trailing expression value when nothing will ever read it,
+matching the same allowance TypeScript gives a `Promise`-returning function passed
+where `() => void` is expected.
+
 ### Arrays
 
 ```ks
@@ -403,6 +453,16 @@ parameter, not a syntax feature to reach for. A constrained type parameter (`T :
 IComparable`) works exactly like it does on a class — the inferred type must satisfy it,
 checked after inference succeeds.
 
+**Extern generic free functions**: an `extern` free function can carry its own type
+parameter list too, re-describing a real generic free function from another package
+(the same shape `extern class Name<T> { ... }` already gives a generic class):
+```ks
+extern (T) => string? CombineValidators2<T>((T) => string? v1, (T) => string? v2) from "kopular/forms";
+(string) => string? combined = CombineValidators2(Required, TooLong);
+```
+Inference, constraints, and arity all work exactly the same as a real generic
+function's — the extern boundary doesn't lose any of it.
+
 **Does not exist (v1 scope cuts, each deliberate)**:
 - **Generic methods.** A class method can't introduce its own new type parameter beyond
   its enclosing class's (generic functions are free-function-only — see above).
@@ -492,6 +552,13 @@ constraint errors included) — and a real KopScript class can extend a generic
 class` with a concrete or threaded-through type argument, same as extending a real generic
 base.
 
+An extern *free function* (the first form above) can carry its own type parameter list
+too, the same place a real generic free function's goes — right after the name:
+`extern (T) => string? CombineValidators2<T>((T) => string? v1, (T) => string? v2) from
+"kopular/forms";`. Inference/constraints/arity all work identically to a real generic
+function (see "Generics" above) — only an extern *value* declaration (the second form)
+can never have one, since there's no call site for a type argument to attach to.
+
 **Never write `async` on an extern function/method signature** — declare its return type
 as `task`/`task<T>` directly (`task<string> text();`, not `async task<string> text();`).
 `async` only means something for a *body* the checker validates (legalizing `await`

package/README.md

@@ -330,6 +330,12 @@ if (c == Color.Green) { print("It's green"); }
 
 Members are numbered from `0` in declaration order, compiling to a frozen JS object.
 
+An enum is also a valid `match` subject (`match c { Color.Red => ..., Color.Green =>
+..., Color.Blue => ..., _ => ... }`, patterns naming its own members) — covering
+every member lets the trailing `_` be omitted, with a real compile error if one is
+missing and there's no `_` to fall back on. See LLM.md's "`match` expression" section
+for the full exhaustiveness rules.
+
 ### Modules
 
 `using "./shapes";` brings every `public` top-level declaration from that file (resolved
@@ -432,6 +438,11 @@ extern class Box<T> {
 Box<number> nb = new Box<number>(5);
 ```
 
+An extern *free function* can be generic the same way — `extern (T) => string?
+CombineValidators2<T>((T) => string? v1, (T) => string? v2) from "kopular/forms";`
+re-describes a real generic free function from another package, with the same
+inference/constraints a local one gets.
+
 Now that KopScript has `async`/`await` and `task<T>` (see below), a Promise-based JS API is
 describable too — `extern task<string> Fetch(...) from "..." as "fetch";` is legitimate,
 and `await`ing it works exactly like awaiting any other KopScript task. What's still not cleanly

package/dist/checker.js

@@ -194,14 +194,21 @@ export class Checker {
             this.checkClassBody(c);
     }
     registerExternFunction(decl) {
-        // extern functions never take a type parameter of their own in v1 —
-        // generic functions (see registerFunction) are a real-function-only
-        // feature; an extern binding always describes a concrete signature.
-        this.functions.set(decl.name, {
-            typeParams: [],
-            typeParamConstraints: [],
+        // Same withTypeParamsInScope treatment registerFunction gives a real
+        // generic function's own signature — an extern free function can be
+        // generic too (re-describing a real generic free function from another
+        // package, e.g. Kopular's own `CombineValidators2<T>`), resolved the
+        // same way so `T` inside `decl.params`/`decl.returnType` resolves
+        // correctly instead of erroring as an unknown type.
+        const { params, returnType } = this.withTypeParamsInScope(decl.typeParams, () => ({
             params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
             returnType: this.resolveType(decl.returnType, decl.line, decl.col),
+        }));
+        this.functions.set(decl.name, {
+            typeParams: decl.typeParams.map((p) => p.name),
+            typeParamConstraints: decl.typeParams.map((p) => p.constraint),
+            params,
+            returnType,
         });
     }
     registerExternClass(decl) {
@@ -1644,6 +1651,19 @@ export class Checker {
             return expectedReturnType;
         }
         const actual = this.checkExpressionExpecting(expr.body, expectedReturnType, scope, lambdaCtx);
+        // An expression-bodied lambda whose expected type is `() => void` may
+        // still have a body that naturally evaluates to something non-void
+        // (`() => this.SubmitTask()` where SubmitTask is `async task`, the
+        // fire-and-forget shape `setTimeout`/`setInterval` callbacks need) —
+        // discarding that value is always safe, the same allowance TypeScript
+        // gives a `Promise`-returning function passed where `() => void` is
+        // expected. This is narrower than "anything is assignable to void": a
+        // `void`-returning FUNCTION's own `return expr;` is still checked
+        // separately and is still a real error — this only relaxes a lambda's
+        // own trailing expression value when nothing will ever read it.
+        if (expectedReturnType.kind === "void") {
+            return T.VOID;
+        }
         if (expectedReturnType.kind !== "unknown" && !this.isAssignableType(actual, expectedReturnType)) {
             this.diagnostics.error("KS4059", `Lambda body has type '${T.typeToString(actual)}', expected '${T.typeToString(expectedReturnType)}'`, expr.line, expr.col);
         }
@@ -2176,30 +2196,69 @@ export class Checker {
         }
         return { type: T.UNKNOWN, methodInfo: null };
     }
+    // `match` accepts two kinds of subject: `string` (the original, matching
+    // literal/regex patterns — unchanged below) and, as of this check, an
+    // `enum` (matching `EnumName.Member` patterns, with real exhaustiveness:
+    // every member covered lets the trailing `_` be omitted entirely, since
+    // there's nothing left for it to catch). Nothing else is valid — a
+    // `match` over a class/number/etc. was never supported and still isn't.
     checkMatch(expr, scope, ctx) {
         const subjectType = this.checkExpression(expr.subject, scope, ctx);
-        this.expectType(subjectType, T.STRING, expr.line, expr.col, "match subject");
+        const isEnumSubject = subjectType.kind === "enum";
+        // Still routed through the shared expectType helper (one literal
+        // KS4046 emission site for the whole checker — see diagnostics.test.ts's
+        // "codes are unique across every emission site"), so the message loses
+        // the "...or an enum" alternative when the subject is neither — an
+        // acceptable trade against introducing a second call site for what's
+        // still fundamentally "wrong type here."
+        if (!isEnumSubject) {
+            this.expectType(subjectType, T.STRING, expr.line, expr.col, "match subject");
+        }
+        const enumName = isEnumSubject ? subjectType.name : null;
         if (expr.arms.length === 0) {
             this.diagnostics.error("KS4086", `match expression must have at least one arm`, expr.line, expr.col);
             return T.UNKNOWN;
         }
         const lastArm = expr.arms[expr.arms.length - 1];
-        if (lastArm.pattern.kind !== "WildcardPattern") {
+        const hasTrailingWildcard = lastArm.pattern.kind === "WildcardPattern";
+        // A plain string match still always requires it (unchanged from
+        // before enums were supported) — only an enum subject can skip it, and
+        // only by covering every member explicitly instead (checked below,
+        // once every arm's patterns have been walked).
+        if (!hasTrailingWildcard && !isEnumSubject) {
             this.diagnostics.error("KS4087", `match expression must end with a wildcard '_' arm`, lastArm.line, lastArm.col);
         }
+        const coveredEnumMembers = new Set();
         let resultType = null;
         for (const arm of expr.arms) {
             if (arm.pattern.kind === "LiteralPattern") {
                 for (const value of arm.pattern.values) {
-                    if (value.kind !== "StringLiteral") {
-                        this.diagnostics.error("KS4088", `match patterns must be string literals`, value.line, value.col);
+                    if (isEnumSubject) {
+                        const valueType = this.checkExpression(value, scope, ctx);
+                        const isSameEnumMember = value.kind === "MemberExpr" && valueType.kind === "enum" && valueType.name === enumName;
+                        if (isSameEnumMember) {
+                            coveredEnumMembers.add(value.property);
+                        }
+                        else if (valueType.kind !== "unknown") {
+                            // valueType === "unknown" means checkExpression already
+                            // reported its own error (e.g. "Enum has no member X") —
+                            // don't pile a second, less specific one on top of it.
+                            this.reportInvalidMatchPattern(`match pattern must be a member of enum '${enumName}' (e.g. '${enumName}.SomeMember')`, value.line, value.col);
+                        }
+                    }
+                    else if (value.kind !== "StringLiteral") {
+                        this.reportInvalidMatchPattern(`match patterns must be string literals`, value.line, value.col);
                     }
                     else {
                         this.checkExpression(value, scope, ctx);
                     }
                 }
             }
-            // RegexPattern and WildcardPattern need no further checking here.
+            else if (arm.pattern.kind === "RegexPattern" && isEnumSubject) {
+                this.reportInvalidMatchPattern(`a regex pattern is not valid for a match over enum '${enumName}' — enum patterns must name a member`, arm.line, arm.col);
+            }
+            // WildcardPattern (and RegexPattern against a string subject) need no
+            // further checking here.
             const armResultType = this.checkExpression(arm.result, scope, ctx);
             if (resultType === null) {
                 resultType = armResultType;
@@ -2208,6 +2267,22 @@ export class Checker {
                 this.diagnostics.error("KS4089", `match arm result type '${T.typeToString(armResultType)}' does not match preceding arms' type '${T.typeToString(resultType)}'`, arm.line, arm.col);
             }
         }
+        if (isEnumSubject && enumName && !hasTrailingWildcard) {
+            const allMembers = [...(this.enums.get(enumName)?.members.keys() ?? [])];
+            const missing = allMembers.filter((m) => !coveredEnumMembers.has(m));
+            if (missing.length > 0) {
+                this.diagnostics.error("KS4105", `match over enum '${enumName}' is not exhaustive — missing case(s) for: ${missing.join(", ")} (add a case for each, or a trailing '_' arm)`, expr.line, expr.col);
+            }
+        }
         return resultType ?? T.UNKNOWN;
     }
+    // The one literal KS4088 emission site (three call sites in checkMatch
+    // route through it — see diagnostics.test.ts's "codes are unique across
+    // every emission site"): a match pattern that isn't valid for its
+    // subject's kind (not a string literal against a string subject, not a
+    // same-enum member reference against an enum subject, or a regex pattern
+    // against an enum subject at all).
+    reportInvalidMatchPattern(message, line, col) {
+        this.diagnostics.error("KS4088", message, line, col);
+    }
 }

package/dist/codegen.js

@@ -98,8 +98,27 @@ export class CodeGenerator {
     // `public` into scope without naming it explicitly. `sourceFileName`/
     // `sourceText` are for the emitted source map only (both optional so every
     // existing test call site keeps compiling unchanged).
-    generate(program, usingExports = new Map(), rawContents = new Map(), sourceFileName = "source.ks", sourceText = "") {
-        this.interfaceNames = new Set(program.statements.filter((s) => s.kind === "InterfaceDecl").map((s) => s.name));
+    generate(program, usingExports = new Map(), rawContents = new Map(), sourceFileName = "source.ks", sourceText = "", 
+    // Interface names visible via a `using` this module doesn't declare
+    // itself — separate from `usingExports` above, which deliberately
+    // excludes interfaces (they're compile-time only and never produce a
+    // JS import). Without this, a class implementing an interface declared
+    // in a DIFFERENT file (e.g. `class Component : Flushable` where
+    // `Flushable` lives in vdom.ks) has that interface name missing from
+    // `interfaceNames` entirely, so genClass's own "only a non-interface
+    // base list entry becomes `extends`" check can't tell it apart from a
+    // real (missing) superclass — it gets emitted as `extends Flushable`,
+    // a real runtime reference to a name nothing ever imports, throwing
+    // `ReferenceError: Flushable is not defined` the moment the class is
+    // ever loaded. Found for real building Kopular's own event-batching
+    // fix — the checker already resolves a cross-module interface's base
+    // list entry correctly (it type-checks fine); only codegen's own,
+    // separate, same-file-only interfaceNames set didn't know about it.
+    importedInterfaceNames = new Set()) {
+        this.interfaceNames = new Set([
+            ...program.statements.filter((s) => s.kind === "InterfaceDecl").map((s) => s.name),
+            ...importedInterfaceNames,
+        ]);
         this.outputLine = 1;
         const outFileName = sourceFileName.replace(/\.ks$/, ".js");
         this.sourceMap = new SourceMapBuilder(outFileName, sourceFileName, sourceText);

package/dist/modules.js

@@ -226,6 +226,13 @@ export function compileGraph(entryAbsPath, fileOverrides) {
     for (const absPath of order) {
         const mod = modules.get(absPath);
         const usingExports = new Map();
+        // Separate from usingExports (interfaces are excluded there — see its
+        // own comment below) — this is what tells codegen's own interfaceNames
+        // set about an interface declared in a DIFFERENT file this module
+        // `using`s, so a class implementing one doesn't get miscompiled into a
+        // real `extends <InterfaceName>` runtime reference (see
+        // CodeGenerator.generate's own comment on importedInterfaceNames).
+        const importedInterfaceNames = new Set();
         for (const u of mod.program.usings) {
             const depPath = resolve(dirname(absPath), u.path) + ".ks";
             const depExports = exportsByModule.get(depPath);
@@ -234,13 +241,17 @@ export function compileGraph(entryAbsPath, fileOverrides) {
                 // they'd make an invalid import specifier if listed here.
                 const importableTypeNames = [...depExports.namedTypes.entries()].filter(([, kind]) => kind !== "interface").map(([name]) => name);
                 usingExports.set(u.path, [...importableTypeNames, ...depExports.functions.keys(), ...depExports.externValues.keys()]);
+                for (const [name, kind] of depExports.namedTypes) {
+                    if (kind === "interface")
+                        importedInterfaceNames.add(name);
+                }
             }
         }
         // Just the basename, not a cwd-relative path — the .js.map file always
         // lands right next to its .ks/.js siblings (ks build writes output in
         // place), so "sources" has to resolve relative to *that* directory, not
         // wherever the compiler happened to be invoked from.
-        const { code, map } = new CodeGenerator().generate(mod.program, usingExports, rawContentsByModule.get(absPath) ?? new Map(), basename(absPath), mod.source);
+        const { code, map } = new CodeGenerator().generate(mod.program, usingExports, rawContentsByModule.get(absPath) ?? new Map(), basename(absPath), mod.source, importedInterfaceNames);
         outputs.set(absPath, code);
         sourceMaps.set(absPath, map);
     }

package/dist/parser.js

@@ -214,7 +214,7 @@ export class Parser {
             this.diagnostics.error("KS2006", "'async' cannot modify a variable declaration", start.line, start.col);
         }
         if (typeParams.length > 0) {
-            this.diagnostics.error("KS2023", "A type parameter list is only allowed on a function declaration", start.line, start.col);
+            this.reportStrayTypeParamList(start.line, start.col);
         }
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
@@ -503,16 +503,33 @@ export class Parser {
         }
         const type = this.parseType();
         const name = this.consume(TokenKind.Identifier, "Expected name").lexeme;
+        // `extern (T) => string? CombineValidators2<T>(...) from "...";` — same
+        // type-param-list-right-after-the-name shape a real generic free
+        // function uses (see parseDeclaration); harmless to try unconditionally
+        // here too, since parseTypeParamList consumes nothing when `<` isn't
+        // next.
+        const typeParams = this.parseTypeParamList();
         if (this.check(TokenKind.LParen)) {
             const params = this.parseParamList();
             const { modulePath, jsName } = this.parseExternTail(name);
             this.consume(TokenKind.Semicolon, "Expected ';' after extern function declaration");
-            return { kind: "ExternFunctionDecl", isExported, name, jsName, params, returnType: type, modulePath, line: start.line, col: start.col };
+            return { kind: "ExternFunctionDecl", isExported, name, typeParams, jsName, params, returnType: type, modulePath, line: start.line, col: start.col };
+        }
+        if (typeParams.length > 0) {
+            this.reportStrayTypeParamList(start.line, start.col);
         }
         const { modulePath, jsName } = this.parseExternTail(name);
         this.consume(TokenKind.Semicolon, "Expected ';' after extern declaration");
         return { kind: "ExternValueDecl", isExported, name, jsName, type, modulePath, line: start.line, col: start.col };
     }
+    // The one literal KS2023 emission site (both parseDeclaration's plain
+    // VarDecl case and parseExternDecl's ExternValueDecl case route through
+    // it — see diagnostics.test.ts's "codes are unique across every emission
+    // site"): a type-parameter list appeared somewhere only a function
+    // declaration (real or extern) may have one.
+    reportStrayTypeParamList(line, col) {
+        this.diagnostics.error("KS2023", "A type parameter list is only allowed on a function declaration", line, col);
+    }
     // Optional `from "<path>"` (omit for an ambient global) and optional
     // `as "<jsName>"` (omit when the JS-side name matches the KopScript-declared one).
     parseExternTail(defaultJsName) {

package/dist/printer.js

@@ -276,7 +276,8 @@ export class Printer {
         const prefix = decl.isExported ? "" : "private ";
         const as = decl.jsName !== decl.name ? ` as "${decl.jsName}"` : "";
         const from = decl.modulePath ? ` from "${decl.modulePath}"` : "";
-        return `${pad}${prefix}extern ${this.printType(decl.returnType)} ${decl.name}(${this.printParams(decl.params)})${from}${as};`;
+        const nameWithTypeParams = this.printTypeParamName(decl);
+        return `${pad}${prefix}extern ${this.printType(decl.returnType)} ${nameWithTypeParams}(${this.printParams(decl.params)})${from}${as};`;
     }
     printExternValue(decl, indent) {
         const pad = indentStr(indent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript, with generics and nullable types",
   "type": "module",
   "license": "MIT",