kopscript 0.14.0 → 0.15.0

package/LLM.md

@@ -75,9 +75,10 @@ below). No circular `using` (compile error).
 **Does not exist**: `any`/`unknown` as a writable annotation, a `let`/`var` keyword (see
 Declarations below — there isn't one), type inference for declarations (every
 local/`const`/param/field/return type is written out explicitly), union types, tuples,
-structural/duck typing (all typing is nominal). Generics exist but are deliberately
-scoped down — see the Generics section for exactly what's NOT supported there (multiple
-type parameters, constraints, generic functions, generic inheritance).
+structural/duck typing (all typing is nominal). Generics exist and cover multiple type
+parameters, single-interface constraints, generic inheritance, and free generic functions
+— see the Generics section for exactly what's still NOT supported there (variance,
+multiple constraints per parameter, generic methods).
 
 ## Declarations
 
@@ -366,10 +367,30 @@ implemented/extended interface — never more than one) — `class Foo<T> : Box<
 IContainer<T>` is a compile error ("has more than one generic entry in its base list") even
 though either half alone would work.
 
+**Generic functions**: only free/top-level functions, never a method inside a class (a
+method still only ever uses its enclosing class's own type parameters):
+```ks
+T Identity<T>(T x) { return x; }
+number n = Identity(5);       // T inferred as number, from the argument
+string s = Identity("hi");    // T inferred as string, independently
+```
+**No explicit type argument at a call site** — `Identity<number>(5)` isn't valid syntax;
+`T` is always inferred from the actual argument types by structurally unifying each
+declared (possibly abstract) parameter type against its argument's real type — including
+through a nested generic type (`T Unwrap<T>(Box<T> b)` infers `T` from `Box<number>`) or a
+lambda argument's own explicit parameter type (`void UseCallback<T>((T) => void cb)` infers
+`T` from `(number n) => ...`). This is a real grammar constraint, not a missing feature:
+`new Box<number>(...)` disambiguates `<` from a comparison only because `new` is a distinct
+keyword context — a bare call has no such anchor, so `f<T>(x)` would be genuinely ambiguous
+with a chained `<`/`>` comparison. If no argument determines a declared type parameter, or
+two arguments would bind it to conflicting types, that's a compile error naming the
+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.
+
 **Does not exist (v1 scope cuts, each deliberate)**:
-- **Generic functions.** `T Identity<T>(T x)` doesn't parse — only classes and interfaces
-  take type parameters, not free functions/methods themselves (a method *inside* a
-  generic class can use that class's own type parameters freely, same as any other member).
+- **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).
 - **Variance.** No `out`/`in`/covariance/contravariance — see invariance above.
 
 ## Nullable types — `T?`
@@ -541,10 +562,11 @@ Locals/params: **camelCase**. This is convention, not enforced by the compiler.
 
 ## Does not exist (don't reach for these)
 
