@chengzhao-dev/dsh-quarto-book 0.6.1 → 0.6.3

package/skills/writing-quarto/scripts/testing-content.py

@@ -52,6 +52,71 @@ title: 入门
 先准备输入，再运行检查，最后对照输出。
 """
 
+TREE_CHAPTER = """---
+title: 入门
+---
+
+## 目标
+
+下面是工程目录树，行尾注释说明每个节点在工程里的用途，读者可以对照磁盘检查。
+
+```text
+├── apps/          #/ 终端程序
+│   └── cli.h       # 读入坐标
+└── tests/         #/ 单元测试
+```
+"""
+
+
+TREE_GAP_CHAPTER = """---
+title: 入门
+---
+
+## 目标
+
+下面是工程目录树，行尾注释说明每个节点在工程里的用途。
+
+```text
+├── lib/    #/ 源码
+└── main.c   # 入口
+```
+"""
+
+
+MERMAID_CHAPTER = """---
+title: 入门
+---
+
+## 目标
+
+下面是一张只画类型和边的类图，读者可以对照箭头理解类型之间的依赖。
+
+::: {.class-diagram}
+```{mermaid}
+%%| fig-cap: "类型 A 依赖类型 B。实线箭头从使用者指向被使用者。"
+%%{init: {"fontFamily": "LXGW Bright Medium, system-ui, sans-serif", "class": {"hideEmptyMembersBox": true}}}%%
+classDiagram
+  direction LR
+  class A
+  class B
+  A --> B
+```
+:::
+"""
+
+
+def long_tree_chapter(lines: int = 21) -> str:
+    rows = []
+    for index in range(lines):
+        prefix = f"├── file{index}.txt"
+        rows.append(prefix + " " * (20 - len(prefix)) + f"# 用途{index}")
+    tree = "\n".join(rows)
+    return (
+        "---\ntitle: 入门\n---\n\n## 目标\n\n"
+        "下面是工程目录树，行尾注释说明每个节点在工程里的用途。\n\n"
+        f"```text\n{tree}\n```\n"
+    )
+
 
 def run_case(tmp: Path) -> subprocess.CompletedProcess[str]:
     return subprocess.run(
@@ -97,6 +162,23 @@ def main() -> int:
                 failures.append(f"{name}: 输出缺少「{needle}」\n{output[:600]}")
 
     expect("合法样书", VALID_CHAPTER, 0, "OK")
+    expect(
+        "正文问答式讲解",
+        VALID_CHAPTER + "\n`Board` 只回答四类问题：坐标、满盘、三连与赢家。\n",
+        1, "问答式讲解",
+    )
+    expect(
+        "代码字面复述",
+        VALID_CHAPTER + "\n对应的代码里，`kBoardRows` 和 `kBoardCols` 都取 3。\n",
+        1, "代码字面复述",
+    )
+    expect(
+        "自造关系词",
+        VALID_CHAPTER + "\n`Game` 与 `Board` 之间的组成边表示什么？\n",
+        1, "自造关系词",
+    )
+    expect("标题口语化", VALID_CHAPTER.replace("## 目标", "## 自己走一局"), 1, "标题带人称")
+    expect("标题带行内代码", VALID_CHAPTER.replace("## 目标", "## 运行 `app`"), 1, "标题带行内代码")
     expect("正文 H1", VALID_CHAPTER.replace("## 目标", "# 目标"), 1, "正文出现 H1")
     expect("缺 title", VALID_CHAPTER.replace("title: 入门\n", ""), 1, "缺少 YAML frontmatter")
     expect(
@@ -126,6 +208,122 @@ def main() -> int:
         0, "OK",
     )
 
+    expect("目录树合格", TREE_CHAPTER, 0, "OK")
+    expect(
+        "标记后多空格",
+        TREE_CHAPTER.replace("# 读入坐标", "#  读入坐标"),
+        1, "标记后只留一个空格",
+    )
+    expect(
+        "注释文字未对齐",
+        TREE_CHAPTER.replace("#/ 终端程序", "#/  终端程序"),
+        1, "注释文字未对齐",
+    )
+    expect(
+        "树注释错列",
+        TREE_CHAPTER.replace("│   └── cli.h       #", "│   └── cli.h        #"),
+        1, "右移一列",
+    )
+    expect("节点与注释太近", TREE_GAP_CHAPTER, 1, "至少留四个空格")
+    expect(
+        "文件 # 未右移",
+        TREE_CHAPTER.replace("│   └── cli.h       #", "│   └── cli.h      #"),
+        1, "右移一列",
+    )
+    expect("树注释只写类别词", TREE_CHAPTER.replace("# 读入坐标", "# 头文件"), 1, "类别词")
+    expect(
+        "目录注释带冒号",
+        TREE_CHAPTER.replace("#/ 终端程序", "#/ 终端程序：打印棋盘"),
+        1, "目录注释只写这里装什么",
+    )
+    expect(
+        "目录注释过长",
+        TREE_CHAPTER.replace("#/ 终端程序", "#/ 终端程序与它的打印读入"),
+        1, "超过 16 列",
+    )
+    expect("树注释列了三项", TREE_CHAPTER.replace("# 读入坐标", "# 读入、打印与写快照"), 1, "压到 1 到 2 项")
+    expect("目录行缺少 #/", TREE_CHAPTER.replace("#/ 终端程序", "# 终端程序"), 1, "目录行的注释以 #/")
+    expect("文件行误写 #/", TREE_CHAPTER.replace("# 读入坐标", "#/ 读入坐标"), 1, "文件行的注释以 #")
+    expect("树行缺少注释", TREE_CHAPTER.replace("# 读入坐标", ""), 1, "缺少行尾注释")
+    expect(
+        "树注释过长",
+        TREE_CHAPTER.replace("# 读入坐标", "# 读入坐标并打印当前棋盘的全部状态"),
+        1, "超过 28 列",
+    )
+    expect("树行数过多", long_tree_chapter(), 1, "超过 20 行")
+
+    expect("类图合格", MERMAID_CHAPTER, 0, "OK")
+    expect(
+        "类图缺少图注",
+        MERMAID_CHAPTER.replace('%%| fig-cap: "类型 A 依赖类型 B。实线箭头从使用者指向被使用者。"\n', ""),
+        1, "fig-cap",
+    )
+    wrong_order = MERMAID_CHAPTER.replace(
+        '%%| fig-cap: "类型 A 依赖类型 B。实线箭头从使用者指向被使用者。"\n%%{init: ',
+        "%%{init: ",
+    ).replace(
+        "classDiagram",
+        '%%| fig-cap: "类型 A 依赖类型 B。实线箭头从使用者指向被使用者。"\nclassDiagram',
+        1,
+    )
+    expect("类图图注写在 init 之后", wrong_order, 1, "init 之前")
+    expect(
+        "类图缺少页面容器",
+        MERMAID_CHAPTER.replace("::: {.class-diagram}\n```{mermaid}", "```{mermaid}").replace(
+            "```\n:::", "```"
+        ),
+        1, ".class-diagram",
+    )
+    expect(
+        "类图缺少空成员配置",
+        MERMAID_CHAPTER.replace(', "class": {"hideEmptyMembersBox": true}', ""),
+        1, "hideEmptyMembersBox",
+    )
+    expect(
+        "类图有成员却用 LR",
+        MERMAID_CHAPTER.replace(
+            "  class B\n",
+            "  class B {\n    int value\n  }\n",
+        ),
+        1, "有成员却用 LR",
+    )
+    expect(
+        "类图类型过多",
+        MERMAID_CHAPTER.replace(
+            "  class B\n",
+            "  class B\n  class C\n  class D\n  class E\n  class F\n  class G\n  class H\n",
+        ),
+        1, "超过 6 个",
+    )
+    expect(
+        "类图成员行过长",
+        MERMAID_CHAPTER.replace(
+            "  class A\n",
+            "  class A {\n    +bool CompletesLine(CellPosition position, CellType cell_type) const\n  }\n",
+        ).replace("direction LR", "direction TB"),
+        1, "超过 40 列",
+    )
+    expect(
+        "单个类成员过多",
+        MERMAID_CHAPTER.replace(
+            "  class A\n",
+            "  class A {\n    int a\n    int b\n    int c\n    int d\n    int e\n    int f\n  }\n",
+        ).replace("direction LR", "direction TB"),
+        1, "超过 5 行",
+    )
+    expect(
+        "类图成员总数过多",
+        MERMAID_CHAPTER.replace(
+            "  class A\n  class B\n",
+            "  class A {\n    int a1\n    int a2\n    int a3\n  }\n"
+            "  class B {\n    int b1\n    int b2\n    int b3\n  }\n"
+            "  class C {\n    int c1\n    int c2\n    int c3\n  }\n"
+            "  class D {\n    int d1\n    int d2\n    int d3\n  }\n"
+            "  class E {\n    int e1\n    int e2\n    int e3\n  }\n",
+        ).replace("direction LR", "direction TB"),
+        1, "超过 14 行",
+    )
+
     with tempfile.TemporaryDirectory() as raw:
         root = Path(raw)
         make_book(root)
@@ -141,7 +339,7 @@ def main() -> int:
             print(f"  FAIL {line}")
         return 1
 
-    print("PASS：9 个用例全部通过")
+    print("PASS：36 个用例全部通过")
     return 0
 
 

package/skills/writing-quarto/scripts/verifying-content.py

@@ -4,6 +4,7 @@
 The checks encode the writing-quarto conventions: one chapter table in
 `_quarto.yml`, YAML titles instead of a body H1, ##/### heading depth, short
 paragraphs and sentences, declared code-fence languages, `{mermaid}` fences,
+class-diagram content budgets, directory-tree annotation columns and markers,
 and no placeholder text left in the prose.
 
 Project-specific rules are optional. If the book has
@@ -31,6 +32,7 @@ import argparse
 import json
 import re
 import sys
+import unicodedata
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -46,7 +48,29 @@ CHAPTER_NUMBER_RE = re.compile(r"第\s*\d+\s*章")
 PLACEHOLDER_RE = re.compile(r"^\s*TODO|待补|待定|TBD", re.IGNORECASE)
 TRAILING_SPACE_RE = re.compile(r"[ 	]+$")
 
+QA_PROSE_RE = re.compile(r"(?:它|只|都|分别|各自)回答|回答(?:四类|整局|这个|哪些|什么)")
+CODE_META_RE = re.compile(r"对应的代码")
+COINED_RELATION_RE = re.compile(r"(?:组成|依赖|继承|调用)边")
+
+TREE_CATEGORY_COMMENTS = frozenset({
+    "头文件", "源文件", "源码", "实现", "测试", "配置文件",
+    "构建脚本", "构建规则", "动态库", "可执行文件",
+})
+MAX_TREE_LINES = 20
+MAX_TREE_COMMENT_WIDTH = 28
+MAX_TREE_DIR_COMMENT_WIDTH = 16
+MIN_TREE_GAP = 4
+
+# 类图的内容预算。数字是版面判断，不是浏览器实测：正文栏约 840 px、字号
+# 15 px 时，6 个类型、14 行成员、单行 40 列仍能在栏内排下；超过就删内容或拆图。
+MAX_CLASS_DIAGRAM_TYPES = 6
+MAX_CLASS_DIAGRAM_MEMBERS = 14
+MAX_CLASS_MEMBERS = 5
+MAX_CLASS_MEMBER_COLUMNS = 40
+CLASS_RE = re.compile(r"^class\s+([A-Za-z_]\w*)\s*(\{)?")
+
 HEADING_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*$")
+HEADING_PERSONAL_RE = re.compile(r"自己|咱们|我们|你|您|跟我|试试|来看")
 FENCE_RE = re.compile(r"^\s*(```+|~~~+)\s*(\{[^}]*\}|[^\s`]*)?")
 LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
 CJK_RE = re.compile(r"[\u3400-\u9fff]")
@@ -158,6 +182,10 @@ def check_heading(path: Path, line: int, level: int, text: str, issues: list[Iss
         issues.append(Issue(path, line, "空标题"))
     if re.search(r"[。！？；]$", text):
         issues.append(Issue(path, line, "标题末尾带句读"))
+    if HEADING_PERSONAL_RE.search(text):
+        issues.append(Issue(path, line, "标题带人称或口语劝诱；改写成对象名或「动词 + 具体宾语」"))
+    if "`" in text:
+        issues.append(Issue(path, line, "标题带行内代码；文件名留给正文，标题写对象"))
 
 
 def check_prose_block(path: Path, start_line: int, text: str, issues: list[Issue]) -> None:
@@ -183,6 +211,220 @@ def check_prose_block(path: Path, start_line: int, text: str, issues: list[Issue
                 break
 
 
+def display_width(text: str) -> int:
+    return sum(2 if unicodedata.east_asian_width(char) in {"W", "F"} else 1 for char in text)
+
+
+def check_mermaid_block(path: Path, block: list[tuple[int, str]]) -> list[Issue]:
+    """Check a class diagram's content budget and direction."""
+    diagram_at = next((index for index, (_, raw) in enumerate(block) if "classDiagram" in raw), None)
+    if diagram_at is None:
+        return []
+
+    issues: list[Issue] = []
+    start_line = block[diagram_at][0]
+    text = "\n".join(raw for _, raw in block)
+    if "hideEmptyMembersBox" not in text:
+        issues.append(Issue(
+            path, start_line,
+            "类图块首缺少 hideEmptyMembersBox 配置；空类会画出空成员栏",
+        ))
+    caption_at = next(
+        (index for index, (_, raw) in enumerate(block) if raw.lstrip().startswith("%%| fig-cap:")),
+        None,
+    )
+    init_at = next(
+        (index for index, (_, raw) in enumerate(block) if raw.lstrip().startswith("%%{init")),
+        None,
+    )
+    if caption_at is None:
+        issues.append(Issue(
+            path, start_line,
+            "类图缺少 fig-cap 图注；线型与读图约定应写在图注里",
+        ))
+    elif init_at is not None and caption_at > init_at:
+        issues.append(Issue(
+            path, block[caption_at][0],
+            "fig-cap 必须写在 init 之前；写在 init 之后会原样渲染成 Mermaid 注释",
+        ))
+
+    classes: dict[str, list[tuple[int, str]]] = {}
+    order: list[str] = []
+    direction = ""
+    direction_line = start_line
+    current: str | None = None
+    for number, raw in block[diagram_at:]:
+        line = raw.strip()
+        if not line or line.startswith("%%"):
+            continue
+        if line.startswith("direction "):
+            direction = line.split(None, 1)[1].strip().upper()
+            direction_line = number
+            continue
+        match = CLASS_RE.match(line)
+        if match:
+            name = match.group(1)
+            if name not in classes:
+                classes[name] = []
+                order.append(name)
+            current = name if "{" in line else None
+            continue
+        if current is None:
+            continue
+        if line == "}":
+            current = None
+            continue
+        if line.startswith("<<") and line.endswith(">>"):
+            continue
+        classes[current].append((number, line))
+
+    total_members = sum(len(lines) for lines in classes.values())
+    if len(order) > MAX_CLASS_DIAGRAM_TYPES:
+        issues.append(Issue(
+            path, start_line,
+            f"类图有 {len(order)} 个类型，超过 {MAX_CLASS_DIAGRAM_TYPES} 个；删节点或拆图",
+        ))
+    if total_members > MAX_CLASS_DIAGRAM_MEMBERS:
+        issues.append(Issue(
+            path, start_line,
+            f"类图成员共 {total_members} 行，超过 {MAX_CLASS_DIAGRAM_MEMBERS} 行；只留本章连边要用的成员",
+        ))
+    for name in order:
+        members = classes[name]
+        if len(members) > MAX_CLASS_MEMBERS:
+            issues.append(Issue(
+                path, members[MAX_CLASS_MEMBERS][0],
+                f"类 {name} 有 {len(members)} 行成员，超过 {MAX_CLASS_MEMBERS} 行；删到本章要用的",
+            ))
+        for number, line in members:
+            width = display_width(line)
+            if width > MAX_CLASS_MEMBER_COLUMNS:
+                issues.append(Issue(
+                    path, number,
+                    f"类图成员行 {width} 列，超过 {MAX_CLASS_MEMBER_COLUMNS} 列；参数省略类型名",
+                ))
+    if direction == "LR" and total_members:
+        issues.append(Issue(
+            path, direction_line,
+            "类图有成员却用 LR；改成 TB，让类型上下排",
+        ))
+    return issues
+
+
+def check_mermaid_wrapper(path: Path, lines: list[str], block: list[tuple[int, str]]) -> list[Issue]:
+    """Check a class diagram sits in the .class-diagram scroll container."""
+    if not any("classDiagram" in raw for _, raw in block):
+        return []
+    start = block[0][0]
+    index = start - 2
+    if 0 <= index < len(lines) and lines[index].lstrip().startswith("```"):
+        index -= 1
+    while index >= 0 and not lines[index].strip():
+        index -= 1
+    if index < 0 or ".class-diagram" not in lines[index]:
+        return [Issue(
+            path, start,
+            "类图缺少 .class-diagram 包裹；无法应用类图的宽度与居中规则",
+        )]
+    return []
+
+
+def check_tree_block(path: Path, block: list[tuple[int, str]]) -> list[Issue]:
+    """Check tree glyph lines: size, marker, width, items, and two marker columns."""
+    tree_lines = [(number, raw) for number, raw in block if "├──" in raw or "└──" in raw]
+    if len(tree_lines) < 2:
+        return []
+    issues: list[Issue] = []
+    if len(tree_lines) > MAX_TREE_LINES:
+        issues.append(Issue(
+            path, tree_lines[0][0],
+            f"树有 {len(tree_lines)} 行，超过 {MAX_TREE_LINES} 行；只留本章会点名的文件",
+        ))
+    dirs: list[tuple[int, int]] = []
+    files: list[tuple[int, int]] = []
+    text_columns: list[tuple[int, int]] = []
+    for number, raw in tree_lines:
+        hash_index = raw.find("#")
+        if hash_index < 0:
+            issues.append(Issue(path, number, "树行缺少行尾注释"))
+            continue
+        prefix = raw[:hash_index]
+        entry = prefix.rstrip()
+        if display_width(prefix) - display_width(entry) < MIN_TREE_GAP:
+            issues.append(Issue(path, number, "节点与注释之间至少留四个空格"))
+        rest = raw[hash_index:]
+        marker = "#/" if rest.startswith("#/") else "#"
+        after = rest[len(marker):]
+        if not after.startswith(" ") or (len(after) > 1 and after[1] == " "):
+            issues.append(Issue(path, number, "标记后只留一个空格"))
+        is_directory = entry.endswith("/")
+        if is_directory and marker != "#/":
+            issues.append(Issue(path, number, "目录行的注释以 #/ 开头"))
+        if not is_directory and marker == "#/":
+            issues.append(Issue(path, number, "文件行的注释以 # 开头"))
+        comment = after.strip()
+        if not comment:
+            issues.append(Issue(path, number, "树行注释为空"))
+            continue
+        if is_directory:
+            if "：" in comment or ":" in comment:
+                issues.append(Issue(
+                    path, number,
+                    "目录注释只写这里装什么，不加冒号或子项职责",
+                ))
+            if "、" in comment:
+                issues.append(Issue(
+                    path, number,
+                    "目录注释不列清单，用名词短语",
+                ))
+            if display_width(comment) > MAX_TREE_DIR_COMMENT_WIDTH:
+                issues.append(Issue(
+                    path, number,
+                    f"目录注释 {display_width(comment)} 列，超过 {MAX_TREE_DIR_COMMENT_WIDTH} 列；只留名词短语",
+                ))
+        else:
+            if display_width(comment) > MAX_TREE_COMMENT_WIDTH:
+                issues.append(Issue(
+                    path, number,
+                    f"注释 {display_width(comment)} 列，超过 {MAX_TREE_COMMENT_WIDTH} 列；缩成短名词短语",
+                ))
+            elif comment.rstrip("：:") in TREE_CATEGORY_COMMENTS:
+                issues.append(Issue(path, number, f"注释只写类别词「{comment}」；写对象与用途"))
+            separators = comment.count("、") + len(re.findall(r"(?<!参)与", comment))
+            if separators > 1:
+                issues.append(Issue(
+                    path, number, f"注释列了 {separators + 1} 项；压到 1 到 2 项",
+                ))
+        column = display_width(prefix)
+        if is_directory:
+            dirs.append((number, column))
+        else:
+            files.append((number, column))
+        text_columns.append((number, column + len(marker) + len(after) - len(after.lstrip(" "))))
+    if dirs:
+        dir_column = dirs[0][1]
+        if any(column != dir_column for _, column in dirs[1:]):
+            issues.append(Issue(path, dirs[0][0], "目录 #/ 未对齐"))
+        for number, column in files:
+            if column != dir_column + 1:
+                issues.append(Issue(
+                    path, number,
+                    f"文件 # 应比目录 # 右移一列（目录在 {dir_column}，文件在 {column}）",
+                ))
+                break
+    elif files:
+        file_column = files[0][1]
+        if any(column != file_column for _, column in files[1:]):
+            issues.append(Issue(path, files[0][0], "文件 # 未对齐"))
+    if text_columns:
+        text_column = text_columns[0][1]
+        for number, column in text_columns[1:]:
+            if column != text_column:
+                issues.append(Issue(path, number, "注释文字未对齐"))
+                break
+    return issues
+
+
 def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> list[Issue]:
     issues: list[Issue] = []
     text = read_text(path)
