@trioforge/crucible 0.1.0 → 0.3.0

package/transformer/data.cjs

@@ -0,0 +1,72 @@
+function createDataChecks({ ts, program, checker, api }) {
+	const unwrap = (expression) => {
+		while (ts.isParenthesizedExpression(expression) || ts.isNonNullExpression(expression))
+			expression = expression.expression;
+		return expression;
+	};
+	const member = (expression) => {
+		if (ts.isPropertyAccessExpression(expression)) return expression.name.text;
+		if (ts.isElementAccessExpression(expression) && ts.isStringLiteralLike(expression.argumentExpression))
+			return expression.argumentExpression.text;
+	};
+	const store = (expression) => api(checker.getTypeAtLocation(expression).getSymbol()) === "ProfileStore";
+	const marketplace = (expression) => {
+		const symbol = checker.getTypeAtLocation(expression).getSymbol();
+		return (
+			symbol?.name === "MarketplaceService" &&
+			symbol.declarations?.some((d) =>
+				d.getSourceFile().fileName.replaceAll("\\", "/").includes("/@rbxts/types/"),
+			)
+		);
+	};
+	const storeCall = (node) => {
+		const callee = unwrap(node.expression);
+		if (store(callee)) return { store: callee };
+		const name = member(callee);
+		if (name !== undefined && store(callee.expression)) return { store: callee.expression, member: name };
+	};
+	let granted;
+	const grants = () => {
+		if (granted === undefined) {
+			granted = false;
+			const walk = (node) => {
+				if (granted) return;
+				if (ts.isCallExpression(node) && storeCall(node)?.member === "grant") granted = true;
+				else ts.forEachChild(node, walk);
+			};
+			for (const source of program.getSourceFiles()) if (!source.isDeclarationFile) walk(source);
+		}
+		return granted;
+	};
+	return ({ report, side }) =>
+		(node) => {
+			if (ts.isCallExpression(node)) {
+				const call = storeCall(node);
+				if (call) {
+					const text = call.store.getText();
+					const client =
+						call.member === undefined || call.member === "loaded" ? !node.arguments.length : false;
+					const required = client ? "client" : "server";
+					if (side(node) !== required)
+						report(
+							node,
+							"CRU027",
+							client
+								? `${text}${call.member ? ".loaded" : ""}() reads the local player's profile; on the server call ${text}${call.member ? ".loaded" : ""}(player).`
+								: `${text}${call.member === undefined ? "(player)" : `.${call.member}`} is server-only; the client reads ${text}().`,
+						);
+				}
+			}
+			if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+				const target = unwrap(node.left);
+				if (member(target) === "ProcessReceipt" && marketplace(target.expression) && grants())
+					report(
+						node,
+						"CRU025",
+						"Crucible's data module owns ProcessReceipt; register grants with a profile store's grant(productId, ...).",
+					);
+			}
+		};
+}
+
+module.exports = { createDataChecks };

package/transformer/declarations.cjs

