#!/usr/bin/env python3 """Guardrail checks for AI observability UI templates. This script is intentionally lightweight: it scans the observability templates and shared CSS for regression signals that previously hurt the war-room UI, including unreadable typography, raw SQL errors, oversized titles, and inline chart sizing. """ from __future__ import annotations import re import sys from dataclasses import dataclass from pathlib import Path ROOT = Path(__file__).resolve().parents[1] TEMPLATE_PATHS = [ "templates/admin/observability_overview.html", "templates/admin/agent_orchestration.html", "templates/admin/business_intel.html", "templates/admin/host_health.html", "templates/admin/ai_calls_dashboard.html", "templates/admin/budget.html", "templates/admin/promotion_review.html", "templates/admin/rag_queries.html", "templates/admin/quality_trend.html", "templates/admin/ppt_audit_history.html", ] OBSERVABILITY_NAV_ITEMS = [ ("templates/admin/observability_overview.html", "obs_overview", "/observability/overview", "觀測台總覽"), ("templates/admin/agent_orchestration.html", "obs_agent_orchestration", "/observability/agent_orchestration", "Agent 編排矩陣"), ("templates/admin/business_intel.html", "obs_business_intel", "/observability/business_intel", "商業面 × AI"), ("templates/admin/host_health.html", "obs_host_health", "/observability/host_health", "主機健康"), ("templates/admin/ai_calls_dashboard.html", "obs_ai_calls", "/observability/ai_calls", "AI 呼叫"), ("templates/admin/budget.html", "obs_budget", "/observability/budget", "預算控管"), ("templates/admin/promotion_review.html", "obs_promotion_review", "/observability/promotion_review", "RAG 晉升審核"), ("templates/admin/rag_queries.html", "obs_rag_queries", "/observability/rag_queries", "RAG 召回詳情"), ("templates/admin/quality_trend.html", "obs_quality_trend", "/observability/quality_trend", "反饋趨勢"), ("templates/admin/ppt_audit_history.html", "obs_ppt_audit", "/observability/ppt_audit_history", "PPT 視覺審核"), ] CSS_PATH = Path("static/css/observability-system.css") SHELL_PATH = Path("templates/components/_ewoooc_shell.html") BASE_PATH = Path("templates/ewoooc_base.html") ROUTE_PATH = Path("routes/admin_observability_routes.py") @dataclass(frozen=True) class Rule: code: str pattern: re.Pattern[str] message: str TEMPLATE_RULES = [ Rule( "legacy_serif_font", re.compile(r"\b(Georgia|Times New Roman)\b", re.IGNORECASE), "觀測台標題不得回退到 Times/Georgia；使用 Noto Sans TC / Inter 與 CSS token。", ), Rule( "raw_error_copy", re.compile( r"(查詢失敗:|ProgrammingError|UndefinedError|Traceback|Internal Server Error|relation\s+"|relation\s+\")" ), "不得把 SQL/Jinja exception 或 raw failure 文案直接顯示給使用者。", ), Rule( "inline_height", re.compile(r"style=\"[^\"]*height\s*:", re.IGNORECASE), "圖表/區塊高度請使用 .obs-chart-frame 系列或 CSS class，不要 inline height。", ), Rule( "static_inline_width", re.compile(r"style=\"(?=[^\"]*width\s*:)(?![^\"]*\{\{)[^\"]*\"", re.IGNORECASE), "靜態寬度請移到 CSS class；僅允許 progress 類動態 width={{ ... }}。", ), Rule( "oversized_title", re.compile(r"font-size:\s*clamp\([^;]*(3\.8rem|4\.45rem)", re.IGNORECASE), "頁面大標不得使用過大 clamp；使用 --obs-title-size token。", ), Rule( "pure_white_surface", re.compile(r"background\s*:\s*#fff\s*;", re.IGNORECASE), "觀測台 hover/card surface 不用純白；使用暖色 paper/surface token。", ), Rule( "wrong_business_active_page", re.compile(r"active_page\s*=\s*['\"]obs_business['\"]"), "商業戰情頁 active_page 必須是 obs_business_intel，否則觀測台 CSS 不會載入。", ), ] REQUIRED_CSS_SNIPPETS = [ "--obs-title-size", "--obs-value-size", ".momo-observability-mode", ".obs-chart-frame", ".obs-chart-frame-tall", ".obs-chart-frame-slim", ".obs-modal-preview", ".obs-progress-xs", ".obs-table-shell", ] REQUIRED_SHELL_SNIPPETS = [ "AI 中樞", "AI 觀測台", "戰情室", "系統與成本", "RAG 與品質", "momo-nav-tree", "momo-nav-subtree", "momo-nav-subtitle", "momo-nav-sublink", "rgba(255, 248, 238, 0.72)", "linear-gradient(180deg", ] FORBIDDEN_SHELL_PATTERNS = [ Rule( "pure_black_sidebar", re.compile(r"\.momo-sidebar\s*\{[^}]*background\s*:\s*(#000|black)\b", re.IGNORECASE | re.DOTALL), "側欄不得回退成純黑背景；必須維持暖深咖啡漸層。", ), Rule( "low_contrast_sublink", re.compile(r"\.momo-nav-sublink\s*\{[^}]*color\s*:\s*rgba\([^)]*,\s*0\.(?:[0-5][0-9]|60)\)", re.IGNORECASE | re.DOTALL), "第二/三層導覽文字透明度過低，會看不清楚；需維持足夠對比。", ), ] REQUIRED_BASE_SNIPPETS = [ "observability-system.css", "momo-observability-mode", "/observability/overview", "/observability/api/health_indicator", ] def line_number(text: str, index: int) -> int: return text.count("\n", 0, index) + 1 def scan_file(relative_path: Path) -> list[str]: path = ROOT / relative_path if not path.exists(): return [f"{relative_path}: missing required observability file"] text = path.read_text(encoding="utf-8") findings: list[str] = [] for rule in TEMPLATE_RULES: for match in rule.pattern.finditer(text): line = line_number(text, match.start()) snippet = match.group(0).replace("\n", " ")[:90] findings.append( f"{relative_path}:{line}: [{rule.code}] {rule.message} ({snippet})" ) return findings def scan_css() -> list[str]: path = ROOT / CSS_PATH if not path.exists(): return [f"{CSS_PATH}: missing required observability CSS"] text = path.read_text(encoding="utf-8") findings: list[str] = [] for snippet in REQUIRED_CSS_SNIPPETS: if snippet not in text: findings.append(f"{CSS_PATH}: missing required token/class `{snippet}`") return findings def scan_required_snippets(relative_path: Path, snippets: list[str], label: str) -> list[str]: path = ROOT / relative_path if not path.exists(): return [f"{relative_path}: missing required {label} file"] text = path.read_text(encoding="utf-8") findings: list[str] = [] for snippet in snippets: if snippet not in text: findings.append(f"{relative_path}: missing required {label} snippet `{snippet}`") return findings def scan_shell() -> list[str]: path = ROOT / SHELL_PATH if not path.exists(): return [f"{SHELL_PATH}: missing required shell file"] text = path.read_text(encoding="utf-8") findings = scan_required_snippets(SHELL_PATH, REQUIRED_SHELL_SNIPPETS, "sidebar/nav") for rule in FORBIDDEN_SHELL_PATTERNS: for match in rule.pattern.finditer(text): line = line_number(text, match.start()) snippet = match.group(0).replace("\n", " ")[:90] findings.append( f"{SHELL_PATH}:{line}: [{rule.code}] {rule.message} ({snippet})" ) return findings def scan_nav_contract() -> list[str]: shell_path = ROOT / SHELL_PATH base_path = ROOT / BASE_PATH route_path = ROOT / ROUTE_PATH if not shell_path.exists() or not base_path.exists(): return [] shell_text = shell_path.read_text(encoding="utf-8") base_text = base_path.read_text(encoding="utf-8") route_text = route_path.read_text(encoding="utf-8") if route_path.exists() else "" findings: list[str] = [] for template_path, active_page, url, label in OBSERVABILITY_NAV_ITEMS: template = ROOT / template_path if not template.exists(): findings.append(f"{template_path}: missing observability template for `{label}`") continue template_text = template.read_text(encoding="utf-8") active_pattern = re.compile( r"set\s+active_page\s*=\s*['\"]" + re.escape(active_page) + r"['\"]" ) route_has_contract = template_path.replace("templates/", "") in route_text and active_page in route_text if not active_pattern.search(template_text) and not route_has_contract: findings.append( f"{template_path}: active_page must be `{active_page}` in template or route for `{label}`" ) if active_page not in shell_text: findings.append(f"{SHELL_PATH}: sidebar missing active_page `{active_page}`") if url not in shell_text: findings.append(f"{SHELL_PATH}: sidebar missing URL `{url}` for `{label}`") if label not in shell_text: findings.append(f"{SHELL_PATH}: sidebar missing label `{label}`") if active_page not in base_text: findings.append(f"{BASE_PATH}: momo-observability-mode list missing `{active_page}`") sidebar_observability_links = set(re.findall(r'href="(/observability/[^"]+)"', shell_text)) expected_links = {url for _, _, url, _ in OBSERVABILITY_NAV_ITEMS} extra_links = sorted(sidebar_observability_links - expected_links) missing_links = sorted(expected_links - sidebar_observability_links) for url in extra_links: findings.append(f"{SHELL_PATH}: unexpected observability sidebar URL `{url}`") for url in missing_links: findings.append(f"{SHELL_PATH}: missing observability sidebar URL `{url}`") return findings def main() -> int: findings: list[str] = [] for template_path in TEMPLATE_PATHS: findings.extend(scan_file(Path(template_path))) findings.extend(scan_css()) findings.extend(scan_shell()) findings.extend(scan_required_snippets(BASE_PATH, REQUIRED_BASE_SNIPPETS, "base/topbar")) findings.extend(scan_nav_contract()) if findings: print("Observability UI guard: FAIL") for finding in findings: print(f"- {finding}") return 1 print("Observability UI guard: PASS") print(f"- templates checked: {len(TEMPLATE_PATHS)}") print(f"- css guardrails checked: {len(REQUIRED_CSS_SNIPPETS)}") print(f"- sidebar/nav guardrails checked: {len(REQUIRED_SHELL_SNIPPETS)}") print(f"- base/topbar guardrails checked: {len(REQUIRED_BASE_SNIPPETS)}") print(f"- nav contract checked: {len(OBSERVABILITY_NAV_ITEMS)} pages") return 0 if __name__ == "__main__": sys.exit(main())