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,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.DEFAULT_RULES = void 0;
3
+ exports.configDefaults = configDefaults;
4
4
  exports.findInstructionFiles = findInstructionFiles;
5
5
  exports.loadConfig = loadConfig;
6
6
  exports.parseRules = parseRules;
@@ -33,6 +33,7 @@ const enforce_marker_js_1 = require("./enforce-marker.js");
33
33
  const integrity_js_1 = require("./integrity.js");
34
34
  const instruction_remedies_js_1 = require("./instruction-remedies.js");
35
35
  const config_schema_js_1 = require("./config-schema.js");
36
+ const config_migrations_js_1 = require("./config-migrations.js");
36
37
  // ---------------------------------------------------------------------------
37
38
  // Constants & regex
38
39
  // ---------------------------------------------------------------------------
@@ -54,24 +55,19 @@ const CHECKBOX_RE = /^- \[([ xX])\]\s+(.+)$/;
54
55
  const INSTRUCTION_FILES = dialect_js_1.DEFAULT_INSTRUCTION_TARGETS;
55
56
  // The default instruction file to validate when no config names one.
56
57
  const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
58
+ /** The default rule markers — read from the schema, like every other default. */
59
+ const DEFAULT_MARKERS = config_schema_js_1.DEFAULT_RULE_MARKERS;
57
60
  /**
58
- * The shipped default severity of every rule — DERIVED from the schema, never
59
- * listed twice.
60
- *
61
- * It used to be the literal beside the type, which is exactly the pair that
62
- * drifts: `rule-meta.test.ts` already cross-checks each rule's documented
63
- * `defaultSeverity` against this object, and it could only ever catch a doc that
64
- * disagreed with the literal, never a literal that disagreed with what parsing
65
- * actually produced. Reading it out of the parser closes that gap: this IS what
66
- * a `{}` config loads as.
61
+ * The defaults with `presets` applied — an empty file extended on the CLI.
62
+ * There is no rule-set-free default here: what every rule defaults to is
63
+ * declared by the rule, and the set arrives as `set` from the root.
67
64
  */
