@ohos-cpf/3rdloop 0.0.8 → 0.0.9

package/vendor/Archive/src/index/index-state.js

@@ -0,0 +1,94 @@
+/**
+ * index-state.js — 索引状态管理
+ *
+ * 判断索引是否就绪、是否需要重建（版本变更、词典指纹变更等），
+ * 并持久化索引元数据到 meta.json。
+ */
+
+import fs from 'node:fs';
+import { INDEX_VERSION } from '../constants.js';
+
+/**
+ * @typedef {Object} IndexMeta
+ * @property {string} indexVersion
+ * @property {string} termsHash
+ * @property {string} synonymsHash
+ * @property {number} segmentCount
+ * @property {number} builtAt
+ */
+
+/** @typedef {'no-index'|'engine-upgraded'|'terms-changed'|'synonyms-changed'} RebuildReason */
+
+export default class IndexState {
+  /**
+   * @param {string} dbPath
+   * @param {string} metaPath
+   * @param {import('../tokenizer/lexicon.js').default} lexicon
+   */
+  constructor(dbPath, metaPath, lexicon) {
+    this.dbPath = dbPath;
+    this.metaPath = metaPath;
+    this.lexicon = lexicon;
+  }
+
+  /**
+   * 索引是否就绪（DB 文件存在且有段数据）。
+   * @returns {Promise<boolean>}
+   */
+  async isReady() {
+    if (!fs.existsSync(this.dbPath)) return false;
+    const meta = await this.readMeta();
+    if (!meta || meta.segmentCount === 0) return false;
+    return true;
+  }
+
+  /**
+   * 判断是否需要重建及原因。
+   * @returns {Promise<RebuildReason|null>}
+   */
+  async needsRebuild() {
+    const meta = await this.readMeta();
+    if (!meta || meta.segmentCount === 0) return 'no-index';
+    if (meta.indexVersion !== INDEX_VERSION) return 'engine-upgraded';
+    if (meta.termsHash !== this.lexicon.getTermsHash()) return 'terms-changed';
+    if (meta.synonymsHash !== this.lexicon.getSynonymsHash()) return 'synonyms-changed';
+    return null;
+  }
+
+  /**
+   * 读取元数据。
+   * @returns {Promise<IndexMeta|null>}
+   */
+  async readMeta() {
+    try {
+      const raw = await fs.promises.readFile(this.metaPath, 'utf-8');
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 写入元数据。
+   * @param {IndexMeta} meta
+   * @returns {Promise<void>}
+   */
+  async writeMeta(meta) {
+    await fs.promises.writeFile(this.metaPath, JSON.stringify(meta, null, 2), 'utf-8');
+  }
+
+  /**
+   * 更新构建完成后的元数据。
+   * @param {number} segmentCount
+   * @returns {Promise<void>}
+   */
+  async markBuilt(segmentCount) {
+    await this.writeMeta({
+      indexVersion: INDEX_VERSION,
+      termsHash: this.lexicon.getTermsHash(),
+      synonymsHash: this.lexicon.getSynonymsHash(),
+      segmentCount,
+      builtAt: Date.now(),
+    });
+  }
+}

package/vendor/Archive/src/index/search-text-builder.js

@@ -0,0 +1,106 @@
+/**
+ * search-text-builder.js — 搜索文本组装
+ *
+ * 为每个 segment 按字符预算组装 search_text。
+ * 标题和 API 符号占比较高，确保精确匹配优先。
+ *
+ * 段级与文档级有不同的预算（见 constants.js）。
+ */
+
+import {
+  BUDGET_TITLE,
+  BUDGET_API_SYMBOLS,
+  BUDGET_HEADINGS,
+  BUDGET_BODY,
+  SECTION_BUDGET_TITLE,
+  SECTION_BUDGET_API_SYMBOLS,
+  SECTION_BUDGET_HEADINGS,
+  SECTION_BUDGET_BODY,
+} from '../constants.js';
+
+/**
+ * 为 segment 构建 search_text。
+ * @param {import('../parser/markdown-splitter.js').DocumentIndexSource} source
+ * @param {import('../tokenizer/tokenizer.js').default} tokenizer
+ * @returns {Promise<string>}
+ */
+export async function buildSearchText(source, tokenizer) {
+  const isSection = Boolean(source.sectionTitle);
+
+  const budgets = isSection
+    ? {
+        title: SECTION_BUDGET_TITLE,
+        api: SECTION_BUDGET_API_SYMBOLS,
+        headings: SECTION_BUDGET_HEADINGS,
+        body: SECTION_BUDGET_BODY,
+      }
+    : {
+        title: BUDGET_TITLE,
+        api: BUDGET_API_SYMBOLS,
+        headings: BUDGET_HEADINGS,
+        body: BUDGET_BODY,
+      };
+
+  const titleText = (source.titleTokens || []).join(' ');
+  const apiText = (source.apiSymbols || []).join(' ');
+
+  const parts = await Promise.all([
+    tokenizeAndCap(titleText, tokenizer, budgets.title),
+    capApiSymbols(source.apiSymbols || [], budgets.api),
+    tokenizeAndCap(source.headingsText, tokenizer, budgets.headings),
+    tokenizeAndCap(source.bodySample, tokenizer, budgets.body),
+  ]);
+
+  return parts.filter(Boolean).join(' ');
+}
+
+/**
+ * 分词后截断到指定字符数。
+ * @param {string} text
+ * @param {import('../tokenizer/tokenizer.js').default} tokenizer
+ * @param {number} maxChars
+ * @returns {Promise<string>}
+ */
+async function tokenizeAndCap(text, tokenizer, maxChars) {
+  if (!text) return '';
+  const tokens = await tokenizer.tokenizeForIndex(text);
+  return capTokens(tokens, maxChars);
+}
+
+/**
+ * API 符号直接拼接截断（不分词，保留完整性）。
+ * @param {string[]} symbols
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function capApiSymbols(symbols, maxChars) {
+  if (!symbols || symbols.length === 0) return '';
+  /** @type {string[]} */
+  const out = [];
+  let total = 0;
+  for (const sym of symbols) {
+    if (total + sym.length + 1 > maxChars) break;
+    out.push(sym);
+    total += sym.length + 1;
+  }
+  return out.join(' ');
+}
+
+/**
+ * token 数组截断到指定字符数。
+ * @param {string[]} tokens
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function capTokens(tokens, maxChars) {
+  if (!tokens || tokens.length === 0) return '';
+  /** @type {string[]} */
+  const out = [];
+  let total = 0;
+  for (const token of tokens) {
+    if (total + token.length + 1 > maxChars) break;
+    out.push(token);
+    total += token.length + 1;
+  }
+  return out.join(' ');
+}

