diff --git a/changes/feat-tracker-manifest-fake.md b/changes/feat-tracker-manifest-fake.md new file mode 100644 index 000000000..1ace0d4e2 --- /dev/null +++ b/changes/feat-tracker-manifest-fake.md @@ -0,0 +1,10 @@ +### Added + +- **`trackerManifestContract`, `trackerManifestFixture` and `trackerManifestFake` in `@wirecat/cli-core/tracker/testing` + run `trackerSourceContract` over a tracker source built from a manifest**, with no code for the service: a CLI made + from `wirecat.config.ts` (linear-cli first) checks its tracker in one line, + `for (const { name, run } of trackerManifestContract(SOURCE, { api, definitions })) it(name, run)`. The fake is + cli-base's strict `graphqlFake` with three rows of each kind behind it, written where the map reads them and linked + across kinds, paged by the Relay cursor, read for changes by the since, archived rows hidden unless asked for. The + fixture brings the held ids, a dead cursor and the faults `skewed`, `change`, `archive` and `remove` + ([TRACKER.md](../docs/dev/TRACKER.md#the-contract-kit)). diff --git a/docs/dev/TRACKER.md b/docs/dev/TRACKER.md index e266c6837..6cea6974c 100644 --- a/docs/dev/TRACKER.md +++ b/docs/dev/TRACKER.md @@ -92,3 +92,36 @@ result. read again, `ids()` covering the full list, a dead cursor answering reset, a clock off by ten minutes either way, an archived row still listed, a deleted row leaving `ids()`, a list cut after its first page, and a spent budget ending a call that pages inside. `fakeTrackerSource` and `exampleTrackerRows` are an in-memory tracker for tests. + +A source built from a manifest runs the contract with no code for the service, as a CLI made from `wirecat.config.ts` +does in its generated test: + +```ts +for (const { name, run } of trackerManifestContract(SOURCE, { api, definitions })) it(name, run) +``` + +- `trackerManifestFake(manifest, { api, definitions })` is cli-base's strict `graphqlFake` with a tracker behind it: + three rows of each kind, sampled within every selection the kind's calls send. The values the map reads are written + where it reads them: ids `issue-1`, a fixed seeded time, a state type from `STATE_TYPES`, an enum's own value. A + field that points at another kind (`state.id`, `assignee.id`, `labels.nodes` with `each`) holds that kind's first + row. +- It answers each call within its selection, two rows a page by the operation's cursor. A change read keeps the rows + whose `updatedAt` is at or after the value at its `"{since}"` (after it, for `gt`), oldest first. An operation that + takes `includeArchived` hides archived rows unless the call sets it. +- The only filter it applies is that since, and it must sit at `.gte` or `.gt` inside + `filter`. Every call is refused when the since sits elsewhere (`createdAt.gte`, `updatedAt.lt`), when a list or id + call sends a `filter` (sync would mark the rows it leaves out deleted), and when a change call's `filter` holds + anything beside the since. Any other variable the fake cannot interpret, such as users' `includeDisabled: true`, + is trusted: it only picks which call of the manifest is answered, and the fake answers as if the tracker applied it. +- A call whose fixed variables match no call of the manifest, a cursor the fake never gave and an unreadable since are + refused and listed in `fake.refusals`, beside `graphqlFake`'s own (an unknown variable, a field the type lacks). + `touch`, `archive` and `remove` change a row on the tracker's side. Building the fake fails for a kind with + `changes` whose `updatedAt` the map does not read from a path. +- `trackerManifestFixture` adds the source over it, the ids it holds per kind (`held`), a dead cursor (`"not a + time"`, which the source answers with `reset` itself, without a call: the case checks the source, never the fake or + the tracker's own refusal of a stale cursor), and the faults + on the issue kind, else the last kind with `changes`: `skewed` and `change`, `archive` when the map reads + `archivedAt`, and `remove`. `trackerManifestContract` runs `trackerSourceContract` over it and fails a case whose + calls the fake refused, with the refusals as its message. +- It answers GraphQL operations paged by a cursor only. `self` is not part of the contract, so the fake leaves its call + to `graphqlFake`'s sample. diff --git a/src/testing/tracker-graphql.ts b/src/testing/tracker-graphql.ts new file mode 100644 index 000000000..12a1a062b --- /dev/null +++ b/src/testing/tracker-graphql.ts @@ -0,0 +1,218 @@ +import type { ManifestOperation, SchemaNode } from "@wirecat/cli-base/codegen" +import type { ServiceApiManifest } from "../cli/service-api-manifest.js" +import type { TrackerKind } from "../domain/tracker.js" +import type { TrackerManifest } from "../tracker/manifest/manifest.js" + +export const URL = "https://api.example-tracker.test/graphql" +export const KEY = "lin_api_fake" + +const text: SchemaNode = { type: "string", nullable: true } +const ref = (name: string, nullable = true): SchemaNode => ({ + type: "ref", + ref: name, + ...(nullable ? { nullable } : {}), +}) +const object = (properties: Record): SchemaNode => ({ type: "object", properties, required: [] }) +const times = { createdAt: text, updatedAt: text, archivedAt: text } +const node = (properties: Record) => object({ id: { type: "string" }, ...times, ...properties }) +const connection = (of: string) => + object({ nodes: { type: "array", items: ref(of, false) }, pageInfo: ref("PageInfo", false) }) + +export const definitions: Record = { + PageInfo: object({ hasNextPage: { type: "boolean" }, endCursor: text }), + ListRequest: { + type: "object", + properties: { + first: { type: "integer", nullable: true }, + after: text, + includeArchived: { type: "boolean", nullable: true }, + orderBy: { type: "string", enum: ["createdAt", "updatedAt"], nullable: true }, + filter: { + type: "object", + properties: {}, + required: [], + additionalProperties: { type: "unknown" }, + nullable: true, + }, + }, + required: [], + }, + Team: node({ name: text, key: text }), + User: node({ name: text, email: text, active: { type: "boolean", nullable: true } }), + WorkflowState: node({ name: text, type: text, position: { type: "number", nullable: true }, team: ref("Team") }), + IssueLabel: node({ name: text, team: ref("Team") }), + ProjectStatus: object({ type: { type: "string", enum: ["backlog", "planned", "started", "completed"] } }), + Project: node({ + name: text, + description: text, + state: text, + status: ref("ProjectStatus", false), + lead: ref("User"), + teams: ref("TeamConnection", false), + targetDate: text, + url: text, + }), + Issue: node({ + identifier: text, + title: text, + description: text, + state: ref("WorkflowState"), + team: ref("Team"), + project: ref("Project"), + assignee: ref("User"), + creator: ref("User"), + labels: ref("IssueLabelConnection", false), + parent: ref("Issue"), + priority: { type: "number", nullable: true }, + dueDate: text, + completedAt: text, + canceledAt: text, + url: text, + }), + Comment: node({ body: text, issue: ref("Issue"), user: ref("User"), url: text }), +} +for (const name of ["Team", "User", "WorkflowState", "IssueLabel", "Project", "Issue", "Comment"]) + definitions[`${name}Connection`] = connection(name) + +export const FIELDS: Record = { + team: ["teams", "Team"], + user: ["users", "User"], + state: ["workflowStates", "WorkflowState"], + label: ["issueLabels", "IssueLabel"], + project: ["projects", "Project"], + issue: ["issues", "Issue"], + comment: ["comments", "Comment"], +} + +const listOperation = (field: string, type: string): ManifestOperation => ({ + id: field, + command: field.toLowerCase(), + binding: { + kind: "graphql", + operation: "query", + field, + variables: { + first: "Int", + after: "String", + filter: `${type}Filter`, + includeArchived: "Boolean", + orderBy: "PaginationOrderBy", + }, + selection: "nodes { id } pageInfo { hasNextPage endCursor }", + }, + effect: "read", + tags: ["query"], + parameters: ["first", "after", "filter", "includeArchived", "orderBy"].map((name) => ({ + name, + in: "body" as const, + required: false, + schema: (definitions.ListRequest as { properties: Record }).properties[name] as SchemaNode, + })), + request: { required: false, confidence: "contract", schema: "ListRequest" }, + response: { confidence: "contract", schema: `${type}Connection` }, + pagination: { + style: "cursor", + cursor: { in: "body", name: "after" }, + next: "pageInfo.endCursor", + items: "nodes", + hasMore: "pageInfo.hasNextPage", + limit: { in: "body", name: "first" }, + }, +}) + +export const api: ServiceApiManifest = { + servers: [{ url: URL }], + securitySchemes: { key: { type: "apiKey", in: "header", name: "Authorization" } }, + security: [{ key: [] }], + operations: [ + ...Object.values(FIELDS).map(([field, type]) => listOperation(field, type)), + { + id: "viewer", + command: "viewer", + binding: { kind: "graphql", operation: "query", field: "viewer", variables: {}, selection: "id" }, + effect: "read", + tags: ["query"], + parameters: [], + response: { confidence: "contract", schema: "User" }, + }, + ], +} + +export const PAGE_INFO = "pageInfo { hasNextPage endCursor }" +const TIMES = "id createdAt updatedAt archivedAt" +const SELECTIONS: Record = { + team: `nodes { ${TIMES} name key } ${PAGE_INFO}`, + user: `nodes { ${TIMES} name email active } ${PAGE_INFO}`, + state: `nodes { ${TIMES} name type position team { id } } ${PAGE_INFO}`, + label: `nodes { ${TIMES} name team { id } } ${PAGE_INFO}`, + project: `nodes { ${TIMES} name description state lead { id } teams { nodes { id } } targetDate url } ${PAGE_INFO}`, + issue: + `nodes { ${TIMES} identifier title description state { id } team { id } project { id } assignee { id } ` + + `creator { id } labels { nodes { id } } parent { id } priority dueDate completedAt canceledAt url } ${PAGE_INFO}`, + comment: `nodes { ${TIMES} body issue { id } user { id } url } ${PAGE_INFO}`, +} +const TIME_MAP = { externalId: "id", createdAt: "createdAt", updatedAt: "updatedAt", archivedAt: "archivedAt" } +// A literal after `key:` reads as a permission key to src/cli/permission-keys.test.ts. +const TEAM_KEY = "key" +const ISSUE_KEY = "identifier" +const MAPS: { [K in TrackerKind]: Record } = { + team: { ...TIME_MAP, name: "name", key: TEAM_KEY }, + user: { ...TIME_MAP, name: "name", email: "email", active: "active" }, + state: { ...TIME_MAP, name: "name", type: "type", position: "position", team: "team.id" }, + label: { ...TIME_MAP, name: "name", team: "team.id" }, + project: { + ...TIME_MAP, + name: "name", + description: "description", + status: "state", + lead: "lead.id", + teams: { each: "teams.nodes", value: "id" }, + targetDate: "targetDate", + url: "url", + }, + issue: { + ...TIME_MAP, + key: ISSUE_KEY, + title: "title", + description: "description", + state: "state.id", + team: "team.id", + project: "project.id", + assignee: "assignee.id", + creator: "creator.id", + labels: { each: "labels.nodes", id: "id" }, + parent: "parent.id", + priority: "priority", + dueDate: "dueDate", + completedAt: "completedAt", + canceledAt: "canceledAt", + url: "url", + }, + comment: { ...TIME_MAP, body: "body", issue: "issue.id", author: "user.id", url: "url" }, +} + +export const ALL = { first: 50, includeArchived: true } +export const MANIFEST = { + provider: "example-tracker", + kinds: ["team", "user", "state", "label", "project", "issue", "comment"], + entities: Object.fromEntries( + (Object.keys(FIELDS) as TrackerKind[]).map((kind) => { + const [operation] = FIELDS[kind] + return [ + kind, + { + list: { operation, variables: ALL, selection: SELECTIONS[kind] }, + changes: { + operation, + variables: { ...ALL, orderBy: "updatedAt", filter: { updatedAt: { gte: "{since}" } } }, + selection: SELECTIONS[kind], + since: "iso", + }, + ids: { operation, variables: ALL, selection: `nodes { id } ${PAGE_INFO}` }, + map: MAPS[kind], + }, + ] + }), + ), + self: { call: { operation: "viewer" }, path: "id" }, +} as unknown as TrackerManifest diff --git a/src/tracker/manifest/manifest.ts b/src/tracker/manifest/manifest.ts index 950969f2f..b2a29ca5c 100644 --- a/src/tracker/manifest/manifest.ts +++ b/src/tracker/manifest/manifest.ts @@ -132,7 +132,7 @@ const selects = (tree: Selection, steps: readonly string[]): boolean => { } /** The selection of one row: under the operation's `items` (a connection's `nodes`) or the call's own. */ -const rowSelection = (tree: Selection, items: string | undefined): Selection | undefined => { +export const rowSelection = (tree: Selection, items: string | undefined): Selection | undefined => { let inside: Selection | true | undefined = tree for (const step of items?.split(".") ?? []) inside = inside === true ? undefined : inside?.[step] return inside === true ? undefined : inside diff --git a/src/tracker/manifest/source.test.ts b/src/tracker/manifest/source.test.ts index e1dbd3849..d1f978a0c 100644 --- a/src/tracker/manifest/source.test.ts +++ b/src/tracker/manifest/source.test.ts @@ -1,221 +1,13 @@ -import { - type GraphqlFakeCall, - graphqlFake, - type ManifestOperation, - type SchemaNode, - type Selection, -} from "@wirecat/cli-base/codegen" +import { type GraphqlFakeCall, graphqlFake, type Selection } from "@wirecat/cli-base/codegen" import { describe, expect, it } from "vitest" import { serviceApiCall } from "../../cli/service-api-call.js" -import type { ServiceApiManifest } from "../../cli/service-api-manifest.js" import type { TrackerKind } from "../../domain/tracker.js" +import { ALL, api, definitions, FIELDS, KEY, MANIFEST, PAGE_INFO, URL } from "../../testing/tracker-graphql.js" import { trackerSourceContract } from "../testing/index.js" import type { TrackerManifest } from "./manifest.js" import { parseTrackerManifest } from "./manifest.js" import { trackerSourceFromManifest } from "./source.js" -const URL = "https://api.example-tracker.test/graphql" -const KEY = "lin_api_fake" - -const text: SchemaNode = { type: "string", nullable: true } -const ref = (name: string, nullable = true): SchemaNode => ({ - type: "ref", - ref: name, - ...(nullable ? { nullable } : {}), -}) -const object = (properties: Record): SchemaNode => ({ type: "object", properties, required: [] }) -const times = { createdAt: text, updatedAt: text, archivedAt: text } -const node = (properties: Record) => object({ id: { type: "string" }, ...times, ...properties }) -const connection = (of: string) => - object({ nodes: { type: "array", items: ref(of, false) }, pageInfo: ref("PageInfo", false) }) - -const definitions: Record = { - PageInfo: object({ hasNextPage: { type: "boolean" }, endCursor: text }), - ListRequest: { - type: "object", - properties: { - first: { type: "integer", nullable: true }, - after: text, - includeArchived: { type: "boolean", nullable: true }, - filter: { - type: "object", - properties: {}, - required: [], - additionalProperties: { type: "unknown" }, - nullable: true, - }, - }, - required: [], - }, - Team: node({ name: text, key: text }), - User: node({ name: text, email: text, active: { type: "boolean", nullable: true } }), - WorkflowState: node({ name: text, type: text, position: { type: "number", nullable: true }, team: ref("Team") }), - IssueLabel: node({ name: text, team: ref("Team") }), - Project: node({ - name: text, - description: text, - state: text, - lead: ref("User"), - teams: ref("TeamConnection", false), - targetDate: text, - url: text, - }), - Issue: node({ - identifier: text, - title: text, - description: text, - state: ref("WorkflowState"), - team: ref("Team"), - project: ref("Project"), - assignee: ref("User"), - creator: ref("User"), - labels: ref("IssueLabelConnection", false), - parent: ref("Issue"), - priority: { type: "number", nullable: true }, - dueDate: text, - completedAt: text, - canceledAt: text, - url: text, - }), - Comment: node({ body: text, issue: ref("Issue"), user: ref("User"), url: text }), -} -for (const name of ["Team", "User", "WorkflowState", "IssueLabel", "Project", "Issue", "Comment"]) - definitions[`${name}Connection`] = connection(name) - -const FIELDS: Record = { - team: ["teams", "Team"], - user: ["users", "User"], - state: ["workflowStates", "WorkflowState"], - label: ["issueLabels", "IssueLabel"], - project: ["projects", "Project"], - issue: ["issues", "Issue"], - comment: ["comments", "Comment"], -} - -const listOperation = (field: string, type: string): ManifestOperation => ({ - id: field, - command: field.toLowerCase(), - binding: { - kind: "graphql", - operation: "query", - field, - variables: { first: "Int", after: "String", filter: `${type}Filter`, includeArchived: "Boolean" }, - selection: "nodes { id } pageInfo { hasNextPage endCursor }", - }, - effect: "read", - tags: ["query"], - parameters: ["first", "after", "filter", "includeArchived"].map((name) => ({ - name, - in: "body" as const, - required: false, - schema: (definitions.ListRequest as { properties: Record }).properties[name] as SchemaNode, - })), - request: { required: false, confidence: "contract", schema: "ListRequest" }, - response: { confidence: "contract", schema: `${type}Connection` }, - pagination: { - style: "cursor", - cursor: { in: "body", name: "after" }, - next: "pageInfo.endCursor", - items: "nodes", - hasMore: "pageInfo.hasNextPage", - limit: { in: "body", name: "first" }, - }, -}) - -const api: ServiceApiManifest = { - servers: [{ url: URL }], - securitySchemes: { key: { type: "apiKey", in: "header", name: "Authorization" } }, - security: [{ key: [] }], - operations: [ - ...Object.values(FIELDS).map(([field, type]) => listOperation(field, type)), - { - id: "viewer", - command: "viewer", - binding: { kind: "graphql", operation: "query", field: "viewer", variables: {}, selection: "id" }, - effect: "read", - tags: ["query"], - parameters: [], - response: { confidence: "contract", schema: "User" }, - }, - ], -} - -const PAGE_INFO = "pageInfo { hasNextPage endCursor }" -const TIMES = "id createdAt updatedAt archivedAt" -const SELECTIONS: Record = { - team: `nodes { ${TIMES} name key } ${PAGE_INFO}`, - user: `nodes { ${TIMES} name email active } ${PAGE_INFO}`, - state: `nodes { ${TIMES} name type position team { id } } ${PAGE_INFO}`, - label: `nodes { ${TIMES} name team { id } } ${PAGE_INFO}`, - project: `nodes { ${TIMES} name description state lead { id } teams { nodes { id } } targetDate url } ${PAGE_INFO}`, - issue: - `nodes { ${TIMES} identifier title description state { id } team { id } project { id } assignee { id } ` + - `creator { id } labels { nodes { id } } parent { id } priority dueDate completedAt canceledAt url } ${PAGE_INFO}`, - comment: `nodes { ${TIMES} body issue { id } user { id } url } ${PAGE_INFO}`, -} -const TIME_MAP = { externalId: "id", createdAt: "createdAt", updatedAt: "updatedAt", archivedAt: "archivedAt" } -const MAPS: { [K in TrackerKind]: Record } = { - team: { ...TIME_MAP, name: "name", key: "key" }, - user: { ...TIME_MAP, name: "name", email: "email", active: "active" }, - state: { ...TIME_MAP, name: "name", type: "type", position: "position", team: "team.id" }, - label: { ...TIME_MAP, name: "name", team: "team.id" }, - project: { - ...TIME_MAP, - name: "name", - description: "description", - status: "state", - lead: "lead.id", - teams: { each: "teams.nodes", value: "id" }, - targetDate: "targetDate", - url: "url", - }, - issue: { - ...TIME_MAP, - key: "identifier", - title: "title", - description: "description", - state: "state.id", - team: "team.id", - project: "project.id", - assignee: "assignee.id", - creator: "creator.id", - labels: { each: "labels.nodes", value: "id" }, - parent: "parent.id", - priority: "priority", - dueDate: "dueDate", - completedAt: "completedAt", - canceledAt: "canceledAt", - url: "url", - }, - comment: { ...TIME_MAP, body: "body", issue: "issue.id", author: "user.id", url: "url" }, -} - -const ALL = { first: 50, includeArchived: true } -const MANIFEST = { - provider: "example-tracker", - kinds: ["team", "user", "state", "label", "project", "issue", "comment"], - entities: Object.fromEntries( - (Object.keys(FIELDS) as TrackerKind[]).map((kind) => { - const [operation] = FIELDS[kind] - return [ - kind, - { - list: { operation, variables: ALL, selection: SELECTIONS[kind] }, - changes: { - operation, - variables: { ...ALL, filter: { updatedAt: { gte: "{since}" } } }, - selection: SELECTIONS[kind], - since: "iso", - }, - ids: { operation, variables: ALL, selection: `nodes { id } ${PAGE_INFO}` }, - map: MAPS[kind], - }, - ] - }), - ), - self: { call: { operation: "viewer" }, path: "id" }, -} as unknown as TrackerManifest - type Row = Record const project = (value: unknown, selection: Selection | true): unknown => { diff --git a/src/tracker/testing/index.ts b/src/tracker/testing/index.ts index c53f0c5da..c4285438f 100644 --- a/src/tracker/testing/index.ts +++ b/src/tracker/testing/index.ts @@ -1,3 +1,11 @@ +export { + type TrackerManifestFake, + type TrackerManifestFakeOptions, + type TrackerManifestFixtureOptions, + trackerManifestContract, + trackerManifestFake, + trackerManifestFixture, +} from "./manifest-fake.js" export { exampleTrackerRows, type FakeTrackerRows, diff --git a/src/tracker/testing/manifest-fake.test.ts b/src/tracker/testing/manifest-fake.test.ts new file mode 100644 index 000000000..c7d66e678 --- /dev/null +++ b/src/tracker/testing/manifest-fake.test.ts @@ -0,0 +1,205 @@ +import { describe, expect, it } from "vitest" +import { serviceApiCall } from "../../cli/service-api-call.js" +import { FAKE_MANIFEST_TOKEN } from "../../crm/testing/index.js" +import { ALL, api, definitions, MANIFEST, PAGE_INFO } from "../../testing/tracker-graphql.js" +import type { TrackerManifest } from "../manifest/manifest.js" +import { trackerManifestContract, trackerManifestFake, trackerManifestFixture } from "./manifest-fake.js" + +type Row = Record + +const fakeOf = (manifest: TrackerManifest = MANIFEST) => { + const fake = trackerManifestFake(manifest, { api, definitions }) + const call = serviceApiCall({ + manifest: api, + service: "Tracker", + fetch: fake.fetch, + token: () => FAKE_MANIFEST_TOKEN, + }) + const read = async (variables: Row, selection = `nodes { id updatedAt archivedAt } ${PAGE_INFO}`) => + (await call("issues", { + path: {}, + query: {}, + headers: {}, + fields: {}, + body: JSON.stringify(variables), + selection, + })) as { + nodes: Row[] + pageInfo: { hasNextPage: boolean; endCursor: string | null } + } + return { fake, read } +} + +const issue = MANIFEST.entities.issue as NonNullable +const withIssue = (change: Partial) => + ({ ...MANIFEST, entities: { ...MANIFEST.entities, issue: { ...issue, ...change } } }) as TrackerManifest + +const ids = (page: { nodes: Row[] }) => page.nodes.map((one) => one.id) + +describe("trackerManifestContract over a Linear-shaped GraphQL schema", () => { + for (const { name, run } of trackerManifestContract(MANIFEST, { api, definitions })) it(name, run) +}) + +describe("trackerManifestFake", () => { + it("writes each row where the map reads it, pointing at the first row of the kind a field names", async () => { + const { fake, read } = fakeOf() + expect(fake.rows.issue?.[1]).toMatchObject({ + id: "issue-2", + title: "title 2", + state: { id: "state-1" }, + team: { id: "team-1" }, + assignee: { id: "user-1" }, + labels: { nodes: [{ id: "label-1" }] }, + archivedAt: null, + updatedAt: "2026-11-01T10:01:00.000Z", + }) + expect(fake.rows.state?.map((row) => row.type)).toEqual(["triage", "backlog", "unstarted"]) + expect((await read(ALL, `nodes { id state { id } } ${PAGE_INFO}`)).nodes[0]).toEqual({ + id: "issue-1", + state: { id: "state-1" }, + }) + }) + + it("pages two at a time by the cursor it gave, and refuses one it did not give", async () => { + const { fake, read } = fakeOf() + const first = await read({ first: 50, includeArchived: true }) + expect(ids(first)).toEqual(["issue-1", "issue-2"]) + expect(first.pageInfo).toEqual({ hasNextPage: true, endCursor: "fake-page-2" }) + const second = await read({ first: 50, includeArchived: true, after: first.pageInfo.endCursor }) + expect(ids(second)).toEqual(["issue-3"]) + expect(second.pageInfo).toEqual({ hasNextPage: false, endCursor: null }) + expect(fake.refusals).toEqual([]) + await expect(read({ first: 50, includeArchived: true, after: "o:2" })).rejects.toThrow() + expect(fake.refusals).toEqual(["issues: o:2 is not a cursor this fake gave"]) + }) + + it("hides an archived row unless the call asks for archived rows", async () => { + const { fake, read } = fakeOf(withIssue({ ids: { ...issue.ids, variables: { first: 50 } } as typeof issue.ids })) + fake.archive("issue", "issue-1") + const shown = await read(ALL) + expect(ids(shown)).toContain("issue-1") + expect(typeof shown.nodes.find((one) => one.id === "issue-1")?.archivedAt).toBe("string") + const hidden = await read({ first: 50 }) + expect(ids(hidden)).toEqual(["issue-2", "issue-3"]) + expect(hidden.pageInfo.hasNextPage).toBe(false) + }) + + it("keeps a change read to the rows changed at or after its since, oldest first", async () => { + const { fake, read } = fakeOf() + fake.touch("issue", "issue-1") + const changes = { ...ALL, orderBy: "updatedAt" } + const since = { ...changes, filter: { updatedAt: { gte: "2026-11-01T10:00:30Z" } } } + const first = await read(since) + expect([...ids(first), ...ids(await read({ ...since, after: first.pageInfo.endCursor }))]).toEqual([ + "issue-2", + "issue-3", + "issue-1", + ]) + await expect(read({ ...changes, filter: { updatedAt: { gte: "yesterday" } } })).rejects.toThrow() + expect(fake.refusals).toEqual(["issues: since yesterday is unreadable"]) + }) + + it("refuses what the API would, and a call the manifest never makes", async () => { + const { fake, read } = fakeOf() + await expect(read({ first: 5, includeArchived: true }, `nodes { id estimate } ${PAGE_INFO}`)).rejects.toThrow() + await expect(read({ first: 5 })).rejects.toThrow() + expect(fake.refusals).toEqual([ + "issues.nodes.estimate: no such field", + "issues: no call of the source manifest sends these variables", + ]) + }) + + it("writes a text field the schema keeps as an enum as one of its values", async () => { + const project = MANIFEST.entities.project as NonNullable + const selection = project.list.selection?.replace(" state ", " status { type } ") + const manifest = { + ...MANIFEST, + kinds: ["project"], + entities: { + project: { + ...project, + list: { ...project.list, selection }, + changes: { ...project.changes, selection }, + map: { ...project.map, status: "status.type" }, + }, + }, + } as unknown + const { fake, source } = trackerManifestFixture(manifest, { api, definitions }) + expect(fake.rows.project?.[0]?.status).toEqual({ type: "backlog" }) + const listed = await source.changes("project", null) + expect("items" in listed && listed.items[0]?.status).toBe("backlog") + expect(fake.refusals).toEqual([]) + }) + + it("fails to build for a kind with changes whose change time the map does not read", () => { + const { updatedAt: _, ...map } = (MANIFEST.entities.issue as { map: Row }).map + const manifest = { ...MANIFEST, entities: { ...MANIFEST.entities, issue: { ...MANIFEST.entities.issue, map } } } + expect(() => trackerManifestFake(manifest as TrackerManifest, { api, definitions })).toThrow(/map updatedAt/) + }) +}) + +describe("a source the contract catches over the fake", () => { + const failing = async (manifest: TrackerManifest, name: RegExp, message: RegExp) => { + const found = trackerManifestContract(manifest, { api, definitions }).find((one) => name.test(one.name)) + expect(found).toBeDefined() + await expect(found?.run()).rejects.toThrow(message) + } + const changes = issue.changes as NonNullable + const since = (filter: Row) => withIssue({ changes: { ...changes, variables: { ...ALL, filter } } }) + + it("an id pass that leaves archived rows out", async () => { + await failing( + withIssue({ ids: { ...issue.ids, variables: { first: 50 } } as typeof issue.ids }), + /archived/, + /issue issue-3: an archived row is still in ids\(\)/, + ) + }) + + it("a change read with no overlap, which loses a change when the clock runs ahead", async () => { + await failing( + { ...MANIFEST, overlapMs: 0 }, + /clock off/, + /issue issue-1 is in the changes with the clock 10 min off/, + ) + }) + + it("a change read whose since is on another time, or reads before it", async () => { + await failing( + since({ createdAt: { gte: "{since}" } }), + /clock off/, + /the fake refused calls the source made:\nissues: \{since\} at filter\.createdAt\.gte is not updatedAt\.gte/, + ) + await failing( + since({ updatedAt: { lt: "{since}" } }), + /clock off/, + /the fake refused calls the source made:\nissues: \{since\} at filter\.updatedAt\.lt is not updatedAt\.gte/, + ) + }) + + it("an id pass or a change read that filters rows out", async () => { + const ids = { ...issue.ids, variables: { ...ALL, filter: { state: { type: { neq: "canceled" } } } } } + await failing( + withIssue({ ids: ids as typeof issue.ids }), + /^ids:/, + /issues: a list or id read with a filter leaves rows out, and sync would mark them deleted/, + ) + await failing( + since({ updatedAt: { gte: "{since}" }, state: { type: { neq: "canceled" } } }), + /clock off/, + /issues: the fake cannot apply filter\.state\.type\.neq, so it would list rows the tracker drops/, + ) + }) + + it("a strict since leaves out a row changed at that very time", async () => { + const { fake, read } = fakeOf(since({ updatedAt: { gt: "{since}" } })) + const at = "2026-11-01T10:01:00.000Z" + expect(ids(await read({ ...ALL, filter: { updatedAt: { gt: at } } }))).toEqual(["issue-3"]) + expect(fake.refusals).toEqual([]) + }) + + it("a fixture over the fake offers every fault the manifest allows", () => { + const { faults, held } = trackerManifestFixture(MANIFEST, { api, definitions }) + expect(Object.keys(faults ?? {}).sort()).toEqual(["archive", "change", "remove", "skewed"]) + expect(held?.comment).toEqual(["comment-1", "comment-2", "comment-3"]) + }) +}) diff --git a/src/tracker/testing/manifest-fake.ts b/src/tracker/testing/manifest-fake.ts new file mode 100644 index 000000000..f10a6b18b --- /dev/null +++ b/src/tracker/testing/manifest-fake.ts @@ -0,0 +1,545 @@ +import { + type GraphqlFake, + type GraphqlFakeAnswer, + type GraphqlFakeCall, + graphqlFake, + type SchemaNode, + type Selection, + sampleOf, +} from "@wirecat/cli-base/codegen" +import { serviceApiCall } from "../../cli/service-api-call.js" +import { manifestBaseUrl, type ServiceApiManifest } from "../../cli/service-api-manifest.js" +import { crmValues } from "../../crm/index.js" +import type { CrmRule } from "../../crm/manifest/manifest.js" +import { at, evaluate, MISSING, rulePaths } from "../../crm/manifest/map.js" +import { resolve, step } from "../../crm/manifest/paths.js" +import { FAKE_MANIFEST_TOKEN } from "../../crm/testing/index.js" +import { STATE_TYPES, type TrackerKind } from "../../domain/tracker.js" +import type { ContractCase } from "../../meetings/index.js" +import { + parseTrackerManifest, + rowSelection, + selectionOf, + type TrackerChangesCall, + type TrackerManifest, + type TrackerManifestHooks, + type TrackerOperationCall, +} from "../manifest/manifest.js" +import { TRACKER_FIELDS } from "../manifest/map.js" +import { trackerSourceFromManifest } from "../manifest/source.js" +import type { TrackerSource } from "../source.js" +import { type TrackerSourceFixture, trackerSourceContract } from "./source-contract.js" + +type Definitions = Readonly> + +export interface TrackerManifestFakeOptions { + /** The generated API manifest the source manifest names its operations in. */ + api: ServiceApiManifest + /** The generated schemas: rows are sampled from them, and every call and answer is checked against them. */ + definitions: Definitions + /** In place of the API manifest's first server. */ + baseUrl?: string +} + +export interface TrackerManifestFake extends GraphqlFake { + /** The rows of each kind as the tracker holds them, every field any call of the kind selects; a test may change them. */ + rows: Partial> + /** Moves one row's change time to now, for the next read of changes to list it. */ + touch(kind: TrackerKind, id: string): void + /** Archives one row now: listed only to a call that asks for archived rows, and read as changed. */ + archive(kind: TrackerKind, id: string): void + /** Deletes one row outright. */ + remove(kind: TrackerKind, id: string): void +} + +/** Three rows in pages of two: every kind pages at least once, whatever `first` the manifest asks for. */ +const ROWS = 3 +const PAGE = 2 +const SEEDED = Date.parse("2026-11-01T10:00:00Z") +/** Linear's argument; a call to an operation that takes it and leaves it unset sees no archived row. */ +const ARCHIVED = "includeArchived" +const CURSOR = /^fake-page-(\d+)$/ + +/** The kind an id field points at: an issue's assignee is a user, its labels are labels. */ +const TARGETS: Readonly> = { + team: "team", + teams: "team", + state: "state", + label: "label", + labels: "label", + project: "project", + lead: "user", + assignee: "user", + creator: "user", + author: "user", + issue: "issue", + parent: "issue", +} + +const SINCE: Record number> = { + iso: (value) => Date.parse(value), + ms: (value) => (/^\d+$/.test(value) ? Number(value) : Number.NaN), + seconds: (value) => (/^\d+$/.test(value) ? Number(value) * 1000 : Number.NaN), +} + +type Value = string | number | boolean | null | { ms: number } + +const idOf = (kind: TrackerKind, n: number) => `${kind}-${n + 1}` + +const merge = (a: Selection, b: Selection): Selection => + Object.fromEntries( + [...new Set([...Object.keys(a), ...Object.keys(b)])].map((key) => { + const [x, y] = [a[key], b[key]] + if (x === undefined || x === true) return [key, y ?? x ?? true] + return [key, y === undefined || y === true ? x : merge(x, y)] + }), + ) + +const project = (value: unknown, selection: Selection | true): unknown => { + if (selection === true || value === null || value === undefined) return value ?? null + if (Array.isArray(value)) return value.map((one) => project(one, selection)) + return Object.fromEntries( + Object.entries(selection).map(([field, inner]) => [field, project((value as crmValues.CrmRaw)[field], inner)]), + ) +} + +const fixedOf = (value: unknown, trail: readonly string[] = []): [string, unknown][] => + crmValues.isRaw(value) + ? Object.entries(value).flatMap(([key, inner]) => fixedOf(inner, [...trail, key])) + : /^\{\w+\}$/.test(String(value)) + ? [] + : [[trail.join("."), value]] + +const placeOf = (value: unknown, placeholder: string, trail: readonly string[] = []): string | undefined => { + if (value === placeholder) return trail.join(".") + if (!crmValues.isRaw(value)) return undefined + for (const [key, inner] of Object.entries(value)) { + const found = placeOf(inner, placeholder, [...trail, key]) + if (found !== undefined) return found + } + return undefined +} + +const put = (row: crmValues.CrmRaw, path: string, value: unknown) => { + const keys = path.split(".") + const last = keys.pop() as string + let here = row + for (const key of keys) { + if (!crmValues.isRaw(here[key])) here[key] = {} + here = here[key] as crmValues.CrmRaw + } + here[last] = value +} + +interface Route { + kind: TrackerKind + call: TrackerOperationCall + since?: { place: string; format: TrackerChangesCall["since"]; after: boolean } + /** Why the fake cannot answer this call as the tracker would; each call by it is refused with this. */ + problem?: string +} + +/** The only filter the fake applies: a since on the change time. Any other would pass rows the tracker drops. */ +const FILTER = "filter" + +/** + * A GraphQL tracker in memory, built from a source manifest and the generated API it names: cli-base's strict + * `graphqlFake` with three rows of each kind behind it. Each row holds the values the map reads where it reads them, + * links to rows of the kinds it points at, and is answered within each call's selection, Relay-paged two a page. A + * change read keeps the rows changed at or after its since, oldest first. A cursor the fake never gave, an unreadable + * since and a call no route of the manifest makes are refused and recorded. + */ +export const trackerManifestFake = (input: unknown, options: TrackerManifestFakeOptions): TrackerManifestFake => { + const { api, definitions } = options + const manifest = parseTrackerManifest(input, api) + const operations = new Map(api.operations.map((one) => [one.id, one])) + const own: string[] = [] + + const operationOf = (call: TrackerOperationCall) => { + const found = operations.get(call.operation) + if (found?.binding.kind !== "graphql") + throw new Error(`${call.operation}: the tracker fake answers GraphQL operations only`) + return found + } + const itemsOf = (call: TrackerOperationCall) => call.items ?? operationOf(call).pagination?.items + const responseOf = (call: TrackerOperationCall): SchemaNode => { + const schema = operationOf(call).response?.schema + return schema === undefined ? { type: "unknown" } : { type: "ref", ref: schema } + } + const nodeAt = (node: SchemaNode | undefined, path: string | undefined) => + (path?.split(".") ?? []).reduce((inner, key) => { + const found = inner && step(inner, key, definitions) + const resolved = found ? resolve(found, definitions) : undefined + return resolved?.type === "array" ? resolved.items : (found ?? undefined) + }, node) + + const sampled = (node: SchemaNode, selection: Selection | true): unknown => { + if (selection === true) return sampleOf(node, definitions) + const found = resolve(node, definitions) + if (found.type === "array") return [sampled(found.items, selection)] + return Object.fromEntries( + Object.entries(selection).map(([name, inner]) => [ + name, + sampled(step(found, name, definitions) ?? { type: "unknown" }, inner), + ]), + ) + } + + /** A value as the schema at its place takes it: a time as ISO text or epoch ms; `undefined` when it cannot. */ + const typed = (node: SchemaNode | undefined, value: Value): unknown => { + const found = node && resolve(node, definitions) + if (value === null) return found === undefined || node?.nullable || found.nullable ? null : undefined + // A text the schema keeps as an enum (Linear's project status type) is one of its values. + if (typeof value === "string" && found?.type === "string" && found.enum && !found.enum.includes(value)) + return found.enum[0] + if (typeof value !== "object") return value + return found?.type === "integer" || found?.type === "number" ? value.ms : new Date(value.ms).toISOString() + } + + const write = (row: crmValues.CrmRaw, item: SchemaNode | undefined, path: string, value: Value) => { + const written = typed(nodeAt(item, path), value) + if (written !== undefined) put(row, path, written) + } + + const pointed = (field: string) => { + const target = TARGETS[field] + return target && manifest.kinds.includes(target) ? idOf(target, 0) : `${field}-1` + } + + const sampleValue = (kind: TrackerKind, field: string, n: number): Value => { + const type = TRACKER_FIELDS[kind][field] + if (field === "externalId") return idOf(kind, n) + // A state of a type outside STATE_TYPES is dropped by the map, and its issues with it. + if (kind === "state" && field === "type") return STATE_TYPES[n % STATE_TYPES.length] as string + switch (type) { + case "epoch": + return field === "createdAt" || field === "updatedAt" ? { ms: SEEDED + n * 60_000 } : null + case "id": + return pointed(field) + case "number": + return n + 1 + case "bool": + return true + case "day": + return `2026-11-0${n + 1}` + default: + return `${field} ${n + 1}` + } + } + + const timePath = (kind: TrackerKind, field: "updatedAt" | "archivedAt") => { + const rule: CrmRule | undefined = manifest.entities[kind]?.map[field] + return typeof rule === "string" ? rule : typeof rule === "object" && "path" in rule ? rule.path : undefined + } + + const items = new Map() + const rows: Partial> = {} + for (const kind of manifest.kinds) { + const entity = manifest.entities[kind] as NonNullable + const calls = [entity.list, entity.changes, entity.ids].filter((one) => one !== undefined) + const selection = calls + .map((call) => rowSelection(selectionOf(call, api) ?? {}, itemsOf(call)) ?? {}) + .reduce((all, one) => merge(all, one), {}) + const item = nodeAt(responseOf(entity.list), itemsOf(entity.list)) + items.set(kind, item) + if (entity.changes && timePath(kind, "updatedAt") === undefined) + throw new Error(`${kind}: map updatedAt to a path, so the fake can read a change time`) + rows[kind] = Array.from({ length: ROWS }, (_, n) => { + const made = item ? sampled(item, selection) : {} + const row = crmValues.isRaw(made) ? made : {} + for (const [field, rule] of Object.entries(entity.map as Record)) { + if (typeof rule === "function" || (typeof rule === "object" && "value" in rule && !("each" in rule))) continue + const [first, inside] = rulePaths(rule) + if (!first) continue + if (inside?.inside !== undefined) { + const one: crmValues.CrmRaw = {} + put(one, inside.path, pointed(field)) + put(row, first.path, [one]) + } else if (typeof rule === "object" && "map" in rule) put(row, first.path, Object.keys(rule.map)[0] ?? null) + else write(row, item, first.path, sampleValue(kind, field, n)) + } + return row + }) + } + + const filterProblem = (kind: TrackerKind, call: TrackerOperationCall, place?: string) => { + const filter = fixedOf(call.variables?.[FILTER] ?? {}) + if (filter.length > 0) + return `${call.operation}: the fake cannot apply ${FILTER}.${filter[0]?.[0]}, so it would list rows the tracker drops` + if (place === undefined) return undefined + const time = timePath(kind, "updatedAt") + const ends = [`${time}.gte`, `${time}.gt`] + if (!ends.some((end) => place === end || place.endsWith(`.${end}`))) + return `${call.operation}: {since} at ${place} is not ${time}.gte or ${time}.gt, the change time the map reads` + return undefined + } + const routes: Route[] = manifest.kinds.flatMap((kind) => { + const entity = manifest.entities[kind] as NonNullable + const plain = (call: TrackerOperationCall): Route => { + const problem = + call.variables && FILTER in call.variables + ? `${call.operation}: a list or id read with a ${FILTER} leaves rows out, and sync would mark them deleted` + : undefined + return { kind, call, ...(problem ? { problem } : {}) } + } + const changes = entity.changes + const place = changes && (placeOf(changes.variables, "{since}") as string) + const problem = changes && filterProblem(kind, changes, place) + return [ + plain(entity.list), + ...(entity.ids ? [plain(entity.ids)] : []), + ...(changes && place + ? [ + { + kind, + call: changes, + since: { place, format: changes.since, after: place.endsWith(".gt") }, + ...(problem ? { problem } : {}), + }, + ] + : []), + ] + }) + + /** A page's size and place are the engine's to set, whatever the template says. */ + const paging = (operation: string, key: string) => { + const pagination = operations.get(operation)?.pagination + return pagination?.style === "cursor" && [pagination.cursor.name, pagination.limit?.name].includes(key) + } + const fixed = (route: Route) => + fixedOf(route.call.variables ?? {}).filter(([key]) => !paging(route.call.operation, key)) + const matches = (route: Route, call: GraphqlFakeCall) => + route.call.operation === call.operation && + fixed(route).every(([key, value]) => JSON.stringify(at(call.variables, key)) === JSON.stringify(value)) && + (!route.since || at(call.variables, route.since.place) !== undefined) + /** A change read wins over a list when its since was sent; else the route that fixes the most values. */ + const routeOf = (call: GraphqlFakeCall) => + routes + .filter((route) => matches(route, call)) + .sort((a, b) => Number(!!b.since) - Number(!!a.since) || fixed(b).length - fixed(a).length)[0] + + const find = (kind: TrackerKind, id: string) => { + const found = rows[kind]?.find((row) => externalIdOf(manifest, kind, row) === id) + if (!found) throw new Error(`the fake holds no ${kind} ${id}`) + return found + } + const timeOf = (kind: TrackerKind, row: crmValues.CrmRaw, field: "updatedAt" | "archivedAt") => { + const path = timePath(kind, field) + const value = path === undefined ? null : at(row, path) + return typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : null + } + const stamp = (kind: TrackerKind, row: crmValues.CrmRaw, field: "updatedAt" | "archivedAt") => { + const path = timePath(kind, field) + if (path === undefined) throw new Error(`${kind}: map ${field} to a path, so the fake can write it`) + write(row, items.get(kind), path, { ms: Date.now() }) + } + + const refuse = (message: string): GraphqlFakeAnswer => { + own.push(message) + return { status: 400, errors: [{ message, extensions: { code: "FAKE_REFUSED" } }] } + } + + const answer = (call: GraphqlFakeCall): GraphqlFakeAnswer => { + const route = routeOf(call) + if (!route) return refuse(`${call.operation}: no call of the source manifest sends these variables`) + if (route.problem) return refuse(route.problem) + const { kind } = route + const operation = operationOf(route.call) + const hidesArchived = operation.binding.kind === "graphql" && ARCHIVED in operation.binding.variables + let listed = (rows[kind] ?? []).filter( + (row) => + !hidesArchived || call.variables[ARCHIVED] === true || !Number.isFinite(timeOf(kind, row, "archivedAt") ?? NaN), + ) + if (route.since) { + const sent = String(at(call.variables, route.since.place)) + const from = SINCE[route.since.format](sent) + if (!Number.isFinite(from)) return refuse(`${call.operation}: since ${sent} is unreadable`) + listed = listed + .filter((row) => { + const time = timeOf(kind, row, "updatedAt") ?? Number.NEGATIVE_INFINITY + return route.since?.after ? time > from : time >= from + }) + .sort((a, b) => (timeOf(kind, a, "updatedAt") ?? 0) - (timeOf(kind, b, "updatedAt") ?? 0)) + } + const selection = call.selection ?? {} + const where = itemsOf(route.call) + const inner = rowSelection(selection, where) ?? true + const pagination = operation.pagination + if (where === undefined) return { data: listed.map((row) => project(row, inner)) } + const made = sampled(responseOf(route.call), selection) + const body = crmValues.isRaw(made) ? made : {} + if (pagination && pagination.style !== "cursor") + throw new Error(`${call.operation}: the tracker fake pages by a cursor only, not by ${pagination.style}`) + if (!pagination) { + put( + body, + where, + listed.map((row) => project(row, inner)), + ) + return { data: project(body, selection) } + } + const sent = call.variables[pagination.cursor.name] + const offset = sent === undefined || sent === null ? 0 : Number(CURSOR.exec(String(sent))?.[1] ?? Number.NaN) + if (!Number.isSafeInteger(offset)) + return refuse(`${call.operation}: ${String(sent)} is not a cursor this fake gave`) + const limit = pagination.limit ? Number(call.variables[pagination.limit.name]) : Number.NaN + const size = Number.isSafeInteger(limit) && limit > 0 ? Math.min(limit, PAGE) : PAGE + const more = offset + size < listed.length + put( + body, + where, + listed.slice(offset, offset + size).map((row) => project(row, inner)), + ) + put(body, pagination.next, more ? `fake-page-${offset + size}` : null) + if (pagination.hasMore) put(body, pagination.hasMore, more) + return { data: project(body, selection) } + } + + const scheme = Object.values(api.securitySchemes ?? {})[0] as + | { type?: string; in?: string; name?: string } + | undefined + const fake = graphqlFake({ + operations: api.operations, + definitions, + url: options.baseUrl ?? manifestBaseUrl(api), + ...(scheme + ? { + auth: + scheme.type === "apiKey" && scheme.in === "header" && scheme.name + ? { header: scheme.name, value: FAKE_MANIFEST_TOKEN } + : { header: "Authorization", value: `Bearer ${FAKE_MANIFEST_TOKEN}` }, + } + : {}), + answers: Object.fromEntries(routes.map((route) => [route.call.operation, answer])), + }) + + return { + // An answer of the fake's own that breaks the schema throws inside fetch, which the source reports as a network + // error; the refusal names it. + fetch: (input, init) => + fake.fetch(input, init).catch((error: unknown) => { + own.push(error instanceof Error ? error.message : String(error)) + throw error + }), + calls: fake.calls, + get refusals() { + return [...fake.refusals, ...own] + }, + rows, + touch: (kind, id) => stamp(kind, find(kind, id), "updatedAt"), + archive(kind, id) { + const row = find(kind, id) + stamp(kind, row, "archivedAt") + stamp(kind, row, "updatedAt") + }, + remove(kind, id) { + const row = find(kind, id) + rows[kind]?.splice(rows[kind].indexOf(row), 1) + }, + } +} + +const externalIdOf = (manifest: TrackerManifest, kind: TrackerKind, row: crmValues.CrmRaw) => { + const rule = manifest.entities[kind]?.map.externalId + const found = rule === undefined ? MISSING : evaluate(rule, row) + return found === MISSING ? null : crmValues.id(found) +} + +export interface TrackerManifestFixtureOptions extends TrackerManifestFakeOptions { + hooks?: TrackerManifestHooks +} + +/** + * A `trackerSourceContract` fixture for a source built from a manifest, over `trackerManifestFake`: the source, the + * rows it holds, a dead cursor, the faults the manifest allows, and the fake itself, whose `refusals` a test asserts + * empty. + */ +export const trackerManifestFixture = ( + manifest: unknown, + options: TrackerManifestFixtureOptions, +): TrackerSourceFixture & { fake: TrackerManifestFake } => { + const fake = trackerManifestFake(manifest, options) + const parsed = parseTrackerManifest(manifest, options.api) + const call = serviceApiCall({ + manifest: options.api, + service: parsed.provider, + fetch: fake.fetch, + token: () => FAKE_MANIFEST_TOKEN, + ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}), + }) + const sourceAt = (now: () => number = Date.now): TrackerSource => + trackerSourceFromManifest(manifest, { + api: options.api, + call, + now, + ...(options.hooks ? { hooks: options.hooks } : {}), + }) + const held = Object.fromEntries( + parsed.kinds.map((kind) => [kind, (fake.rows[kind] ?? []).map((row) => externalIdOf(parsed, kind, row) as string)]), + ) as Partial> + // An issue first: the kind a tracker's changes matter most for. Its last row is the one archived or removed, which + // no other row points at. + const changed = (["issue", ...[...parsed.kinds].reverse()] as const).find( + (kind) => parsed.kinds.includes(kind) && parsed.entities[kind]?.changes, + ) + const archivable = changed && parsed.entities[changed]?.map.archivedAt !== undefined + const first = (kind: TrackerKind) => held[kind]?.[0] as string + const last = (kind: TrackerKind) => held[kind]?.at(-1) as string + return { + source: sourceAt(), + fake, + held, + deadCursor: { kind: parsed.kinds[0] as TrackerKind, cursor: "not a time" }, + faults: { + remove: () => { + const kind = changed ?? (parsed.kinds.at(-1) as TrackerKind) + fake.remove(kind, last(kind)) + return { kind, id: last(kind) } + }, + ...(changed + ? { + skewed: (ms: number) => sourceAt(() => Date.now() + ms), + change: () => { + fake.touch(changed, first(changed)) + return { kind: changed, id: first(changed) } + }, + } + : {}), + ...(changed && archivable + ? { + archive: () => { + fake.archive(changed, last(changed)) + return { kind: changed, id: last(changed) } + }, + } + : {}), + }, + } +} + +/** + * `trackerSourceContract` over `trackerManifestFixture`, each case failing too when the fake refused a call: what a + * generated test runs, `for (const { name, run } of trackerManifestContract(SOURCE, { api, definitions })) it(name, run)`. + */ +export const trackerManifestContract = (manifest: unknown, options: TrackerManifestFixtureOptions): ContractCase[] => { + const fakes: TrackerManifestFake[] = [] + return trackerSourceContract(() => { + const fixture = trackerManifestFixture(manifest, options) + fakes.push(fixture.fake) + return fixture + }).map(({ name, run }) => ({ + name, + async run() { + fakes.length = 0 + const failed = await run().then( + () => undefined, + (error: unknown) => error, + ) + // A refused call fails the source too; the refusal says why, its error only that the tracker said no. + const refused = fakes.flatMap((fake) => fake.refusals) + if (refused.length) + throw new Error(`the fake refused calls the source made:\n${refused.join("\n")}`, { cause: failed }) + if (failed) throw failed + }, + })) +}