@kirrosh/zond 0.22.0 → 0.23.0

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(", ")}]`,
+      });
+    }
+  }
+}

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

@@ -0,0 +1,109 @@
+import type { OpenAPIV3 } from "openapi-types";
+import type { Issue, RuleId, Severity, HeuristicConfig } from "../types.ts";
+import { DEFAULT_SEVERITY } from "../types.ts";
+import type { ParamContext, ResponseContext, RequestBodyContext, SchemaContext } 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;
+}
+
+/**
+ * Group B — formal strictness gaps on parameters.
+ * B1 (path-param without format/pattern) → high.
+ * B3 (integer-param without min/max — pagination names get medium, others low).
+ * B4 (cursor-name string-param without minLength: 1) → low.
+ */
+export function runParamStrictnessRules(ctx: ParamContext, sink: RuleSink, h: HeuristicConfig): void {
+  const p = ctx.param;
+  const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject;
+  const types = normalisedTypes(schema);
+
+  if (p.in === "path" && types.includes("string")) {
+    // Only flag string path-params: integer/number params have type-level
+    // constraints (minimum/maximum, multipleOf), so missing format/pattern
+    // is benign there.
+    const hasFormat = !!(schema as { format?: string }).format;
+    const hasPattern = !!(schema as { pattern?: string }).pattern;
+    if (!hasFormat && !hasPattern) {
+      sink.push("B1", DEFAULT_SEVERITY.B1, `path-param "${p.name}" missing format/pattern`, {
+        jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+        fix_hint: "add format: uuid (or pattern: ^...$) so SDKs reject malformed values client-side",
+      });
+    }
+  }
+
+  if (types.includes("integer") || types.includes("number")) {
+    const hasMin = typeof (schema as { minimum?: unknown }).minimum === "number";
+    const hasMax = typeof (schema as { maximum?: unknown }).maximum === "number";
+    if (!hasMin || !hasMax) {
+      const isPagination = h.pagination_names.some(n => n.toLowerCase() === p.name.toLowerCase());
+      const sev: Severity = isPagination ? "medium" : "low";
+      const which = !hasMin && !hasMax ? "minimum/maximum" : !hasMin ? "minimum" : "maximum";
+      sink.push("B3", sev, `${p.in}-param "${p.name}" (${types.join("|")}) missing ${which}`, {
+        jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+        fix_hint: `add ${which} so out-of-range values are rejected before reaching the server`,
+      });
+    }
+  }
+
+  if (types.includes("string") && h.cursor_names.some(n => n.toLowerCase() === p.name.toLowerCase())) {
+    const minLen = (schema as { minLength?: unknown }).minLength;
+    if (typeof minLen !== "number" || minLen < 1) {
+      sink.push("B4", DEFAULT_SEVERITY.B4, `cursor-param "${p.name}" missing minLength: 1`, {
+        jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+        fix_hint: "add minLength: 1 so empty cursor strings are rejected client-side",
+      });
+    }
+  }
+}
+
+/**
+ * B7 — 2xx response without a JSON schema. `--validate-schema` silently skips
+ * such endpoints, masking real type drift.
+ */
+export function runResponseStrictnessRules(ctx: ResponseContext, sink: RuleSink): void {
+  const status = parseInt(ctx.status, 10);
+  if (!Number.isFinite(status) || status < 200 || status >= 300) return;
+  // 204 No Content / 205 Reset Content / 304 Not Modified by definition carry no body.
+  if (status === 204 || status === 205) return;
+  const r = ctx.response;
+  const hasJsonSchema = r.content && Object.entries(r.content).some(([ct, mt]) => {
+    return ct.includes("json") && (mt.schema !== undefined);
+  });
+  if (!hasJsonSchema) {
+    sink.push("B7", DEFAULT_SEVERITY.B7, `${ctx.status} response missing JSON schema`, {
+      jsonpointer: ctx.jsonpointer, path: ctx.path, method: ctx.method,
+      fix_hint: "declare content.application/json.schema so --validate-schema can verify the response",
+    });
+  }
+}
+
+/**
+ * B8 — request-body root schema without explicit `additionalProperties`.
+ * Informational; tied to mass-assignment risk (T58).
+ */
+export function runRequestBodyStrictnessRules(ctx: RequestBodyContext, sink: RuleSink): 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) continue;
+    const ap = (schema as { additionalProperties?: unknown }).additionalProperties;
+    if (ap === undefined) {
+      sink.push("B8", DEFAULT_SEVERITY.B8, `request body schema does not set additionalProperties`, {
+        jsonpointer: `${ctx.jsonpointer}/content/${ct.replace(/~/g, "~0").replace(/\//g, "~1")}/schema`,
+        path: ctx.path, method: ctx.method,
+        fix_hint: "set additionalProperties: false to make mass-assignment vectors explicit",
+      });
+    }
+  }
+}
+
+/**
+ * Schema-level B-rules that aren't on parameters: currently empty placeholder
+ * for future expansion (e.g. response-body B5 picked up via heuristics).
+ */
+export function runSchemaStrictnessRules(_ctx: SchemaContext, _sink: RuleSink): void {
+  // intentionally empty — heuristic schema-level checks live in heuristics.ts
+}

