merge

Author: annaweber830

.claude/schemas/code-review-output.json

@@ -0,0 +1,27 @@
+{
+    "type": "object",
+    "properties": {
+        "violations": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "ruleId": {
+                        "type": "string"
+                    },
+                    "path": {
+                        "type": "string"
+                    },
+                    "line": {
+                        "type": "integer"
+                    },
+                    "body": {
+                        "type": "string"
+                    }
+                },
+                "required": ["ruleId", "path", "line", "body"]
+            }
+        }
+    },
+    "required": ["violations"]
+}

.claude/scripts/check-compiler.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Secure proxy script to run React Compiler compliance check on a single file.
+# Validates the filepath before passing it to the underlying npm script.
+set -eu
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <filepath>" >&2
+    exit 1
+fi
+
+readonly FILEPATH="$1"
+
+# Strict filepath validation - reject shell metacharacters
+if ! [[ "$FILEPATH" =~ ^[a-zA-Z0-9_./@-]+$ ]]; then
+    echo "Error: Invalid filepath (contains disallowed characters)" >&2
+    exit 1
+fi
+
+npm run react-compiler-compliance-check -- check "$FILEPATH"

.claude/skills/coding-standards/rules/clean-react-0-compiler.md

@@ -0,0 +1,127 @@
+---
+ruleId: CLEAN-REACT-PATTERNS-0
+title: React Compiler compliance
+---
+
+## [CLEAN-REACT-PATTERNS-0] React Compiler compliance
+
+### Reasoning
+
+React Compiler is enabled in this codebase (`babel-plugin-react-compiler` runs first in both webpack and metro configs). It automatically memoizes components and hooks at the AST level — analyzing data flow, tracking dependencies, and inserting fine-grained caching that is more precise than any hand-written `useMemo`, `useCallback`, or `React.memo`.
+
+Manual memoization is therefore:
+
+1. **Redundant** — the compiler already handles it, so the manual wrapper adds zero value
+2. **Harmful** — it interferes with the compiler's optimization model, potentially preventing it from applying its own caching strategy or causing double-wrapping
+3. **Noisy** — it clutters the codebase with dependency arrays that must be maintained, reviewed, and debugged
+
+The codebase enforces this via:
+- **Babel plugin**: `babel-plugin-react-compiler` in `babel.config.js`
+- **ESLint processor**: `eslint-plugin-react-compiler-compat` suppresses redundant lint rules when files compile successfully
+- **CI compliance check**: `scripts/react-compiler-compliance-check.ts` blocks PRs with manual memoization in new files
+
+Reference: [React Compiler documentation](https://react.dev/learn/react-compiler)
+
+### Incorrect
+
+#### Incorrect (useCallback)
+
+```tsx
+function ReportScreen({reportID}: {reportID: string}) {
+    const handlePress = useCallback(() => {
+        Navigation.navigate(ROUTES.REPORT_DETAILS.getRoute(reportID));
+    }, [reportID]);
+
+    return <Button onPress={handlePress} />;
+}
+```
+
+#### Incorrect (useMemo)
+
+```tsx
+function PolicyList({policies}: {policies: Policy[]}) {
+    const sortedPolicies = useMemo(
+        () => policies.sort((a, b) => a.name.localeCompare(b.name)),
+        [policies],
+    );
+
+    return <FlatList data={sortedPolicies} renderItem={renderItem} />;
+}
+```
+
+#### Incorrect (React.memo)
+
+```tsx
+const Avatar = React.memo(function Avatar({source, size}: AvatarProps) {
+    return <Image source={source} style={getAvatarStyle(size)} />;
+});
+```
+
+### Correct
+
+#### Correct (plain function — compiler memoizes automatically)
+
+```tsx
+function ReportScreen({reportID}: {reportID: string}) {
+    const handlePress = () => {
+        Navigation.navigate(ROUTES.REPORT_DETAILS.getRoute(reportID));
+    };
+
+    return <Button onPress={handlePress} />;
+}
+```
+
+#### Correct (plain expression — compiler memoizes automatically)
+
+```tsx
+function PolicyList({policies}: {policies: Policy[]}) {
+    const sortedPolicies = policies.sort((a, b) => a.name.localeCompare(b.name));
+
+    return <FlatList data={sortedPolicies} renderItem={renderItem} />;
+}
+```
+
+#### Correct (plain component — compiler memoizes automatically)
+
+```tsx
+function Avatar({source, size}: AvatarProps) {
+    return <Image source={source} style={getAvatarStyle(size)} />;
+}
+```
+
+---
+
+### Review Metadata
+
+#### Verification
+
+Before flagging, verify that the file actually compiles with React Compiler:
+
+```bash
+check-compiler.sh <filepath>
+```
+
+If the output contains **"Failed to compile"** for the file under review, the rule **does not apply** — the author may have no alternative to manual memoization until the compilation issue is resolved.
+
+#### Condition
+
+The verification step above is a prerequisite. Only flag when the file compiles successfully AND any of these are true in new or modified code:
+
+1. **`useCallback`** — A function is wrapped in `useCallback`. The compiler automatically memoizes closures based on their captured variables.
+2. **`useMemo`** — A value is wrapped in `useMemo`. The compiler automatically caches derived values.
+3. **`React.memo`** — A component is wrapped in `React.memo` (or `memo` imported from React). The compiler automatically skips re-rendering components whose props haven't changed.
+
+**Response:** Challenge the author: "React Compiler is enabled — remove the manual memoization and restructure the code so the compiler can handle it."
+
+The goal is to fix the root cause (make code compiler-friendly) rather than slap on manual memoization as a workaround.
+
+**Search Patterns:**
+- `useCallback\s*\(` — manual callback memoization
+- `useMemo\s*\(` — manual value memoization
+- `React\.memo\s*\(` or `memo\s*\(` — manual component memoization
+- Import statements: `useCallback`, `useMemo` from `react`
+
+**DO NOT flag if:**
+- The file does not compile with React Compiler (verified by the compliance check in the Verification section above)
+- The code is inside `node_modules/`, `patches/`, or test fixtures
+- The manual memoization exists in unchanged lines (pre-existing code not touched by the diff)

.claude/skills/onyx/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: onyx
+description: Onyx state management patterns — useOnyx hook, action files, optimistic updates, collections, and offline-first architecture. Use when working with Onyx connections, writing action files, debugging state, or implementing API calls with optimistic data.
+---
+
+## Core Concepts
+
+Onyx is a **persistent storage solution wrapped in a Pub/Sub library** that enables reactive, offline-first data management — key-value storage with automatic AsyncStorage persistence, reactive subscriptions, and collection management.
+
+For the full API reference (initialization, storage providers, cache eviction, benchmarks, Redux DevTools), see https://github.com/Expensify/react-native-onyx/blob/main/README.md.
+
+## Common Patterns
+
+### Action File Pattern
+
+**IMPORTANT:** Onyx state must only be modified from action files (`src/libs/actions/`). Never call `Onyx.merge`, `Onyx.set`, `Onyx.clear`, or `API.write` directly from a component.
+
+```typescript
+import Onyx from 'react-native-onyx';
+import ONYXKEYS from '@src/ONYXKEYS';
+
+function setIsOffline(isNetworkOffline: boolean, reason = '') {
+    if (reason) {
+        Log.info(`[Network] Client is ${isNetworkOffline ? 'offline' : 'online'} because: ${reason}`);
+    }
+    Onyx.merge(ONYXKEYS.NETWORK, {isOffline: isNetworkOffline});
+}
+
+export {setIsOffline};
+```
+
+### Optimistic Updates Pattern
+
+Optimistic updates allow users to see changes immediately while the API request is queued. This is fundamental to Expensify's offline-first architecture.
+
+For **which pattern to use** (A / B / C / D) and UX behavior for each, see https://github.com/Expensify/App/blob/main/contributingGuides/philosophies/OFFLINE.md.
+
+#### Understanding the Three Data Sets
+
+**CRITICAL:** Backend response data is automatically applied via Pusher updates or HTTPS responses. You do NOT manually set backend data in `successData`/`failureData` — only UI state cleanup goes there.
+
+1. **optimisticData** (Applied immediately, before the API call)
+   - Mirrors what the backend would return on success
+   - Gives the user instant feedback without waiting for the server
+   - Often includes `pendingAction` to flag the change as in-flight (e.g. greying out a comment while offline)
+   - `pendingAction` is cleared once `successData` or `failureData` is applied
+
+2. **successData** (Applied when API succeeds)
+   - Used for UI state cleanup: clearing `pendingAction`, setting `isLoading: false`
+   - For `add` actions: often not needed (optimisticData already set the right state)
+   - For `update`/`delete` actions: include to clear pending state
+
+3. **failureData** (Applied when API fails)
+   - Reverts optimisticData changes
+   - Clears `pendingAction`.
+   - Adds `errors` field for the user to see
+   - Always include this to handle unexpected failures
+
+For code examples of each pattern (A/B, loading state, `finallyData`), see [offline-patterns.md](offline-patterns.md).
+
+## Performance Optimization
+
+### 1. Subscribe to Specific Collection Members
+
+```typescript
+// BAD: re-renders on any report change
+const [allReports] = useOnyx(ONYXKEYS.COLLECTION.REPORT);
+const myReport = allReports[`report_${reportID}`];
+
+// GOOD: re-renders only when this report changes
+const [myReport] = useOnyx(`${ONYXKEYS.COLLECTION.REPORT}${reportID}`);
+```
+
+### 2. Use Selectors to Narrow Re-renders
+
+```typescript
+const accountIDSelector = (account: Account) => account?.accountID;
+const [accountID] = useOnyx(ONYXKEYS.ACCOUNT, {selector: accountIDSelector});
+```
+
+`useOnyx` caches by selector reference — a new function reference on every render bypasses the cache and causes unnecessary re-renders. Prefer pure selectors defined in `src/selectors/` over inline functions. If a selector must be defined inside a component, ensure referential stability: React Compiler handles this automatically, but in components that are not compiled, wrap the selector in `useMemo`.
+
+```typescript
+// BAD: new function reference on every render defeats caching
+const [accountID] = useOnyx(ONYXKEYS.ACCOUNT, {selector: (account) => account?.accountID});
+
+// GOOD: stable reference defined outside the component
+// src/selectors/accountSelectors.ts
+const selectAccountID = (account: Account) => account?.accountID;
+
+// GOOD: stable reference via useMemo (for non-React-Compiler components)
+const selector = useMemo(() => (account: Account) => account?.accountID, []);
+const [accountID] = useOnyx(ONYXKEYS.ACCOUNT, {selector});
+```
+
+For `skipCacheCheck` (large objects) and batch collection update patterns, see https://github.com/Expensify/react-native-onyx/blob/main/README.md.
+
+## Common Pitfalls
+
+### Mixing set and merge on the Same Key
+
+`Onyx.set()` calls are not batched with `Onyx.merge()` calls, which can produce race conditions:
+
+```typescript
+// BAD: merge may execute before set resolves
+Onyx.set(ONYXKEYS.ACCOUNT, null);
+Onyx.merge(ONYXKEYS.ACCOUNT, {validated: true});
+
+// GOOD: use one operation
+Onyx.set(ONYXKEYS.ACCOUNT, {validated: true});
+```
+
+## Common Tasks Quick Reference
+
+```typescript
+// Update a single field
+Onyx.merge(ONYXKEYS.NETWORK, {isOffline: true});
+
+// Delete data
+Onyx.set(ONYXKEYS.ACCOUNT, null);
+
+// Subscribe in component
+const [data] = useOnyx(ONYXKEYS.SOME_KEY);
+
+// Subscribe with selector
+const [field] = useOnyx(ONYXKEYS.SOME_KEY, {selector: (data) => data?.specificField});
+
+// Update collection member
+Onyx.merge(`${ONYXKEYS.COLLECTION.REPORT}${reportID}`, {unread: false});
+
+// Batch update collection
+Onyx.mergeCollection(ONYXKEYS.COLLECTION.REPORT, updates);
+
+// API call with optimistic update
+API.write('SomeCommand', params, {optimisticData, successData, failureData});
+```
+
+## Related Files
+
+- https://github.com/Expensify/react-native-onyx/blob/main/README.md - Full Onyx API reference (initialization, merge/set/connect, collections, loading state, cache eviction, Redux DevTools, benchmarks)
+- https://github.com/Expensify/App/blob/main/contributingGuides/philosophies/OFFLINE.md - Full offline UX patterns, decision flowchart, and when to use each pattern (A/B/C/D)
+- [offline-patterns.md](offline-patterns.md) - Code examples for each optimistic update pattern
+- https://github.com/Expensify/App/blob/main/src/ONYXKEYS.ts - All Onyx key definitions
+- https://github.com/Expensify/App/tree/main/src/libs/actions - Action files that update Onyx
+- https://github.com/Expensify/App/blob/main/src/hooks/useOnyx.ts - useOnyx hook implementation
+- https://github.com/Expensify/App/tree/main/src/types/onyx - TypeScript types for Onyx data