vigiles 39.0.0 → 39.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/action.yml +18 -0
- package/dist/adapters/claude-code/dialect.js +5 -0
- package/dist/audit-report.d.ts +14 -1
- package/dist/audit-report.js +21 -5
- package/dist/audit-report.template.html +33 -28
- package/dist/audit-score.d.ts +4 -1
- package/dist/audit-score.js +3 -1
- package/dist/audit-verdict.d.ts +3 -1
- package/dist/cli-flag-check.d.ts +1 -1
- package/dist/cli-flag-check.js +5 -1
- package/dist/cli-flags.d.ts +1 -1
- package/dist/cli-main.js +153 -72
- package/dist/core/CLAUDE.md.spec.js +2 -2
- package/dist/core/adopt.js +32 -8
- package/dist/core/apply-rules.d.ts +71 -0
- package/dist/core/apply-rules.js +48 -0
- package/dist/core/compile.d.ts +1 -1
- package/dist/core/compile.js +47 -14
- package/dist/core/config-migrations.d.ts +69 -0
- package/dist/core/config-migrations.js +145 -0
- package/dist/core/config-schema.d.ts +163 -187
- package/dist/core/config-schema.js +185 -345
- package/dist/core/dialect.d.ts +1 -1
- package/dist/core/dialect.js +2 -0
- package/dist/core/linter-adapter.d.ts +1 -1
- package/dist/core/presets.d.ts +31 -46
- package/dist/core/presets.js +25 -51
- package/dist/core/rule.d.ts +213 -0
- package/dist/core/rule.js +37 -0
- package/dist/core/skill-resources.d.ts +85 -15
- package/dist/core/skill-resources.js +63 -37
- package/dist/core/spec.d.ts +17 -0
- package/dist/core/types.d.ts +12 -314
- package/dist/core/validate.d.ts +13 -12
- package/dist/core/validate.js +29 -28
- package/dist/doc-commands.d.ts +2 -2
- package/dist/optimize.d.ts +2 -1
- package/dist/overrides.d.ts +13 -9
- package/dist/overrides.js +1 -1
- package/dist/rules/CLAUDE.md.spec.d.ts +3 -0
- package/dist/rules/CLAUDE.md.spec.js +22 -0
- package/dist/rules/groups.d.ts +32 -0
- package/dist/rules/groups.js +27 -0
- package/dist/rules/index.d.ts +412 -0
- package/dist/{core/rule-meta.js → rules/index.js} +301 -209
- package/dist/rules/skill-resource-resolves.d.ts +36 -0
- package/dist/rules/skill-resource-resolves.js +51 -0
- package/dist/run-hook.d.ts +1 -1
- package/dist/scan-core.d.ts +7 -9
- package/dist/scan-core.js +7 -10
- package/dist/scan-files.js +1 -4
- package/dist/scan.d.ts +11 -16
- package/dist/scan.js +31 -8
- package/dist/score-core.js +3 -9
- package/dist/setup-plan.d.ts +6 -26
- package/dist/setup-plan.js +27 -60
- package/dist/skill-harness.d.ts +3 -1
- package/dist/skill-harness.js +5 -2
- package/dist/vigilesrc.schema.json +18 -3
- package/package.json +2 -2
- package/packages/eslint-config/index.mjs +61 -0
- package/dist/core/rule-meta.d.ts +0 -94
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.skillResourceIssues = skillResourceIssues;
|
|
4
|
+
exports.repoRootOnlyAdvice = repoRootOnlyAdvice;
|
|
4
5
|
/**
|
|
5
6
|
* vigiles — SKILL bundled-resource resolution (the cross-reference moat applied
|
|
6
7
|
* to a SKILL.md body).
|
|
@@ -308,51 +309,76 @@ function candidateFor(ref, line) {
|
|
|
308
309
|
*/
|
|
309
310
|
const DISABLE_RE = /<!--\s*vigiles-disable\s+skill-resource-resolves\s*-->/;
|
|
310
311
|
/**
|
|
311
|
-
*
|
|
312
|
-
*
|
|
313
|
-
*
|
|
312
|
+
* Look a candidate up, in the order a reader of the skill would: beside the
|
|
313
|
+
* SKILL.md, then the repo root through a DECLARED shared dir (resolved — the
|
|
314
|
+
* repo said this tree is shared), then the repo root on its own (`repo-root-only`
|
|
315
|
+
* — it works from here, but nothing declared it, so it is reported).
|
|
316
|
+
*/
|
|
317
|
+
function lookup(rel, skillDir, opts) {
|
|
318
|
+
const exists = opts.existsSync;
|
|
319
|
+
if (exists((0, posix_path_js_1.resolve)(skillDir, rel)))
|
|
320
|
+
return "found";
|
|
321
|
+
if (opts.repoRoot === undefined)
|
|
322
|
+
return "missing";
|
|
323
|
+
if (!exists((0, posix_path_js_1.resolve)(opts.repoRoot, rel)))
|
|
324
|
+
return "missing";
|
|
325
|
+
const sharedDirs = opts.sharedDirs ?? [];
|
|
326
|
+
return sharedDirs.includes(rel.split("/")[0]) ? "found" : "repo-root-only";
|
|
327
|
+
}
|
|
328
|
+
/**
|
|
329
|
+
* Reads a SKILL.md body, finds every file it mentions (`scripts/x.sh`,
|
|
330
|
+
* `[guide](references/guide.md)`), and returns the ones that are NOT in the
|
|
331
|
+
* skill's own folder. Files that are there are not returned at all.
|
|
332
|
+
*
|
|
333
|
+
* ```ts
|
|
334
|
+
* // skillDir = .claude/skills/deploy, repoRoot = the repo
|
|
335
|
+
* skillResourceIssues("Run `scripts/deploy.sh`.\nSee `scripts/smoke.sh`.", skillDir, {
|
|
336
|
+
* existsSync, repoRoot,
|
|
337
|
+
* });
|
|
338
|
+
* // → [{ ref: "scripts/deploy.sh", resolution: "repo-root-only", … },
|
|
339
|
+
* // { ref: "scripts/smoke.sh", resolution: "missing", … }]
|
|
340
|
+
* ```
|
|
314
341
|
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
342
|
+
* Despite the name, the result holds both kinds: `missing` (a real break) and
|
|
343
|
+
* `repo-root-only` (works here, breaks when installed elsewhere — a note). The
|
|
344
|
+
* split into two lists happens once, in `collectSurfaceFindings`. It only reads
|
|
345
|
+
* the file system through the injected `existsSync`, so it runs on disk and in
|
|
346
|
+
* the browser, and `lint` and `audit` both call it.
|
|
317
347
|
*/
|
|
318
348
|
function skillResourceIssues(skillBody, skillDir, opts) {
|
|
319
349
|
if (DISABLE_RE.test(skillBody))
|
|
320
350
|
return [];
|
|
321
|
-
const exists = opts.existsSync;
|
|
322
351
|
const lineOffset = opts.lineOffset ?? 0;
|
|
323
|
-
const sharedDirs = new Set(opts.sharedDirs ?? []);
|
|
324
|
-
// A ref resolves if it exists under the skill's own dir. If (and only if) its
|
|
325
|
-
// first segment is a DECLARED shared dir, it may also resolve against the repo
|
|
326
|
-
// root — the opt-in shared-tree case. No shared dirs → skill-dir-only (unchanged).
|
|
327
|
-
const resolvesAnywhere = (rel) => {
|
|
328
|
-
if (exists((0, posix_path_js_1.resolve)(skillDir, rel)))
|
|
329
|
-
return true;
|
|
330
|
-
const firstSeg = rel.split("/")[0];
|
|
331
|
-
return (opts.repoRoot !== undefined &&
|
|
332
|
-
sharedDirs.has(firstSeg) &&
|
|
333
|
-
exists((0, posix_path_js_1.resolve)(opts.repoRoot, rel)));
|
|
334
|
-
};
|
|
335
|
-
const findings = [];
|
|
336
|
-
const seen = new Set();
|
|
337
352
|
const lines = skillBody.split("\n");
|
|
338
|
-
|
|
353
|
+
const reported = (0, markdown_js_1.markdownRefs)(skillBody).flatMap((ref) => {
|
|
339
354
|
const c = candidateFor(ref, lines[ref.line - 1] ?? "");
|
|
340
355
|
if (c === null)
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
356
|
+
return [];
|
|
357
|
+
const resolution = lookup(c.resolved, skillDir, opts);
|
|
358
|
+
return resolution === "found"
|
|
359
|
+
? []
|
|
360
|
+
: [{ ...c, line: c.line + lineOffset, resolution }];
|
|
361
|
+
});
|
|
362
|
+
// De-dupe the same file referenced several times in the body: the first
|
|
363
|
+
// mention is the one reported.
|
|
364
|
+
return reported.filter((f, i) => reported.findIndex((g) => g.kind === f.kind && g.resolved === f.resolved) === i);
|
|
365
|
+
}
|
|
366
|
+
/**
|
|
367
|
+
* What a `repo-root-only` finding means and what to do about it — ONE sentence
|
|
368
|
+
* shared by every surface that prints the note (`audit`'s text and HTML report,
|
|
369
|
+
* `lint`'s line and its CI annotation), so they cannot drift apart.
|
|
370
|
+
*
|
|
371
|
+
* The cure depends on the path's shape: `sharedDirs` declares a top-level
|
|
372
|
+
* DIRECTORY, so a ref under one (`scripts/check.sh`) can be declared shared,
|
|
373
|
+
* while a bare file at the root (`guide.md`) has no directory to declare and the
|
|
374
|
+
* only cure is to ship it beside the SKILL.md.
|
|
375
|
+
*/
|
|
376
|
+
function repoRootOnlyAdvice(f) {
|
|
377
|
+
const slash = f.resolved.indexOf("/");
|
|
378
|
+
const cure = slash > 0
|
|
379
|
+
? `If repo-root resolution is intended, add "${f.resolved.slice(0, slash)}" to sharedDirs in .vigilesrc.json.`
|
|
380
|
+
: "Ship it beside the SKILL.md if the skill is meant to be installed elsewhere.";
|
|
381
|
+
return ("resolves only from the repo root, not from the skill directory — " +
|
|
382
|
+
`it breaks once the skill is installed outside this repository. ${cure}`);
|
|
357
383
|
}
|
|
358
384
|
//# sourceMappingURL=skill-resources.js.map
|
package/dist/core/spec.d.ts
CHANGED
|
@@ -495,6 +495,23 @@ export interface SkillSpec {
|
|
|
495
495
|
* for the default inline execution.
|
|
496
496
|
*/
|
|
497
497
|
readonly context?: "fork";
|
|
498
|
+
/**
|
|
499
|
+
* The subagent type a forked skill starts (`agent` frontmatter): a built-in
|
|
500
|
+
* type (`Explore`, `Plan`, `general-purpose`) or a custom one from the
|
|
501
|
+
* harness's agents directory. Requires `context: "fork"` — without a fork
|
|
502
|
+
* there is no subagent to pick (compile error `agent-without-fork`). Omitted,
|
|
503
|
+
* the harness uses `general-purpose`.
|
|
504
|
+
*/
|
|
505
|
+
readonly agent?: string;
|
|
506
|
+
/**
|
|
507
|
+
* The model the skill runs on (`model` frontmatter): an alias (`sonnet`,
|
|
508
|
+
* `opus`, `haiku`, `fable`), a full model id, or `inherit`. With
|
|
509
|
+
* `context: "fork"` it sets the forked subagent's model; inline, it overrides
|
|
510
|
+
* the model for the rest of the current turn. Omitted on a forked skill, the
|
|
511
|
+
* subagent resolves to the main conversation's model — which is the costly
|
|
512
|
+
* default this field exists to override.
|
|
513
|
+
*/
|
|
514
|
+
readonly model?: string;
|
|
498
515
|
/**
|
|
499
516
|
* The allowed-tools contract for this skill. Each entry must be a known
|
|
500
517
|
* built-in tool or an MCP tool (`mcp__server__tool`). Omit to inherit all
|
package/dist/core/types.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { HarnessDialect } from "./dialect.js";
|
|
2
|
-
import type { HarnessDeclarationShape,
|
|
2
|
+
import type { HarnessDeclarationShape, RulesConfig, VigilesConfigOf } from "./config-schema.js";
|
|
3
|
+
export type { RuleEntry, RulesConfig } from "./config-schema.js";
|
|
3
4
|
/** A parsed rule from a markdown instruction file. */
|
|
4
5
|
export interface ParsedRule {
|
|
5
6
|
title: string;
|
|
@@ -123,310 +124,6 @@ export interface CompileBudgetConfig {
|
|
|
123
124
|
/** The whole rendered Rules section. Default 20,000 (at "error"). */
|
|
124
125
|
maxRulesChars?: number;
|
|
125
126
|
}
|
|
126
|
-
export interface RulesConfig {
|
|
127
|
-
/**
|
|
128
|
-
* Opt-in: a doc in a configured dir (default `docs/`) that no other `.md`
|
|
129
|
-
* references. The `orphans` block turns the SCAN on; this turns the FINDING
|
|
130
|
-
* into a warning or an error.
|
|
131
|
-
*
|
|
132
|
-
* It lived outside this interface until 2026-09 and therefore could not be
|
|
133
|
-
* set at all: `"warn"` and `"off"` were both ignored and the check always
|
|
134
|
-
* exited 1, so a repo's only choice was an always-blocking check or deleting
|
|
135
|
-
* the `orphans` block (#181). Default: "error", matching the old behaviour.
|
|
136
|
-
*/
|
|
137
|
-
"orphan-docs"?: RuleSeverity;
|
|
138
|
-
/**
|
|
139
|
-
* Re-derive a compiled instruction file's references from its `.spec.ts` and
|
|
140
|
-
* report the dead ones.
|
|
141
|
-
*
|
|
142
|
-
* The integrity hash answers "is this file still what the spec compiled to";
|
|
143
|
-
* it says nothing about whether the paths and scripts it NAMES still exist. So
|
|
144
|
-
* an artifact committed while its refs were live stayed green forever after
|
|
145
|
-
* the target was deleted — `compile` errored, `lint` said "hash valid" and
|
|
146
|
-
* exited 0 (#173). Default: "error", matching `compile`.
|
|
147
|
-
*/
|
|
148
|
-
"spec-refs"?: RuleSeverity;
|
|
149
|
-
/**
|
|
150
|
-
* The always-loaded instruction weight may not move away from the committed
|
|
151
|
-
* baseline in `.vigiles/instruction-weight.json` — a ratchet against the
|
|
152
|
-
* repo's own past, not a fixed budget. No baseline file → a one-line note,
|
|
153
|
-
* never a finding, so turning this on fails no repository on day one.
|
|
154
|
-
* `vigiles lint --update-baseline` records it. Default: "error".
|
|
155
|
-
*
|
|
156
|
-
* `["error", { max: 40000 }]` adds an opt-in absolute ceiling on top of the
|
|
157
|
-
* ratchet: a total above `max` is a finding whatever the baseline says, and
|
|
158
|
-
* the baseline cannot be re-recorded above it.
|
|
159
|
-
*/
|
|
160
|
-
"instruction-weight"?: RuleWithOptions<InstructionWeightConfig>;
|
|
161
|
-
/**
|
|
162
|
-
* An instruction spec still uses the deprecated `keyFiles` field — a flat
|
|
163
|
-
* path → description list compiled into the file loaded on every request.
|
|
164
|
-
* Reports the entry count and compiled size with the migration (a `file()`
|
|
165
|
-
* ref in the rule that needs the pointer). The spec is parsed, never run.
|
|
166
|
-
* Default "warn": a deprecation must not turn a consumer's CI red on upgrade.
|
|
167
|
-
*/
|
|
168
|
-
"deprecated-key-files"?: RuleSeverity;
|
|
169
|
-
/**
|
|
170
|
-
* Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
|
|
171
|
-
* rules saying the same thing in different words.
|
|
172
|
-
*
|
|
173
|
-
* Also previously untierable, and worse: it had no rule id at all, so there
|
|
174
|
-
* was no name a config could even mention (#181). Default: "error".
|
|
175
|
-
*/
|
|
176
|
-
"duplicate-rules"?: RuleSeverity;
|
|
177
|
-
/**
|
|
178
|
-
* Require a `.spec.ts` behind each instruction file (CLAUDE.md / AGENTS.md) —
|
|
179
|
-
* the file must be compiled from a typed spec, not hand-written. NARROW: only a
|
|
180
|
-
* `.spec.ts` sibling (or an explicit `<!-- vigiles-disable
|
|
181
|
-
* require-instructions-spec -->` marker) satisfies it; inline
|
|
182
|
-
* `<!-- vigiles:enforce -->` comments do NOT (the rule name says "spec"). Default:
|
|
183
|
-
* "warn". `vigiles init` auto-adopts every instruction file into a spec, so this
|
|
184
|
-
* is GREEN by construction after setup — a safety net for a NEW hand-added file,
|
|
185
|
-
* not a nag. The workflow-tier opt-in (gated under `--strict`).
|
|
186
|
-
*/
|
|
187
|
-
"require-instructions-spec"?: RuleSeverity;
|
|
188
|
-
/**
|
|
189
|
-
* Require a `.spec.ts` behind each SKILL.md — the consistent
|
|
190
|
-
* `require-<surface>-spec` parallel to `require-instructions-spec`. Default:
|
|
191
|
-
* false (OFF): skills are legitimately hand-written, and the coverage that
|
|
192
|
-
* matters ("every skill ships with a test/eval") is the `untested-skill` rule.
|
|
193
|
-
* Set it explicitly if your team wants every skill spec-managed.
|
|
194
|
-
*/
|
|
195
|
-
"require-skill-spec"?: RuleSeverity;
|
|
196
|
-
/** Detect hand-edits to compiled markdown via SHA-256 hash. Default: "warn". */
|
|
197
|
-
integrity?: RuleSeverity;
|
|
198
|
-
/** Enforce minimum spec coverage thresholds. Default: false. ESLint-style: ["warn", { scripts: 50 }]. */
|
|
199
|
-
coverage?: RuleWithOptions<CoverageThresholds>;
|
|
200
|
-
/** Flag a skill (SKILL.md) that ships with no test or eval. Default: "warn". */
|
|
201
|
-
"untested-skill"?: RuleWithOptions<TestCoverageConfig>;
|
|
202
|
-
/** Flag a subagent (agents/*.md) that ships with no test or eval. Default: "warn". */
|
|
203
|
-
"untested-subagent"?: RuleWithOptions<TestCoverageConfig>;
|
|
204
|
-
/** Flag a hook script that ships with no test or eval. Default: "warn". */
|
|
205
|
-
"untested-hook"?: RuleWithOptions<TestCoverageConfig>;
|
|
206
|
-
/** Flag an output style that ships with no test or eval. Default: "warn". */
|
|
207
|
-
"untested-output-style"?: RuleWithOptions<TestCoverageConfig>;
|
|
208
|
-
/**
|
|
209
|
-
* Nudge (or block) when an instruction file has code-shaped references that
|
|
210
|
-
* aren't expressed as vigiles marks (so the lint can't verify them), or a
|
|
211
|
-
* `vigiles:symbol` mark that points at a missing symbol. Drives the
|
|
212
|
-
* PostToolUse refs-hook: "warn" (default) → a non-blocking nudge, "error" →
|
|
213
|
-
* block the edit, false → off.
|
|
214
|
-
*/
|
|
215
|
-
"unmarked-refs"?: RuleSeverity;
|
|
216
|
-
/**
|
|
217
|
-
* Cross-reference each subagent's `tools:` rail against the harness tool
|
|
218
|
-
* catalog — flag a never-available tool or a close typo (the moat). Only
|
|
219
|
-
* high-confidence issues are reported (a bare unrecognized tool is likely
|
|
220
|
-
* plugin/MCP-provided, never flagged). Off unless set; "warn" surfaces,
|
|
221
|
-
* "error" gates CI. Same detector as `scan` + `compileAgent`.
|
|
222
|
-
*/
|
|
223
|
-
"subagent-tool-contract"?: RuleSeverity;
|
|
224
|
-
/**
|
|
225
|
-
* Flag a hook registered under an event name the harness doesn't define (a
|
|
226
|
-
* typo → the hook never fires). High-precision: close typos only, never a
|
|
227
|
-
* framework/custom event. Default "warn"; "error" gates CI. Same detector as
|
|
228
|
-
* `scan`.
|
|
229
|
-
*/
|
|
230
|
-
"hook-events"?: RuleSeverity;
|
|
231
|
-
/**
|
|
232
|
-
* Flag a skill/agent missing a required frontmatter field — a skill needs
|
|
233
|
-
* `name` (to load), an agent needs `name` + `description`. A broken surface
|
|
234
|
-
* that won't register. Default "warn"; "error" gates CI. Same detector as `scan`.
|
|
235
|
-
*/
|
|
236
|
-
"subagent-frontmatter"?: RuleSeverity;
|
|
237
|
-
/**
|
|
238
|
-
* Flag a declared MCP server that can't start — neither a `command` (stdio)
|
|
239
|
-
* nor a `url` (http/sse). Default "warn"; "error" gates CI. Same detector as
|
|
240
|
-
* `scan`. (JSON `.mcp.json`/manifest `mcpServers`; Codex TOML not yet parsed.)
|
|
241
|
-
*/
|
|
242
|
-
"mcp-config"?: RuleSeverity;
|
|
243
|
-
/**
|
|
244
|
-
* RECOMMEND (not require) that a SKILL.md declares an explicit `name` +
|
|
245
|
-
* `description` rather than relying on the dir-name / first-paragraph
|
|
246
|
-
* fallbacks — a more reliable trigger surface. The skill still loads without
|
|
247
|
-
* them, so this is a best-practice nudge: default "warn"; set "error" to
|
|
248
|
-
* enforce on your own skills. Same detector as `scan` (skillMetaIssues).
|
|
249
|
-
*/
|
|
250
|
-
"skill-frontmatter"?: RuleSeverity;
|
|
251
|
-
/**
|
|
252
|
-
* Cross-reference an `mcp__server__tool` in a subagent's contract against the
|
|
253
|
-
* plugin's declared `mcpServers` — flag a server the plugin doesn't declare
|
|
254
|
-
* (the MCP half of the tool moat; `subagent-tool-contract` checks the built-in
|
|
255
|
-
* half). High-precision: only flags when the plugin SHIPS a declared set,
|
|
256
|
-
* allowlists harness built-ins (`ide`), and skips the plugin-namespaced
|
|
257
|
-
* `mcp__plugin_…` form. Default "warn"; "error" gates CI. Same detector as
|
|
258
|
-
* `scan` (mcpToolIssues).
|
|
259
|
-
*/
|
|
260
|
-
"mcp-tool-resolves"?: RuleSeverity;
|
|
261
|
-
/**
|
|
262
|
-
* A file a COMPILED hook line needs is missing — the runtime, the program or
|
|
263
|
-
* its stamp — so the hook cannot run. Read from the hook-line plan, never
|
|
264
|
-
* from parsing a line. Default "warn"; `vigiles:recommended` raises it to
|
|
265
|
-
* "error". See docs/rules/hook-script-exists.md.
|
|
266
|
-
*/
|
|
267
|
-
"hook-script-exists"?: RuleSeverity;
|
|
268
|
-
/**
|
|
269
|
-
* One finding per hook line vigiles did not write: it cannot say what such a
|
|
270
|
-
* line runs or whether it swallows its own failure, so it names the hook and
|
|
271
|
-
* points at compiled hooks (`vigiles/hook`). Default OFF, also under
|
|
272
|
-
* `vigiles:recommended`: the cure is an experimental API, so it is opt-in
|
|
273
|
-
* until compiled hooks leave experimental. See docs/rules/hand-written-hook.md.
|
|
274
|
-
*/
|
|
275
|
-
"hand-written-hook"?: RuleSeverity;
|
|
276
|
-
/**
|
|
277
|
-
* Cross-reference a subagent's `disallowedTools:` block-list against the
|
|
278
|
-
* catalog — the deny-side mirror of `subagent-tool-contract`. A close typo there
|
|
279
|
-
* blocks NOTHING (you meant to deny `Bash`, wrote `Bsh`), leaving the tool
|
|
280
|
-
* available. High-precision: close-typo only (a never-available tool is
|
|
281
|
-
* harmless to list, a bare unknown is likely a plugin tool). Default "warn";
|
|
282
|
-
* "error" gates CI. Same detector as `scan` (disallowedToolIssues).
|
|
283
|
-
*/
|
|
284
|
-
"disallowed-tools-contract"?: RuleSeverity;
|
|
285
|
-
/**
|
|
286
|
-
* Flag two model-invocable skills whose descriptions are near-identical — the
|
|
287
|
-
* selector can't tell them apart, so the wrong one fires (a precision
|
|
288
|
-
* collision). A DETERMINISTIC NCD proxy for a `--trigger`-class behavioral bug;
|
|
289
|
-
* calibrated FP-safe (only basically-identical text, below the sweep's
|
|
290
|
-
* most-similar distinct pair). Default "warn"; "error" gates CI. Same detector
|
|
291
|
-
* as `scan` (descriptionOverlaps).
|
|
292
|
-
*/
|
|
293
|
-
"description-overlap"?: RuleSeverity;
|
|
294
|
-
/**
|
|
295
|
-
* Flag a model-invocable skill whose `description` is so long the trigger
|
|
296
|
-
* signal is buried — the selector weighs the opening most, so a bloated
|
|
297
|
-
* description hurts recall + precision. A DETERMINISTIC heuristic proxy for a
|
|
298
|
-
* `--trigger`-class behavioral bug; calibrated FP-safe (generous default
|
|
299
|
-
* budget, 500 chars). Default "warn" — a proxy, never gates. Same detector as
|
|
300
|
-
* `scan` (descriptionBudgetIssues).
|
|
301
|
-
*/
|
|
302
|
-
"skill-description-budget"?: RuleSeverity;
|
|
303
|
-
/**
|
|
304
|
-
* Size budgets on a COMPILED instruction file (`compile` from a `.spec.ts`):
|
|
305
|
-
* one `commands` entry, one prose section, and the whole Rules section. The
|
|
306
|
-
* whole always-loaded size is `instruction-weight`'s; `keyFiles` is
|
|
307
|
-
* deprecated, so neither is measured here.
|
|
308
|
-
*
|
|
309
|
-
* Default "warn", which is exactly the behaviour before this rule had a name:
|
|
310
|
-
* the per-entry and per-section budgets print as warnings and never stop a
|
|
311
|
-
* compile; the Rules total is not evaluated unless a threshold is configured.
|
|
312
|
-
* "error" (set by `vigiles:recommended`) makes every budget fail `compile` and
|
|
313
|
-
* `lint`. Options are thresholds — see {@link CompileBudgetConfig}. See
|
|
314
|
-
* docs/rules/compile-budget.md.
|
|
315
|
-
*/
|
|
316
|
-
"compile-budget"?: RuleWithOptions<CompileBudgetConfig>;
|
|
317
|
-
/**
|
|
318
|
-
* Flag a skill/agent whose `---` frontmatter block EXISTS but isn't valid YAML
|
|
319
|
-
* — fields may not parse as intended. CAVEAT: a real YAML parser (js-yaml) is
|
|
320
|
-
* stricter than some loaders, so a one-line `description:` containing a `: `
|
|
321
|
-
* colon or an `<example>` block is flagged even though it may still load.
|
|
322
|
-
* Hence default "warn" (a nudge), not "error" — verify before enforcing. Same
|
|
323
|
-
* detector as `scan` (malformedFrontmatter).
|
|
324
|
-
*/
|
|
325
|
-
"frontmatter-valid"?: RuleSeverity;
|
|
326
|
-
/**
|
|
327
|
-
* Flag a `type: "mcp_tool"` hook action that's incomplete (missing `server` /
|
|
328
|
-
* `tool`) or targets a server the plugin doesn't declare in `mcpServers` — the
|
|
329
|
-
* hook silently never dispatches. High-precision: the undeclared-server half is
|
|
330
|
-
* gated on the plugin shipping a declared set and allowlists built-ins (`ide`),
|
|
331
|
-
* mirroring `mcp-tool-resolves`. Default "warn"; "error" gates CI. Same detector
|
|
332
|
-
* as `scan` (mcpHookIssues).
|
|
333
|
-
*/
|
|
334
|
-
"mcp-hook-target-resolves"?: RuleSeverity;
|
|
335
|
-
/**
|
|
336
|
-
* Flag a unit (subagent / model-invocable skill) whose declared tools hold all
|
|
337
|
-
* THREE legs of Simon Willison's "lethal trifecta" — read private data, ingest
|
|
338
|
-
* untrusted content, AND exfiltrate — a prompt-injection exfil path with no
|
|
339
|
-
* exploit code (Meta's Rule of Two: allow at most two). A capability SET-
|
|
340
|
-
* intersection over the declared contract, NOT a text scan; high-precision (only
|
|
341
|
-
* well-known tools map to a leg). An EXPLICIT all-three contract is a "hard"
|
|
342
|
-
* finding; an inherits-all unit (no contract → every leg) is "advisory". Default
|
|
343
|
-
* "warn" (don't-cry-wolf rollout); raise to "error" to gate CI. Same detector as
|
|
344
|
-
* `scan` (lethalTrifectaIssues). See docs/rules/lethal-trifecta.md.
|
|
345
|
-
*/
|
|
346
|
-
"lethal-trifecta"?: RuleSeverity;
|
|
347
|
-
/**
|
|
348
|
-
* Flag a SKILL.md body referencing a bundled file (`scripts/`/`references/`/
|
|
349
|
-
* `assets/`, or a relative markdown link with an extension) that doesn't exist
|
|
350
|
-
* on disk under the skill dir — the agent reads the instruction, gets nothing,
|
|
351
|
-
* and silently continues. The cross-reference moat applied to the SKILL.md body.
|
|
352
|
-
* High-precision / FP-safe (skips URLs, `$VAR` tokens, `../` escapes, extension-
|
|
353
|
-
* less mentions). Default "warn"; raise to "error" to gate CI. Same detector as
|
|
354
|
-
* `scan` (skillResourceIssues). See docs/rules/skill-resource-resolves.md.
|
|
355
|
-
*/
|
|
356
|
-
"skill-resource-resolves"?: RuleSeverity;
|
|
357
|
-
/**
|
|
358
|
-
* Flag a SKILL.md that opens with frontmatter-looking keys (`name:`,
|
|
359
|
-
* `description:`, …) but has NO opening `---` fence — the harness loads the
|
|
360
|
-
* whole file as body, so the skill has no name/description/trigger and is
|
|
361
|
-
* invisible (never fires). High-precision (a fixed key whitelist; markdown /
|
|
362
|
-
* prose lines never match). Default "warn"; raise to "error" to gate CI. Same
|
|
363
|
-
* detector as `scan` (skillFenceIssues). See docs/rules/skill-missing-fence.md.
|
|
364
|
-
*/
|
|
365
|
-
"skill-missing-fence"?: RuleSeverity;
|
|
366
|
-
/**
|
|
367
|
-
* Flag a functional surface directory (skills/agents/commands) nested INSIDE
|
|
368
|
-
* the `.claude-plugin/` manifest dir, where only `plugin.json` belongs — the
|
|
369
|
-
* harness can't see it, so the surface is invisible (the #1 plugin-author
|
|
370
|
-
* mistake). Pure filesystem check, FP-safe. Default "warn"; raise to "error"
|
|
371
|
-
* to gate CI. Same detector as `scan` (pluginLayoutIssues). See
|
|
372
|
-
* docs/rules/plugin-dir-layout.md.
|
|
373
|
-
*/
|
|
374
|
-
"plugin-dir-layout"?: RuleSeverity;
|
|
375
|
-
/**
|
|
376
|
-
* Flag a lethal trifecta that EMERGES across a delegation edge — a subagent
|
|
377
|
-
* whose effective (own ∪ delegated-to) capability holds all three legs though
|
|
378
|
-
* no single unit does (the combined blast radius). The capability-diff across
|
|
379
|
-
* the delegation tree; skips units the per-unit `lethal-trifecta` already
|
|
380
|
-
* flags (no double-report), FP-safe (explicit edges, wildcard-guarded). Default
|
|
381
|
-
* "warn"; raise to "error" to gate CI. Same detector as `scan`
|
|
382
|
-
* (delegationTrifecta). See docs/rules/delegation-trifecta.md.
|
|
383
|
-
*/
|
|
384
|
-
"delegation-trifecta"?: RuleSeverity;
|
|
385
|
-
/**
|
|
386
|
-
* Flag a hook that LOOKS like it blocks but silently doesn't — a block decision
|
|
387
|
-
* (`exit 2` / `decision` / `permissionDecision`) on an event that can't veto, or
|
|
388
|
-
* the legacy top-level `decision` field on a permission-gated event where only
|
|
389
|
-
* `hookSpecificOutput.permissionDecision` works (#19009, the #1 verified hook
|
|
390
|
-
* pain). FP-safe (conservative literal patterns; the blocking-event sets are
|
|
391
|
-
* read from the dialect, so it runs only where they're declared). Default "warn";
|
|
392
|
-
* raise to "error" to gate CI. Same detector as `scan` (hookBlockFindings). See
|
|
393
|
-
* docs/rules/hook-block-ineffective.md.
|
|
394
|
-
*/
|
|
395
|
-
"hook-block-ineffective"?: RuleSeverity;
|
|
396
|
-
/**
|
|
397
|
-
* Flag a hook `matcher` string that doesn't fire the way it reads — a close
|
|
398
|
-
* typo of a built-in tool (`bash`→`Bash`), a matcher that doesn't COMPILE, an
|
|
399
|
-
* MCP pattern that can match no tool name at all (`mcp_memory_*` instead of
|
|
400
|
-
* `mcp__memory__.*`), an MCP pattern too narrow for real server naming
|
|
401
|
-
* (`mcp__[^_]+__[^_]+` can't cross the `_` in `mcp__Google_Calendar__…`), or a
|
|
402
|
-
* server the plugin doesn't declare. A matcher is a PATTERN, so patterns are
|
|
403
|
-
* validated by compiling and probing, never by literal shape. High-precision
|
|
404
|
-
* (close-typo only; MCP gated on a declared set, built-ins allowlisted;
|
|
405
|
-
* match-all and alternation skipped). Default "warn"; raise to "error" to gate
|
|
406
|
-
* CI. Same detector as `scan` (hookMatcherFindings). See
|
|
407
|
-
* docs/rules/hook-matcher.md.
|
|
408
|
-
*/
|
|
409
|
-
"hook-matcher"?: RuleSeverity;
|
|
410
|
-
/**
|
|
411
|
-
* Validate vigiles-builder calls quoted inside ```ts fences in markdown —
|
|
412
|
-
* `enforce()` / `file()` / `cmd()` / `ref()` — against the real linter catalog,
|
|
413
|
-
* filesystem and package scripts.
|
|
414
|
-
*
|
|
415
|
-
* DEFAULT OFF, and the default is the finding. Measured on two repositories
|
|
416
|
-
* 2026-08-19 (2 582 markdown files, 52 refs): **zero true positives, and every
|
|
417
|
-
* error it has ever raised was a false one** — a design sketch writing
|
|
418
|
-
* `cmd("npm test")` for a package that doesn't exist yet, or a third-party
|
|
419
|
-
* `CLAUDE.md` captured verbatim as benchmark data. The reason is structural,
|
|
420
|
-
* not calibration: a fenced block in prose is a DRAWING of config, and this
|
|
421
|
-
* rule reads it as config. The consumer repo could only reach a clean `lint`
|
|
422
|
-
* by excluding a third of itself, after which the pass scanned 604 files and
|
|
423
|
-
* found 0 refs — inert, and still paying for the walk.
|
|
424
|
-
*
|
|
425
|
-
* Turn it on where markdown really is the source (a docs site whose fences are
|
|
426
|
-
* copy-pasted into live specs). See docs/rules/doc-refs.md.
|
|
427
|
-
*/
|
|
428
|
-
"doc-refs"?: RuleSeverity;
|
|
429
|
-
}
|
|
430
127
|
/** Extract severity from a rule value (handles both simple and tuple forms). */
|
|
431
128
|
export declare function ruleSeverity<T>(rule: RuleWithOptions<T> | undefined): RuleSeverity;
|
|
432
129
|
/** Extract options from a rule value (returns undefined for simple severity). */
|
|
@@ -450,22 +147,23 @@ export declare function ruleOptions<T>(rule: RuleWithOptions<T> | undefined): T
|
|
|
450
147
|
*/
|
|
451
148
|
export type HarnessDeclaration = HarnessDeclarationShape;
|
|
452
149
|
/**
|
|
453
|
-
* Full vigiles configuration, loaded from `.vigilesrc.json
|
|
150
|
+
* Full vigiles configuration, loaded from `.vigilesrc.json`, with `rules` keyed
|
|
151
|
+
* by a string id — the form generic code takes.
|
|
454
152
|
*
|
|
455
153
|
* 🔴 DERIVED FROM THE SCHEMA, NOT WRITTEN BESIDE IT. The shape, the defaults and
|
|
456
|
-
* the per-key prose all live in `./config-schema.ts
|
|
457
|
-
*
|
|
458
|
-
*
|
|
459
|
-
*
|
|
460
|
-
*
|
|
461
|
-
*
|
|
462
|
-
*
|
|
154
|
+
* the per-key prose all live in `./config-schema.ts`, and the `rules` are built
|
|
155
|
+
* from the rule set the composition root hands in; the root's PRECISE type
|
|
156
|
+
* (each id with its own options) is `VigilesConfig` in `src/rules/index.ts`. A
|
|
157
|
+
* hand-written twin is the copy that drifts: `harness` and `surfaceRoots` lived
|
|
158
|
+
* in that twin, in `docs/cli.md` and in the loader's coercions, and the three
|
|
159
|
+
* disagreed about what was read (#240). The per-rule prose that lived in a
|
|
160
|
+
* hand-written `RulesConfig` here is each rule's `summary` and its doc.
|
|
463
161
|
*
|
|
464
162
|
* The re-export is TYPE-ONLY on purpose — `types.ts` is imported by node-free
|
|
465
163
|
* core modules, and a value import of the schema module would pull Zod into
|
|
466
164
|
* every one of them.
|
|
467
165
|
*/
|
|
468
|
-
export type VigilesConfig =
|
|
166
|
+
export type VigilesConfig = VigilesConfigOf<RulesConfig>;
|
|
469
167
|
/** Valid marker types for rule detection. */
|
|
470
168
|
export type MarkerType = "headings" | "checkboxes";
|
|
471
169
|
/** Options for parseRules. */
|
package/dist/core/validate.d.ts
CHANGED
|
@@ -1,17 +1,12 @@
|
|
|
1
|
+
import { type ConfigSet } from "./config-schema.js";
|
|
1
2
|
import type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, HarnessDeclaration, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions } from "./types.js";
|
|
2
3
|
export type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, HarnessDeclaration, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions, };
|
|
3
4
|
/**
|
|
4
|
-
* The
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* It used to be the literal beside the type, which is exactly the pair that
|
|
8
|
-
* drifts: `rule-meta.test.ts` already cross-checks each rule's documented
|
|
9
|
-
* `defaultSeverity` against this object, and it could only ever catch a doc that
|
|
10
|
-
* disagreed with the literal, never a literal that disagreed with what parsing
|
|
11
|
-
* actually produced. Reading it out of the parser closes that gap: this IS what
|
|
12
|
-
* a `{}` config loads as.
|
|
5
|
+
* The defaults with `presets` applied — an empty file extended on the CLI.
|
|
6
|
+
* There is no rule-set-free default here: what every rule defaults to is
|
|
7
|
+
* declared by the rule, and the set arrives as `set` from the root.
|
|
13
8
|
*/
|
|
14
|
-
export declare
|
|
9
|
+
export declare function configDefaults<C>(set: ConfigSet<C>, presets?: readonly string[]): C;
|
|
15
10
|
export declare function findInstructionFiles(cwd: string, configFiles?: string[]): string[];
|
|
16
11
|
/**
|
|
17
12
|
* Read and VALIDATE `.vigilesrc.json`.
|
|
@@ -45,9 +40,15 @@ export declare function findInstructionFiles(cwd: string, configFiles?: string[]
|
|
|
45
40
|
* does not execute until the function is called. A rail that never reads a
|
|
46
41
|
* config never pays for the validator.
|
|
47
42
|
*/
|
|
48
|
-
export declare function loadConfig(
|
|
43
|
+
export declare function loadConfig<C>(
|
|
44
|
+
/** The config for the rule set the root hands in (`configFor`). */
|
|
45
|
+
set: ConfigSet<C>, searchFrom?: string, { onInvalid, presets, }?: Readonly<{
|
|
49
46
|
onInvalid?: "throw" | "warn";
|
|
50
|
-
|
|
47
|
+
/** Presets applied on top of the file's own (`--preset=`), see
|
|
48
|
+
* `ConfigSet.parse`. Applied to the defaults too, so they work in a repo
|
|
49
|
+
* with no `.vigilesrc.json` at all. */
|
|
50
|
+
presets?: readonly string[];
|
|
51
|
+
}>): C;
|
|
51
52
|
export declare function parseRules(content: string, { ruleMarkers }?: ParseOptions): ParsedRule[];
|
|
52
53
|
export declare function validate(content: string, { ruleMarkers, rules: rulesConfig, filePath, dialect }?: ValidateOptions): ValidationResult;
|
|
53
54
|
export declare function readInstructionFile(filePath: string, options?: ReadOptions): ReadResult;
|