@canmi/seam-react 0.2.3 → 0.3.7

package/scripts/mock-generator.mjs

@@ -41,6 +41,11 @@ export function generateMockFromSchema(schema, fieldPath = "") {
     return generateMockFromSchema(inner, fieldPath);
   }
 
+  // HTML format: return sample HTML content instead of plain text
+  if (schema.type === "string" && schema.metadata?.format === "html") {
+    return "<p>Sample HTML content</p>";
+  }
+
   // Primitive type forms
   if (schema.type) {
     switch (schema.type) {
@@ -163,3 +168,307 @@ export function deepMerge(base, override) {
   }
   return result;
 }
+
+/**
+ * Recursively walk a JTD schema collecting dot-separated paths
+ * where metadata.format === "html".
+ * Returns a Set including both full paths and flattened paths
+ * (first segment stripped) to match flattenLoaderMock behavior.
+ * @param {object} schema - page-level JTD schema
+ * @returns {Set<string>}
+ */
+/**
+ * Walk JTD schema collecting all valid dot-separated field paths.
+ * Returns a Set including both keyed paths and flattened paths
+ * (first segment stripped) to match flattenLoaderMock behavior.
+ * @param {object} schema - page-level JTD schema
+ * @returns {Set<string>}
+ */
+export function collectSchemaPaths(schema) {
+  const paths = new Set();
+
+  function walk(node, prefix) {
+    if (!node || typeof node !== "object") return;
+
+    if (node.nullable) {
+      const inner = { ...node };
+      delete inner.nullable;
+      walk(inner, prefix);
+      return;
+    }
+
+    if (node.properties || node.optionalProperties) {
+      for (const [key, sub] of Object.entries({
+        ...node.properties,
+        ...node.optionalProperties,
+      })) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        paths.add(path);
+        walk(sub, path);
+      }
+      return;
+    }
+
+    if (node.elements) {
+      walk(node.elements, prefix ? `${prefix}.$` : "$");
+      return;
+    }
+  }
+
+  walk(schema, "");
+
+  // Add flattened paths (strip first segment) to match flattenLoaderMock.
+  // Snapshot before iterating because we mutate paths in the loop body.
+  const snapshot = Array.from(paths);
+  for (const p of snapshot) {
+    const dot = p.indexOf(".");
+    if (dot !== -1) paths.add(p.slice(dot + 1));
+  }
+  return paths;
+}
+
+/**
+ * Standard Levenshtein distance between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array.from({ length: n + 1 }, () => 0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Return the closest candidate within Levenshtein distance <= 3, or null.
+ * @param {string} name
+ * @param {Iterable<string>} candidates
+ * @returns {string | null}
+ */
+export function didYouMean(name, candidates) {
+  let best = null;
+  let bestDist = 4; // threshold: distance must be <= 3
+  for (const c of candidates) {
+    const d = levenshtein(name, c);
+    if (d < bestDist) {
+      bestDist = d;
+      best = c;
+    }
+  }
+  return best;
+}
+
+// Keys to ignore in Proxy tracking — React internals, framework hooks, and prototype methods
+const SKIP_KEYS = new Set([
+  "$$typeof",
+  "then",
+  "toJSON",
+  "constructor",
+  "valueOf",
+  "toString",
+  "hasOwnProperty",
+  "isPrototypeOf",
+  "propertyIsEnumerable",
+  "toLocaleString",
+  "__proto__",
+  "_owner",
+  "_store",
+  "ref",
+  "key",
+  "type",
+  "props",
+  "_self",
+  "_source",
+]);
+
+const ARRAY_METHODS = new Set([
+  "length",
+  "map",
+  "filter",
+  "forEach",
+  "find",
+  "findIndex",
+  "some",
+  "every",
+  "reduce",
+  "reduceRight",
+  "includes",
+  "indexOf",
+  "lastIndexOf",
+  "flat",
+  "flatMap",
+  "slice",
+  "concat",
+  "join",
+  "sort",
+  "reverse",
+  "entries",
+  "keys",
+  "values",
+  "at",
+  "fill",
+  "copyWithin",
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+]);
+
+/**
+ * Wrap an object with a Proxy that records all property access paths into `accessed`.
+ * Nested objects/arrays are recursively wrapped.
+ * @param {unknown} obj - object to wrap
+ * @param {Set<string>} accessed - set to record accessed paths
+ * @param {string} [prefix=""] - current dot-separated path prefix
+ * @returns {unknown}
+ */
+export function createAccessTracker(obj, accessed, prefix = "") {
+  if (obj === null || obj === undefined || typeof obj !== "object") return obj;
+
+  return new Proxy(obj, {
+    get(target, prop, receiver) {
+      // Skip symbols (React internals: Symbol.toPrimitive, Symbol.iterator, etc.)
+      if (typeof prop === "symbol") return Reflect.get(target, prop, receiver);
+
+      // Skip framework / prototype keys
+      if (SKIP_KEYS.has(prop)) return Reflect.get(target, prop, receiver);
+
+      const isArr = Array.isArray(target);
+
+      // Skip array methods but still wrap returned object values
+      if (isArr && ARRAY_METHODS.has(prop)) {
+        const val = Reflect.get(target, prop, receiver);
+        return val;
+      }
+
+      // Numeric index on array — record as prefix.$
+      if (isArr && /^\d+$/.test(prop)) {
+        const path = prefix ? `${prefix}.$` : "$";
+        accessed.add(path);
+        const val = target[prop];
+        if (val !== null && val !== undefined && typeof val === "object") {
+          return createAccessTracker(val, accessed, path);
+        }
+        return val;
+      }
+
+      const path = prefix ? `${prefix}.${prop}` : prop;
+      accessed.add(path);
+
+      const val = Reflect.get(target, prop, receiver);
+      if (val !== null && val !== undefined && typeof val === "object") {
+        return createAccessTracker(val, accessed, path);
+      }
+      return val;
+    },
+  });
+}
+
+/**
+ * Compare accessed property paths against schema-defined paths.
+ * Returns an array of warning strings for fields accessed but not in schema.
+ * @param {Set<string>} accessed - paths recorded by createAccessTracker
+ * @param {object | null} schema - page-level JTD schema
+ * @param {string} routePath - route path for warning messages
+ * @returns {string[]}
+ */
+export function checkFieldAccess(accessed, schema, routePath) {
+  if (!schema) return [];
+
+  const known = collectSchemaPaths(schema);
+  if (known.size === 0) return [];
+
+  const warnings = [];
+  // Collect leaf field names for did-you-mean suggestions
+  const leafNames = new Set();
+  for (const p of known) {
+    const dot = p.lastIndexOf(".");
+    leafNames.add(dot === -1 ? p : p.slice(dot + 1));
+  }
+
+  for (const path of accessed) {
+    if (known.has(path)) continue;
+
+    // Skip if it's a parent prefix of a known path (e.g. "user" when "user.name" exists)
+    let isParent = false;
+    for (const k of known) {
+      if (k.startsWith(path + ".")) {
+        isParent = true;
+        break;
+      }
+    }
+    if (isParent) continue;
+
+    const fieldName = path.includes(".") ? path.slice(path.lastIndexOf(".") + 1) : path;
+    const suggestion = didYouMean(fieldName, leafNames);
+
+    const knownList = [...leafNames].sort().join(", ");
+    let msg = `Route "${routePath}" component accessed data.${path},\n       but schema only defines: ${knownList}`;
+    if (suggestion) {
+      msg += `\n       Did you mean: ${suggestion}?`;
+    }
+    warnings.push(msg);
+  }
+
+  return warnings;
+}
+
+export function collectHtmlPaths(schema) {
+  const paths = new Set();
+
+  function walk(node, prefix) {
+    if (!node || typeof node !== "object") return;
+
+    if (node.nullable) {
+      const inner = { ...node };
+      delete inner.nullable;
+      walk(inner, prefix);
+      return;
+    }
+
+    if (node.type === "string" && node.metadata?.format === "html") {
+      paths.add(prefix);
+      return;
+    }
+
+    if (node.properties || node.optionalProperties) {
+      for (const [key, sub] of Object.entries(node.properties || {})) {
+        walk(sub, prefix ? `${prefix}.${key}` : key);
+      }
+      for (const [key, sub] of Object.entries(node.optionalProperties || {})) {
+        walk(sub, prefix ? `${prefix}.${key}` : key);
+      }
+      return;
+    }
+
+    if (node.elements) {
+      walk(node.elements, prefix ? `${prefix}.$` : "$");
+      return;
+    }
+  }
+
+  walk(schema, "");
+
+  // Add flattened paths (strip first segment) to match flattenLoaderMock
+  const flattened = new Set(paths);
+  for (const p of paths) {
+    const dot = p.indexOf(".");
+    if (dot !== -1) {
+      flattened.add(p.slice(dot + 1));
+    }
+  }
+
+  return flattened;
+}