@@ -0,0 +1,153 @@
+const limits = Object.freeze({
+	MESSAGE_NAME_MAX_BYTES: 64,
+	MAX_ASK_TIMEOUT_SECONDS: 120,
+	MAX_UNION_BRANCHES: 256,
+	MAX_SCHEMA_NODES: 4096,
+	MAX_DEPTH: 32,
+});
+const reactiveLimits = Object.freeze({
+	MESSAGE_NAME_MAX_BYTES: 64,
+	SYNC_VALUE_DEPTH: 28,
+});
+const dataLimits = Object.freeze({
+	STORE_NAME_MAX_BYTES: 50,
+	MESSAGE_NAME_MAX_BYTES: 64,
+	CONFIG_NAME_MAX_BYTES: 64,
+	PERSIST_DEPTH: 28,
+	VIEW_NAME_PREFIX: "Crucible.Data.",
+	LIVE_NAME_PREFIX: "Crucible.Live.",
+	VIEW_NAME_MAX_BYTES: 64,
+	RESERVED_HANDLE_NAMES: Object.freeze(["set", "update", "insert", "remove"]),
+});
+
+const message = {
+	label: "messages",
+	side: "shared",
+	names: "Message",
+	maxBytes: limits.MESSAGE_NAME_MAX_BYTES,
+	typeArguments: 1,
+	arguments: 1,
+	passed: [],
+	position: "payload",
+};
+const replicated = {
+	label: "replicated state",
+	side: "shared",
+	names: "Replicated",
+	maxBytes: reactiveLimits.MESSAGE_NAME_MAX_BYTES,
+	typeArguments: 1,
+	arguments: 2,
+	passed: [1],
+	position: "state",
+};
+const config = {
+	label: "configs",
+	side: "server",
+	names: "Config",
+	maxBytes: dataLimits.CONFIG_NAME_MAX_BYTES,
+	typeArguments: 1,
+	arguments: 2,
+	passed: [1],
+	position: "persist",
+};
+const kinds = Object.freeze({
+	toServer: message,
+	toClient: message,
+	askServer: { ...message, typeArguments: 2, arguments: 2 },
+	replicated,
+	replicatedPerPlayer: replicated,
+	profileStore: {
+		label: "profile stores",
+		side: "shared",
+		names: "Store",
+		maxBytes: dataLimits.STORE_NAME_MAX_BYTES,
+		typeArguments: "optional",
+		arguments: 2,
+		passed: [1],
+		position: "persist",
+		store: true,
+		handles: true,
+	},
+	dataStore: {
+		label: "data stores",
+		side: "server",
+		names: "Store",
+		maxBytes: dataLimits.STORE_NAME_MAX_BYTES,
+		typeArguments: 1,
+		arguments: 2,
+		passed: [1],
+		position: "persist",
+		store: true,
+	},
+	profileMessage: {
+		label: "profile messages",
+		side: "server",
+		names: "Profile message",
+		maxBytes: dataLimits.MESSAGE_NAME_MAX_BYTES,
+		typeArguments: 1,
+		arguments: 1,
+		passed: [],
+		position: "persist",
+	},
+	config,
+	playerConfig: config,
+});
+const depthLimits = Object.freeze({
+	payload: limits.MAX_DEPTH,
+	state: reactiveLimits.SYNC_VALUE_DEPTH,
+	persist: dataLimits.PERSIST_DEPTH,
+});
+
+// Marks sit only on object fields from the root, so only object fields can lose every field.
+function replica(node) {
+	if (node.kind !== "object") return node;
+	const fields = [];
+	for (const [key, child] of node.fields) {
+		if (child.serverOnly) continue;
+		const kept = replica(child);
+		if (kept.kind === "object" && !kept.fields.length) continue;
+		fields.push([key, kept]);
+	}
+	return { kind: "object", fields };
+}
+// Object fields are sorted by bytes, so a depth-first walk lists paths in rule 131 order, a prefix first.
+function serverOnlyPaths(node, prefix = []) {
+	if (node.kind !== "object") return [];
+	return node.fields.flatMap(([key, child]) =>
+		child.serverOnly ? [[...prefix, key]] : serverOnlyPaths(child, [...prefix, key]),
+	);
+}
+const SEGMENT = /^[A-Za-z][A-Za-z0-9_]*$/;
+function viewNameProblems(store, node) {
+	if (node.kind !== "object") return [];
+	const prefix = `${dataLimits.VIEW_NAME_PREFIX}${store}.`;
+	return node.fields.flatMap(([field]) => {
+		const name = prefix + field;
+		if (!SEGMENT.test(field))
+			return [
+				[
+					`value[${JSON.stringify(field)}]`,
+					"a field the owner's client receives is named by one declaration segment, [A-Za-z][A-Za-z0-9_]*; rename it or mark it serverOnly",
+				],
+			];
+		if (Buffer.byteLength(name) > dataLimits.VIEW_NAME_MAX_BYTES)
+			return [
+				[
+					`value.${field}`,
+					`its view name ${name} is ${Buffer.byteLength(name)} bytes, over ${dataLimits.VIEW_NAME_MAX_BYTES}; this store allows field names of at most ${dataLimits.VIEW_NAME_MAX_BYTES - Buffer.byteLength(prefix)} bytes; rename the field, shorten the store name, or mark it serverOnly`,
+				],
+			];
+		return [];
+	});
+}
+
+module.exports = {
+	limits,
+	reactiveLimits,
+	dataLimits,
+	kinds,
+	depthLimits,
+	replica,
+	serverOnlyPaths,
+	viewNameProblems,
+};

package/transformer/index.js

@@ -2,6 +2,8 @@ const path = require("node:path");
 const { createRequire } = require("node:module");
 const { packageOf, typeId, sourceRoot } = require("./type-id.cjs");
 const { createReporter } = require("./diagnostics.cjs");
