@tnotesjs/core 0.2.0 → 0.2.2

package/utils/index.ts

@@ -0,0 +1,71 @@
+/**
+ * utils/index.ts
+ *
+ * util 统一入口
+ */
+
+export { handleError, createError } from './errorHandler'
+export { ensureDirectory } from './file'
+export { generateAnchor } from './generateAnchor'
+export { genHierarchicalSidebar } from './genHierarchicalSidebar'
+export { getChangedIds } from './getChangedIds'
+export { LogLevel, Logger, logger, createLogger } from './logger'
+export { createAddNumberToTitle, generateToc } from './markdown'
+export { parseArgs } from './parseArgs'
+export { parseReadmeCompletedNotes } from './parseReadmeCompletedNotes'
+export {
+  parseTocLine,
+  buildTocLine,
+  buildFolderTocLine,
+  parseTocToTree,
+  parseTocToMutableTree,
+  migrateLegacyNoteParents,
+  serializeTocTree,
+  buildTreeFromFlatNodes,
+  parseTocLinesToFlatNodes,
+  getSubtreeLineRange,
+  getFolderSubtreeRange,
+  getTocEntrySubtreeRange,
+  collectNoteIndexesInSubtree,
+  renameFolderLine,
+  getPreviousNoteIndexOutsideSubtree,
+  isNoteIndexInSubtree,
+  findTocLineIndex,
+  findFolderLineIndex,
+  findTocEntryLineIndex,
+  getPreviousTocNoteIndex,
+  processTocEmptyLines,
+  parseTocCompletedNotes,
+  buildSidebarFromTocTree,
+  resolveNoteFromIndex,
+  getTocLineCompleted,
+  folderTitleFromNoteDirName,
+  isTocContentLine,
+  TOC_INDENT_SPACES,
+} from './tocHelpers'
+export type {
+  ParsedTocLine,
+  TocNode,
+  TocTreeNode,
+  TocFolderNode,
+  TocNoteNode,
+  TocSidebarItem,
+  TocLineKind,
+} from './tocHelpers'
+export {
+  migrateReadmeToToc,
+  extractReadmeBodyAfterToc,
+  README_TOC_END_TAG,
+} from './migrateReadmeToToc'
+export type {
+  MigratedTocEntry,
+  MigrateReadmeToTocResult,
+} from './migrateReadmeToToc'
+export { isPortInUse, killPortProcess, waitForPort } from './portUtils'
+export {
+  parseNoteLine,
+  buildNoteLineMarkdown,
+  processEmptyLines,
+} from './readmeHelpers'
+export { runCommand } from './runCommand'
+export { validateNoteTitle } from './validators'

package/utils/logger.ts

