kopscript 0.7.1 → 0.8.0

package/LLM.md

@@ -21,7 +21,7 @@ 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": [{ "severity": "error", "message": "...", "line": 2, "col": 14, "file": "/abs/path.ks" }], "written": [] }
+{ "success": false, "diagnostics": [{ "code": "KS4065", "severity": "error", "message": "...", "line": 2, "col": 14, "file": "/abs/path.ks" }], "written": [] }
 ```
 
 `written` is the absolute paths actually written (`build` only, and only on success — a
@@ -504,9 +504,48 @@ signature, use different names, not overloading. (Nested function/class/interfac
 declarations, by contrast, *are* a clean compile error: "Nested ... declarations are not
 supported".)
 
+## Common mistakes (seeded from real generation failures)
+
+Real, observed cases where a plausible-looking guess was wrong — not hypothetical gotchas:
+
+- **No implicit `this`.** Every reference to a member of the enclosing class — a field, a
+  property, a method call — must be `this.X`, always, everywhere, including inside a lambda.
+  `Increment()` inside a method body does **not** resolve to `this.Increment()` the way it
+  would in Java/C#/Python; it's an undefined-identifier error unless `Increment` is a real
+  free function. (Discovered building the template compiler above — templates need a
+  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.
+- **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) { ... }`
+  block instead of guard-clause-and-continue.
+- **Never write `async` on an `extern` signature.** `async task<string> text();` inside an
+  `extern class` is a parse error — declare the return type as `task<string> text();`
+  directly; `async` only means something for a body the checker validates, and an `extern`
+  signature has no body.
+- **No object-literal syntax, anywhere, ever.** Reaching for `{ method: "POST", body: x }` to
+  call a JS API that expects one (a `fetch`-style options argument) doesn't compile — there's
+  no way to construct that value in KopScript at all. See the `extern`/`raw string` sections
+  above and Kopular's `http_runtime.js` for the actual workaround (a small hand-written JS
+  shim), not a language feature to reach for.
+- **No ternary expression.** `cond ? a : b` doesn't parse. Use `match` on a `bool`, or an
+  `if`/`else` assigning to a local declared above it.
+- **Two methods with the same name in one class don't error** — the second silently replaces
+  the first (see "Sharp edge" above). If a generated program seems to call the wrong
+  implementation of something, check for an accidental duplicate name before assuming a
+  compiler bug.
+
 ## Diagnostics
 
-Every compiler error/warning is `{ severity, message, line, col }` (1-based). CLI output
-format: `` file:line:col - severity: message `` plus a source line and a `^` pointer.
-`DiagnosticBag.hasErrors` gates whether codegen runs at all — a program with any error
-produces no output.
+Every compiler error/warning is `{ code, severity, message, line, col }` (1-based).
+`code` is `KS` + a number, stable across compiler versions even when `message`'s wording
+changes — match on `code` in tooling, not on `message` text. Ranges by pipeline stage,
+never reused once assigned: `KS1xxx` lexer, `KS2xxx` parser, `KS3xxx` module/`using`
+resolution, `KS4xxx` checker (the large majority of real errors), `KS5xxx` templates.
+CLI output format: `` file:line:col - severity code: message `` plus a source line and a
+`^` pointer. `DiagnosticBag.hasErrors` gates whether codegen runs at all — a program with
+any error produces no output.

package/README.md

@@ -755,7 +755,7 @@ programmatically instead of scraping formatted text:
 {
   "success": false,
   "diagnostics": [
-    { "severity": "error", "message": "Argument 2 has type 'string', expected 'number'", "line": 2, "col": 14, "file": "/abs/path/to/file.ks" }
+    { "code": "KS4065", "severity": "error", "message": "Argument 2 has type 'string', expected 'number'", "line": 2, "col": 14, "file": "/abs/path/to/file.ks" }
   ],
   "written": []
 }
@@ -767,6 +767,15 @@ error-free). A missing entry file reports `{ "success": false, "diagnostics": []
 "written": [], "error": "cannot find file '...'" }` instead of throwing. Exit code is 0
 exactly when `success` is `true`, both with and without `--json`.
 
+Every diagnostic carries a stable `code` (`KS` + a number) alongside its human-readable
+`message` — meant for a tool/agent to pattern-match reliably (`code === "KS4065"`) instead
+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.
+
 During development, use `npm run ks -- <build|run|watch|check> <file.ks>` (backed by
 `tsx`), or run `npm run build` to compile the TypeScript compiler itself to `dist/` and
 use `node dist/cli.js` directly.

package/dist/checker.js

