project-node-memory 0.0.0-stage → 1.0.1

package/lib/engine/commands.js

@@ -0,0 +1,84 @@
+/**
+ * commands —— read / search / diag / dump 的语义层。
+ *
+ * 逐行对齐 Python 版 commands.py：返回值都是 { text | report, code }，
+ * 工具层（host/tools.js）与路由层（host/routes.js）只负责把它包装成工具结果 / HTTP 响应。
+ * 移植期用 test/parity.mjs 拿 Python 原实现逐条对拍。
+ */
+
+import { render_node, render_subtree, toc_lines, node_info, resolve_path, TransclusionError } from './render.js'
+import { search, formatSearch } from './search.js'
+import { diag } from './diag.js'
+import { lib_root_tids } from './mdlib.js'
+
+// 整支渲染字符上限（0 = 不限）。防止一次调用打爆上下文（root ≈ 23.5 万字符）
+export const DEFAULT_MAXLEN = 50000
+
+/** 读取：默认整支；node=仅该节点；toc=目录；raw=元信息 */
+export function cmdRead(nodes, target, { node = false, raw = false, toc = false, maxlen = 0 } = {}) {
+  let tid
+  try {
+    tid = resolve_path(nodes, target)
+  } catch (e) {
+    return { text: e.message, code: 2 }
+  }
+  if (tid === null) {
+    const cands = [...nodes.keys()]
+      .filter((t) => t.startsWith(target) || t.startsWith(target + ':'))
+      .sort()
+      .slice(0, 10)
+    let msg = `未找到节点: ${target}`
+    if (cands.length) msg += '；候选: ' + cands.join('、')
+    return { text: msg, code: 2 }
+  }
+  try {
+    if (toc) return { text: toc_lines(nodes, tid).join('\n'), code: 0 }
+    if (raw) return { text: JSON.stringify(node_info(nodes, tid), null, 2), code: 0 }
+    if (node) {
+      let out = render_node(nodes, tid)
+      const kids = [...nodes.values()].filter((c) => c.parent_tid === tid)
+      if (kids.length) {
+        // 反直觉提示：带 ## 子节的页面只读 node 只回前言
+        out += `\n\n（本节点含 ${kids.length} 个子节：正文在子节里；看结构用 toc 模式，看整支不要传 node）`
+      }
+      return { text: out, code: 0 }
+    }
+    const out = render_subtree(nodes, tid)
+    if (maxlen && out.length > maxlen) {
+      return {
+        text:
+          `渲染超上限: ${out.length} 字符 > ${maxlen}。` +
+          `建议只读单节点或指定小节 tid；如确实需要整支，maxlen 传 0 强制全量。`,
+        code: 2,
+      }
+    }
+    return { text: out, code: 0 }
+  } catch (e) {
+    if (e instanceof TransclusionError) return { text: `错误: ${e.message}`, code: 2 }
+    return { text: e && e.message ? e.message : String(e), code: 2 }
+  }
+}
+
+/** 检索 */
+export function cmdSearch(nodes, query, opts = {}) {
+  const result = search(nodes, query, opts)
+  return { result, text: formatSearch(query, result), code: result.hits.length ? 0 : 1 }
+}
+
+/** 自检 */
+export function cmdDiag(nodes, { problems = [], strict = false, libRoot } = {}) {
+  return diag(nodes, { problems, strict, libRoot })
+}
+
+/** 导出整库为渲染 md 树（一个一级节点一个文件） */
+export function cmdDump(nodes, outDir, fs, path) {
+  const written = []
+  for (const tid of lib_root_tids(nodes)) {
+    const text = render_subtree(nodes, tid)
+    const p = path.join(outDir, `${tid}.md`)
+    fs.mkdirSync(outDir, { recursive: true })
+    fs.writeFileSync(p, text, 'utf8')
+    written.push(p)
+  }
+  return { written, code: 0 }
+}

package/lib/engine/diag.js

