refactor: simplify wiki sync link segmentation

Author: zouyonghe

scripts/sync_docs_to_wiki.py

@@ -84,6 +84,12 @@ class MarkdownLink:
     suffix: str
 
 
+@dataclass
+class Segment:
+    kind: str
+    text: str
+
+
 def repo_root() -> Path:
     return Path(__file__).resolve().parents[1]
 
@@ -217,19 +223,6 @@ def parse_doc_target(target: str) -> tuple[str, str] | None:
     return base_target, anchor
 
 
-def find_candidates_by_suffix(
-    language: str, suffix: str, source_pages: tuple[str, ...]
-) -> list[str]:
-    prefix = f"{language}/"
-    full_suffix = f"{language}/{suffix}"
-    return [
-        page
-        for page in source_pages
-        if page.startswith(prefix)
-        and (page == full_suffix or page.endswith(f"/{suffix}"))
-    ]
-
-
 def find_existing_source_path(
     candidate: PurePosixPath,
     source_root: Path,
@@ -248,7 +241,14 @@ def find_existing_source_path(
     if not suffix:
         return ResolutionResult(resolved_path=None)
 
-    matches = find_candidates_by_suffix(language, suffix, source_pages)
+    prefix = f"{language}/"
+    full_suffix = f"{language}/{suffix}"
+    matches = [
+        page
+        for page in source_pages
+        if page.startswith(prefix)
+        and (page == full_suffix or page.endswith(f"/{suffix}"))
+    ]
     if len(matches) == 1:
         return ResolutionResult(resolved_path=matches[0])
     if len(matches) > 1:
@@ -292,30 +292,30 @@ def __init__(self, source_root: Path):
         self.source_root = Path(source_root)
         self.source_pages = discover_source_pages(str(self.source_root))
 
-    def resolve(self, target: str, source_path: str) -> ResolutionResult:
-        parsed_target = parse_doc_target(target)
-        if parsed_target is None:
-            return ResolutionResult(resolved_path=None)
-
-        base_target, _ = parsed_target
+    def resolve_base_target(
+        self, base_target: str, source_path: str
+    ) -> ResolutionResult:
         return resolve_link_path(
             base_target=base_target,
             source_path=source_path,
             source_root=self.source_root,
             source_pages=self.source_pages,
         )
 
-    def resolve_path(self, target: str, source_path: str) -> str | None:
-        return self.resolve(target, source_path).resolved_path
+    def resolve_markdown_target(
+        self, target: str, source_path: str
+    ) -> tuple[str | None, str]:
+        parsed_target = parse_doc_target(target)
+        if parsed_target is None:
+            return None, ""
 
+        base_target, anchor = parsed_target
+        result = self.resolve_base_target(base_target, source_path)
+        return result.resolved_path, anchor
 
-def rewrite_link_target(target: str, source_path: str, resolver: LinkResolver) -> str:
-    parsed_target = parse_doc_target(target)
-    if parsed_target is None:
-        return target
 
-    base_target, anchor = parsed_target
-    resolved = resolver.resolve_path(base_target, source_path)
+def rewrite_link_target(target: str, source_path: str, resolver: LinkResolver) -> str:
+    resolved, anchor = resolver.resolve_markdown_target(target, source_path)
     if resolved is None:
         return target
 
@@ -343,55 +343,55 @@ def rewrite_links_in_segment(
     return "".join(result)
 
 
-def rewrite_links(
-    content: str,
-    source_path: str,
-    resolver: LinkResolver,
-) -> str:
-    parts: list[tuple[str, str]] = []
+def iter_segments(content: str):
     last_end = 0
-
-    for fenced_match in FENCED_BLOCK_RE.finditer(content):
-        before = content[last_end : fenced_match.start()]
+    for fenced in FENCED_BLOCK_RE.finditer(content):
+        before = content[last_end : fenced.start()]
         if before:
-            parts.append(("text", before))
-        parts.append(("code", fenced_match.group(0)))
-        last_end = fenced_match.end()
+            last_inline_end = 0
+            for inline in INLINE_CODE_RE.finditer(before):
+                if inline.start() > last_inline_end:
+                    yield Segment("text", before[last_inline_end : inline.start()])
+                yield Segment("inline_code", inline.group(0))
+                last_inline_end = inline.end()
+            if last_inline_end < len(before):
+                yield Segment("text", before[last_inline_end:])
+
+        yield Segment("code_block", fenced.group(0))
+        last_end = fenced.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
+    if not tail:
+        return
 
-        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,
-                    )
-                )
+    last_inline_end = 0
+    for inline in INLINE_CODE_RE.finditer(tail):
+        if inline.start() > last_inline_end:
+            yield Segment("text", tail[last_inline_end : inline.start()])
+        yield Segment("inline_code", inline.group(0))
+        last_inline_end = inline.end()
+    if last_inline_end < len(tail):
+        yield Segment("text", tail[last_inline_end:])
 
-            output.append(inline_match.group(0))
-            last_inline_end = inline_match.end()
 
-        after_inline = chunk[last_inline_end:]
-        if after_inline:
+def rewrite_links(
+    content: str,
+    source_path: str,
+    resolver: LinkResolver,
+) -> str:
+    output: list[str] = []
+    for segment in iter_segments(content):
+        if segment.kind == "text":
             output.append(
                 rewrite_links_in_segment(
-                    after_inline,
+                    segment.text,
                     source_path=source_path,
                     resolver=resolver,
                 )
             )
+            continue
+
+        output.append(segment.text)
 
     return "".join(output)
 
@@ -404,12 +404,16 @@ def find_unresolved_doc_links(source_root: Path) -> list[str]:
     for source_path in resolver.source_pages:
         content = (root / source_path).read_text(encoding="utf-8")
         for link in iter_markdown_links(content):
+            resolved_path, _ = resolver.resolve_markdown_target(
+                link.target, source_path
+            )
+            if resolved_path is not None:
+                continue
             parsed_target = parse_doc_target(link.target)
             if parsed_target is None:
                 continue
-            resolution = resolver.resolve(link.target, source_path)
-            if resolution.resolved_path is not None:
-                continue
+            base_target, _ = parsed_target
+            resolution = resolver.resolve_base_target(base_target, source_path)
             if resolution.ambiguous_matches:
                 unresolved.append(
                     f"{source_path} -> {link.target} (ambiguous: {', '.join(resolution.ambiguous_matches)})",

tests/test_sync_docs_to_wiki.py

@@ -41,14 +41,16 @@ def test_module_does_not_expose_removed_wrapper_helpers(self):
         self.assertFalse(hasattr(module, "resolve_source_path"))
         self.assertFalse(hasattr(module, "compute_managed_files"))
         self.assertFalse(hasattr(module, "MANAGED_FILENAMES"))
+        self.assertFalse(hasattr(module, "find_candidates_by_suffix"))
 
     def test_module_exposes_consolidated_helper_names(self):
         module = load_sync_module()
 
         self.assertTrue(hasattr(module, "prepare_candidate_path"))
-        self.assertTrue(hasattr(module, "find_candidates_by_suffix"))
         self.assertTrue(hasattr(module, "resolve_link_path"))
         self.assertTrue(hasattr(module, "LANG_CONFIG"))
+        self.assertTrue(hasattr(module, "Segment"))
+        self.assertTrue(hasattr(module, "iter_segments"))
 
     def test_parse_doc_target_returns_base_and_anchor(self):
         module = load_sync_module()
@@ -68,6 +70,26 @@ def test_iter_markdown_links_handles_whitespace_before_target(self):
 
         self.assertEqual([link.target for link in links], ["guide.md"])
 
+    def test_iter_segments_splits_text_inline_and_fenced_code(self):
+        module = load_sync_module()
+
+        segments = list(
+            module.iter_segments(
+                "Start [Guide](/guide) `code [Guide](/guide)`\n\n```md\n[Guide](/guide)\n```\nTail\n"
+            )
+        )
+
+        self.assertEqual(
+            [(segment.kind, segment.text) for segment in segments],
+            [
+                ("text", "Start [Guide](/guide) "),
+                ("inline_code", "`code [Guide](/guide)`"),
+                ("text", "\n\n"),
+                ("code_block", "```md\n[Guide](/guide)\n```"),
+                ("text", "\nTail\n"),
+            ],
+        )
+
     def test_rewrite_links_handles_absolute_same_language_links(self):
         module = load_sync_module()
 
@@ -221,8 +243,8 @@ def test_link_resolver_resolves_source_paths(self):
             resolver = module.LinkResolver(source_root)
 
             self.assertEqual(
-                resolver.resolve_path("/deploy/guide", "zh/index.md"),
-                "zh/deploy/guide.md",
+                resolver.resolve_markdown_target("/deploy/guide#intro", "zh/index.md"),
+                ("zh/deploy/guide.md", "#intro"),
             )
 
     def test_resolve_link_path_resolves_relative_target(self):
@@ -271,21 +293,21 @@ def test_prepare_candidate_path_normalizes_suffix_and_alias(self):
             module.PurePosixPath("zh/providers/start.md"),
         )
 
-    def test_find_candidates_by_suffix_matches_language_bounded_suffixes(self):
+    def test_find_existing_source_path_matches_language_bounded_suffixes(self):
         module = load_sync_module()
 
         self.assertEqual(
-            module.find_candidates_by_suffix(
-                language="zh",
-                suffix="bar/guide.md",
+            module.find_existing_source_path(
+                candidate=module.PurePosixPath("zh/bar/guide.md"),
+                source_root=Path("/tmp/nonexistent"),
                 source_pages=(
                     "zh/bar/guide.md",
                     "zh/foo/bar/guide.md",
                     "zh/foobar/guide.md",
                     "en/bar/guide.md",
                 ),
-            ),
-            ["zh/bar/guide.md", "zh/foo/bar/guide.md"],
+            ).ambiguous_matches,
+            ("zh/bar/guide.md", "zh/foo/bar/guide.md"),
         )
 
     def test_build_page_info_returns_page_info_dataclass(self):
@@ -436,8 +458,9 @@ def test_resolver_does_not_match_partial_path_segments(self):
 
             resolver = module.LinkResolver(source_root)
 
-            self.assertIsNone(
-                resolver.resolve_path("/bar/guide", "zh/index.md"),
+            self.assertEqual(
+                resolver.resolve_markdown_target("/bar/guide", "zh/index.md"),
+                (None, ""),
             )
 
     def test_live_docs_have_no_unresolved_internal_doc_links(self):