create-yss-spec 1.1.2 → 1.1.4

package/template/.codex/skills/data-analytics/src/analytics-app/scripts/check_analytics_app_runtime_links.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Fail when analytics app runtime paths drift from their expected layout."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+PLUGIN_ROOT = Path(__file__).resolve().parents[3]
+ANALYTICS_APP_SRC = PLUGIN_ROOT / "src" / "analytics-app"
+
+EXPECTED_LOCAL_PATHS = {
+    ANALYTICS_APP_SRC / "charting": [
+        "ChartFrame.tsx",
+        "ChartLegend.tsx",
+        "ChartRenderer.tsx",
+        "ChartTooltip.tsx",
+        "chart-capabilities.ts",
+        "chart-compatibility.ts",
+        "chart-contract.ts",
+        "chart-theme.ts",
+        "chart-tokens.css",
+        "chart-transforms.ts",
+    ],
+    ANALYTICS_APP_SRC / "tables": [
+        "DataTable.d.ts",
+        "DataTable.jsx",
+        "data-table.css",
+    ],
+    ANALYTICS_APP_SRC / "layout": [
+        "AnalyticsLayoutCanvas.tsx",
+        "RichMarkdown.tsx",
+        "analyticsLayoutCore.ts",
+    ],
+    ANALYTICS_APP_SRC / "fonts": [
+        "SystemSansVariableVF.woff2",
+    ],
+}
+
+EXPECTED_LOCAL_FILES = [
+    ANALYTICS_APP_SRC / "analytics-layout.test.mjs",
+    ANALYTICS_APP_SRC / "main.tsx",
+    ANALYTICS_APP_SRC / "tokens.css",
+]
+
+
+def layout_problems() -> list[str]:
+    problems: list[str] = []
+    for path, required_files in EXPECTED_LOCAL_PATHS.items():
+        if path.is_symlink():
+            problems.append(f"{path.relative_to(PLUGIN_ROOT)} must be a real directory")
+            continue
+        if not path.is_dir():
+            problems.append(f"{path.relative_to(PLUGIN_ROOT)} is not a directory")
+            continue
+        for filename in required_files:
+            if not (path / filename).is_file():
+                problems.append(f"{(path / filename).relative_to(PLUGIN_ROOT)} is missing")
+    for path in EXPECTED_LOCAL_FILES:
+        if path.is_symlink():
+            problems.append(f"{path.relative_to(PLUGIN_ROOT)} must be a real file")
+        elif not path.is_file():
+            problems.append(f"{path.relative_to(PLUGIN_ROOT)} is missing")
+    return problems
+
+
+def main() -> int:
+    problems = layout_problems()
+    if problems:
+        names = "\n".join(f" - {problem}" for problem in problems)
+        raise SystemExit(f"Analytics app runtime layout is out of sync:\n{names}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/.codex/skills/data-analytics/src/analytics-app/scripts/design_contract.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Shared DESIGN.md contract checks for generated analytics app packages."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from package_utils import ContractError
+
+CANONICAL_DESIGN_SECTIONS = [
+    "Overview",
+    "Colors",
+    "Typography",
+    "Layout",
+    "Elevation & Depth",
+    "Shapes",
+    "Components",
+    "Do's and Don'ts",
+]
+REQUIRED_FRONTMATTER_KEYS = (
+    "name",
+    "description",
+    "colors",
+    "typography",
+    "spacing",
+    "rounded",
+    "surfaces",
+    "components",
+    "implementation",
+)
+REQUIRED_DESIGN_TOKENS = (
+    "bg/primary",
+    "bg/secondary",
+    "bg/tertiary",
+    "border/light",
+    "border/default",
+    "text/primary",
+    "text/secondary",
+    "text/tertiary",
+    "icon/accent",
+    "space-12",
+    "space-24",
+    "corner-radius/cr-24",
+    "elevation/01",
+    "blue/500",
+    "green/700",
+    "purple/500",
+)
+REQUIRED_TYPE_TOKENS = (
+    "System Sans Variable",
+    "text/xs/normal",
+    "text/xs/semibold",
+    "text/sm/normal",
+    "text/sm/medium",
+    "heading/md/medium",
+    "heading/2xl",
+)
+REQUIRED_SURFACE_MEASUREMENTS = (
+    "1140px",
+    "800px",
+    "48px",
+    "24px",
+)
+REQUIRED_COMPONENT_NAMES = (
+    "top-bar",
+    "metric-card",
+    "report-block",
+    "chart-block",
+    "table-list",
+    "popover-menu",
+)
+
+
+def split_design_file(markdown: str, path: Path) -> tuple[str, str]:
+    if not markdown.startswith("---\n"):
+        raise ContractError(f"{path.name} must start with YAML front matter")
+    try:
+        _opening, frontmatter, body = markdown.split("---\n", 2)
+    except ValueError as exc:
+        raise ContractError(f"{path.name} must contain closed YAML front matter") from exc
+    if not frontmatter.strip():
+        raise ContractError(f"{path.name} front matter must not be empty")
+    if not body.strip():
+        raise ContractError(f"{path.name} body must not be empty")
+    return frontmatter, body
+
+
+def require_frontmatter_key(frontmatter: str, key: str, path: Path) -> None:
+    if not re.search(rf"^{re.escape(key)}\s*:", frontmatter, flags=re.MULTILINE):
+        raise ContractError(f"{path.name} front matter must define {key}")
+
+
+def require_text_anchor(markdown: str, anchor: str, path: Path, group: str) -> None:
+    if anchor not in markdown:
+        raise ContractError(f"{path.name} must include {group} anchor: {anchor}")
+
+
+def section_positions(body: str) -> dict[str, int]:
+    positions: dict[str, int] = {}
+    for match in re.finditer(r"^##\s+(.+?)\s*$", body, flags=re.MULTILINE):
+        title = match.group(1).strip()
+        if title in CANONICAL_DESIGN_SECTIONS:
+            positions[title] = match.start()
+    return positions
+
+
+def validate_design_contract(root: Path) -> None:
+    path = root / "DESIGN.md"
+    if not path.exists():
+        raise ContractError("analytics app package must include DESIGN.md")
+
+    markdown = path.read_text(encoding="utf-8")
+    frontmatter, body = split_design_file(markdown, path)
+
+    for key in REQUIRED_FRONTMATTER_KEYS:
+        require_frontmatter_key(frontmatter, key, path)
+
+    for token in REQUIRED_DESIGN_TOKENS:
+        require_text_anchor(markdown, token, path, "design token")
+    for token in REQUIRED_TYPE_TOKENS:
+        require_text_anchor(markdown, token, path, "typography token")
+    for measurement in REQUIRED_SURFACE_MEASUREMENTS:
+        require_text_anchor(markdown, measurement, path, "surface measurement")
+    for component in REQUIRED_COMPONENT_NAMES:
+        require_text_anchor(frontmatter, component, path, "component recipe")
+
+    positions = section_positions(body)
+    missing_sections = [
+        section for section in CANONICAL_DESIGN_SECTIONS if section not in positions
+    ]
+    if missing_sections:
+        raise ContractError(f"{path.name} is missing sections: {missing_sections}")
+    ordered_positions = [positions[section] for section in CANONICAL_DESIGN_SECTIONS]
+    if ordered_positions != sorted(ordered_positions):
+        raise ContractError(f"{path.name} sections must follow the canonical DESIGN.md order")
+
+    lower_body = body.lower()
+    if "decorative orb" in lower_body or "bokeh" in lower_body:
+        raise ContractError(f"{path.name} must not encourage decorative effects")
+    if "customiz" not in lower_body and "customis" not in lower_body:
+        raise ContractError(f"{path.name} must explain how users can customize outputs")

package/template/.codex/skills/data-analytics/src/analytics-app/scripts/package_utils.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Shared helpers for generated data analytics app packages."""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+
+class ContractError(Exception):
+    """Raised when an analytics app package does not satisfy its contract."""
+
+
+ALLOWED_SOURCE_EXTENSIONS = {".csv", ".json", ".md", ".sql", ".tsv", ".txt"}
+SENSITIVE_FILE_NAMES = {".env", ".env.local", ".env.production", ".env.staging"}
+SENSITIVE_FILE_GLOBS = {"*.pem", "*.key", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*"}
+SENSITIVE_SCAN_SKIP_DIRS = {
+    ".git",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".vite",
+    "build",
+    "dist",
+    "node_modules",
+    "__pycache__",
+}
+TEMPLATE_IGNORE_PATTERNS = (
+    ".dashboard-data",
+    ".report-data",
+    "dist",
+    "node_modules",
+)
+
+
+def slugify(value: str, fallback: str) -> str:
+    chars: list[str] = []
+    previous_dash = False
+    for char in value.lower():
+        if char.isalnum():
+            chars.append(char)
+            previous_dash = False
+        elif not previous_dash:
+            chars.append("-")
+            previous_dash = True
+    slug = "".join(chars).strip("-")
+    return slug or fallback
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise ContractError(f"Missing required file: {path}")
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ContractError(f"Invalid JSON in {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ContractError(f"{path} must contain a JSON object")
+    return value
+
+
+def write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.write_text(f"{json.dumps(payload, indent=2)}\n", encoding="utf-8")
+
+
+def copy_template(template: Path, output: Path, *, force: bool = False) -> None:
+    output = output.resolve()
+    if output.exists() and any(output.iterdir()) and not force:
+        raise RuntimeError(f"{output} already exists and is not empty; pass --force to replace it")
+    if output.exists() and force:
+        shutil.rmtree(output)
+    shutil.copytree(
+        template,
+        output,
+        ignore=shutil.ignore_patterns(*TEMPLATE_IGNORE_PATTERNS),
+    )
+
+
+def require_string(obj: dict[str, Any], field: str, path: str) -> str:
+    value = obj.get(field)
+    if not isinstance(value, str) or not value.strip():
+        raise ContractError(f"{path}.{field} must be a non-empty string")
+    return value
+
+
+def optional_list(obj: dict[str, Any], field: str, path: str) -> list[Any]:
+    value = obj.get(field, [])
+    if not isinstance(value, list):
+        raise ContractError(f"{path}.{field} must be a list when present")
+    return value
+
+
+def require_list(obj: dict[str, Any], field: str, path: str) -> list[Any]:
+    value = obj.get(field)
+    if not isinstance(value, list):
+        raise ContractError(f"{path}.{field} must be a list")
+    return value
+
+
+def require_unique_ids(items: list[Any], field_path: str) -> None:
+    seen: set[str] = set()
+    for idx, item in enumerate(items):
+        if not isinstance(item, dict):
+            continue
+        item_id = item.get("id")
+        if not isinstance(item_id, str) or not item_id.strip():
+            continue
+        if item_id in seen:
+            raise ContractError(f"{field_path}[{idx}].id must be unique")
+        seen.add(item_id)
+
+
+def validate_relative_source_path(
+    root: Path, source_path: str, path: str, package_label: str = "analytics app package"
+) -> None:
+    candidate = (root / source_path).resolve()
+    try:
+        candidate.relative_to(root.resolve())
+    except ValueError as exc:
+        raise ContractError(f"{path}.path must stay inside the {package_label}") from exc
+    if candidate.is_dir():
+        raise ContractError(f"{path}.path must point to a file, not a directory")
+    if candidate.suffix.lower() not in ALLOWED_SOURCE_EXTENSIONS:
+        raise ContractError(f"{path}.path must use one of {sorted(ALLOWED_SOURCE_EXTENSIONS)}")
+
+
+def validate_no_sensitive_files(root: Path, package_label: str = "analytics app") -> None:
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(root)
+        if any(part in SENSITIVE_SCAN_SKIP_DIRS for part in relative.parts[:-1]):
+            continue
+        name = path.name
+        if name in SENSITIVE_FILE_NAMES or any(
+            fnmatch.fnmatch(name, pattern) for pattern in SENSITIVE_FILE_GLOBS
+        ):
+            raise ContractError(
+                f"{package_label} package must not include sensitive files: {relative}"
+            )