@kirrosh/zond 0.22.0 → 0.26.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;
@@ -20,6 +28,12 @@ export interface EndpointInfo {
   security: string[];
   deprecated?: boolean;
   requiresEtag?: boolean;
+  /** ARV-189 (m-21): vendor extensions starting with `x-` from the
+   *  operation (and merged from the path item — operation wins on key
+   *  collision). Used by the `x-zond-*` opt-in/skip rules so callers can
+   *  declare check-level policy directly in the spec without an overlay
+   *  yaml file. Empty/undefined when the spec carries no extensions. */
+  extensions?: Record<string, unknown>;
 }
 
 export interface SecuritySchemeInfo {

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";
+}

package/src/core/lint/rules/consistency.ts

@@ -0,0 +1,158 @@
+import type { OpenAPIV3 } from "openapi-types";
+import type { Issue, RuleId, Severity } from "../types.ts";
+import { DEFAULT_SEVERITY } from "../types.ts";
+import { RULE_AFFECTS } from "../affects.ts";
+import type { SchemaContext } from "../walker.ts";
+import { normalisedTypes } from "../walker.ts";
+import { validateExampleAgainstFormat } from "../format.ts";
+
+interface RuleSink {
+  push(rule: RuleId, severity: Severity, message: string, opts: Partial<Pick<Issue, "path" | "method" | "fix_hint">> & { jsonpointer: string }): void;
+}
+
+export function runConsistencyRules(ctx: SchemaContext, sink: RuleSink): void {
+  const s = ctx.schema;
+  if (!s || typeof s !== "object") return;
+
+  const types = normalisedTypes(s);
+  const isStringy = types.includes("string");
+  const isNumeric = types.includes("number") || types.includes("integer");
+
+  const examples = collectExamples(s);
+  for (const { value, pointer } of examples) {
+    checkValueAgainstSchema(value, s, pointer, "example", isStringy, isNumeric, ctx, sink);
+  }
+
+  if (s.default !== undefined) {
+    checkValueAgainstSchema(s.default, s, `${ctx.jsonpointer}/default`, "default", isStringy, isNumeric, ctx, sink);
+  }
+
+  // A6: enum values pairwise unique.
+  if (Array.isArray(s.enum) && s.enum.length > 0) {
+    const seen = new Set<string>();
+    let dupAt = -1;
+    for (let i = 0; i < s.enum.length; i++) {
+      const k = stableKey(s.enum[i]);
+      if (seen.has(k)) { dupAt = i; break; }
+      seen.add(k);
+    }
+    if (dupAt >= 0) {
+      sink.push("A6", DEFAULT_SEVERITY.A6, `enum has duplicate value at index ${dupAt}`, {
+        jsonpointer: `${ctx.jsonpointer}/enum/${dupAt}`,
+        path: ctx.path, method: ctx.method,
+        fix_hint: "remove the duplicate enum entry",
+      });
+    }
+  }
+}
+
+function collectExamples(s: OpenAPIV3.SchemaObject): Array<{ value: unknown; pointer: string }> {
+  const out: Array<{ value: unknown; pointer: string }> = [];
+  if ((s as { example?: unknown }).example !== undefined) {
+    out.push({ value: (s as { example: unknown }).example, pointer: "example" });
+  }
+  // OpenAPI 3.1 allows examples[]
+  const arr = (s as { examples?: unknown }).examples;
+  if (Array.isArray(arr)) {
+    arr.forEach((v, i) => out.push({ value: v, pointer: `examples/${i}` }));
+  }
+  return out;
+}
+
+function checkValueAgainstSchema(
+  value: unknown,
+  s: OpenAPIV3.SchemaObject,
+  basePointer: string,
+  kind: "example" | "default",
+  isStringy: boolean,
+  isNumeric: boolean,
+  ctx: SchemaContext,
+  sink: RuleSink,
+): void {
+  // basePointer for example/default is sometimes a relative segment like "example".
+  // Prepend ctx.jsonpointer if needed.
+  const jsonpointer = basePointer.startsWith("/")
+    ? basePointer
+    : `${ctx.jsonpointer}/${basePointer}`;
+  const ruleA1 = kind === "example" ? "A1" : "A5";
+  const ruleA2 = kind === "example" ? "A2" : "A5";
+  const ruleA3 = kind === "example" ? "A3" : "A5";
+  const ruleA4 = kind === "example" ? "A4" : "A5";
+
+  // Format check
+  const fmt = (s as { format?: string }).format;
+  if (fmt && isStringy && typeof value === "string") {
+    if (!validateExampleAgainstFormat(value, fmt)) {
+      sink.push(ruleA1, DEFAULT_SEVERITY[ruleA1], `${kind} ${JSON.stringify(value)} violates format: ${fmt}`, {
+        jsonpointer, path: ctx.path, method: ctx.method,
+        fix_hint: `make ${kind} match RFC for format: ${fmt}`,
+      });
+    }
+  }
+
+  // Enum check
+  if (Array.isArray(s.enum) && s.enum.length > 0) {
+    const key = stableKey(value);
+    if (!s.enum.some(e => stableKey(e) === key)) {
+      sink.push(ruleA2, DEFAULT_SEVERITY[ruleA2], `${kind} ${JSON.stringify(value)} is not in enum`, {
+        jsonpointer, path: ctx.path, method: ctx.method,
+        fix_hint: `pick a value from enum: ${JSON.stringify(s.enum)}`,
+      });
+    }
+  }
+
+  // Pattern check
+  const pattern = (s as { pattern?: string }).pattern;
+  if (pattern && typeof value === "string") {
+    let re: RegExp | null = null;
+    try { re = new RegExp(pattern); } catch { /* invalid regex — skip silently */ }
+    if (re && !re.test(value)) {
+      sink.push(ruleA3, DEFAULT_SEVERITY[ruleA3], `${kind} ${JSON.stringify(value)} does not match pattern ${pattern}`, {
+        jsonpointer, path: ctx.path, method: ctx.method,
+        fix_hint: "adjust the example to match the regex",
+      });
+    }
+  }
+
+  // Length / range
+  if (isStringy && typeof value === "string") {
+    const min = (s as { minLength?: number }).minLength;
+    const max = (s as { maxLength?: number }).maxLength;
+    if (typeof min === "number" && value.length < min) {
+      sink.push(ruleA4, DEFAULT_SEVERITY[ruleA4], `${kind} length ${value.length} < minLength ${min}`, {
+        jsonpointer, path: ctx.path, method: ctx.method,
+      });
+    }
+    if (typeof max === "number" && value.length > max) {
+      sink.push(ruleA4, DEFAULT_SEVERITY[ruleA4], `${kind} length ${value.length} > maxLength ${max}`, {
+        jsonpointer, path: ctx.path, method: ctx.method,
+      });
+    }
+  }
+  if (isNumeric && typeof value === "number") {
+    const minimum = (s as { minimum?: number }).minimum;
+    const maximum = (s as { maximum?: number }).maximum;
+    if (typeof minimum === "number" && value < minimum) {
+      sink.push(ruleA4, DEFAULT_SEVERITY[ruleA4], `${kind} ${value} < minimum ${minimum}`, {
+        jsonpointer, path: ctx.path, method: ctx.method,
+      });
+    }
+    if (typeof maximum === "number" && value > maximum) {
+      sink.push(ruleA4, DEFAULT_SEVERITY[ruleA4], `${kind} ${value} > maximum ${maximum}`, {
+        jsonpointer, path: ctx.path, method: ctx.method,
+      });
+    }
+  }
+}
+
+function stableKey(v: unknown): string {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(stableKey).join(",") + "]";
+  const obj = v as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map(k => JSON.stringify(k) + ":" + stableKey(obj[k])).join(",") + "}";
+}
+
+// Suppress unused-export warning: RULE_AFFECTS imported here for future inline
+// affects-tagging if rules grow more local context.
+void RULE_AFFECTS;

