Board charts and forecasts from the board's history, and its timeline (closes #357, closes #361) f2d2776b2a14

//! A board's charts and forecasts from its own history (oxygenhub#357):

//! cumulative flow, cycle time, throughput and a Monte Carlo of when the

//! remaining cards will be done, with no estimates to keep. Everything here

//! is a pure function of the board's card moves (`project_card_moves`), so

//! the series and the forecast's percentiles are testable from a fixture

//! board and a fixed seed.

use std::collections::{BTreeMap, HashMap};

pub const DAY_MS: i64 = 86_400_000;

pub const WEEK_MS: i64 = 7 * DAY_MS;

/// A card's move: to a column, or off the board (`None`), at a time.

#[derive(Clone, Copy, Debug, PartialEq, Eq)]

pub struct Move {

    pub card: i64,

    pub column: Option<i64>,

    pub at: i64,

}

/// Cards per column at the end of each day from `first_day` (midnight UTC,

/// ms) for `days` days: one row a day, one count per column of `columns`

/// (in board order). Moves must be oldest first.

pub fn cumulative_flow(moves: &[Move], columns: &[i64], first_day: i64, days: usize) -> Vec<Vec<usize>> {

    let mut at: HashMap<i64, Option<i64>> = HashMap::new();

    let mut i = 0;

    let mut out = Vec::with_capacity(days);

    for d in 0..days {

        let end = first_day + (d as i64 + 1) * DAY_MS;

        while i < moves.len() && moves[i].at < end {

            at.insert(moves[i].card, moves[i].column);

            i += 1;

        }

        let mut counts = vec![0; columns.len()];

        for col in at.values().flatten() {

            if let Some(k) = columns.iter().position(|c| c == col) {

                counts[k] += 1;

            }

        }

        out.push(counts);

    }

    out

}

/// Each finished card's cycle time in ms: from when it first left the

/// board's first column (work started) to when it first reached `done`

/// after that. A card added straight into a later column starts there.

pub fn cycle_times(moves: &[Move], first_column: i64, done: i64) -> Vec<i64> {

    let mut started: HashMap<i64, i64> = HashMap::new();

    let mut finished: BTreeMap<i64, i64> = BTreeMap::new();

    for m in moves {

        let Some(col) = m.column else { continue };

        if col != first_column && !started.contains_key(&m.card) {

            started.insert(m.card, m.at);

        }

        if col == done && !finished.contains_key(&m.card) {

            if let Some(s) = started.get(&m.card) {

                finished.insert(m.card, m.at - s);

            }

        }

    }

    finished.into_values().collect()

}

/// The `p`th percentile (0 to 100) of `values`, nearest rank; `None` for none.

pub fn percentile(values: &[i64], p: u32) -> Option<i64> {

    if values.is_empty() {

        return None;

    }

    let mut v = values.to_vec();

    v.sort_unstable();

    let rank = ((p as f64 / 100.0) * v.len() as f64).ceil().max(1.0) as usize;

    Some(v[rank.min(v.len()) - 1])

}

/// Cards that first reached `done` in each of the `weeks` whole weeks

/// before `now`, oldest first.

pub fn weekly_throughput(moves: &[Move], done: i64, now: i64, weeks: usize) -> Vec<usize> {

    let mut first: HashMap<i64, i64> = HashMap::new();

    for m in moves {

        if m.column == Some(done) {

            first.entry(m.card).or_insert(m.at);

        }

    }

    let start = now - weeks as i64 * WEEK_MS;

    let mut out = vec![0; weeks];

    for at in first.values() {

        if *at >= start && *at < now {

            out[((at - start) / WEEK_MS) as usize] += 1;

        }

    }

    out

}

/// A forecast: in how many weeks the remaining cards are done at 50% and

/// 85% confidence, from how many weeks of history, and `None` when the

/// history holds no finished card to go on.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Forecast {

    pub remaining: usize,

    pub weeks_of_history: usize,

    pub p50_weeks: Option<usize>,

    pub p85_weeks: Option<usize>,

}

/// A small, seeded generator (xorshift64*): the forecast is the same for

/// the same history and seed, so it is testable and does not flicker

/// between page loads.

struct Rng(u64);

impl Rng {

    fn next(&mut self) -> u64 {

        let mut x = self.0;

        x ^= x >> 12;

        x ^= x << 25;

        x ^= x >> 27;

        self.0 = x;

        x.wrapping_mul(0x2545_F491_4F6C_DD1D)

    }

    fn below(&mut self, n: usize) -> usize {

        (self.next() % n as u64) as usize

    }

}

/// Weeks a run of trials can take at most before it is counted as never.

const HORIZON_WEEKS: usize = 520;

/// A Monte Carlo of when `remaining` cards are done: each trial draws

/// weeks from `throughput` (cards finished in each past week) until the

/// remaining cards are used up, `trials` times, seeded with `seed`.

pub fn forecast(throughput: &[usize], remaining: usize, trials: usize, seed: u64) -> Forecast {

    let weeks_of_history = throughput.len();

    if remaining == 0 {

        return Forecast { remaining, weeks_of_history, p50_weeks: Some(0), p85_weeks: Some(0) };

    }

    if throughput.iter().all(|t| *t == 0) || trials == 0 {

        return Forecast { remaining, weeks_of_history, p50_weeks: None, p85_weeks: None };

    }

    let mut rng = Rng(seed | 1);

    let mut taken: Vec<i64> = Vec::with_capacity(trials);

    for _ in 0..trials {

        let (mut left, mut weeks) = (remaining as i64, 0usize);

        while left > 0 && weeks < HORIZON_WEEKS {

            left -= throughput[rng.below(throughput.len())] as i64;

            weeks += 1;

        }

        taken.push(weeks as i64);

    }

    let at = |p| percentile(&taken, p).map(|w| w as usize).filter(|w| *w < HORIZON_WEEKS);

    Forecast { remaining, weeks_of_history, p50_weeks: at(50), p85_weeks: at(85) }

}

/// The open iteration's burn-down and scope: at the end of each day so

/// far, cards on the board not in `done` (left) and those plus the ones

/// that reached `done` since the iteration began (scope).

pub fn burn_down(moves: &[Move], done: i64, start: i64, days: usize) -> Vec<(usize, usize)> {

    let mut at: HashMap<i64, Option<i64>> = HashMap::new();

    let mut done_since: std::collections::HashSet<i64> = Default::default();

    let mut i = 0;

    let mut out = Vec::with_capacity(days);

    for d in 0..days {

        let end = start + (d as i64 + 1) * DAY_MS;

        while i < moves.len() && moves[i].at < end {

            let m = moves[i];

            at.insert(m.card, m.column);

            if m.column == Some(done) && m.at >= start {

                done_since.insert(m.card);

            }

            i += 1;

        }

        let left = at.values().filter(|c| c.is_some() && **c != Some(done)).count();

        // Done stays done when it leaves the board (an iteration closing).

        out.push((left, left + done_since.len()));

    }

    out

}

/// Points for an SVG polyline of `values` in a `w` × `h` box scaled to

/// `max` (at least 1), one step per value.