@@ -0,0 +1,231 @@
+/**
+ * utils/logger.ts
+ *
+ * 统一的日志系统
+ */
+
+/**
+ * 日志级别枚举
+ */
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  SILENT = 4,
+}
+
+/**
+ * 日志配置接口
+ */
+interface LoggerConfig {
+  level?: LogLevel
+  prefix?: string
+  timestamp?: boolean
+  colors?: boolean
+}
+
+/**
+ * 日志记录器类
+ */
+export class Logger {
+  private level: LogLevel
+  private prefix: string
+  private timestamp: boolean
+  private colors: boolean
+
+  constructor(config: LoggerConfig = {}) {
+    this.level = config.level ?? LogLevel.INFO
+    this.prefix = config.prefix ?? ''
+    this.timestamp = config.timestamp ?? false
+    this.colors = config.colors ?? true
+  }
+
+  /**
+   * 设置日志级别
+   */
+  setLevel(level: LogLevel): void {
+    this.level = level
+  }
+
+  /**
+   * 获取当前时间戳（精确到毫秒）
+   */
+  private getTimestamp(): string {
+    if (!this.timestamp) return ''
+    const now = new Date()
+    const hours = String(now.getHours()).padStart(2, '0')
+    const minutes = String(now.getMinutes()).padStart(2, '0')
+    const seconds = String(now.getSeconds()).padStart(2, '0')
+    const milliseconds = String(now.getMilliseconds()).padStart(3, '0')
+    return `[${hours}:${minutes}:${seconds}.${milliseconds}] `
+  }
+
+  /**
+   * 格式化日志消息
+   */
+  private formatMessage(message: string): string {
+    const timestamp = this.getTimestamp()
+    const prefix = this.prefix ? `[${this.prefix}] ` : ''
+    return `${timestamp}${prefix}${message}`
+  }
+
+  /**
+   * DEBUG 级别日志
+   */
+  debug(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.DEBUG) {
+      console.log(`🐛 ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * INFO 级别日志
+   */
+  info(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`ℹ️  ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 成功日志（特殊的 INFO 级别）
+   */
+  success(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`✅ ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 警告日志
+   */
+  warn(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.WARN) {
+      console.warn(`⚠️  ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 错误日志
+   */
+  error(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.ERROR) {
+      console.error(`❌ ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 进度日志
+   */
+  progress(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`⏳ ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 启动日志
+   */
+  start(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`🚀 ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 停止日志
+   */
+  stop(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`🛑 ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 完成日志
+   */
+  done(message: string, duration?: number, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      const durationStr = duration ? ` (${duration}ms)` : ''
+      console.log(`✨ ${this.formatMessage(message)}${durationStr}`, ...args)
+    }
+  }
+
+  /**
+   * 链接日志
+   */
+  link(message: string, url: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`🔗 ${this.formatMessage(message)} ${url}`, ...args)
+    }
+  }
+
+  /**
+   * 文件操作日志
+   */
+  file(action: string, path: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`📄 ${this.formatMessage(`${action}: ${path}`)}`, ...args)
+    }
+  }
+
+  /**
+   * Git 操作日志
+   */
+  git(message: string, ...args: any[]): void {
+    if (this.level <= LogLevel.INFO) {
+      console.log(`📦 ${this.formatMessage(message)}`, ...args)
+    }
+  }
+
+  /**
+   * 创建子 Logger
+   */
+  child(prefix: string): Logger {
+    return new Logger({
+      level: this.level,
+      prefix: this.prefix ? `${this.prefix}:${prefix}` : prefix,
+      timestamp: this.timestamp,
+      colors: this.colors,
+    })
+  }
+
+  /**
+   * 执行函数并记录耗时
+   */
+  async time<T>(label: string, fn: () => Promise<T>): Promise<T> {
+    this.progress(`${label}...`)
+    const startTime = Date.now()
+
+    try {
+      const result = await fn()
+      const duration = Date.now() - startTime
+      this.done(label, duration)
+      return result
+    } catch (error) {
+      const duration = Date.now() - startTime
+      this.error(`${label} failed after ${duration}ms`)
+      throw error
+    }
+  }
+}
+
+/**
+ * 默认 Logger 实例
+ */
+export const logger = new Logger({
+  level: process.env.DEBUG ? LogLevel.DEBUG : LogLevel.INFO,
+  timestamp: true, // 启用时间戳（精确到毫秒）
+  colors: true,
+})
+
+/**
+ * 创建带前缀的 Logger
+ */
+export function createLogger(prefix: string, config?: LoggerConfig): Logger {
+  return new Logger({
+    ...config,
+    prefix,
+  })
+}

package/utils/markdown.ts

@@ -0,0 +1,75 @@
+/**
+ * utils/markdown.ts
+ *
+ * Markdown 处理工具函数
+ */
+
+import { generateAnchor } from './generateAnchor'
+
+/**
+ * 工厂函数，创建一个带有独立编号状态的标题编号生成器
+ * @returns 返回 addNumberToTitle 方法
+ */
+export function createAddNumberToTitle() {
+  const titleNumbers = Array(7).fill(0) // 用于存储每个级别的编号
+
+  /**
+   * 为标题添加编号
+   * @param title - 原始标题
+   * @returns [新标题, 纯文本标题]
+   */
+  return function addNumberToTitle(title: string): [string, string] {
+    // 正则匹配提取标题信息
+    const match = title.match(
+      /^(#+)\s*((\d+(\.\d*)?(\.\d*)?(\.\d*)?(\.\d*)?(\.\d*)?)\.\s*)?(.*)/,
+    )
+    const plainTitle = match ? match[9].trim() : title.trim()
+
+    const level = title.indexOf(' ')
+    const baseLevel = 2 // 基础级别为2
+
+    // 一级标题不编号
+    if (level === 1) return [title, plainTitle]
+
+    // 重置当前级别以上的编号
+    for (let i = level + 1; i < titleNumbers.length; i++) titleNumbers[i] = 0
+
+    // 增加当前级别的编号
+    titleNumbers[level] += 1
+
+    // 生成新的编号
+    const newNumber = titleNumbers.slice(baseLevel, level + 1).join('.')
+
+    // 构建新的标题
+    const headerSymbol = title.slice(0, level).trim() // 获取原有的 # 符号
+    const newTitle = `${headerSymbol} ${newNumber}. ${plainTitle}`
+
+    return [newTitle, plainTitle]
+  }
+}
+
+/**
+ * 生成 Markdown TOC（目录）
+ * @param titles - 标题列表
+ * @param baseLevel - 基础层级（默认为 2）
+ * @param eol - 换行符（默认为 '\n'）
+ * @returns 生成的 TOC 字符串
+ */
+export function generateToc(
+  titles: string[],
+  baseLevel = 2,
+  eol = '\n',
+): string {
+  const toc = titles
+    .map((title) => {
+      const level = title.indexOf(' ')
+      const text = title.slice(level).trim()
+      const anchor = generateAnchor(text)
+      const indent = Math.max(0, (level - baseLevel) * 2)
+      return ' '.repeat(indent) + `- [${text}](#${anchor})`
+    })
+    .join(eol)
+
+  // !在 TOC 区域前后添加换行符 - 适配 prettier 格式化
+  return `${eol}${toc}${eol}`
+}

package/utils/migrateReadmeToToc.test.ts

@@ -0,0 +1,111 @@
+/**
+ * utils/migrateReadmeToToc.test.ts
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import {
+  extractReadmeBodyAfterToc,
+  migrateReadmeToToc,
+  README_TOC_END_TAG,
+} from './migrateReadmeToToc'
+
+const TOC_REGION = `<!-- region:toc -->
+
+- [1. Alpha](#1-alpha)
+
+${README_TOC_END_TAG}`
+
+describe('extractReadmeBodyAfterToc', () => {
+  it('returns lines after endregion:toc', () => {
+    const content = `${TOC_REGION}\n\n## 1. Alpha\n- [x] [0001. A](url)`
+    const lines = extractReadmeBodyAfterToc(content)
+    expect(lines.some((l) => l.includes('## 1. Alpha'))).toBe(true)
+    expect(lines.some((l) => l.includes('#1-alpha'))).toBe(false)
+  })
+
+  it('throws when endregion:toc is missing', () => {
+    expect(() => extractReadmeBodyAfterToc('# no toc')).toThrow(
+      README_TOC_END_TAG,
+    )
+  })
+})
+
+describe('migrateReadmeToToc', () => {
+  it('outputs folder + nested notes for heading sections', () => {
+    const content = `${TOC_REGION}
+
+## 1. One
+- [x] [0001. Alpha](https://github.com/a/b)
+- [ ] [0002. Beta](https://github.com/a/b)
+`
+    const { entries } = migrateReadmeToToc(content)
+    expect(entries).toEqual([
+      { kind: 'folder', folderTitle: '1. One', indent: 0 },
+      { kind: 'note', noteIndex: '0001', indent: 1, completed: true },
+      { kind: 'note', noteIndex: '0002', indent: 1, completed: false },
+    ])
+  })
+
+  it('handles single note section with folder', () => {
+    const content = `${TOC_REGION}
+
+## 7. Solo
+- [ ] [0036. Only](https://github.com/a/b)
+`
+    const { entries } = migrateReadmeToToc(content)
+    expect(entries).toEqual([
+      { kind: 'folder', folderTitle: '7. Solo', indent: 0 },
+      { kind: 'note', noteIndex: '0036', indent: 1, completed: false },
+    ])
+  })
+
+  it('treats ## and ### as separate groups', () => {
+    const content = `${TOC_REGION}
+
+## 1. A
+- [x] [0001. Alpha](url)
+- [ ] [0002. Beta](url)
+### 1.1 B
+- [x] [0003. Gamma](url)
+- [ ] [0004. Delta](url)
+`
+    const { entries } = migrateReadmeToToc(content)
+    expect(entries).toEqual([
+      { kind: 'folder', folderTitle: '1. A', indent: 0 },
+      { kind: 'note', noteIndex: '0001', indent: 1, completed: true },
+      { kind: 'note', noteIndex: '0002', indent: 1, completed: false },
+      { kind: 'folder', folderTitle: '1.1 B', indent: 0 },
+      { kind: 'note', noteIndex: '0003', indent: 1, completed: true },
+      { kind: 'note', noteIndex: '0004', indent: 1, completed: false },
+    ])
+  })
+
+  it('deduplicates note indexes with warnings', () => {
+    const content = `${TOC_REGION}
+
+## 1. A
+- [x] [0001. Alpha](url)
+## 2. B
+- [ ] [0001. Alpha again](url)
+`
+    const { entries, warnings } = migrateReadmeToToc(content)
+    expect(entries).toHaveLength(2)
+    expect(warnings.some((w) => w.includes('0001'))).toBe(true)
+  })
+
+  it('skips empty sections', () => {
+    const content = `${TOC_REGION}
+
+## Empty
+
+## 2. B
+- [x] [0002. Beta](url)
+`
+    const { entries } = migrateReadmeToToc(content)
+    expect(entries).toEqual([
+      { kind: 'folder', folderTitle: '2. B', indent: 0 },
+      { kind: 'note', noteIndex: '0002', indent: 1, completed: true },
+    ])
+  })
+})

package/utils/migrateReadmeToToc.ts

@@ -0,0 +1,135 @@
+/**
+ * utils/migrateReadmeToToc.ts
+ *
+ * 从 v0.1.x 根目录 README.md 解析笔记分区，生成 TOC.md 条目（init-toc 过渡命令）
+ */
+
+import { parseTocLine } from './tocHelpers'
+
+/** 与 TocGenerator 保持一致 */
+export const README_TOC_END_TAG = '<!-- endregion:toc -->'
+
+/** 迁移后的 flat TOC 条目 */
+export type MigratedTocEntry =
+  | {
+      kind: 'folder'
+      folderTitle: string
+      indent: number
+    }
+  | {
+      kind: 'note'
+      noteIndex: string
+      indent: number
+      completed: boolean
+    }
+
+/** migrateReadmeToToc 返回结果 */
+export interface MigrateReadmeToTocResult {
+  entries: MigratedTocEntry[]
+  warnings: string[]
+}
+
+interface NoteGroupItem {
+  noteIndex: string
+  completed: boolean
+}
+
+interface ReadmeSection {
+  heading: string | null
+  items: NoteGroupItem[]
+}
+
+/**
+ * 取 `<!-- endregion:toc -->` 之后的 README 正文行
+ */
+export function extractReadmeBodyAfterToc(content: string): string[] {
+  const endTagIndex = content.indexOf(README_TOC_END_TAG)
+  if (endTagIndex === -1) {
+    throw new Error(
+      `README.md 中未找到 ${README_TOC_END_TAG}，无法执行 init-toc 迁移`,
+    )
+  }
+
+  const afterTag = content.slice(endTagIndex + README_TOC_END_TAG.length)
+  return afterTag.split('\n')
+}
+
+/**
+ * 从 v0.1.x README 正文解析 TOC 条目。
+ *
+ * 规则：
+ * - 每个 #{2,} 标题独立成组，输出为 folder 行
+ * - 组内笔记统一为 folder 下 indent 1 的 note 行
+ * - 无标题组内笔记为根级 note 行
+ */
+export function migrateReadmeToToc(content: string): MigrateReadmeToTocResult {
+  const lines = extractReadmeBodyAfterToc(content)
+  const warnings: string[] = []
+  const seenIndexes = new Set<string>()
+  const sections: ReadmeSection[] = []
+  let currentHeading: string | null = null
+  let currentGroup: NoteGroupItem[] = []
+
+  const flushGroup = () => {
+    if (currentGroup.length > 0) {
+      sections.push({ heading: currentHeading, items: currentGroup })
+    }
+    currentGroup = []
+  }
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{2,})\s+(.+)$/)
+    if (headingMatch) {
+      flushGroup()
+      currentHeading = headingMatch[2].trim()
+      continue
+    }
+
+    const parsed = parseTocLine(line)
+    if (!parsed.isMatch || !parsed.noteIndex) continue
+
+    if (seenIndexes.has(parsed.noteIndex)) {
+      warnings.push(`跳过重复笔记索引: ${parsed.noteIndex}`)
+      continue
+    }
+
+    seenIndexes.add(parsed.noteIndex)
+    currentGroup.push({
+      noteIndex: parsed.noteIndex,
+      completed: parsed.completed,
+    })
+  }
+
+  flushGroup()
+
+  const entries: MigratedTocEntry[] = []
+  for (const section of sections) {
+    if (section.heading) {
+      entries.push({
+        kind: 'folder',
+        folderTitle: section.heading,
+        indent: 0,
+      })
+      for (const item of section.items) {
+        entries.push({
+          kind: 'note',
+          noteIndex: item.noteIndex,
+          indent: 1,
+          completed: item.completed,
+        })
+      }
+      continue
+    }
+
+    for (const item of section.items) {
+      entries.push({
+        kind: 'note',
+        noteIndex: item.noteIndex,
+        indent: 0,
+        completed: item.completed,
+      })
+    }
+  }
+
+  return { entries, warnings }
+}

