@oriro/orirocli 0.1.9 → 0.1.11

package/skills/craft/vercel-optimize/lib/framework-support.mjs

@@ -1,69 +1,69 @@
-export const CORE_SUPPORTED_FRAMEWORKS = ["next", "sveltekit", "nuxt"];
-export const LIMITED_FRAMEWORKS = ["astro"];
-
-const LABELS = {
-  next: "Next.js",
-  sveltekit: "SvelteKit",
-  nuxt: "Nuxt",
-  astro: "Astro",
-  hono: "Hono",
-  remix: "Remix",
-  unknown: "unknown framework",
-};
-
-export function frameworkLabel(framework) {
-  return LABELS[normalizeFramework(framework)] ?? String(framework ?? "unknown");
-}
-
-export function classifyFrameworkSupport(stack = {}) {
-  const framework = normalizeFramework(stack.framework);
-  const label = frameworkLabel(framework);
-  const supportedLabels = CORE_SUPPORTED_FRAMEWORKS.map(frameworkLabel);
-  const limitedLabels = LIMITED_FRAMEWORKS.map(frameworkLabel);
-
-  if (CORE_SUPPORTED_FRAMEWORKS.includes(framework)) {
-    return {
-      ok: true,
-      status: "supported",
-      blocker: null,
-      framework,
-      label,
-      supportedFrameworks: supportedLabels,
-      limitedFrameworks: limitedLabels,
-      detail: `${label} is supported for metric-backed route-to-file investigations.`,
-    };
-  }
-
-  if (LIMITED_FRAMEWORKS.includes(framework)) {
-    return {
-      ok: true,
-      status: "limited",
-      blocker: null,
-      framework,
-      label,
-      supportedFrameworks: supportedLabels,
-      limitedFrameworks: limitedLabels,
-      detail: `${label} support is limited. The skill can use Vercel metrics and generic platform checks, but framework-specific route-to-file recommendations may be sparse.`,
-    };
-  }
-
-  return {
-    ok: false,
-    status: "unsupported",
-    blocker: "unsupported_framework",
-    framework,
-    label,
-    supportedFrameworks: supportedLabels,
-    limitedFrameworks: limitedLabels,
-    detail: `${label} is not supported for metric-backed route-to-file investigations. Supported frameworks: ${supportedLabels.join(", ")}. Limited support: ${limitedLabels.join(", ")}.`,
-  };
-}
-
-function normalizeFramework(value) {
-  const raw = String(value ?? "unknown")
-    .trim()
-    .toLowerCase();
-  if (raw === "nextjs" || raw === "next.js") return "next";
-  if (raw === "svelte" || raw === "svelte-kit") return "sveltekit";
-  return raw || "unknown";
-}
+export const CORE_SUPPORTED_FRAMEWORKS = ["next", "sveltekit", "nuxt"];
+export const LIMITED_FRAMEWORKS = ["astro"];
+
+const LABELS = {
+  next: "Next.js",
+  sveltekit: "SvelteKit",
+  nuxt: "Nuxt",
+  astro: "Astro",
+  hono: "Hono",
+  remix: "Remix",
+  unknown: "unknown framework",
+};
+
+export function frameworkLabel(framework) {
+  return LABELS[normalizeFramework(framework)] ?? String(framework ?? "unknown");
+}
+
+export function classifyFrameworkSupport(stack = {}) {
+  const framework = normalizeFramework(stack.framework);
+  const label = frameworkLabel(framework);
+  const supportedLabels = CORE_SUPPORTED_FRAMEWORKS.map(frameworkLabel);
+  const limitedLabels = LIMITED_FRAMEWORKS.map(frameworkLabel);
+
+  if (CORE_SUPPORTED_FRAMEWORKS.includes(framework)) {
+    return {
+      ok: true,
+      status: "supported",
+      blocker: null,
+      framework,
+      label,
+      supportedFrameworks: supportedLabels,
+      limitedFrameworks: limitedLabels,
+      detail: `${label} is supported for metric-backed route-to-file investigations.`,
+    };
+  }
+
+  if (LIMITED_FRAMEWORKS.includes(framework)) {
+    return {
+      ok: true,
+      status: "limited",
+      blocker: null,
+      framework,
+      label,
+      supportedFrameworks: supportedLabels,
+      limitedFrameworks: limitedLabels,
+      detail: `${label} support is limited. The skill can use Vercel metrics and generic platform checks, but framework-specific route-to-file recommendations may be sparse.`,
+    };
+  }
+
+  return {
+    ok: false,
+    status: "unsupported",
+    blocker: "unsupported_framework",
+    framework,
+    label,
+    supportedFrameworks: supportedLabels,
+    limitedFrameworks: limitedLabels,
+    detail: `${label} is not supported for metric-backed route-to-file investigations. Supported frameworks: ${supportedLabels.join(", ")}. Limited support: ${limitedLabels.join(", ")}.`,
+  };
+}
+
+function normalizeFramework(value) {
+  const raw = String(value ?? "unknown")
+    .trim()
+    .toLowerCase();
+  if (raw === "nextjs" || raw === "next.js") return "next";
+  if (raw === "svelte" || raw === "svelte-kit") return "sveltekit";
+  return raw || "unknown";
+}

