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

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,151 @@
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
66
+ ```
67
+
68
+ Then open http://127.0.0.1:4310 and add a repository from the UI.
69
+
70
+
71
+ ### Authentication
72
+
73
+ - **GitHub:** set `GITHUB_TOKEN`, or log in with `gh auth login`. Private repositories need the `repo` scope. You can add
74
+ `owner/repo` or paste the repository URL. For GitHub Enterprise Server set `GITHUB_HOST` (one instance per run).
75
+ - **GitLab:** log in with `glab auth login` for each instance, then add `group/project` (GitLab.com) or the full URL
76
+ of a self-managed instance.
77
+
78
+ ### Configuration
79
+
80
+ | Variable | Default | Purpose |
81
+ | -------------- | ------------- | ---------------------------------------------------- |
82
+ | `PORT` | `4310` | HTTP port |
83
+ | `HOST` | `127.0.0.1` | Bind address |
84
+ | `STORE_DIR` | `./data` | Where repository data and the repo list are kept |
85
+ | `POLL_MINUTES` | `5` | Sync interval |
86
+ | `GITHUB_TOKEN` | from `gh` | GitHub token |
87
+ | `GITHUB_HOST` | `github.com` | GitHub Enterprise Server host (REST and GraphQL URLs follow) |
88
+ | `GITLAB_TOKEN` | from `glab` | GitLab.com token; `GITLAB_TOKEN_<HOST>` for self-managed |
89
+ | `VOCABULARY_FILE` | built-in | JSON file with your own words for dependencies, fields and CI workflows (see below) |
90
+
91
+ ### Vocabulary
92
+
93
+ Issue bodies say things like "Depends on #12" or "Bloqueado por #9", and "Design: …" or "Diseño: …" lines. Those words
94
+ are a list in [`server/src/vocabulary.json`](server/src/vocabulary.json), with English, Spanish, Portuguese, French and
95
+ German by default. To use your own words, write a JSON file with any of these keys and set `VOCABULARY_FILE` to its path.
96
+ Each key you give replaces the default list for that key; the rest keep the defaults.
97
+
98
+ ```json
99
+ {
100
+ "blockedBy": ["waits for"],
101
+ "blocks": ["unblocks"],
102
+ "fieldKeys": ["Ticket", "Spec"],
103
+ "ci": { "otherWorkflows": ["nightly", "deploy"] }
104
+ }
105
+ ```
106
+
107
+ - `blockedBy`: phrases that mean "blocked by / depends on" (the issue is blocked by the number that follows).
108
+ - `blocks`: phrases that mean "blocks" (the number that follows is blocked by this issue).
109
+ - `fieldKeys`: keys shown as fields of the detail panel.
110
+ - `ci.otherWorkflows`: workflows that are not a PR's CI (releases, deploys, docs, ...), matched as whole words.
111
+
112
+ The same file is used by the frontend, which receives it with the data.
113
+
114
+ ## API
115
+
116
+ - `GET /api/data`: lightweight records, links and sync status
117
+ - `GET /api/issues/:n`, `GET /api/pulls/:n`: full record for one item
118
+ - `POST /api/sync[?full=1]`: trigger a sync
119
+
120
+ ## Development
121
+
122
+ ```sh
123
+ npm run install:all # frontend dependencies
124
+ REPO=owner/name npm run dev:server # API on :4310
125
+ npm run dev:web # Vite on :5173, proxied to the API
126
+ npm test # server and frontend tests
127
+ ```
128
+
129
+ ## Roadmap
130
+
131
+ - Editing from the timeline (labels, close, comment) through GraphQL mutations
132
+ - Webhooks instead of polling
133
+ - Project and milestone events
134
+ - Velocity per person
135
+ - SQLite storage once the JSON files grow
136
+ - Parallel sync for large repositories (a first full sync of a large repo takes about 2 minutes today)
137
+
138
+ ## Notes
139
+
140
+ - The interface is in English. Issue bodies are read with the vocabulary above (English, Spanish, Portuguese, French,
141
+ German by default); a language not in it needs `VOCABULARY_FILE`.
142
+ - Not read: GitLab epics (a Premium feature) and the parent of an issue in GitLab. A dependency written only in a comment
143
+ is not read either.
144
+ - Links from commits are read from the title: a "#N" that matches an issue links the commit to it. This is a heuristic.
145
+ - A GitLab issue's links are read when the issue is synced. If a link added later does not show after an incremental
146
+ sync, a full sync (`POST /api/sync?full=1`) reads it.
147
+ - Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
148
+
149
+ ## License
150
+
151
+ [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.2",
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
+ });