package/utils/parseArgs.ts

@@ -0,0 +1,90 @@
+/**
+ * utils/parseArgs.ts
+ *
+ * 轻量级命令行参数解析器
+ * 替代 minimist，仅实现项目需要的功能
+ */
+
+interface ParsedArgs {
+  /** 非选项参数 */
+  _: string[]
+  /** 选项参数 */
+  [key: string]: boolean | string | string[]
+}
+
+/**
+ * 解析命令行参数
+ *
+ * 支持的格式：
+ * - `--flag`        → { flag: true }
+ * - `--key=value`   → { key: 'value' }
+ * - `--key value`   → { key: 'value' }（如果 value 不以 - 开头）
+ * - `--no-flag`     → { flag: false }
+ * - 其他参数        → 添加到 `_` 数组
+ *
+ * @param args 命令行参数数组（通常是 process.argv.slice(2)）
+ * @returns 解析后的参数对象
+ */
+export function parseArgs(args: string[]): ParsedArgs {
+  const result: ParsedArgs = { _: [] }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    // 处理 --key=value 格式
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const eqIndex = arg.indexOf('=')
+      const key = arg.slice(2, eqIndex)
+      const value = arg.slice(eqIndex + 1)
+      result[key] = value
+      continue
+    }
+
+    // 处理 --no-flag 格式（否定形式）
+    if (arg.startsWith('--no-')) {
+      const key = arg.slice(5)
+      result[key] = false
+      continue
+    }
+
+    // 处理 --flag 或 --key value 格式
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const next = args[i + 1]
+
+      // 如果下一个参数存在且不是选项，则作为值
+      if (next !== undefined && !next.startsWith('-')) {
+        // 检查是否为布尔字符串
+        if (next === 'true') {
+          result[key] = true
+          i++
+        } else if (next === 'false') {
+          result[key] = false
+          i++
+        } else {
+          // 对于这个项目，所有选项都是布尔值
+          // 所以这里保持 --flag 为 true，不消费下一个参数
+          result[key] = true
+        }
+      } else {
+        result[key] = true
+      }
+      continue
+    }
+
+    // 处理短选项 -x（目前项目未使用，但保留基础支持）
+    if (arg.startsWith('-') && arg.length > 1 && !arg.startsWith('--')) {
+      // 将 -abc 解析为 { a: true, b: true, c: true }
+      const flags = arg.slice(1)
+      for (const flag of flags) {
+        result[flag] = true
+      }
+      continue
+    }
+
+    // 非选项参数
+    result._.push(arg)
+  }
+
+  return result
+}