kopscript 0.10.0 → 0.11.1

package/LLM.md

@@ -15,6 +15,8 @@ ks build <file.ks>          # type-check + emit <file>.js and <file>.js.map next
 ks run <file.ks>            # build, then execute with node --enable-source-maps
 ks watch <file.ks>          # build, then rebuild on every change to any file in the graph
 ks check <file.ks>          # type-check only, no output files
+ks fmt <file.ks>             # rewrite to canonical formatting, in place
+ks fmt <file.ks> --check     # exit 1 if not already formatted; writes nothing either way
 ks build|check <file.ks> --json   # single JSON object on stdout instead of human text
 ```
 
@@ -33,6 +35,13 @@ Source maps are statement-level, not column-level (see `src/sourcemap.ts`, hand-
 zero added dependencies) — a thrown/uncaught error resolves to the right `.ks` line, but a
 specific sub-expression within one line isn't separately mapped.
 
+`ks fmt` (`src/printer.ts`) is single-file (lex+parse only, no `using`-graph/type-checking):
+2-space indent, K&R braces, no trailing commas, double quotes only. Two things it does NOT
+preserve, deliberately: original class-member order (always reprints as fields → properties
+→ constructor → methods, since `ClassDecl` buckets members into separate arrays — see
+"Classes" below — so any original interleaving is already gone from the AST) and one-line
+collapsed bodies (every body always prints as a full multi-line block). Comments survive it.
+
 ## File shape
 
 ```ks

package/README.md

@@ -58,6 +58,10 @@ LLM's context, as opposed to this README's narrative explanation.
   every `.js` file (original `.ks` embedded, no separate file to ship), and `ks run` enables
   it automatically — an uncaught exception names the real `.ks` file and line, not the
   generated JS. Hand-rolled VLQ encoder, zero added dependencies. See "Source maps" below.
+- **A real formatter**: `ks fmt` rewrites a file to one canonical style in place — no
+  bikeshedding, no config to agree on. Comments survive it. Verified idempotent and
+  meaning-preserving (byte-identical compiled output before/after) against every real `.ks`
+  file in this repo and Kopular's own source. See "Formatter" below.
 - **A companion framework, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)**:
   components, constructor-injected services via a composition root (no DI container), and
   real-URL routing (no config DSL) — built entirely on the features above, in a separate
@@ -749,6 +753,8 @@ ks build <file.ks>   # type-check and emit <file>.js (+ <file>.js.map) next to t
 ks run <file.ks>     # build, then execute the emitted JS with node --enable-source-maps
 ks watch <file.ks>   # build, then rebuild on every change to any file in the graph
 ks check <file.ks>   # type-check only — no output files written
+ks fmt <file.ks>            # rewrite the file to canonical formatting, in place
+ks fmt <file.ks> --check    # exit 1 if it isn't already formatted; write nothing either way
 ```
 
 `build` and `check` both accept `--json`, which replaces all human-readable output with a
@@ -793,7 +799,31 @@ This is a deliberate v1 cut, the same spirit as generics/nullable types/template
 useful debugging (correct stack-trace lines, working breakpoints) without a full rewrite of
 codegen's string-concatenation architecture into a position-tracking writer.
 
-During development, use `npm run ks -- <build|run|watch|check> <file.ks>` (backed by
+**Formatter**: `ks fmt <file.ks>` rewrites a file to canonical formatting in place —
+2-space indent, K&R braces, single space around operators, one blank line between
+`using`s and the first declaration and between top-level declarations, one blank line
+between class members, no trailing commas, double quotes only. `ks fmt <file.ks> --check`
+reports (exit 1) whether a file isn't already formatted, without writing anything — for CI,
+the same convention `gofmt -l`/`prettier --check` use. Single-file only: formatting needs
+only lexing and parsing, not the full `using`-graph resolution or type-checking `build`/
+`check`/`watch` do. Comments survive formatting (`src/tokens.ts`'s `CommentTrivia`, attached
+to tokens by the lexer and looked up by `src/printer.ts` per node it prints) — two
+deliberate v1 choices worth knowing about, not silent surprises:
+- **Class members print in a fixed canonical order** (fields, then properties, then the
+  constructor, then methods), regardless of how the original source interleaved them —
+  `ClassDecl` buckets members into separate arrays (see `src/ast.ts`), so any original
+  interleaving between e.g. a field and a method is already gone by the time the AST
+  exists; there's nothing to preserve.
+- **Every body always prints as a full multi-line block**, even a single-statement one a
+  human might have collapsed onto one line — no "when do I collapse this" judgment call for
+  the formatter to get subtly wrong.
+
+Verified against every file in `examples/` and Kopular's own real `.ks` sources: formatting
+twice is a no-op (idempotent), the reformatted file reparses with zero diagnostics, and —
+the real proof formatting never changes what a program means — the *generated JS* for the
+original and the reformatted source is byte-for-byte identical.
+
+During development, use `npm run ks -- <build|run|watch|check|fmt> <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.
 
