ssrwire 0.3.0 → 0.4.0

package/dist/types.d.ts

@@ -30,7 +30,7 @@ export interface DocumentSignals {
     readonly descriptions: readonly ElementSignal[];
     readonly canonicals: readonly ElementSignal[];
     readonly robots: readonly RobotsSignal[];
-    /** Present on probes produced by SSRWire 0.3.0 and newer. */
+    /** 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;
@@ -103,6 +103,8 @@ export interface TargetExpectations {
     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;
 }
@@ -170,6 +172,8 @@ export interface AuditSummary {
     readonly incomplete: number;
 }
 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;
@@ -178,4 +182,82 @@ export interface AuditResult {
     readonly summary: AuditSummary;
 }
 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";
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/examples/github-actions.yml

@@ -27,7 +27,7 @@ jobs:
         if: github.event_name == 'pull_request'
         continue-on-error: true
         run: >-
-          npx --yes ssrwire@0.3.0 check
+          npx --yes ssrwire@0.4.0 check
           --config ssrwire.config.yml
           --format sarif
           --output reports/ssrwire.sarif
@@ -38,7 +38,7 @@ jobs:
         if: github.event_name != 'pull_request'
         continue-on-error: true
         run: >-
-          npx --yes ssrwire@0.3.0 check
+          npx --yes ssrwire@0.4.0 check
           --config ssrwire.config.yml
           --format sarif
           --output reports/ssrwire.sarif

package/examples/ssrwire.config.yml

@@ -1,6 +1,7 @@
 # Replace these URLs with a small set of high-value SSR routes.
 targets:
-  - url: https://example.com/
+  - id: home
+    url: https://example.com/
     expectedStatus: 200
     expectedFinalUrl: https://example.com/
     require:
@@ -12,7 +13,8 @@ targets:
       openGraph: true
       twitterCard: true
 
-  - url: https://example.com/pricing/
+  - id: pricing
+    url: https://example.com/pricing/
     expectedStatus: 200
     require:
       title: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssrwire",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Inspect streamed SSR HTML, SEO and social metadata timing, and crawler-specific delivery from the command line.",
   "type": "module",
   "bin": {

package/src/audit-report.ts

@@ -0,0 +1,269 @@
+import { z } from "zod";
+import type { AuditResult } from "./types.js";
+
+export const AUDIT_SCHEMA_VERSION = 1 as const;
+
+const nonNegativeNumber = z.number().finite().nonnegative();
+const nonNegativeInteger = z.number().int().nonnegative();
+const elementLocation = z.enum(["head", "body", "document"]);
+const severity = z.enum(["info", "warning", "error"]);
+
+const timingMark = z
+  .object({
+    atMs: nonNegativeNumber,
+    observedByByte: nonNegativeInteger,
+  })
+  .strict();
+
+const elementSignal = timingMark
+  .extend({
+    value: z.string(),
+    location: elementLocation,
+  })
+  .strict();
+
+const robotsSignal = elementSignal
+  .extend({ audience: z.enum(["robots", "googlebot", "bingbot"]) })
+  .strict();
+
+const socialMetadataSignal = elementSignal
+  .extend({
+    property: z.enum([
+      "og:title",
+      "og:type",
+      "og:url",
+      "og:image",
+      "og:description",
+      "twitter:card",
+      "twitter:title",
+      "twitter:description",
+      "twitter:image",
+    ]),
+  })
+  .strict();
+
+const jsonLdSignal = timingMark
+  .extend({
+    location: elementLocation,
+    valid: z.boolean().optional(),
+    types: z.array(z.string()),
+    bytes: nonNegativeInteger,
+    analysisLimit: z.string().optional(),
+    error: z.string().optional(),
+  })
+  .strict();
+
+const documentSignals = z
+  .object({
+    title: elementSignal.optional(),
+    titles: z.array(elementSignal).optional(),
+    descriptions: z.array(elementSignal),
+    canonicals: z.array(elementSignal),
+    robots: z.array(robotsSignal),
+    socialMetadata: z.array(socialMetadataSignal).optional(),
+    h1s: z.array(elementSignal),
+    firstMainText: elementSignal.optional(),
+    jsonLd: z.array(jsonLdSignal),
+    headClosed: timingMark.optional(),
+    bodyStarted: timingMark.optional(),
+    documentClosed: timingMark.optional(),
+  })
+  .strict();
+
+const agentProfile = z
+  .object({
+    key: z.string().min(1),
+    label: z.string().min(1),
+    userAgent: z.string(),
+    requiresHeadMetadata: z.boolean(),
+  })
+  .strict();
+
+const redirectHop = z
+  .object({
+    url: z.string(),
+    status: z.number().int().min(100).max(599),
+    location: z.string(),
+    durationMs: nonNegativeNumber,
+  })
+  .strict();
+
+const headerSnapshot = z
+  .object({
+    values: z.record(z.string(), z.string()),
+    setCookiePresent: z.boolean(),
+  })
+  .strict();
+
+const probeTimings = z
+  .object({
+    headersMs: nonNegativeNumber,
+    firstByteMs: nonNegativeNumber.optional(),
+    completeMs: nonNegativeNumber.optional(),
+  })
+  .strict();
+
+const probeResult = z
+  .object({
+    requestedUrl: z.string(),
+    finalUrl: z.string(),
+    agent: agentProfile,
+    status: z.number().int().min(100).max(599).optional(),
+    redirects: z.array(redirectHop),
+    headers: headerSnapshot,
+    timings: probeTimings,
+    bytesRead: nonNegativeInteger,
+    bodySha256: z.string().optional(),
+    signals: documentSignals,
+    completion: z.enum([
+      "complete",
+      "max-bytes-exceeded",
+      "timeout",
+      "network-error",
+      "invalid-response",
+    ]),
+    error: z.string().optional(),
+    sample: z.number().int().positive().optional(),
+  })
+  .strict();
+
+const targetExpectations = z
+  .object({
+    statuses: z.array(z.number().int().min(100).max(599)).min(1),
+    finalUrl: z.string().optional(),
+    requireTitle: z.boolean(),
+    requireDescription: z.boolean(),
+    requireCanonical: z.boolean(),
+    requireH1: z.boolean(),
+    requireMainText: z.boolean(),
+    requireOpenGraph: z.boolean().optional(),
+    requireTwitterCard: z.boolean().optional(),
+    maxFirstByteMs: z.number().positive().finite().optional(),
+    maxCriticalMs: z.number().positive().finite().optional(),
+  })
+  .strict();
+
+const auditTarget = z
+  .object({
+    id: z.string().min(1).optional(),
+    url: z.string(),
+    expectations: targetExpectations,
+  })
+  .strict();
+
+const timingStats = z
+  .object({
+    samples: nonNegativeInteger,
+    minMs: nonNegativeNumber,
+    medianMs: nonNegativeNumber,
+    p95Ms: nonNegativeNumber,
+    maxMs: nonNegativeNumber,
+    spreadMs: nonNegativeNumber,
+  })
+  .strict();
+
+const stabilityTimings = z
+  .object({
+    headers: timingStats.optional(),
+    firstByte: timingStats.optional(),
+    criticalSignals: timingStats.optional(),
+    complete: timingStats.optional(),
+  })
+  .strict();
+
+const stabilityVariants = z
+  .object({
+    completion: nonNegativeInteger,
+    status: nonNegativeInteger,
+    finalUrl: nonNegativeInteger,
+    redirectChain: nonNegativeInteger,
+    bodySha256: nonNegativeInteger,
+    metadataValues: nonNegativeInteger,
+    metadataLocations: nonNegativeInteger,
+  })
+  .strict();
+
+const agentStability = z
+  .object({
+    agent: agentProfile,
+    samples: nonNegativeInteger,
+    complete: nonNegativeInteger,
+    incomplete: nonNegativeInteger,
+    timings: stabilityTimings,
+    variants: stabilityVariants,
+  })
+  .strict();
+
+const finding = z
+  .object({
+    code: z.string().min(1),
+    severity,
+    message: z.string(),
+    url: z.string(),
+    agent: z.string().optional(),
+    evidence: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+  })
+  .strict();
+
+const targetAuditResult = z
+  .object({
+    target: auditTarget,
+    probes: z.array(probeResult),
+    findings: z.array(finding),
+    stability: z.array(agentStability).optional(),
+  })
+  .strict();
+
+const auditSummary = z
+  .object({
+    targets: nonNegativeInteger,
+    probes: nonNegativeInteger,
+    errors: nonNegativeInteger,
+    warnings: nonNegativeInteger,
+    info: nonNegativeInteger,
+    incomplete: nonNegativeInteger,
+  })
+  .strict();
+
+const auditReportSchema = z
+  .object({
+    schemaVersion: z.literal(AUDIT_SCHEMA_VERSION),
+    version: z.string().min(1),
+    generatedAt: z.string().min(1),
+    durationMs: nonNegativeNumber,
+    repeat: z.number().int().min(1).max(10).optional(),
+    results: z.array(targetAuditResult),
+    summary: auditSummary,
+  })
+  .strict();
+
+export class AuditReportError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "AuditReportError";
+  }
+}
+
+export function parseAuditReport(value: unknown, source = "audit report"): AuditResult {
+  const parsed = auditReportSchema.safeParse(value);
+  if (!parsed.success) {
+    const detail = parsed.error.issues
+      .slice(0, 5)
+      .map((issue) => `${issue.path.join(".") || "report"}: ${issue.message}`)
+      .join("; ");
+    throw new AuditReportError(`Invalid ${source}: ${detail}`);
+  }
+
+  // The complete runtime schema above is the persisted counterpart of AuditResult.
+  return parsed.data as AuditResult;
+}
+
+export function parseAuditReportText(text: string, source = "audit report"): AuditResult {
+  let value: unknown;
+  try {
+    value = JSON.parse(text) as unknown;
+  } catch {
+    throw new AuditReportError(`Could not parse ${source} as JSON.`);
+  }
+  return parseAuditReport(value, source);
+}

package/src/audit.ts

@@ -1,4 +1,5 @@
 import { analyzeTarget, summarizeAudit } from "./analyze.js";
+import { AUDIT_SCHEMA_VERSION } from "./audit-report.js";
 import { probeUrl } from "./http-probe.js";
 import { redactAudit } from "./redact.js";
 import { analyzeStability } from "./stability.js";
@@ -186,6 +187,7 @@ export async function runAudit(config: SsrWireConfig): Promise<AuditResult> {
   });
 
   const audit: AuditResult = {
+    schemaVersion: AUDIT_SCHEMA_VERSION,
     version: VERSION,
     generatedAt: new Date().toISOString(),
     durationMs: Math.round(performance.now() - started),

package/src/cli.ts

@@ -1,10 +1,13 @@
-import { access, mkdir, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 import { Command, CommanderError, InvalidArgumentError } from "commander";
 import { runAudit } from "./audit.js";
+import { AuditReportError, parseAuditReportText } from "./audit-report.js";
+import { compareAudits } from "./compare.js";
+import { renderComparisonReport } from "./comparison-reporters.js";
 import { ConfigError, loadConfig } from "./config.js";
 import { renderReport } from "./reporters.js";
-import type { ReportFormat } from "./types.js";
+import type { AuditResult, ComparisonReportFormat, ReportFormat } from "./types.js";
 import { VERSION } from "./version.js";
 
 interface CliOptions {
@@ -21,9 +24,19 @@ interface CliOptions {
   readonly color: boolean;
 }
 
+interface CompareCliOptions {
+  readonly format: ComparisonReportFormat;
+  readonly output?: string;
+  readonly failOn: "regression" | "never";
+  readonly timingRegressionMs: number;
+  readonly timingRegressionPercent: number;
+  readonly color: boolean;
+}
+
 const CONFIG_TEMPLATE = `# SSRWire configuration
 targets:
-  - url: https://example.com/
+  - id: home
+    url: https://example.com/
     expectedStatus: 200
     require:
       title: true
@@ -76,6 +89,24 @@ function parseFailOn(value: string): CliOptions["failOn"] {
   throw new InvalidArgumentError("Expected error, warning, or never.");
 }
 
+function parseComparisonFormat(value: string): ComparisonReportFormat {
+  if (value === "terminal" || value === "json" || value === "html") return value;
+  throw new InvalidArgumentError("Expected terminal, json, or html.");
+}
+
+function parseComparisonFailOn(value: string): CompareCliOptions["failOn"] {
+  if (value === "regression" || value === "never") return value;
+  throw new InvalidArgumentError("Expected regression or never.");
+}
+
+function parseNonNegativeNumber(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new InvalidArgumentError("Expected a finite non-negative number.");
+  }
+  return parsed;
+}
+
 function addCheckOptions(command: Command): Command {
   return command
     .option("-c, --config <path>", "configuration file")
@@ -120,6 +151,16 @@ async function writeReport(path: string, report: string): Promise<void> {
   await writeFile(absolute, report, "utf8");
 }
 
+async function readAuditFile(path: string, label: string): Promise<AuditResult> {
+  let text: string;
+  try {
+    text = await readFile(resolve(path), "utf8");
+  } catch {
+    throw new AuditReportError(`Could not read ${label} audit report: ${path}`);
+  }
+  return parseAuditReportText(text, `${label} audit report`);
+}
+
 async function check(urls: readonly string[], options: CliOptions): Promise<void> {
   const config = await loadConfig({
     ...(options.config ? { configPath: options.config } : {}),
@@ -149,6 +190,38 @@ async function check(urls: readonly string[], options: CliOptions): Promise<void
   process.exitCode = reportExitCode(audit.summary, options.failOn);
 }
 
+async function compareReports(
+  baselinePath: string,
+  candidatePath: string,
+  options: CompareCliOptions,
+): Promise<void> {
+  const [baseline, candidate] = await Promise.all([
+    readAuditFile(baselinePath, "baseline"),
+    readAuditFile(candidatePath, "candidate"),
+  ]);
+  const comparison = compareAudits(baseline, candidate, {
+    baselineLabel: basename(baselinePath),
+    candidateLabel: basename(candidatePath),
+    timingRegressionMs: options.timingRegressionMs,
+    timingRegressionPercent: options.timingRegressionPercent,
+  });
+  const color =
+    options.color &&
+    !options.output &&
+    Boolean(process.stdout.isTTY) &&
+    !Reflect.has(process.env, "NO_COLOR");
+  const report = renderComparisonReport(comparison, options.format, { color });
+
+  if (options.output) {
+    await writeReport(options.output, report);
+    process.stderr.write(`SSRWire wrote ${options.format} comparison to ${options.output}\n`);
+  } else {
+    process.stdout.write(report);
+  }
+
+  process.exitCode = options.failOn === "regression" && comparison.summary.regressions > 0 ? 1 : 0;
+}
+
 async function initialize(path: string, force: boolean): Promise<void> {
   const absolute = resolve(path);
   if (!force) {
@@ -175,21 +248,40 @@ export async function main(argv: readonly string[] = process.argv): Promise<void
     .exitOverride()
     .showHelpAfterError();
 
-  addCheckOptions(program)
-    .argument("[urls...]", "HTTP or HTTPS URLs to inspect")
-    .action(async (urls: string[], _options: CliOptions, command: Command) => {
-      await check(urls, optionsFrom(command));
-    });
-
   addCheckOptions(
     program
-      .command("check")
+      .command("check", { isDefault: true })
       .description("inspect one or more SSR responses")
       .argument("[urls...]", "HTTP or HTTPS URLs to inspect"),
   ).action(async (urls: string[], _options: CliOptions, command: Command) => {
     await check(urls, optionsFrom(command));
   });
 
+  program
+    .command("compare")
+    .description("compare two SSRWire JSON audit reports")
+    .argument("<baseline>", "baseline JSON audit report")
+    .argument("<candidate>", "candidate JSON audit report")
+    .option("-f, --format <format>", "terminal, json, or html", parseComparisonFormat, "terminal")
+    .option("-o, --output <path>", "write the comparison to a file")
+    .option("--fail-on <level>", "regression or never", parseComparisonFailOn, "regression")
+    .option(
+      "--timing-regression-ms <ms>",
+      "minimum absolute median slowdown",
+      parseNonNegativeNumber,
+      250,
+    )
+    .option(
+      "--timing-regression-percent <percent>",
+      "minimum relative median slowdown",
+      parseNonNegativeNumber,
+      25,
+    )
+    .option("--no-color", "disable terminal colors")
+    .action(async (baselinePath: string, candidatePath: string, options: CompareCliOptions) => {
+      await compareReports(baselinePath, candidatePath, options);
+    });
+
   program
     .command("init")
     .description("create a documented starter configuration")