vigiles 38.0.0 → 38.2.0

package/dist/core/keyfiles-source.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findKeyFilesInSpecSource = findKeyFilesInSpecSource;
+/**
+ * Reads `keyFiles` out of an instruction spec's SOURCE, without running it.
+ *
+ * `lint` and `audit` both report the deprecated field (`deprecated-key-files`),
+ * and neither may import a spec: `audit` is a side-effect-free read, and a spec
+ * is the user's program. So the source is PARSED (TypeScript syntax tree) and
+ * the field is read off the tree — a `keyFiles` inside a comment or a string is
+ * not usage, and a text search could not tell the difference.
+ *
+ * Pure: the file walk that feeds it is `src/deprecated-key-files.ts`.
+ */
+const typescript_1 = __importDefault(require("typescript"));
+const keyfiles_js_1 = require("./keyfiles.js");
+/** Field used, size not knowable from the syntax alone. */
+const UNMEASURED = (entries) => ({
+    entries,
+    chars: 0,
+    measured: false,
+});
+/** A literal key or value: `"a"`, `'a'`, `` `a` `` (and, for a key only, `a`). */
+function literalText(node) {
+    return typescript_1.default.isStringLiteral(node) || typescript_1.default.isNoSubstitutionTemplateLiteral(node)
+        ? node.text
+        : undefined;
+}
+/** One `path: "description"` pair, or `undefined` when either side is not literal. */
+function literalEntry(prop) {
+    if (!typescript_1.default.isPropertyAssignment(prop))
+        return undefined;
+    const key = typescript_1.default.isIdentifier(prop.name)
+        ? prop.name.text
+        : literalText(prop.name);
+    const value = literalText(prop.initializer);
+    return key === undefined || value === undefined ? undefined : [key, value];
+}
+/**
+ * Read a `{ path: "description" }` object literal. A computed key or value, or a
+ * spread, makes the map unmeasurable: its pairs are still counted (each one
+ * compiles to a line), its size is not guessed.
+ */
+function measureLiteral(obj) {
+    const pairs = obj.properties.filter(typescript_1.default.isPropertyAssignment);
+    const literal = obj.properties
+        .map(literalEntry)
+        .filter((e) => e !== undefined);
+    return literal.length === obj.properties.length
+        ? (0, keyfiles_js_1.measureKeyFiles)(Object.fromEntries(literal))
+        : UNMEASURED(pairs.length);
+}
+/** The usage a node declares, if it is a `keyFiles` property. */
+function usageAt(node) {
+    if (typescript_1.default.isShorthandPropertyAssignment(node))
+        return node.name.text === "keyFiles" ? UNMEASURED(0) : undefined;
+    if (!typescript_1.default.isPropertyAssignment(node))
+        return undefined;
+    const name = typescript_1.default.isIdentifier(node.name)
+        ? node.name.text
+        : literalText(node.name);
+    if (name !== "keyFiles")
+        return undefined;
+    return typescript_1.default.isObjectLiteralExpression(node.initializer)
+        ? measureLiteral(node.initializer)
+        : UNMEASURED(0);
+}
+/** Depth-first: the first `keyFiles` property under `node`. */
+function firstUsage(node) {
+    return (usageAt(node) ??
+        typescript_1.default.forEachChild(node, (child) => firstUsage(child)) ??
+        undefined);
+}
+/**
+ * The `keyFiles` usage in one spec's source, or `null` when the spec does not
+ * use the field. The first `keyFiles:` property in any object literal counts —
+ * an instruction spec has one builder call, and nothing else in a spec is
+ * called that.
+ */
+function findKeyFilesInSpecSource(source) {
+    const sf = typescript_1.default.createSourceFile("spec.ts", source, typescript_1.default.ScriptTarget.Latest, 
+    /* setParentNodes */ false, typescript_1.default.ScriptKind.TS);
+    return firstUsage(sf) ?? null;
+}
+//# sourceMappingURL=keyfiles-source.js.map

