sync update from LAN repo (source dhk-1 @ 3b1ec5b4)

This commit is contained in:
gozeros committed 2026-11-05 10:56:34 +08:00
1 parent da6521b6cb
commit 264e2200d6
995 files changed
+148105 -13399

No files matched your search

@@ -0,0 +1,11 @@
#!/usr/bin/env python3
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "_shared"))
import render_bbc_page as renderer
from fast_patch_page import run
if __name__ == "__main__":
sys.exit(run(renderer, output_stem="bbc-page"))
@@ -0,0 +1,576 @@
#!/usr/bin/env python3
"""Validate BBC page data and inject it into the bundled HTML template."""
from __future__ import annotations
import argparse
import html as html_lib
import json
import re
import sys
from pathlib import Path
from typing import Any
from urllib.parse import urlparse
SKILL_ROOT = Path(__file__).resolve().parent.parent
ASSETS_DIR = SKILL_ROOT / "assets"
DEFAULT_DATA_PATH = ASSETS_DIR / "default-data.json"
TEMPLATE_PATH = ASSETS_DIR / "bbc-template.html"
RUNTIME_PATH = ASSETS_DIR / "bbc-runtime.js"
DATA_MARKER = "__BBC_PAGE_DATA__"
RUNTIME_MARKER = "__BBC_PAGE_RUNTIME__"
TITLE_RE = re.compile(r"<title>[^<]*</title>", re.IGNORECASE)
MODULES = (
"site",
"navigation",
"breaking",
"lead",
"focus",
"media",
"moreNews",
"regions",
"newsletter",
"footer",
)
THEMES = {"auto", "light", "dark"}
FOCUS_VISUALS = {"harbor", "satellite", "creative-city", "station"}
MEDIA_VISUALS = {"studio", "bulletin", "ocean"}
MORE_VISUALS = {"logistics", "market", "device", "energy"}
REMOTE_MEDIA_TYPES = {"image", "video", "webpage"}
class DataValidationError(ValueError):
"""Raised when the BBC page JSON cannot satisfy the template contract."""
def _read_json(path: Path) -> dict[str, Any]:
try:
data = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise DataValidationError(f"JSON file does not exist: {path}") from exc
except json.JSONDecodeError as exc:
raise DataValidationError(
f"Invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}"
) from exc
if not isinstance(data, dict):
raise DataValidationError("Top-level JSON value must be an object")
return data
def _mapping(value: Any, path: str, errors: list[str]) -> dict[str, Any]:
if not isinstance(value, dict):
errors.append(f"{path} must be an object")
return {}
return value
def _array(
value: Any,
path: str,
errors: list[str],
*,
limit: int | None = None,
) -> list[Any]:
if not isinstance(value, list):
errors.append(f"{path} must be an array")
return []
if limit is not None and len(value) > limit:
errors.append(f"{path} may contain at most {limit} items")
return value
def _non_empty_string(value: Any, path: str, errors: list[str]) -> None:
if not isinstance(value, str) or not value.strip():
errors.append(f"{path} must be a non-empty string")
def _remote_url(value: Any, path: str, errors: list[str], *, required: bool = False, data_prefix: str = "") -> None:
if value in (None, "") and not required:
return
if not isinstance(value, str) or not value.strip():
errors.append(f"{path} must be a non-empty URL")
return
candidate = value.strip()
if data_prefix and candidate.lower().startswith(data_prefix):
return
parsed = urlparse(candidate)
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
errors.append(f"{path} must use an http(s) URL")
def _validate_remote_media_tree(value: Any, path: str, errors: list[str]) -> None:
if isinstance(value, list):
for index, item in enumerate(value):
_validate_remote_media_tree(item, f"{path}[{index}]", errors)
return
if not isinstance(value, dict):
return
media = value.get("media")
if isinstance(media, dict) and "type" in media:
media_path = f"{path}.media"
media_data = _mapping(media, media_path, errors)
media_type = media_data.get("type")
if media_type not in REMOTE_MEDIA_TYPES:
errors.append(f"{media_path}.type must be one of: {', '.join(sorted(REMOTE_MEDIA_TYPES))}")
elif media_type in {"image", "video"}:
_remote_url(media_data.get("mediaUrl"), f"{media_path}.mediaUrl", errors, required=True, data_prefix=f"data:{media_type}/")
if media_type == "video":
_remote_url(media_data.get("posterUrl"), f"{media_path}.posterUrl", errors, data_prefix="data:image/")
if media_type == "webpage":
_remote_url(media_data.get("pageUrl"), f"{media_path}.pageUrl", errors, required=True)
_remote_url(media_data.get("mediaUrl"), f"{media_path}.mediaUrl", errors, data_prefix="data:image/")
if "embed" in media_data and not isinstance(media_data.get("embed"), bool):
errors.append(f"{media_path}.embed must be a boolean")
elif media_type in {"image", "video"}:
_remote_url(media_data.get("pageUrl"), f"{media_path}.pageUrl", errors)
for key, item in value.items():
if key != "media":
_validate_remote_media_tree(item, f"{path}.{key}", errors)
def _string(value: Any, path: str, errors: list[str]) -> None:
if not isinstance(value, str):
errors.append(f"{path} must be a string")
def _strings(
value: dict[str, Any],
keys: tuple[str, ...],
path: str,
errors: list[str],
) -> None:
for key in keys:
_non_empty_string(value.get(key), f"{path}.{key}", errors)
def _href(value: Any, path: str, errors: list[str]) -> None:
_non_empty_string(value, path, errors)
if isinstance(value, str) and not value.startswith("#"):
errors.append(f"{path} must be an in-page anchor starting with #")
def _validate_links(
value: Any,
path: str,
errors: list[str],
*,
limit: int,
require_items: bool,
) -> list[Any]:
items = _array(value, path, errors, limit=limit)
if require_items and not items:
errors.append(f"{path} must contain at least one item")
for index, link_value in enumerate(items):
item_path = f"{path}[{index}]"
link = _mapping(link_value, item_path, errors)
_non_empty_string(link.get("label"), f"{item_path}.label", errors)
_href(link.get("href"), f"{item_path}.href", errors)
return items
def _validate_story_items(
value: Any,
path: str,
errors: list[str],
*,
limit: int,
visuals: set[str],
focus: bool = False,
media: bool = False,
) -> list[Any]:
items = _array(value, path, errors, limit=limit)
if not items:
errors.append(f"{path} must contain at least one item")
seen: set[str] = set()
for index, item_value in enumerate(items):
item_path = f"{path}[{index}]"
item = _mapping(item_value, item_path, errors)
item_id = item.get("id")
_non_empty_string(item_id, f"{item_path}.id", errors)
if isinstance(item_id, str):
if item_id in seen:
errors.append(f"{item_path}.id must be unique")
seen.add(item_id)
keys = ("title", "meta") if media else ("kicker", "title", "time")
_strings(item, keys, item_path, errors)
if focus:
_string(item.get("summary"), f"{item_path}.summary", errors)
_strings(item, ("section",), item_path, errors)
_href(item.get("href"), f"{item_path}.href", errors)
if media and not isinstance(item.get("live"), bool):
errors.append(f"{item_path}.live must be a boolean")
if item.get("visual") not in visuals:
errors.append(
f"{item_path}.visual must be one of: "
f"{', '.join(sorted(visuals))}"
)
return items
def validate_document(data: dict[str, Any]) -> dict[str, Any]:
errors: list[str] = []
_validate_remote_media_tree(data, "$", errors)
for module in MODULES:
if module not in data:
errors.append(f"Missing top-level module: {module}")
site = _mapping(data.get("site"), "site", errors)
_strings(
site,
("pageTitle", "description", "accountLabel", "updatedDate"),
"site",
errors,
)
if site.get("theme") not in THEMES:
errors.append("site.theme must be one of: auto, dark, light")
brand_letters = _array(
site.get("brandLetters"),
"site.brandLetters",
errors,
limit=6,
)
if len(brand_letters) < 2:
errors.append("site.brandLetters must contain at least 2 letters")
for index, letter in enumerate(brand_letters):
if not isinstance(letter, str) or len(letter.strip()) != 1:
errors.append(
f"site.brandLetters[{index}] must be a single character"
)
navigation = _mapping(data.get("navigation"), "navigation", errors)
_strings(
navigation,
(
"channelTitle",
"moreLabel",
"searchLabel",
"searchPlaceholder",
"searchButton",
),
"navigation",
errors,
)
global_links = _validate_links(
navigation.get("global"),
"navigation.global",
errors,
limit=12,
require_items=True,
)
channel_links = _validate_links(
navigation.get("channel"),
"navigation.channel",
errors,
limit=12,
require_items=True,
)
drawer_links = _validate_links(
navigation.get("drawer"),
"navigation.drawer",
errors,
limit=12,
require_items=True,
)
breaking = _mapping(data.get("breaking"), "breaking", errors)
_strings(breaking, ("label", "text", "time"), "breaking", errors)
lead = _mapping(data.get("lead"), "lead", errors)
_strings(
lead,
(
"kicker",
"title",
"summary",
"byline",
"time",
"section",
"visualLabel",
"stamp",
"credit",
),
"lead",
errors,
)
_href(lead.get("sectionHref"), "lead.sectionHref", errors)
if lead.get("visual") != "research-ship":
errors.append("lead.visual must be: research-ship")
related = _validate_links(
lead.get("related"),
"lead.related",
errors,
limit=6,
require_items=False,
)
focus = _mapping(data.get("focus"), "focus", errors)
_strings(focus, ("title", "moreLabel"), "focus", errors)
focus_items = _validate_story_items(
focus.get("items"),
"focus.items",
errors,
limit=8,
visuals=FOCUS_VISUALS,
focus=True,
)
media = _mapping(data.get("media"), "media", errors)
_strings(media, ("title", "moreLabel"), "media", errors)
video_items = _validate_story_items(
media.get("videos"),
"media.videos",
errors,
limit=6,
visuals=MEDIA_VISUALS,
media=True,
)
modal = _mapping(media.get("modal"), "media.modal", errors)
_strings(
modal,
("title", "streamTitle", "streamSubtitle", "currentProgram"),
"media.modal",
errors,
)
audio = _mapping(media.get("audio"), "media.audio", errors)
_strings(
audio,
("sectionTitle", "title", "meta", "durationLabel"),
"media.audio",
errors,
)
duration = audio.get("durationSeconds")
if (
not isinstance(duration, int)
or isinstance(duration, bool)
or not 1 <= duration <= 86400
):
errors.append(
"media.audio.durationSeconds must be an integer from 1 to 86400"
)
more_news = _mapping(data.get("moreNews"), "moreNews", errors)
_strings(
more_news,
("title", "moreLabel", "rankingTitle"),
"moreNews",
errors,
)
more_items = _validate_story_items(
more_news.get("items"),
"moreNews.items",
errors,
limit=12,
visuals=MORE_VISUALS,
)
ranking = _array(
more_news.get("ranking"),
"moreNews.ranking",
errors,
limit=10,
)
if not ranking:
errors.append("moreNews.ranking must contain at least one item")
for index, item_value in enumerate(ranking):
item_path = f"moreNews.ranking[{index}]"
item = _mapping(item_value, item_path, errors)
_non_empty_string(item.get("title"), f"{item_path}.title", errors)
_href(item.get("href"), f"{item_path}.href", errors)
regions = _mapping(data.get("regions"), "regions", errors)
_strings(
regions,
("title", "moreLabel", "weatherTitle", "weatherLabel"),
"regions",
errors,
)
region_items = _array(
regions.get("items"),
"regions.items",
errors,
limit=10,
)
if not region_items:
errors.append("regions.items must contain at least one item")
for index, item_value in enumerate(region_items):
item = _mapping(item_value, f"regions.items[{index}]", errors)
_strings(
item,
("region", "title"),
f"regions.items[{index}]",
errors,
)
weather_items = _array(
regions.get("weather"),
"regions.weather",
errors,
limit=10,
)
if not weather_items:
errors.append("regions.weather must contain at least one item")
for index, item_value in enumerate(weather_items):
item = _mapping(item_value, f"regions.weather[{index}]", errors)
_strings(
item,
("city", "temperature", "condition"),
f"regions.weather[{index}]",
errors,
)
newsletter = _mapping(data.get("newsletter"), "newsletter", errors)
_strings(
newsletter,
("title", "text", "placeholder", "button", "successPrefix"),
"newsletter",
errors,
)
footer = _mapping(data.get("footer"), "footer", errors)
_strings(footer, ("copyright", "legal"), "footer", errors)
footer_links = _validate_links(
footer.get("links"),
"footer.links",
errors,
limit=12,
require_items=True,
)
if errors:
raise DataValidationError("; ".join(errors))
return {
"modules": list(MODULES),
"counts": {
"global_navigation": len(global_links),
"channel_navigation": len(channel_links),
"drawer_navigation": len(drawer_links),
"related": len(related),
"focus": len(focus_items),
"videos": len(video_items),
"more_news": len(more_items),
"ranking": len(ranking),
"regions": len(region_items),
"weather": len(weather_items),
"footer_links": len(footer_links),
},
}
def render_document(data: dict[str, Any], template: str, runtime: str) -> str:
validate_document(data)
if template.count(DATA_MARKER) != 1:
raise DataValidationError(
"Bundled template must contain exactly one data marker"
)
if template.count(RUNTIME_MARKER) != 1:
raise DataValidationError(
"Bundled template must contain exactly one runtime marker"
)
serialized = json.dumps(data, ensure_ascii=False, indent=2).replace(
"</",
"<\\/",
)
safe_runtime = runtime.replace("</script", "<\\/script")
rendered = template.replace(DATA_MARKER, serialized)
rendered = rendered.replace(RUNTIME_MARKER, safe_runtime)
page_title = str((data.get("site") or {}).get("pageTitle") or "").strip()
if page_title:
rendered = TITLE_RE.sub(
f"<title>{html_lib.escape(page_title)}</title>",
rendered,
count=1,
)
return rendered
def _write_new(path: Path, content: str) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
try:
with path.open("x", encoding="utf-8", newline="\n") as handle:
handle.write(content)
except FileExistsError as exc:
raise DataValidationError(
f"Refusing to overwrite existing file: {path}"
) from exc
def _emit(payload: dict[str, Any]) -> None:
print(json.dumps(payload, ensure_ascii=False))
def _command_init(output: Path) -> dict[str, Any]:
data = _read_json(DEFAULT_DATA_PATH)
summary = validate_document(data)
_write_new(
output,
json.dumps(data, ensure_ascii=False, indent=2) + "\n",
)
return {"status": "ok", "action": "init", "output": str(output), **summary}
def _command_validate(input_path: Path) -> dict[str, Any]:
data = _read_json(input_path)
summary = validate_document(data)
return {"status": "ok", "action": "validate", "input": str(input_path), **summary}
def _command_render(input_path: Path, output: Path) -> dict[str, Any]:
data = _read_json(input_path)
template = TEMPLATE_PATH.read_text(encoding="utf-8")
runtime = RUNTIME_PATH.read_text(encoding="utf-8")
rendered = render_document(data, template, runtime)
_write_new(output, rendered)
summary = validate_document(data)
return {
"status": "ok",
"action": "render",
"input": str(input_path),
"output": str(output),
**summary,
}
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=__doc__)
subparsers = parser.add_subparsers(dest="command", required=True)
init_parser = subparsers.add_parser(
"init",
help="Create a new editable JSON document",
)
init_parser.add_argument("--output", type=Path, required=True)
validate_parser = subparsers.add_parser(
"validate",
help="Validate an existing JSON document",
)
validate_parser.add_argument("--input", type=Path, required=True)
render_parser = subparsers.add_parser(
"render",
help="Render validated JSON into the bundled HTML template",
)
render_parser.add_argument("--input", type=Path, required=True)
render_parser.add_argument("--output", type=Path, required=True)
return parser
def main(argv: list[str] | None = None) -> int:
parser = _build_parser()
args = parser.parse_args(argv)
try:
if args.command == "init":
result = _command_init(args.output)
elif args.command == "validate":
result = _command_validate(args.input)
else:
result = _command_render(args.input, args.output)
except (DataValidationError, OSError) as exc:
_emit({"status": "error", "action": args.command, "error": str(exc)})
return 2
_emit(result)
return 0
if __name__ == "__main__":
sys.exit(main())