@@ -198,6 +440,9 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
     in_fence = False
     fence_lang = ""
     fence_start = 0
+    fence_lines: list[tuple[int, str]] = []
+    fence_blocks: list[list[tuple[int, str]]] = []
+    mermaid_blocks: list[list[tuple[int, str]]] = []
     paragraph: list[str] = []
     paragraph_start = 0
 
@@ -215,6 +460,7 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
                 in_fence = True
                 fence_start = number
                 fence_lang = (fence.group(2) or "").strip()
+                fence_lines = []
                 if not fence_lang:
                     issues.append(Issue(path, number, "代码围栏未声明语言"))
                 elif fence_lang == "mermaid":
@@ -226,11 +472,17 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
                         pass
             else:
                 in_fence = False
+                if fence_lines:
+                    fence_blocks.append(fence_lines)
+                    if "mermaid" in fence_lang:
+                        mermaid_blocks.append(fence_lines)
+                    fence_lines = []
             continue
 
         if in_fence:
             if "\t" in raw:
                 issues.append(Issue(path, number, "代码含制表符（改用空格）"))
+            fence_lines.append((number, raw))
             continue
 
         heading = HEADING_RE.match(raw)
@@ -263,6 +515,13 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
 
     flush_paragraph()
 
+    for block in fence_blocks:
+        issues.extend(check_tree_block(path, block))
+
+    for block in mermaid_blocks:
+        issues.extend(check_mermaid_block(path, block))
+        issues.extend(check_mermaid_wrapper(path, lines, block))
+
     for index, raw in enumerate(lines, start=1):
         match = LINK_RE.search(raw)
         if not match:
@@ -291,6 +550,28 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
                 issues.append(Issue(path, index, f"项目禁用词「{term}」"))
                 break
 
+    for index, raw in enumerate(lines, start=1):
+        if raw.lstrip().startswith(("```", "    ")):
+            continue
+        match = QA_PROSE_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                f"问答式讲解「{match.group(0)}」；改成返回值、判断结果或直接陈述",
+            ))
+        match = CODE_META_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                f"代码字面复述「{match.group(0)}」；改成围栏没给出的行为或约束",
+            ))
+        match = COINED_RELATION_RE.search(raw)
+        if match:
+            issues.append(Issue(
+                path, index,
+                f"自造关系词「{match.group(0)}」；用组成、调用、依赖、继承等通行词",
+            ))
+
     required = project.get("chapter_titles", {}).get(rel)
     if required:
         title = parse_frontmatter_title(front)