-Generics beyond one or more type parameters (each with at most one interface constraint)
-and single-generic-base inheritance (no `T : IFoo, IBar` multi-constraints, no generic
-functions, no variance, no more than one generic entry per base list — see Generics above
-for what *is* supported) · `any`/`unknown` annotations ·
+Generics beyond one or more type parameters (each with at most one interface constraint),
+single-generic-base inheritance, and free (never method-level) generic functions with
+inference-only call sites (no `T : IFoo, IBar` multi-constraints, no explicit
+`Identity<number>(5)` type arguments, no variance, no more than one generic entry per base
+list — see Generics above for what *is* supported) · `any`/`unknown` annotations ·
 a `let`/`var` keyword (locals are just `Type name = value;`) · decorators/annotations ·
 reflection · type inference on declarations · ternary expression · union/tuple types ·
 **object-literal syntax** (`{ key: value }` as a value — this doesn't exist *anywhere* in
@@ -579,9 +601,12 @@ Real, observed cases where a plausible-looking guess was wrong — not hypotheti
   dedicated rewriter, `qualifyThis`, specifically because this isn't automatic.)
 - **No `let`/`var`, ever.** Every local is `Type name = value;` — writing `let x = 5;` or a
   bare `const x = 5;` (missing the type) is a parse error, not a lenient inferred form.
-- **No generic functions.** `T Identity<T>(T x) { return x; }` doesn't parse — only classes
-  and interfaces take `<T>`. Don't reach for this even though every mainstream generic
-  language supports it.
+- **No explicit type argument at a generic function call site.** `Identity<number>(5)`
+  doesn't parse — a bare call has no keyword like `new` to disambiguate `<` from a
+  comparison, so type arguments are always inferred from the actual arguments instead.
+  Just call `Identity(5)`; if inference can't determine a type parameter, restructure the
+  call (e.g. an argument that actually mentions the type) rather than reaching for explicit
+  syntax that isn't there.
 - **Early-return doesn't narrow a nullable type.** `if (x == null) { return; } print(x.Length);`
   still errors on `x.Length` — narrowing is scope-based (an `if`/`else` block), not
   control-flow/reachability-based. Wrap the rest of the logic in the `if (x != null) { ... }`

package/README.md

@@ -22,11 +22,11 @@ LLM's context, as opposed to this README's narrative explanation.
   explicit `virtual`/`override` dispatch (methods are sealed unless marked `virtual`), and a full
   `public`/`protected`/`private` access model enforced at compile time.
 - **Strongly typed**: every declaration is explicitly typed and checked at compile time.
-- **Generics**: one or more invariant type parameters on classes and interfaces
-  (`class Box<T> { public T Value; }`, `class Pair<K, V> { ... }`), each optionally
-  constrained to an interface (`class Box<T : IComparable> { ... }`), plus generic
-  inheritance (`class IntBox : Box<number> { }`) — erased at codegen with zero runtime
-  cost, the same way `task<T>`/`state<T>` already are.
+- **Generics**: one or more invariant type parameters on classes, interfaces, and free
+  functions (`class Box<T> { public T Value; }`, `T Identity<T>(T x) { return x; }`), each
+  optionally constrained to an interface (`class Box<T : IComparable> { ... }`), plus
+  generic inheritance (`class IntBox : Box<number> { }`) — erased at codegen with zero
+  runtime cost, the same way `task<T>`/`state<T>` already are.
 - **Nullable types with compiler-enforced null-checking**: `T?` (`string?`, `Dog?`,
   `number[]?`) — a `T?` can't be used where a `T` is expected without an `if (x != null)`
   check first (checked statically, not just at runtime), and comparing a value that can
@@ -258,9 +258,6 @@ inside v1:
 - **Invariant.** `Box<Dog>` is **not** assignable to `Box<Animal>` even though `Dog :
   Animal`, and `Pair<number, string>` is not assignable to `Pair<string, number>` — every
   slot must match exactly, in order.
-- **No generic functions.** `T Identity<T>(T x)` isn't supported — only classes and
-  interfaces take type parameters. A method *inside* a generic class can still use that
-  class's own type parameters freely; it's just not introducing one of its own.
 
 By default a type parameter is fully unconstrained, so you can't call any member on a bare
 `T`/`K`/`V` value inside the generic class's own body — the same restriction C#/Java/
@@ -299,6 +296,24 @@ down. **v1 limit**: at most one generic entry across a whole base list (the supe
 one implemented interface — not several at once) — `class Foo<T> : Box<T>, IContainer<T>`
 is a compile error even though each half would work alone.
 
+**Free functions can be generic too** — only free/top-level functions, not class methods
+(a method inside a class still only uses its enclosing class's own type parameters, never
+introduces a new one):
+
+```ks
+T Identity<T>(T x) { return x; }
+number n = Identity(5);       // T = number, inferred from the argument
+string s = Identity("hi");    // T = string, independently
+```
+
+**No explicit type argument at the call site** — `Identity<number>(5)` isn't valid syntax;
+`T` is always inferred from the actual argument types. This is a real grammar constraint,
+not a missing feature: `new Box<number>(...)` can disambiguate `<` from a comparison only
+because `new` is a distinct keyword context — a bare call has no such anchor, so
+`f<T>(x)` would be genuinely ambiguous with a chained `<`/`>` comparison. If inference
+can't pin down a type parameter from the arguments given, that's a compile error naming the
+unresolved parameter, not a syntax feature to reach for.
+
 See `LLM.md`'s "Generics" section for the exhaustive rules if you're generating code
 against this — nested generics (`Box<Box<number>>`, `Box<number>?[]`, `Pair<number,
 Pair<string, bool>>`) and generic interfaces used as standalone parameter types both work
@@ -892,13 +907,13 @@ into your extensions folder).
 
 ## Status
 
