clarify-kit

把討論整理成能定案的文件。文件用 TypeScript 寫成 *.doc.ts，clarify-kit build 把它們編譯成帶 formatVersion 的 index.json，clarify-kit check 檢查文件是否合格。

文件源碼

index.ts 所在的目錄是一個 entry。它預設匯出 entry 層欄位 describes（涵蓋哪個產品的哪個版本）與 publish（發布到哪裡）。同目錄與子目錄的 *.doc.ts 依相對路徑排序收進這個 entry，每個檔預設匯出一份文件。子目錄有另一個 index.ts 時，底下的檔案歸那個 entry。

// docs/main/index.ts
import { defineDocs } from 'clarify-kit'

export default defineDocs({
  describes: { 'my-product': '1.2.0' },
  publish: { target: 'npm', name: 'my-product-docs' },
})

// docs/main/use-x.doc.ts
import { decision, section, text } from 'clarify-kit'

export default decision({
  id: 'use-x',
  title: '採用 X',
  status: 'proposed',
  appliesFrom: 'next',
  sections: [section('context', '背景', [text('為什麼要採用 X。')])],
})

.doc.ts 用 Node 內建的型別剝除執行，所以只能用可剝除的 TypeScript 語法，相對匯入要寫 .ts 副檔名。專案目錄的 package.json 要設 "type": "module"，否則 Node 會對每個檔案印出模組類型警告。

設定檔

clarify-kit.config.json 放在專案目錄。沒有設定檔時，工作目錄就是專案目錄，所有設定用預設值。

指令

讀取與影響分析

• readDocs('<套件>/<entry>', { version, include, root }) 讀已安裝的 -docs 套件。沒給 version 或給 head 時讀 head，next 看得到。給版號時只看 since 不晚於它的內容。帶 pending 的內容只在讀 head 且 include 含該標籤時看得到。formatVersion 的 major 不是 1，或 docs 結構不對時丟 DocReadError。
• registerDocImpactExtractor() 向 fact-kit 的 impactOf 註冊抽取器，讓影響分析找得到引用某個 fact 的 *.doc.ts。認得 factBlock() 與 scenario() 的 facts 裡的 id 字串、從 facts 來源匯入的 fact 物件，以及 text() 裡的 fact:<id>。算出來的 id 認不得。匯入套件時不會自動註冊。

check 的錯誤碼

check 用 fact-kit 的 loadInstalledIndex 與 selectFacts 讀 factSources 的 facts 套件，所以 fact-kit 1.x 與 2.0 格式的 index 都讀得懂。pending 的 fact 也算存在。

採納後內文不改

decision 採納後內文不改，record 寫完不改。clarify-kit 不比對內文，也沒有採納指令，所以這兩條規則由 PR 審查把關：審查者看到已採納 decision 或寫完的 record 的內文被改動時，要求作者改開新的 decision（用 supersedes 取代舊的）或新的 record。狀態、版本欄位、since、pending 與 supersedes 不算內文，發版釘版號、功能落地時拿掉 pending 標籤、把 decision 改成已取代都可以直接改。

文件套件慣例

build 出的 index.json 要裝進一個發版單元，名稱是 <product>-docs。它的 package.json 照下面設，文件就會預設發布。

{
  "name": "<product>-docs",
  "exports": {
    "./<entry>/index.json": "./dist/<entry>/index.json"
  },
  "files": ["dist"]
}

• name 用 <product>-docs，<product> 是文件涵蓋的產品。
• 不設 "private"，不設就預設發布。設成 true 會讓這個套件不發布。
• exports 一個 entry 對應一行，讀取端靠 <套件>/<entry>/index.json 找到它。
• files 只列 dist。
• describes 記文件涵蓋的產品版號，這個套件本身是一個發版單元，版號跟著自己的發版流程走。