@shop-on/theme-system 0.0.0-stage → 0.1.0

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/artifact.d.ts

@@ -0,0 +1,26 @@
+export type BuildThemeArtifactOptions = {
+  themeRoot: string | URL;
+  srcDir?: string | URL;
+  outputDir?: string | URL;
+  requiredDefaultLocale?: string;
+  requireReleaseNotes?: boolean;
+  configDirsToMirror?: string[];
+  log?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+export type BuildThemeArtifactResult = {
+  version: string;
+  presets: string[];
+  availableLocales: string[];
+  copiedReleaseNotes: boolean;
+};
+
+/** `.output/server` past this fails postbuild. */
+export const SERVER_BUDGET_BYTES: number;
+
+export class ThemeArtifactError extends Error {}
+
+export function buildThemeArtifact(
+  options: BuildThemeArtifactOptions,
+): Promise<BuildThemeArtifactResult>;

package/dist/artifact.mjs

@@ -0,0 +1,351 @@
+import { access, copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CONFIG_DIRS_TO_MIRROR = [
+  "templates",
+  "sections",
+  "blocks",
+  "section-groups",
+  "layouts",
+  "locales",
+];
+
+const PRESET_HANDLE_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const PRESET_HANDLE_MAX = 64;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+// Every file under `.output/server` is shipped to a storefront isolate on each
+// cold start. A full-featured theme is ~4.8 MB; past this, something leaked.
+export const SERVER_BUDGET_BYTES = 6 * 1024 * 1024;
+const TEST_FILE_RE = /\.test\b/;
+
+// A theme with no `src/listings/` (or an empty one) ships a single implicit
+// preset under this handle — the base templates with no overrides.
+const DEFAULT_PRESET_HANDLE = "default";
+
+// Housekeeping files that may sit beside preset directories (e.g. a `.gitkeep`
+// keeping an otherwise-empty `src/listings/` tracked in git). Ignored by the
+// scan so they neither count as presets nor trip the "must be a directory" guard.
+const LISTING_IGNORE = new Set([".gitkeep", ".DS_Store"]);
+const isIgnoredListingEntry = (name) => LISTING_IGNORE.has(name) || name.startsWith("._");
+
+export class ThemeArtifactError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ThemeArtifactError";
+  }
+}
+
+function pathFromRoot(root) {
+  if (root instanceof URL) return fileURLToPath(root);
+  return String(root);
+}
+
+function fail(message) {
+  throw new ThemeArtifactError(message);
+}
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(filePath, description) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (err) {
+    fail(`could not read ${description} at ${filePath}: ${err.message}`);
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    fail(`${description} is not valid JSON: ${err.message}`);
+  }
+}
+
+async function readVersion(pkgPath) {
+  const pkg = await readJson(pkgPath, "package.json");
+  const version = pkg.version;
+  if (typeof version !== "string" || !SEMVER_RE.test(version)) {
+    fail(`package.json version '${version}' is not valid semver — expected X.Y.Z (e.g. 1.0.0)`);
+  }
+  return version;
+}
+
+async function readThemeConfig(themeConfigPath, requiredDefaultLocale) {
+  if (!(await exists(themeConfigPath))) {
+    fail(`theme.config.json not found at ${themeConfigPath}`);
+  }
+
+  const cfg = await readJson(themeConfigPath, "theme.config.json");
+  if (!Array.isArray(cfg.locales) || cfg.locales.length === 0) {
+    fail(`theme.config.json#locales must be a non-empty array`);
+  }
+  if (requiredDefaultLocale && !cfg.locales.includes(requiredDefaultLocale)) {
+    fail(`theme.config.json#locales must include "${requiredDefaultLocale}"`);
+  }
+  return cfg.locales;
+}
+
+async function readReleaseNotes(releaseNotesPath, { requireReleaseNotes, warn }) {
+  if (!(await exists(releaseNotesPath))) {
+    const message = `release-notes.md not found at ${releaseNotesPath} — artifact will be missing canonical release notes`;
+    if (requireReleaseNotes) fail(message);
+    warn?.(message);
+    return null;
+  }
+  return readFile(releaseNotesPath, "utf8");
+}
+
+function validatePresetHandle(name) {
+  if (name.length < 1 || name.length > PRESET_HANDLE_MAX) {
+    fail(
+      `preset handle '${name}' has invalid length ${name.length} — must be 1..${PRESET_HANDLE_MAX} chars`,
+    );
+  }
+  if (!PRESET_HANDLE_RE.test(name)) {
+    fail(
+      `preset handle '${name}' is invalid — must be lowercase kebab-case ASCII (a-z, 0-9, hyphen), no leading/trailing hyphen`,
+    );
+  }
+}
+
+// The orchestrator normalizes settings-data preset keys the same way when it
+// matches them against the artifact's handle at boot — keep the two in sync.
+function normalizePresetKey(value) {
+  return value
+    .normalize("NFC")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+}
+
+// The synthesized preset's handle must line up with `config/settings-data.json`:
+// at boot the orchestrator flattens the settings `presets` wrapper by the
+// artifact's declared handle, so a wrapper the editor keyed (e.g. "kito") paired
+// with a hardcoded "default" handle fails every install. When the wrapper
+// exists, derive the handle from it — the key `current.preset` selects, or the
+// sole key. A theme with no settings-data (or a flat, wrapper-less one) keeps
+// "default": the orchestrator skips flattening entirely for those.
+async function synthesizedPresetHandle(srcDir) {
+  const settingsPath = path.join(srcDir, "config", "settings-data.json");
+  if (!(await exists(settingsPath))) return DEFAULT_PRESET_HANDLE;
+
+  const data = await readJson(settingsPath, "settings-data.json");
+  const presets = data?.presets;
+  if (!presets || typeof presets !== "object" || Array.isArray(presets)) {
+    return DEFAULT_PRESET_HANDLE;
+  }
+
+  const keys = Object.keys(presets);
+  const current = data?.current?.preset;
+  const selected =
+    (typeof current === "string" && keys.includes(current) ? current : null) ??
+    (keys.length === 1 ? keys[0] : null);
+  if (!selected) {
+    fail(
+      `src/listings/ is absent but settings-data.json holds ${keys.length} presets and current.preset selects none — cannot name the synthesized preset`,
+    );
+  }
+
+  const handle = normalizePresetKey(selected);
+  validatePresetHandle(handle);
+  return handle;
+}
+
+// Resolve the theme's presets. A theme with no `src/listings/` (or an empty
+// one) ships a single implicit preset instead of failing: the orchestrator's
+// preset materializer deep-merges `listings/<handle>/` over the base templates,
+// so an empty preset dir renders the base unchanged, and the API validator only
+// requires the declared handle to have a matching (possibly empty) directory.
+// Returns `{ handles, synthesizeDefault }` — when synthesizing, the caller
+// creates an empty `.output/config/listings/<handle>/` instead of mirroring
+// `src/listings/`, with the handle taken from settings-data's presets wrapper
+// (see synthesizedPresetHandle) or "default" when there is none.
+async function resolvePresets(srcListings, srcDir) {
+  if (!(await exists(srcListings))) {
+    return { handles: [await synthesizedPresetHandle(srcDir)], synthesizeDefault: true };
+  }
+
+  let entries;
+  try {
+    entries = await readdir(srcListings, { withFileTypes: true });
+  } catch (err) {
+    fail(`could not read src/listings/: ${err.message}`);
+  }
+
+  const handles = [];
+  for (const entry of entries) {
+    if (isIgnoredListingEntry(entry.name)) continue;
+    if (!entry.isDirectory()) {
+      fail(
+        `src/listings/${entry.name} is not a directory — only preset directories are allowed under src/listings/`,
+      );
+    }
+    validatePresetHandle(entry.name);
+    handles.push(entry.name);
+  }
+  if (handles.length === 0) {
+    return { handles: [await synthesizedPresetHandle(srcDir)], synthesizeDefault: true };
+  }
+  handles.sort();
+  return { handles, synthesizeDefault: false };
+}
+
+async function copyDir(src, dest, { filter } = {}) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, { filter });
+    } else if (entry.isFile()) {
+      if (filter && !filter(entry.name)) continue;
+      await copyFile(srcPath, destPath);
+    } else {
+      fail(`unsupported entry type at ${srcPath} — only regular files and directories allowed`);
+    }
+  }
+}
+
+const isJsonFile = (name) => name.endsWith(".json");
+
+async function mirrorConfig({ srcDir, outputConfig, configDirsToMirror }) {
+  await mkdir(outputConfig, { recursive: true });
+
+  for (const file of ["settings-schema.json", "settings-data.json"]) {
+    const src = path.join(srcDir, "config", file);
+    if (!(await exists(src))) {
+      if (file === "settings-schema.json") {
+        fail(`required src/config/${file} is missing`);
+      }
+      continue;
+    }
+    await copyFile(src, path.join(outputConfig, file));
+  }
+
+  for (const dir of configDirsToMirror) {
+    const src = path.join(srcDir, dir);
+    if (await exists(src)) {
+      await copyDir(src, path.join(outputConfig, dir), { filter: isJsonFile });
+    }
+  }
+}
+
+async function listFiles(dir) {
+  const files = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...(await listFiles(full)));
+    else files.push(full);
+  }
+  return files;
+}
+
+// The server bundle's two leaks: a test file (it registers as a phantom type and
+// pulls in the vitest runtime) and anything that pushes it over the budget.
+async function checkServerBundle(serverDir) {
+  if (!(await exists(serverDir))) return null;
+  const files = await listFiles(serverDir);
+  const tests = files.filter((file) => TEST_FILE_RE.test(path.basename(file)));
+  if (tests.length) {
+    fail(
+      `.output/server holds test files — a test glob leaked into the server build: ${tests
+        .map((file) => path.relative(serverDir, file))
+        .join(", ")}`,
+    );
+  }
+  let bytes = 0;
+  for (const file of files) bytes += (await stat(file)).size;
+  if (bytes > SERVER_BUDGET_BYTES) {
+    const mb = (n) => `${(n / 1024 / 1024).toFixed(2)} MB`;
+    fail(
+      `.output/server is ${mb(bytes)}, over the ${mb(SERVER_BUDGET_BYTES)} budget — look for a browser-only library in .output/server/_libs`,
+    );
+  }
+  return bytes;
+}
+
+async function writeThemeJson(outputThemeJson, version, presets, locales) {
+  const payload = JSON.stringify({ version, presets, available_locales: locales }, null, 2) + "\n";
+  await writeFile(outputThemeJson, payload, "utf8");
+}
+
+async function copyReleaseNotes(outputReleaseNotes, body) {
+  if (body == null) return false;
+  await writeFile(outputReleaseNotes, body, "utf8");
+  return true;
+}
+
+export async function buildThemeArtifact(options) {
+  const themeRoot = path.resolve(pathFromRoot(options.themeRoot));
+  const srcDir = options.srcDir
+    ? path.resolve(pathFromRoot(options.srcDir))
+    : path.join(themeRoot, "src");
+  const outputDir = options.outputDir
+    ? path.resolve(pathFromRoot(options.outputDir))
+    : path.join(themeRoot, ".output");
+  const outputConfig = path.join(outputDir, "config");
+  const srcListings = path.join(srcDir, "listings");
+  const outputListings = path.join(outputConfig, "listings");
+  const releaseNotesPath = path.join(themeRoot, "release-notes.md");
+  const outputReleaseNotes = path.join(outputDir, "release-notes.md");
+  const outputThemeJson = path.join(outputDir, "theme.json");
+  const themeConfigPath = path.join(themeRoot, "theme.config.json");
+  const configDirsToMirror = options.configDirsToMirror ?? CONFIG_DIRS_TO_MIRROR;
+
+  if (!(await exists(outputDir))) {
+    fail(`.output/ does not exist — run \`vite build\` before postbuild`);
+  }
+
+  const serverBytes = await checkServerBundle(path.join(outputDir, "server"));
+  if (serverBytes !== null) {
+    options.log?.(`server bundle: ${(serverBytes / 1024 / 1024).toFixed(2)} MB`);
+  }
+
+  const version = await readVersion(path.join(themeRoot, "package.json"));
+  options.log?.(`version: ${version}`);
+
+  const releaseNotes = await readReleaseNotes(releaseNotesPath, {
+    requireReleaseNotes: options.requireReleaseNotes ?? false,
+    warn: options.warn,
+  });
+
+  const locales = await readThemeConfig(themeConfigPath, options.requiredDefaultLocale);
+  options.log?.(`locales: [${locales.join(", ")}]`);
+
+  const { handles: presets, synthesizeDefault } = await resolvePresets(srcListings, srcDir);
+  options.log?.(`presets: [${presets.join(", ")}]`);
+
+  await mirrorConfig({ srcDir, outputConfig, configDirsToMirror });
+  options.log?.(`mirrored config + schemas → .output/config/`);
+
+  await mkdir(outputConfig, { recursive: true });
+  if (synthesizeDefault) {
+    await mkdir(path.join(outputListings, presets[0]), { recursive: true });
+    options.log?.(
+      `no src/listings/ — synthesized "${presets[0]}" preset (base templates, no overrides)`,
+    );
+  } else {
+    await copyDir(srcListings, outputListings);
+    options.log?.(`mirrored ${presets.length} preset(s) → .output/config/listings/`);
+  }
+
+  await writeThemeJson(outputThemeJson, version, presets, locales);
+  options.log?.(`wrote .output/theme.json`);
+
+  const copiedReleaseNotes = await copyReleaseNotes(outputReleaseNotes, releaseNotes);
+  if (copiedReleaseNotes) options.log?.(`wrote .output/release-notes.md`);
+
+  options.log?.(`done`);
+  return { version, presets, availableLocales: locales, copiedReleaseNotes };
+}

