@ldgerrits/rogen 1.4.0

package/dist/cli.js

@@ -0,0 +1,111 @@
+import { parseArgs } from "util";
+export function printHelp(logger) {
+    const helpText = `
+Rogen - Feature-based folder routing for Roblox
+
+Usage:
+  rogen [command] [options]
+
+Commands:
+  init                 Generate a .rogen.json config file
+  watch                Watch the source and generate automatically
+
+Options:
+  -c, --config <path>  Specify custom config file
+  -p, --project <path> Specify path to Rojo project
+  -t, --tag <tag>      Activate environment tags
+  -m, --mode <mode>    Override modes (luau, ts, darklua, or custom)
+  -s, --source <path>  Override the directory containing uncompiled code
+  -b, --build <path>   Override output directory for transpiled code
+  -o, --output <path>  Override path of Rojo project file
+  -h, --help           Print help
+  -v, --version        Print version
+`;
+    if (logger) {
+        logger.info(helpText.trim());
+    }
+    else {
+        console.log(helpText.trim());
+    }
+}
+export function parseCliArgs(args = process.argv.slice(2), logger) {
+    const options = {
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        init: { type: "boolean", short: "i" },
+        watch: { type: "boolean", short: "w" },
+        config: { type: "string", short: "c" },
+        mode: { type: "string", short: "m", multiple: true },
+        source: { type: "string", short: "s", multiple: true },
+        tag: { type: "string", short: "t", multiple: true },
+        project: { type: "string", short: "p" },
+        build: { type: "string", short: "b" },
+        output: { type: "string", short: "o" },
+    };
+    try {
+        const { values, positionals } = parseArgs({
+            args,
+            options,
+            allowPositionals: true,
+            strict: true,
+        });
+        const parsedArgs = values;
+        if (positionals.length > 0) {
+            const subcommand = positionals[0].toLowerCase();
+            if (subcommand === "init") {
+                parsedArgs.init = true;
+            }
+            else if (subcommand === "watch") {
+                parsedArgs.watch = true;
+            }
+            else if (subcommand === "help") {
+                parsedArgs.help = true;
+            }
+            else if (subcommand === "version") {
+                parsedArgs.version = true;
+            }
+            else {
+                const errorMsg = `unknown subcommand "${positionals[0]}".\nRun 'rogen --help' to see a list of available commands.`;
+                if (logger) {
+                    logger.error(errorMsg);
+                }
+                else {
+                    console.error(errorMsg);
+                }
+                process.exit(1);
+            }
+        }
+        return parsedArgs;
+    }
+    catch (error) {
+        let errCode;
+        let errMsg = String(error);
+        if (typeof error === "object" && error !== null) {
+            const errObj = error;
+            errCode = typeof errObj.code === "string" ? errObj.code : undefined;
+            errMsg =
+                typeof errObj.message === "string"
+                    ? errObj.message
+                    : String(error);
+        }
+        if (errCode === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ||
+            errMsg.includes("Unknown option")) {
+            const cleanMsg = errMsg.replace(/^TypeError \[ERR_PARSE_ARGS_UNKNOWN_OPTION\]:\s*/, "");
+            const errorMsg = `${cleanMsg}\nRun 'rogen --help' to see a list of available commands and options.`;
+            if (logger) {
+                logger.error(errorMsg);
+            }
+            else {
+                console.error(errorMsg);
+            }
+            process.exit(1);
+        }
+        if (logger) {
+            logger.error(errMsg);
+        }
+        else {
+            console.error(errMsg);
+        }
+        process.exit(1);
+    }
+}

package/dist/config.js

