adevkit 0.1.0__py3-none-any.whl

devkit/skills/embedded/vercel-optimize/lib/cost-coverage.mjs

@@ -0,0 +1,143 @@
+// Maps billing line items to gate coverage so report surfaces uncovered dimensions (Sandbox, AI Gateway, Build, …) as blind spots.
+
+// Service → billing dimension. dim=null means uncovered. Substring match — Vercel billing names are stable but untyped.
+const SERVICE_DIMENSION = [
+  { match: /^Function Duration$/i,                       dim: 'function-duration' },
+  { match: /^Function Invocations$/i,                    dim: 'function-duration' },
+  { match: /^Fluid Active CPU$/i,                        dim: 'function-duration' },
+  { match: /^Fluid Provisioned Memory$/i,                dim: 'function-duration' },
+  { match: /^Edge Requests$/i,                           dim: 'edge-requests' },
+  { match: /^Edge Requests.*Additional CPU Duration/i,   dim: 'edge-requests' },
+  { match: /^Edge Function Execution Units$/i,           dim: 'edge-requests' },
+  { match: /^Edge Middleware Invocations$/i,             dim: 'edge-requests' },
+  { match: /^ISR (Reads|Writes)$/i,                      dim: 'isr' },
+  { match: /^Speed Insights( Data Points)?$/i,           dim: 'speed-insights' },
+  { match: /^Image Optimization/i,                       dim: 'image-optimization' },
+  // Indirect: bot-protection gate addresses bandwidth/edge spend.
+  { match: /^Fast Data Transfer$/i,                      dim: 'edge-requests' },
+  { match: /^Fast Origin Transfer$/i,                    dim: 'edge-requests' },
+
+  // Uncovered.
+  { match: /^Sandbox/i,                                  dim: null, family: 'sandbox' },
+  { match: /^AI Gateway$/i,                              dim: null, family: 'ai-gateway' },
+  { match: /^Build Minutes$/i,                           dim: 'build', family: 'build' },
+  { match: /^Build CPU Minutes$/i,                       dim: 'build', family: 'build' },
+  { match: /^Private Data Transfer$/i,                   dim: null, family: 'private-network' },
+  { match: /^Secure Compute Network$/i,                  dim: null, family: 'private-network' },
+  { match: /^Drains Volume$/i,                           dim: null, family: 'drains' },
+  { match: /^Observability Events$/i,                    dim: 'observability-events', family: 'observability-events' },
+  { match: /^Blob/i,                                     dim: null, family: 'blob' },
+  { match: /^Edge Config (Reads|Writes)$/i,              dim: null, family: 'edge-config' },
+  { match: /^Runtime Cache/i,                            dim: null, family: 'runtime-cache' },
+  { match: /^Microfrontends/i,                           dim: null, family: 'microfrontends' },
+  { match: /^Workflow/i,                                 dim: null, family: 'workflow' },
+  { match: /^Queue/i,                                    dim: null, family: 'queues' },
+  { match: /^Flag Requests$/i,                           dim: null, family: 'flags' },
+  { match: /^Flags Explorer/i,                           dim: null, family: 'flags' },
+  { match: /^BotID/i,                                    dim: null, family: 'botid' },
+  { match: /^Firewall/i,                                 dim: null, family: 'firewall' },
+  { match: /^Vercel Agent$/i,                            dim: null, family: 'vercel-agent' },
+
+  // Fixed costs (seats, contracts) — not actionable.
+  { match: /^v0 /i,                                      dim: null, family: 'fixed', actionable: false },
+  { match: /^Additional Team Seats$/i,                   dim: null, family: 'fixed', actionable: false },
+  { match: /^SAML$/i,                                    dim: null, family: 'fixed', actionable: false },
+  { match: /^HIPAA BAA$/i,                               dim: null, family: 'fixed', actionable: false },
+  { match: /^SIEM Integration$/i,                        dim: null, family: 'fixed', actionable: false },
+  { match: /^Web Analytics/i,                            dim: null, family: 'fixed', actionable: false },
+  { match: /^Static IPs$/i,                              dim: null, family: 'fixed', actionable: false },
+  { match: /^Bulk Redirects$/i,                          dim: null, family: 'fixed', actionable: false },
+  { match: /^Preview Deployment Suffix$/i,               dim: null, family: 'fixed', actionable: false },
+  { match: /^Rolling Releases$/i,                        dim: null, family: 'fixed', actionable: false },
+  { match: /^Observability Plus$/i,                      dim: null, family: 'fixed', actionable: false },
+  { match: /^Platform Customer Usage$/i,                 dim: null, family: 'fixed', actionable: false },
+  { match: /^Advanced Deployment Protection$/i,          dim: null, family: 'fixed', actionable: false },
+];
+
+export function classifyService(serviceName, activeDims) {
+  if (!serviceName) return { covered: false, family: 'unknown' };
+  for (const e of SERVICE_DIMENSION) {
+    if (e.match.test(serviceName)) {
+      if (e.dim && activeDims.has(e.dim)) return { covered: true, dim: e.dim };
+      return { covered: false, family: e.family ?? 'unknown', actionable: e.actionable ?? true };
+    }
+  }
+  return { covered: false, family: 'unknown', actionable: true };
+}
+
+export function computeCostCoverage(usage, gates) {
+  const services = Array.isArray(usage?.services) ? usage.services : [];
+  const activeDims = new Set(
+    (gates ?? [])
+      .map((g) => g?.metadata?.billingDimension)
+      .filter((d) => typeof d === 'string' && d !== 'mixed')
+  );
+  let total = 0;
+  let covered = 0;
+  let uncovered = 0;
+  const byFamily = new Map();
+
+  for (const s of services) {
+    const billed = Number(s.billedCost ?? 0);
+    if (!Number.isFinite(billed) || billed <= 0) continue;
+    total += billed;
+    const c = classifyService(s.name, activeDims);
+    if (c.covered) {
+      covered += billed;
+      continue;
+    }
+    uncovered += billed;
+    const key = c.family;
+    const prev = byFamily.get(key) ?? { family: key, billed: 0, services: [], actionable: c.actionable !== false };
+    prev.billed += billed;
+    prev.services.push({ name: s.name, billed });
+    prev.actionable = prev.actionable && (c.actionable !== false);
+    byFamily.set(key, prev);
+  }
+
+  const uncoveredByFamily = [...byFamily.values()]
+    .sort((a, b) => b.billed - a.billed)
+    .map((f) => ({ ...f, services: f.services.sort((a, b) => b.billed - a.billed) }));
+
+  // Pick top gaps globally so multiple families surface (Sandbox + AI Gateway + Build, not 5 Sandbox sub-services). Exclude fixed costs — seats aren't actionable workload.
+  const allActionableServices = [];
+  for (const family of uncoveredByFamily) {
+    if (!family.actionable) continue;
+    for (const s of family.services) {
+      allActionableServices.push({ name: s.name, billed: s.billed, family: family.family });
+    }
+  }
+  allActionableServices.sort((a, b) => b.billed - a.billed);
+  const topGaps = allActionableServices.slice(0, 5).map((s) => ({
+    ...s,
+    share: total > 0 ? s.billed / total : 0,
+  }));
+  return { totalBilled: total, coveredBilled: covered, uncoveredBilled: uncovered, uncoveredByFamily, topGaps };
+}
+
+export function renderCostCoverageMarkdown(coverage) {
+  if (!coverage || !Number.isFinite(coverage.totalBilled) || coverage.totalBilled <= 0) return [];
+  const { totalBilled, coveredBilled, uncoveredBilled, topGaps } = coverage;
+  const actionableGaps = topGaps.filter((g) => g.share >= 0.01); // 1%+ share
+  if (actionableGaps.length === 0) return [];
+  const lines = [];
+  lines.push('');
+  lines.push('### Coverage gaps');
+  lines.push('');
+  const coveredPct = totalBilled > 0 ? (coveredBilled / totalBilled) * 100 : 0;
+  const uncoveredPct = totalBilled > 0 ? (uncoveredBilled / totalBilled) * 100 : 0;
+  lines.push(`This audit has metric coverage for **$${coveredBilled.toFixed(0)} (${coveredPct.toFixed(0)}%)** of this bill via function-duration, edge-requests, ISR, middleware, and image-optimization dimensions. **$${uncoveredBilled.toFixed(0)} (${uncoveredPct.toFixed(0)}%)** sits in billed areas this run cannot analyze safely, including the top actionable items below:`);
+  lines.push('');
+  lines.push('| Service | Billed | Share | Family | Coverage |');
+  lines.push('|---|---|---|---|---|');
+  for (const g of actionableGaps) {
+    lines.push(`| ${escapeCell(g.name)} | $${g.billed.toFixed(2)} | ${(g.share * 100).toFixed(1)}% | ${g.family} | _not analyzed in this run_ |`);
+  }
+  lines.push('');
+  lines.push('_Recommendations in this report address the covered dimensions. The uncovered rows are not ignored; they need a separate investigation before we can make safe recommendations._');
+  return lines;
+}
+
+function escapeCell(s) {
+  return String(s ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}

devkit/skills/embedded/vercel-optimize/lib/dedup-recs.mjs

@@ -0,0 +1,325 @@
+const NO_VALUE = '<none>';
+
+export function dedupeRecommendations(recommendations = []) {
+  if (!Array.isArray(recommendations)) {
+    throw new TypeError('dedupeRecommendations recommendations must be an array');
+  }
+
+  const byKey = new Map();
+  const order = [];
+  for (const rec of recommendations) {
+    if (!rec || typeof rec !== 'object' || rec.abstain === true) {
+      order.push(rec);
+      continue;
+    }
+
+    const key = recommendationKey(rec);
+    if (!byKey.has(key)) {
+      const normalized = withDedupMetadata(rec);
+      byKey.set(key, normalized);
+      order.push({ __dedupKey: key });
+      continue;
+    }
+
+    const current = byKey.get(key);
+    const merged = mergeDuplicateRecs(current, rec);
+    byKey.set(key, merged);
+  }
+
+  return order.map((entry) => entry?.__dedupKey ? byKey.get(entry.__dedupKey) : entry);
+}
+
+export function recommendationKey(rec) {
+  const intent = dedupIntent(rec);
+  const bucket = intent === 'cache-control:s-maxage'
+    ? NO_VALUE
+    : String(rec?.bucket ?? NO_VALUE);
+  return JSON.stringify([
+    bucket,
+    dedupEditTarget(rec),
+    primarySkillRule(rec),
+    intent,
+  ]);
+}
+
+export function normalizePath(path) {
+  if (typeof path !== 'string' || path.trim() === '') return NO_VALUE;
+  return path
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+/g, '/')
+    .replace(/:(\d+)(?::\d+)?$/, '');
+}
+
+export function primarySkillRule(rec) {
+  const citations = Array.isArray(rec?.citations) ? rec.citations : [];
+  return citations.find((c) => typeof c === 'string' && /^[A-Za-z][\w-]*:[A-Za-z][\w-]*$/.test(c)) ?? NO_VALUE;
+}
+
+export function fixShape(rec) {
+  if (typeof rec?.fixShape === 'string' && rec.fixShape.trim()) {
+    return normalizeFixText(rec.fixShape);
+  }
+  const primaryText = [rec?.fix, rec?.desiredBehavior]
+    .filter((v) => typeof v === 'string' && v.trim())
+    .join('\n');
+  const text = primaryText || rec?.what;
+  return normalizeFixText(text);
+}
+
+export function dedupIntent(rec) {
+  if (isSMaxageCacheHeaderRec(rec)) return 'cache-control:s-maxage';
+  if (isCacheLifeRec(rec)) return cacheLifeIntent(rec);
+  const sharedFunction = sharedFunctionTarget(rec);
+  if (sharedFunction) return `parallel-shared-helper:${sharedFunction}`;
+  return fixShape(rec);
+}
+
+export function dedupEditTarget(rec) {
+  return sharedFunctionTarget(rec) ?? normalizePath(firstAffectedFile(rec));
+}
+
+function firstAffectedFile(rec) {
+  const direct = affectedFiles(rec);
+  const editTarget = referencedCodeFiles(rec, ['fix', 'desiredBehavior', 'currentBehavior'])[0];
+  if (editTarget) return editTarget;
+  const referenced = referencedCodeFiles(rec)
+    .find((file) => direct.includes(file));
+  if (referenced) return referenced;
+  return Array.isArray(rec?.affectedFiles) ? rec.affectedFiles[0] : null;
+}
+
+function affectedFiles(rec) {
+  return Array.isArray(rec?.affectedFiles)
+    ? rec.affectedFiles.map(normalizePath).filter((file) => file !== NO_VALUE)
+    : [];
+}
+
+function referencedCodeFiles(rec, fields = ['what', 'why', 'fix', 'currentBehavior', 'desiredBehavior', 'verify']) {
+  const text = fields
+    .map((field) => rec?.[field])
+    .filter((v) => typeof v === 'string' && v.trim())
+    .join('\n');
+  const matches = text.match(/(?:^|[\s`'"(])((?:\.{1,2}\/|[A-Za-z0-9_.@-]+\/)[A-Za-z0-9_./@[\]()-]+\.(?:mjs|cjs|js|jsx|ts|tsx))/g) ?? [];
+  return unique(matches.map((m) =>
+    normalizePath(m.replace(/^[\s`'"(]+/, ''))
+  ).filter((file) => file !== NO_VALUE));
+}
+
+function isSMaxageCacheHeaderRec(rec) {
+  const text = [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.desiredBehavior,
+    ...(Array.isArray(rec?.citations) ? rec.citations : []),
+  ].filter(Boolean).join('\n');
+  return /\bs-maxage\b/i.test(text) &&
+    /\b(?:Cache-Control|CDN cache|cdn-cache|caching\/cdn-cache)\b/i.test(text);
+}
+
+function isCacheLifeRec(rec) {
+  const text = [
+    rec?.candidateRef,
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.desiredBehavior,
+    ...(Array.isArray(rec?.citations) ? rec.citations : []),
+  ].filter(Boolean).join('\n');
+  return /^isr_overrevalidation:/.test(String(rec?.candidateRef ?? '')) &&
+    /\bcacheLife\s*\(|\bcacheLife\b/i.test(text);
+}
+
+function sharedFunctionTarget(rec) {
+  const rule = primarySkillRule(rec);
+  if (!/(?:^|:)async-parallel$|(?:^|:)server-parallel-fetching$|(?:^|:)async-suspense-boundaries$/.test(rule)) {
+    return null;
+  }
+  const text = [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.currentBehavior,
+    rec?.desiredBehavior,
+  ].filter((v) => typeof v === 'string' && v.trim()).join('\n');
+  const names = [
+    ...text.matchAll(/\b(?:get|fetch|load|read|render|create|generate|filter|resolve)[A-Z][A-Za-z0-9_]*\b/g),
+  ].map((m) => m[0]);
+  const stop = new Set([
+    'getPayload',
+    'draftMode',
+    'notFound',
+    'redirect',
+    'Promise',
+    'Response',
+    'NextResponse',
+  ]);
+  const candidates = names.filter((name) => !stop.has(name));
+  if (candidates.length === 0) return null;
+  const score = new Map();
+  for (const name of candidates) {
+    score.set(name, (score.get(name) ?? 0) + 1);
+  }
+  return [...score.entries()]
+    .sort((a, b) => b[1] - a[1] || text.indexOf(a[0]) - text.indexOf(b[0]))
+    .map(([name]) => `function:${name}`)[0] ?? null;
+}
+
+function cacheLifeIntent(rec) {
+  const text = [
+    rec?.what,
+    rec?.why,
+    rec?.fix,
+    rec?.desiredBehavior,
+    rec?.verify,
+  ].filter(Boolean).join('\n');
+  const profiles = unique(
+    [...text.matchAll(/\bcacheLife\s*\(\s*['"`]([^'"`]+)['"`]/g)]
+      .map((m) => m[1])
+  );
+  const tags = unique([
+    ...[...text.matchAll(/\bcacheTag\s*\(([^)]*)\)/gs)].flatMap((m) => {
+      const args = m[1] ?? '';
+      return [
+        ...[...args.matchAll(/['"]([^'"]+)['"]/g)].map((x) => x[1]),
+        ...[...args.matchAll(/`([^`]+)`/g)].map((x) => x[1].includes('${') ? `${x[1].split('${')[0]}*` : x[1]),
+      ];
+    }),
+  ]);
+  const invalidation = /\b(?:revalidateTag|updateTag)\s*\(/.test(text) ? 'with-invalidation-api' : 'no-invalidation-api';
+  return [
+    'next-cache:cache-life',
+    profiles.join('|') || NO_VALUE,
+    tags.join('|') || NO_VALUE,
+    invalidation,
+  ].join(':');
+}
+
+function unique(values) {
+  return Array.from(new Set(values.filter((v) => typeof v === 'string' && v.trim()).map((v) => v.trim()))).sort();
+}
+
+function normalizeFixText(text) {
+  if (typeof text !== 'string' || text.trim() === '') return NO_VALUE;
+  return text
+    .toLowerCase()
+    .replace(/```[\s\S]*?```/g, ' codeblock ')
+    .replace(/`[^`]*`/g, ' code ')
+    .replace(/\b\d+(?:\.\d+)?(?:ms|s|%|kb|mb|gb|k|m)?\b/g, '#')
+    .replace(/[^a-z0-9#]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .slice(0, 80)
+    .join(' ') || NO_VALUE;
+}
+
+function withDedupMetadata(rec) {
+  const existing = normalizedAppliesAlsoTo(rec.appliesAlsoTo);
+  const count = Math.max(
+    numericCount(rec.corroborationCount),
+    1 + existing.length,
+  );
+  return existing.length > 0 || count > 1
+    ? { ...rec, appliesAlsoTo: existing, corroborationCount: count }
+    : { ...rec };
+}
+
+function mergeDuplicateRecs(a, b) {
+  const aScore = recScore(a);
+  const bScore = recScore(b);
+  const winner = bScore > aScore ? b : a;
+  const loser = winner === a ? b : a;
+  const winnerExisting = normalizedAppliesAlsoTo(winner.appliesAlsoTo);
+  const loserExisting = normalizedAppliesAlsoTo(loser.appliesAlsoTo);
+  const appliesAlsoTo = uniqueAppliesAlsoTo([
+    ...winnerExisting,
+    appliesAlsoEntry(loser),
+    ...loserExisting,
+  ]);
+  const corroborationCount =
+    numericCount(winner.corroborationCount) + numericCount(loser.corroborationCount);
+  return {
+    ...winner,
+    appliesAlsoTo,
+    corroborationCount: Math.max(corroborationCount, 1 + appliesAlsoTo.length),
+  };
+}
+
+function recScore(rec) {
+  const priority = typeof rec?.priority === 'number' ? rec.priority : 0;
+  const quality = typeof rec?.quality?.overall === 'number' ? rec.quality.overall : 0;
+  return (priority * 1_000_000_000_000) + signalMagnitude(rec) + quality;
+}
+
+function signalMagnitude(rec) {
+  const text = [
+    rec?.o11ySignal,
+    rec?.why,
+    rec?.what,
+    rec?.impact,
+  ].filter((v) => typeof v === 'string' && v.trim()).join('\n');
+  const inv = parseNumber(text, /(?:inv|invocations?|function invocations?|requests?)[:=]\s*([\d,]+)/i);
+  const p95 = parseNumber(text, /(?:p95|95th percentile(?: duration)?)[:=]?\s*([\d,]+)\s*ms/i);
+  const errors = parseNumber(text, /(?:errs|errors?)[:=]\s*([\d,]+)/i);
+  const writes = parseNumber(text, /writes[:=]\s*([\d,]+)/i);
+  const reads = parseNumber(text, /reads[:=]\s*([\d,]+)/i);
+  if (inv != null && p95 != null) return inv * p95;
+  if (errors != null) return errors;
+  if (writes != null && reads != null) return writes + reads;
+  if (inv != null) return inv;
+  return 0;
+}
+
+function parseNumber(text, re) {
+  const match = re.exec(text);
+  if (!match) return null;
+  const value = Number(String(match[1]).replace(/,/g, ''));
+  return Number.isFinite(value) ? value : null;
+}
+
+function numericCount(value) {
+  return Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+function appliesAlsoEntry(rec) {
+  return {
+    candidateRef: rec?.candidateRef ?? null,
+    affectedFiles: Array.isArray(rec?.affectedFiles)
+      ? rec.affectedFiles.map(normalizePath).filter((p) => p !== NO_VALUE)
+      : [],
+    o11ySignal: rec?.o11ySignal ?? null,
+    what: rec?.what ?? null,
+  };
+}
+
+function normalizedAppliesAlsoTo(entries) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .filter((e) => e && typeof e === 'object')
+    .map((e) => ({
+      candidateRef: e.candidateRef ?? null,
+      affectedFiles: Array.isArray(e.affectedFiles)
+        ? e.affectedFiles.map(normalizePath).filter((p) => p !== NO_VALUE)
+        : [],
+      o11ySignal: e.o11ySignal ?? null,
+      what: e.what ?? null,
+    }));
+}
+
+function uniqueAppliesAlsoTo(entries) {
+  const seen = new Set();
+  const out = [];
+  for (const entry of entries) {
+    const key = JSON.stringify([
+      entry.candidateRef ?? NO_VALUE,
+      entry.affectedFiles?.join(',') ?? NO_VALUE,
+      entry.what ?? NO_VALUE,
+    ]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(entry);
+  }
+  return out;
+}