// The pure logic of the Decisions components (Plan, Decision, Estimate): reading // their props, the message an approved Plan sends, a Decision's weighted // ranking and an Estimate's three-point (PERT) totals. Shared by the renderers // in ui/components/decisions.tsx and the markdown fallback in core/markdown.ts. import { isPlainObject } from "./evaluate"; import type { Value } from "./types"; /** An item's fields by key; a non-object item stands for its main field (a bare string is a title). */ type Fields = { readonly [key: string]: Value | undefined }; /** A scalar as trimmed text; anything else is empty. */ function str(value: unknown): string { if (typeof value === "string") return value.trim(); if (typeof value === "number" && Number.isFinite(value)) return String(value); if (typeof value === "boolean") return String(value); return ""; } /** A finite number, also from numeric text ("2.5"); null otherwise. */ export function readNumber(value: unknown): number | null { if (typeof value === "number") return Number.isFinite(value) ? value : null; if (typeof value === "string" && /^\s*-?(\d+(\.\d*)?|\.\d+)\s*$/.test(value)) return Number(value); return null; } /** A number without float noise, at most `digits` decimals: 2.5, 1.33, 12. */ export function round(value: number, digits = 2): number { const factor = 10 ** digits; return Math.round(value * factor) / factor; } const NUMBER = new Intl.NumberFormat("en-US", { maximumFractionDigits: 1 }); /** One decimal at most, grouped: 1,250.5. */ export function formatAmount(value: number): string { return NUMBER.format(value === 0 ? 0 : value); } /** "1, 2 and 4"; runs of three or more read as ranges: "1–3, 5 and 7–9". */ export function numberList(numbers: readonly number[]): string { const parts: string[] = []; for (let index = 0; index < numbers.length; ) { let end = index; while (end + 1 < numbers.length && numbers[end + 1] === numbers[end] + 1) end++; if (end - index >= 2) { parts.push(`${numbers[index]}–${numbers[end]}`); index = end + 1; } else { parts.push(String(numbers[index])); index++; } } return joinAnd(parts); } /** "a", "a and b", "a, b and c". */ export function joinAnd(parts: readonly string[]): string { if (parts.length <= 1) return parts.join(""); return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`; } // --------------------------------------------------------------------------- // Plan export type Risk = "low" | "medium" | "high"; export interface PlanFile { readonly path: string; readonly line: number | null; } /** A parsed estimate: an amount in a unit ("" for a bare number). */ export interface Quantity { readonly value: number; readonly unit: string; } export interface PlanStep { readonly title: string; readonly detail: string | null; readonly files: readonly PlanFile[]; readonly risk: Risk | null; /** The estimate as written ("2h", "half a day"); null when none. */ readonly estimate: string | null; /** The estimate as an amount, when it is one. */ readonly amount: Quantity | null; readonly optional: boolean; } const RISKS: Record = { low: "low", medium: "medium", med: "medium", moderate: "medium", high: "high" }; /** `path`, `path:12`, `path:12:3`, or `{path, line?}`. */ function planFile(value: Value): PlanFile | null { if (isPlainObject(value)) { const fields: Fields = value; const path = str(fields.path ?? fields.file); if (path === "") return null; const line = readNumber(fields.line); return { path, line: line !== null && line >= 1 ? Math.floor(line) : null }; } const raw = str(value); if (raw === "") return null; const match = /^(.*?):(\d+)(?::\d+)?$/.exec(raw); return match !== null && match[1] !== "" ? { path: match[1], line: Number(match[2]) } : { path: raw, line: null }; } /** Time units in minutes, with a working day of 8 h and a week of 5 days. */ const TIME_MINUTES: Record = { m: 1, h: 60, d: 8 * 60, w: 5 * 8 * 60 }; const UNIT_ALIASES: [RegExp, string][] = [ [/^(m|min|mins|minutes?)$/i, "m"], [/^(h|hr|hrs|hours?)$/i, "h"], [/^(d|days?)$/i, "d"], [/^(w|wk|wks|weeks?)$/i, "w"], [/^(pts?|points?|sp)$/i, "pts"], ]; /** A unit word as one of m, h, d, w, pts; other words stay as written. */ export function normalizeUnit(unit: string): string { const trimmed = unit.trim(); for (const [pattern, name] of UNIT_ALIASES) if (pattern.test(trimmed)) return name; return trimmed; } /** "2h", "1.5 d", "~30 min", "3 pts", 4 → a Quantity; ranges and prose → null. */ export function parseQuantity(value: unknown): Quantity | null { if (typeof value === "number") return Number.isFinite(value) && value >= 0 ? { value, unit: "" } : null; if (typeof value !== "string") return null; const match = /^\s*~?\s*(\d+(?:\.\d+)?|\.\d+)\s*([a-z]*)\s*$/i.exec(value); if (match === null) return null; const unit = normalizeUnit(match[2]); if (match[2] !== "" && !(unit in TIME_MINUTES) && unit !== "pts") return null; return { value: Number(match[1]), unit }; } /** "2.5 h", "8 pts", "1 pt", "3". */ export function formatQuantity(quantity: Quantity): string { const amount = formatAmount(quantity.value); if (quantity.unit === "") return amount; if (quantity.unit === "pts") return `${amount} ${quantity.value === 1 ? "pt" : "pts"}`; return `${amount} ${quantity.unit === "m" ? "min" : quantity.unit}`; } export interface PlanRead { readonly steps: readonly PlanStep[]; readonly error: string | null; } /** Steps from a list of `{title, detail?, files?, risk?, estimate?, optional?}` or titles; untitled items (still streaming) are left out. */ export function readPlan(value: Value | undefined): PlanRead { if (!Array.isArray(value)) return { steps: [], error: "Plan needs a list of steps" }; const steps = value.flatMap((item): PlanStep[] => { const fields: Fields = isPlainObject(item) ? item : { title: item }; const title = str(fields.title ?? fields.name ?? fields.step); if (title === "") return []; const files = (Array.isArray(fields.files) ? fields.files : fields.files === undefined ? [] : [fields.files]) .map(planFile) .filter((file): file is PlanFile => file !== null); const estimate = str(fields.estimate) || null; return [ { title, detail: str(fields.detail ?? fields.description) || null, files, risk: RISKS[str(fields.risk).toLowerCase()] ?? null, estimate, amount: estimate === null ? null : parseQuantity(fields.estimate), optional: fields.optional === true, }, ]; }); return { steps, error: null }; } /** Which steps start checked: all but the optional ones. */ export function initialChecks(steps: readonly PlanStep[]): boolean[] { return steps.map((step) => !step.optional); } export interface EstimateTotal { /** The sum, or null when the estimates can't be added (mixed points and time) or none is a number. */ readonly total: Quantity | null; /** Steps counted whose estimate isn't a number ("half a day"). */ readonly unparsed: number; readonly mixed: boolean; } /** * The sum of the estimates of the `included` steps. Time units add up in the * largest unit present (a day is 8 h, a week 5 days); points and bare * numbers add only to their own kind. */ export function planTotal(steps: readonly PlanStep[], included: readonly boolean[]): EstimateTotal { const counted = steps.filter((step, index) => included[index] !== false && step.estimate !== null); const amounts = counted.flatMap((step) => (step.amount === null ? [] : [step.amount])); const unparsed = counted.length - amounts.length; if (amounts.length === 0) return { total: null, unparsed, mixed: false }; const timed = amounts.every((amount) => amount.unit in TIME_MINUTES); const units = new Set(amounts.map((amount) => amount.unit)); if (!timed && units.size > 1) return { total: null, unparsed, mixed: true }; if (!timed) { return { total: { value: round(amounts.reduce((sum, a) => sum + a.value, 0)), unit: amounts[0].unit }, unparsed, mixed: false }; } const largest = ["w", "d", "h", "m"].find((unit) => units.has(unit)) ?? "h"; const minutes = amounts.reduce((sum, a) => sum + a.value * TIME_MINUTES[a.unit], 0); return { total: { value: round(minutes / TIME_MINUTES[largest]), unit: largest }, unparsed, mixed: false }; } /** * The one message approving the plan sends: * - all steps checked, no note: "Go ahead with the plan." * - some unchecked: "Go ahead with steps 1, 2 and 4. Skip 3 (Migrate the old rows)." * - a note adds " Note: …"; nothing checked with a note: "Don't start the plan yet. Note: …" * Empty when nothing is checked and there is no note (nothing to send). */ export function planMessage(steps: readonly PlanStep[], checked: readonly boolean[], note: string): string { const trimmed = note.trim(); const noteText = trimmed === "" ? "" : ` Note: ${trimmed}`; const kept = steps.flatMap((_, index) => (checked[index] !== false ? [index + 1] : [])); const skipped = steps.flatMap((step, index) => (checked[index] === false ? [{ number: index + 1, title: step.title }] : [])); if (kept.length === 0) return trimmed === "" ? "" : `Don't start the plan yet.${noteText}`; if (skipped.length === 0) return `Go ahead with the plan.${noteText}`; const go = `Go ahead with ${kept.length === 1 ? "step" : "steps"} ${numberList(kept)}.`; const skip = `Skip ${joinAnd(skipped.map((step) => `${step.number} (${step.title})`))}.`; return `${go} ${skip}${noteText}`; } // --------------------------------------------------------------------------- // Decision export interface Criterion { readonly name: string; readonly weight: number; readonly note: string | null; } export interface DecisionOption { readonly name: string; /** One per criterion; null where the option has no (usable) score. */ readonly scores: readonly (number | null)[]; readonly pros: readonly string[]; readonly cons: readonly string[]; readonly note: string | null; } export interface DecisionModel { readonly criteria: readonly Criterion[]; readonly options: readonly DecisionOption[]; /** The top of the score scale: 5, or 10 / 100 when the scores use those. */ readonly scale: number; /** Input problems the component shows below the matrix. */ readonly issues: readonly string[]; } export type DecisionRead = { readonly ok: true; readonly model: DecisionModel } | { readonly ok: false; readonly error: string }; function textList(value: Value | undefined): string[] { if (typeof value === "string") return value.trim() === "" ? [] : [value.trim()]; return (Array.isArray(value) ? value : []).map(str).filter((item) => item !== ""); } /** Criteria (names or `{name, weight?, note?}`) and options (`{name, scores: [..] | {criterion: score}, pros?, cons?, note?}`). */ export function readDecision(options: Value | undefined, criteria: Value | undefined): DecisionRead { if (!Array.isArray(criteria)) return { ok: false, error: "Decision needs a list of criteria" }; if (!Array.isArray(options)) return { ok: false, error: "Decision needs a list of options" }; const issues: string[] = []; const readCriteria = criteria.flatMap((item): Criterion[] => { const fields: Fields = isPlainObject(item) ? item : { name: item }; const name = str(fields.name ?? fields.label); if (name === "") return []; const raw = fields.weight; const weight = raw === undefined || raw === null ? 1 : readNumber(raw); if (weight === null || weight < 0) issues.push(`Weight ${str(raw) || "?"} for ${name} isn't a number of 0 or more; using 1.`); return [{ name, weight: weight === null || weight < 0 ? 1 : weight, note: str(fields.note) || null }]; }); if (readCriteria.length === 0) return { ok: false, error: "Decision needs at least one criterion" }; const byName = new Map(readCriteria.map((criterion, index) => [criterion.name.toLowerCase(), index])); const raws: { option: Omit; scores: (number | null)[] }[] = []; for (const item of options) { const fields: Fields = isPlainObject(item) ? item : { name: item }; const name = str(fields.name ?? fields.title ?? fields.label); if (name === "") continue; const scores: (number | null)[] = readCriteria.map(() => null); const given = fields.scores; const take = (index: number, value: unknown) => { if (value === undefined || value === null) return; const score = readNumber(value); if (score === null || score < 0) issues.push(`${name}: score ${str(value) || "?"} for ${readCriteria[index].name} isn't a number of 0 or more.`); else scores[index] = score; }; if (Array.isArray(given)) { given.slice(0, readCriteria.length).forEach((value, index) => take(index, value)); if (given.length > readCriteria.length) issues.push(`${name} has ${given.length} scores for ${readCriteria.length} criteria; the extra ones are ignored.`); } else if (given !== undefined && isPlainObject(given)) { for (const [key, value] of Object.entries(given)) { const index = byName.get(key.trim().toLowerCase()); if (index === undefined) issues.push(`${name} scores “${key}”, which isn't a criterion.`); else take(index, value); } } raws.push({ option: { name, pros: textList(fields.pros), cons: textList(fields.cons), note: str(fields.note) || null }, scores, }); } const top = Math.max(0, ...raws.flatMap((raw) => raw.scores.filter((score): score is number => score !== null))); const scale = top <= 5 ? 5 : top <= 10 ? 10 : 100; if (top > 100) issues.push("Scores above 100 are counted as 100."); const missing = raws.reduce((count, raw) => count + raw.scores.filter((score) => score === null).length, 0); if (missing > 0) issues.push(`${missing === 1 ? "One score is" : `${missing} scores are`} missing and ${missing === 1 ? "counts" : "count"} as 0.`); return { ok: true, model: { criteria: readCriteria, options: raws.map(({ option, scores }) => ({ ...option, scores: scores.map((score) => (score === null ? null : Math.min(score, scale))) })), scale, issues, }, }; } export interface Ranked { /** The option's position in `model.options`. */ readonly index: number; /** Weighted mean score on the model's scale: Σ wᵢ·sᵢ / Σ wᵢ (a missing score counts as 0). */ readonly total: number; } /** Options by weighted total, best first; ties keep the given order. All weights 0 → every total 0. */ export function rankOptions(model: DecisionModel, weights: readonly number[]): Ranked[] { const sum = weights.reduce((total, weight) => total + Math.max(0, weight), 0); return model.options .map((option, index) => ({ index, total: sum === 0 ? 0 : option.scores.reduce((total, score, criterion) => total + Math.max(0, weights[criterion] ?? 0) * (score ?? 0), 0) / sum, })) .sort((a, b) => b.total - a.total || a.index - b.index); } /** How the leader stands: ahead by `margin` (on the score scale), tied, or alone. */ export function leaderMargin(ranked: readonly Ranked[]): { margin: number; tied: number[] } | null { if (ranked.length === 0) return null; const top = ranked[0].total; // Totals equal to two decimals are a tie: a difference the matrix can't show isn't a win. const tied = ranked.slice(1).filter((entry) => round(entry.total) === round(top)).map((entry) => entry.index); return { margin: ranked.length > 1 ? top - ranked[1].total : 0, tied }; } /** The ± step of the weight controls: 1 for whole weights up to 10, 5 or 10 for percent-like ones, 0.05 for fractions. */ export function weightStep(weights: readonly number[]): number { const top = Math.max(0, ...weights); if (weights.every(Number.isInteger)) return top <= 10 ? 1 : top <= 50 ? 5 : 10; return top <= 1 ? 0.05 : 0.5; } /** The largest weight the controls allow: room to double the heaviest given weight, at least ten steps. */ export function weightMax(weights: readonly number[]): number { const step = weightStep(weights); return Math.max(step * 10, round(Math.max(0, ...weights) * 2, 4)); } /** A weight moved by `steps` steps, kept on the step grid within [0, max]. */ export function nudgeWeight(weight: number, steps: number, step: number, max: number): number { return round(Math.min(max, Math.max(0, Math.round(weight / step + steps) * step)), 4); } /** * What "Go with