@tnotesjs/core 0.1.28 → 0.2.0

package/vitepress/components/sidebarTreeHelpers.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  buildSidebarTree,
+  collectParentKeys,
+  formatTreeNodeName,
+} from './sidebarTreeHelpers'
+
+const sampleSidebar = [
+  {
+    text: '✅ 0001. Root note',
+    link: '/notes/0001/README',
+    items: [
+      {
+        text: '⏰ 0002. Child note',
+        link: '/notes/0002/README',
+      },
+    ],
+  },
+]
+
+const mixedNestingSidebar = [
+  {
+    text: 'TNotes 简介',
+    items: [
+      {
+        text: '✅ 0001. TNotes 简介',
+        link: '/notes/0001. TNotes 简介/README',
+      },
+    ],
+  },
+  {
+    text: '✅ 0019. 关于作者 Tdahuyou',
+    link: '/notes/0019. 关于作者 Tdahuyou/README',
+    items: [{ text: '⏰ 0039. new', link: '/notes/0039. new/README' }],
+  },
+  { text: '⏰ 0039. new', link: '/notes/0039. new/README' },
+]
+
+/** introduction TOC 片段：note → folder → note 混嵌 */
+const noteFolderNoteSidebar = [
+  {
+    text: 'TNotes 笔记书写规范',
+    items: [
+      {
+        text: '✅ emoji 规范',
+        link: '/notes/0027. emoji 规范/README',
+        items: [
+          {
+            text: '评论功能的技术实现（Giscus）',
+            items: [
+              {
+                text: '⏰ 评论功能的技术实现（Giscus）',
+                link: '/notes/0003. 评论功能的技术实现（Giscus）/README',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+]
+
+describe('sidebarTreeHelpers', () => {
+  it('buildSidebarTree includes parent when children are filtered out', () => {
+    const tree = buildSidebarTree(sampleSidebar, {
+      showDone: true,
+      showPending: false,
+      base: '/repo',
+    })
+
+    expect(tree).toHaveLength(1)
+    expect(tree[0].text).toBe('Root note')
+    expect(tree[0].children).toHaveLength(0)
+    expect(tree[0].fullLink).toBe('/repo/notes/0001/README')
+  })
+
+  it('buildSidebarTree includes pending children when enabled', () => {
+    const tree = buildSidebarTree(sampleSidebar, {
+      showDone: true,
+      showPending: true,
+      base: '/repo',
+    })
+
+    expect(tree[0].children).toHaveLength(1)
+  })
+
+  it('formatTreeNodeName includes status emoji', () => {
+    const tree = buildSidebarTree(sampleSidebar, {
+      includeAll: true,
+      base: '/repo',
+    })
+
+    expect(formatTreeNodeName(tree[0])).toBe('✅ Root note')
+  })
+
+  it('collectParentKeys returns keys for branch nodes', () => {
+    const tree = buildSidebarTree(sampleSidebar, {
+      includeAll: true,
+      base: '/repo',
+    })
+
+    expect(collectParentKeys(tree)).toEqual(['/notes/0001/README'])
+  })
+
+  it('buildSidebarTree keeps pure folders but fullLink is null (FolderTreeItems must handle)', () => {
+    const tree = buildSidebarTree(mixedNestingSidebar, {
+      showDone: true,
+      showPending: true,
+      base: '/',
+    })
+
+    expect(tree).toHaveLength(3)
+    const pureFolder = tree[0]
+    expect(pureFolder.text).toBe('TNotes 简介')
+    expect(pureFolder.fullLink).toBeNull()
+    expect(pureFolder.children).toHaveLength(1)
+    expect(tree[1].text).toBe('关于作者 Tdahuyou')
+    expect(tree[1].fullLink).toBeTruthy()
+  })
+
+  it('buildSidebarTree preserves note → folder → note nesting (introduction 0027)', () => {
+    const tree = buildSidebarTree(noteFolderNoteSidebar, {
+      showDone: true,
+      showPending: true,
+      base: '/',
+    })
+
+    expect(tree).toHaveLength(1)
+    expect(tree[0].text).toBe('TNotes 笔记书写规范')
+    expect(tree[0].fullLink).toBeNull()
+
+    const emojiNote = tree[0].children[0]
+    expect(emojiNote.text).toBe('emoji 规范')
+    expect(emojiNote.fullLink).toBeTruthy()
+
+    const giscusFolder = emojiNote.children[0]
+    expect(giscusFolder.text).toBe('评论功能的技术实现（Giscus）')
+    expect(giscusFolder.fullLink).toBeNull()
+    expect(giscusFolder.children).toHaveLength(1)
+  })
+})

package/vitepress/components/sidebarTreeHelpers.ts

@@ -0,0 +1,168 @@
+/**
+ * vitepress/components/sidebarTreeHelpers.ts
+ *
+ * 将 sidebar 数据转换为目录树结构，供 FolderTree 等视图共用
+ */
+
+export type NoteStatus = 'done' | 'pending' | null
+
+export interface SidebarItemLike {
+  text: string
+  link?: string
+  items?: SidebarItemLike[]
+}
+
+export interface SidebarTreeNode {
+  key: string
+  text: string
+  displayText: string
+  link?: string
+  fullLink?: string | null
+  relativePath?: string
+  status: NoteStatus
+  realNumber: string
+  children: SidebarTreeNode[]
+}
+
+export interface BuildSidebarTreeOptions {
+  showPending?: boolean
+  showDone?: boolean
+  includeAll?: boolean
+  base?: string
+}
+
+export function extractRealNumberFromLink(link?: string): string {
+  if (!link) return '0000'
+  const match = link.match(/\/notes\/(\d{4})/)
+  return match ? match[1] : '0000'
+}
+
+export function extractTitleFromText(text: string): string {
+  if (!text) return ''
+  return text.replace(/^\d{4}\.?\s/, '')
+}
+
+export function parseSidebarItemText(
+  text: string,
+  showPending = true,
+  showDone = true,
+  includeAll = false,
+): { included: boolean; status: NoteStatus; cleanText: string } {
+  if (!text) {
+    return { included: false, status: null, cleanText: '' }
+  }
+  if (text.startsWith('✅')) {
+    return {
+      included: includeAll || showDone,
+      status: 'done',
+      cleanText: text.replace('✅ ', ''),
+    }
+  }
+  if (text.startsWith('⏰')) {
+    return {
+      included: includeAll || showPending,
+      status: 'pending',
+      cleanText: text.replace('⏰ ', ''),
+    }
+  }
+  return {
+    included: includeAll,
+    status: null,
+    cleanText: text,
+  }
+}
+
+function mapSidebarItemToNode(
+  item: SidebarItemLike,
+  options: BuildSidebarTreeOptions,
+): SidebarTreeNode | null {
+  const {
+    showPending = true,
+    showDone = true,
+    includeAll = false,
+    base = '',
+  } = options
+  const hasChildren = (item.items?.length ?? 0) > 0
+  const parsed = parseSidebarItemText(
+    item.text,
+    showPending,
+    showDone,
+    includeAll,
+  )
+
+  if (hasChildren) {
+    const children = (item.items ?? [])
+      .map((child) => mapSidebarItemToNode(child, options))
+      .filter((node): node is SidebarTreeNode => node !== null)
+
+    if (!parsed.included && children.length === 0) return null
+
+    const realNumber = extractRealNumberFromLink(item.link)
+    const title = extractTitleFromText(parsed.cleanText)
+
+    return {
+      key: item.link || item.text,
+      text: title,
+      displayText: parsed.cleanText,
+      link: item.link,
+      fullLink: item.link ? (base ? base + item.link : item.link) : null,
+      relativePath: item.link,
+      status: parsed.status,
+      realNumber,
+      children,
+    }
+  }
+
+  if (!item.link || !item.text || !parsed.included) return null
+
+  const realNumber = extractRealNumberFromLink(item.link)
+  const title = extractTitleFromText(parsed.cleanText)
+
+  return {
+    key: item.link,
+    text: title,
+    displayText: parsed.cleanText,
+    link: item.link,
+    fullLink: base ? base + item.link : item.link,
+    relativePath: item.link,
+    status: parsed.status,
+    realNumber,
+    children: [],
+  }
+}
+
+export function buildSidebarTree(
+  items: SidebarItemLike[],
+  options: BuildSidebarTreeOptions = {},
+): SidebarTreeNode[] {
+  if (!Array.isArray(items)) return []
+  return items
+    .map((item) => mapSidebarItemToNode(item, options))
+    .filter((node): node is SidebarTreeNode => node !== null)
+}
+
+export function collectParentKeys(
+  nodes: SidebarTreeNode[],
+  keys: string[] = [],
+): string[] {
+  for (const node of nodes) {
+    if (node.children.length > 0) {
+      keys.push(node.key)
+      collectParentKeys(node.children, keys)
+    }
+  }
+  return keys
+}
+
+export function formatTreeNodeName(
+  node: SidebarTreeNode,
+  showNumber = false,
+): string {
+  const emoji =
+    node.status === 'done' ? '✅ ' : node.status === 'pending' ? '⏰ ' : ''
+  const title =
+    showNumber && node.realNumber
+      ? `${node.realNumber}. ${node.text}`
+      : node.text
+  return `${emoji}${title}`
+}

package/vitepress/components/utils/vscodePaths.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  getRepoRootPath,
+  resolveNoteReadmePath,
+  toVscodeFileUrl,
+} from './vscodePaths'
+
+const notesDir = 'C:\\tnotesjs\\TNotes.introduction\\notes'
+
+describe('vscodePaths', () => {
+  it('getRepoRootPath resolves parent of notes directory', () => {
+    expect(getRepoRootPath(notesDir)).toBe('C:\\tnotesjs\\TNotes.introduction')
+  })
+
+  it('resolveNoteReadmePath handles sidebar link format', () => {
+    expect(resolveNoteReadmePath(notesDir, '/notes/0002. TNotes/README')).toBe(
+      'C:\\tnotesjs\\TNotes.introduction\\notes\\0002. TNotes\\README.md',
+    )
+  })
+
+  it('resolveNoteReadmePath handles vitepress page relativePath', () => {
+    expect(
+      resolveNoteReadmePath(notesDir, 'notes/0002. TNotes 公式支持/README.md'),
+    ).toBe(
+      'C:\\tnotesjs\\TNotes.introduction\\notes\\0002. TNotes 公式支持\\README.md',
+    )
+  })
+
+  it('resolveNoteReadmePath handles repo README page', () => {
+    expect(resolveNoteReadmePath(notesDir, 'README.md')).toBe(
+      'C:\\tnotesjs\\TNotes.introduction\\README.md',
+    )
+  })
+
+  it('toVscodeFileUrl encodes file path', () => {
+    expect(toVscodeFileUrl('C:\\notes\\0001\\README.md')).toContain(
+      'vscode://file/',
+    )
+  })
+})

package/vitepress/components/utils/vscodePaths.ts

@@ -0,0 +1,52 @@
+/**
+ * vitepress/components/utils/vscodePaths.ts
+ *
+ * 将站点内路径解析为本地 VS Code 可打开的文件路径。
+ * NOTES_DIR 通常配置为仓库下的 notes 目录（如 .../TNotes.introduction/notes）。
+ */
+
+export function getRepoRootPath(notesDir: string): string {
+  const normalized = notesDir.replace(/[/\\]+$/, '')
+  if (/[/\\]notes$/i.test(normalized)) {
+    return normalized.replace(/[/\\]notes$/i, '')
+  }
+  return normalized
+}
+
+export function resolveNoteReadmePath(
+  notesDir: string,
+  relativePath: string,
+): string | null {
+  if (!notesDir || !relativePath) return null
+
+  let linkPath = relativePath.replace(/^\/+/, '')
+
+  if (linkPath === 'README.md' || linkPath === 'README') {
+    const repoRoot = getRepoRootPath(notesDir)
+    const sep = repoRoot.includes('\\') ? '\\' : '/'
+    return `${repoRoot}${sep}README.md`
+  }
+
+  if (linkPath.startsWith('notes/')) {
+    linkPath = linkPath.slice('notes/'.length)
+  }
+
+  linkPath = linkPath
+    .replace(/\/README\.md$/i, '')
+    .replace(/\/README$/i, '')
+
+  const decodedFolder = linkPath
+    .split('/')
+    .map((segment) => decodeURIComponent(segment))
+    .join('/')
+
+  const base = notesDir.replace(/[/\\]+$/, '')
+  const sep = base.includes('\\') ? '\\' : '/'
+  const folderPath = decodedFolder.split('/').join(sep)
+
+  return `${base}${sep}${folderPath}${sep}README.md`
+}
+
+export function toVscodeFileUrl(filePath: string): string {
+  return `vscode://file/${encodeURI(filePath)}`
+}

package/vitepress/config/index.ts

@@ -23,6 +23,7 @@ import {
 import { buildProgressPlugin } from '../plugins/buildProgressPlugin'
 import { fileWatcherBridgePlugin } from '../plugins/fileWatcherBridgePlugin'
 import { getNoteByConfigIdPlugin } from '../plugins/getNoteByConfigIdPlugin'
+import { localSearchReindexPlugin } from '../plugins/localSearchReindexPlugin'
 import { renameNotePlugin } from '../plugins/renameNotePlugin'
 import { sidebarStructurePlugin } from '../plugins/sidebarStructurePlugin'
 import { updateConfigPlugin } from '../plugins/updateConfigPlugin'
@@ -73,6 +74,7 @@ export function defineNotesConfig(overrides: UserConfig = {}) {
         sidebarStructurePlugin() as any,
         getNoteByConfigIdPlugin() as any,
         fileWatcherBridgePlugin() as any,
+        localSearchReindexPlugin() as any,
         ...(overrideVite?.plugins || []),
       ],
       server: {

package/vitepress/plugins/localSearchIndexBuilder.ts

@@ -0,0 +1,209 @@
+/**
+ * localSearchIndexBuilder.ts
+ *
+ * dev 下全量重建 VitePress Local Search 索引（删除笔记后移除 stale 条目）
+ */
+
+import MiniSearch from 'minisearch'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {
+  createMarkdownRenderer,
+  resolvePages,
+  type SiteConfig,
+} from 'vitepress'
+
+import { getDocIdFromFile } from './localSearchReindexLogic'
+
+import type { DefaultTheme } from 'vitepress'
+
+const headingRegex =
+  /<h(\d*).*?>(.*?<a.*? href="#.*?".*?>.*?<\/a>)<\/h\1>/gi
+const headingContentRegex = /(.*?)<a.*? href="#(.*?)".*?>.*?<\/a>/i
+
+export type LocalSearchIndexSnapshot = Map<string, string>
+
+type LocalSearchConfig = DefaultTheme.LocalSearchOptions & {
+  options?: {
+    _render?: (
+      mdRaw: string,
+      env: Record<string, unknown>,
+      mdRenderer: Awaited<ReturnType<typeof createMarkdownRenderer>>,
+    ) => Promise<string>
+    miniSearch?: { options?: Record<string, unknown> }
+  }
+}
+
+export type LocalSearchIndexBuildResult = {
+  snapshot: LocalSearchIndexSnapshot
+  pageCount: number
+}
+
+function slash(value: string): string {
+  return value.replace(/\\/g, '/')
+}
+
+function clearHtmlTags(str: string): string {
+  return str.replace(/<[^>]*>/g, '')
+}
+
+function getSearchableText(content: string): string {
+  return clearHtmlTags(content)
+}
+
+function* splitPageIntoSections(html: string) {
+  const result = html.split(headingRegex)
+  result.shift()
+  let parentTitles: string[] = []
+
+  for (let i = 0; i < result.length; i += 3) {
+    const level = parseInt(result[i], 10) - 1
+    const heading = result[i + 1]
+    const headingResult = headingContentRegex.exec(heading)
+    const title = clearHtmlTags(headingResult?.[1] ?? '').trim()
+    const anchor = headingResult?.[2] ?? ''
+    const content = result[i + 2]
+    if (!title || !content) continue
+
+    let titles = parentTitles.slice(0, level)
+    titles[level] = title
+    titles = titles.filter(Boolean)
+    yield { anchor, titles, text: getSearchableText(content) }
+
+    if (level === 0) {
+      parentTitles = [title]
+    } else {
+      parentTitles[level] = title
+    }
+  }
+}
+
+function getLocaleForPath(site: SiteConfig['site'], page: string): string {
+  const normalizedPage = slash(page)
+  for (const [localePath, localeConfig] of Object.entries(site.locales ?? {})) {
+    const prefix = localePath.replace(/\\/g, '/')
+    if (prefix === 'root') continue
+    const normalizedPrefix = prefix.endsWith('/') ? prefix : `${prefix}/`
+    if (normalizedPage.startsWith(normalizedPrefix)) {
+      return localePath
+    }
+    if (localeConfig?.lang && normalizedPage === prefix.replace(/\/$/, '')) {
+      return localePath
+    }
+  }
+  return 'root'
+}
+
+export async function createLocalSearchMarkdownRenderer(
+  siteConfig: SiteConfig,
+): Promise<Awaited<ReturnType<typeof createMarkdownRenderer>>> {
+  return createMarkdownRenderer(
+    siteConfig.srcDir,
+    siteConfig.markdown,
+    siteConfig.site.base,
+    siteConfig.logger,
+  )
+}
+
+async function renderPageHtml(
+  siteConfig: SiteConfig,
+  md: Awaited<ReturnType<typeof createMarkdownRenderer>>,
+  absoluteFile: string,
+): Promise<string> {
+  if (!(await fs.stat(absoluteFile).catch(() => null))) return ''
+
+  const srcDir = siteConfig.srcDir
+  const relativePath = slash(path.relative(srcDir, absoluteFile))
+  const env = {
+    path: absoluteFile,
+    relativePath,
+    cleanUrls: siteConfig.cleanUrls ?? false,
+    frontmatter: {},
+  }
+  const options =
+    (siteConfig.site.themeConfig?.search as LocalSearchConfig | undefined)
+      ?.options ?? {}
+  const mdRaw = await fs.readFile(absoluteFile, 'utf-8')
+
+  if (options._render) {
+    return await options._render(mdRaw, env, md)
+  }
+
+  const html = md.render(mdRaw, env)
+  return (env as { frontmatter?: { search?: boolean } }).frontmatter?.search ===
+    false
+    ? ''
+    : html
+}
+
+async function indexPage(
+  siteConfig: SiteConfig,
+  md: Awaited<ReturnType<typeof createMarkdownRenderer>>,
+  page: string,
+  index: MiniSearch,
+): Promise<void> {
+  const absoluteFile = path.join(siteConfig.srcDir, page)
+  const fileId = getDocIdFromFile({
+    srcDir: siteConfig.srcDir,
+    base: siteConfig.site.base,
+    cleanUrls: siteConfig.cleanUrls ?? false,
+    rewrites: siteConfig.rewrites.map,
+    absoluteOrRelativeFile: absoluteFile,
+  })
+  const html = await renderPageHtml(siteConfig, md, absoluteFile)
+  const sections = splitPageIntoSections(html)
+
+  for (const section of sections) {
+    if (!section || !(section.text || section.titles)) break
+    const { anchor, text, titles } = section
+    const id = anchor ? [fileId, anchor].join('#') : fileId
+    if (index.has(id)) index.discard(id)
+    index.add({
+      id,
+      text,
+      title: titles[titles.length - 1]!,
+      titles: titles.slice(0, -1),
+    })
+  }
+}
+
+/**
+ * 全量重建 local search 索引快照（locale -> double-stringified MiniSearch JSON）
+ *
+ * 使用运行中 dev server 的 SiteConfig，避免二次 resolveConfig 挂死/崩溃。
+ */
+export async function buildLocalSearchIndexSnapshot(
+  siteConfig: SiteConfig,
+  md: Awaited<ReturnType<typeof createMarkdownRenderer>>,
+): Promise<LocalSearchIndexBuildResult> {
+  const { pages } = await resolvePages(
+    siteConfig.srcDir,
+    siteConfig.userConfig,
+    siteConfig.logger,
+  )
+  const options =
+    (siteConfig.site.themeConfig?.search as LocalSearchConfig | undefined)
+      ?.options ?? {}
+  const indexByLocale = new Map<string, MiniSearch>()
+
+  for (const page of pages) {
+    const locale = getLocaleForPath(siteConfig.site, page)
+    let index = indexByLocale.get(locale)
+    if (!index) {
+      index = new MiniSearch({
+        fields: ['title', 'titles', 'text'],
+        storeFields: ['title', 'titles'],
+        ...options.miniSearch?.options,
+      })
+      indexByLocale.set(locale, index)
+    }
+    await indexPage(siteConfig, md, page, index)
+  }
+
+  const snapshot: LocalSearchIndexSnapshot = new Map()
+  for (const [locale, index] of indexByLocale) {
+    snapshot.set(locale, JSON.stringify(JSON.stringify(index)))
+  }
+
+  return { snapshot, pageCount: pages.length }
+}

package/vitepress/plugins/localSearchReindex.test.ts

@@ -0,0 +1,46 @@
+/**
+ * localSearchReindex.test.ts
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import {
+  getDocIdFromFile,
+  isNoteReadmePath,
+} from './localSearchReindexLogic'
+
+describe('isNoteReadmePath', () => {
+  it('matches note readme paths', () => {
+    expect(
+      isNoteReadmePath('C:/repo/notes/0040. new/README.md'),
+    ).toBe(true)
+    expect(
+      isNoteReadmePath('notes/0040. new/README.md'),
+    ).toBe(true)
+  })
+
+  it('rejects non-note markdown files', () => {
+    expect(isNoteReadmePath('notes/0040. new/notes.md')).toBe(false)
+    expect(isNoteReadmePath('README.md')).toBe(false)
+    expect(isNoteReadmePath('TOC.md')).toBe(false)
+  })
+
+  it('respects ignore_dirs folder names', () => {
+    expect(
+      isNoteReadmePath('notes/0040. draft/README.md', ['0040. draft']),
+    ).toBe(false)
+  })
+})
+
+describe('getDocIdFromFile', () => {
+  it('builds clean url doc id with site base', () => {
+    expect(
+      getDocIdFromFile({
+        srcDir: 'C:/repo',
+        base: '/TNotes.introduction/',
+        cleanUrls: true,
+        absoluteOrRelativeFile: 'C:/repo/notes/0040. new/README.md',
+      }),
+    ).toBe('/TNotes.introduction/notes/0040. new/README')
+  })
+})