package/src/core/lint/rules/heuristics.ts

@@ -0,0 +1,97 @@
+import type { OpenAPIV3 } from "openapi-types";
+import type { Issue, RuleId, Severity, HeuristicConfig } from "../types.ts";
+import { DEFAULT_SEVERITY } from "../types.ts";
+import type { ParamContext, SchemaContext, RequestBodyContext } from "../walker.ts";
+import { normalisedTypes } from "../walker.ts";
+
+interface RuleSink {
+  push(rule: RuleId, severity: Severity, message: string, opts: Partial<Pick<Issue, "path" | "method" | "fix_hint">> & { jsonpointer: string }): void;
+}
+
+/**
+ * B2 — path/query param named like an id (`*_id`, `id`) without `format: uuid`
+ * or `pattern`. Heuristic: only on params whose name matches the id-suffix list.
+ */
+export function runParamHeuristics(ctx: ParamContext, sink: RuleSink, h: HeuristicConfig): void {
+  const p = ctx.param;
+  if (p.in !== "path" && p.in !== "query") return;
+  const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject;
+  const types = normalisedTypes(schema);
+  // B2 only applies to string-shaped ids (uuid). Integer ids are constrained
+  // by minimum/maximum (B3 territory), not by format: uuid.
+  if (types.length > 0 && !types.includes("string")) return;
+  const looksLikeId = p.name === "id" || h.id_suffixes.some(s => p.name.endsWith(s));
+  if (!looksLikeId) return;
+  const fmt = (schema as { format?: string }).format;
+  const hasPattern = !!(schema as { pattern?: string }).pattern;
+  if (fmt !== "uuid" && !hasPattern) {
+    sink.push("B2", DEFAULT_SEVERITY.B2, `id-like param "${p.name}" missing format: uuid or pattern (heuristic)`, {
+      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+      fix_hint: "if the id is a UUID, add format: uuid; otherwise add a pattern",
+    });
+  }
+}
+
+/**
+ * B5/B6 — schema property name suggests a known semantic type, but `format`
+ * is missing.
+ *   - `*_at`, `*_date`, `*_time`, `created`, `updated`, `timestamp` → `date-time`
+ *   - `email`, `url`, `website`, `homepage` → `email` / `uri`
+ */
+export function runSchemaHeuristics(ctx: SchemaContext, sink: RuleSink, h: HeuristicConfig): void {
+  if (ctx.origin !== "property" || !ctx.propertyName) return;
+  const s = ctx.schema;
+  const types = normalisedTypes(s);
+  if (!types.includes("string")) return;
+  const fmt = (s as { format?: string }).format;
+  const name = ctx.propertyName;
+
+  // B5 — timestamp fields
+  const looksLikeTimestamp =
+    h.timestamp_suffixes.some(suf => name.endsWith(suf)) ||
+    ["created", "updated", "timestamp"].includes(name);
+  if (looksLikeTimestamp && fmt !== "date-time" && fmt !== "date") {
+    sink.push("B5", DEFAULT_SEVERITY.B5, `field "${name}" looks like a timestamp but has no format: date-time (heuristic)`, {
+      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+      fix_hint: "add format: date-time so --validate-schema enforces RFC3339",
+    });
+  }
+
+  // B6 — email / url
+  if (name === "email" && fmt !== "email") {
+    sink.push("B6", DEFAULT_SEVERITY.B6, `field "${name}" missing format: email (heuristic)`, {
+      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+      fix_hint: "add format: email",
+    });
+  }
+  if (h.url_names.includes(name) && fmt !== "uri" && fmt !== "url") {
+    sink.push("B6", DEFAULT_SEVERITY.B6, `field "${name}" missing format: uri (heuristic)`, {
+      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+      fix_hint: "add format: uri",
+    });
+  }
+}
+
+/**
+ * B9 — request-body schema declares semantically-required-looking properties
+ * (`name`, `email`, `title`) but `required: []` is empty / absent. Heuristic.
+ */
+export function runRequestBodyHeuristics(ctx: RequestBodyContext, sink: RuleSink, h: HeuristicConfig): void {
+  if (!ctx.requestBody.content) return;
+  for (const [ct, mt] of Object.entries(ctx.requestBody.content)) {
+    if (!ct.includes("json")) continue;
+    const schema = mt.schema as OpenAPIV3.SchemaObject | undefined;
+    if (!schema || !schema.properties) continue;
+    const required = (schema.required ?? []) as string[];
+    const propNames = Object.keys(schema.properties);
+    const semanticPresent = h.semantic_required.filter(n => propNames.includes(n));
+    const semanticMissing = semanticPresent.filter(n => !required.includes(n));
+    if (semanticPresent.length > 0 && semanticMissing.length === semanticPresent.length) {
+      sink.push("B9", DEFAULT_SEVERITY.B9, `request body has properties [${semanticPresent.join(", ")}] but none are required (heuristic)`, {
+        jsonpointer: `${ctx.jsonpointer}/content/${ct.replace(/~/g, "~0").replace(/\//g, "~1")}/schema/required`,
+        path: ctx.path, method: ctx.method,
+        fix_hint: `consider adding to required: [${semanticMissing.map(n => `"${n}"`).join(", ")}]`,
+      });
+    }
+  }
+}