cachelint 0.1.0

package/dist/chunk-XKRPGMZT.js

@@ -0,0 +1,197 @@
+// src/exit-codes.ts
+var EXIT_OK = 0;
+var EXIT_CHECK_FAILED = 1;
+var EXIT_PRO_REQUIRED = 2;
+var EXIT_LOCK_PROBLEM = 3;
+var EXIT_CONFIG_OR_SOURCE_ERROR = 4;
+
+// src/errors.ts
+var CachelintError = class extends Error {
+  /** Stable string code (e.g. `"CFG_INVALID"`) — safe to log and to grep. */
+  code;
+  /** Suggested exit code if this error propagates to the CLI's top-level. */
+  exitCode;
+  /** Optional one-line hint to print after the message. */
+  hint;
+  constructor(args) {
+    super(args.message);
+    this.name = this.constructor.name;
+    this.code = args.code;
+    this.exitCode = args.exitCode;
+    if (args.hint !== void 0) this.hint = args.hint;
+    if (args.cause !== void 0) this.cause = args.cause;
+  }
+};
+var ConfigError = class extends CachelintError {
+  /** Optional file path the error was found in. */
+  file;
+  /** Optional "key.path" inside the config that failed. */
+  keyPath;
+  constructor(args) {
+    super({
+      code: args.code ?? "CFG_INVALID",
+      message: args.message,
+      exitCode: EXIT_CONFIG_OR_SOURCE_ERROR,
+      ...args.hint !== void 0 ? { hint: args.hint } : {},
+      ...args.cause !== void 0 ? { cause: args.cause } : {}
+    });
+    if (args.file !== void 0) this.file = args.file;
+    if (args.keyPath !== void 0) this.keyPath = args.keyPath;
+  }
+};
+var SourceError = class extends CachelintError {
+  path;
+  constructor(args) {
+    super({
+      code: args.code ?? "SRC_INVALID",
+      message: args.message,
+      exitCode: EXIT_CONFIG_OR_SOURCE_ERROR,
+      ...args.hint !== void 0 ? { hint: args.hint } : {},
+      ...args.cause !== void 0 ? { cause: args.cause } : {}
+    });
+    if (args.path !== void 0) this.path = args.path;
+  }
+};
+var RuleError = class extends CachelintError {
+  ruleId;
+  constructor(args) {
+    super({
+      code: args.code ?? "RULE_INVALID",
+      message: args.message,
+      exitCode: EXIT_CONFIG_OR_SOURCE_ERROR,
+      ...args.hint !== void 0 ? { hint: args.hint } : {},
+      ...args.cause !== void 0 ? { cause: args.cause } : {}
+    });
+    if (args.ruleId !== void 0) this.ruleId = args.ruleId;
+  }
+};
+var LockError = class extends CachelintError {
+  constructor(args) {
+    super({
+      code: args.code ?? "LOCK_INVALID",
+      message: args.message,
+      exitCode: EXIT_LOCK_PROBLEM,
+      ...args.hint !== void 0 ? { hint: args.hint } : {},
+      ...args.cause !== void 0 ? { cause: args.cause } : {}
+    });
+  }
+};
+var LockMissingError = class extends LockError {
+  constructor(path) {
+    super({
+      code: "LOCK_MISSING",
+      message: `cachelint.lock not found at ${path}`,
+      hint: "Run `cachelint hash <paths>` once and commit the resulting cachelint.lock."
+    });
+  }
+};
+var LockCorruptError = class extends LockError {
+  constructor(message, hint) {
+    super({ code: "LOCK_CORRUPT", message, ...hint !== void 0 ? { hint } : {} });
+  }
+};
+var LicenseError = class extends CachelintError {
+  constructor(args) {
+    super({
+      code: args.code ?? "PRO_REQUIRED",
+      message: args.message,
+      exitCode: EXIT_PRO_REQUIRED,
+      ...args.hint !== void 0 ? { hint: args.hint } : {}
+    });
+  }
+};
+var ExactCountUnavailableError = class extends CachelintError {
+  constructor(message, hint) {
+    super({
+      code: "EXACT_UNAVAILABLE",
+      message,
+      exitCode: EXIT_CONFIG_OR_SOURCE_ERROR,
+      ...hint !== void 0 ? { hint } : {}
+    });
+  }
+};
+var AdapterError = class extends CachelintError {
+  constructor(args) {
+    super({
+      code: args.code ?? "ADAPTER_INVALID",
+      message: args.message,
+      exitCode: EXIT_CONFIG_OR_SOURCE_ERROR,
+      ...args.hint !== void 0 ? { hint: args.hint } : {},
+      ...args.cause !== void 0 ? { cause: args.cause } : {}
+    });
+  }
+};
+var COST_UNAVAILABLE_CODE = "COST_UNAVAILABLE";
+function costUnavailableWarning(err) {
+  return {
+    code: COST_UNAVAILABLE_CODE,
+    message: `cost estimation failed (${err instanceof Error ? err.message : String(err)}) \u2014 continuing without cost data`
+  };
+}
+function diagnosticsExitCode(diagnostics, opts = {}) {
+  const strict = opts.strict === true;
+  for (const d of diagnostics) {
+    if (d.severity === "error") return EXIT_CHECK_FAILED;
+    if (strict && d.severity === "warn") return EXIT_CHECK_FAILED;
+  }
+  return 0;
+}
+function redactSecrets(text) {
+  if (typeof text !== "string") return text;
+  let out = text;
+  out = out.replace(/sk-ant-[A-Za-z0-9_-]{10,}/g, "<redacted>");
+  out = out.replace(/sk-(?:proj-)?[A-Za-z0-9_-]{10,}/g, "<redacted>");
+  out = out.replace(/Bearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer <redacted>");
+  out = out.replace(/(x-api-key[\s:=]+)["']?[A-Za-z0-9._~+/=-]{8,}["']?/gi, "$1<redacted>");
+  out = out.replace(/(Authorization[\s:=]+)["']?[^"'\s,;]{8,}["']?/gi, "$1<redacted>");
+  out = out.replace(/\b[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/g, "<redacted-token>");
+  out = out.replace(
+    /\b(ANTHROPIC_API_KEY|OPENAI_API_KEY|CACHELINT_LICENSE_KEY)\b\s*[=:]\s*["']?[^"'\s,;]+["']?/g,
+    "$1=<redacted>"
+  );
+  return out;
+}
+function renderError(err, opts = {}) {
+  const verbose = opts.verbose === true;
+  if (err instanceof CachelintError) {
+    const lines = [];
+    lines.push(`cachelint: ${err.message}  [${err.code}]`);
+    if (err.hint) lines.push(`  hint: ${err.hint}`);
+    if (verbose && err.stack) lines.push(err.stack);
+    return redactSecrets(lines.join("\n"));
+  }
+  if (err instanceof Error) {
+    if (verbose && err.stack) return redactSecrets(`cachelint: unexpected error
+${err.stack}`);
+    return redactSecrets(`cachelint: unexpected error: ${err.message}`);
+  }
+  return redactSecrets(`cachelint: unexpected error: ${String(err)}`);
+}
+function exitCodeFor(err) {
+  if (err instanceof CachelintError) return err.exitCode;
+  return EXIT_CONFIG_OR_SOURCE_ERROR;
+}
+
+export {
+  EXIT_OK,
+  EXIT_CHECK_FAILED,
+  EXIT_PRO_REQUIRED,
+  EXIT_LOCK_PROBLEM,
+  EXIT_CONFIG_OR_SOURCE_ERROR,
+  CachelintError,
+  ConfigError,
+  SourceError,
+  RuleError,
+  LockError,
+  LockMissingError,
+  LockCorruptError,
+  LicenseError,
+  ExactCountUnavailableError,
+  AdapterError,
+  COST_UNAVAILABLE_CODE,
+  costUnavailableWarning,
+  diagnosticsExitCode,
+  redactSecrets,
+  renderError,
+  exitCodeFor
+};

package/dist/chunk-ZSEZQ422.js

@@ -0,0 +1,286 @@
+import {
+  DEFAULT_EXACT_LIMIT,
+  DEFAULT_EXACT_MODEL,
+  countTokensExact
+} from "./chunk-UUVSBJ62.js";
+import {
+  heuristicTokens,
+  lint,
+  usdPer1kCalls
+} from "./chunk-2JSY5BQA.js";
+import {
+  getModelPricing,
+  referencePricing
+} from "./chunk-O7ZE6CFI.js";
+import {
+  requirePro
+} from "./chunk-GXASKZ4Z.js";
+import {
+  diffLockfiles,
+  isRegression,
+  renderDiffHuman
+} from "./chunk-DYQPXD3G.js";
+import {
+  COST_LINE_OVERLAPPED,
+  RECEIPT_EXACT_FALLBACK_LINE,
+  buildReceiptLines,
+  costLabel,
+  costLineAtRisk,
+  costLineInvalidates,
+  costLineWasted,
+  costSummary,
+  formatUsdPer1k
+} from "./chunk-VWE5TDL5.js";
+import {
+  DEFAULT_LOCKFILE_NAME,
+  computeBundles,
+  makeLockfile,
+  readLockfileIfExists
+} from "./chunk-BUZCVKMZ.js";
+import {
+  resolveConfigArg,
+  resolveSources,
+  toPosixRelative
+} from "./chunk-MW7BXKPR.js";
+import {
+  CACHELINT_VERSION
+} from "./chunk-WPJYUQMU.js";
+import {
+  COST_UNAVAILABLE_CODE,
+  LockMissingError,
+  costUnavailableWarning,
+  redactSecrets
+} from "./chunk-XKRPGMZT.js";
+
+// src/commands/check.ts
+import { resolve as pathResolve } from "path";
+async function check(args = {}) {
+  const root = pathResolve(args.projectRoot ?? process.cwd());
+  const { config, configPath } = resolveConfigArg(args.config, root);
+  const { bundles, warnings } = computeBundles({
+    ...args.paths !== void 0 ? { paths: args.paths } : {},
+    config,
+    projectRoot: root
+  });
+  const lockPath = pathResolve(root, args.lockfile ?? DEFAULT_LOCKFILE_NAME);
+  const committed = readLockfileIfExists(lockPath);
+  if (committed === null) throw new LockMissingError(args.lockfile ?? DEFAULT_LOCKFILE_NAME);
+  const current = makeLockfile(bundles);
+  const diff = diffLockfiles(committed, current);
+  const regression = isRegression(diff);
+  const allFiles = [...new Set(bundles.flatMap((b) => b.files.map((f) => f.path)))].sort();
+  const lintResult = lint({
+    paths: allFiles,
+    config,
+    projectRoot: root,
+    ...args.strict !== void 0 ? { strict: args.strict } : {},
+    ...args.pack !== void 0 ? { pack: args.pack } : {},
+    // R7: cost is forwarded but never recomputed — check reuses the embedded
+    // lint call's resolution/cost data (no second resolution pass).
+    ...args.cost !== void 0 ? { cost: args.cost } : {}
+  });
+  const diagnostics = lintResult.diagnostics;
+  let exactCounts = null;
+  if (args.exact === true) {
+    requirePro("exact", "`--exact` token counting");
+    const model = args.exactModel ?? DEFAULT_EXACT_MODEL;
+    const resolved = resolveSources({
+      paths: allFiles,
+      projectRoot: root,
+      required: false,
+      ...config.exclude !== void 0 ? { exclude: config.exclude } : {},
+      ...config.max_file_bytes !== void 0 ? { maxFileBytes: config.max_file_bytes } : {},
+      ...config.max_total_bytes !== void 0 ? { maxTotalBytes: config.max_total_bytes } : {}
+    });
+    const textBySha = new Map(resolved.sources.map((s) => [s.sha256, s.normalized]));
+    const seen = /* @__PURE__ */ new Set();
+    const requests = [];
+    for (const b of current.bundles) {
+      for (const f of b.files) {
+        if (seen.has(f.sha256)) continue;
+        seen.add(f.sha256);
+        const text = textBySha.get(f.sha256);
+        if (text === void 0) {
+          warnings.push({ code: "EXACT_SHA_MISMATCH", message: `--exact: skipping (content changed during the run)`, path: f.path });
+          continue;
+        }
+        requests.push({ sha256: f.sha256, model, text });
+      }
+    }
+    exactCounts = await countTokensExact(requests, args.exactLimit ?? DEFAULT_EXACT_LIMIT);
+  }
+  const exitCode = regression || lintResult.exitCode === 1 ? 1 : 0;
+  let cost;
+  if (args.cost !== false) {
+    if (lintResult.cost === void 0) {
+      for (const w of lintResult.warnings) {
+        if (w.code === COST_UNAVAILABLE_CODE) warnings.push(w);
+      }
+    } else {
+      try {
+        cost = {
+          ...lintResult.cost,
+          receipt: computeReceipt(bundles, lintResult.cost.normalizedCharsByFile, exactCounts, args.exactModel)
+        };
+      } catch (err) {
+        warnings.push(costUnavailableWarning(err));
+      }
+    }
+  }
+  return {
+    version: CACHELINT_VERSION,
+    configPath,
+    packLoaded: lintResult.packLoaded,
+    lockfilePath: lockPath,
+    diff,
+    regression,
+    diagnostics,
+    exactCounts,
+    warnings,
+    exitCode,
+    ...cost !== void 0 ? { cost } : {}
+  };
+}
+function computeReceipt(bundles, normalizedCharsByFile, exactCounts, exactModelArg) {
+  const ref = referencePricing();
+  let engagementMinimumTokens = ref.minCacheablePrefixTokens;
+  let engagementMinimumSource = ref.model;
+  if (exactModelArg !== void 0) {
+    const named = getModelPricing(exactModelArg);
+    if (named !== null && named.minCacheablePrefixTokens > engagementMinimumTokens) {
+      engagementMinimumTokens = named.minCacheablePrefixTokens;
+      engagementMinimumSource = named.model;
+    }
+  }
+  const exactBySha = exactCounts === null ? null : new Map(exactCounts.map((e) => [e.sha256, e.tokens]));
+  const entries = [];
+  let exactRefined = false;
+  let anyFallback = false;
+  for (const b of bundles) {
+    let heuristicSum = 0;
+    let exactSum = 0;
+    let fullyExact = exactBySha !== null;
+    for (const f of b.files) {
+      const chars = normalizedCharsByFile[f.path];
+      if (chars === void 0) {
+        throw new Error(
+          `cost estimate unavailable: ${f.path} is in the bundle but was not part of source resolution (binary, oversize, or excluded)`
+        );
+      }
+      heuristicSum += heuristicTokens(chars);
+      const exact = exactBySha?.get(f.sha256);
+      if (exact === void 0) fullyExact = false;
+      else exactSum += exact;
+    }
+    const useExact = exactBySha !== null && fullyExact;
+    if (exactBySha !== null) {
+      if (useExact) exactRefined = true;
+      else anyFallback = true;
+    }
+    const protectedTokens = useExact ? exactSum : heuristicSum;
+    const engaged = protectedTokens >= engagementMinimumTokens;
+    entries.push({
+      name: b.name,
+      protectedTokens,
+      tokenSource: useExact ? "exact" : "heuristic",
+      engaged,
+      ...engaged ? { protectedUsdPer1kCalls: usdPer1kCalls(protectedTokens, ref) } : {}
+    });
+  }
+  let engagedTokens = 0;
+  for (const e of entries) {
+    if (e.engaged) engagedTokens += e.protectedTokens;
+  }
+  return {
+    bundles: entries,
+    protectedTokens: engagedTokens,
+    protectedUsdPer1kCalls: usdPer1kCalls(engagedTokens, ref),
+    engagementMinimumTokens,
+    engagementMinimumSource,
+    exactRefined,
+    ...anyFallback ? { exactFallbackReason: RECEIPT_EXACT_FALLBACK_LINE } : {}
+  };
+}
+function renderCheckHuman(r) {
+  const lines = [];
+  if (r.packLoaded !== null) lines.push(`note  pack "${r.packLoaded}" loaded (no additional rules in this build yet)`);
+  for (const w of r.warnings) lines.push(`note  ${w.path ? w.path + ": " : ""}${w.message}`);
+  if (r.regression) {
+    lines.push("cachelint: cachelint.lock is out of date \u2014");
+    lines.push(renderDiffHuman(r.diff));
+  }
+  const label = r.cost !== void 0 ? costLabel({ model: r.cost.pricing.referenceModel }, r.cost.pricing.asOf) : "";
+  let errors = 0;
+  let warns = 0;
+  for (let i = 0; i < r.diagnostics.length; i++) {
+    const d = r.diagnostics[i];
+    if (d.severity === "error") errors++;
+    else warns++;
+    const level = d.severity === "error" ? "error  " : "warning";
+    lines.push(`${d.file}:${d.line}:${d.column}  ${level}  ${d.rule}  ${d.message}`);
+    if (d.whyUrl) lines.push(`  why: ${d.whyUrl}`);
+    const dc = r.cost?.perDiagnostic[i] ?? null;
+    if (dc !== null) {
+      if (!dc.countsTowardTotal) {
+        lines.push(`  ${COST_LINE_OVERLAPPED}`);
+      } else if (dc.volatility === "per-call") {
+        lines.push(`  ${costLineInvalidates(dc.fromHereTokens)}`);
+        const usd = dc.wastedUsdPer1kCalls !== void 0 ? formatUsdPer1k(dc.wastedUsdPer1kCalls) : null;
+        if (usd !== null) lines.push(`  ${costLineWasted(usd, label)}`);
+      } else {
+        lines.push(`  ${costLineAtRisk(dc.fromHereTokens)}`);
+      }
+    }
+  }
+  if (r.exactCounts) {
+    for (const e of r.exactCounts) lines.push(`tokens  ${e.sha256.slice(0, 12)}  ${e.tokens}  (${e.model})`);
+  }
+  if (r.exitCode === 0) {
+    lines.push(errors + warns > 0 ? `cachelint: lock OK; ${warns} warning${warns === 1 ? "" : "s"} (non-blocking)` : "cachelint: lock OK, no problems found.");
+    if (r.cost !== void 0) pushReceiptLines(lines, r.cost, label);
+  } else {
+    if (r.cost !== void 0) {
+      const summary = costSummary(r.cost.totals, label);
+      if (summary !== null) lines.push(`cachelint: ${summary}`);
+    }
+    const bits = [];
+    if (r.regression) bits.push("stable-prefix hash moved");
+    if (errors > 0) bits.push(`${errors} error-severity finding${errors === 1 ? "" : "s"}`);
+    if (!r.regression && errors === 0 && warns > 0) bits.push(`${warns} warning${warns === 1 ? "" : "s"} (elevated by --strict)`);
+    lines.push(`cachelint: FAILED \u2014 ${bits.length > 0 ? bits.join("; ") : "see above"}`);
+  }
+  return redactSecrets(lines.join("\n"));
+}
+function pushReceiptLines(lines, cost, label) {
+  for (const l of buildReceiptLines(cost, label)) lines.push(`cachelint: ${l}`);
+}
+function renderCheckJson(r, projectRoot = process.cwd()) {
+  return redactSecrets(
+    JSON.stringify(
+      {
+        version: r.version,
+        configPath: r.configPath,
+        packLoaded: r.packLoaded,
+        lockfilePath: toPosixRelative(r.lockfilePath, pathResolve(projectRoot)),
+        exitCode: r.exitCode,
+        regression: r.regression,
+        diff: r.diff,
+        diagnostics: r.diagnostics,
+        ...r.exactCounts ? { exactCounts: r.exactCounts } : {},
+        warnings: r.warnings,
+        // R4: present only when cost was computed — `--no-cost` (and
+        // degradation) omit the block by construction. The shared shape
+        // mirrors lint's cost block exactly; `receipt` is check-specific.
+        ...r.cost !== void 0 ? { cost: r.cost } : {}
+      },
+      null,
+      2
+    )
+  ) + "\n";
+}
+
+export {
+  check,
+  renderCheckHuman,
+  renderCheckJson
+};

package/dist/cli.d.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * v1.0 stability contract for cachelint's process exit codes.
+ *
+ * Imported by both the CLI (src/cli.ts) and the error taxonomy (src/errors.ts),
+ * which is why it lives in its own module — importing cli.ts has side effects
+ * (it calls `program.parseAsync`), and we want errors.ts to be safe to import
+ * anywhere.
+ *
+ * The table:
+ *   0  ok
+ *   1  hash moved / error-severity rule fired (real regression)
+ *   2  Pro feature invoked without a license (entitlement)
+ *   3  cachelint.lock missing or corrupt
+ *   4  config / source error (incl. missing ANTHROPIC_API_KEY when --exact IS licensed)
+ */
+declare const EXIT_OK = 0;
+declare const EXIT_CHECK_FAILED = 1;
+declare const EXIT_PRO_REQUIRED = 2;
+declare const EXIT_LOCK_PROBLEM = 3;
+declare const EXIT_CONFIG_OR_SOURCE_ERROR = 4;
+
+/**
+ * cachelint — CLI entry point.
+ *
+ * Unit 1 ships stub subcommands so the bin is real and `--help` / `--version`
+ * are instant; Units 2–4 fill in the actual behavior.
+ *
+ * Design notes:
+ *   - Heavy modules (rules engine, lockfile, license verify) are lazy-imported
+ *     INSIDE each action so cold-start for `--help` / `--version` stays fast.
+ *   - Exit codes are pinned (see Requirements R4 in the plan):
+ *       0  ok or only warns without --strict
+ *       1  hash moved / error-severity rule fired (real regression)
+ *       2  Pro feature invoked without a license (entitlement)
+ *       3  cachelint.lock missing or corrupt
+ *       4  config or source error (incl. missing ANTHROPIC_API_KEY when --exact IS licensed)
+ */
+
+/**
+ * Run the CLI. Extracted so the module can be imported in tests without
+ * arg parsing as a side effect.
+ */
+declare function runCli(argv?: readonly string[]): Promise<void>;
+
+export { EXIT_CHECK_FAILED, EXIT_CONFIG_OR_SOURCE_ERROR, EXIT_LOCK_PROBLEM, EXIT_OK, EXIT_PRO_REQUIRED, runCli };