From b6629e5450ee8649b44f3ba7600741a35ec8b7ef Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 22 Oct 2026 11:52:27 +0800 Subject: [PATCH] =?UTF-8?q?fix(parse):=20D9=20=E6=9C=AA=E9=97=AD=E5=90=88?= =?UTF-8?q?=E5=BC=95=E5=8F=B7=E4=B8=8D=E5=86=8D=E9=9D=99=E9=BB=98=E5=90=9E?= =?UTF-8?q?=E8=A1=8C=EF=BC=88=E5=88=86=E7=B1=BB=E5=B1=82=20+=20=E8=A7=A3?= =?UTF-8?q?=E6=9E=90=E5=B1=82=E5=8F=8C=E5=B1=82=E4=BF=AE=E5=A4=8D=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 缺陷:`**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 方案评估(待审阅,未改代码) 已知边界:单引号 '...' 未闭合仍是旧行为,留作后续评估 (单引号兼作英文撇号,误判风险高于双引号)。 --- doc/design/change-d9-unterminated-string.md | 184 +++++++++++++++++ doc/design/parser-diagnostics-d8-d9.md | 208 +++++++++++++++++++ doc/design/spaced-function-names-d8.md | 216 ++++++++++++++++++++ src/lex/mod.rs | 66 +++++- src/parse/mod.rs | 13 +- 5 files changed, 685 insertions(+), 2 deletions(-) create mode 100644 doc/design/change-d9-unterminated-string.md create mode 100644 doc/design/parser-diagnostics-d8-d9.md create mode 100644 doc/design/spaced-function-names-d8.md diff --git a/doc/design/change-d9-unterminated-string.md b/doc/design/change-d9-unterminated-string.md new file mode 100644 index 0000000..de85a83 --- /dev/null +++ b/doc/design/change-d9-unterminated-string.md @@ -0,0 +1,184 @@ +# 变更记录:D9 未闭合引号不再静默吞行 + +| | | +|---|---| +| 状态 | **Implemented**(待合入) | +| 日期 | 2026-10-22 | +| 缺陷 | [D9](../research/qdagent-refactor-defects-2026-10.md) | +| 设计 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md) §1 | +| 改动文件 | `src/lex/mod.rs` · `src/parse/mod.rs` | +| 影响面 | 行分类 + 语句解析(仅影响**畸形**输入) | + +--- + +## 1. 修了什么 + +**修复前**:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0。 + +```bash +$ marqdo run u.mq.md +$ echo $? +0 # 没有输出、没有报错,s 这一行凭空消失 +``` + +**修复后**:解析期报错,退出码非 0。 + +```bash +$ marqdo run u.mq.md +error: u.mq.md: 7:1: unterminated string: this line starts bold code but +contains an odd number of `"` -- close the string and the trailing `**` +(line: **s = "abc) +$ echo $? +1 +``` + +(实测记录:报错回显中 `unterminated` 前的空格与行号格式由 +`Diagnostic` 的 span 渲染决定,与其它语法错一致。) + +--- + +## 2. 根因 + +问题**不在**解析器——`parse_quoted_string` 里的 +`bail!("unterminated {quote} string")` 一直都在,措辞也对。 +问题是这一行**根本到不了解析器**: + +``` +"**s = \"abc" + ↓ classify_line + ↓ 首字符 '*' → is_marqdo_star_line? + matching_bold_close() 扫描时遇到 '"' → in_str = true + 之后再也没有 '"' 来关闭 → 后续所有 '*' 都被当作字符串内容跳过 + → 找不到收尾 '**' → 返回 None + ↓ is_marqdo_star_line = false + ↓ 落入 `Some('*') if !is_marqdo_star_line` → LineKind::Comment + ↓ 成为「叙述」,解析器看不到 +``` + +**这是分类层的静默降级,不是解析层的缺陷。** + +它比一般的解析错误更危险,因为: + +| 场景 | 后果 | +|------|------| +| 手写漏一个引号 | 该行消失 → 别处报 `undefined variable`,排查方向被引偏 | +| LLM 生成文档 | 少一段内容,但 `exit 0`、`check` 通过,**文档看起来完整却缺节** | +| CI / 文档门禁 | 门禁试跑通过 → 残缺文档被沉淀入库 | + +--- + +## 3. 怎么改的 + +两层,缺一不可。 + +### 3.1 分类层:把畸形行留在 Code 类 + +`src/lex/mod.rs` + +```rust +if trimmed.starts_with("**") { + if trimmed.trim() == "** **" { + return true; + } + if matching_bold_close(trimmed).is_some() { + return true; + } + // D9: 粗体起始但引号永不闭合 → 找不到收尾 `**` + // 判为 Comment 会静默丢行;判为 Code 让解析器报错 + return has_unterminated_string(trimmed); +} +``` + +新增辅助函数: + +```rust +pub fn has_unterminated_string(line: &str) -> bool { + // 统计未被 \ 转义的双引号个数,奇数即「开了没收」 +} +``` + +### 3.2 解析层:给出精确报错 + +`src/parse/mod.rs`,紧跟既有粗体分支之后: + +```rust +// D9: 粗体起始但引号未闭合 —— 走到这里说明没有收尾 `**`, +// 通用 "unrecognized statement" 会掩盖真正原因。 +if trimmed.starts_with("**") && has_unterminated_string(trimmed) { + bail!("{span}: unterminated string: ... (line: {trimmed})"); +} +``` + +没有这一层,用户会看到 `unrecognized statement: **s = "abc`—— +能定位到行,但不知道是引号没闭合。 + +--- + +## 4. 影响面(改前量化过) + +对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描,正确跳过 `\` 转义: + +| 指标 | 数值 | +|------|------| +| `.mq.md` 文件总数 | 845 | +| 含 `**` 起始代码行的文件 | 620 | +| **引号计数为奇数的代码行** | **0** | + +**结论:不改变任何现有文件的解析结果。** 这条修复只作用于畸形输入。 + +--- + +## 5. 测试 + +### 5.1 新增单元测试(`src/lex/mod.rs`,4 个) + +| 测试 | 断言 | +|------|------| +| `unterminated_quote_inside_bold_is_code_not_comment` | 未闭合引号的粗体行 → `Code`(修复前失败,修复后通过) | +| `balanced_quote_inside_bold_still_code` | 闭合引号仍是 `Code` | +| `prose_with_quotes_stays_comment` | 叙述里提引号 → 仍是 `Comment` | +| `prose_bold_emphasis_with_quote_stays_comment` | 叙述里含孤立引号 → 仍是 `Comment` | + +**先写测试确认失败**(TDD): + +``` +---- lex::tests::unterminated_quote_inside_bold_is_code_not_comment +panicked: expected Code (so parser reports the error), + got [ClassifiedLine { kind: Comment, text: "**s = \"abc" }] +``` + +修复后 14/14 通过。 + +### 5.2 回归 + +| 范围 | 结果 | +|------|------| +| `cargo test --release --lib` | **237 passed, 0 failed**(基线 233 + 新增 4) | +| `cargo test --release --test gold` | 276 passed, 8 failed | +| ↑ 上述 8 个失败是否本次引入 | **否**。`git stash` 后基线同样 8 failed | +| 8 个失败的原因 | 全部 `ext_web_*`,依赖 Go 插件 `libweb` 构建,本机环境不具备 | + +--- + +## 6. 已知边界 + +| 情形 | 行为 | 说明 | +|------|------|------| +| `**s = "a` + 下一行 `b"**` | 报错 | 字符串不跨行,符合现状 | +| 单引号 `'...'` 未闭合 | **仍是旧行为**(静默) | 本次只处理双引号;单引号在 Marqdo 里使用频率低,留作后续 | +| 叙述行含孤立 `"` | 不受影响 | 判定入口是 `starts_with("**")`,叙述行不进入 | + +> 单引号的情况建议后续按同样思路处理,但需要单独评估 +> (单引号也用于英文撇号,误判风险高于双引号)。 + +--- + +## 7. 变更清单 + +| 文件 | 变更 | +|------|------| +| `src/lex/mod.rs` | `is_marqdo_star_line` 增加未闭合引号分支;新增 `pub fn has_unterminated_string`;新增 4 个测试 | +| `src/parse/mod.rs` | import 辅助函数;`parse_simple_stmt` 增加精确报错分支 | +| `doc/design/parser-diagnostics-d8-d9.md` | 新增(设计依据 + 影响面 + 方案评判) | +| `doc/design/spaced-function-names-d8.md` | 新增(D8 方案评估,待审阅) | +| `doc/design/change-d9-unterminated-string.md` | 本文件 | diff --git a/doc/design/parser-diagnostics-d8-d9.md b/doc/design/parser-diagnostics-d8-d9.md new file mode 100644 index 0000000..176c305 --- /dev/null +++ b/doc/design/parser-diagnostics-d8-d9.md @@ -0,0 +1,208 @@ +# 设计:解析器诊断缺陷修复(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`) + +每一步独立提交,便于回滚。 diff --git a/doc/design/spaced-function-names-d8.md b/doc/design/spaced-function-names-d8.md new file mode 100644 index 0000000..76e8d06 --- /dev/null +++ b/doc/design/spaced-function-names-d8.md @@ -0,0 +1,216 @@ +# 方案评估:函数名含空格的调用(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 相关代码。 diff --git a/src/lex/mod.rs b/src/lex/mod.rs index ba119ad..104ac30 100644 --- a/src/lex/mod.rs +++ b/src/lex/mod.rs @@ -138,7 +138,14 @@ fn is_marqdo_star_line(trimmed: &str) -> bool { if trimmed.trim() == "** **" { return true; } - return matching_bold_close(trimmed).is_some(); + if matching_bold_close(trimmed).is_some() { + return true; + } + // D9: a bold-starting line whose string literal is never closed has no + // findable closing `**` -- the scanner stays "inside the string" forever. + // Classifying it as Comment would silently drop the line; treat it as + // Code so the parser can report `unterminated " string`. + return has_unterminated_string(trimmed); } if !trimmed.starts_with('*') || trimmed.len() < 2 { return false; @@ -146,6 +153,29 @@ fn is_marqdo_star_line(trimmed: &str) -> bool { matching_italic_close(trimmed).is_some() } +/// True when `line` contains an odd number of unescaped double quotes, +/// i.e. a string literal that is opened but never closed. +/// +/// Used only by [`is_marqdo_star_line`] to keep a malformed bold line in the +/// Code class so the parser surfaces the error (D9). Prose lines never reach +/// here -- they do not start with `**`. +pub fn has_unterminated_string(line: &str) -> bool { + let bytes = line.as_bytes(); + let mut i = 0usize; + let mut count = 0usize; + while i < bytes.len() { + match bytes[i] { + b'\\' => i += 2, + b'"' => { + count += 1; + i += 1; + } + _ => i += 1, + } + } + count % 2 == 1 +} + /// Closing `**` for a bold segment, skipping strings and backticks. /// Returns the index within `trimmed` of the first `*` of the closing `**`. /// When `require_eol`, the closing `**` must be the last non-ws on the line (whole-line code). @@ -605,6 +635,40 @@ mod tests { assert!(lines.iter().any(|l| l.kind == LineKind::Code)); } + #[test] + fn unterminated_quote_inside_bold_is_code_not_comment() { + // D9: "**s = \"abc" has an unclosed string. Classification must keep it + // as Code so the parser reports "unterminated \" string" instead of + // silently demoting the line to narration. + let lines = classify_source("**s = \"abc\n"); + let code = lines.iter().find(|l| l.text.contains("abc")); + assert!( + matches!(code.map(|l| l.kind), Some(LineKind::Code)), + "expected Code (so parser reports the error), got {lines:?}" + ); + } + + #[test] + fn balanced_quote_inside_bold_still_code() { + let lines = classify_source("**s = \"abc\"**\n"); + let code = lines.iter().find(|l| l.text.contains("abc")); + assert!(matches!(code.map(|l| l.kind), Some(LineKind::Code))); + } + + #[test] + fn prose_with_quotes_stays_comment() { + // Narration that merely mentions quotes must stay narration. + let lines = classify_source("他说 \"你好\",然后走了。\n"); + assert!(matches!(lines.first().map(|l| l.kind), Some(LineKind::Comment))); + } + + #[test] + fn prose_bold_emphasis_with_quote_stays_comment() { + // **强调** with a stray quote in surrounding prose is still narration. + let lines = classify_source("这一句有 \" 引号但不是代码。\n"); + assert!(matches!(lines.first().map(|l| l.kind), Some(LineKind::Comment))); + } + #[test] fn math_fence_body_stays_code() { let lines = classify_source("`f` =\n$$\nx^2 - 2\n$$\n"); diff --git a/src/parse/mod.rs b/src/parse/mod.rs index ec54f92..a4f6f95 100644 --- a/src/parse/mod.rs +++ b/src/parse/mod.rs @@ -15,7 +15,7 @@ use crate::ast::{ BranchArm, Expr, Function, Import, IndexKey, Literal, Module, Param, Stmt, Use, }; use crate::diagnostics::{bail_at, Diagnostic, Span}; -use crate::lex::{classify_source, ClassifiedLine, LineKind}; +use crate::lex::{ClassifiedLine, LineKind, classify_source, has_unterminated_string}; use crate::parse::expr::parse_call_after_gt as call_after_gt; use crate::parse::expr::parse_call_tail; use crate::parse::expr::parse_expr as parse_expr_str; @@ -433,6 +433,17 @@ impl<'a> Cursor<'a> { return self.stmt_from_bold_inner(inner, span); } + // D9: bold code whose string literal is never closed. The line reaches + // this point (classifier keeps it Code) but has no closing `**`, so the + // generic "unrecognized statement" would hide the real cause. + if trimmed.starts_with("**") && has_unterminated_string(trimmed) { + bail!( + "{span}: unterminated string: this line starts bold code but \ + contains an odd number of `\"` -- close the string and the \ + trailing `**` (line: {trimmed})" + ); + } + // v0.3: *…* = return if trimmed.starts_with('*') && trimmed.ends_with('*') && !trimmed.starts_with("**") { let inner = &trimmed[1..trimmed.len() - 1];