vigiles 30.0.1 → 31.0.0

package/dist/linting.js

@@ -1,38 +1,26 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles/linting` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-linting.api.md`, which
+// `npm run api:check` fails on.
 /**
- * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
- * files. The spec builders/types that describe a CLAUDE.md, a SKILL.md or an
- * agent, plus the public compile entry points, under one concern-named import.
+ * `vigiles/linting` — Pillar 1 entry point: what a spec AUTHOR imports to describe a CLAUDE.md,
+ * a SKILL.md or an agent — the builders, the verified-reference constructors and their types.
+ * Compiling is the CLI's job (`vigiles compile` / `vigiles lint`), not this subpath's.
  *
- * Curated (named, not `export *`) so the internal compiler validators, hash
- * helpers, and the linter cross-reference ENGINE stay out of the public surface,
- * the api reports, and the docs site (the CLI imports those from the source).
+ * Curated (named, not `export *`) so the internal compiler, validators, hash helpers and the
+ * linter cross-reference ENGINE stay out of the public surface, the api reports and the docs.
  *
- * 🔴 THAT SENTENCE USED TO BE FALSE, and so did the one after it (fixed
- * 2026-08-21). The file claimed to be curated while `export * from
- * "./core/spec.js"` sat one line below it, and it claimed "the spec builders are
- * also at the package root (`vigiles`)" — measured against `vigiles.api.md`: 191
- * exports there and zero matches for `claude`, `agent`, `enforce` or `result`.
- * The builders' second door is `vigiles/spec`, not the root. Both claims read as
- * documentation of a decision and were descriptions of the opposite one; a
- * header nobody re-reads is where an `export *` hides best.
- *
- * WHAT THE CURATION DROPS (28 symbols, measured — nothing in this repo imported
- * any of them from here; every in-repo user takes them from `vigiles/spec`, and
- * the one live consumer of this subpath in the docs takes `compileAgent`): the
- * typed-COMPOSITION family — `experimental_pipe`/`_pipeStep`/`_start`/
- * `_andThen`/`_needs`, `Pipeline`, `PipeStep`, `Supplies`, `Handoff`,
- * `NeedsContract`, `OkOf`, `TypedAgentSpec`, `TypedOutcome`, `Shape`,
- * `OutputFieldType` and the `result()` builder. Those verify HANDOFFS between
- * workers; they compile to nothing and lint nothing, so they are not pillar 1.
- *
- * ⚠️ The cut is not a clean slice along that line, and pretending otherwise
- * would strand a signature: the `result()` FUNCTION leaves, but the
- * `OutputContract` TYPE stays, because `compileAgent`/`compileSkill` name it in
- * their own types. A consumer who needs to BUILD one imports `vigiles/spec`.
+ * WHAT THE CURATION DROPS (28 symbols, measured 2026-08-21 — nothing in this repo imported any
+ * of them from here; every in-repo user takes them from `vigiles/spec`): the typed-COMPOSITION
+ * family — `experimental_pipe`/`_pipeStep`/`_start`/`_andThen`/`_needs`, `Pipeline`, `PipeStep`,
+ * `Supplies`, `Handoff`, `NeedsContract`, `OkOf`, `TypedAgentSpec`, `TypedOutcome`, `Shape`,
+ * `OutputFieldType` and the `result()` builder. Those verify HANDOFFS between workers; they
+ * compile to nothing and lint nothing, so they are not pillar 1.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.compileRailway = exports.compileAgent = exports.compileSkill = exports.compileClaude = exports.BUILTIN_LINTERS = exports.agent = exports.instructions = exports.claude = exports.experimental_agent = exports.experimental_skill = exports.project = exports.glob = exports.dir = exports.ref = exports.symbol = exports.cmd = exports.file = exports.guard = exports.guidance = exports.enforce = exports.experimental_effect = exports.prose = exports.instructionFile = void 0;
+exports.BUILTIN_LINTERS = exports.agent = exports.instructions = exports.claude = exports.experimental_agent = exports.experimental_skill = exports.project = exports.glob = exports.dir = exports.ref = exports.symbol = exports.cmd = exports.file = exports.guard = exports.guidance = exports.enforce = exports.experimental_effect = exports.prose = exports.instructionFile = void 0;
 // --- the spec authoring builders: rules, refs, prose, and the three spec kinds ---
 var spec_js_1 = require("./core/spec.js");
 // instruction files
@@ -67,12 +55,11 @@ Object.defineProperty(exports, "instructions", { enumerable: true, get: function
 Object.defineProperty(exports, "agent", { enumerable: true, get: function () { return spec_js_1.agent; } });
 var spec_js_2 = require("./core/spec.js");
 Object.defineProperty(exports, "BUILTIN_LINTERS", { enumerable: true, get: function () { return spec_js_2.BUILTIN_LINTERS; } });
-// Compile: only the public entry points + their option/result types.
-var compile_js_1 = require("./core/compile.js");
-Object.defineProperty(exports, "compileClaude", { enumerable: true, get: function () { return compile_js_1.compileClaude; } });
-Object.defineProperty(exports, "compileSkill", { enumerable: true, get: function () { return compile_js_1.compileSkill; } });
-Object.defineProperty(exports, "compileAgent", { enumerable: true, get: function () { return compile_js_1.compileAgent; } });
-Object.defineProperty(exports, "compileRailway", { enumerable: true, get: function () { return compile_js_1.compileRailway; } });
+// NO COMPILE ENTRY POINTS HERE (removed in the major that ships #257). `compileClaude`,
+// `compileSkill`, `compileAgent`, `compileRailway` and their option/result types were public
+// with no external caller — measured across the repos that depend on vigiles, every import is a
+// spec builder — and the promise froze them synchronous while the symbol check they run became
+// async. Spec authors run `vigiles compile`; the CLI imports the compiler from source.
 // core/linters is the cross-reference ENGINE (checkLinterRule/editDistance/…),
 // consumed by compile — not part of the public authoring surface.
 //# sourceMappingURL=linting.js.map

package/dist/local-files-tracked.d.ts

@@ -5,13 +5,30 @@
  * every "cannot tell".
  */
 export declare function trackedLocalFiles(root: string): string[];