pub fn polyline(values: &[usize], max: usize, w: i64, h: i64) -> String {

    let max = max.max(1) as f64;

    let n = values.len().max(2) - 1;

    values

        .iter()

        .enumerate()

        .map(|(i, v)| format!("{},{}", (i as i64 * w) / n as i64, h - ((*v as f64 / max) * h as f64).round() as i64))

        .collect::<Vec<_>>()

        .join(" ")

}

/// The bands of a cumulative flow chart as SVG polygon points, one per

/// column (bottom band last in board order, Done at the bottom): each band

/// spans from the sum of the columns after it to that sum plus its own.

pub fn flow_bands(rows: &[Vec<usize>], w: i64, h: i64) -> Vec<String> {

    let cols = rows.first().map(|r| r.len()).unwrap_or(0);

    let max = rows.iter().map(|r| r.iter().sum::<usize>()).max().unwrap_or(0).max(1) as f64;

    let n = rows.len().max(2) - 1;

    let x = |i: usize| (i as i64 * w) / n as i64;

    let y = |v: usize| h - ((v as f64 / max) * h as f64).round() as i64;

    (0..cols)

        .map(|k| {

            let below = |r: &Vec<usize>| r[k + 1..].iter().sum::<usize>();

            let top: Vec<String> = rows.iter().enumerate().map(|(i, r)| format!("{},{}", x(i), y(below(r) + r[k]))).collect();

            let bottom: Vec<String> = rows.iter().enumerate().rev().map(|(i, r)| format!("{},{}", x(i), y(below(r)))).collect();

            [top, bottom].concat().join(" ")

        })

        .collect()

}

#[cfg(test)]

mod tests {

    use super::*;

    const T0: i64 = 1_000 * DAY_MS;

    fn m(card: i64, column: Option<i64>, day: i64) -> Move {

        Move { card, column, at: T0 + day * DAY_MS + 3_600_000 }

    }

    /// Backlog 1, Doing 2, Done 3: card 1 goes the whole way in four days,

    /// card 2 reaches Doing on day 2 and stays, card 3 is added straight

    /// into Doing on day 3 and done on day 5, card 4 is archived on day 4.

    fn board() -> Vec<Move> {

        vec![

            m(1, Some(1), 0),

            m(2, Some(1), 0),

            m(4, Some(1), 0),

            m(1, Some(2), 1),

            m(2, Some(2), 2),

            m(3, Some(2), 3),

            m(4, None, 4),

            m(1, Some(3), 5),

            m(3, Some(3), 5),

        ]

    }

    #[test]

    fn cumulative_flow_replays_the_moves() {

        let rows = cumulative_flow(&board(), &[1, 2, 3], T0, 6);

        assert_eq!(rows, vec![vec![3, 0, 0], vec![2, 1, 0], vec![1, 2, 0], vec![1, 3, 0], vec![0, 3, 0], vec![0, 1, 2]]);

        let bands = flow_bands(&rows, 100, 30);

        assert_eq!(bands.len(), 3);

        assert!(bands[2].starts_with("0,30"), "Done is the bottom band: {}", bands[2]);

    }

    #[test]

    fn cycle_time_and_throughput() {

        let mut times = cycle_times(&board(), 1, 3);

        times.sort();

        assert_eq!(times, vec![2 * DAY_MS, 4 * DAY_MS], "card 3: day 3 to 5; card 1: day 1 to 5");

        assert_eq!(percentile(&times, 50), Some(2 * DAY_MS));

        assert_eq!(percentile(&times, 85), Some(4 * DAY_MS));

        assert_eq!(percentile(&[], 50), None);

        let now = T0 + 7 * DAY_MS;

        assert_eq!(weekly_throughput(&board(), 3, now, 2), vec![0, 2]);

    }

    #[test]

    fn the_forecast_is_seeded_and_honest() {

        // Two cards a week, every week: ten cards take five weeks, always.

        let f = forecast(&[2, 2, 2, 2], 10, 1000, 7);

        assert_eq!((f.p50_weeks, f.p85_weeks, f.weeks_of_history), (Some(5), Some(5), 4));

        // Uneven weeks: the 85% date is no earlier than the 50% one, and the

        // same seed gives the same answer.

        let a = forecast(&[0, 1, 4, 2, 3], 12, 2000, 42);

        assert_eq!(a, forecast(&[0, 1, 4, 2, 3], 12, 2000, 42));

        let (p50, p85) = (a.p50_weeks.unwrap(), a.p85_weeks.unwrap());

        assert!((4..=7).contains(&p50) && p85 >= p50, "{a:?}");

        // Nothing finished yet: no forecast, said plainly.

        assert_eq!(forecast(&[0, 0], 5, 100, 1).p50_weeks, None);

        assert_eq!(forecast(&[], 5, 100, 1).p50_weeks, None);

        assert_eq!(forecast(&[1], 0, 100, 1).p85_weeks, Some(0));

    }

    #[test]

    fn burn_down_counts_left_and_scope() {

        let bd = burn_down(&board(), 3, T0, 6);

        assert_eq!(bd[0], (3, 3));

        assert_eq!(bd[3], (4, 4), "card 3 added on day 3 grows the scope");

        assert_eq!(bd[4], (3, 3), "card 4 archived on day 4 leaves it");

        assert_eq!(bd[5], (1, 3), "two done");

        assert_eq!(polyline(&[0, 2, 4], 4, 10, 10), "0,10 5,5 10,0");

    }

}

//! A board's Charts tab (oxygenhub#357): cumulative flow, cycle time,

//! throughput, the open iteration's burn-down, and forecasts of when the

//! remaining cards are done, all from the board's card moves

//! ([`crate::board_stats`]). Drawn as inline SVG in the hub's chart style,

//! with the numbers behind each chart in a table; the API gives the series.

use super::projects::{board_columns, rights_of, CardFilter};

use super::{Error, Page, Shell};

use crate::auth::Viewer;

use crate::board_stats::{self as bs, Move, DAY_MS, WEEK_MS};

use crate::db::{self, projects as pdb};

use crate::Shared;

use askama::Template;

use axum::extract::{Path, Query, State};

use axum::response::{IntoResponse, Response};

use serde::Deserialize;

use std::fmt::Write;

/// Days of cumulative flow drawn, and weeks of throughput a forecast

/// draws from.

pub const FLOW_DAYS: usize = 60;

pub const HISTORY_WEEKS: usize = 12;

/// Monte Carlo trials per forecast.

const TRIALS: usize = 4000;

/// The trials, for the page to say.

pub const TRIALS_SHOWN: usize = TRIALS;

const W: i64 = 640;

const H: i64 = 170;

fn day_of(ms: i64) -> String {

    let t = time::OffsetDateTime::from_unix_timestamp(ms.div_euclid(1000)).unwrap_or(time::OffsetDateTime::UNIX_EPOCH);

    format!("{:04}-{:02}-{:02}", t.year(), u8::from(t.month()), t.day())

}

fn esc(s: &str) -> String {

    s.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;")

}

/// One forecast: what it covers, how many cards are left, and the dates

/// they are done by at 50% and 85%, or why there are none.

#[derive(Clone, Debug)]

pub struct ForecastRow {

    pub scope: String,

    pub remaining: usize,

