issue-timeline 0.0.0-stage → 1.0.0-beta.3

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.
@@ -0,0 +1,67 @@
1
+ # Contributing to issue-timeline
2
+
3
+ Thanks for taking the time to contribute. This project is read-only by design, so most useful changes are
4
+ visualizations, analysis, provider support and performance.
5
+
6
+ ## Getting started
7
+
8
+ Requirements: Node.js 22 or newer, npm.
9
+
10
+ ```sh
11
+ git clone https://github.com/system4us/issue-timeline.git
12
+ cd issue-timeline
13
+ npm run install:all
14
+ npm test
15
+ ```
16
+
17
+ Run it locally with `REPO=owner/name npm run dev:server` (API on port 4310) and `npm run dev:web` (Vite on port 5173).
18
+
19
+ ## Project layout
20
+
21
+ - `server/src/`: the Node service (no runtime dependencies). Providers (`github.js`, `gitlab.js`), sync (`sync.js`),
22
+ derived data (`derive.js`), storage (`store.js`) and the HTTP API (`index.js`).
23
+ - `server/test/`: server tests, using `node:test` and a fake GitHub client.
24
+ - `web/src/`: the React frontend. Timeline, analysis, filters and detail views. Pure logic (`filters.ts`, `metrics.ts`,
25
+ `lanes.ts`, `timeScale.ts`) lives next to its tests.
26
+
27
+ ## Before you open a pull request
28
+
29
+ 1. `npm test` passes (server and frontend).
30
+ 2. `npm run build` passes (it type-checks with `tsc`).
31
+ 3. New logic has tests. Pure functions are preferred over logic inside components.
32
+ 4. The change is focused. One feature or fix per pull request.
33
+ 5. The commit messages say what changed and why, in the imperative mood ("add blocker chain analysis").
34
+
35
+ ## Guidelines
36
+
37
+ - **Keep the server dependency-free** unless there is a strong reason. It is a deliberate property of the project.
38
+ - **Read-only first.** Changes that write to GitHub or GitLab need a design discussion before code.
39
+ - **Never commit secrets or data.** Tokens, certificates, `data/` and downloaded store files must stay out of the
40
+ repository. Check `git status` before committing.
41
+ - **Keep both providers in mind.** A feature for GitHub should either work for GitLab or say clearly why it doesn't.
42
+
43
+ ## Reporting bugs
44
+
45
+ Open an issue with:
46
+
47
+ - what you did, what you expected, and what happened
48
+ - the provider (GitHub or GitLab, and the instance for self-managed)
49
+ - the version (from `package.json`, or the npm version you used) and your Node version
50
+ - a minimal reproduction, or the relevant part of the store file with private data removed
51
+
52
+ Do not paste tokens, private repository content or certificates into an issue.
53
+
54
+ ## Proposing features
55
+
56
+ Open an issue describing the problem before the solution. Explain who it helps and what the view should show. Small
57
+ ideas are welcome in the same way.
58
+
59
+ ## Security
60
+
61
+ If you find a security issue, do not open a public issue. Contact the maintainers privately first. Note that the local
62
+ API currently has no authentication, so exposing it beyond `127.0.0.1` without your own access control is a known
63
+ limitation, not a vulnerability to report.
64
+
65
+ ## License
66
+
67
+ By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE).
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 system4us
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,159 @@
1
- # Temporary Holding Version
1
+ # issue-timeline
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **See the whole story of your backlog.** issue-timeline turns the issues and pull/merge requests of your GitHub and
4
+ GitLab projects into an interactive timeline: when work was opened, how it moved, what blocks what, and where the
5
+ bottlenecks are. Read-only, self-hosted, one command to run.
6
+
7
+ > **Beta (`1.0.0-beta.1`).** The local API has no authentication and storage is plain JSON. Run it on `127.0.0.1` or
8
+ > behind your own access control. See [Roadmap](#roadmap).
9
+
10
+ ---
11
+
12
+ ## Why issue-timeline
13
+
14
+ Issue lists tell you what is open today. They don't tell you how the work actually flowed. issue-timeline does:
15
+
16
+ - **See bursts and droughts.** Work arrives in waves. A horizontal timeline shows every issue and pull request as a bar
17
+ from creation to close or merge, so you can spot the week everything stalled.
18
+ - **Read dependencies at a glance.** Blockers are drawn as arrows, blocked items are marked, and each item shows how many
19
+ open issues sit behind it, all the way down the chain.
20
+ - **Track epics without guessing.** Progress is computed from the real state of each child, not from checkboxes someone
21
+ forgot to tick. Sub-issues and task lists both count.
22
+ - **Answer the questions that matter.** Open issues over time, created vs closed per week, days to close, days to merge,
23
+ PRs merged without review, the oldest open issues, and per-milestone, per-label or per-author breakdowns.
24
+ - **Share a view.** Filters live in the URL. Copy it, send it, reload it, and your teammate sees exactly what you see.
25
+
26
+ ## Features
27
+
28
+ ### Timeline
29
+ - Horizontal, draggable timeline with logarithmic zoom and a one-click fit.
30
+ - Two time axes: **event order** (every creation, close or merge gets the same width, so nothing is hidden by a
31
+ long quiet period) and **real time**, with idle stretches collapsed into a "N days without activity" marker.
32
+ - Open items fade into the present; closed items keep their full length.
33
+ - Issue ↔ pull request links, highlighted on hover or selection.
34
+ - Filters by text, state, milestone, labels (any or all), authors, assignees, dates, and linked/unlinked PRs.
35
+ - Group rows by milestone, label or author. The axis adapts to what is on screen.
36
+
37
+ ### Hierarchy and dependencies
38
+ - **Epics and children:** native GitHub sub-issues and the task lists written in epic descriptions. Parents show a
39
+ `▸closed/total` counter and a progress line; their children light up on hover, listed open-first in the tooltip.
40
+ - **Blockers:** native relations (GitHub "blocked by / blocks", GitLab issue links "blocks / is blocked by") and
41
+ plain-language references in descriptions ("Depends on #N", "Blocked by #N", "Blocks #N", "Depende de #N", "Bloquea #N"…).
42
+ Red arrows for open blockers, grey dashed for resolved ones. The words are a vocabulary, see below.
43
+ - **Chain analysis:** how many issues are stuck behind each blocker, transitively.
44
+
45
+ ### Analysis
46
+ - Open issues over time, created vs closed per week.
47
+ - Time to close and time to merge, with medians and p90.
48
+ - PR size against merge time.
49
+ - Issues with and without a linked PR.
50
+ - PRs merged without a review.
51
+ - A comparison table for every milestone, label, author or assignee: progress, open, median and p90 close time,
52
+ merged PRs, open without PR, oldest open item, and due dates. Click a row to filter the whole app by it.
53
+
54
+ ### Built to run anywhere
55
+ - **Node service with zero dependencies** (Node 22+). Polls GitHub GraphQL or GitLab REST every 5 minutes.
56
+ - **Full history on the first pass:** issues and PRs/MRs with comments, events, commits, and reviews/approvals.
57
+ Incremental syncs after that.
58
+ - **Multiple repositories**, switchable from the header, each stored separately.
59
+ - **Atomic JSON storage**, one file per repository. Easy to back up, inspect and move.
60
+ - Published as an **npm package**.
61
+
62
+ ## Quick start
63
+
64
+ ```sh
65
+ npx issue-timeline@beta
66
+ ```
67
+
68
+ It opens http://127.0.0.1:4310 in your browser (`--no-open` to skip); add a repository from the page. Data is kept in
69
+ your user folder (`~/.local/share/issue-timeline` on Linux, `~/Library/Application Support/issue-timeline` on macOS,
70
+ `%APPDATA%\issue-timeline` on Windows), not in the folder you run it from; set `STORE_DIR` to change it.
71
+
72
+ To keep it running after you close the terminal: `npx issue-timeline --background`, and `issue-timeline stop` to stop it.
73
+
74
+
75
+ ### Authentication
76
+
77
+ issue-timeline signs in with the sessions you already have: the **GitHub CLI** (`gh auth login`) and the **GitLab CLI**
78
+ (`glab auth login`, once per instance). Nothing to configure, it only reads, and it never stores your tokens. The
79
+ startup message shows which of the two it found. Tokens in the environment work too, for machines without the CLIs.
80
+
81
+ - **GitHub:** set `GITHUB_TOKEN`, or log in with `gh auth login`. Private repositories need the `repo` scope. You can add
82
+ `owner/repo` or paste the repository URL. For GitHub Enterprise Server set `GITHUB_HOST` (one instance per run).
83
+ - **GitLab:** log in with `glab auth login` for each instance, then add `group/project` (GitLab.com) or the full URL
84
+ of a self-managed instance.
85
+
86
+ ### Configuration
87
+
88
+ | Variable | Default | Purpose |
89
+ | -------------- | ------------- | ---------------------------------------------------- |
90
+ | `PORT` | `4310` | HTTP port |
91
+ | `HOST` | `127.0.0.1` | Bind address |
92
+ | `STORE_DIR` | user data folder | Where repository data and the repo list are kept |
93
+ | `POLL_MINUTES` | `5` | Sync interval |
94
+ | `GITHUB_TOKEN` | from `gh` | GitHub token |
95
+ | `GITHUB_HOST` | `github.com` | GitHub Enterprise Server host (REST and GraphQL URLs follow) |
96
+ | `GITLAB_TOKEN` | from `glab` | GitLab.com token; `GITLAB_TOKEN_<HOST>` for self-managed |
97
+ | `VOCABULARY_FILE` | built-in | JSON file with your own words for dependencies, fields and CI workflows (see below) |
98
+
99
+ ### Vocabulary
100
+
101
+ Issue bodies say things like "Depends on #12" or "Bloqueado por #9", and "Design: …" or "Diseño: …" lines. Those words
102
+ are a list in [`server/src/vocabulary.json`](server/src/vocabulary.json), with English, Spanish, Portuguese, French and
103
+ German by default. To use your own words, write a JSON file with any of these keys and set `VOCABULARY_FILE` to its path.
104
+ Each key you give replaces the default list for that key; the rest keep the defaults.
105
+
106
+ ```json
107
+ {
108
+ "blockedBy": ["waits for"],
109
+ "blocks": ["unblocks"],
110
+ "fieldKeys": ["Ticket", "Spec"],
111
+ "ci": { "otherWorkflows": ["nightly", "deploy"] }
112
+ }
113
+ ```
114
+
115
+ - `blockedBy`: phrases that mean "blocked by / depends on" (the issue is blocked by the number that follows).
116
+ - `blocks`: phrases that mean "blocks" (the number that follows is blocked by this issue).
117
+ - `fieldKeys`: keys shown as fields of the detail panel.
118
+ - `ci.otherWorkflows`: workflows that are not a PR's CI (releases, deploys, docs, ...), matched as whole words.
119
+
120
+ The same file is used by the frontend, which receives it with the data.
121
+
122
+ ## API
123
+
124
+ - `GET /api/data`: lightweight records, links and sync status
125
+ - `GET /api/issues/:n`, `GET /api/pulls/:n`: full record for one item
126
+ - `POST /api/sync[?full=1]`: trigger a sync
127
+
128
+ ## Development
129
+
130
+ ```sh
131
+ npm run install:all # frontend dependencies
132
+ REPO=owner/name npm run dev:server # API on :4310
133
+ npm run dev:web # Vite on :5173, proxied to the API
134
+ npm test # server and frontend tests
135
+ ```
136
+
137
+ ## Roadmap
138
+
139
+ - Editing from the timeline (labels, close, comment) through GraphQL mutations
140
+ - Webhooks instead of polling
141
+ - Project and milestone events
142
+ - Velocity per person
143
+ - SQLite storage once the JSON files grow
144
+ - Parallel sync for large repositories (a first full sync of a large repo takes about 2 minutes today)
145
+
146
+ ## Notes
147
+
148
+ - The interface is in English. Issue bodies are read with the vocabulary above (English, Spanish, Portuguese, French,
149
+ German by default); a language not in it needs `VOCABULARY_FILE`.
150
+ - Not read: GitLab epics (a Premium feature) and the parent of an issue in GitLab. A dependency written only in a comment
151
+ is not read either.
152
+ - Links from commits are read from the title: a "#N" that matches an issue links the commit to it. This is a heuristic.
153
+ - A GitLab issue's links are read when the issue is synced. If a link added later does not show after an incremental
154
+ sync, a full sync (`POST /api/sync?full=1`) reads it.
155
+ - Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
156
+
157
+ ## License
158
+
159
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,47 @@
1
1
  {
2
2
  "name": "issue-timeline",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0-beta.3",
4
+ "description": "Read-only timeline of GitHub and GitLab issues and pull/merge requests, with analysis, hierarchy and dependencies.",
5
+ "type": "module",
6
+ "bin": {
7
+ "issue-timeline": "server/src/index.js"
8
+ },
9
+ "license": "MIT",
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/system4us/issue-timeline.git"
13
+ },
14
+ "homepage": "https://github.com/system4us/issue-timeline#readme",
15
+ "bugs": {
16
+ "url": "https://github.com/system4us/issue-timeline/issues"
17
+ },
18
+ "keywords": [
19
+ "issues",
20
+ "pull-requests",
21
+ "timeline",
22
+ "github",
23
+ "gitlab",
24
+ "project-management",
25
+ "dependencies",
26
+ "analytics"
27
+ ],
28
+ "files": [
29
+ "server/src",
30
+ "web/dist",
31
+ "README.md",
32
+ "LICENSE",
33
+ "CONTRIBUTING.md"
34
+ ],
35
+ "scripts": {
36
+ "install:all": "npm install --prefix web",
37
+ "dev:server": "node server/src/index.js",
38
+ "dev:web": "npm run dev --prefix web",
39
+ "build": "npm run build --prefix web",
40
+ "start": "node server/src/index.js",
41
+ "test": "node --test server/src/*.test.js server/test/*.test.js && npm test --prefix web",
42
+ "prepack": "npm run install:all && npm run build"
43
+ },
44
+ "engines": {
45
+ "node": ">=22"
46
+ }
47
+ }
@@ -0,0 +1,159 @@
1
+ // CI runs, kept apart from the issues and the commits. Only what the timeline needs is summarized per pull request:
2
+ // whether its commits ran CI, the state of the last run and a link to it. The runs themselves stay in their own file
3
+ // and are not shown one by one. Dependabot, Pages and release/tag workflows are a separate category, never a PR's CI.
4
+
5
+ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
6
+ import { githubEndpoints } from "./github.js";
7
+ import { compile, vocabulary } from "./vocabulary.js";
8
+
9
+ export const CI_DAYS = Number(process.env.CI_DAYS ?? 90); // how far back the runs are kept
10
+ const CI_EVENTS = new Set(["pull_request", "push", "workflow_dispatch", "merge_group", "pull_request_target", "schedule"]);
11
+
12
+ const OTHER = compile(vocabulary).otherWorkflows;
13
+
14
+ /**
15
+ * The category of a run: "ci", "dependabot", "pages", or "other" (releases, tags, deploys: the names in vocabulary.json).
16
+ * Words are matched whole, so a workflow called "Stage" is not a tag.
17
+ */
18
+ export function categorize({ name = "", path = "", event = "", actor = "" }) {
19
+ if (/dependabot/i.test(`${path} ${actor}`)) return "dependabot";
20
+ if (/pages/i.test(`${path} ${name}`)) return "pages";
21
+ if (OTHER.test(`${name} ${path}`)) return "other";
22
+ return CI_EVENTS.has(event) ? "ci" : "other";
23
+ }
24
+
25
+ const STATE = {
26
+ success: "passed", failure: "failed", failed: "failed", skipped: "skipped", cancelled: "cancelled", canceled: "cancelled",
27
+ timed_out: "failed", action_required: "pending", neutral: "passed", stale: "cancelled",
28
+ };
29
+ /** The state a run shows: "running" while it has no conclusion yet, otherwise the mapped conclusion. */
30
+ export function stateOf(run) {
31
+ if (!run.conclusion) return "running";
32
+ return STATE[run.conclusion] ?? run.conclusion;
33
+ }
34
+
35
+ /** GitHub Actions runs created since `since` (a date, yyyy-mm-dd), newest first. */
36
+ export async function githubRuns({ token, owner, name, since, fetchImpl = fetch }) {
37
+ const day = since.slice(0, 10); // the API filters by date
38
+ const out = [];
39
+ for (let page = 1; page <= 100; page++) {
40
+ const res = await fetchImpl(`${githubEndpoints().rest}/repos/${owner}/${name}/actions/runs?per_page=100&page=${page}&created=${encodeURIComponent(`>=${day}`)}`, {
41
+ headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "user-agent": "issue-timeline" },
42
+ });
43
+ if (!res.ok) throw new Error(`GitHub ${res.status} reading the Actions runs: ${(await res.text()).slice(0, 160)}`);
44
+ const body = await res.json();
45
+ for (const r of body.workflow_runs ?? []) {
46
+ const run = {
47
+ id: String(r.id), url: r.html_url, name: r.name ?? "", path: r.path ?? "", event: r.event ?? "",
48
+ actor: r.actor?.login ?? "", branch: r.head_branch ?? null, sha: r.head_sha, status: r.status, conclusion: r.conclusion ?? null, at: r.created_at,
49
+ };
50
+ out.push({ ...run, category: categorize(run) });
51
+ }
52
+ if ((body.workflow_runs ?? []).length < 100) break;
53
+ }
54
+ return out;
55
+ }
56
+
57
+ // GitLab's pipeline "source" in the words GitHub uses for the same trigger. A merge request pipeline is the PR's CI.
58
+ const GITLAB_SOURCE = { merge_request_event: "pull_request", external_pull_request_event: "pull_request" };
59
+
60
+ /**
61
+ * GitLab pipelines updated since `since` (ISO time), normalized like the GitHub runs. The branch goes in `branch`, not in
62
+ * `path`: `categorize` reads `path` for the workflow file, and a branch named "pages-redesign" must not look like Pages.
63
+ */
64
+ export function gitlabRunOf(p) {
65
+ const event = GITLAB_SOURCE[p.source] ?? p.source ?? "";
66
+ const run = { id: String(p.id), url: p.web_url, name: "pipeline", path: "", event, actor: "", branch: p.ref ?? null, sha: p.sha, status: p.status, conclusion: p.status, at: p.created_at };
67
+ return { ...run, category: categorize(run) };
68
+ }
69
+
70
+ /** Each pull request: the state of its last CI run, with the link to it. Only "ci" runs count; the others are summarized apart. */
71
+ export function summarize({ runs, pulls }) {
72
+ const prOfSha = new Map();
73
+ for (const p of Object.values(pulls)) for (const c of p.commits ?? []) if (!prOfSha.has(c.oid)) prOfSha.set(c.oid, p.number);
74
+ const byPr = {};
75
+ for (const run of runs) {
76
+ if (run.category !== "ci") continue;
77
+ const pr = prOfSha.get(run.sha);
78
+ if (!pr) continue;
79
+ const entry = byPr[pr] ?? (byPr[pr] = { count: 0, last: null });
80
+ entry.count++;
81
+ if (!entry.last || run.at > entry.last.at) entry.last = run;
82
+ }
83
+ const out = {};
84
+ for (const [pr, { count, last }] of Object.entries(byPr)) {
85
+ out[pr] = { state: stateOf(last), url: last.url, at: last.at, count };
86
+ }
87
+ // Each other kind of workflow: how many runs, and the last one.
88
+ const other = {};
89
+ for (const run of runs) {
90
+ if (run.category === "ci") continue;
91
+ const entry = other[run.category] ?? (other[run.category] = { count: 0, last: null });
92
+ entry.count++;
93
+ if (!entry.last || run.at > entry.last.at) entry.last = { url: run.url, at: run.at, state: stateOf(run), name: run.name };
94
+ }
95
+ return { byPr: out, other, lastRunAt: runs.reduce((m, r) => (r.at > m ? r.at : m), "") || null };
96
+ }
97
+
98
+ /** The CI store: one JSON file with the runs of the window. */
99
+ export class CiStore {
100
+ constructor(file) { this.file = file; this.data = { meta: { repo: null, lastSync: null }, runs: [], changes: [] }; this.writing = Promise.resolve(); }
101
+
102
+ async load() {
103
+ try {
104
+ const parsed = JSON.parse(await readFile(this.file, "utf8"));
105
+ this.data = { meta: { repo: null, lastSync: null, ...parsed.meta }, runs: parsed.runs ?? [], changes: parsed.changes ?? [] };
106
+ } catch (e) { if (e.code !== "ENOENT") throw e; }
107
+ return this;
108
+ }
109
+
110
+ /** Adds the runs read now (replacing the same ids), keeps the rest of the window (from `floor` on), and drops what fell out of it. */
111
+ merge(repo, fresh, floor, at) {
112
+ if (this.data.meta.repo !== repo) this.data = { meta: { repo: null, lastSync: null }, runs: [] };
113
+ const seen = new Set(fresh.map((r) => r.id));
114
+ const kept = this.data.runs.filter((r) => !seen.has(r.id) && r.at >= floor);
115
+ this.data = { meta: { repo, lastSync: at }, runs: [...fresh.filter((r) => r.at >= floor), ...kept].sort((a, b) => (b.at > a.at ? 1 : -1)), changes: this.data.changes ?? [] };
116
+ }
117
+
118
+ save() {
119
+ this.writing = this.writing.then(async () => {
120
+ await mkdir(this.file.replace(/[\\/][^\\/]*$/, ""), { recursive: true });
121
+ const tmp = `${this.file}.tmp`;
122
+ await writeFile(tmp, JSON.stringify(this.data));
123
+ await rename(tmp, this.file);
124
+ });
125
+ return this.writing;
126
+ }
127
+ }
128
+
129
+ /** The oldest run kept: CI_DAYS back. The window is always this, whatever the sync. */
130
+ export function windowFloor(now) {
131
+ return new Date(now - CI_DAYS * 86_400_000).toISOString();
132
+ }
133
+
134
+ /** Where this sync starts reading the host: the window, or a day before the last sync (a later sync reads less). */
135
+ export function readFrom(now, meta) {
136
+ const floor = Date.parse(windowFloor(now));
137
+ const incremental = meta.lastSync ? Date.parse(meta.lastSync) - 86_400_000 : floor;
138
+ return new Date(Math.max(incremental, floor)).toISOString();
139
+ }
140
+
141
+ /** The commits that changed the CI definition on GitHub (the workflow files) since `since`, newest first. */
142
+ export async function githubWorkflowChanges({ token, owner, name, since, fetchImpl = fetch }) {
143
+ const out = [];
144
+ for (let page = 1; page <= 10; page++) {
145
+ const res = await fetchImpl(`${githubEndpoints().rest}/repos/${owner}/${name}/commits?path=${encodeURIComponent(".github/workflows")}&since=${encodeURIComponent(since)}&per_page=100&page=${page}`, {
146
+ headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "user-agent": "issue-timeline" },
147
+ });
148
+ if (!res.ok) throw new Error(`GitHub ${res.status} reading the workflow commits: ${(await res.text()).slice(0, 160)}`);
149
+ const rows = await res.json();
150
+ for (const c of rows) {
151
+ out.push({
152
+ sha: c.sha, title: (c.commit?.message ?? "").split("\n")[0], author: c.author?.login ?? c.commit?.author?.name ?? null,
153
+ at: c.commit?.committer?.date ?? c.commit?.author?.date ?? null, url: c.html_url,
154
+ });
155
+ }
156
+ if (rows.length < 100) break;
157
+ }
158
+ return out;
159
+ }
@@ -0,0 +1,62 @@
1
+ import { test } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { categorize, stateOf, summarize, windowFloor, readFrom, gitlabRunOf } from "./ci.js";
4
+
5
+ test("GitLab: a merge request pipeline is the MR's CI; a branch name never decides the category", () => {
6
+ const mr = gitlabRunOf({ id: 1, web_url: "u", ref: "feature/x", sha: "h7", status: "success", source: "merge_request_event", created_at: "2026-01-01T10:00:00Z" });
7
+ assert.equal(mr.category, "ci");
8
+ const push = gitlabRunOf({ id: 2, web_url: "u", ref: "main", sha: "m1", status: "success", source: "push", created_at: "2026-01-01T10:00:00Z" });
9
+ assert.equal(push.category, "ci");
10
+ const branchNamedPages = gitlabRunOf({ id: 3, web_url: "u", ref: "pages-redesign", sha: "h8", status: "failed", source: "merge_request_event", created_at: "2026-01-01T10:00:00Z" });
11
+ assert.equal(branchNamedPages.category, "ci", "the branch name must not turn an MR's CI into Pages");
12
+ assert.equal(branchNamedPages.branch, "pages-redesign");
13
+ const summary = summarize({ runs: [mr], pulls: { 7: { number: 7, commits: [{ oid: "h7" }] } } });
14
+ assert.equal(summary.byPr[7].state, "passed");
15
+ });
16
+
17
+ test("categories: CI events, and Dependabot / Pages / releases apart", () => {
18
+ assert.equal(categorize({ name: "CI", path: ".github/workflows/ci.yml", event: "pull_request" }), "ci");
19
+ assert.equal(categorize({ name: "CI", path: ".github/workflows/ci.yml", event: "push" }), "ci");
20
+ assert.equal(categorize({ name: "npm_and_yarn in /site", path: "dynamic/dependabot/dependabot-updates", event: "dynamic", actor: "dependabot[bot]" }), "dependabot");
21
+ assert.equal(categorize({ name: "pages build and deployment", path: "dynamic/pages/pages-build-deployment", event: "dynamic" }), "pages");
22
+ assert.equal(categorize({ name: "Release", path: ".github/workflows/release.yml", event: "push" }), "other");
23
+ assert.equal(categorize({ name: "Tag", path: ".github/workflows/tag.yml", event: "push" }), "other");
24
+ });
25
+
26
+ test("states: a run with no conclusion is running; skipped stays skipped", () => {
27
+ assert.equal(stateOf({ conclusion: null }), "running");
28
+ assert.equal(stateOf({ conclusion: "success" }), "passed");
29
+ assert.equal(stateOf({ conclusion: "failure" }), "failed");
30
+ assert.equal(stateOf({ conclusion: "skipped" }), "skipped");
31
+ assert.equal(stateOf({ conclusion: "cancelled" }), "cancelled");
32
+ });
33
+
34
+ const pulls = {
35
+ 7: { number: 7, commits: [{ oid: "h7" }] },
36
+ 8: { number: 8, commits: [{ oid: "h8" }] },
37
+ 9: { number: 9, commits: [] },
38
+ };
39
+
40
+ test("a PR gets the state of its last CI run, with its link; other workflows are not its CI", () => {
41
+ const runs = [
42
+ { id: "1", sha: "h7", category: "ci", conclusion: "failure", url: "u1", at: "2026-01-01T10:00:00Z" },
43
+ { id: "2", sha: "h7", category: "ci", conclusion: "success", url: "u2", at: "2026-01-01T11:00:00Z" },
44
+ { id: "3", sha: "h8", category: "ci", conclusion: "skipped", url: "u3", at: "2026-01-02T10:00:00Z" },
45
+ { id: "4", sha: "h7", category: "dependabot", conclusion: "success", url: "u4", at: "2026-01-03T10:00:00Z" },
46
+ { id: "5", sha: "main1", category: "pages", conclusion: "success", url: "u5", name: "pages", at: "2026-01-03T11:00:00Z" },
47
+ ];
48
+ const s = summarize({ runs, pulls });
49
+ assert.deepEqual(s.byPr[7], { state: "passed", url: "u2", at: "2026-01-01T11:00:00Z", count: 2 });
50
+ assert.deepEqual(s.byPr[8], { state: "skipped", url: "u3", at: "2026-01-02T10:00:00Z", count: 1 });
51
+ assert.equal(s.byPr[9], undefined, "a PR without runs has no CI entry");
52
+ assert.equal(s.other.dependabot.count, 1);
53
+ assert.equal(s.other.pages.last.url, "u5");
54
+ });
55
+
56
+ test("the window is always CI_DAYS back; a sync reads from a day before the last one, never before the window", () => {
57
+ const now = Date.parse("2026-03-01T00:00:00Z");
58
+ assert.equal(windowFloor(now), new Date(now - 90 * 86_400_000).toISOString());
59
+ assert.equal(readFrom(now, { lastSync: null }), windowFloor(now));
60
+ assert.equal(readFrom(now, { lastSync: "2026-02-28T12:00:00Z" }), "2026-02-27T12:00:00.000Z");
61
+ assert.equal(readFrom(now, { lastSync: "2025-01-01T00:00:00Z" }), windowFloor(now), "an old last sync cannot reach before the window");
62
+ });
@@ -0,0 +1,87 @@
1
+ // Command line behaviour: where the data lives, opening the browser, running in the background.
2
+ import { spawn, spawnSync } from "node:child_process";
3
+ import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
4
+ import { homedir } from "node:os";
5
+ import { join } from "node:path";
6
+
7
+ export const HELP = `issue-timeline: a timeline of the issues and pull/merge requests of GitHub and GitLab repositories
8
+
9
+ Usage: issue-timeline [options]
10
+ issue-timeline stop
11
+
12
+ -b, --background keep running after the terminal closes (logs in the data folder)
13
+ --no-open do not open the browser
14
+ -h, --help show this help
15
+
16
+ Sign-in: it uses your existing sessions, nothing to configure. GitHub: gh auth login (or GITHUB_TOKEN).
17
+ GitLab: glab auth login (or GITLAB_TOKEN). It only reads, and never stores your tokens.
18
+
19
+ Environment: PORT, HOST, STORE_DIR, POLL_MINUTES, GITHUB_TOKEN, GITHUB_HOST, VOCABULARY_FILE. See the README.`;
20
+
21
+ export function parseArgs(argv) {
22
+ const has = (...names) => names.some((n) => argv.includes(n));
23
+ return { help: has("-h", "--help"), background: has("-b", "--background"), noOpen: has("--no-open"), stop: argv[0] === "stop" };
24
+ }
25
+
26
+ /**
27
+ * Where the data is kept: STORE_DIR; the ./data of the current folder when it already holds a repository list (the
28
+ * layout before this default existed); otherwise a folder of the user, so running the command in a project does not
29
+ * drop a data folder inside it.
30
+ */
31
+ export function defaultStoreDir({ env = process.env, cwd = process.cwd(), platform = process.platform, home = homedir() } = {}) {
32
+ if (env.STORE_DIR) return env.STORE_DIR;
33
+ if (existsSync(join(cwd, "data", "repos.json"))) return join(cwd, "data");
34
+ if (platform === "win32") return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "issue-timeline");
35
+ if (platform === "darwin") return join(home, "Library", "Application Support", "issue-timeline");
36
+ return join(env.XDG_DATA_HOME ?? join(home, ".local", "share"), "issue-timeline");
37
+ }
38
+
39
+ /** Opens a URL in the default browser. Best effort: a headless machine just keeps the printed URL. */
40
+ export function openBrowser(url, { platform = process.platform, spawnImpl = spawn } = {}) {
41
+ const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
42
+ try {
43
+ const child = spawnImpl(cmd, args, { stdio: "ignore", detached: true });
44
+ child.on?.("error", () => {});
45
+ child.unref?.();
46
+ } catch { /* no browser available */ }
47
+ }
48
+
49
+ /** Should the browser open by itself? Not in CI, not over a non-interactive pipe, not when asked not to. */
50
+ export function shouldOpen({ noOpen, env = process.env, isTTY = process.stdout.isTTY } = {}) {
51
+ return !noOpen && Boolean(isTTY) && !env.CI && !env.NO_OPEN;
52
+ }
53
+
54
+ const pidFile = (dir) => join(dir, "issue-timeline.pid");
55
+
56
+ /** Starts this same command detached, with its output in <dir>/issue-timeline.log, and returns its pid. */
57
+ export function startBackground({ dir, argv, script }) {
58
+ mkdirSync(dir, { recursive: true });
59
+ const log = openSync(join(dir, "issue-timeline.log"), "a");
60
+ const rest = argv.filter((a) => a !== "-b" && a !== "--background");
61
+ const child = spawn(process.execPath, [script, ...rest, "--no-open"], {
62
+ detached: true, stdio: ["ignore", log, log], env: { ...process.env, STORE_DIR: dir, ISSUE_TIMELINE_CHILD: "1" },
63
+ });
64
+ child.unref();
65
+ writeFileSync(pidFile(dir), String(child.pid));
66
+ return child.pid;
67
+ }
68
+
69
+ export function stopBackground(dir) {
70
+ let pid;
71
+ try { pid = Number(readFileSync(pidFile(dir), "utf8")); } catch { return null; }
72
+ try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
73
+ rmSync(pidFile(dir), { force: true });
74
+ return pid;
75
+ }
76
+
77
+ const loggedIn = (cmd, args, run) => { try { return run(cmd, args, { stdio: "ignore", timeout: 5000 }).status === 0; } catch { return false; } };
78
+
79
+ /** How each host is signed in, for the startup message. Never prints a token. */
80
+ export function authSummary({ env = process.env, run = spawnSync } = {}) {
81
+ const github = env.GITHUB_TOKEN ? "GITHUB_TOKEN" : loggedIn("gh", ["auth", "status"], run) ? "gh session" : null;
82
+ const gitlab = env.GITLAB_TOKEN ? "GITLAB_TOKEN" : loggedIn("glab", ["auth", "status"], run) ? "glab session" : null;
83
+ return [
84
+ `GitHub: ${github ?? "not signed in. Run `gh auth login` or set GITHUB_TOKEN"}`,
85
+ `GitLab: ${gitlab ?? "not signed in. Run `glab auth login` or set GITLAB_TOKEN"}`,
86
+ ];
87
+ }
@@ -0,0 +1,35 @@
1
+ import { test } from "node:test";
2
+ import assert from "node:assert/strict";
3
+ import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
4
+ import { tmpdir } from "node:os";
5
+ import { join } from "node:path";
6
+ import { defaultStoreDir, parseArgs, shouldOpen } from "./cli.js";
7
+
8
+ test("data folder: STORE_DIR, then a previous ./data, then a user folder", () => {
9
+ const cwd = mkdtempSync(join(tmpdir(), "it-"));
10
+ const home = "/home/u";
11
+ assert.equal(defaultStoreDir({ env: { STORE_DIR: "/x" }, cwd, home }), "/x");
12
+ assert.equal(defaultStoreDir({ env: {}, cwd, platform: "linux", home }), "/home/u/.local/share/issue-timeline");
13
+ assert.equal(defaultStoreDir({ env: { XDG_DATA_HOME: "/xdg" }, cwd, platform: "linux", home }), "/xdg/issue-timeline");
14
+ assert.equal(defaultStoreDir({ env: {}, cwd, platform: "darwin", home }), "/home/u/Library/Application Support/issue-timeline");
15
+ mkdirSync(join(cwd, "data")); writeFileSync(join(cwd, "data", "repos.json"), "[]");
16
+ assert.equal(defaultStoreDir({ env: {}, cwd, home }), join(cwd, "data"));
17
+ });
18
+
19
+ test("arguments and when the browser opens", () => {
20
+ assert.deepEqual(parseArgs(["-b", "--no-open"]), { help: false, background: true, noOpen: true, stop: false });
21
+ assert.equal(parseArgs(["stop"]).stop, true);
22
+ assert.equal(shouldOpen({ noOpen: false, env: {}, isTTY: true }), true);
23
+ assert.equal(shouldOpen({ noOpen: true, env: {}, isTTY: true }), false);
24
+ assert.equal(shouldOpen({ noOpen: false, env: { CI: "1" }, isTTY: true }), false);
25
+ assert.equal(shouldOpen({ noOpen: false, env: {}, isTTY: false }), false);
26
+ });
27
+
28
+ import { authSummary } from "./cli.js";
29
+
30
+ test("startup auth summary: env tokens, CLI sessions or a hint", () => {
31
+ const ok = () => ({ status: 0 }), no = () => ({ status: 1 });
32
+ assert.deepEqual(authSummary({ env: {}, run: ok }), ["GitHub: gh session", "GitLab: glab session"]);
33
+ assert.deepEqual(authSummary({ env: { GITHUB_TOKEN: "x", GITLAB_TOKEN: "y" }, run: no }), ["GitHub: GITHUB_TOKEN", "GitLab: GITLAB_TOKEN"]);
34
+ assert.match(authSummary({ env: {}, run: no })[1], /glab auth login/);
35
+ });