vigiles 8.0.0 → 9.1.0

package/dist/audit-score.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Category scoring for `vigiles audit` — the Lighthouse rings.
+ *
+ * A single structural-health number (the leaderboard's `scoreReport`) ranks
+ * plugins, but it hides WHERE a harness is weak. This buckets the SAME
+ * deterministic findings into four categories — Truthfulness, Triggering,
+ * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
+ * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
+ * the leaderboard's single health number, via the shared `computeIntegrityScore`
+ * — so the two surfaces never disagree). Same detectors, no re-detection
+ * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
+ * hooks actually block?" — is NOT an `audit` ring:
+ * it requires executing your hooks, which needs cross-platform confinement
+ * that isn't shipped yet, so it lives in the `vigiles/testing` API via
+ * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
+ *
+ * A category that can't be assessed scores `null` (n/a) and is EXCLUDED from the
+ * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
+ */
+import { type PluginScore } from "./leaderboard.js";
+import type { ScanReport } from "./scan.js";
+export type CategoryKey = "Truthfulness" | "Triggering" | "Structure" | "Tested";
+export interface CategoryScore {
+    readonly key: CategoryKey;
+    /** 0–100, or `null` when the category isn't assessable (n/a — excluded from overall). */
+    readonly score: number | null;
+    /** Relative weight in the overall (equal by default — tune later). */
+    readonly weight: number;
+    /**
+     * Advisory categories are shown but EXCLUDED from the overall grade. An untested
+     * surface (or any best-practice gap) is a HARDENING signal, not a broken harness
+     * — it must never drag the grade down, so `audit` doesn't read as F on a clean
+     * repo that simply hasn't written tests yet. The grade reflects what's BROKEN.
+     */
+    readonly advisory?: boolean;
+    /** Human-readable deductions / notes, worst first; empty when clean. */
+    readonly findings: readonly string[];
+}
+export interface AuditScore {
+    /**
+     * The headline score — `100 − Σ(all graded penalties)`, clamped to [0,100]
+     * (the SAME summed model as the leaderboard's single health number, computed by
+     * the shared {@link computeIntegrityScore}, so the two surfaces never disagree).
+     * The per-category rings below are a DIAGNOSTIC breakdown, not the headline: a
+     * plugin whose only issue is Structure −30 shows Structure 70 in the breakdown
+     * AND overall 70 (averaging the rings would dilute that to ~90). 0 when empty.
+     */
+    readonly overall: number;
+    readonly grade: PluginScore["grade"];
+    readonly categories: readonly CategoryScore[];
+    /** No loadable surface at all — overall 0, every category n/a. */
+    readonly empty: boolean;
+}
+/**
+ * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
+ * penalties)` (the shared summed model — NOT the average of the rings — so it
+ * equals the leaderboard's single health number). The advisory Tested ring and
+ * any n/a ring are shown but excluded from the headline.
+ */
+export declare function auditScore(report: ScanReport): AuditScore;
+/** Render the category rings (diagnostic) + the summed overall for the terminal. */
+export declare function formatAuditScore(s: AuditScore): string;
+//# sourceMappingURL=audit-score.d.ts.map

