vigiles 27.3.0 → 29.0.0

package/dist/scan.js

@@ -35,10 +35,15 @@ exports.expandMarketplace = expandMarketplace;
 exports.formatScanReport = formatScanReport;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
+// The COMPOSITION-ROOT loader, not the `vigiles/claude-code` wrapper: this
+// module always passes a layout explicitly (it never wanted the wrapper's
+// Claude Code default), and only the generic one takes the `ExcludeSet` that
+// makes `.vigilesrc.json#exclude` reach surface discovery.
+const plugin_loader_js_1 = require("./plugin-loader.js");
 const layout_js_1 = require("./adapters/claude-code/layout.js");
 const dialect_js_1 = require("./adapters/claude-code/dialect.js");
 const plugin_loader_js_2 = require("./plugin-loader.js");
+const score_core_js_1 = require("./score-core.js");
 const skill_refs_js_1 = require("./skill-refs.js");
 const hook_events_js_1 = require("./core/hook-events.js");
 const mcp_config_js_1 = require("./core/mcp-config.js");
@@ -49,6 +54,9 @@ const mcp_contract_message_js_1 = require("./core/mcp-contract-message.js");
 const mcp_hook_js_1 = require("./core/mcp-hook.js");
 const merge_conflict_js_1 = require("./core/merge-conflict.js");
 const plugin_dir_layout_js_1 = require("./core/plugin-dir-layout.js");
+const surface_discovery_js_1 = require("./core/surface-discovery.js");
+const surface_discovery_fs_js_1 = require("./surface-discovery-fs.js");
+const layout_registry_js_1 = require("./layout-registry.js");
 const hook_block_ineffective_js_1 = require("./core/hook-block-ineffective.js");
 const hook_matcher_js_1 = require("./core/hook-matcher.js");
 const test_coverage_js_1 = require("./test-coverage.js");
@@ -139,8 +147,23 @@ function ownTestSignalOnDisk(dir) {
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
 function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts = {}) {
     const lay = layout ?? layout_js_1.claudeCodeLayout;
-    const cls = (0, scan_core_js_1.makeClassifier)(lay);
-    const loaded = (0, plugin_loader_js_1.loadPlugin)(dir, lay);
+    // The declared harnesses, or the single positional one — so every path below
+    // is the multi-harness path and a one-entry list is not a second code path.
+    const declared = opts.harnesses && opts.harnesses.length > 0
+        ? opts.harnesses
+        : [{ layout: lay, dialect, roots: [] }];
+    // A path is a surface if ANY declared harness reads it as one. Classifying a
+    // merged file map with one layout would drop the other harness's surfaces
+    // silently — the same shape of miss as grading a scan that opened nothing.
+    const cls = (0, scan_core_js_1.makeUnionClassifier)(declared.map((h) => h.layout));
+    const loaded = (0, plugin_loader_js_1.loadPlugins)(dir, declared.map((h) => ({ layout: h.layout, roots: h.roots })), opts.excludes);
+    // WHICH harness's instruction file this repo actually has. The first declared
+    // one that is present, not the first one declared: a repo listing
+    // `claude-code` before `codex` and shipping only `AGENTS.md` has an
+    // instruction file, and saying it does not was half of #240's wrong grade.
+    // Its dialect carries the budget the weight below is measured against, so the
+    // file named and the limit it is judged by come from the same harness.
+    const instructionHarness = declared.find((h) => loaded.files[h.layout.instructionFile] !== undefined) ?? declared[0];
     // Parse the raw `settings.hooks` ONCE at the boundary (parse-don't-validate):
     // tolerant of the Claude Code nested shape AND the Codex flat shape, so every
     // hook detector below consumes typed `HookRegistration[]` instead of re-walking
@@ -157,10 +180,11 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
     const eventNames = (0, hook_normalize_js_1.hookEventNames)(loaded.settings.hooks);
     const allHookEventIssues = (0, hook_events_js_1.verifyHookEvents)(eventNames, dialect);
     const hookEventIssues = (0, hook_events_js_1.scoredIssues)(allHookEventIssues);
-    const instructions = loaded.files[lay.instructionFile] !== undefined
+    const instructionFile = instructionHarness.layout.instructionFile;
+    const instructions = loaded.files[instructionFile] !== undefined
         ? {
-            file: lay.instructionFile,
-            hasSpec: (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.resolve)(dir), `${lay.instructionFile}.spec.ts`)),
+            file: instructionFile,
+            hasSpec: (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.resolve)(dir), `${instructionFile}.spec.ts`)),
         }
         : null;
     const mcpServers = collectMcpServers((0, node_path_1.resolve)(dir), lay);
