@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/exporter/case-study/index.ts

@@ -0,0 +1,270 @@
+import type { RunRecord, StoredStepResult } from "../../../db/queries.ts";
+import type { FailureClass } from "../../diagnostics/failure-class.ts";
+import { buildCurl } from "../curl.ts";
+
+export interface CaseStudyOptions {
+  result: StoredStepResult;
+  run: RunRecord;
+  /** Pulled from OpenAPI `info.title` if available. */
+  specTitle?: string | null;
+  specVersion?: string | null;
+  zondVersion: string;
+  /** TASK-164 (m-9 P8): cap response/request bodies to N bytes. 0 or
+   *  unset = no cap. The CLI wrapper defaults to 8 KB. */
+  bodyCapBytes?: number;
+  /** ARV-106/107: short registry slug (`--api <name>`). When set, the
+   *  case-study renders a `zond request --api <name>` alternative below the
+   *  curl repro and falls back to it for the "API" field when specTitle is
+   *  null. */
+  apiName?: string | null;
+  /** ARV-107: loaded OpenAPI spec. When provided, the renderer auto-extracts
+   *  the relevant operation block for the "What the spec says" section instead
+   *  of leaving the `<TODO: paste …>` placeholder. */
+  specDoc?: OpenApiDocLike | null;
+}
+
+/** Minimal shape we touch from an OpenAPI spec — keeps this module
+ *  framework-free. */
+interface OpenApiDocLike {
+  paths?: Record<string, Record<string, unknown>> | null;
+  components?: { schemas?: Record<string, unknown> } | null;
+}
+
+function capBody(content: string | null | undefined, capBytes: number | undefined): string | null {
+  if (!content) return content ?? null;
+  if (!capBytes || capBytes <= 0 || content.length <= capBytes) return content;
+  const dropped = content.length - capBytes;
+  return `${content.slice(0, capBytes)}\n[truncated ${dropped} bytes; first ${capBytes} shown; full body in run DB]`;
+}
+
+const CLASS_HUMAN: Record<FailureClass, string> = {
+  definitely_bug: "definitely_bug",
+  likely_bug: "likely_bug",
+  quirk: "quirk",
+  env_issue: "env_issue",
+  cascade: "cascade",
+};
+
+const TODO = (hint: string): string => `<TODO: ${hint}>`;
+
+function tryPretty(s: string | null | undefined): string {
+  if (!s) return "";
+  try {
+    return JSON.stringify(JSON.parse(s), null, 2);
+  } catch {
+    return s;
+  }
+}
+
+function extractPath(url: string | null): string {
+  if (!url) return TODO("path");
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url;
+  }
+}
+
+function shortDescription(result: StoredStepResult): string {
+  if (result.failure_class_reason) return result.failure_class_reason;
+  if (result.error_message) return result.error_message;
+  if (result.response_status != null && result.response_status >= 500) {
+    return `unexpected ${result.response_status} from server`;
+  }
+  if (result.response_status != null && result.response_status >= 400) {
+    return `unexpected ${result.response_status} response`;
+  }
+  return TODO("one-line summary of the failure");
+}
+
+function tldrLine(result: StoredStepResult): string {
+  switch (result.failure_class) {
+    case "definitely_bug":
+      return "Backend bug — endpoint contradicts its own contract.";
+    case "likely_bug":
+      return "Suspicious behaviour — contract leaves it ambiguous, but the response is hard to defend.";
+    case "quirk":
+      return "Documented quirk worth flagging in onboarding docs / a spec PR.";
+    case "env_issue":
+      return "Environment / fixture issue — not an API bug, but blocks the test from running.";
+    default:
+      return TODO("one-sentence takeaway");
+  }
+}
+
+function whyItMatters(result: StoredStepResult): string {
+  switch (result.failure_class) {
+    case "definitely_bug":
+    case "likely_bug": {
+      const reason = result.failure_class_reason ?? TODO("explain why this is a bug — what user-visible impact?");
+      const failedAsserts = result.assertions.filter((a) => !a.passed);
+      const detail = failedAsserts.length > 0
+        ? failedAsserts
+            .map((a) => `- \`${a.rule}\` at \`${a.field}\`: expected \`${JSON.stringify(a.expected)}\`, got \`${JSON.stringify(a.actual)}\``)
+            .join("\n")
+        : "";
+      return detail ? `${reason}\n\nFailed assertions:\n\n${detail}` : reason;
+    }
+    case "quirk":
+      return `Spec implies one thing, server does another:\n\n- Expected: ${TODO("what the spec promised")}\n- Actual: ${TODO("what the server did")}`;
+    case "env_issue":
+      return result.failure_class_reason ?? TODO("describe what the test setup needed and didn't get");
+    default:
+      return TODO("explain why this finding matters to the reader");
+  }
+}
+
+function howZondFoundIt(result: StoredStepResult): string {
+  const prov = result.provenance;
+  if (!prov || prov.type === "manual") {
+    return `Manually authored test case: \`${result.suite_name}\` → \`${result.test_name}\`.`;
+  }
+  const generator = prov.generator ?? "openapi-generated";
+  const lines: string[] = [];
+  lines.push(`Generated by \`${generator}\` (${prov.type ?? "unknown"}).`);
+  if (prov.endpoint) lines.push(`Targeted endpoint: \`${prov.endpoint}\`.`);
+  if (prov.response_branch) lines.push(`Asserted response branch: \`${prov.response_branch}\`.`);
+  lines.push(`Suite: \`${result.suite_name}\` → \`${result.test_name}\`.`);
+  return lines.join("\n");
+}
+
+function matchSpecOperation(
+  spec: OpenApiDocLike,
+  method: string,
+  concretePath: string,
+): { template: string; operation: Record<string, unknown> } | null {
+  const paths = spec.paths;
+  if (!paths) return null;
+  const want = method.toLowerCase();
+  // Prefer an exact path hit (no path-params), then fall back to a regex-based
+  // template match. Both passes ignore query strings.
+  const cleanPath = concretePath.split("?")[0] ?? concretePath;
+  if (paths[cleanPath]) {
+    const op = (paths[cleanPath] as Record<string, unknown>)[want];
+    if (op && typeof op === "object") return { template: cleanPath, operation: op as Record<string, unknown> };
+  }
+  for (const [template, item] of Object.entries(paths)) {
+    if (template === cleanPath) continue;
+    if (!template.includes("{")) continue;
+    const re = new RegExp("^" + template.replace(/\{[^}]+\}/g, "[^/]+") + "$");
+    if (!re.test(cleanPath)) continue;
+    const op = (item as Record<string, unknown>)[want];
+    if (op && typeof op === "object") return { template, operation: op as Record<string, unknown> };
+  }
+  return null;
+}
+
+function specSnippet(result: StoredStepResult, specDoc?: OpenApiDocLike | null): string {
+  if (!result.spec_pointer && !result.spec_excerpt) {
+    // ARV-107: try to recover the operation slice from the loaded spec.
+    if (specDoc && result.request_method && result.request_url) {
+      const path = extractPath(result.request_url);
+      const match = matchSpecOperation(specDoc, result.request_method, path);
+      if (match) {
+        const ptr = `JSON pointer: \`#/paths/${match.template.replace(/\//g, "~1")}/${result.request_method.toLowerCase()}\`\n\n`;
+        return ptr + "```json\n" + JSON.stringify(match.operation, null, 2) + "\n```";
+      }
+    }
+    return TODO("paste the relevant slice of the OpenAPI spec");
+  }
+  const ptr = result.spec_pointer ? `JSON pointer: \`${result.spec_pointer}\`\n\n` : "";
+  const excerpt = result.spec_excerpt
+    ? "```json\n" + tryPretty(result.spec_excerpt) + "\n```"
+    : TODO("snippet not captured at run time");
+  return ptr + excerpt;
+}
+
+function provenanceLine(result: StoredStepResult): string {
+  const prov = result.provenance;
+  if (!prov) return `Test source: \`${result.suite_name}\` (no provenance metadata).`;
+  const parts: string[] = [];
+  if (prov.generator) parts.push(`generator \`${prov.generator}\``);
+  if (prov.spec) parts.push(`spec \`${prov.spec}\``);
+  if (prov.response_branch) parts.push(`branch \`${prov.response_branch}\``);
+  return parts.length > 0
+    ? `Provenance: ${parts.join(", ")}.`
+    : `Provenance: \`${prov.type ?? "unknown"}\`.`;
+}
+
+function buildZondRequestLine(apiName: string, result: StoredStepResult): string {
+  const method = (result.request_method ?? "GET").toUpperCase();
+  const path = extractPath(result.request_url);
+  const parts: string[] = [`zond request --api ${apiName} ${method} ${path}`];
+  if (result.request_body) {
+    const escaped = result.request_body.replace(/'/g, `'\\''`);
+    parts.push(`  --json '${escaped}'`);
+  }
+  return parts.join(" \\\n");
+}
+
+export function renderCaseStudy(opts: CaseStudyOptions): string {
+  const { result, run, specTitle, specVersion, zondVersion, apiName } = opts;
+  const method = (result.request_method ?? TODO("HTTP method")).toUpperCase();
+  const path = extractPath(result.request_url);
+  const fc = result.failure_class ? CLASS_HUMAN[result.failure_class] : TODO("classification");
+
+  // ARV-107: cascade — explicit spec title, then registry slug (`--api`), then
+  // collection-id breadcrumb, then unrecoverable.
+  const apiLine = specTitle
+    ? `${specTitle}${specVersion ? ` ${specVersion}` : ""}`
+    : apiName
+      ? apiName
+      : (run.collection_id != null ? TODO("API title — spec was not loadable at export time") : TODO("API name"));
+
+  const responseStatus = result.response_status != null ? String(result.response_status) : "no response";
+  const cappedBody = capBody(result.response_body, opts.bodyCapBytes);
+  const responseBody = cappedBody
+    ? "```json\n" + tryPretty(cappedBody) + "\n```"
+    : (result.error_message ? `Network/runtime error: \`${result.error_message}\`` : "_(empty body)_");
+
+  // ARV-106: prefer the `zond request` form when an api slug is known
+  // (skill anti-curl rule). The curl block stays as a copy-paste fallback for
+  // recipients without zond installed, with a redacted Authorization header.
+  const reproAlt = apiName
+    ? `\n\n_Or with zond:_\n\n\`\`\`bash\n${buildZondRequestLine(apiName, result)}\n\`\`\``
+    : "";
+
+  return `# ${method} ${path} — ${shortDescription(result)}
+
+## TL;DR
+
+- **What we found:** ${fc}
+- **What went wrong:** ${tldrLine(result)}
+- **Repro:** see below
+
+## Context
+
+- **API:** ${apiLine}
+- **Endpoint:** \`${method} ${path}\`
+- ${provenanceLine(result)}
+
+### What the spec says
+
+${specSnippet(result, opts.specDoc)}
+
+## Repro
+
+\`\`\`bash
+${buildCurl(result)}
+\`\`\`${reproAlt}
+
+## What happened
+
+- **Status:** ${responseStatus}
+- **Duration:** ${result.duration_ms} ms
+
+${responseBody}
+
+## Why it matters
+
+${whyItMatters(result)}
+
+## How zond found it
+
+${howZondFoundIt(result)}
+
+---
+
+_Generated by zond ${zondVersion} from run #${run.id} (result #${result.id})._
+`;
+}

package/src/core/exporter/curl.ts

@@ -0,0 +1,40 @@
+import type { StoredStepResult } from "../../db/queries.ts";
+
+export interface BuildCurlOptions {
+  /** "redacted" — emit `Authorization: Bearer <REDACTED>` placeholder so the
+   *  reader knows the original request was authenticated (ARV-106). "omit" —
+   *  legacy behaviour. Defaults to "redacted". */
+  authHeader?: "redacted" | "omit";
+}
+
+function isRemoteUrl(url: string | null | undefined): boolean {
+  if (!url) return false;
+  try {
+    const u = new URL(url);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+    const host = u.hostname.toLowerCase();
+    return host !== "localhost" && host !== "127.0.0.1" && host !== "::1" && host !== "0.0.0.0";
+  } catch {
+    return false;
+  }
+}
+
+/** Single-quote-wrapped curl, safe-ish for shells. */
+export function buildCurl(step: StoredStepResult, options: BuildCurlOptions = {}): string {
+  const parts: string[] = ["curl"];
+  const method = step.request_method?.toUpperCase();
+  if (method && method !== "GET") {
+    parts.push("-X", method);
+  }
+  const wantAuth = (options.authHeader ?? "redacted") === "redacted" && isRemoteUrl(step.request_url);
+  if (wantAuth) {
+    parts.push("-H", "'Authorization: Bearer <REDACTED — replace with your token>'");
+  }
+  if (step.request_body) {
+    const escaped = step.request_body.replace(/'/g, `'\\''`);
+    parts.push("-H", "'Content-Type: application/json'");
+    parts.push("-d", `'${escaped}'`);
+  }
+  parts.push(`'${step.request_url ?? ""}'`);
+  return parts.join(" ");
+}

package/src/core/exporter/exporter.ts

@@ -0,0 +1,48 @@
+/**
+ * Single sanitization seam for everything zond writes to disk or stdout.
+ *
+ * Background: m-10 (TASK-166..168) introduced a secrets registry and
+ * `redact()` helper. The first wave of work added `redact(...)` calls
+ * inside individual exporters and reporters, which means a new exporter
+ * is one missing call away from leaking a secret. TASK-186 collapses
+ * that risk: every exporter declares a pure `render()` and goes through
+ * the {@link runExporter} pipeline, which applies the sanitizer exactly
+ * once at the boundary.
+ *
+ * The interface is deliberately string-out only — every consumer
+ * (writeFile, console.log, HTTP body) accepts a string anyway.
+ */
+
+import { redact } from "../secrets/registry.ts";
+
+export interface Exporter<I, O = void> {
+  /** Stable identifier — used in logs and tests. */
+  readonly name: string;
+  /** Mime hint for the rendered payload. */
+  readonly mime: string;
+  /** Pure render — no I/O, no redaction. Receives caller-supplied opts. */
+  render(input: I, opts?: O): string;
+}
+
+/**
+ * Run an exporter's render through the sanitizer pipeline. This is the
+ * only place sanitization happens for exporter output — render() must
+ * NOT call `redact()` itself, and callers must NOT redact again on top.
+ *
+ * Sanitization is currently a single pass of {@link redact}; future
+ * sanitizer rules (e.g. identity scrubbing) will plug in here so every
+ * exporter inherits them automatically.
+ */
+export function runExporter<I, O>(exporter: Exporter<I, O>, input: I, opts?: O): string {
+  return applySanitizer(exporter.render(input, opts));
+}
+
+/**
+ * Sanitizer pipeline used by {@link runExporter}. Exposed for the
+ * handful of sites that build their payload outside the exporter
+ * interface (e.g. probe digests assembled inline) so they can opt into
+ * the same single-pass redaction without duplicating logic.
+ */
+export function applySanitizer(payload: string): string {
+  return redact(payload);
+}

package/src/core/exporter/html-report/escape.ts

@@ -0,0 +1,24 @@
+// Minimal HTML escaper for safe inlining of user-controlled strings
+// (request URLs, response bodies, error messages) into the single-file report.
+
+const HTML_ESCAPES: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+export function escapeHtml(input: string | null | undefined): string {
+  if (input == null) return "";
+  return String(input).replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch] ?? ch);
+}
+
+export function tryPrettyJson(s: string | null | undefined): string {
+  if (!s) return "";
+  try {
+    return JSON.stringify(JSON.parse(s), null, 2);
+  } catch {
+    return s;
+  }
+}