kopscript 0.19.0 → 0.20.0

package/LLM.md

@@ -23,9 +23,18 @@ ks build|check <file.ks> --json   # single JSON object on stdout instead of huma
 `--json` output shape (also what a tool/agent should parse instead of scraping text):
 
 ```json
-{ "success": false, "diagnostics": [{ "code": "KS4065", "severity": "error", "message": "...", "line": 2, "col": 14, "file": "/abs/path.ks" }], "written": [] }
+{ "success": false, "diagnostics": [{ "code": "KS4083", "severity": "error", "message": "Class 'Widget' has no member 'Vlaue'", "line": 3, "col": 13, "fix": "Did you mean 'Value'?", "file": "/abs/path.ks" }], "written": [] }
 ```
 
+`fix` is present only when the checker/parser found something concrete enough to say beyond
+the message itself — a real "did you mean 'X'?" against an actually-declared name close
+enough to be a plausible typo (unknown member/function/identifier/type — `KS4083`/`KS4062`/
+`KS4048`/`KS4008`/`KS4076`/`KS4077`), or a precise, always-accurate pointer for a handful of
+other high-frequency errors (a missing `await` on `KS4059`, `match` also accepting an enum
+subject on `KS4046`, a stray type-parameter list on `KS2023`, an invalid `match` pattern on
+`KS4088`). Absent entirely (no empty string) when nothing that specific applies — most
+diagnostics still don't have one, and that's expected, not a gap to fill in for every code.
+
 `written` is the absolute paths actually written (`build` only, and only on success — a
 failed `build` writes nothing; `.js.map` paths aren't listed separately, one is written next
 to each `.js` path in `written`). Exit code is `0` iff `success` is `true`. A missing entry

package/README.md

@@ -873,12 +873,20 @@ programmatically instead of scraping formatted text:
 {
   "success": false,
   "diagnostics": [
-    { "code": "KS4065", "severity": "error", "message": "Argument 2 has type 'string', expected 'number'", "line": 2, "col": 14, "file": "/abs/path/to/file.ks" }
+    { "code": "KS4083", "severity": "error", "message": "Class 'Widget' has no member 'Vlaue'", "line": 3, "col": 13, "fix": "Did you mean 'Value'?", "file": "/abs/path/to/file.ks" }
   ],
   "written": []
 }
 ```
 
+Some diagnostics also carry a `fix` field — a real "did you mean 'X'?" against something
+actually declared, for the unknown-member/function/identifier/type family of errors, or a
+precise next step for a handful of other common ones (a missing `await`, `match` also
+accepting an enum subject, a stray type-parameter list). Not every diagnostic has one —
+absent entirely, not an empty string, when nothing that specific applies — but where it's
+present, it's meant to be actionable directly, by a human or an AI agent, without needing to
+re-derive it from the message alone.
+
 `written` lists the absolute paths of every `.js` file actually written (always empty for
 `check`, and for `build` on failure — nothing is written unless the whole graph is
 error-free). A missing entry file reports `{ "success": false, "diagnostics": [],
@@ -890,9 +898,9 @@ Every diagnostic carries a stable `code` (`KS` + a number) alongside its human-r
 of parsing prose that can be reworded between versions. Codes are grouped by pipeline stage
 and never reused once assigned: `KS1xxx` lexer, `KS2xxx` parser, `KS3xxx` module/`using`
 resolution, `KS4xxx` the checker (by far the largest category — most real type errors live
-here), `KS5xxx` templates. There's no generated reference doc mapping every code to an
-explanation yet — for now, `message` is still the primary explanation; `code` is for
-matching, not (yet) for looking up docs.
+here), `KS5xxx` templates. There's still no generated reference doc mapping every code to an
+explanation — `message` (plus `fix`, when present — see above) is the explanation; `code` is
+for matching reliably across wording changes, not for looking up a separate page.
 
 **Source maps**: `build` writes a real source-map v3 `<file>.js.map` alongside every
 `<file>.js`, with the original `.ks` source embedded (`sourcesContent`) so a deployed app

