create-pmos 0.133.0 → 0.135.0

package/workspace/lib/calendar-tidy.js

@@ -0,0 +1,230 @@
+'use strict';
+/* calendar-tidy.js — the tidy-up suggestions of the console3 Calendar page (initiative calendar-tidy-up, R1 to R6).
+ *
+ *   tidyFrom({ range, today, nowMs, events, eventsSource, inis, gantt, planItems })   → { tidy, tidy_total, tidy_note }
+ *
+ * PURE and READ ONLY. No I/O, no clock, no model call, and no write function: a suggestion is a proposal in words. PMOS holds
+ * no calendar credentials, so nothing here can move, decline or send anything (R3).
+ *
+ * INPUT (plain data that routes-calendar-views.js already holds):
+ *   range       = { start, end } 'YYYY-MM-DD'
+ *   events      = imported events ({ id, at, end, title, initiative, prep, prep_done, steps }); all of them, this filters
+ *   inis        = the initiative facts ({ id, title, done, status, promised, stopped:{state}, horizon })
+ *   gantt       = model.ganttRows rows ({ id, status, promised })
+ *   planItems   = [{ id, initiative, title, due, milestone, state }]
+ *
+ * THE RULES (PRD R2). Each gives at most one suggestion per pair or item.
+ *   overlap          bad   two timed events that overlap
+ *   no-buffer        warn  two timed events on the same day with a gap of 0 to 9 minutes (10 minutes or more is fine)
+ *   prep-risk        warn  calendar-layers prepRisks: less than PER_STEP (30) free minutes for each prep step left
+ *   dead-initiative  warn  an event about an initiative that is done, parked, on hold, closed or cancelled
+ *   review-early     info  a review, sync or checkpoint event before a milestone or promised date of its initiative that
+ *                          is not done (the nearest one is named)
+ *   likely-delay     bad   a milestone or promised date in range of an initiative that is overdue or delayed
+ *                    warn  the same, for an initiative at risk
+ *   heavy-day        info  a working day with more than 6 hours (360 minutes) of timed meetings; exactly 6 hours is fine
+ * All-day events (a date with no time) take no time, so the time rules leave them out.
+ *
+ * OUTPUT. Sorted by severity (bad, warn, info), then date, then id; capped at TIDY_CAP; tidy_total counts all. tidy_note
+ * names each rule that could not run, with the reason (R5): no events in the range, or no initiative data. */
+const L = require('./calendar-layers.js');
+
+const TIDY_CAP = 40;
+const BUFFER_MIN = 10;
+const HEAVY_MIN = 6 * 60;
+const SEVERITY = ['bad', 'warn', 'info'];
+const RULES = ['overlap', 'no-buffer', 'prep-risk', 'dead-initiative', 'review-early', 'likely-delay', 'heavy-day'];
+const EVENT_RULES = ['overlap', 'no-buffer', 'prep-risk', 'dead-initiative', 'review-early', 'heavy-day'];
+const INI_RULES = ['dead-initiative', 'review-early', 'likely-delay'];
+const REVIEW_RE = /review|sync|checkpoint/i;
+
+const pad = (n) => String(n).padStart(2, '0');
+const isDay = (s) => typeof s === 'string' && /^\d{4}-\d{2}-\d{2}/.test(s) && !Number.isNaN(Date.parse(s.slice(0, 10) + 'T00:00:00Z'));
+const day10 = (s) => String(s).slice(0, 10);
+const str = (v) => (typeof v === 'string' ? v.trim() : '');
+const hhmm = (ms) => { const m = L.minuteOfDay(ms); return `${pad(Math.floor(m / 60))}:${pad(m % 60)}`; };
+const dow = (s) => new Date(Date.parse(s + 'T00:00:00Z')).getUTCDay();
+const isWorkday = (s) => dow(s) >= 1 && dow(s) <= 5;
+const duration = (min) => { const h = Math.floor(min / 60); const m = min % 60; return m ? `${h} h ${m} min` : `${h} h`; };
+const titleOf = (e) => str(e && e.title) || 'a meeting';
+const evRef = (e) => ({ type: 'event', id: String(e.id) });
+const iniRef = (id) => ({ type: 'initiative', id: String(id) });
+
+/** The state that makes an initiative's meetings pointless, as a word, or null while it is live. */
+function deadWord(ini) {
+  if (!ini) return null;
+  if (ini.done || ini.status === 'done') return 'done';
+  const st = ini.stopped && str(ini.stopped.state).toLowerCase();
+  if (st === 'on-hold' || st === 'held' || st === 'on hold') return 'on hold';
+  if (st === 'closed' || st === 'cancelled' || st === 'parked') return st;
+  const words = [ini.horizon, ini.status, ini.stage, ini.lifecycle && ini.lifecycle.state].map((x) => str(x).toLowerCase());
+  if (words.includes('parked')) return 'parked';
+  if (words.some((w) => w === 'on hold' || w === 'on-hold' || w === 'held')) return 'on hold';
+  return null;
+}
+
+/** The worst delay status of an initiative from its facts and its gantt row: 'overdue' | 'delayed' | 'at risk' | null. */
+function delayWord(ini, row) {
+  const order = ['overdue', 'delayed', 'at risk'];
+  const found = [ini && ini.status, row && row.status].map((x) => str(x).toLowerCase()).filter((x) => order.includes(x));
+  if (!found.length) return null;
+  return order.find((o) => found.includes(o));
+}
+
+/** The dated milestones of each initiative that are not done: its promised date and its plan-item milestones. */
+function milestonesOf(inis, planItems) {
+  const out = new Map();
+  const add = (id, m) => { if (!out.has(id)) out.set(id, []); out.get(id).push(m); };
+  for (const i of inis) {
+    if (!i || !i.id || i.done || !isDay(i.promised)) continue;
+    add(String(i.id), { date: day10(i.promised), title: `the promised date of ${str(i.title) || i.id}`, short: 'the promised date', ref: iniRef(i.id), key: `ini:${i.id}:promised` });
+  }
+  for (const p of planItems || []) {
+    if (!p || !p.id || !p.initiative || !p.milestone || p.state === 'done' || !isDay(p.due)) continue;
+    add(String(p.initiative), { date: day10(p.due), title: `the milestone ${str(p.title) || p.id}`, short: `the milestone ${str(p.title) || p.id}`, ref: { type: 'plan-item', id: String(p.id) }, key: `plan:${p.id}` });
+  }
+  for (const list of out.values()) list.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : a.key < b.key ? -1 : 1));
+  return out;
+}
+
+function tidyFrom(input = {}) {
+  const range = input.range || {};
+  const today = input.today;
+  const inis = Array.isArray(input.inis) ? input.inis.filter((i) => i && i.id) : [];
+  const iniById = new Map(inis.map((i) => [String(i.id), i]));
+  const rowById = new Map((input.gantt || []).filter((r) => r && r.id).map((r) => [String(r.id), r]));
+  const inRange = (d) => d >= range.start && d <= range.end;
+
+  // the events inside the range, each with its day and, when it has a time, its span
+  const events = [];
+  for (const e of input.events || []) {
+    const at = e && (e.at || e.start);
+    if (!e || !e.id || !isDay(at)) continue;
+    const sp = L.spanOf(e);
+    const date = sp ? L.localDay(sp.s) : day10(at);
+    if (!inRange(date)) continue;
+    events.push({ e, date, sp });
+  }
+  const timed = events.filter((x) => x.sp).sort((a, b) => a.sp.s - b.sp.s || b.sp.f - a.sp.f || (String(a.e.id) < String(b.e.id) ? -1 : 1));
+
+  const note = {};
+  if (!events.length) {
+    const why = input.eventsSource === 'none' ? 'no calendar is imported, so there are no events to check' : 'no events fall inside this range';
+    for (const r of EVENT_RULES) note[r] = why;
+  }
+  if (!inis.length) for (const r of INI_RULES) if (!note[r]) note[r] = 'no initiative status was read, so initiatives cannot be checked';
+
+  const out = new Map();
+  const put = (s) => { if (!out.has(s.id)) out.set(s.id, s); };
+
+  // overlap and no-buffer: every pair of timed events on the same day
+  const byDay = new Map();
+  for (const x of timed) { if (!byDay.has(x.date)) byDay.set(x.date, []); byDay.get(x.date).push(x); }
+  for (const [date, list] of byDay) {
+    for (let i = 0; i < list.length; i++) {
+      for (let j = i + 1; j < list.length; j++) {
+        const a = list[i]; const b = list[j];          // a starts first (or at the same time and runs longer)
+        const pair = [String(a.e.id), String(b.e.id)].sort().join('+');
+        if (b.sp.s < a.sp.f) {
+          put({ id: `overlap:${pair}`, rule: 'overlap', severity: 'bad', date,
+            title: `${titleOf(a.e)} overlaps ${titleOf(b.e)}`,
+            why: `${titleOf(a.e)} runs from ${hhmm(a.sp.s)} to ${hhmm(a.sp.f)} and ${titleOf(b.e)} starts at ${hhmm(b.sp.s)}, so you cannot attend both in full.`,
+            suggestion: `Move ${titleOf(b.e)} to ${hhmm(a.sp.f)} or shorten ${titleOf(a.e)}.`,
+            refs: [evRef(a.e), evRef(b.e)] });
+          continue;
+        }
+        const gap = Math.round((b.sp.s - a.sp.f) / 60000);
+        if (gap >= 0 && gap < BUFFER_MIN && L.localDay(a.sp.f) === date) {
+          // only the next event after a counts: a gap to a later one is never smaller than the gap to the next one
+          const between = list.some((c, k) => k !== i && k !== j && c.sp.s >= a.sp.f && c.sp.s < b.sp.s);
+          if (between) continue;
+          put({ id: `no-buffer:${pair}`, rule: 'no-buffer', severity: 'warn', date,
+            title: `No break between ${titleOf(a.e)} and ${titleOf(b.e)}`,
+            why: gap === 0
+              ? `${titleOf(b.e)} starts at ${hhmm(b.sp.s)}, the minute ${titleOf(a.e)} ends. You have no time to move, take notes or prepare.`
+              : `${titleOf(b.e)} starts ${gap} ${gap === 1 ? 'minute' : 'minutes'} after ${titleOf(a.e)} ends. That is less than ${BUFFER_MIN} minutes to move, take notes or prepare.`,
+            suggestion: `Move ${titleOf(b.e)} to ${hhmm(a.sp.f + BUFFER_MIN * 60000)} or end ${titleOf(a.e)} ${BUFFER_MIN - gap} ${BUFFER_MIN - gap === 1 ? 'minute' : 'minutes'} earlier.`,
+            refs: [evRef(a.e), evRef(b.e)] });
+        }
+      }
+    }
+  }
+
+  // prep-risk: the calendar-memory rule, for the events in range
+  if (events.length) {
+    for (const r of L.prepRisks(events.map((x) => x.e), today, input.nowMs)) {
+      put({ id: `prep-risk:${r.id}`, rule: 'prep-risk', severity: 'warn', date: r.date,
+        title: `Little time to prepare for ${r.title}`,
+        why: `${r.title} has ${r.left} prep ${r.left === 1 ? 'step' : 'steps'} left, and only ${Math.round(r.free)} minutes of free working time remain before it. Each step needs about 30 minutes.`,
+        suggestion: `Block time before ${r.title} for the prep, or move ${r.title} to a later day.`,
+        refs: [{ type: 'event', id: String(r.id) }] });
+    }
+  }
+
+  // dead-initiative and review-early: an event about an initiative
+  const miles = milestonesOf(inis, input.planItems);
+  for (const { e, date } of events) {
+    const id = e.initiative ? String(e.initiative) : null;
+    const ini = id ? iniById.get(id) : null;
+    if (!ini) continue;
+    const name = str(ini.title) || id;
+    const dead = deadWord(ini);
+    if (dead) {
+      put({ id: `dead-initiative:${e.id}`, rule: 'dead-initiative', severity: 'warn', date,
+        title: `${titleOf(e)} is about an initiative that is ${dead}`,
+        why: `${titleOf(e)} is linked to ${name}, which is ${dead}.`,
+        suggestion: `Cancel ${titleOf(e)} or give it a new purpose, because ${name} is ${dead}.`,
+        refs: [evRef(e), iniRef(id)] });
+      continue;
+    }
+    if (REVIEW_RE.test(titleOf(e))) {
+      const next = (miles.get(id) || []).find((m) => m.date > date);
+      if (next) {
+        put({ id: `review-early:${e.id}`, rule: 'review-early', severity: 'info', date,
+          title: `${titleOf(e)} comes before what it reviews`,
+          why: `${titleOf(e)} is on ${date}, but ${next.title} is on ${next.date} and is not done yet.`,
+          suggestion: `Move ${titleOf(e)} to ${next.date} or later, or keep it as a progress check and say so in the invite.`,
+          refs: [evRef(e), next.ref, ...(next.ref.type === 'initiative' ? [] : [iniRef(id)])] });
+      }
+    }
+  }
+
+  // likely-delay: a milestone or promised date in range of an initiative that is late already
+  for (const [id, list] of miles) {
+    const ini = iniById.get(id);
+    if (!ini || deadWord(ini)) continue;
+    const late = delayWord(ini, rowById.get(id));
+    if (!late) continue;
+    const name = str(ini.title) || id;
+    for (const m of list) {
+      if (!inRange(m.date)) continue;
+      put({ id: `likely-delay:${m.key}`, rule: 'likely-delay', severity: late === 'at risk' ? 'warn' : 'bad', date: m.date,
+        title: `${m.short.charAt(0).toUpperCase() + m.short.slice(1)} of ${name} is likely to slip`,
+        why: `${name} is ${late}, and ${m.title} is on ${m.date}.`,
+        suggestion: `Agree a new date for ${m.short} with the people who depend on it, or cut its scope to keep ${m.date}.`,
+        refs: m.ref.type === 'initiative' ? [m.ref] : [m.ref, iniRef(id)] });
+    }
+  }
+
+  // heavy-day: more than six hours of timed meetings on a working day (overlaps count once)
+  for (const [date, list] of byDay) {
+    if (!isWorkday(date)) continue;
+    const iv = L.minutesOn(list.map((x) => x.sp), date).map((m) => [m.from, m.to]).sort((a, b) => a[0] - b[0]);
+    let busy = 0; let cur = null;
+    for (const [s, f] of iv) { if (cur && s <= cur[1]) cur[1] = Math.max(cur[1], f); else { if (cur) busy += cur[1] - cur[0]; cur = [s, f]; } }
+    if (cur) busy += cur[1] - cur[0];
+    if (busy <= HEAVY_MIN) continue;
+    const longest = list.slice().sort((a, b) => (b.sp.f - b.sp.s) - (a.sp.f - a.sp.s))[0];
+    put({ id: `heavy-day:${date}`, rule: 'heavy-day', severity: 'info', date,
+      title: `${duration(busy)} of meetings on ${date}`,
+      why: `More than 6 hours of meetings on ${date} leave little time for focused work.`,
+      suggestion: `Move or shorten one meeting on ${date}, for example ${titleOf(longest.e)}, to free a block of focus time.`,
+      refs: list.map((x) => evRef(x.e)) });
+  }
+
+  const all = [...out.values()].sort((a, b) => SEVERITY.indexOf(a.severity) - SEVERITY.indexOf(b.severity)
+    || (a.date < b.date ? -1 : a.date > b.date ? 1 : 0) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { tidy: all.slice(0, TIDY_CAP), tidy_total: all.length, tidy_note: note };
+}
+
+module.exports = { tidyFrom, deadWord, delayWord, TIDY_CAP, BUFFER_MIN, HEAVY_MIN, RULES, SEVERITY };