@lownoise-studio/rendershield 0.1.6 → 0.3.1

package/src/core/loadConfig.ts

@@ -1,74 +1,173 @@
-import fs from "fs-extra";
-import path from "node:path";
-import { RenderShieldConfig } from "../types.js";
-
-const CONFIG_NAME = "rendershield.config.json";
-
-type BoolFlag = { enabled: boolean };
-
-function isObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-function coerceBoolFlag(
-  parsed: any,
-  key: "sitemap" | "robots" | "worker",
-  defaultEnabled: boolean
-): BoolFlag {
-  // If missing, provide defaults (keeps older configs from exploding)
-  if (parsed?.[key] == null) return { enabled: defaultEnabled };
-
-  // If present, validate shape
-  const v = parsed[key];
-  if (!isObject(v)) {
-    throw new Error(`${key} must be an object like { "enabled": true }`);
-  }
-  if (typeof (v as any).enabled !== "boolean") {
-    throw new Error(`${key}.enabled must be a boolean`);
-  }
-  return { enabled: (v as any).enabled };
-}
-
-export async function loadConfig(
-  cwd = process.cwd()
-): Promise<RenderShieldConfig> {
-  const p = path.join(cwd, CONFIG_NAME);
-  const exists = await fs.pathExists(p);
-  if (!exists) {
-    throw new Error(`Missing ${CONFIG_NAME}. Run: rendershield init`);
-  }
-
-  const raw = await fs.readFile(p, "utf8");
-  let parsed: any;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new Error(`${CONFIG_NAME} is not valid JSON`);
-  }
-
-  // Minimal validation (v0)
-  if (parsed?.version !== 1) throw new Error(`Config version must be 1`);
-  if (!parsed?.site?.canonicalBase)
-    throw new Error(`site.canonicalBase is required`);
-  if (!parsed?.site?.siteName) throw new Error(`site.siteName is required`);
-  if (!parsed?.site?.defaultOgImage)
-    throw new Error(`site.defaultOgImage is required`);
-  if (!parsed?.site?.authorName)
-    throw new Error(`site.authorName is required`);
-  if (!parsed?.content?.markdown?.baseDir)
-    throw new Error(`content.markdown.baseDir is required`);
-  if (
-    !Array.isArray(parsed?.content?.markdown?.collections) ||
-    parsed.content.markdown.collections.length === 0
-  ) {
-    throw new Error(`content.markdown.collections must be a non-empty array`);
-  }
-  if (!parsed?.output?.outDir) throw new Error(`output.outDir is required`);
-
-  // Validate + default these optional sections to prevent TypeErrors later
-  parsed.sitemap = coerceBoolFlag(parsed, "sitemap", true);
-  parsed.robots = coerceBoolFlag(parsed, "robots", true);
-  parsed.worker = coerceBoolFlag(parsed, "worker", true);
-
-  return parsed as RenderShieldConfig;
-}
+import fs from "fs-extra";
+import path from "node:path";
+import { RenderShieldConfig } from "../types.js";
+
+const CONFIG_NAME = "rendershield.config.json";
+
+const DEFAULT_SITEMAP_PATH = "/sitemap.xml";
+const DEFAULT_ROBOTS_PATH = "/robots.txt";
+
+type BoolFlag = { enabled: boolean };
+
+/** Shape of config as read from JSON (before normalization). Used for validation only. */
+interface ParsedInput {
+  version?: unknown;
+  site?: { canonicalBase?: unknown; siteName?: unknown; defaultOgImage?: unknown; authorName?: unknown };
+  content?: { markdown?: { baseDir?: unknown; collections?: unknown[] } };
+  output?: { outDir?: unknown };
+  sitemap?: Record<string, unknown>;
+  robots?: Record<string, unknown>;
+  worker?: Record<string, unknown>;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function coerceBoolFlag(
+  parsed: Record<string, unknown>,
+  key: "sitemap" | "robots" | "worker",
+  defaultEnabled: boolean
+): BoolFlag {
+  // If missing, provide defaults (keeps older configs from exploding)
+  if (parsed?.[key] == null) return { enabled: defaultEnabled };
+
+  // If present, validate shape
+  const v = parsed[key];
+  if (!isObject(v)) {
+    throw new Error(`${key} must be an object like { "enabled": true }`);
+  }
+  const enabled = (v as Record<string, unknown>).enabled;
+  if (typeof enabled !== "boolean") {
+    throw new Error(`${key}.enabled must be a boolean`);
+  }
+  return { enabled };
+}
+
+/**
+ * Worker config policy: strict mode.
+ * When worker.enabled is true, all of lovableOrigin, rewriteRouteBases, and
+ * botUserAgentPatterns are required and must be non-empty. No defaults are
+ * supplied — build fails with a crisp error.
+ * lovableOrigin: must be http: or https: only (no file:, javascript:, protocol-relative).
+ * botUserAgentPatterns: substring match only (not regex); empty strings rejected to avoid overmatching.
+ */
+function validateWorkerWhenEnabled(parsed: Record<string, unknown>): void {
+  const worker = parsed.worker as Record<string, unknown> | undefined;
+  if (!worker?.lovableOrigin || typeof worker.lovableOrigin !== "string") {
+    throw new Error(
+      `worker.lovableOrigin is required when worker.enabled is true. Example: "https://your-site.lovable.app"`
+    );
+  }
+  let url: URL;
+  try {
+    url = new URL(worker.lovableOrigin);
+  } catch {
+    throw new Error(
+      `worker.lovableOrigin must be a valid URL. Got: "${worker.lovableOrigin}"`
+    );
+  }
+  const scheme = url.protocol.toLowerCase();
+  if (scheme !== "http:" && scheme !== "https:") {
+    throw new Error(
+      `worker.lovableOrigin must use http or https. Got: "${url.protocol}"`
+    );
+  }
+  if (
+    !Array.isArray(worker.rewriteRouteBases) ||
+    worker.rewriteRouteBases.length === 0
+  ) {
+    throw new Error(
+      `worker.rewriteRouteBases must be a non-empty array when worker.enabled is true. Example: ["/blog/"]`
+    );
+  }
+  if (
+    !Array.isArray(worker.botUserAgentPatterns) ||
+    worker.botUserAgentPatterns.length === 0
+  ) {
+    throw new Error(
+      `worker.botUserAgentPatterns must be a non-empty array when worker.enabled is true. Example: ["googlebot", "bingbot"]`
+    );
+  }
+  // Substring match only; empty string would match every User-Agent
+  for (let i = 0; i < worker.botUserAgentPatterns.length; i++) {
+    const p = worker.botUserAgentPatterns[i];
+    if (typeof p !== "string" || p.trim() === "") {
+      throw new Error(
+        `worker.botUserAgentPatterns[${i}] must be a non-empty string (substring match). Empty or invalid entry would overmatch.`
+      );
+    }
+  }
+}
+
+export async function loadConfig(
+  cwd = process.cwd()
+): Promise<RenderShieldConfig> {
+  const p = path.join(cwd, CONFIG_NAME);
+  const exists = await fs.pathExists(p);
+  if (!exists) {
+    throw new Error(`Missing ${CONFIG_NAME}. Run: rendershield init`);
+  }
+
+  const raw = await fs.readFile(p, "utf8");
+  let parsed: ParsedInput & Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw) as ParsedInput & Record<string, unknown>;
+  } catch {
+    throw new Error(`${CONFIG_NAME} is not valid JSON`);
+  }
+
+  // Minimal validation (v0)
+  if (parsed?.version !== 1) throw new Error(`Config version must be 1`);
+  if (!parsed?.site?.canonicalBase)
+    throw new Error(`site.canonicalBase is required`);
+  if (!parsed?.site?.siteName) throw new Error(`site.siteName is required`);
+  if (!parsed?.site?.defaultOgImage)
+    throw new Error(`site.defaultOgImage is required`);
+  if (!parsed?.site?.authorName)
+    throw new Error(`site.authorName is required`);
+  if (!parsed?.content?.markdown?.baseDir)
+    throw new Error(`content.markdown.baseDir is required`);
+  if (
+    !Array.isArray(parsed?.content?.markdown?.collections) ||
+    parsed.content.markdown.collections.length === 0
+  ) {
+    throw new Error(`content.markdown.collections must be a non-empty array`);
+  }
+  if (!parsed?.output?.outDir) throw new Error(`output.outDir is required`);
+
+  // Validate + default these optional sections (preserve path so it is not lost)
+  const sitemapFlag = coerceBoolFlag(parsed, "sitemap", true);
+  const sitemapObj = parsed.sitemap as Record<string, unknown> | undefined;
+  const sitemapPathVal = sitemapObj?.path;
+  const sitemapPath =
+    typeof sitemapPathVal === "string" && sitemapPathVal.trim().startsWith("/")
+      ? sitemapPathVal.trim()
+      : DEFAULT_SITEMAP_PATH;
+  parsed.sitemap = { enabled: sitemapFlag.enabled, path: sitemapPath };
+
+  const robotsFlag = coerceBoolFlag(parsed, "robots", true);
+  const robotsObj = parsed.robots as Record<string, unknown> | undefined;
+  const robotsPathVal = robotsObj?.path;
+  const robotsPath =
+    typeof robotsPathVal === "string" && robotsPathVal.trim().startsWith("/")
+      ? robotsPathVal.trim()
+      : DEFAULT_ROBOTS_PATH;
+  parsed.robots = { enabled: robotsFlag.enabled, path: robotsPath };
+
+  const workerFlag = coerceBoolFlag(parsed, "worker", true);
+  if (workerFlag.enabled) {
+    validateWorkerWhenEnabled(parsed);
+    // Keep parsed.worker as the full object from JSON (already validated)
+  } else {
+    parsed.worker = {
+      enabled: false,
+      lovableOrigin: "",
+      rewriteRouteBases: [],
+      botUserAgentPatterns: [],
+      debugHeaders: false,
+    };
+  }
+
+  return parsed as RenderShieldConfig;
+}

