设计文档和开发文档

[mahiru114514]

Summary

• add a design document for integrating structured diagnostics into the DSL parsers
• add a development guide covering implementation stages, testing, error recovery, and acceptance criteria
• distinguish current repository behavior from proposed functionality

Scope

Documentation only. No compiler source code or tests are changed.

Validation

• Markdown rendering passed
• local links and code fences checked
• independent documentation review: 0 critical and 0 important issues
• project L2 tests were not run because the local harness and Python test dependencies were unavailable

[github-actions]

🤖 AI Code Review

共审查 2 个变更文件

📁 docs/topics/09-DSL错误提示美化器-开发文档.md

🔴 测试用例分类不一致 — 测试用例清单中“正确基础DSL”包含“for”，但基础 DSL (DSLParser) 通常只支持单行语句，for 属于扩展语法。这将误导开发人员，建议将 for 移至“正确扩展 DSL”，或明确基础 DSL 也支持 for（若确实如此，需在文档中说明）。

🟡 dsl_grammar.py 职责不明确 — 阶段四中定义 OP_SIGNATURES 应放在共享模块，但“建议目录”中的 dsl_grammar.py 描述过于笼统。建议明确该文件是唯一存放语法、正则与算子签名的地方，并与阶段四保持一致，避免重复定义。

🟡 “开发前必须复现的问题”缺少具体示例 — 文档要求记录三类基线输出，但未给出任何示例文本或格式。建议补充一两个实际输出样例（如 bad.dsl 的当前异常文本），以便开发人员对照改进。

💭 PowerShell 命令换行符不兼容 — 测试计划中的 Windows PowerShell 示例使用了 \ 反斜杠换行，但 PowerShell 要求使用反引号 `。建议改为一行或使用反引号，避免用户直接复制时报错。

💭 “设计文档”引用缺乏上下文 — 推荐阅读顺序中引用了设计文档的多个节号，但未概括这些节的内容。如果设计文档不公开，该引用对读者无帮助，建议添加简要说明或提供可访问的链接。

---

📁 docs/topics/09-DSL错误提示美化器-设计文档.md

🔴 设计不一致：DSLSyntaxError 继承关系未明确 — 第7.2节说“继承或等价兼容 DSLParseError”，但第14节又说“让 DSLSyntaxError 保持其子类或兼容别名关系”。未定义具体实现方式（直接继承、别名、或 DSLParseError 变为 DSLSyntaxError 的别名？），导致旧代码 except DSLParseError 的行为不确定。建议：明确选择一种策略（如 DSLSyntaxError 继承 DSLParseError，且不修改 DSLParseError 的现有行为），并在兼容性章节中说明迁移路径。

🔴 render_error 接口设计矛盾 — 第11.2节 render_error 签名 def render_error(err, *, stream: TextIO, use_color: Optional[bool] = None) -> str：接受 stream 参数但返回字符串，stream 仅用于 TTY 检测却未实际写入。调用者无法直观判断是否需要自行打印返回值。建议：分为 format_error(err, use_color)（返回字符串）和 render_error(err, stream, use_color)（直接写入流，返回 None），或明确 stream 只用于检测颜色，并在文档中说明。

🔴 去重键定义可能导致有效错误被抑制 — 第9.3节去重键为 (filename, line, col, error_code, message)。当同一位置同一错误码但不同消息（例如不同修复建议的变体）时，会错误地只保留一个。更合理的做法是 (filename, line, col, error_code) 去重，并保留第一个消息。建议：修改去重键，去掉 message，并明确级联抑制规则（如结构错误导致的后继错误不报告）。

🟡 SourceBuffer 制表符换算缺乏算法细节 — 第7.1节说“caret 的显示列必须逐字符换算”，但未提供具体换算规则（如 tab 按 4 列对齐到下一个制表位）。渲染器实现时可能不一致。建议：补充伪代码或明确说明 display_column = raw_column + sum(tab_width - (current_display_col % tab_width) for each tab before raw_column) 之类的算法。

🟡 CompileResult.diagnostics 与 errors 的同步策略未定义 — 第7.4节说 errors 保留无 ANSI 文本，diagnostics 是首选数据源，但未说明当 diagnostics 存在时 errors 是否自动生成。如果调用方必须同时设置两个字段，容易遗漏。建议：要么让 errors 成为 diagnostics 的只读属性（自动生成纯文本字符串），要么在文档中要求调用方必须从 diagnostics 渲染，并废弃 errors 字段（或标记为向后兼容）。

🟡 CompilerDriver 回退信号未定义 — 第12.3节说“只有明确表示‘该解析器不适用’的内部信号才允许回退”，但未定义该信号是什么（自定义异常？标志位？）。建议：定义 ParserNotApplicable 异常，仅在期待的基础解析器（如 ExtendedDSLParser 遇到纯 DSL 时）抛出，其他异常（包括 DSLSyntaxError）不得触发回退。

🟡 性能基线测量方法不完整 — 第15节要求“原解析流程”中位数，但未说明“原解析流程”是哪个版本（当前 master？是否包含验证？）。建议：明确使用当前 main 分支上 DSLParser().parse(text) 对正确 DSL 基准用例的耗时作为基线，并在性能报告中包含用例列表和机器配置。

🟡 错误码覆盖要求不完整 — 第16节验收标准只要求覆盖 E100、E101、E110、E111、E200、E201，但第8节共定义了 11 个错误码。建议：至少覆盖所有错误码，或明确哪些是可选（如 E202、E203 可推迟），但需在文档中标注。

💭 end_col 的 exclusive 语义与渲染示例不符 — 第7.2节说 end_col 是 1-based exclusive，但第11.1节“按跨度绘制 ^~~~”时，如果 end_col 是 exclusive，则 ^ 覆盖 [col, end_col-1]；但渲染示例中 ^ 通常覆盖到 end_col 对应的字符。建议：明确说明渲染时 ^ 的起止字符索引（Python 风格的 [col-1:end_col-1]），并附上示例。

💭 render_error 的行号宽度缺乏上下文 — 第11.1节要求行号宽度按“本次报告的最大行号计算”，但 render_error 单独渲染一个错误时无法知道最大行号。建议：render_error 增加 max_line_number 参数，或由 ErrorCollector.report() 预计算并传入。

💭 修复建议的“同类”定义模糊 — 第10节“拼写建议仅比较同类关键字或算子名”，未定义如何分类“同类”。建议：明确只与预定义的关键字集合和算子名集合进行编辑距离比较（如 Levenshtein ≤ 2），且只比较相同类型（关键字 vs 算子名不跨类）。

💭 块恢复策略可能导致错误级联风险 — 第9.2节恢复规则第4条在遇到不匹配结束符时主动弹出匹配块，可能掩盖后续错误（如 while … endif 弹出 while，随后 endwhile 变为多余）。虽然文档提到错误上限可抑制，但恢复逻辑本身增加了测试复杂度。建议：采用更保守的策略：只报告错误，不修改栈，让后续行继续匹配，直到 EOF 再报告未闭合块。当前设计请提供更多测试用例证明其收益。

---