-This is a v1 / hobby-project scope. Nullable types (`T?`) and generics (a single
-unconstrained, invariant type parameter on classes/interfaces) have both shipped — see
-above for both. What generics deliberately doesn't cover: multiple type parameters
-(`Map<K, V>`), constraints (`T : IFoo`), generic functions, generic inheritance, and
-variance — each a real, separable extension rather than a v1 oversight. Also not yet
-supported: static auto-properties, interface properties (methods only), and nested
-functions/classes.
+This is a v1 / hobby-project scope. Nullable types (`T?`) and generics (multiple type
+parameters, single-interface constraints, generic inheritance, and free generic functions)
+have all shipped — see above for the full "Generics" section. What generics still
+deliberately doesn't cover: variance, multiple constraints per parameter, generic methods
+(only free functions), and more than one generic entry per base list — each a real,
+separable extension rather than a v1 oversight. Also not yet supported: static
+auto-properties, interface properties (methods only), and nested functions/classes.
 
 `async`/`await`, `task<T>`, and `try`/`catch`/`finally`/`throw` are now in place (see the
 language tour above) — the ceiling that's left is what's *inside* those: no async lambdas,

package/dist/checker.js

@@ -194,7 +194,12 @@ 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: [],
             params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
             returnType: this.resolveType(decl.returnType, decl.line, decl.col),
         });
@@ -504,6 +509,68 @@ export class Checker {
                 return type;
         }
     }
