skill-linter 0.1.0__py3-none-any.whl

skill_linter/__init__.py

@@ -0,0 +1 @@
+"""skill-linter: validate Agent Skills repos."""

skill_linter/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from skill_linter.cli import main
+
+sys.exit(main())

skill_linter/cli.py

@@ -0,0 +1,216 @@
+"""Command-line interface: skill-linter check | release | stamp | rules."""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import re
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from skill_linter import model, release, stamp
+from skill_linter.config import Config, ConfigError, find_root, load_config
+from skill_linter.engine import all_rules, effective_severity, run, validate_config
+from skill_linter.repo import Repo
+from skill_linter.report import format_json, format_text
+
+EXIT_OK, EXIT_ERRORS, EXIT_USAGE = 0, 1, 2
+CHECK_EXCLUDES = frozenset({"release"})
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skill-linter", description="Validate an Agent Skills repo."
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"skill-linter {version('skill-linter')}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser(
+        "check", help="run every enabled rule except the release checks"
+    )
+    check.add_argument("--only", help="comma-separated rule groups to run")
+    check.add_argument(
+        "--skill", help="limit skill rules to one skill and skip repo rules"
+    )
+    check.add_argument("--format", choices=("text", "json"), default="text")
+    check.add_argument(
+        "--root",
+        type=Path,
+        help="repo root (default: nearest pyproject.toml with the table)",
+    )
+    check.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="also show info issues and skipped rules",
+    )
+
+    release_cmd = sub.add_parser(
+        "release", help="run the plugin release checks on the shipped tree, then check"
+    )
+    release_cmd.add_argument("--format", choices=("text", "json"), default="text")
+    release_cmd.add_argument("--root", type=Path)
+    release_cmd.add_argument("-v", "--verbose", action="store_true")
+
+    stamp = sub.add_parser(
+        "stamp",
+        help="write counts and the version into version.json and the stamp files",
+    )
+    stamp.add_argument(
+        "--check",
+        action="store_true",
+        help="write nothing; exit 1 if anything is stale",
+    )
+    stamp.add_argument(
+        "--dry-run", action="store_true", help="print the diff; write nothing"
+    )
+    stamp.add_argument("--root", type=Path)
+
+    rules = sub.add_parser("rules", help="list every rule")
+    rules.add_argument("--format", choices=("text", "json"), default="text")
+    rules.add_argument("--root", type=Path)
+    return parser
+
+
+def _load(root: Path | None) -> Config:
+    cfg = load_config(root.resolve()) if root else load_config(find_root(Path.cwd()))
+    validate_config(cfg)
+    return cfg
+
+
+def _groups() -> set[str]:
+    return {r.group for r in model.REGISTRY.values()} | {"custom"}
+
+
+def cmd_check(args) -> int:
+    groups = None
+    if args.only:
+        groups = {g.strip() for g in args.only.split(",") if g.strip()}
+        unknown = groups - _groups()
+        if unknown:
+            print(
+                f"unknown rule group(s): {', '.join(sorted(unknown))}", file=sys.stderr
+            )
+            return EXIT_USAGE
+    cfg = _load(args.root)
+    report = run(
+        Repo(cfg),
+        groups=groups,
+        skill=args.skill,
+        exclude_groups=CHECK_EXCLUDES - (groups or set()),
+    )
+    print(
+        format_json(report, cfg.root)
+        if args.format == "json"
+        else format_text(report, args.verbose)
+    )
+    return EXIT_ERRORS if report.has_errors else EXIT_OK
+
+
+def cmd_release(args) -> int:
+    cfg = _load(args.root)
+    repo = Repo(cfg)
+    release.shipped_tree(
+        repo
+    )  # config error (exit 2) when neither plugin_root nor ship is set
+    report = run(repo)
+    print(
+        format_json(report, cfg.root)
+        if args.format == "json"
+        else format_text(report, args.verbose)
+    )
+    return EXIT_ERRORS if report.has_errors else EXIT_OK
+
+
+def cmd_stamp(args) -> int:
+    repo = Repo(_load(args.root))
+    changes, errors = stamp.plan(repo)
+    for message in errors:
+        print(f"error: {message}", file=sys.stderr)
+    if errors:
+        return EXIT_ERRORS
+    if args.dry_run:
+        for rel, (old, new) in changes.items():
+            sys.stdout.writelines(
+                difflib.unified_diff(
+                    old.splitlines(True), new.splitlines(True), f"a/{rel}", f"b/{rel}"
+                )
+            )
+        return EXIT_OK
+    if args.check:
+        for rel in changes:
+            print(f"stale: {rel}")
+        return EXIT_ERRORS if changes else EXIT_OK
+    stamp.write(repo, changes)
+    for rel in changes:
+        print(f"stamped: {rel}")
+    return EXIT_OK
+
+
+LAYERS = {1: "spec", 2: "convention", 3: "policy"}
+
+
+def _rule_order(r) -> tuple:
+    """Registration order of groups, then IDs in numeric order (H01 before H16)."""
+    groups = list(dict.fromkeys(x.group for x in model.REGISTRY.values()))
+    prefix, number = re.match(r"^(.*?)(\d*)$", r.id).groups()
+    rank = groups.index(r.group) if r.group in groups else len(groups)
+    return (rank, prefix, int(number) if number else 0, r.id)
+
+
+def cmd_rules(args) -> int:
+    try:
+        cfg = _load(args.root)
+    except ConfigError:
+        if args.root:
+            raise
+        cfg = None
+    rows = []
+    rules = all_rules(cfg) if cfg is not None else list(model.REGISTRY.values())
+    for r in sorted(rules, key=_rule_order):
+        row = {
+            "id": r.id,
+            "name": r.name,
+            "group": r.group,
+            "layer": r.layer,
+            "default": r.severity.value,
+            "overridable": r.overridable,
+            "summary": r.summary,
+        }
+        if cfg is not None:
+            row["effective"] = effective_severity(cfg, r).value
+        rows.append(row)
+    if args.format == "json":
+        print(json.dumps(rows, indent=2))
+    else:
+        name_width = max(len(row["name"]) for row in rows)
+        for row in rows:
+            sev = row.get("effective", row["default"])
+            print(
+                f"{row['id']:<8}  {row['name']:<{name_width}}  {row['group']:<12}  "
+                f"{LAYERS[row['layer']]:<10}  {sev:<7}  {row['summary']}"
+            )
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        commands = {
+            "check": cmd_check,
+            "release": cmd_release,
+            "stamp": cmd_stamp,
+            "rules": cmd_rules,
+        }
+        return commands[args.command](args)
+    except ConfigError as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skill_linter/commands.py

