@kirrosh/zond 0.26.1 → 0.27.0

package/src/core/runner/types.ts

@@ -1,94 +0,0 @@
-export type StepStatus = "pass" | "fail" | "skip" | "error";
-
-export interface HttpRequest {
-  method: string;
-  url: string;
-  headers: Record<string, string>;
-  body?: string;
-  formData?: FormData;
-}
-
-export interface HttpResponse {
-  status: number;
-  headers: Record<string, string>;
-  body: string;
-  body_parsed?: unknown;
-  duration_ms: number;
-  /** TASK-144: number of network-level retries that preceded this response.
-   *  0 when the request succeeded on the first attempt. */
-  network_retry_count?: number;
-}
-
-/**
- * `kind` lets the UI surface the assertion that matches the test's stated
- * intent (primary) ahead of OpenAPI schema noise (schema) and housekeeping
- * checks like duration/header asserts (auxiliary). Optional for backwards
- * compatibility — older runs render as `primary` by default.
- */
-export type AssertionKind = "primary" | "schema" | "auxiliary";
-
-export interface AssertionResult {
-  field: string;
-  rule: string;
-  passed: boolean;
-  actual: unknown;
-  expected: unknown;
-  kind?: AssertionKind;
-}
-
-export interface StepResult {
-  name: string;
-  status: StepStatus;
-  duration_ms: number;
-  request: HttpRequest;
-  response?: HttpResponse;
-  assertions: AssertionResult[];
-  captures: Record<string, unknown>;
-  error?: string;
-  provenance?: import("../parser/types.ts").SourceMetadata | null;
-  /** TASK-101: classification of why this failure happened — definitely_bug,
-   *  likely_bug, quirk, env_issue. `null` for passed/skipped/unclassifiable. */
-  failure_class?: import("../diagnostics/failure-class.ts").FailureClass | null;
-  failure_class_reason?: string | null;
-  /** TASK-102: JSON Pointer into the OpenAPI doc + frozen excerpt of the
-   *  schema at that pointer. Captured at run time so later spec edits don't
-   *  rewrite history. `null` for manual YAML or when spec isn't available. */
-  spec_pointer?: string | null;
-  spec_excerpt?: string | null;
-  /** TASK-144: how many network-level retries the http-client performed
-   *  before this step settled. Omitted (or 0) when no retry was needed.
-   *  Surfaced in the JSON report so flaky-network steps are visible. */
-  network_retry?: number;
-  /** ARV-157: summary of `--validate-schema` outcome for this step. Present
-   *  only when the runner had a schema validator attached AND a JSON body
-   *  was returned (so consumers can distinguish "no drift" from "never
-   *  validated"). Granular failures still live in `assertions[]` with
-   *  `kind: "schema"`; this block is the at-a-glance shape skill docs
-   *  describe and JSON-report consumers grep for. */
-  schema_validation?: {
-    result: "PASS" | "FAIL" | "no-endpoint" | "no-schema";
-    matched_endpoint: { method: string; path: string } | null;
-    matched_response_status: string | null;
-    error_count: number;
-  };
-}
-
-export interface TestRunResult {
-  suite_name: string;
-  suite_tags?: string[];
-  suite_description?: string;
-  suite_file?: string;
-  started_at: string;
-  finished_at: string;
-  total: number;
-  passed: number;
-  failed: number;
-  skipped: number;
-  /** ARV-318: steps whose status is "error" (couldn't execute — env_issue,
-   *  network, etc.). Previously counted in `total` but in none of
-   *  passed/failed/skipped, so `total === passed+failed+skipped` silently
-   *  broke and error steps reconciled into no bucket. Optional for back-compat
-   *  with older result literals; the runner always sets it. */
-  errored?: number;
-  steps: StepResult[];
-}

package/src/core/secrets/registry.ts

