issue-map 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gunter Chou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# issue-map
+
+把 GitHub Issues 的阻擋關係畫成一頁開發地圖：**哪幾張票現在可以動、哪幾張在等誰、關鍵路徑是哪一條。**
+
+狀態的權威永遠是 GitHub Issues。這一頁只是快照，頁面上不能改狀態——所以不會長出第二個事實來源。
+
+## 用法
+
+在**要看的那個 repo** 裡跑：
+
+```bash
+bunx github:gunter1020/issue-map#main
+```
+
+`#main` 不是裝飾：**不帶 ref 的話 bun 會一直用第一次解析到的那個 commit**。實測過——先跑不帶 ref 的版本，之後 repo 推了新 commit，再跑同一行還是拿到舊的（`~/.bun/install/cache/@GH@gunter1020-issue-map-<sha>@@@1` 看得到是哪一個），加上 `#main` 才拿到新的。
+
+起在 `http://localhost:4747` **並直接開瀏覽器**。每次重新整理都重抓 GitHub，看到的一定是現在的狀態。repo 是 `gh` 從 cwd 的 git 推斷的，不必填。
+
+不要自動開分頁就設 `ISSUE_MAP_OPEN=0`。
+
+只要一份靜態 HTML 的話（`-p` 是用來選另一個 bin 的，少了它會變成起 server）：
+
+```bash
+bunx -p github:gunter1020/issue-map#main issue-map-build            # 寫到 dist/issue-map.html
+bunx -p github:gunter1020/issue-map#main issue-map-build out.html
+```
+
+快照就是快照——狀態會過期，要看現在的狀態就用上面的 server。
+
+## 前置條件
+
+- **Bun**。這幾支用了 `Bun.build`、`Bun.serve`、`Bun.file` 與 bun 的 `spawnSync`，Node 跑不起來。
+- **`gh` CLI 已登入**，而且對目標 repo 有讀取權。
+- 目標 repo 有 git remote 指向 GitHub。
+- 沒有 runtime 依賴；devDependencies 只有型別與 lint／format 工具。
+
+## 設定
+
+全部有預設值，一個都不設也跑得起來。預設值長在 `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` 的開發模式預設關掉）        |
+
+兩個要特別想過的：
+
+- **標籤字彙**：目標 repo 沒在用這套標籤就要換成它自己的名字。程式會偵測——快照裡完全沒出現 ready／unready 任何一個標籤時，就不拿 triage 當閘門，否則每張票都會變成「待評估」。
+- **指令名**：`/implement`、`/triage` 是 Claude Code 的 skill。目標 repo 沒有的話一定要換掉，不然圖上會叫人跑不存在的東西。
+
+## 常見失敗
+
+- `gh api graphql 失敗：…` — `gh` 沒登入，或 cwd 不在目標 repo 的 git 樹裡。
+- `open issue 超過 100 張，這支要改成分頁抓` — GraphQL 的 `first` 上限就是 100。要支援更多票得在 `issue-map.ts` 的 `query()` 加分頁；這是要改程式，不是設定。
+
+## 檔案
+
+| 檔案                         | 責任                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `scripts/issue-map.ts`       | 抓快照、算每張票的狀態與下一步、產出 HTML。移植設定在裡面的 `CONFIG`   |
+| `scripts/issue-map-model.ts` | 純資料模型：分組、關鍵路徑。前後端共用                                 |
+| `scripts/issue-map-page.ts`  | 瀏覽器端程式碼，建置時被打包進 HTML                                    |
+| `scripts/issue-map.html`     | 樣板。兩個佔位區塊（`issue-map-data`、`issue-map-code`）會被填入       |
+| `scripts/issue-map-serve.ts` | 本機 server，每個請求重抓一次                                          |
+| `scripts/mutate.ts`          | 突變測試：改壞一行看測試會不會紅。守門測試的反向驗證用它，不要手改檔案 |
+
+## 在這個 repo 裡開發
+
+```bash
+bun install
+bun run issue-map:serve   # --watch，改程式碼會自動重啟；刻意不自動開瀏覽器（每存一次檔就會多一個分頁）
+bun run issue-map         # 只產檔到 dist/issue-map.html
+bun run check             # lint + format:check + typecheck
+bun test                  # 純模型那一層（分組、關鍵路徑、排版）
+```
+
+這個 repo 自己還沒有 issue，`GH_REPO=<owner>/<repo>` 指到有票的 repo 才畫得出東西。
+
+`tests/` 只守會讓地圖說謊或不能看的事，外觀（顏色、形狀、間距）刻意不驗。新增守門測試要走反向驗證——把它宣稱要擋的缺陷放回產品碼，確認它會紅：
+
+```bash
+bun run mutate scripts/issue-map-model.ts tests/issue-map-layout.test.ts
+```
+
+## 兩個設計上的決定，改之前先知道
+
+- **這一頁不能改狀態。** 沒有按鈕會回寫 GitHub。刻意的：狀態只有一個事實來源，多一個入口就會不一致。
+- **票名不進地圖。** 節點只掛票號，名字在下方清單。試過在內文加短名段落，那是票名的第二個事實來源，改標題不會改它；機械縮短標題讀不通。

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "issue-map",
+  "version": "0.1.0",
+  "description": "把 GitHub Issues 的阻擋關係畫成一頁開發地圖：哪幾張票現在可以動、哪幾張在等誰、關鍵路徑是哪一條。",
+  "keywords": [
+    "bun",
+    "cli",
+    "dependency-graph",
+    "github",
+    "issues"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gunter1020/issue-map.git"
+  },
+  "bin": {
+    "issue-map": "./scripts/issue-map-serve.ts",
+    "issue-map-build": "./scripts/issue-map.ts"
+  },
+  "files": [
+    "scripts/issue-map.ts",
+    "scripts/issue-map-model.ts",
+    "scripts/issue-map-page.ts",
+    "scripts/issue-map-serve.ts",
+    "scripts/issue-map.html"
+  ],
+  "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",
+    "typecheck": "tsc --noEmit",
+    "mutate": "bun run scripts/mutate.ts",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "check": "bun run lint && bun run format:check && bun run typecheck"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "^0.62.0",
+    "oxlint": "^1.76.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/scripts/issue-map-model.ts