package/dist/checker.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import { closestMatch } from "./suggest.js";
 import * as T from "./types.js";
 export function emptyModuleExports() {
     return { namedTypes: new Map(), classes: new Map(), interfaces: new Map(), enums: new Map(), functions: new Map(), externValues: new Map() };
@@ -40,6 +41,14 @@ class Scope {
     child() {
         return new Scope(this);
     }
+    // Every local/param name visible from here, walking up through every
+    // enclosing scope — used only to build "did you mean 'X'?" candidates for
+    // an undefined-identifier error (KS4048), never for real name resolution
+    // (resolve() above already does that correctly, including shadowing).
+    allNames() {
+        const own = [...this.vars.keys()];
+        return this.parent ? [...own, ...this.parent.allNames()] : own;
+    }
 }
 export class Checker {
     recordHover(line, col, text) {
@@ -389,7 +398,9 @@ export class Checker {
                 this.diagnostics.error("KS4007", `Generic type '${name}' requires ${this.describeArity(declaredParams)} (e.g. '${name}<${declaredParams.join(", ")}>')`, line, col);
             }
             else {
-                this.diagnostics.error("KS4008", `Unknown type '${name}'`, line, col);
+                const candidates = [...this.namedTypes.keys(), "number", "string", "bool", "void"];
+                const suggestion = closestMatch(name, candidates);
+                this.diagnostics.error("KS4008", `Unknown type '${name}'`, line, col, suggestion ? `Did you mean '${suggestion}'?` : undefined);
             }
             return T.UNKNOWN;
         }
@@ -1071,6 +1082,35 @@ export class Checker {
         }
         return null;
     }
+    // Every instance field/method name declared anywhere in className's own
+    // superclass chain — used only to build "did you mean 'X'?" candidates
+    // for an unknown-member error (KS4083), never for real member resolution
+    // (lookupField/lookupMethod above already do that correctly).
+    allInstanceMemberNames(className) {
+        const names = [];
+        let current = className;
+        while (current) {
+            const info = this.classes.get(current);
+            if (!info)
+                break;
+            names.push(...info.fields.keys(), ...info.methods.keys());
+            current = info.superclass;
+        }
+        return names;
+    }
+    // Same, for static members (KS4077's own candidates).
+    allStaticMemberNames(className) {
+        const names = [];
+        let current = className;
+        while (current) {
+            const info = this.classes.get(current);
+            if (!info)
+                break;
+            names.push(...info.staticFields.keys(), ...info.staticMethods.keys());
+            current = info.superclass;
+        }
+        return names;
+    }
     // Enforces C#-style private/protected/public access from the current class context.
     checkAccessibility(visibility, owner, ctx, memberName, line, col) {
         if (visibility === "public")
@@ -1384,7 +1424,14 @@ export class Checker {
     }
     expectType(actual, expected, line, col, context) {
         if (!T.typesEqual(actual, expected)) {
-            this.diagnostics.error("KS4046", `Expected type '${T.typeToString(expected)}' for ${context}, got '${T.typeToString(actual)}'`, line, col);
+            // The one context-specific hint worth giving here: a match subject
+            // that's neither string nor enum most likely means the author didn't
+            // know match accepts an enum too (see LLM.md's "match expression").
+            // Every OTHER expectType call site (if-condition, binary-op operand,
+            // ...) doesn't have an equally specific, generically-true next step,
+            // so it gets no fix rather than a vague one.
+            const fix = context === "match subject" ? `match also accepts an enum subject — see LLM.md's "match expression" section.` : undefined;
+            this.diagnostics.error("KS4046", `Expected type '${T.typeToString(expected)}' for ${context}, got '${T.typeToString(actual)}'`, line, col, fix);
         }
     }
     // Recognizes `name != null` / `name == null` (either operand order) as a
@@ -1478,7 +1525,23 @@ export class Checker {
                 const fnInfo = this.functions.get(expr.name);
                 if (fnInfo)
                     return T.functionType(fnInfo.params, fnInfo.returnType);
-                this.diagnostics.error("KS4048", `Undefined identifier '${expr.name}'`, expr.line, expr.col);
+                {
+                    const candidates = [...scope.allNames(), ...this.functions.keys(), ...this.externValues.keys()];
+                    const suggestion = closestMatch(expr.name, candidates);
+                    // No implicit `this` (see LLM.md's "Common mistakes") is a real,
+                    // common, PRECISELY detectable case of this exact error: the name
+                    // is undefined as a bare identifier, but it IS a real member of
+                    // the enclosing class — so it's always accurate to point at
+                    // `this.${name}`, never a guess the way the Levenshtein
+                    // suggestion above already handles unrelated-typo cases.
+                    const isOwnMember = ctx.currentClass ? this.allInstanceMemberNames(ctx.currentClass.name).includes(expr.name) : false;
+                    const fix = suggestion
+                        ? `Did you mean '${suggestion}'?`
+                        : isOwnMember
+                            ? `No implicit 'this' — did you mean 'this.${expr.name}'?`
+                            : undefined;
+                    this.diagnostics.error("KS4048", `Undefined identifier '${expr.name}'`, expr.line, expr.col, fix);
+                }
                 return T.UNKNOWN;
             }
             case "ThisExpr": {
@@ -1665,7 +1728,12 @@ export class Checker {
             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);
+            // A `task`-typed body where anything else was expected is very often
+            // a missing `await`, not a genuinely wrong return type — precise and
+            // always accurate to say so specifically, unlike a generic "check the
+            // types" hint that wouldn't be worth giving.
+            const fix = actual.kind === "task" ? "Did you forget 'await'?" : undefined;
+            this.diagnostics.error("KS4059", `Lambda body has type '${T.typeToString(actual)}', expected '${T.typeToString(expectedReturnType)}'`, expr.line, expr.col, fix);
         }
         return actual;
     }
@@ -1722,7 +1790,20 @@ export class Checker {
                     expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
                     return T.VOID;
                 }
-                this.diagnostics.error("KS4062", `Undefined function '${expr.callee.name}'`, expr.line, expr.col);
+                {
+                    // Same "no implicit this" mistake KS4048 checks for (see its own
+                    // comment) — `Increment()` inside a method never resolves to
+                    // `this.Increment()`, even when Increment really is a method on
+                    // the enclosing class.
+                    const isOwnMethod = ctx.currentClass ? this.allInstanceMemberNames(ctx.currentClass.name).includes(expr.callee.name) : false;
+                    const suggestion = isOwnMethod ? null : closestMatch(expr.callee.name, [...this.functions.keys()]);
+                    const fix = isOwnMethod
+                        ? `No implicit 'this' — did you mean 'this.${expr.callee.name}(...)'?`
+                        : suggestion
+                            ? `Did you mean '${suggestion}'?`
+                            : undefined;
+                    this.diagnostics.error("KS4062", `Undefined function '${expr.callee.name}'`, expr.line, expr.col, fix);
+                }
                 expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
                 return T.UNKNOWN;
             }
