From 74b4ca130e4092b38f8e1132eb0907a4c2bbf001 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 17 Sep 2026 15:54:27 +0800 Subject: [PATCH] =?UTF-8?q?feat(timer):=20=E7=A2=BC=E9=8C=B6=E7=A7=BB?= =?UTF-8?q?=E5=87=BA=E9=A0=98=E5=8F=96=EF=BC=8C=E7=AD=89=E5=B7=A5=E4=BD=9C?= =?UTF-8?q?=E6=A8=B9=E5=BB=BA=E6=88=90=E4=B9=8B=E5=BE=8C=E6=89=8D=E8=B5=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 原本的順序是「放行 → 設 assignee 與標籤 → 起錶 → 處理分支」，而工作樹建立 失敗會中止整個領取——錶已經起了才失敗，使用者會被計一段什麼都沒做的時間， 而工時要準正是工時報表的立足點。 claim 只留領取鎖的兩件事（assignee 與標籤），起錶交給新的 timer.js，由流程 正本排在 branch-prep 之後。timer 已經跑在這顆議題上時什麼都不做：中斷後重跑 是它最常見的處境，重新起錶會把已經累積的時間切成兩段；跑在別顆上則照舊擋下， 不代勞停錶。 三支腳本讀碼錶的那段各留一份，趁這次收進 lib。 議題 #40 Co-Authored-By: Claude Opus 5 (1M context) --- scripts/claim.js | 21 +++--- scripts/timer.js | 78 +++++++++++++++++++++++ scripts/wp-extract.js | 11 +--- test/claim.test.js | 24 +++---- test/timer.test.js | 144 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 248 insertions(+), 30 deletions(-) create mode 100644 scripts/timer.js create mode 100644 test/timer.test.js diff --git a/scripts/claim.js b/scripts/claim.js index 8d58f6a..8b36844 100644 --- a/scripts/claim.js +++ b/scripts/claim.js @@ -1,10 +1,13 @@ #!/usr/bin/env node /** - * 領取一顆工作包：上鎖、貼標籤、起錶。 + * 領取一顆工作包：上鎖、貼標籤。 * * 鎖用 assignee 加標籤，不用碼錶——Gitea 只讓人讀自己的碼錶（`/user/stopwatches`）， * 看不到別人的錶，拿它當鎖會漏判。碼錶在這裡只有一個用途：發現自己忘了停掉上一顆。 * + * **錶不在這一步起**。它等工作樹建好之後才由 timer.js 起動（見 branch-prep.js）： + * 工作樹建立失敗會中止整個領取，錶要是先起了，使用者就被計了一段什麼都沒做的時間。 + * * 四種狀態的處置： * - 他人已認領 → 擋。不會兩個人做同一件事。 * - 自己的錶跑在本議題 → 擋。這顆你已經在做了，別重複起錶。 @@ -24,12 +27,14 @@ import { fetchIssue, giteaRequest, listLabels, + listStopwatches, main, parseFlags, parseIndex, parseRepo, preflight, resolveLogin, + stopwatchOnIssue, } from './lib.js'; /** 領取鎖的另一半。本 plugin 不自動建立標籤，這個名字要在 repo 上先存在。 */ @@ -84,9 +89,6 @@ main(async () => { }); labels.push(IN_PROGRESS); } - // 錶最後才起：前面任一步失敗時，不該留下一顆還在跑的碼錶 - planned.push({ method: 'POST', path: `${issuePath}/stopwatch/start`, body: {} }); - if (dryRun) { return { dryRun: true, repo, index, title: issue.title, requests: planned, 已認領過 }; } @@ -102,7 +104,8 @@ main(async () => { url: issue.html_url, assignee: me, labels, - 碼錶中: true, + // 鎖上好了，錶還沒起：它等工作樹建好之後才由 timer.js 起動 + 碼錶中: false, 已認領過, }; }); @@ -128,14 +131,10 @@ function checkClaimable(assignees, me, index) { * 跑在別的議題是「你忘了停掉那一顆」。 */ async function checkNoStopwatch(login, repo, index) { - const path = '/user/stopwatches'; - const watches = expectOk(await giteaRequest(login, 'GET', path), `GET ${path}`) ?? []; + const watches = await listStopwatches(login); if (watches.length === 0) return; - const here = watches.find( - (watch) => `${watch.repo_owner_name}/${watch.repo_name}` === repo && watch.issue_index === index, - ); - if (here) { + if (stopwatchOnIssue(watches, repo, index)) { throw new ScriptError( 'STOPWATCH_ON_THIS_ISSUE', `你的碼錶已經跑在議題 #${index} 上，這顆你正在做；` + diff --git a/scripts/timer.js b/scripts/timer.js new file mode 100644 index 0000000..245dded --- /dev/null +++ b/scripts/timer.js @@ -0,0 +1,78 @@ +#!/usr/bin/env node +/** + * 起錶。 + * + * 錶與領取鎖是兩件事：鎖用 assignee 加標籤（見 claim.js），錶只管工時。分開的理由是 + * 時機不同——鎖要在開工之前就上好，錶則要等到**工作樹真的建好之後**才起。工作樹建立 + * 失敗會中止整個領取，錶要是先起了，使用者就被計了一段什麼都沒做的時間， + * 而工時要準正是工時報表的立足點。 + * + * 自己的錶跑在別顆議題上時擋下，不代勞停錶：那一段時間該記在哪顆議題上只有人知道， + * 腳本自作主張會把工時記錯地方。錶已經跑在本議題上則什麼都不做——重新起錶會把已經 + * 累積的時間切成兩段，而中斷後重跑正是這支腳本最常見的處境。 + * + * 用法： + * node scripts/timer.js --repo owner/name --index 40 [--host <網址>] [--dry-run] + */ +import { + ScriptError, + expectOk, + fetchIssue, + giteaRequest, + listStopwatches, + main, + parseFlags, + parseIndex, + parseRepo, + preflight, + resolveLogin, + stopwatchOnIssue, +} from './lib.js'; + +main(async () => { + const flags = parseFlags(process.argv.slice(2), { + required: ['repo', 'index'], + optional: ['host'], + booleans: ['dry-run'], + }); + const repo = parseRepo(flags.repo); + const index = parseIndex(flags.index); + const issuePath = `/repos/${repo}/issues/${index}`; + const dryRun = flags['dry-run'] === true; + + const login = resolveLogin({ host: flags.host }); + // 試跑照樣讀現況：手寫一份固定的清單會跟實作走鐘，也說不出「這顆已經在計時了」 + if (!dryRun) await preflight(login, repo); + const issue = await fetchIssue(login, repo, index); + + const watches = await listStopwatches(login); + const 已在計時 = stopwatchOnIssue(watches, repo, index) !== null; + if (!已在計時 && watches.length > 0) { + const elsewhere = watches[0]; + throw new ScriptError( + 'STOPWATCH_ON_OTHER_ISSUE', + `你的碼錶正跑在 ${elsewhere.repo_owner_name}/${elsewhere.repo_name} 的議題 ` + + `#${elsewhere.issue_index} 上，起錶前請先手動停錶，否則工時會記到那一顆去`, + ); + } + + // 已經在跑就不重起：重新起錶會把已經累積的時間切成兩段 + const planned = 已在計時 ? [] : [{ method: 'POST', path: `${issuePath}/stopwatch/start`, body: {} }]; + + if (dryRun) { + return { dryRun: true, repo, index, title: issue.title, requests: planned, 已在計時 }; + } + + for (const { method, path, body } of planned) { + expectOk(await giteaRequest(login, method, path, { body }), `${method} ${path}`); + } + + return { + repo, + index: issue.number, + title: issue.title, + url: issue.html_url, + 碼錶中: true, + 已在計時, + }; +}); diff --git a/scripts/wp-extract.js b/scripts/wp-extract.js index eb081a8..eb31ee1 100644 --- a/scripts/wp-extract.js +++ b/scripts/wp-extract.js @@ -14,9 +14,8 @@ import { UNMERGED_COMMENT_NOTE, countUnmergedComments, - expectOk, fetchIssue, - giteaRequest, + listStopwatches, main, pages, parseFlags, @@ -24,6 +23,7 @@ import { parseRepo, preflight, resolveLogin, + stopwatchOnIssue, } from './lib.js'; import { checklistInSection, @@ -118,10 +118,5 @@ async function fetchLinked(login, path, kind) { * ——領取鎖看的是 assignee。 */ async function hasRunningStopwatch(login, repo, index) { - const path = '/user/stopwatches'; - const watches = expectOk(await giteaRequest(login, 'GET', path), `GET ${path}`) ?? []; - - return watches.some( - (watch) => `${watch.repo_owner_name}/${watch.repo_name}` === repo && watch.issue_index === index, - ); + return stopwatchOnIssue(await listStopwatches(login), repo, index) !== null; } diff --git a/test/claim.test.js b/test/claim.test.js index af8cf33..b3445ae 100644 --- a/test/claim.test.js +++ b/test/claim.test.js @@ -1,6 +1,10 @@ /** * 領取工作包的鎖。 * + * 錶不在這一支起——它等工作樹建好之後才由 timer.js 起動，所以這裡連帶要驗 + * 「一發起錶請求都沒有」：領取失敗或工作樹建不起來時，使用者不該被計一段 + * 什麼都沒做的時間。 + * * 這一支的價值全在「什麼時候擋下來」：放行的路徑只有一條，擋的理由有四種， * 而擋錯的代價是兩個人做同一件事、或是工時記到別顆議題上。所以決策表的四種狀態 * 各有測試，而且每一種都要驗「一個字都沒寫進 Gitea」——擋下來卻已經改了一半， @@ -68,7 +72,7 @@ const writes = (stub) => // ── 決策表：無鎖 ─────────────────────────────────────────────────── -test('沒有鎖時放行：設 assignee、貼進行中、起錶', async (t) => { +test('沒有鎖時放行：設 assignee、貼進行中', async (t) => { const stub = await withStub(t, {}, { repoLabels: ['ready-for-agent', '進行中'] }); const { code, json } = await run([], stub); @@ -76,11 +80,11 @@ test('沒有鎖時放行：設 assignee、貼進行中、起錶', async (t) => { assert.equal(code, 0); assert.equal(json.data.assignee, ME); assert.deepEqual(json.data.labels, ['進行中']); - assert.equal(json.data.碼錶中, true); + assert.equal(json.data.碼錶中, false, '鎖上好了，錶還沒起'); assert.equal(json.data.已認領過, false); }); -test('放行時三個寫入請求都發出，且順序為先上鎖再起錶', async (t) => { +test('放行時只寫入鎖的那兩件事，一發起錶請求都沒有', async (t) => { const stub = await withStub(t, {}, { repoLabels: ['進行中'] }); await run([], stub); @@ -90,9 +94,8 @@ test('放行時三個寫入請求都發出，且順序為先上鎖再起錶', as [ `PATCH /api/v1/repos/${REPO}/issues/${INDEX}`, `POST /api/v1/repos/${REPO}/issues/${INDEX}/labels`, - `POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`, ], - '錶要最後才起：前面任一步失敗時，不該留下一顆還在跑的碼錶', + '錶等工作樹建好之後才由 timer.js 起動：建不起來就中止，不該已經計了時間', ); }); @@ -180,7 +183,7 @@ test('自己已認領但沒有錶時放行，並如實說這顆本來就是自 assert.equal(code, 0); assert.equal(json.data.已認領過, true); - assert.equal(json.data.碼錶中, true, '錶還是要起，中斷重跑就是為了接上這件事'); + assert.equal(json.data.碼錶中, false, '重跑時鎖照樣補齊，錶則仍舊留到工作樹建好之後'); }); test('進行中標籤已經在議題上時不重複貼', async (t) => { @@ -251,7 +254,6 @@ test('--dry-run 印出將發出的寫入，但一個字都不寫進去', async ( [ `PATCH /repos/${REPO}/issues/${INDEX}`, `POST /repos/${REPO}/issues/${INDEX}/labels`, - `POST /repos/${REPO}/issues/${INDEX}/stopwatch/start`, ], ); assert.deepEqual(writes(stub), [], '預覽不得真的寫入'); @@ -270,7 +272,7 @@ test('--dry-run 會先讀現況：預覽出來的是這一顆實際的處境', a assert.ok(reads.includes(`/api/v1/repos/${REPO}/labels`)); }); -test('--dry-run 略過已經做好的部分，不謊報將發出的請求', async (t) => { +test('--dry-run 略過已經做好的部分：鎖都在了就什麼都不必寫', async (t) => { const stub = await withStub(t, {}, { assignees: [ME], labels: ['進行中'], @@ -280,9 +282,9 @@ test('--dry-run 略過已經做好的部分，不謊報將發出的請求', asyn const { json } = await run(['--dry-run'], stub); assert.deepEqual( - json.data.requests.map((r) => `${r.method} ${r.path}`), - [`POST /repos/${REPO}/issues/${INDEX}/stopwatch/start`], - 'assignee 與標籤都已經到位，只差起錶', + json.data.requests, + [], + 'assignee 與標籤都已經到位，中斷重跑就是走到這裡；手寫一份固定的清單會謊報', ); }); diff --git a/test/timer.test.js b/test/timer.test.js new file mode 100644 index 0000000..ffd7930 --- /dev/null +++ b/test/timer.test.js @@ -0,0 +1,144 @@ +/** + * 起錶。 + * + * 錶是工時報表的唯一來源，所以這一支的價值全在「什麼時候不該起」：工作樹還沒建好 + * 不該起（那由流程的順序保證），自己的錶已經跑在別顆議題上更不該起——那會把兩顆 + * 工作包的時間攪在一起。停錶一律由使用者自己來，這裡不提供。 + */ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { runScript } from './helpers/run-script.js'; +import { healthyRoutes, stubEnv as envFor, withStubGitea } from './helpers/stub-gitea.js'; + +const REPO = 'plugins/tea-sdlc'; +const INDEX = 40; + +/** 議題上跑著的碼錶長什麼樣 */ +const stopwatchOn = (index, repo = REPO) => ({ + issue_index: index, + repo_owner_name: repo.split('/')[0], + repo_name: repo.split('/')[1], +}); + +function routes(overrides = {}, { stopwatches = [] } = {}) { + return healthyRoutes(REPO, { + [`GET /api/v1/repos/${REPO}/issues/${INDEX}`]: { + status: 200, + body: { + number: INDEX, + title: '以 worktree 建立工作包分支並備妥隔離環境', + html_url: `https://gitea.jsc.idv.tw/${REPO}/issues/${INDEX}`, + }, + }, + 'GET /api/v1/user/stopwatches': { status: 200, body: stopwatches }, + [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`]: { status: 201, body: {} }, + ...overrides, + }); +} + +const withStub = (t, overrides = {}, options) => withStubGitea(t, routes(overrides, options)); + +const run = (args, stub) => + runScript('timer.js', ['--repo', REPO, '--index', String(INDEX), ...args], { env: envFor(stub) }); + +/** 會改動 Gitea 的請求；前置檢查打在 issues/0 的探針不算（見 lib 的 checkIssueWrite） */ +const writes = (stub) => + stub.requests.filter((r) => r.method !== 'GET').filter((r) => !r.path.endsWith('/issues/0')); + +test('沒有錶在跑時起錶，並回報起在哪一顆上', async (t) => { + const stub = await withStub(t); + + const { code, json } = await run([], stub); + + assert.equal(code, 0, json.error?.message); + assert.equal(json.data.碼錶中, true); + assert.equal(json.data.index, INDEX); + assert.deepEqual( + writes(stub).map((r) => `${r.method} ${r.path}`), + [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`], + ); +}); + +test('錶已經跑在這顆議題上時什麼都不做，重跑不會把計時打斷', async (t) => { + const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] }); + + const { code, json } = await run([], stub); + + assert.equal(code, 0, json.error?.message); + assert.equal(json.data.碼錶中, true); + assert.equal(json.data.已在計時, true, '要如實說這顆本來就在計時，不要假裝是這次起的'); + assert.deepEqual(writes(stub), [], '重新起錶會把已經累積的時間切成兩段'); +}); + +test('錶跑在別顆議題上時擋下，並指出是哪一顆', async (t) => { + const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(7)] }); + + const { code, json } = await run([], stub); + + assert.equal(code, 1); + assert.equal(json.error.code, 'STOPWATCH_ON_OTHER_ISSUE'); + assert.match(json.error.message, /#7/, '忘了停掉的是哪一顆，要指名'); + assert.deepEqual(writes(stub), [], '擋下來就不該寫進任何東西'); +}); + +test('別的 repo 上的同號碼錶也算自己有錶在跑', async (t) => { + const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX, 'plugins/別的專案')] }); + + const { json } = await run([], stub); + + assert.equal(json.error.code, 'STOPWATCH_ON_OTHER_ISSUE'); + assert.match(json.error.message, /別的專案/); +}); + +test('不代替使用者停錶：訊息要說清楚下一步是他自己去停', async (t) => { + const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(7)] }); + + const { json } = await run([], stub); + + assert.match(json.error.message, /停/); +}); + +test('議題不存在時回可區分的錯誤碼', async (t) => { + const stub = await withStub(t, { + [`GET /api/v1/repos/${REPO}/issues/${INDEX}`]: { status: 404, body: { message: 'not found' } }, + }); + + const { json } = await run([], stub); + + assert.equal(json.error.code, 'ISSUE_NOT_FOUND'); + assert.deepEqual(writes(stub), []); +}); + +test('--index 不是正整數時擋在打 Gitea 之前', async (t) => { + const stub = await withStub(t); + + const { json } = await runScript('timer.js', ['--repo', REPO, '--index', '0'], { + env: envFor(stub), + }); + + assert.equal(json.error.code, 'BAD_INDEX'); + assert.equal(stub.requests.length, 0); +}); + +test('--dry-run 印出將發出的寫入，但一個字都不寫進去', async (t) => { + const stub = await withStub(t); + + const { code, json } = await run(['--dry-run'], stub); + + assert.equal(code, 0); + assert.equal(json.data.dryRun, true); + assert.deepEqual( + json.data.requests.map((r) => `${r.method} ${r.path}`), + [`POST /repos/${REPO}/issues/${INDEX}/stopwatch/start`], + ); + assert.deepEqual(writes(stub), [], '預覽不得真的寫入'); +}); + +test('--dry-run 會先讀現況：已經在計時時預覽出來就是什麼都不做', async (t) => { + const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] }); + + const { json } = await run(['--dry-run'], stub); + + assert.deepEqual(json.data.requests, [], '手寫一份固定的清單會跟實作走鐘'); + assert.equal(json.data.已在計時, true); +});