cachelint 0.1.0

package/dist/index.js

@@ -0,0 +1,184 @@
+import {
+  check,
+  renderCheckHuman,
+  renderCheckJson
+} from "./chunk-ZSEZQ422.js";
+import {
+  activate,
+  deactivate,
+  licenseStatus
+} from "./chunk-JZU4PCTS.js";
+import "./chunk-UUVSBJ62.js";
+import {
+  KNOWN_PACK_IDS,
+  estimateCosts,
+  heuristicTokens,
+  lint,
+  renderLintHuman,
+  renderLintJson,
+  usdPer1kCalls
+} from "./chunk-2JSY5BQA.js";
+import {
+  PRICING_AS_OF,
+  PRICING_TABLE_VERSION,
+  REFERENCE_MODEL,
+  getModelPricing,
+  referencePricing,
+  wastePerTokenUsd
+} from "./chunk-O7ZE6CFI.js";
+import {
+  GRACE_PERIOD_DAYS,
+  activeLicenseInfo,
+  isPro,
+  requirePro,
+  verifyLicenseToken
+} from "./chunk-GXASKZ4Z.js";
+import "./chunk-4LB5LF2P.js";
+import {
+  allRules,
+  getRule,
+  ruleDocsUrl
+} from "./chunk-WKFGRNYK.js";
+import {
+  diffLockfiles,
+  isRegression
+} from "./chunk-DYQPXD3G.js";
+import {
+  COST_LINE_OVERLAPPED,
+  RECEIPT_EXACT_FALLBACK_LINE,
+  buildReceiptLines,
+  costLabel,
+  costLineAtRisk,
+  costLineInvalidates,
+  costLineWasted,
+  costSummary,
+  formatTokens,
+  formatUsdPer1k,
+  receiptAllBelowMinimumLine,
+  receiptProtectedLine,
+  receiptWarnQualifier,
+  receiptWontEngageLine
+} from "./chunk-VWE5TDL5.js";
+import {
+  hash,
+  renderHashHuman,
+  renderHashJson
+} from "./chunk-SQ4IAMTX.js";
+import {
+  DEFAULT_LOCKFILE_NAME,
+  LOCKFILE_FORMAT_VERSION,
+  canonicalJsonStringify,
+  parseLockfile,
+  serializeLockfile
+} from "./chunk-BUZCVKMZ.js";
+import {
+  CONFIG_FILENAMES,
+  configJsonSchema,
+  configSchema,
+  defineConfig,
+  loadConfig,
+  parseConfig,
+  resolveConfigArg
+} from "./chunk-MW7BXKPR.js";
+import {
+  DEFAULT_RULE_SEVERITY,
+  DEFAULT_RULE_VOLATILITY,
+  RULE_IDS
+} from "./chunk-4GHSUBAY.js";
+import {
+  CACHELINT_VERSION,
+  COST_MODEL_VERSION,
+  NORMALIZATION_POLICY_VERSION,
+  RULE_TABLE_VERSION
+} from "./chunk-WPJYUQMU.js";
+import {
+  AdapterError,
+  COST_UNAVAILABLE_CODE,
+  CachelintError,
+  ConfigError,
+  ExactCountUnavailableError,
+  LicenseError,
+  LockCorruptError,
+  LockError,
+  LockMissingError,
+  RuleError,
+  SourceError
+} from "./chunk-XKRPGMZT.js";
+export {
+  AdapterError,
+  CACHELINT_VERSION,
+  CONFIG_FILENAMES,
+  COST_LINE_OVERLAPPED,
+  COST_MODEL_VERSION,
+  COST_UNAVAILABLE_CODE,
+  CachelintError,
+  ConfigError,
+  DEFAULT_LOCKFILE_NAME,
+  DEFAULT_RULE_SEVERITY,
+  DEFAULT_RULE_VOLATILITY,
+  ExactCountUnavailableError,
+  GRACE_PERIOD_DAYS,
+  KNOWN_PACK_IDS,
+  LOCKFILE_FORMAT_VERSION,
+  LicenseError,
+  LockCorruptError,
+  LockError,
+  LockMissingError,
+  NORMALIZATION_POLICY_VERSION,
+  PRICING_AS_OF,
+  PRICING_TABLE_VERSION,
+  RECEIPT_EXACT_FALLBACK_LINE,
+  REFERENCE_MODEL,
+  RULE_IDS,
+  RULE_TABLE_VERSION,
+  RuleError,
+  SourceError,
+  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
+};