@@ -0,0 +1,247 @@
+/**
+ * 開發地圖的形狀與純推導。**沒有 Bun、沒有 DOM**——抓資料的那一側（`issue-map.ts`）與畫面
+ * 那一側（`issue-map-page.ts`）都 import 它，所以它不能碰任何一邊的專屬 API。
+ *
+ * 這裡住的是「同一份定義只有一份」的東西：狀態的五個值、一張票的形狀、分群規則、關鍵路徑，
+ * 以及線路圖的排版。畫面那一側曾經把狀態的五個值再抄一次，兩邊沒有東西保證同步；現在型別
+ * 是共用的，抄錯編不過。
+ */
+
+/** 一張票現在的處境。同時是頁面的顏色與篩選分頁。 */
+export type Status = 'ready' | 'active' | 'blocked' | 'triage' | 'done'
+
+/** 五個狀態的顯示順序，也是清單的排序權重。 */
+export const STATUS_ORDER: readonly Status[] = ['ready', 'active', 'blocked', 'triage', 'done']
+
+export const STATUS_LABEL: Readonly<Record<Status, string>> = {
+  ready: '可接手',
+  active: '進行中',
+  blocked: '阻擋中',
+  triage: '待 triage',
+  done: '已完成',
+}
+
+/** 頁面吃的形狀。這裡是它唯一的定義。 */
+export type MapIssue = {
+  readonly number: number
+  readonly title: string
+  readonly url: string
+  readonly closedAt: string | null
+  /** 開票的人。帳號已刪除時是空字串。 */
+  readonly author: string
+  readonly labels: readonly string[]
+  readonly assignees: readonly string[]
+  readonly parent: number | null
+  /** 全部的阻擋者，含已關掉的——頁面要畫出「已解鎖的前置」。 */
+  readonly blockedBy: readonly number[]
+  /** 還開著的阻擋者，就是實際的閘門。 */
+  readonly waitingFor: readonly number[]
+  readonly status: Status
+  /** 白話的下一步，已完成的票是空字串。 */
+  readonly nextStep: string
+  /** 有子票的票。它自己不做事，等子票全關。 */
+  readonly isParent: boolean
+}
+
+/** 畫在同一張圖上的一群票。 */
+export type Group = {
+  /** 有 parent 的群就是那張主票；沒有的是「其他依賴鏈」與「獨立票」這兩種。 */
+  readonly parent: number | null
+  readonly title: string
+  readonly members: readonly number[]
+}
+
+export type Snapshot = {
+  readonly generatedAt: string
+  readonly repo: string
+  /** 這一次實際生效的標籤字彙。圖例照它寫，不然改了設定圖例就會說謊。 */
+  readonly labels: { readonly ready: readonly string[]; readonly unready: readonly string[] }
+  /** 一張圖一群。 */
+  readonly groups: readonly Group[]
+  /** 最長的一條依序未完成鏈，也就是最少要幾輪。 */
+  readonly criticalPath: number
+  readonly issues: readonly MapIssue[]
+}
+
+/**
+ * 分群：同一張主票底下的子票一群；沒有主票但跟別人有前置關係的合成一群；完全孤立的合成一群。
+ * 一張圖畫一群。
+ */
+export function groupsOf(issues: readonly MapIssue[]): Group[] {
+  const known = new Set(issues.map((issue) => issue.number))
+  const blocking = new Set(issues.flatMap((issue) => issue.blockedBy))
+  const byParent = new Map<number, number[]>()
+  for (const issue of issues) {
+    if (issue.parent === null) continue
+    const siblings = byParent.get(issue.parent) ?? []
+    siblings.push(issue.number)
+    byParent.set(issue.parent, siblings)
+  }
+
+  const groups: Group[] = []
+  for (const [parent, members] of byParent) {
+    const spec = issues.find((issue) => issue.number === parent)
+    groups.push({ parent, title: spec?.title ?? `#${parent} 的子票`, members })
+  }
+
+  const grouped = new Set([...byParent.values()].flat())
+  const linked: number[] = []
+  const alone: number[] = []
+  for (const issue of issues) {
+    if (grouped.has(issue.number) || issue.isParent) continue
+    const hasEdge = blocking.has(issue.number) || issue.blockedBy.some((n) => known.has(n))
+    ;(hasEdge ? linked : alone).push(issue.number)
+  }
+  if (linked.length) groups.push({ parent: null, title: '其他依賴鏈', members: linked })
+  if (alone.length) groups.push({ parent: null, title: '獨立票', members: alone })
+  return groups
+}
+
+/** DAG 裡從來源算起的最長路徑。環在資料裡不該有，真的有就當它走到底。 */
+function longestPath(
+  start: number,
+  predecessorsOf: (n: number) => readonly number[],
+  memo: Map<number, number>,
+): number {
+  function walk(n: number, seen: Set<number>): number {
+    const cached = memo.get(n)
+    if (cached !== undefined) return cached
+    if (seen.has(n)) return 0
+    seen.add(n)
+    let best = 0
+    for (const previous of predecessorsOf(n)) best = Math.max(best, walk(previous, seen))
+    memo.set(n, best + 1)
+    return best + 1
+  }
+  return walk(start, new Set())
+}
+
+/** 最長的一條依序未完成鏈。 */
+export function criticalPathOf(issues: readonly MapIssue[]): number {
+  const waiting = new Map(issues.map((issue) => [issue.number, issue.waitingFor]))
+  const memo = new Map<number, number>()
+  let longest = 0
+  for (const issue of issues) {
+    if (issue.status === 'done') continue
+    longest = Math.max(
+      longest,
+      longestPath(issue.number, (n) => waiting.get(n) ?? [], memo),
+    )
+  }
+  return longest
+}
+
+/** 線路圖的尺寸。改這裡就會同時改到排版與 SVG 的畫布大小。 */
+export const MAP = {
+  /** 左邊留給線名，也讓第一站的名字不會壓到它。 */
+  gutter: 96,
+  /** 站與站的水平距離。 */
+  step: 108,
+  /** 線與線的垂直距離。 */
+  row: 72,
+  /** 第一條線離上緣。 */
+  top: 26,
+  /** 站點的半徑。 */
+  dot: 7,
+  /** 跨線轉折的圓角。 */
+  bend: 12,
+  /** 最後一站的名字會往右伸出去，畫布要留得下。 */
+  rightPad: 46,
+} as const
+
+export type Point = { readonly x: number; readonly y: number }
+export type Edge = { readonly from: number; readonly to: number }
+
+export type Layout = {
+  /** 每一條線由前到後的站。只有一站的線不標線名。 */
+  readonly tracks: readonly (readonly number[])[]
+  /** 孤立的票排成幾列月台。 */
+  readonly islandRows: number
+  /** 月台從第幾列開始。 */
+  readonly islandFrom: number
+  readonly xy: ReadonlyMap<number, Point>
+  readonly edges: readonly Edge[]
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * 把一組票排成線路圖。
+ *
+ * x 由整張圖的 level 決定（前置在左），y 由票屬於哪一條線決定。所有邊因此一律向右，跨線的邊
+ * 只需要一個直角轉折。
+ *
+ * 真的有前置關係的票才排成線：每次挑最長的一條鏈當一條線，挑完移除再挑下一條。組裡完全沒有
+ * 前置關係的票（既不擋人也不被擋）不算線，打包成一片月台橫排——不然一組十二張互不相干的票
+ * 會變成十二條單站線。
+ */
+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 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 wired = members.filter((m) => hasEdge.has(m.number))
+  const island = members.filter((m) => !hasEdge.has(m.number))
+
+  const level = new Map<number, number>()
+  for (const m of wired) longestPath(m.number, predsOf, level)
+  const levelOf = (n: number) => level.get(n) ?? 1
+  const deeperFirst = (a: number, b: number) => levelOf(b) - levelOf(a)
+
+  const left = new Set(wired.map((m) => m.number))
+  const tracks: number[][] = []
+  while (left.size) {
+    const tail = [...left].sort((a, b) => deeperFirst(a, b) || a - b)[0] as number
+    const chain = [tail]
+    for (let at = tail; ;) {
+      const back = predsOf(at)
+        .filter((n) => left.has(n))
+        .sort(deeperFirst)[0]
+      if (back === undefined) break
+      chain.unshift(back)
+      at = back
+    }
+    for (const n of chain) left.delete(n)
+    tracks.push(chain)
+  }
+
+  const depth = wired.length ? Math.max(...wired.map((m) => levelOf(m.number))) : 1
+  const perRow = Math.max(depth, 4)
+  const xy = new Map<number, Point>()
+  tracks.forEach((chain, index) => {
+    for (const n of chain) {
+      xy.set(n, { x: MAP.gutter + (levelOf(n) - 1) * MAP.step, y: MAP.top + index * MAP.row })
+    }
+  })
+  island.forEach((m, index) => {
+    xy.set(m.number, {
+      x: MAP.gutter + (index % perRow) * MAP.step,
+      y: MAP.top + (tracks.length + Math.floor(index / perRow)) * MAP.row,
+    })
+  })
+  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,
+    height: MAP.top + (tracks.length + islandRows) * MAP.row,
+  }
+}