@sonordev/contracts 2.3.0 → 2.5.0

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;

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/dist/sentences.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Sentences contract: how prose is split into sentences, so the APIs that cut
+ * an excerpt, a carousel slide or a summary out of an article agree on where
+ * a sentence ends. The APIs import it as `@sonordev/contracts/sentences`.
+ *
+ * Lossless: joining the result with spaces gives back every word of the input,
+ * in order. The usual one-liner, `text.match(/[^.!?]+[.!?]+(?=\s|$)/g)`, isn't.
+ * A period it can't use, like the first one in "9 p.m. call", makes match()
+ * skip ahead and silently drop every word before its next match, so a
+ * sentence about a 9 p.m. call comes back as "m.". Don't re-fork a regex for
+ * this.
+ *
+ * A sentence ends at . ! or ? (and any closing quote or bracket after it)
+ * followed by whitespace, then an optional opening quote or bracket, then
+ * A to Z or 0 to 9. Never before a lowercase word or a symbol, and only ASCII
+ * capitals count. It doesn't end at:
+ *  - an abbreviation: a dotted one made of letters ("p.m.", "U.S.", "e.g.",
+ *    "Ph.D."), a single letter ("J.", "Plan A."), or a short form listed below
+ *    (titles, months, days, company suffixes, street suffixes);
+ *  - a label that has a number after it ("No. 5", "Fig. 2", "Ste. 200");
+ *  - a list number ("1.", "Step 2.", "Do three things: 1.").
+ * A piece with no letter in it ("...", "1.") isn't a sentence and joins the
+ * next one. A "!" or "?" is never held back by an abbreviation (only a period
+ * is), though the same start-of-sentence rule applies after it.
+ *
+ * Prices, versions, domains and email addresses ("$4.50", "v2.1",
+ * "example.com") are not abbreviations: a sentence can end after them.
+ *
+ * Where it is unsure it leans toward not splitting, because a sentence that
+ * runs long costs less than a lost word. A period after a short form that
+ * isn't listed ends a sentence like any other.
+ *
+ * It reads sentences, not layout. A newline or a list marker doesn't start a
+ * new sentence by itself, so split text into lines or paragraphs first when
+ * those matter, then split each one.
+ */
+/**
+ * Splits prose into trimmed sentences without dropping or reordering a word.
+ * Empty, blank and nullish input give `[]`, never `null`.
+ *
+ * One pass, linear in the length of the text: each run of . ! ? (and the
+ * closing quotes or brackets after it) is looked at once, an abbreviation or
+ * list-marker check reads only the last few characters, and the check for a
+ * letter reads each character once.
+ */
+export declare function splitSentences(text: string | null | undefined): string[];