issue-map 0.4.0 → 0.5.0

package/README.ja.md

@@ -57,13 +57,13 @@ CLI 側（生成メッセージ、エラー）は英語のみです。
 
 ## 設定
 
-すべて既定値があり、何も設定しなくても動きます。既定値は `scripts/issue-map.ts` の `CONFIG` に
+すべて既定値があり、何も設定しなくても動きます。既定値は `src/issue-map.ts` の `CONFIG` に
 あります。
 
 | 環境変数                   | 既定                              | 意味                                                       |
 | -------------------------- | --------------------------------- | ---------------------------------------------------------- |
 | `GH_REPO`                  | cwd の git から推測               | 別の repo を描くときに設定（`gh` 自身の変数。fork も同様） |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | サブチケットが本文で親を指す見出し                         |
+| `ISSUE_MAP_PARENT_HEADING` | 未設定（本文は取得しない）        | サブチケットが本文で親を指す見出し。設定すると本文を読む   |
 | `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info`         | 未評価で、まだ誰にも渡せない                               |
 | `ISSUE_MAP_LABELS_READY`   | `ready-for-agent,ready-for-human` | 評価済み・着手可                                           |
 | `ISSUE_MAP_LABELS_ACTIVE`  | `in-progress`                     | 誰かが対応中（assignee がなくてもよい）                    |
@@ -82,6 +82,9 @@ CLI 側（生成メッセージ、エラー）は英語のみです。
 - **コマンド名。** `/implement` と `/triage` は向こうの [`implement`](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement) と
   [`triage`](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage) skill です。対象 repo に実在するものを指すようにしてください。さもないと、
   存在しないものを走らせろとマップが指示します。
+- **本文の慣習はオプトイン。** 本文は GitHub のレスポンスの 9 割以上を占めるのに、正規表現
+  ひとつを通すだけで、ページの他のどこでも使われません。そのため `ISSUE_MAP_PARENT_HEADING`
+  を設定したときだけ本文を取得します。ネイティブ sub-issue は設定不要で、常に優先されます。
 - **クローズ済みの兄弟にはネイティブ sub-issue が要る。** マップが問い合わせるクローズ済みチケット
   は、open なチケットがまだ指しているものだけで、子チケットはネイティブの sub-issue 関係から取り
   ます。`## Parent` の本文慣例を使う repo ではグループ内の**クローズ済み**の子が出てこず、進捗が
@@ -95,15 +98,15 @@ CLI 側（生成メッセージ、エラー）は英語のみです。
 
 ## ファイル
 
-| ファイル                     | 責務                                                                   |
-| ---------------------------- | ---------------------------------------------------------------------- |
-| `scripts/issue-map.ts`       | スナップショット取得、状態と次の一手の導出、HTML 生成。設定は `CONFIG` |
-| `scripts/issue-map-model.ts` | 純粋なデータモデル：グルーピング、クリティカルパス、レイアウト         |
-| `scripts/issue-map-i18n.ts`  | 4 言語の文言と引き当て                                                 |
-| `scripts/issue-map-page.ts`  | ブラウザ側のコード。ビルド時に HTML へバンドルされる                   |
-| `scripts/issue-map.html`     | テンプレート。2 つのプレースホルダが埋められる                         |
-| `scripts/issue-map-serve.ts` | ローカル server。リクエストごとに取り直す                              |
-| `scripts/mutate.ts`          | ミューテーションテスト：1 行を壊してテストが赤くなるか見る             |
+| ファイル                 | 責務                                                                   |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `src/issue-map.ts`       | スナップショット取得、状態と次の一手の導出、HTML 生成。設定は `CONFIG` |
+| `src/issue-map-model.ts` | 純粋なデータモデル：グルーピング、クリティカルパス、レイアウト         |
+| `src/issue-map-i18n.ts`  | 4 言語の文言と引き当て                                                 |
+| `src/issue-map-page.ts`  | ブラウザ側のコード。ビルド時に HTML へバンドルされる                   |
+| `src/issue-map.html`     | テンプレート。2 つのプレースホルダが埋められる                         |
+| `src/issue-map-serve.ts` | ローカル server。リクエストごとに取り直す                              |
+| `tools/mutate.ts`        | ミューテーションテスト：1 行を壊してテストが赤くなるか見る             |
 
 ## この repo で開発する
 
