drskill 0.1.0__py3-none-any.whl

drskill/checks/__init__.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable
+
+from drskill.ledger import Config
+from drskill.models import Contributor, Finding
+from drskill.resolution import World
+
+CheckFn = Callable[[World, Config], list[Finding]]
+REGISTRY: dict[str, CheckFn] = {}
+
+
+def check(check_id: str):
+    def deco(fn: CheckFn) -> CheckFn:
+        REGISTRY[check_id] = fn
+        return fn
+
+    return deco
+
+
+def fingerprint(check_id: str, contributors: list[Contributor], extra: str = "") -> str:
+    payload = "|".join([check_id, *sorted(c.content_hash for c in contributors), extra])
+    return "sha256:" + hashlib.sha256(payload.encode()).hexdigest()
+
+
+def make_finding(
+    check_id: str,
+    severity: str,
+    contributors: list[Contributor],
+    message: str,
+    *,
+    harnesses: list[str] | None = None,
+    fix_commands: list[str] | None = None,
+    extra_key: str = "",
+) -> Finding:
+    if harnesses is None:
+        harnesses = sorted({d.harness for c in contributors for d in c.deployments})
+    return Finding(
+        check_id=check_id,
+        severity=severity,
+        contributors=[c.id for c in contributors],
+        contributor_names=sorted({c.name for c in contributors}),
+        harnesses=harnesses,
+        message=message,
+        fix_commands=fix_commands or [],
+        fingerprint=fingerprint(check_id, contributors, extra_key),
+    )
+
+
+def run_all(world: World, config: Config) -> list[Finding]:
+    # Import registers every check module exactly once.
+    from drskill.checks import budget, duplicates, filesystem, lockfile, shadowing, spec  # noqa: F401
+
+    findings: list[Finding] = []
+    for fn in REGISTRY.values():
+        findings.extend(fn(world, config))
+    merged: dict[str, Finding] = {}
+    for f in findings:
+        if f.fingerprint in merged:
+            prior = merged[f.fingerprint]
+            merged[f.fingerprint] = prior.model_copy(
+                update={"harnesses": sorted(set(prior.harnesses) | set(f.harnesses))}
+            )
+        else:
+            merged[f.fingerprint] = f
+    return sorted(
+        merged.values(), key=lambda f: (f.severity, f.check_id, f.message)
+    )

drskill/checks/budget.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from drskill.checks import check, make_finding
+from drskill.ledger import Config
+from drskill.models import Finding
+from drskill.resolution import World
+
+
+@check("budget-catalog-tokens")
+def budget_catalog_tokens(world: World, config: Config) -> list[Finding]:
+    out = []
+    for hid, hdef in world.harnesses.items():
+        contributors = world.effective(hid)
+        total = sum(c.token_cost.catalog_tokens for c in contributors)
+        if total > config.budget.catalog_tokens_max:
+            out.append(
+                make_finding(
+                    "budget-catalog-tokens", "warning", contributors,
+                    f"{hdef.display_name} startup catalog is ~{total} tokens "
+                    f"(budget {config.budget.catalog_tokens_max})",
+                    harnesses=[hid],
+                    extra_key=hid,
+                    fix_commands=[f"drskill list --tokens --harness {hid}"],
+                )
+            )
+    return out
+
+
+@check("budget-body-tokens")
+def budget_body_tokens(world: World, config: Config) -> list[Finding]:
+    return [
+        make_finding(
+            "budget-body-tokens", "warning", [c],
+            f"'{c.name}' body is ~{c.token_cost.body_tokens} tokens "
+            f"(warn ceiling {config.budget.body_tokens_warn})",
+            fix_commands=[f"Split or trim {c.id}; move reference material into bundled files"],
+        )
+        for c in world.contributors.values()
+        if c.token_cost.body_tokens > config.budget.body_tokens_warn
+    ]

drskill/checks/duplicates.py

