npm - issue-map - Versions diffs - 0.3.0 → 0.3.1 - Mend

issue-map 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.ja.md +26 -22
package/README.md +27 -23
package/README.zh-CN.md +17 -19
package/README.zh-TW.md +17 -17
package/package.json +1 -1
package/scripts/issue-map-serve.ts +2 -2
package/scripts/issue-map.ts +177 -54

package/README.ja.md CHANGED Viewed

@@ -74,8 +74,9 @@ bunx -p issue-map@latest issue-map-build out.html
 i18n の層です。スナップショットに文を保存していたら、言語を切り替えるたびに GitHub を取り直す
 ことになります。
-CLI 側（生成メッセージ、エラー）は意図的に中国語のままです。あれはこのツールを開発する人向けで
-あって、ページの一部ではありません。
+CLI 側（生成メッセージ、エラー）は英語のみで、ページの言語設定には従いません。あれは
+`bunx issue-map` の出力であり、コマンドを打った人が読むもので、ページの一部ではありません。
+例外は `scripts/mutate.ts` で、この repo 内部のツールなので中国語のままです。
 ## 前提条件
@@ -90,36 +91,39 @@ CLI 側（生成メッセージ、エラー）は意図的に中国語のまま
 すべて既定値があり、何も設定しなくても動きます。既定値は `scripts/issue-map.ts` の `CONFIG` に
 あります。
-| 環境変数                   | 既定                              | 意味                                                                                   |
-| -------------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
-| `GH_REPO`                  | cwd の git から推測               | 別の repo を描くときに設定（`gh` 自身の変数。fork や複数 remote の判断も任せます）     |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | サブチケットが本文で親を指す見出し。GitHub ネイティブの sub-issue があればそちらを優先 |
-| `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 がなくてもよい）                                    |
-| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | 人がやるもの。次の一手に実装コマンドを出さない                                         |
-| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | 着手できるときにマップが促すコマンド                                                   |
-| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | まだ評価が要るときにマップが促すコマンド                                               |
-| `ISSUE_MAP_PORT`           | `4747`                            | server のポート                                                                        |
-| `ISSUE_MAP_OPEN`           | 有効                              | `0` にするとブラウザを開かない（`bun --watch` の開発モードは既定で無効）               |
-とくに考えておくべきものが 2 つ：
+| 環境変数                   | 既定                              | 意味                                                                                                                                               |
+| -------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GH_REPO`                  | cwd の git から推測               | 別の repo を描くときに設定（`gh` 自身の変数。fork や複数 remote の判断も任せます）                                                                 |
+| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | サブチケットが本文で親を指す見出し。GitHub ネイティブの sub-issue があればそちらを優先。クローズ済みの兄弟が見えるのはネイティブの場合だけ（下記） |
+| `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 がなくてもよい）                                                                                                |
+| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | 人がやるもの。次の一手に実装コマンドを出さない                                                                                                     |
+| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | 着手できるときにマップが促すコマンド                                                                                                               |
+| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | まだ評価が要るときにマップが促すコマンド                                                                                                           |
+| `ISSUE_MAP_PORT`           | `4747`                            | server のポート                                                                                                                                    |
+| `ISSUE_MAP_OPEN`           | 有効                              | `0` にするとブラウザを開かない（`bun --watch` の開発モードは既定で無効）                                                                           |
+とくに考えておくべきものが 3 つ：
 - **ラベルの語彙**：対象 repo がこのセットを使っていないなら、その repo の名前に置き換えてください。
   コード側で検知します——スナップショットに ready／unready のどのラベルも現れないときは triage を
   ゲートにしません。そうしないと全チケットが「未評価」になってしまいます。
 - **コマンド名**：`/implement` と `/triage` は Claude Code の skill です。対象 repo にそれがない
   場合は必ず差し替えてください。さもないと、存在しないものを走らせろとマップが指示します。
+- **クローズ済みの兄弟にはネイティブ sub-issue が要る**：マップが GitHub に問い合わせるクローズ済み
+  チケットは、open なチケットがまだ指しているものだけです——そのブロッカー、その親、そして親の
+  子チケット。子チケットは GitHub ネイティブの sub-issue 関係から取るので、`## Parent` の本文慣例を
+  使う repo ではグループ内の**クローズ済み**の子が出てこず、進捗が実際より少なく見えます。open な
+  チケットは影響を受けません。代わりに repo のクローズ済みチケットを全部走査する手もありますが、
+  古い repo ではわずか数枚のために数十回のリクエストを払うことになります。ネイティブ sub-issue より
+  前に作られたグループなら、子チケットを一度リンクし直す（チケットの Sub-issues）だけでクローズ済みの
+  子が戻ります。本文の慣例は残しておいて構いません——ネイティブのほうが優先されます。
 ## よくある失敗
