@sonordev/contracts 2.2.0 → 2.4.0

package/dist/schema-placeholders.d.ts

@@ -0,0 +1,87 @@
+/**
+ * JSON-LD template placeholders: found once, dropped wherever sonor-api serves
+ * stored schema to a site, and never stored as implemented by register-schema.
+ *
+ * Stored JSON-LD (seo_schema_markup.schema_json, seo_pages.managed_schema) can
+ * carry a template's unfilled slots. Schema extracted from a site's source,
+ * where the base URL was a variable, comes back as https://example.com; an AI
+ * filling a template leaves "Example", "+1-000-000-0000", "[Resident Name]",
+ * "{plan.name}", or an object that is only a "note" saying what goes there.
+ * site-kit renders all of it on the live page, where search engines and AI
+ * crawlers take it as the business's identity. Observed 2026-10-01: a live
+ * site served an Organization named "Example", phone +1-000-000-0000, on its
+ * home page, and dozens more of its implemented rows carried example.com URLs
+ * and unfilled template slots.
+ *
+ * Conservative on purpose, because a false positive removes real schema from a
+ * live site:
+ *   - Domains: only the reserved example domains (example.com, example.net,
+ *     example.org, their subdomains, and the .example TLD), and only when the
+ *     whole value is a URL, host or email address. A real domain with
+ *     "example" in its path, or prose that mentions example.com, is fine.
+ *   - Names: whole-value matches only (trimmed, case-insensitive) on name-like
+ *     properties. "Example Plumbing Co" is a real name.
+ *   - Phones (telephone, faxNumber, tel: links): all zeros, 123-456-7890,
+ *     XXX-XXX-XXXX, and 555-0100 through 555-0199, the North American range
+ *     reserved for fiction. 555-0200 and 555-1212 are real numbers.
+ *   - Template slots: a value that is wholly a bracketed slot ("[YYYY-MM-DD]")
+ *     or a JSX expression ("{plan.name}"), a {{mustache}} slot, a
+ *     REPLACE_WITH_ marker, a title-case field name in brackets inside text
+ *     ("Call [Phone Number]"), or a JSX member expression inside a URL. A URI
+ *     template's {search_term_string} is how schema.org spells a SearchAction
+ *     and is never a finding.
+ *   - Annotations: an object that holds nothing but an AI note. A note key on
+ *     a real node is stripped (it isn't schema.org vocabulary) and the node
+ *     stays.
+ *
+ * The unit is the NODE: the innermost object with @type or @id (or a top-level
+ * or @graph member) whose own values hold the placeholder. A placeholder node
+ * is dropped whole, since its other values came from the same unfilled
+ * template. Its real siblings, and a real parent it hangs off, stay: an
+ * FAQPage keeps its questions when only its publisher was a placeholder. A
+ * node left with nothing but JSON-LD keywords once its placeholder children
+ * are gone (a BreadcrumbList whose every item was a placeholder) goes too, so
+ * the site falls back to what it generates itself.
+ *
+ * Single source of truth for "is this stored schema a placeholder", published
+ * as `@sonordev/contracts/schema-placeholders`: sonor-api's public schema reads
+ * and register-schema, and site-kit's ManagedSchema and LLMSchema (so a site
+ * drops a placeholder whichever Sonor source served it) all call it. Add new
+ * shapes here, with a test, never in a caller.
+ */
+export type SchemaPlaceholderReason = 'example_domain' | 'placeholder_phone' | 'placeholder_name' | 'template_token' | 'annotation' | 'emptied';
+export interface SchemaPlaceholderEvidence {
+    reason: SchemaPlaceholderReason;
+    /** The property that held the value. */
+    key: string;
+    /** The value, cut short for logs. */
+    value: string;
+}
+export interface SchemaPlaceholderNode {
+    /** Where the node sits: '$' for the root, then .key and [index] steps. */
+    path: string;
+    /** The node's @type ('A,B' when it has several), or null. */
+    type: string | null;
+    reasons: SchemaPlaceholderReason[];
+    evidence: SchemaPlaceholderEvidence[];
+}
+export interface SchemaPlaceholderScan<T> {
+    /** The value without its placeholder nodes: the same reference when nothing was found, null when nothing real is left. */
+    value: T | null;
+    /** Every node removed, outermost only (a dropped node's children go with it). */
+    dropped: SchemaPlaceholderNode[];
+    /** AI note keys stripped from nodes that were kept. */
+    notes: Array<{
+        path: string;
+        key: string;
+    }>;
+}
+/**
+ * The value with its placeholder nodes removed, and what was removed. Pure; the
+ * input is never mutated.
+ */
+export declare function withoutSchemaPlaceholders<T>(value: T): SchemaPlaceholderScan<T>;
+/** Which nodes of a JSON-LD value are placeholders, and why. */
+export declare function findSchemaPlaceholders(value: unknown): SchemaPlaceholderNode[];
+/** One line a person can act on: 'Organization at $: name "Example" is a placeholder name'. */
+export declare function describeSchemaPlaceholder(node: SchemaPlaceholderNode): string;

package/dist/schema-placeholders.js

@@ -0,0 +1,321 @@
+'use strict';
+
+// 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;
+}
+
+exports.describeSchemaPlaceholder = describeSchemaPlaceholder;
+exports.findSchemaPlaceholders = findSchemaPlaceholders;
+exports.withoutSchemaPlaceholders = withoutSchemaPlaceholders;