@decocms/blocks-cli 7.0.0

package/scripts/generate-sections.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env tsx
+/**
+ * Scans site section files and extracts convention-based metadata:
+ *   - export const eager = true       → alwaysEager
+ *   - export const cache = "listing"  → registerCacheableSections
+ *   - export const layout = true      → registerLayoutSections
+ *   - export const sync = true        → registerSectionsSync (bundled, not lazy)
+ *   - export const clientOnly = true  → registerSection with clientOnly
+ *   - export const seo = true         → registerSeoSections
+ *   - export function LoadingFallback → registerSection with loadingFallback
+ *
+ * Emits sections.gen.ts with metadata + sync imports for sections marked sync=true.
+ *
+ * Usage (from site root):
+ *   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-sections.ts
+ *
+ * CLI:
+ *   --sections-dir  override input  (default: src/sections)
+ *   --out-file      override output (default: src/server/cms/sections.gen.ts)
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+function arg(name: string, fallback: string): string {
+  const idx = args.indexOf(`--${name}`);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+}
+
+const sectionsDir = path.resolve(process.cwd(), arg("sections-dir", "src/sections"));
+const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/sections.gen.ts"));
+
+interface SectionMeta {
+  eager?: boolean;
+  neverDefer?: boolean;
+  cache?: string;
+  layout?: boolean;
+  sync?: boolean;
+  clientOnly?: boolean;
+  seo?: boolean;
+  hasLoadingFallback?: boolean;
+}
+
+const EXPORT_CONST_RE = /export\s+const\s+(eager|neverDefer|cache|layout|sync|clientOnly|seo)\s*=\s*(.+?)(?:;|\n)/g;
+// Detects `export function LoadingFallback(...)`, `export const LoadingFallback = ...`, etc.
+const LOADING_FALLBACK_INLINE_RE = /export\s+(?:function|const|let|var)\s+LoadingFallback\b/;
+// Detects re-exports like:
+//   export { LoadingFallback } from "..."
+//   export { default as LoadingFallback } from "..."
+//   export { Foo as LoadingFallback } from "..."
+// False-positive for `export { LoadingFallback as Foo }` (exports `Foo`, not
+// `LoadingFallback`), but that's unrealistic in section files and would surface
+// as a loud build error rather than silent CLS.
+const LOADING_FALLBACK_REEXPORT_RE = /export\s*\{[^}]*\bLoadingFallback\b[^}]*\}/;
+
+function hasLoadingFallbackExport(content: string): boolean {
+  return (
+    LOADING_FALLBACK_INLINE_RE.test(content) ||
+    LOADING_FALLBACK_REEXPORT_RE.test(content)
+  );
+}
+
+function extractMeta(content: string): SectionMeta | null {
+  const meta: SectionMeta = {};
+  let found = false;
+
+  for (const match of content.matchAll(EXPORT_CONST_RE)) {
+    const key = match[1] as keyof SectionMeta;
+    const rawValue = match[2].trim().replace(/['"]/g, "");
+    found = true;
+
+    if (key === "cache") {
+      meta.cache = rawValue;
+    } else if (rawValue === "true") {
+      (meta as any)[key] = true;
+    }
+  }
+
+  if (hasLoadingFallbackExport(content)) {
+    meta.hasLoadingFallback = true;
+    found = true;
+  }
+
+  return found ? meta : null;
+}
+
+function walkDir(dir: string, base: string = dir): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, base));
+    } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function fileToSectionKey(filePath: string, _sectionsDir: string): string {
+  const rel = path.relative(_sectionsDir, filePath).replace(/\\/g, "/");
+  return `site/sections/${rel}`;
+}
+
+function relativeImportPath(from: string, to: string): string {
+  let rel = path.relative(path.dirname(from), to).replace(/\\/g, "/");
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel.replace(/\.tsx?$/, "");
+}
+
+// ---------------------------------------------------------------------------
+
+if (!fs.existsSync(sectionsDir)) {
+  console.warn(`Sections directory not found: ${sectionsDir} — generating empty output.`);
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  fs.writeFileSync(outFile, [
+    "// Auto-generated — no sections found.",
+    "export const sectionMeta = {};",
+    "",
+  ].join("\n"));
+  process.exit(0);
+}
+
+const sectionFiles = walkDir(sectionsDir);
+const entries: Array<{ key: string; meta: SectionMeta; filePath: string }> = [];
+
+for (const filePath of sectionFiles) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const meta = extractMeta(content);
+  if (!meta) continue;
+  const key = fileToSectionKey(filePath, sectionsDir);
+  entries.push({ key, meta, filePath });
+}
+
+const syncEntries = entries.filter((e) => e.meta.sync);
+const fallbackEntries = entries.filter((e) => e.meta.hasLoadingFallback);
+
+const lines: string[] = [
+  "// Auto-generated by @decocms/blocks-cli/scripts/generate-sections.ts",
+  "// Do not edit manually. Add convention exports to your section files instead.",
+  "//",
+  "// Supported conventions:",
+  "//   export const eager = true       → prefer eager (defers past fold threshold)",
+  "//   export const neverDefer = true  → ALWAYS eager, ignores fold threshold",
+  "//   export const cache = \"listing\"  → SWR-cached section loader results",
+  "//   export const layout = true      → cached as layout (Header, Footer, Theme)",
+  "//   export const sync = true        → bundled synchronously (not lazy-loaded)",
+  "//   export const clientOnly = true  → skip SSR (client-only rendering)",
+  "//   export const seo = true         → SEO section (provides page head data)",
+  "//   export function LoadingFallback → skeleton shown while section loads",
+  "",
+];
+
+// Sync imports — sections marked sync=true get static imports for registerSectionsSync
+for (let i = 0; i < syncEntries.length; i++) {
+  const e = syncEntries[i];
+  const importPath = relativeImportPath(outFile, e.filePath);
+  const varName = `_sync${i}`;
+  lines.push(`import * as ${varName} from "${importPath}";`);
+}
+
+// LoadingFallback imports — sections with LoadingFallback that aren't sync-imported
+const nonSyncFallbacks = fallbackEntries.filter((e) => !e.meta.sync);
+for (let i = 0; i < nonSyncFallbacks.length; i++) {
+  const e = nonSyncFallbacks[i];
+  const importPath = relativeImportPath(outFile, e.filePath);
+  lines.push(`import { LoadingFallback as _fb${i} } from "${importPath}";`);
+}
+
+lines.push("");
+
+// Metadata map
+lines.push("export interface SectionMetaEntry {");
+lines.push("  eager?: boolean;");
+lines.push("  cache?: string;");
+lines.push("  layout?: boolean;");
+lines.push("  sync?: boolean;");
+lines.push("  clientOnly?: boolean;");
+lines.push("  seo?: boolean;");
+lines.push("  hasLoadingFallback?: boolean;");
+lines.push("}");
+lines.push("");
+lines.push("export const sectionMeta: Record<string, SectionMetaEntry> = {");
+for (const e of entries) {
+  const props = Object.entries(e.meta)
+    .map(([k, v]) => `${k}: ${typeof v === "string" ? `"${v}"` : v}`)
+    .join(", ");
+  lines.push(`  "${e.key}": { ${props} },`);
+}
+lines.push("};");
+lines.push("");
+
+// Sync components map
+if (syncEntries.length > 0) {
+  lines.push("export const syncComponents: Record<string, any> = {");
+  for (let i = 0; i < syncEntries.length; i++) {
+    lines.push(`  "${syncEntries[i].key}": _sync${i},`);
+  }
+  lines.push("};");
+} else {
+  lines.push("export const syncComponents: Record<string, any> = {};");
+}
+lines.push("");
+
+// LoadingFallback components map
+const allFallbacks = entries.filter((e) => e.meta.hasLoadingFallback);
+if (allFallbacks.length > 0) {
+  lines.push("export const loadingFallbacks: Record<string, React.ComponentType<any>> = {");
+  for (const e of allFallbacks) {
+    if (e.meta.sync) {
+      const syncIdx = syncEntries.indexOf(e);
+      lines.push(`  "${e.key}": _sync${syncIdx}.LoadingFallback,`);
+    } else {
+      const fbIdx = nonSyncFallbacks.indexOf(e);
+      lines.push(`  "${e.key}": _fb${fbIdx},`);
+    }
+  }
+  lines.push("};");
+} else {
+  lines.push("export const loadingFallbacks: Record<string, React.ComponentType<any>> = {};");
+}
+lines.push("");
+
+fs.mkdirSync(path.dirname(outFile), { recursive: true });
+fs.writeFileSync(outFile, lines.join("\n"));
+
+console.log(
+  `Generated section metadata for ${entries.length} sections → ${path.relative(process.cwd(), outFile)}`,
+);
+console.log(
+  `  ${syncEntries.length} sync, ${allFallbacks.length} with LoadingFallback, ` +
+  `${entries.filter((e) => e.meta.eager).length} eager, ` +
+  `${entries.filter((e) => e.meta.layout).length} layout, ` +
+  `${entries.filter((e) => e.meta.cache).length} cached`,
+);

package/scripts/htmx-analyze.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env tsx
+/**
+ * HTMX surface analyzer — CLI entry point.
+ *
+ * Inventories the `hx-*` surface of a Deco storefront so the engineer
+ * (or the next codemod wave) knows exactly what shapes are out there
+ * before starting the rewrite to React. Per D2 in the migration
+ * tooling policy, all htmx is rewritten on migration; no runtime is
+ * shipped in `@decocms/start`.
+ *
+ * Usage (from a site directory):
+ *   npx -p @decocms/start deco-htmx-analyze
+ *   npx -p @decocms/start deco-htmx-analyze --source /path/to/site
+ *   npx -p @decocms/start deco-htmx-analyze --json
+ *
+ * Options:
+ *   --source <dir>   Site directory to analyze (default: current directory)
+ *   --json           Emit machine-readable JSON instead of pretty text
+ *   --top <n>        Show top N files by occurrence count (default: 20)
+ *   --help, -h       Show this help
+ *
+ * Wave 13-A. Read-only. Codemods land in Wave 14.
+ */
+
+import * as path from "node:path";
+import { realFsAdapter } from "./migrate/post-cleanup/runner";
+import {
+	analyzeHtmx,
+	type HtmxCategory,
+	type HtmxInventory,
+} from "./migrate/analyzers/htmx-analyze";
+import { banner, bold, cyan, gray, green, red, yellow } from "./migrate/colors";
+
+interface CliOpts {
+	source: string;
+	json: boolean;
+	top: number;
+	help: boolean;
+}
+
+function parseArgs(args: string[]): CliOpts {
+	let source = ".";
+	let json = false;
+	let top = 20;
+	let help = false;
+	for (let i = 0; i < args.length; i++) {
+		switch (args[i]) {
+			case "--source":
+				source = args[++i];
+				break;
+			case "--json":
+				json = true;
+				break;
+			case "--top":
+				top = Number.parseInt(args[++i] ?? "20", 10);
+				if (Number.isNaN(top) || top < 0) top = 20;
+				break;
+			case "--help":
+			case "-h":
+				help = true;
+				break;
+			default:
+				console.error(`Unknown argument: ${args[i]}`);
+				process.exit(1);
+		}
+	}
+	return { source, json, top, help };
+}
+
+function printHelp(): void {
+	console.log(`deco-htmx-analyze
+
+Inventory the htmx surface (hx-* attributes) of a Deco storefront.
+
+Usage:
+  npx -p @decocms/start deco-htmx-analyze [options]
+
+Options:
+  --source <dir>   Site directory to analyze (default: cwd)
+  --json           Emit machine-readable JSON
+  --top <n>        Top N files by occurrence count (default: 20)
+  --help, -h       Show this help
+
+The output is read-only. Codemods that rewrite htmx to React are a
+planned follow-up — see the deco-to-tanstack-migration skill for the
+per-pattern rewrite recipes.
+`);
+}
+
+const CATEGORY_DESCRIPTIONS: Record<HtmxCategory, string> = {
+	"event-handler": "hx-on:* with no fetch attr — pure client-side handler",
+	"form-swap": "hx-post on a <form> with hx-target/hx-swap",
+	"click-swap": "hx-get/hx-post on a button with hx-target",
+	"auto-fetch": "hx-trigger=keyup/intersect/etc on input or auto-fired element",
+	"oob-swap": "hx-swap-oob / hx-select-oob — out-of-band patches",
+	boost: "hx-boost=true — link prefetch, already-SPA in TanStack Start",
+	unmatched: "hx-* attribute set that didn't match a known pattern",
+};
+
+const CATEGORY_RECIPES: Record<HtmxCategory, string> = {
+	"event-handler":
+		"replace hx-on:click={useScript(...)} with onClick={() => { ... }}",
+	"form-swap":
+		"<form onSubmit> + useMutation/server function; render result with state",
+	"click-swap":
+		"setState/setView + conditional render, or sub-route via TanStack Router",
+	"auto-fetch":
+		"debounced state + useQuery; for intersect use IntersectionObserver",
+	"oob-swap":
+		"manual: out-of-band has no 1:1; refactor to broadcast event + listener",
+	boost: "replace <a hx-boost> with TanStack Router <Link> (already SPA)",
+	unmatched: "manual review",
+};
+
+const CATEGORY_ORDER: HtmxCategory[] = [
+	"event-handler",
+	"click-swap",
+	"form-swap",
+	"auto-fetch",
+	"boost",
+	"oob-swap",
+	"unmatched",
+];
+
+function printText(inv: HtmxInventory, top: number): void {
+	banner("HTMX surface analysis");
+
+	if (inv.totalOccurrences === 0) {
+		console.log(green("✓ No hx-* attributes found.\n"));
+		return;
+	}
+
+	console.log(`${bold("Files with hx-* usage:")} ${inv.totalFiles}`);
+	console.log(`${bold("Total occurrences:")}    ${inv.totalOccurrences}\n`);
+
+	console.log(bold("By category:"));
+	for (const cat of CATEGORY_ORDER) {
+		const count = inv.byCategory[cat];
+		if (count === 0) continue;
+		const label = `${cat.padEnd(15)}`;
+		const desc = gray(CATEGORY_DESCRIPTIONS[cat]);
+		console.log(`  ${cyan(label)} ${String(count).padStart(4)}  ${desc}`);
+	}
+
+	console.log(`\n${bold("Migration recipes:")}`);
+	for (const cat of CATEGORY_ORDER) {
+		if (inv.byCategory[cat] === 0) continue;
+		console.log(`  ${cyan(cat.padEnd(15))} ${gray(CATEGORY_RECIPES[cat])}`);
+	}
+
+	console.log(`\n${bold(`Top ${top} files by occurrence:`)}`);
+	const slice = inv.files.slice(0, top);
+	const widest = Math.max(...slice.map((f) => f.file.length), 30);
+	for (const f of slice) {
+		const detail = CATEGORY_ORDER.filter((c) => f.byCategory[c] > 0)
+			.map((c) => `${c}=${f.byCategory[c]}`)
+			.join(", ");
+		console.log(
+			`  ${f.file.padEnd(widest)}  ${String(f.total).padStart(3)}  ${gray(detail)}`,
+		);
+	}
+
+	if (inv.files.length > top) {
+		console.log(gray(`  …and ${inv.files.length - top} more file(s)`));
+	}
+
+	console.log(`\n${bold("Sample call sites:")}`);
+	for (const cat of CATEGORY_ORDER) {
+		const samples = inv.samples[cat];
+		if (samples.length === 0) continue;
+		console.log(`  ${cyan(cat)}`);
+		for (const s of samples) {
+			const attrs = s.attrs.join(", ");
+			console.log(
+				`    ${gray(`${s.file}:${s.line}`)} <${s.tag}> [${attrs}]`,
+			);
+		}
+	}
+
+	const hasOob = inv.byCategory["oob-swap"] > 0;
+	const hasUnmatched = inv.byCategory.unmatched > 0;
+	if (hasOob || hasUnmatched) {
+		console.log();
+		if (hasOob) {
+			console.log(
+				yellow(
+					"⚠ oob-swap occurrences require manual rewrite — no 1:1 React equivalent.",
+				),
+			);
+		}
+		if (hasUnmatched) {
+			console.log(
+				yellow(
+					"⚠ unmatched occurrences require manual review — see Sample call sites.",
+				),
+			);
+		}
+	}
+	console.log();
+}
+
+function main(argv: string[]): number {
+	const opts = parseArgs(argv);
+	if (opts.help) {
+		printHelp();
+		return 0;
+	}
+
+	const sourceDir = path.resolve(opts.source);
+	const inv = analyzeHtmx(sourceDir, realFsAdapter);
+
+	if (opts.json) {
+		console.log(JSON.stringify(inv, null, 2));
+	} else {
+		printText(inv, opts.top);
+	}
+	return 0;
+}
+
+try {
+	process.exit(main(process.argv.slice(2)));
+} catch (err) {
+	console.error(red(`✗ deco-htmx-analyze failed: ${(err as Error).message}`));
+	if (process.env.DEBUG) console.error((err as Error).stack);
+	process.exit(1);
+}

