#!/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()