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.
Files changed (62) hide show
  1. package/action.yml +18 -0
  2. package/dist/adapters/claude-code/dialect.js +5 -0
  3. package/dist/audit-report.d.ts +14 -1
  4. package/dist/audit-report.js +21 -5
  5. package/dist/audit-report.template.html +33 -28
  6. package/dist/audit-score.d.ts +4 -1
  7. package/dist/audit-score.js +3 -1
  8. package/dist/audit-verdict.d.ts +3 -1
  9. package/dist/cli-flag-check.d.ts +1 -1
  10. package/dist/cli-flag-check.js +5 -1
  11. package/dist/cli-flags.d.ts +1 -1
  12. package/dist/cli-main.js +153 -72
  13. package/dist/core/CLAUDE.md.spec.js +2 -2
  14. package/dist/core/adopt.js +32 -8
  15. package/dist/core/apply-rules.d.ts +71 -0
  16. package/dist/core/apply-rules.js +48 -0
  17. package/dist/core/compile.d.ts +1 -1
  18. package/dist/core/compile.js +47 -14
  19. package/dist/core/config-migrations.d.ts +69 -0
  20. package/dist/core/config-migrations.js +145 -0
  21. package/dist/core/config-schema.d.ts +163 -187
  22. package/dist/core/config-schema.js +185 -345
  23. package/dist/core/dialect.d.ts +1 -1
  24. package/dist/core/dialect.js +2 -0
  25. package/dist/core/linter-adapter.d.ts +1 -1
  26. package/dist/core/presets.d.ts +31 -46
  27. package/dist/core/presets.js +25 -51
  28. package/dist/core/rule.d.ts +213 -0
  29. package/dist/core/rule.js +37 -0
  30. package/dist/core/skill-resources.d.ts +85 -15
  31. package/dist/core/skill-resources.js +63 -37
  32. package/dist/core/spec.d.ts +17 -0
  33. package/dist/core/types.d.ts +12 -314
  34. package/dist/core/validate.d.ts +13 -12
  35. package/dist/core/validate.js +29 -28
  36. package/dist/doc-commands.d.ts +2 -2
  37. package/dist/optimize.d.ts +2 -1
  38. package/dist/overrides.d.ts +13 -9
  39. package/dist/overrides.js +1 -1
  40. package/dist/rules/CLAUDE.md.spec.d.ts +3 -0
  41. package/dist/rules/CLAUDE.md.spec.js +22 -0
  42. package/dist/rules/groups.d.ts +32 -0
  43. package/dist/rules/groups.js +27 -0
  44. package/dist/rules/index.d.ts +412 -0
  45. package/dist/{core/rule-meta.js → rules/index.js} +301 -209
  46. package/dist/rules/skill-resource-resolves.d.ts +36 -0
  47. package/dist/rules/skill-resource-resolves.js +51 -0
  48. package/dist/run-hook.d.ts +1 -1
  49. package/dist/scan-core.d.ts +7 -9
  50. package/dist/scan-core.js +7 -10
  51. package/dist/scan-files.js +1 -4
  52. package/dist/scan.d.ts +11 -16
  53. package/dist/scan.js +31 -8
  54. package/dist/score-core.js +3 -9
  55. package/dist/setup-plan.d.ts +6 -26
  56. package/dist/setup-plan.js +27 -60
  57. package/dist/skill-harness.d.ts +3 -1
  58. package/dist/skill-harness.js +5 -2
  59. package/dist/vigilesrc.schema.json +18 -3
  60. package/package.json +2 -2
  61. package/packages/eslint-config/index.mjs +61 -0
  62. package/dist/core/rule-meta.d.ts +0 -94
@@ -1,10 +1,8 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.FOLDED_RULES = exports.MOVED_TO_OVERRIDES = exports.REPLACED_KEYS = exports.VigilesConfigError = exports.vigilesConfigSchema = exports.RULE_NAMES = exports.PROJECT_CONFIG_FILE = void 0;
4
- exports.parseVigilesConfig = parseVigilesConfig;
5
- exports.replacedKeyMessage = replacedKeyMessage;
6
- exports.movedToOverridesMessages = movedToOverridesMessages;
7
- exports.foldedRuleMessages = foldedRuleMessages;
3
+ exports.VigilesConfigError = exports.DEFAULT_RULE_MARKERS = exports.stringList = exports.PROJECT_CONFIG_FILE = void 0;
4
+ exports.configFor = configFor;
5
+ exports.parsePresetFlags = parsePresetFlags;
8
6
  exports.formatConfigIssues = formatConfigIssues;
