vigiles 7.0.0 → 9.0.0

package/dist/audit-html.d.ts

@@ -0,0 +1,20 @@
+import type { AuditReport } from "./audit-report.js";
+/**
+ * Candidate locations for the built template, relative to this module (`__dirname`
+ * is the compiled `dist/` at runtime, or `src/` under vitest). CommonJS output, so
+ * we use `__dirname`, not `import.meta`.
+ */
+export declare function templatePath(): string | null;
+/**
+ * Inject the report JSON into a template by replacing the quoted placeholder
+ * string with the JSON object literal. Pure — the testable core. Throws if the
+ * template is missing the placeholder.
+ */
+export declare function injectReportData(template: string, report: AuditReport): string;
+/**
+ * Render the self-contained HTML report (React template + injected data). Throws
+ * if the template hasn't been built — the caller (writeAuditHtml) catches that and
+ * skips the HTML, since the JSON + terminal report don't depend on it.
+ */
+export declare function renderAuditHtml(report: AuditReport): string;
+//# sourceMappingURL=audit-html.d.ts.map

package/dist/audit-html.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.templatePath = templatePath;
+exports.injectReportData = injectReportData;
+exports.renderAuditHtml = renderAuditHtml;
+/**
+ * The shareable HTML audit report — the prebuilt **Vite + React + shadcn** template
+ * (`report/`, built to one self-contained file at `dist/audit-report.template.html`)
+ * with the {@link AuditReport} JSON injected. The React app runs in the reader's
+ * browser, so the CLI stays runtime-dependency-light and the output is still a
+ * single offline file. There is ONE renderer (pure shadcn/Tailwind) — no inline-CSS
+ * fallback; the build guarantees the template exists, and if it somehow doesn't the
+ * caller skips the HTML (the JSON + terminal report still work).
+ *
+ * `<`/`>`/`&` are escaped on injection so report text can never break out of the
+ * `<script>`. `injectReportData` is the pure, testable core.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const PLACEHOLDER = "__VIGILES_DATA_PLACEHOLDER__";
+/**
+ * Candidate locations for the built template, relative to this module (`__dirname`
+ * is the compiled `dist/` at runtime, or `src/` under vitest). CommonJS output, so
+ * we use `__dirname`, not `import.meta`.
+ */
+function templatePath() {
+    const candidates = [
+        (0, node_path_1.resolve)(__dirname, "audit-report.template.html"), // dist/ (shipped)
+        (0, node_path_1.resolve)(__dirname, "..", "dist", "audit-report.template.html"), // src/ under vitest
+    ];
+    return candidates.find((p) => (0, node_fs_1.existsSync)(p)) ?? null;
+}
+/** Escape `<`, `>`, `&` so report text can never break out of the `<script>`. */
+function escapeForScript(json) {
+    return json.replace(/[<>&]/g, (ch) => "\\u00" + ch.charCodeAt(0).toString(16).padStart(2, "0"));
+}
+/**
+ * Inject the report JSON into a template by replacing the quoted placeholder
+ * string with the JSON object literal. Pure — the testable core. Throws if the
+ * template is missing the placeholder.
+ */
+function injectReportData(template, report) {
+    const re = new RegExp(`(["'])${PLACEHOLDER}\\1`);
+    if (!re.test(template)) {
+        throw new Error("audit report template is missing the data placeholder");
+    }
+    return template.replace(re, escapeForScript(JSON.stringify(report)));
+}
+/**
+ * Render the self-contained HTML report (React template + injected data). Throws
+ * if the template hasn't been built — the caller (writeAuditHtml) catches that and
+ * skips the HTML, since the JSON + terminal report don't depend on it.
+ */
+function renderAuditHtml(report) {
+    const p = templatePath();
+    if (!p) {
+        throw new Error("audit report template not built — run `npm run build` (builds report/), or use --json / --no-html");
+    }
+    return injectReportData((0, node_fs_1.readFileSync)(p, "utf-8"), report);
+}
+//# sourceMappingURL=audit-html.js.map