package/scripts/skeleton/cache.mjs

@@ -0,0 +1,135 @@
+/* packages/client/react/scripts/skeleton/cache.mjs */
+
+import { build } from "esbuild";
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createI18n } from "@canmi/seam-i18n";
+
+/** Parse import statements to map local names to specifiers */
+function parseComponentImports(source) {
+  const map = new Map();
+  const re = /import\s+(?:(\w+)\s*,?\s*)?(?:\{([^}]*)\}\s*)?from\s+['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    const [, defaultName, namedPart, specifier] = m;
+    if (defaultName) map.set(defaultName, specifier);
+    if (namedPart) {
+      for (const part of namedPart.split(",")) {
+        const t = part.trim();
+        if (!t) continue;
+        const asMatch = t.match(/^(\w+)\s+as\s+(\w+)$/);
+        if (asMatch) {
+          map.set(asMatch[2], specifier);
+          map.set(asMatch[1], specifier);
+        } else {
+          map.set(t, specifier);
+        }
+      }
+    }
+  }
+  return map;
+}
+
+/** Bundle each component via esbuild (write: false) and SHA-256 hash the output */
+async function computeComponentHashes(names, importMap, routesDir) {
+  const hashes = new Map();
+  const seen = new Set();
+  const tasks = [];
+  for (const name of names) {
+    const specifier = importMap.get(name);
+    if (!specifier || seen.has(specifier)) continue;
+    seen.add(specifier);
+    tasks.push(
+      build({
+        stdin: { contents: `import '${specifier}'`, resolveDir: routesDir, loader: "js" },
+        bundle: true,
+        write: false,
+        format: "esm",
+        platform: "node",
+        treeShaking: false,
+        external: ["react", "react-dom", "@canmi/seam-react", "@canmi/seam-i18n"],
+        logLevel: "silent",
+      })
+        .then((result) => {
+          const content = result.outputFiles[0]?.text || "";
+          const hash = createHash("sha256").update(content).digest("hex");
+          for (const [n, s] of importMap) {
+            if (s === specifier) hashes.set(n, hash);
+          }
+        })
+        .catch(() => {}),
+    );
+  }
+  await Promise.all(tasks);
+  return hashes;
+}
+
+/**
+ * Hash the build scripts themselves to invalidate cache when tooling changes.
+ * @param {string[]} scriptFiles - absolute paths of script files to hash
+ */
+function computeScriptHash(scriptFiles) {
+  const h = createHash("sha256");
+  for (const f of scriptFiles) h.update(readFileSync(f, "utf-8"));
+  return h.digest("hex");
+}
+
+function pathToSlug(path) {
+  const t = path
+    .replace(/^\/|\/$/g, "")
+    .replace(/\//g, "-")
+    .replace(/:/g, "");
+  return t || "index";
+}
+
+function readCache(cacheDir, slug) {
+  try {
+    return JSON.parse(readFileSync(join(cacheDir, `${slug}.json`), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cacheDir, slug, key, data) {
+  writeFileSync(join(cacheDir, `${slug}.json`), JSON.stringify({ key, data }));
+}
+
+function computeCacheKey(componentHash, manifestContent, config, scriptHash, locale, messagesJson) {
+  const h = createHash("sha256");
+  h.update(componentHash);
+  h.update(manifestContent);
+  h.update(JSON.stringify(config));
+  h.update(scriptHash);
+  if (locale) h.update(locale);
+  if (messagesJson) h.update(messagesJson);
+  return h.digest("hex").slice(0, 16);
+}
+
+function buildI18nValue(locale, messages, defaultLocale) {
+  const localeMessages = messages?.[locale] || {};
+  const fallback =
+    defaultLocale && locale !== defaultLocale ? messages?.[defaultLocale] || {} : undefined;
+  const instance = createI18n(locale, localeMessages, fallback);
+  const usedKeys = new Set();
+  const origT = instance.t;
+  return {
+    locale: instance.locale,
+    t(key, params) {
+      usedKeys.add(key);
+      return origT(key, params);
+    },
+    _usedKeys: usedKeys,
+  };
+}
+
+export {
+  parseComponentImports,
+  computeComponentHashes,
+  computeScriptHash,
+  pathToSlug,
+  readCache,
+  writeCache,
+  computeCacheKey,
+  buildI18nValue,
+};

package/scripts/skeleton/layout.mjs

@@ -0,0 +1,109 @@
+/* packages/client/react/scripts/skeleton/layout.mjs */
+
+import { createElement } from "react";
+import { buildSentinelData } from "@canmi/seam-react";
+import {
+  generateMockFromSchema,
+  flattenLoaderMock,
+  deepMerge,
+  collectHtmlPaths,
+  createAccessTracker,
+  checkFieldAccess,
+} from "../mock-generator.mjs";
+import { guardedRender } from "./render.mjs";
+import { buildPageSchema } from "./schema.mjs";
+
+function toLayoutId(path) {
+  return path === "/"
+    ? "_layout_root"
+    : `_layout_${path.replace(/^\/|\/$/g, "").replace(/\//g, "-")}`;
+}
+
+/** Extract layout components and metadata from route tree */
+function extractLayouts(routes) {
+  const seen = new Map();
+  (function walk(defs, parentId) {
+    for (const def of defs) {
+      if (def.layout && def.children) {
+        const id = toLayoutId(def.path);
+        if (!seen.has(id)) {
+          seen.set(id, {
+            component: def.layout,
+            loaders: def.loaders || {},
+            mock: def.mock || null,
+            parentId: parentId || null,
+          });
+        }
+        walk(def.children, id);
+      }
+    }
+  })(routes, null);
+  return seen;
+}
+
+/**
+ * Resolve mock data for a layout: auto-generate from schema when loaders exist,
+ * then deep-merge any user-provided partial mock on top.
+ * Unlike resolveRouteMock, a layout with no loaders and no mock is valid (empty shell).
+ */
+function resolveLayoutMock(entry, manifest) {
+  if (Object.keys(entry.loaders).length > 0) {
+    const schema = buildPageSchema(entry, manifest);
+    if (schema) {
+      const keyedMock = generateMockFromSchema(schema);
+      const autoMock = flattenLoaderMock(keyedMock);
+      return entry.mock ? deepMerge(autoMock, entry.mock) : autoMock;
+    }
+  }
+  return entry.mock || {};
+}
+
+/**
+ * Render layout with seam-outlet placeholder, optionally with sentinel data.
+ * @param {{ buildWarnings: string[], seenWarnings: Set<string> }} ctx - shared warning state
+ */
+function renderLayout(LayoutComponent, id, entry, manifest, i18nValue, ctx) {
+  const mock = resolveLayoutMock(entry, manifest);
+  const schema =
+    Object.keys(entry.loaders || {}).length > 0 ? buildPageSchema(entry, manifest) : null;
+  const htmlPaths = schema ? collectHtmlPaths(schema) : new Set();
+  const data = Object.keys(mock).length > 0 ? buildSentinelData(mock, "", htmlPaths) : {};
+
+  // Wrap data with Proxy to detect schema/component field mismatches
+  const accessed = new Set();
+  const trackedData = Object.keys(data).length > 0 ? createAccessTracker(data, accessed) : data;
+
+  function LayoutWithOutlet() {
+    return createElement(LayoutComponent, null, createElement("seam-outlet", null));
+  }
+  const html = guardedRender(`layout:${id}`, LayoutWithOutlet, trackedData, i18nValue, ctx);
+
+  const fieldWarnings = checkFieldAccess(accessed, schema, `layout:${id}`);
+  for (const w of fieldWarnings) {
+    const msg = `[seam] warning: ${w}`;
+    if (!ctx.seenWarnings.has(msg)) {
+      ctx.seenWarnings.add(msg);
+      ctx.buildWarnings.push(msg);
+    }
+  }
+
+  return html;
+}
+
+/** Flatten routes, annotating each leaf with its parent layout id */
+function flattenRoutes(routes, currentLayout) {
+  const leaves = [];
+  for (const route of routes) {
+    if (route.layout && route.children) {
+      leaves.push(...flattenRoutes(route.children, toLayoutId(route.path)));
+    } else if (route.children) {
+      leaves.push(...flattenRoutes(route.children, currentLayout));
+    } else {
+      if (currentLayout) route._layoutId = currentLayout;
+      leaves.push(route);
+    }
+  }
+  return leaves;
+}
+
+export { toLayoutId, extractLayouts, resolveLayoutMock, renderLayout, flattenRoutes };