Files
marqdo/doc/design/spaced-function-names-d8.md
cflmy b6629e5450 fix(parse): D9 未闭合引号不再静默吞行(分类层 + 解析层双层修复)
缺陷:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0,
没有输出也没有报错,该行凭空消失。对「文档即程序」来说这是最危险的一类
错误——文档看起来完整、能跑、check 通过,实际少了一节。

根因在**分类层**而不是解析层:
parse_quoted_string 里 `unterminated " string` 的报错一直都在,
但 matching_bold_close 扫描时遇到未闭合的 '"' 后一直处于 in_str 状态,
再也找不到收尾 '**',于是 is_marqdo_star_line 返回 false,
该行被判为 LineKind::Comment 成为叙述,解析器根本看不到它。
解析层精心准备的报错不可达。

修复(两层,缺一不可):
1. src/lex/mod.rs
   - 新增 pub fn has_unterminated_string:统计未被 \ 转义的 '"',奇数即「开了没收」
   - is_marqdo_star_line:粗体起始且找不到收尾时,若引号未闭合则仍判 Code
     (判 Comment 会静默丢行;判 Code 才能让解析器说话)
2. src/parse/mod.rs
   - parse_simple_stmt 紧跟既有粗体分支之后,对「粗体起始 + 引号未闭合」
     给出精确报错,而不是笼统的 unrecognized statement

影响面(改前量化,避免凭直觉改核心解析):
- 全仓库 845 个 .mq.md、620 个含代码行文件
- 引号计数为奇数的代码行:**0**
- 结论:不改变任何现有文件的解析结果,只作用于畸形输入

测试(TDD,先写测试确认失败再修):
- 新增 4 个单测:未闭合→Code、闭合→Code、叙述含引号→Comment、
  叙述含孤立引号→Comment
- 修复前 unterminated_quote_inside_bold_is_code_not_comment 如期失败
- 修复后 lex 14/14;cargo test --lib 237 passed 0 failed(基线 233 + 新增 4)
- cargo test --test gold 276 passed 8 failed;git stash 验证基线同样 8 failed,
  失败全部是 ext_web_*(依赖 Go 插件 libweb,本机环境不具备),与本次无关

文档:
- doc/design/parser-diagnostics-d8-d9.md  设计依据、根因链路、候选方案评判、影响面
- doc/design/change-d9-unterminated-string.md  变更记录(现象/根因/改法/测试/边界)
- doc/design/spaced-function-names-d8.md  D8 方案评估(待审阅,未改代码)

已知边界:单引号 '...' 未闭合仍是旧行为,留作后续评估
(单引号兼作英文撇号,误判风险高于双引号)。
2026-10-22 11:52:27 +08:00

