@kirrosh/zond 0.26.1 → 0.27.0

package/src/core/severity/index.ts

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

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

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

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

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