@@ -0,0 +1,220 @@
+/**
+ * diag —— 结构自检。
+ *
+ * errors  = 真损坏（悬空/位置型引用、循环、孤儿、树环、重复 TID），退出码 2。
+ * warnings = 疑似漂移（跨节点重复块 / 节点内重复行），默认只报；strict 时算失败。
+ *
+ * 逐行对齐 Python 版 commands.cmd_diag（含 _is_boilerplate 的全部豁免规则）。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { extract_refs } from './parse.js'
+import { render_node, TransclusionError } from './render.js'
+
+const POSITIONAL_SEG = /^\d+(\.\d+)*$/
+const DUP_MIN_LEN = 40 // 视为漂移候选的文本块最短长度
+const DUP_NAV_ALNUM = 24 // 去掉链接/URL 后实义字符少于此值 → 导航/出处样板
+const IGNORE_FILE = 'diag_ignore.json'
+const URL_RE = /https?:\/\/\S+/g
+const MD_LINK_RE = /\[([^\]]*)\]\([^)]*\)/g
+const REF_RE = /\[\[[^\]]*\]\]/g
+const ALNUM_RE = /[\p{L}\p{N}_]/gu
+const BULLET_RE = /^(?:[-*+]\s+|\d+[.)]\s+)/
+
+/** 从节点 source 反查库根（.nodekb 目录），用于读本地豁免文件 */
+export function libRootOf(nodes) {
+  for (const n of nodes.values()) {
+    const src = String(n.source || '').split('#')[0]
+    if (!src) continue
+    let dir = path.dirname(path.resolve(src))
+    for (;;) {
+      if (path.basename(dir) === '.nodekb') return dir
+      const up = path.dirname(dir)
+      if (up === dir) break
+      dir = up
+    }
+  }
+  return null
+}
+
+function compileRules(items) {
+  const out = []
+  for (const item of items || []) {
+    try {
+      out.push(new RegExp(String(item)))
+    } catch {
+      /* 非法正则跳过 */
+    }
+  }
+  return out
+}
+
+/** 读库根的 diag_ignore.json：{"blocks": [...], "lines": [...]}，两项都是正则列表 */
+function loadIgnore(libRoot) {
+  if (!libRoot) return { blocks: [], lines: [] }
+  const p = path.join(libRoot, IGNORE_FILE)
+  let data
+  try {
+    if (!fs.statSync(p).isFile()) return { blocks: [], lines: [] }
+    data = JSON.parse(fs.readFileSync(p, 'utf8'))
+  } catch {
+    return { blocks: [], lines: [] }
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return { blocks: [], lines: [] }
+  return { blocks: compileRules(data.blocks), lines: compileRules(data.lines) }
+}
+
+function norm(blk) {
+  return blk.split(/\s+/).filter(Boolean).join(' ')
+}
+
+/**
+ * 样板判定：导航/出处注记、纯链接、URL、HTML 碎片、参数块。
+ * 这些块跨页面「重复」是设计使然，一旦上报健康检查就长期变红、随后被无视。
+ */
+export function isBoilerplate(blk) {
+  const s = String(blk).trim()
+  if (!s) return true
+  const lines = s.split('\n').map((ln) => ln.trim()).filter(Boolean)
+  const body = lines.filter((ln) => !ln.startsWith('>'))
+  if (!body.length) return true // 整块都是引用注记
+  const core = body
+  const first = core[0].replace(/^[*_> ]+/, '')
+  if (first.startsWith('<')) return true // HTML 碎片
+  if (new RegExp(`^(?:${URL_RE.source})$`).test(first)) return true // 裸 URL 行
+  const joined = core.join('\n')
+  // 导航块里链接文本本身就是文件名，不能算「内容」：整段链接先剔除再计实义字符
+  const stripped = joined.replace(URL_RE, '').replace(MD_LINK_RE, '').replace(REF_RE, '')
+  if ((stripped.match(ALNUM_RE) || []).length < DUP_NAV_ALNUM) return true
+  if (core.every((ln) => BULLET_RE.test(ln) || ln.startsWith('|')) && !/[。，]/.test(joined)) {
+    return true // 整块都是列表项/表格行且无叙述句（参数块）
+  }
+  return false
+}
+
+/** 内容漂移：物理重复的文本块（同一段文字出现在 2+ 节点，且不是转译引用 / 样板） */
+export function dupBlocks(nodes, ignore = []) {
+  const byBlock = new Map()
+  for (const n of nodes.values()) {
+    for (const blk of String(n.content).split(/\n\s*\n/)) {
+      const b = norm(blk)
+      if (b.length < DUP_MIN_LEN || isBoilerplate(blk)) continue
+      if (ignore.some((rx) => rx.test(b))) continue
+      const list = byBlock.get(b) || []
+      list.push(n.tid)
+      byBlock.set(b, list)
+    }
+  }
+  const out = []
+  for (const [b, tids] of byBlock) {
+    const uniq = [...new Set(tids)].sort()
+    if (uniq.length >= 2) {
+      // 跨节点漂移；单节点内部重复不报
+      out.push(`内容重复（可能漂移）: ${uniq.join(', ')} 共有块「${b.slice(0, 60)}${b.length > 60 ? '…' : ''}」`)
+    }
+  }
+  return out.slice(0, 20)
+}
+
+/** 节点内重复行：同一节点里 ≥40 字符的正文行出现 2+ 次 */
+export function intraDupLines(nodes, ignore = []) {
+  const out = []
+  for (const n of nodes.values()) {
+    const counts = new Map()
+    let fenced = false
+    for (const line of String(n.content).split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/)) {
+      const s = line.trim()
+      if (s.startsWith('```')) {
+        fenced = !fenced
+        continue
+      }
+      if (fenced || s.startsWith('|') || !s) continue
+      if (s.length >= 40 && /[a-zA-Z0-9\u4e00-\u9fff]/.test(s)) {
+        if (isBoilerplate(s) || ignore.some((rx) => rx.test(s))) continue
+        counts.set(s, (counts.get(s) || 0) + 1)
+      }
+    }
+    for (const [s, c] of counts) {
+      if (c >= 2) {
+        out.push(`节点内重复行: ${n.tid} 出现 ${c} 次「${s.slice(0, 60)}${s.length > 60 ? '…' : ''}」`)
+        break // 每节点只报 1 条，避免刷屏
+      }
+    }
+  }
+  return out.slice(0, 20)
+}
+
+function detectTreeCycles(nodes, problems) {
+  for (const tid of nodes.keys()) {
+    let cur = tid
+    const seen = []
+    const seenSet = new Set()
+    while (cur != null && nodes.has(cur)) {
+      if (seenSet.has(cur)) {
+        problems.push(`树环: ${[...seen, cur].join(' -> ')}`)
+        break
+      }
+      seenSet.add(cur)
+      seen.push(cur)
+      cur = nodes.get(cur).parent_tid
+    }
+  }
+}
+
+function typeCounts(nodes) {
+  const counts = new Map()
+  for (const n of nodes.values()) counts.set(n.type, (counts.get(n.type) || 0) + 1)
+  return Object.fromEntries([...counts.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)))
+}
+
+/**
+ * 自检。
+ * @returns {{report:object, code:number}}
+ */
+export function diag(nodes, { problems = [], strict = false, libRoot } = {}) {
+  const errors = [...problems]
+
+  for (const node of nodes.values()) {
+    for (const refTid of extract_refs(node.content)) {
+      if (!nodes.has(refTid)) {
+        errors.push(`悬空引用: ${node.tid} → [[${refTid}]]`)
+      } else {
+        const segs = refTid.split(':')
+        if (segs.length >= 3 && POSITIONAL_SEG.test(segs[segs.length - 1])) {
+          // 位置型段落 TID（文件:序号）：插章节就漂移，禁止作为引用目标
+          errors.push(`位置型 TID 引用（插章节会漂移）: ${node.tid} → [[${refTid}]]`)
+        }
+      }
+    }
+  }
+  for (const tid of nodes.keys()) {
+    try {
+      render_node(nodes, tid)
+    } catch (e) {
+      if (e instanceof TransclusionError) errors.push(`循环引用 @${tid}: ${e.message}`)
+      else throw e
+    }
+  }
+  for (const node of nodes.values()) {
+    if (node.parent_tid != null && !nodes.has(node.parent_tid)) {
+      errors.push(`孤儿节点: ${node.tid} (父 ${node.parent_tid} 不存在)`)
+    }
+  }
+  detectTreeCycles(nodes, errors)
+
+  const root = libRoot || libRootOf(nodes)
+  const ignore = loadIgnore(root)
+  const warnings = [...dupBlocks(nodes, ignore.blocks), ...intraDupLines(nodes, ignore.lines)]
+
+  const code = errors.length || (strict && warnings.length) ? 2 : 0
+  const report = {
+    exit_code: code,
+    errors,
+    warnings,
+    node_count: nodes.size,
+    types: typeCounts(nodes),
+  }
+  if (!errors.length && !warnings.length) report.status = 'ok'
+  return { report, code }
+}

