ssrwire 0.2.0 → 0.4.0

package/src/stability.ts

@@ -1,3 +1,12 @@
+import {
+  effectiveTwitterCardSignal,
+  firstSocialSignal,
+  normalizeSocialValue,
+  OPEN_GRAPH_PROPERTIES,
+  OPEN_GRAPH_REQUIRED_PROPERTIES,
+  socialSignals,
+  TWITTER_CARD_REQUIRED_FIELDS,
+} from "./social.js";
 import type {
   AgentProfile,
   AgentStability,
@@ -7,6 +16,7 @@ import type {
   ProbeResult,
   RobotsAudience,
   RobotsSignal,
+  SocialMetadataProperty,
   TimingStats,
 } from "./types.js";
 
@@ -25,6 +35,11 @@ export interface StabilityAnalysis {
   readonly findings: readonly Finding[];
 }
 
+interface SocialSignature {
+  openGraph?: unknown;
+  twitterCard?: unknown;
+}
+
 function normalizeText(value: string): string {
   return value.trim().replace(/\s+/g, " ");
 }
@@ -117,8 +132,97 @@ function robotsValueLocations(probe: ProbeResult): readonly (readonly [string, s
   );
 }
 
-function metadataValueSignature(probe: ProbeResult): string {
+function socialValuesForSignature(
+  probe: ProbeResult,
+  property: SocialMetadataProperty,
+): readonly string[] {
+  const values = [
+    ...new Set(
+      socialSignals(probe.signals, property)
+        .map((signal) => normalizeSocialValue(property, signal.value, probe.finalUrl))
+        .filter((value) => value.length > 0),
+    ),
+  ];
+  return property === "og:image" ? values : values.sort();
+}
+
+function socialLocationsForSignature(
+  probe: ProbeResult,
+  property: SocialMetadataProperty,
+): readonly (readonly [string, string])[] {
+  if (property !== "og:image") {
+    return signalValueLocations(socialSignals(probe.signals, property), (value) =>
+      normalizeSocialValue(property, value, probe.finalUrl),
+    );
+  }
+  return socialSignals(probe.signals, property)
+    .map(
+      (signal) =>
+        [normalizeSocialValue(property, signal.value, probe.finalUrl), signal.location] as const,
+    )
+    .filter(([value]) => value.length > 0);
+}
+
+function socialValueSignature(target: AuditTarget, probe: ProbeResult): unknown {
+  const signature: SocialSignature = {};
+  if (target.expectations.requireOpenGraph === true) {
+    signature.openGraph = Object.fromEntries(
+      OPEN_GRAPH_PROPERTIES.map((property) => [
+        property,
+        socialValuesForSignature(probe, property),
+      ]),
+    );
+  }
+  if (target.expectations.requireTwitterCard === true) {
+    signature.twitterCard = Object.fromEntries(
+      TWITTER_CARD_REQUIRED_FIELDS.map((field) => {
+        const signal = effectiveTwitterCardSignal(probe.signals, field);
+        return [
+          field,
+          signal === undefined
+            ? "<missing>"
+            : normalizeSocialValue(signal.property, signal.value, probe.finalUrl) || "<missing>",
+        ];
+      }),
+    );
+  }
+  return Object.keys(signature).length === 0 ? undefined : signature;
+}
+
+function socialLocationSignature(target: AuditTarget, probe: ProbeResult): unknown {
+  const signature: SocialSignature = {};
+  if (target.expectations.requireOpenGraph === true) {
+    signature.openGraph = Object.fromEntries(
+      OPEN_GRAPH_PROPERTIES.map((property) => [
+        property,
+        socialLocationsForSignature(probe, property),
+      ]),
+    );
+  }
+  if (target.expectations.requireTwitterCard === true) {
+    signature.twitterCard = Object.fromEntries(
+      TWITTER_CARD_REQUIRED_FIELDS.map((field) => {
+        const signal = effectiveTwitterCardSignal(probe.signals, field);
+        return [
+          field,
+          signal === undefined
+            ? []
+            : [
+                [
+                  normalizeSocialValue(signal.property, signal.value, probe.finalUrl),
+                  signal.location,
+                ],
+              ],
+        ];
+      }),
+    );
+  }
+  return Object.keys(signature).length === 0 ? undefined : signature;
+}
+
+function metadataValueSignature(target: AuditTarget, probe: ProbeResult): string {
   const titles = probe.signals.titles ?? (probe.signals.title ? [probe.signals.title] : []);
+  const social = socialValueSignature(target, probe);
   return JSON.stringify({
     title: normalizedSignalValues(titles),
     description: normalizedSignalValues(probe.signals.descriptions),
@@ -126,11 +230,13 @@ function metadataValueSignature(probe: ProbeResult): string {
       normalizeCanonical(value, probe.finalUrl),
     ),
     robots: effectiveRobotsValue(probe),
+    ...(social === undefined ? {} : { social }),
   });
 }
 
-function metadataLocationSignature(probe: ProbeResult): string {
+function metadataLocationSignature(target: AuditTarget, probe: ProbeResult): string {
   const titles = probe.signals.titles ?? (probe.signals.title ? [probe.signals.title] : []);
+  const social = socialLocationSignature(target, probe);
   return JSON.stringify({
     title: signalValueLocations(titles),
     description: signalValueLocations(probe.signals.descriptions),
@@ -138,6 +244,7 @@ function metadataLocationSignature(probe: ProbeResult): string {
       normalizeCanonical(value, probe.finalUrl),
     ),
     robots: robotsValueLocations(probe),
+    ...(social === undefined ? {} : { social }),
   });
 }
 
@@ -213,6 +320,16 @@ export function criticalSignalsArrivalMs(
   }
   if (expectations.requireH1 && !addRequired(firstNonEmpty(probe.signals.h1s))) return undefined;
   if (expectations.requireMainText && !addRequired(probe.signals.firstMainText)) return undefined;
+  if (expectations.requireOpenGraph === true) {
+    for (const property of OPEN_GRAPH_REQUIRED_PROPERTIES) {
+      if (!addRequired(firstSocialSignal(probe.signals, property))) return undefined;
+    }
+  }
+  if (expectations.requireTwitterCard === true) {
+    for (const field of TWITTER_CARD_REQUIRED_FIELDS) {
+      if (!addRequired(effectiveTwitterCardSignal(probe.signals, field))) return undefined;
+    }
+  }
 
   return required === 0 ? undefined : Math.max(...marks);
 }
@@ -275,8 +392,10 @@ function summarizeAgent(target: AuditTarget, probes: readonly ProbeResult[]): Ag
       finalUrl: uniqueCount(finalResponses.map((probe) => normalizeUrl(probe.finalUrl))),
       redirectChain: uniqueCount(probes.map(redirectChainSignature)),
       bodySha256: uniqueCount(complete.map((probe) => probe.bodySha256 ?? "<missing>")),
-      metadataValues: uniqueCount(complete.map(metadataValueSignature)),
-      metadataLocations: uniqueCount(complete.map(metadataLocationSignature)),
+      metadataValues: uniqueCount(complete.map((probe) => metadataValueSignature(target, probe))),
+      metadataLocations: uniqueCount(
+        complete.map((probe) => metadataLocationSignature(target, probe)),
+      ),
     },
   };
 }

