diff --git a/doc/adr/0001-implementation-language.md b/doc/adr/0001-implementation-language.md index 8fa80e0..09fe955 100644 --- a/doc/adr/0001-implementation-language.md +++ b/doc/adr/0001-implementation-language.md @@ -5,28 +5,24 @@ | 状态 | **Spike 通过(Python)** — 参考实现语言待勾选 | | 日期 | 2026-08-04 | | 决策者 | chaungming + 协作 | -| 相关 | [tech-stack.md](../design/tech-stack.md) · [markdown-mapping.md](../design/markdown-mapping.md) | +| 相关 | [tech-stack.md](../design/tech-stack.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [spike/REPORT.md](../../spike/REPORT.md) | --- ## 背景 -语法宪法 v0.1 已定。需要选定**第一版参考实现**的实现语言与 GFM 解析前端,以便: +语法宪法 v0.1 已定。需要选定第一版参考实现的实现语言与 Markdown 前端,以便跑通 `examples/*.mq.md`,并用测试锁定行首判别、`*`/`**`、`+`/`-`、表格、frontmatter `>`。 -- 跑通 `examples/*.mq.md` -- 用测试锁定行首判别、`*`/`**`、`+`/`-`、表格、frontmatter `>` -- **不**在未论证前把某语言脚手架当成既成事实 - -目标是**验证宪法**,不是一次定终身的生产编译器。 +目标是验证宪法,不是一次定终身的生产编译器。 --- ## 约束(验收必须满足) -1. 能区分无序列表的 **`-` vs `+`** 项目符(分支/循环)。 -2. GFM **表格**、**emphasis / strong**(`*` / `**`)边界可映射回源位置。 -3. 能做**行预分类**(无标记=注释)再 lower 到 Marqdo AST。 -4. frontmatter 中非纯 YAML 的 **`> file.mq.md` 行**可解析。 +1. 能区分无序列表的 `-` vs `+` 项目符(分支/循环)。 +2. GFM 表格、emphasis / strong(`*` / `**`)可解析。 +3. 能做行预分类(无标记=注释)再 lower 到 Marqdo AST。 +4. frontmatter 中非纯 YAML 的 `> file.mq.md` 行可解析。 5. CLI + 自动化测试可对照 `examples/` 期望输出。 --- @@ -35,58 +31,40 @@ | ID | 方案 | 验证期适配 | 长期编译器适配 | |----|------|------------|----------------| -| A | **TypeScript + remark/rehype(mdast)+ Vitest** | 高 | 中(可留作工具链) | -| B | **Rust + comrak 或 pulldown-cmark + 集成测试** | 中 | 高 | -| C | Python + mistune/markdown-it-py | 高(原型) | 低 | +| A | TypeScript + remark/mdast + Vitest | 高 | 中 | +| B | Rust + comrak / pulldown-cmark | 中 | 高 | +| C | Python + markdown-it-py + pytest | 高 | 中(可作参考实现) | | D | Go + goldmark | 中 | 中 | -详见对比:[tech-stack.md](../design/tech-stack.md)。 +详见 [tech-stack.md](../design/tech-stack.md)。 --- -## 提议决策(请确认) +## 已执行:Python Spike -### 验证期(现在 → 跑通 examples) +因 npm 过慢,Spike **改用选项 C(Python)**,目录 [`spike/`](../../spike/)。 -**Spike 优先采用 Python(快速验证),不默认上 npm/TypeScript 脚手架。** +结果:**S1–S5 全部通过**(`pytest` 6 passed)。见 [REPORT.md](../../spike/REPORT.md)。 -| 步骤 | 选择 | -|------|------| -| **Spike(进行中)** | **Python 3.11+** + 轻量 Markdown 库(如 `markdown-it-py`)+ `pytest` | -| 验证通过后的参考实现 | 另议:可继续 Python,或再评 TypeScript / Rust(见原选项 A/B) | +关键发现: -理由:npm 安装过慢会阻塞 Spike;Python 足以验收 S1–S5 与「行分类 / bullet 区分」风险。 -**原选项 A(TypeScript + remark)降为验证通过后的候选实现,不再作为 Spike 必经之路。** - -### 长期(宪法稳定后) - -**不绑定 A。** 另开 ADR 评估 Rust(选项 B)作正式编译器/单二进制;TS 实现可降级为兼容测试预言机或弃用。 - -### 明确不选(验证期) - -- **C Python** 作唯一实现:易成抛弃原型,双维护差。 -- **未 Spike 就写死 B**:怕拖慢验证。若你更熟 Rust且愿意先 Spike B,可对调。 +- `-` / `+` 必须用**行扫描**保留项目符。 +- frontmatter 导入行不能整块丢给严格 YAML。 +- `markdown-it-py` 足够解析强调与表格;勿开缺依赖的 linkify。 --- -## Spike 清单(定案前 ≥ 完成 A;可选 B) +## 待确认:参考实现语言 -| # | 用例 | 通过标准 | -|---|------|----------| -| S1 | `*a*` vs `**a**` | 得到 emphasis / strong,且能还原源码切片 | -| S2 | `- item` vs `+ item` | AST **能区分** bullet(或源行补救成功) | -| S3 | 单列表格 | 表头+单元格可遍历 | -| S4 | 文件头 `---` + 正文内 `---` | 能分开 frontmatter 与可选框线 | -| S5 | frontmatter 行 `> x.mq.md` | 不被 YAML 解析掐死,可抽出导入 | +Spike 已证明 Python 路径可行。请勾选正式参考实现: -**提议流程:** 先做 **Python Spike(本目录 `spike/`,≤1 日)** → 记录 S1–S5 通过/补救 → 再决定参考实现语言(Python 延续 / TS / Rust)→ Accepted 后才建正式 `src/`。 +- [ ] **继续 Python**(推荐:与 Spike 同栈,立刻可写 `marqdo run`) +- [ ] 改选 TypeScript(选项 A) +- [ ] 改选 Rust(选项 B) +- [ ] 其它:________ ---- +确认后将本 ADR 标为 **Accepted**,再建立正式包(非 `spike/` 玩具目录)。 -## 确认栏 +### 长期 -- [x] Spike 使用 Python(进行中) -- [ ] Spike 通过后:参考实现继续 Python -- [ ] Spike 通过后:改选 TypeScript -- [ ] Spike 通过后:改选 Rust -- [ ] 其它:________ \ No newline at end of file +不排除日后用 Rust 做生产编译器;与验证期/参考实现可以分离。