vigiles 14.7.0 → 14.8.0

package/dist/score-core.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Structural-health SCORING core — extracted as a NODE-FREE leaf.
+ *
+ * The scoring functions (`scoreReport`/`reportDeductions`/`computeIntegrityScore`/
+ * `gradeFor` + the penalty weights) are pure: they take a {@link ScanReport} and
+ * return numbers/labels, touching no filesystem. They lived in `leaderboard.ts`,
+ * but that module ALSO holds the node-only `rankPlugins`/`pluginLabel` (which call
+ * `scanPlugin` + `node:fs`), so importing ANY symbol from it eagerly pulled the
+ * whole `scan.ts` → `@ast-grep/napi` (a native binary) + `node:fs` chain into the
+ * graph — tainting `buildAuditReport` and blocking the in-browser audit engine
+ * (`scanFiles` is node-free, but the report BUILDER re-tainted it via
+ * audit-score/optimize/audit-verdict → leaderboard → scan).
+ *
+ * Splitting the pure core out here — exactly like `core/ncd.ts` was extracted from
+ * `proofs.ts` to keep `node:crypto` out of the browser graph — lets the report
+ * builder import scoring WITHOUT the node-only leaderboard code. `leaderboard.ts`
+ * re-exports these for its own consumers (rankPlugins/formatters), so nothing that
+ * imported them from `./leaderboard.js` breaks. The `ScanReport` import is
+ * TYPE-ONLY (elided at build), so no runtime `scan.ts` dependency enters this leaf.
+ * See src/scan-files.ts (BROWSER_ROOT) and research/report-view-and-browser-demo.md.
+ */
+import type { ScanReport } from "./scan.js";
+export interface PluginScore {
+    readonly dir: string;
+    readonly name: string;
+    /** 0–100 structural-health score (100 = no structural issues found). */
+    readonly score: number;
+    readonly grade: "A" | "B" | "C" | "D" | "F";
+    /** Human-readable deductions, worst first. */
+    readonly issues: readonly string[];
+    readonly report: ScanReport;
+}
+export declare const W_MISSING_HOOK = 15;
+export declare const W_NO_DESCRIPTION = 10;
+export declare const W_DANGLING_REF = 8;
+export declare const W_OVERLAP = 8;
+export declare const W_NO_CONTRACT = 5;
+export declare const W_TRIFECTA = 10;
+/** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
+export declare function gradeFor(score: number): PluginScore["grade"];
+/** One deduction: a count, its per-item weight, and the label if non-zero. */
+export interface Deduction {
+    readonly n: number;
+    readonly weight: number;
+    readonly label: string;
+}
+/**
+ * The COMPLETE graded-penalty list a report incurs — the single source of truth
+ * BOTH the leaderboard's single health number and the audit's category rings
+ * read, so the overall can never drift between the two surfaces. Each entry is a
+ * graded penalty; untested surfaces are deliberately ABSENT (they're advisory,
+ * surfaced separately, never scored).
+ */
+export declare function reportDeductions(r: ScanReport): Deduction[];
+/** True when a report has no loadable plugin surface at all (the empty machine). */
+export declare function isEmptyMachine(r: ScanReport): boolean;
+/**
+ * THE shared integrity score — `100 − Σ(all graded penalties)`, clamped to
+ * [0,100]. Both the leaderboard's single health number AND the audit's headline
+ * overall read this, so the two can never disagree (the summed model is the
+ * honest one — averaging rings would dilute a real problem). Returns the score
+ * plus the per-item deductions so callers render their own issue/finding lists.
+ */
+export declare function computeIntegrityScore(deductions: readonly Deduction[]): {
+    score: number;
+    penalty: number;
+};
+/** Deterministic structural-health score for one scanned plugin. */
+export declare function scoreReport(r: ScanReport): {
+    score: number;
+    issues: string[];
+};
+//# sourceMappingURL=score-core.d.ts.map

package/dist/score-core.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.W_TRIFECTA = exports.W_NO_CONTRACT = exports.W_OVERLAP = exports.W_DANGLING_REF = exports.W_NO_DESCRIPTION = exports.W_MISSING_HOOK = void 0;
+exports.gradeFor = gradeFor;
+exports.reportDeductions = reportDeductions;
+exports.isEmptyMachine = isEmptyMachine;
+exports.computeIntegrityScore = computeIntegrityScore;
+exports.scoreReport = scoreReport;
+// Penalty weights — broken-at-runtime costs most, footguns less, nudges least.
+// Exported so the category view (audit-score.ts) reuses the SAME weights and the
+// two surfaces can never drift on a per-item cost.
+exports.W_MISSING_HOOK = 15; // a hook script that doesn't exist → never runs
+exports.W_NO_DESCRIPTION = 10; // a skill with no usable description → can't trigger
+exports.W_DANGLING_REF = 8; // a referenced intra-plugin file that's missing → broken path
+exports.W_OVERLAP = 8; // a description collision → the wrong skill fires
+exports.W_NO_CONTRACT = 5; // generic small-footgun weight (disallowedTools typo, invalid model/color)
+exports.W_TRIFECTA = 10; // a HARD lethal-trifecta contract (all three legs, explicit) → a prompt-injection exfil path. HALF the old 20: a DING, not a fail — a trifecta is a real risk worth surfacing in the grade, but official plugins ship the pattern by design, so it dents the score (e.g. feature-dev's 3 hard units → −30 → C) without a catastrophic F.
+// Two things are advisory, NOT graded penalties (shown, never scored — see scoreReport):
+//   - untested surfaces — a hardening gap, not breakage.
+//   - an agent that inherits all tools (no `tools:` line) — see reportDeductions for why.
+//   - an inherits-all (severity "advisory") trifecta finding — shown by the Safety
+//     ring but never scored; only the HARD, explicit all-three-legs finding grades.
+/** Map a 0–100 structural-health score to its letter grade (A ≥90 … F <60). */
+function gradeFor(score) {
+    if (score >= 90)
+        return "A";
+    if (score >= 80)
+        return "B";
+    if (score >= 70)
+        return "C";
+    if (score >= 60)
+        return "D";
+    return "F";
+}
+/**
+ * The COMPLETE graded-penalty list a report incurs — the single source of truth
+ * BOTH the leaderboard's single health number and the audit's category rings
+ * read, so the overall can never drift between the two surfaces. Each entry is a
+ * graded penalty; untested surfaces are deliberately ABSENT (they're advisory,
+ * surfaced separately, never scored).
+ */
+function reportDeductions(r) {
+    const missingHooks = r.hooks.filter((h) => h.status === "missing").length;
+    const noDesc = r.skills.filter((s) => !s.hasDescription).length;
+    const deadTools = r.agents.reduce((n, a) => n + a.toolIssues.length, 0);
+    const deadMcpTools = r.agents.reduce((n, a) => n + a.mcpToolIssues.length, 0);
+    const deadDisallowed = r.agents.reduce((n, a) => n + a.disallowedToolIssues.length, 0);
+    // HARD lethal-trifecta findings only — an EXPLICIT contract naming all three
+    // legs (a prompt-injection exfil path). Graded at W_TRIFECTA=10 (HALF the old
+    // 20): a DING that surfaces a real risk in the grade without a catastrophic F
+    // for an accepted design pattern official plugins ship. Advisory (inherits-all)
+    // trifecta findings are surfaced but NEVER graded (aligned with the inherits-all
+    // stance), so they're excluded here.
+    const hardTrifecta = r.trifectaFindings.filter((f) => f.finding.severity === "hard").length;
+    return [
+        {
+            n: hardTrifecta,
+            weight: exports.W_TRIFECTA,
+            label: "unit(s) holding all three lethal-trifecta legs (prompt-injection exfil path)",
+        },
+        {
+            n: missingHooks,
+            weight: exports.W_MISSING_HOOK,
+            label: "hook script(s) MISSING",
+        },
+        {
+            n: r.hookEventIssues.length,
+            weight: exports.W_MISSING_HOOK,
+            label: "hook(s) on an unknown event (never fire)",
+        },
+        {
+            n: noDesc,
+            weight: exports.W_NO_DESCRIPTION,
+            label: "skill(s) with no usable description",
+        },
+        {
+            n: r.descriptionOverlaps.length,
+            weight: exports.W_OVERLAP,
+            label: "near-identical skill description(s) (wrong one fires)",
+        },
+        {
+            n: r.danglingRefs.length,
+            weight: exports.W_DANGLING_REF,
+            label: "broken intra-plugin reference(s)",
+        },
+        {
+            n: deadTools,
+            weight: exports.W_DANGLING_REF,
+            label: "unavailable agent tool(s) (typo / never-available)",
+        },
+        {
+            n: deadMcpTools,
+            weight: exports.W_DANGLING_REF,
+            label: "agent MCP tool(s) whose server isn't declared (can't resolve)",
+        },
+        {
+            n: deadDisallowed,
+            weight: exports.W_NO_CONTRACT,
+            label: "agent disallowedTools typo(s) that block nothing",
+        },
+        // NB: an agent that inherits all tools (no `tools:` line) is ADVISORY, not a
+        // graded penalty — it's surfaced by scoreReport / the Structure ring but never
+        // drags the score. WHY: omitting the `tools:` line is a near-universal,
+        // legitimate authoring style (a measured OSS sweep of 122 real plugins found
+        // 109 whose ONLY finding was this), so penalizing it makes the grade cry wolf
+        // on idiomatic subagents. A health score should mean "something is BROKEN", and
+        // a broad-by-default tool surface is a hardening/least-privilege NUDGE, not
+        // breakage. The count is re-derived where the advisory note is built.
+        {
+            n: r.frontmatterIssues.length,
+            weight: exports.W_NO_DESCRIPTION,
+            label: "surface(s) missing required frontmatter (name/description)",
+        },
+        {
+            n: r.frontmatterValueIssues.length,
+            weight: exports.W_NO_CONTRACT,
+            label: "agent(s) with an invalid model/color (typo → silent fallback)",
+        },
+        {
+            n: r.mcpIssues.length,
+            weight: exports.W_DANGLING_REF,
+            label: "MCP server(s) that can't start (no command/url)",
+        },
+        {
+            n: r.mcpHookIssues.length,
+            weight: exports.W_DANGLING_REF,
+            label: "mcp_tool hook(s) incomplete / targeting an undeclared server",
+        },
+        {
+            n: r.skillResourceIssues.length,
+            weight: exports.W_DANGLING_REF,
+            label: "skill bundled-resource ref(s) that don't resolve on disk",
+        },
+        {
+            n: r.skillFenceIssues.length,
+            weight: exports.W_NO_DESCRIPTION,
+            label: "invisible skill(s) (frontmatter with no opening `---` fence)",
+        },
+        {
+            n: r.pluginLayoutIssues.length,
+            weight: exports.W_NO_DESCRIPTION,
+            label: "functional dir(s) misplaced inside `.claude-plugin/` (invisible)",
+        },
+        {
+            n: r.hookBlockFindings.length,
+            weight: exports.W_MISSING_HOOK,
+            label: "hook(s) that look like they block but silently don't",
+        },
+        {
+            n: r.hookMatcherFindings.length,
+            weight: exports.W_MISSING_HOOK,
+            label: "hook matcher(s) that never fire (typo / wrong MCP form)",
+        },
+        // NB: delegationTrifecta (like the advisory per-unit/inherits-all trifecta) is a
+        // ⚠ RISK, surfaced but NOT graded — only the HARD per-unit trifecta above scores.
+        // NB: untested surfaces are NOT a penalty — an untested surface is a hardening
+        // gap, not breakage, so it never drags the health score (it's appended as an
+        // advisory note below). The score ranks what's BROKEN.
+    ];
+}
+/** True when a report has no loadable plugin surface at all (the empty machine). */
+function isEmptyMachine(r) {
+    const surfaces = r.skills.length +
+        r.agents.length +
+        r.hooks.length +
+        r.inlineHooks +
+        r.commands;
+    return surfaces === 0 && !r.mcp;
+}
+/**
+ * THE shared integrity score — `100 − Σ(all graded penalties)`, clamped to
+ * [0,100]. Both the leaderboard's single health number AND the audit's headline
+ * overall read this, so the two can never disagree (the summed model is the
+ * honest one — averaging rings would dilute a real problem). Returns the score
+ * plus the per-item deductions so callers render their own issue/finding lists.
+ */
+function computeIntegrityScore(deductions) {
+    let penalty = 0;
+    for (const d of deductions) {
+        if (d.n <= 0)
+            continue;
+        penalty += d.n * d.weight;
+    }
+    return { score: Math.max(0, 100 - penalty), penalty };
+}
+/** Resolve the terse "thing(s)" plural placeholder against a count:
+ * n===1 drops the "(s)" ("1 tool"); otherwise it becomes "s" ("3 tools").
+ * (Kept local — audit-score.ts has its own copy to avoid a circular import.) */
+function pluralizeLabel(n, label) {
+    return label.replace(/\(s\)/g, n === 1 ? "" : "s");
+}
+/** Deterministic structural-health score for one scanned plugin. */
+function scoreReport(r) {
+    // An empty/unloadable machine isn't healthy — it's a non-plugin or a broken
+    // load. A command-only or MCP-only plugin (commands/*.md or .mcp.json with no
+    // skills/agents/hooks) IS a legitimate plugin, though — Anthropic ships
+    // command-only plugins in its own marketplace — so it must NOT score 0.
+    const surfaces = r.skills.length + r.agents.length + r.hooks.length + r.commands;
+    if (surfaces === 0 && !r.mcp) {
+        return { score: 0, issues: ["no loadable plugin surface"] };
+    }
+    const deductions = reportDeductions(r);
+    const { score } = computeIntegrityScore(deductions);
+    const issues = [];
+    for (const d of deductions) {
+        if (d.n === 0)
+            continue;
+        issues.push(`${String(d.n)} ${pluralizeLabel(d.n, d.label)}`);
+    }
+    // Sort issues by cost (worst first) so the report leads with what matters.
+    issues.sort((a, b) => Number(b.split(" ")[0]) - Number(a.split(" ")[0]));
+    // Advisory notes are surfaced for visibility but DON'T affect the score, so they
+    // come AFTER the real (score-affecting) issues:
+    //   - inherit-all (no tool contract): a least-privilege NUDGE, not breakage —
+    //     see reportDeductions for the full rationale.
+    //   - untested surfaces: a hardening gap, not breakage.
+    const noContract = r.agents.filter((a) => a.tools === null).length;
+    if (noContract > 0) {
+        issues.push(`${String(noContract)} ${pluralizeLabel(noContract, "agent(s) inherit all tools (no contract) (advisory)")}`);
+    }
+    if (r.untested > 0) {
+        issues.push(`${String(r.untested)} ${pluralizeLabel(r.untested, "untested surface(s) (advisory)")}`);
+    }
+    return { score, issues };
+}
+//# sourceMappingURL=score-core.js.map

