@icntswm/skillcheck 0.1.0

package/dist/confusion.js

@@ -0,0 +1,45 @@
+/**
+ * Confusion pairs over failed routing runs: which expected skill was missed
+ * and what the agent loaded instead. Error runs are skipped (they say nothing
+ * about routing); so are runs whose only failures concern forbid/none, since
+ * the expected-label rules below produce no label for them.
+ */
+export function confusion(results) {
+    const counts = new Map();
+    for (const res of results) {
+        for (const run of res.runs) {
+            if (run.ok || run.error)
+                continue;
+            for (const expected of expectedLabels(res.case, run.loaded)) {
+                for (const got of gotLabels(res.case, run.loaded)) {
+                    const key = `${expected}\u0000${got}`;
+                    const pair = counts.get(key);
+                    if (pair)
+                        pair.count++;
+                    else
+                        counts.set(key, { expected, got, count: 1 });
+                }
+            }
+        }
+    }
+    return [...counts.values()].sort((a, b) => b.count - a.count || a.expected.localeCompare(b.expected) || a.got.localeCompare(b.got));
+}
+/** A missed expectation; expect_any collapses to one "a|b" label. */
+function expectedLabels(c, loaded) {
+    const labels = [];
+    for (const name of c.expect)
+        if (!loaded.includes(name))
+            labels.push(name);
+    if (c.expect_any.length > 0 && !c.expect_any.some((name) => loaded.includes(name))) {
+        labels.push(c.expect_any.join("|"));
+    }
+    if (c.first && loaded[0] !== c.first && !labels.includes(c.first))
+        labels.push(c.first);
+    return labels;
+}
+/** Loaded skills nobody asked for; "(nothing)" when the agent loaded none. */
+function gotLabels(c, loaded) {
+    const allowed = new Set([...c.expect, ...c.expect_any, ...(c.first ? [c.first] : [])]);
+    const unexpected = loaded.filter((name) => !allowed.has(name));
+    return unexpected.length > 0 ? unexpected : ["(nothing)"];
+}

package/dist/describe.js

