diff --git a/.bumpy/bytes-mock-bounds.md b/.bumpy/bytes-mock-bounds.md new file mode 100644 index 0000000..0ced323 --- /dev/null +++ b/.bumpy/bytes-mock-bounds.md @@ -0,0 +1,5 @@ +--- +"@saeris/valicon": patch +--- + +Keep `bytes` mocks within Valimock's string bound. A Lexicon `maxLength` such as the 2 MB limit on `com.atproto.sync.subscribeRepos#commit` no longer produces megabytes of base64 that Valimock rejects and regenerates until its retry budget runs out, which made mocking that definition take over a second. A `minLength` larger than the bound now widens it instead of being reported as unsatisfiable. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0878968..18ba0f9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,5 +26,5 @@ jobs: cache: true - run: vp check - - run: vp test + - run: vp test --coverage - run: vp pack diff --git a/src/__tests__/fixtures/synthetic.ts b/src/__tests__/fixtures/synthetic.ts new file mode 100644 index 0000000..99039f9 --- /dev/null +++ b/src/__tests__/fixtures/synthetic.ts @@ -0,0 +1,153 @@ +import type { LexiconDoc } from "../../types/index.js"; + +/** + * Hand-written documents that use the Lexicon features the published + * fixtures happen not to: string and integer enums and constants, byte and + * grapheme minimums, nullable required fields, open unions without variants, + * top-level primitive definitions, and XRPC endpoints with every optional + * part left out or filled in. + */ +export const kitchenSink: LexiconDoc = { + lexicon: 1, + id: "com.example.kitchenSink", + description: "Every Lexicon feature the published fixtures do not use.", + defs: { + main: { + type: "record", + key: "any", + record: { + type: "object", + required: ["status", "when"], + nullable: ["note", "when"], + properties: { + status: { type: "string", enum: ["draft", "published"] }, + note: { type: "string" }, + kind: { type: "string", const: "note" }, + title: { + type: "string", + minLength: 1, + maxLength: 100, + minGraphemes: 1, + maxGraphemes: 50 + }, + "content-type": { type: "string" }, + priority: { type: "integer", enum: [1, 2, 3] }, + version: { type: "integer", const: 1 }, + when: { type: "string", format: "datetime" }, + cover: { type: "blob" }, + payload: { type: "bytes" }, + embed: { type: "union", refs: [] }, + tags: { type: "array", items: { type: "string" }, minLength: 1 } + } + } + }, + history: { + type: "array", + items: { type: "ref", ref: "#entry" }, + maxLength: 10 + }, + entry: { + type: "object", + properties: { at: { type: "string", format: "datetime" } } + }, + photo: { type: "blob", accept: ["image/*"], maxSize: 1000 }, + enabled: { type: "boolean" }, + signature: { type: "bytes", minLength: 1, maxLength: 64 }, + link: { type: "cid-link" }, + count: { type: "integer", minimum: 0, maximum: 10 }, + label: { type: "string", description: "A free-form label." }, + anything: { type: "unknown" } + } +}; + +export const ping: LexiconDoc = { + lexicon: 1, + id: "com.example.ping", + defs: { + main: { type: "procedure", description: "Checks that the service is up." } + } +}; + +export const count: LexiconDoc = { + lexicon: 1, + id: "com.example.count", + defs: { + main: { + type: "query", + parameters: { + type: "params", + required: ["q"], + properties: { + q: { type: "string" }, + limit: { type: "integer", default: 10 }, + tags: { type: "array", items: { type: "string" } }, + verbose: { type: "boolean", default: false } + } + }, + errors: [{ name: "TooMany" }] + } + } +}; + +export const upload: LexiconDoc = { + lexicon: 1, + id: "com.example.upload", + defs: { + main: { + type: "procedure", + input: { encoding: "*/*", description: "The raw file." }, + output: { + encoding: "application/json", + description: "The stored file.", + schema: { type: "ref", ref: "#result" } + } + }, + result: { + type: "object", + required: ["cid"], + properties: { cid: { type: "string", format: "cid" } } + } + } +}; + +export const events: LexiconDoc = { + lexicon: 1, + id: "com.example.events", + defs: { + main: { + type: "subscription", + parameters: { + type: "params", + properties: { cursor: { type: "integer" } } + }, + errors: [{ name: "FutureCursor", description: "The cursor is ahead." }] + } + } +}; + +export const feed: LexiconDoc = { + lexicon: 1, + id: "com.example.feed", + defs: { + main: { + type: "subscription", + message: { + description: "A feed event.", + schema: { type: "union", refs: ["#post"] } + } + }, + post: { + type: "object", + properties: { text: { type: "string" } } + } + } +}; + +export const syntheticLexicons: LexiconDoc[] = [ + kitchenSink, + ping, + count, + upload, + events, + feed +]; diff --git a/src/__tests__/valimock.test.ts b/src/__tests__/valimock.test.ts index c7db283..796a8ea 100644 --- a/src/__tests__/valimock.test.ts +++ b/src/__tests__/valimock.test.ts @@ -1,9 +1,26 @@ -import { describe, expect, it } from "vitest"; +import { faker } from "@faker-js/faker"; +import { describe, expect, it, vi } from "vitest"; import * as v from "valibot"; import { Valimock } from "valimock"; +import { + atIdentifier, + atUri, + cid, + datetime, + did, + didPlc, + didWeb, + handle, + language, + nsid, + recordKey, + tid, + uri +} from "../actions/index.js"; import { readLexiconFixtures } from "./fixtures/lexicons.js"; import { resolvePlaceholder } from "./fixtures/samples.js"; import { compileLexicons } from "../methods/compileLexicon.js"; +import { bytes } from "../schemas/bytes.js"; import { CID_REGEX, DATETIME_REGEX, @@ -12,16 +29,24 @@ import { NSID_REGEX, TID_REGEX } from "../regex.js"; -import { lexiconMocks } from "../valimock.js"; +import { union } from "../schemas/union.js"; +import { + lexiconMocks, + mockCid, + mockHandle, + mockMimeType, + mockNsid +} from "../valimock.js"; describe("lexiconMocks", () => { const compiled = compileLexicons(readLexiconFixtures(), { resolve: resolvePlaceholder }); + const warnings: string[] = []; const mock = new Valimock({ ...lexiconMocks, seed: 42, - onWarn: () => {} + onWarn: (warning) => warnings.push(warning) }).mock; const schemas = Object.entries(compiled).flatMap(([nsid, defs]) => @@ -32,13 +57,37 @@ describe("lexiconMocks", () => { ); // Every schema compiled from a real Lexicon must produce mocks that pass - // its own validation, otherwise the mocks are useless as test data. + // its own validation, otherwise the mocks are useless as test data. A + // warning means Valimock exhausted its retry budget on some field, which + // is both a generator that disagrees with the schema and the slow path + // that made this suite time out. it.each(schemas)("should mock valid data for %s", (_name, schema) => { + warnings.length = 0; for (let round = 0; round < 3; round++) { const value: unknown = mock(schema); const result = v.safeParse(schema, value); expect(result.issues ?? []).toStrictEqual([]); } + expect(warnings).toStrictEqual([]); + }); + + it("should keep bytes mocks small and within Lexicon limits", () => { + // `com.atproto.sync.subscribeRepos#commit` allows a 2 MB CAR file. A mock + // that size is useless as test data and far exceeds Valimock's string + // bound, which it would then retry sixteen times per field. + warnings.length = 0; + const large = mock(bytes({ maxLength: 2_000_000 })); + expect(large.$bytes.length).toBeLessThanOrEqual(128); + // A minimum above the string bound must still be honored rather than + // reported as unsatisfiable. + const small = mock(bytes({ minLength: 200, maxLength: 300 })); + expect(small.$bytes.length).toBeGreaterThanOrEqual( + Math.ceil((200 * 4) / 3) + ); + expect( + v.safeParse(bytes({ minLength: 200, maxLength: 300 }), small).success + ).toBe(true); + expect(warnings).toStrictEqual([]); }); it("should generate realistic identifiers", () => { @@ -95,6 +144,129 @@ describe("lexiconMocks", () => { expect(blob.size).toBeLessThanOrEqual(2_000_000); }); + it("should mock every format action", () => { + const formats: Record v.GenericValidation> = { + atIdentifier, + atUri, + cid, + datetime, + did, + didPlc, + didWeb, + handle, + language, + nsid, + recordKey, + tid, + uri + }; + for (const [name, format] of Object.entries(formats)) { + const schema = v.pipe(v.string(), format()); + // Every top-level mock call reseeds, so one call for a batch of + // values exercises the generator's own variety. + for (const value of mock(v.pipe(v.array(schema), v.length(20)))) { + expect(v.safeParse(schema, value).success, `${name}: ${value}`).toBe( + true + ); + } + } + }); + + it("should pick MIME types that satisfy accept lists", () => { + const mimeType = /^[a-z]+\/\S+$/u; + expect(mockMimeType(faker, [])).toMatch(mimeType); + expect(mockMimeType(faker, ["*/*"])).toMatch(mimeType); + expect(mockMimeType(faker, ["image/*"])).toMatch(/^image\//u); + // Groups Valicon has no examples for still get a type of the right kind. + expect(mockMimeType(faker, ["font/*"])).toMatch(/^font\/\S+$/u); + expect(mockMimeType(faker, ["application/json"])).toBe("application/json"); + }); + + it("should generate CIDs for both atproto codecs", () => { + // Records and commits are dag-cbor, blobs are raw bytes, and the codec + // is visible in the CID prefix. + expect(mockCid(faker)).toMatch(/^bafyrei/u); + expect(mockCid(faker, "raw")).toMatch(/^bafkrei/u); + expect(mockCid(faker, "raw")).toMatch(CID_REGEX); + }); + + it("should never produce an empty handle label or NSID segment", () => { + // Faker words can consist entirely of characters a handle label or an + // NSID segment cannot contain, so the generators must substitute a + // placeholder rather than emit an invalid identifier. + const username = vi + .spyOn(faker.internet, "username") + .mockReturnValue("___"); + const noun = vi.spyOn(faker.word, "noun").mockReturnValue("ÉTÉ"); + try { + expect(mockHandle(faker)).toMatch(/^user\./u); + expect(mockHandle(faker)).toMatch(HANDLE_REGEX); + expect(mockNsid(faker)).toContain(".feed."); + expect(mockNsid(faker)).toMatch(NSID_REGEX); + } finally { + username.mockRestore(); + noun.mockRestore(); + } + }); + + it("should tolerate hand-built actions without a requirement", () => { + // Valimock dispatches on the action type alone, so a schema built by + // another tool may carry a Valicon action type without its requirement. + const bare = (type: string) => + // oxlint-disable-next-line typescript/no-unsafe-type-assertion + ({ + kind: "validation", + type, + async: false + }) as v.GenericValidation; + for (const type of ["accept", "min_decoded_bytes", "max_decoded_bytes"]) { + const value = mock(v.pipe(v.string(), bare(type))); + expect(value.length).toBeGreaterThan(0); + } + }); + + it("should require Valimock 1.7 so the lazy mock can recurse", () => { + const lazy = lexiconMocks.customMocks?.lazy; + if (!lazy) { + throw new Error("expected a lazy mock"); + } + expect(() => lazy(v.lazy(() => v.string()))).toThrow( + "Valimock 1.7 or newer" + ); + }); + + it("should fail loudly for lazy schemas that resolve to nothing", () => { + const lazy = lexiconMocks.customMocks?.lazy; + if (!lazy) { + throw new Error("expected a lazy mock"); + } + const instance = new Valimock({ ...lexiconMocks, seed: 42 }); + expect(() => lazy(v.string(), instance.options, instance.mock)).toThrow( + "Unable to resolve lazy schema" + ); + expect(() => + lazy( + v.lazy(() => null as never), + instance.options, + instance.mock + ) + ).toThrow("Unable to resolve lazy schema"); + }); + + it("should stamp $type on whatever a variant mock returns", () => { + const lazy = lexiconMocks.customMocks?.lazy; + if (!lazy) { + throw new Error("expected a lazy mock"); + } + const instance = new Valimock({ ...lexiconMocks, seed: 42 }); + const embed = union([ + v.looseObject({ $type: v.literal("com.example.embed") }) + ]); + expect(lazy(embed, instance.options, () => "not an object")).toStrictEqual({ + $type: "com.example.embed" + }); + }); + it("should leave plain strings to the default generator", () => { const value = mock(v.object({ firstName: v.string() })); expect(typeof value.firstName).toBe("string"); diff --git a/src/actions/__tests__/decodedBytes.test.ts b/src/actions/__tests__/decodedBytes.test.ts index 9ec3d44..5cdc429 100644 --- a/src/actions/__tests__/decodedBytes.test.ts +++ b/src/actions/__tests__/decodedBytes.test.ts @@ -32,6 +32,14 @@ describe("decodedBytes", () => { }); }); + it("should leave type errors to the string schema", () => { + // Valibot keeps running validations after the schema failed, so the + // actions must not count the bytes of a value that is not a string. + const schema = v.pipe(v.string(), minDecodedBytes(1), maxDecodedBytes(2)); + const result = v.safeParse(schema, 123); + expect(result.issues?.map((issue) => issue.type)).toStrictEqual(["string"]); + }); + it("should enforce the maximum decoded length", () => { const schema = v.pipe(v.string(), maxDecodedBytes(2)); expect(v.safeParse(schema, "AAA=").success).toBe(true); diff --git a/src/methods/__tests__/compileLexicon.test.ts b/src/methods/__tests__/compileLexicon.test.ts index 60fb3f0..9577deb 100644 --- a/src/methods/__tests__/compileLexicon.test.ts +++ b/src/methods/__tests__/compileLexicon.test.ts @@ -9,8 +9,27 @@ import { sampleCid, samplePost } from "../../__tests__/fixtures/samples.js"; +import type { LexiconDoc } from "../../types/index.js"; import { compileLexicon, compileLexicons } from "../compileLexicon.js"; +const endpoint: LexiconDoc = { + lexicon: 1, + id: "com.example.endpoint", + defs: { main: { type: "query" } } +}; + +function mainSchema( + compiled: Record>, + nsid: string +): v.GenericSchema { + const main = compiled[nsid]?.main; + if (typeof main !== "object" || main === null || !("kind" in main)) { + throw new Error(`${nsid} did not compile`); + } + // oxlint-disable-next-line typescript/no-unsafe-type-assertion + return main as v.GenericSchema; +} + describe("compileLexicon", () => { const compiled = compileLexicons(readLexiconFixtures(), { resolve: resolvePlaceholder @@ -134,6 +153,68 @@ describe("compileLexicon", () => { ); }); + it("should reject references to XRPC definitions", () => { + // Queries, procedures and subscriptions describe endpoints, not data, so + // nothing can reference them, whether locally or from another document. + const local: LexiconDoc = { + lexicon: 1, + id: "com.example.local", + defs: { + main: { type: "query" }, + thing: { + type: "object", + properties: { ref: { type: "ref", ref: "#main" } } + } + } + }; + expect(() => compileLexicon(local)).toThrow( + 'Cannot reference the XRPC definition "#main"' + ); + const remote: LexiconDoc = { + lexicon: 1, + id: "com.example.remote", + defs: { + main: { + type: "object", + properties: { ref: { type: "ref", ref: "com.example.endpoint" } } + } + } + }; + const main = mainSchema( + compileLexicons([endpoint, remote]), + "com.example.remote" + ); + expect(() => v.parse(main, { ref: {} })).toThrow( + 'Cannot reference the XRPC definition "com.example.endpoint"' + ); + }); + + it("should fail for references that cannot be resolved", () => { + const doc: LexiconDoc = { + lexicon: 1, + id: "com.example.dangling", + defs: { + main: { + type: "object", + properties: { + missingDoc: { type: "ref", ref: "com.example.missing" }, + missingDef: { type: "ref", ref: "com.example.endpoint#missing" } + } + } + } + }; + const main = mainSchema( + compileLexicons([endpoint, doc]), + "com.example.dangling" + ); + expect(() => v.parse(main, { missingDoc: {} })).toThrow( + 'Unresolved reference "com.example.missing"' + ); + expect(() => v.parse(main, { missingDef: {} })).toThrow( + 'Unresolved reference "com.example.endpoint#missing"' + ); + }); + it("should respect the object mode", () => { const { main } = compileLexicon( readLexiconFixture("app.bsky.graph.follow"), diff --git a/src/methods/__tests__/fromLexicon.test.ts b/src/methods/__tests__/fromLexicon.test.ts index 8466fca..6c3ee46 100644 --- a/src/methods/__tests__/fromLexicon.test.ts +++ b/src/methods/__tests__/fromLexicon.test.ts @@ -1,5 +1,11 @@ import { describe, expect, it } from "vitest"; import { readLexiconFixture } from "../../__tests__/fixtures/lexicons.js"; +import { + count, + kitchenSink, + syntheticLexicons +} from "../../__tests__/fixtures/synthetic.js"; +import type { LexiconDoc } from "../../types/index.js"; import { fromLexicon, toIdentifier, toImportAlias } from "../fromLexicon.js"; describe("fromLexicon", () => { @@ -53,6 +59,47 @@ describe("fromLexicon", () => { expect(code).toContain('{ key: "tid", mode: "strict" }'); }); + it.each(syntheticLexicons.map((doc): [string, LexiconDoc] => [doc.id, doc]))( + "should generate a module for %s", + (_nsid, doc) => { + expect(fromLexicon(doc)).toContain("export const main"); + } + ); + + it("should quote property names that are not identifiers", () => { + expect(fromLexicon(kitchenSink)).toContain('"content-type": '); + }); + + it("should use strict objects for anonymous objects when asked", () => { + // Params and body objects have no `$type`, so they are plain Valibot + // objects whose flavor follows the object mode. + expect(fromLexicon(count, { objectMode: "strict" })).toContain( + "v.strictObject(" + ); + expect(fromLexicon(count, { objectMode: "strip" })).toContain("v.object("); + expect(fromLexicon(count)).toContain("v.looseObject("); + }); + + it("should reject documents Valicon cannot express", () => { + const doc = (main: unknown): LexiconDoc => + // oxlint-disable-next-line typescript/no-unsafe-type-assertion + ({ lexicon: 1, id: "com.example.bad", defs: { main } }) as LexiconDoc; + const withProperty = (property: unknown): LexiconDoc => + doc({ type: "object", properties: { x: property } }); + expect(() => + fromLexicon(withProperty({ type: "ref", ref: "#nope" })) + ).toThrow('Unknown reference "#nope"'); + expect(() => + fromLexicon(withProperty({ type: "string", format: "ipv4" })) + ).toThrow('Unknown string format "ipv4"'); + expect(() => fromLexicon(withProperty({ type: "float" }))).toThrow( + 'Unsupported Lexicon type "float"' + ); + expect(() => fromLexicon(doc({ type: "float" }))).toThrow( + 'Unsupported Lexicon definition type "float"' + ); + }); + it("should produce safe identifiers", () => { expect(toIdentifier("main")).toBe("main"); expect(toIdentifier("default")).toBe("_default"); diff --git a/src/methods/__tests__/roundTrip.test.ts b/src/methods/__tests__/roundTrip.test.ts index 99bdf48..80af228 100644 --- a/src/methods/__tests__/roundTrip.test.ts +++ b/src/methods/__tests__/roundTrip.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it } from "vitest"; import { readLexiconFixtures } from "../../__tests__/fixtures/lexicons.js"; import { resolvePlaceholder } from "../../__tests__/fixtures/samples.js"; +import { syntheticLexicons } from "../../__tests__/fixtures/synthetic.js"; import type { LexiconDoc } from "../../types/index.js"; import { compileLexicons } from "../compileLexicon.js"; import { toLexicon } from "../toLexicon.js"; @@ -56,4 +57,20 @@ describe("lexicon round trip", () => { ).toEqual(normalize(doc, nsid)); } ); + + // The synthetic documents cover the Lexicon features the published + // fixtures happen not to use, so the guarantee extends to the whole spec. + const synthetic = compileLexicons(syntheticLexicons); + + it.each(syntheticLexicons.map((doc): [string, LexiconDoc] => [doc.id, doc]))( + "%s", + (nsid, doc) => { + expect( + toLexicon(synthetic[nsid]!, { + id: nsid, + ...(doc.description ? { description: doc.description } : {}) + }) + ).toEqual(normalize(doc, nsid)); + } + ); }); diff --git a/src/methods/__tests__/toLexicon.test.ts b/src/methods/__tests__/toLexicon.test.ts index 86432a1..f1b6f3d 100644 --- a/src/methods/__tests__/toLexicon.test.ts +++ b/src/methods/__tests__/toLexicon.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import * as v from "valibot"; import { readLexiconFixture } from "../../__tests__/fixtures/lexicons.js"; import { @@ -11,7 +11,7 @@ import { language, uri } from "../../actions/index.js"; -import { procedure, query } from "../../definitions/index.js"; +import { procedure, query, subscription } from "../../definitions/index.js"; import { blob, object, @@ -327,6 +327,271 @@ describe("toLexicon", () => { ); }); + it("should convert the constraints the published fixtures never use", () => { + const shared = v.object({ city: v.string() }); + const doc = toLexicon( + record("com.example.kitchen", { + slug: v.pipe( + v.string(), + v.nonEmpty(), + v.minBytes(2), + v.minGraphemes(1) + ), + status: v.pipe(v.string(), v.values(["draft", "live"])), + kind: v.pipe(v.string(), v.value("note")), + priority: v.pipe(v.number(), v.integer(), v.values([1, 2, 3])), + version: v.pipe(v.number(), v.integer(), v.value(1)), + one: v.literal(1), + yes: v.pipe(v.boolean(), v.value(true)), + level: v.picklist([1, 2]), + anything: v.any(), + bag: v.record(v.string(), v.unknown()), + strict: v.strictObject({ a: v.string() }), + loose: v.looseObject({ b: v.string() }), + home: shared, + work: shared, + name: v.optional(v.string(), () => "anon"), + tags: v.pipe(v.array(v.string()), v.nonEmpty()) + }) + ); + expect(doc.defs).toEqual({ + main: { + type: "record", + record: { + type: "object", + required: [ + "slug", + "status", + "kind", + "priority", + "version", + "one", + "yes", + "level", + "anything", + "bag", + "strict", + "loose", + "home", + "work", + "tags" + ], + properties: { + slug: { type: "string", minLength: 2, minGraphemes: 1 }, + status: { type: "string", enum: ["draft", "live"] }, + kind: { type: "string", const: "note" }, + priority: { type: "integer", enum: [1, 2, 3] }, + version: { type: "integer", const: 1 }, + one: { type: "integer", const: 1 }, + yes: { type: "boolean", const: true }, + level: { type: "integer", enum: [1, 2] }, + anything: { type: "unknown" }, + bag: { type: "unknown" }, + strict: { type: "ref", ref: "#strict" }, + loose: { type: "ref", ref: "#loose" }, + // A schema used twice is hoisted once and referenced twice. + home: { type: "ref", ref: "#home" }, + work: { type: "ref", ref: "#home" }, + name: { type: "string", default: "anon" }, + tags: { type: "array", items: { type: "string" }, minLength: 1 } + } + } + }, + strict: { + type: "object", + required: ["a"], + properties: { a: { type: "string" } } + }, + loose: { + type: "object", + required: ["b"], + properties: { b: { type: "string" } } + }, + home: { + type: "object", + required: ["city"], + properties: { city: { type: "string" } } + } + }); + }); + + it("should suffix hoisted names that collide", () => { + // Two different anonymous objects under the same property name must + // become two definitions, not one overwriting the other. + const doc = toLexicon( + record("com.example.thing", { + first: v.object({ item: v.object({ a: v.string() }) }), + second: v.object({ item: v.object({ b: v.string() }) }) + }) + ); + expect(Object.keys(doc.defs)).toStrictEqual([ + "main", + "first", + "second", + "item", + "item2" + ]); + expect(doc.defs.first).toMatchObject({ + properties: { item: { type: "ref", ref: "#item" } } + }); + expect(doc.defs.second).toMatchObject({ + properties: { item: { type: "ref", ref: "#item2" } } + }); + }); + + it("should infer the NSID from a token", () => { + expect( + toLexicon({ confirmed: token("com.atproto.label.defs#confirmed") }).id + ).toBe("com.atproto.label.defs"); + }); + + it("should fail loudly for more schemas Lexicon cannot express", () => { + const thing = (entries: v.ObjectEntries) => + record("com.example.thing", entries); + const cases: [v.ObjectEntries, string][] = [ + [ + { grid: v.array(v.array(v.string())) }, + "Lexicon arrays cannot be nested." + ], + [ + { list: v.pipe(v.array(v.string()), v.includes("a")) }, + 'The "includes" action cannot be converted' + ], + [{ big: v.literal(1n) }, 'The "literal" schema cannot be converted'], + [ + { mixed: v.picklist(["a", 1]) }, + 'The "picklist" schema cannot be converted' + ], + [{ when: v.date() }, 'The "date" schema cannot be converted'], + [ + { kind: token("com.example.defs#kind") }, + "Tokens cannot be used as properties" + ], + [ + { embed: v.variant("$type", [v.object({ $type: v.literal("a") })]) }, + 'Lexicon unions must be created with the "union" function' + ] + ]; + for (const [entries, message] of cases) { + expect(() => toLexicon(thing(entries))).toThrow(message); + } + expect(() => + toLexicon( + v.pipe(v.string(), v.metadata({ lexicon: { type: "record" } })), + { id: "com.example.thing" } + ) + ).toThrow("Records must wrap an object schema."); + expect(() => + toLexicon( + { embed: union([v.object({ $type: v.literal("com.example.a") })]) }, + { id: "com.example.thing" } + ) + ).toThrow('The definition "embed" cannot be a reference or union.'); + }); + + it("should report actions whose requirement is not what Lexicon expects", () => { + // Another tool could build a schema that reuses Valibot action types + // with a different requirement shape. Those must be reported rather + // than silently dropped from the document. + const bogus = (type: string) => + // oxlint-disable-next-line typescript/no-unsafe-type-assertion + ({ kind: "validation", type, requirement: Symbol("bogus") }) as never; + const cases: [v.GenericSchema, string][] = [ + [v.string(), "min_bytes"], + [v.string(), "max_bytes"], + [v.string(), "min_graphemes"], + [v.string(), "max_graphemes"], + [v.string(), "values"], + [v.string(), "value"], + [v.pipe(v.number(), v.integer()), "min_value"], + [v.pipe(v.number(), v.integer()), "max_value"], + [v.pipe(v.number(), v.integer()), "values"], + [v.pipe(v.number(), v.integer()), "value"], + [v.array(v.string()), "min_length"], + [v.array(v.string()), "max_length"] + ]; + for (const [schema, type] of cases) { + expect(() => + toLexicon( + record("com.example.thing", { x: v.pipe(schema, bogus(type)) }) + ) + ).toThrow(`The "${type}" action cannot be converted`); + } + }); + + it("should describe parameters and allow unknown array items", () => { + const doc = toLexicon( + query("com.example.q", { + parameters: v.pipe( + v.object({ raw: v.array(v.unknown()) }), + v.description("Filters.") + ) + }) + ); + expect(doc.defs.main).toEqual({ + type: "query", + parameters: { + type: "params", + description: "Filters.", + required: ["raw"], + properties: { raw: { type: "array", items: { type: "unknown" } } } + } + }); + }); + + it("should fail loudly for XRPC shapes Lexicon cannot express", () => { + const params = (entries: v.ObjectEntries) => + query("com.example.q", { parameters: v.object(entries) }); + expect(() => toLexicon(params({ since: v.nullable(v.string()) }))).toThrow( + "XRPC parameters cannot be nullable." + ); + expect(() => + toLexicon(params({ tags: v.optional(v.array(v.string()), () => []) })) + ).toThrow( + 'Only string, integer and boolean properties can have a default value, not "tags".' + ); + expect(() => + toLexicon(params({ filter: v.object({ a: v.string() }) })) + ).toThrow( + 'XRPC parameters can only be primitives or arrays of primitives, not "filter".' + ); + expect(() => + toLexicon(query("com.example.q", { parameters: v.string() })) + ).toThrow("XRPC parameters must be an object schema."); + expect(() => + toLexicon( + query("com.example.q", { + output: { encoding: "application/json", schema: v.string() } + }) + ) + ).toThrow( + 'XRPC bodies must be an object, a reference or a union schema, not "output".' + ); + expect(() => + toLexicon( + subscription("com.example.s", { + message: { schema: v.object({ a: v.string() }) } + }) + ) + ).toThrow("Subscription messages must be a union schema."); + }); + + it("should stay silent when errorMode is ignore", () => { + const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); + try { + const doc = toLexicon( + record("com.example.thing", { ratio: v.number() }), + { + errorMode: "ignore" + } + ); + expect(doc.defs.main).toMatchObject({ type: "record" }); + expect(warn).not.toHaveBeenCalled(); + } finally { + warn.mockRestore(); + } + }); + it("should only warn when errorMode is warn", () => { const warnings: string[] = []; const original = console.warn; diff --git a/src/methods/compileLexicon.ts b/src/methods/compileLexicon.ts index d5f3618..9440c4a 100644 --- a/src/methods/compileLexicon.ts +++ b/src/methods/compileLexicon.ts @@ -103,10 +103,14 @@ interface Environment { function lookup(callee: string): AnyFunction { const [namespace, name] = callee.split("."); const table: object = namespace === "v" ? v : LEX; + // Callees are produced by `buildLexicon`, which only names functions that + // exist, so the guards below never fire. + /* istanbul ignore next */ const fn: unknown = name !== void 0 && Object.hasOwn(table, name) ? Reflect.get(table, name) : null; + /* istanbul ignore next */ if (typeof fn !== "function") { throw new Error(`Unknown function "${callee}"`); } @@ -141,6 +145,9 @@ function isCompiledDefinition(value: unknown): value is CompiledDefinition { */ function localSchema(environment: Environment, name: string): v.GenericSchema { const definition = environment.locals.get(name); + // `buildLexicon` rejects unknown local references and orders definitions + // so that dependencies are evaluated first. + /* istanbul ignore next */ if (definition === void 0) { throw new Error(`Unresolved reference "#${name}"`); } @@ -194,6 +201,7 @@ function evaluate(expr: Expr, environment: Environment): unknown { return definition; }); } + /* istanbul ignore next */ default: { throw new Error("Unknown expression"); } @@ -236,6 +244,8 @@ export function compileLexicon( }; for (const { name, expr } of buildLexicon(doc, config).defs) { const definition = evaluate(expr, environment); + // Every definition expression evaluates to a schema or an XRPC definition. + /* istanbul ignore next */ if (!isCompiledDefinition(definition)) { throw new Error(`Definition "${name}" did not compile to a schema`); } diff --git a/src/methods/fromLexicon.ts b/src/methods/fromLexicon.ts index aa1d8ae..6c24218 100644 --- a/src/methods/fromLexicon.ts +++ b/src/methods/fromLexicon.ts @@ -172,6 +172,7 @@ function print(expr: Expr, indent: number): string { } return `${expr.callee}(\n${args.map((arg) => inner + arg).join(",\n")}\n${pad})`; } + /* istanbul ignore next */ default: { throw new Error("Unknown expression"); } diff --git a/src/methods/toLexicon.ts b/src/methods/toLexicon.ts index a6c9e07..4e7268b 100644 --- a/src/methods/toLexicon.ts +++ b/src/methods/toLexicon.ts @@ -231,6 +231,8 @@ function isRecordKeyType(value: string): value is RecordKeyType { */ function splitOuter(schema: GenericSchema): SplitSchema { const [base, ...rest] = getPipeItems(schema); + // The first pipe item of a Valibot pipe is always a schema. + /* istanbul ignore next */ return { base: isSchema(base) ? base : schema, actions: rest.filter(isAction) @@ -269,10 +271,13 @@ function resolveLazy(schema: GenericSchema): GenericSchema { let resolved = schema; while (resolved.type === "lazy") { const getter = prop(resolved, "getter"); + // A Valibot lazy schema always has a getter that returns a schema. + /* istanbul ignore next */ if (typeof getter !== "function") { return resolved; } const next: unknown = getter(null); + /* istanbul ignore next */ if (!isSchema(next)) { return resolved; } @@ -440,6 +445,9 @@ function convertUnion( const refs = getUnionOptions(split.base).map((option) => { const resolved = resolveUnionOption(option); const name = getTypeName(resolved); + // `union()` already rejects options without a `$type` literal when the + // options are read above. + /* istanbul ignore next */ if (name === null) { throw new Error("Union options must declare a `$type` literal"); } @@ -553,6 +561,8 @@ function convertString( * @returns The known values, if any. */ function getKnownValues(metadata: unknown): readonly string[] | null { + // Valibot metadata is always an object. + /* istanbul ignore else */ if (typeof metadata === "object" && metadata !== null) { const lexicon = prop(metadata, "lexicon"); if (typeof lexicon === "object" && lexicon !== null) { @@ -635,6 +645,8 @@ function convertArray( ): LexArray { const item = prop(split.base, "item"); let items: LexArrayItem = { type: "unknown" }; + // A Valibot array schema always carries an item schema. + /* istanbul ignore else */ if (isSchema(item)) { const converted = convertValue(item, key, context); if (converted.type === "array") { @@ -815,6 +827,8 @@ function convertInline( } case "picklist": { const options = prop(base, "options"); + // A Valibot picklist always carries an options array. + /* istanbul ignore else */ if (Array.isArray(options)) { if (options.every((option) => typeof option === "string")) { return withDescription( @@ -915,6 +929,8 @@ function unwrapProperty(schema: GenericSchema): UnwrappedProperty { defaultValue = typeof default_ === "function" ? default_() : default_; } const wrapped = prop(current, "wrapped"); + // Valibot wrapper schemas always wrap a schema. + /* istanbul ignore next */ if (!isSchema(wrapped)) { break; } @@ -1293,6 +1309,8 @@ function inferId( } if (getLexiconMetadata(definition)?.type === "token") { const literal = prop(splitDeep(definition).base, "literal"); + // `token()` is built on a string literal. + /* istanbul ignore else */ if (typeof literal === "string") { return splitLexRef(literal).nsid; } diff --git a/src/schemas/__tests__/union.test.ts b/src/schemas/__tests__/union.test.ts index 9707961..678d9a3 100644 --- a/src/schemas/__tests__/union.test.ts +++ b/src/schemas/__tests__/union.test.ts @@ -94,6 +94,49 @@ describe("union", () => { expect(getUnionOptions(union([v.lazy(() => view)]))).toHaveLength(1); }); + it("should accept every object schema flavor as an option", () => { + const strict = v.strictObject({ $type: v.literal("com.example.a") }); + const rest = v.objectWithRest( + { $type: v.literal("com.example.b") }, + v.unknown() + ); + const schema = union([strict, rest], { closed: true }); + expect(v.parse(schema, { $type: "com.example.a" })).toStrictEqual({ + $type: "com.example.a" + }); + expect(v.parse(schema, { $type: "com.example.b", extra: 1 })).toStrictEqual( + { $type: "com.example.b", extra: 1 } + ); + expect(getUnionOptions(schema)).toHaveLength(2); + }); + + it("should accept any variant in an open union without options", () => { + // The Lexicon spec allows an open union with an empty `refs` list as a + // placeholder for variants that will be defined later. + const anything = union([]); + expect(v.parse(anything, { $type: "com.example.later" })).toStrictEqual({ + $type: "com.example.later" + }); + expect(v.safeParse(anything, {}).success).toBe(false); + }); + + it("should fail loudly for lazy options that are not object schemas", () => { + // oxlint-disable-next-line typescript/no-unsafe-type-assertion + const text = v.lazy(() => v.string()) as never; + expect(() => v.parse(union([text]), { $type: "x" })).toThrow( + "Union options must be object schemas" + ); + // oxlint-disable-next-line typescript/no-unsafe-type-assertion + const nothing = v.lazy(() => null as never) as never; + expect(() => v.parse(union([nothing]), { $type: "x" })).toThrow( + "Lazy union options must resolve to a schema" + ); + }); + + it("should report no options for values that are not schemas", () => { + expect(getUnionOptions({})).toStrictEqual([]); + }); + it("should fail loudly for options without a $type literal", () => { const broken = union([v.looseObject({ name: v.string() })]); expect(() => v.parse(broken, { name: "x" })).toThrow( diff --git a/src/utils/__tests__/base32.test.ts b/src/utils/__tests__/base32.test.ts new file mode 100644 index 0000000..4c84893 --- /dev/null +++ b/src/utils/__tests__/base32.test.ts @@ -0,0 +1,55 @@ +import { describe, expect, it } from "vitest"; +import { TID_REGEX } from "../../regex.js"; +import { + BASE32_SORTABLE_ALPHABET, + decodeBase32, + encodeBase32, + encodeTid +} from "../base32.js"; + +describe("base32", () => { + it("should round trip bytes of every alignment", () => { + // Five bytes fill eight characters exactly. Every other length leaves + // bits that must be zero padded on the way out and dropped on the way + // back, which is where hand-rolled base32 usually goes wrong. + for (let length = 0; length <= 10; length++) { + const bytes = Uint8Array.from( + { length }, + (_, index) => (index * 37 + 11) & 255 + ); + const encoded = encodeBase32(bytes); + expect(encoded).toHaveLength(Math.ceil((length * 8) / 5)); + expect(decodeBase32(encoded)).toStrictEqual(bytes); + } + }); + + it("should encode with the sortable alphabet when asked", () => { + const bytes = Uint8Array.from([0, 255, 16]); + const encoded = encodeBase32(bytes, BASE32_SORTABLE_ALPHABET); + expect(encoded).not.toBe(encodeBase32(bytes)); + expect(decodeBase32(encoded, BASE32_SORTABLE_ALPHABET)).toStrictEqual( + bytes + ); + }); + + it("should reject strings that are not canonical base32", () => { + // CIDs use the lowercase, unpadded alphabet only. + expect(decodeBase32("ABCD")).toBeNull(); + expect(decodeBase32("ab=")).toBeNull(); + // A single character carries fewer bits than a byte. + expect(decodeBase32("b")).toBeNull(); + // Trailing bits must be zero, otherwise two strings decode to one value. + expect(decodeBase32("aa")).toStrictEqual(Uint8Array.from([0])); + expect(decodeBase32("ab")).toBeNull(); + }); + + it("should encode TIDs that sort by timestamp", () => { + const earlier = encodeTid(1_700_000_000_000_000, 5); + const later = encodeTid(1_700_000_000_000_001, 5); + expect(earlier).toMatch(TID_REGEX); + expect([later, earlier].sort()).toStrictEqual([earlier, later]); + // The clock id occupies the low ten bits and is masked, not carried. + expect(encodeTid(0, 1024)).toBe(encodeTid(0, 0)); + expect(encodeTid(0, 0)).toBe("2222222222222"); + }); +}); diff --git a/src/utils/__tests__/lexRef.test.ts b/src/utils/__tests__/lexRef.test.ts new file mode 100644 index 0000000..1dd23c0 --- /dev/null +++ b/src/utils/__tests__/lexRef.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from "vitest"; +import { + joinLexRef, + splitLexRef, + toAbsoluteLexRef, + toRelativeLexRef +} from "../lexRef.js"; + +describe("lexRef", () => { + it("should split references the way the Lexicon spec reads them", () => { + // A bare NSID means the main definition of that document. + expect(splitLexRef("com.example.post")).toStrictEqual({ + nsid: "com.example.post", + name: "main" + }); + expect(splitLexRef("com.example.defs#view")).toStrictEqual({ + nsid: "com.example.defs", + name: "view" + }); + // A leading hash is a reference within the current document. + expect(splitLexRef("#view")).toStrictEqual({ nsid: "", name: "view" }); + }); + + it("should join references back to their shortest spelling", () => { + expect(joinLexRef("com.example.post", "main")).toBe("com.example.post"); + expect(joinLexRef("com.example.defs", "view")).toBe( + "com.example.defs#view" + ); + }); + + it("should convert between document-relative and global spellings", () => { + const doc = "com.example.defs"; + expect(toRelativeLexRef("com.example.defs#view", doc)).toBe("#view"); + expect(toRelativeLexRef("#view", doc)).toBe("#view"); + expect(toRelativeLexRef("com.example.post", doc)).toBe("com.example.post"); + expect(toAbsoluteLexRef("#view", doc)).toBe("com.example.defs#view"); + expect(toAbsoluteLexRef("#main", doc)).toBe("com.example.defs"); + // References into other documents are already global. + expect(toAbsoluteLexRef("com.example.post#reply", doc)).toBe( + "com.example.post#reply" + ); + }); +}); diff --git a/src/utils/__tests__/parseAtUri.test.ts b/src/utils/__tests__/parseAtUri.test.ts new file mode 100644 index 0000000..1d6aa15 --- /dev/null +++ b/src/utils/__tests__/parseAtUri.test.ts @@ -0,0 +1,27 @@ +import { describe, expect, it } from "vitest"; +import { parseAtUri } from "../parseAtUri.js"; + +describe("parseAtUri", () => { + it("should split a record URI into its parts", () => { + expect( + parseAtUri( + "at://did:plc:ewvi7nxzyoun6zhxrhs64oiz/app.bsky.feed.post/3jzfcijpj2z2a" + ) + ).toStrictEqual({ + authority: "did:plc:ewvi7nxzyoun6zhxrhs64oiz", + collection: "app.bsky.feed.post", + rkey: "3jzfcijpj2z2a" + }); + expect(parseAtUri("at://alice.bsky.social")).toStrictEqual({ + authority: "alice.bsky.social" + }); + }); + + it("should decode fragments and reject malformed escapes", () => { + const base = "at://alice.bsky.social/app.bsky.feed.post/3jzfcijpj2z2a"; + expect(parseAtUri(`${base}#/a%20b`)?.fragment).toBe("/a b"); + // "%E0" starts a multi-byte sequence that never completes, which the + // spec's JSON pointer rules do not allow. + expect(parseAtUri(`${base}#/%E0`)).toBeNull(); + }); +}); diff --git a/src/valimock.ts b/src/valimock.ts index 8bfc36f..1d93de3 100644 --- a/src/valimock.ts +++ b/src/valimock.ts @@ -245,6 +245,28 @@ export function mockBytes(faker: Faker, minLength = 0, maxLength = 64): string { return btoa(binary).replace(/=+$/u, ""); } +/** + * The length of the unpadded base64 encoding of `bytes` raw bytes. + * + * @param bytes The number of raw bytes. + * + * @returns The number of base64 characters. + */ +function base64Length(bytes: number): number { + return Math.ceil((bytes * 4) / 3); +} + +/** + * The number of raw bytes that fit in `characters` unpadded base64 characters. + * + * @param characters The number of base64 characters. + * + * @returns The number of raw bytes. + */ +function decodedLength(characters: number): number { + return Math.floor((characters * 3) / 4); +} + /** * Capitalizes the first character of a word. * @@ -316,7 +338,14 @@ export const stringActions: Readonly> = { }, min_decoded_bytes: (ctx, action) => { ctx.format = "bytes"; - ctx.custom.minDecodedBytes = requirementOf(action); + const minDecodedBytes = requirementOf(action); + ctx.custom.minDecodedBytes = minDecodedBytes; + // Valimock caps every string at `ctx.bounds.max` characters. A Lexicon + // minimum larger than that cap fits would otherwise be unsatisfiable, so + // widen the bound to the base64 length of the minimum. + if (typeof minDecodedBytes === "number") { + ctx.bounds.max = Math.max(ctx.bounds.max, base64Length(minDecodedBytes)); + } }, max_decoded_bytes: (ctx, action) => { ctx.format = "bytes"; @@ -346,9 +375,17 @@ export const stringFormats: Readonly> = { typeof ctx.custom.minDecodedBytes === "number" ? ctx.custom.minDecodedBytes : 0, - typeof ctx.custom.maxDecodedBytes === "number" - ? ctx.custom.maxDecodedBytes - : 64 + // A Lexicon `maxLength` on bytes is an upper bound, not a target. + // Mocks stay within Valimock's string bound (128 characters unless the + // schema says otherwise) so a 2 MB CAR file limit yields a few dozen + // bytes rather than megabytes of base64 that Valimock rejects and + // regenerates until its retry budget runs out. + Math.min( + typeof ctx.custom.maxDecodedBytes === "number" + ? ctx.custom.maxDecodedBytes + : 64, + decodedLength(ctx.bounds.max) + ) ), cid: (ctx) => mockCid(ctx.faker), datetime: (ctx) => mockDatetime(ctx.faker), diff --git a/vite.config.ts b/vite.config.ts index f5bb283..3337bb4 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -31,6 +31,11 @@ export default defineConfig({ include: ["**/*.{test,spec}.{ts,tsx}"], exclude: ["**/node_modules/**", "**/dist/**"], environment: "node", - passWithNoTests: true + passWithNoTests: true, + coverage: { + include: ["src/**"], + exclude: ["src/**/__tests__/**"], + thresholds: { 100: true } + } } });