@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/severity/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Unified severity matrix (ARV-250, m-21 pivot).
+ *
+ * Single source of truth for severity classification across all
+ * finding-producing subsystems (lint, checks, probes). Replaces three
+ * divergent ladders (lint 3-tier, checks 4-tier, probes 4-tier).
+ *
+ * Principle: **no evidence — no high severity**. Severity reflects
+ * proven impact, not anomaly presence. CRITICAL exists in the type
+ * but is reserved for end-to-end exploit chains; producers without
+ * such chains must NOT emit it.
+ */
+
+export type Severity = "critical" | "high" | "medium" | "low" | "info";
+
+const SEVERITY_RANK: Record<Severity, number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  info: 4,
+};
+
+export function rankSeverity(s: Severity): number {
+  return SEVERITY_RANK[s];
+}
+
+/**
+ * Empty severity-bucket map. Use as starting tally; downstream code
+ * increments per finding.
+ */
+export function emptySeverityBuckets(): Record<Severity, number> {
+  return { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+}
+
+/**
+ * SARIF level mapping (sarif.ts previously hardcoded 4-tier; this
+ * keeps the same external semantics + adds 'info' → 'note').
+ */
+export function severityToSarifLevel(s: Severity): "error" | "warning" | "note" {
+  if (s === "critical" || s === "high") return "error";
+  if (s === "medium") return "warning";
+  return "note"; // low + info
+}
+
+/**
+ * Console glyph for severity. Stable per-glyph keeps fb-loop diff
+ * compares clean.
+ */
+export function severityGlyph(s: Severity): string {
+  switch (s) {
+    case "critical": return "🚨";
+    case "high":     return "🔴";
+    case "medium":   return "⚠️";
+    case "low":      return "ℹ️";
+    case "info":     return "·";
+  }
+}

package/src/core/spec/infer-schema.ts

@@ -0,0 +1,102 @@
+/**
+ * ARV-175: infer a JSON Schema (draft-07 subset) from a set of sample
+ * response bodies. Built-in, zero-dependency — quicktype/genson would each
+ * drag in a large dependency tree, which contradicts zond's dumb-tool /
+ * minimal-deps charter (see src/CLAUDE.md). The `--engine` flag keeps the
+ * seam open if a heavier engine is ever wanted, but `builtin` is the default
+ * and the only one wired.
+ *
+ * Strategy — structural union over the samples:
+ *   - primitives → { type }
+ *   - arrays     → { type: "array", items: <merge of every element> }
+ *   - objects    → { type: "object", properties, required }
+ *                  `required` = keys present in EVERY object sample (an
+ *                  intersection — a field missing from one sample is optional).
+ *   - mixed types across samples → { type: [sorted, unique] } (or a bare
+ *     type when they all agree). null folds into the type list so a
+ *     sometimes-null field reads as `["null","string"]`.
+ *
+ * Not a full inference engine: no format detection, no enum mining, no
+ * anyOf for heterogeneous array items beyond a type union. Good enough to
+ * seed `response_schema_conformance` on specs that declare no response
+ * schema, which is the whole point (ARV-175 goal).
+ */
+
+export type JsonSchema = Record<string, unknown>;
+
+type JsonType = "null" | "boolean" | "integer" | "number" | "string" | "array" | "object";
+
+function typeOf(v: unknown): JsonType {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  const t = typeof v;
+  if (t === "boolean") return "boolean";
+  if (t === "number") return Number.isInteger(v) ? "integer" : "number";
+  if (t === "string") return "string";
+  return "object";
+}
+
+/** Infer a schema from one or more samples of the same logical value. */
+export function inferSchema(samples: unknown[]): JsonSchema {
+  const nonEmpty = samples.filter((s) => s !== undefined);
+  if (nonEmpty.length === 0) return {};
+
+  const types = new Set<JsonType>();
+  for (const s of nonEmpty) types.add(typeOf(s));
+
+  // Object: merge properties across every object sample.
+  if (types.has("object")) {
+    const objSamples = nonEmpty.filter((s) => typeOf(s) === "object") as Array<Record<string, unknown>>;
+    const propSamples = new Map<string, unknown[]>();
+    for (const obj of objSamples) {
+      for (const [k, v] of Object.entries(obj)) {
+        if (!propSamples.has(k)) propSamples.set(k, []);
+        propSamples.get(k)!.push(v);
+      }
+    }
+    // required = keys present in ALL object samples (intersection).
+    const required = [...propSamples.keys()].filter(
+      (k) => objSamples.every((obj) => Object.prototype.hasOwnProperty.call(obj, k)),
+    );
+    const properties: JsonSchema = {};
+    for (const [k, vs] of propSamples) properties[k] = inferSchema(vs);
+
+    const schema: JsonSchema = { type: mergeType(types, "object") };
+    if (Object.keys(properties).length > 0) schema.properties = sortKeys(properties);
+    if (required.length > 0) schema.required = required.sort();
+    return schema;
+  }
+
+  // Array: items schema is the union of every element across every sample.
+  if (types.has("array")) {
+    const elements: unknown[] = [];
+    for (const s of nonEmpty) if (Array.isArray(s)) elements.push(...s);
+    const schema: JsonSchema = { type: mergeType(types, "array") };
+    if (elements.length > 0) schema.items = inferSchema(elements);
+    return schema;
+  }
+
+  // Primitives only.
+  return { type: mergeType(types) };
+}
+
+/** Collapse the observed type set into a single `type` value: a string when
+ *  they agree (preferring `primary` if given, e.g. object/array), otherwise a
+ *  sorted unique list. `integer`+`number` collapses to `number`. */
+function mergeType(types: Set<JsonType>, primary?: JsonType): string | string[] {
+  const t = new Set(types);
+  if (t.has("number") && t.has("integer")) t.delete("integer");
+  if (primary && t.size > 1) {
+    // Object/array with a stray null etc. — keep the structural type plus null.
+    const rest = [...t].filter((x) => x !== primary);
+    if (rest.length === 1 && rest[0] === "null") return [primary, "null"].sort();
+  }
+  const arr = [...t].sort();
+  return arr.length === 1 ? arr[0]! : arr;
+}
+
+function sortKeys(obj: JsonSchema): JsonSchema {
+  const out: JsonSchema = {};
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k];
+  return out;
+}