@@ -123,10 +126,10 @@ bun test                  # 純粋なモデル層
 製品コードに戻し、赤くなることを確かめます：
 
 ```bash
-bun run mutate scripts/issue-map-model.ts tests/issue-map-layout.test.ts
+bun run mutate src/issue-map-model.ts tests/issue-map-layout.test.ts
 ```
 
-**`scripts/issue-map-i18n.ts` を触るとき。** `EN` が原稿であり、キーの定義場所です。3 つの翻訳の型
+**`src/issue-map-i18n.ts` を触るとき。** `EN` が原稿であり、キーの定義場所です。3 つの翻訳の型
 はそこから導かれるので、キーや `{n}` の差し込み名が 1 つ欠けると `bun run typecheck` が赤くなります。
 英語で単複を分けるキーは `{ one, other }`、中国語と日本語は 1 本の文字列で構いません。モデル側は文
 を組み立てません——`nextStep` は `{ kind: 'waitChildren', count: 2 }` のような構造化された値で、

package/README.md

@@ -56,12 +56,12 @@ CLI output (build messages, errors) is English only.
 ## Configuration
 
 Everything has a default — it runs with nothing set. The defaults live in `CONFIG` in
-`scripts/issue-map.ts`.
+`src/issue-map.ts`.
 
 | Environment variable       | Default                           | Meaning                                                                        |
 | -------------------------- | --------------------------------- | ------------------------------------------------------------------------------ |
 | `GH_REPO`                  | inferred from the git in cwd      | Map another repo (`gh`'s own variable; forks and multiple remotes are its job) |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | Body heading under which a sub-issue points at its parent                      |
+| `ISSUE_MAP_PARENT_HEADING` | unset (bodies are not fetched)    | Body heading under which a sub-issue points at its parent. Set it to opt in    |
 | `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info`         | Not assessed yet, cannot be handed to anyone                                   |
 | `ISSUE_MAP_LABELS_READY`   | `ready-for-agent,ready-for-human` | Assessed and ready to work on                                                  |
 | `ISSUE_MAP_LABELS_ACTIVE`  | `in-progress`                     | Somebody is on it, with or without an assignee                                 |
@@ -82,6 +82,9 @@ Three worth knowing:
   [`implement`](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement) and
   [`triage`](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage) skills. Point
   them at something that exists in the target repo, or the map tells people to run what isn't there.
+- **The body convention is opt-in.** Issue bodies are over 90% of what the GitHub response
+  weighs, and they feed one regex — nothing else on the page uses them. So they are only fetched
+  when `ISSUE_MAP_PARENT_HEADING` is set. Native sub-issues need no setting and always win.
 - **Closed siblings need native sub-issues.** The map asks GitHub only for the closed issues an
   open one still points at, and children come from the native sub-issue relation. With the
   `## Parent` body convention a group's _closed_ children never appear, so its progress looks
@@ -95,15 +98,15 @@ tree.
 
 ## Files
 
-| File                         | Responsibility                                                           |
-| ---------------------------- | ------------------------------------------------------------------------ |
-| `scripts/issue-map.ts`       | Snapshot, status and next step, produces the HTML. Knobs in its `CONFIG` |
-| `scripts/issue-map-model.ts` | Pure data model: grouping, critical path, layout. Shared by both sides   |
-| `scripts/issue-map-i18n.ts`  | Strings for the four languages, plus the lookup                          |
-| `scripts/issue-map-page.ts`  | Browser-side code, bundled into the HTML at build time                   |
-| `scripts/issue-map.html`     | The template. Two placeholder blocks get filled in                       |
-| `scripts/issue-map-serve.ts` | Local server, re-fetches on every request                                |
-| `scripts/mutate.ts`          | Mutation testing: break one line, see whether a test goes red            |
+| File                     | Responsibility                                                           |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `src/issue-map.ts`       | Snapshot, status and next step, produces the HTML. Knobs in its `CONFIG` |
+| `src/issue-map-model.ts` | Pure data model: grouping, critical path, layout. Shared by both sides   |
+| `src/issue-map-i18n.ts`  | Strings for the four languages, plus the lookup                          |
+| `src/issue-map-page.ts`  | Browser-side code, bundled into the HTML at build time                   |
+| `src/issue-map.html`     | The template. Two placeholder blocks get filled in                       |
+| `src/issue-map-serve.ts` | Local server, re-fetches on every request                                |
+| `tools/mutate.ts`        | Mutation testing: break one line, see whether a test goes red            |
 
 ## Developing in this repo
 
@@ -123,10 +126,10 @@ shape, spacing) are deliberately not asserted. A new guard test has to be verifi
 the defect it claims to catch back into the product code and confirm it goes red:
 
 ```bash
-bun run mutate scripts/issue-map-model.ts tests/issue-map-layout.test.ts
+bun run mutate src/issue-map-model.ts tests/issue-map-layout.test.ts
 ```
 
