@sonordev/contracts 2.15.0 → 2.17.0

package/dist/portfolio.js

@@ -1,10 +1,43 @@
 'use strict';
 
-// 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 = {
@@ -47,6 +80,7 @@ var PORTFOLIO_SECTION_TYPES = [
   // proof
   "portfolioPerformance",
   "portfolioSpeedComparison",
+  "portfolioVerification",
   // outcome
   "portfolioResults",
   "portfolioMetricsTimeline",
@@ -75,6 +109,7 @@ var SECTION_STAGE = {
   portfolioTechStack: "build",
   portfolioPerformance: "proof",
   portfolioSpeedComparison: "proof",
+  portfolioVerification: "proof",
   portfolioResults: "outcome",
   portfolioMetricsTimeline: "outcome",
   portfolioConversionFunnel: "outcome",
@@ -94,6 +129,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])
 );
@@ -137,7 +184,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: {
@@ -148,15 +195,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;
@@ -236,6 +288,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 || "");
@@ -281,7 +677,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",
@@ -311,7 +706,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";
@@ -353,9 +748,15 @@ exports.PORTFOLIO_CONTRACT_VERSION = PORTFOLIO_CONTRACT_VERSION;
 exports.PORTFOLIO_KPI_JSON_SCHEMA = PORTFOLIO_KPI_JSON_SCHEMA;
 exports.PORTFOLIO_SECTION_ORDER = PORTFOLIO_SECTION_ORDER;
 exports.PORTFOLIO_SECTION_TYPES = PORTFOLIO_SECTION_TYPES;
+exports.PORTFOLIO_VERIFICATION_JSON_SCHEMA = PORTFOLIO_VERIFICATION_JSON_SCHEMA;
 exports.SECTION_STAGE = SECTION_STAGE;
+exports.STAGE_CORE_ALTERNATES = STAGE_CORE_ALTERNATES;
 exports.STAGE_CORE_SECTION = STAGE_CORE_SECTION;
 exports.STAGE_NAME_MAX_CHARS = STAGE_NAME_MAX_CHARS;
+exports.VERIFICATION_CHECK_FIELDS = VERIFICATION_CHECK_FIELDS;
+exports.VERIFICATION_EARLIEST_DAY = VERIFICATION_EARLIEST_DAY;
+exports.VERIFICATION_FIELD_MAX_CHARS = VERIFICATION_FIELD_MAX_CHARS;
+exports.VERIFICATION_MAX_CHECKS = VERIFICATION_MAX_CHECKS;
 exports.carryReportedMetrics = carryReportedMetrics;
 exports.caseStudyFlowProblems = caseStudyFlowProblems;
 exports.caseStudyStageStatus = caseStudyStageStatus;
@@ -367,12 +768,20 @@ exports.isFrameReadyMessage = isFrameReadyMessage;
 exports.isHeadlineMetric = isHeadlineMetric;
 exports.isLighthouseKpi = isLighthouseKpi;
 exports.isMetricSource = isMetricSource;
+exports.isPlaceholderText = isPlaceholderText;
 exports.isPortfolioSectionType = isPortfolioSectionType;
+exports.isRealDay = isRealDay;
+exports.isVacuousScope = isVacuousScope;
+exports.latestVerificationDay = latestVerificationDay;
 exports.metricSourceLabel = metricSourceLabel;
 exports.metricSourceProblem = metricSourceProblem;
 exports.narrativeProblems = narrativeProblems;
 exports.orderSections = orderSections;
+exports.readVerificationChecks = readVerificationChecks;
 exports.sectionStage = sectionStage;
 exports.shortAttribution = shortAttribution;
+exports.stageCoreSections = stageCoreSections;
 exports.stageName = stageName;
 exports.stageNamesProblems = stageNamesProblems;
+exports.verificationLink = verificationLink;
+exports.verificationProblems = verificationProblems;