From 0d52a4337780760cd384164001678df6e1e3a362 Mon Sep 17 00:00:00 2001 From: leemour Date: Wed, 18 Nov 2026 20:08:58 +0100 Subject: [PATCH 1/4] feat(tracker): trackerManifestContract, trackerManifestFake and trackerManifestFixture test a source from a manifest A tracker CLI made from wirecat.config.ts (linear-cli first) could not run trackerSourceContract: fakeTrackerSource is a TrackerSource, not a fake of the service, and the generated test synced over graphqlFake, which answers schema samples with no state. This is the tracker counterpart of #3088. - trackerManifestFake(manifest, { api, definitions, baseUrl? }) is cli-base's strict graphqlFake with three rows of each kind behind it. Each row is sampled within every selection its kind's calls send, with the values the map reads written where it reads them, and links to the first row of the kind a field points at (state.id, assignee.id, labels.nodes with each). Calls are answered within their selection, two rows a Relay page; a change read keeps rows at or after its since, oldest first; an operation taking includeArchived hides archived rows unless the call sets it. A call whose fixed variables match no manifest call, a cursor the fake never gave, an unreadable since and an answer of its own that breaks the schema are recorded in refusals. touch, archive and remove change a row. - trackerManifestFixture adds the source, held ids, a dead cursor and the faults skewed, change, archive and remove. - trackerManifestContract runs trackerSourceContract over it and fails a case whose calls the fake refused. - The Linear-shaped schema of source.test.ts moves to src/testing/ tracker-graphql.ts so both tests use it; its change call now sends orderBy, and issue labels use { each, id } as linear-cli does. - rowSelection is exported from the tracker manifest module. Co-Authored-By: Claude Opus 5.5 --- changes/feat-tracker-manifest-fake.md | 10 + docs/dev/TRACKER.md | 26 ++ src/testing/tracker-graphql.ts | 213 +++++++++ src/tracker/manifest/manifest.ts | 2 +- src/tracker/manifest/source.test.ts | 212 +-------- src/tracker/testing/index.ts | 8 + src/tracker/testing/manifest-fake.test.ts | 138 ++++++ src/tracker/testing/manifest-fake.ts | 517 ++++++++++++++++++++++ 8 files changed, 915 insertions(+), 211 deletions(-) create mode 100644 changes/feat-tracker-manifest-fake.md create mode 100644 src/testing/tracker-graphql.ts create mode 100644 src/tracker/testing/manifest-fake.test.ts create mode 100644 src/tracker/testing/manifest-fake.ts 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..65c3bc074 100644 --- a/docs/dev/TRACKER.md +++ b/docs/dev/TRACKER.md @@ -92,3 +92,29 @@ 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}"`, oldest first. An operation that takes + `includeArchived` hides archived rows unless the call sets 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, 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. +- 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..0d8bf0f86 --- /dev/null +++ b/src/testing/tracker-graphql.ts @@ -0,0 +1,213 @@ +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") }), + 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) + +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" } +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", 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..f03feb5c7 --- /dev/null +++ b/src/tracker/testing/manifest-fake.test.ts @@ -0,0 +1,138 @@ +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("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) => { + const found = trackerManifestContract(manifest, { api, definitions }).find((one) => name.test(one.name)) + await expect(found?.run()).rejects.toThrow() + } + + it("an id pass that leaves archived rows out", async () => { + await failing(withIssue({ ids: { ...issue.ids, variables: { first: 50 } } as typeof issue.ids }), /archived/) + }) + + it("a change read with no overlap, which loses a change when the clock runs ahead", async () => { + await failing({ ...MANIFEST, overlapMs: 0 }, /clock off/) + }) + + 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..70d9a5e00 --- /dev/null +++ b/src/tracker/testing/manifest-fake.ts @@ -0,0 +1,517 @@ +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)] + }), + ) + +/** Only the selected fields: what GraphQL answers. */ +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)]), + ) +} + +/** Every dotted path with a fixed value in a call's variables; a placeholder is not fixed. */ +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"] } +} + +/** + * 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: TrackerManifest, + 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) + + /** A value of the type with only the selected fields. */ + 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 routes: Route[] = manifest.kinds.flatMap((kind) => { + const entity = manifest.entities[kind] as NonNullable + return [ + { kind, call: entity.list }, + ...(entity.ids ? [{ kind, call: entity.ids }] : []), + ...(entity.changes + ? [ + { + kind, + call: entity.changes, + since: { place: placeOf(entity.changes.variables, "{since}") as string, format: entity.changes.since }, + }, + ] + : []), + ] + }) + + /** 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`) + 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) => (timeOf(kind, row, "updatedAt") ?? Number.NEGATIVE_INFINITY) >= 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: TrackerManifest, + 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: TrackerManifest, + 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 + await run() + const refused = fakes.flatMap((fake) => fake.refusals) + if (refused.length) throw new Error(`the fake refused calls the source made:\n${refused.join("\n")}`) + }, + })) +} From f9e9a3fb8295a580f8f81f5017d6d95ad94742a0 Mon Sep 17 00:00:00 2001 From: leemour Date: Wed, 18 Nov 2026 20:56:58 +0100 Subject: [PATCH 2/4] fix(tracker): trackerManifestContract takes the generated SOURCE as it is, and an enum field is pinned by a test The generated wirecat-config.ts types SOURCE as a plain record, so the three helpers take the manifest as unknown and parse it, as trackerSourceFromManifest does; linear-cli's test needs no cast. The Linear-shaped schema gains an enum project status, and a test checks the fake writes one of its values, the one defect linear-cli's real schema showed. Co-Authored-By: Claude Opus 5.5 --- src/testing/tracker-graphql.ts | 2 ++ src/tracker/testing/manifest-fake.test.ts | 22 ++++++++++++++++++++++ src/tracker/testing/manifest-fake.ts | 15 +++------------ 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/src/testing/tracker-graphql.ts b/src/testing/tracker-graphql.ts index 0d8bf0f86..2a4c49344 100644 --- a/src/testing/tracker-graphql.ts +++ b/src/testing/tracker-graphql.ts @@ -41,10 +41,12 @@ export const definitions: Record = { 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, diff --git a/src/tracker/testing/manifest-fake.test.ts b/src/tracker/testing/manifest-fake.test.ts index f03feb5c7..e2db0aebd 100644 --- a/src/tracker/testing/manifest-fake.test.ts +++ b/src/tracker/testing/manifest-fake.test.ts @@ -109,6 +109,28 @@ describe("trackerManifestFake", () => { ]) }) + 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 } } } diff --git a/src/tracker/testing/manifest-fake.ts b/src/tracker/testing/manifest-fake.ts index 70d9a5e00..199349288 100644 --- a/src/tracker/testing/manifest-fake.ts +++ b/src/tracker/testing/manifest-fake.ts @@ -95,7 +95,6 @@ const merge = (a: Selection, b: Selection): Selection => }), ) -/** Only the selected fields: what GraphQL answers. */ 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)) @@ -104,7 +103,6 @@ const project = (value: unknown, selection: Selection | true): unknown => { ) } -/** Every dotted path with a fixed value in a call's variables; a placeholder is not fixed. */ const fixedOf = (value: unknown, trail: readonly string[] = []): [string, unknown][] => crmValues.isRaw(value) ? Object.entries(value).flatMap(([key, inner]) => fixedOf(inner, [...trail, key])) @@ -146,10 +144,7 @@ interface Route { * 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: TrackerManifest, - options: TrackerManifestFakeOptions, -): TrackerManifestFake => { +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])) @@ -173,7 +168,6 @@ export const trackerManifestFake = ( return resolved?.type === "array" ? resolved.items : (found ?? undefined) }, node) - /** A value of the type with only the selected fields. */ const sampled = (node: SchemaNode, selection: Selection | true): unknown => { if (selection === true) return sampleOf(node, definitions) const found = resolve(node, definitions) @@ -430,7 +424,7 @@ export interface TrackerManifestFixtureOptions extends TrackerManifestFakeOption * empty. */ export const trackerManifestFixture = ( - manifest: TrackerManifest, + manifest: unknown, options: TrackerManifestFixtureOptions, ): TrackerSourceFixture & { fake: TrackerManifestFake } => { const fake = trackerManifestFake(manifest, options) @@ -496,10 +490,7 @@ export const trackerManifestFixture = ( * `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: TrackerManifest, - options: TrackerManifestFixtureOptions, -): ContractCase[] => { +export const trackerManifestContract = (manifest: unknown, options: TrackerManifestFixtureOptions): ContractCase[] => { const fakes: TrackerManifestFake[] = [] return trackerSourceContract(() => { const fixture = trackerManifestFixture(manifest, options) From 24cf3a4e22fc6c00aef94caa3caf2d2044ef49f8 Mon Sep 17 00:00:00 2001 From: leemour Date: Wed, 18 Nov 2026 21:05:00 +0100 Subject: [PATCH 3/4] fix(tracker): the manifest fake refuses a since or a filter it cannot apply, and names the refusal in the failed case A review found manifests the contract passed although real Linear would answer them differently: - {since} was found by position and always read as updatedAt >= since, so filter.createdAt.gte and filter.updatedAt.lt passed. A change call is now refused unless {since} sits at .gte or .gt; gt keeps only rows strictly after it. - Fixed variables only picked a route, so an ids call filtering out canceled issues passed, though sync would mark them deleted. A list or id call with a filter, and a change call whose filter holds anything beside the since, are refused. Other variables are trusted, and TRACKER.md says so. - trackerManifestContract now fails with the fake's refusals as the message even when the source threw first, so a test can match why. - TRACKER.md says the dead-cursor case is answered by the source itself and never reaches the fake. Co-Authored-By: Claude Opus 5.5 --- docs/dev/TRACKER.md | 15 +++++-- src/tracker/testing/manifest-fake.test.ts | 53 ++++++++++++++++++++-- src/tracker/testing/manifest-fake.ts | 55 +++++++++++++++++++---- 3 files changed, 106 insertions(+), 17 deletions(-) diff --git a/docs/dev/TRACKER.md b/docs/dev/TRACKER.md index 65c3bc074..6cea6974c 100644 --- a/docs/dev/TRACKER.md +++ b/docs/dev/TRACKER.md @@ -106,15 +106,22 @@ for (const { name, run } of trackerManifestContract(SOURCE, { api, definitions } 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}"`, oldest first. An operation that takes - `includeArchived` hides archived rows unless the call sets it. + 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, and the faults +- `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. + 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/tracker/testing/manifest-fake.test.ts b/src/tracker/testing/manifest-fake.test.ts index e2db0aebd..c7d66e678 100644 --- a/src/tracker/testing/manifest-fake.test.ts +++ b/src/tracker/testing/manifest-fake.test.ts @@ -139,17 +139,62 @@ describe("trackerManifestFake", () => { }) describe("a source the contract catches over the fake", () => { - const failing = async (manifest: TrackerManifest, name: RegExp) => { + const failing = async (manifest: TrackerManifest, name: RegExp, message: RegExp) => { const found = trackerManifestContract(manifest, { api, definitions }).find((one) => name.test(one.name)) - await expect(found?.run()).rejects.toThrow() + 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/) + 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/) + 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", () => { diff --git a/src/tracker/testing/manifest-fake.ts b/src/tracker/testing/manifest-fake.ts index 199349288..f10a6b18b 100644 --- a/src/tracker/testing/manifest-fake.ts +++ b/src/tracker/testing/manifest-fake.ts @@ -134,9 +134,14 @@ const put = (row: crmValues.CrmRaw, path: string, value: unknown) => { interface Route { kind: TrackerKind call: TrackerOperationCall - since?: { place: string; format: TrackerChangesCall["since"] } + 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, @@ -257,17 +262,39 @@ export const trackerManifestFake = (input: unknown, options: TrackerManifestFake }) } + 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 [ - { kind, call: entity.list }, - ...(entity.ids ? [{ kind, call: entity.ids }] : []), - ...(entity.changes + plain(entity.list), + ...(entity.ids ? [plain(entity.ids)] : []), + ...(changes && place ? [ { kind, - call: entity.changes, - since: { place: placeOf(entity.changes.variables, "{since}") as string, format: entity.changes.since }, + call: changes, + since: { place, format: changes.since, after: place.endsWith(".gt") }, + ...(problem ? { problem } : {}), }, ] : []), @@ -315,6 +342,7 @@ export const trackerManifestFake = (input: unknown, options: TrackerManifestFake 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 @@ -327,7 +355,10 @@ export const trackerManifestFake = (input: unknown, options: TrackerManifestFake const from = SINCE[route.since.format](sent) if (!Number.isFinite(from)) return refuse(`${call.operation}: since ${sent} is unreadable`) listed = listed - .filter((row) => (timeOf(kind, row, "updatedAt") ?? Number.NEGATIVE_INFINITY) >= from) + .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 ?? {} @@ -500,9 +531,15 @@ export const trackerManifestContract = (manifest: unknown, options: TrackerManif name, async run() { fakes.length = 0 - await run() + 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")}`) + if (refused.length) + throw new Error(`the fake refused calls the source made:\n${refused.join("\n")}`, { cause: failed }) + if (failed) throw failed }, })) } From f1765411969893cee92a0cd34b4e98ce5e63c87e Mon Sep 17 00:00:00 2001 From: leemour Date: Wed, 18 Nov 2026 21:27:46 +0100 Subject: [PATCH 4/4] fix(tracker): the test schema's key fields are constants, so the permission-key check does not read them as keys Co-Authored-By: Claude Opus 5.5 --- src/testing/tracker-graphql.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/testing/tracker-graphql.ts b/src/testing/tracker-graphql.ts index 2a4c49344..12a1a062b 100644 --- a/src/testing/tracker-graphql.ts +++ b/src/testing/tracker-graphql.ts @@ -152,8 +152,11 @@ const SELECTIONS: Record = { 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: "key" }, + 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" }, @@ -169,7 +172,7 @@ const MAPS: { [K in TrackerKind]: Record } = { }, issue: { ...TIME_MAP, - key: "identifier", + key: ISSUE_KEY, title: "title", description: "description", state: "state.id",