@izumisy-tailor/omakase-modules 0.6.0 → 0.6.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@izumisy-tailor/omakase-modules",
   "private": false,
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Modularization mechanism for Tailor Platform application powered by Tailor SDK",
   "type": "module",
   "files": [

package/src/config/sdk/paths.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveBasePath } from "./paths";
+
+// =============================================================================
+// resolveBasePath Tests
+// =============================================================================
+
+describe("resolveBasePath", () => {
+  beforeEach(() => {
+    vi.spyOn(process, "cwd").mockReturnValue("/mocked/cwd");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("when basePath is undefined", () => {
+    it("should return process.cwd()", () => {
+      const result = resolveBasePath(undefined);
+      expect(result).toBe("/mocked/cwd");
+    });
+  });
+
+  describe("when basePath is an empty string", () => {
+    it("should return process.cwd()", () => {
+      const result = resolveBasePath("");
+      expect(result).toBe("/mocked/cwd");
+    });
+  });
+
+  describe("when basePath is a file:// URL (import.meta.url format)", () => {
+    it("should convert to directory path on Unix-like systems", () => {
+      const fileUrl = "file:///path/to/project/config.ts";
+      const result = resolveBasePath(fileUrl);
+      expect(result).toBe("/path/to/project");
+    });
+
+    it("should handle nested directory paths", () => {
+      const fileUrl = "file:///Users/developer/projects/my-app/src/config.ts";
+      const result = resolveBasePath(fileUrl);
+      expect(result).toBe("/Users/developer/projects/my-app/src");
+    });
+
+    it("should handle pathToFileURL output", () => {
+      // Simulate what import.meta.url would look like
+      const absolutePath = "/some/absolute/path/to/file.ts";
+      const fileUrl = pathToFileURL(absolutePath).href;
+      const result = resolveBasePath(fileUrl);
+      expect(result).toBe("/some/absolute/path/to");
+    });
+
+    it("should handle file URLs with spaces (encoded)", () => {
+      const fileUrl = "file:///path/to/my%20project/config.ts";
+      const result = resolveBasePath(fileUrl);
+      expect(result).toBe("/path/to/my project");
+    });
+  });
+
+  describe("when basePath is an absolute directory path", () => {
+    it("should return the path as-is", () => {
+      const absolutePath = "/path/to/project";
+      const result = resolveBasePath(absolutePath);
+      expect(result).toBe("/path/to/project");
+    });
+
+    it("should not modify paths with trailing slash", () => {
+      const absolutePath = "/path/to/project/";
+      const result = resolveBasePath(absolutePath);
+      expect(result).toBe("/path/to/project/");
+    });
+  });
+
+  describe("when basePath is a relative path", () => {
+    it("should return the relative path as-is (caller responsibility to resolve)", () => {
+      const relativePath = "./relative/path";
+      const result = resolveBasePath(relativePath);
+      expect(result).toBe("./relative/path");
+    });
+  });
+});
+
+// =============================================================================
+// Integration behavior documentation tests
+// =============================================================================
+
+describe("resolveBasePath integration scenarios", () => {
+  it("should work with typical import.meta.url usage pattern", () => {
+    // This simulates: { basePath: import.meta.url }
+    // where import.meta.url is something like "file:///path/to/tailor.config.ts"
+    const importMetaUrl = pathToFileURL(
+      "/projects/my-app/tailor.config.ts",
+    ).href;
+    const result = resolveBasePath(importMetaUrl);
+
+    // Should return the directory containing tailor.config.ts
+    expect(result).toBe("/projects/my-app");
+  });
+
+  it("should allow resolving relative module paths from the resolved base", () => {
+    const importMetaUrl = pathToFileURL(
+      "/projects/my-app/tailor.config.ts",
+    ).href;
+    const basePath = resolveBasePath(importMetaUrl);
+
+    // User can then do: path.resolve(basePath, "./modules.ts")
+    const modulesPath = path.resolve(basePath, "./modules.ts");
+    expect(modulesPath).toBe("/projects/my-app/modules.ts");
+  });
+});

package/src/config/sdk/paths.ts

@@ -1,11 +1,35 @@
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import type { DefinedModule, DependencyModules } from "../../builder/helpers";
 import type { LoadedModules } from "../module-loader";
 import { loadModuleForDev } from "./dev-context";
 import { generateWrapperFiles } from "./wrapper/generator";
 import { OMAKASE_WRAPPER_DIR } from "./wrapper/base";
 
+/**
+ * Resolve basePath from various input formats.
+ *
+ * Accepts:
+ * - `import.meta.url` (e.g., "file:///path/to/file.ts") - converted to directory path
+ * - Absolute directory path (e.g., "/path/to/dir")
+ * - `undefined` - falls back to `process.cwd()`
+ *
+ * @internal Exported for testing purposes
+ */
+export const resolveBasePath = (basePath: string | undefined): string => {
+  if (!basePath) {
+    return process.cwd();
+  }
+
+  // Handle file:// URLs (from import.meta.url)
+  if (basePath.startsWith("file://")) {
+    const filePath = fileURLToPath(basePath);
+    return path.dirname(filePath);
+  }
+
+  return basePath;
+};
+
 /**
  * Check if the imported module is a DefinedModule (from defineModule)
  * rather than a LoadedModules (from loadModules)
@@ -32,9 +56,17 @@ const isDefinedModule = (
  *
  * @example
  * ```typescript
- * // With logging enabled
+ * // With import.meta.url (recommended)
  * const moduleReference = await getModules("./modules.ts", {
- *   log: true,
+ *   basePath: import.meta.url,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With explicit directory path
+ * const moduleReference = await getModules("./modules.ts", {
+ *   basePath: "/path/to/project",
  * });
  * ```
  */
@@ -42,7 +74,19 @@ export type GetModulesOptions = {
   /**
    * Base path for resolving relative modulesPath and generating wrapper files.
    *
-   * Defaults to `process.cwd()`.
+   * Accepts:
+   * - `import.meta.url` - Automatically converted to the directory containing the caller file (recommended)
+   * - An absolute directory path
+   * - `undefined` - Falls back to `process.cwd()`
+   *
+   * @example
+   * ```typescript
+   * // Using import.meta.url (recommended)
+   * await getModules("./modules.ts", { basePath: import.meta.url });
+   *
+   * // Using explicit path
+   * await getModules("./modules.ts", { basePath: "/path/to/project" });
+   * ```
    *
    * @default process.cwd()
    */
@@ -130,7 +174,8 @@ export const getModules = async (
   modulesPath: string,
   options: GetModulesOptions = {},
 ) => {
-  const { basePath = process.cwd(), log = false } = options;
+  const { basePath: rawBasePath, log = false } = options;
+  const basePath = resolveBasePath(rawBasePath);
 
   // Resolve modules path to absolute path
   const absoluteModulesPath = path.isAbsolute(modulesPath)