@incremark/core 0.0.1

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@incremark/core",
+  "version": "0.0.1",
+  "description": "增量式 Markdown 解析器核心库",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./detector": {
+      "types": "./dist/detector/index.d.ts",
+      "import": "./dist/detector/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@types/mdast": "^4.0.0",
+    "mdast-util-from-markdown": "^2.0.0",
+    "mdast-util-gfm": "^3.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-util-types": "^2.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "markdown",
+    "parser",
+    "incremental",
+    "streaming",
+    "ai",
+    "mdast",
+    "unified"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/incremark.git",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}

package/src/detector/index.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest'
+import {
+  detectFenceStart,
+  detectFenceEnd,
+  isEmptyLine,
+  isHeading,
+  isThematicBreak,
+  isListItemStart,
+  isBlockquoteStart,
+  detectContainer,
+  createInitialContext
+} from './index'
+
+describe('块检测器', () => {
+  describe('detectFenceStart', () => {
+    it('检测反引号 fence', () => {
+      const result = detectFenceStart('```js')
+      expect(result).toEqual({ char: '`', length: 3 })
+    })
+
+    it('检测波浪号 fence', () => {
+      const result = detectFenceStart('~~~python')
+      expect(result).toEqual({ char: '~', length: 3 })
+    })
+
+    it('检测更长的 fence', () => {
+      const result = detectFenceStart('`````')
+      expect(result).toEqual({ char: '`', length: 5 })
+    })
+
+    it('非 fence 返回 null', () => {
+      expect(detectFenceStart('普通文本')).toBeNull()
+      expect(detectFenceStart('``不够长')).toBeNull()
+    })
+  })
+
+  describe('detectFenceEnd', () => {
+    it('匹配相同长度', () => {
+      const context = { ...createInitialContext(), inFencedCode: true, fenceChar: '`', fenceLength: 3 }
+      expect(detectFenceEnd('```', context)).toBe(true)
+    })
+
+    it('匹配更长的结束', () => {
+      const context = { ...createInitialContext(), inFencedCode: true, fenceChar: '`', fenceLength: 3 }
+      expect(detectFenceEnd('`````', context)).toBe(true)
+    })
+
+    it('不匹配更短的', () => {
+      const context = { ...createInitialContext(), inFencedCode: true, fenceChar: '`', fenceLength: 5 }
+      expect(detectFenceEnd('```', context)).toBe(false)
+    })
+  })
+
+  describe('isEmptyLine', () => {
+    it('空行', () => {
+      expect(isEmptyLine('')).toBe(true)
+      expect(isEmptyLine('   ')).toBe(true)
+      expect(isEmptyLine('\t')).toBe(true)
+    })
+
+    it('非空行', () => {
+      expect(isEmptyLine('内容')).toBe(false)
+      expect(isEmptyLine('  a  ')).toBe(false)
+    })
+  })
+
+  describe('isHeading', () => {
+    it('有效标题', () => {
+      expect(isHeading('# H1')).toBe(true)
+      expect(isHeading('## H2')).toBe(true)
+      expect(isHeading('###### H6')).toBe(true)
+    })
+
+    it('无效标题', () => {
+      expect(isHeading('####### H7')).toBe(false) // 超过 6 级
+      expect(isHeading('#没有空格')).toBe(false)
+      expect(isHeading('普通文本')).toBe(false)
+    })
+  })
+
+  describe('isThematicBreak', () => {
+    it('有效水平线', () => {
+      expect(isThematicBreak('---')).toBe(true)
+      expect(isThematicBreak('***')).toBe(true)
+      expect(isThematicBreak('___')).toBe(true)
+      expect(isThematicBreak('-----')).toBe(true)
+    })
+
+    it('无效水平线', () => {
+      expect(isThematicBreak('--')).toBe(false)
+      expect(isThematicBreak('- - -')).toBe(false) // 有空格
+    })
+  })
+
+  describe('isListItemStart', () => {
+    it('无序列表', () => {
+      expect(isListItemStart('- item')).toEqual({ ordered: false, indent: 0 })
+      expect(isListItemStart('  * item')).toEqual({ ordered: false, indent: 2 })
+    })
+
+    it('有序列表', () => {
+      expect(isListItemStart('1. item')).toEqual({ ordered: true, indent: 0 })
+      expect(isListItemStart('  99. item')).toEqual({ ordered: true, indent: 2 })
+    })
+
+    it('非列表', () => {
+      expect(isListItemStart('普通文本')).toBeNull()
+    })
+  })
+
+  describe('isBlockquoteStart', () => {
+    it('有效引用', () => {
+      expect(isBlockquoteStart('> quote')).toBe(true)
+      expect(isBlockquoteStart('  > quote')).toBe(true)
+    })
+
+    it('无效引用', () => {
+      expect(isBlockquoteStart('    > 太多缩进')).toBe(false)
+    })
+  })
+
+  describe('detectContainer', () => {
+    it('检测容器开始', () => {
+      const result = detectContainer('::: warning')
+      expect(result).toEqual({ name: 'warning', markerLength: 3, isEnd: false })
+    })
+
+    it('检测容器结束', () => {
+      const result = detectContainer(':::')
+      expect(result).toEqual({ name: '', markerLength: 3, isEnd: true })
+    })
+
+    it('检测更长的标记', () => {
+      const result = detectContainer('::::: outer')
+      expect(result).toEqual({ name: 'outer', markerLength: 5, isEnd: false })
+    })
+
+    it('名称白名单', () => {
+      const config = { allowedNames: ['warning', 'info'] }
+      expect(detectContainer('::: warning', config)).not.toBeNull()
+      expect(detectContainer('::: danger', config)).toBeNull()
+    })
+
+    it('非容器语法', () => {
+      expect(detectContainer('普通文本')).toBeNull()
+      expect(detectContainer(':: 太短')).toBeNull()
+    })
+  })
+})
+