9
7
  /**
10
8
  * `.vigilesrc.json`, AS A SCHEMA — the one place the config's shape, its
@@ -25,17 +23,19 @@ exports.formatConfigIssues = formatConfigIssues;
25
23
  * happening inside the tool, so the shape is now DECLARED and anything outside
26
24
  * it is named out loud.
27
25
  *
28
- * THE TYPE IS DERIVED FROM THIS, not written beside it: `VigilesConfig` is
29
- * `z.infer<typeof vigilesConfigSchema>` (see `./types.ts`), so a field cannot
30
- * exist in the type and not in the validator, which is how `surfaceRoots` ended
31
- * up documented in `docs/cli.md` for a week after it stopped being read.
26
+ * THE TYPE IS DERIVED FROM THIS, not written beside it: `VigilesConfigOf` is
27
+ * the static keys' `z.output` plus the rule set's own entries (see `./types.ts`),
28
+ * so a field cannot exist in the type and not in the validator, which is how
29
+ * `surfaceRoots` ended up documented in `docs/cli.md` for a week after it
30
+ * stopped being read.
32
31
  *
33
- * DEFAULTS LIVE HERE TOO, and that is what makes the derivation exact. Every key
32
+ * THE RULES ARE A PARAMETER. The `rules` object, its defaults and the presets
33
+ * `extends` accepts are BUILT from the rule set a composition root hands to
34
+ * {@link configFor} — each rule declares its id, default and options schema in
35
+ * its own module (`src/rules/`), and this file names none of them. Every key
34
36
  * the loaded config is guaranteed to carry (`rules`, `files`, `ruleMarkers`)
35
- * carries a Zod `.default(...)`, and Zod's inferred OUTPUT type for a defaulted
36
- * field is non-optional — so `z.infer` reproduces the old
37
- * `rules: Required<RulesConfig>` exactly, rather than approximating it. Parsing
38
- * `{}` yields byte-for-byte the old `DEFAULT_CONFIG`.
37
+ * carries a Zod `.default(...)`, so parsing `{}` yields every rule at its
38
+ * shipped default (`src/rules/index.test.ts` pins that snapshot).
39
39
  *
40
40
  * ⚠️ ZOD COSTS ~45 ms TO IMPORT (measured, Zod 4.6.5), AND IT IS IMPORTED
41
41
  * NORMALLY — `src/core/validate.ts` has a top-level `import`, not a deferred
@@ -52,6 +52,7 @@ exports.formatConfigIssues = formatConfigIssues;
52
52
  const zod_1 = require("zod");
53
53
  const edit_distance_js_1 = require("./edit-distance.js");
54
54
  const presets_js_1 = require("./presets.js");
55
+ const rule_js_1 = require("./rule.js");
55
56
  /** The config file; the directory holding it is a project root. */
56
57
  exports.PROJECT_CONFIG_FILE = ".vigilesrc.json";
57
58
  // ---------------------------------------------------------------------------
