@tokenoftrust/cli 1.0.0

package/src/validate.mjs

@@ -0,0 +1,291 @@
+/**
+ * Tenant-contract validation CORE — the pure, I/O-light checks `tot validate`
+ * runs before you commit/submit, so the classes of defect that otherwise fail
+ * silently (or as a cryptic reconcile/build error) are caught locally.
+ *
+ * Design principle — "valid locally ≡ will reconcile in storefront": these checks
+ * mirror the reconcile pipeline's own gate (@tot/private-controlplane
+ * customization-reconcile.ts `mapToArtifact` / `validateRawHtml`). Kept in step
+ * with the in-repo source of truth `scripts/tenant/validate.mjs` (which the CI
+ * regression test imports). FOLLOW-UP: collapse the two onto this module as the
+ * single source once the package is the install surface.
+ *
+ * Pure + dependency-free (readFileSync only). `validateTenant(dir)` is the entry
+ * point; `validateConfigShape` is exported for focused testing.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const NUL = String.fromCharCode(0);
+export const ERROR = "error";
+export const WARN = "warn";
+
+/** @typedef {{level:string, rule:string, file:string, message:string, fix?:string}} Finding */
+function mk(level, rule, file, message, fix) {
+  return { level, rule, file, message, fix };
+}
+
+// --- canonical `.tot/config.json` shape (the #24/#25 regression guard) --------
+const KNOWN_KINDS = new Set(["file", "tree"]);
+const REQUIRED_WORKSPACES = ["content/", "public/", "theme.json"];
+
+/**
+ * Validate a parsed `.tot/config.json` against the shape the reconcile pipeline
+ * (`mapToArtifact`) requires. Pure — no I/O.
+ * @returns {Finding[]}
+ */
+export function validateConfigShape(config, file = ".tot/config.json") {
+  const out = [];
+  if (config == null || typeof config !== "object") {
+    return [mk(ERROR, "config-parse", file, "config is not a JSON object")];
+  }
+  if (typeof config.tenant !== "string" || !config.tenant) {
+    out.push(mk(ERROR, "config-tenant", file, "`tenant` must be a non-empty string"));
+  }
+  if (!Array.isArray(config.mappings)) {
+    out.push(mk(ERROR, "config-mappings", file, "`mappings` must be an array", "seed shape: [{workspace,repo,kind}]"));
+    return out;
+  }
+  const seen = new Set();
+  for (const [i, m] of config.mappings.entries()) {
+    const at = `${file} mappings[${i}]`;
+    if (m == null || typeof m !== "object") {
+      out.push(mk(ERROR, "mapping-shape", at, "mapping must be an object"));
+      continue;
+    }
+    if (typeof m.workspace !== "string" || !m.workspace) {
+      out.push(mk(ERROR, "mapping-workspace", at, "`workspace` must be a non-empty string"));
+    } else {
+      seen.add(m.workspace.replace(/\/+$/, "") + (m.kind === "tree" ? "/" : ""));
+      seen.add(m.workspace);
+    }
+    // THE regression guard: reconcile's mapToArtifact dereferences m.repo and only
+    // knows "file" vs tree — a missing repo or kind:"dir" makes it throw at runtime.
+    if (typeof m.repo !== "string" || !m.repo) {
+      out.push(
+        mk(ERROR, "mapping-repo", at,
+          `mapping for "${m.workspace ?? "?"}" is missing a string \`repo\` (reconcile mapToArtifact throws on undefined.repo)`,
+          `add "repo": "tenants/${config.tenant ?? "<id>"}/${(m.workspace ?? "").replace(/\/+$/, "")}${m.kind === "file" ? "" : "/"}"`),
+      );
+    }
+    if (!KNOWN_KINDS.has(m.kind)) {
+      out.push(
+        mk(ERROR, "mapping-kind", at,
+          `\`kind\` is "${m.kind}" — must be "file" or "tree" (legacy "dir" is the #24/#25 bug)`,
+          m.kind === "dir" ? 'change "dir" → "tree"' : 'set "file" for a single file, "tree" for a directory'),
+      );
+    }
+  }
+  for (const req of REQUIRED_WORKSPACES) {
+    const bare = req.replace(/\/+$/, "");
+    if (!seen.has(req) && !seen.has(bare)) {
+      out.push(mk(WARN, "config-coverage", file, `mappings do not cover "${req}" — edits there won't flow back`));
+    }
+  }
+  return out;
+}
+
+// --- tiny HTML checks (mirror customization-reconcile.ts validateRawHtml) ------
+function isFullDocument(html) {
+  const head = html.slice(0, 512).toLowerCase();
+  return head.includes("<!doctype") || head.includes("<html");
+}
+function validateRawHtmlBody(html) {
+  if (typeof html !== "string" || html.length === 0) return "empty document";
+  if (html.includes(NUL)) return "contains NUL byte (not text/HTML)";
+  if (!html.includes("<")) return "no markup tags found";
+  return null;
+}
+
+// --- filesystem helpers ------------------------------------------------------
+function readJsonSafe(path) {
+  try {
+    return { value: JSON.parse(readFileSync(path, "utf8")), error: null };
+  } catch (e) {
+    return { value: null, error: /** @type {Error} */ (e).message };
+  }
+}
+function walk(dir, pred) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) out.push(...walk(p, pred));
+    else if (pred(p)) out.push(p);
+  }
+  return out;
+}
+
+// --- link / asset extraction -------------------------------------------------
+const HREF_RE = /\bhref\s*=\s*"([^"]*)"/gi;
+const SRC_RE = /\b(?:src|srcset)\s*=\s*"([^"]*)"/gi;
+const STYLE_OPEN_WITH_ATTRS_RE = /<style\s+[^>]*>/i;
+
+/**
+ * Full static validation of a tenant directory (content/ public/ theme.json [.tot/]).
+ * @param {string} tenantDir absolute path to the tenant dir
+ * @param {{tenantId?:string, scope?:string}} [opts]
+ * @returns {{ok:boolean, findings:Finding[]}}
+ */
+export function validateTenant(tenantDir, opts = {}) {
+  /** @type {Finding[]} */
+  const findings = [];
+  const rel = (p) => relative(tenantDir, p) || p;
+  const contentDir = join(tenantDir, "content");
+  const publicDir = join(tenantDir, "public");
+  const pagesDir = join(contentDir, "pages-html");
+
+  // 0. basic layout
+  if (!existsSync(contentDir)) {
+    findings.push(mk(ERROR, "layout", "content/", "no content/ directory"));
+  }
+
+  // 1. .tot/config.json — shape (flow-back readiness)
+  const configPath = join(tenantDir, ".tot", "config.json");
+  let config = null;
+  if (existsSync(configPath)) {
+    const { value, error } = readJsonSafe(configPath);
+    if (error) {
+      findings.push(mk(ERROR, "config-parse", ".tot/config.json", `invalid JSON: ${error}`));
+    } else {
+      config = value;
+      findings.push(...validateConfigShape(value, ".tot/config.json"));
+    }
+  } else {
+    findings.push(
+      mk(WARN, "config-absent", ".tot/config.json",
+        "no .tot/config.json — tenant can serve but is NOT flow-back-ready (reconcile has nothing to map)"),
+    );
+  }
+  const scope = opts.scope || config?.scope;
+
+  // 2. theme.json — parse (a malformed one is a WHOLE-APP BUILD FAILURE)
+  const themePath = join(tenantDir, "theme.json");
+  if (existsSync(themePath)) {
+    const { error } = readJsonSafe(themePath);
+    if (error) {
+      findings.push(
+        mk(ERROR, "theme-parse", "theme.json",
+          `invalid JSON: ${error}`, "theme.json is loaded by an eager Vite glob — a parse error fails the entire storefront build"),
+      );
+    }
+  }
+
+  // 3. content JSON — parse + blocks shape
+  for (const name of ["home.json", "chrome.json"]) {
+    const p = join(contentDir, name);
+    if (existsSync(p)) {
+      const { value, error } = readJsonSafe(p);
+      if (error) {
+        findings.push(mk(ERROR, "content-json-parse", `content/${name}`, `invalid JSON: ${error} (fails the build)`));
+      } else if (name === "home.json" && value && "blocks" in value && !Array.isArray(value.blocks)) {
+        findings.push(mk(ERROR, "home-blocks", "content/home.json", "`blocks` must be an array (index.astro throws otherwise)"));
+      }
+    }
+  }
+
+  // 4. raw HTML documents — validate + portability + resolution
+  const chromePath = join(contentDir, "chrome.html");
+  const hasChrome = existsSync(chromePath);
+  const htmlFiles = walk(contentDir, (p) => p.endsWith(".html"));
+  const pageTargets = buildPageTargetSet(contentDir, pagesDir);
+
+  for (const p of htmlFiles) {
+    const r = rel(p);
+    const html = readFileSync(p, "utf8");
+    const base = r === "content/chrome.html";
+
+    const bad = validateRawHtmlBody(html);
+    if (bad) {
+      findings.push(mk(ERROR, "html-invalid", r, `not a servable document: ${bad}`));
+      continue;
+    }
+    if (!base && !isFullDocument(html) && !hasChrome) {
+      findings.push(
+        mk(ERROR, "html-fragment", r,
+          "is an HTML fragment but the tenant ships no content/chrome.html to wrap it — it will serve unwrapped/naked",
+          "make it a full <!doctype html> document, or add content/chrome.html with <!--PAGE_BODY-->"),
+      );
+    }
+    if (STYLE_OPEN_WITH_ATTRS_RE.test(html)) {
+      findings.push(
+        mk(WARN, "style-attrs", r,
+          "has an inline <style …> with attributes — the CSP nonce injector only matches a bare <style>, so this CSS is dropped when served",
+          "use a bare <style> tag"),
+      );
+    }
+
+    for (const m of html.matchAll(HREF_RE)) {
+      findings.push(...checkLink(m[1].trim(), r, scope, pageTargets));
+    }
+    for (const m of html.matchAll(SRC_RE)) {
+      const f = checkAsset(m[1].trim(), r, publicDir, opts.tenantId || config?.tenant);
+      if (f) findings.push(f);
+    }
+  }
+
+  const ok = !findings.some((f) => f.level === ERROR);
+  return { ok, findings };
+}
+
+function buildPageTargetSet(contentDir, pagesDir) {
+  const set = new Set(["/", ""]);
+  if (existsSync(join(contentDir, "home.html"))) set.add("/");
+  for (const p of walk(pagesDir, (x) => x.endsWith(".html"))) {
+    const relPath = relative(pagesDir, p).replace(/\.html$/, "");
+    const slug = relPath === "index" ? "" : relPath;
+    set.add(`/${slug}/`.replace(/\/+/g, "/"));
+    set.add(`/${slug}`.replace(/\/+$/, "") || "/");
+  }
+  return set;
+}
+
+function checkLink(href, file, scope, pageTargets) {
+  const out = [];
+  if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) return out;
+  if (/^https?:\/\/localhost(?::\d+)?/i.test(href)) {
+    out.push(mk(ERROR, "link-localhost", file, `links to a localhost URL: ${href}`, "use a root-absolute path (/foo/)"));
+    return out;
+  }
+  if (scope && new RegExp(`^https?://(www\\.)?${escapeRe(scope)}(/|$)`, "i").test(href)) {
+    const path = href.replace(/^https?:\/\/(www\.)?[^/]+/i, "") || "/";
+    out.push(
+      mk(ERROR, "link-nonportable", file,
+        `internal CTA is hardcoded to https://${scope}${path} — it leaves localhost/preview when served`,
+        `use the root-absolute form: ${path}`),
+    );
+    return out;
+  }
+  if (/^([a-z]+:)?\/\//i.test(href)) return out;
+  if (href.startsWith("/")) {
+    if (href.startsWith("/tenants/")) return out;
+    const path = href.split(/[?#]/)[0];
+    const norm = path.replace(/\/+$/, "") || "/";
+    if (!pageTargets.has(path) && !pageTargets.has(norm) && !pageTargets.has(norm + "/")) {
+      out.push(mk(WARN, "link-dangling", file, `internal link ${path} does not resolve to a known page (would 404)`));
+    }
+    return out;
+  }
+  out.push(mk(WARN, "link-relative", file, `relative link "${href}" — internal links should be root-absolute (/foo/)`));
+  return out;
+}
+
+function checkAsset(src, file, publicDir, tenantId) {
+  if (!src || /^([a-z]+:)?\/\//i.test(src) || src.startsWith("data:")) return null;
+  let relPath = null;
+  if (tenantId && src.startsWith(`/tenants/${tenantId}/`)) {
+    relPath = src.slice(`/tenants/${tenantId}/`.length).split(/[?#]/)[0];
+  } else if (src.startsWith("/")) {
+    return null;
+  } else {
+    relPath = src.split(/[?#]/)[0];
+  }
+  if (!relPath) return null;
+  if (!existsSync(join(publicDir, relPath))) {
+    return mk(WARN, "asset-missing", file, `references public asset "${src}" which is not present under public/`);
+  }
+  return null;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");