adevkit 0.1.0__py3-none-any.whl

devkit/skills/embedded/vercel-optimize/lib/sanitizers/rate-limit.mjs

@@ -0,0 +1,67 @@
+// Prepend a caveat (don't drop — customer may be on a higher tier) when a
+// rec prescribes concurrency above a known provider rate limit.
+
+const PROVIDER_LIMITS = {
+  notion: { rps: 3, label: 'Notion', doc: 'https://developers.notion.com/reference/request-limits' },
+  openai: { rps: 30, label: 'OpenAI', doc: 'https://platform.openai.com/docs/guides/rate-limits' },
+  stripe: { rps: 100, label: 'Stripe', doc: 'https://docs.stripe.com/rate-limits' },
+  anthropic: { rps: 10, label: 'Anthropic', doc: 'https://docs.anthropic.com/en/api/rate-limits' },
+};
+
+export const metadata = {
+  id: 'rate-limit',
+  description: 'Prepend caveat when a rec prescribes concurrency above a known provider rate limit.',
+};
+
+const PROVIDER_RE = new RegExp(`\\b(${Object.keys(PROVIDER_LIMITS).join('|')})\\b`, 'gi');
+const CONCURRENCY_RE = /\b(?:concurrency|parallel|in\s+parallel|simultaneous|simultaneously|fan[- ]?out|Promise\.all)\b[^\d]{0,40}(\d{1,4})\b/gi;
+const CONCURRENCY_RE_REVERSE = /\b(\d{1,4})\s*(?:concurrent|parallel|simultaneous|in flight)\b/gi;
+
+export function apply(rec, _ctx = {}) {
+  const text = collectText(rec);
+  const providers = matchProviders(text);
+  if (providers.length === 0) return {};
+  const concurrency = matchConcurrency(text);
+  if (concurrency === null) return {};
+
+  const tags = [];
+  let prepend = '';
+  for (const key of providers) {
+    const limit = PROVIDER_LIMITS[key];
+    if (!limit) continue;
+    if (concurrency > limit.rps) {
+      const tag = `rate-limit:${limit.label}:${concurrency}/${limit.rps}`;
+      tags.push(tag);
+      prepend += `⚠ ${limit.label} rate-limits to ~${limit.rps} requests/second on first-tier plans; the prescribed concurrency of ${concurrency} may saturate the limit. Verify your tier before applying.\n\n`;
+    }
+  }
+  if (tags.length === 0) return {};
+  if (typeof rec.fix === 'string') rec.fix = prepend + rec.fix;
+  else rec.fix = prepend.trim();
+  return { tags, needsReview: true };
+}
+
+function collectText(rec) {
+  return [rec.what, rec.why, rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+}
+
+function matchProviders(text) {
+  const out = new Set();
+  for (const m of text.matchAll(PROVIDER_RE)) out.add(m[1].toLowerCase());
+  return [...out];
+}
+
+function matchConcurrency(text) {
+  let max = null;
+  for (const m of text.matchAll(CONCURRENCY_RE)) {
+    const n = Number(m[1]);
+    if (Number.isFinite(n) && (max === null || n > max)) max = n;
+  }
+  for (const m of text.matchAll(CONCURRENCY_RE_REVERSE)) {
+    const n = Number(m[1]);
+    if (Number.isFinite(n) && (max === null || n > max)) max = n;
+  }
+  return max;
+}

devkit/skills/embedded/vercel-optimize/lib/sanitizers/rendering-mode-mislabel.mjs

@@ -0,0 +1,38 @@
+// Warn when a rec's claimed rendering mode (static/ISR/SSR) contradicts
+// the scanner-tagged mode for that route. No-op when the scanner didn't
+// tag a renderingMode — full AST inference isn't implemented yet.
+
+import { extractRoute } from '../util.mjs';
+
+const MODE_PATTERNS = {
+  static: /\bstatic(?:ally rendered)?\b|prerender(?:ed)?\b/i,
+  isr: /\bISR\b|incremental[- ]?static|revalidate\s*:\s*\d/i,
+  ssr: /\bSSR\b|server[- ]?side rendered|dynamic\s*=\s*['"]force-dynamic['"]/i,
+};
+
+export const metadata = {
+  id: 'rendering-mode-mislabel',
+  description: 'Catch recs that blame the wrong rendering mode (e.g. "convert from ISR" on a static page).',
+};
+
+export function apply(rec, ctx = {}) {
+  const route = extractRoute(rec);
+  if (!route) return {};
+  const routes = ctx?.signals?.codebase?.routes ?? [];
+  const match = routes.find((r) => r.routePath === route);
+  const actualMode = match?.renderingMode;
+  if (!actualMode) return {};
+
+  const text = [rec.what, rec.why, rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+  const claimedModes = Object.entries(MODE_PATTERNS)
+    .filter(([, re]) => re.test(text))
+    .map(([m]) => m);
+
+  if (claimedModes.length === 0 || claimedModes.includes(actualMode)) return {};
+
+  const warning = `\n\n_⚠ Rendering-mode mismatch: this rec describes the route as \`${claimedModes.join(', ')}\` but the scanner classified it as \`${actualMode}\`. Verify the rendering mode before applying._`;
+  if (typeof rec.fix === 'string') rec.fix += warning;
+  return { tag: `rendering-mode-mislabel:${claimedModes.join(',')}!=${actualMode}`, needsReview: true };
+}

devkit/skills/embedded/vercel-optimize/lib/sanitizers/undeclared-dep.mjs

@@ -0,0 +1,78 @@
+// Prepend `npm i <pkg>` when the fix imports a package missing from
+// package.json — otherwise pasted code hits a runtime error.
+
+const IMPORT_RE = /\bimport\s+(?:[\w*{}\s,]+\s+from\s+)?["']([^"']+)["']/g;
+const REQUIRE_RE = /\brequire\s*\(\s*["']([^"']+)["']\s*\)/g;
+// Captures package root from `pkg/sub` and `@scope/pkg/sub`.
+const PKG_ROOT_RE = /^(@[^/]+\/[^/]+|[^/]+)/;
+const NODE_BUILTINS = new Set([
+  'fs', 'fs/promises', 'path', 'os', 'crypto', 'http', 'https', 'http2', 'net',
+  'dns', 'tls', 'util', 'url', 'stream', 'buffer', 'events', 'process', 'child_process',
+  'cluster', 'worker_threads', 'inspector', 'perf_hooks', 'assert', 'console',
+  'querystring', 'string_decoder', 'tty', 'vm', 'zlib', 'readline', 'punycode',
+  'module', 'timers', 'async_hooks', 'v8', 'test', 'diagnostics_channel',
+]);
+
+export const metadata = {
+  id: 'undeclared-dep',
+  description: 'Prepend `npm i <pkg>` when fix imports a package not in package.json.',
+};
+
+export function apply(rec, ctx = {}) {
+  const pkg = ctx?.package ?? ctx?.signals?.package ?? null;
+  if (!pkg) return {};
+
+  const known = new Set([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+    ...Object.keys(pkg.peerDependencies ?? {}),
+    ...Object.keys(pkg.optionalDependencies ?? {}),
+  ]);
+
+  const text = [rec.fix, rec.currentBehavior, rec.desiredBehavior]
+    .filter((s) => typeof s === 'string')
+    .join('\n');
+  const codeBlocks = extractCodeBlocks(text);
+  const importedRoots = new Set();
+  for (const block of codeBlocks) {
+    for (const m of block.matchAll(IMPORT_RE)) {
+      const root = pkgRoot(m[1]);
+      if (root) importedRoots.add(root);
+    }
+    for (const m of block.matchAll(REQUIRE_RE)) {
+      const root = pkgRoot(m[1]);
+      if (root) importedRoots.add(root);
+    }
+  }
+
+  const undeclared = [...importedRoots]
+    .filter((r) => !r.startsWith('.'))
+    .filter((r) => !NODE_BUILTINS.has(r))
+    .filter((r) => !r.startsWith('node:'))
+    .filter((r) => !known.has(r));
+
+  if (undeclared.length === 0) return {};
+
+  const installLines = undeclared.map((p) => `\`npm i ${p}\``).join(', ');
+  const prepend = `**Add dependency first**: ${installLines}\n\n`;
+  if (typeof rec.fix === 'string') rec.fix = prepend + rec.fix;
+  else rec.fix = prepend.trim();
+  return { tags: undeclared.map((p) => `undeclared-dep:${p}`), needsReview: true };
+}
+
+function pkgRoot(specifier) {
+  if (!specifier) return null;
+  if (specifier.startsWith('.')) return specifier;
+  const m = specifier.match(PKG_ROOT_RE);
+  return m ? m[1] : null;
+}
+
+function extractCodeBlocks(text) {
+  const out = [];
+  const re = /```[\w-]*\n?([\s\S]*?)```/g;
+  let m;
+  while ((m = re.exec(text)) !== null) out.push(m[1]);
+  // Also scan raw text for rare inline imports outside code blocks.
+  out.push(text);
+  return out;
+}

devkit/skills/embedded/vercel-optimize/lib/sanitizers/vercel-directive-strip.mjs

@@ -0,0 +1,37 @@
+// Strip Cache-Control directives Vercel's CDN silently ignores
+// (stale-if-error, proxy-revalidate, must-revalidate). s-maxage/max-age/
+// stale-while-revalidate/no-store/private/public are honored — leave them.
+
+import { escapeRegex } from '../util.mjs';
+
+const STRIP_DIRECTIVES = ['stale-if-error', 'proxy-revalidate', 'must-revalidate'];
+
+export const metadata = {
+  id: 'vercel-directive-strip',
+  description: 'Strip cache-control directives Vercel\'s CDN does not honor.',
+};
+
+export function apply(rec, _ctx = {}) {
+  const fields = ['fix', 'currentBehavior', 'desiredBehavior'];
+  const strippedSet = new Set();
+  for (const f of fields) {
+    if (typeof rec[f] !== 'string') continue;
+    for (const directive of STRIP_DIRECTIVES) {
+      const re = new RegExp(`(?:,\\s*)?\\b${escapeRegex(directive)}\\b(?:\\s*,)?`, 'g');
+      if (re.test(rec[f])) {
+        rec[f] = rec[f]
+          .replace(new RegExp(`\\b${escapeRegex(directive)}\\b`, 'g'), '')
+          .replace(/,\s*,/g, ',')
+          .replace(/(['"])\s*,\s*/g, '$1, ')
+          .replace(/,\s*(['"])/g, ', $1')
+          .replace(/(['"])\s*,\s*(['"])/g, '$1, $2')
+          .replace(/\b(Cache-Control|cache-control)\b:\s*,\s*/g, '$1: ')
+          .replace(/(['"])\s*,\s*\1/g, '$1');
+        strippedSet.add(directive);
+      }
+    }
+  }
+  const stripped = [...strippedSet];
+  if (stripped.length === 0) return {};
+  return { tags: stripped.map((d) => `vercel-directive-strip:${d}`) };
+}

devkit/skills/embedded/vercel-optimize/lib/sanitizers/window-units.mjs

@@ -0,0 +1,32 @@
+// The metrics window is fixed by collect-signals (currently 14d). Do not let
+// agent prose turn observed counts into monthly counts.
+
+import { normalizeObservedWindowUnits } from '../display-labels.mjs';
+
+export const metadata = {
+  id: 'window-units',
+  description: 'Rewrite observed /mo or monthly count units to /window so reports do not imply extrapolated monthly data.',
+};
+
+const STRING_FIELDS = [
+  'what',
+  'why',
+  'fix',
+  'currentBehavior',
+  'desiredBehavior',
+  'verify',
+];
+
+export function apply(rec) {
+  const tags = [];
+  for (const field of STRING_FIELDS) {
+    if (typeof rec?.[field] !== 'string') continue;
+    const before = rec[field];
+    const after = normalizeObservedWindowUnits(before);
+    if (after !== before) {
+      rec[field] = after;
+      tags.push(`window-units:${field}`);
+    }
+  }
+  return tags.length > 0 ? { tags } : {};
+}

devkit/skills/embedded/vercel-optimize/lib/scanners/cache-components-suspense-dedupe.mjs

@@ -0,0 +1,109 @@
+// Detects the Cache Components anti-pattern where `'use cache'` doesn't dedupe across
+// separate `<Suspense>` boundaries — each boundary triggers a separate evaluation of the
+// "shared" cached function, multiplying invocations and ISR write pressure.
+//
+// Simplified single-file heuristic (cross-file segment analysis is out of scope):
+//   File contains `'use cache'` directive (or `use cache` keyword)
+//   AND file has 2+ `<Suspense ...>` boundaries
+//   AND a repeated fetch URL or function call appears in the body.
+//
+// False positives are tolerable: the support-topic body recommends a known-good remediation
+// (hoist promise to page, or move to `'use cache: remote'`) whether or not the specific call
+// site is the exact one paying the cost. The verifier abstains when the file structure
+// doesn't match the pitfall.
+
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'cache-components-suspense-dedupe',
+  title: "'use cache' with multiple Suspense boundaries on the same data",
+  severity: 'medium',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    "Default `'use cache'` does not dedupe identical calls across separate `<Suspense>` boundaries on the same render. Each boundary re-invokes the cached function, multiplying function-duration cost and inflating ISR write churn when the output is large.",
+  fix:
+    "Hoist the promise to the page level (`const dataPromise = fetchData()` at the top, passed down to each Suspense child) OR move the shared fetch into a `'use cache: remote'` data-access layer so cross-request and cross-boundary dedupe applies.",
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/directives/use-cache',
+    'https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents',
+    'https://nextjs.org/docs/app/guides/migrating-to-cache-components',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '**/*.test.*', '**/*.spec.*'],
+  includeGlobs: [
+    '**/page.{ts,tsx,js,jsx}',
+    '**/layout.{ts,tsx,js,jsx}',
+    '**/components/**/*.{tsx,jsx}',
+  ],
+};
+
+const USE_CACHE_RE = /^[\t ]*['"]use cache['"]/m;
+const SUSPENSE_TAG_RE = /<Suspense\b/g;
+const FETCH_LITERAL_RE = /fetch\s*\(\s*(['"`])([^'"`]{6,200})\1/g;
+// Helper function calls that look like data-fetchers (lowercase camel, no JSX/HTML noise).
+const HELPER_CALL_RE = /\b(get|fetch|load|find|query|read)[A-Z][A-Za-z0-9_]+\s*\(/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!USE_CACHE_RE.test(content)) continue;
+
+    const suspenseCount = countMatches(content, SUSPENSE_TAG_RE);
+    if (suspenseCount < 2) continue;
+
+    const repeated = findRepeated(content);
+    if (repeated.length === 0) continue;
+
+    // Anchor the finding to the first repeated call site so the customer
+    // can locate the duplicate quickly.
+    const first = repeated[0];
+    out.push({
+      pattern: metadata.id,
+      file: path,
+      line: lineOf(content, first.firstIdx),
+      evidence: first.kind === 'fetch'
+        ? `fetch("${truncate(first.token, 60)}") called ${first.count}× across Suspense boundaries`
+        : `${first.token}() called ${first.count}× across Suspense boundaries`,
+      trafficIndependent: metadata.trafficIndependent,
+      subtype: first.kind === 'fetch' ? 'fetch-literal' : 'helper-call',
+    });
+  }
+  return out;
+}
+
+function countMatches(content, re) {
+  re.lastIndex = 0;
+  let n = 0;
+  while (re.exec(content) !== null) n++;
+  return n;
+}
+
+function findRepeated(content) {
+  const tokens = new Map(); // token -> { kind, count, firstIdx }
+  let m;
+  FETCH_LITERAL_RE.lastIndex = 0;
+  while ((m = FETCH_LITERAL_RE.exec(content)) !== null) {
+    record(tokens, m[2], 'fetch', m.index);
+  }
+  HELPER_CALL_RE.lastIndex = 0;
+  while ((m = HELPER_CALL_RE.exec(content)) !== null) {
+    const name = m[0].replace(/\s*\($/, '').trim();
+    record(tokens, name, 'helper', m.index);
+  }
+  return [...tokens.values()]
+    .filter((t) => t.count >= 2)
+    .sort((a, b) => b.count - a.count);
+}
+
+function record(map, token, kind, idx) {
+  if (!token) return;
+  if (!map.has(token)) {
+    map.set(token, { token, kind, count: 0, firstIdx: idx });
+  }
+  map.get(token).count++;
+}
+
+function truncate(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + '…';
+}

devkit/skills/embedded/vercel-optimize/lib/scanners/edge-heavy-import.mjs

@@ -0,0 +1,94 @@
+// Flag node-only / heavy imports in edge-runtime files (either a
+// middleware basename or an `export const runtime = 'edge'`). These
+// either fail at deploy (node: builtins, native bindings) or inflate
+// cold-start latency. Line-anchored matches + type-only-import skip
+// keep FP low.
+
+const EDGE_RUNTIME_RE = /export\s+const\s+runtime\s*=\s*['"]edge['"]/;
+const IMPORT_RE = /^\s*import\s+(?:type\s+)?(?:[^'"]*\s+from\s+)?['"]([^'"]+)['"]/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+const REQUIRE_RE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+const TYPE_IMPORT_RE = /^\s*import\s+type\s+/;
+
+const HEAVY_PATTERNS = [
+  /^node:/,
+  /^sharp$/,
+  /^@aws-sdk\//,
+  /^@prisma\/client$/,
+  /^prisma$/,
+  /^pg$/,
+  /^mysql2(?:\/|$)/,
+  /^puppeteer(?:-core)?(?:\/|$)/,
+  /^playwright(?:-core)?(?:\/|$)/,
+  /^bcrypt$/,
+  /^jsonwebtoken$/,
+  /^canvas$/,
+  /^@google-cloud\//,
+];
+
+export const metadata = {
+  id: 'edge-heavy-import',
+  title: 'Heavy / node-only import inside edge-runtime file',
+  severity: 'high',
+  billingDimension: 'function-duration',
+  trafficIndependent: true,
+  description:
+    'Edge runtime is a constrained sandbox with no node: builtins and a much smaller cold-start budget than Node functions. Heavy SDKs (sharp, @aws-sdk/*, @prisma/client, pg, puppeteer) either fail at deploy or inflate cold-start latency. Move the import to a Node runtime function, or replace with an edge-compatible alternative (e.g., neon-driver instead of pg).',
+  fix:
+    'Either (a) drop the `export const runtime = \'edge\'` so the route runs on Node (default in 2026), or (b) replace the heavy import with an edge-compatible alternative. For DB: use @neondatabase/serverless or @planetscale/database instead of pg/mysql2. For image: do the work in a Node route handler. For auth signing: use jose (Web Crypto) instead of jsonwebtoken.',
+  citations: [
+    'https://vercel.com/docs/functions/runtimes/edge-runtime',
+    'https://vercel.com/docs/fluid-compute',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**', '**/*.test.*', '**/*.spec.*'],
+  includeGlobs: ['**/*.{ts,tsx,js,mjs}'],
+};
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isEdgeRuntimeFile(path, content)) continue;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Type-only imports are erased at compile, never reach runtime.
+      if (TYPE_IMPORT_RE.test(line)) continue;
+      const specifiers = extractSpecifiers(line);
+      for (const spec of specifiers) {
+        const match = HEAVY_PATTERNS.find((re) => re.test(spec));
+        if (!match) continue;
+        out.push({
+          pattern: metadata.id,
+          file: path,
+          line: i + 1,
+          evidence: `import "${spec}" in edge-runtime file`,
+          edgeReason: isMiddleware(path) ? 'middleware (always edge)' : 'export const runtime = "edge"',
+          importedModule: spec,
+          trafficIndependent: metadata.trafficIndependent,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function isEdgeRuntimeFile(path, content) {
+  return isMiddleware(path) || EDGE_RUNTIME_RE.test(content);
+}
+
+function isMiddleware(path) {
+  return /(?:^|\/)middleware\.(ts|tsx|js|mjs)$/.test(path);
+}
+
+function extractSpecifiers(line) {
+  const out = new Set();
+  // IMPORT_RE has `gm` flag — reset lastIndex per call.
+  IMPORT_RE.lastIndex = 0;
+  let m;
+  while ((m = IMPORT_RE.exec(line)) !== null) out.add(m[1]);
+  DYNAMIC_IMPORT_RE.lastIndex = 0;
+  while ((m = DYNAMIC_IMPORT_RE.exec(line)) !== null) out.add(m[1]);
+  REQUIRE_RE.lastIndex = 0;
+  while ((m = REQUIRE_RE.exec(line)) !== null) out.add(m[1]);
+  return [...out];
+}

devkit/skills/embedded/vercel-optimize/lib/scanners/force-dynamic.mjs

@@ -0,0 +1,42 @@
+export const metadata = {
+  id: 'force-dynamic',
+  title: "export const dynamic = 'force-dynamic'",
+  severity: 'medium',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    "force-dynamic disables static + ISR rendering. The route runs the function on every request. Sometimes necessary (cookies, headers, real-time data), often a habit that costs function-duration and edge-requests at scale.",
+  fix:
+    "Audit the route. If dynamic behavior comes from cookies()/headers()/searchParams, force-dynamic may be redundant — Next infers dynamic automatically. Consider revalidate / 'use cache' / generateStaticParams if any portion can be pre-rendered.",
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**'],
+  includeGlobs: ['**/route.{ts,tsx,js,jsx}', '**/page.{ts,tsx,js,jsx}'],
+};
+
+const RE = /export\s+const\s+dynamic\s*=\s*["']force-dynamic["']/;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(path)) continue;
+    const m = RE.exec(content);
+    if (m) {
+      out.push({
+        pattern: metadata.id,
+        file: path,
+        line: lineOf(content, m.index),
+        evidence: 'export const dynamic = "force-dynamic"',
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+import { lineOf } from '../util.mjs';
+
+function isApplicable(path) {
+  return /(\/route|\/page)\.(tsx?|jsx?)$/.test(path);
+}

devkit/skills/embedded/vercel-optimize/lib/scanners/headers-in-page.mjs

@@ -0,0 +1,44 @@
+import { lineOf } from '../util.mjs';
+
+export const metadata = {
+  id: 'headers-in-page',
+  title: 'Dynamic API call forcing dynamic rendering',
+  severity: 'medium',
+  billingDimension: 'function-duration',
+  trafficIndependent: false,
+  description:
+    'headers(), cookies(), and draftMode() are dynamic APIs. Reading them in a page/layout makes the entire segment dynamic — no ISR, no static generation, and a function invocation on every request.',
+  fix:
+    'Move the dynamic API call into a child Server Component that lives inside a Suspense boundary. The parent can stay static; only the leaf re-renders dynamically.',
+  citations: [
+    'https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config',
+    'https://nextjs.org/docs/app/building-your-application/caching',
+  ],
+  excludeGlobs: ['node_modules/**', '.next/**', 'dist/**', '__tests__/**'],
+  includeGlobs: ['**/{page,layout,template}.{tsx,jsx}'],
+};
+
+const RE = /\b(cookies|headers|draftMode)\s*\(\s*\)/g;
+
+export function scan({ files }) {
+  const out = [];
+  for (const { path, content } of files) {
+    if (!isApplicable(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: `${m[1]}()`,
+        trafficIndependent: metadata.trafficIndependent,
+      });
+    }
+  }
+  return out;
+}
+
+function isApplicable(path) {
+  return /\/(page|layout|template)\.(tsx|jsx)$/.test(path);
+}

devkit/skills/embedded/vercel-optimize/lib/scanners/index.mjs

@@ -0,0 +1,35 @@
+import * as unoptimizedImage from './unoptimized-image.mjs';
+import * as forceDynamic from './force-dynamic.mjs';
+import * as middlewareBroad from './middleware-broad-matcher.mjs';
+import * as missingCacheHeaders from './missing-cache-headers.mjs';
+import * as maxAgeNoSMaxage from './max-age-without-s-maxage.mjs';
+import * as headersInPage from './headers-in-page.mjs';
+import * as sourceMapsProd from './source-maps-production.mjs';
+import * as prismaIncludeTree from './prisma-include-tree.mjs';
+import * as sveltekitPrerenderMissing from './sveltekit-prerender-missing.mjs';
+import * as largeStaticAsset from './large-static-asset.mjs';
+import * as edgeHeavyImport from './edge-heavy-import.mjs';
+import * as useCacheDateStamp from './use-cache-date-stamp.mjs';
+import * as cacheComponentsSuspenseDedupe from './cache-components-suspense-dedupe.mjs';
+import * as turboForceBypass from './turbo-force-bypass.mjs';
+import * as regionPinInConfig from './region-pin-in-config.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,
+];

devkit/skills/embedded/vercel-optimize/lib/scanners/large-static-asset.mjs

@@ -0,0 +1,92 @@
+// 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';
+}