package/src/core/spec/layers.ts

@@ -0,0 +1,154 @@
+/**
+ * ARV-122 (m-19, blocker-m-18): layered spec model.
+ *
+ * Today two artifact sources contribute to the resource map under
+ * `apis/<name>/`:
+ *   1. `.api-resources.yaml` — sha-tracked, regenerated by
+ *      `refresh-api` from `spec.json` (upstream OpenAPI).
+ *   2. `.api-resources.local.yaml` — ARV-111 user extension that
+ *      survives `refresh-api` (write-only endpoints, common SaaS-style
+ *      ingest, …).
+ *
+ * `readResourceMap` in `cli/commands/discover.ts` merges them by hand:
+ * extensions win on `resource` name collision. m-18 (quicktype-derived
+ * and mitmproxy-derived schema layers) will add two more sources with
+ * different precedence and merge semantics — doing that ad-hoc would
+ * end the way ad-hoc output-format parsing did (ARV-97 family,
+ * resolved by m-19/ARV-116).
+ *
+ * This module is the same move for spec sources: declare each source
+ * once as a `SpecLayer`, with precedence and merge policy, and feed
+ * them through `composeSpec()`. The result is a `ComposedSpec` plus a
+ * `ProvenanceMap` (`resource → layer.id`) that downstream code can
+ * consult to explain *where* a field came from (m-18 follow-ups will
+ * surface this in `doctor` / `catalog --provenance`; this task only
+ * ships the internal API).
+ *
+ * Scope of this task: ONLY the resource-map dimension (the actual
+ * `ResourceYaml` shape used by every other module). Other dimensions
+ * (raw OpenAPI document, fixture manifest) keep their own loaders —
+ * generalising further before there's a second consumer would be
+ * premature.
+ */
+
+/** How a layer's entries combine with already-resolved entries. */
+export type MergePolicy =
+  /** Layer entries replace lower-precedence entries on key collision. */
+  | "override"
+  /** Layer entries are dropped if a lower-precedence entry already
+   *  owns the key. (Useful for "default" layers that fill gaps but
+   *  shouldn't shadow user input.) */
+  | "preserve"
+  /** Layer entries are appended even when a key already exists,
+   *  producing duplicate keys. Reserved for future fixture layers;
+   *  not used by the current two-layer resource composition. */
+  | "append";
+
+/** Domain a layer contributes to. Today only `resources` is wired —
+ *  m-18 will likely add `fixtures` (manifest merge) and `spec`
+ *  (raw OpenAPI augmentation). Listed up front so layer factories
+ *  carry the tag at construction. */
+export type LayerScope = "resources" | "fixtures" | "spec";
+
+/** A single typed source of spec data. */
+export interface SpecLayer<T> {
+  /** Stable identifier surfaced in the provenance map (e.g.,
+   *  `"upstream"`, `"extension"`, `"quicktype"`). Must be unique
+   *  inside one `composeSpec` call. */
+  id: string;
+  /** Source path/URL for diagnostics. Optional — synthetic layers
+   *  (in-memory test fixtures) can omit. */
+  path?: string;
+  /** Higher precedence wins on key collisions when `mergePolicy` is
+   *  `"override"`. Ties: layer ordering in the input array. */
+  precedence: number;
+  /** Which composition this layer participates in. `composeSpec` does
+   *  not currently route on scope — it expects callers to filter — but
+   *  the field makes layer arrays self-describing. */
+  scope: LayerScope;
+  /** How this layer's entries combine with lower-precedence ones. */
+  mergePolicy: MergePolicy;
+  /** Load the layer's entries. Async to accommodate filesystem and
+   *  network sources (an HTTP-fetched OpenAPI snapshot in the future
+   *  could implement this directly). */
+  load: () => Promise<T[]> | T[];
+}
+
+/** Function deriving the merge key for an entry. Pulled out so callers
+ *  can compose resource lists (key = resource name) and, later, fixture
+ *  lists (key = var name) with the same engine. */
+export type KeyFn<T> = (entry: T) => string;
+
+/** Output of `composeSpec`. `entries` is the merged list in stable
+ *  order (lowest precedence first, with higher-precedence overrides
+ *  applied in-place); `provenance` maps the merged key back to the
+ *  layer id that ultimately owns it. */
+export interface ComposedSpec<T> {
+  entries: T[];
+  provenance: Map<string, string>;
+}
+
+/**
+ * Compose layers into a single entry list + provenance map.
+ *
+ * Order of operations:
+ *   1. Layers are sorted by ascending `precedence` (low → high). A
+ *      stable sort is used so ties keep input order.
+ *   2. Each layer's entries are loaded in sequence (the loader is
+ *      async-safe so a slow loader can't block parallel ones — but
+ *      we keep ordering deterministic by awaiting in turn).
+ *   3. Entries are folded into the result Map keyed by `keyFn(entry)`:
+ *        - `mergePolicy === "override"` → replace; provenance updates.
+ *        - `mergePolicy === "preserve"` → only set if the key is new.
+ *        - `mergePolicy === "append"`   → key suffixed with `#<n>` to
+ *          avoid collision; provenance still recorded.
+ *
+ * The result preserves insertion order of the underlying Map, which
+ * is the natural "lowest-precedence-first" view: callers that need a
+ * different ordering re-sort downstream.
+ */
+export async function composeSpec<T>(
+  layers: SpecLayer<T>[],
+  keyFn: KeyFn<T>,
+): Promise<ComposedSpec<T>> {
+  const ordered = [...layers].sort((a, b) => a.precedence - b.precedence);
+
+  const seenIds = new Set<string>();
+  for (const l of ordered) {
+    if (seenIds.has(l.id)) {
+      throw new Error(`composeSpec: duplicate layer id "${l.id}"`);
+    }
+    seenIds.add(l.id);
+  }
+
+  const merged = new Map<string, T>();
+  const provenance = new Map<string, string>();
+  let appendCounter = 0;
+
+  for (const layer of ordered) {
+    const entries = await layer.load();
+    for (const entry of entries) {
+      const key = keyFn(entry);
+      switch (layer.mergePolicy) {
+        case "override":
+          merged.set(key, entry);
+          provenance.set(key, layer.id);
+          break;
+        case "preserve":
+          if (!merged.has(key)) {
+            merged.set(key, entry);
+            provenance.set(key, layer.id);
+          }
+          break;
+        case "append": {
+          const tagged = `${key}#${appendCounter++}`;
+          merged.set(tagged, entry);
+          provenance.set(tagged, layer.id);
+          break;
+        }
+      }
+    }
+  }
+
+  return { entries: Array.from(merged.values()), provenance };
+}

