truepath 是做什麼的?
一個 spec.json 敘述流程(節點、邊緣)、情境(路徑、訊息、標題、輸入)以及判決的來源。build.py 計算判決、佈局圖形、執行檢查,並產生一個離線的 .html 檔案 — 否則什麼都不產生。
spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html (or nothing)
layout.py ──┘ └► fixture.json (--export)
工作流程
-
將最接近的範例複製到主題筆記旁邊(請參閱檔案), 將
spec.json重新命名為<subject>.spec.json。 -
敘述節點和邊緣。每個匯集節點(結果)都有一個
kind; 這些 kind 是唯一的顏色,每個顏色都有一個圖例標籤。 -
選擇判決的來源(見下文):當規則存在於程式碼中時使用
oracle,否則使用 JSport。 -
編寫情境。每個情境宣告其
origin、其inputs、預期的判決欄位expect,以及沿著實際邊緣的steps。 -
建置,然後開啟檔案:
python3 <skill-dir>/scripts/build.py <subject>.spec.json -
閱讀違規情況,修正規格 — 永遠不要修改檢查。
spec.json 建置 sim.html,<subject>.spec.json 建置 <subject>.sim.html;-o 可指定其他檔案名稱。
頁面開啟在第一個分頁,細節面板展開。折疊面板會切換到概覽:繪製完整路徑,一個點在其上循環移動。
判決的來源
| 來源 | 規格鍵 | 使用時機 | 面板中的標記 |
|---|---|---|---|
| Oracle | oracle | 規則存在於儲存庫中 | ✓ code |
| Port | port: "decide.js" | 尚無程式碼、正在討論的規則、無程式碼的流程 | ⚠ ported |
Oracle 協議。 build.py 對 oracle.ref 執行 git archive(永遠不是即時工作目錄:正在開發的分支在建立過程中可能會移動),提取 oracle.paths,連結 oracle.link(通常是 node_modules)並將 oracle.files 複製到其中,然後在 oracle.cwd 中執行 oracle.cmd,同時設定:
TRUEPATH_ORACLE_IN:一個 JSON 陣列,包含每個情境的inputs;TRUEPATH_ORACLE_OUT:要寫入判決 JSON 陣列的位置,順序相同。
當 oracle.repo 是相對路徑時,會從規格所在的資料夾讀取。link 和 files 都以 {snapshot中的路徑: 來源} 的格式寫入:link 是儲存庫中的路徑,files 是規格旁邊的檔案。
判決是一個包含欄位的物件。outcome 是必要的:它指定路徑必須結束的節點,並將情境與邏輯連結起來。basis 選擇性地說明每個欄位是否由真實程式碼計算("code: …")、glue 複製了行為("port: …")或模擬定義了它(任何其他文字,顯示為 ◇ definition)。頁面會在每個面板值的旁邊顯示該標記,前提是其欄位有基礎值,將滑鼠懸停在其上時會顯示完整文字,而 --export 只斷言基礎值為 code 的欄位:在 oracle 下,沒有基礎值的欄位視為 code,在 port 下則視為 ported。一個 oracle 可以混合它們:仍在討論中的規則與程式碼已執行的規則並列。任何執行器都可以使用:專案自己框架的測試檔案、腳本、Java 的 JUnit 測試。頁尾會顯示產生判決的參考名稱和簡短 SHA。
測試檔案 oracle 可以兼作回歸測試套件:當設定 TRUEPATH_ORACLE_IN 時,它會寫入判決,否則它會讀取匯出的 fixture 並斷言它。這樣情境就只存在於規格中一次,並在 CI 中執行。examples/loyalty-tier/src/oracle.js 同時實現了這兩種功能。
規格參考
| 鍵 | 形狀 | 備註 |
|---|---|---|
title, subtitle, source | 字串 | source 會顯示在頁尾;與規格中的所有文字一樣,它們以文字形式顯示,絕不會作為 HTML 讀取 |
lang | en(預設)或 fr | 頁面自身文字的語言;規格的文字以該語言編寫 |
kinds | {id: {label, color}} | 最多 4 個 |
nodes | [{id, label, role?, kind?}] | role: "decision" 標記一個分支點;路徑的起點會被找到並繪製成圓形;匯集節點需要 kind |
edges | [[from, to, label]] | 如果沒有標籤則使用 "" |
panel | [{label, value, at, labels?, digits?, compared?}] | value 讀取 inputs.x 或 verdict.y;從步驟 at 開始顯示(0 是第一步);labels 將值對應到頁面顯示的內容(分別為 "true"、"false"、"null"、"[]");digits 將數值代碼零填充到該長度;compared: true 用於命名配對比較內容(修復、規則)的那一行,該行不參與首次分歧搜尋 |
scenarios | [{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}] | origin: `{kind: real |
pairs | [{before, after, tab, summary}] | 兩個情境 ID,以 − 和 + 的形式並排播放;步驟數相同 |
grid | `{baseline, questions | variants, cases, steps, expect?, show?, hover, summary?}` |
oracle | {repo, ref, paths, link?, files?, cwd, cmd} | 見上文 |
port | 導出 decide(inputs) 的 CommonJS 檔案路徑 | 當沒有 oracle 時使用 |
export | {dir, fixture, assert} | --export <worktree> 將 fixture 寫入那裡 |
比較多個規則:網格
當問題是「每個可能的答案對每個案例做了什麼」時,宣告一個 grid。相對於扁平規則列表,問題更受青睞:讀者一個問題一個問題地決定,因此頁面應該以此方式佈局。
baseline:{id, label, short?, inputs},當前的狀況;questions:[{id, text, options: [{id, label, inputs}], cases, if?}]。cases列出該問題所決定的案例;if: {"Q1": "1A"}表示僅在該答案之後才提出此問題。build.py會為每個一致的答案集(1A+2A、1A+2B、1B)推導出一個變體,合併選項的inputs;cases:[{id, label, summary, origin, inputs, steps?}];label用讀者知道的詞語命名行,而不是案例代碼;steps: 所有儲存格共用,除非某個案例有自己的步驟;expect:{case: {variant: {field: value}}},由 C3 檢查;show: 矩陣儲存格顯示的單一面板行(預設為hover中的第一個);hover: 儲存格在懸停時顯示的行;summary: 矩陣上方的一行文字。
一個扁平的 variants: [{id, label, short?, note?, inputs}] 搭配 baseline 作為 id 仍然有效:矩陣隨後只有一個區段,每個案例與每個變體比較。
頁面開啟在矩陣上:每個問題一個表格,其案例與當前狀況和每個答案進行比較,儲存格的行在與當前狀況不同時標記為 ≠。沒有每個案例的分頁:點擊儲存格會開啟它,顯示當前狀況與該答案的比較,並標記首次分歧。兩個按鈕行 − 和 +,用於在該區段的答案之間選擇任一側(1A 旁邊是 1B,而不僅僅是在當前狀況旁邊),每個按鈕以其問題名稱命名;← matrix 返回。在面板中,一個帶有 "value": "answer" 和 "compared": true 的行會命名所播放的答案。
步驟範本。 message、caption 和 hop 可以引用 {inputs.x} 或 {verdict.y}:它們在邏輯執行後被填充,格式與讀取相同路徑的面板行相同。跳轉到 {verdict.outcome} 可以讓一個步驟列表服務於每個規則。
檢查
| ID | 拒絕情況 |
|---|---|
| C1 | 步驟的 hop 不是一條邊 |
| C2 | 路徑中斷、不是從源節點開始或沒有步驟 |
| C3 | expect 欄位與邏輯矛盾 |
| C4 | 路徑結束在邏輯的 outcome 之外,或邏輯沒有給出 outcome |
| C5 | outcome 沒有 kind、kind 沒有圖例、超過 4 個 kind |
| C6 | 標籤寬度超出其框(13px monospace) |
| C7 | 情境沒有 origin 來說明是 real 還是 illustrative,以及來自何處 |
| C8 | 配對的情境無法一起進行,或未知 |
| C9 | 面板行讀取了情境缺少的欄位 |
| C10 | 矩陣儲存格命名的面板行不存在 |
| C11 | 顯示在問題下的案例,其儲存格仍依賴於另一個問題 |
| C12 | 案例不在任何矩陣區段中,或區段命名了未知案例 |
| C13 | 面板行設定在情境沒有的步驟出現 |
C3 和 C4 是重點:一個說程式碼不會做的事情的情境無法發布。C6 保護的是佈局而不是規格:框的大小是根據其標籤調整的,因此只有在 layout.py 停止這樣做時才會觸發。透過在 tests/ 中破壞一次其輸入來證明新檢查的有效性。每個檢查都是 build.py 中的一個函式,列在 CHECKS 下,使用此表格中的 ID。
建置無法讀取的規格(缺少鍵、邊連接到未知節點、port 拋出異常)會以相同方式拒絕,使用簡單明瞭的文字,在檢查執行之前。
設計規則
- 每個圖表只有一個移動元素:一個單一的點,恆定速度,一次移動一個 hop。
- 並排的兩個圖表同步移動。
- 已走過的邊緣是實線,未走過的邊緣是虛線和灰色;路徑外的節點淡出。
- 顏色僅編碼結果的 kind。在配對中,首次分歧(面板值不同的第一步)以琥珀色輪廓標記,並在兩側標記
≠,面板顯示−/+列。 - 僅在沒有實際案例達到該結果時使用說明性情境;說明實際案例的來源(工單、記錄、度量、日期)。
- 網格每個儲存格顯示一個欄位;每個儲存格三個欄位使矩陣難以閱讀。
- 預設為淺色主題,在
prefers-color-scheme下為深色;無網路字型,因此檔案可以離線工作。
檔案
| 路徑 | 角色 |
|---|---|
scripts/build.py | 讀取規格、獲取判決、執行檢查、寫入頁面和匯出 |
scripts/runtime.html | 頁面;build.py 將要顯示的內容(已格式化)提供給它,而不提供規格的任何其他內容 |
scripts/layout.py | 分層佈局:框的大小根據其標籤調整,正交邊緣 |
examples/refund-window/ | 一個 JS port 和一個之前/之後配對 |
examples/free-shipping/ | 一個網格:兩個開放性問題,每個問題根據其變更的案例進行決定 |
examples/loyalty-tier/ | 一個資料夾自身 src/ 的 oracle、其 glue 以及 --export 寫入的 fixture |
生成的檔案(.truepath/,其中存放 oracle 的快照,以及規格旁邊的 *.html)是建置輸出。port 範例保留其 sim.html,以便無需執行即可查看技能。loyalty-tier 不保留任何內容:其頁尾顯示產生判決的提交名稱,因此頁面會隨每次提交而變化,並且它只在包含它的 git 儲存庫內建置。
限制
- 一種圖表類型:流程圖。未建置序列圖和架構圖。
C6在 macOS(ui-monospace)上測量;較窄的 Windows 字型只會增加間距。- 步驟是宣告的,而不是從邏輯推導出來的:C3 和 C4 捕獲錯誤的結果,而不是錯誤的中間訊息。