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

Parked opened this
Closed without merging

scout/forge:scout/6848-a-milestone-s-page-draws-issues-closed-p → main 1 commit fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +237 −7
src/core/milestones.ts +12
@@ -13,6 +13,7 @@
1313 * from it.
1414 */
1515
16 import { paceOf, type Pace } from "./pace.ts";
1617 import type { Database } from "bun:sqlite";
1718 import { writeStamp } from "./write_clock.ts";
1819 import { deferredIn, repoGraph, type Graph } from "./dependencies.ts";
@@ -117,6 +118,8 @@ export interface Milestone extends Limb {
117118 };
118119 /** A plain sentence: when it lands at this week's pace, or why nobody can say. */
119120 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;
120123 /** What it waits for directly that has a tree of its own. */
121124 readonly limbs: readonly Limb[];
122125 /** What it waits for directly that brings none: at most an order among these. */
@@ -605,6 +608,12 @@ export function readPlan(
605608 }
606609 : {}),
607610 estimate,
611 pace: paceOf(
612 db,
613 under.filter(counted).map((i) => i.id),
614 limb.weight.open,
615 now,
616 ),
608617 limbs: arranged(issue.id, [...limbIds]).map(limbOf),
609618 leaves: children
610619 .filter((c) => !limbIds.has(c.id))
@@ -665,6 +674,9 @@ export function milestoneJson(
665674 ...limbJson(milestone),
666675 title: milestone.issue.title,
667676 estimate: milestone.estimate,
677 closedPerDay: milestone.pace.closedPerDay,
678 paceDate: milestone.pace.paceDate,
679 pace: milestone.pace.line,
668680 // `building` is the count, as on a limb; this is who is on what.
669681 buildingNow: milestone.building.map((b) => ({
670682 ...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"
33
44 export const tool: Tool = {
55 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)",
77 description:
88 "How far each ask is. With `app`: top-level limbs, done/total, building, recent merges.",
99 inputSchema: {
src/web/pages/milestones.ts +23 −6
@@ -20,6 +20,8 @@ import {
2020 type Milestone,
2121 type Plan,
2222 } from "../../core/milestones.ts";
23 import type { Pace } from "../../core/pace.ts";
24 import { daySpark } from "../studio/kpi_row.ts";
2325 import type { Database } from "bun:sqlite";
2426 import { parseSeat, seating } from "../../core/limb_seats.ts";
2527 import type { Issue } from "../../core/issues.ts";
@@ -198,17 +200,18 @@ function limbLine(base: string, limb: Limb, move: Html | null = null): Html {
198200 }
199201
200202 /** 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 =>
202204 cachedPlan(
203205 {
204206 repoId: repo.id,
205207 stamp: planStamp(ctx.app.db, repo),
206208 spend,
207 now: new Date(),
209 now,
208210 },
209211 () =>
210212 readPlan(ctx.app.db, repo, {
211213 spend,
214 now,
212215 stretch: (name, ms) => notePhase(ctx.request, `plan-${name}`, ms),
213216 }),
214217 );
@@ -219,7 +222,7 @@ export function milestonesPage(ctx: Ctx): Response {
219222 const repo = timePhase(ctx.request, "repo", () => loadRepo(ctx));
220223 if (!repo) return notFoundPage(ctx);
221224 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()));
223226 const base = repoBase(repo);
224227 const move = timePhase(ctx.request, "seats", () =>
225228 moverFor(ctx.app.db, repo, ctx.auth.user, plan.read),
@@ -358,6 +361,18 @@ function watchButton(base: string, m: Milestone, watching: boolean): Html {
358361 </form>`;
359362 }
360363
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
361376 function milestoneBody(
362377 repo: Repo,
363378 m: Milestone,
@@ -401,6 +416,7 @@ function milestoneBody(
401416 m.trim === undefined ? {} : { tone: "attn" },
402417 )}
403418 <p id="ms-estimate">${m.estimate}</p>
419 ${paceLine(m.pace)}
404420 ${when(
405421 m.trim,
406422 (why) => html`<p class="small">A candidate to trim: ${why}.</p>`,
@@ -535,14 +551,14 @@ function milestoneBody(
535551 }
536552
537553 /** 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 {
539555 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
540556 const repo = timePhase(ctx.request, "repo", () => loadRepo(ctx));
541557 if (!repo) return notFoundPage(ctx);
542558 const number = Number(ctx.params.number);
543559 const owner = canSeeOwnerFacts(ctx.app.db, repo, ctx.auth.user);
544560 const plan = Number.isInteger(number)
545 ? timePhase(ctx.request, "plan", () => planFor(ctx, repo, owner))
561 ? timePhase(ctx.request, "plan", () => planFor(ctx, repo, owner, now))
546562 : undefined;
547563 const milestone = plan?.milestone(number);
548564 if (plan === undefined || milestone === undefined) return notFoundPage(ctx);
@@ -659,9 +675,10 @@ export async function milestoneData(
659675 ctx: Ctx,
660676 repo: Repo,
661677 number: number,
678 now: Date = new Date(),
662679 ): Promise<Record<string, unknown> | undefined> {
663680 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(
665682 number,
666683 );
667684 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs