@tnotesjs/core 0.2.0 → 0.2.2

package/utils/parseReadmeCompletedNotes.test.ts

@@ -0,0 +1,90 @@
+/**
+ * utils/parseReadmeCompletedNotes.test.ts
+ *
+ * 测试 parseReadmeCompletedNotes 函数，确保正确解析 README 中的完成状态
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import { parseReadmeCompletedNotes } from './parseReadmeCompletedNotes'
+
+describe('parseReadmeCompletedNotes', () => {
+  const REMOTE = 'https://github.com/owner/repo/notes'
+
+  it('should count completed and total notes correctly', () => {
+    const content = [
+      `- [x] [0001. First note](${REMOTE}/0001.first-note/README) ✅`,
+      `- [ ] [0002. Second note](${REMOTE}/0002.second-note/README) ❌`,
+      `- [x] [0003. Third note](${REMOTE}/0003.third-note/README)`,
+      `- [ ] [0004. Fourth note](${REMOTE}/0004.fourth-note/README)`,
+    ].join('\n')
+
+    const result = parseReadmeCompletedNotes(content)
+
+    expect(result.totalCount).toBe(4)
+    expect(result.completedCount).toBe(2)
+  })
+
+  it('should prioritize emoji over checkbox markers', () => {
+    const content = [
+      `- [ ] [0001. Note with x](${REMOTE}/0001.x/README) ❌`,
+      `- [x] [0002. Note with check](${REMOTE}/0002.check/README) ✅`,
+    ].join('\n')
+
+    const result = parseReadmeCompletedNotes(content)
+
+    expect(result.notes[0].completed).toBe(false)  // ❌ takes priority
+    expect(result.notes[1].completed).toBe(true)   // ✅ takes priority
+  })
+
+  it('should deduplicate identical note indexes with same status', () => {
+    const content = [
+      `- [x] [0001. First note](${REMOTE}/0001.first/README) ✅`,
+      `- [x] [0001. First note dup](${REMOTE}/0001.first/README)`,
+    ].join('\n')
+
+    const result = parseReadmeCompletedNotes(content)
+
+    expect(result.totalCount).toBe(1)
+  })
+
+  it('should throw when same note index has conflicting statuses', () => {
+    const content = [
+      `- [x] [0001. First note](${REMOTE}/0001.first/README) ✅`,
+      `- [ ] [0001. First note undone](${REMOTE}/0001.first/README)`,
+    ].join('\n')
+
+    expect(() => parseReadmeCompletedNotes(content)).toThrow(
+      /相同编号.*不同的完成状态/,
+    )
+  })
+
+  it('should ignore lines without note index', () => {
+    const content = [
+      '# Header',
+      '',
+      `- [x] [0001. First note](${REMOTE}/0001.first/README)`,
+      'some random text without index',
+      `- [ ] [0002. Second note](${REMOTE}/0002.second/README)`,
+    ].join('\n')
+
+    const result = parseReadmeCompletedNotes(content)
+
+    expect(result.totalCount).toBe(2)
+    expect(result.completedCount).toBe(1)
+  })
+
+  it('should handle empty content', () => {
+    const result = parseReadmeCompletedNotes('')
+
+    expect(result.totalCount).toBe(0)
+    expect(result.completedCount).toBe(0)
+  })
+
+  it('should handle content with no matching lines', () => {
+    const result = parseReadmeCompletedNotes('# Just a header\n\nSome text')
+
+    expect(result.totalCount).toBe(0)
+    expect(result.completedCount).toBe(0)
+  })
+})

package/utils/parseReadmeCompletedNotes.ts

@@ -0,0 +1,108 @@
+/**
+ * utils/parseReadmeCompletedNotes.ts
+ *
+ * 解析 README.md 中的完成笔记数量
+ */
+
+/**
+ * 笔记状态
+ */
+interface NoteStatus {
+  noteIndex: string // 笔记编号（如 "0001"）
+  completed: boolean // 是否完成
+  line: string // 原始行内容
+}
+
+/**
+ * 解析结果
+ */
+interface ParseResult {
+  completedCount: number // 完成的笔记数量
+  totalCount: number // 总笔记数量
+  notes: NoteStatus[] // 所有笔记的状态
+}
+
+/**
+ * 从 README.md 内容中解析完成笔记数量
+ *
+ * 优先级判断逻辑（从上到下，匹配一个即停止）：
+ * 1. 如果有 ❌ → 未完成
+ * 2. 如果有 ⏰ → 未完成
+ * 3. 如果有 ✅ → 完成
+ * 4. 如果以 - [ ] 开头 → 未完成
+ * 5. 如果以 - [x] 开头 → 完成
+ *
+ * @param content - README.md 的内容
+ * @returns 解析结果
+ * @throws 如果发现相同编号的笔记有不同的完成状态
+ */
+export function parseReadmeCompletedNotes(content: string): ParseResult {
+  const lines = content.split('\n')
+  const noteMap = new Map<string, NoteStatus>()
+
+  // 笔记编号正则：匹配 4 位数字（如 0001, 0002）
+  const noteIndexRegex = /\[(\d{4})\./
+
+  for (const line of lines) {
+    // 提取笔记编号
+    const match = line.match(noteIndexRegex)
+    if (!match) continue
+
+    const noteIndex = match[1]
+
+    // 判断完成状态（按优先级）
+    let completed: boolean
+
+    if (line.includes('❌')) {
+      // 优先级 1: ❌ 表示未完成
+      completed = false
+    } else if (line.includes('⏰')) {
+      // 优先级 2: ⏰ 表示未完成
+      completed = false
+    } else if (line.includes('✅')) {
+      // 优先级 3: ✅ 表示完成
+      completed = true
+    } else if (line.trim().startsWith('- [ ]')) {
+      // 优先级 4: - [ ] 表示未完成
+      completed = false
+    } else if (line.trim().startsWith('- [x]')) {
+      // 优先级 5: - [x] 表示完成
+      completed = true
+    } else {
+      // 未匹配任何规则，跳过
+      continue
+    }
+
+    // 检查是否已存在该编号的笔记
+    if (noteMap.has(noteIndex)) {
+      const existing = noteMap.get(noteIndex)!
+      if (existing.completed !== completed) {
+        throw new Error(
+          `发现相同编号 ${noteIndex} 的笔记有不同的完成状态:\n` +
+            `  第一次出现: ${existing.line}\n` +
+            `  第二次出现: ${line}`,
+        )
+      }
+      // 状态相同，跳过（去重）
+      continue
+    }
+
+    // 记录笔记状态
+    noteMap.set(noteIndex, {
+      noteIndex,
+      completed,
+      line: line.trim(),
+    })
+  }
+
+  // 统计结果
+  const notes = Array.from(noteMap.values())
+  const completedCount = notes.filter((note) => note.completed).length
+  const totalCount = notes.length
+
+  return {
+    completedCount,
+    totalCount,
+    notes,
+  }
+}

package/utils/portUtils.ts

@@ -0,0 +1,113 @@
+/**
+ * utils/portUtils.ts
+ *
+ * 端口管理工具函数
+ */
+
+import { execSync } from 'child_process'
+
+import { logger } from './logger'
+
+/**
+ * 检查端口是否被占用
+ */
+export function isPortInUse(port: number): boolean {
+  try {
+    // Windows 系统使用 netstat 命令，只检测 LISTENING 状态（忽略 TIME_WAIT）
+    if (process.platform === 'win32') {
+      const output = execSync(
+        `netstat -ano | findstr :${port} | findstr LISTENING`,
+        { encoding: 'utf-8', stdio: 'pipe' },
+      )
+      return output.trim().length > 0
+    }
+    // Unix-like 系统使用 lsof 命令
+    else {
+      const output = execSync(`lsof -i :${port}`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      })
+      return output.trim().length > 0
+    }
+  } catch (error) {
+    // 如果命令执行失败（没有找到占用），返回 false
+    return false
+  }
+}
+
+/**
+ * 获取占用端口的进程 PID
+ */
+function getPortPid(port: number): number | null {
+  try {
+    if (process.platform === 'win32') {
+      const output = execSync(`netstat -ano | findstr :${port}`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      })
+      const lines = output.trim().split('\n')
+      if (lines.length > 0) {
+        const match = lines[0].match(/\s+(\d+)\s*$/)
+        if (match) {
+          return parseInt(match[1])
+        }
+      }
+    } else {
+      const output = execSync(`lsof -t -i :${port}`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      })
+      const pid = parseInt(output.trim())
+      if (!isNaN(pid)) {
+        return pid
+      }
+    }
+  } catch (error) {
+    // 命令执行失败
+  }
+  return null
+}
+
+/**
+ * 终止占用端口的进程
+ */
+export function killPortProcess(port: number): boolean {
+  const pid = getPortPid(port)
+  if (!pid) {
+    return false
+  }
+
+  try {
+    if (process.platform === 'win32') {
+      execSync(`taskkill /F /PID ${pid}`, { stdio: 'pipe' })
+    } else {
+      execSync(`kill -9 ${pid}`, { stdio: 'pipe' })
+    }
+    logger.info(`已终止占用端口 ${port} 的进程 (PID: ${pid})`)
+    return true
+  } catch (error) {
+    logger.error(
+      `终止进程失败 (PID: ${pid}): ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    )
+    return false
+  }
+}
+
+/**
+ * 等待端口可用
+ */
+export async function waitForPort(
+  port: number,
+  timeout: number = 5000,
+): Promise<boolean> {
+  const startTime = Date.now()
+  while (Date.now() - startTime < timeout) {
+    if (!isPortInUse(port)) {
+      return true
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+  return false
+}

package/utils/readmeHelpers.ts

@@ -0,0 +1,190 @@
+/**
+ * utils/readmeHelpers.ts
+ *
+ * README 更新的公共辅助函数
+ */
+
+import { NoteManager } from '../core/NoteManager'
+
+import type { NoteInfo } from '../types'
+
+/**
+ * 笔记行匹配正则表达式
+ *
+ * 格式:
+ * - [x] [0001. 笔记标题]
+ * 或
+ *   - [x] [0001. 笔记标题] (支持缩进)
+ *
+ * 要求: 笔记名称必须是 4 个数字开头，后面紧跟着一个小数点和一个空格，随后跟着任意标题内容
+ */
+const NOTE_LINE_REGEX = /^( *)- \[.\] \[(\d{4}\. .+?)\]/
+
+/**
+ * 笔记链接解析结果
+ */
+interface ParsedNoteLine {
+  isMatch: boolean // 是否匹配到笔记行
+  noteIndex: string | null // 笔记索引 (如 "0001")
+}
+
+/**
+ * 解析 home readme 笔记链接行，提取笔记 ID
+ * @param line - 要解析的行
+ * @returns 解析结果 { isMatch, noteIndex }
+ */
+export function parseNoteLine(line: string): ParsedNoteLine {
+  // 匹配笔记链接格式: - [x] [0001. xxx](...)
+  // 或简单格式: - [ ] [0001. xxx]
+  // 支持缩进: "  - [x] [0001. xxx]"
+  const noteMatch = line.match(NOTE_LINE_REGEX)
+
+  if (!noteMatch) {
+    return {
+      isMatch: false,
+      noteIndex: null,
+    }
+  }
+
+  const [, , text] = noteMatch // 第一个捕获组是缩进，第二个是文本
+
+  // 提取笔记 ID
+  const noteIndex = NoteManager.extractNoteIndex(text)
+
+  return {
+    isMatch: true,
+    noteIndex,
+  }
+}
+
+/**
+ * 构建 home readme 笔记链接
+ * @param note - 笔记信息
+ * @param repoOwner - 仓库所有者
+ * @param repoName - 仓库名称
+ * @returns 完整的 GitHub URL
+ */
+function buildNoteLink(
+  note: NoteInfo,
+  repoOwner: string,
+  repoName: string,
+): string {
+  const encodedDirName = encodeURIComponent(note.dirName)
+  return `https://github.com/${repoOwner}/${repoName}/tree/main/notes/${encodedDirName}/README.md`
+}
+
+/**
+ * 根据笔记配置更新状态
+ * @param note - 笔记信息
+ * @returns { status, deprecatedMark } 状态字符和弃用标记
+ */
+function updateNoteStatus(note: NoteInfo): {
+  status: string
+  deprecatedMark: string
+} {
+  let status = ' ' // 默认未完成
+  const deprecatedMark = '' // 弃用标记（已废弃，保留返回值结构以免破坏 API）
+
+  if (note.config) {
+    if (note.config.done) {
+      status = 'x' // 完成的笔记，勾选复选框
+    }
+  }
+
+  return { status, deprecatedMark }
+}
+
+/**
+ * 构建完整的笔记行
+ * @param note - 笔记信息
+ * @param repoOwner - 仓库所有者
+ * @param repoName - 仓库名称
+ * @returns 完整的 Markdown 行
+ */
+export function buildNoteLineMarkdown(
+  note: NoteInfo,
+  repoOwner: string,
+  repoName: string,
+): string {
+  const url = buildNoteLink(note, repoOwner, repoName)
+  const { status, deprecatedMark } = updateNoteStatus(note)
+  return `- [${status}] [${note.dirName}](${url})${deprecatedMark}`
+}
+
+/**
+ * 检查是否是笔记列表行
+ * @param line - 要检查的行
+ * @returns 是否是笔记行
+ */
+function isNoteLine(line: string): boolean {
+  return NOTE_LINE_REGEX.test(line)
+}
+
+/**
+ * 合并 home readme 连续空行
+ * @param lines - 原始行数组
+ * @returns 合并后的行数组
+ */
+function mergeConsecutiveEmptyLines(lines: string[]): string[] {
+  const result: string[] = []
+  let previousLineIsEmpty = false
+
+  for (const line of lines) {
+    const isCurrentLineEmpty = line === ''
+
+    if (isCurrentLineEmpty) {
+      // 只有前一行不是空行时才保留当前空行
+      if (!previousLineIsEmpty) {
+        result.push(line)
+        previousLineIsEmpty = true
+      }
+    } else {
+      result.push(line)
+      previousLineIsEmpty = false
+    }
+  }
+
+  return result
+}
+
+/**
+ * 移除相邻 home readme 笔记之间的空行
+ * @param lines - 行数组
+ * @returns 处理后的行数组
+ */
+function removeEmptyLinesBetweenNotes(lines: string[]): string[] {
+  const result: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const currentLine = lines[i]
+    const prevLine = i > 0 ? lines[i - 1] : null
+    const nextLine = i < lines.length - 1 ? lines[i + 1] : null
+
+    // 如果当前行是空行,且前后都是笔记,则跳过这个空行
+    if (currentLine === '' && prevLine && nextLine) {
+      const isPrevLineNote = isNoteLine(prevLine)
+      const isNextLineNote = isNoteLine(nextLine)
+
+      if (isPrevLineNote && isNextLineNote) {
+        continue // 跳过笔记之间的空行
+      }
+    }
+
+    result.push(currentLine)
+  }
+
+  return result
+}
+
+/**
+ * 处理 README 中的空行
+ * 1. 合并连续空行
+ * 2. 移除相邻笔记之间的空行
+ * @param lines - 原始行数组
+ * @returns 处理后的行数组
+ */
+export function processEmptyLines(lines: string[]): string[] {
+  const stepOne = mergeConsecutiveEmptyLines(lines)
+  const stepTwo = removeEmptyLinesBetweenNotes(stepOne)
+  return stepTwo
+}

package/utils/runCommand.ts

@@ -0,0 +1,29 @@
+/**
+ * utils/runCommand.ts
+ *
+ * 运行命令的工具函数
+ */
+
+import { exec } from 'child_process'
+
+/**
+ * 使用 exec 执行命令
+ * @param command - 要执行的命令
+ * @param dir - 执行目录
+ * @returns Promise<string> 命令输出
+ */
+export async function runCommand(
+  command: string,
+  dir: string
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    exec(command, { cwd: dir }, (error, stdout, stderr) => {
+      if (error) {
+        console.error(`处理 ${dir} 时出错：${stderr}`)
+        reject(error)
+      } else {
+        resolve(stdout.trim())
+      }
+    })
+  })
+}