@@ -1,164 +0,0 @@
-/**
- * SecretRegistry — runtime registry of secret values + sanitizer
- * (TASK-166, m-10).
- *
- * The registry is the single point that knows "this string is a secret;
- * if you see it anywhere in a request URL, body, response, log line, or
- * exporter, replace it with `<redacted:<var-name>>`". Every persisted
- * artifact path (DB-write — TASK-167, exporters — TASK-168) calls
- * `redact()` / `redactObject()` before writing, so the user can ship a
- * digest / HTML report without scrubbing tokens by hand.
- *
- * Design rules:
- *   - Exact-match only — no heuristics ("looks like a JWT", "starts with
- *     `sk_`"). False positives are worse than false negatives here.
- *   - Minimum length 8 — protects against `auth_token: ""` or `id: 1`
- *     turning every "1" in the report into `<redacted>`.
- *   - One marker format documented in one place: `<redacted:<name>>`.
- *   - `setEnabled(false)` returns a no-op redactor for `--no-redact` (local
- *     debug). Default is enabled.
- *
- * Marker format: `<redacted:auth_token>` — the name comes from the
- * variable that registered the value (e.g. `.env.yaml` key, `--env` flag,
- * `.secrets.yaml` future entry). Anything that opens a redacted artifact
- * sees the variable name and knows where to look it up locally.
- */
-
-/** Minimum length below which a registered value is silently ignored. */
-export const MIN_SECRET_LENGTH = 8;
-
-const REDACTED_MARKER_RE = /<redacted:[a-zA-Z0-9_.-]+>/;
-
-export interface SecretEntry {
-  name: string;
-  value: string;
-}
-
-export class SecretRegistry {
-  /** value → name. We keep map keyed by *value* so a single redact pass
-   *  iterates the unique values rather than all registrations. Two names
-   *  registering the same value collapse to one entry — the most recent
-   *  wins. */
-  private byValue = new Map<string, string>();
-  private enabled = true;
-
-  register(name: string, value: unknown): void {
-    if (typeof value !== "string") return;
-    if (value.length < MIN_SECRET_LENGTH) return;
-    this.byValue.set(value, name);
-  }
-
-  /**
-   * Bulk-register every string value in a flat object. Used by
-   * `.env.yaml` / `.secrets.yaml` loaders so we don't have to know in
-   * advance which keys are sensitive. The variable name carried into the
-   * marker is the object key.
-   */
-  registerAll(entries: Record<string, unknown> | undefined | null): void {
-    if (!entries) return;
-    for (const [k, v] of Object.entries(entries)) this.register(k, v);
-  }
-
-  /** Disable redaction (for `--no-redact` local debug). */
-  setEnabled(enabled: boolean): void {
-    this.enabled = enabled;
-  }
-
-  isEnabled(): boolean {
-    return this.enabled;
-  }
-
-  /** Names of every var that had a value registered. Stable diagnostic. */
-  redactedNames(): string[] {
-    return [...new Set(this.byValue.values())].sort();
-  }
-
-  hasSecrets(): boolean {
-    return this.byValue.size > 0;
-  }
-
-  /** Drop all registered secrets — used between test cases. */
-  clear(): void {
-    this.byValue.clear();
-  }
-
-  /**
-   * Replace every occurrence of a registered value in `text` with the
-   * marker `<redacted:<name>>`. Longest values first, so a token that
-   * happens to contain a shorter registered substring still ends up
-   * redacted as the more-specific match.
-   */
-  redact(text: string): string {
-    if (!this.enabled || this.byValue.size === 0) return text;
-    if (typeof text !== "string" || text.length === 0) return text;
-
-    let out = text;
-    for (const [value, name] of this.sortedEntries()) {
-      if (out.indexOf(value) === -1) continue;
-      out = out.split(value).join(`<redacted:${name}>`);
-    }
-    return out;
-  }
-
-  /**
-   * Deep-clone variant for arbitrary structured data (request/response
-   * bodies, header maps, JSON envelopes). Strings get redacted; numbers,
-   * booleans, null, Buffers stay as-is. Cycles are not expected on the
-   * artifact paths but we guard with `seen` to be safe.
-   */
-  redactObject<T>(obj: T): T {
-    if (!this.enabled || this.byValue.size === 0) return obj;
-    return this.deepRedact(obj, new WeakSet()) as T;
-  }
-
-  private sortedEntries(): Array<[string, string]> {
-    return [...this.byValue.entries()].sort((a, b) => b[0].length - a[0].length);
-  }
-
-  private deepRedact(node: unknown, seen: WeakSet<object>): unknown {
-    if (node == null) return node;
-    if (typeof node === "string") return this.redact(node);
-    if (typeof node !== "object") return node;
-    if (seen.has(node as object)) return node;
-    seen.add(node as object);
-
-    if (Array.isArray(node)) {
-      return node.map((v) => this.deepRedact(v, seen));
-    }
-    // Buffers / Uint8Array / Date — leave intact.
-    if (node instanceof Uint8Array || node instanceof Date) return node;
-
-    const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(node)) {
-      out[k] = this.deepRedact(v, seen);
-    }
-    return out;
-  }
-}
-
-/**
- * Process-wide registry. CLI commands populate it once after loading
- * `.env.yaml` / `.secrets.yaml`; library callers can pass their own
- * instance instead of touching this singleton in tests.
- */
-let globalRegistry: SecretRegistry | undefined;
-
-export function getSecretRegistry(): SecretRegistry {
-  if (!globalRegistry) globalRegistry = new SecretRegistry();
-  return globalRegistry;
-}
-
-/** Replace the global registry. Tests use this to reset state. */
-export function setSecretRegistry(reg: SecretRegistry): void {
-  globalRegistry = reg;
-}
-
-/** Convenience: redact a string via the global registry. */
-export function redact(text: string): string {
-  return getSecretRegistry().redact(text);
-}
-
-/** Convenience: redact a nested object via the global registry. */
-export function redactObject<T>(value: T): T {
-  return getSecretRegistry().redactObject(value);
-}

