From c1a4bb47b69947e6dc3783f353aa86e15c69798f Mon Sep 17 00:00:00 2001 From: cflmy Date: Tue, 4 Aug 2026 10:55:50 +0800 Subject: [PATCH] Propose ADR 0001 for validation-phase implementation language. Recommend TypeScript + remark for syntax validation, with spikes required before scaffolding and Rust left open for a later compiler. Co-authored-by: Cursor --- README.md | 6 +- doc/README.md | 15 ++-- doc/adr/0001-implementation-language.md | 98 +++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 10 deletions(-) create mode 100644 doc/adr/0001-implementation-language.md diff --git a/README.md b/README.md index a4cfc7d..a72319d 100644 --- a/README.md +++ b/README.md @@ -40,15 +40,15 @@ Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程 1. 叙述默认安全(无标记 = 注释)。 2. 返回是架构;打印只是函数。 3. 依赖清单由工具生成(OKF 风格),不是手填配置。 -4. 实现语言**未定案**,先 Spike 再 ADR([tech-stack.md](doc/design/tech-stack.md))。 +4. 实现语言**未定案**:见选型 ADR [0001](doc/adr/0001-implementation-language.md)(提议:验证期 TypeScript + remark)。 --- ## 现状 - 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md) -- 叙述/可执行:[code-vs-comment.md](doc/design/code-vs-comment.md) -- 选型分析(未拍板):[tech-stack.md](doc/design/tech-stack.md) +- 选型 ADR(提议中):[0001-implementation-language.md](doc/adr/0001-implementation-language.md) +- 选型分析:[tech-stack.md](doc/design/tech-stack.md) --- diff --git a/doc/README.md b/doc/README.md index 8699cce..408cb69 100644 --- a/doc/README.md +++ b/doc/README.md @@ -8,19 +8,20 @@ |------|------| | [`research/`](research/) | 外部标准与调研 | | [`design/`](design/) | 语言设计(语法映射、清单模型等) | -| `adr/` | 架构决策记录(待建) | +| [`adr/`](adr/) | 架构决策记录 | | `roadmap/` | 里程碑(待建) | ## 当前文档 | 文档 | 摘要 | |------|------| -| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0 语法宪法**:Markup-as-Syntax 全映射 | -| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述面 / 可执行面 / 外联面——无标记为何是注释 | -| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | **提案**:`---` 返回、斜体注释、粗体程序面 vs 无标记代码 | -| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 机器生成的 OKF 风格依赖/文档清单 | -| [design/tech-stack.md](design/tech-stack.md) | 参考实现选型**分析**(未定案,待 Spike) | -| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | Google OKF 调研与借鉴 | +| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** | +| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 | +| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出/分割线决议记录 | +| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 | +| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比分析 | +| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **选型 ADR(提议中)** | +| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 | 示例程序见仓库 [`examples/`](../examples/)。 diff --git a/doc/adr/0001-implementation-language.md b/doc/adr/0001-implementation-language.md new file mode 100644 index 0000000..16c55f6 --- /dev/null +++ b/doc/adr/0001-implementation-language.md @@ -0,0 +1,98 @@ +# ADR 0001:参考实现语言与 Markdown 前端 + +| | | +|---|---| +| 状态 | **提议中(Proposed)** — 待确认后 Accepted | +| 日期 | 2026-08-04 | +| 决策者 | chaungming + 协作 | +| 相关 | [tech-stack.md](../design/tech-stack.md) · [markdown-mapping.md](../design/markdown-mapping.md) | + +--- + +## 背景 + +语法宪法 v0.1 已定。需要选定**第一版参考实现**的实现语言与 GFM 解析前端,以便: + +- 跑通 `examples/*.mq.md` +- 用测试锁定行首判别、`*`/`**`、`+`/`-`、表格、frontmatter `>` +- **不**在未论证前把某语言脚手架当成既成事实 + +目标是**验证宪法**,不是一次定终身的生产编译器。 + +--- + +## 约束(验收必须满足) + +1. 能区分无序列表的 **`-` vs `+`** 项目符(分支/循环)。 +2. GFM **表格**、**emphasis / strong**(`*` / `**`)边界可映射回源位置。 +3. 能做**行预分类**(无标记=注释)再 lower 到 Marqdo AST。 +4. frontmatter 中非纯 YAML 的 **`> file.mq.md` 行**可解析。 +5. CLI + 自动化测试可对照 `examples/` 期望输出。 + +--- + +## 选项 + +| ID | 方案 | 验证期适配 | 长期编译器适配 | +|----|------|------------|----------------| +| A | **TypeScript + remark/rehype(mdast)+ Vitest** | 高 | 中(可留作工具链) | +| B | **Rust + comrak 或 pulldown-cmark + 集成测试** | 中 | 高 | +| C | Python + mistune/markdown-it-py | 高(原型) | 低 | +| D | Go + goldmark | 中 | 中 | + +详见对比:[tech-stack.md](../design/tech-stack.md)。 + +--- + +## 提议决策(请确认) + +### 验证期(现在 → 跑通 examples) + +**采用选项 A:TypeScript + remark-gfm + mdast + Vitest + Node ≥ 20。** + +理由: + +1. 与 GitHub 预览最接近,减少「能渲染不能跑」。 +2. mdast 保留 list 的 `spread` / 子节点;需 Spike 确认 **bullet 字符 `-`/`+` 可取**(取不到则自研行扫描补一层)。 +3. 迭代宪法快,符合「设计刚定、语义还在磨」的阶段。 + +### 长期(宪法稳定后) + +**不绑定 A。** 另开 ADR 评估 Rust(选项 B)作正式编译器/单二进制;TS 实现可降级为兼容测试预言机或弃用。 + +### 明确不选(验证期) + +- **C Python** 作唯一实现:易成抛弃原型,双维护差。 +- **未 Spike 就写死 B**:怕拖慢验证。若你更熟 Rust且愿意先 Spike B,可对调。 + +--- + +## 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 A(≤1 日)** → 若 S2 失败再评估自研行扫描或转 Spike B → 将本 ADR 标为 **Accepted** → 再允许添加 `package.json` 与 `src/`。 + +--- + +## 后果 + +- Accepted 后:仓库可建 `src/`、`tests/`,CLI `marqdo run`。 +- 生成 OKF 清单、LSP 等不在本 ADR 范围。 +- 实现须遵守:先做行分类,再求值([code-vs-comment.md](../design/code-vs-comment.md))。 + +--- + +## 确认栏 + +- [ ] 同意验证期 = TypeScript + remark +- [ ] 改选:验证期 = Rust(先 Spike B) +- [ ] 改选:其它:________ + +确认后把状态改为 **Accepted**,并开始 Spike(不是直接铺全量解释器)。