@shop-on/theme-system 0.5.0 → 0.6.0

package/dist/artifact.mjs

@@ -11,6 +11,10 @@ const CONFIG_DIRS_TO_MIRROR = [
   "locales",
 ];
 
+// `src/ai/` (the theme's guide and recipes for the editor tools) lands at
+// `config/ai/`; anything `aiManifest` refuses fails the build.
+const AI_DIR = "ai";
+
 const PRESET_HANDLE_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 const PRESET_HANDLE_MAX = 64;
 const SEMVER_RE = /^\d+\.\d+\.\d+$/;
@@ -91,7 +95,15 @@ async function readThemeConfig(themeConfigPath, requiredDefaultLocale) {
   if (requiredDefaultLocale && !cfg.locales.includes(requiredDefaultLocale)) {
     fail(`theme.config.json#locales must include "${requiredDefaultLocale}"`);
   }
-  return cfg.locales;
+  // The hosts a developer's theme may reach beyond Lite's API (theme.json#egress).
+  // Only the shape is checked here; the theme store owns the host rules.
+  if (
+    cfg.egress !== undefined &&
+    !(Array.isArray(cfg.egress) && cfg.egress.every((host) => typeof host === "string"))
+  ) {
+    fail(`theme.config.json#egress must be an array of hostnames`);
+  }
+  return { locales: cfg.locales, egress: cfg.egress };
 }
 
 async function readReleaseNotes(releaseNotesPath, { requireReleaseNotes, warn }) {
@@ -241,6 +253,49 @@ async function mirrorConfig({ srcDir, outputConfig, configDirsToMirror }) {
   }
 }
 