@@ -221,7 +221,7 @@ export class Checker {
         this.externValues.set(decl.name, T.STRING);
         const resolvedPath = resolve(dirname(this.currentFilePath), decl.path);
         if (!existsSync(resolvedPath)) {
-            this.diagnostics.error(`Cannot find file '${decl.path}' referenced by 'raw string ${decl.name}' (looked for '${resolvedPath}')`, decl.line, decl.col);
+            this.diagnostics.error("KS4001", `Cannot find file '${decl.path}' referenced by 'raw string ${decl.name}' (looked for '${resolvedPath}')`, decl.line, decl.col);
             return;
         }
         this.rawContents.set(decl.name, readFileSync(resolvedPath, "utf-8"));
@@ -272,10 +272,10 @@ export class Checker {
         const seen = new Map();
         const declare = (name, line, col) => {
             if (this.importedNames.has(name)) {
-                this.diagnostics.error(`Declaration '${name}' conflicts with a name brought in by 'using'`, line, col);
+                this.diagnostics.error("KS4002", `Declaration '${name}' conflicts with a name brought in by 'using'`, line, col);
             }
             else if (seen.has(name)) {
-                this.diagnostics.error(`Duplicate top-level declaration '${name}'`, line, col);
+                this.diagnostics.error("KS4003", `Duplicate top-level declaration '${name}'`, line, col);
             }
             seen.set(name, true);
         };
@@ -305,11 +305,11 @@ export class Checker {
             return;
         const info = this.classes.get(decl.name);
         if (info.superclass && !this.isExportedName(info.superclass)) {
-            this.diagnostics.error(`Exported class '${decl.name}' has a base class '${info.superclass}' that isn't exported`, decl.line, decl.col);
+            this.diagnostics.error("KS4004", `Exported class '${decl.name}' has a base class '${info.superclass}' that isn't exported`, decl.line, decl.col);
         }
         for (const ifaceName of info.interfaces) {
             if (!this.isExportedName(ifaceName)) {
-                this.diagnostics.error(`Exported class '${decl.name}' implements interface '${ifaceName}', which isn't exported`, decl.line, decl.col);
+                this.diagnostics.error("KS4005", `Exported class '${decl.name}' implements interface '${ifaceName}', which isn't exported`, decl.line, decl.col);
             }
         }
     }
@@ -321,7 +321,7 @@ export class Checker {
             return;
         for (const baseName of info.bases) {
             if (!this.isExportedName(baseName)) {
-                this.diagnostics.error(`Exported interface '${decl.name}' extends interface '${baseName}', which isn't exported`, decl.line, decl.col);
+                this.diagnostics.error("KS4006", `Exported interface '${decl.name}' extends interface '${baseName}', which isn't exported`, decl.line, decl.col);
             }
         }
     }
@@ -342,10 +342,10 @@ export class Checker {
         if (!resolved) {
             const name = node.kind === "NamedType" ? node.name : "[]";
             if (name !== "[]" && this.genericTypeParams.has(name) && !node.typeArgs) {
-                this.diagnostics.error(`Generic type '${name}' requires a type argument (e.g. '${name}<T>')`, line, col);
+                this.diagnostics.error("KS4007", `Generic type '${name}' requires a type argument (e.g. '${name}<T>')`, line, col);
             }
             else {
-                this.diagnostics.error(`Unknown type '${name}'`, line, col);
+                this.diagnostics.error("KS4008", `Unknown type '${name}'`, line, col);
             }
             return T.UNKNOWN;
         }
@@ -380,10 +380,10 @@ export class Checker {
             case "interface": {
                 const isGeneric = this.genericTypeParams.has(type.name);
                 if (isGeneric && !type.typeArg) {
-                    this.diagnostics.error(`Generic type '${type.name}' requires a type argument (e.g. '${type.name}<T>')`, line, col);
+                    this.diagnostics.error("KS4009", `Generic type '${type.name}' requires a type argument (e.g. '${type.name}<T>')`, line, col);
                 }
                 else if (!isGeneric && type.typeArg) {
-                    this.diagnostics.error(`Type '${type.name}' is not generic — it doesn't take a type argument`, line, col);
+                    this.diagnostics.error("KS4010", `Type '${type.name}' is not generic — it doesn't take a type argument`, line, col);
                 }
                 if (type.typeArg)
                     this.validateGenericArity(type.typeArg, line, col);
@@ -450,7 +450,7 @@ export class Checker {
         const members = new Map();
         decl.members.forEach((name, index) => {
             if (members.has(name)) {
-                this.diagnostics.error(`Duplicate enum member '${name}'`, decl.line, decl.col);
+                this.diagnostics.error("KS4011", `Duplicate enum member '${name}'`, decl.line, decl.col);
                 return;
             }
             members.set(name, index);
@@ -468,14 +468,14 @@ export class Checker {
         const bases = [];
         for (const baseName of decl.baseList) {
             if (this.namedTypes.get(baseName) !== "interface") {
-                this.diagnostics.error(`Interface '${decl.name}' can only extend other interfaces (unknown interface '${baseName}')`, decl.line, decl.col);
+                this.diagnostics.error("KS4012", `Interface '${decl.name}' can only extend other interfaces (unknown interface '${baseName}')`, decl.line, decl.col);
                 continue;
             }
             // v1 generics can't appear in a base list at all — only as a
             // standalone type (field/param/return/local, `new Box<T>()`). A
             // class/interface always implements/extends a *bare* name.
             if (this.genericTypeParams.has(baseName)) {
-                this.diagnostics.error(`Interface '${decl.name}' cannot extend generic interface '${baseName}' — not supported in v1`, decl.line, decl.col);
+                this.diagnostics.error("KS4013", `Interface '${decl.name}' cannot extend generic interface '${baseName}' — not supported in v1`, decl.line, decl.col);
                 continue;
             }
             bases.push(baseName);
@@ -492,7 +492,7 @@ export class Checker {
         while (stack.length > 0) {
             const current = stack.pop();
             if (current === decl.name) {
-                this.diagnostics.error(`Circular interface inheritance detected involving '${decl.name}'`, decl.line, decl.col);
+                this.diagnostics.error("KS4014", `Circular interface inheritance detected involving '${decl.name}'`, decl.line, decl.col);
                 return;
             }
             if (seen.has(current))
@@ -563,13 +563,13 @@ export class Checker {
             // standalone type (field/param/return/local, `new Box<T>()`). A
             // class always extends/implements a *bare* name.
             if (this.genericTypeParams.has(baseName)) {
-                this.diagnostics.error(`Class '${decl.name}' cannot extend/implement generic type '${baseName}' — not supported in v1`, decl.line, decl.col);
+                this.diagnostics.error("KS4015", `Class '${decl.name}' cannot extend/implement generic type '${baseName}' — not supported in v1`, decl.line, decl.col);
                 continue;
             }
             const kind = this.namedTypes.get(baseName);
             if (kind === "class") {
                 if (superclass !== null) {
-                    this.diagnostics.error(`Class '${decl.name}' cannot extend multiple classes ('${superclass}' and '${baseName}')`, decl.line, decl.col);
+                    this.diagnostics.error("KS4016", `Class '${decl.name}' cannot extend multiple classes ('${superclass}' and '${baseName}')`, decl.line, decl.col);
                 }
                 else {
                     superclass = baseName;
@@ -579,7 +579,7 @@ export class Checker {
                 interfaces.push(baseName);
             }
             else {
-                this.diagnostics.error(`Unknown base class or interface '${baseName}'`, decl.line, decl.col);
+                this.diagnostics.error("KS4017", `Unknown base class or interface '${baseName}'`, decl.line, decl.col);
             }
         }
         this.classes.set(decl.name, {
@@ -602,7 +602,7 @@ export class Checker {
         let current = info.superclass;
         while (current) {
             if (seen.has(current)) {
-                this.diagnostics.error(`Circular inheritance detected involving '${decl.name}'`, decl.line, decl.col);
+                this.diagnostics.error("KS4018", `Circular inheritance detected involving '${decl.name}'`, decl.line, decl.col);
                 return;
             }
             seen.add(current);
@@ -617,11 +617,11 @@ export class Checker {
             return;
         if (info.superclass) {
             if (!decl.constructor.baseArgs) {
-                this.diagnostics.error(`Class '${decl.name}' extends '${info.superclass}' and must call the base constructor via ': base(...)'`, decl.constructor.line, decl.constructor.col);
+                this.diagnostics.error("KS4019", `Class '${decl.name}' extends '${info.superclass}' and must call the base constructor via ': base(...)'`, decl.constructor.line, decl.constructor.col);
             }
         }
         else if (decl.constructor.baseArgs) {
-            this.diagnostics.error(`Class '${decl.name}' has no base class; ': base(...)' is not valid here`, decl.constructor.line, decl.constructor.col);
+            this.diagnostics.error("KS4020", `Class '${decl.name}' has no base class; ': base(...)' is not valid here`, decl.constructor.line, decl.constructor.col);
         }
     }
     // Walks up the inheritance chain to find the nearest ancestor that already
@@ -644,28 +644,28 @@ export class Checker {
                 continue; // static methods don't participate in virtual dispatch
             const methodInfo = classInfo.methods.get(method.name);
             if (methodInfo.isVirtual && methodInfo.isOverride) {
-                this.diagnostics.error(`Method '${method.name}' cannot be both 'virtual' and 'override'`, method.line, method.col);
+                this.diagnostics.error("KS4021", `Method '${method.name}' cannot be both 'virtual' and 'override'`, method.line, method.col);
             }
             const ancestor = this.findNearestMethodInChain(decl.name, method.name);
             if (ancestor) {
                 const overridable = ancestor.info.isVirtual || ancestor.info.isOverride;
                 if (!methodInfo.isOverride) {
-                    this.diagnostics.error(`Method '${method.name}' hides inherited member '${ancestor.owner}.${method.name}'; add 'override' (and mark the base member 'virtual')`, method.line, method.col);
+                    this.diagnostics.error("KS4022", `Method '${method.name}' hides inherited member '${ancestor.owner}.${method.name}'; add 'override' (and mark the base member 'virtual')`, method.line, method.col);
                 }
                 else if (!overridable) {
-                    this.diagnostics.error(`Cannot override non-virtual method '${ancestor.owner}.${method.name}'; mark it 'virtual' in '${ancestor.owner}'`, method.line, method.col);
+                    this.diagnostics.error("KS4023", `Cannot override non-virtual method '${ancestor.owner}.${method.name}'; mark it 'virtual' in '${ancestor.owner}'`, method.line, method.col);
                 }
                 else {
                     const paramsMatch = methodInfo.params.length === ancestor.info.params.length &&
                         methodInfo.params.every((p, i) => T.typesEqual(p, ancestor.info.params[i]));
                     const returnMatches = T.typesEqual(methodInfo.returnType, ancestor.info.returnType);
                     if (!paramsMatch || !returnMatches) {
-                        this.diagnostics.error(`Method '${method.name}' does not match the signature of overridden method '${ancestor.owner}.${method.name}'`, method.line, method.col);
+                        this.diagnostics.error("KS4024", `Method '${method.name}' does not match the signature of overridden method '${ancestor.owner}.${method.name}'`, method.line, method.col);
                     }
                 }
             }
             else if (methodInfo.isOverride) {
-                this.diagnostics.error(`Method '${method.name}' marked 'override' but no matching method was found in a base class`, method.line, method.col);
+                this.diagnostics.error("KS4025", `Method '${method.name}' marked 'override' but no matching method was found in a base class`, method.line, method.col);
             }
         }
     }
@@ -677,12 +677,12 @@ export class Checker {
             for (const sig of this.collectInterfaceMethods(ifaceName)) {
                 const found = this.lookupMethod(decl.name, sig.name);
                 if (!found) {
-                    this.diagnostics.error(`Class '${decl.name}' does not implement method '${sig.name}' required by interface '${ifaceName}'`, decl.line, decl.col);
+                    this.diagnostics.error("KS4026", `Class '${decl.name}' does not implement method '${sig.name}' required by interface '${ifaceName}'`, decl.line, decl.col);
                     continue;
                 }
                 const paramsMatch = found.info.params.length === sig.params.length && found.info.params.every((p, i) => T.typesEqual(p, sig.params[i]));
                 if (!paramsMatch || !T.typesEqual(found.info.returnType, sig.returnType)) {
-                    this.diagnostics.error(`Class '${decl.name}' member '${sig.name}' does not match the signature required by interface '${ifaceName}'`, decl.line, decl.col);
+                    this.diagnostics.error("KS4027", `Class '${decl.name}' member '${sig.name}' does not match the signature required by interface '${ifaceName}'`, decl.line, decl.col);
                 }
             }
         }
@@ -772,13 +772,13 @@ export class Checker {
             return;
         if (visibility === "private") {
             if (ctx.currentClass?.name !== owner) {
-                this.diagnostics.error(`'${memberName}' is private and not accessible outside class '${owner}'`, line, col);
+                this.diagnostics.error("KS4028", `'${memberName}' is private and not accessible outside class '${owner}'`, line, col);
             }
             return;
         }
         // protected
         if (!ctx.currentClass || !(ctx.currentClass.name === owner || this.isSubclass(ctx.currentClass.name, owner))) {
-            this.diagnostics.error(`'${memberName}' is protected and only accessible within '${owner}' or its subclasses`, line, col);
+            this.diagnostics.error("KS4029", `'${memberName}' is protected and only accessible within '${owner}' or its subclasses`, line, col);
         }
     }
     // Assignability: is a value of type `from` usable where type `to` is expected?
@@ -840,13 +840,13 @@ export class Checker {
     resolveBodyReturnType(declaredReturnType, isAsync, line, col) {
         if (isAsync) {
             if (declaredReturnType.kind !== "task") {
-                this.diagnostics.error(`'async' functions/methods must return 'task' or 'task<T>', got '${T.typeToString(declaredReturnType)}'`, line, col);
+                this.diagnostics.error("KS4030", `'async' functions/methods must return 'task' or 'task<T>', got '${T.typeToString(declaredReturnType)}'`, line, col);
                 return T.UNKNOWN;
             }
             return declaredReturnType.resultType;
         }
         if (declaredReturnType.kind === "task") {
-            this.diagnostics.error(`A function/method returning 'task'/'task<T>' must be marked 'async'`, line, col);
+            this.diagnostics.error("KS4031", `A function/method returning 'task'/'task<T>' must be marked 'async'`, line, col);
         }
         return declaredReturnType;
     }
@@ -886,13 +886,13 @@ export class Checker {
                 const baseCtorParams = this.lookupCtorParams(info.superclass);
                 const baseCtx = { returnType: T.VOID, currentClass: info, inConstructor: false, loopDepth: 0, isAsync: false };
                 if (decl.constructor.baseArgs.length !== baseCtorParams.length) {
-                    this.diagnostics.error(`Expected ${baseCtorParams.length} base constructor argument(s), got ${decl.constructor.baseArgs.length}`, decl.constructor.line, decl.constructor.col);
+                    this.diagnostics.error("KS4032", `Expected ${baseCtorParams.length} base constructor argument(s), got ${decl.constructor.baseArgs.length}`, decl.constructor.line, decl.constructor.col);
                 }
                 decl.constructor.baseArgs.forEach((arg, i) => {
                     const expected = baseCtorParams[i] ?? T.UNKNOWN;
                     const argType = this.checkExpressionExpecting(arg, expected, paramScope, baseCtx);
                     if (!this.isAssignableType(argType, expected)) {
-                        this.diagnostics.error(`Base constructor argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
+                        this.diagnostics.error("KS4033", `Base constructor argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
                     }
                 });
             }
@@ -922,7 +922,7 @@ export class Checker {
                 isAsync: false,
             });
             if (!this.isAssignableType(initType, declaredType)) {
-                this.diagnostics.error(`Cannot assign value of type '${T.typeToString(initType)}' to static field of type '${T.typeToString(declaredType)}'`, field.line, field.col);
+                this.diagnostics.error("KS4034", `Cannot assign value of type '${T.typeToString(initType)}' to static field of type '${T.typeToString(declaredType)}'`, field.line, field.col);
             }
         }
     }
@@ -939,7 +939,7 @@ export class Checker {
                 this.recordHover(stmt.nameLine, stmt.nameCol, `${stmt.isConst ? "const" : "let"} ${stmt.name}: ${T.typeToString(declaredType)}`);
                 const initType = this.checkExpressionExpecting(stmt.init, declaredType, scope, ctx);
                 if (!this.isAssignableType(initType, declaredType)) {
-                    this.diagnostics.error(`Cannot assign value of type '${T.typeToString(initType)}' to variable of type '${T.typeToString(declaredType)}'`, stmt.line, stmt.col);
+                    this.diagnostics.error("KS4035", `Cannot assign value of type '${T.typeToString(initType)}' to variable of type '${T.typeToString(declaredType)}'`, stmt.line, stmt.col);
                 }
                 scope.declare(stmt.name, declaredType, stmt.isConst);
                 return;
@@ -994,11 +994,11 @@ export class Checker {
                 const declaredVarType = this.resolveType(stmt.varType, stmt.line, stmt.col);
                 if (iterableType.kind === "array") {
                     if (!this.isAssignableType(iterableType.element, declaredVarType)) {
-                        this.diagnostics.error(`Cannot use loop variable of type '${T.typeToString(declaredVarType)}' for array of '${T.typeToString(iterableType.element)}'`, stmt.line, stmt.col);
+                        this.diagnostics.error("KS4036", `Cannot use loop variable of type '${T.typeToString(declaredVarType)}' for array of '${T.typeToString(iterableType.element)}'`, stmt.line, stmt.col);
                     }
                 }
                 else if (iterableType.kind !== "unknown") {
-                    this.diagnostics.error(`Cannot iterate over non-array type '${T.typeToString(iterableType)}'`, stmt.line, stmt.col);
+                    this.diagnostics.error("KS4037", `Cannot iterate over non-array type '${T.typeToString(iterableType)}'`, stmt.line, stmt.col);
                 }
                 const forScope = scope.child();
                 forScope.declare(stmt.varName, declaredVarType, false);
@@ -1008,14 +1008,14 @@ export class Checker {
             case "ReturnStatement": {
                 const actual = stmt.value ? this.checkExpressionExpecting(stmt.value, ctx.returnType, scope, ctx) : T.VOID;
                 if (!this.isAssignableType(actual, ctx.returnType)) {
-                    this.diagnostics.error(`Return type '${T.typeToString(actual)}' does not match declared return type '${T.typeToString(ctx.returnType)}'`, stmt.line, stmt.col);
+                    this.diagnostics.error("KS4038", `Return type '${T.typeToString(actual)}' does not match declared return type '${T.typeToString(ctx.returnType)}'`, stmt.line, stmt.col);
                 }
                 return;
             }
             case "BreakStatement":
             case "ContinueStatement":
                 if (ctx.loopDepth === 0) {
-                    this.diagnostics.error(`'${stmt.kind === "BreakStatement" ? "break" : "continue"}' used outside of a loop`, stmt.line, stmt.col);
+                    this.diagnostics.error("KS4039", `'${stmt.kind === "BreakStatement" ? "break" : "continue"}' used outside of a loop`, stmt.line, stmt.col);
                 }
                 return;
             case "ExpressionStatement":
@@ -1039,30 +1039,30 @@ export class Checker {
                 this.checkExpression(stmt.expression, scope, ctx);
                 return;
             case "FunctionDecl":
-                this.diagnostics.error(`Nested function declarations are not supported`, stmt.line, stmt.col);
+                this.diagnostics.error("KS4040", `Nested function declarations are not supported`, stmt.line, stmt.col);
                 return;
             case "ClassDecl":
-                this.diagnostics.error(`Nested class declarations are not supported`, stmt.line, stmt.col);
+                this.diagnostics.error("KS4041", `Nested class declarations are not supported`, stmt.line, stmt.col);
                 return;
             case "InterfaceDecl":
-                this.diagnostics.error(`Nested interface declarations are not supported`, stmt.line, stmt.col);
+                this.diagnostics.error("KS4042", `Nested interface declarations are not supported`, stmt.line, stmt.col);
                 return;
             case "EnumDecl":
-                this.diagnostics.error(`Nested enum declarations are not supported`, stmt.line, stmt.col);
+                this.diagnostics.error("KS4043", `Nested enum declarations are not supported`, stmt.line, stmt.col);
                 return;
             case "ExternFunctionDecl":
             case "ExternClassDecl":
             case "ExternValueDecl":
-                this.diagnostics.error(`'extern' declarations are only allowed at the top level of a file`, stmt.line, stmt.col);
+                this.diagnostics.error("KS4044", `'extern' declarations are only allowed at the top level of a file`, stmt.line, stmt.col);
                 return;
             case "RawStringDecl":
-                this.diagnostics.error(`'raw' declarations are only allowed at the top level of a file`, stmt.line, stmt.col);
+                this.diagnostics.error("KS4045", `'raw' declarations are only allowed at the top level of a file`, stmt.line, stmt.col);
                 return;
         }
     }
     expectType(actual, expected, line, col, context) {
         if (!T.typesEqual(actual, expected)) {
-            this.diagnostics.error(`Expected type '${T.typeToString(expected)}' for ${context}, got '${T.typeToString(actual)}'`, line, col);
+            this.diagnostics.error("KS4046", `Expected type '${T.typeToString(expected)}' for ${context}, got '${T.typeToString(actual)}'`, line, col);
         }
     }
     // Recognizes `name != null` / `name == null` (either operand order) as a
@@ -1129,7 +1129,7 @@ export class Checker {
                 const first = elementTypes[0];
                 for (let i = 1; i < elementTypes.length; i++) {
                     if (!T.typesEqual(elementTypes[i], first)) {
-                        this.diagnostics.error(`Array elements must all have the same type`, expr.line, expr.col);
+                        this.diagnostics.error("KS4047", `Array elements must all have the same type`, expr.line, expr.col);
                         break;
                     }
                 }
@@ -1156,14 +1156,14 @@ export class Checker {
                 const fnInfo = this.functions.get(expr.name);
                 if (fnInfo)
                     return T.functionType(fnInfo.params, fnInfo.returnType);
-                this.diagnostics.error(`Undefined identifier '${expr.name}'`, expr.line, expr.col);
+                this.diagnostics.error("KS4048", `Undefined identifier '${expr.name}'`, expr.line, expr.col);
                 return T.UNKNOWN;
             }
             case "ThisExpr": {
                 const found = scope.resolve("this");
                 if (found)
                     return found.type;
-                this.diagnostics.error(`'this' used outside of a class method`, expr.line, expr.col);
+                this.diagnostics.error("KS4049", `'this' used outside of a class method`, expr.line, expr.col);
                 return T.UNKNOWN;
             }
             case "UnaryExpr": {
@@ -1203,13 +1203,13 @@ export class Checker {
                     if (expr.target.kind === "Identifier") {
                         const found = scope.resolve(expr.target.name);
                         if (found?.isConst) {
-                            this.diagnostics.error(`Cannot assign to const variable '${expr.target.name}'`, expr.line, expr.col);
+                            this.diagnostics.error("KS4050", `Cannot assign to const variable '${expr.target.name}'`, expr.line, expr.col);
                         }
                     }
                 }
                 const valueType = this.checkExpressionExpecting(expr.value, targetType, scope, ctx);
                 if (!this.isAssignableType(valueType, targetType)) {
-                    this.diagnostics.error(`Cannot assign value of type '${T.typeToString(valueType)}' to target of type '${T.typeToString(targetType)}'`, expr.line, expr.col);
+                    this.diagnostics.error("KS4051", `Cannot assign value of type '${T.typeToString(valueType)}' to target of type '${T.typeToString(targetType)}'`, expr.line, expr.col);
                 }
                 return targetType;
             }
@@ -1226,7 +1226,7 @@ export class Checker {
                 if (objType.kind === "array")
                     return objType.element;
                 if (objType.kind !== "unknown") {
-                    this.diagnostics.error(`Cannot index into non-array type '${T.typeToString(objType)}'`, expr.line, expr.col);
+                    this.diagnostics.error("KS4052", `Cannot index into non-array type '${T.typeToString(objType)}'`, expr.line, expr.col);
                 }
                 return T.UNKNOWN;
             }
@@ -1240,13 +1240,13 @@ export class Checker {
                 return this.checkLambda(expr, T.UNKNOWN, scope, ctx);
             case "AwaitExpr": {
                 if (!ctx.isAsync) {
-                    this.diagnostics.error(`'await' can only be used inside an 'async' function or method`, expr.line, expr.col);
+                    this.diagnostics.error("KS4053", `'await' can only be used inside an 'async' function or method`, expr.line, expr.col);
                 }
                 const operandType = this.checkExpression(expr.operand, scope, ctx);
                 if (operandType.kind === "task")
                     return operandType.resultType;
                 if (operandType.kind !== "unknown") {
-                    this.diagnostics.error(`Cannot 'await' a value of type '${T.typeToString(operandType)}'`, expr.line, expr.col);
+                    this.diagnostics.error("KS4054", `Cannot 'await' a value of type '${T.typeToString(operandType)}'`, expr.line, expr.col);
                 }
                 return T.UNKNOWN;
             }
@@ -1268,7 +1268,7 @@ export class Checker {
             return this.checkLambda(expr, expected, scope, ctx);
         if (expr.kind === "NullLiteral") {
             if (expected.kind !== "nullable" && expected.kind !== "unknown") {
-                this.diagnostics.error(`Cannot assign 'null' to non-nullable type '${T.typeToString(expected)}'`, expr.line, expr.col);
+                this.diagnostics.error("KS4055", `Cannot assign 'null' to non-nullable type '${T.typeToString(expected)}'`, expr.line, expr.col);
                 return T.UNKNOWN;
             }
             return expected;
@@ -1278,7 +1278,7 @@ export class Checker {
     checkLambda(expr, expected, scope, ctx) {
         if (expected.kind !== "function") {
             if (expected.kind !== "unknown") {
-                this.diagnostics.error(`Lambda expression is not valid where type '${T.typeToString(expected)}' is expected`, expr.line, expr.col);
+                this.diagnostics.error("KS4056", `Lambda expression is not valid where type '${T.typeToString(expected)}' is expected`, expr.line, expr.col);
             }
             const paramTypes = expr.params.map((p) => this.resolveType(p.type, expr.line, expr.col));
             const lambdaScope = scope.child();
@@ -1289,13 +1289,13 @@ export class Checker {
             return T.functionType(paramTypes, actualReturnType);
         }
         if (expr.params.length !== expected.params.length) {
-            this.diagnostics.error(`Lambda has ${expr.params.length} parameter(s), but ${expected.params.length} were expected`, expr.line, expr.col);
+            this.diagnostics.error("KS4057", `Lambda has ${expr.params.length} parameter(s), but ${expected.params.length} were expected`, expr.line, expr.col);
         }
         const paramTypes = expr.params.map((p, i) => {
             const declared = this.resolveType(p.type, expr.line, expr.col);
             const expectedParamType = expected.params[i];
             if (expectedParamType && !T.typesEqual(declared, expectedParamType)) {
-                this.diagnostics.error(`Lambda parameter '${p.name}' has type '${T.typeToString(declared)}', expected '${T.typeToString(expectedParamType)}'`, expr.line, expr.col);
+                this.diagnostics.error("KS4058", `Lambda parameter '${p.name}' has type '${T.typeToString(declared)}', expected '${T.typeToString(expectedParamType)}'`, expr.line, expr.col);
             }
             return declared;
         });
@@ -1330,7 +1330,7 @@ export class Checker {
         }
         const actual = this.checkExpressionExpecting(expr.body, expectedReturnType, scope, lambdaCtx);
         if (expectedReturnType.kind !== "unknown" && !this.isAssignableType(actual, expectedReturnType)) {
-            this.diagnostics.error(`Lambda body has type '${T.typeToString(actual)}', expected '${T.typeToString(expectedReturnType)}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4059", `Lambda body has type '${T.typeToString(actual)}', expected '${T.typeToString(expectedReturnType)}'`, expr.line, expr.col);
         }
         return actual;
     }
@@ -1361,12 +1361,12 @@ export class Checker {
             if (nullSide) {
                 const otherType = nullSide === "left" ? rightType : leftType;
                 if (otherType.kind !== "nullable" && otherType.kind !== "unknown") {
-                    this.diagnostics.error(`Type '${T.typeToString(otherType)}' can never be null — only a nullable type (e.g. '${T.typeToString(otherType)}?') can be compared to 'null'`, line, col);
+                    this.diagnostics.error("KS4060", `Type '${T.typeToString(otherType)}' can never be null — only a nullable type (e.g. '${T.typeToString(otherType)}?') can be compared to 'null'`, line, col);
                 }
                 return T.BOOL;
             }
             if (!T.typesEqual(leftType, rightType)) {
-                this.diagnostics.error(`Cannot compare '${T.typeToString(leftType)}' with '${T.typeToString(rightType)}'`, line, col);
+                this.diagnostics.error("KS4061", `Cannot compare '${T.typeToString(leftType)}' with '${T.typeToString(rightType)}'`, line, col);
             }
             return T.BOOL;
         }
@@ -1387,7 +1387,7 @@ export class Checker {
                     expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
                     return T.VOID;
                 }
-                this.diagnostics.error(`Undefined function '${expr.callee.name}'`, expr.line, expr.col);
+                this.diagnostics.error("KS4062", `Undefined function '${expr.callee.name}'`, expr.line, expr.col);
                 expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
                 return T.UNKNOWN;
             }
@@ -1427,43 +1427,43 @@ export class Checker {
             return calleeType.returnType;
         }
         if (calleeType.kind !== "unknown") {
-            this.diagnostics.error(`Cannot call a value of type '${T.typeToString(calleeType)}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4063", `Cannot call a value of type '${T.typeToString(calleeType)}'`, expr.line, expr.col);
         }
         expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
         return T.UNKNOWN;
     }
     checkArgs(expr, paramTypes, scope, ctx) {
         if (expr.args.length !== paramTypes.length) {
-            this.diagnostics.error(`Expected ${paramTypes.length} argument(s), got ${expr.args.length}`, expr.line, expr.col);
+            this.diagnostics.error("KS4064", `Expected ${paramTypes.length} argument(s), got ${expr.args.length}`, expr.line, expr.col);
         }
         expr.args.forEach((arg, i) => {
             const expected = paramTypes[i] ?? T.UNKNOWN;
             const argType = this.checkExpressionExpecting(arg, expected, scope, ctx);
             if (!this.isAssignableType(argType, expected)) {
-                this.diagnostics.error(`Argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
+                this.diagnostics.error("KS4065", `Argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
             }
         });
     }
     checkNew(expr, scope, ctx) {
         if (this.interfaces.has(expr.className)) {
-            this.diagnostics.error(`Cannot instantiate interface '${expr.className}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4066", `Cannot instantiate interface '${expr.className}'`, expr.line, expr.col);
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
         if (this.enums.has(expr.className)) {
-            this.diagnostics.error(`Cannot instantiate enum '${expr.className}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4067", `Cannot instantiate enum '${expr.className}'`, expr.line, expr.col);
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
         const info = this.classes.get(expr.className);
         if (!info) {
-            this.diagnostics.error(`Unknown class '${expr.className}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4068", `Unknown class '${expr.className}'`, expr.line, expr.col);
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
         let typeArg;
         if (info.typeParam && !expr.typeArgs) {
-            this.diagnostics.error(`Generic class '${expr.className}' requires a type argument (e.g. 'new ${expr.className}<T>(...)')`, expr.line, expr.col);
+            this.diagnostics.error("KS4069", `Generic class '${expr.className}' requires a type argument (e.g. 'new ${expr.className}<T>(...)')`, expr.line, expr.col);
             // Abstractly-typed (T-containing) ctor params, un-substitutable
             // without a real type argument, would otherwise cascade into a
             // confusing "expected 'T'" error on every argument — one clear error
@@ -1472,7 +1472,7 @@ export class Checker {
             return T.UNKNOWN;
         }
         if (!info.typeParam && expr.typeArgs) {
-            this.diagnostics.error(`Class '${expr.className}' is not generic — it doesn't take a type argument`, expr.line, expr.col);
+            this.diagnostics.error("KS4070", `Class '${expr.className}' is not generic — it doesn't take a type argument`, expr.line, expr.col);
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
@@ -1487,13 +1487,13 @@ export class Checker {
             ctorParams = ctorParams.map((p) => this.substituteTypeParam(p, paramName, arg));
         }
         if (expr.args.length !== ctorParams.length) {
-            this.diagnostics.error(`Expected ${ctorParams.length} constructor argument(s), got ${expr.args.length}`, expr.line, expr.col);
+            this.diagnostics.error("KS4071", `Expected ${ctorParams.length} constructor argument(s), got ${expr.args.length}`, expr.line, expr.col);
         }
         expr.args.forEach((arg, i) => {
             const expected = ctorParams[i] ?? T.UNKNOWN;
             const argType = this.checkExpressionExpecting(arg, expected, scope, ctx);
             if (!this.isAssignableType(argType, expected)) {
-                this.diagnostics.error(`Constructor argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
+                this.diagnostics.error("KS4072", `Constructor argument ${i + 1} has type '${T.typeToString(argType)}', expected '${T.typeToString(expected)}'`, arg.line, arg.col);
             }
         });
         return T.classType(expr.className, typeArg);
@@ -1538,7 +1538,7 @@ export class Checker {
     // inference is needed there at all.
     checkArrayMap(expr, elementType, scope, ctx) {
         if (expr.args.length !== 1) {
-            this.diagnostics.error(`Map expects exactly 1 argument, got ${expr.args.length}`, expr.line, expr.col);
+            this.diagnostics.error("KS4073", `Map expects exactly 1 argument, got ${expr.args.length}`, expr.line, expr.col);
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.arrayOf(T.UNKNOWN);
         }
@@ -1547,12 +1547,12 @@ export class Checker {
         const argType = this.checkExpressionExpecting(arg, expectedCallbackType, scope, ctx);
         if (argType.kind !== "function") {
             if (argType.kind !== "unknown") {
-                this.diagnostics.error(`Map expects a function as its argument, got '${T.typeToString(argType)}'`, arg.line, arg.col);
+                this.diagnostics.error("KS4074", `Map expects a function as its argument, got '${T.typeToString(argType)}'`, arg.line, arg.col);
             }
             return T.arrayOf(T.UNKNOWN);
         }
         if (argType.params.length !== 1 || !this.isAssignableType(elementType, argType.params[0])) {
-            this.diagnostics.error(`Map callback must take a single '${T.typeToString(elementType)}' parameter, got '${T.typeToString(argType)}'`, arg.line, arg.col);
+            this.diagnostics.error("KS4075", `Map callback must take a single '${T.typeToString(elementType)}' parameter, got '${T.typeToString(argType)}'`, arg.line, arg.col);
         }
         return T.arrayOf(argType.returnType);
     }
@@ -1573,7 +1573,7 @@ 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(`Enum '${objName}' has no member '${expr.property}'`, expr.line, expr.col);
+                    this.diagnostics.error("KS4076", `Enum '${objName}' has no member '${expr.property}'`, expr.line, expr.col);
                     return { type: T.UNKNOWN, methodInfo: null };
                 }
                 return { type: T.enumType(objName), methodInfo: null };
@@ -1590,13 +1590,13 @@ 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(`Class '${objName}' has no static member '${expr.property}'`, expr.line, expr.col);
+                this.diagnostics.error("KS4077", `Class '${objName}' has no static member '${expr.property}'`, expr.line, expr.col);
                 return { type: T.UNKNOWN, methodInfo: null };
             }
         }
         const objectType = this.checkExpression(expr.object, scope, ctx);
         if (objectType.kind === "nullable") {
-            this.diagnostics.error(`Cannot access member '${expr.property}' on possibly-null type '${T.typeToString(objectType)}' — check for null first (e.g. 'if (x != null) { ... }')`, expr.line, expr.col);
+            this.diagnostics.error("KS4078", `Cannot access member '${expr.property}' on possibly-null type '${T.typeToString(objectType)}' — check for null first (e.g. 'if (x != null) { ... }')`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "string") {
@@ -1610,7 +1610,7 @@ export class Checker {
             const method = STRING_METHODS[expr.property];
             if (method)
                 return { type: method.returnType, methodInfo: method };
-            this.diagnostics.error(`Unknown string member '${expr.property}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4079", `Unknown string member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "array") {
@@ -1626,7 +1626,7 @@ export class Checker {
             // ever reaching checkMember, so `arr.Map(f)` works; `arr.Map` used as
             // a bare value (not called) falls through to this error, same as an
             // unknown member — a known v1 restriction.
-            this.diagnostics.error(`Unknown array member '${expr.property}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4080", `Unknown array member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "state") {
@@ -1642,7 +1642,7 @@ export class Checker {
                 };
                 return { type: method.returnType, methodInfo: method };
             }
-            this.diagnostics.error(`Unknown state member '${expr.property}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4081", `Unknown state member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "class") {
@@ -1658,7 +1658,7 @@ export class Checker {
                 if (isAssignTarget && !field.info.hasSetter) {
                     const inOwnCtor = ctx.inConstructor && ctx.currentClass?.name === field.owner;
                     if (!inOwnCtor) {
-                        this.diagnostics.error(`'${expr.property}' has no setter and can only be assigned within ${field.owner}'s constructor`, expr.line, expr.col);
+                        this.diagnostics.error("KS4082", `'${expr.property}' has no setter and can only be assigned within ${field.owner}'s constructor`, expr.line, expr.col);
                     }
                 }
                 return { type: substitute(field.info.type), methodInfo: null };
@@ -1669,7 +1669,7 @@ export class Checker {
                 const info = paramName ? { ...method.info, params: method.info.params.map(substitute), returnType: substitute(method.info.returnType) } : method.info;
                 return { type: info.returnType, methodInfo: info };
             }
-            this.diagnostics.error(`Class '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4083", `Class '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind === "interface") {
@@ -1684,11 +1684,11 @@ export class Checker {
                 const returnType = substitute(sig.returnType);
                 return { type: returnType, methodInfo: { params, returnType, visibility: "public", isVirtual: false, isOverride: false } };
             }
-            this.diagnostics.error(`Interface '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4084", `Interface '${objectType.name}' has no member '${expr.property}'`, expr.line, expr.col);
             return { type: T.UNKNOWN, methodInfo: null };
         }
         if (objectType.kind !== "unknown") {
-            this.diagnostics.error(`Cannot access member '${expr.property}' on type '${T.typeToString(objectType)}'`, expr.line, expr.col);
+            this.diagnostics.error("KS4085", `Cannot access member '${expr.property}' on type '${T.typeToString(objectType)}'`, expr.line, expr.col);
         }
         return { type: T.UNKNOWN, methodInfo: null };
     }
@@ -1696,19 +1696,19 @@ export class Checker {
         const subjectType = this.checkExpression(expr.subject, scope, ctx);
         this.expectType(subjectType, T.STRING, expr.line, expr.col, "match subject");
         if (expr.arms.length === 0) {
-            this.diagnostics.error(`match expression must have at least one arm`, expr.line, expr.col);
+            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") {
-            this.diagnostics.error(`match expression must end with a wildcard '_' arm`, lastArm.line, lastArm.col);
+            this.diagnostics.error("KS4087", `match expression must end with a wildcard '_' arm`, lastArm.line, lastArm.col);
         }
         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(`match patterns must be string literals`, value.line, value.col);
+                        this.diagnostics.error("KS4088", `match patterns must be string literals`, value.line, value.col);
                     }
                     else {
                         this.checkExpression(value, scope, ctx);
@@ -1721,7 +1721,7 @@ export class Checker {
                 resultType = armResultType;
             }
             else if (!this.isAssignableType(armResultType, resultType)) {
-                this.diagnostics.error(`match arm result type '${T.typeToString(armResultType)}' does not match preceding arms' type '${T.typeToString(resultType)}'`, arm.line, arm.col);
+                this.diagnostics.error("KS4089", `match arm result type '${T.typeToString(armResultType)}' does not match preceding arms' type '${T.typeToString(resultType)}'`, arm.line, arm.col);
             }
         }
         return resultType ?? T.UNKNOWN;

package/dist/diagnostics.js

@@ -2,11 +2,11 @@ export class DiagnosticBag {
     constructor() {
         this.diagnostics = [];
     }
-    error(message, line, col) {
-        this.diagnostics.push({ severity: "error", message, line, col });
+    error(code, message, line, col) {
+        this.diagnostics.push({ code, severity: "error", message, line, col });
     }
-    warning(message, line, col) {
-        this.diagnostics.push({ severity: "warning", message, line, col });
+    warning(code, message, line, col) {
+        this.diagnostics.push({ code, severity: "warning", message, line, col });
     }
     get hasErrors() {
         return this.diagnostics.some((d) => d.severity === "error");
@@ -17,7 +17,7 @@ export class DiagnosticBag {
             .map((d) => {
             const sourceLine = lines[d.line - 1] ?? "";
             const pointer = " ".repeat(Math.max(0, d.col - 1)) + "^";
-            return (`${fileName}:${d.line}:${d.col} - ${d.severity}: ${d.message}\n` +
+            return (`${fileName}:${d.line}:${d.col} - ${d.severity} ${d.code}: ${d.message}\n` +
                 `  ${sourceLine}\n` +
                 `  ${pointer}`);
         })

package/dist/lexer.js

@@ -107,7 +107,7 @@ export class Lexer {
             value += this.readStringChar();
         }
         if (this.isAtEnd()) {
-            this.diagnostics.error("Unterminated string literal", line, col);
+            this.diagnostics.error("KS1001", "Unterminated string literal", line, col);
         }
         else {
             this.advance(); // closing quote
@@ -127,7 +127,7 @@ export class Lexer {
             raw += this.advance();
         }
         if (this.isAtEnd()) {
-            this.diagnostics.error("Unterminated interpolated string literal", line, col);
+            this.diagnostics.error("KS1002", "Unterminated interpolated string literal", line, col);
         }
         else {
             this.advance(); // closing quote
@@ -157,7 +157,7 @@ export class Lexer {
             }
         }
         if (this.isAtEnd()) {
-            this.diagnostics.error("Unterminated regex literal", line, col);
+            this.diagnostics.error("KS1003", "Unterminated regex literal", line, col);
         }
         else {
             this.advance(); // closing quote
@@ -284,7 +284,7 @@ export class Lexer {
                 }
                 break;
         }
-        this.diagnostics.error(`Unexpected character '${c}'`, line, col);
+        this.diagnostics.error("KS1004", `Unexpected character '${c}'`, line, col);
         return this.next();
     }
     make(kind, lexeme, line, col) {

package/dist/modules.js

@@ -25,21 +25,21 @@ function expandTemplates(program, absPath, diagnostics, fileOverrides) {
             continue;
         const templateRef = stmt.template;
         if (stmt.methods.some((m) => m.name === "Render" && !m.isStatic)) {
-            diagnostics.error(`Class '${stmt.name}' has both a 'template' declaration and a hand-written 'Render()' method — remove one`, templateRef.line, templateRef.col);
+            diagnostics.error("KS3001", `Class '${stmt.name}' has both a 'template' declaration and a hand-written 'Render()' method — remove one`, templateRef.line, templateRef.col);
             continue;
         }
         const templatePath = resolve(dirname(absPath), templateRef.path);
         watchFiles.push(templatePath);
         const exists = fileOverrides?.has(templatePath) || existsSync(templatePath);
         if (!exists) {
-            diagnostics.error(`Cannot find template file '${templateRef.path}' (looked for '${displayPath(templatePath)}')`, templateRef.line, templateRef.col);
+            diagnostics.error("KS3002", `Cannot find template file '${templateRef.path}' (looked for '${displayPath(templatePath)}')`, templateRef.line, templateRef.col);
             continue;
         }
         const templateSource = fileOverrides?.get(templatePath) ?? readFileSync(templatePath, "utf-8");
         const templateDiagnostics = new DiagnosticBag();
         const root = new TemplateParser(templateSource, templateDiagnostics).parseDocument();
         for (const d of templateDiagnostics.diagnostics) {
-            diagnostics.error(`[${templateRef.path}:${d.line}:${d.col}] ${d.message}`, templateRef.line, templateRef.col);
+            diagnostics.error("KS3003", `[${templateRef.path}:${d.line}:${d.col}] ${d.message}`, templateRef.line, templateRef.col);
         }
         if (!root)
             continue;
@@ -48,12 +48,12 @@ function expandTemplates(program, absPath, diagnostics, fileOverrides) {
         const compileDiagnostics = new DiagnosticBag();
         const { renderMethod, autoSubscribeFields } = new TemplateCompiler(memberNames, stateFieldNames, compileDiagnostics).compile(root, templateRef);
         for (const d of compileDiagnostics.diagnostics) {
-            diagnostics.error(`[${templateRef.path}:${d.line}:${d.col}] ${d.message}`, templateRef.line, templateRef.col);
+            diagnostics.error("KS3004", `[${templateRef.path}:${d.line}:${d.col}] ${d.message}`, templateRef.line, templateRef.col);
         }
         stmt.methods.push(renderMethod);
         if (autoSubscribeFields.length > 0) {
             if (!stmt.constructor) {
-                diagnostics.error(`Class '${stmt.name}' has a template referencing state<T> field(s) (${autoSubscribeFields.join(", ")}) but no constructor to subscribe from`, templateRef.line, templateRef.col);
+                diagnostics.error("KS3005", `Class '${stmt.name}' has a template referencing state<T> field(s) (${autoSubscribeFields.join(", ")}) but no constructor to subscribe from`, templateRef.line, templateRef.col);
                 continue;
             }
             for (const fieldName of autoSubscribeFields) {
@@ -128,16 +128,16 @@ export function loadModuleGraph(entryAbsPath, fileOverrides) {
         stack.push(absPath);
         for (const u of program.usings) {
             if (!u.path.startsWith("./") && !u.path.startsWith("../")) {
-                diagnostics.error(`'using' path '${u.path}' must be relative (start with './' or '../')`, u.line, u.col);
+                diagnostics.error("KS3006", `'using' path '${u.path}' must be relative (start with './' or '../')`, u.line, u.col);
                 continue;
             }
             const depPath = resolve(dirname(absPath), u.path) + ".ks";
             if (!exists(depPath)) {
-                diagnostics.error(`Cannot find module '${u.path}' (looked for '${displayPath(depPath)}')`, u.line, u.col);
+                diagnostics.error("KS3007", `Cannot find module '${u.path}' (looked for '${displayPath(depPath)}')`, u.line, u.col);
                 continue;
             }
             if (stack.includes(depPath)) {
-                diagnostics.error(`Circular 'using' dependency: ${[...stack, depPath].map(displayPath).join(" -> ")}`, u.line, u.col);
+                diagnostics.error("KS3008", `Circular 'using' dependency: ${[...stack, depPath].map(displayPath).join(" -> ")}`, u.line, u.col);
                 continue;
             }
             record.dependencies.push(depPath);
@@ -180,7 +180,7 @@ export function compileGraph(entryAbsPath, fileOverrides) {
             const mergeOne = (name, apply) => {
                 const existingFrom = importedFrom.get(name);
                 if (existingFrom && existingFrom !== depPath) {
-                    mod.diagnostics.error(`'${name}' is exported by both '${displayPath(existingFrom)}' and '${displayPath(depPath)}' — ambiguous 'using'`, u.line, u.col);
+                    mod.diagnostics.error("KS3009", `'${name}' is exported by both '${displayPath(existingFrom)}' and '${displayPath(depPath)}' — ambiguous 'using'`, u.line, u.col);
                     return;
                 }
                 importedFrom.set(name, depPath);

package/dist/parser.js

@@ -16,7 +16,7 @@ export class Parser {
         while (!this.check(TokenKind.EOF)) {
             if (this.check(TokenKind.Using)) {
                 const t = this.peek();
-                this.diagnostics.error("'using' directives must appear at the top of the file, before any other declaration", t.line, t.col);
+                this.diagnostics.error("KS2001", "'using' directives must appear at the top of the file, before any other declaration", t.line, t.col);
                 this.parseUsing(); // consume and discard so parsing can continue
                 continue;
             }
@@ -44,7 +44,7 @@ export class Parser {
             const expr = this.parseExpression();
             if (!this.check(TokenKind.EOF)) {
                 const t = this.peek();
-                this.diagnostics.error(`Unexpected token '${t.lexeme}' after expression`, t.line, t.col);
+                this.diagnostics.error("KS2002", `Unexpected token '${t.lexeme}' after expression`, t.line, t.col);
             }
             return expr;
         }
@@ -60,7 +60,7 @@ export class Parser {
             const type = this.parseType();
             if (!this.check(TokenKind.EOF)) {
                 const t = this.peek();
-                this.diagnostics.error(`Unexpected token '${t.lexeme}' after type`, t.line, t.col);
+                this.diagnostics.error("KS2003", `Unexpected token '${t.lexeme}' after type`, t.line, t.col);
             }
             return type;
         }
@@ -152,11 +152,11 @@ export class Parser {
         if (this.isDeclStart()) {
             const decl = this.parseDeclaration(isExported);
             if (decl.kind === "VarDecl") {
-                this.diagnostics.error("'public'/'private' cannot modify a variable declaration", modifierTok.line, modifierTok.col);
+                this.diagnostics.error("KS2004", "'public'/'private' cannot modify a variable declaration", modifierTok.line, modifierTok.col);
             }
             return decl;
         }
-        this.diagnostics.error("Expected a class, interface, enum, or function declaration after 'public'/'private'", modifierTok.line, modifierTok.col);
+        this.diagnostics.error("KS2005", "Expected a class, interface, enum, or function declaration after 'public'/'private'", modifierTok.line, modifierTok.col);
         throw new ParseError();
     }
     // Lookahead for the C#-style `Type name` declaration shape (locals and
@@ -204,7 +204,7 @@ export class Parser {
             return { kind: "FunctionDecl", isExported, isAsync, name, params, returnType: type, body, line: start.line, col: start.col };
         }
         if (isAsync) {
-            this.diagnostics.error("'async' cannot modify a variable declaration", start.line, start.col);
+            this.diagnostics.error("KS2006", "'async' cannot modify a variable declaration", start.line, start.col);
         }
         this.consume(TokenKind.Assign, "Expected '=' in variable declaration");
         const init = this.parseExpression();
@@ -273,7 +273,7 @@ export class Parser {
             if (this.check(TokenKind.Template)) {
                 const templateStart = this.advance();
                 if (template) {
-                    this.diagnostics.error(`Class '${name}' already has a 'template' declaration`, templateStart.line, templateStart.col);
+                    this.diagnostics.error("KS2007", `Class '${name}' already has a 'template' declaration`, templateStart.line, templateStart.col);
                 }
                 this.consume(TokenKind.From, "Expected 'from \"<path>\"' after 'template'");
                 const pathTok = this.consume(TokenKind.String, "Expected a file path string after 'from'");
@@ -333,7 +333,7 @@ export class Parser {
                 const params = this.parseParamList();
                 const body = this.parseBlock();
                 if (isStatic && (isVirtual || isOverride)) {
-                    this.diagnostics.error("'static' methods cannot be 'virtual' or 'override'", memberStart.line, memberStart.col);
+                    this.diagnostics.error("KS2008", "'static' methods cannot be 'virtual' or 'override'", memberStart.line, memberStart.col);
                 }
                 methods.push({
                     kind: "MethodDecl",
@@ -354,13 +354,13 @@ export class Parser {
             }
             else if (this.check(TokenKind.LBrace)) {
                 if (isVirtual || isOverride) {
-                    this.diagnostics.error("'virtual'/'override' are only valid on methods", memberStart.line, memberStart.col);
+                    this.diagnostics.error("KS2009", "'virtual'/'override' are only valid on methods", memberStart.line, memberStart.col);
                 }
                 if (isAsync) {
-                    this.diagnostics.error("'async' is only valid on methods", memberStart.line, memberStart.col);
+                    this.diagnostics.error("KS2010", "'async' is only valid on methods", memberStart.line, memberStart.col);
                 }
                 if (isStatic) {
-                    this.diagnostics.error("'static' properties are not supported in v1 (use a static field instead)", memberStart.line, memberStart.col);
+                    this.diagnostics.error("KS2011", "'static' properties are not supported in v1 (use a static field instead)", memberStart.line, memberStart.col);
                 }
                 this.advance(); // '{'
                 this.consume(TokenKind.Get, "Expected 'get' in property accessor list");
@@ -386,10 +386,10 @@ export class Parser {
             }
             else {
                 if (isVirtual || isOverride) {
-                    this.diagnostics.error("'virtual'/'override' are only valid on methods", memberStart.line, memberStart.col);
+                    this.diagnostics.error("KS2012", "'virtual'/'override' are only valid on methods", memberStart.line, memberStart.col);
                 }
                 if (isAsync) {
-                    this.diagnostics.error("'async' is only valid on methods", memberStart.line, memberStart.col);
+                    this.diagnostics.error("KS2013", "'async' is only valid on methods", memberStart.line, memberStart.col);
                 }
                 let initializer = null;
                 if (isStatic) {
@@ -500,7 +500,7 @@ export class Parser {
         const start = this.advance(); // 'raw'
         const typeTok = this.consume(TokenKind.Identifier, "Expected 'string' after 'raw'");
         if (typeTok.lexeme !== "string") {
-            this.diagnostics.error(`'raw' declarations must be of type 'string', got '${typeTok.lexeme}'`, typeTok.line, typeTok.col);
+            this.diagnostics.error("KS2014", `'raw' declarations must be of type 'string', got '${typeTok.lexeme}'`, typeTok.line, typeTok.col);
         }
         const name = this.consume(TokenKind.Identifier, "Expected name").lexeme;
         this.consume(TokenKind.From, "Expected 'from \"<path>\"' after 'raw string <Name>'");
@@ -531,10 +531,10 @@ export class Parser {
             if (this.check(TokenKind.Constructor)) {
                 const ctorTok = this.advance();
                 if (virtualTok) {
-                    this.diagnostics.error(`'virtual' is not valid on an extern constructor`, virtualTok.line, virtualTok.col);
+                    this.diagnostics.error("KS2015", `'virtual' is not valid on an extern constructor`, virtualTok.line, virtualTok.col);
                 }
                 if (hasConstructor) {
-                    this.diagnostics.error(`Extern class '${name}' already has a constructor signature`, ctorTok.line, ctorTok.col);
+                    this.diagnostics.error("KS2016", `Extern class '${name}' already has a constructor signature`, ctorTok.line, ctorTok.col);
                 }
                 ctorParams = this.parseParamList();
                 hasConstructor = true;
@@ -550,7 +550,7 @@ export class Parser {
             }
             else if (this.check(TokenKind.LBrace)) {
                 if (virtualTok) {
-                    this.diagnostics.error(`'virtual' is not valid on an extern property`, virtualTok.line, virtualTok.col);
+                    this.diagnostics.error("KS2017", `'virtual' is not valid on an extern property`, virtualTok.line, virtualTok.col);
                 }
                 this.advance();
                 this.consume(TokenKind.Get, "Expected 'get' in extern property accessor list");
@@ -566,7 +566,7 @@ export class Parser {
             }
             else {
                 if (virtualTok) {
-                    this.diagnostics.error(`'virtual' is not valid on an extern property`, virtualTok.line, virtualTok.col);
+                    this.diagnostics.error("KS2018", `'virtual' is not valid on an extern property`, virtualTok.line, virtualTok.col);
                 }
                 this.consume(TokenKind.Semicolon, "Expected ';' after extern property declaration");
                 properties.push({ isStatic, name: memberName, type, hasSetter: true });
@@ -671,7 +671,7 @@ export class Parser {
             finallyBlock = this.parseBlock();
         }
         if (!catchBlock && !finallyBlock) {
-            this.diagnostics.error("'try' must be followed by 'catch' and/or 'finally'", start.line, start.col);
+            this.diagnostics.error("KS2019", "'try' must be followed by 'catch' and/or 'finally'", start.line, start.col);
         }
         return { kind: "TryStatement", tryBlock, catchParam, catchBlock, finallyBlock, line: start.line, col: start.col };
     }
@@ -945,7 +945,7 @@ export class Parser {
             this.consume(TokenKind.RParen, "Expected ')' after expression");
             return expr;
         }
-        this.diagnostics.error(`Unexpected token '${t.lexeme || t.kind}'`, t.line, t.col);
+        this.diagnostics.error("KS2020", `Unexpected token '${t.lexeme || t.kind}'`, t.line, t.col);
         throw new ParseError();
     }
     // Distinguishes a lambda's parameter list from a parenthesized expression.
@@ -1049,7 +1049,7 @@ export class Parser {
         const subParser = new Parser(subTokens, subDiagnostics);
         const expr = subParser.parseExpression();
         for (const d of subDiagnostics.diagnostics) {
-            this.diagnostics.error(d.message, token.line, token.col);
+            this.diagnostics.error("KS2021", d.message, token.line, token.col);
         }
         return expr;
     }
@@ -1109,7 +1109,7 @@ export class Parser {
         if (this.check(kind))
             return this.advance();
         const t = this.peek();
-        this.diagnostics.error(message, t.line, t.col);
+        this.diagnostics.error("KS2022", message, t.line, t.col);
         throw new ParseError();
     }
     synchronize() {

package/dist/template_compiler.js

@@ -222,7 +222,7 @@ export class TemplateCompiler {
         const elementChildren = node.children.filter((c) => c.kind === "element");
         const textChildren = node.children.filter((c) => c.kind === "text");
         if (textChildren.length > 0 && elementChildren.length > 0) {
-            this.diagnostics.error(`<${node.tag}> cannot mix text and element children — Kopular's DOM bindings have no text-node API, so text can only be a whole element's content`, node.line, node.col);
+            this.diagnostics.error("KS5015", `<${node.tag}> cannot mix text and element children — Kopular's DOM bindings have no text-node API, so text can only be a whole element's content`, node.line, node.col);
         }
         else if (textChildren.length > 0) {
             const parts = textChildren.flatMap((t) => t.parts).map((p) => (p.kind === "Expr" ? { kind: "Expr", expression: this.resolve(p.expression, localScope) } : p));

package/dist/template_lexer.js

@@ -130,7 +130,7 @@ export class TemplateLexer {
             while (!this.isAtEnd() && this.peek() !== '"')
                 value += this.advance();
             if (this.isAtEnd()) {
-                this.diagnostics.error("Unterminated attribute value", line, col);
+                this.diagnostics.error("KS5001", "Unterminated attribute value", line, col);
             }
             else {
                 this.advance(); // closing '"'
@@ -143,7 +143,7 @@ export class TemplateLexer {
         while (!this.isAtEnd() && !/[\s=>/]/.test(this.peek()))
             name += this.advance();
         if (name.length === 0) {
-            this.diagnostics.error(`Unexpected character '${this.peek()}' in tag`, line, col);
+            this.diagnostics.error("KS5002", `Unexpected character '${this.peek()}' in tag`, line, col);
             this.advance(); // avoid an infinite loop on a genuinely unexpected character
             return this.nextTagToken();
         }

package/dist/template_parser.js

@@ -44,7 +44,7 @@ export class TemplateParser {
         const expr = new Parser(tokens, localDiagnostics).parseStandaloneExpression();
         for (const d of localDiagnostics.diagnostics) {
             const { line, col } = remapPosition(fragmentLine, fragmentCol, d.line, d.col);
-            this.diagnostics.error(d.message, line, col);
+            this.diagnostics.error("KS5003", d.message, line, col);
         }
         return expr;
     }
@@ -57,7 +57,7 @@ export class TemplateParser {
         const tokens = new Lexer(source, localDiagnostics).tokenize();
         const ofIndex = tokens.findIndex((t) => t.kind === TokenKind.Identifier && t.lexeme === "of");
         if (ofIndex < 1 || tokens[ofIndex - 1].kind !== TokenKind.Identifier) {
-            this.diagnostics.error(`Expected '*for="Type varName of iterable"', got '${source}'`, fragmentLine, fragmentCol);
+            this.diagnostics.error("KS5004", `Expected '*for="Type varName of iterable"', got '${source}'`, fragmentLine, fragmentCol);
             return null;
         }
         const varNameToken = tokens[ofIndex - 1];
@@ -67,7 +67,7 @@ export class TemplateParser {
         const iterable = new Parser(iterableTokens, localDiagnostics).parseStandaloneExpression();
         for (const d of localDiagnostics.diagnostics) {
             const { line, col } = remapPosition(fragmentLine, fragmentCol, d.line, d.col);
-            this.diagnostics.error(d.message, line, col);
+            this.diagnostics.error("KS5005", d.message, line, col);
         }
         return { varType, varName: varNameToken.lexeme, iterable, line: fragmentLine, col: fragmentCol };
     }
@@ -104,7 +104,7 @@ export class TemplateParser {
                 const exprCol = col;
                 advancePos(text.slice(i, exprStartOffset));
                 if (end === -1) {
-                    this.diagnostics.error("Unterminated '{{' interpolation", exprLine, exprCol);
+                    this.diagnostics.error("KS5006", "Unterminated '{{' interpolation", exprLine, exprCol);
                     break;
                 }
                 const exprSource = text.slice(exprStartOffset, end);
@@ -139,7 +139,7 @@ export class TemplateParser {
         const elementRoots = roots.filter((r) => r.kind === "element");
         if (elementRoots.length !== 1) {
             const at = roots[0] ?? { line: 1, col: 1 };
-            this.diagnostics.error(`A template must have exactly one top-level element, found ${elementRoots.length}`, at.line, at.col);
+            this.diagnostics.error("KS5007", `A template must have exactly one top-level element, found ${elementRoots.length}`, at.line, at.col);
             return null;
         }
         return elementRoots[0];
@@ -153,7 +153,7 @@ export class TemplateParser {
             return this.parseElement();
         }
         const t = this.advance();
-        this.diagnostics.error(`Unexpected token in template ('${t.lexeme}')`, t.line, t.col);
+        this.diagnostics.error("KS5008", `Unexpected token in template ('${t.lexeme}')`, t.line, t.col);
         return null;
     }
     parseElement() {
@@ -183,7 +183,7 @@ export class TemplateParser {
             }
             else if (name === "*if") {
                 if (ifCondition || forBinding) {
-                    this.diagnostics.error(`Only one structural directive ('*if'/'*for') is allowed per element`, nameTok.line, nameTok.col);
+                    this.diagnostics.error("KS5009", `Only one structural directive ('*if'/'*for') is allowed per element`, nameTok.line, nameTok.col);
                 }
                 else {
                     ifCondition = this.parseEmbeddedExpression(valueTok.lexeme, valueTok.line, valueTok.col);
@@ -191,7 +191,7 @@ export class TemplateParser {
             }
             else if (name === "*for") {
                 if (ifCondition || forBinding) {
-                    this.diagnostics.error(`Only one structural directive ('*if'/'*for') is allowed per element`, nameTok.line, nameTok.col);
+                    this.diagnostics.error("KS5010", `Only one structural directive ('*if'/'*for') is allowed per element`, nameTok.line, nameTok.col);
                 }
                 else {
                     forBinding = this.parseForBinding(valueTok.lexeme, valueTok.line, valueTok.col);
@@ -219,11 +219,11 @@ export class TemplateParser {
             if (this.check(TemplateTokenKind.TagClose)) {
                 const closeTok = this.advance();
                 if (closeTok.lexeme !== tag) {
-                    this.diagnostics.error(`Mismatched closing tag: expected '</${tag}>', got '</${closeTok.lexeme}>'`, closeTok.line, closeTok.col);
+                    this.diagnostics.error("KS5011", `Mismatched closing tag: expected '</${tag}>', got '</${closeTok.lexeme}>'`, closeTok.line, closeTok.col);
                 }
             }
             else {
-                this.diagnostics.error(`Expected closing tag '</${tag}>'`, tagTok.line, tagTok.col);
+                this.diagnostics.error("KS5012", `Expected closing tag '</${tag}>'`, tagTok.line, tagTok.col);
             }
         }
         return { kind: "element", tag, staticAttrs, propBindings, eventBindings, ifCondition, forBinding, children, line: tagTok.line, col: tagTok.col };
@@ -233,7 +233,7 @@ export class TemplateParser {
     }
     consumeAttrValue(attrNameTok) {
         if (!this.check(TemplateTokenKind.AttrValue)) {
-            this.diagnostics.error(`Expected a quoted value after '${attrNameTok.lexeme}='`, attrNameTok.line, attrNameTok.col);
+            this.diagnostics.error("KS5013", `Expected a quoted value after '${attrNameTok.lexeme}='`, attrNameTok.line, attrNameTok.col);
             return null;
         }
         return this.advance();
@@ -243,7 +243,7 @@ export class TemplateParser {
             this.advance();
         }
         else {
-            this.diagnostics.error(message, at.line, at.col);
+            this.diagnostics.error("KS5014", message, at.line, at.col);
         }
     }
 }

package/package.json

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