mirror of
https://github.com/marcoallegretti/WEFT_OS.git
synced 2026-11-22 08:13:59 +00:00
175 lines
6.7 KiB
Python
175 lines
6.7 KiB
Python
|
|
"""Check contributor documents: local links and anchors, toolkit metadata, catalog and issue forms."""
|
||
|
|
|
||
|
|
import re
|
||
|
|
import sys
|
||
|
|
from pathlib import Path
|
||
|
|
from urllib.parse import unquote, urlsplit
|
||
|
|
|
||
|
|
try:
|
||
|
|
import yaml
|
||
|
|
from markdown_it import MarkdownIt
|
||
|
|
except ImportError as error:
|
||
|
|
sys.exit(f"{error}; install .agents/scripts/requirements.txt to run the toolkit checks")
|
||
|
|
|
||
|
|
|
||
|
|
ROOT = Path(__file__).resolve().parents[2]
|
||
|
|
MARKDOWN = MarkdownIt("commonmark")
|
||
|
|
FRONTMATTER = re.compile(r"\A---\n(.*?)\n---(?:\n|\Z)", re.DOTALL)
|
||
|
|
CATALOGUED = ("commands", "agents", "skills")
|
||
|
|
TOP_LEVEL = ("AGENTS.md", "CONTRIBUTING.md", "README.md", "BLUEPRINT.md",
|
||
|
|
".github/pull_request_template.md")
|
||
|
|
SLUG_DROP = re.compile(r"[^\w\- ]", re.UNICODE)
|
||
|
|
|
||
|
|
|
||
|
|
def body(source):
|
||
|
|
match = FRONTMATTER.match(source)
|
||
|
|
return source[match.end():] if match else source
|
||
|
|
|
||
|
|
|
||
|
|
def tokens(source):
|
||
|
|
for block in MARKDOWN.parse(body(source)):
|
||
|
|
yield block
|
||
|
|
yield from block.children or []
|
||
|
|
|
||
|
|
|
||
|
|
def local_links(path, source, *, images=True):
|
||
|
|
"""Yield (target, resolved path, fragment) for each relative link or image."""
|
||
|
|
for token in tokens(source):
|
||
|
|
if token.type == "link_open":
|
||
|
|
target = token.attrGet("href")
|
||
|
|
elif images and token.type == "image":
|
||
|
|
target = token.attrGet("src")
|
||
|
|
else:
|
||
|
|
continue
|
||
|
|
if not target:
|
||
|
|
continue
|
||
|
|
url = urlsplit(target)
|
||
|
|
if url.scheme or url.netloc:
|
||
|
|
continue
|
||
|
|
resolved = (path.parent / unquote(url.path)).resolve() if url.path else path.resolve()
|
||
|
|
yield target, resolved, unquote(url.fragment)
|
||
|
|
|
||
|
|
|
||
|
|
def anchors(source):
|
||
|
|
"""Return GitHub-style heading anchors, including numbered duplicates."""
|
||
|
|
result, seen = set(), {}
|
||
|
|
blocks = MARKDOWN.parse(body(source))
|
||
|
|
for index, block in enumerate(blocks):
|
||
|
|
if block.type != "heading_open":
|
||
|
|
continue
|
||
|
|
inline = blocks[index + 1]
|
||
|
|
text = "".join(child.content for child in inline.children or []
|
||
|
|
if child.type in ("text", "code_inline"))
|
||
|
|
slug = SLUG_DROP.sub("", text.strip().lower()).replace(" ", "-")
|
||
|
|
count = seen.get(slug, 0)
|
||
|
|
seen[slug] = count + 1
|
||
|
|
result.add(slug if count == 0 else f"{slug}-{count}")
|
||
|
|
return result
|
||
|
|
|
||
|
|
|
||
|
|
def metadata_fields(source):
|
||
|
|
"""Return name/description from a YAML mapping with unique string fields, else None."""
|
||
|
|
try:
|
||
|
|
node = yaml.compose(source, Loader=yaml.SafeLoader)
|
||
|
|
except yaml.YAMLError:
|
||
|
|
return None
|
||
|
|
if not isinstance(node, yaml.MappingNode):
|
||
|
|
return None
|
||
|
|
fields = {}
|
||
|
|
for key, value in node.value:
|
||
|
|
if (not isinstance(key, yaml.ScalarNode) or key.tag != "tag:yaml.org,2002:str"
|
||
|
|
or key.value in fields):
|
||
|
|
return None
|
||
|
|
fields[key.value] = value
|
||
|
|
result = {}
|
||
|
|
for name in ("name", "description"):
|
||
|
|
value = fields.get(name)
|
||
|
|
if not isinstance(value, yaml.ScalarNode) or value.tag != "tag:yaml.org,2002:str":
|
||
|
|
return None
|
||
|
|
result[name] = value.value
|
||
|
|
return result
|
||
|
|
|
||
|
|
|
||
|
|
def check_issue_forms(root):
|
||
|
|
errors = []
|
||
|
|
for path in sorted((root / ".github/ISSUE_TEMPLATE").glob("*.yml")):
|
||
|
|
label = path.relative_to(root)
|
||
|
|
try:
|
||
|
|
form = yaml.safe_load(path.read_text(encoding="utf-8"))
|
||
|
|
except yaml.YAMLError as error:
|
||
|
|
errors.append(f"{label}: invalid YAML: {error}")
|
||
|
|
continue
|
||
|
|
if path.name == "config.yml":
|
||
|
|
if not isinstance(form, dict) or "blank_issues_enabled" not in form:
|
||
|
|
errors.append(f"{label}: missing blank_issues_enabled")
|
||
|
|
continue
|
||
|
|
if (not isinstance(form, dict) or not isinstance(form.get("name"), str)
|
||
|
|
or not isinstance(form.get("description"), str)
|
||
|
|
or not isinstance(form.get("body"), list) or not form["body"]):
|
||
|
|
errors.append(f"{label}: issue form needs name, description and a nonempty body")
|
||
|
|
continue
|
||
|
|
ids = [item.get("id") for item in form["body"]
|
||
|
|
if isinstance(item, dict) and item.get("type") != "markdown"]
|
||
|
|
if None in ids or len(ids) != len(set(ids)):
|
||
|
|
errors.append(f"{label}: every input needs a unique id")
|
||
|
|
return errors
|
||
|
|
|
||
|
|
|
||
|
|
def check(root):
|
||
|
|
root = root.resolve()
|
||
|
|
toolkit = root / ".agents"
|
||
|
|
catalog_path = toolkit / "README.md"
|
||
|
|
if not catalog_path.is_file():
|
||
|
|
return ["missing .agents/README.md"]
|
||
|
|
catalog = catalog_path.read_text(encoding="utf-8")
|
||
|
|
catalog_targets = {resolved for _, resolved, _ in local_links(catalog_path, catalog,
|
||
|
|
images=False)}
|
||
|
|
errors = []
|
||
|
|
documents = sorted(toolkit.rglob("*.md")) + [root / name for name in TOP_LEVEL]
|
||
|
|
anchor_cache = {}
|
||
|
|
for path in documents:
|
||
|
|
label = path.relative_to(root)
|
||
|
|
if not path.is_file():
|
||
|
|
errors.append(f"missing {label}")
|
||
|
|
continue
|
||
|
|
source = path.read_text(encoding="utf-8")
|
||
|
|
for target, resolved, fragment in local_links(path, source):
|
||
|
|
if not resolved.is_relative_to(root) or not resolved.exists():
|
||
|
|
errors.append(f"{label}: broken local link {target}")
|
||
|
|
continue
|
||
|
|
if fragment and resolved.suffix == ".md":
|
||
|
|
if resolved not in anchor_cache:
|
||
|
|
anchor_cache[resolved] = anchors(resolved.read_text(encoding="utf-8"))
|
||
|
|
if fragment not in anchor_cache[resolved]:
|
||
|
|
errors.append(f"{label}: missing anchor {target}")
|
||
|
|
relative = path.relative_to(toolkit) if path.is_relative_to(toolkit) else None
|
||
|
|
if relative and relative.parts[0] in CATALOGUED:
|
||
|
|
match = FRONTMATTER.match(source)
|
||
|
|
if not match:
|
||
|
|
errors.append(f"{label}: missing front matter")
|
||
|
|
continue
|
||
|
|
fields = metadata_fields(match[1])
|
||
|
|
expected = path.parent.name if path.name == "SKILL.md" else path.stem
|
||
|
|
if not fields or fields["name"] != expected or not fields["description"].strip():
|
||
|
|
errors.append(f"{label}: name must match path and description must be nonempty; "
|
||
|
|
"use a YAML mapping with unique string fields")
|
||
|
|
if path.resolve() not in catalog_targets:
|
||
|
|
errors.append(f"{label}: absent from toolkit catalog")
|
||
|
|
for kind in CATALOGUED:
|
||
|
|
if not list((toolkit / kind).rglob("*.md")):
|
||
|
|
errors.append(f"no documents in .agents/{kind}")
|
||
|
|
return errors + check_issue_forms(root)
|
||
|
|
|
||
|
|
|
||
|
|
def main():
|
||
|
|
errors = check(ROOT)
|
||
|
|
if errors:
|
||
|
|
print("\n".join(errors), file=sys.stderr)
|
||
|
|
return 1
|
||
|
|
print("Contributor toolkit links, anchors, metadata, catalog and issue forms passed.")
|
||
|
|
return 0
|
||
|
|
|
||
|
|
|
||
|
|
if __name__ == "__main__":
|
||
|
|
raise SystemExit(main())
|