+async function readSchemaDir(dir) {
+  if (!(await exists(dir))) return [];
+  const schemas = [];
+  for (const file of (await readdir(dir)).sort()) {
+    if (!file.endsWith(".json") || file.startsWith("._")) continue;
+    const schema = await readJson(path.join(dir, file), `${path.basename(dir)}/${file}`);
+    schemas.push({ ...schema, type: file.replace(/\.json$/, "") });
+  }
+  return schemas;
+}
+
+// `src/ai/` under the rule every host and the upload apply, then each recipe
+// against the theme's own schemas: a recipe that names a section, block or
+// setting the theme doesn't have fails the build, as a missing locale does.
+// Loaded only for a theme that ships `src/ai/`: the reader is TypeScript,
+// which the in-repo source of this package reaches only through a TS-aware
+// loader.
+async function mirrorAi(srcDir, outputConfig) {
+  const aiSrc = path.join(srcDir, AI_DIR);
+  if (!(await exists(aiSrc))) return 0;
+  const { readThemeAiDir } = await import("@shop-on/theme-contract/ai-files");
+  const { checkRecipe } = await import("@shop-on/theme-contract/editor-tools");
+  const ai = await readThemeAiDir(aiSrc);
+  if (ai.skipped.length) fail(`src/ai/${ai.skipped[0].reason}`);
+  const schemas = {
+    sections: await readSchemaDir(path.join(srcDir, "sections")),
+    blocks: await readSchemaDir(path.join(srcDir, "blocks")),
+  };
+  for (const recipe of ai.recipes) {
+    const bad = checkRecipe(recipe, schemas);
+    if (bad) fail(`src/ai/recipes/${recipe.handle}.json: ${bad}`);
+  }
+  const out = path.join(outputConfig, AI_DIR);
+  await mkdir(out, { recursive: true });
+  if (ai.recipes.length) await mkdir(path.join(out, "recipes"), { recursive: true });
+  if (ai.guide) await writeFile(path.join(out, "guide.md"), ai.guide);
+  for (const recipe of ai.recipes) {
+    const file = path.join("recipes", `${recipe.handle}.json`);
+    await copyFile(path.join(aiSrc, file), path.join(out, file));
+  }
+  return ai.recipes.length;
+}
+
 async function listFiles(dir) {
   const files = [];
   for (const entry of await readdir(dir, { withFileTypes: true })) {
@@ -275,8 +330,9 @@ async function checkServerBundle(serverDir) {
   return bytes;
 }
 
-async function writeThemeJson(outputThemeJson, version, presets, locales) {
-  const payload = JSON.stringify({ version, presets, available_locales: locales }, null, 2) + "\n";
+async function writeThemeJson(outputThemeJson, version, presets, locales, egress) {
+  const payload =
+    JSON.stringify({ version, presets, available_locales: locales, egress }, null, 2) + "\n";
   await writeFile(outputThemeJson, payload, "utf8");
 }
 
@@ -320,7 +376,7 @@ export async function buildThemeArtifact(options) {
     warn: options.warn,
   });
 
-  const locales = await readThemeConfig(themeConfigPath, options.requiredDefaultLocale);
+  const { locales, egress } = await readThemeConfig(themeConfigPath, options.requiredDefaultLocale);
   options.log?.(`locales: [${locales.join(", ")}]`);
 
   const { handles: presets, synthesizeDefault } = await resolvePresets(srcListings, srcDir);
@@ -329,6 +385,9 @@ export async function buildThemeArtifact(options) {
   await mirrorConfig({ srcDir, outputConfig, configDirsToMirror });
   options.log?.(`mirrored config + schemas → .output/config/`);
 
+  const recipes = await mirrorAi(srcDir, outputConfig);
+  if (recipes > 0) options.log?.(`checked ${recipes} recipe(s) against the theme's schemas`);
+
   await mkdir(outputConfig, { recursive: true });
   if (synthesizeDefault) {
     await mkdir(path.join(outputListings, presets[0]), { recursive: true });
@@ -340,7 +399,7 @@ export async function buildThemeArtifact(options) {
     options.log?.(`mirrored ${presets.length} preset(s) → .output/config/listings/`);
   }
 
-  await writeThemeJson(outputThemeJson, version, presets, locales);
+  await writeThemeJson(outputThemeJson, version, presets, locales, egress);
   options.log?.(`wrote .output/theme.json`);
 
   const copiedReleaseNotes = await copyReleaseNotes(outputReleaseNotes, releaseNotes);

package/dist/check.d.ts

@@ -10,6 +10,7 @@ export type ThemeCheckRule =
   | "theme-info"
   | "release-notes-version"
   | "scheme-contrast"
+  | "closest-provider"
   | "invalid-suppression";
 
 export type ThemeCheckFinding = {
@@ -20,6 +21,8 @@ export type ThemeCheckFinding = {
   message: string;
   /** The recipe the rule enforces, relative to the theme root. */
   docs: string;
+  /** Printed, but doesn't fail the run. */
+  warning?: true;
 };
 
 /** `{ [file]: { [rule]: count } }`. */
@@ -27,7 +30,7 @@ export type ThemeCheckBaseline = Record<string, Partial<Record<ThemeCheckRule, n
 
 export const BASELINE_FILE: "theme-check.baseline.json";
 
-export const RULES: Record<ThemeCheckRule, { docs: string; release?: true }>;
+export const RULES: Record<ThemeCheckRule, { docs: string; release?: true; warning?: true }>;
 
 export function checkTheme(options: {
   themeRoot: string | URL;

package/dist/check.mjs

@@ -9,6 +9,8 @@
 //   --baseline <file>  counts to tolerate (default: theme-check.baseline.json)
 //   --write-baseline   record today's findings as the baseline and exit 0
 //
+// A `warning` rule's findings print with the rest but don't fail the run.
+//
 // A finding in a `.tsx` can be suppressed on the line above it, with a reason:
 //   // theme-check-disable-next-line literal-color: white over the hero image
 //   {/* theme-check-disable-next-line raw-internal-link: works before hydration */}
@@ -17,6 +19,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, styleText } from "node:util";
+import { PICKER_RESOURCES } from "@shop-on/theme-contract/closest-scope";
 import { contrastRatio, parseColor } from "@shop-on/theme-runtime/color";
 import { findMissingLocaleKeys } from "./check-locales.mjs";
 
@@ -40,6 +43,10 @@ export const RULES = {
   "theme-info": { docs: "recipes/quality.md#completeness", release: true },
   "release-notes-version": { docs: "SKILL.md#shipping-a-version" },
   "scheme-contrast": { docs: "recipes/styling.md#color-schemes" },
+  "closest-provider": {
+    docs: "recipes/dynamic-sources.md#closest-resources--closest_",
+    warning: true,
+  },
   "invalid-suppression": { docs: "recipes/quality.md#suppressing-a-finding" },
 };
 
@@ -429,6 +436,73 @@ const CHECKS = {
     }
     return out;
   },
+
+  "closest-provider": (ctx) => {
+    const out = [];
+    for (const { file } of ctx.schemas) {
+      const source = ctx.text(file);
+      const schema = ctx.json(file);
+      const settings = Array.isArray(schema.settings) ? schema.settings : [];
+      const provides =
+        schema.provides && typeof schema.provides === "object" ? schema.provides : {};
+      const providesAt = Math.max(source.indexOf('"provides"'), 0);
+      const warn = (line, message) => out.push({ file, line, rule: "closest-provider", message });
+
+      const pickers = {};
+      for (const setting of settings) {
+        const resource = PICKER_RESOURCES[setting?.type];
+        if (resource && setting.id) (pickers[resource] ??= []).push(setting.id);
+      }
+      for (const [resource, [first, ...rest]] of Object.entries(pickers)) {
+        if (!rest.length || provides[resource]) continue;
+        for (const id of rest) {
+          warn(
+            jsonLine(source, "id", id),
+            `only "${first}" provides ${resource} to closest_* sources; a second ${resource} picker ("${id}") never does`,
+          );
+        }
+      }
+
+      const staticBlocks = new Set(
+        (Array.isArray(schema.blocks) ? schema.blocks : [])
+          .filter((block) => block?.static && typeof block.type === "string")
+          .map((block) => block.type.replace(/^_/, "")),
+      );
+      const settingIds = new Set(settings.map((setting) => setting?.id));
+      const listedBy = new Map();
+      for (const [resource, decl] of Object.entries(provides)) {
+        const key = new RegExp(`"${escapeRegExp(resource)}"\\s*:`).exec(source.slice(providesAt));
+        const at = providesAt + (key?.index ?? 0);
+        // `$theme` (THEME_FED in @shop-on/theme-contract): a list the theme
+        // feeds itself, with no picker to name.
+        if (decl?.from !== "$theme" && !settingIds.has(decl?.from)) {
+          warn(
+            jsonLine(source, "from", decl?.from, at),
+            `provides.${resource}.from "${decl?.from}" names no setting on this schema; it provides nothing`,
+          );
+        }
+        for (const id of Array.isArray(decl?.each) ? decl.each : []) {
+          const line = lineAt(source, Math.max(source.indexOf(`"${id}"`, at), 0));
+          if (!staticBlocks.has(id)) {
+            warn(
+              line,
+              `provides.${resource}.each "${id}" names no static block on this schema; it scopes nothing`,
+            );
+          }
+          const other = listedBy.get(id);
+          if (other) {
+            warn(
+              line,
+              `static block "${id}" is in both provides.${other}.each and provides.${resource}.each; a subtree takes one list, and the other's closest_* bindings show their literals`,
+            );
+          } else {
+            listedBy.set(id, resource);
+          }
+        }
+      }
+    }
+    return out;
+  },
 };
 
 /** `// theme-check-disable-next-line <rule>[, <rule>]: <reason>` in any
@@ -477,6 +551,7 @@ export function checkTheme({ themeRoot, release = false }) {
       ...f,
       file: path.relative(root, f.file).split(path.sep).join("/"),
       docs: `${SKILL}/${RULES[f.rule].docs}`,
+      ...(RULES[f.rule].warning && { warning: true }),
     }))
     .sort(
       (a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.rule.localeCompare(b.rule),
@@ -501,7 +576,7 @@ export function applyBaseline(findings, baseline) {
   return findings.filter(({ file, rule }) => counts[file][rule] > (baseline[file]?.[rule] ?? 0));
 }
 
-/** The CLI: prints findings, returns `false` when any is left. */
+/** The CLI: prints findings, returns `false` when any but a warning is left. */
 export function runThemeCheck({ themeRoot, argv = process.argv.slice(2) }) {
   const { values } = parseArgs({
     args: argv,
@@ -534,14 +609,16 @@ export function runThemeCheck({ themeRoot, argv = process.argv.slice(2) }) {
   const fresh = applyBaseline(findings, baseline);
   const known = findings.filter((f) => !fresh.includes(f));
   const baselined = known.length;
+  const problems = fresh.filter((f) => !f.warning).length;
+  const warnings = fresh.length - problems;
 
   if (values.json) {
     console.log(JSON.stringify({ findings: fresh, baselined }, null, 2));
-    return fresh.length === 0;
+    return problems === 0;
   }
   // styleText drops the color when stdout isn't a terminal or NO_COLOR is set.
   const print = (f, dim = false) => {
-    const line = `${styleText("cyan", `${f.file}:${f.line}`)} ${styleText("yellow", f.rule)} ${f.message}`;
+    const line = `${styleText("cyan", `${f.file}:${f.line}`)} ${styleText("yellow", f.rule)}${f.warning ? " (warning)" : ""} ${f.message}`;
     console.log(dim ? styleText("dim", line) : line);
   };
   for (const f of fresh) print(f);
@@ -559,9 +636,10 @@ export function runThemeCheck({ themeRoot, argv = process.argv.slice(2) }) {
       );
     }
   }
-  const summary = fresh.length
-    ? styleText(["red", "bold"], `✖ ${fresh.length} problem${fresh.length === 1 ? "" : "s"}`)
-    : styleText(["green", "bold"], "✓ no problems");
+  const warned = warnings ? `, ${warnings} warning${warnings === 1 ? "" : "s"}` : "";
+  const summary = problems
+    ? styleText(["red", "bold"], `✖ ${problems} problem${problems === 1 ? "" : "s"}${warned}`)
+    : styleText(["green", "bold"], `✓ no problems${warned}`);
   const knownNote = baselined
     ? styleText(
         "dim",
@@ -569,5 +647,5 @@ export function runThemeCheck({ themeRoot, argv = process.argv.slice(2) }) {
       )
     : "";
   console.log(`\n${summary}${knownNote}`);
-  return fresh.length === 0;
+  return problems === 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shop-on/theme-system",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "SEE LICENSE IN dist/LICENSE.md",
   "files": [
     "dist"
@@ -40,8 +40,8 @@
     }
   },
   "dependencies": {
-    "@shop-on/theme-contract": "0.5.0",
-    "@shop-on/theme-runtime": "0.5.0"
+    "@shop-on/theme-contract": "0.6.0",
+    "@shop-on/theme-runtime": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "26.6.5",