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
|
@@ -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
|
|
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
|
package/dist/core/presets.d.ts
CHANGED
|
@@ -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
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
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
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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
|
-
*
|
|
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 {
|
|
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
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
*
|
|
31
|
-
*
|
|
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
|
|
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
|
package/dist/core/presets.js
CHANGED
|
@@ -1,58 +1,32 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.
|
|
4
|
-
exports.
|
|
5
|
-
exports.
|
|
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
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
"
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
/**
|
|
55
|
-
|
|
56
|
-
|
|
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
|
|
1
|
+
/** How a bundled-resource reference was found in the body. */
|
|
2
2
|
export type SkillResourceKind = "link" | "path";
|
|
3
|
-
/**
|
|
4
|
-
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
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
|
|
33
|
-
*
|
|
34
|
-
*
|
|
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
|
-
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
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
|
|
61
|
-
*
|
|
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
|
|
132
|
+
export declare function repoRootOnlyAdvice(f: SkillResourceFinding<"repo-root-only">): string;
|
|
133
|
+
export {};
|
|
64
134
|
//# sourceMappingURL=skill-resources.d.ts.map
|