WEFT_OS/.agents/scripts/check_toolkit.py
Marco Allegretti dcc09f319d
docs: add engineering contract, contributor toolkit and templates
Add AGENTS.md as the single engineering contract: sources of truth,
evidence and proof requirements, ownership, working modes, the reviewed
change loop, maintenance isolation, decision authority, dependency and
fork rules, the 0.0.x to 0.1.0 release progression, and branch and
publication rules.

Add .agents/ with scope, implement, verify, maintenance and release
procedures; reviewer, architecture debt scout, simplicity and refactoring
roles; skills for the compositor, Servo rendering, runtime capabilities,
appd sessions, packages and data, Linux deployment, integration
verification and documentation; and verify.py, which runs the existing
check profiles with --locked from any directory, stops on the first
failure and supports --dry-run.

check_toolkit.py validates local links and heading anchors, metadata,
catalog coverage and issue forms. A new contributor-toolkit CI job runs
both. The structure follows the Resina Design System toolkit at
1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT.

Validation, against the committed lockfiles:
- verify.py toolkit: checker passes, 28 runner/checker tests pass
- verify.py portable, demos, packages: pass
- verify.py linux, runtime, servo-embed: fail on existing defects
  (clippy collapsible_if in the winit backend, three clippy lints in
  weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo
  revision's servo-layout); the runner reports the failing status

Add CONTRIBUTING.md, issue forms for defects and changes, maintenance
problems and decisions of direction, and a pull request template asking
for ownership, proof and the validation actually performed. README.md
links the contribution guide.
2026-10-09 08:34:48 +00:00

174 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())