package/src/detector/index.ts

@@ -0,0 +1,271 @@
+/**
+ * 块类型检测与边界判断
+ *
+ * Markdown 块级元素的识别规则
+ */
+
+import type { BlockContext, ContainerConfig, ContainerMatch } from '../types'
+
+// ============ 代码块检测 ============
+
+/**
+ * 检测行是否是代码块 fence 开始
+ */
+export function detectFenceStart(line: string): { char: string; length: number } | null {
+  const match = line.match(/^(\s*)((`{3,})|(~{3,}))/)
+  if (match) {
+    const fence = match[2]
+    const char = fence[0]
+    return { char, length: fence.length }
+  }
+  return null
+}
+
+/**
+ * 检测行是否是代码块 fence 结束
+ */
+export function detectFenceEnd(line: string, context: BlockContext): boolean {
+  if (!context.inFencedCode || !context.fenceChar || !context.fenceLength) {
+    return false
+  }
+
+  const pattern = new RegExp(`^\\s{0,3}${context.fenceChar}{${context.fenceLength},}\\s*$`)
+  return pattern.test(line)
+}
+
+// ============ 行类型检测 ============
+
+/**
+ * 检测是否是空行或仅包含空白字符
+ */
+export function isEmptyLine(line: string): boolean {
+  return /^\s*$/.test(line)
+}
+
+/**
+ * 检测是否是标题行
+ */
+export function isHeading(line: string): boolean {
+  return /^#{1,6}\s/.test(line)
+}
+
+/**
+ * 检测是否是 thematic break（水平线）
+ */
+export function isThematicBreak(line: string): boolean {
+  return /^(\*{3,}|-{3,}|_{3,})\s*$/.test(line.trim())
+}
+
+/**
+ * 检测是否是列表项开始
+ */
+export function isListItemStart(line: string): { ordered: boolean; indent: number } | null {
+  // 无序列表: - * +
+  const unordered = line.match(/^(\s*)([-*+])\s/)
+  if (unordered) {
+    return { ordered: false, indent: unordered[1].length }
+  }
+
+  // 有序列表: 1. 2) 等
+  const ordered = line.match(/^(\s*)(\d{1,9})[.)]\s/)
+  if (ordered) {
+    return { ordered: true, indent: ordered[1].length }
+  }
+
+  return null
+}
+
+/**
+ * 检测是否是引用块开始
+ */
+export function isBlockquoteStart(line: string): boolean {
+  return /^\s{0,3}>/.test(line)
+}
+
+/**
+ * 检测是否是 HTML 块
+ */
+export function isHtmlBlock(line: string): boolean {
+  return (
+    /^\s{0,3}<(script|pre|style|textarea|!--|!DOCTYPE|\?|!\[CDATA\[)/i.test(line) ||
+    /^\s{0,3}<\/?[a-zA-Z][a-zA-Z0-9-]*(\s|>|$)/.test(line)
+  )
+}
+
+/**
+ * 检测表格分隔行
+ */
+export function isTableDelimiter(line: string): boolean {
+  return /^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?$/.test(line.trim())
+}
+
+// ============ 容器检测 ============
+
+/**
+ * 检测容器开始或结束
+ *
+ * 支持格式：
+ * - ::: name      开始
+ * - ::: name attr 开始（带属性）
+ * - :::           结束
+ * - :::::: name   开始（更长的标记，用于嵌套）
+ */
+export function detectContainer(line: string, config?: ContainerConfig): ContainerMatch | null {
+  const marker = config?.marker || ':'
+  const minLength = config?.minMarkerLength || 3
+
+  const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(
+    `^(\\s*)(${escapedMarker}{${minLength},})(?:\\s+(\\w[\\w-]*))?(?:\\s+(.*))?\\s*$`
+  )
+
+  const match = line.match(pattern)
+  if (!match) {
+    return null
+  }
+
+  const markerLength = match[2].length
+  const name = match[3] || ''
+  const isEnd = !name && !match[4]
+
+  if (!isEnd && config?.allowedNames && config.allowedNames.length > 0) {
+    if (!config.allowedNames.includes(name)) {
+      return null
+    }
+  }
+
+  return { name, markerLength, isEnd }
+}
+
+/**
+ * 检测容器结束
+ */
+export function detectContainerEnd(
+  line: string,
+  context: BlockContext,
+  config?: ContainerConfig
+): boolean {
+  if (!context.inContainer || !context.containerMarkerLength) {
+    return false
+  }
+
+  const result = detectContainer(line, config)
+  if (!result) {
+    return false
+  }
+
+  return result.isEnd && result.markerLength >= context.containerMarkerLength
+}
+
+// ============ 边界检测 ============
+
+/**
+ * 判断两行之间是否构成块边界
+ */
+export function isBlockBoundary(
+  prevLine: string,
+  currentLine: string,
+  context: BlockContext
+): boolean {
+  if (context.inFencedCode) {
+    return detectFenceEnd(currentLine, context)
+  }
+
+  if (isEmptyLine(prevLine) && !isEmptyLine(currentLine)) {
+    return true
+  }
+
+  if (isHeading(currentLine) && !isEmptyLine(prevLine)) {
+    return true
+  }
+
+  if (isThematicBreak(currentLine)) {
+    return true
+  }
+
+  if (detectFenceStart(currentLine)) {
+    return true
+  }
+
+  return false
+}
+
+// ============ 上下文管理 ============
+
+/**
+ * 创建初始上下文
+ */
+export function createInitialContext(): BlockContext {
+  return {
+    inFencedCode: false,
+    listDepth: 0,
+    blockquoteDepth: 0,
+    inContainer: false,
+    containerDepth: 0
+  }
+}
+
+/**
+ * 更新上下文（处理一行后）
+ */
+export function updateContext(
+  line: string,
+  context: BlockContext,
+  containerConfig?: ContainerConfig | boolean
+): BlockContext {
+  const newContext = { ...context }
+
+  const containerCfg =
+    containerConfig === true ? {} : containerConfig === false ? undefined : containerConfig
+
+  // 代码块优先级最高
+  if (context.inFencedCode) {
+    if (detectFenceEnd(line, context)) {
+      newContext.inFencedCode = false
+      newContext.fenceChar = undefined
+      newContext.fenceLength = undefined
+    }
+    return newContext
+  }
+
+  const fence = detectFenceStart(line)
+  if (fence) {
+    newContext.inFencedCode = true
+    newContext.fenceChar = fence.char
+    newContext.fenceLength = fence.length
+    return newContext
+  }
+
+  // 容器处理
+  if (containerCfg !== undefined) {
+    if (context.inContainer) {
+      if (detectContainerEnd(line, context, containerCfg)) {
+        newContext.containerDepth = context.containerDepth - 1
+        if (newContext.containerDepth === 0) {
+          newContext.inContainer = false
+          newContext.containerMarkerLength = undefined
+          newContext.containerName = undefined
+        }
+        return newContext
+      }
+
+      const nested = detectContainer(line, containerCfg)
+      if (nested && !nested.isEnd) {
+        newContext.containerDepth = context.containerDepth + 1
+        return newContext
+      }
+    } else {
+      const container = detectContainer(line, containerCfg)
+      if (container && !container.isEnd) {
+        newContext.inContainer = true
+        newContext.containerMarkerLength = container.markerLength
+        newContext.containerName = container.name
+        newContext.containerDepth = 1
+        return newContext
+      }
+    }
+  }
+
+  return newContext
+}
+

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @incremark/core
+ *
+ * 增量式 Markdown 解析器核心库
+ * 专为 AI 流式输出场景设计
+ */
+
+// 核心解析器
+export { IncremarkParser, createIncremarkParser } from './parser'
+
+// 类型导出
+export type {
+  BlockStatus,
+  ParsedBlock,
+  IncrementalUpdate,
+  ParserOptions,
+  ParserState,
+  ContainerConfig,
+  BlockContext,
+  ContainerMatch,
+  BlockTypeInfo,
+  Root,
+  RootContent
+} from './types'
+
+// 检测器
+export {
+  // 代码块
+  detectFenceStart,
+  detectFenceEnd,
+  // 行类型
+  isEmptyLine,
+  isHeading,
+  isThematicBreak,
+  isListItemStart,
+  isBlockquoteStart,
+  isHtmlBlock,
+  isTableDelimiter,
+  // 容器
+  detectContainer,
+  detectContainerEnd,
+  // 边界
+  isBlockBoundary,
+  // 上下文
+  createInitialContext,
+  updateContext
+} from './detector'
+
+// 工具函数
+export { generateId, resetIdCounter, calculateLineOffset, splitLines, joinLines } from './utils'
+