@isentinel/rojo-utils 0.1.0

package/out-tsc/vitest/tsdown.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("tsdown").UserConfig;
+export default _default;
+//# sourceMappingURL=tsdown.config.d.ts.map

package/out-tsc/vitest/tsdown.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdown.config.d.ts","sourceRoot":"","sources":["../../tsdown.config.ts"],"names":[],"mappings":""}

package/out-tsc/vitest/vitest.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vite").UserConfig;
+export default _default;
+//# sourceMappingURL=vitest.config.d.ts.map

package/out-tsc/vitest/vitest.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../../vitest.config.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@isentinel/rojo-utils",
+  "version": "0.1.0",
+  "description": "Rojo tree walking, nested project resolution, and DataModel path mapping",
+  "keywords": [
+    "roblox",
+    "rojo",
+    "datamodel",
+    "tree"
+  ],
+  "license": "MIT",
+  "author": "Christopher Buss <christopher.buss@pm.me> (https://github.com/christopher-buss)",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "dependencies": {
+    "arktype": "2.2.0"
+  },
+  "devDependencies": {
+    "@isentinel/eslint-config": "6.0.0-beta.12",
+    "@types/node": "24.12.3",
+    "@typescript/native-preview": "7.0.0-dev.20260607.1",
+    "@vitest/coverage-v8": "4.1.8",
+    "@vitest/eslint-plugin": "1.6.19",
+    "eslint": "10.7.0",
+    "eslint-plugin-jest-extended": "3.0.1",
+    "eslint-plugin-n": "18.2.2",
+    "eslint-plugin-pnpm": "1.6.1",
+    "jest-extended": "7.0.0",
+    "tsdown": "0.22.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.8"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,25 @@
+{
+	"name": "rojo-utils",
+	"$schema": "../../node_modules/nx/schemas/project-schema.json",
+	"projectType": "library",
+	"tags": ["scope:tooling", "type:lib"],
+	"targets": {
+		"build": {
+			"command": "tsdown",
+			"outputs": ["{projectRoot}/dist"],
+			"options": {
+				"cwd": "libs/rojo-utils"
+			}
+		},
+		"lint": {
+			"command": "eslint",
+			"hasTypeAwareRules": true
+		},
+		"test": {
+			"command": "vitest run --coverage",
+			"options": {
+				"cwd": "libs/rojo-utils"
+			}
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { loadRojoProject } from "./loader.ts";
+export { collectMounts, pruneAncestors } from "./mount-collector.ts";
+export type { Mount, PathClassifier, PathKind } from "./mount-collector.ts";
+export { mapFsPathToDataModel, mapFsRootToDataModel } from "./path-mapper.ts";
+export {
+	FileRelation,
+	NetworkType,
+	RbxPathParent,
+	RbxType,
+	RojoResolver,
+} from "./rojo-resolver.ts";
+export type {
+	PartitionInfo,
+	RbxPath,
+	RelativeRbxPath,
+	RojoResolverState,
+} from "./rojo-resolver.ts";
+export {
+	collectPaths,
+	rebaseTreePaths,
+	resolveNestedProjects,
+	resolveNestedProjectSources,
+} from "./rojo-tree.ts";
+export { findInTree, matchNodePath } from "./tree-mapper.ts";
+export type { LoadedRojoProject, RojoProject, RojoTreeNode } from "./types.ts";

package/src/loader.spec.ts

@@ -0,0 +1,240 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { loadRojoProject } from "./loader.ts";
+
+describe(loadRojoProject, () => {
+	it("should load and parse a valid Rojo project", () => {
+		expect.assertions(2);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "default.project.json");
+		fs.writeFileSync(
+			projectPath,
+			JSON.stringify({
+				name: "TestProject",
+				tree: {
+					$className: "DataModel",
+					ReplicatedStorage: {
+						shared: { $path: "src/shared" },
+					},
+				},
+			}),
+		);
+
+		try {
+			const project = loadRojoProject(projectPath);
+
+			expect(project.name).toBe("TestProject");
+			expect(project.tree).toStrictEqual({
+				$className: "DataModel",
+				ReplicatedStorage: {
+					shared: { $path: "src/shared" },
+				},
+			});
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should resolve nested project references", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		fs.writeFileSync(
+			path.join(temporaryDirectory, "inner.project.json"),
+			JSON.stringify({ name: "Inner", tree: { $path: "src/inner" } }),
+		);
+		const projectPath = path.join(temporaryDirectory, "default.project.json");
+		fs.writeFileSync(
+			projectPath,
+			JSON.stringify({
+				name: "Outer",
+				tree: {
+					$className: "DataModel",
+					ReplicatedStorage: {
+						inner: { $path: "inner.project.json" },
+					},
+				},
+			}),
+		);
+
+		try {
+			const project = loadRojoProject(projectPath);
+
+			expect(project.tree["ReplicatedStorage"]).toStrictEqual({
+				inner: { $path: "src/inner" },
+			});
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should preserve servePort when present", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "default.project.json");
+		fs.writeFileSync(
+			projectPath,
+			JSON.stringify({
+				name: "TestProject",
+				servePort: 34872,
+				tree: { $className: "DataModel" },
+			}),
+		);
+
+		try {
+			const project = loadRojoProject(projectPath);
+
+			expect(project.servePort).toBe(34872);
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should not include servePort when absent", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "default.project.json");
+		fs.writeFileSync(
+			projectPath,
+			JSON.stringify({
+				name: "TestProject",
+				tree: { $className: "DataModel" },
+			}),
+		);
+
+		try {
+			const project = loadRojoProject(projectPath);
+
+			expect(project.servePort).toBeUndefined();
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should throw with file path when project has malformed JSON", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "bad.project.json");
+		fs.writeFileSync(projectPath, "not valid json {{{");
+
+		try {
+			expect(() => loadRojoProject(projectPath)).toThrow("Failed to parse Rojo project");
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should throw when project JSON is not an object", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "array.project.json");
+		fs.writeFileSync(projectPath, JSON.stringify([1, 2, 3]));
+
+		try {
+			expect(() => loadRojoProject(projectPath)).toThrow(
+				"Rojo project must be a JSON object",
+			);
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should throw when file does not exist", () => {
+		expect.assertions(1);
+
+		expect(() => loadRojoProject("/nonexistent/project.json")).toThrow(
+			"Could not read Rojo project",
+		);
+	});
+
+	it("should throw when name is missing", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "bad.project.json");
+		fs.writeFileSync(projectPath, JSON.stringify({ tree: { $className: "DataModel" } }));
+
+		try {
+			expect(() => loadRojoProject(projectPath)).toThrow(
+				'Rojo project must have a non-empty "name" field',
+			);
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should throw when name is empty string", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "bad.project.json");
+		fs.writeFileSync(
+			projectPath,
+			JSON.stringify({ name: "", tree: { $className: "DataModel" } }),
+		);
+
+		try {
+			expect(() => loadRojoProject(projectPath)).toThrow(
+				'Rojo project must have a non-empty "name" field',
+			);
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should throw when tree is missing", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "bad.project.json");
+		fs.writeFileSync(projectPath, JSON.stringify({ name: "Bad" })!);
+
+		try {
+			expect(() => loadRojoProject(projectPath)).toThrow(
+				'Rojo project must have a "tree" object',
+			);
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should throw when tree is an array", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "bad.project.json");
+		fs.writeFileSync(projectPath, JSON.stringify({ name: "Bad", tree: [] }));
+
+		try {
+			expect(() => loadRojoProject(projectPath)).toThrow(
+				'Rojo project must have a "tree" object',
+			);
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+
+	it("should throw when tree is null", () => {
+		expect.assertions(1);
+
+		const temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "rojo-loader-test-"));
+		const projectPath = path.join(temporaryDirectory, "bad.project.json");
+		fs.writeFileSync(projectPath, JSON.stringify({ name: "Bad", tree: null }));
+
+		try {
+			expect(() => loadRojoProject(projectPath)).toThrow(
+				'Rojo project must have a "tree" object',
+			);
+		} finally {
+			fs.rmSync(temporaryDirectory, { force: true, recursive: true });
+		}
+	});
+});

package/src/loader.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { resolveNestedProjects } from "./rojo-tree.ts";
+import type { LoadedRojoProject, RojoTreeNode } from "./types.ts";
+
+export function loadRojoProject(projectPath: string): LoadedRojoProject {
+	let content: string;
+	try {
+		content = readFileSync(projectPath, "utf-8");
+	} catch (err) {
+		throw new Error(`Could not read Rojo project: ${projectPath}`, { cause: err });
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch (err) {
+		throw new Error(`Failed to parse Rojo project: ${projectPath}`, { cause: err });
+	}
+
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new Error(`Rojo project must be a JSON object: ${projectPath}`);
+	}
+
+	const raw = parsed as Record<string, unknown>;
+
+	if (typeof raw["name"] !== "string" || raw["name"] === "") {
+		throw new Error(`Rojo project must have a non-empty "name" field: ${projectPath}`);
+	}
+
+	if (typeof raw["tree"] !== "object" || raw["tree"] === null || Array.isArray(raw["tree"])) {
+		throw new Error(`Rojo project must have a "tree" object: ${projectPath}`);
+	}
+
+	const rootDirectory = dirname(projectPath);
+	const tree = resolveNestedProjects(raw["tree"] as RojoTreeNode, rootDirectory);
+
+	return {
+		name: raw["name"],
+		raw,
+		servePort: typeof raw["servePort"] === "number" ? raw["servePort"] : undefined,
+		tree,
+	};
+}

package/src/mount-collector.spec.ts

@@ -0,0 +1,272 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { PathClassifier, PathKind } from "./mount-collector.ts";
+import { collectMounts, pruneAncestors } from "./mount-collector.ts";
+import type { RojoTreeNode } from "./types.ts";
+
+function allDirectories(): PathKind {
+	return "directory";
+}
+
+function makeClassifier(kinds: Record<string, PathKind>): PathClassifier {
+	function classify(fsPath: string): PathKind {
+		return kinds[fsPath] ?? "missing";
+	}
+
+	return classify;
+}
+
+describe(collectMounts, () => {
+	it("should return empty array for tree with no $path entries", () => {
+		expect.assertions(1);
+
+		const tree = { $className: "DataModel" } satisfies RojoTreeNode;
+
+		expect(collectMounts(tree, "", allDirectories)).toStrictEqual([]);
+	});
+
+	it("should collect a single directory $path entry", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				client: { $path: "out/client" },
+			},
+		} satisfies RojoTreeNode;
+
+		expect(collectMounts(tree, "", allDirectories)).toStrictEqual([
+			{ dataModelPath: "ReplicatedStorage/client", fsPath: "out/client" },
+		]);
+	});
+
+	it("should collect multiple $path entries in nested tree", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				client: { $path: "out/client" },
+				shared: { $path: "out/shared" },
+			},
+			ServerScriptService: {
+				server: { $path: "out/server" },
+			},
+		} satisfies RojoTreeNode;
+
+		const result = collectMounts(tree, "", allDirectories);
+
+		expect(result).toStrictEqual([
+			{ dataModelPath: "ReplicatedStorage/client", fsPath: "out/client" },
+			{ dataModelPath: "ReplicatedStorage/shared", fsPath: "out/shared" },
+			{ dataModelPath: "ServerScriptService/server", fsPath: "out/server" },
+		]);
+	});
+
+	it("should normalize trailing slash in $path", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				client: { $path: "out/client/" },
+			},
+		} satisfies RojoTreeNode;
+
+		expect(collectMounts(tree, "", allDirectories)).toStrictEqual([
+			{ dataModelPath: "ReplicatedStorage/client", fsPath: "out/client" },
+		]);
+	});
+
+	it("should skip file-valued $path entries", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				Constants: { $path: "out/shared/Constants.luau" },
+				shared: { $path: "out/shared" },
+			},
+		} satisfies RojoTreeNode;
+
+		const classify = makeClassifier({
+			"out/shared": "directory",
+			"out/shared/Constants.luau": "file",
+		});
+
+		expect(collectMounts(tree, "", classify)).toStrictEqual([
+			{ dataModelPath: "ReplicatedStorage/shared", fsPath: "out/shared" },
+		]);
+	});
+
+	it("should skip missing paths silently", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				client: { $path: "out/client" },
+				missing: { $path: "out/missing" },
+			},
+		} satisfies RojoTreeNode;
+
+		const classify = makeClassifier({
+			"out/client": "directory",
+		});
+
+		const result = collectMounts(tree, "", classify);
+
+		expect(result).toStrictEqual([
+			{ dataModelPath: "ReplicatedStorage/client", fsPath: "out/client" },
+		]);
+	});
+
+	it("should skip $path entries pointing at .project.json files", () => {
+		expect.assertions(2);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				nested: { $path: "packages/shared/default.project.json" },
+			},
+		} satisfies RojoTreeNode;
+
+		const classify = vi.fn<PathClassifier>();
+
+		expect(collectMounts(tree, "", classify)).toStrictEqual([]);
+		expect(classify).not.toHaveBeenCalled();
+	});
+
+	it("should skip $path entries with non-string values", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				optional: { $path: { optional: "out/maybe" } },
+			},
+		} satisfies RojoTreeNode;
+
+		expect(collectMounts(tree, "", allDirectories)).toStrictEqual([]);
+	});
+
+	it("should skip keys that start with $", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			$properties: { Name: "Game" },
+		} satisfies RojoTreeNode;
+
+		expect(collectMounts(tree, "", allDirectories)).toStrictEqual([]);
+	});
+
+	it("should skip non-object values", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			$ignoreUnknownInstances: true,
+		} satisfies RojoTreeNode;
+
+		expect(collectMounts(tree, "", allDirectories)).toStrictEqual([]);
+	});
+
+	it("should walk deeply nested tree structures", () => {
+		expect.assertions(1);
+
+		const tree = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				Packages: {
+					friends: {
+						Client: { $path: "src/Client" },
+						Shared: { $path: "src/Shared" },
+					},
+				},
+			},
+		} satisfies RojoTreeNode;
+
+		expect(collectMounts(tree, "", allDirectories)).toStrictEqual([
+			{
+				dataModelPath: "ReplicatedStorage/Packages/friends/Client",
+				fsPath: "src/Client",
+			},
+			{
+				dataModelPath: "ReplicatedStorage/Packages/friends/Shared",
+				fsPath: "src/Shared",
+			},
+		]);
+	});
+
+	it("should build DataModel paths from given current prefix", () => {
+		expect.assertions(1);
+
+		const subtree = {
+			lib: { $path: "out/lib" },
+		} satisfies RojoTreeNode;
+
+		expect(collectMounts(subtree, "ReplicatedStorage/shared", allDirectories)).toStrictEqual([
+			{ dataModelPath: "ReplicatedStorage/shared/lib", fsPath: "out/lib" },
+		]);
+	});
+});
+
+describe(pruneAncestors, () => {
+	it("should return empty array for empty input", () => {
+		expect.assertions(1);
+
+		expect(pruneAncestors([])).toStrictEqual([]);
+	});
+
+	it("should pass unrelated paths through unchanged", () => {
+		expect.assertions(1);
+
+		const paths = ["ReplicatedStorage/Client", "ServerScriptService/Server"];
+
+		expect(pruneAncestors(paths)).toStrictEqual(paths);
+	});
+
+	it("should drop descendant when ancestor is present", () => {
+		expect.assertions(1);
+
+		expect(
+			pruneAncestors(["ReplicatedStorage/Client", "ReplicatedStorage/Client/Systems"]),
+		).toStrictEqual(["ReplicatedStorage/Client"]);
+	});
+
+	it("should drop descendant regardless of input order", () => {
+		expect.assertions(1);
+
+		expect(
+			pruneAncestors(["ReplicatedStorage/Client/Systems", "ReplicatedStorage/Client"]),
+		).toStrictEqual(["ReplicatedStorage/Client"]);
+	});
+
+	it("should respect segment boundaries when testing ancestry", () => {
+		expect.assertions(1);
+
+		expect(
+			pruneAncestors(["ReplicatedStorage/Client", "ReplicatedStorage/ClientExtras"]),
+		).toStrictEqual(["ReplicatedStorage/Client", "ReplicatedStorage/ClientExtras"]);
+	});
+
+	it("should keep identical paths unchanged (caller dedupes)", () => {
+		expect.assertions(1);
+
+		expect(pruneAncestors(["A/B", "A/B"])).toStrictEqual(["A/B", "A/B"]);
+	});
+
+	it("should drop all descendants under a common ancestor", () => {
+		expect.assertions(1);
+
+		expect(
+			pruneAncestors([
+				"ReplicatedStorage/Client",
+				"ReplicatedStorage/Client/Systems",
+				"ReplicatedStorage/Client/Components",
+				"ServerScriptService/Server",
+			]),
+		).toStrictEqual(["ReplicatedStorage/Client", "ServerScriptService/Server"]);
+	});
+});