@@ -831,12 +861,13 @@ functions/classes.
 language tour above) — the ceiling that's left is what's *inside* those: no async lambdas,
 and no way to build a `task` value by hand outside an `async` function body.
 
-No formatter (`ks fmt`) yet — it was blocked on the lexer discarding every comment entirely,
-which an AST-based pretty-printer would otherwise silently delete on reformat. That's now
-fixed: every `Token` carries its own `leadingComments` (see `src/tokens.ts`'s
-`CommentTrivia`), purely additive trivia the parser/checker/codegen never look at. This is
-groundwork, not the formatter itself — `ks fmt` (walking the AST and re-emitting source with
-comments placed back correctly) is a separate, not-yet-started piece of work.
+`ks fmt` now exists (see "Formatter" above) — it was blocked on the lexer discarding every
+comment entirely, which an AST-based pretty-printer would otherwise silently delete on
+reformat, until `Token.leadingComments` (`src/tokens.ts`'s `CommentTrivia`) closed that gap.
+`src/printer.ts` looks up each comment by the line number of the token it attached to
+(not a `(line, col)` pair — several node kinds, e.g. `FieldDecl`, deliberately record their
+position at their *type* token, after any `public`/`static`/etc. modifiers, which a
+column-exact lookup would miss).
 
 ### A frontend framework: Kopular
 

package/dist/cli.js

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
-import { writeFileSync, watch as fsWatch } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, watch as fsWatch } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { resolve, basename, join } from "node:path";
 import { compileGraph } from "./modules.js";
