@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/lib/scanners/index.mjs

@@ -0,0 +1,35 @@
+import * as cacheComponentsSuspenseDedupe from "./cache-components-suspense-dedupe.mjs";
+import * as edgeHeavyImport from "./edge-heavy-import.mjs";
+import * as forceDynamic from "./force-dynamic.mjs";
+import * as headersInPage from "./headers-in-page.mjs";
+import * as largeStaticAsset from "./large-static-asset.mjs";
+import * as maxAgeNoSMaxage from "./max-age-without-s-maxage.mjs";
+import * as middlewareBroad from "./middleware-broad-matcher.mjs";
+import * as missingCacheHeaders from "./missing-cache-headers.mjs";
+import * as prismaIncludeTree from "./prisma-include-tree.mjs";
+import * as regionPinInConfig from "./region-pin-in-config.mjs";
+import * as sourceMapsProd from "./source-maps-production.mjs";
+import * as sveltekitPrerenderMissing from "./sveltekit-prerender-missing.mjs";
+import * as turboForceBypass from "./turbo-force-bypass.mjs";
+import * as unoptimizedImage from "./unoptimized-image.mjs";
+import * as useCacheDateStamp from "./use-cache-date-stamp.mjs";
+
+// `use-client-cascade` is intentionally NOT registered: 0.3% conversion
+// rate, and client-bundle size isn't billed on Vercel.
+export const scanners = [
+  unoptimizedImage,
+  forceDynamic,
+  middlewareBroad,
+  missingCacheHeaders,
+  maxAgeNoSMaxage,
+  headersInPage,
+  sourceMapsProd,
+  prismaIncludeTree,
+  sveltekitPrerenderMissing,
+  largeStaticAsset,
+  edgeHeavyImport,
+  useCacheDateStamp,
+  cacheComponentsSuspenseDedupe,
+  turboForceBypass,
+  regionPinInConfig,
+];

package/skills/craft/vercel-optimize/lib/scanners/large-static-asset.mjs

