Files
marqdo/doc/design/parser-diagnostics-d8-d9.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

209 lines
8.1 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 设计:解析器诊断缺陷修复(D8 / D9)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-10-22 |
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 / D9 |
| 影响面 | **核心解析**(`src/lex/mod.rs` 行分类 + `src/parse/expr.rs` 函数调用) |
| 关联 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-vs-comment.md](code-vs-comment.md) |
---
## 0. 为什么这两条要先做调研
D8 与 D9 都落在**行分类**这一层:它决定一行是「叙述」还是「代码」。
改错的代价是**整类文档解析结果变化**,而不是某个函数行为变化。
所以本文先量化影响面、列出候选方案并逐条否决,再动手。
一句话结论:
- **D9** 的根因是分类层把「引号未闭合的粗体行」降级为叙述,
导致解析层精心准备的 `unterminated " string` 报错**永远走不到**。
修法是在分类层补一条「粗体起始但闭合搜索失败」的判定,让它进入解析层报错。
语料实测 620 个文件 0 处受影响,风险可控。
- **D8** 的根因是函数名解析按空格切词,与定义侧不对称。
修法是在**定义期**拒绝含空格的函数名(fail fast),
而不是在调用期做贪婪匹配(那会改变所有多词行的语义)。
---
## 1. D9 — 未闭合引号静默吞行
### 1.1 现状链路
```
源码行 "**s = \"abc"
↓ classify_source → classify_line
↓ 首字符 '*' → is_marqdo_star_line?
trimmed.starts_with("**") → matching_bold_close(trimmed)
→ matching_bold_close_opts(require_eol=true)
扫描时遇 '"' → in_str = true
之后没有任何 '"' 关闭它 → 后续 '*' 全部被当作字符串内容跳过
返回 None(找不到收尾 **)
→ is_marqdo_star_line = false
↓ classify_line 落到 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
↓ 该行成为**叙述**,parser 根本看不到它
↓ parse_quoted_string 里 `bail!("unterminated {quote} string")` 不可达
```
**结论**:这不是解析器的 bug,是**分类器的静默降级**。
解析层已经把错误信息写好了,却没有人把这一行送到它面前。
### 1.2 影响(为什么算高严重度)
| 场景 | 后果 |
|------|------|
| 手写漏一个引号 | 该行消失;变量未定义 → 在别处报 `undefined variable`,方向被引偏 |
| LLM 生成文档 | 少一段内容,但 `exit 0`、`marqdo check` 通过,**文档看起来完整却缺节** |
| CI/门禁 | 门禁试跑通过 → 错误文档被沉淀入库 |
对「文档即程序」而言,这属于最危险的一类:**静默产出错误结果**。
### 1.3 候选方案与评判
#### 方案 A:分类层补判定(采纳)
在 `is_marqdo_star_line` 中,当 `trimmed.starts_with("**")` 且
`matching_bold_close` 返回 `None` 时,再判断「这一行是否**像**粗体代码」:
- 行内含有 `=`(赋值)或 `>` 前导(调用)等强代码信号
- 且引号计数为奇数
满足则**仍判为 Code**,让解析层去报 `unterminated " string`。
**优点**
- 改动局限在分类层,不动解析语义
- 复用解析层已有的、措辞准确的报错
- 对「正常叙述中含 `**` 强调」零影响(那些行引号是配对的)
**风险**:叙述里恰好出现 `**…"…` 这种畸形组合会被判成代码 → 报错。
但实测语料 0 例,且这种组合本身就是写法错误,报错是**期望行为**。
#### 方案 B:解析层预扫描(否决)
在 `parse_classified` 前加一遍全文引号配对检查。
**否决理由**:引号可以合法地出现在叙述、围栏代码块、行内代码里。
全文扫描无法区分上下文,会制造大量假阳性(例如叙述里写「他说 "你好」)。
逐行判断需要的是**分类**信息,而这正是方案 A 在做的事。
#### 方案 C:放宽 `matching_bold_close`,引号未闭合时也认 `**` 收尾(否决)
**否决理由**:会改变「粗体闭合」的语义。`**s = "a ** b"` 这类行
会提前在中间 `**` 处闭合,把字符串拆断,产生更难理解的错误。
这是把静默错误换成**更混乱的错误**,不是改进。
### 1.4 影响面实测
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描:
| 指标 | 数值 |
|------|------|
| `.mq.md` 文件总数 | 845 |
| 含 `**` 起始代码行的文件 | 620 |
| **引号计数为奇数的代码行** | **0** |
扫描时正确跳过了 `\` 转义(`\"` 不算引号开合)。
结论:修复不会改变任何现有文件的解析结果。
### 1.5 验收
| 用例 | 期望 |
|------|------|
| `**s = "abc`(未闭合) | 报 `unterminated " string`,退出码非 0 |
| `**s = "abc"`(闭合) | 正常运行 |
| 跨行 `**s = "a` + `b"**` | 报错(不跨行拼接,符合现状) |
| 叙述 `他说 "你好"` | 仍是叙述,不受影响 |
| 全量 `cargo test` | 233 全绿 |
| 全仓库重跑 `marqdo check` | 无新增错误 |
---
## 2. D8 — 函数名含空格:定义成功、调用必崩
> **⚠️ 本节方案已作废。** 原主张「定义期拒绝空格」违背了「完全兼容 Markdown」:
> `## 用户 登录流程` 是合法标题,不该为了可调用而改写。
> 现行评估见 [spaced-function-names-d8.md](spaced-function-names-d8.md)(Proposed · 待审阅)。
> 本文其余部分(D9)仍然有效。
### 2.1 现状链路
```
定义侧:## 加一 号 → 标题整体作为函数名 "加一 号"(允许空格)
调用侧:> 加一 号 n=1
↓ 按空白切词
token[0] = "加一" → 当作函数名
token[1..] = ["号", "n=1"]
↓ "号" 无 `=` → 按位置参数/变量插值处理
↓ 变量 "号" 不存在 → undefined variable `号`
```
两侧不对称:定义时把整串当名字,调用时只取第一个词。
### 2.2 候选方案与评判
#### 方案 A:定义期拒绝空格(**已否决**)
解析 `## 函数名` 时,若函数名含空白则报错:
```
error: 文件:行: function name may not contain spaces: `加一 号`
(write `加一_号`, or quote the call as `> "加一 号"`)
```
**优点**
- fail fast:错误在定义处暴露,与调用处报 `undefined variable` 相比指向明确
- 不改变任何合法程序的语义
- 与「标识符不含空格」的通行约定一致
**风险**:可能已有文件用了空格函数名且**只定义不调用**(今天能跑)。
需先扫描语料确认。
#### 方案 B:调用侧贪婪匹配已知函数名(否决)
按「已知函数名的最长前缀」匹配。
**否决理由**:
1. 需要把「所有已定义函数名」带进表达式解析上下文,跨越模块边界后不可判定
2. `> print text=hello world` 里 `hello world` 会被尝试拼成函数名,语义歧义
3. 改变所有多词行的解析路径,属于核心语义变更,收益远小于风险
#### 方案 C:只警告不报错(否决)
**否决理由**:D8 的危害正是「check 通过、运行崩」。继续给警告等于维持现状。
### 2.3 影响面实测
统计仓库内**定义侧含空格**的 `##`/`###` 标题(仅可调用的层级):
| 指标 | 数值 |
|------|------|
| 含空格的二级及以下标题 | 4 |
| 其中位于源码(非运行时目录)的 | **0** |
| 分布 | 全部在 `.marqdo/agent/contexts/*.mq.md` 运行时生成物,且是叙述性标题("Existing Capabilities"),从未被调用 |
结论:源码中不存在含空格的函数名,加定义期校验不会破坏任何现有模块。
运行时生成的 context 文件不受影响——它们不被 import。
### 2.4 验收
| 用例 | 期望 |
|------|------|
| `## 加一 号` | 报 `function name may not contain spaces` |
| `## 加一_号` + 调用 | 正常 |
| `## 断言干净`(中文连写) | 正常 |
| 方法 `### 名字 带空格` | 同样拒绝 |
| 全量测试 | 233 全绿 |
---
## 3. 实施顺序
1. D9(分类层,影响面已量化)→ 测试 → 文档
2. D8(定义期校验)→ 测试 → 文档
3. 两条都做完后跑全仓库回归(`cargo test` + 抽样 `marqdo run`)
每一步独立提交,便于回滚。