    pub weeks_of_history: usize,

    pub p50: Option<String>,

    pub p85: Option<String>,

}

/// The open iteration's name, first day, and each day's (left, scope).

pub type Burn = (String, i64, Vec<(usize, usize)>);

/// Everything the Charts tab and the API show.

pub struct Charts {

    pub columns: Vec<String>,

    /// Cumulative flow: the first day and each day's counts per column.

    pub flow_first: i64,

    pub flow: Vec<Vec<usize>>,

    /// Cycle time of the cards finished in the last [`HISTORY_WEEKS`], in days.

    pub cycle_median_days: Option<f64>,

    pub cycle_p85_days: Option<f64>,

    pub cycle_finished: usize,

    /// Cards done in each of the last [`HISTORY_WEEKS`] weeks, and when

    /// the first of them began.

    pub throughput: Vec<usize>,

    pub throughput_from: i64,

    /// The open iteration's name, first day and its days' (left, scope).

    pub burn: Option<Burn>,

    pub forecasts: Vec<ForecastRow>,

    /// The timeline (#361): iterations as spans, and the board's milestones

    /// with their due dates and forecast spans.

    pub timeline: Vec<TimelineRow>,

}

/// A row of the timeline: an iteration's span, or a milestone's due date

/// with the span its open cards are forecast to be done in (50% to 85%).

#[derive(Clone, Debug)]

pub struct TimelineRow {

    pub name: String,

    pub milestone: bool,

    pub start: Option<i64>,

    pub end: Option<i64>,

    pub due: Option<i64>,

    pub forecast: Option<(i64, i64)>,

    pub open: bool,

}

/// The board's charts as `account` may see them; `q` narrows the

/// forecast's cards as the board's filter bar does.

pub async fn compute(

    app: &Shared,

    account: Option<&db::accounts::Account>,

    project: &pdb::Project,

    q: &str,

    now: i64,

) -> sqlx::Result<Charts> {

    let (columns, _) = board_columns(app, account, &project.owner, project, false).await?;

    let ids: Vec<i64> = columns.iter().map(|c| c.column.id).collect();

    let done = pdb::done_column(&columns.iter().map(|c| c.column.clone()).collect::<Vec<_>>());

    // Only the cards this viewer may see count: the history of the rest stays out.

    let visible: std::collections::HashSet<i64> = {

        let (archived, _) = board_columns(app, account, &project.owner, project, true).await?;

        columns.iter().chain(archived.iter()).flat_map(|c| c.cards.iter().map(|v| v.card.id)).collect()

    };

    let moves: Vec<Move> = pdb::moves(&app.db, project.id, 0)

        .await?

        .into_iter()

        .filter(|(card, _, _)| visible.contains(card))

        .map(|(card, column, at)| Move { card, column, at })

        .collect();

    let today = now - now.rem_euclid(DAY_MS);

    let flow_first = (today - (FLOW_DAYS as i64 - 1) * DAY_MS).max(project.created_ms - project.created_ms.rem_euclid(DAY_MS));

    let days = ((today - flow_first) / DAY_MS + 1) as usize;

    let flow = bs::cumulative_flow(&moves, &ids, flow_first, days);

    let (mut cycle_median_days, mut cycle_p85_days, mut cycle_finished) = (None, None, 0);

    let mut throughput = vec![0; HISTORY_WEEKS];

    if let (Some(first), Some(done)) = (ids.first().copied(), done) {

        let times = bs::cycle_times(&moves, first, done);

        cycle_finished = times.len();

        let days = |ms: i64| (ms as f64 / DAY_MS as f64 * 10.0).round() / 10.0;

        cycle_median_days = bs::percentile(&times, 50).map(days);

        cycle_p85_days = bs::percentile(&times, 85).map(days);

        throughput = bs::weekly_throughput(&moves, done, now, HISTORY_WEEKS);

    }

    // History begins with the board: fewer weeks than that are not history.

    let weeks_old = ((now - project.created_ms) / WEEK_MS).max(1) as usize;

    let history: Vec<usize> = throughput[HISTORY_WEEKS.saturating_sub(weeks_old)..].to_vec();

    let iterations = pdb::iterations(&app.db, project.id).await?;

    let open = iterations.iter().find(|i| i.closed_ms.is_none());

    let burn = match (open, done) {

        (Some(it), Some(done)) => {

            let so_far = ((now.min(it.end_ms - 1) - it.start_ms) / DAY_MS + 1).clamp(1, pdb::iteration_days(it)) as usize;

            Some((it.name.clone(), it.start_ms, bs::burn_down(&moves, done, it.start_ms, so_far)))

        }

        _ => None,

    };

    // Forecasts: the open iteration's (or the whole board's) open cards,

    // each milestone's, and the filter's when one is given.

    let filter = CardFilter::parse(q);

    let open_cards: Vec<&super::projects::CardView> = columns

        .iter()

        .filter(|c| Some(c.column.id) != done)

        .flat_map(|c| c.cards.iter())

        .filter(|c| !matches!(c.state.as_str(), "closed" | "landed"))

        .collect();

    let seed = (project.id as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15) ^ (today / DAY_MS) as u64;

    let row = |scope: String, remaining: usize| {

        let f = bs::forecast(&history, remaining, TRIALS, seed);

        let date = |w: Option<usize>| w.map(|w| day_of(now + w as i64 * WEEK_MS));

        ForecastRow { scope, remaining, weeks_of_history: f.weeks_of_history, p50: date(f.p50_weeks), p85: date(f.p85_weeks) }

    };

    let mut forecasts = Vec::new();

    let mut timeline: Vec<TimelineRow> = iterations

        .iter()

        .take(6)

        .rev()

        .map(|it| TimelineRow {

            name: it.name.clone(),

            milestone: false,

            start: Some(it.start_ms),

            end: Some(it.end_ms),

            due: None,

            forecast: None,

            open: it.closed_ms.is_none(),

        })

        .collect();

    if !q.trim().is_empty() {

        forecasts.push(row(format!("Cards matching {}", q.trim()), open_cards.iter().filter(|c| filter.keeps(c, now)).count()));

    }

    let scope = match open {

        Some(it) => format!("{} (open cards on the board)", it.name),

        None => "Open cards on the board".to_string(),

    };

    forecasts.push(row(scope, open_cards.len()));

    let mut milestones: Vec<String> = open_cards.iter().map(|c| c.milestone.clone()).filter(|m| !m.is_empty()).collect();

    milestones.sort();

    milestones.dedup();

    // Milestones' due dates, from the repositories of the cards that name them.

    let mut due: std::collections::HashMap<String, i64> = Default::default();

    let mut repos: Vec<i64> = open_cards.iter().filter(|c| !c.milestone.is_empty()).filter_map(|c| c.card.repo_id).collect();

    repos.sort();

    repos.dedup();

    for rid in repos {

        for ms in db::issues::milestones(&app.db, rid).await? {

            if let Some(d) = ms.due_ms {

                due.entry(ms.title).and_modify(|e| *e = (*e).min(d)).or_insert(d);

            }

        }

    }

    for m in milestones {

        let n = open_cards.iter().filter(|c| c.milestone == m).count();

        let f = bs::forecast(&history, n, TRIALS, seed);

        let at = |w: Option<usize>| w.map(|w| now + w as i64 * WEEK_MS);

        timeline.push(TimelineRow {

            name: m.clone(),

            milestone: true,

            start: None,

            end: None,

            due: due.get(&m).copied(),

            forecast: at(f.p50_weeks).zip(at(f.p85_weeks)),

            open: true,

        });

        forecasts.push(row(format!("Milestone {m}"), n));

    }

    Ok(Charts {

        columns: columns.iter().map(|c| c.column.name.clone()).collect(),

        flow_first,

        flow,

        cycle_median_days,

        cycle_p85_days,

        cycle_finished,

        throughput,

        throughput_from: now - HISTORY_WEEKS as i64 * WEEK_MS,

        burn,

        forecasts,

        timeline,

    })

}