package/src/core/spec/merge-specs.ts

@@ -0,0 +1,156 @@
+/**
+ * Deterministic union of two or more dereferenced OpenAPI documents into
+ * one (ARV-375). Motivation: an org running multiple API versions
+ * side-by-side (v1/v2, deprecated-but-live + current) wants combined
+ * coverage instead of re-scanning each version and reconciling reports by
+ * hand. Before this, that merge was a one-off python script per session.
+ *
+ * Policy — pure, deterministic, no judgment (belongs in zond core per the
+ * litmus test):
+ *   - `paths`: union; on a path-key collision the LATER spec wins, and the
+ *     collision is recorded so the caller can warn (silent shadowing of a
+ *     real endpoint is a correctness trap).
+ *   - `components.*`: union per sub-bucket (schemas, securitySchemes,
+ *     parameters, responses, …); later wins. A component-name collision
+ *     whose two definitions DIFFER (deep-unequal) is reported separately —
+ *     that is the dangerous case (same name, different shape).
+ *   - `servers`, `security`, `tags`: unioned & de-duped by value/name.
+ *   - `info`: taken from the first spec; `version` becomes the unique
+ *     source versions joined with `+` so the merged target is self-labelling.
+ *
+ * Inputs are assumed already dereferenced (readOpenApiSpec output), so path
+ * operations are self-contained — no cross-spec $ref resolution needed.
+ */
+
+import type { OpenAPIV3 } from "openapi-types";
+
+export interface MergeInput {
+  /** Source label (path or URL) for the merge summary. */
+  source: string;
+  doc: OpenAPIV3.Document;
+}
+
+export interface MergeSummary {
+  sources: { source: string; paths: number }[];
+  totalPaths: number;
+  /** Path keys declared by more than one spec (later-wins applied). */
+  pathCollisions: string[];
+  /** `components.<bucket>.<name>` whose definition differs across specs. */
+  schemaConflicts: string[];
+}
+
+export interface MergeResult {
+  merged: OpenAPIV3.Document;
+  summary: MergeSummary;
+}
+
+const COMPONENT_BUCKETS = [
+  "schemas",
+  "responses",
+  "parameters",
+  "examples",
+  "requestBodies",
+  "headers",
+  "securitySchemes",
+  "links",
+  "callbacks",
+] as const;
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  // Cheap structural compare — specs are plain JSON after dereference.
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function mergeOpenApiDocs(inputs: MergeInput[]): MergeResult {
+  if (inputs.length === 0) throw new Error("mergeOpenApiDocs: no specs to merge");
+  const first = inputs[0]!.doc;
+
+  const paths: NonNullable<OpenAPIV3.Document["paths"]> = {};
+  const pathCollisions: string[] = [];
+  const sources: MergeSummary["sources"] = [];
+
+  for (const { source, doc } of inputs) {
+    const specPaths = doc.paths ?? {};
+    let count = 0;
+    for (const [p, item] of Object.entries(specPaths)) {
+      if (p in paths) pathCollisions.push(p);
+      paths[p] = item as OpenAPIV3.PathItemObject;
+      count++;
+    }
+    sources.push({ source, paths: count });
+  }
+
+  // Merge components bucket-by-bucket; flag same-name-different-shape.
+  const schemaConflicts: string[] = [];
+  const components: Record<string, Record<string, unknown>> = {};
+  for (const { doc } of inputs) {
+    const comps = (doc.components ?? {}) as Record<string, Record<string, unknown> | undefined>;
+    for (const bucket of COMPONENT_BUCKETS) {
+      const incoming = comps[bucket];
+      if (!incoming) continue;
+      const target = (components[bucket] ??= {});
+      for (const [name, def] of Object.entries(incoming)) {
+        if (name in target && !deepEqual(target[name], def)) {
+          schemaConflicts.push(`${bucket}.${name}`);
+        }
+        target[name] = def;
+      }
+    }
+  }
+
+  // Union servers by url, security by value, tags by name.
+  const servers = dedupeBy(
+    inputs.flatMap((i) => i.doc.servers ?? []),
+    (s) => s.url,
+  );
+  const security = dedupeBy(
+    inputs.flatMap((i) => i.doc.security ?? []),
+    (s) => JSON.stringify(s),
+  );
+  const tags = dedupeBy(
+    inputs.flatMap((i) => i.doc.tags ?? []),
+    (t) => t.name,
+  );
+
+  const versions = dedupe(inputs.map((i) => i.doc.info?.version).filter(Boolean) as string[]);
+
+  const merged: OpenAPIV3.Document = {
+    ...first,
+    openapi: first.openapi ?? "3.0.0",
+    info: {
+      ...first.info,
+      version: versions.join("+") || first.info?.version || "merged",
+    },
+    paths,
+    ...(Object.keys(components).length > 0 ? { components: components as OpenAPIV3.ComponentsObject } : {}),
+    ...(servers.length > 0 ? { servers } : {}),
+    ...(security.length > 0 ? { security } : {}),
+    ...(tags.length > 0 ? { tags } : {}),
+  };
+
+  return {
+    merged,
+    summary: {
+      sources,
+      totalPaths: Object.keys(paths).length,
+      pathCollisions: dedupe(pathCollisions),
+      schemaConflicts: dedupe(schemaConflicts),
+    },
+  };
+}
+
+function dedupe<T>(arr: T[]): T[] {
+  return [...new Set(arr)];
+}
+
+function dedupeBy<T>(arr: T[], key: (x: T) => string): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const x of arr) {
+    const k = key(x);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(x);
+  }
+  return out;
+}