package/dist/audit-prompts.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Auto-generated trigger probes for `vigiles audit`'s model trigger tier.
+ *
+ * The trigger-rate eval needs a per-skill prompt set (does the description FIRE?
+ * — recall + precision). Authoring that set by hand was the friction that made
+ * the eval un-wowable. The trigger tier removes it: derive a small, DIVERSE probe
+ * set from each skill's own description — zero setup. `--prompts=<file>` still
+ * overrides for a rigorous, curated benchmark.
+ *
+ * Deterministic by design (no model needed to AUTHOR the probes — the model is
+ * spent RUNNING them). The trick that clears the diversity gate: extract a SHORT
+ * topic from the description (so the shared text stays small relative to the
+ * frame) and wrap it in lexically-distant frames. Measured min pairwise NCD
+ * ~0.27 across short/long descriptions — comfortably above {@link AUTO_MIN_DISTANCE}.
+ */
+import type { TriggerPromptSet } from "./scan-behavioral.js";
+export interface PromptSkill {
+    readonly name: string;
+    readonly description: string;
+}
+/** How many recall probes we generate per skill (each a distinct frame). */
+export declare const AUTO_RECALL_COUNT = 6;
+/**
+ * The diversity floor for AUTO probes — relaxed from the default 0.3 because a
+ * templated-but-varied machine probe legitimately shares a topic phrase (the
+ * generator's measured min is ~0.27). Still well above 0 → genuine copy-paste
+ * is caught; the gate's "vary the phrasing" advice is for hand-authored sets.
+ */
+export declare const AUTO_MIN_DISTANCE = 0.2;
+/**
+ * Extract a short, action-shaped topic from a description: drop boilerplate
+ * lead-ins ("A skill that…", "Use this skill to…"), take the first clause, cap
+ * at 8 words. Capping is load-bearing — a long verbatim topic makes the frames
+ * too similar (NCD collapses below the gate).
+ */
+export declare function topicOf(description: string): string;
+/** Recall probes for one skill: distinct frames around its extracted topic. */
+export declare function recallPrompts(description: string, count?: number): string[];
+/**
+ * Build a {@link TriggerPromptSet} from skill descriptions — zero-setup trigger
+ * probes. Each skill gets `recallPrompts` derived from its description plus the
+ * shared irrelevant bank for precision. Skills with an empty description are
+ * skipped (nothing to derive a topic from).
+ */
+export declare function autoTriggerPrompts(skills: readonly PromptSkill[], count?: number): TriggerPromptSet;
+//# sourceMappingURL=audit-prompts.d.ts.map

