diff --git a/docs/guide/01-quickstart.md b/docs/guide/01-quickstart.md
index 381bd7e..2b237bd 100644
--- a/docs/guide/01-quickstart.md
+++ b/docs/guide/01-quickstart.md
@@ -322,6 +322,7 @@ test=> select * from foo;
```
+> 上面这三条语句(建表、插入、查询)的逐步解释、前置条件和常见误解,见[读懂第一条 SQL:建表、插入与查询](first-three-sql.md)。
- **结语**
本文档只是给用户一个简单的指引,演示如何从源码开始,一步一步搭建一个完整的OpenTenBase集群,后续会有更多的文章来介绍OpenTenBase的特性使用,优化,问题定位等内容。
diff --git a/docs/guide/first-three-sql.md b/docs/guide/first-three-sql.md
new file mode 100644
index 0000000..ac942d8
--- /dev/null
+++ b/docs/guide/first-three-sql.md
@@ -0,0 +1,192 @@
+# 读懂第一条 SQL:建表、插入与查询
+
+> 本文伴读[快速入门](01-quickstart.md)的“使用”小节。那里给出了三条 SQL 和它们的执行输出,但没有逐条说明每条语句在做什么。本文按“建表 → 插入 → 查询”的顺序把这三条拆开讲清楚。
+>
+> 本文不新增 SQL,也不改写原文中的 SQL。标为“来源文档展示”的输出是原文照录,不是实测结果。
+
+## 先分清三种提示符
+
+原文的代码块里混着三类行:shell 命令、SQL 语句、执行输出。它们的区别看行首:
+
+| 行首 | 是什么 | 原文例子 |
+|---|---|---|
+| `$` | 操作系统 shell 提示符,后面是 shell 命令 | `$ psql -h ${CoordinateNode_IP} ...` |
+| `postgres=#` | psql 提示符,当前连的是 `postgres` 库;`#` 表示超级用户 | `postgres=# create database test;` |
+| `test=>` | psql 提示符,执行 `\c test test` 之后已切到 `test` 库;`>` 表示普通用户 | `test=> select * from foo;` |
+| 无提示符 | 上一条语句的执行输出 | `CREATE TABLE`、`(2 rows)` |
+
+复制示例时只复制提示符后面的部分。把 `test=>` 一起粘进 psql,会得到一个语法错误,而不是执行结果。
+
+## 前置条件
+
+三条语句依赖原文前一段的准备工作,按顺序是:
+
+1. 集群已启动,并且能通过 CN(协调节点)连接。
+2. 已建库和用户,并把库的属主交给该用户:原文执行 `create database test;`、`create user test ...`、`alter database test owner to test;`。
+3. 已切换到目标库:原文执行 `\c test test`,之后提示符才从 `postgres=#` 变成 `test=>`。
+
+这也是下文三条语句的提示符都是 `test=>` 的原因:它们是在 `test` 库里、以普通用户 `test` 的身份执行的。
+
+> 原文的建用户示例使用了一个演示用的简单口令。它只适合一次性演示环境,不要复制到任何真实部署中;真实环境请使用符合口令策略的强口令。
+
+## 第一步:建表
+
+**用途**:在 `test` 库里建一张名为 `foo` 的表,并指定按 `id` 列分布数据。
+
+**原文语句**:
+
+
+```sql
+create table foo(id bigint, str text) distribute by shard(id);
+```
+
+**逐段拆解**:
+
+| 片段 | 含义 |
+|---|---|
+| `create table foo` | 建表,表名 `foo` |
+| `(id bigint, str text)` | 两个列:`id` 是 64 位整数,`str` 是变长文本 |
+| `distribute by shard(id)` | OpenTenBase 的分布子句,按 `id` 列的值决定每一行落到哪个 DN(数据节点) |
+
+**关于 `distribute by shard(id)`**:这是 OpenTenBase 在标准 SQL 之外提供的语法,用来描述数据在多个 DN 之间怎么分。理解它时有三个容易过头的地方:
+
+- 它不是 PostgreSQL 或 MySQL 的通用写法,照搬到别的数据库会报错。
+- “按 `id` 分布”不等于“每个 `id` 独占一个节点”,也不等于“两行数据一定落在两个不同的 DN”。
+- 不能只凭插入的行数推断分布结果。某一行实际落在哪个 DN,取决于分布键的取值和节点数量。
+
+**前置条件**:已按上文完成建库、建用户并切换到 `test` 库。
+
+**来源文档展示**:紧跟这条语句,原文给出的标签是 `CREATE TABLE`。
+
+**常见误解**:
+
+- 把 `distribute by shard(id)` 理解成索引或分区。它是数据的分布方式,不创建索引。
+- 以为这段建表语句能直接在单机 PostgreSQL 上运行。它依赖 OpenTenBase 的集群能力。
+- 以为两行数据必然分散在不同节点。分布是按下标值计算的,和插入了几行没有关系。
+
+**来源**:`docs/guide/01-quickstart.md`(固定提交 `4eaeba90188926ddf4da23b74775cdf150ffdfe8`),“使用”小节代码块中,`\c test test` 之后的第一条 `test=>` 语句。[在固定提交上查看](https://github.com/OpenTenBase/docs/blob/4eaeba90188926ddf4da23b74775cdf150ffdfe8/docs/guide/01-quickstart.md)
+
+## 第二步:插入
+
+**用途**:向 `foo` 一次插入两行数据。
+
+**原文语句**:
+
+
+```sql
+insert into foo values(1, 'tencent'), (2, 'shenzhen');
+```
+
+**逐段拆解**:
+
+| 片段 | 含义 |
+|---|---|
+| `insert into foo` | 向 `foo` 表插入 |
+| `values(1, 'tencent'), (2, 'shenzhen')` | 两组括号就是两行,逗号分隔 |
+| `1`、`2` | 对应 `id` 列(整数,不加引号) |
+| `'tencent'`、`'shenzhen'` | 对应 `str` 列(字符串,用单引号) |
+
+**为什么不写列清单**:这条语句省略了 `(id, str)`。省略时,`values` 里的值按建表时的列顺序依次匹配,所以第一个值进 `id`,第二个值进 `str`。写全列清单更不容易出错,但原文示例没有写,本文不改写它。
+
+**前置条件**:`foo` 表已存在,即第一步已成功。否则插入会失败。
+
+**来源文档展示**:紧跟这条语句,原文给出的标签是 `COPY 2`。
+
+> 说明:`COPY 2` 是原文给出的标签,这里照录。如果你在自己的环境里执行,以实际输出为准。
+
+**常见误解**:
+
+- 把两组括号当成一行两列。这里一个括号是一行,两个括号是两行,每行两列。
+- 用双引号写字符串。SQL 里双引号是标识符,字符串必须用单引号。
+- 以为值的个数可以随意。`values` 每组的值的数量必须和表的列数对应。
+
+**来源**:`docs/guide/01-quickstart.md`(固定提交 `4eaeba90188926ddf4da23b74775cdf150ffdfe8`),“使用”小节代码块中,建表语句之后的第一条 `test=>` 语句。[在固定提交上查看](https://github.com/OpenTenBase/docs/blob/4eaeba90188926ddf4da23b74775cdf150ffdfe8/docs/guide/01-quickstart.md)
+
+## 第三步:查询
+
+**用途**:把 `foo` 里的数据读出来,确认前两步的结果。
+
+**原文语句**:
+
+
+```sql
+select * from foo;
+```
+
+**逐段拆解**:
+
+| 片段 | 含义 |
+|---|---|
+| `select` | 查询 |
+| `*` | 返回表里的全部列(这里就是 `id` 和 `str` 两列) |
+| `from foo` | 从 `foo` 表读取 |
+
+**预期结果**(来源文档展示):原文给出的结果是一个两列表格,内容如下。
+
+| id | str |
+|---|---|
+| 1 | tencent |
+| 2 | shenzhen |
+
+这里必须说清三点:
+
+- 本文没有实际执行这条查询,上表是**预期结果**,来源是原文展示。
+- `select *` 返回的是全部列,不是“全部数据”这个意义上的一切;本例恰好返回全部两行。
+- 这条语句**没有 `ORDER BY`**,所以不保证任何返回顺序。原文展示的 `1`、`2` 顺序只是那次展示的顺序,不是可以依赖的契约。需要固定顺序时必须显式写 `ORDER BY`。
+
+**前置条件**:`foo` 表已存在且有数据,即前两步都已成功。
+
+**来源文档展示**:原文在结果表格后给出 `(2 rows)`,表示返回两行。
+
+**常见误解**:
+
+- 以为没有 `ORDER BY` 也会按插入顺序返回。不保证。
+- 以为 `select *` 是推荐写法。列结构变化会让下游消费方受影响,正式查询建议写出需要的列名。
+- 以为查询结果为空的表和报错是一回事。空表返回 0 行,不是错误。
+
+**来源**:`docs/guide/01-quickstart.md`(固定提交 `4eaeba90188926ddf4da23b74775cdf150ffdfe8`),“使用”小节代码块中的第三条 `test=>` 语句。[在固定提交上查看](https://github.com/OpenTenBase/docs/blob/4eaeba90188926ddf4da23b74775cdf150ffdfe8/docs/guide/01-quickstart.md)
+
+## 把三条连起来看
+
+
+
+先看图的上半部分:客户端连到 CN,CN 再把语句下发到各个 DN,返回的数据由 CN 汇总给客户端。再看下半部分:三步是一条链,建表拿到表结构,插入才有地方放数据,查询才有内容可读;任何一步失败,后面两步都做不下去。
+
+图中的 `distribute by shard(id)` 只规定“由 `id` 计算落点”,具体落在哪个 DN 取决于分片规则和节点数量,所以图上没有把某一行画到某个具体节点。
+
+| 顺序 | 语句作用 | 依赖 | 来源文档展示的输出 |
+|---|---|---|---|
+| 第一步 | 建表 `foo`,两列,按 `id` 分布 | 已建库、建用户、切到 `test` 库 | `CREATE TABLE` |
+| 第二步 | 插入两行数据 | `foo` 已存在 | `COPY 2` |
+| 第三步 | 读出全部列 | `foo` 已存在且有数据 | 两行结果、`(2 rows)` |
+
+三步是严格的先后关系:建表失败,插入必然失败;插入失败,查询会得到空结果而不是两行。
+
+## 校验这三条语句有没有和原文走样
+
+`docs/guide/first-three-sql.md`(也就是本文)里的三条 SQL 是逐字引用原文的。为了避免日后维护时原文改了、伴读没跟上,仓库里带了一个离线校验工具:
+
+```
+python3 tools/sql_guide/check.py --root .
+```
+
+它只做一件事:检查本文中标记的三条语句与 `docs/guide/01-quickstart.md` 里的原文是否仍然逐字一致。它不联网、不连数据库、不执行任何 SQL。
+
+它的通过只说明**引用没有漂移**,不说明本文的技术解释正确,也不说明这三条语句在你的环境里能跑通。使用方法、退出码和已知限制见仓库内 `tools/sql_guide/README.md`。
+
+## 下一步读什么
+
+按下面的顺序继续,每条都说明了它适合解决什么问题:
+
+1. [快速入门](01-quickstart.md):回到原文,确认集群部署步骤和这三条语句的上下文。
+2. [应用接入指南](02-access.md):用 Java、C、shell、Python、PHP 或 Go 连接 OpenTenBase。
+3. [基本使用](03-basic-use.md):继续学建库、建表、数据导入和更复杂的查询。
+4. [用户管理](07-user-rights.md):理解本文示例里的 `test` 用户、库属主和权限之间的关系。
+5. [如何贡献 OpenTenBase](../contribution/how-to.md):发现文档问题或有改进建议时,提 issue 或 PR 的流程。
+
+## 这一页覆盖到哪里
+
+- 只讲上面这三条语句,不新增第四条,也不改写原文。
+- 输出只有两种来源:原文照录,或由原文推导的预期结果;没有在集群上实跑。
+- 性能调优、分布键怎么选、权限模型的细节,留给后面的章节。
+- 如果你的环境跑出来和这里写的不一样,欢迎按上面第 5 个入口反馈。
diff --git a/docs/guide/images/first-three-sql-flow.svg b/docs/guide/images/first-three-sql-flow.svg
new file mode 100644
index 0000000..a756c24
--- /dev/null
+++ b/docs/guide/images/first-three-sql-flow.svg
@@ -0,0 +1,68 @@
+
diff --git a/tools/sql_guide/README.md b/tools/sql_guide/README.md
new file mode 100644
index 0000000..233a358
--- /dev/null
+++ b/tools/sql_guide/README.md
@@ -0,0 +1,99 @@
+# SQL 伴读来源一致性校验
+
+这个目录里只有一个工具,用处很窄:检查 `docs/guide/first-three-sql.md` 中引用的三条 SQL,是否仍与 `docs/guide/01-quickstart.md` 里的原文逐字一致。
+
+## 为什么需要它
+
+伴读手册的三条语句是从快速入门里逐字复制的。只要原文改了、伴读没跟上,读者就会看到一份“看起来对、实际上是旧版本”的解释。人工复查容易漏,这个工具把这件事变成一条命令。
+
+它只回答“引用有没有走样”,不回答“解释对不对”,也不回答“SQL 能不能跑通”。
+
+## 用法
+
+在仓库根目录执行:
+
+```bash
+python3 tools/sql_guide/check.py --root .
+```
+
+输出示例:
+
+```
+sql-guide source consistency check
+ manifest: tools/sql_guide/examples.json
+ source: docs/guide/01-quickstart.md
+ guide: docs/guide/first-three-sql.md
+
+PASS create-foo-table guide:40 <- source:312
+PASS insert-foo-rows guide:77 <- source:314
+PASS select-foo-all guide:113 <- source:316
+
+summary: 3 examples, 3 passed, 0 failed
+```
+
+机器可读输出:
+
+```bash
+python3 tools/sql_guide/check.py --root . --format json
+```
+
+JSON 包含 `schema_version`、`summary`、`files`、`results`、`issues`。出现不一致时,`results[].expected` 与 `results[].actual` 会给出原文与伴读两侧的语句(超过 160 字符截断)。报告不包含任何其他文件内容,也不包含口令。
+
+## 退出码
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 配置合法,三个示例全部与来源一致 |
+| `1` | 文档缺失、定位失败、示例重复,或语句与来源不一致 |
+| `2` | 命令行参数错误,或 `examples.json` 缺失/不是合法 JSON/结构不合法 |
+
+`1` 与 `2` 的区分很重要:`1` 说明文档需要修,`2` 说明工具配置本身需要修。
+
+## 定位方式
+
+工具不依赖行号,因为行号会随文档编辑漂移。它依赖三件事:
+
+1. **来源侧**:`examples.json` 指定来源文件和每条语句的开头(`statement_prefix`)。工具只扫描代码围栏内部、以 `postgres=#` 或 `test=>` 提示符开头的行,提示符之后的部分才是语句。围栏内的命令行、元命令和执行输出都不会被当成语句。
+2. **伴读侧**:每条语句上方有一个 HTML 注释标记,标记与紧邻的 `sql` 围栏绑定:
+
+ ````markdown
+
+ ```sql
+ create table foo(id bigint, str text) distribute by shard(id);
+ ```
+ ````
+
+ 标记与围栏之间只允许空行。
+3. **唯一性**:每个 ID 在伴读里必须恰好出现一次,在来源里必须恰好匹配一条语句。匹配到两条以上时,工具报“歧义”并失败,不会自己挑一条。
+
+## 比对规则
+
+只做两件事:去掉已声明的提示符,去掉行首行尾空白。此外一律逐字比较:
+
+- 不折叠字符串内部的空格(`'shenzhen'` 与 `'shen zhen'` 视为不同);
+- 不忽略大小写;
+- 不做标点归一化,不替换全角/半角。
+
+宁可误报,也不做模糊匹配——模糊匹配会让“已经改坏了但看起来差不多”的情况通过。
+
+## 已知限制
+
+- 只支持本项目约定的三个单行示例,不是通用 Markdown 解析器,也不是 SQL 解析器。
+- 只识别 `postgres=#` 与 `test=>` 两种提示符,且必须在代码围栏内。
+- 只比较语句文本。语句的**技术解释**是否正确、能否在某个环境执行、性能如何,都不在检查范围内。
+- 不联网、不连接数据库、不执行任何 SQL、不修改仓库文件。
+- 通过检查不代表文档整体正确,只代表这三条引用没有漂移。
+
+## 测试
+
+```bash
+python3 -m unittest discover -s tools/sql_guide/tests -v
+```
+
+测试覆盖:正常通过、字符串字面量被改、内部空格差异、分号缺失、来源文件缺失、来源语句缺失、来源出现两条相同候选、伴读标记缺失/重复/后接非 SQL 围栏/多行代码块、清单非法 JSON/缺键/多键/版本不支持、JSON 报告可解析且计数一致、`--help` 返回 0,以及对本仓库真实文档的端到端检查。
+
+## 新增一个示例
+
+1. 在 `examples.json` 的 `examples` 里加一项:唯一 `id`,以及来源语句的开头 `statement_prefix`(要足够独特,避免匹配到多条)。
+2. 在伴读文档中,把语句放进以 `sql` 标注的代码围栏,并在围栏上一行加 ``。
+3. 运行 `python3 tools/sql_guide/check.py --root .`,确认新示例为 `PASS`。
diff --git a/tools/sql_guide/check.py b/tools/sql_guide/check.py
new file mode 100644
index 0000000..64a1c2f
--- /dev/null
+++ b/tools/sql_guide/check.py
@@ -0,0 +1,701 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Offline source-consistency checker for the first-three-SQL walkthrough.
+
+The checker answers exactly one question: are the three SQL statements quoted
+in docs/guide/first-three-sql.md still byte-for-byte identical to the three
+statements shown in docs/guide/01-quickstart.md?
+
+Deliberate limits:
+
+* standard library only, no third-party imports;
+* reads local files, never opens a network connection;
+* never executes SQL and never starts a database;
+* only understands the narrow Markdown subset described in README.md;
+* proves reference consistency, not technical correctness.
+
+Exit codes: 0 all examples match, 1 document/locator/mismatch problem,
+2 invalid CLI arguments or invalid manifest.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence, Tuple
+
+EXIT_OK = 0
+EXIT_MISMATCH = 1
+EXIT_USAGE = 2
+
+SCHEMA_VERSION = 1
+DEFAULT_MANIFEST = Path("tools") / "sql_guide" / "examples.json"
+
+# A fenced code block: at most three spaces of indent, then ``` or ~~~ (3+),
+# then an optional info string.
+FENCE_RE = re.compile(r"^(?P[ \t]{0,3})(?P`{3,}|~{3,})(?P.*)$")
+
+# The guide binds an ID to the next fenced block with this HTML comment:
+#
+MARKER_RE = re.compile(
+ r""
+)
+
+PREVIEW_LIMIT = 160
+
+
+class ManifestError(Exception):
+ """The manifest is missing, unreadable, or structurally invalid."""
+
+
+@dataclass(frozen=True)
+class CodeLine:
+ number: int
+ text: str
+
+
+@dataclass(frozen=True)
+class Fence:
+ start_index: int # 0-based index of the opening fence line
+ start_line: int # 1-based line number of the opening fence
+ info: str
+ lines: Tuple[CodeLine, ...]
+ closed: bool
+
+
+@dataclass(frozen=True)
+class Statement:
+ line: int
+ sql: str
+
+
+@dataclass(frozen=True)
+class Example:
+ id: str
+ statement_prefix: str
+
+
+@dataclass(frozen=True)
+class Manifest:
+ schema_version: int
+ source_document: str
+ guide_document: str
+ allowed_prompts: Tuple[str, ...]
+ guide_marker: str
+ examples: Tuple[Example, ...]
+
+
+@dataclass
+class Binding:
+ """One ID marker found in the guide, resolved to a SQL line when possible."""
+
+ line: int
+ sql: Optional[str] = None
+ sql_line: Optional[int] = None
+ problem: str = ""
+
+
+@dataclass
+class Result:
+ example_id: str
+ passed: bool
+ reason: str = ""
+ source_line: Optional[int] = None
+ guide_line: Optional[int] = None
+ expected: Optional[str] = None
+ actual: Optional[str] = None
+
+
+@dataclass
+class Report:
+ manifest_path: str
+ source_path: str
+ guide_path: str
+ results: List[Result] = field(default_factory=list)
+ issues: List[str] = field(default_factory=list)
+
+ @property
+ def total(self) -> int:
+ return len(self.results)
+
+ @property
+ def passed(self) -> int:
+ return sum(1 for item in self.results if item.passed)
+
+ @property
+ def failed(self) -> int:
+ return self.total - self.passed
+
+ def exit_code(self) -> int:
+ if self.issues or self.failed:
+ return EXIT_MISMATCH
+ return EXIT_OK
+
+
+# --------------------------------------------------------------------------
+# Markdown scanning
+# --------------------------------------------------------------------------
+
+
+def parse_fences(text: str) -> List[Fence]:
+ """Return every fenced code block in document order.
+
+ An unclosed fence runs to the end of the document; callers do not treat
+ that as an error, because the statements we look for are matched by
+ content, not by fence boundaries.
+ """
+ lines = text.splitlines()
+ fences: List[Fence] = []
+ index = 0
+ total = len(lines)
+
+ while index < total:
+ match = FENCE_RE.match(lines[index])
+ if match is None:
+ index += 1
+ continue
+
+ token = match.group("fence")
+ char = token[0]
+ length = len(token)
+ info = match.group("info").strip()
+ start_index = index
+ start_line = index + 1
+ index += 1
+
+ body: List[CodeLine] = []
+ closed = False
+ while index < total:
+ stripped = lines[index].strip()
+ if len(stripped) >= length and set(stripped) == {char}:
+ closed = True
+ index += 1
+ break
+ body.append(CodeLine(index + 1, lines[index]))
+ index += 1
+
+ fences.append(Fence(start_index, start_line, info, tuple(body), closed))
+
+ return fences
+
+
+def extract_source_statements(text: str, prompts: Sequence[str]) -> List[Statement]:
+ """Pull candidate statements out of fenced blocks in the source document.
+
+ Only lines that start with one of the declared prompts qualify. Everything
+ else inside a fence -- command output, meta-commands, shell lines -- is
+ ignored, so no output line can be mistaken for a statement.
+ """
+ ordered = sorted(prompts, key=len, reverse=True)
+ statements: List[Statement] = []
+
+ for fence in parse_fences(text):
+ for code_line in fence.lines:
+ stripped = code_line.text.strip()
+ for prompt in ordered:
+ if not stripped.startswith(prompt):
+ continue
+ sql = stripped[len(prompt) :].strip()
+ if sql:
+ statements.append(Statement(code_line.number, sql))
+ break
+
+ return statements
+
+
+def load_manifest(path: Path) -> Manifest:
+ """Read and validate the manifest, raising ManifestError on any defect."""
+ try:
+ raw = path.read_text(encoding="utf-8")
+ except FileNotFoundError:
+ raise ManifestError("manifest not found: {}".format(path)) from None
+ except OSError as exc:
+ raise ManifestError("manifest unreadable: {} ({})".format(path, exc)) from None
+
+ try:
+ data = json.loads(raw)
+ except json.JSONDecodeError as exc:
+ raise ManifestError(
+ "manifest is not valid JSON: {} (line {}, column {})".format(
+ path, exc.lineno, exc.colno
+ )
+ ) from None
+
+ if not isinstance(data, dict):
+ raise ManifestError("manifest root must be a JSON object")
+
+ allowed_keys = {
+ "schema_version",
+ "source_document",
+ "guide_document",
+ "allowed_prompts",
+ "guide_marker",
+ "examples",
+ }
+ unknown = sorted(set(data) - allowed_keys)
+ if unknown:
+ raise ManifestError(
+ "manifest has unsupported key(s): {}".format(", ".join(unknown))
+ )
+ missing = sorted(allowed_keys - set(data))
+ if missing:
+ raise ManifestError(
+ "manifest is missing key(s): {}".format(", ".join(missing))
+ )
+
+ version = data["schema_version"]
+ if not isinstance(version, int) or isinstance(version, bool):
+ raise ManifestError("schema_version must be an integer")
+ if version != SCHEMA_VERSION:
+ raise ManifestError(
+ "unsupported schema_version {}, expected {}".format(
+ version, SCHEMA_VERSION
+ )
+ )
+
+ for key in ("source_document", "guide_document", "guide_marker"):
+ if not isinstance(data[key], str) or not data[key].strip():
+ raise ManifestError("{} must be a non-empty string".format(key))
+
+ prompts = data["allowed_prompts"]
+ if not isinstance(prompts, list) or not prompts:
+ raise ManifestError("allowed_prompts must be a non-empty list")
+ for prompt in prompts:
+ if not isinstance(prompt, str) or not prompt:
+ raise ManifestError("every allowed_prompts entry must be a non-empty string")
+
+ raw_examples = data["examples"]
+ if not isinstance(raw_examples, list) or not raw_examples:
+ raise ManifestError("examples must be a non-empty list")
+
+ examples: List[Example] = []
+ seen_ids = set()
+ for position, item in enumerate(raw_examples, start=1):
+ if not isinstance(item, dict):
+ raise ManifestError("examples[{}] must be a JSON object".format(position))
+ extra = sorted(set(item) - {"id", "statement_prefix"})
+ if extra:
+ raise ManifestError(
+ "examples[{}] has unsupported key(s): {}".format(
+ position, ", ".join(extra)
+ )
+ )
+ example_id = item.get("id")
+ prefix = item.get("statement_prefix")
+ if not isinstance(example_id, str) or not example_id.strip():
+ raise ManifestError("examples[{}].id must be a non-empty string".format(position))
+ if not re.fullmatch(r"[A-Za-z0-9_.-]+", example_id):
+ raise ManifestError(
+ "examples[{}].id must match [A-Za-z0-9_.-]+, got {!r}".format(
+ position, example_id
+ )
+ )
+ if not isinstance(prefix, str) or not prefix.strip():
+ raise ManifestError(
+ "examples[{}].statement_prefix must be a non-empty string".format(position)
+ )
+ if example_id in seen_ids:
+ raise ManifestError("duplicate example id: {}".format(example_id))
+ seen_ids.add(example_id)
+ examples.append(Example(example_id, prefix))
+
+ return Manifest(
+ schema_version=version,
+ source_document=data["source_document"],
+ guide_document=data["guide_document"],
+ allowed_prompts=tuple(prompts),
+ guide_marker=data["guide_marker"],
+ examples=tuple(examples),
+ )
+
+
+def bind_guide(text: str, marker: str) -> Tuple[Dict[str, List[Binding]], List[str]]:
+ """Resolve every `` in the guide to the block after it.
+
+ A binding is only accepted when the marker is followed by nothing but blank
+ lines and then a single-line ```sql fence. Anything else is reported, never
+ silently skipped.
+ """
+ lines = text.splitlines()
+ fences = parse_fences(text)
+ bindings: Dict[str, List[Binding]] = {}
+ issues: List[str] = []
+
+ for index, raw in enumerate(lines):
+ match = MARKER_RE.search(raw)
+ if match is None or match.group("key") != marker:
+ continue
+
+ ident = match.group("ident")
+ marker_line = index + 1
+ fence = next((item for item in fences if item.start_index > index), None)
+ if fence is None:
+ bindings.setdefault(ident, []).append(
+ Binding(marker_line, problem="marker is not followed by a code fence")
+ )
+ continue
+
+ gap = [text_line for text_line in lines[index + 1 : fence.start_index] if text_line.strip()]
+ if gap:
+ bindings.setdefault(ident, []).append(
+ Binding(
+ marker_line,
+ problem="non-blank content between marker (line {}) and fence (line {})".format(
+ marker_line, fence.start_line
+ ),
+ )
+ )
+ continue
+
+ info_tokens = fence.info.split()
+ if not info_tokens or info_tokens[0].lower() != "sql":
+ bindings.setdefault(ident, []).append(
+ Binding(
+ marker_line,
+ problem="marker is not followed by a ```sql fence (fence at line {})".format(
+ fence.start_line
+ ),
+ )
+ )
+ continue
+
+ body = [item for item in fence.lines if item.text.strip()]
+ if len(body) != 1:
+ bindings.setdefault(ident, []).append(
+ Binding(
+ marker_line,
+ problem="expected exactly one SQL line in the fenced block at line {}, found {}".format(
+ fence.start_line, len(body)
+ ),
+ )
+ )
+ continue
+
+ if not fence.closed:
+ issues.append(
+ "fenced block at line {} is never closed".format(fence.start_line)
+ )
+
+ bindings.setdefault(ident, []).append(
+ Binding(marker_line, body[0].text.strip(), body[0].number)
+ )
+
+ return bindings, issues
+
+
+# --------------------------------------------------------------------------
+# Comparison
+# --------------------------------------------------------------------------
+
+
+def first_difference(left: str, right: str) -> int:
+ """Return the 0-based index of the first differing character."""
+ for position, (a, b) in enumerate(zip(left, right)):
+ if a != b:
+ return position
+ return min(len(left), len(right))
+
+
+def preview(value: str) -> str:
+ if len(value) <= PREVIEW_LIMIT:
+ return value
+ return value[: PREVIEW_LIMIT - 3] + "..."
+
+
+def evaluate(
+ manifest: Manifest,
+ source_text: str,
+ guide_text: str,
+) -> Tuple[List[Result], List[str]]:
+ statements = extract_source_statements(source_text, manifest.allowed_prompts)
+ bindings, issues = bind_guide(guide_text, manifest.guide_marker)
+ results: List[Result] = []
+
+ known_ids = {example.id for example in manifest.examples}
+ for ident, found in sorted(bindings.items()):
+ if ident not in known_ids:
+ for item in found:
+ issues.append(
+ "guide line {}: marker id {!r} is not declared in the manifest".format(
+ item.line, ident
+ )
+ )
+
+ for example in manifest.examples:
+ bound = bindings.get(example.id, [])
+
+ if not bound:
+ results.append(
+ Result(
+ example.id,
+ False,
+ "guide marker not found; expected ".format(
+ manifest.guide_marker, example.id
+ ),
+ )
+ )
+ continue
+
+ if len(bound) > 1:
+ lines = ", ".join(str(item.line) for item in bound)
+ results.append(
+ Result(
+ example.id,
+ False,
+ "guide marker appears {} times (lines {}); each id must appear once".format(
+ len(bound), lines
+ ),
+ )
+ )
+ continue
+
+ single = bound[0]
+ if single.problem or single.sql is None:
+ results.append(
+ Result(example.id, False, single.problem, guide_line=single.line)
+ )
+ continue
+
+ candidates = [
+ item for item in statements if item.sql.startswith(example.statement_prefix)
+ ]
+
+ if not candidates:
+ results.append(
+ Result(
+ example.id,
+ False,
+ "source statement not found; no prompted line starts with {!r}".format(
+ example.statement_prefix
+ ),
+ guide_line=single.sql_line,
+ actual=single.sql,
+ )
+ )
+ continue
+
+ if len(candidates) > 1:
+ lines = ", ".join(str(item.line) for item in candidates)
+ results.append(
+ Result(
+ example.id,
+ False,
+ "source statement is ambiguous: {} candidates with prefix {!r} at lines {}; "
+ "refusing to pick one".format(
+ len(candidates), example.statement_prefix, lines
+ ),
+ guide_line=single.sql_line,
+ actual=single.sql,
+ )
+ )
+ continue
+
+ source = candidates[0]
+ if source.sql == single.sql:
+ results.append(
+ Result(
+ example.id,
+ True,
+ source_line=source.line,
+ guide_line=single.sql_line,
+ )
+ )
+ continue
+
+ offset = first_difference(source.sql, single.sql)
+ results.append(
+ Result(
+ example.id,
+ False,
+ "statement differs from source at column {} (source line {})".format(
+ offset + 1, source.line
+ ),
+ source_line=source.line,
+ guide_line=single.sql_line,
+ expected=source.sql,
+ actual=single.sql,
+ )
+ )
+
+ return results, issues
+
+
+# --------------------------------------------------------------------------
+# Rendering
+# --------------------------------------------------------------------------
+
+
+def render_text(report: Report) -> str:
+ lines = [
+ "sql-guide source consistency check",
+ " manifest: {}".format(report.manifest_path),
+ " source: {}".format(report.source_path),
+ " guide: {}".format(report.guide_path),
+ "",
+ ]
+
+ for result in report.results:
+ if result.passed:
+ lines.append(
+ "PASS {:<22} guide:{} <- source:{}".format(
+ result.example_id, result.guide_line, result.source_line
+ )
+ )
+ continue
+
+ lines.append("FAIL {}".format(result.example_id))
+ lines.append(" reason: {}".format(result.reason))
+ if result.guide_line is not None:
+ lines.append(" guide: {}:{}".format(report.guide_path, result.guide_line))
+ if result.source_line is not None:
+ lines.append(" source: {}:{}".format(report.source_path, result.source_line))
+ if result.expected is not None:
+ lines.append(" expected: {}".format(result.expected))
+ if result.actual is not None:
+ lines.append(" actual: {}".format(result.actual))
+
+ if report.issues:
+ lines.append("")
+ lines.append("scope issues:")
+ for issue in report.issues:
+ lines.append(" - {}".format(issue))
+
+ lines.append("")
+ lines.append(
+ "summary: {} examples, {} passed, {} failed".format(
+ report.total, report.passed, report.failed
+ )
+ )
+ return "\n".join(lines)
+
+
+def render_json(report: Report) -> str:
+ payload = {
+ "schema_version": SCHEMA_VERSION,
+ "summary": {
+ "total": report.total,
+ "passed": report.passed,
+ "failed": report.failed,
+ "status": "pass" if report.total and not report.failed and not report.issues else "fail",
+ },
+ "files": {
+ "manifest": report.manifest_path,
+ "source": report.source_path,
+ "guide": report.guide_path,
+ },
+ "results": [
+ {
+ "id": result.example_id,
+ "status": "pass" if result.passed else "fail",
+ "reason": result.reason,
+ "source": {"path": report.source_path, "line": result.source_line},
+ "guide": {"path": report.guide_path, "line": result.guide_line},
+ "expected": preview(result.expected) if result.expected is not None else None,
+ "actual": preview(result.actual) if result.actual is not None else None,
+ }
+ for result in report.results
+ ],
+ "issues": list(report.issues),
+ }
+ return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+# --------------------------------------------------------------------------
+# Entry point
+# --------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(
+ prog="check.py",
+ description=(
+ "Compare the SQL statements quoted in the companion guide with the "
+ "statements in the source document. Offline, read-only, never executes SQL."
+ ),
+ )
+ parser.add_argument(
+ "--root",
+ default=".",
+ help="repository root that contains the manifest and both documents (default: .)",
+ )
+ parser.add_argument(
+ "--format",
+ choices=("text", "json"),
+ default="text",
+ dest="output_format",
+ help="report format (default: text)",
+ )
+ return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+ parser = build_parser()
+ args = parser.parse_args(argv)
+
+ root = Path(args.root)
+ if not root.is_dir():
+ print("error: --root is not a directory: {}".format(root), file=sys.stderr)
+ return EXIT_USAGE
+
+ manifest_path = (root / DEFAULT_MANIFEST).resolve()
+
+ try:
+ manifest = load_manifest(manifest_path)
+ except ManifestError as exc:
+ print("error: {}".format(exc), file=sys.stderr)
+ return EXIT_USAGE
+
+ source_path = (root / manifest.source_document).resolve()
+ guide_path = (root / manifest.guide_document).resolve()
+
+ source_text = ""
+ guide_text = ""
+ missing: List[str] = []
+ for label, path in (("source", source_path), ("guide", guide_path)):
+ try:
+ text = path.read_text(encoding="utf-8")
+ except FileNotFoundError:
+ missing.append("{} document not found: {}".format(label, manifest.source_document if label == "source" else manifest.guide_document))
+ continue
+ except OSError as exc:
+ missing.append(
+ "{} document unreadable: {} ({})".format(
+ label, path, exc
+ )
+ )
+ continue
+ if label == "source":
+ source_text = text
+ else:
+ guide_text = text
+
+ report = Report(
+ manifest_path=str(DEFAULT_MANIFEST),
+ source_path=manifest.source_document,
+ guide_path=manifest.guide_document,
+ )
+
+ if missing:
+ for example in manifest.examples:
+ report.results.append(
+ Result(example.id, False, "; ".join(missing))
+ )
+ else:
+ results, issues = evaluate(manifest, source_text, guide_text)
+ report.results = results
+ report.issues = issues
+
+ if args.output_format == "json":
+ print(render_json(report))
+ else:
+ print(render_text(report))
+
+ return report.exit_code()
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/sql_guide/examples.json b/tools/sql_guide/examples.json
new file mode 100644
index 0000000..52b2991
--- /dev/null
+++ b/tools/sql_guide/examples.json
@@ -0,0 +1,24 @@
+{
+ "schema_version": 1,
+ "source_document": "docs/guide/01-quickstart.md",
+ "guide_document": "docs/guide/first-three-sql.md",
+ "allowed_prompts": [
+ "postgres=#",
+ "test=>"
+ ],
+ "guide_marker": "sql-guide-example",
+ "examples": [
+ {
+ "id": "create-foo-table",
+ "statement_prefix": "create table foo"
+ },
+ {
+ "id": "insert-foo-rows",
+ "statement_prefix": "insert into foo values"
+ },
+ {
+ "id": "select-foo-all",
+ "statement_prefix": "select * from foo"
+ }
+ ]
+}
diff --git a/tools/sql_guide/tests/test_check.py b/tools/sql_guide/tests/test_check.py
new file mode 100644
index 0000000..ef9552b
--- /dev/null
+++ b/tools/sql_guide/tests/test_check.py
@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Tests for tools/sql_guide/check.py.
+
+Every case builds a tiny throw-away repository in a temporary directory, so the
+tests never touch the real documents and never need a database or a network
+connection. The last test class runs the checker against the real repository.
+
+Run with:
+ python3 -m unittest discover -s tools/sql_guide/tests -v
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+CHECK = Path(__file__).resolve().parents[1] / "check.py"
+REPO_ROOT = CHECK.parents[2]
+
+CREATE_SQL = "create table foo(id bigint, str text) distribute by shard(id);"
+INSERT_SQL = "insert into foo values(1, 'tencent'), (2, 'shenzhen');"
+SELECT_SQL = "select * from foo;"
+
+# ---------------------------------------------------------------------------
+# Fixtures modelled on docs/guide/01-quickstart.md and the companion guide.
+# ---------------------------------------------------------------------------
+
+SOURCE_HEADER = """# 快速入门
+
+## 使用
+* 连接到 CN 主节点执行 SQL
+
+```
+"""
+
+SOURCE_BODY = """$ psql -h ${{CoordinateNode_IP}} -p ${{CoordinateNode_PORT}} -U opentenbase -d postgres
+
+postgres=# create database test;
+CREATE DATABASE
+postgres=# \\c test test
+You are now connected to database "test" as user "test".
+test=> {create}
+CREATE TABLE
+test=> {insert}
+COPY 2
+test=> {select}
+ id | str
+----+----------
+ 1 | tencent
+ 2 | shenzhen
+(2 rows)
+
+```
+"""
+
+SOURCE_FIXTURE = SOURCE_HEADER + SOURCE_BODY.format(
+ create=CREATE_SQL, insert=INSERT_SQL, select=SELECT_SQL
+)
+
+
+def guide_block(example_id, sql):
+ return "\n```sql\n{}\n```\n".format(example_id, sql)
+
+
+GUIDE_HEADER = "# 读懂第一条 SQL:建表、插入与查询\n\n正文。\n\n"
+
+GUIDE_FIXTURE = (
+ GUIDE_HEADER
+ + guide_block("create-foo-table", CREATE_SQL)
+ + "\n"
+ + guide_block("insert-foo-rows", INSERT_SQL)
+ + "\n"
+ + guide_block("select-foo-all", SELECT_SQL)
+)
+
+MANIFEST_FIXTURE = {
+ "schema_version": 1,
+ "source_document": "docs/guide/01-quickstart.md",
+ "guide_document": "docs/guide/first-three-sql.md",
+ "allowed_prompts": ["postgres=#", "test=>"],
+ "guide_marker": "sql-guide-example",
+ "examples": [
+ {"id": "create-foo-table", "statement_prefix": "create table foo"},
+ {"id": "insert-foo-rows", "statement_prefix": "insert into foo values"},
+ {"id": "select-foo-all", "statement_prefix": "select * from foo"},
+ ],
+}
+
+
+class CheckerTestCase(unittest.TestCase):
+ """Base class: builds a fixture repository and runs the checker on it."""
+
+ def setUp(self):
+ self._tmp = tempfile.TemporaryDirectory()
+ self.root = Path(self._tmp.name)
+ (self.root / "tools" / "sql_guide").mkdir(parents=True)
+ (self.root / "docs" / "guide").mkdir(parents=True)
+ self.manifest_path = self.root / "tools" / "sql_guide" / "examples.json"
+ self.source_path = self.root / "docs" / "guide" / "01-quickstart.md"
+ self.guide_path = self.root / "docs" / "guide" / "first-three-sql.md"
+ self.write_manifest()
+ self.write_source(SOURCE_FIXTURE)
+ self.write_guide(GUIDE_FIXTURE)
+
+ def tearDown(self):
+ self._tmp.cleanup()
+
+ # -- fixture helpers ---------------------------------------------------
+
+ def write_manifest(self, payload=None, raw=None):
+ if raw is not None:
+ self.manifest_path.write_text(raw, encoding="utf-8")
+ return
+ data = MANIFEST_FIXTURE if payload is None else payload
+ self.manifest_path.write_text(
+ json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8"
+ )
+
+ def write_source(self, text):
+ self.source_path.write_text(text, encoding="utf-8")
+
+ def write_guide(self, text):
+ self.guide_path.write_text(text, encoding="utf-8")
+
+ def line_of(self, path, needle):
+ for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+ if needle in line:
+ return number
+ raise AssertionError("fixture does not contain {!r}".format(needle))
+
+ # -- runner ------------------------------------------------------------
+
+ def run_check(self, *extra):
+ completed = subprocess.run(
+ [sys.executable, str(CHECK), "--root", str(self.root), *extra],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ )
+ return completed.returncode, completed.stdout, completed.stderr
+
+
+class TestHappyPath(CheckerTestCase):
+ """T01: the three correct examples pass with exit code 0."""
+
+ def test_t01_all_examples_pass(self):
+ code, out, err = self.run_check()
+ self.assertEqual(code, 0, msg=err)
+ self.assertIn("summary: 3 examples, 3 passed, 0 failed", out)
+ self.assertEqual(out.count("PASS "), 3)
+ self.assertNotIn("FAIL", out)
+
+ def test_t01_reports_source_line_numbers(self):
+ _, out, _ = self.run_check()
+ self.assertIn("guide:{} <- source:{}".format(
+ self.line_of(self.guide_path, CREATE_SQL),
+ self.line_of(self.source_path, CREATE_SQL),
+ ), out)
+
+
+class TestMismatch(CheckerTestCase):
+ """T02 and T08: any byte-level drift is a failure with a precise location."""
+
+ def test_t02_changed_string_literal_fails(self):
+ changed = INSERT_SQL.replace("'shenzhen'", "'Shanghai'")
+ self.write_guide(GUIDE_FIXTURE.replace(INSERT_SQL, changed))
+ code, out, err = self.run_check()
+ self.assertEqual(code, 1, msg=err)
+ self.assertIn("FAIL insert-foo-rows", out)
+ self.assertIn("differs from source", out)
+ self.assertIn("summary: 3 examples, 2 passed, 1 failed", out)
+
+ def test_t02_failure_points_at_the_edited_line(self):
+ changed = INSERT_SQL.replace("'shenzhen'", "'Shanghai'")
+ self.write_guide(GUIDE_FIXTURE.replace(INSERT_SQL, changed))
+ _, out, _ = self.run_check()
+ expected_line = self.line_of(self.guide_path, changed)
+ self.assertIn("guide: docs/guide/first-three-sql.md:{}".format(expected_line), out)
+
+ def test_t08_internal_space_is_not_normalised(self):
+ spaced = INSERT_SQL.replace("'shenzhen'", "'shen zhen'")
+ self.write_guide(GUIDE_FIXTURE.replace(INSERT_SQL, spaced))
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("differs from source", out)
+
+ def test_t08_trailing_semicolon_is_compared(self):
+ self.write_guide(GUIDE_FIXTURE.replace(SELECT_SQL, "select * from foo"))
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("FAIL select-foo-all", out)
+
+
+class TestSourceLocating(CheckerTestCase):
+ """T03, T04, T05, T07: how the source document is located."""
+
+ def test_t03_missing_source_document(self):
+ self.source_path.unlink()
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("source document not found: docs/guide/01-quickstart.md", out)
+ self.assertIn("summary: 3 examples, 0 passed, 3 failed", out)
+
+ def test_t04_source_statement_missing(self):
+ self.write_source(SOURCE_FIXTURE.replace("test=> " + INSERT_SQL + "\n", ""))
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("source statement not found", out)
+ self.assertIn("FAIL insert-foo-rows", out)
+
+ def test_t05_two_matching_statements_are_ambiguous(self):
+ duplicated = SOURCE_FIXTURE.replace(
+ "test=> " + INSERT_SQL + "\n",
+ "test=> " + INSERT_SQL + "\ntest=> " + INSERT_SQL + "\n",
+ )
+ self.write_source(duplicated)
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("ambiguous", out)
+ self.assertIn("refusing to pick one", out)
+
+ def test_t07_output_lines_are_not_treated_as_statements(self):
+ # The fixture already mixes prompts, meta-commands and output; a clean
+ # pass proves that only prompted lines were read, and that the prefix
+ # match did not pick up "CREATE TABLE" or "COPY 2".
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 0)
+ self.assertNotIn("COPY 2", out)
+
+ def test_t07_statement_outside_a_fence_is_ignored(self):
+ injected = SOURCE_FIXTURE + "\ntest=> select * from foo;\n"
+ self.write_source(injected)
+ code, _, _ = self.run_check()
+ self.assertEqual(code, 0, msg="a prompt line outside a fence must not be scanned")
+
+
+class TestGuideBinding(CheckerTestCase):
+ """T06: the guide side of the binding must be unique and well formed."""
+
+ def test_t06_missing_marker(self):
+ self.write_guide(
+ GUIDE_FIXTURE.replace(guide_block("insert-foo-rows", INSERT_SQL), "")
+ )
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("guide marker not found", out)
+ self.assertIn("FAIL insert-foo-rows", out)
+
+ def test_t06_duplicate_marker(self):
+ block = guide_block("create-foo-table", CREATE_SQL)
+ self.write_guide(GUIDE_FIXTURE + "\n" + block)
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("appears 2 times", out)
+
+ def test_t06_marker_without_fence(self):
+ self.write_guide(
+ GUIDE_FIXTURE.replace(
+ guide_block("select-foo-all", SELECT_SQL),
+ "\n",
+ )
+ )
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("not followed by", out)
+
+ def test_t06_multi_line_block_is_rejected(self):
+ block = "\n```sql\n{}\n{}\n```\n".format(
+ CREATE_SQL, SELECT_SQL
+ )
+ self.write_guide(
+ GUIDE_FIXTURE.replace(guide_block("create-foo-table", CREATE_SQL), block)
+ )
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("expected exactly one SQL line", out)
+
+ def test_t06_unknown_marker_id_is_reported(self):
+ self.write_guide(
+ GUIDE_FIXTURE + "\n" + guide_block("not-in-manifest", SELECT_SQL)
+ )
+ code, out, _ = self.run_check()
+ self.assertEqual(code, 1)
+ self.assertIn("is not declared in the manifest", out)
+
+
+class TestManifestValidation(CheckerTestCase):
+ """T09: a broken manifest is a usage error, never a silent pass."""
+
+ def test_t09_invalid_json(self):
+ self.write_manifest(raw="{ not json ")
+ code, out, err = self.run_check()
+ self.assertEqual(code, 2)
+ self.assertIn("not valid JSON", err)
+ self.assertEqual(out, "")
+
+ def test_t09_missing_key(self):
+ payload = dict(MANIFEST_FIXTURE)
+ payload.pop("guide_marker")
+ self.write_manifest(payload)
+ code, _, err = self.run_check()
+ self.assertEqual(code, 2)
+ self.assertIn("missing key", err)
+
+ def test_t09_unknown_key(self):
+ payload = json.loads(json.dumps(MANIFEST_FIXTURE))
+ payload["unexpected"] = True
+ self.write_manifest(payload)
+ code, _, err = self.run_check()
+ self.assertEqual(code, 2)
+ self.assertIn("unsupported key", err)
+
+ def test_t09_unsupported_schema_version(self):
+ payload = json.loads(json.dumps(MANIFEST_FIXTURE))
+ payload["schema_version"] = 99
+ self.write_manifest(payload)
+ code, _, err = self.run_check()
+ self.assertEqual(code, 2)
+ self.assertIn("unsupported schema_version", err)
+
+ def test_t09_missing_manifest(self):
+ self.manifest_path.unlink()
+ code, _, err = self.run_check()
+ self.assertEqual(code, 2)
+ self.assertIn("manifest not found", err)
+
+ def test_t09_bad_root(self):
+ completed = subprocess.run(
+ [sys.executable, str(CHECK), "--root", str(self.root / "absent")],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ )
+ self.assertEqual(completed.returncode, 2)
+ self.assertIn("not a directory", completed.stderr)
+
+ def test_t09_bad_cli_argument(self):
+ completed = subprocess.run(
+ [sys.executable, str(CHECK), "--format", "yaml"],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ )
+ self.assertEqual(completed.returncode, 2)
+
+
+class TestJsonReport(CheckerTestCase):
+ """T10: the JSON report is machine readable and agrees with the text one."""
+
+ def test_t10_json_report_is_consistent(self):
+ code, out, _ = self.run_check("--format", "json")
+ self.assertEqual(code, 0)
+ payload = json.loads(out)
+ self.assertEqual(payload["schema_version"], 1)
+ self.assertEqual(payload["summary"]["total"], 3)
+ self.assertEqual(payload["summary"]["passed"], 3)
+ self.assertEqual(payload["summary"]["failed"], 0)
+ self.assertEqual(payload["summary"]["status"], "pass")
+ self.assertEqual(len(payload["results"]), 3)
+ self.assertEqual(payload["issues"], [])
+ for item in payload["results"]:
+ self.assertEqual(item["status"], "pass")
+ self.assertIsInstance(item["guide"]["line"], int)
+ self.assertIsInstance(item["source"]["line"], int)
+
+ def test_t10_json_reports_failures_without_dumping_files(self):
+ self.write_guide(GUIDE_FIXTURE.replace(INSERT_SQL, INSERT_SQL.replace("tencent", "tencnet")))
+ code, out, _ = self.run_check("--format", "json")
+ self.assertEqual(code, 1)
+ payload = json.loads(out)
+ self.assertEqual(payload["summary"]["failed"], 1)
+ failed = [item for item in payload["results"] if item["status"] == "fail"]
+ self.assertEqual(len(failed), 1)
+ self.assertIn("differs from source", failed[0]["reason"])
+
+ def test_t10_help_exits_zero(self):
+ completed = subprocess.run(
+ [sys.executable, str(CHECK), "--help"],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ )
+ self.assertEqual(completed.returncode, 0)
+ self.assertIn("--format", completed.stdout)
+
+
+class TestRealRepository(unittest.TestCase):
+ """The documents shipped in this repository must satisfy the checker."""
+
+ def test_real_repository_passes(self):
+ completed = subprocess.run(
+ [sys.executable, str(CHECK), "--root", str(REPO_ROOT)],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ )
+ self.assertEqual(completed.returncode, 0, msg=completed.stdout + completed.stderr)
+ self.assertIn("3 examples, 3 passed, 0 failed", completed.stdout)
+
+ def test_real_repository_json_passes(self):
+ completed = subprocess.run(
+ [sys.executable, str(CHECK), "--root", str(REPO_ROOT), "--format", "json"],
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ )
+ self.assertEqual(completed.returncode, 0, msg=completed.stdout + completed.stderr)
+ self.assertEqual(json.loads(completed.stdout)["summary"]["status"], "pass")
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)