@qilitt-mickey/vue3-temp-skill 1.1.72 → 1.1.75

package/parser/override.js

@@ -1,119 +1,119 @@
-/**
- * override.js — 业务级映射覆写 API（V3.1 §3.4.4.3 可选扩展）
- *
- * 用途：业务项目存在少量自定义映射需求时，通过本 API 在运行时覆写
- * 指定字段，无需在业务侧维护完整 mapping/ 目录。
- *
- * 设计约束（严格按方案）：
- *   1. 浅覆写 + 深合并：覆写只落在传入的 key 上，未提及的映射原样保留。
- *   2. 不可变：返回新对象，不修改传入的 themeVars / 映射数据集。
- *   3. 白名单校验：只允许覆写词典中已存在的 key——防止业务侧拼错字段名
- *      造成静默失效（与 parser「守门员」职责一致：错误数据进不了链路）。
- *      需要放开时传 { strict: false }，未知 key 将产生告警但不阻断。
- *   4. 本 API 属链路 A（基线注入）配套能力：服务于「空白新项目从零接入
- *      Skill 主题体系」的场景；成熟模板项目（如 vue3-web-temp）不引入。
- *
- * 用法：
- *   import { themeVars, overrideMapping } from "@qilitt-mickey/vue3-temp-skill/dist/theme-vars.js";
- *   const custom = overrideMapping(themeVars, { color: { brandPrimary: "#ff6600" } });
- *
- * 或对语义 ID 映射条目覆写（parser 内部使用）：
- *   const entry = overrideMapping(baseEntry, { css_vars: { menu_bg: "--custom-var" } }, { id: "admin.layout.sidebar.menu" });
- */
-
-/** 递归合并覆写：override 中的值覆盖 base，对象做深合并，其余类型直接替换 */
-function deepMerge(base, override) {
-  const out = Array.isArray(base) ? [...base] : { ...base };
-  for (const [k, v] of Object.entries(override ?? {})) {
-    if (v !== null && typeof v === "object" && !Array.isArray(v)
-      && out[k] !== null && typeof out[k] === "object" && !Array.isArray(out[k])) {
-      out[k] = deepMerge(out[k], v);
-    }
-    else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-
-/**
- * 覆写映射对象。
- * @param {object} base     基础映射（themeVars / 单个映射条目 / 整个 dataset）
- * @param {object} override 覆写片段，结构与 base 对应部分同构
- * @param {{ id?: string, strict?: boolean }} [opts]
- *   - id：被覆写对象的标识（用于错误提示，如语义 ID 名）
- *   - strict：默认 true——override 中出现 base 不存在的 key 时抛错
- * @returns {object} 新对象（base 不被修改）
- */
-export function overrideMapping(base, override, opts = {}) {
-  const { id = "mapping", strict = true } = opts;
-  if (base === null || typeof base !== "object")
-    throw new TypeError(`overrideMapping: base 必须为对象（${id}）`);
-  if (override === null || override === undefined)
-    return base;
-  if (typeof override !== "object")
-    throw new TypeError(`overrideMapping: override 必须为对象（${id}）`);
-
-  // 白名单校验：只允许覆写已存在的 key（拼错字段名直接暴露）
-  for (const k of Object.keys(override)) {
-    if (!(k in base)) {
-      const msg = `overrideMapping: 「${k}」在 ${id} 中不存在，无法覆写${strict ? "（strict 模式，疑似字段名拼写错误）" : "（已忽略）"}`;
-      if (strict)
-        throw new Error(msg);
-      console.warn(`  ⚠ ${msg}`);
-    }
-  }
-
-  return deepMerge(base, override);
-}
-
-/**
- * 便捷封装：批量覆写多个语义 ID 条目。
- * @param {Record<string, object>} index  合并索引（id → 条目），如 buildMergedIndex 结果
- * @param {Record<string, object>} overrides { 语义ID: 覆写片段 }
- * @param {{ strict?: boolean }} [opts]
- * @returns {Record<string, object>} 新索引
- */
-export function overrideMappings(index, overrides, opts = {}) {
-  const out = { ...index };
-  for (const [id, patch] of Object.entries(overrides)) {
-    if (!out[id]) {
-      const msg = `overrideMappings: 语义 ID「${id}」不在词典中，无法覆写`;
-      if (opts.strict !== false)
-        throw new Error(msg);
-      console.warn(`  ⚠ ${msg}`);
-      continue;
-    }
-    out[id] = overrideMapping(out[id], patch, { id, strict: opts.strict !== false });
-  }
-  return out;
-}
-
-// ---- CLI 独立执行：对一份 changeset 计算覆写结果（调试用）----
-// 用法：node parser/override.js <overrides.json>
-//   overrides.json 形如 { "admin.layout.sidebar.menu": { "css_vars": { "menu_bg": "--x" } } }
-if (process.argv[1] && process.argv[1].endsWith("override.js")) {
-  const { readFileSync } = await import("node:fs");
-  const { buildMappingDataset } = await import("./loader.js");
-  const { buildMergedIndex } = await import("./validator.js");
-  const file = process.argv[2];
-  if (!file) {
-    console.error("用法：node parser/override.js <overrides.json>");
-    process.exit(1);
-  }
-  try {
-    const overrides = JSON.parse(readFileSync(file, "utf-8"));
-    const dataset = buildMappingDataset();
-    const index = buildMergedIndex(dataset);
-    const merged = overrideMappings(index, overrides);
-    const changed = Object.keys(overrides).filter(id => merged[id]);
-    console.log(`✔ 覆写成功 ${changed.length} 条：`);
-    for (const id of changed)
-      console.log(`  - ${id}`);
-    console.log(JSON.stringify(Object.fromEntries(changed.map(id => [id, merged[id]])), null, 2));
-  }
-  catch (e) {
-    console.error(`✖ 覆写失败：${e.message}`);
-    process.exit(1);
-  }
-}
+/**
+ * override.js — 业务级映射覆写 API（可选扩展）
+ *
+ * 用途：业务项目存在少量自定义映射需求时，通过本 API 在运行时覆写
+ * 指定字段，无需在业务侧维护完整 mapping/ 目录。
+ *
+ * 设计约束（严格按方案）：
+ *   1. 浅覆写 + 深合并：覆写只落在传入的 key 上，未提及的映射原样保留。
+ *   2. 不可变：返回新对象，不修改传入的 themeVars / 映射数据集。
+ *   3. 白名单校验：只允许覆写词典中已存在的 key——防止业务侧拼错字段名
+ *      造成静默失效（与 parser「守门员」职责一致：错误数据进不了链路）。
+ *      需要放开时传 { strict: false }，未知 key 将产生告警但不阻断。
+ *   4. 本 API 属链路 A（基线注入）配套能力：服务于「空白新项目从零接入
+ *      Skill 主题体系」的场景；成熟模板项目（如 vue3-web-temp）不引入。
+ *
+ * 用法：
+ *   import { themeVars, overrideMapping } from "@qilitt-mickey/vue3-temp-skill/dist/theme-vars.js";
+ *   const custom = overrideMapping(themeVars, { color: { brandPrimary: "#ff6600" } });
+ *
+ * 或对语义 ID 映射条目覆写（parser 内部使用）：
+ *   const entry = overrideMapping(baseEntry, { css_vars: { menu_bg: "--custom-var" } }, { id: "admin.layout.sidebar.menu" });
+ */
+
+/** 递归合并覆写：override 中的值覆盖 base，对象做深合并，其余类型直接替换 */
+function deepMerge(base, override) {
+  const out = Array.isArray(base) ? [...base] : { ...base };
+  for (const [k, v] of Object.entries(override ?? {})) {
+    if (v !== null && typeof v === "object" && !Array.isArray(v)
+      && out[k] !== null && typeof out[k] === "object" && !Array.isArray(out[k])) {
+      out[k] = deepMerge(out[k], v);
+    }
+    else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * 覆写映射对象。
+ * @param {object} base     基础映射（themeVars / 单个映射条目 / 整个 dataset）
+ * @param {object} override 覆写片段，结构与 base 对应部分同构
+ * @param {{ id?: string, strict?: boolean }} [opts]
+ *   - id：被覆写对象的标识（用于错误提示，如语义 ID 名）
+ *   - strict：默认 true——override 中出现 base 不存在的 key 时抛错
+ * @returns {object} 新对象（base 不被修改）
+ */
+export function overrideMapping(base, override, opts = {}) {
+  const { id = "mapping", strict = true } = opts;
+  if (base === null || typeof base !== "object")
+    throw new TypeError(`overrideMapping: base 必须为对象（${id}）`);
+  if (override === null || override === undefined)
+    return base;
+  if (typeof override !== "object")
+    throw new TypeError(`overrideMapping: override 必须为对象（${id}）`);
+
+  // 白名单校验：只允许覆写已存在的 key（拼错字段名直接暴露）
+  for (const k of Object.keys(override)) {
+    if (!(k in base)) {
+      const msg = `overrideMapping: 「${k}」在 ${id} 中不存在，无法覆写${strict ? "（strict 模式，疑似字段名拼写错误）" : "（已忽略）"}`;
+      if (strict)
+        throw new Error(msg);
+      console.warn(`  ⚠ ${msg}`);
+    }
+  }
+
+  return deepMerge(base, override);
+}
+
+/**
+ * 便捷封装：批量覆写多个语义 ID 条目。
+ * @param {Record<string, object>} index  合并索引（id → 条目），如 buildMergedIndex 结果
+ * @param {Record<string, object>} overrides { 语义ID: 覆写片段 }
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Record<string, object>} 新索引
+ */
+export function overrideMappings(index, overrides, opts = {}) {
+  const out = { ...index };
+  for (const [id, patch] of Object.entries(overrides)) {
+    if (!out[id]) {
+      const msg = `overrideMappings: 语义 ID「${id}」不在词典中，无法覆写`;
+      if (opts.strict !== false)
+        throw new Error(msg);
+      console.warn(`  ⚠ ${msg}`);
+      continue;
+    }
+    out[id] = overrideMapping(out[id], patch, { id, strict: opts.strict !== false });
+  }
+  return out;
+}
+
+// ---- CLI 独立执行：对一份 changeset 计算覆写结果（调试用）----
+// 用法：node parser/override.js <overrides.json>
+//   overrides.json 形如 { "admin.layout.sidebar.menu": { "css_vars": { "menu_bg": "--x" } } }
+if (process.argv[1] && process.argv[1].endsWith("override.js")) {
+  const { readFileSync } = await import("node:fs");
+  const { buildMappingDataset } = await import("./loader.js");
+  const { buildMergedIndex } = await import("./validator.js");
+  const file = process.argv[2];
+  if (!file) {
+    console.error("用法：node parser/override.js <overrides.json>");
+    process.exit(1);
+  }
+  try {
+    const overrides = JSON.parse(readFileSync(file, "utf-8"));
+    const dataset = buildMappingDataset();
+    const index = buildMergedIndex(dataset);
+    const merged = overrideMappings(index, overrides);
+    const changed = Object.keys(overrides).filter(id => merged[id]);
+    console.log(`✔ 覆写成功 ${changed.length} 条：`);
+    for (const id of changed)
+      console.log(`  - ${id}`);
+    console.log(JSON.stringify(Object.fromEntries(changed.map(id => [id, merged[id]])), null, 2));
+  }
+  catch (e) {
+    console.error(`✖ 覆写失败：${e.message}`);
+    process.exit(1);
+  }
+}