@cspeach/cli 1.1.29 → 1.1.30

package/dist/register/status-file/register-model.js

@@ -0,0 +1,307 @@
+// @ts-nocheck
+// GENERATED COPY — do not edit here. Edit viewer/src/lib/register-model.js,
+// then run `npx tsx scripts/sync-status-file.ts` (prebuild runs it too).
+// src/register/__tests__/status-file-pin.test.ts fails when this copy drifts.
+/**
+ * What a manager reads, worked out from the register.
+ *
+ * Pure: a Register in, plain data out. No DOM and no clock — `now` is handed
+ * in — so the page, the status file and the tests all get the same answer.
+ *
+ * "Proven" means the system said so: verified (had findings, a later
+ * measurement has none) or clean (measured, never had any). A developer's
+ * "fixed" is a claim and is never counted here.
+ */
+import { activeOf, provenOf, settledOf } from '@cspeach/register-core';
+/**
+ * The three counts every surface divides by are defined once, in register-core,
+ * where the terminal reads them too. They are passed on from here so that
+ * register-parts.js — which draws the lane table for both the page and the
+ * status file — takes its numbers from the model, like everything else it draws.
+ */
+export { activeOf, provenOf, settledOf };
+/** Worst first: the order cells are banded in a block and listed in a legend. */
+export const STATE_ORDER = ['regressed', 'did-not-hold', 'untouched', 'decided', 'working', 'claimed', 'verified', 'clean', 'retired'];
+export const STATE_LABEL = {
+    regressed: 'Regressed',
+    'did-not-hold': 'Did not hold',
+    untouched: 'Untouched',
+    decided: 'Decided',
+    working: 'Working',
+    claimed: 'Claimed fixed',
+    verified: 'Verified',
+    clean: 'Clean',
+    retired: 'Retired',
+};
+/**
+ * Objects carrying a state this build has no word for. Data written by a newer
+ * CSPeach, or hand-edited: the map already draws them in the tenth colour, and
+ * the legend has to name that colour or the reader is left with a mark nobody
+ * accounts for.
+ */
+export const unknownStateCount = (register) => register.objects.filter((o) => !Object.hasOwn(STATE_LABEL, o.state)).length;
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const two = (n) => String(n).padStart(2, '0');
+export function formatWhen(iso) {
+    const t = iso ? new Date(iso) : null;
+    if (!t || Number.isNaN(t.getTime()))
+        return 'never';
+    return `${t.getUTCDate()} ${MONTHS[t.getUTCMonth()]} ${t.getUTCFullYear()} ${two(t.getUTCHours())}:${two(t.getUTCMinutes())} UTC`;
+}
+const plural = (n, one, many) => `${n.toLocaleString('en-US')} ${n === 1 ? one : many}`;
+/**
+ * Proven, but one step removed from the system.
+ *
+ * A file export is somebody's choice of what to put in a file, with which
+ * scope, at which moment. It can prove an object — a team with nobody connected
+ * to SAP works that way for weeks — but it is not the same thing as a run of
+ * the system, and every place that shows such a proof says which it was. One
+ * phrase, defined once, because it is printed in five of them.
+ */
+export const FROM_FILE = 'measured from a file';
+/**
+ * Weaker still: the file never mentioned the object, and the person who
+ * imported it told CSPeach to read that silence as clean. Nothing looked at the
+ * object at all — so where a colour rests on that, it says this instead of
+ * `FROM_FILE`, which would claim a measurement that never happened.
+ */
+export const NOT_MENTIONED = 'not mentioned in a file';
+/**
+ * The same silence, from a live check run: the run finished and never reported
+ * the object. There is no file, so `NOT_MENTIONED` would be the page describing
+ * something that did not happen — and a manager who went looking for the export
+ * would find none. Which of the two is said follows the BASIS that drove the
+ * state, never the shape of the row.
+ */
+export const NOT_REPORTED = 'not reported by the check run';
+/** "A", "A and B", "A, B and C" — how a person would say a list out loud. */
+const andList = (names) => (names.length < 3 ? names.join(' and ') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
+/** As many names as a person reads before they stop reading names. */
+const LIST_CAP = 12;
+const count = (value) => value.toLocaleString('en-US');
+/**
+ * How a cut list ends.
+ *
+ * Three endings, because a reader sent to the wrong place looks for something
+ * that is not drawn. Objects are cells on the map, so on the PAGE the rest of
+ * them are one click away. In the status FILE that map is a picture with no
+ * script behind it, so the same list points at the object list the file
+ * carries further down. And a list of something that is on neither — a pair of
+ * lanes, an object out of scope — says only how many it left out.
+ */
+const seeMap = (more) => `and ${count(more)} more — see the map`;
+const seeObjectList = (more) => `and ${count(more)} more — see the object list below`;
+const justHowMany = (more) => `and ${count(more)} more`;
+/**
+ * A list, and an honest count of what is not on it.
+ *
+ * A new ATC variant can regress three thousand objects in one run. Joining
+ * every name would put a 60 KB paragraph on the page on the day a manager most
+ * needs to read it — and it would still not be a list anybody could use. Twelve
+ * names, then the number, then where the rest of them are.
+ *
+ * `tail` writes that last part, and there is no default: a new cut list has to
+ * say where its own reader should look. `more` overrides what is counted, for
+ * a list whose items and whose problem are not the same thing.
+ *
+ * Only the DETAIL is cut. The `keys` beside it stay complete: they are data a
+ * map or an export reads, not something a person is looking at.
+ */
+function upTo(parts, { tail, cap = LIST_CAP, sep = ', ', more } = {}) {
+    if (parts.length <= cap)
+        return parts.join(sep);
+    return [...parts.slice(0, cap), tail(more ?? parts.length - cap)].join(sep);
+}
+/**
+ * One object can be wrong in more than one way — regressed AND disputed is a
+ * normal pairing. Counting the ways would tell the manager four things need
+ * attention when three objects do, so this counts objects.
+ */
+function attentionKeys(register) {
+    const keys = new Set();
+    for (const o of register.objects) {
+        if (o.state === 'regressed' || o.state === 'did-not-hold' || o.decision?.conflict)
+            keys.add(o.key);
+    }
+    return keys;
+}
+export function summarize(register, { unreadable = 0 } = {}) {
+    const { totals } = register;
+    const proven = provenOf(totals.byState);
+    // Floor, never round: 7,997 of 8,000 is not 100% proven, and a manager who
+    // reads 100% stops looking. Only every last object earns the round number.
+    const provenPct = totals.active ? Math.floor((proven / totals.active) * 100) : 0;
+    const needAttention = attentionKeys(register).size;
+    const lastMeasured = register.lastMeasuredAt ? `last measured ${formatWhen(register.lastMeasuredAt)}` : 'never measured';
+    // A project where every object was retired has nothing left to prove, and
+    // "0% proven" would read as a team that proved nothing. An empty project
+    // keeps the percentage: its map already says there is nothing in scope yet.
+    const provenPhrase = totals.objects > 0 && totals.active === 0 ? 'nothing left to prove' : `${provenPct}% proven`;
+    // A proof read out of a file is still a proof, and it is not the same thing
+    // as a run of the system. The one line a manager reads says how much of what
+    // it just called proven came that way, right beside the word.
+    const fromFile = (totals.fromFile?.verified ?? 0) + (totals.fromFile?.clean ?? 0);
+    const fromFilePhrase = fromFile > 0 ? ` · ${count(fromFile)} of them ${FROM_FILE}` : '';
+    // A folder from an older build carries no `undecided`; work it out the same
+    // way register-core does, so the line never prints a blank.
+    const decided = totals.decided ?? 0;
+    const undecided = Number.isFinite(totals.undecided) ? totals.undecided : Math.max(0, totals.objects - decided);
+    return {
+        objects: totals.objects, active: totals.active, proven, provenPct, decided: totals.decided, undecided, needAttention,
+        lastMeasured, unreadable, fromFile,
+        line: `${plural(totals.objects, 'object', 'objects')} · ${provenPhrase}${fromFilePhrase} · ${count(decided)} decided, ${count(undecided)} undecided · ${plural(needAttention, 'needs attention', 'need attention')} · ${lastMeasured}`,
+    };
+}
+const DAY_MS = 86_400_000;
+/**
+ * `surface` is which of the two things these words will be read on. It changes
+ * one mark: where a cut list of OBJECTS sends the reader. On the page that is
+ * the map, where a cell opens. In the status file the map is a picture, so it
+ * is the object list the file carries instead.
+ */
+export function needsYou(register, { now, unreadable = 0, quietDays = 6, surface = 'page' } = {}) {
+    const items = [];
+    const inState = (state) => register.objects.filter((o) => o.state === state);
+    // The four lists below name objects, and an object is a cell. Everything
+    // else here names something the map does not draw.
+    const onMap = surface === 'file' ? seeObjectList : seeMap;
+    const regressed = inState('regressed');
+    if (regressed.length) {
+        items.push({ kind: 'regressed', title: `${plural(regressed.length, 'object has', 'objects have')} more findings than before`,
+            detail: upTo(regressed.map((o) => o.name), { tail: onMap }), keys: regressed.map((o) => o.key) });
+    }
+    const didNotHold = inState('did-not-hold');
+    if (didNotHold.length) {
+        // Objects, not fixes. One object can carry three failed fixes, and "3 fixes
+        // did not hold" sends a lead looking for three things to put right.
+        //
+        // Every writer who claimed a fix here, not just the first. The register
+        // carries no per-rule open counts, so the model cannot tell whose fix
+        // failed — naming one person would put the blame on a guess.
+        items.push({ kind: 'did-not-hold', title: `${plural(didNotHold.length, 'object has', 'objects have')} a fix that did not hold`,
+            detail: upTo(didNotHold.map((o) => {
+                const by = [...new Set(o.fixes.filter((f) => f.status === 'fixed').map((f) => f.by))];
+                return `${o.name} (fixed by ${by.length ? andList(by) : 'unknown'})`;
+            }), { tail: onMap }),
+            keys: didNotHold.map((o) => o.key) });
+    }
+    const conflicts = register.objects.filter((o) => o.decision?.conflict);
+    if (conflicts.length) {
+        items.push({ kind: 'conflict', title: `${plural(conflicts.length, 'decision needs', 'decisions need')} the lead to rule`,
+            detail: upTo(conflicts.map((o) => `${o.name} — ${Object.entries(o.decision.conflict).map(([w, c]) => `${w}: ${c}`).join(', ')}`), { tail: onMap, sep: '; ' }),
+            keys: conflicts.map((o) => o.key) });
+    }
+    // An accepted exception is work nobody has to do — on a reason somebody gave.
+    // One with no reason (an older record, a hand-written file) is a decision the
+    // lead cannot defend yet.
+    const noReason = register.objects.filter((o) => o.decision?.classification === 'keep' && o.decision?.exception === true && !o.decision?.reason);
+    if (noReason.length) {
+        items.push({ kind: 'exception-no-reason', title: `${plural(noReason.length, 'accepted exception has', 'accepted exceptions have')} no reason`,
+            detail: upTo(noReason.map((o) => o.name), { tail: onMap }), keys: noReason.map((o) => o.key) });
+    }
+    const unowned = register.objects.filter((o) => o.lane === null);
+    if (unowned.length) {
+        const packages = [...new Set(unowned.map((o) => o.package))].sort();
+        items.push({ kind: 'unowned', title: `${plural(unowned.length, 'object has', 'objects have')} no owner`,
+            detail: `Packages: ${upTo(packages, { tail: onMap })}`, keys: unowned.map((o) => o.key) });
+    }
+    const overlap = register.objects.filter((o) => o.laneOverlap.length > 0);
+    if (overlap.length) {
+        // Three lanes can claim one object, and "two lanes" would then be wrong.
+        // A pair of lanes is not on the map either — no cell says "fi + sd" — so a
+        // cut list of pairs says only how many it left out.
+        items.push({ kind: 'overlap', title: `${plural(overlap.length, 'object is', 'objects are')} claimed by more than one lane`,
+            detail: upTo([...new Set(overlap.map((o) => o.laneOverlap.join(' + ')))].sort(), { tail: justHowMany, sep: '; ' }), keys: overlap.map((o) => o.key) });
+    }
+    // A lane that has finished its work stops writing records, and that is the
+    // point — it is not quiet, it is done. Only a lane with work still open can
+    // be waiting for someone.
+    const nowMs = Date.parse(now);
+    for (const lane of register.lanes) {
+        if (!lane.objects || !lane.lastRecordAt || !Number.isFinite(nowMs))
+            continue;
+        if (lane.objects - settledOf(lane.byState) <= 0)
+            continue;
+        const days = Math.floor((nowMs - Date.parse(lane.lastRecordAt)) / DAY_MS);
+        if (days >= quietDays) {
+            items.push({ kind: 'quiet-lane', title: `${lane.owner} (${lane.id}): no records for ${plural(days, 'day', 'days')}`,
+                detail: `Last record ${formatWhen(lane.lastRecordAt)}`, keys: [] });
+        }
+    }
+    if (register.unknownKeys.length) {
+        // These objects are on no map: being out of scope is the whole of what is
+        // wrong with them. So the tail says what the list leaves out rather than
+        // where to look, and it counts ROWS — what somebody actually recorded.
+        // Neither cap is the size of the problem: register-core stops collecting
+        // keys at 50, and twelve of those are printed.
+        const shown = Math.min(register.unknownKeys.length, LIST_CAP);
+        items.push({ kind: 'unknown-objects', title: `${plural(register.skipped.rowsNotInBaseline, 'row names', 'rows name')} an object that is not in scope`,
+            detail: upTo(register.unknownKeys, {
+                more: register.skipped.rowsNotInBaseline - shown,
+                tail: (more) => (more === 1
+                    ? 'and 1 more row names an object that is not in scope'
+                    : `${justHowMany(more)} rows name objects that are not in scope`),
+            }),
+            keys: [] });
+    }
+    if (unreadable) {
+        items.push({ kind: 'unreadable', title: `${plural(unreadable, 'file', 'files')} could not be read yet`,
+            detail: 'Usually a file that is still syncing. Reload in a minute.', keys: [] });
+    }
+    return items;
+}
+export function packageBlocks(register) {
+    const rank = Object.fromEntries(STATE_ORDER.map((s, i) => [s, i]));
+    const byPackage = new Map();
+    for (const o of register.objects) {
+        if (!byPackage.has(o.package))
+            byPackage.set(o.package, []);
+        byPackage.get(o.package).push(o);
+    }
+    return [...byPackage.entries()]
+        .map(([pkg, objects]) => {
+        const byState = Object.fromEntries(STATE_ORDER.map((s) => [s, 0]));
+        for (const o of objects)
+            byState[o.state] += 1;
+        return {
+            package: pkg,
+            // 'en' on every comparison: the order of a map must not depend on the
+            // laptop's locale, or two people looking at one folder see the cells in
+            // two different places.
+            objects: objects.slice().sort((a, b) => rank[a.state] - rank[b.state] || a.name.localeCompare(b.name, 'en')),
+            byState,
+        };
+    })
+        .sort((a, b) => b.objects.length - a.objects.length || a.package.localeCompare(b.package, 'en'));
+}
+/**
+ * Active objects nobody has measured. Their colour rests on what people said,
+ * and the page says so out loud: "not measured" is a state of knowledge, not a
+ * blank. A retired object is not counted — there is nothing left to prove.
+ */
+export const notMeasuredCount = (register) => register.objects.filter((o) => o.state !== 'retired' && (o.lastMeasuredAt ?? null) === null).length;
+/**
+ * One object's measurements, newest first: when, by whom, how many open, and
+ * whether the numbers came from a system check or from a file somebody read in.
+ * `more` is how many older ones the cap left out.
+ *
+ * BOTH bases are here, the counted and the uncounted. A file export of an
+ * object the system has already measured moves nothing — live evidence outranks
+ * file evidence, per object — but hiding it would leave a manager wondering
+ * where the run they were told about went. It is shown, and it is labelled.
+ */
+export function measurementHistory(o, runs, { cap = 8 } = {}) {
+    const all = (o.measurements ?? []).map((m) => ({ m, info: runs?.[m.run] })).filter((x) => x.info).reverse();
+    return {
+        rows: all.slice(0, cap).map(({ m, info }) => ({
+            at: info.at, by: info.by, open: m.open, fromFile: info.basis === 'file',
+            variant: info.atcVariant ?? '', scope: info.scope ?? '',
+            // Straight off the register, never worked out again here: whether this
+            // run moved the object's colour is register-core's answer, and a second
+            // copy of that rule in the view is a second place for it to go wrong.
+            counted: m.counted === true,
+            ...(m.evidence ? { evidence: m.evidence } : {}),
+        })),
+        more: Math.max(0, all.length - cap),
+    };
+}