@@ -0,0 +1,282 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+/** Config roots to scan, earlier first: user config, then project (project overrides).
+ * An explicit configDir beats CLAUDE_CONFIG_DIR. */
+export function skillRoots(opts) {
+    const home = opts?.home ?? os.homedir();
+    const cwd = opts?.cwd ?? process.cwd();
+    const configRoot = opts?.configDir || process.env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
+    return [configRoot, path.join(cwd, ".claude")];
+}
+/** Skill dir names under dir: subdirs with a SKILL.md, symlinks followed. */
+export function skillDirNames(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        // statSync follows symlinks, so linked skill dirs count too
+        try {
+            if (fs.statSync(path.join(dir, entry)).isDirectory()
+                && fs.statSync(path.join(dir, entry, "SKILL.md")).isFile()) {
+                out.push(entry);
+            }
+        }
+        catch {
+            // not a skill dir
+        }
+    }
+    return out;
+}
+/** Command names under dir: top-level .md files. */
+export function commandNames(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".md"))
+            continue;
+        try {
+            if (fs.statSync(path.join(dir, entry)).isFile())
+                out.push(entry.slice(0, -3));
+        }
+        catch {
+            // not a regular file
+        }
+    }
+    return out;
+}
+export function loadSkillDocs(opts) {
+    const cwd = opts?.cwd ?? process.cwd();
+    const byName = new Map();
+    const roots = skillRoots(opts);
+    for (const root of roots) {
+        const inRoot = new Map();
+        for (const name of commandNames(path.join(root, "commands"))) {
+            const file = path.join(root, "commands", `${name}.md`);
+            inRoot.set(name, { name, kind: "command", file, description: readDescription(file), plugin: null });
+        }
+        // within one root a skill beats a command with the same name
+        for (const name of skillDirNames(path.join(root, "skills"))) {
+            const file = path.join(root, "skills", name, "SKILL.md");
+            inRoot.set(name, { name, kind: "skill", file, description: readDescription(file), plugin: null });
+        }
+        // a later root overrides an earlier one
+        for (const [name, doc] of inRoot)
+            byName.set(name, doc);
+    }
+    // plugin docs carry a `plugin:` prefix, so they never collide with the above
+    for (const doc of pluginDocs(roots[0], cwd)) {
+        if (!byName.has(doc.name))
+            byName.set(doc.name, doc);
+    }
+    return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/** Description from frontmatter plus when_to_use; never throws, "" when absent. */
+function readDescription(file) {
+    return describeFrom(readFrontmatter(file));
+}
+function describeFrom(fm) {
+    const description = fm.description;
+    if (description === undefined)
+        return "";
+    const when = fm.whenToUse;
+    const joined = when !== undefined && when.length > 0 ? `${description} ${when}` : description;
+    return joined.replace(/\s+/g, " ").trim();
+}
+function readFrontmatter(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return {};
+    }
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return {};
+    const end = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+    if (end < 0)
+        return {};
+    return frontmatter(lines.slice(1, end));
+}
+function frontmatter(body) {
+    try {
+        // descriptions are often multi-line `>-` scalars, so this needs a real yaml parser
+        const parsed = parseYaml(body.join("\n"));
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            const obj = parsed;
+            const out = {};
+            if (typeof obj.name === "string")
+                out.name = obj.name;
+            if (typeof obj.description === "string")
+                out.description = obj.description;
+            if (typeof obj.when_to_use === "string")
+                out.whenToUse = obj.when_to_use;
+            return out;
+        }
+    }
+    catch {
+        // fall through: Claude Code accepts files yaml does not
+    }
+    // real command files carry non-YAML lines like `argument-hint: [PROJ-1234] [repo]`
+    // that break the whole document; read the fields we need line by line instead
+    return {
+        name: readField(body, "name"),
+        description: readField(body, "description"),
+        whenToUse: readField(body, "when_to_use"),
+    };
+}
+const BLOCK_MARKERS = new Set(["", ">", ">-", "|", "|-"]);
+/** Line-based value of a top-level frontmatter key; folded scalars continue below. */
+function readField(lines, key) {
+    const prefix = `${key}:`;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.startsWith(prefix))
+            continue;
+        const rest = line.slice(prefix.length).trim();
+        if (!BLOCK_MARKERS.has(rest))
+            return unquote(rest);
+        const parts = [];
+        for (let j = i + 1; j < lines.length; j++) {
+            const cont = lines[j];
+            if (cont.trim() === "")
+                continue;
+            if (cont !== cont.trimStart())
+                parts.push(cont.trim()); // indented deeper than the key
+            else
+                break;
+        }
+        return parts.length > 0 ? unquote(parts.join(" ")) : undefined;
+    }
+    return undefined;
+}
+function unquote(value) {
+    const first = value[0];
+    if ((first === '"' || first === "'") && value.length >= 2 && value[value.length - 1] === first) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/** Plugin skills and commands registered under the user config root. */
+function pluginDocs(configRoot, cwd) {
+    const registry = readJson(path.join(configRoot, "plugins", "installed_plugins.json"));
+    const plugins = registry?.plugins;
+    if (typeof plugins !== "object" || plugins === null)
+        return [];
+    const disabled = disabledPlugins(configRoot);
+    const out = [];
+    for (const [key, entries] of Object.entries(plugins)) {
+        if (disabled.has(key))
+            continue;
+        if (!Array.isArray(entries))
+            continue;
+        const plugin = key.split("@")[0]; // name is the part before the marketplace
+        for (const raw of entries) {
+            if (typeof raw !== "object" || raw === null)
+                continue;
+            const entry = raw;
+            const scoped = entry.scope === "project" || entry.scope === "local";
+            if (entry.scope !== "user" && !(scoped && entry.projectPath === cwd))
+                continue;
+            const installPath = entry.installPath;
+            if (typeof installPath !== "string" || installPath === "")
+                continue;
+            out.push(...pluginSkillDocs(plugin, installPath), ...pluginCommandDocs(plugin, installPath));
+        }
+    }
+    return out;
+}
+function disabledPlugins(configRoot) {
+    const enabled = readJson(path.join(configRoot, "settings.json"))?.enabledPlugins;
+    const out = new Set();
+    if (typeof enabled !== "object" || enabled === null)
+        return out;
+    for (const [key, value] of Object.entries(enabled)) {
+        if (value === false)
+            out.add(key);
+    }
+    return out;
+}
+function pluginSkillDocs(plugin, installPath) {
+    const declared = pluginManifest(installPath)?.skills;
+    const dirs = Array.isArray(declared)
+        ? declared.filter((s) => typeof s === "string").map((rel) => path.resolve(installPath, rel))
+        : skillDirNames(path.join(installPath, "skills")).map((name) => path.join(installPath, "skills", name));
+    const out = [];
+    for (const dir of dirs) {
+        const file = path.join(dir, "SKILL.md");
+        if (!isFile(file))
+            continue;
+        const fm = readFrontmatter(file);
+        const name = fm.name !== undefined && fm.name.trim() !== "" ? fm.name.trim() : path.basename(dir);
+        out.push({ name: `${plugin}:${name}`, kind: "skill", file, description: describeFrom(fm), plugin });
+    }
+    return out;
+}
+function pluginCommandDocs(plugin, installPath) {
+    const declared = pluginManifest(installPath)?.commands;
+    let files;
+    if (Array.isArray(declared)) {
+        files = [];
+        for (const entry of declared) {
+            if (typeof entry !== "string")
+                continue;
+            const p = path.resolve(installPath, entry);
+            if (isFile(p)) {
+                if (p.endsWith(".md"))
+                    files.push(p);
+            }
+            else {
+                files.push(...commandFiles(p));
+            }
+        }
+    }
+    else {
+        files = commandFiles(path.join(installPath, "commands"));
+    }
+    return files.map((file) => ({
+        name: `${plugin}:${path.basename(file).replace(/\.md$/, "")}`,
+        kind: "command",
+        file,
+        description: readDescription(file),
+        plugin,
+    }));
+}
+function commandFiles(dir) {
+    return commandNames(dir).map((name) => path.join(dir, `${name}.md`));
+}
+function pluginManifest(installPath) {
+    return readJson(path.join(installPath, ".claude-plugin", "plugin.json"));
+}
+function readJson(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null; // missing or broken registry just means no plugins
+    }
+}
+function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/judge.js

