Oleks
440 lines
16 KiB
Python
Executable File
440 lines
16 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
"""Static pass over a Claude Code plugin's definitions -> one JSON document.
|
|
|
|
Usage: plugin-inventory <path|name> [--json] [--catalog PATH]
|
|
|
|
Reads a plugin's skills/, agents/, hooks/, and bin/, and reports the static
|
|
signals defined in design/spec.md §5.1 (verb ratios, procedural density,
|
|
duplicated command blocks, rule tables, script coverage, tool-allowlist
|
|
shape). Stdlib only, offline, no PyYAML — this file itself is the plugin's
|
|
own thesis (FR-8): reading a plugin's structure is a pure-script step by
|
|
every one of the five determinism tests in references/boundary-rubric.md.
|
|
|
|
No --json: pretty-printed (indent=2), for humans.
|
|
--json: compact single line, for piping into bin/offload-scan or tests.
|
|
"""
|
|
import argparse
|
|
import glob
|
|
import json
|
|
import os
|
|
import re
|
|
import sys
|
|
|
|
PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
|
DEFAULT_CATALOG = os.path.join(PLUGIN_ROOT, "references", "signals-catalog.md")
|
|
CACHE_GLOB = os.path.expanduser("~/.claude/plugins/cache/*/{name}/*/")
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# signals-catalog.md loader
|
|
# --------------------------------------------------------------------------
|
|
|
|
KNOWN_SECTIONS = {"script-verbs", "judgment-verbs", "mechanical-tools", "thresholds"}
|
|
|
|
|
|
def load_catalog(path):
|
|
"""Reads only the fenced code block immediately following each
|
|
recognized `## <section>` heading; everything else is prose for humans
|
|
and is never parsed (see references/signals-catalog.md's own header for
|
|
why: markdown and a hand-rolled comment syntax collide on bare `#`)."""
|
|
with open(path, encoding="utf-8") as f:
|
|
text = f.read()
|
|
|
|
sections = {}
|
|
heading_re = re.compile(r"^##\s+([a-z-]+)\s*$", re.MULTILINE)
|
|
for m in heading_re.finditer(text):
|
|
name = m.group(1)
|
|
if name not in KNOWN_SECTIONS:
|
|
continue
|
|
block = re.search(r"```\S*\n(.*?)```", text[m.end():], re.DOTALL)
|
|
if not block:
|
|
continue
|
|
body = block.group(1)
|
|
if name == "thresholds":
|
|
values = {}
|
|
for raw in body.split("\n"):
|
|
line = raw.split("#", 1)[0].strip()
|
|
if ":" in line:
|
|
k, v = line.split(":", 1)
|
|
values[k.strip()] = float(v.strip())
|
|
sections[name] = values
|
|
else:
|
|
items = set()
|
|
for raw in body.split("\n"):
|
|
for item in raw.split(","):
|
|
item = item.strip()
|
|
if re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", item):
|
|
items.add(item)
|
|
sections[name] = items
|
|
missing = KNOWN_SECTIONS - sections.keys()
|
|
if missing:
|
|
sys.exit(f"error: {path} is missing section(s): {', '.join(sorted(missing))}")
|
|
return sections
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# target resolution
|
|
# --------------------------------------------------------------------------
|
|
|
|
def semver_key(dirname):
|
|
m = re.match(r"^(\d+)\.(\d+)\.(\d+)", dirname)
|
|
return tuple(int(g) for g in m.groups()) if m else (0, 0, 0)
|
|
|
|
|
|
def resolve_target(target):
|
|
if os.sep in target or os.path.isdir(target):
|
|
path = os.path.abspath(target)
|
|
if not os.path.isdir(path):
|
|
sys.exit(f"error: no such directory: {path}")
|
|
return path, "path"
|
|
|
|
candidates = []
|
|
for entry in glob.glob(CACHE_GLOB.format(name=re.escape(target)).replace(r"\*", "*")):
|
|
if os.path.exists(os.path.join(entry, ".orphaned_at")):
|
|
continue
|
|
candidates.append(entry.rstrip("/"))
|
|
if not candidates:
|
|
sys.exit(f"error: no cached plugin found for name {target!r} "
|
|
f"(and not a directory)")
|
|
candidates.sort(key=lambda p: semver_key(os.path.basename(p)))
|
|
return candidates[-1], "oleks-local"
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# frontmatter (no PyYAML — this environment's SKILL.md/agent.md frontmatter
|
|
# is a narrow subset: scalar `key: value` lines and `key: |` block scalars)
|
|
# --------------------------------------------------------------------------
|
|
|
|
def parse_frontmatter(text):
|
|
if not text.startswith("---"):
|
|
return {}, text
|
|
lines = text.split("\n")
|
|
if lines[0].strip() != "---":
|
|
return {}, text
|
|
end = None
|
|
for i in range(1, len(lines)):
|
|
if lines[i].strip() == "---":
|
|
end = i
|
|
break
|
|
if end is None:
|
|
return {}, text
|
|
meta = {}
|
|
i = 1
|
|
while i < end:
|
|
line = lines[i]
|
|
if not line.strip() or line.lstrip().startswith("#"):
|
|
i += 1
|
|
continue
|
|
m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
|
|
if not m:
|
|
i += 1
|
|
continue
|
|
key, val = m.group(1), m.group(2).strip()
|
|
if val in ("|", "|-", ">", ">-"):
|
|
block = []
|
|
i += 1
|
|
while i < end and (lines[i].startswith(" ") or lines[i].startswith("\t") or not lines[i].strip()):
|
|
block.append(lines[i].strip())
|
|
i += 1
|
|
meta[key] = " ".join(b for b in block if b)
|
|
continue
|
|
meta[key] = val.strip('"\'')
|
|
i += 1
|
|
body = "\n".join(lines[end + 1:])
|
|
return meta, body
|
|
|
|
|
|
def split_list(value):
|
|
if not value:
|
|
return []
|
|
return [v.strip() for v in value.split(",") if v.strip()]
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# signal computation
|
|
# --------------------------------------------------------------------------
|
|
|
|
def verb_counts(body, verbs):
|
|
total = 0
|
|
for verb in verbs:
|
|
total += len(re.findall(r"\b" + re.escape(verb) + r"\b", body, re.IGNORECASE))
|
|
return total
|
|
|
|
|
|
def procedural_density(body):
|
|
list_item_re = re.compile(r"^\s*(?:\d+[.)]|[-*])\s+.+$", re.MULTILINE)
|
|
items = list_item_re.findall(body)
|
|
if not items:
|
|
return 0.0
|
|
with_command = sum(1 for item in items if "`" in item)
|
|
return round(with_command / len(items), 3)
|
|
|
|
|
|
def extract_command_blocks(body):
|
|
blocks = re.findall(r"```(?:bash|sh|shell)?\n(.*?)```", body, re.DOTALL)
|
|
sigs = {}
|
|
for block in blocks:
|
|
first_line = next((ln.strip() for ln in block.splitlines() if ln.strip()), None)
|
|
if not first_line:
|
|
continue
|
|
sig = re.sub(r"\s+", " ", first_line)
|
|
sigs[sig] = sigs.get(sig, 0) + 1
|
|
return [{"sig": sig, "count": count} for sig, count in sorted(sigs.items())]
|
|
|
|
|
|
def count_rule_tables(body):
|
|
return len(re.findall(r"^\|.+\|\s*\n\|[\s:|-]+\|\s*$", body, re.MULTILINE))
|
|
|
|
|
|
def find_references(body, references_dir):
|
|
if not os.path.isdir(references_dir):
|
|
return []
|
|
known = set(os.listdir(references_dir))
|
|
found = set()
|
|
for m in re.finditer(r"([A-Za-z0-9_-]+\.md)", body):
|
|
if m.group(1) in known:
|
|
found.add(m.group(1))
|
|
return sorted(found)
|
|
|
|
|
|
def wc(text):
|
|
return len(text.split())
|
|
|
|
|
|
# --------------------------------------------------------------------------
|
|
# per-plugin walk
|
|
# --------------------------------------------------------------------------
|
|
|
|
def walk_skills(plugin_path, catalog):
|
|
"""Returns (skills, bodies) — bodies maps skill name -> body text, kept
|
|
out of the JSON output but needed by build_aggregate for drift detection."""
|
|
skills = []
|
|
bodies = {}
|
|
skills_dir = os.path.join(plugin_path, "skills")
|
|
if not os.path.isdir(skills_dir):
|
|
return skills, bodies
|
|
for name in sorted(os.listdir(skills_dir)):
|
|
skill_md = os.path.join(skills_dir, name, "SKILL.md")
|
|
if not os.path.isfile(skill_md):
|
|
continue
|
|
with open(skill_md, encoding="utf-8") as f:
|
|
text = f.read()
|
|
meta, body = parse_frontmatter(text)
|
|
script_v = verb_counts(body, catalog["script-verbs"])
|
|
judgment_v = verb_counts(body, catalog["judgment-verbs"])
|
|
ratio = round(script_v / (script_v + judgment_v), 3) if (script_v + judgment_v) else 0.0
|
|
skill_name = meta.get("name", name)
|
|
bodies[skill_name] = body
|
|
skills.append({
|
|
"name": skill_name,
|
|
"description_words": wc(meta.get("description", "")),
|
|
"body_words": wc(body),
|
|
"allowed_tools": split_list(meta.get("allowed-tools", meta.get("tools", ""))),
|
|
"procedural_density": procedural_density(body),
|
|
"script_verbs": script_v,
|
|
"judgment_verbs": judgment_v,
|
|
"verb_ratio": ratio,
|
|
"command_blocks": extract_command_blocks(body),
|
|
"rule_tables": count_rule_tables(body),
|
|
"references": find_references(body, os.path.join(skills_dir, name, "references")),
|
|
})
|
|
return skills, bodies
|
|
|
|
|
|
def walk_agents(plugin_path, catalog):
|
|
agents = []
|
|
agents_dir = os.path.join(plugin_path, "agents")
|
|
if not os.path.isdir(agents_dir):
|
|
return agents
|
|
mechanical = catalog["mechanical-tools"]
|
|
for fname in sorted(os.listdir(agents_dir)):
|
|
if not fname.endswith(".md"):
|
|
continue
|
|
with open(os.path.join(agents_dir, fname), encoding="utf-8") as f:
|
|
text = f.read()
|
|
meta, body = parse_frontmatter(text)
|
|
tools = split_list(meta.get("tools", ""))
|
|
mech = sum(1 for t in tools if t in mechanical)
|
|
agents.append({
|
|
"name": meta.get("name", fname[:-3]),
|
|
"model": meta.get("model", ""),
|
|
"tools": tools,
|
|
"body_words": wc(body),
|
|
"mechanical_tool_share": round(mech / len(tools), 3) if tools else 0.0,
|
|
})
|
|
return agents
|
|
|
|
|
|
def walk_hooks(plugin_path):
|
|
"""Returns (hooks, texts) — texts maps hook filename -> file content, kept
|
|
out of the JSON output but needed by build_aggregate for drift detection."""
|
|
hooks = []
|
|
texts = {}
|
|
hooks_dir = os.path.join(plugin_path, "hooks")
|
|
if not os.path.isdir(hooks_dir):
|
|
return hooks, texts
|
|
hooks_json = os.path.join(plugin_path, ".claude-plugin", "hooks.json")
|
|
events_by_file = {}
|
|
if os.path.isfile(hooks_json):
|
|
try:
|
|
with open(hooks_json, encoding="utf-8") as f:
|
|
data = json.load(f)
|
|
for event, entries in (data.get("hooks") or {}).items():
|
|
for entry in entries:
|
|
for hook in entry.get("hooks", []):
|
|
cmd = hook.get("command", "")
|
|
m = re.search(r"([\w.-]+\.sh)\b", cmd)
|
|
if m:
|
|
events_by_file[m.group(1)] = event
|
|
except (json.JSONDecodeError, OSError):
|
|
pass
|
|
for fname in sorted(os.listdir(hooks_dir)):
|
|
fpath = os.path.join(hooks_dir, fname)
|
|
if not os.path.isfile(fpath):
|
|
continue
|
|
with open(fpath, encoding="utf-8", errors="ignore") as f:
|
|
content = f.read()
|
|
texts[fname] = content
|
|
hooks.append({"file": fname, "event": events_by_file.get(fname, "unknown"),
|
|
"loc": content.count("\n") + 1})
|
|
return hooks, texts
|
|
|
|
|
|
def detect_lang(fpath):
|
|
try:
|
|
with open(fpath, encoding="utf-8", errors="ignore") as f:
|
|
first = f.readline()
|
|
except OSError:
|
|
return "unknown"
|
|
if first.startswith("#!"):
|
|
if "python" in first:
|
|
return "python"
|
|
if "bash" in first:
|
|
return "bash"
|
|
if "sh" in first:
|
|
return "sh"
|
|
if fpath.endswith(".py"):
|
|
return "python"
|
|
return "unknown"
|
|
|
|
|
|
def walk_scripts(plugin_path):
|
|
scripts = []
|
|
bin_dir = os.path.join(plugin_path, "bin")
|
|
if not os.path.isdir(bin_dir):
|
|
return scripts
|
|
for fname in sorted(os.listdir(bin_dir)):
|
|
fpath = os.path.join(bin_dir, fname)
|
|
if not os.path.isfile(fpath):
|
|
continue
|
|
with open(fpath, encoding="utf-8", errors="ignore") as f:
|
|
loc = sum(1 for _ in f)
|
|
scripts.append({"file": f"bin/{fname}", "loc": loc, "lang": detect_lang(fpath)})
|
|
return scripts
|
|
|
|
|
|
def distinctive_tokens(text):
|
|
"""Identifier-shaped tokens only (snake_case, SCREAMING_CASE, or
|
|
file/tool names with an underscore or a dot) — deliberately NOT plain
|
|
English words, which overlap constantly between topically-related prose
|
|
and produce false positives (e.g. every worktree-discipline skill shares
|
|
"already"/"session"/"branch" with every worktree-discipline hook,
|
|
regardless of whether any actual logic is restated). Real drift shows up
|
|
as the same *specific* identifier — an env var, a function name, a
|
|
literal filename — named in both places."""
|
|
snake = re.findall(r"\b[a-z][a-z0-9]*(?:_[a-z0-9]+){1,}\b", text)
|
|
screaming = re.findall(r"\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+){1,}\b", text)
|
|
dotted = re.findall(r"\b[a-zA-Z][a-zA-Z0-9_-]{3,}\.(?:sh|py|json|md)\b", text)
|
|
return {t.lower() for t in snake + screaming + dotted}
|
|
|
|
|
|
def build_aggregate(skills, agents, hooks, scripts, catalog, bodies=None, hook_texts=None):
|
|
skill_body_words = sum(s["body_words"] for s in skills)
|
|
agent_body_words = sum(a["body_words"] for a in agents)
|
|
script_loc = sum(s["loc"] for s in scripts) + sum(h["loc"] for h in hooks)
|
|
total_words = skill_body_words + agent_body_words
|
|
coverage = round(script_loc / total_words, 3) if total_words else 0.0
|
|
|
|
sig_skills = {}
|
|
for skill in skills:
|
|
for block in skill["command_blocks"]:
|
|
sig_skills.setdefault(block["sig"], set()).add(skill["name"])
|
|
min_skills = int(catalog["thresholds"].get("duplicate_block_min_skills", 2))
|
|
duplicated = [
|
|
{"sig": sig, "skills": sorted(names)}
|
|
for sig, names in sorted(sig_skills.items())
|
|
if len(names) >= min_skills
|
|
]
|
|
|
|
drift = []
|
|
bodies = bodies or {}
|
|
hook_texts = hook_texts or {}
|
|
min_shared = int(catalog["thresholds"].get("hook_prose_drift_min_shared_tokens", 3))
|
|
for hook in hooks:
|
|
hook_tokens = distinctive_tokens(hook_texts.get(hook["file"], ""))
|
|
if not hook_tokens:
|
|
continue
|
|
for skill_name, body in bodies.items():
|
|
shared = hook_tokens & distinctive_tokens(body)
|
|
if len(shared) >= min_shared:
|
|
drift.append({
|
|
"hook": hook["file"],
|
|
"skill": skill_name,
|
|
"shared_tokens": sorted(shared)[:10],
|
|
})
|
|
|
|
return {
|
|
"skill_body_words": skill_body_words,
|
|
"agent_body_words": agent_body_words,
|
|
"script_loc": script_loc,
|
|
"script_coverage": coverage,
|
|
"duplicated_command_blocks": duplicated,
|
|
"hook_prose_drift": drift,
|
|
}
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(prog="plugin-inventory")
|
|
parser.add_argument("target", help="plugin directory path, or a bare name to resolve from the plugin cache")
|
|
parser.add_argument("--json", action="store_true", help="compact single-line JSON instead of pretty-printed")
|
|
parser.add_argument("--catalog", default=DEFAULT_CATALOG, help="path to signals-catalog.md")
|
|
args = parser.parse_args()
|
|
|
|
catalog = load_catalog(args.catalog)
|
|
plugin_path, source = resolve_target(args.target)
|
|
|
|
manifest_path = os.path.join(plugin_path, ".claude-plugin", "plugin.json")
|
|
manifest = {}
|
|
if os.path.isfile(manifest_path):
|
|
with open(manifest_path, encoding="utf-8") as f:
|
|
manifest = json.load(f)
|
|
|
|
skills, bodies = walk_skills(plugin_path, catalog)
|
|
agents = walk_agents(plugin_path, catalog)
|
|
hooks, hook_texts = walk_hooks(plugin_path)
|
|
scripts = walk_scripts(plugin_path)
|
|
aggregate = build_aggregate(skills, agents, hooks, scripts, catalog, bodies, hook_texts)
|
|
|
|
doc = {
|
|
"plugin": {
|
|
"name": manifest.get("name", os.path.basename(plugin_path)),
|
|
"version": manifest.get("version", "unknown"),
|
|
"source": source,
|
|
"path": plugin_path,
|
|
},
|
|
"skills": skills,
|
|
"agents": agents,
|
|
"hooks": hooks,
|
|
"scripts": scripts,
|
|
"aggregate": aggregate,
|
|
}
|
|
|
|
if args.json:
|
|
print(json.dumps(doc))
|
|
else:
|
|
print(json.dumps(doc, indent=2))
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|