vigiles 40.0.0 → 41.0.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.
@@ -1,333 +0,0 @@
1
- /**
2
- * The context-creep RATCHET: the always-loaded weight may not grow past
3
- * what the repository itself last recorded.
4
- *
5
- * WHY A RATCHET AND NOT THE BUDGET. `./instruction-weight.ts` explains why the
6
- * harness's own threshold cannot gate: real repositories sit several times over
7
- * it, and a rule that fails every repo on day one is switched off on day one.
8
- * What CAN gate is the repository's own past. The baseline is whatever the repo
9
- * weighed when it was last recorded, so a repo four times over budget starts
10
- * green — and stays green only while it does not get heavier. The measured case
11
- * this exists for: a root instruction file cut from ~4 100 lines to ~1 900, then
12
- * regrown by ~1 000 lines over ten ordinary commits, with nothing in CI to say so.
13
- *
14
- * WHY THE SUM, AGAIN. The baseline records `committedTotal`, the same number the
15
- * audit report scores: everything the harness loads without being asked that a
16
- * teammate on the same commit also loads. A per-file baseline would read text
17
- * moved into an always-loaded sibling as a shrink — the evasion the weight
18
- * module was built to see through. The per-file sizes are recorded too, but only
19
- * so a message can say WHICH file moved; the verdict is decided on the total.
20
- *
21
- * WHY A SHRINK IS A FINDING TOO. A baseline left above the tree is headroom, and
22
- * headroom is exactly where the regrowth above landed: every character up to the
23
- * old number would pass. So, like ESLint's unpruned suppressions and `betterer
24
- * ci`, a tree LIGHTER than its baseline asks for the baseline to be lowered —
25
- * one command, in the same change that made the cut. The baseline then always
26
- * equals the tree on the default branch, and any growth at all is a diff a
27
- * reviewer sees.
28
- *
29
- * WHO WRITES IT. Never `lint` on its own: a read never writes. The file is
30
- * written only by the explicit `vigiles lint --update-baseline`, the same shape
31
- * as `eslint --suppress-all` / `--prune-suppressions` and `jest -u`. Raising the
32
- * baseline is allowed and is the point: growth is not forbidden, it is made
33
- * visible as a reviewed diff of a committed file.
34
- *
35
- * VERSION 2 — THE ALWAYS-LOADED CONTEXT. The output style the committed settings select
36
- * and the skill listing load at session start exactly as the instructions do
37
- * (`./always-loaded.ts`), so a section moved from `CLAUDE.md` into either is
38
- * the same relocation the sum above exists to see. A version-2 entry carries
39
- * them as `parts`, each with its own `measure`, and the verdict is decided on
40
- * the SUM of the instructions and every recorded part. Per part, so a change
41
- * to how one part is measured asks to re-record that part by name.
42
- *
43
- * ⚠️ THE TRADE-OFF OF A STRICT FILE, stated rather than hidden. Version 1 was
44
- * read with `.strict()` and `z.literal(1)`, so there is no extension of it an
45
- * OLDER vigiles accepts: it reads a version-2 file as "cannot be read", which
46
- * is a finding at the rule's severity — red CI wherever lint still runs the old
47
- * release, the moment one teammate re-records. Loud, never silent, but red. The
48
- * alternative, a sibling file old readers ignore, would split one gated sum
49
- * across two files, so that a move from one to the other read as a shrink in
50
- * each. What keeps the cost small:
51
- *
52
- * - a repo still on version 1 is read as before — the instructions gate as
53
- * they did, and each new part that is not zero is a NOTE, never a finding,
54
- * so upgrading vigiles never turns CI red;
55
- * - `--update-baseline` writes version 2 only when some part is not zero, so
56
- * a repo with no output style and no listed skill keeps a version-1 file
57
- * every release reads — and, once a file is version 2, keeps it there even
58
- * when every part drops to zero, so re-adding a part is growth, not a note;
59
- * - the note and the rule doc say to upgrade vigiles wherever lint runs
60
- * BEFORE re-recording.
61
- *
62
- * Pure: parsing, comparison and formatting only. Reading and writing the file
63
- * is the caller's (`src/context-creep-ratchet.ts`).
64
- */
65
- import { z } from "zod";
66
- import type { InstructionWeight } from "./instruction-weight.js";
67
- import type { AlwaysLoadedContext, LoadedPart, LoadedPartName } from "./always-loaded.js";
68
- /** Where the baseline lives, relative to the directory `.vigilesrc.json` is read from. */
69
- export declare const INSTRUCTION_BASELINE_FILE = ".vigiles/context-creep.json";
70
- /**
71
- * The name this baseline had before the rule became `context-creep`. Still
72
- * READ when the new file is absent (a repo upgrading keeps its ratchet), never
73
- * written; {@link legacyBaselineNote} tells the author how to move it.
74
- */
75
- export declare const LEGACY_INSTRUCTION_BASELINE_FILE = ".vigiles/instruction-weight.json";
76
- /** Which of the two baseline files exist: neither/only the new one, the old one alone, or both. */
77
- export type LegacyBaseline = "none" | "only" | "both";
78
- /** The command that renames the old baseline — quoted verbatim by the note. */
79
- export declare const RENAME_BASELINE_COMMAND = "git mv .vigiles/instruction-weight.json .vigiles/context-creep.json";
80
- /** The command that drops a stale old baseline once the new one exists. */
81
- export declare const REMOVE_LEGACY_BASELINE_COMMAND = "git rm .vigiles/instruction-weight.json";
82
- /**
83
- * The one-sentence NOTE (never a finding) for a repo that still has the old
84
- * file, or `undefined` when it has not. The exact command is in the text: the
85
- * session-start hook injects `lint --summary` into the agent, and the agent
86
- * runs the command.
87
- */
88
- export declare function legacyBaselineNote(legacy: LegacyBaseline): string | undefined;
89
- /** The command that writes the baseline — named once, quoted by every message. */
90
- export declare const UPDATE_BASELINE_COMMAND = "vigiles lint --update-baseline";
91
- /**
92
- * The newest on-disk shape this release reads and writes. Bumped only on an
93
- * incompatible change. Version 1 is still read, and still WRITTEN when no
94
- * always-loaded part has anything in it — see the header for why.
95
- */
96
- export declare const INSTRUCTION_BASELINE_VERSION = 2;
97
- /**
98
- * Which measurement produced a recorded PART — the same job as
99
- * {@link INSTRUCTION_WEIGHT_MEASURE}, per part, so a change to how the skill
100
- * listing is rendered re-records the listing and names it.
101
- */
102
- export declare const LOADED_PART_MEASURE = 1;
103
- /** The parts a version-2 entry may carry, in the order they are printed. */
104
- export declare const LOADED_PART_NAMES: readonly LoadedPartName[];
105
- /**
106
- * Which MEASUREMENT produced a recorded number — bumped whenever a release
107
- * changes what counts (chain membership in any adapter, how a file is sized),
108
- * even when the file shape stays the same.
109
- *
110
- * Without it, a vigiles fix that moves a file into or out of the chain moves
111
- * `committedTotal` on every consumer with a committed baseline, and they see
112
- * `grew`/`shrank` attributed to their own content. With it, they see one
113
- * "re-record" verdict that names the cause. `version` cannot do this job: it
114
- * describes the file, not the number in it.
115
- */
116
- export declare const INSTRUCTION_WEIGHT_MEASURE = 1;
117
- declare const partSchema: z.ZodObject<{
118
- measure: z.ZodNumber;
119
- total: z.ZodNumber;
120
- files: z.ZodRecord<z.ZodString, z.ZodNumber>;
121
- }, z.core.$strict>;
122
- declare const entrySchema: z.ZodObject<{
123
- unit: z.ZodEnum<{
124
- chars: "chars";
125
- bytes: "bytes";
126
- }>;
127
- measure: z.ZodNumber;
128
- total: z.ZodNumber;
129
- files: z.ZodRecord<z.ZodString, z.ZodNumber>;
130
- parts: z.ZodOptional<z.ZodObject<{
131
- "output-style": z.ZodOptional<z.ZodObject<{
132
- measure: z.ZodNumber;
133
- total: z.ZodNumber;
134
- files: z.ZodRecord<z.ZodString, z.ZodNumber>;
135
- }, z.core.$strict>>;
136
- "skill-listing": z.ZodOptional<z.ZodObject<{
137
- measure: z.ZodNumber;
138
- total: z.ZodNumber;
139
- files: z.ZodRecord<z.ZodString, z.ZodNumber>;
140
- }, z.core.$strict>>;
141
- }, z.core.$strict>>;
142
- }, z.core.$strict>;
143
- declare const baselineSchema: z.ZodObject<{
144
- version: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>;
145
- bundles: z.ZodRecord<z.ZodString, z.ZodObject<{
146
- unit: z.ZodEnum<{
147
- chars: "chars";
148
- bytes: "bytes";
149
- }>;
150
- measure: z.ZodNumber;
151
- total: z.ZodNumber;
152
- files: z.ZodRecord<z.ZodString, z.ZodNumber>;
153
- parts: z.ZodOptional<z.ZodObject<{
154
- "output-style": z.ZodOptional<z.ZodObject<{
155
- measure: z.ZodNumber;
156
- total: z.ZodNumber;
157
- files: z.ZodRecord<z.ZodString, z.ZodNumber>;
158
- }, z.core.$strict>>;
159
- "skill-listing": z.ZodOptional<z.ZodObject<{
160
- measure: z.ZodNumber;
161
- total: z.ZodNumber;
162
- files: z.ZodRecord<z.ZodString, z.ZodNumber>;
163
- }, z.core.$strict>>;
164
- }, z.core.$strict>>;
165
- }, z.core.$strict>>;
166
- }, z.core.$strict>;
167
- /** One bundle's recorded weight. */
168
- export type BaselineEntry = Readonly<z.infer<typeof entrySchema>>;
169
- /** One recorded always-loaded part. */
170
- export type BaselinePart = Readonly<z.infer<typeof partSchema>>;
171
- /** The whole committed file. */
172
- export type InstructionBaseline = z.infer<typeof baselineSchema>;
173
- /** The file's contents, parsed once at the boundary. */
174
- export type ParsedBaseline = {
175
- readonly kind: "ok";
176
- readonly baseline: InstructionBaseline;
177
- } | {
178
- readonly kind: "invalid";
179
- readonly message: string;
180
- };
181
- export declare function parseInstructionBaseline(text: string): ParsedBaseline;
182
- /**
183
- * What a measured weight would be recorded as: the SCORED files only, plus
184
- * every always-loaded part that is not zero when one is handed in.
185
- */
186
- export declare function entryFor(weight: InstructionWeight, loaded?: AlwaysLoadedContext): BaselineEntry;
187
- /** One file whose recorded size differs. `null` = absent on that side. */
188
- export interface FileChange {
189
- readonly path: string;
190
- readonly from: number | null;
191
- readonly to: number | null;
192
- }
193
- /**
194
- * The comparison of a tree against its baseline. Each case is a different fact,
195
- * so each is its own member — "no baseline" is not "equal", and a baseline in
196
- * another unit is not a number to subtract.
197
- */
198
- export type RatchetVerdict = {
199
- readonly kind: "unrecorded";
200
- /** What `--update-baseline` would write. */
201
- readonly current: BaselineEntry;
202
- } | {
203
- readonly kind: "unit-changed";
204
- readonly recorded: BaselineEntry["unit"];
205
- readonly current: BaselineEntry["unit"];
206
- } | {
207
- readonly kind: "measure-changed";
208
- readonly recorded: number;
209
- readonly current: number;
210
- /** Set when it is one always-loaded PART whose measurement changed. */
211
- readonly part?: LoadedPartName;
212
- } | {
213
- readonly kind: "held";
214
- readonly total: number;
215
- readonly unit: BaselineEntry["unit"];
216
- } | {
217
- readonly kind: "grew" | "shrank";
218
- readonly from: number;
219
- readonly to: number;
220
- readonly unit: BaselineEntry["unit"];
221
- /** Every file whose size moved, largest movement first. */
222
- readonly changes: readonly FileChange[];
223
- };
224
- export declare function compareToBaseline(weight: InstructionWeight, recorded: BaselineEntry | undefined): RatchetVerdict;
225
- /** One part's recorded and current size, for the line that says where weight moved. */
226
- export interface PartMove {
227
- readonly part: "instructions" | LoadedPartName;
228
- readonly from: number;
229
- readonly to: number;
230
- }
231
- /**
232
- * The ratchet's verdict for one bundle with its always-loaded context:
233
- *
234
- * - `instructions-only` — decided on the instructions as before. A version-1
235
- * file, or a repo with no part to add and no file yet. Each part that is
236
- * not zero is listed so the caller can print it as a NOTE.
237
- * - `always-loaded` — decided on the SUM of the instructions and the parts: a
238
- * version-2 file, or no file yet and something to add (recording then
239
- * writes version 2). `byPart` says where weight moved, also on `held`,
240
- * because a held sum can hide a listing that doubled while the
241
- * instructions halved.
242
- */
243
- export type BaselineVerdict = {
244
- readonly kind: "instructions-only";
245
- readonly verdict: RatchetVerdict;
246
- readonly unrecordedParts: readonly {
247
- readonly part: LoadedPartName;
248
- readonly total: number;
249
- }[];
250
- } | {
251
- readonly kind: "always-loaded";
252
- readonly verdict: RatchetVerdict;
253
- readonly byPart: readonly PartMove[];
254
- /** Recorded parts this run cannot measure, carried rather than compared. */
255
- readonly unmeasured: readonly UnmeasuredPart[];
256
- };
257
- /**
258
- * A part the baseline records and this run cannot measure: the adapter no
259
- * longer models it (`not-modelled`), the harness has no such part
260
- * (`not-supported`), or the selected style names no repository file
261
- * (`unresolved`). None of these is ZERO (`./always-loaded.ts` keeps them apart
262
- * for that reason), so the recorded size is carried into the comparison and
263
- * into a re-record instead of being read as a cut. Reading it as 0 would print
264
- * "shrank … lock the cut in", and following that advice would delete the part
265
- * — and, with no part left, turn the file back into version 1, silently
266
- * returning the gate to the instructions alone.
267
- */
268
- export interface UnmeasuredPart {
269
- readonly part: LoadedPartName;
270
- readonly kind: Exclude<LoadedPart["kind"], "counted" | "none">;
271
- readonly recorded: number;
272
- }
273
- /**
274
- * `current` with every recorded part this run cannot measure carried over from
275
- * `recorded`, and the list of those parts. `counted` and `none` are measured —
276
- * `none` is a real zero — so they are never carried.
277
- */
278
- export declare function carryUnmeasured(current: BaselineEntry, loaded: AlwaysLoadedContext, recorded: BaselineEntry | undefined): {
279
- readonly entry: BaselineEntry;
280
- readonly unmeasured: readonly UnmeasuredPart[];
281
- };
282
- /** Which version of the file the verdict is read against; `absent` = no file. */
283
- export type BaselineFileVersion = 1 | typeof INSTRUCTION_BASELINE_VERSION | "absent";
284
- export declare function compareAlwaysLoadedToBaseline(weight: InstructionWeight, loaded: AlwaysLoadedContext, recorded: BaselineEntry | undefined, file: BaselineFileVersion): BaselineVerdict;
285
- /** One file's size, for naming where the weight is. */
286
- export interface FileWeight {
287
- readonly path: string;
288
- readonly size: number;
289
- }
290
- /**
291
- * A total above the opt-in absolute ceiling (`["error", { max }]`).
292
- *
293
- * Decided on the same number the ratchet records — `committedTotal`, the SCORED
294
- * files only — and in the same unit, so the two can never disagree about what
295
- * the weight is. It does not look at the baseline at all: that independence is
296
- * what makes it a ceiling and not a second ratchet.
297
- */
298
- export interface CeilingVerdict {
299
- readonly total: number;
300
- readonly max: number;
301
- readonly unit: BaselineEntry["unit"];
302
- /** The scored files, heaviest first — where the cut has to come from. */
303
- readonly largest: readonly FileWeight[];
304
- }
305
- /** `undefined` when the weight is at or under `max`, or when no ceiling is set. */
306
- export declare function checkCeiling(weight: InstructionWeight, max: number | undefined): CeilingVerdict | undefined;
307
- /** Replace the measured bundles' entries; `null` removes one. Others are kept. */
308
- export declare function recordEntries(previous: InstructionBaseline | undefined, measured: readonly (readonly [string, BaselineEntry | null])[]): InstructionBaseline;
309
- /** Stable text: sorted keys, two-space indent, trailing newline, no timestamp. */
310
- export declare function serializeBaseline(baseline: InstructionBaseline): string;
311
- /** The one-paragraph message a verdict prints as, prefixed by its bundle. */
312
- export declare function formatVerdict(verdict: RatchetVerdict, at: string, subject?: string): string;
313
- /** The message for one bundle's {@link BaselineVerdict}, prefixed by its bundle. */
314
- export declare function formatBaselineVerdict(verdict: BaselineVerdict, at: string): string;
315
- /** Why a recorded part was carried: the run could not measure it, not a cut. */
316
- export declare function describeUnmeasured(u: UnmeasuredPart): string;
317
- /**
318
- * The NOTE a version-1 file gets for each part that is not zero: always
319
- * loaded, not yet in the baseline, and what recording it does — including the
320
- * one cost of recording, an older vigiles reading the new file as unreadable.
321
- */
322
- export declare function formatUnrecordedParts(parts: readonly {
323
- readonly part: LoadedPartName;
324
- readonly total: number;
325
- }[], unit: BaselineEntry["unit"], at: string): string;
326
- /** The message for a total over the ceiling, prefixed by its bundle. */
327
- export declare function formatCeiling(verdict: CeilingVerdict, at: string): string;
328
- /** Why `--update-baseline` wrote nothing: the ceiling it would have been recorded above. */
329
- export declare function formatRefusal(verdict: CeilingVerdict, at: string): string;
330
- /** The compile-time one-liner: weight now, against the baseline when there is one. */
331
- export declare function formatWeightLine(verdict: RatchetVerdict, label?: string): string;
332
- export {};
333
- //# sourceMappingURL=instruction-baseline.d.ts.map