@@ -0,0 +1,103 @@
+"""Exact and near duplicate detection. MinHash is hand rolled and uses
+zlib.crc32 because builtin str hash() is salted per process."""
+
+from __future__ import annotations
+
+import shlex
+import zlib
+from itertools import combinations
+
+from drskill.checks import check, make_finding
+from drskill.ledger import Config
+from drskill.models import Contributor, Finding
+from drskill.resolution import World
+
+SHINGLE_WORDS = 5
+NUM_HASHES = 128
+
+
+def shingles(text: str, k: int = SHINGLE_WORDS) -> set[str]:
+    words = text.lower().split()
+    if len(words) <= k:
+        return {" ".join(words)} if words else set()
+    return {" ".join(words[i : i + k]) for i in range(len(words) - k + 1)}
+
+
+def signature(sh: set[str]) -> list[int]:
+    if not sh:
+        return [0] * NUM_HASHES
+    return [
+        min(zlib.crc32(f"{seed}:{s}".encode()) for s in sh)
+        for seed in range(NUM_HASHES)
+    ]
+
+
+def estimate(a: list[int], b: list[int]) -> float:
+    return sum(x == y for x, y in zip(a, b)) / len(a)
+
+
+def _text(c: Contributor) -> str:
+    return f"{c.routing_text}\n{c.body}"
+
+
+def _harnesses_loading_both(world: World, a: Contributor, b: Contributor) -> set[str]:
+    both = set()
+    for hid in world.harnesses:
+        eff = {c.id for c in world.effective(hid)}
+        if a.id in eff and b.id in eff:
+            both.add(hid)
+    return both
+
+
+@check("exact-duplicate")
+def exact_duplicate(world: World, config: Config) -> list[Finding]:
+    by_hash: dict[str, list[Contributor]] = {}
+    for c in world.contributors.values():
+        by_hash.setdefault(c.content_hash, []).append(c)
+    out = []
+    for group in by_hash.values():
+        if len(group) < 2:
+            continue
+        # pairs co-loaded by one harness belong to double-load, not here
+        clean_pairs = [
+            (a, b)
+            for a, b in combinations(group, 2)
+            if not _harnesses_loading_both(world, a, b)
+        ]
+        if clean_pairs:
+            out.append(
+                make_finding(
+                    "exact-duplicate", "warning", group,
+                    "identical skills installed in more than one place: "
+                    + ", ".join(sorted(c.id for c in group)),
+                    fix_commands=[
+                        f"npx skills remove {shlex.quote(group[0].name)}"
+                        "  # from the copies you don't want"
+                    ],
+                )
+            )
+    return out
+
+
+@check("near-duplicate")
+def near_duplicate(world: World, config: Config) -> list[Finding]:
+    cs = list(world.contributors.values())
+    sigs = {c.id: signature(shingles(_text(c))) for c in cs}
+    out = []
+    for a, b in combinations(cs, 2):
+        if a.content_hash == b.content_hash:
+            continue
+        sim = estimate(sigs[a.id], sigs[b.id])
+        if sim >= config.thresholds.near_duplicate:
+            out.append(
+                make_finding(
+                    "near-duplicate", "warning", [a, b],
+                    f"'{a.name}' and '{b.name}' are ~{sim:.0%} similar; "
+                    "likely the same skill twice",
+                    fix_commands=[
+                        f"Compare and keep one: diff {shlex.quote(a.id)} {shlex.quote(b.id)}",
+                        f"npx skills remove {shlex.quote(b.name)}",
+                    ],
+                )
+            )
+    return out

