@reglow/review-mcp 0.1.0

package/catalog.mjs

@@ -0,0 +1,537 @@
+/**
+ * ReView 组件目录（内置于 MCP 服务器）
+ *
+ * ReView 组件库未发布到 npm，知识源是「本地仓库」，因此组件目录**从仓库实时解析**，
+ * 而不是像 reui 那样内置静态清单。三个权威来源：
+ * - 分类归属：`docs/.vitepress/sidebar.ts`（VitePress 侧边栏，9 个分类的权威定义）
+ * - 组件文档：`docs/components/*.md`（文档文件名即组件名，与官网 URL 末段一致）
+ * - 组件源码：`uni_modules/reglow-review/components/re-*`（easycom 标签为目录名）
+ * - 演示页：`pages/<category>/<name>/<name>.uvue`（官网「代码示例」的来源）
+ *
+ * 用途：
+ * - 未指定 component 时返回「按分类的组件总览」；
+ * - 为每个组件生成官方文档深链（human 可读的权威来源）；
+ * - 仓库内缺少组件文档时，作为回退抓取官网的路径映射。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** 官方文档站点基地址 */
+export const DOCS_BASE = "https://reglow.huoli.tech/components-library/review";
+/** 官网版本记录页 */
+export const CHANGELOG_URL = `${DOCS_BASE}/changelog`;
+/** 官网指南页前缀（快速开始 / 主题定制 / 国际化） */
+export const GUIDE_BASE = `${DOCS_BASE}/getting-started`;
+
+/** 仓库内的关键路径（相对仓库根，posix 分隔符） */
+export const SIDEBAR_FILE = "docs/.vitepress/sidebar.ts";
+export const DOCS_DIR = "docs/components";
+export const GUIDE_DIR = "docs/guide";
+export const COMPONENT_DIR = "uni_modules/reglow-review/components";
+export const DEMO_DIR = "pages";
+export const CHANGELOG_FILE = "CHANGELOG.md";
+export const README_FILE = "README.md";
+/** 组件目录 / easycom 标签前缀 */
+export const COMPONENT_PREFIX = "re-";
+
+/**
+ * 分类清单：key 为官网路由段（= `content/components-library/2.review/3.components/{n}.<key>` 去掉数字前缀），
+ * `sidebarText` 为 `docs/.vitepress/sidebar.ts` 中的分类标题（解析归属时用它匹配）。
+ *
+ * `module` 在侧边栏里写作「全局配置 Config」（只列了 config-provider），官网分类页口径为「基础模块」
+ * （还含 re-common / re-theme），这里取官网口径作为 label。
+ */
+export const CATEGORIES = [
+  { key: "base", label: "基础", english: "Basic", sidebarText: "基础 Basic" },
+  {
+    key: "navigation",
+    label: "导航",
+    english: "Navigation",
+    sidebarText: "导航 Navigation",
+  },
+  { key: "input", label: "输入", english: "Input", sidebarText: "输入 Input" },
+  {
+    key: "display",
+    label: "数据展示",
+    english: "Data Display",
+    sidebarText: "数据展示 Data Display",
+  },
+  {
+    key: "feedback",
+    label: "反馈",
+    english: "Feedback",
+    sidebarText: "反馈 Feedback",
+  },
+  {
+    key: "list-layout",
+    label: "列表与布局",
+    english: "List & Layout",
+    sidebarText: "列表与布局 List & Layout",
+  },
+  {
+    key: "marketing",
+    label: "营销",
+    english: "Marketing",
+    sidebarText: "营销 Marketing",
+  },
+  {
+    key: "business",
+    label: "业务",
+    english: "Business",
+    sidebarText: "业务 Business",
+  },
+  {
+    key: "module",
+    label: "基础模块",
+    english: "Module",
+    sidebarText: "全局配置 Config",
+  },
+];
+
+/** 官网 `pages/<key>/` 使用的分类目录名（与 CATEGORIES.key 一致） */
+export const CATEGORY_KEYS = CATEGORIES.map((item) => item.key);
+/** 未收录于侧边栏时的兜底分类 */
+export const OTHER_CATEGORY = "other";
+
+/**
+ * 一个文档页对应多个 easycom 标签的特殊情况
+ * （`docs/components/layout.md` 描述的是 `re-row` + `re-col`，仓库里没有 `re-layout` 目录）
+ */
+export const TAG_ALIASES = {
+  layout: ["re-row", "re-col"],
+};
+
+// ============================ 通用文件工具 ============================
+
+/** 统一使用 posix 分隔符（便于跨平台比对与展示） */
+export function toPosix(value) {
+  return String(value ?? "")
+    .split(path.sep)
+    .join("/");
+}
+
+/** 读取 JSON（失败返回 null） */
+export function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 递归读取目录下所有文件（相对路径，posix 分隔符）
+ *
+ * 默认跳过隐藏目录、`__tests__` 与 `*.test.js`（ReView 的组件单测也被排除）。
+ */
+export function walkFiles(dir, { skipTests = true, base = dir } = {}) {
+  const result = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    if (
+      skipTests &&
+      (entry.name === "__tests__" || entry.name.endsWith(".test.js"))
+    )
+      continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory())
+      result.push(...walkFiles(full, { skipTests, base }));
+    else if (entry.isFile()) result.push(toPosix(path.relative(base, full)));
+  }
+  return result.sort();
+}
+
+/** 目录是否存在 */
+function isDir(target) {
+  try {
+    return fs.statSync(target).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** 文件是否存在 */
+function isFile(target) {
+  try {
+    return fs.statSync(target).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** 安全读取文本文件（不存在 / 过大时返回 null） */
+function readTextSafe(file, maxBytes = 2 * 1024 * 1024) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// ============================ 文档链接 ============================
+
+/**
+ * 组件官网文档链接
+ *
+ * 与 reui 版不同的是：ReView 的 URL 需要分类段，因此 `category` 必传
+ * （分类未知时返回 null，由 `site.mjs` 从官网总览页反查）。
+ */
+export function docsUrlFor(name, category) {
+  const key = String(name ?? "").trim();
+  const group = String(category ?? "").trim();
+  if (!key || !group) return null;
+  return `${DOCS_BASE}/components/${group}/${key}`;
+}
+
+/** 官网分类总览链接 */
+export function categoryUrlFor(category) {
+  const group = String(category ?? "").trim();
+  return group ? `${DOCS_BASE}/components/${group}` : `${DOCS_BASE}/components`;
+}
+
+/** 官网版本记录页链接 */
+export function changelogUrlFor() {
+  return CHANGELOG_URL;
+}
+
+/** 官网指南页链接（topic → 路径段） */
+export function guideUrlFor(slug) {
+  const key = String(slug ?? "").trim();
+  return key ? `${GUIDE_BASE}/${key}` : GUIDE_BASE;
+}
+
+/** 组件中文名（无中文名时回退组件名） */
+export function componentLabel(entry) {
+  if (entry == null) return "";
+  if (typeof entry === "string") return entry;
+  const name = String(entry.name ?? "");
+  const cn = String(entry.cn ?? "");
+  return cn ? `${name} ${cn}` : name;
+}
+
+// ============================ sidebar.ts 解析 ============================
+
+/** 分类标题 → 分类 key */
+export function categoryKeyForText(text) {
+  const raw = String(text ?? "").trim();
+  const exact = CATEGORIES.find((item) => item.sidebarText === raw);
+  if (exact) return exact.key;
+  // 退一步：只用英文部分匹配（如 "Basic" / "List & Layout"）
+  const english = raw.replace(/[\u4e00-\u9fff]/g, "").trim();
+  const byEnglish = CATEGORIES.find(
+    (item) => item.english.toLowerCase() === english.toLowerCase(),
+  );
+  if (byEnglish) return byEnglish.key;
+  const slug = english
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+  return slug || OTHER_CATEGORY;
+}
+
+/** 侧边栏条目标题 → 中文名（"Button 按钮" → "按钮"） */
+export function chineseNameFromText(text) {
+  const raw = String(text ?? "").trim();
+  const match = raw.match(/^([A-Za-z][A-Za-z0-9\s&.-]*?)\s+([^\x00-\x7F].*)$/);
+  return match ? match[2].trim() : "";
+}
+
+/**
+ * 解析 `docs/.vitepress/sidebar.ts`（按行状态机，不用正则硬啃整个文件）
+ *
+ * 结构约定（文件内实际写法）：
+ * - 分类：`text: "基础 Basic",` 紧随其后的一行是 `collapsed: ...`
+ * - 条目：单行 `{ text: "Button 按钮", link: "/components/button" },`
+ *          或多行 `text: "DateTimePicker ...",` + `link: "/components/date-time-picker",`
+ *
+ * @returns {{ key: string, label: string, english: string, text: string, items: { name: string, cn: string }[] }[]}
+ */
+export function parseSidebarCategories(source) {
+  const lines = String(source ?? "").split(/\r?\n/);
+  const categories = [];
+  let current = null;
+
+  const nextMeaningfulLine = (from) => {
+    for (let i = from; i < lines.length; i += 1) {
+      if (lines[i].trim()) return lines[i].trim();
+    }
+    return "";
+  };
+  const pushItem = (text, link) => {
+    if (!current) return;
+    const name = String(link ?? "").match(/\/components\/([^/?#]+)\/?$/)?.[1];
+    if (!name) return;
+    if (current.items.some((item) => item.name === name)) return;
+    current.items.push({ name, cn: chineseNameFromText(text) });
+  };
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const single = lines[i].match(
+      /\{\s*text:\s*"([^"]+)"\s*,\s*link:\s*"([^"]+)"\s*\}/,
+    );
+    if (single) {
+      pushItem(single[1], single[2]);
+      continue;
+    }
+    const bare = lines[i].match(/^\s*text:\s*"([^"]+)"\s*,?\s*$/);
+    if (!bare) continue;
+    const next = nextMeaningfulLine(i + 1);
+    const link = next.match(/^link:\s*"([^"]+)"/)?.[1];
+    if (link) {
+      pushItem(bare[1], link);
+    } else if (/^collapsed:/.test(next)) {
+      const def = CATEGORIES.find(
+        (item) => item.key === categoryKeyForText(bare[1]),
+      );
+      current = {
+        key: categoryKeyForText(bare[1]),
+        label: def?.label ?? bare[1],
+        english: def?.english ?? "",
+        text: bare[1].trim(),
+        items: [],
+      };
+      categories.push(current);
+    }
+  }
+  return categories;
+}
+
+// ============================ 文档正文小工具 ============================
+
+/** 取 Markdown 的一级标题 */
+export function firstHeading(markdown) {
+  return (
+    String(markdown ?? "")
+      .match(/^#\s+(.+)$/m)?.[1]
+      ?.trim() ?? ""
+  );
+}
+
+/** 取 Markdown 首个正文段落（跳过标题 / 表格 / 引用 / 代码块） */
+export function firstParagraph(markdown) {
+  const lines = String(markdown ?? "").split(/\r?\n/);
+  const buffer = [];
+  let started = false;
+  for (const line of lines) {
+    const text = line.trim();
+    if (!started) {
+      if (text.startsWith("#")) started = true;
+      continue;
+    }
+    if (text === "") {
+      if (buffer.length) break;
+      continue;
+    }
+    if (/^(#|\||>|```|<\/|<|[-*+]\s)/.test(text)) break;
+    buffer.push(text);
+  }
+  return buffer.join(" ").trim();
+}
+
+/** 文档标题中的中文名（"# 按钮 Button" → "按钮"） */
+export function chineseNameFromHeading(heading) {
+  const raw = String(heading ?? "").trim();
+  const match = raw.match(
+    /^([^\x00-\x7F][^\x00-\x7F\s]*)\s+[A-Za-z0-9\s&.-]+$/,
+  );
+  return match ? match[1] : "";
+}
+
+// ============================ 目录构建 ============================
+
+/** 扫描 `pages/<category>/<name>/<name>.uvue`，得到 组件名 → 演示页相对路径 */
+function scanDemoPages(root) {
+  const result = new Map();
+  const pagesDir = path.join(root, DEMO_DIR);
+  if (!isDir(pagesDir)) return result;
+  for (const group of fs.readdirSync(pagesDir, { withFileTypes: true })) {
+    if (!group.isDirectory() || group.name.startsWith(".")) continue;
+    const groupDir = path.join(pagesDir, group.name);
+    for (const item of fs.readdirSync(groupDir, { withFileTypes: true })) {
+      if (!item.isDirectory() || item.name.startsWith(".")) continue;
+      const demoDir = path.join(groupDir, item.name);
+      const preferred = path.join(demoDir, `${item.name}.uvue`);
+      const target = isFile(preferred)
+        ? preferred
+        : fs.readdirSync(demoDir).find((file) => file.endsWith(".uvue")) &&
+        path.join(
+          demoDir,
+          fs.readdirSync(demoDir).find((file) => file.endsWith(".uvue")),
+        );
+      if (!target || !isFile(target)) continue;
+      if (result.has(item.name)) continue;
+      result.set(item.name, {
+        path: toPosix(path.relative(root, target)),
+        category: group.name,
+      });
+    }
+  }
+  return result;
+}
+
+/** 扫描组件源码目录，得到 组件名 → { dir, files, tag } */
+function scanComponentDirs(root) {
+  const result = new Map();
+  const componentsDir = path.join(root, COMPONENT_DIR);
+  if (!isDir(componentsDir)) return result;
+  for (const entry of fs.readdirSync(componentsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!entry.name.startsWith(COMPONENT_PREFIX)) continue;
+    const dir = path.join(componentsDir, entry.name);
+    const name = entry.name.slice(COMPONENT_PREFIX.length);
+    const files = walkFiles(dir);
+    if (files.length === 0) continue;
+    result.set(name, {
+      dir: toPosix(path.relative(root, dir)),
+      tag: entry.name,
+      files,
+    });
+  }
+  return result;
+}
+
+/**
+ * 构建组件目录
+ *
+ * @param {string} root ReView 仓库根目录（也接受只含 `uni_modules/reglow-review` 的安装目录）
+ * @returns {{
+ *   root: string, categories: object[], components: object[],
+ *   byName: Map<string, object>, componentCount: number, documentedCount: number,
+ *   catalogItem: (name: string) => object | undefined,
+ *   docsUrlFor: (name: string) => string | null,
+ *   componentLabel: (name: string) => string,
+ *   categoryOf: (key: string) => object | undefined,
+ * }}
+ */
+export function createCatalog(root) {
+  const rootPath = path.resolve(String(root ?? "."));
+  const sidebarPath = path.join(rootPath, SIDEBAR_FILE);
+  const sidebarSource = readTextSafe(sidebarPath);
+  const parsed = sidebarSource ? parseSidebarCategories(sidebarSource) : [];
+
+  const docsDir = path.join(rootPath, DOCS_DIR);
+  const docNames = isDir(docsDir)
+    ? fs
+      .readdirSync(docsDir)
+      .filter((file) => file.endsWith(".md"))
+      .map((file) => file.replace(/\.md$/, ""))
+      .sort()
+    : [];
+  const demoPages = scanDemoPages(rootPath);
+  const dirs = scanComponentDirs(rootPath);
+
+  // 组件名全集：侧边栏 ∪ 文档页 ∪ 源码目录 ∪ 演示页
+  const names = new Set([
+    ...parsed.flatMap((group) => group.items.map((item) => item.name)),
+    ...docNames,
+    ...dirs.keys(),
+    ...demoPages.keys(),
+  ]);
+
+  // 归属查询：侧边栏（权威）→ pages/<category>/ 目录 → null
+  const fromSidebar = new Map();
+  for (const group of parsed) {
+    for (const item of group.items) fromSidebar.set(item.name, { group, item });
+  }
+
+  const components = [];
+  for (const name of [...names].sort()) {
+    const docPath = docNames.includes(name) ? `${DOCS_DIR}/${name}.md` : null;
+    const docText = docPath ? readTextSafe(path.join(rootPath, docPath)) : null;
+    const sidebarHit = fromSidebar.get(name);
+    const demo = demoPages.get(name);
+    const source = dirs.get(name);
+    const category = sidebarHit?.group.key ?? demo?.category ?? OTHER_CATEGORY;
+    const def = CATEGORIES.find((item) => item.key === category);
+    const heading = firstHeading(docText);
+    const cn = sidebarHit?.item.cn || chineseNameFromHeading(heading) || "";
+    const tags = source ? [source.tag] : (TAG_ALIASES[name] ?? []);
+
+    components.push({
+      name,
+      tag: tags[0] ?? null,
+      tags,
+      cn,
+      description: docText ? firstParagraph(docText) : "",
+      category,
+      categoryLabel: def?.label ?? "其他（未收录于侧边栏）",
+      categoryEnglish: def?.english ?? "",
+      layer: source ? "uni_modules" : "docs",
+      dir: source?.dir ?? null,
+      files: source?.files ?? [],
+      docPath,
+      demoPath: demo?.path ?? null,
+      docsUrl: docsUrlFor(name, category === OTHER_CATEGORY ? null : category),
+      documented: Boolean(docPath),
+      /** 侧边栏未收录（内部子组件 / 新增但未登记） */
+      unlisted: !sidebarHit,
+    });
+  }
+
+  const byName = new Map(components.map((item) => [item.name, item]));
+
+  /** 分类总览：侧边栏分类 + 各自组件（保留侧边栏顺序） */
+  const categories = (
+    parsed.length > 0
+      ? parsed
+      : CATEGORIES.map((item) => ({
+        key: item.key,
+        label: item.label,
+        english: item.english,
+        text: item.sidebarText,
+        items: [],
+      }))
+  ).map((group) => ({
+    key: group.key,
+    label: group.label,
+    english: group.english,
+    text: group.text,
+    url: categoryUrlFor(group.key),
+    components: group.items
+      .map((item) => byName.get(item.name))
+      .filter(Boolean),
+  }));
+
+  function catalogItem(name) {
+    const raw = String(name ?? "").trim();
+    if (!raw) return null;
+    // 依次兼容：easycom 标签写法（`re-button` / `RE-BUTTON`）、驼峰名（`DateTimePicker`）、下划线
+    const normalized = raw
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .replace(new RegExp(`^${COMPONENT_PREFIX}`, "i"), "")
+      .replace(/[\s_]+/g, "-")
+      .replace(/-+/g, "-")
+      .toLowerCase();
+    return byName.get(normalized) ?? null;
+  }
+
+  return {
+    root: toPosix(rootPath),
+    categories,
+    components,
+    byName,
+    componentCount: components.length,
+    documentedCount: components.filter((item) => item.documented).length,
+    catalogItem,
+    docsUrlFor(name) {
+      return catalogItem(name)?.docsUrl ?? null;
+    },
+    componentLabel(name) {
+      return componentLabel(catalogItem(name) ?? name);
+    },
+    categoryOf(key) {
+      return CATEGORIES.find((item) => item.key === String(key ?? "").trim());
+    },
+  };
+}
+
+export { isDir, isFile, readTextSafe };

package/cli-utils.mjs

@@ -0,0 +1,29 @@
+/**
+ * CLI 通用工具（review-mcp / review-setup / review-skills 共用）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * 判断当前模块是否被「直接执行」（而非被 import）
+ *
+ * 兼容性说明：npm 安装的 bin 在软链场景（`npm link`、`npm i <本地目录>`）下，
+ * `process.argv[1]` 是软链路径，而 `import.meta.url` 指向真实路径，
+ * 直接字符串比较会判定失败并导致 CLI 静默不执行；因此两侧都做 realpath 归一化。
+ *
+ * @param {string} importMetaUrl 调用方传入的 `import.meta.url`
+ */
+export function isEntryModule(importMetaUrl) {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  const self = fileURLToPath(importMetaUrl);
+  const resolved = path.resolve(entry);
+  if (resolved === self) return true;
+  try {
+    return fs.realpathSync(resolved) === fs.realpathSync(self);
+  } catch {
+    return false;
+  }
+}