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
@@ -8,7 +8,7 @@
8
8
  * cohesive, type-enforced unit: the concrete `LINTERS` registry (in
9
9
  * `linters.ts`) is a `Record<BuiltinLinter, LinterAdapter>`, so a missing linter
10
10
  * or capability is a tsc error, and `linter-contract.test.ts` covers the
11
- * docs/prose parity a type can't see. Mirrors the `HarnessAdapter`/`rule-meta`
11
+ * docs/prose parity a type can't see. Mirrors the `HarnessAdapter`/rule-set
12
12
  * patterns already used in the repo. See `research/linter-adapter-architecture.md`.
13
13
  *
14
14
  * This module is a TYPE-ONLY LEAF: it imports only a type from `spec.ts` (the
@@ -1,56 +1,41 @@
1
1
  /**
2
2
  * Named rule PRESETS a `.vigilesrc.json` can `extends` — the ESLint
3
- * `recommended` model, stored as data.
3
+ * `recommended` model, stored as data on the rule GROUPS.
4
4
  *
5
5
  * 🔴 WHY A PRESET READ AT LOAD TIME, NOT RULE LINES WRITTEN AT SETUP TIME. Every
6
- * rule's built-in default stays `warn` (`config-schema.ts`); the structural rules
7
- * gate only because `init` turns them up. It used to do that by WRITING nine
8
- * `"<rule>": "error"` lines into the new repo's config — a snapshot of the group
9
- * on the day `init` ran. A repo adopted before a rule joined the group never got
10
- * it from an upgrade, and re-running `init` to fetch it rewrote far more than
11
- * the rule (#338). `"extends": "vigiles:recommended"` is resolved by the loader
12
- * on every run, so the repo follows the group as the installed vigiles ships it,
13
- * and an explicit `rules` entry still overrides it.
6
+ * rule keeps its own built-in default; a group gates only because its preset
7
+ * turns it up. `init` used to do that by WRITING nine `"<rule>": "error"` lines
8
+ * into the new repo's config — a snapshot of the group on the day `init` ran. A
9
+ * repo adopted before a rule joined the group never got it from an upgrade, and
10
+ * re-running `init` to fetch it rewrote far more than the rule (#338). An
11
+ * `extends` preset is resolved by the loader on every run, so the repo follows
12
+ * the group as the installed vigiles ships it, and an explicit `rules` entry
13
+ * still overrides it.
14
14
  *
15
- * ⚠️ ADDING A RULE HERE IS A BREAKING CHANGE (a `!` commit, a semver major): it
16
- * can turn a consumer's CI red with no edit on their side. Removing one is not.
17
- * ESLint treats `eslint:recommended` the same way.
15
+ * WHERE THE PRESETS COME FROM — not from here. A preset is a field of a group
16
+ * (`RuleGroupSpec.preset`: its name and the severity it sets), and a rule's
17
+ * membership is its own `group` field; both live in the outer rule layer
18
+ * (`src/rules/`) and arrive as parameters. So this file names no rule and no
19
+ * group, and moving a rule between groups is an edit to that rule alone.
18
20
  *
19
- * Harness-agnostic data: rule names only, no adapter fact.
21
+ * ⚠️ RAISING A RULE UNDER A PRESET THAT SETS `error` IS A BREAKING CHANGE (a `!`
22
+ * commit, a semver major): it can turn a consumer's CI red with no edit on their
23
+ * side. A preset that sets `warn` can grow freely. ESLint treats
24
+ * `eslint:recommended` the same way.
20
25
  */
21
- import type { RulesConfig } from "./types.js";
26
+ import type { RuleGroups, RuleSpec } from "./rule.js";
27
+ /** The namespace every preset name carries; the CLI flag may omit it. */
28
+ export declare const PRESET_PREFIX = "vigiles:";
22
29
  /**
23
- * The rules `vigiles:recommended` raises to `error` — the FP-safe structural
24
- * group: each one fires only on a genuine defect (a never-available or typo'd
25
- * tool, a subagent missing `name`/`description`, a typo'd hook event, a file a
26
- * compiled hook needs gone missing, a broken MCP reference, two skills that
27
- * collide in the selector), so a well-formed harness stays green.
28
- *
29
- * `hand-written-hook` is NOT here: its only cure is a compiled hook, written
30
- * with the `experimental_define*` API, and a preset must not push users onto an
31
- * experimental API. It joins when compiled hooks leave experimental (the exit
32
- * criteria in docs/experimental.md, "When the prefix comes off").
33
- *
34
- * Also gates `require-instructions-spec`: a hand-written CLAUDE.md / AGENTS.md
35
- * is a file whose references nothing re-verifies on change. It is the one rule
36
- * here a clean repo can fail before any work is done, so its finding names all
37
- * three ways out in order — adopt it (`adopt-spec` / `init --target`), exclude
38
- * a folder that is not yours, or turn it off for folders that stay hand-written
39
- * (`overrides`) — and `init` adopts every instruction file it finds, so a repo
40
- * set up by `init` starts green.
41
- *
42
- * Deliberately EXCLUDES the `untested-*` workflow rules: they stay an explicit
43
- * opt-in (`init --strict`).
30
+ * The preset names a raw `extends` value lists, in order: a string is one, an
31
+ * array is several. Anything else — or any entry that is not in `known` —
32
+ * yields `null`, so the caller leaves it for the schema to refuse with its own
33
+ * message.
34
+ */
35
+ export declare function extendedPresets(known: readonly string[], value: unknown): readonly string[] | null;
36
+ /**
37
+ * What each preset sets, as the config would spell it: every rule whose group
38
+ * carries the preset, at the preset's severity.
44
39
  */
45
- export declare const RECOMMENDED_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap", "compile-budget", "require-instructions-spec"];
46
- /** The preset names `extends` accepts. One today; the tuple is the enum. */
47
- export declare const PRESET_NAMES: readonly ["vigiles:recommended"];
48
- /** A preset name `extends` accepts. */
49
- export type PresetName = (typeof PRESET_NAMES)[number];
50
- /** The preset `init` writes. */
51
- export declare const RECOMMENDED_PRESET: PresetName;
52
- /** Whether a raw value names a preset. */
53
- export declare function isPresetName(value: unknown): value is PresetName;
54
- /** The rule severities a preset sets, in the config's raw spelling. */
55
- export declare function presetRules(name: PresetName): Readonly<Partial<Record<keyof RulesConfig, "error">>>;
40
+ export declare function presetRulesOf(rules: readonly RuleSpec[], groups: RuleGroups): (name: string) => Readonly<Record<string, "error" | "warn">>;
56
41
  //# sourceMappingURL=presets.d.ts.map
@@ -1,58 +1,32 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.RECOMMENDED_PRESET = exports.PRESET_NAMES = exports.RECOMMENDED_RULES = void 0;
4
- exports.isPresetName = isPresetName;
5
- exports.presetRules = presetRules;
3
+ exports.PRESET_PREFIX = void 0;
4
+ exports.extendedPresets = extendedPresets;
5
+ exports.presetRulesOf = presetRulesOf;
6
+ /** The namespace every preset name carries; the CLI flag may omit it. */
7
+ exports.PRESET_PREFIX = "vigiles:";
6
8
  /**
7
- * The rules `vigiles:recommended` raises to `error` — the FP-safe structural
8
- * group: each one fires only on a genuine defect (a never-available or typo'd
9
- * tool, a subagent missing `name`/`description`, a typo'd hook event, a file a
10
- * compiled hook needs gone missing, a broken MCP reference, two skills that
11
- * collide in the selector), so a well-formed harness stays green.
12
- *
13
- * `hand-written-hook` is NOT here: its only cure is a compiled hook, written
14
- * with the `experimental_define*` API, and a preset must not push users onto an
15
- * experimental API. It joins when compiled hooks leave experimental (the exit
16
- * criteria in docs/experimental.md, "When the prefix comes off").
17
- *
18
- * Also gates `require-instructions-spec`: a hand-written CLAUDE.md / AGENTS.md
19
- * is a file whose references nothing re-verifies on change. It is the one rule
20
- * here a clean repo can fail before any work is done, so its finding names all
21
- * three ways out in order — adopt it (`adopt-spec` / `init --target`), exclude
22
- * a folder that is not yours, or turn it off for folders that stay hand-written
23
- * (`overrides`) — and `init` adopts every instruction file it finds, so a repo
24
- * set up by `init` starts green.
25
- *
26
- * Deliberately EXCLUDES the `untested-*` workflow rules: they stay an explicit
27
- * opt-in (`init --strict`).
9
+ * The preset names a raw `extends` value lists, in order: a string is one, an
10
+ * array is several. Anything else — or any entry that is not in `known` —
11
+ * yields `null`, so the caller leaves it for the schema to refuse with its own
12
+ * message.
28
13
  */
29
- exports.RECOMMENDED_RULES = [
30
- "subagent-tool-contract",
31
- "subagent-frontmatter",
32
- "hook-events",
33
- "hook-script-exists",
34
- "mcp-config",
35
- "mcp-tool-resolves",
36
- "mcp-hook-target-resolves",
37
- "disallowed-tools-contract",
38
- "description-overlap",
39
- "compile-budget",
40
- "require-instructions-spec",
41
- ];
42
- /** The preset names `extends` accepts. One today; the tuple is the enum. */
43
- exports.PRESET_NAMES = ["vigiles:recommended"];
44
- /** The preset `init` writes. */
45
- exports.RECOMMENDED_PRESET = "vigiles:recommended";
46
- /** What each preset sets, as the config would spell it. */
47
- const PRESETS = {
48
- "vigiles:recommended": Object.fromEntries(exports.RECOMMENDED_RULES.map((r) => [r, "error"])),
49
- };
50
- /** Whether a raw value names a preset. */
51
- function isPresetName(value) {
52
- return exports.PRESET_NAMES.some((n) => n === value);
14
+ function extendedPresets(known, value) {
15
+ if (value === undefined)
16
+ return [];
17
+ const list = Array.isArray(value) ? value : [value];
18
+ return list.every((n) => typeof n === "string" && known.includes(n))
19
+ ? list
20
+ : null;
53
21
  }
54
- /** The rule severities a preset sets, in the config's raw spelling. */
55
- function presetRules(name) {
56
- return PRESETS[name];
22
+ /**
23
+ * What each preset sets, as the config would spell it: every rule whose group
24
+ * carries the preset, at the preset's severity.
25
+ */
26
+ function presetRulesOf(rules, groups) {
27
+ return (name) => Object.fromEntries(rules.flatMap((r) => {
28
+ const preset = groups[r.group]?.preset;
29
+ return preset?.name === name ? [[r.id, preset.severity]] : [];
30
+ }));
57
31
  }
58
32
  //# sourceMappingURL=presets.js.map
@@ -0,0 +1,213 @@
1
+ /**
2
+ * THE RULE PORT — what a lint rule IS, as core sees it. Core declares it; each
3
+ * rule implements it as a module in `src/rules/<id>.ts`; `src/rules/index.ts`
4
+ * assembles the set; and only a composition root (`src/cli-main.ts`, the
5
+ * browser demo's entry) hands that set to the generic machinery here — the
6
+ * config schema (`configFor`), the presets, `init`'s policy, and (next) the
7
+ * scan's rule findings. The same shape as the harness ports: core never imports
8
+ * a rule, never spells a rule id and never names a group, and three ESLint
9
+ * fences hold that (`local/no-rule-ids`, `local/no-group-names`, the
10
+ * `boundaries` rule layer — see `eslint.config.mjs`).
11
+ *
12
+ * WHY NOT A REGISTRY IN CORE. One was proposed and rejected (2026-10-14): a
13
+ * `core/rule-registry.ts` importing every rule moves the list into one file but
14
+ * leaves core depending on the rules, which is the dependency this port exists
15
+ * to remove (`.claude/skills/hexagonal-architecture/SKILL.md`, mistake 2).
16
+ *
17
+ * WHY THE DETECTOR STAYS IN CORE. A detector (`skillResourceIssues`,
18
+ * `lethalTrifectaIssues`) is a domain capability — a pure function over a
19
+ * parsed artifact, shared by `lint` and `audit` (one-detector-no-drift). What a
20
+ * rule module adds is the POLICY around it: its id, group, default, cure, and
21
+ * how a finding reads.
22
+ *
23
+ * Harness-agnostic data; no adapter fact.
24
+ */
25
+ import type { z } from "zod";
26
+ import type { SkillResourceFinding } from "./skill-resources.js";
27
+ /**
28
+ * The decidability class of a defect — the single fact that sets its ceiling.
29
+ *
30
+ * - `structural-closed` — decidable from the artifact's own content over a CLOSED
31
+ * vocabulary; a TYPE could make it impossible for authors who route through the
32
+ * typed constructor. Ceiling: unrepresentable / won't-typecheck.
33
+ * - `external-decidable` — decidable, but needs the EXTERNAL world (the
34
+ * filesystem, a linter catalog, another file/server). No type can read those,
35
+ * so the ceiling is a hard ERROR at compile-cross-ref or lint — never a type.
36
+ * - `heuristic-behavioral` — undecidable or a fuzzy proxy ("are these too
37
+ * similar?", "does this fire?"). Ceiling: a WARNING or a model-MEASUREMENT. By
38
+ * the math, not by laziness; an `error` here would cry wolf.
39
+ *
40
+ * The bucket is the CEILING; `defaultSeverity` is where the rule sits TODAY. A
41
+ * bucket-A/B rule at `warn` is a CANDIDATE for promotion to `error`; a bucket-C
42
+ * rule at `warn` is permanent.
43
+ */
44
+ export type RuleBucket = "structural-closed" | "external-decidable" | "heuristic-behavioral";
45
+ /** The artifact surface a rule reads (coarse; a rule may span several). */
46
+ export type RuleSurface = "instruction" | "skill" | "subagent" | "hook" | "output-style" | "mcp" | "plugin" | "docs";
47
+ /** Where a rule sits by default — `"off"` is the normalized form of `false`. */
48
+ export type RuleDefaultSeverity = "error" | "warn" | "off";
49
+ /**
50
+ * What fixes a rule's finding: `"edit"` (the user edits their own file), a CLI
51
+ * verb, or a public export. Data, so a test can hold the line that a rule ON by
52
+ * default is never curable only through an `experimental_` export.
53
+ */
54
+ export type RuleCure = "edit" | {
55
+ readonly cli: "compile" | "init";
56
+ } | {
57
+ readonly export: string;
58
+ };
59
+ /**
60
+ * One finding as every surface prints it — `lint`'s line, `audit`'s terminal
61
+ * block, the `AuditReport` JSON and the HTML report all read this one shape, so
62
+ * they cannot drift on what a finding says.
63
+ */
64
+ export interface Finding {
65
+ /**
66
+ * `finding` — what the rule reports (`✗`/`⚠`, counted at the rule's
67
+ * severity); `note` — informational, never counted, so it never fails CI.
68
+ */
69
+ readonly kind: "finding" | "note";
70
+ /** The file the finding is in, relative to the scanned directory. */
71
+ readonly path: string;
72
+ /** 1-based line in that file, when the rule knows it. */
73
+ readonly line?: number;
74
+ /** The surface the finding is about (a skill's name). */
75
+ readonly subject: string;
76
+ /** What is wrong and, for a note, how to cure it — one sentence. */
77
+ readonly message: string;
78
+ }
79
+ /**
80
+ * What a rule module reads off a scan — the part of the loaded harness that
81
+ * migrated rules need, typed HERE so a rule module never imports the app's
82
+ * `ScanReport` (`boundaries` refuses rule → app, type imports included). It
83
+ * grows as rules migrate (vigiles#390), only ever by what the loaded plugin
84
+ * already carries, never by a field named after one rule.
85
+ */
86
+ export interface ScanInput {
87
+ readonly skills: readonly {
88
+ readonly name: string;
89
+ /** Repo-relative path of the SKILL.md. */
90
+ readonly path: string;
91
+ /** Every bundled-resource reference in its body that is not beside it. */
92
+ readonly resourceIssues: readonly SkillResourceFinding[];
93
+ }[];
94
+ }
95
+ /**
96
+ * A lint rule, declared — the ESLint `meta` pattern, one module per rule.
97
+ * Unmigrated rules are rows of this shape in `src/rules/index.ts` (no
98
+ * `findings`); a migrated rule is `src/rules/<id>.ts` and declares how its
99
+ * findings read.
100
+ */
101
+ export interface RuleSpec {
102
+ /** The rule's id: its key in `.vigilesrc.json#rules` and its doc's file name. */
103
+ readonly id: string;
104
+ /**
105
+ * The rule's GROUP — a key of the group record the root hands in
106
+ * (`src/rules/groups.ts`). Membership is this field; every list of a group's
107
+ * rules is derived from it.
108
+ */
109
+ readonly group: string;
110
+ /** The decidability class → the rule's strongest possible ceiling. */
111
+ readonly bucket: RuleBucket;
112
+ /** The artifact surface(s) the rule reads (non-empty). */
113
+ readonly surface: readonly RuleSurface[];
114
+ /** Where the rule sits by default today (≤ the bucket's ceiling). */
115
+ readonly defaultSeverity: RuleDefaultSeverity;
116
+ /** One-line "what it checks" (tracks the docs matrix row). */
117
+ readonly summary: string;
118
+ /** The shared pure detector function (one-detector-no-drift traceability). */
119
+ readonly detector: string;
120
+ /**
121
+ * The upstream construct that makes this SAME defect impossible for authors
122
+ * who route through it — a TYPE (structural-closed) or a COMPILE cross-ref.
123
+ */
124
+ readonly upstreamPrevention?: string;
125
+ /** What fixes a finding. */
126
+ readonly cure: RuleCure;
127
+ /**
128
+ * The schema of the rule's options, when it takes any: the config then
129
+ * accepts `["warn" | "error", options]` beside a bare severity.
130
+ */
131
+ readonly options?: z.ZodType;
132
+ /**
133
+ * A migrated rule's findings, read off the scan (`ScanInput`) and phrased
134
+ * the way every surface prints them. `applyRules` calls it for a rule that is
135
+ * on; `lint` counts what it returns at each finding's own severity.
136
+ */
137
+ readonly findings?: (scan: ScanInput) => readonly Finding[];
138
+ /**
139
+ * For a rule not yet migrated to a module: the scan field its findings sit
140
+ * in, so `applyRules` can blank them when the rule is off. Only a field that
141
+ * is shown and never scored is declared (see `./apply-rules.ts`).
142
+ */
143
+ readonly legacy?: {
144
+ readonly scanField: string;
145
+ };
146
+ }
147
+ /**
148
+ * A rule GROUP — keyed by confidence, so membership says how far a rule may be
149
+ * trusted. The concrete record is outer-layer data (`src/rules/groups.ts`);
150
+ * core reads only these fields.
151
+ */
152
+ export interface RuleGroupSpec {
153
+ /**
154
+ * Whether the group's findings may move the audit score. An ungraded group's
155
+ * findings are shown apart and never summed.
156
+ */
157
+ readonly graded: boolean;
158
+ /** How a report heads the group's block. */
159
+ readonly label: string;
160
+ /** One line under the label, when the label alone does not say enough. */
161
+ readonly blurb?: string;
162
+ /**
163
+ * The preset that turns the group up, and the severity it sets. A preset is
164
+ * a name `.vigilesrc.json#extends` and `--preset=` accept.
165
+ */
166
+ readonly preset?: {
167
+ readonly name: `${string}:${string}`;
168
+ readonly severity: "error" | "warn";
169
+ };
170
+ /**
171
+ * What `vigiles init` does with the group: `"extends"` — writes its preset
172
+ * into `extends` (the group a fresh repo gates on); `"--strict"` — writes its
173
+ * rules at `error` only under that flag. Absent: `init` writes nothing.
174
+ */
175
+ readonly init?: "extends" | "--strict";
176
+ }
177
+ /** A group record, as the root hands it in. */
178
+ export type RuleGroups = Readonly<Record<string, RuleGroupSpec>>;
179
+ /**
180
+ * Declare a rule, keeping its literal types (the id, the options schema) so the
181
+ * set's precise config type can be derived from it.
182
+ */
183
+ export declare function defineRule<const S extends RuleSpec>(spec: S): S;
184
+ /** The ids of a rule set, as a union. */
185
+ export type RuleIdOf<R extends readonly RuleSpec[]> = R[number]["id"];
186
+ /** A rule's shipped default, as the config spells it (`false` for off). */
187
+ export declare function configDefault(rule: RuleSpec): "warn" | "error" | false;
188
+ /** Every rule's shipped default, keyed by id. */
189
+ export declare function defaultSeverities(rules: readonly RuleSpec[]): Readonly<Record<string, "warn" | "error" | false>>;
190
+ /**
191
+ * What `vigiles init` writes, derived from the groups' `init` fields — so
192
+ * `init` follows the group record instead of carrying its own lists.
193
+ */
194
+ export interface InitPolicy {
195
+ /** The preset `init` writes into `extends`. */
196
+ readonly preset: string;
197
+ /** Every preset name, so `init` can read an existing `extends`. */
198
+ readonly presets: readonly string[];
199
+ /**
200
+ * The rules that preset RAISES (its rules whose default is not already the
201
+ * preset's severity) — what `--report-only` writes at `warn` instead.
202
+ */
203
+ readonly presetRules: readonly string[];
204
+ /**
205
+ * The rules `init --strict` writes at `error`: the `--strict` groups' rules
206
+ * that are ON by default. An opt-in rule (off by default, e.g. one that does
207
+ * nothing without its options) stays opt-in.
208
+ */
209
+ readonly strictRules: readonly string[];
210
+ }
211
+ /** {@link InitPolicy} from a rule set and its groups. */
212
+ export declare function initPolicyOf(rules: readonly RuleSpec[], groups: RuleGroups): InitPolicy;
213
+ //# sourceMappingURL=rule.d.ts.map
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.defineRule = defineRule;
4
+ exports.configDefault = configDefault;
5
+ exports.defaultSeverities = defaultSeverities;
6
+ exports.initPolicyOf = initPolicyOf;
7
+ /**
8
+ * Declare a rule, keeping its literal types (the id, the options schema) so the
9
+ * set's precise config type can be derived from it.
10
+ */
11
+ function defineRule(spec) {
12
+ return spec;
13
+ }
14
+ /** A rule's shipped default, as the config spells it (`false` for off). */
15
+ function configDefault(rule) {
16
+ return rule.defaultSeverity === "off" ? false : rule.defaultSeverity;
17
+ }
18
+ /** Every rule's shipped default, keyed by id. */
19
+ function defaultSeverities(rules) {
20
+ return Object.fromEntries(rules.map((r) => [r.id, configDefault(r)]));
21
+ }
22
+ /** {@link InitPolicy} from a rule set and its groups. */
23
+ function initPolicyOf(rules, groups) {
24
+ const extended = Object.values(groups).find((g) => g.init === "extends");
25
+ const inGroup = (init) => rules.filter((r) => groups[r.group]?.init === init);
26
+ return {
27
+ preset: extended?.preset?.name ?? "",
28
+ presets: Object.values(groups).flatMap((g) => g.preset ? [g.preset.name] : []),
29
+ presetRules: inGroup("extends")
30
+ .filter((r) => r.defaultSeverity !== extended?.preset?.severity)
31
+ .map((r) => r.id),
32
+ strictRules: inGroup("--strict")
33
+ .filter((r) => r.defaultSeverity !== "off")
34
+ .map((r) => r.id),
35
+ };
36
+ }
37
+ //# sourceMappingURL=rule.js.map
@@ -1,10 +1,33 @@
1
- /** How a missing bundled-resource reference was found in the body. */
1
+ /** How a bundled-resource reference was found in the body. */
2
2
  export type SkillResourceKind = "link" | "path";
3
- /** A SKILL.md body reference to a local bundled file that doesn't exist on disk. */
4
- export interface SkillResourceFinding {
3
+ /**
4
+ * Why a bundled-resource reference is reported. A ref that resolves under the
5
+ * skill dir (or through a declared shared dir) is not reported at all; one that
6
+ * does not is reported for exactly one of these reasons:
7
+ *
8
+ * - `missing` — the file exists nowhere the detector can see. The agent reads
9
+ * the instruction and gets nothing, wherever the skill runs.
10
+ * - `repo-root-only` — not beside the SKILL.md, but present at `repoRoot` (#382).
11
+ * The agent usually runs from the repository root, so a body that says
12
+ * "run `scripts/check.sh`" works while the skill runs inside its own repo and
13
+ * breaks once the skill is installed anywhere else (a plugin install, a copied
14
+ * skill). Not a miss, and not fine either — a separate fact.
15
+ *
16
+ * Two values rather than a boolean because each one drives a different
17
+ * consequence downstream: only `missing` is scored or gated, and
18
+ * `repo-root-only` is printed as a note. A consumer that reads only one of them
19
+ * says which one in its type (`SkillResourceFinding<"missing">`).
20
+ */
21
+ export type SkillResourceResolution = "missing" | "repo-root-only";
22
+ /** The reference itself, whatever its resolution. */
23
+ interface SkillResourceRef {
5
24
  /** The reference text exactly as written in the body (e.g. `scripts/run.sh`). */
6
25
  readonly ref: string;
7
- /** The path normalized relative to the skill dir, used for resolution. */
26
+ /**
27
+ * The path normalized relative to the skill dir — and, for `repo-root-only`,
28
+ * equally the path relative to the repo root, since both resolve the same
29
+ * relative string.
30
+ */
8
31
  readonly resolved: string;
9
32
  /** Whether the ref came from a markdown link `[..](..)` or an inline/path mention. */
10
33
  readonly kind: SkillResourceKind;
@@ -16,11 +39,35 @@ export interface SkillResourceFinding {
16
39
  */
17
40
  readonly line: number;
18
41
  }
42
+ /**
43
+ * One file reference in a SKILL.md body that is not beside the SKILL.md.
44
+ * `resolution` says why it was reported. For `.claude/skills/deploy/SKILL.md`:
45
+ *
46
+ * ```ts
47
+ * // line 8 says "run `scripts/deploy.sh`"; only <repo>/scripts/deploy.sh exists
48
+ * { ref: "scripts/deploy.sh", resolved: "scripts/deploy.sh", kind: "path",
49
+ * line: 8, resolution: "repo-root-only" }
50
+ * // line 9 says "see `scripts/smoke.sh`"; that file exists nowhere
51
+ * { ref: "scripts/smoke.sh", resolved: "scripts/smoke.sh", kind: "path",
52
+ * line: 9, resolution: "missing" }
53
+ * ```
54
+ *
55
+ * `SkillResourceFinding` on its own is either case: check `resolution` to tell
56
+ * them apart. `SkillResourceFinding<"missing">` is only the first kind, so a
57
+ * list typed with it (the scored one) cannot be handed a note.
58
+ */
59
+ export type SkillResourceFinding<R extends SkillResourceResolution = SkillResourceResolution> = R extends SkillResourceResolution ? SkillResourceRef & {
60
+ readonly resolution: R;
61
+ } : never;
19
62
  export interface SkillResourceOptions {
20
63
  /** REQUIRED, injected existence check (disk: node:fs existsSync). */
21
64
  readonly existsSync: (p: string) => boolean;
22
65
  /**
23
- * Repo root, used only together with `sharedDirs` (below). Off by default.
66
+ * The repository root — the directory the agent usually runs from. A ref that
67
+ * misses under the skill dir but exists here is reported as `repo-root-only`
68
+ * instead of `missing`; a ref under a declared `sharedDirs` entry (below)
69
+ * resolves here outright. Omitted → the detector sees only the skill dir and
70
+ * every miss is `missing`.
24
71
  */
25
72
  readonly repoRoot?: string;
26
73
  /**
@@ -29,10 +76,9 @@ export interface SkillResourceOptions {
29
76
  * libraries keep ONE top-level `scripts/` tree instead of a copy beside every
30
77
  * SKILL.md, so a ref like `scripts/promptfoo/x.py` lives at the repo root. When
31
78
  * a ref's FIRST path segment is a declared shared dir, it may ALSO resolve
32
- * against `repoRoot`. Scoped to declared dirs on PURPOSE: a repo that sets no
33
- * `sharedDirs` is byte-identical to before (skill-dir-only), and even with it a
34
- * ref OUTSIDE a shared dir still can't be masked by a same-named repo-root file.
35
- * The controlled fix for feedback P1-4 (opt-in, never a default behavior change).
79
+ * against `repoRoot`. Scoped to declared dirs on PURPOSE: a ref OUTSIDE a
80
+ * shared dir is never RESOLVED by a same-named repo-root file — at most it is
81
+ * reported as `repo-root-only`, visibly, never dropped (feedback P1-4).
36
82
  */
37
83
  readonly sharedDirs?: readonly string[];
38
84
  /**
@@ -53,12 +99,36 @@ export interface SkillResourceOptions {
53
99
  readonly lineOffset?: number;
54
100
  }
55
101
  /**
56
- * The bundled-resource references in a SKILL.md body that don't resolve on disk
57
- * under `skillDir`. Pure + FP-safe (see the module header). `skillDir` is the
58
- * directory the SKILL.md itself lives in (resources are bundled beside it).
102
+ * Reads a SKILL.md body, finds every file it mentions (`scripts/x.sh`,
103
+ * `[guide](references/guide.md)`), and returns the ones that are NOT in the
104
+ * skill's own folder. Files that are there are not returned at all.
105
+ *
106
+ * ```ts
107
+ * // skillDir = .claude/skills/deploy, repoRoot = the repo
108
+ * skillResourceIssues("Run `scripts/deploy.sh`.\nSee `scripts/smoke.sh`.", skillDir, {
109
+ * existsSync, repoRoot,
110
+ * });
111
+ * // → [{ ref: "scripts/deploy.sh", resolution: "repo-root-only", … },
112
+ * // { ref: "scripts/smoke.sh", resolution: "missing", … }]
113
+ * ```
114
+ *
115
+ * Despite the name, the result holds both kinds: `missing` (a real break) and
116
+ * `repo-root-only` (works here, breaks when installed elsewhere — a note). The
117
+ * split into two lists happens once, in `collectSurfaceFindings`. It only reads
118
+ * the file system through the injected `existsSync`, so it runs on disk and in
119
+ * the browser, and `lint` and `audit` both call it.
120
+ */
121
+ export declare function skillResourceIssues(skillBody: string, skillDir: string, opts: SkillResourceOptions): readonly SkillResourceFinding[];
122
+ /**
123
+ * What a `repo-root-only` finding means and what to do about it — ONE sentence
124
+ * shared by every surface that prints the note (`audit`'s text and HTML report,
125
+ * `lint`'s line and its CI annotation), so they cannot drift apart.
59
126
  *
60
- * The shared detector behind both `vigiles lint` (the `skill-resource-resolves`
61
- * rule) and `vigiles audit` (the read-only report) — one detector, no drift.
127
+ * The cure depends on the path's shape: `sharedDirs` declares a top-level
128
+ * DIRECTORY, so a ref under one (`scripts/check.sh`) can be declared shared,
129
+ * while a bare file at the root (`guide.md`) has no directory to declare and the
130
+ * only cure is to ship it beside the SKILL.md.
62
131
  */
63
- export declare function skillResourceIssues(skillBody: string, skillDir: string, opts: SkillResourceOptions): SkillResourceFinding[];
132
+ export declare function repoRootOnlyAdvice(f: SkillResourceFinding<"repo-root-only">): string;
133
+ export {};
64
134
  //# sourceMappingURL=skill-resources.d.ts.map