@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/severity/index.ts

@@ -0,0 +1,121 @@
+/**
+ * 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";
+
+export const SEVERITY_ORDER: readonly Severity[] = [
+  "critical",
+  "high",
+  "medium",
+  "low",
+  "info",
+] as const;
+
+const SEVERITY_RANK: Record<Severity, number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  info: 4,
+};
+
+/**
+ * Strength of evidence backing a finding. Drives the severity cap
+ * applied at finding-emission time.
+ *
+ * - `end_to_end`: zond demonstrated the impact itself (read another
+ *   user's data, executed action without auth, file read confirmed).
+ *   Required for CRITICAL.
+ * - `evidence_chain`: ≥2 requests prove the finding (storage +
+ *   reflection found, follow-up GET shows persistence, OOB callback
+ *   received). Required for HIGH.
+ * - `single_signal`: one request/response indicates an anomaly but
+ *   no follow-up confirms impact (server accepted CRLF / 169.254 /
+ *   is_admin field — outcome unknown). Capped at LOW.
+ * - `static`: spec-lint, style, naming, missing additionalProperties.
+ *   No runtime evidence. Capped at INFO.
+ */
+export type ProofKind = "end_to_end" | "evidence_chain" | "single_signal" | "static";
+
+const PROOF_CAP: Record<ProofKind, Severity> = {
+  end_to_end: "critical",
+  evidence_chain: "high",
+  single_signal: "low",
+  static: "info",
+};
+
+/**
+ * Caps a claimed severity by the strength of evidence behind it.
+ * Producers should pass their natural severity claim and the proof
+ * kind; the cap function downgrades if claim exceeds what evidence
+ * supports.
+ *
+ * Example: mass-assignment probe wants HIGH (dangerous field), but
+ * only has single-signal proof (server returned 200, didn't verify
+ * persistence). Cap returns LOW. To get HIGH, probe must escalate
+ * proof to evidence_chain by doing follow-up GET.
+ */
+export function capSeverityByProof(claim: Severity, proof: ProofKind): Severity {
+  const cap = PROOF_CAP[proof];
+  return rankSeverity(claim) < rankSeverity(cap) ? cap : claim;
+}
+
+export function rankSeverity(s: Severity): number {
+  return SEVERITY_RANK[s];
+}
+
+/** True iff `a` is at least as severe as `b`. */
+export function isAtLeast(a: Severity, b: Severity): boolean {
+  return rankSeverity(a) <= rankSeverity(b);
+}
+
+/** Highest severity among inputs; returns 'info' on empty list. */
+export function maxSeverity(items: readonly Severity[]): Severity {
+  let best: Severity = "info";
+  for (const s of items) {
+    if (rankSeverity(s) < rankSeverity(best)) best = s;
+  }
+  return best;
+}
+
+/**
+ * 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/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/util/format-eta.ts

@@ -0,0 +1,21 @@
+/**
+ * ARV-249: human-readable duration formatter for ETA / progress lines.
+ *
+ * Distinct from `core/reporter/console.formatDuration`, which is geared to
+ * per-step latencies (sub-second resolution, single unit). Here we drop
+ * sub-second precision but emit two units once we cross a minute, so a
+ * five-minute ETA reads `5m12s` instead of `5m 12s`.
+ */
+export function formatEta(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) return "?";
+  const s = Math.round(seconds);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) {
+    const m = Math.floor(s / 60);
+    const rem = s % 60;
+    return rem > 0 ? `${m}m${rem}s` : `${m}m`;
+  }
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  return m > 0 ? `${h}h${m}m` : `${h}h`;
+}

package/src/core/utils.ts