package/src/stream-parser.ts

@@ -1,5 +1,7 @@
 import { Parser } from "htmlparser2";
 
+import { isSocialMetadataProperty } from "./social.js";
+
 import type {
   DocumentSignals,
   ElementLocation,
@@ -7,6 +9,8 @@ import type {
   JsonLdSignal,
   RobotsAudience,
   RobotsSignal,
+  SocialMetadataProperty,
+  SocialMetadataSignal,
   TimingMark,
 } from "./types.js";
 
@@ -93,6 +97,8 @@ class HtmlStreamInspector implements StreamInspector {
   readonly #descriptions: ElementSignal[] = [];
   readonly #canonicals: ElementSignal[] = [];
   readonly #robots: RobotsSignal[] = [];
+  readonly #socialMetadata: SocialMetadataSignal[] = [];
+  readonly #socialMetadataCounts = new Map<SocialMetadataProperty, number>();
   readonly #h1s: ElementSignal[] = [];
   readonly #jsonLd: JsonLdSignal[] = [];
   readonly #titles: ElementSignal[] = [];
@@ -170,6 +176,7 @@ class HtmlStreamInspector implements StreamInspector {
       descriptions: [...this.#descriptions],
       canonicals: [...this.#canonicals],
       robots: [...this.#robots],
+      socialMetadata: [...this.#socialMetadata],
       h1s: [...this.#h1s],
       ...(firstMainText === undefined || firstMainText.value.length === 0 ? {} : { firstMainText }),
       jsonLd: [...this.#jsonLd],
@@ -213,7 +220,14 @@ class HtmlStreamInspector implements StreamInspector {
       return;
     }
 
-    const { name: metaNameAttribute, content, rel, href, type: scriptType } = attributes;
+    const {
+      name: metaNameAttribute,
+      property: metaPropertyAttribute,
+      content,
+      rel,
+      href,
+      type: scriptType,
+    } = attributes;
     if (name === "head") this.#inHead = true;
     if (name === "body") {
       if (this.#bodyStarted === undefined) this.#bodyStarted = this.#mark();
@@ -232,6 +246,7 @@ class HtmlStreamInspector implements StreamInspector {
 
     if (name === "meta") {
       const metaName = metaNameAttribute?.trim().toLowerCase();
+      const metaProperty = metaPropertyAttribute?.trim().toLowerCase();
       if (
         content !== undefined &&
         metaName === "description" &&
@@ -249,6 +264,21 @@ class HtmlStreamInspector implements StreamInspector {
           audience: metaName,
         });
       }
+      const socialProperty = isSocialMetadataProperty(metaProperty)
+        ? metaProperty
+        : isSocialMetadataProperty(metaName)
+          ? metaName
+          : undefined;
+      if (content !== undefined && socialProperty !== undefined) {
+        const count = this.#socialMetadataCounts.get(socialProperty) ?? 0;
+        if (count < SIGNAL_LIMIT) {
+          this.#socialMetadata.push({
+            ...this.#elementSignal(content, location),
+            property: socialProperty,
+          });
+          this.#socialMetadataCounts.set(socialProperty, count + 1);
+        }
+      }
     }
 
     if (name === "link") {

package/src/types.ts

@@ -18,6 +18,21 @@ export interface RobotsSignal extends ElementSignal {
   readonly audience: RobotsAudience;
 }
 
+export type SocialMetadataProperty =
+  | "og:title"
+  | "og:type"
+  | "og:url"
+  | "og:image"
+  | "og:description"
+  | "twitter:card"
+  | "twitter:title"
+  | "twitter:description"
+  | "twitter:image";
+
+export interface SocialMetadataSignal extends ElementSignal {
+  readonly property: SocialMetadataProperty;
+}
+
 export interface JsonLdSignal extends TimingMark {
   readonly location: ElementLocation;
   readonly valid?: boolean;
@@ -33,6 +48,8 @@ export interface DocumentSignals {
   readonly descriptions: readonly ElementSignal[];
   readonly canonicals: readonly ElementSignal[];
   readonly robots: readonly RobotsSignal[];
+  /** Present on current probes; optional for low-level callers and older in-memory results. */
+  readonly socialMetadata?: readonly SocialMetadataSignal[];
   readonly h1s: readonly ElementSignal[];
   readonly firstMainText?: ElementSignal;
   readonly jsonLd: readonly JsonLdSignal[];
@@ -109,11 +126,17 @@ export interface TargetExpectations {
   readonly requireCanonical: boolean;
   readonly requireH1: boolean;
   readonly requireMainText: boolean;
+  /** Require the four Open Graph protocol basic metadata properties. Defaults to false. */
+  readonly requireOpenGraph?: boolean;
+  /** Require SSRWire's Twitter Card readiness contract. Defaults to false. */
+  readonly requireTwitterCard?: boolean;
   readonly maxFirstByteMs?: number;
   readonly maxCriticalMs?: number;
 }
 
 export interface AuditTarget {
+  /** Stable identity used to match the same target across reports with different origins. */
+  readonly id?: string;
   readonly url: string;
   readonly expectations: TargetExpectations;
 }
@@ -190,6 +213,8 @@ export interface AuditSummary {
 }
 
 export interface AuditResult {
+  /** Version of the persisted audit-report contract, independent of the package version. */
+  readonly schemaVersion: 1;
   readonly version: string;
   readonly generatedAt: string;
   readonly durationMs: number;
@@ -199,3 +224,95 @@ export interface AuditResult {
 }
 
 export type ReportFormat = "terminal" | "json" | "sarif";
+
+export type ComparisonKind = "regression" | "fixed" | "changed";
+
+export type ComparisonScope = "target" | "agent" | "finding" | "response" | "metadata" | "timing";
+
+export interface ComparisonChange {
+  readonly kind: ComparisonKind;
+  readonly scope: ComparisonScope;
+  readonly code: string;
+  readonly message: string;
+  readonly agent?: string;
+  readonly field?: string;
+  readonly baseline?: string | number | boolean;
+  readonly candidate?: string | number | boolean;
+}
+
+export interface ComparisonTimelineEvent {
+  readonly key: string;
+  readonly label: string;
+  readonly medianMs: number;
+  readonly location?: ElementLocation | "mixed";
+  readonly observedByByte?: number;
+}
+
+export interface ComparisonTimelineSnapshot {
+  readonly samples: number;
+  readonly events: readonly ComparisonTimelineEvent[];
+}
+
+export interface ComparisonTimelineLane {
+  readonly agent: string;
+  readonly label: string;
+  readonly baseline?: ComparisonTimelineSnapshot;
+  readonly candidate?: ComparisonTimelineSnapshot;
+}
+
+export type TargetComparisonStatus = "matched" | "added" | "removed";
+
+export interface TargetComparison {
+  readonly key: string;
+  readonly id?: string;
+  readonly status: TargetComparisonStatus;
+  readonly baselineUrl?: string;
+  readonly candidateUrl?: string;
+  readonly changes: readonly ComparisonChange[];
+  readonly timelines: readonly ComparisonTimelineLane[];
+}
+
+export interface AuditReportDescriptor {
+  readonly label: string;
+  readonly version: string;
+  readonly schemaVersion: 1;
+  readonly generatedAt: string;
+  readonly repeat: number;
+}
+
+export interface ComparisonThresholds {
+  readonly timingRegressionMs: number;
+  readonly timingRegressionPercent: number;
+}
+
+export interface ComparisonSummary {
+  readonly targets: number;
+  readonly matchedTargets: number;
+  readonly addedTargets: number;
+  readonly removedTargets: number;
+  readonly unchangedTargets: number;
+  readonly regressions: number;
+  readonly fixed: number;
+  readonly changed: number;
+}
+
+export interface AuditComparison {
+  readonly schemaVersion: 1;
+  readonly kind: "comparison";
+  readonly version: string;
+  readonly generatedAt: string;
+  readonly baseline: AuditReportDescriptor;
+  readonly candidate: AuditReportDescriptor;
+  readonly thresholds: ComparisonThresholds;
+  readonly results: readonly TargetComparison[];
+  readonly summary: ComparisonSummary;
+}
+
+export interface CompareAuditOptions {
+  readonly baselineLabel?: string;
+  readonly candidateLabel?: string;
+  readonly timingRegressionMs?: number;
+  readonly timingRegressionPercent?: number;
+}
+
+export type ComparisonReportFormat = "terminal" | "json" | "html";