Accept route C: ship the interpreter/VM on wasm32 with a thin JS host bridge, not transpile-to-JS. Add design, roadmap, and cross-links. Co-authored-by: Cursor <cursoragent@cursor.com>
153 lines
6.1 KiB
Markdown
153 lines
6.1 KiB
Markdown
# 参考实现:技术选型分析(尚未拍板)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **分析中 — 未定案** |
|
||
| 日期 | 2026-08-04 |
|
||
| 说明 | 对比候选与约束;**不在本文直接开写实现仓库脚手架** |
|
||
|
||
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,**最终实现语言须单开 ADR 确认后再动工。**
|
||
|
||
---
|
||
|
||
## 1. 我们在选什么
|
||
|
||
参考实现至少包含:
|
||
|
||
1. **读入** `.mq.md`(含 frontmatter 混合行)
|
||
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
|
||
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
|
||
4. **两遍**:收集定义 + 导入 → 求值
|
||
5. **CLI** + **金样例测试**(`tests/`)
|
||
|
||
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
|
||
|
||
---
|
||
|
||
## 2. 选型准则(按权重)
|
||
|
||
| 权重 | 准则 | 说明 |
|
||
|------|------|------|
|
||
| 高 | GFM 忠实度 | 表格、列表符、强调边界与 GitHub 预览一致,减少「能渲染不能跑 / 能跑不能渲染」 |
|
||
| 高 | 与宪法同构 | 易于表达「先 mdast/事件流,再 Marqdo AST」 |
|
||
| 高 | 测试与迭代速度 | 改语法宪法时能快速改测试 |
|
||
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
|
||
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
|
||
| 低 | 极致性能 | v0 样例很小 |
|
||
| 低 | 浏览器内运行 | **已后置落地规划**:见 [ADR 0002](../adr/0002-browser-marqdo-wasm.md)(WASM 解释器) |
|
||
|
||
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
|
||
|
||
---
|
||
|
||
## 3. 架构共性(与语言无关)
|
||
|
||
无论选哪门实现语言,流水线应一致:
|
||
|
||
```
|
||
.mq.md 文本
|
||
→ 前端:GFM 友好解析(或事件扫描)
|
||
→ Middle:Marqdo lower(行类、标题树、- / +、表、围栏)
|
||
→ Marqdo AST
|
||
→ 语义:导入图、提升、作用域
|
||
→ 后端:解释器(v0)/日后编译
|
||
→ 测试:tests 金样例 → 期望 stdout
|
||
```
|
||
|
||
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
|
||
|
||
---
|
||
|
||
## 4. 候选对比
|
||
|
||
### A. TypeScript / Node + remark(mdast)
|
||
|
||
| 利 | 弊 |
|
||
|----|----|
|
||
| remark-gfm 与预览器语义接近;mdast 节点齐全 | 运行时依赖 Node;发行 CLI 需打包 |
|
||
| 迭代快、Vitest 方便 | 性能与「系统级编译器」形象偏软 |
|
||
| 与 Markdown 工具链同生态 | 需纪律:避免把业务写进插件泥潭 |
|
||
|
||
**适合:** 验证宪法、快速金样例。
|
||
**不自动等于最终生产编译器。**
|
||
|
||
### B. Rust + pulldown-cmark / comrak
|
||
|
||
| 利 | 弊 |
|
||
|----|----|
|
||
| 单静态二进制、性能好、适合日后正式编译器 | GFM 表格/细节与 GitHub 仍可能有差异,要对齐测试 |
|
||
| 类型与代数数据类型适合 AST | 前期迭代比 TS 慢 |
|
||
| 无 GC、可嵌入 | MD 生态碎片,选库要论证 |
|
||
|
||
**适合:** 中长期「真编译器」或与 TS 原型双轨。
|
||
**风险:** 首版就上 Rust 可能拖慢语法验证。
|
||
|
||
### C. Python + markdown-it-py / mistune
|
||
|
||
| 利 | 弊 |
|
||
|----|----|
|
||
| 原型极快 | 类型与工程化偏弱;双实现时易弃 |
|
||
| 文本处理友好 | 打包 CLI 体验一般 |
|
||
|
||
**适合:** 一次性语法实验。
|
||
**不推荐**作为唯一长期实现,除非团队强约束。
|
||
|
||
### D. Go + goldmark
|
||
|
||
| 利 | 弊 |
|
||
|----|----|
|
||
| 单二进制、部署简单 | 泛型/AST 表达力一般;MD 库选 goldmark 需 GFM 扩展评估 |
|
||
| 并发与工具链成熟 | 与 MD 研究生态联系弱于 JS |
|
||
|
||
**适合:** 工具型 CLI 优先的团队。
|
||
|
||
### E. 自研扫描器(任意语言)+ 仅用 GFM 做对照测试
|
||
|
||
| 利 | 弊 |
|
||
|----|----|
|
||
| 完全控制行首判别与 `+`/`-` 语义 | 重复实现表格/强调,易与渲染不一致 |
|
||
| 可强制「行分类优先于块解析」 | 工作量大 |
|
||
|
||
**适合:** 证明「行首判别」与 CommonMark 块结构冲突时的研究分支。
|
||
可与 A/B 组合:自研 lower,块结构仍喂给现成解析器。
|
||
|
||
---
|
||
|
||
## 5. 关键技术风险(与选语言正交)
|
||
|
||
1. **行首判别 vs 块解析器** — CommonMark 先成块再看内容;Marqdo 先看行类。可能需「行预分类再喂解析器」或「解析后按源位置重分类」。选型时要让候选语言/库能拿到**源行映射**。
|
||
2. **frontmatter 非纯 YAML** — `>` 导入行是扩展;不能整块丢给严格 YAML 解析器。
|
||
3. **`+` 与 `-` 列表** — 多数解析器都认,但 lower 必须保留**项目符字符**,不能只得「unordered list」。选库时验证 AST 是否保留 bullet type。
|
||
4. **`*` else vs `*返回*` vs 强调** — 依赖 inline 解析与「整行恰好一个 `*`」的行级规则并存。
|
||
|
||
以上 4 点应作为**选型验收用例**,写进 ADR:用最小样例在候选栈上 Spike,再定案。
|
||
|
||
---
|
||
|
||
## 6. 建议的决策流程(尚未执行)
|
||
|
||
1. **Spike(各 ≤0.5–1 日)**
|
||
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
|
||
- 候选 B:Rust + comrak/pulldown — 同上。
|
||
- (可选)C 或 D 若团队有偏好再做。
|
||
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `import x:x.mq.md` 的 frontmatter 行。
|
||
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
|
||
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
|
||
|
||
---
|
||
|
||
## 7. 当前态度(非正式投票)
|
||
|
||
| 阶段 | 倾向(待 Spike 验证) |
|
||
|------|------------------------|
|
||
| 语法验证期 | 更可能是 **TypeScript + remark**(快、GFM 近) |
|
||
| 长期生产编译器 | **开放** Rust / Go,不与验证期绑定 |
|
||
|
||
**本文不授权开始实现。** 确认 Spike 计划或直接指定语言后,再写 `adr/0001-implementation-language.md`。
|
||
|
||
---
|
||
|
||
## 8. 与「无标记 = 注释」的关系
|
||
|
||
实现必须先做**行分类**(见 [code-vs-comment.md](code-vs-comment.md)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。
|