package/src/core/loadMarkdown.ts

@@ -9,7 +9,7 @@ const md = new MarkdownIt({ html: false, linkify: true, typographer: true });
 
 const REQUIRED_FIELDS = "title, excerpt, datePublished, coverImage, slug";
 
-function requireString(value: any, field: string, file: string): string {
+function requireString(value: unknown, field: string, file: string): string {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(
       `Missing required frontmatter field "${field}" in ${file}. Required fields: ${REQUIRED_FIELDS}`
@@ -18,7 +18,7 @@ function requireString(value: any, field: string, file: string): string {
   return value.trim();
 }
 
-function normalizeDate(value: any, file: string): string {
+function normalizeDate(value: unknown, file: string): string {
   if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
     return value;
   }

package/src/core/renderHtml.ts

@@ -57,7 +57,11 @@ export function renderPageHtml(cfg: RenderShieldConfig, doc: MarkdownDoc): strin
   <meta name="twitter:description" content="${escapeHtml(description)}">
   <meta name="twitter:image" content="${escapeHtml(ogImageUrl)}">
 
-  <script type="application/ld+json">${escapeHtml(JSON.stringify(jsonLd))}</script>
+  <script type="application/ld+json">${((): string => {
+    const raw = JSON.stringify(jsonLd);
+    // Case-insensitive: </script> and </SCRIPT> etc. must not break out of the tag
+    return raw.replace(/<\/script>/gi, "<\\/script>");
+  })()}</script>
 </head>
 <body>
   <main>

package/src/core/validateOutput.ts

@@ -1,9 +1,18 @@
-type ValidateParams = {
+export type ValidateParams = {
   html: string;
   outFile: string;
   routePath: string;
+  /** Source markdown file path; included in error context when provided */
+  sourcePath?: string;
+  /**
+   * Allowed JSON-LD @type values. Default allows Article, BlogPosting, WebPage.
+   * Add types (e.g. FAQPage, Organization) if your renderer emits them.
+   */
+  allowedJsonLdTypes?: string[];
 };
 
+const DEFAULT_ALLOWED_JSON_LD_TYPES = ["Article", "BlogPosting", "WebPage"];
+
 function hasNonEmptyTitle(html: string): boolean {
   const m = html.match(/<title>([\s\S]*?)<\/title>/i);
   if (!m) return false;
@@ -12,7 +21,6 @@ function hasNonEmptyTitle(html: string): boolean {
 }
 
 function getMetaContent(html: string, name: string): string | null {
-  // matches: <meta name="description" content="...">
   const re = new RegExp(
     `<meta\\s+[^>]*name=["']${escapeRegExp(name)}["'][^>]*>`,
     "i"
@@ -48,12 +56,126 @@ function getOgContent(html: string, property: string): string | null {
   return contentMatch?.[1]?.trim() ?? null;
 }
 
-function getJsonLd(html: string): string | null {
-  const m = html.match(
-    /<script\s+[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/i
+/** Returns all JSON-LD script tag contents (order preserved). Many pages emit multiple: WebPage, BreadcrumbList, Organization, etc. */
+function getAllJsonLdScripts(html: string): string[] {
+  const re = /<script\s+[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  const out: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html)) !== null) {
+    const content = (m[1] ?? "").trim();
+    if (content.length > 0) out.push(content);
+  }
+  return out;
+}
+
+/** Normalize @type: schema.org allows string or array of strings. Return array of lowercase types. */
+function normalizeJsonLdTypes(typeValue: unknown): string[] {
+  if (typeValue == null) return [];
+  if (typeof typeValue === "string") return [typeValue.toLowerCase().trim()].filter(Boolean);
+  if (Array.isArray(typeValue)) {
+    return typeValue
+      .filter((t) => typeof t === "string")
+      .map((t) => (t as string).toLowerCase().trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+/** Minimal shape for a JSON-LD node we validate (schema.org Article, BlogPosting, WebPage, etc.). */
+type JsonLdNode = Record<string, unknown>;
+
+/** Validate a single JSON-LD node (object). Returns true if it satisfies the contract. */
+function validateJsonLdNode(
+  node: JsonLdNode,
+  location: string,
+  allowedTypes: string[]
+): void {
+  const types = normalizeJsonLdTypes(node["@type"]);
+  if (types.length === 0) {
+    throw new Error(
+      `Invalid JSON-LD at ${location}: missing or invalid @type. Required (string or array of strings).`
+    );
+  }
+
+  const allowedSet = new Set(allowedTypes.map((t) => t.toLowerCase()));
+  const hasAllowedType = types.some((t) => allowedSet.has(t));
+  if (!hasAllowedType) {
+    throw new Error(
+      `Invalid JSON-LD at ${location}: @type "${String(node["@type"])}" is not in allowed list [${allowedTypes.join(", ")}]. Add it to allowedJsonLdTypes if your page uses this type.`
+    );
+  }
+
+  const primaryType = types[0];
+  const missing: string[] = [];
+  if (!node["@context"]) missing.push("@context");
+  if (!node["@type"]) missing.push("@type");
+  if (!node.headline && !node.name) missing.push("headline or name");
+  const articleLike = ["article", "blogposting"];
+  if (articleLike.includes(primaryType) && !node.datePublished) {
+    missing.push("datePublished");
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Invalid JSON-LD at ${location}: missing required fields: ${missing.join(", ")}.`
+    );
+  }
+
+  if (node.datePublished && typeof node.datePublished === "string") {
+    const dateMatch = node.datePublished.match(/^\d{4}-\d{2}-\d{2}/);
+    if (!dateMatch) {
+      throw new Error(
+        `Invalid JSON-LD at ${location}: datePublished must be YYYY-MM-DD or ISO 8601. Got: "${node.datePublished}"`
+      );
+    }
+  }
+}
+
+/**
+ * Validates JSON-LD: valid JSON, @type in allowed list, required fields.
+ * Accepts single object or array of objects (at least one item must satisfy the contract).
+ * @type may be string or array of strings (e.g. ["Article","NewsArticle"]).
+ */
+function validateJsonLdSchema(
+  jsonLd: string,
+  context: { routePath: string; sourcePath?: string },
+  allowedTypes: string[]
+): void {
+  const { routePath, sourcePath } = context;
+  const location = sourcePath ? `route ${routePath} (source: ${sourcePath})` : `route ${routePath}`;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(jsonLd);
+  } catch {
+    const preview = jsonLd.length > 200 ? jsonLd.slice(0, 200) + "…" : jsonLd;
+    throw new Error(
+      `Invalid JSON-LD at ${location}: JSON parse error. Ensure the script tag contains valid JSON. Preview: ${preview}`
+    );
+  }
+
+  const items: unknown[] = Array.isArray(parsed) ? parsed : [parsed];
+  if (items.length === 0) {
+    throw new Error(
+      `Invalid JSON-LD at ${location}: empty array or missing object.`
+    );
+  }
+
+  let lastErr: Error | null = null;
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    if (typeof item !== "object" || item === null || Array.isArray(item)) continue;
+    try {
+      validateJsonLdNode(item as JsonLdNode, location, allowedTypes);
+      return;
+    } catch (e) {
+      lastErr = e instanceof Error ? e : new Error(String(e));
+    }
+  }
+  if (lastErr) throw lastErr;
+  throw new Error(
+    `Invalid JSON-LD at ${location}: no item in the array satisfies the required type contract (allowed: [${allowedTypes.join(", ")}]).`
   );
-  if (!m) return null;
-  return (m[1] ?? "").trim();
 }
 
 function getArticleInnerHtml(html: string): string | null {
@@ -80,69 +202,127 @@ function escapeRegExp(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+function formatErrorContext(params: ValidateParams): string {
+  const lines: string[] = [];
+  lines.push(`- routePath: ${params.routePath}`);
+  lines.push(`- outFile: ${params.outFile}`);
+  if (params.sourcePath) {
+    lines.push(`- sourcePath: ${params.sourcePath}`);
+  }
+  return lines.join("\n");
+}
+
+export type ContractCheckResult = {
+  ok: boolean;
+  missing: string[];
+};
+
+/**
+ * Runs the same contract checks as validatePrerenderHtml but returns a result instead of throwing.
+ * Used by verify --prod to report whether production HTML satisfies the bot contract.
+ */
+export function checkPrerenderContract(
+  html: string,
+  options: {
+    routePath?: string;
+    outFile?: string;
+    sourcePath?: string;
+    allowedJsonLdTypes?: string[];
+  } = {}
+): ContractCheckResult {
+  const routePath = options.routePath ?? "(production)";
+  const allowedJsonLdTypes = options.allowedJsonLdTypes ?? DEFAULT_ALLOWED_JSON_LD_TYPES;
+  const missing = collectContractMissing(html, routePath, options.sourcePath, allowedJsonLdTypes);
+  return { ok: missing.length === 0, missing };
+}
+
 export function validatePrerenderHtml(params: ValidateParams): void {
-  const { html, outFile, routePath } = params;
+  const {
+    html,
+    routePath,
+    sourcePath,
+    allowedJsonLdTypes = DEFAULT_ALLOWED_JSON_LD_TYPES,
+  } = params;
+
+  const missing = collectContractMissing(html, routePath, sourcePath, allowedJsonLdTypes);
+
+  if (missing.length > 0) {
+    const context = formatErrorContext(params);
+    const msg =
+      `RenderShield validation failed for prerendered page:\n` +
+      context +
+      `\nMissing/invalid requirements:\n` +
+      missing.map((m) => `- ${m}`).join("\n") +
+      `\n\nFix the source content or renderer so bots receive complete HTML. Check frontmatter and template (title, excerpt, datePublished, coverImage, slug).`;
+
+    throw new Error(msg);
+  }
+}
 
+/** Shared contract checks; returns missing list. validatePrerenderHtml throws when missing.length > 0. */
+function collectContractMissing(
+  html: string,
+  routePath: string,
+  sourcePath: string | undefined,
+  allowedJsonLdTypes: string[]
+): string[] {
   const missing: string[] = [];
 
-  // 1) Title
   if (!hasNonEmptyTitle(html)) missing.push("Missing or empty <title>");
-
-  // 2) Meta description
   const desc = getMetaContent(html, "description");
   if (!desc) missing.push('Missing <meta name="description" content="...">');
-
-  // 3) Canonical
   const canonical = getLinkHref(html, "canonical");
   if (!canonical) missing.push('Missing <link rel="canonical" href="...">');
 
-  // 4) Open Graph tags
   const ogTitle = getOgContent(html, "og:title");
   const ogDesc = getOgContent(html, "og:description");
   const ogImg = getOgContent(html, "og:image");
   const ogUrl = getOgContent(html, "og:url");
-
   if (!ogTitle) missing.push("Missing Open Graph tag: og:title");
-  if (!ogDesc) missing.push("Missing Open Graph tag: og:description");
+  if (!ogDesc) {
+    missing.push("Missing Open Graph tag: og:description");
+  } else if (ogDesc.length > 200) {
+    missing.push(`Open Graph description too long (${ogDesc.length} chars). Max 200.`);
+  }
   if (!ogImg) missing.push("Missing Open Graph tag: og:image");
   if (!ogUrl) missing.push("Missing Open Graph tag: og:url");
 
-  // 5) JSON-LD
-  const jsonLd = getJsonLd(html);
-  if (!jsonLd) {
+  const jsonLdScripts = getAllJsonLdScripts(html);
+  if (jsonLdScripts.length === 0) {
     missing.push('Missing JSON-LD: <script type="application/ld+json">...</script>');
-  } else if (jsonLd.length <= 20) {
-    missing.push("JSON-LD script present but too short/empty");
+  } else {
+    let onePassed = false;
+    for (const scriptContent of jsonLdScripts) {
+      if (scriptContent.length <= 20) continue;
+      try {
+        validateJsonLdSchema(
+          scriptContent,
+          { routePath, sourcePath },
+          allowedJsonLdTypes
+        );
+        onePassed = true;
+        break;
+      } catch {
+        // continue to next script
+      }
+    }
+    if (!onePassed) missing.push("No JSON-LD script satisfied the required type contract.");
   }
 
-  // 6) Article content
   const articleInner = getArticleInnerHtml(html);
   if (!articleInner) {
     missing.push("Missing <article>...</article>");
   } else {
     const text = stripTags(articleInner);
     const words = wordCount(text);
-
-    // Require either enough characters or enough words
     const okByChars = text.length >= 80;
     const okByWords = words >= 20;
-
     if (!okByChars && !okByWords) {
       missing.push(
-        `Article content too short (got ${words} words, ${text.length} chars). Require >= 20 words or >= 80 chars.`
+        `Article content too short (${words} words, ${text.length} chars). Require >= 20 words or >= 80 chars.`
       );
     }
   }
 
-  if (missing.length > 0) {
-    const msg =
-      `RenderShield validation failed for prerendered page:\n` +
-      `- routePath: ${routePath}\n` +
-      `- outFile: ${outFile}\n` +
-      `Missing/invalid requirements:\n` +
-      missing.map((m) => `- ${m}`).join("\n") +
-      `\n\nFix the source content or renderer so bots receive complete HTML.`;
-
-    throw new Error(msg);
-  }
+  return missing;
 }