@intlayer/engine 9.5.6 → 9.5.7

package/dist/esm/utils/runOnce.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runOnce.mjs","names":[],"sources":["../../../src/utils/runOnce.ts"],"sourcesContent":["import { rmSync } from 'node:fs';\nimport { mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';\nimport { dirname } from 'node:path';\nimport packageJson from '@intlayer/core/package.json' with { type: 'json' };\n\n/**\n * Lifecycle of the run described by a sentinel file.\n *\n * - `running` — a process owns the sentinel and its callback is still in flight.\n *   Other processes must wait instead of starting a concurrent run.\n * - `done` — the callback completed; the sentinel is now a plain cache marker.\n */\ntype SentinelStatus = 'running' | 'done';\n\ntype SentinelData = {\n  version: string;\n  timestamp: number;\n  status: SentinelStatus;\n  /** PID of the process that owns the sentinel, used to detect abandoned locks. */\n  pid: number;\n};\n\n/** Sentinel state as read from disk, enriched with the file's modification time. */\ntype SentinelState = SentinelData & { mtimeMs: number };\n\n/**\n * Context handed to the callback so it can interact with the lock it runs under.\n */\nexport type RunOnceContext = {\n  /**\n   * Re-create the sentinel file after an operation that may have deleted it —\n   * typically cleaning the output directory, which wipes the cache directory the\n   * sentinel lives in. Without this, concurrent processes would see no lock and\n   * start a competing run while this one is still writing.\n   */\n  renewLock: () => Promise<void>;\n};\n\ntype RunOnceOptions = {\n  /**\n   * The function to execute when the sentinel is not found or is older than the cache timeout.\n   */\n  onIsCached?: () => void | Promise<void>;\n  /**\n   * The time window in milliseconds during which the sentinel is considered valid.\n   *\n   * @default 60000 = 1 minute\n   */\n  cacheTimeoutMs?: number;\n  /**\n   * If true, the callback will always run. If undefined, the callback will run only if the sentinel is older than the cache timeout.\n   *\n   * @default false\n   */\n  forceRun?: boolean;\n  /**\n   * How long to wait for another process to release the sentinel before\n   * considering its run abandoned and taking the lock over.\n   *\n   * @default 300000 = 5 minutes\n   */\n  lockWaitTimeoutMs?: number;\n};\n\nconst DEFAULT_RUN_ONCE_OPTIONS = {\n  cacheTimeoutMs: 60 * 1000, // 1 minute in milliseconds,\n  lockWaitTimeoutMs: 5 * 60 * 1000, // 5 minutes in milliseconds\n} satisfies RunOnceOptions;\n\n/** Delay between two reads of a sentinel owned by another process. */\nconst LOCK_POLL_INTERVAL_MS = 50;\n\nconst delay = (durationMs: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, durationMs));\n\n/**\n * Sentinels owned by this process, released synchronously on exit so a crash or\n * a Ctrl-C never leaves a `running` lock that would stall the next run.\n */\nconst ownedSentinelFilePaths = new Set<string>();\n\nprocess.on('exit', () => {\n  for (const sentinelFilePath of ownedSentinelFilePaths) {\n    try {\n      rmSync(sentinelFilePath, { force: true });\n    } catch {}\n  }\n});\n\n/**\n * Reads the sentinel file, returning `undefined` when it does not exist or\n * cannot be parsed.\n *\n * Sentinels written by older versions carry no `status`; they always describe a\n * finished run, so they are reported as `done`.\n */\nconst readSentinelState = async (\n  sentinelFilePath: string\n): Promise<SentinelState | undefined> => {\n  try {\n    const [sentinelStats, raw] = await Promise.all([\n      stat(sentinelFilePath),\n      readFile(sentinelFilePath, 'utf8'),\n    ]);\n\n    const parsed = JSON.parse(raw) as Partial<SentinelData>;\n\n    return {\n      version: parsed.version ?? '',\n      timestamp: parsed.timestamp ?? 0,\n      status: parsed.status ?? 'done',\n      pid: parsed.pid ?? 0,\n      mtimeMs: sentinelStats.mtime.getTime(),\n    };\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * Whether the process that wrote the sentinel is still alive. An unknown PID\n * (legacy sentinel) is assumed alive so the staleness timeout stays the only\n * way to reclaim it.\n */\nconst isOwnerProcessAlive = (pid: number): boolean => {\n  if (!pid || pid === process.pid) return true;\n\n  try {\n    // Signal 0 performs an existence check without delivering a signal.\n    process.kill(pid, 0);\n    return true;\n  } catch (error) {\n    // EPERM means the process exists but belongs to another user.\n    return (error as NodeJS.ErrnoException).code === 'EPERM';\n  }\n};\n\nconst serializeSentinel = (timestamp: number, status: SentinelStatus): string =>\n  JSON.stringify({\n    version: packageJson.version,\n    timestamp,\n    status,\n    pid: process.pid,\n  } satisfies SentinelData);\n\n/**\n * Attempts to take ownership of the sentinel.\n *\n * `wx` makes the creation atomic, so exactly one process can win even when\n * several start at the same moment.\n *\n * @returns `true` when this process now owns the sentinel, `false` when another\n * process created it first.\n */\nconst acquireSentinel = async (\n  sentinelFilePath: string,\n  timestamp: number\n): Promise<boolean> => {\n  const data = serializeSentinel(timestamp, 'running');\n\n  for (let attempt = 0; attempt < 2; attempt++) {\n    try {\n      // Ensure the directory exists before writing the file\n      await mkdir(dirname(sentinelFilePath), { recursive: true });\n\n      await writeFile(sentinelFilePath, data, { flag: 'wx' });\n      return true;\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n\n      if (code === 'EEXIST') return false;\n      // The directory was removed between the mkdir and the write (e.g. a\n      // concurrent output-directory clean); retry once.\n      if (code === 'ENOENT' && attempt === 0) continue;\n\n      throw error;\n    }\n  }\n\n  return false;\n};\n\n/**\n * Rewrites the sentinel owned by this process, overwriting any existing file.\n */\nconst writeOwnedSentinel = async (\n  sentinelFilePath: string,\n  timestamp: number,\n  status: SentinelStatus\n): Promise<void> => {\n  try {\n    await mkdir(dirname(sentinelFilePath), { recursive: true });\n    await writeFile(sentinelFilePath, serializeSentinel(timestamp, status));\n  } catch {}\n};\n\nconst removeSentinel = async (sentinelFilePath: string): Promise<void> => {\n  try {\n    await unlink(sentinelFilePath);\n  } catch {}\n};\n\n/**\n * Ensures a callback function runs only once within a specified time window across multiple processes.\n * Uses a sentinel file to coordinate execution and prevent duplicate work.\n *\n * Processes that lose the race for the sentinel wait for the owner to finish\n * rather than running a competing copy of the callback — concurrent runs would\n * otherwise write to (and clean) the same output directory at the same time.\n *\n * @param sentinelFilePath - Path to the sentinel file used for coordination\n * @param callback - The function to execute (should be async)\n * @param options - The options for the runOnce function\n *\n * @example\n * ```typescript\n * await runOnce(\n *   '/tmp/intlayer-sentinel',\n *   async ({ renewLock }) => {\n *     await cleanOutputDir(configuration); // may delete the sentinel\n *     await renewLock();\n *     await prepareIntlayer();\n *   },\n *   { cacheTimeoutMs: 30 * 1000 } // 30 seconds cache\n * );\n * ```\n *\n * @throws {Error} When there are unexpected filesystem errors\n */\nexport const runOnce = async (\n  sentinelFilePath: string,\n  callback: (context: RunOnceContext) => void | Promise<void>,\n  options?: RunOnceOptions\n) => {\n  const { onIsCached, cacheTimeoutMs, forceRun, lockWaitTimeoutMs } = {\n    ...DEFAULT_RUN_ONCE_OPTIONS,\n    ...(options ?? {}),\n  };\n  const currentTimestamp = Date.now();\n  const waitDeadline = currentTimestamp + lockWaitTimeoutMs;\n\n  // Acquisition loop: read the sentinel, then either return early (fresh cache),\n  // wait for the current owner, or take the lock. Every branch either returns or\n  // makes progress, so the loop always terminates.\n  while (true) {\n    const sentinelState = await readSentinelState(sentinelFilePath);\n\n    if (sentinelState) {\n      const sentinelAge = Date.now() - sentinelState.mtimeMs;\n\n      if (sentinelState.status === 'running') {\n        const isAbandoned =\n          sentinelAge > lockWaitTimeoutMs ||\n          !isOwnerProcessAlive(sentinelState.pid);\n\n        if (!isAbandoned && Date.now() < waitDeadline) {\n          await delay(LOCK_POLL_INTERVAL_MS);\n          continue;\n        }\n\n        // The owner died or overran the timeout: reclaim the sentinel.\n        await removeSentinel(sentinelFilePath);\n        continue;\n      }\n\n      const isCacheValid =\n        !forceRun &&\n        sentinelAge <= cacheTimeoutMs &&\n        sentinelState.version === packageJson.version;\n\n      if (isCacheValid) {\n        await onIsCached?.();\n        return;\n      }\n\n      await removeSentinel(sentinelFilePath);\n    }\n\n    const hasAcquiredSentinel = await acquireSentinel(\n      sentinelFilePath,\n      currentTimestamp\n    );\n\n    if (hasAcquiredSentinel) break;\n\n    // Another process won the race in the meantime: loop back and wait for it.\n    // The delay also guarantees the loop yields, so a sentinel being repeatedly\n    // created and removed can never turn into a busy wait.\n    await delay(LOCK_POLL_INTERVAL_MS);\n  }\n\n  ownedSentinelFilePaths.add(sentinelFilePath);\n\n  const renewLock = () =>\n    writeOwnedSentinel(sentinelFilePath, currentTimestamp, 'running');\n\n  try {\n    await callback({ renewLock });\n\n    // Mark the run as finished, re-creating the sentinel if the callback\n    // deleted it (e.g. by cleaning the output directory).\n    await writeOwnedSentinel(sentinelFilePath, currentTimestamp, 'done');\n  } catch {\n    await removeSentinel(sentinelFilePath); // Remove sentinel file if an error occurs\n  } finally {\n    ownedSentinelFilePaths.delete(sentinelFilePath);\n  }\n};\n"],"mappings":"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"}
+{"version":3,"file":"runOnce.mjs","names":[],"sources":["../../../src/utils/runOnce.ts"],"sourcesContent":["import { rmSync } from 'node:fs';\nimport {\n  mkdir,\n  readFile,\n  rmdir,\n  stat,\n  unlink,\n  writeFile,\n} from 'node:fs/promises';\nimport { dirname } from 'node:path';\nimport packageJson from '@intlayer/core/package.json' with { type: 'json' };\n\n/**\n * Lifecycle of the run described by a sentinel file.\n *\n * - `running` — a process owns the sentinel and its callback is still in flight.\n *   Other processes must wait instead of starting a concurrent run.\n * - `done` — the callback completed; the sentinel is now a plain cache marker.\n */\ntype SentinelStatus = 'running' | 'done';\n\ntype SentinelData = {\n  version: string;\n  timestamp: number;\n  status: SentinelStatus;\n  /** PID of the process that owns the sentinel, used to detect abandoned locks. */\n  pid: number;\n};\n\n/** Sentinel state as read from disk, enriched with the file's modification time. */\ntype SentinelState = SentinelData & { mtimeMs: number };\n\n/**\n * Context handed to the callback so it can interact with the lock it runs under.\n */\nexport type RunOnceContext = {\n  /**\n   * Re-create the sentinel file after an operation that may have deleted it —\n   * typically cleaning the output directory, which wipes the cache directory the\n   * sentinel lives in. Without this, concurrent processes would see no lock and\n   * start a competing run while this one is still writing.\n   */\n  renewLock: () => Promise<void>;\n};\n\ntype RunOnceOptions = {\n  /**\n   * The function to execute when the sentinel is not found or is older than the cache timeout.\n   */\n  onIsCached?: () => void | Promise<void>;\n  /**\n   * The time window in milliseconds during which the sentinel is considered valid.\n   *\n   * @default 60000 = 1 minute\n   */\n  cacheTimeoutMs?: number;\n  /**\n   * If true, the callback will always run. If undefined, the callback will run only if the sentinel is older than the cache timeout.\n   *\n   * @default false\n   */\n  forceRun?: boolean;\n  /**\n   * How long to wait for another process to release the sentinel before\n   * considering its run abandoned and taking the lock over.\n   *\n   * @default 300000 = 5 minutes\n   */\n  lockWaitTimeoutMs?: number;\n};\n\nconst DEFAULT_RUN_ONCE_OPTIONS = {\n  cacheTimeoutMs: 60 * 1000, // 1 minute in milliseconds,\n  lockWaitTimeoutMs: 5 * 60 * 1000, // 5 minutes in milliseconds\n} satisfies RunOnceOptions;\n\n/** Delay between two reads of a sentinel owned by another process. */\nconst LOCK_POLL_INTERVAL_MS = 50;\n\nconst delay = (durationMs: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, durationMs));\n\n/**\n * Sentinels owned by this process, released synchronously on exit so a crash or\n * a Ctrl-C never leaves a `running` lock that would stall the next run.\n */\nconst ownedSentinelFilePaths = new Set<string>();\n\nprocess.on('exit', () => {\n  for (const sentinelFilePath of ownedSentinelFilePaths) {\n    try {\n      rmSync(sentinelFilePath, { force: true });\n    } catch {}\n  }\n  for (const mutexDirPath of ownedMutexDirPaths) {\n    try {\n      rmSync(mutexDirPath, { recursive: true, force: true });\n    } catch {}\n  }\n});\n\n/**\n * Reads the sentinel file, returning `undefined` when it does not exist or\n * cannot be parsed.\n *\n * Sentinels written by older versions carry no `status`; they always describe a\n * finished run, so they are reported as `done`.\n */\nconst readSentinelState = async (\n  sentinelFilePath: string\n): Promise<SentinelState | undefined> => {\n  try {\n    const [sentinelStats, raw] = await Promise.all([\n      stat(sentinelFilePath),\n      readFile(sentinelFilePath, 'utf8'),\n    ]);\n\n    const parsed = JSON.parse(raw) as Partial<SentinelData>;\n\n    return {\n      version: parsed.version ?? '',\n      timestamp: parsed.timestamp ?? 0,\n      status: parsed.status ?? 'done',\n      pid: parsed.pid ?? 0,\n      mtimeMs: sentinelStats.mtime.getTime(),\n    };\n  } catch {\n    return undefined;\n  }\n};\n\n/**\n * Whether the process that wrote the sentinel is still alive. An unknown PID\n * (legacy sentinel) is assumed alive so the staleness timeout stays the only\n * way to reclaim it.\n */\nconst isOwnerProcessAlive = (pid: number): boolean => {\n  if (!pid || pid === process.pid) return true;\n\n  try {\n    // Signal 0 performs an existence check without delivering a signal.\n    process.kill(pid, 0);\n    return true;\n  } catch (error) {\n    // EPERM means the process exists but belongs to another user.\n    return (error as NodeJS.ErrnoException).code === 'EPERM';\n  }\n};\n\nconst serializeSentinel = (timestamp: number, status: SentinelStatus): string =>\n  JSON.stringify({\n    version: packageJson.version,\n    timestamp,\n    status,\n    pid: process.pid,\n  } satisfies SentinelData);\n\n/**\n * Attempts to take ownership of the sentinel.\n *\n * `wx` makes the creation atomic, so exactly one process can win even when\n * several start at the same moment.\n *\n * @returns `true` when this process now owns the sentinel, `false` when another\n * process created it first.\n */\nconst acquireSentinel = async (\n  sentinelFilePath: string,\n  timestamp: number\n): Promise<boolean> => {\n  const data = serializeSentinel(timestamp, 'running');\n\n  for (let attempt = 0; attempt < 2; attempt++) {\n    try {\n      // Ensure the directory exists before writing the file\n      await mkdir(dirname(sentinelFilePath), { recursive: true });\n\n      await writeFile(sentinelFilePath, data, { flag: 'wx' });\n      return true;\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n\n      if (code === 'EEXIST') return false;\n      // The directory was removed between the mkdir and the write (e.g. a\n      // concurrent output-directory clean); retry once.\n      if (code === 'ENOENT' && attempt === 0) continue;\n\n      throw error;\n    }\n  }\n\n  return false;\n};\n\n/**\n * Rewrites the sentinel owned by this process, overwriting any existing file.\n */\nconst writeOwnedSentinel = async (\n  sentinelFilePath: string,\n  timestamp: number,\n  status: SentinelStatus\n): Promise<void> => {\n  try {\n    await mkdir(dirname(sentinelFilePath), { recursive: true });\n    await writeFile(sentinelFilePath, serializeSentinel(timestamp, status));\n  } catch {}\n};\n\nconst removeSentinel = async (sentinelFilePath: string): Promise<void> => {\n  try {\n    await unlink(sentinelFilePath);\n  } catch {}\n};\n\n/** Delay between two attempts to enter the sentinel critical section. */\nconst MUTEX_POLL_INTERVAL_MS = 10;\n\n/**\n * A critical-section mutex older than this was left behind by a process that\n * died while holding it, and can be taken over.\n */\nconst MUTEX_STALE_MS = 10 * 1000;\n\n/** Mutex directories owned by this process, released on exit like sentinels. */\nconst ownedMutexDirPaths = new Set<string>();\n\n/**\n * Serializes the \"read the sentinel, decide, replace it\" sequence across\n * processes so it behaves as a compare-and-swap.\n *\n * Without it, two contenders reading the same stale sentinel could both remove\n * it, and the slower one would delete the `running` sentinel the faster one\n * had just created — letting two callbacks run at once. A directory is used\n * because `mkdir` is atomic on every platform.\n */\nconst withSentinelMutex = async <TResult>(\n  sentinelFilePath: string,\n  criticalSection: () => Promise<TResult>\n): Promise<TResult> => {\n  const mutexDirPath = `${sentinelFilePath}.mutex`;\n\n  while (true) {\n    try {\n      await mkdir(dirname(sentinelFilePath), { recursive: true });\n      // Non-recursive on purpose: `recursive` swallows EEXIST\n      await mkdir(mutexDirPath);\n      break;\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n\n      // The parent directory was removed between the two `mkdir` calls (e.g. a\n      // concurrent output-directory clean): recreate it and retry.\n      if (code === 'ENOENT') continue;\n      if (code !== 'EEXIST') throw error;\n\n      try {\n        const mutexStats = await stat(mutexDirPath);\n\n        if (Date.now() - mutexStats.mtime.getTime() > MUTEX_STALE_MS) {\n          await rmdir(mutexDirPath).catch(() => {});\n          continue;\n        }\n      } catch {\n        // The holder released it in the meantime: retry right away\n        continue;\n      }\n\n      await delay(MUTEX_POLL_INTERVAL_MS);\n    }\n  }\n\n  ownedMutexDirPaths.add(mutexDirPath);\n\n  try {\n    return await criticalSection();\n  } finally {\n    ownedMutexDirPaths.delete(mutexDirPath);\n    await rmdir(mutexDirPath).catch(() => {});\n  }\n};\n\n/** Outcome of one pass through the sentinel critical section. */\ntype AcquisitionOutcome = 'acquired' | 'cached' | 'wait';\n\n/**\n * Ensures a callback function runs only once within a specified time window across multiple processes.\n * Uses a sentinel file to coordinate execution and prevent duplicate work.\n *\n * Processes that lose the race for the sentinel wait for the owner to finish\n * rather than running a competing copy of the callback — concurrent runs would\n * otherwise write to (and clean) the same output directory at the same time.\n *\n * @param sentinelFilePath - Path to the sentinel file used for coordination\n * @param callback - The function to execute (should be async)\n * @param options - The options for the runOnce function\n *\n * @example\n * ```typescript\n * await runOnce(\n *   '/tmp/intlayer-sentinel',\n *   async ({ renewLock }) => {\n *     await cleanOutputDir(configuration); // may delete the sentinel\n *     await renewLock();\n *     await prepareIntlayer();\n *   },\n *   { cacheTimeoutMs: 30 * 1000 } // 30 seconds cache\n * );\n * ```\n *\n * @throws {Error} When there are unexpected filesystem errors\n */\nexport const runOnce = async (\n  sentinelFilePath: string,\n  callback: (context: RunOnceContext) => void | Promise<void>,\n  options?: RunOnceOptions\n) => {\n  const { onIsCached, cacheTimeoutMs, forceRun, lockWaitTimeoutMs } = {\n    ...DEFAULT_RUN_ONCE_OPTIONS,\n    ...(options ?? {}),\n  };\n  const currentTimestamp = Date.now();\n  const waitDeadline = currentTimestamp + lockWaitTimeoutMs;\n\n  // Acquisition loop: read the sentinel, then either return early (fresh cache),\n  // wait for the current owner, or take the lock. Every branch either returns or\n  // makes progress, so the loop always terminates.\n  while (true) {\n    const outcome = await withSentinelMutex(\n      sentinelFilePath,\n      async (): Promise<AcquisitionOutcome> => {\n        const sentinelState = await readSentinelState(sentinelFilePath);\n\n        if (sentinelState) {\n          const sentinelAge = Date.now() - sentinelState.mtimeMs;\n\n          if (sentinelState.status === 'running') {\n            const isAbandoned =\n              sentinelAge > lockWaitTimeoutMs ||\n              !isOwnerProcessAlive(sentinelState.pid);\n\n            if (!isAbandoned && Date.now() < waitDeadline) return 'wait';\n            // The owner died or overran the timeout: reclaim the sentinel below.\n          } else {\n            const isCacheValid =\n              !forceRun &&\n              sentinelAge <= cacheTimeoutMs &&\n              sentinelState.version === packageJson.version;\n\n            if (isCacheValid) return 'cached';\n          }\n\n          await removeSentinel(sentinelFilePath);\n        }\n\n        const hasAcquiredSentinel = await acquireSentinel(\n          sentinelFilePath,\n          currentTimestamp\n        );\n\n        return hasAcquiredSentinel ? 'acquired' : 'wait';\n      }\n    );\n\n    if (outcome === 'cached') {\n      await onIsCached?.();\n      return;\n    }\n\n    if (outcome === 'acquired') break;\n\n    // Another process owns the sentinel: wait for it, then look again. The\n    // delay also guarantees the loop yields, so it can never turn into a busy\n    // wait.\n    await delay(LOCK_POLL_INTERVAL_MS);\n  }\n\n  ownedSentinelFilePaths.add(sentinelFilePath);\n\n  const renewLock = () =>\n    writeOwnedSentinel(sentinelFilePath, currentTimestamp, 'running');\n\n  try {\n    await callback({ renewLock });\n\n    // Mark the run as finished, re-creating the sentinel if the callback\n    // deleted it (e.g. by cleaning the output directory).\n    await writeOwnedSentinel(sentinelFilePath, currentTimestamp, 'done');\n  } catch {\n    await removeSentinel(sentinelFilePath); // Remove sentinel file if an error occurs\n  } finally {\n    ownedSentinelFilePaths.delete(sentinelFilePath);\n  }\n};\n"],"mappings":"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"}

package/dist/esm/utils/runParallel/pidTree.mjs

@@ -1,5 +1,5 @@
-import { wmic } from "./wmic.mjs";
 import { ps } from "./ps.mjs";
+import { wmic } from "./wmic.mjs";
 import * as os$1 from "node:os";
 
 //#region src/utils/runParallel/pidTree.ts

package/dist/esm/utils/withFileLock.mjs

@@ -1,6 +1,6 @@
+import { dirname } from "node:path";
 import { rmSync } from "node:fs";
 import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
 
 //#region src/utils/withFileLock.ts
 const DEFAULT_OPTIONS = {

package/dist/esm/watcher.mjs

@@ -1,20 +1,20 @@
 import { formatPath } from "./utils/formatter.mjs";
 import { getFormatFromExtension } from "./utils/getFormatFromExtension.mjs";
 import { parseContentDeclarationFileName } from "./utils/parseContentDeclarationFileName.mjs";
-import { handleAdditionalContentDeclarationFile } from "./handleAdditionalContentDeclarationFile.mjs";
+import { prepareIntlayer } from "./prepareIntlayer.mjs";
+import { writeContentDeclaration } from "./writeContentDeclaration/writeContentDeclaration.mjs";
 import { handleContentDeclarationFileChange } from "./handleContentDeclarationFileChange.mjs";
+import { handleAdditionalContentDeclarationFile } from "./handleAdditionalContentDeclarationFile.mjs";
 import { handleContentDeclarationFileMoved } from "./handleContentDeclarationFileMoved.mjs";
 import { handleUnlinkedContentDeclarationFile } from "./handleUnlinkedContentDeclarationFile.mjs";
-import { prepareIntlayer } from "./prepareIntlayer.mjs";
-import { writeContentDeclaration } from "./writeContentDeclaration/writeContentDeclaration.mjs";
-import { existsSync, watch as watch$1 } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { basename, dirname, extname, resolve } from "node:path";
 import * as ANSIColor from "@intlayer/config/colors";
-import { transpileTSToCJS } from "@intlayer/config/file";
 import { colorize, getAppLogger } from "@intlayer/config/logger";
 import { getConfiguration, getConfigurationAndFilePath } from "@intlayer/config/node";
 import { clearAllCache, clearDiskCacheMemory, clearModuleCache, normalizePath } from "@intlayer/config/utils";
+import { existsSync, watch as watch$1 } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { transpileTSToCJS } from "@intlayer/config/file";
 
 //#region src/watcher.ts
 const pendingUnlinks = /* @__PURE__ */ new Map();

package/dist/esm/writeConfiguration/index.mjs

@@ -1,7 +1,7 @@
 import { writeFileIfChanged } from "../writeFileIfChanged.mjs";
 import { generateConfigurationContent } from "./generateConfigurationContent.mjs";
-import { mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { mkdir, readFile } from "node:fs/promises";
 
 //#region src/writeConfiguration/index.ts
 const isCachedConfigurationUpToDate = async (configuration) => {

package/dist/esm/writeContentDeclaration/processContentDeclarationContent.mjs

@@ -1,8 +1,8 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { colorizePath, x } from "@intlayer/config/logger";
-import { deepTransformNode } from "@intlayer/core/interpreter";
 import * as NodeTypes from "@intlayer/types/nodeType";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { deepTransformNode } from "@intlayer/core/interpreter";
 
 //#region src/writeContentDeclaration/processContentDeclarationContent.ts
 /**

package/dist/esm/writeContentDeclaration/transformJSFile.mjs

@@ -1,6 +1,6 @@
 import { babelTsParser } from "../utils/babelParser.mjs";
-import { getNodeType } from "@intlayer/core/dictionaryManipulator";
 import * as NodeTypes from "@intlayer/types/nodeType";
+import { getNodeType } from "@intlayer/core/dictionaryManipulator";
 import * as recast from "recast";
 
 //#region src/writeContentDeclaration/transformJSFile.ts

package/dist/esm/writeContentDeclaration/writeContentDeclaration.mjs

@@ -1,17 +1,17 @@
-import { readDictionariesFromDisk } from "../utils/readDictionariesFromDisk.mjs";
 import { getFormatFromExtension } from "../utils/getFormatFromExtension.mjs";
 import { detectFormatCommand } from "../detectFormatCommand.mjs";
+import { readDictionariesFromDisk } from "../utils/readDictionariesFromDisk.mjs";
 import { processContentDeclarationContent } from "./processContentDeclarationContent.mjs";
 import { transformJSONFile } from "./transformJSONFile.mjs";
 import { writeJSFile } from "./writeJSFile.mjs";
 import { writeMarkdownFile } from "./writeMarkdownFile.mjs";
 import { writeYamlFile } from "./writeYamlFile.mjs";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { COMPILER_NO_METADATA } from "@intlayer/config/defaultValues";
-import { getFilteredLocalesDictionary, getPerLocaleDictionary } from "@intlayer/core/plugins";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { execSync } from "node:child_process";
+import { getFilteredLocalesDictionary, getPerLocaleDictionary } from "@intlayer/core/plugins";
 import { isDeepStrictEqual } from "node:util";
 
 //#region src/writeContentDeclaration/writeContentDeclaration.ts

package/dist/esm/writeContentDeclaration/writeJSFile.mjs

@@ -1,11 +1,11 @@
 import { getFormatFromExtension } from "../utils/getFormatFromExtension.mjs";
-import { transformJSFile } from "./transformJSFile.mjs";
 import { detectFormatCommand } from "../detectFormatCommand.mjs";
+import { transformJSFile } from "./transformJSFile.mjs";
 import { getContentDeclarationFileTemplate } from "../getContentDeclarationFileTemplate/getContentDeclarationFileTemplate.mjs";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { getAppLogger, logger } from "@intlayer/config/logger";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { execSync } from "node:child_process";
 
 //#region src/writeContentDeclaration/writeJSFile.ts

package/dist/esm/writeContentDeclaration/writeMarkdownFile.mjs

@@ -1,7 +1,7 @@
 import { detectFormatCommand } from "../detectFormatCommand.mjs";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { MARKDOWN } from "@intlayer/types/nodeType";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { execSync } from "node:child_process";
 
 //#region src/writeContentDeclaration/writeMarkdownFile.ts

package/dist/esm/writeContentDeclaration/writeYamlFile.mjs

@@ -1,6 +1,6 @@
 import { detectFormatCommand } from "../detectFormatCommand.mjs";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { execSync } from "node:child_process";
 import { stringifyYaml } from "@intlayer/core/utils";
 

package/dist/esm/writeFileIfChanged.mjs

@@ -1,6 +1,6 @@
+import { basename, dirname, join } from "node:path";
 import { rmSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 
 //#region src/writeFileIfChanged.ts

package/dist/types/utils/runOnce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runOnce.d.ts","names":[],"sources":["../../../src/utils/runOnce.ts"],"mappings":";;;;YA4BY;;;;;;;EAOV,iBAAiB;;KAGd;;;;EAIH,0BAA0B;;;;;;EAM1B;;;;;;EAMA;;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAwKW,UAAO,0BACM,WACb,SAAS,0BAA0B,eAAa,UACjD,mBAAc"}
+{"version":3,"file":"runOnce.d.ts","names":[],"sources":["../../../src/utils/runOnce.ts"],"mappings":";;;;YAmCY;;;;;;;EAOV,iBAAiB;;KAGd;;;;EAIH,0BAA0B;;;;;;EAM1B;;;;;;EAMA;;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmPW,UAAO,0BACM,WACb,SAAS,0BAA0B,eAAa,UACjD,mBAAc"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/engine",
-  "version": "9.5.6",
+  "version": "9.5.7",
   "private": false,
   "description": "Scans and builds Intlayer declaration files into dictionaries based on Intlayer configuration.",
   "keywords": [