cluaupp 1.5.2 → 2.0.0-beta.1

package/src/api/surface/build.ts

@@ -0,0 +1,374 @@
+/**
+ * Builds `api/roblox/surface.json` from:
+ *  1. luau-lsp Roblox definitions (`globalTypes.*.d.luau`) — types, nullability, overloads, operators;
+ *  2. `api/roblox/luau-builtins.d.luau` — math, string, table, coroutine, bit32, buffer, os, vector, globals;
+ *  3. the Roblox API dump profile (`api/normalized/roblox-target.profile.json`) — security, read-only,
+ *     creatable/service, deprecation tags and integer-typed members.
+ *
+ * Run with `cluaupp api surface --defs <globalTypes.d.luau>`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseDefinitions, type DefinitionFile, type ExternType } from "./luau-defs.js";
+import type { LFn, LType, RobloxSurface, SurfaceClass, SurfaceDatatype, SurfaceMember, SurfaceStatic } from "./model.js";
+import { projectRoot } from "../../package-info.js";
+
+interface ProfileMember {
+	name: string;
+	writable?: boolean;
+	readable?: boolean;
+	readSecurity?: string;
+	writeSecurity?: string;
+	security?: string;
+	tags?: Array<string | Record<string, unknown>>;
+	valueType?: { kind: string; name?: string };
+	returnTypes?: Array<{ kind: string; name?: string }>;
+	canYield?: boolean;
+	deprecated?: { deprecated: boolean; replacement?: string };
+}
+
+interface ProfileClass {
+	name: string;
+	superclass: string | null;
+	tags: string[];
+	creatable: boolean;
+	service: boolean;
+	creation?: { kind: string; abstract?: boolean; pluginOnly?: boolean };
+	properties: ProfileMember[];
+	methods: ProfileMember[];
+	events: ProfileMember[];
+	callbacks: ProfileMember[];
+}
+
+interface Profile {
+	classes: Record<string, ProfileClass>;
+	enums: Record<string, { items: Array<{ name: string; tags?: string[] }> }>;
+}
+
+const INT_PRIMITIVES = new Set(["int", "int64", "int32", "int16", "int8"]);
+
+function hasTag(m: ProfileMember | ProfileClass, tag: string): boolean {
+	return (m.tags || []).some((t) => t === tag);
+}
+
+function isSignal(t: LType | undefined): t is Extract<LType, { k: "name" }> {
+	return !!t && t.k === "name" && t.name === "RBXScriptSignal";
+}
+
+function intify(t: LType): LType {
+	// keep the union wide: callers store the result back into an LType slot
+	if (t.k === "name" && t.name === "number") {
+		return { k: "name", name: "int" };
+	}
+	if (t.k === "opt") {
+		return { k: "opt", t: intify(t.t) };
+	}
+	return t;
+}
+
+function security(level: string | undefined): string | undefined {
+	return level && level !== "None" ? level : undefined;
+}
+
+function convertMembers(ext: ExternType, profileClass: ProfileClass | undefined): Record<string, SurfaceMember> {
+	const members: Record<string, SurfaceMember> = {};
+	const pProps = new Map((profileClass?.properties || []).map((p) => [p.name, p]));
+	const pMethods = new Map<string, ProfileMember[]>();
+	for (const m of profileClass?.methods || []) {
+		const list = pMethods.get(m.name) || [];
+		list.push(m);
+		pMethods.set(m.name, list);
+	}
+	const pEvents = new Map((profileClass?.events || []).map((p) => [p.name, p]));
+	const pCallbacks = new Map((profileClass?.callbacks || []).map((p) => [p.name, p]));
+
+	for (const m of ext.members) {
+		if (m.fn) {
+			if (m.name.startsWith("__")) {
+				continue;
+			}
+			const existing = members[m.name];
+			if (existing && existing.kind === "method") {
+				existing.overloads!.push(m.fn);
+				continue;
+			}
+			const pm = pMethods.get(m.name)?.[0];
+			const member: SurfaceMember = { kind: "method", overloads: [m.fn] };
+			if (pm) {
+				const ret = pm.returnTypes?.[0];
+				if (ret && ret.kind === "Primitive" && INT_PRIMITIVES.has(ret.name || "") && m.fn.returns.length === 1) {
+					m.fn.returns[0] = intify(m.fn.returns[0]) as (typeof m.fn.returns)[number];
+				}
+				const sec = security(pm.security);
+				if (sec) {
+					member.security = sec;
+				}
+				if (pm.canYield || hasTag(pm, "Yields") || hasTag(pm, "CanYield")) {
+					member.yields = true;
+				}
+				if (hasTag(pm, "NotScriptable")) {
+					member.notScriptable = true;
+				}
+			} else if (/Async$/.test(m.name)) {
+				member.yields = true;
+			}
+			if (m.deprecated) {
+				member.deprecated = m.deprecated;
+			}
+			members[m.name] = member;
+			continue;
+		}
+		const type = m.type!;
+		if (isSignal(type)) {
+			const args = (type.args || []).filter((a) => !(a.k === "name" && a.name === "()"));
+			const member: SurfaceMember = { kind: "event", args };
+			const pe = pEvents.get(m.name);
+			const sec = security(pe?.security);
+			if (sec) {
+				member.security = sec;
+			}
+			if (m.deprecated) {
+				member.deprecated = m.deprecated;
+			}
+			members[m.name] = member;
+			continue;
+		}
+		const pc = pCallbacks.get(m.name);
+		if (pc || (type.k === "fn" && !pProps.has(m.name))) {
+			const member: SurfaceMember = { kind: "callback", type };
+			const sec = security(pc?.security);
+			if (sec) {
+				member.security = sec;
+			}
+			members[m.name] = member;
+			continue;
+		}
+		const pp = pProps.get(m.name);
+		let propType: LType = type;
+		if (pp?.valueType?.kind === "Primitive" && INT_PRIMITIVES.has(pp.valueType.name || "")) {
+			propType = intify(propType);
+		}
+		const member: SurfaceMember = { kind: "property", type: propType };
+		if (pp) {
+			if (pp.writable === false || hasTag(pp, "ReadOnly")) {
+				member.readonly = true;
+			}
+			const rs = security(pp.readSecurity);
+			const ws = security(pp.writeSecurity);
+			if (rs) {
+				member.security = rs;
+			}
+			if (ws) {
+				member.writeSecurity = ws;
+			}
+			if (hasTag(pp, "NotScriptable")) {
+				member.notScriptable = true;
+			}
+			if (hasTag(pp, "NotReplicated")) {
+				member.notReplicated = true;
+			}
+		}
+		if (m.deprecated) {
+			member.deprecated = m.deprecated;
+		}
+		members[m.name] = member;
+	}
+	return members;
+}
+
+function staticsFrom(type: LType): Record<string, SurfaceStatic> {
+	const out: Record<string, SurfaceStatic> = {};
+	const tables: LType[] = type.k === "inter" ? type.ts : [type];
+	for (const t of tables) {
+		if (t.k !== "table") {
+			continue;
+		}
+		for (const [name, value] of Object.entries(t.fields)) {
+			if (value.k === "fn") {
+				out[name] = { kind: "function", overloads: [value] };
+			} else if (value.k === "inter" && value.ts.every((x) => x.k === "fn")) {
+				out[name] = { kind: "function", overloads: value.ts as LFn[] };
+			} else {
+				out[name] = { kind: "value", type: value };
+			}
+		}
+	}
+	return out;
+}
+
+function datatypeFrom(ext: ExternType, statics: LType | undefined): SurfaceDatatype {
+	const operators: Record<string, LFn[]> = {};
+	for (const m of ext.members) {
+		if (m.fn && m.name.startsWith("__")) {
+			(operators[m.name] ||= []).push(m.fn);
+		}
+	}
+	return {
+		name: ext.name,
+		members: convertMembers(ext, undefined),
+		operators,
+		statics: statics ? staticsFrom(statics) : {},
+	};
+}
+
+export interface BuildSurfaceOptions {
+	definitions: string;
+	builtins?: string;
+	profile?: string;
+}
+
+export function buildSurface(options: BuildSurfaceOptions): RobloxSurface {
+	const defsText = fs.readFileSync(options.definitions, "utf8");
+	const builtinsPath = options.builtins || path.join(projectRoot, "api", "roblox", "luau-builtins.d.luau");
+	const profilePath = options.profile || path.join(projectRoot, "api", "normalized", "roblox-target.profile.json");
+	const roblox = parseDefinitions(defsText);
+	const builtins = parseDefinitions(fs.readFileSync(builtinsPath, "utf8"));
+	const profile: Profile = fs.existsSync(profilePath) ? JSON.parse(fs.readFileSync(profilePath, "utf8")) : { classes: {}, enums: {} };
+	return assemble(roblox, builtins, profile, {
+		definitions: path.basename(options.definitions),
+		builtins: path.basename(builtinsPath),
+		profile: fs.existsSync(profilePath) ? path.basename(profilePath) : "none",
+	});
+}
+
+function assemble(roblox: DefinitionFile, builtins: DefinitionFile, profile: Profile, sources: Record<string, string>): RobloxSurface {
+	const surface: RobloxSurface = {
+		schema: 1,
+		generatedAt: new Date().toISOString().slice(0, 10),
+		sources,
+		classes: {},
+		datatypes: {},
+		enums: {},
+		globals: {},
+		libraries: {},
+		aliases: {},
+	};
+	const declared = new Map<string, { type: LType; deprecated?: string | true }>();
+	for (const d of [...roblox.declares, ...builtins.declares]) {
+		declared.set(d.name, d);
+	}
+	const externByName = new Map<string, ExternType>();
+	for (const ext of roblox.externs) {
+		externByName.set(ext.name, ext);
+	}
+	const isClass = (name: string | null): boolean => {
+		let cur = name;
+		let guard = 0;
+		while (cur && guard++ < 64) {
+			if (cur === "Object" || cur === "Instance") {
+				return true;
+			}
+			cur = externByName.get(cur)?.extends ?? null;
+		}
+		return false;
+	};
+	const services = new Set<string>((roblox.metadata.SERVICES as string[]) || []);
+	const creatable = new Set<string>((roblox.metadata.CREATABLE_INSTANCES as string[]) || []);
+
+	for (const ext of roblox.externs) {
+		if (ext.name.startsWith("Enum") && ext.name.endsWith("_INTERNAL") && ext.extends === "Enum") {
+			const enumName = ext.name.slice(4, -"_INTERNAL".length);
+			const items: string[] = [];
+			const deprecated: string[] = [];
+			for (const m of ext.members) {
+				if (m.type) {
+					items.push(m.name);
+					if (m.deprecated) {
+						deprecated.push(m.name);
+					}
+				}
+			}
+			surface.enums[enumName] = { name: enumName, items, ...(deprecated.length ? { deprecated } : {}) };
+			continue;
+		}
+		if (ext.extends === "EnumItem" || ext.name === "Enum" || ext.name === "EnumItem") {
+			continue;
+		}
+		if (ext.name === "Object" || isClass(ext.extends) || ext.name === "Instance") {
+			const pc = profile.classes[ext.name];
+			const cls: SurfaceClass = {
+				name: ext.name,
+				superclass: ext.extends,
+				members: convertMembers(ext, pc),
+				creatable: creatable.has(ext.name),
+				service: services.has(ext.name),
+			};
+			if (pc?.creation?.abstract) {
+				cls.abstract = true;
+			}
+			if (pc && hasTag(pc, "Deprecated")) {
+				cls.deprecated = true;
+			}
+			if (pc && hasTag(pc, "NotCreatable")) {
+				cls.notCreatable = true;
+			}
+			surface.classes[ext.name] = cls;
+			continue;
+		}
+		surface.datatypes[ext.name] = datatypeFrom(ext, declared.get(ext.name)?.type);
+	}
+
+	// Datatype-like statics without an extern body (e.g. `declare Instance: {…}` is handled by the checker).
+	for (const [name, d] of declared) {
+		if (surface.datatypes[name]) {
+			continue;
+		}
+		if (["Instance", "Enum", "game", "workspace", "script", "plugin", "shared", "task", "debug", "utf8"].includes(name)) {
+			continue;
+		}
+		if (/^[A-Z]/.test(name) && d.type.k === "table" && !surface.classes[name]) {
+			surface.datatypes[name] = { name, members: {}, operators: {}, statics: staticsFrom(d.type) };
+		}
+	}
+
+	for (const [name, d] of declared) {
+		if (d.type.k === "table" && /^[a-z]/.test(name)) {
+			surface.libraries[name] = staticsFrom(d.type);
+			continue;
+		}
+		if (d.type.k === "fn") {
+			surface.globals[name] = { overloads: [d.type], ...(d.deprecated ? { deprecated: d.deprecated } : {}) };
+			continue;
+		}
+		if (["game", "workspace", "script", "plugin", "shared", "Enum"].includes(name)) {
+			surface.globals[name] = { type: d.type };
+		}
+	}
+	surface.globals.Instance = { type: declared.get("Instance")!.type };
+
+	for (const [name, t] of Object.entries(roblox.aliases)) {
+		if (name === "ENUM_LIST" || name.startsWith("Enum")) {
+			continue;
+		}
+		surface.aliases[name] = t;
+	}
+	return surface;
+}
+
+export function writeSurface(surface: RobloxSurface, dest = path.join(projectRoot, "api", "roblox", "surface.json")): string {
+	fs.mkdirSync(path.dirname(dest), { recursive: true });
+	fs.writeFileSync(dest, `${JSON.stringify(surface)}\n`, "utf8");
+	return dest;
+}
+
+/** Default location of the luau-lsp definitions downloaded by the VS Code extension. */
+export function findLuauLspDefinitions(): string | null {
+	const roots = [
+		process.env.APPDATA && path.join(process.env.APPDATA, "Code", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+		process.env.APPDATA && path.join(process.env.APPDATA, "Cursor", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+		process.env.HOME && path.join(process.env.HOME, ".config", "Code", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+		process.env.HOME && path.join(process.env.HOME, "Library", "Application Support", "Code", "User", "globalStorage", "johnnymorganz.luau-lsp"),
+	].filter(Boolean) as string[];
+	for (const root of roots) {
+		if (!fs.existsSync(root)) {
+			continue;
+		}
+		const files = fs.readdirSync(root).filter((f) => /^globalTypes.*\.d\.luau$/.test(f));
+		const preferred = files.find((f) => /PluginSecurity/.test(f)) || files[0];
+		if (preferred) {
+			return path.join(root, preferred);
+		}
+	}
+	return null;
+}