package/src/core/secrets/secrets-file.ts

@@ -1,115 +0,0 @@
-/**
- * `.secrets.yaml` — gitignored flat YAML file holding raw secret values
- * for an API (TASK-170, m-10). Companion to `.env.yaml` which references
- * keys here via `@secret:<name>`.
- *
- *     # apis/<name>/.secrets.yaml (NEVER committed)
- *     auth_token: "tok_..."
- *     dsn: "https://...@example.com/..."
- *
- *     # apis/<name>/.env.yaml (committable)
- *     auth_token: "@secret:auth_token"
- *     base_url: "https://api.example.com"
- *
- * Mental model: anything in `.secrets.yaml` is registered with the
- * `SecretRegistry` at load-time, so it gets redacted in any persisted
- * artifact (DB, exporters, digests). Anything in `.env.yaml` is plain.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { getSecretRegistry } from "./registry.ts";
-
-const SECRETS_FILENAME = ".secrets.yaml";
-const SECRET_REF_RE = /^@secret:([A-Za-z_][A-Za-z0-9_.-]*)$/;
-
-/** Resolved contents of a `.secrets.yaml`. */
-export interface SecretsFile {
-  filePath: string;
-  values: Record<string, string>;
-}
-
-/**
- * Read `.secrets.yaml` from a directory, register every value with the
- * global SecretRegistry, and return the parsed map. Returns `null` when
- * the file is absent — callers should treat that as "no secrets to
- * register" rather than a failure.
- */
-export function loadSecretsFile(dir: string): SecretsFile | null {
-  const filePath = join(dir, SECRETS_FILENAME);
-  if (!existsSync(filePath)) return null;
-  const text = readFileSync(filePath, "utf-8");
-  let parsed: unknown;
-  try {
-    parsed = (Bun as any).YAML.parse(text);
-  } catch (err) {
-    throw new Error(`Failed to parse ${filePath}: ${(err as Error).message}`);
-  }
-  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`${filePath} must contain a flat YAML object of key: "value" entries`);
-  }
-
-  const values: Record<string, string> = {};
-  for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
-    if (v == null) continue;                 // empty placeholder — skip
-    if (typeof v === "object") {
-      throw new Error(
-        `${filePath}: nested values are not supported (key "${k}"). ` +
-        `.secrets.yaml is intentionally flat — keep one level of key/value pairs.`,
-      );
-    }
-    values[k] = String(v);
-  }
-
-  const reg = getSecretRegistry();
-  reg.registerAll(values);
-
-  return { filePath, values };
-}
-
-/**
- * Walk up a directory chain to find the first `.secrets.yaml` and load
- * it. Used by the env loader so a single secrets file at the API root
- * (`apis/<name>/.secrets.yaml`) is picked up regardless of which
- * subdirectory `zond run` was invoked from.
- */
-export function loadSecretsFromAncestor(start: string, stopAt?: string): SecretsFile | null {
-  let dir = start;
-  for (let i = 0; i < 8; i++) {
-    const file = loadSecretsFile(dir);
-    if (file) return file;
-    if (stopAt && dir === stopAt) return null;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-  return null;
-}
-
-/**
- * Resolve any `@secret:<name>` reference inside an env object against
- * the values from `secrets`. Throws when a referenced name is missing
- * (fail-loud).
- */
-export function resolveSecretRefs(
-  envValues: Record<string, string>,
-  secrets: SecretsFile | null,
-  filePath: string,
-): Record<string, string> {
-  const out: Record<string, string> = { ...envValues };
-  for (const [k, v] of Object.entries(out)) {
-    const m = typeof v === "string" ? v.match(SECRET_REF_RE) : null;
-    if (!m) continue;
-    const refName = m[1]!;
-    const value = secrets?.values[refName];
-    if (value == null) {
-      const where = secrets ? secrets.filePath : `${dirname(filePath)}/${SECRETS_FILENAME}`;
-      throw new Error(
-        `${filePath}: key "${k}" references @secret:${refName} but no such entry exists in ${where}. ` +
-        `Add \`${refName}: "<value>"\` to ${where} (or remove the @secret: prefix to use a literal value).`,
-      );
-    }
-    out[k] = value;
-  }
-  return out;
-}

package/src/core/selectors/operation-filter.ts

@@ -1,144 +0,0 @@
-/**
- * Unified operation filter (m-15 ARV-9).
- *
- * Parses `--include`/`--exclude` filter specs in a single grammar so
- * `zond run`, `zond checks`, `zond probe`, and `zond generate` all
- * accept the same `<selector>:<value>` strings without each command
- * inventing its own flag set.
- *
- * Grammar:
- *
- *   <spec> := <selector> ":" <value>
- *   <selector> := "path" | "method" | "tag" | "operation-id" | "operationId"
- *   <value>:
- *     path        — POSIX-style regex matched against `op.path`
- *     method      — comma-separated HTTP methods, case-insensitive
- *     tag         — comma-separated tag names, exact match (case-sensitive)
- *     operation-id — POSIX-style regex matched against `op.operationId`
- *
- * Semantics:
- *   - Multiple `--include` flags combine with OR (op passes if it
- *     matches *any* include); when no include is given, every op is
- *     considered included.
- *   - `--exclude` always removes a match — combines with OR too.
- *   - Excludes are evaluated *after* includes.
- *
- * Errors are returned in a `errors[]` array on the compile result so
- * the CLI can surface a friendly multi-line message instead of a
- * stack trace (AC #4).
- */
-import type { EndpointInfo } from "../generator/types.ts";
-
-export type SelectorKind = "path" | "method" | "tag" | "operation-id";
-
-const SELECTOR_ALIASES: Record<string, SelectorKind> = {
-  path: "path",
-  method: "method",
-  tag: "tag",
-  "operation-id": "operation-id",
-  operationid: "operation-id",
-  operation_id: "operation-id",
-};
-
-export interface ParsedSelector {
-  kind: SelectorKind;
-  raw: string;
-  /** Regex form for `path` and `operation-id` selectors. */
-  pattern?: RegExp;
-  /** Lowercase token list for `method`/`tag` selectors. */
-  values?: string[];
-}
-
-export type ParseResult =
-  | { ok: true; selector: ParsedSelector }
-  | { ok: false; error: string };
-
-export function parseFilterSpec(spec: string): ParseResult {
-  const idx = spec.indexOf(":");
-  if (idx <= 0) {
-    return { ok: false, error: `Filter "${spec}": expected "<selector>:<value>" (e.g. path:/users/.*)` };
-  }
-  const head = spec.slice(0, idx).trim().toLowerCase();
-  const tail = spec.slice(idx + 1).trim();
-  if (tail.length === 0) {
-    return { ok: false, error: `Filter "${spec}": value is empty after "${head}:"` };
-  }
-  const kind = SELECTOR_ALIASES[head];
-  if (!kind) {
-    const known = Object.keys(SELECTOR_ALIASES).filter((k) => k === SELECTOR_ALIASES[k]).join(", ");
-    return { ok: false, error: `Filter "${spec}": unknown selector "${head}". Known: ${known}` };
-  }
-
-  if (kind === "path" || kind === "operation-id") {
-    let pattern: RegExp;
-    try {
-      pattern = new RegExp(tail);
-    } catch (err) {
-      return { ok: false, error: `Filter "${spec}": invalid regex — ${(err as Error).message}` };
-    }
-    return { ok: true, selector: { kind, raw: spec, pattern } };
-  }
-
-  // method / tag — comma-separated.
-  const values = tail.split(",").map((v) => v.trim()).filter(Boolean);
-  if (values.length === 0) {
-    return { ok: false, error: `Filter "${spec}": no values after "${head}:"` };
-  }
-  if (kind === "method") {
-    return { ok: true, selector: { kind, raw: spec, values: values.map((v) => v.toUpperCase()) } };
-  }
-  return { ok: true, selector: { kind, raw: spec, values } };
-}
-
-function selectorMatches(sel: ParsedSelector, op: EndpointInfo): boolean {
-  switch (sel.kind) {
-    case "path":
-      return sel.pattern!.test(op.path);
-    case "method":
-      return sel.values!.includes(op.method.toUpperCase());
-    case "tag":
-      return op.tags.some((t) => sel.values!.includes(t));
-    case "operation-id":
-      return op.operationId !== undefined && sel.pattern!.test(op.operationId);
-  }
-}
-
-export interface CompileFilterOptions {
-  includes?: string[];
-  excludes?: string[];
-}
-
-export interface CompiledFilter {
-  filter: (op: EndpointInfo) => boolean;
-  errors: string[];
-  /** Parsed selectors — handy for debug `--explain` output. */
-  parsed: { includes: ParsedSelector[]; excludes: ParsedSelector[] };
-}
-
-export function compileOperationFilter(opts: CompileFilterOptions = {}): CompiledFilter {
-  const errors: string[] = [];
-  const includes: ParsedSelector[] = [];
-  const excludes: ParsedSelector[] = [];
-  for (const raw of opts.includes ?? []) {
-    const r = parseFilterSpec(raw);
-    if (r.ok) includes.push(r.selector);
-    else errors.push(r.error);
-  }
-  for (const raw of opts.excludes ?? []) {
-    const r = parseFilterSpec(raw);
-    if (r.ok) excludes.push(r.selector);
-    else errors.push(r.error);
-  }
-  const filter = (op: EndpointInfo): boolean => {
-    if (includes.length > 0) {
-      const passInclude = includes.some((s) => selectorMatches(s, op));
-      if (!passInclude) return false;
-    }
-    for (const s of excludes) {
-      if (selectorMatches(s, op)) return false;
-    }
-    return true;
-  };
-  return { filter, errors, parsed: { includes, excludes } };
-}
-