package/src/core/lint/types.ts

@@ -0,0 +1,96 @@
+import type { RecommendedAction } from "../diagnostics/failure-hints.ts";
+
+// Severity unified in src/core/severity (ARV-250). Lint historically used a
+// 3-tier ladder (high/medium/low) without 'critical' or 'info'. ARV-255
+// will downgrade most lint findings to info/low; this re-export aligns the
+// type but does not yet change DEFAULT_SEVERITY values per rule.
+import type { Severity } from "../severity/index.ts";
+export type { Severity };
+
+export type { RecommendedAction };
+
+export type RuleId =
+  | "A1" | "A2" | "A3" | "A4" | "A5" | "A6"
+  | "B1" | "B2" | "B3" | "B4" | "B5" | "B6" | "B7" | "B8" | "B9";
+
+export const ALL_RULES: RuleId[] = [
+  "A1", "A2", "A3", "A4", "A5", "A6",
+  "B1", "B2", "B3", "B4", "B5", "B6", "B7", "B8", "B9",
+];
+
+/**
+ * ARV-255 (m-21 pivot): all lint findings cap at LOW/INFO. Static spec
+ * analysis is hygiene — no runtime evidence, no exploit pathway, no
+ * security or contract drift. The old "HIGH on missing additionalProperties"
+ * inflation made the audit report unreadable; now lint lives in the
+ * hygiene category and surfaces via `zond lint` separately.
+ *
+ * Tier assignment:
+ * - `low`: real spec violations (format mismatch in example, missing
+ *   path-param format, response without schema). Worth fixing, but not
+ *   security.
+ * - `info`: style and documentation gaps (additionalProperties, naming,
+ *   missing examples, optional descriptions). Could be intentional.
+ */
+export const DEFAULT_SEVERITY: Record<RuleId, Severity> = {
+  A1: "low",    A2: "low",    A3: "info",   A4: "info",   A5: "info",   A6: "info",
+  B1: "low",    B2: "info",   B3: "info",   B4: "info",   B5: "info",
+  B6: "info",   B7: "low",    B8: "info",   B9: "info",
+};
+
+export interface Issue {
+  rule: RuleId;
+  severity: Severity;
+  path?: string;
+  method?: string;
+  jsonpointer: string;
+  message: string;
+  fix_hint?: string;
+  affects?: string[];
+  /** TASK-294: agent-routable action — always `fix_spec` for lint issues
+   *  (the spec is the source of truth and the only thing to edit). */
+  recommended_action: RecommendedAction;
+}
+
+export type RuleSetting = "off" | Severity;
+
+export interface HeuristicConfig {
+  id_suffixes: string[];
+  timestamp_suffixes: string[];
+  url_names: string[];
+  cursor_names: string[];
+  pagination_names: string[];
+  semantic_required: string[];
+}
+
+export interface LintConfig {
+  rules: Partial<Record<RuleId, RuleSetting>>;
+  heuristics: HeuristicConfig;
+  ignore_paths: string[];
+  include_paths?: string[];
+  max_issues?: number;
+}
+
+export interface LintStats {
+  total: number;
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  info: number;
+  endpoints: number;
+}
+
+export interface LintResult {
+  issues: Issue[];
+  stats: LintStats;
+}
+
+export const DEFAULT_HEURISTICS: HeuristicConfig = {
+  id_suffixes: ["_id", "Id", "ID"],
+  timestamp_suffixes: ["_at", "_date", "_time"],
+  url_names: ["url", "website", "homepage", "callback_url", "webhook_url"],
+  cursor_names: ["after", "before", "cursor", "token", "page_token", "next_token"],
+  pagination_names: ["limit", "offset", "page", "size", "count", "per_page", "page_size"],
+  semantic_required: ["name", "email", "title"],
+};