+const { createNetwork } = require("./network.cjs");
+const { createDataChecks } = require("./data.cjs");
 
 module.exports = function transformer(program, config = {}, extras = {}) {
 	const ts = extras.ts ?? require("typescript");
@@ -9,10 +11,20 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 	const f = ts.factory;
 	const symbols = new Map();
 	const unalias = (s) => s && (s.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(s) : s);
-	let invalidMetadata = false;
+	const describe = (error) =>
+		error instanceof RangeError && error.message === "Maximum call stack size exceeded"
+			? "Cannot transform input: the type checker ran out of stack. A type in this file nests or inherits too deeply to analyse."
+			: `Cannot transform input: ${String(error instanceof Error ? error.message : error).split(/\r?\n/)[0]}`;
+	let startupFault;
 	try {
 		for (const source of program.getSourceFiles()) {
-			const owner = packageOf(source.fileName);
+			let owner;
+			try {
+				owner = packageOf(source.fileName);
+			} catch {
+				startupFault = "Cannot read package metadata. Check the project's package.json files.";
+				break;
+			}
 			if (owner?.json.name !== "@trioforge/crucible") continue;
 			const module = checker.getSymbolAtLocation(source);
 			if (!module) continue;
@@ -21,8 +33,8 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 				if (!symbols.has(target)) symbols.set(target, symbol.name);
 			}
 		}
-	} catch {
-		invalidMetadata = true;
+	} catch (error) {
+		startupFault = describe(error);
 	}
 	const api = (symbol) => symbols.get(unalias(symbol));
 	const modifiers = (node, flags) => (ts.getCombinedModifierFlags(node) & flags) !== 0;
@@ -46,12 +58,14 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 	};
 	const diagnosticSink = extras.addDiagnostic;
 	let report;