package/vendor/Archive/src/index.js

@@ -0,0 +1,22 @@
+/**
+ * index.js — 对外导出入口
+ *
+ * 导出核心类 DocSearchEngine 和相关类型/常量，
+ * 供外部 SDK / 库形式调用。
+ *
+ * 使用示例：
+ *   import { DocSearchEngine } from './Archive/src/index.js';
+ *
+ *   const engine = new DocSearchEngine();
+ *   await engine.init({ dataDir: '/data/my-docs' });
+ *   await engine.addDocument({ documentId: 'guides/intro', catalog: 'guides', content: '# 入门' });
+ *   const results = await engine.search({ query: '入门', limit: 5 });
+ *   await engine.close();
+ */
+
+export { default as DocSearchEngine } from './engine.js';
+export { default } from './engine.js';
+
+export { DEFAULT_CATALOGS, INDEX_VERSION } from './constants.js';
+
+export { PathSafetyError } from './utils/path-safety.js';

package/vendor/Archive/src/parser/api-identifiers.js

@@ -0,0 +1,121 @@
+/**
+ * api-identifiers.js — API 符号提取与匹配
+ *
+ * 从文本和代码块中提取 API 符号，用于索引阶段增强检索召回。
+ * 规则：
+ *   1. 模块路径：@ohos.camera → camera, @ohos.camera
+ *   2. camelCase：cameraManager → cameraManager, cameramanager
+ *   3. PascalCase：CameraManager（过滤太通用的词）
+ *   4. 装饰器：@Component, @Builder
+ *
+ * 提取后去除被包含的子串（如 "camera" 被 "cameraManager" 包含时去掉）。
+ */
+
+/** 太通用的 PascalCase 词，过滤掉 */
+const GENERIC = new Set([
+  'API', 'Type', 'Value', 'Error', 'Action', 'Method', 'Class',
+  'Object', 'String', 'Number', 'Boolean', 'Array', 'Function',
+  'Param', 'Params', 'Config', 'Options', 'Result', 'Data', 'Info',
+]);
+
+/** 缩写词保留 */
+const ACRONYMS = new Set([
+  'HTTP', 'URL', 'JSON', 'XML', 'HTML', 'CSS', 'SQL', 'API',
+  'UI', 'UX', 'ID', 'UUID', 'URI', 'SSL', 'TLS', 'DNS', 'TCP',
+  'UDP', 'RPC', 'SDK', 'WASM', 'FTS', 'GIL',
+]);
+
+/**
+ * 判断 PascalCase 符号是否有价值（非通用词、足够长）。
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+function isValuable(symbol) {
+  if (GENERIC.has(symbol)) return false;
+  if (ACRONYMS.has(symbol)) return true;
+  if (symbol.length <= 3) return false;
+  return /^[A-Z]/.test(symbol);
+}
+
+/**
+ * 为符号添加大小写变体。
+ * @param {Set<string>} set
+ * @param {string} symbol
+ */
+function appendVariants(set, symbol) {
+  if (!symbol) return;
+  set.add(symbol);
+  // camelCase → 全小写
+  if (/^[a-z]/.test(symbol)) {
+    set.add(symbol.toLowerCase());
+  }
+}
+
+/**
+ * 去除被其他符号包含的子串。
+ * 例如 "camera" 被 "cameraManager" 包含时去掉 "camera"。
+ * @param {string[]} symbols
+ * @returns {string[]}
+ */
+function filterSubsumed(symbols) {
+  /** @type {string[]} */
+  const result = [];
+  const sorted = [...symbols].sort((a, b) => b.length - a.length);
+  for (const sym of sorted) {
+    const lower = sym.toLowerCase();
+    if (result.some((r) => r.toLowerCase().includes(lower) && r.toLowerCase() !== lower)) {
+      continue;
+    }
+    result.push(sym);
+  }
+  return result;
+}
+
+/**
+ * 从文本和代码块中提取 API 符号。
+ * @param {string} text
+ * @param {string[]} codeBlocks
+ * @returns {string[]}
+ */
+export function extractApiSymbols(text, codeBlocks) {
+  /** @type {Set<string>} */
+  const symbols = new Set();
+
+  for (const source of [text, ...codeBlocks]) {
+    if (!source) continue;
+
+    // 1. 模块路径: @ohos.camera
+    for (const mod of source.matchAll(/@[a-z]+\.[a-z][a-zA-Z0-9.]+/gi)) {
+      appendVariants(symbols, mod[0]);
+    }
+
+    // 2. camelCase: cameraManager
+    for (const camel of source.matchAll(/\b[a-z][a-z0-9]*[A-Z][a-zA-Z0-9]+\b/g)) {
+      appendVariants(symbols, camel[0]);
+    }
+
+    // 3. PascalCase: CameraManager
+    for (const pascal of source.matchAll(/[A-Z][a-zA-Z0-9]{2,}/g)) {
+      if (isValuable(pascal[0])) symbols.add(pascal[0]);
+    }
+
+    // 4. 装饰器: @Component, @Builder
+    for (const deco of source.matchAll(/@[A-Z][a-zA-Z]+/g)) {
+      symbols.add(deco[0]);
+    }
+  }
+
+  return filterSubsumed([...symbols]);
+}
+
+/**
+ * 判断查询 token 是否匹配文档的 API 符号集合。
+ * @param {string} token
+ * @param {string[]} apiSymbols
+ * @returns {boolean}
+ */
+export function matchApiSymbol(token, apiSymbols) {
+  if (!token || apiSymbols.length === 0) return false;
+  const lower = token.toLowerCase();
+  return apiSymbols.some((sym) => sym.toLowerCase() === lower);
+}

