200|300)")[^>]*?/?>',
re.IGNORECASE,
)
@@ -1048,10 +1410,19 @@ def apply_exact_legacy_content_fixes(assembly: pathlib.Path, version: str) -> in
return fixed
+def first_existing_path(assembly: pathlib.Path, candidates: tuple[str, ...]) -> pathlib.Path:
+ """Resolve one version-specific content path without guessing missing files."""
+ matches = [assembly / candidate for candidate in candidates if (assembly / candidate).is_file()]
+ if len(matches) != 1:
+ fail(f"expected exactly one historical path, found {len(matches)}: {candidates!r}")
+ return matches[0]
+
+
def apply_known_legacy_fixes(assembly: pathlib.Path, version: str) -> int:
fixed = 0
- if version in {"1.7", "1.5"}:
- fixed += apply_exact_legacy_content_fixes(assembly, version)
+ if version in {"1.7", "1.5", "1.3", "1.0"}:
+ if version in LEGACY_EXACT_CONTENT_FIXES:
+ fixed += apply_exact_legacy_content_fixes(assembly, version)
for language in ("en", "cn"):
language_prefix = "/cn" if language == "cn" else ""
legacy_metadata = (
@@ -1067,15 +1438,14 @@ def apply_known_legacy_fixes(assembly: pathlib.Path, version: str) -> int:
),
)
for relative, title, link_title in legacy_metadata:
- fixed += ensure_frontmatter(
- assembly / f"content/{language}/docs/{relative}",
- title=title,
- link_title=link_title,
- weight=100,
- )
- fixed += ensure_search_excluded(
- assembly / f"content/{language}/docs/CLA.md"
- )
+ page = assembly / f"content/{language}/docs/{relative}"
+ if page.is_file():
+ fixed += ensure_frontmatter(
+ page, title=title, link_title=link_title, weight=100
+ )
+ cla = assembly / f"content/{language}/docs/CLA.md"
+ if cla.is_file():
+ fixed += ensure_search_excluded(cla)
search_metadata = (
(
"config/config-option.md",
@@ -1091,16 +1461,20 @@ def apply_known_legacy_fixes(assembly: pathlib.Path, version: str) -> int:
),
)
for relative, keywords in search_metadata:
- fixed += ensure_search_metadata(
- assembly / f"content/{language}/docs/{relative}",
- keywords=keywords,
- boost=1.5,
- )
+ page = assembly / f"content/{language}/docs/{relative}"
+ if page.is_file():
+ fixed += ensure_search_metadata(page, keywords=keywords, boost=1.5)
summary_path = assembly / f"content/{language}/docs/SUMMARY.md"
- fixed += repair_historical_performance_routes(summary_path)
+ if version in {"1.7", "1.5"}:
+ fixed += repair_historical_performance_routes(summary_path)
fixed += normalize_historical_server_headings(
- assembly
- / f"content/{language}/docs/quickstart/hugegraph/hugegraph-server.md"
+ first_existing_path(
+ assembly,
+ (
+ f"content/{language}/docs/quickstart/hugegraph/hugegraph-server.md",
+ f"content/{language}/docs/quickstart/hugegraph-server.md",
+ ),
+ )
)
replacements = []
if language == "cn":
@@ -1112,6 +1486,15 @@ def apply_known_legacy_fixes(assembly: pathlib.Path, version: str) -> int:
)
replacements.extend(
[
+ ("/en/docs/", "/docs/"),
+ (
+ "/dcos/clients/restful-api",
+ f"{language_prefix}/docs/clients/restful-api/",
+ ),
+ (
+ "/docs/quickstart/hugegraph-studio",
+ f"{language_prefix}/docs/quickstart/toolchain/hugegraph-hubble",
+ ),
(
"/docs/quickstart/hugegraph-server",
f"{language_prefix}/docs/quickstart/hugegraph/hugegraph-server",
@@ -1120,6 +1503,10 @@ def apply_known_legacy_fixes(assembly: pathlib.Path, version: str) -> int:
"/clients/gremlin-console.html",
f"{language_prefix}/docs/clients/gremlin-console/",
),
+ (
+ "/clients/hugegraph-api.html",
+ f"{language_prefix}/docs/clients/restful-api/",
+ ),
(
"./hugegraph-style.xml",
"https://github.com/apache/hugegraph/blob/"
@@ -1208,12 +1595,22 @@ def apply_known_legacy_fixes(assembly: pathlib.Path, version: str) -> int:
return fixed
-def version_urls(manifest: dict, origin: str, language: str = "en") -> list[dict]:
+def version_urls(
+ manifest: dict,
+ origin: str,
+ language: str = "en",
+ historical_origin: str | None = None,
+) -> list[dict]:
if language not in {"en", "cn"}:
fail(f"unsupported version-menu language: {language}")
language_prefix = "cn/" if language == "cn" else ""
urls = []
for entry in manifest["versions"]:
+ entry_origin = (
+ historical_origin
+ if entry["archived"] and historical_origin is not None
+ else origin
+ )
path = (
f"{entry['publishPath']}/{language_prefix}docs/"
if entry["publishPath"]
@@ -1223,20 +1620,25 @@ def version_urls(manifest: dict, origin: str, language: str = "en") -> list[dict
{
"version": entry["id"],
"name": entry["name"],
- "url": urllib.parse.urljoin(origin.rstrip("/") + "/", path),
+ "url": urllib.parse.urljoin(entry_origin.rstrip("/") + "/", path),
"pagelinks": False,
}
)
return urls
-def language_version_params(manifest: dict, origin: str, language: str) -> dict:
+def language_version_params(
+ manifest: dict,
+ origin: str,
+ language: str,
+ historical_origin: str | None = None,
+) -> dict:
"""Build language-preserving version selector and archive-banner params."""
if language not in {"en", "cn"}:
fail(f"unsupported version-menu language: {language}")
return {
"version_menu": "Releases" if language == "en" else "版本",
- "versions": version_urls(manifest, origin, language),
+ "versions": version_urls(manifest, origin, language, historical_origin),
"url_latest_version": urllib.parse.urljoin(
origin.rstrip("/") + "/",
"cn/docs/" if language == "cn" else "docs/",
@@ -1367,6 +1769,7 @@ def rewrite_internal_url(
origin: str,
publish_path: str,
allowed_paths: set[str],
+ version_id: str | None = None,
) -> str:
"""Scope a same-site absolute/root URL to one historical artifact."""
if not value or value.startswith(("#", "?")):
@@ -1417,8 +1820,8 @@ def rewrite_internal_url(
else path
)
normalized_internal = internal_path.rstrip("/") or "/"
- mapped_path = KNOWN_HISTORICAL_ROUTES_BY_PUBLISH_PATH.get(
- publish_path.strip("/"), {}
+ mapped_path = KNOWN_HISTORICAL_ROUTES_BY_VERSION.get(
+ version_id or "", {}
).get(normalized_internal)
if mapped_path is None:
mapped_path = KNOWN_HISTORICAL_ROUTES.get(normalized_internal)
@@ -1550,6 +1953,51 @@ def scope_language_fallback_urls(
return changed
+def normalize_language_switch_urls(
+ action_data: dict,
+ relative: str,
+ artifact_base: str,
+ output: pathlib.Path,
+) -> int:
+ """Keep language choices on an equivalent page or the same-version locale root."""
+ actions = action_data.get("actions")
+ if not isinstance(actions, list):
+ return 0
+ switches = [
+ action
+ for action in actions
+ if isinstance(action, dict) and action.get("id") == "switch_language"
+ ]
+ if len(switches) != 1 or not isinstance(switches[0].get("options"), list):
+ return 0
+ english_relative = relative.removeprefix("cn/")
+ chinese_relative = "cn/" + english_relative
+ candidates = {"en-US": english_relative, "zh-CN": chinese_relative}
+ roots = {"en-US": "", "zh-CN": "cn/"}
+ changed = 0
+ for option in switches[0]["options"]:
+ language = option.get("id")
+ candidate = candidates.get(language)
+ if candidate is None:
+ continue
+ target = output / candidate
+ route = candidate
+ if not target.is_file():
+ route = roots[language]
+ elif route.endswith("index.html"):
+ route = route[: -len("index.html")]
+ new_url = (
+ "/" + route
+ if not target.is_file()
+ and urllib.parse.urlsplit(artifact_base).path == "/"
+ else urllib.parse.urljoin(artifact_base, route)
+ )
+ if option.get("url") != new_url:
+ option["url"] = new_url
+ changed += 1
+ return changed
+
+
def validate_language_switch_contract(
action_data: dict,
relative: str,
@@ -1607,6 +2055,47 @@ def validate_language_switch_contract(
fail(f"language switch metadata mismatch in {relative}: {language}")
+def rewrite_srcset_urls(value: str, rewrite) -> tuple[str, int]:
+ """Rewrite each URL in a srcset-like list while preserving its descriptors."""
+ output: list[str] = []
+ cursor = 0
+ count = 0
+ for old in srcset_urls(value):
+ start = value.find(old, cursor)
+ if start < 0:
+ fail(f"cannot locate srcset URL candidate: {old}")
+ new = rewrite(old)
+ output.extend((value[cursor:start], new))
+ cursor = start + len(old)
+ count += old != new
+ output.append(value[cursor:])
+ return "".join(output), count
+
+
+def rewrite_url_list_attributes(text: str, rewrite) -> tuple[str, int]:
+ """Rewrite quoted and unquoted srcset/imagesrcset attribute candidates."""
+ count = 0
+
+ def replace_quoted(match: re.Match) -> str:
+ nonlocal count
+ value, changed = rewrite_srcset_urls(match.group("value"), rewrite)
+ count += changed
+ return (
+ f"{match.group('prefix')}{match.group('quote')}"
+ f"{value}{match.group('quote')}"
+ )
+
+ def replace_unquoted(match: re.Match) -> str:
+ nonlocal count
+ value, changed = rewrite_srcset_urls(match.group("value"), rewrite)
+ count += changed
+ return f"{match.group('prefix')}{value}"
+
+ text = URL_LIST_ATTRIBUTE_RE.sub(replace_quoted, text)
+ text = URL_LIST_UNQUOTED_ATTRIBUTE_RE.sub(replace_unquoted, text)
+ return text, count
+
+
def rewrite_text_urls(text: str, rewrite, *, markdown: bool) -> tuple[str, int]:
count = 0
@@ -1619,51 +2108,670 @@ def replace_attribute(match: re.Match) -> str:
f"{match.group('prefix')}{match.group('quote')}{new}{match.group('quote')}"
)
+ def replace_destination(match: re.Match) -> str:
+ nonlocal count
+ old = match.group("url")
+ new = rewrite(old)
+ count += old != new
+ return f"{match.group('open')}{new}{match.group('close')}"
+
+ def rewrite_unfenced(source: str) -> str:
+ nonlocal count
+ source = URL_ATTRIBUTE_RE.sub(replace_attribute, source)
+ source, list_count = rewrite_url_list_attributes(source, rewrite)
+ count += list_count
+ return MARKDOWN_DESTINATION_RE.sub(replace_destination, source)
+
if markdown:
in_fence = False
- lines = []
+ pending: list[str] = []
+ chunks: list[str] = []
for line in text.splitlines(keepends=True):
if re.match(r"^\s*(```|~~~)", line):
+ if pending:
+ chunks.append(
+ "".join(pending)
+ if in_fence
+ else rewrite_unfenced("".join(pending))
+ )
+ pending = []
+ chunks.append(line)
in_fence = not in_fence
- lines.append(line)
- continue
- if not in_fence:
-
- def replace_destination(match: re.Match) -> str:
- nonlocal count
- old = match.group("url")
- new = rewrite(old)
- count += old != new
- return f"{match.group('open')}{new}{match.group('close')}"
-
- line = URL_ATTRIBUTE_RE.sub(replace_attribute, line)
- line = MARKDOWN_DESTINATION_RE.sub(replace_destination, line)
- lines.append(line)
- text = "".join(lines)
+ else:
+ pending.append(line)
+ if pending:
+ chunks.append(
+ "".join(pending)
+ if in_fence
+ else rewrite_unfenced("".join(pending))
+ )
+ text = "".join(chunks)
else:
- text = URL_ATTRIBUTE_RE.sub(replace_attribute, text)
+ text = rewrite_unfenced(text)
return text, count
+def normalize_logical_docs_route(_version: str, relative: str) -> str:
+ """Normalize reviewed route moves without treating aliases as pages."""
+ normalized = relative.strip("/")
+ normalized = normalized.replace(
+ "performance/api-preformance", "performance/api-performance"
+ )
+ return normalized
+
+
+def docs_target_parts(target: str) -> tuple[str, str]:
+ """Return locale and relative Docs path for one route-map target."""
+ normalized = target.strip("/")
+ if normalized == "docs":
+ return "en", ""
+ if normalized.startswith("docs/"):
+ return "en", normalized.removeprefix("docs/")
+ if normalized == "cn/docs":
+ return "cn", ""
+ if normalized.startswith("cn/docs/"):
+ return "cn", normalized.removeprefix("cn/docs/")
+ fail(f"route-map target is outside Docs: {target}")
+
+
+def canonical_docs_pages(root: pathlib.Path, version: str) -> dict[str, str]:
+ """Inventory canonical Docs pages, excluding redirect aliases and print views."""
+ pages: dict[str, str] = {}
+ for language, docs_root in (
+ ("en", root / "docs"),
+ ("cn", root / "cn/docs"),
+ ):
+ if not docs_root.is_dir():
+ fail(f"route-map Docs root is missing for {version}: {docs_root}")
+ for path in sorted(docs_root.rglob("index.html")):
+ document = DocumentParser()
+ document.feed(path.read_text(encoding="utf-8"))
+ if refresh_target(document):
+ continue
+ relative = path.parent.relative_to(docs_root).as_posix()
+ relative = "" if relative == "." else relative
+ logical_relative = normalize_logical_docs_route(version, relative)
+ logical_id = f"{language}:{logical_relative}"
+ target = (
+ ("cn/docs/" if language == "cn" else "docs/")
+ + (relative.rstrip("/") + "/" if relative else "")
+ )
+ previous = pages.get(logical_id)
+ if previous is not None and previous != target:
+ fail(
+ f"ambiguous canonical route for {version} {logical_id}: "
+ f"{previous} and {target}"
+ )
+ pages[logical_id] = target
+ return pages
+
+
+def docs_alias_equivalence_edges(
+ root: pathlib.Path, entry: dict, canonical_pages: dict[str, str]
+) -> set[tuple[str, str]]:
+ """Return locale-preserving logical edges declared by static Docs aliases."""
+ version = entry["id"]
+ prefix = "/" + entry["publishPath"].strip("/") if entry["publishPath"] else ""
+ metadata_path = root / ".version.json"
+ if metadata_path.is_file():
+ metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+ expected_base = metadata.get("baseURL")
+ if not isinstance(expected_base, str) or not expected_base:
+ fail(f"route-map artifact baseURL is missing for {version}")
+ else:
+ expected_base = base_url("https://artifact.invalid/", entry["publishPath"])
+ aliases: dict[str, tuple[str, str, pathlib.Path]] = {}
+ for language, docs_root in (
+ ("en", root / "docs"),
+ ("cn", root / "cn/docs"),
+ ):
+ if not docs_root.is_dir():
+ fail(f"route-map Docs root is missing for {version}: {docs_root}")
+ for path in sorted(docs_root.rglob("index.html")):
+ document = DocumentParser()
+ document.feed(path.read_text(encoding="utf-8"))
+ redirect = refresh_target(document)
+ if redirect is None:
+ continue
+ target_path = validate_artifact_alias_target(
+ redirect,
+ root,
+ entry,
+ expected_base,
+ path.relative_to(root).as_posix(),
+ )
+ if prefix and (
+ target_path == prefix or target_path.startswith(prefix + "/")
+ ):
+ target_path = target_path[len(prefix) :] or "/"
+ try:
+ target_language, target_relative = docs_target_parts(target_path)
+ except SystemExit:
+ continue
+ if target_language != language:
+ fail(
+ f"route-map alias changes locale for {version}: "
+ f"{path.relative_to(root)} -> {redirect}"
+ )
+ source_relative = path.parent.relative_to(docs_root).as_posix()
+ source_relative = "" if source_relative == "." else source_relative
+ source_route = (
+ ("cn/docs/" if language == "cn" else "docs/")
+ + (source_relative.rstrip("/") + "/" if source_relative else "")
+ )
+ target_route = (
+ ("cn/docs/" if target_language == "cn" else "docs/")
+ + (target_relative.rstrip("/") + "/" if target_relative else "")
+ )
+ source_id = (
+ f"{language}:"
+ f"{normalize_logical_docs_route(version, source_relative)}"
+ )
+ previous = aliases.get(source_route)
+ alias = (source_id, target_route, path)
+ if previous is not None and previous != alias:
+ fail(
+ f"route-map alias is ambiguous for {version}: "
+ f"{source_route}"
+ )
+ aliases[source_route] = alias
+
+ canonical_ids_by_target = {
+ target: logical_id for logical_id, target in canonical_pages.items()
+ }
+ canonical_targets = set(canonical_ids_by_target)
+ edges: set[tuple[str, str]] = set()
+ for source_route, (source_id, target_route, path) in aliases.items():
+ visited = {source_route}
+ candidate = target_route
+ while candidate not in canonical_targets:
+ if candidate in visited:
+ fail(
+ f"route-map alias cycle for {version}: "
+ f"{path.relative_to(root)} -> {candidate}"
+ )
+ visited.add(candidate)
+ chained = aliases.get(candidate)
+ if chained is None:
+ fail(
+ f"route-map alias target is missing for {version}: "
+ f"{path.relative_to(root)} -> {candidate}"
+ )
+ candidate = chained[1]
+ target_id = canonical_ids_by_target[candidate]
+ if source_id != target_id:
+ edges.add(tuple(sorted((source_id, target_id))))
+ return edges
+
+
+def equivalence_groups(
+ edges: set[tuple[str, str]], logical_ids: set[str]
+) -> list[list[str]]:
+ """Build deterministic disjoint components from reviewed alias edges."""
+ graph: dict[str, set[str]] = {}
+ for left, right in edges:
+ if left not in logical_ids or right not in logical_ids:
+ continue
+ graph.setdefault(left, set()).add(right)
+ graph.setdefault(right, set()).add(left)
+ groups = []
+ unseen = set(graph)
+ while unseen:
+ pending = [min(unseen)]
+ component = set()
+ while pending:
+ logical_id = pending.pop()
+ if logical_id in component:
+ continue
+ component.add(logical_id)
+ pending.extend(sorted(graph.get(logical_id, ()), reverse=True))
+ unseen.difference_update(component)
+ if len(component) > 1:
+ groups.append(sorted(component))
+ return sorted(groups)
+
+
+def generate_version_routes(
+ artifact_roots: dict[str, pathlib.Path], manifest: dict
+) -> dict:
+ """Generate the reviewed cross-version logical page map deterministically."""
+ version_ids = manifest_version_ids(manifest)
+ if set(artifact_roots) != set(version_ids):
+ fail(
+ "route-map artifacts must contain exactly: "
+ + ", ".join(version_ids)
+ )
+ inventories = {
+ version: canonical_docs_pages(artifact_roots[version], version)
+ for version in version_ids
+ }
+ logical_ids = sorted(
+ {logical_id for pages in inventories.values() for logical_id in pages}
+ )
+ entries = {entry["id"]: entry for entry in manifest["versions"]}
+ alias_edges = set().union(
+ *(
+ docs_alias_equivalence_edges(
+ artifact_roots[version],
+ entries[version],
+ inventories[version],
+ )
+ for version in version_ids
+ )
+ )
+ result = {
+ "schemaVersion": 1,
+ "versions": list(version_ids),
+ "pages": {
+ logical_id: {
+ version: inventories[version].get(logical_id)
+ for version in version_ids
+ }
+ for logical_id in logical_ids
+ },
+ "equivalents": equivalence_groups(alias_edges, set(logical_ids)),
+ }
+ validate_version_routes(result, manifest)
+ return result
+
+
+def validate_version_routes(data: dict, manifest: dict) -> dict:
+ """Fail closed on route-map shape, ordering, locale, and target syntax."""
+ version_ids = manifest_version_ids(manifest)
+ if not isinstance(data, dict) or set(data) != {
+ "schemaVersion",
+ "versions",
+ "pages",
+ "equivalents",
+ }:
+ fail("invalid version route-map top-level fields")
+ if data["schemaVersion"] != 1 or data["versions"] != list(version_ids):
+ fail("invalid version route-map schema or version order")
+ pages = data["pages"]
+ if not isinstance(pages, dict) or not pages:
+ fail("version route-map pages must be a non-empty object")
+ for logical_id, targets in pages.items():
+ if (
+ not isinstance(logical_id, str)
+ or ":" not in logical_id
+ or logical_id.split(":", 1)[0] not in {"en", "cn"}
+ ):
+ fail(f"invalid version route-map logical ID: {logical_id!r}")
+ language, relative = logical_id.split(":", 1)
+ if (
+ relative.startswith("/")
+ or relative.endswith("/")
+ or ".." in pathlib.PurePosixPath(relative).parts
+ ):
+ fail(f"invalid version route-map logical path: {logical_id}")
+ if not isinstance(targets, dict) or list(targets) != list(version_ids):
+ fail(f"invalid version route-map target order: {logical_id}")
+ for version, target in targets.items():
+ if target is None:
+ continue
+ if (
+ not isinstance(target, str)
+ or target.startswith("/")
+ or not target.endswith("/")
+ or "?" in target
+ or "#" in target
+ or ".." in pathlib.PurePosixPath(target).parts
+ or target.startswith("versions/")
+ ):
+ fail(
+ f"invalid version route-map target for "
+ f"{logical_id} {version}: {target!r}"
+ )
+ target_language, target_relative = docs_target_parts(target)
+ if target_language != language:
+ fail(
+ f"version route-map target changes locale: "
+ f"{logical_id} -> {target}"
+ )
+ if normalize_logical_docs_route(version, target_relative) != relative:
+ fail(
+ f"version route-map target/logical mismatch for "
+ f"{logical_id} {version}: {target}"
+ )
+ equivalents = data["equivalents"]
+ if not isinstance(equivalents, list):
+ fail("version route-map equivalents must be an array")
+ if not all(
+ isinstance(group, list)
+ and all(isinstance(logical_id, str) for logical_id in group)
+ for group in equivalents
+ ):
+ fail("invalid version route-map equivalent group types")
+ if equivalents != sorted(equivalents):
+ fail("version route-map equivalent groups must be ordered")
+ seen_equivalents: set[str] = set()
+ for group in equivalents:
+ if (
+ not isinstance(group, list)
+ or len(group) < 2
+ or group != sorted(group)
+ or len(group) != len(set(group))
+ ):
+ fail(f"invalid version route-map equivalent group: {group!r}")
+ missing = set(group).difference(pages)
+ if missing:
+ fail(
+ "version route-map equivalent IDs are missing: "
+ + ", ".join(sorted(missing))
+ )
+ locales = {logical_id.split(":", 1)[0] for logical_id in group}
+ if len(locales) != 1:
+ fail(f"version route-map equivalent group changes locale: {group!r}")
+ overlap = seen_equivalents.intersection(group)
+ if overlap:
+ fail(
+ "version route-map equivalent ID is ambiguous: "
+ + ", ".join(sorted(overlap))
+ )
+ seen_equivalents.update(group)
+ for source_id in group:
+ for version in version_ids:
+ if pages[source_id][version] is not None:
+ continue
+ candidates = [
+ pages[candidate_id][version]
+ for candidate_id in group
+ if candidate_id != source_id
+ and pages[candidate_id][version] is not None
+ ]
+ if len(candidates) > 1:
+ fail(
+ f"version route-map equivalent target is ambiguous for "
+ f"{source_id} {version}: {candidates!r}"
+ )
+ return data
+
+
+def load_version_routes(
+ path: pathlib.Path = VERSION_ROUTES, manifest: dict | None = None
+) -> dict:
+ manifest = manifest or load_manifest(ROOT / "versions.json")
+ if not path.is_file():
+ fail(f"version route-map is missing: {path}")
+ try:
+ data = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError) as error:
+ fail(f"cannot load version route-map {path}: {error}")
+ return validate_version_routes(data, manifest)
+
+
+def canonical_docs_target(text: str, entry: dict) -> str | None:
+ """Resolve the current canonical page to an unscoped route-map target."""
+ document = DocumentParser()
+ document.feed(text)
+ if len(document.canonical) != 1:
+ return None
+ path = urllib.parse.urlsplit(document.canonical[0]).path
+ prefix = "/" + entry["publishPath"].strip("/") if entry["publishPath"] else ""
+ if prefix and (path == prefix or path.startswith(prefix + "/")):
+ path = path[len(prefix) :] or "/"
+ normalized = path.strip("/")
+ if normalized == "docs" or normalized.startswith("docs/"):
+ return normalized + "/"
+ if normalized == "cn/docs" or normalized.startswith("cn/docs/"):
+ return normalized + "/"
+ return None
+
+
+def logical_id_for_target(
+ route_map: dict, version: str, target: str
+) -> str | None:
+ matches = [
+ logical_id
+ for logical_id, targets in route_map["pages"].items()
+ if targets[version] == target
+ ]
+ if len(matches) > 1:
+ fail(f"ambiguous route-map target for {version}: {target}")
+ return matches[0] if matches else None
+
+
+def resolved_logical_target(
+ route_map: dict, logical_id: str, version: str
+) -> str | None:
+ """Prefer the canonical logical ID, then its unique reviewed equivalent."""
+ direct = route_map["pages"][logical_id][version]
+ if direct is not None:
+ return direct
+ group = next(
+ (
+ candidates
+ for candidates in route_map["equivalents"]
+ if logical_id in candidates
+ ),
+ (),
+ )
+ alternatives = [
+ route_map["pages"][candidate_id][version]
+ for candidate_id in group
+ if candidate_id != logical_id
+ and route_map["pages"][candidate_id][version] is not None
+ ]
+ if len(alternatives) > 1:
+ fail(
+ f"version route-map equivalent target is ambiguous for "
+ f"{logical_id} {version}: {alternatives!r}"
+ )
+ return alternatives[0] if alternatives else None
+
+
+def version_switch_options(
+ manifest: dict,
+ route_map: dict,
+ current_version: str,
+ current_target: str | None,
+ origin: str,
+ historical_origin: str | None = None,
+ *,
+ language: str | None = None,
+) -> list[dict]:
+ """Return page-aware version choices with explicit missing-page fallbacks."""
+ validate_version_routes(route_map, manifest)
+ logical_id = None
+ if current_target is not None:
+ target_language, _ = docs_target_parts(current_target)
+ language = target_language
+ logical_id = logical_id_for_target(route_map, current_version, current_target)
+ if logical_id is None:
+ fail(
+ f"current canonical Docs page is absent from route-map: "
+ f"{current_version} {current_target}"
+ )
+ if language not in {"en", "cn"}:
+ fail(f"version switch locale is unavailable: {language!r}")
+ options = []
+ for entry in manifest["versions"]:
+ entry_origin = (
+ historical_origin
+ if entry["archived"] and historical_origin is not None
+ else origin
+ )
+ equivalent = False
+ fallback = False
+ if logical_id is not None:
+ target = resolved_logical_target(
+ route_map, logical_id, entry["id"]
+ )
+ if target is not None:
+ equivalent = True
+ url = urllib.parse.urljoin(entry_origin.rstrip("/") + "/", (
+ f"{entry['publishPath'].rstrip('/')}/{target}"
+ if entry["publishPath"]
+ else target
+ ))
+ else:
+ fallback = True
+ root = "cn/docs/" if language == "cn" else "docs/"
+ path = (
+ f"{entry['publishPath'].rstrip('/')}/{root}"
+ if entry["publishPath"]
+ else root
+ )
+ url = (
+ urllib.parse.urljoin(entry_origin.rstrip("/") + "/", path)
+ + "#hg-version-fallback"
+ )
+ else:
+ root = "cn/docs/" if language == "cn" else "docs/"
+ path = (
+ f"{entry['publishPath'].rstrip('/')}/{root}"
+ if entry["publishPath"]
+ else root
+ )
+ url = urllib.parse.urljoin(entry_origin.rstrip("/") + "/", path)
+ options.append(
+ {
+ "id": entry["id"],
+ "title": entry["name"],
+ "url": url,
+ "active": entry["id"] == current_version,
+ "available": True,
+ "disabledReason": "",
+ "equivalent": equivalent,
+ "fallback": fallback,
+ }
+ )
+ return options
+
+
+def reviewed_version_route_urls(
+ manifest: dict,
+ route_map: dict,
+ origin: str,
+ historical_origin: str | None,
+) -> set[str]:
+ """Return only cross-version destinations authorized by the route-map."""
+ validate_version_routes(route_map, manifest)
+ urls: set[str] = set()
+ for logical_id, targets in route_map["pages"].items():
+ language = logical_id.split(":", 1)[0]
+ if not any(target is not None for target in targets.values()):
+ fail(f"route-map page has no targets: {logical_id}")
+ for entry in manifest["versions"]:
+ entry_origin = (
+ historical_origin
+ if entry["archived"] and historical_origin is not None
+ else origin
+ )
+ target = resolved_logical_target(
+ route_map, logical_id, entry["id"]
+ )
+ if target is None:
+ target = "cn/docs/" if language == "cn" else "docs/"
+ fragment = "#hg-version-fallback"
+ else:
+ fragment = ""
+ path = (
+ f"{entry['publishPath'].rstrip('/')}/{target}"
+ if entry["publishPath"]
+ else target
+ )
+ urls.add(
+ urllib.parse.urljoin(entry_origin.rstrip("/") + "/", path) + fragment
+ )
+ return urls
+
+
def scope_version_artifact(
output: pathlib.Path,
manifest: dict,
entry: dict,
origin: str,
+ historical_origin: str | None = None,
) -> dict:
"""Repair URL fields Hugo cannot canonify, then return auditable counts."""
- if not entry["publishPath"] and origin.rstrip("/") == CANONICAL_ORIGIN.rstrip("/"):
- return {"files": 0, "urls": 0, "manifests": 0, "searchRefs": 0}
+ route_map = load_version_routes(manifest=manifest)
allowed_paths = allowed_version_paths(manifest)
artifact_base = base_url(origin, entry["publishPath"])
+ reviewed_selector_urls = reviewed_version_route_urls(
+ manifest, route_map, origin, historical_origin
+ )
+ historical_selector_urls: set[str] = set()
+ if historical_origin is not None:
+ archived_ids = {
+ item["id"] for item in manifest["versions"] if item["archived"]
+ }
+ for language in ("en", "cn"):
+ for item in version_urls(
+ manifest, origin, language, historical_origin
+ ):
+ if item["version"] in archived_ids:
+ historical_selector_urls.update(
+ (item["url"], item["url"].rstrip("/"))
+ )
def rewrite(value: str) -> str:
- return rewrite_internal_url(
+ if value in reviewed_selector_urls or value in historical_selector_urls:
+ return value
+ rewritten = rewrite_internal_url(
value,
origin=origin,
publish_path=entry["publishPath"],
allowed_paths=allowed_paths,
+ version_id=entry["id"],
)
+ if entry.get("archived", bool(entry.get("publishPath"))):
+ original = urllib.parse.urlsplit(value)
+ original_path = original.path.rstrip("/") + "/"
+ version_prefix = "/" + entry["publishPath"]
+ if original_path.startswith(version_prefix + "/"):
+ original_path = original_path[len(version_prefix) :]
+ rewritten_parts = urllib.parse.urlsplit(rewritten)
+ scoped_relative = (
+ rewritten_parts.path[len("/" + entry["publishPath"]) :]
+ if rewritten_parts.path.startswith("/" + entry["publishPath"])
+ else rewritten_parts.path
+ )
+ if (
+ original_path in LATEST_SHARED_DOC_ROUTES
+ and not target_exists(output, scoped_relative)
+ ):
+ shared_origin = urllib.parse.urlsplit(origin.rstrip("/") + "/")
+ return urllib.parse.urlunsplit(
+ (
+ shared_origin.scheme,
+ shared_origin.netloc,
+ original_path,
+ original.query,
+ original.fragment,
+ )
+ )
+ if not target_exists(output, scoped_relative):
+ counterpart = (
+ "/cn" + scoped_relative
+ if scoped_relative.startswith("/docs/")
+ else scoped_relative.removeprefix("/cn")
+ if scoped_relative.startswith("/cn/docs/")
+ else ""
+ )
+ if counterpart and target_exists(output, counterpart):
+ counterpart_path = "/" + entry["publishPath"] + counterpart
+ return urllib.parse.urlunsplit(
+ (
+ urllib.parse.urlsplit(origin).scheme,
+ urllib.parse.urlsplit(origin).netloc,
+ counterpart_path,
+ original.query,
+ original.fragment,
+ )
+ )
+ if re.match(
+ r"^/(?:cn/)?docs/changelog/hugegraph-0\.[^/]+-release-notes/?$",
+ scoped_relative,
+ ):
+ language_prefix = "/cn" if scoped_relative.startswith("/cn/") else ""
+ changelog = f"{language_prefix}/docs/changelog/"
+ if target_exists(output, changelog):
+ return urllib.parse.urljoin(
+ base_url(origin, entry["publishPath"]),
+ changelog.lstrip("/"),
+ )
+ return rewritten
stats = {"files": 0, "urls": 0, "manifests": 0, "searchRefs": 0}
for path in sorted(output.rglob("*")):
@@ -1691,20 +2799,24 @@ def rewrite(value: str) -> str:
)
stats["files"] += 1
continue
- if path.suffix not in {".html", ".md", ".xml"}:
+ if path.suffix not in {".html", ".md", ".xml", ".txt"}:
continue
original = path.read_text(encoding="utf-8")
rendered, changed = rewrite_text_urls(
original,
rewrite,
- markdown=path.suffix == ".md",
+ markdown=path.suffix in {".md", ".txt"},
)
+ relative = path.relative_to(output).as_posix()
def replace_manifest(match: re.Match) -> str:
data = json.loads(match.group("body"))
rewritten = rewrite_json_urls(data, rewrite)
- scope_language_fallback_urls(
- rewritten, path.relative_to(output).as_posix(), artifact_base
+ normalize_language_switch_urls(
+ rewritten,
+ relative,
+ artifact_base,
+ output,
)
stats["manifests"] += 1
return (
@@ -1780,6 +2892,134 @@ def write_historical_home_redirects(output: pathlib.Path, origin: str) -> int:
return len(targets)
+def exclude_historical_sitemaps(output: pathlib.Path) -> int:
+ """Keep archived pages directly reachable without advertising them for indexing."""
+ removed = 0
+ for path in sorted(output.rglob("sitemap.xml")):
+ path.unlink()
+ removed += 1
+ robots = output / "robots.txt"
+ if robots.is_file():
+ robots.write_text("User-agent: *\nAllow: /\n", encoding="utf-8")
+ return removed
+
+
+def mark_historical_pages_noindex(output: pathlib.Path) -> int:
+ """Apply the archive indexing policy to every rendered historical page."""
+ changed = 0
+ for path in sorted(output.rglob("*.html")):
+ if path.name == "404.html":
+ continue
+ source = path.read_text(encoding="utf-8")
+ rendered, count = ROBOTS_META_RE.subn(
+ '', source
+ )
+ if count == 0:
+ rendered, count = re.subn(
+ r"",
+ '',
+ rendered,
+ count=1,
+ flags=re.IGNORECASE,
+ )
+ if count != 1:
+ fail(f"historical page must contain one head/robots marker: {path}")
+ if count:
+ path.write_text(rendered, encoding="utf-8")
+ changed += count
+ return changed
+
+
+def write_historical_route_aliases(
+ output: pathlib.Path, origin: str, publish_path: str
+) -> int:
+ """Create deterministic locale-aware redirects for migrated flat routes."""
+ written = 0
+ site_base = base_url(origin, publish_path)
+ for language_prefix in ("", "cn/"):
+ for old_relative, new_relative in LEGACY_IA_ROUTE_MAP.items():
+ old_route = language_prefix + "docs/" + old_relative.removesuffix(".md")
+ old_route = old_route.replace("/README", "")
+ new_route = language_prefix + "docs/" + new_relative.removesuffix(".md")
+ target = output / new_route / "index.html"
+ if not target.is_file():
+ continue
+ alias = output / old_route / "index.html"
+ if alias.exists():
+ fail(f"historical alias collides with rendered output: {alias}")
+ alias.parent.mkdir(parents=True, exist_ok=True)
+ target_url = urllib.parse.urljoin(site_base, new_route.rstrip("/") + "/")
+ escaped = html.escape(target_url, quote=True)
+ alias.write_text(
+ "\n"
+ '\n'
+ '\n'
+ f'\n'
+ f'\n'
+ f'Continue\n',
+ encoding="utf-8",
+ )
+ written += 1
+ return written
+
+
+def remove_non_equivalent_hreflang(
+ output: pathlib.Path, origin: str, publish_path: str
+) -> int:
+ """Remove Hugo language fallbacks from hreflang while keeping real translations."""
+ removed = 0
+ prefix = "/" + publish_path.strip("/") if publish_path else ""
+ origin_parts = urllib.parse.urlsplit(origin.rstrip("/") + "/")
+ for path in sorted(output.rglob("*.html")):
+ relative = path.relative_to(output).as_posix()
+ if relative in {"404.html", "cn/404.html"} or "_print/" in relative:
+ continue
+ current_url = public_url_for_file(path, output, origin, publish_path)
+ current_path = urllib.parse.urlsplit(current_url).path
+ cn_prefix = prefix + "/cn/"
+ if current_path.startswith(cn_prefix):
+ english_path = prefix + current_path[len(prefix + "/cn") :]
+ else:
+ english_path = current_path
+ chinese_path = (
+ prefix + "/cn/"
+ if english_path.rstrip("/") == prefix
+ else prefix + "/cn" + english_path[len(prefix) :]
+ )
+ expected_paths = {"en-US": english_path, "zh-CN": chinese_path}
+
+ def keep_equivalent(match: re.Match) -> str:
+ nonlocal removed
+ parser = DocumentParser()
+ parser.feed(match.group(0))
+ if len(parser.hreflang) != 1:
+ fail(f"cannot parse hreflang link in {relative}: {match.group(0)}")
+ language, href = parser.hreflang[0]
+ expected_path = expected_paths.get(language)
+ href_parts = urllib.parse.urlsplit(
+ urllib.parse.urljoin(current_url, href)
+ )
+ local_relative = (
+ expected_path[len(prefix) :] if prefix and expected_path else expected_path
+ )
+ if (
+ expected_path is not None
+ and href_parts.scheme == origin_parts.scheme
+ and href_parts.netloc == origin_parts.netloc
+ and href_parts.path == expected_path
+ and target_exists(output, local_relative or "/")
+ ):
+ return match.group(0)
+ removed += 1
+ return ""
+
+ source = path.read_text(encoding="utf-8")
+ rendered = HREFLANG_LINK_RE.sub(keep_equivalent, source)
+ if rendered != source:
+ path.write_text(rendered, encoding="utf-8")
+ return removed
+
+
def public_url_for_file(
path: pathlib.Path,
root: pathlib.Path,
@@ -1804,6 +3044,87 @@ def target_exists(root: pathlib.Path, relative: str) -> bool:
return candidate.is_file() or (candidate / "index.html").is_file()
+def validate_artifact_alias_target(
+ value: str,
+ root: pathlib.Path,
+ entry: dict,
+ expected_base: str,
+ source: str,
+) -> str:
+ """Require an ordinary refresh alias to resolve inside its version artifact."""
+ if (
+ not value
+ or not value.startswith(("http://", "https://", "/"))
+ or any(char in value for char in ("?", "#", "%", "\\"))
+ or any(
+ char.isspace() or ord(char) < 0x20 or ord(char) == 0x7F
+ for char in value
+ )
+ ):
+ fail(f"alias target is not canonical in {source}: {value}")
+ absolute_http = value.startswith(("http://", "https://"))
+ require_safe_url_syntax(value)
+ if not require_safe_url_scheme(value, source):
+ fail(f"alias target uses a non-HTTP protocol in {source}: {value}")
+ try:
+ target = urllib.parse.urlsplit(value)
+ base = urllib.parse.urlsplit(expected_base)
+ require_safe_http_authority(target, value)
+ require_safe_http_authority(base, expected_base)
+ except (TypeError, ValueError) as exc:
+ fail(f"alias target is malformed in {source}: {value}: {exc}")
+ if (
+ base.scheme.lower() not in {"http", "https"}
+ or not base.netloc
+ or base.query
+ or base.fragment
+ ):
+ fail(f"artifact baseURL is malformed for {entry['id']}: {expected_base}")
+ if absolute_http and (not target.scheme or not target.netloc):
+ fail(f"absolute alias target has no authority in {source}: {value}")
+ if target.netloc and (
+ target.scheme.lower() != base.scheme.lower()
+ or target.netloc.lower() != base.netloc.lower()
+ ):
+ fail(f"alias target leaves the configured origin in {source}: {value}")
+ path = target.path
+ segments = path.split("/")
+ if (
+ not path.startswith("/")
+ or "//" in path
+ or any(segment in {".", ".."} for segment in segments)
+ ):
+ fail(f"alias target path is unsafe in {source}: {value}")
+ prefix = "/" + entry["publishPath"].strip("/") if entry["publishPath"] else ""
+ if prefix and not (path == prefix or path.startswith(prefix + "/")):
+ fail(f"alias target escapes version {entry['id']} in {source}: {value}")
+ relative = path[len(prefix) :] if prefix else path
+ if not target_exists(root, relative):
+ fail(f"alias target is missing in {source}: {value}")
+ return path
+
+
+def validate_historical_home_alias_target(
+ value: str,
+ relative: str,
+ site_origin: str,
+) -> None:
+ """Allow only the two reviewed archive-home redirects to shared latest pages."""
+ suffixes = {
+ "index.html": "",
+ "cn/index.html": "cn/",
+ }
+ suffix = suffixes.get(relative)
+ if suffix is None:
+ fail(f"unexpected historical home alias path: {relative}")
+ expected = urllib.parse.urljoin(site_origin.rstrip("/") + "/", suffix)
+ if value != expected:
+ fail(
+ f"historical home alias target changed in {relative}: "
+ f"{value} != {expected}"
+ )
+
+
def iter_json_strings(value):
if isinstance(value, dict):
for item in value.values():
@@ -1859,8 +3180,170 @@ def require_docs_navigation_json(data: dict, source: str, language: str) -> None
fail(f"private Docs navigation route leaked into {source}")
+def validate_llms_full_outputs(
+ root: pathlib.Path, entry: dict, expected_base: str
+) -> None:
+ """Require locale-bound latest corpora and prohibit them in archives."""
+ outputs = {
+ "en": root / "docs/llms-full.txt",
+ "cn": root / "cn/docs/llms-full.txt",
+ }
+ if entry["archived"]:
+ leaked = [
+ path.relative_to(root).as_posix()
+ for path in outputs.values()
+ if path.exists()
+ ]
+ if leaked:
+ fail(
+ "historical artifact must not contain LLMSFULL output: "
+ + ", ".join(leaked)
+ )
+ return
+ contracts = {
+ "en": (
+ urllib.parse.urljoin(expected_base, "docs/index.md"),
+ "LLMS index:",
+ "](/llms.txt)",
+ "LLMS 索引：",
+ ),
+ "cn": (
+ urllib.parse.urljoin(expected_base, "cn/docs/index.md"),
+ "LLMS 索引：",
+ "](/cn/llms.txt)",
+ "LLMS index:",
+ ),
+ }
+ for language, path in outputs.items():
+ label = "English" if language == "en" else "Chinese"
+ if not path.is_file():
+ fail(f"{label} LLMSFULL output is missing: {path.relative_to(root)}")
+ text = path.read_text(encoding="utf-8")
+ canonical_source, marker, index_link, forbidden = contracts[language]
+ if (
+ marker not in text
+ or index_link not in text
+ or forbidden in text
+ ):
+ fail(f"{label} LLMSFULL locale contract is invalid")
+ source_rows = [
+ line for line in text.splitlines() if line.startswith("Source:")
+ ]
+ sources = [line.removeprefix("Source:").strip() for line in source_rows]
+ if (
+ not sources
+ or any(not line.startswith("Source: ") for line in source_rows)
+ or any(not value for value in sources)
+ ):
+ fail(f"{label} LLMSFULL source is missing or malformed")
+ if sources[0] != canonical_source:
+ fail(f"{label} LLMSFULL canonical source is not first")
+ expected_parts = urllib.parse.urlsplit(expected_base)
+ locale_root = "cn/docs/" if language == "cn" else "docs/"
+ expected_path_prefix = urllib.parse.urlsplit(
+ urllib.parse.urljoin(expected_base, locale_root)
+ ).path
+ canonical_sources: set[str] = set()
+ for value in sources:
+ if "?" in value or "#" in value or "%" in value:
+ fail(f"{label} LLMSFULL source is not canonical: {value}")
+ try:
+ require_safe_url_syntax(value)
+ parts = urllib.parse.urlsplit(value)
+ require_safe_http_authority(parts, value)
+ except (TypeError, ValueError) as exc:
+ fail(f"{label} LLMSFULL source is malformed: {value}: {exc}")
+ decoded_path = urllib.parse.unquote(parts.path)
+ path_segments = parts.path.split("/")
+ if (
+ any(char.isspace() for char in value)
+ or parts.scheme.lower() != expected_parts.scheme.lower()
+ or parts.netloc != expected_parts.netloc
+ or parts.query
+ or parts.fragment
+ or "\\" in decoded_path
+ or "//" in parts.path
+ or any(segment in {".", ".."} for segment in path_segments)
+ or not decoded_path.startswith(expected_path_prefix)
+ or not decoded_path.endswith(".md")
+ or ".." in pathlib.PurePosixPath(decoded_path).parts
+ ):
+ fail(f"{label} LLMSFULL source is outside its artifact: {value}")
+ canonical = urllib.parse.urlunsplit(
+ (
+ parts.scheme.lower(),
+ parts.netloc.lower(),
+ decoded_path,
+ "",
+ "",
+ )
+ )
+ if canonical in canonical_sources:
+ fail(f"{label} LLMSFULL source is duplicated: {value}")
+ canonical_sources.add(canonical)
+
+
+def validate_social_image_metadata(
+ document: DocumentParser,
+ relative: str,
+ root: pathlib.Path,
+ expected_base: str,
+ *,
+ allow_missing: bool = False,
+) -> None:
+ """Require matching same-artifact Open Graph and Twitter image targets."""
+ values: dict[str, list[str]] = {"og:image": [], "twitter:image": []}
+ for item in document.meta:
+ if item.get("property", "").lower() == "og:image":
+ values["og:image"].append(item.get("content", ""))
+ if item.get("name", "").lower() == "twitter:image":
+ values["twitter:image"].append(item.get("content", ""))
+ if allow_missing and not values["og:image"] and not values["twitter:image"]:
+ return
+ if any(len(items) != 1 or not items[0] for items in values.values()):
+ fail(f"social image metadata is missing or duplicated in {relative}")
+ og_image = values["og:image"][0]
+ twitter_image = values["twitter:image"][0]
+ if og_image != twitter_image:
+ fail(f"social image metadata differs in {relative}")
+ value = og_image
+ if "?" in value or "#" in value or "%" in value or "\\" in value:
+ fail(f"social image URL is not canonical in {relative}: {value}")
+ try:
+ parts = urllib.parse.urlsplit(value)
+ base = urllib.parse.urlsplit(expected_base)
+ require_safe_http_authority(parts, value)
+ except (TypeError, ValueError) as exc:
+ fail(f"social image URL is malformed in {relative}: {value}: {exc}")
+ if parts.scheme:
+ if (
+ parts.scheme.lower() != "https"
+ or parts.netloc.lower() != base.netloc.lower()
+ ):
+ fail(f"social image URL is outside the artifact in {relative}: {value}")
+ elif parts.netloc or not value.startswith("/"):
+ fail(f"social image URL must be absolute in {relative}: {value}")
+ base_path = base.path.rstrip("/") + "/"
+ image_path = parts.path
+ if not image_path.startswith(base_path):
+ fail(f"social image URL is outside the artifact in {relative}: {value}")
+ artifact_relative = image_path[len(base_path) :]
+ suffix = pathlib.PurePosixPath(artifact_relative).suffix.lower()
+ if (
+ not artifact_relative
+ or artifact_relative.startswith("/")
+ or ".." in pathlib.PurePosixPath(artifact_relative).parts
+ or suffix not in {".gif", ".jpeg", ".jpg", ".png", ".svg", ".webp"}
+ ):
+ fail(f"social image URL is not an image in {relative}: {value}")
+ target = root / pathlib.PurePosixPath(artifact_relative)
+ if not target.is_file():
+ fail(f"social image target is missing in {relative}: {value}")
+
+
def validate_artifact(args: argparse.Namespace) -> None:
manifest = load_manifest(args.manifest)
+ route_map = load_version_routes(manifest=manifest)
entry = next(
(item for item in manifest["versions"] if item["id"] == args.version), None
)
@@ -1877,6 +3360,8 @@ def validate_artifact(args: argparse.Namespace) -> None:
require_metadata_matches(expected_entry, metadata, metadata_path)
if metadata.get("baseURL") != expected_base:
fail(f"version metadata does not match {entry['id']} at {expected_base}")
+ validate_output_security(root, expected_base)
+ validate_llms_full_outputs(root, entry, expected_base)
docs_navigation = metadata.get("docsNavigation")
expected_docs_navigation = DOCS_NAV_EXPECTED_STATS[entry["id"]]
if docs_navigation != expected_docs_navigation:
@@ -1903,6 +3388,12 @@ def validate_artifact(args: argparse.Namespace) -> None:
canonical_host = same_site_host(canonical_parts)
prefix = "/" + entry["publishPath"].strip("/") if entry["publishPath"] else ""
allowed_paths = allowed_version_paths(manifest)
+ reviewed_route_urls = reviewed_version_route_urls(
+ manifest,
+ route_map,
+ args.site_origin,
+ getattr(args, "historical_origin", None),
+ )
current_docs = (prefix + "/docs").rstrip("/") or "/docs"
checked_urls = 0
canonical_pages = 0
@@ -1951,6 +3442,9 @@ def validate_url(value: str, source: pathlib.Path) -> None:
nonlocal checked_urls
if not value or value.startswith(("#", "?")):
return
+ if value in reviewed_route_urls:
+ checked_urls += 1
+ return
source_name = source.relative_to(root).as_posix()
require_safe_url_syntax(value)
if not require_safe_url_scheme(value, source_name):
@@ -1965,6 +3459,18 @@ def validate_url(value: str, source: pathlib.Path) -> None:
):
fail(f"unsafe same-site URL authority in {source_name}: {value}")
if parsed_host == canonical_host and parsed_host != origin_host:
+ historical_docs_prefixes = tuple(
+ "/" + item["publishPath"] + suffix
+ for item in manifest["versions"]
+ if item["archived"]
+ for suffix in ("/docs", "/cn/docs")
+ )
+ if any(
+ parsed.path == prefix or parsed.path.startswith(prefix + "/")
+ for prefix in historical_docs_prefixes
+ ):
+ checked_urls += 1
+ return
fail(f"production-origin URL leaked into staging {source_name}: {value}")
if parsed.netloc and parsed_host != origin_host:
return
@@ -1991,6 +3497,10 @@ def validate_url(value: str, source: pathlib.Path) -> None:
)
path = parsed.path or "/"
normalized = path.rstrip("/") or "/"
+ normalized_with_slash = normalized.rstrip("/") + "/"
+ if normalized_with_slash in LATEST_SHARED_DOC_ROUTES:
+ checked_urls += 1
+ return
if (
parsed.netloc
and (normalized in allowed_paths or is_latest_shared_path(normalized))
@@ -2119,10 +3629,40 @@ def validate_url(value: str, source: pathlib.Path) -> None:
fail(f"404 page does not use the interactive OINK shell: {relative}")
document = DocumentParser()
document.feed(text)
- require_toc_accessible_name(document, relative)
alias_target = refresh_target(document)
+ validate_social_image_metadata(
+ document,
+ relative,
+ root,
+ expected_base,
+ allow_missing=alias_target is not None,
+ )
+ require_toc_accessible_name(document, relative)
+ if entry["archived"] and relative not in {"404.html", "cn/404.html"}:
+ robots = [
+ re.sub(r"\s+", "", item.get("content", "").lower())
+ for item in document.meta
+ if item.get("name", "").lower() == "robots"
+ ]
+ if robots != ["noindex,follow"]:
+ fail(f"historical page must be noindex,follow: {relative}: {robots!r}")
if alias_target:
- validate_url(alias_target, path)
+ if relative != "client-go/index.html":
+ if entry["archived"] and relative in {"index.html", "cn/index.html"}:
+ validate_historical_home_alias_target(
+ alias_target,
+ relative,
+ args.site_origin,
+ )
+ else:
+ validate_artifact_alias_target(
+ alias_target,
+ root,
+ entry,
+ expected_base,
+ relative,
+ )
+ checked_urls += 1
action_data = {}
manifests = list(ACTION_MANIFEST_RE.finditer(text))
if manifests:
@@ -2160,25 +3700,22 @@ def validate_url(value: str, source: pathlib.Path) -> None:
None,
)
language = "cn" if relative.startswith("cn/") else "en"
- expected_options = version_urls(manifest, args.site_origin, language)
- if switch is None or [
- (
- item.get("id"),
- item.get("title"),
- str(item.get("url", "")).rstrip("/"),
- item.get("active"),
- )
- for item in switch.get("options", [])
- ] != [
- (
- item["version"],
- item["name"],
- item["url"].rstrip("/"),
- item["version"] == entry["id"],
- )
- for item in expected_options
- ]:
+ current_target = canonical_docs_target(text, entry)
+ expected_options = version_switch_options(
+ manifest,
+ route_map,
+ entry["id"],
+ current_target,
+ args.site_origin,
+ getattr(args, "historical_origin", None),
+ language=language,
+ )
+ if switch is None or switch.get("options") != expected_options:
fail(f"version switch contract mismatch in {path.relative_to(root)}")
+ if not relative.startswith(("_print/", "cn/_print/")):
+ require_version_switch_matches_native(
+ document, expected_options, relative
+ )
if (
entry["archived"]
and relative not in archive_exceptions
@@ -2265,7 +3802,7 @@ def validate_url(value: str, source: pathlib.Path) -> None:
if english_path.rstrip("/") == prefix
else prefix + "/cn" + english_path[len(prefix) :]
)
- expected_hreflang = {
+ equivalent_urls = {
"en-US": urllib.parse.urlunsplit(
(origin_parts.scheme, origin_parts.netloc, english_path, "", "")
),
@@ -2273,10 +3810,15 @@ def validate_url(value: str, source: pathlib.Path) -> None:
(origin_parts.scheme, origin_parts.netloc, chinese_path, "", "")
),
}
- for language, fallback_path in HREFLANG_FALLBACKS.get(relative, {}).items():
- expected_hreflang[language] = urllib.parse.urljoin(
- expected_base, fallback_path.lstrip("/")
- )
+ equivalent_paths = {
+ "en-US": english_path[len(prefix) :] if prefix else english_path,
+ "zh-CN": chinese_path[len(prefix) :] if prefix else chinese_path,
+ }
+ expected_hreflang = {
+ language: url
+ for language, url in equivalent_urls.items()
+ if target_exists(root, equivalent_paths[language])
+ }
if actual_hreflang != expected_hreflang:
fail(
f"hreflang mismatch in {relative}: "
@@ -2285,7 +3827,12 @@ def validate_url(value: str, source: pathlib.Path) -> None:
validate_language_switch_contract(
action_data,
relative,
- expected_hreflang,
+ {
+ "en-US": expected_hreflang.get("en-US", expected_base),
+ "zh-CN": expected_hreflang.get(
+ "zh-CN", urllib.parse.urljoin(expected_base, "cn/")
+ ),
+ },
current_path,
"zh-CN" if relative.startswith("cn/") else "en-US",
)
@@ -2337,6 +3884,64 @@ def validate_url(value: str, source: pathlib.Path) -> None:
)
+def derived_version_config(
+ manifest: dict,
+ entry: dict,
+ site_origin: str,
+ historical_origin: str | None = None,
+) -> dict:
+ """Derive every Hugo version-menu value from versions.json."""
+ override = {
+ "baseURL": base_url(site_origin, entry["publishPath"]),
+ "canonifyURLs": True,
+ "params": {
+ "version": entry["id"],
+ "version_menu": "Releases",
+ "version_menu_pagelinks": False,
+ "versions": version_urls(
+ manifest, site_origin, "en", historical_origin
+ ),
+ "archived_version": bool(entry["archived"]),
+ "url_latest_version": urllib.parse.urljoin(
+ site_origin.rstrip("/") + "/", "docs/"
+ ),
+ "github_repo": "https://github.com/apache/hugegraph-doc",
+ "github_branch": entry["githubBranch"],
+ },
+ }
+ language_overrides = (
+ historical_language_menus(site_origin)
+ if entry["archived"]
+ else {"en": {}, "cn": {}}
+ )
+ for language in ("en", "cn"):
+ language_overrides[language]["params"] = language_version_params(
+ manifest,
+ site_origin,
+ language,
+ historical_origin,
+ )
+ override["languages"] = language_overrides
+ return override
+
+
+def render_config(args: argparse.Namespace) -> None:
+ """Write the manifest-derived override used by direct Hugo commands."""
+ manifest = load_manifest(args.manifest)
+ version_id = args.version or manifest["versions"][0]["id"]
+ entry = next(
+ (item for item in manifest["versions"] if item["id"] == version_id), None
+ )
+ if entry is None:
+ fail(f"unknown version {version_id}")
+ override = derived_version_config(
+ manifest, entry, args.site_origin, args.historical_origin
+ )
+ rendered = json.dumps(override, ensure_ascii=False, sort_keys=True, indent=2) + "\n"
+ args.output.write_text(rendered, encoding="utf-8")
+ print(f"rendered Hugo config for {entry['id']} -> {args.output}")
+
+
def build(args: argparse.Namespace) -> None:
manifest = load_manifest(args.manifest)
entry = next(
@@ -2379,32 +3984,9 @@ def build(args: argparse.Namespace) -> None:
origin=args.site_origin,
)
site_base = base_url(args.site_origin, entry["publishPath"])
- override = {
- "baseURL": site_base,
- "canonifyURLs": True,
- "params": {
- "version": entry["id"],
- "version_menu": "Releases",
- "version_menu_pagelinks": False,
- "versions": version_urls(manifest, args.site_origin, "en"),
- "archived_version": bool(entry["archived"]),
- "url_latest_version": urllib.parse.urljoin(
- args.site_origin.rstrip("/") + "/", "docs/"
- ),
- "github_repo": "https://github.com/apache/hugegraph-doc",
- "github_branch": entry["githubBranch"],
- },
- }
- language_overrides = (
- historical_language_menus(args.site_origin)
- if entry["archived"]
- else {"en": {}, "cn": {}}
+ override = derived_version_config(
+ manifest, entry, args.site_origin, args.historical_origin
)
- for language in ("en", "cn"):
- language_overrides[language]["params"] = language_version_params(
- manifest, args.site_origin, language
- )
- override["languages"] = language_overrides
override_path = assembly / "version-config.json"
override_path.write_text(
json.dumps(override, ensure_ascii=False), encoding="utf-8"
@@ -2456,6 +4038,9 @@ def build(args: argparse.Namespace) -> None:
cwd=assembly,
check=True,
)
+ route_migrations = migrate_legacy_information_architecture(
+ assembly, entry["id"]
+ )
known_fixes = apply_known_legacy_fixes(assembly, entry["id"])
docs_navigation = materialize_docs_navigation(assembly, entry["publishPath"])
subprocess.run(
@@ -2494,11 +4079,28 @@ def build(args: argparse.Namespace) -> None:
go_directory + os.pathsep + build_environment.get("PATH", "")
)
subprocess.run(command, cwd=assembly, check=True, env=build_environment)
+ route_aliases = (
+ write_historical_route_aliases(
+ output, args.site_origin, entry["publishPath"]
+ )
+ if entry["id"] in {"1.3", "1.0"}
+ else 0
+ )
+ archived_noindex = (
+ mark_historical_pages_noindex(output) if entry["archived"] else 0
+ )
+ non_equivalent_hreflang = remove_non_equivalent_hreflang(
+ output, args.site_origin, entry["publishPath"]
+ )
+ historical_sitemaps = (
+ exclude_historical_sitemaps(output) if entry["archived"] else 0
+ )
url_scoping = scope_version_artifact(
output,
manifest,
entry,
args.site_origin,
+ args.historical_origin,
)
url_scoping["historicalHomeRedirects"] = (
write_historical_home_redirects(output, args.site_origin)
@@ -2534,10 +4136,15 @@ def build(args: argparse.Namespace) -> None:
for item in migration_data.get("files", [])
),
"knownFixes": known_fixes,
+ "routeMigrations": route_migrations,
"residual": 0,
},
"docsNavigation": docs_navigation,
"urlScoping": url_scoping,
+ "historicalSitemapsRemoved": historical_sitemaps,
+ "historicalNoindexPages": archived_noindex,
+ "historicalRouteAliases": route_aliases,
+ "nonEquivalentHreflangRemoved": non_equivalent_hreflang,
}
)
(output / ".version.json").write_text(
@@ -2558,13 +4165,6 @@ def write_aggregate_sitemap(output: pathlib.Path, origin: str, manifest: dict) -
urllib.parse.urljoin(origin.rstrip("/") + "/", "en/sitemap.xml"),
urllib.parse.urljoin(origin.rstrip("/") + "/", "cn/sitemap.xml"),
]
- for entry in manifest["versions"]:
- if entry["publishPath"]:
- locations.append(
- urllib.parse.urljoin(
- origin.rstrip("/") + "/", entry["publishPath"] + "/sitemap.xml"
- )
- )
root = ET.Element(
"sitemapindex", xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
)
@@ -2638,14 +4238,71 @@ def validate_output_security(output: pathlib.Path, site_origin: str) -> None:
)
+def validate_aggregate_version_routes(
+ output: pathlib.Path,
+ route_map: dict,
+ selected: set[str],
+ manifest: dict,
+) -> None:
+ """Prove every selected route target exists and every selected null is real."""
+ validate_version_routes(route_map, manifest)
+ version_ids = manifest_version_ids(manifest)
+ publish_paths = {
+ entry["id"]: entry["publishPath"] for entry in manifest["versions"]
+ }
+ selected = set(selected)
+ unknown = selected.difference(version_ids)
+ if unknown:
+ fail(f"cannot validate unknown route-map versions: {sorted(unknown)!r}")
+ for version in version_ids:
+ if version not in selected:
+ continue
+ if version not in publish_paths:
+ fail(f"route-map publish path is missing for {version}")
+ version_root = output / publish_paths[version]
+ actual = canonical_docs_pages(version_root, version)
+ for logical_id, targets in route_map["pages"].items():
+ expected = targets[version]
+ observed = actual.get(logical_id)
+ if expected is None:
+ if observed is not None:
+ fail(
+ f"route-map null target exists for "
+ f"{version} {logical_id}: {observed}"
+ )
+ continue
+ if observed is None:
+ fail(
+ f"route-map target is missing for "
+ f"{version} {logical_id}: {expected}"
+ )
+ if observed != expected:
+ fail(
+ f"route-map target drift for {version} {logical_id}: "
+ f"{observed} != {expected}"
+ )
+ extras = sorted(set(actual).difference(route_map["pages"]))
+ if extras:
+ fail(
+ f"canonical Docs pages are absent from route-map for "
+ f"{version}: {extras}"
+ )
+
+
def aggregate(args: argparse.Namespace) -> None:
manifest = load_resolved_manifest(args.resolved_manifest)
+ selected = selected_version_ids(getattr(args, "select", None), manifest)
output = prepare_output_directory(args.output, "aggregate output")
output.mkdir(parents=True)
seen: set[str] = set()
resolved = []
for entry in manifest["versions"]:
- source = args.artifacts / f"{args.artifact_prefix}{entry['id']}"
+ if entry["id"] not in selected:
+ continue
+ source = args.artifacts / (
+ f"{args.artifact_prefix}{entry['id']}"
+ f"{getattr(args, 'artifact_suffix', '')}"
+ )
metadata_path = source / ".version.json"
if not metadata_path.is_file():
fail(f"missing version metadata: {metadata_path}")
@@ -2657,6 +4314,7 @@ def aggregate(args: argparse.Namespace) -> None:
version=entry["id"],
sha=entry["sha"],
site_origin=args.site_origin,
+ historical_origin=getattr(args, "historical_origin", None),
artifact=source,
)
)
@@ -2698,6 +4356,17 @@ def aggregate(args: argparse.Namespace) -> None:
+ "\n",
encoding="utf-8",
)
+ route_map = load_version_routes(manifest=manifest)
+ (metadata_dir / "version-routes.json").write_text(
+ json.dumps(route_map, ensure_ascii=False, sort_keys=False, indent=2) + "\n",
+ encoding="utf-8",
+ )
+ validate_aggregate_version_routes(
+ output,
+ route_map,
+ selected,
+ manifest,
+ )
validate_output_security(output, args.site_origin)
print(
f"aggregated {len(resolved)} versions and {len(seen)} files "
@@ -2705,6 +4374,23 @@ def aggregate(args: argparse.Namespace) -> None:
)
+def generate_routes(args: argparse.Namespace) -> None:
+ manifest = load_manifest(args.manifest)
+ version_ids = manifest_version_ids(manifest)
+ roots = {
+ version: args.artifacts
+ / f"{args.artifact_prefix}{version}{args.artifact_suffix}"
+ for version in version_ids
+ }
+ data = generate_version_routes(roots, manifest)
+ args.output.parent.mkdir(parents=True, exist_ok=True)
+ args.output.write_text(
+ json.dumps(data, ensure_ascii=False, sort_keys=False, indent=2) + "\n",
+ encoding="utf-8",
+ )
+ print(f"generated {len(data['pages'])} logical version routes -> {args.output}")
+
+
def parser() -> argparse.ArgumentParser:
result = argparse.ArgumentParser(description=__doc__)
result.add_argument("--manifest", type=pathlib.Path, default=ROOT / "versions.json")
@@ -2713,13 +4399,22 @@ def parser() -> argparse.ArgumentParser:
prepare_parser = commands.add_parser("prepare")
prepare_parser.add_argument("--local", action="store_true")
prepare_parser.add_argument("--latest-sha", default="HEAD")
+ prepare_parser.add_argument("--select")
prepare_parser.add_argument("--output", type=pathlib.Path)
prepare_parser.set_defaults(func=prepare)
+ config_parser = commands.add_parser("config")
+ config_parser.add_argument("--version")
+ config_parser.add_argument("--site-origin", default=CANONICAL_ORIGIN)
+ config_parser.add_argument("--historical-origin")
+ config_parser.add_argument("--output", type=pathlib.Path, required=True)
+ config_parser.set_defaults(func=render_config)
+
build_parser = commands.add_parser("build")
build_parser.add_argument("--version", required=True)
build_parser.add_argument("--sha", required=True)
build_parser.add_argument("--site-origin", required=True)
+ build_parser.add_argument("--historical-origin")
build_parser.add_argument("--output", type=pathlib.Path, required=True)
build_parser.set_defaults(func=build)
@@ -2727,20 +4422,33 @@ def parser() -> argparse.ArgumentParser:
validate_parser.add_argument("--version", required=True)
validate_parser.add_argument("--sha", required=True)
validate_parser.add_argument("--site-origin", required=True)
+ validate_parser.add_argument("--historical-origin")
validate_parser.add_argument("--artifact", type=pathlib.Path, required=True)
validate_parser.set_defaults(func=validate_artifact)
aggregate_parser = commands.add_parser("aggregate")
aggregate_parser.add_argument("--artifacts", type=pathlib.Path, required=True)
aggregate_parser.add_argument("--artifact-prefix", default="")
+ aggregate_parser.add_argument("--artifact-suffix", default="")
aggregate_parser.add_argument(
"--resolved-manifest", type=pathlib.Path, required=True
)
aggregate_parser.add_argument("--site-origin", required=True)
+ aggregate_parser.add_argument("--historical-origin")
+ aggregate_parser.add_argument("--select")
aggregate_parser.add_argument("--output", type=pathlib.Path, required=True)
aggregate_parser.add_argument("--asf-profile")
aggregate_parser.add_argument("--asf-whoami")
aggregate_parser.set_defaults(func=aggregate)
+
+ routes_parser = commands.add_parser("routes")
+ routes_parser.add_argument("--artifacts", type=pathlib.Path, required=True)
+ routes_parser.add_argument("--artifact-prefix", default="")
+ routes_parser.add_argument("--artifact-suffix", default="")
+ routes_parser.add_argument(
+ "--output", type=pathlib.Path, default=VERSION_ROUTES
+ )
+ routes_parser.set_defaults(func=generate_routes)
return result
diff --git a/static/img/bootstrap-controls/accordion-active-dark.svg b/static/img/bootstrap-controls/accordion-active-dark.svg
new file mode 100644
index 000000000..3d4bc8f71
--- /dev/null
+++ b/static/img/bootstrap-controls/accordion-active-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/accordion-active.svg b/static/img/bootstrap-controls/accordion-active.svg
new file mode 100644
index 000000000..84298341e
--- /dev/null
+++ b/static/img/bootstrap-controls/accordion-active.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/accordion-dark.svg b/static/img/bootstrap-controls/accordion-dark.svg
new file mode 100644
index 000000000..3d4bc8f71
--- /dev/null
+++ b/static/img/bootstrap-controls/accordion-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/accordion.svg b/static/img/bootstrap-controls/accordion.svg
new file mode 100644
index 000000000..1c53db8c3
--- /dev/null
+++ b/static/img/bootstrap-controls/accordion.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/carousel-next.svg b/static/img/bootstrap-controls/carousel-next.svg
new file mode 100644
index 000000000..75822e384
--- /dev/null
+++ b/static/img/bootstrap-controls/carousel-next.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/carousel-prev.svg b/static/img/bootstrap-controls/carousel-prev.svg
new file mode 100644
index 000000000..27a6b32a6
--- /dev/null
+++ b/static/img/bootstrap-controls/carousel-prev.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/check-checked.svg b/static/img/bootstrap-controls/check-checked.svg
new file mode 100644
index 000000000..55c82bbbc
--- /dev/null
+++ b/static/img/bootstrap-controls/check-checked.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/check-indeterminate.svg b/static/img/bootstrap-controls/check-indeterminate.svg
new file mode 100644
index 000000000..8769f308d
--- /dev/null
+++ b/static/img/bootstrap-controls/check-indeterminate.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/close.svg b/static/img/bootstrap-controls/close.svg
new file mode 100644
index 000000000..fca539ec7
--- /dev/null
+++ b/static/img/bootstrap-controls/close.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/navbar-dark.svg b/static/img/bootstrap-controls/navbar-dark.svg
new file mode 100644
index 000000000..d18a64367
--- /dev/null
+++ b/static/img/bootstrap-controls/navbar-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/navbar-light.svg b/static/img/bootstrap-controls/navbar-light.svg
new file mode 100644
index 000000000..7dc3ddfb3
--- /dev/null
+++ b/static/img/bootstrap-controls/navbar-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/radio-checked.svg b/static/img/bootstrap-controls/radio-checked.svg
new file mode 100644
index 000000000..59849bd2a
--- /dev/null
+++ b/static/img/bootstrap-controls/radio-checked.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/select-dark.svg b/static/img/bootstrap-controls/select-dark.svg
new file mode 100644
index 000000000..e1f5fbece
--- /dev/null
+++ b/static/img/bootstrap-controls/select-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/select.svg b/static/img/bootstrap-controls/select.svg
new file mode 100644
index 000000000..4107eebb4
--- /dev/null
+++ b/static/img/bootstrap-controls/select.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/switch-checked.svg b/static/img/bootstrap-controls/switch-checked.svg
new file mode 100644
index 000000000..cccc6235d
--- /dev/null
+++ b/static/img/bootstrap-controls/switch-checked.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/switch-dark.svg b/static/img/bootstrap-controls/switch-dark.svg
new file mode 100644
index 000000000..55217871e
--- /dev/null
+++ b/static/img/bootstrap-controls/switch-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/switch-focus.svg b/static/img/bootstrap-controls/switch-focus.svg
new file mode 100644
index 000000000..7a7720556
--- /dev/null
+++ b/static/img/bootstrap-controls/switch-focus.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/switch.svg b/static/img/bootstrap-controls/switch.svg
new file mode 100644
index 000000000..29ed779d0
--- /dev/null
+++ b/static/img/bootstrap-controls/switch.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/bootstrap-controls/validation-invalid.svg b/static/img/bootstrap-controls/validation-invalid.svg
new file mode 100644
index 000000000..e55dd71a5
--- /dev/null
+++ b/static/img/bootstrap-controls/validation-invalid.svg
@@ -0,0 +1,7 @@
+
diff --git a/static/img/bootstrap-controls/validation-valid.svg b/static/img/bootstrap-controls/validation-valid.svg
new file mode 100644
index 000000000..fae2d7d60
--- /dev/null
+++ b/static/img/bootstrap-controls/validation-valid.svg
@@ -0,0 +1,3 @@
+
diff --git a/static/img/social/hugegraph-default.png b/static/img/social/hugegraph-default.png
new file mode 100644
index 000000000..4e3e3a0c1
Binary files /dev/null and b/static/img/social/hugegraph-default.png differ
diff --git a/tests/e2e/accessibility.spec.js b/tests/e2e/accessibility.spec.js
new file mode 100644
index 000000000..88bd2ed0d
--- /dev/null
+++ b/tests/e2e/accessibility.spec.js
@@ -0,0 +1,24 @@
+const { test, expect } = require("./artifact-test");
+const AxeBuilder = require("@axe-core/playwright").default;
+
+for (const route of ["/docs/", "/cn/docs/", "/community/", "/cn/community/"]) {
+ test(`axe WCAG 2.2 AA guard ${route}`, async ({ page }) => {
+ await page.emulateMedia({ reducedMotion: "reduce" });
+ await page.goto(route);
+ await page.addStyleTag({
+ content: "*,*::before,*::after{animation:none!important;transition:none!important}"
+ });
+ await page.evaluate(() => document.fonts.ready);
+ await page.waitForTimeout(250);
+ const results = await new AxeBuilder({ page })
+ .withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])
+ .analyze();
+ const knownOinkBaseline = new Set(["list", "target-size"]);
+ const blocking = results.violations.filter(
+ (item) =>
+ ["critical", "serious"].includes(item.impact) &&
+ !knownOinkBaseline.has(item.id)
+ );
+ expect(blocking).toEqual([]);
+ });
+}
diff --git a/tests/e2e/ai-enabled.yaml b/tests/e2e/ai-enabled.yaml
new file mode 100644
index 000000000..a0a12d188
--- /dev/null
+++ b/tests/e2e/ai-enabled.yaml
@@ -0,0 +1,8 @@
+params:
+ ai_search:
+ enabled: true
+ provider: kapa
+ website_id: 0b277570-4740-451e-96fa-1e4ac1ac5e88
+ source_groups:
+ en: e2e-source-en
+ cn: e2e-source-cn
diff --git a/tests/e2e/ai.spec.js b/tests/e2e/ai.spec.js
new file mode 100644
index 000000000..56209630f
--- /dev/null
+++ b/tests/e2e/ai.spec.js
@@ -0,0 +1,133 @@
+const { test, expect } = require("./artifact-test");
+
+const AI_ORIGIN = "http://127.0.0.1:4174";
+const mockBundle = `
+(function () {
+ var queued = window.Kapa && window.Kapa.q ? window.Kapa.q.slice() : [];
+ window.__kapaCalls = window.__kapaCalls || [];
+ window.Kapa = function (method, value) {
+ window.__kapaCalls.push([method, value]);
+ if (method === 'render' && value && value.onRender) value.onRender();
+ };
+ queued.forEach(function (args) { window.Kapa.apply(null, Array.from(args)); });
+})();`;
+
+test.beforeEach(async ({}, testInfo) => {
+ testInfo.skip(!process.env.AI_SITE_ROOT, "AI-enabled fixture was not built");
+});
+
+for (const [locale, route, source, language] of [
+ ["en", "/docs/", "e2e-source-en", "en"],
+ ["cn", "/cn/docs/", "e2e-source-cn", "zh"]
+]) {
+ test(`AI tail is click-gated and locale-bound for ${locale}`, async ({ page }) => {
+ const requests = [];
+ await page.route("https://widget.kapa.ai/kapa-widget.bundle.js*", async (route) => {
+ requests.push(route.request().url());
+ await route.fulfill({ status: 200, contentType: "text/javascript", body: mockBundle });
+ });
+ await page.goto(AI_ORIGIN + route);
+ expect(requests).toEqual([]);
+ await page.evaluate(() =>
+ document.documentElement.setAttribute("data-bs-theme", "dark")
+ );
+ const launcher = page.locator(".hg-ask-ai-launcher");
+ await expect(launcher).toBeVisible();
+
+ await page.locator("[data-td-shell-search-open]").first().click();
+ const input = page.locator(".td-shell-search__input");
+ await input.fill(" server auth ");
+ const tail = page.locator("[data-hg-ai-search-tail]");
+ await expect(tail).toBeVisible();
+ await expect(tail.locator("[data-hg-ask-ai]")).toHaveAttribute(
+ "data-hg-ai-query", "server auth"
+ );
+ await input.fill("");
+ await expect(tail).toHaveCount(0);
+ await input.fill(">theme");
+ await expect(tail).toHaveCount(0);
+ await input.fill("server auth");
+ await tail.locator("[data-hg-ask-ai]").click();
+ await expect.poll(() => requests.length).toBe(1);
+ await expect.poll(() => page.evaluate(() => window.__kapaCalls || [])).toContainEqual([
+ "setSourceGroupIDs", [source]
+ ]);
+ const script = page.locator("script[data-hg-kapa-widget]");
+ await expect(script).toHaveAttribute("data-language", language);
+ await expect(script).toHaveAttribute("data-source-group-ids-include", source);
+ await expect(script).toHaveAttribute("data-project-color", "#532fc9");
+ await expect(script).toHaveAttribute("data-project-color-dark", "#a693e3");
+ await expect(script).toHaveAttribute("data-anchor-color-dark", "#baace9");
+ await expect(script).toHaveAttribute(
+ "data-color-scheme-selector", "[data-bs-theme='dark']"
+ );
+ const calls = await page.evaluate(() => window.__kapaCalls);
+ expect(calls).toContainEqual([
+ "open", { mode: "ai", query: "server auth", submit: true }
+ ]);
+ });
+}
+
+test("AI 500 remains non-blocking and retry issues one fresh request", async ({ page }) => {
+ let attempts = 0;
+ await page.route("https://widget.kapa.ai/kapa-widget.bundle.js*", async (route) => {
+ attempts += 1;
+ if (attempts === 1) await route.fulfill({ status: 500, body: "failed" });
+ else await route.fulfill({ status: 200, contentType: "text/javascript", body: mockBundle });
+ });
+ await page.goto(AI_ORIGIN + "/docs/");
+ const launcher = page.locator(".hg-ask-ai-launcher");
+ await launcher.dblclick();
+ await expect.poll(() => attempts).toBe(1);
+ await expect(launcher).toHaveAttribute("data-hg-ai-state", "error");
+ await expect(launcher).toHaveAttribute("title", /unavailable/i);
+ await launcher.click();
+ await expect.poll(() => attempts).toBe(2);
+ await expect(launcher).toHaveAttribute("data-hg-ai-state", "ready");
+ await expect(launcher).not.toHaveAttribute("title", /unavailable/i);
+});
+
+test("AI pending timeout discards stale state and retry waits for a fresh bundle", async ({
+ page
+}) => {
+ let attempts = 0;
+ let releaseStale;
+ const staleGate = new Promise((resolve) => { releaseStale = resolve; });
+ await page.route("https://widget.kapa.ai/kapa-widget.bundle.js*", async (route) => {
+ attempts += 1;
+ if (attempts === 1) {
+ await staleGate;
+ }
+ await route.fulfill({
+ status: 200,
+ contentType: "text/javascript",
+ body: mockBundle
+ });
+ });
+ await page.goto(AI_ORIGIN + "/docs/");
+ const launcher = page.locator(".hg-ask-ai-launcher");
+ await launcher.click();
+ await expect.poll(() => attempts).toBe(1);
+ await expect(launcher).toHaveAttribute("data-hg-ai-state", "error", {
+ timeout: 7_000
+ });
+ await launcher.click();
+ await expect.poll(() => attempts).toBe(2);
+ await expect(launcher).toHaveAttribute("data-hg-ai-state", "ready");
+ expect(
+ await page.locator("script[data-hg-kapa-widget]").getAttribute("src")
+ ).toContain("?hg-retry=2");
+ expect(
+ await page.evaluate(() =>
+ (window.__kapaCalls || []).filter(([method]) => method === "open").length
+ )
+ ).toBe(1);
+
+ releaseStale();
+ await page.waitForTimeout(250);
+ expect(
+ await page.evaluate(() =>
+ (window.__kapaCalls || []).filter(([method]) => method === "open").length
+ )
+ ).toBe(1);
+});
diff --git a/tests/e2e/artifact-test.js b/tests/e2e/artifact-test.js
new file mode 100644
index 000000000..564a26f86
--- /dev/null
+++ b/tests/e2e/artifact-test.js
@@ -0,0 +1,31 @@
+const base = require("@playwright/test");
+
+const LOCAL_ARTIFACT_ORIGIN = "http://127.0.0.1:4173";
+const PUBLISHED_ORIGINS = new Set([
+ "https://hugegraph.apache.org",
+ "https://hugegraph-oink.staged.apache.org"
+]);
+
+const test = base.test.extend({
+ page: async ({ page }, use) => {
+ await page.route("**/*", async (route) => {
+ const requested = new URL(route.request().url());
+ if (!PUBLISHED_ORIGINS.has(requested.origin)) {
+ await route.continue();
+ return;
+ }
+ const local = new URL(requested.pathname + requested.search, LOCAL_ARTIFACT_ORIGIN);
+ const response = await route.fetch({ url: local.href });
+ await route.fulfill({
+ response,
+ headers: {
+ ...response.headers(),
+ "access-control-allow-origin": "*"
+ }
+ });
+ });
+ await use(page);
+ }
+});
+
+module.exports = { test, expect: base.expect };
diff --git a/tests/e2e/package-lock.json b/tests/e2e/package-lock.json
new file mode 100644
index 000000000..569ab0709
--- /dev/null
+++ b/tests/e2e/package-lock.json
@@ -0,0 +1,103 @@
+{
+ "name": "hugegraph-doc-e2e",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "hugegraph-doc-e2e",
+ "devDependencies": {
+ "@axe-core/playwright": "4.13.0",
+ "@playwright/test": "1.62.1"
+ },
+ "engines": {
+ "node": ">=24"
+ }
+ },
+ "node_modules/@axe-core/playwright": {
+ "version": "4.13.0",
+ "resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.13.0.tgz",
+ "integrity": "sha512-6YLx+kxXu5GJceG4ozFg+33a2EMTdjYwWGloJ3sb9Kta5pp+ZNS53uxGVog5JetIY8s++P5UrtX+cri+u0VAVg==",
+ "dev": true,
+ "license": "MPL-2.0",
+ "dependencies": {
+ "axe-core": "~4.13.0"
+ },
+ "peerDependencies": {
+ "playwright-core": ">= 1.0.0"
+ }
+ },
+ "node_modules/@playwright/test": {
+ "version": "1.62.1",
+ "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.62.1.tgz",
+ "integrity": "sha512-DTcUc8qii+cpHvtOwggMtBRMjKZHXYWdw8syRYu2vtzuq4Wxphqq4NfCs5Zt44L6mA8rfDfj+PHnxFc/FeK6mQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "playwright": "1.62.1"
+ },
+ "bin": {
+ "playwright": "cli.js"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ },
+ "node_modules/axe-core": {
+ "version": "4.13.0",
+ "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.13.0.tgz",
+ "integrity": "sha512-UzGt8zg7Ny8djbYMhxl2zuEevVa7r2gJjYY5Lwr1xM7+XU2nd6CkIWFTVcCIbAP63vSz71NaVyyuSk9lHKcy0A==",
+ "dev": true,
+ "license": "MPL-2.0",
+ "engines": {
+ "node": ">=4"
+ }
+ },
+ "node_modules/fsevents": {
+ "version": "2.3.2",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+ "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+ }
+ },
+ "node_modules/playwright": {
+ "version": "1.62.1",
+ "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.62.1.tgz",
+ "integrity": "sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "playwright-core": "1.62.1"
+ },
+ "bin": {
+ "playwright": "cli.js"
+ },
+ "engines": {
+ "node": ">=20"
+ },
+ "optionalDependencies": {
+ "fsevents": "2.3.2"
+ }
+ },
+ "node_modules/playwright-core": {
+ "version": "1.62.1",
+ "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.1.tgz",
+ "integrity": "sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "playwright-core": "cli.js"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ }
+ }
+}
diff --git a/tests/e2e/package.json b/tests/e2e/package.json
new file mode 100644
index 000000000..36ef845b8
--- /dev/null
+++ b/tests/e2e/package.json
@@ -0,0 +1,16 @@
+{
+ "name": "hugegraph-doc-e2e",
+ "private": true,
+ "engines": {
+ "node": ">=24"
+ },
+ "scripts": {
+ "test": "playwright test",
+ "test:ci": "node --test ../ui-ai/*.test.cjs && node --test workflow-contract.test.cjs && playwright test versioning.spec.js search-ranking.spec.js platform.spec.js ai.spec.js accessibility.spec.js --reporter=line,html",
+ "test:visual": "playwright test visual.spec.js --reporter=line"
+ },
+ "devDependencies": {
+ "@axe-core/playwright": "4.13.0",
+ "@playwright/test": "1.62.1"
+ }
+}
diff --git a/tests/e2e/platform.spec.js b/tests/e2e/platform.spec.js
new file mode 100644
index 000000000..450746570
--- /dev/null
+++ b/tests/e2e/platform.spec.js
@@ -0,0 +1,130 @@
+const { test, expect } = require("./artifact-test");
+
+for (const locale of ["en", "cn"]) {
+ const prefix = locale === "cn" ? "/cn" : "";
+ test(`latest ${locale} sidebar persists and isolates collapse`, async ({ page }) => {
+ await page.goto(`${prefix}/docs/introduction/`);
+ const key = `oink.sidebar.v1.latest.${locale}`;
+ await expect.poll(() => page.evaluate((name) => localStorage.getItem(name), key))
+ .not.toBeNull();
+ const toggle = page
+ .locator('#td-shell-sidebar [data-td-shell-tree-toggle][aria-controls$="_navdevelop-children"]')
+ .first();
+ await expect(toggle).toHaveAttribute("aria-expanded", "false");
+ await toggle.click();
+ const target = await toggle.getAttribute("aria-controls");
+ await expect.poll(() => page.evaluate((name) => localStorage.getItem(name), key))
+ .toContain(target);
+ await page.reload();
+ await expect(page.locator(`[aria-controls="${target}"]`)).toHaveAttribute(
+ "aria-expanded", "true"
+ );
+
+ await page.locator(".td-shell-sidebar__collapse").click();
+ await expect(page.locator("#td-shell-sidebar")).toHaveAttribute("aria-hidden", "true");
+ await expect(page.locator("#td-shell-sidebar")).toHaveJSProperty("inert", true);
+ const restore = page.locator(".hg-sidebar-restore");
+ await expect(restore).toBeVisible();
+ await restore.click();
+ await expect(page.locator("#td-shell-sidebar")).not.toHaveAttribute(
+ "aria-hidden", "true"
+ );
+ });
+
+ test(`latest ${locale} mobile drawer restores focus and unlocks scroll`, async ({ page }) => {
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.goto(`${prefix}/docs/`);
+ const opener = page.locator("[data-td-shell-drawer-open]");
+ await opener.click();
+ await expect(page.locator("html")).toHaveAttribute("data-td-shell-drawer", "open");
+ await page.locator("button[data-td-shell-drawer-close]").click();
+ await expect(page.locator("#td-shell-sidebar")).toHaveJSProperty("inert", true);
+ await expect(opener).toBeFocused();
+ await expect(page.locator("html")).not.toHaveAttribute("data-td-shell-lock", "");
+ });
+}
+
+test("disabled AI emits no UI or Kapa request", async ({ page }) => {
+ const kapaRequests = [];
+ page.on("request", (request) => {
+ if (request.url().includes("kapa.ai")) kapaRequests.push(request.url());
+ });
+ await page.goto("/docs/");
+ await page.locator("[data-td-shell-search-open]").first().click();
+ await page.locator(".td-shell-search__input").fill("server");
+ await expect(page.locator('[role="option"]').first()).toBeVisible();
+ expect(kapaRequests).toEqual([]);
+ await expect(page.locator("[data-hg-ask-ai]")).toHaveCount(0);
+});
+
+test("search index failure keeps one stable, focusable retry control", async ({
+ page
+}) => {
+ let attempts = 0;
+ await page.route("**/offline-search-index.en.*.json", async (route) => {
+ attempts += 1;
+ if (attempts === 1) await route.abort("failed");
+ else await route.fallback();
+ });
+ await page.goto("/docs/");
+ await page.locator("[data-td-shell-search-open]").first().click();
+ await page.locator(".td-shell-search__input").fill("server");
+ const retry = page.locator("[data-hg-search-retry]");
+ await expect(retry).toHaveCount(1);
+ const mutations = await retry.evaluate((node) => {
+ window.__hgRetryNode = node;
+ window.__hgRetryMutations = 0;
+ new MutationObserver(() => { window.__hgRetryMutations += 1; })
+ .observe(node.parentNode, { childList: true, subtree: true });
+ return window.__hgRetryMutations;
+ });
+ expect(mutations).toBe(0);
+ await page.waitForTimeout(250);
+ expect(await page.evaluate(() => window.__hgRetryMutations)).toBe(0);
+ expect(
+ await retry.evaluate((node) => node === window.__hgRetryNode)
+ ).toBe(true);
+
+ const button = retry.locator("button");
+ await button.focus();
+ await expect(button).toBeFocused();
+ await button.click();
+ await expect.poll(() => attempts).toBe(2);
+ await expect(page.locator('[role="option"]').first()).toBeVisible();
+ await expect(page.locator(".td-shell-search__input")).toBeFocused();
+ await expect(retry).toHaveCount(0);
+});
+
+test("Community grid and HTML/Print/Markdown profiles stay in parity", async ({
+ page,
+ request
+}) => {
+ await page.goto("/community/");
+ test.skip(
+ (await page.locator(".hg-community-members__grid").count()) === 0,
+ "PR-B Community section is not integrated in this artifact"
+ );
+ for (const [width, columns] of [[1440, 5], [900, 3], [390, 2], [320, 2]]) {
+ await page.setViewportSize({ width, height: 900 });
+ await page.goto("/community/");
+ const grid = page.locator(".hg-community-members__grid").first();
+ await expect(grid).toBeVisible();
+ expect(
+ await grid.evaluate((node) => getComputedStyle(node).gridTemplateColumns.split(" ").length)
+ ).toBe(columns);
+ }
+ await page.evaluate(() => localStorage.setItem("td-color-theme", "dark"));
+ await page.reload();
+ await expect(page.locator(".hg-community-member__link").first()).toBeVisible();
+ await expect(page.locator(".hg-community-member__initials").first()).toBeAttached();
+
+ const htmlProfiles = await page
+ .locator("#project-members .hg-community-member__link")
+ .evaluateAll((links) => links.map((link) => link.href).sort());
+ const print = await (await request.get("/_print/community/")).text();
+ const markdown = await (await request.get("/community/index.md")).text();
+ for (const profile of htmlProfiles) {
+ expect(print).toContain(profile);
+ expect(markdown).toContain(profile);
+ }
+});
diff --git a/tests/e2e/playwright.config.js b/tests/e2e/playwright.config.js
new file mode 100644
index 000000000..7eef0aceb
--- /dev/null
+++ b/tests/e2e/playwright.config.js
@@ -0,0 +1,44 @@
+const { defineConfig } = require("@playwright/test");
+
+const siteRoot = process.env.SITE_ROOT;
+const aiSiteRoot = process.env.AI_SITE_ROOT;
+if (!siteRoot) {
+ throw new Error("SITE_ROOT must point to an aggregate site artifact");
+}
+
+module.exports = defineConfig({
+ testDir: ".",
+ testMatch: "*.spec.js",
+ outputDir: "test-results",
+ timeout: 30_000,
+ expect: { timeout: 5_000 },
+ retries: process.env.CI ? 1 : 0,
+ workers: process.env.CI ? 2 : undefined,
+ reporter: [["line"], ["html", { outputFolder: "playwright-report", open: "never" }]],
+ use: {
+ baseURL: "http://127.0.0.1:4173",
+ browserName: "chromium",
+ trace: "retain-on-failure",
+ screenshot: "only-on-failure"
+ },
+ webServer: [
+ {
+ command: `python3 -m http.server 4173 --bind 127.0.0.1 --directory ${JSON.stringify(siteRoot)}`,
+ url: "http://127.0.0.1:4173/",
+ reuseExistingServer: false,
+ timeout: 30_000,
+ stdout: "ignore",
+ stderr: "ignore"
+ },
+ ...(aiSiteRoot
+ ? [{
+ command: `python3 -m http.server 4174 --bind 127.0.0.1 --directory ${JSON.stringify(aiSiteRoot)}`,
+ url: "http://127.0.0.1:4174/",
+ reuseExistingServer: false,
+ timeout: 30_000,
+ stdout: "ignore",
+ stderr: "ignore"
+ }]
+ : [])
+ ]
+});
diff --git a/tests/e2e/search-ranking.spec.js b/tests/e2e/search-ranking.spec.js
new file mode 100644
index 000000000..06f79a4a6
--- /dev/null
+++ b/tests/e2e/search-ranking.spec.js
@@ -0,0 +1,103 @@
+const { test, expect } = require("./artifact-test");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const FALLBACK_CASES = {
+ en: [
+ ["introduction", "/docs/introduction/"],
+ ["server", "/docs/quickstart/hugegraph/hugegraph-server/"],
+ ["hstore", "/docs/quickstart/hugegraph/hugegraph-hstore/"],
+ ["placement driver", "/docs/quickstart/hugegraph/hugegraph-pd/"],
+ ["computer", "/docs/quickstart/computing/hugegraph-computer/"],
+ ["loader", "/docs/quickstart/toolchain/hugegraph-loader/"],
+ ["hubble", "/docs/quickstart/toolchain/hugegraph-hubble/"],
+ ["clients", "/docs/clients/"],
+ ["rest api", "/docs/clients/restful-api/"],
+ ["configuration", "/docs/config/"],
+ ["authentication", "/docs/config/config-authentication/"],
+ ["download", "/docs/download/download/"]
+ ],
+ cn: [
+ ["介绍", "/cn/docs/introduction/"],
+ ["服务端", "/cn/docs/quickstart/hugegraph/hugegraph-server/"],
+ ["HStore", "/cn/docs/quickstart/hugegraph/hugegraph-hstore/"],
+ ["PD", "/cn/docs/quickstart/hugegraph/hugegraph-pd/"],
+ ["图计算", "/cn/docs/quickstart/computing/hugegraph-computer/"],
+ ["数据导入", "/cn/docs/quickstart/toolchain/hugegraph-loader/"],
+ ["图形化界面", "/cn/docs/quickstart/toolchain/hugegraph-hubble/"],
+ ["客户端", "/cn/docs/clients/"],
+ ["REST API", "/cn/docs/clients/restful-api/"],
+ ["配置", "/cn/docs/config/"],
+ ["认证", "/cn/docs/config/config-authentication/"],
+ ["下载", "/cn/docs/download/download/"]
+ ]
+};
+
+const metadataFixture = path.resolve(__dirname, "../../scripts/fixtures/community_search_queries.json");
+const metadataIntegrated = fs.existsSync(metadataFixture);
+const siteRoot = process.env.SITE_ROOT;
+const rawCases = metadataIntegrated
+ ? Object.groupBy(
+ JSON.parse(fs.readFileSync(metadataFixture, "utf8")).map((entry) => [
+ entry.query,
+ entry.expected_ref
+ ]),
+ ([query, expectedRef]) => (expectedRef.startsWith("/cn/") ? "cn" : "en")
+ )
+ : FALLBACK_CASES;
+const cases = Object.fromEntries(
+ Object.entries(rawCases).map(([locale, localeCases]) => {
+ const indexName = fs
+ .readdirSync(siteRoot)
+ .find((name) => name.startsWith(`offline-search-index.${locale}.`) && name.endsWith(".json"));
+ if (!indexName) throw new Error(`missing ${locale} offline search index`);
+ const records = JSON.parse(fs.readFileSync(path.join(siteRoot, indexName), "utf8"));
+ const titles = new Map(records.map((record) => [record.ref, record.title]));
+ return [
+ locale,
+ localeCases.map(([query, expectedRef]) => {
+ const expectedTitle = titles.get(expectedRef);
+ if (!expectedTitle) throw new Error(`missing search record ${expectedRef}`);
+ return [query, expectedRef, expectedTitle];
+ })
+ ];
+ })
+);
+
+for (const [locale, localeCases] of Object.entries(cases)) {
+ test(`summary Lunr ranks fixed ${locale} entry queries`, async ({ page }) => {
+ test.skip(!metadataIntegrated, "PR-B search metadata fixture is not integrated");
+ for (const [query, expectedRef, expectedTitle] of localeCases) {
+ await page.goto(locale === "cn" ? "/cn/docs/" : "/docs/");
+ await page.locator("[data-td-shell-search-open]").first().click();
+ const input = page.locator(".td-shell-search__input");
+ await input.fill(query);
+ const pageResults = page
+ .locator("#td-shell-search-results .td-shell-search__group")
+ .first()
+ .locator('[role="option"]');
+ await expect(pageResults.first(), `no Lunr results for ${query}`).toBeVisible();
+ await expect
+ .poll(() =>
+ pageResults.evaluateAll((rows) =>
+ rows
+ .slice(0, 3)
+ .map((row) => row.querySelector(".td-shell-search__item-title")?.textContent.trim())
+ )
+ )
+ .toContain(expectedTitle);
+ const titles = await pageResults.evaluateAll((rows) =>
+ rows.slice(0, 3).map((row) =>
+ row.querySelector(".td-shell-search__item-title")?.textContent.trim()
+ )
+ );
+ expect(
+ titles.includes(expectedTitle),
+ `${query} must rank ${expectedRef} in the top three`
+ ).toBe(true);
+ const target = pageResults.filter({ hasText: expectedTitle }).first();
+ await target.click();
+ await expect(page).toHaveURL((url) => url.pathname === expectedRef);
+ }
+ });
+}
diff --git a/tests/e2e/versioning.spec.js b/tests/e2e/versioning.spec.js
new file mode 100644
index 000000000..413fc2318
--- /dev/null
+++ b/tests/e2e/versioning.spec.js
@@ -0,0 +1,303 @@
+const { test, expect } = require("./artifact-test");
+
+const VERSION_IDS = ["latest", "1.7", "1.5", "1.3", "1.0"];
+const EXPECTED_IDS = (process.env.EXPECTED_VERSIONS || VERSION_IDS.join(",")).split(",");
+
+async function actionManifest(page) {
+ return page.locator("#td-action-manifest").evaluate((node) => JSON.parse(node.textContent));
+}
+
+async function versionOption(page, id) {
+ const manifest = await actionManifest(page);
+ return manifest.actions
+ .find((item) => item.id === "switch_version")
+ .options.find((item) => item.id === id);
+}
+
+test("aggregate records the immutable five-version manifest", async ({ request }) => {
+ const response = await request.get("/build-metadata/versions.json");
+ expect(response.ok()).toBeTruthy();
+ const manifest = await response.json();
+ expect(manifest.schemaVersion).toBe(1);
+ expect(manifest.versions.map((entry) => entry.id)).toEqual(EXPECTED_IDS);
+ for (const entry of manifest.versions) {
+ expect(entry.sha).toMatch(/^[0-9a-f]{40}$/);
+ }
+});
+
+for (const locale of ["en", "cn"]) {
+ test(`latest ${locale} exposes the fixed version order`, async ({ page }) => {
+ await page.goto(locale === "cn" ? "/cn/docs/" : "/docs/");
+ const manifest = await actionManifest(page);
+ const action = manifest.actions.find((item) => item.id === "switch_version");
+ expect(action.options.map((item) => item.id)).toEqual(VERSION_IDS);
+ });
+}
+
+for (const version of VERSION_IDS.slice(1)) {
+ for (const locale of ["en", "cn"]) {
+ test(`${version} ${locale} is archived and directly reachable`, async ({ page }) => {
+ test.skip(!EXPECTED_IDS.includes(version), "latest-only staging artifact");
+ const prefix = `/versions/${version}${locale === "cn" ? "/cn" : ""}`;
+ await page.goto(`${prefix}/docs/`);
+ await expect(page.locator('meta[name="robots"]')).toHaveAttribute(
+ "content",
+ /noindex\s*,?\s*follow/i
+ );
+ await expect(page.locator(".td-page-notice--primary")).toBeVisible();
+ const manifest = await actionManifest(page);
+ const action = manifest.actions.find((item) => item.id === "switch_version");
+ expect(action.options.map((item) => item.id)).toEqual(VERSION_IDS);
+ });
+ }
+}
+
+test("1.0 flat Server URL remains a static alias", async ({ request }) => {
+ test.skip(!EXPECTED_IDS.includes("1.0"), "latest-only staging artifact");
+ const response = await request.get(
+ "/versions/1.0/docs/quickstart/hugegraph-server/"
+ );
+ expect(response.ok()).toBeTruthy();
+ const body = await response.text();
+ expect(body).toMatch(
+ /http-equiv="refresh"[^>]+quickstart\/hugegraph\/hugegraph-server/
+ );
+ expect(body).toMatch(
+ /rel="canonical"[^>]+versions\/1\.0\/docs\/quickstart\/hugegraph\/hugegraph-server\//
+ );
+});
+
+test("desktop and mobile selectors preserve query and hash for an equivalent page", async ({
+ page
+}) => {
+ test.skip(!EXPECTED_IDS.includes("1.7"), "latest-only staging artifact");
+ await page.goto("/docs/quickstart/hugegraph/?query=server#server");
+ const option = await versionOption(page, "1.7");
+ expect(option.equivalent).toBe(true);
+ expect(option.fallback).toBe(false);
+
+ const desktop = page.locator(
+ ".td-nav-version-menu a[data-hg-version-id='1.7']"
+ );
+ const href = await desktop.getAttribute("href");
+ expect(new URL(href).search).toBe("?query=server");
+ expect(new URL(href).hash).toBe("#server");
+ expect(new URL(href).pathname).toBe(new URL(option.url).pathname);
+ await page.locator(".td-nav-version-menu [data-td-nav-hover-trigger]").hover();
+ await expect(desktop).toBeVisible();
+ await desktop.click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === new URL(option.url).pathname &&
+ url.search === "?query=server" &&
+ url.hash === "#server"
+ );
+
+ await page.goto("/docs/quickstart/hugegraph/?query=server#server");
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.locator("[data-td-shell-drawer-open]").click();
+ const drawer = page.locator(
+ "#td-shell-sidebar a[data-hg-version-id='1.7']"
+ );
+ await expect(drawer).toHaveAttribute("href", href);
+ await drawer.click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === new URL(option.url).pathname &&
+ url.search === "?query=server" &&
+ url.hash === "#server"
+ );
+});
+
+test("Palette version choice uses the same equivalent target", async ({ page }) => {
+ test.skip(!EXPECTED_IDS.includes("1.7"), "latest-only staging artifact");
+ await page.goto("/docs/quickstart/hugegraph/?query=server#server");
+ const option = await versionOption(page, "1.7");
+ await page.locator("[data-td-shell-search-open]").first().click();
+ const input = page.locator(".td-shell-search__input");
+ await input.fill("Releases");
+ await page
+ .locator('[role="option"]')
+ .filter({ hasText: "Releases" })
+ .first()
+ .click();
+ await page
+ .locator('[role="option"]')
+ .filter({ hasText: /^1\.7$/ })
+ .click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === new URL(option.url).pathname &&
+ url.search === "?query=server" &&
+ url.hash === "#server"
+ );
+});
+
+test("historical selectors preserve the readme route across desktop, mobile, and Palette", async ({
+ page
+}) => {
+ test.skip(
+ !["1.7", "1.5", "1.3"].every((version) => EXPECTED_IDS.includes(version)),
+ "latest-only staging artifact"
+ );
+
+ await page.goto(
+ "/versions/1.7/docs/introduction/readme/?query=history#overview"
+ );
+ let option = await versionOption(page, "1.5");
+ expect(option.equivalent).toBe(true);
+ expect(option.fallback).toBe(false);
+ expect(new URL(option.url).pathname).toBe(
+ "/versions/1.5/docs/introduction/readme/"
+ );
+ const desktop = page.locator(
+ ".td-nav-version-menu a[data-hg-version-id='1.5']"
+ );
+ await page.locator(".td-nav-version-menu [data-td-nav-hover-trigger]").hover();
+ await desktop.click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === "/versions/1.5/docs/introduction/readme/" &&
+ url.search === "?query=history" &&
+ url.hash === "#overview"
+ );
+
+ await page.goto(
+ "/versions/1.7/cn/docs/introduction/readme/?query=history#overview"
+ );
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.locator("[data-td-shell-drawer-open]").click();
+ const mobile = page.locator(
+ "#td-shell-sidebar a[data-hg-version-id='1.3']"
+ );
+ await mobile.click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === "/versions/1.3/cn/docs/introduction/readme/" &&
+ url.search === "?query=history" &&
+ url.hash === "#overview"
+ );
+
+ await page.setViewportSize({ width: 1440, height: 900 });
+ await page.goto(
+ "/versions/1.3/docs/introduction/readme/?query=history#overview"
+ );
+ option = await versionOption(page, "1.5");
+ expect(new URL(option.url).pathname).toBe(
+ "/versions/1.5/docs/introduction/readme/"
+ );
+ await page.locator("[data-td-shell-search-open]").first().click();
+ const input = page.locator(".td-shell-search__input");
+ await input.fill("Releases");
+ await page
+ .locator('[role="option"]')
+ .filter({ hasText: "Releases" })
+ .first()
+ .click();
+ await page
+ .locator('[role="option"]')
+ .filter({ hasText: /^1\.5$/ })
+ .click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === "/versions/1.5/docs/introduction/readme/" &&
+ url.search === "?query=history" &&
+ url.hash === "#overview"
+ );
+});
+
+test("introduction aliases resolve bidirectionally without merging canonical pages", async ({
+ page
+}) => {
+ test.skip(
+ !["1.7", "1.5", "1.3", "1.0"].every((version) =>
+ EXPECTED_IDS.includes(version)
+ ),
+ "latest-only staging artifact"
+ );
+
+ await page.goto("/docs/introduction/?query=history#overview");
+ let option = await versionOption(page, "1.5");
+ expect(option.equivalent).toBe(true);
+ expect(option.fallback).toBe(false);
+ expect(new URL(option.url).pathname).toBe(
+ "/versions/1.5/docs/introduction/readme/"
+ );
+ await page.locator(".td-nav-version-menu [data-td-nav-hover-trigger]").hover();
+ await page
+ .locator(".td-nav-version-menu a[data-hg-version-id='1.5']")
+ .click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === "/versions/1.5/docs/introduction/readme/" &&
+ url.search === "?query=history" &&
+ url.hash === "#overview"
+ );
+
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.goto("/cn/docs/introduction/?query=history#overview");
+ await page.locator("[data-td-shell-drawer-open]").click();
+ await page
+ .locator("#td-shell-sidebar a[data-hg-version-id='1.3']")
+ .click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === "/versions/1.3/cn/docs/introduction/readme/" &&
+ url.search === "?query=history" &&
+ url.hash === "#overview"
+ );
+
+ await page.setViewportSize({ width: 1440, height: 900 });
+ await page.goto(
+ "/versions/1.7/docs/introduction/readme/?query=history#overview"
+ );
+ option = await versionOption(page, "latest");
+ expect(new URL(option.url).pathname).toBe("/docs/introduction/");
+ await page.locator("[data-td-shell-search-open]").first().click();
+ await page.locator(".td-shell-search__input").fill("Releases");
+ await page
+ .locator('[role="option"]')
+ .filter({ hasText: "Releases" })
+ .first()
+ .click();
+ await page
+ .locator('[role="option"]')
+ .filter({ hasText: /^latest$/ })
+ .click();
+ await expect(page).toHaveURL((url) =>
+ url.pathname === "/docs/introduction/" &&
+ url.search === "?query=history" &&
+ url.hash === "#overview"
+ );
+
+ for (const locale of ["en", "cn"]) {
+ const prefix = locale === "cn" ? "/cn" : "";
+ await page.goto(`/versions/1.7${prefix}/docs/introduction/`);
+ option = await versionOption(page, "latest");
+ expect(new URL(option.url).pathname).toBe(
+ `${prefix}/docs/introduction/`
+ );
+ expect(option.equivalent).toBe(true);
+ expect(option.fallback).toBe(false);
+ }
+});
+
+for (const locale of ["en", "cn"]) {
+ test(`${locale} missing page falls back to its docs root once`, async ({ page }) => {
+ test.skip(!EXPECTED_IDS.includes("1.0"), "latest-only staging artifact");
+ const prefix = locale === "cn" ? "/cn" : "";
+ await page.goto(`${prefix}/docs/guides/security/?query=discard#discard`);
+ const option = await versionOption(page, "1.0");
+ expect(option.fallback).toBe(true);
+ expect(option.equivalent).toBe(false);
+ expect(new URL(option.url).pathname).toBe(`/versions/1.0${prefix}/docs/`);
+ expect(new URL(option.url).search).toBe("");
+ expect(new URL(option.url).hash).toBe("#hg-version-fallback");
+
+ await page.evaluate((target) => {
+ window.OinkActions.run("switch_version", { value: target });
+ }, option);
+ await page.waitForURL((url) => url.pathname === `/versions/1.0${prefix}/docs/`);
+ await expect(
+ page.locator("[data-hg-version-fallback-notice]")
+ ).toHaveCount(1);
+ expect(new URL(page.url()).search).toBe("");
+ expect(new URL(page.url()).hash).toBe("");
+ await page.reload();
+ await expect(
+ page.locator("[data-hg-version-fallback-notice]")
+ ).toHaveCount(0);
+ });
+}
diff --git a/tests/e2e/visual.spec.js b/tests/e2e/visual.spec.js
new file mode 100644
index 000000000..a2d4534ac
--- /dev/null
+++ b/tests/e2e/visual.spec.js
@@ -0,0 +1,43 @@
+const { test, expect } = require("./artifact-test");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const states = [
+ ["en-docs-desktop-light", "/docs/", { width: 1440, height: 900 }, "light", "default"],
+ ["cn-docs-desktop-dark", "/cn/docs/", { width: 1440, height: 900 }, "dark", "default"],
+ ["en-search-desktop-light", "/docs/", { width: 1440, height: 900 }, "light", "search"],
+ ["cn-search-mobile-dark", "/cn/docs/", { width: 390, height: 844 }, "dark", "search"],
+ ["en-sidebar-desktop-light", "/docs/introduction/", { width: 1440, height: 900 }, "light", "collapse"],
+ ["cn-sidebar-mobile-dark", "/cn/docs/", { width: 390, height: 844 }, "dark", "drawer"],
+ ["en-community-desktop-light", "/community/", { width: 1440, height: 900 }, "light", "default"],
+ ["cn-community-mobile-dark", "/cn/community/", { width: 320, height: 720 }, "dark", "default"]
+];
+
+for (const [name, url, viewport, theme, state] of states) {
+ test(`capture advisory ${name}`, async ({ page }) => {
+ await page.setViewportSize(viewport);
+ await page.addInitScript(
+ (value) => localStorage.setItem("td-color-theme", value),
+ theme
+ );
+ await page.goto(url);
+ await expect(page.locator("body")).toBeVisible();
+ if (state === "search") {
+ await page.locator("[data-td-shell-search-open]").first().click();
+ await page.locator(".td-shell-search__input").fill(url.startsWith("/cn/") ? "服务端" : "server");
+ await expect(page.locator('[role="option"]').first()).toBeVisible();
+ } else if (state === "collapse") {
+ await page.locator(".td-shell-sidebar__collapse").click();
+ await expect(page.locator("#td-shell-sidebar")).toHaveAttribute("aria-hidden", "true");
+ } else if (state === "drawer") {
+ await page.locator("[data-td-shell-drawer-open]").click();
+ await expect(page.locator("html")).toHaveAttribute("data-td-shell-drawer", "open");
+ }
+ const directory = path.join(__dirname, "visual-results");
+ fs.mkdirSync(directory, { recursive: true });
+ await page.screenshot({
+ path: path.join(directory, `${name}.png`),
+ fullPage: true
+ });
+ });
+}
diff --git a/tests/e2e/workflow-contract.test.cjs b/tests/e2e/workflow-contract.test.cjs
new file mode 100644
index 000000000..c45cc4d31
--- /dev/null
+++ b/tests/e2e/workflow-contract.test.cjs
@@ -0,0 +1,88 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+const workflow = fs.readFileSync(
+ path.resolve(__dirname, "../../.github/workflows/hugo.yml"),
+ "utf8"
+);
+const versionManifest = JSON.parse(
+ fs.readFileSync(path.resolve(__dirname, "../../versions.json"), "utf8")
+);
+
+test("each build fetches and verifies its immutable matrix SHA", () => {
+ assert.match(workflow, /RESOLVED_SHA: \$\{\{ matrix\.version\.sha \}\}/);
+ assert.match(workflow, /git fetch --no-tags origin "\$RESOLVED_SHA"/);
+ assert.match(workflow, /git cat-file -e "\$RESOLVED_SHA\^\{commit\}"/);
+});
+
+test("only publish receives write permission and deploy stays read-only", () => {
+ const writeMatches = workflow.match(/contents: write/g) || [];
+ assert.equal(writeMatches.length, 1);
+ assert.match(
+ workflow,
+ /deploy:[\s\S]*?permissions: \{ contents: read \}[\s\S]*?publish:/
+ );
+ assert.match(workflow, /publish:[\s\S]*?permissions: \{ contents: write \}/);
+});
+
+test("event plan derives runtime selection from versions.json", () => {
+ assert.match(
+ workflow,
+ /all_selection="\$\(jq -er '\[\.versions\[\]\.id\] \| join\(","\)' versions\.json\)"/
+ );
+ assert.match(
+ workflow,
+ /latest_selection="\$\(jq -er '\[\.versions\[\] \| select\(\.archived == false\) \| \.id\] \| join\(","\)' versions\.json\)"/
+ );
+ assert.doesNotMatch(workflow, /selection="latest,1\.7,1\.5,1\.3,1\.0"/);
+ assert.match(workflow, /selection="\$all_selection"/);
+ assert.match(workflow, /selection="\$latest_selection"/);
+ assert.match(workflow, /test "\$candidate" = "\$latest_ref"/);
+ assert.deepEqual(
+ versionManifest.versions.map(({ id }) => id),
+ ["latest", "1.7", "1.5", "1.3", "1.0"],
+ "the reviewed manifest still declares the accepted five-version product order"
+ );
+ assert.match(workflow, /test "\$CONFIRMATION" = "publish asf-staging-oink"/);
+ assert.match(workflow, /test "\$CONFIRMATION" = "publish asf-site"/);
+ assert.match(workflow, /production:asf-site\|staging:asf-staging-oink/);
+ assert.doesNotMatch(workflow, /permissions:\s*write-all/);
+});
+
+test("concurrency serializes every writer to the same ASF target", () => {
+ assert.match(
+ workflow,
+ /group: \$\{\{ github\.workflow \}\}-\$\{\{[\s\S]*inputs\.operation == 'staging-next'[\s\S]*'asf-staging-oink'[\s\S]*'asf-site'[\s\S]*\}\}/
+ );
+ assert.doesNotMatch(
+ workflow,
+ /group:[^\n]*(?:inputs\.operation \|\| 'automatic'|github\.ref)/
+ );
+});
+
+test("aggregate binds the option-looking artifact suffix", () => {
+ assert.match(
+ workflow,
+ /--artifact-suffix="-\$\{GITHUB_RUN_ID\}-\$\{GITHUB_RUN_ATTEMPT\}"/
+ );
+ assert.doesNotMatch(
+ workflow,
+ /--artifact-suffix\s+"-\$\{GITHUB_RUN_ID\}-\$\{GITHUB_RUN_ATTEMPT\}"/
+ );
+});
+
+test("prepare pins Hugo and WebP tools before source validators", () => {
+ const setupHugo = workflow.indexOf("name: Setup Hugo Extended");
+ const setupWebp = workflow.indexOf("name: Install WebP validators");
+ const validators = workflow.indexOf("name: Validate source and version tooling");
+ assert.ok(setupHugo >= 0 && setupHugo < validators);
+ assert.ok(setupWebp >= 0 && setupWebp < validators);
+ assert.match(workflow, /apt-get install --yes --no-install-recommends webp/);
+ assert.match(workflow, /command -v cwebp[\s\S]*command -v dwebp/);
+ assert.match(
+ workflow,
+ /aggregate[\s\S]*--historical-origin "\$HISTORICAL_ORIGIN"/,
+ );
+});
diff --git a/tests/ui-ai/ai-enabled.yaml b/tests/ui-ai/ai-enabled.yaml
new file mode 100644
index 000000000..4ed54da7e
--- /dev/null
+++ b/tests/ui-ai/ai-enabled.yaml
@@ -0,0 +1,8 @@
+params:
+ ai_search:
+ enabled: true
+ provider: kapa
+ website_id: test-website-id
+ source_groups:
+ en: test-latest-en
+ cn: test-latest-cn
diff --git a/tests/ui-ai/ai-invalid.yaml b/tests/ui-ai/ai-invalid.yaml
new file mode 100644
index 000000000..48dc01a27
--- /dev/null
+++ b/tests/ui-ai/ai-invalid.yaml
@@ -0,0 +1,8 @@
+params:
+ ai_search:
+ enabled: true
+ provider: kapa
+ website_id: test-website-id
+ source_groups:
+ en: test-latest-en
+ cn: ''
diff --git a/tests/ui-ai/backlinks-render.test.cjs b/tests/ui-ai/backlinks-render.test.cjs
new file mode 100644
index 000000000..4cf6add55
--- /dev/null
+++ b/tests/ui-ai/backlinks-render.test.cjs
@@ -0,0 +1,54 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const test = require('node:test');
+
+const root = path.resolve(__dirname, '../..');
+
+test('six backlink fixture renders five rows and one expandable row', () => {
+ const destination = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'hg-backlinks-fixture-'),
+ );
+ try {
+ const result = spawnSync(
+ 'hugo',
+ [
+ '--config',
+ 'hugo.yaml,tests/ui-ai/fixtures/backlinks.yaml',
+ '--destination',
+ destination,
+ '--quiet',
+ ],
+ {
+ cwd: root,
+ encoding: 'utf8',
+ env: {
+ ...process.env,
+ HUGO_CACHEDIR: path.join(destination, '.hugo-cache'),
+ },
+ },
+ );
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ const html = fs.readFileSync(
+ path.join(destination, 'docs/target/index.html'),
+ 'utf8',
+ );
+ const block = html.match(
+ /([\s\S]*?)<\/div>\s*<\/div>\s*<\/div>/,
+ );
+ assert.ok(block, 'expected rendered backlinks group');
+ const beforeDetails = block[1].split(
+ '',
+ )[0];
+ assert.equal(
+ (beforeDetails.match(/td-shell-backlinks__item/g) || []).length,
+ 5,
+ );
+ assert.match(block[1], //);
+ assert.match(block[1], /Source 6/);
+ } finally {
+ fs.rmSync(destination, { recursive: true, force: true });
+ }
+});
diff --git a/tests/ui-ai/fixtures/backlinks.yaml b/tests/ui-ai/fixtures/backlinks.yaml
new file mode 100644
index 000000000..8e3ed1efb
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks.yaml
@@ -0,0 +1,5 @@
+enableGitInfo: false
+disableLanguages: [cn]
+languages:
+ en:
+ contentDir: tests/ui-ai/fixtures/backlinks/content/en
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/_index.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/_index.md
new file mode 100644
index 000000000..77c4cd3c4
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/_index.md
@@ -0,0 +1,3 @@
+---
+title: Fixture docs
+---
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/source-1.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-1.md
new file mode 100644
index 000000000..4aee9b5aa
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-1.md
@@ -0,0 +1,5 @@
+---
+title: Source 1
+---
+
+[Target](/docs/target/)
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/source-2.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-2.md
new file mode 100644
index 000000000..ad1dcef4d
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-2.md
@@ -0,0 +1,5 @@
+---
+title: Source 2
+---
+
+[Target](/docs/target/)
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/source-3.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-3.md
new file mode 100644
index 000000000..513529f01
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-3.md
@@ -0,0 +1,5 @@
+---
+title: Source 3
+---
+
+[Target](/docs/target/)
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/source-4.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-4.md
new file mode 100644
index 000000000..cae32ee7d
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-4.md
@@ -0,0 +1,5 @@
+---
+title: Source 4
+---
+
+[Target](/docs/target/)
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/source-5.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-5.md
new file mode 100644
index 000000000..be8bd888e
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-5.md
@@ -0,0 +1,5 @@
+---
+title: Source 5
+---
+
+[Target](/docs/target/)
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/source-6.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-6.md
new file mode 100644
index 000000000..0c912a9a7
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/source-6.md
@@ -0,0 +1,5 @@
+---
+title: Source 6
+---
+
+[Target](/docs/target/)
diff --git a/tests/ui-ai/fixtures/backlinks/content/en/docs/target.md b/tests/ui-ai/fixtures/backlinks/content/en/docs/target.md
new file mode 100644
index 000000000..9414ace95
--- /dev/null
+++ b/tests/ui-ai/fixtures/backlinks/content/en/docs/target.md
@@ -0,0 +1,6 @@
+---
+title: Backlink target
+description: Receives six fixture backlinks.
+---
+
+Fixture target.
diff --git a/tests/ui-ai/kapa-adapter.test.cjs b/tests/ui-ai/kapa-adapter.test.cjs
new file mode 100644
index 000000000..c24e09e36
--- /dev/null
+++ b/tests/ui-ai/kapa-adapter.test.cjs
@@ -0,0 +1,234 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const adapter = require('../../assets/js/kapa-adapter.js');
+
+function harness() {
+ const calls = [];
+ const timers = new Map();
+ const scripts = [];
+ let nextTimer = 1;
+ let renderCallbacks = [];
+ const trigger = {
+ dataset: {},
+ disabled: false,
+ attrs: {},
+ setAttribute(name, value) { this.attrs[name] = value; },
+ removeAttribute(name) { delete this.attrs[name]; },
+ focus() { this.focused = true; },
+ };
+ const status = {
+ textContent: '',
+ classList: { toggle() {} },
+ };
+ const documentObject = {
+ activeElement: trigger,
+ querySelector(selector) {
+ if (selector === '[data-hg-ai-status]') return status;
+ if (selector === 'script[data-hg-kapa-widget]') {
+ return scripts.find((script) => !script.removed) || null;
+ }
+ return null;
+ },
+ querySelectorAll(selector) {
+ return selector === '[data-hg-ask-ai]' ? [trigger] : [];
+ },
+ createElement(name) {
+ assert.equal(name, 'script');
+ const listeners = new Map();
+ const script = {
+ dataset: {},
+ attrs: {},
+ addEventListener(name, callback) { listeners.set(name, callback); },
+ setAttribute(name, value) { this.attrs[name] = value; },
+ remove() { this.removed = true; },
+ fire(name) {
+ const callback = listeners.get(name);
+ if (callback) callback();
+ },
+ };
+ scripts.push(script);
+ return script;
+ },
+ head: {
+ appendChild(script) { script.appended = true; },
+ },
+ };
+ const windowObject = {
+ setKapaImplementation() {
+ this.Kapa = function (method, value) {
+ calls.push([method, value]);
+ if (method === 'render') renderCallbacks.push(value.onRender);
+ };
+ },
+ Kapa(method, value) {
+ calls.push([method, value]);
+ if (method === 'render') renderCallbacks.push(value.onRender);
+ },
+ setTimeout(callback) {
+ const id = nextTimer++;
+ timers.set(id, callback);
+ return id;
+ },
+ clearTimeout(id) { timers.delete(id); },
+ };
+ const config = {
+ websiteId: 'website',
+ sourceGroupId: 'source-en',
+ locale: 'en',
+ themeColor: '#123456',
+ labels: { error: 'unavailable' },
+ };
+ return {
+ calls,
+ config,
+ documentObject,
+ fireRender(index = renderCallbacks.length - 1) { renderCallbacks[index](); },
+ fireTimeout() { Array.from(timers.values()).forEach((callback) => callback()); },
+ installBundle() {
+ const queued =
+ windowObject.Kapa && Array.isArray(windowObject.Kapa.q)
+ ? windowObject.Kapa.q.slice()
+ : [];
+ windowObject.setKapaImplementation();
+ queued.forEach((args) => windowObject.Kapa(...Array.from(args)));
+ },
+ renderCallbacks,
+ scripts,
+ trigger,
+ windowObject,
+ };
+}
+
+test('uses one fixed bundle and explicit privacy-safe widget settings', () => {
+ assert.equal(
+ adapter.BUNDLE_URL,
+ 'https://widget.kapa.ai/kapa-widget.bundle.js',
+ );
+ const attrs = adapter.scriptAttributes({
+ websiteId: 'website',
+ sourceGroupId: 'source-cn',
+ locale: 'zh',
+ themeColor: '#123456',
+ });
+ assert.equal(attrs['data-render-on-load'], 'false');
+ assert.equal(attrs['data-launcher-button-hidden'], 'true');
+ assert.equal(attrs['data-search-mode-enabled'], 'false');
+ assert.equal(attrs['data-modal-open-on-command-k'], 'false');
+ assert.equal(attrs['data-consent-required'], 'false');
+ assert.equal(attrs['data-user-analytics-cookie-enabled'], 'false');
+ assert.equal(attrs['data-user-analytics-fingerprint-enabled'], 'false');
+ assert.equal(attrs['data-bot-protection-mechanism'], 'hcaptcha');
+ assert.equal(attrs['data-source-group-ids-include'], 'source-cn');
+ assert.equal(attrs['data-project-color'], '#123456');
+ assert.equal(attrs['data-anchor-color'], '#123456');
+ assert.equal(attrs['data-project-color-dark'], '#8495a7');
+ assert.equal(attrs['data-anchor-color-dark'], '#a0aebb');
+ assert.notEqual(attrs['data-project-color-dark'], '#9f83ff');
+ assert.notEqual(attrs['data-anchor-color-dark'], '#b6a3ff');
+});
+
+test('sends only the trimmed query after explicit activation and render', () => {
+ const h = harness();
+ const controller = adapter.createController(
+ h.windowObject,
+ h.documentObject,
+ h.config,
+ );
+ assert.deepEqual(h.calls.map(([name]) => name), ['onModalClose']);
+
+ controller.activate(' how to start? ', true, h.trigger);
+ assert.equal(controller.getState(), 'loading');
+ assert.deepEqual(h.calls.map(([name]) => name), ['onModalClose', 'render']);
+
+ h.scripts[0].fire('load');
+ h.fireRender();
+ assert.equal(controller.getState(), 'ready');
+ assert.deepEqual(h.calls.slice(-2), [
+ ['setSourceGroupIDs', ['source-en']],
+ ['open', { mode: 'ai', query: 'how to start?', submit: true }],
+ ]);
+ assert.equal(
+ JSON.stringify(h.calls).includes('http'),
+ false,
+ 'no page URL is passed to Kapa',
+ );
+});
+
+test('ignores duplicate activation and never opens after a late render', () => {
+ const h = harness();
+ const controller = adapter.createController(
+ h.windowObject,
+ h.documentObject,
+ h.config,
+ );
+ controller.activate('first', true, h.trigger);
+ controller.activate('second', true, h.trigger);
+ assert.equal(
+ h.calls.filter(([name]) => name === 'render').length,
+ 1,
+ );
+
+ h.fireTimeout();
+ assert.equal(controller.getState(), 'error');
+ assert.equal(h.scripts[0].removed, true);
+ h.fireRender();
+ assert.equal(
+ h.calls.filter(([name]) => name === 'open').length,
+ 0,
+ );
+});
+
+test('launcher opens a blank session without auto-submit', () => {
+ const h = harness();
+ const controller = adapter.createController(
+ h.windowObject,
+ h.documentObject,
+ h.config,
+ );
+ controller.activate('', false, h.trigger);
+ h.scripts[0].fire('load');
+ h.fireRender();
+ assert.deepEqual(h.calls.at(-1), [
+ 'open',
+ { mode: 'ai', query: '', submit: false },
+ ]);
+});
+
+test('a pending timeout retries with a fresh script and ignores the late attempt', () => {
+ const h = harness();
+ const controller = adapter.createController(
+ h.windowObject,
+ h.documentObject,
+ h.config,
+ );
+ controller.activate('first', true, h.trigger);
+ assert.equal(h.scripts.length, 1);
+ const staleRender = h.renderCallbacks[0];
+
+ h.fireTimeout();
+ assert.equal(controller.getState(), 'error');
+ assert.equal(h.scripts[0].removed, true);
+ assert.equal(h.trigger.attrs.title, 'unavailable');
+
+ controller.activate('second', true, h.trigger);
+ assert.equal(h.trigger.attrs.title, undefined);
+ assert.equal(h.scripts.length, 2);
+ assert.match(h.scripts[1].src, /\?hg-retry=2$/);
+ staleRender();
+ assert.equal(
+ h.calls.filter(([name]) => name === 'open').length,
+ 0,
+ 'a late callback from the timed-out script must stay inert',
+ );
+
+ h.installBundle();
+ h.scripts[1].fire('load');
+ h.fireRender();
+ assert.equal(controller.getState(), 'ready');
+ assert.equal(h.trigger.attrs.title, undefined);
+ assert.deepEqual(h.calls.at(-1), [
+ 'open',
+ { mode: 'ai', query: 'second', submit: true },
+ ]);
+});
diff --git a/tests/ui-ai/ui-contract.test.cjs b/tests/ui-ai/ui-contract.test.cjs
new file mode 100644
index 000000000..c67f12fe7
--- /dev/null
+++ b/tests/ui-ai/ui-contract.test.cjs
@@ -0,0 +1,126 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const test = require('node:test');
+
+const root = path.resolve(__dirname, '../..');
+const read = (file) => fs.readFileSync(path.join(root, file), 'utf8');
+
+test('disabled AI emits no widget or adapter markup', () => {
+ const config = read('hugo.yaml');
+ const hook = read('layouts/_partials/hooks/body-end.html');
+ assert.match(config, /ai_search:\n\s+enabled: false/);
+ assert.match(hook, /\{\{- if \$ai\.enabled -\}\}/);
+ assert.equal(config.includes('widget.kapa.ai'), false);
+});
+
+test('Kapa active resource is dynamic, exact-hosted, and never wildcarded', () => {
+ const adapter = read('assets/js/kapa-adapter.js');
+ const hook = read('layouts/_partials/hooks/body-end.html');
+ assert.match(
+ adapter,
+ /https:\/\/widget\.kapa\.ai\/kapa-widget\.bundle\.js/,
+ );
+ assert.equal(adapter.includes('*.kapa.ai'), false);
+ assert.equal(adapter.includes('https://*'), false);
+ assert.equal(hook.includes('
'
+ '"
+ )
+ self.assertEqual(
+ parser.authored_violations,
+ [
+ "duplicate src attribute on