@isentinel/rojo-utils 0.1.0

package/src/rojo-tree.ts

@@ -0,0 +1,162 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+import type { RojoTreeNode } from "./types.ts";
+
+/**
+ * Mutable state threaded through {@link resolveTree} during a single
+ * resolution.
+ */
+interface ResolveContext {
+	/** Absolute paths of every nested project file inlined so far. */
+	sources: Set<string>;
+	/** Project files on the current chain, for circular-reference detection. */
+	visited: Set<string>;
+}
+
+/**
+ * Like {@link resolveNestedProjects}, but also reports the absolute path of
+ * every nested project file inlined during resolution. Change-detection
+ * callers hash these so an edit to a nested `*.project.json` invalidates the
+ * build.
+ */
+export function resolveNestedProjectSources(
+	tree: RojoTreeNode,
+	rootDirectory: string,
+): { projectFiles: Array<string>; tree: RojoTreeNode } {
+	const context: ResolveContext = { sources: new Set<string>(), visited: new Set<string>() };
+	const resolved = resolveTree(tree, rootDirectory, rootDirectory, context);
+	return { projectFiles: [...context.sources], tree: resolved };
+}
+
+export function resolveNestedProjects(tree: RojoTreeNode, rootDirectory: string): RojoTreeNode {
+	return resolveNestedProjectSources(tree, rootDirectory).tree;
+}
+
+export function collectPaths(node: RojoTreeNode, result: Array<string>): void {
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$path" && typeof value === "string") {
+			result.push(value.replaceAll("\\", "/"));
+		} else if (typeof value === "object" && !Array.isArray(value) && !key.startsWith("$")) {
+			collectPaths(value as RojoTreeNode, result);
+		}
+	}
+}
+
+export function rebaseTreePaths(
+	node: RojoTreeNode,
+	fromDirectory: string,
+	toDirectory: string,
+): RojoTreeNode {
+	const result: RojoTreeNode = {};
+
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$path" && typeof value === "string") {
+			const absolutePath = resolve(fromDirectory, value);
+			result[key] = relative(toDirectory, absolutePath).replaceAll("\\", "/");
+			continue;
+		}
+
+		if (typeof value !== "object" || key.startsWith("$") || Array.isArray(value)) {
+			result[key] = value;
+			continue;
+		}
+
+		result[key] = rebaseTreePaths(value as RojoTreeNode, fromDirectory, toDirectory);
+	}
+
+	return result;
+}
+
+function nestedProjectPath(currentDirectory: string, value: string): string | undefined {
+	// Resolve a `$path` string to the nested project file it should inline, or
+	// undefined when the path is a plain source mount. Rojo treats a `$path`
+	// pointing at a directory containing `default.project.json` as a nested
+	// project (e.g. `$path: ".."` into a package root), so honor that alongside
+	// explicit `*.project.json` references.
+	if (value.endsWith(".project.json")) {
+		return join(currentDirectory, value);
+	}
+
+	const directoryDefault = join(currentDirectory, value, "default.project.json");
+	return existsSync(directoryDefault) ? directoryDefault : undefined;
+}
+
+function inlineNestedProject(
+	projectPath: string,
+	currentDirectory: string,
+	originalRoot: string,
+	context: ResolveContext,
+): RojoTreeNode {
+	const chain = new Set(context.visited);
+	chain.add(projectPath);
+	context.sources.add(projectPath);
+
+	let content: string;
+	try {
+		content = readFileSync(projectPath, "utf-8");
+	} catch (err) {
+		const relativePath = relative(currentDirectory, projectPath);
+		throw new Error(`Could not read nested Rojo project: ${relativePath}`, { cause: err });
+	}
+
+	let project: { tree: RojoTreeNode };
+	try {
+		project = JSON.parse(content) as { tree: RojoTreeNode };
+	} catch (err) {
+		const relativePath = relative(currentDirectory, projectPath);
+		throw new Error(`Failed to parse nested Rojo project: ${relativePath}`, { cause: err });
+	}
+
+	return resolveTree(project.tree, dirname(projectPath), originalRoot, {
+		sources: context.sources,
+		visited: chain,
+	});
+}
+
+function resolveRootRelativePath(
+	currentDirectory: string,
+	value: string,
+	originalRoot: string,
+): string {
+	const absolutePath = join(currentDirectory, value);
+	return relative(originalRoot, absolutePath).replaceAll("\\", "/");
+}
+
+function resolveTree(
+	node: RojoTreeNode,
+	currentDirectory: string,
+	originalRoot: string,
+	context: ResolveContext,
+): RojoTreeNode {
+	const resolved: RojoTreeNode = {};
+
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$path" && typeof value === "string") {
+			const projectPath = nestedProjectPath(currentDirectory, value);
+			if (projectPath === undefined) {
+				resolved[key] = resolveRootRelativePath(currentDirectory, value, originalRoot);
+				continue;
+			}
+
+			if (context.visited.has(projectPath)) {
+				throw new Error(`Circular project reference: ${value}`);
+			}
+
+			Object.assign(
+				resolved,
+				inlineNestedProject(projectPath, currentDirectory, originalRoot, context),
+			);
+			continue;
+		}
+
+		if (typeof value !== "object" || key.startsWith("$") || Array.isArray(value)) {
+			resolved[key] = value;
+			continue;
+		}
+
+		resolved[key] = resolveTree(value as RojoTreeNode, currentDirectory, originalRoot, context);
+	}
+
+	return resolved;
+}

