fp-layers

依據《Grokking Simplicity》的「分層設計（Stratified Design）」概念打造的程式碼分析 CLI 工具。

掃描 JavaScript / TypeScript 專案，自動：

• 🏷️ 將每個函式標記為 💥 Action（動作） 或 🧮 Calculation（計算/純函式），並實作書中「動作會傳染」的規則
• 📝 在每個檔案旁產生 *.fp.js / *.fp.ts 註記副本（原始檔完全不修改），註記包含判定原因與重構建議
• 📊 產生 fp-report.html 分層報告：金字塔式呼叫圖，動作區在上、計算區在下，一眼看出程式碼的抽象層級是否健康

安裝

在你的專案中安裝（擇一）：

yarn add -D fp-layers
npm  install -D fp-layers
pnpm add -D fp-layers

或從 GitHub 直接安裝：

yarn add -D github:Retsomm/fp-layers

使用

yarn fpl            # 分析當前目錄
yarn fpl src        # 指定資料夾

（npm 使用 npx fpl src、pnpm 使用 pnpm fpl src）

也可以在你專案的 package.json 加入 script，像 vitest 一樣使用：

"scripts": { "fp": "fpl src" }

輸出範例

  cart.js
    💥💥💥💥🧮🧮🧮  （動作 4｜計算 3）→ 已產生 cart.fp.js
    💡 addItem: 把時間當「參數」傳進來（隱性輸入 → 顯性參數）
    💡 calcTotal: 改成「回傳新值」，由呼叫端決定怎麼用（copy-on-write 思維）
──────────────────────────────────────────
✅ 分析完成：1 個檔案｜💥 4 動作｜🧮 3 計算（計算佔比 43%）
📊 分層報告：fp-report.html（用瀏覽器開啟）

建議在你的 .gitignore 加入：

*.fp.js
*.fp.ts
fp-report.html

判定規則（對應書中章節）

| 偵測到 | 判定 | 建議（章節） | |---|---|---| | Date.now()、Math.random() | 💥 隱性輸入 | 改成參數傳入（ch4） | | 修改外部變數、push/屬性賦值 | 💥 寫入共享狀態 | 回傳副本 copy-on-write（ch6） | | fetch、DOM、localStorage | 💥 與外界互動 | 抽出決策為計算，動作留薄薄一層（ch4/18） | | 呼叫了任何 Action | 💥 動作傳染 | 把動作呼叫往外移（ch3） | | 以上皆無 | 🧮 純計算 | 好測試、可重用，多多益善 |

專案架構（本身即分層設計示範）

src/
├── cli.ts               💥 動作層：讀檔、寫檔、印出結果（薄）
├── analyzer/
│   ├── parse.ts         🧮 原始碼 → 函式事實（抽象屏障：隱藏 AST 細節）
│   ├── classify.ts      🧮 事實 → Action/Calculation 判決
│   ├── callGraph.ts     🧮 判決 → 分層呼叫圖
│   └── annotate.ts      🧮 原始碼＋判決 → 註記字串
└── ui/
    └── layerView.ts     🧮 圖資料 → SVG/HTML 字串

所有邏輯都是純計算，cli.ts 只負責 I/O——歡迎閱讀原始碼，每個檔案的開頭註解都標明它對應書中的哪個概念。

開發

git clone https://github.com/Retsomm/fp-layers.git
cd fp-layers
yarn && yarn compile
node out/cli.js sample     # 用內附範例測試

License

MIT