drskill-core 0.3.0__py3-none-any.whl

drskill/checks/__init__.py

@@ -0,0 +1,82 @@
+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 = "",
+    texts: list[str] | None = None,
+) -> str:
+    """Fingerprint over the material the check judged. By default that is
+    each contributor's whole normalized content; a check that only judged a
+    slice (e.g. descriptions) passes `texts` so acks survive unrelated edits."""
+    if texts is None:
+        parts = sorted(c.content_hash for c in contributors)
+    else:
+        parts = sorted(hashlib.sha256(t.encode()).hexdigest() for t in texts)
+    payload = "|".join([check_id, *parts, 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 = "",
+    fingerprint_texts: list[str] | None = None,
+) -> 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, fingerprint_texts),
+    )
+
+
+def run_all(world: World, config: Config) -> list[Finding]:
+    # Import registers every check module exactly once.
+    from drskill.checks import budget, duplicates, filesystem, heuristics, injection, 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/heuristics.py

@@ -0,0 +1,249 @@
+"""Tier 2 heuristic checks: deterministic, threshold-tuned, always ack-able."""
+
+from __future__ import annotations
+
+import re
+from itertools import combinations
+from pathlib import Path
+
+from drskill import text
+from drskill.checks import check, make_finding
+from drskill.checks.duplicates import estimate, shingles, signature
+from drskill.ledger import Config
+from drskill.models import Contributor, Finding
+from drskill.resolution import World
+
+
+def _skill_md(world: World) -> list[Contributor]:
+    return [
+        c
+        for c in world.contributors.values()
+        if Path(c.id).name == "SKILL.md" and c.frontmatter_valid
+    ]
+
+
+@check("missing-activation")
+def missing_activation(world: World, config: Config) -> list[Finding]:
+    offenders = sorted(
+        (
+            c for c in _skill_md(world)
+            if c.routing_text.strip() and not text.has_activation(c.routing_text)
+        ),
+        key=lambda c: c.name,
+    )
+    if not offenders:
+        return []
+    n = len(offenders)
+    head = (
+        f"{n} skill{'s' if n != 1 else ''} never "
+        f"{'say' if n != 1 else 'says'} when to use "
+        f"{'them' if n != 1 else 'it'}; the router has to guess:"
+    )
+    member_lines = "".join(f"\n        {c.name}: {c.id}" for c in offenders)
+    return [
+        make_finding(
+            "missing-activation", "warning", offenders,
+            head + member_lines,
+            fix_commands=[
+                "Start each description with a condition, e.g. 'Use when ...'"
+            ],
+            fingerprint_texts=[f"{c.name}\n{c.routing_text}" for c in offenders],
+        )
+    ]
+
+
+_IMPERATIVE = re.compile(r"\b(always|never)\s+((?:\w+[ \t]){0,3}\w+)", re.IGNORECASE)
+
+# Unlike text.STOPWORDS, verbs stay: "use tabs" needs "use". Only glue words
+# and location/degree adverbs are dropped.
+# Corpus tuning 2026-07-20: set-intersection matching fired 119 times and
+# set-containment 248 times on the hermes corpus (179 skills), almost all
+# single shared verbs. The shipped rule is strict verb+object bigram
+# equality: the first two non-glue tokens after always/never must match
+# exactly. Very low recall, near-zero noise.
+_IMPERATIVE_DROP = frozenset(
+    """a an the and or for in on at to of with from by anywhere everywhere
+    nowhere here there always never all any this that these those it its
+    your you""".split()
+)
+
+
+_SNIPPET_MAX = 100
+
+
+def _snippet(body: str, start: int, end: int) -> str:
+    line_start = body.rfind("\n", 0, start) + 1
+    line_end = body.find("\n", end)
+    if line_end == -1:
+        line_end = len(body)
+    line = body[line_start:line_end].strip()
+    if len(line) > _SNIPPET_MAX:
+        line = line[: _SNIPPET_MAX - 1].rstrip() + "…"
+    return line
+
+
+def _imperative_phrases(c: Contributor) -> dict[str, dict[tuple[str, str], str]]:
+    """kind -> {verb+object bigram: snippet of the first line saying it}."""
+    out: dict[str, dict[tuple[str, str], str]] = {"always": {}, "never": {}}
+    for m in _IMPERATIVE.finditer(c.body):
+        toks = [t for t in text.tokenize(m.group(2)) if t not in _IMPERATIVE_DROP]
+        if len(toks) >= 2:
+            out[m.group(1).lower()].setdefault(
+                (toks[0], toks[1]), _snippet(c.body, m.start(), m.end())
+            )
+    return out
+
+
+@check("opposing-imperatives")
+def opposing_imperatives(world: World, config: Config) -> list[Finding]:
+    cs = _skill_md(world)
+    phrases = {c.id: _imperative_phrases(c) for c in cs}
+    out = []
+    for a, b in combinations(cs, 2):
+        seen: set[str] = set()
+        for kind_a, kind_b in (("always", "never"), ("never", "always")):
+            for pair in sorted(set(phrases[a.id][kind_a]) & set(phrases[b.id][kind_b])):
+                phrase = " ".join(pair)
+                if phrase in seen:
+                    continue
+                seen.add(phrase)
+                lines = [
+                    f"'{a.name}' and '{b.name}' give opposite orders about "
+                    f"'{phrase}':",
+                    f'        {a.name}: "{phrases[a.id][kind_a][pair]}"',
+                    f"            {a.id}",
+                    f'        {b.name}: "{phrases[b.id][kind_b][pair]}"',
+                    f"            {b.id}",
+                    "        (exact-match check; paraphrased contradictions are"
+                    " not detected)",
+                ]
+                out.append(
+                    make_finding(
+                        "opposing-imperatives", "warning", [a, b],
+                        "\n".join(lines),
+                        fix_commands=[
+                            "Align the two instructions, or scope each to its own condition"
+                        ],
+                        extra_key=phrase,
+                        fingerprint_texts=[f"{a.name}\n{a.body}", f"{b.name}\n{b.body}"],
+                    )
+                )
+    return out
+
+
+def _is_duplicate_pair(
+    a: Contributor,
+    b: Contributor,
+    near_threshold: float,
+    sigs: dict[str, list[int]],
+) -> bool:
+    if a.content_hash == b.content_hash:
+        return True
+    return estimate(sigs[a.id], sigs[b.id]) >= near_threshold
+
+
+@check("description-overlap")
+def description_overlap(world: World, config: Config) -> list[Finding]:
+    cs = [c for c in _skill_md(world) if c.routing_text.strip()]
+    vecs = {c.id: text.shingle_vector(c.routing_text) for c in cs}
+    sigs = {c.id: signature(shingles(f"{c.routing_text}\n{c.body}")) for c in cs}
+
+    # Collapse duplicate groups to one representative each BEFORE clustering.
+    # Skipping only the direct edge is not enough: a carved-out duplicate
+    # pair could re-enter one cluster through a third skill that overlaps
+    # both (found in review). Duplicates are the stronger diagnosis and are
+    # reported by their own checks.
+    rep_parent = {c.id: c.id for c in cs}
+
+    def rep_find(x: str) -> str:
+        while rep_parent[x] != x:
+            rep_parent[x] = rep_parent[rep_parent[x]]
+            x = rep_parent[x]
+        return x
+
+    for a, b in combinations(cs, 2):
+        # Same-name pairs are diverged-copies territory; duplicate pairs are
+        # exact/near-duplicate territory. Both collapse to one representative.
+        if a.name == b.name or _is_duplicate_pair(
+            a, b, config.thresholds.near_duplicate, sigs
+        ):
+            rep_parent[rep_find(a.id)] = rep_find(b.id)
+    by_id = {c.id: c for c in cs}
+    reps = [by_id[cid] for cid in sorted({rep_find(c.id) for c in cs})]
+
+    parent = {c.id: c.id for c in reps}
+
+    def find(x: str) -> str:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    for a, b in combinations(reps, 2):
+        if text.cosine(vecs[a.id], vecs[b.id]) >= config.thresholds.description_overlap:
+            parent[find(a.id)] = find(b.id)
+
+    clusters: dict[str, list[Contributor]] = {}
+    for c in reps:
+        clusters.setdefault(find(c.id), []).append(c)
+
+    out = []
+    for members in clusters.values():
+        if len(members) < 2:
+            continue
+        members = sorted(members, key=lambda c: c.name)
+        phrases = text.shared_phrases([m.routing_text for m in members])[:3]
+        if phrases:
+            quoted = ", ".join(f"'{p}'" for p in phrases)
+            claim = f" all claim {quoted}"
+        else:
+            claim = " have near-identical descriptions"
+        # Same-name members collapse to one representative above, so names
+        # inside a cluster are unique and need no path disambiguation.
+        names = ", ".join(m.name for m in members)
+        member_lines = "".join(f"\n        {m.name}: {m.id}" for m in members)
+        out.append(
+            make_finding(
+                "description-overlap", "warning", members,
+                f"{len(members)} skills ({names}){claim}; "
+                "none states an exclusive condition, so routing between them "
+                f"is a coin flip{member_lines}",
+                fix_commands=[
+                    "Give each description an exclusive 'use when' condition the others lack"
+                ],
+                fingerprint_texts=[f"{m.name}\n{m.routing_text}" for m in members],
+            )
+        )
+    return out
+
+
+@check("generic-description")
+def generic_description(world: World, config: Config) -> list[Finding]:
+    offenders = []
+    for c in sorted(_skill_md(world), key=lambda c: c.name):
+        if not c.routing_text.strip():
+            continue
+        distinct = {
+            t for t in text.content_tokens(c.routing_text)
+            if t not in text.GENERIC_VOCAB
+        }
+        if len(distinct) < config.thresholds.generic_min_distinct_tokens:
+            offenders.append(c)
+    if not offenders:
+        return []
+    n = len(offenders)
+    head = (
+        f"{n} skill description{'s have' if n != 1 else ' has'} "
+        "no distinguishing words to route on:"
+    )
+    member_lines = "".join(f"\n        {c.name}: {c.id}" for c in offenders)
+    return [
+        make_finding(
+            "generic-description", "warning", offenders,
+            head + member_lines,
+            fix_commands=[
+                "Name the concrete inputs, outputs, or domain in each description"
+            ],
+            fingerprint_texts=[f"{c.name}\n{c.routing_text}" for c in offenders],
+        )
+    ]