-**Adding to `scripts/issue-map-i18n.ts`.** `EN` is the original and defines the keys; the three
+**Adding to `src/issue-map-i18n.ts`.** `EN` is the original and defines the keys; the three
 translations are typed from it, so a missing key or a missing `{n}` placeholder turns
 `bun run typecheck` red. Keys needing English plurals are written `{ one, other }`; Chinese and
 Japanese take a single string. The model never builds sentences — `nextStep` is a structured value

package/README.zh-CN.md

@@ -54,12 +54,12 @@ CLI 那一侧（产文件消息、错误）只有英文。
 
 ## 配置
 
-全部有默认值，一个都不设也跑得起来。默认值长在 `scripts/issue-map.ts` 的 `CONFIG`。
+全部有默认值，一个都不设也跑得起来。默认值长在 `src/issue-map.ts` 的 `CONFIG`。
 
 | 环境变量                   | 默认                              | 意思                                                   |
 | -------------------------- | --------------------------------- | ------------------------------------------------------ |
 | `GH_REPO`                  | 从 cwd 的 git 推断                | 要画别的 repo 时设它（`gh` 自己的变量，fork 也交给它） |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | 子票在正文指向母票的段落标题                           |
+| `ISSUE_MAP_PARENT_HEADING` | 未设（不抓正文）                  | 子票在正文指向母票的段落标题。设了才会读正文           |
 | `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info`         | 还没评估完，不能交给谁做                               |
 | `ISSUE_MAP_LABELS_READY`   | `ready-for-agent,ready-for-human` | 评估完、可以动工                                       |
 | `ISSUE_MAP_LABELS_ACTIVE`  | `in-progress`                     | 有人在做，不必有 assignee                              |
@@ -77,6 +77,9 @@ CLI 那一侧（产文件消息、错误）只有英文。
   做」这个标签。）
 - **指令名。** `/implement`、`/triage` 就是那边的 [`implement`](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement) 与
   [`triage`](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage) skill。要指向目标 repo 真的有的东西，不然图上会叫人跑不存在的。
+- **正文惯例要明讲才生效。** 正文占了 GitHub 响应九成以上的重量，而它只喂一条 regex，页面上
+  没有别的地方用得到。所以只有设了 `ISSUE_MAP_PARENT_HEADING` 才会去抓正文。原生 sub-issue
+  不必设置，而且一律优先。
 - **已完成的兄弟票要靠原生 sub-issue。** 地图只跟 GitHub 要 open 票还牵着的 closed 票，而子票是从
   原生的 sub-issue 关系拿的。用 `## Parent` 正文惯例的 repo 看不到一组里**已完成**的子票，那一组的
   进度会比实际少。把子票在票页的 Sub-issues 关联上去一次就会回来；正文惯例可以留着，原生的本来
@@ -88,15 +91,15 @@ CLI 那一侧（产文件消息、错误）只有英文。
 
 ## 文件
 
-| 文件                         | 职责                                                     |
-| ---------------------------- | -------------------------------------------------------- |
-| `scripts/issue-map.ts`       | 抓快照、算状态与下一步、产出 HTML。配置在里面的 `CONFIG` |
-| `scripts/issue-map-model.ts` | 纯数据模型：分组、关键路径、排版。前后端共用             |
-| `scripts/issue-map-i18n.ts`  | 四种语言的文案与查表                                     |
-| `scripts/issue-map-page.ts`  | 浏览器端代码，构建时被打包进 HTML                        |
-| `scripts/issue-map.html`     | 模板。两个占位区块会被填入                               |
-| `scripts/issue-map-serve.ts` | 本机 server，每个请求重抓一次                            |
-| `scripts/mutate.ts`          | 变异测试：改坏一行看测试会不会红                         |
+| 文件                     | 职责                                                     |
+| ------------------------ | -------------------------------------------------------- |
+| `src/issue-map.ts`       | 抓快照、算状态与下一步、产出 HTML。配置在里面的 `CONFIG` |
+| `src/issue-map-model.ts` | 纯数据模型：分组、关键路径、排版。前后端共用             |
+| `src/issue-map-i18n.ts`  | 四种语言的文案与查表                                     |
+| `src/issue-map-page.ts`  | 浏览器端代码，构建时被打包进 HTML                        |
+| `src/issue-map.html`     | 模板。两个占位区块会被填入                               |
+| `src/issue-map-serve.ts` | 本机 server，每个请求重抓一次                            |
+| `tools/mutate.ts`        | 变异测试：改坏一行看测试会不会红                         |
 
 ## 在这个 repo 里开发
 