package/dist/core/keyfiles.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `keyFiles` — DEPRECATED, removed in the major after the one that ships this
+ * notice (the one-major alias window in `core/spec.ts`).
+ *
+ * WHY. The field compiles a flat "## Key Files" path → description list into
+ * the instruction file the harness loads on EVERY request. Measured on this
+ * repository's own root spec (2026-10-11): 230 entries, 45,467 characters —
+ * 29% of a 157,872-character file, paid on every request, to tell an agent where files are
+ * when it finds them itself with Glob/Grep. Anthropic's own guidance lists
+ * "File-by-file descriptions of the codebase" under what to EXCLUDE from
+ * `CLAUDE.md` (https://code.claude.com/docs/en/best-practices).
+ *
+ * THE REPLACEMENT, decided per entry, in this order:
+ * - the file's own header, the docs or the path already say it → delete it;
+ * - a fact about that one file, written nowhere else → that file's header
+ *   comment, where a reader meets it on opening the file;
+ * - a rule an agent must follow while working in one folder → that folder's
+ *   nested instruction file (`<folder>/CLAUDE.md` from its own spec), which
+ *   loads only when the agent works there;
+ * - only when nothing else would lead an agent to the file → a one-line
+ *   `file()` pointer where the decision that needs it is written (verified
+ *   exactly like a `keyFiles` path, by `validateFileRef`).
+ *
+ * This module is pure: the renderer `compile` uses, the measurement the
+ * `deprecated-key-files` rule reports, and its message — one wording for lint
+ * and audit.
+ */
+/** Where the migration is written up. Printed in every finding. */
+export declare const KEYFILES_DOCS_URL = "https://github.com/zernie/vigiles/blob/main/docs/rules/deprecated-key-files.md";
+/**
+ * The compiled "## Key Files" section — the ONE renderer, so the size a
+ * finding reports is the size of what actually loads.
+ */
+export declare function renderKeyFiles(keyFiles: Readonly<Record<string, string>>): string;
+/**
+ * What a spec's `keyFiles` costs. `measured: false` when the map is not a
+ * literal (a variable, a computed key or value, a spread) — then the field is
+ * known to be USED and its size is not guessed.
+ */
+export interface KeyFilesUsage {
+    readonly entries: number;
+    readonly chars: number;
+    readonly measured: boolean;
+}
+/** Measure a map the way it compiles. */
+export declare function measureKeyFiles(keyFiles: Readonly<Record<string, string>>): KeyFilesUsage;
+/** The cost half of a finding, e.g. `230 entries, 45,467 characters compiled into …`. */
+export declare function keyFilesCost(u: KeyFilesUsage): string;
+/**
+ * The instruction file a spec compiles to — `pkg/AGENTS.md.spec.ts` →
+ * `AGENTS.md` — so the fix names the nested file in the reader's own harness
+ * instead of assuming one.
+ */
+export declare function instructionFileOfSpec(specPath: string): string;
+/**
+ * The fix, one sentence — shared by the lint message and the audit line. The
+ * four places an entry can go, in the order to try them; the full recipe is
+ * the migration guide. `targets` are the instruction files the reported specs
+ * compile to (`CLAUDE.md`, `AGENTS.md`), so the nested file is named for real.
+ */
+export declare function keyFilesFix(targets: readonly string[]): string;
+/** The whole finding: what it costs, then where each entry goes and where it is written up. */
+export declare function keyFilesDeprecationMessage(u: KeyFilesUsage, target: string): string;
+//# sourceMappingURL=keyfiles.d.ts.map

package/dist/core/keyfiles.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * `keyFiles` — DEPRECATED, removed in the major after the one that ships this
+ * notice (the one-major alias window in `core/spec.ts`).
+ *
+ * WHY. The field compiles a flat "## Key Files" path → description list into
+ * the instruction file the harness loads on EVERY request. Measured on this
+ * repository's own root spec (2026-10-11): 230 entries, 45,467 characters —
+ * 29% of a 157,872-character file, paid on every request, to tell an agent where files are
+ * when it finds them itself with Glob/Grep. Anthropic's own guidance lists
+ * "File-by-file descriptions of the codebase" under what to EXCLUDE from
+ * `CLAUDE.md` (https://code.claude.com/docs/en/best-practices).
+ *
+ * THE REPLACEMENT, decided per entry, in this order:
+ * - the file's own header, the docs or the path already say it → delete it;
+ * - a fact about that one file, written nowhere else → that file's header
+ *   comment, where a reader meets it on opening the file;
+ * - a rule an agent must follow while working in one folder → that folder's
+ *   nested instruction file (`<folder>/CLAUDE.md` from its own spec), which
+ *   loads only when the agent works there;
+ * - only when nothing else would lead an agent to the file → a one-line
+ *   `file()` pointer where the decision that needs it is written (verified
+ *   exactly like a `keyFiles` path, by `validateFileRef`).
+ *
+ * This module is pure: the renderer `compile` uses, the measurement the
+ * `deprecated-key-files` rule reports, and its message — one wording for lint
+ * and audit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEYFILES_DOCS_URL = void 0;
+exports.renderKeyFiles = renderKeyFiles;
+exports.measureKeyFiles = measureKeyFiles;
+exports.keyFilesCost = keyFilesCost;
+exports.instructionFileOfSpec = instructionFileOfSpec;
+exports.keyFilesFix = keyFilesFix;
+exports.keyFilesDeprecationMessage = keyFilesDeprecationMessage;
+/** Where the migration is written up. Printed in every finding. */
+exports.KEYFILES_DOCS_URL = "https://github.com/zernie/vigiles/blob/main/docs/rules/deprecated-key-files.md";
+/**
+ * The compiled "## Key Files" section — the ONE renderer, so the size a
+ * finding reports is the size of what actually loads.
+ */
+function renderKeyFiles(keyFiles) {
+    return [
+        "## Key Files",
+        "",
+        ...Object.entries(keyFiles).map(([path, desc]) => `- \`${path}\` — ${desc}`),
+    ].join("\n");
+}
+/** Measure a map the way it compiles. */
+function measureKeyFiles(keyFiles) {
+    return {
+        entries: Object.keys(keyFiles).length,
+        chars: renderKeyFiles(keyFiles).length,
+        measured: true,
+    };
+}
+const grouped = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/** The cost half of a finding, e.g. `230 entries, 45,467 characters compiled into …`. */
+function keyFilesCost(u) {
+    if (!u.measured)
+        return "not a literal map — size not measured";
+    const noun = u.entries === 1 ? "entry" : "entries";
+    return `${String(u.entries)} ${noun}, ${grouped(u.chars)} characters compiled into the instruction file`;
+}
+/**
+ * The instruction file a spec compiles to — `pkg/AGENTS.md.spec.ts` →
+ * `AGENTS.md` — so the fix names the nested file in the reader's own harness
+ * instead of assuming one.
+ */
+function instructionFileOfSpec(specPath) {
+    return specPath.replace(/^.*[\\/]/, "").replace(/\.spec\.ts$/, "");
+}
+/**
+ * The fix, one sentence — shared by the lint message and the audit line. The
+ * four places an entry can go, in the order to try them; the full recipe is
+ * the migration guide. `targets` are the instruction files the reported specs
+ * compile to (`CLAUDE.md`, `AGENTS.md`), so the nested file is named for real.
+ */
+function keyFilesFix(targets) {
+    // In the order given — the detector sorts findings by path — once each.
+    const nested = Array.from(new Set(targets), (t) => `<folder>/${t}`).join(" or ");
+    return ("For each entry: delete it if the file or the docs already say it · " +
+        "move a fact about one file into that file's header comment · " +
+        `move a rule for one folder into ${nested} · ` +
+        "keep a one-line file() pointer only if nothing else leads there");
+}
+/** The whole finding: what it costs, then where each entry goes and where it is written up. */
+function keyFilesDeprecationMessage(u, target) {
+    return (`\`keyFiles\` is deprecated and goes away in the next major (${keyFilesCost(u)}). ` +
+        `${keyFilesFix([target])} (guide: ${exports.KEYFILES_DOCS_URL})`);
+}
+//# sourceMappingURL=keyfiles.js.map

package/dist/core/orphans.js

@@ -217,7 +217,7 @@ function formatOrphanReport(report) {
     ];
     for (const o of report.orphans)
         lines.push(`    ${o}`);
-    lines.push("  Fix: link each from another .md (README, a spec's Key Files, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  exclude it via .vigilesrc.json → `orphans.exclude` (or narrow `orphans.include`).");
+    lines.push("  Fix: link each from another .md (README, an instruction file, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  exclude it via .vigilesrc.json → `orphans.exclude` (or narrow `orphans.include`).");
     return lines.join("\n");
 }
 //# sourceMappingURL=orphans.js.map

package/dist/core/rule-meta.js

@@ -238,6 +238,15 @@ exports.RULE_META = {
         detector: "checkContentBudgets",
         upstreamPrevention: "compile measures the spec before writing; a render policy (enforce render, guidance details) meets a budget without deleting a rule",
     },
+    "deprecated-key-files": {
+        id: "deprecated-key-files",
+        bucket: "structural-closed",
+        surface: ["instruction"],
+        defaultSeverity: "warn",
+        summary: "An instruction spec doesn't use the deprecated keyFiles (always-loaded file map).",
+        detector: "findDeprecatedKeyFiles",
+        upstreamPrevention: "the @deprecated keyFiles field is removed next major",
+    },
     "skill-description-budget": {
         id: "skill-description-budget",
         bucket: "heuristic-behavioral",

package/dist/core/session.d.ts

@@ -57,6 +57,13 @@ export declare function loadSpecSurface(basePath: string): SpecSurface;
 /**
  * Load keyFiles from compiled markdown files. Reads each target's
  * "## Key Files" section and extracts the file paths.
+ *
+ * @deprecated Goes away together with the deprecated `keyFiles` spec field (see
+ * the `deprecated-key-files` rule), in the major after the one that deprecates
+ * it. It reads the field back out of COMPILED markdown with a regex rather than
+ * from the spec, and it is deliberately not ported in the release that
+ * deprecates the field: with the field gone, the session audit's "files the
+ * specs know about" is `surface.trackedInputs` (the sidecar manifests) alone.
  */
 export declare function loadKeyFilesFromSpecs(basePath: string): Set<string>;
 /** A finding about a file not tracked by any spec. */

package/dist/core/session.js

@@ -143,6 +143,13 @@ function loadSpecSurface(basePath) {
 /**
  * Load keyFiles from compiled markdown files. Reads each target's
  * "## Key Files" section and extracts the file paths.
+ *
+ * @deprecated Goes away together with the deprecated `keyFiles` spec field (see
+ * the `deprecated-key-files` rule), in the major after the one that deprecates
+ * it. It reads the field back out of COMPILED markdown with a regex rather than
+ * from the spec, and it is deliberately not ported in the release that
+ * deprecates the field: with the field gone, the session audit's "files the
+ * specs know about" is `surface.trackedInputs` (the sidecar manifests) alone.
  */
 function loadKeyFilesFromSpecs(basePath) {
     const keyFiles = new Set();
@@ -175,6 +182,7 @@ function loadKeyFilesFromSpecs(basePath) {
 function analyzeSession(basePath, baseRef) {
     const changedFiles = gitChangedFiles(basePath, baseRef);
     const surface = loadSpecSurface(basePath);
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- keyFiles is deprecated, not removed: it still compiles until the next major, and this reads it back until then
     const keyFiles = loadKeyFilesFromSpecs(basePath);
     const trackedChanges = [];
     const untrackedChanges = [];

package/dist/core/spec.d.ts

@@ -352,7 +352,19 @@ export interface ClaudeSpec {
     readonly target?: InstructionTarget | InstructionTarget[];
     /** npm scripts / shell commands → descriptions. Verified against package.json. */
     readonly commands?: Record<string, string>;
-    /** File paths → descriptions. Verified via existsSync. */
+    /**
+     * File paths → descriptions, compiled into a "## Key Files" list. Verified via existsSync.
+     *
+     * @deprecated Move each entry out, then remove `keyFiles`. The list loads
+     * on every request to tell the agent where files are, which it finds itself.
+     * For each entry: delete it if the file or the docs already say it; move a
+     * fact about one file into that file's header comment; move a rule for one
+     * folder into that folder's nested instruction file; keep a one-line
+     * `file()` pointer (verified the same way) only if nothing else leads there.
+     * Still compiled for one major — the one that ships this notice — and
+     * removed in the major after it; `vigiles lint` reports every use as
+     * `deprecated-key-files`. Migration: docs/rules/deprecated-key-files.md.
+     */
     readonly keyFiles?: Record<string, string>;
     /** Named prose sections — plain strings or tagged templates with file()/cmd()/ref(). */
     readonly sections?: Record<string, string | InstructionFragment[]>;
@@ -379,6 +391,7 @@ export interface ClaudeSpec {
 type ClaudeSpecBase = {
     readonly target?: InstructionTarget | InstructionTarget[];
     readonly commands?: Record<string, string>;
+    /** @deprecated Move each entry out, then remove `keyFiles` — see {@link ClaudeSpec.keyFiles}. Removed in the major after the one that deprecates it. */
     readonly keyFiles?: Record<string, string>;
     readonly maxTokens?: number;
     readonly rules: Record<string, Rule>;

package/dist/core/types.d.ts

@@ -55,6 +55,19 @@ export interface CoverageThresholds {
     /** Min % of npm scripts documented in spec commands. */
     scripts?: number;
 }
+/**
+ * Options for the `instruction-weight` rule: `["error", { max: 40000 }]`.
+ */
+export interface InstructionWeightConfig {
+    /**
+     * An opt-in ABSOLUTE ceiling on the always-loaded instruction weight, in the
+     * harness's own unit (characters for Claude Code, bytes for Codex). A total
+     * above it is a finding at the rule's severity regardless of the baseline, and
+     * `vigiles lint --update-baseline` refuses to record a baseline above it.
+     * Omitted → only the ratchet applies. A positive integer.
+     */
+    max?: number;
+}
 /**
  * Options for the orphan-docs check. The PRESENCE of this block in
  * `.vigilesrc.json` OPTS THE REPO IN — the scan is off unless declared,
@@ -140,8 +153,20 @@ export interface RulesConfig {
      * repo's own past, not a fixed budget. No baseline file → a one-line note,
      * never a finding, so turning this on fails no repository on day one.
      * `vigiles lint --update-baseline` records it. Default: "error".
+     *
+     * `["error", { max: 40000 }]` adds an opt-in absolute ceiling on top of the
+     * ratchet: a total above `max` is a finding whatever the baseline says, and
+     * the baseline cannot be re-recorded above it.
+     */
+    "instruction-weight"?: RuleWithOptions<InstructionWeightConfig>;
+    /**
+     * An instruction spec still uses the deprecated `keyFiles` field — a flat
+     * path → description list compiled into the file loaded on every request.
+     * Reports the entry count and compiled size with the migration (a `file()`
+     * ref in the rule that needs the pointer). The spec is parsed, never run.
+     * Default "warn": a deprecation must not turn a consumer's CI red on upgrade.
      */
-    "instruction-weight"?: RuleSeverity;
+    "deprecated-key-files"?: RuleSeverity;
     /**
      * Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
      * rules saying the same thing in different words.

package/dist/deprecated-key-files.d.ts

@@ -0,0 +1,35 @@
+import { type KeyFilesUsage } from "./core/keyfiles.js";
+import type { RuleSeverity } from "./core/types.js";
+/** One spec still using `keyFiles`, relative to the directory searched. */
+export interface DeprecatedKeyFilesFinding extends KeyFilesUsage {
+    readonly path: string;
+}
+/**
+ * The detector: of the given instruction specs, the ones still using
+ * `keyFiles`, sorted by path. The file walk and the reads are the caller's
+ * (the composition root), so this stays free of I/O.
+ */
+export declare function findDeprecatedKeyFiles(io: {
+    /** Instruction specs (`**\/*.md.spec.ts`, the glob `compile` uses), relative paths. */
+    readonly specPaths: readonly string[];
+    readonly read: (path: string) => string;
+}): readonly DeprecatedKeyFilesFinding[];
+/**
+ * `lint`'s side of the rule. Runs ONCE over the repository, like the
+ * instruction-weight ratchet: a nested bundle's spec would otherwise be
+ * reported again by every bundle that encloses it. Warning by default — a
+ * deprecation that gated would turn a consumer's CI red on upgrade, which the
+ * one-major window exists to prevent.
+ */
+export declare function checkDeprecatedKeyFiles(opts: {
+    readonly severity: RuleSeverity;
+    /** Called only when the rule is on. */
+    readonly find: () => readonly DeprecatedKeyFilesFinding[];
+    readonly silent: boolean;
+    /** One per finding, with the spec's path relative to `root`. */
+    readonly annotate: (level: "error" | "warning", message: string, path: string) => void;
+}): {
+    readonly issues: number;
+    readonly errors: number;
+};
+//# sourceMappingURL=deprecated-key-files.d.ts.map

package/dist/deprecated-key-files.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findDeprecatedKeyFiles = findDeprecatedKeyFiles;
+exports.checkDeprecatedKeyFiles = checkDeprecatedKeyFiles;
+/**
+ * The `deprecated-key-files` rule: every instruction spec that still uses the
+ * deprecated `keyFiles` field. ONE detector, two readers — `lint` (this file's
+ * `checkDeprecatedKeyFiles`) and `audit` (`scanPlugin`'s `deprecatedKeyFiles`)
+ * both call {@link findDeprecatedKeyFiles}, so they cannot disagree.
+ *
+ * The decisions — what a spec's `keyFiles` costs, what the finding says — are
+ * pure and live in `core/keyfiles.ts` / `core/keyfiles-source.ts`; this module
+ * owns what is left: matching specs to findings and printing them. The
+ * effects — walking the repository and reading files — happen in the composition root (`cli-main.ts`,
+ * `specsUsingKeyFiles`) and are handed in. Migration guide:
+ * docs/rules/deprecated-key-files.md.
+ */
+const keyfiles_source_js_1 = require("./core/keyfiles-source.js");
+const keyfiles_js_1 = require("./core/keyfiles.js");
+/**
+ * The detector: of the given instruction specs, the ones still using
+ * `keyFiles`, sorted by path. The file walk and the reads are the caller's
+ * (the composition root), so this stays free of I/O.
+ */
+function findDeprecatedKeyFiles(io) {
+    return [...io.specPaths].sort().flatMap((path) => {
+        const usage = (0, keyfiles_source_js_1.findKeyFilesInSpecSource)(io.read(path));
+        return usage === null ? [] : [{ path, ...usage }];
+    });
+}
+/** The lint message, naming the nested file after the spec's own target. */
+const messageFor = (f) => (0, keyfiles_js_1.keyFilesDeprecationMessage)(f, (0, keyfiles_js_1.instructionFileOfSpec)(f.path));
+/**
+ * `lint`'s side of the rule. Runs ONCE over the repository, like the
+ * instruction-weight ratchet: a nested bundle's spec would otherwise be
+ * reported again by every bundle that encloses it. Warning by default — a
+ * deprecation that gated would turn a consumer's CI red on upgrade, which the
+ * one-major window exists to prevent.
+ */
+function checkDeprecatedKeyFiles(opts) {
+    const { severity } = opts;
+    if (!severity)
+        return { issues: 0, errors: 0 };
+    const found = opts.find();
+    const mark = severity === "error" ? "✗" : "⚠";
+    const level = severity === "error" ? "error" : "warning";
+    if (!opts.silent && found.length > 0)
+        console.log("\nDeprecated-key-files check:\n");
+    // Silent (`--json`, `--summary`) prints nothing at all, annotations
+    // included: they go to stdout and would corrupt the JSON.
+    if (!opts.silent)
+        found.forEach((f) => {
+            const message = messageFor(f);
+            console.log(`  ${mark} ${f.path}: ${message}`);
+            opts.annotate(level, message, f.path);
+        });
+    return {
+        issues: found.length,
+        errors: severity === "error" ? found.length : 0,
+    };
+}
+//# sourceMappingURL=deprecated-key-files.js.map

package/dist/instruction-weight-ratchet.d.ts

@@ -24,23 +24,35 @@ export interface RatchetLine {
 }
 /**
  * Pure: the lines a run prints, given what was measured and what is on disk.
+ * `max` is the opt-in absolute ceiling; a bundle over it adds a finding of its
+ * own, whatever the baseline says (including when there is none, or it is
+ * unreadable).
  *
  * A bundle with no entry is a nudge while the repo has NO baseline file (it has
  * not opted in, and a fresh repo must not fail on day one) — but a FINDING once
  * the file exists: a bundle that appeared after the baseline was recorded is
  * weight nobody signed off on.
  */
-export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[]): readonly RatchetLine[];
-/** Run the ratchet for `lint`: print, annotate, count. */
-export declare function checkInstructionWeightRatchet(opts: {
+export declare function ratchetLines(onDisk: BaselineOnDisk, measured: readonly MeasuredBundle[], max?: number): readonly RatchetLine[];
+/**
+ * The bundles `--update-baseline` must not record: each one over the ceiling,
+ * as the refusal text. Empty when there is no ceiling or nothing exceeds it.
+ */
+export declare function updateRefusals(measured: readonly MeasuredBundle[], max: number | undefined): readonly string[];
+/** The options {@link checkInstructionWeightRatchet} takes. */
+interface RatchetOptions {
     readonly root: string;
     readonly severity: RuleSeverity;
+    /** The opt-in absolute ceiling (`["error", { max }]`); `undefined` = ratchet only. */
+    readonly max?: number;
     readonly update: boolean;
     readonly silent: boolean;
     /** Called only when the rule is on or an update was asked for. */
     readonly measure: () => readonly MeasuredBundle[];
     readonly annotate: (level: "error" | "warning", message: string) => void;
-}): {
+}
+/** Run the ratchet for `lint`: print, annotate, count. */
+export declare function checkInstructionWeightRatchet(opts: RatchetOptions): {
     issues: number;
     errors: number;
 };
@@ -50,4 +62,5 @@ export declare function checkInstructionWeightRatchet(opts: {
  * `lint` stays the single gate. `null` when there is nothing to weigh.
  */
 export declare function compileWeightLine(root: string, weight: InstructionWeight | null): string | null;
+export {};
 //# sourceMappingURL=instruction-weight-ratchet.d.ts.map

package/dist/instruction-weight-ratchet.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readInstructionBaseline = readInstructionBaseline;
 exports.writeInstructionBaseline = writeInstructionBaseline;
 exports.ratchetLines = ratchetLines;
+exports.updateRefusals = updateRefusals;
 exports.checkInstructionWeightRatchet = checkInstructionWeightRatchet;
 exports.compileWeightLine = compileWeightLine;
 /**
@@ -41,13 +42,29 @@ function writeInstructionBaseline(root, onDisk, measured) {
 }
 /**
  * Pure: the lines a run prints, given what was measured and what is on disk.
+ * `max` is the opt-in absolute ceiling; a bundle over it adds a finding of its
+ * own, whatever the baseline says (including when there is none, or it is
+ * unreadable).
  *
  * A bundle with no entry is a nudge while the repo has NO baseline file (it has
  * not opted in, and a fresh repo must not fail on day one) — but a FINDING once
  * the file exists: a bundle that appeared after the baseline was recorded is
  * weight nobody signed off on.
  */
-function ratchetLines(onDisk, measured) {
+function ratchetLines(onDisk, measured, max) {
+    return [
+        ...baselineLines(onDisk, measured),
+        ...measured.flatMap(([at, weight]) => ceilingLine(at, weight, max)),
+    ];
+}
+/** One bundle's ceiling finding, or nothing when it is at or under `max`. */
+function ceilingLine(at, weight, max) {
+    const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
+    return over === undefined
+        ? []
+        : [{ at, status: "finding", text: (0, instruction_baseline_js_1.formatCeiling)(over, at) }];
+}
+function baselineLines(onDisk, measured) {
     if (onDisk.kind === "invalid") {
         return [
             {
@@ -77,41 +94,73 @@ function ratchetLines(onDisk, measured) {
         return [{ at, status, text: `${(0, instruction_baseline_js_1.formatVerdict)(verdict, at)}${unfollowed}` }];
     });
 }
+/**
+ * The bundles `--update-baseline` must not record: each one over the ceiling,
+ * as the refusal text. Empty when there is no ceiling or nothing exceeds it.
+ */
+function updateRefusals(measured, max) {
+    return measured.flatMap(([at, weight]) => {
+        const over = weight === null ? undefined : (0, instruction_baseline_js_1.checkCeiling)(weight, max);
+        return over === undefined ? [] : [(0, instruction_baseline_js_1.formatRefusal)(over, at)];
+    });
+}
+/**
+ * What `lint` compares against: the file as it is, or — under `--update-baseline`
+ * and when nothing is over the ceiling — the file just written. A baseline above
+ * the ceiling would bypass it (re-recording is how a ratchet gets loosened), so
+ * then nothing is written and the refusals are returned for the caller to fail on.
+ */
+function recordOrRead(opts, measured) {
+    const before = readInstructionBaseline(opts.root);
+    const refusals = opts.update ? updateRefusals(measured, opts.max) : [];
+    const record = opts.update && refusals.length === 0;
+    return {
+        refusals,
+        onDisk: record
+            ? {
+                kind: "ok",
+                baseline: writeInstructionBaseline(opts.root, before, measured),
+            }
+            : before,
+    };
+}
+/** The human-readable report: what was recorded, then one line per bundle. */
+function printReport(lines, severity, recorded) {
+    console.log("\nInstruction-weight ratchet:\n");
+    if (recorded)
+        console.log(`  ✓ recorded ${instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE}`);
+    const marks = {
+        finding: severity === "error" ? "✗" : "⚠",
+        ok: "✓",
+        note: "ℹ",
+    };
+    lines.forEach((l) => {
+        console.log(`  ${marks[l.status]} ${l.text}`);
+    });
+}
 /** Run the ratchet for `lint`: print, annotate, count. */
 function checkInstructionWeightRatchet(opts) {
     const { severity, update, silent } = opts;
     if (!severity && !update)
         return { issues: 0, errors: 0 };
     const measured = opts.measure();
-    const before = readInstructionBaseline(opts.root);
-    const onDisk = update
-        ? {
-            kind: "ok",
-            baseline: writeInstructionBaseline(opts.root, before, measured),
-        }
-        : before;
-    const lines = severity ? ratchetLines(onDisk, measured) : [];
+    const { onDisk, refusals } = recordOrRead(opts, measured);
+    refusals.forEach((message) => {
+        console.error(`✗ ${message}`);
+        opts.annotate("error", message);
+    });
+    const lines = severity ? ratchetLines(onDisk, measured, opts.max) : [];
     const findings = lines.filter((l) => l.status === "finding");
     if (!silent && (update || lines.length > 0)) {
-        console.log("\nInstruction-weight ratchet:\n");
-        if (update)
-            console.log(`  ✓ recorded ${instruction_baseline_js_1.INSTRUCTION_BASELINE_FILE}`);
-        const marks = {
-            finding: severity === "error" ? "✗" : "⚠",
-            ok: "✓",
-            note: "ℹ",
-        };
-        lines.forEach((l) => {
-            console.log(`  ${marks[l.status]} ${l.text}`);
-        });
+        printReport(lines, severity, update && refusals.length === 0);
     }
     const level = severity === "error" ? "error" : "warning";
     findings.forEach((l) => {
         opts.annotate(level, l.text);
     });
     return {
-        issues: findings.length,
-        errors: severity === "error" ? findings.length : 0,
+        issues: findings.length + refusals.length,
+        errors: (severity === "error" ? findings.length : 0) + refusals.length,
     };
 }
 /**