plumbbob 0.12.1 → 0.13.1

package/dist/lib/orient.js

@@ -4,6 +4,7 @@
 // contents (no fs), and a malformed document degrades to fewer fields rather
 // than throwing.
 import { parseStepSeam, scopeDrift } from "./intent.js";
+import { expandStepList, formatStepList, hasStep, normalizeStepList, parseStepList, readBuildArgs, } from "./steplist.js";
 /**
  * The lines of a named `## Section`, from its heading to the next `## ` (or
  * EOF), with the offset of the first line so a caller can name an absolute
@@ -74,33 +75,35 @@ export function parseSteps(intent) {
         return { n: s.n, done: s.done, title: s.title, planned: /done when/i.test(block), doneWhen, model, line: offset + s.idx + 1 };
     });
 }
-// A build-order line: step numbers and commas, nothing else. A trailing comma
-// is tolerated, since a hand edit leaves one behind.
-const BUILD_ORDER_LINE = /^\d+(?:\s*,\s*\d+)*\s*,?$/;
+// A build-order line: step numbers and spans (`2-4`) joined by commas, with or
+// without a space after each, and nothing else. A trailing comma is tolerated,
+// since a hand edit leaves one behind.
+const BUILD_ORDER_LINE = /^\d+(?:-\d+)?(?:\s*,\s*\d+(?:-\d+)?)*\s*,?$/;
 /**
  * The build order declared under `## Build order`: the step numbers on the
- * first line that is nothing but numbers and commas, in the sequence written.
+ * first line that is nothing but numbers, spans, and commas, in the sequence
+ * written, each span spelled out in place (`1, 6, 2-4` reads 1, 6, 2, 3, 4).
  *
  * The line is the plan's own statement of what to build next once the
  * numbering stops carrying it (a refined plan appends a step 7 that has to
  * land before step 5), and `plumbbob order` is the verb that writes it. The
  * template's guidance, a comment, and an absent section all read as `[]`,
- * which every picker takes to mean document order. Numbers come back
- * verbatim, repeats and unknowns included: `orderSteps` does the cleaning, and
- * `recover` wants the raw read to say which number the plan lacks.
+ * which every picker takes to mean document order, and so does a line holding
+ * a span that runs backward. Numbers come back verbatim, repeats and unknowns
+ * included: `orderSteps` does the cleaning, and `recover` wants the raw read to
+ * say which number the plan lacks. A span stops at the first number past the
+ * plan, which it keeps for `recover` to name.
  */
 export function parseBuildOrder(intent) {
     const line = sectionLines(intent, '## Build order')
         .lines.map((l) => l.trim())
         .find((l) => BUILD_ORDER_LINE.test(l));
-    if (line === undefined) {
+    const list = line === undefined ? null : parseStepList(line.replace(/\s+/g, '').replace(/,$/, ''));
+    if (list === null) {
         return [];
     }
-    return line
-        .split(',')
-        .map((n) => n.trim())
-        .filter((n) => n.length > 0)
-        .map(Number);
+    const planned = new Set(parseSteps(intent).map((s) => s.n));
+    return expandStepList(list, (n) => planned.has(n));
 }
 /**
  * The steps in build order: the numbers `order` lists first, in that sequence,
@@ -234,6 +237,246 @@ export function clearBuildOrder(intent) {
     }
     return lines.join('\n');
 }
+// A range's opener: the item's number, the command in backticks, a comma, and
+// the stop's text from `**stop:**` to the end of the line.
+const RANGE_OPENER = /^`([^`]*)`\s*,?\s*\*\*stop:\*\*\s*(.*)$/i;
+// A `<...>` fill-in the template ships, still waiting for its words.
+const FILL_IN = /<[^<>]+>/;
+/**
+ * Parse the ranges under `## Build ranges`: one numbered item per range, the
+ * command in backticks, then `**stop:**` and the stop's text, then an optional
+ * `- model:` sub-line.
+ *
+ * The command's steps go through the turn hook's own reader, so the card can
+ * never suggest a command the hook reads another way. A paragraph before the
+ * list and any sub-line but the model are the reader's. An item still holding
+ * a `<...>` fill-in in its command or stop is scaffold, the template's
+ * placeholder waiting for words, and reads as neither a range nor a report; any
+ * other item that fails the grammar is reported by its number and never
+ * thrown. A plan without the section, a build's record from before ranges
+ * existed under another heading, and a section holding only the placeholder
+ * all read as no ranges.
+ */
+export function parseBuildRanges(intent) {
+    const { offset, lines } = sectionLines(intent, '## Build ranges');
+    const ranges = [];
+    const malformed = [];
+    const openers = lines.flatMap((l, idx) => {
+        const m = /^(\d+)\.\s+(.*)$/.exec(l);
+        return m === null ? [] : [{ item: Number(m[1]), text: m[2] ?? '', idx }];
+    });
+    openers.forEach((o, i) => {
+        const block = lines.slice(o.idx + 1, openers[i + 1]?.idx ?? lines.length);
+        const text = [o.text, ...wrappedLines(block)].join(' ').trim();
+        if (FILL_IN.test(text)) {
+            return;
+        }
+        const range = readRange(o.item, text, block, offset + o.idx + 1);
+        if (range === null) {
+            malformed.push(o.item);
+        }
+        else {
+            ranges.push(range);
+        }
+    });
+    return { ranges, malformed };
+}
+/**
+ * The lines an item's opener wraps onto: each line after it, trimmed, up to the
+ * first blank line, sub-line, or heading.
+ */
+function wrappedLines(block) {
+    const end = block.findIndex((l) => l.trim() === '' || /^\s*[-*+]\s/.test(l) || l.startsWith('#'));
+    return block.slice(0, end === -1 ? block.length : end).map((l) => l.trim());
+}
+/**
+ * One item read as a range, or null when it is not one: a command other than
+ * `/plumbbob:build` with steps and nothing after them, a bare command naming
+ * more than one step, or a stop with no text.
+ */
+function readRange(item, text, block, line) {
+    const m = RANGE_OPENER.exec(text);
+    const args = /^\/plumbbob:build\s+([\d,\s-]+)$/.exec((m?.[1] ?? '').trim())?.[1];
+    const stop = (m?.[2] ?? '').trim();
+    if (args === undefined || stop === '') {
+        return null;
+    }
+    const read = readBuildArgs(args);
+    const single = read.steps?.length === 1 && read.steps[0]?.from === read.steps[0]?.to;
+    if (read.steps === null || (!read.range && !single)) {
+        return null;
+    }
+    const model = /^\s*-\s*model:\s*(.+)$/im.exec(block.join('\n'))?.[1]?.trim() ?? null;
+    return {
+        item,
+        command: (m?.[1] ?? '').trim(),
+        steps: read.steps,
+        bare: !read.range,
+        stop,
+        model: model === null || FILL_IN.test(model) ? null : model,
+        line,
+    };
+}
+/**
+ * Where the build stands in its ranges, read from `step`: the range holding
+ * it, the command that runs what is left of that range, the range its landing
+ * completed, and every range the plan has outgrown.
+ *
+ * Nothing is stored. A range is landed once every step it names is done, and
+ * what is left of it is its undone steps from `step` on, in build order, so a
+ * step pause names what is left once the step in flight lands. A landing
+ * range down to one step writes it `9-9`, which lands it, where a bare range
+ * stays bare. `ordered` is the plan's steps in build order, landed ones
+ * included. With no range that parses, no step sits outside one, so a fresh
+ * build's placeholder flags nothing.
+ */
+export function rangeStanding(plan, ordered, step) {
+    const drift = rangeDrift(plan, ordered);
+    const count = plan.ranges.length + plan.malformed.length;
+    const at = ordered.findIndex((s) => s.n === step);
+    const holding = plan.ranges.find((r) => step !== null && hasStep(r.steps, step));
+    if (holding === undefined) {
+        const outside = step !== null && plan.ranges.length > 0 && ordered[at]?.done === false;
+        return { count, holding: null, command: null, flag: outside ? noRangeWords([step]) : null, completed: null, drift };
+    }
+    const flag = drift.find((d) => d.item === holding.item && d.kind !== 'malformed')?.words ?? null;
+    const left = at === -1 ? [] : ordered.slice(at).filter((s) => !s.done && hasStep(holding.steps, s.n));
+    return {
+        count,
+        holding,
+        command: flag === null && left.length > 0 ? `/plumbbob:build ${leftExpression(holding, left)}` : null,
+        flag,
+        completed: ordered[at]?.done === true && rangeLanded(holding, ordered) ? holding : null,
+        drift,
+    };
+}
+/** Whether a range has landed: the plan holds a step it names, and every one it holds is done. */
+function rangeLanded(range, ordered) {
+    const held = ordered.filter((s) => hasStep(range.steps, s.n));
+    return held.length > 0 && held.every((s) => s.done);
+}
+/**
+ * The ranges block the dashboard renders, and the move it suggests: the range
+ * holding the next undone step and the command that runs what is left of it.
+ *
+ * Null for a plan without ranges, so the block vanishes. The move is null when
+ * the next step sits in no range, its range is flagged, or the step is still
+ * unplanned, which leaves the dashboard's own step move in charge.
+ */
+function rangesView(intent, ordered, next) {
+    const plan = parseBuildRanges(intent);
+    const standing = rangeStanding(plan, ordered, next?.n ?? null);
+    if (standing.count === 0) {
+        return { view: null, move: null };
+    }
+    const own = (item) => standing.drift.filter((d) => d.item === item && d.kind !== 'malformed');
+    const rows = plan.ranges.map((range) => ({
+        range,
+        landed: rangeLanded(range, ordered),
+        next: range === standing.holding,
+        drift: own(range.item).map((d) => d.words),
+    }));
+    const view = { count: standing.count, rows, plan: standing.drift.filter((d) => d.item === null || d.kind === 'malformed').map((d) => d.words) };
+    const { holding, command } = standing;
+    const move = holding === null || command === null || next?.planned !== true ? null : `build range ${holding.item} of ${standing.count} — \`${command}\``;
+    return { view, move };
+}
+/**
+ * What is left of a range as the steps of a command: a landing range's last
+ * step written `9-9` so the command lands it, else the steps in build order
+ * with each climbing run folded to a span, a bare range's lone number included.
+ */
+function leftExpression(range, left) {
+    const ns = left.map((s) => s.n);
+    return !range.bare && ns.length === 1 ? `${ns[0]}-${ns[0]}` : formatStepList(ns);
+}
+/** The words for steps no range names: `no range names step 12`, or `steps 11, 12`. */
+function noRangeWords(steps) {
+    return `no range names ${stepPhrase(steps.map(String)).words}`;
+}
+/**
+ * Every report on the ranges, in the order the dashboard lists them: each
+ * range's own (a step the plan lacks, a step another range also names, a step
+ * from outside it the build order puts among its own), then the undone steps
+ * no range names, then the items that do not parse.
+ *
+ * A step the build order puts inside a range, and a step no range names,
+ * count only while undone, since a landed step cannot cut a run short. The
+ * coverage check runs only once a real range parses.
+ */
+function rangeDrift(plan, ordered) {
+    const own = plan.ranges.flatMap((r) => [
+        ...missingDrift(r, ordered),
+        ...sharedDrift(r, plan.ranges, ordered),
+        ...insideDrift(r, ordered),
+    ]);
+    const outside = ordered.filter((s) => !s.done && !plan.ranges.some((r) => hasStep(r.steps, s.n))).map((s) => s.n);
+    const uncovered = plan.ranges.length > 0 && outside.length > 0 ? [{ kind: 'uncovered', item: null, words: noRangeWords(outside) }] : [];
+    const malformed = plan.malformed.map((item) => ({ kind: 'malformed', item, words: `item ${item} under Build ranges does not parse` }));
+    return [...own, ...uncovered, ...malformed];
+}
+/**
+ * A range naming steps the plan lacks, reported as the spans it names past
+ * the plan's steps, so a span of any width is read without being counted out.
+ */
+function missingDrift(range, ordered) {
+    const held = ordered.map((s) => s.n).sort((a, b) => a - b);
+    const gaps = [];
+    for (const span of range.steps) {
+        let from = span.from;
+        for (const n of held.filter((h) => h >= span.from && h <= span.to)) {
+            if (n > from) {
+                gaps.push({ from, to: n - 1 });
+            }
+            from = Math.max(from, n + 1);
+        }
+        if (from <= span.to) {
+            gaps.push({ from, to: span.to });
+        }
+    }
+    if (gaps.length === 0) {
+        return [];
+    }
+    const { words, be } = stepPhrase(normalizeStepList(gaps).split(','));
+    return [{ kind: 'missing', item: range.item, words: `${words} ${be} not in the plan` }];
+}
+/** A range sharing steps with another range, one report for each other range. */
+function sharedDrift(range, ranges, ordered) {
+    const mine = ordered.filter((s) => hasStep(range.steps, s.n));
+    return ranges.flatMap((other) => {
+        const both = other === range ? [] : mine.filter((s) => hasStep(other.steps, s.n)).map((s) => String(s.n));
+        if (both.length === 0) {
+            return [];
+        }
+        const { words, be } = stepPhrase(both);
+        return [{ kind: 'shared', item: range.item, words: `${words} ${be} also in range ${other.item}` }];
+    });
+}
+/**
+ * A range the build order cuts short: an undone step it does not name, placed
+ * between two of its own, where a run of the range halts.
+ *
+ * An outside step ahead of the range's first step builds first and cuts
+ * nothing, and the card names its range before this one.
+ */
+function insideDrift(range, ordered) {
+    const first = ordered.findIndex((s) => hasStep(range.steps, s.n));
+    const last = ordered.findLastIndex((s) => hasStep(range.steps, s.n));
+    const inside = first === -1 ? [] : ordered.slice(first + 1, last).filter((s) => !s.done && !hasStep(range.steps, s.n));
+    if (inside.length === 0) {
+        return [];
+    }
+    const words = stepPhrase(inside.map((s) => String(s.n))).words;
+    return [{ kind: 'inside', item: range.item, words: `the build order puts ${words} inside it` }];
+}
+/**
+ * Steps as a phrase, with the verb that agrees: `step 12` and `is`, or
+ * `steps 11, 12` and `are`. Each item is a number or a span as it is typed.
+ */
+function stepPhrase(items) {
+    const one = items.length === 1 && /^\d+$/.test(items[0] ?? '');
+    return { words: `${one ? 'step' : 'steps'} ${items.join(', ')}`, be: one ? 'is' : 'are' };
+}
 /**
  * Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section.
  *
@@ -365,27 +608,29 @@ export function lastLedgerSha(checkpoints) {
     return last;
 }
 /**
- * The step number an explicit skill invocation asks for, out of the raw
- * argument text `status --invoked` receives.
+ * The steps an explicit skill invocation asks for, out of the raw argument
+ * text `status --invoked` receives, read the way the turn hook reads a typed
+ * range.
  *
- * The first whitespace-separated token shaped like `22` or `22-24` names the
- * step (a range asks to start at its first number); flags such as `--auto` and
- * anything else parse to null, meaning "no explicit ask", which leaves the
- * dashboard's own suggestion in charge. Null in means null out, so a host that
- * never substitutes the invocation degrades to today's rendering.
+ * A step number names one step, and a range or a list names the steps it
+ * holds (`orient` starts it at the first undone one in build order); `--auto`
+ * alone, a range that does not parse, and free text parse to null, meaning "no
+ * explicit ask", which leaves the dashboard's own suggestion in charge. Null in
+ * means null out, so a host that never substitutes the invocation degrades to
+ * today's rendering.
  */
 export function parseRequestedStep(raw) {
-    if (raw === null) {
-        return null;
-    }
-    for (const token of raw.trim().split(/\s+/)) {
-        const m = /^(\d+)(?:-\d+)?$/.exec(token);
-        if (m) {
-            const n = Number(m[1]);
-            return n >= 1 ? n : null;
-        }
-    }
-    return null;
+    return raw === null ? null : readBuildArgs(raw.trim()).steps;
+}
+/**
+ * The step a requested list starts at: its first undone step in build order,
+ * however the list was written; its first step in build order when every one
+ * has landed; or its first number written when the plan holds none of them, so
+ * the dashboard reports that number missing. Null for an empty list.
+ */
+export function rangeStart(ordered, list) {
+    const named = ordered.filter((s) => hasStep(list, s.n));
+    return (named.find((s) => !s.done) ?? named[0])?.n ?? list[0]?.from ?? null;
 }
 /**
  * The single primary next move the dashboard suggests.
@@ -454,15 +699,22 @@ export function orient(input) {
     const order = parseBuildOrder(input.intent);
     const ordered = orderSteps(steps, order);
     const parks = parseParkTotals(input.buildLog);
+    // The step an explicit ask points at: the number typed, or where a typed
+    // range starts in build order.
+    const requested = input.requested === null ? null : rangeStart(ordered, input.requested);
     // The target the dashboard details: the explicitly requested step when it
     // exists in the plan, else the next undone. A requested number that names no
     // planned step carries nothing here; the next-move line reports the mismatch
     // while the rest of the dashboard renders as usual.
-    const requestedStep = input.requested === null ? undefined : steps.find((s) => s.n === input.requested);
+    const requestedStep = requested === null ? undefined : steps.find((s) => s.n === requested);
     const nextUndone = ordered.find((s) => !s.done);
     const target = requestedStep ?? nextUndone;
     const seamParse = target === undefined ? null : parseStepSeam(input.intent, target.n);
     const phase = input.spiking ? 'SPIKE' : input.inFlight !== null ? 'BUILD' : 'DESIGN';
+    // At the boundary with nothing asked for, the move names the range holding
+    // the next step; a spike, a step in flight, or a request keeps its own.
+    const ranges = rangesView(input.intent, ordered, nextUndone);
+    const atBoundary = !input.spiking && input.inFlight === null && requested === null;
     return {
         title: parseTitle(input.intent),
         phase,
@@ -471,9 +723,10 @@ export function orient(input) {
         parked: parks.open,
         parkedTotal: parks.total,
         openQuestions: parseOpenQuestions(input.intent),
-        next: nextMove(input.spiking, ordered, input.inFlight, parks.open, input.requested),
+        next: (atBoundary ? ranges.move : null) ?? nextMove(input.spiking, ordered, input.inFlight, parks.open, requested),
         nextUndone: nextUndone?.n ?? null,
         buildOrder: remainingOrder(steps, order, null),
+        ranges: ranges.view,
         requested: requestedStep?.n ?? null,
         nextDoneWhen: target?.doneWhen ?? null,
         nextSeam: seamParse !== null && seamParse.ok ? seamParse.seam : [],
@@ -903,6 +1156,45 @@ export function parseSummary(detail) {
     }
     return { lead, highlights };
 }
+/**
+ * `.plumbbob/detail.md` with a blank line around every heading, and everything
+ * else as written.
+ *
+ * A model copying the detail template can run a heading straight into its body
+ * or its predecessor, and markdownlint's MD022 fails that file wherever
+ * `.plumbbob/` is linted, which turns a downstream checkpoint red. Heading lines
+ * inside a fenced block are content, not headings, so a fence is left whole.
+ * Pure and idempotent: text that already has its blank lines comes back byte for
+ * byte, so a caller can compare the result to the input to learn whether
+ * anything needed fixing.
+ */
+export function normalizeDetailHeadings(detail) {
+    const out = [];
+    let fence = null;
+    let afterHeading = false;
+    for (const line of detail.split('\n')) {
+        if (fence !== null) {
+            const close = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line)?.[1];
+            if (close !== undefined && close.startsWith(fence.char) && close.length >= fence.length) {
+                fence = null;
+            }
+            out.push(line);
+            continue;
+        }
+        const heading = /^ {0,3}#{1,6}(\s|$)/.test(line);
+        const prior = out[out.length - 1];
+        if ((heading || afterHeading) && line.trim() !== '' && prior !== undefined && prior.trim() !== '') {
+            out.push('');
+        }
+        const open = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (open !== undefined) {
+            fence = { char: open.charAt(0), length: open.length };
+        }
+        out.push(line);
+        afterHeading = heading;
+    }
+    return out.join('\n');
+}
 /**
  * The `## <n>` sections of `.plumbbob/detail.md` with their bodies: the full
  * story behind each highlight, in the order the model wrote them. The body is
@@ -985,11 +1277,15 @@ export function formatOrientation(o) {
         return detail.length > 0 ? [head, ...detail].join('\n') : head;
     });
     const stepsBlock = o.steps.length === 0 ? '  (no steps planned yet)' : `  steps  ${doneCount}/${o.steps.length} done\n${stepLines.join('\n')}`;
+    const rangesBlock = o.ranges === null ? [] : [formatRanges(o.ranges), ''];
     const cp = o.lastCheckpoint;
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
     // A neutral reconciliation note, only when there is something to reconcile:
     // commits landed since the last checkpoint that plumbbob's ledger didn't
-    // record. Informational: the human commits freely, so this never gates.
+    // record. A commit a plumbbob verb makes starts the range, and a hand-made
+    // plan commit drops out on its `plumbbob plan` body marker, so the count is
+    // the same one `handoff` folds into its Verdict. Informational: the human
+    // commits freely, so this never gates.
     const receipts = o.outOfBand > 0
         ? [`${o.outOfBand} commit${o.outOfBand === 1 ? '' : 's'} since the last checkpoint landed outside plumbbob's ledger.`]
         : [];
@@ -1001,6 +1297,7 @@ export function formatOrientation(o) {
         '',
         stepsBlock,
         '',
+        ...rangesBlock,
         cpLine,
         ...receipts,
         ...orderRow,
@@ -1009,3 +1306,22 @@ export function formatOrientation(o) {
         `next → ${o.next}`,
     ].join('\n');
 }
+/**
+ * The dashboard's ranges block, in the step list's own grammar: a count, then a
+ * row per range with its command as the plan wrote it and its model, `✓` for
+ * a range landed and `▸` with the `← next` tail for the one holding the next
+ * step. An undone range carries its stop beneath it, since the stops ahead are
+ * what the human steers by, and a landed one folds to its row. A range's drift
+ * rides beneath it, and the plan's own rows close the block.
+ */
+function formatRanges(view) {
+    const landed = view.rows.filter((r) => r.landed).length;
+    const rows = view.rows.flatMap((r) => {
+        const marker = r.landed ? '✓' : r.next ? '▸' : ' ';
+        const model = r.range.model === null ? '' : ` · ${r.range.model}`;
+        const head = `  ${marker} ${r.range.item}  ${r.range.command}${model}${r.next ? '   ← next' : ''}`;
+        const stop = r.landed ? [] : [`        stop: ${r.range.stop}`];
+        return [head, ...stop, ...r.drift.map((words) => `        ⚠ needs a re-cut: ${words}`)];
+    });
+    return [`  ranges  ${landed} of ${view.count} done`, ...rows, ...view.plan.map((words) => `  ⚠ ${words}`)].join('\n');
+}