-- `gh api graphql 失敗：…` — `gh` にログインしていないか、cwd が対象 repo の git ツリーの中に
+- `gh api graphql failed: …` — `gh` にログインしていないか、cwd が対象 repo の git ツリーの中に
   ありません。
-- `open issue 超過 100 張，這支要改成分頁抓` — GraphQL の `first` の上限が 100 です。それ以上の
-  チケットに対応するには `issue-map.ts` の `query()` にページングを足す必要があります。これは設定
-  ではなくコードの変更です。
-（CLI のメッセージは中国語なので、実際に出力される通りに引用しています。）
 ## ファイル

package/README.md CHANGED Viewed

@@ -71,8 +71,9 @@ The model and fetch side **no longer builds sentences**: `nextStep` is a structu
 `{ kind: 'waitChildren', count: 2 }`, and so are group names. The words are assembled in the i18n
 layer. If the snapshot stored sentences, switching language would mean re-fetching from GitHub.
-The CLI side (build messages, errors) is deliberately left in Chinese: that output is for whoever
-develops this tool, not part of the page.
+The CLI side (build messages, errors) is English only and does not follow the page's language
+setting: it is the output of `bunx issue-map`, read by whoever ran the command, not part of the
+page. `scripts/mutate.ts` is the exception — it is an in-repo tool, so it stays Chinese.
 ## Requirements
@@ -87,20 +88,20 @@ develops this tool, not part of the page.
 Everything has a default — it runs with nothing set. The defaults live in `CONFIG` in
 `scripts/issue-map.ts`.