@@ -0,0 +1,349 @@
+import fs from "fs";
+import path from "path";
+import { defaultConfig, defaultProject } from "./constants.js";
+const CONFIG_KEYS_MAP = {
+    source: true,
+    tags: true,
+    verbatim: true,
+    casing: true,
+    unwrap: true,
+    aliases: true,
+    globIgnorePaths: true,
+    luau: true,
+    ts: true,
+    darklua: true,
+    project: true,
+};
+const KEYS = Object.keys(CONFIG_KEYS_MAP);
+const LEGACY_KEYS = {
+    keepRouteNames: "verbatim",
+    keepSuffixes: "verbatim",
+    template: "project",
+};
+function getClosestMatch(input, targets, distanceThreshold) {
+    let closest = null;
+    let minDistance = Infinity;
+    for (const target of targets) {
+        const matrix = Array.from({ length: input.length + 1 }, () => Array(target.length + 1).fill(0));
+        for (let i = 0; i <= input.length; i++)
+            matrix[i][0] = i;
+        for (let j = 0; j <= target.length; j++)
+            matrix[0][j] = j;
+        for (let i = 1; i <= input.length; i++) {
+            for (let j = 1; j <= target.length; j++) {
+                const cost = input[i - 1] === target[j - 1] ? 0 : 1;
+                matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j - 1] + cost // substitution
+                );
+            }
+        }
+        const distance = matrix[input.length][target.length];
+        if (distance < minDistance) {
+            minDistance = distance;
+            closest = target;
+        }
+    }
+    return minDistance <= distanceThreshold ? closest : null;
+}
+function isValidRojoTree(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return (typeof record.tree === "object" &&
+        record.tree !== null &&
+        !Array.isArray(record.tree));
+}
+export function isMode(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.output === "string" &&
+        typeof value.build === "string");
+}
+export function resolveConfigPath(customPathArg, logger) {
+    const cwd = process.cwd();
+    if (customPathArg) {
+        const resolvedPath = path.resolve(cwd, customPathArg);
+        if (!fs.existsSync(resolvedPath)) {
+            throw new Error(`specified config file not found: ${customPathArg}`);
+        }
+        return resolvedPath;
+    }
+    const defaultPath = path.resolve(cwd, ".rogen.json");
+    if (fs.existsSync(defaultPath)) {
+        return defaultPath;
+    }
+    try {
+        const directoryFiles = fs.readdirSync(cwd);
+        const matchedConfig = directoryFiles.find((file) => file.endsWith(".rogen.json"));
+        if (matchedConfig) {
+            return path.resolve(cwd, matchedConfig);
+        }
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : "Unknown Error";
+        if (logger) {
+            logger.error(`failed to scan directory for .rogen.json - ${msg}`);
+        }
+        else {
+            console.error(`failed to scan directory for .rogen.json - ${msg}`);
+        }
+    }
+    return undefined;
+}
+export function createFallbackConfig(cwd) {
+    const isTs = fs.existsSync(path.join(cwd, "tsconfig.json"));
+    const isWally = fs.existsSync(path.join(cwd, "wally.toml"));
+    const isPesde = fs.existsSync(path.join(cwd, "pesde.toml"));
+    const tree = structuredClone(defaultProject.tree);
+    const project = {
+        name: path.basename(cwd) || defaultProject.name,
+        tree: tree,
+    };
+    if (isTs) {
+        project.globIgnorePaths = ["**/package.json", "**/tsconfig.json"];
+        const hasRbxts = fs.existsSync(path.join(cwd, "node_modules", "@rbxts"));
+        const hasFlamework = fs.existsSync(path.join(cwd, "node_modules", "@flamework"));
+        const hasRbxtsJs = fs.existsSync(path.join(cwd, "node_modules", "@rbxts-js"));
+        const rbxtsIncludeNode = { $path: "include" };
+        if (hasRbxts || hasFlamework || hasRbxtsJs) {
+            const nodeModulesNode = { $className: "Folder" };
+            if (hasRbxts)
+                nodeModulesNode["@rbxts"] = { $path: "node_modules/@rbxts" };
+            if (hasFlamework)
+                nodeModulesNode["@flamework"] = {
+                    $path: "node_modules/@flamework",
+                };
+            if (hasRbxtsJs)
+                nodeModulesNode["@rbxts-js"] = {
+                    $path: "node_modules/@rbxts-js",
+                };
+            rbxtsIncludeNode.node_modules = nodeModulesNode;
+        }
+        tree.ReplicatedStorage = {
+            ...(tree.ReplicatedStorage || {}),
+            rbxts_include: rbxtsIncludeNode,
+        };
+    }
+    if (isWally) {
+        if (fs.existsSync(path.join(cwd, "Packages"))) {
+            tree.ReplicatedStorage = {
+                ...(tree.ReplicatedStorage || {}),
+                Packages: { $path: "Packages" },
+            };
+        }
+        if (fs.existsSync(path.join(cwd, "ServerPackages"))) {
+            tree.ServerScriptService = {
+                ...(tree.ServerScriptService || {}),
+                ServerPackages: { $path: "ServerPackages" },
+            };
+        }
+    }
+    if (isPesde) {
+        if (fs.existsSync(path.join(cwd, "roblox_packages"))) {
+            tree.ReplicatedStorage = {
+                ...(tree.ReplicatedStorage || {}),
+                Packages: { $path: "roblox_packages" },
+            };
+        }
+        if (fs.existsSync(path.join(cwd, "roblox_server_packages"))) {
+            tree.ServerScriptService = {
+                ...(tree.ServerScriptService || {}),
+                ServerPackages: { $path: "roblox_server_packages" },
+            };
+        }
+    }
+    const config = {
+        ...structuredClone(defaultConfig),
+        project: project,
+    };
+    return config;
+}
+export function loadConfig(configPath, projectPathArg) {
+    const anchor = configPath ? path.dirname(configPath) : process.cwd();
+    const config = createFallbackConfig(anchor);
+    if (configPath) {
+        const rawConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        for (const key in rawConfig) {
+            if (!KEYS.includes(key)) {
+                if (key in LEGACY_KEYS) {
+                    throw new Error(`key "${key}" has been renamed to "${LEGACY_KEYS[key]}". Please, update your configuration.`);
+                }
+                const value = rawConfig[key];
+                const isObject = typeof value === "object" &&
+                    value !== null &&
+                    !Array.isArray(value);
+                const modeData = isObject
+                    ? value
+                    : null;
+                // Default modes merging
+                if (isObject &&
+                    (key === "luau" || key === "ts" || key === "darklua")) {
+                    config[key] = {
+                        ...config[key],
+                        ...modeData,
+                    };
+                    config[key].tags =
+                        modeData &&
+                            typeof modeData.tags === "object" &&
+                            modeData.tags !== null &&
+                            !Array.isArray(modeData.tags)
+                            ? modeData.tags
+                            : {};
+                    config[key].globIgnorePaths = Array.isArray(config[key].globIgnorePaths)
+                        ? config[key].globIgnorePaths
+                        : [];
+                    continue;
+                }
+                // Custom modes merging
+                const intendedAsMode = modeData &&
+                    ("output" in modeData ||
+                        "build" in modeData ||
+                        "tags" in modeData ||
+                        "globIgnorePaths" in modeData);
+                if (intendedAsMode) {
+                    if (typeof modeData.output !== "string") {
+                        throw new Error(`custom mode "${key}" is missing a valid "output" string.`);
+                    }
+                    if (typeof modeData.build !== "string") {
+                        throw new Error(`custom mode "${key}" is missing a valid "build" string.`);
+                    }
+                    config[key] = {
+                        output: modeData.output,
+                        build: modeData.build,
+                        tags: typeof modeData.tags === "object" &&
+                            modeData.tags !== null &&
+                            !Array.isArray(modeData.tags)
+                            ? modeData.tags
+                            : {},
+                        globIgnorePaths: Array.isArray(modeData.globIgnorePaths)
+                            ? modeData.globIgnorePaths
+                            : [],
+                    };
+                    continue;
+                }
+                const closestMatch = getClosestMatch(key, KEYS, 2);
+                if (closestMatch) {
+                    throw new Error(`unknown key "${key}". Did you mean "${closestMatch}"?`);
+                }
+                throw new Error(`unknown configuration key "${key}".`);
+            }
+            else {
+                // Validate keys
+                if (key === "source" &&
+                    typeof rawConfig[key] !== "string" &&
+                    !Array.isArray(rawConfig[key])) {
+                    throw new Error(`'source' must be a string or an array of strings.`);
+                }
+                else if (key === "project" &&
+                    typeof rawConfig[key] !== "object" &&
+                    typeof rawConfig[key] !== "string") {
+                    throw new Error(`'project' must be an inline object or a string path to a JSON file.`);
+                }
+                else if ((key === "verbatim" || key === "unwrap") &&
+                    typeof rawConfig[key] !== "boolean") {
+                    throw new Error(`'${key}' must be a boolean.`);
+                }
+                else if (key === "casing") {
+                    if (typeof rawConfig[key] !== "string") {
+                        throw new Error(`'casing' must be a string.`);
+                    }
+                    const casingVal = rawConfig[key]
+                        .toLowerCase()
+                        .replace(/[-_\s]/g, "");
+                    if (casingVal === "pascal" || casingVal === "pascalcase") {
+                        config.casing = "PascalCase";
+                    }
+                    else if (casingVal === "camel" ||
+                        casingVal === "camelcase") {
+                        config.casing = "camelCase";
+                    }
+                    else {
+                        throw new Error(`'casing' must be either "PascalCase" or "camelCase".`);
+                    }
+                }
+                else if (key === "globIgnorePaths" &&
+                    !Array.isArray(rawConfig[key])) {
+                    throw new Error(`'${key}' must be an array of strings.`);
+                }
+                else if (key === "tags") {
+                    if (typeof rawConfig[key] !== "object" ||
+                        rawConfig[key] === null ||
+                        Array.isArray(rawConfig[key])) {
+                        throw new Error(`'tags' must be a key-value object of booleans.`);
+                    }
+                    for (const tagKey in rawConfig[key]) {
+                        if (typeof rawConfig[key][tagKey] !== "boolean") {
+                            throw new Error(`value for tag "${tagKey}" must be a boolean.`);
+                        }
+                    }
+                }
+                config[key] = rawConfig[key];
+            }
+        }
+    }
+    // Project handling
+    if (projectPathArg) {
+        const projectPath = path.resolve(process.cwd(), projectPathArg);
+        if (!fs.existsSync(projectPath)) {
+            throw new Error(`specified project file not found: ${projectPath}`);
+        }
+        config.project = JSON.parse(fs.readFileSync(projectPath, "utf-8"));
+    }
+    else if (typeof config.project === "string") {
+        const projectPath = path.resolve(anchor, config.project);
+        if (!fs.existsSync(projectPath)) {
+            throw new Error(`specified project file not found: ${projectPath}`);
+        }
+        config.project = JSON.parse(fs.readFileSync(projectPath, "utf-8"));
+    }
+    if (!isValidRojoTree(config.project)) {
+        throw new Error("provided project is not a valid Rojo project. " +
+            "It must be a JSON object containing a 'name' and 'tree' property.");
+    }
+    return { config, anchor };
+}
+export function getEnvironment(anchor, cliModes) {
+    if (cliModes && cliModes.length > 0) {
+        return {
+            isTsProject: cliModes.includes("ts"),
+            isDarkluaProject: cliModes.includes("darklua"),
+        };
+    }
+    const isTsProject = fs.existsSync(path.join(anchor, "tsconfig.json"));
+    const isDarkluaProject = fs.existsSync(path.join(anchor, ".darklua.json")) ||
+        fs.existsSync(path.join(anchor, ".darklua.json5"));
+    return { isTsProject, isDarkluaProject };
+}
+export function resolveActiveModes(config, cliModes, env) {
+    const activeModes = [];
+    if (cliModes && cliModes.length > 0) {
+        for (const cliMode of cliModes) {
+            const requestedMode = config[cliMode];
+            if (!isMode(requestedMode)) {
+                throw new Error(`mode "${cliMode}" is not defined or is invalid in your config file.`);
+            }
+            activeModes.push({ name: cliMode, config: requestedMode });
+        }
+    }
+    else {
+        for (const key in config) {
+            const potentialMode = config[key];
+            if (isMode(potentialMode)) {
+                if (key === "luau" && env.isTsProject)
+                    continue;
+                if (key === "ts" && !env.isTsProject)
+                    continue;
+                if (key === "darklua" && !env.isDarkluaProject)
+                    continue;
+                activeModes.push({ name: key, config: potentialMode });
+            }
+        }
+        if (activeModes.length === 0) {
+            throw new Error("no output modes defined in configuration file. Add 'luau', 'ts', or custom modes.");
+        }
+    }
+    return activeModes;
+}

