MoonMark - 高性能 MoonBit Markdown 解析与渲染引擎

MoonMark 是一款完全使用 MoonBit 编写的轻量级 Markdown 解析器与 HTML 渲染引擎。本项目面向一个有明确文档边界的 CommonMark 风格子集，为博客系统（SSG）、在线预览工具以及富文本编辑器提供基础设施支持。

English Documentation | 参考与致谢说明

🌟 核心特性与申报承诺实现

1. 🚀 基于 StringView 的解析架构

内存视图设计：AST 节点（Text、CodeSpan、Link、Image、CodeBlock）在能够保留源文本切片时使用 MoonBit 原生 StringView。
以实测为准：扁平的块级/行级解析会避免复制文本片段；blockquote/list 等嵌套结构在规范化输入时可能创建临时缓冲区，基准结果取决于工具链和机器。

2. 📍 精确 Span 位置追踪 (Precise Source Mapping)

Position 结构同时记录 1-based 行号 (line)、1-based 列号 (column) 以及基于当前解析器字符串索引模型的 **0-based 偏移量 (offset)**；列号不是 Unicode 字素簇计数。
每一个 Block 和 Inline 语法树节点均包含精确的 span : Span（含 start 与 end），方便集成 IDE 语法高亮、错误诊断与代码重构工具。

3. 🛡️ 防御式 HTML 渲染

HTML 实体转义：严格转义 < (<), > (>), & (&), " ("), ' (') 等敏感字符。
**URL 协议清洗 (sanitize_url)**：扫描 Link 与 Image 目标协议，拒绝 javascript:、vbscript:、file: 及不安全的 data: 内容，并在写入属性前转义安全值。这是渲染器的防御层，不能替代 Content Security Policy。

4. 📦 批量转换与强大的 CLI

开箱即用 CLI：支持单文件转换、多文件批量转换（--batch）以及递归目录转换（--dir），并保留相对目录结构。
目录自动创建：输出目标路径若不存在，命令行工具会自动调用操作系统 API 创建目录结构。

功能范围与当前边界

当前版本支持标题、段落、引用、围栏代码块、有序/无序列表、强调、加粗、行内代码、链接和图片。
原始 HTML 会作为文本转义输出。本项目不宣称完整 CommonMark 兼容、不提供原始 HTML 透传，也不承诺扩展语法兼容。
URL 清洗是渲染器防御层；应用仍应自行校验不可信输入，并配置合适的 Content Security Policy（CSP）。
--dir 会递归处理 .md 与 .markdown，保留相对目录并输出 .html；其他扩展名会被忽略。

🏗️ 架构概览

moonmark/
├── src/ast/       # 抽象语法树（AST）核心定义，采用 StringView 与 Span 定义节点
├── src/parser/    # 状态机驱动的扫描器（Lexer）与向下递归解析器（Parser）
├── src/html/      # 安全转义工具及安全 URL 清洗 HTML 渲染映射
├── src/cli/       # 提供单文件、多文件与目录批量转换 CLI
└── benches/       # 性能基准测试模块

🛠️ 安装、构建与复现步骤

1. 安装 MoonBit 工具链

请安装与本模块兼容的稳定版 MoonBit 工具链，并先检查版本：

# 检查 MoonBit 版本
moon version

2. 获取代码与检验

git clone https://github.com/zmjknn/zxnMoonbit.git
cd zxnMoonbit

# 1. 语法检查
moon check --deny-warn

# 2. 单元测试
moon test

# 3. 性能基准测试
moon bench

# 4. 代码格式化校验
moon fmt --check

# 5. 重新生成公共接口文件（提交前请审阅生成差异）
moon info

# 6. CLI 冒烟测试
moon run src/cli -- --help

# 7. 检查补丁格式
git diff --check

moon info 的作用是重新生成公共 .mbti 接口文件，本身不是通过/失败式测试；提交前应审阅生成差异。

如果系统安装了 GNU Make，也可以使用 make check、make fmt-check、make test、make bench 和 make cli-smoke 快捷执行对应检查。

💻 CLI 命令行工具使用指南

1. Demo 演示模式

直接运行 CLI 查看默认演示效果：

moon run src/cli

2. 单文件转换模式

moon run src/cli -- input.md -o output.html

3. 多文件批量转换模式 (`--batch` / `-b`)

moon run src/cli -- --batch README.md README_zh.md -o dist/

4. 目录批量转换模式 (`--dir` / `-d`)

将输入目录及其子目录中的所有 .md、.markdown 文件批量渲染为 .html，并保留相对目录结构输出到目标文件夹：

moon run src/cli -- --dir docs/ -o dist/
# docs/guide/start.md -> dist/guide/start.html

5. 帮助菜单

moon run src/cli -- --help

--dir 会自动创建缺失的输出目录、保留嵌套相对路径，并忽略非 .md/.markdown 文件。读写失败会由 CLI 报错；如需机器可读的失败处理，请由调用方检查进程输出和目标文件。

本版本验证快照

当前仓库包含 11 个 .mbt 源码/测试文件和 12 个自动化测试，覆盖 AST Span、嵌套块重建、HTML 转义、危险 URL 协议、安全栅格图片 data: URL、空输入、Unicode 文本和 CLI 相对目录输出。

基准模块 benches/bench.mbt 包含三个命名工作负载。使用 moon 0.1.20260713 在 Windows 上得到的一组本地基线如下：

工作负载	平均值 ± σ	范围	基准运行次数
扁平 Markdown	2.19 µs ± 132.08 ns	2.04–2.42 µs	10 × 49,233
结构化 Markdown	3.01 µs ± 125.75 ns	2.87–3.20 µs	10 × 33,538
Unicode 与嵌套 Markdown	6.77 µs ± 167.50 ns	6.57–7.09 µs	10 × 14,904

以上数据是可复现的本地基线，不是跨机器性能保证；进行性能比较前请在目标工具链和硬件上重新运行 moon bench。

📚 开源参考与致谢 (Prior Art & References)

本项目在架构设计与规格规范制定过程中参考了以下优秀开源项目：

marked.js (MIT License)
- 参考范围：AST 语法树节点分类划分（Block/Inline 拆分机制）、HTML 实体转义规则设计及 CLI 命令选项交互规范。
pulldown-cmark (MIT License)
- 参考范围：基于 StringView 切片的零分配状态机解析模型、事件驱动流式解析理念与 CommonMark 测试样例建设思路。

详细参考、许可证全文及引用范围声明请参见 REFERENCES.md。

本项目未打包或复制上述项目的源代码；REFERENCES.md 仅说明设计参考和许可证边界。MoonMark 自有源代码使用 Apache-2.0 发布。

📄 许可证

本项目基于 Apache License 2.0 协议开源。