@@ -2054,7 +2135,8 @@ export class Checker {
                 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("KS4076", `Enum '${objName}' has no member '${expr.property}'`, expr.line, expr.col);
+                    const suggestion = closestMatch(expr.property, [...enumInfo.members.keys()]);
+                    this.diagnostics.error("KS4076", `Enum '${objName}' has no member '${expr.property}'`, expr.line, expr.col, suggestion ? `Did you mean '${objName}.${suggestion}'?` : undefined);
                     return { type: T.UNKNOWN, methodInfo: null };
                 }
                 return { type: T.enumType(objName), methodInfo: null };
@@ -2071,7 +2153,10 @@ export class Checker {
                     this.checkAccessibility(method.info.visibility, method.owner, ctx, expr.property, expr.line, expr.col);
                     return { type: method.info.returnType, methodInfo: method.info };
                 }
-                this.diagnostics.error("KS4077", `Class '${objName}' has no static member '${expr.property}'`, expr.line, expr.col);
+                {
+                    const suggestion = closestMatch(expr.property, this.allStaticMemberNames(objName));
+                    this.diagnostics.error("KS4077", `Class '${objName}' has no static member '${expr.property}'`, expr.line, expr.col, suggestion ? `Did you mean '${objName}.${suggestion}'?` : undefined);
+                }
                 return { type: T.UNKNOWN, methodInfo: null };
             }
         }
@@ -2159,7 +2244,12 @@ export class Checker {
                 };
                 return { type: info.returnType, methodInfo: info };
             }
-            this.diagnostics.error("KS4083", `Class '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
+            {
+                const suggestion = closestMatch(expr.property, this.allInstanceMemberNames(objectType.name));
+                this.diagnostics.error("KS4083", `Class '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col, suggestion
+                    ? `Did you mean '${suggestion}'?`
+                    : `No similar member found on '${objectType.name}' — if this should exist, check its class (or extern binding, if '${objectType.name}' describes external JS) actually declares it.`);
+            }
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "interface") {
@@ -2243,11 +2333,11 @@ export class Checker {
                             // 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);
+                            this.reportInvalidMatchPattern(`match pattern must be a member of enum '${enumName}' (e.g. '${enumName}.SomeMember')`, value.line, value.col, `See LLM.md's "match expression" section for enum-pattern syntax.`);
                         }
                     }
                     else if (value.kind !== "StringLiteral") {
-                        this.reportInvalidMatchPattern(`match patterns must be string literals`, value.line, value.col);
+                        this.reportInvalidMatchPattern(`match patterns must be string literals`, value.line, value.col, `A non-string, non-enum match subject isn't supported at all — see LLM.md's "match expression" section.`);
                     }
                     else {
                         this.checkExpression(value, scope, ctx);
@@ -2255,7 +2345,7 @@ export class Checker {
                 }
             }
             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);
