feat(datasource intercom): relations of the reference tier (lot 2.5)

[christophebrun-forest]

Lot 2.5 of PRD-1111 — PRD-1145. Branches off feat/datasource-intercom and merges back into it.

Declares the relations between the collections this datasource already serves, and answers them. Lot 1 shipped none, on the ground that a relation whose target collection is missing makes the schema refuse to boot — true of Contacts and Companies only, while IntercomAdmin, IntercomTeam, IntercomTicketState and IntercomTicketType all shipped in that same lot. The visible consequence: an assignee, a state and a type were raw ids, and a team was an array of ids with no link to its teammates.

What sizes this change

Publishing a many-to-one is not free. The agent marks it filterable as soon as any column of its target is (GeneratorField#build_many_to_one_schema), so the interface offers assignee:name the moment the relation exists — and the datasource cannot opt out: making the relation unfilterable would mean stripping the filters off Admin and Team themselves. Left unanswered, that filter reaches a translator refusing every traversing field, which is the interface offering a filter this package then refuses.

So the traversal is the bulk of the diff, and the declarations are a handful of lines.

What it does

• Eight many-to-one relations towards Admin, Team, TicketState and TicketType, declared before the ticket-attribute columns so a workspace attribute whose name lands on a relation is skipped with a warning rather than colliding and taking the boot with it.
• IntercomTeamMembership, synthesized from GET /teams: Intercom carries the membership on both sides (teams[].admin_ids, admins[].team_ids) and exposes no resource for the pair, while a many-to-many needs a collection to travel through. One record per pair, keyed teamId:adminId, read-only — Intercom writes none. Teams and Admins now navigate to each other both ways.
• admin_names / team_names replace the arrays of ids on Team and Admin: one readable form plus a relation to navigate, rather than two ways to read one fact. Read only when a projection asks for them, and a token that cannot read the other side costs the column, never the page or the relation.
• One label per object on a ticket: state_category and state_external_label are dropped — a hop away on the state relation, and neither was ever filterable, so no segment, scope or saved filter could rest on them. state_label and ticket_type_name stay, a list view having to read without a join.
• A projection through a relation reads its target once per page, never once per row, and nests the row under the relation name. An id naming no record reads as no record, not as a broken row.
• A condition through a relation is resolved by the target itself — over every record it holds, not over a page — and becomes a condition on the foreign key. Exact, with three edges, all refused by name rather than approximated:
  • Intercom takes no membership operator on these fields, so N matches become an OR of N equalities, which counts against the 15 conditions a group allows. Past that: refused, naming the relation the operator filtered on rather than the key it resolved to.
  • A condition the target matched nothing with names no row, and the DSL cannot say so: the search is skipped entirely instead of being sent as a filter that would come back with everything.
  • A relation whose foreign key the endpoint does not filter — the ticket state — is refused before the target is read, saying which of the two it is: read and navigate, not filter.

Decisions taken while implementing

• A nil projection now returns only the declared columns. The raw membership ids stay on the serialized row — they are what the names are read from — but are no longer published: project slices on the columns.
• A relation's filterability is checked before the target is read. A filter on state:category used to read /ticket_states for nothing before refusing.
• The unknown-relation refusal covers the many-to-many too. A scope written on admins:name is refused saying which relations are filtered through, rather than claiming the relation does not exist.

Known, and documented rather than discovered

• A relation reads its target undecorated, so a permission scope or segment on the target does not narrow what a relation resolves. That is how a native datasource behaves — it joins the table without applying the scopes of the collection mapped to it — but it belongs in the README.
• A row whose foreign key is null matches no relation filter, the way a join drops it, negated filters included. A ticket with no assignee is not "assigned to someone other than Marie".
• state_id is still to probe on /tickets/search: the measured table carries no filter on a state id, so the state relation navigates without translating into a filter. In the refusal table and in the README, not in an assumption.

Verification

• 418 examples, 0 failures, 100% line coverage on the package.
• RuboCop clean across the 899 files of the repo.
• Covered: the refusals, the id-type match on both ends of every relation, the 15-leaf ceiling, matches-nothing without a request, relation conditions nested inside and / or next to native ones, and the real related-list path through Utils::Collection.list_relation.
• Every payload is hand-written from the OpenAPI 2.16 spec, never captured from a workspace.

README: a ## Relations section (the table, the synthesized membership, the read cost, the null semantics) and a ### Through a relation subsection under Filtering.

🤖 Generated with Claude Code

Note

Add reference-tier relations and IntercomTeamMembership to Intercom datasource

• Adds a shared relations.rb module that lets collections declare read-only many-to-one and many-to-many relations, project nested records, and rewrite relation filters into foreign-key conditions.
• Introduces team_membership.rb as a synthesized collection to support the many-to-many relation between IntercomTeam and IntercomAdmin.
• Updates Ticket, Admin, Team, and Conversation collections to declare relations such as admin_assignee, teams, and closed_by, replacing raw ID lists with derived admin_names and team_names columns.
• Risk: Removes the team_ids, admin_ids, state_category, and state_external_label columns from the Intercom schemas; any existing consumers relying on these fields will break.

^{Macroscope summarized e1ae9b4.}

[qltysh]

All good ✅

[qltysh]

Coverage Impact

Unable to calculate total coverage change because base branch coverage was not found.

Modified Files with Diff Coverage (12)

Rating	File	% Diff	Uncovered Line #s
	...rcom/lib/forest_admin_datasource_intercom/collections/admin.rb	100.0%
	...t_admin_datasource_intercom/query/condition_tree_translator.rb	100.0%
	...orest_admin_datasource_intercom/collections/team_membership.rb	100.0%
	...ercom/lib/forest_admin_datasource_intercom/collections/team.rb	100.0%
	...b/forest_admin_datasource_intercom/collections/conversation.rb	100.0%
	.../lib/forest_admin_datasource_intercom/collections/relations.rb	100.0%
	..._admin_datasource_intercom/collections/fetch_all_collection.rb	100.0%
	...ce_intercom/lib/forest_admin_datasource_intercom/datasource.rb	100.0%
	...orest_admin_datasource_intercom/collections/base_collection.rb	100.0%
	...est_admin_datasource_intercom/collections/cursor_collection.rb	100.0%
	...oolkit/lib/forest_admin_datasource_toolkit/utils/collection.rb	100.0%
	...com/lib/forest_admin_datasource_intercom/collections/ticket.rb	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[macroscopeapp]

🟡 Medium

agent-ruby/packages/forest_admin_datasource_toolkit/lib/forest_admin_datasource_toolkit/utils/collection.rb

Line 197 in e1ae9b4

return through_collection.aggregate(

aggregate_relation counts through rows even when their nested target resolves to nil, so /count-related reports memberships that list_relation has already removed. This makes relationship counts and pagination incorrect for deleted or inaccessible targets; apply the same target-existence filtering before aggregating.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/forest_admin_datasource_toolkit/lib/forest_admin_datasource_toolkit/utils/collection.rb around line 197:

`aggregate_relation` counts through rows even when their nested target resolves to `nil`, so `/count-related` reports memberships that `list_relation` has already removed. This makes relationship counts and pagination incorrect for deleted or inaccessible targets; apply the same target-existence filtering before aggregating.