cluaupp 1.5.2 → 2.0.0-beta.2

package/src/compiler/parser.ts

@@ -0,0 +1,1943 @@
+/**
+ * CL++ 0.9 parser — grammar and precedence of KartzRbx/CLPP `parser.cpp` (docs/ebnf.md),
+ * extended for the Roblox host: any keyword after `.`, calls on any expression, generic
+ * member calls (`x.WaitForChild<Model>("Map")`), `expr as Type`, typed `for (Player p in …)`,
+ * anonymous `func (…) { }` values, `expr ~> handler;` on Roblox events, `T?` and `func(A) -> R` types.
+ *
+ * CL++ precedence is kept exactly: unary `-`/`not`/`~` sit between `shl/shr` and comparison, so
+ * `-a + b` is `-(a + b)` and `not a == b` is `not (a == b)`. A unary operator in operand position
+ * (`a * -b`, `x == -1`), which CLPP rejects, binds tightly to its operand.
+ */
+
+import type {
+	Arg,
+	Attribute,
+	BinaryOp,
+	Decl,
+	DeclKind,
+	EnumDecl,
+	Expr,
+	FieldDecl,
+	FuncDecl,
+	LinkDecl,
+	MatchArm,
+	NamespaceDecl,
+	Param,
+	Pattern,
+	Program,
+	Stmt,
+	StructDecl,
+	SwitchCase,
+	TypeAliasDecl,
+	TypeNode,
+	VariantDecl,
+	VarName,
+} from "./ast.js";
+import type { DiagnosticBag } from "./diagnostics.js";
+import { KEYWORDS, tokenize, VALUE_KEYWORDS, type Token } from "./lexer.js";
+import type { SourceFile, Span } from "./source.js";
+
+const TYPE_KEYWORDS = new Set(["int", "float", "double", "bool", "string", "task", "buffer", "Vector2", "Vector3", "Vector4", "void"]);
+const ASSIGN_OPS = new Set(["=", "+=", "-=", "*=", "/=", "%="]);
+const LEGACY_SIGNAL_METHODS = new Set(["Connect", "Once", "ConnectParallel", "Wait"]);
+const STATEMENT_KEYWORDS = new Set([
+	"let", "const", "constexpr", "auto", "if", "while", "for", "return", "break", "continue", "switch", "match", "try",
+	"post", "warn", "report", "cout", "func", "struct", "enum", "variant", "link", "import", "signal", "observable",
+	"atomic", "namespace", "abstract", "final", "async", "extern", "static", "void", "using",
+]);
+
+export function defaultAlias(path: string): string {
+	let base = path.replace(/^@/, "").replace(/\\/g, "/");
+	if (base.includes("/")) {
+		base = base.slice(base.lastIndexOf("/") + 1);
+		base = base.replace(/\.(server|client)?\.?clp$/i, "").replace(/\.clp$/i, "");
+	} else {
+		base = base.slice(base.lastIndexOf(".") + 1);
+	}
+	base = base.replace(/\.[^.]*$/, "");
+	if (!base) {
+		return "";
+	}
+	return base[0].toUpperCase() + base.slice(1);
+}
+
+class ParseAbort extends Error {}
+
+export class Parser {
+	private tokens: Token[];
+	private i = 0;
+	private pendingDoc: string | undefined;
+	private depth = 0;
+
+	constructor(
+		private readonly source: SourceFile,
+		private readonly diags: DiagnosticBag,
+		tokens?: Token[],
+	) {
+		this.tokens = tokens ?? tokenize(source.text, diags);
+	}
+
+	// ---------- token helpers ----------
+
+	private peek(n = 0): Token {
+		return this.tokens[Math.min(this.i + n, this.tokens.length - 1)];
+	}
+
+	private get tok(): Token {
+		return this.tokens[this.i];
+	}
+
+	private advance(): Token {
+		const t = this.tokens[this.i];
+		if (this.i < this.tokens.length - 1) {
+			this.i++;
+		}
+		return t;
+	}
+
+	private atEnd(): boolean {
+		return this.tok.kind === "eof";
+	}
+
+	private isOp(text: string, n = 0): boolean {
+		const t = this.peek(n);
+		return t.kind === "op" && t.text === text;
+	}
+
+	private isKw(text: string, n = 0): boolean {
+		const t = this.peek(n);
+		return t.kind === "keyword" && t.text === text;
+	}
+
+	private isIdent(n = 0, text?: string): boolean {
+		const t = this.peek(n);
+		return t.kind === "ident" && (text === undefined || t.text === text);
+	}
+
+	private eatOp(text: string): boolean {
+		if (this.isOp(text)) {
+			this.advance();
+			return true;
+		}
+		return false;
+	}
+
+	private eatKw(text: string): boolean {
+		if (this.isKw(text)) {
+			this.advance();
+			return true;
+		}
+		return false;
+	}
+
+	private prevEnd(): number {
+		return this.tokens[Math.max(0, this.i - 1)].end;
+	}
+
+	private spanFrom(start: number): Span {
+		return { start, end: Math.max(start, this.prevEnd()) };
+	}
+
+	private errorAt(span: Span, message: string, notes?: string[], code = "CL1100"): void {
+		this.diags.error(code, span, message, notes);
+	}
+
+	private expectOp(text: string, context?: string): Token {
+		if (this.isOp(text)) {
+			return this.advance();
+		}
+		const t = this.tok;
+		const where = t.kind === "eof" ? "end of file" : `'${t.text}'`;
+		const span = text === ";" && this.i > 0 ? { start: this.prevEnd(), end: this.prevEnd() + 1 } : { start: t.start, end: Math.max(t.end, t.start + 1) };
+		this.errorAt(span, `expected '${text}'${context ? ` ${context}` : ""}, found ${where}`, undefined, text === ";" ? "CL1101" : "CL1102");
+		throw new ParseAbort();
+	}
+
+	private expectName(what = "name"): Token {
+		if (this.tok.kind === "ident") {
+			return this.advance();
+		}
+		const t = this.tok;
+		if (t.kind === "keyword") {
+			this.errorAt({ start: t.start, end: t.end }, `'${t.text}' is a reserved word and cannot be used as a ${what}`, undefined, "CL1103");
+		} else {
+			this.errorAt({ start: t.start, end: Math.max(t.end, t.start + 1) }, `expected ${what}`, undefined, "CL1104");
+		}
+		throw new ParseAbort();
+	}
+
+	/** Name after `.` / `::` — keywords are fine there (`Instance.new`, `x.type`). */
+	private expectMemberName(): Token {
+		const t = this.tok;
+		if (t.kind === "ident" || t.kind === "keyword") {
+			return this.advance();
+		}
+		this.errorAt({ start: t.start, end: Math.max(t.end, t.start + 1) }, "expected member name", undefined, "CL1105");
+		throw new ParseAbort();
+	}
+
+	private synchronize(): void {
+		let braces = 0;
+		while (!this.atEnd()) {
+			const t = this.tok;
+			if (t.kind === "op") {
+				if (t.text === ";" && braces === 0) {
+					this.advance();
+					return;
+				}
+				if (t.text === "{") {
+					braces++;
+				} else if (t.text === "}") {
+					if (braces === 0) {
+						return;
+					}
+					braces--;
+					if (braces === 0) {
+						this.advance();
+						return;
+					}
+				}
+			} else if (braces === 0 && t.newlineBefore && t.kind === "keyword" && STATEMENT_KEYWORDS.has(t.text) && this.i > 0) {
+				return;
+			}
+			this.advance();
+		}
+	}
+
+	// ---------- program ----------
+
+	parseProgram(): Program {
+		const program: Program = { file: this.source.path, mode: "nonstrict", directives: [], body: [] };
+		let sawCode = false;
+		while (!this.atEnd()) {
+			const t = this.tok;
+			if (t.kind === "directive") {
+				this.advance();
+				const word = String(t.value || "");
+				if (sawCode) {
+					this.diags.warning("CL1201", { start: t.start, end: t.end }, `directive '<<!${word}' must be at the top of the file; it is ignored here`);
+					continue;
+				}
+				if (word === "strict" || word === "nocheck" || word === "nonstrict") {
+					program.mode = word;
+				} else if (word === "native" || word === "optimize" || word === "nostrict" || word === "pure" || word === "nolint") {
+					program.directives.push(word);
+				} else {
+					this.diags.warning("CL1202", { start: t.start, end: t.end }, `unknown directive '<<!${word}'`, ["known: strict, nonstrict, nocheck, native, pure, nolint"]);
+				}
+				continue;
+			}
+			sawCode = true;
+			const before = this.i;
+			const stmt = this.statementSafe(true);
+			if (stmt) {
+				program.body.push(stmt);
+			} else if (this.i === before) {
+				this.advance();
+			}
+		}
+		return program;
+	}
+
+	private statementSafe(top: boolean): Stmt | null {
+		const start = this.i;
+		try {
+			return this.statement(top);
+		} catch (err) {
+			if (!(err instanceof ParseAbort)) {
+				throw err;
+			}
+			if (this.i === start) {
+				this.advance();
+			}
+			this.synchronize();
+			return null;
+		}
+	}
+
+	private attributes(): Attribute[] {
+		const attrs: Attribute[] = [];
+		while (this.isOp("[") && this.isOp("[", 1)) {
+			const start = this.tok.start;
+			this.advance();
+			this.advance();
+			do {
+				const nameTok = this.tok;
+				if (nameTok.kind !== "ident" && nameTok.kind !== "keyword") {
+					this.errorAt({ start: nameTok.start, end: nameTok.end }, "expected attribute name", undefined, "CL1106");
+					throw new ParseAbort();
+				}
+				this.advance();
+				const args: string[] = [];
+				if (this.eatOp("(")) {
+					while (!this.isOp(")") && !this.atEnd()) {
+						const a = this.advance();
+						if (a.text !== ",") {
+							args.push(a.kind === "string" ? String(a.value) : a.text);
+						}
+					}
+					this.expectOp(")");
+				}
+				attrs.push({ name: nameTok.text, args, span: { start: nameTok.start, end: this.prevEnd() } });
+			} while (this.eatOp(","));
+			this.expectOp("]", "to close the attribute");
+			this.expectOp("]", "to close the attribute");
+			if (attrs.length && attrs[attrs.length - 1].span.start < start) {
+				attrs[attrs.length - 1].span.start = start;
+			}
+		}
+		return attrs;
+	}
+
+	private takeDoc(): string | undefined {
+		const doc = this.pendingDoc;
+		this.pendingDoc = undefined;
+		return doc;
+	}
+
+	// ---------- statements ----------
+
+	private block(): Stmt[] {
+		this.expectOp("{", "to open a block");
+		this.depth++;
+		const body: Stmt[] = [];
+		while (!this.isOp("}") && !this.atEnd()) {
+			const before = this.i;
+			const stmt = this.statementSafe(false);
+			if (stmt) {
+				body.push(stmt);
+			} else if (this.i === before) {
+				this.advance();
+			}
+		}
+		this.depth--;
+		this.expectOp("}", "to close the block");
+		return body;
+	}
+
+	private statement(top: boolean): Stmt | null {
+		while (this.tok.kind === "doc") {
+			this.pendingDoc = String(this.tok.value || "");
+			this.advance();
+		}
+		if (this.tok.kind === "directive") {
+			const t = this.advance();
+			this.diags.warning("CL1201", { start: t.start, end: t.end }, `directive '<<!${t.value}' must be at the top of the file; it is ignored here`);
+			return null;
+		}
+		const start = this.tok.start;
+		const attrs = this.attributes();
+		const stmt = this.statementInner(top, attrs);
+		if (stmt && attrs.length) {
+			stmt.attributes = attrs;
+		}
+		if (stmt && stmt.span.start > start) {
+			stmt.span = { start, end: stmt.span.end };
+		}
+		return stmt;
+	}
+
+	private declStmt(decl: Decl): Stmt {
+		return { kind: "Decl", decl, span: decl.span };
+	}
+
+	private statementInner(top: boolean, attrs: Attribute[]): Stmt | null {
+		const t = this.tok;
+		const start = t.start;
+
+		if (t.kind === "op" && t.text === "#") {
+			const lineEnd = this.source.text.indexOf("\n", t.start);
+			const end = lineEnd < 0 ? this.source.text.length : lineEnd;
+			const text = this.source.text.slice(t.start, end).trim();
+			this.errorAt({ start: t.start, end }, `'${text}' is C preprocessor syntax; CL++ 0.9 has no headers or #include`, [
+				"import a module with `link \"./file.clp\" as Name;`",
+				"Roblox types and services come from `link @clpp.roblox;`",
+			], "CL1107");
+			while (!this.atEnd() && this.tok.start < end) {
+				this.advance();
+			}
+			return null;
+		}
+
+		if (t.kind === "op" && t.text === ";") {
+			this.advance();
+			return null;
+		}
+
+		if (t.kind === "keyword") {
+			switch (t.text) {
+				case "static":
+					if (["func", "void", "async", "struct", "enum"].includes(this.peek(1).text)) {
+						this.advance();
+						const inner = this.statementInner(top, attrs);
+						if (inner && inner.kind === "Decl" && inner.decl.kind === "Func") {
+							inner.decl.isStatic = true;
+						}
+						return inner;
+					}
+					break;
+				case "link":
+				case "import":
+				case "from":
+					return this.declStmt(this.link(attrs));
+				case "struct":
+					return this.declStmt(this.struct(attrs, false, false));
+				case "abstract":
+				case "final":
+					if (this.isKw("struct", 1)) {
+						this.advance();
+						return this.declStmt(this.struct(attrs, t.text === "abstract", t.text === "final"));
+					}
+					break;
+				case "enum":
+					return this.declStmt(this.enumDecl(attrs));
+				case "variant":
+					return this.declStmt(this.variant(attrs));
+				case "type":
+					if (this.isIdent(1) && this.isOp("=", 2)) {
+						return this.declStmt(this.typeAlias(attrs));
+					}
+					break;
+				case "namespace":
+					return this.declStmt(this.namespace(attrs));
+				case "func":
+					if (!this.isOp("(", 1)) {
+						return this.declStmt(this.func(attrs, {}));
+					}
+					break;
+				case "async":
+					if (this.isKw("func", 1)) {
+						this.advance();
+						return this.declStmt(this.func(attrs, { isAsync: true }));
+					}
+					break;
+				case "extern":
+					this.advance();
+					if (!this.isKw("func")) {
+						this.errorAt({ start: this.tok.start, end: this.tok.end }, "expected 'func' after 'extern'");
+						throw new ParseAbort();
+					}
+					return this.declStmt(this.func(attrs, { isExtern: true }));
+				case "void":
+					if (this.isIdent(1) && this.isOp("(", 2)) {
+						return this.declStmt(this.voidFunc(attrs));
+					}
+					break;
+				case "signal":
+					return this.signalDecl();
+				case "post":
+				case "cout":
+				case "warn":
+				case "report":
+					if (this.isOp("(", 1)) {
+						return this.output();
+					}
+					break;
+				case "let":
+					return this.letStmt();
+				case "const":
+				case "constexpr":
+				case "auto":
+				case "atomic":
+					return this.keywordDecl(t.text as DeclKind);
+				case "observable":
+					return this.observableDecl();
+				case "decltype":
+					return this.decltypeDecl();
+				case "if":
+					return this.ifStmt();
+				case "while":
+					return this.whileStmt();
+				case "for":
+					return this.forStmt();
+				case "switch":
+					return this.switchStmt();
+				case "match":
+					return this.matchStmt();
+				case "try":
+					return this.tryStmt();
+				case "return": {
+					this.advance();
+					let value: Expr | null = null;
+					if (!this.isOp(";")) {
+						value = this.expression();
+					}
+					this.expectOp(";", "after return");
+					return { kind: "Return", value, span: this.spanFrom(start) };
+				}
+				case "break":
+				case "continue":
+					this.advance();
+					this.expectOp(";", `after ${t.text}`);
+					return { kind: t.text === "break" ? "Break" : "Continue", span: this.spanFrom(start) };
+				case "using":
+					return this.usingStmt();
+				default:
+					break;
+			}
+		}
+
+		if (this.isOp("{")) {
+			const body = this.block();
+			return { kind: "Block", body, span: this.spanFrom(start) };
+		}
+
+		// `Type name = expr;`
+		const typed = this.tryTypedDecl();
+		if (typed) {
+			return typed;
+		}
+
+		return this.exprStatement();
+	}
+
+	private exprStatement(): Stmt {
+		const start = this.tok.start;
+		const expr = this.expression();
+		if (this.tok.kind === "op" && ASSIGN_OPS.has(this.tok.text)) {
+			const op = this.advance().text as "=";
+			const value = this.expression();
+			this.expectOp(";", "after assignment");
+			if (!isPlace(expr)) {
+				this.errorAt(expr.span, "cannot assign to this expression", ["assign to a variable, field (`p.hp`), element (`xs[i]`) or `@field`"], "CL1108");
+			}
+			return { kind: "Assign", target: expr, op, value, span: this.spanFrom(start) };
+		}
+		if (this.isOp("~>")) {
+			this.advance();
+			const handler = this.expression();
+			this.expectOp(";", "after connection");
+			return { kind: "Connect", signal: expr, handler, span: this.spanFrom(start) };
+		}
+		if (!this.isOp(";")) {
+			const t = this.tok;
+			if (t.newlineBefore && !this.atEnd()) {
+				this.errorAt({ start: this.prevEnd(), end: this.prevEnd() + 1 }, "expected ';' at the end of the statement", undefined, "CL1101");
+				return { kind: "Expr", expr, span: this.spanFrom(start) };
+			}
+		}
+		this.expectOp(";", "after expression");
+		return { kind: "Expr", expr, span: this.spanFrom(start) };
+	}
+
+	private output(): Stmt {
+		const start = this.tok.start;
+		const channel = this.advance().text as "post" | "cout" | "warn" | "report";
+		this.expectOp("(");
+		const values: Expr[] = [];
+		if (!this.isOp(")")) {
+			values.push(this.expression());
+			while (this.eatOp(",")) {
+				values.push(this.expression());
+			}
+		}
+		this.expectOp(")");
+		this.expectOp(";", `after ${channel}(...)`);
+		const span = this.spanFrom(start);
+		if (values.length === 0) {
+			values.push({ kind: "String", value: "", span });
+		}
+		if (values.length === 1) {
+			return { kind: "Output", channel, value: values[0], span };
+		}
+		// post(a, b) → print(a, b) on Roblox: keep every argument.
+		const call: Expr = { kind: "Call", callee: { kind: "Name", name: channel === "warn" ? "warn" : "print", typeArgs: null, span }, args: values.map((v) => ({ name: null, value: v })), span };
+		if (channel === "report") {
+			return { kind: "Output", channel, value: values[0], span };
+		}
+		return { kind: "Expr", expr: call, span };
+	}
+
+	private letStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		const mutable = this.eatKw("mut");
+		if (this.isOp("(")) {
+			this.advance();
+			const names: VarName[] = [];
+			do {
+				const n = this.expectName("variable name");
+				names.push({ name: n.text, span: { start: n.start, end: n.end } });
+			} while (this.eatOp(","));
+			this.expectOp(")");
+			this.expectOp("=");
+			const init = this.expression();
+			this.expectOp(";", "after declaration");
+			if (names.length < 2) {
+				this.errorAt(this.spanFrom(start), "destructuring needs at least two names: `let (a, b) = …;`", undefined, "CL1109");
+			}
+			return { kind: "Var", declKind: mutable ? "let mut" : "let", names, unpack: true, declaredType: null, decltypeOf: null, init, span: this.spanFrom(start) };
+		}
+		return this.finishVar(start, mutable ? "let mut" : "let", null, null);
+	}
+
+	private finishVar(start: number, declKind: DeclKind, declaredType: TypeNode | null, decltypeOf: Expr | null): Stmt {
+		const n = this.expectName("variable name");
+		let type = declaredType;
+		if (!type && this.eatOp(":")) {
+			type = this.type();
+		}
+		let init: Expr | null = null;
+		if (this.eatOp("=")) {
+			init = this.expression();
+		} else if (!this.isOp(";")) {
+			this.expectOp("=", "in declaration");
+		}
+		this.expectOp(";", "after declaration");
+		return {
+			kind: "Var",
+			declKind,
+			names: [{ name: n.text, span: { start: n.start, end: n.end } }],
+			unpack: false,
+			declaredType: type,
+			decltypeOf,
+			init,
+			span: this.spanFrom(start),
+		};
+	}
+
+	private keywordDecl(kind: DeclKind): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		return this.finishVar(start, kind, null, null);
+	}
+
+	private observableDecl(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		let type: TypeNode | null = null;
+		const mark = this.i;
+		const maybe = this.tryType();
+		if (maybe && this.isIdent()) {
+			type = maybe;
+		} else {
+			this.i = mark;
+		}
+		return this.finishVar(start, "observable", type, null);
+	}
+
+	private decltypeDecl(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		this.expectOp("(");
+		const of = this.expression();
+		this.expectOp(")");
+		return this.finishVar(start, "decltype", null, of);
+	}
+
+	private tryTypedDecl(): Stmt | null {
+		const t = this.tok;
+		if (t.kind !== "ident" && !(t.kind === "keyword" && TYPE_KEYWORDS.has(t.text) && t.text !== "void")) {
+			return null;
+		}
+		const mark = this.i;
+		const type = this.tryType();
+		if (type && this.isIdent() && (this.isOp("=", 1) || this.isOp(";", 1))) {
+			return this.finishVar(t.start, "typed", type, null);
+		}
+		this.i = mark;
+		return null;
+	}
+
+	private ifStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		this.expectOp("(", "after 'if'");
+		let letName: VarName | null = null;
+		if (this.eatKw("let")) {
+			const n = this.expectName("variable name");
+			letName = { name: n.text, span: { start: n.start, end: n.end } };
+			this.expectOp("=");
+		}
+		const cond = this.expression();
+		this.expectOp(")", "to close the condition");
+		const then = this.block();
+		let elseBody: Stmt[] | null = null;
+		if (this.eatKw("else")) {
+			if (this.isKw("if")) {
+				elseBody = [this.ifStmt()];
+			} else {
+				elseBody = this.block();
+			}
+		}
+		return { kind: "If", cond, letName, then, else: elseBody, span: this.spanFrom(start) };
+	}
+
+	private whileStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		this.expectOp("(", "after 'while'");
+		const cond = this.expression();
+		this.expectOp(")", "to close the condition");
+		const body = this.block();
+		return { kind: "While", cond, body, span: this.spanFrom(start) };
+	}
+
+	private forStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		this.expectOp("(", "after 'for'");
+		// for (let [mut] x in …)
+		if (this.isKw("let")) {
+			const nameAt = this.isKw("mut", 1) ? 2 : 1;
+			if (this.peek(nameAt).kind === "ident" && this.isKw("in", nameAt + 1)) {
+				this.advance();
+				const mutable = this.eatKw("mut");
+				const n = this.expectName("loop variable");
+				this.advance(); // in
+				const iterable = this.expression();
+				this.expectOp(")");
+				const body = this.block();
+				return { kind: "ForIn", name: { name: n.text, span: { start: n.start, end: n.end } }, mutable, iterable, body, span: this.spanFrom(start) };
+			}
+		}
+		// for (Player p in …) — typed loop variable (Cluaupp)
+		{
+			const mark = this.i;
+			const type = this.tryType();
+			if (type && this.isIdent() && this.isKw("in", 1)) {
+				const n = this.advance();
+				this.advance();
+				const iterable = this.expression();
+				this.expectOp(")");
+				const body = this.block();
+				return { kind: "ForIn", name: { name: n.text, span: { start: n.start, end: n.end } }, mutable: false, iterable, body, declaredType: type, span: this.spanFrom(start) };
+			}
+			this.i = mark;
+		}
+		let init: Stmt | null = null;
+		if (this.isOp(";")) {
+			this.advance();
+		} else if (this.isKw("let")) {
+			init = this.letStmt();
+		} else {
+			const typed = this.tryTypedDecl();
+			init = typed ?? this.simpleAssign(true);
+		}
+		let cond: Expr | null = null;
+		if (!this.isOp(";")) {
+			cond = this.expression();
+		}
+		this.expectOp(";", "after the loop condition");
+		let step: Stmt | null = null;
+		if (!this.isOp(")")) {
+			step = this.simpleAssign(false);
+		}
+		this.expectOp(")", "to close the loop header");
+		const body = this.block();
+		return { kind: "For", init, cond, step, body, span: this.spanFrom(start) };
+	}
+
+	/** `x = e` / `x += e` / `x++` with or without the trailing `;`. */
+	private simpleAssign(requireSemicolon: boolean): Stmt {
+		const start = this.tok.start;
+		const target = this.expression();
+		let stmt: Stmt;
+		if (this.tok.kind === "op" && ASSIGN_OPS.has(this.tok.text)) {
+			const op = this.advance().text as "=";
+			const value = this.expression();
+			stmt = { kind: "Assign", target, op, value, span: this.spanFrom(start) };
+		} else {
+			stmt = { kind: "Expr", expr: target, span: this.spanFrom(start) };
+		}
+		if (requireSemicolon) {
+			this.expectOp(";");
+		}
+		return stmt;
+	}
+
+	private switchStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		this.expectOp("(", "after 'switch'");
+		const subject = this.expression();
+		this.expectOp(")");
+		this.expectOp("{");
+		const cases: SwitchCase[] = [];
+		let sawDefault = false;
+		while (!this.isOp("}") && !this.atEnd()) {
+			const caseStart = this.tok.start;
+			let test: Expr | null = null;
+			if (this.eatKw("case")) {
+				test = this.expression();
+			} else if (this.eatKw("default")) {
+				if (sawDefault) {
+					this.errorAt(this.spanFrom(caseStart), "switch already has a default case", undefined, "CL1110");
+				}
+				sawDefault = true;
+			} else {
+				this.errorAt({ start: this.tok.start, end: this.tok.end }, "expected 'case' or 'default'", undefined, "CL1111");
+				throw new ParseAbort();
+			}
+			this.expectOp(":", "after the case label");
+			const body: Stmt[] = [];
+			while (!this.isKw("case") && !this.isKw("default") && !this.isOp("}") && !this.atEnd()) {
+				const before = this.i;
+				const stmt = this.statementSafe(false);
+				if (stmt) {
+					body.push(stmt);
+				} else if (this.i === before) {
+					this.advance();
+				}
+			}
+			cases.push({ test, body, span: this.spanFrom(caseStart) });
+		}
+		this.expectOp("}");
+		return { kind: "Switch", subject, cases, span: this.spanFrom(start) };
+	}
+
+	private matchStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		this.expectOp("(", "after 'match'");
+		const subject = this.expression();
+		this.expectOp(")");
+		this.expectOp("{");
+		const arms: MatchArm[] = [];
+		while (!this.isOp("}") && !this.atEnd()) {
+			const armStart = this.tok.start;
+			try {
+				const pattern = this.pattern();
+				let guard: Expr | null = null;
+				if (this.eatKw("guard")) {
+					guard = this.expression();
+				}
+				this.expectOp("~>", "after the match pattern");
+				let body: Stmt[];
+				if (this.isOp("{")) {
+					body = this.block();
+				} else {
+					const stmt = this.statement(false);
+					body = stmt ? [stmt] : [];
+				}
+				arms.push({ pattern, guard, body, span: this.spanFrom(armStart) });
+			} catch (err) {
+				if (!(err instanceof ParseAbort)) {
+					throw err;
+				}
+				this.synchronize();
+			}
+		}
+		this.expectOp("}");
+		return { kind: "Match", subject, arms, span: this.spanFrom(start) };
+	}
+
+	private pattern(): Pattern {
+		const t = this.tok;
+		if (t.kind === "ident" && t.text === "_" && (this.isOp("~>", 1) || this.isKw("guard", 1))) {
+			this.advance();
+			return { kind: "Wildcard", span: { start: t.start, end: t.end } };
+		}
+		const expr = this.orExpr();
+		const span = expr.span;
+		if (expr.kind === "Name" && !expr.typeArgs) {
+			return { kind: "Case", name: expr.name, qualifier: null, binding: null, span };
+		}
+		if (expr.kind === "Call" && expr.args.length === 1 && expr.args[0].name === null && expr.args[0].value.kind === "Name") {
+			const arg = expr.args[0].value;
+			const binding: VarName = { name: arg.name, span: arg.span };
+			if (expr.callee.kind === "Name") {
+				return { kind: "Case", name: expr.callee.name, qualifier: null, binding, span };
+			}
+			if (expr.callee.kind === "Member") {
+				return { kind: "Case", name: expr.callee.name, qualifier: expr.callee.object, binding, span };
+			}
+		}
+		return { kind: "Value", expr, span };
+	}
+
+	private tryStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		const body = this.block();
+		if (!this.eatKw("catch")) {
+			this.errorAt({ start: this.tok.start, end: this.tok.end }, "expected 'catch' after the try block", undefined, "CL1112");
+			throw new ParseAbort();
+		}
+		let catchName: VarName | null = null;
+		if (this.eatOp("(")) {
+			if (this.isIdent()) {
+				const n = this.advance();
+				catchName = { name: n.text, span: { start: n.start, end: n.end } };
+			}
+			this.expectOp(")");
+		}
+		const handler = this.block();
+		return { kind: "Try", body, catchName, handler, span: this.spanFrom(start) };
+	}
+
+	private usingStmt(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		const mod = this.expectName("module alias");
+		this.expectOp(".");
+		const member = this.expectMemberName();
+		this.expectOp(";");
+		return { kind: "Using", module: mod.text, member: member.text, memberSpan: { start: member.start, end: member.end }, span: this.spanFrom(start) };
+	}
+
+	private signalDecl(): Stmt {
+		const start = this.tok.start;
+		this.advance();
+		const n = this.expectName("signal name");
+		const params: TypeNode[] = [];
+		if (this.eatOp("(")) {
+			if (!this.isOp(")")) {
+				do {
+					params.push(this.type());
+					if (this.isIdent()) {
+						this.advance();
+					}
+				} while (this.eatOp(","));
+			}
+			this.expectOp(")");
+		}
+		this.expectOp(";", "after signal declaration");
+		return { kind: "Signal", name: { name: n.text, span: { start: n.start, end: n.end } }, params, span: this.spanFrom(start) };
+	}
+
+	// ---------- declarations ----------
+
+	private link(attrs: Attribute[]): LinkDecl {
+		const start = this.tok.start;
+		this.advance();
+		let path = "";
+		let isPackage = false;
+		let pathSpan: Span;
+		if (this.isOp("@")) {
+			const at = this.advance();
+			const first = this.expectMemberName();
+			path = `@${first.text}`;
+			while (this.eatOp(".")) {
+				path += `.${this.expectMemberName().text}`;
+			}
+			isPackage = true;
+			pathSpan = { start: at.start, end: this.prevEnd() };
+		} else if (this.tok.kind === "string") {
+			const s = this.advance();
+			path = String(s.value);
+			pathSpan = { start: s.start, end: s.end };
+		} else if (this.isOp("{")) {
+			this.errorAt({ start: this.tok.start, end: this.tok.end }, "named imports `import { A } from \"…\"` were removed in CL++ 0.9", ["use `link \"./file.clp\" as Name;` and refer to `Name.A`"], "CL1113");
+			throw new ParseAbort();
+		} else {
+			this.errorAt({ start: this.tok.start, end: this.tok.end }, "expected a module: `@clpp.roblox` or \"./file.clp\"", undefined, "CL1114");
+			throw new ParseAbort();
+		}
+		let alias = "";
+		let aliasExplicit = false;
+		let aliasSpan = pathSpan;
+		if (this.eatKw("as")) {
+			const a = this.expectName("module alias");
+			alias = a.text;
+			aliasExplicit = true;
+			aliasSpan = { start: a.start, end: a.end };
+		} else {
+			alias = defaultAlias(path);
+		}
+		this.expectOp(";", "after link");
+		if (!alias) {
+			this.errorAt(pathSpan, "cannot name this module; add `as Name`", undefined, "CL1115");
+		}
+		return { kind: "Link", path, isPackage, alias, aliasExplicit, pathSpan, aliasSpan, span: this.spanFrom(start), attributes: attrs };
+	}
+
+	private typeParams(): string[] {
+		const out: string[] = [];
+		if (this.eatOp("<")) {
+			do {
+				out.push(this.expectName("type parameter").text);
+			} while (this.eatOp(","));
+			this.expectOp(">");
+		}
+		return out;
+	}
+
+	private struct(attrs: Attribute[], isAbstract: boolean, isFinal: boolean): StructDecl {
+		const start = this.tok.start;
+		const doc = this.takeDoc();
+		this.advance();
+		const n = this.expectName("struct name");
+		const typeParams = this.typeParams();
+		const bases: TypeNode[] = [];
+		if (this.eatOp(":")) {
+			do {
+				bases.push(this.type());
+			} while (this.eatOp(","));
+		}
+		this.expectOp("{", "to open the struct body");
+		const decl: StructDecl = {
+			kind: "Struct",
+			name: n.text,
+			nameSpan: { start: n.start, end: n.end },
+			span: { start, end: start },
+			typeParams,
+			bases,
+			fields: [],
+			methods: [],
+			isAbstract,
+			isFinal,
+			attributes: attrs,
+			doc,
+		};
+		while (!this.isOp("}") && !this.atEnd()) {
+			try {
+				this.member(decl);
+			} catch (err) {
+				if (!(err instanceof ParseAbort)) {
+					throw err;
+				}
+				this.synchronize();
+			}
+		}
+		this.expectOp("}", "to close the struct");
+		this.eatOp(";");
+		decl.span = this.spanFrom(start);
+		return decl;
+	}
+
+	private member(decl: StructDecl): void {
+		while (this.tok.kind === "doc") {
+			this.pendingDoc = String(this.tok.value || "");
+			this.advance();
+		}
+		const attrs = this.attributes();
+		const mods = { isPrivate: false, isOverride: false, isAbstract: false, isFinal: false, isStatic: false, isAsync: false };
+		for (;;) {
+			if (this.eatKw("private")) {
+				mods.isPrivate = true;
+			} else if (this.eatKw("public")) {
+				mods.isPrivate = false;
+			} else if (this.eatKw("override")) {
+				mods.isOverride = true;
+			} else if (this.eatKw("abstract")) {
+				mods.isAbstract = true;
+			} else if (this.eatKw("final")) {
+				mods.isFinal = true;
+			} else if (this.eatKw("static")) {
+				mods.isStatic = true;
+			} else if (this.isKw("async") && this.isKw("func", 1)) {
+				this.advance();
+				mods.isAsync = true;
+			} else {
+				break;
+			}
+		}
+		if (this.isKw("func")) {
+			const fn = this.func(attrs, mods);
+			if (decl.methods.some((m) => m.name === fn.name)) {
+				this.errorAt(fn.nameSpan, `method '${fn.name}' is already declared in struct ${decl.name}`, undefined, "CL2001");
+				return;
+			}
+			decl.methods.push(fn);
+			return;
+		}
+		if (this.isKw("void") && this.isIdent(1) && this.isOp("(", 2)) {
+			const fn = this.voidFunc(attrs);
+			Object.assign(fn, mods);
+			decl.methods.push(fn);
+			return;
+		}
+		const start = this.tok.start;
+		const doc = this.takeDoc();
+		const type = this.type();
+		const n = this.expectName("field name");
+		let defaultValue: Expr | null = null;
+		if (this.eatOp("=")) {
+			defaultValue = this.expression();
+		}
+		this.expectOp(";", "after field");
+		if (decl.fields.some((f) => f.name === n.text)) {
+			this.errorAt({ start: n.start, end: n.end }, `field '${n.text}' is already declared in struct ${decl.name}`, undefined, "CL2002");
+			return;
+		}
+		const field: FieldDecl = { name: n.text, nameSpan: { start: n.start, end: n.end }, type, isPrivate: mods.isPrivate, span: this.spanFrom(start), doc };
+		if (defaultValue) {
+			field.defaultValue = defaultValue;
+		}
+		decl.fields.push(field);
+	}
+
+	private enumDecl(attrs: Attribute[]): EnumDecl {
+		const start = this.tok.start;
+		const doc = this.takeDoc();
+		this.advance();
+		const n = this.expectName("enum name");
+		this.expectOp("{");
+		const cases: EnumDecl["cases"] = [];
+		while (!this.isOp("}") && !this.atEnd()) {
+			const c = this.expectName("enum case");
+			let payload: TypeNode | null = null;
+			if (this.eatOp("(")) {
+				payload = this.type();
+				this.expectOp(")");
+			}
+			if (cases.some((x) => x.name === c.text)) {
+				this.errorAt({ start: c.start, end: c.end }, `case '${c.text}' is already declared in enum ${n.text}`, undefined, "CL2003");
+			} else {
+				cases.push({ name: c.text, span: { start: c.start, end: c.end }, payload });
+			}
+			if (!this.eatOp(",")) {
+				break;
+			}
+		}
+		this.expectOp("}", "to close the enum");
+		this.eatOp(";");
+		return { kind: "Enum", name: n.text, nameSpan: { start: n.start, end: n.end }, span: this.spanFrom(start), cases, attributes: attrs, doc };
+	}
+
+	private variant(attrs: Attribute[]): VariantDecl {
+		const start = this.tok.start;
+		this.advance();
+		const n = this.expectName("variant name");
+		this.expectOp("{");
+		const alternatives: TypeNode[] = [];
+		while (!this.isOp("}") && !this.atEnd()) {
+			alternatives.push(this.type());
+			if (!this.eatOp(",")) {
+				break;
+			}
+		}
+		this.expectOp("}");
+		this.eatOp(";");
+		if (alternatives.length === 0) {
+			this.errorAt(this.spanFrom(start), "a variant needs at least one type", undefined, "CL1116");
+		}
+		return { kind: "Variant", name: n.text, nameSpan: { start: n.start, end: n.end }, span: this.spanFrom(start), alternatives, attributes: attrs };
+	}
+
+	private typeAlias(attrs: Attribute[]): TypeAliasDecl {
+		const start = this.tok.start;
+		this.advance();
+		const n = this.expectName("type name");
+		this.expectOp("=");
+		const type = this.type();
+		this.expectOp(";", "after type alias");
+		return { kind: "TypeAlias", name: n.text, nameSpan: { start: n.start, end: n.end }, span: this.spanFrom(start), type, attributes: attrs };
+	}
+
+	private namespace(attrs: Attribute[]): NamespaceDecl {
+		const start = this.tok.start;
+		this.advance();
+		const n = this.expectName("namespace name");
+		this.expectOp("{");
+		const funcs: FuncDecl[] = [];
+		while (!this.isOp("}") && !this.atEnd()) {
+			try {
+				const fattrs = this.attributes();
+				const isStatic = this.eatKw("static");
+				const isAsync = this.isKw("async") && this.isKw("func", 1) ? (this.advance(), true) : false;
+				if (this.isKw("func")) {
+					funcs.push(this.func(fattrs, { isAsync, isStatic }));
+				} else if (this.isKw("void") && this.isIdent(1)) {
+					funcs.push(this.voidFunc(fattrs));
+				} else {
+					this.errorAt({ start: this.tok.start, end: this.tok.end }, "a namespace can only contain functions", undefined, "CL1117");
+					throw new ParseAbort();
+				}
+			} catch (err) {
+				if (!(err instanceof ParseAbort)) {
+					throw err;
+				}
+				this.synchronize();
+			}
+		}
+		this.expectOp("}");
+		return { kind: "Namespace", name: n.text, nameSpan: { start: n.start, end: n.end }, span: this.spanFrom(start), funcs, attributes: attrs };
+	}
+
+	private func(attrs: Attribute[], mods: Partial<FuncDecl>): FuncDecl {
+		const start = this.tok.start;
+		const doc = this.takeDoc();
+		this.advance(); // func
+		let name: string;
+		let nameSpan: Span;
+		let operator: FuncDecl["operator"] = null;
+		if (this.eatKw("operator")) {
+			const sig = this.tok;
+			if (this.eatOp("+")) {
+				operator = "+";
+			} else if (this.eatOp("-")) {
+				operator = "-";
+			} else if (this.eatOp("[")) {
+				this.expectOp("]");
+				operator = "[]";
+			} else {
+				this.errorAt({ start: sig.start, end: sig.end }, "expected '+', '-' or '[]' after 'operator'", undefined, "CL1118");
+				throw new ParseAbort();
+			}
+			name = `operator${operator}`;
+			nameSpan = { start: sig.start, end: this.prevEnd() };
+		} else {
+			const n = this.expectName("function name");
+			name = n.text;
+			nameSpan = { start: n.start, end: n.end };
+		}
+		const typeParams = this.typeParams();
+		const params = this.params();
+		let returnType: TypeNode | null = null;
+		if (this.eatOp("->")) {
+			returnType = this.type();
+		}
+		const where: FuncDecl["where"] = [];
+		if (this.eatKw("where")) {
+			do {
+				const w = this.expectName("type parameter");
+				this.expectOp(":");
+				where.push({ name: w.text, type: this.type() });
+			} while (this.eatOp(","));
+		}
+		let body: Stmt[] | null = null;
+		if (this.isOp("{")) {
+			body = this.block();
+		} else {
+			this.expectOp(";", "or a body `{ … }` after the function signature");
+		}
+		return {
+			kind: "Func",
+			name,
+			nameSpan,
+			span: this.spanFrom(start),
+			typeParams,
+			params,
+			returnType,
+			body,
+			isAsync: false,
+			isExtern: false,
+			isStatic: false,
+			isAbstract: false,
+			isOverride: false,
+			isFinal: false,
+			isPrivate: false,
+			operator,
+			where,
+			attributes: attrs,
+			doc,
+			...mods,
+		};
+	}
+
+	private voidFunc(attrs: Attribute[]): FuncDecl {
+		const start = this.tok.start;
+		const doc = this.takeDoc();
+		this.advance(); // void
+		const n = this.expectName("function name");
+		const params = this.params();
+		const body = this.block();
+		return {
+			kind: "Func",
+			name: n.text,
+			nameSpan: { start: n.start, end: n.end },
+			span: this.spanFrom(start),
+			typeParams: [],
+			params,
+			returnType: { kind: "Named", name: "void", args: [], span: { start, end: start + 4 } },
+			body,
+			isAsync: false,
+			isExtern: false,
+			isStatic: false,
+			isAbstract: false,
+			isOverride: false,
+			isFinal: false,
+			isPrivate: false,
+			operator: null,
+			where: [],
+			attributes: attrs,
+			doc,
+		};
+	}
+
+	private params(): Param[] {
+		this.expectOp("(", "to open the parameter list");
+		const params: Param[] = [];
+		if (!this.isOp(")")) {
+			do {
+				const pStart = this.tok.start;
+				let type: TypeNode | null = null;
+				const mark = this.i;
+				const maybe = this.tryType();
+				if (maybe && (this.isIdent() || this.isOp("..."))) {
+					type = maybe;
+				} else {
+					this.i = mark;
+				}
+				const variadic = this.eatOp("...");
+				const n = this.expectName("parameter name");
+				let defaultValue: Expr | null = null;
+				if (this.eatOp("=")) {
+					defaultValue = this.expression();
+				}
+				params.push({ name: n.text, span: { start: n.start, end: n.end }, type, variadic, defaultValue });
+				if (variadic && this.isOp(",")) {
+					this.errorAt(this.spanFrom(pStart), "the variadic parameter must be the last one", undefined, "CL1119");
+				}
+			} while (this.eatOp(","));
+		}
+		this.expectOp(")", "to close the parameter list");
+		return params;
+	}
+
+	// ---------- types ----------
+
+	/** Type or an error. */
+	private type(): TypeNode {
+		const t = this.tok;
+		const type = this.tryType();
+		if (!type) {
+			this.errorAt({ start: t.start, end: Math.max(t.end, t.start + 1) }, "expected a type", undefined, "CL1120");
+			throw new ParseAbort();
+		}
+		return type;
+	}
+
+	/** Speculative type parse: returns null (and restores nothing) on failure. Never reports. */
+	private tryType(): TypeNode | null {
+		const start = this.tok.start;
+		const first = this.typeAtom();
+		if (!first) {
+			return null;
+		}
+		if (this.isOp("|") || this.isOp("&")) {
+			const op = this.tok.text;
+			const members = [first];
+			while (this.isOp(op)) {
+				const mark = this.i;
+				this.advance();
+				const next = this.typeAtom();
+				if (!next) {
+					this.i = mark;
+					break;
+				}
+				members.push(next);
+			}
+			if (members.length > 1) {
+				return { kind: op === "|" ? "Union" : "Intersection", members, span: this.spanFrom(start) };
+			}
+		}
+		return first;
+	}
+
+	private typeAtom(): TypeNode | null {
+		const t = this.tok;
+		const start = t.start;
+		let node: TypeNode | null = null;
+		if (t.kind === "string") {
+			this.advance();
+			node = { kind: "Literal", value: String(t.value), span: { start, end: t.end } };
+		} else if (t.kind === "int" || t.kind === "float") {
+			this.advance();
+			node = { kind: "Literal", value: Number(t.value), span: { start, end: t.end } };
+		} else if (t.kind === "keyword" && (t.text === "true" || t.text === "false")) {
+			this.advance();
+			node = { kind: "Literal", value: t.text === "true", span: { start, end: t.end } };
+		} else if (t.kind === "keyword" && t.text === "null") {
+			this.advance();
+			node = { kind: "Named", name: "null", args: [], span: { start, end: t.end } };
+		} else if (t.kind === "keyword" && t.text === "func" && this.isOp("(", 1)) {
+			this.advance();
+			this.advance();
+			const params: TypeNode[] = [];
+			if (!this.isOp(")")) {
+				do {
+					const p = this.tryType();
+					if (!p) {
+						return null;
+					}
+					params.push(p);
+					if (this.isIdent()) {
+						this.advance();
+					}
+				} while (this.eatOp(","));
+			}
+			if (!this.eatOp(")")) {
+				return null;
+			}
+			let ret: TypeNode | null = null;
+			if (this.eatOp("->")) {
+				ret = this.typeAtom();
+				if (!ret) {
+					return null;
+				}
+			}
+			node = { kind: "Func", params, ret, span: this.spanFrom(start) };
+		} else if (t.kind === "op" && t.text === "(") {
+			const mark = this.i;
+			this.advance();
+			const inner = this.tryType();
+			if (!inner || !this.eatOp(")")) {
+				this.i = mark;
+				return null;
+			}
+			node = inner;
+		} else if (t.kind === "ident" || (t.kind === "keyword" && TYPE_KEYWORDS.has(t.text))) {
+			this.advance();
+			let name = t.text;
+			let qualifier: string | undefined;
+			while (this.isOp(".") && (this.peek(1).kind === "ident" || this.peek(1).kind === "keyword")) {
+				// `Combat.Fighter`, `Enum.Material`
+				if (this.peek(1).kind === "keyword" && !TYPE_KEYWORDS.has(this.peek(1).text)) {
+					break;
+				}
+				this.advance();
+				qualifier = qualifier ? `${qualifier}.${name}` : name;
+				name = this.advance().text;
+			}
+			const args: TypeNode[] = [];
+			if (this.isOp("<")) {
+				const mark = this.i;
+				this.advance();
+				let ok = true;
+				if (!this.isOp(">")) {
+					do {
+						const arg = this.tryType();
+						if (!arg) {
+							ok = false;
+							break;
+						}
+						args.push(arg);
+					} while (this.eatOp(","));
+				}
+				if (!ok || !this.eatOp(">")) {
+					this.i = mark;
+					args.length = 0;
+					return null;
+				}
+			}
+			node = { kind: "Named", name, args, span: this.spanFrom(start) };
+			if (qualifier) {
+				node.qualifier = qualifier;
+			}
+		} else {
+			return null;
+		}
+		while (this.isOp("?")) {
+			// `Part?` — but not the ternary `cond ? a : b` (type contexts never see that).
+			this.advance();
+			node = { kind: "Optional", inner: node, span: this.spanFrom(start) };
+		}
+		return node;
+	}
+
+	// ---------- expressions ----------
+
+	expression(): Expr {
+		const cond = this.orExpr();
+		if (this.isOp("?")) {
+			this.advance();
+			const then = this.expression();
+			this.expectOp(":", "in the ternary expression");
+			const otherwise = this.expression();
+			return { kind: "Ternary", cond, then, else: otherwise, span: { start: cond.span.start, end: otherwise.span.end } };
+		}
+		return cond;
+	}
+
+	private binary(op: BinaryOp, left: Expr, right: Expr, opTok: Token): Expr {
+		return { kind: "Binary", op, left, right, opSpan: { start: opTok.start, end: opTok.end }, span: { start: left.span.start, end: right.span.end } };
+	}
+
+	private orExpr(): Expr {
+		let left = this.andExpr();
+		while (this.isKw("or") || this.isOp("||")) {
+			const op = this.advance();
+			left = this.binary("or", left, this.andExpr(), op);
+		}
+		return left;
+	}
+
+	private andExpr(): Expr {
+		let left = this.bitOr();
+		while (this.isKw("and") || this.isOp("&&")) {
+			const op = this.advance();
+			left = this.binary("and", left, this.bitOr(), op);
+		}
+		return left;
+	}
+
+	private bitOr(): Expr {
+		let left = this.bitXor();
+		while (this.isOp("|")) {
+			const op = this.advance();
+			left = this.binary("|", left, this.bitXor(), op);
+		}
+		return left;
+	}
+
+	private bitXor(): Expr {
+		let left = this.bitAnd();
+		while (this.isOp("^")) {
+			const op = this.advance();
+			left = this.binary("^", left, this.bitAnd(), op);
+		}
+		return left;
+	}
+
+	private bitAnd(): Expr {
+		let left = this.shift();
+		while (this.isOp("&")) {
+			const op = this.advance();
+			left = this.binary("&", left, this.shift(), op);
+		}
+		return left;
+	}
+
+	private shift(): Expr {
+		let left = this.unary();
+		while (this.isKw("shl") || this.isKw("shr")) {
+			const op = this.advance();
+			left = this.binary(op.text as "shl", left, this.unary(), op);
+		}
+		return left;
+	}
+
+	/** CL++ unary level: the operand is everything up to `shl`/`shr`. */
+	private unary(): Expr {
+		const t = this.tok;
+		const start = t.start;
+		if (t.kind === "op" && (t.text === "-" || t.text === "~" || t.text === "!")) {
+			this.advance();
+			const operand = this.unary();
+			const op = t.text === "!" ? "not" : (t.text as "-" | "~");
+			return { kind: "Unary", op, operand, loose: true, span: { start, end: operand.span.end } };
+		}
+		if (t.kind === "keyword") {
+			switch (t.text) {
+				case "not": {
+					this.advance();
+					const operand = this.unary();
+					return { kind: "Unary", op: "not", operand, loose: true, span: { start, end: operand.span.end } };
+				}
+				case "spawn": {
+					this.advance();
+					const call = this.unary();
+					return { kind: "Spawn", call, span: { start, end: call.span.end } };
+				}
+				case "await": {
+					this.advance();
+					const operand = this.unary();
+					return { kind: "Await", operand, span: { start, end: operand.span.end } };
+				}
+				case "thread": {
+					if (this.isOp(".", 1) || this.isOp("::", 1)) {
+						break;
+					}
+					this.advance();
+					const call = this.unary();
+					return { kind: "Thread", call, span: { start, end: call.span.end } };
+				}
+				case "new":
+					return this.newExpr();
+				default:
+					break;
+			}
+		}
+		if (t.kind === "op" && (t.text === "++" || t.text === "--")) {
+			this.advance();
+			const target = this.unary();
+			return { kind: "Update", target, delta: t.text === "++" ? 1 : -1, prefix: true, span: { start, end: target.span.end } };
+		}
+		return this.comparison();
+	}
+
+	private newExpr(): Expr {
+		const start = this.tok.start;
+		this.advance();
+		const target = this.primary(true);
+		if (this.isOp("(")) {
+			const args = this.args();
+			return this.postfix({ kind: "New", target, args, hasParens: true, span: this.spanFrom(start) });
+		}
+		return { kind: "New", target, args: [], hasParens: false, span: this.spanFrom(start) };
+	}
+
+	private comparison(): Expr {
+		let left = this.additive();
+		for (;;) {
+			const t = this.tok;
+			if (t.kind === "op" && (t.text === "==" || t.text === "!=" || t.text === "<" || t.text === "<=" || t.text === ">" || t.text === ">=")) {
+				this.advance();
+				left = this.binary(t.text as BinaryOp, left, this.additive(), t);
+				continue;
+			}
+			return left;
+		}
+	}
+
+	private additive(): Expr {
+		let left = this.multiplicative();
+		for (;;) {
+			const t = this.tok;
+			if (t.kind === "op" && (t.text === "+" || t.text === "-" || t.text === ".:" || t.text === "..")) {
+				this.advance();
+				left = this.binary(t.text as BinaryOp, left, this.multiplicative(), t);
+				continue;
+			}
+			return left;
+		}
+	}
+
+	private multiplicative(): Expr {
+		let left = this.operand();
+		for (;;) {
+			const t = this.tok;
+			if (t.kind === "op" && (t.text === "*" || t.text === "/" || t.text === "%")) {
+				this.advance();
+				left = this.binary(t.text as BinaryOp, left, this.operand(), t);
+				continue;
+			}
+			return left;
+		}
+	}
+
+	/** Operand of `*`, `+`, comparisons: a postfix expression, or a tight prefix operator (Cluaupp). */
+	private operand(): Expr {
+		const t = this.tok;
+		const start = t.start;
+		if (t.kind === "op" && (t.text === "-" || t.text === "~" || t.text === "!")) {
+			this.advance();
+			const inner = this.operand();
+			return { kind: "Unary", op: t.text === "!" ? "not" : (t.text as "-" | "~"), operand: inner, loose: false, span: { start, end: inner.span.end } };
+		}
+		if (t.kind === "keyword" && t.text === "not") {
+			this.advance();
+			const inner = this.operand();
+			return { kind: "Unary", op: "not", operand: inner, loose: false, span: { start, end: inner.span.end } };
+		}
+		if (t.kind === "keyword" && (t.text === "await" || t.text === "spawn")) {
+			this.advance();
+			const inner = this.operand();
+			return t.text === "await" ? { kind: "Await", operand: inner, span: { start, end: inner.span.end } } : { kind: "Spawn", call: inner, span: { start, end: inner.span.end } };
+		}
+		if (t.kind === "keyword" && t.text === "new") {
+			return this.newExpr();
+		}
+		return this.postfix(this.primary(false));
+	}
+
+	private args(): Arg[] {
+		this.expectOp("(");
+		const args: Arg[] = [];
+		if (!this.isOp(")")) {
+			do {
+				if (this.isOp(")")) {
+					break; // trailing comma
+				}
+				if ((this.tok.kind === "ident" || this.tok.kind === "keyword") && this.isOp(":", 1) && !this.isOp("::", 1)) {
+					const n = this.advance();
+					this.advance();
+					args.push({ name: n.text, nameSpan: { start: n.start, end: n.end }, value: this.expression() });
+				} else {
+					args.push({ name: null, value: this.expression() });
+				}
+			} while (this.eatOp(","));
+		}
+		this.expectOp(")", "to close the argument list");
+		return args;
+	}
+
+	/** `<T, U>` immediately followed by `(` — a generic call. Restores position when it is not. */
+	private tryCallTypeArgs(): TypeNode[] | null {
+		if (!this.isOp("<")) {
+			return null;
+		}
+		const mark = this.i;
+		this.advance();
+		const args: TypeNode[] = [];
+		if (!this.isOp(">")) {
+			do {
+				const t = this.tryType();
+				if (!t) {
+					this.i = mark;
+					return null;
+				}
+				args.push(t);
+			} while (this.eatOp(","));
+		}
+		if (!this.eatOp(">") || !this.isOp("(")) {
+			this.i = mark;
+			return null;
+		}
+		return args;
+	}
+
+	private postfix(expr: Expr): Expr {
+		for (;;) {
+			const t = this.tok;
+			if (t.kind === "op") {
+				if (t.text === ".") {
+					this.advance();
+					const n = this.expectMemberName();
+					const typeArgs = this.tryCallTypeArgs();
+					expr = { kind: "Member", object: expr, name: n.text, nameSpan: { start: n.start, end: n.end }, typeArgs, span: { start: expr.span.start, end: n.end } };
+					continue;
+				}
+				if (t.text === "::") {
+					this.advance();
+					const n = this.expectMemberName();
+					expr = { kind: "Scope", object: expr, name: n.text, nameSpan: { start: n.start, end: n.end }, span: { start: expr.span.start, end: n.end } };
+					continue;
+				}
+				if (t.text === "[") {
+					if (this.isOp("[", 1) && expr.kind !== "Index") {
+						// `[[attr]]` never follows an expression; treat as index anyway.
+					}
+					this.advance();
+					const index = this.expression();
+					this.expectOp("]", "to close the index");
+					expr = { kind: "Index", object: expr, index, span: this.spanFrom(expr.span.start) };
+					continue;
+				}
+				if (t.text === "(") {
+					const args = this.args();
+					expr = { kind: "Call", callee: expr, args, span: this.spanFrom(expr.span.start) };
+					continue;
+				}
+				if (t.text === "++" || t.text === "--") {
+					this.advance();
+					expr = { kind: "Update", target: expr, delta: t.text === "++" ? 1 : -1, prefix: false, span: this.spanFrom(expr.span.start) };
+					continue;
+				}
+				if (t.text === "~>" && (this.peek(1).kind === "ident") && LEGACY_SIGNAL_METHODS.has(this.peek(1).text) && this.isOp("(", 2)) {
+					// Cluaupp 1.x `signal~>Connect(fn)` → `signal.Connect(fn)`
+					this.advance();
+					const n = this.advance();
+					const member: Expr = { kind: "Member", object: expr, name: n.text, nameSpan: { start: n.start, end: n.end }, typeArgs: null, span: { start: expr.span.start, end: n.end } };
+					const args = this.args();
+					expr = { kind: "Call", callee: member, args, legacyConnect: true, span: this.spanFrom(expr.span.start) };
+					continue;
+				}
+			}
+			if (t.kind === "keyword" && t.text === "as" && !t.newlineBefore) {
+				this.advance();
+				const type = this.type();
+				return { kind: "Cast", operand: expr, type, span: this.spanFrom(expr.span.start) };
+			}
+			return expr;
+		}
+	}
+
+	private primary(forNew: boolean): Expr {
+		const t = this.tok;
+		const start = t.start;
+		const span = { start, end: t.end };
+		switch (t.kind) {
+			case "int":
+			case "float":
+				this.advance();
+				return { kind: "Number", value: Number(t.value), isFloat: t.kind === "float", raw: t.text, span };
+			case "string":
+				this.advance();
+				return { kind: "String", value: String(t.value ?? ""), span };
+			case "template":
+				this.advance();
+				return this.template(t);
+			case "ident": {
+				if (this.isOp("=>", 1)) {
+					return this.lambdaSingle();
+				}
+				this.advance();
+				const typeArgs = this.tryCallTypeArgs();
+				return { kind: "Name", name: t.text, typeArgs, span };
+			}
+			case "keyword":
+				return this.keywordPrimary(t, forNew);
+			case "op":
+				if (t.text === "(") {
+					const lambda = this.tryLambdaParens();
+					if (lambda) {
+						return lambda;
+					}
+					this.advance();
+					const inner = this.expression();
+					this.expectOp(")", "to close the parenthesis");
+					return inner;
+				}
+				if (t.text === "@") {
+					this.advance();
+					let n = this.expectMemberName();
+					if (n.text === "this") {
+						if (!this.eatOp(".") && !this.eatOp("::")) {
+							this.errorAt({ start: this.tok.start, end: this.tok.end }, "expected '.' after '@this'", undefined, "CL1121");
+							throw new ParseAbort();
+						}
+						n = this.expectMemberName();
+					}
+					return { kind: "SelfField", name: n.text, nameSpan: { start: n.start, end: n.end }, span: { start, end: n.end } };
+				}
+				break;
+			default:
+				break;
+		}
+		const where = t.kind === "eof" ? "end of file" : `'${t.text}'`;
+		this.errorAt({ start: t.start, end: Math.max(t.end, t.start + 1) }, `expected an expression, found ${where}`, undefined, "CL1122");
+		throw new ParseAbort();
+	}
+
+	private keywordPrimary(t: Token, forNew: boolean): Expr {
+		const start = t.start;
+		const span = { start, end: t.end };
+		switch (t.text) {
+			case "true":
+			case "false":
+				this.advance();
+				return { kind: "Bool", value: t.text === "true", span };
+			case "null":
+				this.advance();
+				return { kind: "Null", span };
+			case "endl":
+				this.advance();
+				return { kind: "String", value: "\n", span };
+			case "func": {
+				if (this.isOp("(", 1)) {
+					this.advance();
+					const params = this.params();
+					let returnType: TypeNode | null = null;
+					if (this.eatOp("->")) {
+						returnType = this.type();
+					}
+					const body = this.block();
+					return { kind: "Function", params, returnType, body, isLambda: false, span: this.spanFrom(start) };
+				}
+				break;
+			}
+			case "parallel": {
+				this.advance();
+				const args = this.args();
+				if (args.length < 1) {
+					this.errorAt(this.spanFrom(start), "parallel(...) needs at least one call", undefined, "CL1123");
+				}
+				return { kind: "Parallel", calls: args.map((a) => a.value), span: this.spanFrom(start) };
+			}
+			case "pcall":
+			case "move":
+			case "join": {
+				this.advance();
+				this.expectOp("(", `after '${t.text}'`);
+				const operand = this.expression();
+				this.expectOp(")");
+				const s = this.spanFrom(start);
+				if (t.text === "pcall") {
+					return { kind: "PCall", operand, span: s };
+				}
+				if (t.text === "move") {
+					return { kind: "Move", operand, span: s };
+				}
+				return { kind: "Join", operand, span: s };
+			}
+			default:
+				break;
+		}
+		// Type keywords used as values: Vector3(…), int(x), string.format, task.wait, buffer::create, type(x)
+		if (TYPE_KEYWORDS.has(t.text) || VALUE_KEYWORDS.has(t.text)) {
+			if (forNew || this.isOp("(", 1) || this.isOp(".", 1) || this.isOp("::", 1) || this.isOp("<", 1)) {
+				this.advance();
+				const typeArgs = this.tryCallTypeArgs();
+				return { kind: "Name", name: t.text, typeArgs, span };
+			}
+		}
+		const message = KEYWORDS.has(t.text) ? `'${t.text}' cannot start an expression here` : `unexpected '${t.text}'`;
+		this.errorAt(span, message, undefined, "CL1124");
+		throw new ParseAbort();
+	}
+
+	private lambdaSingle(): Expr {
+		const n = this.advance();
+		this.advance(); // =>
+		const params: Param[] = [{ name: n.text, span: { start: n.start, end: n.end }, type: null, variadic: false, defaultValue: null }];
+		const body = this.isOp("{") ? this.block() : this.expression();
+		return { kind: "Function", params, returnType: null, body, isLambda: true, span: this.spanFrom(n.start) };
+	}
+
+	/** `(a, b) => expr` / `(int a) => expr` (Cluaupp). */
+	private tryLambdaParens(): Expr | null {
+		const mark = this.i;
+		const start = this.tok.start;
+		// fast reject: scan for `) =>` at depth 0
+		let depth = 0;
+		let j = 0;
+		for (;; j++) {
+			const t = this.peek(j);
+			if (t.kind === "eof") {
+				return null;
+			}
+			if (t.kind === "op") {
+				if (t.text === "(") {
+					depth++;
+				} else if (t.text === ")") {
+					depth--;
+					if (depth === 0) {
+						break;
+					}
+				} else if (t.text === ";" || t.text === "{" || t.text === "}") {
+					return null;
+				}
+			}
+		}
+		if (!this.isOp("=>", j + 1)) {
+			return null;
+		}
+		try {
+			const params = this.params();
+			this.expectOp("=>");
+			const body = this.isOp("{") ? this.block() : this.expression();
+			return { kind: "Function", params, returnType: null, body, isLambda: true, span: this.spanFrom(start) };
+		} catch (err) {
+			if (!(err instanceof ParseAbort)) {
+				throw err;
+			}
+			this.i = mark;
+			return null;
+		}
+	}
+
+	private template(t: Token): Expr {
+		const parts: Array<string | Expr> = [];
+		for (const part of t.parts || []) {
+			if (part.text !== undefined) {
+				parts.push(part.text);
+				continue;
+			}
+			if (!part.hole) {
+				continue;
+			}
+			const hole = part.hole;
+			if (this.source.text.slice(hole.start, hole.end).trim() === "") {
+				this.errorAt({ start: hole.start - 2, end: hole.end + 1 }, "empty interpolation `${}`", undefined, "CL1125");
+				continue;
+			}
+			const tokens = tokenize(this.source.text, this.diags, hole.start, hole.end);
+			const sub = new Parser(this.source, this.diags, tokens);
+			try {
+				const expr = sub.expression();
+				if (!sub.atEnd()) {
+					this.errorAt({ start: sub.tok.start, end: sub.tok.end }, "unexpected text in interpolation", undefined, "CL1126");
+				}
+				parts.push(expr);
+			} catch (err) {
+				if (!(err instanceof ParseAbort)) {
+					throw err;
+				}
+			}
+		}
+		return { kind: "Template", parts, span: { start: t.start, end: t.end } };
+	}
+}
+
+export function isPlace(expr: Expr): boolean {
+	switch (expr.kind) {
+		case "Name":
+			return !expr.typeArgs;
+		case "SelfField":
+			return true;
+		case "Member":
+			return !expr.typeArgs;
+		case "Index":
+			return true;
+		default:
+			return false;
+	}
+}
+
+export function parse(source: SourceFile, diags: DiagnosticBag): Program {
+	return new Parser(source, diags).parseProgram();
+}