-| Environment variable       | Default                           | Meaning                                                                                                             |
-| -------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `GH_REPO`                  | inferred from the git in cwd      | Set it to map another repo (`gh`'s own variable; forks and multiple remotes are its job too)                        |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | The body heading under which a sub-issue points at its parent. A native GitHub sub-issue relation wins when present |
-| `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info`         | Carrying one means it is not assessed yet and cannot be handed to anyone                                            |
-| `ISSUE_MAP_LABELS_READY`   | `ready-for-agent,ready-for-human` | Only with one of these does an issue count as assessed and ready to work on                                         |
-| `ISSUE_MAP_LABELS_ACTIVE`  | `in-progress`                     | Carrying one means somebody is on it, with or without an assignee                                                   |
-| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | These need a person, so the next step is not an implementation command                                              |
-| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | The command the map tells you to run when an issue is ready                                                         |
-| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | The command the map tells you to run when it still needs assessing                                                  |
-| `ISSUE_MAP_PORT`           | `4747`                            | Port for the server                                                                                                 |
-| `ISSUE_MAP_OPEN`           | on                                | Set `0` to stop opening the browser (the `bun --watch` dev mode has it off)                                         |
-Two worth thinking through:
+| Environment variable       | Default                           | Meaning                                                                                                                                                                      |
+| -------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GH_REPO`                  | inferred from the git in cwd      | Set it to map another repo (`gh`'s own variable; forks and multiple remotes are its job too)                                                                                 |
+| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | The body heading under which a sub-issue points at its parent. A native GitHub sub-issue relation wins when present, and only native ones show _closed_ siblings (see below) |
+| `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info`         | Carrying one means it is not assessed yet and cannot be handed to anyone                                                                                                     |
+| `ISSUE_MAP_LABELS_READY`   | `ready-for-agent,ready-for-human` | Only with one of these does an issue count as assessed and ready to work on                                                                                                  |
+| `ISSUE_MAP_LABELS_ACTIVE`  | `in-progress`                     | Carrying one means somebody is on it, with or without an assignee                                                                                                            |
+| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | These need a person, so the next step is not an implementation command                                                                                                       |
+| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | The command the map tells you to run when an issue is ready                                                                                                                  |
+| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | The command the map tells you to run when it still needs assessing                                                                                                           |
+| `ISSUE_MAP_PORT`           | `4747`                            | Port for the server                                                                                                                                                          |
+| `ISSUE_MAP_OPEN`           | on                                | Set `0` to stop opening the browser (the `bun --watch` dev mode has it off)                                                                                                  |
+Three worth thinking through:
 - **Label vocabulary**: if the target repo does not use this set, replace them with its own names.
   The code detects it — when the snapshot contains none of the ready/unready labels at all, triage
@@ -108,16 +109,19 @@ Two worth thinking through:
 - **Command names**: `/implement` and `/triage` are Claude Code skills. If the target repo has no
   such skills you must change them, or the map will tell people to run something that does not
   exist.
+- **Closed siblings need native sub-issues**: the map asks GitHub only for the closed issues an
+  open one still points at — its blockers, its parent, and that parent's children. Children come
+  from GitHub's native sub-issue relation, so with the `## Parent` body convention a group's
+  _closed_ children never appear and its progress looks smaller than it is. Open issues are not
+  affected. The alternative is scanning every closed issue in the repo, which on an old repo means
+  dozens of requests to find a handful of issues. If a group predates native sub-issues, linking
+  its children once (the issue's Sub-issues panel) brings the closed ones back; the body convention
+  can stay, the native relation wins anyway.
 ## When it fails
-- `gh api graphql 失敗：…` — `gh` is not logged in, or your cwd is not inside the target repo's git
-  tree.
-- `open issue 超過 100 張，這支要改成分頁抓` — 100 is the hard cap on GraphQL's `first`. Supporting
-  more issues means adding pagination to `query()` in `issue-map.ts`; that is a code change, not
-  configuration.
-(CLI messages are in Chinese, so they are quoted here as they actually appear.)
+- `gh api graphql failed: …` — `gh` is not logged in, or your cwd is not inside the target repo's
+  git tree.
 ## Files

package/README.zh-CN.md CHANGED Viewed

@@ -61,7 +61,7 @@ bunx -p issue-map@latest issue-map-build out.html
 的值，分组名字也一样，话在 i18n 那一层才组出来。快照里存中文句子的话，换一次语言就得重抓一次
 GitHub。
-CLI 那一侧（产文件消息、错误）刻意留中文：那是给开发者看的，不是页面的一部分。
+CLI 那一侧（产文件消息、错误）只有英文，也不跟着页面的语言走：那是 `bunx issue-map` 的输出，给下指令的人看的，不是页面的一部分。例外是 `scripts/mutate.ts`——它是这个 repo 内部的工具，留中文。
 ## 前置条件
@@ -74,30 +74,28 @@ CLI 那一侧（产文件消息、错误）刻意留中文：那是给开发者
 全部有默认值，一个都不设也跑得起来。默认值长在 `scripts/issue-map.ts` 的 `CONFIG`。
-| 环境变量                   | 默认                              | 意思                                                               |
-| -------------------------- | --------------------------------- | ------------------------------------------------------------------ |
-| `GH_REPO`                  | 从 cwd 的 git 推断                | 要画别的 repo 时设它（`gh` 自己的变量，fork 与多 remote 也交给它） |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | 子票在正文指向母票的段落标题。GitHub 原生 sub-issue 有值时优先     |
-| `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                                  |
-| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | 这些要人做，下一步不写实作指令                                     |
-| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | 可以动工时图上叫人跑的指令                                         |
-| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | 还要评估时图上叫人跑的指令                                         |
-| `ISSUE_MAP_PORT`           | `4747`                            | server 的端口                                                      |
-| `ISSUE_MAP_OPEN`           | 开                                | 设 `0` 就不自动开浏览器（`bun --watch` 的开发模式默认关掉）        |
-两个要特别想过的：
+| 环境变量                   | 默认                              | 意思                                                                                                       |
+| -------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `GH_REPO`                  | 从 cwd 的 git 推断                | 要画别的 repo 时设它（`gh` 自己的变量，fork 与多 remote 也交给它）                                         |
+| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | 子票在正文指向母票的段落标题。GitHub 原生 sub-issue 有值时优先，而且只有原生的看得到已完成的兄弟票（见下） |
+| `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                                                                          |
+| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | 这些要人做，下一步不写实作指令                                                                             |
+| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | 可以动工时图上叫人跑的指令                                                                                 |
+| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | 还要评估时图上叫人跑的指令                                                                                 |
+| `ISSUE_MAP_PORT`           | `4747`                            | server 的端口                                                                                              |
+| `ISSUE_MAP_OPEN`           | 开                                | 设 `0` 就不自动开浏览器（`bun --watch` 的开发模式默认关掉）                                                |
+三个要特别想过的：
 - **标签词汇**：目标 repo 没在用这套标签就要换成它自己的名字。程序会侦测——快照里完全没出现 ready／unready 任何一个标签时，就不拿 triage 当闸门，否则每张票都会变成「待评估」。
 - **指令名**：`/implement`、`/triage` 是 Claude Code 的 skill。目标 repo 没有的话一定要换掉，不然图上会叫人跑不存在的东西。
+- **已完成的兄弟票要靠原生 sub-issue**：地图只跟 GitHub 要 open 票还牵着的 closed 票——它的阻挡者、它的 parent，以及那个 parent 底下的子票。子票是从 GitHub 原生的 sub-issue 关系拿的，所以用 `## Parent` 正文惯例的 repo 看不到一组里**已完成**的子票，那一组的进度会比实际少。open 票不受影响。另一条路是整包扫过 repo 里所有 closed 票，而那在老 repo 上是几十次请求换个位数张票。一组票如果是原生 sub-issue 之前开的，把子票关联上去一次（票页的 Sub-issues）就会回来；正文惯例可以留着，原生的本来就优先。
 ## 常见失败
-- `gh api graphql 失敗：…` — `gh` 没登录，或 cwd 不在目标 repo 的 git 树里。
-- `open issue 超過 100 張，這支要改成分頁抓` — GraphQL 的 `first` 上限就是 100。要支持更多票得在 `issue-map.ts` 的 `query()` 加分页；这是要改程序，不是配置。
-（CLI 消息是繁体中文，所以这里照它实际印出来的样子引用。）
+- `gh api graphql failed: …` — `gh` 没登录，或 cwd 不在目标 repo 的 git 树里。
 ## 文件

package/README.zh-TW.md CHANGED Viewed

@@ -61,7 +61,7 @@ bunx -p issue-map@latest issue-map-build out.html
 的值，分組名字也一樣，話在 i18n 那一層才組出來。快照裡存中文句子的話，換一次語言就得重抓一次
 GitHub。
-CLI 那一側（產檔訊息、錯誤）刻意留中文：那是給開發者看的，不是頁面的一部分。
+CLI 那一側（產檔訊息、錯誤）只有英文，也不跟著頁面的語言走：那是 `bunx issue-map` 的輸出，給下指令的人看的，不是頁面的一部分。例外是 `scripts/mutate.ts`——它是這個 repo 內部的工具，留中文。
 ## 前置條件
@@ -74,28 +74,28 @@ CLI 那一側（產檔訊息、錯誤）刻意留中文：那是給開發者看
 全部有預設值，一個都不設也跑得起來。預設值長在 `scripts/issue-map.ts` 的 `CONFIG`。
-| 環境變數                   | 預設                              | 意思                                                               |
-| -------------------------- | --------------------------------- | ------------------------------------------------------------------ |
-| `GH_REPO`                  | 從 cwd 的 git 推斷                | 要畫別的 repo 時設它（`gh` 自己的變數，fork 與多 remote 也交給它） |
-| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | 子票在內文指向母票的段落標題。GitHub 原生 sub-issue 有值時優先     |
-| `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                                  |
-| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | 這些要人做，下一步不寫實作指令                                     |
-| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | 可以動工時圖上叫人跑的指令                                         |
-| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | 還要評估時圖上叫人跑的指令                                         |
-| `ISSUE_MAP_PORT`           | `4747`                            | server 的 port                                                     |
-| `ISSUE_MAP_OPEN`           | 開                                | 設 `0` 就不自動開瀏覽器（`bun --watch` 的開發模式預設關掉）        |
-兩個要特別想過的：
+| 環境變數                   | 預設                              | 意思                                                                                                       |
+| -------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `GH_REPO`                  | 從 cwd 的 git 推斷                | 要畫別的 repo 時設它（`gh` 自己的變數，fork 與多 remote 也交給它）                                         |
+| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | 子票在內文指向母票的段落標題。GitHub 原生 sub-issue 有值時優先，而且只有原生的看得到已完成的兄弟票（見下） |
+| `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                                                                          |
+| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | 這些要人做，下一步不寫實作指令                                                                             |
+| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | 可以動工時圖上叫人跑的指令                                                                                 |
+| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | 還要評估時圖上叫人跑的指令                                                                                 |
+| `ISSUE_MAP_PORT`           | `4747`                            | server 的 port                                                                                             |
+| `ISSUE_MAP_OPEN`           | 開                                | 設 `0` 就不自動開瀏覽器（`bun --watch` 的開發模式預設關掉）                                                |
+三個要特別想過的：
 - **標籤字彙**：目標 repo 沒在用這套標籤就要換成它自己的名字。程式會偵測——快照裡完全沒出現 ready／unready 任何一個標籤時，就不拿 triage 當閘門，否則每張票都會變成「待評估」。
 - **指令名**：`/implement`、`/triage` 是 Claude Code 的 skill。目標 repo 沒有的話一定要換掉，不然圖上會叫人跑不存在的東西。
+- **已完成的兄弟票要靠原生 sub-issue**：地圖只跟 GitHub 要 open 票還牽著的 closed 票——它的阻擋者、它的 parent，以及那個 parent 底下的子票。子票是從 GitHub 原生的 sub-issue 關係拿的，所以用 `## Parent` 內文慣例的 repo 看不到一組裡**已完成**的子票，那一組的進度會比實際少。open 票不受影響。另一條路是整包掃過 repo 裡所有 closed 票，而那在老 repo 上是幾十次請求換個位數張票。一組票如果是原生 sub-issue 之前開的，把子票關聯上去一次（票頁的 Sub-issues）就會回來；內文慣例可以留著，原生的本來就優先。
 ## 常見失敗
-- `gh api graphql 失敗：…` — `gh` 沒登入，或 cwd 不在目標 repo 的 git 樹裡。
-- `open issue 超過 100 張，這支要改成分頁抓` — GraphQL 的 `first` 上限就是 100。要支援更多票得在 `issue-map.ts` 的 `query()` 加分頁；這是要改程式，不是設定。
+- `gh api graphql failed: …` — `gh` 沒登入，或 cwd 不在目標 repo 的 git 樹裡。
 ## 檔案

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "issue-map",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",

package/scripts/issue-map-serve.ts CHANGED Viewed

@@ -36,7 +36,7 @@ function openInBrowser(url: string): void {
   const result = spawnSync(command, { stdout: 'ignore', stderr: 'pipe' })
   if (!result.success) {
     console.error(
-      `打不開瀏覽器（${command[0]}：${result.stderr.toString().trim()}）——自己開上面那個網址`,
+      `Could not open the browser (${command[0]}: ${result.stderr.toString().trim()}) — open the URL above yourself`,
     )
   }
 }
@@ -72,5 +72,5 @@ const server = Bun.serve({
 })
 const url = `http://localhost:${server.port}`
-console.log(`開發地圖：${url}（重新整理就重抓 GitHub）`)
+console.log(`Dev map: ${url} (every refresh re-fetches from GitHub)`)
 if (OPEN) openInBrowser(url)

package/scripts/issue-map.ts CHANGED Viewed

@@ -11,6 +11,10 @@
  * 帶進快照的 issue：所有 open issue，加上仍被 open issue 牽著的 closed issue。後者畫成「已完成」
  * 的節點讓進度看得見，沒人牽著之後自然消失。
  *
+ * closed 是**指名**去要的（阻擋者、parent、parent 底下的子票），不掃整包——老 repo 幾千張
+ * closed 裡通常只有個位數會留下。代價：同一組裡已完成的兄弟票要靠 GitHub 原生 sub-issue 才
+ * 抽得到，用內文 `## Parent` 慣例的 repo 看不到它們，那一組的進度會比實際少。
+ *
  * **要畫哪個 repo**：從 cwd 的 git 推斷，不必填——在那個 repo 裡跑 `bunx issue-map@latest`
  * 就好。要指定別的 repo 設 `GH_REPO`。標籤字彙與 parent 的慣例都能用環境變數調，見底下的
  * `CONFIG`，整份對照表在 README。
@@ -42,8 +46,10 @@ const TEMPLATE = new URL('./issue-map.html', import.meta.url).pathname
 const CLIENT = new URL('./issue-map-page.ts', import.meta.url).pathname
 const OUTPUT = process.argv[2] ?? 'dist/issue-map.html'
-/** 一次查得回來的上限。GraphQL 的 `first` 最多就是 100，超過會少票，所以超過就喊。 */
+/** 一頁的張數。GraphQL 的 `first` 最多就是 100，票再多就靠 cursor 一頁一頁接。 */
 const PAGE = 100
+/** 一次用 alias 指名幾張票。GraphQL 對單一查詢的節點數有上限，這個量級離它還很遠。 */
+const BATCH = 50
 function labelList(raw: string | undefined, fallback: string): readonly string[] {
   return (raw ?? fallback)
@@ -96,50 +102,163 @@ type RawIssue = {
 /** 一路帶著算好的 parent，免得同一段內文被 regex 掃好幾次。 */
 type Issue = RawIssue & { readonly parentNumber: number | null }
-interface Connection {
-  pageInfo: { hasNextPage: boolean }
-  nodes: RawIssue[]
+interface Page<T> {
+  pageInfo: { hasNextPage: boolean; endCursor: string | null }
+  nodes: T[]
 }
-interface QueryResult {
-  repository: { nameWithOwner: string } & Record<'open' | 'closed', Connection>
+/** 票號查不到（號碼其實是 PR，或那張票不存在）時 GraphQL 回 null。 */
+type MaybeIssue = RawIssue | null
+const ISSUE_FIELDS = `
+  number title state url body closedAt
+  author { login }
+  parent { number }
+  labels(first: 20) { nodes { name } }
+  assignees(first: 10) { nodes { login } }
+  blockedBy(first: 50) { nodes { number } }
+`
+/**
+ * 跑一次 `gh api graphql`。
+ *
+ * 票號是我們自己從前一次結果拿到的整數，直接組進查詢字串；只有 cursor 走變數——它是 API 給的
+ * 不透明字串，沒有理由自己去逃脫它。
+ */
+function run<T>(query: string, variables: Record<string, string> = {}): T {
+  // `{owner}`／`{repo}` 由 gh 從 cwd 的 git 推斷，`GH_REPO` 可以蓋過去。
+  const args = [
+    'gh',
+    'api',
+    'graphql',
+    '-f',
+    `query=${query}`,
+    '-F',
+    'owner={owner}',
+    '-F',
+    'repo={repo}',
+  ]
+  for (const [name, value] of Object.entries(variables)) args.push('-f', `${name}=${value}`)
+  const result = spawnSync(args, { stdout: 'pipe', stderr: 'pipe' })
+  if (result.exitCode !== 0) throw new Error(`gh api graphql failed: ${result.stderr.toString()}`)
+  const parsed = JSON.parse(result.stdout.toString()) as { data: T; errors?: unknown }
+  if (parsed.errors) throw new Error(`GraphQL errors: ${JSON.stringify(parsed.errors)}`)
+  return parsed.data
 }
-const FIELDS = `
-  pageInfo { hasNextPage }
-  nodes {
-    number title state url body closedAt
-    author { login }
-    parent { number }
-    labels(first: 20) { nodes { name } }
-    assignees(first: 10) { nodes { login } }
-    blockedBy(first: 50) { nodes { number } }
+const OPEN_QUERY = `
+  query($owner: String!, $repo: String!, $after: String) {
+    repository(owner: $owner, name: $repo) {
+      nameWithOwner
+      issues(states: OPEN, first: ${PAGE}, after: $after, orderBy: { field: CREATED_AT, direction: DESC }) {
+        pageInfo { hasNextPage endCursor }
+        nodes { ${ISSUE_FIELDS} }
+      }
+    }
+  }`
+/** open issue 全部都要，所以一路翻到底——票超過一頁不是錯誤，是常態。 */
+function fetchOpen(): { nameWithOwner: string; open: RawIssue[] } {
+  type Result = { repository: { nameWithOwner: string; issues: Page<RawIssue> } }
+  const open: RawIssue[] = []
+  let nameWithOwner = ''
+  let after: string | null = null
+  for (;;) {
+    const variables: Record<string, string> = after ? { after } : {}
+    const { repository } = run<Result>(OPEN_QUERY, variables)
+    nameWithOwner = repository.nameWithOwner
+    open.push(...repository.issues.nodes)
+    const { hasNextPage, endCursor } = repository.issues.pageInfo
+    if (!hasNextPage || !endCursor) break
+    after = endCursor
   }
-`
+  return { nameWithOwner, open }
+}
+/** alias 不能以數字開頭，所以票號前面補一個 `i`。 */
+const alias = (number: number) => `i${number}`
-/** 一次問完 repo 名字與兩種狀態的 issue，只開一個 `gh` 行程。 */
-const QUERY = `
+function chunks<T>(items: readonly T[], size: number): T[][] {
+  const batches: T[][] = []
+  for (let index = 0; index < items.length; index += size) {
+    batches.push(items.slice(index, index + size))
+  }
+  return batches
+}
+/** 指名要哪幾張票，一批 alias 問完。查不到的就當沒有。 */
+function fetchByNumber(numbers: readonly number[]): RawIssue[] {
+  type Result = { repository: Record<string, MaybeIssue> }
+  const found: RawIssue[] = []
+  for (const batch of chunks(numbers, BATCH)) {
+    const query = `
   query($owner: String!, $repo: String!) {
     repository(owner: $owner, name: $repo) {
-      nameWithOwner
-      open: issues(states: OPEN, first: ${PAGE}, orderBy: { field: CREATED_AT, direction: DESC }) { ${FIELDS} }
-      closed: issues(states: CLOSED, first: ${PAGE}, orderBy: { field: CREATED_AT, direction: DESC }) { ${FIELDS} }
+      ${batch.map((number) => `${alias(number)}: issue(number: ${number}) { ${ISSUE_FIELDS} }`).join('\n      ')}
     }
   }`
+    const { repository } = run<Result>(query)
+    for (const number of batch) {
+      const issue = repository[alias(number)]
+      if (issue) found.push(issue)
+    }
+  }
+  return found
+}
-function query(): QueryResult['repository'] {
-  // `{owner}`／`{repo}` 由 gh 從 cwd 的 git 推斷，`GH_REPO` 可以蓋過去。
-  const result = spawnSync(
-    ['gh', 'api', 'graphql', '-f', `query=${QUERY}`, '-F', 'owner={owner}', '-F', 'repo={repo}'],
-    { stdout: 'pipe', stderr: 'pipe' },
-  )
-  if (result.exitCode !== 0) throw new Error(`gh api graphql 失敗：${result.stderr.toString()}`)
-  const parsed = JSON.parse(result.stdout.toString()) as { data: QueryResult; errors?: unknown }
-  if (parsed.errors) throw new Error(`GraphQL 錯誤：${JSON.stringify(parsed.errors)}`)
-  const repository = parsed.data.repository
-  if (repository.open.pageInfo.hasNextPage) {
-    throw new Error(`open issue 超過 ${PAGE} 張，這支要改成分頁抓`)
+function childrenQuery(parent: number): string {
+  return `
+  query($owner: String!, $repo: String!, $after: String) {
+    repository(owner: $owner, name: $repo) {
+      issue(number: ${parent}) {
+        subIssues(first: ${PAGE}, after: $after) {
+          pageInfo { hasNextPage endCursor }
+          nodes { ${ISSUE_FIELDS} }
+        }
+      }
+    }
+  }`
+}
+/**
+ * 拿這些 parent 底下的子票，為的是把同一組裡**已完成**的兄弟票撈出來當進度。
+ *
+ * 只有 GitHub 原生 sub-issue 有值。用內文 `## Parent` 慣例的 repo 這裡是空的，那些已完成的
+ * 兄弟票就不會出現在圖上——要把它們找回來只能整包掃 closed，而那對老 repo 是幾十次請求換
+ * 幾張票。open 的兄弟不必靠這裡，它們本來就在 open 那包。
+ */
+function fetchChildren(parents: readonly number[]): RawIssue[] {
+  type Batch = { repository: Record<string, { subIssues: Page<RawIssue> } | null> }
+  type More = { repository: { issue: { subIssues: Page<RawIssue> } | null } }
+  const children: RawIssue[] = []
+  for (const batch of chunks(parents, BATCH)) {
+    const query = `
+  query($owner: String!, $repo: String!) {
+    repository(owner: $owner, name: $repo) {
+      ${batch
+        .map(
+          (number) => `${alias(number)}: issue(number: ${number}) {
+        subIssues(first: ${PAGE}) { pageInfo { hasNextPage endCursor } nodes { ${ISSUE_FIELDS} } } }`,
+        )
+        .join('\n      ')}
+    }
+  }`
+    const { repository } = run<Batch>(query)
+    for (const number of batch) {
+      const page = repository[alias(number)]?.subIssues
+      if (!page) continue
+      children.push(...page.nodes)
+      // 子票破百的 parent 很罕見，就讓它自己續抓，不為了它把整批都變成分頁查詢。
+      let after = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null
+      while (after) {
+        const next = run<More>(childrenQuery(number), { after }).repository.issue?.subIssues
+        if (!next) break
+        children.push(...next.nodes)
+        after = next.pageInfo.hasNextPage ? next.pageInfo.endCursor : null
+      }
+    }
   }
-  return repository
+  return children
 }
 /** 原生 sub-issue 優先；沒有就讀內文的 `## <標題>` 之後第一個 `#<n>`。 */
@@ -150,9 +269,8 @@ function withParent(raw: RawIssue): Issue {
 }
 export function takeSnapshot(): Snapshot {
-  const repository = query()
-  const open = repository.open.nodes.map(withParent)
-  const closed = repository.closed.nodes.map(withParent)
+  const { nameWithOwner, open: rawOpen } = fetchOpen()
+  const open = rawOpen.map(withParent)
   const openNumbers = new Set(open.map((issue) => issue.number))
   const openParents = new Set(open.map((issue) => issue.parentNumber).filter(isNumber))
@@ -160,17 +278,17 @@ export function takeSnapshot(): Snapshot {
     open.flatMap((issue) => issue.blockedBy.nodes.map((blocker) => blocker.number)),
   )
-  // 只留 open issue 還牽著的 closed issue：當它們的阻擋者、當它們的 parent，或跟它們同一個
-  // parent（同一組子票的已完成進度）。沒人牽著之後自然從地圖消失。
-  const kept = [
-    ...open,
-    ...closed.filter(
-      (issue) =>
-        blockers.has(issue.number) ||
-        openParents.has(issue.number) ||
-        (issue.parentNumber !== null && openParents.has(issue.parentNumber)),
-    ),
-  ]
+  // 進圖的 closed issue 只有 open issue 還牽著的那些：它們的阻擋者、它們的 parent，以及同一個
+  // parent 底下已完成的兄弟（那一組的進度）。所以不掃整包 closed，而是指名去要——老 repo 的
+  // 幾千張 closed 裡通常只有個位數會留下，翻完它們是拿幾十次請求換幾張票。
+  const referenced = [...new Set([...blockers, ...openParents])].filter(
+    (number) => !openNumbers.has(number),
+  )
+  const closed = dedupe([...fetchByNumber(referenced), ...fetchChildren([...openParents])])
+    .filter((issue) => issue.state === 'CLOSED' && !openNumbers.has(issue.number))
+    .map(withParent)
+  const kept = [...open, ...closed]
   const parents = new Set(kept.map((issue) => issue.parentNumber).filter(isNumber))
   const openChildren = new Map<number, number>()
   for (const issue of kept) {
@@ -187,7 +305,7 @@ export function takeSnapshot(): Snapshot {
     .toSorted((a, b) => a.number - b.number)
   return {
     generatedAt: new Date().toISOString(),
-    repo: repository.nameWithOwner,
+    repo: nameWithOwner,
     labels: { ready: CONFIG.ready, unready: CONFIG.unready },
     groups: groupsOf(issues),
     criticalPath: criticalPathOf(issues),
@@ -195,6 +313,11 @@ export function takeSnapshot(): Snapshot {
   }
 }
+/** 同一張票可能同時是某人的阻擋者又是某人的兄弟，用票號收斂成一張。 */
+function dedupe(issues: readonly RawIssue[]): RawIssue[] {
+  return [...new Map(issues.map((issue) => [issue.number, issue])).values()]
+}
 function isNumber(value: number | null): value is number {
   return value !== null
 }
@@ -281,9 +404,9 @@ async function bundleClient(): Promise<string> {
     format: 'iife',
     minify: false,
   })
-  if (!built.success) throw new Error(`打包 ${CLIENT} 失敗：${built.logs.join('\n')}`)
+  if (!built.success) throw new Error(`Failed to bundle ${CLIENT}: ${built.logs.join('\n')}`)
   const [output] = built.outputs
-  if (!output) throw new Error(`打包 ${CLIENT} 沒有產出`)
+  if (!output) throw new Error(`Bundling ${CLIENT} produced no output`)
   return output.text()
 }
@@ -307,17 +430,17 @@ export async function renderFragment(snapshot: Snapshot): Promise<string> {
 function replaceIn(html: string, marker: RegExp, body: string, what: string): string {
   const next = html.replace(marker, `$1${body}$2`)
-  if (next === html) throw new Error(`樣板缺少 ${what} 區塊：${TEMPLATE}`)
+  if (next === html) throw new Error(`Template is missing the ${what} block: ${TEMPLATE}`)
   return next
 }
 export function describe(snapshot: Snapshot): string {
   const done = snapshot.issues.filter((issue) => issue.status === 'done').length
-  return `${snapshot.issues.length - done} 張未完成、${done} 張仍被引用的已完成（${snapshot.generatedAt}）`
+  return `${snapshot.issues.length - done} unfinished, ${done} closed but still referenced (${snapshot.generatedAt})`
 }
 if (import.meta.main) {
   const snapshot = takeSnapshot()
   await Bun.write(OUTPUT, await renderFragment(snapshot))
-  console.log(`已寫入 ${OUTPUT}：${describe(snapshot)}`)
+  console.log(`Wrote ${OUTPUT}: ${describe(snapshot)}`)
 }