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

package/skills/writing-quarto/scripts/checking-dom.py

@@ -240,7 +240,8 @@ def check_contracts(book_dir, htmls, css_pairs, root=None, require_favicon=True)
     ))
 
     # ---------- C1 复制按钮可见性 ----------
-    sibling_ok = False
+    checked = 0
+    bad = 0
     scaffold_pages = 0
     for path, tree, _rels in htmls:
         scaffolds = [n for n in walk(tree) if SCAFFOLD in n.classes]
@@ -249,20 +250,23 @@ def check_contracts(book_dir, htmls, css_pairs, root=None, require_favicon=True)
         scaffold_pages += 1
         for sc in scaffolds:
             code = [c for c in sc.children if c.tag == "div" and SRCODE in c.classes]
+            if not code:
+                continue
+            checked += 1
             btns = [c for c in sc.children if c.tag == "button" and COPY_BTN in c.classes]
-            if code and btns and not any(is_descendant(b, code[0]) for b in btns):
-                sibling_ok = True
+            if not btns or any(is_descendant(b, code[0]) for b in btns):
+                bad += 1
     hover_rule = any(
         ".%s:hover .%s" % (SCAFFOLD, COPY_BTN) in css for _, css in css_pairs
     )
     stale_rule = any(
         "div.%s:hover .%s" % (SRCODE, COPY_BTN) in css for _, css in css_pairs
     )
