fix: validate and preserve wiki sync links

Author: zouyonghe

.github/workflows/sync-wiki.yml

@@ -40,6 +40,9 @@ jobs:
       - name: Run sync unit tests
         run: python -m unittest discover -s tests -p 'test_sync_docs_to_wiki.py' -v
 
+      - name: Validate internal doc links
+        run: python scripts/sync_docs_to_wiki.py --source-root . --check-links-only
+
       - name: Clone AstrBot wiki
         env:
           WIKI_TOKEN: ${{ secrets.ASTRBOT_WIKI_TOKEN }}

scripts/sync_docs_to_wiki.py

@@ -8,6 +8,11 @@
 
 
 TITLE_RE = re.compile(r"^#\s+(.+)$", re.MULTILINE)
+FENCED_BLOCK_RE = re.compile(
+    r"(^```.*?$.*?^```$|^~~~.*?$.*?^~~~$)",
+    re.MULTILINE | re.DOTALL,
+)
+INLINE_CODE_RE = re.compile(r"(`[^`]*`)")
 MANIFEST_NAME = ".astrbot-wiki-sync-manifest"
 SOURCE_ALIASES = {
     "zh/config/providers/start.md": "zh/providers/start.md",
@@ -317,27 +322,80 @@ def rewrite_link_target(target: str, source_path: str, resolver: LinkResolver) -
     return f"{page_name_for_source(resolved)}{anchor}"
 
 
-def rewrite_links(
-    content: str,
+def rewrite_links_in_segment(
+    segment: str,
     source_path: str,
     resolver: LinkResolver,
 ) -> str:
-    links = list(iter_markdown_links(content))
+    links = list(iter_markdown_links(segment))
     if not links:
-        return content
+        return segment
 
     result: list[str] = []
     previous_end = 0
     for link in links:
-        result.append(content[previous_end : link.start])
+        result.append(segment[previous_end : link.start])
         result.append(
             f"{link.prefix}{rewrite_link_target(link.target, source_path, resolver)}{link.suffix}",
         )
         previous_end = link.end
-    result.append(content[previous_end:])
+    result.append(segment[previous_end:])
     return "".join(result)
 
 
+def rewrite_links(
+    content: str,
+    source_path: str,
+    resolver: LinkResolver,
+) -> str:
+    parts: list[tuple[str, str]] = []
+    last_end = 0
+
+    for fenced_match in FENCED_BLOCK_RE.finditer(content):
+        before = content[last_end : fenced_match.start()]
+        if before:
+            parts.append(("text", before))
+        parts.append(("code", fenced_match.group(0)))
+        last_end = fenced_match.end()
+
+    tail = content[last_end:]
+    if tail:
+        parts.append(("text", tail))
+
+    output: list[str] = []
+    for kind, chunk in parts:
+        if kind == "code":
+            output.append(chunk)
+            continue
+
+        last_inline_end = 0
+        for inline_match in INLINE_CODE_RE.finditer(chunk):
+            before_inline = chunk[last_inline_end : inline_match.start()]
+            if before_inline:
+                output.append(
+                    rewrite_links_in_segment(
+                        before_inline,
+                        source_path=source_path,
+                        resolver=resolver,
+                    )
+                )
+
+            output.append(inline_match.group(0))
+            last_inline_end = inline_match.end()
+
+        after_inline = chunk[last_inline_end:]
+        if after_inline:
+            output.append(
+                rewrite_links_in_segment(
+                    after_inline,
+                    source_path=source_path,
+                    resolver=resolver,
+                )
+            )
+
+    return "".join(output)
+
+
 def find_unresolved_doc_links(source_root: Path) -> list[str]:
     unresolved: list[str] = []
     root = Path(source_root)
@@ -362,6 +420,15 @@ def find_unresolved_doc_links(source_root: Path) -> list[str]:
     return unresolved
 
 
+def check_unresolved_doc_links(source_root: Path) -> None:
+    unresolved = find_unresolved_doc_links(source_root)
+    if not unresolved:
+        return
+
+    issues = "\n".join(f"- {item}" for item in unresolved)
+    raise ValueError(f"Unresolved internal doc links found:\n{issues}")
+
+
 def page_name_for_source(source_path: str) -> str:
     if not source_path.endswith(".md"):
         raise ValueError(f"Unsupported source path: {source_path}")
@@ -417,12 +484,6 @@ def build_home_page(language: str) -> str:
     return normalize_content("\n".join(lines))
 
 
-def sidebar_group_name(group: str) -> str:
-    if group == "root":
-        return "Top Level"
-    return group.replace("-", " ")
-
-
 def build_sidebar(page_infos: list[PageInfo]) -> str:
     lines: list[str] = []
 
@@ -449,7 +510,7 @@ def build_sidebar(page_infos: list[PageInfo]) -> str:
             grouped.setdefault(info.group, []).append(info)
 
         for group_name in sorted(grouped):
-            lines.append(f"- {sidebar_group_name(group_name)}")
+            lines.append(f"- {group_name}")
             for info in grouped[group_name]:
                 lines.append(f"  - [{info.title}]({info.page_name})")
 
@@ -469,7 +530,7 @@ def build_page_info(
 
     relative = PurePosixPath(source_path)
     parts = relative.parts
-    group = "root" if len(parts) <= 2 else parts[1]
+    group = "Top Level" if len(parts) <= 2 else parts[1].replace("-", " ")
 
     return PageInfo(
         source_path=source_path,
@@ -553,11 +614,23 @@ def main() -> int:
     )
     parser.add_argument(
         "--wiki-root",
-        required=True,
         help="Path to the checked out wiki repository.",
     )
+    parser.add_argument(
+        "--check-links-only",
+        action="store_true",
+        help="Validate internal doc links without writing wiki files.",
+    )
     args = parser.parse_args()
 
+    if not args.check_links_only and not args.wiki_root:
+        parser.error("--wiki-root is required unless --check-links-only is set")
+
+    check_unresolved_doc_links(Path(args.source_root))
+
+    if args.check_links_only:
+        return 0
+
     sync_docs_to_wiki(
         source_root=Path(args.source_root), wiki_root=Path(args.wiki_root)
     )

tests/test_sync_docs_to_wiki.py

@@ -165,6 +165,48 @@ def test_rewrite_links_leaves_local_asset_links_unchanged(self):
                 content,
             )
 
+    def test_rewrite_links_skips_fenced_code_blocks(self):
+        module = load_sync_module()
+
+        with TemporaryDirectory() as temp_dir:
+            source_root = Path(temp_dir) / "docs"
+            (source_root / "zh").mkdir(parents=True)
+            (source_root / "zh" / "index.md").write_text("# Home\n", encoding="utf-8")
+            (source_root / "zh" / "guide.md").write_text("# Guide\n", encoding="utf-8")
+            resolver = module.LinkResolver(source_root)
+
+            content = "```md\n[Guide](/guide)\n```\n\nSee [Guide](/guide).\n"
+
+            self.assertEqual(
+                module.rewrite_links(
+                    content,
+                    source_path="zh/index.md",
+                    resolver=resolver,
+                ),
+                "```md\n[Guide](/guide)\n```\n\nSee [Guide](zh-guide).\n",
+            )
+
+    def test_rewrite_links_skips_inline_code(self):
+        module = load_sync_module()
+
+        with TemporaryDirectory() as temp_dir:
+            source_root = Path(temp_dir) / "docs"
+            (source_root / "zh").mkdir(parents=True)
+            (source_root / "zh" / "index.md").write_text("# Home\n", encoding="utf-8")
+            (source_root / "zh" / "guide.md").write_text("# Guide\n", encoding="utf-8")
+            resolver = module.LinkResolver(source_root)
+
+            content = "Use `[Guide](/guide)` literally, then See [Guide](/guide).\n"
+
+            self.assertEqual(
+                module.rewrite_links(
+                    content,
+                    source_path="zh/index.md",
+                    resolver=resolver,
+                ),
+                "Use `[Guide](/guide)` literally, then See [Guide](zh-guide).\n",
+            )
+
     def test_link_resolver_resolves_source_paths(self):
         module = load_sync_module()
 
@@ -266,6 +308,26 @@ def test_build_page_info_returns_page_info_dataclass(self):
             self.assertIsInstance(page_info, module.PageInfo)
             self.assertEqual(page_info.page_name, "zh-index")
 
+    def test_build_page_info_uses_display_ready_group(self):
+        module = load_sync_module()
+
+        with TemporaryDirectory() as temp_dir:
+            source_root = Path(temp_dir) / "docs"
+            (source_root / "zh" / "agent-runners").mkdir(parents=True)
+            (source_root / "zh" / "agent-runners" / "guide.md").write_text(
+                "# Guide\n",
+                encoding="utf-8",
+            )
+
+            resolver = module.LinkResolver(source_root)
+            page_info = module.build_page_info(
+                source_root=source_root,
+                source_path="zh/agent-runners/guide.md",
+                resolver=resolver,
+            )
+
+            self.assertEqual(page_info.group, "agent runners")
+
     def test_sync_writes_pages_and_sidebar(self):
         module = load_sync_module()
 
@@ -387,6 +449,20 @@ def test_live_docs_have_no_unresolved_internal_doc_links(self):
 
         self.assertEqual(unresolved, [])
 
+    def test_check_unresolved_doc_links_raises_for_bad_docs(self):
+        module = load_sync_module()
+
+        with TemporaryDirectory() as temp_dir:
+            source_root = Path(temp_dir) / "docs"
+            (source_root / "zh").mkdir(parents=True)
+            (source_root / "zh" / "index.md").write_text(
+                "See [Missing](/missing).\n",
+                encoding="utf-8",
+            )
+
+            with self.assertRaises(ValueError):
+                module.check_unresolved_doc_links(source_root)
+
 
 if __name__ == "__main__":
     unittest.main()