cluaupp 1.5.2 → 2.0.0-beta.1

package/src/api/surface/luau-defs.ts

@@ -0,0 +1,635 @@
+/**
+ * Parser for Luau definition files (`*.d.luau`, the luau-lsp format):
+ * `declare extern type X [extends Y] with … end`, `declare name: Type`, `declare function f(…): R`,
+ * `type Alias = Type`, `export type Alias<T> = Type`, `@deprecated` / `@[deprecated {use = "…"}]`.
+ */
+
+import type { LFn, LParam, LType } from "./model.js";
+
+interface Tok {
+	t: "name" | "string" | "number" | "op" | "eof";
+	v: string;
+	line: number;
+}
+
+const OPS = ["...", "->", "::", "@[", "(", ")", "{", "}", "[", "]", "<", ">", ",", ":", ";", "?", "|", "&", "=", ".", "@"];
+
+function lex(text: string): Tok[] {
+	const out: Tok[] = [];
+	let i = 0;
+	let line = 1;
+	while (i < text.length) {
+		const c = text[i];
+		if (c === "\n") {
+			line++;
+			i++;
+			continue;
+		}
+		if (c === " " || c === "\t" || c === "\r") {
+			i++;
+			continue;
+		}
+		if (c === "-" && text[i + 1] === "-") {
+			if (text.startsWith("--[[", i) || text.startsWith("--[=[", i)) {
+				const close = text.indexOf("]]", i);
+				const chunk = text.slice(i, close < 0 ? text.length : close + 2);
+				line += chunk.split("\n").length - 1;
+				i = close < 0 ? text.length : close + 2;
+				continue;
+			}
+			while (i < text.length && text[i] !== "\n") {
+				i++;
+			}
+			continue;
+		}
+		if (/[A-Za-z_]/.test(c)) {
+			let j = i + 1;
+			while (j < text.length && /[A-Za-z0-9_]/.test(text[j])) {
+				j++;
+			}
+			out.push({ t: "name", v: text.slice(i, j), line });
+			i = j;
+			continue;
+		}
+		if (/[0-9]/.test(c)) {
+			let j = i + 1;
+			while (j < text.length && /[0-9.]/.test(text[j])) {
+				j++;
+			}
+			out.push({ t: "number", v: text.slice(i, j), line });
+			i = j;
+			continue;
+		}
+		if (c === '"' || c === "'") {
+			let j = i + 1;
+			while (j < text.length && text[j] !== c) {
+				if (text[j] === "\\") {
+					j++;
+				}
+				j++;
+			}
+			out.push({ t: "string", v: text.slice(i + 1, j), line });
+			i = j + 1;
+			continue;
+		}
+		const op = OPS.find((o) => text.startsWith(o, i));
+		if (op) {
+			out.push({ t: "op", v: op, line });
+			i += op.length;
+			continue;
+		}
+		i++;
+	}
+	out.push({ t: "eof", v: "", line });
+	return out;
+}
+
+export interface ExternMember {
+	name: string;
+	type?: LType;
+	fn?: LFn;
+	deprecated?: string | true;
+}
+
+export interface ExternType {
+	name: string;
+	extends: string | null;
+	members: ExternMember[];
+	line: number;
+}
+
+export interface DefinitionFile {
+	metadata: Record<string, unknown>;
+	externs: ExternType[];
+	/** `declare name: Type` and `declare function name(…)` */
+	declares: Array<{ name: string; type: LType; deprecated?: string | true }>;
+	aliases: Record<string, LType>;
+	aliasParams: Record<string, string[]>;
+}
+
+class DefParser {
+	private i = 0;
+	/** Defaults of the generic parameters read last (`<T = BasePart>`). */
+	lastDefaults: Record<string, LType> = {};
+
+	constructor(private readonly toks: Tok[]) {}
+
+	private peek(n = 0): Tok {
+		return this.toks[Math.min(this.i + n, this.toks.length - 1)];
+	}
+
+	private next(): Tok {
+		return this.toks[this.i++] ?? this.toks[this.toks.length - 1];
+	}
+
+	private is(v: string, n = 0): boolean {
+		const t = this.peek(n);
+		return (t.t === "op" || t.t === "name") && t.v === v;
+	}
+
+	private eat(v: string): boolean {
+		if (this.is(v)) {
+			this.i++;
+			return true;
+		}
+		return false;
+	}
+
+	private expect(v: string): void {
+		if (!this.eat(v)) {
+			const t = this.peek();
+			throw new Error(`definitions: expected '${v}' at line ${t.line}, found '${t.v}'`);
+		}
+	}
+
+	private name(): string {
+		const t = this.next();
+		if (t.t !== "name") {
+			throw new Error(`definitions: expected name at line ${t.line}, found '${t.v}'`);
+		}
+		return t.v;
+	}
+
+	file(): DefinitionFile {
+		const out: DefinitionFile = { metadata: {}, externs: [], declares: [], aliases: {}, aliasParams: {} };
+		while (this.peek().t !== "eof") {
+			const deprecated = this.attributes();
+			if (this.is("declare")) {
+				this.next();
+				if (this.is("extern")) {
+					this.next();
+					this.expect("type");
+					out.externs.push(this.externType());
+					continue;
+				}
+				if (this.is("class")) {
+					this.next();
+					out.externs.push(this.externType(true));
+					continue;
+				}
+				if (this.is("function")) {
+					this.next();
+					const name = this.name();
+					const fn = this.funcSignature(false);
+					out.declares.push({ name, type: fn, ...(deprecated ? { deprecated } : {}) });
+					continue;
+				}
+				const name = this.name();
+				this.expect(":");
+				const type = this.type();
+				out.declares.push({ name, type, ...(deprecated ? { deprecated } : {}) });
+				continue;
+			}
+			if (this.is("export")) {
+				this.next();
+			}
+			if (this.is("type")) {
+				this.next();
+				const name = this.name();
+				this.lastDefaults = {};
+				const params = this.genericParamNames();
+				const defaults = this.lastDefaults;
+				this.expect("=");
+				out.aliases[name] = substituteNames(this.type(), defaults);
+				if (params.length) {
+					out.aliasParams[name] = params;
+				}
+				continue;
+			}
+			this.next();
+		}
+		return out;
+	}
+
+	/** `@deprecated`, `@[deprecated {use = "X"}]`, `@checked` … — returns the deprecation, if any. */
+	private attributes(): string | true | undefined {
+		let deprecated: string | true | undefined;
+		for (;;) {
+			if (this.is("@[")) {
+				this.next();
+				let depth = 1;
+				let sawDeprecated = false;
+				while (depth > 0 && this.peek().t !== "eof") {
+					const t = this.next();
+					if (t.t === "op" && (t.v === "[" || t.v === "@[")) {
+						depth++;
+					} else if (t.t === "op" && t.v === "]") {
+						depth--;
+					} else if (t.t === "name" && t.v === "deprecated") {
+						sawDeprecated = true;
+						deprecated = true;
+					} else if (sawDeprecated && t.t === "string") {
+						deprecated = t.v;
+					}
+				}
+				continue;
+			}
+			if (this.is("@")) {
+				this.next();
+				const word = this.name();
+				if (word === "deprecated") {
+					deprecated = true;
+				}
+				continue;
+			}
+			return deprecated;
+		}
+	}
+
+	private genericParamNames(): string[] {
+		const names: string[] = [];
+		if (this.eat("<")) {
+			while (!this.is(">") && this.peek().t !== "eof") {
+				const t = this.next();
+				if (t.t === "name") {
+					names.push(t.v);
+				}
+				if (this.eat("=")) {
+					const def = this.type();
+					if (t.t === "name") {
+						this.lastDefaults[t.v] = def;
+					}
+				}
+				this.eat("...");
+				this.eat(",");
+			}
+			this.expect(">");
+		}
+		return names;
+	}
+
+	private externType(isClass = false): ExternType {
+		const line = this.peek().line;
+		const name = this.name();
+		let ext: string | null = null;
+		if (this.eat("extends")) {
+			ext = this.name();
+		}
+		if (!isClass) {
+			this.expect("with");
+		}
+		const members: ExternMember[] = [];
+		while (!this.is("end") && this.peek().t !== "eof") {
+			const deprecated = this.attributes();
+			if (this.is("function")) {
+				this.next();
+				const mname = this.name();
+				const fn = this.funcSignature(true);
+				members.push({ name: mname, fn, ...(deprecated ? { deprecated } : {}) });
+				continue;
+			}
+			if (this.is("[")) {
+				// indexer `[string]: any`
+				this.next();
+				this.type();
+				this.expect("]");
+				this.expect(":");
+				this.type();
+				continue;
+			}
+			if (this.peek().t === "name" && (this.is(":", 1))) {
+				const mname = this.name();
+				this.expect(":");
+				const type = this.type();
+				members.push({ name: mname, type, ...(deprecated ? { deprecated } : {}) });
+				continue;
+			}
+			if (this.is("read") || this.is("write")) {
+				this.next();
+				continue;
+			}
+			this.next();
+		}
+		this.expect("end");
+		return { name, extends: ext, members, line };
+	}
+
+	/** `(self, a: T, b: U?, ...: V): R` after the function name. */
+	private funcSignature(method: boolean): LFn {
+		const generics = this.genericParamNames();
+		this.expect("(");
+		const params: LParam[] = [];
+		let variadic: LType | undefined;
+		let first = true;
+		while (!this.is(")") && this.peek().t !== "eof") {
+			if (this.eat("...")) {
+				variadic = this.eat(":") ? this.type() : { k: "name", name: "any" };
+				this.eat(",");
+				continue;
+			}
+			const pname = this.name();
+			if (first && method && pname === "self") {
+				if (this.eat(":")) {
+					this.type();
+				}
+				first = false;
+				this.eat(",");
+				continue;
+			}
+			first = false;
+			let t: LType = { k: "name", name: "any" };
+			if (this.eat(":")) {
+				t = this.type();
+			}
+			params.push({ name: pname, t });
+			this.eat(",");
+		}
+		this.expect(")");
+		const fn: LFn = { k: "fn", params, returns: [] };
+		if (variadic) {
+			fn.variadic = variadic;
+		}
+		if (generics.length) {
+			fn.generics = generics;
+		}
+		if (this.eat(":")) {
+			this.returnTypes(fn);
+		}
+		return fn;
+	}
+
+	private returnTypes(fn: LFn): void {
+		if (this.is("(")) {
+			// tuple `(A, B)` or a parenthesized function type `((a) -> b)`
+			const mark = this.i;
+			this.next();
+			if (this.eat(")")) {
+				if (this.is("->")) {
+					this.i = mark;
+					fn.returns = [this.type()];
+				}
+				return;
+			}
+			const list: LType[] = [];
+			let tail: LType | undefined;
+			while (!this.is(")") && this.peek().t !== "eof") {
+				if (this.eat("...")) {
+					tail = this.type();
+				} else {
+					list.push(this.type());
+				}
+				this.eat(",");
+			}
+			this.expect(")");
+			if (this.is("->") || this.is("|") || this.is("?") || this.is("&")) {
+				this.i = mark;
+				fn.returns = [this.type()];
+				return;
+			}
+			fn.returns = list;
+			if (tail) {
+				fn.returnsVariadic = tail;
+			}
+			return;
+		}
+		if (this.eat("...")) {
+			fn.returnsVariadic = this.type();
+			return;
+		}
+		const t = this.type();
+		if (t.k === "name" && (t.name === "nil" || t.name === "()")) {
+			return;
+		}
+		fn.returns = [t];
+	}
+
+	type(): LType {
+		this.eat("|");
+		const first = this.intersection();
+		if (!this.is("|")) {
+			return first;
+		}
+		const ts = [first];
+		while (this.eat("|")) {
+			ts.push(this.intersection());
+		}
+		return { k: "union", ts };
+	}
+
+	private intersection(): LType {
+		const first = this.postfix();
+		if (!this.is("&")) {
+			return first;
+		}
+		const ts = [first];
+		while (this.eat("&")) {
+			ts.push(this.postfix());
+		}
+		return { k: "inter", ts };
+	}
+
+	private postfix(): LType {
+		let t = this.primary();
+		while (this.eat("?")) {
+			t = { k: "opt", t };
+		}
+		return t;
+	}
+
+	private primary(): LType {
+		const tok = this.peek();
+		if (tok.t === "string") {
+			this.next();
+			return { k: "lit", value: tok.v };
+		}
+		if (this.is("typeof")) {
+			this.next();
+			this.expect("(");
+			let depth = 1;
+			while (depth > 0 && this.peek().t !== "eof") {
+				const t = this.next();
+				if (t.v === "(") {
+					depth++;
+				} else if (t.v === ")") {
+					depth--;
+				}
+			}
+			return { k: "name", name: "any" };
+		}
+		if (this.is("{")) {
+			return this.table();
+		}
+		if (this.is("<")) {
+			// generic function type `<T>(a: T) -> T`
+			const generics = this.genericParamNames();
+			const fn = this.parenType() as LFn;
+			if (fn.k === "fn" && generics.length) {
+				fn.generics = generics;
+			}
+			return fn;
+		}
+		if (this.is("(")) {
+			return this.parenType();
+		}
+		if (this.is("...")) {
+			this.next();
+			const inner = this.type();
+			return inner.k === "name" ? { k: "pack", name: inner.name } : inner;
+		}
+		if (tok.t === "name") {
+			this.next();
+			let name = tok.v;
+			while (this.is(".") && this.peek(1).t === "name") {
+				this.next();
+				name += `.${this.next().v}`;
+			}
+			if (name === "true" || name === "false") {
+				return { k: "lit", value: name === "true" };
+			}
+			if (this.eat("...")) {
+				return { k: "pack", name };
+			}
+			if (this.is("<")) {
+				this.next();
+				const args: LType[] = [];
+				while (!this.is(">") && this.peek().t !== "eof") {
+					if (this.is("(") && this.is(")", 1)) {
+						this.next();
+						this.next();
+						args.push({ k: "name", name: "()" });
+					} else {
+						const arg = this.type();
+						if (arg.k === "name" && arg.name === "__pack") {
+							args.push(...(arg.args || []));
+						} else {
+							args.push(arg);
+						}
+					}
+					this.eat(",");
+				}
+				this.expect(">");
+				return { k: "name", name, args };
+			}
+			return { k: "name", name };
+		}
+		throw new Error(`definitions: unexpected '${tok.v}' at line ${tok.line}`);
+	}
+
+	/** `( … )` — a function type when followed by `->`, else grouping. */
+	private parenType(): LType {
+		this.expect("(");
+		const params: LParam[] = [];
+		let variadic: LType | undefined;
+		while (!this.is(")") && this.peek().t !== "eof") {
+			if (this.eat("...")) {
+				variadic = this.is(",") || this.is(")") ? { k: "name", name: "any" } : this.type();
+				this.eat(",");
+				continue;
+			}
+			let pname: string | undefined;
+			if (this.peek().t === "name" && this.is(":", 1)) {
+				pname = this.next().v;
+				this.next();
+			}
+			const t = this.type();
+			if (t.k === "pack") {
+				variadic = { k: "name", name: "any" };
+				this.eat(",");
+				continue;
+			}
+			params.push(pname ? { name: pname, t } : { t });
+			this.eat(",");
+		}
+		this.expect(")");
+		if (this.eat("->")) {
+			const fn: LFn = { k: "fn", params, returns: [] };
+			if (variadic) {
+				fn.variadic = variadic;
+			}
+			this.returnTypes(fn);
+			return fn;
+		}
+		if (params.length === 1 && !variadic) {
+			return params[0].t;
+		}
+		if (params.length === 0) {
+			return { k: "name", name: "()" };
+		}
+		// a type pack `(A, B)`, as in RBXScriptSignal<(InputObject, boolean)>
+		return { k: "name", name: "__pack", args: params.map((p) => p.t) };
+	}
+
+	private table(): LType {
+		this.expect("{");
+		if (this.eat("}")) {
+			return { k: "table", fields: {} };
+		}
+		// `{ T }` array
+		const mark = this.i;
+		const isField = (this.peek().t === "name" && this.is(":", 1)) || this.is("[") || ((this.is("read") || this.is("write")) && this.peek(1).t === "name");
+		if (!isField) {
+			const elem = this.type();
+			if (this.eat("}")) {
+				return { k: "array", t: elem };
+			}
+			this.i = mark;
+		}
+		const fields: Record<string, LType> = {};
+		let indexer: [LType, LType] | undefined;
+		while (!this.is("}") && this.peek().t !== "eof") {
+			if ((this.is("read") || this.is("write")) && this.peek(1).t === "name" && this.is(":", 2)) {
+				this.next();
+			}
+			if (this.eat("[")) {
+				const key = this.type();
+				this.expect("]");
+				this.expect(":");
+				indexer = [key, this.type()];
+			} else {
+				const fname = this.name();
+				this.expect(":");
+				fields[fname] = this.type();
+			}
+			if (!this.eat(",")) {
+				this.eat(";");
+			}
+		}
+		this.expect("}");
+		if (indexer && Object.keys(fields).length === 0) {
+			return { k: "map", key: indexer[0], value: indexer[1] };
+		}
+		return { k: "table", fields };
+	}
+}
+
+/** Replace generic parameter names by their defaults (`RaycastResult<T = BasePart>` → BasePart). */
+function substituteNames(t: LType, map: Record<string, LType>): LType {
+	if (Object.keys(map).length === 0) {
+		return t;
+	}
+	const sub = (x: LType): LType => substituteNames(x, map);
+	switch (t.k) {
+		case "name":
+			return map[t.name] && !t.args ? map[t.name] : t.args ? { ...t, args: t.args.map(sub) } : t;
+		case "opt":
+			return { k: "opt", t: sub(t.t) };
+		case "union":
+		case "inter":
+			return { k: t.k, ts: t.ts.map(sub) };
+		case "array":
+			return { k: "array", t: sub(t.t) };
+		case "map":
+			return { k: "map", key: sub(t.key), value: sub(t.value) };
+		case "table":
+			return { k: "table", fields: Object.fromEntries(Object.entries(t.fields).map(([k, v]) => [k, sub(v)])) };
+		case "fn":
+			return { ...t, params: t.params.map((p) => ({ ...p, t: sub(p.t) })), returns: t.returns.map(sub) };
+		default:
+			return t;
+	}
+}
+
+export function parseDefinitions(text: string): DefinitionFile {
+	let metadata: Record<string, unknown> = {};
+	const first = text.split("\n", 1)[0];
+	if (first.startsWith("--#METADATA#")) {
+		try {
+			metadata = JSON.parse(first.slice("--#METADATA#".length));
+		} catch {
+			metadata = {};
+		}
+	}
+	const file = new DefParser(lex(text)).file();
+	file.metadata = metadata;
+	return file;
+}