package/src/tree-mapper.spec.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+
+import { findInTree, matchNodePath } from "./tree-mapper.ts";
+import type { RojoTreeNode } from "./types.ts";
+
+describe(matchNodePath, () => {
+	it("should return undefined when $path is not a string", () => {
+		expect.assertions(1);
+
+		const node: RojoTreeNode = { $path: { optional: "maybe" } };
+
+		expect(matchNodePath(node, "out/client", "ReplicatedStorage/client")).toBeUndefined();
+	});
+
+	it("should return DataModel path on exact match", () => {
+		expect.assertions(1);
+
+		const node: RojoTreeNode = { $path: "out/client" };
+
+		expect(matchNodePath(node, "out/client", "ReplicatedStorage/client")).toBe(
+			"ReplicatedStorage/client",
+		);
+	});
+
+	it("should strip trailing slash before matching", () => {
+		expect.assertions(1);
+
+		const node: RojoTreeNode = { $path: "out/client/" };
+
+		expect(matchNodePath(node, "out/client", "ReplicatedStorage/client")).toBe(
+			"ReplicatedStorage/client",
+		);
+	});
+
+	it("should return nested DataModel path when target is under $path", () => {
+		expect.assertions(1);
+
+		const node: RojoTreeNode = { $path: "out/client" };
+
+		expect(matchNodePath(node, "out/client/ui", "ReplicatedStorage/client")).toBe(
+			"ReplicatedStorage/client/ui",
+		);
+	});
+
+	it("should return undefined when paths do not match", () => {
+		expect.assertions(1);
+
+		const node: RojoTreeNode = { $path: "out/server" };
+
+		expect(matchNodePath(node, "out/client", "ServerScriptService/server")).toBeUndefined();
+	});
+
+	it("should not match partial directory names", () => {
+		expect.assertions(1);
+
+		const node: RojoTreeNode = { $path: "out/cli" };
+
+		expect(matchNodePath(node, "out/client", "ReplicatedStorage/cli")).toBeUndefined();
+	});
+
+	it("should return undefined when node has no $path", () => {
+		expect.assertions(1);
+
+		const node: RojoTreeNode = { $className: "Folder" };
+
+		expect(matchNodePath(node, "out/client", "ReplicatedStorage/folder")).toBeUndefined();
+	});
+});
+
+const simpleRojoTree: RojoTreeNode = {
+	$className: "DataModel",
+	ReplicatedStorage: {
+		client: { $path: "out/client" },
+	},
+	ServerScriptService: {
+		server: { $path: "out/server" },
+	},
+};
+
+describe(findInTree, () => {
+	it("should find exact $path match", () => {
+		expect.assertions(1);
+
+		expect(findInTree(simpleRojoTree, "out/client", "")).toBe("ReplicatedStorage/client");
+	});
+
+	it("should find nested path under $path entry", () => {
+		expect.assertions(1);
+
+		expect(findInTree(simpleRojoTree, "out/client/ui", "")).toBe("ReplicatedStorage/client/ui");
+	});
+
+	it("should find deeply nested tree structures", () => {
+		expect.assertions(1);
+
+		const nestedTree: RojoTreeNode = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				shared: {
+					lib: { $path: "out/shared/lib" },
+				},
+			},
+		};
+
+		expect(findInTree(nestedTree, "out/shared/lib", "")).toBe("ReplicatedStorage/shared/lib");
+	});
+
+	it("should return undefined when no match", () => {
+		expect.assertions(1);
+
+		expect(findInTree(simpleRojoTree, "out/unknown", "")).toBeUndefined();
+	});
+
+	it("should skip $ prefixed keys", () => {
+		expect.assertions(1);
+
+		const tree: RojoTreeNode = {
+			$className: "DataModel",
+			$properties: { Name: "Game" },
+		};
+
+		expect(findInTree(tree, "out/client", "")).toBeUndefined();
+	});
+
+	it("should skip non-object values", () => {
+		expect.assertions(1);
+
+		const tree: RojoTreeNode = {
+			$className: "DataModel",
+			$ignoreUnknownInstances: true,
+		};
+
+		expect(findInTree(tree, "out/client", "")).toBeUndefined();
+	});
+
+	it("should build DataModel path from current path", () => {
+		expect.assertions(1);
+
+		const subtree: RojoTreeNode = {
+			lib: { $path: "out/shared/lib" },
+		};
+
+		expect(findInTree(subtree, "out/shared/lib", "ReplicatedStorage/shared")).toBe(
+			"ReplicatedStorage/shared/lib",
+		);
+	});
+});

