feat(zendesk): add Zendesk datasource package

[PMerlet]

Summary

New forest_admin_datasource_zendesk package that surfaces Zendesk Tickets, Users, Organizations, and ticket Comments as Forest Admin collections — same architectural pattern as the existing forest_admin_datasource_active_record / _mongoid / _rpc siblings, mirroring the Node @forestadmin/datasource-* ecosystem.

• 4 collections with schema-level intra-datasource relations: Ticket → requester/assignee/organization/comments, Comment → author/ticket, User → organization/requested_tickets, Organization → users/tickets.
• Custom fields: discovers admin-defined ticket_fields, user_fields, organization_fields at boot and exposes them as real Forest columns. Translator rewrites custom-column names to Zendesk Search syntax.
• Timezone-aware Date filters: Forest's caller timezone is threaded through the translator; bare Date values are interpreted as start-of-day in the caller's TZ then converted to UTC (DST-aware).
• Loud-vs-graceful error handling: critical paths (search, count, fetch_ticket_comments) raise APIError; enrichment paths (bulk user/org lookups, schema introspection) log a warning and degrade safely.
• Synthetic single-PK on Comments (<comment_id>-<ticket_id> String) to side-step forest_admin_rails 1.26.2's URL constraint, which rejects the | character used by the toolkit's native composite-key pack_id. Filed-this-as-a-bug-worth-fixing-upstream note in the relevant code comment.

What's NOT in this PR (deliberate v1 scope)

• Read-only — no create/update/delete on any collection. The Compliance handoff workflow (update ticket status / reassign group) is the obvious next add.
• No caching — every list page hits Zendesk's Search API + bulk user/org lookups. Add Rails.cache wrapping in a follow-up if rate limits become a concern.
• Zendesk Search's 1000-result hard cap is not surfaced in pagination yet (cursor-based Incremental Export API would be the correct path for large datasets).
• No native OR-aggregator translation (raises loudly on unsupported operators).

Test plan

• cd packages/forest_admin_datasource_zendesk && bundle install && bundle exec rspec — 131 examples, 0 failures
• Coverage ≥ 90% line and branch (98.5% line / 90.7% branch with WebMock blocking real net)
• Manually verified end-to-end against a live Zendesk dev instance (browse tickets, requester join, conversation thread via Ticket → comments related list, comment detail page via synthetic PK)
• Reviewer to confirm: gemspec metadata, dependency pins, SchemaEmitter compatibility with toolkit ≥ 1.26
• Reviewer to confirm: package layout matches conventions (Zeitwerk, Rakefile, .rspec)

🤖 Generated with Claude Code

Note

Add Zendesk datasource package with collections for tickets, users, organizations, and comments

• Introduces a new forest_admin_datasource_zendesk gem that connects Forest Admin to Zendesk via the zendesk_api gem, exposing Ticket, User, Organization, and Comment as queryable collections.
• Implements a ConditionTreeTranslator that converts Forest Admin filter trees to Zendesk Search query strings, with timezone-aware date handling, custom field remapping, and AND-only aggregation.
• Adds a Client wrapper with distinct error policies: critical paths raise APIError on failure; enrichment paths (bulk email/user/org lookups, schema introspection) degrade gracefully to {} or [] with a warning.
• Custom fields are discovered at boot via CustomFieldsIntrospector, which maps Zendesk field types to Forest column schemas and injects them into collection schemas and query translation.
• Wires the package into CI (lint, coverage), semantic-release automation, and RuboCop configuration.

^{Macroscope summarized 116f909.}

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): aggregate	1

[qltysh]

Function with many parameters (count = 4): aggregate [qlty:function-parameters]

[macroscopeapp]

🟢 Low query/condition_tree_translator.rb:59

The special requester: mapping on line 63 only applies to the EQUAL operator. For NOT_EQUAL, IN, or NOT_IN on requester_email, the code falls through to the generic path and emits the unmappable field name requester_email instead of requester, producing malformed queries like -requester_email:value or requester_email:val1 requester_email:val2.

       def translate_leaf(leaf)
         field = mapped_field(leaf.field)
         value = leaf.value
 
-        return "requester:#{format_value(value)}" if leaf.field == 'requester_email' && leaf.operator == Operators::EQUAL
+        field = 'requester' if leaf.field == 'requester_email'
 
         case leaf.operator

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

In file packages/forest_admin_datasource_zendesk/lib/forest_admin_datasource_zendesk/query/condition_tree_translator.rb around lines 59-64:

The special `requester:` mapping on line 63 only applies to the `EQUAL` operator. For `NOT_EQUAL`, `IN`, or `NOT_IN` on `requester_email`, the code falls through to the generic path and emits the unmappable field name `requester_email` instead of `requester`, producing malformed queries like `-requester_email:value` or `requester_email:val1 requester_email:val2`.

Evidence trail:
packages/forest_admin_datasource_zendesk/lib/forest_admin_datasource_zendesk/query/condition_tree_translator.rb at REVIEWED_COMMIT:
- Line 58: `field = mapped_field(leaf.field)`
- Line 63: `return "requester:#{format_value(value)}" if leaf.field == 'requester_email' && leaf.operator == Operators::EQUAL` - special case only for EQUAL
- Lines 65-68: generic case statement uses `field` variable for NOT_EQUAL, IN, NOT_IN
- Lines 87-89: `mapped_field` returns `@custom_fields[field] || field` - returns field name unchanged if not in custom_fields