@incremark/core 0.0.1

package/src/parser/IncremarkParser.ts

@@ -0,0 +1,476 @@
+/**
+ * 增量 Markdown 解析器
+ *
+ * 设计思路：
+ * 1. 维护一个文本缓冲区，接收流式输入
+ * 2. 识别"稳定边界"（如空行、标题等），将已完成的块标记为 completed
+ * 3. 对于正在接收的块，每次重新解析，但只解析该块的内容
+ * 4. 复杂嵌套节点（如列表、引用）作为整体处理，直到确认完成
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { gfmFromMarkdown } from 'mdast-util-gfm'
+import { gfm } from 'micromark-extension-gfm'
+import type { Extension as MicromarkExtension } from 'micromark-util-types'
+import type { Extension as MdastExtension } from 'mdast-util-from-markdown'
+
+import type {
+  Root,
+  RootContent,
+  ParsedBlock,
+  IncrementalUpdate,
+  ParserOptions,
+  BlockStatus,
+  BlockContext,
+  ContainerConfig
+} from '../types'
+
+import {
+  createInitialContext,
+  updateContext,
+  isEmptyLine,
+  detectFenceStart,
+  isHeading,
+  isThematicBreak,
+  isBlockquoteStart,
+  isListItemStart,
+  detectContainer
+} from '../detector'
+
+// ============ 解析器类 ============
+
+export class IncremarkParser {
+  private buffer = ''
+  private lines: string[] = []
+  /** 行偏移量前缀和：lineOffsets[i] = 第i行起始位置的偏移量 */
+  private lineOffsets: number[] = [0]
+  private completedBlocks: ParsedBlock[] = []
+  private pendingStartLine = 0
+  private blockIdCounter = 0
+  private context: BlockContext
+  private options: ParserOptions
+  /** 缓存的容器配置，避免重复计算 */
+  private cachedContainerConfig: ContainerConfig | undefined | null = null
+  /** 上次 append 返回的 pending blocks，用于 getAst 复用 */
+  private lastPendingBlocks: ParsedBlock[] = []
+
+  constructor(options: ParserOptions = {}) {
+    this.options = {
+      gfm: true,
+      ...options
+    }
+    this.context = createInitialContext()
+    // 初始化容器配置缓存
+    this.cachedContainerConfig = this.computeContainerConfig()
+  }
+
+  private generateBlockId(): string {
+    return `block-${++this.blockIdCounter}`
+  }
+
+  private computeContainerConfig(): ContainerConfig | undefined {
+    const containers = this.options.containers
+    if (!containers) return undefined
+    return containers === true ? {} : containers
+  }
+
+  private getContainerConfig(): ContainerConfig | undefined {
+    return this.cachedContainerConfig ?? undefined
+  }
+
+  private parse(text: string): Root {
+    const extensions: MicromarkExtension[] = []
+    const mdastExtensions: MdastExtension[] = []
+
+    if (this.options.gfm) {
+      extensions.push(gfm())
+      mdastExtensions.push(...gfmFromMarkdown())
+    }
+
+    // 如果用户传入了自定义扩展，添加它们
+    if (this.options.extensions) {
+      extensions.push(...this.options.extensions)
+    }
+    if (this.options.mdastExtensions) {
+      mdastExtensions.push(...this.options.mdastExtensions)
+    }
+
+    return fromMarkdown(text, { extensions, mdastExtensions })
+  }
+
+  /**
+   * 增量更新 lines 和 lineOffsets
+   * 只处理新增的内容，避免全量 split
+   */
+  private updateLines(): void {
+    const prevLineCount = this.lines.length
+
+    if (prevLineCount === 0) {
+      // 首次输入，直接 split
+      this.lines = this.buffer.split('\n')
+      this.lineOffsets = [0]
+      for (let i = 0; i < this.lines.length; i++) {
+        this.lineOffsets.push(this.lineOffsets[i] + this.lines[i].length + 1)
+      }
+      return
+    }
+
+    // 找到最后一个不完整的行（可能被新 chunk 续上）
+    const lastLineStart = this.lineOffsets[prevLineCount - 1]
+    const textFromLastLine = this.buffer.slice(lastLineStart)
+
+    // 重新 split 最后一行及之后的内容
+    const newLines = textFromLastLine.split('\n')
+
+    // 替换最后一行并追加新行
+    this.lines.length = prevLineCount - 1
+    this.lineOffsets.length = prevLineCount
+
+    for (let i = 0; i < newLines.length; i++) {
+      this.lines.push(newLines[i])
+      const prevOffset = this.lineOffsets[this.lineOffsets.length - 1]
+      this.lineOffsets.push(prevOffset + newLines[i].length + 1)
+    }
+  }
+
+  /**
+   * O(1) 获取行偏移量
+   */
+  private getLineOffset(lineIndex: number): number {
+    return this.lineOffsets[lineIndex] ?? 0
+  }
+
+  /**
+   * 查找稳定边界
+   * 返回稳定边界行号和该行对应的上下文（用于后续更新，避免重复计算）
+   */
+  private findStableBoundary(): { line: number; contextAtLine: BlockContext } {
+    let stableLine = -1
+    let stableContext: BlockContext = this.context
+    let tempContext = { ...this.context }
+    const containerConfig = this.getContainerConfig()
+
+    for (let i = this.pendingStartLine; i < this.lines.length; i++) {
+      const line = this.lines[i]
+      const wasInFencedCode = tempContext.inFencedCode
+      const wasInContainer = tempContext.inContainer
+      const wasContainerDepth = tempContext.containerDepth
+
+      tempContext = updateContext(line, tempContext, containerConfig)
+
+      if (wasInFencedCode && !tempContext.inFencedCode) {
+        if (i < this.lines.length - 1) {
+          stableLine = i
+          stableContext = { ...tempContext }
+        }
+        continue
+      }
+
+      if (tempContext.inFencedCode) {
+        continue
+      }
+
+      if (wasInContainer && wasContainerDepth === 1 && !tempContext.inContainer) {
+        if (i < this.lines.length - 1) {
+          stableLine = i
+          stableContext = { ...tempContext }
+        }
+        continue
+      }
+
+      if (tempContext.inContainer) {
+        continue
+      }
+
+      const stablePoint = this.checkStability(i, containerConfig)
+      if (stablePoint >= 0) {
+        stableLine = stablePoint
+        stableContext = { ...tempContext }
+      }
+    }
+
+    return { line: stableLine, contextAtLine: stableContext }
+  }
+
+  private checkStability(
+    lineIndex: number,
+    containerConfig: ContainerConfig | undefined
+  ): number {
+    // 第一行永远不稳定
+    if (lineIndex === 0) {
+      return -1
+    }
+
+    const line = this.lines[lineIndex]
+    const prevLine = this.lines[lineIndex - 1]
+
+    // 前一行是独立块（标题、分割线），该块已完成
+    if (isHeading(prevLine) || isThematicBreak(prevLine)) {
+      return lineIndex - 1
+    }
+
+    // 最后一行不稳定（可能还有更多内容）
+    if (lineIndex >= this.lines.length - 1) {
+      return -1
+    }
+
+    // 前一行非空时，如果当前行是新块开始，则前一块已完成
+    if (!isEmptyLine(prevLine)) {
+      // 新标题开始
+      if (isHeading(line)) {
+        return lineIndex - 1
+      }
+
+      // 新代码块开始
+      if (detectFenceStart(line)) {
+        return lineIndex - 1
+      }
+
+      // 新引用块开始（排除连续引用）
+      if (isBlockquoteStart(line) && !isBlockquoteStart(prevLine)) {
+        return lineIndex - 1
+      }
+
+      // 新列表开始（排除连续列表项）
+      if (isListItemStart(line) && !isListItemStart(prevLine)) {
+        return lineIndex - 1
+      }
+
+      // 新容器开始
+      if (containerConfig !== undefined) {
+        const container = detectContainer(line, containerConfig)
+        if (container && !container.isEnd) {
+          const prevContainer = detectContainer(prevLine, containerConfig)
+          if (!prevContainer || prevContainer.isEnd) {
+            return lineIndex - 1
+          }
+        }
+      }
+    }
+
+    // 空行标志段落结束
+    if (isEmptyLine(line) && !isEmptyLine(prevLine)) {
+      return lineIndex
+    }
+
+    return -1
+  }
+
+  private nodesToBlocks(
+    nodes: RootContent[],
+    startOffset: number,
+    rawText: string,
+    status: BlockStatus
+  ): ParsedBlock[] {
+    const blocks: ParsedBlock[] = []
+    let currentOffset = startOffset
+
+    for (const node of nodes) {
+      const nodeStart = node.position?.start?.offset ?? currentOffset
+      const nodeEnd = node.position?.end?.offset ?? currentOffset + 1
+      const nodeText = rawText.substring(nodeStart - startOffset, nodeEnd - startOffset)
+
+      blocks.push({
+        id: this.generateBlockId(),
+        status,
+        node,
+        startOffset: nodeStart,
+        endOffset: nodeEnd,
+        rawText: nodeText
+      })
+
+      currentOffset = nodeEnd
+    }
+
+    return blocks
+  }
+
+  /**
+   * 追加新的 chunk 并返回增量更新
+   */
+  append(chunk: string): IncrementalUpdate {
+    this.buffer += chunk
+    this.updateLines()
+
+    const { line: stableBoundary, contextAtLine } = this.findStableBoundary()
+
+    const update: IncrementalUpdate = {
+      completed: [],
+      updated: [],
+      pending: [],
+      ast: { type: 'root', children: [] }
+    }
+
+    if (stableBoundary >= this.pendingStartLine && stableBoundary >= 0) {
+      const stableText = this.lines.slice(this.pendingStartLine, stableBoundary + 1).join('\n')
+      const stableOffset = this.getLineOffset(this.pendingStartLine)
+
+      const ast = this.parse(stableText)
+      const newBlocks = this.nodesToBlocks(ast.children, stableOffset, stableText, 'completed')
+
+      this.completedBlocks.push(...newBlocks)
+      update.completed = newBlocks
+
+      // 直接使用 findStableBoundary 计算好的上下文，避免重复遍历
+      this.context = contextAtLine
+      this.pendingStartLine = stableBoundary + 1
+    }
+
+    if (this.pendingStartLine < this.lines.length) {
+      const pendingText = this.lines.slice(this.pendingStartLine).join('\n')
+
+      if (pendingText.trim()) {
+        const pendingOffset = this.getLineOffset(this.pendingStartLine)
+        const ast = this.parse(pendingText)
+
+        update.pending = this.nodesToBlocks(ast.children, pendingOffset, pendingText, 'pending')
+      }
+    }
+
+    // 缓存 pending blocks 供 getAst 使用
+    this.lastPendingBlocks = update.pending
+
+    update.ast = {
+      type: 'root',
+      children: [...this.completedBlocks.map((b) => b.node), ...update.pending.map((b) => b.node)]
+    }
+
+    // 触发状态变化回调
+    this.emitChange(update.pending)
+
+    return update
+  }
+
+  /**
+   * 触发状态变化回调
+   */
+  private emitChange(pendingBlocks: ParsedBlock[] = []): void {
+    if (this.options.onChange) {
+      this.options.onChange({
+        completedBlocks: this.completedBlocks,
+        pendingBlocks,
+        markdown: this.buffer,
+        ast: {
+          type: 'root',
+          children: [
+            ...this.completedBlocks.map((b) => b.node),
+            ...pendingBlocks.map((b) => b.node)
+          ]
+        }
+      })
+    }
+  }
+
+  /**
+   * 标记解析完成，处理剩余内容
+   * 也可用于强制中断时（如用户点击停止），将 pending 内容标记为 completed
+   */
+  finalize(): IncrementalUpdate {
+    const update: IncrementalUpdate = {
+      completed: [],
+      updated: [],
+      pending: [],
+      ast: { type: 'root', children: [] }
+    }
+
+    if (this.pendingStartLine < this.lines.length) {
+      const remainingText = this.lines.slice(this.pendingStartLine).join('\n')
+
+      if (remainingText.trim()) {
+        const remainingOffset = this.getLineOffset(this.pendingStartLine)
+        const ast = this.parse(remainingText)
+
+        const finalBlocks = this.nodesToBlocks(
+          ast.children,
+          remainingOffset,
+          remainingText,
+          'completed'
+        )
+
+        this.completedBlocks.push(...finalBlocks)
+        update.completed = finalBlocks
+      }
+    }
+
+    // 清空 pending 缓存
+    this.lastPendingBlocks = []
+    this.pendingStartLine = this.lines.length
+
+    update.ast = {
+      type: 'root',
+      children: this.completedBlocks.map((b) => b.node)
+    }
+
+    // 触发状态变化回调
+    this.emitChange([])
+
+    return update
+  }
+
+  /**
+   * 强制中断解析，将所有待处理内容标记为完成
+   * 语义上等同于 finalize()，但名称更清晰
+   */
+  abort(): IncrementalUpdate {
+    return this.finalize()
+  }
+
+  /**
+   * 获取当前完整的 AST
+   * 复用上次 append 的 pending 结果，避免重复解析
+   */
+  getAst(): Root {
+    return {
+      type: 'root',
+      children: [
+        ...this.completedBlocks.map((b) => b.node),
+        ...this.lastPendingBlocks.map((b) => b.node)
+      ]
+    }
+  }
+
+  /**
+   * 获取所有已完成的块
+   */
+  getCompletedBlocks(): ParsedBlock[] {
+    return [...this.completedBlocks]
+  }
+
+  /**
+   * 获取当前缓冲区内容
+   */
+  getBuffer(): string {
+    return this.buffer
+  }
+
+  /**
+   * 设置状态变化回调（用于 DevTools 等）
+   */
+  setOnChange(callback: ((state: import('../types').ParserState) => void) | undefined): void {
+    this.options.onChange = callback
+  }
+
+  /**
+   * 重置解析器状态
+   */
+  reset(): void {
+    this.buffer = ''
+    this.lines = []
+    this.lineOffsets = [0]
+    this.completedBlocks = []
+    this.pendingStartLine = 0
+    this.blockIdCounter = 0
+    this.context = createInitialContext()
+    this.lastPendingBlocks = []
+
+    // 触发状态变化回调
+    this.emitChange([])
+  }
+}
+
+/**
+ * 创建 Incremark 解析器实例
+ */
+export function createIncremarkParser(options?: ParserOptions): IncremarkParser {
+  return new IncremarkParser(options)
+}

