diff --git a/CHANGELOG.md b/CHANGELOG.md index fb2dd22..cd4ce5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,11 @@ Every entry says what changed as a caller sees it, why, and what to watch for group up to 0.695.0 does, must read `place.basic` instead. Until it does, a call that offers Basic and a token may be signed with Basic, and a token with no `:` is no longer refused. The caller keeps that check: `value` never throws. Digest is still `undefined`. +- **A sample of a union takes the branch with the most required fields, not the first.** Attio's `GET /v2/self` + answers `{ active: false }` first, so `fakeApi` answered a sign-in check without the workspace's id. Watch for: a + test that reads a sampled union, in `fakeApi` or the GraphQL fake, now sees the larger branch. A field typed + `string | { id }` samples as the object; Notion's description samples 92 of its 609 definitions differently, while + HubSpot's, ydisk's, Drive's and Calendar's sample as before. ### Fixed @@ -54,6 +59,17 @@ Every entry says what changed as a caller sees it, why, and what to watch for - **WC-ARCH-5 names a known gap:** drive's and ydisk's live `files` groups are hand-written in each CLI until cli-core has a shared files domain. - **Publishing no longer tells a CLI to pass `--profiles all` in `server.json`.** +- **`names: { fromPath: true }` names a PUT on a collection `-upsert` when a PUT on its item exists too.** Attio's + `PUT /v2/objects/{object}/records` (create or update by a unique value) and `PUT …/records/{record_id}` both became + `objects-records-replace`, and generation stopped. Watch for: a CLI that named one of such a pair in + `names.commands` to avoid the clash now gets `-upsert` for the other. +- **A string with a `pattern` gets a sample the pattern and its length bounds take.** A pattern of groups, + alternatives or a `.` (Attio's `^https:\/\/.*` and ISO 8601 durations) fell back to `xxxxxx`, which the strict fake + then refused. +- **The OpenAPI adapter reads `prefixItems`, an `allOf` of unions of plain values, and skips `minProperties` and + `maxProperties`.** Each stopped generation for Attio's description. A tuple is read as a list of its places, an + `allOf` of unions with no object in any branch as its first member; one with an object is still refused. A closed + tuple (`items: false`) is still refused. ## 0.116.0 — 17.11.2026 diff --git a/src/codegen/fake.test.ts b/src/codegen/fake.test.ts index 1f2dfdf..d52a634 100644 --- a/src/codegen/fake.test.ts +++ b/src/codegen/fake.test.ts @@ -364,3 +364,26 @@ describe("pagination detection does not guess", () => { ) }) }) + +describe("sampleOf for a fake's answers", () => { + it("takes the union branch that asks the most, so a reader finds its fields", () => { + const inactive: SchemaNode = { type: "object", properties: { active: { type: "boolean" } }, required: ["active"] } + const active: SchemaNode = { + type: "object", + properties: { active: { type: "boolean" }, workspace_id: { type: "string" } }, + required: ["active", "workspace_id"], + } + expect(sampleOf({ type: "union", of: [inactive, active] }, {})).toMatchObject({ workspace_id: expect.any(String) }) + }) + + it("gives a string a pattern of groups or a wildcard takes", () => { + const duration = "P(?:(\\d+Y)?(\\d+D)?(?:T(\\d+H)?)?)" + for (const pattern of ["^https:\\/\\/.*", duration, "^[-+]?([1-8]?\\d(\\.\\d+)?|90(\\.0+)?)$", "^id_.{4}$"]) + expect(new RegExp(pattern).test(String(sampleOf({ type: "string", pattern }, {}))), pattern).toBe(true) + }) + + it("keeps a pattern's sample inside the string's length bounds", () => { + expect(String(sampleOf({ type: "string", pattern: "^.*$", minLength: 3 }, {})).length).toBeGreaterThanOrEqual(3) + expect(String(sampleOf({ type: "string", pattern: "^(\\d+)$", minLength: 3 }, {}))).toMatch(/^\d{3,}$/) + }) +}) diff --git a/src/codegen/fake.ts b/src/codegen/fake.ts index a8bb01e..7c367ee 100644 --- a/src/codegen/fake.ts +++ b/src/codegen/fake.ts @@ -232,8 +232,11 @@ const patternSample = (pattern: string): string | undefined => { atom = next === "d" ? "0" : next === "w" ? "x" : /[^a-zA-Z0-9]/.test(next) ? next : "" if (!atom) return undefined at += 2 - } else if ("()|.".includes(char)) return undefined - else { + } else if ("()|".includes(char)) return undefined + else if (char === ".") { + atom = "x" + at += 1 + } else { atom = char at += 1 } @@ -246,6 +249,12 @@ const patternSample = (pattern: string): string | undefined => { return regexOf(pattern)?.test(sample) ? sample : undefined } +const requiredCount = (node: SchemaNode, definitions: Definitions): number => + objectParts(node, definitions)?.required.length ?? 0 + +// Strings a pattern made of groups or alternatives often takes: a link, an ISO duration and date, a number, a word. +const GUESSES = ["https://example.com", "P1D", "2026-01-01", "0", "000000", "x", "example", "a@example.com"] + /** A value the schema accepts: the first enum value, the minimum, one array item, every object field. */ export const sampleOf = ( node: SchemaNode, @@ -258,8 +267,11 @@ export const sampleOf = ( // A schema that contains itself stops at its first repeat. return target && !seen.has(node.ref) ? sampleOf(target, definitions, new Set([...seen, node.ref])) : null } - case "union": - return node.of[0] ? sampleOf(node.of[0], definitions, seen) : null + case "union": { + // The branch that asks the most: a first branch such as `{ active: false }` would leave out what a reader needs. + const [best] = [...node.of].sort((a, b) => requiredCount(b, definitions) - requiredCount(a, definitions)) + return best ? sampleOf(best, definitions, seen) : null + } case "allOf": { const parts = objectParts(node, definitions) return parts ? sampleOf({ type: "object", ...parts }, definitions, seen) : null @@ -268,7 +280,14 @@ export const sampleOf = ( if (node.enum?.[0] !== undefined) return node.enum[0] if (node.format === "binary") return "attach://xxxxxx" const plain = "x".repeat(Math.max(node.minLength ?? 6, 1)).slice(0, node.maxLength ?? 64) - return node.pattern === undefined ? plain : (patternSample(node.pattern) ?? plain) + if (node.pattern === undefined) return plain + const pattern = regexOf(node.pattern) + const fits = (one: string | undefined): one is string => + one !== undefined && + one.length >= (node.minLength ?? 0) && + one.length <= (node.maxLength ?? Number.POSITIVE_INFINITY) && + pattern?.test(one) !== false + return [patternSample(node.pattern), ...GUESSES, plain].find(fits) ?? plain } case "integer": case "number": diff --git a/src/codegen/openapi.test.ts b/src/codegen/openapi.test.ts index cde0a7e..fa6bdfe 100644 --- a/src/codegen/openapi.test.ts +++ b/src/codegen/openapi.test.ts @@ -81,22 +81,54 @@ describe("adaptOpenApi refuses what it would otherwise get wrong", () => { }) it("names an unknown keyword", () => { - expect(problemsOf(document({ Pet: { prefixItems: [{ type: "string" }] } }))).toEqual([ - '#/components/schemas/Pet: unsupported keyword "prefixItems"', + expect(problemsOf(document({ Pet: { patternProperties: { "^x": { type: "string" } } } }))).toEqual([ + '#/components/schemas/Pet: unsupported keyword "patternProperties"', "#/components/schemas/Pet: a schema with no type", ]) }) - it("refuses oneOf beside anyOf, and an allOf of two unions", () => { + it("refuses oneOf beside anyOf, and an allOf of two unions beside an object or of unions of objects", () => { const either = { oneOf: [{ type: "string" }, { type: "integer" }] } + const base = { type: "object", properties: { id: { type: "string" } } } expect( - problemsOf(document({ Both: { ...either, anyOf: [{ type: "string" }] }, Two: { allOf: [either, either] } })), + problemsOf( + document({ + Both: { ...either, anyOf: [{ type: "string" }] }, + Two: { allOf: [either, either] }, + Three: { allOf: [either, either, base] }, + Objects: { allOf: [{ oneOf: [base, { type: "string" }] }, { oneOf: [base, { type: "string" }] }] }, + }), + ), ).toEqual([ "#/components/schemas/Both: both oneOf and anyOf on one schema", - "#/components/schemas/Two: an allOf of several unions", + "#/components/schemas/Three: an allOf of several unions", + "#/components/schemas/Objects: an allOf of several unions", ]) }) + it("reads a tuple as a list of its places, an allOf of unions as the first, and skips a property count", () => { + const path = { + anyOf: [ + { type: "string" }, + { type: "array", prefixItems: [{ type: "string" }], items: { type: "integer" }, minItems: 2 }, + ], + } + const input = document({ + Path: path, + Narrowed: { allOf: [{ $ref: "#/components/schemas/Path" }, { anyOf: [path.anyOf[0], { type: "null" }] }] }, + Params: { type: "object", additionalProperties: { type: "string" }, minProperties: 1, maxProperties: 9 }, + }) + expect(problemsOf(input)).toEqual([]) + expect(schema(input, "Path")?.schema).toMatchObject({ + type: "union", + of: [ + { type: "string" }, + { type: "array", minItems: 2, items: { type: "union", of: [{ type: "string" }, { type: "integer" }] } }, + ], + }) + expect(schema(input, "Narrowed")?.schema).toMatchObject({ type: "ref", ref: "Path" }) + }) + it("refuses an allOf that distributes a union inside itself, instead of recursing forever", () => { const base = { type: "object", properties: { id: { type: "string" } } } const Loop = { oneOf: [{ type: "string" }, { allOf: [base, { $ref: "#/components/schemas/Loop" }] }] } diff --git a/src/codegen/openapi.ts b/src/codegen/openapi.ts index 66f2717..1fcac58 100644 --- a/src/codegen/openapi.ts +++ b/src/codegen/openapi.ts @@ -29,7 +29,19 @@ const METHODS = ["get", "post", "put", "patch", "delete", "head"] as const * Carried by the model, or harmless to lose. `not` only narrows what a payload may hold; losing it * accepts more, never refuses a valid request. */ -const IGNORED = new Set(["readOnly", "example", "examples", "externalDocs", "title", "xml", "writeOnly", "not"]) +// minProperties and maxProperties only check a count; the service checks it again, so a looser schema loses nothing. +const IGNORED = new Set([ + "readOnly", + "example", + "examples", + "externalDocs", + "title", + "xml", + "writeOnly", + "not", + "minProperties", + "maxProperties", +]) const KNOWN = new Set([ ...IGNORED, "type", @@ -46,6 +58,7 @@ const KNOWN = new Set([ "minimum", "maximum", "items", + "prefixItems", "minItems", "maxItems", "uniqueItems", @@ -258,7 +271,7 @@ class Adapter { const types = new Set(source.enum.map(typeOfConst)) if (types.size === 1) return [...types][0] } - if (source.items !== undefined) return "array" + if (source.items !== undefined || source.prefixItems !== undefined) return "array" if (source.properties !== undefined || source.required !== undefined || source.additionalProperties !== undefined) return "object" return undefined @@ -343,8 +356,12 @@ class Adapter { } case "array": { // JSON Schema reads a missing `items` as "any item". - const items = - source.items === undefined ? { type: "unknown" as const } : this.schema(source.items, `${where}[]`) + const rest = source.items === undefined ? { type: "unknown" as const } : this.schema(source.items, `${where}[]`) + // A tuple (`prefixItems`) is read as a list whose every item is one of its places: looser, never wrong. + const places = Array.isArray(source.prefixItems) + ? source.prefixItems.map((one, index) => this.schema(one, `${where}.prefixItems[${index}]`)) + : [] + const items: SchemaNode = places.length === 0 ? rest : { type: "union", of: [...places, rest] } const node: Node<"array"> = { ...common, type: "array", items } if (typeof source.minItems === "number") node.minItems = source.minItems if (typeof source.maxItems === "number") node.maxItems = source.maxItems @@ -439,6 +456,22 @@ class Adapter { }) if (unions.length === 0) return undefined const [union] = unions + // Every value of an allOf of unions of plain values passes each one, so the first alone is looser and never refuses + // a right value, as Attio's kanban status_attribute narrows a path union again. With an object in a branch the + // value may need fields from two unions at once, which the first alone would refuse. + const plain = (member: unknown) => + !isObject(member) || + (member.type !== "object" && + member.properties === undefined && + member.allOf === undefined && + member.$ref === undefined) + if ( + unions.length > 1 && + union && + unions.length === members.length && + unions.every((one) => one.members.every(plain)) + ) + return { ...this.schema(union.member, `${where}.allOf[0]`), ...common } if (unions.length > 1 || !union) { this.problems.push(`${where}: an allOf of several unions`) return { type: "unknown" } diff --git a/src/codegen/pipeline.ts b/src/codegen/pipeline.ts index 03512c1..491ad09 100644 --- a/src/codegen/pipeline.ts +++ b/src/codegen/pipeline.ts @@ -78,12 +78,20 @@ const commandFromPath = (operation: ApiOperation, all: readonly ApiOperation[], ((other.binding.method === "GET" && other.binding.path === path) || (other.binding.path.startsWith(`${path}/{`) && !other.binding.path.slice(path.length + 1).includes("/"))), ) + // A PUT on the collection beside a PUT on its item is the "create or update by a unique value" (Attio's assert). + const itemPut = all.some( + (other) => + other.binding.kind === "http" && + other.binding.method === "PUT" && + other.binding.path.startsWith(`${path}/{`) && + !other.binding.path.slice(path.length + 1).includes("/"), + ) const verb = { GET: onItem || parts.at(-1) === "me" ? "get" : "list", HEAD: "head", DELETE: "delete", PATCH: "update", - PUT: onItem || collection ? "replace" : "", + PUT: onItem ? "replace" : collection ? (itemPut ? "upsert" : "replace") : "", POST: onItem ? "update" : collection ? "create" : "", }[method] return [...words, verb].filter(Boolean).join("-") diff --git a/src/codegen/swagger.test.ts b/src/codegen/swagger.test.ts index 5d1dc23..7a82f5e 100644 --- a/src/codegen/swagger.test.ts +++ b/src/codegen/swagger.test.ts @@ -175,6 +175,26 @@ describe("command names and spec patches", () => { expect(commands).toEqual(["users-list", "users-me-get", "blocks-children-list"]) }) + it("names a PUT on a collection beside a PUT on its item upsert, so the two do not clash", () => { + const id = [{ name: "record_id", in: "path", required: true, schema: { type: "string" } }] + const attio = { + openapi: "3.1.0", + info: {}, + paths: { + "/v2/records": { put: { operationId: "assert" } }, + "/v2/records/{record_id}": { parameters: id, put: { operationId: "replace" } }, + "/v2/notes": { get: { operationId: "notes" }, put: { operationId: "notes-put" } }, + }, + components: { schemas: {} }, + } + const [manifest] = generate(adaptOpenApi(attio), [manifestGenerator({ path: "manifest.ts" })], { + banner: [], + names: { fromPath: true }, + }) + const commands = [...(manifest?.content.matchAll(/"command": "([^"]+)"/g) ?? [])].map(([, command]) => command) + expect(commands).toEqual(["records-upsert", "records-replace", "notes-list", "notes-replace"]) + }) + it("refuses a name for an unknown operation or one that is not kebab case", () => { const { document } = patchSpec(hubspot, { stubMissingSchemas: "missing" }) const run = (commands: Record) =>