drskill/checks/filesystem.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import shlex
+
+from drskill.checks import check, make_finding
+from drskill.ledger import Config
+from drskill.models import Finding
+from drskill.resolution import World
+
+
+@check("broken-symlink")
+def broken_symlink(world: World, config: Config) -> list[Finding]:
+    return [
+        make_finding(
+            "broken-symlink", "error", [],
+            f"broken symlink: {b.path} points at nothing",
+            harnesses=[b.harness],
+            extra_key=str(b.path),
+            fix_commands=[f"rm {shlex.quote(str(b.path))}"],
+        )
+        for b in world.broken_symlinks
+    ]
+
+
+@check("unreadable-skill")
+def unreadable_skill(world: World, config: Config) -> list[Finding]:
+    return [
+        make_finding(
+            "unreadable-skill", "warning", [],
+            f"cannot read {path}: skipped",
+            harnesses=[harness],
+            extra_key=str(path),
+            fix_commands=[f"Check permissions: ls -l {shlex.quote(str(path))}"],
+        )
+        for harness, path in world.unreadable
+    ]

drskill/checks/lockfile.py

@@ -0,0 +1,129 @@
+"""skills-lock.json parsing (read-only, always) and drift attribution."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shlex
+from pathlib import Path
+
+from drskill.checks import check, make_finding
+from drskill.ledger import Config
+from drskill.models import Finding
+from drskill.resolution import World
+
+# Verified 2026-07-19 against `npx skills add vercel-labs/agent-skills` output and
+# vercel-labs/skills @ src/local-lock.ts (LocalSkillLockEntry.computedHash /
+# computeSkillFolderHash): the local project lockfile field is `computedHash`, a
+# plain sha256 hex digest with no prefix. `hash`/`integrity`/`sha256` are kept as
+# fallbacks for the (untested) global/user-scope lock schema, which the same source
+# comment says uses a GitHub tree SHA instead.
+_HASH_FIELDS = ("computedHash", "hash", "integrity", "sha256")
+
+
+def load_lockfile(project_root: Path) -> dict[str, dict] | None:
+    p = project_root / "skills-lock.json"
+    if not p.is_file():
+        return None
+    try:
+        data = json.loads(p.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    skills = data.get("skills", data)
+    if not isinstance(skills, dict):
+        return None
+    return {k: v for k, v in skills.items() if isinstance(v, dict)}
+
+
+def compute_tree_hash(skill_dir: Path) -> str:
+    # Mirrors vercel-labs/skills `computeSkillFolderHash` (src/local-lock.ts): sha256
+    # over relative-path bytes immediately followed by file-content bytes, sorted by
+    # relative path, with `.git` and `node_modules` subdirectories excluded. No
+    # separator byte between path and content — matched here for hash compatibility.
+    h = hashlib.sha256()
+    for f in sorted(
+        p
+        for p in skill_dir.rglob("*")
+        if p.is_file() and not {".git", "node_modules"} & set(p.relative_to(skill_dir).parts[:-1])
+    ):
+        h.update(f.relative_to(skill_dir).as_posix().encode())
+        h.update(f.read_bytes())
+    return h.hexdigest()
+
+
+def _entry_hash(entry: dict) -> str | None:
+    for field in _HASH_FIELDS:
+        v = entry.get(field)
+        if isinstance(v, str):
+            return v.removeprefix("sha256:").removeprefix("sha256-")
+    return None
+
+
+@check("lockfile-drift")
+def lockfile_drift(world: World, config: Config) -> list[Finding]:
+    if not world.lockfile:
+        return []
+    by_name = {c.name: c for c in world.contributors.values()}
+    out = []
+    matches: list[str] = []
+    mismatches: list[tuple[str, object]] = []
+    for name, entry in sorted(world.lockfile.items()):
+        expected = _entry_hash(entry)
+        c = by_name.get(name)
+        if c is None:
+            out.append(
+                make_finding(
+                    "lockfile-drift", "warning", [],
+                    f"'{name}' is in skills-lock.json but not found on disk",
+                    harnesses=sorted(world.harnesses),
+                    extra_key=f"missing:{name}",
+                    fix_commands=[
+                        f"npx skills add {shlex.quote(str(entry.get('source', name)))}",
+                        "npx skills sync",
+                    ],
+                )
+            )
+            continue
+        if expected is None:
+            continue
+        skill_dir = Path(c.id).parent
+        if compute_tree_hash(skill_dir) == expected:
+            matches.append(name)
+        else:
+            mismatches.append((name, c))
+
+    # Self-calibration: if every hashed entry mismatches (and at least one
+    # matched, verifying the algorithm), attribute each mismatch by name. If
+    # NONE match, we can't tell drift from an algorithm mismatch against this
+    # lockfile's producer — collapse to a single "unverifiable" warning
+    # instead of crying wolf on every skill.
+    if mismatches and not matches:
+        out.append(
+            make_finding(
+                "lockfile-drift", "warning", [],
+                "skills-lock.json hashes use an algorithm drskill cannot "
+                "reproduce; hash-drift detection is disabled for this "
+                "lockfile (missing-skill detection still active)",
+                harnesses=sorted(world.harnesses),
+                extra_key="unverifiable",
+                fix_commands=[
+                    "npx skills sync  # reinstall to a known-good state if you suspect drift"
+                ],
+            )
+        )
+    else:
+        for name, c in mismatches:
+            out.append(
+                make_finding(
+                    "lockfile-drift", "warning", [c],
+                    f"'{name}' was modified outside `npx skills` — likely a "
+                    "`gh skill update` or a hand edit; the lockfile no longer matches",
+                    fix_commands=[
+                        "npx skills sync  # restore the locked version",
+                        f"npx skills update {shlex.quote(name)}  # or re-pin the new content",
+                    ],
+                )
+            )
+    return out

drskill/checks/shadowing.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import shlex
+
+from drskill.checks import check, make_finding
+from drskill.ledger import Config
+from drskill.models import Finding
+from drskill.resolution import World
+
+
+@check("name-shadow")
+def name_shadow(world: World, config: Config) -> list[Finding]:
+    out = []
+    for hid in world.harnesses:
+        for c, d in world.harness_loads(hid):
+            if d.shadowed_by is None:
+                continue
+            winner = world.contributors[d.shadowed_by]
+            wdep = next(x for x in winner.deployments if x.harness == hid)
+            out.append(
+                make_finding(
+                    "name-shadow", "warning", [winner, c],
+                    f"two skills named '{c.name}': the {wdep.scope} copy at "
+                    f"{wdep.path} wins by search order and shadows {d.path}",
+                    harnesses=[hid],
+                    extra_key=winner.id,
+                    fix_commands=[
+                        f"Remove or rename the shadowed copy: {shlex.quote(str(d.path))}",
+                    ],
+                )
+            )
+    return out
+
+
+@check("double-load")
+def double_load(world: World, config: Config) -> list[Finding]:
+    out = []
+    for hid in world.harnesses:
+        # Key by content hash, then by contributor id, so that a single
+        # contributor reached twice through the same real path (e.g. one
+        # search directory symlinked into another) collapses to one entry
+        # instead of looking like two distinct copies.
+        by_hash: dict[str, dict[str, tuple]] = {}
+        for c, d in world.harness_loads(hid):
+            if d.shadowed_by is None:
+                by_hash.setdefault(c.content_hash, {}).setdefault(c.id, (c, d))
+        for loads in by_hash.values():
+            if len(loads) < 2:
+                continue
+            contributors = [c for c, _ in loads.values()]
+            paths = ", ".join(str(d.path) for _, d in loads.values())
+            quoted_paths = ", ".join(shlex.quote(str(d.path)) for _, d in loads.values())
+            display = world.harnesses[hid].display_name
+            out.append(
+                make_finding(
+                    "double-load", "error", contributors,
+                    f"{display} loads the same skill "
+                    f"'{contributors[0].name}' {len(loads)} times: {paths}",
+                    harnesses=[hid],
+                    extra_key=hid,
+                    fix_commands=[f"Remove all but one copy ({quoted_paths})"],
+                )
+            )
+    return out

drskill/checks/spec.py

@@ -0,0 +1,108 @@
+"""Spec-compliance checks. Only SKILL.md contributors are checked; bare
+.md skills (pi root files) are not SKILL.md spec artifacts."""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+
+from drskill.checks import check, make_finding
+from drskill.ledger import Config
+from drskill.models import Finding
+from drskill.resolution import World
+
+DESCRIPTION_MAX = 1024
+
+
+def _skill_md_contributors(world: World):
+    return [c for c in world.contributors.values() if Path(c.id).name == "SKILL.md"]
+
+
+@check("spec-invalid-frontmatter")
+def spec_invalid_frontmatter(world: World, config: Config) -> list[Finding]:
+    return [
+        make_finding(
+            "spec-invalid-frontmatter", "error", [c],
+            f"'{c.name}': frontmatter does not parse as YAML ({c.id})",
+            fix_commands=[f"Fix the YAML frontmatter in {shlex.quote(c.id)}"],
+        )
+        for c in _skill_md_contributors(world)
+        if not c.frontmatter_valid
+    ]
+
+
+@check("spec-name-mismatch")
+def spec_name_mismatch(world: World, config: Config) -> list[Finding]:
+    out = []
+    for c in _skill_md_contributors(world):
+        folder = Path(c.id).parent.name
+        if c.frontmatter_valid and c.name != folder:
+            out.append(
+                make_finding(
+                    "spec-name-mismatch", "error", [c],
+                    f"frontmatter name '{c.name}' does not match folder '{folder}'",
+                    fix_commands=[
+                        f"Rename the folder to {shlex.quote(c.name)} or set "
+                        f"'name: {shlex.quote(folder)}' in {shlex.quote(c.id)}"
+                    ],
+                )
+            )
+    return out
+
+
+@check("spec-missing-description")
+def spec_missing_description(world: World, config: Config) -> list[Finding]:
+    return [
+        make_finding(
+            "spec-missing-description", "error", [c],
+            f"'{c.name}' has no description; the router cannot route to it",
+            fix_commands=[
+                f"Add a 'description:' with a clear 'use when' condition to {shlex.quote(c.id)}"
+            ],
+        )
+        for c in _skill_md_contributors(world)
+        if c.frontmatter_valid and not c.routing_text.strip()
+    ]
+
+
+@check("spec-description-too-long")
+def spec_description_too_long(world: World, config: Config) -> list[Finding]:
+    return [
+        make_finding(
+            "spec-description-too-long", "error", [c],
+            f"'{c.name}' description is {len(c.routing_text)} chars (max {DESCRIPTION_MAX})",
+            fix_commands=[
+                f"Shorten the description in {shlex.quote(c.id)} to {DESCRIPTION_MAX} chars or fewer"
+            ],
+        )
+        for c in _skill_md_contributors(world)
+        if len(c.routing_text) > DESCRIPTION_MAX
+    ]
+
+
+def _has_angle_bracket(value: object) -> bool:
+    """Look for '<' or '>' in parsed frontmatter values, not the raw YAML
+    text. Raw text also contains YAML's own syntax characters (e.g. the
+    folded block scalar indicator in 'description: >-'), which are not
+    frontmatter values and would false-positive on ordinary multi-line
+    descriptions."""
+    if isinstance(value, str):
+        return "<" in value or ">" in value
+    if isinstance(value, dict):
+        return any(_has_angle_bracket(v) for v in value.values())
+    if isinstance(value, list):
+        return any(_has_angle_bracket(v) for v in value)
+    return False
+
+
+@check("frontmatter-angle-brackets")
+def frontmatter_angle_brackets(world: World, config: Config) -> list[Finding]:
+    return [
+        make_finding(
+            "frontmatter-angle-brackets", "warning", [c],
+            f"'{c.name}' frontmatter contains angle brackets, a spec-flagged injection vector",
+            fix_commands=[f"Remove '<' and '>' from the frontmatter of {shlex.quote(c.id)}"],
+        )
+        for c in _skill_md_contributors(world)
+        if c.frontmatter_valid and _has_angle_bracket(c.frontmatter)
+    ]