+    // The reverse of substituteTypeParams: derives bindings *from* matching a
+    // generic function's declared (abstract) parameter type against one real
+    // argument's actual (concrete) type, instead of substituting bindings
+    // *into* a type. Structural unification, same recursive shape as
+    // substituteTypeParams/typesEqual — whenever `declared` is a TypeParamType
+    // for one of `typeParamNames`, records `bindings.set(name, actual)` the
+    // first time it's seen; a later argument that would bind the same name to
+    // a genuinely different type is recorded in `conflicts` instead of
+    // silently overwriting (see checkGenericFunctionCall's own error for
+    // that). A structural mismatch elsewhere (e.g. declared is `T[]` but
+    // actual isn't an array at all) simply infers nothing from that
+    // position — the normal post-substitution assignability check catches
+    // the real type error afterward, with a clearer message than unification
+    // failing silently here would give.
+    inferTypeParamBindings(declared, actual, typeParamNames, bindings, conflicts) {
+        if (declared.kind === "typeParam" && typeParamNames.has(declared.name)) {
+            const existing = bindings.get(declared.name);
+            if (existing) {
+                if (!T.typesEqual(existing, actual))
+                    conflicts.set(declared.name, actual);
+            }
+            else {
+                bindings.set(declared.name, actual);
+            }
+            return;
+        }
+        if (declared.kind === "array" && actual.kind === "array") {
+            this.inferTypeParamBindings(declared.element, actual.element, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "nullable") {
+            const actualInner = actual.kind === "nullable" ? actual.inner : actual;
+            this.inferTypeParamBindings(declared.inner, actualInner, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "task" && actual.kind === "task") {
+            this.inferTypeParamBindings(declared.resultType, actual.resultType, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if (declared.kind === "state" && actual.kind === "state") {
+            this.inferTypeParamBindings(declared.valueType, actual.valueType, typeParamNames, bindings, conflicts);
+            return;
+        }
+        if ((declared.kind === "class" || declared.kind === "interface") && declared.kind === actual.kind && declared.name === actual.name) {
+            const declaredArgs = declared.typeArgs ?? [];
+            const actualArgs = actual.typeArgs ?? [];
+            declaredArgs.forEach((d, i) => {
+                if (actualArgs[i])
+                    this.inferTypeParamBindings(d, actualArgs[i], typeParamNames, bindings, conflicts);
+            });
+            return;
+        }
+        if (declared.kind === "function" && actual.kind === "function") {
+            declared.params.forEach((d, i) => {
+                if (actual.params[i])
+                    this.inferTypeParamBindings(d, actual.params[i], typeParamNames, bindings, conflicts);
+            });
+            this.inferTypeParamBindings(declared.returnType, actual.returnType, typeParamNames, bindings, conflicts);
+        }
+        // Anything else (primitive/enum/void/unknown, or a structural
+        // mismatch) has nothing to unify — no-op.
+    }
     // Builds the bindings map for a generic reference (a `ClassType`/
     // `InterfaceType`'s own `typeArgs`, zipped against its declared
     // `typeParams`) — the "own bindings" every member-lookup/conformance
@@ -879,10 +946,18 @@ export class Checker {
         }
     }
     registerFunction(decl) {
-        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)}`);
+        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,
+        });
+        const nameWithTypeParam = decl.typeParams.length > 0 ? `${decl.name}<${decl.typeParams.map((p) => p.name).join(", ")}>` : decl.name;
+        this.recordHover(decl.line, decl.col, `function ${nameWithTypeParam}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
     }
     isSubclass(sub, sup) {
         let current = sub;
@@ -1082,11 +1157,17 @@ export class Checker {
         this.checkStatement(stmt, scope, { returnType: T.VOID, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: true });
     }
     checkFunctionBody(decl, parentScope) {
-        const info = this.functions.get(decl.name);
-        const scope = parentScope.child();
-        decl.params.forEach((p, i) => scope.declare(p.name, info.params[i], false));
-        const returnType = this.resolveBodyReturnType(info.returnType, decl.isAsync, decl.line, decl.col);
-        this.checkBlock(decl.body, scope, { returnType, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: decl.isAsync });
+        // Same withTypeParamsInScope treatment checkClassBody gives a generic
+        // class's own method bodies — without it, a generic function's type
+        // parameter would resolve in its declared signature but not inside a
+        // local declaration/lambda written in its own body.
+        this.withTypeParamsInScope(decl.typeParams, () => {
+            const info = this.functions.get(decl.name);
+            const scope = parentScope.child();
+            decl.params.forEach((p, i) => scope.declare(p.name, info.params[i], false));
+            const returnType = this.resolveBodyReturnType(info.returnType, decl.isAsync, decl.line, decl.col);
+            this.checkBlock(decl.body, scope, { returnType, currentClass: null, inConstructor: false, loopDepth: 0, isAsync: decl.isAsync });
+        });
     }
     checkClassBody(decl) {
         // Constructor/method *bodies* run in this same scope registerClass used
@@ -1626,6 +1707,9 @@ export class Checker {
                 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)}`);
+            if (info.typeParams.length > 0) {
+                return this.checkGenericFunctionCall(expr, expr.callee.name, info, scope, ctx);
+            }
             this.checkArgs(expr, info.params, scope, ctx);
             return info.returnType;
         }
@@ -1678,6 +1762,50 @@ export class Checker {
             }
         });
     }
+    // A generic function call has no explicit type-argument syntax (see
+    // README's "Generics" — a real grammar-ambiguity reason, `f<T>(x)` is
+    // indistinguishable from a chained comparison with no keyword like `new`
+    // to disambiguate it), so every type parameter is inferred from the
+    // actual argument types instead. Checks argument count first (an arity
+    // mismatch would make inference itself meaningless), infers bindings by
+    // unifying each declared (abstract) parameter type against its actual
+    // argument's real type (see inferTypeParamBindings), then re-runs the
+    // normal assignability check with the now-concrete substituted parameter
+    // types — catching anything structural unification alone wouldn't (e.g.
+    // an argument assignable to, but not identical to, its inferred slot).
+    checkGenericFunctionCall(expr, functionName, info, scope, ctx) {
+        if (expr.args.length !== info.params.length) {
+            this.diagnostics.error("KS4098", `Expected ${info.params.length} argument(s), got ${expr.args.length}`, expr.line, expr.col);
+            expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
+            return T.UNKNOWN;
+        }
+        const actualArgTypes = expr.args.map((a) => this.checkExpression(a, scope, ctx));
+        const typeParamNames = new Set(info.typeParams);
+        const bindings = new Map();
+        const conflicts = new Map();
+        info.params.forEach((declared, i) => this.inferTypeParamBindings(declared, actualArgTypes[i], typeParamNames, bindings, conflicts));
+        for (const [name, conflictingType] of conflicts) {
+            this.diagnostics.error("KS4099", `Type parameter '${name}' inferred as both '${T.typeToString(bindings.get(name))}' and '${T.typeToString(conflictingType)}' from different arguments — conflicting types`, expr.line, expr.col);
+        }
+        const unresolved = info.typeParams.filter((name) => !bindings.has(name));
+        if (unresolved.length > 0) {
+            this.diagnostics.error("KS4100", `Cannot infer type parameter${unresolved.length === 1 ? "" : "s"} '${unresolved.join("', '")}' for '${functionName}' — no argument determines ${unresolved.length === 1 ? "it" : "them"}`, expr.line, expr.col);
+            return T.UNKNOWN;
+        }
+        info.typeParams.forEach((name, i) => {
+            const constraint = info.typeParamConstraints[i];
+            if (constraint)
+                this.checkConstraintSatisfied(bindings.get(name), constraint, name, expr.line, expr.col);
+        });
+        const substitutedParams = info.params.map((p) => this.substituteTypeParams(p, bindings));
+        expr.args.forEach((arg, i) => {
+            const expected = substitutedParams[i];
+            if (!this.isAssignableType(actualArgTypes[i], expected)) {
+                this.diagnostics.error("KS4101", `Argument ${i + 1} has type '${T.typeToString(actualArgTypes[i])}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
+            }
+        });
+        return this.substituteTypeParams(info.returnType, bindings);
+    }
     checkNew(expr, scope, ctx) {
         if (this.interfaces.has(expr.className)) {
             this.diagnostics.error("KS4066", `Cannot instantiate interface '${expr.className}'`, expr.line, expr.col);

package/dist/parser.js

@@ -198,14 +198,24 @@ export class Parser {
         const type = this.parseType();
         const nameTok = this.consume(TokenKind.Identifier, "Expected name");
         const name = nameTok.lexeme;
+        // `T Identity<T>(T x) { ... }` — a free function's own type-param list,
+        // between its name and `(`. Only meaningful for the function branch
+        // below; a local/top-level variable declaration never has `<` right
+        // after its name, so trying this first costs nothing in that case
+        // (parseTypeParamList returns immediately without consuming anything
+        // when `<` isn't there).
+        const typeParams = this.parseTypeParamList();
         if (this.check(TokenKind.LParen)) {
             const params = this.parseParamList();
             const body = this.parseBlock();
-            return { kind: "FunctionDecl", isExported, isAsync, name, params, returnType: type, body, line: start.line, col: start.col };
+            return { kind: "FunctionDecl", isExported, isAsync, name, typeParams, params, returnType: type, body, line: start.line, col: start.col };
         }
         if (isAsync) {
             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.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
         this.consume(TokenKind.Semicolon, "Expected ';' after variable declaration");

package/dist/printer.js

@@ -208,7 +208,8 @@ export class Printer {
     printFunction(decl, indent) {
         const pad = indentStr(indent);
         const prefix = `${decl.isExported ? "" : "private "}${decl.isAsync ? "async " : ""}`;
-        return `${pad}${prefix}${this.printType(decl.returnType)} ${decl.name}(${this.printParams(decl.params)}) ${this.printBlock(decl.body, indent).trimStart()}`;
+        const nameWithTypeParam = this.printTypeParamName(decl);
+        return `${pad}${prefix}${this.printType(decl.returnType)} ${nameWithTypeParam}(${this.printParams(decl.params)}) ${this.printBlock(decl.body, indent).trimStart()}`;
     }
     // Canonical member order: fields, then properties, then the constructor,
     // then methods — regardless of how the original source interleaved them.

package/package.json

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