shapecraft 1.0.0

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

@@ -0,0 +1,850 @@
+import { describe, expect } from "vitest";
+import { annotate, shapes } from "../../shape";
+import { fromJSONSchema, toJSONSchema } from "./transform";
+
+describe("toJSONSchema — scalars", (it) => {
+  it("string → { type: 'string' }", () => {
+    expect(toJSONSchema(shapes.string())).toEqual({ type: "string" });
+  });
+
+  it("string with min/max → minLength/maxLength", () => {
+    const s = annotate.as(shapes.string(), { min: 2, max: 8 });
+    expect(toJSONSchema(s)).toEqual({
+      type: "string",
+      minLength: 2,
+      maxLength: 8,
+    });
+  });
+
+  it("string with RegExp pattern → pattern uses .source", () => {
+    const s = annotate.pattern(shapes.string(), /^[a-z]+$/);
+    expect(toJSONSchema(s)).toEqual({ type: "string", pattern: "^[a-z]+$" });
+  });
+
+  it("string with string-source pattern → pattern stored as-is", () => {
+    const s = annotate.pattern(shapes.string(), "^[A-Z]{3}$");
+    expect(toJSONSchema(s)).toEqual({ type: "string", pattern: "^[A-Z]{3}$" });
+  });
+
+  it("boolean → { type: 'boolean' }", () => {
+    expect(toJSONSchema(shapes.boolean())).toEqual({ type: "boolean" });
+  });
+
+  it("nil → { type: 'null' }", () => {
+    expect(toJSONSchema(shapes.nil())).toEqual({ type: "null" });
+  });
+
+  it("notDefined → {} with x-shapecraft.kind 'undefined'", () => {
+    expect(toJSONSchema(shapes.notDefined())).toEqual({
+      "x-shapecraft": { kind: "undefined" },
+    });
+  });
+
+  it("unknown → {}", () => {
+    expect(toJSONSchema(shapes.unknown())).toEqual({});
+  });
+
+  it("date → string + date-time format + x-shapecraft.kind 'date'", () => {
+    expect(toJSONSchema(shapes.date())).toEqual({
+      type: "string",
+      format: "date-time",
+      "x-shapecraft": { kind: "date" },
+    });
+  });
+
+  it("binary → string + contentEncoding base64 + x-shapecraft.kind 'binary'", () => {
+    expect(toJSONSchema(shapes.binary())).toEqual({
+      type: "string",
+      contentEncoding: "base64",
+      "x-shapecraft": { kind: "binary" },
+    });
+  });
+});
+
+describe("toJSONSchema — numbers", (it) => {
+  it("number() → type 'number' + tag preserved", () => {
+    expect(toJSONSchema(shapes.number())).toEqual({
+      type: "number",
+      "x-shapecraft": { numberTag: "number" },
+    });
+  });
+
+  it("int() → type 'integer' + tag preserved, no bounds", () => {
+    expect(toJSONSchema(shapes.int())).toEqual({
+      type: "integer",
+      "x-shapecraft": { numberTag: "int" },
+    });
+  });
+
+  it("int8 → integer with [-128, 127]", () => {
+    expect(toJSONSchema(shapes.int8())).toEqual({
+      type: "integer",
+      minimum: -128,
+      maximum: 127,
+      "x-shapecraft": { numberTag: "int8" },
+    });
+  });
+
+  it("uint8 → integer with [0, 255]", () => {
+    expect(toJSONSchema(shapes.uint8())).toEqual({
+      type: "integer",
+      minimum: 0,
+      maximum: 255,
+      "x-shapecraft": { numberTag: "uint8" },
+    });
+  });
+
+  it("int16 → integer with [-32768, 32767]", () => {
+    expect(toJSONSchema(shapes.int16())).toEqual({
+      type: "integer",
+      minimum: -32768,
+      maximum: 32767,
+      "x-shapecraft": { numberTag: "int16" },
+    });
+  });
+
+  it("uint32 → integer with [0, 4294967295]", () => {
+    expect(toJSONSchema(shapes.uint32())).toEqual({
+      type: "integer",
+      minimum: 0,
+      maximum: 4_294_967_295,
+      "x-shapecraft": { numberTag: "uint32" },
+    });
+  });
+
+  it("float32 → number with float32 bounds", () => {
+    const out = toJSONSchema(shapes.float32());
+    expect(out.type).toBe("number");
+    expect(out.minimum).toBeLessThan(0);
+    expect(out.maximum).toBeGreaterThan(0);
+    expect(out["x-shapecraft"]).toEqual({ numberTag: "float32" });
+  });
+
+  it("integer with narrower anno.min/max clamps tighter than tag range", () => {
+    const s = annotate.as(shapes.int16(), { min: 0, max: 100 });
+    expect(toJSONSchema(s)).toEqual({
+      type: "integer",
+      minimum: 0,
+      maximum: 100,
+      "x-shapecraft": { numberTag: "int16" },
+    });
+  });
+
+  it("integer with wider anno.min/max keeps the tag bound (intersection)", () => {
+    const s = annotate.as(shapes.uint8(), { min: -1000, max: 1000 });
+    expect(toJSONSchema(s)).toEqual({
+      type: "integer",
+      minimum: 0,
+      maximum: 255,
+      "x-shapecraft": { numberTag: "uint8" },
+    });
+  });
+
+  it("number literal → { const }, no type", () => {
+    expect(toJSONSchema(shapes.literal(7))).toEqual({ const: 7 });
+  });
+});
+
+describe("toJSONSchema — literals & unions", (it) => {
+  it("string literal → { const: 'a' }", () => {
+    expect(toJSONSchema(shapes.literal("a"))).toEqual({ const: "a" });
+  });
+
+  it("boolean literal → { const: true }", () => {
+    expect(toJSONSchema(shapes.literal(true))).toEqual({ const: true });
+  });
+
+  it("union of all string literals → enum", () => {
+    const u = shapes.union(
+      shapes.literal("a"),
+      shapes.literal("b"),
+      shapes.literal("c"),
+    );
+    expect(toJSONSchema(u)).toEqual({ enum: ["a", "b", "c"] });
+  });
+
+  it("union of mixed literal scalars → enum", () => {
+    const u = shapes.union(
+      shapes.literal("a"),
+      shapes.literal(1),
+      shapes.literal(true),
+    );
+    expect(toJSONSchema(u)).toEqual({ enum: ["a", 1, true] });
+  });
+
+  it("union with at least one non-literal → anyOf recursed", () => {
+    const u = shapes.union(shapes.literal("a"), shapes.number());
+    expect(toJSONSchema(u)).toEqual({
+      anyOf: [
+        { const: "a" },
+        { type: "number", "x-shapecraft": { numberTag: "number" } },
+      ],
+    });
+  });
+});
+
+describe("toJSONSchema — collections", (it) => {
+  it("array of strings with min/max → items, minItems, maxItems", () => {
+    const s = annotate.as(shapes.array(shapes.string()), { min: 1, max: 3 });
+    expect(toJSONSchema(s)).toEqual({
+      type: "array",
+      items: { type: "string" },
+      minItems: 1,
+      maxItems: 3,
+    });
+  });
+
+  it("array with anno.uniqueItems → uniqueItems: true", () => {
+    const s = annotate.uniqueItems(shapes.array(shapes.string()));
+    expect(toJSONSchema(s)).toEqual({
+      type: "array",
+      items: { type: "string" },
+      uniqueItems: true,
+    });
+  });
+
+  it("array with anno.unique → x-shapecraft.unique (column-level)", () => {
+    const s = annotate.unique(shapes.array(shapes.string()));
+    expect(toJSONSchema(s)).toEqual({
+      type: "array",
+      items: { type: "string" },
+      "x-shapecraft": { unique: true },
+    });
+  });
+
+  it("mapping with required + optional → properties present, required skips optional, additionalProperties false", () => {
+    const m = shapes.mapping({
+      a: shapes.string(),
+      b: annotate.optional(shapes.number()),
+    });
+    expect(toJSONSchema(m)).toEqual({
+      type: "object",
+      properties: {
+        a: { type: "string" },
+        b: { type: "number", "x-shapecraft": { numberTag: "number" } },
+      },
+      required: ["a"],
+      additionalProperties: false,
+    });
+  });
+
+  it("mapping with no required keys omits the required array", () => {
+    const m = shapes.mapping({
+      a: annotate.optional(shapes.string()),
+    });
+    expect(toJSONSchema(m)).toEqual({
+      type: "object",
+      properties: { a: { type: "string" } },
+      additionalProperties: false,
+    });
+  });
+
+  it("nested mapping recurses", () => {
+    const m = shapes.mapping({
+      outer: shapes.mapping({ inner: shapes.number() }),
+    });
+    expect(toJSONSchema(m)).toEqual({
+      type: "object",
+      properties: {
+        outer: {
+          type: "object",
+          properties: {
+            inner: { type: "number", "x-shapecraft": { numberTag: "number" } },
+          },
+          required: ["inner"],
+          additionalProperties: false,
+        },
+      },
+      required: ["outer"],
+      additionalProperties: false,
+    });
+  });
+
+  it("record with patterned string key → additionalProperties + propertyNames", () => {
+    const r = shapes.record(
+      annotate.pattern(shapes.string(), /^[a-z]+$/),
+      shapes.number(),
+    );
+    expect(toJSONSchema(r)).toEqual({
+      type: "object",
+      additionalProperties: {
+        type: "number",
+        "x-shapecraft": { numberTag: "number" },
+      },
+      propertyNames: { type: "string", pattern: "^[a-z]+$" },
+    });
+  });
+
+  it("record with number key → numeric-pattern propertyNames hint", () => {
+    const r = shapes.record(shapes.number(), shapes.string());
+    expect(toJSONSchema(r)).toEqual({
+      type: "object",
+      additionalProperties: { type: "string" },
+      propertyNames: { type: "string", pattern: "^-?\\d+(\\.\\d+)?$" },
+    });
+  });
+
+  it("vector(3, float32) → fixed-length array + x-shapecraft.kind 'vector'", () => {
+    const v = shapes.vector(3, shapes.float32());
+    const out = toJSONSchema(v);
+    expect(out.type).toBe("array");
+    expect(out.minItems).toBe(3);
+    expect(out.maxItems).toBe(3);
+    expect(out["x-shapecraft"]?.kind).toBe("vector");
+    expect(out["x-shapecraft"]?.vectorDims).toBe(3);
+    const items = out.items as {
+      type?: string;
+      "x-shapecraft"?: { numberTag?: string };
+    };
+    expect(items.type).toBe("number");
+    expect(items["x-shapecraft"]?.numberTag).toBe("float32");
+  });
+});
+
+describe("toJSONSchema — shapecraft-only annotations", (it) => {
+  it("scalar anno.unique → x-shapecraft.unique (not uniqueItems)", () => {
+    const s = annotate.unique(shapes.string());
+    expect(toJSONSchema(s)).toEqual({
+      type: "string",
+      "x-shapecraft": { unique: true },
+    });
+  });
+
+  it("anno.primary → x-shapecraft.primary", () => {
+    const s = annotate.primary(shapes.string());
+    expect(toJSONSchema(s)).toEqual({
+      type: "string",
+      "x-shapecraft": { primary: true },
+    });
+  });
+
+  it("anno.foreign → x-shapecraft.foreign round-trips", () => {
+    const s = annotate.foreign(shapes.string(), "users", "id");
+    expect(toJSONSchema(s)).toEqual({
+      type: "string",
+      "x-shapecraft": { foreign: { table: "users", column: "id" } },
+    });
+  });
+
+  it("top-level optional → x-shapecraft.optional: true", () => {
+    const s = annotate.optional(shapes.string());
+    expect(toJSONSchema(s)).toEqual({
+      type: "string",
+      "x-shapecraft": { optional: true },
+    });
+  });
+
+  it("optional as mapping value is consumed by parent (not surfaced as x-shapecraft.optional)", () => {
+    const m = shapes.mapping({ a: annotate.optional(shapes.string()) });
+    const out = toJSONSchema(m);
+    expect(out.required).toBeUndefined();
+    expect(out.properties?.a).toEqual({ type: "string" });
+  });
+});
+
+describe("fromJSONSchema — direct construction (lenient inputs)", (it) => {
+  it("{} → unknown", () => {
+    expect(toJSONSchema(fromJSONSchema({}))).toEqual({});
+  });
+
+  it("{ type: 'string' } → string", () => {
+    expect(toJSONSchema(fromJSONSchema({ type: "string" }))).toEqual({
+      type: "string",
+    });
+  });
+
+  it("{ type: 'boolean' } → boolean", () => {
+    expect(toJSONSchema(fromJSONSchema({ type: "boolean" }))).toEqual({
+      type: "boolean",
+    });
+  });
+
+  it("{ type: 'null' } → nil", () => {
+    expect(toJSONSchema(fromJSONSchema({ type: "null" }))).toEqual({
+      type: "null",
+    });
+  });
+
+  it("{ type: 'integer' } without numberTag → int", () => {
+    expect(toJSONSchema(fromJSONSchema({ type: "integer" }))).toEqual({
+      type: "integer",
+      "x-shapecraft": { numberTag: "int" },
+    });
+  });
+
+  it("{ type: 'number' } without numberTag → number", () => {
+    expect(toJSONSchema(fromJSONSchema({ type: "number" }))).toEqual({
+      type: "number",
+      "x-shapecraft": { numberTag: "number" },
+    });
+  });
+
+  it("oneOf is treated like anyOf", () => {
+    const out = fromJSONSchema({
+      oneOf: [{ type: "string" }, { type: "number" }],
+    });
+    expect(out.type).toBe("union");
+    expect(toJSONSchema(out)).toEqual({
+      anyOf: [
+        { type: "string" },
+        { type: "number", "x-shapecraft": { numberTag: "number" } },
+      ],
+    });
+  });
+
+  it("{ type: 'object', additionalProperties: { type: 'string' } } → record(string, string)", () => {
+    const out = fromJSONSchema({
+      type: "object",
+      additionalProperties: { type: "string" },
+    });
+    expect(out.type).toBe("record");
+    expect(toJSONSchema(out)).toEqual({
+      type: "object",
+      additionalProperties: { type: "string" },
+    });
+  });
+
+  it("{ x-shapecraft: { kind: 'undefined' } } → notDefined", () => {
+    const out = fromJSONSchema({ "x-shapecraft": { kind: "undefined" } });
+    expect(out.type).toBe("undefined");
+  });
+
+  it("string with format 'date-time' but no x-shapecraft → date (lenient)", () => {
+    const out = fromJSONSchema({ type: "string", format: "date-time" });
+    expect(out.type).toBe("date");
+  });
+
+  it("string with contentEncoding 'base64' but no x-shapecraft → binary (lenient)", () => {
+    const out = fromJSONSchema({ type: "string", contentEncoding: "base64" });
+    expect(out.type).toBe("binary");
+  });
+
+  it("const literal → shapes.literal", () => {
+    expect(toJSONSchema(fromJSONSchema({ const: "hi" }))).toEqual({
+      const: "hi",
+    });
+    expect(toJSONSchema(fromJSONSchema({ const: 42 }))).toEqual({ const: 42 });
+    expect(toJSONSchema(fromJSONSchema({ const: true }))).toEqual({
+      const: true,
+    });
+  });
+
+  it("enum of literals → union of literals", () => {
+    expect(toJSONSchema(fromJSONSchema({ enum: ["a", "b", "c"] }))).toEqual({
+      enum: ["a", "b", "c"],
+    });
+  });
+
+  it("array without x-shapecraft.kind → array (not vector) even if minItems=maxItems", () => {
+    const out = fromJSONSchema({
+      type: "array",
+      items: { type: "string" },
+      minItems: 3,
+      maxItems: 3,
+    });
+    expect(out.type).toBe("array");
+    expect(toJSONSchema(out)).toEqual({
+      type: "array",
+      items: { type: "string" },
+      minItems: 3,
+      maxItems: 3,
+    });
+  });
+});
+
+describe("fromJSONSchema — round-trip via toJSONSchema", (it) => {
+  const roundTrip = (s: shapes.Shape): void => {
+    const json = toJSONSchema(s);
+    const reconstructed = fromJSONSchema(json);
+    expect(toJSONSchema(reconstructed)).toEqual(json);
+  };
+
+  it("scalars", () => {
+    roundTrip(shapes.string());
+    roundTrip(shapes.boolean());
+    roundTrip(shapes.nil());
+    roundTrip(shapes.notDefined());
+    roundTrip(shapes.unknown());
+    roundTrip(shapes.date());
+    roundTrip(shapes.binary());
+  });
+
+  it("strings with min/max and patterns", () => {
+    roundTrip(annotate.as(shapes.string(), { min: 2, max: 8 }));
+    roundTrip(annotate.pattern(shapes.string(), /^[a-z]+$/));
+    roundTrip(annotate.pattern(shapes.string(), "^[A-Z]{3}$"));
+  });
+
+  it("every number tag", () => {
+    roundTrip(shapes.number());
+    roundTrip(shapes.int());
+    roundTrip(shapes.int8());
+    roundTrip(shapes.uint8());
+    roundTrip(shapes.int16());
+    roundTrip(shapes.uint16());
+    roundTrip(shapes.int32());
+    roundTrip(shapes.uint32());
+    roundTrip(shapes.int64());
+    roundTrip(shapes.uint64());
+    roundTrip(shapes.float());
+    roundTrip(shapes.float32());
+    roundTrip(shapes.float64());
+  });
+
+  it("integer with narrower anno.min/max", () => {
+    roundTrip(annotate.as(shapes.int16(), { min: 0, max: 100 }));
+  });
+
+  it("integer with wider anno.min/max (intersection)", () => {
+    roundTrip(annotate.as(shapes.uint8(), { min: -1000, max: 1000 }));
+  });
+
+  it("literal scalars", () => {
+    roundTrip(shapes.literal("a"));
+    roundTrip(shapes.literal(7));
+    roundTrip(shapes.literal(true));
+  });
+
+  it("union of literals (enum)", () => {
+    roundTrip(
+      shapes.union(
+        shapes.literal("a"),
+        shapes.literal("b"),
+        shapes.literal("c"),
+      ),
+    );
+    roundTrip(
+      shapes.union(
+        shapes.literal("a"),
+        shapes.literal(1),
+        shapes.literal(true),
+      ),
+    );
+  });
+
+  it("union with non-literal variant (anyOf)", () => {
+    roundTrip(shapes.union(shapes.literal("a"), shapes.number()));
+  });
+
+  it("arrays with min/max, uniqueItems, and column-level unique", () => {
+    roundTrip(annotate.as(shapes.array(shapes.string()), { min: 1, max: 3 }));
+    roundTrip(annotate.uniqueItems(shapes.array(shapes.string())));
+    roundTrip(annotate.unique(shapes.array(shapes.string())));
+  });
+
+  it("mappings with required, optional, nested", () => {
+    roundTrip(
+      shapes.mapping({
+        a: shapes.string(),
+        b: annotate.optional(shapes.number()),
+      }),
+    );
+    roundTrip(shapes.mapping({ a: annotate.optional(shapes.string()) }));
+    roundTrip(
+      shapes.mapping({
+        outer: shapes.mapping({ inner: shapes.number() }),
+      }),
+    );
+  });
+
+  it("records with patterned and numeric keys", () => {
+    roundTrip(
+      shapes.record(
+        annotate.pattern(shapes.string(), /^[a-z]+$/),
+        shapes.number(),
+      ),
+    );
+    roundTrip(shapes.record(shapes.number(), shapes.string()));
+    roundTrip(shapes.record(shapes.string(), shapes.string()));
+  });
+
+  it("vector(3, float32)", () => {
+    roundTrip(shapes.vector(3, shapes.float32()));
+  });
+
+  it("shapecraft-only annotations at top level", () => {
+    roundTrip(annotate.optional(shapes.string()));
+    roundTrip(annotate.primary(shapes.string()));
+    roundTrip(annotate.unique(shapes.string()));
+    roundTrip(annotate.foreign(shapes.string(), "users", "id"));
+  });
+});
+
+describe("fromJSONSchema — $defs / $ref / $anchor", (it) => {
+  it("$defs becomes a ShapeModule with one table per def", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        product: {
+          type: "object",
+          properties: { name: { type: "string" } },
+          required: ["name"],
+        },
+      },
+    });
+    expect(out.type).toBe("module");
+    const mod = out as shapes.ShapeModule;
+    expect(Object.keys(mod.input)).toEqual(["product"]);
+    expect(mod.input.product?.type).toBe("mapping");
+  });
+
+  it("def with no PK-like field auto-injects id bigint identity PK", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        product: { type: "object", properties: { name: { type: "string" } } },
+      },
+    }) as shapes.ShapeModule;
+    const product = mod_(out, "product");
+    const id = product.input.id as shapes.ShapeNumber;
+    expect(id?.type).toBe("number");
+    expect(id?.tag).toBe("int64");
+    expect(id?.anno.primary).toBe(true);
+    expect(id?.anno.autoIncrement).toBe(true);
+  });
+
+  it("def with a required 'id' uses it as PK without auto-inject", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        user: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            name: { type: "string" },
+          },
+          required: ["id", "name"],
+        },
+      },
+    }) as shapes.ShapeModule;
+    const user = mod_(out, "user");
+    const id = user.input.id as shapes.ShapeNumber;
+    expect(id?.anno.primary).toBe(true);
+    expect(id?.anno.autoIncrement).toBeUndefined();
+    expect(Object.keys(user.input)).toEqual(["id", "name"]);
+  });
+
+  it("def with required '${name}Id' uses that as PK", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        order: {
+          type: "object",
+          properties: { orderId: { type: "string" } },
+          required: ["orderId"],
+        },
+      },
+    }) as shapes.ShapeModule;
+    const order = mod_(out, "order");
+    const pk = order.input.orderId;
+    expect(pk?.anno.primary).toBe(true);
+  });
+
+  it("non-required 'id' field → error", () => {
+    expect(() =>
+      fromJSONSchema({
+        $defs: {
+          user: {
+            type: "object",
+            properties: { id: { type: "integer" } },
+          },
+        },
+      }),
+    ).toThrow(/has an 'id' field that doesn't qualify as PK/);
+  });
+
+  it("$ref to another def becomes FK column", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        user: {
+          type: "object",
+          properties: { id: { type: "integer" }, name: { type: "string" } },
+          required: ["id"],
+        },
+        post: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            author: { $ref: "#/$defs/user" },
+          },
+          required: ["id"],
+        },
+      },
+    }) as shapes.ShapeModule;
+    const post = mod_(out, "post");
+    const author = post.input.author;
+    expect(author?.anno.foreign).toEqual({ table: "user", column: "id" });
+    expect(author?.type).toBe("number");
+  });
+
+  it("$anchor allows #anchor refs", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        product: {
+          $anchor: "ProductSchema",
+          type: "object",
+          properties: { id: { type: "integer" } },
+          required: ["id"],
+        },
+        order: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            product: { $ref: "#ProductSchema" },
+          },
+          required: ["id"],
+        },
+      },
+    }) as shapes.ShapeModule;
+    const order = mod_(out, "order");
+    expect(order.input.product?.anno.foreign).toEqual({
+      table: "product",
+      column: "id",
+    });
+  });
+
+  it("array<$ref> generates a junction table; original property dropped", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        product: { type: "object", properties: {} },
+        order: {
+          type: "object",
+          properties: {
+            items: { type: "array", items: { $ref: "#/$defs/product" } },
+          },
+        },
+      },
+    }) as shapes.ShapeModule;
+    expect(Object.keys(out.input).sort()).toEqual([
+      "order",
+      "order_items",
+      "product",
+    ]);
+    const junction = mod_(out, "order_items");
+    expect(Object.keys(junction.input)).toEqual(["order_id", "items_id"]);
+    expect(junction.input.order_id?.anno.foreign).toEqual({
+      table: "order",
+      column: "id",
+    });
+    expect(junction.input.order_id?.anno.primary).toBe(true);
+    expect(junction.input.items_id?.anno.foreign).toEqual({
+      table: "product",
+      column: "id",
+    });
+    expect(junction.input.items_id?.anno.primary).toBe(true);
+  });
+
+  it("external $ref → unknown column", () => {
+    const out = fromJSONSchema({
+      $defs: {
+        user: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            avatar: { $ref: "https://example.com/avatar.json" },
+          },
+          required: ["id"],
+        },
+      },
+    }) as shapes.ShapeModule;
+    const user = mod_(out, "user");
+    expect(user.input.avatar?.type).toBe("unknown");
+  });
+
+  it("top-level object with $defs becomes one more table in the module", () => {
+    const out = fromJSONSchema({
+      title: "blog",
+      type: "object",
+      properties: { content: { type: "string" } },
+      required: ["content"],
+      $defs: {
+        comment: { type: "object", properties: {} },
+      },
+    }) as shapes.ShapeModule;
+    expect(Object.keys(out.input).sort()).toEqual(["blog", "comment"]);
+  });
+
+  it("legacy 'definitions' keyword is treated like '$defs'", () => {
+    const out = fromJSONSchema({
+      definitions: {
+        user: {
+          type: "object",
+          properties: { id: { type: "integer" } },
+          required: ["id"],
+        },
+      },
+    });
+    expect(out.type).toBe("module");
+    expect(Object.keys((out as shapes.ShapeModule).input)).toEqual(["user"]);
+  });
+
+  it("$ref to a non-object def is inlined (typedef-style)", () => {
+    const out = fromJSONSchema({
+      definitions: {
+        Currency: { type: "string", pattern: "^[A-Z]{3}$" },
+        Money: {
+          type: "object",
+          properties: {
+            amount: { type: "number" },
+            currency: { $ref: "#/definitions/Currency" },
+          },
+          required: ["amount", "currency"],
+        },
+      },
+    }) as shapes.ShapeModule;
+    expect(Object.keys(out.input).sort()).toEqual(["Money"]);
+    const money = mod_(out, "Money");
+    const currency = money.input.currency;
+    expect(currency?.type).toBe("string");
+    expect(currency?.anno.foreign).toBeUndefined();
+    expect(currency?.anno.pattern).toBe("^[A-Z]{3}$");
+  });
+
+  it("$ref nested inside oneOf is resolved by ref index", () => {
+    const out = fromJSONSchema({
+      definitions: {
+        A: {
+          type: "object",
+          properties: { id: { type: "integer" } },
+          required: ["id"],
+        },
+        B: {
+          type: "object",
+          properties: { id: { type: "integer" } },
+          required: ["id"],
+        },
+        Either: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            details: {
+              oneOf: [{ $ref: "#/definitions/A" }, { $ref: "#/definitions/B" }],
+            },
+          },
+          required: ["id"],
+        },
+      },
+    }) as shapes.ShapeModule;
+    const either = mod_(out, "Either");
+    const details = either.input.details;
+    expect(details?.type).toBe("union");
+  });
+
+  it("module round-trips through toJSONSchema", () => {
+    const original = fromJSONSchema({
+      $defs: {
+        product: {
+          $anchor: "ProductSchema",
+          type: "object",
+          properties: { id: { type: "integer" } },
+          required: ["id"],
+        },
+      },
+    });
+    const schema = toJSONSchema(original);
+    expect(schema.$defs).toBeDefined();
+    expect(schema.$defs?.product).toBeDefined();
+  });
+});
+
+const mod_ = (m: shapes.ShapeModule, k: string): shapes.ShapeMapping => {
+  const t = m.input[k];
+  if (t === undefined) throw new Error(`missing table ${k}`);
+  return t;
+};