@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/api/schema.ts

@@ -0,0 +1,170 @@
+import type { JsonSchema, KeyField } from "./types.ts"
+
+/** Schemas, examples, and key fields for contracts: inferred from answers seen, checked against answers got. */
+
+const MAX_ERRORS = 10
+const MAX_DEPTH = 8
+
+export function typeOf(v: unknown): string {
+  if (v === null) return "null"
+  if (Array.isArray(v)) return "array"
+  if (typeof v === "number") return Number.isInteger(v) ? "integer" : "number"
+  return typeof v
+}
+
+function types(s: JsonSchema): string[] {
+  return s.type === undefined ? [] : Array.isArray(s.type) ? s.type : [s.type]
+}
+
+/** One schema that every value given fits: a field present in every object is required, one seen as null is nullable. */
+export function inferSchema(values: unknown[], depth = 0): JsonSchema {
+  const seen = values.filter((v) => v !== undefined)
+  if (!seen.length) return {}
+  // An observed 10 can be 10.5 next time (a price): numbers seen in answers are numbers, not integers.
+  const kinds = new Set(seen.map((v) => (typeOf(v) === "integer" ? "number" : typeOf(v))))
+  const nullable = kinds.delete("null")
+  if (!kinds.size) return { type: "null" }
+  if (kinds.size > 1) return { anyOf: [...kinds].map((k) => inferSchema(seen.filter((v) => typeOf(v) === k || (k === "number" && typeof v === "number")), depth)), ...(nullable ? { nullable } : {}) }
+  const [kind] = [...kinds]
+  const out: JsonSchema = { type: kind, ...(nullable ? { nullable } : {}) }
+  if (depth >= MAX_DEPTH) return out
+  if (kind === "object") {
+    const objects = seen.filter((v) => typeOf(v) === "object") as Record<string, unknown>[]
+    const keys = [...new Set(objects.flatMap((o) => Object.keys(o)))]
+    out.properties = Object.fromEntries(keys.map((k) => [k, inferSchema(objects.map((o) => o[k]), depth + 1)]))
+    const required = keys.filter((k) => objects.every((o) => k in o))
+    if (required.length) out.required = required
+  } else if (kind === "array") {
+    const items = (seen.filter(Array.isArray) as unknown[][]).flat()
+    if (items.length) out.items = inferSchema(items.slice(0, 200), depth + 1)
+  } else if (kind === "string") {
+    const strings = seen.filter((v) => typeof v === "string") as string[]
+    if (strings.every((s) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(s))) out.format = "date-time"
+    else if (strings.every((s) => /^\d{4}-\d{2}-\d{2}$/.test(s))) out.format = "date"
+    else if (strings.every((s) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s))) out.format = "uuid"
+    else if (strings.every((s) => /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(s))) out.format = "email"
+  }
+  return out
+}
+
+/** What is wrong with a value against a schema, as "path: problem" lines (none when it fits). */
+export function validate(value: unknown, schema: JsonSchema | undefined, at = "$", errors: string[] = []): string[] {
+  if (!schema || errors.length >= MAX_ERRORS) return errors
+  if (schema.allOf) for (const s of schema.allOf) validate(value, s, at, errors)
+  const alts = schema.anyOf || schema.oneOf
+  if (alts?.length && !(value === null && schema.nullable)) {
+    if (!alts.some((s) => !validate(value, s, at, []).length)) errors.push(`${at}: matches none of ${alts.length} allowed shapes`)
+    return errors
+  }
+  const allowed = types(schema)
+  if (value === null) {
+    if (schema.nullable || allowed.includes("null") || !allowed.length) return errors
+    errors.push(`${at}: is null, expected ${allowed.join(" or ")}`)
+    return errors
+  }
+  const actual = typeOf(value)
+  if (allowed.length && !allowed.includes(actual) && !(actual === "integer" && allowed.includes("number"))) {
+    errors.push(`${at}: is ${actual}, expected ${allowed.join(" or ")}`)
+    return errors
+  }
+  if (schema.enum?.length && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) errors.push(`${at}: ${JSON.stringify(value)} is not one of ${schema.enum.map((e) => JSON.stringify(e)).join(", ")}`)
+  if (actual === "object") {
+    const obj = value as Record<string, unknown>
+    for (const k of schema.required || []) if (!(k in obj)) errors.push(`${at}.${k}: missing`)
+    for (const [k, s] of Object.entries(schema.properties || {})) if (k in obj && obj[k] !== undefined) validate(obj[k], s, `${at}.${k}`, errors)
+  } else if (actual === "array" && schema.items) {
+    ;(value as unknown[]).slice(0, 50).forEach((v, i) => validate(v, schema.items, `${at}[${i}]`, errors))
+  }
+  return errors.slice(0, MAX_ERRORS)
+}
+
+/** The value at a path like data.orders[0].id (or $.data...). */
+export function getPath(value: unknown, path: string): unknown {
+  const parts = path.replace(/^\$\.?/, "").match(/[^.[\]]+|\[\d+\]/g) || []
+  let cur: unknown = value
+  for (const p of parts) {
+    if (cur === null || cur === undefined) return undefined
+    cur = p.startsWith("[") ? (cur as unknown[])[Number(p.slice(1, -1))] : (cur as Record<string, unknown>)[p]
+  }
+  return cur
+}
+
+const KEY_NAME = /(^|_|\b)(id|uuid|key|code|status|state|type|kind|name|title|total|count|amount|price|currency|email|success|ok|result|message)$/i
+const STABLE_NAME = /(^|_)(status|state|type|kind|currency|success|ok|result)$/i
+
+/** Scalar fields under a value, with their paths (into the first element of arrays). */
+function scalars(value: unknown, at = "", depth = 0, out: [string, unknown][] = []): [string, unknown][] {
+  if (depth > 4 || out.length > 200) return out
+  if (Array.isArray(value)) {
+    if (value.length) scalars(value[0], `${at}[0]`, depth + 1, out)
+  } else if (value && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) scalars(v, at ? `${at}.${k}` : k, depth + 1, out)
+  } else if (at) out.push([at, value])
+  return out
+}
+
+/**
+ * The fields worth checking in an answer: ids, statuses, names, totals, and the like, present in every sample, at most
+ * `max`. A value is pinned with `equals` only when every sample had it and the field is a status or type, which does not
+ * change from one call to the next; other values change with data, so only their type is checked.
+ */
+export function keyFields(samples: unknown[], max = 8): KeyField[] {
+  if (!samples.length) return []
+  const all = samples.map((s) => new Map(scalars(s)))
+  const first = scalars(samples[0])
+  const fields: KeyField[] = []
+  const ranked = first
+    .filter(([p]) => all.every((m) => m.has(p)))
+    .map(([p, v]) => ({ p, v, leaf: p.split(/[.[]/).pop()!.replace(/]$/, ""), depth: p.split(/[.[]/).length }))
+    .filter((f) => KEY_NAME.test(f.leaf))
+    .sort((a, b) => a.depth - b.depth)
+  for (const f of ranked) {
+    if (fields.length >= max) break
+    const values = all.map((m) => m.get(f.p))
+    const same = values.every((v) => JSON.stringify(v) === JSON.stringify(values[0]))
+    const pinned = same && STABLE_NAME.test(f.leaf) && f.v !== null && typeof f.v !== "object"
+    fields.push({ path: f.p, type: typeof f.v === "number" ? "number" : typeOf(f.v), ...(pinned ? { equals: f.v } : {}) })
+  }
+  return fields
+}
+
+/** Check key fields against an answer: "path: problem" for each one that is wrong. */
+export function checkFields(value: unknown, fields: KeyField[]): string[] {
+  const out: string[] = []
+  for (const f of fields) {
+    const v = getPath(value, f.path)
+    if (v === undefined) out.push(`${f.path}: missing`)
+    else if (f.equals !== undefined && JSON.stringify(v) !== JSON.stringify(f.equals)) out.push(`${f.path}: is ${JSON.stringify(v)}, expected ${JSON.stringify(f.equals)}`)
+    else if (f.type && v !== null && typeOf(v) !== f.type && !(f.type === "number" && typeOf(v) === "integer")) out.push(`${f.path}: is ${typeOf(v)}, expected ${f.type}`)
+  }
+  return out
+}
+
+/** A value that fits a schema, from its examples where it has them: a request body to start from. */
+export function exampleFor(schema: JsonSchema | undefined, depth = 0, name = ""): unknown {
+  if (!schema) return null
+  if (schema.example !== undefined) return schema.example
+  if (schema.enum?.length) return schema.enum[0]
+  const alt = schema.anyOf?.[0] || schema.oneOf?.[0]
+  if (alt) return exampleFor(alt, depth, name)
+  if (schema.allOf?.length) return Object.assign({}, ...schema.allOf.map((s) => exampleFor(s, depth, name)).filter((v) => v && typeof v === "object"))
+  const t = types(schema).find((x) => x !== "null") || (schema.properties ? "object" : schema.items ? "array" : "string")
+  if (depth > 5) return t === "array" ? [] : t === "object" ? {} : null
+  switch (t) {
+    case "object":
+      return Object.fromEntries(Object.entries(schema.properties || {}).map(([k, s]) => [k, exampleFor(s, depth + 1, k)]))
+    case "array":
+      return schema.items ? [exampleFor(schema.items, depth + 1, name)] : []
+    case "integer":
+    case "number":
+      return 1
+    case "boolean":
+      return true
+    default:
+      if (schema.format === "date-time") return "2026-01-01T00:00:00Z"
+      if (schema.format === "date") return "2026-01-01"
+      if (schema.format === "email" || /email/i.test(name)) return "user@example.com"
+      if (schema.format === "uuid") return "00000000-0000-0000-0000-000000000001"
+      return name ? `sample-${name}` : "sample"
+  }
+}