217 lines
9.0 KiB
Markdown
Raw Permalink 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)
| | |
|---|---|
| 状态 | **Proposed · 待审阅**(未实施任何代码改动) |
| 日期 | 2026-10-22 |
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 |
| 前置 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md)(该文方案 A「禁止空格」**已被否决**,见 §0) |
| 影响面 | 核心解析:`src/parse/expr.rs` 调用切词 / `src/lex` 行分类 / 名称解析 |
---
## 0. 为什么原方案被否决
原方案 A 主张「定义期拒绝含空格的函数名」。这是**错的**,理由是我此前忽略的一句话:
> Marqdo 的立身之本就是**完全兼容 Markdown**。
`## 用户 登录` 是一个**完全合法的 Markdown 二级标题**。真实文档里这类标题极多:
```markdown
## 用户 登录流程
## 第三阶段 数据校验
## Appendix A Results
```
如果禁止这些标题当函数名,等于强迫作者为了「能调用」而改写标题措辞——
这恰恰把「代码即文档」降级成「代码迁就文档」。作者写的标题首先应当是**他自己想写的标题**。
**结论:空格必须被支持,问题只在于「怎么把带空格的名字准确传给调用」。**
---
## 1. 事实基础(全部实测,1.5.2)
先固定真实行为,避免方案讨论建立在猜测上。
### 1.1 定义侧
| 输入 | 结果 |
|------|------|
| `## 加一 号` | ✅ 定义成功,函数名**原样**为 `加一 号`(`parse_object_decl` 走 `Ok((raw.to_string(), None))`) |
| `## 用户 登录流程` | ✅ 同上 |
**定义侧完全支持空格**,不需要任何改动。
### 1.2 调用侧
| 输入 | 结果 | 原因 |
|------|------|------|
| `> 加一 号 n=1` | ❌ `undefined variable 号` | `parse_call_tail` 用 `split_whitespace().next()` 只取首词 |
| `> [加一_号] n=1` | ✅ 正常(返回 2) | 方括号标记调用**已存在**且工作 |
| `> [加一 号] n=1` | ❌ `unknown function [加一` | `is_bracket_callee_inner` 第 1248 行**显式拒绝含空白** |
| `` `加一 号` `` 作为表达式 | ❌ `undefined variable 加一 号` | 反引号名走变量解析,找不到函数 |
### 1.3 关键发现
> **方括号标记调用(`[callee]`)已经存在且实现完整**,
> 挡住带空格名字的是 `is_bracket_callee_inner` 里的**两处**校验,
> 而不是一处(首轮评估低估了)。
这是本次评估最重要的发现:**不需要发明新语法**,只需要让既有机制接受空格。
### 1.4 可行性实测(已做,未保留改动)
为回答「放开后运行时到底能不能查到含空格的函数名」,做了受控实验:
临时放开两处校验 → 编译 → 跑用例 → **立即回退**(`src/parse/expr.rs` 已恢复原样)。
| 关卡 | 位置 | 原逻辑 | 放开后 |
|------|------|--------|--------|
| 1 | `is_bracket_callee_inner` | `t.chars().any(is_whitespace)` → 拒绝 | 删除该检查 |
| 2 | 同函数末尾 bare-name 白名单 | `is_alphanumeric() \| '_' \| '.' \| !is_ascii()` | 追加 `\| c == ' '` |
**实验结果**
| 用例 | 结果 |
|------|------|
| `## 加一 号` + `> [加一 号] n=1` | ✅ **返回 `2`**(运行时函数表正确命中含空格名) |
| `## 加一_号` + `> [加一_号] n=1`(对照) | ✅ 仍返回 `2`,既有行为不变 |
| 全量 `cargo test --lib` | ✅ **237 passed, 0 failed** |
**结论**:方案 1 技术上完全成立,且**不破坏既有测试**。
(237 = 基线 233 + 本轮 D9 新增的 4 个分类测试。)
> 注意:实验只证明「可行」,未固化。正式实施需要补 §4 的全部 V1–V9 用例,
> 特别是 V3–V7 的歧义排除,再决定是否合入。
---
## 2. 候选方案
### 方案 1 — 放开方括号内的空格(推荐)
**做法**:把 `is_bracket_callee_inner` 的「含空白即拒绝」改为「允许空白,
但需与既有歧义守卫共存」;并确认调用链后续不再按空格切词。
**用法**:
```markdown
## 用户 登录流程
+ `账号`
*"已登录 " + `账号`*
# main
> [用户 登录流程] 账号=alice
*""
```
**优点**
- 不新增语法:`[…]` 标记调用是**既有**的正式特性,只是被一行校验挡住
- 向后兼容:所有现有调用(含 `[加一_号]`)行为不变
- 与 Markdown 完全兼容:标题怎么写都行,调用时用方括号「引用这个名字」
- 语义清晰:方括号本身就是「这里是一个整体名字」的视觉标记
- 可推广:方法调用 `[obj.方法 名]`、库函数 `[lib.函数 名]` 一并受益
**风险与缓解**
| 风险 | 缓解 |
|------|------|
| `[…]` 也被用于链接索引 `[key](map)` | 已有守卫:`]` 后紧跟 `(` 则不是 callee(第 981 行),保持 |
| JSON 数组 `[1, 2]` 被误认为 callee | 既有守卫:含 `,` `:` `{` `}` `[` `]` 一律拒绝,保持 |
| `print text=(礼貌 [问候] x)` 类内嵌方括号 | 既有守卫:前缀含 `=` `(` `"` `'` `:` 则不当 callee,保持 |
| 运行时按下标查函数表,`加一 号` 能否命中 | **需实测验证**(见 §4 验证计划 V1) |
**工作量**:改 2 处校验 + 补 6–9 个测试 + 更新教程与陷阱手册。**最小可验证改动**。
---
### 方案 2 — 调用侧最长前缀匹配(否决)
**做法**:拿到 `加一 号 n=1` 后,尝试用「已知函数名」做最长前缀匹配。
**否决理由**
1. **上下文不可达**:调用发生在表达式解析阶段,此时只有本模块符号表;
跨模块 `lib.函数 名` 需要 import 解析结果,不可在词法期判定。
2. **歧义爆炸**:`> print text=hello world` 中,若存在名为 `print text` 的函数,
本来正确的调用会突然变成别的函数。所有多词行语义都可能改变。
3. 属于**核心语义变更**,收益(省掉方括号)远小于风险。
---
### 方案 3 — 主张「标题即函数名,调用用完整标题」(不改代码,只改文档)
**做法**:明确官方立场——带空格的名字**不自称可调用**,需要调用就请写
一个无空格的 `## 别名` 转发,或直接把标题写成无空格形式。
```markdown
## 用户 登录流程 ← 给人读的标题,不被调用
## 用户登录流程 ← 真正被调用的函数
+ `账号`
...
```
**优点**:零代码改动;鼓励「标题给人、标识符给机器」的清晰分层。
**缺点**:与「完全兼容 Markdown」仍有张力——作者得写两遍。
**适用**:如果审计认为方括号放开会牵连过多,可作为**保守退路**。
---
### 方案 4 — 反引号名解析到函数(否决)
允许 `` `加一 号` `` 在**调用位**解析成函数引用(`> `加一 号` n=1`)。
**否决理由**:反引号在 Marqdo 中统一表示**变量**引用。让它有时指变量、有时指函数,
会让「反引号=变量」这条最基础的约定失效,错误更难排查。
---
## 3. 方案对比
| 维度 | 方案 1 放开方括号 | 方案 2 前缀匹配 | 方案 3 文档立场 | 方案 4 反引号 |
|------|------------------|----------------|----------------|--------------|
| 兼容 Markdown | ✅ 完全 | ✅ | ⚠️ 需写两遍 | ✅ |
| 新增语法 | 无(复用既有) | 无 | 无 | 有歧义 |
| 改动范围 | 1 处校验 + 测试 | 核心语义 | 0 代码 | 核心语义 |
| 回归风险 | 低 | **高** | 无 | **高** |
| 可验证性 | 高(可枚举用例) | 低 | — | 低 |
| 推荐 | **首选** | 否决 | 备选 | 否决 |
---
## 4. 若采纳方案 1:验证计划
必须全部通过才可合入。
| 编号 | 用例 | 期望 |
|------|------|------|
| V1 ✅| `## 加一 号` + `> [加一 号] n=1` | 返回 `2`(**已实测通过**,见 §1.4) |
| V2 | `## 加一_号` + `> [加一_号] n=1` | 返回 `2`(**既有行为不变**) |
| V3 | 链接索引 `[k](m)` | 仍解析为索引,不被当 callee |
| V4 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不被当 callee |
| V5 | 方括号内 JSON `[1, 2]` / `["a"]` | 仍被拒绝为 callee |
| V6 | 跨模块 `[lib.函数 名]` | 正确解析到库函数 |
| V7 | 方法 `[obj.方法 名]` | 正确解析 receiver |
| V8 | 全量 `cargo test` | 233 全绿(+ 新增用例) |
| V9 | 全仓库 `.mq.md` 回归 | 无新增解析错误 |
**V1 是决定性的**:如果运行时函数表以 `加一 号` 为键能正常查到,
方案 1 就成立;如果查不到(比如符号表内部也做了归一化),需要再评估。
---
## 5. 待你决策的问题
1. **选哪个方案?** 我倾向 **方案 1**(放开方括号空格):不新增语法、
完全兼容 Markdown、改动可控、可验证性强。
2. **若选方案 1,调用书写是否需要中文别名?** 例如同时接受 `【加一 号】`(全角方括号),
与全角冒号问题(D2)一致。
3. **是否要保留方案 3 的文档立场作为补充说明?** 即「标题可自由书写;
需要调用时用 `[完整名]` 引用」——这句话本身就很适合写进教程。
在你确认前,我不会改动 D8 相关代码。