68
- exports.DEFAULT_RULES = defaultConfig()
69
- .rules;
70
- /** The default rule markers — read from the schema, like every other default. */
71
- const DEFAULT_MARKERS = defaultConfig().ruleMarkers;
72
- /** A freshly parsed empty config — the defaults, straight from the schema. */
73
- function defaultConfig() {
74
- return config_schema_js_1.vigilesConfigSchema.parse({});
65
+ function configDefaults(set, presets) {
66
+ const parsed = set.parse({}, presets);
67
+ if (parsed.success)
68
+ return parsed.data;
69
+ /* v8 ignore next -- `{}` with known presets always parses */
70
+ throw new config_schema_js_1.VigilesConfigError((0, config_schema_js_1.formatConfigIssues)(set.schema, parsed.error.issues).join("\n"));
75
71
  }
76
72
  // ---------------------------------------------------------------------------
77
73
  // Instruction file discovery
@@ -115,7 +111,10 @@ function findInstructionFiles(cwd, configFiles) {
115
111
  * does not execute until the function is called. A rail that never reads a
116
112
  * config never pays for the validator.
117
113
  */
118
- function loadConfig(searchFrom, { onInvalid = "throw" } = {}) {
114
+ function loadConfig(
115
+ /** The config for the rule set the root hands in (`configFor`). */
116
+ set, searchFrom, { onInvalid = "throw", presets, } = {}) {
117
+ const fallback = () => configDefaults(set, presets);
119
118
  let raw;
120
119
  try {
121
120
  const explorer = (0, cosmiconfig_1.cosmiconfigSync)("vigiles", {
@@ -127,21 +126,21 @@ function loadConfig(searchFrom, { onInvalid = "throw" } = {}) {
127
126
  catch {
128
127
  // No file, unreadable file, malformed JSON — the defaults, as always. A
129
128
  // config we CAN read and refuse is a different thing and is handled below.
130
- return defaultConfig();
129
+ return fallback();
131
130
  }
132
131
  if (raw === undefined || raw === null)
133
- return defaultConfig();
132
+ return fallback();
134
133
  // The replaced keys get their own message BEFORE the schema's, because the
135
134
  // reader is someone whose config used to work: `.strict()` would tell them
136
135
  // "unknown key harness", which is true and useless. See REPLACED_KEYS.
137
136
  // The per-rule `exclude` options moved to `overrides` the same way, and a
138
137
  // rule folded into another names the one that reports it now.
139
138
  const problems = [
140
- ...(0, config_schema_js_1.movedToOverridesMessages)(raw),
141
- ...(0, config_schema_js_1.foldedRuleMessages)(raw),
139
+ ...(0, config_migrations_js_1.movedToOverridesMessages)(raw),
140
+ ...(0, config_migrations_js_1.foldedRuleMessages)(raw),
142
141
  ];
143
142
  if (typeof raw === "object" && !Array.isArray(raw)) {
144
- const present = config_schema_js_1.REPLACED_KEYS.filter((k) => k.key in raw);
143
+ const present = config_migrations_js_1.REPLACED_KEYS.filter((k) => k.key in raw);
145
144
  if (present.length > 0) {
146
145
  // The names the user's OWN removed `harness` key held, so the worked
147
146
  // example in the message shows their migration rather than a fixed pair
@@ -149,21 +148,21 @@ function loadConfig(searchFrom, { onInvalid = "throw" } = {}) {
149
148
  // a config we have already refused, so the message must survive garbage.
150
149
  const legacy = raw.harness;
151
150
  const names = (Array.isArray(legacy) ? legacy : legacy === undefined ? [] : [legacy]).filter((n) => typeof n === "string" && n.length > 0);
152
- problems.push((0, config_schema_js_1.replacedKeyMessage)(present, names));
151
+ problems.push((0, config_migrations_js_1.replacedKeyMessage)(present, names));
153
152
  }
154
153
  }
155
154
  if (problems.length === 0) {
156
- const parsed = (0, config_schema_js_1.parseVigilesConfig)(raw);
155
+ const parsed = set.parse(raw, presets);
157
156
  if (parsed.success)
158
157
  return parsed.data;
159
- problems.push(...(0, config_schema_js_1.formatConfigIssues)(parsed.error.issues));
158
+ problems.push(...(0, config_schema_js_1.formatConfigIssues)(set.schema, parsed.error.issues));
160
159
  }
161
160
  if (onInvalid === "throw")
162
161
  throw new config_schema_js_1.VigilesConfigError(problems.join("\n"));
163
162
  for (const line of problems)
164
163
  console.warn(`⚠ ${line}`);
165
164
  console.warn("⚠ Using default configuration.");
166
- return defaultConfig();
165
+ return fallback();
167
166
  }
168
167
  // ---------------------------------------------------------------------------
169
168
  // Parsing
@@ -257,7 +256,9 @@ function handWrittenFinding(content, filePath) {
257
256
  };
258
257
  }
259
258
  function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect } = {}) {
260
- const activeRules = rulesConfig ?? exports.DEFAULT_RULES;
259
+ // No rules handed in → every rule off: the defaults belong to the rule set,
260
+ // which only the root holds.
261
+ const activeRules = rulesConfig ?? {};
261
262
  const parsedRules = parseRules(content, { ruleMarkers });
262
263
  const enforced = countEnforcement(parsedRules, "enforced");
263
264
  const guidanceOnly = countEnforcement(parsedRules, "guidance");
@@ -7,8 +7,8 @@
7
7
  * that must obey it — "always pass `curl -g`, or bracketed params glob and the
8
8
  * request fails SILENTLY"; "every `psql` needs `--single-transaction`". The rule
9
9
  * and its violation live **in the same file**, three paragraphs apart, and
10
- * nothing compares them. It is `prose isn't policy` turned on the author's own
11
- * document, and it is the smallest possible instance of it.
10
+ * nothing compares them. It is a rule nobody checks, turned on the author's own
11
+ * document, and it is the smallest possible instance of one.
12
12
  *
13
13
  * vigiles cannot INFER such a rule — no tool reads "always use -g" and derives
14
14
  * which flag is mandatory. What was missing is not cleverness but a cheap way to
@@ -29,6 +29,7 @@
29
29
  import { type PluginScore } from "./score-core.js";
30
30
  import { type ExplanationConfidence } from "./score-explainer.js";
31
31
  import type { ScanReport } from "./scan.js";
32
+ import type { GradedView } from "./core/apply-rules.js";
32
33
  /**
33
34
  * The action a recommendation asks for. The deterministic detectors yield two:
34
35
  * `"differentiate"` (a description-overlap PAIR — make the two distinct so the
@@ -68,7 +69,7 @@ export interface OptimizeReport {
68
69
  * score + a typed recommendation per deterministic finding (`likely` dead-ends
69
70
  * before `possible` proxies, via explainScore's own ordering). Pure over the report.
70
71
  */
71
- export declare function optimize(report: ScanReport): OptimizeReport;
72
+ export declare function optimize(report: GradedView<ScanReport>): OptimizeReport;
72
73
  /**
73
74
  * Just the deterministic fix list (no score header) — folded into the default
74
75
  * `vigiles audit` report so every finding carries its fix inline (replaces the
@@ -1,25 +1,29 @@
1
1
  import type { RuleSeverity, RulesConfig } from "./core/types.js";
2
- /** A rule name — a key of the rule set. */
3
- export type RuleName = keyof RulesConfig;
4
2
  /** One `overrides` entry, as parsed: globs and the severities they set. */
5
- export interface RuleOverride {
3
+ export interface RuleOverride<Id extends string = string> {
6
4
  readonly files: readonly string[];
7
- readonly rules: Readonly<Partial<Record<RuleName, RuleSeverity>>>;
5
+ readonly rules: {
6
+ readonly [K in Id]?: RuleSeverity;
7
+ };
8
8
  }
9
- /** The severity of every rule, for any path. */
10
- export interface RuleResolver {
9
+ /**
10
+ * The severity of every rule, for any path. Generic over the rule ids: the
11
+ * root instantiates it over its rule set (a typo'd id is a tsc error there),
12
+ * and generic code takes it over `string` and never spells an id.
13
+ */
14
+ export interface RuleResolver<Id extends string = string> {
11
15
  /**
12
16
  * The severity `rule` has for a finding at `path` (repository-relative).
13
17
  * `undefined` — a finding with no path — gets the severity from `rules`.
14
18
  */
15
- severityAt(rule: RuleName, path: string | undefined): RuleSeverity;
19
+ severityAt(rule: Id, path: string | undefined): RuleSeverity;
16
20
  /**
17
21
  * Whether `rule` can fire anywhere: on in `rules`, or turned on by some
18
22
  * override. A check that would skip its whole scan when its rule is off asks
19
23
  * this, so an override that turns a rule ON for one folder is not dropped.
20
24
  */
21
- mayFire(rule: RuleName): boolean;
25
+ mayFire(rule: Id): boolean;
22
26
  }
23
27
  /** Build the resolver once per run, from the parsed `rules` and `overrides`. */
24
- export declare function ruleResolver(rules: Readonly<RulesConfig>, overrides?: readonly RuleOverride[]): RuleResolver;
28
+ export declare function ruleResolver<Id extends string = string>(rules: Readonly<RulesConfig<Id>>, overrides?: readonly RuleOverride<Id>[]): RuleResolver<Id>;
25
29
  //# sourceMappingURL=overrides.d.ts.map
package/dist/overrides.js CHANGED
@@ -10,7 +10,7 @@ exports.ruleResolver = ruleResolver;
10
10
  * PRECEDENCE is ESLint's cascade: the `extends` preset, then `rules`, then each
11
11
  * override whose `files` cover the finding's path, in order — a later override
12
12
  * wins over an earlier one. `extends` < `rules` is settled when the config is
13
- * parsed (`parseVigilesConfig`); this module adds the per-path layer on top.
13
+ * parsed (`ConfigSet.parse`, `core/config-schema.ts`); this module adds the per-path layer on top.
14
14
  *
15
15
  * WHAT AN OVERRIDE SETS: a severity. A rule's options (`["error", { … }]`) live
16
16
  * in `rules`, once; an override that changes `compile-budget` to `warn` keeps
@@ -0,0 +1,3 @@
1
+ declare const _default: import("../core/spec.js").ClaudeSpec;
2
+ export default _default;
3
+ //# sourceMappingURL=CLAUDE.md.spec.d.ts.map
@@ -0,0 +1,22 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ /**
4
+ * Directory-scoped guidance for working in `src/rules/` — the rule layer.
5
+ *
6
+ * The full project rule set is the ROOT `CLAUDE.md` (compiled from
7
+ * `CLAUDE.md.spec.ts`). This nested spec adds what belongs next to the rule
8
+ * modules: what a rule file declares, what it may import, how to add one.
9
+ * Source of truth; `src/rules/CLAUDE.md` is a compiled build artifact
10
+ * (`vigiles compile`).
11
+ */
12
+ const spec_js_1 = require("../core/spec.js");
13
+ exports.default = (0, spec_js_1.instructionFile)({
14
+ sections: {
15
+ scope: `Working in \`src/rules/\`? This is the RULE layer — vigiles' product lint rules as data, outside core like the adapters. A rule is a module \`<id>.ts\` implementing core's \`RuleSpec\` (\`src/core/rule.ts\`); \`groups.ts\` is the group record; \`index.ts\` is the set, which still holds the not-yet-migrated rules as rows (#390). Only a composition root (\`src/cli-main.ts\`, the browser demo's \`runAudit\`, the JSON-Schema build) imports \`index.ts\` and hands the set to core.`,
16
+ },
17
+ rules: {
18
+ "what-a-rule-declares": (0, spec_js_1.guidance)("A rule module declares its POLICY with `defineRule`: `id`, `group` (a key of `RULE_GROUPS`), decidability `bucket`, `surface`, `defaultSeverity`, `cure`, `summary`, the core `detector` it reports, an `options` Zod schema if it takes options, and `findings(scan)` — how each finding reads, off core's `ScanInput`. The detector itself stays in `src/core/`. A rule imports `../core/` only: never another rule, `index.ts`, `groups.ts`, app code or an adapter (`boundaries` refuses each). A rule spells only its own id, and its colocated `<id>.test.ts` too; any other file takes the id from the module (`local/no-rule-ids`)."),
19
+ "adding-a-rule": (0, spec_js_1.guidance)("Adding a rule changes three places and no generic file: the module `<id>.ts` (with `<id>.test.ts` beside it), one entry in `RULES` in `index.ts`, and `docs/rules/<id>.md` plus its row in `docs/verifying-instruction-files.md`. Group membership is the rule's `group` field; presets, `init`'s writes and the audit blocks derive from it. A rule module in a GRADED group needs its findings wired to the scorers first (#390) — `index.test.ts` fails until then."),
20
+ },
21
+ });
22
+ //# sourceMappingURL=CLAUDE.md.spec.js.map
@@ -0,0 +1,32 @@
1
+ export declare const RULE_GROUPS: {
2
+ readonly structural: {
3
+ readonly graded: true;
4
+ readonly label: "Structural";
5
+ readonly preset: {
6
+ readonly name: "vigiles:recommended";
7
+ readonly severity: "error";
8
+ };
9
+ readonly init: "extends";
10
+ };
11
+ readonly workflow: {
12
+ readonly graded: true;
13
+ readonly label: "Workflow";
14
+ readonly init: "--strict";
15
+ };
16
+ readonly nudge: {
17
+ readonly graded: true;
18
+ readonly label: "Nudge";
19
+ };
20
+ readonly experimental: {
21
+ readonly graded: false;
22
+ readonly label: "Experimental — not graded";
23
+ readonly blurb: "Checks vigiles ships but has not measured as reliable enough to grade you on. They never move the score.";
24
+ readonly preset: {
25
+ readonly name: "vigiles:experimental";
26
+ readonly severity: "warn";
27
+ };
28
+ };
29
+ };
30
+ /** A group's name — a key of {@link RULE_GROUPS}. */
31
+ export type RuleGroupName = keyof typeof RULE_GROUPS;
32
+ //# sourceMappingURL=groups.d.ts.map
@@ -0,0 +1,27 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.RULE_GROUPS = void 0;
4
+ exports.RULE_GROUPS = {
5
+ structural: {
6
+ graded: true,
7
+ label: "Structural",
8
+ preset: { name: "vigiles:recommended", severity: "error" },
9
+ init: "extends",
10
+ },
11
+ workflow: {
12
+ graded: true,
13
+ label: "Workflow",
14
+ init: "--strict",
15
+ },
16
+ nudge: {
17
+ graded: true,
18
+ label: "Nudge",
19
+ },
20
+ experimental: {
21
+ graded: false,
22
+ label: "Experimental — not graded",
23
+ blurb: "Checks vigiles ships but has not measured as reliable enough to grade you on. They never move the score.",
24
+ preset: { name: "vigiles:experimental", severity: "warn" },
25
+ },
26
+ };
27
+ //# sourceMappingURL=groups.js.map