sync update from LAN repo (source master @ ca48c4ec)

This commit is contained in:
gozeros committed 2026-11-05 10:53:54 +08:00
1 parent 8bc8b0e082
commit ea9dcff9c0
873 files changed
+107866 -14011

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_manila_times_page as renderer
from fast_patch_page import run
if __name__ == "__main__":
sys.exit(run(renderer, output_stem="manila-times-page"))
@@ -0,0 +1,547 @@
#!/usr/bin/env python3
"""Validate Manila Times-style page data and render the bundled template."""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
from typing import Any
from urllib.parse import urlparse
SKILL_DIR = Path(__file__).resolve().parents[1]
ASSETS_DIR = SKILL_DIR / "assets"
DEFAULT_DATA_PATH = ASSETS_DIR / "default-data.json"
TEMPLATE_PATH = ASSETS_DIR / "manila-times-template.html"
RUNTIME_PATH = ASSETS_DIR / "manila-times-runtime.js"
MODULES = (
"site",
"navigation",
"ticker",
"lead",
"pulse",
"regions",
"opinion",
"sections",
"media",
"footer",
)
LEAD_VISUALS = {"bay-transit", "port", "city"}
REGION_VISUALS = {"luzon", "visayas", "mindanao", "metro"}
BUSINESS_VISUALS = {"market", "factory", "shipping"}
SPORTS_VISUALS = {"basketball", "running", "volleyball"}
VIDEO_VISUALS = {"studio", "islands", "city-night"}
FORBIDDEN_TEXT = ("<script", "<iframe", "javascript:", "http://", "https://")
REMOTE_MEDIA_TYPES = {"image", "video", "webpage"}
MEDIA_URL_KEYS = {"mediaUrl", "posterUrl", "pageUrl"}
TECHNICAL_TEXT_KEYS = {"id", "href", "visual", "direction", "theme", "language", "type", "mediaUrl", "posterUrl", "pageUrl"}
class DataValidationError(ValueError):
"""Raised when JSON does not satisfy the fixed page contract."""
def _read_json(path: Path) -> dict[str, Any]:
try:
value = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise DataValidationError(f"input 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(value, dict):
raise DataValidationError("top-level JSON value must be an object")
return value
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],
*,
minimum: int,
maximum: int,
) -> list[Any]:
if not isinstance(value, list):
errors.append(f"{path} must be an array")
return []
if len(value) < minimum:
errors.append(f"{path} must contain at least {minimum} item(s)")
if len(value) > maximum:
errors.append(f"{path} must contain at most {maximum} item(s)")
return value
def _required_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 _href(value: Any, path: str, errors: list[str]) -> None:
_required_string(value, path, errors)
if isinstance(value, str) and not value.startswith("#"):
errors.append(f"{path} must be an in-page anchor beginning with #")
def _unique_id(item: dict[str, Any], path: str, seen: set[str], errors: list[str]) -> None:
item_id = item.get("id")
_required_string(item_id, f"{path}.id", errors)
if isinstance(item_id, str):
if item_id in seen:
errors.append(f"{path}.id duplicates {item_id!r}")
seen.add(item_id)
def _links(
value: Any,
path: str,
errors: list[str],
*,
minimum: int,
maximum: int,
) -> list[Any]:
items = _array(value, path, errors, minimum=minimum, maximum=maximum)
for index, raw in enumerate(items):
item = _mapping(raw, f"{path}[{index}]", errors)
_required_string(item.get("label"), f"{path}[{index}].label", errors)
_href(item.get("href"), f"{path}[{index}].href", errors)
return items
def _strings(item: dict[str, Any], path: str, keys: tuple[str, ...], errors: list[str]) -> None:
for key in keys:
_required_string(item.get(key), f"{path}.{key}", errors)
def _validate_no_remote_or_markup(value: Any, path: str, errors: list[str]) -> None:
if isinstance(value, dict):
for key, item in value.items():
if key in MEDIA_URL_KEYS:
continue
_validate_no_remote_or_markup(item, f"{path}.{key}", errors)
elif isinstance(value, list):
for index, item in enumerate(value):
_validate_no_remote_or_markup(item, f"{path}[{index}]", errors)
elif isinstance(value, str):
lowered = value.lower()
if any(token in lowered for token in FORBIDDEN_TEXT):
errors.append(f"{path} must not contain HTML, script, iframe, or remote URLs")
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_type = media.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.get("mediaUrl"), f"{media_path}.mediaUrl", errors, required=True, data_prefix=f"data:{media_type}/")
if media_type == "video":
_remote_url(media.get("posterUrl"), f"{media_path}.posterUrl", errors, data_prefix="data:image/")
if media_type == "webpage":
_remote_url(media.get("pageUrl"), f"{media_path}.pageUrl", errors, required=True)
_remote_url(media.get("mediaUrl"), f"{media_path}.mediaUrl", errors, data_prefix="data:image/")
if "embed" in media and not isinstance(media.get("embed"), bool):
errors.append(f"{media_path}.embed must be a boolean")
elif media_type in {"image", "video"}:
_remote_url(media.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 _validate_chinese_reader_copy(
value: Any,
path: str,
errors: list[str],
*,
key: str | None = None,
) -> None:
if isinstance(value, dict):
for child_key, item in value.items():
_validate_chinese_reader_copy(
item,
f"{path}.{child_key}",
errors,
key=child_key,
)
elif isinstance(value, list):
for index, item in enumerate(value):
_validate_chinese_reader_copy(item, f"{path}[{index}]", errors, key=key)
elif (
isinstance(value, str)
and key not in TECHNICAL_TEXT_KEYS
and not (key and key.lower().endswith(("id", "href", "url")))
):
has_latin = any(
"a" <= character.lower() <= "z" for character in value
)
has_cjk = any("\u3400" <= character <= "\u9fff" for character in value)
if has_latin and not has_cjk:
errors.append(f"{path} must use Simplified Chinese reader-facing copy")
def _story(
value: Any,
path: str,
errors: list[str],
seen: set[str],
visuals: set[str],
) -> dict[str, Any]:
item = _mapping(value, path, errors)
_unique_id(item, path, seen, errors)
_strings(item, path, ("kicker", "title", "summary", "visual"), errors)
if item.get("visual") not in visuals:
errors.append(f"{path}.visual must be one of {sorted(visuals)}")
return item
def validate_document(data: dict[str, Any]) -> dict[str, int]:
errors: list[str] = []
missing = [name for name in MODULES if name not in data]
extra = [name for name in data if name not in MODULES]
if missing:
errors.append("missing top-level module(s): " + ", ".join(missing))
if extra:
errors.append("unknown top-level module(s): " + ", ".join(extra))
site = _mapping(data.get("site"), "site", errors)
_strings(
site,
"site",
(
"brandPrefix",
"brandAccent",
"kicker",
"tagline",
"dateLabel",
"editionLabel",
"pageTitle",
"description",
"language",
"skipLabel",
),
errors,
)
if site.get("theme") not in {"light", "dark", "auto"}:
errors.append("site.theme must be light, dark, or auto")
if site.get("language") != "zh-CN":
errors.append("site.language must be zh-CN")
weather = _array(site.get("weather"), "site.weather", errors, minimum=1, maximum=6)
seen_weather: set[str] = set()
for index, raw in enumerate(weather):
path = f"site.weather[{index}]"
item = _mapping(raw, path, errors)
_unique_id(item, path, seen_weather, errors)
_strings(item, path, ("city", "temp", "condition"), errors)
navigation = _mapping(data.get("navigation"), "navigation", errors)
_strings(
navigation,
"navigation",
("menuLabel", "searchLabel", "themeLightLabel", "themeDarkLabel"),
errors,
)
utility_left = _links(
navigation.get("utilityLeft"),
"navigation.utilityLeft",
errors,
minimum=1,
maximum=5,
)
utility_right = _links(
navigation.get("utilityRight"),
"navigation.utilityRight",
errors,
minimum=1,
maximum=5,
)
primary = _links(
navigation.get("primary"),
"navigation.primary",
errors,
minimum=3,
maximum=9,
)
drawer = _mapping(navigation.get("drawer"), "navigation.drawer", errors)
_strings(drawer, "navigation.drawer", ("eyebrow", "title", "text", "ctaLabel"), errors)
_href(drawer.get("ctaHref"), "navigation.drawer.ctaHref", errors)
search = _mapping(navigation.get("search"), "navigation.search", errors)
_strings(search, "navigation.search", ("title", "placeholder", "hint", "emptyMessage", "resultPrefix"), errors)
ticker = _mapping(data.get("ticker"), "ticker", errors)
_strings(ticker, "ticker", ("label", "text", "time"), errors)
_href(ticker.get("href"), "ticker.href", errors)
lead = _mapping(data.get("lead"), "lead", errors)
_strings(lead, "lead", ("datelineLeft", "datelineRight"), errors)
seen_lead: set[str] = set()
main = _story(lead.get("main"), "lead.main", errors, seen_lead, LEAD_VISUALS)
_strings(main, "lead.main", ("byline", "time"), errors)
side_stories = _array(lead.get("sideStories"), "lead.sideStories", errors, minimum=1, maximum=4)
for index, raw in enumerate(side_stories):
path = f"lead.sideStories[{index}]"
item = _story(raw, path, errors, seen_lead, LEAD_VISUALS)
_strings(item, path, ("byline", "time"), errors)
feeds = _array(lead.get("feeds"), "lead.feeds", errors, minimum=2, maximum=3)
seen_feeds: set[str] = set()
feed_items = 0
for feed_index, raw_feed in enumerate(feeds):
feed_path = f"lead.feeds[{feed_index}]"
feed = _mapping(raw_feed, feed_path, errors)
_unique_id(feed, feed_path, seen_feeds, errors)
_required_string(feed.get("label"), f"{feed_path}.label", errors)
items = _array(feed.get("items"), f"{feed_path}.items", errors, minimum=1, maximum=8)
feed_items += len(items)
for item_index, raw_item in enumerate(items):
item_path = f"{feed_path}.items[{item_index}]"
item = _mapping(raw_item, item_path, errors)
_strings(item, item_path, ("time", "title"), errors)
pulse = _mapping(data.get("pulse"), "pulse", errors)
_strings(pulse, "pulse", ("label", "title"), errors)
pulse_items = _array(pulse.get("items"), "pulse.items", errors, minimum=2, maximum=8)
seen_pulse: set[str] = set()
for index, raw in enumerate(pulse_items):
path = f"pulse.items[{index}]"
item = _mapping(raw, path, errors)
_unique_id(item, path, seen_pulse, errors)
_strings(item, path, ("label", "value", "change"), errors)
if item.get("direction") not in {"up", "down", "flat"}:
errors.append(f"{path}.direction must be up, down, or flat")
regions = _mapping(data.get("regions"), "regions", errors)
_strings(regions, "regions", ("eyebrow", "title", "moreLabel"), errors)
_href(regions.get("moreHref"), "regions.moreHref", errors)
region_tabs = _array(regions.get("tabs"), "regions.tabs", errors, minimum=2, maximum=6)
seen_regions: set[str] = set()
region_stories = 0
for tab_index, raw_tab in enumerate(region_tabs):
tab_path = f"regions.tabs[{tab_index}]"
tab = _mapping(raw_tab, tab_path, errors)
_unique_id(tab, tab_path, seen_regions, errors)
_required_string(tab.get("label"), f"{tab_path}.label", errors)
feature = _mapping(tab.get("feature"), f"{tab_path}.feature", errors)
_strings(feature, f"{tab_path}.feature", ("kicker", "title", "summary", "visual"), errors)
if feature.get("visual") not in REGION_VISUALS:
errors.append(f"{tab_path}.feature.visual must be one of {sorted(REGION_VISUALS)}")
items = _array(tab.get("items"), f"{tab_path}.items", errors, minimum=1, maximum=6)
region_stories += len(items)
for item_index, raw_item in enumerate(items):
item_path = f"{tab_path}.items[{item_index}]"
item = _mapping(raw_item, item_path, errors)
_strings(item, item_path, ("location", "title", "summary"), errors)
opinion = _mapping(data.get("opinion"), "opinion", errors)
_strings(opinion, "opinion", ("eyebrow", "title", "summary"), errors)
columns = _array(opinion.get("columns"), "opinion.columns", errors, minimum=2, maximum=6)
seen_columns: set[str] = set()
for index, raw in enumerate(columns):
path = f"opinion.columns[{index}]"
item = _mapping(raw, path, errors)
_unique_id(item, path, seen_columns, errors)
_strings(item, path, ("initial", "name", "title", "summary"), errors)
sections = _mapping(data.get("sections"), "sections", errors)
business = _mapping(sections.get("business"), "sections.business", errors)
_strings(business, "sections.business", ("eyebrow", "title", "moreLabel"), errors)
_href(business.get("moreHref"), "sections.business.moreHref", errors)
business_items = _array(business.get("items"), "sections.business.items", errors, minimum=2, maximum=6)
seen_business: set[str] = set()
for index, raw in enumerate(business_items):
_story(raw, f"sections.business.items[{index}]", errors, seen_business, BUSINESS_VISUALS)
sports = _mapping(sections.get("sports"), "sections.sports", errors)
_strings(sports, "sections.sports", ("eyebrow", "title", "moreLabel"), errors)
_href(sports.get("moreHref"), "sections.sports.moreHref", errors)
seen_sports: set[str] = set()
_story(sports.get("hero"), "sections.sports.hero", errors, seen_sports, SPORTS_VISUALS)
sports_items = _array(sports.get("items"), "sections.sports.items", errors, minimum=1, maximum=5)
for index, raw in enumerate(sports_items):
item = _mapping(raw, f"sections.sports.items[{index}]", errors)
_unique_id(item, f"sections.sports.items[{index}]", seen_sports, errors)
_strings(item, f"sections.sports.items[{index}]", ("kicker", "title", "visual"), errors)
if item.get("visual") not in SPORTS_VISUALS:
errors.append(f"sections.sports.items[{index}].visual must be one of {sorted(SPORTS_VISUALS)}")
market = _mapping(sections.get("market"), "sections.market", errors)
_required_string(market.get("title"), "sections.market.title", errors)
market_items = _array(market.get("items"), "sections.market.items", errors, minimum=1, maximum=6)
for index, raw in enumerate(market_items):
path = f"sections.market.items[{index}]"
item = _mapping(raw, path, errors)
_strings(item, path, ("label", "value"), errors)
if item.get("direction") not in {"up", "down", "flat"}:
errors.append(f"{path}.direction must be up, down, or flat")
media = _mapping(data.get("media"), "media", errors)
watch = _mapping(media.get("watch"), "media.watch", errors)
_strings(watch, "media.watch", ("eyebrow", "title", "moreLabel"), errors)
_href(watch.get("moreHref"), "media.watch.moreHref", errors)
videos = _array(watch.get("videos"), "media.watch.videos", errors, minimum=1, maximum=6)
seen_videos: set[str] = set()
for index, raw in enumerate(videos):
path = f"media.watch.videos[{index}]"
item = _mapping(raw, path, errors)
_unique_id(item, path, seen_videos, errors)
_strings(item, path, ("duration", "kicker", "title", "summary", "visual"), errors)
if item.get("visual") not in VIDEO_VISUALS:
errors.append(f"{path}.visual must be one of {sorted(VIDEO_VISUALS)}")
modal = _mapping(watch.get("modal"), "media.watch.modal", errors)
_strings(modal, "media.watch.modal", ("title", "streamSubtitle", "captionsOn", "captionsOff"), errors)
edition = _mapping(media.get("edition"), "media.edition", errors)
_strings(edition, "media.edition", ("eyebrow", "title", "summary", "openLabel", "subscribeLabel", "modalTitle", "date"), errors)
_href(edition.get("subscribeHref"), "media.edition.subscribeHref", errors)
pages = _array(edition.get("pages"), "media.edition.pages", errors, minimum=2, maximum=8)
seen_pages: set[str] = set()
for index, raw in enumerate(pages):
path = f"media.edition.pages[{index}]"
item = _mapping(raw, path, errors)
_unique_id(item, path, seen_pages, errors)
_strings(item, path, ("label", "headline", "text"), errors)
newsletter = _mapping(media.get("newsletter"), "media.newsletter", errors)
_strings(newsletter, "media.newsletter", ("eyebrow", "title", "text", "placeholder", "button", "successPrefix"), errors)
footer = _mapping(data.get("footer"), "footer", errors)
_strings(footer, "footer", ("description", "copyright", "legal"), errors)
footer_columns = _array(footer.get("columns"), "footer.columns", errors, minimum=1, maximum=5)
seen_footer: set[str] = set()
footer_links = 0
for index, raw in enumerate(footer_columns):
path = f"footer.columns[{index}]"
item = _mapping(raw, path, errors)
_unique_id(item, path, seen_footer, errors)
_required_string(item.get("title"), f"{path}.title", errors)
footer_links += len(_links(item.get("links"), f"{path}.links", errors, minimum=1, maximum=8))
_validate_remote_media_tree(data, "$", errors)
_validate_no_remote_or_markup(data, "$", errors)
_validate_chinese_reader_copy(data, "$", errors)
if errors:
raise DataValidationError("\n".join(f"- {error}" for error in errors))
return {
"weather_locations": len(weather),
"navigation_links": len(utility_left) + len(utility_right) + len(primary),
"lead_stories": 1 + len(side_stories),
"feeds": len(feeds),
"feed_items": feed_items,
"pulse_items": len(pulse_items),
"region_tabs": len(region_tabs),
"region_stories": region_stories,
"opinion_columns": len(columns),
"business_stories": len(business_items),
"sports_stories": 1 + len(sports_items),
"market_items": len(market_items),
"videos": len(videos),
"edition_pages": len(pages),
"footer_columns": len(footer_columns),
"footer_links": footer_links,
}
def render_document(data: dict[str, Any], template: str, runtime: str) -> str:
validate_document(data)
data_text = json.dumps(data, ensure_ascii=False, separators=(",", ":"))
data_text = data_text.replace("</script", "<\\/script")
if template.count("__MANILA_TIMES_PAGE_DATA__") != 1:
raise DataValidationError("template must contain one __MANILA_TIMES_PAGE_DATA__ marker")
if template.count("__MANILA_TIMES_PAGE_RUNTIME__") != 1:
raise DataValidationError("template must contain one __MANILA_TIMES_PAGE_RUNTIME__ marker")
rendered = template.replace("__MANILA_TIMES_PAGE_DATA__", data_text).replace("__MANILA_TIMES_PAGE_RUNTIME__", runtime)
if "__MANILA_TIMES_PAGE_" in rendered:
raise DataValidationError("unresolved template marker remains in rendered HTML")
return rendered
def _write_new(path: Path, content: str) -> None:
if path.exists():
raise DataValidationError(f"refusing to overwrite existing file: {path}; choose a new path")
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8", newline="\n")
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)
counts = validate_document(data)
_write_new(output, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
return {"status": "ok", "action": "init", "output": str(output), "modules": list(MODULES), "counts": counts}
def _command_validate(input_path: Path) -> dict[str, Any]:
counts = validate_document(_read_json(input_path))
return {"status": "ok", "action": "validate", "input": str(input_path), "modules": list(MODULES), "counts": counts}
def _command_render(input_path: Path, output: Path) -> dict[str, Any]:
data = _read_json(input_path)
counts = validate_document(data)
template = TEMPLATE_PATH.read_text(encoding="utf-8")
runtime = RUNTIME_PATH.read_text(encoding="utf-8")
_write_new(output, render_document(data, template, runtime))
return {"status": "ok", "action": "render", "input": str(input_path), "output": str(output), "modules": list(MODULES), "counts": counts}
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description="Initialize, validate, and render Manila Times-style portal JSON.")
subparsers = parser.add_subparsers(dest="command", required=True)
init_parser = subparsers.add_parser("init", help="write a fresh default JSON file")
init_parser.add_argument("--output", required=True, type=Path)
validate_parser = subparsers.add_parser("validate", help="validate a JSON file")
validate_parser.add_argument("--input", required=True, type=Path)
render_parser = subparsers.add_parser("render", help="render validated JSON into the fixed HTML template")
render_parser.add_argument("--input", required=True, type=Path)
render_parser.add_argument("--output", required=True, type=Path)
return parser
def main(argv: list[str] | None = None) -> int:
parser = _build_parser()
args = parser.parse_args(argv)
try:
if args.command == "init":
payload = _command_init(args.output)
elif args.command == "validate":
payload = _command_validate(args.input)
else:
payload = _command_render(args.input, args.output)
_emit(payload)
return 0
except (DataValidationError, OSError) as exc:
_emit({"status": "error", "action": args.command, "message": str(exc)})
return 1
if __name__ == "__main__":
sys.exit(main())