@@ -0,0 +1,53 @@
+export const DIAGNOSIS = "skill named in text but not invoked — a model or directive limit, not routing";
+export const DIAGNOSIS_LIMIT = "reproduce on a stronger model before editing descriptions";
+export function judge(c, r) {
+    if (r.error) {
+        return {
+            ok: false, reasons: [r.error], reason: r.error, loaded: r.loaded,
+            diagnosis: null, costUsd: r.costUsd, error: r.error,
+            stoppedEarly: r.stoppedEarly, durationMs: r.durationMs,
+        };
+    }
+    const got = r.loaded;
+    const reasons = [];
+    for (const name of c.expect) {
+        if (!got.includes(name))
+            reasons.push(`not loaded ${name}`);
+    }
+    if (c.expect_any.length > 0 && !c.expect_any.some((name) => got.includes(name))) {
+        reasons.push(`not loaded any of [${c.expect_any.join(", ")}]`);
+    }
+    for (const name of c.forbid) {
+        if (got.includes(name))
+            reasons.push(`forbidden ${name}`);
+    }
+    if (c.first) {
+        if (got.length === 0)
+            reasons.push(`nothing loaded, expected ${c.first} first`);
+        else if (got[0] !== c.first)
+            reasons.push(`loaded ${got[0]} first, expected ${c.first}`);
+    }
+    if (c.none && got.length > 0) {
+        reasons.push(`expected nothing, loaded [${got.join(", ")}]`);
+    }
+    const unique = [...new Set(reasons)];
+    const ok = unique.length === 0;
+    let diagnosis = null;
+    if (!ok && got.length === 0) {
+        const text = r.text.toLowerCase();
+        const named = [...c.expect, ...c.expect_any].some((name) => text.includes(name.toLowerCase()));
+        if (named)
+            diagnosis = DIAGNOSIS;
+    }
+    return {
+        ok, reasons: unique, reason: unique.slice(0, 2).join("; "), loaded: got,
+        diagnosis, costUsd: r.costUsd, error: null,
+        stoppedEarly: r.stoppedEarly, durationMs: r.durationMs,
+    };
+}
+export function aggregate(c, runs, threshold) {
+    const passed = runs.filter((r) => r.ok).length;
+    // epsilon: 1/3 * 3 >= 1.0 must hold despite float noise
+    const ok = runs.length > 0 && passed / runs.length >= threshold - 1e-9;
+    return { case: c, runs, passed, ok, threshold };
+}