@@ -114,10 +117,10 @@ bun test                  # 纯模型那一层
 要走反向验证——把它宣称要挡的缺陷放回产品代码，确认它会红：
 
 ```bash
-bun run mutate scripts/issue-map-model.ts tests/issue-map-layout.test.ts
+bun run mutate src/issue-map-model.ts tests/issue-map-layout.test.ts
 ```
 
-**要动 `scripts/issue-map-i18n.ts`。** `EN` 是原稿，也是键的定义处；三份翻译的类型由它推导，少一个
+**要动 `src/issue-map-i18n.ts`。** `EN` 是原稿，也是键的定义处；三份翻译的类型由它推导，少一个
 键或少一个 `{n}` 代入名，`bun run typecheck` 就会红。英文要分单复数的键写成 `{ one, other }`，中日
 文写一句字符串就好。模型那一侧不算句子——`nextStep` 是 `{ kind: 'waitChildren', count: 2 }` 这种结构
 化的值，话在这里才组出来。

package/README.zh-TW.md

@@ -54,12 +54,12 @@ CLI 那一側（產檔訊息、錯誤）只有英文。
 
 ## 設定
 
-全部有預設值，一個都不設也跑得起來。預設值長在 `scripts/issue-map.ts` 的 `CONFIG`。
+全部有預設值，一個都不設也跑得起來。預設值長在 `src/issue-map.ts` 的 `CONFIG`。
 
 | 環境變數                   | 預設                              | 意思                                                   |
 | -------------------------- | --------------------------------- | ------------------------------------------------------ |
 | `GH_REPO`                  | 從 cwd 的 git 推斷                | 要畫別的 repo 時設它（`gh` 自己的變數，fork 也交給它） |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | 子票在內文指向母票的段落標題                           |
+| `ISSUE_MAP_PARENT_HEADING` | 未設（不抓內文）                  | 子票在內文指向母票的段落標題。設了才會讀內文           |
 | `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info`         | 還沒評估完，不能交給誰做                               |
 | `ISSUE_MAP_LABELS_READY`   | `ready-for-agent,ready-for-human` | 評估完、可以動工                                       |
 | `ISSUE_MAP_LABELS_ACTIVE`  | `in-progress`                     | 有人在做，不必有 assignee                              |
@@ -77,6 +77,9 @@ CLI 那一側（產檔訊息、錯誤）只有英文。
   做」這個標籤。）
 - **指令名。** `/implement`、`/triage` 就是那邊的 [`implement`](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement) 與
   [`triage`](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage) skill。要指向目標 repo 真的有的東西，不然圖上會叫人跑不存在的。
+- **內文慣例要明講才生效。** 內文佔了 GitHub 回應九成以上的重量，而它只餵一條 regex，頁面上
+  沒有別的地方用得到。所以只有設了 `ISSUE_MAP_PARENT_HEADING` 才會去抓內文。原生 sub-issue
+  不必設定，而且一律優先。
 - **已完成的兄弟票要靠原生 sub-issue。** 地圖只跟 GitHub 要 open 票還牽著的 closed 票，而子票是從
   原生的 sub-issue 關係拿的。用 `## Parent` 內文慣例的 repo 看不到一組裡**已完成**的子票，那一組的
   進度會比實際少。把子票在票頁的 Sub-issues 關聯上去一次就會回來；內文慣例可以留著，原生的本來
@@ -88,15 +91,15 @@ CLI 那一側（產檔訊息、錯誤）只有英文。
 
 ## 檔案
 