@@ -0,0 +1,117 @@
+"""Command files, their YAML definitions, and plugin locations, shared by the hidden and workflow rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from skill_linter.repo import Repo
+
+
+@dataclass
+class Definition:
+    file: Path
+    rel: str
+    data: dict[str, Any] | None
+    error: str | None
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default) if isinstance(self.data, dict) else default
+
+
+def load_yaml(text: str) -> tuple[Any, str | None]:
+    try:
+        return yaml.safe_load(text), None
+    except yaml.YAMLError as exc:
+        return None, str(exc).replace("\n", " ")
+
+
+def commands_dir(repo: Repo) -> Path | None:
+    return repo.cfg.path(repo.cfg.commands_dir) if repo.cfg.commands_dir else None
+
+
+def manifest_path(repo: Repo) -> Path | None:
+    if repo.cfg.manifest:
+        return repo.cfg.path(repo.cfg.manifest)
+    base = commands_dir(repo)
+    return base / "workflow-manifest.yaml" if base else None
+
+
+def definitions(repo: Repo) -> list[Definition]:
+    cached = getattr(repo, "_definitions", None)
+    if cached is not None:
+        return cached
+    base = commands_dir(repo)
+    found: list[Definition] = []
+    manifest = manifest_path(repo)
+    if base and base.is_dir():
+        for path in sorted(base.rglob("*.yaml")):
+            if manifest and path.resolve() == manifest.resolve():
+                continue
+            data, error = load_yaml(repo.read(path))
+            if error is None and not isinstance(data, dict):
+                error = "definition must be a YAML mapping"
+                data = None
+            found.append(Definition(path, repo.rel(path), data, error))
+    repo._definitions = found
+    return found
+
+
+def command_files(repo: Repo) -> list[Path]:
+    """Every .md under the commands folder, except files inside a references/ folder."""
+    base = commands_dir(repo)
+    if not base or not base.is_dir():
+        return []
+    return sorted(
+        p for p in base.rglob("*.md") if "references" not in p.relative_to(base).parts
+    )
+
+
+def frontmatter_block(text: str) -> str | None:
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            return "\n".join(lines[1:index])
+    return None
+
+
+def command_frontmatter(text: str) -> tuple[dict[str, Any] | None, str | None]:
+    """(data, error). data is None with no error when the file has no frontmatter."""
+    block = frontmatter_block(text)
+    if block is None:
+        if text.splitlines()[:1] == ["---"]:
+            return None, "frontmatter opened with --- but never closed"
+        return None, None
+    data, error = load_yaml(block)
+    if error:
+        return None, error
+    if data is None:
+        return {}, None
+    if not isinstance(data, dict):
+        return None, "frontmatter must be a YAML mapping"
+    return data, None
+
+
+def plugin_dir(repo: Repo) -> Path:
+    return repo.cfg.path(repo.cfg.plugin_root) if repo.cfg.plugin_root else repo.root
+
+
+def plugin_json_path(repo: Repo) -> Path:
+    return plugin_dir(repo) / ".claude-plugin" / "plugin.json"
+
+
+def marketplace_path(repo: Repo) -> Path:
+    return repo.root / ".claude-plugin" / "marketplace.json"
+
+
+def skill_and_command_files(repo: Repo, pattern: str = "*.md") -> list[Path]:
+    paths: list[Path] = []
+    for base in (repo.skills_dir, commands_dir(repo)):
+        if base and base.is_dir():
+            paths.extend(p for p in sorted(base.rglob(pattern)) if p.is_file())
+    return paths

skill_linter/config.py

@@ -0,0 +1,356 @@
+"""Read and validate the [tool.skill-linter] table in a repo's pyproject.toml."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+TABLE = "skill-linter"
+SEVERITY_VALUES = {"error", "warning", "off"}
+VALUE_LISTS = {
+    "role",
+    "scope",
+    "output-format",
+    "phases",
+    "requires",
+    "input-types",
+    "output-types",
+}
+POLICY_KEYS = {
+    "required_sections",
+    "section_order",
+    "workflow_steps",
+    "body_lines",
+    "license",
+    "reciprocal_related_skills",
+    "resolve_relative_paths",
+}
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass
+class Config:
+    root: Path
+    skills_dir: str = "skills"
+    shared_dirs: list[str] = field(default_factory=list)
+    commands_dir: str | None = None
+    manifest: str | None = None
+    workflow_glob: str = "**/*.md"
+    version_file: str = "version.json"
+    markdown_paths: list[str] = field(default_factory=list)
+    docs_url: str | None = None
+    skill_path: str = "domain"
+    domains: list[dict[str, str]] | None = None
+    domain_lists: list[str] = field(default_factory=list)
+    index_files: list[str] = field(default_factory=list)
+    sidebar_file: str | None = None
+    plugin_root: str | None = None
+    ship: list[str] | None = None
+    credit: dict[str, Any] | None = None
+    values: dict[str, list[str]] = field(default_factory=dict)
+    policy: dict[str, Any] = field(default_factory=dict)
+    severity: dict[str, str] = field(default_factory=dict)
+    custom_rules: list[dict[str, Any]] = field(default_factory=list)
+    stamp_files: list[dict[str, Any]] = field(default_factory=list)
+    credentials_allow: list[str] = field(default_factory=list)
+    vendored: list[dict[str, str]] = field(default_factory=list)
+    release_deny: list[str] = field(default_factory=list)
+    max_file_bytes: int = 1_000_000
+
+    def path(self, rel: str) -> Path:
+        return self.root / rel
+
+
+def _read_table(pyproject: Path) -> dict[str, Any] | None:
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{pyproject}: invalid pyproject.toml: {exc}") from exc
+    return data.get("tool", {}).get(TABLE)
+
+
+def find_root(start: Path) -> Path:
+    """The nearest directory at or above start whose pyproject.toml has [tool.skill-linter]."""
+    for directory in [start, *start.parents]:
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file() and _read_table(candidate) is not None:
+            return directory
+    raise ConfigError(
+        f"no pyproject.toml with a [tool.{TABLE}] table at or above {start}"
+    )
+
+
+def load_config(root: Path) -> Config:
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        raise ConfigError(f"{pyproject} not found")
+    table = _read_table(pyproject)
+    if table is None:
+        raise ConfigError(f"{pyproject} has no [tool.{TABLE}] table")
+    return _build(root, table)
+
+
+def _build(root: Path, t: dict[str, Any]) -> Config:
+    cfg = Config(root=root)
+    known = {
+        "skills_dir": _str,
+        "shared_dirs": _str_list,
+        "commands_dir": _str,
+        "manifest": _str,
+        "workflow_glob": _str,
+        "version_file": _str,
+        "markdown_paths": _str_list,
+        "docs_url": _str,
+        "skill_path": _str,
+        "domain_lists": _str_list,
+        "index_files": _str_list,
+        "sidebar_file": _str,
+        "plugin_root": _str,
+        "ship": _str_list,
+    }
+    structured = {
+        "domains",
+        "credit",
+        "allowed_values",
+        "policy",
+        "severity",
+        "rules",
+        "stamp",
+        "credentials",
+        "vendored",
+        "release",
+    }
+    for key in t:
+        if key not in known and key not in structured:
+            raise ConfigError(f"unknown key '{key}' in [tool.{TABLE}]")
+    for key, check in known.items():
+        if key in t:
+            setattr(cfg, key, check(key, t[key]))
+
+    if cfg.skill_path not in ("domain", "flat"):
+        raise ConfigError("skill_path must be 'domain' or 'flat'")
+    if cfg.plugin_root is not None and cfg.ship is not None:
+        raise ConfigError("plugin_root and ship are exclusive; set one")
+    if "markdown_paths" not in t:
+        cfg.markdown_paths = [cfg.skills_dir]
+
+    if "domains" in t:
+        cfg.domains = _domains(t["domains"])
+    if "credit" in t:
+        cfg.credit = _credit(t["credit"])
+    if "allowed_values" in t:
+        values = _table("allowed_values", t["allowed_values"])
+        for key, val in values.items():
+            if key not in VALUE_LISTS:
+                raise ConfigError(f"unknown key 'allowed_values.{key}'")
+            cfg.values[key] = _str_list(f"allowed_values.{key}", val)
+    if "policy" in t:
+        cfg.policy = _policy(_table("policy", t["policy"]))
+    if "severity" in t:
+        for rule_id, level in _table("severity", t["severity"]).items():
+            if level not in SEVERITY_VALUES:
+                raise ConfigError(
+                    f"severity for {rule_id} must be one of error, warning, off; found {level!r}"
+                )
+            cfg.severity[rule_id] = level
+    if "rules" in t:
+        rules = _table("rules", t["rules"])
+        for key in rules:
+            if key != "custom":
+                raise ConfigError(f"unknown key 'rules.{key}'")
+        cfg.custom_rules = _table_list("rules.custom", rules.get("custom", []))
+    if "stamp" in t:
+        stamp = _table("stamp", t["stamp"])
+        for key in stamp:
+            if key != "files":
+                raise ConfigError(f"unknown key 'stamp.{key}'")
+        cfg.stamp_files = _stamp_files(stamp.get("files", []))
+    if "credentials" in t:
+        credentials = _table("credentials", t["credentials"])
+        for key in credentials:
+            if key != "allow":
+                raise ConfigError(f"unknown key 'credentials.{key}'")
+        cfg.credentials_allow = _str_list(
+            "credentials.allow", credentials.get("allow", [])
+        )
+    if "vendored" in t:
+        cfg.vendored = _vendored(t["vendored"])
+    if "release" in t:
+        release = _table("release", t["release"])
+        for key in release:
+            if key not in ("deny", "max_file_bytes"):
+                raise ConfigError(f"unknown key 'release.{key}'")
+        cfg.release_deny = _str_list("release.deny", release.get("deny", []))
+        if "max_file_bytes" in release:
+            size = release["max_file_bytes"]
+            if not isinstance(size, int) or isinstance(size, bool) or size <= 0:
+                raise ConfigError("release.max_file_bytes must be a positive integer")
+            cfg.max_file_bytes = size
+    return cfg
+
+
+def _str(key: str, value: Any) -> str:
+    if not isinstance(value, str):
+        raise ConfigError(f"{key} must be a string")
+    return value
+
+
+def _str_list(key: str, value: Any) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise ConfigError(f"{key} must be a list of strings")
+    return value
+
+
+def _table(key: str, value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigError(f"{key} must be a table")
+    return value
+
+
+def _table_list(key: str, value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or not all(isinstance(v, dict) for v in value):
+        raise ConfigError(f"{key} must be an array of tables")
+    return value
+
+
+def _range(key: str, value: Any) -> list[int]:
+    ok = (
+        isinstance(value, list)
+        and len(value) == 2
+        and all(isinstance(v, int) and not isinstance(v, bool) for v in value)
+        and value[0] <= value[1]
+    )
+    if not ok:
+        raise ConfigError(f"policy.{key} must be [min, max] integers")
+    return value
+
+
+def _domains(value: Any) -> list[dict[str, str]]:
+    items = _table_list("domains", value)
+    for item in items:
+        if set(item) != {"id", "label"} or not all(
+            isinstance(v, str) for v in item.values()
+        ):
+            raise ConfigError("domains entries must be { id = '...', label = '...' }")
+    return items
+
+
+def _credit(value: Any) -> dict[str, Any]:
+    credit = _table("credit", value)
+    if set(credit) - {"text", "when"} or not isinstance(credit.get("text"), str):
+        raise ConfigError(
+            "credit must have a 'text' string and an optional 'when' table"
+        )
+    when = credit.get("when", {})
+    if not isinstance(when, dict) or not all(isinstance(v, str) for v in when.values()):
+        raise ConfigError("credit.when must map frontmatter fields to strings")
+    return {"text": credit["text"], "when": when}
+
+
+def _policy(policy: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key, value in policy.items():
+        if key not in POLICY_KEYS:
+            raise ConfigError(f"unknown key 'policy.{key}'")
+        if key == "required_sections":
+            out[key] = _str_list("policy.required_sections", value)
+        elif key in ("workflow_steps", "body_lines"):
+            out[key] = _range(key, value)
+        elif key == "license":
+            out[key] = _str("policy.license", value)
+        elif key == "section_order":
+            if not isinstance(value, bool) and not (
+                isinstance(value, list) and all(isinstance(v, str) for v in value)
+            ):
+                raise ConfigError(
+                    "policy.section_order must be true, false, or a list of section titles"
+                )
+            out[key] = value
+        else:
+            if not isinstance(value, bool):
+                raise ConfigError(f"policy.{key} must be true or false")
+            out[key] = value
+    return out
+
+
+def _vendored(value: Any) -> list[dict[str, str]]:
+    items = _table_list("vendored", value)
+    for item in items:
+        if set(item) != {"path", "source", "tag"} or not all(
+            isinstance(v, str) for v in item.values()
+        ):
+            raise ConfigError("vendored entries must be { path, source, tag } strings")
+    return items
+
+
+COUNT_KEYS = {
+    "version",
+    "skillCount",
+    "workflowCount",
+    "referenceFileCount",
+    "domainCount",
+}
+
+
+PER_SKILL_KEY = "referenceFileCount.{skill}"
+PER_SKILL_GROUPS = ({"skill", "count"}, {"skill", "count", "s"})
+
+
+def valid_count_key(key: str) -> bool:
+    return key in COUNT_KEYS or any(
+        key.startswith(prefix) and len(key) > len(prefix)
+        for prefix in ("skillCount.", "referenceFileCount.")
+    )
+
+
+def _stamp_files(value: Any) -> list[dict[str, Any]]:
+    entries = _table_list("stamp.files", value)
+    for entry in entries:
+        unknown = set(entry) - {"path", "json", "patterns", "markers"}
+        if unknown:
+            raise ConfigError(
+                f"stamp.files entry has unknown key(s): {', '.join(sorted(unknown))}"
+            )
+        if not isinstance(entry.get("path"), str):
+            raise ConfigError("stamp.files entry needs a 'path' string")
+        where = f"stamp.files '{entry['path']}'"
+        for pointer, key in _table(f"{where} json", entry.get("json", {})).items():
+            if not pointer.startswith("/"):
+                raise ConfigError(
+                    f"{where}: JSON pointer {pointer!r} must start with '/'"
+                )
+            if not isinstance(key, str) or not valid_count_key(key):
+                raise ConfigError(f"{where}: unknown count key {key!r}")
+        for item in _table_list(f"{where} patterns", entry.get("patterns", [])):
+            if set(item) != {"key", "regex"} or not all(
+                isinstance(v, str) for v in item.values()
+            ):
+                raise ConfigError(
+                    f"{where}: patterns entries are {{ key, regex }} strings"
+                )
+            if not valid_count_key(item["key"]):
+                raise ConfigError(f"{where}: unknown count key {item['key']!r}")
+            try:
+                regex = re.compile(item["regex"])
+            except re.error as exc:
+                raise ConfigError(f"{where}: regex does not compile: {exc}") from exc
+            if item["key"] == PER_SKILL_KEY:
+                if set(regex.groupindex) not in PER_SKILL_GROUPS or regex.groups != len(
+                    regex.groupindex
+                ):
+                    raise ConfigError(
+                        f"{where}: regex for {PER_SKILL_KEY} needs named groups 'skill' and 'count', optionally 's', and no others"
+                    )
+            elif regex.groups != 1:
+                raise ConfigError(
+                    f"{where}: regex {item['regex']!r} must have exactly one group (the number)"
+                )
+        if "markers" in entry and not isinstance(entry["markers"], bool):
+            raise ConfigError(f"{where}: markers must be true or false")
+    return entries