@@ -103,143 +104,34 @@ const withOptions = (options) => zod_1.z.union([
103
104
  * `asStringArray` did; the difference is that anything that is neither is now a
104
105
  * schema error instead of a `console.warn` nobody reads.
105
106
  */
106
- const stringList = zod_1.z
107
+ exports.stringList = zod_1.z
107
108
  .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
108
109
  .transform((v) => (typeof v === "string" ? [v] : v));
109
110
  // ---------------------------------------------------------------------------
110
- // Rules
111
- // ---------------------------------------------------------------------------
112
- /** Min % thresholds for the `coverage` rule. */
113
- const coverageThresholds = zod_1.z
114
- .object({
115
- /** Min % of enabled linter rules with `enforce()` declarations. */
116
- linterRules: zod_1.z.number().optional(),
117
- /** Min % of npm scripts documented in spec commands. */
118
- scripts: zod_1.z.number().optional(),
119
- })
120
- .strict();
121
- /**
122
- * Discovery options shared by the `untested-*` rules. `include` is where tests
123
- * live — a real option of the rule. Skipping paths is not: that is `overrides`
124
- * with the rule off (see {@link MOVED_TO_OVERRIDES}).
125
- */
126
- const testCoverageConfig = zod_1.z
127
- .object({
128
- include: stringList.optional(),
129
- testExtension: zod_1.z.string().optional(),
130
- })
131
- .strict();
132
- /**
133
- * Options for `instruction-weight`. `max` is an opt-in ABSOLUTE ceiling on the
134
- * always-loaded total, in the harness's own unit — independent of the ratchet's
135
- * baseline. A positive integer: `0` would fail every repo that has an
136
- * instruction file, and `"40000"` is a string the author meant as a number.
137
- */
138
- const instructionWeightConfig = zod_1.z
139
- .object({
140
- max: zod_1.z.number().int().positive().optional(),
141
- })
142
- .strict();
143
- /**
144
- * Thresholds for `compile-budget`, in characters. Each one left out keeps its
145
- * built-in default; `0` turns that one budget off.
146
- */
147
- const compileBudgetThresholds = zod_1.z
148
- .object({
149
- /** One `commands` description. */
150
- maxEntryChars: zod_1.z.number().optional(),
151
- /** One named prose section. */
152
- maxSectionChars: zod_1.z.number().optional(),
153
- /** The whole rendered Rules section. */
154
- maxRulesChars: zod_1.z.number().optional(),
155
- })
156
- .strict();
157
- /**
158
- * Every validation rule, with its shipped default severity.
159
- *
160
- * 🔴 THIS OBJECT IS THE RULE SET. `rules-docs-in-sync` already treats the
161
- * `RulesConfig` keys as the single source of truth the docs must track; now they
162
- * are also what the validator accepts, so a rule name that is not here is
163
- * REJECTED with the near-miss suggested rather than silently ignored — which is
164
- * the same class of bug as a misspelled harness name, and was equally quiet.
165
- */
166
- const rulesSchema = zod_1.z
167
- .object({
168
- "spec-refs": severitySchema.default("error"),
169
- "orphan-docs": severitySchema.default("warn"),
170
- "duplicate-rules": severitySchema.default("warn"),
171
- "require-instructions-spec": severitySchema.default("warn"),
172
- "require-skill-spec": severitySchema.default(false),
173
- integrity: severitySchema.default("warn"),
174
- coverage: withOptions(coverageThresholds).default(false),
175
- "untested-skill": withOptions(testCoverageConfig).default("warn"),
176
- "untested-subagent": withOptions(testCoverageConfig).default("warn"),
177
- "untested-hook": withOptions(testCoverageConfig).default("warn"),
178
- "untested-output-style": withOptions(testCoverageConfig).default("warn"),
179
- "unmarked-refs": severitySchema.default("warn"),
180
- "subagent-tool-contract": severitySchema.default("warn"),
181
- "hook-events": severitySchema.default("warn"),
182
- "subagent-frontmatter": severitySchema.default("warn"),
183
- "mcp-config": severitySchema.default("warn"),
184
- "skill-frontmatter": severitySchema.default("warn"),
185
- "mcp-tool-resolves": severitySchema.default("warn"),
186
- "hook-script-exists": severitySchema.default("warn"),
187
- // OFF: its only cure is a compiled hook, an experimental API (docs/experimental.md).
188
- "hand-written-hook": severitySchema.default(false),
189
- "disallowed-tools-contract": severitySchema.default("warn"),
190
- "description-overlap": severitySchema.default("warn"),
191
- "skill-description-budget": severitySchema.default("warn"),
192
- "compile-budget": withOptions(compileBudgetThresholds).default("warn"),
193
- "frontmatter-valid": severitySchema.default("warn"),
194
- "mcp-hook-target-resolves": severitySchema.default("warn"),
195
- "lethal-trifecta": severitySchema.default("warn"),
196
- "skill-resource-resolves": severitySchema.default("warn"),
197
- "skill-missing-fence": severitySchema.default("warn"),
198
- "plugin-dir-layout": severitySchema.default("warn"),
199
- "delegation-trifecta": severitySchema.default("warn"),
200
- "hook-block-ineffective": severitySchema.default("warn"),
201
- "hook-matcher": severitySchema.default("warn"),
202
- "doc-refs": severitySchema.default(false),
203
- "instruction-weight": withOptions(instructionWeightConfig).default("error"),
204
- "deprecated-key-files": severitySchema.default("warn"),
205
- })
206
- .strict();
207
- /** The rule names, for the "did you mean" on an unknown one. */
208
- exports.RULE_NAMES = Object.keys(rulesSchema.shape);
209
- // ---------------------------------------------------------------------------
210
111
  // Overrides — per-path severities (`./overrides.ts`)
211
112
  // ---------------------------------------------------------------------------
212
- /**
213
- * The rule set as an override may spell it: every rule, a SEVERITY only, no
214
- * default. Options stay in `rules` — one place — so `["error", { … }]` here is
215
- * refused rather than accepted and never read. Derived from `rulesSchema`'s
216
- * keys, so a rule added there is overridable with no second list, and an
217
- * unknown name gets the same "did you mean" as in `rules`.
218
- */
219
- const overrideRulesSchema = zod_1.z
220
- .object(Object.fromEntries(Object.keys(rulesSchema.shape).map((name) => [
221
- name,
222
- severitySchema.optional(),
223
- ])))
224
- .strict();
225
113
  /**
226
114
  * One `overrides` entry. `files` are root-relative globs with top-level
227
115
  * `exclude`'s semantics; an entry with none would apply nowhere, so it is
228
- * refused rather than kept as a line that does nothing.
116
+ * refused rather than kept as a line that does nothing. Its `rules` are every
117
+ * rule, a SEVERITY only, no default: options stay in `rules` — one place — so
118
+ * `["error", { … }]` here is refused rather than accepted and never read.
229
119
  */
230
- const overrideSchema = zod_1.z
120
+ const overrideSchema = (ruleNames) => zod_1.z
231
121
  .object({
232
- files: stringList.refine((globs) => globs.length > 0, {
122
+ files: exports.stringList.refine((globs) => globs.length > 0, {
233
123
  message: "needs at least one glob",
234
124
  }),
235
- rules: overrideRulesSchema,
125
+ rules: zod_1.z
126
+ .object(Object.fromEntries(ruleNames.map((name) => [name, severitySchema.optional()])))
127
+ .strict(),
236
128
  })
237
129
  .strict();
238
130
  // ---------------------------------------------------------------------------
239
131
  // Harnesses (#240)
240
132
  // ---------------------------------------------------------------------------
241
133
  /**
242
- * ONE harness's entry in {@link vigilesConfigSchema}'s `harnesses`.
134
+ * ONE harness's entry in the config's `harnesses`.
243
135
  *
244
136
  * `.strict()` is load-bearing here specifically: the whole reason this key
245
137
  * exists is that a declaration which reaches nothing used to be silent, and
@@ -247,26 +139,25 @@ const overrideSchema = zod_1.z
247
139
  */
248
140
  const harnessDeclarationSchema = zod_1.z
249
141
  .object({
250
- roots: stringList.optional(),
142
+ roots: exports.stringList.optional(),
251
143
  })
252
144
  .strict();
253
145
  // ---------------------------------------------------------------------------
254
146
  // The config
255
147
  // ---------------------------------------------------------------------------
148
+ /** What counts as a rule in markdown, by default: both constructs. */
149
+ exports.DEFAULT_RULE_MARKERS = ["headings", "checkboxes"];
256
150
  /**
257
- * The whole of `.vigilesrc.json`.
258
- *
259
- * `.strict()` at the top level is the check that did not exist: an unrecognized
260
- * key is now a named error with a suggestion, where it used to be spread into
261
- * the config object and never read.
151
+ * The keys of `.vigilesrc.json` that do not depend on the rule set, in the
152
+ * order the "Known: …" list prints them (it is capped, so the keys people
153
+ * misspell most come first). `rules`, `overrides` and `extends` are built from
154
+ * the rule set by {@link configFor} and slotted in around these.
262
155
  */
263
- exports.vigilesConfigSchema = zod_1.z
264
- .object({
156
+ const configKeys = {
265
157
  /** Which markdown constructs count as a rule — headings, checkboxes, or both. */
266
158
  ruleMarkers: zod_1.z
267
- .array(zod_1.z.enum(["headings", "checkboxes"]))
268
- .default(["headings", "checkboxes"]),
269
- rules: rulesSchema.prefault({}),
159
+ .array(zod_1.z.enum(exports.DEFAULT_RULE_MARKERS))
160
+ .default([...exports.DEFAULT_RULE_MARKERS]),
270
161
  /** The instruction files to validate. */
271
162
  files: zod_1.z.array(zod_1.z.string()).default(["CLAUDE.md"]),
272
163
  maxRules: zod_1.z.number().optional(),
@@ -287,91 +178,168 @@ exports.vigilesConfigSchema = zod_1.z
287
178
  bundles: zod_1.z.enum(["root", "all"]).optional(),
288
179
  orphans: zod_1.z
289
180
  .object({
290
- include: stringList.optional(),
181
+ include: exports.stringList.optional(),
291
182
  })
292
183
  .strict()
293
184
  .optional(),
294
- exclude: stringList.optional(),
295
- /**
296
- * Per-path rule severities, ESLint's `{ files, rules }` list: a later entry
297
- * wins over an earlier one, any entry over `rules`, `rules` over `extends`.
298
- * Resolved by `ruleResolver` (`./overrides.ts`).
299
- */
300
- overrides: zod_1.z.array(overrideSchema).optional(),
301
- sharedDirs: stringList.optional(),
185
+ exclude: exports.stringList.optional(),
186
+ };
187
+ /** The keys after `overrides`; `extends` and `$schema` close the shape. */
188
+ const configTailKeys = {
189
+ sharedDirs: exports.stringList.optional(),
302
190
  harnesses: zod_1.z.record(zod_1.z.string(), harnessDeclarationSchema).optional(),
303
191
  audit: zod_1.z.object({ measure: zod_1.z.boolean().optional() }).strict().optional(),
304
192
  eval: zod_1.z.object({ apiVersion: zod_1.z.number().optional() }).strict().optional(),
305
193
  nudge: zod_1.z.literal("dismissed").optional(),
306
- /**
307
- * A named preset whose rule severities apply UNDER `rules` — ESLint's
308
- * `extends`. `"vigiles:recommended"` gates the structural group (see
309
- * `./presets.ts`); an explicit `rules` entry overrides it. Applied by
310
- * {@link parseVigilesConfig}, which is why this key is only VALIDATED here.
311
- * Placed after the keys people misspell most: the "Known:" list is capped.
312
- */
313
- extends: zod_1.z.enum(presets_js_1.PRESET_NAMES).optional(),
314
- /**
315
- * The editor's pointer at the published JSON Schema. Accepted, never read.
316
- *
317
- * 🔴 IT IS DECLARED HERE RATHER THAN EXCUSED IN THE UNKNOWN-KEY WALKER, and
318
- * the reason is that the walker is only half the surface. `dist/vigilesrc.
319
- * schema.json` is generated FROM this object by
320
- * `scripts/build-config-schema.mjs`, with `additionalProperties: false`, so
321
- * a key missing here is refused TWICE: once by the CLI, and once by the
322
- * editor being pointed at the schema. Measured before this key existed, on
323
- * `{"$schema": <the schema's own $id>, "harnesses": {"claude-code": {}}}`:
324
- *
325
- * ```
326
- * $ vigiles audit . --no-interactive
327
- * ✗ .vigilesrc.json: unknown key "$schema" in (top level). Known: …
328
- * (exit 2)
329
- * $ # and the same document against dist/vigilesrc.schema.json:
330
- * additionalProperties: should NOT have additional properties ($schema)
331
- * ```
332
- *
333
- * An exception in the walker would have fixed the first line and left the
334
- * second — a red squiggle on the one line whose entire job is to turn the
335
- * squiggles on. One declaration, both halves, because both derive from here.
336
- *
337
- * It is LAST in the shape on purpose: `knownKeysAt` reads this object to
338
- * build the "Known: …" candidate list, which is capped, so a key nobody
339
- * misspells belongs past the cap rather than at the head of the suggestion.
340
- */
341
- $schema: zod_1.z.string().optional(),
342
- })
343
- .strict();
194
+ };
344
195
  /**
345
- * Parse a raw `.vigilesrc.json` value — THE one entry point every reader uses.
196
+ * The editor's pointer at the published JSON Schema. Accepted, never read.
346
197
  *
347
- * 🔴 THE PRESET IS MERGED INTO THE RAW INPUT, BEFORE THE SCHEMA, for one reason:
348
- * after parsing, every rule carries a value (the schema fills each default), so
349
- * "the user wrote `hook-events: warn`" and "nobody wrote it" are the same
350
- * output, and an explicit downgrade could not win over the preset. Before
351
- * parsing, the user's own `rules` keys are exactly what they wrote. So the
352
- * preset's severities go UNDER them, and the schema then normalizes and
353
- * validates the result as if the user had typed both.
198
+ * 🔴 IT IS DECLARED HERE RATHER THAN EXCUSED IN THE UNKNOWN-KEY WALKER, and
199
+ * the reason is that the walker is only half the surface. `dist/vigilesrc.
200
+ * schema.json` is generated FROM this schema by
201
+ * `scripts/build-config-schema.mjs`, with `additionalProperties: false`, so
202
+ * a key missing here is refused TWICE: once by the CLI, and once by the
203
+ * editor being pointed at the schema. Measured before this key existed, on
204
+ * `{"$schema": <the schema's own $id>, "harnesses": {"claude-code": {}}}`:
354
205
  *
355
- * Only a recognized preset with an object (or absent) `rules` is expanded;
356
- * anything else is passed through untouched for the schema to refuse with its
357
- * own message, so a typo in `extends` is reported, never silently ignored.
206
+ * ```
207
+ * $ vigiles audit . --no-interactive
208
+ * ✗ .vigilesrc.json: unknown key "$schema" in (top level). Known: …
209
+ * (exit 2)
210
+ * $ # and the same document against dist/vigilesrc.schema.json:
211
+ * additionalProperties: should NOT have additional properties ($schema)
212
+ * ```
213
+ *
214
+ * It is LAST in the shape on purpose: `knownKeysAt` reads the schema to build
215
+ * the "Known: …" candidate list, which is capped, so a key nobody misspells
216
+ * belongs past the cap rather than at the head of the suggestion.
358
217
  */
359
- function parseVigilesConfig(raw) {
360
- return exports.vigilesConfigSchema.safeParse(withPresetRules(raw));
218
+ const schemaPointer = zod_1.z.string().optional();
219
+ /** Each rule's key with its default and, with `options`, the tuple form. */
220
+ function rulesSchemaOf(rules) {
221
+ return zod_1.z
222
+ .object(Object.fromEntries(rules.map((r) => [
223
+ r.id,
224
+ (r.options ? withOptions(r.options) : severitySchema).default((0, rule_js_1.configDefault)(r)),
225
+ ])))
226
+ .strict();
227
+ }
228
+ /** The whole schema, `rules`/`overrides`/`extends` slotted in key order. */
229
+ function configSchemaOf(rules, presetNames) {
230
+ const presetName = zod_1.z.enum(presetNames);
231
+ const { ruleMarkers, ...bodyKeys } = configKeys;
232
+ return zod_1.z
233
+ .object({
234
+ ruleMarkers,
235
+ rules: rulesSchemaOf(rules).prefault({}),
236
+ ...bodyKeys,
237
+ /**
238
+ * Per-path rule severities, ESLint's `{ files, rules }` list: a later
239
+ * entry wins over an earlier one, any entry over `rules`, `rules` over
240
+ * `extends`. Resolved by `ruleResolver` (`../overrides.ts`).
241
+ */
242
+ overrides: zod_1.z.array(overrideSchema(rules.map((r) => r.id))).optional(),
243
+ ...configTailKeys,
244
+ /**
245
+ * A named preset (or a list of them) whose rule severities apply UNDER
246
+ * `rules` — ESLint's `extends`. A later preset wins over an earlier one,
247
+ * and an explicit `rules` entry overrides them all. Applied by `parse`,
248
+ * which is why this key is only VALIDATED here.
249
+ */
250
+ extends: zod_1.z.union([presetName, zod_1.z.array(presetName)]).optional(),
251
+ $schema: schemaPointer,
252
+ })
253
+ .strict();
361
254
  }
362
- /** `raw` with its `extends` preset's rules placed under its own `rules`. */
363
- function withPresetRules(raw) {
255
+ /**
256
+ * Build `.vigilesrc.json` for a rule set: each rule's key with its default and,
257
+ * for a rule with `options`, the `[severity, options]` form; `overrides` over
258
+ * the same ids; `extends` over the groups' preset names.
259
+ *
260
+ * The one place Zod cannot carry the type: an object built from
261
+ * `Object.fromEntries` has string keys, so the parse result is narrowed to the
262
+ * set's precise type by `complete`, which checks at run time that every id is
263
+ * present — never by an assertion.
264
+ */
265
+ function configFor(rules, groups) {
266
+ const ruleNames = rules.map((r) => r.id);
267
+ const presets = Object.values(groups).flatMap((g) => g.preset?.name ?? []);
268
+ const presetNames = [...new Set(presets)];
269
+ const schema = configSchemaOf(rules, presetNames);
270
+ const presetRules = (0, presets_js_1.presetRulesOf)(rules, groups);
271
+ const complete = (c) => ruleNames.every((id) => id in c.rules);
272
+ return {
273
+ schema,
274
+ ruleNames,
275
+ presetNames,
276
+ parse(raw, extraPresets = []) {
277
+ const parsed = schema.safeParse(withPresetRules(raw, presetNames, presetRules, extraPresets));
278
+ if (!parsed.success)
279
+ return parsed;
280
+ const data = parsed.data;
281
+ if (!complete(data))
282
+ throw new Error("configFor: a parsed config lost a rule");
283
+ return { success: true, data };
284
+ },
285
+ };
286
+ }
287
+ /** `raw` with its presets' rules placed under its own `rules`, in order. */
288
+ function withPresetRules(raw, known, presetRules, extraPresets) {
364
289
  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
365
290
  return raw;
366
- const preset = "extends" in raw ? raw.extends : undefined;
367
- const rules = "rules" in raw ? raw.rules : undefined;
368
- if (!(0, presets_js_1.isPresetName)(preset))
291
+ const extended = (0, presets_js_1.extendedPresets)(known, "extends" in raw ? raw.extends : undefined);
292
+ if (extended === null)
369
293
  return raw;
294
+ const layer = [...extended, ...extraPresets].reduce((acc, name) => ({ ...acc, ...presetRules(name) }), {});
295
+ return withRulesUnder(raw, layer);
296
+ }
297
+ /**
298
+ * `raw` with `layer` placed UNDER its own `rules`. A non-object `rules` is left
299
+ * for the schema to refuse with its own message.
300
+ */
301
+ function withRulesUnder(raw, layer) {
302
+ if (Object.keys(layer).length === 0)
303
+ return raw;
304
+ const rules = "rules" in raw ? raw.rules : undefined;
370
305
  if (rules === undefined)
371
- return { ...raw, rules: { ...(0, presets_js_1.presetRules)(preset) } };
306
+ return { ...raw, rules: layer };
372
307
  if (typeof rules !== "object" || rules === null || Array.isArray(rules))
373
308
  return raw;
374
- return { ...raw, rules: { ...(0, presets_js_1.presetRules)(preset), ...rules } };
309
+ return { ...raw, rules: { ...layer, ...rules } };
310
+ }
311
+ /** The non-empty, trimmed entries of a comma list. */
312
+ function commaList(value) {
313
+ return value
314
+ .split(",")
315
+ .map((v) => v.trim())
316
+ .filter((v) => v.length > 0);
317
+ }
318
+ /**
319
+ * Parse the values of `--preset=` (each may be a comma list) into preset
320
+ * names, through the SAME enum `extends` validates with, so the config file
321
+ * and the command line refuse an unknown name with the same message. The
322
+ * `vigiles:` prefix is optional on the command line: `--preset=experimental`
323
+ * and `--preset=vigiles:experimental` are the same preset.
324
+ */
325
+ function parsePresetFlags(known, values) {
326
+ const short = known.map((n) => n.slice(presets_js_1.PRESET_PREFIX.length)).join(", ");
327
+ const names = values.flatMap(commaList);
328
+ if (names.length === 0 && values.length > 0)
329
+ return { ok: false, message: `--preset: needs a name. Known: ${short}.` };
330
+ const presetName = zod_1.z.enum(known);
331
+ const parsed = names.map((given) => ({
332
+ given,
333
+ result: presetName.safeParse(given.startsWith(presets_js_1.PRESET_PREFIX) ? given : `${presets_js_1.PRESET_PREFIX}${given}`),
334
+ }));
335
+ const bad = parsed.find((p) => !p.result.success);
336
+ if (bad !== undefined && !bad.result.success)
337
+ return {
338
+ ok: false,
339
+ message: `--preset: unknown preset "${bad.given}" — ${bad.result.error.issues[0]?.message ?? "invalid"}. Known: ${short}.`,
340
+ };
341
+ const ok = parsed.flatMap((p) => (p.result.success ? [p.result.data] : []));
342
+ return { ok: true, presets: [...new Set(ok)] };
375
343
  }
376
344
  /**
377
345
  * A `.vigilesrc.json` that cannot be honoured as written.
@@ -387,134 +355,6 @@ class VigilesConfigError extends Error {
387
355
  name = "VigilesConfigError";
388
356
  }
389
357
  exports.VigilesConfigError = VigilesConfigError;
390
- /**
391
- * The two keys `harnesses` replaced, and the sentence each one gets (#240).
392
- *
393
- * They are listed here rather than left to `.strict()`'s "Unrecognized key"
394
- * because the reader of that message is someone whose config USED to work: they
395
- * need the new spelling, not the news that the old one is unknown. `.strict()`
396
- * would tell them the truth in the least useful possible way.
397
- */
398
- exports.REPLACED_KEYS = [
399
- {
400
- key: "harness",
401
- // The literal OLD config text this migration notice quotes back at the user:
402
- // a historical artefact, not a fact about a harness, so there is no port to
403
- // read it off. This is the one exemption here that is not debt.
404
- // eslint-disable-next-line local/no-harness-names -- quoted legacy config
405
- was: '"harness": ["claude-code", "codex"]',
406
- now: "a KEY per harness",
407
- },
408
- {
409
- key: "surfaceRoots",
410
- was: '"surfaceRoots": [".ai"]',
411
- now: '"roots" INSIDE the harness that reads them',
412
- },
413
- ];
414
- /**
415
- * The message a config written in the replaced shape gets.
416
- *
417
- * `names` are the harnesses the user's OWN config named under the removed
418
- * `harness` key, so the worked example below shows THEIR migration.
419
- *
420
- * 🔴 IT USED TO BE A FIXED EXAMPLE — `{ "harnesses": { "claude-code": …,
421
- * "codex": {} } }`, two names typed into the core. Its own comment called that
422
- * debt and predicted the failure: "with a third adapter this sample goes
423
- * stale". Reading the names from the config being migrated is better than
424
- * reading them from the registry would have been, and it is available here:
425
- * it shows the reader their own keys instead of somebody else's.
426
- */
427
- function replacedKeyMessage(present, names) {
428
- // Empty when the config used only `surfaceRoots`, or named no harness — a
429
- // placeholder the reader will obviously replace, never an invented name.
430
- const example = (names.length > 0 ? names : ["<harness>"])
431
- .map((n, i) => `"${n}": ${i === 0 ? '{ "roots": [".ai"] }' : "{}"}`)
432
- .join(", ");
433
- return (`.vigilesrc.json: ${present.map((k) => `"${k.key}"`).join(" and ")} ` +
434
- `${present.length === 1 ? "was" : "were"} replaced by one nested key, "harnesses".\n` +
435
- ` Write: { "harnesses": { ${example} } }\n` +
436
- present.map((k) => ` - ${k.was} → ${k.now}`).join("\n") +
437
- `\n The old harness ARRAY's order silently decided what got read: one order graded the ` +
438
- `skills and read no instruction file, the other read the instruction file and found no ` +
439
- `skills. Scoping each root under the harness that reads it removes the order.`);
440
- }
441
- /**
442
- * The per-rule `exclude` options that became `overrides`, and the rules an
443
- * equivalent override turns off. `untested-*` shared ONE merged option set, so
444
- * an `exclude` on any of them skipped those paths for all four.
445
- */
446
- exports.MOVED_TO_OVERRIDES = [
447
- ...[
448
- "untested-skill",
449
- "untested-subagent",
450
- "untested-hook",
451
- "untested-output-style",
452
- ].map((owner, _i, all) => ({ owner, rules: all })),
453
- { owner: "orphans", rules: ["orphan-docs"] },
454
- ];
455
- /** A plain JSON object, narrowed without a cast. */
456
- function isRecord(v) {
457
- return typeof v === "object" && v !== null && !Array.isArray(v);
458
- }
459
- /** The `exclude` an old config wrote under `owner`, as a glob list, if any. */
460
- function movedExclude(raw, owner) {
461
- if (!isRecord(raw))
462
- return null;
463
- const value = isRecord(raw.rules) ? raw.rules[owner] : undefined;
464
- const tuple = Array.isArray(value) ? value : [];
465
- const holder = owner === "orphans" ? raw.orphans : tuple[1];
466
- if (!isRecord(holder) || holder.exclude === undefined)
467
- return null;
468
- const globs = [holder.exclude].flat();
469
- return globs.filter((g) => typeof g === "string");
470
- }
471
- /**
472
- * The message an old config with a per-rule `exclude` gets — the user's OWN
473
- * globs, written as the `overrides` entry that does what the option did.
474
- *
475
- * Read BEFORE the schema, like {@link REPLACED_KEYS}: the reader's config used
476
- * to work, so "unknown key exclude" would be true and useless.
477
- */
478
- function movedToOverridesMessages(raw) {
479
- return exports.MOVED_TO_OVERRIDES.flatMap(({ owner, rules }) => {
480
- const globs = movedExclude(raw, owner);
481
- if (globs === null)
482
- return [];
483
- const files = globs.map((g) => JSON.stringify(g)).join(", ");
484
- const off = rules.map((r) => `"${r}": "off"`).join(", ");
485
- return [
486
- `.vigilesrc.json: "exclude" inside "${owner}" moved to "overrides" — skipping paths is not a rule option any more; an override turns the rule off for them.\n` +
487
- ` Write: "overrides": [{ "files": [${files}], "rules": { ${off} } }]\n` +
488
- ` and remove "exclude" from "${owner}". Paths top-level "exclude" removes are not read at all; an override only changes what a rule reports.`,
489
- ];
490
- });
491
- }
492
- /** Rules whose findings another rule now reports, and what changed. */
493
- exports.FOLDED_RULES = [
494
- {
495
- rule: "prefer-compiled-hooks",
496
- into: "hand-written-hook",
497
- what: "every hook line vigiles did not write is now one hand-written-hook finding that names it",
498
- },
499
- ];
500
- /**
501
- * The message a config naming a folded rule gets — in `rules` or in an
502
- * `overrides` entry. Read BEFORE the schema, like {@link REPLACED_KEYS}: the
503
- * reader's config used to work, so "unknown key" would be true and useless.
504
- */
505
- function foldedRuleMessages(raw) {
506
- if (!isRecord(raw))
507
- return [];
508
- const overrides = Array.isArray(raw.overrides)
509
- ? raw.overrides
510
- : [];
511
- const ruleBlocks = [
512
- raw.rules,
513
- ...overrides.map((o) => (isRecord(o) ? o.rules : undefined)),
514
- ];
515
- return exports.FOLDED_RULES.filter(({ rule }) => ruleBlocks.some((b) => isRecord(b) && rule in b)).map(({ rule, into, what }) => `.vigilesrc.json: rule "${rule}" was folded into "${into}": ${what}.\n` +
516
- ` Remove "${rule}"; set "${into}" to change how those findings report.`);
517
- }
518
358
  // ---------------------------------------------------------------------------
519
359
  // Messages — the half a schema library does NOT give you
520
360
  // ---------------------------------------------------------------------------
@@ -528,8 +368,8 @@ function foldedRuleMessages(raw) {
528
368
  * by `resolveDeclaredHarnesses` against the adapter registry, which core may not
529
369
  * import).
530
370
  */
531
- function knownKeysAt(path) {
532
- let node = exports.vigilesConfigSchema;
371
+ function knownKeysAt(schema, path) {
372
+ let node = schema;
533
373
  for (const seg of path) {
534
374
  node = childAt(node, seg);
535
375
  if (node === undefined)
@@ -620,10 +460,10 @@ function pathLabel(path) {
620
460
  * the key accepts, and an unknown key carries the candidate list plus a
621
461
  * distance-bounded "did you mean".
622
462
  */
623
- function formatConfigIssues(issues) {
463
+ function formatConfigIssues(schema, issues) {
624
464
  return issues.flatMap((issue) => {
625
465
  if (issue.code === "unrecognized_keys")
626
- return unknownKeyLines(issue);
466
+ return unknownKeyLines(schema, issue);
627
467
  if (issue.code === "invalid_union")
628
468
  return unionLines(issue);
629
469
  return [
@@ -632,8 +472,8 @@ function formatConfigIssues(issues) {
632
472
  });
633
473
  }
634
474
  /** One line per unrecognized key, with a near-miss or the candidate list. */
635
- function unknownKeyLines(issue) {
636
- const known = knownKeysAt(issue.path ?? []);
475
+ function unknownKeyLines(schema, issue) {
476
+ const known = knownKeysAt(schema, issue.path ?? []);
637
477
  const where = pathLabel(issue.path ?? []);
638
478
  return (issue.keys ?? []).map((key) => {
639
479
  // A near-miss REPLACES the candidate list rather than joining it. The rules
@@ -35,7 +35,7 @@ import type { InstructionBudget } from "./instruction-weight.js";
35
35
  * membership test over key names, which are facts about a FILE FORMAT and carry
36
36
  * no harness in them.
37
37
  */
38
- export declare const RENDERABLE_SKILL_FRONTMATTER_KEYS: readonly ["name", "description", "disable-model-invocation", "context", "argument-hint", "allowed-tools", "disallowed-tools"];
38
+ export declare const RENDERABLE_SKILL_FRONTMATTER_KEYS: readonly ["name", "description", "disable-model-invocation", "context", "agent", "model", "argument-hint", "allowed-tools", "disallowed-tools"];
39
39
  /**
40
40
  * The instruction filenames vigiles recognizes when NO dialect is injected, in
41
41
  * precedence order — `[0]` is what a spec compiles into when it names no target.
@@ -20,6 +20,8 @@ exports.RENDERABLE_SKILL_FRONTMATTER_KEYS = [
20
20
  "description",
21
21
  "disable-model-invocation",
22
22
  "context",
23
+ "agent",
24
+ "model",
23
25
  "argument-hint",
24
26
  "allowed-tools",
25
27
  "disallowed-tools",