/// The timeline as SVG: a row per iteration (its span) and per milestone

/// (its due date as a mark, its forecast as a band), today as a line.

pub fn timeline_svg(rows: &[TimelineRow], now: i64) -> String {

    let times: Vec<i64> = rows

        .iter()

        .flat_map(|r| [r.start, r.end, r.due, r.forecast.map(|f| f.0), r.forecast.map(|f| f.1)])

        .flatten()

        .chain([now - 14 * DAY_MS, now + 14 * DAY_MS])

        .collect();

    let (lo, hi) = (*times.iter().min().unwrap_or(&now), *times.iter().max().unwrap_or(&now));

    let span = (hi - lo).max(DAY_MS) as f64;

    const LABEL: f64 = 150.0;

    let x = |t: i64| LABEL + (t - lo) as f64 / span * (W as f64 - LABEL - 4.0);

    let row_h = 22.0;

    let h = rows.len() as f64 * row_h + 22.0;

    let mut out = format!(

        r#"<svg class="chart timeline" viewBox="0 0 {W} {h:.0}" role="img" aria-label="Timeline: {} iterations and milestones from {} to {}">"#,

        rows.len(),

        day_of(lo),

        day_of(hi)

    );

    for (i, r) in rows.iter().enumerate() {

        let y = i as f64 * row_h + 4.0;

        let _ = write!(out, r#"<text class="axis" x="0" y="{:.1}">{}</text>"#, y + 13.0, esc(&r.name.chars().take(22).collect::<String>()));

        if let (Some(a), Some(b)) = (r.start, r.end) {

            let class = if r.open { "s-main" } else { "s-mute" };

            let _ = write!(

                out,

                r#"<rect class="bar {class}" x="{:.1}" y="{:.1}" width="{:.1}" height="12"><title>{}: {} to {}</title></rect>"#,

                x(a),

                y + 3.0,

                (x(b) - x(a)).max(2.0),

                esc(&r.name),

                day_of(a),

                day_of(b - 1)

            );

        }

        if let Some((a, b)) = r.forecast {

            let _ = write!(

                out,

                r#"<rect class="bar s-warn forecast" x="{:.1}" y="{:.1}" width="{:.1}" height="12"><title>{}: done 50% by {}, 85% by {}</title></rect>"#,

                x(a),

                y + 3.0,

                (x(b) - x(a)).max(3.0),

                esc(&r.name),

                day_of(a),

                day_of(b)

            );

        }

        if let Some(d) = r.due {

            let _ = write!(

                out,

                r#"<path class="line s-bad" d="M{0:.1},{1:.1} l5,7 l-5,7 l-5,-7 z"><title>{2} due {3}</title></path>"#,

                x(d),

                y + 2.0,

                esc(&r.name),

                day_of(d)

            );

        }

    }

    let _ = write!(out, r#"<line class="grid today" x1="{0:.1}" x2="{0:.1}" y1="0" y2="{1:.0}"/>"#, x(now), h - 18.0);

    let _ = write!(out, r#"<text class="axis" x="{LABEL}" y="{:.0}">{}</text>"#, h - 4.0, day_of(lo));

    let _ = write!(out, r#"<text class="axis" x="{:.1}" y="{:.0}" text-anchor="middle">today</text>"#, x(now), h - 4.0);

    let _ = write!(out, r#"<text class="axis" x="{W}" y="{:.0}" text-anchor="end">{}</text></svg>"#, h - 4.0, day_of(hi));

    out

}

/// Cumulative flow as stacked bands, the board's first column on top.

fn flow_svg(c: &Charts) -> String {

    let bands = bs::flow_bands(&c.flow, W, H);

    let mut out = format!(

        r#"<svg class="chart flow" viewBox="0 0 {W} {}" role="img" aria-label="Cumulative flow: cards per column each day for {} days">"#,

        H + 18,

        c.flow.len()

    );

    for (k, pts) in bands.iter().enumerate() {

        let class = if k + 1 == bands.len() { 5 } else { k % 5 };

        let _ = write!(out, r#"<polygon class="band cf-{class}" points="{pts}"><title>{}</title></polygon>"#, esc(&c.columns[k]));

    }

    let _ = write!(out, r#"<text class="axis" x="0" y="{}">{}</text>"#, H + 14, day_of(c.flow_first));

    let _ = write!(out, r#"<text class="axis" x="{W}" y="{}" text-anchor="end">today</text></svg>"#, H + 14);

    out

}

/// Bars, one per week.

fn bars_svg(values: &[usize], label: &str) -> String {

    let max = values.iter().copied().max().unwrap_or(0).max(1);

    let step = W as f64 / values.len().max(1) as f64;

    let mut out = format!(r#"<svg class="chart" viewBox="0 0 {W} {}" role="img" aria-label="{}">"#, H + 18, esc(label));

    for (i, v) in values.iter().enumerate() {

        let h = (*v as f64 / max as f64) * H as f64;

        let _ = write!(

            out,

            r#"<rect class="bar s-ok" x="{:.1}" y="{:.1}" width="{:.1}" height="{h:.1}"><title>{v} done</title></rect>"#,

            i as f64 * step + step * 0.15,

            H as f64 - h,

            step * 0.7

        );

    }

    let _ = write!(out, r#"<text class="axis" x="0" y="{}">{} weeks ago</text>"#, H + 14, values.len());

    let _ = write!(out, r#"<text class="axis" x="{W}" y="{}" text-anchor="end">this week</text></svg>"#, H + 14);

    out

}

/// The burn-down: cards left, and the scope above it.

fn burn_svg(days: &[(usize, usize)]) -> String {

    let max = days.iter().map(|(_, s)| *s).max().unwrap_or(0).max(1);

    let left: Vec<usize> = days.iter().map(|(l, _)| *l).collect();

    let scope: Vec<usize> = days.iter().map(|(_, s)| *s).collect();

    format!(

        r#"<svg class="chart" viewBox="0 0 {W} {H}" role="img" aria-label="Burn-down: {} cards left of {} after {} days"><polyline class="line s-mute" points="{}"><title>scope</title></polyline><polyline class="line s-main" points="{}"><title>left</title></polyline></svg>"#,

        left.last().unwrap_or(&0),

        scope.last().unwrap_or(&0),

        days.len(),

        bs::polyline(&scope, max, W, H),

        bs::polyline(&left, max, W, H)

    )

}

#[derive(Template)]

#[template(path = "project_charts.html")]

pub struct ChartsPage {

    shell: Shell,

    project: pdb::Project,

    views: Vec<pdb::View>,

    c: Charts,

    flow_svg: String,

    throughput_svg: String,

    burn_svg: String,

    timeline_svg: String,

    /// The last fortnight of cumulative flow, for its table: day and counts.

    flow_table: Vec<(String, Vec<usize>)>,

    week_table: Vec<(String, usize)>,

    q: String,

}

#[derive(Deserialize, Default)]

pub struct ChartsQuery {

    #[serde(default)]

    q: Option<String>,

}

pub async fn show(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, number)): Path<(String, i64)>,

    Query(query): Query<ChartsQuery>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/projects/{owner}/{number}/charts"), &viewer);

    let e = |e| Error::from_db(shell.clone(), e);

    let r = rights_of(&app, viewer.account(), &owner).await.map_err(e)?.ok_or_else(|| Error::not_found(shell.clone()))?;

    let project = pdb::get(&app.db, &owner, number)

        .await

        .map_err(e)?

        .filter(|p| p.public || r.member)

        .ok_or_else(|| Error::not_found(shell.clone()))?;

    let now = db::now_ms();

    let q = query.q.unwrap_or_default();

    let c = compute(&app, viewer.account(), &project, &q, now).await.map_err(e)?;

    let flow_table = c

        .flow

        .iter()

        .enumerate()

        .skip(c.flow.len().saturating_sub(14))

        .map(|(d, row)| (day_of(c.flow_first + d as i64 * DAY_MS), row.clone()))

        .collect();

    let week_table = c.throughput.iter().enumerate().map(|(i, n)| (day_of(c.throughput_from + i as i64 * WEEK_MS), *n)).collect();

    let page = ChartsPage {

        flow_svg: flow_svg(&c),

        throughput_svg: bars_svg(&c.throughput, "Throughput: cards done each week"),

        burn_svg: c.burn.as_ref().map(|(_, _, d)| burn_svg(d)).unwrap_or_default(),

        timeline_svg: if c.timeline.is_empty() { String::new() } else { timeline_svg(&c.timeline, now) },

        views: pdb::views(&app.db, project.id).await.map_err(e)?,

        shell,

        project,

        c,

        flow_table,

        week_table,

        q,

    };

    Ok(Page(page).into_response())

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn the_timeline_draws_iterations_milestones_and_forecasts() {

        let now = 1_000 * DAY_MS;

        let rows = vec![

            TimelineRow {

                name: "Sprint 1".into(),

                milestone: false,

                start: Some(now - 20 * DAY_MS),

                end: Some(now - 6 * DAY_MS),

                due: None,

                forecast: None,

                open: false,

            },

            TimelineRow {

                name: "Sprint 2".into(),

                milestone: false,

                start: Some(now - 6 * DAY_MS),

                end: Some(now + 8 * DAY_MS),

                due: None,

                forecast: None,

                open: true,

            },

            TimelineRow {

                name: "Release <1>".into(),

                milestone: true,

                start: None,

                end: None,

                due: Some(now + 10 * DAY_MS),

                forecast: Some((now + 7 * DAY_MS, now + 21 * DAY_MS)),

                open: true,

            },

        ];

        let svg = timeline_svg(&rows, now);

        assert!(svg.starts_with("<svg class=\"chart timeline\"") && svg.ends_with("</svg>"));

        assert_eq!(svg.matches("class=\"bar s-mute\"").count(), 1, "a past iteration");

        assert_eq!(svg.matches("class=\"bar s-main\"").count(), 1, "the open one");

        assert!(svg.contains("Release <1>: done 50% by") && svg.contains("class=\"line s-bad\""), "{svg}");

        assert!(svg.contains("aria-label=\"Timeline: 3 iterations and milestones"), "named for a screen reader");

        assert!(!svg.contains("style="), "coloured by the theme's classes only");

    }

}

{% extends "base.html" %}

{% block title %}Charts · {{ project.title }} · Projects · {{ project.owner }}{% endblock %}

{% block mainclass %} class="wide"{% endblock %}

{% block content %}

<div class="head"><h1>{{ project.title }} <small><a href="/projects/{{ project.owner }}">{{ project.owner }}'s projects</a> · #{{ project.number }}</small></h1></div>

<nav class="board-tabs" aria-label="Views of this board">

  <a class="board-tab" href="/projects/{{ project.owner }}/{{ project.number }}">Board</a>

  {% for v in views %}<a class="board-tab" href="/projects/{{ project.owner }}/{{ project.number }}?view={{ v.name|urlencode }}">{{ v.name }} <span class="small mute">{{ v.layout }}</span></a>{% endfor %}

  <a class="board-tab on" href="/projects/{{ project.owner }}/{{ project.number }}/charts" aria-current="page">Charts</a>

</nav>

<p class="small mute">From the board's own history: when each card joined each column. No estimates; the forecasts sample the weeks the board has had.</p>

<section aria-labelledby="fc-h">

<h2 id="fc-h">Forecasts</h2>

<form class="board-filter" method="get" action="/projects/{{ project.owner }}/{{ project.number }}/charts" role="search">

  <label class="visually-hidden" for="fc-q">Forecast the cards matching</label><input type="search" id="fc-q" name="q" value="{{ q }}" placeholder="forecast cards matching: label:bug, milestone:…, repo:…">

  <button type="submit" class="small">FORECAST</button>

</form>

<div class="table-wrap"><table class="board-table">

  <thead><tr><th scope="col">Cards</th><th scope="col">Left</th><th scope="col">50% done by</th><th scope="col">85% done by</th></tr></thead>

  <tbody>{% for f in c.forecasts %}<tr><td>{{ f.scope }}</td><td>{{ f.remaining }}</td>

    {% match f.p50 %}{% when Some(d) %}<td><strong>{{ d }}</strong></td>{% when None %}<td class="mute" colspan="2">no forecast: no card has reached Done in the weeks it draws from</td>{% endmatch %}

    {% if let Some(d) = f.p85 %}<td>{{ d }}</td>{% else if f.p50.is_some() %}<td class="mute">beyond ten years</td>{% endif %}</tr>{% endfor %}</tbody>

</table></div>

{% if let Some(f) = c.forecasts.first() %}<p class="small mute">From {{ f.weeks_of_history }} week{% if f.weeks_of_history != 1 %}s{% endif %} of throughput (cards reaching Done each week), sampled {{ crate::web::board_charts::TRIALS_SHOWN }} times; the same history gives the same dates all day.</p>{% endif %}

</section>

<div class="chart-grid">

<figure class="chart-card wide-card" id="timeline"><figcaption>Timeline</figcaption>

  {% if timeline_svg.is_empty() %}<p class="mute">No iterations yet, and no open card with a milestone. Start an iteration on the board, or give cards milestones, and they appear here.</p>

  {% else %}{{ timeline_svg|safe }}

  <div class="legend"><span class="key s-main">open iteration</span><span class="key s-mute">past iteration</span><span class="key s-warn">forecast: 50% to 85%</span><span class="key s-bad">milestone due</span></div>{% endif %}

</figure>

{% if let Some((name, _, days)) = c.burn %}

<figure class="chart-card"><figcaption>{{ name }}: burn-down</figcaption>{{ burn_svg|safe }}

  <div class="legend"><span class="key s-main">cards left</span><span class="key s-mute">scope</span></div>

  <p class="small mute">{% if let Some((l, s)) = days.last() %}{{ l }} left of {{ s }} after {{ days.len() }} day{% if days.len() != 1 %}s{% endif %}{% endif %}.</p>

</figure>

{% endif %}

<figure class="chart-card"><figcaption>Cycle time</figcaption>

  {% match c.cycle_median_days %}{% when Some(m) %}<p class="kpi"><span class="kpi-v">{{ m }} d</span> <span class="kpi-l">median</span> · <span class="kpi-v">{% if let Some(p) = c.cycle_p85_days %}{{ p }}{% endif %} d</span> <span class="kpi-l">85th percentile</span></p>

  <p class="small mute">From leaving the first column to reaching Done, over {{ c.cycle_finished }} finished card{% if c.cycle_finished != 1 %}s{% endif %}.</p>

  {% when None %}<p class="mute">No card has gone from started to Done yet.</p>{% endmatch %}

</figure>

<figure class="chart-card"><figcaption>Throughput: cards done each week</figcaption>{{ throughput_svg|safe }}

  <details><summary class="small">the numbers</summary><table class="board-table"><thead><tr><th scope="col">Week from</th><th scope="col">Done</th></tr></thead><tbody>{% for (w, n) in week_table %}<tr><td>{{ w }}</td><td>{{ n }}</td></tr>{% endfor %}</tbody></table></details>

</figure>

<figure class="chart-card wide-card"><figcaption>Cumulative flow</figcaption>{{ flow_svg|safe }}

  <div class="legend">{% for name in c.columns %}<span class="key cf-key cf-{% if loop.last %}5{% else %}{{ loop.index0 % 5 }}{% endif %}">{{ name }}</span>{% endfor %}</div>

  <p class="small mute">Cards in each column at the end of each day. A band that keeps widening is where work waits.</p>

  <details><summary class="small">the last fortnight's numbers</summary><div class="table-wrap"><table class="board-table"><thead><tr><th scope="col">Day</th>{% for name in c.columns %}<th scope="col">{{ name }}</th>{% endfor %}</tr></thead><tbody>{% for (d, row) in flow_table %}<tr><td>{{ d }}</td>{% for n in row %}<td>{{ n }}</td>{% endfor %}</tr>{% endfor %}</tbody></table></div></details>

</figure>

</div>

{% endblock %}

- **A hung test no longer holds a runner (#365):** the PostgreSQL tests run under nextest like the rest, and CI stops any test still running after ten minutes; the history scan's tests have four worker threads and a two-minute bound of their own. Two of them once sat for an hour on plex-1.

- **Charts and forecasts from the board's own history (#357):** a **Charts** tab on every board, with no estimates to keep.

  - **Forecasts**: a Monte Carlo of the board's weekly throughput (the last 12 weeks, or its life if shorter) says when the open cards will be done, at 50% and 85%: for the open iteration or the whole board, for each milestone, and for any filter. It says how many weeks it rests on, and says plainly when there is nothing to go on. Seeded by the board and the day, so it does not change between page loads.

  - **Cycle time** (leaving the first column to reaching Done: median and 85th percentile), **throughput** (cards done each week), the open iteration's **burn-down** with its scope, and **cumulative flow** (cards per column per day over 60 days, a widening band showing where work waits).

  - **Timeline** (#361): iterations as spans and milestones with their due dates and forecast bands on one time axis, today marked.

  - Drawn server-side as SVG in the hub's chart style, readable in both themes, each with its numbers in a table. `GET /projects/{owner}/{n}/charts` (`?q=`) gives the series and forecasts; `oh project charts N [-q FILTER]`.

/// `GET /projects/{owner}/{n}/charts` (#357): the board's charts and

/// forecasts from its own history.

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]

pub struct BoardCharts {

    /// The board's columns, in order.

    pub columns: Vec<String>,

    /// Cumulative flow: each day (YYYY-MM-DD) with its cards per column.

    pub cumulative_flow: Vec<FlowDay>,

    /// From leaving the first column to reaching Done, in days: median and

    /// 85th percentile, over `finished` cards; absent before any.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub cycle_time_median_days: Option<f64>,

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub cycle_time_p85_days: Option<f64>,

    pub finished: usize,

    /// Cards that reached Done each week, oldest first.

    pub throughput: Vec<WeekCount>,

    /// The open iteration's burn-down, when one is open.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub burn_down: Option<BurnDown>,

    pub forecasts: Vec<BoardForecast>,

}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct FlowDay {

    pub day: String,

    pub counts: Vec<usize>,

}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct WeekCount {

    /// The week's first day.

    pub week: String,

    pub done: usize,

}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct BurnDown {

    pub iteration: String,

    pub first_day: String,

    /// Each day so far: cards left and the scope.

    pub left: Vec<usize>,

    pub scope: Vec<usize>,

}

/// When `remaining` cards are done, at 50% and 85% (YYYY-MM-DD), from

/// `weeks_of_history` weeks of throughput; absent when none reached Done.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct BoardForecast {

    pub scope: String,

    pub remaining: usize,

    pub weeks_of_history: usize,

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub p50: Option<String>,

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub p85: Option<String>,

}

        ("BoardCharts", schemars::schema_for!(BoardCharts)),

        .route("/projects/{owner}/{number}/charts", get(projects::charts))

/// `GET /projects/{owner}/{n}/charts` (#357): `?q=` narrows the forecast

/// as the board's filter bar does.

pub async fn charts(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, number)): Path<(String, i64)>,

    Query(f): Query<BoardFilter>,

) -> Result<Json<hub_api::BoardCharts>, ApiError> {

    use crate::web::board_charts as bc;

    let c = caller(&app, &headers).await?;

    let (_, p) = visible(&app, &c, &owner, number).await?;

    let now = crate::db::now_ms();

    let ch = bc::compute(&app, c.account.as_ref(), &p, f.q.as_deref().unwrap_or(""), now).await?;

    let day = |ms: i64| {

        let t = time::OffsetDateTime::from_unix_timestamp(ms.div_euclid(1000)).unwrap_or(time::OffsetDateTime::UNIX_EPOCH);

        format!("{:04}-{:02}-{:02}", t.year(), u8::from(t.month()), t.day())

    };

    use crate::board_stats::{DAY_MS, WEEK_MS};

    Ok(Json(hub_api::BoardCharts {

        cumulative_flow: ch

            .flow

            .iter()

            .enumerate()

            .map(|(d, counts)| hub_api::FlowDay { day: day(ch.flow_first + d as i64 * DAY_MS), counts: counts.clone() })

            .collect(),

        cycle_time_median_days: ch.cycle_median_days,

        cycle_time_p85_days: ch.cycle_p85_days,

        finished: ch.cycle_finished,

        throughput: ch

            .throughput

            .iter()

            .enumerate()

            .map(|(i, n)| hub_api::WeekCount { week: day(ch.throughput_from + i as i64 * WEEK_MS), done: *n })

            .collect(),

        burn_down: ch.burn.as_ref().map(|(name, start, days)| hub_api::BurnDown {

            iteration: name.clone(),

            first_day: day(*start),

            left: days.iter().map(|(l, _)| *l).collect(),

            scope: days.iter().map(|(_, s)| *s).collect(),

        }),

        forecasts: ch

            .forecasts

            .into_iter()

            .map(|f| hub_api::BoardForecast {

                scope: f.scope,

                remaining: f.remaining,

                weeks_of_history: f.weeks_of_history,

                p50: f.p50,

                p85: f.p85,

            })

            .collect(),

        columns: ch.columns,

    }))

}

pub mod board_stats;

pub mod board_charts;

        .route("/projects/{owner}/{number}/charts", get(board_charts::show))

    // Charts by API (#357): the series and a forecast, no estimates.

    let (st, v) = api(app, "GET", "/api/v1/projects/andy/1/charts", None, None).await;

    assert_eq!(st, StatusCode::OK, "{v}");

    assert_eq!(v["columns"], serde_json::json!(["Backlog", "Doing", "Done"]));

    assert!(!v["cumulative_flow"].as_array().unwrap().is_empty() && v["throughput"].as_array().unwrap().len() == 12, "{v}");

    assert_eq!(v["forecasts"][0]["scope"], "Open cards on the board", "{v}");

    let (_, v) = api(app, "GET", "/api/v1/projects/andy/1/charts?q=label:none", None, None).await;

    let today = v["cumulative_flow"].as_array().unwrap().last().unwrap()["day"].clone();

    assert_eq!((v["forecasts"][0]["remaining"].as_u64(), &v["forecasts"][0]["p50"]), (Some(0), &today), "nothing left is done today: {v}");

    // Charts (#357): one card reached Done this week, so two open cards

    // (an issue and a note) are forecast two weeks out; the flow's Done band

    // is drawn in the success colour.

    let ch = get(app, "/projects/andy/1/charts", Some(&andy)).await.body;

    assert!(ch.contains("Cumulative flow") && ch.contains("class=\"band cf-5\""), "{ch}");

    let two_weeks = {

        let t = time::OffsetDateTime::now_utc() + time::Duration::days(14);

        format!("{:04}-{:02}-{:02}", t.year(), u8::from(t.month()), t.day())

    };

    assert!(ch.contains("Open cards on the board</td><td>2</td>") && ch.contains(&format!("<strong>{two_weeks}</strong>")), "{ch}");

    assert!(ch.contains("From 1 week of throughput"), "says what it rests on");

    let anon_ch = get(app, "/projects/andy/1/charts", None).await.body;

    assert!(anon_ch.contains("Open cards on the board</td><td>1</td>"), "a reader's forecast counts only what it may see");

    /// A board's charts from its own history: forecasts, cycle time,

    /// throughput (#357)

    Charts {

        /// The board

        number: i64,

        /// Forecast only the cards this filter keeps (words, repo:, label:, milestone:…)

        #[arg(long, short = 'q')]

        filter: Option<String>,

    },

            }

        }

        ProjectCmd::Charts { number, filter } => {

            let path = match &filter {

                Some(q) => format!("{base}/{number}/charts?q={}", enc(q)),

                None => format!("{base}/{number}/charts"),

            };

            if json {

                println!("{}", c.get_text(&path)?);

                return Ok(0);

            }

            let ch: hub_api::BoardCharts = c.get(&path)?;

            println!("{}", ui::strong("Forecasts"));

            for f in &ch.forecasts {

                let when = match (&f.p50, &f.p85) {

                    (Some(a), Some(b)) => format!("50% by {a}, 85% by {b}"),

                    (Some(a), None) => format!("50% by {a}, 85% beyond ten years"),

                    _ => "no forecast: nothing has reached Done in the weeks it draws from".to_string(),

                };

                println!("  {}  {} left · {when}", f.scope, f.remaining);

            }

            if let Some(f) = ch.forecasts.first() {

                println!("  {}", ui::dim(&format!("from {} week(s) of throughput", f.weeks_of_history)));

            }

            println!();

            match (ch.cycle_time_median_days, ch.cycle_time_p85_days) {

                (Some(m), Some(p)) => {

                    println!("{} median {m} d, 85th percentile {p} d over {} finished", ui::strong("Cycle time"), ch.finished)

                }

                _ => println!("{} {}", ui::strong("Cycle time"), ui::dim("no card has gone from started to Done yet")),

            }

            let weeks: Vec<String> = ch.throughput.iter().map(|w| w.done.to_string()).collect();

            println!("{} {} {}", ui::strong("Throughput"), weeks.join(" "), ui::dim("(cards done each week, oldest first)"));

            if let Some(b) = &ch.burn_down {

                println!(

                    "{} {}: {} left of {}",

                    ui::strong("Burn-down"),

                    b.iteration,

                    b.left.last().unwrap_or(&0),

                    b.scope.last().unwrap_or(&0)

                );

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route, or a known one with the wrong method, too), cursor pagination (`?after=`), ETags on cacheable resources, and rate limits per token. Resources mirror the pages: `/repos/{owner}/{name}`, `/bookmarks`, `/changes/{hash}`, `/tree/{ref}/{path}`, `/file/{ref}/{path}`, `/blame`, `/history/{ref}` (`?path=`, `?offset=&limit=`, or `?r=REVSET` for the changes a revset selects, evaluated under a two-second budget and answering 400 when it does not parse or goes past it; Oxygen's docs/revset_query_language.md), `/compare`, `/conflicts`, `/proposals` (`?state=open|draft|landed|closed|all`, open ones and drafts by default; a source bookmark may hold `/`, and `owner/name:bookmark` naming the repository itself is its own bookmark), `/proposals/{n}/comments|reviews|checks|files`, `PATCH /proposals/{n}` (the title and description, for its author or a maintainer, and `labels`, the whole set by name, for triage; what is not given stays), `POST /proposals/{n}/land` (repo:write: what the Land button does, `409` with the blockers when it cannot; a landed proposal keeps the changes it landed and reports `landed` with who, how (`web`, or `api (token NAME)`) and when, which its event, the audit log and the push record also say, adding when nobody approved), `/proposals/{n}/content/{base|head}/{path}` (a changed file's bytes in the target's state or the projected state, for editor diff views), `/issues` (creating an issue can set its labels, assignees and milestone; `PATCH /issues/{n}` edits the title and body for the author or triage, and replaces labels, assignees or the milestone for triage, recording each on the timeline; unknown names are refused before anything changes), `/labels` (`POST` creates or changes one, `DELETE /labels/{name}` removes it; triage), `/milestones` (`POST` creates one or changes the description and due date of the one with that title, `PATCH /milestones/{title}` changes title, description, due date or state; triage), `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags` (`POST` creates one, repo:write; `DELETE /tags/{tag}` withdraws one, a maintainer, `409` while a release uses it; §9), `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/user/repos` (the caller's own, organisations' and collaborations, `?affiliation=&after=&limit=`, #302), `/user/orgs`, `/user/sky` (Your sky's data, the dashboard backdrop's: the caller's repositories and their events of the last 30 days as `[repo, kind, at_ms, n]`, for the Android app; oxygenhub-android#23; `/repos/{owner}/{name}/sky` gives one repository's, its pages' backdrop), `/user/issues` (the open issues assigned to the caller, in repositories it can see, newest-updated first, each with its repository and address; #359), `/user/flow/runs` (the newest Flow runs of the caller's repositories, each with its repository and jobs, `?before=MS&limit=`; oxygenhub-android#26), `/user/starter?owner=X` and `/repos/{owner}/{name}/starter` (#347: the assistants a new repository under X may ask, and, `POST {"description", "assistant"}` by its admin, an assistant's draft of an empty repository's starting files, committed in the background as the caller, the hub signing as their delegate; `GET` says `running`, `done` with the change and files, or `failed` with why), `/notifications` (the caller's inbox and unread count, each with its repository, reason, thread and label, #305; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/users/{name}/drops` and `/drops` (§4.5), `/orgs/{name}`, `/checks/{state}` (the checks on a state, named by its hash, by its heads joined with `+`, by the one head of a single-head state, or by a bookmark), `/checks/required` (`GET`, and `PUT` of the whole list by a repository admin: the checks a proposal needs, passed, to land), `/projects/{owner}` (list, create) and `/projects/{owner}/{n}` (the board as the caller may see it, with its saved `views` and each column's `wip_limit`; `?q=` applies a filter as the board's filter bar reads it (words, `repo:`, `assignee:`, `label:`, `milestone:`, `state:`, `is:open|closed`, `age:>Nd|<Nd`) and `?view=NAME` a saved view's, #361, `/charts` its cumulative flow, cycle time, weekly throughput, the open iteration's burn-down and Monte Carlo forecasts of when its open cards, each milestone's and `?q=`'s are done, at 50% and 85%, from its card moves, #357, `PATCH` for title, description, privacy and closing, and `owner` to transfer it to an owner the caller may make boards under (#125: it takes the next number there, and its old address redirects), `/cards` to list them by column or add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one, `POST /columns` (`{"name"}`, at the right), `PATCH /columns/{column}` (by id or name: `{"name", "position"}`, 0 the leftmost) and `DELETE /columns/{column}` (its cards to the first remaining column; a board keeps one) for its columns, each answering the board (#366), `POST /cards/move` (#289: `{"from", "column", "except", "state", "dry_run"}`) to move a column's cards at once, but those `except` names (card ids or issue and proposal references) and, given `state`, only those whose issue or proposal is in one, all or none and audited once, answering what moved and what was kept; `POST /cards/archive` (#293: `{"from", "older_days", "except", "state", "dry_run"}`, the same selection and an age) to archive them, `GET /cards?archived=true` to list the archived ones (each with `archived_ms`) and `POST /cards/{id}/restore` to put one back; cards carry their `labels` and `assignees`; `repo:write` and the page's rights to change), `/coverage` and `/tests` (a bookmark's coverage and JUnit test reports from Flow jobs, newest first, `?bookmark=&limit=`), `POST /coverage` (repo:write, #136: `{"bookmark"}` or `{"change"}` and `content`, an LCOV, Cobertura or JaCoCo report measured off the hub, kept for that state as uploaded by the caller, shown "uploaded by NAME" wherever a run number would be, and setting no check; `oh coverage upload FILE`), `/coverage/{id}` (a report with its files) and `/tests/{id}` (a report with its cases, `?status=failed` for the failed and errored ones), `/flow/runs` (`GET`: runs newest first, `?before=N&limit=`; `POST {"bookmark"}` or `{"change"}`, repo:write: run a bookmark's current state, the default bookmark when none is named, or one change's state; with `"jobs": [NAME..]` only those jobs and what they depend on, each one a manual run starts, else `409` naming the ones it does (#130); `oh run start --job NAME`), `/flow/runs/{n}` (a run with its jobs, each with its timings: `queued_ms`, `ready_ms`, the `phases` its runner reported (image, prepare, run, finish, in milliseconds) and its peak disk and memory; #348, `oh run view N --timings`), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`), `/flow/runs/{n}/jobs/{job}/reports` and `/flow/runs/{n}/jobs/{job}/report` (`?name=`; with its files, and `…/report/{path}` one file as published, sandboxed) and `/reports` (`?bookmark=`: the newest run of each) and `/reports/{name}` (`?id=` or `?bookmark=`; `…/files/{path}`): the reports Flow jobs publish (#348, docs/reports.md §6; `oh run report N JOB`, `oh report`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/flow/runs/{n}/jobs/{job}/rerun` (repo:write, oxygenflow#31: that job of a finished run again, in the same run, with the jobs that depend on it; what it depends on keeps its result, so a flaky test reruns without its build; their logs, artifacts and reports go, their checks return to queued and the run is running again; `{"queued": N}`, or `409` while the run is live or for a job it lacks; RE-RUN THIS JOB on the run page, `oh run rerun N --job NAME`), `/flow/runs/{n}/cancel` (repo:write: a run still going ends as `cancelled`, its running jobs stopped when their runner next reports; `409` when it had already ended; a push to a bookmark cancels the push runs of it still going: the queued ones, and those running too unless the repository keeps them or they are the default bookmark's, which always finish (#369)), `/search`. A change's author carries the account its key is linked to, or `null` and a `note` saying the key is not linked and where its owner links it; `via` names the delegate (an agent) that signed for the author when one did, with the delegation's scope and expiry and whether it has since been revoked, and the pages show the same as an `agent` badge, a `via` row under the author on the change page, and a count under the author in Contributors (the change page shows a "key not linked" tag, with a link to Settings → Keys for signed-in viewers). Shapes reuse `oxy --json` shapes wherever one exists (change, status, blame, diff) so tools written against the CLI work against the hub. `crates/hub-api` holds the types with `serde` derives and is what the runner and the VS Code extension will link.

  <a class="board-tab" href="/projects/{{ project.owner }}/{{ project.number }}/charts">Charts</a>

/* Cumulative flow bands (#357): the mark's colours, Done in the success colour. */

svg.chart .band { stroke: var(--panel); stroke-width: .5; }

.cf-0 { fill: var(--m3); color: var(--m3); } .cf-1 { fill: var(--m1); color: var(--m1); } .cf-2 { fill: var(--warn); color: var(--warn); }

.cf-3 { fill: var(--m4); color: var(--m4); } .cf-4 { fill: var(--m5); color: var(--m5); } .cf-5 { fill: var(--ok); color: var(--ok); }

.legend .key.cf-key { color: var(--ink); fill: none; }

.legend .key.cf-0::before { background: var(--m3); } .legend .key.cf-1::before { background: var(--m1); } .legend .key.cf-2::before { background: var(--warn); }

.legend .key.cf-3::before { background: var(--m4); } .legend .key.cf-4::before { background: var(--m5); } .legend .key.cf-5::before { background: var(--ok); }

.chart-card.wide-card { grid-column: 1 / -1; }

.kpi { margin: 6px 0; }

svg.timeline .forecast { opacity: .55; }

svg.timeline .today { stroke: var(--acc); stroke-dasharray: 3 3; }

svg.timeline path.line { fill: currentColor; }