vigiles 39.2.0 → 40.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.
- package/dist/adapter.d.ts +3 -2
- package/dist/adapters/claude-code/dialect.js +4 -0
- package/dist/adapters/claude-code/output-style.js +15 -0
- package/dist/adapters/claude-code/skill-listing.d.ts +48 -0
- package/dist/adapters/claude-code/skill-listing.js +54 -0
- package/dist/adapters/codex/dialect.js +4 -0
- package/dist/adapters/codex/layout.js +5 -0
- package/dist/adapters/codex/mock-model.d.ts +7 -0
- package/dist/adapters/codex/mock-model.js +1 -0
- package/dist/adapters/codex/skill-listing.d.ts +42 -0
- package/dist/adapters/codex/skill-listing.js +40 -0
- package/dist/audit-html.js +7 -2
- package/dist/audit-report.d.ts +51 -0
- package/dist/audit-report.js +54 -8
- package/dist/audit-report.template.html +38 -33
- package/dist/cli-main.d.ts +9 -3
- package/dist/cli-main.js +32 -17
- package/dist/{instruction-weight-ratchet.d.ts → context-creep-ratchet.d.ts} +34 -12
- package/dist/context-creep-ratchet.js +270 -0
- package/dist/core/always-loaded.d.ts +128 -0
- package/dist/core/always-loaded.js +134 -0
- package/dist/core/compile.js +1 -1
- package/dist/core/dialect.d.ts +9 -0
- package/dist/core/harness-unit.d.ts +20 -0
- package/dist/core/harness-unit.js +24 -0
- package/dist/core/instruction-baseline.d.ts +179 -11
- package/dist/core/instruction-baseline.js +349 -47
- package/dist/core/instruction-weight.d.ts +2 -11
- package/dist/core/instruction-weight.js +6 -16
- package/dist/core/layout.d.ts +40 -0
- package/dist/core/layout.js +25 -1
- package/dist/core/output-style.d.ts +20 -0
- package/dist/core/skill-listing.d.ts +49 -0
- package/dist/core/skill-listing.js +23 -0
- package/dist/core/types.d.ts +2 -2
- package/dist/deprecated-key-files.d.ts +1 -1
- package/dist/deprecated-key-files.js +1 -1
- package/dist/fs-walk.d.ts +31 -0
- package/dist/fs-walk.js +49 -0
- package/dist/local-files.js +2 -1
- package/dist/plugin-loader.js +40 -19
- package/dist/rules/index.d.ts +4 -4
- package/dist/rules/index.js +7 -7
- package/dist/scan-files.js +24 -3
- package/dist/scan.d.ts +30 -1
- package/dist/scan.js +69 -3
- package/dist/surface-discovery-fs.d.ts +15 -0
- package/dist/surface-discovery-fs.js +55 -0
- package/dist/vigilesrc.schema.json +2 -2
- package/hooks/session-start.sh +3 -1
- package/package.json +1 -1
- package/dist/instruction-weight-ratchet.js +0 -181
package/dist/cli-main.d.ts
CHANGED
|
@@ -84,8 +84,14 @@ interface LintReport {
|
|
|
84
84
|
hookBlockErrors: number;
|
|
85
85
|
hookMatcherIssues: number;
|
|
86
86
|
hookMatcherErrors: number;
|
|
87
|
-
|
|
88
|
-
|
|
87
|
+
contextCreepIssues: number;
|
|
88
|
+
contextCreepErrors: number;
|
|
89
|
+
/**
|
|
90
|
+
* Notes the context-creep ratchet raises that never count: today the one
|
|
91
|
+
* naming the old baseline file and the command that moves it. `--summary`
|
|
92
|
+
* prints them, because the session-start hook injects that output.
|
|
93
|
+
*/
|
|
94
|
+
contextCreepNotes: readonly string[];
|
|
89
95
|
deprecatedKeyFilesIssues: number;
|
|
90
96
|
deprecatedKeyFilesErrors: number;
|
|
91
97
|
docRefErrors: number;
|
|
@@ -129,7 +135,7 @@ export declare function lintTotals(report: LintReport): {
|
|
|
129
135
|
* suggest improvements.
|
|
130
136
|
*
|
|
131
137
|
* Flags:
|
|
132
|
-
* --summary Print a single-line summary (for SessionStart hooks)
|
|
138
|
+
* --summary Print a single-line summary (for SessionStart hooks), plus one note line while the old baseline file exists
|
|
133
139
|
* --json Print structured JSON report (for CI integration)
|
|
134
140
|
*/
|
|
135
141
|
/**
|
package/dist/cli-main.js
CHANGED
|
@@ -49,7 +49,7 @@ const setup_plan_js_1 = require("./setup-plan.js");
|
|
|
49
49
|
const types_js_1 = require("./core/types.js");
|
|
50
50
|
const test_coverage_js_1 = require("./test-coverage.js");
|
|
51
51
|
const scan_js_1 = require("./scan.js");
|
|
52
|
-
const
|
|
52
|
+
const context_creep_ratchet_js_1 = require("./context-creep-ratchet.js");
|
|
53
53
|
const frame_js_1 = require("./core/frame.js");
|
|
54
54
|
const surface_discovery_js_1 = require("./core/surface-discovery.js");
|
|
55
55
|
const scan_trigger_suggest_js_1 = require("./scan-trigger-suggest.js");
|
|
@@ -538,7 +538,7 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
|
|
|
538
538
|
*
|
|
539
539
|
* `estimateTokens` is `length / 4`, calibrated for ASCII English; it undercounts
|
|
540
540
|
* Cyrillic and CJK substantially. It is labelled `est.` for that reason and must
|
|
541
|
-
* never become the number a rule gates on — see the
|
|
541
|
+
* never become the number a rule gates on — see the context-creep rule.
|
|
542
542
|
*/
|
|
543
543
|
function formatArtifactSize(markdown) {
|
|
544
544
|
const chars = markdown.length;
|
|
@@ -711,6 +711,17 @@ async function compile(specPaths, config, excludes, opts = {}) {
|
|
|
711
711
|
function isGitHubActions() {
|
|
712
712
|
return process.env.GITHUB_ACTIONS === "true";
|
|
713
713
|
}
|
|
714
|
+
/**
|
|
715
|
+
* One bundle's always-loaded weight and always-loaded context, measured by the one
|
|
716
|
+
* route `scan` reports and `lint`'s ratchet gates — so `lint` and `compile`
|
|
717
|
+
* cannot arrive at a different number from the audit.
|
|
718
|
+
*/
|
|
719
|
+
function measuredBundle(at, abs, harness) {
|
|
720
|
+
const m = (0, scan_js_1.measureAlwaysLoaded)(abs, harness);
|
|
721
|
+
return m.instructionWeight === null
|
|
722
|
+
? [at, null]
|
|
723
|
+
: [at, m.instructionWeight, m.alwaysLoaded];
|
|
724
|
+
}
|
|
714
725
|
/**
|
|
715
726
|
* Emit a GitHub Actions annotation for the inline PR experience.
|
|
716
727
|
* No-op outside GitHub Actions.
|
|
@@ -1080,7 +1091,7 @@ function lintExitCode(report) {
|
|
|
1080
1091
|
report.delegationTrifectaErrors > 0 ||
|
|
1081
1092
|
report.hookBlockErrors > 0 ||
|
|
1082
1093
|
report.hookMatcherErrors > 0 ||
|
|
1083
|
-
report.
|
|
1094
|
+
report.contextCreepErrors > 0 ||
|
|
1084
1095
|
report.deprecatedKeyFilesErrors > 0 ||
|
|
1085
1096
|
report.symbolRefErrors > 0 ||
|
|
1086
1097
|
report.mcpRefErrors > 0 ||
|
|
@@ -1327,7 +1338,7 @@ function verifyMarkdownModeRules(frame, files, silent, config) {
|
|
|
1327
1338
|
* suggest improvements.
|
|
1328
1339
|
*
|
|
1329
1340
|
* Flags:
|
|
1330
|
-
* --summary Print a single-line summary (for SessionStart hooks)
|
|
1341
|
+
* --summary Print a single-line summary (for SessionStart hooks), plus one note line while the old baseline file exists
|
|
1331
1342
|
* --json Print structured JSON report (for CI integration)
|
|
1332
1343
|
*/
|
|
1333
1344
|
/**
|
|
@@ -1859,19 +1870,16 @@ async function runLint(restArgs, flags, excludes, config) {
|
|
|
1859
1870
|
// typo, an uncompilable or unreachable MCP pattern, one too narrow for real
|
|
1860
1871
|
// server naming, or an undeclared MCP server).
|
|
1861
1872
|
const hookMatcher = overBundles(checkHookMatcher, run, lintRoots);
|
|
1862
|
-
// 7v.
|
|
1873
|
+
// 7v. Context-creep ratchet — the always-loaded instruction weight may
|
|
1863
1874
|
// not move off the committed baseline. One file for the whole run (bundles
|
|
1864
1875
|
// are keys inside it), so it runs ONCE over `lintRoots`, not per bundle.
|
|
1865
|
-
const
|
|
1876
|
+
const contextCreep = (0, context_creep_ratchet_js_1.checkContextCreepRatchet)({
|
|
1866
1877
|
root: frame.root,
|
|
1867
|
-
severity: (0, types_js_1.ruleSeverity)(config?.rules?.["
|
|
1868
|
-
max: (0, types_js_1.ruleOptions)(config?.rules?.["
|
|
1878
|
+
severity: (0, types_js_1.ruleSeverity)(config?.rules?.["context-creep"]),
|
|
1879
|
+
max: (0, types_js_1.ruleOptions)(config?.rules?.["context-creep"])?.max,
|
|
1869
1880
|
update: flags.includes("--update-baseline"),
|
|
1870
1881
|
silent,
|
|
1871
|
-
measure: () => lintRoots.map((abs) =>
|
|
1872
|
-
frame.bundle(abs).at,
|
|
1873
|
-
(0, scan_js_1.measureInstructionWeight)(abs, adapter),
|
|
1874
|
-
]),
|
|
1882
|
+
measure: () => lintRoots.map((abs) => measuredBundle(frame.bundle(abs).at, abs, adapter)),
|
|
1875
1883
|
annotate: (level, message) => {
|
|
1876
1884
|
ghAnnotate(level, message);
|
|
1877
1885
|
},
|
|
@@ -2033,8 +2041,9 @@ async function runLint(restArgs, flags, excludes, config) {
|
|
|
2033
2041
|
hookBlockErrors: hookBlock.errors,
|
|
2034
2042
|
hookMatcherIssues: hookMatcher.issues,
|
|
2035
2043
|
hookMatcherErrors: hookMatcher.errors,
|
|
2036
|
-
|
|
2037
|
-
|
|
2044
|
+
contextCreepIssues: contextCreep.issues,
|
|
2045
|
+
contextCreepErrors: contextCreep.errors,
|
|
2046
|
+
contextCreepNotes: contextCreep.notes,
|
|
2038
2047
|
deprecatedKeyFilesIssues: deprecatedKeyFiles.issues,
|
|
2039
2048
|
deprecatedKeyFilesErrors: deprecatedKeyFiles.errors,
|
|
2040
2049
|
// Only the "error" tier gates. At "warn" the findings are printed and
|
|
@@ -2117,6 +2126,11 @@ function printLintSummary(report) {
|
|
|
2117
2126
|
else {
|
|
2118
2127
|
console.log(`vigiles: ${parts.join(" / ")}`);
|
|
2119
2128
|
}
|
|
2129
|
+
// One extra line per note, only when there is one: the old baseline file's
|
|
2130
|
+
// rename command reaches the agent through the session-start hook.
|
|
2131
|
+
report.contextCreepNotes.forEach((note) => {
|
|
2132
|
+
console.log(`vigiles: note — ${note}`);
|
|
2133
|
+
});
|
|
2120
2134
|
}
|
|
2121
2135
|
function collectDocumentedRules(excludes) {
|
|
2122
2136
|
const documented = new Set();
|
|
@@ -7479,13 +7493,14 @@ async function main() {
|
|
|
7479
7493
|
(await compile(specs, config, excludes, { harnessFlag })) && valid;
|
|
7480
7494
|
// The always-loaded weight the author just produced, against the
|
|
7481
7495
|
// committed baseline — shown at the moment of change. Report-only:
|
|
7482
|
-
// `lint` is the gate (rule `
|
|
7496
|
+
// `lint` is the gate (rule `context-creep`).
|
|
7483
7497
|
if (specs.length > 0) {
|
|
7484
|
-
const
|
|
7498
|
+
const measured = measuredBundle(".", projectRoot, (0, adapter_registry_js_1.resolveHarnessSelection)({
|
|
7485
7499
|
root: projectRoot,
|
|
7486
7500
|
flag: harnessFlag,
|
|
7487
7501
|
configHarness: (0, adapter_registry_js_1.declaredHarnessNames)(config.harnesses),
|
|
7488
|
-
}).adapter)
|
|
7502
|
+
}).adapter);
|
|
7503
|
+
const weightLine = (0, context_creep_ratchet_js_1.compileWeightLine)(projectRoot, measured);
|
|
7489
7504
|
if (weightLine !== null)
|
|
7490
7505
|
console.log(`\n${weightLine}`);
|
|
7491
7506
|
}
|
|
@@ -1,15 +1,33 @@
|
|
|
1
|
-
import { type InstructionBaseline, type ParsedBaseline } from "./core/instruction-baseline.js";
|
|
1
|
+
import { type InstructionBaseline, type LegacyBaseline, type ParsedBaseline } from "./core/instruction-baseline.js";
|
|
2
|
+
import type { AlwaysLoadedContext } from "./core/always-loaded.js";
|
|
2
3
|
import type { InstructionWeight } from "./core/instruction-weight.js";
|
|
3
4
|
import type { RuleSeverity } from "./core/types.js";
|
|
4
5
|
/** The file on disk, read once: absent, parsed, or refused. */
|
|
5
6
|
export type BaselineOnDisk = {
|
|
6
7
|
readonly kind: "absent";
|
|
7
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;
|
|
8
20
|
export declare function readInstructionBaseline(root: string): BaselineOnDisk;
|
|
9
|
-
/**
|
|
10
|
-
|
|
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 [
|
|
11
28
|
at: string,
|
|
12
|
-
weight: InstructionWeight
|
|
29
|
+
weight: InstructionWeight,
|
|
30
|
+
loaded: AlwaysLoadedContext
|
|
13
31
|
];
|
|
14
32
|
/** Write the baseline for every measured bundle; returns what was written. */
|
|
15
33
|
export declare function writeInstructionBaseline(root: string, onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[]): InstructionBaseline;
|
|
@@ -33,13 +51,13 @@ export interface RatchetLine {
|
|
|
33
51
|
* the file exists: a bundle that appeared after the baseline was recorded is
|
|
34
52
|
* weight nobody signed off on.
|
|
35
53
|
*/
|
|
36
|
-
export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[], max?: number): readonly RatchetLine[];
|
|
54
|
+
export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[], max?: number, source?: BaselineSource): readonly RatchetLine[];
|
|
37
55
|
/**
|
|
38
56
|
* The bundles `--update-baseline` must not record: each one over the ceiling,
|
|
39
57
|
* as the refusal text. Empty when there is no ceiling or nothing exceeds it.
|
|
40
58
|
*/
|
|
41
59
|
export declare function updateRefusals(measured: readonly MeasuredBundle[], max: number | undefined): readonly string[];
|
|
42
|
-
/** The options {@link
|
|
60
|
+
/** The options {@link checkContextCreepRatchet} takes. */
|
|
43
61
|
interface RatchetOptions {
|
|
44
62
|
readonly root: string;
|
|
45
63
|
readonly severity: RuleSeverity;
|
|
@@ -51,16 +69,20 @@ interface RatchetOptions {
|
|
|
51
69
|
readonly measure: () => readonly MeasuredBundle[];
|
|
52
70
|
readonly annotate: (level: "error" | "warning", message: string) => void;
|
|
53
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
|
+
}
|
|
54
79
|
/** Run the ratchet for `lint`: print, annotate, count. */
|
|
55
|
-
export declare function
|
|
56
|
-
issues: number;
|
|
57
|
-
errors: number;
|
|
58
|
-
};
|
|
80
|
+
export declare function checkContextCreepRatchet(opts: RatchetOptions): RatchetResult;
|
|
59
81
|
/**
|
|
60
82
|
* The line `compile` prints after writing instruction files: the weight NOW,
|
|
61
83
|
* against the baseline, at the moment the author changed it. Report-only —
|
|
62
84
|
* `lint` stays the single gate. `null` when there is nothing to weigh.
|
|
63
85
|
*/
|
|
64
|
-
export declare function compileWeightLine(root: string,
|
|
86
|
+
export declare function compileWeightLine(root: string, measured: MeasuredBundle): string | null;
|
|
65
87
|
export {};
|
|
66
|
-
//# sourceMappingURL=
|
|
88
|
+
//# sourceMappingURL=context-creep-ratchet.d.ts.map
|
|
@@ -0,0 +1,270 @@
|
|
|
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
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The ALWAYS-LOADED CONTEXT: everything the harness loads at session start without a
|
|
3
|
+
* decision — the always-loaded instructions, the output style the committed
|
|
4
|
+
* settings select, and the skill listing — summed in the harness's own unit.
|
|
5
|
+
*
|
|
6
|
+
* WHY THE SUM, AND NOT THE INSTRUCTIONS ALONE. `./instruction-weight.ts`
|
|
7
|
+
* explains why a per-FILE weight invites the evasion it is meant to catch: text
|
|
8
|
+
* moved into an always-loaded sibling is still loaded. The output style and the
|
|
9
|
+
* skill listing are always-loaded siblings of the same kind. A section cut
|
|
10
|
+
* from `CLAUDE.md` into the selected style, or into a skill's description,
|
|
11
|
+
* still reaches the model on every request; a weight that counts only the
|
|
12
|
+
* instruction file reads that move as a shrink. The parts are reported one by
|
|
13
|
+
* one so a reader can see WHERE the weight is, and summed so a move between
|
|
14
|
+
* them nets out.
|
|
15
|
+
*
|
|
16
|
+
* WHAT IT IS NOT. It is the part of every request THE REPOSITORY decides, not
|
|
17
|
+
* the size of a request: the harness's own system prompt and tool definitions,
|
|
18
|
+
* user- and plugin-level skills, and the conversation history are added in a
|
|
19
|
+
* real session and are not repository facts. Units are the harness's own
|
|
20
|
+
* (characters for Claude Code, bytes for Codex) and never tokens, for the
|
|
21
|
+
* reason `InstructionBudget.unit` gives.
|
|
22
|
+
*
|
|
23
|
+
* WHAT IS COUNTED, PER PART.
|
|
24
|
+
*
|
|
25
|
+
* - output style: only a style the COMMITTED settings select and the
|
|
26
|
+
* repository holds as a file in the session's own style folder. A style
|
|
27
|
+
* selected in a per-machine settings file is not a property of the commit;
|
|
28
|
+
* a name no repository file declares (a built-in style, or a typo the
|
|
29
|
+
* harness silently resolves to its default) has no size vigiles can read,
|
|
30
|
+
* and is reported by name rather than counted as zero.
|
|
31
|
+
* - skill listing: every skill in the folder a session at the repository
|
|
32
|
+
* root loads (`skillsHome`), at the depths the harness reads there
|
|
33
|
+
* (`SkillDiscovery`: one folder per skill on Claude Code, a recursive walk
|
|
34
|
+
* on Codex), rendered by the harness's own entry format with its
|
|
35
|
+
* per-entry cap. A plugin's `skills/` folder is what the plugin's
|
|
36
|
+
* USERS load, not a session here.
|
|
37
|
+
*
|
|
38
|
+
* Pure: the caller hands in a file map (repo-relative path → text) holding the
|
|
39
|
+
* committed settings, the style files and the SKILL.md files. The CLI reads
|
|
40
|
+
* them from disk; the browser engine passes the tree it fetched.
|
|
41
|
+
*/
|
|
42
|
+
import type { HarnessDialect } from "./dialect.js";
|
|
43
|
+
import { type HarnessUnit } from "./harness-unit.js";
|
|
44
|
+
import { type PluginLayout } from "./layout.js";
|
|
45
|
+
import type { ListedSkill } from "./skill-listing.js";
|
|
46
|
+
/** The parts that join the instructions in the always-loaded context. */
|
|
47
|
+
export type LoadedPartName = "output-style" | "skill-listing";
|
|
48
|
+
/** One file's share of a part, in the harness's unit. */
|
|
49
|
+
export interface LoadedPartFile {
|
|
50
|
+
readonly path: string;
|
|
51
|
+
readonly size: number;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* One part of the always-loaded context. Each absence is its own fact, because each
|
|
55
|
+
* calls for a different reading:
|
|
56
|
+
*
|
|
57
|
+
* - `counted` — the part loads, and this is its size;
|
|
58
|
+
* - `none` — the harness has this part and the repository loads nothing of
|
|
59
|
+
* it (no style selected, no listed skill);
|
|
60
|
+
* - `not-supported` — the harness has no such thing (Codex has no output
|
|
61
|
+
* styles);
|
|
62
|
+
* - `not-modelled` — the adapter does not say how the harness does it, so
|
|
63
|
+
* vigiles cannot measure it; NOT the same as zero;
|
|
64
|
+
* - `unresolved` — a style is selected by a name no repository file
|
|
65
|
+
* declares: a built-in style, or a typo that loads the default.
|
|
66
|
+
*/
|
|
67
|
+
export type LoadedPart = {
|
|
68
|
+
readonly kind: "counted";
|
|
69
|
+
readonly total: number;
|
|
70
|
+
readonly files: readonly LoadedPartFile[];
|
|
71
|
+
} | {
|
|
72
|
+
readonly kind: "none";
|
|
73
|
+
} | {
|
|
74
|
+
readonly kind: "not-supported";
|
|
75
|
+
} | {
|
|
76
|
+
readonly kind: "not-modelled";
|
|
77
|
+
} | {
|
|
78
|
+
readonly kind: "unresolved";
|
|
79
|
+
readonly name: string;
|
|
80
|
+
};
|
|
81
|
+
export interface AlwaysLoadedContext {
|
|
82
|
+
readonly unit: HarnessUnit;
|
|
83
|
+
/** The instructions' committed total — the same number the weight scores. */
|
|
84
|
+
readonly instructions: number;
|
|
85
|
+
readonly outputStyle: LoadedPart;
|
|
86
|
+
readonly skillListing: LoadedPart;
|
|
87
|
+
/** Instructions plus every `counted` part. */
|
|
88
|
+
readonly total: number;
|
|
89
|
+
}
|
|
90
|
+
type AlwaysLoadedLayout = Pick<PluginLayout, "outputStyles" | "userSurfaceRoot" | "surfaces" | "skillDiscovery" | "settings" | "settingsPath">;
|
|
91
|
+
/** The instructions' weight, as `weighInstructions` measured it. */
|
|
92
|
+
export interface WeighedInstructions {
|
|
93
|
+
readonly unit: HarnessUnit;
|
|
94
|
+
/** The SCORED total — what a teammate on the same commit also loads. */
|
|
95
|
+
readonly committedTotal: number;
|
|
96
|
+
}
|
|
97
|
+
export interface AlwaysLoadedInput {
|
|
98
|
+
readonly weight: WeighedInstructions;
|
|
99
|
+
readonly files: Readonly<Record<string, string>>;
|
|
100
|
+
readonly layout: AlwaysLoadedLayout;
|
|
101
|
+
readonly dialect: Pick<HarnessDialect, "skillListing">;
|
|
102
|
+
}
|
|
103
|
+
/** What one part is measured from: the input, in the weight's unit. */
|
|
104
|
+
export interface LoadedPartInput {
|
|
105
|
+
readonly files: Readonly<Record<string, string>>;
|
|
106
|
+
readonly layout: AlwaysLoadedLayout;
|
|
107
|
+
readonly dialect: Pick<HarnessDialect, "skillListing">;
|
|
108
|
+
readonly unit: HarnessUnit;
|
|
109
|
+
}
|
|
110
|
+
/** The selected output style's part. */
|
|
111
|
+
export declare function outputStylePart(input: LoadedPartInput, settings: Readonly<Record<string, unknown>>): LoadedPart;
|
|
112
|
+
/**
|
|
113
|
+
* Every SKILL.md the session's skills folder holds at a depth the harness
|
|
114
|
+
* reads ({@link skillDiscoveryOf}), read once.
|
|
115
|
+
*/
|
|
116
|
+
export declare function sessionSkills(layout: AlwaysLoadedLayout, files: Readonly<Record<string, string>>): readonly ListedSkill[];
|
|
117
|
+
/** The skill listing's part: each listed skill's entry, sized. */
|
|
118
|
+
export declare function skillListingPart(input: LoadedPartInput, settings: Readonly<Record<string, unknown>>): LoadedPart;
|
|
119
|
+
/** The size a part adds to the sum: its total when counted, else nothing. */
|
|
120
|
+
export declare const partTotal: (part: LoadedPart) => number;
|
|
121
|
+
/**
|
|
122
|
+
* Weigh the always-loaded context: the instructions' committed total (already
|
|
123
|
+
* measured by the instruction weight) plus the selected output style and the
|
|
124
|
+
* skill listing, each in the same unit by the same `sizeIn`.
|
|
125
|
+
*/
|
|
126
|
+
export declare function weighAlwaysLoaded(input: AlwaysLoadedInput): AlwaysLoadedContext;
|
|
127
|
+
export {};
|
|
128
|
+
//# sourceMappingURL=always-loaded.d.ts.map
|