package/scripts/lib/blocks-dedupe.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+import {
+  blockHasPath,
+  type Candidate,
+  decodeBlockName,
+  decodeBlockNameWithPasses,
+  mergeCandidates,
+  pickWinner,
+} from "./blocks-dedupe";
+
+const cand = (overrides: Partial<Candidate> & { file: string }): Candidate => ({
+  passes: 0,
+  mtimeMs: 0,
+  hasPath: true,
+  parsed: { path: "/" },
+  ...overrides,
+});
+
+describe("decodeBlockNameWithPasses", () => {
+  it("returns the literal key with a 0 pass count when filename has no encoding", () => {
+    expect(decodeBlockNameWithPasses("Header.json")).toEqual({ name: "Header", passes: 0 });
+  });
+
+  it("decodes a single layer of URL encoding", () => {
+    expect(decodeBlockNameWithPasses("pages-Home%20-%20LB-618509.json")).toEqual({
+      name: "pages-Home - LB-618509",
+      passes: 1,
+    });
+  });
+
+  it("decodes the bot's double-encoded scheme through to the literal key", () => {
+    // Bot encodes the raw prod URL-encoded key once: `encodeURIComponent("pages-Home%20-%20LB-618509")`.
+    expect(decodeBlockNameWithPasses("pages-Home%2520-%2520LB-618509.json")).toEqual({
+      name: "pages-Home - LB-618509",
+      passes: 2,
+    });
+  });
+
+  it("stops decoding when a literal % survives a round", () => {
+    // `%` alone isn't valid encoding — the loop catches the throw and stops.
+    expect(decodeBlockNameWithPasses("weird%percent.json")).toEqual({
+      name: "weird%percent",
+      passes: 0,
+    });
+  });
+});
+
+describe("decodeBlockName", () => {
+  it("matches decodeBlockNameWithPasses on the name", () => {
+    expect(decodeBlockName("pages-Home%2520-%2520LB-618509.json")).toBe("pages-Home - LB-618509");
+  });
+});
+
+describe("blockHasPath", () => {
+  it("returns true for live page blocks", () => {
+    expect(blockHasPath({ path: "/", sections: [] })).toBe(true);
+  });
+
+  it("returns false when path is null (zombie entry)", () => {
+    expect(blockHasPath({ path: null, sections: [] })).toBe(false);
+  });
+
+  it("returns false when path is missing", () => {
+    expect(blockHasPath({ sections: [] })).toBe(false);
+  });
+
+  it("returns false for empty path strings", () => {
+    expect(blockHasPath({ path: "" })).toBe(false);
+  });
+
+  it("returns false for non-objects", () => {
+    expect(blockHasPath(null)).toBe(false);
+    expect(blockHasPath("/")).toBe(false);
+  });
+});
+
+describe("pickWinner", () => {
+  it("prefers a candidate with a real path over a zombie", () => {
+    const live = cand({ file: "live.json", hasPath: true });
+    const zombie = cand({ file: "zombie.json", hasPath: false, parsed: { path: null } });
+    expect(pickWinner(live, zombie)).toBe(live);
+    expect(pickWinner(zombie, live)).toBe(live);
+  });
+
+  it("prefers higher decode-pass count when path-status matches", () => {
+    // The lebiscuit reproduction case: a stale single-encoded leftover with a
+    // newer mtime and larger size loses to the bot's double-encoded fresh file.
+    const stale = cand({
+      file: "pages-Home%20-%20LB-618509.json",
+      passes: 1,
+      mtimeMs: 2_000_000,
+    });
+    const fresh = cand({
+      file: "pages-Home%2520-%2520LB-618509.json",
+      passes: 2,
+      mtimeMs: 1_000_000,
+    });
+    expect(pickWinner(stale, fresh)).toBe(fresh);
+  });
+
+  it("falls through to mtime when pass count ties", () => {
+    const older = cand({ file: "a.json", passes: 1, mtimeMs: 1 });
+    const newer = cand({ file: "b.json", passes: 1, mtimeMs: 2 });
+    expect(pickWinner(older, newer)).toBe(newer);
+  });
+
+  it("falls through to lex filename when everything else ties", () => {
+    const a = cand({ file: "a.json", passes: 0, mtimeMs: 5 });
+    const b = cand({ file: "b.json", passes: 0, mtimeMs: 5 });
+    expect(pickWinner(a, b)).toBe(a);
+    expect(pickWinner(b, a)).toBe(a);
+  });
+});
+
+describe("mergeCandidates", () => {
+  it("returns each candidate unchanged when there are no collisions", () => {
+    const a = cand({ file: "Header.json" });
+    const b = cand({ file: "Footer.json" });
+    const result = mergeCandidates([
+      { candidate: a, key: "Header" },
+      { candidate: b, key: "Footer" },
+    ]);
+    expect(result.collisions).toEqual([]);
+    expect(result.winners).toEqual({ Header: a, Footer: b });
+  });
+
+  it("records a collision and picks the winner", () => {
+    const stale = cand({ file: "pages-Home%20-%20LB-618509.json", passes: 1, mtimeMs: 5 });
+    const fresh = cand({ file: "pages-Home%2520-%2520LB-618509.json", passes: 2, mtimeMs: 1 });
+    const result = mergeCandidates([
+      { candidate: stale, key: "pages-Home - LB-618509" },
+      { candidate: fresh, key: "pages-Home - LB-618509" },
+    ]);
+    expect(result.winners["pages-Home - LB-618509"]).toBe(fresh);
+    expect(result.collisions).toEqual([
+      {
+        key: "pages-Home - LB-618509",
+        files: ["pages-Home%20-%20LB-618509.json", "pages-Home%2520-%2520LB-618509.json"],
+        winner: "pages-Home%2520-%2520LB-618509.json",
+      },
+    ]);
+  });
+
+  it("collapses three-way collisions into one record without dropping the winner", () => {
+    const a = cand({ file: "a.json", passes: 0, mtimeMs: 1 });
+    const b = cand({ file: "b.json", passes: 1, mtimeMs: 2 });
+    const c = cand({ file: "c.json", passes: 2, mtimeMs: 3 });
+    const result = mergeCandidates([
+      { candidate: a, key: "k" },
+      { candidate: b, key: "k" },
+      { candidate: c, key: "k" },
+    ]);
+    expect(result.winners.k).toBe(c);
+    expect(result.collisions).toHaveLength(1);
+    expect(result.collisions[0].winner).toBe("c.json");
+    // a, b, and c should all be tracked (a and b as ignored, c as winner).
+    expect(new Set(result.collisions[0].files)).toEqual(new Set(["a.json", "b.json", "c.json"]));
+  });
+
+  it("prefers the live page over a zombie even when zombie has more passes", () => {
+    const livePlain = cand({
+      file: "Home.json",
+      passes: 0,
+      hasPath: true,
+      parsed: { path: "/" },
+    });
+    const zombieEncoded = cand({
+      file: "Home%2520.json",
+      passes: 2,
+      hasPath: false,
+      parsed: { path: null },
+    });
+    const result = mergeCandidates([
+      { candidate: zombieEncoded, key: "Home" },
+      { candidate: livePlain, key: "Home" },
+    ]);
+    expect(result.winners.Home).toBe(livePlain);
+  });
+});