@@ -188,7 +212,17 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
     // deterministic tier (`Tested`), and the real-model tier (`Evaluated`). The
     // tiers differ in cost, cadence AND in the question they answer, so collapsing
     // them here would make the difference unrecoverable downstream.
-    const coverage = (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: dir, layout: lay });
+    const coverage = (0, test_coverage_js_1.findUntestedSurfaces)({
+        basePath: dir,
+        layout: lay,
+        // The SAME `.vigilesrc.json#exclude`, in this walk's string face. Untested-
+        // surface discovery is a second walk over the same trees, so leaving it out
+        // would have excluded a skill from the GRADE while still naming it in
+        // "Untested surfaces: 1" — a report contradicting itself about whether the
+        // file exists. `exclude` here NARROWS (it unions with DEFAULT_IGNORE), which
+        // is the documented relationship between the repo floor and a rule's own list.
+        exclude: opts.excludes ? [...opts.excludes.ignore] : undefined,
+    });
     const caveats = (0, test_coverage_js_1.coverageCaveats)(coverage);
     return {
         dir,
@@ -229,6 +263,11 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         trifectaFindings,
         skillResourceIssues: skillResourceFindings,
         skillFenceIssues: skillFenceFindings,
+        unclaimedSurfaces: (0, surface_discovery_js_1.unclaimedSurfaceFindings)((0, surface_discovery_fs_js_1.boundedSurfacePaths)((0, node_path_1.resolve)(dir), opts.excludes), layout_registry_js_1.REGISTERED_LAYOUTS, declared.map((h) => ({
+            harness: h.layout.name,
+            layout: h.layout,
+            roots: h.roots,
+        }))),
         pluginLayoutIssues: (0, plugin_dir_layout_js_1.pluginDirLayoutIssues)((0, node_path_1.resolve)(dir, (0, node_path_1.dirname)(lay.manifestPath)), 
         // The hooks dir is a misplaceable functional surface too, but it lives in
         // the layout as a convention PATH (`hooks/hooks.json`), not in surfaceDirs
@@ -257,8 +296,13 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
                 return (0, node_fs_1.existsSync)(p) ? nodeReadFile(p) : undefined;
             }).map(merge_conflict_js_1.mergeConflictWarning),
         ],
-        instructionWeight: dialect.instructionBudget
-            ? (0, instruction_weight_js_1.weighInstructions)(readAlwaysLoaded(dir, dialect.instructionBudget), dialect.instructionBudget)
+        // Measured under the dialect whose instruction file this repo HAS — see
+        // `instructionHarness`. A budget is a harness's own number in a harness's own
+        // unit (Claude Code counts 40 000 chars, Codex 32 768 bytes), so there is no
+        // meaningful sum across two; reporting the one that owns the file that
+        // exists is the only reading that is true of something.
+        instructionWeight: instructionHarness.dialect.instructionBudget
+            ? (0, instruction_weight_js_1.weighInstructions)(readAlwaysLoaded(dir, instructionHarness.dialect.instructionBudget), instructionHarness.dialect.instructionBudget)
             : null,
         untested: coverage.untested.length,
         untestedHarness: coverage.harness.untested.length,
