avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/cost-abuse-guard.js

@@ -0,0 +1,975 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const { nowIso, safeReadJson, safeWriteJson } = require("./fsx");
+
+const CONTRACT = "avorelo.costAbuseGuard.v1";
+const REPORT_DIR_REL = ".claude/cco/reports/cost-abuse-guard";
+const REPORT_JSON_REL = `${REPORT_DIR_REL}/latest-report.json`;
+
+const TEXT_FILE_RE = /\.(cjs|cts|env|ini|js|json|jsx|md|mjs|mts|prisma|sql|toml|ts|tsx|txt|yaml|yml)$/i;
+const SKIP_DIRS = new Set([
+  ".claude",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".wasp",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+]);
+
+// ---------------------------------------------------------------------------
+// Detection patterns
+// ---------------------------------------------------------------------------
+
+const RETRY_RE = /\b(retry|retries|backoff|retryable|exponentialBackoff|retryWithBackoff|retryDelay|maxRetries|retryCount|retryInterval)\b/i;
+const RETRY_BOUNDED_RE = /\b(maxRetries|max_retries|retryLimit|retry_limit|MAX_RETRIES|MAX_RETRY|retryCount\s*[<>=]|attempts\s*[<>=]|retries\s*[<>=])\b/i;
+const POLLING_RE = /\b(setInterval|polling|poll|pollInterval|startPolling|pollUntil|longPoll)\b/i;
+const POLLING_BOUNDED_RE = /\b(clearInterval|setTimeout|maxPolls|pollTimeout|stopPolling|MAX_POLLS|AbortController)\b/i;
+const SCHEDULED_JOB_RE = /\b(cron|schedule|node-cron|node_cron|cronJob|scheduledTask|agenda|bull|bullmq|bree)\b/i;
+const QUEUE_WORKER_RE = /\b(queue|worker|bull|bullmq|amqp|amqplib|rabbitmq|celery|bee-queue|pgboss|faktory)\b/i;
+const BATCH_JOB_RE = /\b(batch|bulk|batchProcess|bulkInsert|bulkCreate|bulkWrite|batchSize|BATCH_SIZE)\b/i;
+const BATCH_BOUNDED_RE = /\b(batchSize|batch_size|BATCH_SIZE|limit|chunkSize|chunk_size|pageSize|page_size)\b/i;
+const RATE_LIMIT_RE = /\b(rateLimit|rate_limit|rateLimiter|throttle|express-rate-limit|@upstash\/ratelimit|bottleneck|p-throttle|limiter)\b/i;
+const TIMEOUT_RE = /\b(timeout|setTimeout|AbortController|signal|requestTimeout|connectTimeout|idleTimeout|keepAliveTimeout)\b/i;
+const CONCURRENCY_RE = /\b(concurrency|parallel|pool|pLimit|p-limit|Promise\.all|Promise\.allSettled|workerPool|threadPool|cluster\.fork)\b/i;
+const CONCURRENCY_BOUNDED_RE = /\b(pLimit|p-limit|concurrency\s*[:=]\s*\d|maxConcurrency|MAX_CONCURRENCY|pool\s*[:=]\s*\d|poolSize|maxWorkers|max_workers)\b/i;
+const PUBLIC_ENDPOINT_RE = /\b(app\.(get|post|put|patch|delete)\s*\(|router\.(get|post|put|patch|delete)\s*\(|export\s+(async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\b|export\s+const\s+(GET|POST|PUT|PATCH|DELETE)\b)\b/;
+const AUTH_MIDDLEWARE_RE = /\b(auth|authenticate|requireAuth|requireUser|verifyToken|getServerSession|clerkMiddleware|authMiddleware|isAuthenticated|passport\.authenticate|jwt\.verify|verifyAuth)\b/i;
+const AI_TOOL_LOOP_RE = /\b(while|for)\b[\s\S]{0,200}\b(tool_call|toolCall|function_call|functionCall|tool_use|toolUse|runTools|executeTools|completions\.create|chat\.completions|anthropic\.messages|openai\.chat)\b/i;
+const AI_MODEL_RE = /\b(openai|anthropic|completions\.create|chat\.completions|messages\.create|generateText|streamText|ai\.run|model\.generate|llm\.call)\b/i;
+const EXPENSIVE_SCRIPT_RE = /\b(ffmpeg|sharp|imagemagick|puppeteer|playwright|chromium|headless|pdf|render|transcode|encode|compress|crypto\.pbkdf2|crypto\.scrypt|bcrypt\.hash)\b/i;
+const PAYMENT_RE = /\b(stripe|payment|billing|charge|invoice|subscription|checkout|paymentIntent|createCharge|createPaymentIntent|createSubscription)\b/i;
+const FREE_TRIAL_RE = /\b(trial|free.plan|freemium|free.tier|trialEnd|trialDays|isTrial|FREE_PLAN|FREE_TIER)\b/i;
+const CACHE_RE = /\b(cache|redis|memoize|lru-cache|node-cache|ioredis|memcached|cacheControl|stale-while-revalidate|unstable_cache|revalidate)\b/i;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function sanitizeText(value, max = 220) {
+  const text = String(value || "")
+    .replace(/\s+/g, " ")
+    .replace(/(?:sk-[A-Za-z0-9_-]{16,}|gh[ps]_[A-Za-z0-9]{12,}|npm_[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{16})/g, "[redacted-token]")
+    .replace(/(bearer\s+)[A-Za-z0-9._-]{8,}/ig, "$1[redacted]")
+    .replace(/((?:api[_ -]?key|token|password|secret|authorization)\s*[:=]\s*)([^\s'"]+)/ig, "$1[redacted]")
+    .trim();
+  if (!text) return null;
+  return text.length > max ? `${text.slice(0, max - 3).trimEnd()}...` : text;
+}
+
+function sanitizeRef(ref) {
+  const text = String(ref || "").trim().replace(/\\/g, "/");
+  if (!text || text.startsWith("..")) return null;
+  return text;
+}
+
+function makeEvidenceRef(relPath, lineNumber, label) {
+  const base = sanitizeRef(relPath);
+  if (!base) return null;
+  const suffix = Number.isFinite(lineNumber) && lineNumber > 0 ? `:${lineNumber}` : "";
+  const note = label ? ` (${sanitizeText(label, 80)})` : "";
+  return `${base}${suffix}${note}`;
+}
+
+function severityRank(severity) {
+  if (severity === "block") return 4;
+  if (severity === "warn") return 3;
+  if (severity === "info") return 2;
+  return 1;
+}
+
+// ---------------------------------------------------------------------------
+// Filesystem
+// ---------------------------------------------------------------------------
+
+function walkWorkspace(cwd) {
+  const files = [];
+
+  function visit(current, depth) {
+    if (depth > 8 || files.length >= 2200) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (files.length >= 2200) return;
+      const absPath = path.join(current, entry.name);
+      const relPath = toPosix(path.relative(cwd, absPath));
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        visit(absPath, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      files.push({
+        absPath,
+        relPath,
+        text: undefined,
+      });
+    }
+  }
+
+  visit(cwd, 0);
+  return files;
+}
+
+function readText(file) {
+  if (file.text !== undefined) return file.text;
+  if (!TEXT_FILE_RE.test(file.relPath)) {
+    file.text = null;
+    return file.text;
+  }
+  try {
+    const stat = fs.statSync(file.absPath);
+    if (stat.size > 256 * 1024) {
+      file.text = null;
+      return file.text;
+    }
+    file.text = fs.readFileSync(file.absPath, "utf8");
+    return file.text;
+  } catch {
+    file.text = null;
+    return file.text;
+  }
+}
+
+function findLineNumber(text, index) {
+  return text.slice(0, index).split(/\r?\n/).length;
+}
+
+function collectPatternRefs(file, regex, options = {}) {
+  const text = readText(file);
+  if (!text) return [];
+  const limit = options.limit || 5;
+  const refs = [];
+  const flags = regex.flags.includes("g") ? regex.flags : `${regex.flags}g`;
+  const matcher = new RegExp(regex.source, flags);
+  let match;
+  while ((match = matcher.exec(text)) && refs.length < limit) {
+    const lineNumber = findLineNumber(text, match.index);
+    refs.push(makeEvidenceRef(file.relPath, lineNumber, options.label ? options.label(match) : null));
+    if (match.index === matcher.lastIndex) matcher.lastIndex += 1;
+  }
+  return refs.filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// Report scaffold
+// ---------------------------------------------------------------------------
+
+function buildEmptyReport(startTime) {
+  return {
+    schemaVersion: CONTRACT,
+    generatedAt: nowIso(),
+    status: "no_data",
+    redacted: true,
+    summary: {
+      title: "Cost & Abuse Guard",
+      text: "No cost or abuse surface detected.",
+      findingCounts: { info: 0, warn: 0, block: 0 },
+      safeNextAction: "No cost or abuse surface was detected. Re-run after adding runtime, API, or scheduling code.",
+    },
+    surfaceEvidence: {
+      filesInspected: 0,
+      artifactsInspected: 0,
+      changedFilesConsidered: 0,
+      surfacesDetected: [],
+      limitsApplied: [],
+    },
+    findings: [],
+    productHome: {
+      cardSource: "costAbuseGuard",
+      status: "no_data",
+      found: [],
+      fixedOrPrepared: [],
+      savedOrProved: [],
+      forReview: [],
+      safeNextAction: "No cost or abuse surface was detected.",
+    },
+    valueProof: {
+      implemented: true,
+      dogfooded: false,
+      measured: false,
+      measurementType: "heuristic",
+      publicClaimAllowed: false,
+      evidenceRefs: [],
+      caveat: "Local static scan only. No billing or provider API calls.",
+    },
+    limits: {
+      localFirst: true,
+      deterministicFirst: true,
+      modelCalls: false,
+      networkCalls: false,
+      providerCalls: false,
+      rawLogDump: false,
+      rawPromptDump: false,
+      rawCodeDump: false,
+      secretDump: false,
+      autoFix: false,
+    },
+    overhead: {
+      durationMs: 0,
+      filesInspected: 0,
+      artifactsInspected: 0,
+      limitsApplied: [],
+    },
+    _startTime: startTime,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+function createState() {
+  return {
+    seenFindingIds: new Set(),
+    surfacesDetected: new Set(),
+    limitsApplied: [],
+    findingCounter: 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Finding helpers
+// ---------------------------------------------------------------------------
+
+function addFinding(report, state, fields) {
+  const evidenceRef = sanitizeRef(fields.evidenceRef);
+  const key = `${fields.reasonCode}:${evidenceRef || "none"}`;
+  if (state.seenFindingIds.has(key)) return;
+  state.seenFindingIds.add(key);
+
+  state.findingCounter += 1;
+  const id = `cost-abuse-${String(state.findingCounter).padStart(3, "0")}`;
+
+  const finding = {
+    id,
+    severity: fields.severity,
+    reasonCode: fields.reasonCode,
+    title: sanitizeText(fields.title, 120),
+    message: sanitizeText(fields.message || fields.title, 220),
+    evidenceRefs: [
+      evidenceRef ? { path: evidenceRef, kind: fields.kind || "pattern", selector: fields.selector || null, redacted: true } : null,
+    ].filter(Boolean),
+    safeNextAction: sanitizeText(fields.safeNextAction, 220) || "Review cost or abuse surfaces before trusting this path.",
+  };
+  report.findings.push(finding);
+}
+
+function addSurface(state, name) {
+  state.surfacesDetected.add(name);
+}
+
+// ---------------------------------------------------------------------------
+// Detection: retry loops
+// ---------------------------------------------------------------------------
+
+function detectRetryLoops(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!RETRY_RE.test(text)) continue;
+
+    addSurface(state, "retry_loop");
+    const bounded = RETRY_BOUNDED_RE.test(text);
+    const refs = collectPatternRefs(file, RETRY_RE, { limit: 2 });
+    const ref = refs[0];
+
+    if (bounded) {
+      addFinding(report, state, {
+        severity: "info",
+        reasonCode: "COST_ABUSE_RETRY_BOUNDED",
+        title: "Retry with max cap detected",
+        message: "Retry loop appears bounded with a max-retries limit.",
+        evidenceRef: ref,
+        kind: "pattern",
+        safeNextAction: "Verify the retry cap is reasonable for production load.",
+      });
+    } else {
+      addFinding(report, state, {
+        severity: "warn",
+        reasonCode: "COST_ABUSE_RETRY_UNBOUNDED",
+        title: "Retry without max cap",
+        message: "Retry or backoff pattern found without a visible max-retries limit.",
+        evidenceRef: ref,
+        kind: "pattern",
+        safeNextAction: "Add a max-retries cap or circuit breaker before trusting this retry path.",
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: polling loops
+// ---------------------------------------------------------------------------
+
+function detectPollingLoops(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!POLLING_RE.test(text)) continue;
+
+    addSurface(state, "polling_loop");
+    const bounded = POLLING_BOUNDED_RE.test(text);
+    const refs = collectPatternRefs(file, POLLING_RE, { limit: 2 });
+    const ref = refs[0];
+
+    if (bounded) {
+      addFinding(report, state, {
+        severity: "info",
+        reasonCode: "COST_ABUSE_POLLING_FOUND",
+        title: "Polling with timeout detected",
+        message: "Polling pattern found with visible timeout or cleanup.",
+        evidenceRef: ref,
+        kind: "pattern",
+        safeNextAction: "Verify the polling timeout is reasonable for production.",
+      });
+    } else {
+      addFinding(report, state, {
+        severity: "warn",
+        reasonCode: "COST_ABUSE_POLLING_UNBOUNDED",
+        title: "Polling without timeout",
+        message: "Polling or setInterval pattern found without a visible timeout or clearInterval.",
+        evidenceRef: ref,
+        kind: "pattern",
+        safeNextAction: "Add a timeout or max-polls limit before trusting this polling path.",
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: scheduled jobs
+// ---------------------------------------------------------------------------
+
+function detectScheduledJobs(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!SCHEDULED_JOB_RE.test(text)) continue;
+
+    addSurface(state, "scheduled_job");
+    const refs = collectPatternRefs(file, SCHEDULED_JOB_RE, { limit: 2 });
+
+    addFinding(report, state, {
+      severity: "info",
+      reasonCode: "COST_ABUSE_SURFACE_FOUND",
+      title: "Scheduled job or cron pattern detected",
+      message: "Cron or scheduling pattern detected. Verify cost bounds.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: "Verify that scheduled jobs have bounded execution time and cost limits.",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: queue workers
+// ---------------------------------------------------------------------------
+
+function detectQueueWorkers(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!QUEUE_WORKER_RE.test(text)) continue;
+
+    addSurface(state, "queue_worker");
+    const hasConcurrency = CONCURRENCY_BOUNDED_RE.test(text);
+    const refs = collectPatternRefs(file, QUEUE_WORKER_RE, { limit: 2 });
+
+    addFinding(report, state, {
+      severity: hasConcurrency ? "info" : "warn",
+      reasonCode: hasConcurrency ? "COST_ABUSE_QUEUE_WORKER_FOUND" : "COST_ABUSE_MISSING_CONCURRENCY_LIMIT",
+      title: hasConcurrency ? "Queue worker with concurrency limit" : "Queue worker without visible concurrency limit",
+      message: hasConcurrency
+        ? "Queue worker pattern detected with a visible concurrency limit."
+        : "Queue worker pattern detected without a visible concurrency or pool limit.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: hasConcurrency
+        ? "Verify the concurrency limit is appropriate for production."
+        : "Add a concurrency or pool limit to the queue worker before trusting this path.",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: batch jobs
+// ---------------------------------------------------------------------------
+
+function detectBatchJobs(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!BATCH_JOB_RE.test(text)) continue;
+
+    addSurface(state, "batch_job");
+    const bounded = BATCH_BOUNDED_RE.test(text);
+    const refs = collectPatternRefs(file, BATCH_JOB_RE, { limit: 2 });
+
+    if (bounded) {
+      addFinding(report, state, {
+        severity: "info",
+        reasonCode: "COST_ABUSE_BATCH_JOB_FOUND",
+        title: "Batch job with size limit detected",
+        message: "Batch or bulk pattern detected with a visible size limit.",
+        evidenceRef: refs[0],
+        kind: "pattern",
+        safeNextAction: "Verify the batch size is reasonable for production load.",
+      });
+    } else {
+      addFinding(report, state, {
+        severity: "warn",
+        reasonCode: "COST_ABUSE_BATCH_UNBOUNDED",
+        title: "Batch job without visible size limit",
+        message: "Batch or bulk pattern detected without a visible batch size or limit.",
+        evidenceRef: refs[0],
+        kind: "pattern",
+        safeNextAction: "Add a batch size or limit before trusting this batch path.",
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: rate limiting
+// ---------------------------------------------------------------------------
+
+function detectRateLimiting(report, state, files) {
+  let hasRateLimitLib = false;
+
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!RATE_LIMIT_RE.test(text)) continue;
+
+    addSurface(state, "rate_limit");
+    hasRateLimitLib = true;
+    const refs = collectPatternRefs(file, RATE_LIMIT_RE, { limit: 2 });
+
+    addFinding(report, state, {
+      severity: "info",
+      reasonCode: "COST_ABUSE_RATE_LIMIT_FOUND",
+      title: "Rate limiting evidence detected",
+      message: "Rate-limit or throttle pattern found.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: "Verify rate limits are applied to all public and cost-sensitive endpoints.",
+    });
+  }
+
+  return hasRateLimitLib;
+}
+
+// ---------------------------------------------------------------------------
+// Detection: timeouts
+// ---------------------------------------------------------------------------
+
+function detectTimeouts(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!TIMEOUT_RE.test(text)) continue;
+    // Skip if it's just a test file or config
+    if (/\.(test|spec|config)\./i.test(file.relPath)) continue;
+
+    addSurface(state, "timeout");
+    const refs = collectPatternRefs(file, /\b(AbortController|requestTimeout|connectTimeout|idleTimeout)\b/i, { limit: 2 });
+    if (refs.length > 0) {
+      addFinding(report, state, {
+        severity: "info",
+        reasonCode: "COST_ABUSE_TIMEOUT_FOUND",
+        title: "Timeout or abort evidence detected",
+        message: "Timeout or AbortController usage found.",
+        evidenceRef: refs[0],
+        kind: "pattern",
+        safeNextAction: "Verify timeouts cover all external and cost-sensitive calls.",
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: concurrency
+// ---------------------------------------------------------------------------
+
+function detectConcurrency(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!CONCURRENCY_RE.test(text)) continue;
+
+    addSurface(state, "concurrency");
+    const bounded = CONCURRENCY_BOUNDED_RE.test(text);
+    const refs = collectPatternRefs(file, CONCURRENCY_RE, { limit: 2 });
+
+    if (bounded) {
+      addFinding(report, state, {
+        severity: "info",
+        reasonCode: "COST_ABUSE_CONCURRENCY_LIMIT_FOUND",
+        title: "Concurrency limit detected",
+        message: "Concurrency or parallel pattern with a visible limit.",
+        evidenceRef: refs[0],
+        kind: "pattern",
+        safeNextAction: "Verify the concurrency limit is appropriate for production.",
+      });
+    } else {
+      addFinding(report, state, {
+        severity: "warn",
+        reasonCode: "COST_ABUSE_MISSING_CONCURRENCY_LIMIT",
+        title: "Concurrency without visible limit",
+        message: "Parallel or pool pattern found without a visible concurrency cap.",
+        evidenceRef: refs[0],
+        kind: "pattern",
+        safeNextAction: "Add a concurrency limit before trusting this parallel execution path.",
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: public endpoints without auth/rate-limit
+// ---------------------------------------------------------------------------
+
+function detectPublicEndpoints(report, state, files, hasRateLimitLib) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!PUBLIC_ENDPOINT_RE.test(text)) continue;
+
+    addSurface(state, "public_endpoint");
+    const hasAuth = AUTH_MIDDLEWARE_RE.test(text);
+    const hasRateLimit = RATE_LIMIT_RE.test(text);
+    const refs = collectPatternRefs(file, PUBLIC_ENDPOINT_RE, { limit: 2 });
+
+    if (!hasAuth && !hasRateLimit) {
+      addFinding(report, state, {
+        severity: "warn",
+        reasonCode: "COST_ABUSE_MISSING_RATE_LIMIT",
+        title: "Public endpoint without auth or rate limit",
+        message: "API endpoint found without visible auth middleware or rate limiting.",
+        evidenceRef: refs[0],
+        kind: "pattern",
+        safeNextAction: "Add rate limiting or auth middleware to public endpoints before production.",
+      });
+    } else {
+      addFinding(report, state, {
+        severity: "info",
+        reasonCode: "COST_ABUSE_PUBLIC_ENDPOINT_FOUND",
+        title: "Public endpoint with protection evidence",
+        message: `API endpoint found with ${hasAuth ? "auth" : ""}${hasAuth && hasRateLimit ? " and " : ""}${hasRateLimit ? "rate limit" : ""} evidence.`,
+        evidenceRef: refs[0],
+        kind: "pattern",
+        safeNextAction: "Verify all public endpoints have adequate rate limiting and auth.",
+      });
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: AI tool loops
+// ---------------------------------------------------------------------------
+
+function detectAiToolLoops(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!AI_MODEL_RE.test(text)) continue;
+
+    const hasLoop = AI_TOOL_LOOP_RE.test(text);
+    if (hasLoop) {
+      addSurface(state, "ai_tool_loop");
+      const hasBound = /\b(maxIterations|max_iterations|MAX_ITERATIONS|maxSteps|max_steps|maxToolCalls|maxRounds|iteration\s*[<>=]|step\s*[<>=])\b/i.test(text);
+      const refs = collectPatternRefs(file, AI_TOOL_LOOP_RE, { limit: 2 });
+
+      if (hasBound) {
+        addFinding(report, state, {
+          severity: "warn",
+          reasonCode: "COST_ABUSE_AI_TOOL_LOOP_FOUND",
+          title: "AI tool loop with iteration bound",
+          message: "AI model call inside a loop with a visible iteration limit.",
+          evidenceRef: refs[0],
+          kind: "pattern",
+          safeNextAction: "Verify the AI loop iteration cap and cost budget are appropriate for production.",
+        });
+      } else {
+        addFinding(report, state, {
+          severity: "block",
+          reasonCode: "COST_ABUSE_AI_TOOL_LOOP_FOUND",
+          title: "AI tool loop without visible iteration bound",
+          message: "AI model call inside a loop without a visible max-iterations or max-steps limit. This is a cost runaway risk.",
+          evidenceRef: refs[0],
+          kind: "pattern",
+          safeNextAction: "Add a max-iterations or cost budget cap to the AI tool loop before production.",
+        });
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: expensive scripts
+// ---------------------------------------------------------------------------
+
+function detectExpensiveScripts(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!EXPENSIVE_SCRIPT_RE.test(text)) continue;
+
+    addSurface(state, "expensive_script");
+    const hasTimeout = TIMEOUT_RE.test(text);
+    const refs = collectPatternRefs(file, EXPENSIVE_SCRIPT_RE, { limit: 2 });
+
+    addFinding(report, state, {
+      severity: hasTimeout ? "info" : "warn",
+      reasonCode: hasTimeout ? "COST_ABUSE_SURFACE_FOUND" : "COST_ABUSE_MISSING_TIMEOUT",
+      title: hasTimeout ? "Expensive compute with timeout" : "Expensive compute without visible timeout",
+      message: hasTimeout
+        ? "Heavy compute pattern detected with timeout evidence."
+        : "Heavy compute pattern (image processing, PDF, headless browser, etc.) without a visible timeout.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: hasTimeout
+        ? "Verify the timeout is reasonable for production workloads."
+        : "Add a timeout or resource limit to expensive compute before production.",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: abuse surfaces (public endpoints without rate limit)
+// ---------------------------------------------------------------------------
+
+function detectAbuseSurfaces(report, state, files) {
+  // This is covered by detectPublicEndpoints above; we add a second pass
+  // specifically looking for API route files (Next.js / Express) that lack
+  // any rate-limit import in the same file OR a middleware-level rate limit.
+  for (const file of files) {
+    if (!/\/(app\/api\/|pages\/api\/|server\/routes\/)/.test(file.relPath)) continue;
+    const text = readText(file);
+    if (!text) continue;
+    if (RATE_LIMIT_RE.test(text)) continue;
+    if (!PUBLIC_ENDPOINT_RE.test(text) && !/\bexport\b/.test(text)) continue;
+
+    addSurface(state, "abuse_surface");
+    const refs = collectPatternRefs(file, /\bexport\s+(async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\b/i, { limit: 1 });
+    if (refs.length === 0) continue;
+
+    addFinding(report, state, {
+      severity: "warn",
+      reasonCode: "COST_ABUSE_MISSING_RATE_LIMIT",
+      title: "API route without file-level rate limit",
+      message: "API route handler lacks a visible rate-limit import in the same file.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: "Add rate limiting at the route or middleware level before production.",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: payment surfaces
+// ---------------------------------------------------------------------------
+
+function detectPaymentSurfaces(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!PAYMENT_RE.test(text)) continue;
+
+    addSurface(state, "payment_surface");
+    const refs = collectPatternRefs(file, PAYMENT_RE, { limit: 2 });
+
+    addFinding(report, state, {
+      severity: "warn",
+      reasonCode: "COST_ABUSE_PAYMENT_SURFACE_FOUND",
+      title: "Payment or billing surface detected",
+      message: "Stripe, payment, or billing pattern found. Review for idempotency and abuse protection.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: "Verify payment endpoints have idempotency keys, rate limits, and webhook signature verification.",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: free trial surfaces
+// ---------------------------------------------------------------------------
+
+function detectFreeTrialSurfaces(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!FREE_TRIAL_RE.test(text)) continue;
+
+    addSurface(state, "free_trial_surface");
+    const refs = collectPatternRefs(file, FREE_TRIAL_RE, { limit: 2 });
+
+    addFinding(report, state, {
+      severity: "info",
+      reasonCode: "COST_ABUSE_FREE_TRIAL_SURFACE_FOUND",
+      title: "Free trial or freemium surface detected",
+      message: "Trial or free-plan pattern found. Review for abuse potential.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: "Verify free-tier usage limits and trial abuse protections are in place.",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Detection: cache surfaces
+// ---------------------------------------------------------------------------
+
+function detectCacheSurfaces(report, state, files) {
+  for (const file of files) {
+    const text = readText(file);
+    if (!text) continue;
+    if (!CACHE_RE.test(text)) continue;
+
+    addSurface(state, "cache_surface");
+    const refs = collectPatternRefs(file, CACHE_RE, { limit: 2 });
+
+    addFinding(report, state, {
+      severity: "info",
+      reasonCode: "COST_ABUSE_SURFACE_FOUND",
+      title: "Cache surface detected",
+      message: "Cache, Redis, or memoization pattern found.",
+      evidenceRef: refs[0],
+      kind: "pattern",
+      safeNextAction: "Verify cache TTLs and eviction are appropriate for cost control.",
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Finalization
+// ---------------------------------------------------------------------------
+
+function finalizeReport(report, state, startTime) {
+  // Remove internal field
+  delete report._startTime;
+
+  const findings = report.findings.sort((a, b) => severityRank(b.severity) - severityRank(a.severity));
+  report.findings = findings;
+
+  const infos = findings.filter((f) => f.severity === "info").length;
+  const warns = findings.filter((f) => f.severity === "warn").length;
+  const blocks = findings.filter((f) => f.severity === "block").length;
+
+  report.summary.findingCounts = { info: infos, warn: warns, block: blocks };
+
+  const surfacesDetected = [...state.surfacesDetected];
+  report.surfaceEvidence.surfacesDetected = surfacesDetected;
+
+  // Determine status
+  if (surfacesDetected.length === 0) {
+    report.status = "no_data";
+    report.summary.text = "No cost or abuse surface detected.";
+    report.summary.safeNextAction = "No cost or abuse surface was detected. Re-run after adding runtime, API, or scheduling code.";
+  } else if (blocks > 0) {
+    report.status = "blocked";
+    const firstBlock = findings.find((f) => f.severity === "block");
+    report.summary.text = `${surfacesDetected.length} surface(s) detected. ${blocks} blocker(s) found.`;
+    report.summary.safeNextAction = firstBlock?.safeNextAction || "Fix cost or abuse blockers before trusting this path.";
+  } else if (warns > 0) {
+    report.status = "warn";
+    const firstWarn = findings.find((f) => f.severity === "warn");
+    report.summary.text = `${surfacesDetected.length} surface(s) detected. ${warns} warning(s) need review.`;
+    report.summary.safeNextAction = firstWarn?.safeNextAction || "Add or verify bounds before trusting this path.";
+  } else {
+    report.status = "pass";
+    report.summary.text = `${surfacesDetected.length} surface(s) detected. Cost and abuse bounds appear adequate.`;
+    report.summary.safeNextAction = "Keep cost and abuse bounds current as the codebase changes.";
+  }
+
+  // Product home card
+  report.productHome.status = report.status;
+  report.productHome.found = surfacesDetected;
+  report.productHome.forReview = findings.filter((f) => f.severity === "warn" || f.severity === "block").map((f) => f.title).slice(0, 6);
+  report.productHome.savedOrProved = findings.filter((f) => f.severity === "info").map((f) => f.title).slice(0, 6);
+  report.productHome.safeNextAction = report.summary.safeNextAction;
+
+  // Overhead
+  const durationMs = Date.now() - startTime;
+  report.overhead.durationMs = durationMs;
+  report.overhead.filesInspected = report.surfaceEvidence.filesInspected;
+  report.overhead.artifactsInspected = report.surfaceEvidence.artifactsInspected;
+
+  return report;
+}
+
+// ---------------------------------------------------------------------------
+// Build
+// ---------------------------------------------------------------------------
+
+function buildCostAbuseGuard(cwd = process.cwd(), options = {}) {
+  const startTime = Date.now();
+  const files = walkWorkspace(cwd);
+  const report = buildEmptyReport(startTime);
+  const state = createState();
+
+  report.surfaceEvidence.filesInspected = files.length;
+  report.surfaceEvidence.artifactsInspected = files.length;
+
+  // Run all detectors
+  detectRetryLoops(report, state, files);
+  detectPollingLoops(report, state, files);
+  detectScheduledJobs(report, state, files);
+  detectQueueWorkers(report, state, files);
+  detectBatchJobs(report, state, files);
+  const hasRateLimitLib = detectRateLimiting(report, state, files);
+  detectTimeouts(report, state, files);
+  detectConcurrency(report, state, files);
+  detectPublicEndpoints(report, state, files, hasRateLimitLib);
+  detectAiToolLoops(report, state, files);
+  detectExpensiveScripts(report, state, files);
+  detectAbuseSurfaces(report, state, files);
+  detectPaymentSurfaces(report, state, files);
+  detectFreeTrialSurfaces(report, state, files);
+  detectCacheSurfaces(report, state, files);
+
+  finalizeReport(report, state, startTime);
+
+  if (options.write !== false) {
+    safeWriteJson(cwd, REPORT_JSON_REL, report);
+  }
+  return report;
+}
+
+function generateCostAbuseGuard(cwd = process.cwd(), options = {}) {
+  const report = buildCostAbuseGuard(cwd, options);
+  return {
+    report,
+    reportPath: path.join(cwd, REPORT_JSON_REL),
+  };
+}
+
+function loadCostAbuseGuard(cwd = process.cwd()) {
+  return safeReadJson(cwd, REPORT_JSON_REL, null);
+}
+
+// ---------------------------------------------------------------------------
+// Text formatting
+// ---------------------------------------------------------------------------
+
+function formatCostAbuseGuardText(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return [
+      "Avorelo Cost & Abuse Guard",
+      "Status: NO DATA",
+      "No cost or abuse surface was detected yet.",
+      "Safe next action: Re-run after adding runtime, API, or scheduling code.",
+    ].join("\n");
+  }
+
+  const counts = report.summary?.findingCounts || { info: 0, warn: 0, block: 0 };
+  const surfaceCount = report.surfaceEvidence?.surfacesDetected?.length || 0;
+
+  const lines = [
+    "Avorelo Cost & Abuse Guard",
+    `Status: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()} · redacted=yes`,
+    `Surfaces: ${surfaceCount} · info=${counts.info} · warn=${counts.warn} · block=${counts.block}`,
+    "Notes: local static scan only · no billing or provider calls",
+  ];
+
+  const findings = Array.isArray(report.findings) ? report.findings.slice(0, 8) : [];
+  if (findings.length > 0) {
+    lines.push("");
+    lines.push("Findings:");
+    for (const finding of findings) {
+      const ref = finding.evidenceRefs?.[0]?.path || "";
+      lines.push(`- [${finding.severity}] ${finding.title}${ref ? ` · ${ref}` : ""}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(`Safe next action: ${report.summary?.safeNextAction || "Add or verify bounds before trusting this path."}`);
+  return lines.join("\n");
+}
+
+function formatCostAbuseGuardStatusLineFromReport(report) {
+  if (!report || report.schemaVersion !== CONTRACT) {
+    return "Cost-abuse guard: NOT RUN · run `avorelo cost-abuse-guard --text`";
+  }
+  const counts = report.summary?.findingCounts || { info: 0, warn: 0, block: 0 };
+  return `Cost-abuse guard: ${String(report.status || "no_data").replace(/_/g, " ").toUpperCase()}`
+    + ` · block=${counts.block}`
+    + ` · warn=${counts.warn}`
+    + ` · next: ${sanitizeText(report.summary?.safeNextAction, 140) || "Review cost and abuse surfaces."}`;
+}
+
+// ---------------------------------------------------------------------------
+// Surface builder (for dashboard / status integration)
+// ---------------------------------------------------------------------------
+
+function buildCostAbuseGuardSurface(cwd = process.cwd(), options = {}) {
+  const report = loadCostAbuseGuard(cwd) || (options.buildIfMissing ? buildCostAbuseGuard(cwd, { write: false }) : null);
+  if (!report) {
+    return {
+      status: "not_run",
+      blockerCount: 0,
+      needsReviewCount: 0,
+      surfacesInspected: 0,
+      nextBestAction: "Run `avorelo cost-abuse-guard --text` before treating cost or abuse surfaces as safe.",
+      statusLine: "Cost-abuse guard: NOT RUN · run `avorelo cost-abuse-guard --text`",
+      showInStatus: true,
+      showInDashboard: true,
+      evidenceRef: null,
+      limitations: [
+        "Local static scan only. No billing or provider API calls.",
+      ],
+    };
+  }
+
+  const counts = report.summary?.findingCounts || { info: 0, warn: 0, block: 0 };
+  return {
+    status: report.status,
+    blockerCount: counts.block,
+    needsReviewCount: counts.warn,
+    surfacesInspected: report.surfaceEvidence?.surfacesDetected?.length || 0,
+    nextBestAction: report.summary?.safeNextAction,
+    statusLine: formatCostAbuseGuardStatusLineFromReport(report),
+    showInStatus: true,
+    showInDashboard: true,
+    evidenceRef: REPORT_JSON_REL,
+    limitations: [
+      "Local static scan only. No billing or provider API calls.",
+      "No model, network, or provider calls happen in this guard.",
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  CONTRACT,
+  REPORT_JSON_REL,
+  buildCostAbuseGuard,
+  generateCostAbuseGuard,
+  loadCostAbuseGuard,
+  formatCostAbuseGuardText,
+  formatCostAbuseGuardStatusLineFromReport,
+  buildCostAbuseGuardSurface,
+};