@@ -0,0 +1,93 @@
+// Flag oversized assets under public/. Pure fs.stat — no parsing, no LLM.
+// 500 KB threshold is where bandwidth/first-paint start to bite (Vercel
+// Doctor's 4 KB triggers on favicons).
+
+import { readdir, stat } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+
+const THRESHOLD_BYTES = 500_000;
+const TOP_N = 20;
+
+const SKIP_EXTENSIONS = new Set([".html", ".txt", ".xml", ".json", ".webmanifest", ".ico"]);
+const SKIP_PATH_PREFIXES = [".well-known/"];
+
+export const metadata = {
+  id: "large-static-asset",
+  title: "Large file in public/",
+  severity: "medium",
+  billingDimension: "bandwidth",
+  trafficIndependent: true,
+  description:
+    "Static assets in `public/` over 500 KB ship as-is from the CDN. Whether the cost is meaningful depends on traffic, but the candidate is binary — the file is either needed at that size or it can be optimized (compressed image, video transcode, or moved off the critical path).",
+  fix: "Verify the asset is reachable on the customer-facing hot path. Then choose: (a) compress (convert PNG → AVIF/WebP; transcode MP4 to lower bitrate); (b) host externally (Vercel Blob, S3, or a media CDN with per-asset signed URLs); (c) lazy-load (defer to client-side fetch instead of bundling into initial HTML).",
+  citations: [
+    "https://vercel.com/docs/manage-cdn-usage",
+    "https://vercel.com/docs/image-optimization",
+  ],
+  excludeGlobs: ["node_modules/**", ".next/**", "dist/**", "__tests__/**"],
+  includeGlobs: ["public/**/*"],
+};
+
+// Walks public/ directly because collectFiles only emits text-readable
+// extensions — binary assets never reach the shared `files` array.
+export async function scan({ rootDir }) {
+  if (!rootDir) return [];
+  const root = join(rootDir, "public");
+  const out = [];
+  try {
+    for await (const entry of walk(root)) {
+      if (shouldSkip(entry.relPath)) continue;
+      if (entry.size < THRESHOLD_BYTES) continue;
+      out.push({
+        pattern: metadata.id,
+        file: join("public", entry.relPath),
+        line: 1,
+        evidence: `${formatBytes(entry.size)} (${extname(entry.relPath) || "no-ext"})`,
+        trafficIndependent: metadata.trafficIndependent,
+        sizeBytes: entry.size,
+      });
+    }
+  } catch {
+    return [];
+  }
+  out.sort((a, b) => b.sizeBytes - a.sizeBytes);
+  return out.slice(0, TOP_N);
+}
+
+async function* walk(dir, base = "") {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    const rel = base ? `${base}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      yield* walk(full, rel);
+      continue;
+    }
+    if (!e.isFile()) continue;
+    try {
+      const s = await stat(full);
+      yield { relPath: rel, size: s.size };
+    } catch {
+      /* skip unreadable */
+    }
+  }
+}
+
+function shouldSkip(relPath) {
+  if (SKIP_PATH_PREFIXES.some((p) => relPath.startsWith(p))) return true;
+  const ext = extname(relPath).toLowerCase();
+  if (SKIP_EXTENSIONS.has(ext)) return true;
+  return false;
+}
+
+function formatBytes(b) {
+  if (b >= 1e9) return (b / 1e9).toFixed(2) + " GB";
+  if (b >= 1e6) return (b / 1e6).toFixed(2) + " MB";
+  if (b >= 1e3) return (b / 1e3).toFixed(1) + " KB";
+  return b + " B";
+}

package/skills/craft/vercel-optimize/lib/scanners/max-age-without-s-maxage.mjs

@@ -0,0 +1,47 @@
+import { lineOf } from "../util.mjs";
+
+export const metadata = {
+  id: "max-age-without-s-maxage",
+  title: "Cache-Control: max-age without s-maxage",
+  severity: "medium",
+  billingDimension: "edge-requests",
+  trafficIndependent: false,
+  description:
+    "max-age caches in the browser; s-maxage caches at the CDN. Without s-maxage, every uncached visitor request invokes the function. Adding s-maxage often cuts function invocations by 80%+ on read-heavy routes.",
+  fix: "Add s-maxage to the Cache-Control header. Example: Cache-Control: public, max-age=60, s-maxage=600, stale-while-revalidate=86400. Pair with explicit cache-bust strategy if content can change.",
+  citations: [
+    "https://vercel.com/docs/caching/cdn-cache",
+    "https://vercel.com/docs/caching/cache-control-headers",
+  ],
+  excludeGlobs: ["node_modules/**", ".next/**", "dist/**", "__tests__/**", "*.config.*"],
+  includeGlobs: ["**/*.{ts,tsx,js,jsx,mjs}"],
+};
+
+const RE = /Cache-Control[^"'`]*?max-age\s*=\s*\d+/gi;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (/\.test\.|\.spec\./.test(path)) continue;
+    let m;
+    RE.lastIndex = 0;
+    while ((m = RE.exec(content)) !== null) {
+      const hit = m[0];
+      if (
+        /s-maxage/i.test(hit) ||
+        /CDN-Cache-Control/i.test(
+          content.slice(Math.max(0, m.index - 100), m.index + hit.length + 100),
+        )
+      )
+        continue;
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: hit.slice(0, 160),
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}

package/skills/craft/vercel-optimize/lib/scanners/middleware-broad-matcher.mjs