-| 檔案                         | 責任                                                     |
-| ---------------------------- | -------------------------------------------------------- |
-| `scripts/issue-map.ts`       | 抓快照、算狀態與下一步、產出 HTML。設定在裡面的 `CONFIG` |
-| `scripts/issue-map-model.ts` | 純資料模型：分組、關鍵路徑、排版。前後端共用             |
-| `scripts/issue-map-i18n.ts`  | 四種語言的文案與查表                                     |
-| `scripts/issue-map-page.ts`  | 瀏覽器端程式碼，建置時被打包進 HTML                      |
-| `scripts/issue-map.html`     | 樣板。兩個佔位區塊會被填入                               |
-| `scripts/issue-map-serve.ts` | 本機 server，每個請求重抓一次                            |
-| `scripts/mutate.ts`          | 突變測試：改壞一行看測試會不會紅                         |
+| 檔案                     | 責任                                                     |
+| ------------------------ | -------------------------------------------------------- |
+| `src/issue-map.ts`       | 抓快照、算狀態與下一步、產出 HTML。設定在裡面的 `CONFIG` |
+| `src/issue-map-model.ts` | 純資料模型：分組、關鍵路徑、排版。前後端共用             |
+| `src/issue-map-i18n.ts`  | 四種語言的文案與查表                                     |
+| `src/issue-map-page.ts`  | 瀏覽器端程式碼，建置時被打包進 HTML                      |
+| `src/issue-map.html`     | 樣板。兩個佔位區塊會被填入                               |
+| `src/issue-map-serve.ts` | 本機 server，每個請求重抓一次                            |
+| `tools/mutate.ts`        | 突變測試：改壞一行看測試會不會紅                         |
 
 ## 在這個 repo 裡開發
 
@@ -114,10 +117,10 @@ bun test                  # 純模型那一層
 要走反向驗證——把它宣稱要擋的缺陷放回產品碼，確認它會紅：
 
 ```bash
-bun run mutate scripts/issue-map-model.ts tests/issue-map-layout.test.ts
+bun run mutate src/issue-map-model.ts tests/issue-map-layout.test.ts
 ```
 