package/dist/constants.js

@@ -0,0 +1,86 @@
+export const version = "1.4.0";
+export const defaultProject = {
+    name: "roblox-game",
+    tree: { $className: "DataModel" },
+};
+export const defaultConfig = {
+    source: ["src"],
+    tags: {},
+    verbatim: false,
+    casing: "camelCase",
+    globIgnorePaths: [],
+    aliases: {},
+    unwrap: false,
+    luau: {
+        output: "default.project.json",
+        build: "src",
+        tags: {},
+        globIgnorePaths: [],
+    },
+    ts: {
+        output: "default.project.json",
+        build: "out",
+        tags: {},
+        globIgnorePaths: [],
+    },
+    darklua: {
+        output: "build.project.json",
+        build: "dist",
+        tags: {},
+        globIgnorePaths: [],
+    },
+    project: defaultProject,
+};
+export const services = {
+    Server: "ServerScriptService",
+    Client: "StarterPlayerScripts",
+    Shared: "ReplicatedStorage",
+    ServerScriptService: "ServerScriptService",
+    ReplicatedStorage: "ReplicatedStorage",
+    ReplicatedFirst: "ReplicatedFirst",
+    ServerStorage: "ServerStorage",
+    StarterGui: "StarterGui",
+    StarterPack: "StarterPack",
+    StarterPlayerScripts: "StarterPlayerScripts",
+    StarterCharacterScripts: "StarterCharacterScripts",
+    Workspace: "Workspace",
+    Lighting: "Lighting",
+    SoundService: "SoundService",
+    RobloxPluginGuiService: "RobloxPluginGuiService",
+};
+export const serviceParents = {
+    StarterPlayerScripts: "StarterPlayer",
+    StarterCharacterScripts: "StarterPlayer",
+};
+export const serverContainers = new Set([
+    "ServerScriptService",
+    "ServerStorage",
+]);
+export const clientContainers = new Set([
+    "StarterPlayer",
+    "StarterPlayerScripts",
+    "StarterCharacterScripts",
+    "StarterGui",
+    "StarterPack",
+    "ReplicatedFirst",
+]);
+export const serviceAliases = new Set(["server", "client", "shared"]);
+export function generateRoutingMaps(customAliases = {}) {
+    const mergedServices = { ...services, ...customAliases };
+    const lowerCaseMap = Object.fromEntries(Object.entries(mergedServices).map(([k, v]) => [k.toLowerCase(), v]));
+    const mergedKeys = Object.keys(mergedServices).sort((a, b) => b.length - a.length);
+    const lowerKeys = Object.keys(lowerCaseMap).sort((a, b) => b.length - a.length);
+    const allPrefixKeys = Array.from(new Set([...lowerKeys, ...mergedKeys])).sort((a, b) => b.length - a.length);
+    const separatorSuffixRegex = new RegExp(`[\\.\\-_\\+](${lowerKeys.join("|")})$`, "i");
+    const pascalCaseSuffixRegex = new RegExp(`(${mergedKeys.join("|")})$`);
+    const separatorPrefixRegex = new RegExp(`^(${lowerKeys.join("|")})([\\.\\-_\\+])`, "i");
+    const camelCasePrefixRegex = new RegExp(`^(${allPrefixKeys.join("|")})(?=[A-Z])`);
+    return {
+        mergedServices,
+        lowerCaseMap,
+        separatorSuffixRegex,
+        pascalCaseSuffixRegex,
+        separatorPrefixRegex,
+        camelCasePrefixRegex,
+    };
+}

