@trioforge/crucible 0.1.0 → 0.2.0

package/out/vide/init.luau

@@ -0,0 +1,50 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _vide = TS.import(script, TS.getModule(script, "@rbxts", "vide").src)
+local cleanup = _vide.cleanup
+local source = _vide.source
+local untracked = TS.import(script, script.Parent, "reactive").untracked
+local createWatchFrom = TS.import(script, script.Parent, "internal", "reactive", "flush").createWatchFrom
+local createRootScope = TS.import(script, script.Parent, "internal", "reactive", "ownership").createRootScope
+local NO_OWNER = "useReadable() needs a Vide owner: call it inside a component or root()"
+--[[
+	*
+	 * A Vide source that follows `readable`. It holds the value read now, untracked, and takes each change on the
+	 * reactive flush, through a `watch` that ends with the current Vide owner. Outside a Vide component or `root` it
+	 * throws.
+	 
+]]
+local function useReadable(readable)
+	local dispose
+	-- Vide's cleanup is the only public test for an owner, and registering first leaves nothing to undo.
+	local owned = pcall(cleanup, function()
+		local _result = dispose
+		if _result ~= nil then
+			_result = _result()
+		end
+		return _result
+	end)
+	if not owned then
+		error(NO_OWNER, 2)
+	end
+	local initial = untracked(readable)
+	local value = source(initial)
+	local latest = initial
+	local write = function()
+		value(latest)
+		return nil
+	end
+	-- A root, so a component mounted from inside a Crucible run or callback does not end with it.
+	dispose = createRootScope(function()
+		return createWatchFrom(readable, initial, function(current)
+			latest = current
+			-- Vide runs its effects inside the write. Across gsub's C call a yield in one throws where it yields, so
+			-- Vide's own error path pops its scope stack. Without it the runner cancels the yielded worker mid-effect.
+			string.gsub("x", "x", write)
+		end)
+	end)
+	return value
+end
+return {
+	useReadable = useReadable,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@trioforge/crucible",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"license": "MIT",
 	"main": "out/init.luau",
 	"types": "out/index.d.ts",
@@ -21,10 +21,20 @@
 			"types": "./out/client/index.d.ts",
 			"default": "./out/client/init.luau"
 		},
+		"./vide": {
+			"types": "./out/vide/index.d.ts",
+			"default": "./out/vide/init.luau"
+		},
 		"./transformer": "./transformer/index.js"
 	},
 	"peerDependencies": {
-		"typescript": "5.5.3"
+		"typescript": "5.5.3",
+		"@rbxts/vide": "^0.6.1"
+	},
+	"peerDependenciesMeta": {
+		"@rbxts/vide": {
+			"optional": true
+		}
 	},
 	"files": [
 		"out",
@@ -32,6 +42,7 @@
 		"server",
 		"client",
 		"emit",
+		"vide",
 		"LICENSE"
 	],
 	"repository": {

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) => {
@@ -499,7 +513,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) ||
@@ -622,6 +640,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 +714,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 +734,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;
 		}
 	};