package/src/core/spec/schema-from-runs.ts

@@ -0,0 +1,117 @@
+/**
+ * ARV-175: extract 2xx response bodies from a persisted run and infer a
+ * JSON Schema per (endpoint, status). The output `patch.schema.json` is the
+ * input to `refresh-api --merge-schema` (ARV-176), which folds it into the
+ * spec overlay so `response_schema_conformance` has something to check on
+ * APIs whose upstream spec declares no response schemas.
+ */
+
+import { inferSchema, type JsonSchema } from "./infer-schema.ts";
+import { specPathToRegex, normalizePath } from "../generator/coverage-scanner.ts";
+import type { EndpointInfo } from "../generator/types.ts";
+
+export interface SchemaFromRunsResult {
+  /** endpoint label (`METHOD /path/{tpl}`) → status code → inferred schema. */
+  patch: Record<string, Record<string, JsonSchema>>;
+  /** Per-group accounting for the CLI to report. */
+  groups: Array<{
+    endpoint: string;
+    status: string;
+    samples: number;
+    emitted: boolean;
+    reason?: string;
+  }>;
+}
+
+export interface ResultRow {
+  request_method: string | null;
+  request_url: string | null;
+  response_status: number | null;
+  response_body: string | null;
+}
+
+/** Strip base URL, query, and trailing slash from a concrete request URL,
+ *  leaving just the path for spec-template matching. */
+function pathOf(rawUrl: string): string {
+  let p = rawUrl;
+  // Drop scheme+host if present.
+  const schemeIdx = p.indexOf("://");
+  if (schemeIdx !== -1) {
+    const afterScheme = p.slice(schemeIdx + 3);
+    const slash = afterScheme.indexOf("/");
+    p = slash === -1 ? "/" : afterScheme.slice(slash);
+  }
+  const q = p.indexOf("?");
+  if (q !== -1) p = p.slice(0, q);
+  return p.replace(/\/+$/, "") || "/";
+}
+
+/** Match a concrete path to the most specific spec endpoint (fewest params
+ *  wins, so `/users/me` beats `/users/{id}`). Returns the endpoint label. */
+function matchEndpoint(
+  method: string,
+  concretePath: string,
+  endpoints: EndpointInfo[],
+): string | null {
+  const norm = normalizePath(concretePath);
+  const candidates = endpoints
+    .filter((e) => e.method.toUpperCase() === method.toUpperCase())
+    .filter((e) => specPathToRegex(e.path).test(norm))
+    .sort((a, b) => paramCount(a.path) - paramCount(b.path));
+  const best = candidates[0];
+  return best ? `${best.method.toUpperCase()} ${best.path}` : null;
+}
+
+function paramCount(path: string): number {
+  return (path.match(/\{[^}]+\}/g) ?? []).length;
+}
+
+export interface SchemaFromRunsOptions {
+  results: ResultRow[];
+  endpoints: EndpointInfo[];
+  /** Minimum 2xx samples per (endpoint, status) group to emit a schema. */
+  minSamples: number;
+}
+
+export function schemaFromRuns(opts: SchemaFromRunsOptions): SchemaFromRunsResult {
+  const { results, endpoints, minSamples } = opts;
+  // (endpoint → status → parsed bodies)
+  const buckets = new Map<string, Map<string, unknown[]>>();
+  // Preserve unmatched URLs so the CLI can hint at spec/base-url drift.
+  for (const r of results) {
+    if (r.response_status == null || r.response_status < 200 || r.response_status >= 300) continue;
+    if (!r.response_body || !r.request_url || !r.request_method) continue;
+    let body: unknown;
+    try {
+      body = JSON.parse(r.response_body);
+    } catch {
+      continue; // non-JSON 2xx body — nothing to infer for application/json
+    }
+    const endpoint = matchEndpoint(r.request_method, pathOf(r.request_url), endpoints);
+    if (!endpoint) continue;
+    const status = String(r.response_status);
+    if (!buckets.has(endpoint)) buckets.set(endpoint, new Map());
+    const byStatus = buckets.get(endpoint)!;
+    if (!byStatus.has(status)) byStatus.set(status, []);
+    byStatus.get(status)!.push(body);
+  }
+
+  const patch: SchemaFromRunsResult["patch"] = {};
+  const groups: SchemaFromRunsResult["groups"] = [];
+  // Deterministic order: sort by endpoint then status.
+  for (const endpoint of [...buckets.keys()].sort()) {
+    const byStatus = buckets.get(endpoint)!;
+    for (const status of [...byStatus.keys()].sort()) {
+      const samples = byStatus.get(status)!;
+      if (samples.length < minSamples) {
+        groups.push({ endpoint, status, samples: samples.length, emitted: false, reason: `<${minSamples} samples` });
+        continue;
+      }
+      const schema = inferSchema(samples);
+      if (!patch[endpoint]) patch[endpoint] = {};
+      patch[endpoint]![status] = schema;
+      groups.push({ endpoint, status, samples: samples.length, emitted: true });
+    }
+  }
+  return { patch, groups };
+}