issue-map 0.3.1 → 0.5.0
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.
- package/README.ja.md +87 -111
- package/README.md +94 -115
- package/README.zh-CN.md +80 -81
- package/README.zh-TW.md +80 -81
- package/package.json +10 -15
- package/{scripts → src}/issue-map-i18n.ts +11 -5
- package/{scripts → src}/issue-map-model.ts +55 -26
- package/src/issue-map-page.ts +411 -0
- package/{scripts → src}/issue-map-serve.ts +33 -19
- package/src/issue-map-view.ts +694 -0
- package/{scripts → src}/issue-map.html +33 -6
- package/src/issue-map.ts +657 -0
- package/scripts/issue-map-page.ts +0 -991
- package/scripts/issue-map.ts +0 -446
package/README.ja.md
CHANGED
|
@@ -7,161 +7,137 @@
|
|
|
7
7
|
GitHub Issues のブロック関係を 1 ページの開発マップにします：**いま着手できるのはどれか、どれが
|
|
8
8
|
何を待っているか、クリティカルパスはどこを通るか。**
|
|
9
9
|
|
|
10
|
-
状態の正は常に GitHub Issues です。このページはスナップショットにすぎず、ここでは状態を変えられ
|
|
11
|
-
ません——だから 2 つ目の正が生まれません。
|
|
12
|
-
|
|
13
|
-
## なぜこれを作ったか
|
|
14
|
-
|
|
15
|
-
出発点は [mattpocock/skills](https://github.com/mattpocock/skills) です。「ワークフローを skill と
|
|
16
|
-
して書き、agent に走らせる」というやり方をチームで採り入れてから、チケットを起票するコストが
|
|
17
|
-
下がりました。思いついたら 1 枚起票して skill に渡す。結果としてチケットは一気に増えます。それは
|
|
18
|
-
プロセスが機能している証拠であって、問題ではありません。
|
|
19
|
-
|
|
20
|
-
問題は次の一手です。Agent は 1 ラウンドに 1 枚しか扱えないので、毎ラウンド実際に決めるのは**どれを
|
|
21
|
-
渡すか**です。その答えはどの 1 枚の中にもなく、チケットとチケットの間にあります——誰が誰を
|
|
22
|
-
ブロックしているか、親はあと何枚のサブチケットを待っているか、いちばん長い鎖は何段か。GitHub
|
|
23
|
-
Issues は一度に 1 枚しか見せてくれないので、その絵を組み立てるには 1 枚ずつ開くしかなく、しかも
|
|
24
|
-
明日もまた同じことをします。
|
|
25
|
-
|
|
26
|
-
このページがその絵です。
|
|
27
|
-
|
|
28
|
-
## 使い方
|
|
29
|
-
|
|
30
|
-
**見たい repo の中で**実行します：
|
|
31
|
-
|
|
32
10
|
```bash
|
|
33
11
|
bunx issue-map@latest
|
|
34
12
|
```
|
|
35
13
|
|
|
36
|
-
|
|
14
|
+
見たい repo の中で実行します。ブラウザのタブが開き、更新するたびに GitHub を取り直します。状態の
|
|
15
|
+
正は常に GitHub Issues——このページはスナップショットで、状態は変えられません。
|
|
37
16
|
|
|
38
|
-
|
|
39
|
-
ので、見えているのは常に現在の状態です。repo は `gh` が cwd の git から推測するため、指定は不要
|
|
40
|
-
です。
|
|
17
|
+
## なぜこれを作ったか
|
|
41
18
|
|
|
42
|
-
|
|
19
|
+
Agent は 1 ラウンドに 1 枚しか扱えないので、毎ラウンド実際に決めるのは**どれを渡すか**です。その
|
|
20
|
+
答えはどの 1 枚の中にもなく、チケットとチケットの間にあります——誰が誰をブロックしているか、親は
|
|
21
|
+
あと何枚のサブチケットを待っているか、いちばん長い鎖は何段か。GitHub は一度に 1 枚しか見せてくれ
|
|
22
|
+
ません。このページがその絵です。
|
|
43
23
|
|
|
44
|
-
|
|
45
|
-
|
|
24
|
+
[mattpocock/skills](https://github.com/mattpocock/skills) のやり方——ワークフローを skill として
|
|
25
|
+
書き、agent に走らせる——を前提に作っており、既定のラベルとコマンドもそこから来ています。
|
|
46
26
|
|
|
47
|
-
|
|
48
|
-
bunx -p issue-map@latest issue-map-build # dist/issue-map.html に書き出す
|
|
49
|
-
bunx -p issue-map@latest issue-map-build out.html
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
スナップショットはスナップショットです——状態は古くなります。いまの状態を見たいときは上の server
|
|
53
|
-
を使ってください。
|
|
27
|
+
## 使い方
|
|
54
28
|
|
|
55
|
-
|
|
29
|
+
| コマンド | 得られるもの |
|
|
30
|
+
| --------------------------------------------------- | ---------------------------------------- |
|
|
31
|
+
| `bunx issue-map@latest` | 空き port で server 起動、ブラウザも開く |
|
|
32
|
+
| `bunx -p issue-map@latest issue-map-build` | 静的ファイルを `dist/issue-map.html` へ |
|
|
33
|
+
| `bunx -p issue-map@latest issue-map-build out.html` | 静的ファイルを指定したパスへ |
|
|
56
34
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
35
|
+
- repo は `gh` が cwd の git から推測するので、指定は不要です。
|
|
36
|
+
- `ISSUE_MAP_PORT` で port を固定できます。固定は厳密で、埋まっていれば黙って移らず失敗します。
|
|
37
|
+
- `ISSUE_MAP_OPEN=0` でタブを開きません。
|
|
38
|
+
- 静的ファイルは古くなります。いまの状態を見たいときは server を使ってください。
|
|
39
|
+
- スクリプトが動かせない場所（厳しい CSP、一部のプレビュー）では、空白ではなくチケットの
|
|
40
|
+
プレーンな一覧にフォールバックします。
|
|
41
|
+
- `@latest` は npm 上の最新版です。固定するなら `bunx issue-map@0.2.0`。
|
|
61
42
|
|
|
62
|
-
|
|
43
|
+
## 前提条件
|
|
63
44
|
|
|
64
|
-
- `
|
|
65
|
-
|
|
66
|
-
-
|
|
67
|
-
そうでなければ、欠けたものが `{n}` のまま画面に出てしまい、そのマスに到達して初めて気づくことに
|
|
68
|
-
なります。
|
|
69
|
-
- 英語で単複を分けるキーは `{ one, other }` で書き、中国語と日本語は 1 本の文字列で構いません
|
|
70
|
-
（`Intl.PluralRules` はこれらの言語では `other` しか返しません）。
|
|
45
|
+
- **Bun**——`Bun.build`、`Bun.serve`、`Bun.file` を使っているので、Node では動きません。
|
|
46
|
+
- **`gh` CLI にログイン済み**で、対象 repo への読み取り権限があること。
|
|
47
|
+
- 対象 repo に GitHub を指す git remote があること。
|
|
71
48
|
|
|
72
|
-
|
|
73
|
-
`{ kind: 'waitChildren', count: 2 }` のような構造化された値で、グループ名も同じです。言葉になるのは
|
|
74
|
-
i18n の層です。スナップショットに文を保存していたら、言語を切り替えるたびに GitHub を取り直す
|
|
75
|
-
ことになります。
|
|
49
|
+
runtime 依存はありません。
|
|
76
50
|
|
|
77
|
-
|
|
78
|
-
`bunx issue-map` の出力であり、コマンドを打った人が読むもので、ページの一部ではありません。
|
|
79
|
-
例外は `scripts/mutate.ts` で、この repo 内部のツールなので中国語のままです。
|
|
51
|
+
## 言語
|
|
80
52
|
|
|
81
|
-
|
|
53
|
+
右上で切り替えます：英語（既定）、繁体字中国語、簡体字中国語、日本語。選んだ言語はブラウザに記憶
|
|
54
|
+
され、repo ごとではありません——言語は読む人の好みであって、プロジェクトの設定ではないからです。
|
|
82
55
|
|
|
83
|
-
|
|
84
|
-
動きません。
|
|
85
|
-
- **`gh` CLI にログイン済み**で、対象 repo への読み取り権限があること。
|
|
86
|
-
- 対象 repo に GitHub を指す git remote があること。
|
|
87
|
-
- runtime 依存はなし。devDependencies は型と lint／format のツールだけです。
|
|
56
|
+
CLI 側（生成メッセージ、エラー）は英語のみです。
|
|
88
57
|
|
|
89
58
|
## 設定
|
|
90
59
|
|
|
91
|
-
すべて既定値があり、何も設定しなくても動きます。既定値は `
|
|
60
|
+
すべて既定値があり、何も設定しなくても動きます。既定値は `src/issue-map.ts` の `CONFIG` に
|
|
92
61
|
あります。
|
|
93
62
|
|
|
94
|
-
| 環境変数 | 既定 | 意味
|
|
95
|
-
| -------------------------- | --------------------------------- |
|
|
96
|
-
| `GH_REPO` | cwd の git から推測 | 別の repo を描くときに設定（`gh` 自身の変数。fork
|
|
97
|
-
| `ISSUE_MAP_PARENT_HEADING` |
|
|
98
|
-
| `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info` |
|
|
99
|
-
| `ISSUE_MAP_LABELS_READY` | `ready-for-agent,ready-for-human` |
|
|
100
|
-
| `ISSUE_MAP_LABELS_ACTIVE` | `in-progress` |
|
|
101
|
-
| `ISSUE_MAP_LABELS_HUMAN` | `ready-for-human` | 人がやるもの。次の一手に実装コマンドを出さない
|
|
102
|
-
| `ISSUE_MAP_CMD_IMPLEMENT` | `/implement` | 着手できるときにマップが促すコマンド
|
|
103
|
-
| `ISSUE_MAP_CMD_TRIAGE` | `/triage` | まだ評価が要るときにマップが促すコマンド
|
|
104
|
-
| `ISSUE_MAP_PORT` |
|
|
105
|
-
| `ISSUE_MAP_OPEN` | 有効 | `0`
|
|
63
|
+
| 環境変数 | 既定 | 意味 |
|
|
64
|
+
| -------------------------- | --------------------------------- | ---------------------------------------------------------- |
|
|
65
|
+
| `GH_REPO` | cwd の git から推測 | 別の repo を描くときに設定（`gh` 自身の変数。fork も同様） |
|
|
66
|
+
| `ISSUE_MAP_PARENT_HEADING` | 未設定（本文は取得しない） | サブチケットが本文で親を指す見出し。設定すると本文を読む |
|
|
67
|
+
| `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info` | 未評価で、まだ誰にも渡せない |
|
|
68
|
+
| `ISSUE_MAP_LABELS_READY` | `ready-for-agent,ready-for-human` | 評価済み・着手可 |
|
|
69
|
+
| `ISSUE_MAP_LABELS_ACTIVE` | `in-progress` | 誰かが対応中（assignee がなくてもよい） |
|
|
70
|
+
| `ISSUE_MAP_LABELS_HUMAN` | `ready-for-human` | 人がやるもの。次の一手に実装コマンドを出さない |
|
|
71
|
+
| `ISSUE_MAP_CMD_IMPLEMENT` | `/implement` | 着手できるときにマップが促すコマンド |
|
|
72
|
+
| `ISSUE_MAP_CMD_TRIAGE` | `/triage` | まだ評価が要るときにマップが促すコマンド |
|
|
73
|
+
| `ISSUE_MAP_PORT` | OS が割り当てる空き port | server のポート |
|
|
74
|
+
| `ISSUE_MAP_OPEN` | 有効 | `0` にするとブラウザを開かない |
|
|
106
75
|
|
|
107
76
|
とくに考えておくべきものが 3 つ：
|
|
108
77
|
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
78
|
+
- **ラベルの語彙。** ready／unready の既定値は mattpocock/skills の 5 つの[標準 triage ラベル](https://github.com/mattpocock/skills/blob/main/skills/engineering/setup-matt-pocock-skills/triage-labels.md)
|
|
79
|
+
のうち 4 つです。対象 repo が別の名前を使っているなら差し替えてください。これらのラベルが 1 つも
|
|
80
|
+
現れないときは triage をゲートにしません。そうしないと全チケットが「未評価」になってしまいます
|
|
81
|
+
（`in-progress` はこのツール独自で、skill 側に「対応中」のラベルはありません）。
|
|
82
|
+
- **コマンド名。** `/implement` と `/triage` は向こうの [`implement`](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement) と
|
|
83
|
+
[`triage`](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage) skill です。対象 repo に実在するものを指すようにしてください。さもないと、
|
|
84
|
+
存在しないものを走らせろとマップが指示します。
|
|
85
|
+
- **本文の慣習はオプトイン。** 本文は GitHub のレスポンスの 9 割以上を占めるのに、正規表現
|
|
86
|
+
ひとつを通すだけで、ページの他のどこでも使われません。そのため `ISSUE_MAP_PARENT_HEADING`
|
|
87
|
+
を設定したときだけ本文を取得します。ネイティブ sub-issue は設定不要で、常に優先されます。
|
|
88
|
+
- **クローズ済みの兄弟にはネイティブ sub-issue が要る。** マップが問い合わせるクローズ済みチケット
|
|
89
|
+
は、open なチケットがまだ指しているものだけで、子チケットはネイティブの sub-issue 関係から取り
|
|
90
|
+
ます。`## Parent` の本文慣例を使う repo ではグループ内の**クローズ済み**の子が出てこず、進捗が
|
|
91
|
+
実際より少なく見えます。チケットの Sub-issues で一度リンクし直せば戻ります。本文の慣例は残して
|
|
92
|
+
おいて構いません——ネイティブのほうが優先されます。
|
|
122
93
|
|
|
123
94
|
## よくある失敗
|
|
124
95
|
|
|
125
|
-
|
|
126
|
-
|
|
96
|
+
`gh api graphql failed: …` — `gh` にログインしていないか、cwd が対象 repo の git ツリーの中に
|
|
97
|
+
ありません。
|
|
127
98
|
|
|
128
99
|
## ファイル
|
|
129
100
|
|
|
130
|
-
| ファイル
|
|
131
|
-
|
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
101
|
+
| ファイル | 責務 |
|
|
102
|
+
| ------------------------ | ---------------------------------------------------------------------- |
|
|
103
|
+
| `src/issue-map.ts` | スナップショット取得、状態と次の一手の導出、HTML 生成。設定は `CONFIG` |
|
|
104
|
+
| `src/issue-map-model.ts` | 純粋なデータモデル：グルーピング、クリティカルパス、レイアウト |
|
|
105
|
+
| `src/issue-map-i18n.ts` | 4 言語の文言と引き当て |
|
|
106
|
+
| `src/issue-map-page.ts` | ブラウザ側のコード。ビルド時に HTML へバンドルされる |
|
|
107
|
+
| `src/issue-map.html` | テンプレート。2 つのプレースホルダが埋められる |
|
|
108
|
+
| `src/issue-map-serve.ts` | ローカル server。リクエストごとに取り直す |
|
|
109
|
+
| `tools/mutate.ts` | ミューテーションテスト：1 行を壊してテストが赤くなるか見る |
|
|
139
110
|
|
|
140
111
|
## この repo で開発する
|
|
141
112
|
|
|
142
113
|
```bash
|
|
143
114
|
bun install
|
|
144
|
-
bun run issue-map:serve # --watch
|
|
115
|
+
bun run issue-map:serve # --watch。ブラウザは開かない（保存のたびにタブが増えるため）
|
|
145
116
|
bun run issue-map # dist/issue-map.html を生成するだけ
|
|
146
117
|
bun run check # lint + format:check + typecheck
|
|
147
|
-
bun test #
|
|
118
|
+
bun test # 純粋なモデル層
|
|
148
119
|
```
|
|
149
120
|
|
|
150
121
|
この repo 自体にはまだ issue がないので、`GH_REPO=<owner>/<repo>` でチケットのある repo を指さない
|
|
151
122
|
と何も描けません。
|
|
152
123
|
|
|
153
|
-
`tests/`
|
|
154
|
-
|
|
155
|
-
|
|
124
|
+
**テスト。** `tests/` が守るのは「マップが嘘をつく」「読めなくなる」ことだけで、見た目（色・形・
|
|
125
|
+
間隔）は意図的に検証しません。ガードテストを足すときは逆検証で——そのテストが防ぐと主張する欠陥を
|
|
126
|
+
製品コードに戻し、赤くなることを確かめます：
|
|
156
127
|
|
|
157
128
|
```bash
|
|
158
|
-
bun run mutate
|
|
129
|
+
bun run mutate src/issue-map-model.ts tests/issue-map-layout.test.ts
|
|
159
130
|
```
|
|
160
131
|
|
|
161
|
-
|
|
132
|
+
**`src/issue-map-i18n.ts` を触るとき。** `EN` が原稿であり、キーの定義場所です。3 つの翻訳の型
|
|
133
|
+
はそこから導かれるので、キーや `{n}` の差し込み名が 1 つ欠けると `bun run typecheck` が赤くなります。
|
|
134
|
+
英語で単複を分けるキーは `{ one, other }`、中国語と日本語は 1 本の文字列で構いません。モデル側は文
|
|
135
|
+
を組み立てません——`nextStep` は `{ kind: 'waitChildren', count: 2 }` のような構造化された値で、
|
|
136
|
+
言葉になるのはここです。
|
|
137
|
+
|
|
138
|
+
## 2 つの設計判断
|
|
162
139
|
|
|
163
|
-
- **このページでは状態を変えられません。** GitHub
|
|
164
|
-
|
|
165
|
-
-
|
|
166
|
-
|
|
167
|
-
せん。機械的に短縮したものは読めませんでした。
|
|
140
|
+
- **このページでは状態を変えられません。** GitHub に書き戻すボタンはありません。状態の正は 1 つだけ
|
|
141
|
+
で、入口が増えれば必ず食い違います。
|
|
142
|
+
- **短縮名の欄は設けません。** 駅にはタイトルの先頭数文字を出します。本文に短縮名を手で書くと
|
|
143
|
+
タイトルの 2 つ目の正になり、タイトルを直しても追随しません。完全なタイトルは下の一覧にあります。
|
package/README.md
CHANGED
|
@@ -5,161 +5,140 @@
|
|
|
5
5
|
Draws the blocking relationships between your GitHub Issues as a one-page dev map: **which issues
|
|
6
6
|
can be picked up now, which are waiting on what, and where the critical path runs.**
|
|
7
7
|
|
|
8
|
-
GitHub Issues stays the source of truth. This page is only a snapshot — you cannot change status on
|
|
9
|
-
it, so no second source of truth grows out of it.
|
|
10
|
-
|
|
11
|
-
## Why this exists
|
|
12
|
-
|
|
13
|
-
It started with [mattpocock/skills](https://github.com/mattpocock/skills). Once the team adopted
|
|
14
|
-
that way of working — write the workflow as a skill, let the agent run it — filing an issue got
|
|
15
|
-
cheap: think of something, open a ticket, hand it to a skill. So the issue count grew fast. That is
|
|
16
|
-
the process working, not a problem.
|
|
17
|
-
|
|
18
|
-
The problem is the next step. An agent takes one issue per round, so what you actually decide each
|
|
19
|
-
round is **which one**. That answer is in no single issue; it lives between them: who blocks whom,
|
|
20
|
-
how many sub-issues a parent is still waiting on, how long the longest chain is. GitHub Issues only
|
|
21
|
-
ever shows you one issue at a time, so assembling that picture means opening them one by one — and
|
|
22
|
-
doing it again tomorrow.
|
|
23
|
-
|
|
24
|
-
This page is that picture.
|
|
25
|
-
|
|
26
|
-
## Usage
|
|
27
|
-
|
|
28
|
-
Run it inside **the repo you want to look at**:
|
|
29
|
-
|
|
30
8
|
```bash
|
|
31
9
|
bunx issue-map@latest
|
|
32
10
|
```
|
|
33
11
|
|
|
34
|
-
|
|
12
|
+
Run it inside the repo you want to look at. A browser tab opens; every refresh re-fetches from
|
|
13
|
+
GitHub. GitHub Issues stays the source of truth — this page is a snapshot and cannot change status.
|
|
35
14
|
|
|
36
|
-
|
|
37
|
-
so what you see is the current state. The repo is what `gh` infers from the git remote in your cwd —
|
|
38
|
-
nothing to fill in.
|
|
15
|
+
## Why
|
|
39
16
|
|
|
40
|
-
|
|
17
|
+
An agent takes one issue per round, so what you decide each round is **which one**. That answer is
|
|
18
|
+
in no single issue; it lives between them — who blocks whom, how many sub-issues a parent is still
|
|
19
|
+
waiting on, how long the longest chain is. GitHub shows you one issue at a time. This page shows
|
|
20
|
+
the picture.
|
|
41
21
|
|
|
42
|
-
|
|
43
|
-
|
|
22
|
+
It is built around [mattpocock/skills](https://github.com/mattpocock/skills) — write the workflow
|
|
23
|
+
as a skill, let the agent run it — which is where the default labels and commands come from.
|
|
44
24
|
|
|
45
|
-
|
|
46
|
-
bunx -p issue-map@latest issue-map-build # writes dist/issue-map.html
|
|
47
|
-
bunx -p issue-map@latest issue-map-build out.html
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
A snapshot is a snapshot — it goes stale. Use the server above when you need the current state.
|
|
25
|
+
## Usage
|
|
51
26
|
|
|
52
|
-
|
|
27
|
+
| Command | What you get |
|
|
28
|
+
| --------------------------------------------------- | ------------------------------------ |
|
|
29
|
+
| `bunx issue-map@latest` | Server on a free port, browser opens |
|
|
30
|
+
| `bunx -p issue-map@latest issue-map-build` | Static file at `dist/issue-map.html` |
|
|
31
|
+
| `bunx -p issue-map@latest issue-map-build out.html` | Static file at a path you name |
|
|
53
32
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
33
|
+
- The repo comes from `gh` reading the git remote in your cwd — nothing to fill in.
|
|
34
|
+
- `ISSUE_MAP_PORT` pins the port. Pinned is strict: it fails rather than moving if taken.
|
|
35
|
+
- `ISSUE_MAP_OPEN=0` stops the browser tab.
|
|
36
|
+
- A static file goes stale. Use the server when you need the current state.
|
|
37
|
+
- Where scripts cannot run (a strict CSP, some preview panes) the file falls back to a plain
|
|
38
|
+
listing of the issues rather than a blank page.
|
|
39
|
+
- `@latest` takes the newest version on npm; pin one with `bunx issue-map@0.2.0`.
|
|
59
40
|
|
|
60
|
-
|
|
41
|
+
## Requirements
|
|
61
42
|
|
|
62
|
-
-
|
|
63
|
-
|
|
64
|
-
-
|
|
65
|
-
and it will not compile. Otherwise the missing one prints as a literal `{n}` on the page, and
|
|
66
|
-
you would only find it by reaching that exact cell.
|
|
67
|
-
- Keys that need English plurals are written `{ one, other }`; Chinese and Japanese take a single
|
|
68
|
-
string (`Intl.PluralRules` only has `other` for those languages).
|
|
43
|
+
- **Bun** — these scripts use `Bun.build`, `Bun.serve` and `Bun.file`; Node will not run them.
|
|
44
|
+
- **`gh` CLI, logged in**, with read access to the target repo.
|
|
45
|
+
- A git remote pointing at GitHub.
|
|
69
46
|
|
|
70
|
-
|
|
71
|
-
`{ kind: 'waitChildren', count: 2 }`, and so are group names. The words are assembled in the i18n
|
|
72
|
-
layer. If the snapshot stored sentences, switching language would mean re-fetching from GitHub.
|
|
47
|
+
No runtime dependencies.
|
|
73
48
|
|
|
74
|
-
|
|
75
|
-
setting: it is the output of `bunx issue-map`, read by whoever ran the command, not part of the
|
|
76
|
-
page. `scripts/mutate.ts` is the exception — it is an in-repo tool, so it stays Chinese.
|
|
49
|
+
## Language
|
|
77
50
|
|
|
78
|
-
|
|
51
|
+
Switch in the top right: English (default), 繁體中文, 简体中文, 日本語. The choice is remembered in
|
|
52
|
+
the browser and is not tied to a repo — language is the reader's preference, not a project setting.
|
|
79
53
|
|
|
80
|
-
|
|
81
|
-
not run them.
|
|
82
|
-
- **`gh` CLI, logged in**, with read access to the target repo.
|
|
83
|
-
- The target repo has a git remote pointing at GitHub.
|
|
84
|
-
- No runtime dependencies; devDependencies are only types and lint/format tools.
|
|
54
|
+
CLI output (build messages, errors) is English only.
|
|
85
55
|
|
|
86
56
|
## Configuration
|
|
87
57
|
|
|
88
58
|
Everything has a default — it runs with nothing set. The defaults live in `CONFIG` in
|
|
89
|
-
`
|
|
90
|
-
|
|
91
|
-
| Environment variable | Default | Meaning
|
|
92
|
-
| -------------------------- | --------------------------------- |
|
|
93
|
-
| `GH_REPO` | inferred from the git in cwd |
|
|
94
|
-
| `ISSUE_MAP_PARENT_HEADING` |
|
|
95
|
-
| `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info` |
|
|
96
|
-
| `ISSUE_MAP_LABELS_READY` | `ready-for-agent,ready-for-human` |
|
|
97
|
-
| `ISSUE_MAP_LABELS_ACTIVE` | `in-progress` |
|
|
98
|
-
| `ISSUE_MAP_LABELS_HUMAN` | `ready-for-human` |
|
|
99
|
-
| `ISSUE_MAP_CMD_IMPLEMENT` | `/implement` |
|
|
100
|
-
| `ISSUE_MAP_CMD_TRIAGE` | `/triage` |
|
|
101
|
-
| `ISSUE_MAP_PORT` |
|
|
102
|
-
| `ISSUE_MAP_OPEN` | on |
|
|
103
|
-
|
|
104
|
-
Three worth
|
|
105
|
-
|
|
106
|
-
- **Label vocabulary
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
59
|
+
`src/issue-map.ts`.
|
|
60
|
+
|
|
61
|
+
| Environment variable | Default | Meaning |
|
|
62
|
+
| -------------------------- | --------------------------------- | ------------------------------------------------------------------------------ |
|
|
63
|
+
| `GH_REPO` | inferred from the git in cwd | Map another repo (`gh`'s own variable; forks and multiple remotes are its job) |
|
|
64
|
+
| `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 |
|
|
65
|
+
| `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info` | Not assessed yet, cannot be handed to anyone |
|
|
66
|
+
| `ISSUE_MAP_LABELS_READY` | `ready-for-agent,ready-for-human` | Assessed and ready to work on |
|
|
67
|
+
| `ISSUE_MAP_LABELS_ACTIVE` | `in-progress` | Somebody is on it, with or without an assignee |
|
|
68
|
+
| `ISSUE_MAP_LABELS_HUMAN` | `ready-for-human` | Needs a person, so the next step is not an implementation command |
|
|
69
|
+
| `ISSUE_MAP_CMD_IMPLEMENT` | `/implement` | Command the map suggests when an issue is ready |
|
|
70
|
+
| `ISSUE_MAP_CMD_TRIAGE` | `/triage` | Command the map suggests when it still needs assessing |
|
|
71
|
+
| `ISSUE_MAP_PORT` | an OS-assigned free port | Port for the server |
|
|
72
|
+
| `ISSUE_MAP_OPEN` | on | `0` stops the browser tab |
|
|
73
|
+
|
|
74
|
+
Three worth knowing:
|
|
75
|
+
|
|
76
|
+
- **Label vocabulary.** The ready/unready defaults are four of the five canonical
|
|
77
|
+
[triage labels](https://github.com/mattpocock/skills/blob/main/skills/engineering/setup-matt-pocock-skills/triage-labels.md)
|
|
78
|
+
from mattpocock/skills. If the target repo uses different names, set them. When none of these
|
|
79
|
+
labels appear at all, triage stops being a gate — otherwise every issue would come out as "needs
|
|
80
|
+
triage". (`in-progress` is this tool's own; the skills have no "somebody is on it" label.)
|
|
81
|
+
- **Command names.** `/implement` and `/triage` are the
|
|
82
|
+
[`implement`](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement) and
|
|
83
|
+
[`triage`](https://github.com/mattpocock/skills/tree/main/skills/engineering/triage) skills. Point
|
|
84
|
+
them at something that exists in the target repo, or the map tells people to run what isn't there.
|
|
85
|
+
- **The body convention is opt-in.** Issue bodies are over 90% of what the GitHub response
|
|
86
|
+
weighs, and they feed one regex — nothing else on the page uses them. So they are only fetched
|
|
87
|
+
when `ISSUE_MAP_PARENT_HEADING` is set. Native sub-issues need no setting and always win.
|
|
88
|
+
- **Closed siblings need native sub-issues.** The map asks GitHub only for the closed issues an
|
|
89
|
+
open one still points at, and children come from the native sub-issue relation. With the
|
|
90
|
+
`## Parent` body convention a group's _closed_ children never appear, so its progress looks
|
|
91
|
+
smaller than it is. Linking them once in the issue's Sub-issues panel brings them back; the body
|
|
92
|
+
convention can stay, the native relation wins anyway.
|
|
120
93
|
|
|
121
94
|
## When it fails
|
|
122
95
|
|
|
123
|
-
|
|
124
|
-
|
|
96
|
+
`gh api graphql failed: …` — `gh` is not logged in, or your cwd is not inside the target repo's git
|
|
97
|
+
tree.
|
|
125
98
|
|
|
126
99
|
## Files
|
|
127
100
|
|
|
128
|
-
| File
|
|
129
|
-
|
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
101
|
+
| File | Responsibility |
|
|
102
|
+
| ------------------------ | ------------------------------------------------------------------------ |
|
|
103
|
+
| `src/issue-map.ts` | Snapshot, status and next step, produces the HTML. Knobs in its `CONFIG` |
|
|
104
|
+
| `src/issue-map-model.ts` | Pure data model: grouping, critical path, layout. Shared by both sides |
|
|
105
|
+
| `src/issue-map-i18n.ts` | Strings for the four languages, plus the lookup |
|
|
106
|
+
| `src/issue-map-page.ts` | Browser-side code, bundled into the HTML at build time |
|
|
107
|
+
| `src/issue-map.html` | The template. Two placeholder blocks get filled in |
|
|
108
|
+
| `src/issue-map-serve.ts` | Local server, re-fetches on every request |
|
|
109
|
+
| `tools/mutate.ts` | Mutation testing: break one line, see whether a test goes red |
|
|
137
110
|
|
|
138
111
|
## Developing in this repo
|
|
139
112
|
|
|
140
113
|
```bash
|
|
141
114
|
bun install
|
|
142
|
-
bun run issue-map:serve # --watch
|
|
115
|
+
bun run issue-map:serve # --watch; no browser tab (you would get one per save)
|
|
143
116
|
bun run issue-map # build the file only, to dist/issue-map.html
|
|
144
117
|
bun run check # lint + format:check + typecheck
|
|
145
|
-
bun test # the pure model layer
|
|
118
|
+
bun test # the pure model layer
|
|
146
119
|
```
|
|
147
120
|
|
|
148
121
|
This repo has no issues of its own yet, so point `GH_REPO=<owner>/<repo>` at one that has tickets to
|
|
149
122
|
get anything drawn.
|
|
150
123
|
|
|
151
|
-
`tests/` only guards
|
|
152
|
-
spacing) are deliberately not asserted. A new guard test has to be verified in reverse — put
|
|
153
|
-
defect it claims to catch back into the product code and confirm it goes red:
|
|
124
|
+
**Tests.** `tests/` only guards what would make the map lie or make it unreadable; looks (colour,
|
|
125
|
+
shape, spacing) are deliberately not asserted. A new guard test has to be verified in reverse — put
|
|
126
|
+
the defect it claims to catch back into the product code and confirm it goes red:
|
|
154
127
|
|
|
155
128
|
```bash
|
|
156
|
-
bun run mutate
|
|
129
|
+
bun run mutate src/issue-map-model.ts tests/issue-map-layout.test.ts
|
|
157
130
|
```
|
|
158
131
|
|
|
159
|
-
|
|
132
|
+
**Adding to `src/issue-map-i18n.ts`.** `EN` is the original and defines the keys; the three
|
|
133
|
+
translations are typed from it, so a missing key or a missing `{n}` placeholder turns
|
|
134
|
+
`bun run typecheck` red. Keys needing English plurals are written `{ one, other }`; Chinese and
|
|
135
|
+
Japanese take a single string. The model never builds sentences — `nextStep` is a structured value
|
|
136
|
+
like `{ kind: 'waitChildren', count: 2 }`, assembled into words here.
|
|
137
|
+
|
|
138
|
+
## Two design decisions
|
|
160
139
|
|
|
161
|
-
- **
|
|
162
|
-
|
|
163
|
-
- **
|
|
164
|
-
short
|
|
165
|
-
|
|
140
|
+
- **The page cannot change status.** No button writes back to GitHub. Status has exactly one source
|
|
141
|
+
of truth, and a second entry point makes them disagree.
|
|
142
|
+
- **No separate short name.** Stations are labelled with the first few characters of the title.
|
|
143
|
+
A hand-maintained short name in the issue body would be a second source of truth — editing the
|
|
144
|
+
title would not update it. The list below carries the full titles.
|