package/dist/license-GFDBTQHG.js

@@ -0,0 +1,19 @@
+import {
+  activate,
+  deactivate,
+  licenseStatus,
+  renderActivateHuman,
+  renderDeactivateHuman,
+  renderLicenseStatusHuman
+} from "./chunk-JZU4PCTS.js";
+import "./chunk-GXASKZ4Z.js";
+import "./chunk-4LB5LF2P.js";
+import "./chunk-XKRPGMZT.js";
+export {
+  activate,
+  deactivate,
+  licenseStatus,
+  renderActivateHuman,
+  renderDeactivateHuman,
+  renderLicenseStatusHuman
+};

package/dist/lint-PQHIDWOY.js

@@ -0,0 +1,19 @@
+import {
+  lint,
+  renderLintHuman,
+  renderLintJson
+} from "./chunk-2JSY5BQA.js";
+import "./chunk-O7ZE6CFI.js";
+import "./chunk-GXASKZ4Z.js";
+import "./chunk-4LB5LF2P.js";
+import "./chunk-WKFGRNYK.js";
+import "./chunk-VWE5TDL5.js";
+import "./chunk-MW7BXKPR.js";
+import "./chunk-4GHSUBAY.js";
+import "./chunk-WPJYUQMU.js";
+import "./chunk-XKRPGMZT.js";
+export {
+  lint,
+  renderLintHuman,
+  renderLintJson
+};

package/dist/sarif-EQ6VJNGN.js

@@ -0,0 +1,63 @@
+import {
+  allRules,
+  ruleDocsUrl
+} from "./chunk-WKFGRNYK.js";
+import "./chunk-4GHSUBAY.js";
+import {
+  CACHELINT_VERSION
+} from "./chunk-WPJYUQMU.js";
+import "./chunk-XKRPGMZT.js";
+
+// src/adapters/sarif.ts
+var SARIF_SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json";
+var INFORMATION_URI = "https://github.com/davioe/cachelint";
+function toSarif(diagnostics) {
+  const rules = allRules().map((r) => ({
+    id: r.id,
+    name: r.id,
+    shortDescription: { text: r.title },
+    helpUri: ruleDocsUrl(r.id),
+    defaultConfiguration: { level: r.defaultSeverity === "error" ? "error" : "warning" }
+  }));
+  const results = diagnostics.map((d) => ({
+    ruleId: d.rule,
+    level: d.severity === "error" ? "error" : "warning",
+    message: { text: d.fixHint ? `${d.message} \u2014 ${d.fixHint}` : d.message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: d.file },
+          region: {
+            startLine: d.line,
+            startColumn: d.column,
+            ...d.snippet ? { snippet: { text: d.snippet } } : {}
+          }
+        }
+      }
+    ]
+  }));
+  return {
+    $schema: SARIF_SCHEMA,
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "cachelint",
+            informationUri: INFORMATION_URI,
+            version: CACHELINT_VERSION,
+            rules
+          }
+        },
+        results
+      }
+    ]
+  };
+}
+function sarifString(diagnostics) {
+  return JSON.stringify(toSarif(diagnostics), null, 2) + "\n";
+}
+export {
+  sarifString,
+  toSarif
+};

package/dist/step-summary-NKD4N7AY.js

