issue-map 0.3.1 → 0.4.0

package/scripts/issue-map.html

@@ -424,6 +424,7 @@
   }
 
   .map-wrap {
+    position: relative;
     background: var(--card);
     border: 1px solid var(--line);
     border-top: 2px solid var(--track, var(--line-strong));
@@ -537,17 +538,42 @@
   }
 
   /* 線名 */
-  .tname {
+  /* 線名。畫在 SVG 外面的一欄，這樣長的名字用 text-overflow 就截得掉——SVG 的 <text> 不會
+     換行也不會自己截斷，長一點就會蓋到第一個站點上。寬度比 MAP.gutter 少一點，留白給站點。 */
+  .tlabel {
+    position: absolute;
+    left: 12px;
+    width: 84px;
+    transform: translateY(-12px);
     font-family: var(--mono);
+    pointer-events: none;
+  }
+  .tlabel b,
+  .tlabel span {
+    display: block;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+  .tlabel b {
     font-size: 12px;
     font-weight: 600;
-    fill: var(--muted);
+    color: var(--muted);
     font-variant-numeric: tabular-nums;
   }
-  .tsub {
-    font-family: var(--mono);
+  .tlabel span {
     font-size: 10px;
-    fill: var(--faint);
+    color: var(--faint);
+  }
+
+  /* 沒有畫圖的那幾組。 */
+  .undrawn {
+    margin: 0;
+    padding: 14px 12px;
+    color: var(--faint);
+    font-size: 13px;
+    border: 1px dashed var(--line);
+    border-radius: 2px;
   }
 
   .map-key {

package/scripts/issue-map.ts

@@ -1,38 +1,21 @@
 #!/usr/bin/env bun
 /**
  * 開發地圖：把 GitHub Issues 的阻擋關係抓下來，塞進 `scripts/issue-map.html` 這份樣板，產出一頁
- * 可以直接看的 HTML。
+ * 可以直接看的 HTML。每張票的狀態、在等誰、下一步都在這裡算完才送進頁面，樣板只負責畫。
  *
- * 狀態的權威永遠是 GitHub Issues。這一頁只是**快照**：頁面上不能改狀態，要更新就重跑這支。
- * 這樣不會長出第二個事實來源。
+ * 帶進快照的 issue：所有 open issue，加上仍被 open issue 牽著的 closed issue（畫成「已完成」的
+ * 節點讓進度看得見，沒人牽著之後自然消失）。closed 是**指名**去要的——阻擋者、parent、parent
+ * 底下的子票，不掃整包，因為老 repo 幾千張 closed 裡通常只有個位數會留下。代價：同一組裡已
+ * 完成的兄弟票要靠 GitHub 原生 sub-issue 才抽得到，用內文 `## Parent` 慣例的 repo 看不到它們，
+ * 那一組的進度會比實際少。
  *
- * 每張票的狀態、在等誰、下一步都在這裡算完才送進頁面，樣板只負責畫。
- *
- * 帶進快照的 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。
- *
- * 票名不進地圖。曾經試過在內文加一個 `## 短名` 段落給站點當標籤，但那要每張票靠人維護、
- * 而且是票名的第二個事實來源，改標題不會改它。機械縮短標題也試過，這裡的標題沒有一致結構，
- * 縮出來讀不通。所以站點只掛票號，名字交給清單。
- *
- * 用法：
- *   bun run scripts/issue-map.ts                  # 寫到 dist/issue-map.html
- *   bun run scripts/issue-map.ts path/to/out.html
- *
- * 要「重新整理就是最新」，改跑 `scripts/issue-map-serve.ts`：它每個請求都呼叫這裡的
- * `takeSnapshot` 重抓一次。
+ * 用法：`bun run scripts/issue-map.ts [out.html]`，預設寫到 `dist/issue-map.html`。
+ * 環境變數與設計決定見 README；移植要調的東西在底下的 `CONFIG`。
  */
 
 import { spawnSync } from 'bun'
 
+import { LOCALE_NAME, LOCALES, t } from './issue-map-i18n.ts'
 import {
   criticalPathOf,
   groupsOf,
@@ -41,6 +24,7 @@ import {
   type Snapshot,
   type Status,
 } from './issue-map-model.ts'
+import { esc, viewOf } from './issue-map-view.ts'
 
 const TEMPLATE = new URL('./issue-map.html', import.meta.url).pathname
 const CLIENT = new URL('./issue-map-page.ts', import.meta.url).pathname
@@ -61,8 +45,7 @@ function labelList(raw: string | undefined, fallback: string): readonly string[]
 /**
  * 移植時要調的東西全在這裡，而且都有預設值——不設任何一個也跑得起來。
  *
- * repo 不在這裡：`gh` 的 `{owner}`／`{repo}` 佔位符會從 cwd 的 git 推斷，要指定別的 repo 就設
- * `GH_REPO`（`gh` 自己的環境變數，fork 與多 remote 的判斷也一併交給它）。
+ * repo 不在這裡：那是 `gh` 自己的 `GH_REPO`，fork 與多 remote 的判斷也一併交給它。
  */
 const CONFIG = {
   /** 子票在內文裡指向 parent 的標題。GitHub 原生 sub-issue 有值時優先用原生的。 */
@@ -119,6 +102,33 @@ const ISSUE_FIELDS = `
   blockedBy(first: 50) { nodes { number } }
 `
 
+type GraphQLError = { readonly type?: string; readonly message?: string }
+
+/**
+ * 從 `gh api graphql` 的輸出取出 data。
+ *
+ * **查不到的票不是錯誤。** 指名去要某個票號時，GitHub 會同時回 `data`（那個 alias 是 `null`）
+ * 與一筆 `NOT_FOUND`，而 `gh` 為了那筆錯誤以非零離開。號碼其實是 PR、票被轉移或刪掉、內文
+ * 慣例掃出來的誤判——在老 repo 上都是常態，一個掃不到就讓整張圖產不出來並不合理。所以只有
+ * `NOT_FOUND` 以外的錯誤才拋，資料照用。
+ *
+ * 連 data 都沒有（沒登入、網路不通）就拿 stderr 當原因拋出去。
+ */
+export function dataOrThrow<T>(stdout: string, stderr: string): T {
+  let parsed: { data?: T; errors?: readonly GraphQLError[] } | undefined
+  try {
+    parsed = stdout ? (JSON.parse(stdout) as typeof parsed) : undefined
+  } catch {
+    parsed = undefined
+  }
+  const fatal = (parsed?.errors ?? []).filter((error) => error.type !== 'NOT_FOUND')
+  if (!parsed?.data || fatal.length) {
+    const why = fatal.length ? JSON.stringify(fatal) : stderr.trim() || stdout.trim()
+    throw new Error(`gh api graphql failed: ${why}`)
+  }
+  return parsed.data
+}
+
 /**
  * 跑一次 `gh api graphql`。
  *
@@ -140,10 +150,7 @@ function run<T>(query: string, variables: Record<string, string> = {}): T {
   ]
   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
+  return dataOrThrow<T>(result.stdout.toString(), result.stderr.toString())
 }
 
 const OPEN_QUERY = `
@@ -223,9 +230,8 @@ function childrenQuery(parent: number): string {
 /**
  * 拿這些 parent 底下的子票，為的是把同一組裡**已完成**的兄弟票撈出來當進度。
  *
- * 只有 GitHub 原生 sub-issue 有值。用內文 `## Parent` 慣例的 repo 這裡是空的，那些已完成的
- * 兄弟票就不會出現在圖上——要把它們找回來只能整包掃 closed，而那對老 repo 是幾十次請求換
- * 幾張票。open 的兄弟不必靠這裡，它們本來就在 open 那包。
+ * 只有 GitHub 原生 sub-issue 有值；用內文 `## Parent` 慣例的 repo 這裡是空的（檔頭說的那個
+ * 代價）。open 的兄弟不必靠這裡，它們本來就在 open 那包。
  */
 function fetchChildren(parents: readonly number[]): RawIssue[] {
   type Batch = { repository: Record<string, { subIssues: Page<RawIssue> } | null> }
@@ -278,9 +284,7 @@ export function takeSnapshot(): Snapshot {
     open.flatMap((issue) => issue.blockedBy.nodes.map((blocker) => blocker.number)),
   )
 
-  // 進圖的 closed issue 只有 open issue 還牽著的那些：它們的阻擋者、它們的 parent，以及同一個
-  // parent 底下已完成的兄弟（那一組的進度）。所以不掃整包 closed，而是指名去要——老 repo 的
-  // 幾千張 closed 裡通常只有個位數會留下，翻完它們是拿幾十次請求換幾張票。
+  // 指名去要而不掃整包 closed，理由見檔頭。
   const referenced = [...new Set([...blockers, ...openParents])].filter(
     (number) => !openNumbers.has(number),
   )
@@ -389,13 +393,11 @@ function describeIssue(raw: Issue, context: Context): MapIssue {
   }
 }
 
-/** 把快照塞進樣板。回傳的是 artifact 用的片段（沒有 doctype／html／head／body）。 */
 /**
  * 把畫面那一支打包成一段可以直接放進 `<script>` 的程式碼。
  *
- * 產出必須是**一個檔案**（artifact 的頁面就是一份 HTML），但來源不必——來源是 TypeScript，
- * 所以型別跟這裡共用同一份定義，而且純推導測得到。`format: 'iife'` 是因為它要塞進行內；
- * 不 minify 是因為這是開發用的頁面，讀得懂比小重要。
+ * 產出必須是一個檔案，但來源不必——來源是 TypeScript，所以型別跟這裡共用同一份定義，而且純
+ * 推導測得到。`format: 'iife'` 是因為它要塞進行內；不 minify 是因為這是開發用的頁面。
  */
 async function bundleClient(): Promise<string> {
   const built = await Bun.build({
@@ -410,6 +412,56 @@ async function bundleClient(): Promise<string> {
   return output.text()
 }
 
+/**
+ * 把樣板裡某個容器的內容填掉。
+ *
+ * 樣板裡這些容器都是空的（`<div id="x"></div>`），所以只要在開頭標籤與結尾標籤之間插入即可，
+ * 不必真的剖析 HTML。填不到就是樣板被改壞了，直接喊。
+ */
+function fillById(html: string, id: string, body: string): string {
+  // 標籤名要吃得到數字，`h1`、`h2` 都是容器。
+  const marker = new RegExp(`(<[a-z][a-z0-9]*[^>]*\\sid="${id}"[^>]*>)(</[a-z][a-z0-9]*>)`)
+  const next = html.replace(marker, `$1${body}$2`)
+  if (next === html) throw new Error(`Template is missing an empty #${id}: ${TEMPLATE}`)
+  return next
+}
+
+/**
+ * 建置時就把整頁畫好。
+ *
+ * 標記由 `issue-map-view.ts` 產生，畫面那一支重畫時用的是同一批函式——所以沒有 JS 的環境看到的
+ * 是同一份頁面，只是不能互動。少了這一步，擋掉 inline script 的地方（嚴格 CSP、某些預覽窗）
+ * 拿到的會是一份空骨架。
+ *
+ * 預設語言是英文；換語言要有 JS，那本來就不是靜態檔能做的事。
+ */
+function prerender(html: string, snapshot: Snapshot): string {
+  const view = viewOf(snapshot)
+  const foot = view.footerHTML()
+  const detail = view.detailPanelHTML(view.defaultPick())
+  const rows = view.rowsHTML('all')
+  const title = view.title()
+  const filled: [string, string][] = [
+    ['eyebrow', esc(view.eyebrow())],
+    ['page-title', esc(title)],
+    ['lede', view.lede()],
+    ['stats', view.statsHTML()],
+    ['detail', detail.html],
+    ['groups', view.groupsHTML()],
+    ['list-title', esc(t('list.title'))],
+    ['list-sub', esc(t('list.count', { n: rows.shown }))],
+    ['tabs', view.tabsHTML('all')],
+    ['rows', rows.html],
+    ['foot-truth', foot.truth],
+    ['foot-refresh', foot.refresh],
+    ['foot-config', foot.config],
+    ['lang', LOCALES.map((l) => `<option value="${l}">${esc(LOCALE_NAME[l])}</option>`).join('')],
+  ]
+  const withBody = filled.reduce((acc, [id, body]) => fillById(acc, id, body), html)
+  return replaceIn(withBody, /(<title>)[\s\S]*?(<\/title>)/, esc(title), 'title')
+}
+
+/** 把快照塞進樣板。回傳的是 artifact 用的片段（沒有 doctype／html／head／body）。 */
 export async function renderFragment(snapshot: Snapshot): Promise<string> {
   const template = await Bun.file(TEMPLATE).text()
   const withData = replaceIn(
@@ -419,8 +471,9 @@ export async function renderFragment(snapshot: Snapshot): Promise<string> {
     JSON.stringify(snapshot).replaceAll('<', '\\u003c'),
     'issue-map-data',
   )
+  const withPage = prerender(withData, snapshot)
   return replaceIn(
-    withData,
+    withPage,
     /(<script id="issue-map-code">)[\s\S]*?(<\/script>)/,
     // 程式碼不能這樣逃脫——`a < b` 會被改壞。只擋真正會提早收尾的那一個序列。
     (await bundleClient()).replace(/<\/script/gi, '<\\/script'),
@@ -428,6 +481,18 @@ export async function renderFragment(snapshot: Snapshot): Promise<string> {
   )
 }
 
+/**
+ * 把片段包成一份完整文件。**直接開檔案看的一律走這裡**：少了 doctype 瀏覽器會進 quirks mode。
+ * charset 是防禦性的——從 `file://` 開沒有 header 可依靠，而這一頁帶著四種語言的文案。
+ *
+ * `lang` 是預設語言；頁面上換語言時畫面那一支會改掉 `documentElement.lang`。
+ */
+export async function renderDocument(snapshot: Snapshot): Promise<string> {
+  const head =
+    '<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">'
+  return `<!doctype html><html lang="en"><head>${head}</head><body>${await renderFragment(snapshot)}</body></html>`
+}
+
 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(`Template is missing the ${what} block: ${TEMPLATE}`)
@@ -441,6 +506,6 @@ export function describe(snapshot: Snapshot): string {
 
 if (import.meta.main) {
   const snapshot = takeSnapshot()
-  await Bun.write(OUTPUT, await renderFragment(snapshot))
+  await Bun.write(OUTPUT, await renderDocument(snapshot))
   console.log(`Wrote ${OUTPUT}: ${describe(snapshot)}`)
 }