#!/usr/bin/env python3 """Check the skills repo: frontmatter, rule shape, sources, internal links. tools/check.py # lint every SKILL.md and rule; exit 1 on any error tools/check.py --links # also fetch every external link (HEAD, then GET), with a User-Agent Checks (each a hard error): - every */SKILL.md and steering/*.md has frontmatter with `name` (lowercase a-z0-9-, no '--', <= 64 chars; for a SKILL.md it equals 'solnix-' + its directory, or its directory) and `description` (<= 1024 chars); - every solnix/rules/-.md has title/area/impact/verified frontmatter, the sections **Antipattern**, **The Solnix way**, **The illumos way**, **The difference.**, **Check.**, **Sources**, and at least one source bullet with a link; - every rule a SKILL.md names (`foo.md` under ../rules/ or rules/) exists; - no banned marketing words; "Solnix" capitalised in prose; - solnix/rules/tasks.tsv and errors.tsv (the tables translate_command and explain_error read): exact header, every row cited, rules named exist, patterns compile, ids unique. Stdlib only. """ import os, re, sys, urllib.request, urllib.error, concurrent.futures as cf REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) UA = "solnix-skills-check/1 (+https://codeberg.org/solnix/skills)" NAME = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$") BANNED = re.compile(r"\b(robust|seamless(ly)?|powerful|leverag\w*|simply|effortless\w*)\b", re.I) RULE_SECTIONS = ["**Antipattern**", "**The Solnix way**", "**The illumos way**", "**The difference.**", "**Check.**", "**Sources**"] errors = [] def err(path, msg): errors.append(f"{os.path.relpath(path, REPO)}: {msg}") def frontmatter(text): if not text.startswith("---\n"): return None, text head, sep, body = text[4:].partition("\n---\n") if not sep: return None, text fm, key = {}, None for line in head.splitlines(): m = re.match(r"^([a-zA-Z][\w-]*):\s*(.*)$", line) if m: key, val = m.group(1), m.group(2).strip() fm[key] = "" if val in (">", "|", ">-", "|-") else val.strip("\"'") elif key and line.startswith(" "): fm[key] = (fm[key] + " " + line.strip()).strip() return fm, body def prose(text): # drop frontmatter, fenced code, inline code, link targets, bold labels: what's left is prose _, t = frontmatter(text) t = re.sub(r"(?s)```.*?```", "", t) t = re.sub(r"`[^`]*`", "", t) t = re.sub(r"\]\([^)]*\)", "]", t) return re.sub(r"https?://\S+", "", t) def check_skill(path, text): fm, body = frontmatter(text) if fm is None: return err(path, "no frontmatter") name, desc = fm.get("name", ""), fm.get("description", "") if not NAME.match(name) or len(name) > 64: err(path, f"bad name {name!r}") if os.path.basename(path) == "SKILL.md": d = os.path.basename(os.path.dirname(path)) if name not in (d, f"solnix-{d}"): err(path, f"name {name!r} does not match directory {d!r}") if not desc or len(desc) > 1024: err(path, f"description missing or over 1024 chars ({len(desc)})") for ref in set(re.findall(r"`(?:\.\./rules/|solnix/rules/|rules/)?([a-z0-9]+-[a-z0-9-]+\.md)`", body)): if not any(os.path.exists(os.path.join(REPO, d, ref)) for d in ("solnix/rules", "steering", "workflows")) \ and not ref.startswith(("illumos-domain", "nix-conventions", "builder-queue", "product", "architectures", "design-")): err(path, f"names {ref}, which does not exist") def check_rule(path, text): fm, body = frontmatter(text) if fm is None: return err(path, "no frontmatter") for k in ("title", "area", "impact", "verified"): if not fm.get(k): err(path, f"frontmatter lacks {k}") if fm.get("impact") not in ("CRITICAL", "HIGH", "MEDIUM", "LOW"): err(path, f"impact {fm.get('impact')!r}") base = os.path.basename(path)[:-3] if not base.startswith(fm.get("area", "") + "-") and fm.get("area"): err(path, f"file name does not start with its area {fm.get('area')!r}") pos = -1 for s in RULE_SECTIONS: i = body.find(s) if i < 0: err(path, f"missing section {s}") elif i < pos: err(path, f"section {s} out of order") pos = max(pos, i) src = body.split("**Sources**", 1)[-1] if not re.search(r"^- .*\]\(https?://", src, re.M): err(path, "no linked source under **Sources**") def check_prose(path, text): p = prose(text) for m in BANNED.finditer(p): err(path, f"banned word {m.group(0)!r}") for line in p.splitlines(): line = re.sub(r'"[^"]*"', "", line) # quotations keep the source's spelling line = re.sub(r"\bsolnix (?=[0-9a-f]{7}\b)|\[[^\]]*\]|solnix note", "", line) # repo@sha cites, link text, the compare-page field if re.search(r"(?\]`\"']+", t)}) urls = [u for u in urls if "example" not in u and "<" not in u and "localhost" not in u] def get(u): for method in ("HEAD", "GET"): try: r = urllib.request.urlopen(urllib.request.Request(u.split("#")[0], method=method, headers={"User-Agent": UA}), timeout=20) return u, r.status except urllib.error.HTTPError as e: if method == "GET": return u, e.code except Exception as e: if method == "GET": return u, type(e).__name__ return u, "?" with cf.ThreadPoolExecutor(8) as ex: for u, st in ex.map(get, urls): if st != 200: errors.append(f"link {u}: {st}") print(f"checked {len(urls)} links") def main(): texts = [] for root, _, files in os.walk(REPO): if "/.git" in root or "/site" in root: continue for f in files: if f in TSV_COLS and os.path.relpath(root, REPO) == "solnix/rules": check_tsv(os.path.join(root, f)) continue if not f.endswith(".md") or f.startswith("_"): continue p = os.path.join(root, f) t = open(p, encoding="utf-8").read() texts.append(t) rel = os.path.relpath(p, REPO) if f == "SKILL.md" or (rel.startswith("steering/") and f != "README.md"): check_skill(p, t) if rel.startswith("solnix/rules/") and f != "SKILL.md": check_rule(p, t) if f not in ("README.md", "AGENTS.md", "LICENSE") and rel != "steering/voice.md": check_prose(p, t) if "--links" in sys.argv: links(texts) for e in errors: print(e) print(f"{len(errors)} errors") sys.exit(1 if errors else 0) if __name__ == "__main__": main()