1"""Shared SKILL.md frontmatter parsing for researcher validation scripts."""
2 
3from __future__ import annotations
4 
5import json
6import re
7from typing import Any
8 
9try:
10    import yaml
11except ImportError:  # pragma: no cover - PyYAML is stdlib-adjacent in CI via setup
12    yaml = None  # type: ignore[assignment]
13 
14MIN_DESCRIPTION_LENGTH = 20
15YAML_INDICATOR_ONLY = re.compile(r"^[>|]?-?$")
16 
17 
18def strip_bom(text: str) -> str:
19    return text[1:] if text.startswith("\ufeff") else text
20 
21 
22def split_frontmatter(text: str) -> tuple[str | None, str]:
23    """Return (frontmatter_inner, body). Inner block excludes --- delimiters."""
24    text = strip_bom(text)
25    if not (text.startswith("---\n") or text.startswith("---\r\n")):
26        return None, text
27 
28    delimiter_len = 5 if text.startswith("---\r\n") else 4
29    match = re.search(r"(?m)^---\s*$", text[delimiter_len:])
30    if match is None:
31        return None, text
32 
33    end = delimiter_len + match.start()
34    inner = text[delimiter_len:end].rstrip("\r")
35    body = text[delimiter_len + match.end() :]
36    if body.startswith("\r\n"):
37        body = body[2:]
38    elif body.startswith("\n"):
39        body = body[1:]
40    return inner, body
41 
42 
43def parse_frontmatter(text: str) -> tuple[dict[str, Any], list[str]]:
44    """Parse SKILL.md frontmatter with strict YAML when available."""
45    issues: list[str] = []
46    inner, _body = split_frontmatter(text)
47    if inner is None:
48        return {}, ["missing or invalid frontmatter delimiters"]
49 
50    if yaml is None:
51        return _parse_frontmatter_fallback(inner, issues)
52 
53    try:
54        data = yaml.safe_load(inner)
55    except yaml.YAMLError as exc:
56        issues.append(f"invalid YAML frontmatter: {exc}")
57        return {}, issues
58 
59    if not isinstance(data, dict):
60        issues.append("frontmatter must be a YAML mapping")
61        return {}, issues
62 
63    normalized: dict[str, Any] = {}
64    for key, value in data.items():
65        if value is None:
66            continue
67        normalized[str(key)] = value
68 
69    _validate_required_fields(normalized, issues)
70    return normalized, issues
71 
72 
73def _parse_frontmatter_fallback(inner: str, issues: list[str]) -> tuple[dict[str, Any], list[str]]:
74    """Line-based fallback when PyYAML is unavailable."""
75    data: dict[str, Any] = {}
76    in_description = False
77    description_lines: list[str] = []
78 
79    for raw in inner.splitlines():
80        line = raw.rstrip("\r")
81        if in_description:
82            if re.match(r"^[A-Za-z0-9_-]+:", line):
83                data["description"] = " ".join(description_lines).strip()
84                in_description = False
85            else:
86                trimmed = line.strip()
87                if trimmed and trimmed not in (">", ">-", "|", "|-"):
88                    description_lines.append(trimmed)
89                continue
90 
91        if not line.strip() or line.startswith(" "):
92            continue
93        if ":" not in line:
94            continue
95        key, value = line.split(":", 1)
96        key = key.strip()
97        value = value.strip().strip('"').strip("'")
98        if key == "description" and value in (">", ">-", "|", "|-", ""):
99            in_description = True
100            continue
101        data[key] = value
102 
103    if in_description:
104        data["description"] = " ".join(description_lines).strip()
105 
106    _validate_required_fields(data, issues)
107    return data, issues
108 
109 
110def _validate_required_fields(data: dict[str, Any], issues: list[str]) -> None:
111    raw_name = data.get("name", "")
112    raw_description = data.get("description", "")
113 
114    if raw_name and not isinstance(raw_name, str):
115        issues.append(f"name must be a string, got {type(raw_name).__name__}")
116        name = ""
117    else:
118        name = str(raw_name).strip()
119 
120    if raw_description and not isinstance(raw_description, str):
121        issues.append(f"description must be a string, got {type(raw_description).__name__}")
122        description = ""
123    else:
124        description = str(raw_description).strip()
125 
126    if not name:
127        issues.append("missing name")
128    if not description:
129        issues.append("missing description")
130    elif len(description) < MIN_DESCRIPTION_LENGTH:
131        issues.append(f"description too short ({len(description)} chars)")
132    elif YAML_INDICATOR_ONLY.match(description):
133        issues.append("description parsed as YAML indicator only")
134 
135 
136def format_frontmatter(name: str, description: str, **extra: str) -> str:
137    """Render a standards-compliant frontmatter block."""
138    lines = [f"name: {name}", f"description: {json.dumps(description, ensure_ascii=False)}"]
139    for key, value in extra.items():
140        lines.append(f"{key}: {json.dumps(value, ensure_ascii=False)}")
141    return "---\n" + "\n".join(lines) + "\n---\n"
142