Public: anyone can read this; the crew can change it.
A milestone's page draws issues closed per day and the date it is on pace for, from one plan read #6868
scout/forge:scout/6848-a-milestone-s-page-draws-issues-closed-p → main 1 commit fork
5 files
changed +237
−7
src/core/milestones.ts +12
| @@ -13,6 +13,7 @@ | ||
| 13 | 13 | * from it. |
| 14 | 14 | */ |
| 15 | 15 | |
| 16 | import { paceOf, type Pace } from "./pace.ts"; | |
| 16 | 17 | import type { Database } from "bun:sqlite"; |
| 17 | 18 | import { writeStamp } from "./write_clock.ts"; |
| 18 | 19 | import { deferredIn, repoGraph, type Graph } from "./dependencies.ts"; |
| @@ -117,6 +118,8 @@ export interface Milestone extends Limb { | ||
| 117 | 118 | }; |
| 118 | 119 | /** A plain sentence: when it lands at this week's pace, or why nobody can say. */ |
| 119 | 120 | readonly estimate: string; |
| 121 | /** Issues closed per day and the date it is on pace for, at the `now` the plan was read with. */ | |
| 122 | readonly pace: Pace; | |
| 120 | 123 | /** What it waits for directly that has a tree of its own. */ |
| 121 | 124 | readonly limbs: readonly Limb[]; |
| 122 | 125 | /** What it waits for directly that brings none: at most an order among these. */ |
| @@ -605,6 +608,12 @@ export function readPlan( | ||
| 605 | 608 | } |
| 606 | 609 | : {}), |
| 607 | 610 | estimate, |
| 611 | pace: paceOf( | |
| 612 | db, | |
| 613 | under.filter(counted).map((i) => i.id), | |
| 614 | limb.weight.open, | |
| 615 | now, | |
| 616 | ), | |
| 608 | 617 | limbs: arranged(issue.id, [...limbIds]).map(limbOf), |
| 609 | 618 | leaves: children |
| 610 | 619 | .filter((c) => !limbIds.has(c.id)) |
| @@ -665,6 +674,9 @@ export function milestoneJson( | ||
| 665 | 674 | ...limbJson(milestone), |
| 666 | 675 | title: milestone.issue.title, |
| 667 | 676 | estimate: milestone.estimate, |
| 677 | closedPerDay: milestone.pace.closedPerDay, | |
| 678 | paceDate: milestone.pace.paceDate, | |
| 679 | pace: milestone.pace.line, | |
| 668 | 680 | // `building` is the count, as on a limb; this is who is on what. |
| 669 | 681 | buildingNow: milestone.building.map((b) => ({ |
| 670 | 682 | ...brief(b.issue), |
src/core/pace.ts added +73
| @@ -0,0 +1,73 @@ | ||
| 1 | /** | |
| 2 | * Pace (#6848): how many issues a milestone closed each day over the last | |
| 3 | * `PACE_DAYS` UTC days, and the date it is on pace to finish. One grouped | |
| 4 | * query; `now` is given, never read, so a caller that shows the same | |
| 5 | * milestone twice shows the same day. | |
| 6 | */ | |
| 7 | ||
| 8 | import type { Database } from "bun:sqlite"; | |
| 9 | ||
| 10 | /** Days drawn, today last. */ | |
| 11 | export const PACE_DAYS = 14; | |
| 12 | /** The window the pace is taken over. */ | |
| 13 | export const PACE_WINDOW = 7; | |
| 14 | const DAY_MS = 86_400_000; | |
| 15 | ||
| 16 | export interface Pace { | |
| 17 | /** Issues closed each day, oldest first, today last: `PACE_DAYS` numbers. */ | |
| 18 | readonly closedPerDay: readonly number[]; | |
| 19 | /** The UTC date (YYYY-MM-DD) it is on pace to finish; null when it is stalled or done. */ | |
| 20 | readonly paceDate: string | null; | |
| 21 | /** The UTC date the last issue closed, when nothing is left open; else null. */ | |
| 22 | readonly doneDate: string | null; | |
| 23 | /** `on pace for <date>`, `no movement in 7 days`, `done <date>`, or "" with nothing to count. */ | |
| 24 | readonly line: string; | |
| 25 | } | |
| 26 | ||
| 27 | const dayOf = (at: Date): string => at.toISOString().slice(0, 10); | |
| 28 | ||
| 29 | /** | |
| 30 | * `ids` are the issues beneath the milestone that count as work; `open` | |
| 31 | * how many of them are open. | |
| 32 | */ | |
| 33 | export function paceOf( | |
| 34 | db: Database, | |
| 35 | ids: readonly string[], | |
| 36 | open: number, | |
| 37 | now: Date, | |
| 38 | ): Pace { | |
| 39 | const rows = | |
| 40 | ids.length === 0 | |
| 41 | ? [] | |
| 42 | : db | |
| 43 | .query<{ day: string; n: number }, [string]>( | |
| 44 | `SELECT substr(closed_at, 1, 10) AS day, COUNT(*) AS n | |
| 45 | FROM issue | |
| 46 | WHERE id IN (SELECT value FROM json_each(?1)) | |
| 47 | AND state = 'closed' AND closed_at IS NOT NULL | |
| 48 | GROUP BY day`, | |
| 49 | ) | |
| 50 | .all(JSON.stringify(ids)); | |
| 51 | const perDay = new Map(rows.map((r) => [r.day, r.n])); | |
| 52 | const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()); | |
| 53 | const days = Array.from({ length: PACE_DAYS }, (_, i) => | |
| 54 | dayOf(new Date(today - (PACE_DAYS - 1 - i) * DAY_MS)), | |
| 55 | ); | |
| 56 | const closedPerDay = days.map((d) => perDay.get(d) ?? 0); | |
| 57 | if (ids.length === 0) return { closedPerDay, paceDate: null, doneDate: null, line: "" }; | |
| 58 | if (open === 0) { | |
| 59 | const last = rows.reduce<string | null>((m, r) => (m === null || r.day > m ? r.day : m), null); | |
| 60 | return { | |
| 61 | closedPerDay, | |
| 62 | paceDate: null, | |
| 63 | doneDate: last, | |
| 64 | line: last === null ? "" : `done ${last}`, | |
| 65 | }; | |
| 66 | } | |
| 67 | const week = closedPerDay.slice(-PACE_WINDOW).reduce((a, b) => a + b, 0); | |
| 68 | if (week === 0) | |
| 69 | return { closedPerDay, paceDate: null, doneDate: null, line: `no movement in ${PACE_WINDOW} days` }; | |
| 70 | const ahead = Math.ceil(open / (week / PACE_WINDOW)); | |
| 71 | const paceDate = dayOf(new Date(today + ahead * DAY_MS)); | |
| 72 | return { closedPerDay, paceDate, doneDate: null, line: `on pace for ${paceDate}` }; | |
| 73 | } |
src/http/mcp/tools/milestones.ts +1 −1
| @@ -3,7 +3,7 @@ import { good, bad, type Tool, APP_ARG, planRepo, isAnswer } from "../shared.ts" | ||
| 3 | 3 | |
| 4 | 4 | export const tool: Tool = { |
| 5 | 5 | name: "milestones", |
| 6 | doc: "`{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues)", | |
| 6 | doc: "`{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, `closedPerDay` (14 days) and `paceDate`, and for an owner `spend`: dollars, changes landed ever, the costliest three issues)", | |
| 7 | 7 | description: |
| 8 | 8 | "How far each ask is. With `app`: top-level limbs, done/total, building, recent merges.", |
| 9 | 9 | inputSchema: { |
src/web/pages/milestones.ts +23 −6
| @@ -20,6 +20,8 @@ import { | ||
| 20 | 20 | type Milestone, |
| 21 | 21 | type Plan, |
| 22 | 22 | } from "../../core/milestones.ts"; |
| 23 | import type { Pace } from "../../core/pace.ts"; | |
| 24 | import { daySpark } from "../studio/kpi_row.ts"; | |
| 23 | 25 | import type { Database } from "bun:sqlite"; |
| 24 | 26 | import { parseSeat, seating } from "../../core/limb_seats.ts"; |
| 25 | 27 | import type { Issue } from "../../core/issues.ts"; |
| @@ -198,17 +200,18 @@ function limbLine(base: string, limb: Limb, move: Html | null = null): Html { | ||
| 198 | 200 | } |
| 199 | 201 | |
| 200 | 202 | /** The repository's plan, kept while nothing it reads changes. */ |
| 201 | const planFor = (ctx: Ctx, repo: Repo, spend: boolean): Plan => | |
| 203 | const planFor = (ctx: Ctx, repo: Repo, spend: boolean, now: Date): Plan => | |
| 202 | 204 | cachedPlan( |
| 203 | 205 | { |
| 204 | 206 | repoId: repo.id, |
| 205 | 207 | stamp: planStamp(ctx.app.db, repo), |
| 206 | 208 | spend, |
| 207 | now: new Date(), | |
| 209 | now, | |
| 208 | 210 | }, |
| 209 | 211 | () => |
| 210 | 212 | readPlan(ctx.app.db, repo, { |
| 211 | 213 | spend, |
| 214 | now, | |
| 212 | 215 | stretch: (name, ms) => notePhase(ctx.request, `plan-${name}`, ms), |
| 213 | 216 | }), |
| 214 | 217 | ); |
| @@ -219,7 +222,7 @@ export function milestonesPage(ctx: Ctx): Response { | ||
| 219 | 222 | const repo = timePhase(ctx.request, "repo", () => loadRepo(ctx)); |
| 220 | 223 | if (!repo) return notFoundPage(ctx); |
| 221 | 224 | const spend = canSeeOwnerFacts(ctx.app.db, repo, ctx.auth.user); |
| 222 | const plan = timePhase(ctx.request, "plan", () => planFor(ctx, repo, spend)); | |
| 225 | const plan = timePhase(ctx.request, "plan", () => planFor(ctx, repo, spend, new Date())); | |
| 223 | 226 | const base = repoBase(repo); |
| 224 | 227 | const move = timePhase(ctx.request, "seats", () => |
| 225 | 228 | moverFor(ctx.app.db, repo, ctx.auth.user, plan.read), |
| @@ -358,6 +361,18 @@ function watchButton(base: string, m: Milestone, watching: boolean): Html { | ||
| 358 | 361 | </form>`; |
| 359 | 362 | } |
| 360 | 363 | |
| 364 | /** Issues closed per day with the design system's sparkline, and one line of what it means. */ | |
| 365 | function paceLine(pace: Pace): Html | null { | |
| 366 | if (pace.line === "") return null; | |
| 367 | const spark = daySpark( | |
| 368 | pace.closedPerDay, | |
| 369 | `Issues closed each day over the last ${pace.closedPerDay.length} days`, | |
| 370 | ); | |
| 371 | return html`<div class="bar" id="ms-pace"> | |
| 372 | <span class="muted">${spark}</span><span>${pace.line}</span> | |
| 373 | </div>`; | |
| 374 | } | |
| 375 | ||
| 361 | 376 | function milestoneBody( |
| 362 | 377 | repo: Repo, |
| 363 | 378 | m: Milestone, |
| @@ -401,6 +416,7 @@ function milestoneBody( | ||
| 401 | 416 | m.trim === undefined ? {} : { tone: "attn" }, |
| 402 | 417 | )} |
| 403 | 418 | <p id="ms-estimate">${m.estimate}</p> |
| 419 | ${paceLine(m.pace)} | |
| 404 | 420 | ${when( |
| 405 | 421 | m.trim, |
| 406 | 422 | (why) => html`<p class="small">A candidate to trim: ${why}.</p>`, |
| @@ -535,14 +551,14 @@ function milestoneBody( | ||
| 535 | 551 | } |
| 536 | 552 | |
| 537 | 553 | /** GET /:owner/:name/milestones/:number — one milestone, opened. */ |
| 538 | export function milestonePage(ctx: Ctx): Response { | |
| 554 | export function milestonePage(ctx: Ctx, now: Date = new Date()): Response { | |
| 539 | 555 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 540 | 556 | const repo = timePhase(ctx.request, "repo", () => loadRepo(ctx)); |
| 541 | 557 | if (!repo) return notFoundPage(ctx); |
| 542 | 558 | const number = Number(ctx.params.number); |
| 543 | 559 | const owner = canSeeOwnerFacts(ctx.app.db, repo, ctx.auth.user); |
| 544 | 560 | const plan = Number.isInteger(number) |
| 545 | ? timePhase(ctx.request, "plan", () => planFor(ctx, repo, owner)) | |
| 561 | ? timePhase(ctx.request, "plan", () => planFor(ctx, repo, owner, now)) | |
| 546 | 562 | : undefined; |
| 547 | 563 | const milestone = plan?.milestone(number); |
| 548 | 564 | if (plan === undefined || milestone === undefined) return notFoundPage(ctx); |
| @@ -659,9 +675,10 @@ export async function milestoneData( | ||
| 659 | 675 | ctx: Ctx, |
| 660 | 676 | repo: Repo, |
| 661 | 677 | number: number, |
| 678 | now: Date = new Date(), | |
| 662 | 679 | ): Promise<Record<string, unknown> | undefined> { |
| 663 | 680 | const owner = canSeeOwnerFacts(ctx.app.db, repo, ctx.auth.user); |
| 664 | const milestone = readPlan(ctx.app.db, repo, { spend: owner }).milestone( | |
| 681 | const milestone = readPlan(ctx.app.db, repo, { spend: owner, now }).milestone( | |
| 665 | 682 | number, |
| 666 | 683 | ); |
| 667 | 684 | const viewer = ctx.auth.user; |
test/milestone-pace.test.ts added +128
| @@ -0,0 +1,128 @@ | ||
| 1 | /** A milestone's pace (#6848): closed per day, and the date it is on pace for, on the page and in the MCP. */ | |
| 2 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 3 | import { mkdtempSync, rmSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { linkIssue } from "../src/actions/dependencies.ts"; | |
| 7 | import { openIssue, setIssueState } from "../src/actions/issues.ts"; | |
| 8 | import { createRepo } from "../src/actions/repos.ts"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { getIssueById, type Issue } from "../src/core/issues.ts"; | |
| 11 | import { paceOf } from "../src/core/pace.ts"; | |
| 12 | import { getRepo, type Repo } from "../src/core/repos.ts"; | |
| 13 | import { createUser, getUserByName } from "../src/core/users.ts"; | |
| 14 | import type { Ctx } from "../src/http/context.ts"; | |
| 15 | import { milestoneData, milestonePage } from "../src/web/pages/milestones.ts"; | |
| 16 | import { quietLogs } from "./helpers/globals.ts"; | |
| 17 | import { proveAll } from "./helpers/verified.ts"; | |
| 18 | ||
| 19 | quietLogs(); | |
| 20 | ||
| 21 | // One instant for the whole file, a minute past midnight UTC. | |
| 22 | const NOW = new Date("2026-10-27T00:01:00.000Z"); | |
| 23 | const at = (daysAgo: number): string => | |
| 24 | new Date(Date.UTC(2026, 9, 27 - daysAgo, 12)).toISOString(); | |
| 25 | ||
| 26 | let root = ""; | |
| 27 | let app: App; | |
| 28 | let repo: Repo; | |
| 29 | ||
| 30 | beforeAll(async () => { | |
| 31 | root = mkdtempSync(join(tmpdir(), "forge-pace-")); | |
| 32 | app = createApp({ dataDir: root, port: 0, forgeRepo: "alice/forge" }); | |
| 33 | const u = await createUser(app.db, { | |
| 34 | origin: "seed", | |
| 35 | trusted: true, | |
| 36 | username: "alice", | |
| 37 | email: "[email protected]", | |
| 38 | password: "a-good-passphrase", | |
| 39 | adminIfFirst: true, | |
| 40 | }); | |
| 41 | if (!u.ok) throw new Error(u.error); | |
| 42 | proveAll(app); | |
| 43 | const made = await createRepo(app, u.value as never, { name: "forge" }); | |
| 44 | if (!made.ok) throw new Error(made.error); | |
| 45 | repo = getRepo(app.db, "alice", "forge")!; | |
| 46 | }); | |
| 47 | afterAll(() => { | |
| 48 | app.close(); | |
| 49 | rmSync(root, { recursive: true, force: true }); | |
| 50 | }); | |
| 51 | ||
| 52 | const alice = () => getUserByName(app.db, "alice")!; | |
| 53 | const make = (title: string): Issue => { | |
| 54 | const o = openIssue(app, alice(), repo, { title }); | |
| 55 | if (!o.ok) throw new Error(String(o.error)); | |
| 56 | return o.value; | |
| 57 | }; | |
| 58 | ||
| 59 | /** A milestone waiting for `leaves` issues; `closed` of them closed on the given days ago. */ | |
| 60 | function milestone(name: string, open: number, closedDaysAgo: number[]): Issue { | |
| 61 | const top = make(name); | |
| 62 | for (const [i, ago] of [...closedDaysAgo, ...Array(open).fill(null)].entries()) { | |
| 63 | const leaf = make(`${name} ${i}`); | |
| 64 | const linked = linkIssue(app, alice(), repo, top, leaf); | |
| 65 | if (!linked.ok) throw new Error(String(linked.error)); | |
| 66 | if (ago === null) continue; | |
| 67 | expect(setIssueState(app, alice(), repo, getIssueById(app.db, leaf.id)!, "closed").ok).toBe(true); | |
| 68 | app.db.query("UPDATE issue SET closed_at = ?1 WHERE id = ?2").run(at(ago), leaf.id); | |
| 69 | } | |
| 70 | return top; | |
| 71 | } | |
| 72 | ||
| 73 | const ctxFor = (number: number): Ctx => | |
| 74 | ({ | |
| 75 | app, | |
| 76 | request: new Request(`http://x/alice/forge/milestones/${number}`), | |
| 77 | url: new URL(`http://x/alice/forge/milestones/${number}`), | |
| 78 | params: { owner: "alice", name: "forge", number: String(number) }, | |
| 79 | auth: { user: alice(), scope: undefined, via: "session" }, | |
| 80 | theme: undefined, | |
| 81 | }) as Ctx; | |
| 82 | ||
| 83 | /** The page's pace line and the MCP's data, both at NOW. */ | |
| 84 | async function both(top: Issue) { | |
| 85 | const html = await milestonePage(ctxFor(top.number), NOW).text(); | |
| 86 | const line = /id="ms-pace"[\s\S]*?<span>([^<]*)<\/span>\s*<\/div>/.exec(html)?.[1]; | |
| 87 | const data = (await milestoneData(ctxFor(top.number), repo, top.number, NOW))!; | |
| 88 | return { html, line, data }; | |
| 89 | } | |
| 90 | ||
| 91 | test("on pace: 3 closed in 7 days and 2 open lands 5 days out; page and MCP agree", async () => { | |
| 92 | const top = milestone("Pace", 2, [0, 1, 2, 9]); | |
| 93 | const { html, line, data } = await both(top); | |
| 94 | expect(data["closedPerDay"]).toEqual([0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 1, 1]); | |
| 95 | // 3 closed in the last 7 days: ceil(2 / (3 / 7)) = 5 days after 2026-10-27. | |
| 96 | expect(data["paceDate"]).toBe("2026-11-01"); | |
| 97 | expect(line).toBe(`on pace for ${data["paceDate"]}`); | |
| 98 | expect(data["pace"]).toBe(line!); | |
| 99 | expect(html).toContain("<svg"); | |
| 100 | }); | |
| 101 | ||
| 102 | test("stalled: nothing closed in 7 days says so and has no date", async () => { | |
| 103 | const top = milestone("Stalled", 1, [10]); | |
| 104 | const { line, data } = await both(top); | |
| 105 | expect(line).toBe("no movement in 7 days"); | |
| 106 | expect(data["paceDate"]).toBeNull(); | |
| 107 | }); | |
| 108 | ||
| 109 | test("done: nothing open says the day the last one closed", async () => { | |
| 110 | const top = milestone("Finished", 0, [3, 5]); | |
| 111 | const { line, data } = await both(top); | |
| 112 | expect(line).toBe("done 2026-10-24"); | |
| 113 | expect(data["paceDate"]).toBeNull(); | |
| 114 | }); | |
| 115 | ||
| 116 | test("the pace is one grouped read, whatever the number of issues", () => { | |
| 117 | const queries: string[] = []; | |
| 118 | const db = { | |
| 119 | query: (sql: string) => { | |
| 120 | queries.push(sql); | |
| 121 | return { all: () => [{ day: "2026-10-27", n: 2 }] }; | |
| 122 | }, | |
| 123 | } as never; | |
| 124 | const pace = paceOf(db, ["a", "b", "c"], 1, NOW); | |
| 125 | expect(queries.length).toBe(1); | |
| 126 | expect(queries[0]).toContain("GROUP BY"); | |
| 127 | expect(pace.closedPerDay.at(-1)).toBe(2); | |
| 128 | }); |
new above
offline