-**要動 `scripts/issue-map-i18n.ts`。** `EN` 是原稿，也是鍵的定義處；三份翻譯的型別由它推導，少一個
+**要動 `src/issue-map-i18n.ts`。** `EN` 是原稿，也是鍵的定義處；三份翻譯的型別由它推導，少一個
 鍵或少一個 `{n}` 代入名，`bun run typecheck` 就會紅。英文要分單複數的鍵寫成 `{ one, other }`，中日
 文寫一句字串就好。模型那一側不算句子——`nextStep` 是 `{ kind: 'waitChildren', count: 2 }` 這種結構
 化的值，話在這裡才組出來。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issue-map",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Draws the blocking relationships between your GitHub Issues as a one-page dev map: which issues can be picked up now, which are waiting on what, and where the critical path runs.",
   "keywords": [
     "bun",
@@ -15,27 +15,21 @@
     "url": "git+https://github.com/gunter1020/issue-map.git"
   },
   "bin": {
-    "issue-map": "./scripts/issue-map-serve.ts",
-    "issue-map-build": "./scripts/issue-map.ts"
+    "issue-map": "./src/issue-map-serve.ts",
+    "issue-map-build": "./src/issue-map.ts"
   },
   "files": [
     "README.zh-TW.md",
     "README.zh-CN.md",
     "README.ja.md",
-    "scripts/issue-map.ts",
-    "scripts/issue-map-i18n.ts",
-    "scripts/issue-map-model.ts",
-    "scripts/issue-map-page.ts",
-    "scripts/issue-map-view.ts",
-    "scripts/issue-map-serve.ts",
-    "scripts/issue-map.html"
+    "src"
   ],
   "type": "module",
   "scripts": {
-    "issue-map": "bun run scripts/issue-map.ts",
-    "issue-map:serve": "ISSUE_MAP_OPEN=0 bun --watch scripts/issue-map-serve.ts",
+    "issue-map": "bun run src/issue-map.ts",
+    "issue-map:serve": "ISSUE_MAP_OPEN=0 bun --watch src/issue-map-serve.ts",
     "typecheck": "tsc --noEmit",
-    "mutate": "bun run scripts/mutate.ts",
+    "mutate": "bun run tools/mutate.ts",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "lint": "oxlint .",

package/{scripts → src}/issue-map-model.ts

@@ -72,14 +72,36 @@ export type Group = {
 export type Snapshot = {
   readonly generatedAt: string
   readonly repo: string
-  /** 這一次實際生效的標籤字彙。圖例照它寫，不然改了設定圖例就會說謊。 */
-  readonly labels: { readonly ready: readonly string[]; readonly unready: readonly string[] }
+  /**
+   * 這一次實際生效的標籤字彙與閘門。圖例照它寫，不然改了設定圖例就會說謊。
+   *
+   * `gated` 是**狀態機當下真的有沒有把這些標籤當閘門**。字彙本身一律有預設值、永遠非空，拿
+   * 它的長度去推閘門開著沒有的話，repo 還沒導入標籤時票會判成可動，頁尾卻說沒掛標籤等於未定案。
+   */
+  readonly labels: {
+    readonly ready: readonly string[]
+    readonly unready: readonly string[]
+    readonly gated: boolean
+  }
   readonly groups: readonly Group[]
   /** 最長的一條依序未完成鏈，也就是最少要幾輪。 */
   readonly criticalPath: number
   readonly issues: readonly MapIssue[]
 }
 
+/**
+ * 什麼都還沒有的快照。畫面那一側解析行內 JSON 時用它補齊缺的欄位——**缺欄位只在那一個邊界
+ * 成立**，收在這裡的話下游拿到的一律是完整的 `Snapshot`，不必每個欄位各自決定「缺了算什麼」。
+ */
+export const EMPTY_SNAPSHOT: Snapshot = {
+  generatedAt: '',
+  repo: '',
+  labels: { ready: [], unready: [], gated: false },
+  groups: [],
+  criticalPath: 0,
+  issues: [],
+}
+
 /**
  * 分群：同一張主票底下的子票一群；沒有主票但跟別人有前置關係的合成一群；完全孤立的合成一群。
  * 一張圖畫一群。
@@ -173,10 +195,8 @@ export type Edge = { readonly from: number; readonly to: number }
 export type Layout = {
   /** 每一條線由前到後的站。只有一站的線不標線名。 */
   readonly tracks: readonly (readonly number[])[]
-  /** 孤立的票排成幾列月台。 */
+  /** 孤立的票排成幾列月台。月台接在最後一條線下面，起點就是 `tracks.length`。 */
   readonly islandRows: number
-  /** 月台從第幾列開始。 */
-  readonly islandFrom: number
   readonly xy: ReadonlyMap<number, Point>
   readonly edges: readonly Edge[]
   readonly width: number
@@ -190,6 +210,21 @@ const ISLAND_MIN_PER_ROW = 4
  */
 const ISLAND_MAX_PER_ROW = 12
 
+/**
+ * 一組票內部的阻擋邊。**什麼算一條邊只有這一份定義**——排版照它畫線，頁面也照它判斷這一組畫
+ * 出來到底有沒有線；各算一次的話會出現「說要畫圖、畫出來卻沒有線」。
+ */
+export function edgesWithin(members: readonly MapIssue[]): Edge[] {
+  const inGroup = new Set(members.map((m) => m.number))
+  const edges: Edge[] = []
+  for (const m of members) {
+    for (const from of m.blockedBy) {
+      if (inGroup.has(from)) edges.push({ from, to: m.number })
+    }
+  }
+  return edges
+}
+
 /**
  * 把一組票排成線路圖。
  *
@@ -201,19 +236,12 @@ const ISLAND_MAX_PER_ROW = 12
  * 會變成十二條單站線。
  */
 export function layoutOf(members: readonly MapIssue[]): Layout {
-  const inGroup = new Set(members.map((m) => m.number))
-  const preds = new Map(
-    members.map((m) => [m.number, m.blockedBy.filter((n) => inGroup.has(n))] as const),
-  )
+  const edges = edgesWithin(members)
+  const preds = new Map<number, number[]>(members.map((m) => [m.number, []]))
+  for (const edge of edges) preds.get(edge.to)?.push(edge.from)
   const predsOf = (n: number): readonly number[] => preds.get(n) ?? []
 
-  const hasEdge = new Set<number>()
-  for (const m of members) {
-    for (const from of predsOf(m.number)) {
-      hasEdge.add(m.number)
-      hasEdge.add(from)
-    }
-  }
+  const hasEdge = new Set(edges.flatMap((edge) => [edge.from, edge.to]))
   const wired = members.filter((m) => hasEdge.has(m.number))
   const island = members.filter((m) => !hasEdge.has(m.number))
 
@@ -257,15 +285,9 @@ export function layoutOf(members: readonly MapIssue[]): Layout {
   })
   const islandRows = Math.ceil(island.length / perRow)
 
-  const edges: Edge[] = []
-  for (const m of members) {
-    for (const from of predsOf(m.number)) edges.push({ from, to: m.number })
-  }
-
   return {
     tracks,
     islandRows,
-    islandFrom: tracks.length,
     xy,
     edges,
     width: MAP.gutter + perRow * MAP.step + MAP.rightPad,

package/{scripts → src}/issue-map-page.ts

@@ -8,18 +8,9 @@
  * 這裡剩下的是 DOM 與事件：讀寫 localStorage 的兩個偏好（語言、收合）、事件代理、選取狀態。
  */
 
-import {
-  DEFAULT_LOCALE,
-  isLocale,
-  type Locale,
-  LOCALE_NAME,
-  LOCALES,
-  locale,
-  setLocale,
-  t,
-} from './issue-map-i18n.ts'
-import { type Snapshot } from './issue-map-model.ts'
-import { esc, type Filter, viewOf } from './issue-map-view.ts'
+import { DEFAULT_LOCALE, isLocale, type Locale, locale, setLocale, t } from './issue-map-i18n.ts'
+import { EMPTY_SNAPSHOT, type Snapshot } from './issue-map-model.ts'
+import { type Filter, langOptionsHTML, viewOf } from './issue-map-view.ts'
 
 /** 樣板保證這些節點存在。找不到就是樣板被改壞了，早點喊比畫出半張圖好。 */
 function pick(id: string): HTMLElement {
@@ -28,9 +19,18 @@ function pick(id: string): HTMLElement {
   return node
 }
 
-const snapshot = JSON.parse(pick('issue-map-data').textContent || '{}') as Partial<Snapshot>
+/**
+ * 行內 JSON 是整份快照唯一可能殘缺的地方（沒有資料、被截斷）。缺的欄位在這裡一次補齊，下游
+ * 拿到的一律是完整的 `Snapshot`——不然每個用到快照的地方都要自己決定「缺了算什麼」。
+ */
+function readSnapshot(): Snapshot {
+  const parsed = JSON.parse(pick('issue-map-data').textContent || '{}') as Partial<Snapshot>
+  return { ...EMPTY_SNAPSHOT, ...parsed }
+}
+
+const snapshot = readSnapshot()
 const view = viewOf(snapshot)
-const repo = snapshot.repo ?? ''
+const repo = snapshot.repo
 
 const detail = pick('detail')
 const rowsEl = pick('rows')
@@ -40,6 +40,28 @@ const tabsEl = pick('tabs')
 let selected: number | null = null
 let filter: Filter = 'all'
 
+// ---- 偏好 ----
+
+/**
+ * 偏好記在瀏覽器。**讀不到、寫不進都不是錯誤**：無痕視窗與擋掉儲存的設定裡 `localStorage` 會
+ * 直接丟例外，那時偏好只在這一次有效，畫面照樣是完整的——所以存取一律收在這兩支裡。
+ */
+function readStored(key: string): string | null {
+  try {
+    return localStorage.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+function writeStored(key: string, value: string): void {
+  try {
+    localStorage.setItem(key, value)
+  } catch {
+    // 存不了就只在這一次有效。
+  }
+}
+
 // ---- 語言 ----
 
 /**
@@ -51,31 +73,20 @@ let filter: Filter = 'all'
 const LOCALE_KEY = 'issue-map:locale'
 
 function readLocale(): Locale {
-  try {
-    const saved = localStorage.getItem(LOCALE_KEY)
-    if (isLocale(saved)) return saved
-  } catch {
-    // 讀不到就用預設，畫面照樣是完整的。
-  }
-  return DEFAULT_LOCALE
+  const saved = readStored(LOCALE_KEY)
+  return isLocale(saved) ? saved : DEFAULT_LOCALE
 }
 
 /** 語言選單只做一次；換語言是整頁重畫，選單自己不重建，不然焦點會掉。 */
 function mountLangPicker(): void {
   const picker = pick('lang')
   if (!(picker instanceof HTMLSelectElement)) throw new Error('#lang 不是 select')
-  picker.innerHTML = LOCALES.map(
-    (option) => `<option value="${option}">${esc(LOCALE_NAME[option])}</option>`,
-  ).join('')
+  picker.innerHTML = langOptionsHTML()
   picker.value = locale()
   picker.addEventListener('change', () => {
     if (!isLocale(picker.value)) return
     setLocale(picker.value)
-    try {
-      localStorage.setItem(LOCALE_KEY, picker.value)
-    } catch {
-      // 存不了就只在這一次有效。
-    }
+    writeStored(LOCALE_KEY, picker.value)
     render()
   })
 }
@@ -90,7 +101,7 @@ const COLLAPSE_KEY = `issue-map:collapsed:${repo}`
 
 function readFolded(): Set<string> {
   try {
-    return new Set(JSON.parse(localStorage.getItem(COLLAPSE_KEY) || '[]') as string[])
+    return new Set(JSON.parse(readStored(COLLAPSE_KEY) || '[]') as string[])
   } catch {
     return new Set()
   }
@@ -102,14 +113,26 @@ function isFolded(parent: number): boolean {
   return folded.has(String(parent))
 }
 
+/**
+ * 掛在某張票底下的東西該不該藏起來。
+ *
+ * 看的是**整條祖先鏈**，不只直屬主票——三層的鏈收起最上面那張時，第三層的 `data-parent` 指的
+ * 是第二層，只比對直屬的話它會單獨留在畫面上。
+ */
+function foldedAnywhere(parent: number): boolean {
+  const seen = new Set<number>()
+  for (let at: number | null = parent; at !== null && !seen.has(at);) {
+    if (isFolded(at)) return true
+    seen.add(at)
+    at = view.issueAt(at)?.parent ?? null
+  }
+  return false
+}
+
 function setFolded(parent: number, shut: boolean): void {
   if (shut) folded.add(String(parent))
   else folded.delete(String(parent))
-  try {
-    localStorage.setItem(COLLAPSE_KEY, JSON.stringify([...folded]))
-  } catch {
-    // 存不了就只在這一次有效，畫面照樣能開合。
-  }
+  writeStored(COLLAPSE_KEY, JSON.stringify([...folded]))
   paintFolded()
 }
 
@@ -119,7 +142,7 @@ function setFolded(parent: number, shut: boolean): void {
  */
 function paintFolded(): void {
   for (const node of document.querySelectorAll<HTMLElement>('[data-parent]')) {
-    node.hidden = isFolded(Number(node.dataset.parent))
+    node.hidden = foldedAnywhere(Number(node.dataset.parent))
   }
   for (const section of document.querySelectorAll<HTMLElement>('section.group[data-fold]')) {
     section.dataset.folded = String(isFolded(Number(section.dataset.fold)))
@@ -370,10 +393,11 @@ function render(): void {
   pick('lede').innerHTML = view.lede()
   pick('stats').innerHTML = view.statsHTML()
 
+  // 三段都是逃脫過的 HTML，跟建置時填進樣板的是同一批字串——用 textContent 塞會把逃脫顯示出來。
   const foot = view.footerHTML()
-  pick('foot-truth').textContent = foot.truth
+  pick('foot-truth').innerHTML = foot.truth
   pick('foot-refresh').innerHTML = foot.refresh
-  pick('foot-config').textContent = foot.config
+  pick('foot-config').innerHTML = foot.config
 
   groupsEl.innerHTML = view.groupsHTML()
   tabsEl.setAttribute('aria-label', t('tabs.aria'))

package/{scripts → src}/issue-map-serve.ts

@@ -43,19 +43,34 @@ function openInBrowser(url: string): void {
   }
 }
 
+/**
+ * 同時抵達的請求共用同一次抓取。
+ *
+ * 一次重新整理按兩下、或開著兩個分頁，本來會各自跑一趟完整的 GitHub 抓取；它們要的是同一刻的
+ * 狀態，讓後到的等前一趟就好。抓完就清掉，所以「每次重新整理都是最新的」沒有變。
+ */
+let inFlight: Promise<string> | null = null
+
 async function page(): Promise<string> {
-  const snapshot = takeSnapshot()
+  const snapshot = await takeSnapshot()
   console.log(describe(snapshot))
   return renderDocument(snapshot)
 }
 
+function pageShared(): Promise<string> {
+  inFlight ??= page().finally(() => {
+    inFlight = null
+  })
+  return inFlight
+}
+
 const server = Bun.serve({
   port: PORT,
   async fetch(request) {
     const { pathname } = new URL(request.url)
     if (pathname !== '/') return new Response(null, { status: 404 })
     try {
-      return new Response(await page(), {
+      return new Response(await pageShared(), {
         headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
       })
     } catch (error) {