@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/lib/citations.mjs

@@ -0,0 +1,147 @@
+// Curated doc library — the allow-list for recommender citations.
+
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const LIBRARY_PATH = join(HERE, "..", "references", "docs-library.json");
+
+let cached;
+
+export async function loadLibrary() {
+  if (cached) return cached;
+  const raw = await readFile(LIBRARY_PATH, "utf-8");
+  cached = JSON.parse(raw);
+  return cached;
+}
+
+export async function isKnownUrl(url) {
+  const lib = await loadLibrary();
+  return lib.urls.some((e) => e.url === url);
+}
+
+export async function lookupUrl(url) {
+  const lib = await loadLibrary();
+  return lib.urls.find((e) => e.url === url);
+}
+
+export async function lookupSkillRule(ref) {
+  const lib = await loadLibrary();
+  const m = ref.match(/^([\w-]+):([\w-]+)$/);
+  if (!m) return undefined;
+  return lib.ruleSkillRefs.find((r) => r.skill === m[1] && r.rule === m[2]);
+}
+
+// Narrow semver subset: "*", "fw@*", "fw@14", "fw@>=15.0.0", "fw@<X", "fw@X.Y", "fw@X.Y.Z", "a || b".
+export function matchesFrameworkVersion(pattern, framework, version) {
+  if (pattern === "*") return true;
+
+  if (pattern.includes("||")) {
+    return pattern
+      .split("||")
+      .map((p) => p.trim())
+      .some((p) => matchesFrameworkVersion(p, framework, version));
+  }
+
+  const m = pattern.match(/^([\w-]+)@(.+)$/);
+  if (!m) return false;
+  const [, fw, range] = m;
+
+  if (fw !== framework) return false;
+  if (range === "*") return true;
+
+  const verParts = parseVersion(version);
+  if (!verParts) return false;
+
+  let m2 = range.match(/^>=\s*(.+)$/);
+  if (m2) {
+    const min = parseVersion(m2[1]);
+    return min ? compareVersion(verParts, min) >= 0 : false;
+  }
+
+  m2 = range.match(/^<\s*(.+)$/);
+  if (m2) {
+    const max = parseVersion(m2[1]);
+    return max ? compareVersion(verParts, max) < 0 : false;
+  }
+
+  if (/^\d+$/.test(range)) {
+    return verParts[0] === Number(range);
+  }
+
+  m2 = range.match(/^(\d+)\.(\d+)$/);
+  if (m2) {
+    return verParts[0] === Number(m2[1]) && verParts[1] === Number(m2[2]);
+  }
+
+  const exact = parseVersion(range);
+  if (exact) return compareVersion(verParts, exact) === 0;
+
+  return false;
+}
+
+function parseVersion(v) {
+  const m = String(v)
+    .replace(/^[v^~]+/, "")
+    .match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return null;
+  return [Number(m[1]) || 0, Number(m[2]) || 0, Number(m[3]) || 0];
+}
+
+function compareVersion(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+// Filtered subset embedded in recommender prompt — LLM never sees URLs for features not in user's stack.
+export async function libraryForStack(framework, version) {
+  const lib = await loadLibrary();
+  const matches = (frameworks) =>
+    frameworks.some((p) => matchesFrameworkVersion(p, framework, version) || p === "*");
+  return {
+    urls: lib.urls.filter((e) => matches(e.applicableFrameworks)),
+    ruleSkillRefs: lib.ruleSkillRefs.filter((r) => matches(r.applicableFrameworks)),
+  };
+}
+
+export async function sanitizeCitations(rec, framework, version) {
+  const lib = await loadLibrary();
+  const strippedUnknown = [];
+  const strippedVersion = [];
+  const kept = [];
+
+  for (const cite of rec.citations ?? []) {
+    const ruleRef = await lookupSkillRule(cite);
+    if (ruleRef) {
+      if (
+        matchesFrameworkVersion(ruleRef.applicableFrameworks.join(" || "), framework, version) ||
+        ruleRef.applicableFrameworks.includes("*")
+      ) {
+        kept.push(cite);
+      } else {
+        strippedVersion.push(cite);
+      }
+      continue;
+    }
+
+    const entry = lib.urls.find((e) => e.url === cite);
+    if (!entry) {
+      strippedUnknown.push(cite);
+      continue;
+    }
+    if (
+      entry.applicableFrameworks.includes("*") ||
+      entry.applicableFrameworks.some((p) => matchesFrameworkVersion(p, framework, version))
+    ) {
+      kept.push(cite);
+    } else {
+      strippedVersion.push(cite);
+    }
+  }
+
+  rec.citations = kept;
+  return { rec, strippedUnknown, strippedVersion };
+}

package/skills/craft/vercel-optimize/lib/cost-coverage.mjs

@@ -0,0 +1,162 @@
+// 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, " ");
+}

package/skills/craft/vercel-optimize/lib/dedup-recs.mjs

@@ -0,0 +1,340 @@
+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;
+}