feat(utils): define file config (#13283)

** What
 - Allow auto-loaded Medusa files to export a config object.
 - Currently supports isDisabled to control loading.
 - new instance `FeatureFlag` exported by `@medusajs/framework/utils`
 - `feature-flags` is now a supported folder for medusa projects, modules, providers and plugins. They will be loaded and added to `FeatureFlag`

** Why
 - Enables conditional loading of routes, migrations, jobs, subscribers, workflows, and other files based on feature flags.

```ts
// /src/feature-flags

import { FlagSettings } from "@medusajs/framework/feature-flags"

const CustomFeatureFlag: FlagSettings = {
  key: "custom_feature",
  default_val: false,
  env_key: "FF_MY_CUSTOM_FEATURE",
  description: "Enable xyz",
}

export default CustomFeatureFlag
```

```ts
// /src/modules/my-custom-module/migration/Migration20250822135845.ts

import { FeatureFlag } from "@medusajs/framework/utils"

export class Migration20250822135845 extends Migration {
  override async up(){ }
  override async down(){ }
}

defineFileConfig({
  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_feature")
})
```

packages/core/utils/src/common/__tests__/flatten-object-to-key-value-pairs.spec.ts

@@ -167,7 +167,6 @@ describe("flattenObjectToKeyValuePairs", function () {
     }
 
     const keyValueParis = flattenObjectToKeyValuePairs(cart)
-    console.log(JSON.stringify(keyValueParis, null, 2))
     expect(keyValueParis).toEqual({
       id: "cart_01JRDH08QD8CZ0KJDVE410KM1J",
       currency_code: "usd",

packages/core/utils/src/common/define-file-config.ts

@@ -0,0 +1,28 @@
+import { InputFileConfig } from "@medusajs/types"
+import { getCallerFilePath } from "./get-caller-file-path"
+
+export const MEDUSA_SKIP_FILE = Symbol.for("__MEDUSA_SKIP_FILE__")
+/**
+ * The "defineFileConfig" helper can be used to define the configuration
+ * of any file auto-loaded by Medusa.
+ *
+ * It is used to avoid loading files that are not required. Like a feature flag
+ * that is disabled.
+ */
+const FILE_CONFIGS = new Map()
+export function defineFileConfig(config?: InputFileConfig) {
+  const filePath = config?.path ?? getCallerFilePath()
+  FILE_CONFIGS.set(filePath, config)
+}
+
+export function getDefinedFileConfig(path?: string) {
+  return FILE_CONFIGS.get(path)
+}
+
+export function isFileDisabled(path?: string) {
+  return !!getDefinedFileConfig(path)?.isDisabled?.()
+}
+
+export function isFileSkipped(exported: unknown) {
+  return !!exported?.[MEDUSA_SKIP_FILE]
+}

packages/core/utils/src/common/dynamic-import.ts

@@ -1,3 +1,4 @@
+import { isFileDisabled, MEDUSA_SKIP_FILE } from "./define-file-config"
 import { resolveExports } from "./resolve-exports"
 
 /**
@@ -13,5 +14,12 @@ import { resolveExports } from "./resolve-exports"
  */
 export async function dynamicImport(path: string): Promise<any> {
   const module = require(path)
-  return resolveExports(module)
+
+  const exported = resolveExports(module)
+
+  if (isFileDisabled(path)) {
+    exported[MEDUSA_SKIP_FILE] = true
+  }
+
+  return exported
 }

packages/core/utils/src/common/index.ts

@@ -15,6 +15,7 @@ export * from "./deep-equal-obj"
 export * from "./deep-flat-map"
 export * from "./deep-merge"
 export * from "./define-config"
+export * from "./define-file-config"
 export * from "./dynamic-import"
 export * from "./env-editor"
 export * from "./errors"
@@ -50,6 +51,7 @@ export * from "./map-object-to"
 export * from "./medusa-container"
 export * from "./merge-metadata"
 export * from "./merge-plugin-modules"
+export * from "./normalize-csv-value"
 export * from "./normalize-import-path-with-source"
 export * from "./object-from-string-path"
 export * from "./object-to-string-path"
@@ -69,6 +71,7 @@ export * from "./remove-nullisih"
 export * from "./remove-undefined"
 export * from "./remove-undefined-properties"
 export * from "./resolve-exports"
+export * from "./retry-execution"
 export * from "./rules"
 export * from "./selector-constraints-to-string"
 export * from "./serialize-error"
@@ -88,5 +91,3 @@ export * from "./upper-case-first"
 export * from "./validate-handle"
 export * from "./validate-module-name"
 export * from "./wrap-handler"
-export * from "./normalize-csv-value"
-export * from "./retry-execution"

packages/core/utils/src/common/normalize-import-path-with-source.ts

@@ -5,7 +5,8 @@ import { join } from "path"
  * @param path
  */
 export function normalizeImportPathWithSource(
-  path: string | undefined
+  path: string | undefined,
+  cwd: string = process.cwd()
 ): string {
   let normalizePath = path
 
@@ -19,7 +20,7 @@ export function normalizeImportPathWithSource(
      * "./src" directory inside it.
      */
     let sourceDir = normalizePath.startsWith("./src") ? "./" : "./src"
-    normalizePath = join(process.cwd(), sourceDir, normalizePath)
+    normalizePath = join(cwd, sourceDir, normalizePath)
   }
 
   return normalizePath ?? ""

packages/core/utils/src/common/read-dir-recursive.ts

@@ -25,10 +25,12 @@ export async function readDirRecursive(
   dir: string,
   options?: {
     ignoreMissing?: boolean
+    maxDepth?: number
   }
 ): Promise<Dirent[]> {
   let allEntries: Dirent[] = []
-  const readRecursive = async (dir: string) => {
+  const readRecursive = async (dir: string, depth: number = 1) => {
+    const maxDepth = options?.maxDepth ?? Infinity
     try {
       const entries = await readdir(dir, { withFileTypes: true })
       for (const entry of entries) {
@@ -38,14 +40,15 @@ export async function readDirRecursive(
         })
         allEntries.push(entry)
 
-        if (entry.isDirectory()) {
-          await readRecursive(fullPath)
+        if (entry.isDirectory() && depth < maxDepth) {
+          await readRecursive(fullPath, depth + 1)
         }
       }
     } catch (error) {
       if (options?.ignoreMissing && error.code === "ENOENT") {
         return
       }
+
       throw error
     }
   }