package/src/tree-mapper.ts

@@ -0,0 +1,54 @@
+import type { RojoTreeNode } from "./types.ts";
+
+const TRAILING_SLASH = /\/$/;
+
+export function matchNodePath(
+	childNode: RojoTreeNode,
+	targetPath: string,
+	childDataModelPath: string,
+): string | undefined {
+	const nodePath = childNode.$path;
+	if (typeof nodePath !== "string") {
+		return undefined;
+	}
+
+	const normalizedNodePath = nodePath.replace(TRAILING_SLASH, "");
+	if (normalizedNodePath === targetPath) {
+		return childDataModelPath;
+	}
+
+	if (targetPath.startsWith(`${normalizedNodePath}/`)) {
+		const remainder = targetPath.slice(normalizedNodePath.length + 1);
+		return `${childDataModelPath}/${remainder}`;
+	}
+
+	return undefined;
+}
+
+export function findInTree(
+	node: RojoTreeNode,
+	targetPath: string,
+	currentDataModelPath: string,
+): string | undefined {
+	for (const [key, value] of Object.entries(node)) {
+		if (typeof value !== "object" || key.startsWith("$")) {
+			continue;
+		}
+
+		const childNode = value as RojoTreeNode;
+		const childDataModelPath =
+			currentDataModelPath === "" ? key : `${currentDataModelPath}/${key}`;
+
+		const pathMatch = matchNodePath(childNode, targetPath, childDataModelPath);
+		if (pathMatch !== undefined) {
+			return pathMatch;
+		}
+
+		const found = findInTree(childNode, targetPath, childDataModelPath);
+		if (found !== undefined) {
+			return found;
+		}
+	}
+
+	return undefined;
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+export interface RojoTreeNode {
+	$className?: string;
+	$ignoreUnknownInstances?: boolean;
+	$path?: string | { optional: string };
+	$properties?: Record<string, unknown>;
+	[key: string]:
+		| boolean
+		| Record<string, unknown>
+		| RojoTreeNode
+		| string
+		| undefined
+		| { optional: string };
+}
+
+export interface RojoProject {
+	name: string;
+	servePort?: number;
+	tree: RojoTreeNode;
+}
+
+/**
+ * Result of `loadRojoProject` — the validated narrow shape plus the original
+ * parsed JSON. Callers that need top-level fields beyond name/servePort/tree
+ * (gameId, placeId, globIgnorePaths, etc.) read them from `raw` rather than
+ * re-parsing the project file.
+ */
+export interface LoadedRojoProject extends RojoProject {
+	raw: Record<string, unknown>;
+}

package/test/setup/jest-extended.ts

@@ -0,0 +1,4 @@
+import * as matchers from "jest-extended";
+import { expect } from "vitest";
+
+expect.extend(matchers);

package/test/setup/vitest-jest-extended.d.ts

@@ -0,0 +1 @@
+import "jest-extended";

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "../../tsconfig.node.json",
+	"references": [
+		{
+			"path": "./tsconfig.lib.json"
+		},
+		{
+			"path": "./tsconfig.spec.json"
+		}
+	],
+	"files": [],
+	"include": []
+}

package/tsconfig.lib.json

@@ -0,0 +1,17 @@
+{
+	"extends": "../../tsconfig.node.json",
+	"compilerOptions": {
+		"rootDir": "src",
+		"allowImportingTsExtensions": true,
+		"rewriteRelativeImportExtensions": true,
+		"allowJs": false,
+		"isolatedDeclarations": true
+	},
+	"references": [
+		{
+			"path": "../../tools/eslint-rules/tsconfig.lib.json"
+		}
+	],
+	"include": ["src/**/*.ts"],
+	"exclude": ["./node_modules", "src/**/*.spec.ts", "src/**/*.spec-d.ts", "**/*.config.ts"]
+}