From e65b05dfcb71a8681e4d815875d180326e039b4d Mon Sep 17 00:00:00 2001 From: Drake Costa Date: Wed, 4 Nov 2026 15:53:01 -0800 Subject: [PATCH 1/2] fix: keep bytes mocks within Valimock's string bound Mocking `com.atproto.sync.subscribeRepos#commit` took over a second and timed out under Wallaby. Its `blocks` field is a Lexicon `bytes` with `maxLength: 2000000`, and the `bytes` format generator picked a random size up to that limit, producing megabytes of base64 that Valimock rejected against its 128 character string bound and regenerated sixteen times before giving up with a warning. The generator now caps the decoded size at what fits in `ctx.bounds.max`, and `min_decoded_bytes` widens the bound when a Lexicon minimum would not otherwise fit. The integration test no longer silences Valimock warnings and asserts there are none, since a retry-budget warning is both a generator that disagrees with the schema and the slow path. --- .bumpy/bytes-mock-bounds.md | 5 ++++ src/__tests__/valimock.test.ts | 30 +++++++++++++++++++++-- src/valimock.ts | 45 +++++++++++++++++++++++++++++++--- 3 files changed, 74 insertions(+), 6 deletions(-) create mode 100644 .bumpy/bytes-mock-bounds.md 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/src/__tests__/valimock.test.ts b/src/__tests__/valimock.test.ts index c7db283..88e72b6 100644 --- a/src/__tests__/valimock.test.ts +++ b/src/__tests__/valimock.test.ts @@ -4,6 +4,7 @@ import { Valimock } from "valimock"; 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, @@ -18,10 +19,11 @@ 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 +34,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", () => { 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), From e9989a08517982244c2da04adaf3a124fe2866d6 Mon Sep 17 00:00:00 2001 From: Drake Costa Date: Wed, 4 Nov 2026 16:19:07 -0800 Subject: [PATCH 2/2] test: cover every branch and enforce 100% coverage Adds tests for the paths no published Lexicon fixture exercises: base32 decoding, Lexicon reference spelling, AT URI fragments, the unused mock generators and their fallbacks, every object schema flavor and the empty open union, XRPC and reference errors in compileLexicon, and the string, integer, array, XRPC and errorMode branches of toLexicon. Synthetic Lexicon documents cover the spec features the fixtures do not use and are round-tripped like the published ones. The handful of defensive branches that Valibot types make unreachable carry istanbul ignore hints with a reason. Coverage is configured with a 100% threshold and CI now runs the tests with coverage. --- .github/workflows/ci.yml | 2 +- src/__tests__/fixtures/synthetic.ts | 153 +++++++++++ src/__tests__/valimock.test.ts | 150 ++++++++++- src/actions/__tests__/decodedBytes.test.ts | 8 + src/methods/__tests__/compileLexicon.test.ts | 81 ++++++ src/methods/__tests__/fromLexicon.test.ts | 47 ++++ src/methods/__tests__/roundTrip.test.ts | 17 ++ src/methods/__tests__/toLexicon.test.ts | 269 ++++++++++++++++++- src/methods/compileLexicon.ts | 10 + src/methods/fromLexicon.ts | 1 + src/methods/toLexicon.ts | 18 ++ src/schemas/__tests__/union.test.ts | 43 +++ src/utils/__tests__/base32.test.ts | 55 ++++ src/utils/__tests__/lexRef.test.ts | 43 +++ src/utils/__tests__/parseAtUri.test.ts | 27 ++ vite.config.ts | 7 +- 16 files changed, 925 insertions(+), 6 deletions(-) create mode 100644 src/__tests__/fixtures/synthetic.ts create mode 100644 src/utils/__tests__/base32.test.ts create mode 100644 src/utils/__tests__/lexRef.test.ts create mode 100644 src/utils/__tests__/parseAtUri.test.ts 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 88e72b6..796a8ea 100644 --- a/src/__tests__/valimock.test.ts +++ b/src/__tests__/valimock.test.ts @@ -1,6 +1,22 @@ -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"; @@ -13,7 +29,14 @@ 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(), { @@ -121,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/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 } + } } });