ssrwire 0.2.0 → 0.4.0

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
@@ -31,6 +44,8 @@ targets:
       canonical: true
       h1: true
       mainText: true
+      openGraph: false
+      twitterCard: false
 
 agents:
   - browser
@@ -74,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")
@@ -118,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 } : {}),
@@ -147,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) {
@@ -168,26 +243,45 @@ export async function main(argv: readonly string[] = process.argv): Promise<void
   const program = new Command();
   program
     .name("ssrwire")
-    .description("Inspect streamed SSR HTML and crawler-specific metadata delivery.")
+    .description("Inspect streamed SSR HTML, SEO, and social metadata delivery.")
     .version(VERSION)
     .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")