package/lib/engine/mdlib.js

@@ -0,0 +1,283 @@
+/**
+ * mdlib —— md 即库的解析层（零持久化状态）。
+ *
+ * 移植自 nodekb/kb/mdlib.py，模型完全一致：
+ * - 文件夹 → 节点（type=文件夹名，parent=父文件夹）
+ * - md 文件 → 文件节点（tid=`{文件夹tid}:{文件名}`，parent=所在文件夹）
+ * - `<node name="X" parent="Y" type="Z">文本</node>` 显式节点：
+ *   parent 缺省 = 文件内第一个 <node> 段的 name（文件根），否则文件节点
+ *   type 缺省 = 所在文件夹名
+ * - 非节点文本按最近 `##` H2 拆分为隐式节点：tid=`{文件tid}:{章节号}`，positional=true
+ *
+ * 所有文本皆节点；content 为原文（含 `[[TID]]` 引用），渲染层展开。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { slugify } from './parse.js'
+
+const H1_RE = /^#\s+(.*)$/
+const H2_RE = /^##\s+(.*)$/
+const ATTR_RE = /(\w+)="([^"]*)"/g
+const NUM_HEAD = /^\d+(\.\d+)*$/
+
+export const ROOT_TID = 'root'
+
+/** Python str.splitlines 的等价实现（末尾换行不产生空行） */
+export function splitLines(text) {
+  if (text === '') return []
+  const parts = text.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/)
+  if (parts.length && parts[parts.length - 1] === '') parts.pop()
+  return parts
+}
+
+/** 段级 TID：标题首 token 为数字编号时用编号，否则用序号 */
+export function section_tid(file_tid, title, idx) {
+  const first = title ? (title.trim().split(/\s+/)[0] || '').replace(/[。：:]+$/, '') : ''
+  if (NUM_HEAD.test(first)) return `${file_tid}:${first}`
+  return `${file_tid}:${idx}`
+}
+
+function newNode(tid, title, type, parent, sort, source, content, kind) {
+  return {
+    tid,
+    title,
+    type,
+    parent_tid: parent,
+    sort,
+    content: content === undefined ? [] : content,
+    source,
+    kind: kind || 'node',
+  }
+}
+
+function toPosix(p) {
+  return String(p).replace(/\\/g, '/')
+}
+
+/**
+ * 解析单个 md 文件为节点列表（文件节点 + 隐式 H2 段 + 显式 <node>，按物理行序）。
+ */
+export function parse_file(absPath, file_tid, folder_type, parent_tid) {
+  const text = fs.readFileSync(absPath, 'utf8').replace(/^\uFEFF+/, '')
+  const lines = splitLines(text)
+  const rel = toPosix(absPath)
+
+  // 1) 先找 H1（围栏内的 # 不算标题）：它决定文件节点的 title，且整行不进任何节点正文
+  let h1 = null
+  let h1_line = 0
+  let fenced = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line.trim().startsWith('```')) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    const m = H1_RE.exec(line)
+    if (m) {
+      h1 = m[1].trim()
+      h1_line = i + 1
+      break
+    }
+  }
+
+  const nodes = []
+  const file_node = newNode(
+    file_tid,
+    h1 || path.basename(absPath, path.extname(absPath)),
+    folder_type,
+    parent_tid,
+    0,
+    `${rel}#L1-L${lines.length}`,
+    [],
+    'file',
+  )
+  nodes.push(file_node)
+
+  let first_node_tid = null // 文件根（第一个 <node> 的 name）
+  let sec_node = null
+  let sec_index = 0
+  const stack = [] // 显式 <node> 嵌套栈
+  fenced = false // ``` 围栏内一律视为原文，不做任何标记解析
+
+  const default_parent = () => (first_node_tid ? first_node_tid : file_tid)
+  // 内容落到哪：最内层 <node> 栈 → 当前 H2 段 → 文件节点
+  const content_target = () => (stack.length ? stack[stack.length - 1] : sec_node || file_node)
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineno = i + 1
+    const line = lines[i]
+    if (lineno === h1_line) continue
+    if (line.trim().startsWith('```')) {
+      fenced = !fenced
+      content_target().content.push(line)
+      continue
+    }
+    if (fenced) {
+      content_target().content.push(line)
+      continue
+    }
+    if (stack.length) {
+      if (line.trim() === '</node>') {
+        stack.pop()
+        continue
+      }
+      // 内层 <node>（须单行闭合；只认行首，正文里提到 <node> 不算）
+      if (line.replace(/^\s+/, '').startsWith('<node')) {
+        const attrs = Object.fromEntries([...line.matchAll(ATTR_RE)].map((m) => [m[1], m[2]]))
+        const name = (attrs.name || '').trim()
+        if (name) {
+          const n = newNode(
+            name,
+            name,
+            (attrs.type || '').trim() || folder_type,
+            (attrs.parent || '').trim() || default_parent(),
+            lineno,
+            `${rel}#L${lineno}`,
+          )
+          nodes.push(n)
+          const gt = line.indexOf('>')
+          const rest = gt >= 0 ? line.slice(gt + 1) : ''
+          if (rest.includes('</node>')) {
+            n.content.push(rest.split('</node>')[0])
+            const after = rest.split('</node>').slice(1).join('</node>')
+            if (after) stack[stack.length - 1].content.push(after)
+          }
+        }
+        continue
+      }
+      stack[stack.length - 1].content.push(line)
+      continue
+    }
+    if (line.replace(/^\s+/, '').startsWith('<node')) {
+      const attrs = Object.fromEntries([...line.matchAll(ATTR_RE)].map((m) => [m[1], m[2]]))
+      const name = (attrs.name || '').trim()
+      if (name) {
+        const parent = (attrs.parent || '').trim() || default_parent()
+        const ptype = (attrs.type || '').trim() || folder_type
+        const n = newNode(name, name, ptype, parent, lineno, `${rel}#L${lineno}`)
+        nodes.push(n)
+        if (first_node_tid === null) first_node_tid = name
+        const gt = line.indexOf('>')
+        const rest = gt >= 0 ? line.slice(gt + 1) : ''
+        if (rest.includes('</node>')) {
+          // 单行 <node>…文本…</node>
+          n.content.push(rest.split('</node>')[0])
+        } else {
+          stack.push(n)
+        }
+      }
+      continue
+    }
+    const m2 = H2_RE.exec(line)
+    if (m2) {
+      sec_index += 1
+      const title = m2[1].trim() || '(unnamed)'
+      const tid = section_tid(file_tid, title, sec_index)
+      sec_node = newNode(tid, title, folder_type, default_parent(), lineno, `${rel}#L${lineno}`, [], 'section')
+      sec_node.positional = true // 位置型段落 TID：插章节就漂移，不可作引用/检索句柄
+      nodes.push(sec_node)
+      continue
+    }
+    ;(sec_node || file_node).content.push(line)
+  }
+
+  for (const n of nodes) n.content = n.content.join('\n').trim()
+  return nodes
+}
+
+function folder_tid(rel_parts) {
+  if (!rel_parts.length) return ROOT_TID
+  return rel_parts.map(slugify).join(':')
+}
+
+/**
+ * 解析 `.nodekb/` 库为节点映射（Map，保持插入顺序 = 物理顺序）。
+ *
+ * problems 传数组时：重复 TID 降级为「跳过冲突项 + 记录问题」，其余照读；
+ * 不传时重复 TID 直接抛错（fail-fast）。
+ */
+export function parse_library(lib_dir, problems) {
+  const root = path.resolve(lib_dir)
+  let st
+  try {
+    st = fs.statSync(root)
+  } catch {
+    throw new Error(`库目录不存在: ${lib_dir}`)
+  }
+  if (!st.isDirectory()) throw new Error(`库目录不存在: ${lib_dir}`)
+
+  const nodes = new Map()
+  nodes.set(
+    ROOT_TID,
+    newNode(ROOT_TID, '.nodekb', 'root', null, 0, '', '', 'folder'),
+  )
+
+  const duplicate = (tid, what) => {
+    if (!Array.isArray(problems)) throw new Error(`重复 TID: ${tid}（${what} 与现有节点冲突）`)
+    problems.push(`重复 TID: ${tid}（${what} 冲突，已跳过）`)
+  }
+
+  const walk = (dir, rel_parts) => {
+    const ftid = folder_tid(rel_parts)
+    const ftype = rel_parts.length ? slugify(rel_parts[rel_parts.length - 1]) : 'root'
+    const ptid = folder_tid(rel_parts.slice(0, -1))
+
+    let skipFiles = false
+    if (ftid !== ROOT_TID) {
+      if (nodes.has(ftid)) {
+        duplicate(ftid, `文件夹 ${dir}`)
+        skipFiles = true // 与 Python 一致：本层文件跳过，子目录照走
+      } else {
+        nodes.set(
+          ftid,
+          newNode(ftid, rel_parts[rel_parts.length - 1], ftype, ptid, rel_parts.length, '', '', 'folder'),
+        )
+      }
+    }
+
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    // 跳过 .git 等点目录，避免污染节点树
+    const dirs = entries
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .map((e) => e.name)
+      .sort()
+    const files = entries
+      .filter((e) => e.isFile())
+      .map((e) => e.name)
+      .sort()
+
+    for (const name of skipFiles ? [] : files) {
+      if (!name.endsWith('.md')) continue
+      const md = path.join(dir, name)
+      const stem = slugify(path.basename(name, path.extname(name)))
+      const fileTid = ftid !== ROOT_TID ? `${ftid}:${stem}` : stem
+      for (const node of parse_file(md, fileTid, ftype, ftid)) {
+        if (nodes.has(node.tid)) {
+          duplicate(node.tid, name)
+          continue
+        }
+        nodes.set(node.tid, node)
+      }
+    }
+
+    for (const name of dirs) walk(path.join(dir, name), [...rel_parts, name])
+  }
+
+  walk(root, [])
+  return nodes
+}
+
+/** 一级节点列表（parent 为 null），按 sort 排序 */
+export function lib_root_tids(nodes) {
+  return [...nodes.values()]
+    .filter((n) => n.parent_tid === null)
+    .sort((a, b) => a.sort - b.sort)
+    .map((n) => n.tid)
+}