package/src/parser/index.ts

@@ -0,0 +1,2 @@
+export { IncremarkParser, createIncremarkParser } from './IncremarkParser'
+

package/src/types/index.ts

@@ -0,0 +1,144 @@
+import type { Root, RootContent } from 'mdast'
+import type { Extension as MicromarkExtension } from 'micromark-util-types'
+import type { Extension as MdastExtension } from 'mdast-util-from-markdown'
+
+/**
+ * 解析块的状态
+ */
+export type BlockStatus =
+  | 'pending'    // 正在接收中，可能不完整
+  | 'stable'     // 可能完整，但下一个 chunk 可能会改变它
+  | 'completed'  // 确认完成，不会再改变
+
+/**
+ * 解析出的块
+ */
+export interface ParsedBlock {
+  /** 块的唯一 ID */
+  id: string
+  /** 块状态 */
+  status: BlockStatus
+  /** AST 节点 */
+  node: RootContent
+  /** 原始文本起始位置（相对于完整文档） */
+  startOffset: number
+  /** 原始文本结束位置 */
+  endOffset: number
+  /** 原始文本内容 */
+  rawText: string
+}
+
+/**
+ * 增量更新事件
+ */
+export interface IncrementalUpdate {
+  /** 新完成的块 */
+  completed: ParsedBlock[]
+  /** 更新的块（内容变化） */
+  updated: ParsedBlock[]
+  /** 当前正在解析中的块（可能不完整） */
+  pending: ParsedBlock[]
+  /** 完整的 AST（包含所有已解析的内容） */
+  ast: Root
+}
+
+/**
+ * 容器语法配置
+ */
+export interface ContainerConfig {
+  /** 容器标记字符，默认 ':' */
+  marker?: string
+  /** 最小标记长度，默认 3 */
+  minMarkerLength?: number
+  /** 允许的容器名称（如 ['warning', 'info', 'youtube']），undefined 表示允许所有 */
+  allowedNames?: string[]
+}
+
+/**
+ * 解析器状态变化事件
+ */
+export interface ParserState {
+  /** 已完成的块 */
+  completedBlocks: ParsedBlock[]
+  /** 待处理的块 */
+  pendingBlocks: ParsedBlock[]
+  /** 完整的 Markdown 内容 */
+  markdown: string
+  /** 完整的 AST */
+  ast: Root
+}
+
+/**
+ * 解析器配置
+ */
+export interface ParserOptions {
+  /** 启用 GFM 扩展（表格、任务列表等） */
+  gfm?: boolean
+  /**
+   * 启用 ::: 容器语法支持（用于边界检测）
+   * - false: 禁用（默认）
+   * - true: 使用默认配置启用
+   * - ContainerConfig: 使用自定义配置启用
+   */
+  containers?: boolean | ContainerConfig
+  /** 自定义块边界检测函数 */
+  blockBoundaryDetector?: (content: string, position: number) => boolean
+  /** 自定义 micromark 扩展（如 directive） */
+  extensions?: MicromarkExtension[]
+  /** 自定义 mdast 扩展（如 directiveFromMarkdown） */
+  mdastExtensions?: MdastExtension[]
+  /** 状态变化回调 */
+  onChange?: (state: ParserState) => void
+}
+
+/**
+ * 块上下文
+ */
+export interface BlockContext {
+  /** 当前是否在代码块中 */
+  inFencedCode: boolean
+  /** 代码块的 fence 字符（` 或 ~） */
+  fenceChar?: string
+  /** 代码块的 fence 长度 */
+  fenceLength?: number
+  /** 当前列表嵌套深度 */
+  listDepth: number
+  /** 当前引用嵌套深度 */
+  blockquoteDepth: number
+  /** 当前是否在容器块中 */
+  inContainer: boolean
+  /** 容器的标记长度 */
+  containerMarkerLength?: number
+  /** 容器名称 */
+  containerName?: string
+  /** 容器嵌套深度（支持嵌套容器） */
+  containerDepth: number
+}
+
+/**
+ * 容器检测结果
+ */
+export interface ContainerMatch {
+  /** 容器名称 */
+  name: string
+  /** 标记长度（冒号数量） */
+  markerLength: number
+  /** 是否是结束标记 */
+  isEnd: boolean
+}
+
+/**
+ * 块类型检测结果
+ */
+export interface BlockTypeInfo {
+  type: string
+  /** 是否是容器节点（可以包含其他块） */
+  isContainer: boolean
+  /** 是否需要显式关闭（如代码块） */
+  requiresClosing: boolean
+  /** 关闭模式 */
+  closingPattern?: RegExp
+}
+
+export type { Root, RootContent }
+

package/src/utils/index.ts

@@ -0,0 +1,44 @@
+/**
+ * 工具函数
+ */
+
+/**
+ * 生成唯一 ID
+ */
+let idCounter = 0
+export function generateId(prefix = 'block'): string {
+  return `${prefix}-${++idCounter}`
+}
+
+/**
+ * 重置 ID 计数器（用于测试）
+ */
+export function resetIdCounter(): void {
+  idCounter = 0
+}
+
+/**
+ * 计算行的偏移量
+ */
+export function calculateLineOffset(lines: string[], lineIndex: number): number {
+  let offset = 0
+  for (let i = 0; i < lineIndex && i < lines.length; i++) {
+    offset += lines[i].length + 1 // +1 for newline
+  }
+  return offset
+}
+
+/**
+ * 将文本按行分割
+ */
+export function splitLines(text: string): string[] {
+  return text.split('\n')
+}
+
+/**
+ * 合并行为文本
+ */
+export function joinLines(lines: string[], start: number, end: number): string {
+  return lines.slice(start, end + 1).join('\n')
+}
+