@wwkit/shared 1.0.28 → 1.0.29

package/src/config-loader.js

@@ -1,251 +1,251 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import os from 'node:os'
-import process from 'node:process'
-import { fileURLToPath } from 'node:url'
-import JSON5 from 'json5'
-
-const ENV_PATTERN = /\{env:(\w+)\}/g
-const PKG_PATTERN = /\{pkg:([^}]+)\}/g
-
-const _selfDir = path.dirname(fileURLToPath(import.meta.url))
-
-/**
- * 向上查找 pnpm 工作区根目录
- * @param {string} startDir
- * @returns {string|null}
- */
-function findWorkspaceRoot(startDir) {
-  let dir = startDir
-  while (dir !== path.dirname(dir)) {
-    if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml'))) return dir
-    const packagesDir = path.join(dir, 'packages')
-    if (fs.existsSync(packagesDir) && fs.existsSync(path.join(dir, 'package.json'))) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
-        if (pkg.private && pkg.workspaces) return dir
-      } catch {}
-    }
-    dir = path.dirname(dir)
-  }
-  return null
-}
-
-/**
- * 解析 npm 包的安装目录路径
- *
- * 从当前文件位置向外逐级查找 node_modules 目录，在其中定位目标包。
- * {pkg:XX} 的目标包必然与当前包在同一个 node_modules 空间下，
- * 因此只需向外找到最近的 node_modules 即可命中。
- * 开发环境下回退到工作区 packages/ 目录。
- *
- * @param {string} pkgName - 包名，如 @wwkit/harness
- * @returns {string} 目录路径，找不到时返回空串
- */
-function resolvePkgPath(pkgName) {
-  let dir = _selfDir
-  while (dir !== path.dirname(dir)) {
-    const pkgJsonPath = path.join(dir, 'node_modules', pkgName, 'package.json')
-    if (fs.existsSync(pkgJsonPath)) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
-        if (pkg.name === pkgName) return path.dirname(pkgJsonPath)
-      } catch {}
-    }
-    dir = path.dirname(dir)
-  }
-  const wsRoot = findWorkspaceRoot(_selfDir)
-  if (wsRoot) {
-    const seg = pkgName.includes('/') ? pkgName.split('/').pop() : pkgName
-    const candidate = path.join(wsRoot, 'packages', seg)
-    const pkgJson = path.join(candidate, 'package.json')
-    if (fs.existsSync(pkgJson)) {
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgJson, 'utf8'))
-        if (pkg.name === pkgName) return candidate
-      } catch {}
-    }
-  }
-  return ''
-}
-
-/**
- * 递归检查 builtin 是否有 user 缺少的 key（嵌套对象也递归比较）。
- * @param {*} builtin
- * @param {*} user
- * @returns {boolean}
- */
-function hasMissingKeys(builtin, user) {
-  if (!builtin || typeof builtin !== 'object' || Array.isArray(builtin)) return false
-  if (!user || typeof user !== 'object' || Array.isArray(user)) return false
-  for (const key of Object.keys(builtin)) {
-    if (!(key in user)) return true
-    const bv = builtin[key]
-    const uv = user[key]
-    if (bv && typeof bv === 'object' && !Array.isArray(bv)
-        && uv && typeof uv === 'object' && !Array.isArray(uv)) {
-      if (hasMissingKeys(bv, uv)) return true
-    }
-  }
-  return false
-}
-
-/**
- * 递归合并对象，override 优先，嵌套对象深合并（数组/标量直接覆盖）。
- */
-export function deepMerge(base, override) {
-  const merged = { ...(base ?? {}) }
-  for (const [key, value] of Object.entries(override ?? {})) {
-    if (value && typeof value === 'object' && !Array.isArray(value)
-        && merged[key] && typeof merged[key] === 'object' && !Array.isArray(merged[key])) {
-      merged[key] = deepMerge(merged[key], value)
-    } else {
-      merged[key] = value
-    }
-  }
-  return merged
-}
-
-/**
- * 递归解析字符串中的 {env:XXX} 占位符，替换为环境变量值（未设置则为空串）。
- */
-export function resolveEnvVars(value, env = process.env) {
-  if (typeof value === 'string') {
-    return value.replace(ENV_PATTERN, (_, name) => env[name] ?? '')
-  }
-  if (Array.isArray(value)) {
-    return value.map((v) => resolveEnvVars(v, env))
-  }
-  if (value && typeof value === 'object') {
-    const out = {}
-    for (const [k, v] of Object.entries(value)) out[k] = resolveEnvVars(v, env)
-    return out
-  }
-  return value
-}
-
-/**
- * 递归解析字符串中的 {pkg:NAME} 占位符，替换为包安装目录（找不到则为空串）。
- */
-export function resolvePkgVars(value) {
-  if (typeof value === 'string') {
-    return value.replace(PKG_PATTERN, (_, name) => resolvePkgPath(name.trim()))
-  }
-  if (Array.isArray(value)) {
-    return value.map((v) => resolvePkgVars(v))
-  }
-  if (value && typeof value === 'object') {
-    const out = {}
-    for (const [k, v] of Object.entries(value)) out[k] = resolvePkgVars(v)
-    return out
-  }
-  return value
-}
-
-/**
- * 多层配置加载器：内置 config.json5 + 用户 config.json5 + 环境变量注入内容（优先级从低到高）。
- *
- * 默认行为（无需配置）：
- *   - 深合并（deepMerge），非浅合并
- *   - 结果默认解析 {env:XXX} 占位符
- *
- * 可选层（通过选项开启）：
- *   - envContentVar: 指定环境变量名，其内容作为"注入配置"这一层参与合并（优先级最高，同样走深合并+占位符解析）
- *   - envDirVar:     指定环境变量名，其值覆盖用户配置目录
- *
- * 用法：
- *   const loader = createConfigLoader({
- *     builtinConfigPath: path.join(__dirname, 'config.json5'),
- *     userConfigDir: getXdgConfigDir('cft'),
- *   })
- *   loader.copyBuiltinConfig()  // 复制内置→用户目录（不覆盖已存在）
- *   const cfg = loader.getConfig()
- */
-export function createConfigLoader({ builtinConfigPath, userConfigDir, envContentVar = null, envDirVar = null }) {
-  const getUserDir = () => (envDirVar ? (process.env[envDirVar] ?? userConfigDir) : userConfigDir)
-  const getUserConfigPath = () => path.join(getUserDir(), 'config.json5')
-
-  function loadJson5(filePath) {
-    if (!filePath || !fs.existsSync(filePath)) return {}
-    try {
-      return JSON5.parse(fs.readFileSync(filePath, 'utf-8'))
-    } catch {
-      return {}
-    }
-  }
-
-  function loadContent(content) {
-    if (!content) return {}
-    try {
-      return JSON5.parse(content)
-    } catch {
-      return {}
-    }
-  }
-
-  function getConfig() {
-    const builtin = loadJson5(builtinConfigPath)
-    const user = loadJson5(getUserConfigPath())
-    let merged = deepMerge(builtin, user)
-    if (envContentVar) {
-      merged = deepMerge(merged, loadContent(process.env[envContentVar]))
-    }
-    return resolvePkgVars(resolveEnvVars(merged))
-  }
-
-  function copyBuiltinConfig() {
-    const dir = getUserDir()
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true })
-    }
-    const userPath = getUserConfigPath()
-    if (!fs.existsSync(userPath) && fs.existsSync(builtinConfigPath)) {
-      fs.copyFileSync(builtinConfigPath, userPath)
-      return true
-    }
-    return false
-  }
-
-  /**
-   * 合并内置配置到用户配置文件：
-   * 用户文件不存在 → 复制 builtin；已存在 → 追加缺失 key（不覆盖已有值）。
-   * @returns {boolean} 是否写入了文件
-   */
-  function mergeBuiltinConfig() {
-    const dir = getUserDir()
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true })
-    }
-    const userPath = getUserConfigPath()
-    if (!fs.existsSync(userPath)) {
-      if (fs.existsSync(builtinConfigPath)) {
-        fs.copyFileSync(builtinConfigPath, userPath)
-        return true
-      }
-      return false
-    }
-    const builtin = loadJson5(builtinConfigPath)
-    const user = loadJson5(userPath)
-    if (!hasMissingKeys(builtin, user)) return false
-    const merged = deepMerge(builtin, user)
-    fs.writeFileSync(userPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8')
-    return true
-  }
-
-  return {
-    getConfig,
-    copyBuiltinConfig,
-    mergeBuiltinConfig,
-    userConfigDir: getUserDir(),
-    userConfigPath: getUserConfigPath(),
-  }
-}
-
-/**
- * 获取 XDG 配置目录下的子路径。
- * ~/.config/<subdir>  或  $XDG_CONFIG_HOME/<subdir>
- */
-export function getXdgConfigDir(subdir) {
-  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config')
-  return path.join(xdg, subdir)
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import JSON5 from 'json5'
+
+const ENV_PATTERN = /\{env:(\w+)\}/g
+const PKG_PATTERN = /\{pkg:([^}]+)\}/g
+
+const _selfDir = path.dirname(fileURLToPath(import.meta.url))
+
+/**
+ * 向上查找 pnpm 工作区根目录
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+function findWorkspaceRoot(startDir) {
+  let dir = startDir
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml'))) return dir
+    const packagesDir = path.join(dir, 'packages')
+    if (fs.existsSync(packagesDir) && fs.existsSync(path.join(dir, 'package.json'))) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
+        if (pkg.private && pkg.workspaces) return dir
+      } catch {}
+    }
+    dir = path.dirname(dir)
+  }
+  return null
+}
+
+/**
+ * 解析 npm 包的安装目录路径
+ *
+ * 从当前文件位置向外逐级查找 node_modules 目录，在其中定位目标包。
+ * {pkg:XX} 的目标包必然与当前包在同一个 node_modules 空间下，
+ * 因此只需向外找到最近的 node_modules 即可命中。
+ * 开发环境下回退到工作区 packages/ 目录。
+ *
+ * @param {string} pkgName - 包名，如 @wwkit/harness
+ * @returns {string} 目录路径，找不到时返回空串
+ */
+function resolvePkgPath(pkgName) {
+  let dir = _selfDir
+  while (dir !== path.dirname(dir)) {
+    const pkgJsonPath = path.join(dir, 'node_modules', pkgName, 'package.json')
+    if (fs.existsSync(pkgJsonPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+        if (pkg.name === pkgName) return path.dirname(pkgJsonPath)
+      } catch {}
+    }
+    dir = path.dirname(dir)
+  }
+  const wsRoot = findWorkspaceRoot(_selfDir)
+  if (wsRoot) {
+    const seg = pkgName.includes('/') ? pkgName.split('/').pop() : pkgName
+    const candidate = path.join(wsRoot, 'packages', seg)
+    const pkgJson = path.join(candidate, 'package.json')
+    if (fs.existsSync(pkgJson)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJson, 'utf8'))
+        if (pkg.name === pkgName) return candidate
+      } catch {}
+    }
+  }
+  return ''
+}
+
+/**
+ * 递归检查 builtin 是否有 user 缺少的 key（嵌套对象也递归比较）。
+ * @param {*} builtin
+ * @param {*} user
+ * @returns {boolean}
+ */
+function hasMissingKeys(builtin, user) {
+  if (!builtin || typeof builtin !== 'object' || Array.isArray(builtin)) return false
+  if (!user || typeof user !== 'object' || Array.isArray(user)) return false
+  for (const key of Object.keys(builtin)) {
+    if (!(key in user)) return true
+    const bv = builtin[key]
+    const uv = user[key]
+    if (bv && typeof bv === 'object' && !Array.isArray(bv)
+        && uv && typeof uv === 'object' && !Array.isArray(uv)) {
+      if (hasMissingKeys(bv, uv)) return true
+    }
+  }
+  return false
+}
+
+/**
+ * 递归合并对象，override 优先，嵌套对象深合并（数组/标量直接覆盖）。
+ */
+export function deepMerge(base, override) {
+  const merged = { ...(base ?? {}) }
+  for (const [key, value] of Object.entries(override ?? {})) {
+    if (value && typeof value === 'object' && !Array.isArray(value)
+        && merged[key] && typeof merged[key] === 'object' && !Array.isArray(merged[key])) {
+      merged[key] = deepMerge(merged[key], value)
+    } else {
+      merged[key] = value
+    }
+  }
+  return merged
+}
+
+/**
+ * 递归解析字符串中的 {env:XXX} 占位符，替换为环境变量值（未设置则为空串）。
+ */
+export function resolveEnvVars(value, env = process.env) {
+  if (typeof value === 'string') {
+    return value.replace(ENV_PATTERN, (_, name) => env[name] ?? '')
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => resolveEnvVars(v, env))
+  }
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const [k, v] of Object.entries(value)) out[k] = resolveEnvVars(v, env)
+    return out
+  }
+  return value
+}
+
+/**
+ * 递归解析字符串中的 {pkg:NAME} 占位符，替换为包安装目录（找不到则为空串）。
+ */
+export function resolvePkgVars(value) {
+  if (typeof value === 'string') {
+    return value.replace(PKG_PATTERN, (_, name) => resolvePkgPath(name.trim()))
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => resolvePkgVars(v))
+  }
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const [k, v] of Object.entries(value)) out[k] = resolvePkgVars(v)
+    return out
+  }
+  return value
+}
+
+/**
+ * 多层配置加载器：内置 config.json5 + 用户 config.json5 + 环境变量注入内容（优先级从低到高）。
+ *
+ * 默认行为（无需配置）：
+ *   - 深合并（deepMerge），非浅合并
+ *   - 结果默认解析 {env:XXX} 占位符
+ *
+ * 可选层（通过选项开启）：
+ *   - envContentVar: 指定环境变量名，其内容作为"注入配置"这一层参与合并（优先级最高，同样走深合并+占位符解析）
+ *   - envDirVar:     指定环境变量名，其值覆盖用户配置目录
+ *
+ * 用法：
+ *   const loader = createConfigLoader({
+ *     builtinConfigPath: path.join(__dirname, 'config.json5'),
+ *     userConfigDir: getXdgConfigDir('cft'),
+ *   })
+ *   loader.copyBuiltinConfig()  // 复制内置→用户目录（不覆盖已存在）
+ *   const cfg = loader.getConfig()
+ */
+export function createConfigLoader({ builtinConfigPath, userConfigDir, envContentVar = null, envDirVar = null }) {
+  const getUserDir = () => (envDirVar ? (process.env[envDirVar] ?? userConfigDir) : userConfigDir)
+  const getUserConfigPath = () => path.join(getUserDir(), 'config.json5')
+
+  function loadJson5(filePath) {
+    if (!filePath || !fs.existsSync(filePath)) return {}
+    try {
+      return JSON5.parse(fs.readFileSync(filePath, 'utf-8'))
+    } catch {
+      return {}
+    }
+  }
+
+  function loadContent(content) {
+    if (!content) return {}
+    try {
+      return JSON5.parse(content)
+    } catch {
+      return {}
+    }
+  }
+
+  function getConfig() {
+    const builtin = loadJson5(builtinConfigPath)
+    const user = loadJson5(getUserConfigPath())
+    let merged = deepMerge(builtin, user)
+    if (envContentVar) {
+      merged = deepMerge(merged, loadContent(process.env[envContentVar]))
+    }
+    return resolvePkgVars(resolveEnvVars(merged))
+  }
+
+  function copyBuiltinConfig() {
+    const dir = getUserDir()
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+    const userPath = getUserConfigPath()
+    if (!fs.existsSync(userPath) && fs.existsSync(builtinConfigPath)) {
+      fs.copyFileSync(builtinConfigPath, userPath)
+      return true
+    }
+    return false
+  }
+
+  /**
+   * 合并内置配置到用户配置文件：
+   * 用户文件不存在 → 复制 builtin；已存在 → 追加缺失 key（不覆盖已有值）。
+   * @returns {boolean} 是否写入了文件
+   */
+  function mergeBuiltinConfig() {
+    const dir = getUserDir()
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+    const userPath = getUserConfigPath()
+    if (!fs.existsSync(userPath)) {
+      if (fs.existsSync(builtinConfigPath)) {
+        fs.copyFileSync(builtinConfigPath, userPath)
+        return true
+      }
+      return false
+    }
+    const builtin = loadJson5(builtinConfigPath)
+    const user = loadJson5(userPath)
+    if (!hasMissingKeys(builtin, user)) return false
+    const merged = deepMerge(builtin, user)
+    fs.writeFileSync(userPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8')
+    return true
+  }
+
+  return {
+    getConfig,
+    copyBuiltinConfig,
+    mergeBuiltinConfig,
+    userConfigDir: getUserDir(),
+    userConfigPath: getUserConfigPath(),
+  }
+}
+
+/**
+ * 获取 XDG 配置目录下的子路径。
+ * ~/.config/<subdir>  或  $XDG_CONFIG_HOME/<subdir>
+ */
+export function getXdgConfigDir(subdir) {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config')
+  return path.join(xdg, subdir)
 }