dsh-plugin-t-expert 0.2.7 → 0.2.10

package/lib/catalog.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * T专家 花名册：扫描固定专家目录，解析 frontmatter，按 slug 建立索引。
  *
@@ -9,6 +10,24 @@ import { createHash } from "node:crypto";
 import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 
+/**
+ * 名册本体：`Map<slug, Expert>`，另外挂上扫描诊断与分类表。
+ *
+ * 之所以是 Map 加属性而不是 `{bySlug, ...}`：调用方（`lib/index.js`、测试）大量直接
+ * `catalog.get(slug)` / `catalog.size` / 迭代，保持 Map 形态的改动面最小。
+ * @typedef {Map<string, any> & {
+ *   divisions: string[],
+ *   rosterDivisions: string[],
+ *   customDivisions: string[],
+ *   customRoot: string | undefined,
+ *   customLabels: Record<string, string>,
+ *   sidecarPresent: boolean,
+ *   skippedFiles: number,
+ *   unreadableDivisions: string[],
+ *   labels: Record<string, string>,
+ * }} CatalogMap
+ */
+
 /** 内置的分区目录名（= divisions.json 的键）。 */
 export const DEFAULT_DIVISIONS = [
   "academic",
@@ -79,19 +98,29 @@ export async function loadDivisionLabels(zhRoot) {
  * 这样新增的分类不必改代码就能被扫描到。
  */
 export async function discoverDivisions(root) {
+  const report = { found: [], unreadable: [], rootError: undefined };
   let entries;
   try {
     entries = await readdir(root, { withFileTypes: true });
-  } catch {
-    return [];
+  } catch (error) {
+    report.rootError = error;
+    return report;
   }
-  const found = [];
   for (const entry of entries) {
     if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-    const files = await readdir(join(root, entry.name)).catch(() => []);
-    if (files.some((name) => name.endsWith(".md"))) found.push(entry.name);
+    let files;
+    try {
+      files = await readdir(join(root, entry.name));
+    } catch (error) {
+      // 分区目录读不动 —— 过去这里 `.catch(() => [])` 把它当成「没有 .md 的空分区」丢掉，
+      // 于是该分区整批专家静默缺席（单个分区不可读即可让名册 316→244，见 D-18）。
+      report.unreadable.push({ division: entry.name, error });
+      continue;
+    }
+    if (files.some((name) => name.endsWith(".md"))) report.found.push(entry.name);
   }
-  return found.sort();
+  report.found.sort();
+  return report;
 }
 
 const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,127}$/;
@@ -150,14 +179,17 @@ export function truncate(text, limit) {
   return value.length > limit ? `${value.slice(0, Math.max(0, limit - 1))}…` : value;
 }
 
-/** 递归收集目录下的 .md 文件（跳过符号链接，与 DSH 的扫描口径一致）。 */
+/**
+ * 递归收集目录下的 .md 文件（跳过符号链接，与 DSH 的扫描口径一致）。
+ *
+ * 读目录失败**不再静默返回**：整个分区不可读时（EACCES 等）那批专家会**悄悄**从名册里消失
+ * ——实测单个分区不可读就能让 316 位掉到 244 位且零日志（D-18）。现在错误带路径抛给调用方，
+ * 由调用方逐分区记 warn，名册照旧返回其余可读的部分。
+ * @param dir - 要递归的目录。
+ * @param onFile - 每个 .md 文件的回调 `(fullPath, fileName)`。
+ */
 async function walkMarkdown(dir, onFile) {
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
+  const entries = await readdir(dir, { withFileTypes: true });
   entries.sort((a, b) => a.name.localeCompare(b.name));
   for (const entry of entries) {
     const full = join(dir, entry.name);
@@ -188,41 +220,91 @@ export async function loadCatalog(root, divisions, options = {}) {
   await assertDirectory(root);
   const zhRoot = typeof options.zhRoot === "string" && options.zhRoot !== "" ? options.zhRoot : undefined;
   const customRoot = typeof options.customRoot === "string" && options.customRoot !== "" ? options.customRoot : undefined;
+  /** 宿主 logger（可选）：所有「本该说话却过去没说」的地方都走它，不再 console（N-3）。 */
+  const logger = options.logger;
+  const warn = (message) => logger?.warn?.(message);
   // 中文侧车目录：names.json / descriptions.json / <与 experts 同相对路径的 .md>。
   // 译文永不写进 experts（那是随包发布的只读名册），所以名册更新不受影响。
-  const zhNames = zhRoot === undefined ? {} : await readJson(join(zhRoot, "names.json"));
-  const zhDescriptions = zhRoot === undefined ? {} : await readJson(join(zhRoot, "descriptions.json"));
-  const divisionLabels = await loadDivisionLabels(zhRoot);
+  // 侧车缺失是**自洽的错配**（它由 seedData 播种、路径来自 Config.zhRoot），必须可观察：
+  // 过去这里静默变成「全英文名册」，面板与工具都不报错（D-5）。
+  // 侧车「可用」= 目录存在**且**至少有一个内容锚点（names/descriptions/divisions/manual/manual-bodies
+  // 或任一分区目录）。只看目录存在是不够的：存在但空（或只剩 .DS_Store）时 seedData 会跳过播种，
+  // 于是中文名/简介全空却什么都不说 —— 正是 D-5 要消灭的静默降级。
+  const sidecarDirExists = zhRoot === undefined ? true : await isDirectory(zhRoot);
+  const sidecarAnchor = zhRoot === undefined || !sidecarDirExists
+    ? undefined
+    : await firstExisting([
+      join(zhRoot, "names.json"),
+      join(zhRoot, "descriptions.json"),
+      join(zhRoot, "divisions.json"),
+      join(zhRoot, "manual.json"),
+      join(zhRoot, "manual-bodies"),
+    ]);
+  const sidecarPresent = zhRoot === undefined || (sidecarDirExists && sidecarAnchor !== undefined);
+  if (zhRoot !== undefined && !sidecarDirExists) {
+    warn(`[t-team] 中文侧车目录不存在：${zhRoot}（中文名/简介/分类标签会全部回退英文；跑一次首启播种或把 zhRoot 指到正确位置）`);
+  } else if (zhRoot !== undefined && !sidecarPresent) {
+    warn(`[t-team] 中文侧车目录存在但没有任何内容（缺少 names.json/descriptions.json 等）：${zhRoot}`
+      + `（中文名/简介/分类标签会全部回退英文；删掉这个空目录让插件下次启动重新播种）`);
+  }
+  const zhNames = zhRoot === undefined || !sidecarPresent ? {} : await readJson(join(zhRoot, "names.json"));
+  const zhDescriptions = zhRoot === undefined || !sidecarPresent ? {} : await readJson(join(zhRoot, "descriptions.json"));
+  const divisionLabels = sidecarPresent ? await loadDivisionLabels(zhRoot) : {};
   // 自建分类的显示名表（键 = 声明过的自建分类）；官方标签优先级更高，见文件末尾的合并处。
   const customLabels = await loadCustomLabels(customRoot);
   // 未显式配置分类时自动发现：新增分类无需改代码。
   // 发现结果一律按 isValidDivision 过一遍，**列表与扫描共用同一份过滤结果** ——
   // 否则目录名不合规时会出现「分区名在列表里、专家却一个都没扫到」的空分区（已实测）。
-  const scanned = (divisions !== undefined && divisions.length > 0 ? divisions : await discoverDivisions(root))
+  // 显式配置了 divisions 就不自动发现；否则用发现结果，并把「读不动的分区」报出来（D-18）。
+  const discovery = divisions !== undefined && divisions.length > 0 ? undefined : await discoverDivisions(root);
+  if (discovery?.rootError !== undefined) {
+    warn(`[t-team] 无法列出专家根目录下的分区：${root}（${String(discovery.rootError)}）`);
+  }
+  for (const item of discovery?.unreadable ?? []) {
+    warn(`[t-team] 分区目录无法读取，该分区专家已全部跳过：${join(root, item.division)}（${String(item.error)}）`);
+  }
+  const scanned = (divisions !== undefined && divisions.length > 0 ? divisions : discovery.found)
     .filter(isValidDivision);
-  const catalog = new Map();
+  /** 读不动的分区（供 host 侧 snapshot 暴露，诊断用）。 */
+  const unreadableDivisions = (discovery?.unreadable ?? []).map((item) => item.division);
+  /** @type {CatalogMap} 名册本体 + 扫描诊断（见 CatalogMap 的各字段说明）。 */
+  const catalog = /** @type {CatalogMap} */ (new Map());
 
   /** 解析一个 persona 文件并放进名册；自定义根的文件额外带 custom 标记与写回路径。 */
   async function ingest(fromRoot, division, filePath, fileName, isCustom) {
     const slug = fileName.slice(0, -3);
-    if (!SLUG_PATTERN.test(slug)) return;
+    if (!SLUG_PATTERN.test(slug)) {
+      // 文件名不合规 → 这位专家不会进名册。过去完全无声（D-18 同类）；降到 debug 是刻意的：
+      // 它属于「文件命名不合规」，不该在正常安装里刷 warn。
+      logger?.debug?.(`[t-team] 跳过文件名不合规的专家文件：${filePath}`);
+      return "skipped";
+    }
     let raw;
     try {
       raw = stripBom(await readFile(filePath, "utf8"));
-    } catch {
-      return;
+    } catch (error) {
+      // 读不到就是这位专家静默缺席的直接原因，必须可见（过去 `catch { return; }` 什么都不说）。
+      warn(`[t-team] 读不到专家文件，已跳过：${filePath}（${String(error)}）`);
+      return "skipped";
     }
     const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-    if (match === null) return;
+    if (match === null) {
+      logger?.debug?.(`[t-team] 跳过没有 frontmatter 的专家文件：${filePath}`);
+      return "skipped";
+    }
     const meta = parseMetadata(match[1]);
-    if (!meta.name || !meta.description) return;
+    if (!meta.name || !meta.description) {
+      // 缺 name/description 的专家**不会进名册**，而这是作者最常犯的错 —— 过去零信号。
+      warn(`[t-team] 专家文件缺 name 或 description，已跳过：${filePath}`);
+      return "skipped";
+    }
     if (catalog.has(slug)) {
       if (isCustom) {
         // 内置优先：自定义目录里出现同名 slug 时保留内置那位，不覆盖也不报冲突。
-        console.warn(`[t-team] 自定义专家与内置专家同 slug，已忽略：${slug}（${filePath}）`);
-        return;
+        warn(`[t-team] 自定义专家与内置专家同 slug，已忽略：${slug}（${filePath}）`);
+        return "skipped";
       }
-      console.warn(`[t-team] slug 冲突，后者覆盖前者：${slug}`);
+      warn(`[t-team] slug 冲突，后者覆盖前者：${slug}`);
     }
     const entry = {
       slug,
@@ -246,19 +328,36 @@ export async function loadCatalog(root, divisions, options = {}) {
     catalog.set(slug, entry);
   }
 
-  for (const division of scanned) {
-    await walkMarkdown(join(root, division), (filePath, fileName) => ingest(root, division, filePath, fileName, false));
-  }
+  /** 返回值用于把「跳过」计数汇总成一条 warn；逐条 debug 太吵，全静默又看不见。 */
+  let skipped = 0;
+  const walkInto = async (baseRoot, division, isCustom) => {
+    const dir = join(baseRoot, division);
+    if (!(await isDirectory(dir))) return;
+    try {
+      await walkMarkdown(dir, async (filePath, fileName) => {
+        if ((await ingest(baseRoot, division, filePath, fileName, isCustom)) === "skipped") skipped += 1;
+      });
+    } catch (error) {
+      // 分区读不动 = 这个分区下的专家整批缺席。这是「无声掉专家」的根源，必须逐分区报出来。
+      // 不抛错：其余分区仍然可用，名册照旧返回（降级但可观察）。
+      warn(`[t-team] 分区目录无法读取，该分区专家已全部跳过：${dir}（${String(error)}）`);
+    }
+  };
+
+  for (const division of scanned) await walkInto(root, division, false);
 
   // 自建专家根：目录可以不存在（还没建过任何自建专家），分区同样自动发现。
   let customDivisions = [];
   if (customRoot !== undefined) {
-    customDivisions = (await discoverDivisions(customRoot)).filter(isValidDivision);
-    for (const division of customDivisions) {
-      await walkMarkdown(join(customRoot, division), (filePath, fileName) => ingest(customRoot, division, filePath, fileName, true));
+    const customDiscovery = await discoverDivisions(customRoot);
+    for (const item of customDiscovery.unreadable) {
+      warn(`[t-team] 自建分区目录无法读取，该分区专家已全部跳过：${join(customRoot, item.division)}（${String(item.error)}）`);
     }
+    customDivisions = customDiscovery.found.filter(isValidDivision);
+    for (const division of customDivisions) await walkInto(customRoot, division, true);
   }
 
+  if (skipped > 0) warn(`[t-team] 名册加载跳过了 ${skipped} 个专家文件（原因见上面的逐条日志）`);
   if (catalog.size === 0) throw new Error(`专家目录为空或没有可解析的专家：${root}`);
   markConflicts(catalog);
   catalog.divisions = [...scanned, ...customDivisions.filter((item) => !scanned.includes(item))];
@@ -267,6 +366,10 @@ export async function loadCatalog(root, divisions, options = {}) {
   catalog.customRoot = customRoot;
   // 自建分类的显示名表；它的**键**同时就是"声明过的自建分类"——允许空分类（目录里还没有专家）。
   catalog.customLabels = customLabels;
+  // 供 host 侧 snapshot() 暴露给面板：侧车缺了、有没有专家因此跳过。
+  catalog.sidecarPresent = sidecarPresent;
+  catalog.skippedFiles = skipped;
+  catalog.unreadableDivisions = unreadableDivisions;
   // 官方标签优先：官方分类的显示名跟随中文侧车，不允许被本机覆盖（2026-09-12 用户选定）。
   catalog.labels = { ...customLabels, ...divisionLabels };
   if (zhRoot !== undefined) {
@@ -293,6 +396,26 @@ async function readJson(path) {
   }
 }
 
+/** 返回第一个存在的路径（侧车「有没有内容」的锚点探测）。 */
+async function firstExisting(paths) {
+  for (const path of paths) {
+    if (await isPath(path)) return path;
+  }
+  return undefined;
+}
+
+/** 路径是否存在（文件或目录）。 */
+async function isPath(path) {
+  const info = await stat(path).catch(() => undefined);
+  return info !== undefined;
+}
+
+/** 是否为目录（用于「侧车/分区是否存在」的存在性探测）。 */
+async function isDirectory(path) {
+  const info = await stat(path).catch(() => undefined);
+  return info !== undefined && info.isDirectory();
+}
+
 /** 是否为普通文件。 */
 async function isFile(path) {
   const info = await stat(path).catch(() => undefined);