jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
43 lines
3.0 KiB
Markdown
43 lines
3.0 KiB
Markdown
---
|
||
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 指令驗證搬移未破壞行為；無法執行時說明原因並標註風險。
|