@@ -0,0 +1,53 @@
+export const metadata = {
+  id: "middleware-broad-matcher",
+  title: "Middleware matcher missing or too broad",
+  severity: "high",
+  billingDimension: "edge-requests",
+  trafficIndependent: true,
+  description:
+    'middleware.ts without a config.matcher (or matcher: ["/(.*)"]) runs on every request including _next/static, _next/image, favicon.ico, and image asset fetches. Edge-request cost scales accordingly.',
+  fix: 'Scope the matcher to actual application paths. Example: matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"]',
+  citations: ["https://nextjs.org/docs/app/building-your-application/routing/middleware"],
+  excludeGlobs: ["node_modules/**", ".next/**", "dist/**", "__tests__/**"],
+  includeGlobs: ["middleware.{ts,js,mjs}", "src/middleware.{ts,js,mjs}"],
+};
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(path)) continue;
+
+    const exportsMiddleware =
+      /export\s+(default\s+)?(async\s+)?function\s+middleware/.test(content) ||
+      /export\s+const\s+middleware\s*=/.test(content);
+    if (!exportsMiddleware) continue;
+
+    const configBlock = content.match(/export\s+const\s+config\s*=\s*\{([\s\S]*?)\}/);
+    const matcherStr = configBlock && configBlock[1].match(/matcher\s*:\s*([^,}]+)/);
+
+    let problem = null;
+    if (!configBlock || !matcherStr) {
+      problem = "no config.matcher (runs on every request)";
+    } else {
+      const m = matcherStr[1];
+      if (/['"`]\s*\/\s*['"`]/.test(m) || /['"`]\/\(\.\*\)['"`]/.test(m)) {
+        problem = 'matcher = "/" or "/(.*)" (still covers everything)';
+      }
+    }
+
+    if (problem) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: 1,
+        evidence: problem,
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+function isApplicable(path) {
+  return /(^|\/)middleware\.(ts|js|mjs)$/.test(path);
+}

package/skills/craft/vercel-optimize/lib/scanners/missing-cache-headers.mjs

