kopscript 0.1.0 → 0.3.0

package/dist/checker.js

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 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() };
@@ -16,6 +18,12 @@ class Scope {
     constructor(parent = null) {
         this.parent = parent;
         this.vars = new Map();
+        // Names known non-null *in this scope specifically* — an overlay checked
+        // independently of where a name was actually declared (which can be many
+        // scopes up), set only on the narrow child scope an `if (x != null)`
+        // branch (or `&&`/`||` short-circuit) is checked in. See
+        // Checker.detectNullCheck/narrowedChild.
+        this.narrowed = new Set();
     }
     declare(name, type, isConst) {
         this.vars.set(name, { type, isConst });
@@ -23,15 +31,25 @@ class Scope {
     resolve(name) {
         return this.vars.get(name) ?? this.parent?.resolve(name) ?? null;
     }
+    narrowNonNull(name) {
+        this.narrowed.add(name);
+    }
+    isNarrowedNonNull(name) {
+        return this.narrowed.has(name) || (this.parent?.isNarrowedNonNull(name) ?? false);
+    }
     child() {
         return new Scope(this);
     }
 }
 export class Checker {
-    constructor(program, diagnostics, imports = emptyModuleExports()) {
+    recordHover(line, col, text) {
+        this.hoverEntries.push({ line, col, text });
+    }
+    constructor(program, diagnostics, imports = emptyModuleExports(), currentFilePath = "test.ks") {
         this.program = program;
         this.diagnostics = diagnostics;
         this.imports = imports;
+        this.currentFilePath = currentFilePath;
         this.classes = new Map();
         this.interfaces = new Map();
         this.enums = new Map();
@@ -39,6 +57,8 @@ export class Checker {
         this.externValues = new Map();
         this.namedTypes = new Map();
         this.importedNames = new Set();
+        this.rawContents = new Map();
+        this.hoverEntries = [];
     }
     check() {
         for (const [name, kind] of this.imports.namedTypes) {
@@ -66,7 +86,8 @@ export class Checker {
         const externFunctionDecls = this.program.statements.filter((s) => s.kind === "ExternFunctionDecl");
         const externClassDecls = this.program.statements.filter((s) => s.kind === "ExternClassDecl");
         const externValueDecls = this.program.statements.filter((s) => s.kind === "ExternValueDecl");
-        this.checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls);
+        const rawStringDecls = this.program.statements.filter((s) => s.kind === "RawStringDecl");
+        this.checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls, rawStringDecls);
         for (const c of classDecls)
             this.namedTypes.set(c.name, "class");
         for (const i of interfaceDecls)
@@ -105,6 +126,8 @@ export class Checker {
             this.registerExternFunction(f);
         for (const v of externValueDecls)
             this.registerExternValue(v);
+        for (const r of rawStringDecls)
+            this.registerRawStringDecl(r);
         const globalScope = new Scope();
         for (const stmt of this.program.statements) {
             if (stmt.kind === "ClassDecl" ||
@@ -112,7 +135,8 @@ export class Checker {
                 stmt.kind === "EnumDecl" ||
                 stmt.kind === "ExternFunctionDecl" ||
                 stmt.kind === "ExternClassDecl" ||
-                stmt.kind === "ExternValueDecl") {
+                stmt.kind === "ExternValueDecl" ||
+                stmt.kind === "RawStringDecl") {
                 continue;
             }
             this.checkTopLevelStatement(stmt, globalScope);
@@ -160,6 +184,25 @@ export class Checker {
     registerExternValue(decl) {
         this.externValues.set(decl.name, this.resolveType(decl.type, decl.line, decl.col));
     }
+    // `raw string <Name> from "<path>";` — resolves <path> relative to this
+    // module's own file, reads it at compile time, and types <Name> as an
+    // ordinary string identifier via the same externValues table an ambient
+    // extern value uses (free same-file resolution, free export propagation).
+    registerRawStringDecl(decl) {
+        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);
+            return;
+        }
+        this.rawContents.set(decl.name, readFileSync(resolvedPath, "utf-8"));
+    }
+    // The raw-declared string contents resolved by this module's own `raw`
+    // declarations (not inherited from imports). Call only after check() has
+    // run; codegen uses this to emit each declaring file's string constants.
+    getRawContents() {
+        return this.rawContents;
+    }
     // The subset of this module's registered declarations visible to a file
     // that `using`s it. Call only after check() has run.
     getExports() {
@@ -190,10 +233,13 @@ export class Checker {
             else if (stmt.kind === "ExternValueDecl" && stmt.isExported) {
                 exports.externValues.set(stmt.name, this.externValues.get(stmt.name));
             }
+            else if (stmt.kind === "RawStringDecl" && stmt.isExported) {
+                exports.externValues.set(stmt.name, this.externValues.get(stmt.name));
+            }
         }
         return exports;
     }
-    checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls) {
+    checkNoDuplicateTopLevelNames(classDecls, interfaceDecls, enumDecls, functionDecls, externFunctionDecls, externClassDecls, externValueDecls, rawStringDecls) {
         const seen = new Map();
         const declare = (name, line, col) => {
             if (this.importedNames.has(name)) {
@@ -218,6 +264,8 @@ export class Checker {
             declare(c.name, c.line, c.col);
         for (const v of externValueDecls)
             declare(v.name, v.line, v.col);
+        for (const r of rawStringDecls)
+            declare(r.name, r.line, r.col);
     }
     // An exported class's superclass and directly-implemented interfaces must
     // also be exported — otherwise a file that imports this class would have
@@ -259,7 +307,9 @@ export class Checker {
     }
     // ---------- registration ----------
     resolveType(node, line, col) {
-        const resolved = T.resolveTypeNode(node, this.namedTypes);
+        const resolved = T.resolveTypeNode(node, this.namedTypes, (namedNode, type) => {
+            this.recordHover(namedNode.line, namedNode.col, T.typeToString(type));
+        });
         if (!resolved) {
             const name = node.kind === "NamedType" ? node.name : "[]";
             this.diagnostics.error(`Unknown type '${name}'`, line, col);
@@ -277,13 +327,15 @@ export class Checker {
             members.set(name, index);
         });
         this.enums.set(decl.name, { name: decl.name, members });
+        this.recordHover(decl.line, decl.col, `enum ${decl.name}`);
     }
     registerInterface(decl) {
-        const methods = decl.methods.map((m) => ({
-            name: m.name,
-            params: m.params.map((p) => this.resolveType(p.type, m.line, m.col)),
-            returnType: this.resolveType(m.returnType, m.line, m.col),
-        }));
+        const methods = decl.methods.map((m) => {
+            const params = m.params.map((p) => this.resolveType(p.type, m.line, m.col));
+            const returnType = this.resolveType(m.returnType, m.line, m.col);
+            this.recordHover(m.nameLine, m.nameCol, `${m.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
+            return { name: m.name, params, returnType };
+        });
         const bases = [];
         for (const baseName of decl.baseList) {
             if (this.namedTypes.get(baseName) !== "interface") {
@@ -293,6 +345,7 @@ export class Checker {
             bases.push(baseName);
         }
         this.interfaces.set(decl.name, { name: decl.name, bases, methods });
+        this.recordHover(decl.line, decl.col, `interface ${decl.name}`);
     }
     checkInterfaceHierarchy(decl) {
         const info = this.interfaces.get(decl.name);
@@ -335,14 +388,18 @@ export class Checker {
         return info.bases.some((b) => this.interfaceExtends(b, sup));
     }
     registerClass(decl) {
+        this.recordHover(decl.line, decl.col, `class ${decl.name}`);
         const fields = new Map();
         const staticFields = new Map();
         for (const f of decl.fields) {
             const info = { type: this.resolveType(f.type, f.line, f.col), visibility: f.visibility, hasSetter: true };
+            this.recordHover(f.nameLine, f.nameCol, `${f.name}: ${T.typeToString(info.type)}`);
             (f.isStatic ? staticFields : fields).set(f.name, info);
         }
         for (const p of decl.properties) {
-            fields.set(p.name, { type: this.resolveType(p.type, p.line, p.col), visibility: p.visibility, hasSetter: p.hasSetter });
+            const type = this.resolveType(p.type, p.line, p.col);
+            this.recordHover(p.nameLine, p.nameCol, `${p.name}: ${T.typeToString(type)}`);
+            fields.set(p.name, { type, visibility: p.visibility, hasSetter: p.hasSetter });
         }
         const methods = new Map();
         const staticMethods = new Map();
@@ -354,6 +411,7 @@ export class Checker {
                 isVirtual: m.isVirtual,
                 isOverride: m.isOverride,
             };
+            this.recordHover(m.nameLine, m.nameCol, `${m.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
             (m.isStatic ? staticMethods : methods).set(m.name, info);
         }
         const ownCtorParams = decl.constructor
@@ -483,10 +541,10 @@ export class Checker {
         }
     }
     registerFunction(decl) {
-        this.functions.set(decl.name, {
-            params: decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col)),
-            returnType: this.resolveType(decl.returnType, decl.line, decl.col),
-        });
+        const params = decl.params.map((p) => this.resolveType(p.type, decl.line, decl.col));
+        const returnType = this.resolveType(decl.returnType, decl.line, decl.col);
+        this.functions.set(decl.name, { params, returnType });
+        this.recordHover(decl.line, decl.col, `function ${decl.name}(${params.map(T.typeToString).join(", ")}): ${T.typeToString(returnType)}`);
     }
     isSubclass(sub, sup) {
         let current = sub;
@@ -580,6 +638,16 @@ export class Checker {
     isAssignableType(from, to) {
         if (from.kind === "unknown" || to.kind === "unknown")
             return true;
+        // Widening: a non-null T (or another T?) is always fine where T? is
+        // expected. The reverse — a possibly-null value where a non-null type
+        // is expected — is never allowed here; that's exactly what narrowing
+        // (see detectNullCheck) exists to get past by changing `from` itself
+        // at the reference site, not by relaxing this rule.
+        if (to.kind === "nullable") {
+            return from.kind === "nullable" ? this.isAssignableType(from.inner, to.inner) : this.isAssignableType(from, to.inner);
+        }
+        if (from.kind === "nullable")
+            return false;
         if (to.kind === "interface") {
             if (from.kind === "class")
                 return this.classImplementsInterface(from.name, to.name);
@@ -691,6 +759,7 @@ export class Checker {
         switch (stmt.kind) {
             case "VarDecl": {
                 const declaredType = this.resolveType(stmt.type, stmt.line, stmt.col);
+                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);
@@ -704,12 +773,19 @@ export class Checker {
             case "IfStatement": {
                 const condType = this.checkExpression(stmt.condition, scope, ctx);
                 this.expectType(condType, T.BOOL, stmt.line, stmt.col, "if condition");
-                this.checkBlock(stmt.thenBranch, scope, ctx);
+                // `if (x != null)` narrows x to non-null in the then-branch;
+                // `if (x == null) ... else ...` narrows it in the else-branch —
+                // see detectNullCheck for exactly what's recognized (bare
+                // identifier vs. `null`, either operand order, `==`/`!=` only).
+                const nullCheck = this.detectNullCheck(stmt.condition);
+                const thenScope = nullCheck?.positiveWhenTrue ? this.narrowedChild(scope, nullCheck.name) : scope;
+                const elseScope = nullCheck && !nullCheck.positiveWhenTrue ? this.narrowedChild(scope, nullCheck.name) : scope;
+                this.checkBlock(stmt.thenBranch, thenScope, ctx);
                 if (stmt.elseBranch) {
                     if (stmt.elseBranch.kind === "IfStatement")
-                        this.checkStatement(stmt.elseBranch, scope, ctx);
+                        this.checkStatement(stmt.elseBranch, elseScope, ctx);
                     else
-                        this.checkBlock(stmt.elseBranch, scope, ctx);
+                        this.checkBlock(stmt.elseBranch, elseScope, ctx);
                 }
                 return;
             }
@@ -802,6 +878,9 @@ export class Checker {
             case "ExternValueDecl":
                 this.diagnostics.error(`'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);
+                return;
         }
     }
     expectType(actual, expected, line, col, context) {
@@ -809,8 +888,41 @@ export class Checker {
             this.diagnostics.error(`Expected type '${T.typeToString(expected)}' for ${context}, got '${T.typeToString(actual)}'`, line, col);
         }
     }
+    // Recognizes `name != null` / `name == null` (either operand order) as a
+    // null-check on a bare identifier — the only shape narrowing understands.
+    // `positiveWhenTrue: true` means the condition being true implies `name`
+    // is non-null (`!=`); `false` means the condition being *false* implies
+    // that (`==`). Deliberately narrow: no `this.Field != null`, no `&&`-
+    // chains inside the checked expression itself, no reachability analysis
+    // for an early-return guard clause (`if (x == null) { return; }` doesn't
+    // narrow `x` afterward) — each would need tracking narrowing by path or
+    // by control-flow reachability rather than by scope, real additional
+    // machinery this v1 doesn't take on.
+    detectNullCheck(condition) {
+        if (condition.kind !== "BinaryExpr" || (condition.op !== "==" && condition.op !== "!="))
+            return null;
+        const { left, right } = condition;
+        const ident = left.kind === "Identifier" ? left : right.kind === "Identifier" ? right : null;
+        const other = ident === left ? right : left;
+        if (!ident || other.kind !== "NullLiteral")
+            return null;
+        return { name: ident.name, positiveWhenTrue: condition.op === "!=" };
+    }
+    narrowedChild(scope, name) {
+        const child = scope.child();
+        child.narrowNonNull(name);
+        return child;
+    }
     // ---------- expressions ----------
     checkExpression(expr, scope, ctx) {
+        const type = this.checkExpressionInner(expr, scope, ctx);
+        if (expr.kind === "Identifier")
+            this.recordHover(expr.line, expr.col, `${expr.name}: ${T.typeToString(type)}`);
+        if (expr.kind === "ThisExpr")
+            this.recordHover(expr.line, expr.col, `this: ${T.typeToString(type)}`);
+        return type;
+    }
+    checkExpressionInner(expr, scope, ctx) {
         switch (expr.kind) {
             case "NumberLiteral":
                 return T.NUMBER;
@@ -818,6 +930,15 @@ export class Checker {
                 return T.STRING;
             case "BoolLiteral":
                 return T.BOOL;
+            // Modeled as UNKNOWN rather than a dedicated Type — typesEqual/
+            // isAssignableType already treat UNKNOWN as compatible with anything,
+            // which is exactly right for a bare `null` with no expected type
+            // (e.g. `x == null`). The real enforcement (null only assignable
+            // where a nullable type is actually expected) lives in
+            // checkExpressionExpecting below, the same place LambdaExpr gets its
+            // expected-type-aware handling.
+            case "NullLiteral":
+                return T.UNKNOWN;
             case "InterpolatedStringLiteral":
                 for (const part of expr.parts) {
                     if (part.kind === "Expr")
@@ -839,8 +960,16 @@ export class Checker {
             }
             case "Identifier": {
                 const found = scope.resolve(expr.name);
-                if (found)
+                if (found) {
+                    // A nullable local/param narrowed by an enclosing `if (x != null)`
+                    // (or equivalent — see detectNullCheck) type-checks as its
+                    // non-null inner type at this specific reference, without
+                    // changing what's actually declared. Narrowing only applies to
+                    // bare names, not member-access paths like `this.Field`.
+                    if (found.type.kind === "nullable" && scope.isNarrowedNonNull(expr.name))
+                        return found.type.inner;
                     return found.type;
+                }
                 const externValue = this.externValues.get(expr.name);
                 if (externValue)
                     return externValue;
@@ -875,7 +1004,14 @@ export class Checker {
             }
             case "LogicalExpr": {
                 const leftType = this.checkExpression(expr.left, scope, ctx);
-                const rightType = this.checkExpression(expr.right, scope, ctx);
+                // `x != null && x.Foo` narrows x for the right operand (only
+                // reached once the left side is true, i.e. x is non-null); by De
+                // Morgan's, `x == null || x.Foo` narrows it the same way (the
+                // right side only runs once the left is false, i.e. x is non-null).
+                const nullCheck = this.detectNullCheck(expr.left);
+                const narrowRight = nullCheck && ((expr.op === "&&" && nullCheck.positiveWhenTrue) || (expr.op === "||" && !nullCheck.positiveWhenTrue));
+                const rightScope = narrowRight ? this.narrowedChild(scope, nullCheck.name) : scope;
+                const rightType = this.checkExpression(expr.right, rightScope, ctx);
                 this.expectType(leftType, T.BOOL, expr.line, expr.col, `'${expr.op}' operand`);
                 this.expectType(rightType, T.BOOL, expr.line, expr.col, `'${expr.op}' operand`);
                 return T.BOOL;
@@ -953,6 +1089,13 @@ export class Checker {
     checkExpressionExpecting(expr, expected, scope, ctx) {
         if (expr.kind === "LambdaExpr")
             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);
+                return T.UNKNOWN;
+            }
+            return expected;
+        }
         return this.checkExpression(expr, scope, ctx);
     }
     checkLambda(expr, expected, scope, ctx) {
@@ -1030,6 +1173,21 @@ export class Checker {
             return T.NUMBER;
         }
         if (op === "==" || op === "!=") {
+            // A literal `null` type-checks as UNKNOWN with no expected type (see
+            // checkExpressionInner), which typesEqual would happily accept
+            // against anything — including a type that can never actually be
+            // null. Checked here, against the AST node itself, specifically so
+            // `nonNullableThing == null` (almost always a leftover from before a
+            // type was made non-nullable, or a copy-pasted guard that can't
+            // trigger) is a compile error instead of a silently-always-false comparison.
+            const nullSide = expr.left.kind === "NullLiteral" ? "left" : expr.right.kind === "NullLiteral" ? "right" : null;
+            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);
+                }
+                return T.BOOL;
+            }
             if (!T.typesEqual(leftType, rightType)) {
                 this.diagnostics.error(`Cannot compare '${T.typeToString(leftType)}' with '${T.typeToString(rightType)}'`, line, col);
             }
@@ -1056,6 +1214,7 @@ export class Checker {
                 expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
                 return T.UNKNOWN;
             }
+            this.recordHover(expr.callee.line, expr.callee.col, `function ${expr.callee.name}(${info.params.map(T.typeToString).join(", ")}): ${T.typeToString(info.returnType)}`);
             this.checkArgs(expr, info.params, scope, ctx);
             return info.returnType;
         }
@@ -1124,6 +1283,7 @@ export class Checker {
             expr.args.forEach((a) => this.checkExpression(a, scope, ctx));
             return T.UNKNOWN;
         }
+        this.recordHover(expr.line, expr.col, `class ${expr.className}`);
         const ctorParams = this.lookupCtorParams(expr.className);
         if (expr.args.length !== ctorParams.length) {
             this.diagnostics.error(`Expected ${ctorParams.length} constructor argument(s), got ${expr.args.length}`, expr.line, expr.col);
@@ -1196,11 +1356,20 @@ export class Checker {
         return T.arrayOf(argType.returnType);
     }
     checkMember(expr, scope, ctx, isAssignTarget = false) {
+        const result = this.checkMemberInner(expr, scope, ctx, isAssignTarget);
+        const text = result.methodInfo
+            ? `${expr.property}(${result.methodInfo.params.map(T.typeToString).join(", ")}): ${T.typeToString(result.methodInfo.returnType)}`
+            : `${expr.property}: ${T.typeToString(result.type)}`;
+        this.recordHover(expr.line, expr.col, text);
+        return result;
+    }
+    checkMemberInner(expr, scope, ctx, isAssignTarget) {
         // A bare type name as the "object" — Color.Red (enum) or Dog.Count (static) —
         // is a type reference, not a value, so it's handled before the general expression check.
         if (expr.object.kind === "Identifier" && !scope.resolve(expr.object.name)) {
             const objName = expr.object.name;
             if (this.enums.has(objName)) {
+                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);
@@ -1209,6 +1378,7 @@ export class Checker {
                 return { type: T.enumType(objName), methodInfo: null };
             }
             if (this.classes.has(objName)) {
+                this.recordHover(expr.object.line, expr.object.col, `class ${objName}`);
                 const field = this.lookupStaticField(objName, expr.property);
                 if (field) {
                     this.checkAccessibility(field.info.visibility, field.owner, ctx, expr.property, expr.line, expr.col);
@@ -1224,6 +1394,10 @@ export class Checker {
             }
         }
         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);
+            return { type: T.UNKNOWN, methodInfo: null };
+        }
         if (objectType.kind === "string") {
             if (expr.property === "Length")
                 return { type: T.NUMBER, methodInfo: null };

package/dist/cli.js

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

package/dist/codegen.js

@@ -60,7 +60,7 @@ export class CodeGenerator {
     // the list of names that module exports — resolved by the caller from that
     // module's own checked Program, since a bare `using` brings everything
     // `public` into scope without naming it explicitly.
-    generate(program, usingExports = new Map()) {
+    generate(program, usingExports = new Map(), rawContents = new Map()) {
         this.interfaceNames = new Set(program.statements.filter((s) => s.kind === "InterfaceDecl").map((s) => s.name));
         const importLines = program.usings
             .map((u) => {
@@ -82,6 +82,11 @@ export class CodeGenerator {
                     lines.push(binding);
                 continue;
             }
+            if (stmt.kind === "RawStringDecl") {
+                const content = rawContents.get(stmt.name) ?? "";
+                lines.push(`${stmt.isExported ? "export const" : "const"} ${stmt.name} = ${JSON.stringify(content)};`);
+                continue;
+            }
             let code = this.genStatement(stmt, 0);
             if ((stmt.kind === "ClassDecl" || stmt.kind === "EnumDecl" || stmt.kind === "FunctionDecl") && stmt.isExported) {
                 code = `export ${code}`;
@@ -126,6 +131,7 @@ export class CodeGenerator {
             case "ExternFunctionDecl":
             case "ExternClassDecl":
             case "ExternValueDecl":
+            case "RawStringDecl":
                 return ""; // handled directly in generate(); unreachable here except via a nested-decl error path
             case "EnumDecl": {
                 const entries = stmt.members.map((m, i) => `${m}: ${i}`).join(", ");
@@ -247,6 +253,8 @@ export class CodeGenerator {
                 return JSON.stringify(expr.value);
             case "BoolLiteral":
                 return String(expr.value);
+            case "NullLiteral":
+                return "null";
             case "InterpolatedStringLiteral":
                 return this.genInterpolatedString(expr);
             case "ArrayLiteral":

package/dist/lexer.js

@@ -2,6 +2,7 @@ import { TokenKind } from "./tokens.js";
 const KEYWORDS = {
     using: TokenKind.Using,
     extern: TokenKind.Extern,
+    raw: TokenKind.Raw,
     from: TokenKind.From,
     as: TokenKind.As,
     const: TokenKind.Const,
@@ -33,6 +34,7 @@ const KEYWORDS = {
     void: TokenKind.Void,
     true: TokenKind.True,
     false: TokenKind.False,
+    null: TokenKind.Null,
     task: TokenKind.Task,
     state: TokenKind.State,
     async: TokenKind.Async,
@@ -213,6 +215,8 @@ export class Lexer {
                 return this.make(TokenKind.Semicolon, c, line, col);
             case ".":
                 return this.make(TokenKind.Dot, c, line, col);
+            case "?":
+                return this.make(TokenKind.Question, c, line, col);
             case "+":
                 return this.make(TokenKind.Plus, c, line, col);
             case "-":