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 <cursoragent@cursor.com>
This commit is contained in:
1 parent
0ae5bce70a
commit
c1a4bb47b6
3 files changed
+109
-10
No files matched your search
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+8
-7
@@ -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/)。
|
||||
|
||||
|
||||
@@ -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(不是直接铺全量解释器)。
|
||||
Reference in new issue
Block a user