Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
23 changes: 23 additions & 0 deletions src/codegen/fake.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,}$/)
})
})
29 changes: 24 additions & 5 deletions src/codegen/fake.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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":
Expand Down
42 changes: 37 additions & 5 deletions src/codegen/openapi.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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" }] }] }
Expand Down
41 changes: 37 additions & 4 deletions src/codegen/openapi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -46,6 +58,7 @@ const KNOWN = new Set([
"minimum",
"maximum",
"items",
"prefixItems",
"minItems",
"maxItems",
"uniqueItems",
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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" }
Expand Down
10 changes: 9 additions & 1 deletion src/codegen/pipeline.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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("-")
Expand Down
20 changes: 20 additions & 0 deletions src/codegen/swagger.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string>) =>
Expand Down
Loading