package/dist/audit-prompts.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTO_MIN_DISTANCE = exports.AUTO_RECALL_COUNT = void 0;
+exports.topicOf = topicOf;
+exports.recallPrompts = recallPrompts;
+exports.autoTriggerPrompts = autoTriggerPrompts;
+/** How many recall probes we generate per skill (each a distinct frame). */
+exports.AUTO_RECALL_COUNT = 6;
+/**
+ * The diversity floor for AUTO probes — relaxed from the default 0.3 because a
+ * templated-but-varied machine probe legitimately shares a topic phrase (the
+ * generator's measured min is ~0.27). Still well above 0 → genuine copy-paste
+ * is caught; the gate's "vary the phrasing" advice is for hand-authored sets.
+ */
+exports.AUTO_MIN_DISTANCE = 0.2;
+// Lexically-distant frames around a short topic. Order matters: the first N are
+// used, and they're arranged so any prefix stays diverse (verified in the test).
+const RECALL_FRAMES = [
+    (t) => `I need help to ${t} in my project right now.`,
+    (t) => `How do I ${t}? Walk me through the steps.`,
+    (t) => `Please ${t} before I open this pull request.`,
+    (t) => `What's the recommended way to ${t} on a large team?`,
+    (t) => `Can you take a look and ${t} for me?`,
+    (t) => `My task today: ${t} across the whole repo.`,
+    (t) => `Is there a tool that will ${t} automatically?`,
+    (t) => `Give me a checklist to ${t} thoroughly.`,
+];
+// Unrelated requests for the precision arm — varied, clearly off-topic, so a
+// well-scoped skill should NOT fire on them (a too-broad description that hijacks
+// these fails precision). Generic on purpose, distant from any one skill's topic.
+// Count is load-bearing: the auto trigger tier applies the diversity gate's
+// `minPrompts` floor (= AUTO_RECALL_COUNT) to BOTH arms, so the bank must hold at
+// least AUTO_RECALL_COUNT entries or the precision arm fails preflight and every
+// skill reports "unmeasured" instead of running.
+const IRRELEVANT_BANK = [
+    "What's the weather forecast for Tokyo this weekend?",
+    "Summarize the plot of Hamlet in two sentences.",
+    "Convert 100 US dollars to euros at today's rate.",
+    "Recommend a good pasta recipe for dinner tonight.",
+    "Who won the most Olympic gold medals in swimming?",
+    "Explain how photosynthesis works in plants.",
+    "Suggest a weekend hiking trail near Seattle.",
+];
+// Boilerplate lead-in words that carry no topical signal (skill descriptions
+// open with a verb — "Reviews…", "Generate…" — so stripping these from the front
+// never eats the real action). Applied iteratively until a content word remains.
+const LEAD_WORD = /^(a|an|the|this|use|skill|agent|tool|command|helper|that|which|to|for|when|invoked?|invoke|used?|helps?|you|with)\b[\s,:-]*/i;
+/**
+ * Extract a short, action-shaped topic from a description: drop boilerplate
+ * lead-ins ("A skill that…", "Use this skill to…"), take the first clause, cap
+ * at 8 words. Capping is load-bearing — a long verbatim topic makes the frames
+ * too similar (NCD collapses below the gate).
+ */
+function topicOf(description) {
+    let t = description.trim().toLowerCase();
+    let prev = "";
+    while (t !== prev) {
+        prev = t;
+        t = t.replace(LEAD_WORD, "");
+    }
+    const firstClause = t.split(/[.,;:!?]/)[0].trim();
+    const words = firstClause.split(/\s+/).filter(Boolean).slice(0, 8);
+    const topic = words.join(" ");
+    // Fall back to the raw (capped, lowercased) description if stripping left nothing.
+    return (topic || description.trim().toLowerCase().split(/\s+/).slice(0, 8).join(" "));
+}
+/** Recall probes for one skill: distinct frames around its extracted topic. */
+function recallPrompts(description, count = exports.AUTO_RECALL_COUNT) {
+    const topic = topicOf(description);
+    return RECALL_FRAMES.slice(0, count).map((frame) => frame(topic));
+}
+/**
+ * Build a {@link TriggerPromptSet} from skill descriptions — zero-setup trigger
+ * probes. Each skill gets `recallPrompts` derived from its description plus the
+ * shared irrelevant bank for precision. Skills with an empty description are
+ * skipped (nothing to derive a topic from).
+ */
+function autoTriggerPrompts(skills, count = exports.AUTO_RECALL_COUNT) {
+    const set = {};
+    for (const s of skills) {
+        if (!s.description.trim())
+            continue;
+        set[s.name] = {
+            prompts: recallPrompts(s.description, count),
+            irrelevant: [...IRRELEVANT_BANK],
+        };
+    }
+    return set;
+}
+//# sourceMappingURL=audit-prompts.js.map

