node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/lib/docs-shared.ts

@@ -0,0 +1,422 @@
+/**
+ * 帮助文档的纯函数层。
+ *
+ * 这里只放**不碰文件系统**的逻辑：front matter 解析、标题锚点、目录提取、
+ * 搜索引擎与前后篇排序。服务端读取内容在 `docs.ts`，客户端渲染直接复用本文件，
+ * 于是标题 id、目录、搜索结果三处的规则永远一致。
+ */
+
+/* ============================ 类型 ============================ */
+
+export type DocTocItem = {
+  /** 标题锚点 id（与渲染出的 heading id 完全一致） */
+  id: string;
+  text: string;
+  level: number;
+};
+
+export type DocNavPage = {
+  slug: string;
+  title: string;
+  description: string;
+  order: number;
+  updated: string;
+  readingMinutes: number;
+};
+
+export type DocNavGroup = {
+  key: string;
+  title: string;
+  description: string;
+  order: number;
+  /** 分组直属页面 */
+  pages: DocNavPage[];
+  /** 嵌套子分组 */
+  groups: DocNavGroup[];
+  /** 递归页面总数 */
+  count: number;
+};
+
+export type DocNavSection =
+  | ({ type: 'page' } & DocNavPage)
+  | ({ type: 'group' } & DocNavGroup);
+
+export type DocNav = {
+  /** 顶层页面与分组按 order 混排，侧边栏照这个顺序渲染 */
+  sections: DocNavSection[];
+};
+
+export type DocsStats = {
+  pageCount: number;
+  groupCount: number;
+  updatedAt: string;
+};
+
+export type DocRecord = {
+  slug: string;
+  title: string;
+  description: string;
+  tags: string[];
+  order: number;
+  hidden: boolean;
+  updated: string;
+  /** 已去掉 front matter 与首行 H1 的正文 */
+  body: string;
+  toc: DocTocItem[];
+  readingMinutes: number;
+  /** 所在分组链路，用于面包屑，如 ['使用指南'] */
+  groupTrail: string[];
+};
+
+export type DocSearchHit = {
+  slug: string;
+  title: string;
+  groupTitle: string;
+  description: string;
+  excerpt: string;
+  score: number;
+};
+
+/** 搜索函数需要的精简字段（避免把整篇正文传进打分函数） */
+export type SearchableDoc = {
+  slug: string;
+  title: string;
+  description: string;
+  tags: string[];
+  groupTitle: string;
+  headings: string[];
+  plainText: string;
+};
+
+/* ============================ front matter ============================ */
+
+export type FrontMatterValue = string | number | boolean | string[];
+
+export type FrontMatter = {
+  data: Record<string, FrontMatterValue>;
+  /** front matter 之后的正文 */
+  body: string;
+};
+
+function parseScalar(raw: string): FrontMatterValue {
+  const v = raw.trim();
+  if (!v) return '';
+
+  if (
+    (v.startsWith('"') && v.endsWith('"') && v.length >= 2) ||
+    (v.startsWith("'") && v.endsWith("'") && v.length >= 2)
+  ) {
+    return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\'/g, "'");
+  }
+
+  if (v.startsWith('[') && v.endsWith(']')) {
+    return v
+      .slice(1, -1)
+      .split(',')
+      .map((s) => parseScalar(s))
+      .filter((s): s is string => typeof s === 'string' && s.trim().length > 0)
+      .map((s) => s.trim());
+  }
+
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+
+  return v;
+}
+
+/**
+ * 解析 `---` 包围的简易 front matter。
+ *
+ * 刻意不引入 yaml 依赖：比赛环境离线，而文档只需要 title / description /
+ * order / tags / updated / hidden 这几个标量。解析失败一律降级为空元数据，
+ * 正文照常渲染 —— 写错一个冒号不该让整篇文档打不开。
+ */
+export function parseFrontMatter(raw: string): FrontMatter {
+  const text = String(raw ?? '').replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+  const lines = text.split('\n');
+  if (lines[0]?.trim() !== '---') return { data: {}, body: text };
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      end = i;
+      break;
+    }
+  }
+  if (end < 0) return { data: {}, body: text };
+
+  const data: Record<string, FrontMatterValue> = {};
+  for (const line of lines.slice(1, end)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const colon = trimmed.indexOf(':');
+    if (colon <= 0) continue;
+    const key = trimmed.slice(0, colon).trim().toLowerCase();
+    if (!key) continue;
+    data[key] = parseScalar(trimmed.slice(colon + 1));
+  }
+
+  return { data, body: lines.slice(end + 1).join('\n').replace(/^\n+/, '') };
+}
+
+/** front matter 的数组字段 → 字符串数组（也接受逗号分隔的单个字符串） */
+export function toTags(value: FrontMatterValue | undefined): string[] {
+  if (Array.isArray(value)) return value.map((s) => s.trim()).filter(Boolean);
+  if (typeof value === 'string') {
+    return value
+      .split(/[,，、]/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+/* ============================ Markdown 文本工具 ============================ */
+
+/** 去掉行内 Markdown 标记，保留可读文字（标题锚点、目录、搜索摘要共用） */
+export function stripInlineMarkdown(text: string): string {
+  return String(text ?? '')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/(\*\*|__)(.*?)\1/g, '$2')
+    .replace(/(\*|_)(.*?)\1/g, '$2')
+    .replace(/~~(.*?)~~/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .trim();
+}
+
+/**
+ * 标题 → 锚点 id。
+ *
+ * 同一篇文档里重名标题依次加 `-2`、`-3`。传入同一个 used 集合时，
+ * 服务端目录与客户端渲染得到的 id 必然一致，不会出现「点了目录跳不动」。
+ */
+export function headingId(text: string, used?: Set<string>): string {
+  let base = stripInlineMarkdown(text)
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, ' ')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (!base) base = 'section';
+  if (!used) return base;
+
+  let id = base;
+  let n = 2;
+  while (used.has(id)) {
+    id = `${base}-${n}`;
+    n += 1;
+  }
+  used.add(id);
+  return id;
+}
+
+/**
+ * 提取正文目录（默认 h2 / h3）。
+ *
+ * 所有级别的标题都参与编号（与渲染器一致），只是 h1 / h4+ 不进目录。
+ */
+export function extractToc(body: string, maxLevel = 3): DocTocItem[] {
+  const used = new Set<string>();
+  const out: DocTocItem[] = [];
+  let inFence = false;
+
+  for (const line of String(body ?? '').replace(/\r\n?/g, '\n').split('\n')) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    const m = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (!m) continue;
+
+    const level = m[1].length;
+    const text = stripInlineMarkdown(m[2]).trim();
+    if (!text) continue;
+
+    const id = headingId(text, used);
+    if (level >= 2 && level <= maxLevel) out.push({ id, text, level });
+  }
+
+  return out;
+}
+
+/** 去掉正文开头的第一个 H1（页面标题已由文档站渲染，正文再出现一次会重复） */
+export function stripLeadingH1(body: string): string {
+  return String(body ?? '').replace(/^\s*#\s+.*(?:\n+|$)/, '');
+}
+
+/** 取正文第一个标题（通常是被 strip 掉的 H1） */
+export function firstHeading(body: string): string {
+  const m = String(body ?? '')
+    .replace(/\r\n?/g, '\n')
+    .match(/^\s*#\s+(.+?)\s*$/m);
+  return m ? stripInlineMarkdown(m[1]).trim() : '';
+}
+
+/** 取正文第一段普通文字，作为缺省摘要 */
+export function firstParagraph(body: string): string {
+  const lines = String(body ?? '').replace(/\r\n?/g, '\n').split('\n');
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t) continue;
+    if (/^(#{1,6})\s+/.test(t)) continue;
+    if (/^```/.test(t)) continue;
+    if (/^\|?\s*:?-{2,}/.test(t)) continue;
+    if (/^>\s?/.test(t)) {
+      const quote = stripInlineMarkdown(t.replace(/^>\s?/, ''));
+      if (quote) return quote.slice(0, 160);
+      continue;
+    }
+    if (/^([-*+]|\d+[.)])\s+/.test(t)) {
+      const item = stripInlineMarkdown(t.replace(/^([-*+]|\d+[.)])\s+/, ''));
+      if (item) return item.slice(0, 160);
+      continue;
+    }
+    const text = stripInlineMarkdown(t);
+    if (text) return text.slice(0, 160);
+  }
+  return '';
+}
+
+/** Markdown → 纯文本，用于搜索与摘要（保留代码块内容，去掉标记符号） */
+export function plainTextOf(body: string): string {
+  return String(body ?? '')
+    .replace(/\r\n?/g, '\n')
+    .replace(/^\s*```.*$/gm, ' ')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/^\s{0,3}>\s?/gm, '')
+    .replace(/^\s{0,3}([-*+]|\d+[.)])\s+/gm, '')
+    .replace(/[*_~#|]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** 中文按 350 字/分钟、英文按 200 词/分钟估算，最少 1 分钟 */
+export function readingMinutesOf(text: string): number {
+  const cjk = (String(text ?? '').match(/[\u3400-\u9fff]/g) ?? []).length;
+  const latin = (String(text ?? '').match(/[A-Za-z0-9]+/g) ?? []).length;
+  return Math.max(1, Math.ceil(cjk / 350 + latin / 200));
+}
+
+/** 把命中词附近的一小段文字截出来，避免搜索结果只给一句摘要 */
+export function excerptAround(text: string, tokens: string[], maxLength = 160): string {
+  const plain = String(text ?? '').replace(/\s+/g, ' ').trim();
+  if (!plain) return '';
+
+  const lower = plain.toLowerCase();
+  let hit = -1;
+  for (const t of tokens) {
+    const i = lower.indexOf(t.toLowerCase());
+    if (i >= 0 && (hit < 0 || i < hit)) hit = i;
+  }
+
+  if (hit < 0) return plain.slice(0, maxLength) + (plain.length > maxLength ? '…' : '');
+
+  // 窗口必须先保证包含命中词，再向两侧扩展；
+  // 只按 hit - 偏移 取起点时，短窗口可能整个落在命中词之前。
+  const start = Math.max(0, Math.min(hit - Math.floor(maxLength / 2), plain.length - maxLength));
+  const end = Math.min(
+    plain.length,
+    Math.max(start + maxLength, hit + Math.max(12, Math.ceil(maxLength * 0.25)))
+  );
+  return `${start > 0 ? '…' : ''}${plain.slice(start, end)}${end < plain.length ? '…' : ''}`;
+}
+
+/* ============================ 搜索 ============================ */
+
+function tokenize(q: string): string[] {
+  return q
+    .toLowerCase()
+    .split(/[\s,，、/]+/)
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+/** 无序子序列兜底：用户只记得标题里的几个字，顺序对不上也能命中 */
+function isSubsequence(text: string, token: string): boolean {
+  if (!token) return true;
+  let i = 0;
+  for (const ch of text) {
+    if (ch === token[i]) i += 1;
+    if (i >= token.length) return true;
+  }
+  return i >= token.length;
+}
+
+function scoreOf(doc: SearchableDoc, tokens: string[]): number | null {
+  const title = doc.title.toLowerCase();
+  const desc = doc.description.toLowerCase();
+  const group = doc.groupTitle.toLowerCase();
+  const tags = doc.tags.map((t) => t.toLowerCase());
+  const headings = doc.headings.map((h) => h.toLowerCase());
+  const body = doc.plainText.toLowerCase();
+
+  let total = 0;
+  for (const t of tokens) {
+    let s = 0;
+    if (title === t) s = 240;
+    else if (title.startsWith(t)) s = 140;
+    else if (title.includes(t)) s = 100;
+    else if (tags.some((k) => k === t || k.includes(t))) s = 65;
+    else if (group.includes(t)) s = 55;
+    else if (headings.some((h) => h.includes(t))) s = 45;
+    else if (desc.includes(t)) s = 30;
+    else {
+      const count = body.split(t).length - 1;
+      if (count > 0) s = 15 + Math.min(15, count * 2);
+      else if (isSubsequence(title, t)) s = 8;
+    }
+    if (!s) return null;
+    total += s;
+  }
+
+  if (tokens.length === 1 && title === tokens[0]) total += 120;
+  return total;
+}
+
+/**
+ * 文档搜索。
+ *
+ * 与全局搜索的约定一致：所有分词都命中才算命中（AND），
+ * 标题 > 标签 > 分组 > 小标题 > 摘要 > 正文，正文按出现次数小幅加分。
+ */
+export function searchDocs(docs: SearchableDoc[], query: string, limit = 12): DocSearchHit[] {
+  const tokens = tokenize(query);
+  if (!tokens.length) return [];
+
+  const scored: { doc: SearchableDoc; score: number }[] = [];
+  for (const doc of docs) {
+    const score = scoreOf(doc, tokens);
+    if (score !== null) scored.push({ doc, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.doc.title.localeCompare(b.doc.title, 'zh-CN'));
+
+  return scored.slice(0, limit).map(({ doc, score }) => ({
+    slug: doc.slug,
+    title: doc.title,
+    groupTitle: doc.groupTitle,
+    description: doc.description,
+    excerpt: excerptAround(doc.plainText, tokens),
+    score,
+  }));
+}
+
+/* ============================ 展示工具 ============================ */
+
+export function docHref(slug: string): string {
+  const clean = String(slug ?? '').replace(/^\/+|\/+$/g, '');
+  return clean ? `/docs/${clean}` : '/docs';
+}
+
+export function formatDocDate(value: string): string {
+  const v = String(value ?? '').trim();
+  if (!v) return '';
+  return v.slice(0, 10);
+}