+/**
+ * Does the COMMITTED `.vigiles/.gitignore` (the one at `HEAD`) lack entries
+ * vigiles needs — i.e. will vigiles' additions show up as a change to a tracked
+ * file until someone commits them.
+ *
+ * The question is asked of `HEAD`, not of the worktree's dirtiness, and that
+ * is the point (Codex review on #275, third pass). "The file is modified" was
+ * the earlier predicate; it could not tell vigiles' additions from the owner's
+ * own unrelated edit, and then advised committing work in progress. Reading the
+ * committed copy answers only for vigiles' entries, staged or not, and says
+ * nothing once they are committed, whatever else the owner is editing.
+ * `HEAD:./path`, not `HEAD:path`: without `./` git resolves the path from the
+ * REPOSITORY root, so a package nested in a larger worktree read the wrong file
+ * — or none — and stayed silent (Codex review on #275, gitrevisions(7)).
+ * Silent on every "cannot tell": not in a repo, no `HEAD`, file not committed.
+ */
+export declare function committedIgnoreFileLacksEntries(root: string): boolean;
 /**
  * The one-line warning for {@link trackedLocalFiles}, or `null` when there is
  * nothing to say. Files inside a tracked local DIRECTORY (`state/`,
  * `eval-cache/`) are named by that directory, so one line stays one line and the
  * command it prints untracks all of them.
  */
-export declare function formatTrackedLocalFiles(tracked: readonly string[]): string | null;
+export declare function formatTrackedLocalFiles(tracked: readonly string[], committedLacksEntries?: boolean): string | null;
 /** Print the warning for `root` to stderr when there is one. CLI-only. */
 export declare function warnTrackedLocalFiles(root: string): void;
 //# sourceMappingURL=local-files-tracked.d.ts.map