@@ -0,0 +1,160 @@
+import {
+  renderDiffHuman
+} from "./chunk-DYQPXD3G.js";
+import {
+  buildReceiptLines,
+  costLabel,
+  costLineAtRisk,
+  costSummary
+} from "./chunk-VWE5TDL5.js";
+import {
+  redactSecrets
+} from "./chunk-XKRPGMZT.js";
+
+// src/ci/step-summary.ts
+import { appendFileSync } from "fs";
+function stepSummaryPath(env = process.env) {
+  const optOut = env["CACHELINT_NO_STEP_SUMMARY"];
+  if (optOut !== void 0 && optOut.trim() !== "") return null;
+  const path = env["GITHUB_STEP_SUMMARY"];
+  if (path === void 0 || path.trim() === "") return null;
+  return path;
+}
+function mdEscapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function mdCell(s) {
+  return mdEscapeHtml(s).replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function fencedBlock(text) {
+  let longestRun = 0;
+  for (const m of text.matchAll(/`+/g)) {
+    if (m[0].length > longestRun) longestRun = m[0].length;
+  }
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  return [`${fence}text`, text, fence];
+}
+function findingsTableLines(diagnostics) {
+  if (diagnostics.length === 0) return ["No rule findings."];
+  const lines = ["| location | severity | rule | message |", "| --- | --- | --- | --- |"];
+  for (const d of diagnostics) {
+    const severity = d.severity === "error" ? "error" : "warning";
+    lines.push(`| \`${mdCell(`${d.file}:${d.line}:${d.column}`)}\` | ${severity} | ${mdCell(d.rule)} | ${mdCell(d.message)} |`);
+  }
+  return lines;
+}
+function problemTally(diagnostics) {
+  let errors = 0;
+  let warns = 0;
+  for (const d of diagnostics) {
+    if (d.severity === "error") errors++;
+    else warns++;
+  }
+  const parts = [];
+  if (errors > 0) parts.push(`${errors} error${errors === 1 ? "" : "s"}`);
+  if (warns > 0) parts.push(`${warns} warning${warns === 1 ? "" : "s"}`);
+  const total = diagnostics.length;
+  return `${total} problem${total === 1 ? "" : "s"} (${parts.join(", ")})`;
+}
+function costTotalsLines(cost) {
+  if (cost === void 0) return [];
+  const label = costLabel({ model: cost.pricing.referenceModel }, cost.pricing.asOf);
+  const summary = costSummary(cost.totals, label);
+  if (summary !== null) return [`**Cost:** ${summary}`];
+  if (cost.totals.atRiskTokens > 0) return [`**Cost:** ${costLineAtRisk(cost.totals.atRiskTokens)}`];
+  return [];
+}
+function renderLintSection(result) {
+  const lines = ["## cachelint lint", ""];
+  lines.push(...findingsTableLines(result.diagnostics));
+  lines.push("");
+  lines.push(
+    result.diagnostics.length === 0 ? "**Result:** no problems found (exit code 0)" : `**Result:** ${problemTally(result.diagnostics)} \u2014 exit code ${result.exitCode}`
+  );
+  const cost = costTotalsLines(result.cost);
+  if (cost.length > 0) {
+    lines.push("");
+    lines.push(...cost);
+  }
+  return lines.join("\n");
+}
+function receiptLines(cost, label) {
+  return buildReceiptLines(cost, label).map((l) => `- ${mdEscapeHtml(l)}`);
+}
+function renderCheckSection(r) {
+  const lines = ["## cachelint check", ""];
+  if (r.regression) {
+    lines.push("**Bundle stability:** REGRESSION \u2014 `cachelint.lock` is out of date:", "", ...fencedBlock(renderDiffHuman(r.diff)));
+  } else {
+    lines.push("**Bundle stability:** lock OK \u2014 `cachelint.lock` matches the current sources.");
+  }
+  lines.push("");
+  lines.push(...findingsTableLines(r.diagnostics));
+  lines.push("");
+  lines.push(`**Result:** ${r.exitCode === 0 ? "PASSED (exit code 0)" : "FAILED (exit code 1)"}`);
+  if (r.cost !== void 0) {
+    const label = costLabel({ model: r.cost.pricing.referenceModel }, r.cost.pricing.asOf);
+    const cost = r.exitCode === 0 ? receiptLines(r.cost, label) : costTotalsLines(r.cost);
+    if (cost.length > 0) {
+      lines.push("");
+      lines.push(...cost);
+    }
+  }
+  return lines.join("\n");
+}
+function renderFailureSection(command, exitCode, err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const headline = message.split("\n")[0] ?? "";
+  return [
+    `## cachelint ${command} \u2014 error`,
+    "",
+    `\`cachelint ${command}\` did not complete (exit code ${exitCode}): ${headline === "" ? "unknown error" : mdEscapeHtml(headline)}`
+  ].join("\n");
+}
+function appendStepSummary(markdown, env = process.env) {
+  const path = stepSummaryPath(env);
+  if (path === null) return;
+  try {
+    appendFileSync(path, redactSecrets(markdown) + "\n\n", "utf8");
+  } catch (e) {
+    noteFailure(e);
+  }
+}
+function noteFailure(e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  try {
+    process.stderr.write(redactSecrets(`cachelint: could not append the CI step summary (${msg}) \u2014 continuing
+`));
+  } catch {
+  }
+}
+function writeSection(render, env) {
+  if (stepSummaryPath(env) === null) return;
+  let markdown;
+  try {
+    markdown = render();
+  } catch (e) {
+    noteFailure(e);
+    return;
+  }
+  appendStepSummary(markdown, env);
+}
+function writeLintStepSummary(result, env = process.env) {
+  writeSection(() => renderLintSection(result), env);
+}
+function writeCheckStepSummary(result, env = process.env) {
+  writeSection(() => renderCheckSection(result), env);
+}
+function writeFailureStepSummary(context, exitCode, err, env = process.env) {
+  writeSection(() => renderFailureSection(context.command, exitCode, err), env);
+}
+export {
+  appendStepSummary,
+  renderCheckSection,
+  renderFailureSection,
+  renderLintSection,
+  stepSummaryPath,
+  writeCheckStepSummary,
+  writeFailureStepSummary,
+  writeLintStepSummary
+};

package/dist/store-KZIQANIT.js

@@ -0,0 +1,14 @@
+import {
+  clearStoredLicense,
+  hasEnvLicense,
+  licenseFilePath,
+  readStoredLicense,
+  writeStoredLicense
+} from "./chunk-4LB5LF2P.js";
+export {
+  clearStoredLicense,
+  hasEnvLicense,
+  licenseFilePath,
+  readStoredLicense,
+  writeStoredLicense
+};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "cachelint",
+  "version": "0.1.0",
+  "description": "A linter + CI gate for LLM prompt-cache regressions. Catches the silent-invalidator class (interpolated timestamps, unsorted JSON, BOM, mixed line endings) and fails PRs when a committed prompt's stable-prefix hash moves.",
+  "license": "MIT",
+  "author": "cachelint contributors",
+  "homepage": "https://github.com/davioe/cachelint",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davioe/cachelint.git"
+  },
+  "bugs": {
+    "url": "https://github.com/davioe/cachelint/issues"
+  },
+  "keywords": [
+    "llm",
+    "prompt",
+    "prompt-cache",
+    "prompt-caching",
+    "anthropic",
+    "claude",
+    "openai",
+    "linter",
+    "ci",
+    "cache-control",
+    "cachelint",
+    "developer-tools",
+    "lint"
+  ],
+  "type": "module",
+  "bin": {
+    "cachelint": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist/",
+    "schema/",
+    "README.md",
+    "LICENSE",
+    "LICENSE-PRO.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "clean": "node -e \"for (const d of ['dist','coverage']) require('node:fs').rmSync(d,{recursive:true,force:true})\"",
+    "pack:check": "node scripts/check-pack-allowlist.mjs",
+    "prepublishOnly": "npm run build && npm run pack:check"
+  },
+  "dependencies": {
+    "acorn": "^8.16.0",
+    "acorn-walk": "^8.3.5",
+    "commander": "^14.0.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/schema/cachelint.config.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "prompt_globs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "exclude": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "disable": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "R001",
+          "R002",
+          "R003",
+          "R004",
+          "R005"
+        ]
+      }
+    },
+    "rules": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "enum": [
+          "R001",
+          "R002",
+          "R003",
+          "R004",
+          "R005"
+        ]
+      },
+      "additionalProperties": {
+        "type": "string",
+        "enum": [
+          "off",
+          "warn",
+          "error"
+        ]
+      }
+    },
+    "bundles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "files": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "required": [
+          "name",
+          "files"
+        ],
+        "additionalProperties": false,
+        "description": "A named, ordered group of files hashed together as one cache prefix."
+      }
+    },
+    "max_file_bytes": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "max_total_bytes": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "pro": {
+      "type": "object",
+      "properties": {
+        "exact_limit": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "packs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": false,
+      "description": "Pro-tier settings (only consulted when a Pro feature is invoked with a valid license)."
+    }
+  },
+  "additionalProperties": false,
+  "description": "cachelint configuration (cachelint.config.json / .yaml / .yml)."
+}