@@ -0,0 +1,97 @@
+// Two checks emitted as `missing-cache-headers`:
+//   A. GET handler with no Cache-Control AND no auth signal.
+//   B. fetch() with `cache:'no-store'` / `next:{revalidate:0}` outside an
+//      auth window (~10 lines above, 5 below).
+
+export const metadata = {
+  id: "missing-cache-headers",
+  title: "Cacheable route or fetch with no caching (Cache-Control absent or no-store)",
+  severity: "medium",
+  billingDimension: "edge-requests",
+  trafficIndependent: false,
+  description:
+    'Two antipatterns: (a) GET handlers without explicit Cache-Control headers serve uncached; (b) fetch() calls with cache:"no-store" or next:{revalidate:0} opt out of caching even on cacheable upstream data. For non-auth routes / fetches, both are leaving cache hits on the floor.',
+  fix: 'For GET handlers: return a Response with Cache-Control: public, s-maxage=<seconds>, stale-while-revalidate=<window>. For fetch(): drop cache:"no-store" (use { next: { revalidate: <seconds> } } in Next.js) so the response is cached by the framework + CDN.',
+  citations: [
+    "https://vercel.com/docs/caching/cdn-cache",
+    "https://vercel.com/docs/caching/cache-control-headers",
+    "https://nextjs.org/docs/app/building-your-application/caching",
+  ],
+  excludeGlobs: [
+    "node_modules/**",
+    ".next/**",
+    "dist/**",
+    "__tests__/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+  ],
+  // page/layout included: no-store fetches commonly hide in Server Components.
+  includeGlobs: [
+    "**/route.{ts,tsx,js,jsx}",
+    "**/api/**/*.{ts,tsx,js,jsx}",
+    "**/page.{ts,tsx,js,jsx}",
+    "**/layout.{ts,tsx,js,jsx}",
+  ],
+};
+
+// Covers NextAuth, Clerk, JWT, Bearer, plus Next dynamic-render APIs.
+// FP on cacheable routes that read a session is acceptable — verifier decides.
+const AUTH_RE =
+  /\b(cookies\(\)|headers\(\)|getSession\(|getServerSession\(|currentUser\(|clerkClient|auth\(\)|verifyJWT|verifyToken|jwt\.verify|decode\(|Bearer\s|Authorization|supabase\.auth\.)/i;
+
+const NO_STORE_RE = /cache\s*:\s*['"]no-store['"]/;
+const REVALIDATE_ZERO_RE = /next\s*:\s*\{[^}]*revalidate\s*:\s*0\b/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(path)) continue;
+
+    const hasGetHandler =
+      /export\s+(async\s+)?function\s+GET/.test(content) ||
+      /export\s+const\s+GET\s*=/.test(content);
+    if (hasGetHandler) {
+      const hasCacheControl =
+        /Cache-Control/i.test(content) ||
+        /CDN-Cache-Control/i.test(content) ||
+        /export\s+const\s+revalidate\s*=/.test(content);
+      if (!hasCacheControl && !AUTH_RE.test(content)) {
+        out.push({
+          pattern: metadata.id,
+          subtype: "get-handler-no-cache-control",
+          file: path,
+          line: 1,
+          evidence: "GET handler with no Cache-Control / revalidate / auth signal",
+          trafficIndependent: metadata.trafficIndependent,
+        });
+      }
+    }
+
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const noStoreHit = NO_STORE_RE.test(line);
+      const revalidateZeroHit = REVALIDATE_ZERO_RE.test(line);
+      if (!noStoreHit && !revalidateZeroHit) continue;
+      const start = Math.max(0, i - 10);
+      const end = Math.min(lines.length, i + 5);
+      const window = lines.slice(start, end).join("\n");
+      if (AUTH_RE.test(window)) continue;
+      // Mutation verbs legitimately don't cache.
+      if (/method\s*:\s*['"](?:POST|PUT|PATCH|DELETE)['"]/i.test(window)) continue;
+      out.push({
+        pattern: metadata.id,
+        subtype: noStoreHit ? "fetch-no-store" : "fetch-revalidate-zero",
+        file: path,
+        line: i + 1,
+        evidence: line.trim().slice(0, 200),
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+function isApplicable(path) {
+  return /\/(route|index|page|layout)\.(ts|tsx|js|jsx)$/.test(path) || /\/api\//.test(path);
+}

package/skills/craft/vercel-optimize/lib/scanners/prisma-include-tree.mjs

@@ -0,0 +1,39 @@
+import { lineOf } from "../util.mjs";
+
+export const metadata = {
+  id: "prisma-include-tree-bloat",
+  title: "Deep Prisma include tree (3+ levels)",
+  severity: "high",
+  billingDimension: "function-duration",
+  trafficIndependent: false,
+  description:
+    "Nested .include({ x: { include: { y: { include: { z: ... } } } } }) makes Prisma issue a single huge join that scales O(N*M*K). Function duration explodes, memory spikes, often causes timeouts.",
+  fix: "Replace with explicit .findMany() calls or scoped .include() of only what the consumer reads. Consider Prisma.select() to project specific fields. For lists, batch with DataLoader patterns.",
+  citations: ["vercel-react-best-practices:server-parallel-fetching"],
+  excludeGlobs: ["node_modules/**", ".next/**", "dist/**", "__tests__/**"],
+  includeGlobs: ["**/*.{ts,tsx,js,jsx}"],
+};
+
+// Catches 3+ nesting levels of `include:` within a single object literal.
+const RE = /include\s*:\s*\{[\s\S]*?include\s*:\s*\{[\s\S]*?include\s*:/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (/\.test\.|\.spec\./.test(path)) continue;
+    let m;
+    RE.lastIndex = 0;
+    while ((m = RE.exec(content)) !== null) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: "3+ levels of nested Prisma .include()",
+        trafficIndependent: metadata.trafficIndependent,
+      });
+      // One finding per file is enough — agent investigates holistically.
+      break;
+    }
+  }
+  return out;
+}

package/skills/craft/vercel-optimize/lib/scanners/region-pin-in-config.mjs

@@ -0,0 +1,89 @@
+// Detects pinned function regions in vercel.json or per-route segment config.
+// Provides the "configured region" signal for the region-misconfig gate when a TTFB
+// breakdown by function_region isn't available (current state — see Phase 0 preflight
+// in plans/wild-splashing-flamingo.md).
+//
+// Subtypes:
+//   vercel-json-single   — vercel.json `regions: ["iad1"]` (single region, no failover)
+//   vercel-json-list     — vercel.json `regions: [...]` (multi-region; informational)
+//   segment-preferred    — `export const preferredRegion = 'iad1'` (or array)
+
+import { lineOf } from "../util.mjs";
+
+export const metadata = {
+  id: "region-pin-in-config",
+  title: "Function region pinned in config",
+  severity: "low",
+  billingDimension: "function-duration",
+  trafficIndependent: true,
+  description:
+    "vercel.json `regions` or per-route `preferredRegion` is set. If the pinned region is far from the dominant user geo (or far from a data source) p95 TTFB suffers. This scanner provides the configured-region signal so the region-misconfig gate can recommend an audit.",
+  fix: "Audit the pinned region against traffic geography (Speed Insights or Web Analytics by country) and data-source location. Consider multi-region if data lives in a fixed location and users are global; consider relocating if users are concentrated in one geography.",
+  citations: [
+    "https://vercel.com/docs/functions/configuring-functions/region",
+    "https://vercel.com/docs/functions/configuring-functions/region",
+  ],
+  excludeGlobs: ["node_modules/**", ".next/**", "dist/**"],
+  includeGlobs: [
+    "vercel.json",
+    "**/vercel.json",
+    "**/page.{ts,tsx,js,jsx}",
+    "**/route.{ts,tsx,js,jsx}",
+    "**/layout.{ts,tsx,js,jsx}",
+  ],
+};
+
+// Matches `regions: ["iad1"]`, `regions: ['iad1', 'sfo1']`, or `"regions": ["iad1"]`
+const VERCEL_JSON_REGIONS_RE = /['"]?regions['"]?\s*:\s*\[([^\]]+)\]/;
+// `export const preferredRegion = 'iad1'` OR `= ['iad1', 'sfo1']`
+const PREFERRED_REGION_RE = /export\s+const\s+preferredRegion\s*=\s*(['"][^'"]+['"]|\[[^\]]+\])/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    const name = path.split("/").pop();
+
+    if (name === "vercel.json") {
+      const m = VERCEL_JSON_REGIONS_RE.exec(content);
+      if (m) {
+        const regions = parseRegionList(m[1]);
+        out.push({
+          pattern: metadata.id,
+          file: path,
+          line: lineOf(content, m.index),
+          evidence: `vercel.json regions: [${regions.join(", ")}]`,
+          trafficIndependent: metadata.trafficIndependent,
+          subtype: regions.length === 1 ? "vercel-json-single" : "vercel-json-list",
+          regions,
+        });
+      }
+      continue;
+    }
+
+    // Segment config files (page.tsx, route.ts, layout.tsx).
+    const m = PREFERRED_REGION_RE.exec(content);
+    if (m) {
+      const raw = m[1];
+      const regions = raw.startsWith("[")
+        ? parseRegionList(raw.slice(1, -1))
+        : [raw.replace(/['"]/g, "")];
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: `preferredRegion = ${raw}`,
+        trafficIndependent: metadata.trafficIndependent,
+        subtype: "segment-preferred",
+        regions,
+      });
+    }
+  }
+  return out;
+}
+
+function parseRegionList(inner) {
+  return inner
+    .split(",")
+    .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+    .filter(Boolean);
+}

package/skills/craft/vercel-optimize/lib/scanners/source-maps-production.mjs

@@ -0,0 +1,33 @@
+import { lineOf } from "../util.mjs";
+
+export const metadata = {
+  id: "source-maps-production",
+  title: "Source maps enabled in production",
+  severity: "low",
+  billingDimension: "edge-requests",
+  trafficIndependent: true,
+  description:
+    "productionBrowserSourceMaps: true ships .map files in the production bundle, increasing transfer size 30-100% per visitor. Useful for error reporting via Sentry; not useful for users.",
+  fix: "Keep source maps generation but exclude them from the public bundle. Upload to your error tracker via build-time CI step; do not serve them with the deployment.",
+  citations: ["https://nextjs.org/docs/messages/improper-devtool"],
+  excludeGlobs: [],
+  includeGlobs: ["next.config.{js,mjs,ts}", "svelte.config.{js,mjs,ts}"],
+};
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!/^next\.config\.(js|mjs|ts)$/.test(path.split("/").pop() ?? "")) continue;
+    const m = /productionBrowserSourceMaps\s*:\s*true/.exec(content);
+    if (m) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: "productionBrowserSourceMaps: true",
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}

package/skills/craft/vercel-optimize/lib/scanners/sveltekit-prerender-missing.mjs

@@ -0,0 +1,47 @@
+// Flag SvelteKit pages that haven't declared prerender/ssr/config — they
+// default to per-request function execution. Pages that have already opted
+// in or out are skipped; the investigator agent decides actual staticness.
+
+export const metadata = {
+  id: "sveltekit-prerender-missing",
+  title: "SvelteKit page without explicit prerender / ISR config",
+  severity: "low",
+  billingDimension: "function-duration",
+  trafficIndependent: false,
+  description:
+    "SvelteKit page or +page.server.ts is missing an explicit `prerender`, `ssr`, or adapter `config.isr` declaration. Default is per-request function execution — investigate whether the route could be prerendered or ISR-cached.",
+  fix: "If the page is static (no per-user / per-request data), add `export const prerender = true` in +page.ts or +page.server.ts. If the data refreshes on a schedule, prefer adapter-vercel's ISR option via `export const config = { isr: { expiration: 60 } }`.",
+  citations: [
+    "https://kit.svelte.dev/docs/page-options",
+    "https://kit.svelte.dev/docs/adapter-vercel",
+    "https://vercel.com/docs/incremental-static-regeneration",
+  ],
+  excludeGlobs: ["node_modules/**", ".svelte-kit/**", "build/**", "__tests__/**"],
+  includeGlobs: [
+    "src/routes/**/+page.svelte",
+    "src/routes/**/+page.server.{ts,js}",
+    "src/routes/+page.svelte",
+    "src/routes/+page.server.{ts,js}",
+  ],
+};
+
+const PRERENDER_RE = /export\s+const\s+prerender\b/;
+const SSR_RE = /export\s+const\s+ssr\b/;
+const CONFIG_RE = /export\s+const\s+config\s*=\s*\{[^}]*\b(isr|prerender|runtime|split|regions)\b/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!path.includes("/routes/")) continue;
+    if (PRERENDER_RE.test(content) || SSR_RE.test(content) || CONFIG_RE.test(content)) continue;
+    out.push({
+      pattern: metadata.id,
+      file: path,
+      // Absence-finding — no specific line, placeholder 1.
+      line: 1,
+      evidence: "No `prerender`, `ssr`, or `config = { isr | runtime | ... }` export found",
+      trafficIndependent: metadata.trafficIndependent,
+    });
+  }
+  return out;
+}