package/vendor/Archive/src/parser/api-suffixes.js

@@ -0,0 +1,48 @@
+/**
+ * api-suffixes.js — API 命名后缀规则
+ *
+ * 用于 API 符号提取与查询匹配，识别 HarmonyOS / ArkTS 常见的
+ * API 命名后缀（Manager, Controller, Service 等）。
+ */
+
+/** API 类名常见后缀（用于判断符号是否为 API 类） */
+export const API_SUFFIXES = [
+  'Manager',
+  'Controller',
+  'Service',
+  'Provider',
+  'Helper',
+  'Factory',
+  'Builder',
+  'Observer',
+  'Listener',
+  'Callback',
+  'Interface',
+  'Adapter',
+  'Wrapper',
+  'Handler',
+];
+
+/** API 后缀集合（O(1) 判断） */
+const API_SUFFIX_SET = new Set(API_SUFFIXES);
+
+/**
+ * 判断符号是否以已知 API 后缀结尾。
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+export function hasApiSuffix(symbol) {
+  for (const suffix of API_SUFFIXES) {
+    if (symbol.endsWith(suffix) && symbol.length > suffix.length) return true;
+  }
+  return false;
+}
+
+/**
+ * 判断符号是否为 Manager 类 API（用于 rerank 强 boost）。
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+export function isManagerApi(symbol) {
+  return symbol.endsWith('Manager') && symbol.length > 'Manager'.length;
+}

package/vendor/Archive/src/parser/heading-normalize.js

@@ -0,0 +1,40 @@
+/**
+ * heading-normalize.js — Markdown 标题规范化
+ *
+ * 统一不同 Markdown 变体下的标题文本：
+ *   - 去掉前导/尾随空白与 Markdown 标记符 (#, *)
+ *   - 合并连续空白
+ *   - 去掉行内代码标记（`code` → code）
+ *   - 折叠链接文本（[text](url) → text）
+ *
+ * 不依赖 AST 解析器，纯文本处理，作为 splitter 的辅助。
+ */
+
+/**
+ * 规范化标题文本。
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalizeHeading(raw) {
+  if (!raw) return '';
+  return raw
+    .replace(/^#+\s*/, '') // 去掉前导 #
+    .replace(/[*_~]+/g, '') // 去掉强调标记
+    .replace(/`([^`]*)`/g, '$1') // 行内代码去标记
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // 链接取文本
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * 判断标题是否像文件名（不应作为文档标题）。
+ * 例如 "getting-started"、"api/camera"。
+ * @param {string} title
+ * @returns {boolean}
+ */
+export function isFilenameLike(title) {
+  if (!title) return true;
+  // 全小写、含连字符或斜杠、无中文 → 疑似文件名
+  if (/^[a-z0-9\-_/.]+$/.test(title) && !title.includes(' ')) return true;
+  return false;
+}

package/vendor/Archive/src/parser/markdown-splitter.js

@@ -0,0 +1,215 @@
+/**
+ * markdown-splitter.js — Markdown 文档拆分为索引段
+ *
+ * 流程：
+ *   1. 按行扫描 Markdown，识别 H1-H6 标题与代码块边界。
+ *   2. 按 H4 heading 将文档拆分为多个 segment。
+ *   3. 对每个段生成 DocumentIndexSource：
+ *      sectionTitle / leadText / apiSymbols / headingsText /
+ *      titleTokens / bodySample / excerptTruncated。
+ *   4. 限制单文档最大段数（MAX_SECTIONS_PER_DOC），超出截断。
+ *
+ * 不依赖 unified/remark 等重型 AST 库，使用轻量正则 + 行扫描，
+ * 既满足拆段需求，又减少依赖体积。
+ */
+
+import {
+  MAX_SECTIONS_PER_DOC,
+  LEAD_TEXT_CHARS,
+  BUDGET_BODY,
+  SECTION_BUDGET_BODY,
+} from '../constants.js';
+import { normalizeHeading, isFilenameLike } from './heading-normalize.js';
+import { extractApiSymbols } from './api-identifiers.js';
+
+/** H4 标题行正则 */
+const H4_RE = /^####\s+(.*)$/;
+/** 任意标题行正则（捕获层级与文本） */
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+/** 代码块围栏正则 */
+const FENCE_RE = /^(```|~~~)/;
+
+/**
+ * @typedef {Object} DocumentIndexSource
+ * @property {string} sectionTitle
+ * @property {string} leadText
+ * @property {string[]} apiSymbols
+ * @property {string} headingsText
+ * @property {string[]} titleTokens
+ * @property {string} bodySample
+ * @property {boolean} excerptTruncated
+ */
+
+/**
+ * 解析文档标题（优先级：传入 > H1 > 文件名兜底）。
+ * @param {string} markdown
+ * @param {string} [explicitTitle]
+ * @param {string} [documentId]
+ * @returns {string}
+ */
+export function resolveDocTitle(markdown, explicitTitle, documentId) {
+  if (explicitTitle && !isFilenameLike(explicitTitle)) return explicitTitle;
+
+  for (const line of markdown.split('\n')) {
+    const m = line.match(/^#\s+(.*)$/);
+    if (m) {
+      const title = normalizeHeading(m[1]);
+      if (title && !isFilenameLike(title)) return title;
+    }
+  }
+
+  // 兜底：取 documentId 最后一段
+  if (documentId) {
+    const last = documentId.split('/').pop() || documentId;
+    return last.replace(/[-_]/g, ' ');
+  }
+  return 'Untitled';
+}
+
+/**
+ * 将 Markdown 拆分为索引段列表。
+ * @param {string} markdown
+ * @param {{documentId:string, docTitle:string}} ctx
+ * @returns {DocumentIndexSource[]}
+ */
+export function splitMarkdown(markdown, ctx) {
+  const lines = markdown.split('\n');
+
+  /** @type {Array<{title:string, level:number, lines:string[]}>} */
+  const sections = [];
+  /** @type {{title:string, level:number, lines:string[]}|null} */
+  let current = { title: '', level: 0, lines: [] };
+
+  let inFence = false;
+
+  for (const line of lines) {
+    // 代码块边界切换
+    if (FENCE_RE.test(line.trim())) {
+      inFence = !inFence;
+      current.lines.push(line);
+      continue;
+    }
+
+    // 代码块内不识别标题
+    if (!inFence) {
+      const h4 = line.match(H4_RE);
+      if (h4) {
+        // 结束当前段
+        if (current.lines.length > 0 || current.title) {
+          sections.push(current);
+        }
+        current = {
+          title: normalizeHeading(h4[1]),
+          level: 4,
+          lines: [],
+        };
+        continue;
+      }
+    }
+
+    current.lines.push(line);
+  }
+  // 尾段
+  if (current.lines.length > 0 || current.title) {
+    sections.push(current);
+  }
+
+  // 限制段数
+  const limited = sections.slice(0, MAX_SECTIONS_PER_DOC);
+  const truncated = sections.length > MAX_SECTIONS_PER_DOC;
+
+  /** @type {DocumentIndexSource[]} */
+  const sources = limited.map((section, idx) => {
+    const body = section.lines.join('\n');
+    const isSection = Boolean(section.title);
+
+    // 提取段内所有子标题
+    const headings = [];
+    /** @type {string[]} */
+    const codeBlocks = [];
+    let inCode = false;
+    /** @type {string[]} */
+    let codeBuf = [];
+
+    for (const line of section.lines) {
+      if (FENCE_RE.test(line.trim())) {
+        if (inCode) {
+          codeBlocks.push(codeBuf.join('\n'));
+          codeBuf = [];
+        }
+        inCode = !inCode;
+        continue;
+      }
+      if (inCode) {
+        codeBuf.push(line);
+        continue;
+      }
+      const h = line.match(HEADING_RE);
+      if (h) {
+        headings.push(normalizeHeading(h[2]));
+      }
+    }
+
+    const leadText = truncateAtWordBoundary(body.replace(/\s+/g, ' ').trim(), LEAD_TEXT_CHARS);
+    const apiSymbols = extractApiSymbols(body, codeBlocks);
+    const headingsText = headings.filter(Boolean).join(' ');
+    const titleTokens = [ctx.docTitle, section.title].filter(Boolean);
+    const bodySample = buildBodySample(body, isSection);
+
+    return {
+      sectionTitle: section.title || (idx === 0 ? ctx.docTitle : ''),
+      leadText,
+      apiSymbols,
+      headingsText,
+      titleTokens,
+      bodySample,
+      excerptTruncated: truncated && idx === limited.length - 1,
+    };
+  });
+
+  // 保证至少有一段
+  if (sources.length === 0) {
+    sources.push({
+      sectionTitle: ctx.docTitle,
+      leadText: '',
+      apiSymbols: [],
+      headingsText: '',
+      titleTokens: [ctx.docTitle],
+      bodySample: '',
+      excerptTruncated: false,
+    });
+  }
+
+  return sources;
+}
+
+/**
+ * 在词边界处截断文本。
+ * @param {string} text
+ * @param {number} maxLen
+ * @returns {string}
+ */
+function truncateAtWordBoundary(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  const slice = text.slice(0, maxLen);
+  const lastSpace = slice.lastIndexOf(' ');
+  if (lastSpace > maxLen * 0.5) return slice.slice(0, lastSpace);
+  return slice;
+}
+
+/**
+ * 构建正文样本（head + tail）。
+ * 段级与文档级有不同的预算。
+ * @param {string} body
+ * @param {boolean} isSection
+ * @returns {string}
+ */
+function buildBodySample(body, isSection) {
+  const budget = isSection ? SECTION_BUDGET_BODY : BUDGET_BODY;
+  const normalized = body.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= budget) return normalized;
+
+  const headLen = Math.floor(budget * 0.7);
+  const tailLen = budget - headLen;
+  return normalized.slice(0, headLen) + ' ' + normalized.slice(-tailLen);
+}