package/dist/junit.js

@@ -0,0 +1,84 @@
+/** Codepoints that are not representable in XML 1.0 at all. */
+const INVALID_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g;
+/**
+ * JUnit XML as GitLab and GitHub test reporters understand it. A run that
+ * errored is an <error> (the model never answered), a wrong routing is a
+ * <failure>.
+ */
+export function toJunit(report) {
+    const suiteName = `skillcheck.${report.agent}`;
+    const rows = report.cases.map((c) => ({ c, kind: classify(c) }));
+    const count = (kind) => rows.filter((r) => r.kind === kind).length;
+    const totals = `tests="${report.cases.length}" failures="${count("failed")}" errors="${count("errored")}"`;
+    const properties = ["    <properties>", `      <property name="agent" value="${esc(report.agent)}"/>`];
+    if (report.model !== null)
+        properties.push(`      <property name="model" value="${esc(report.model)}"/>`);
+    properties.push(`      <property name="costUsd" value="${report.summary.costUsd.toFixed(2)}"/>`);
+    // early-stopped runs report no cost, so costUsd alone understates the spend
+    if (report.summary.unknownCostRuns > 0) {
+        properties.push(`      <property name="unknownCostRuns" value="${report.summary.unknownCostRuns}"/>`);
+    }
+    properties.push("    </properties>");
+    const cases = rows.map(({ c, kind }) => testcase(c, kind, suiteName));
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        // Jenkins' schema allows `skipped` on <testsuite> only, not on <testsuites>
+        `<testsuites name="skillcheck" ${totals} time="${sec(report.durationMs)}">`,
+        `  <testsuite name="${esc(suiteName)}" ${totals} skipped="${count("skipped")}" time="${sec(report.durationMs)}" timestamp="${esc(report.startedAt)}">`,
+        ...properties,
+        ...cases,
+        "  </testsuite>",
+        "</testsuites>",
+        "",
+    ].join("\n");
+}
+function classify(c) {
+    if (c.status !== "failed")
+        return c.status === "skipped" ? "skipped" : "passed";
+    const failed = c.runs.filter((r) => !r.ok);
+    return failed.length > 0 && failed.every((r) => r.error) ? "errored" : "failed";
+}
+function testcase(c, kind, suiteName) {
+    const time = sec(c.runs.reduce((ms, r) => ms + r.durationMs, 0));
+    const name = `#${c.id ?? c.index} ${collapse(c.query)}`;
+    const open = `      <testcase name="${esc(name)}" classname="${esc(suiteName)}" time="${time}">`;
+    if (kind === "passed")
+        return `      <testcase name="${esc(name)}" classname="${esc(suiteName)}" time="${time}"/>`;
+    if (kind === "skipped")
+        return `${open}\n        <skipped message="budget reached"/>\n      </testcase>`;
+    const error = kind === "errored";
+    const culprit = c.runs.find((r) => !r.ok && (error ? r.error : !r.error));
+    const tag = error ? "error" : "failure";
+    const type = error ? "run" : "routing";
+    const message = error ? culprit?.error ?? "" : culprit?.reason ?? "";
+    return `${open}\n        <${tag} message="${esc(message)}" type="${type}">${esc(detail(c))}</${tag}>\n      </testcase>`;
+}
+/** One line per run, then the diagnoses, then the case note. */
+function detail(c) {
+    const lines = c.runs.map((r, i) => {
+        const head = `run ${i + 1}: ${r.ok ? "ok" : "FAIL"} loaded [${r.loaded.join(", ")}]`;
+        return r.ok ? head : `${head} · ${r.reason}`;
+    });
+    const diagnoses = [...new Set(c.runs.map((r) => r.diagnosis).filter((d) => d !== null))];
+    lines.push(...diagnoses.map((d) => `diagnosis: ${d}`));
+    if (c.note !== null)
+        lines.push(`note: ${c.note}`);
+    return lines.join("\n");
+}
+/** Milliseconds to seconds, at most three decimals, trailing zeros trimmed. */
+function sec(ms) {
+    return String(Number((ms / 1000).toFixed(3)));
+}
+/** Collapse to one line without truncating; the full query must stay in the name. */
+function collapse(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function esc(text) {
+    return text
+        .replace(INVALID_XML, "")
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}

package/dist/lexical.js

@@ -0,0 +1,117 @@
+// A tiny TF-IDF index: enough lexical signal to compare descriptions without
+// pulling in a stemming or embeddings dependency.
+const STOPWORDS = new Set([
+    // Russian and English function words carry no routing signal. MR, CI, DB, PR
+    // are two-letter but real, so tokenize keeps words of length >= 2 and the
+    // common two-letter function words are listed here. ё folds to е before the
+    // check, so the е spellings are listed.
+    "и", "в", "на", "не", "что", "это", "как", "для", "по", "из", "или", "при", "об", "но", "же",
+    "the", "and", "for", "with", "this", "that", "from", "into", "when", "use", "not", "are", "was",
+    "за", "до", "от", "то", "ли", "бы", "мы", "вы", "он", "она", "оно", "они", "мой", "мои", "моих",
+    "мое", "его", "ее", "их", "там", "тут", "вот", "уже", "еще", "так",
+    "to", "of", "in", "on", "is", "it", "an", "as", "at", "be", "by", "or", "if", "do", "we",
+    "you", "my", "me", "your", "our", "its",
+]);
+export function tokenize(text) {
+    // camelCase boundaries become spaces, and ё is treated as е
+    const spaced = text.replace(/[ёЁ]/g, (c) => (c === "ё" ? "е" : "Е")).replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+    const words = spaced.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+    return words
+        .filter((w) => w.length >= 2 && !STOPWORDS.has(w))
+        // crude stem: 5 chars is enough to tell inflections of one word from
+        // different words, and a real stemmer is not worth the dependency
+        .map((w) => (w.length > 5 ? w.slice(0, 5) : w));
+}
+/** Doc text = description plus the name itself, split on the usual separators. */
+function docText(name, text) {
+    return `${text} ${name.split(/[-_:]/).join(" ")}`;
+}
+function termFreq(tokens) {
+    const tf = new Map();
+    for (const t of tokens)
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    return tf;
+}
+function normalize(vec) {
+    let sum = 0;
+    for (const w of vec.values())
+        sum += w * w;
+    const norm = Math.sqrt(sum);
+    if (norm === 0)
+        return; // empty vector stays all-zero, cosine gives 0
+    for (const [t, w] of vec)
+        vec.set(t, w / norm);
+}
+function cosine(a, b) {
+    const [small, big] = a.size <= b.size ? [a, b] : [b, a];
+    let dot = 0;
+    for (const [t, w] of small) {
+        const wb = big.get(t);
+        if (wb !== undefined)
+            dot += w * wb;
+    }
+    return dot;
+}
+export class LexicalIndex {
+    vectors = new Map();
+    idf = new Map();
+    constructor(docs) {
+        const df = new Map();
+        const tfs = docs.map((d) => {
+            const tf = termFreq(tokenize(docText(d.name, d.text)));
+            for (const t of tf.keys())
+                df.set(t, (df.get(t) ?? 0) + 1);
+            return { name: d.name, tf };
+        });
+        const n = docs.length;
+        for (const [t, count] of df)
+            this.idf.set(t, Math.log(1 + n / count));
+        for (const { name, tf } of tfs) {
+            const vec = new Map();
+            for (const [t, count] of tf)
+                vec.set(t, count * (this.idf.get(t) ?? 0));
+            normalize(vec);
+            this.vectors.set(name, vec);
+        }
+    }
+    rank(query) {
+        const q = this.vectorize(tokenize(query));
+        const out = [...this.vectors.entries()].map(([name, vec]) => ({ name, score: cosine(q, vec) }));
+        out.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : 1));
+        return out;
+    }
+    similarity(a, b) {
+        const va = this.vectors.get(a);
+        const vb = this.vectors.get(b);
+        if (!va || !vb)
+            return 0;
+        return cosine(va, vb);
+    }
+    pairs(minScore) {
+        const names = [...this.vectors.keys()];
+        const out = [];
+        for (let i = 0; i < names.length; i++) {
+            for (let j = i + 1; j < names.length; j++) {
+                let a = names[i];
+                let b = names[j];
+                if (a > b)
+                    [a, b] = [b, a];
+                const score = this.similarity(a, b);
+                if (score >= minScore)
+                    out.push({ a, b, score });
+            }
+        }
+        out.sort((x, y) => y.score - x.score || (x.a < y.a ? -1 : x.a > y.a ? 1 : x.b < y.b ? -1 : x.b > y.b ? 1 : 0));
+        return out;
+    }
+    vectorize(tokens) {
+        const vec = new Map();
+        for (const [t, count] of termFreq(tokens)) {
+            const idf = this.idf.get(t);
+            if (idf !== undefined)
+                vec.set(t, count * idf); // unknown words carry no signal
+        }
+        normalize(vec);
+        return vec;
+    }
+}

