---
name: spec-node-src-layout
description: JSC plugins 共用「Node 主程式 src/ 收攏規範」：主程式改寫為 Node 之後，主程式入口及其 require／import 依賴鏈的 .js／.mjs／.cjs 檔集中收進 src/；明文排除工具設定檔（如 *.config.js）與 test/、tests/、scripts/ 目錄；搬移後必須更新所有引用該路徑的地方（require／import 相對路徑、package.json 的 main／bin／scripts／exports、action.yml／Dockerfile／entrypoint.sh 等指令檔內的路徑）。當其他 skill 內文引用 spec-node-src-layout 或 /jsc-shared:spec-node-src-layout、或需要把 Node 主程式的 .js 收進 src/ 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
---

# spec-node-src-layout — 共用 Node 主程式 src/ 收攏規範

主程式改寫（或確認）為 Node 之後，一律依以下規範把主程式及其依賴鏈收進 `src/`，不得另行約定不同的收攏範圍或排除規則。

## 收攏範圍

- 在專案根目錄建立 `src/`（若不存在）。
- 將**主程式入口及其 `require`／`import` 依賴鏈**的 `.js`／`.mjs`／`.cjs` 檔**移入 `src/`**，優先 `git mv` 保留歷史。
- 依賴鏈的判定只沿著專案自有原始碼的 `require`／`import` 遞迴展開，**排除** `node_modules`／`.git`／`.docs`／`dist`／`bin`／`obj` 與其他第三方依賴目錄。
- 主程式入口統一為 `src/index.js`（或 `src/<main>.js`）。

## 明文排除、不搬

以下檔案／目錄即使被主程式引用，仍**留在原位、不移入 `src/`**，因為外部工具依慣例路徑尋找它們，搬走會弄壞 lint／test／build 流程：

| 類型 | 範例 |
| --- | --- |
| 工具設定檔 | `*.config.js`（`eslint.config.js`／`jest.config.js`／`webpack.config.js` 等）、`.*rc.js`（husky／commitlint 等工具設定） |
| 測試目錄 | `test/`、`tests/` |
| 腳本目錄 | `scripts/` |

## 搬移後必須更新的引用

搬移完成後，逐一確認並更新所有引用該檔案舊路徑的地方，確保不破壞既有行為：

- 模組間的 `require`／`import` 相對路徑（包含被排除、留在原位但引用了搬入 `src/` 檔案的檔案，例如 `test/`／`scripts/` 內的引用路徑也要同步更新）。
- `package.json` 的 `main`／`bin`／`scripts`／`exports`（改指向 `src/...`）。
- 指令檔內對主程式路徑的引用：`action.yml` 的 `runs.main`／`runs.entrypoint`、`Dockerfile`、`entrypoint.sh` 等。

若 `src/` 下需要的相依尚未宣告，於對應的 `package.json` 補上；不擅自新增與功能無關的相依。

## 自我檢查

1. `src/` 內的主程式與其依賴鏈完整，沒有漏搬的中間模組（執行時不會因路徑找不到而失敗）。
2. 明文排除清單內的檔案／目錄確實留在原位。
3. 全專案搜尋舊路徑（檔名／相對路徑字串），確認沒有殘留引用。
4. 若環境可執行，實際跑一次主程式或既有測試／lint／build 指令驗證搬移未破壞行為；無法執行時說明原因並標註風險。