#!/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", ] CSS_PATH = Path("static/css/observability-system.css") SHELL_PATH = Path("templates/components/_ewoooc_shell.html") BASE_PATH = Path("templates/ewoooc_base.html") @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 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")) 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)}") return 0 if __name__ == "__main__": sys.exit(main())