@@ -588,6 +632,11 @@ function formatScanReport(r) {
     out.push(...section("Skill bundled resources", r.skillResourceIssues.map((s) => `  ✗ ${s.name}: ${s.finding.ref} (line ${String(s.finding.line)}) — bundled resource not found`)));
     out.push(...section("Invisible skills (missing frontmatter fence)", r.skillFenceIssues.map((s) => `  ✗ ${s.name} (${s.path}): opens with \`${s.finding.key}:\` but no \`---\` fence — loads as body, never fires`)));
     out.push(...section("Misplaced plugin directories", r.pluginLayoutIssues.map((p) => `  ✗ ${p.message}`)));
+    // A harness sitting where no adapter reads (#240). Printed as a ✗ section like
+    // any other structural defect, because that is what it is: the grade above it
+    // was computed without this directory in it, and the old behaviour was to say
+    // nothing at all while returning A (100/100).
+    out.push(...section("Surfaces no harness reads", r.unclaimedSurfaces.map((u) => `  ✗ ${u.message}`)));
     out.push(...section("Lethal trifecta across delegation (blast radius)", r.delegationTrifecta.map((d) => `  ⚠ ${d.finding.name} (${d.path}): ${d.finding.message}`)));
     out.push(...section("Ineffective hook guards (false confidence)", r.hookBlockFindings.map((h) => `  ✗ [${h.event}] ${h.scriptPath ?? "(inline)"}: ${h.message}`)));
     out.push(...section("Hook matchers that don't fire as written", r.hookMatcherFindings.map((m) => `  ✗ ${m.message}`)));
@@ -658,6 +707,7 @@ function formatScanReport(r) {
         r.skillResourceIssues.length +
         r.skillFenceIssues.length +
         r.pluginLayoutIssues.length +
+        r.unclaimedSurfaces.length +
         r.hookBlockFindings.length +
         r.hookMatcherFindings.length +
         // Only HARD trifectas (✗) count as STRUCTURAL defects here. Both severities are
@@ -667,9 +717,15 @@ function formatScanReport(r) {
         // "broken" in the CLI summary is a separate, louder call. The delegation-trifecta
         // ⚠ risk is ungraded and does NOT count either.
         r.trifectaFindings.filter((t) => t.finding.severity === "hard").length;
-    out.push(broken === 0
-        ? "✓ no structural issues found"
-        : `⚠ ${String(broken)} structural issue(s) — see ✗/⚠ above`);
+    out.push(broken > 0
+        ? `⚠ ${String(broken)} structural issue(s) — see ✗/⚠ above`
+        : // 🔴 "NOTHING WAS FOUND" IS NOT "NOTHING IS WRONG" (#240). With zero
+            // surfaces read, `broken` is zero for want of anything to count, and this
+            // line was the sentence the reporter quoted under an A (100): a repo whose
+            // 37 skills sat in a directory this tool does not know by name.
+            (0, score_core_js_1.isEmptyMachine)(r)
+                ? "⚠ nothing to check — 0 skills, 0 agents, 0 commands were read"
+                : "✓ no structural issues found");
     return out.join("\n");
 }
 //# sourceMappingURL=scan.js.map

package/dist/score-core.js

@@ -290,6 +290,14 @@ function reportDeductions(r) {
             weight: exports.W_NO_DESCRIPTION,
             label: "functional dir(s) misplaced inside `.claude-plugin/` (invisible)",
         },
+        // A surface dir NO registered harness reads (#240). Same weight and label as
+        // the Structure ring's row by construction — the two are kept identical on
+        // purpose, so the headline and the breakdown cannot disagree about it.
+        {
+            n: r.unclaimedSurfaces.length,
+            weight: exports.W_NO_DESCRIPTION,
+            label: "surface dir(s) no harness reads (not in this grade)",
+        },
         {
             n: r.hookBlockFindings.length,
             weight: exports.W_MISSING_HOOK,

package/dist/setup-plan.d.ts

@@ -133,7 +133,8 @@ export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "unt
  */
 export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher", "doc-refs"];
 export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
-    harness: string | string[];
+    /** Canonical harness names this repo targets, in the order to declare them. */
+    harnesses: readonly string[];
     strict: boolean;
     reportOnly?: boolean;
     /** Whether the LINT pillar is on (default true). The rule gate is a lint-layer

package/dist/setup-plan.js

@@ -148,8 +148,13 @@ exports.NUDGE_RULES = [
 function mergeProjectConfig(existing, opts) {
     const config = { ...existing };
     let changed = false;
-    if (config.harness === undefined) {
-        config.harness = opts.harness;
+    // The NESTED key (#240). `init` writes the declaration with no roots — a repo
+    // whose surfaces sit where its harness reads them needs none, and a root is a
+    // fact only the owner knows. Writing the flat `harness`/`surfaceRoots` pair
+    // here would emit a config the loader now REFUSES, which is why this one line
+    // moved with the shape even though the rest of `init` did not.
+    if (config.harnesses === undefined) {
+        config.harnesses = Object.fromEntries(opts.harnesses.map((h) => [h, {}]));
         changed = true;
     }
     // The rule gate belongs to the LINT layer — a test-only setup records the

package/dist/surface-discovery-fs.d.ts

@@ -0,0 +1,12 @@
+import { type DiscoveredSurface } from "./core/surface-discovery.js";
+import { type ExcludeSet } from "./exclude.js";
+/**
+ * Repo-relative paths of every file inside the bounded root set's surface dirs.
+ *
+ * Exported for the test that proves the bound holds — a caller that wants
+ * surfaces wants {@link discoverSurfacesOnDisk}.
+ */
+export declare function boundedSurfacePaths(root: string, excludes?: ExcludeSet): readonly string[];
+/** Every surface the bounded walk finds on disk under `root`, by shape. */
+export declare function discoverSurfacesOnDisk(root: string, excludes?: ExcludeSet): readonly DiscoveredSurface[];
+//# sourceMappingURL=surface-discovery-fs.d.ts.map

package/dist/surface-discovery-fs.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundedSurfacePaths = boundedSurfacePaths;
+exports.discoverSurfacesOnDisk = discoverSurfacesOnDisk;
+/**
+ * The DISK half of surface discovery: enumerate the repo-relative paths inside
+ * the bounded root set, so the pure classifier in `src/core/surface-discovery.ts`
+ * can say which of them are surfaces.
+ *
+ * Paths only — never contents. Discovery answers "is there a surface here that
+ * nobody reads", which is a question about NAMES; reading a file nobody claims
+ * would be doing the very work the finding says is not being done.
+ *
+ * 🔴 THE WALK IS BOUNDED BY CONSTRUCTION, NOT BY A DEPTH COUNTER. One `readdir`
+ * of the repo root, one per DOT-DIRECTORY found there, and then descent ONLY
+ * into a directory named by `SURFACE_SHAPES` (`skills`/`agents`/`commands`).
+ * `src/`, `packages/`, `node_modules/` are never entered — there is no traversal
+ * that could reach them, so there is no budget to tune and no flag to get wrong.
+ * The module header of `core/surface-discovery.ts` holds the reason the bound is
+ * this shape and why an adapter may not widen it.
+ *
+ * `exclude` is applied PER ENTRY, not only at the entry point, for the reason
+ * b751471 measured: a vendored tree is normally excluded at its own root
+ * (`skills/vendored`), which is a DESCENDANT of a surface dir, so an
+ * entry-point-only check lets every one of its files through. Without this, a
+ * discovery pass that walks dot-directories would grade copied-in corpora as the
+ * repo's own work and the repo's only stated remedy would not reach it.
+ *
+ * Symlinks go through the ONE policy (`src/fs-walk.ts`): `walkableRoot` at each
+ * surface dir the layout-blind walk opens, `entryOf` for every entry below it.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const surface_discovery_js_1 = require("./core/surface-discovery.js");
+const exclude_js_1 = require("./exclude.js");
+const fs_walk_js_1 = require("./fs-walk.js");
+/** The shape directory names, as a set — the only dirs the walk descends into. */
+const SHAPE_DIRS = new Set(surface_discovery_js_1.SURFACE_SHAPES.map((s) => s.dir));
+/** Directory entry names under `dir`, or `[]` when it cannot be read. */
+function namesIn(dir) {
+    try {
+        return (0, node_fs_1.readdirSync)(dir);
+    }
+    catch {
+        return []; // unreadable: the same silence `entryOf` gives, never a throw
+    }
+}
+/** Every file path (repo-relative, POSIX) under an opened surface directory. */
+function filesUnder(root, rel, excluded, out) {
+    const abs = (0, node_path_1.join)(root, rel);
+    for (const name of namesIn(abs)) {
+        const childRel = `${rel}/${name}`;
+        const childAbs = (0, node_path_1.join)(root, childRel);
+        if (excluded(childAbs))
+            continue;
+        const entry = (0, fs_walk_js_1.entryOf)(childAbs);
+        if (entry.kind === "dir")
+            filesUnder(root, childRel, excluded, out);
+        // `childRel` is built with `/` from `readdir` names (which never contain a
+        // separator), so it is already the POSIX form the classifier matches on.
+        else if (entry.kind === "file")
+            out.push(childRel);
+    }
+}
+/**
+ * Repo-relative paths of every file inside the bounded root set's surface dirs.
+ *
+ * Exported for the test that proves the bound holds — a caller that wants
+ * surfaces wants {@link discoverSurfacesOnDisk}.
+ */
+function boundedSurfacePaths(root, excludes) {
+    const excluded = (0, exclude_js_1.excludedBy)(excludes);
+    const out = [];
+    // The repo root is a discovery root, and so is each of its dot-directories.
+    const roots = ["", ...namesIn(root).filter((n) => (0, surface_discovery_js_1.isDiscoveryRoot)(n))];
+    for (const base of roots.filter((b) => b === "" || !excluded((0, node_path_1.join)(root, b)))) {
+        for (const rel of surfaceDirsIn(root, base)) {
+            if (openableSurfaceDir(root, rel, excluded))
+                filesUnder(root, rel, excluded, out);
+        }
+    }
+    return out;
+}
+/** Repo-relative surface dirs directly under one discovery root. */
+function surfaceDirsIn(root, base) {
+    const baseAbs = base === "" ? root : (0, node_path_1.join)(root, base);
+    return namesIn(baseAbs)
+        .filter((n) => SHAPE_DIRS.has(n))
+        .map((n) => (base === "" ? n : `${base}/${n}`));
+}
+/** May the walk open `<root>/<rel>` as a surface directory? */
+function openableSurfaceDir(root, rel, excluded) {
+    const abs = (0, node_path_1.join)(root, rel);
+    if (excluded(abs))
+        return false;
+    // A FILE named `skills` is not a surface dir. A SYMLINKED one is (`entryOf`
+    // says "skip" for it, deliberately — that rule is for entries the walk finds
+    // INSIDE), so the entry point gets `walkableRoot`, which follows it unless
+    // the target contains the scanned root. See src/fs-walk.ts.
+    if ((0, fs_walk_js_1.entryOf)(abs).kind === "file")
+        return false;
+    return (0, fs_walk_js_1.walkableRoot)(abs, root);
+}
+/** Every surface the bounded walk finds on disk under `root`, by shape. */
+function discoverSurfacesOnDisk(root, excludes) {
+    return (0, surface_discovery_js_1.discoverSurfaces)(boundedSurfacePaths(root, excludes));
+}
+//# sourceMappingURL=surface-discovery-fs.js.map