package/lib/engine/parse.js

@@ -0,0 +1,67 @@
+/**
+ * parse —— TID 语法层：`<tscl id="TID">` 定义、`[[TID]]` 引用、slug 归一化。
+ *
+ * 与 Python 版 nodekb/kb/parse.py 一一对应（本文件是移植，语义必须保持一致）：
+ * - TID 合法性：小写字母/数字/CJK 开头，仅含 a-z0-9 CJK : . _ -
+ * - 类型名：小写字母/数字/CJK 开头，仅含 a-z0-9 CJK _ -（不含冒号，避免与 TID 分隔符混淆）
+ * - slugify：小写 → 非 [字母数字._-] 转 '-' → 压缩连续 '-' → 去两端 -_
+ */
+
+const CJK = '\\u4e00-\\u9fff'
+
+// 引用：[[TID]]（允许 CJK，便于中文文件名/标题直接进入 TID）
+export const REF_SOURCE = '\\[\\[([a-zA-Z0-9\\u4e00-\\u9fff:._-]+)\\]\\]'
+
+const TSCL_SOURCE = '<tscl id="([^"]+)">([\\s\\S]*?)<\\/tscl>'
+const TID_RE = new RegExp(`^[a-z0-9${CJK}][a-z0-9${CJK}:._-]*$`)
+const TYPE_RE = new RegExp(`^[a-z0-9${CJK}][a-z0-9${CJK}_-]*$`)
+
+/** 新的 [[...]] 正则实例（global 正则有 lastIndex 状态，绝不共享） */
+export function refRegex() {
+  return new RegExp(REF_SOURCE, 'g')
+}
+
+export function is_valid_tid(tid) {
+  return TID_RE.test(String(tid))
+}
+
+export function is_valid_type(type) {
+  return TYPE_RE.test(String(type))
+}
+
+/** 文件名/标题 → TID 段 */
+export function slugify(name) {
+  let s = String(name).toLowerCase()
+  // Python 的 \w 在 UNICODE 下含各语种字母数字：用 \p{L}\p{N}_ 对齐，避免把 é/ü 误伤成 '-'
+  s = s.replace(/[^\p{L}\p{N}._-]/gu, '-')
+  s = s.replace(/-+/g, '-')
+  return s.replace(/^[-_]+/, '').replace(/[-_]+$/, '')
+}
+
+/** 提取全部 <tscl> 定义 → [[tid, text]]（保序） */
+export function extract_defs(content) {
+  const out = []
+  for (const m of String(content).matchAll(new RegExp(TSCL_SOURCE, 'gs'))) {
+    out.push([m[1], m[2]])
+  }
+  return out
+}
+
+/** 提取全部 [[TID]] 引用（保序，允许重复） */
+export function extract_refs(content) {
+  const out = []
+  for (const m of String(content).matchAll(refRegex())) out.push(m[1])
+  return out
+}
+
+/** 剥离 <tscl> 标签本身，保留内部文本（渲染投影的基础变换） */
+export function strip_tags(content) {
+  return String(content).replace(new RegExp(TSCL_SOURCE, 'gs'), '$2')
+}
+
+/** 同一节点内重复定义的 tid */
+export function find_duplicate_defs(content) {
+  const seen = new Map()
+  for (const [tid] of extract_defs(content)) seen.set(tid, (seen.get(tid) || 0) + 1)
+  return [...seen.entries()].filter(([, n]) => n > 1).map(([tid]) => tid)
+}