memproof 0.1.0__tar.gz → 0.2.0__tar.gz

{memproof-0.1.0 → memproof-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memproof
-Version: 0.1.0
+Version: 0.2.0
 Summary: Evidence-first health checks for Markdown knowledge vaults.
 Author: memproof contributors
 License-Expression: MIT
@@ -19,24 +19,41 @@ License-File: LICENSE
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: ruff==0.17.2; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
 Dynamic: license-file
 
 # memproof
 
+[![PyPI](https://img.shields.io/pypi/v/memproof.svg)](https://pypi.org/project/memproof/)
+[![test](https://github.com/hsys123/memproof/actions/workflows/test.yml/badge.svg)](https://github.com/hsys123/memproof/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 Evidence-first health checks for Markdown knowledge vaults.
 
 `memproof` answers one question: **can you prove what your knowledge base claims?**
 Every finding carries a `path:line`, the evidence behind it, and a concrete fix.
 It is read-only, offline, and deterministic.
 
+## Check Agent Skills (agentskills.io)
+
+Point `memproof skills` at a directory of `skills/<name>/SKILL.md` to validate the agentskills.io
+contract: kebab-case names that match their directory, description limits,
+optional-field types and unknown keys. Add `--registry skills.json` to diff the disk against a declared skill registry in both directions.
+
+```bash
+memproof skills ./skills --registry config/skills.json --fail-on high
+```
+
 ## Install
 
 ```bash
 uv tool install memproof
 # or
 pip install memproof
+
+# before the PyPI release, install straight from GitHub:
+uv tool install git+https://github.com/hsys123/memproof
 ```
 
 ## Use

{memproof-0.1.0 → memproof-0.2.0}/README.md

@@ -1,17 +1,34 @@
 # memproof
 
+[![PyPI](https://img.shields.io/pypi/v/memproof.svg)](https://pypi.org/project/memproof/)
+[![test](https://github.com/hsys123/memproof/actions/workflows/test.yml/badge.svg)](https://github.com/hsys123/memproof/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 Evidence-first health checks for Markdown knowledge vaults.
 
 `memproof` answers one question: **can you prove what your knowledge base claims?**
 Every finding carries a `path:line`, the evidence behind it, and a concrete fix.
 It is read-only, offline, and deterministic.
 
+## Check Agent Skills (agentskills.io)
+
+Point `memproof skills` at a directory of `skills/<name>/SKILL.md` to validate the agentskills.io
+contract: kebab-case names that match their directory, description limits,
+optional-field types and unknown keys. Add `--registry skills.json` to diff the disk against a declared skill registry in both directions.
+
+```bash
+memproof skills ./skills --registry config/skills.json --fail-on high
+```
+
 ## Install
 
 ```bash
 uv tool install memproof
 # or
 pip install memproof
+
+# before the PyPI release, install straight from GitHub:
+uv tool install git+https://github.com/hsys123/memproof
 ```
 
 ## Use

{memproof-0.1.0 → memproof-0.2.0}/memproof/__init__.py

@@ -1,3 +1,3 @@
 """memproof — evidence-first health checks for Markdown knowledge vaults."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{memproof-0.1.0 → memproof-0.2.0}/memproof/cli.py

@@ -10,6 +10,15 @@ from .checks import ALL_CHECKS
 from .checks import links as links_check
 from .model import Finding
 from .report import render_json, render_markdown, write_report
+from .skills import (
+    render_json as render_skills_json,
+)
+from .skills import (
+    render_markdown as render_skills_markdown,
+)
+from .skills import (
+    scan_skills,
+)
 from .vault import load_vault
 
 FAIL_RANK = {"high": 0, "medium": 1, "low": 2}
@@ -56,6 +65,17 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="reference date for freshness checks (YYYY-MM-DD)",
     )
+    skills = subparsers.add_parser("skills", help="check Agent Skills (SKILL.md) spec conformance")
+    skills.add_argument("path", type=Path, help="directory containing skills/<name>/SKILL.md")
+    skills.add_argument("--registry", type=Path, help="JSON file listing the expected skill ids")
+    skills.add_argument("--format", choices=("markdown", "json"), default="markdown")
+    skills.add_argument("--output", type=Path, help="write the report to this file")
+    skills.add_argument(
+        "--fail-on",
+        choices=("none", "low", "medium", "high"),
+        default="none",
+        help="exit 1 when a finding at or above this severity exists",
+    )
     subparsers.add_parser("version", help="print the version")
     return parser
 
@@ -80,6 +100,31 @@ def main(argv: list[str] | None = None) -> int:
         print(__version__)
         return 0
 
+    if args.command == "skills":
+        skills_root = args.path
+        if not skills_root.is_dir():
+            print(f"memproof: not a directory: {skills_root}", file=sys.stderr)
+            return 2
+        skill_findings, scan = scan_skills(skills_root, args.registry)
+        content = (
+            render_skills_markdown(scan, skill_findings)
+            if args.format == "markdown"
+            else render_skills_json(scan, skill_findings)
+        )
+        if args.output:
+            write_report(args.output, content)
+            print(f"wrote {args.output}")
+        else:
+            sys.stdout.write(content)
+        if args.fail_on == "none":
+            return 0
+        threshold = FAIL_RANK[args.fail_on]
+        worst = min(
+            (FAIL_RANK.get(finding.severity, 99) for finding in skill_findings),
+            default=99,
+        )
+        return 1 if worst <= threshold else 0
+
     root = args.path
     if not root.is_dir():
         print(f"memproof: not a directory: {root}", file=sys.stderr)

memproof-0.2.0/memproof/skills.py

@@ -0,0 +1,524 @@
+"""Agent Skills (SKILL.md) spec-conformance and registry-consistency checks.
+
+Implements the agentskills.io frontmatter contract: name, description, and the
+optional license / compatibility / metadata / allowed-tools fields. Findings
+carry path:line, evidence, and a fix, mirroring the vault checks.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .model import Finding
+from .report import score, summarize
+
+SCHEMA = "memproof.skills.v1"
+NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+NAME_MAX = 64
+DESCRIPTION_MAX = 1024
+COMPATIBILITY_MAX = 500
+REQUIRED_KEYS = ("name", "description")
+KNOWN_OPTIONAL_KEYS = ("allowed-tools", "compatibility", "license", "metadata")
+REGISTRY_LIST_KEYS = ("skills", "capabilities", "entries", "items")
+REGISTRY_NAME_KEYS = ("id", "name", "skill")
+
+
+@dataclass(frozen=True)
+class SkillsScan:
+    root: Path
+    skills: int
+    registry: int | None
+
+
+def _finding(
+    check: str,
+    severity: str,
+    path: str,
+    line: int,
+    message: str,
+    evidence: str = "",
+    fix: str = "",
+) -> Finding:
+    return Finding(
+        check=check,
+        severity=severity,
+        path=path,
+        line=line,
+        message=message,
+        evidence=evidence,
+        fix=fix,
+    )
+
+
+def _split_frontmatter(text: str) -> tuple[list[str] | None, str | None]:
+    if not text.startswith("---"):
+        return None, "file does not start with a --- frontmatter block"
+    lines = text.splitlines()
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            return lines[1:index], None
+    return None, "frontmatter closing --- is missing"
+
+
+def _key_lines(fm_lines: list[str]) -> dict[str, int]:
+    keys: dict[str, int] = {}
+    for offset, line in enumerate(fm_lines):
+        if not line or line[:1].isspace() or ":" not in line:
+            continue
+        key = line.split(":", 1)[0].strip()
+        keys.setdefault(key, offset + 2)
+    return keys
+
+
+def check_spec(path: Path, rel: str) -> list[Finding]:
+    """L1: agentskills.io frontmatter conformance for one skill."""
+    findings: list[Finding] = []
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return [
+            _finding(
+                "skills.spec",
+                "high",
+                rel,
+                1,
+                "SKILL.md is unreadable",
+                str(exc)[:200],
+                "fix the file encoding or permissions",
+            )
+        ]
+    fm_lines, error = _split_frontmatter(text)
+    if fm_lines is None or error is not None:
+        return [
+            _finding(
+                "skills.spec",
+                "high",
+                rel,
+                1,
+                error or "missing frontmatter",
+                "agentskills.io requires a SKILL.md frontmatter block",
+                "add a --- name/description --- block",
+            )
+        ]
+    raw = "\n".join(fm_lines)
+    try:
+        loaded: Any = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        return [
+            _finding(
+                "skills.spec",
+                "high",
+                rel,
+                1,
+                "frontmatter YAML cannot be parsed",
+                str(exc)[:200],
+                "fix the YAML syntax",
+            )
+        ]
+    if not isinstance(loaded, dict):
+        return [
+            _finding(
+                "skills.spec",
+                "high",
+                rel,
+                1,
+                "frontmatter must be a mapping",
+                f"got {type(loaded).__name__}",
+                "use key: value pairs",
+            )
+        ]
+
+    keys = _key_lines(fm_lines)
+    known = set(REQUIRED_KEYS) | set(KNOWN_OPTIONAL_KEYS)
+    unknown = sorted(str(key) for key in loaded if key not in known)
+    if unknown:
+        findings.append(
+            _finding(
+                "skills.spec",
+                "medium",
+                rel,
+                keys.get(unknown[0], 1),
+                "unknown frontmatter keys: " + ", ".join(unknown),
+                "spec fields: name, description, license, compatibility, metadata, allowed-tools",
+                "remove them or propose them upstream at agentskills.io",
+            )
+        )
+
+    name = loaded.get("name")
+    if not isinstance(name, str) or not name.strip():
+        findings.append(
+            _finding(
+                "skills.spec",
+                "high",
+                rel,
+                keys.get("name", 1),
+                "missing or empty name",
+                "every skill needs a name",
+                "add the name field",
+            )
+        )
+    else:
+        if len(name) > NAME_MAX:
+            findings.append(
+                _finding(
+                    "skills.spec",
+                    "high",
+                    rel,
+                    keys.get("name", 1),
+                    f"name is {len(name)} characters (max {NAME_MAX})",
+                    name[:80],
+                    "shorten the name",
+                )
+            )
+        if NAME_RE.fullmatch(name) is None:
+            findings.append(
+                _finding(
+                    "skills.spec",
+                    "high",
+                    rel,
+                    keys.get("name", 1),
+                    "name must be lowercase kebab-case (a-z, 0-9, single hyphens)",
+                    name,
+                    "rename the skill and its directory",
+                )
+            )
+        if name != path.parent.name:
+            findings.append(
+                _finding(
+                    "skills.spec",
+                    "high",
+                    rel,
+                    keys.get("name", 1),
+                    "name must match its directory",
+                    f"name={name!r} directory={path.parent.name!r}",
+                    "make them identical",
+                )
+            )
+
+    description = loaded.get("description")
+    if not isinstance(description, str) or not description.strip():
+        findings.append(
+            _finding(
+                "skills.spec",
+                "high",
+                rel,
+                keys.get("description", 1),
+                "missing or empty description",
+                "the description drives skill discovery",
+                "describe what the skill does and when to use it",
+            )
+        )
+    elif len(description) > DESCRIPTION_MAX:
+        findings.append(
+            _finding(
+                "skills.spec",
+                "medium",
+                rel,
+                keys.get("description", 1),
+                f"description is {len(description)} characters (max {DESCRIPTION_MAX})",
+                description[:80] + "...",
+                "move detail into the body or references/",
+            )
+        )
+
+    license_value = loaded.get("license")
+    if license_value is not None and not isinstance(license_value, str):
+        findings.append(
+            _finding(
+                "skills.spec",
+                "low",
+                rel,
+                keys.get("license", 1),
+                "license must be a short string or a reference to a bundled license file",
+                f"got {type(license_value).__name__}",
+                "use a plain string",
+            )
+        )
+
+    compatibility = loaded.get("compatibility")
+    if compatibility is not None:
+        if not isinstance(compatibility, str):
+            findings.append(
+                _finding(
+                    "skills.spec",
+                    "medium",
+                    rel,
+                    keys.get("compatibility", 1),
+                    "compatibility must be a string",
+                    f"got {type(compatibility).__name__}",
+                    "describe environment requirements in one string",
+                )
+            )
+        elif len(compatibility) > COMPATIBILITY_MAX:
+            findings.append(
+                _finding(
+                    "skills.spec",
+                    "medium",
+                    rel,
+                    keys.get("compatibility", 1),
+                    f"compatibility is {len(compatibility)} characters (max {COMPATIBILITY_MAX})",
+                    compatibility[:80] + "...",
+                    "keep only the hard requirements",
+                )
+            )
+
+    allowed_tools = loaded.get("allowed-tools")
+    if allowed_tools is not None:
+        shape_ok = isinstance(allowed_tools, str) or (
+            isinstance(allowed_tools, list) and all(isinstance(item, str) for item in allowed_tools)
+        )
+        if not shape_ok:
+            findings.append(
+                _finding(
+                    "skills.spec",
+                    "medium",
+                    rel,
+                    keys.get("allowed-tools", 1),
+                    "allowed-tools must be a string or a list of strings",
+                    f"got {type(allowed_tools).__name__}",
+                    "use a space-delimited string or a list",
+                )
+            )
+
+    metadata = loaded.get("metadata")
+    if metadata is not None:
+        if not isinstance(metadata, dict):
+            findings.append(
+                _finding(
+                    "skills.spec",
+                    "medium",
+                    rel,
+                    keys.get("metadata", 1),
+                    "metadata must be a mapping of string to string",
+                    f"got {type(metadata).__name__}",
+                    "use key: value pairs",
+                )
+            )
+        else:
+            for meta_key, meta_value in metadata.items():
+                if not isinstance(meta_key, str) or not meta_key.strip():
+                    findings.append(
+                        _finding(
+                            "skills.spec",
+                            "medium",
+                            rel,
+                            keys.get("metadata", 1),
+                            "metadata keys must be non-empty strings",
+                            f"got {meta_key!r}",
+                            "name every metadata key",
+                        )
+                    )
+                elif isinstance(meta_value, (dict, list)):
+                    findings.append(
+                        _finding(
+                            "skills.spec",
+                            "medium",
+                            rel,
+                            keys.get("metadata", 1),
+                            f"metadata[{meta_key!r}] must be a scalar (the spec maps string to string)",
+                            f"got {type(meta_value).__name__}",
+                            "flatten the structure or serialize it",
+                        )
+                    )
+                elif not isinstance(meta_value, str):
+                    findings.append(
+                        _finding(
+                            "skills.spec",
+                            "low",
+                            rel,
+                            keys.get("metadata", 1),
+                            f"metadata[{meta_key!r}] is not a string",
+                            f"got {type(meta_value).__name__}",
+                            "quote the value so clients read it as a string",
+                        )
+                    )
+    return findings
+
+
+def load_registry(path: Path) -> tuple[list[str] | None, str | None]:
+    """Load a registry file: a JSON array of names/objects, or an object wrapping one."""
+    try:
+        doc: Any = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        return None, str(exc)[:200]
+    items: list[Any] | None = None
+    if isinstance(doc, list):
+        items = doc
+    elif isinstance(doc, dict):
+        for key in REGISTRY_LIST_KEYS:
+            value = doc.get(key)
+            if isinstance(value, list):
+                items = value
+                break
+    if items is None:
+        return (
+            None,
+            "registry must be a JSON array or an object with a skills/capabilities/entries/items list",
+        )
+    names: list[str] = []
+    for item in items:
+        if isinstance(item, str):
+            names.append(item)
+            continue
+        if isinstance(item, dict):
+            for key in REGISTRY_NAME_KEYS:
+                value = item.get(key)
+                if isinstance(value, str):
+                    names.append(value)
+                    break
+            else:
+                return None, "registry entries must be strings or objects with id/name/skill"
+            continue
+        return None, "registry entries must be strings or objects with id/name/skill"
+    return names, None
+
+
+def scan_skills(root: Path, registry_path: Path | None) -> tuple[list[Finding], SkillsScan]:
+    """Scan root for */SKILL.md and (optionally) compare against a registry file."""
+    findings: list[Finding] = []
+    skill_files = sorted(path for path in root.glob("*/SKILL.md") if path.is_file())
+    for path in skill_files:
+        rel = path.relative_to(root).as_posix()
+        findings.extend(check_spec(path, rel))
+    if not skill_files:
+        findings.append(
+            _finding(
+                "skills.spec",
+                "medium",
+                root.as_posix(),
+                1,
+                "no skills discovered",
+                "expected */SKILL.md directories under the root",
+                "point memproof at the skills parent directory",
+            )
+        )
+
+    registry_names: list[str] | None = None
+    registry_count: int | None = None
+    if registry_path is not None:
+        registry_names, error = load_registry(registry_path)
+        if registry_names is None or error is not None:
+            findings.append(
+                _finding(
+                    "skills.registry",
+                    "high",
+                    registry_path.as_posix(),
+                    1,
+                    "registry file cannot be loaded",
+                    error or "unknown error",
+                    "fix the registry JSON",
+                )
+            )
+        else:
+            registry_count = len(registry_names)
+            disk = {path.parent.name for path in skill_files}
+            declared = set(registry_names)
+            for name in sorted(disk - declared):
+                findings.append(
+                    _finding(
+                        "skills.registry",
+                        "medium",
+                        name + "/SKILL.md",
+                        1,
+                        "skill exists on disk but is missing from the registry",
+                        f"registry: {registry_path.as_posix()}",
+                        "register it or remove the directory",
+                    )
+                )
+            for name in sorted(declared - disk):
+                findings.append(
+                    _finding(
+                        "skills.registry",
+                        "medium",
+                        registry_path.as_posix(),
+                        1,
+                        f"registry entry has no skill directory: {name}",
+                        f"{len(disk)} skills found on disk",
+                        "remove the entry or add the skill",
+                    )
+                )
+            duplicates = sorted({n for n in registry_names if registry_names.count(n) > 1})
+            if duplicates:
+                findings.append(
+                    _finding(
+                        "skills.registry",
+                        "medium",
+                        registry_path.as_posix(),
+                        1,
+                        "duplicate registry entries: " + ", ".join(duplicates),
+                        f"{len(registry_names)} entries total",
+                        "keep one entry per skill",
+                    )
+                )
+    return findings, SkillsScan(root=root, skills=len(skill_files), registry=registry_count)
+
+
+def render_markdown(scan: SkillsScan, findings: list[Finding]) -> str:
+    ordered = sorted(findings, key=_sort_key)
+    counts = summarize(ordered)
+    registry_label = str(scan.registry) if scan.registry is not None else "off"
+    lines = [
+        f"# memproof skills report — {scan.root.name or scan.root.as_posix()}",
+        "",
+        (
+            f"Score: {score(ordered)}/100 · Skills: {scan.skills} · Registry: {registry_label} · "
+            f"Findings: {counts['high']} high / {counts['medium']} medium / {counts['low']} low"
+        ),
+        "",
+    ]
+    labels = {"high": "High", "medium": "Medium", "low": "Low"}
+    for severity in ("high", "medium", "low"):
+        lines.append(f"## {labels[severity]}")
+        lines.append("")
+        group = [finding for finding in ordered if finding.severity == severity]
+        if not group:
+            lines.append("None.")
+            lines.append("")
+            continue
+        for finding in group:
+            lines.append(f"- [{finding.check}] {finding.path}:{finding.line} — {finding.message}")
+            if finding.evidence:
+                lines.append(f"  Evidence: {finding.evidence}")
+            if finding.fix:
+                lines.append(f"  Fix: {finding.fix}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _sort_key(finding: Finding) -> tuple[int, str, int, str]:
+    order = {"high": 0, "medium": 1, "low": 2}
+    return (order.get(finding.severity, 99), finding.path, finding.line, finding.check)
+
+
+def render_json(scan: SkillsScan, findings: list[Finding]) -> str:
+    ordered = sorted(findings, key=_sort_key)
+    registry_label = scan.registry if scan.registry is not None else 0
+    payload = {
+        "schema": SCHEMA,
+        "root": scan.root.as_posix(),
+        "summary": {
+            "score": score(ordered),
+            "skills": scan.skills,
+            "registry": registry_label,
+            "findings": summarize(ordered),
+        },
+        "findings": [
+            {
+                "check": finding.check,
+                "severity": finding.severity,
+                "path": finding.path,
+                "line": finding.line,
+                "message": finding.message,
+                "evidence": finding.evidence,
+                "fix": finding.fix,
+            }
+            for finding in ordered
+        ],
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"

{memproof-0.1.0 → memproof-0.2.0}/memproof.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memproof
-Version: 0.1.0
+Version: 0.2.0
 Summary: Evidence-first health checks for Markdown knowledge vaults.
 Author: memproof contributors
 License-Expression: MIT
@@ -19,24 +19,41 @@ License-File: LICENSE
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: ruff==0.17.2; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
 Dynamic: license-file
 
 # memproof
 
+[![PyPI](https://img.shields.io/pypi/v/memproof.svg)](https://pypi.org/project/memproof/)
+[![test](https://github.com/hsys123/memproof/actions/workflows/test.yml/badge.svg)](https://github.com/hsys123/memproof/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 Evidence-first health checks for Markdown knowledge vaults.
 
 `memproof` answers one question: **can you prove what your knowledge base claims?**
 Every finding carries a `path:line`, the evidence behind it, and a concrete fix.
 It is read-only, offline, and deterministic.
 
+## Check Agent Skills (agentskills.io)
+
+Point `memproof skills` at a directory of `skills/<name>/SKILL.md` to validate the agentskills.io
+contract: kebab-case names that match their directory, description limits,
+optional-field types and unknown keys. Add `--registry skills.json` to diff the disk against a declared skill registry in both directions.
+
+```bash
+memproof skills ./skills --registry config/skills.json --fail-on high
+```
+
 ## Install
 
 ```bash
 uv tool install memproof
 # or
 pip install memproof
+
+# before the PyPI release, install straight from GitHub:
+uv tool install git+https://github.com/hsys123/memproof
 ```
 
 ## Use

{memproof-0.1.0 → memproof-0.2.0}/memproof.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ memproof/__main__.py
 memproof/cli.py
 memproof/model.py
 memproof/report.py
+memproof/skills.py
 memproof/vault.py
 memproof.egg-info/PKG-INFO
 memproof.egg-info/SOURCES.txt
@@ -20,4 +21,5 @@ memproof/checks/links.py
 memproof/checks/provenance.py
 memproof/checks/structure.py
 tests/test_checks.py
-tests/test_cli.py
+tests/test_cli.py
+tests/test_skills.py

{memproof-0.1.0 → memproof-0.2.0}/memproof.egg-info/requires.txt

@@ -2,5 +2,5 @@ pyyaml>=6.0
 
 [dev]
 pytest>=8.0
-ruff>=0.6
+ruff==0.17.2
 mypy>=1.11

{memproof-0.1.0 → memproof-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memproof"
-version = "0.1.0"
+version = "0.2.0"
 description = "Evidence-first health checks for Markdown knowledge vaults."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,7 +29,7 @@ Issues = "https://github.com/hsys123/memproof/issues"
 memproof = "memproof.cli:main"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11"]
+dev = ["pytest>=8.0", "ruff==0.17.2", "mypy>=1.11"]
 
 [tool.setuptools.packages.find]
 include = ["memproof*"]

{memproof-0.1.0 → memproof-0.2.0}/tests/test_cli.py

@@ -27,7 +27,7 @@ def run(*args: str) -> subprocess.CompletedProcess[str]:
 def test_version() -> None:
     proc = run("version")
     assert proc.returncode == 0
-    assert proc.stdout.strip() == "0.1.0"
+    assert proc.stdout.strip() == "0.2.0"
 
 
 def test_check_exit_zero_by_default() -> None:

memproof-0.2.0/tests/test_skills.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from memproof.skills import check_spec, load_registry, scan_skills
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run(*args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, "-m", "memproof", *args],
+        cwd=ROOT,
+        env={**os.environ, "PYTHONPATH": str(ROOT), "PYTHONIOENCODING": "utf-8"},
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def write_skill(root: Path, name: str, frontmatter: str) -> Path:
+    skill_dir = root / name
+    skill_dir.mkdir(parents=True)
+    path = skill_dir / "SKILL.md"
+    path.write_text("---\n" + frontmatter + "\n---\n\nBody.\n", encoding="utf-8")
+    return path
+
+
+def codes(findings: list) -> set[str]:
+    return {finding.check for finding in findings}
+
+
+def severities(findings: list) -> list[str]:
+    return [finding.severity for finding in findings]
+
+
+def test_minimal_valid_skill_has_no_findings(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: A portable sample skill.")
+    findings, scan = scan_skills(tmp_path, None)
+    assert findings == []
+    assert scan.skills == 1
+
+
+def test_missing_frontmatter_is_high(tmp_path: Path) -> None:
+    skill = tmp_path / "sample"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("no frontmatter here\n", encoding="utf-8")
+    findings, _ = scan_skills(tmp_path, None)
+    assert severities(findings) == ["high"]
+
+
+def test_unclosed_frontmatter_is_high(tmp_path: Path) -> None:
+    skill = tmp_path / "sample"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: sample\n", encoding="utf-8")
+    findings, _ = scan_skills(tmp_path, None)
+    assert severities(findings) == ["high"]
+
+
+def test_broken_yaml_is_high(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: [unclosed")
+    findings, _ = scan_skills(tmp_path, None)
+    assert severities(findings) == ["high"]
+
+
+def test_name_must_match_directory(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: other\ndescription: Mismatched.")
+    findings, _ = scan_skills(tmp_path, None)
+    assert findings and findings[0].severity == "high"
+    assert "must match" in findings[0].message
+
+
+def test_name_must_be_kebab_case(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: Sample\ndescription: Uppercase name.")
+    findings, _ = scan_skills(tmp_path, None)
+    assert findings and findings[0].severity == "high"
+    assert "kebab" in findings[0].message
+
+
+def test_missing_description_is_high(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample")
+    findings, _ = scan_skills(tmp_path, None)
+    assert findings and findings[0].severity == "high"
+    assert "description" in findings[0].message
+
+
+def test_oversized_description_is_medium(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: " + "x" * 1100)
+    findings, _ = scan_skills(tmp_path, None)
+    assert severities(findings) == ["medium"]
+
+
+def test_unknown_frontmatter_key_is_medium(tmp_path: Path) -> None:
+    write_skill(
+        tmp_path,
+        "sample",
+        "name: sample\ndescription: Fine.\nversion: 3",
+    )
+    findings, _ = scan_skills(tmp_path, None)
+    assert len(findings) == 1
+    assert findings[0].severity == "medium"
+    assert "version" in findings[0].message
+
+
+def test_metadata_scalar_rules(tmp_path: Path) -> None:
+    write_skill(
+        tmp_path,
+        "sample",
+        "name: sample\n"
+        "description: Metadata shapes.\n"
+        "metadata:\n"
+        "  aii.tier: core\n"
+        "  aii.flag: true\n"
+        "  aii.nested:\n"
+        "    inner: value\n",
+    )
+    findings, _ = scan_skills(tmp_path, None)
+    levels = sorted(finding.severity for finding in findings)
+    assert levels == ["low", "medium"]
+
+
+def test_metadata_non_mapping_is_medium(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: Flat.\nmetadata: oops")
+    findings, _ = scan_skills(tmp_path, None)
+    assert severities(findings) == ["medium"]
+
+
+def test_oversized_compatibility_is_medium(tmp_path: Path) -> None:
+    write_skill(
+        tmp_path,
+        "sample",
+        "name: sample\ndescription: Compat.\ncompatibility: " + "y" * 600,
+    )
+    findings, _ = scan_skills(tmp_path, None)
+    assert severities(findings) == ["medium"]
+
+
+def test_allowed_tools_list_is_accepted(tmp_path: Path) -> None:
+    write_skill(
+        tmp_path,
+        "sample",
+        "name: sample\ndescription: Tools.\nallowed-tools:\n  - Read\n  - Bash",
+    )
+    findings, _ = scan_skills(tmp_path, None)
+    assert findings == []
+
+
+def test_empty_root_is_medium(tmp_path: Path) -> None:
+    findings, scan = scan_skills(tmp_path, None)
+    assert scan.skills == 0
+    assert severities(findings) == ["medium"]
+
+
+def test_registry_unregistered_and_missing(tmp_path: Path) -> None:
+    write_skill(tmp_path, "present", "name: present\ndescription: On disk.")
+    registry = tmp_path / "registry.json"
+    registry.write_text(json.dumps(["ghost"]), encoding="utf-8")
+    findings, scan = scan_skills(tmp_path, registry)
+    assert scan.registry == 1
+    medium = [f.message for f in findings if f.severity == "medium"]
+    assert any("missing from the registry" in message for message in medium)
+    assert any("no skill directory" in message for message in medium)
+
+
+def test_registry_duplicate_entries_are_medium(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: Dup.")
+    registry = tmp_path / "registry.json"
+    registry.write_text(json.dumps(["sample", "sample"]), encoding="utf-8")
+    findings, scan = scan_skills(tmp_path, registry)
+    assert scan.registry == 2
+    assert any("duplicate" in f.message for f in findings if f.severity == "medium")
+
+
+def test_registry_object_shape_is_supported(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: Shape.")
+    registry = tmp_path / "registry.json"
+    payload = {"skills": [{"id": "sample", "tier": "core"}]}
+    registry.write_text(json.dumps(payload), encoding="utf-8")
+    findings, scan = scan_skills(tmp_path, registry)
+    assert findings == []
+    assert scan.registry == 1
+
+
+def test_registry_parse_error_is_high(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: Bad registry.")
+    registry = tmp_path / "registry.json"
+    registry.write_text("{broken", encoding="utf-8")
+    findings, _ = scan_skills(tmp_path, registry)
+    assert findings and findings[0].severity == "high"
+    assert findings[0].check == "skills.registry"
+
+
+def test_load_registry_rejects_unknown_shapes(tmp_path: Path) -> None:
+    path = tmp_path / "registry.json"
+    path.write_text(json.dumps({"unexpected": 1}), encoding="utf-8")
+    names, error = load_registry(path)
+    assert names is None
+    assert error is not None
+
+
+def test_cli_skills_command_end_to_end(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: sample\ndescription: CLI run.")
+    proc = run("skills", str(tmp_path), "--format", "json")
+    assert proc.returncode == 0, proc.stderr
+    payload = json.loads(proc.stdout)
+    assert payload["schema"] == "memproof.skills.v1"
+    assert payload["summary"]["skills"] == 1
+
+
+def test_cli_skills_fail_on_high(tmp_path: Path) -> None:
+    write_skill(tmp_path, "sample", "name: other\ndescription: Mismatched.")
+    proc = run("skills", str(tmp_path), "--fail-on", "high")
+    assert proc.returncode == 1
+    assert "## High" in proc.stdout
+
+
+def test_check_spec_direct(tmp_path: Path) -> None:
+    skill = write_skill(tmp_path, "sample", "name: sample\ndescription: Direct.")
+    findings = check_spec(skill, "sample/SKILL.md")
+    assert findings == []