cluaupp 1.5.2 → 2.0.0-beta.1

package/src/compiler/project.ts

@@ -0,0 +1,354 @@
+/**
+ * Project compilation: maps `Src/` onto the Roblox DataModel, builds the typed `@game` tree,
+ * resolves `link`s into a module graph (each module checked once, cycles reported) and emits Luau.
+ *
+ * Layout — folders named like a service map onto that service:
+ *   Src/ServerScriptService/…            → game.ServerScriptService
+ *   Src/ReplicatedStorage/Shared/…       → game.ReplicatedStorage.Shared
+ *   Src/StarterPlayer/StarterPlayerScripts → game.StarterPlayer.StarterPlayerScripts
+ * Legacy domain folders still work: Server → ServerScriptService, Client → StarterPlayerScripts,
+ * anything else → ReplicatedStorage/<folder>.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { LinkDecl } from "./ast.js";
+import { Checker, type FileInfo, type LinkInfo } from "./checker/checker.js";
+import type { LinkTarget, ModuleExports } from "./checker/symbols.js";
+import { DiagnosticBag, type Diagnostic } from "./diagnostics.js";
+import { emitLuau } from "./emit/emitter.js";
+import { isIdentifier, luauString } from "./emit/names.js";
+import { parse } from "./parser.js";
+import { robloxApi, type RobloxApi } from "./roblox/api.js";
+import { runContextOf, type RunContext } from "./roblox/context.js";
+import { SourceFile } from "./source.js";
+import { DESKTOP_ONLY, STD_PATHS } from "./stdlib.js";
+import type { DataModelNode } from "./types.js";
+
+export const SOURCE_EXT = ".clp";
+export const LIBS_FOLDER = ["ReplicatedStorage", "CluauppLibs"];
+
+const LEGACY_FOLDERS: Record<string, string[]> = {
+	Server: ["ServerScriptService"],
+	Client: ["StarterPlayer", "StarterPlayerScripts"],
+	Character: ["StarterPlayer", "StarterCharacterScripts"],
+	Gui: ["StarterGui"],
+};
+
+const NESTED_SERVICES: Record<string, string[]> = {
+	StarterPlayerScripts: ["StarterPlayer", "StarterPlayerScripts"],
+	StarterCharacterScripts: ["StarterPlayer", "StarterCharacterScripts"],
+};
+
+export interface ProjectOptions {
+	root: string;
+	srcDir: string;
+	strict: boolean;
+	version: string;
+	api?: RobloxApi;
+}
+
+export interface CompiledFile {
+	file: string;
+	rel: string;
+	outRel: string;
+	luau: string | null;
+	sourceMap?: import("../clpp/contract.js").SourceMapLine[];
+	diagnostics: Diagnostic[];
+	source: SourceFile;
+	info: FileInfo | null;
+}
+
+export function scriptStem(fileName: string): string {
+	return path.basename(fileName).replace(/\.(server|client|plugin)?\.?clp$/i, "").replace(/\.clp$/i, "");
+}
+
+export function outputName(rel: string): string {
+	return rel.replace(/\.clp$/i, ".luau");
+}
+
+/** DataModel path of a source file, e.g. `ReplicatedStorage/Shared/Combat.clp` → ["ReplicatedStorage", "Shared", "Combat"]. */
+export function dataModelPath(api: RobloxApi, rel: string): string[] {
+	const parts = rel.replace(/\\/g, "/").split("/");
+	const file = parts.pop()!;
+	const stem = scriptStem(file);
+	const first = parts[0];
+	let base: string[];
+	let rest: string[];
+	if (!first) {
+		base = ["ReplicatedStorage"];
+		rest = [];
+	} else if (NESTED_SERVICES[first]) {
+		base = NESTED_SERVICES[first];
+		rest = parts.slice(1);
+	} else if (first === "StarterPlayer" && NESTED_SERVICES[parts[1]]) {
+		base = NESTED_SERVICES[parts[1]];
+		rest = parts.slice(2);
+	} else if (api.isService(first)) {
+		base = [first];
+		rest = parts.slice(1);
+	} else if (LEGACY_FOLDERS[first]) {
+		base = LEGACY_FOLDERS[first];
+		rest = parts.slice(1);
+	} else {
+		base = ["ReplicatedStorage"];
+		rest = parts;
+	}
+	return [...base, ...rest, stem];
+}
+
+export function classForFile(fileName: string): string {
+	const ctx = runContextOf(fileName);
+	return ctx === "server" ? "Script" : ctx === "client" ? "LocalScript" : ctx === "plugin" ? "Script" : "ModuleScript";
+}
+
+export function collectClp(dir: string, out: string[] = []): string[] {
+	if (!fs.existsSync(dir)) {
+		return out;
+	}
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			collectClp(full, out);
+		} else if (entry.name.toLowerCase().endsWith(SOURCE_EXT)) {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+/** Typed `game` tree: services → folders → scripts compiled from Src, plus CluauppLibs. */
+export function buildDataModel(api: RobloxApi, srcDir: string, files: string[], libs: string[] = []): DataModelNode {
+	const root: DataModelNode = { name: "game", className: "DataModel", path: [], children: new Map() };
+	const ensure = (segments: string[], leafClass: string, sourceFile?: string): void => {
+		let node = root;
+		segments.forEach((seg, i) => {
+			let child = node.children.get(seg);
+			const isLeaf = i === segments.length - 1;
+			if (!child) {
+				const cls = i === 0 && api.isService(seg) ? seg : isLeaf ? leafClass : i === 1 && segments[0] === "StarterPlayer" ? seg : "Folder";
+				child = { name: seg, className: cls, path: segments.slice(0, i + 1), children: new Map() };
+				node.children.set(seg, child);
+			}
+			if (isLeaf && sourceFile) {
+				child.className = leafClass;
+				child.sourceFile = sourceFile;
+			}
+			node = child;
+		});
+	};
+	for (const svc of ["Workspace", "Players", "ReplicatedStorage", "ReplicatedFirst", "ServerScriptService", "ServerStorage", "StarterGui", "StarterPack", "StarterPlayer", "Lighting", "SoundService", "Teams"]) {
+		ensure([svc], svc);
+	}
+	ensure(["StarterPlayer", "StarterPlayerScripts"], "StarterPlayerScripts");
+	ensure(["StarterPlayer", "StarterCharacterScripts"], "StarterCharacterScripts");
+	for (const file of files) {
+		const rel = path.relative(srcDir, file).replace(/\\/g, "/");
+		ensure(dataModelPath(api, rel), classForFile(file), path.resolve(file));
+	}
+	if (libs.length) {
+		ensure(LIBS_FOLDER, "Folder");
+		for (const lib of libs) {
+			ensure([...LIBS_FOLDER, lib], "ModuleScript");
+		}
+	}
+	return root;
+}
+
+/** Luau expression that reaches an Instance by its DataModel path, robust to replication order. */
+export function instancePath(dm: string[], service: (name: string) => string, fromDm: string[] | null): string {
+	if (fromDm && fromDm.length > 1 && dm.length > 1) {
+		const fromParent = fromDm.slice(0, -1);
+		const targetParent = dm.slice(0, -1);
+		if (fromParent.join("/") === targetParent.join("/")) {
+			return `script.Parent${childAccess(dm[dm.length - 1])}`;
+		}
+	}
+	const [first, ...rest] = dm;
+	let expr = first === "Workspace" ? "workspace" : service(first);
+	for (const seg of rest) {
+		expr += childAccess(seg);
+	}
+	return expr;
+}
+
+function childAccess(name: string): string {
+	return `:WaitForChild(${luauString(name)})`;
+}
+
+export class ProjectCompiler {
+	readonly api: RobloxApi;
+	readonly files: string[];
+	readonly dataModel: DataModelNode;
+	private readonly results = new Map<string, CompiledFile>();
+	private readonly inProgress: string[] = [];
+	private readonly byDmPath = new Map<string, string>();
+	private readonly libs: string[];
+
+	constructor(private readonly options: ProjectOptions, libs: string[] = []) {
+		this.api = options.api ?? robloxApi();
+		this.files = collectClp(options.srcDir).map((f) => path.resolve(f));
+		this.libs = libs;
+		this.dataModel = buildDataModel(this.api, options.srcDir, this.files, libs);
+		for (const f of this.files) {
+			this.byDmPath.set(this.dmOf(f).join("/"), f);
+		}
+	}
+
+	rel(file: string): string {
+		return path.relative(this.options.srcDir, file).replace(/\\/g, "/");
+	}
+
+	dmOf(file: string): string[] {
+		return dataModelPath(this.api, this.rel(file));
+	}
+
+	compileAll(): CompiledFile[] {
+		return this.files.map((f) => this.compile(f));
+	}
+
+	compile(file: string, text?: string): CompiledFile {
+		const key = path.resolve(file);
+		const cached = this.results.get(key);
+		if (cached && text === undefined) {
+			return cached;
+		}
+		const source = new SourceFile(this.rel(key), text ?? fs.readFileSync(key, "utf8"));
+		const diags = new DiagnosticBag(source);
+		const rel = this.rel(key);
+		const context = runContextOf(key);
+		const kind = context === "shared" ? "module" : "script";
+		this.inProgress.push(key);
+		const program = parse(source, diags);
+		const dmPath = this.dmOf(key);
+		let info: FileInfo | null = null;
+		try {
+			info = new Checker({
+				program,
+				source,
+				diags,
+				api: this.api,
+				moduleId: key,
+				kind,
+				context,
+				strict: this.options.strict,
+				resolveLink: (link) => this.resolveLink(link, key, diags),
+				dataModel: this.dataModel,
+				dmPath,
+			}).run();
+		} finally {
+			this.inProgress.pop();
+		}
+		let luau: string | null = null;
+		let sourceMap: import("../clpp/contract.js").SourceMapLine[] = [];
+		if (diags.errorCount === 0) {
+			luau = emitLuau(program, info, this.api, {
+				sourceLabel: rel,
+				sourcePosition: offset => source.position(offset),
+				onSourceMap: lines => {sourceMap = lines;},
+				version: this.options.version,
+				requireTarget: (l, service) => this.requireTarget(l, dmPath, service),
+				libsRoot: (service) => instancePath(LIBS_FOLDER, service, null),
+			});
+		}
+		const result: CompiledFile = { file: key, rel, outRel: outputName(rel), luau, sourceMap, diagnostics: diags.items, source, info };
+		this.results.set(key, result);
+		return result;
+	}
+
+	private resolveLink(link: LinkDecl, fromFile: string, diags: DiagnosticBag): LinkTarget {
+		const p = link.path;
+		if (link.isPackage) {
+			if (p === "@clpp.roblox" || p === "@roblox") {
+				return { kind: "roblox" };
+			}
+			const std = STD_PATHS[p];
+			if (std && std !== "unsupported") {
+				return { kind: "std", module: std };
+			}
+			if (DESKTOP_ONLY[p]) {
+				return { kind: "error", message: `${p} is a desktop module of the clpp VM and does not exist on Roblox`, notes: [DESKTOP_ONLY[p]] };
+			}
+			const lib = /^@(?:clpp\.libs|cluaupp)\.([A-Za-z0-9_]+)$/.exec(p);
+			if (lib) {
+				const name = this.libs.find((l) => l.toLowerCase() === lib[1].toLowerCase());
+				if (!name && this.libs.length) {
+					return { kind: "error", message: `CluauppLibs has no library '${lib[1]}'`, notes: [`available: ${this.libs.join(", ")}`] };
+				}
+				const libName = name ?? lib[1][0].toUpperCase() + lib[1].slice(1);
+				return { kind: "luau", dmPath: [...LIBS_FOLDER, libName], label: libName };
+			}
+			if (p.startsWith("@game.") || /^@[A-Z]/.test(p)) {
+				const shorthand = !p.startsWith("@game.");
+				const segments = p.slice(shorthand ? 1 : "@game.".length).split(".");
+				if (!this.api.isService(segments[0])) {
+					return { kind: "error", message: `'${segments[0]}' is not a Roblox service`, notes: ["link @ReplicatedStorage.Shared.Module as Module;"] };
+				}
+				const fileHit = this.byDmPath.get(segments.join("/"));
+				if (fileHit) {
+					return this.linkFile(fileHit, fromFile);
+				}
+				if (shorthand) {
+					return { kind: "error", message: `no .clp module at ${p}`, notes: [`create src/${segments.join("/")}.clp or use a relative link to the file`] };
+				}
+				return { kind: "luau", dmPath: segments, label: segments.join(".") };
+			}
+			return { kind: "error", message: `unknown module ${p}`, notes: ["@clpp.roblox, @clpp.axiom, @clpp.libs.<Lib>, @ReplicatedStorage.Shared.<Module>, @game.<Service>.<…>"] };
+		}
+		let target = path.resolve(path.dirname(fromFile), p);
+		if (!fs.existsSync(target) && fs.existsSync(`${target}.clp`)) {
+			target = `${target}.clp`;
+		}
+		if (!target.toLowerCase().endsWith(SOURCE_EXT)) {
+			return { kind: "error", message: `cannot link '${p}': CL++ modules are .clp files`, notes: [/\.(clh|clpp)$/i.test(p) ? "CL++ 0.9 has no headers: rename the module to .clp" : "link \"./file.clp\" as Name;"] };
+		}
+		if (!fs.existsSync(target)) {
+			return { kind: "error", message: `cannot open module '${p}'` };
+		}
+		void diags;
+		return this.linkFile(target, fromFile);
+	}
+
+	private linkFile(target: string, fromFile: string): LinkTarget {
+		const key = path.resolve(target);
+		if (this.inProgress.includes(key)) {
+			const cycle = [...this.inProgress.slice(this.inProgress.indexOf(key)), key].map((f) => this.rel(f));
+			return { kind: "error", message: "circular link", notes: [cycle.join(" → ")] };
+		}
+		if (key === path.resolve(fromFile)) {
+			return { kind: "error", message: "a module cannot link itself" };
+		}
+		const compiled = this.compile(key);
+		if (!compiled.info) {
+			return { kind: "error", message: `module ${this.rel(key)} failed to compile` };
+		}
+		if (compiled.diagnostics.some((d) => d.severity === "error")) {
+			const first = compiled.diagnostics.find((d) => d.severity === "error")!;
+			return { kind: "error", message: `module ${this.rel(key)} has errors`, notes: [`${first.file}:${first.line}:${first.column}: ${first.message}`] };
+		}
+		const exports: ModuleExports = compiled.info.exports;
+		return { kind: "clp", exports, dmPath: this.dmOf(key), file: key };
+	}
+
+	private requireTarget(link: LinkInfo, fromDm: string[], service: (name: string) => string): string | null {
+		const t = link.target;
+		if (t.kind === "clp" && t.dmPath) {
+			return instancePath(t.dmPath, service, fromDm);
+		}
+		if (t.kind === "luau") {
+			return instancePath(t.dmPath, service, fromDm);
+		}
+		return null;
+	}
+}
+
+/** Compile one file with no project around it (tests, playground, `cluaupp check <file>`). */
+export function compileSource(text: string, fileName = "Main.server.clp", options: Partial<ProjectOptions> = {}): CompiledFile {
+	const root = options.root ?? process.cwd();
+	const srcDir = options.srcDir ?? root;
+	const compiler = new ProjectCompiler({ root, srcDir, strict: options.strict ?? false, version: options.version ?? "dev", api: options.api });
+	return compiler.compile(path.resolve(srcDir, fileName), text);
+}
+
+export { isIdentifier };
+export type { RunContext };