package/dist/check-locales.d.ts

@@ -0,0 +1,23 @@
+export type CheckThemeLocalesOptions = {
+  themeRoot: string | URL;
+};
+
+export type MissingLocaleKey = {
+  locale: string;
+  /** The catalog file the key is missing from, e.g. `en.default.schema.json`. */
+  catalog: string;
+  /** `t:group.key` for a schema key, `ns.key` (or `a|b.key`) for a runtime one. */
+  key: string;
+  /** Absolute path of the first file that asks for the key. */
+  file: string;
+  line: number;
+};
+
+export function findMissingLocaleKeys(options: CheckThemeLocalesOptions): {
+  locales: string[];
+  schemaKeyCount: number;
+  runtimeKeyCount: number;
+  missing: MissingLocaleKey[];
+};
+
+export function checkThemeLocales(options: CheckThemeLocalesOptions): boolean;

package/dist/check-locales.mjs

@@ -0,0 +1,147 @@
+// Every translation key a theme asks for must exist in every catalog.
+//
+// Two vocabularies, two failure modes, and only one of them is loud:
+//   - a schema `t:` key renders its raw name in the editor. Visible, ugly, cheap
+//     to spot.
+//   - a RUNTIME key throws at render (`Could not resolve … in messages for
+//     locale`) on whichever page happens to use it. That can ship, because the
+//     compiler never sees a string passed to `t()`.
+//
+// A theme wires it as `scripts/check-locales.mjs` → `pnpm -C themes/<name> check:locales`.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function walk(dir, match, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, match, out);
+    else if (match.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+function read(file) {
+  return JSON.parse(fs.readFileSync(file, "utf-8"));
+}
+
+function lookup(catalog, dotted) {
+  let node = catalog;
+  for (const part of dotted.split(".")) {
+    if (typeof node !== "object" || node === null || !(part in node)) return undefined;
+    node = node[part];
+  }
+  return typeof node === "string" ? node : undefined;
+}
+
+function lineAt(source, index) {
+  return source.slice(0, index).split("\n").length;
+}
+
+/** Every key the theme asks for that some catalog lacks. Each key carries the
+ * first place it is asked for, so a report can point at the caller. */
+export function findMissingLocaleKeys({ themeRoot }) {
+  const root = themeRoot instanceof URL ? fileURLToPath(themeRoot) : String(themeRoot);
+  const srcDir = path.join(root, "src");
+
+  const locales = fs
+    .readdirSync(path.join(srcDir, "locales"))
+    .filter((f) => f.endsWith(".default.json"))
+    .map((f) => f.replace(".default.json", ""));
+
+  // --- schema keys: `"t:group.key"` anywhere in a section/block/config JSON ---
+  const schemaKeys = new Map();
+  for (const file of walk(srcDir, /\.json$/)) {
+    if (file.includes(`${path.sep}locales${path.sep}`)) continue;
+    const source = fs.readFileSync(file, "utf-8");
+    for (const match of source.matchAll(/"t:([a-z0-9_.]+)"/g)) {
+      if (!schemaKeys.has(match[1])) {
+        schemaKeys.set(match[1], { file, line: lineAt(source, match.index) });
+      }
+    }
+  }
+
+  // --- runtime keys: `const t = useTranslations("ns")` … `t("key")` ------------
+  // Each translator local is bound to the namespace(s) it was created with, so a
+  // key is checked against THOSE rather than every namespace in the file. Matching
+  // the local by name matters: a file that calls its translator `content` or
+  // `a11y` rather than `t` used to be skipped in silence, and a missing RUNTIME
+  // key throws at render.
+  //
+  // A name declared twice in one file — two components in `header-drawer.tsx` each
+  // have their own `t` — keeps both namespaces and the key may resolve under
+  // either. Telling those two `t`s apart needs a scope, which needs a parser; the
+  // bug worth catching is a key that exists under NO namespace it could have come
+  // from, and this still catches that.
+  const runtimeKeys = new Map();
+  for (const file of walk(srcDir, /\.tsx?$/)) {
+    if (file.endsWith(".test.ts") || file.endsWith(".test.tsx")) continue;
+    const source = fs.readFileSync(file, "utf-8");
+    const bindings = new Map();
+    for (const [, name, ns] of source.matchAll(
+      /(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*useTranslations\(\s*"([^"]+)"\s*\)/g,
+    )) {
+      if (!bindings.has(name)) bindings.set(name, new Set());
+      bindings.get(name).add(ns);
+    }
+    if (bindings.size === 0) continue;
+    for (const [name, namespaces] of bindings) {
+      const calls = new RegExp(`\\b${name}\\(\\s*"([a-z0-9_.]+)"`, "g");
+      for (const match of source.matchAll(calls)) {
+        const entry = JSON.stringify([[...namespaces], match[1]]);
+        if (!runtimeKeys.has(entry)) {
+          runtimeKeys.set(entry, { file, line: lineAt(source, match.index) });
+        }
+      }
+    }
+  }
+
+  const missing = [];
+  for (const locale of locales) {
+    const catalog = `${locale}.default.schema.json`;
+    const schema = read(path.join(srcDir, "locales", catalog));
+    for (const [key, at] of schemaKeys) {
+      if (lookup(schema, key) === undefined) {
+        missing.push({ locale, catalog, key: `t:${key}`, ...at });
+      }
+    }
+  }
+  for (const locale of locales) {
+    const catalog = `${locale}.default.json`;
+    const runtime = read(path.join(srcDir, "locales", catalog));
+    for (const [entry, at] of runtimeKeys) {
+      const [namespaces, key] = JSON.parse(entry);
+      if (!namespaces.some((ns) => lookup(runtime, `${ns}.${key}`) !== undefined)) {
+        missing.push({ locale, catalog, key: `${namespaces.join("|")}.${key}`, ...at });
+      }
+    }
+  }
+
+  return { locales, schemaKeyCount: schemaKeys.size, runtimeKeyCount: runtimeKeys.size, missing };
+}
+
+/** Logs per-catalog coverage and every missing key; returns `false` when any
+ * catalog is missing one. */
+export function checkThemeLocales({ themeRoot }) {
+  const { locales, schemaKeyCount, runtimeKeyCount, missing } = findMissingLocaleKeys({
+    themeRoot,
+  });
+
+  const report = (label, total, catalog) => {
+    for (const locale of locales) {
+      const keys = missing
+        .filter((m) => m.catalog === catalog(locale))
+        .map((m) => m.key)
+        .sort();
+      console.log(`${locale} ${label} ${total - keys.length}/${total}`);
+      for (const key of keys) console.log(`  MISSING ${key}`);
+    }
+  };
+  report("schema: ", schemaKeyCount, (locale) => `${locale}.default.schema.json`);
+  report("runtime:", runtimeKeyCount, (locale) => `${locale}.default.json`);
+
+  if (missing.length) {
+    console.error("\nA missing runtime key throws at render; a missing schema key shows raw.");
+  }
+  return missing.length === 0;
+}

package/dist/check.d.ts

@@ -0,0 +1,45 @@
+export type ThemeCheckRule =
+  | "locales-complete"
+  | "literal-color"
+  | "hardcoded-buyer-string"
+  | "raw-internal-link"
+  | "tenant-picker-default"
+  | "section-presets"
+  | "schema-label-key"
+  | "t-key-in-tsx"
+  | "theme-info"
+  | "release-notes-version"
+  | "scheme-contrast"
+  | "invalid-suppression";
+
+export type ThemeCheckFinding = {
+  /** Relative to the theme root, `/`-separated. */
+  file: string;
+  line: number;
+  rule: ThemeCheckRule;
+  message: string;
+  /** The recipe the rule enforces, relative to the theme root. */
+  docs: string;
+};
+
+/** `{ [file]: { [rule]: count } }`. */
+export type ThemeCheckBaseline = Record<string, Partial<Record<ThemeCheckRule, number>>>;
+
+export const BASELINE_FILE: "theme-check.baseline.json";
+
+export const RULES: Record<ThemeCheckRule, { docs: string; release?: true }>;
+
+export function checkTheme(options: {
+  themeRoot: string | URL;
+  /** Also run the rules only a hand-off needs (`theme-info`). */
+  release?: boolean;
+}): ThemeCheckFinding[];
+
+export function toBaseline(findings: ThemeCheckFinding[]): ThemeCheckBaseline;
+
+export function applyBaseline(
+  findings: ThemeCheckFinding[],
+  baseline: ThemeCheckBaseline,
+): ThemeCheckFinding[];
+
+export function runThemeCheck(options: { themeRoot: string | URL; argv?: string[] }): boolean;