package/dist/audit-score.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditScore = auditScore;
+exports.formatAuditScore = formatAuditScore;
+/**
+ * Category scoring for `vigiles audit` — the Lighthouse rings.
+ *
+ * A single structural-health number (the leaderboard's `scoreReport`) ranks
+ * plugins, but it hides WHERE a harness is weak. This buckets the SAME
+ * deterministic findings into four categories — Truthfulness, Triggering,
+ * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
+ * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
+ * the leaderboard's single health number, via the shared `computeIntegrityScore`
+ * — so the two surfaces never disagree). Same detectors, no re-detection
+ * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
+ * hooks actually block?" — is NOT an `audit` ring:
+ * it requires executing your hooks, which needs cross-platform confinement
+ * that isn't shipped yet, so it lives in the `vigiles/testing` API via
+ * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
+ *
+ * A category that can't be assessed scores `null` (n/a) and is EXCLUDED from the
+ * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
+ */
+const leaderboard_js_1 = require("./leaderboard.js");
+// Per-item penalties are the SHARED leaderboard weights (imported above) so the
+// category rings and the single health number can never drift. W_UNTESTED is
+// audit-only — untested surfaces are advisory (shown, never scored into overall).
+const W_UNTESTED = 3;
+/** Apply deductions to a 100 base, clamped to [0,100], collecting non-zero labels. */
+function scoreFrom(deductions) {
+    let penalty = 0;
+    const findings = [];
+    for (const d of deductions) {
+        if (d.n <= 0)
+            continue;
+        penalty += d.n * d.weight;
+        findings.push({ n: d.n, text: `${String(d.n)} ${d.label}` });
+    }
+    findings.sort((a, b) => b.n - a.n);
+    return {
+        score: Math.max(0, 100 - penalty),
+        findings: findings.map((f) => f.text),
+    };
+}
+function truthfulness(r) {
+    const missingHooks = r.hooks.filter((h) => h.status === "missing").length;
+    const { score, findings } = scoreFrom([
+        {
+            n: r.danglingRefs.length,
+            weight: leaderboard_js_1.W_DANGLING_REF,
+            label: "broken intra-plugin reference(s)",
+        },
+        {
+            n: missingHooks,
+            weight: leaderboard_js_1.W_MISSING_HOOK,
+            label: "hook script(s) missing (never run)",
+        },
+    ]);
+    return { key: "Truthfulness", score, weight: 1, findings };
+}
+function triggering(r) {
+    const noDesc = r.skills.filter((s) => !s.hasDescription).length;
+    const { score, findings } = scoreFrom([
+        {
+            n: noDesc,
+            weight: leaderboard_js_1.W_NO_DESCRIPTION,
+            label: "skill(s) with no usable description (can't trigger)",
+        },
+        {
+            n: r.descriptionOverlaps.length,
+            weight: leaderboard_js_1.W_OVERLAP,
+            label: "near-identical skill description(s) (wrong one fires)",
+        },
+    ]);
+    return { key: "Triggering", score, weight: 1, findings };
+}
+function structure(r) {
+    const noContract = r.agents.filter((a) => a.tools === null).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);
+    const { score, findings } = scoreFrom([
+        {
+            n: deadTools,
+            weight: leaderboard_js_1.W_DANGLING_REF,
+            label: "agent tool(s) that don't exist (typo / never-available)",
+        },
+        {
+            n: deadMcpTools,
+            weight: leaderboard_js_1.W_DANGLING_REF,
+            label: "agent MCP tool(s) whose server isn't declared",
+        },
+        {
+            n: r.hookEventIssues.length,
+            weight: leaderboard_js_1.W_MISSING_HOOK,
+            label: "hook(s) on an unknown event (never fire)",
+        },
+        {
+            n: r.mcpIssues.length,
+            weight: leaderboard_js_1.W_DANGLING_REF,
+            label: "MCP server(s) that can't start (no command/url)",
+        },
+        {
+            n: r.mcpHookIssues.length,
+            weight: leaderboard_js_1.W_DANGLING_REF,
+            label: "mcp_tool hook(s) incomplete / undeclared server",
+        },
+        {
+            n: r.frontmatterIssues.length,
+            weight: leaderboard_js_1.W_NO_DESCRIPTION,
+            label: "surface(s) missing required frontmatter",
+        },
+        {
+            n: r.frontmatterValueIssues.length,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
+            label: "agent(s) with an invalid model/color (silent fallback)",
+        },
+        {
+            n: deadDisallowed,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
+            label: "disallowedTools typo(s) that block nothing",
+        },
+        {
+            n: noContract,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
+            label: "agent(s) inherit all tools (no contract)",
+        },
+    ]);
+    return { key: "Structure", score, weight: 1, findings };
+}
+function tested(r) {
+    const { score, findings } = scoreFrom([
+        { n: r.untested, weight: W_UNTESTED, label: "untested surface(s)" },
+    ]);
+    // ADVISORY: untested surfaces are a hardening gap, not breakage — shown, but
+    // excluded from the overall grade (so a clean-but-untested repo isn't graded F).
+    return { key: "Tested", score, weight: 1, advisory: true, findings };
+}
+/**
+ * An instruction-only repo (just a CLAUDE.md/AGENTS.md, no plugin surface) is NOT
+ * empty — the scan records `instructions` precisely so it isn't graded F/0 "no
+ * loadable surface". Only a dir with NO instruction file AND no surface is empty.
+ * (The shared `isEmptyMachine` ignores `instructions`; audit additionally treats
+ * an instruction file as a surface.)
+ */
+function isEmptyAudit(r) {
+    return (0, leaderboard_js_1.isEmptyMachine)(r) && !r.instructions;
+}
+/**
+ * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
+ * penalties)` (the shared summed model — NOT the average of the rings — so it
+ * equals the leaderboard's single health number). The advisory Tested ring and
+ * any n/a ring are shown but excluded from the headline.
+ */
+function auditScore(report) {
+    if (isEmptyAudit(report)) {
+        const categories = [
+            "Truthfulness",
+            "Triggering",
+            "Structure",
+            "Tested",
+        ];
+        return {
+            overall: 0,
+            grade: (0, leaderboard_js_1.gradeFor)(0),
+            categories: categories.map((key) => ({
+                key,
+                score: null,
+                weight: 1,
+                findings: ["no loadable plugin surface"],
+            })),
+            empty: true,
+        };
+    }
+    const categories = [
+        truthfulness(report),
+        triggering(report),
+        structure(report),
+        tested(report),
+    ];
+    // The headline is the SUMMED model (the shared integrity score), NOT the average
+    // of the rings — averaging would let a real problem in one category be diluted
+    // by clean siblings. The rings above stay a diagnostic breakdown; Tested
+    // (advisory) is never summed in (untested surfaces don't drag the grade).
+    const { score: overall } = (0, leaderboard_js_1.computeIntegrityScore)((0, leaderboard_js_1.reportDeductions)(report));
+    return { overall, grade: (0, leaderboard_js_1.gradeFor)(overall), categories, empty: false };
+}
+// A 22-cell bar gauge ("ring" in the terminal; the real rings are the HTML).
+const BAR_CELLS = 22;
+/** A glyph that signals the band at a glance (green/amber/red, no ANSI needed). */
+function bandGlyph(score) {
+    if (score === null)
+        return "○";
+    if (score >= 90)
+        return "●";
+    if (score >= 70)
+        return "◑";
+    return "✗";
+}
+function bar(score) {
+    if (score === null)
+        return "n/a";
+    const filled = Math.round((score / 100) * BAR_CELLS);
+    return "█".repeat(filled) + "░".repeat(BAR_CELLS - filled);
+}
+/** Render the category rings (diagnostic) + the summed overall for the terminal. */
+function formatAuditScore(s) {
+    const lines = ["Harness audit", ""];
+    for (const c of s.categories) {
+        const glyph = bandGlyph(c.score);
+        const label = c.key.padEnd(13);
+        const num = (c.score === null ? "n/a" : String(c.score)).padStart(4);
+        const tag = c.advisory ? "  · advisory (not graded)" : "";
+        lines.push(`  ${glyph} ${label} ${num}  ${bar(c.score)}${tag}`);
+        if (c.findings.length > 0) {
+            lines.push(`       └ ${c.findings.join("; ")}`);
+        }
+    }
+    lines.push("");
+    lines.push(`Harness health: ${s.grade} (${String(s.overall)}/100)`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=audit-score.js.map

package/dist/cli-commands.d.ts

@@ -11,7 +11,7 @@
  * recognizes exactly these, so this list can't silently drift from the code.
  */
 /** Human-facing verbs (printed in help; typed by a human/agent/CI). */
-export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "scan", "scaffold-test", "generate", "hook-runtime"];
+export declare const VERBS: readonly ["init", "compile", "eject", "lint", "test", "eval", "audit", "scaffold-test", "generate", "hook-runtime"];
 /** Runtime entrypoint kinds under `vigiles hook-runtime <kind>` (emitted, not typed). */
 export declare const HOOK_RUNTIME_KINDS: readonly ["run-program", "agent", "agent-start", "agent-done", "skill", "skill-tool", "skill-start", "skill-done", "run-skill", "intercept-tool", "guard", "action", "refs", "effect-enter", "effect-exit"];
 export type Verb = (typeof VERBS)[number];

package/dist/cli-commands.js

@@ -21,7 +21,7 @@ exports.VERBS = [
     "lint",
     "test",
     "eval",
-    "scan",
+    "audit",
     "scaffold-test",
     "generate",
     "hook-runtime",