package/dist/execute.js

@@ -0,0 +1,109 @@
+import fs from "fs";
+import path from "path";
+import { build } from "./build.js";
+import { ConsoleLogger, getTimeStamp } from "./logger.js";
+export async function execute(sourcePaths, env, activeModes, baseProjectTree, config, cliArgs, anchor, logger = new ConsoleLogger()) {
+    try {
+        for (const activeMode of activeModes) {
+            const targetConfig = activeMode.config;
+            const modeName = activeMode.name;
+            const buildResult = await build(targetConfig, baseProjectTree, config, env, sourcePaths, cliArgs, anchor);
+            const dropped = [];
+            if (buildResult.exposedDataFiles.length > 0) {
+                logger.warn(`${getTimeStamp()} [${modeName}] Skipping project file generation. Rogen cannot map data files directly.`);
+                for (const exposedPath of buildResult.exposedDataFiles) {
+                    const ext = path.extname(exposedPath);
+                    const fileName = path.basename(exposedPath);
+                    const baseName = fileName.substring(0, fileName.length - ext.length);
+                    const dirName = path.dirname(exposedPath);
+                    logger.info(`  - Cannot resolve data type "${ext}" for: "${exposedPath}"`);
+                    logger.info(`    Fix: Wrap it in a folder (e.g., move it to "${dirName}/${baseName}/data${ext}")`);
+                }
+                continue;
+            }
+            if (buildResult.missingPaths.length > 0) {
+                for (const item of buildResult.missingPaths) {
+                    const ext = path.extname(item.absolutePath).toLowerCase();
+                    if (ext === ".luau" || ext === ".lua") {
+                        const dir = path.dirname(item.absolutePath);
+                        if (!fs.existsSync(dir)) {
+                            fs.mkdirSync(dir, { recursive: true });
+                        }
+                        fs.writeFileSync(item.absolutePath, "");
+                    }
+                    else if (ext === "") {
+                        if (!fs.existsSync(item.absolutePath)) {
+                            fs.mkdirSync(item.absolutePath, {
+                                recursive: true,
+                            });
+                        }
+                    }
+                    else {
+                        delete item.parent[item.key];
+                        dropped.push(`${item.treePath} ($path "${item.path}")`);
+                    }
+                }
+            }
+            const finalContent = JSON.stringify(buildResult.tree, null, "\t");
+            let shouldWrite = true;
+            if (fs.existsSync(buildResult.output)) {
+                const existingContent = fs.readFileSync(buildResult.output, "utf-8");
+                if (existingContent === finalContent) {
+                    shouldWrite = false;
+                }
+            }
+            if (!shouldWrite) {
+                continue;
+            }
+            const outputDir = path.dirname(buildResult.output);
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+            fs.writeFileSync(buildResult.output, finalContent);
+            const totalRemoved = buildResult.removed.length + dropped.length;
+            if (totalRemoved > 0) {
+                if (cliArgs.watch) {
+                    logger.warn(`Pruned ${totalRemoved} unresolvable paths.`);
+                }
+                else {
+                    logger.warn(`Removed entries whose paths do not exist:`);
+                    for (const item of buildResult.removed) {
+                        logger.info(`  - ${item.treePath} ($path "${item.rojoPath}")`);
+                    }
+                    for (const item of dropped) {
+                        logger.info(`  - ${item}`);
+                    }
+                }
+            }
+            if (buildResult.collisions.length > 0) {
+                for (const collision of buildResult.collisions) {
+                    logger.warn(collision);
+                }
+            }
+            if (cliArgs.watch) {
+                const outputName = path.basename(buildResult.output);
+                logger.success(`[${modeName}] Rebuilt "${buildResult.name}" -> ${outputName}`);
+            }
+            else {
+                logger.success(`Generated Rojo tree for "${buildResult.name}"`);
+                logger.info(`  Processed: ${buildResult.fileCount} files`);
+                logger.info(`  Build dir: ${buildResult.buildDir}`);
+                const activeTags = Object.keys(targetConfig.tags || {}).filter((t) => targetConfig.tags[t]);
+                if (activeTags.length > 0) {
+                    logger.info(`  Tags: ${activeTags.join(", ")}`);
+                }
+                logger.info(`  Output to: ${buildResult.output}`);
+            }
+        }
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            logger.error(`failed to execute build - ${error.message}`);
+        }
+        else {
+            logger.error(`failed to execute build due to an unknown error`);
+        }
+        return false;
+    }
+}