|
| 1 | +#!/usr/bin/env python3 |
| 2 | +# SPDX-FileCopyrightText: 2026 Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org> |
| 3 | +# SPDX-License-Identifier: GPL-3.0-or-later |
| 4 | +"""Enforce Construct's SKILL.md `description` cap (<= 1000 rendered chars). |
| 5 | +
|
| 6 | +The skill loader's absolute limit is 1024; this repo caps the *rendered* |
| 7 | +description at 1000 (a 24-char margin for encoding/trailing-newline edge |
| 8 | +cases). YAML folded scalars (`description: >`) join their wrapped lines with |
| 9 | +spaces, so the raw line count is not what the loader sees — this script |
| 10 | +reproduces the folding so the count matches, exactly as documented in |
| 11 | +CONTRIBUTING.md. Both the block form (`description: >`, used by root skills) |
| 12 | +and the single-line plain/quoted form (used by Grok skills) are handled. |
| 13 | +
|
| 14 | +Usage: |
| 15 | + check-description-length.py FILE [FILE ...] |
| 16 | +
|
| 17 | +Prints every offender and exits 1 if any description exceeds the cap; |
| 18 | +exits 0 otherwise. Files without frontmatter or a `description` key are |
| 19 | +skipped silently. |
| 20 | +""" |
| 21 | +import sys |
| 22 | + |
| 23 | +CAP = 1000 |
| 24 | + |
| 25 | + |
| 26 | +def rendered_length(path): |
| 27 | + """Return the rendered description length, or None if there is none.""" |
| 28 | + lines = open(path, encoding="utf-8").read().splitlines() |
| 29 | + if not lines or lines[0].strip() != "---": |
| 30 | + return None |
| 31 | + try: |
| 32 | + end = lines.index("---", 1) |
| 33 | + except ValueError: |
| 34 | + return None |
| 35 | + fm = lines[1:end] |
| 36 | + |
| 37 | + di = next((k for k, l in enumerate(fm) if l.startswith("description:")), None) |
| 38 | + if di is None: |
| 39 | + return None |
| 40 | + head = fm[di][len("description:"):].strip() |
| 41 | + |
| 42 | + # Block scalar: `>` (folded) / `|` (literal), optional chomping (`-`/`+`). |
| 43 | + if head[:1] in ("|", ">"): |
| 44 | + clip = not head.rstrip().endswith("-") # `-` strips the trailing newline |
| 45 | + body = [] |
| 46 | + for k in range(di + 1, len(fm)): |
| 47 | + l = fm[k] |
| 48 | + if l.strip() == "": |
| 49 | + body.append("") |
| 50 | + elif l.startswith((" ", "\t")): |
| 51 | + body.append(l.strip()) |
| 52 | + else: |
| 53 | + break # dedented line ends the block (next key) |
| 54 | + while body and body[-1] == "": |
| 55 | + body.pop() |
| 56 | + out, buf = [], [] |
| 57 | + for b in body: |
| 58 | + if b == "": |
| 59 | + out.append(" ".join(buf)) |
| 60 | + buf = [] |
| 61 | + else: |
| 62 | + buf.append(b) |
| 63 | + if buf: |
| 64 | + out.append(" ".join(buf)) |
| 65 | + return len("\n".join(out)) + (1 if clip else 0) |
| 66 | + |
| 67 | + # Single-line plain or quoted scalar (Grok skills). |
| 68 | + if head: |
| 69 | + if len(head) >= 2 and head[0] == head[-1] and head[0] in ("'", '"'): |
| 70 | + head = head[1:-1] |
| 71 | + return len(head) |
| 72 | + return None |
| 73 | + |
| 74 | + |
| 75 | +def main(argv): |
| 76 | + offenders = [] |
| 77 | + for path in argv: |
| 78 | + try: |
| 79 | + n = rendered_length(path) |
| 80 | + except OSError as e: |
| 81 | + print(f" ! cannot read {path}: {e}", file=sys.stderr) |
| 82 | + offenders.append((path, -1)) |
| 83 | + continue |
| 84 | + if n is not None and n > CAP: |
| 85 | + offenders.append((path, n)) |
| 86 | + if offenders: |
| 87 | + print(f"SKILL.md description cap (<= {CAP} rendered chars) exceeded:", |
| 88 | + file=sys.stderr) |
| 89 | + for path, n in offenders: |
| 90 | + where = "unreadable" if n < 0 else f"{n} chars ({n - CAP} over)" |
| 91 | + print(f" {path}: {where}", file=sys.stderr) |
| 92 | + print("Trim the `description` and re-stage. See CONTRIBUTING.md " |
| 93 | + "(Editing rules) for the folded-scalar rationale.", file=sys.stderr) |
| 94 | + return 1 |
| 95 | + return 0 |
| 96 | + |
| 97 | + |
| 98 | +if __name__ == "__main__": |
| 99 | + sys.exit(main(sys.argv[1:])) |
0 commit comments