shapecraft 1.0.0

package/packages/core/src/shape/transforms/json-schema/transform.ts

@@ -0,0 +1,882 @@
+import { annotate, shapes } from "../../shape";
+import { NumberTag } from "../../tags";
+import {
+  JSONSchema,
+  JSONSchemaDefinition,
+  JSONSchemaTypeName,
+  ShapecraftMeta,
+} from "./types";
+
+const INT_RANGES: Record<string, { minimum?: number; maximum?: number }> = {
+  int8: { minimum: -128, maximum: 127 },
+  uint8: { minimum: 0, maximum: 255 },
+  int16: { minimum: -32768, maximum: 32767 },
+  uint16: { minimum: 0, maximum: 65535 },
+  int32: { minimum: -2_147_483_648, maximum: 2_147_483_647 },
+  uint32: { minimum: 0, maximum: 4_294_967_295 },
+  int64: { minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER },
+  uint64: { minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+  int: {},
+};
+
+const FLOAT32_MAX = 3.4028234663852886e38;
+
+const FLOAT_RANGES: Record<string, { minimum?: number; maximum?: number }> = {
+  float32: { minimum: -FLOAT32_MAX, maximum: FLOAT32_MAX },
+  float64: {},
+  float: {},
+  number: {},
+};
+
+const numberTagRange = (
+  tag: NumberTag,
+): { type: "integer" | "number"; minimum?: number; maximum?: number } => {
+  if (tag in INT_RANGES) return { type: "integer", ...(INT_RANGES[tag] ?? {}) };
+  return { type: "number", ...(FLOAT_RANGES[tag] ?? {}) };
+};
+
+const attachMeta = (out: JSONSchema, meta: ShapecraftMeta): JSONSchema =>
+  Object.keys(meta).length === 0 ? out : { ...out, "x-shapecraft": meta };
+
+const isLiteralScalar = (s: shapes.Shape): boolean =>
+  (s.type === "string" || s.type === "number" || s.type === "boolean") &&
+  s.literal === true;
+
+type ModuleCtx = {
+  tablesByName: Record<string, shapes.ShapeMapping>;
+  anchorOf: Record<string, string | undefined>;
+};
+
+const refTo = (tableName: string, ctx: ModuleCtx): string => {
+  const anchor = ctx.anchorOf[tableName];
+  return anchor !== undefined ? `#${anchor}` : `#/$defs/${tableName}`;
+};
+
+const convert = (
+  shape: shapes.Shape,
+  topLevel: boolean,
+  modCtx?: ModuleCtx,
+): JSONSchema => {
+  if (
+    modCtx !== undefined &&
+    shape.anno.foreign !== undefined &&
+    shape.anno.foreign.table in modCtx.tablesByName
+  ) {
+    return { $ref: refTo(shape.anno.foreign.table, modCtx) };
+  }
+
+  const meta: ShapecraftMeta = {};
+  if (shape.anno.unique) meta.unique = true;
+  if (shape.anno.primary) meta.primary = true;
+  if (shape.anno.foreign) meta.foreign = shape.anno.foreign;
+  if (topLevel && shape.anno.optional) meta.optional = true;
+
+  let out: JSONSchema = {};
+  switch (shape.type) {
+    case "string": {
+      if (shape.literal) {
+        out = { const: shape.input as string };
+        break;
+      }
+      out = { type: "string" };
+      if (shape.anno.min !== undefined) out.minLength = shape.anno.min;
+      if (shape.anno.max !== undefined) out.maxLength = shape.anno.max;
+      if (shape.anno.pattern !== undefined) {
+        out.pattern =
+          shape.anno.pattern instanceof RegExp ?
+            shape.anno.pattern.source
+          : shape.anno.pattern;
+      }
+      if (shape.anno.format !== undefined) out.format = shape.anno.format;
+      break;
+    }
+    case "number": {
+      if (shape.literal) {
+        out = { const: shape.input as number };
+        break;
+      }
+      const r = numberTagRange(shape.tag);
+      out = { type: r.type };
+      if (r.minimum !== undefined) out.minimum = r.minimum;
+      if (r.maximum !== undefined) out.maximum = r.maximum;
+      if (shape.anno.min !== undefined)
+        out.minimum =
+          out.minimum === undefined ?
+            shape.anno.min
+          : Math.max(out.minimum, shape.anno.min);
+      if (shape.anno.max !== undefined)
+        out.maximum =
+          out.maximum === undefined ?
+            shape.anno.max
+          : Math.min(out.maximum, shape.anno.max);
+      meta.numberTag = shape.tag;
+      break;
+    }
+    case "boolean": {
+      out =
+        shape.literal ? { const: shape.input as boolean } : { type: "boolean" };
+      break;
+    }
+    case "nil":
+      out = { type: "null" };
+      break;
+    case "undefined":
+      out = {};
+      meta.kind = "undefined";
+      break;
+    case "unknown":
+      out = {};
+      break;
+    case "date":
+      out = { type: "string", format: "date-time" };
+      meta.kind = "date";
+      break;
+    case "binary":
+      out = { type: "string", contentEncoding: "base64" };
+      meta.kind = "binary";
+      break;
+    case "array": {
+      out = { type: "array", items: convert(shape.input, false, modCtx) };
+      if (shape.anno.min !== undefined) out.minItems = shape.anno.min;
+      if (shape.anno.max !== undefined) out.maxItems = shape.anno.max;
+      if (shape.anno.uniqueItems) out.uniqueItems = true;
+      break;
+    }
+    case "vector": {
+      out = {
+        type: "array",
+        items: convert(shape.input.format, false, modCtx),
+        minItems: shape.input.dims,
+        maxItems: shape.input.dims,
+      };
+      meta.kind = "vector";
+      meta.vectorDims = shape.input.dims;
+      break;
+    }
+    case "tuple": {
+      out = {
+        type: "array",
+        prefixItems: shape.input.map((s) => convert(s, false, modCtx)),
+        minItems: shape.input.length,
+        maxItems: shape.input.length,
+      };
+      meta.kind = "tuple";
+      meta.tupleLen = shape.input.length;
+      break;
+    }
+    case "range": {
+      const itemSchema = convert(shape.input, false, modCtx);
+      out = {
+        type: "object",
+        properties: {
+          lower: { anyOf: [itemSchema, { type: "null" }] },
+          upper: { anyOf: [itemSchema, { type: "null" }] },
+          lowerInclusive: { type: "boolean" },
+          upperInclusive: { type: "boolean" },
+        },
+        required: ["lower", "upper", "lowerInclusive", "upperInclusive"],
+        additionalProperties: false,
+      };
+      meta.kind = "range";
+      break;
+    }
+    case "mapping": {
+      const properties: Record<string, JSONSchema> = {};
+      const required: string[] = [];
+      for (const [k, child] of Object.entries(shape.input)) {
+        properties[k] = convert(child, false, modCtx);
+        if (!child.anno.optional) required.push(k);
+      }
+      out = { type: "object", properties, additionalProperties: false };
+      if (required.length > 0) out.required = required;
+      break;
+    }
+    case "record": {
+      const [keyShape, valShape] = shape.input;
+      out = {
+        type: "object",
+        additionalProperties: convert(valShape, false, modCtx),
+      };
+      if (keyShape.type === "string" && keyShape.anno.pattern !== undefined) {
+        const src =
+          keyShape.anno.pattern instanceof RegExp ?
+            keyShape.anno.pattern.source
+          : keyShape.anno.pattern;
+        out.propertyNames = { type: "string", pattern: src };
+      } else if (keyShape.type === "number") {
+        out.propertyNames = { type: "string", pattern: "^-?\\d+(\\.\\d+)?$" };
+      }
+      break;
+    }
+    case "union": {
+      const variants = Array.from(shape.input) as shapes.Shape[];
+      if (variants.length > 0 && variants.every(isLiteralScalar)) {
+        out = {
+          enum: variants.map(
+            (v) =>
+              (
+                v as
+                  | shapes.ShapeString
+                  | shapes.ShapeNumber
+                  | shapes.ShapeBoolean
+              ).input as string | number | boolean,
+          ),
+        };
+      } else {
+        out = { anyOf: variants.map((v) => convert(v, false, modCtx)) };
+      }
+      break;
+    }
+    case "module": {
+      const tablesByName: Record<string, shapes.ShapeMapping> = {};
+      const anchorOf: Record<string, string | undefined> = {};
+      for (const [k, table] of Object.entries(shape.input)) {
+        tablesByName[k] = table;
+        const a = table.anno.meta?.anchor;
+        anchorOf[k] = typeof a === "string" ? a : undefined;
+      }
+      const ctx: ModuleCtx = { tablesByName, anchorOf };
+      const defs: Record<string, JSONSchema> = {};
+      for (const [k, table] of Object.entries(shape.input)) {
+        const sub = convert(table, false, ctx);
+        const anchor = anchorOf[k];
+        defs[k] = anchor !== undefined ? { $anchor: anchor, ...sub } : sub;
+      }
+      out = { $defs: defs };
+      break;
+    }
+  }
+
+  if (shape.anno.title !== undefined) out.title = shape.anno.title;
+  if (shape.anno.description !== undefined)
+    out.description = shape.anno.description;
+
+  return attachMeta(out, meta);
+};
+
+export const toJSONSchema = (shape: shapes.Shape): JSONSchema =>
+  convert(shape, true);
+
+const numberByTag = (tag: NumberTag): shapes.ShapeNumber => {
+  switch (tag) {
+    case "int":
+      return shapes.int();
+    case "int8":
+      return shapes.int8();
+    case "uint8":
+      return shapes.uint8();
+    case "int16":
+      return shapes.int16();
+    case "uint16":
+      return shapes.uint16();
+    case "int32":
+      return shapes.int32();
+    case "uint32":
+      return shapes.uint32();
+    case "int64":
+      return shapes.int64();
+    case "uint64":
+      return shapes.uint64();
+    case "float":
+      return shapes.float();
+    case "float32":
+      return shapes.float32();
+    case "float64":
+      return shapes.float64();
+    default:
+      return shapes.number();
+  }
+};
+
+const naturalRangeForTag = (
+  tag: NumberTag,
+): { minimum?: number; maximum?: number } => {
+  if (tag in INT_RANGES) return INT_RANGES[tag] ?? {};
+  return FLOAT_RANGES[tag] ?? {};
+};
+
+const asSchema = (def: JSONSchemaDefinition | undefined): JSONSchema => {
+  if (def === undefined || def === true) return {};
+  if (def === false) return {};
+  return def;
+};
+
+// JSON Schema doesn't require `type` — when `properties`/`items` are present,
+// the type is implied. Infer it so we don't fall through to `unknown`.
+const effectiveType = (s: JSONSchema): JSONSchemaTypeName | undefined => {
+  if (typeof s.type === "string") return s.type;
+  if (Array.isArray(s.type) && s.type.length > 0) return s.type[0];
+  if (
+    s.properties !== undefined ||
+    s.additionalProperties !== undefined ||
+    s.patternProperties !== undefined ||
+    s.required !== undefined ||
+    s.propertyNames !== undefined ||
+    s.minProperties !== undefined ||
+    s.maxProperties !== undefined
+  )
+    return "object";
+  if (
+    s.items !== undefined ||
+    s.uniqueItems !== undefined ||
+    s.minItems !== undefined ||
+    s.maxItems !== undefined
+  )
+    return "array";
+  return undefined;
+};
+
+const literalFromValue = (v: unknown): shapes.Shape => {
+  if (typeof v === "string" || typeof v === "number" || typeof v === "boolean")
+    return shapes.literal(v);
+  if (v === null) return shapes.nil();
+  return shapes.unknown();
+};
+
+// oneOf/anyOf variants are often refinements on a sibling `type` (e.g.
+// `{type: "string", oneOf: [{format: "ipv4"}, ...]}`). Inherit the parent's
+// effective type into variants that don't declare their own, so each variant
+// resolves to a real shape rather than `unknown`. Drop any variants that
+// still resolve to `unknown` after that, and fall back to type-based handling
+// if nothing substantive survives.
+const combinatorBase = (
+  schema: JSONSchema,
+  idx: RefIndex | undefined,
+): shapes.Shape | undefined => {
+  const variantsRaw = schema.anyOf ?? schema.oneOf;
+  if (variantsRaw === undefined || variantsRaw.length === 0) return undefined;
+  const parentType = effectiveType(schema);
+  const all = variantsRaw.map((v) => {
+    const vs = asSchema(v);
+    const merged: JSONSchema =
+      (
+        vs.type === undefined &&
+        parentType !== undefined &&
+        vs.$ref === undefined
+      ) ?
+        { type: parentType, ...vs }
+      : vs;
+    return convertFrom(merged, false, idx);
+  });
+  const substantive = all.filter((s) => s.type !== "unknown");
+  if (substantive.length === 0) return undefined;
+  if (substantive.length === 1) return substantive[0];
+  return shapes.union(substantive);
+};
+
+const convertFrom = (
+  schema: JSONSchema,
+  topLevel: boolean,
+  idx?: RefIndex,
+): shapes.Shape => {
+  if (idx !== undefined && typeof schema.$ref === "string") {
+    const key = resolveRef(schema.$ref, idx);
+    const target = key !== null ? idx.defs[key] : undefined;
+    if (target !== undefined) return convertFrom(target, false, idx);
+    return shapes.unknown();
+  }
+
+  const meta: ShapecraftMeta = schema["x-shapecraft"] ?? {};
+
+  let base: shapes.Shape;
+  const combinator = combinatorBase(schema, idx);
+
+  if (schema.const !== undefined) {
+    base = literalFromValue(schema.const);
+  } else if (
+    schema.enum !== undefined &&
+    Array.isArray(schema.enum) &&
+    schema.enum.length > 0
+  ) {
+    base = shapes.union(schema.enum.map(literalFromValue));
+  } else if (combinator !== undefined) {
+    base = combinator;
+  } else if (meta.kind === "undefined") {
+    base = shapes.notDefined();
+  } else if (meta.kind === "date") {
+    base = shapes.date();
+  } else if (meta.kind === "binary") {
+    base = shapes.binary();
+  } else if (meta.kind === "vector") {
+    const itemSchema = asSchema(
+      Array.isArray(schema.items) ? schema.items[0] : schema.items,
+    );
+    const itemTag = itemSchema["x-shapecraft"]?.numberTag ?? "number";
+    const format = numberByTag(itemTag);
+    const dims = meta.vectorDims ?? schema.minItems ?? 0;
+    base = shapes.vector(dims, format);
+  } else if (
+    meta.kind === "tuple" ||
+    Array.isArray(schema.prefixItems) ||
+    (Array.isArray(schema.items) && schema.items.length >= 2)
+  ) {
+    const items =
+      schema.prefixItems ?? (Array.isArray(schema.items) ? schema.items : []);
+    base = shapes.tuple(
+      ...items.map((s) => convertFrom(asSchema(s), false, idx)),
+    );
+  } else if (meta.kind === "range") {
+    const lowerDef = schema.properties?.["lower"];
+    const lowerSchema = asSchema(lowerDef);
+    const variants = lowerSchema.anyOf ?? lowerSchema.oneOf ?? undefined;
+    const inner =
+      variants !== undefined ?
+        (variants.map((v) => asSchema(v)).find((v) => v.type !== "null") ?? {})
+      : lowerSchema;
+    base = shapes.range(convertFrom(inner, false, idx));
+  } else {
+    switch (effectiveType(schema)) {
+      case "null":
+        base = shapes.nil();
+        break;
+      case "boolean":
+        base = shapes.boolean();
+        break;
+      case "string": {
+        if (
+          schema.format === "date-time" ||
+          schema.format === "date" ||
+          schema.format === "timestamp" ||
+          schema.format === "time"
+        ) {
+          base = shapes.date();
+        } else if (schema.contentEncoding === "base64") {
+          base = shapes.binary();
+        } else {
+          let s: shapes.ShapeString = shapes.string();
+          if (schema.pattern !== undefined)
+            s = annotate.pattern(s, schema.pattern);
+          if (schema.minLength !== undefined)
+            s = annotate.min(s, schema.minLength);
+          if (schema.maxLength !== undefined)
+            s = annotate.max(s, schema.maxLength);
+          if (schema.format !== undefined)
+            s = annotate.format(s, schema.format);
+          base = s;
+        }
+        break;
+      }
+      case "integer":
+      case "number": {
+        const tag: NumberTag =
+          meta.numberTag ?? (schema.type === "integer" ? "int" : "number");
+        let n: shapes.ShapeNumber = numberByTag(tag);
+        const natural = naturalRangeForTag(tag);
+        if (
+          schema.minimum !== undefined &&
+          (natural.minimum === undefined || schema.minimum !== natural.minimum)
+        )
+          n = annotate.min(n, schema.minimum);
+        if (
+          schema.maximum !== undefined &&
+          (natural.maximum === undefined || schema.maximum !== natural.maximum)
+        )
+          n = annotate.max(n, schema.maximum);
+        base = n;
+        break;
+      }
+      case "array": {
+        const itemSchema = asSchema(
+          Array.isArray(schema.items) ? schema.items[0] : schema.items,
+        );
+        let a: shapes.ShapeArray = shapes.array(
+          convertFrom(itemSchema, false, idx),
+        );
+        if (schema.minItems !== undefined) a = annotate.min(a, schema.minItems);
+        if (schema.maxItems !== undefined) a = annotate.max(a, schema.maxItems);
+        if (schema.uniqueItems === true) a = annotate.uniqueItems(a);
+        base = a;
+        break;
+      }
+      case "object": {
+        if (schema.properties !== undefined) {
+          const required = new Set(schema.required ?? []);
+          const rec: Record<string, shapes.Shape> = {};
+          for (const [k, v] of Object.entries(schema.properties)) {
+            let child = convertFrom(asSchema(v), false, idx);
+            if (!required.has(k)) child = annotate.optional(child);
+            rec[k] = child;
+          }
+          base = shapes.mapping(rec);
+        } else if (
+          schema.additionalProperties !== undefined &&
+          schema.additionalProperties !== false
+        ) {
+          const valShape = convertFrom(
+            asSchema(schema.additionalProperties),
+            false,
+            idx,
+          );
+          const pn =
+            (
+              schema.propertyNames !== undefined &&
+              schema.propertyNames !== true &&
+              schema.propertyNames !== false
+            ) ?
+              schema.propertyNames
+            : undefined;
+          let keyShape: shapes.ShapeKeyable;
+          if (pn?.pattern === "^-?\\d+(\\.\\d+)?$") {
+            keyShape = shapes.number();
+          } else if (pn?.pattern !== undefined) {
+            keyShape = annotate.pattern(shapes.string(), pn.pattern);
+          } else {
+            keyShape = shapes.string();
+          }
+          base = shapes.record(keyShape, valShape);
+        } else {
+          base = shapes.unknown();
+        }
+        break;
+      }
+      default:
+        base = shapes.unknown();
+    }
+  }
+
+  if (meta.unique === true) base = annotate.unique(base);
+  if (meta.primary === true) base = annotate.primary(base);
+  if (meta.foreign !== undefined)
+    base = annotate.foreign(base, meta.foreign.table, meta.foreign.column);
+  if (topLevel && meta.optional === true) base = annotate.optional(base);
+  if (schema.title !== undefined) base = annotate.titled(base, schema.title);
+  if (schema.description !== undefined)
+    base = annotate.described(base, schema.description);
+
+  return base;
+};
+
+type RefIndex = {
+  defs: Record<string, JSONSchema>;
+  byAnchor: Map<string, string>;
+  byPath: Map<string, string>;
+};
+
+type PkInfo = {
+  column: string;
+  shape: shapes.Shape;
+  autoInjected: boolean;
+};
+
+type PkRegistry = Record<string, PkInfo>;
+
+type JunctionSpec = {
+  parentTable: string;
+  property: string;
+  refTable: string;
+};
+
+const buildRefIndex = (schema: JSONSchema): RefIndex => {
+  const defs: Record<string, JSONSchema> = {};
+  const byAnchor = new Map<string, string>();
+  const byPath = new Map<string, string>();
+  const collect = (
+    rawDefs: Record<string, JSONSchemaDefinition> | undefined,
+    pathPrefix: string,
+  ) => {
+    if (rawDefs === undefined) return;
+    for (const [key, defDef] of Object.entries(rawDefs)) {
+      if (typeof defDef !== "object" || defDef === null) continue;
+      const def = defDef as JSONSchema;
+      if (defs[key] === undefined) defs[key] = def;
+      byPath.set(`${pathPrefix}${key}`, key);
+      if (def.$anchor !== undefined) byAnchor.set(def.$anchor, key);
+    }
+  };
+  collect(schema.$defs, "#/$defs/");
+  collect(schema.definitions, "#/definitions/");
+  return { defs, byAnchor, byPath };
+};
+
+const resolveRef = (ref: string, idx: RefIndex): string | null => {
+  if (ref.startsWith("#/$defs/") || ref.startsWith("#/definitions/"))
+    return idx.byPath.get(ref) ?? null;
+  if (ref.startsWith("#") && !ref.startsWith("#/"))
+    return idx.byAnchor.get(ref.slice(1)) ?? null;
+  return null;
+};
+
+const detectPkPropertyName = (
+  defName: string,
+  def: JSONSchema,
+): string | null => {
+  const required = new Set(def.required ?? []);
+  const props = def.properties ?? {};
+  const lower = defName.toLowerCase();
+  const candidates = ["id", `${lower}id`, `${lower}_id`];
+  for (const cand of candidates) {
+    for (const propName of Object.keys(props)) {
+      if (propName.toLowerCase() === cand && required.has(propName))
+        return propName;
+    }
+  }
+  return null;
+};
+
+const bareTypeShape = (s: shapes.Shape): shapes.Shape => {
+  switch (s.type) {
+    case "number":
+      return numberByTag(s.tag);
+    case "string":
+      return shapes.string();
+    case "boolean":
+      return shapes.boolean();
+    case "date":
+      return shapes.date();
+    case "binary":
+      return shapes.binary();
+    default:
+      return s;
+  }
+};
+
+const lastSegment = (id: string): string => {
+  const slash = id.lastIndexOf("/");
+  const tail = slash >= 0 ? id.slice(slash + 1) : id;
+  const dot = tail.indexOf(".");
+  return dot >= 0 ? tail.slice(0, dot) : tail;
+};
+
+const topLevelTableName = (schema: JSONSchema): string => {
+  if (typeof schema.title === "string" && schema.title.length > 0)
+    return schema.title;
+  if (typeof schema.$id === "string" && schema.$id.length > 0)
+    return lastSegment(schema.$id);
+  return "root";
+};
+
+const buildPkInfo = (
+  defKey: string,
+  def: JSONSchema,
+  idx: RefIndex,
+): PkInfo => {
+  const pkName = detectPkPropertyName(defKey, def);
+  if (pkName !== null) {
+    const propSchema = asSchema(def.properties?.[pkName]);
+    const propShape = convertFrom(propSchema, false, idx);
+    return {
+      column: pkName,
+      shape: bareTypeShape(propShape),
+      autoInjected: false,
+    };
+  }
+  const props = def.properties ?? {};
+  const hasLiteralId = Object.keys(props).some((n) => n.toLowerCase() === "id");
+  if (hasLiteralId) {
+    throw new Error(
+      `def '${defKey}' has an 'id' field that doesn't qualify as PK (not in required[])`,
+    );
+  }
+  return {
+    column: "id",
+    shape: shapes.int64(),
+    autoInjected: true,
+  };
+};
+
+const convertDefToTable = (
+  defKey: string,
+  def: JSONSchema,
+  idx: RefIndex,
+  pkRegistry: PkRegistry,
+  junctions: JunctionSpec[],
+): shapes.ShapeMapping => {
+  const required = new Set(def.required ?? []);
+  const props = def.properties ?? {};
+  const pkInfo = pkRegistry[defKey];
+
+  const rec: Record<string, shapes.Shape> = {};
+
+  if (pkInfo !== undefined && pkInfo.autoInjected) {
+    rec[pkInfo.column] = annotate.autoIncremented(
+      annotate.primary(shapes.int64()),
+    );
+  }
+
+  for (const [propName, propSchemaRaw] of Object.entries(props)) {
+    const propSchema = asSchema(propSchemaRaw);
+
+    if (typeof propSchema.$ref === "string") {
+      const targetKey = resolveRef(propSchema.$ref, idx);
+      const targetDef = targetKey !== null ? idx.defs[targetKey] : undefined;
+      if (targetKey === null || targetDef === undefined) {
+        let s: shapes.Shape = shapes.unknown();
+        if (!required.has(propName)) s = annotate.optional(s);
+        rec[propName] = s;
+        continue;
+      }
+      if (targetDef.type === "object") {
+        const targetPk = pkRegistry[targetKey];
+        if (targetPk === undefined || targetPk.shape.type === "unknown") {
+          throw new Error(
+            `def '${defKey}': $ref target '${targetKey}' has no usable PK type for FK`,
+          );
+        }
+        let fk: shapes.Shape = annotate.foreign(
+          bareTypeShape(targetPk.shape),
+          targetKey,
+          targetPk.column,
+        );
+        if (!required.has(propName)) fk = annotate.optional(fk);
+        rec[propName] = fk;
+        continue;
+      }
+      let inlined = convertFrom(targetDef, false, idx);
+      if (!required.has(propName)) inlined = annotate.optional(inlined);
+      rec[propName] = inlined;
+      continue;
+    }
+
+    if (propSchema.type === "array") {
+      const itemSchema = asSchema(
+        Array.isArray(propSchema.items) ?
+          propSchema.items[0]
+        : propSchema.items,
+      );
+      if (typeof itemSchema.$ref === "string") {
+        const targetKey = resolveRef(itemSchema.$ref, idx);
+        const targetDef = targetKey !== null ? idx.defs[targetKey] : undefined;
+        if (
+          targetKey !== null &&
+          targetDef !== undefined &&
+          targetDef.type === "object" &&
+          pkRegistry[targetKey] !== undefined
+        ) {
+          junctions.push({
+            parentTable: defKey,
+            property: propName,
+            refTable: targetKey,
+          });
+          continue;
+        }
+      }
+    }
+
+    if (
+      pkInfo !== undefined &&
+      !pkInfo.autoInjected &&
+      propName === pkInfo.column
+    ) {
+      rec[propName] = annotate.primary(bareTypeShape(pkInfo.shape));
+      continue;
+    }
+
+    let child = convertFrom(propSchema, false, idx);
+    if (!required.has(propName)) child = annotate.optional(child);
+    rec[propName] = child;
+  }
+
+  let mapping: shapes.ShapeMapping = shapes.mapping(rec);
+  mapping = annotate.titled(mapping, defKey) as shapes.ShapeMapping;
+  if (typeof def.$anchor === "string") {
+    mapping = annotate.meta(mapping, {
+      anchor: def.$anchor,
+    }) as shapes.ShapeMapping;
+  }
+  if (typeof def.description === "string") {
+    mapping = annotate.described(
+      mapping,
+      def.description,
+    ) as shapes.ShapeMapping;
+  }
+  return mapping;
+};
+
+const buildJunctionTable = (
+  spec: JunctionSpec,
+  pkRegistry: PkRegistry,
+): { name: string; mapping: shapes.ShapeMapping } => {
+  const parentPk = pkRegistry[spec.parentTable];
+  const refPk = pkRegistry[spec.refTable];
+  if (parentPk === undefined || refPk === undefined) {
+    throw new Error(
+      `junction table ${spec.parentTable}_${spec.property}: missing PK for endpoint`,
+    );
+  }
+  const name = `${spec.parentTable}_${spec.property}`;
+  const parentCol = `${spec.parentTable}_id`;
+  const refCol = `${spec.property}_id`;
+
+  const parentFk = annotate.primary(
+    annotate.foreign(
+      bareTypeShape(parentPk.shape),
+      spec.parentTable,
+      parentPk.column,
+    ),
+  );
+  const refFk = annotate.primary(
+    annotate.foreign(bareTypeShape(refPk.shape), spec.refTable, refPk.column),
+  );
+
+  const rec: Record<string, shapes.Shape> =
+    parentCol === refCol ?
+      // self-ref edge case: column-name collision impossible because we use
+      // `${property}_id` for the second column. If somehow they still match,
+      // fall back to a numeric suffix.
+      { [parentCol]: parentFk, [`${refCol}_2`]: refFk }
+    : { [parentCol]: parentFk, [refCol]: refFk };
+
+  let mapping: shapes.ShapeMapping = shapes.mapping(rec);
+  mapping = annotate.titled(mapping, name) as shapes.ShapeMapping;
+  mapping = annotate.meta(mapping, { junction: true }) as shapes.ShapeMapping;
+  return { name, mapping };
+};
+
+const convertFromModule = (schema: JSONSchema): shapes.ShapeModule => {
+  const idx = buildRefIndex(schema);
+
+  const pkRegistry: PkRegistry = {};
+  for (const [defKey, def] of Object.entries(idx.defs)) {
+    if (def.type !== "object") continue;
+    pkRegistry[defKey] = buildPkInfo(defKey, def, idx);
+  }
+
+  const hasTopLevelObject =
+    schema.type === "object" && schema.properties !== undefined;
+  let topLevelKey: string | null = null;
+  if (hasTopLevelObject) {
+    topLevelKey = topLevelTableName(schema);
+    if (topLevelKey in pkRegistry) {
+      throw new Error(
+        `top-level table name '${topLevelKey}' collides with a $defs key`,
+      );
+    }
+    pkRegistry[topLevelKey] = buildPkInfo(topLevelKey, schema, idx);
+  }
+
+  const tables: Record<string, shapes.ShapeMapping> = {};
+  const junctions: JunctionSpec[] = [];
+
+  for (const [defKey, def] of Object.entries(idx.defs)) {
+    if (def.type !== "object") continue;
+    tables[defKey] = convertDefToTable(defKey, def, idx, pkRegistry, junctions);
+  }
+
+  if (topLevelKey !== null) {
+    tables[topLevelKey] = convertDefToTable(
+      topLevelKey,
+      schema,
+      idx,
+      pkRegistry,
+      junctions,
+    );
+  }
+
+  for (const spec of junctions) {
+    const { name, mapping } = buildJunctionTable(spec, pkRegistry);
+    tables[name] = mapping;
+  }
+
+  let mod: shapes.ShapeModule = shapes.module(tables);
+  if (typeof schema.title === "string")
+    mod = annotate.titled(mod, schema.title) as shapes.ShapeModule;
+  if (typeof schema.description === "string")
+    mod = annotate.described(mod, schema.description) as shapes.ShapeModule;
+  return mod;
+};
+
+export const fromJSONSchema = (schema: JSONSchema): shapes.Shape => {
+  if (schema.$defs !== undefined || schema.definitions !== undefined)
+    return convertFromModule(schema);
+  return convertFrom(schema, true);
+};