package/dist/local-files-tracked.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trackedLocalFiles = trackedLocalFiles;
+exports.committedIgnoreFileLacksEntries = committedIgnoreFileLacksEntries;
 exports.formatTrackedLocalFiles = formatTrackedLocalFiles;
 exports.warnTrackedLocalFiles = warnTrackedLocalFiles;
 /**
@@ -20,6 +21,8 @@ exports.warnTrackedLocalFiles = warnTrackedLocalFiles;
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = require("node:path");
 const local_files_js_1 = require("./local-files.js");
+/** `.vigiles/.gitignore`, repo-relative. */
+const IGNORE_FILE = node_path_1.posix.join(local_files_js_1.VIGILES_DIR, local_files_js_1.LOCAL_GITIGNORE_FILE);
 /**
  * The per-checkout files under `<root>/.vigiles/` that git tracks, as
  * repo-relative paths from `root`. Empty when nothing is tracked, when `root` is
@@ -42,28 +45,67 @@ function trackedLocalFiles(root) {
         return [];
     }
 }
+/**
+ * Does the COMMITTED `.vigiles/.gitignore` (the one at `HEAD`) lack entries
+ * vigiles needs — i.e. will vigiles' additions show up as a change to a tracked
+ * file until someone commits them.
+ *
+ * The question is asked of `HEAD`, not of the worktree's dirtiness, and that
+ * is the point (Codex review on #275, third pass). "The file is modified" was
+ * the earlier predicate; it could not tell vigiles' additions from the owner's
+ * own unrelated edit, and then advised committing work in progress. Reading the
+ * committed copy answers only for vigiles' entries, staged or not, and says
+ * nothing once they are committed, whatever else the owner is editing.
+ * `HEAD:./path`, not `HEAD:path`: without `./` git resolves the path from the
+ * REPOSITORY root, so a package nested in a larger worktree read the wrong file
+ * — or none — and stayed silent (Codex review on #275, gitrevisions(7)).
+ * Silent on every "cannot tell": not in a repo, no `HEAD`, file not committed.
+ */
+function committedIgnoreFileLacksEntries(root) {
+    try {
+        const r = (0, node_child_process_1.spawnSync)("git", ["show", `HEAD:./${IGNORE_FILE}`], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (r.status !== 0 || typeof r.stdout !== "string")
+            return false;
+        return (0, local_files_js_1.entriesNotInEffect)(r.stdout).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The one-line warning for {@link trackedLocalFiles}, or `null` when there is
  * nothing to say. Files inside a tracked local DIRECTORY (`state/`,
  * `eval-cache/`) are named by that directory, so one line stays one line and the
  * command it prints untracks all of them.
  */
-function formatTrackedLocalFiles(tracked) {
-    if (tracked.length === 0)
-        return null;
-    // `.vigiles/state/.claude/hooks/x.json` → `.vigiles/state`: the list entry.
-    const entries = [
-        ...new Set(tracked.map((p) => p.split("/").slice(0, 2).join("/"))),
-    ];
-    const one = entries.length === 1;
-    return (`⚠ ${entries.join(", ")} ${one ? "is" : "are"} tracked by git, but ` +
-        `${local_files_js_1.VIGILES_DIR}/ local files describe one checkout and would credit a ` +
-        `machine where nothing ran. .gitignore does not untrack a tracked file; ` +
-        `untrack ${one ? "it" : "them"} once: git rm -r --cached ${entries.join(" ")}`);
+function formatTrackedLocalFiles(tracked, committedLacksEntries = false) {
+    const lines = [];
+    if (tracked.length > 0) {
+        // `.vigiles/state/.claude/hooks/x.json` → `.vigiles/state`: the list entry.
+        const entries = [
+            ...new Set(tracked.map((p) => p.split("/").slice(0, 2).join("/"))),
+        ];
+        const one = entries.length === 1;
+        lines.push(`⚠ ${entries.join(", ")} ${one ? "is" : "are"} tracked by git, but ` +
+            `${local_files_js_1.VIGILES_DIR}/ local files describe one checkout and would credit a ` +
+            `machine where nothing ran. .gitignore does not untrack a tracked file; ` +
+            `untrack ${one ? "it" : "them"} once: git rm -r --cached ${entries.join(" ")}`);
+    }
+    // Not "untrack it": the repo may keep its own rules there, and untracking
+    // would take them away from everyone else.
+    if (committedLacksEntries)
+        lines.push(`⚠ ${IGNORE_FILE} is tracked by git and its committed version lacks ` +
+            `vigiles' local-file entries, which vigiles adds to your copy. Commit ` +
+            `those lines once; entries are appended only when missing.`);
+    return lines.length > 0 ? lines.join("\n") : null;
 }
 /** Print the warning for `root` to stderr when there is one. CLI-only. */
 function warnTrackedLocalFiles(root) {
-    const line = formatTrackedLocalFiles(trackedLocalFiles(root));
+    const line = formatTrackedLocalFiles(trackedLocalFiles(root), committedIgnoreFileLacksEntries(root));
     if (line)
         process.stderr.write(line + "\n");
 }

package/dist/local-files.d.ts

@@ -35,6 +35,8 @@ export declare const LOCAL_FILES: readonly LocalFile[];
  */
 export declare const COMMITTED_PATHS: readonly string[];
 /** The header comment on a `.vigiles/.gitignore` vigiles creates. */
+/** The ignore file vigiles keeps inside `.vigiles/`. One spelling for every reader. */
+export declare const LOCAL_GITIGNORE_FILE = ".gitignore";
 export declare const LOCAL_GITIGNORE_HEADER: readonly string[];
 /** The ignore lines, in order: every local path, then the file itself. */
 export declare function localIgnoreEntries(): string[];
@@ -49,8 +51,9 @@ export declare function localIgnoreEntries(): string[];
  *   or reordered. Appending is enough because git's last matching rule wins.
  *
  * "In effect" is judged the way git reads the file, not by text membership:
- * lines in order, a later `!/entry` cancels an earlier `/entry`, and leading
- * whitespace is part of the pattern (only trailing whitespace is dropped).
+ * lines in order, a later negation cancels an earlier `/entry` (see
+ * {@link inEffect}), and leading whitespace is part of the pattern (only
+ * trailing whitespace is dropped).
  * Both cases were measured with `git check-ignore`: `/coverage.json` followed
  * by `!/coverage.json`, and ` /coverage.json`, each leave the file NOT
  * ignored while a trimmed set would call the entry present.
@@ -58,5 +61,11 @@ export declare function localIgnoreEntries(): string[];
  * Costs one read on the hot path. Best-effort: any fs error is swallowed —
  * keeping git tidy must never break a hook, a test run or an audit.
  */
+/**
+ * The entries a `.vigiles/.gitignore` with this content does NOT put in effect.
+ * One reader for both questions — "what to append" ({@link ensureLocalFilesIgnored})
+ * and "does the committed copy already carry them" (the CLI's tracked-file check).
+ */
+export declare function entriesNotInEffect(content: string): string[];
 export declare function ensureLocalFilesIgnored(vigilesDir: string): void;
 //# sourceMappingURL=local-files.d.ts.map

package/dist/local-files.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOCAL_GITIGNORE_HEADER = exports.COMMITTED_PATHS = exports.LOCAL_FILES = exports.EVAL_CACHE_DIR = exports.HOOK_OBSERVATIONS_FILE = exports.GUARD_LEDGER_FILE = exports.EFFECT_ACTIVE_FILE = exports.ACTIVE_AGENT_FILE = exports.ACTIVE_SKILL_FILE = exports.HOOK_STATE_DIR = exports.LEDGER_FILE = exports.COVERAGE_ARTIFACT_FILE = exports.VIGILES_DIR = void 0;
+exports.LOCAL_GITIGNORE_HEADER = exports.LOCAL_GITIGNORE_FILE = exports.COMMITTED_PATHS = exports.LOCAL_FILES = exports.EVAL_CACHE_DIR = exports.HOOK_OBSERVATIONS_FILE = exports.GUARD_LEDGER_FILE = exports.EFFECT_ACTIVE_FILE = exports.ACTIVE_AGENT_FILE = exports.ACTIVE_SKILL_FILE = exports.HOOK_STATE_DIR = exports.LEDGER_FILE = exports.COVERAGE_ARTIFACT_FILE = exports.VIGILES_DIR = void 0;
 exports.localIgnoreEntries = localIgnoreEntries;
+exports.entriesNotInEffect = entriesNotInEffect;
 exports.ensureLocalFilesIgnored = ensureLocalFilesIgnored;
 /**
  * The files vigiles writes into a project's `.vigiles/` that describe ONE
@@ -108,6 +109,8 @@ exports.COMMITTED_PATHS = [
     "action-gates.json", // declared action gates (`action-gate.ts`)
 ];
 /** The header comment on a `.vigiles/.gitignore` vigiles creates. */
+/** The ignore file vigiles keeps inside `.vigiles/`. One spelling for every reader. */
+exports.LOCAL_GITIGNORE_FILE = ".gitignore";
 exports.LOCAL_GITIGNORE_HEADER = [
     "# Written by vigiles. These files describe one checkout on one machine and are",
     "# never committed. Everything else in .vigiles/ is the project's: commit it.",
@@ -116,16 +119,25 @@ exports.LOCAL_GITIGNORE_HEADER = [
 function localIgnoreEntries() {
     return [
         ...exports.LOCAL_FILES.map((f) => `/${f.name}${f.dir ? "/" : ""}`),
-        "/.gitignore",
+        `/${exports.LOCAL_GITIGNORE_FILE}`,
     ];
 }
-/** Is `entry` ignoring its path after git reads `lines` top to bottom. */
+/**
+ * Is `entry` ignoring its path after git reads `lines` top to bottom.
+ *
+ * Conservative on purpose: ANY negation after the entry's last occurrence counts
+ * as cancelling it. Git re-includes on `!/coverage.json`, but equally on
+ * `!coverage.json` or `!*.json` (last matching pattern wins), and matching
+ * gitignore globs here would be a second, partial implementation of git. The
+ * cost of being conservative is one extra append after an unrelated negation;
+ * the next call finds the entries last and leaves the file alone.
+ */
 function inEffect(lines, entry) {
     let on = false;
     for (const line of lines) {
         if (line === entry)
             on = true;
-        else if (line === `!${entry}`)
+        else if (line.startsWith("!"))
             on = false;
     }
     return on;
@@ -141,8 +153,9 @@ function inEffect(lines, entry) {
  *   or reordered. Appending is enough because git's last matching rule wins.
  *
  * "In effect" is judged the way git reads the file, not by text membership:
- * lines in order, a later `!/entry` cancels an earlier `/entry`, and leading
- * whitespace is part of the pattern (only trailing whitespace is dropped).
+ * lines in order, a later negation cancels an earlier `/entry` (see
+ * {@link inEffect}), and leading whitespace is part of the pattern (only
+ * trailing whitespace is dropped).
  * Both cases were measured with `git check-ignore`: `/coverage.json` followed
  * by `!/coverage.json`, and ` /coverage.json`, each leave the file NOT
  * ignored while a trimmed set would call the entry present.
@@ -150,9 +163,18 @@ function inEffect(lines, entry) {
  * Costs one read on the hot path. Best-effort: any fs error is swallowed —
  * keeping git tidy must never break a hook, a test run or an audit.
  */
+/**
+ * The entries a `.vigiles/.gitignore` with this content does NOT put in effect.
+ * One reader for both questions — "what to append" ({@link ensureLocalFilesIgnored})
+ * and "does the committed copy already carry them" (the CLI's tracked-file check).
+ */
+function entriesNotInEffect(content) {
+    const lines = content.split(/\r?\n/).map((l) => l.replace(/\s+$/, ""));
+    return localIgnoreEntries().filter((e) => !inEffect(lines, e));
+}
 function ensureLocalFilesIgnored(vigilesDir) {
     try {
-        const file = (0, node_path_1.resolve)(vigilesDir, ".gitignore");
+        const file = (0, node_path_1.resolve)(vigilesDir, exports.LOCAL_GITIGNORE_FILE);
         const entries = localIgnoreEntries();
         let current;
         try {
@@ -166,11 +188,10 @@ function ensureLocalFilesIgnored(vigilesDir) {
             (0, node_fs_1.writeFileSync)(file, [...exports.LOCAL_GITIGNORE_HEADER, ...entries, ""].join("\n"));
             return;
         }
-        const lines = current.split(/\r?\n/).map((l) => l.replace(/\s+$/, ""));
-        const missing = entries.filter((e) => !inEffect(lines, e));
+        const missing = entriesNotInEffect(current);
         if (missing.length === 0)
             return;
-        const header = lines.includes(exports.LOCAL_GITIGNORE_HEADER[0])
+        const header = current.split(/\r?\n/).includes(exports.LOCAL_GITIGNORE_HEADER[0])
             ? []
             : exports.LOCAL_GITIGNORE_HEADER;
         const sep = current === "" || current.endsWith("\n") ? "" : "\n";

package/dist/test.js

@@ -1,4 +1,9 @@
 "use strict";
+// 🔴 PUBLIC ENTRY POINT `vigiles` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles.api.md`, which
+// `npm run api:check` fails on.
 /**
  * `vigiles` (the package root) — the **free** testing surface: everything you can
  * run without a model call, and therefore without a bill.

package/dist/vitest.mjs

@@ -1,3 +1,8 @@
+// 🔴 PUBLIC ENTRY POINT `vigiles/vitest` — every export here is a promise to users. The default for a
+// symbol is INTERNAL. It is exported only if (a) a NAMED external consumer uses it, or (b) it is
+// a deliberate extension point listed in STABILITY.md (the adapter kit is the example). "Might
+// be useful" is neither. Review point: the diff of `api-surface/vigiles-vitest.api.md`, which
+// `npm run api:check` fails on.
 /* eslint-disable max-params, @typescript-eslint/no-explicit-any --
    The matcher signatures mirror the runtime vigilesMatchers (positional args),
    and `Matchers<T = any>` must match @vitest/expect's generic default to merge. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "30.0.1",
+  "version": "31.0.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",
@@ -138,6 +138,7 @@
   "dependencies": {
     "@ast-grep/napi": "^0.43.0",
     "@iarna/toml": "^2.2.5",
+    "@vscode/tree-sitter-wasm": "0.3.1",
     "ci-info": "^4.4.0",
     "cosmiconfig": "^9.0.1",
     "glob": "^13.0.6",
@@ -148,10 +149,5 @@
     "ts-essentials": "^10.2.1",
     "typescript": "^5.9.3",
     "zod": "^4.6.5"
-  },
-  "optionalDependencies": {
-    "@ast-grep/lang-python": "^0.0.6",
-    "@ast-grep/lang-ruby": "^0.0.7",
-    "@ast-grep/lang-rust": "^0.0.7"
   }
 }