@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/generator/types.ts

@@ -8,6 +8,14 @@ export interface ResponseInfo {
 
 export interface EndpointInfo {
   path: string;
+  /** ARV-183: original spec path before ARV-40 path-param disambiguation
+   *  renamed `{id}` → `{<resource>_id}`. Set only when a rename happened;
+   *  unset means `path` is the original. Used by checks that look up
+   *  `doc.paths[...]` by string equality (status_code_conformance,
+   *  response_headers_conformance) — without this they miss the spec
+   *  entry and either fire phantom findings (status_code) or silently
+   *  skip (response_headers). */
+  originalPath?: string;
   method: string;
   operationId?: string;
   summary?: string;

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

@@ -0,0 +1,129 @@
+/**
+ * `.identity.yaml` — gitignored flat YAML file holding non-secret-but-
+ * personally-identifying values for an API (TASK-174, m-10).
+ *
+ *     # apis/<name>/.identity.yaml
+ *     organization_id_or_slug: "acme-eng"
+ *     member_id: "12345"
+ *
+ *     # apis/<name>/.env.yaml
+ *     organization_id_or_slug: "@identity:organization_id_or_slug"
+ *     auth_token: "@secret:auth_token"
+ *
+ * Mental model:
+ *   - `.secrets.yaml` → values auto-registered with SecretRegistry,
+ *     replaced with `<redacted:<name>>` in every persisted artifact.
+ *   - `.identity.yaml` → values are visible locally and visible in
+ *     case-study drafts by default. The opt-in `--redact-identity`
+ *     flag (TASK-173) swaps them for placeholders when sharing
+ *     outbound. Doctor shows them as plain text.
+ *
+ * The file is git-invisible (gitignore is amended by setup-api) so a
+ * teammate forking the repo doesn't accidentally inherit your org slug.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const IDENTITY_FILENAME = ".identity.yaml";
+const IDENTITY_REF_RE = /^@identity:([A-Za-z_][A-Za-z0-9_.-]*)$/;
+
+/** Canonical identity-key vocabulary. The setup-api seeder uses this to
+ *  decide which placeholders to put in a fresh `.identity.yaml`. */
+export const CANONICAL_IDENTITY_KEYS = new Set<string>([
+  "organization_id_or_slug",
+  "organization_slug",
+  "organization_id",
+  "member_id",
+  "user_id",
+  "project_id_or_slug",
+  "project_slug",
+  "project_id",
+  "team_slug",
+  "team_id",
+  "account_id",
+]);
+
+export interface IdentityFile {
+  filePath: string;
+  values: Record<string, string>;
+}
+
+export function loadIdentityFile(dir: string): IdentityFile | null {
+  const filePath = join(dir, IDENTITY_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;
+    if (typeof v === "object") {
+      throw new Error(`${filePath}: nested values are not supported (key "${k}").`);
+    }
+    values[k] = String(v);
+  }
+  return { filePath, values };
+}
+
+export function loadIdentityFromAncestor(start: string, stopAt?: string): IdentityFile | null {
+  let dir = start;
+  for (let i = 0; i < 8; i++) {
+    const file = loadIdentityFile(dir);
+    if (file) return file;
+    if (stopAt && dir === stopAt) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Replace every value from an identity map with `<identity:<key>>`
+ * inside `text`. Used by `--redact-identity` (TASK-173). Mirrors the
+ * SecretRegistry's logic — longest values first so a containing value
+ * wins, minimum length 2 (identity slugs can be short like `acme`).
+ */
+export function redactIdentityIn(text: string, values: Record<string, string>): string {
+  if (!text || Object.keys(values).length === 0) return text;
+  const entries = Object.entries(values)
+    .filter(([, v]) => typeof v === "string" && v.length >= 2)
+    .sort((a, b) => b[1].length - a[1].length);
+  let out = text;
+  for (const [name, value] of entries) {
+    if (out.indexOf(value) === -1) continue;
+    out = out.split(value).join(`<identity:${name}>`);
+  }
+  return out;
+}
+
+export function resolveIdentityRefs(
+  envValues: Record<string, string>,
+  identity: IdentityFile | 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(IDENTITY_REF_RE) : null;
+    if (!m) continue;
+    const refName = m[1]!;
+    const value = identity?.values[refName];
+    if (value == null) {
+      const where = identity ? identity.filePath : `${dirname(filePath)}/${IDENTITY_FILENAME}`;
+      throw new Error(
+        `${filePath}: key "${k}" references @identity:${refName} but no such entry exists in ${where}. ` +
+        `Add \`${refName}: "<value>"\` to ${where} (or remove the @identity: prefix to use a literal value).`,
+      );
+    }
+    out[k] = value;
+  }
+  return out;
+}

package/src/core/lint/affects.ts

@@ -0,0 +1,28 @@
+import type { RuleId } from "./types.ts";
+
+/**
+ * Cross-reference: which other zond commands are made noisier or less reliable
+ * by an unfixed issue of each rule. Surfaced in JSON output as `affects[]` so
+ * agents and IDEs can predict which probe runs will produce false-positive 5xx
+ * or which `--validate-schema` checks will silently no-op.
+ */
+export const RULE_AFFECTS: Record<RuleId, string[]> = {
+  // Group A — lax examples mislead generators and downstream consumers.
+  A1: ["run:--validate-schema", "generate"],
+  A2: ["run:--validate-schema", "generate"],
+  A3: ["run:--validate-schema", "generate"],
+  A4: ["run:--validate-schema", "generate"],
+  A5: ["generate"],
+  A6: [],
+
+  // Group B — loose schema lets the spec accept what the server rejects.
+  B1: ["probe-validation:invalid-path-uuid", "probe-methods"],
+  B2: ["probe-validation:invalid-path-uuid"],
+  B3: ["probe-validation:boundary-string"],
+  B4: ["probe-validation:boundary-string"],
+  B5: ["run:--validate-schema"],
+  B6: ["run:--validate-schema"],
+  B7: ["run:--validate-schema"],
+  B8: ["probe-mass-assignment"],
+  B9: ["probe-validation:missing-required"],
+};

package/src/core/lint/config.ts

@@ -0,0 +1,96 @@
+import { readFileSync, existsSync } from "fs";
+import type { LintConfig, RuleId, RuleSetting } from "./types.ts";
+import { ALL_RULES, DEFAULT_HEURISTICS, DEFAULT_SEVERITY } from "./types.ts";
+
+export function defaultConfig(): LintConfig {
+  const rules: Partial<Record<RuleId, RuleSetting>> = {};
+  for (const r of ALL_RULES) rules[r] = DEFAULT_SEVERITY[r];
+  return {
+    rules,
+    heuristics: { ...DEFAULT_HEURISTICS },
+    ignore_paths: [],
+  };
+}
+
+interface RawConfig {
+  rules?: Record<string, string>;
+  heuristics?: Partial<typeof DEFAULT_HEURISTICS>;
+  ignore_paths?: string[];
+}
+
+/**
+ * Merge order: defaults → file config (.zond-lint.json) → CLI --rule overrides.
+ * --rule format: comma-separated `R1` (enable at default severity), `!R1`
+ * (disable), or `R1=high|medium|low` (set severity).
+ */
+export function loadConfig(opts: {
+  configPath?: string;
+  cliRule?: string;
+  includePaths?: string[];
+  maxIssues?: number;
+}): LintConfig {
+  const cfg = defaultConfig();
+
+  if (opts.configPath) {
+    if (!existsSync(opts.configPath)) {
+      throw new Error(`Config file not found: ${opts.configPath}`);
+    }
+    const raw = JSON.parse(readFileSync(opts.configPath, "utf8")) as RawConfig;
+    if (raw.rules) {
+      for (const [rule, val] of Object.entries(raw.rules)) {
+        if (!ALL_RULES.includes(rule as RuleId)) continue;
+        cfg.rules[rule as RuleId] = normaliseSetting(val);
+      }
+    }
+    if (raw.heuristics) cfg.heuristics = { ...cfg.heuristics, ...raw.heuristics };
+    if (raw.ignore_paths) cfg.ignore_paths = raw.ignore_paths;
+  }
+
+  if (opts.cliRule) {
+    for (const tok of opts.cliRule.split(",").map(s => s.trim()).filter(Boolean)) {
+      if (tok.startsWith("!")) {
+        const r = tok.slice(1) as RuleId;
+        if (ALL_RULES.includes(r)) cfg.rules[r] = "off";
+      } else if (tok.includes("=")) {
+        const [r, sev] = tok.split("=") as [RuleId, string];
+        if (ALL_RULES.includes(r)) cfg.rules[r] = normaliseSetting(sev);
+      } else {
+        const r = tok as RuleId;
+        if (ALL_RULES.includes(r)) cfg.rules[r] = DEFAULT_SEVERITY[r];
+      }
+    }
+  }
+
+  if (opts.includePaths && opts.includePaths.length > 0) cfg.include_paths = opts.includePaths;
+  if (opts.maxIssues) cfg.max_issues = opts.maxIssues;
+  return cfg;
+}
+
+function normaliseSetting(raw: string): RuleSetting {
+  const v = raw.toLowerCase();
+  if (v === "off" || v === "false" || v === "no") return "off";
+  // ARV-255: spec-lint is hygiene — severity capped at LOW/INFO. User
+  // overrides via `--rule R=high|medium` are still parsed for back-compat
+  // but silently downgraded so the cap is enforced uniformly.
+  if (v === "high" || v === "error") return "low";
+  if (v === "medium" || v === "warn" || v === "warning") return "low";
+  if (v === "low") return "low";
+  if (v === "info" || v === "informational") return "info";
+  return "off";
+}
+
+/**
+ * Glob matcher — supports `*` and `**`. Used for `ignore_paths` /
+ * `include_paths`.
+ */
+export function matchGlob(glob: string, path: string): boolean {
+  const re = new RegExp(
+    "^" + glob
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+      .replace(/\*\*/g, "<<<DSTAR>>>")
+      .replace(/\*/g, "[^/]*")
+      .replace(/<<<DSTAR>>>/g, ".*") +
+      "$",
+  );
+  return re.test(path);
+}

package/src/core/lint/format.ts

@@ -0,0 +1,42 @@
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import { STRICT_RFC3339_DATE_TIME } from "../runner/schema-validator.ts";
+
+const ajv = new Ajv({ strict: false, allErrors: false });
+addFormats(ajv);
+ajv.addFormat("date-time", { type: "string", validate: STRICT_RFC3339_DATE_TIME });
+
+const SUPPORTED = new Set([
+  "date-time", "date", "time",
+  "email", "idn-email",
+  "uri", "uri-reference", "url",
+  "uuid",
+  "ipv4", "ipv6",
+  "hostname", "idn-hostname",
+  "regex",
+  "byte", "binary", "password",
+]);
+
+const cache = new Map<string, (v: unknown) => boolean>();
+
+/**
+ * True if `value` satisfies the OpenAPI/JSON-Schema `format`. Returns true for
+ * unknown formats (we can't say). Returns true for non-string values
+ * (OpenAPI's `format` only constrains strings).
+ */
+export function validateExampleAgainstFormat(value: unknown, format: string): boolean {
+  if (typeof value !== "string") return true;
+  if (!SUPPORTED.has(format)) return true;
+  if (format === "url") format = "uri";
+
+  let validator = cache.get(format);
+  if (!validator) {
+    try {
+      validator = ajv.compile({ type: "string", format }) as (v: unknown) => boolean;
+      cache.set(format, validator);
+    } catch {
+      return true;
+    }
+  }
+  return validator(value);
+}

package/src/core/lint/index.ts

@@ -0,0 +1,94 @@
+import type { OpenAPIV3 } from "openapi-types";
+import type { Issue, RuleId, Severity, LintConfig, LintResult } from "./types.ts";
+import { walk } from "./walker.ts";
+import { matchGlob } from "./config.ts";
+import { runConsistencyRules } from "./rules/consistency.ts";
+import {
+  runParamStrictnessRules,
+  runResponseStrictnessRules,
+  runRequestBodyStrictnessRules,
+  runSchemaStrictnessRules,
+} from "./rules/strictness.ts";
+import {
+  runParamHeuristics,
+  runSchemaHeuristics,
+  runRequestBodyHeuristics,
+} from "./rules/heuristics.ts";
+import { RULE_AFFECTS } from "./affects.ts";
+
+export type { Issue, LintConfig, LintResult, LintStats, Severity, RuleId } from "./types.ts";
+export { loadConfig, defaultConfig } from "./config.ts";
+export { formatHuman, formatNdjson, formatGrouped, buildRuleSummary } from "./reporter.ts";
+export type { RuleSummaryEntry } from "./reporter.ts";
+
+export function lintSpec(doc: OpenAPIV3.Document, config: LintConfig): LintResult {
+  const issues: Issue[] = [];
+  const endpoints = new Set<string>();
+
+  const sink = {
+    push(rule: RuleId, severity: Severity, message: string, opts: { jsonpointer: string; path?: string; method?: string; fix_hint?: string }) {
+      const setting = config.rules[rule];
+      if (setting === "off" || setting === undefined) return;
+
+      // Path-include / ignore filters operate on opts.path when present.
+      if (opts.path) {
+        if (config.ignore_paths.some(g => matchGlob(g, opts.path!))) return;
+        if (config.include_paths && config.include_paths.length > 0
+            && !config.include_paths.some(g => matchGlob(g, opts.path!))) return;
+      }
+
+      const issue: Issue = {
+        rule,
+        severity: setting as Severity,
+        jsonpointer: opts.jsonpointer,
+        message,
+        recommended_action: "fix_spec",
+      };
+      if (opts.path) issue.path = opts.path;
+      if (opts.method && opts.method !== "*") issue.method = opts.method;
+      if (opts.fix_hint) issue.fix_hint = opts.fix_hint;
+      const aff = RULE_AFFECTS[rule];
+      if (aff && aff.length > 0) issue.affects = aff;
+
+      if (opts.path) endpoints.add(`${opts.method ?? ""} ${opts.path}`);
+
+      issues.push(issue);
+    },
+  };
+
+  walk(doc, ctx => {
+    if (config.max_issues && issues.length >= config.max_issues) return;
+    switch (ctx.kind) {
+      case "parameter":
+        runParamStrictnessRules(ctx, sink, config.heuristics);
+        runParamHeuristics(ctx, sink, config.heuristics);
+        break;
+      case "response":
+        runResponseStrictnessRules(ctx, sink);
+        break;
+      case "requestBody":
+        runRequestBodyStrictnessRules(ctx, sink);
+        runRequestBodyHeuristics(ctx, sink, config.heuristics);
+        break;
+      case "schema":
+        runConsistencyRules(ctx, sink);
+        runSchemaStrictnessRules(ctx, sink);
+        runSchemaHeuristics(ctx, sink, config.heuristics);
+        break;
+    }
+  });
+
+  // Trim to max_issues if exceeded mid-walk
+  const trimmed = config.max_issues ? issues.slice(0, config.max_issues) : issues;
+
+  const stats = {
+    total: trimmed.length,
+    critical: trimmed.filter(i => i.severity === "critical").length,
+    high: trimmed.filter(i => i.severity === "high").length,
+    medium: trimmed.filter(i => i.severity === "medium").length,
+    low: trimmed.filter(i => i.severity === "low").length,
+    info: trimmed.filter(i => i.severity === "info").length,
+    endpoints: endpoints.size,
+  };
+  return { issues: trimmed, stats };
+}

package/src/core/lint/reporter.ts

@@ -0,0 +1,128 @@
+import type { Issue, LintStats, Severity } from "./types.ts";
+import { severityGlyph, rankSeverity } from "../severity/index.ts";
+
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+const useColor = (): boolean => process.stdout.isTTY === true;
+
+const ICON: Record<Severity, string> = {
+  critical: "🚨", high: "🔴", medium: "⚠️ ", low: "ℹ️ ", info: "· ",
+};
+const COLOR: Record<Severity, string> = {
+  critical: RED, high: RED, medium: YELLOW, low: DIM, info: DIM,
+};
+
+export function formatHuman(issues: Issue[], stats: LintStats): string {
+  if (issues.length === 0) {
+    return useColor() ? `${BOLD}✓ no issues${RESET}\n` : "✓ no issues\n";
+  }
+  const groups: Record<Severity, Issue[]> = {
+    critical: [], high: [], medium: [], low: [], info: [],
+  };
+  for (const i of issues) groups[i.severity].push(i);
+
+  const lines: string[] = [];
+  for (const sev of ["critical", "high", "medium", "low", "info"] as Severity[]) {
+    const g = groups[sev];
+    if (g.length === 0) continue;
+    const header = `${ICON[sev]} ${sev.toUpperCase()} (${g.length})`;
+    lines.push(useColor() ? `${COLOR[sev]}${BOLD}${header}${RESET}` : header);
+    for (const i of g) {
+      const where = formatWhere(i);
+      const tail = useColor() ? `${DIM}(${i.rule})${RESET}` : `(${i.rule})`;
+      lines.push(`  ${where}  ${i.message} ${tail}`);
+      if (i.fix_hint) {
+        lines.push(useColor() ? `    ${DIM}→ ${i.fix_hint}${RESET}` : `    → ${i.fix_hint}`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push(`${stats.total} issue(s) across ${stats.endpoints} endpoint(s)`);
+  return lines.join("\n") + "\n";
+}
+
+function formatWhere(i: Issue): string {
+  if (i.path && i.method && i.method !== "*") return `${i.method} ${i.path}`;
+  if (i.path) return i.path;
+  return i.jsonpointer;
+}
+
+export function formatNdjson(issues: Issue[]): string {
+  return issues.map(i => JSON.stringify(i)).join("\n") + (issues.length ? "\n" : "");
+}
+
+/**
+ * TASK-279: rule × severity rollup. The flat `formatHuman` output has a habit
+ * of producing 700+ lines on real-world specs (one large SaaS spec we
+ * benchmarked had 385 of 714 issues from a single rule). This collapses
+ * them to one row per rule so a human can
+ * triage by impact instead of `grep '(B1)' | wc -l`.
+ */
+export interface RuleSummaryEntry {
+  rule: string;
+  severity: Severity;
+  count: number;
+  endpoints: number;
+  message: string;
+  sample?: { method?: string; path?: string; jsonpointer?: string };
+}
+
+export function buildRuleSummary(issues: Issue[]): RuleSummaryEntry[] {
+  type Bucket = { rule: string; severity: Severity; count: number; endpointSet: Set<string>; message: string; sample?: RuleSummaryEntry["sample"] };
+  const map = new Map<string, Bucket>();
+  for (const i of issues) {
+    const key = `${i.rule}|${i.severity}`;
+    let b = map.get(key);
+    if (!b) {
+      b = { rule: i.rule, severity: i.severity, count: 0, endpointSet: new Set(), message: i.message };
+      if (i.path || i.method || i.jsonpointer) {
+        b.sample = { method: i.method, path: i.path, jsonpointer: i.jsonpointer };
+      }
+      map.set(key, b);
+    }
+    b.count++;
+    if (i.path) b.endpointSet.add(`${i.method ?? "*"} ${i.path}`);
+    else if (i.jsonpointer) b.endpointSet.add(i.jsonpointer);
+  }
+  return [...map.values()]
+    .sort((a, b) => rankSeverity(a.severity) - rankSeverity(b.severity) || b.count - a.count)
+    .map(b => ({
+      rule: b.rule,
+      severity: b.severity,
+      count: b.count,
+      endpoints: b.endpointSet.size,
+      message: b.message,
+      ...(b.sample ? { sample: b.sample } : {}),
+    }));
+}
+
+export function formatGrouped(issues: Issue[], stats: LintStats, opts: { top?: number } = {}): string {
+  if (issues.length === 0) {
+    return useColor() ? `${BOLD}✓ no issues${RESET}\n` : "✓ no issues\n";
+  }
+  const summary = buildRuleSummary(issues);
+  const rows = opts.top != null && opts.top > 0 ? summary.slice(0, opts.top) : summary;
+
+  const lines: string[] = [];
+  let lastSev: Severity | null = null;
+  for (const r of rows) {
+    if (r.severity !== lastSev) {
+      const header = `${ICON[r.severity]} ${r.severity.toUpperCase()}`;
+      lines.push(useColor() ? `${COLOR[r.severity]}${BOLD}${header}${RESET}` : header);
+      lastSev = r.severity;
+    }
+    const tag = useColor() ? `${COLOR[r.severity]}${r.rule}${RESET}` : r.rule;
+    const endpointsLabel = r.endpoints === r.count ? `${r.count}` : `${r.count} (${r.endpoints} endpoints)`;
+    lines.push(`  ${tag.padEnd(useColor() ? 14 : 4)}  ${endpointsLabel.padStart(6)}  ${r.message}`);
+  }
+  lines.push("");
+  const truncated = opts.top != null && opts.top > 0 && summary.length > rows.length
+    ? ` (showing top ${rows.length} of ${summary.length} rules; pass --top 0 or --verbose for all)`
+    : "";
+  lines.push(`${stats.total} issue(s) across ${stats.endpoints} endpoint(s)${truncated}. Re-run with --verbose for the flat list.`);
+  return lines.join("\n") + "\n";
+}