package/dist/test-coverage-files.d.ts

@@ -0,0 +1,11 @@
+import type { PluginLayout } from "./core/layout.js";
+import type { Surface } from "./test-coverage.js";
+/**
+ * The untested harness surfaces (skills / agents / hooks) in a file map — the
+ * browser-safe twin of `findUntestedSurfaces`, returning only the `untested` list
+ * (`scanFiles` needs the count). Same coverage rules as the disk detector.
+ */
+export declare function findUntestedSurfacesInFiles(files: Record<string, string>, layout: PluginLayout): {
+    untested: Surface[];
+};
+//# sourceMappingURL=test-coverage-files.d.ts.map

package/dist/test-coverage-files.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findUntestedSurfacesInFiles = findUntestedSurfacesInFiles;
+/**
+ * Browser-safe twin of `findUntestedSurfaces` (src/test-coverage.ts) — the same
+ * untested-surface detection over an in-memory repo-relative file map instead of
+ * a disk walk. `findUntestedSurfaces` globs the filesystem; this reimplements each
+ * of its `globSync` calls as an `Object.keys(files).filter(...)` over the map, so
+ * `scanFiles` reaches the SAME `untested` count with no disk I/O.
+ *
+ * Mirrors the disk detector exactly: the skill/agent surface globs (both the plain
+ * and the materialize-root form), the hook-script discovery from the
+ * manifest/settings/`.local` settings, the test-file globs (harness/eval/test
+ * suffixes) with the same ignore set, the `vigiles:ignore-test` exemption, and the
+ * colocation + content-reference coverage rules. See the parity test in
+ * src/scan-files.test.ts.
+ */
+const posix_path_js_1 = require("./posix-path.js");
+// Mirrors src/test-coverage.ts constants.
+const DEFAULT_TEST_SUFFIXES = [
+    ".harness.mjs",
+    ".eval.mjs",
+    ".test.ts",
+    ".test.mts",
+    ".test.cts",
+    ".test.js",
+    ".test.mjs",
+    ".test.cjs",
+];
+const IGNORE_MARKER = "vigiles:ignore-test";
+const SCRIPT_RE = /[\w./${}@-]+\.(?:sh|mjs|cjs|js|ts|py|rb)/g;
+/** Mirror of the DEFAULT_IGNORE globs (root-anchored), as a key predicate. */
+function isIgnored(key) {
+    return /^(?:node_modules|dist|\.vigiles|\.git)\//.test(key);
+}
+/** Escape a literal path segment for use inside a RegExp. */
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** The two prefixes a surface dir can occupy (plain + materialize-root form). */
+function surfacePrefixes(dir, materializeRoot) {
+    if (!dir)
+        return [];
+    const matForm = materializeRoot ? `${materializeRoot}/${dir}` : dir;
+    return [...new Set([dir, matForm])];
+}
+/** Keys matching `<prefix>/<leafRe>` for any prefix, deduped + sorted (globSync order). */
+function matchSurface(files, prefixes, leafRe) {
+    const found = new Set();
+    for (const prefix of prefixes) {
+        const re = new RegExp(`^${escapeRe(prefix)}/${leafRe}$`);
+        for (const key of Object.keys(files)) {
+            if (isIgnored(key))
+                continue;
+            if (re.test(key))
+                found.add(key);
+        }
+    }
+    return [...found].sort();
+}
+function discoverSkills(files, layout) {
+    const out = [];
+    if (layout.skillDir) {
+        const prefixes = surfacePrefixes(layout.skillDir, layout.materializeRoot);
+        for (const path of matchSurface(files, prefixes, "[^/]+/SKILL\\.md")) {
+            const name = (0, posix_path_js_1.basename)((0, posix_path_js_1.dirname)(path));
+            const content = files[path];
+            out.push({
+                kind: "skill",
+                path,
+                name,
+                tokens: [`${layout.skillDir}/${name}`, `:${name}`],
+                ignored: content.includes(IGNORE_MARKER),
+            });
+        }
+    }
+    // Single-skill-directory target: a bare `SKILL.md` at the repo root.
+    if (Object.prototype.hasOwnProperty.call(files, "SKILL.md")) {
+        const name = "SKILL"; // browser has no real base dir name (see BROWSER_ROOT).
+        const content = files["SKILL.md"];
+        out.push({
+            kind: "skill",
+            path: "SKILL.md",
+            name,
+            tokens: [`${layout.skillDir}/${name}`, `:${name}`],
+            ignored: content.includes(IGNORE_MARKER),
+        });
+    }
+    return out;
+}
+function discoverAgents(files, layout) {
+    const out = [];
+    if (!layout.agentDir)
+        return out;
+    const prefixes = surfacePrefixes(layout.agentDir, layout.materializeRoot);
+    for (const path of matchSurface(files, prefixes, "[^/]+\\.md")) {
+        if (path.endsWith(".spec.ts"))
+            continue;
+        const content = files[path];
+        const name = (0, posix_path_js_1.basename)(path, ".md");
+        const dir = (0, posix_path_js_1.dirname)(path);
+        out.push({
+            kind: "agent",
+            path,
+            name,
+            tokens: [`${dir}/${name}`],
+            ignored: content.includes(IGNORE_MARKER),
+        });
+    }
+    return out;
+}
+/** Hook-script paths referenced from a manifest's `hooks` block (file hooks only). */
+function hookScripts(files, manifest, pluginRootToken) {
+    const text = files[manifest];
+    if (text === undefined)
+        return [];
+    let hooks;
+    try {
+        hooks = JSON.parse(text).hooks;
+    }
+    catch {
+        return [];
+    }
+    if (hooks === undefined)
+        return [];
+    const raw = JSON.stringify(hooks);
+    const unbraced = pluginRootToken.replace(/^\$\{(.+)\}$/, "$$$1");
+    const scripts = new Set();
+    for (const m of raw.matchAll(SCRIPT_RE)) {
+        const rel = m[0]
+            .replaceAll(pluginRootToken, "")
+            .replaceAll(unbraced, "")
+            .replace(/^\/+/, "")
+            .replace(/^\.\//, "");
+        if (Object.prototype.hasOwnProperty.call(files, rel))
+            scripts.add(rel);
+    }
+    return [...scripts];
+}
+function discoverHooks(files, layout) {
+    const scripts = new Set();
+    const localSettings = layout.settingsPath.replace(/(\.[^./]+)$/, ".local$1");
+    const manifests = [
+        ...new Set([layout.manifestPath, layout.settingsPath, localSettings]),
+    ];
+    for (const m of manifests) {
+        for (const s of hookScripts(files, m, layout.pluginRootToken)) {
+            scripts.add(s);
+        }
+    }
+    return [...scripts].sort().map((path) => ({
+        kind: "hook",
+        path,
+        name: (0, posix_path_js_1.basename)(path).replace(/\.[^.]+$/, ""),
+        tokens: [path],
+        ignored: false,
+    }));
+}
+function discoverTests(files) {
+    const out = [];
+    for (const [path, content] of Object.entries(files)) {
+        if (isIgnored(path))
+            continue;
+        if (DEFAULT_TEST_SUFFIXES.some((s) => path.endsWith(s))) {
+            out.push({ path, content });
+        }
+    }
+    return out;
+}
+/** Mirror of test-coverage.ts `isColocated`. */
+function isColocated(surface, testPath) {
+    if (surface.kind === "skill") {
+        const dir = (0, posix_path_js_1.dirname)(surface.path);
+        return dir === "."
+            ? (0, posix_path_js_1.dirname)(testPath) === "."
+            : testPath.startsWith(`${dir}/`);
+    }
+    return ((0, posix_path_js_1.dirname)(testPath) === (0, posix_path_js_1.dirname)(surface.path) &&
+        (0, posix_path_js_1.basename)(testPath).startsWith(`${surface.name}.`));
+}
+function isCovered(surface, tests) {
+    for (const t of tests) {
+        if (t.path === surface.path)
+            continue;
+        if (isColocated(surface, t.path))
+            return true;
+        if (surface.tokens.some((tok) => t.content.includes(tok)))
+            return true;
+    }
+    return false;
+}
+/**
+ * The untested harness surfaces (skills / agents / hooks) in a file map — the
+ * browser-safe twin of `findUntestedSurfaces`, returning only the `untested` list
+ * (`scanFiles` needs the count). Same coverage rules as the disk detector.
+ */
+function findUntestedSurfacesInFiles(files, layout) {
+    const surfaces = [
+        ...discoverSkills(files, layout),
+        ...discoverAgents(files, layout),
+        ...discoverHooks(files, layout),
+    ];
+    const considered = surfaces.filter((s) => !s.ignored);
+    const tests = discoverTests(files);
+    const untested = considered.filter((s) => !isCovered(s, tests));
+    return { untested };
+}
+//# sourceMappingURL=test-coverage-files.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "14.7.0",
+  "version": "14.8.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",