@kirrosh/zond 0.26.0 → 0.27.0

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

@@ -1,270 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-// 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;
-  }
-}