-    c1 = sibling_ok and hover_rule and not stale_rule
+    c1 = checked > 0 and bad == 0 and hover_rule and not stale_rule
     results.append((
         "C1", "复制按钮 hover 可见（兄弟 DOM + scaffold 选择器）", c1,
-        "pages=%d sibling=%s hover-rule=%s%s"
-        % (scaffold_pages, sibling_ok, hover_rule, " stale-rule!" if stale_rule else ""),
+        "pages=%d checked=%d bad=%d hover-rule=%s%s"
+        % (scaffold_pages, checked, bad, hover_rule, " stale-rule!" if stale_rule else ""),
         [
             "产物中 button.%s 必须与 div.%s 同为 .%s 的直接子元素" % (COPY_BTN, SRCODE, SCAFFOLD),
             "CSS 必须含 .%s:hover .%s（不能停留在 div.%s:hover 的后代写法）"
@@ -535,6 +539,8 @@ def main():
     args = parser.parse_args()
 
     book_dir = Path(args.book_dir)
+    if not book_dir.is_absolute():
+        book_dir = Path(args.root) / book_dir
     if not book_dir.is_dir():
         print("MISS 产物目录不存在：%s（请先运行 quarto render）" % book_dir)
         return 2

package/skills/writing-quarto/scripts/checking-links.py

@@ -20,8 +20,13 @@ import sys
 from pathlib import Path
 
 LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
+REF_USE_RE = re.compile(r"(!?)\[([^\]]*)\]\[([^\]]*)\]")
+REF_DEF_RE = re.compile(r"^ {0,3}\[([^\]]+)\]:\s*(?:<([^>\s]+)>|(\S+))")
+INLINE_CODE_RE = re.compile(r"`+[^`]*`+")
 HTML_LINK_RE = re.compile(r"<(?:a|img)\b[^>]*\b(?:href|src)=\"([^\"]+)\"", re.IGNORECASE)
+FENCE_RE = re.compile(r"^\s*(```+|~~~+)")
 SKIP_PREFIXES = ("http://", "https://", "mailto:", "tel:", "data:", "#", "//")
+SKIP_DIRS = {".git", ".cache", ".quarto", "_book", "_freeze", "_site", "build", "node_modules", "temp"}
 
 
 def collect_sources(root: Path, paths: list[str]) -> list[Path]:
@@ -41,17 +46,57 @@ def collect_sources(root: Path, paths: list[str]) -> list[Path]:
     return sorted(
         path for path in found
         if not any(
-            part in {".git", ".cache", ".quarto", "_book", "_freeze", "_site", "build", "node_modules", "temp"}
-            for part in path.parts
+            part in SKIP_DIRS
+            for part in path.relative_to(root).parts
         )
     )
 
 
-def link_targets(text: str):
-    for match in LINK_RE.finditer(text):
-        yield match.group(1)
-    for match in HTML_LINK_RE.finditer(text):
-        yield match.group(1)
+def normalize_label(label: str) -> str:
+    return re.sub(r"\s+", " ", label.strip()).casefold()
+
+
+def collect_definitions(text: str) -> dict[str, tuple[int, str]]:
+    """收集引用式链接定义 `[label]: target`；围栏内的定义不算。"""
+    definitions: dict[str, tuple[int, str]] = {}
+    in_fence = False
+    for number, line in enumerate(text.splitlines(), start=1):
+        if FENCE_RE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        match = REF_DEF_RE.match(line)
+        if not match:
+            continue
+        label = normalize_label(match.group(1))
+        target = match.group(2) or match.group(3) or ""
+        if label and label not in definitions:
+            definitions[label] = (number, target)
+    return definitions
+
+
+def iter_links(text: str, definitions: dict[str, tuple[int, str]]):
+    in_fence = False
+    for number, line in enumerate(text.splitlines(), start=1):
+        if FENCE_RE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence or REF_DEF_RE.match(line):
+            continue
+        # 行内代码里的方括号不是链接；先抹掉，避免把示例当引用。
+        visible = INLINE_CODE_RE.sub(lambda match: " " * len(match.group(0)), line)
+        for match in LINK_RE.finditer(visible):
+            yield number, match.group(1), None
+        for match in REF_USE_RE.finditer(visible):
+            label = match.group(3) or match.group(2)
+            key = normalize_label(label)
+            if not key:
+                continue
+            definition = definitions.get(key)
+            yield number, definition[1] if definition else None, label
+        for match in HTML_LINK_RE.finditer(visible):
+            yield number, match.group(1), None
 
 
 def main() -> int:
@@ -72,13 +117,25 @@ def main() -> int:
         return 2
 
     sources = collect_sources(root, args.paths)
-    broken: list[tuple[str, str, str]] = []
+    if not sources:
+        print("失败  没有可检查的 Markdown/Quarto 源文件", file=sys.stderr)
+        return 2
+    broken: list[tuple[str, int, str, str]] = []
     checked = 0
 
     for source in sources:
-        text = source.read_text(encoding="utf-8", errors="replace")
+        try:
+            text = source.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            print(f"失败  {source} 不是合法 UTF-8：{exc}", file=sys.stderr)
+            return 1
         rel = source.relative_to(root).as_posix()
-        for raw in link_targets(text):
+        definitions = collect_definitions(text)
+        for number, raw, label in iter_links(text, definitions):
+            if raw is None:
+                checked += 1
+                broken.append((rel, number, f"[{label}]", "引用标签未定义"))
+                continue
             target = raw.strip()
             if not target or target.startswith(SKIP_PREFIXES):
                 continue
@@ -91,7 +148,7 @@ def main() -> int:
             candidates = [source.parent / clean, root / clean]
             if any(candidate.exists() for candidate in candidates):
                 continue
-            broken.append((rel, target, "目标不存在"))
+            broken.append((rel, number, target, "目标不存在"))
 
     print(f"扫描 {len(sources)} 个文件，检查 {checked} 条本地链接。")
     if not broken:
@@ -99,8 +156,8 @@ def main() -> int:
         return 0
 
     print(f"发现 {len(broken)} 条断链：")
-    for rel, target, reason in broken[:80]:
-        print(f"  {rel} -> {target}（{reason}）")
+    for rel, number, target, reason in broken[:80]:
+        print(f"  {rel}:{number} -> {target}（{reason}）")
     return 1
 
 

package/skills/writing-quarto/scripts/checking-names.py

@@ -33,7 +33,7 @@ EXCLUDE_DIR_SUFFIXES = ("_files",)
 
 TOOL_FIXED_NAMES = {
     "CMakeLists.txt", "_quarto.yml", "_quarto.yaml", "SKILL.md", "AGENTS.md",
-    "README.md", "README.en.md", "LICENSE", "CONTRIBUTING.md",
+    "README.md", "README.en.md", "LICENSE", "OFL.txt", "CONTRIBUTING.md",
     ".editorconfig", ".gitignore", ".gitattributes", "openai.yaml",
     "package.json", "package-lock.json", "pnpm-lock.yaml", "tsconfig.json",
 }
@@ -56,6 +56,8 @@ def name_form_error(name: str) -> str | None:
     if " " in name:
         return "含空格"
     if "-" not in name:
+        if not all(ch.islower() or ch.isdigit() or ch == "." for ch in name):
+            return "含非小写字符"
         return None
     parts = name.split("-")
     if any(part == "" for part in parts):

package/skills/writing-quarto/scripts/checking-output.py

@@ -7,7 +7,7 @@
 不在本检查范围内。
 
 用法：python checking-output.py [--book-dir _book] [--root .] [--require-sitemap]
-退出码：0 = 通过；1 = 存在阻塞问题。
+退出码：0 = 通过；1 = 存在阻塞问题；2 = 渲染产物目录或首页缺失。
 """
 
 import argparse
@@ -37,12 +37,12 @@ def main() -> int:
     index = book / "index.html"
     if not index.is_file():
         print(f"缺少产物首页 {book.as_posix()}/index.html：确认在仓库根目录渲染")
-        return 1
+        return 2
 
     html_files = sorted(book.rglob("*.html"))
     if not html_files:
         print(f"{book.as_posix()} 下没有任何 HTML 文件")
-        return 1
+        return 2
 
     for path in html_files:
         rel = path.relative_to(book).as_posix()

package/skills/writing-quarto/scripts/checking-prose.py

@@ -42,13 +42,13 @@ class Issue:
     message: str
 
 
-def strip_frontmatter(text: str) -> str:
+def split_frontmatter(text: str) -> tuple[int, str]:
     lines = text.splitlines()
     if lines and lines[0].strip() == "---":
         for index in range(1, len(lines)):
             if lines[index].strip() == "---":
-                return "\n".join(lines[index + 1 :])
-    return text
+                return index + 1, "\n".join(lines[index + 1 :])
+    return 0, text
 
 
 def mask_links_and_tags(line: str) -> str:
@@ -98,11 +98,11 @@ def check_line(path: str, number: int, line: str) -> list[Issue]:
 
 
 def scan_file(root: Path, path: Path) -> list[Issue]:
-    text = path.read_text(encoding="utf-8", errors="replace")
-    text = strip_frontmatter(text)
+    text = path.read_text(encoding="utf-8")
+    offset, body = split_frontmatter(text)
     issues: list[Issue] = []
     in_fence = False
-    for number, line in enumerate(text.splitlines(), start=1):
+    for number, line in enumerate(body.splitlines(), start=offset + 1):
         if FENCE.match(line):
             in_fence = not in_fence
             continue
@@ -135,7 +135,11 @@ def main() -> int:
 
     issues: list[Issue] = []
     for path in collect_files(root):
-        issues.extend(scan_file(root, path))
+        try:
+            issues.extend(scan_file(root, path))
+        except UnicodeDecodeError as exc:
+            print(f"失败  {path} 不是合法 UTF-8：{exc}", file=sys.stderr)
+            return 1
 
     if args.json:
         print(

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

@@ -68,6 +68,36 @@ title: 入门
 """
 
 
+HTML_FIGURE_BAD = """---
+title: 入门
+---
+
+## 目标
+
+这一章说明一个可以重复验证的目标。
+
+```{=html}
+<svg class="coords-grid" role="img" aria-label="棋盘坐标。"><rect width="10" height="10"/></svg>
+```
+"""
+
+HTML_FIGURE_GOOD = """---
+title: 入门
+---
+
+## 目标
+
+这一章说明一个可以重复验证的目标。
+
+```{=html}
+<figure class="book-figure">
+<svg class="coords-grid" role="img" aria-label="棋盘坐标。"><rect width="10" height="10"/></svg>
+<figcaption>棋盘坐标图：3 行 3 列。</figcaption>
+</figure>
+```
+"""
+
+
 TREE_GAP_CHAPTER = """---
 title: 入门
 ---
@@ -139,8 +169,11 @@ def main() -> int:
         pass
 
     failures: list[str] = []
+    passed_cases = 0
 
     def expect(name: str, chapter: str, code: int, needle: str, project: bool = False) -> None:
+        nonlocal passed_cases
+        passed_cases += 1
         with tempfile.TemporaryDirectory() as raw:
             root = Path(raw)
             make_book(root, chapter)
@@ -177,6 +210,31 @@ def main() -> int:
         VALID_CHAPTER + "\n`Game` 与 `Board` 之间的组成边表示什么？\n",
         1, "自造关系词",
     )
+    expect(
+        "类型承载",
+        VALID_CHAPTER + "\n坐标由 `CellPosition` 承载，取值由 `CellType` 承载。\n",
+        1, "承载",
+    )
+    expect(
+        "小节导航",
+        VALID_CHAPTER + "\n下一节说明落子顺序。\n",
+        1, "小节导航",
+    )
+    expect(
+        "拉链句",
+        VALID_CHAPTER + "\n两个类型分别交给坐标与取值。\n",
+        1, "拉链句",
+    )
+    duplicate_link = (
+        "https://github.com/chengzhao-dev/cpp-board-games/blob/main/"
+        "games/tictactoe/tictactoe/include/board.h"
+    )
+    expect(
+        "同章重复文件链接",
+        VALID_CHAPTER
+        + f"\n[board.h]({duplicate_link})\n\n[board.h]({duplicate_link})\n",
+        1, "同章重复文件链接",
+    )
     expect("标题口语化", VALID_CHAPTER.replace("## 目标", "## 自己走一局"), 1, "标题带人称")
     expect("标题带行内代码", VALID_CHAPTER.replace("## 目标", "## 运行 `app`"), 1, "标题带行内代码")
     expect("正文 H1", VALID_CHAPTER.replace("## 目标", "# 目标"), 1, "正文出现 H1")
@@ -196,6 +254,12 @@ def main() -> int:
         "---\ntitle: 入门\n---\n\n## 目标\n\n```\nprint(1)\n```\n",
         1, "未声明语言",
     )
+    expect(
+        "相邻围栏缺少空行",
+        "---\ntitle: 入门\n---\n\n## 目标\n\n"
+        "```text\na\n```\n```text\nb\n```\n",
+        1, "DOC-E11",
+    )
     expect(
         "项目禁用词生效",
         "---\ntitle: 入门\n---\n\n## 目标\n\n棋盘格子按行列编号，程序读取当前状态。\n",
@@ -209,6 +273,8 @@ def main() -> int:
     )
 
     expect("目录树合格", TREE_CHAPTER, 0, "OK")
+    expect("原生 SVG 缺图注", HTML_FIGURE_BAD, 1, "figcaption")
+    expect("原生 SVG 图注合格", HTML_FIGURE_GOOD, 0, "OK")
     expect(
         "标记后多空格",
         TREE_CHAPTER.replace("# 读入坐标", "#  读入坐标"),
@@ -325,6 +391,7 @@ def main() -> int:
     )
 
     with tempfile.TemporaryDirectory() as raw:
+        passed_cases += 1
         root = Path(raw)
         make_book(root)
         (root / "content" / "part" / "01-intro.qmd").unlink()
@@ -339,7 +406,7 @@ def main() -> int:
             print(f"  FAIL {line}")
         return 1
 
-    print("PASS：36 个用例全部通过")
+    print(f"PASS：{passed_cases} 个用例全部通过")
     return 0