+	let networkProgram;
+	let dataProgram;
 	return (context) => (source) => {
 		if (source.isDeclarationFile) return source;
 		let used = false;
 		report ??= createReporter(ts, diagnosticSink ?? ((d) => context.addDiagnostic(d)));
-		if (invalidMetadata) {
-			report(source, "Crucible", "Cannot read package metadata. Check the project's package.json files.");
+		if (startupFault) {
+			report(source, "Crucible", startupFault);
 			return source;
 		}
 		const isGlobal = (decl) => {
@@ -326,6 +340,26 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 				call(runtime("defineClass"), [f.createIdentifier(node.name.text), object(data)]),
 			);
 		};
+		// A Rojo project may map a folder's files one by one rather than the folder, as Rogen does before their
+		// outputs exist. Each such file names the instance of the folder that holds it.
+		const mappedByFiles = (resolver, folder, out) => {
+			const found = new Set();
+			for (const source of program.getSourceFiles()) {
+				const parts = path
+					.relative(folder, source.fileName)
+					.replace(/\.tsx?$/, "")
+					.split(path.sep);
+				const name = parts.at(-1).replace(/\.(server|client)$/, "");
+				if (source.isDeclarationFile || parts[0] === ".." || path.isAbsolute(parts[0]) || name === "index")
+					continue;
+				const rbx = resolver.getRbxPathFromFilePath(path.join(out, ...parts) + ".luau");
+				const tail = [...parts.slice(0, -1), name];
+				if (rbx?.length > tail.length && tail.every((part, at) => rbx.at(at - tail.length) === part))
+					found.add(rbx.slice(0, -tail.length).join("\0"));
+			}
+			if (found.size > 1) return null;
+			return found.size ? [...found][0].split("\0") : undefined;
+		};
 		const boot = (node) => {
 			let options = node.arguments[0];
 			while (
@@ -360,10 +394,10 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 						report(entry, "CRU006", "load entry must be a string literal.");
 						return entry;
 					}
-					const root = path.dirname(
+					const configFile =
 						program.getCompilerOptions().configFilePath ??
-							path.join(program.getCurrentDirectory(), "tsconfig.json"),
-					);
+						path.join(program.getCurrentDirectory(), "tsconfig.json");
+					const root = packageOf(configFile)?.dir ?? path.dirname(configFile);
 					let resolver;
 					try {
 						const compiler =
@@ -371,8 +405,10 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 								/roblox-ts[\\/]out[\\/]Project[\\/]functions[\\/]compileFiles\.js$/.test(file),
 							) ?? require.resolve("roblox-ts/package.json", { paths: [root, __dirname] });
 						const { RojoResolver } = createRequire(compiler)("@roblox-ts/rojo-resolver");
-						const rojoPath = config.rojo ?? RojoResolver.findRojoConfigFilePath(root).path;
-						resolver = rojoPath && RojoResolver.fromPath(path.resolve(root, rojoPath));
+						const rojoPath = config.rojo
+							? path.resolve(root, config.rojo)
+							: RojoResolver.findRojoConfigFilePath(path.dirname(configFile)).path;
+						resolver = rojoPath && RojoResolver.fromPath(rojoPath);
 					} catch {
 						report(entry, "CRU006", "Cannot load the running compiler's Rojo resolver or project mapping.");
 						return entry;
@@ -385,12 +421,18 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 					const suffix = entry.text.slice(prefix.length).replace(/\.tsx?$/, "");
 					const opts = program.getCompilerOptions();
 					const inputRoot = sourceRoot(opts, [program.getCommonSourceDirectory()]);
-					const relative = inputRoot && path.relative(inputRoot, path.resolve(root, prefix));
+					const folder = path.resolve(root, prefix);
+					const relative = inputRoot && path.relative(inputRoot, folder);
+					const inside = relative !== undefined && !relative.startsWith("..") && !path.isAbsolute(relative);
+					const out = inside && path.resolve(opts.outDir, relative);
 					const mapped =
-						relative !== undefined &&
-						!relative.startsWith("..") &&
-						!path.isAbsolute(relative) &&
-						resolver?.getRbxPathFromFilePath(path.resolve(opts.outDir, relative));
+						out &&
+						resolver &&
+						(resolver.getRbxPathFromFilePath(out) ?? mappedByFiles(resolver, folder, out));
+					if (mapped === null) {
+						report(entry, "CRU006", "load prefix maps to more than one Rojo folder.");
+						return entry;
+					}
 					if (!mapped) {
 						report(entry, "CRU006", "load prefix is outside the Rojo mapping.");
 						return entry;
@@ -499,7 +541,11 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 				.slice(0, -1)
 				.reverse()
 				.find((part) => ["server", "client", "shared"].includes(part));
+		let network;
+		let data;
 		const inspect = (node) => {
+			network.inspect(node);
+			data(node);
 			if (
 				ts.isImportDeclaration(node) ||
 				ts.isExportDeclaration(node) ||
@@ -513,9 +559,19 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 					specifier &&
 					ts.isStringLiteral(specifier) &&
 					specifier.text.startsWith("@trioforge/crucible/") &&
-					!["@trioforge/crucible/server", "@trioforge/crucible/client"].includes(specifier.text)
+					![
+						"@trioforge/crucible/server",
+						"@trioforge/crucible/client",
+						"@trioforge/crucible/vide",
+						"@trioforge/crucible/util/random",
+						"@trioforge/crucible/maths/spline",
+					].includes(specifier.text)
 				)
-					report(node, "CRU004", "Import only the root, server or client Crucible entries.");
+					report(
+						node,
+						"CRU004",
+						"Import only the root, server, client, vide, util/random or maths/spline Crucible entries.",
+					);
 			}
 			if (ts.isClassExpression(node) || ts.isClassDeclaration(node)) {
 				const type = instanceType(node);
@@ -622,6 +678,8 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 		};
 
 		const visit = (node) => {
+			const networkNode = network.visit(node);
+			if (networkNode) return networkNode;
 			if (isMacro(node, "attribute")) {
 				const field = node.parent;
 				if (
@@ -694,6 +752,16 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 			return next;
 		};
 		try {
+			networkProgram ??= createNetwork({ ts, program, checker, api, kindOf, instanceType, modifiers, isMacro });
+			network = networkProgram({
+				source,
+				report,
+				runtime,
+				side,
+				visitInput: (node) => ts.visitNode(node, visit),
+			});
+			dataProgram ??= createDataChecks({ ts, program, checker, api });
+			data = dataProgram({ report, side });
 			inspect(source);
 			const next = ts.visitEachChild(source, visit, context);
 			if (!used) return next;
@@ -704,11 +772,7 @@ module.exports = function transformer(program, config = {}, extras = {}) {
 			);
 			return f.updateSourceFile(next, [imports, ...next.statements]);
 		} catch (error) {
-			report(
-				source,
-				"Crucible",
-				`Cannot transform input: ${String(error instanceof Error ? error.message : error).split(/\r?\n/)[0]}`,
-			);
+			report(source, "Crucible", describe(error));
 			return source;
 		}
 	};