vigiles 27.3.0 → 29.0.0

package/dist/core/symbols.js

@@ -1,8 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.installedGrammars = installedGrammars;
 exports.langForFile = langForFile;
 exports.definedSymbols = definedSymbols;
 exports.definedSymbolsInFile = definedSymbolsInFile;
@@ -23,18 +21,60 @@ exports.fileDefinesSymbol = fileDefinesSymbol;
  * delegated. Ambiguity (a name defined in several files) is reported, not guessed.
  */
 const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
 const node_path_1 = require("node:path");
 const napi_1 = require("@ast-grep/napi");
-const lang_python_1 = __importDefault(require("@ast-grep/lang-python"));
-const lang_rust_1 = __importDefault(require("@ast-grep/lang-rust"));
-const lang_ruby_1 = __importDefault(require("@ast-grep/lang-ruby"));
-let registered = false;
+/**
+ * The non-web grammars, as OPTIONAL packages keyed by the id ast-grep registers them under.
+ *
+ * 🔴 WHY OPTIONAL, AND WHY IT IS NOT A PREFERENCE. These three are the only packages in this
+ * dependency tree carrying a `postinstall` (measured 2026-09-20 with `npm query
+ * ":attr(scripts, [postinstall])"`). Since pnpm 10 a consumer's install FAILS on an
+ * unapproved lifecycle script, so every downstream project installing vigiles with pnpm got
+ * `ERR_PNPM_IGNORED_BUILDS` and a non-zero exit — for grammars most of them never use. The web
+ * grammars every user does need (TypeScript, TSX, JavaScript, CSS) are built into
+ * `@ast-grep/napi` and cost nothing.
+ *
+ * They load through `createRequire` rather than `await import()` on purpose: the packages are
+ * CommonJS (`"main": "index.js"`, no `exports`), so a synchronous require works and NOTHING in
+ * this module's public surface has to become async. Measured, not assumed.
+ */
+const OPTIONAL_GRAMMARS = {
+    python: "@ast-grep/lang-python",
+    rust: "@ast-grep/lang-rust",
+    ruby: "@ast-grep/lang-ruby",
+};
+// Anchored on THIS module's own file, not on the consumer's project root. Under pnpm a
+// consumer's root does not contain our transitive packages at all — the same addressing
+// mistake that made every hook fail there — and these grammars are OUR optional dependencies,
+// so they resolve from where this file lives. `__filename` rather than `import.meta.url`
+// because this package compiles to CommonJS (`module: Node16`, `main: ./dist/test.js`).
+const require_ = (0, node_module_1.createRequire)(__filename);
+/** Registered grammar ids, populated on first use. `null` until then. */
+let loaded = null;
 function ensureRegistered() {
-    if (registered)
-        return;
-    // Non-web grammars ship as separate packages registered at runtime.
-    (0, napi_1.registerDynamicLanguage)({ python: lang_python_1.default, rust: lang_rust_1.default, ruby: lang_ruby_1.default });
-    registered = true;
+    if (loaded)
+        return loaded;
+    const dynamic = {};
+    const present = new Set();
+    for (const [id, pkg] of Object.entries(OPTIONAL_GRAMMARS)) {
+        try {
+            dynamic[id] = require_(pkg);
+            present.add(id);
+        }
+        catch {
+            // Absent by design: an optional dependency the consumer did not install. The caller is
+            // told WHICH id is missing (see `langForFile`), so "not checked" never reads as "clean".
+        }
+    }
+    if (present.size > 0)
+        (0, napi_1.registerDynamicLanguage)(dynamic);
+    loaded = present;
+    return loaded;
+}
+/** Which optional grammars this process actually has. Exported so a report can say so. */
+function installedGrammars() {
+    return ensureRegistered();
 }
 const EXT_LANG = {
     ".ts": napi_1.Lang.TypeScript,
@@ -53,11 +93,18 @@ const EXT_LANG = {
     ".rb": "ruby",
     ".rbi": "ruby",
 };
-/** The ast-grep language for a file, or null if unsupported (graceful skip). */
 function langForFile(file) {
-    if (file.endsWith(".d.ts"))
-        return napi_1.Lang.TypeScript;
-    return EXT_LANG[(0, node_path_1.extname)(file).toLowerCase()] ?? null;
+    const key = file.endsWith(".d.ts")
+        ? napi_1.Lang.TypeScript
+        : EXT_LANG[(0, node_path_1.extname)(file).toLowerCase()];
+    if (key === undefined)
+        return { kind: "unsupported" };
+    // A string key is one of the dynamically registered grammars; the enum members are built in.
+    if (typeof key === "string" && key in OPTIONAL_GRAMMARS) {
+        if (!ensureRegistered().has(key))
+            return { kind: "grammar-missing", id: key, pkg: OPTIONAL_GRAMMARS[key] };
+    }
+    return { kind: "ready", lang: key };
 }
 const ID_KINDS = new Set(["identifier", "constant", "type_identifier"]);
 const SCOPE_KINDS = new Set([
@@ -97,9 +144,10 @@ function definedSymbols(code, lang) {
 }
 /** Defined symbols for a file on disk, or [] if unreadable/unsupported. */
 function definedSymbolsInFile(file) {
-    const lang = langForFile(file);
-    if (!lang)
+    const support = langForFile(file);
+    if (support.kind !== "ready")
         return [];
+    const lang = support.lang;
     try {
         return definedSymbols((0, node_fs_1.readFileSync)(file, "utf-8"), lang);
     }

package/dist/core/types.d.ts

@@ -1,4 +1,5 @@
 import type { HarnessDialect } from "./dialect.js";
+import type { HarnessDeclarationShape, VigilesConfigShape } from "./config-schema.js";
 /** A parsed rule from a markdown instruction file. */
 export interface ParsedRule {
     title: string;
@@ -377,113 +378,41 @@ export interface RulesConfig {
 export declare function ruleSeverity<T>(rule: RuleWithOptions<T> | undefined): RuleSeverity;
 /** Extract options from a rule value (returns undefined for simple severity). */
 export declare function ruleOptions<T>(rule: RuleWithOptions<T> | undefined): T | undefined;
-/** Full vigiles configuration. Loaded from .vigilesrc.json. */
-export interface VigilesConfig {
-    ruleMarkers: MarkerType[];
-    rules: Required<RulesConfig>;
-    files: string[];
-    /** Maximum number of rules allowed per spec. */
-    maxRules?: number;
-    /** Maximum estimated tokens for compiled output. */
-    maxTokens?: number;
-    /** Maximum lines per prose section. */
-    maxSectionLines?: number;
-    /** Skip config-enabled checks, only verify rule exists in catalog. */
-    catalogOnly?: boolean;
-    /** Custom linter configs (rulesDir). */
-    linters?: Record<string, {
-        rulesDir?: string | string[];
-    }>;
-    /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
-    /**
-     * Which bundles `lint` scores: `"root"` (default) or `"all"`.
-     *
-     * A monorepo holding `skills/` plus `plugins/  * /skills/` had its nested skills
-     * silently uncounted — the counters looked complete while whole surfaces were
-     * never read (#185). `"all"` scores every discovered bundle in one pass, so a
-     * CI gate keeps ONE exit code over the whole repo.
-     *
-     * Root-only remains the default because descending unconditionally would score
-     * vendored third-party plugins (a repo may keep a pinned corpus on disk) as if
-     * they were the project's own. The default no longer hides the skip: `lint`
-     * names the bundles it did not score.
-     */
-    bundles?: "root" | "all";
-    orphans?: OrphansConfig;
-    /**
-     * Paths and globs the repo's own tooling does NOT police — vendored corpora,
-     * benchmark fixtures, frozen reproductions (tsconfig-style, relative to the
-     * repo root; a bare directory name such as `"bench"` excludes its subtree, as
-     * do `"bench/"` and `"bench/**"`). `node_modules`/`dist`/`.git`/`.vigiles` are
-     * always excluded.
-     *
-     * ONE filter, every pass (#192): `compile` does not load an excluded spec,
-     * `lint` does not discover an excluded instruction file, nested bundle, doc, or
-     * surface, `audit` does not read an excluded instruction file, and
-     * `test`/`eval` do not discover an excluded script. It filters DISCOVERY only:
-     * a path you name on the command line is still processed, and one line says
-     * which pattern it matched. The rule-level `orphans.exclude` and
-     * `untested-*` `exclude` NARROW their own rule further and never re-admit a
-     * path excluded here (union, not override). Parsed once in `src/exclude.ts`.
-     */
-    exclude?: readonly string[];
-    /**
-     * Top-level dir names shared across skills, e.g. `["scripts", "references"]`.
-     * OPT-IN: many skill libraries keep ONE top-level `scripts/`/`references/` tree
-     * rather than a copy beside every `SKILL.md`, so a bundled ref like
-     * `scripts/promptfoo/x.py` lives at the REPO ROOT. When a `SKILL.md` body ref's
-     * first path segment is a declared shared dir, `skill-resource-resolves` / audit
-     * ALSO resolves it against the repo root, not only the skill's own dir. Scoped
-     * to declared dirs on purpose: a repo that omits this key behaves exactly as
-     * before (skill-dir-only resolution), and a ref outside a shared dir is never
-     * masked by a same-named repo-root file. See feedback P1-4.
-     */
-    sharedDirs?: readonly string[];
-    /**
-     * The harness(es) this repo targets — selects the compile dialect / skill
-     * frontmatter profile / instruction-file shape, instead of sniffing the cwd.
-     * A single name (`"codex"`) for the common single-harness repo, or an array
-     * (`["claude-code", "codex"]`) declaring the supported set. Written by
-     * `vigiles init`. Omitted → the CLI auto-detects (backwards-compatible).
-     * Canonical adapter names; `"claude"` is accepted as an alias for
-     * `"claude-code"`. See research/multi-harness-compile.md.
-     */
-    harness?: string | string[];
-    /**
-     * `vigiles audit` preferences. `measure` is the sticky remembered answer to the
-     * "run the executing checks against your harness?" prompt — at a TTY `audit`
-     * asks once, then records the choice here so it never asks again. `true` runs
-     * the executing checks (safety battery · live MCP · skill firing) on every
-     * interactive run, `false` keeps them off (edit this key to change). Written by
-     * the audit consent prompt, not `init`. Headless runs never execute regardless
-     * (audit is a local report, not a CI step — there is no execution flag).
-     */
-    audit?: {
-        measure?: boolean;
-    };
-    /**
-     * `vigiles eval` preferences. `apiVersion` is the hand-bumped **behavior epoch**
-     * folded into the eval LOCK's input hash (`src/eval-lock.ts`): bump it when a
-     * harness-side change YOU made (a CLAUDE.md edit, a global hook) would shift
-     * eval outputs but isn't otherwise visible to the lock — so `vigiles eval
-     * --check` reports the committed eval results STALE and forces a local re-run.
-     * Default 1. Distinct from the (auto-resolved) `claude` CLI version, which is
-     * recorded as provenance but deliberately NOT hashed.
-     */
-    eval?: {
-        apiVersion?: number;
-    };
-    /**
-     * Suppress the adoption nudges `audit` prints (the "N surfaces not yet
-     * spec-managed → create specs" invitation). Set `"dismissed"` to hide them —
-     * the "remembered decline" half of the non-evil adoption contract, so a team
-     * that deliberately runs the integrity GATE alone (no specs/plugin) isn't
-     * nagged on every run. USER-SET only: `audit`/`lint` are pure reads and never
-     * write this (a read never writes). The deterministic findings + fixes are
-     * unaffected — this silences only the invitation, never a real finding.
-     */
-    nudge?: "dismissed";
-}
+/**
+ * ONE harness's entry in {@link VigilesConfig.harnesses} — what this repo tells
+ * that harness about itself. Today that is only `roots`; the OBJECT (rather than
+ * a bare array of roots) is what leaves room for a second per-harness fact
+ * without another top-level key, which is how `surfaceRoots` came to exist
+ * beside `harness` in the first place.
+ *
+ * `{}` is meaningful and is the common case: "this repo targets this harness,
+ * and it reads it where it normally reads it."
+ *
+ * `roots` are extra repo-relative dirs THIS harness's surfaces live under, read
+ * with THIS harness's own `surfaceDirs` — `[".ai"]` under `"claude-code"` means
+ * `.ai/skills`, `.ai/agents`, `.ai/commands`. Every entry must resolve to at
+ * least one surface dir that exists on disk under this harness's layout; one
+ * that does not is a hard error, because a root declared under a harness that
+ * reads nothing there changes nothing and used to say nothing.
+ */
+export type HarnessDeclaration = HarnessDeclarationShape;
+/**
+ * Full vigiles configuration, loaded from `.vigilesrc.json`.
+ *
+ * 🔴 DERIVED FROM THE SCHEMA, NOT WRITTEN BESIDE IT. The shape, the defaults and
+ * the per-key prose all live in `./config-schema.ts`; this is
+ * `z.infer<typeof vigilesConfigSchema>` with the defaults applied, so the type
+ * says exactly what a parsed config carries — `rules` non-optional and complete
+ * because every rule key has a schema default, optional keys optional because
+ * the schema says so. A hand-written twin is the copy that drifts: `harness` and
+ * `surfaceRoots` lived in that twin, in `docs/cli.md` and in the loader's
+ * coercions, and the three disagreed about what was read (#240).
+ *
+ * The re-export is TYPE-ONLY on purpose — `types.ts` is imported by node-free
+ * core modules, and a value import of the schema module would pull Zod into
+ * every one of them.
+ */
+export type VigilesConfig = VigilesConfigShape;
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";
 /** Options for parseRules. */

package/dist/core/validate.d.ts

@@ -1,25 +1,53 @@
-import type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions } from "./types.js";
-export type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions, };
-export declare const DEFAULT_RULES: Required<RulesConfig>;
-export declare function findInstructionFiles(cwd?: string, configFiles?: string[]): string[];
+import type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, HarnessDeclaration, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions } from "./types.js";
+export type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, HarnessDeclaration, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions, };
 /**
- * ESLint users write `"off"` / `0` / `1` / `2` for severity; normalize to
- * vigiles's `"warn" | "error" | false` so a rule the user meant to DISABLE
- * (`"off"`) or GATE (`2`) actually does — instead of a truthy string / number
- * silently rendering as a non-gating warn (issue #112 + numeric severities). The
- * array form `[sev, opts]` recurses on the head. An unrecognized value is left
- * as-is (it renders as a warn, the pre-existing behavior).
+ * The shipped default severity of every rule — DERIVED from the schema, never
+ * listed twice.
+ *
+ * It used to be the literal beside the type, which is exactly the pair that
+ * drifts: `rule-meta.test.ts` already cross-checks each rule's documented
+ * `defaultSeverity` against this object, and it could only ever catch a doc that
+ * disagreed with the literal, never a literal that disagreed with what parsing
+ * actually produced. Reading it out of the parser closes that gap: this IS what
+ * a `{}` config loads as.
  */
-export declare function normalizeSeverity(v: unknown): unknown;
+export declare const DEFAULT_RULES: Required<RulesConfig>;
+export declare function findInstructionFiles(cwd?: string, configFiles?: string[]): string[];
 /**
- * Coerce a config value that should be a `string[]`: a bare STRING becomes a
- * one-element array (the natural first-value mistake), so `exclude` /
- * `orphans.include` don't silently iterate a string's CHARACTERS as globs — a
- * no-op at best, and garbage "orphan" matches (`.`, `/`, `README.md`) at worst.
- * A non-string/array value falls back with a warning (the `ruleMarkers` pattern).
+ * Read and VALIDATE `.vigilesrc.json`.
+ *
+ * 🔴 `searchFrom` IS NOT A CONVENIENCE. cosmiconfig defaults to the process's
+ * working directory and walks up — right for a CLI verb, where the user is
+ * standing in the project they mean, and wrong for a hook, whose process has no
+ * stable cwd. A hook rail that omits it reads a DIFFERENT project's config, or
+ * none, and the failure runs the wrong way: a missing file means defaults, so a
+ * rule the author switched OFF comes back on, silently, because the file saying
+ * "off" was never found. Nothing in the output distinguishes that from a project
+ * that never configured the rule.
+ *
+ * 🔴 `onInvalid` IS THE ONE PLACE THE CALL SITES DIFFER, AND IT IS NOT A SPLIT
+ * IN WHAT IS CHECKED. Every reader validates; they disagree only about what a
+ * bad config is allowed to do to them. A VERB is a human standing at a prompt
+ * having just edited the file — `"throw"`, so the line they typed is refused out
+ * loud. A HOOK RAIL is a fresh process inside somebody's editing session, and a
+ * hook that dies on a malformed config turns a typo in a JSON file into a failed
+ * edit, which is a worse outcome than the nudge not firing — `"warn"`, print the
+ * same lines to stderr and carry on with the defaults.
+ *
+ * The two hook rails are `refsHookCommand` and `evalLockNudgeHookCommand`
+ * (`vigiles hook-runtime refs` / `eval-lock-nudge`, both registered as
+ * PostToolUse `Edit|Write` in `.claude-plugin/plugin.json`). Every other reader
+ * is a verb.
+ *
+ * ⚠️ THE SCHEMA MODULE IS REQUIRED IN-BODY, and that is hygiene rather than an
+ * optimization worth a paragraph: Zod is a ~45 ms cold import, `tsc` emits
+ * CommonJS across 230 separate files, so a `require` in a function body genuinely
+ * does not execute until the function is called. A rail that never reads a
+ * config never pays for the validator.
  */
-export declare function asStringArray(v: unknown, fallback: readonly string[], key: string): readonly string[];
-export declare function loadConfig(): VigilesConfig;
+export declare function loadConfig(searchFrom?: string, { onInvalid }?: {
+    onInvalid?: "throw" | "warn";
+}): VigilesConfig;
 export declare function parseRules(content: string, { ruleMarkers }?: ParseOptions): ParsedRule[];
 export declare function validate(content: string, { ruleMarkers, rules: rulesConfig, filePath, dialect }?: ValidateOptions): ValidationResult;
 export declare function readInstructionFile(filePath: string, options?: ReadOptions): ReadResult;