package/skills/craft/vercel-optimize/lib/scanners/turbo-force-bypass.mjs

@@ -0,0 +1,136 @@
+// Detects Turborepo cache bypass patterns that cause every commit to rebuild every project,
+// driving Build Minutes to dominate the bill on monorepos.
+//
+// Three signal subtypes:
+//   force-flag      — `TURBO_FORCE=true` env var or `turbo run ... --force` in build script
+//   cache-disabled  — `turbo.json` declares `"cache": false` for the build pipeline
+//   no-ignore-step  — repo has turbo.json and no repo-declared ignoreCommand;
+//                     verify Vercel's skip-unaffected project setting before recommending one
+//
+// This pattern has caused full-monorepo rebuilds on every commit. Build-skip
+// settings and right-sized build machines can reduce Build Minutes when the
+// project is rebuilding unchanged work.
+
+export const metadata = {
+  id: "turbo-force-bypass",
+  title: "Turborepo cache bypass on a monorepo",
+  severity: "high",
+  billingDimension: "build",
+  trafficIndependent: true, // build-time, fires regardless of route traffic
+  description:
+    "Turborepo's per-task cache can be bypassed by an explicit force flag, a `cache: false` config, or missing build-skip configuration. Every commit can rebuild unchanged work; Build Minutes climb with project count.",
+  fix: "Remove `TURBO_FORCE=true` from build env/scripts unless intentional. Set `tasks.build.cache: true` in `turbo.json` (or remove the override), and include generated outputs in Turbo's cache contract. Prefer Vercel's skip-unaffected monorepo behavior when available; use `ignoreCommand` only when that setting cannot cover the project.",
+  citations: [
+    "https://vercel.com/docs/monorepos",
+    "https://vercel.com/docs/builds",
+    "https://turborepo.dev/docs/crafting-your-repository/caching",
+  ],
+  excludeGlobs: ["node_modules/**", ".next/**", "dist/**"],
+  includeGlobs: [
+    "turbo.json",
+    "**/turbo.json",
+    "package.json",
+    "**/package.json",
+    "vercel.json",
+    "**/vercel.json",
+  ],
+};
+
+const FORCE_ENV_RE = /TURBO_FORCE\s*=\s*(?:true|1)\b/;
+const FORCE_FLAG_RE = /\bturbo\s+(?:run\s+)?[a-z:_-]+[^\n&|;]*\s--force\b/;
+
+export function scan({ files }) {
+  const out = [];
+  let hasTurboJson = false;
+  let vercelJsonFile = null;
+  let vercelJsonContent = null;
+
+  for (const { path, content } of files) {
+    const name = path.split("/").pop();
+
+    if (name === "turbo.json") {
+      hasTurboJson = true;
+      const buildCacheDisabled = detectBuildCacheDisabled(content);
+      if (buildCacheDisabled) {
+        out.push({
+          pattern: metadata.id,
+          file: path,
+          line: buildCacheDisabled.line,
+          evidence: "turbo.json: tasks.build.cache = false",
+          trafficIndependent: metadata.trafficIndependent,
+          subtype: "cache-disabled",
+        });
+      }
+      continue;
+    }
+
+    if (name === "package.json") {
+      const scripts = safeScripts(content);
+      for (const [scriptName, body] of Object.entries(scripts)) {
+        if (FORCE_ENV_RE.test(body) || FORCE_FLAG_RE.test(body)) {
+          const line = lineOfMatch(content, body) ?? 1;
+          out.push({
+            pattern: metadata.id,
+            file: path,
+            line,
+            evidence: `package.json scripts.${scriptName}: ${truncate(body, 80)}`,
+            trafficIndependent: metadata.trafficIndependent,
+            subtype: "force-flag",
+          });
+        }
+      }
+      continue;
+    }
+
+    if (name === "vercel.json") {
+      vercelJsonFile = path;
+      vercelJsonContent = content;
+    }
+  }
+
+  // No-ignore-step: repo has turbo.json AND vercel.json lacks an ignoreCommand.
+  // This is an investigation prompt, not proof that the dashboard skip setting is off.
+  if (hasTurboJson && vercelJsonFile && !/"ignoreCommand"\s*:/.test(vercelJsonContent ?? "")) {
+    out.push({
+      pattern: metadata.id,
+      file: vercelJsonFile,
+      line: 1,
+      evidence:
+        "turbo repo without ignoreCommand in vercel.json; verify Vercel skip-unaffected setting",
+      trafficIndependent: metadata.trafficIndependent,
+      subtype: "no-ignore-step",
+    });
+  }
+
+  return out;
+}
+
+function detectBuildCacheDisabled(content) {
+  // Tolerate JSONC comments and trailing commas — light scan, not full parse.
+  // Match `"build": { ... "cache": false ... }` within reasonable lookahead.
+  const buildTask = /"build"\s*:\s*\{([\s\S]{0,400}?)\}/.exec(content);
+  if (!buildTask) return null;
+  if (!/"cache"\s*:\s*false/.test(buildTask[1])) return null;
+  const lineNum = content.slice(0, buildTask.index).split("\n").length;
+  return { line: lineNum };
+}
+
+function safeScripts(content) {
+  try {
+    const parsed = JSON.parse(content);
+    return parsed?.scripts && typeof parsed.scripts === "object" ? parsed.scripts : {};
+  } catch {
+    return {};
+  }
+}
+
+function lineOfMatch(haystack, needle) {
+  const idx = haystack.indexOf(needle);
+  if (idx < 0) return null;
+  return haystack.slice(0, idx).split("\n").length;
+}
+
+function truncate(s, n) {
+  if (typeof s !== "string") return "";
+  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+}