deepmerge-plus/AGENTS.md

用於深度（遞迴）合併 JavaScript 物件的函式庫 / A library for deep (recursive) merging of JavaScript objects

# deepmerge-plus 專案代理規則
# deepmerge-plus Project Agent Rules

## 概述

本檔案定義了 deepmerge-plus 專案中代理（Agent）工具呼叫的規則和相容性記錄。

This file defines the rules and compatibility records for agent tool invocation in the deepmerge-plus project.

---

## 測試檔案規則

### 共享屬性規則

**新建立的測試都必須在 target 和 source 中加入共享屬性。**

**New tests must include shared properties in both target and source.**

```typescript
import { _sharedPropTarget, _sharedPropSource } from './lib/data';

const target = {
  // ... 其他測試屬性
  ..._sharedPropTarget,
};

const source = {
  // ... 其他測試屬性
  ..._sharedPropSource,
};
```

**為什麼需要共享屬性？**

- 確保測試能夠捕捉到 falsy 值（`null`、`undefined`、`false`、`0`）的處理問題
- 這些值在 `keyValueOrMode` 和 `keyValueUpsertMode` 選項中特別重要
- 有助於驗證 `??` 運算子與 `||` 運算子的行為差異

**Why are shared properties needed?**

- Ensures tests catch falsy value handling issues (`null`, `undefined`, `false`, `0`)
- These values are particularly important for `keyValueOrMode` and `keyValueUpsertMode` options
- Helps verify the behavioral differences between `??` and `||` operators

---

## 工具呼叫優先順序

當需要使用 package runner 呼叫工具時，依序嘗試以下工具：

| 優先順序 | 工具 | 適用環境 |
|---------|------|---------|
| 1 | `ynpx` | 跨環境工具（支援 Yarn 與 pnpm） |
| 2 | `pnpm dlx` | pnpm 環境 |
| 3 | `bunx` | Bun 環境 |
| 4 | `npx` | 最後手段（Node.js 預設） |

---

## 工具相容性記錄

### 測試工具

| 工具 | 直接呼叫 | ynpx | pnpm dlx | bunx | npx | 備註 |
|------|---------|------|----------|------|-----|------|
| **jest** | ❌ | - | - | - | ✅ | 需要透過 pnpm run test 執行 |
| **tsx** | ✅ | - | - | - | - | 可直接呼叫 |

### 執行 TypeScript 檔案

| 工具 | 直接呼叫 | tsx | ts-node | 備註 |
|------|---------|-----|---------|------|
| **tsx** | ✅ | - | - | 優先使用 tsx 執行 |
| **ts-node** | ✅ | - | - | 若 tsx 失敗則使用 ts-node |

---

## 測試執行方式

### 執行所有測試

```bash
pnpm run test
```

### 執行特定測試檔案

```bash
pnpm run test test/tmp-runtime-data.test.ts
```

### 直接呼叫 Jest

若直接呼叫失敗，請依序嘗試：

```bash
# 1. 嘗試 ynpx
ynpx jest test/tmp-runtime-data.test.ts

# 2. 嘗試 pnpm dlx
pnpm dlx jest test/tmp-runtime-data.test.ts

# 3. 嘗試 bunx
bunx jest test/tmp-runtime-data.test.ts

# 4. 最後手段：npx
npx jest test/tmp-runtime-data.test.ts
```

---

## 失敗紀錄

當工具無法正常運作時，請將該工具記錄至對應的檔案：

- `docs/ts-node-required.md` - 需要使用 ts-node 的檔案清單
- `docs/npx-required.md` - 需要使用 npx 的模組清單

---

## 注意事項

1. **優先使用已安裝的工具**：盡量不使用 package runner，直接呼叫已安裝的工具
2. **依序嘗試**：當需要使用 package runner 時，依序嘗試 ynpx → pnpm dlx → bunx → npx
3. **記錄結果**：將最終可用的呼叫方式記錄於本檔案
4. **環境差異**：不同工具對於呼叫方式可能有不同的相容性

---

## 更新日誌

| 日期 | 更新內容 |
|------|---------|
| 2026-03-25 | 初始版本，建立工具呼叫優先順序與相容性記錄 |