skillscheck 0.1.0__py3-none-any.whl

skillscheck/agents/__init__.py

@@ -0,0 +1,106 @@
+"""Agent adapters and cross-agent checks."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ..models import Diagnostic, Level, SkillInfo
+
+from .claude import ClaudeAdapter
+from .codex import CodexAdapter
+from .copilot import CopilotAdapter
+from .cursor import CursorAdapter
+from .gemini import GeminiAdapter
+from .roo import RooAdapter
+from .swival import SwivalAdapter
+from .windsurf import WindsurfAdapter
+
+
+class AgentAdapter(Protocol):
+    name: str
+    source_url: str
+
+    def detect(self, repo_root: Path) -> bool: ...
+    def check(self, repo_root: Path, skills: list[SkillInfo]) -> list[Diagnostic]: ...
+    def known_frontmatter_fields(self) -> set[str]: ...
+    def allows_tools_list_syntax(self) -> bool: ...
+
+
+ALL_ADAPTERS: list[AgentAdapter] = [
+    ClaudeAdapter(),
+    CodexAdapter(),
+    CopilotAdapter(),
+    CursorAdapter(),
+    GeminiAdapter(),
+    RooAdapter(),
+    SwivalAdapter(),
+    WindsurfAdapter(),
+]  # type: ignore[list-item]
+
+
+def get_adapters(names: list[str] | None, repo_root: Path) -> list[AgentAdapter]:
+    if names is None or names == ["all"]:
+        return [a for a in ALL_ADAPTERS if a.detect(repo_root)]
+    result = []
+    name_map = {a.name: a for a in ALL_ADAPTERS}
+    for n in names:
+        if n in name_map:
+            result.append(name_map[n])
+    return result
+
+
+def _read_json_metadata(path: Path) -> dict | None:
+    import json
+
+    try:
+        data = json.loads(path.read_text())
+        return data if isinstance(data, dict) else None
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def cross_agent_check(
+    repo_root: Path, adapters: list[AgentAdapter]
+) -> list[Diagnostic]:
+    if len(adapters) < 2:
+        return []
+
+    diags: list[Diagnostic] = []
+    names: dict[str, str] = {}
+    versions: dict[str, str] = {}
+    descriptions: dict[str, str] = {}
+
+    config_files = {
+        "plugin.json": repo_root / ".claude-plugin" / "plugin.json",
+        "gemini-extension.json": repo_root / "gemini-extension.json",
+    }
+
+    for label, path in config_files.items():
+        data = _read_json_metadata(path)
+        if data is None:
+            continue
+        if "name" in data:
+            names[label] = data["name"]
+        if "version" in data:
+            versions[label] = data["version"]
+        if "description" in data:
+            descriptions[label] = data["description"]
+
+    for field, collected, check_id in [
+        ("name", names, "3c.name-mismatch"),
+        ("version", versions, "3c.version-mismatch"),
+        ("description", descriptions, "3c.description-mismatch"),
+    ]:
+        if len(set(collected.values())) > 1:
+            detail = ", ".join(f"{k}={v!r}" for k, v in collected.items())
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    check_id,
+                    f"{field} mismatch across agent configs: {detail}",
+                    path=str(repo_root),
+                )
+            )
+
+    return diags

skillscheck/agents/_util.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..models import Diagnostic, Level, SkillInfo
+
+
+def load_json_object(
+    path: Path,
+    prefix: str,
+    label: str,
+    source_url: str,
+) -> tuple[dict | None, list[Diagnostic]]:
+    diags: list[Diagnostic] = []
+    if not path.exists():
+        diags.append(
+            Diagnostic(
+                Level.ERROR,
+                f"{prefix}.missing",
+                f"{label} not found",
+                path=str(path),
+                source_url=source_url,
+            )
+        )
+        return None, diags
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as e:
+        diags.append(
+            Diagnostic(
+                Level.ERROR,
+                f"{prefix}.invalid",
+                f"invalid JSON: {e}",
+                path=str(path),
+                source_url=source_url,
+            )
+        )
+        return None, diags
+    if not isinstance(data, dict):
+        diags.append(
+            Diagnostic(
+                Level.ERROR,
+                f"{prefix}.type",
+                f"{label} must be a JSON object",
+                path=str(path),
+                source_url=source_url,
+            )
+        )
+        return None, diags
+    return data, diags
+
+
+def check_field_types(
+    skill: SkillInfo,
+    fields: set[str],
+    expected_type: type | tuple[type, ...],
+    type_label: str,
+    check_prefix: str,
+    source_url: str,
+    validator: Any = None,
+) -> list[Diagnostic]:
+    diags: list[Diagnostic] = []
+    fm = skill.frontmatter or {}
+    for field in fields:
+        val = fm.get(field)
+        if val is None:
+            continue
+        if validator is not None:
+            if not validator(val):
+                diags.append(
+                    Diagnostic(
+                        Level.ERROR,
+                        f"{check_prefix}.frontmatter.{field}-type",
+                        f"'{field}' must be {type_label}, got {type(val).__name__}",
+                        path=skill.skill_md_path,
+                        source_url=source_url,
+                    )
+                )
+        elif not isinstance(val, expected_type):
+            diags.append(
+                Diagnostic(
+                    Level.ERROR,
+                    f"{check_prefix}.frontmatter.{field}-type",
+                    f"'{field}' must be {type_label}, got {type(val).__name__}",
+                    path=skill.skill_md_path,
+                    source_url=source_url,
+                )
+            )
+    return diags

skillscheck/agents/claude.py

@@ -0,0 +1,383 @@
+"""Claude Code agent adapter (3a)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..models import Diagnostic, Level, SkillInfo
+from ._util import load_json_object
+
+EXTENSION_FIELDS = {
+    "disable-model-invocation",
+    "user-invocable",
+    "argument-hint",
+    "model",
+    "context",
+    "agent",
+    "hooks",
+}
+
+PLUGIN_JSON_ALLOWED_FIELDS = {
+    "name",
+    "description",
+    "version",
+    "author",
+    "keywords",
+    "license",
+    "repository",
+    "homepage",
+}
+
+
+class ClaudeAdapter:
+    name = "claude"
+    source_url = "https://code.claude.com/docs/en/skills"
+
+    def detect(self, repo_root: Path) -> bool:
+        return (repo_root / ".claude-plugin").is_dir()
+
+    def known_frontmatter_fields(self) -> set[str]:
+        return EXTENSION_FIELDS
+
+    def allows_tools_list_syntax(self) -> bool:
+        return False
+
+    def check(self, repo_root: Path, skills: list[SkillInfo]) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        plugin_dir = repo_root / ".claude-plugin"
+
+        diags.extend(self._check_plugin_json(plugin_dir))
+        diags.extend(self._check_marketplace_json(plugin_dir, root=repo_root))
+        diags.extend(self._check_consistency(plugin_dir))
+        return diags
+
+    def _check_plugin_json(self, plugin_dir: Path) -> list[Diagnostic]:
+        path = plugin_dir / "plugin.json"
+        data, diags = load_json_object(
+            path, "3a.plugin-json", "plugin.json", self.source_url
+        )
+        if data is None:
+            return diags
+
+        if "name" not in data:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.plugin-json.name",
+                    "plugin.json missing 'name' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        if "version" not in data:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.plugin-json.version",
+                    "plugin.json missing 'version' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        if "description" not in data:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.plugin-json.description",
+                    "plugin.json missing 'description' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+
+        author = data.get("author")
+        if author is None:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.plugin-json.author",
+                    "plugin.json missing 'author' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        elif not isinstance(author, dict):
+            diags.append(
+                Diagnostic(
+                    Level.ERROR,
+                    "3a.plugin-json.author-type",
+                    "plugin.json 'author' must be an object with a 'name' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        elif "name" not in author:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.plugin-json.author-name",
+                    "plugin.json 'author' object missing 'name' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+
+        keywords = data.get("keywords")
+        if keywords is None:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.plugin-json.keywords",
+                    "plugin.json missing 'keywords' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        elif not isinstance(keywords, list):
+            diags.append(
+                Diagnostic(
+                    Level.ERROR,
+                    "3a.plugin-json.keywords-type",
+                    "plugin.json 'keywords' must be an array of strings",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        elif not all(isinstance(k, str) for k in keywords):
+            diags.append(
+                Diagnostic(
+                    Level.ERROR,
+                    "3a.plugin-json.keywords-items",
+                    "plugin.json 'keywords' array must contain only strings",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+
+        bad_fields = set(data.keys()) - PLUGIN_JSON_ALLOWED_FIELDS
+        if bad_fields:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.plugin-json.fields",
+                    f"plugin.json has unrecognized fields: {', '.join(sorted(bad_fields))}",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+
+        return diags
+
+    def _check_marketplace_json(self, plugin_dir: Path, root: Path) -> list[Diagnostic]:
+        path = plugin_dir / "marketplace.json"
+        data, diags = load_json_object(
+            path, "3a.marketplace-json", "marketplace.json", self.source_url
+        )
+        if data is None:
+            return diags
+
+        if "name" not in data:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.marketplace-json.name",
+                    "marketplace.json missing 'name' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+
+        metadata = data.get("metadata")
+        if metadata is None:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.marketplace-json.metadata",
+                    "marketplace.json missing 'metadata' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        elif not isinstance(metadata, dict):
+            diags.append(
+                Diagnostic(
+                    Level.ERROR,
+                    "3a.marketplace-json.metadata-type",
+                    "marketplace.json 'metadata' must be an object",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        else:
+            if "description" not in metadata:
+                diags.append(
+                    Diagnostic(
+                        Level.WARNING,
+                        "3a.marketplace-json.metadata-desc",
+                        "marketplace.json 'metadata' missing 'description' field",
+                        path=str(path),
+                        source_url=self.source_url,
+                    )
+                )
+
+        owner = data.get("owner")
+        if owner is None:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.marketplace-json.owner",
+                    "marketplace.json missing 'owner' field",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        elif not isinstance(owner, dict):
+            diags.append(
+                Diagnostic(
+                    Level.ERROR,
+                    "3a.marketplace-json.owner-type",
+                    "marketplace.json 'owner' must be an object",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        else:
+            if "name" not in owner:
+                diags.append(
+                    Diagnostic(
+                        Level.WARNING,
+                        "3a.marketplace-json.owner-name",
+                        "marketplace.json 'owner' missing 'name' field",
+                        path=str(path),
+                        source_url=self.source_url,
+                    )
+                )
+
+        if "plugins" not in data:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.marketplace-json.plugins",
+                    "marketplace.json missing 'plugins' array",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        elif not isinstance(data["plugins"], list):
+            diags.append(
+                Diagnostic(
+                    Level.ERROR,
+                    "3a.marketplace-json.plugins-type",
+                    "'plugins' must be an array",
+                    path=str(path),
+                    source_url=self.source_url,
+                )
+            )
+        else:
+            for i, plugin in enumerate(data["plugins"]):
+                if not isinstance(plugin, dict):
+                    diags.append(
+                        Diagnostic(
+                            Level.ERROR,
+                            "3a.marketplace-json.plugin-type",
+                            f"plugins[{i}] must be an object",
+                            path=str(path),
+                            source_url=self.source_url,
+                        )
+                    )
+                    continue
+                source = plugin.get("source")
+                if source is None:
+                    diags.append(
+                        Diagnostic(
+                            Level.WARNING,
+                            "3a.marketplace-json.plugin-source",
+                            f"plugins[{i}] missing 'source' field",
+                            path=str(path),
+                            source_url=self.source_url,
+                        )
+                    )
+                elif not isinstance(source, str):
+                    diags.append(
+                        Diagnostic(
+                            Level.ERROR,
+                            "3a.marketplace-json.plugin-source-type",
+                            f"plugins[{i}] 'source' must be a string, got {type(source).__name__}",
+                            path=str(path),
+                            source_url=self.source_url,
+                        )
+                    )
+                else:
+                    resolved = (root / source).resolve()
+                    if not resolved.is_dir():
+                        diags.append(
+                            Diagnostic(
+                                Level.ERROR,
+                                "3a.marketplace-json.plugin-source-missing",
+                                f"plugins[{i}] source '{source}' does not resolve to a directory",
+                                path=str(path),
+                                source_url=self.source_url,
+                            )
+                        )
+
+        return diags
+
+    def _check_consistency(self, plugin_dir: Path) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        pj = plugin_dir / "plugin.json"
+        mj = plugin_dir / "marketplace.json"
+
+        if not pj.exists() or not mj.exists():
+            return diags
+
+        try:
+            pj_data = json.loads(pj.read_text())
+            mj_data = json.loads(mj.read_text())
+        except (json.JSONDecodeError, OSError):
+            return diags
+
+        if not isinstance(pj_data, dict) or not isinstance(mj_data, dict):
+            return diags
+
+        pj_name = pj_data.get("name", "")
+        mj_name = mj_data.get("name", "")
+        if pj_name and mj_name and pj_name != mj_name:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.consistency.name",
+                    f"name mismatch: plugin.json='{pj_name}' marketplace.json='{mj_name}'",
+                    path=str(plugin_dir),
+                    source_url=self.source_url,
+                )
+            )
+
+        pj_desc = pj_data.get("description", "")
+        mj_meta = mj_data.get("metadata", {})
+        mj_desc = mj_meta.get("description", "") if isinstance(mj_meta, dict) else ""
+        if pj_desc and mj_desc and pj_desc != mj_desc:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.consistency.description",
+                    "description mismatch: plugin.json vs marketplace.json metadata.description",
+                    path=str(plugin_dir),
+                    source_url=self.source_url,
+                )
+            )
+
+        pj_version = pj_data.get("version", "")
+        mj_version = mj_data.get("version", "")
+        if pj_version and mj_version and pj_version != mj_version:
+            diags.append(
+                Diagnostic(
+                    Level.WARNING,
+                    "3a.consistency.version",
+                    f"version mismatch: plugin.json='{pj_version}' marketplace.json='{mj_version}'",
+                    path=str(plugin_dir),
+                    source_url=self.source_url,
+                )
+            )
+
+        return diags