fix dots in file/directory names breaking Lua require resolution (#1445) (#1702)

RealColdFry · web-flow · commit 2fc2e99680aa · 2026-04-16T22:17:41.000+02:00
* fix dots in file/directory names breaking Lua require resolution (#1445) Lua's require() uses dots as path separators, so a file at Foo.Bar/index.lua is unreachable via require("Foo.Bar.index") since Lua looks for Foo/Bar/index.lua. Expand dotted path segments into nested directories in the emit output, and emit a diagnostic when this expansion causes output path collisions. * replace dots with underscores in output paths instead of expanding to nested directories * more tests
diff --git a/src/transpilation/diagnostics.ts b/src/transpilation/diagnostics.ts
@@ -59,3 +59,9 @@ export const unsupportedJsxEmit = createDiagnosticFactory(() => 'JSX is only sup
 export const pathsWithoutBaseUrl = createDiagnosticFactory(
     () => "When configuring 'paths' in tsconfig.json, the option 'baseUrl' must also be provided."
 );
+
+export const emitPathCollision = createDiagnosticFactory(
+    (outputPath: string, file1: string, file2: string) =>
+        `Output path '${outputPath}' is used by both '${file1}' and '${file2}'. ` +
+        `Dots in file/directory names are replaced with underscores for Lua module resolution.`
+);
diff --git a/src/transpilation/transpiler.ts b/src/transpilation/transpiler.ts
@@ -4,6 +4,7 @@ import { CompilerOptions, isBundleEnabled, LuaLibImportKind, LuaTarget } from ".
 import { buildMinimalLualibBundle, findUsedLualibFeatures, getLuaLibBundle } from "../LuaLib";
 import { normalizeSlashes, trimExtension } from "../utils";
 import { getBundleResult } from "./bundle";
+import { emitPathCollision } from "./diagnostics";
 import { getPlugins, Plugin } from "./plugins";
 import { resolveDependencies } from "./resolve";
 import { getProgramTranspileResult, TranspileOptions } from "./transpile";
@@ -143,10 +144,17 @@ export class Transpiler {
             diagnostics.push(...bundleDiagnostics);
             emitPlan = [bundleFile];
         } else {
-            emitPlan = resolutionResult.resolvedFiles.map(file => ({
-                ...file,
-                outputPath: getEmitPath(file.fileName, program),
-            }));
+            const outputPathMap = new Map<string, string>();
+            emitPlan = resolutionResult.resolvedFiles.map(file => {
+                const outputPath = getEmitPath(file.fileName, program);
+                const existing = outputPathMap.get(outputPath);
+                if (existing) {
+                    diagnostics.push(emitPathCollision(outputPath, existing, file.fileName));
+                } else {
+                    outputPathMap.set(outputPath, file.fileName);
+                }
+                return { ...file, outputPath };
+            });
         }
 
         performance.endSection("getEmitPlan");
@@ -189,11 +197,17 @@ export function getEmitPathRelativeToOutDir(fileName: string, program: ts.Progra
         emitPathSplits[0] = "lua_modules";
     }
 
+    // Replace dots with underscores in path segments so that Lua's require()
+    // resolves correctly. Dots are path separators in Lua's module system, so
+    // "Foo.Bar/index.lua" would be unreachable via require("Foo.Bar.index")
+    // since Lua interprets it as "Foo/Bar/index.lua".
+    emitPathSplits[emitPathSplits.length - 1] = trimExtension(emitPathSplits[emitPathSplits.length - 1]);
+    emitPathSplits = emitPathSplits.map(segment => segment.replace(/\./g, "_"));
+
     // Set extension
     const extension = ((program.getCompilerOptions() as CompilerOptions).extension ?? "lua").trim();
     const trimmedExtension = extension.startsWith(".") ? extension.substring(1) : extension;
-    emitPathSplits[emitPathSplits.length - 1] =
-        trimExtension(emitPathSplits[emitPathSplits.length - 1]) + "." + trimmedExtension;
+    emitPathSplits[emitPathSplits.length - 1] += "." + trimmedExtension;
 
     return path.join(...emitPathSplits);
 }
diff --git a/test/unit/modules/resolution.spec.ts b/test/unit/modules/resolution.spec.ts
@@ -1,5 +1,6 @@
+import * as path from "path";
 import * as ts from "typescript";
-import { couldNotResolveRequire } from "../../../src/transpilation/diagnostics";
+import { couldNotResolveRequire, emitPathCollision } from "../../../src/transpilation/diagnostics";
 import * as util from "../../util";
 
 const requireRegex = /require\("(.*?)"\)/;
@@ -166,6 +167,52 @@ test.each([
         .tap(expectToRequire(expectedPath));
 });
 
+// https://github.com/TypeScriptToLua/TypeScriptToLua/issues/1445
+// Can't test this via execution because the test harness uses package.preload
+// instead of real filesystem resolution, so require() always finds the module
+// regardless of output path. We check the output path directly instead.
+test("dots in directory names are replaced with underscores in output", () => {
+    const { transpiledFiles } = util.testModule`
+        import { answer } from "./Foo.Bar";
+        export const result = answer;
+    `
+        .addExtraFile("Foo.Bar/index.ts", "export const answer = 42;")
+        .setOptions({ rootDir: "." })
+        .getLuaResult();
+
+    const dottedFile = transpiledFiles.find(f => f.lua?.includes("answer = 42"));
+    expect(dottedFile).toBeDefined();
+    expect(dottedFile!.outPath).toContain(path.join("Foo_Bar", "index.lua"));
+    expect(dottedFile!.outPath).not.toContain("Foo.Bar");
+});
+
+test("dots in file names are replaced with underscores in output", () => {
+    const { transpiledFiles } = util.testModule`
+        import { answer } from "./foo.test";
+        export const result = answer;
+    `
+        .addExtraFile("foo.test.ts", "export const answer = 42;")
+        .setOptions({ rootDir: "." })
+        .getLuaResult();
+
+    const dottedFile = transpiledFiles.find(f => f.lua?.includes("answer = 42"));
+    expect(dottedFile).toBeDefined();
+    expect(dottedFile!.outPath).toContain("foo_test.lua");
+    expect(dottedFile!.outPath).not.toContain("foo.test");
+});
+
+test("dots in paths that collide with existing paths produce a diagnostic", () => {
+    util.testModule`
+        import { a } from "./Foo.Bar";
+        import { b } from "./Foo_Bar";
+        export const result = a + b;
+    `
+        .addExtraFile("Foo.Bar/index.ts", "export const a = 1;")
+        .addExtraFile("Foo_Bar/index.ts", "export const b = 2;")
+        .setOptions({ rootDir: "." })
+        .expectToHaveDiagnostics([emitPathCollision.code]);
+});
+
 test("import = require", () => {
     util.testModule`
         import foo = require("./foo/bar");
diff --git a/test/util.ts b/test/util.ts
@@ -534,8 +534,9 @@ end)());`;
             const moduleExports = {};
             globalContext.exports = moduleExports;
             globalContext.module = { exports: moduleExports };
+            const baseName = fileName.replace("./", "");
             const transpiledExtraFile = transpiledFiles.find(({ sourceFiles }) =>
-                sourceFiles.some(f => f.fileName === fileName.replace("./", "") + ".ts")
+                sourceFiles.some(f => f.fileName === baseName + ".ts" || f.fileName === baseName + "/index.ts")
             );
 
             if (transpiledExtraFile?.js) {
