@isentinel/rojo-utils 0.1.0

package/src/mount-collector.ts

@@ -0,0 +1,72 @@
+import type { RojoTreeNode } from "./types.ts";
+
+export type PathKind = "directory" | "file" | "missing";
+
+export type PathClassifier = (fsPath: string) => PathKind;
+
+export interface Mount {
+	dataModelPath: string;
+	fsPath: string;
+}
+
+const TrailingSlashPattern = /\/$/;
+
+export function collectMounts(
+	node: RojoTreeNode,
+	currentDataModelPath: string,
+	classify: PathClassifier,
+): Array<Mount> {
+	const result: Array<Mount> = [];
+	walk(node, currentDataModelPath, classify, result);
+	return result;
+}
+
+export function pruneAncestors(paths: Array<string>): Array<string> {
+	return paths.filter((candidate) => {
+		return paths.every((other) => other === candidate || !candidate.startsWith(`${other}/`));
+	});
+}
+
+function addDirectoryMount(
+	node: RojoTreeNode,
+	dataModelPath: string,
+	classify: PathClassifier,
+	result: Array<Mount>,
+): void {
+	const rawPath = node.$path;
+	if (typeof rawPath !== "string") {
+		return;
+	}
+
+	if (rawPath.endsWith(".project.json")) {
+		return;
+	}
+
+	const fsPath = rawPath.replace(TrailingSlashPattern, "");
+	if (classify(fsPath) === "directory") {
+		result.push({ dataModelPath, fsPath });
+	}
+}
+
+function isTreeChild(value: unknown): value is RojoTreeNode {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function walk(
+	node: RojoTreeNode,
+	currentDataModelPath: string,
+	classify: PathClassifier,
+	result: Array<Mount>,
+): void {
+	for (const [key, value] of Object.entries(node)) {
+		if (key.startsWith("$") || !isTreeChild(value)) {
+			continue;
+		}
+
+		const childDataModelPath =
+			currentDataModelPath === "" ? key : `${currentDataModelPath}/${key}`;
+
+		addDirectoryMount(value, childDataModelPath, classify, result);
+		walk(value, childDataModelPath, classify, result);
+	}
+}

package/src/path-mapper.spec.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from "vitest";
+
+import { mapFsPathToDataModel, mapFsRootToDataModel } from "./path-mapper.ts";
+import type { RojoTreeNode } from "./types.ts";
+
+const simpleRojoTree: RojoTreeNode = {
+	$className: "DataModel",
+	ReplicatedStorage: {
+		client: { $path: "out/client" },
+	},
+	ServerScriptService: {
+		server: { $path: "out/server" },
+	},
+};
+
+describe(mapFsRootToDataModel, () => {
+	it("should map outDir to DataModel path via Rojo tree", () => {
+		expect.assertions(1);
+
+		expect(mapFsRootToDataModel("out/client", simpleRojoTree)).toBe("ReplicatedStorage/client");
+	});
+
+	it("should map server outDir to DataModel path", () => {
+		expect.assertions(1);
+
+		expect(mapFsRootToDataModel("out/server", simpleRojoTree)).toBe(
+			"ServerScriptService/server",
+		);
+	});
+
+	it("should handle nested tree structures", () => {
+		expect.assertions(1);
+
+		const nestedTree: RojoTreeNode = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				shared: {
+					lib: { $path: "out/shared/lib" },
+				},
+			},
+		};
+
+		expect(mapFsRootToDataModel("out/shared/lib", nestedTree)).toBe(
+			"ReplicatedStorage/shared/lib",
+		);
+	});
+
+	it("should handle path nested under a $path entry", () => {
+		expect.assertions(1);
+
+		expect(mapFsRootToDataModel("out/client/ui", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/ui",
+		);
+	});
+
+	it("should throw when no mapping found", () => {
+		expect.assertions(1);
+
+		expect(() => mapFsRootToDataModel("out/unknown", simpleRojoTree)).toThrow(
+			/No Rojo tree mapping found for path: out\/unknown\n\nAvailable \$path entries: out\/client, out\/server/,
+		);
+	});
+
+	it("should omit available paths line when tree has no $path entries", () => {
+		expect.assertions(1);
+
+		const emptyTree: RojoTreeNode = { $className: "DataModel" };
+
+		expect(() => mapFsRootToDataModel("out/foo", emptyTree)).toThrow(
+			"No Rojo tree mapping found for path: out/foo",
+		);
+	});
+
+	it("should strip trailing slash before lookup", () => {
+		expect.assertions(1);
+
+		expect(mapFsRootToDataModel("out/client/", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client",
+		);
+	});
+
+	it("should look up source path directly for pure Luau", () => {
+		expect.assertions(1);
+
+		const tree: RojoTreeNode = {
+			$className: "DataModel",
+			ReplicatedStorage: {
+				shared: { $path: "shared" },
+			},
+		};
+
+		expect(mapFsRootToDataModel("shared", tree)).toBe("ReplicatedStorage/shared");
+	});
+});
+
+describe(mapFsPathToDataModel, () => {
+	it("should map a .luau file path to DataModel path", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("out/client/Button.luau", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/Button",
+		);
+	});
+
+	it("should map a .lua file path to DataModel path", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("out/client/Button.lua", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/Button",
+		);
+	});
+
+	it("should handle init.luau by mapping to parent", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("out/client/Button/init.luau", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/Button",
+		);
+	});
+
+	it("should handle init.lua by mapping to parent", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("out/client/Button/init.lua", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/Button",
+		);
+	});
+
+	it("should normalize backslashes", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("out\\client\\Button.luau", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/Button",
+		);
+	});
+
+	it("should return undefined when no mapping found", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("unknown/file.luau", simpleRojoTree)).toBeUndefined();
+	});
+
+	it("should handle paths without Luau extension", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("out/client/Button", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/Button",
+		);
+	});
+
+	it("should handle deeply nested paths", () => {
+		expect.assertions(1);
+
+		expect(mapFsPathToDataModel("out/client/components/ui/Button.luau", simpleRojoTree)).toBe(
+			"ReplicatedStorage/client/components/ui/Button",
+		);
+	});
+
+	it("should map root init.luau when tree root has $path", () => {
+		expect.assertions(1);
+
+		const rootOnlyTree: RojoTreeNode = { $path: "out" };
+
+		expect(mapFsPathToDataModel("out/init.luau", rootOnlyTree)).toBe("");
+	});
+
+	it("should map nested file when tree root has $path", () => {
+		expect.assertions(1);
+
+		const rootOnlyTree: RojoTreeNode = { $path: "out" };
+
+		expect(mapFsPathToDataModel("out/core/module.luau", rootOnlyTree)).toBe("core/module");
+	});
+
+	it("should map nested init.luau when tree root has $path", () => {
+		expect.assertions(1);
+
+		const rootOnlyTree: RojoTreeNode = { $path: "out" };
+
+		expect(mapFsPathToDataModel("out/core/init.luau", rootOnlyTree)).toBe("core");
+	});
+
+	it("should return undefined when tree root $path does not match", () => {
+		expect.assertions(1);
+
+		const rootOnlyTree: RojoTreeNode = { $path: "out" };
+
+		expect(mapFsPathToDataModel("other/file.luau", rootOnlyTree)).toBeUndefined();
+	});
+
+	it("should fall through to findInTree when root $path is an optional object", () => {
+		expect.assertions(1);
+
+		const tree: RojoTreeNode = {
+			$path: { optional: "out" },
+			ReplicatedStorage: { lib: { $path: "lib" } },
+		};
+
+		expect(mapFsPathToDataModel("lib/foo.luau", tree)).toBe("ReplicatedStorage/lib/foo");
+	});
+});