+import { Lexer } from "./lexer.js";
+import { Parser } from "./parser.js";
+import { DiagnosticBag } from "./diagnostics.js";
+import { Printer, collectComments } from "./printer.js";
 function outputPathFor(filePath) {
     const name = basename(filePath, ".ks");
     return join(resolve(filePath, ".."), `${name}.js`);
@@ -153,13 +157,48 @@ function watchCommand(filePath) {
     console.log(`[watch] ${filePath} — watching for changes. Press Ctrl+C to stop.`);
     rebuild();
 }
-const COMMANDS = ["build", "run", "watch", "check"];
+// Rewrites `filePath` to canonical formatting, or (with `check: true`)
+// reports whether it already is without touching it — for CI, matching
+// `gofmt -l`/`prettier --check`'s convention. Single-file only, unlike
+// `build`/`check`/`watch`: formatting only needs lex+parse (see
+// printer.ts), no `using`-graph resolution or type-checking, so there's no
+// `compileGraph` call here at all.
+function fmtCommand(filePath, check) {
+    if (!existsSync(filePath)) {
+        console.error(`ks: cannot find file '${filePath}'`);
+        process.exitCode = 1;
+        return;
+    }
+    const source = readFileSync(filePath, "utf-8");
+    const diagnostics = new DiagnosticBag();
+    const tokens = new Lexer(source, diagnostics).tokenize();
+    const program = new Parser(tokens, diagnostics).parseProgram();
+    if (diagnostics.hasErrors) {
+        console.error(diagnostics.format(source, filePath));
+        process.exitCode = 1;
+        return;
+    }
+    const formatted = new Printer(collectComments(tokens)).print(program);
+    if (check) {
+        if (formatted !== source) {
+            console.error(`${filePath} is not formatted`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (formatted !== source) {
+        writeFileSync(filePath, formatted, "utf-8");
+        console.log(`Formatted ${filePath}`);
+    }
+}
+const COMMANDS = ["build", "run", "watch", "check", "fmt"];
 function main() {
     const args = process.argv.slice(2);
     const jsonMode = args.includes("--json");
-    const [command, file] = args.filter((a) => a !== "--json");
+    const checkMode = args.includes("--check");
+    const [command, file] = args.filter((a) => a !== "--json" && a !== "--check");
     if (!command || !file || !COMMANDS.includes(command)) {
-        console.error("Usage: ks <build|run|watch|check> <file.ks> [--json]");
+        console.error("Usage: ks <build|run|watch|check|fmt> <file.ks> [--json] [--check]");
         process.exitCode = 1;
         return;
     }
@@ -168,10 +207,18 @@ function main() {
         process.exitCode = 1;
         return;
     }
+    if (checkMode && command !== "fmt") {
+        console.error("ks: --check is only supported with 'fmt'");
+        process.exitCode = 1;
+        return;
+    }
     const filePath = resolve(file);
     if (command === "check") {
         checkCommand(filePath, jsonMode);
     }
+    else if (command === "fmt") {
+        fmtCommand(filePath, checkMode);
+    }
     else if (command === "build") {
         const { outPath } = build(filePath, jsonMode);
         if (outPath && !jsonMode)

package/dist/printer.js

@@ -0,0 +1,377 @@
+// Builds the line -> comments lookup the Printer consults at every node it's
+// about to print. A separate pass over the token stream, not parser surgery.
+// Keyed by line number *alone*, not the full (line, col) position: a `//`
+// comment always consumes to end-of-line (lexer.ts's `skipTrivia`), so the
+// token it attaches to is either the first thing on its own following line,
+// or shares a line with real code — either way, that line number is unique
+// within a file, and unambiguous as a lookup key. This matters because
+// several AST node kinds (`FieldDecl`/`MethodDecl`/`PropertyDecl` chief among
+// them) deliberately record `line`/`col` at their *type* token, not their
+// first token — parser.ts captures `memberStart` only after consuming any
+// `public`/`static`/`async`/`virtual` modifiers — so a comment attached to
+// the modifier keyword (the token a leading comment actually lands on) would
+// never match an exact (line, col) key, even though it's unambiguously that
+// member's comment. A handful of node shapes carry no `line`/`col` at all
+// (`Param`, `LambdaParam`, `CatchParam`, the bare `TypeNode` variants,
+// `ExternPropertySig`/`ExternMethodSig`) — a comment immediately before one
+// of those has nothing to attach to and is dropped; a real, documented v1
+// loss, not a silent regression (every comment is dropped everywhere today).
+export function collectComments(tokens) {
+    const map = new Map();
+    for (const t of tokens) {
+        if (t.leadingComments.length > 0)
+            map.set(t.line, t.leadingComments);
+    }
+    return map;
+}
+function indentStr(indent) {
+    return "  ".repeat(indent);
+}
+// Re-escapes an already-unescaped string literal value back to source form
+// (the lexer resolves `\n \t \r \\ \" \{ \}` at lex time — see
+// lexer.ts's readStringChar). `escapeBraces` is only needed for an
+// interpolated string's literal text chunks, where a bare `{`/`}` would
+// otherwise be misread as starting a new interpolation hole on reparse;
+// a plain `"..."` string has no such ambiguity, so leaves them alone.
+function escapeStringValue(value, escapeBraces) {
+    let out = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/\r/g, "\\r");
+    if (escapeBraces)
+        out = out.replace(/\{/g, "\\{").replace(/\}/g, "\\}");
+    return out;
+}
+const BIG_TOP_LEVEL_KINDS = new Set([
+    "ClassDecl",
+    "InterfaceDecl",
+    "EnumDecl",
+    "FunctionDecl",
+    "ExternFunctionDecl",
+    "ExternClassDecl",
+    "ExternValueDecl",
+    "RawStringDecl",
+]);
+// Prints an AST back to canonical KopScript source — the counterpart to
+// codegen.ts's AST -> JS, structured the same way (one private method per
+// node kind) so either file explains the other's shape. See README.md's
+// "Formatter" section for the canonical style rules and the deliberate v1
+// simplifications (always-multi-line bodies, imposed class-member order).
+export class Printer {
+    constructor(comments) {
+        this.comments = comments;
+    }
+    print(program) {
+        const parts = [];
+        for (const u of program.usings) {
+            this.emit(parts, u, `using "${u.path}";`, 0);
+        }
+        const usingsToBody = program.usings.length > 0 && program.statements.length > 0;
+        let prevWasBig = false;
+        program.statements.forEach((stmt, i) => {
+            const isBig = BIG_TOP_LEVEL_KINDS.has(stmt.kind);
+            const blankBefore = i === 0 ? usingsToBody : isBig || prevWasBig;
+            this.emit(parts, stmt, this.printStatement(stmt, 0), 0, blankBefore);
+            prevWasBig = isBig;
+        });
+        return parts.join("\n") + "\n";
+    }
+    // Looks up any comments recorded at `node`'s own position and pushes them
+    // (plus `text`) onto `parts` in the right shape: a comment tagged
+    // `sameLineAsPreviousToken` appends to the *previous* entry already in
+    // `parts` (a real trailing comment, e.g. `x = 5; // note`) instead of
+    // starting a new line; every other comment becomes its own leading line
+    // immediately before `text`, indented to match it. `blankLineBefore`
+    // (for the blank line between top-level declarations / class members)
+    // has to be inserted *after* a trailing comment attaches to the true
+    // previous line but *before* any leading comments/text — inserting it
+    // any earlier would make a trailing comment attach to the blank
+    // separator itself instead of the line it actually trails.
+    emit(parts, node, text, indent, blankLineBefore = false) {
+        const found = this.comments.get(node.line) ?? [];
+        let rest = found;
+        if (rest.length > 0 && rest[0].sameLineAsPreviousToken && parts.length > 0) {
+            parts[parts.length - 1] += ` //${rest[0].text}`;
+            rest = rest.slice(1);
+        }
+        if (blankLineBefore && parts.length > 0)
+            parts.push("");
+        const pad = indentStr(indent);
+        for (const c of rest)
+            parts.push(`${pad}//${c.text}`);
+        parts.push(text);
+    }
+    // ---------- types ----------
+    printType(type) {
+        switch (type.kind) {
+            case "NamedType":
+                return type.typeArgs ? `${type.name}<${type.typeArgs.map((t) => this.printType(t)).join(", ")}>` : type.name;
+            case "ArrayType":
+                return `${this.printType(type.element)}[]`;
+            case "FunctionType":
+                return `(${type.params.map((p) => this.printType(p)).join(", ")}) => ${this.printType(type.returnType)}`;
+            case "TaskType":
+                return type.resultType.kind === "NamedType" && type.resultType.name === "void" ? "task" : `task<${this.printType(type.resultType)}>`;
+            case "StateType":
+                return `state<${this.printType(type.valueType)}>`;
+            case "NullableType":
+                return `${this.printType(type.inner)}?`;
+        }
+    }
+    printParams(params) {
+        return params.map((p) => `${this.printType(p.type)} ${p.name}`).join(", ");
+    }
+    // ---------- top-level declarations ----------
+    printStatement(stmt, indent) {
+        const pad = indentStr(indent);
+        switch (stmt.kind) {
+            case "VarDecl":
+                return `${pad}${stmt.isConst ? "const " : ""}${this.printType(stmt.type)} ${stmt.name} = ${this.printExpr(stmt.init, indent)};`;
+            case "FunctionDecl":
+                return this.printFunction(stmt, indent);
+            case "ClassDecl":
+                return this.printClass(stmt, indent);
+            case "InterfaceDecl":
+                return this.printInterface(stmt, indent);
+            case "EnumDecl":
+                return `${pad}${stmt.isExported ? "" : "private "}enum ${stmt.name} { ${stmt.members.join(", ")} }`;
+            case "ExternFunctionDecl":
+                return this.printExternFunction(stmt, indent);
+            case "ExternClassDecl":
+                return this.printExternClass(stmt, indent);
+            case "ExternValueDecl":
+                return this.printExternValue(stmt, indent);
+            case "RawStringDecl":
+                return `${pad}${stmt.isExported ? "" : "private "}raw string ${stmt.name} from "${stmt.path}";`;
+            case "Block":
+                return this.printBlock(stmt, indent);
+            case "IfStatement":
+                return this.printIf(stmt, indent);
+            case "WhileStatement":
+                return `${pad}while (${this.printExpr(stmt.condition, indent)}) ${this.printBlock(stmt.body, indent).trimStart()}`;
+            case "ForStatement": {
+                const init = stmt.init ? (stmt.init.kind === "VarDecl" ? `${stmt.init.isConst ? "const " : ""}${this.printType(stmt.init.type)} ${stmt.init.name} = ${this.printExpr(stmt.init.init, indent)}` : this.printExpr(stmt.init.expression, indent)) : "";
+                const cond = stmt.condition ? this.printExpr(stmt.condition, indent) : "";
+                const update = stmt.update ? this.printExpr(stmt.update, indent) : "";
+                return `${pad}for (${init}; ${cond}; ${update}) ${this.printBlock(stmt.body, indent).trimStart()}`;
+            }
+            case "ForInStatement":
+                return `${pad}foreach (${this.printType(stmt.varType)} ${stmt.varName} in ${this.printExpr(stmt.iterable, indent)}) ${this.printBlock(stmt.body, indent).trimStart()}`;
+            case "ReturnStatement":
+                return stmt.value ? `${pad}return ${this.printExpr(stmt.value, indent)};` : `${pad}return;`;
+            case "BreakStatement":
+                return `${pad}break;`;
+            case "ContinueStatement":
+                return `${pad}continue;`;
+            case "ExpressionStatement":
+                return `${pad}${this.printExpr(stmt.expression, indent)};`;
+            case "TryStatement":
+                return this.printTry(stmt, indent);
+            case "ThrowStatement":
+                return `${pad}throw ${this.printExpr(stmt.expression, indent)};`;
+        }
+    }
+    printBlock(block, indent) {
+        const pad = indentStr(indent);
+        if (block.statements.length === 0)
+            return `{\n${pad}}`;
+        const parts = [];
+        for (const s of block.statements) {
+            this.emit(parts, s, this.printStatement(s, indent + 1), indent + 1);
+        }
+        return `{\n${parts.join("\n")}\n${pad}}`;
+    }
+    printIf(stmt, indent) {
+        const pad = indentStr(indent);
+        let code = `${pad}if (${this.printExpr(stmt.condition, indent)}) ${this.printBlock(stmt.thenBranch, indent).trimStart()}`;
+        if (stmt.elseBranch) {
+            code += stmt.elseBranch.kind === "IfStatement" ? ` else ${this.printIf(stmt.elseBranch, indent).trimStart()}` : ` else ${this.printBlock(stmt.elseBranch, indent).trimStart()}`;
+        }
+        return code;
+    }
+    printTry(stmt, indent) {
+        let code = `${indentStr(indent)}try ${this.printBlock(stmt.tryBlock, indent).trimStart()}`;
+        if (stmt.catchBlock && stmt.catchParam) {
+            code += ` catch (${this.printType(stmt.catchParam.type)} ${stmt.catchParam.name}) ${this.printBlock(stmt.catchBlock, indent).trimStart()}`;
+        }
+        if (stmt.finallyBlock) {
+            code += ` finally ${this.printBlock(stmt.finallyBlock, indent).trimStart()}`;
+        }
+        return code;
+    }
+    printFunction(decl, indent) {
+        const pad = indentStr(indent);
+        const prefix = `${decl.isExported ? "" : "private "}${decl.isAsync ? "async " : ""}`;
+        return `${pad}${prefix}${this.printType(decl.returnType)} ${decl.name}(${this.printParams(decl.params)}) ${this.printBlock(decl.body, indent).trimStart()}`;
+    }
+    // Canonical member order: fields, then properties, then the constructor,
+    // then methods — regardless of how the original source interleaved them.
+    // ClassDecl buckets members into four separate arrays (see ast.ts), so
+    // any original interleaving between e.g. a field and a method is already
+    // gone by the time the AST exists; this imposes one fixed, consistent
+    // order rather than guessing at how to restore it. A real, visible
+    // behavior on first-format of a file that interleaved members — not
+    // hidden, documented in README.md's "Formatter" section.
+    printClass(decl, indent) {
+        const pad = indentStr(indent);
+        const memberPad = indentStr(indent + 1);
+        const nameWithTypeParam = decl.typeParam ? `${decl.name}<${decl.typeParam}>` : decl.name;
+        const header = decl.baseList.length > 0 ? `class ${nameWithTypeParam} : ${decl.baseList.join(", ")} {` : `class ${nameWithTypeParam} {`;
+        const prefix = decl.isExported ? "" : "private ";
+        const memberParts = [];
+        const pushMember = (node, text) => {
+            this.emit(memberParts, node, text, indent + 1, memberParts.length > 0);
+        };
+        for (const field of decl.fields) {
+            const modifiers = `${field.visibility}${field.isStatic ? " static" : ""}`;
+            const init = field.initializer ? ` = ${this.printExpr(field.initializer, indent + 1)}` : "";
+            pushMember(field, `${memberPad}${modifiers} ${this.printType(field.type)} ${field.name}${init};`);
+        }
+        for (const prop of decl.properties) {
+            const accessors = prop.hasSetter ? "get; set;" : "get;";
+            pushMember(prop, `${memberPad}${prop.visibility} ${this.printType(prop.type)} ${prop.name} { ${accessors} }`);
+        }
+        if (decl.constructor) {
+            pushMember(decl.constructor, this.printConstructor(decl.constructor, indent + 1));
+        }
+        for (const method of decl.methods) {
+            const modifiers = [method.visibility, method.isStatic ? "static" : null, method.isAsync ? "async" : null, method.isVirtual ? "virtual" : null, method.isOverride ? "override" : null].filter((m) => m !== null).join(" ");
+            pushMember(method, `${memberPad}${modifiers} ${this.printType(method.returnType)} ${method.name}(${this.printParams(method.params)}) ${this.printBlock(method.body, indent + 1).trimStart()}`);
+        }
+        if (decl.template) {
+            pushMember(decl.template, `${memberPad}template from "${decl.template.path}";`);
+        }
+        if (memberParts.length === 0)
+            return `${pad}${prefix}${header}\n${pad}}`;
+        return `${pad}${prefix}${header}\n${memberParts.join("\n")}\n${pad}}`;
+    }
+    printConstructor(ctor, indent) {
+        const pad = indentStr(indent);
+        const base = ctor.baseArgs ? ` : base(${ctor.baseArgs.map((a) => this.printExpr(a, indent)).join(", ")})` : "";
+        return `${pad}constructor(${this.printParams(ctor.params)})${base} ${this.printBlock(ctor.body, indent).trimStart()}`;
+    }
+    printInterface(decl, indent) {
+        const pad = indentStr(indent);
+        const memberPad = indentStr(indent + 1);
+        const nameWithTypeParam = decl.typeParam ? `${decl.name}<${decl.typeParam}>` : decl.name;
+        const header = decl.baseList.length > 0 ? `interface ${nameWithTypeParam} : ${decl.baseList.join(", ")} {` : `interface ${nameWithTypeParam} {`;
+        const prefix = decl.isExported ? "" : "private ";
+        if (decl.methods.length === 0)
+            return `${pad}${prefix}${header}\n${pad}}`;
+        const memberParts = [];
+        for (const m of decl.methods) {
+            this.emit(memberParts, m, `${memberPad}${this.printType(m.returnType)} ${m.name}(${this.printParams(m.params)});`, indent + 1);
+        }
+        return `${pad}${prefix}${header}\n${memberParts.join("\n")}\n${pad}}`;
+    }
+    printExternFunction(decl, indent) {
+        const pad = indentStr(indent);
+        const prefix = decl.isExported ? "" : "private ";
+        const as = decl.jsName !== decl.name ? ` as "${decl.jsName}"` : "";
+        const from = decl.modulePath ? ` from "${decl.modulePath}"` : "";
+        return `${pad}${prefix}extern ${this.printType(decl.returnType)} ${decl.name}(${this.printParams(decl.params)})${from}${as};`;
+    }
+    printExternValue(decl, indent) {
+        const pad = indentStr(indent);
+        const prefix = decl.isExported ? "" : "private ";
+        const as = decl.jsName !== decl.name ? ` as "${decl.jsName}"` : "";
+        const from = decl.modulePath ? ` from "${decl.modulePath}"` : "";
+        return `${pad}${prefix}extern ${this.printType(decl.type)} ${decl.name}${from}${as};`;
+    }
+    printExternClass(decl, indent) {
+        const pad = indentStr(indent);
+        const memberPad = indentStr(indent + 1);
+        const prefix = decl.isExported ? "" : "private ";
+        const nameWithTypeParam = decl.typeParam ? `${decl.name}<${decl.typeParam}>` : decl.name;
+        const lines = [];
+        if (decl.hasConstructor)
+            lines.push(`${memberPad}constructor(${this.printParams(decl.ctorParams)});`);
+        for (const p of decl.properties) {
+            const accessors = p.hasSetter ? "get; set;" : "get;";
+            lines.push(`${memberPad}${p.isStatic ? "static " : ""}${this.printType(p.type)} ${p.name} { ${accessors} }`);
+        }
+        for (const m of decl.methods) {
+            const modifiers = `${m.isStatic ? "static " : ""}${m.isVirtual ? "virtual " : ""}`;
+            lines.push(`${memberPad}${modifiers}${this.printType(m.returnType)} ${m.name}(${this.printParams(m.params)});`);
+        }
+        const from = decl.modulePath ? ` from "${decl.modulePath}"` : "";
+        if (lines.length === 0)
+            return `${pad}${prefix}extern class ${nameWithTypeParam} {\n${pad}}${from};`;
+        return `${pad}${prefix}extern class ${nameWithTypeParam} {\n${lines.join("\n")}\n${pad}}${from};`;
+    }
+    // ---------- expressions ----------
+    // `indent` only matters to the two expression kinds that can themselves
+    // introduce a real newline (a `match` expression, a lambda with a block
+    // body) — every other case ignores it. Threaded through generally rather
+    // than special-cased at each call site, so a `match`/block-lambda buried
+    // inside a call argument several levels deep still indents correctly,
+    // not just one at the top of a statement.
+    printExpr(expr, indent = 0) {
+        switch (expr.kind) {
+            case "NumberLiteral":
+                return String(expr.value);
+            case "StringLiteral":
+                return `"${escapeStringValue(expr.value, false)}"`;
+            case "BoolLiteral":
+                return String(expr.value);
+            case "NullLiteral":
+                return "null";
+            case "InterpolatedStringLiteral":
+                return this.printInterpolatedString(expr, indent);
+            case "ArrayLiteral":
+                return `[${expr.elements.map((e) => this.printExpr(e, indent)).join(", ")}]`;
+            case "Identifier":
+                return expr.name;
+            case "ThisExpr":
+                return "this";
+            case "UnaryExpr":
+                return `${expr.op}${this.printExpr(expr.operand, indent)}`;
+            case "BinaryExpr":
+                return `${this.printExpr(expr.left, indent)} ${expr.op} ${this.printExpr(expr.right, indent)}`;
+            case "LogicalExpr":
+                return `${this.printExpr(expr.left, indent)} ${expr.op} ${this.printExpr(expr.right, indent)}`;
+            case "AssignExpr":
+                return `${this.printExpr(expr.target, indent)} = ${this.printExpr(expr.value, indent)}`;
+            case "CallExpr":
+                return `${this.printExpr(expr.callee, indent)}(${expr.args.map((a) => this.printExpr(a, indent)).join(", ")})`;
+            case "NewExpr": {
+                const typeArgs = expr.typeArgs ? `<${expr.typeArgs.map((t) => this.printType(t)).join(", ")}>` : "";
+                return `new ${expr.className}${typeArgs}(${expr.args.map((a) => this.printExpr(a, indent)).join(", ")})`;
+            }
+            case "MemberExpr":
+                return `${this.printExpr(expr.object, indent)}.${expr.property}`;
+            case "IndexExpr":
+                return `${this.printExpr(expr.object, indent)}[${this.printExpr(expr.index, indent)}]`;
+            case "MatchExpr":
+                return this.printMatch(expr, indent);
+            case "LambdaExpr":
+                return this.printLambda(expr, indent);
+            case "AwaitExpr":
+                return `await ${this.printExpr(expr.operand, indent)}`;
+            case "StateExpr":
+                return `state(${this.printExpr(expr.initializer, indent)})`;
+        }
+    }
+    printLambda(expr, indent) {
+        const params = expr.params.map((p) => `${this.printType(p.type)} ${p.name}`).join(", ");
+        if (expr.body.kind === "Block")
+            return `(${params}) => ${this.printBlock(expr.body, indent).trimStart()}`;
+        return `(${params}) => ${this.printExpr(expr.body, indent)}`;
+    }
+    printInterpolatedString(expr, indent) {
+        const body = expr.parts.map((part) => (part.kind === "Text" ? escapeStringValue(part.text, true) : `{${this.printExpr(part.expression, indent)}}`)).join("");
+        return `$"${body}"`;
+    }
+    printMatch(expr, indent) {
+        const pad = indentStr(indent);
+        const armPad = indentStr(indent + 1);
+        const lines = [`match ${this.printExpr(expr.subject, indent)} {`];
+        const armParts = [];
+        for (const arm of expr.arms) {
+            const pattern = arm.pattern.kind === "WildcardPattern" ? "_" : arm.pattern.kind === "RegexPattern" ? `r"${arm.pattern.source}"` : arm.pattern.values.map((v) => this.printExpr(v, indent)).join(", ");
+            this.emit(armParts, arm, `${armPad}${pattern} => ${this.printExpr(arm.result, indent + 1)},`, indent + 1);
+        }
+        // No trailing comma after the last arm, matching the observed convention.
+        if (armParts.length > 0)
+            armParts[armParts.length - 1] = armParts[armParts.length - 1].replace(/,$/, "");
+        lines.push(...armParts, `${pad}}`);
+        return lines.join("\n");
+    }
+}

package/package.json

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