@@ -1,5 +1,9 @@
 export function getByPath(obj: unknown, path: string, defaultVal?: unknown): unknown {
-  const keys = path.split(".");
+  // Normalize JSONPath-like bracket indexing (`data[0].id`) to dotted form
+  // (`data.0.id`) so callers can use either spelling. Numeric segments also
+  // index arrays correctly because `array["0"]` is equivalent to `array[0]`.
+  const normalized = path.replace(/\[(\d+)\]/g, ".$1").replace(/^\./, "");
+  const keys = normalized.split(".");
   let result: unknown = obj;
   for (const key of keys) {
     result = (result as Record<string, unknown>)?.[key];

package/src/core/workspace/config.ts

@@ -0,0 +1,129 @@
+/**
+ * Workspace `zond.config.yml` loader (TASK-301).
+ *
+ * Centralises read-only access to workspace-level defaults. Right now only
+ * two fields are honoured:
+ *
+ *   defaults:
+ *     timeout_ms: 30000   # used by cleanup / prepare-fixtures / probe
+ *                         # mass-assignment / probe security / request
+ *     rate_limit: 5       # used by `zond run` (number, or "auto")
+ *
+ * Resolution chain across the CLI (highest wins):
+ *
+ *   CLI flag → per-API .env.yaml meta → workspace defaults → hard-coded fallback
+ *
+ * Per-API overrides live in `apis/<name>/.env.yaml` as `rateLimit:` /
+ * `timeoutMs:` (see `loadEnvMeta`); we deliberately don't carve a second
+ * channel into this file to avoid two ways of saying the same thing.
+ *
+ * Read-once-and-cache: the file is parsed at most once per process from
+ * the workspace root resolved by `findWorkspaceRoot`. Tests can call
+ * `_resetWorkspaceConfigCache()` between runs.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findWorkspaceRoot } from "./root.ts";
+
+export interface WorkspaceDefaults {
+  /** Per-request timeout in ms applied when the CLI flag and `.env.yaml` are silent. */
+  timeoutMs?: number;
+  /** Run-time rate limit (rps) or `"auto"`. */
+  rateLimit?: number | "auto";
+}
+
+let cache: { root: string; defaults: WorkspaceDefaults } | null = null;
+
+function parseTimeoutMs(v: unknown): number | undefined {
+  if (typeof v === "number" && Number.isFinite(v) && v > 0) return v;
+  if (typeof v === "string") {
+    const n = Number.parseInt(v, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return undefined;
+}
+
+function parseRateLimit(v: unknown): number | "auto" | undefined {
+  if (v === "auto") return "auto";
+  if (typeof v === "number" && Number.isFinite(v) && v > 0) return v;
+  if (typeof v === "string") {
+    if (v === "auto") return "auto";
+    const n = Number.parseFloat(v);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return undefined;
+}
+
+function readDefaults(configPath: string): WorkspaceDefaults {
+  if (!existsSync(configPath)) return {};
+  let parsed: unknown;
+  try {
+    const text = readFileSync(configPath, "utf8");
+    parsed = Bun.YAML.parse(text);
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+  const obj = parsed as Record<string, unknown>;
+  const defaultsRaw = obj.defaults;
+  if (typeof defaultsRaw !== "object" || defaultsRaw === null || Array.isArray(defaultsRaw)) return {};
+  const d = defaultsRaw as Record<string, unknown>;
+  const out: WorkspaceDefaults = {};
+  const t = parseTimeoutMs(d.timeout_ms ?? d.timeoutMs);
+  if (t !== undefined) out.timeoutMs = t;
+  const r = parseRateLimit(d.rate_limit ?? d.rateLimit);
+  if (r !== undefined) out.rateLimit = r;
+  return out;
+}
+
+/**
+ * Returns the workspace defaults block, cached for the lifetime of the
+ * process. When no workspace marker is found, returns `{}` (no defaults).
+ */
+export function loadWorkspaceDefaults(cwd?: string): WorkspaceDefaults {
+  const ws = findWorkspaceRoot(cwd);
+  if (ws.fromFallback) return {};
+  if (cache && cache.root === ws.root) return cache.defaults;
+  const defaults = readDefaults(join(ws.root, "zond.config.yml"));
+  cache = { root: ws.root, defaults };
+  return defaults;
+}
+
+/** Test helper: drop the parse cache so the next call re-reads from disk. */
+export function _resetWorkspaceConfigCache(): void {
+  cache = null;
+}
+
+export const HARD_DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * Resolve `--timeout` via CLI > per-API `.env.yaml` (`timeoutMs`) > workspace
+ * `defaults.timeout_ms` > 30000. Each layer accepts `undefined` to mean
+ * "fall through".
+ */
+export function resolveTimeoutMs(
+  cliFlag: number | undefined,
+  envMetaTimeout: number | undefined,
+  cwd?: string,
+): number {
+  if (cliFlag !== undefined) return cliFlag;
+  if (envMetaTimeout !== undefined) return envMetaTimeout;
+  const ws = loadWorkspaceDefaults(cwd);
+  return ws.timeoutMs ?? HARD_DEFAULT_TIMEOUT_MS;
+}
+
+/**
+ * Resolve `--rate-limit` via CLI > per-API `.env.yaml` (`rateLimit`) >
+ * workspace `defaults.rate_limit` > undefined (no throttling).
+ */
+export function resolveRateLimit(
+  cliFlag: number | "auto" | undefined,
+  envMetaRateLimit: number | "auto" | undefined,
+  cwd?: string,
+): number | "auto" | undefined {
+  if (cliFlag !== undefined) return cliFlag;
+  if (envMetaRateLimit !== undefined) return envMetaRateLimit;
+  const ws = loadWorkspaceDefaults(cwd);
+  return ws.rateLimit;
+}