cachelint 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1200 @@
+import { z } from 'zod';
+
+/**
+ * Versioned constants pinned in `cachelint.lock`.
+ *
+ * Bumping any of these means a previously-committed lock will be reported
+ * by `cachelint check` as "rules-moved" (exit code 1) with a specific
+ * upgrade message — never a generic diff. See docs/determinism-contract.md.
+ */
+/** The published npm version of cachelint. */
+declare const CACHELINT_VERSION: string;
+/**
+ * Version of the lockfile's normalization rules (BOM strip, CRLF→LF,
+ * trailing-newline policy, sorted-by-codepoint JSON keys, ASCII-only escape).
+ * Bump only when a deliberate, documented behavior change ships.
+ */
+declare const NORMALIZATION_POLICY_VERSION: 1;
+/**
+ * Version of the rule table (which rules ship, which severities they default
+ * to). Adding a new rule WITHOUT changing existing rule outputs does not
+ * require a bump; changing what an existing rule flags does.
+ */
+declare const RULE_TABLE_VERSION: 1;
+/**
+ * Version of the cost model (volatility classes, from-here/chars-per-token
+ * formula, earliest-divergence aggregation, cache-engagement semantics).
+ * Bump when the cost *formula* or engagement semantics change — NOT for
+ * price-data updates, which bump the pricing table's own
+ * `PRICING_TABLE_VERSION` / `PRICING_AS_OF` in `src/cost/pricing.ts` instead.
+ */
+declare const COST_MODEL_VERSION: 1;
+
+/**
+ * The canonical MVP rule-id list and severity vocabulary.
+ *
+ * Kept in its own tiny module so `src/config/schema.ts` (Unit 2B) can validate
+ * config keys against it without importing the rule implementations (Unit 2C),
+ * which pull in `acorn` and other heavier deps. Unit 2C's `src/rules/index.ts`
+ * imports this list and asserts each rule registers under one of these ids.
+ *
+ * R006 / R007 are deferred to v0.2 (see the plan's Scope Boundaries) and are
+ * intentionally NOT here yet: a config that names `R006` should fail with the
+ * "unknown rule id" message until the rule actually ships.
+ */
+/** Every rule id the MVP knows about. Order is the documented display order. */
+declare const RULE_IDS: readonly ["R001", "R002", "R003", "R004", "R005"];
+/** A known rule id. */
+type RuleId = (typeof RULE_IDS)[number];
+/** Default severity for each MVP rule (the "rule table", versioned via RULE_TABLE_VERSION). */
+declare const DEFAULT_RULE_SEVERITY: Readonly<Record<RuleId, "error" | "warn">>;
+/**
+ * How a finding's bytes move over time — the cost model's classification.
+ *
+ *   - `"per-call"`: the offending value differs on every API call (interpolated
+ *     timestamp, fresh UUID) → every call from the finding onward misses the
+ *     cache; priced in dollars per 1,000 calls.
+ *   - `"regeneration"`: the bytes are identical call-to-call and only change
+ *     when the file is regenerated/edited (hardcoded timestamp, BOM, line
+ *     endings) → reported as "tokens at risk", never given a dollar figure
+ *     (conservative — see docs/cost-model.md, Unit 6).
+ */
+type Volatility = "per-call" | "regeneration";
+/**
+ * Default volatility class for each MVP rule (the rule-level default; R001
+ * overrides per pattern via `RawDiagnostic.volatility`). Changing a class is a
+ * cost-model semantics change → bump COST_MODEL_VERSION in `src/version.ts`.
+ *
+ * R003 is deliberately "regeneration": unsorted `JSON.stringify` is a
+ * fragility/risk — its output is often byte-stable run-to-run, so pricing it
+ * as per-call waste would overstate.
+ */
+declare const DEFAULT_RULE_VOLATILITY: Readonly<Record<RuleId, Volatility>>;
+
+/**
+ * One warning emitted during resolution but not severe enough to abort.
+ * (Hard problems throw `SourceError` instead.)
+ */
+interface ResolutionWarning {
+    /** Machine-readable code: `"SKIPPED_SECRET"`, `"SKIPPED_BINARY"`, `"GLOB_EMPTY"`. */
+    readonly code: string;
+    /** Human one-liner. */
+    readonly message: string;
+    /** Optional path associated with the warning. */
+    readonly path?: string;
+}
+
+/**
+ * cachelint typed-error taxonomy.
+ *
+ * Every error thrown out of a command, the library API, or a rule MUST be one
+ * of these subclasses — so callers can `instanceof`-check, and the CLI's
+ * top-level catch can map each to its documented exit code.
+ *
+ * Exit-code contract (v1.0):
+ *   0  ok
+ *   1  hash moved / error-severity rule fired
+ *   2  Pro feature invoked without a license
+ *   3  cachelint.lock missing or corrupt
+ *   4  config / source error (incl. missing ANTHROPIC_API_KEY when --exact is licensed)
+ */
+
+/** Base class for every error cachelint deliberately throws. */
+declare class CachelintError extends Error {
+    /** Stable string code (e.g. `"CFG_INVALID"`) — safe to log and to grep. */
+    readonly code: string;
+    /** Suggested exit code if this error propagates to the CLI's top-level. */
+    readonly exitCode: number;
+    /** Optional one-line hint to print after the message. */
+    readonly hint?: string;
+    constructor(args: {
+        code: string;
+        message: string;
+        exitCode: number;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/** Configuration file / schema problems. Maps to exit 4. */
+declare class ConfigError extends CachelintError {
+    /** Optional file path the error was found in. */
+    readonly file?: string;
+    /** Optional "key.path" inside the config that failed. */
+    readonly keyPath?: string;
+    constructor(args: {
+        code?: string;
+        message: string;
+        file?: string;
+        keyPath?: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/** Source resolution problems (missing files, oversize, binary, traversal). Maps to exit 4. */
+declare class SourceError extends CachelintError {
+    readonly path?: string;
+    constructor(args: {
+        code?: string;
+        message: string;
+        path?: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/** Rule-engine problems (bad rule definition, sandbox violation). Maps to exit 4. */
+declare class RuleError extends CachelintError {
+    readonly ruleId?: string;
+    constructor(args: {
+        code?: string;
+        message: string;
+        ruleId?: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/** `cachelint.lock` problems. Maps to exit 3. */
+declare class LockError extends CachelintError {
+    constructor(args: {
+        code?: string;
+        message: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/** Specialisation: the lock file isn't there yet. */
+declare class LockMissingError extends LockError {
+    constructor(path: string);
+}
+/** Specialisation: the lock file is unparseable / a different major / corrupt. */
+declare class LockCorruptError extends LockError {
+    constructor(message: string, hint?: string);
+}
+/** Entitlement: Pro feature was invoked without a valid license. Maps to exit 2. */
+declare class LicenseError extends CachelintError {
+    constructor(args: {
+        code?: string;
+        message: string;
+        hint?: string;
+    });
+}
+/** `--exact` token counting is requested but the API key is missing. Maps to exit 4 (config, not entitlement). */
+declare class ExactCountUnavailableError extends CachelintError {
+    constructor(message: string, hint?: string);
+}
+/** Output adapter problems (unknown adapter, malformed adapter output). Maps to exit 4. */
+declare class AdapterError extends CachelintError {
+    constructor(args: {
+        code?: string;
+        message: string;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Warning code signalling that cost estimation degraded (R7): the run
+ * completed without a `cost` block, and this warning is the only trace.
+ * Agents/embedders match on this sentinel — shared by `lint` and `check`.
+ */
+declare const COST_UNAVAILABLE_CODE: "COST_UNAVAILABLE";
+/** A rule violation surfaced to the user. */
+type DiagnosticSeverity = "error" | "warn";
+interface Diagnostic {
+    /** Rule id (e.g. "R001"). */
+    rule: string;
+    /** Severity at this site (after pragmas, config overrides, --strict). */
+    severity: DiagnosticSeverity;
+    /** Repo-relative file path with `/` separators. */
+    file: string;
+    /** 1-based line. */
+    line: number;
+    /** 1-based column. */
+    column: number;
+    /** One-line human message. */
+    message: string;
+    /** Short hint for the fix (one line). */
+    fixHint?: string;
+    /** URL of the rule's docs page (docs/rules/<id>.md). */
+    whyUrl?: string;
+    /** Snippet of the offending line (trimmed, no secrets). */
+    snippet?: string;
+    /**
+     * Volatility class stamped by the rules engine (per-pattern override or
+     * rule-level default). Classification metadata, not cost output — it stays
+     * in `--json` even when cost output is suppressed.
+     */
+    volatility?: Volatility;
+}
+
+/**
+ * The `cachelint.config.{json,yaml,yml}` schema.
+ *
+ * Config is **data only** — JSON or YAML, never `.ts`/`.js` (no code-execution
+ * attack surface at config-load time; see the plan's Key Technical Decisions).
+ * This module owns:
+ *   - `configSchema`            — the zod schema (strict: unknown keys rejected)
+ *   - `CachelintConfig`         — the inferred TS type
+ *   - `defineConfig`            — a typed identity helper for programmatic use
+ *   - `configJsonSchema()`      — the JSON Schema (draft 2020-12) for editors
+ *
+ * Loading + format resolution + turning zod errors into `ConfigError` lives in
+ * `src/config/load.ts`. The committed `schema/cachelint.config.schema.json` is
+ * generated from `configJsonSchema()`; `test/config/schema.test.ts` asserts the
+ * committed file is in sync so it can never silently drift.
+ */
+
+/**
+ * The full config schema. `strictObject` ⇒ an unknown top-level key is a hard
+ * error (catches typos like `prompt_glob` early instead of silently ignoring).
+ */
+declare const configSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    prompt_globs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disable: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        R001: "R001";
+        R002: "R002";
+        R003: "R003";
+        R004: "R004";
+        R005: "R005";
+    }>>>;
+    rules: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        R001: "R001";
+        R002: "R002";
+        R003: "R003";
+        R004: "R004";
+        R005: "R005";
+    }> & z.core.$partial, z.ZodEnum<{
+        error: "error";
+        off: "off";
+        warn: "warn";
+    }>>>;
+    bundles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        files: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    max_file_bytes: z.ZodOptional<z.ZodNumber>;
+    max_total_bytes: z.ZodOptional<z.ZodNumber>;
+    pro: z.ZodOptional<z.ZodObject<{
+        exact_limit: z.ZodOptional<z.ZodNumber>;
+        packs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The validated, parsed config object. */
+type CachelintConfig = z.infer<typeof configSchema>;
+/** The shape a user writes (identical here — kept distinct for future divergence). */
+type CachelintConfigInput = z.input<typeof configSchema>;
+/**
+ * Typed identity helper for constructing a config in code (e.g. when calling
+ * the library API: `lint({ config: defineConfig({ prompt_globs: [...] }) })`).
+ * Does **no** runtime validation — that's `loadConfig` / `parseConfig`'s job —
+ * so it stays zero-cost and usable in any context. Mirrors the Vite/Vitest
+ * `defineConfig` convention.
+ */
+declare function defineConfig(config: CachelintConfigInput): CachelintConfigInput;
+/** The JSON Schema (draft 2020-12) for `cachelint.config.*` — for editor autocomplete. */
+declare function configJsonSchema(): Record<string, unknown>;
+
+/**
+ * Config discovery + loading for `cachelint.config.{json,yaml,yml}`.
+ *
+ * Data only — JSON or YAML, never executable. Everything that can go wrong
+ * surfaces as a `ConfigError` (exit code 4) with a precise message:
+ *   - file named explicitly but missing            → CFG_NOT_FOUND
+ *   - a `.ts` / `.js` / `.cjs` / `.mjs` config path → CFG_CODE_NOT_ALLOWED
+ *   - unparseable JSON / YAML                       → CFG_PARSE
+ *   - schema violation (unknown key, bad type, …)   → CFG_INVALID  (lists the offending paths)
+ *   - more than one auto-discovered config file     → CFG_AMBIGUOUS
+ *
+ * `loadConfig` returns `{ config, path }` (or `{ config: {}, path: null }` when
+ * nothing is found and none was requested). `parseConfig` validates an already
+ * in-memory object (used by the library API and by tests).
+ */
+
+/** Filenames auto-discovered in the project root, in precedence order. */
+declare const CONFIG_FILENAMES: readonly ["cachelint.config.json", "cachelint.config.yaml", "cachelint.config.yml"];
+interface LoadedConfig {
+    /** The validated config (an empty object if no file was found and none was requested). */
+    readonly config: CachelintConfig;
+    /** POSIX-relative path of the file that was loaded, or `null` if none. */
+    readonly path: string | null;
+}
+interface LoadConfigOptions {
+    /** Project root (absolute or resolved against cwd). Defaults to `process.cwd()`. */
+    readonly projectRoot?: string;
+    /**
+     * Explicit config path (from `--config`). If given and missing → CFG_NOT_FOUND.
+     * If omitted, we auto-discover among `CONFIG_FILENAMES` in the project root.
+     */
+    readonly explicitPath?: string;
+}
+/**
+ * Resolve, read, parse, and validate the project config.
+ * @throws {ConfigError} on any discovery/parse/validation problem.
+ */
+declare function loadConfig(opts?: LoadConfigOptions): LoadedConfig;
+/**
+ * Validate an already-in-memory config object (no disk access). Used by the
+ * library API (`lint({ config })`) and by tests.
+ * @throws {ConfigError} on schema violation.
+ */
+declare function parseConfig(data: unknown, sourceLabel?: string): CachelintConfig;
+/** What every command accepts for its `config` argument: a file path, an in-memory object, or nothing (auto-discover). */
+type ConfigArg = string | CachelintConfigInput | undefined;
+/** Resolve a command's `config` argument to a validated config + the loaded path (null for in-memory / not found). */
+declare function resolveConfigArg(arg: ConfigArg, projectRoot: string): {
+    config: CachelintConfig;
+    configPath: string | null;
+};
+
+/**
+ * The cachelint rules engine.
+ *
+ * A *rule* is a pure function: `match(raw, ctx) => RawDiagnostic[]`. No I/O, no
+ * network, no filesystem writes, no dynamic `import()`. `test/rules/purity.sandbox.test.ts`
+ * enforces this by running each rule with `fs`/`net`/`child_process` poisoned.
+ *
+ * The engine:
+ *   - owns the registry (id → Rule), keyed by the `src/rules/ids.ts` allow-list;
+ *   - resolves effective severity per rule from config (`disable` + `rules`);
+ *   - runs enabled rules over each `ResolvedSource` (operating on the RAW text,
+ *     so reported line/column match the file as the author sees it);
+ *   - applies `cachelint-disable-next-line` pragmas;
+ *   - fills in `rule` / `severity` / `file` / `whyUrl` so rules only emit the
+ *     location + message.
+ *
+ * `--strict` is NOT applied here — it only changes the *exit code*
+ * (`diagnosticsExitCode(..., { strict })` in `errors.ts`), not the displayed
+ * severity, mirroring ESLint's `--max-warnings 0`.
+ */
+
+/** What a rule emits: a location + a message. The engine adds the rest. */
+interface RawDiagnostic {
+    /** 1-based line in the RAW file. */
+    readonly line: number;
+    /** 1-based column in the RAW file. */
+    readonly column: number;
+    /** One-line human message. */
+    readonly message: string;
+    /** Short fix hint (one line). */
+    readonly fixHint?: string;
+    /** Trimmed snippet of the offending line (rule must ensure no secrets). */
+    readonly snippet?: string;
+    /** Per-pattern volatility override; when absent the rule's `volatility` applies. */
+    readonly volatility?: Volatility;
+}
+/** Per-file context handed to a rule's `match`. Read-only; no I/O capability. */
+interface RuleContext {
+    /** Repo-relative POSIX path. */
+    readonly file: string;
+    /** Lowercased file extension including the dot ("" if none). */
+    readonly ext: string;
+    /** Whether the file had a leading UTF-8 BOM (precomputed in resolution). */
+    readonly bomByte: boolean;
+    /** Whether the file mixed CRLF and bare-LF/CR endings (precomputed). */
+    readonly mixedLineEndings: boolean;
+    /**
+     * Whether this file is in scope for "prompt-only" rules (currently just
+     * R003). True when the path matched `config.prompt_globs`, was named as a
+     * literal CLI argument, or (Unit 3) is already recorded in `cachelint.lock`.
+     * R003 never runs against arbitrary source — this gate is why.
+     */
+    readonly promptScoped: boolean;
+}
+/** A rule definition. `match` MUST be pure. */
+interface Rule {
+    readonly id: RuleId;
+    /** Default severity (overridable per project via `config.rules`). */
+    readonly defaultSeverity: "error" | "warn";
+    /** Rule-level volatility class (overridable per finding via `RawDiagnostic.volatility`). */
+    readonly volatility: Volatility;
+    /** Short human title (also the SARIF rule shortDescription). */
+    readonly title: string;
+    /** Pure: no I/O, no network, no fs writes, no dynamic import. */
+    match(raw: string, ctx: RuleContext): RawDiagnostic[];
+}
+/** All registered rules, in display order. */
+declare function allRules(): ReadonlyArray<Rule>;
+/** Look up a rule by id (or `undefined`). */
+declare function getRule(id: string): Rule | undefined;
+/** The docs URL for a rule. */
+declare function ruleDocsUrl(id: RuleId): string;
+
+/**
+ * Static, versioned, dated Anthropic pricing table — the single source of
+ * price data for cost estimation. Embedded in the binary: no network, no
+ * environment reads, no I/O. Pure module.
+ *
+ * Versioning split (see docs/determinism-contract.md once Unit 6 documents it):
+ *   - Price-data updates bump `PRICING_TABLE_VERSION` and `PRICING_AS_OF`.
+ *   - Formula / engagement-semantics changes bump `COST_MODEL_VERSION` in
+ *     `src/version.ts` instead.
+ *
+ * Prices verified against platform.claude.com/docs/en/pricing as of 2026-06.
+ */
+/** Pricing facts for one model, in USD per million tokens. */
+interface ModelPricing {
+    /** Model id as it appears in API requests (e.g. "claude-sonnet-4-6"). */
+    readonly model: string;
+    /** Base input price, $/MTok. */
+    readonly baseInputPerMTok: number;
+    /** Cache-read (cache-hit) input price, $/MTok. */
+    readonly cacheReadPerMTok: number;
+    /** Minimum prompt-prefix length (tokens) below which caching never engages. */
+    readonly minCacheablePrefixTokens: number;
+}
+/** Version of the price *data* below. Bump on any price/minimum change. */
+declare const PRICING_TABLE_VERSION: 1;
+/** The month the prices below were verified against the published price list. */
+declare const PRICING_AS_OF = "2026-06";
+/**
+ * The Sonnet-class reference model every dollar figure is computed against.
+ * Deliberately decoupled from `--exact`'s tokenizer default — see the plan's
+ * Key Technical Decisions (no reference-model override surface in v1).
+ */
+declare const REFERENCE_MODEL = "claude-sonnet-4-6";
+/**
+ * Look up a model's pricing. Returns `null` for an unknown model id — callers
+ * must handle it explicitly and never produce NaN dollars from a miss.
+ */
+declare function getModelPricing(model: string): ModelPricing | null;
+/** Pricing for the Sonnet-class reference model (always present in the table). */
+declare function referencePricing(): ModelPricing;
+/**
+ * Dollars wasted per invalidated token: the cache-read discount delta,
+ * (base input − cache read) / 1e6. The cache-write premium (1.25× on the
+ * re-written prefix) is deliberately ignored — every modeling choice errs
+ * toward understating, so a skeptical bill-payer recomputing the figure can
+ * only find it conservative.
+ */
+declare function wastePerTokenUsd(p: ModelPricing): number;
+
+/**
+ * The cost-estimation engine: from-here token counts, volatility-classed
+ * earliest-divergence aggregation, dollars per 1,000 calls.
+ *
+ * Pure: no I/O, no clock, no environment — mirroring the rules engine's
+ * purity discipline (`test/cost/purity.test.ts` enforces it statically).
+ *
+ * ALL cost math runs on NORMALIZED text — the same basis hashing and
+ * `--exact` use (`src/sources/normalize.ts`) — while diagnostics carry RAW
+ * line/column. The two coordinate systems differ (BOM strip, CRLF→LF,
+ * per-line right-trim), but normalization preserves line boundaries, so the
+ * mapping is line-wise: normalized offset = Σ(normalized line length + 1 LF)
+ * for the lines before the finding + min(column − 1, the finding's normalized
+ * line length). Everything is clamped so from-here counts are never negative
+ * — even when the column points into right-trimmed whitespace or the line
+ * sits in a collapsed trailing-blank-line run.
+ *
+ * Modeling choices (all conservative — err toward understating):
+ *   - "per-call" findings get dollars; "regeneration" findings only count as
+ *     "tokens at risk" and never get a dollar figure.
+ *   - Per file *per class*, only the earliest finding counts toward totals
+ *     (`countsTowardTotal`): later same-class findings sit inside the
+ *     already-invalidated suffix. Classes never suppress each other — a BOM
+ *     at 1:1 does not swallow a later interpolated UUID's dollar line.
+ *   - Files are disjoint, so summing per-file earliest findings never double
+ *     counts. At-risk tokens are totaled separately and NEVER added to waste.
+ *   - chars/4 token heuristic: `fromHereTokens = ceil(remainingChars / 4)`.
+ */
+
+/** Cost data for one diagnostic (parallel to the input diagnostics array). */
+interface DiagnosticCost {
+    /** ceil(normalized chars from the finding to EOF / 4). */
+    readonly fromHereTokens: number;
+    /** Resolved volatility class (per-pattern override or rule default). */
+    readonly volatility: Volatility;
+    /**
+     * True only for the earliest finding in its file *and* class — the one
+     * whose `fromHereTokens` feeds the per-file and overall totals. Only totals
+     * are summable; summing per-diagnostic figures double-counts.
+     */
+    readonly countsTowardTotal: boolean;
+    /**
+     * Dollars per 1,000 calls — present only for the "per-call" class.
+     *
+     * Do NOT sum across diagnostics — use `CostTotals.wastedUsdPer1kCalls`
+     * instead; per-diagnostic figures overlap within a file, and entries with
+     * `countsTowardTotal: false` are informational only.
+     */
+    readonly wastedUsdPer1kCalls?: number;
+}
+/** Aggregated totals (per file, and overall across files). */
+interface CostTotals {
+    /** From-here tokens of the earliest per-call finding (summed across files). */
+    readonly wastedTokens: number;
+    /** `wastedTokens` priced at the waste-per-token basis, per 1,000 calls. */
+    readonly wastedUsdPer1kCalls: number;
+    /** From-here tokens of the earliest regeneration finding — tracked separately, never added to waste. */
+    readonly atRiskTokens: number;
+}
+/** The full estimate for one run. */
+interface CostEstimate {
+    /**
+     * One entry per input diagnostic, same order. `null` when no normalized
+     * text was supplied for the diagnostic's file (no cost can be computed).
+     */
+    readonly perDiagnostic: ReadonlyArray<DiagnosticCost | null>;
+    /** Totals per file (sorted by file path), only for files with cost data. */
+    readonly perFile: ReadonlyMap<string, CostTotals>;
+    /** Overall totals across all files. */
+    readonly totals: CostTotals;
+}
+/** Dollars per 1,000 calls for `tokens` re-billed at the full base-input rate. */
+declare function usdPer1kCalls(tokens: number, pricing: ModelPricing): number;
+/**
+ * The chars/4 heuristic: estimated tokens for `chars` normalized characters.
+ * Exported so `check`'s receipt (Unit 4) prices bundles on exactly the same
+ * basis as the per-diagnostic estimates.
+ */
+declare function heuristicTokens(chars: number): number;
+/**
+ * Estimate costs for a set of diagnostics against per-file NORMALIZED text
+ * (the `ResolvedSource.normalized` field — never raw text).
+ *
+ * `pricing` defaults to the Sonnet-class reference model; pass another table
+ * entry to re-price (the public output keeps the reference basis in v1).
+ */
+declare function estimateCosts(diagnostics: ReadonlyArray<Diagnostic>, normalizedTextByFile: ReadonlyMap<string, string>, pricing?: ModelPricing): CostEstimate;
+
+/**
+ * Shared dollar/label formatting for every cost-rendering surface (lint
+ * summary, check receipt, step summary). Pure functions only — renderers
+ * format precomputed numbers, nothing else.
+ */
+
+/**
+ * Format a dollars-per-1,000-calls figure with 2 significant digits, e.g.
+ * `2.134 → "$2.1"`, `0.0123 → "$0.012"`, `126 → "$130"` (never exponent
+ * notation). Returns `null` below $0.01 per 1k calls — the caller then
+ * renders the tokens-only form.
+ *
+ * The 2-significant-digit rule is `Number(usd.toPrecision(2))` re-stringified:
+ * deterministic, trailing zeros dropped (`0.010 → "$0.01"`).
+ */
+declare function formatUsdPer1k(usd: number): string | null;
+/**
+ * The assumption-stating label printed next to every dollar figure, e.g.
+ * `est. if caching is enabled, claude-sonnet-4-6 pricing, 2026-06`.
+ *
+ * Accepts anything carrying a `model` name (a full `ModelPricing` entry, or
+ * the pricing metadata echoed in a result's cost block) so renderers can
+ * format from precomputed data without re-querying the table.
+ */
+declare function costLabel(pricing: Pick<ModelPricing, "model">, asOf: string): string;
+/**
+ * Deterministic thousands grouping (`1234567 → "1,234,567"`) — never
+ * `toLocaleString`, whose output depends on the ICU build.
+ */
+declare function formatTokens(n: number): string;
+/** Token line for the earliest per-call-volatile finding in a file. */
+declare function costLineInvalidates(fromHereTokens: number): string;
+/** Dollar line under the invalidates line. `usd` is a `formatUsdPer1k` result. */
+declare function costLineWasted(usd: string, label: string): string;
+/** Printed for later same-class findings in the same file (no double-claiming). */
+declare const COST_LINE_OVERLAPPED = "(overlapped by the finding above \u2014 no additional waste)";
+/** Token line for the earliest regeneration-class finding in a file (never dollars). */
+declare function costLineAtRisk(fromHereTokens: number): string;
+/**
+ * End-of-output cost summary phrase (without any `cachelint: ` prefix — the
+ * renderer adds its own). Returns `null` when no per-call-volatile waste was
+ * found (R2: the summary exists only when per-call findings exist); at-risk
+ * tokens are appended as a separate segment, never added to the waste figure.
+ * Below $0.01 per 1,000 calls the phrase falls back to tokens-only.
+ */
+declare function costSummary(totals: {
+    readonly wastedTokens: number;
+    readonly wastedUsdPer1kCalls: number;
+    readonly atRiskTokens: number;
+}, label: string): string | null;
+/**
+ * The receipt headline: protected tokens + dollar value over the ENGAGED
+ * bundles only (bundles under the cacheable minimum are excluded — they are
+ * called out separately via `receiptWontEngageLine`). `usd` is a
+ * `formatUsdPer1k` result; `null` renders the under-a-cent form.
+ */
+declare function receiptProtectedLine(tokens: number, engagedBundles: number, usd: string | null, label: string): string;
+/** Per-bundle minimum-cacheable qualifier: this bundle is too short to cache at all. */
+declare function receiptWontEngageLine(name: string, tokens: number, minimumTokens: number): string;
+/** Printed instead of the headline when NO bundle reaches the cacheable minimum. */
+declare function receiptAllBelowMinimumLine(minimumTokens: number, minimumSource: string): string;
+/**
+ * Warn-findings qualifier printed next to the protected total on a green
+ * check (plan gap 1): the receipt must not claim the full value when warn
+ * findings already erode it. Returns `null` when there is neither waste nor
+ * at-risk data (clean run — no qualifier).
+ */
+declare function receiptWarnQualifier(totals: {
+    readonly wastedTokens: number;
+    readonly wastedUsdPer1kCalls: number;
+    readonly atRiskTokens: number;
+}): string | null;
+/**
+ * The structural slice of a check cost report the receipt builder needs —
+ * kept structural (not `CheckCostReport`) so this module never imports from
+ * `src/commands/`.
+ */
+interface ReceiptLinesInput {
+    readonly receipt: {
+        readonly bundles: ReadonlyArray<{
+            readonly name: string;
+            readonly protectedTokens: number;
+            readonly engaged: boolean;
+        }>;
+        readonly protectedTokens: number;
+        readonly protectedUsdPer1kCalls: number;
+        readonly engagementMinimumTokens: number;
+        readonly engagementMinimumSource: string;
+        readonly exactFallbackReason?: string;
+    };
+    readonly totals: {
+        readonly wastedTokens: number;
+        readonly wastedUsdPer1kCalls: number;
+        readonly atRiskTokens: number;
+    };
+}
+/**
+ * The green-check value receipt as UNPREFIXED phrase lines — the single
+ * builder behind every receipt surface. `renderCheckHuman` prefixes each line
+ * with `cachelint: `; the CI step summary turns each into a `- ` markdown
+ * bullet. Line order: protected headline (+ warn qualifier), per-bundle
+ * won't-engage callouts, the all-below-minimum callout (+ warn qualifier),
+ * and the `--exact` wholesale-fallback note.
+ */
+declare function buildReceiptLines(cost: ReceiptLinesInput, label: string): string[];
+/**
+ * One-line honesty note when `--exact` ran but could not cover every file of
+ * at least one bundle (call cap exhausted, or content changed mid-run): the
+ * affected bundles fall back WHOLESALE to the chars/4 heuristic — exact and
+ * heuristic counts are never blended within a bundle (R6).
+ */
+declare const RECEIPT_EXACT_FALLBACK_LINE = "--exact did not cover every bundle file (call cap reached, or content changed during the run) \u2014 affected bundles use the chars/4 estimate";
+
+/**
+ * `cachelint lint` — scan prompt content files for silent cache invalidators.
+ *
+ * Pipeline: load config → resolve sources (shared substrate) → run the rules
+ * engine → apply `disable` / `rules` severity overrides + `cachelint-disable`
+ * pragmas (inside the engine) → render. The library entry `lint()` returns the
+ * structured result and never writes to disk; the CLI wrapper adds `--json` /
+ * `--sarif` rendering and the process exit code.
+ *
+ * Exit-code contribution: `1` if any `error`-severity diagnostic fired (or any
+ * `warn` when `--strict`), else `0`. Pro-gated `--sarif` without a license is
+ * `2` (thrown as `LicenseError` before any output).
+ *
+ * R003 scoping: a file is "prompt-scoped" (eligible for R003) when it's matched
+ * by `config.prompt_globs` or named as a *literal* path on the command line.
+ * Glob-expanded CLI paths are NOT auto-scoped — that's what keeps a first run
+ * from lighting up with R003 findings across a whole repo.
+ */
+
+interface LintArgs {
+    /** Paths/globs to lint. If empty, falls back to `config.prompt_globs`. */
+    readonly paths?: ReadonlyArray<string>;
+    /** Config: a file path, an in-memory config object, or omitted (auto-discover). */
+    readonly config?: ConfigArg;
+    /** Project root. Defaults to `process.cwd()`. */
+    readonly projectRoot?: string;
+    /** Treat `warn`-severity diagnostics as build failures for the exit code. */
+    readonly strict?: boolean;
+    /** Pro: load a provider bug-pattern pack by id (e.g. `"anthropic-2026-q1"`). */
+    readonly pack?: string;
+    /**
+     * Compute cost estimates and attach them as `LintResult.cost` (default
+     * `true`; the CLI's global `--no-cost` passes `false`). Cost output is
+     * cosmetic only — it never affects diagnostics, exit codes, or hashing (R7).
+     * Public API addition (additive, optional).
+     */
+    readonly cost?: boolean;
+}
+/**
+ * The structured cost block attached to a `LintResult` (and echoed verbatim
+ * into `--json` output). Absent entirely when cost output is disabled
+ * (`cost: false` / `--no-cost`) or when cost computation degraded — consumers
+ * detect cost availability by the block's presence (R4).
+ *
+ * Summability contract (documented as part of `costModelVersion: 1`): only
+ * `totals` is summable; per-diagnostic figures overlap within a file, and only
+ * entries with `countsTowardTotal: true` feed the totals.
+ */
+interface LintCostReport {
+    /** Cost-*formula* version (see `COST_MODEL_VERSION` in src/version.ts). */
+    readonly costModelVersion: typeof COST_MODEL_VERSION;
+    /** Price-*data* provenance for every dollar figure in this block. */
+    readonly pricing: {
+        /** Version of the embedded pricing table (`PRICING_TABLE_VERSION`). */
+        readonly tableVersion: typeof PRICING_TABLE_VERSION;
+        /** Month the prices were verified, e.g. `"2026-06"`. */
+        readonly asOf: string;
+        /** The Sonnet-class reference model all dollar figures use. */
+        readonly referenceModel: string;
+    };
+    /**
+     * One entry per `LintResult.diagnostics` element, same order. `null` when
+     * no cost could be computed for that diagnostic's file.
+     */
+    readonly perDiagnostic: ReadonlyArray<DiagnosticCost | null>;
+    /** Earliest-divergence totals across all files (waste and at-risk are disjoint). */
+    readonly totals: CostTotals;
+    /**
+     * NORMALIZED character count per resolved file (repo-relative POSIX path →
+     * chars), keys sorted by path. Additive in cost-model v1 (Unit 4): the
+     * auditable input of the chars/4 heuristic — `check` derives its per-bundle
+     * receipt token counts from these without a second resolution pass.
+     *
+     * Part of the `costModelVersion: 1` stability contract: its presence,
+     * keying, and normalized-chars semantics only change with a
+     * `COST_MODEL_VERSION` bump.
+     */
+    readonly normalizedCharsByFile: Readonly<Record<string, number>>;
+}
+interface LintResult {
+    /** cachelint version that produced this result. */
+    readonly version: string;
+    /** POSIX-relative path of the loaded config file, or `null`. */
+    readonly configPath: string | null;
+    /** The Pro pack that was loaded for this run, or `null`. */
+    readonly packLoaded: string | null;
+    /** All diagnostics, sorted by (file, line, column, rule). */
+    readonly diagnostics: Diagnostic[];
+    /** Non-fatal resolution notes (skipped secrets/binaries, empty globs). */
+    readonly warnings: ResolutionWarning[];
+    /** `1` if the run should fail CI, else `0` (honoring `strict`). */
+    readonly exitCode: 0 | 1;
+    /** Cost estimates (R1/R2/R4). Absent under `cost: false` or on degradation. */
+    readonly cost?: LintCostReport;
+}
+/** Run the lint pipeline. Reads the filesystem; never writes. */
+declare function lint(args?: LintArgs): LintResult;
+interface RenderOptions {
+    /** Emit ANSI colors. */
+    readonly color?: boolean;
+}
+/** Human-readable report (ripgrep-ish: `file:line:col  level  RID  message`). */
+declare function renderLintHuman(result: LintResult, opts?: RenderOptions): string;
+/** Stable JSON report. */
+declare function renderLintJson(result: LintResult): string;
+
+/**
+ * `cachelint.lock` — format, canonical serialization, read, atomic write.
+ *
+ * The lock is the single committed artifact and it stores **hashes only —
+ * never content**. It is byte-identical across Windows / macOS / Linux and
+ * Node 22/24 for the same inputs, because it is written through the
+ * canonical encoding below:
+ *
+ *   - object keys sorted by Unicode codepoint (UTF-16 code-unit order — equal
+ *     to codepoint order for the BMP, which is all we ever emit)
+ *   - ASCII-only output: every char >= U+0080 is escaped as `\uXXXX` (surrogate
+ *     pairs as two `\uXXXX`), so a non-ASCII path/message can't introduce
+ *     OS-encoding drift
+ *   - numbers serialized via `String(n)` (we only ever emit non-negative
+ *     integers, where that equals JSON's own rendering)
+ *   - 2-space indentation, LF newlines, and **no trailing newline** after the
+ *     closing `}`
+ *
+ * The policy versions (`normalizationPolicyVersion`, `ruleTableVersion`) are
+ * stored so `cachelint check` can report a deliberate bump as "policy moved"
+ * rather than a confusing per-file diff. `cachelintVersion` is informational
+ * only — `check` ignores it when deciding pass/fail, so a no-op upgrade does
+ * not churn the file.
+ */
+/** Bump when the *structure* of `cachelint.lock` changes (not its contents). */
+declare const LOCKFILE_FORMAT_VERSION: 1;
+/** Default lockfile path, relative to the project root. */
+declare const DEFAULT_LOCKFILE_NAME = "cachelint.lock";
+/** One file inside a bundle: its repo-relative POSIX path + the sha256 of its normalized content. */
+interface LockFileEntry {
+    readonly path: string;
+    readonly sha256: string;
+}
+/** One bundle: a named, ordered group of files and the hash over their per-file hashes. */
+interface LockBundle {
+    readonly name: string;
+    readonly files: ReadonlyArray<LockFileEntry>;
+    readonly stablePrefixHash: string;
+}
+/** The full lockfile object. */
+interface Lockfile {
+    readonly version: number;
+    readonly cachelintVersion: string;
+    readonly normalizationPolicyVersion: number;
+    readonly ruleTableVersion: number;
+    /** Bundles, sorted by `name` (codepoint order). */
+    readonly bundles: ReadonlyArray<LockBundle>;
+}
+/** Serialize any JSON value with sorted keys, ASCII-only escaping, 2-space indent, no trailing newline. */
+declare function canonicalJsonStringify(value: unknown): string;
+/** The exact bytes that should be on disk for this lockfile (LF, no trailing newline). */
+declare function serializeLockfile(lock: Lockfile): string;
+/** Parse + validate a lockfile's text. Throws `LockCorruptError` on anything off. */
+declare function parseLockfile(text: string, label?: string): Lockfile;
+
+/**
+ * `cachelint hash [paths…]` — compute every bundle's `stablePrefixHash` and
+ * write / update `cachelint.lock`.
+ *
+ * The lock is the analogue of `package-lock.json`: `hash` is the *writer* (a
+ * developer runs it locally and commits the result); `check` is the *verifier*
+ * (CI). One direction. The file stores hashes only — never content. The write is
+ * atomic (temp file → rename).
+ *
+ * The library entry `hash()` returns the lockfile object + the text written + the
+ * path; it always writes (that's the command's whole job), so unlike `lint()` it
+ * is not side-effect-free.
+ */
+
+interface HashArgs {
+    /** Paths/globs to hash as one-file bundles. If empty, falls back to `config.prompt_globs` (+ always `config.bundles`). */
+    readonly paths?: ReadonlyArray<string>;
+    readonly config?: ConfigArg;
+    /** Project root. Defaults to `process.cwd()`. */
+    readonly projectRoot?: string;
+    /** Lockfile path relative to the project root (default `cachelint.lock`). */
+    readonly out?: string;
+}
+interface HashResult {
+    /** The lockfile object that was written. */
+    readonly lockfile: Lockfile;
+    /** The exact text written to disk. */
+    readonly text: string;
+    /** Absolute path of the lockfile. */
+    readonly path: string;
+    /** POSIX-relative path of the loaded config, or `null`. */
+    readonly configPath: string | null;
+    /** Non-fatal resolution notes (skipped secrets/binaries, empty globs). */
+    readonly warnings: ResolutionWarning[];
+    /** Number of bundles recorded. */
+    readonly bundleCount: number;
+}
+/** Compute bundles and write `cachelint.lock`. */
+declare function hash(args?: HashArgs): HashResult;
+/** Human-readable summary for the CLI. */
+declare function renderHashHuman(r: HashResult, projectRoot?: string): string;
+/** Stable JSON report — lets an agent read back the written bundle hashes without parsing prose. */
+declare function renderHashJson(r: HashResult, projectRoot?: string): string;
+
+/**
+ * Categorized diff between a committed `cachelint.lock` and a freshly-recomputed
+ * one. This is what `cachelint check` reports.
+ *
+ * What counts as a *regression* (exit code 1):
+ *   - a bundle's `stablePrefixHash` moved
+ *   - a bundle was added or removed
+ *   - a bundle's file list / per-file hashes changed
+ *   - the normalization policy or rule-table version changed (a deliberate
+ *     `cachelint` upgrade — reported with its own message, not as a file diff)
+ *
+ * `cachelintVersion` is intentionally NOT compared — a no-op upgrade must not
+ * make `check` fail.
+ */
+
+interface PolicyChange {
+    readonly field: "normalizationPolicyVersion" | "ruleTableVersion";
+    readonly committed: number;
+    readonly current: number;
+}
+interface BundleHashChange {
+    readonly name: string;
+    readonly committedHash: string;
+    readonly currentHash: string;
+    /** Files whose path set or per-file hash changed (for the human report). */
+    readonly fileChanges: ReadonlyArray<{
+        path: string;
+        committed: string | null;
+        current: string | null;
+    }>;
+}
+interface LockDiff {
+    readonly policyChanges: ReadonlyArray<PolicyChange>;
+    readonly addedBundles: ReadonlyArray<string>;
+    readonly removedBundles: ReadonlyArray<string>;
+    readonly changedBundles: ReadonlyArray<BundleHashChange>;
+}
+/** Whether this diff represents a regression (i.e. `check` should fail). */
+declare function isRegression(d: LockDiff): boolean;
+/** Compute the diff of `current` against the `committed` lockfile. */
+declare function diffLockfiles(committed: Lockfile, current: Lockfile): LockDiff;
+
+interface ExactCountResult {
+    readonly sha256: string;
+    readonly model: string;
+    readonly tokens: number;
+}
+
+/**
+ * `cachelint check [--config]` — the headline CI gate.
+ *
+ * It recomputes every bundle's `stablePrefixHash`, reads the committed
+ * `cachelint.lock`, runs the lint rules over the bundle's files, and exits with
+ * the pinned table:
+ *   0  ok (lock matches; lint clean, or only `warn`s without `--strict`)
+ *   1  a `stablePrefixHash` moved / a bundle was added or removed / the
+ *      normalization-policy or rule-table version changed, OR an `error`-severity
+ *      rule fired (or a `warn` when `--strict`)
+ *   2  a Pro feature (`--exact`, `--sarif`, `--pack`) was invoked without a license
+ *   3  `cachelint.lock` missing or corrupt
+ *   4  config or source error (incl. missing `ANTHROPIC_API_KEY` when `--exact` IS licensed)
+ *
+ * Exit-code mapping is enforced by the typed errors (`LockMissingError`/3,
+ * `LockCorruptError`/3, `LicenseError`/2, `ExactCountUnavailableError`/4,
+ * `ConfigError`/`SourceError`/4); a regression diff or failing lint produces 1
+ * directly via the returned `exitCode`.
+ */
+
+interface CheckArgs {
+    /** Paths/globs to treat as one-file bundles. If empty, falls back to `config.prompt_globs` (+ always `config.bundles`). */
+    readonly paths?: ReadonlyArray<string>;
+    readonly config?: ConfigArg;
+    readonly projectRoot?: string;
+    /** Lockfile path relative to the project root (default `cachelint.lock`). */
+    readonly lockfile?: string;
+    /** Treat `warn`-severity rule findings as failures for the exit code. */
+    readonly strict?: boolean;
+    /** Pro: also count tokens via the Anthropic count-tokens API. */
+    readonly exact?: boolean;
+    /** Pro: model whose tokenizer to use for `--exact` (default `DEFAULT_EXACT_MODEL`). */
+    readonly exactModel?: string;
+    /** Pro: cap on `--exact` API calls per run (default 100). */
+    readonly exactLimit?: number;
+    /** Pro: load a provider bug-pattern pack by id. */
+    readonly pack?: string;
+    /**
+     * Compute cost estimates + the value receipt and attach them as
+     * `CheckResult.cost` (default `true`; the CLI's global `--no-cost` passes
+     * `false` — forwarded to the embedded `lint()` call). Cost output is
+     * cosmetic only — it never affects diagnostics, exit codes, lockfile bytes,
+     * or hashing (R7). Public API addition (additive, optional).
+     */
+    readonly cost?: boolean;
+}
+/** One bundle's entry in the green-check value receipt (R3). */
+interface ReceiptBundle {
+    readonly name: string;
+    /**
+     * Estimated cacheable-prefix tokens this bundle protects: `ceil(normalized
+     * chars / 4)` summed over the bundle's files — or the summed `--exact`
+     * counts when `tokenSource` is `"exact"`.
+     */
+    readonly protectedTokens: number;
+    /**
+     * `"exact"` only when EVERY file of this bundle got an `--exact` count this
+     * run; any skipped file (call cap, sha mismatch) falls the whole bundle
+     * back to `"heuristic"` — exact and heuristic counts are never blended (R6).
+     */
+    readonly tokenSource: "exact" | "heuristic";
+    /** Whether `protectedTokens` reaches the engagement minimum (caching can engage). */
+    readonly engaged: boolean;
+    /** Reference-model dollar value per 1,000 calls — present only when engaged. */
+    readonly protectedUsdPer1kCalls?: number;
+}
+/**
+ * The green-check value receipt (R3): what a stable prefix is worth. All
+ * dollar figures use the Sonnet-class reference model regardless of
+ * `--exact-model` (R5); the engagement minimum may be raised by an
+ * `--exact-model` present in the pricing table (the user handed us evidence
+ * of their real model — ignoring its higher minimum would overstate).
+ */
+interface CheckReceipt {
+    /** One entry per bundle, in lockfile (name-sorted) order. */
+    readonly bundles: ReadonlyArray<ReceiptBundle>;
+    /** Protected tokens summed over ENGAGED bundles only (below-minimum bundles protect nothing yet). */
+    readonly protectedTokens: number;
+    /** `protectedTokens` valued at the reference model, per 1,000 calls. */
+    readonly protectedUsdPer1kCalls: number;
+    /** The minimum cacheable prefix length (tokens) used for the engagement check. */
+    readonly engagementMinimumTokens: number;
+    /** Model id whose minimum governs: the reference model, or a higher-minimum `--exact-model`. */
+    readonly engagementMinimumSource: string;
+    /** True when at least one bundle's token count came from `--exact` results. */
+    readonly exactRefined: boolean;
+    /** Present when `--exact` ran but at least one bundle fell back to the heuristic. */
+    readonly exactFallbackReason?: string;
+}
+/**
+ * The structured cost block attached to a `CheckResult` (and echoed verbatim
+ * into `--json` output). The shared shape is exactly the embedded `lint()`
+ * call's `LintCostReport` (no second resolution or estimation pass); `check`
+ * adds only the `receipt`. Absent entirely under `cost: false` / `--no-cost`
+ * or on degradation — presence signals availability (R4).
+ */
+interface CheckCostReport extends LintCostReport {
+    readonly receipt: CheckReceipt;
+}
+interface CheckResult {
+    readonly version: string;
+    readonly configPath: string | null;
+    /** The Pro pack loaded for this run, or `null`. */
+    readonly packLoaded: string | null;
+    readonly lockfilePath: string;
+    /** Diff of the recomputed bundles against the committed lock. */
+    readonly diff: LockDiff;
+    /** Whether the diff is a regression (hash moved / bundle added-removed / policy bumped). */
+    readonly regression: boolean;
+    /** Lint diagnostics over the bundle files. */
+    readonly diagnostics: Diagnostic[];
+    /** `--exact` token counts, when requested + licensed (else `null`). */
+    readonly exactCounts: ExactCountResult[] | null;
+    readonly warnings: ResolutionWarning[];
+    /** `0` if everything checks out, `1` on a regression or a failing rule. */
+    readonly exitCode: 0 | 1;
+    /** Cost estimates + value receipt (R1/R3/R4). Absent under `cost: false` or on degradation. */
+    readonly cost?: CheckCostReport;
+}
+/** Run the check pipeline. Reads the filesystem; never writes. Throws typed errors for exit 2/3/4. */
+declare function check(args?: CheckArgs): Promise<CheckResult>;
+declare function renderCheckHuman(r: CheckResult): string;
+declare function renderCheckJson(r: CheckResult, projectRoot?: string): string;
+
+/**
+ * Offline verification of a cachelint Pro license token. **No network, ever.**
+ *
+ * Token: `base64url(payloadJson) "." base64url(ed25519Signature)`. The signature
+ * covers the *exact bytes* of `base64url(payloadJson)` (the part before the dot)
+ * — so re-serializing the payload can't change what was signed. Verification:
+ *
+ *   1. split on the single `.`; base64url-decode both halves
+ *   2. parse the payload JSON; require `v === 1`
+ *   3. look up `kid` in the trusted-key set; reject an unknown `kid`
+ *   4. `crypto.verify(null, signedBytes, key, sig)` (Ed25519 ⇒ algorithm `null`)
+ *   5. reject if the `nonce` is on the revoked list
+ *   6. reject if `plan !== "pro"`
+ *   7. `exp`: accepted up to {@link GRACE_PERIOD_DAYS} days past expiry (with a
+ *      warning); beyond that, rejected
+ *
+ * On any failure this throws `LicenseError` (exit code 2) — and never echoes the
+ * token bytes.
+ */
+/** Days after `exp` that a token is still honored (with a warning) before hard rejection. */
+declare const GRACE_PERIOD_DAYS = 14;
+/** The Pro capabilities a license may grant. */
+type LicenseFeature = "sarif" | "exact" | "pack";
+interface LicensePayload {
+    /** Payload schema version. Must be `1`. */
+    readonly v: 1;
+    /** Subject — the buyer's email (printed by `cachelint --version` as the only anti-share signal). */
+    readonly sub: string;
+    /** Plan — currently always `"pro"`. */
+    readonly plan: "pro";
+    /** Granted features. */
+    readonly features: ReadonlyArray<LicenseFeature>;
+    /** Issued-at (unix seconds). */
+    readonly iat: number;
+    /** Expiry (unix seconds). */
+    readonly exp: number;
+    /** Per-token nonce (revocation handle). */
+    readonly nonce: string;
+    /** Signing-key id (matched against the trusted-key set). */
+    readonly kid: number;
+}
+interface VerifiedLicense {
+    readonly payload: LicensePayload;
+    /** True if the token is past `exp` but still inside the grace window. */
+    readonly inGracePeriod: boolean;
+    /** A human warning to surface (e.g. grace-period notice), or `null`. */
+    readonly warning: string | null;
+}
+/** Verify `token`. Throws `LicenseError` on anything wrong. `now` is injectable for tests (unix ms). */
+declare function verifyLicenseToken(token: string, now?: number): VerifiedLicense;
+
+/**
+ * Pro-feature gate — the single place core code asks "is this licensed?".
+ *
+ * It reads the stored token (env override, then the per-user file), verifies it
+ * offline (Ed25519, no network), and caches the result for the process. The
+ * gate is *never* consulted on a core path — `lint`/`hash`/`check` without a Pro
+ * flag don't touch it. On any verification failure the gate simply behaves as
+ * "no license" (the failure is surfaced by `cachelint activate` / `license status`,
+ * not by a core command).
+ *
+ * `requirePro(feature, …)` throws `LicenseError` (exit code 2) with the upgrade
+ * hint when the feature isn't licensed.
+ */
+
+/** The Pro-gated capabilities. */
+type ProFeature = LicenseFeature;
+/** Public, token-free view of the active license. */
+interface ActiveLicenseInfo {
+    readonly plan: "pro";
+    /** Buyer email. */
+    readonly sub: string;
+    /** Expiry (unix seconds). */
+    readonly exp: number;
+    /** Signing-key id. */
+    readonly kid: number;
+    /** Granted features. */
+    readonly features: ReadonlyArray<ProFeature>;
+    /** True if past `exp` but inside the grace window. */
+    readonly inGracePeriod: boolean;
+    /** Where the token came from (`env …` or a file path) — never the token itself. */
+    readonly source: string;
+}
+/** The active license info, or `null` if none / invalid. Never returns the raw token. */
+declare function activeLicenseInfo(): ActiveLicenseInfo | null;
+/** Whether a Pro feature is licensed. With no argument: whether *any* valid Pro license is active. */
+declare function isPro(feature?: ProFeature): boolean;
+/**
+ * Throw {@link LicenseError} (exit code 2) unless `feature` is licensed.
+ * @param feature  the capability being used
+ * @param whatHuman  a short noun phrase for the message, e.g. "`--sarif` output"
+ */
+declare function requirePro(feature: ProFeature, whatHuman: string): void;
+
+/**
+ * `cachelint activate <key>` / `cachelint license [status]` / `cachelint deactivate`.
+ *
+ * All offline. `activate` verifies the token (Ed25519, no network) and, on
+ * success, writes it to the per-user license file; it never echoes the token
+ * back. `license status` prints the plan, buyer email, expiry, and granted
+ * features — never the raw token. `deactivate` removes the file (and warns if a
+ * `CACHELINT_LICENSE_KEY` env override is still in effect).
+ */
+
+interface ActivateResult {
+    readonly info: ActiveLicenseInfo;
+    /** Path the token was written to. */
+    readonly storedAt: string;
+    /** Grace-period / other notice, or `null`. */
+    readonly warning: string | null;
+}
+/** Verify and store a license token. Throws `LicenseError` (exit 2) on a bad/expired token. */
+declare function activate(token: string): ActivateResult;
+interface LicenseStatus {
+    readonly active: boolean;
+    readonly info: ActiveLicenseInfo | null;
+    /** Path where a stored license would live (whether or not one is there). */
+    readonly filePath: string;
+}
+/** Inspect the active license. Never throws for "no license" — that's just `active: false`. */
+declare function licenseStatus(): LicenseStatus;
+interface DeactivateResult {
+    /** Whether a stored file was actually removed. */
+    readonly removed: boolean;
+    /** True if a CACHELINT_LICENSE_KEY env override is still active (so Pro stays on). */
+    readonly envStillActive: boolean;
+    readonly filePath: string;
+}
+/** Remove the stored license file. */
+declare function deactivate(): DeactivateResult;
+
+/**
+ * Provider-specific bug-pattern packs (Pro, `--pack <id>`).
+ *
+ * The pack *surface* ships in the MVP — the flag is recognized, Pro-gated, and
+ * the id is validated — but no pack rules are wired in yet: the rules need an
+ * FP audit against real provider-using repos before they earn a place, and
+ * shipping speculative ones would undermine the linter's signal. `packRules(id)`
+ * therefore returns `[]` for now. When the `anthropic-2026-q1` rules are ready,
+ * wiring them in is two steps: (1) add an `extraRules?: ReadonlyArray<Rule>`
+ * option to `RunRulesOptions` in `src/rules/index.ts` and run them alongside the
+ * static `REGISTRY`; (2) have `lint()`/`check()` pass `packRules(packLoaded)`.
+ *
+ * `anthropic-2026-q1` is reserved for rules derived from the early-2026 Claude
+ * Code cache regressions (`anthropics/claude-code#34629` / `#46829` / `#41930`
+ * and the April-23 postmortem).
+ */
+
+/** Pack ids this build recognizes. */
+declare const KNOWN_PACK_IDS: ReadonlySet<string>;
+
+export { type ActivateResult, type ActiveLicenseInfo, AdapterError, CACHELINT_VERSION, CONFIG_FILENAMES, COST_LINE_OVERLAPPED, COST_MODEL_VERSION, COST_UNAVAILABLE_CODE, type CachelintConfig, type CachelintConfigInput, CachelintError, type CheckArgs, type CheckCostReport, type CheckReceipt, type CheckResult, type ConfigArg, ConfigError, type CostEstimate, type CostTotals, DEFAULT_LOCKFILE_NAME, DEFAULT_RULE_SEVERITY, DEFAULT_RULE_VOLATILITY, type DeactivateResult, type Diagnostic, type DiagnosticCost, type DiagnosticSeverity, ExactCountUnavailableError, GRACE_PERIOD_DAYS, type HashArgs, type HashResult, KNOWN_PACK_IDS, LOCKFILE_FORMAT_VERSION, LicenseError, type LicenseFeature, type LicensePayload, type LicenseStatus, type LintArgs, type LintCostReport, type LintResult, type LoadConfigOptions, type LoadedConfig, type LockBundle, LockCorruptError, type LockDiff, LockError, type LockFileEntry, LockMissingError, type Lockfile, type ModelPricing, NORMALIZATION_POLICY_VERSION, PRICING_AS_OF, PRICING_TABLE_VERSION, type ProFeature, RECEIPT_EXACT_FALLBACK_LINE, REFERENCE_MODEL, RULE_IDS, RULE_TABLE_VERSION, type RawDiagnostic, type ReceiptBundle, type ReceiptLinesInput, type Rule, type RuleContext, RuleError, type RuleId, SourceError, type VerifiedLicense, type Volatility, activate, activeLicenseInfo, allRules, buildReceiptLines, canonicalJsonStringify, check, configJsonSchema, configSchema, costLabel, costLineAtRisk, costLineInvalidates, costLineWasted, costSummary, deactivate, defineConfig, diffLockfiles, estimateCosts, formatTokens, formatUsdPer1k, getModelPricing, getRule, hash, heuristicTokens, isPro, isRegression, licenseStatus, lint, loadConfig, parseConfig, parseLockfile, receiptAllBelowMinimumLine, receiptProtectedLine, receiptWarnQualifier, receiptWontEngageLine, referencePricing, renderCheckHuman, renderCheckJson, renderHashHuman, renderHashJson, renderLintHuman, renderLintJson, requirePro, resolveConfigArg, ruleDocsUrl, serializeLockfile, usdPer1kCalls, verifyLicenseToken, wastePerTokenUsd };