package/src/path-mapper.ts

@@ -0,0 +1,45 @@
+import { collectPaths } from "./rojo-tree.ts";
+import { findInTree } from "./tree-mapper.ts";
+import type { RojoTreeNode } from "./types.ts";
+
+const TRAILING_SLASH = /\/$/;
+
+export function mapFsRootToDataModel(outDirectory: string, rojoTree: RojoTreeNode): string {
+	const normalized = outDirectory.replace(TRAILING_SLASH, "");
+	const result = findInTree(rojoTree, normalized, "");
+	if (result === undefined) {
+		const available: Array<string> = [];
+		collectPaths(rojoTree, available);
+
+		let message = `No Rojo tree mapping found for path: ${normalized}`;
+		if (available.length > 0) {
+			message += `\n\nAvailable $path entries: ${available.join(", ")}`;
+		}
+
+		throw new Error(message);
+	}
+
+	return result;
+}
+
+const LUAU_EXTENSIONS = /\.luau?$/;
+const INIT_SUFFIX = /\/init$/;
+
+export function mapFsPathToDataModel(fsPath: string, rojoTree: RojoTreeNode): string | undefined {
+	const normalized = fsPath.replaceAll("\\", "/").replace(LUAU_EXTENSIONS, "");
+	const withoutInit = normalized.replace(INIT_SUFFIX, "");
+
+	const rootPath = rojoTree.$path;
+	if (typeof rootPath === "string") {
+		const normalizedRootPath = rootPath.replace(TRAILING_SLASH, "");
+		if (withoutInit === normalizedRootPath) {
+			return "";
+		}
+
+		if (withoutInit.startsWith(`${normalizedRootPath}/`)) {
+			return withoutInit.slice(normalizedRootPath.length + 1);
+		}
+	}
+
+	return findInTree(rojoTree, withoutInit, "");
+}