vigiles 40.1.0 → 41.1.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/dist/adapter.d.ts +1 -1
- package/dist/adapters/claude-code/skill-listing.d.ts +27 -5
- package/dist/adapters/claude-code/skill-listing.js +29 -1
- package/dist/adapters/codex/skill-listing.d.ts +22 -4
- package/dist/adapters/codex/skill-listing.js +30 -1
- package/dist/cli-main.d.ts +4 -3
- package/dist/cli-main.js +121 -25
- package/dist/context-creep-lint.d.ts +123 -0
- package/dist/context-creep-lint.js +397 -0
- package/dist/core/always-loaded-limits.d.ts +118 -0
- package/dist/core/always-loaded-limits.js +175 -0
- package/dist/core/always-loaded.d.ts +15 -1
- package/dist/core/always-loaded.js +9 -0
- package/dist/core/baseline-store.d.ts +183 -0
- package/dist/core/baseline-store.js +392 -0
- package/dist/core/instruction-weight.d.ts +3 -3
- package/dist/core/instruction-weight.js +3 -3
- package/dist/core/legacy-baseline.d.ts +70 -0
- package/dist/core/legacy-baseline.js +117 -0
- package/dist/core/rule-proof/kits/eslint.d.ts +30 -0
- package/dist/core/rule-proof/kits/eslint.js +130 -0
- package/dist/core/rule-proof/kits/index.d.ts +7 -0
- package/dist/core/rule-proof/kits/index.js +12 -0
- package/dist/core/rule-proof/kits/ruff.d.ts +28 -0
- package/dist/core/rule-proof/kits/ruff.js +178 -0
- package/dist/core/rule-proof/node-install.d.ts +32 -0
- package/dist/core/rule-proof/node-install.js +117 -0
- package/dist/core/rule-proof/pair.d.ts +11 -0
- package/dist/core/rule-proof/pair.js +61 -0
- package/dist/core/rule-proof/port.d.ts +77 -0
- package/dist/core/rule-proof/port.js +3 -0
- package/dist/core/rule-proof/report.d.ts +11 -0
- package/dist/core/rule-proof/report.js +36 -0
- package/dist/core/rule-proof/run.d.ts +58 -0
- package/dist/core/rule-proof/run.js +260 -0
- package/dist/core/rule-proof/types.d.ts +119 -0
- package/dist/core/rule-proof/types.js +13 -0
- package/dist/core/skill-listing.d.ts +24 -0
- package/dist/core/types.d.ts +14 -6
- package/dist/entries/rule-proof.d.ts +18 -0
- package/dist/entries/rule-proof.js +23 -0
- package/dist/host/rule-proof.io.d.ts +4 -0
- package/dist/host/rule-proof.io.js +64 -0
- package/dist/local-files.js +2 -2
- package/dist/rules/index.d.ts +25 -2
- package/dist/rules/index.js +22 -9
- package/dist/scan.js +27 -1
- package/dist/vigilesrc.schema.json +32 -0
- package/hooks/session-start.sh +4 -3
- package/package.json +2 -1
- package/dist/context-creep-ratchet.d.ts +0 -88
- package/dist/context-creep-ratchet.js +0 -270
- package/dist/core/instruction-baseline.d.ts +0 -333
- package/dist/core/instruction-baseline.js +0 -570
package/dist/local-files.js
CHANGED
|
@@ -108,8 +108,8 @@ exports.COMMITTED_PATHS = [
|
|
|
108
108
|
"schema.json", // YAML-LSP frontmatter schema (`vigiles init`)
|
|
109
109
|
"guards.json", // the declared guard set (`core/guards.ts`)
|
|
110
110
|
"action-gates.json", // declared action gates (`action-gate.ts`)
|
|
111
|
-
"
|
|
112
|
-
"instruction-weight.json", //
|
|
111
|
+
"baseline.json", // the accepted sizes rules ratchet against (`core/baseline-store.ts`)
|
|
112
|
+
"instruction-weight.json", // an old always-loaded baseline, read only to migrate it (`core/legacy-baseline.ts`)
|
|
113
113
|
];
|
|
114
114
|
/** The header comment on a `.vigiles/.gitignore` vigiles creates. */
|
|
115
115
|
/** The ignore file vigiles keeps inside `.vigiles/`. One spelling for every reader. */
|
package/dist/rules/index.d.ts
CHANGED
|
@@ -20,6 +20,25 @@ import { z } from "zod";
|
|
|
20
20
|
import { type RulesConfigOf, type VigilesConfigOf } from "../core/config-schema.js";
|
|
21
21
|
import { RULE_GROUPS } from "./groups.js";
|
|
22
22
|
export { RULE_GROUPS };
|
|
23
|
+
/**
|
|
24
|
+
* Options for `context-creep`.
|
|
25
|
+
*
|
|
26
|
+
* `limits` overrides the harness's own limit for a part, in the harness's unit
|
|
27
|
+
* (characters for Claude Code, bytes for Codex): `instructions` (the selected
|
|
28
|
+
* output style counts with them) and `skill-listing`. A part left out keeps
|
|
29
|
+
* the harness's number. Going over a limit is a finding the baseline store can
|
|
30
|
+
* accept; `max` is the opt-in ABSOLUTE ceiling on the scored instructions that
|
|
31
|
+
* no baseline lifts. Each value is a positive integer: `0` would put every
|
|
32
|
+
* repository with an instruction file over, and `"40000"` is a string the
|
|
33
|
+
* author meant as a number.
|
|
34
|
+
*/
|
|
35
|
+
export declare const contextCreepOptions: z.ZodObject<{
|
|
36
|
+
max: z.ZodOptional<z.ZodNumber>;
|
|
37
|
+
limits: z.ZodOptional<z.ZodObject<{
|
|
38
|
+
instructions: z.ZodOptional<z.ZodNumber>;
|
|
39
|
+
"skill-listing": z.ZodOptional<z.ZodNumber>;
|
|
40
|
+
}, z.core.$strict>>;
|
|
41
|
+
}, z.core.$strict>;
|
|
23
42
|
/** Every rule, in the config schema's key order. */
|
|
24
43
|
export declare const RULES: readonly [{
|
|
25
44
|
readonly id: "spec-refs";
|
|
@@ -387,10 +406,14 @@ export declare const RULES: readonly [{
|
|
|
387
406
|
readonly surface: readonly ["instruction", "skill", "output-style"];
|
|
388
407
|
readonly defaultSeverity: "error";
|
|
389
408
|
readonly cure: "edit";
|
|
390
|
-
readonly summary: "What the harness loads at session start (instructions
|
|
391
|
-
readonly detector: "
|
|
409
|
+
readonly summary: "What the harness loads at session start (instructions with the selected output style, the skill listing) is within the harness's own limits, or no larger than the size .vigiles/baseline.json accepted.";
|
|
410
|
+
readonly detector: "checkAlwaysLoadedLimits";
|
|
392
411
|
readonly options: z.ZodObject<{
|
|
393
412
|
max: z.ZodOptional<z.ZodNumber>;
|
|
413
|
+
limits: z.ZodOptional<z.ZodObject<{
|
|
414
|
+
instructions: z.ZodOptional<z.ZodNumber>;
|
|
415
|
+
"skill-listing": z.ZodOptional<z.ZodNumber>;
|
|
416
|
+
}, z.core.$strict>>;
|
|
394
417
|
}, z.core.$strict>;
|
|
395
418
|
}, {
|
|
396
419
|
readonly id: "deprecated-key-files";
|
package/dist/rules/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.RULES = exports.RULE_GROUPS = void 0;
|
|
3
|
+
exports.RULES = exports.contextCreepOptions = exports.RULE_GROUPS = void 0;
|
|
4
4
|
/**
|
|
5
5
|
* THE RULE SET — every lint rule vigiles ships, in one tuple, assembled here in
|
|
6
6
|
* the outer rule layer and handed to core by the composition roots
|
|
@@ -47,14 +47,27 @@ const testCoverageConfig = zod_1.z
|
|
|
47
47
|
})
|
|
48
48
|
.strict();
|
|
49
49
|
/**
|
|
50
|
-
* Options for `context-creep`.
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
50
|
+
* Options for `context-creep`.
|
|
51
|
+
*
|
|
52
|
+
* `limits` overrides the harness's own limit for a part, in the harness's unit
|
|
53
|
+
* (characters for Claude Code, bytes for Codex): `instructions` (the selected
|
|
54
|
+
* output style counts with them) and `skill-listing`. A part left out keeps
|
|
55
|
+
* the harness's number. Going over a limit is a finding the baseline store can
|
|
56
|
+
* accept; `max` is the opt-in ABSOLUTE ceiling on the scored instructions that
|
|
57
|
+
* no baseline lifts. Each value is a positive integer: `0` would put every
|
|
58
|
+
* repository with an instruction file over, and `"40000"` is a string the
|
|
59
|
+
* author meant as a number.
|
|
54
60
|
*/
|
|
55
|
-
|
|
61
|
+
exports.contextCreepOptions = zod_1.z
|
|
56
62
|
.object({
|
|
57
63
|
max: zod_1.z.number().int().positive().optional(),
|
|
64
|
+
limits: zod_1.z
|
|
65
|
+
.object({
|
|
66
|
+
instructions: zod_1.z.number().int().positive().optional(),
|
|
67
|
+
"skill-listing": zod_1.z.number().int().positive().optional(),
|
|
68
|
+
})
|
|
69
|
+
.strict()
|
|
70
|
+
.optional(),
|
|
58
71
|
})
|
|
59
72
|
.strict();
|
|
60
73
|
/**
|
|
@@ -443,9 +456,9 @@ exports.RULES = [
|
|
|
443
456
|
surface: ["instruction", "skill", "output-style"],
|
|
444
457
|
defaultSeverity: "error",
|
|
445
458
|
cure: "edit",
|
|
446
|
-
summary: "What the harness loads at session start (instructions
|
|
447
|
-
detector: "
|
|
448
|
-
options:
|
|
459
|
+
summary: "What the harness loads at session start (instructions with the selected output style, the skill listing) is within the harness's own limits, or no larger than the size .vigiles/baseline.json accepted.",
|
|
460
|
+
detector: "checkAlwaysLoadedLimits",
|
|
461
|
+
options: exports.contextCreepOptions,
|
|
449
462
|
}),
|
|
450
463
|
(0, rule_js_1.defineRule)({
|
|
451
464
|
id: "deprecated-key-files",
|
package/dist/scan.js
CHANGED
|
@@ -77,6 +77,7 @@ const coverage_evidence_js_1 = require("./coverage-evidence.js");
|
|
|
77
77
|
const scan_core_js_1 = require("./scan-core.js");
|
|
78
78
|
const instruction_weight_js_1 = require("./core/instruction-weight.js");
|
|
79
79
|
const always_loaded_js_1 = require("./core/always-loaded.js");
|
|
80
|
+
const always_loaded_limits_js_1 = require("./core/always-loaded-limits.js");
|
|
80
81
|
const event_capability_js_1 = require("./core/event-capability.js");
|
|
81
82
|
const hook_command_js_1 = require("./core/hook-command.js");
|
|
82
83
|
const hook_paths_js_1 = require("./core/hook-paths.js");
|
|
@@ -757,12 +758,37 @@ function alwaysLoadedLines(f) {
|
|
|
757
758
|
` = always loaded: ${g(f.total)} ${f.unit} loaded at session start before any decision (instructions + output style + skill listing)`,
|
|
758
759
|
];
|
|
759
760
|
}
|
|
761
|
+
/**
|
|
762
|
+
* Each limited part against the harness's own limit — the same detector
|
|
763
|
+
* `lint`'s context-creep rule reports (`checkAlwaysLoadedLimits`), so the two
|
|
764
|
+
* never disagree about what is over. A listing over its budget is said as what
|
|
765
|
+
* it does to the session, not what it costs: descriptions past it are dropped,
|
|
766
|
+
* so those skills cannot be picked by what they say they are for.
|
|
767
|
+
*/
|
|
768
|
+
function limitLines(w, loaded) {
|
|
769
|
+
const check = (0, always_loaded_limits_js_1.checkAlwaysLoadedLimits)(w, loaded);
|
|
770
|
+
const g = (n) => n.toLocaleString("en-US");
|
|
771
|
+
const row = check.parts
|
|
772
|
+
.map((p) => `${p.part} ${g(p.size)} of ${g(p.limit)}`)
|
|
773
|
+
.join(" · ");
|
|
774
|
+
return [
|
|
775
|
+
` limits (${check.unit}): ${row}`,
|
|
776
|
+
...check.over.map((p) => p.part === "skill-listing"
|
|
777
|
+
? ` ⚠ the skill listing is over the harness's listing budget by ${g(p.size - p.limit)} ${check.unit}: at session start the harness drops skill descriptions past it, so some skills lose the text they are picked by and may never trigger`
|
|
778
|
+
: ` ⚠ ${(0, always_loaded_limits_js_1.describeOver)(p, check.unit)}`),
|
|
779
|
+
];
|
|
780
|
+
}
|
|
760
781
|
/** What the instruction file costs: its always-loaded weight, then any deprecated `keyFiles` inflating it. */
|
|
761
782
|
function instructionCostLines(r) {
|
|
762
783
|
const weight = r.instructionWeight
|
|
763
784
|
? [
|
|
764
785
|
...instructionWeightLines(r.instructionWeight),
|
|
765
|
-
...(r.alwaysLoaded
|
|
786
|
+
...(r.alwaysLoaded
|
|
787
|
+
? [
|
|
788
|
+
...alwaysLoadedLines(r.alwaysLoaded),
|
|
789
|
+
...limitLines(r.instructionWeight, r.alwaysLoaded),
|
|
790
|
+
]
|
|
791
|
+
: []),
|
|
766
792
|
"",
|
|
767
793
|
]
|
|
768
794
|
: [];
|
|
@@ -1696,6 +1696,22 @@
|
|
|
1696
1696
|
"type": "integer",
|
|
1697
1697
|
"exclusiveMinimum": 0,
|
|
1698
1698
|
"maximum": 9007199254740991
|
|
1699
|
+
},
|
|
1700
|
+
"limits": {
|
|
1701
|
+
"type": "object",
|
|
1702
|
+
"properties": {
|
|
1703
|
+
"instructions": {
|
|
1704
|
+
"type": "integer",
|
|
1705
|
+
"exclusiveMinimum": 0,
|
|
1706
|
+
"maximum": 9007199254740991
|
|
1707
|
+
},
|
|
1708
|
+
"skill-listing": {
|
|
1709
|
+
"type": "integer",
|
|
1710
|
+
"exclusiveMinimum": 0,
|
|
1711
|
+
"maximum": 9007199254740991
|
|
1712
|
+
}
|
|
1713
|
+
},
|
|
1714
|
+
"additionalProperties": false
|
|
1699
1715
|
}
|
|
1700
1716
|
},
|
|
1701
1717
|
"additionalProperties": false
|
|
@@ -1719,6 +1735,22 @@
|
|
|
1719
1735
|
"type": "integer",
|
|
1720
1736
|
"exclusiveMinimum": 0,
|
|
1721
1737
|
"maximum": 9007199254740991
|
|
1738
|
+
},
|
|
1739
|
+
"limits": {
|
|
1740
|
+
"type": "object",
|
|
1741
|
+
"properties": {
|
|
1742
|
+
"instructions": {
|
|
1743
|
+
"type": "integer",
|
|
1744
|
+
"exclusiveMinimum": 0,
|
|
1745
|
+
"maximum": 9007199254740991
|
|
1746
|
+
},
|
|
1747
|
+
"skill-listing": {
|
|
1748
|
+
"type": "integer",
|
|
1749
|
+
"exclusiveMinimum": 0,
|
|
1750
|
+
"maximum": 9007199254740991
|
|
1751
|
+
}
|
|
1752
|
+
},
|
|
1753
|
+
"additionalProperties": false
|
|
1722
1754
|
}
|
|
1723
1755
|
},
|
|
1724
1756
|
"additionalProperties": false
|
package/hooks/session-start.sh
CHANGED
|
@@ -5,9 +5,10 @@
|
|
|
5
5
|
# Uses `vigiles lint --summary` which is designed for this: it
|
|
6
6
|
# silences all per-stage output and prints a single line like
|
|
7
7
|
# vigiles: 3 stale / 2 validation errors / 1 duplicate
|
|
8
|
-
# (or "vigiles: clean") so the injection costs a handful of tokens. While
|
|
9
|
-
#
|
|
10
|
-
#
|
|
8
|
+
# (or "vigiles: clean") so the injection costs a handful of tokens. While the
|
|
9
|
+
# always-loaded context is over a harness limit with no baseline recorded, or
|
|
10
|
+
# an old baseline file still needs migrating, it adds one `vigiles: note — …`
|
|
11
|
+
# line naming the command, so the agent runs it.
|
|
11
12
|
#
|
|
12
13
|
# Hook runs on the `startup` and `compact` matchers — the latter is
|
|
13
14
|
# effectively free on token budget because it fires every time
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vigiles",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "41.1.0",
|
|
4
4
|
"description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude-code",
|
|
@@ -42,6 +42,7 @@
|
|
|
42
42
|
"./spec": "./dist/core/spec.js",
|
|
43
43
|
"./eval": "./dist/eval-surface.js",
|
|
44
44
|
"./linting": "./dist/linting.js",
|
|
45
|
+
"./rule-proof": "./dist/entries/rule-proof.js",
|
|
45
46
|
"./hook": "./dist/hook.js",
|
|
46
47
|
"./claude-code": "./dist/claude-code.js",
|
|
47
48
|
"./codex": "./dist/codex.js",
|
|
@@ -1,88 +0,0 @@
|
|
|
1
|
-
import { type InstructionBaseline, type LegacyBaseline, type ParsedBaseline } from "./core/instruction-baseline.js";
|
|
2
|
-
import type { AlwaysLoadedContext } from "./core/always-loaded.js";
|
|
3
|
-
import type { InstructionWeight } from "./core/instruction-weight.js";
|
|
4
|
-
import type { RuleSeverity } from "./core/types.js";
|
|
5
|
-
/** The file on disk, read once: absent, parsed, or refused. */
|
|
6
|
-
export type BaselineOnDisk = {
|
|
7
|
-
readonly kind: "absent";
|
|
8
|
-
} | ParsedBaseline;
|
|
9
|
-
/**
|
|
10
|
-
* Where the baseline is read from, and whether the pre-rename file is still
|
|
11
|
-
* around. The new file wins; the old one is read only when the new one is
|
|
12
|
-
* absent, so a repo that upgrades keeps its ratchet until it renames the file.
|
|
13
|
-
*/
|
|
14
|
-
export interface BaselineSource {
|
|
15
|
-
/** The path read (repo-relative): the new file, else the old one, else the new path. */
|
|
16
|
-
readonly file: string;
|
|
17
|
-
readonly legacy: LegacyBaseline;
|
|
18
|
-
}
|
|
19
|
-
export declare function baselineSource(root: string): BaselineSource;
|
|
20
|
-
export declare function readInstructionBaseline(root: string): BaselineOnDisk;
|
|
21
|
-
/**
|
|
22
|
-
* One bundle's measurement: where it is, and either nothing to weigh or its
|
|
23
|
-
* weight WITH the always-loaded context around it. One union, not an optional third
|
|
24
|
-
* element: a weight without its always-loaded context used to read as "no parts", so a
|
|
25
|
-
* recorded part was compared as 0 — a shrink nobody made.
|
|
26
|
-
*/
|
|
27
|
-
export type MeasuredBundle = readonly [at: string, weight: null] | readonly [
|
|
28
|
-
at: string,
|
|
29
|
-
weight: InstructionWeight,
|
|
30
|
-
loaded: AlwaysLoadedContext
|
|
31
|
-
];
|
|
32
|
-
/** Write the baseline for every measured bundle; returns what was written. */
|
|
33
|
-
export declare function writeInstructionBaseline(root: string, onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[]): InstructionBaseline;
|
|
34
|
-
/**
|
|
35
|
-
* One line of lint output. `finding` counts toward the exit code; `ok` is the
|
|
36
|
-
* baseline holding; `note` is the opt-in nudge on a repo with no baseline.
|
|
37
|
-
*/
|
|
38
|
-
export interface RatchetLine {
|
|
39
|
-
readonly at: string;
|
|
40
|
-
readonly status: "finding" | "ok" | "note";
|
|
41
|
-
readonly text: string;
|
|
42
|
-
}
|
|
43
|
-
/**
|
|
44
|
-
* Pure: the lines a run prints, given what was measured and what is on disk.
|
|
45
|
-
* `max` is the opt-in absolute ceiling; a bundle over it adds a finding of its
|
|
46
|
-
* own, whatever the baseline says (including when there is none, or it is
|
|
47
|
-
* unreadable).
|
|
48
|
-
*
|
|
49
|
-
* A bundle with no entry is a nudge while the repo has NO baseline file (it has
|
|
50
|
-
* not opted in, and a fresh repo must not fail on day one) — but a FINDING once
|
|
51
|
-
* the file exists: a bundle that appeared after the baseline was recorded is
|
|
52
|
-
* weight nobody signed off on.
|
|
53
|
-
*/
|
|
54
|
-
export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[], max?: number, source?: BaselineSource): readonly RatchetLine[];
|
|
55
|
-
/**
|
|
56
|
-
* The bundles `--update-baseline` must not record: each one over the ceiling,
|
|
57
|
-
* as the refusal text. Empty when there is no ceiling or nothing exceeds it.
|
|
58
|
-
*/
|
|
59
|
-
export declare function updateRefusals(measured: readonly MeasuredBundle[], max: number | undefined): readonly string[];
|
|
60
|
-
/** The options {@link checkContextCreepRatchet} takes. */
|
|
61
|
-
interface RatchetOptions {
|
|
62
|
-
readonly root: string;
|
|
63
|
-
readonly severity: RuleSeverity;
|
|
64
|
-
/** The opt-in absolute ceiling (`["error", { max }]`); `undefined` = ratchet only. */
|
|
65
|
-
readonly max?: number;
|
|
66
|
-
readonly update: boolean;
|
|
67
|
-
readonly silent: boolean;
|
|
68
|
-
/** Called only when the rule is on or an update was asked for. */
|
|
69
|
-
readonly measure: () => readonly MeasuredBundle[];
|
|
70
|
-
readonly annotate: (level: "error" | "warning", message: string) => void;
|
|
71
|
-
}
|
|
72
|
-
/** What {@link checkContextCreepRatchet} hands back to `lint`. */
|
|
73
|
-
interface RatchetResult {
|
|
74
|
-
readonly issues: number;
|
|
75
|
-
readonly errors: number;
|
|
76
|
-
/** Notes to show even when `lint` is silent (`--summary`): the old-file rename command. */
|
|
77
|
-
readonly notes: readonly string[];
|
|
78
|
-
}
|
|
79
|
-
/** Run the ratchet for `lint`: print, annotate, count. */
|
|
80
|
-
export declare function checkContextCreepRatchet(opts: RatchetOptions): RatchetResult;
|
|
81
|
-
/**
|
|
82
|
-
* The line `compile` prints after writing instruction files: the weight NOW,
|
|
83
|
-
* against the baseline, at the moment the author changed it. Report-only —
|
|
84
|
-
* `lint` stays the single gate. `null` when there is nothing to weigh.
|
|
85
|
-
*/
|
|
86
|
-
export declare function compileWeightLine(root: string, measured: MeasuredBundle): string | null;
|
|
87
|
-
export {};
|
|
88
|
-
//# sourceMappingURL=context-creep-ratchet.d.ts.map
|
|
@@ -1,270 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.baselineSource = baselineSource;
|
|
4
|
-
exports.readInstructionBaseline = readInstructionBaseline;
|
|
5
|
-
exports.writeInstructionBaseline = writeInstructionBaseline;
|
|
6
|
-
exports.ratchetLines = ratchetLines;
|
|
7
|
-
exports.updateRefusals = updateRefusals;
|
|
8
|
-
exports.checkContextCreepRatchet = checkContextCreepRatchet;
|
|
9
|
-
exports.compileWeightLine = compileWeightLine;
|
|
10
|
-
/**
|
|
11
|
-
* `lint`'s side of the context-creep ratchet: measure each scored bundle,
|
|
12
|
-
* compare it with `.vigiles/context-creep.json`, and — only under the
|
|
13
|
-
* explicit `--update-baseline` — write that file.
|
|
14
|
-
*
|
|
15
|
-
* The decisions (what a verdict is, what it says) live in
|
|
16
|
-
* `core/instruction-baseline.ts`; this module owns the two effects the core
|
|
17
|
-
* must not have, reading and writing the committed file, plus turning verdicts
|
|
18
|
-
* into lint counters.
|
|
19
|
-
*
|
|
20
|
-
* WHY THE FILE IS COMMITTED, unlike `.vigiles/coverage.json`. Coverage records
|
|
21
|
-
* what tests ran on THIS machine, so a committed copy would credit a checkout
|
|
22
|
-
* where nothing ran. The baseline records a property of the COMMIT: it is built
|
|
23
|
-
* from `committedTotal`, which already leaves out every per-machine file
|
|
24
|
-
* (`CLAUDE.local.md`, a gitignored settings sibling), so two clones of one
|
|
25
|
-
* commit compute byte-identical files. That is what lets CI compare against it.
|
|
26
|
-
*/
|
|
27
|
-
const node_fs_1 = require("node:fs");
|
|
28
|
-
const node_path_1 = require("node:path");
|
|
29
|
-
const instruction_baseline_js_1 = require("./core/instruction-baseline.js");
|
|
30
|
-
function baselineSource(root) {
|
|
31
|
-
const hasNew = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE));
|
|
32
|
-
const hasOld = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, instruction_baseline_js_1.LEGACY_INSTRUCTION_BASELINE_FILE));
|
|
33
|
-
if (hasNew) {
|
|
34
|
-
return {
|
|
35
|
-
file: instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE,
|
|
36
|
-
legacy: hasOld ? "both" : "none",
|
|
37
|
-
};
|
|
38
|
-
}
|
|
39
|
-
return hasOld
|
|
40
|
-
? { file: instruction_baseline_js_1.LEGACY_INSTRUCTION_BASELINE_FILE, legacy: "only" }
|
|
41
|
-
: { file: instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE, legacy: "none" };
|
|
42
|
-
}
|
|
43
|
-
function readInstructionBaseline(root) {
|
|
44
|
-
const path = (0, node_path_1.join)(root, baselineSource(root).file);
|
|
45
|
-
return (0, node_fs_1.existsSync)(path)
|
|
46
|
-
? (0, instruction_baseline_js_1.parseInstructionBaseline)((0, node_fs_1.readFileSync)(path, "utf-8"))
|
|
47
|
-
: { kind: "absent" };
|
|
48
|
-
}
|
|
49
|
-
/** Write the baseline for every measured bundle; returns what was written. */
|
|
50
|
-
function writeInstructionBaseline(root, onDisk, measured) {
|
|
51
|
-
const previous = onDisk.kind === "ok" ? onDisk.baseline : undefined;
|
|
52
|
-
const next = (0, instruction_baseline_js_1.recordEntries)(previous, measured.map((m) => [m[0], recordedEntry(m, previous)]));
|
|
53
|
-
const path = (0, node_path_1.join)(root, instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE);
|
|
54
|
-
(0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
|
|
55
|
-
(0, node_fs_1.writeFileSync)(path, (0, instruction_baseline_js_1.serializeBaseline)(next));
|
|
56
|
-
return next;
|
|
57
|
-
}
|
|
58
|
-
/**
|
|
59
|
-
* What `--update-baseline` writes for one bundle: the measured entry, with
|
|
60
|
-
* every part the old entry records and this run cannot measure carried over —
|
|
61
|
-
* re-recording must not drop a part only because the adapter stopped modelling
|
|
62
|
-
* it (`carryUnmeasured`).
|
|
63
|
-
*/
|
|
64
|
-
function recordedEntry(m, previous) {
|
|
65
|
-
if (m[1] === null)
|
|
66
|
-
return null;
|
|
67
|
-
const [at, weight, loaded] = m;
|
|
68
|
-
const old = entryAt(previous?.bundles ?? {}, at);
|
|
69
|
-
return (0, instruction_baseline_js_1.carryUnmeasured)((0, instruction_baseline_js_1.entryFor)(weight, loaded), loaded, old).entry;
|
|
70
|
-
}
|
|
71
|
-
/** One bundle's recorded entry, or `undefined` when the file has none. */
|
|
72
|
-
const entryAt = (bundles, at) => Object.hasOwn(bundles, at) ? bundles[at] : undefined;
|
|
73
|
-
/**
|
|
74
|
-
* Pure: the lines a run prints, given what was measured and what is on disk.
|
|
75
|
-
* `max` is the opt-in absolute ceiling; a bundle over it adds a finding of its
|
|
76
|
-
* own, whatever the baseline says (including when there is none, or it is
|
|
77
|
-
* unreadable).
|
|
78
|
-
*
|
|
79
|
-
* A bundle with no entry is a nudge while the repo has NO baseline file (it has
|
|
80
|
-
* not opted in, and a fresh repo must not fail on day one) — but a FINDING once
|
|
81
|
-
* the file exists: a bundle that appeared after the baseline was recorded is
|
|
82
|
-
* weight nobody signed off on.
|
|
83
|
-
*/
|
|
84
|
-
function ratchetLines(onDisk, measured, max, source = { file: instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE, legacy: "none" }) {
|
|
85
|
-
return [
|
|
86
|
-
...baselineLines(onDisk, measured, source.file),
|
|
87
|
-
...legacyLines(source.legacy),
|
|
88
|
-
...measured.flatMap(([at, weight]) => ceilingLine(at, weight, max)),
|
|
89
|
-
];
|
|
90
|
-
}
|
|
91
|
-
/** One bundle's ceiling finding, or nothing when it is at or under `max`. */
|
|
92
|
-
function ceilingLine(at, weight, max) {
|
|
93
|
-
const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
|
|
94
|
-
return over === undefined
|
|
95
|
-
? []
|
|
96
|
-
: [{ at, status: "finding", text: (0, instruction_baseline_js_1.formatCeiling)(over, at) }];
|
|
97
|
-
}
|
|
98
|
-
/** The one finding an unreadable baseline file gets. */
|
|
99
|
-
const unreadableLine = (message, file) => ({
|
|
100
|
-
at: ".",
|
|
101
|
-
status: "finding",
|
|
102
|
-
text: `${file} cannot be read (${message}) — ` +
|
|
103
|
-
`re-record it with \`${instruction_baseline_js_1.UPDATE_BASELINE_COMMAND}\``,
|
|
104
|
-
});
|
|
105
|
-
/** The rename/remove NOTE for a repo that still has the old baseline file. */
|
|
106
|
-
function legacyLines(legacy) {
|
|
107
|
-
const text = (0, instruction_baseline_js_1.legacyBaselineNote)(legacy);
|
|
108
|
-
return text === undefined ? [] : [{ at: ".", status: "note", text }];
|
|
109
|
-
}
|
|
110
|
-
function baselineLines(onDisk, measured, path) {
|
|
111
|
-
if (onDisk.kind === "invalid")
|
|
112
|
-
return [unreadableLine(onDisk.message, path)];
|
|
113
|
-
const recorded = onDisk.kind === "ok" ? onDisk.baseline.bundles : {};
|
|
114
|
-
const file = onDisk.kind === "ok" ? onDisk.baseline.version : "absent";
|
|
115
|
-
return measured.flatMap((m) => {
|
|
116
|
-
if (m[1] === null)
|
|
117
|
-
return [];
|
|
118
|
-
const [at, weight, loaded] = m;
|
|
119
|
-
const verdict = (0, instruction_baseline_js_1.compareAlwaysLoadedToBaseline)(weight, loaded, entryAt(recorded, at), file);
|
|
120
|
-
const text = `${(0, instruction_baseline_js_1.formatBaselineVerdict)(verdict, at)}${unfollowedNote(weight)}`;
|
|
121
|
-
return [
|
|
122
|
-
{ at, status: lineStatus(verdict, onDisk), text },
|
|
123
|
-
...partNotes(verdict, weight.unit, at),
|
|
124
|
-
];
|
|
125
|
-
});
|
|
126
|
-
}
|
|
127
|
-
/**
|
|
128
|
-
* `held` is ok; a bundle with no entry is a nudge while the repo has no
|
|
129
|
-
* baseline file — every other verdict is a finding.
|
|
130
|
-
*/
|
|
131
|
-
function lineStatus(verdict, onDisk) {
|
|
132
|
-
if (verdict.verdict.kind === "held")
|
|
133
|
-
return "ok";
|
|
134
|
-
return verdict.verdict.kind === "unrecorded" && onDisk.kind !== "ok"
|
|
135
|
-
? "note"
|
|
136
|
-
: "finding";
|
|
137
|
-
}
|
|
138
|
-
/**
|
|
139
|
-
* An import named and not read is weight this number lacks — a second hop, or
|
|
140
|
-
* a path that does not resolve. Said on the line itself, because the gate
|
|
141
|
-
* holding is only as true as the sum it holds.
|
|
142
|
-
*/
|
|
143
|
-
function unfollowedNote(weight) {
|
|
144
|
-
return weight.unreadImports.length > 0
|
|
145
|
-
? ` (${String(weight.unreadImports.length)} import(s) not followed: ${weight.unreadImports.join(", ")} — their size is not in this number)`
|
|
146
|
-
: "";
|
|
147
|
-
}
|
|
148
|
-
/**
|
|
149
|
-
* A version-1 file's NOTE for parts that are not in it. Never a finding: a
|
|
150
|
-
* repo whose file predates the always-loaded context must not go red on upgrade — it
|
|
151
|
-
* records the parts when it chooses to, and they gate from then on.
|
|
152
|
-
*/
|
|
153
|
-
function partNotes(verdict, unit, at) {
|
|
154
|
-
return verdict.kind === "instructions-only" &&
|
|
155
|
-
verdict.unrecordedParts.length > 0
|
|
156
|
-
? [
|
|
157
|
-
{
|
|
158
|
-
at,
|
|
159
|
-
status: "note",
|
|
160
|
-
text: (0, instruction_baseline_js_1.formatUnrecordedParts)(verdict.unrecordedParts, unit, at),
|
|
161
|
-
},
|
|
162
|
-
]
|
|
163
|
-
: [];
|
|
164
|
-
}
|
|
165
|
-
/**
|
|
166
|
-
* The bundles `--update-baseline` must not record: each one over the ceiling,
|
|
167
|
-
* as the refusal text. Empty when there is no ceiling or nothing exceeds it.
|
|
168
|
-
*/
|
|
169
|
-
function updateRefusals(measured, max) {
|
|
170
|
-
return measured.flatMap(([at, weight]) => {
|
|
171
|
-
const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
|
|
172
|
-
return over === undefined ? [] : [(0, instruction_baseline_js_1.formatRefusal)(over, at)];
|
|
173
|
-
});
|
|
174
|
-
}
|
|
175
|
-
/**
|
|
176
|
-
* What `lint` compares against: the file as it is, or — under `--update-baseline`
|
|
177
|
-
* and when nothing is over the ceiling — the file just written. A baseline above
|
|
178
|
-
* the ceiling would bypass it (re-recording is how a ratchet gets loosened), so
|
|
179
|
-
* then nothing is written and the refusals are returned for the caller to fail on.
|
|
180
|
-
*/
|
|
181
|
-
function recordOrRead(opts, measured) {
|
|
182
|
-
const before = readInstructionBaseline(opts.root);
|
|
183
|
-
const refusals = opts.update ? updateRefusals(measured, opts.max) : [];
|
|
184
|
-
const record = opts.update && refusals.length === 0;
|
|
185
|
-
return {
|
|
186
|
-
refusals,
|
|
187
|
-
onDisk: record
|
|
188
|
-
? {
|
|
189
|
-
kind: "ok",
|
|
190
|
-
baseline: writeInstructionBaseline(opts.root, before, measured),
|
|
191
|
-
}
|
|
192
|
-
: before,
|
|
193
|
-
};
|
|
194
|
-
}
|
|
195
|
-
/** The human-readable report: what was recorded, then one line per bundle. */
|
|
196
|
-
function printReport(lines, severity, recorded) {
|
|
197
|
-
console.log("\nContext-creep ratchet:\n");
|
|
198
|
-
if (recorded)
|
|
199
|
-
console.log(` ✓ recorded ${instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE}`);
|
|
200
|
-
const marks = {
|
|
201
|
-
finding: severity === "error" ? "✗" : "⚠",
|
|
202
|
-
ok: "✓",
|
|
203
|
-
note: "ℹ",
|
|
204
|
-
};
|
|
205
|
-
lines.forEach((l) => {
|
|
206
|
-
console.log(` ${marks[l.status]} ${l.text}`);
|
|
207
|
-
});
|
|
208
|
-
}
|
|
209
|
-
/** The notes `--summary` carries: only while the rule is on, and only the old-file one. */
|
|
210
|
-
function noteTexts(severity, source) {
|
|
211
|
-
return severity ? legacyLines(source.legacy).map((l) => l.text) : [];
|
|
212
|
-
}
|
|
213
|
-
/** The refusals, printed and annotated: a baseline above the ceiling is never written. */
|
|
214
|
-
function reportRefusals(opts, refusals) {
|
|
215
|
-
refusals.forEach((message) => {
|
|
216
|
-
console.error(`✗ ${message}`);
|
|
217
|
-
opts.annotate("error", message);
|
|
218
|
-
});
|
|
219
|
-
}
|
|
220
|
-
/** Run the ratchet for `lint`: print, annotate, count. */
|
|
221
|
-
function checkContextCreepRatchet(opts) {
|
|
222
|
-
const { severity, update, silent } = opts;
|
|
223
|
-
if (!severity && !update)
|
|
224
|
-
return { issues: 0, errors: 0, notes: [] };
|
|
225
|
-
const measured = opts.measure();
|
|
226
|
-
const { onDisk, refusals } = recordOrRead(opts, measured);
|
|
227
|
-
reportRefusals(opts, refusals);
|
|
228
|
-
// Read AFTER a possible write: an update leaves the new file beside an old
|
|
229
|
-
// one, and the note must then say the old one is stale.
|
|
230
|
-
const source = baselineSource(opts.root);
|
|
231
|
-
const lines = severity
|
|
232
|
-
? ratchetLines(onDisk, measured, opts.max, source)
|
|
233
|
-
: [];
|
|
234
|
-
const findings = lines.filter((l) => l.status === "finding");
|
|
235
|
-
if (!silent && (update || lines.length > 0)) {
|
|
236
|
-
printReport(lines, severity, update && refusals.length === 0);
|
|
237
|
-
}
|
|
238
|
-
const level = severity === "error" ? "error" : "warning";
|
|
239
|
-
findings.forEach((l) => {
|
|
240
|
-
opts.annotate(level, l.text);
|
|
241
|
-
});
|
|
242
|
-
return {
|
|
243
|
-
issues: findings.length + refusals.length,
|
|
244
|
-
errors: (severity === "error" ? findings.length : 0) + refusals.length,
|
|
245
|
-
notes: noteTexts(severity, source),
|
|
246
|
-
};
|
|
247
|
-
}
|
|
248
|
-
/**
|
|
249
|
-
* The line `compile` prints after writing instruction files: the weight NOW,
|
|
250
|
-
* against the baseline, at the moment the author changed it. Report-only —
|
|
251
|
-
* `lint` stays the single gate. `null` when there is nothing to weigh.
|
|
252
|
-
*/
|
|
253
|
-
function compileWeightLine(root, measured) {
|
|
254
|
-
if (measured[1] === null)
|
|
255
|
-
return null;
|
|
256
|
-
const [, weight, loaded] = measured;
|
|
257
|
-
const onDisk = readInstructionBaseline(root);
|
|
258
|
-
if (onDisk.kind === "invalid") {
|
|
259
|
-
return `always-loaded: ${baselineSource(root).file} cannot be read (${onDisk.message})`;
|
|
260
|
-
}
|
|
261
|
-
const recorded = onDisk.kind === "ok" ? onDisk.baseline.bundles : {};
|
|
262
|
-
const verdict = (0, instruction_baseline_js_1.compareAlwaysLoadedToBaseline)(weight, loaded, entryAt(recorded, "."), onDisk.kind === "ok" ? onDisk.baseline.version : "absent");
|
|
263
|
-
const line = (0, instruction_baseline_js_1.formatWeightLine)(verdict.verdict, verdict.kind === "always-loaded"
|
|
264
|
-
? "always-loaded context"
|
|
265
|
-
: "always-loaded");
|
|
266
|
-
return verdict.kind === "always-loaded" && verdict.unmeasured.length > 0
|
|
267
|
-
? [line, ...verdict.unmeasured.map(instruction_baseline_js_1.describeUnmeasured)].join("\n ")
|
|
268
|
-
: line;
|
|
269
|
-
}
|
|
270
|
-
//# sourceMappingURL=context-creep-ratchet.js.map
|