@sonordev/contracts 2.2.0 → 2.4.0

package/dist/schema-placeholders.mjs

@@ -0,0 +1,317 @@
+// src/contracts/schema-placeholders.ts
+var RESERVED_EXAMPLE_DOMAINS = ["example.com", "example.net", "example.org"];
+var RESERVED_EXAMPLE_TLD = "example";
+var PLACEHOLDER_NAMES = /* @__PURE__ */ new Set([
+  "example",
+  "example business",
+  "example company",
+  "example organization",
+  "your business",
+  "your business name",
+  "your company",
+  "your company name",
+  "your organization",
+  "your organization name",
+  "business name",
+  "company name",
+  "organization name",
+  "your name",
+  "lorem ipsum"
+]);
+var NAME_KEYS = /* @__PURE__ */ new Set([
+  "name",
+  "legalName",
+  "alternateName",
+  "author",
+  "creator",
+  "publisher",
+  "brand",
+  "provider",
+  "seller",
+  "manufacturer",
+  "organizer",
+  "founder"
+]);
+var PHONE_KEYS = /* @__PURE__ */ new Set(["telephone", "faxNumber"]);
+var URI_TEMPLATE_KEYS = /* @__PURE__ */ new Set(["target", "urlTemplate"]);
+var BODY_TEXT_KEYS = /* @__PURE__ */ new Set(["articleBody"]);
+var ANNOTATION_KEYS = /* @__PURE__ */ new Set(["note", "notes", "_note", "_notes", "_comment", "_comments", "__comment", "$comment"]);
+var STRUCTURAL_KEYS = /* @__PURE__ */ new Set(["@context", "@type", "@id", "position"]);
+var MUSTACHE_SLOT = /\{\{\s*[#^/>&]?\s*[A-Za-z_$][\w$.[\]-]*\s*\}\}/;
+var JSX_EXPRESSION_VALUE = /^\{\s*[A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*|\[[^\]]*\])+[^{}]*\}$/;
+var JSX_MEMBER_IN_TEXT = /\{\s*[A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*)+\s*\}/;
+var BRACKET_SLOT_VALUE = /^\[\s*[A-Za-z][^[\]"{}<>]{0,80}\]$/;
+var BRACKET_SLOT_IN_TEXT = /\[\s*((?:your|insert your|enter your|add your)\s+[^[\]]{1,60}?|(?:(?:business|company|organization|brand|full|first|last|resident|client|customer|author)\s+)?(?:name|phone(?:\s+number)?|telephone|email(?:\s+address)?|(?:street\s+)?address|city|state|zip(?:\s+code)?|postal\s+code|website|url|logo|date))\s*\](?!\()/gi;
+var REPLACE_MARKER = /\bREPLACE(?:_WITH_\w*|_ME\b)/;
+var UPPER_SLOT_VALUE = /^YOUR_[A-Z0-9_]+$/;
+var MAX_DEPTH = 40;
+var MAX_EVIDENCE = 5;
+var EVIDENCE_VALUE_LENGTH = 120;
+function withoutSchemaPlaceholders(value) {
+  const state = { dropped: [], notes: [] };
+  if (value === null || value === void 0) return { value: null, ...state };
+  const result = visitRoot(value, state);
+  return { value: result, ...state };
+}
+function findSchemaPlaceholders(value) {
+  return withoutSchemaPlaceholders(value).dropped;
+}
+var REASON_TEXT = {
+  example_domain: "is on a reserved example domain",
+  placeholder_phone: "is a placeholder phone number",
+  placeholder_name: "is a placeholder name",
+  template_token: "is an unfilled template slot",
+  annotation: "is an AI note, not schema",
+  emptied: "held only placeholders"
+};
+function describeSchemaPlaceholder(node) {
+  const where = `${node.type || "Node"} at ${node.path}`;
+  const first = node.evidence[0];
+  const detail = first ? `${first.key} ${JSON.stringify(first.value)} ${REASON_TEXT[first.reason]}` : REASON_TEXT[node.reasons[0]];
+  return node.reasons.includes("emptied") ? `${where} has nothing real left: ${detail}` : `${where}: ${detail}`;
+}
+function visitRoot(value, state) {
+  if (Array.isArray(value)) {
+    const out = visitArray(value, "$", state, 0, true);
+    return out.removed && out.value.length === 0 ? null : out.value;
+  }
+  if (!isPlainObject(value)) return value;
+  if (isGraphWrapper(value)) {
+    const out = visitContainer(value, "$", state, 0);
+    return out.removedChild && !hasContentBeyond(out.value, /* @__PURE__ */ new Set(["@context"])) ? null : out.value;
+  }
+  const visit = visitNode(value, "$", state, 0);
+  return visit.keep ? visit.value : null;
+}
+function visitNode(node, path, state, depth) {
+  if (isAnnotationOnly(node)) {
+    state.dropped.push({ path, type: null, reasons: ["annotation"], evidence: annotationEvidence(node) });
+    return { keep: false };
+  }
+  const evidence = [];
+  collectEvidence(node, evidence, depth);
+  if (evidence.length) {
+    state.dropped.push({ path, type: typeOf(node), reasons: unique(evidence.map((e) => e.reason)), evidence });
+    return { keep: false };
+  }
+  const droppedMark = state.dropped.length;
+  const notesMark = state.notes.length;
+  const pruned = visitContainer(node, path, state, depth);
+  if (pruned.removedChild && !hasContentBeyond(pruned.value, STRUCTURAL_KEYS)) {
+    const children = state.dropped.splice(droppedMark);
+    state.notes.length = notesMark;
+    state.dropped.push({
+      path,
+      type: typeOf(node),
+      reasons: unique(["emptied", ...children.flatMap((c) => c.reasons)]),
+      evidence: children.flatMap((c) => c.evidence).slice(0, MAX_EVIDENCE)
+    });
+    return { keep: false };
+  }
+  return { keep: true, value: pruned.value };
+}
+function visitContainer(obj, path, state, depth) {
+  if (depth >= MAX_DEPTH) return { value: obj, removedChild: false };
+  let changed = false;
+  let removedChild = false;
+  const out = {};
+  for (const [key, child] of Object.entries(obj)) {
+    if (key === "@context") {
+      out[key] = child;
+      continue;
+    }
+    if (ANNOTATION_KEYS.has(key)) {
+      state.notes.push({ path, key });
+      changed = true;
+      continue;
+    }
+    const childPath = stepKey(path, key);
+    if (Array.isArray(child)) {
+      const pruned = visitArray(child, childPath, state, depth + 1, key === "@graph");
+      if (pruned.removed) removedChild = true;
+      if (pruned.value !== child) changed = true;
+      if (pruned.removed && pruned.value.length === 0) continue;
+      out[key] = pruned.value;
+      continue;
+    }
+    if (isPlainObject(child)) {
+      if (isNestedNode(child)) {
+        const visit = visitNode(child, childPath, state, depth + 1);
+        if (!visit.keep) {
+          changed = true;
+          removedChild = true;
+          continue;
+        }
+        if (visit.value !== child) changed = true;
+        out[key] = visit.value;
+        continue;
+      }
+      const pruned = visitContainer(child, childPath, state, depth + 1);
+      if (pruned.removedChild) removedChild = true;
+      if (pruned.value !== child) changed = true;
+      out[key] = pruned.value;
+      continue;
+    }
+    out[key] = child;
+  }
+  return { value: changed ? out : obj, removedChild };
+}
+function visitArray(items, path, state, depth, units) {
+  if (depth >= MAX_DEPTH) return { value: items, removed: false };
+  let changed = false;
+  let removed = false;
+  const out = [];
+  items.forEach((item, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (Array.isArray(item)) {
+      const pruned = visitArray(item, itemPath, state, depth + 1, units);
+      if (pruned.removed) removed = true;
+      if (pruned.value !== item) changed = true;
+      out.push(pruned.value);
+      return;
+    }
+    if (isPlainObject(item) && (units || isNestedNode(item))) {
+      const visit = visitNode(item, itemPath, state, depth + 1);
+      if (!visit.keep) {
+        changed = true;
+        removed = true;
+        return;
+      }
+      if (visit.value !== item) changed = true;
+      out.push(visit.value);
+      return;
+    }
+    if (isPlainObject(item)) {
+      const pruned = visitContainer(item, itemPath, state, depth + 1);
+      if (pruned.removedChild) removed = true;
+      if (pruned.value !== item) changed = true;
+      out.push(pruned.value);
+      return;
+    }
+    out.push(item);
+  });
+  return { value: changed ? out : items, removed };
+}
+function collectEvidence(holder, out, depth) {
+  for (const [key, value] of Object.entries(holder)) {
+    if (key === "@context" || ANNOTATION_KEYS.has(key)) continue;
+    collectFromValue(holder, key, value, out, depth);
+  }
+}
+function collectFromValue(holder, key, value, out, depth) {
+  if (depth >= MAX_DEPTH || out.length >= MAX_EVIDENCE) return;
+  if (typeof value === "string") {
+    for (const reason of placeholderReasons(key, value, holder)) {
+      if (out.length >= MAX_EVIDENCE) return;
+      out.push({ reason, key, value: cutForLog(value) });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectFromValue(holder, key, item, out, depth + 1);
+    return;
+  }
+  if (isPlainObject(value) && !isNestedNode(value)) collectEvidence(value, out, depth + 1);
+}
+function placeholderReasons(key, raw, holder) {
+  const value = raw.trim();
+  if (!value) return [];
+  const reasons = [];
+  const host = urlHost(value);
+  if (host && isReservedExampleHost(host)) reasons.push("example_domain");
+  if ((PHONE_KEYS.has(key) || /^tel:/i.test(value)) && isPlaceholderPhone(value)) reasons.push("placeholder_phone");
+  if (NAME_KEYS.has(key) && !("value" in holder) && PLACEHOLDER_NAMES.has(normalizeName(value))) {
+    reasons.push("placeholder_name");
+  }
+  if (isTemplateSlot(key, value)) reasons.push("template_token");
+  return reasons;
+}
+function isTemplateSlot(key, value) {
+  if (JSX_EXPRESSION_VALUE.test(value) || BRACKET_SLOT_VALUE.test(value) || UPPER_SLOT_VALUE.test(value)) return true;
+  if (REPLACE_MARKER.test(value)) return true;
+  if (!BODY_TEXT_KEYS.has(key)) {
+    if (MUSTACHE_SLOT.test(value)) return true;
+    for (const match of value.matchAll(BRACKET_SLOT_IN_TEXT)) {
+      if (/^[A-Z]/.test(match[1])) return true;
+    }
+  }
+  return !URI_TEMPLATE_KEYS.has(key) && isUrlOrPath(value) && JSX_MEMBER_IN_TEXT.test(value);
+}
+function urlHost(value) {
+  const mailto = /^mailto:[^@\s?]+@([^?\s#/]+)/i.exec(value);
+  if (mailto) return mailto[1];
+  const url = /^(?:[a-z][a-z0-9+.-]*:)?\/\/(?:[^/?#@\s]*@)?([^/?#:\s]+)/i.exec(value);
+  if (url) return url[1];
+  const email = /^[^\s@/:]+@([^\s@/:?#]+)$/.exec(value);
+  if (email) return email[1];
+  const bare = /^((?:[a-z0-9-]+\.)+[a-z][a-z0-9-]*)\.?(?::\d+)?(?:[/?#]\S*)?$/i.exec(value);
+  return bare ? bare[1] : null;
+}
+function isReservedExampleHost(host) {
+  const h = host.toLowerCase().replace(/\.$/, "");
+  if (h === RESERVED_EXAMPLE_TLD || h.endsWith(`.${RESERVED_EXAMPLE_TLD}`)) return true;
+  return RESERVED_EXAMPLE_DOMAINS.some((domain) => h === domain || h.endsWith(`.${domain}`));
+}
+function isUrlOrPath(value) {
+  return /^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(value) || value.startsWith("/");
+}
+function isPlaceholderPhone(raw) {
+  const value = raw.replace(/^tel:/i, "").trim();
+  if (/^[+\d\s().xX-]+$/.test(value) && (value.match(/x/gi)?.length ?? 0) >= 4) return true;
+  let digits = value.replace(/\D/g, "");
+  if (digits.length === 11 && digits.startsWith("1")) digits = digits.slice(1);
+  if (digits.length >= 7 && /^0+$/.test(digits)) return true;
+  if (digits === "1234567890" || digits === "1234567") return true;
+  const local = digits.length === 10 ? digits.slice(3) : digits.length === 7 ? digits : null;
+  return local !== null && /^55501\d\d$/.test(local);
+}
+function normalizeName(value) {
+  return value.replace(/\s+/g, " ").trim().replace(/[.,]+$/, "").toLowerCase();
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNestedNode(value) {
+  return "@type" in value || "@id" in value || isAnnotationOnly(value);
+}
+function isGraphWrapper(value) {
+  return "@graph" in value && !("@type" in value) && !("@id" in value);
+}
+function isAnnotationOnly(value) {
+  if ("@type" in value || "@id" in value || "@graph" in value) return false;
+  const keys = Object.keys(value).filter((key) => key !== "@context");
+  return keys.length > 0 && keys.every((key) => ANNOTATION_KEYS.has(key));
+}
+function annotationEvidence(node) {
+  return Object.entries(node).filter(([key]) => ANNOTATION_KEYS.has(key)).slice(0, MAX_EVIDENCE).map(([key, value]) => ({
+    reason: "annotation",
+    key,
+    value: cutForLog(typeof value === "string" ? value : JSON.stringify(value) ?? "")
+  }));
+}
+function hasContentBeyond(obj, ignored) {
+  return Object.entries(obj).some(([key, value]) => !ignored.has(key) && hasContent(value));
+}
+function hasContent(value) {
+  if (value === null || value === void 0 || value === "") return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (isPlainObject(value)) return Object.keys(value).length > 0;
+  return true;
+}
+function typeOf(node) {
+  const type = node["@type"];
+  if (typeof type === "string") return type;
+  if (Array.isArray(type)) return type.filter((t) => typeof t === "string").join(",") || null;
+  return null;
+}
+function stepKey(path, key) {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function cutForLog(value) {
+  return value.length > EVIDENCE_VALUE_LENGTH ? `${value.slice(0, EVIDENCE_VALUE_LENGTH)}...` : value;
+}
+
+export { describeSchemaPlaceholder, findSchemaPlaceholders, withoutSchemaPlaceholders };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.2.0",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule and how a proposal's site plan counts its pages. Pure functions, no dependencies.",
+  "version": "2.4.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, and which stored JSON-LD is a template's unfilled placeholder. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -90,6 +90,16 @@
       "import": "./dist/proposal-sitemap.mjs",
       "require": "./dist/proposal-sitemap.js"
     },
+    "./error-page": {
+      "types": "./dist/error-page.d.ts",
+      "import": "./dist/error-page.mjs",
+      "require": "./dist/error-page.js"
+    },
+    "./schema-placeholders": {
+      "types": "./dist/schema-placeholders.d.ts",
+      "import": "./dist/schema-placeholders.mjs",
+      "require": "./dist/schema-placeholders.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {