issue-map 0.3.0 → 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,34 +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。後者畫成「已完成」
- * 的節點讓進度看得見，沒人牽著之後自然消失。
- *
- * **要畫哪個 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,
@@ -37,13 +24,16 @@ 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
 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)
@@ -55,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 有值時優先用原生的。 */
@@ -96,50 +85,186 @@ 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[]
+}
+
+/** 票號查不到（號碼其實是 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 } }
+`
+
+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`。
+ *
+ * 票號是我們自己從前一次結果拿到的整數，直接組進查詢字串；只有 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' })
+  return dataOrThrow<T>(result.stdout.toString(), result.stderr.toString())
 }
-interface QueryResult {
-  repository: { nameWithOwner: string } & Record<'open' | 'closed', Connection>
+
+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 }
 }
 
-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 } }
+/** alias 不能以數字開頭，所以票號前面補一個 `i`。 */
+const alias = (number: number) => `i${number}`
+
+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
+}
 
-/** 一次問完 repo 名字與兩種狀態的 issue，只開一個 `gh` 行程。 */
-const QUERY = `
+/** 指名要哪幾張票，一批 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 這裡是空的（檔頭說的那個
+ * 代價）。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 +275,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 +284,15 @@ 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，理由見檔頭。
+  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 +309,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 +317,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
 }
@@ -266,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({
@@ -281,12 +406,62 @@ 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()
 }
 
+/**
+ * 把樣板裡某個容器的內容填掉。
+ *
+ * 樣板裡這些容器都是空的（`<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(
@@ -296,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'),
@@ -305,19 +481,31 @@ 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(`樣板缺少 ${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)}`)
+  await Bun.write(OUTPUT, await renderDocument(snapshot))
+  console.log(`Wrote ${OUTPUT}: ${describe(snapshot)}`)
 }