package/dist/lint.js

@@ -0,0 +1,51 @@
+import { LexicalIndex } from "./lexical.js";
+// measured on a real config: a true near-duplicate pair scored 0.42, a known
+// confusion pair 0.20, so 0.3 separates them
+export const LINT_DEFAULTS = { top: 5, overlap: 0.3, minLength: 40 };
+export function lint(docs, suite, opts) {
+    const index = new LexicalIndex(docs.map((d) => ({ name: d.name, text: d.description })));
+    const short = docs
+        .filter((d) => d.description.length < opts.minLength)
+        .map((d) => ({ name: d.name, kind: d.kind, length: d.description.length }));
+    const similar = index.pairs(opts.overlap);
+    const far = [];
+    const covered = new Set();
+    if (suite) {
+        for (const c of suite.cases) {
+            for (const name of [...c.expect, ...c.expect_any, ...c.forbid, ...(c.first ? [c.first] : [])])
+                covered.add(name);
+            if (c.none)
+                continue; // a none case expects nothing lexical
+            far.push(...farForCase(c, index, opts.top));
+        }
+    }
+    // with no suite there is no evidence either way, so uncovered stays empty;
+    // plugin skills are someone else's, they are not required to have cases
+    const uncovered = suite
+        ? docs.filter((d) => d.kind === "skill" && d.plugin === null && !covered.has(d.name)).map((d) => d.name).sort()
+        : [];
+    return { docs: docs.length, cases: suite?.cases.length ?? 0, short, similar, far, uncovered };
+}
+function farForCase(c, index, top) {
+    const ranking = index.rank(c.query);
+    const byName = new Map(ranking.map((r, i) => [r.name, i + 1]));
+    const targets = c.expect.map((name) => ({ label: name, members: [name] }));
+    // the whole expect_any is one target, ranked by its best member
+    if (c.expect_any.length > 0)
+        targets.push({ label: c.expect_any.join("|"), members: c.expect_any });
+    if (c.first !== undefined && !c.expect.includes(c.first))
+        targets.push({ label: c.first, members: [c.first] });
+    const out = [];
+    for (const t of targets) {
+        // names without a doc (built-ins, typos) cannot be ranked; plugin `x:y`
+        // names have docs once plugins are loaded and are ranked like any other
+        const ranks = t.members.map((m) => byName.get(m)).filter((r) => r !== undefined);
+        if (ranks.length === 0)
+            continue;
+        const rank = Math.min(...ranks);
+        if (rank > top) {
+            out.push({ index: c.index, id: c.id ?? null, query: c.query, expected: t.label, rank, top: ranking.slice(0, 3).map((r) => r.name) });
+        }
+    }
+    return out;
+}

package/dist/pool.js

@@ -0,0 +1,35 @@
+export async function runPool(items, concurrency, worker, opts) {
+    const cap = Math.max(1, Math.floor(concurrency) || 1);
+    const results = new Array(items.length).fill(undefined);
+    const inflight = new Set();
+    let next = 0;
+    let failed = false;
+    let firstError;
+    const canStart = () => !failed && next < items.length && (!opts?.shouldStart || opts.shouldStart());
+    const start = () => {
+        const i = next++;
+        const task = (async () => {
+            try {
+                results[i] = await worker(items[i], i);
+            }
+            catch (e) {
+                if (!failed) {
+                    failed = true;
+                    firstError = e;
+                }
+            }
+        })();
+        const slot = task.then(() => { inflight.delete(slot); });
+        inflight.add(slot);
+    };
+    while (canStart() && inflight.size < cap)
+        start();
+    while (inflight.size > 0) {
+        await Promise.race(inflight);
+        while (canStart() && inflight.size < cap)
+            start();
+    }
+    if (failed)
+        throw firstError;
+    return results;
+}