@sonordev/contracts 2.15.0 → 2.16.0

package/dist/portfolio.mjs

@@ -1,8 +1,41 @@
-// src/contracts/portfolio.ts
+// src/contracts/public-url-host.ts
+function isPrivateIpv4(a, b) {
+  return a === 127 || a === 10 || a === 0 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127 || a >= 224;
+}
+function ipv6Words(host) {
+  if (!host.includes(":") || !/^[a-f\d:.]+$/.test(host)) return null;
+  let canonical;
+  try {
+    canonical = new URL(`http://[${host}]/`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const sides = canonical.split("::");
+  const left = sides[0] ? sides[0].split(":") : [];
+  const right = sides.length > 1 && sides[1] ? sides[1].split(":") : [];
+  return [...left, ...Array(sides.length > 1 ? 8 - left.length - right.length : 0).fill("0"), ...right].map((word) => parseInt(word, 16));
+}
+function isBlockedPublicUrlHost(rawHost) {
+  const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
+  const blockedName = host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal");
+  if (host.includes(":") && host.includes("%")) return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  const blockedIp = !!ipv4 && isPrivateIpv4(Number(ipv4[1]), Number(ipv4[2]));
+  const words = ipv6Words(host);
+  const blockedIpv6 = !!words && // Unspecified/loopback, unique-local, link-local, deprecated site-local
+  // and multicast destinations aren't public logo/webhook endpoints.
+  (words.every((word) => word === 0) || words.slice(0, 7).every((word) => word === 0) && words[7] === 1 || (words[0] & 65024) === 64512 || (words[0] & 65472) === 65152 || (words[0] & 65472) === 65216 || (words[0] & 65280) === 65280 || // IPv4-mapped and older IPv4-compatible forms carry an IPv4 destination.
+  words.slice(0, 5).every((word) => word === 0) && [0, 65535].includes(words[5]) && isPrivateIpv4(words[6] >> 8, words[6] & 255));
+  return blockedName || blockedIp || blockedIpv6;
+}
+
+// src/contracts/frame-ready.ts
 var FRAME_READY_MESSAGE = "sonor:frame-ready";
 function isFrameReadyMessage(data) {
   return !!data && typeof data === "object" && data.type === FRAME_READY_MESSAGE && data.v === 1;
 }
+
+// src/contracts/portfolio.ts
 var PORTFOLIO_CONTRACT_VERSION = 1;
 var CASE_STUDY_STAGES = ["problem", "build", "proof", "outcome"];
 var CASE_STUDY_STAGE_COPY = {
@@ -45,6 +78,7 @@ var PORTFOLIO_SECTION_TYPES = [
   // proof
   "portfolioPerformance",
   "portfolioSpeedComparison",
+  "portfolioVerification",
   // outcome
   "portfolioResults",
   "portfolioMetricsTimeline",
@@ -73,6 +107,7 @@ var SECTION_STAGE = {
   portfolioTechStack: "build",
   portfolioPerformance: "proof",
   portfolioSpeedComparison: "proof",
+  portfolioVerification: "proof",
   portfolioResults: "outcome",
   portfolioMetricsTimeline: "outcome",
   portfolioConversionFunnel: "outcome",
@@ -92,6 +127,18 @@ var STAGE_CORE_SECTION = {
   proof: "portfolioPerformance",
   outcome: "portfolioResults"
 };
+var STAGE_CORE_ALTERNATES = {
+  proof: ["portfolioVerification"]
+};
+var STAND_IN_HAS_CONTENT = {
+  portfolioVerification: (data) => readVerificationChecks(data).length > 0
+};
+var STAND_IN_EMPTY_COPY = {
+  portfolioVerification: "The verification is there, but none of its checks can be shown yet. Add a check, and say what it doesn't cover."
+};
+function stageCoreSections(stage) {
+  return [STAGE_CORE_SECTION[stage], ...STAGE_CORE_ALTERNATES[stage] ?? []];
+}
 var PORTFOLIO_SECTION_ORDER = Object.fromEntries(
   PORTFOLIO_SECTION_TYPES.map((type, i) => [type, i])
 );
@@ -135,7 +182,7 @@ var STAGE_MISSING_COPY = {
     noCore: "The build is shown but the plan behind it is missing. Add the strategy."
   },
   proof: {
-    empty: "Nothing measures the finished build. Add a performance measurement.",
+    empty: "Nothing measures the finished build. Add a performance measurement, or a verification when the screens are behind a sign-in.",
     noCore: "The old site is compared but the finished build has no measurement of its own. Add a performance measurement."
   },
   outcome: {
@@ -146,15 +193,20 @@ var STAGE_MISSING_COPY = {
 function caseStudyStageStatus(sections) {
   const ordered = orderSections(sections);
   return CASE_STUDY_STAGES.map((stage) => {
-    const present = ordered.map((s) => s.sectionType).filter((t) => isPortfolioSectionType(t) && SECTION_STAGE[t] === stage);
-    const complete = present.includes(STAGE_CORE_SECTION[stage]);
+    const own = ordered.filter(
+      (s) => isPortfolioSectionType(s.sectionType) && SECTION_STAGE[s.sectionType] === stage
+    );
+    const present = own.map((s) => s.sectionType);
+    const standIns = STAGE_CORE_ALTERNATES[stage] ?? [];
+    const emptyStandIns = own.filter(
+      (s) => standIns.includes(s.sectionType) && STAND_IN_HAS_CONTENT[s.sectionType]?.(s.data) === false
+    );
+    const complete = own.some(
+      (s) => s.sectionType === STAGE_CORE_SECTION[stage] || standIns.includes(s.sectionType) && !emptyStandIns.includes(s)
+    );
     const copy = STAGE_MISSING_COPY[stage];
-    return {
-      stage,
-      present,
-      complete,
-      missing: complete ? null : present.length ? copy.noCore : copy.empty
-    };
+    const missing = complete ? null : (emptyStandIns.length ? STAND_IN_EMPTY_COPY[emptyStandIns[0].sectionType] : void 0) ?? (present.length ? copy.noCore : copy.empty);
+    return { stage, present, complete, missing };
   });
 }
 var NARRATIVE_MAX_CHARS = 320;
@@ -234,6 +286,350 @@ function caseStudyFlowProblems(input) {
   }
   return problems;
 }
+var ISO_DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+function isRealDay(value) {
+  if (typeof value !== "string" || !ISO_DAY_RE.test(value)) return false;
+  const [year, month, day] = value.split("-").map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+var VERIFICATION_MAX_CHECKS = 8;
+var VERIFICATION_CHECK_FIELDS = ["label", "result", "measured", "where", "method", "date", "scope"];
+var VERIFICATION_FIELD_MAX_CHARS = {
+  label: 80,
+  result: 120,
+  measured: 200,
+  where: 200,
+  method: 240,
+  scope: 240
+};
+var VERIFICATION_EARLIEST_DAY = "2000-01-01";
+function latestVerificationDay(now = /* @__PURE__ */ new Date()) {
+  const tomorrow = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));
+  return tomorrow.toISOString().slice(0, 10);
+}
+function wordsOf(text) {
+  return text.toLowerCase().replace(/['’]/g, "").split(/[^a-z0-9]+/).filter(Boolean);
+}
+var FILLER_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "of",
+  "to",
+  "at",
+  "as",
+  "in",
+  "is",
+  "are",
+  "be",
+  "it",
+  "this",
+  "that",
+  "any",
+  "all"
+]);
+var PLACEHOLDER_WORDS = /* @__PURE__ */ new Set([
+  ...FILLER_WORDS,
+  "n",
+  "na",
+  "nil",
+  "null",
+  "undefined",
+  "none",
+  "nothing",
+  "else",
+  "no",
+  "not",
+  "yes",
+  "ok",
+  "okay",
+  "x",
+  "xx",
+  "xxx",
+  "tbd",
+  "tbc",
+  "tba",
+  "todo",
+  "lorem",
+  "ipsum",
+  "misc",
+  "etc",
+  "various",
+  "multiple",
+  "same",
+  "above",
+  "see",
+  "here",
+  "there",
+  "applicable",
+  "available",
+  "relevant",
+  "required",
+  "needed",
+  "specified",
+  "unspecified",
+  "provided",
+  "given",
+  "stated",
+  "known",
+  "unknown",
+  "apply",
+  "applies",
+  "exist",
+  "exists",
+  "restriction",
+  "restrictions",
+  "limit",
+  "limits",
+  "limitation",
+  "limitations",
+  "caveat",
+  "caveats",
+  "exclusion",
+  "exclusions",
+  "exception",
+  "exceptions",
+  "constraint",
+  "constraints",
+  "gap",
+  "gaps",
+  "issue",
+  "issues",
+  "problem",
+  "problems",
+  "boundary",
+  "boundaries"
+]);
+var LIMIT_WORDS = /* @__PURE__ */ new Set([
+  "only",
+  "not",
+  "never",
+  "cannot",
+  "except",
+  "beyond",
+  "outside",
+  "just",
+  "solely",
+  "merely",
+  "unless",
+  "besides",
+  "untested",
+  "unmeasured",
+  "unchecked",
+  "unverified",
+  // negative contractions, apostrophe dropped
+  "isnt",
+  "arent",
+  "wasnt",
+  "werent",
+  "dont",
+  "doesnt",
+  "didnt",
+  "cant",
+  "couldnt",
+  "wont",
+  "wouldnt",
+  "hasnt",
+  "havent",
+  "hadnt",
+  "shouldnt",
+  "mustnt",
+  "neednt"
+]);
+var EXCLUSION_WORDS = /* @__PURE__ */ new Set([
+  "exclude",
+  "excludes",
+  "excluded",
+  "excluding",
+  "omit",
+  "omits",
+  "omitted",
+  "skip",
+  "skips",
+  "skipped",
+  "limited"
+]);
+var NEGATOR_WORDS = /* @__PURE__ */ new Set(["no", "none", "nothing", "without"]);
+function isPlaceholderText(text) {
+  const words = wordsOf(text);
+  return words.length === 0 || words.every((word) => PLACEHOLDER_WORDS.has(word));
+}
+function isVacuousScope(scope) {
+  const words = wordsOf(scope);
+  if (words.length < 2) return true;
+  const wordAfter = (i) => {
+    for (let j = i + 1; j < words.length; j++) if (!FILLER_WORDS.has(words[j])) return words[j];
+    return void 0;
+  };
+  const wordBefore = (i) => {
+    for (let j = i - 1; j >= 0; j--) if (!FILLER_WORDS.has(words[j])) return words[j];
+    return void 0;
+  };
+  const marksLimit = words.map((word, i) => {
+    if (NEGATOR_WORDS.has(word)) {
+      const next = wordAfter(i);
+      return next !== void 0 && !PLACEHOLDER_WORDS.has(next) && !EXCLUSION_WORDS.has(next);
+    }
+    if (EXCLUSION_WORDS.has(word)) return !NEGATOR_WORDS.has(wordBefore(i) ?? "");
+    return LIMIT_WORDS.has(word);
+  });
+  if (!marksLimit.some(Boolean)) return true;
+  return !words.some(
+    (word) => !PLACEHOLDER_WORDS.has(word) && !LIMIT_WORDS.has(word) && !EXCLUSION_WORDS.has(word) && !NEGATOR_WORDS.has(word)
+  );
+}
+function carriesCredentials(text) {
+  for (let at = text.indexOf("://"); at !== -1; at = text.indexOf("://", at + 3)) {
+    for (let i = at + 3; i < text.length; i++) {
+      const char = text[i];
+      if (char === "@") return true;
+      if (char === "/" || char === "?" || char === "#" || /\s/.test(char)) break;
+    }
+  }
+  return false;
+}
+var WEB_ADDRESS = /^https?:\/\//i;
+var BARE_PRIVATE_ADDRESS = /^(?:localhost|\d{1,3}(?:\.\d{1,3}){3}|\[[0-9a-f:.]+\])(?::\d+)?(?:[/?#]|$)/i;
+function trimPunctuation(word) {
+  let start = 0;
+  let end = word.length;
+  while (start < end && `("'<`.includes(word[start])) start++;
+  while (end > start && `)"'>.,;!?`.includes(word[end - 1])) end--;
+  return word.slice(start, end);
+}
+function namesPrivateAddress(text) {
+  return text.split(/\s+/).some((word) => {
+    const token = trimPunctuation(word);
+    const address = WEB_ADDRESS.test(token) ? token : BARE_PRIVATE_ADDRESS.test(token) ? `http://${token}` : null;
+    if (!address) return false;
+    try {
+      return isBlockedPublicUrlHost(new URL(address).hostname);
+    } catch {
+      return false;
+    }
+  });
+}
+function looksLikePathOrHost(token) {
+  const pieces = token.split(/[/\\.]/).filter(Boolean);
+  return pieces.length >= 2 && pieces.every((piece) => /^[\w:-]{2,}$/.test(piece));
+}
+function whereProblem(where) {
+  if (carriesCredentials(where)) return "must not carry a username or password";
+  if (namesPrivateAddress(where)) return "must be a public address, not localhost or a private network";
+  const named = !isPlaceholderText(where) && (verificationLink(where) !== null || where.split(/\s+/).length >= 2 || looksLikePathOrHost(where));
+  return named ? null : "must say where the check ran: a public web address, or a screen or file named in words";
+}
+var NOT_PLAIN_LINE = /[\p{Cc}\u2028\u2029\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/u;
+function checkProblems(check, at, latestDay, strict) {
+  if (!check || typeof check !== "object" || Array.isArray(check)) return [`${at} must be an object`];
+  const entry = check;
+  const problems = [];
+  if (strict) {
+    for (const key of Object.keys(entry)) {
+      if (!VERIFICATION_CHECK_FIELDS.includes(key)) problems.push(`${at}.${key} is not a field`);
+    }
+  }
+  for (const field of VERIFICATION_CHECK_FIELDS) {
+    const value = entry[field];
+    if (typeof value !== "string" || !value.trim()) {
+      problems.push(
+        field === "scope" ? `${at}.scope is required: say what the check does not cover` : `${at}.${field} is required`
+      );
+      continue;
+    }
+    if (NOT_PLAIN_LINE.test(value)) problems.push(`${at}.${field} must be one line of plain text`);
+    if (field === "date") continue;
+    const max = VERIFICATION_FIELD_MAX_CHARS[field];
+    if (value.trim().length > max) problems.push(`${at}.${field} is over ${max} characters`);
+  }
+  const date = typeof entry.date === "string" ? entry.date.trim() : "";
+  if (date) {
+    if (!isRealDay(date)) problems.push(`${at}.date must be a real day, YYYY-MM-DD`);
+    else if (date < VERIFICATION_EARLIEST_DAY) problems.push(`${at}.date must be ${VERIFICATION_EARLIEST_DAY} or later`);
+    else if (date > latestDay) problems.push(`${at}.date is in the future`);
+  }
+  const text = (field) => {
+    const value = entry[field];
+    return typeof value === "string" && value.trim() && value.trim().length <= VERIFICATION_FIELD_MAX_CHARS[field] ? value.trim() : null;
+  };
+  const where = text("where");
+  const problem = where === null ? null : whereProblem(where);
+  if (problem) problems.push(`${at}.where ${problem}`);
+  const scope = text("scope");
+  if (scope !== null && isVacuousScope(scope)) {
+    problems.push(`${at}.scope must state a limit: what the check does not cover, using a word like "only", "not", "except" or "without"`);
+  }
+  return problems;
+}
+function verificationProblems(data, options = {}) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return ["verification data must be an object"];
+  const { checks, ...rest } = data;
+  const problems = Object.keys(rest).map((key) => `${key} is not a field of a verification`);
+  if (!Array.isArray(checks) || checks.length === 0) return [...problems, "checks must list at least one check"];
+  if (checks.length > VERIFICATION_MAX_CHECKS) {
+    problems.push(`checks is over ${VERIFICATION_MAX_CHECKS} entries; keep the ones that matter`);
+  }
+  const latestDay = options.latestDay ?? latestVerificationDay();
+  checks.forEach((check, i) => problems.push(...checkProblems(check, `checks[${i}]`, latestDay, true)));
+  return problems;
+}
+function readVerificationChecks(data, options = {}) {
+  const checks = data?.checks;
+  if (!Array.isArray(checks)) return [];
+  const latestDay = options.latestDay ?? latestVerificationDay();
+  const shown = [];
+  checks.forEach((check, i) => {
+    if (shown.length >= VERIFICATION_MAX_CHECKS || checkProblems(check, `checks[${i}]`, latestDay, false).length) return;
+    const entry = check;
+    shown.push(
+      Object.fromEntries(VERIFICATION_CHECK_FIELDS.map((field) => [field, entry[field].trim()]))
+    );
+  });
+  return shown;
+}
+function verificationLink(where) {
+  const text = where.trim();
+  if (!text || /\s/.test(text)) return null;
+  try {
+    const url = new URL(text);
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    if (url.username || url.password || isBlockedPublicUrlHost(url.hostname)) return null;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+var PORTFOLIO_VERIFICATION_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/portfolio-verification.v1.json",
+  title: "PortfolioVerificationData",
+  description: "A short list of checks on the finished build. Each says what was checked, where, how, when, what came out, and what it does not cover.",
+  type: "object",
+  required: ["checks"],
+  properties: {
+    checks: {
+      type: "array",
+      minItems: 1,
+      maxItems: VERIFICATION_MAX_CHECKS,
+      items: {
+        type: "object",
+        required: [...VERIFICATION_CHECK_FIELDS],
+        properties: {
+          label: { type: "string", minLength: 1, maxLength: VERIFICATION_FIELD_MAX_CHARS.label },
+          result: { type: "string", minLength: 1, maxLength: VERIFICATION_FIELD_MAX_CHARS.result },
+          measured: { type: "string", minLength: 1, maxLength: VERIFICATION_FIELD_MAX_CHARS.measured },
+          where: { type: "string", minLength: 1, maxLength: VERIFICATION_FIELD_MAX_CHARS.where },
+          method: { type: "string", minLength: 1, maxLength: VERIFICATION_FIELD_MAX_CHARS.method },
+          date: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
+          scope: { type: "string", minLength: 1, maxLength: VERIFICATION_FIELD_MAX_CHARS.scope }
+        },
+        additionalProperties: false
+      }
+    }
+  },
+  additionalProperties: false
+};
 var LIGHTHOUSE_RE = /lighthouse/i;
 function isLighthouseKpi(kpi) {
   return LIGHTHOUSE_RE.test(kpi.label || "");
@@ -279,7 +675,6 @@ var PORTFOLIO_KPI_JSON_SCHEMA = {
   additionalProperties: true
 };
 var METRIC_SOURCES = ["measured", "reported", "estimated"];
-var ISO_DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
 var MONTHS = [
   "January",
   "February",
@@ -309,7 +704,7 @@ function metricSourceProblem(metric) {
   if (typeof by.organization !== "string" || !by.organization.trim()) {
     return "reportedBy.organization is required";
   }
-  if (typeof by.date !== "string" || !ISO_DAY_RE.test(by.date) || Number.isNaN(Date.parse(by.date))) {
+  if (typeof by.date !== "string" || !isRealDay(by.date)) {
     return "reportedBy.date must be a real day, YYYY-MM-DD";
   }
   if (by.role !== void 0 && typeof by.role !== "string") return "reportedBy.role must be text";
@@ -341,4 +736,4 @@ function carryReportedMetrics(previous, next, keyOf) {
   return [...reported, ...generated];
 }
 
-export { CASE_STUDY_NARRATIVE_JSON_SCHEMA, CASE_STUDY_STAGES, CASE_STUDY_STAGE_COPY, FRAME_READY_MESSAGE, METRIC_SOURCES, NARRATIVE_MAX_CHARS, PORTFOLIO_CONTRACT_VERSION, PORTFOLIO_KPI_JSON_SCHEMA, PORTFOLIO_SECTION_ORDER, PORTFOLIO_SECTION_TYPES, SECTION_STAGE, STAGE_CORE_SECTION, STAGE_NAME_MAX_CHARS, carryReportedMetrics, caseStudyFlowProblems, caseStudyStageStatus, challengeId, curateHeroKpis, formatAttribution, groupSectionsByStage, isFrameReadyMessage, isHeadlineMetric, isLighthouseKpi, isMetricSource, isPortfolioSectionType, metricSourceLabel, metricSourceProblem, narrativeProblems, orderSections, sectionStage, shortAttribution, stageName, stageNamesProblems };
+export { CASE_STUDY_NARRATIVE_JSON_SCHEMA, CASE_STUDY_STAGES, CASE_STUDY_STAGE_COPY, FRAME_READY_MESSAGE, METRIC_SOURCES, NARRATIVE_MAX_CHARS, PORTFOLIO_CONTRACT_VERSION, PORTFOLIO_KPI_JSON_SCHEMA, PORTFOLIO_SECTION_ORDER, PORTFOLIO_SECTION_TYPES, PORTFOLIO_VERIFICATION_JSON_SCHEMA, SECTION_STAGE, STAGE_CORE_ALTERNATES, STAGE_CORE_SECTION, STAGE_NAME_MAX_CHARS, VERIFICATION_CHECK_FIELDS, VERIFICATION_EARLIEST_DAY, VERIFICATION_FIELD_MAX_CHARS, VERIFICATION_MAX_CHECKS, carryReportedMetrics, caseStudyFlowProblems, caseStudyStageStatus, challengeId, curateHeroKpis, formatAttribution, groupSectionsByStage, isFrameReadyMessage, isHeadlineMetric, isLighthouseKpi, isMetricSource, isPlaceholderText, isPortfolioSectionType, isRealDay, isVacuousScope, latestVerificationDay, metricSourceLabel, metricSourceProblem, narrativeProblems, orderSections, readVerificationChecks, sectionStage, shortAttribution, stageCoreSections, stageName, stageNamesProblems, verificationLink, verificationProblems };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.15.0",
+  "version": "2.16.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, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, what a publication's branding may hold, which literal hosts are refused as public fetch destinations, and which inbox cards are decisions a bulk action leaves alone. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {