pagesight 0.18.0 → 0.20.0

package/src/api/compare-snapshots.ts

@@ -1,221 +1,9 @@
-import { z } from "zod";
+import { canonical, normalizeReport, parseNumericValue, Incompatible, requireSame } from "./report-table.js";
 import { RequestError } from "../shared/http.js";
 import { capture, type Evidence } from "./evidence.js";
 import type { ImportedSnapshot } from "./evidence-schema.js";
-import { gaRequestSchema, gscRequestSchema } from "./schema.js";
 
-const gscRow = z
-  .object({
-    keys: z.array(z.string()).optional(),
-    clicks: z.number().finite(),
-    impressions: z.number().finite(),
-    ctr: z.number().finite(),
-    position: z.number().finite(),
-  })
-  .passthrough();
-const gscResponse = z
-  .object({
-    rows: z.array(gscRow).default([]),
-    responseAggregationType: z.string().min(1),
-    metadata: z.record(z.unknown()).optional(),
-  })
-  .passthrough();
-const gaResponse = z
-  .object({
-    dimensionHeaders: z.array(z.object({ name: z.string() })).default([]),
-    metricHeaders: z.array(z.object({ name: z.string(), type: z.string().optional() })).min(1),
-    rows: z
-      .array(
-        z.object({
-          dimensionValues: z.array(z.object({ value: z.string() })).default([]),
-          metricValues: z.array(z.object({ value: z.string() })),
-        }),
-      )
-      .default([]),
-    metadata: z.object({ timeZone: z.string().min(1), currencyCode: z.string().optional() }).passthrough(),
-  })
-  .passthrough();
-const gaComparisonDimensions = new Set([
-  "hostName",
-  "sessionDefaultChannelGroup",
-  "sessionSourceMedium",
-  "eventName",
-  "landingPagePlusQueryString",
-  "sessionSource",
-]);
-
-function canonical(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (value && typeof value === "object")
-    return `{${Object.entries(value)
-      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-      .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`)
-      .join(",")}}`;
-  return JSON.stringify(value) ?? "undefined";
-}
-
-type RawValue = number | string;
-type Report = {
-  request: unknown;
-  start: string;
-  end: string;
-  dimensions: string[];
-  metrics: string[];
-  semantics: unknown;
-  rows: Map<string, { keys: string[]; values: RawValue[] }>;
-  warnings: string[];
-};
-class Incompatible extends Error {}
-const requireSame = (a: unknown, b: unknown, message: string) => {
-  if (canonical(a) !== canonical(b)) throw new Incompatible(message);
-};
-
-type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
-
-function normalizeReport(observation: Evidence, context: SnapshotContext): Report {
-  let report: Report | undefined;
-  let offset = 0;
-  for (const page of observation.pages) {
-    let current: Omit<Report, "rows">;
-    let rows: Array<{ keys: string[]; values: RawValue[] }>;
-    if (observation.provider === "gsc") {
-      const q = gscRequestSchema.parse(page.request);
-      const response = gscResponse.parse(page.response);
-      if (
-        q.dataState !== "final" ||
-        Object.keys(response.metadata ?? {}).some((key) => key.startsWith("first_incomplete"))
-      )
-        throw new Incompatible("GSC data must be finalized.");
-      if (q.startRow !== offset)
-        throw new Incompatible("Report must contain contiguous pages starting at offset zero.");
-      if (q.dimensions.some((dimension) => dimension === "date" || dimension === "hour"))
-        throw new Incompatible(
-          "Time dimensions need a separate alignment policy; this comparison uses non-time row keys.",
-        );
-      const { startDate, endDate, startRow: _startRow, rowLimit: _rowLimit, ...scope } = q;
-      current = {
-        request: scope,
-        start: startDate,
-        end: endDate,
-        dimensions: q.dimensions,
-        metrics: ["clicks", "impressions", "ctr", "position"],
-        semantics: { aggregation: response.responseAggregationType, timezone: "America/Los_Angeles" },
-        warnings: [],
-      };
-      if (!context.observedGscDates.includes(endDate))
-        current.warnings.push(
-          "GSC has no observed date row for the requested end date; trailing days may be unavailable or have no activity.",
-        );
-      rows = response.rows.map((r) => ({ keys: r.keys ?? [], values: [r.clicks, r.impressions, r.ctr, r.position] }));
-    } else {
-      const q = gaRequestSchema.parse(page.request);
-      const response = gaResponse.parse(page.response);
-      if (q.dateRanges.length !== 1) throw new Incompatible("GA comparison requires exactly one date range.");
-      if (
-        q.dimensions.some(
-          (dimension) => !gaComparisonDimensions.has(dimension.name) || Object.hasOwn(dimension, "dimensionExpression"),
-        )
-      )
-        throw new Incompatible("GA comparison supports only snapshot dimension names without dimension expressions.");
-      if (q.offset !== offset) throw new Incompatible("Report must contain contiguous pages starting at offset zero.");
-      const { dateRanges, offset: _offset, limit: _limit, returnPropertyQuota: _quota, ...scope } = q;
-      const dimensions = q.dimensions.map((d) => d.name);
-      const metrics = q.metrics.map((m) => m.name);
-      if (new Set(metrics).size !== metrics.length)
-        throw new Incompatible("GA metric names must be unique to preserve every compared value.");
-      requireSame(
-        response.dimensionHeaders.map((h) => h.name),
-        dimensions,
-        "GA dimension headers must match the request.",
-      );
-      requireSame(
-        response.metricHeaders.map((h) => h.name),
-        metrics,
-        "GA metric headers must match the request.",
-      );
-      current = {
-        request: scope,
-        start: dateRanges[0].startDate,
-        end: dateRanges[0].endDate,
-        dimensions,
-        metrics,
-        semantics: {
-          timezone: response.metadata.timeZone,
-          currency: response.metadata.currencyCode ?? null,
-          metrics: response.metricHeaders,
-        },
-        warnings: [],
-      };
-      if (response.metadata.subjectToThresholding) current.warnings.push("GA report is subject to thresholding.");
-      if (response.metadata.dataLossFromOtherRow)
-        current.warnings.push("GA high-cardinality rows were combined into (other).");
-      if (Array.isArray(response.metadata.samplingMetadatas) && response.metadata.samplingMetadatas.length)
-        current.warnings.push("GA report is sampled.");
-      const collectedDate = new Intl.DateTimeFormat("en-CA", {
-        timeZone: response.metadata.timeZone,
-        year: "numeric",
-        month: "2-digit",
-        day: "2-digit",
-      }).format(new Date(observation.finishedAt));
-      if (Date.parse(collectedDate) - Date.parse(current.end) < 3 * 86400000)
-        current.warnings.push(
-          "GA was collected fewer than three property-calendar days after the requested end date; recent data may still change.",
-        );
-      if (response.metricHeaders.some((h) => h.type === "TYPE_CURRENCY") && !response.metadata.currencyCode)
-        throw new Incompatible("GA currency metrics require a known response currency.");
-      rows = response.rows.map((r) => ({
-        keys: r.dimensionValues.map((v) => v.value),
-        values: r.metricValues.map((v) => v.value),
-      }));
-    }
-    requireSame(
-      { startDate: current.start, endDate: current.end },
-      { startDate: context.requestedDates.startDate, endDate: context.requestedDates.endDate },
-      "Report period does not match the snapshot context.",
-    );
-    if (report) {
-      requireSame(
-        [report.request, report.start, report.end, report.semantics],
-        [current.request, current.start, current.end, current.semantics],
-        "Report scope or metadata changed between pages.",
-      );
-      report.warnings.push(...current.warnings);
-    } else report = { ...current, rows: new Map() };
-    for (const row of rows) {
-      if (row.keys.length !== current.dimensions.length || row.values.length !== current.metrics.length)
-        throw new Incompatible("Row shape does not match the requested dimensions and metrics.");
-      const key = canonical(row.keys);
-      if (report.rows.has(key)) throw new Incompatible("Duplicate row keys make this report ambiguous.");
-      report.rows.set(key, row);
-    }
-    offset += rows.length;
-  }
-  if (!report) throw new Incompatible("No report pages available.");
-  if (
-    observation.pagination &&
-    (observation.pagination.rowsReturned !== offset ||
-      observation.pagination.nextOffset !== (observation.pagination.exhausted ? null : offset))
-  )
-    throw new Incompatible("Report pagination does not match the retained rows.");
-  if (observation.status !== "ok" || !observation.pagination?.exhausted || observation.error)
-    report.warnings.push(
-      "Report has incomplete pagination or a provider failure; only observed common rows can be compared.",
-    );
-  return report;
-}
-
-function parseNumericValue(value: RawValue): number | null {
-  if (typeof value === "string" && !/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/u.test(value)) return null;
-  const result = Number(value);
-  if (typeof value === "string" && !/^-?\d+$/u.test(value)) {
-    const mantissa = value.split(/[eE]/u)[0];
-    const significant = mantissa.replace(/[-.]/gu, "").replace(/^0+/u, "").replace(/0+$/u, "");
-    if (significant.length > 15 || (result === 0 && /[1-9]/u.test(mantissa))) return null;
-  }
-  return Number.isFinite(result) && Math.abs(result) <= Number.MAX_SAFE_INTEGER ? result : null;
-}
-
-function metric(baseline: RawValue, current: RawValue) {
+function metric(baseline: number | string, current: number | string) {
   const before = parseNumericValue(baseline);
   const after = parseNumericValue(current);
   if (before === null || after === null)
@@ -233,7 +21,9 @@ function metric(baseline: RawValue, current: RawValue) {
   return { baseline, current, delta, percentChange: percent !== null && Number.isFinite(percent) ? percent : null };
 }
 
-function compareObservation(
+type SnapshotContext = ImportedSnapshot["pages"][0]["response"]["context"];
+
+export function compareObservation(
   baseline: Evidence | undefined,
   current: Evidence | undefined,
   maxRows: number,

package/src/api/crawl.ts

@@ -0,0 +1,53 @@
+import { aggregate, capture, type Evidence } from "./evidence.js";
+import { crawlSite } from "../web/site-graph.js";
+import type { SiteConfig } from "./schema.js";
+import type { Executor } from "./execute.js";
+
+type Input = {
+  config: SiteConfig;
+  maxPages: number;
+  maxDepth: number;
+  maxLinks: number;
+  includeQuery: boolean;
+  inspectLimit: number;
+};
+export async function crawl(input: Input, run: Executor): Promise<Evidence> {
+  const { config } = input;
+  const request = {
+    site: config.site,
+    seeds: config.pages,
+    sitemap: config.sitemap,
+    maxPages: input.maxPages,
+    maxDepth: input.maxDepth,
+    maxLinks: input.maxLinks,
+    includeQuery: input.includeQuery,
+  };
+  const graph = await capture("web", "site-graph", config.site, request, () => crawlSite(request));
+  graph.name = "crawl.graph";
+  const data = graph.pages[0]?.response as Awaited<ReturnType<typeof crawlSite>> | undefined;
+  if (data && !data.complete) graph.status = "partial";
+  const observations = [graph];
+  const urls =
+    data?.pages
+      .filter((p) => p.status === 200 && p.contentType?.toLowerCase().includes("text/html"))
+      .slice(0, input.inspectLimit)
+      .map((p) => p.url) ?? [];
+  if (config.gscSite)
+    for (const url of urls)
+      observations.push({
+        ...(await run({ operation: "gsc.inspect", site: config.gscSite, url })),
+        name: `gsc.inspect:${url}`,
+      });
+  const result = aggregate("crawl", config.site, input, observations);
+  Object.assign(result.pages[0].response as object, {
+    context: config.context,
+    indexingSample: {
+      selected: config.gscSite ? urls : [],
+      limit: input.inspectLimit,
+      available: Boolean(config.gscSite),
+      meaning:
+        "Stored Google state for selected fetched HTML pages only; not a site indexing count. Missing inspection is unknown.",
+    },
+  });
+  return result;
+}

package/src/api/evaluate-change.ts

@@ -0,0 +1,189 @@
+import type { ChangeRecord } from "./change-record.js";
+import { compareObservation } from "./compare-snapshots.js";
+import { capture, type Evidence } from "./evidence.js";
+import type { ImportedSnapshot } from "./evidence-schema.js";
+import { canonical, normalizeReport, requireSame, Incompatible } from "./report-table.js";
+import { configSchema, gaRequestSchema, gscRequestSchema } from "./schema.js";
+import { snapshotOperations, observationName } from "./snapshot.js";
+import { normalizeGaProperty } from "../providers/ga.js";
+import { RequestError } from "../shared/http.js";
+
+export function localDay(at: string, timeZone: string): string {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(at));
+  const value = (name: string) => parts.find((p) => p.type === name)!.value;
+  return `${value("year")}-${value("month")}-${value("day")}`;
+}
+function scope(provider: string, request: unknown) {
+  if (provider === "ga") {
+    const { offset: _offset, limit: _limit, returnPropertyQuota: _quota, ...rest } = gaRequestSchema.parse(request);
+    return rest;
+  }
+  const { startRow: _offset, rowLimit: _limit, ...rest } = gscRequestSchema.parse(request);
+  return rest;
+}
+export function boundReport(snapshot: ImportedSnapshot, name: string) {
+  const { context, observations } = snapshot.pages[0].response;
+  const config = configSchema.parse(context.config);
+  const expected = snapshotOperations(config, context.requestedDates.startDate, context.requestedDates.endDate, 1).find(
+    (op) => observationName(op) === name,
+  );
+  const observation = observations.find((o) => o.name === name);
+  if (!expected || !["ga.report", "gsc.report"].includes(expected.operation))
+    throw new Incompatible("Not a configured snapshot report.");
+  if (!observation || observation.status === "error" || !observation.pages.length)
+    throw new Incompatible("Report unavailable; absence is not zero.");
+  const provider = expected.operation === "ga.report" ? "ga" : "gsc";
+  const target =
+    expected.operation === "ga.report"
+      ? normalizeGaProperty(expected.property)
+      : expected.operation === "gsc.report"
+        ? expected.site
+        : "";
+  if (observation.provider !== provider || observation.operation !== "report" || observation.target !== target)
+    throw new Incompatible("Report identity does not match configured provider/property.");
+  if (expected.operation !== "ga.report" && expected.operation !== "gsc.report")
+    throw new Incompatible("Unsupported report.");
+  for (const page of observation.pages)
+    requireSame(
+      scope(provider, page.request),
+      scope(provider, expected.request),
+      "Report request differs from configured scope.",
+    );
+  return { observation, report: normalizeReport(observation, context) };
+}
+export const fingerprint = (value: unknown) => Bun.CryptoHasher.hash("sha256", canonical(value), "hex");
+
+export async function evaluateChange(
+  record: ChangeRecord,
+  baseline: ImportedSnapshot,
+  current: ImportedSnapshot | undefined,
+  maxRows: number,
+): Promise<Evidence> {
+  if (baseline.target !== record.site || (current && current.target !== record.site))
+    throw new RequestError("Change record and snapshots must identify the same exact site", null, "invalid_input");
+  const before = baseline.pages[0].response;
+  const after = current?.pages[0].response;
+  const names = [
+    ...new Set(
+      [...before.observations, ...(after?.observations ?? [])]
+        .filter((o) => o.operation === "report" && ["gsc", "ga"].includes(o.provider))
+        .map((o) => o.name),
+    ),
+  ].sort();
+  const result = await capture(
+    "pagesight",
+    "change.evaluate",
+    record.site,
+    {
+      recordSha256: fingerprint(record),
+      baselineSha256: fingerprint(baseline),
+      currentSha256: current ? fingerprint(current) : null,
+      maxRows,
+    },
+    async () => {
+      const observations = names.map((name) => {
+        try {
+          const a = boundReport(baseline, name);
+          const timezone = (a.report.semantics as { timezone: string }).timezone;
+          const deploymentDay = localDay(record.deployedAt, timezone);
+          if (a.report.end >= deploymentDay)
+            throw new Incompatible("Baseline must end before the deployment day in this report's timezone.");
+          if (!current || !after)
+            return {
+              name,
+              status: "pending",
+              reason: "After snapshot not supplied; no outcome is available.",
+              timezone,
+              deploymentDay,
+            };
+          const b = boundReport(current, name);
+          if (b.report.start <= deploymentDay)
+            throw new Incompatible("After period must start after the deployment day in this report's timezone.");
+          const identity = (snapshot: ImportedSnapshot) => {
+            const config = configSchema.parse(snapshot.pages[0].response.context.config);
+            return {
+              site: config.site,
+              gscSite: config.gscSite,
+              gaProperty: config.gaProperty ? normalizeGaProperty(config.gaProperty) : null,
+              productionHostname: config.productionHostname,
+            };
+          };
+          requireSame(
+            identity(baseline),
+            identity(current),
+            "Configured site, provider identity or production hostname changed.",
+          );
+          if (
+            a.observation.provider === "ga" &&
+            record.measurementChanges.some((change) => {
+              const day = localDay(change.at, timezone);
+              return day >= a.report.start && day <= b.report.end;
+            })
+          )
+            throw new Incompatible(
+              "A declared measurement change intersects the combined periods; GA deltas are withheld.",
+            );
+          return {
+            ...compareObservation(a.observation, b.observation, maxRows, before.context, after.context),
+            timezone,
+            deploymentDay,
+            gapDays: (Date.parse(b.report.start) - Date.parse(a.report.end)) / 86400000 - 1,
+            weekdays: {
+              baselineStart: new Date(a.report.start).getUTCDay(),
+              currentStart: new Date(b.report.start).getUTCDay(),
+            },
+          };
+        } catch (error) {
+          return {
+            name,
+            status: "incompatible",
+            reason:
+              error instanceof Incompatible
+                ? error.message
+                : "Unsupported report or reporting timezone; no delta calculated.",
+          };
+        }
+      });
+      return {
+        evaluationVersion: 1,
+        record,
+        recordVerification: "User-supplied deployment and change context, not independently verified",
+        scope: "Original configured snapshot reports; affectedUrls are annotations and do not filter report rows",
+        state: !current
+          ? observations.some((o) => o.status === "pending")
+            ? "pending"
+            : "unavailable"
+          : observations.some((o) => ["compared", "limited"].includes(o.status))
+            ? "descriptive"
+            : "unavailable",
+        observations,
+        confounded: record.overlappingChanges.length > 0,
+        contextChanged: Boolean(
+          after &&
+          canonical(configSchema.parse(before.context.config)) !== canonical(configSchema.parse(after.context.config)),
+        ),
+        limitations: [
+          "Cloudflare, Bing, crawl graphs, HTML, sitemaps and inspection evidence are unsupported; no cross-provider funnel is calculated.",
+          "Declared overlapping changes confound attribution. Configuration-context changes remain visible and can alter event interpretation.",
+          "Descriptive comparison only. This does not establish causality, statistical significance or the change's effect on rankings.",
+          "Deployment day is excluded in each report's timezone. Equal windows can still differ in weekdays, seasonality, demand or search-system changes.",
+          "Only declared measurement and overlapping changes are known. An empty list is not proof that no other changes occurred.",
+          "Affected URLs do not change property, hostname, channel or row scope. Missing rows remain unknown, never zero.",
+          "Collected timestamps do not prove immutable historical data; source hashes identify the supplied artifacts, not their authenticity.",
+        ],
+      };
+    },
+  );
+  const data = result.pages[0]?.response as { observations: Array<{ status: string }> } | undefined;
+  if (
+    result.status === "ok" &&
+    (!current || !data?.observations.length || data.observations.some((o) => o.status !== "compared"))
+  )
+    result.status = "partial";
+  return result;
+}

package/src/api/execute.ts

@@ -1,3 +1,14 @@
+import { verifyRender } from "./verify-render.js";
+import { followupChanges } from "./followup-changes.js";
+import { cloudflareAudit } from "./cloudflare.js";
+
+import { evaluateChange } from "./evaluate-change.js";
+import { crawl } from "./crawl.js";
+import { technicalChanges } from "./technical-changes.js";
+import { investigate } from "./investigation.js";
+import { assessSnapshot } from "./assessment.js";
+import { opportunities } from "./opportunities.js";
+import { gaRealtime } from "./ga-realtime.js";
 import { importUiFindings } from "./ui-findings.js";
 import { doctor } from "./doctor.js";
 import { ZodError } from "zod";
@@ -31,6 +42,12 @@ export async function execute(input: unknown): Promise<Evidence> {
       "invalid_input",
     );
   }
+  if (
+    op.operation === "page.verify" &&
+    op.navigation &&
+    new URL(op.navigation.fromUrl).origin !== new URL(op.url).origin
+  )
+    throw new RequestError("Navigation source must share the target origin", null, "invalid_input");
   const result = await dispatch(op);
   if (op.operation.startsWith("ga.")) result.credential = await gaCredentialInfo();
   if (op.operation.startsWith("bing."))
@@ -45,6 +62,29 @@ export async function execute(input: unknown): Promise<Evidence> {
 
 async function dispatch(op: ParsedOperation): Promise<Evidence> {
   switch (op.operation) {
+    case "page.verify":
+      return verifyRender(op);
+    case "cloudflare.audit":
+      return cloudflareAudit(op);
+
+    case "change.followup":
+      return followupChanges(op.experiments, op.asOf ?? new Date().toISOString(), op.lagDays);
+    case "change.evaluate":
+      return evaluateChange(op.record, op.baseline, op.current, op.maxRows);
+    case "crawl":
+      return crawl(op, execute);
+    case "technical.compare":
+      return technicalChanges(op.baseline, op.current);
+    case "investigate":
+      return investigate(op, execute);
+    case "opportunities":
+      return opportunities(op.snapshot, {
+        minImpressions: op.minImpressions,
+        maxClicks: op.maxClicks,
+        maxRows: op.maxRows,
+      });
+    case "assess":
+      return assessSnapshot(op.snapshot, op.maxRows);
     case "evidence.import":
       return importUiFindings(op.document);
     case "compare":
@@ -109,6 +149,8 @@ async function dispatch(op: ParsedOperation): Promise<Evidence> {
           "Configured key events are not necessarily validated product outcomes; inspect event names. Check nextPageToken.",
         ],
       );
+    case "ga.realtime":
+      return gaRealtime(op.property, op.request);
     case "ga.report":
       return gaReport(op.property, op.request, op.maxPages);
     case "page":