+                this.reportInvalidMatchPattern(`a regex pattern is not valid for a match over enum '${enumName}' — enum patterns must name a member`, arm.line, arm.col, `Use '${enumName}.SomeMember' patterns instead — see LLM.md's "match expression" section.`);
             }
             // WildcardPattern (and RegexPattern against a string subject) need no
             // further checking here.
@@ -2282,7 +2372,7 @@ export class Checker {
     // 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);
+    reportInvalidMatchPattern(message, line, col, fix) {
+        this.diagnostics.error("KS4088", message, line, col, fix);
     }
 }

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/diagnostics.js

@@ -2,11 +2,11 @@ export class DiagnosticBag {
     constructor() {
         this.diagnostics = [];
     }
-    error(code, message, line, col) {
-        this.diagnostics.push({ code, severity: "error", message, line, col });
+    error(code, message, line, col, fix) {
+        this.diagnostics.push({ code, severity: "error", message, line, col, ...(fix ? { fix } : {}) });
     }
-    warning(code, message, line, col) {
-        this.diagnostics.push({ code, severity: "warning", message, line, col });
+    warning(code, message, line, col, fix) {
+        this.diagnostics.push({ code, severity: "warning", message, line, col, ...(fix ? { fix } : {}) });
     }
     get hasErrors() {
         return this.diagnostics.some((d) => d.severity === "error");
@@ -17,10 +17,19 @@ export class DiagnosticBag {
             .map((d) => {
             const sourceLine = lines[d.line - 1] ?? "";
             const pointer = " ".repeat(Math.max(0, d.col - 1)) + "^";
+            const fixLine = d.fix ? `\n  fix: ${d.fix}` : "";
             return (`${fileName}:${d.line}:${d.col} - ${d.severity} ${d.code}: ${d.message}\n` +
                 `  ${sourceLine}\n` +
-                `  ${pointer}`);
+                `  ${pointer}${fixLine}`);
         })
             .join("\n\n");
     }
+    // Machine-readable form of the exact same diagnostics format() prints —
+    // for a caller that wants to act on a compile error programmatically
+    // (an editor extension, a CI check, an AI coding agent) instead of
+    // scraping formatted text. `fileName` matches format()'s own parameter so
+    // both outputs agree on what file each diagnostic is attributed to.
+    toJSON(fileName) {
+        return { file: fileName, diagnostics: this.diagnostics };
+    }
 }

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

@@ -528,7 +528,7 @@ export class Parser {
     // 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);
+        this.diagnostics.error("KS2023", "A type parameter list is only allowed on a function declaration", line, col, "Remove the type parameter list here, or add '(...)' parameters if this was meant to be a function — a variable (real or extern) can never have its own type parameters, only a function (real or extern) or a class/interface can.");
     }
     // Optional `from "<path>"` (omit for an ambient global) and optional
     // `as "<jsName>"` (omit when the JS-side name matches the KopScript-declared one).

package/dist/suggest.js

@@ -0,0 +1,44 @@
+// Plain edit-distance "did you mean X?" suggestion — used by the checker
+// wherever a name doesn't resolve (an unknown member, function, identifier,
+// or type name) to point at the closest ACTUALLY-DECLARED name, when one is
+// close enough to plausibly be a typo. Deliberately generic (no knowledge
+// of what kind of name it's comparing — member, function, type, whatever
+// the caller passes as `candidates`), so every "unknown X" diagnostic can
+// reuse the exact same logic instead of each hand-rolling its own.
+function levenshteinDistance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const dp = Array.from({ length: rows }, () => new Array(cols).fill(0));
+    for (let i = 0; i < rows; i++)
+        dp[i][0] = i;
+    for (let j = 0; j < cols; j++)
+        dp[0][j] = j;
+    for (let i = 1; i < rows; i++) {
+        for (let j = 1; j < cols; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[a.length][b.length];
+}
+// Returns the closest of `candidates` to `target`, or null if nothing is
+// close enough to be worth suggesting (a totally unrelated name is worse
+// than no suggestion at all — e.g. suggesting 'value' isn't found via
+// "close typo of an existing member" reasoning if the member genuinely
+// doesn't exist anywhere close). The threshold scales with the target's own
+// length: a short name needs a near-exact match, a long one tolerates
+// proportionally more difference.
+export function closestMatch(target, candidates) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const candidate of candidates) {
+        if (candidate === target)
+            continue; // never suggest the name itself
+        const distance = levenshteinDistance(target, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    const threshold = Math.max(2, Math.ceil(target.length / 3));
+    return best !== null && bestDistance <= threshold ? best : null;
+}

package/package.json

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