package/skills/craft/vercel-optimize/lib/gates/build-minutes-fanout.mjs

@@ -1,73 +1,73 @@
-// Build Minutes climb on monorepos when Turborepo cache is bypassed or every project rebuilds on every commit.
-// Threshold: Build Minutes line > 15% of total bill OR scanner emits any turbo-force-bypass finding (even at lower share).
-// Account-scoped because the lever is project-settings (Ignored Build Step, Elastic Build Machines), not code.
-export const metadata = {
-  id: "build_minutes_fanout",
-  threshold: "Build Minutes share > 0.15 OR turbo-force-bypass finding present",
-  billingDimension: "build",
-  scope: "account",
-  sourceCitation: "vercel-optimize gate threshold",
-  description:
-    "Build Minutes line dominates the bill or Turborepo cache is bypassed. On monorepos, unchanged work should be skipped through Vercel skip-unaffected behavior, a verified Ignored Build Step, and a complete Turbo cache contract.",
-};
-
-const BUILD_RE = /^Build (CPU )?Minutes$/i;
-const SCANNER_PATTERN = "turbo-force-bypass";
-const SHARE_FLOOR = 0.15;
-
-export function gate(signals) {
-  const services = signals?.usage?.services;
-  const total = Array.isArray(services)
-    ? services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
-    : 0;
-  const buildBilled = Array.isArray(services)
-    ? services
-        .filter((s) => BUILD_RE.test(String(s?.name ?? "")))
-        .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
-    : 0;
-
-  const buildShare = total > 0 ? buildBilled / total : 0;
-
-  const findings = (signals?.codebase?.findings ?? []).filter((f) => f.pattern === SCANNER_PATTERN);
-
-  if (buildShare <= SHARE_FLOOR && findings.length === 0) return [];
-
-  const subtypes = unique(findings.map((f) => f.subtype).filter(Boolean));
-  const sampleFiles = unique(findings.map((f) => f.file).filter(Boolean)).slice(0, 4);
-
-  const reason =
-    findings.length > 0
-      ? buildShare > SHARE_FLOOR
-        ? "Build Minutes share is high and Turborepo cache bypass detected in repo"
-        : "Turborepo cache bypass detected in repo"
-      : "Build Minutes line exceeds 15% of total billed cost";
-
-  return [
-    {
-      kind: metadata.id,
-      scope: "account",
-      files: sampleFiles,
-      priority: findings.length > 0 ? 65 : 50,
-      confidence: findings.length > 0 ? 0.86 : 0.74,
-      o11ySignal: `build_minutes_share=${(buildShare * 100).toFixed(0)}% scanner_findings=${findings.length}`,
-      reason,
-      question:
-        findings.length > 0
-          ? `Turborepo cache bypass detected (${subtypes.join(", ")}). Which build pipeline forces a rebuild on every commit, and can Ignored Build Step + cache re-enable cut the project fan-out?`
-          : "Build Minutes exceed 15% of the bill. Is Ignored Build Step configured? Is Turborepo cache active across builds? Would Elastic Build Machines reduce duration on hot builds?",
-      evidence: {
-        metric: "usage.services",
-        buildBilled,
-        totalBilled: total,
-        buildShare,
-        scannerFindings: findings.length,
-        scannerSubtypes: subtypes,
-        sampleFiles,
-      },
-    },
-  ];
-}
-
-function unique(values) {
-  return [...new Set(values)];
-}
+// Build Minutes climb on monorepos when Turborepo cache is bypassed or every project rebuilds on every commit.
+// Threshold: Build Minutes line > 15% of total bill OR scanner emits any turbo-force-bypass finding (even at lower share).
+// Account-scoped because the lever is project-settings (Ignored Build Step, Elastic Build Machines), not code.
+export const metadata = {
+  id: "build_minutes_fanout",
+  threshold: "Build Minutes share > 0.15 OR turbo-force-bypass finding present",
+  billingDimension: "build",
+  scope: "account",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Build Minutes line dominates the bill or Turborepo cache is bypassed. On monorepos, unchanged work should be skipped through Vercel skip-unaffected behavior, a verified Ignored Build Step, and a complete Turbo cache contract.",
+};
+
+const BUILD_RE = /^Build (CPU )?Minutes$/i;
+const SCANNER_PATTERN = "turbo-force-bypass";
+const SHARE_FLOOR = 0.15;
+
+export function gate(signals) {
+  const services = signals?.usage?.services;
+  const total = Array.isArray(services)
+    ? services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
+    : 0;
+  const buildBilled = Array.isArray(services)
+    ? services
+        .filter((s) => BUILD_RE.test(String(s?.name ?? "")))
+        .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0)
+    : 0;
+
+  const buildShare = total > 0 ? buildBilled / total : 0;
+
+  const findings = (signals?.codebase?.findings ?? []).filter((f) => f.pattern === SCANNER_PATTERN);
+
+  if (buildShare <= SHARE_FLOOR && findings.length === 0) return [];
+
+  const subtypes = unique(findings.map((f) => f.subtype).filter(Boolean));
+  const sampleFiles = unique(findings.map((f) => f.file).filter(Boolean)).slice(0, 4);
+
+  const reason =
+    findings.length > 0
+      ? buildShare > SHARE_FLOOR
+        ? "Build Minutes share is high and Turborepo cache bypass detected in repo"
+        : "Turborepo cache bypass detected in repo"
+      : "Build Minutes line exceeds 15% of total billed cost";
+
+  return [
+    {
+      kind: metadata.id,
+      scope: "account",
+      files: sampleFiles,
+      priority: findings.length > 0 ? 65 : 50,
+      confidence: findings.length > 0 ? 0.86 : 0.74,
+      o11ySignal: `build_minutes_share=${(buildShare * 100).toFixed(0)}% scanner_findings=${findings.length}`,
+      reason,
+      question:
+        findings.length > 0
+          ? `Turborepo cache bypass detected (${subtypes.join(", ")}). Which build pipeline forces a rebuild on every commit, and can Ignored Build Step + cache re-enable cut the project fan-out?`
+          : "Build Minutes exceed 15% of the bill. Is Ignored Build Step configured? Is Turborepo cache active across builds? Would Elastic Build Machines reduce duration on hot builds?",
+      evidence: {
+        metric: "usage.services",
+        buildBilled,
+        totalBilled: total,
+        buildShare,
+        scannerFindings: findings.length,
+        scannerSubtypes: subtypes,
+        sampleFiles,
+      },
+    },
+  ];
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}