package/dist/audit-report.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The `AuditReport` — the versioned JSON contract that IS the audit's product
+ * boundary. Everything renders FROM it: the local self-contained HTML report,
+ * `audit --json` for CI, and (later) an upload to a hosted dashboard. Because it's
+ * the wire format between the CLI and anything downstream, it is VERSIONED
+ * (`meta.schemaVersion`) and stable — additive changes only within a version.
+ *
+ * Pure: `buildAuditReport` assembles the report from the same deterministic pieces
+ * the terminal output uses (`auditScore` + `optimize` + the scan inventory) — no
+ * re-detection (one-detector-no-drift), no model, no clock (a `generatedAt`
+ * timestamp is attached by the CLI at write time, never by this pure builder, so
+ * the embedded-in-HTML form stays deterministic).
+ */
+import { type AuditScore } from "./audit-score.js";
+import { type Recommendation } from "./optimize.js";
+import type { AdoptabilityResult } from "./adoptability.js";
+import type { ScanReport } from "./scan.js";
+/** The current schema version. Bump only on a BREAKING change to the shape. */
+export declare const AUDIT_SCHEMA_VERSION = 1;
+export interface AuditReportMeta {
+    /** Wire-format version — consumers gate on this. */
+    readonly schemaVersion: typeof AUDIT_SCHEMA_VERSION;
+    readonly tool: "vigiles";
+    /** The vigiles version that produced the report. */
+    readonly vigilesVersion: string;
+    /** The detected/selected harness (`claude-code`, `codex`, …). */
+    readonly harness: string;
+    /** The audited directory. */
+    readonly dir: string;
+    /** ISO-8601 produced-at stamp — set by the CLI at write time (NOT the pure builder). */
+    readonly generatedAt?: string;
+}
+/** What the harness ships — the "inventory" surface counts. */
+export interface AuditInventory {
+    readonly skills: number;
+    readonly agents: number;
+    readonly hooks: number;
+    readonly commands: number;
+    readonly mcp: boolean;
+    readonly untested: number;
+}
+/**
+ * The full audit, as the dashboard / CI / HTML all consume it. Self-describing
+ * and versioned; additive-only within a `schemaVersion`.
+ */
+export interface AuditReport {
+    readonly meta: AuditReportMeta;
+    /** The four deterministic category rings + the weighted overall + grade. */
+    readonly score: AuditScore;
+    /** The deterministic, ranked fixes (the inline recommendations). */
+    readonly recommendations: readonly Recommendation[];
+    readonly inventory: AuditInventory;
+    /**
+     * The adoption preview — "what would vigiles catch in your repo?" Present only
+     * when the model-gated tier ran (behind consent); a deterministic read omits it.
+     * Additive/optional, so the schema version is unchanged.
+     */
+    readonly adoptability?: AdoptabilityResult;
+}
+export interface BuildAuditReportOptions {
+    readonly harness: string;
+    readonly vigilesVersion: string;
+}
+/**
+ * Assemble the versioned {@link AuditReport} from a scan report — pure, no clock.
+ * The CLI attaches `meta.generatedAt` when it writes the JSON artifact; the
+ * HTML-embedded form omits it so the rendered file stays deterministic.
+ */
+export declare function buildAuditReport(report: ScanReport, opts: BuildAuditReportOptions): AuditReport;
+//# sourceMappingURL=audit-report.d.ts.map

package/dist/audit-report.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIT_SCHEMA_VERSION = void 0;
+exports.buildAuditReport = buildAuditReport;
+/**
+ * The `AuditReport` — the versioned JSON contract that IS the audit's product
+ * boundary. Everything renders FROM it: the local self-contained HTML report,
+ * `audit --json` for CI, and (later) an upload to a hosted dashboard. Because it's
+ * the wire format between the CLI and anything downstream, it is VERSIONED
+ * (`meta.schemaVersion`) and stable — additive changes only within a version.
+ *
+ * Pure: `buildAuditReport` assembles the report from the same deterministic pieces
+ * the terminal output uses (`auditScore` + `optimize` + the scan inventory) — no
+ * re-detection (one-detector-no-drift), no model, no clock (a `generatedAt`
+ * timestamp is attached by the CLI at write time, never by this pure builder, so
+ * the embedded-in-HTML form stays deterministic).
+ */
+const audit_score_js_1 = require("./audit-score.js");
+const optimize_js_1 = require("./optimize.js");
+/** The current schema version. Bump only on a BREAKING change to the shape. */
+exports.AUDIT_SCHEMA_VERSION = 1;
+/**
+ * Assemble the versioned {@link AuditReport} from a scan report — pure, no clock.
+ * The CLI attaches `meta.generatedAt` when it writes the JSON artifact; the
+ * HTML-embedded form omits it so the rendered file stays deterministic.
+ */
+function buildAuditReport(report, opts) {
+    return {
+        meta: {
+            schemaVersion: exports.AUDIT_SCHEMA_VERSION,
+            tool: "vigiles",
+            vigilesVersion: opts.vigilesVersion,
+            harness: opts.harness,
+            dir: report.dir,
+        },
+        score: (0, audit_score_js_1.auditScore)(report),
+        recommendations: (0, optimize_js_1.optimize)(report).recommendations,
+        inventory: {
+            skills: report.skills.length,
+            agents: report.agents.length,
+            // All hooks, file-backed + inline — matches formatScanReport and the
+            // emptiness/scoring count, so a JSON/HTML "What it ships" never reports 0
+            // hooks for an inline-hook-only harness.
+            hooks: report.hooks.length + report.inlineHooks,
+            commands: report.commands,
+            mcp: report.mcp,
+            untested: report.untested,
+        },
+    };
+}
+//# sourceMappingURL=audit-report.js.map