ssrwire 0.1.0 → 0.3.0

package/src/redact.ts

@@ -90,6 +90,11 @@ function redactSignals(signals: DocumentSignals, plan: RedactionPlan): DocumentS
     descriptions: signals.descriptions.map((signal) => redactElement(signal, plan)),
     canonicals: signals.canonicals.map((signal) => redactElement(signal, plan)),
     robots: signals.robots.map((signal) => redactElement(signal, plan)),
+    ...(signals.socialMetadata === undefined
+      ? {}
+      : {
+          socialMetadata: signals.socialMetadata.map((signal) => redactElement(signal, plan)),
+        }),
     h1s: signals.h1s.map((signal) => redactElement(signal, plan)),
     ...(signals.firstMainText === undefined
       ? {}
@@ -160,6 +165,18 @@ export function redactAudit(audit: AuditResult, secrets: readonly string[]): Aud
         },
       },
       probes: result.probes.map((probe) => redactProbeWithPlan(probe, plan)),
+      ...(result.stability === undefined
+        ? {}
+        : {
+            stability: result.stability.map((summary) => ({
+              ...summary,
+              agent: {
+                ...summary.agent,
+                label: redactText(summary.agent.label, plan),
+                userAgent: redactText(summary.agent.userAgent, plan),
+              },
+            })),
+          }),
       findings: result.findings.map((finding) => ({
         ...finding,
         message: redactText(finding.message, plan),

package/src/reporters.ts

@@ -1,4 +1,11 @@
+import {
+  effectiveTwitterCardSignal,
+  firstSocialSignal,
+  OPEN_GRAPH_REQUIRED_PROPERTIES,
+  TWITTER_CARD_REQUIRED_FIELDS,
+} from "./social.js";
 import type {
+  AgentStability,
   AuditResult,
   ElementSignal,
   Finding,
@@ -70,8 +77,9 @@ function firstSignal(signals: readonly ElementSignal[]): ElementSignal | undefin
   return signals.find((signal) => signal.value.trim().length > 0) ?? signals[0];
 }
 
-function probeRow(probe: ProbeResult): readonly string[] {
+function probeRow(probe: ProbeResult, showSample: boolean): readonly string[] {
   return [
+    ...(showSample ? [String(probe.sample ?? "—")] : []),
     truncate(probe.agent.label, 24),
     probe.status === undefined ? "—" : String(probe.status),
     probe.completion,
@@ -84,6 +92,59 @@ function probeRow(probe: ProbeResult): readonly string[] {
   ];
 }
 
+function formatSignalSet(signals: readonly (ElementSignal | undefined)[]): string {
+  const present = signals.filter((signal): signal is ElementSignal => signal !== undefined);
+  if (present.length < signals.length) return `${present.length}/${signals.length}`;
+  const arrivalMs = Math.max(...present.map((signal) => signal.atMs));
+  const location = present.some((signal) => signal.location === "body")
+    ? "body"
+    : present.some((signal) => signal.location === "document")
+      ? "document"
+      : "head";
+  return `${Math.round(arrivalMs)} ms/${location}`;
+}
+
+function socialRow(probe: ProbeResult, showSample: boolean): readonly string[] {
+  return [
+    ...(showSample ? [String(probe.sample ?? "—")] : []),
+    truncate(probe.agent.label, 24),
+    formatSignalSet(
+      OPEN_GRAPH_REQUIRED_PROPERTIES.map((property) => firstSocialSignal(probe.signals, property)),
+    ),
+    formatSignalSet(
+      TWITTER_CARD_REQUIRED_FIELDS.map((field) => effectiveTwitterCardSignal(probe.signals, field)),
+    ),
+  ];
+}
+
+function stabilityRows(stability: readonly AgentStability[]): readonly (readonly string[])[] {
+  const labels: Readonly<Record<keyof AgentStability["timings"], string>> = {
+    headers: "Headers",
+    firstByte: "First byte",
+    criticalSignals: "Critical signals",
+    complete: "Complete",
+  };
+  const rows: string[][] = [];
+  for (const summary of stability) {
+    for (const key of ["headers", "firstByte", "criticalSignals", "complete"] as const) {
+      const stats = summary.timings[key];
+      if (stats === undefined) continue;
+      rows.push([
+        truncate(summary.agent.label, 24),
+        `${summary.complete}/${summary.samples}`,
+        labels[key],
+        String(stats.samples),
+        formatMs(stats.minMs),
+        formatMs(stats.medianMs),
+        formatMs(stats.p95Ms),
+        formatMs(stats.maxMs),
+        formatMs(stats.spreadMs),
+      ]);
+    }
+  }
+  return rows;
+}
+
 function renderTable(headers: readonly string[], rows: readonly (readonly string[])[]): string {
   const widths = headers.map((header, column) =>
     Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)),
@@ -116,12 +177,17 @@ export function renderTerminal(audit: AuditResult, options: ReporterOptions = {}
     paint(`SSRWire ${audit.version}`, ANSI.bold, color),
     paint(`Generated ${audit.generatedAt} in ${formatMs(audit.durationMs)}`, ANSI.dim, color),
   ];
+  if ((audit.repeat ?? 1) > 1) {
+    lines.push(paint(`${audit.repeat} sequential samples per URL and agent`, ANSI.dim, color));
+  }
 
   for (const result of audit.results) {
+    const showSample = (audit.repeat ?? 1) > 1;
     lines.push("", paint(terminalSafe(result.target.url), ANSI.bold, color));
     lines.push(
       renderTable(
         [
+          ...(showSample ? ["Sample"] : []),
           "Agent",
           "HTTP",
           "Result",
@@ -132,10 +198,39 @@ export function renderTerminal(audit: AuditResult, options: ReporterOptions = {}
           "Canonical",
           "Main",
         ],
-        result.probes.map(probeRow),
+        result.probes.map((probe) => probeRow(probe, showSample)),
       ),
     );
 
+    const showSocial =
+      result.target.expectations.requireOpenGraph === true ||
+      result.target.expectations.requireTwitterCard === true ||
+      result.probes.some((probe) => (probe.signals.socialMetadata?.length ?? 0) > 0);
+    if (showSocial) {
+      lines.push(
+        "",
+        "Social preview readiness",
+        renderTable(
+          [...(showSample ? ["Sample"] : []), "Agent", "Open Graph", "Twitter Card"],
+          result.probes.map((probe) => socialRow(probe, showSample)),
+        ),
+      );
+    }
+
+    if (result.stability !== undefined) {
+      const rows = stabilityRows(result.stability);
+      if (rows.length > 0) {
+        lines.push(
+          "",
+          "Stability timings (nearest-rank p95)",
+          renderTable(
+            ["Agent", "Complete", "Metric", "N", "Min", "Median", "P95", "Max", "Spread"],
+            rows,
+          ),
+        );
+      }
+    }
+
     if (result.findings.length === 0) {
       lines.push("Findings: none");
     } else {

package/src/social.ts

@@ -0,0 +1,116 @@
+import type { DocumentSignals, SocialMetadataProperty, SocialMetadataSignal } from "./types.js";
+
+export const SOCIAL_METADATA_PROPERTIES = [
+  "og:title",
+  "og:type",
+  "og:url",
+  "og:image",
+  "og:description",
+  "twitter:card",
+  "twitter:title",
+  "twitter:description",
+  "twitter:image",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const OPEN_GRAPH_PROPERTIES = [
+  "og:title",
+  "og:type",
+  "og:url",
+  "og:image",
+  "og:description",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const OPEN_GRAPH_REQUIRED_PROPERTIES = [
+  "og:title",
+  "og:type",
+  "og:url",
+  "og:image",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const TWITTER_PROPERTIES = [
+  "twitter:card",
+  "twitter:title",
+  "twitter:description",
+  "twitter:image",
+] as const satisfies readonly SocialMetadataProperty[];
+
+export const TWITTER_CARD_REQUIRED_FIELDS = ["card", "title", "description", "image"] as const;
+export type TwitterCardField = (typeof TWITTER_CARD_REQUIRED_FIELDS)[number];
+
+const SOCIAL_METADATA_PROPERTY_SET = new Set<string>(SOCIAL_METADATA_PROPERTIES);
+const SOCIAL_URL_PROPERTY_SET = new Set<SocialMetadataProperty>([
+  "og:url",
+  "og:image",
+  "twitter:image",
+]);
+
+export function isSocialMetadataProperty(
+  value: string | undefined,
+): value is SocialMetadataProperty {
+  return value !== undefined && SOCIAL_METADATA_PROPERTY_SET.has(value);
+}
+
+export function socialSignals(
+  signals: DocumentSignals,
+  property: SocialMetadataProperty,
+): readonly SocialMetadataSignal[] {
+  return (signals.socialMetadata ?? []).filter((signal) => signal.property === property);
+}
+
+export function firstSocialSignal(
+  signals: DocumentSignals,
+  property: SocialMetadataProperty,
+): SocialMetadataSignal | undefined {
+  return socialSignals(signals, property).find((signal) => signal.value.trim().length > 0);
+}
+
+export function effectiveTwitterCardSignal(
+  signals: DocumentSignals,
+  field: TwitterCardField,
+): SocialMetadataSignal | undefined {
+  if (field === "card") return firstSocialSignal(signals, "twitter:card");
+  if (field === "title") {
+    return firstSocialSignal(signals, "twitter:title") ?? firstSocialSignal(signals, "og:title");
+  }
+  if (field === "description") {
+    return (
+      firstSocialSignal(signals, "twitter:description") ??
+      firstSocialSignal(signals, "og:description")
+    );
+  }
+  return firstSocialSignal(signals, "twitter:image") ?? firstSocialSignal(signals, "og:image");
+}
+
+export function normalizeSocialValue(
+  property: SocialMetadataProperty,
+  value: string,
+  baseUrl: string,
+): string {
+  const normalized = value.trim().replace(/\s+/gu, " ");
+  if (normalized.length === 0) return "";
+  if (SOCIAL_URL_PROPERTY_SET.has(property)) {
+    try {
+      const url = new URL(normalized, baseUrl);
+      url.hash = "";
+      return url.href;
+    } catch {
+      return normalized;
+    }
+  }
+  return property === "og:type" || property === "twitter:card"
+    ? normalized.toLowerCase()
+    : normalized;
+}
+
+export function isAbsoluteHttpSocialUrl(value: string): boolean {
+  try {
+    const url = new URL(value.trim());
+    return (
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      url.username.length === 0 &&
+      url.password.length === 0
+    );
+  } catch {
+    return false;
+  }
+}