package/skills/craft/vercel-optimize/lib/gates/cold-start.mjs

@@ -1,72 +1,72 @@
-// Signal: `function_start_type` dimension on `vercel.function_invocation.count` (cold|hot|prewarmed).
-// Threshold WHY: 40%+ cold is fixable via Fluid keep-warm; 30% is the noise floor for serverless without keep-warm.
-// total>=1000/14d (~3/hr) keeps Poisson CI on cold rate at ~±5% near the 40% threshold.
-export const metadata = {
-  id: "cold_start",
-  threshold: "coldPct > 0.4 AND total >= 1000",
-  billingDimension: "function-duration",
-  scope: "route",
-  sourceCitation: "vercel-optimize gate threshold",
-  description:
-    "Routes where > 40% of invocations are cold-start, at meaningful traffic (>=1,000 total invocations in window). Cold starts add 200-800ms per request and break the perceived latency budget on cache-miss paths. The 40% threshold is where cold-rate becomes a real signal vs Poisson noise on serverless. Sourced from vercel.function_invocation.count grouped by function_start_type.",
-};
-
-export function gate(signals) {
-  const cs = extractColdStarts(signals);
-  return cs
-    .filter((r) => r.coldPct > 0.4 && r.total >= 1000)
-    .map((r) => ({
-      kind: metadata.id,
-      scope: "route",
-      route: r.route,
-      files: [],
-      priority: Math.round(r.total * r.coldPct),
-      confidence: 0.92,
-      o11ySignal: `cold=${(r.coldPct * 100).toFixed(0)}%,inv=${r.total}`,
-      reason: "high cold-start rate on hot route",
-      question: `What initialization or bundle overhead makes ${r.route} cold-start ${(r.coldPct * 100).toFixed(0)}% of ${r.total} invocations?`,
-      evidence: {
-        metric: "fnStartTypeByRoute",
-        route: r.route,
-        coldPct: r.coldPct,
-        total: r.total,
-        coldCount: r.coldCount ?? null,
-      },
-    }));
-}
-
-function extractColdStarts(signals) {
-  const live = signals.metrics?.fnStartTypeByRoute;
-  if (Array.isArray(live?.rows) && live.rows.some((r) => "coldCount" in r || "coldPct" in r)) {
-    return live.rows
-      .filter((r) => r.route)
-      .map((r) => ({
-        route: r.route,
-        total: r.total ?? 0,
-        coldCount: r.coldCount ?? 0,
-        coldPct: r.coldPct ?? 0,
-      }));
-  }
-
-  // Legacy fixture: pre-derived coldStartByRoute rows.
-  const direct = signals.metrics?.coldStartByRoute;
-  if (Array.isArray(direct?.rows)) {
-    return direct.rows
-      .filter((r) => r.route)
-      .map((r) => ({ route: r.route, coldPct: r.coldPct ?? 0, total: r.total ?? 0 }));
-  }
-
-  // Older legacy fixture: series + summary shape.
-  const legacy = signals.metrics?.coldStarts;
-  if (Array.isArray(legacy?.series)) {
-    return legacy.series
-      .map((s) => {
-        const total = s.summary?.count ?? 0;
-        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
-        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
-      })
-      .filter((r) => r.route);
-  }
-
-  return [];
-}
+// Signal: `function_start_type` dimension on `vercel.function_invocation.count` (cold|hot|prewarmed).
+// Threshold WHY: 40%+ cold is fixable via Fluid keep-warm; 30% is the noise floor for serverless without keep-warm.
+// total>=1000/14d (~3/hr) keeps Poisson CI on cold rate at ~±5% near the 40% threshold.
+export const metadata = {
+  id: "cold_start",
+  threshold: "coldPct > 0.4 AND total >= 1000",
+  billingDimension: "function-duration",
+  scope: "route",
+  sourceCitation: "vercel-optimize gate threshold",
+  description:
+    "Routes where > 40% of invocations are cold-start, at meaningful traffic (>=1,000 total invocations in window). Cold starts add 200-800ms per request and break the perceived latency budget on cache-miss paths. The 40% threshold is where cold-rate becomes a real signal vs Poisson noise on serverless. Sourced from vercel.function_invocation.count grouped by function_start_type.",
+};
+
+export function gate(signals) {
+  const cs = extractColdStarts(signals);
+  return cs
+    .filter((r) => r.coldPct > 0.4 && r.total >= 1000)
+    .map((r) => ({
+      kind: metadata.id,
+      scope: "route",
+      route: r.route,
+      files: [],
+      priority: Math.round(r.total * r.coldPct),
+      confidence: 0.92,
+      o11ySignal: `cold=${(r.coldPct * 100).toFixed(0)}%,inv=${r.total}`,
+      reason: "high cold-start rate on hot route",
+      question: `What initialization or bundle overhead makes ${r.route} cold-start ${(r.coldPct * 100).toFixed(0)}% of ${r.total} invocations?`,
+      evidence: {
+        metric: "fnStartTypeByRoute",
+        route: r.route,
+        coldPct: r.coldPct,
+        total: r.total,
+        coldCount: r.coldCount ?? null,
+      },
+    }));
+}
+
+function extractColdStarts(signals) {
+  const live = signals.metrics?.fnStartTypeByRoute;
+  if (Array.isArray(live?.rows) && live.rows.some((r) => "coldCount" in r || "coldPct" in r)) {
+    return live.rows
+      .filter((r) => r.route)
+      .map((r) => ({
+        route: r.route,
+        total: r.total ?? 0,
+        coldCount: r.coldCount ?? 0,
+        coldPct: r.coldPct ?? 0,
+      }));
+  }
+
+  // Legacy fixture: pre-derived coldStartByRoute rows.
+  const direct = signals.metrics?.coldStartByRoute;
+  if (Array.isArray(direct?.rows)) {
+    return direct.rows
+      .filter((r) => r.route)
+      .map((r) => ({ route: r.route, coldPct: r.coldPct ?? 0, total: r.total ?? 0 }));
+  }
+
+  // Older legacy fixture: series + summary shape.
+  const legacy = signals.metrics?.coldStarts;
+  if (Array.isArray(legacy?.series)) {
+    return legacy.series
+      .map((s) => {
+        const total = s.summary?.count ?? 0;
+        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
+        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
+      })
+      .filter((r) => r.route);
+  }
+
+  return [];
+}

package/skills/craft/vercel-optimize/lib/gates/contract.mjs

@@ -1,82 +1,82 @@
-const VALID_SCOPES = new Set(["route", "file", "account"]);
-
-export class CandidateContractError extends Error {
-  constructor(errors) {
-    super(`gate candidate contract failed:\n${errors.map((e) => `- ${e}`).join("\n")}`);
-    this.name = "CandidateContractError";
-    this.errors = errors;
-  }
-}
-
-export function validateCandidates(candidates, ctx = {}) {
-  if (!Array.isArray(candidates)) {
-    throw new CandidateContractError([`${ctx.source ?? "gate"}: expected candidate array`]);
-  }
-  const errors = [];
-  for (let i = 0; i < candidates.length; i++) {
-    errors.push(...validateCandidate(candidates[i], { ...ctx, index: i }).errors);
-  }
-  if (errors.length > 0) throw new CandidateContractError(errors);
-  return candidates;
-}
-
-export function validateCandidate(candidate, ctx = {}) {
-  const label = candidateLabel(candidate, ctx);
-  const errors = [];
-  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
-    return { ok: false, errors: [`${label}: candidate must be an object`] };
-  }
-
-  if (!nonEmptyString(candidate.kind)) errors.push(`${label}: kind must be a non-empty string`);
-  if (!VALID_SCOPES.has(candidate.scope)) {
-    errors.push(`${label}: scope must be one of route, file, account`);
-  }
-  if (!Number.isFinite(candidate.priority))
-    errors.push(`${label}: priority must be a finite number`);
-  if (!Number.isFinite(candidate.confidence))
-    errors.push(`${label}: confidence must be a finite number`);
-  if (Array.isArray(candidate.files)) {
-    if (!candidate.files.every((f) => typeof f === "string" && f.length > 0)) {
-      errors.push(`${label}: files must contain only non-empty strings`);
-    }
-  } else {
-    errors.push(`${label}: files must be an array`);
-  }
-  if (!nonEmptyString(candidate.reason)) errors.push(`${label}: reason must be a non-empty string`);
-  if (!nonEmptyString(candidate.question))
-    errors.push(`${label}: question must be a non-empty string`);
-
-  if (candidate.scope === "route") {
-    const hasRoute = nonEmptyString(candidate.route);
-    const hasHostname = nonEmptyString(candidate.hostname);
-    if (!hasRoute && !hasHostname) {
-      errors.push(`${label}: route-scoped candidates must set route or hostname`);
-    }
-  }
-  if (candidate.scope === "file") {
-    if (candidate.route != null || candidate.hostname != null) {
-      errors.push(`${label}: file-scoped candidates must not set route or hostname`);
-    }
-    if (!Array.isArray(candidate.files) || candidate.files.length === 0) {
-      errors.push(`${label}: file-scoped candidates must include at least one file`);
-    }
-  }
-  if (candidate.scope === "account") {
-    if (candidate.route != null || candidate.hostname != null) {
-      errors.push(`${label}: account-scoped candidates must not set route or hostname`);
-    }
-  }
-
-  return { ok: errors.length === 0, errors };
-}
-
-function candidateLabel(candidate, ctx) {
-  const source = ctx.source ?? "gate";
-  const index = ctx.index == null ? "?" : ctx.index;
-  const kind = candidate?.kind ?? "?";
-  return `${source}[${index}] ${kind}`;
-}
-
-function nonEmptyString(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
+const VALID_SCOPES = new Set(["route", "file", "account"]);
+
+export class CandidateContractError extends Error {
+  constructor(errors) {
+    super(`gate candidate contract failed:\n${errors.map((e) => `- ${e}`).join("\n")}`);
+    this.name = "CandidateContractError";
+    this.errors = errors;
+  }
+}
+
+export function validateCandidates(candidates, ctx = {}) {
+  if (!Array.isArray(candidates)) {
+    throw new CandidateContractError([`${ctx.source ?? "gate"}: expected candidate array`]);
+  }
+  const errors = [];
+  for (let i = 0; i < candidates.length; i++) {
+    errors.push(...validateCandidate(candidates[i], { ...ctx, index: i }).errors);
+  }
+  if (errors.length > 0) throw new CandidateContractError(errors);
+  return candidates;
+}
+
+export function validateCandidate(candidate, ctx = {}) {
+  const label = candidateLabel(candidate, ctx);
+  const errors = [];
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    return { ok: false, errors: [`${label}: candidate must be an object`] };
+  }
+
+  if (!nonEmptyString(candidate.kind)) errors.push(`${label}: kind must be a non-empty string`);
+  if (!VALID_SCOPES.has(candidate.scope)) {
+    errors.push(`${label}: scope must be one of route, file, account`);
+  }
+  if (!Number.isFinite(candidate.priority))
+    errors.push(`${label}: priority must be a finite number`);
+  if (!Number.isFinite(candidate.confidence))
+    errors.push(`${label}: confidence must be a finite number`);
+  if (Array.isArray(candidate.files)) {
+    if (!candidate.files.every((f) => typeof f === "string" && f.length > 0)) {
+      errors.push(`${label}: files must contain only non-empty strings`);
+    }
+  } else {
+    errors.push(`${label}: files must be an array`);
+  }
+  if (!nonEmptyString(candidate.reason)) errors.push(`${label}: reason must be a non-empty string`);
+  if (!nonEmptyString(candidate.question))
+    errors.push(`${label}: question must be a non-empty string`);
+
+  if (candidate.scope === "route") {
+    const hasRoute = nonEmptyString(candidate.route);
+    const hasHostname = nonEmptyString(candidate.hostname);
+    if (!hasRoute && !hasHostname) {
+      errors.push(`${label}: route-scoped candidates must set route or hostname`);
+    }
+  }
+  if (candidate.scope === "file") {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: file-scoped candidates must not set route or hostname`);
+    }
+    if (!Array.isArray(candidate.files) || candidate.files.length === 0) {
+      errors.push(`${label}: file-scoped candidates must include at least one file`);
+    }
+  }
+  if (candidate.scope === "account") {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: account-scoped candidates must not set route or hostname`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function candidateLabel(candidate, ctx) {
+  const source = ctx.source ?? "gate";
+  const index = ctx.index == null ? "?" : ctx.index;
+  const kind = candidate?.kind ?? "?";
+  return `${source}[${index}] ${kind}`;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}