ci: Add context rich ai-review (#1194)

This adds experimental ai review with enhanced context. It uses
`.github/review-references.yaml` as repo specific instructions for
additional context.

This change is intended as live testing of the review. 
(To prevent leaking information from reference private repos, it is
allowed only for members of Apify team on Github)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Pijukatel

.github/review-references.yaml

@@ -0,0 +1,29 @@
+# Cross-repository references for the apify-factory review (apify/ai-developer, `review-references`).
+version: 1
+
+instructions: |
+  This repository is the Python client for the Apify API, a port of the JS client that the Python SDK
+  builds on. For every behaviour the pull request adds or changes, check three things: that it matches
+  what the API actually does, that it matches what the JS client does for the same operation (ignore
+  differences caused by different language idioms and style), and that every place the Python SDK uses
+  the changed code still works. Back every finding with the reference file and line (create public
+  github link fixed to a commit you have seen).
+
+references:
+  - repository: apify/apify-core
+    ref: develop
+    paths:
+      - src/api/**
+      - src/packages/**
+    instructions: |
+      The API the client calls. Compare the request the client builds with what the handler accepts
+      (paths, methods, query and body parameters, defaults, limits) and what the client expects back with
+      what the handler returns (field names and types, pagination, status codes, error types).
+  - repository: apify/apify-client-js
+    instructions: |
+      The reference implementation this client mirrors. Compare the changed Python methods with the
+      matching JS methods: parameters and defaults, the request it sends, how it parses the response,
+      what it returns, and how it handles errors.
+  - repository: apify/apify-sdk-python
+    instructions: |
+      The main consumer of this client. Highlight the changes that will require updates to the SDK.

.github/workflows/factory_review.yaml

@@ -25,6 +25,8 @@ jobs:
     # Paths never auto-approved here, on top of the pipeline's defaults. Proposed from the
     # repository's layout when this workflow was added; edit them like any other code.
     with:
+      # The draft of the cross-repository references, under evaluation. Back to `main` once it lands.
+      ai-developer-ref: claude/review-references
       policy: |
         {
           "denyGlobs": [

.rules.md

@@ -42,3 +42,7 @@ The OpenAPI spec can lag behind the API and omit fields, and a live response onl
 
 - A single resource's fields are in `PUBLISHED_*_FIELDS` in `src/packages/<area>-server/src/<resource>/<resource>.server.ts`.
 - A list endpoint has its own, usually smaller, `API_PUBLISHED_*_LIST_FIELDS` in `src/api/src/routes/<resource>/<resource>_list.ts`, and often builds each item inline. Don't assume a list item has the same fields as the single resource.
+
+### Additional context
+
+The code in this repository is based on and integrated with code from other repositories. The most important references are defined in [review references](./.github/review-references.yaml)